Authoring a plugin

What it is

An Omniscio plugin adds a panel to the app. The manifest names the plugin, its sidebar icon, the permissions it asks for, the panel entry point and, if it has one, the worker entry point. The panel is ordinary web code; the worker is an ES module the app starts beside it, which the panel calls through a small request table.

The author kit gives you a working starter with both halves wired together, plus the generated lists everything must match: the manifest schema, the permission names (with the wording the consent screen shows), the icon names that actually draw, and the SDK types your editor completes against. Those lists are generated from the app's own sources, so they cannot promise something the app refuses.

Where to find it

• The authoring flow lives in the Omniscio repository, under the plugin kit script folder and the starter template it scaffolds.
• The finished plugin loads through Settings → Plugins → Developer Mode, which is also where its live status, reload button and removal live.
• Finished plugins can later be published to the Marketplace, which is a separate, review-gated step with its own account requirements.

How it behaves

Creating. The create step asks for a plugin id, an output folder, a sidebar icon and any extra permissions. It checks the generated manifest with the app's validator before writing anything, so a refused create leaves nothing on disk. The scaffold contains the manifest, a panel, a worker that answers two example methods, the SDK types, and npm scripts that call the same toolkit.

Building. The build typechecks the plugin, bundles the worker into a single file, copies the panel's static files and bundles its script. A plugin that does not typecheck is refused rather than half-built, and no source maps ship.

Checking the manifest. The validate step runs the same validator the app's loader runs. It also requires an SDK version on any manifest that declares a worker backend, because that field selects the loader — a backend without it could never start. It is deliberately not a copy of the schema: the app's answer is the only answer that matters.

Packaging. The package step runs the plugin's own validate and build, clears the old output so a stale build cannot ship, strips source maps, writes a .amcplugin archive, and verifies the finished archive: the expected top-level entries, every declared entry point present, the version matching the manifest, and no source maps or TypeScript inside. A failed package leaves nothing publishable and names what was wrong.

Inspecting and unpacking. An archive can be read without extracting it — manifest, permissions, file list, signature state, and whether the app would accept the embedded manifest. Unpacking treats the archive as untrusted: it refuses paths that try to escape, absolute and drive-letter paths, symbolic links, duplicate or case-colliding names, oversized archives and entries that inflate past their declared size. It writes into a temporary folder and only moves it into place when every file is safely written, so a refused unpack never damages or half-fills a folder you already had.

Loading it. Developer Mode loads your source folder straight into the running app. The tooling asks the app to load it and the app shows an approval card naming the folder; nothing runs until the person approves. A loaded plugin carries a DEV badge and beats a marketplace or built-in copy with the same id. Developer Mode is the person's switch: turning it off unloads every dev plugin, and the tooling never turns it on by itself.

Signature state. A locally built package carries no signature. The Marketplace signs the package bytes when it is uploaded and stores that signature with its own record, which is why an inspector reports every local package as unsigned.

For agents

The authoring page for a repository checkout is docs/developing/PLUGIN_AUTHORING_GUIDE.md; it gives the exact commands, the expected output of each step, and a refusal table. The toolkit is scripts/plugin-kit/cli.mjs (run it with node from the repository root); the generated reference is under src/plugins/_kit/generated/. The acceptance harness an outside author is measured by is scripts/plugin-kit/fresh-agent-run.mjs, and the rules the kit must keep are in .claude/memory/contracts/plugin-author-kit-contract.md.

Related

• Plugin Developer Mode — the setting that loads an unpacked plugin.
• Plugin Marketplace — publishing, review and install.