@rackbops/ac-plugin-contract 2.0.0-alpha.33

package/AUTHORING.md

@@ -0,0 +1,934 @@
+# Writing an artifact-console plugin
+
+A plugin adds to the console without changing it: a nav **panel**, an Overview **card**, a confirm-gated
+**action**, a scheduled **job**, an HTTP **route**, and a **setting** are all contributed from data + a small
+server module. The host validates the plugin's manifest before it runs any of the plugin's code, loads it at
+startup, and surfaces it at `GET /api/plugins`.
+
+This guide is written against the reference plugin, [`plugins/hello`](../../plugins/hello), which contributes
+**one of each** of the six points (two jobs: the host job `hello.tick` and the agent job `hello.machines`, #51;
+two actions, `hello.ping` and the option-picker example `hello.order`, #463, whose choices come from a second
+route, `GET /toppings`).
+Every **code** snippet below is excerpted from that plugin, trimmed to what its section is about — the §1
+manifest and §2 server snippets show its first action (`hello.ping`) and route (`/ping`), and the option-picker
+part of §2 shows `hello.order` and `GET /toppings` — copy it and change
+the names. (The §1 `package.json` is shown in two blocks — the `acPlugin` manifest, then the surrounding fields
+— with the manifest's arrays on single lines for readability.) The plugin contract itself is specified in
+[`design.md` §4](../plans/v2/design.md).
+
+## 0. Where a plugin lives
+
+A plugin is a directory `plugins/<id>/` — a pnpm workspace member (the `plugins/*` glob in
+`pnpm-workspace.yaml` already covers it, so a new dir needs no workspace edit). The host **auto-discovers** every
+subdirectory of `plugins/` whose `package.json` carries an `acPlugin` block; there is no registration list to
+add yourself to. A directory with no `acPlugin` block is simply not a plugin and is skipped. So the whole job is:
+create `plugins/<id>/`, give its `package.json` an `acPlugin` block and the files it points at, and the host
+finds it.
+
+## 1. The manifest — `package.json` `acPlugin`
+
+The host reads the `acPlugin` block from the plugin's `package.json` and validates it against the generated
+JSON Schema (`packages/contract/schema.json`) **before loading any code**. An invalid manifest is recorded as
+an error and the plugin is skipped — it never runs. The schema is `additionalProperties: false`, so a mistyped
+key is itself a hard validation error, not a silently-ignored field.
+
+```json
+"acPlugin": {
+  "id": "hello",
+  "hostApiVersion": 1,
+  "kind": "in-process",
+  "server": "dist/server.js",
+  "frontend": "dist/ui.js",
+  "contributes": {
+    "panels": [{ "id": "hello-panel", "title": "Hello", "route": "/hello", "export": "HelloPanel" }],
+    "cards": [{ "id": "hello-card", "title": "Hello", "sizes": ["2x1"], "export": "HelloCard" }],
+    "actions": [
+      {
+        "id": "hello.ping",
+        "title": "Ping",
+        "scope": "global",
+        "confirm": true,
+        "fields": [{ "name": "message", "label": "Message", "type": "string" }]
+      }
+    ],
+    "jobs": [
+      { "id": "hello.tick", "schedule": "*/15 * * * *", "timeoutSec": 30, "runOn": "host" },
+      { "id": "hello.machines", "schedule": "17 3 * * *", "timeoutSec": 30, "runOn": "agent" }
+    ],
+    "routes": [{ "method": "GET", "path": "/ping" }],
+    "settings": [{ "key": "greeting", "type": "string", "default": "hello" }],
+    "attention": true
+  }
+}
+```
+
+That `acPlugin` block sits inside an otherwise ordinary `package.json`. The **rest** of the file matters too —
+the workspace ratchet requires a `name`, a `build` script, and an `exports` (or `main`) entry, so a plugin
+missing any of them fails `pnpm run check`. The complete shape (the `acPlugin` block above elided):
+
+```jsonc
+{
+  "name": "@ac/plugin-hello",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": { ".": { "default": "./dist/server.js" } },
+  "acPlugin": { /* the block shown above */ },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.ui.json --noEmit",
+    "build": "tsc && tsc -p tsconfig.ui.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ac/contract": "workspace:*",
+    "@rackbops/ui-react": "^0.2.36",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
+```
+
+`"type": "module"` (the emitted `dist/*.js` are ESM), `"exports"` pointing at the built server, and the shared
+dev deps pinned through the workspace `catalog:` (one version of `typescript`/`vitest`/`@types/node`/`@types/react`
+across the repo — run `pnpm install` after adding them). `@rackbops/ui-react` and `react` are only needed if you
+ship a frontend (§3). If that frontend needs `@types/react-dom` too (a real render test, not just
+`@testing-library/react`), put it on the catalog rather than a bare semver range — pnpm can otherwise link a new
+consumer's `@types/react-dom` to a peer-unqualified store path that doesn't exist, failing with `TS2307` (#205).
+The `scripts` and tsconfig split are explained in §3.
+
+Rules the host enforces, at validation or load time:
+
+- **`id`** must match `/^[a-z][a-z0-9-]*$/` and is **permanent** — it is the plugin's route namespace
+  (`/api/x/<id>/…`), its state key and its log prefix. Renaming it orphans a deployed plugin's stored data, so
+  never rename it. Plugin `id`, panel `id`/`route`, card `id` and action `id` are **globally unique** across all
+  installed plugins. (These, plus `hostApiVersion` equality, are checked by the *validator* before any plugin
+  code loads.) **Collisions are origin-aware** (#451): an installed plugin (one found under the operator's
+  second, agent-writable plugins directory, `AC_INSTALLED_PLUGINS_DIR`) whose `id` or any contributed
+  id/route matches a *bundled* plugin's (one shipped in the image's own `plugins/`) is refused — only the
+  installed plugin errors, naming the bundled owner — and the bundled one keeps running unaffected. This
+  is what stops a third-party package from disabling a bundled plugin (e.g. the auth provider, or `admin`
+  itself) just by declaring its id. Two bundled plugins sharing an id is still a build/CI mistake and both
+  error, the same for two installed plugins with no bundled plugin in the collision.
+- **`hostApiVersion`** must equal the host's `HOST_API_VERSION` (currently `1`); a mismatch is rejected.
+- **`kind: "in-process"`** must declare a `server` entry — the *loader* records an error and skips a plugin that
+  doesn't (the schema itself requires only `id`, `hostApiVersion` and `kind`). `contributes` and every sub-field
+  is optional in the schema — contribute only the points you use; each contribution's own required fields are
+  schema-enforced.
+- The manifest is the **declaration**; your server code supplies the runtime halves. An HTTP route and a job must
+  be *declared here* or the host will refuse to serve/run them (see §2).
+
+## 2. The server — `src/server.ts`
+
+The server entry (`dist/server.js`) exports **`createPlugin`**. `createPlugin(host)` must be **pure** — it does
+no host I/O, so the host can construct every plugin before any side effect. All I/O goes inside `activate()`
+(called once at startup) and `runJob(ctx)` (called per scheduled/triggered job run).
+
+```ts
+import type { CreatePlugin } from "@ac/contract"
+
+export const createPlugin: CreatePlugin = (host) => ({
+  activate() {
+    // GET /api/x/hello/ping → the greeting setting (its default comes from the manifest `settings[]`).
+    host.routes.register("GET", "/ping", async () => {
+      const greeting = (await host.settings.get("greeting")) ?? "hello"
+      return Response.json({ greeting })
+    })
+    // A confirm-gated action: the button, confirm and fields come from the manifest; the handler is here.
+    host.actions.register({
+      id: "hello.ping",
+      run: async (input) => ({ echoed: input }),
+    })
+  },
+  runJob(ctx) {
+    // One `runJob` dispatches all the plugin's contributed jobs, selected by `ctx.jobId`.
+    if (ctx.jobId === "hello.tick") ctx.log("hello tick")
+    // hello.machines (#51) calls no verb -- the per-machine fan-out itself is what it demonstrates;
+    // #52's real scans are the verb-calling agent jobs. Records nothing on a console with no paired
+    // machine, same as any other agent job dispatched to zero machines.
+    if (ctx.jobId === "hello.machines") {
+      ctx.log(`hello from the host for ${ctx.machine?.name ?? "(no machine)"}`)
+    }
+  },
+})
+```
+
+- **Route** — `host.routes.register(method, path, handler)`. The handler is a web-standard
+  `(request: Request) => Response | Promise<Response>`, mounted at `/api/x/<id><path>`. You may only register a
+  `(method, path)` you declared in `contributes.routes` — an undeclared route throws. **Never answer `502` or
+  `504` yourself** (#474): the production console is reached through Cloudflare, and Cloudflare's own
+  documentation says it "returns a Cloudflare-branded HTTP 502 or 504 error when your origin web server responds
+  with a standard HTTP 502 bad gateway or 504 gateway timeout error" — so on the production console (default
+  Cloudflare error pages) your JSON `{ ok: false, error }` does not reach the browser and a client sees an HTML
+  page. For "a dependency I relay to (a paired agent, the sidecar)
+  is unavailable or refused" answer `503`: Cloudflare's Custom Errors page says its Error Pages "do not apply to
+  responses with an HTTP status code of `500`, `501`, `503`, or `505`", and its "Error 503" page tells an origin's
+  own 503 from Cloudflare's by whether the page's HTML contains `cloudflare`. Neither says in so many words that
+  an origin's 503 *body* passes through — that is inferred, and a Custom Error Rule an operator sets on the zone
+  can act on any status from 400 up — so the check on the deployed console is what proves it. Otherwise a 4xx or
+  `500`. `packages/host/src/no-gateway-status.test.ts` scans every bundled plugin's `src/` and the host's, and
+  fails naming the file and line (an installed third-party plugin is not covered).
+- **Action** — `host.actions.register({ id, run })`. The button, `confirm`/`danger` and the modal `fields` all
+  come from the manifest; here you supply only `run(input)`. (The action's manifest metadata drives the shell
+  UI; registering a `run` for an id the manifest omits simply leaves it without a button.)
+- **Job** — implement `runJob(ctx)` and dispatch on `ctx.jobId`. The host runs only jobs you declared in
+  `contributes.jobs`, on their 5-field cron `schedule`. `ctx.log` appends to that run's recorded log;
+  `ctx.signal` aborts at `timeoutSec`. `runOn: "host"` runs your `runJob` once, in the host process.
+  `runOn: "agent"` (#51) also runs your `runJob` in the host process — the agent itself runs no plugin
+  code — but once per currently paired machine, with `ctx.machine` set to `{ id, name }`; do the
+  machine's own work through `host.agent.call(ctx.machine.id, …)`. A machine that doesn't answer when
+  the job is due is never a failed run: it's queued (a red `queued` row in the tasks drawer) and the
+  host's own scheduler tick drains the queue, running the job for that machine as soon as it becomes
+  reachable again — nothing in your `runJob` needs to know this happened. `host.jobs.machineRuns(jobId)`
+  reads the current per-machine state: one entry per paired machine for an agent job (its last run,
+  or why it's still queued), or a single entry for a host job. `plugins/scans` (#258) is the reference
+  for a verb-calling agent job: it calls a scan verb per machine and stores the answer only on
+  success, keeping a separate `.../error` key for a failure and throwing the agent's reason verbatim
+  so the run is honestly recorded failed -- store, log, throw, in that order, never masking the
+  agent's text with a storage error of your own.
+- **Setting** — read/write with `host.settings.get(key)` / `host.settings.set(key, value)`. Both are async;
+  `get` returns the manifest `default` when unset.
+
+`createPlugin` must import from `@ac/contract` **type-only** (`import type`), so the compiled `dist/server.js`
+has no runtime imports — see §6.
+
+### Rejecting a bad action input — `ActionInputError` (#440)
+
+An action's `run(input)` receives whatever the caller POSTed under `{ "input": … }`. When that input is
+**malformed** (a missing or wrong-typed field, a bad `owner/name`), throw an `Error` whose **`name` is
+`"ActionInputError"`** and the host answers `400` with its message. Any other thrown error is a `500`.
+Carry the class in your own plugin — five lines, no runtime import from the host:
+
+```ts
+import type { ActionInputErrorName } from "@ac/contract"
+
+export class ActionInputError extends Error {
+  override name: ActionInputErrorName = "ActionInputError"
+}
+```
+
+Throw it for the **shape of what the caller sent** — that is the caller's to fix. Keep a plain `Error` (a 500)
+for anything that went wrong in the world while acting on a well-formed input: a GitHub failure, a store that
+isn't cloned, a machine that isn't paired. When unsure, leave it a plain `Error`.
+
+**Why a name and not a class you import.** A plugin server imports `@ac/contract` as `import type` only (above), so
+a class exported from the contract would give every plugin a *runtime* dependency on it, which its compiled
+`dist/server.js` is meant not to have. And `instanceof` cannot see across a bundle: a rollup-bundled server
+inlines its own copy of any class it declares, which is a different class from the host's. A `name` compares
+equal wherever the error was made (the `AbortError` idiom). Only the *type* of the name,
+`ActionInputErrorName`, comes from the contract, so renaming it there breaks your build rather than silently
+turning your 400s into 500s.
+
+**The route also guards a missing `input` for you.** If your manifest declares `fields` for the action and the
+body has no `input` object (`null`, an array, a string, or nothing at all — a caller who sent the fields at the
+top level of the body instead of under `input`), the host answers `400` *before your `run` is called*, naming
+the fields. An action that declares no `fields` is not guarded — it is legitimately called with no input — so
+its `run` must still cope with `input` being `undefined`. A field-declaring action's `run` still validates each
+field itself: the guard only ensures there is an object to read them from.
+
+### Action form fields — `multiselect`, `hidden`, `optionsFrom` (#463)
+
+An action's `fields[]` are what the universal modal renders. Each field has a `name` (the key in the `input` your
+`run` receives), a `label`, and a `type`:
+
+| `type` | Renders | Value your `run` receives |
+|---|---|---|
+| `string` | a text box | a string |
+| `text` | a multi-line text box | a string |
+| `number` | a number box | a number |
+| `boolean` | a checkbox | a boolean |
+| `select` | a `<select>` of its fixed `options` (or of the choices `optionsFrom` answers) | a string |
+| `multiselect` | a picker (below) of its `optionsFrom` choices or its fixed `options`, or a comma-separated text box when it has neither | a **`string[]`**, trimmed and de-duplicated |
+| `hidden` | nothing | the value the caller seeded (`actions.open({ …, input })`), unchanged; when the seed does not name it (or there is no `input`), the one in the stored draft; `""` otherwise |
+
+A `multiselect`'s value is always an array in the modal's state, in the draft it stores, and in the `input` it
+POSTs. A seed or an older stored draft that holds a comma-separated string (`"bug, docs"`) is read as that list,
+so a caller may seed either form. A `hidden` field is for a value the caller knows and the user should not edit
+(an id, a scope) but your `run` still needs; it is not validated or shown by the shell, so treat it as caller
+input like any other.
+
+**`optionsFrom`** lets a field's choices come from one of your own routes instead of being fixed in the manifest.
+It is valid only on a `select` or `multiselect` field, not beside a non-empty fixed `options` list (one source of
+choices, not two), and the validator refuses anything provably wrong at load time (the plugin is skipped, naming
+the field):
+
+```json
+{
+  "name": "toppings",
+  "label": "Toppings",
+  "type": "multiselect",
+  "optionsFrom": { "route": "/toppings", "params": ["shop"] }
+}
+```
+
+- **`route`** must be one of the plugin's **own declared `GET` routes** (`contributes.routes[]`): a path starting
+  with `/`, with no query string or fragment and no `..`, `//`, `%` or `\` (a percent-escaped dot segment would
+  climb out of your namespace once the browser resolves the URL). A route declared as `toppings` is served as
+  `/toppings`, so `optionsFrom` names it that way. The shell fetches `/api/x/<id><route>`.
+- **`params`** (optional) names **other fields of the same action**. Their current values are sent as query
+  parameters (`?shop=…`), a `multiselect`'s as its comma-joined picks. While any named field is empty nothing is
+  fetched and the picker says `Fill in “<label>” to load the choices.` (a `hidden` field named here must be
+  seeded by the caller, since it has no control to fill in); the first fetch runs at once, each later one waits
+  for a 250 ms pause after the last change, and an answer that is no longer the latest is dropped. While the
+  choices are loading or blocked, the field lists the picks it still holds (`Chosen: …`), since they are still
+  submitted.
+
+**What the route answers** is an **`ActionOptionsResponse`** (`packages/contract/src/action-options.ts`, its
+comments condensed here):
+
+```ts
+type ActionOptionsResponse =
+  | { ok: true; groups: ActionOptionGroup[]; allowCustom?: boolean; preselect?: string[] }
+  | { ok: false; error: string }
+
+interface ActionOptionGroup {
+  key: string
+  caption?: string // the group's heading
+  exclusive?: boolean // at most one pick from this group: a segmented control with a "None"
+  options: ActionOption[]
+}
+interface ActionOption {
+  value: string // what is submitted
+  label?: string // what is shown; defaults to value
+  color?: string // six hex digits, no "#" -- GitHub's form (a label's colour)
+  description?: string // the chip's tooltip
+  badge?: string // a small tag beside the label
+}
+```
+
+The shell makes every part of the answer safe before it renders it: a `color` that is not exactly six hex digits
+is ignored, an option `value` is trimmed, a duplicate `value` within a group, an option with no string (or a blank)
+`value` and a group left empty are dropped, and every string is rendered as text, never as markup. A body that is
+not that shape, a network error, no answer within 15 seconds, or `{ ok: false, error }` (**whatever the status** —
+answer `503`, never `502`/`504`, per §2) is a **failed load**:
+the field falls back to a plain text box, so the action stays usable: a `multiselect`'s is comma-separated
+(`Couldn't load the choices: <reason>. Type them below, separated by commas.`), a `select`'s takes one value
+(`Couldn't load the choices: <reason>. Type a value below.`).
+
+The picker itself is the shell's, and behaves the way 1.x's label picker did: an `exclusive` group is a segmented
+control and clicking the current pick (or "None") clears it; the other groups are coloured chips (text colour
+chosen for contrast); a search box appears when **more than 8** options sit outside the exclusive groups (an
+exclusive group is a small control and is never filtered) and never hides an option that is already chosen (an
+option of a loaded group that you just unticked stays on screen until the filter next changes); a chosen value no group names (a seed, a
+draft) lands in a trailing **Other** group instead of being dropped, and **`allowCustom: true`** adds a free-form
+"add" box there (Enter adds, it does not submit the form); **`preselect`** picks those values once (a `select`
+takes the first), only while nothing is chosen and the user has not touched the picker — a seed or a draft that
+already holds picks wins over it (an empty draft does not). It is keyboard-operable (the chips and segments are
+native checkboxes and radios), and a group is named by its `caption`, or by the field's label when it has none.
+A `multiselect`'s fixed `options` list gets the same treatment as a route's answer (values and labels trimmed,
+blanks and repeats dropped); a plain `select`'s fixed `options` are rendered as written.
+
+`plugins/hello` is the worked example: `hello.order` (a `hidden` `ticket`, a `string` `shop` and the `multiselect`
+`toppings` above) reads `GET /toppings?shop=…`, which answers an exclusive **Size** group and a coloured
+**Toppings** group of twelve options with `allowCustom`; `?shop=closed` answers `503 { ok: false, error: "the shop
+is closed" }` so you can see the fallback. Its `run` echoes its input, so the submitted array is visible.
+
+## 3. The frontend — `src/ui.tsx`
+
+A plugin's `frontend` (`dist/ui.js`) is a single ES module the host serves at `/plugins-assets/<id>` and the
+shell `import()`s. It exports the components the manifest's `export` names point at. It imports **only the
+import-map externals** — `react` (via `react/jsx-runtime`), `react-dom`, `react-router`, `@rackbops/ui-react` and
+`@ac/host` — so **React is never bundled**: the shell and every plugin share one React copy through the host
+page's import map.
+
+The built `index.html` template keeps those paths unversioned, but the host adds its running version as a
+`?v=<encoded-version>` query when it serves the shell. There are seven mapped specifiers and six distinct
+vendor URLs because `react-dom` and `react-dom/client` deliberately share the byte-identical
+`/vendor/react-dom.js?v=…` URL. `/index.js` receives the same query. Plugins must keep importing the bare
+specifiers above—never `/vendor/*.js` or a relative `src/vendor/*` module—so the browser cannot load a second
+React or `@ac/host` instance. Both versioned and legacy asset URLs remain valid and revalidating; the query is a
+deployment cache key, not a filesystem path or a change to the plugin ABI.
+
+```tsx
+import { Card } from "@rackbops/ui-react"
+
+export function HelloPanel() {
+  return (
+    <Card>
+      <h1>Hello from a plugin</h1>
+      <p>This panel is contributed by plugins/hello — the reference plugin.</p>
+    </Card>
+  )
+}
+
+export function HelloCard() {
+  return <Card>Hello, from a contributed card.</Card>
+}
+```
+
+A card's manifest `sizes` (`["2x1"]` above, `<width>x<height>`) names the grid slots it renders at; the
+Overview dashboard (#77) reads only the **height** half as the card's own default row-span tier (1/3, 2/3, or
+3/3) — `sizes[0]`'s second number, falling back to 2 when that's missing, unparseable, or outside 1-3. A viewer's ⚙ menu can
+override a card's height per layout; picking that same default height back clears the override rather than
+pinning it, so an un-touched card keeps tracking whatever this manifest declares even after a redeploy changes
+it.
+
+### The `@ac/host` browser module
+
+`@ac/host` (typed as `BrowserHostApi` in `@ac/contract`) is the one shared module instance the shell and every
+plugin import through the host page's import map — upgrading it upgrades every plugin, with no plugin rebuild.
+Methods are added additively. **Inside the console**, every plugin-facing surface below is safe to call from a
+mounted panel/card's effect **or** at bundle import time: a call made before the shell has mounted its chrome is
+held and delivered, in order, once it does — a plugin never has to wait for the shell itself. **Outside the
+console** (a bundle that never runs inside the shell at all) that hold is permanent for `header.registerButton`,
+`actions.open` and `quickcast.register` — there is no shell to eventually deliver to, so the call simply has no
+effect — except `toast`, which renders through a minimal, self-contained fallback after a tick once nothing has
+claimed it, so a toast is never silently lost.
+
+`theme.token` resolves a `--rb-*` custom property to its current value:
+
+```ts
+import { theme } from "@ac/host"
+
+const accent = theme.token("--rb-accent")
+```
+
+`toast` shows a message through the shell's toast portal. Called before the shell mounts, it is buffered (capped
+so an import-time loop can't grow it without bound) and flushed once it does; only if no shell ever mounts at
+all does it fall back to a minimal, self-contained DOM toast — so a plugin calling `toast` never silently loses
+a message:
+
+```ts
+import { toast } from "@ac/host"
+
+toast("hi from hello")
+```
+
+`header.registerButton` puts a button in the shell header and returns the unregister — the unregister works
+whether or not the button has been delivered yet (cancels a pending registration, or removes a delivered one):
+
+```ts
+import { header } from "@ac/host"
+
+const unregister = header.registerButton({ id: "hello-scan", label: "Scan", onClick: () => {} })
+```
+
+`actions.open` opens the universal confirm modal for a registered action — the plugin's own, or another
+plugin's (`pluginId` names it; the Board and the Artifacts action bar open `provider-github`'s and others').
+`target` scopes the draft to a specific object, e.g. an issue number, when the action isn't `scope: "global"`.
+It is fire-and-forget, held until the shell mounts, and dropped if it never does:
+
+```ts
+import { actions } from "@ac/host"
+
+actions.open({ pluginId: "hello", actionId: "hello.ping" })
+```
+
+`input` seeds the form (`actions.open({ pluginId: "provider-github", actionId: "issue.comment", target:
+"acme/kb#2", input: { repo: "acme/kb", number: 2 } })`). A seed wins over the stored draft for the same
+`target` **for the fields it names** (#478): every other field keeps what the draft holds, so a comment typed
+into a modal opened from a row survives a cancel and a reopen of the same row, while a seeded `repo` or `number`
+is never stale. A field the seed names as empty (`""`, `[]`, `0`, `false`) still wins; only a key that is absent
+(or `undefined`) leaves the field to the draft, and a field in neither gets its default. So seed only what you
+know: a key seeded as `""` because the value is unknown wipes what the operator typed for that field on a reopen
+-- omit the key instead. A key that is not a
+field of the action is dropped, from the seed and from the draft. The merged values are written back as the
+draft at once, so a reload keeps exactly what the form shows; a draft is still kept on Cancel and on a failed
+submit and cleared on a successful one, under the same `ac-draft:<pluginId>/<actionId>/<scopeKey>` key.
+
+**A seed must name every field whose meaning depends on another field it names.** `issue.labels` diffs
+`originalLabels` (what the form showed) against `labels` (what is ticked), so the Board seeds both; a caller that
+seeded only `originalLabels` would get a fresh snapshot diffed against a stale drafted `labels`, and remove
+labels nobody unticked.
+
+`actions.open` returns nothing, and cannot tell you whether the action ran. `actions.subscribe` is that signal:
+the listener is called once for every action the modal dispatched and got a result for — success or failure,
+and whoever opened it (your own `actions.open`, or the Ctrl/Cmd+K palette) — with the action's `pluginId`,
+`actionId`, `ok`, the `error` message on a failure, and the opened ref's `target` (absent when the ref had none,
+as from the palette) — what the action was opened *for*, not what the operator finally typed into the form. It
+carries no input. Cancelling, or closing before the confirm, calls nothing. Use it to
+refresh what an action changed — the Board refetches the card an `issue.*` action named, so a closed issue's row
+goes at once instead of at the next poll. It returns the unsubscribe; a listener that throws is logged and
+skipped, and never reaches the modal or another listener. It needs no shell to be mounted: it simply hears
+nothing until one dispatches something.
+
+```ts
+import { actions } from "@ac/host"
+
+const off = actions.subscribe((e) => {
+  if (e.ok && e.pluginId === "provider-github" && e.actionId.startsWith("issue.")) {
+    // refetch what the action changed; e.target says what it was opened for (absent from the palette)
+  }
+})
+// ... and in the effect's cleanup: off()
+```
+
+Every tabbed panel, and every action of a plugin that loaded without error, is automatically listed in the
+Ctrl/Cmd+K quickcast palette — nothing to register for that. (A panel that lost a contested nav slot —
+`buildTabs` skips a non-owning `navOwner: false` panel — has no tab but IS still listed: `quickcastPanels`
+offers every loadable panel on purpose (#65), so the palette stays a keyboard way back to it. Actions are pure
+data, so they surface even for a plugin with no frontend at all.) `quickcast.register` is for anything beyond a plain
+panel/action jump: register a function returning the plugin's current items, and the palette calls it on open
+and again on every filter keystroke (matching each item's `label` and `hint` — see below). Items appear after
+the built-in panel/action items, in registration order; the plugin's `run` decides what happens (navigate, open
+its own UI, call `actions.open`) and the palette closes before calling it. Held until the shell mounts, the
+same as `header.registerButton`. This is the snippet `HelloPanel` itself registers in an effect:
+
+```tsx
+import { quickcast, toast } from "@ac/host"
+import { useEffect } from "react"
+
+useEffect(
+  () => quickcast.register(() => [{ label: "Hello: say hi", run: () => toast("hi from hello") }]),
+  [],
+)
+```
+
+A `hint` (optional, e.g. a category or the plugin id) is searched the same as `label`, ranked after it — so
+`>hel` finds an item whose label doesn't contain "hel" but whose hint does — and renders as muted secondary
+text in the row.
+
+`fetch` makes a same-origin, credentialed, CSRF-aware request to a host/plugin route — a relative `path`
+resolves against the console origin; a cross-origin absolute URL throws rather than being followed. A panel
+reads a provider's routes through this rather than a bare `window.fetch`; a card should reach for `cached`
+below instead:
+
+```ts
+import { fetch } from "@ac/host"
+
+const res = await fetch("/api/x/provider-github/issues?repo=o/n")
+const data = await res.json()
+```
+
+`cached` and `invalidate` wrap `fetch` in a per-path 45 s (default) TTL cache (E7 #77): a call within `ttlMs`
+of the path's last fetch reuses that same underlying request instead of issuing a new one — each caller
+still gets its own `Response` (`.clone()`), so two independent reads of a cache hit never collide on an
+already-consumed body. Only `GET` may be cached (`cached` throws on any other method); a rejected fetch is
+never cached — the very next call retries. **A card reads through `cached`, never bare `fetch`, so Refresh
+and the Overview heartbeat (both call `invalidate`) actually reach it** — a card that bypasses `cached` keeps
+serving its own stale response until its own next poll, deaf to both:
+
+```ts
+import { cached, invalidate } from "@ac/host"
+
+const res = await cached("/api/x/scans/context-pressure") // a hit inside 45 s reuses the one in-flight/last fetch
+const data = await res.json()
+
+// ... later, e.g. from a Refresh button:
+invalidate("/api/x/scans/context-pressure") // this one path
+invalidate() // every cached path
+```
+
+**Type resolution and testing.** A plugin importing `@ac/host` needs three things beyond the import itself —
+the guide is written against hello, so this is exactly what it does:
+
+1. **The ambient declaration.** TypeScript's `declare module "@ac/host"` (in
+   `packages/ui-shell/src/ac-host.d.ts`, what lets the shell's own program see it) doesn't cross a package
+   boundary just because your plugin also depends on `@ac/contract` — your plugin's own `tsconfig.ui.json`
+   only sees files it includes. Copy [`plugins/hello/src/ac-host.d.ts`](../../plugins/hello/src/ac-host.d.ts)
+   into your plugin (it deliberately re-declares only the plugin-facing surface — no `ShellChrome`/`__shell`,
+   which are shell-internal) and add it to that tsconfig's `include`, the way hello's
+   [`tsconfig.ui.json`](../../plugins/hello/tsconfig.ui.json) does. A vendored copy can silently drift from
+   the shell's own, the same risk as the `@ac/contract` schema copy in §5 — guard it the way
+   [`plugins/hello/src/ac-host-drift.test.ts`](../../plugins/hello/src/ac-host-drift.test.ts) does, pinning
+   the copy's exported surface against the shell's line-for-line.
+2. **The Vitest alias.** `@ac/host` only resolves for real through the host page's import map, which a plain
+   Node test runner has no equivalent of. If you test the frontend through Vitest, alias the specifier to
+   `packages/ui-shell/src/vendor/ac-host-entry.mjs` (the shell's own implementation — reuse it rather than
+   mocking), the way [`plugins/hello/vitest.config.ts`](../../plugins/hello/vitest.config.ts) does.
+3. **Leaving it external in the build.** Nothing extra is needed here as long as you build with plain `tsc`
+   (§3, no bundler) — `tsc` only transpiles syntax, so `import { toast } from "@ac/host"` is emitted into
+   `dist/ui.js` verbatim, unresolved, for the browser's import map to satisfy at runtime, exactly like the
+   `react`/`@rackbops/ui-react` imports. (This only becomes something to configure explicitly if a plugin
+   ever builds its frontend with a bundler instead — then `@ac/host` needs the same external treatment
+   `packages/ui-shell/vendor.config.mjs` gives `react`/`react-dom`.)
+
+Build it with `tsc` and `"jsx": "react-jsx"` — `tsc` under `nodenext` preserves the bare `@rackbops/ui-react`
+import and injects `import { jsx } from "react/jsx-runtime"`, emitting exactly the servable ESM the import map
+resolves. Do **not** bundle (no rollup/esbuild bundling of React) — that would ship a second React copy.
+
+hello uses two tsconfigs so the server (no JSX) and the frontend (JSX) build separately:
+
+`tsconfig.json` (server):
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
+  "include": ["src/server.ts", "src/server.test.ts"]
+}
+```
+
+`tsconfig.ui.json` (frontend):
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist", "jsx": "react-jsx" },
+  "include": ["src/ui.tsx", "src/ui.test.tsx"]
+}
+```
+
+and `package.json` builds + typechecks both:
+
+```json
+"scripts": {
+  "typecheck": "tsc --noEmit && tsc -p tsconfig.ui.json --noEmit",
+  "build": "tsc && tsc -p tsconfig.ui.json",
+  "test": "vitest run"
+}
+```
+
+`react` and `@rackbops/ui-react` are `dependencies` (needed to typecheck the frontend); at runtime they resolve
+through the import map, not from the plugin's `node_modules`. `@rackbops/ui-react` is **optional** — a frontend
+can use plain JSX and drop it, keeping only `react`. And if you split the server or frontend across multiple
+source files, each relative import carries an explicit `.js` extension (`import { x } from "./util.js"`, even
+from a `.ts` source) — the workspace is `moduleResolution: nodenext`.
+
+If your **server** takes on a runtime npm dependency (not just a type-only `import type`), it must be bundled
+into `dist/server.js` — the image ships a plugin's `package.json` + `dist/*.js` only, never a plugin
+`node_modules`, and `scripts/assert-image.mjs` asserts every `plugins/*` id actually loads in the booted image
+(so a plugin shipping an unresolvable bare import goes red there, not silently in production). `plugins/issues-classic`
+is the worked example (#312): `tsconfig.build.json` emits the server alone to `dist-tsc/`, and
+`rollup.config.mjs` bundles that into `dist/server.js` with everything except Node's own `node:*` built-ins
+inlined — `yaml` (its `views.yaml` parser) included. `createPlugin` stays pure regardless of how the server is
+built. The **frontend** is never bundled this way (§3 above) — `@ac/host`/`react`/`@rackbops/ui-react` resolve
+through the shell's import map, not a bundle.
+
+## 4. `CHANGELOG.md` — required, and version-matched
+
+Every plugin needs a `CHANGELOG.md` with a section matching its `package.json` `version`, in Keep-a-Changelog
+form `## <version> - <YYYY-MM-DD>`:
+
+```markdown
+# Changelog
+
+## 0.1.0 - 2026-09-21
+
+- A second action, `hello.order`, and a second route, `GET /toppings` (#463): the worked example of the
+  action-form option pickers. The action has a `hidden` field (`ticket`), a `string` field (`shop`) and a
+  `multiselect` (`toppings`) whose choices come from `GET /toppings?shop=<shop>` (`optionsFrom`): two
+  groups -- an exclusive "Size" and a plain, coloured "Toppings" -- and a free-form add. `?shop=closed`
+  answers 503 with `{ ok: false, error: "the shop is closed" }`, so the picker's text-box fallback is
+  reachable in a browser. The handler echoes the input it received, so the submitted `toppings` array is
+  visible. `hello.ping` is unchanged.
+```
+
+This is a **hard requirement**: `scripts/generate-index.mjs` scans every plugin's `acPlugin` block + CHANGELOG
+into the committed `plugins.json` (the shared plugin-index envelope), and **throws** — failing `pnpm run check`
+— if the current version has no matching CHANGELOG section. Bump the version and add its section together.
+
+## 5. Vendor the contract — `vendor/@ac/contract/schema.json` (when you need it)
+
+An in-monorepo plugin depends on `@ac/contract: workspace:*`, so it builds against the **live** contract and a
+host-side change reaches it immediately — nothing to drift from. A plugin that instead pins or publishes against
+a fixed `@ac/contract` builds against a **frozen copy**, which can silently fall behind the host. The guard
+against that is a vendored snapshot of the schema:
+
+```sh
+cp packages/contract/schema.json plugins/<id>/vendor/@ac/contract/schema.json
+```
+
+`check-contract` (`packages/host/src/check-contract.test.ts`) asserts that **every vendored copy that exists** is
+identical to the live `packages/contract/schema.json`, and that at least one plugin vendors one so the guard is
+never a no-op (the reference plugin `hello` provides that copy). So vendoring is **optional for a `workspace:*`
+monorepo plugin** and the pattern to follow for a pinned or published one; when the contract changes you
+**re-vendor** (copy again) and commit — that acknowledgement is the point of the check.
+
+## 6. Build, package, and verify it loads
+
+```sh
+pnpm install                 # once, after adding the plugin's deps
+pnpm run check               # build + regenerate plugins.json + lint + typecheck + test
+```
+
+`pnpm run check` runs `vitest run` in every package, and Vitest **fails a package that ships no test file** (with
+*no test files found*) — so write at least one test; copy the shape of `hello`'s `src/server.test.ts` (a
+`createPlugin` smoke test with a mocked `host`) and `src/ui.test.tsx` (a component-export test), both listed in
+the tsconfig `include`s above. `check` also regenerates the committed `plugins.json` and then
+**fails if it differs from `HEAD`** — adding a plugin changes it, so `pnpm run check` stays red until you
+**commit** the regenerated `plugins.json` (staging is not enough; the check diffs against the last commit).
+
+Then confirm the plugin **loads and activates**. Build, then boot the host pointed at your `plugins/` dir — both
+`AC_PLUGINS_DIR` and `AC_STATE_DIR` must be **absolute** paths (the host rejects a relative one at startup), and
+`AC_STATE_DIR` must be **writable**: the host opens its SQLite DB at `<AC_STATE_DIR>/ac.db`, and the image
+default `/state` does not exist on a dev box.
+
+```sh
+pnpm -r build
+mkdir -p .dev-state
+AC_PLUGINS_DIR="$PWD/plugins" AC_STATE_DIR="$PWD/.dev-state" node packages/host/dist/main.js
+```
+
+The host listens on `http://127.0.0.1:8787` by default (override with `AC_HOST` / `AC_PORT`). Read `GET
+/api/plugins` there (the envelope is `{ "plugins": [ … ] }`): your plugin appears with **no `error`** and its
+`frontend`/`panels`/`cards`/`actions` — a contribution you didn't declare is simply absent. `GET /api/x/<id>/…`
+hits your routes; `/plugins-assets/<id>` serves your frontend. Its entry also carries `origin` — the shell marks
+a tab dashed when the plugin was found under an *installed* plugins dir rather than the image's own `plugins/`;
+this is derived from where the host found it, so there is nothing a plugin can declare to change it.
+
+**Packaging into the image.** `main.js` discovers plugins at `../plugins` (i.e. `/app/plugins` in the image), so
+the `Dockerfile` copies each plugin's runtime files there: `package.json` plus the whole `dist/`
+directory (`COPY --from=build /repo/plugins/<name>/dist ./plugins/<name>/dist`) — **not** a
+hand-listed set of individual files (#401). Your server may freely split across sibling emitted
+modules (a plain `tsc` build, e.g. so one can be unit-tested directly — `plugins/provider-artifacts`,
+#67, is the reference) with no extra Dockerfile work: the whole-`dist/` copy ships whatever you
+emit, automatically. This is safe from shipping a compiled `*.test.js` alongside your real modules
+only because the container's `pnpm -r build` runs your **build-only** tsconfig
+(`tsconfig.build.json`/`tsconfig.ui.build.json`, excluding every `*.test.ts`), never the
+test-covering one `typecheck` uses — guarded by `scripts/check-no-test-emit.mjs` (#350, run twice in
+`pnpm run check`), which fails the moment any package's build leaves a compiled test file under
+`dist*/`. A brand-new **plugin directory** still needs its own two `COPY` lines (`scripts/
+check-dockerfile-plugin-copy.mjs`, wired into `pnpm run check`, fails naming any `acPlugin` plugin
+copied file-by-file or not copied at all; `scripts/assert-image.mjs` is the runtime-load proof that
+catches a plugin dir never `COPY`ed at all, in the real booted image).
+
+## 7. Host-agent capabilities
+
+A plugin that needs to reach a paired machine's host agent (a git status, a `claude`/`gh` run, ...)
+declares which capabilities it may use in its manifest, as a sibling of `contributes` rather than
+inside it -- a capability isn't a contribution point, it's a permission:
+
+```json
+"acPlugin": {
+  "id": "hello",
+  ...
+  "capabilities": ["agent.git.read"]
+}
+```
+
+Each declared capability appears as its own row in the Agents panel's Grants grid, one column per
+paired machine; an operator grants or revokes it there, per machine, and nothing here runs until it
+is granted. `hello`'s own manifest declares `agent.git.read` as the reference declaration (`hello`
+never actually calls it -- the declaration alone is what the grid, a live pairing pass, and this
+guide need).
+
+At runtime, call a granted capability on a specific paired machine through `host.agent`:
+
+```ts
+const machines = await host.agent.list() // paired machines, each with its current grants
+const outcome = await host.agent.call(machines[0].id, "GET", "/v1/repos")
+if (outcome.ok) {
+  // outcome.status, outcome.body
+} else {
+  // outcome.error.kind: "unknown-machine" | "refused" | "grant" | "pin" | "network" | "http"
+}
+```
+
+`outcome.error.kind === "grant"` is the one worth showing to the person almost verbatim -- it
+carries the agent's own refusal text (`"<capability> is not granted to <plugin> on <machine>"`). The
+others are the console's problem to describe differently: `unknown-machine` (a stale machine id),
+`refused` (the path isn't a `/v1/*` verb, or is `/v1/pair`/`/v1/grants` -- the control plane, never
+reachable this way, whatever the path spelling), `pin` (the agent's certificate changed since
+pairing), `network`, `http` (an unexpected status the console doesn't special-case).
+
+A verb that can genuinely run long (a scan, a build) needs a fifth, optional `call` argument:
+`host.agent.call(machineId, method, path, body, { timeoutMs })` sets how long the console waits for
+the agent's response *headers* (undici's `headersTimeout`; the default is 300s). Pass the verb's own
+limit plus a margin -- `scans` passes `agent limit + 30s` -- so the agent's own `504` reaches the
+console before the console gives up and reports a bare `network` timeout instead.
+
+### Streaming a job into the tasks drawer
+
+A capability whose verb starts a long-running agent job (`exec/claude`'s `{ jobId }`, #54) doesn't
+need to poll or parse SSE itself -- `host.agent.streamJob(machineId, jobId, { label })` opens the
+agent's `GET /v1/jobs/:jobId/events` through the same pinned client, registers a new host task for
+`label`, and relays every `line`/`done` frame into it as the job runs; it resolves `{ taskId }` once
+the agent has confirmed the stream is open (a `200`), or rejects (starting no task) on anything
+else -- an invalid `jobId`, an unknown machine, or a non-`200` from the agent (a `404`, a `403`
+refusal, ...), each surfaced the same way `call` surfaces them. The relay itself runs detached from
+that promise, so nothing in a plugin's own code touches the stream at all:
+
+```ts
+const { jobId } = await execResult // however the plugin's own verb call started the job
+const { taskId } = await host.agent.streamJob(machineId, jobId, { label: `code: ${prompt}` })
+// taskId names the task now streaming in the tasks drawer -- the action can simply return it.
+```
+
+`plugins/claude-runner` (#54) is the reference: `task.code` and `routine.rerun` call `exec/claude`
+then `streamJob` and return the task id, never touching SSE framing themselves.
+
+## 8. The needs-attention rail (#78)
+
+`contributes.attention: true` marks a plugin that serves `GET /api/x/<id>/attention` ->
+`{ ok: true, items: AttentionItem[] }` (`@ac/contract`'s `attention.ts`). The `overview` plugin's
+rollup card discovers every contributor from `GET /api/plugins`'s `PluginView.attention` field (no
+second manifest read) and polls each `/attention` route, merging, sorting by severity, and deduping
+by `${source}:${id}`.
+
+```ts
+interface AttentionItem {
+  id: string                 // unique within YOUR plugin; the rollup's dedupe key is `${source}:${id}`
+  severity: "danger" | "warn" | "info"
+  source: string              // your own plugin id -- the rollup shows it as the row's source
+  text: string                 // always a counted sentence: "3 open actions in the ledger", never "some actions"
+  badge?: string
+  href?: string                // an external link; wins over `target` when both are set
+  target?: string               // an in-app destination: "widget:<cardId>" or "panel:<pluginId>"
+  hint?: string                  // the exact command to run, or the reason -- shown as a tooltip/expander
+  action?: { kind: "issue"; repo?: string; title: string; body: string }  // opens provider-github's issue.create, seeded
+}
+```
+
+**Own the fact, own the row.** The rollup itself derives nothing -- it only merges what contributors
+already computed. If your plugin is the one that KNOWS a fact is wrong (a failed job, a stale scan, a
+stuck push), your plugin is the one that turns it into a row, at the severity and with the hint that
+makes sense given what only you know about it. Don't reach into another plugin's storage or routes to
+compute a row about ITS facts -- ask that plugin's own maintainer to add the row instead.
+
+`scans` (`scan.stale.<kind>`, warn, one row per kind with a stale machine) and `provider-artifacts`
+(`store.push-rejected` danger, `ledger.open`/`reviews.open`/`reviews.untracked` warn,
+`publish.error.<machineId>` warn) are the reference contributors; `overview`'s own server (`GET
+/attention`'s handler) is the reference for a plugin computing rows about facts it has PRIVILEGED,
+cross-plugin, host-internal access to (job health across every other plugin, paired-agent
+reachability) rather than its own storage -- `host.jobs.machineRunsOf(pluginId, jobId)` and
+`host.plugins.list()` are additive `HostApi` capabilities added for exactly this, deliberately
+scoped no wider than the data `GET /api/jobs/:pluginId/:jobId/runs` and `GET /api/plugins` already
+serve publicly over HTTP.
+
+## 9. Building a plugin outside this repo (#450)
+
+Everything above is written from inside this monorepo, where a plugin depends on `@ac/contract:
+workspace:*` and builds against the **live** contract with nothing to drift from. A plugin that
+instead lives in its **own repository** — the normal shape for a third-party plugin — depends on the
+**published** [`@rackbops/ac-plugin-contract`](https://www.npmjs.com/package/@rackbops/ac-plugin-contract)
+package instead: the same `HostApi`, manifest types, and generated JSON Schema this guide has been
+using all along, assembled by `packages/plugin-contract/build.mjs` from this repo's own `@ac/contract`
+build, the shell's `ac-host.d.ts`, and this very file (shipped inside the package as `AUTHORING.md`).
+Its version always equals the `artifact-console` host's own version — pin your `devDependency` the
+way you'd pin against a specific host release.
+
+**The devDependency:**
+
+```sh
+pnpm add -D @rackbops/ac-plugin-contract @types/node @types/react
+```
+
+`@types/react` is for a frontend written as `.tsx`: the tsconfig below compiles JSX with
+`"jsx": "react-jsx"`, and without React's types every JSX tag fails (`TS2875`, `TS7026`). A frontend
+with no JSX can leave it out. React itself is never a dependency of your package: the console's import
+map provides it at runtime (the externals below).
+
+`HostApi`'s types (and `@octokit/rest`'s, which it references) use fetch-API globals such as
+`Request`, `Response`, `AbortSignal`, `Blob` and `File`. With TypeScript's default `lib` the DOM
+library declares them; a server-side tsconfig that narrows `lib` to exclude DOM (this repo's own uses
+`["ES2023"]`) needs `@types/node` for them instead. A plugin server runs on Node, so the tsconfig
+below names `"node"` — which is why `@types/node` must be installed: naming it without the package
+fails with `TS2688: Cannot find type definition file for 'node'`.
+
+**A tsconfig** — the same `nodenext` shape every in-repo plugin already builds with (§3 above), plus
+the ambient `@ac/host` declaration this package publishes as a types-only subpath. Naming anything in
+`types` REPLACES TypeScript's default auto-inclusion of every installed `@types/*` package (the same
+reason this repo's own `tsconfig.base.json` explicitly lists `"node"`), so `"node"` is named alongside
+the host declaration or Node's own globals (`process`, `Buffer`, …) disappear from your server code:
+
+```json
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "jsx": "react-jsx",
+    "types": ["node", "@rackbops/ac-plugin-contract/host"]
+  }
+}
+```
+
+`@rackbops/ac-plugin-contract/host` is what replaces copying `plugins/hello/src/ac-host.d.ts` by hand
+(§3, step 1, the in-repo path): the published package's own `./host` export IS that ambient
+declaration, pre-stripped of the shell-internal `ShellChrome`/`__shell` surface a plugin was never
+meant to see, kept in sync with the live shell automatically on every release rather than by a
+vendored copy a plugin author has to remember to update.
+
+**Your server code:**
+
+```ts
+import type { HostApi, Plugin } from "@rackbops/ac-plugin-contract"
+
+export function createPlugin(host: HostApi): Plugin {
+  return { activate: async () => { host.log.info("hi") } }
+}
+```
+
+**Your frontend code** imports `@ac/host` exactly as an in-repo plugin does (§3) — the specifier is
+never a real dependency of your package (it resolves through the console's own import map at
+runtime, never through your `node_modules`), so don't add it to `package.json` at all; the
+`types` array above is what gives it a type without one.
+
+**The rollup externals**, if your frontend builds with a bundler instead of plain `tsc` (§3's own
+"leaving it external" note): the same seven import-map specifiers every in-repo plugin's frontend
+resolves against, so your bundle inlines none of them — `react`, `react/jsx-runtime`, `react-dom`,
+`react-dom/client`, `react-router`, `@ac/host`, `@rackbops/ui-react`.
+
+**Vendoring `schema.json` with a drift check.** §5 above vendors a schema snapshot for a plugin
+pinned against a *frozen* contract, which an out-of-repo plugin always is (there is no live contract
+to build against outside this repo at all). Vendor the published copy, and check it on every install
+rather than trusting the pin alone — the console's own manifest schema can change between the
+version you built against and the version you're actually running against:
+
+```sh
+mkdir -p vendor && cp node_modules/@rackbops/ac-plugin-contract/schema.json vendor/schema.json
+```
+
+```js
+// scripts/check-schema-drift.mjs
+import { readFileSync } from "node:fs"
+
+const vendored = readFileSync("vendor/schema.json", "utf8")
+const live = readFileSync("node_modules/@rackbops/ac-plugin-contract/schema.json", "utf8")
+if (vendored !== live) {
+  console.error("vendor/schema.json has drifted from @rackbops/ac-plugin-contract -- re-vendor it:")
+  console.error("  cp node_modules/@rackbops/ac-plugin-contract/schema.json vendor/schema.json")
+  process.exit(1)
+}
+```
+
+**Naming your published package.** Follow `@rackbops/ac-plugin-<id>` (#105) — the same `@rackbops/`
+scope this whole family of packages uses (`ac-agent`, `ac-plugin-contract` itself), so
+`<id>` matches your manifest's own `acPlugin.id` and an operator installing it can tell at a glance
+what it's for.
+
+## The seven contribution points, in one place
+
+| Point | Declared in `contributes` | Supplied by |
+|---|---|---|
+| Panel | `panels[]` (`id`, `title`, `route`, `export`, `nav?`, `order?`) | a component export in `ui.js` |
+| Card | `cards[]` (`id`, `title`, `sizes`, `export`) | a component export in `ui.js` |
+| Action | `actions[]` (`id`, `scope`, `title?`, `confirm?`, `danger?`, `fields?`) | `host.actions.register({ id, run })` |
+| Job | `jobs[]` (`id`, `schedule`, `timeoutSec`, `runOn`) | `runJob(ctx)` dispatching on `ctx.jobId` |
+| Route | `routes[]` (`method`, `path`) | `host.routes.register(method, path, handler)` |
+| Setting | `settings[]` (`key`, `type`, `default?`) | read via `host.settings.get/set` |
+| Attention | `attention: true` | `host.routes.register("GET", "/attention", handler)` -> `{ ok: true, items }` |
+
+**Panel order (#472).** The tab strip, the narrow-screen nav drawer and the quickcast panel list all show
+panels in one order, which the host resolves per request: `GET /api/plugins` stamps every panel with an
+integer `rank` and the shell only sorts by it. The rule, in priority order:
+
+1. panels named in the operator's **`tab_order`** host setting -- a comma-separated list of panel ids, edited
+   in Admin > Settings (or set with `AC_TAB_ORDER`), applied on the next page load -- in the order listed; an
+   id that names no loaded panel is ignored, never an error. (A panel `id` has no fixed grammar, but the
+   setting cannot name one that contains a space or a comma, so pick panel ids without them);
+2. then panels whose manifest declares **`order`** -- an optional finite number on the panel, lower first --
+   with a `bundled` plugin's panel always ahead of an `installed` plugin's, so a third-party package
+   declaring `order: -1` cannot jump ahead of the bundled ordered panels (it does still precede every panel
+   that declares no `order`);
+3. then every other panel, by plugin directory name and then declaration order (where every panel sat
+   before `order` existed).
+
+Ties break the same way, so the order is total. `order` is a hint the operator can always override with
+`tab_order`, so leave it off unless your panel belongs at the front (the Board declares `10`, Issues `20`,
+which puts them right after Home). `Home` is always first and is not orderable. A panel that lost a
+contested nav slot still has no tab, and still appears in quickcast at its ranked position.
+
+A card never renders its own heading -- the wrapper supplies it from the manifest `title`
+(`HomeCards.tsx`'s `PluginCard`, `<Card><h3>{title}</h3>...</Card>`); a card rendering one of its
+own duplicates it on screen (#399).
+
+Two more fields exist on `Contributes` (`packages/contract/src/manifest.ts`) but aren't live
+contribution points yet: **`themes`** (`ThemeContribution: {id, title?}`) is schema-declared with no
+host-side reader at all -- validates, but nothing consumes it. **`provides`/`consumes`**
+(`SlotRef: {slot, version}`) ARE live and load-bearing, but for a different kind of plugin than this
+guide's worked example: a slot (`issues@1`, `artifacts@1`, `auth@1`, `notify@1`) is a
+named/versioned TypeScript interface one plugin **provides** and others **consume** -- the host
+refuses to activate a consumer whose slot has no provider, and says why (`resolveSlots`,
+`packages/host/src/plugins/slots.ts`, re-exported from `plugins/index.ts`). `ac-auth-cf-access`
+(`auth@1`) and `ac-notify-discord` (`notify@1`) are the reference *providers*; see their own
+`src/server.ts` for `host.slots.provide(slot, version, impl)`, and `design.md` §4 for the slot
+contract itself. `hello` contributes none of the six points above via a slot (nor `attention` -- its own manifest
+declares panels/cards/actions/jobs/routes/settings only, matching the intro above) -- it's the
+reference for those six, not for slot provision or the attention rail; `plugins/scans` and
+`plugins/overview` are the worked examples for `contributes.attention` (§8 above).