Worked examples — real plugin source#

What this is: complete, unedited source of shipping Kizen plugins, generated by npx --yes @kizenapps/cli report. The numbered docs teach contracts in isolation; these files show whole plugins that actually build, install, and run. Read them when you want to see how the pieces sit together in a real repo rather than how one method behaves.

Not hand-written. Every .md here is generator output. Don't edit them — fix the plugin (or the generator) and regenerate, or your correction is lost on the next refresh. See Regenerating.

The reports#

Report	Lines	Surfaces it demonstrates
kitchen_sink.md	~5,150	Everything. Actions (writeback, perform-action, relationship-add override, deliberate failure modes), Python automation steps (all 10 `data_type`s, secret + Basic auth, retry/backoff, forced failures), blocks (dashboard, homepage, record, cross-block ping/pong, charts), floating frames (script widget, scoped iframe, iframe bridge), pages, toolbar items, views (form, frameless, summary), data adornments, object settings items, calendar sources, route scripts, and both setup assistants. Four services, one per auth shape.
google_calendar.md	~975	A production integration, narrow and deep: user-level OAuth service, calendar source (`calendars.js` + `events.js`), date and datetime data adornments, and business + user setup assistants driven by async selects (`getFetchUrl.js` + `optionMapper.js`). Also 14 release-note files, showing how versioning accumulates over a real plugin's life.

Kitchen sink is the reference implementation — synthetic, exhaustive, and commented to explain the contract each artifact relies on. Google Calendar is the counterweight: what a plugin looks like when it solves one problem for real customers.

What's in a report#

Four sections, in this order:

Title and description — the plugin's name, version, and marketplace description.
## Configuration (kizen.json) — the plugin manifest.
## File Tree — the repo layout as ASCII.
## Files — one ### \path`` heading per file, then its contents in a fenced block.

Because every file gets its own ### heading with the real repo path, you can grep for a path or a symbol and land in the right artifact.

Reading them efficiently#

These files are big. Two habits help:

Grep, don't read top-to-bottom. From the repo root, grep -n 'showViewInModal' docs/examples/kitchen_sink.md gets you to the call sites; the nearest preceding ### \…`` heading tells you which file you're in.
Start from the file tree. It's ~200 lines near the top of each report and shows the whole artifact layout at a glance. Pick the artifact, then jump to its heading.

If your client can't read the repo off disk, the bundled MCP server does targeted retrieval for you — see mcp-server/.

Regenerating#

Requires @kizenapps/cli — no install needed, npx --yes fetches it — and a local clone of the plugin repo. Run it from inside the plugin directory, writing the output back into this repo — <docs-dir> below is the absolute path to the docs/ directory containing this examples/ folder:

Shell

cd /path/to/plugin-kitchen-sink    && npx --yes @kizenapps/cli report -o <docs-dir>/examples/kitchen_sink.html
cd /path/to/plugin-google-calendar && npx --yes @kizenapps/cli report -o <docs-dir>/examples/google_calendar.html
rm <docs-dir>/examples/*.html

The command also writes an .html sibling next to the .md. Only the .md is committed here — the HTML is a human-oriented viewer, it's large, and it adds nothing an agent can use. Hence the rm.

The output filename is what the MCP server treats as the api_name, so keep the basename equal to the plugin's api_name (kitchen_sink, not kitchen-sink). The server treats every .md in this directory as a report except the names listed in its NON_REPORT_FILES set — which is why this README.md isn't served as a plugin. Add any other prose file you drop here to that set.

Before you add a new report#

A report reproduces plugin source verbatim, and only manifest credentials are masked — see 02-getting-started.md for what the generator does and doesn't redact. Read the diff before you commit a new one, not just the manifest section.

Staleness#

Each report is a snapshot of one version — the heading tells you which (Kitchen Sink v1.0.0, Google Calendar v2.0.1). Plugins keep moving after that. When a report and the live docs disagree about a contract, trust the numbered docs in ../ and check the plugin repo; when a report and your own memory of an API disagree, trust the report, because it compiled.