<!-- pane skill v0.0.31 -->

pane

pane is a CLI for the Pane relay: a round-trip UI channel between agents and humans. You render an HTML UI, the relay hands the human a URL, the human's interactions come back to you as structured events.

When to use this

Use pane when the human's answer is genuinely too rich for text — a form to fill, options to rank, a document to mark up, a dashboard to act on. For a plain question, just ask in text; pane only wins on the rich slice.

<!-- pane:core:start -->

Events or records — pick the primitive first

Pane has two data primitives. Pick before you design the schema or write HTML; they shape the page totally differently.

• Event = an append-only journaled fact ("this happened"). One-shot

interactions: form submission, approval, survey answer, picker, doc review.

• Record = a row in a mutable, queryable collection ("this exists, here is

its current value"). Multi-item applications: todo list, shopping list, checklist, packing list, expense log, inventory, kanban board, comment thread.

Tiebreaker. If there is more than one mutable item on screen and the current state matters more than the history of edits, default to records. The first thing a developer or agent tries (a todo list, a shopping list, a checklist) is almost always records — not events.

Full records reference (schema, page-side API, conflicts, CLI) is in Records further down. Read it before designing the schema, not after.

Page-side API at a glance

Inside the iframe, window.pane has these surfaces. Skim once so you don't invent things that don't exist or miss things that do.

Each surface is documented in detail further down (The schema, Records, Attachments). Use this table as the index, not as the spec.

<!-- pane:core:end -->

Setup

The hosted relay (https://relay.paneui.com) is the default — pane agent register works out of the box. The CLI needs:

• An agent API key. Either pre-provided by the operator (as

PANE_API_KEY), or obtained yourself via pane agent register (see "Registering" below). Once registered, the key is saved to the config file and you don't need PANE_API_KEY at all.

• A relay URL. Only relevant for self-hosters — set PANE_URL (or pass

--url) to point at a non-hosted relay.

Output is JSON on stdout. Errors are {"error":{"code","message"}} on stderr with a non-zero exit.

Keeping this skill up to date

This skill carries its version in an HTML comment near the top of the file:

<!-- pane skill vX.Y.Z -->

The skill version is the pane package version (@paneui/relay, @paneui/cli, @paneui/core — all kept in lockstep by the release script). scripts/cut-release.sh updates this comment alongside the package.jsons and the CLI's VERSION constant, so every release bumps the skill version even if the SKILL.md content didn't change. That keeps "what relay am I talking to" and "what skill do I have" answered by one number.

The relay you talk to publishes its own version of this skill at GET /skills/pane/SKILL.md/version. At conversation start, check whether your local copy is behind, and if so refresh it.

The check is a short shell snippet:

LOCAL_VER=$(grep -m1 -oE '<!-- pane skill v[0-9]+\.[0-9]+\.[0-9]+' <path-to-your-local-skill> | grep -oE '[0-9]+\.[0-9]+\.[0-9]+$')
REMOTE_VER=$(pane skill version --plain)
# If the relay is on an old image that lacks a version comment, the probe
# returns "0.0.0". Don't clobber a newer local copy with the older relay
# skill — skip the update and proceed with what's local.
if [ "$REMOTE_VER" = "0.0.0" ]; then
  : # nothing to do
elif [ "$LOCAL_VER" != "$REMOTE_VER" ]; then
  pane skill show > <path-to-your-local-skill>   # overwrites with the relay's current skill
fi

Where <path-to-your-local-skill> is wherever YOUR runtime stores the pane skill (e.g. ~/.claude/skills/pane/SKILL.md for Claude Code, ~/.cursor/rules/pane.mdc for Cursor, the relevant section of ~/.codex/AGENTS.md for Codex / Gemini-style concatenated files).

The two greps above are intentionally strict:

• -m1 stops at the first match in the file, so prose mentions of the

pattern (this very section!) don't double-count.

• [0-9]+\.[0-9]+\.[0-9]+ only matches a real semver triple, so a

literal <!-- pane skill vX.Y.Z --> in documentation is skipped.

The strict matcher does NOT accept prerelease tags (e.g. 1.0.0-rc1). If we ever ship those, both this snippet and the relay's parser need a matching update.

Rules:

• If the local file has no <!-- pane skill v... --> comment, treat it as

stale and run pane skill show > <path>.

• If REMOTE_VER is 0.0.0, skip the update — the relay is on an old

image without a version comment, and clobbering your (presumably newer) local copy with that would be a downgrade. The snippet above guards this; if you're rolling your own check, do the same.

• If the network is unreachable or pane skill version fails, **do not

update** — proceed with the local skill you have. Skipping a check is always safer than half-writing the file.

• Don't loop. Check once at conversation start; if you've already refreshed in

this run and it's still mismatched, stop and pane the error to the human.

• If you've hand-edited the local skill (added your own notes), save your

changes first — pane skill show > <path> is a clobbering write.

Discover the CLI with --help

Before using a command, run its help. This skill summarizes the workflow, but --help is the authoritative, always-current reference for every flag, argument, and default:

• pane --help — the command list and global options.
• pane <command> --help — every flag and option for that command, e.g.

pane create --help, pane watch --help, pane send --help, pane agent register --help.

If a command errors or you are unsure of an option name, run `--help` instead of guessing — the CLI is self-documenting and the help text reflects the installed version, which this skill may not.

If pane exits 75 ("CLI upgrade required")

The relay you're talking to needs a newer @paneui/cli than you have installed. The CLI signals this with exit code 75 (EX_TEMPFAIL) and a stderr message that starts with pane: this relay requires @paneui/cli >= <version>. If that message includes a To upgrade: <command> line, the command is correct for how pane was installed on this machine — there's nothing to guess.

What to do, in this order:

1. Run the printed upgrade command once. If no command is printed (the

message says "vendored" or "unknown" install), stop and ask the human to bump @paneui/cli — don't try to install one yourself.

1. Re-run your original `pane` command once. If it succeeds, continue.
2. If it still fails with exit 75 after one upgrade + retry, stop and

pane the error to the human. Do not loop — repeated upgrade attempts in the same run are a bug, not a recovery strategy.

Registering

If you weren't handed an API key, provision one yourself — once — with:

pane agent register --name "<short-descriptive-agent-name>"

Pick a stable, descriptive name — it's how a human tells your agent apart from other agents on the relay (e.g. claude-code-lalit-macbook, ci-pr-review-bot, telegram-helper). The relay defaults the name if omitted, but the default is unhelpful; always set one.

Self-hosters add --url "$PANE_URL" (or set PANE_URL) to target a non-hosted relay.

Whether pane agent register works depends on the relay's REGISTRATION_MODE:

• closed (the default) — the endpoint returns 404. The operator must hand

you a key directly; self-registration is disabled.

• secret — pass the operator-shared registration secret with --secret <s>

or the PANE_REGISTER_SECRET env var. A missing/wrong secret is a 401.

• open (the hosted relay's mode) — public; pane agent register --name <name>

works with no secret.

On success this calls the relay's POST /v1/register, mints an agent + API key, and saves the key and relay URL to the CLI config file (${XDG_CONFIG_HOME:-~/.config}/pane/config.json, mode 0600). After that, every other command picks the key up from that file automatically — no env vars needed.

• The key is not printed by default. Pass --print-key if you need it echoed.
• Run it just once; re-running mints a fresh agent each time.
• The relay rate-limits /v1/register per IP; if you hit it, pane agent register

fails with rate_limited — wait and retry.

Templates and panes — the model

A template is a reusable UI template: the HTML, an optional event schema, and an optional input schema. A pane is one _use_ of a template — one context, one human, one event log, one TTL. Many panes per template.

A pane is pinned to the template version it was created with. To change a live pane's design or content, you don't edit the running pane — you append a new template version and re-pin the pane to it with pane upgrade (see the pane upgrade command below); the human keeps the same URL.

The reusable template is the unit you should think in. Start every task with `pane template list` (or pane template search <keywords>) to see what already exists — a previous run may have authored exactly the UI you need. The intended flow is: author a template once with pane template create, then instance it many times with pane create --template-id <slug> — no HTML re-sent, no regeneration. Per-instance data (the "PR metadata" that makes the same PR-review page show _this_ PR) rides in --input-data; the page reads it as window.pane.inputData.

There are two ways to give pane create a template:

• By reference — --template-id <id|slug> — instance an existing reusable

template. The reuse path, and the one you should reach for first.

• Inline — --template <path|inline> — a one-off UI, defined on the call.

The relay creates an anonymous template behind it. Use the inline form for a one-off — a UI you won't reuse across panes; anything reusable belongs in pane template create. You don't manage that anonymous template directly, but you are not locked out of editing the pane's HTML later: pane upgrade <pane-id> --template <new-html> edits an inline pane's HTML in place, same URL, in one call (see pane upgrade). So "I made it inline, now I can't change it" is false — reach for pane upgrade --template.

Search before you generate — the load-bearing rule

Before you generate any template HTML, search for one that already exists.

pane template search <keywords>     # e.g. pane template search "pr review"
pane template list                  # all your templates, recent first

You are ephemeral; the relay is durable. A previous run of yours (or this agent on another run) may have already authored exactly the template you are about to build — a PR-review page, an approval form, a survey. Regenerating it from scratch wastes tokens and causes drift: ten separately-generated copies of "the same" page will not stay the same. The template on the relay is the one source of truth.

So the workflow is:

1. pane template search <keywords> — does a suitable template already exist?
2. If yes — use it: pane create --template-id <id|slug> (optionally

--input-data for this instance's data). Inspect it first with pane template show <id|slug> — the description and each version's input_schema tell you what it does and what data it needs. Done — no HTML written.

1. If nothing fits — only then author. If the UI is genuinely a one-off,

use the inline pane create --template ... form. If it is something you (or the operator) will want again, register it: pane template create — so the next run can find and reuse it.

A reusable template is only reusable if you look for it. Skipping the search makes the whole feature dead weight.

…and name what you author

The flip side: search only works on metadata you populate when you author. When you call pane template create, every metadata field is optional, but each one you skip is a future search query that comes back empty.

Populate, even briefly:

• `--name` — human-readable label. "PR Review", not "Form 1".
• `--slug` — a short, durable kebab-case handle. Record it; you (or any

future run) can later use pane create --template-id <slug> with no search at all. Without a slug, the only handle is the relay-assigned id — which is not memorable and not stable in your prompt context.

• `--description` — what a future you reads to decide "is this the one I

want?" before fetching the HTML. Cover three things: what the template is for, what the human can do on it (which events it emits), and what input_data shape it expects. As long as that fits, length doesn't matter — overly terse here costs every future reader, overly long here costs nothing.

• `--tags` — a few short keywords. They do double duty: they make

pane template search "review" / … "code" find the template, and every pane created from it inherits them as filter tags, so the human can slice their Panes tab by tag (e.g. show only livia panes). See "Tagging panes" below — tag your reusable templates so the panes they spawn are filterable.

• `--input-schema` — optional JSON Schema for the input_data the

template expects. Doubles as documentation: a future you reads it to know exactly what shape of data to pass at pane create time.

None of these are required by the relay. All of them are required if you want this template to be findable later. Treat them as a one-time author's tax that pays back every reuse.

Heuristic for when to bother:

• One-off shape (a custom approval for this specific deploy, a survey

you're handing out once) → use the inline pane create --template … form, skip the metadata.

• Reusable shape (a PR review page, a deploy approval, a generic survey

template) → pane template create with --name, --slug, --description, --tags populated. The tokens you save are your next pane's.

The commands

pane create — start a pane

Reference an existing template (the reuse path — see "Search before you generate" above):

pane create --template-id pr-review --input-data ./pr-42.json --ttl 600

Or inline a one-off template:

pane create --template ./form.html --name "Quick poll" \
  --event-schema ./schema.json --title "Quick poll" --ttl 600

• --name <text> — required for the inline form (--template). It names

the template the relay auto-creates behind the inline pane so it shows a readable label in the owner UI instead of a random-looking id. Rejected with --template-id (the reference form inherits the existing template's name).

• --slug <text> — optional inline-form slug; must be unique among your

templates. Rejected with --template-id.

• --title <text> — the human's browser tab title for this pane (max 80

chars, single line). Set a descriptive, per-pane value so a human with several panes open can tell tabs apart. Optional: when omitted the relay falls back to the template's name — the existing name for the reference form, or the --name you pass for the inline form.

• --template-id <v> — reference an existing template by id or slug. Pair with

--version <n> to pin a specific version (defaults to the latest).

• --template <v> — inline HTML UI: a file path, or inline HTML. Pair with

--name (required). (A remote-URL type, html-ref, exists in the schema but the relay does not serve it in this release — pass the HTML inline.)

• --event-schema <v> — the event vocabulary (see The schema below). A .json

file or inline JSON. Used with --template; not needed with --template-id. Optional — omit it for a view-only template (see View-only templates below); the pane then accepts no page/agent events.

• --input-schema <v> — inline-form input schema. JSON Schema for --input-data,

as a .json file or inline JSON. Used with --template; rejected with `--template-id` (the schema comes from the pinned template version there). Optional. Pass it whenever `--input-data` carries `attachment_id`s the page needs to render — the participant attachment-download bridge walks input_data against the template version's inputSchema for "format": "pane-attachment-id" sites, and an attachment without a walkable site is unreachable from the page even when the agent owns it.

• --input-data <v> — this instance's seed data, a JSON object (file or inline

JSON). The relay validates it against the template version's input_schema; the page reads it as window.pane.inputData. Works with either form.

• Exactly one of --template-id / --template must be given.
• Optional: --ttl <seconds>, --participants <n>, --metadata <path|json>,

--callback <path|json>.

Prints { pane_id, urls, tokens, expires_at }. Deliver `urls.humans[0]` to the human over whatever channel you already have (Telegram, Slack, email). Keep pane_id. tokens are per-participant auth already baked into the urls — you don't normally use them directly; the CLI authenticates with PANE_API_KEY.

#### Tagging panes (so the human can filter them)

A pane carries filter tags — the human's Panes tab has a tag-chip filter (All · ★ Favorites · your tags), so good tags let them slice hundreds of panes down to "the livia ones" or "PR reviews for cp-backend". Tag deliberately.

A pane's tags are snapshotted at create time as the union of two sources:

• Template tags (pane template create --tags …) — inherited by every pane

the template spawns. This is the main axis ("what kind": pr-review, standup). A template is never left untagged: with no --tags it falls back to the --slug, and with neither it falls back to a tag derived from the template name (kebab-cased) — so every pane is at least filterable. Still, prefer explicit --tags: a name-derived tag is a coarse last resort.

• Per-pane tags (pane create --tags …) — an instance-specific axis layered

on top. The classic case: one pr-review template used across repos, with the repo per pane:

  pane create --template-id pr-review --tags cp-backend   # → tags: pr-review, cp-backend
  pane create --template-id pr-review --tags aambackend   # → tags: pr-review, aambackend

The human can then filter to pr-review + cp-backend (AND) to see exactly PR reviews for that repo.

Rules: each tag ≤50 chars, ≤20 per pane; favorite/favorites are reserved (favoriting is the human's per-human star, not a tag). The human can also add/remove a pane's tags themselves from the Panes tab — so tagging is a best-effort signal, not a contract, but tag well and they won't have to.

pane template — manage reusable templates

pane template <subcommand> — one command, several subcommands:

# search / list — find an existing template before generating one
pane template search "pr review"
pane template list

# show — full template: head metadata + every version (HTML, schemas)
pane template show pr-review

# create — register a named, reusable template (its v1)
pane template create --name "PR Review" --slug pr-review \
  --description "PR review page: diff + approve/request-changes" \
  --tags pr,review,code \
  --template ./pr-review.html --event-schema ./pr-review-schema.json \
  --input-schema ./pr-review-input.json
#   -> prints { template_id, slug, version }

# version — append a new immutable version (existing versions never change)
pane template version pr-review --template ./pr-review-v2.html \
  --event-schema ./pr-review-schema.json

# update — change head metadata only (never the content)
pane template update pr-review --description "..." --tags pr,review

• search/list return a lean list — `id, slug, name, description, tags,

latest_version, last_used_at — no HTML. Fetch the HTML with show` once you have chosen one.

• The slug is the durable handle: record it (pr-review) and later

pane create --template-id pr-review with no search at all.

• --input-schema is optional JSON Schema describing the input_data the

template needs. It doubles as documentation — it tells a future you exactly what data to pass.

• Editing a template appends a version; it never mutates an existing one.

Panes pin the version they were created with, so old panes are unaffected by a new version.

<!-- pane:core:start -->

The schema

The schema is the contract for _every_ event on the pane. The relay rejects any event that violates it — a wrong data shape, or the wrong author. Get this right or the round trip silently fails.

Each entry under events declares:

• payload — a JSON Schema for the event's data. {} means "any

object". Be as strict as you can: the relay validates pane.emit(...) / pane send data against it and rejects mismatches.

• emittedBy — who may emit this type: "page" (the human's UI, via the

pane.emit bridge) and/or "agent" (you, via pane send). Emitting a type your side isn't listed in fails with author_not_allowed.

{
  "events": {
    "form.submitted": {
      "payload": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "rating": { "type": "integer" }
        },
        "required": ["name", "rating"]
      },
      "emittedBy": ["page"]
    },
    "assistant.reply": {
      "payload": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "message": { "type": "string" }
        },
        "required": ["title", "message"]
      },
      "emittedBy": ["agent"]
    }
  }
}

Standards-aligned shape (x-pane-events) — recommended for new templates (#300)

The legacy shape above stays supported. New templates should prefer the standards-aligned form, which mirrors the x-pane-collections extension used for recordSchema: a JSON Schema 2020-12 document with one namespaced extension. Same vocabulary an agent already knows from records, so you only learn one convention across both event and record schemas.

$schema: "https://json-schema.org/draft/2020-12/schema"

$defs:
  ReviewSubmitted:
    type: object
    properties:
      rating: { type: integer, minimum: 1, maximum: 5 }
      message: { type: string, maxLength: 4000 }
    required: [rating]
  AssistantReply:
    type: object
    properties:
      title:   { type: string }
      message: { type: string }
    required: [title, message]

x-pane-events:
  review.submitted:
    payload: { $ref: "#/$defs/ReviewSubmitted" }
    emit:    [page]               # subset of {agent, page}
  assistant.reply:
    payload: { $ref: "#/$defs/AssistantReply" }
    emit:    [agent]

Mapping from the legacy shape:

Both shapes normalize to the same internal representation at validation time, so every downstream pane (events route, WS replay, schema-compat) behaves identically. The relay rejects a document that mixes both — pick one per template.

Inline payloads (no $ref) are accepted in the new shape too for terse single-use schemas; $defs only earns its keep when two events share a payload type or a template has many events.

View-only templates (reports, dashboards, charts)

The event schema is optional. A template created with no --event-schema is view-only: a report, dashboard, or chart the human only _reads_ — there is nothing to submit back.

• Omit --event-schema on pane create --template ... or pane template create to

make a view-only template. The CLI sends no event schema.

• A view-only pane declares an empty event vocabulary, strictly enforced.

Every page/agent emit is rejected 422 unknown_event_type — pane.emit in the page and pane send from the agent both fail. There is no event type the pane will accept.

• A view-only template can still carry an --input-schema and be seeded per

pane with --input-data — that is how one report template renders many different reports. The input contract is independent of the event schema.

• Use this for anything the human only consumes: a status dashboard, a metrics

chart, a generated report. If you need an answer back, give the template an event schema instead.

Writing the template

The template is the HTML page the human sees. It does not run like a normal web page — the relay serves it inside a locked-down sandboxed iframe with no network access. Ordinary <form action>, fetch(), or XMLHttpRequest will not work and the human's answer will never reach you.

Instead, the relay injects a global window.pane bridge. The template talks to the pane _only_ through it:

• pane.emit(type, data?, opts?) → Promise<{ id, deduped }> — send an event.

type must exist in the schema with "page" in emittedBy; data must satisfy its payload. This is how the human's answer reaches you.

• pane.on(type, handler) → unsubscribe — react to events (e.g. an

assistant.reply you sent via pane send).

• pane.state — .events (the log so far), .last(type?), .subscribe(fn).
• pane.inputData — this pane's per-instance seed data: the input_data

passed to POST /v1/panes, validated by the relay against the template version's input_schema. Read it to render this instance — e.g. a PR-review template does window.pane.inputData.prTitle. It is `null` until the shell delivers the init frame, so `await window.pane.ready` before reading it on first paint — a synchronous read at top-of-script runs before init lands and sees null, so an agent-init template would fall into its empty state forever. It is also null when the pane was created without input_data.

• pane.uploadBlob(file, opts?) / pane.downloadBlob(attachment_id) /

pane.saveBlob(attachment_id, filename?) — attachment plumbing. Method names still carry the legacy "Blob" suffix from before the Session→Pane, Artifact→Template, Blob→Attachment rename — every other pane (CLI nouns, JSON fields, schema format) uses "attachment", but these three methods kept their old names for runtime compatibility. They return / accept AttachmentRef objects with attachment_id, mime, size, etc. See the "Human file uploads" and "Lazy image fetch" sections below.

What a handler receives — the event envelope

pane.on(type, handler) calls handler(ev) with one argument: the event envelope, _not_ the bare payload. The envelope shape is:

{
  (id, pane_id, author, ts, type, data, causation_id, idempotency_key);
}

The payload — the object you passed to pane.emit(...) or to pane send --data — is in `ev.data`. So an event sent with pane send --type assistant.reply --data '{"title":"...","message":"..."}' arrives at the handler as ev, and the content is ev.data.title / ev.data.message.

Two things to know:

• Handlers also fire for replayed history. When the iframe connects, every

prior event is replayed through your pane.on handlers — including events sent _before_ the template loaded. A handler registered in an inline <script> still receives an assistant.reply that was sent earlier, so you don't need to race the agent.

• pane.state.last(type) returns the most recent envelope of that type (or the

most recent of any type if you omit type) — use it to render "whatever the latest reply is" without wiring a handler.

A minimal working template for the schema above:

<!doctype html>
<meta charset="utf-8" />
<style>
  #reply-msg {
    white-space: pre-wrap;
  }
</style>
<!--
  Note: the template runs in a sandboxed iframe. The relay grants `allow-forms`
  alongside `allow-scripts` so a real <form> + Enter-to-submit works, but the
  iframe has no `allow-same-origin`, so a form's *native* submission can't
  reach any origin anyway. Either pattern is fine — we use a plain
  <button type="button"> + click handler below so the example doesn't depend
  on form-submission semantics at all.
-->
<div id="f">
  <input id="name" placeholder="Your name" required />
  <input id="rating" type="number" min="1" max="5" required />
  <button type="button" id="submit">Submit</button>
</div>
<p id="status"></p>

<!-- The agent's reply renders here -->
<section id="reply" hidden>
  <h2 id="reply-title"></h2>
  <p id="reply-msg"></p>
</section>

<script>
  // The agent pushes a rich reply with
  //   pane send --type assistant.reply --data '{"title":"…","message":"…"}'
  // `ev` is the envelope; the payload is `ev.data`.
  pane.on("assistant.reply", (ev) => {
    const { title, message } = ev.data;
    // .textContent — never .innerHTML — so agent text can't inject markup.
    document.getElementById("reply-title").textContent = title;
    // `white-space: pre-wrap` (above) keeps `\n` in `message` as line breaks.
    document.getElementById("reply-msg").textContent = message;
    document.getElementById("reply").hidden = false;
  });

  document.getElementById("submit").addEventListener("click", async () => {
    const name = document.getElementById("name").value;
    const rating = Number(document.getElementById("rating").value);
    // Basic validation — the sandbox doesn't give us native form validation
    // here because we're not using <form>'s submit pipeline.
    if (!name || !(rating >= 1 && rating <= 5)) return;
    // Emit the terminal event — this is what `pane watch --type` waits for.
    // Await it: pane.emit resolves only once the relay has accepted the
    // event, and rejects if delivery fails. Only show "Sent" after that.
    await pane.emit("form.submitted", { name, rating });
    document.getElementById("status").textContent = "Sent — thank you.";
  });
</script>

DON'T render the raw envelope. Never JSON.stringify(ev) (or ev.data) onto the page, and never use the envelope as a fallback display when a handler isn't sure what to do. If a handler doesn't recognize an event, ignore it — the page should only ever show specific ev.data fields it understands, rendered into real DOM. The whole point of Pane is a proper UI; a JSON dump is a bug.

Rules of thumb when authoring the template:

• The event type you pane.emit for the human's final action must match

the --type you later pane watch for. Above: form.submitted.

• A handler's argument is the envelope — read the payload from ev.data,

and render its individual fields with .textContent into real elements.

• window.pane is published synchronously, so pane.emit and pane.on

work the moment your inline <script> runs, and pane.on handlers replay prior events once the init frame lands. But `pane.inputData` (and the replayed history) are not available until that init frame arrives — if your first paint reads inputData synchronously, await window.pane.ready first or it races to null.

• No external assets that need the network (CDN scripts, remote fonts/images):

the sandbox CSP blocks them. Inline everything, or use data URIs.

• Keep the template self-contained — it's one HTML document.

House style — don't hardcode colors, build on the injected theme

The relay injects a default stylesheet into every pane before your markup — pane's brand look (warm-paper background, coral accent) that is already both light- and dark-mode aware via prefers-color-scheme. Plain semantic HTML (<h2>, <table>, <label>, <input>, <button>, <fieldset>…) renders on-brand with zero CSS from you. The default path is therefore: write semantic HTML and let it inherit. Only add CSS for layout/bespoke components — and when you do, build on the injected CSS variables, never hardcode colors, backgrounds, or fonts. Hardcoded values break dark mode and drift off-brand.

The variables (set on :root, with a prefers-color-scheme: dark variant — so referencing them is automatically theme-correct):

GOOD — a custom card that stays brand- and theme-correct for free:

.card {
  background: var(--pane-subtle);
  color: var(--pane-fg);
  border: 1px solid var(--pane-border);
  border-radius: var(--pane-radius);
  padding: 16px;
}
.card .meta { color: var(--pane-muted); }
.card .cta { background: var(--pane-accent); color: #fff; }

AVOID — hardcoded values. LLMs habitually default to a dark "dashboard" look (`#0d1117`, `#111`, neon accents). Don't. It ignores the human's actual theme, fails in light mode, and clashes with pane's brand:

/* ✗ breaks light mode, off-brand, ignores the human's preference */
body { background: #0d1117; color: #e6edf3; }
.card { background: #161b22; border: 1px solid #30363d; }
.cta { background: #238636; }

Rules of thumb:

• Both themes are non-negotiable. Anything you author must read correctly in

light and dark. Using the variables gets you this automatically; if you set a literal color anywhere, you now own making it work in both — usually not worth it.

• Check `pane taste` first. Before authoring, run pane taste get — if the

human has recorded presentation preferences ("always dark", "denser tables", "purple accents"), those override this default guidance. When the human gives presentation feedback, persist it with pane taste set. See the pane taste section for the full loop.

• Escape hatch — `data-pane-bare`. Put the literal string data-pane-bare

anywhere in your HTML (e.g. <html data-pane-bare>) and the relay skips the default-sheet injection entirely — you own 100% of the styling. Use it only when the human explicitly asked for a fully bespoke theme (or taste says so). Once bare, the --pane-* variables no longer exist, so you must define every color yourself — including a dark-mode path.

<!-- pane:core:end -->

pane watch <id> — wait for the answer

pane watch holds a WebSocket and prints one compact JSON object per line to stdout, flushing after each. This is the key command — it's how you wait for the human.

pane watch pan_xxxx --type form.submitted

• --type <t[,t2,…]> — exit 0 after the first event whose type is in this

comma-separated set. Use this to wait for the human's terminal action. Pass multiple types when you want to exit on any of several outcomes (e.g. --type form.submitted,form.cancelled).

• --filter-type <t[,t2,…]> — restrict the STDOUT stream to events whose

type is in this set. system.* events (participant joined, pane expired) and the terminal _closed line always pass through so the harness still sees lifecycle signals. --type controls the EXIT condition; --filter-type controls the OUTPUT. Combine them (--type X --filter-type X) for "stream only X events and exit on the first one".

• --once — exit 0 after the very first event.
• --timeout <seconds> — wall-clock max wait. Exits with code ws_timeout

if the awaited terminal condition (--once, --type, pane close) hasn't happened by then. Frames arriving do NOT reset the timer — this is the budget for "give up on the human", not an idle detector. Use it so you don't wait forever for a human who never acts.

• bare — stream until interrupted (SIGINT).

Outcomes — branch on these:

• An event of your --type lands → its JSON line is printed, exit 0. The

human answered; act on the event's data.

• The pane expires or closes first → a final {"type":"_closed"} line is

printed, exit 0. The human did not answer (TTL elapsed). Do not treat a _closed line as the answer — handle it as "no response".

• --timeout elapses → {"error":{"code":"ws_timeout"}} on stderr, non-zero

exit.

• The relay drops the connection abnormally → ws_closed_abnormally on

stderr, non-zero exit (distinct from a clean _closed).

pane show <id> — snapshot, optionally long-polled

pane show pan_xxxx                          # snapshot, returns immediately
pane show pan_xxxx --since <next_cursor>    # only events past the cursor
pane show pan_xxxx --since <next_cursor> --wait 30

Prints { meta, events, next_cursor } without holding a WebSocket. Two modes:

• Default (non-blocking). Returns whatever exists right now. Use for

a one-off "is the pane still alive?" check.

• `--wait <secs>` (long-poll). The relay holds the request open for

up to that many seconds — capped server-side at 30 — and returns as soon as a new event arrives. Use this for headless polling agents that can't keep a WebSocket open (cron, FaaS, slow links): call, re-call with the previous next_cursor as --since, repeat. Higher latency per round-trip than pane watch but no long-lived connection.

Choose watch (streaming) when you can hold a process; choose show --wait (polling) when you can't.

pane send <id> — emit your own event

pane send pan_xxxx --type assistant.reply \
  --data '{"title":"Got it","message":"Thanks — your rating is recorded."}'

--data is a file path or inline JSON. The event type must exist in the schema with agent in its emittedBy. Use this to update the UI live while the human works.

pane delete <id> — close a pane

pane delete pan_xxxx

Closes the pane and tears it down (DELETE /v1/panes/:id). Idempotent — re-deleting an already-closed pane is a no-op. Use it to clean up a pane you are done with rather than waiting for its TTL to expire.

pane upgrade <id> — change a live pane's design + content in place (#267)

A pane is pinned to one template version for its whole life — pane create captures the latest version at creation time and never moves. So when a human asks you to "update this pane with a new design / new content", you do not edit the running pane's HTML directly in storage and you do not have to throw the pane away. There are two ways in, depending on the pane:

A. Inline pane → edit the HTML in one call (the common case). A pane created with inline HTML (pane create --template <html>) can have its HTML changed in place with a single command — the relay appends a fresh version and re-pins the pane to it atomically, same id/URL:

pane upgrade pan_xxxx --template ./v2.html          # just new HTML
pane upgrade pan_xxxx --template ./v2.html --event-schema ./v2-schema.json

Any schema you don't pass is inherited from the pane's current version, so to change only the HTML you pass only --template. This is the answer to "I made an inline pane and now want to tweak its HTML" — you do NOT need to rebuild it into a new pane, and you do NOT need a separate template version step. (The MCP upgrade_pane tool takes the same as an html arg.) Inline panes only.

B. Named/reusable template → version it, then re-pin. For a pane on a named template (created with pane template create + --template-id), the template is a shared asset, so its versions are managed explicitly:

1. Append a new template version:

   pane template version <id|slug> --template ./v2.html --event-schema ./v2-schema.json
   #   -> { template_id, version: 2 }

1. Re-pin the live pane to it — same pane, same URL:

   pane upgrade pan_xxxx                          # -> latest version
   pane upgrade pan_xxxx --template-version 2     # -> a specific version
   pane upgrade pan_xxxx --force                  # override the compat gate

Prints { pane_id, template_version_id, template_version, upgraded, breaks, compat }. upgraded:false means the pane was already on that version (idempotent no-op).

Either way swaps both the HTML (design) and the event/input/record schemas (content contract). It only moves a pane between versions of the same template — pointing it at a different template is conceptually a different pane, so create a new one for that.

The schema-compat gate. By default (strict) the relay refuses the upgrade with schema_incompatible_upgrade (a 422 whose details.breaks lists the offending paths) when the new version narrows the schema — a removed collection, a newly-required field, a tightened type — because events already written under the old schema would no longer validate. Adding optional fields, new collections, or loosening bounds is compatible and passes. Pass --force to apply a narrowing upgrade anyway, accepting that old events may no longer match. Events on disk are never rewritten — each keeps the version it was authored under (#268), so prior history still renders.

Live-reload caveat. The re-pin takes effect on the relay immediately and emits a system.template.updated event, but an already-open pane tab is not force-reloaded in this release — the new version renders the next time the URL is loaded. If the human is looking at the pane right now, ask them to refresh.

pane update <id> — edit instance-level fields in place (#502)

A pane's per-instance fields (TTL, title, preamble, input_data, metadata, tags, icon overrides) are set at pane create and are otherwise frozen for the pane's lifetime. pane update lifts that — PATCH /v1/panes/:id lets you edit any of them without minting a new pane. The pane keeps its id, URL, event log, and template pin; only the fields you pass change.

# Extend a live pane's TTL — same URL.
pane update pan_xxxx --ttl 31536000              # one year from now
pane update pan_xxxx --expires-at 2027-01-01T00:00:00Z

# Edit display fields.
pane update pan_xxxx --title "Renamed"
pane update pan_xxxx --preamble "Why this matters"
pane update pan_xxxx --tags repo:cp-backend,pr:42

# Replace input_data wholesale — revalidated against the pane's pinned
# template version's input_schema (same gate as create).
pane update pan_xxxx --input-data @./session.json

# Per-pane icon overrides — set or clear.
pane update pan_xxxx --icon-emoji 👶
pane update pan_xxxx --clear-icon-emoji

--ttl and --expires-at are mutually exclusive (both express the same intent). Both forms are clamped against the relay's MAX_TTL_SECONDS cap; exceeding it is rejected with invalid_request (not silently truncated) so the agent's sense of the lifetime matches the relay's.

--input-data is replaced wholesale (not merged) and revalidated against the pane's current template version's input_schema. Same attachment-access gate as create: any format: pane-attachment-id site in the new data must reference attachments accessible to the calling agent.

--tags is also replaced wholesale, then merged with the template's tags by the relay (template tags lead). favorite/favorites are reserved.

The relay appends a system.pane.updated system event listing the names of the fields that changed (no values, so the event stream stays PII-free). Already-open pane tabs do not auto-reload on PATCH in this release — same behaviour as pane upgrade. Use pane update when the human's URL must keep working; use pane create only when you need a new logical pane.

pane list — enumerate your panes

pane list                                  # default --status=open
pane list --status all
pane list --status closed --limit 100
pane list --template-id pane-pitch-deck    # filter by named template
pane list --cursor <opaque>                # next page

Lists your agent's panes, newest first. The response is intentionally LEAN: each row carries active_human_participants (a count of non-revoked human URLs on that pane) but NOT the full participant array — agents with many panes × many humans should not pay that bandwidth on every list call. To see the participants themselves (including revoked rows), call pane participant list <pane-id>.

The response also carries NO secrets: no participant tokens, no callback URL, no metadata or input_data.

Load-bearing caveat — participant tokens are unrecoverable. The relay stores only the hash of each participant token; the plaintext URL is returned exactly once in the pane create response and cannot be retrieved later. If you lost a URL, neither pane list nor pane participant list will return it; instead, use pane participant new to mint a fresh URL on the still-alive pane.

pane participant list|new|revoke — manage URLs on a live pane

# Find the participant ids on one pane.
pane participant list pan_abc123

# Lost the URL but the pane is still alive — mint a new entry door.
pane participant new pan_abc123 | tee -a ~/.pane-urls.jsonl

# Invalidate a URL you no longer want usable.
pane participant revoke pan_abc123 p_xyz

Three primitives that together replace pane delete + pane create for the lost-URL case (which would destroy the pane's event log, template pin, and created_at — participant new preserves all of that).

• pane participant list <pane-id> — returns the full

participant array for one pane (active AND revoked rows). Each row has participant_id (the revoke handle), kind, token_prefix (non-secret correlator like tok_h_BUcx), joined_at, and revoked_at. This is the step you use to find a participant_id to pass to revoke.

• pane participant new <pane-id> — mints a fresh human URL on

an existing pane. Returns { participant_id, kind, token, url, created_at } exactly ONCE. Save the response (pipe to a JSONL log) before delivering the URL.

• pane participant revoke <pane-id> <participant-id> —

invalidates one URL. The pane's other URLs (and your own websocket) are untouched. Idempotent: running revoke twice still returns success. Caveat: in this version, existing WebSocket connections held under the revoked token are NOT actively kicked; only new HTTP and WS connections under that token fail.

Recovery recipe when you dropped the create response:

pane list                                          # find pane_id
pane participant list pan_abc123                   # find participant
                                                           #   ids on that
                                                           #   pane
pane participant new pan_abc123 | tee -a ~/.pane-urls.jsonl
# use the new url; the old one is still valid until you revoke
pane participant revoke pan_abc123 p_xyz           # optional —
                                                           #   invalidate
                                                           #   the old URL

pane config — inspect the resolved config

pane config

Prints the relay URL and API-key prefix the CLI is currently using, where each came from (flag / env / store), and the config-file path. Makes no network call. The full API key is never printed — only a masked prefix. Run it when a command fails with config_error to see what is actually set.

pane agent logout — clear the saved credentials

pane agent logout

Deletes the locally-saved relay URL + API key from the CLI config file. This is local only — it does not revoke the key on the relay; the key still works if used again. To actually revoke the key, use pane key revoke.

pane key — inspect or revoke your API key

pane key list                 # show your agent's key info (one key per agent)
pane key revoke --yes         # REVOKE your own key — a self-destruct

A pane agent has exactly one API key. keys list shows its metadata (key_prefix, created/last-used, etc.) — never the full key. keys revoke permanently revokes your own key; it stops working immediately and you would have to pane agent register again. It refuses to run without --yes.

pane taste — remembering UI preferences across runs

pane taste get                              # read current notes (JSON)
echo "- denser tables\n- no rounded corners" | pane taste set
pane taste set --file ./taste.md            # read from a file instead of stdin
pane taste clear --yes                      # forget everything

taste is a small markdown blob — your agent's accumulated presentation taste: how the human you serve likes panes to look. The intended loop is:

1. Before generating a template, run pane taste get and fold the

taste field into the prompt that authors the HTML. Past feedback ("dark header", "no emoji", "tighter spacing") shapes the new template.

1. When the human gives presentation feedback, run pane taste get,

merge the new guidance into the existing notes in your prompt, then write the WHOLE updated blob back with pane taste set. Don't append blindly — taste set is whole-blob replace on purpose, so the notes stay curated and don't rot into a transcript.

1. Keep entries about presentation only — colours, density, component

choices, layout. Project context, todos, and per-run state belong somewhere else (your own memory, the pane's events, etc.).

Keyed today by the calling agent's API key — per-agent, not per-human (pane v1 has no first-class human identity yet). Expect this to move to per-human later; the CLI pane won't change.

pane feedback — product feedback to pane's maintainers

pane feedback create --type bug --message "watch dropped at 30s"
echo "long note" | pane feedback create --type note --message -
pane feedback list

Bugs, feature requests, or notes about pane itself (CLI, relay, docs, this skill) — not about the human's task.

Prefer GitHub Issues at github.com/aerolalit/paneui for bugs and features — that's the maintainers' primary triage. Use pane feedback only when you can't reach GitHub in this run (no gh, no auth, headless). Notes are fine to send directly.

--type ∈ {bug, feature, note}. --message - reads stdin. --pane-id is optional. No reply channel — don't use this for anything you need an answer to, or for the human's answer to a pane question (use events). UI preferences belong in pane taste, not here.

pane attachment — binary attachments (images, PDFs, audio, video)

# Upload a file. Default scope is "agent" (reusable across the agent's panes).
pane attachment upload --file ./chart.png

# Pane-scope (dies with the pane; cheaper to GC):
pane attachment upload --file ./hero.jpg --scope pane --pane-id pan_xxx

# Template-scope (reusable across every pane using the template):
pane attachment upload --file ./icon.svg --scope template --template-id <id>

# List your blobs (newest first; paginated via --cursor):
pane attachment list                              # first 50
pane attachment list --limit 25 --cursor <opaque> # next page

# Inspect / download / delete:
pane attachment show <blob_id>
pane attachment download <blob_id> --out ./out.png
pane attachment delete <blob_id>

# Mint a /b/<token> URL the human can fetch directly (no agent API key):
pane attachment token mint <blob_id>              # default TTL: 24h agent / pane-TTL / 30d template
pane attachment token mint <blob_id> --once       # self-deletes on first GET

# Enumerate the tokens minted against one attachment (audit — includes revoked rows):
pane attachment token list <blob_id>

# Revoke a token (incident response — see docs/RUNBOOK-LEAKED-TOKEN.md):
pane attachment token revoke <blob_id> <token_id>

Token TTL vs pane TTL. A /b/<token> URL you bake into a pane's --input-data is auto-extended to the pane's TTL on pane create: if the token would expire before the pane, the relay bumps it to match, so the capability URL never 404s out from under a still-live pane. You no longer need to hand-match --ttl on token mint to the pane's --ttl. Caveats: only the owning agent's own tokens are extended, and --once tokens are left alone (they are meant to vanish on first GET). This cascade runs on the URLs present in input_data at create time — tokens you introduce later via events are not retroactively extended.

One-shot upload + emit — most agents emit events that REFERENCE blobs rather than embed them. Use pane send --attachment to do both in one call:

# Uploads ./chart.png as a pane-scope attachment, then sends an event
# whose data is { attachment: <AttachmentRef> } into the pane.
pane send <pane-id> --type chart.update --attachment ./chart.png

The pane's event schema should declare an attachment field with format: pane-attachment-id:

{
  "events": {
    "chart.update": {
      "emittedBy": ["agent"],
      "payload": {
        "type": "object",
        "properties": {
          "attachment": {
            "type": "object",
            "properties": {
              "attachment_id": { "type": "string", "format": "pane-attachment-id" }
            },
            "required": ["attachment_id"]
          }
        },
        "required": ["attachment"]
      }
    }
  }
}

Pages handle the event by reading ev.data.attachment.url and stuffing it in <img> / <iframe> / wherever the attachment is meant to render:

pane.on("chart.update", (ev) => {
  document.getElementById("chart").src = ev.data.attachment.url;
});

Default limits (the hosted relay): 5 MB per attachment, 500 MB total per agent. Adjust BLOB_* env vars on self-host. See docs/BLOB_BACKENDS.md for the backend matrix, docs/CAPABILITY-URLS.md for the /b/<token> threat model, and docs/SECURITY-POLYGLOTS.md for the upload-side defence (sharp normalisation + EXIF strip; SVG is passthrough — keep it out of BLOB_MIME_ALLOWLIST if your pane renders SVGs inline).

Human file uploads

A human inside a rendered pane can upload a file BACK to the relay via window.pane.uploadBlob(file, options?). The returned AttachmentRef is suitable for stuffing into an event payload — the agent receives it and can pane attachment download (or mint a /b/<token> URL) to read the bytes.

1. Declare the event in your schema with an attachment field.

{
  "events": {
    "photo.attached": {
      "emittedBy": ["page"],
      "payload": {
        "type": "object",
        "properties": {
          "attachment": {
            "type": "object",
            "properties": {
              "attachment_id": { "type": "string", "format": "pane-attachment-id" }
            },
            "required": ["attachment_id"]
          }
        },
        "required": ["attachment"]
      }
    }
  }
}

2. Inside the template HTML, wire a file input to `pane.uploadBlob` + `pane.emit`.

<input type="file" id="picker" accept="image/jpeg,image/png">
<button id="send" disabled>Upload</button>
<div id="status"></div>
<script>
  const picker = document.getElementById("picker");
  const sendBtn = document.getElementById("send");
  const status = document.getElementById("status");
  picker.addEventListener("change", () => {
    sendBtn.disabled = !picker.files?.length;
  });
  sendBtn.addEventListener("click", async () => {
    sendBtn.disabled = true;
    status.textContent = "uploading...";
    try {
      // Hands the File to the shell over postMessage; the shell POSTs
      // to /s/<participantToken>/attachments and returns the AttachmentRef.
      const attachment = await window.pane.uploadBlob(picker.files[0]);
      await window.pane.emit("photo.attached", { attachment });
      status.textContent = "uploaded.";
    } catch (e) {
      // e.code is the relay's error code (e.g. "blob_size_exceeded",
      // "mime_disallowed"). Branch on it to render a useful message.
      status.textContent = "failed: " + (e.code || e.message);
      sendBtn.disabled = false;
    }
  });
</script>

3. Agent-side, watch for the event and read the bytes.

# Wait for the human's upload event.
EVENT=$(pane watch "$SID" --type photo.attached)
ATTACHMENT_ID=$(echo "$EVENT" | jq -r .data.attachment.attachment_id)

# Download the bytes.
pane attachment download "$ATTACHMENT_ID" --out ./uploaded.jpg

Uploads are pinned to scope=pane: they cascade-delete with the pane, count against the AGENT's quota (not the participant), and run through the same MIME-sniff + polyglot-defense + EXIF-strip pipeline as pane attachment upload. See docs/CAPABILITY-URLS.md for the threat model.

Lazy image fetch in a pane

The reverse direction — the agent has an image (e.g. a chart it generated, an attachment downloaded from somewhere, output of an image pipeline) and wants the pane to render it.

Don't inline the bytes as data:image/...;base64 on the event. The iframe CSP allows data:, but it costs 33% on base64, duplicates the bytes on disk (encrypted attachment store + event row), replays over WebSocket on every reconnect, and a 1 MB image won't fit under MAX_EVENT_DATA_BYTES (default 64 KB). The whole point of attachment storage is to avoid this. (Tiny inline icons / placeholders as data: are fine.)

Instead, upload the image as an attachment, mint a `/b/<token>` capability URL, and point an `<img>` straight at it. The iframe CSP allows the relay's own origin in img-src/media-src, so the browser loads the bytes directly — with HTTP caching and range requests, and no postMessage round-trip. The capability token in the URL is the only credential (the sandboxed iframe carries no cookie); the relay gatekeeps it via /b/:token (entropy + revoke + TTL + status), and connect-src 'none' still blocks fetch/XHR.

1. Upload the bytes and mint a capability URL.

# Upload as a pane-scoped attachment (cascade-deletes with the pane).
ATT_ID=$(pane attachment upload --file ./weather-chart.png \
  --scope pane --pane-id "$SID" | jq -r .attachment_id)

# Mint a /b/<token> URL. TTL defaults to the pane's lifetime for
# pane-scope attachments; --once self-deletes the token on first GET.
IMG_URL=$(pane attachment token mint "$ATT_ID" | jq -r .url)

2. Pass the URL into the pane.

Either bake it into input_data at pane create time, or emit it on an event the template listens for:

pane send "$SID" --type image.delivered --data "{\"url\":\"$IMG_URL\"}"

3. Render it with a plain `<img>` — no JS bridge needed.

<img id="chart" alt="weather chart">
<script>
  // From input_data: <img src> can also be set directly in the template
  // via your render. From an event:
  window.pane.on("image.delivered", (ev) => {
    document.getElementById("chart").src = ev.data.url;
  });
</script>

Alternative — the `downloadBlob` bridge. window.pane.downloadBlob(attachment_id) returns a real browser Blob brokered by the shell (which fetches with the participant token and decrypts when BLOB_ENCRYPT_AT_REST is on). This is for getting raw bytes into JS — e.g. to hand to a <canvas> or parse — not for <img> rendering: the CSP does not allow blob: object URLs in img-src, so URL.createObjectURL(blob) as an <img src> is blocked. For rendering, prefer the capability-URL path above.

Migration note. Earlier versions of this skill showed img.src = URL.createObjectURL(await pane.downloadBlob(id)). That pattern never worked — blob: is not in img-src and it raises a CSP violation. Replace it with the capability-URL <img src> above. The attachment:<id> scheme is likewise unsupported (no handler) and is no longer in the CSP allowlist; do not use it.

Either way, the attachment must be referenced from this pane — the capability token is minted by the agent that owns it, and downloadBlob's participant token cannot enumerate arbitrary blobs the agent owns. See docs/CAPABILITY-URLS.md for the full trust model.

<!-- pane:core:start -->

Records — per-pane mutable collections (#287)

Records are a separate data shape from events. Where events are an append-only journal ("Alice posted", "Bob clicked"), records are a mutable per-pane collection (posts, comments, reactions, line items in a form) keyed by stable record_key. Templates that look like applications — todo lists, shopping lists, checklists, packing lists, expense logs, inventories, kanban boards, comment threads, form collections — should use records. These are the obvious first things a developer or agent tries to build on pane, and every one of them is records-shaped, not events-shaped. One-shot interactions (a form submission, an approval, a survey answer) stay on events.

When to reach for which

Declaring a record collection

Set the template's record_schema to a JSON Schema 2020-12 document with one namespaced extension, x-pane-collections. Only the extension is pane-specific; everything else is standard JSON Schema you already know.

$schema: "https://json-schema.org/draft/2020-12/schema"
$defs:
  Comment:
    type: object
    properties:
      body: { type: string, minLength: 1, maxLength: 4000 }
    required: [body]
  Post:
    type: object
    properties:
      title: { type: string }
      body:  { type: string }
    required: [title, body]

x-pane-collections:
  posts:
    schema: { $ref: "#/$defs/Post" }
    write:  [agent, page]          # principals that may create / update
    delete: [agent, author]        # `author` = only the row's authorId
  comments:
    schema: { $ref: "#/$defs/Comment" }
    write:  [page]
    delete: [author]

write is a non-empty subset of {agent, page}; delete is a non-empty subset of {agent, page, author}. The author rule on delete lets a participant delete their own rows without granting blanket delete to all participants. Collection names match ^[a-z][a-z0-9_-]{0,63}$.

Pass record_schema to pane template create (or the inline form on pane create) alongside event_schema / input_schema. The --record-schema flag takes a file path or inline JSON, same shape as --event-schema:

# Author the reusable template once. Omit --event-sc