@paneui/cli 0.0.9 → 0.0.10

package/dist/commands/template.js

@@ -4,10 +4,12 @@
 // a positional subcommand (create / version / update / search / list / show /
 // delete).
 // An template is a reusable UI template (HTML + event schema + optional input
-// schema); a surface is one *use* of one version of it. Authoring an template
-// once and instancing it via `pane surface create --template-id` removes the
+// schema); a pane is one *use* of one version of it. Authoring an template
+// once and instancing it via `pane create --template-id` removes the
 // per-use cost of regenerating the same HTML.
-import { createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, } from "@paneui/core";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, validateIconEmoji, } from "@paneui/core";
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { resolveJson, resolveText } from "../input.js";
@@ -21,7 +23,10 @@ const CREATE_FLAGS = [
     "template-type",
     "event-schema",
     "input-schema",
+    "icon-emoji",
 ];
+const SET_ICON_FLAGS = ["template-id", "emoji", "image"];
+const SET_ICON_BOOLS = ["clear"];
 const VERSION_FLAGS = [
     "template",
     "template-type",
@@ -32,32 +37,47 @@ const UPDATE_FLAGS = ["name", "slug", "description", "tags"];
 const NO_FLAGS = [];
 const NO_BOOLS = [];
 const DELETE_BOOLS = ["yes"];
+const PUBLISH_FLAGS = ["scopes"];
+const SEARCH_PUBLIC_FLAGS = ["limit", "offset"];
 export const artifactHelp = `pane template — manage reusable, versioned templates
 
 An template is a reusable UI template: HTML + an event schema + an optional
-input schema. A surface is one use of one version of it. Author an template
-once, then instance it many times with 'pane surface create --template-id <id|slug>'
-instead of regenerating the HTML on every surface.
+input schema. A pane is one use of one version of it. Author an template
+once, then instance it many times with 'pane create --template-id <id|slug>'
+instead of regenerating the HTML on every pane.
 
 Usage:
   pane template <subcommand> [options]
 
 Subcommands:
-  create     Create a named, reusable template (its v1).
-  version    Append a new version to an existing template.
-  update     Update an template's head metadata (name/slug/description/tags).
-  search     Search the agent's named templates (lean — no HTML).
-  list       List the agent's named templates (search with no query).
-  show       Show a full template: head metadata + its version list.
-  delete     Permanently delete an template and ALL its versions. Requires
-             --yes. Refused with 409 conflict if any surface (open or
-             closed) still references the template — delete those first.
+  create        Create a named, reusable template (its v1).
+  version       Append a new version to an existing template.
+  update        Update an template's head metadata (name/slug/description/tags).
+  search        Search the agent's named templates (lean — no HTML).
+  list          List the agent's named templates (search with no query).
+  show          Show a full template: head metadata + its version list.
+  delete        Permanently delete an template and ALL its versions. Requires
+                --yes. Refused with 409 conflict if any pane (open or
+                closed) still references the template — delete those first.
+  publish       Publish a template to the public catalog (so other humans
+                can install it). Optionally lock --scopes at publish time.
+  unpublish     Remove a template from the public catalog. Existing
+                installs are unaffected; the template just stops appearing
+                in searches.
+  search-public Search the PUBLIC catalog of all published templates from
+                every agent. Use before creating a new template, to find
+                an existing one you can install/recommend instead.
+  set-icon      Set (or clear) a template's icon — a single emoji, or an
+                uploaded raster image (png/jpeg/webp/gif). No SVG, no URLs.
 
   pane template create --name <n> --template <path|inline>
                        [--event-schema <path|json>] [--slug <s>]
                        [--description <d>] [--tags <t1,t2>]
                        [--input-schema <path|json>] [--template-type <t>]
+                       [--icon-emoji <emoji>]
       Creates a named template. Prints { template_id, slug, version }.
+      --icon-emoji sets a single-emoji icon at create time; use 'set-icon'
+      with --image to attach an uploaded image icon afterwards.
 
   pane template version <id|slug> --template <path|inline>
                         [--event-schema <path|json>]
@@ -81,11 +101,41 @@ Subcommands:
 
   pane template delete <id|slug> --yes
       Permanently deletes the template and all its versions. Refused
-      (409 conflict) if any surface in any state still references one
-      of the template's versions — run 'pane surface delete <surface-id>' on
+      (409 conflict) if any pane in any state still references one
+      of the template's versions — run 'pane delete <pane-id>' on
       each first, or wait for the relay's TTL sweeper to reclaim them.
       Prints { template, deleted: true } on success.
 
+  pane template publish <id|slug> [--scopes <s1,s2,...>]
+      Publishes the template to the public catalog. Other humans can then
+      install it from their /apps page. --scopes is a comma-separated
+      'verb:noun' list (e.g. 'read:agent,write:pane') that locks the
+      permissions this version requests; reissue with new --scopes to
+      reset them. Prints the head metadata + published_at + scopes.
+
+  pane template unpublish <id|slug>
+      Removes the template from the public catalog. Existing installs
+      keep working — they're pinned to their version. Prints the head
+      metadata with published_at: null.
+
+  pane template search-public [query] [--limit <n>] [--offset <n>]
+      Searches the PUBLIC catalog across every agent's published
+      templates. Substring match on name, description, and tags. Ranked
+      by install_count desc, then publish recency. Useful BEFORE
+      authoring: 'pane template search-public pr-review' may find an
+      existing one you can install instead of building from scratch.
+      Prints { items, total, offset, limit }.
+
+  pane template set-icon --template-id <id> (--emoji <e> | --image <path>)
+  pane template set-icon --template-id <id> --clear
+      Sets the template's icon. Pass exactly one of:
+        --emoji <e>    a single emoji grapheme (rendered inline as text)
+        --image <path> a local raster image (png/jpeg/webp/gif). Uploaded as
+                       a template-scoped attachment, then linked as the icon.
+        --clear        removes both the emoji and the image icon.
+      Image icons are served same-origin from the relay; external URLs and
+      SVG are never accepted. Prints the updated lean template summary.
+
 Options:
   --name <n>          Template display name (required for 'create').
   --slug <s>          Stable, agent-chosen handle (unique per agent). The
@@ -117,8 +167,9 @@ Options:
                       emittedBy is any non-empty subset of ["page", "agent"].
                       payload is a JSON Schema; the relay validates every
                       emit against it. See docs/SPEC.md for the full grammar.
-  --input-schema <v>  JSON Schema for this template's per-surface input_data —
+  --input-schema <v>  JSON Schema for this template's per-pane input_data —
                       a file path, or inline JSON. Optional.
+  --icon-emoji <e>    Single-emoji icon for the template (create only).
   --template-type <t> "html-inline" (default) or "html-ref".
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
@@ -189,7 +240,7 @@ function resolveTags(args) {
         .filter((t) => t !== "");
     return tags.length > 0 ? tags : undefined;
 }
-async function runArtifactCreate(args) {
+async function runTemplateCreate(args) {
     assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "pane template create");
     const name = args.flags.get("name");
     if (!name)
@@ -218,6 +269,9 @@ async function runArtifactCreate(args) {
         candidate["tags"] = tags;
     if (inputSchema !== undefined)
         candidate["input_schema"] = inputSchema;
+    const iconEmoji = args.flags.get("icon-emoji");
+    if (iconEmoji !== undefined)
+        candidate["icon_emoji"] = iconEmoji;
     const parsed = createArtifactSchema.safeParse(candidate);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
@@ -238,7 +292,7 @@ async function runArtifactCreate(args) {
         failFromError(e);
     }
 }
-async function runArtifactVersion(args) {
+async function runTemplateVersion(args) {
     assertKnownFlags(args, VERSION_FLAGS, NO_BOOLS, "pane template version");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
@@ -274,7 +328,7 @@ async function runArtifactVersion(args) {
         failFromError(e);
     }
 }
-async function runArtifactUpdate(args) {
+async function runTemplateUpdate(args) {
     assertKnownFlags(args, UPDATE_FLAGS, NO_BOOLS, "pane template update");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
@@ -312,7 +366,7 @@ async function runArtifactUpdate(args) {
         failFromError(e);
     }
 }
-async function runArtifactSearch(args, query) {
+async function runTemplateSearch(args, query) {
     assertKnownFlags(args, NO_FLAGS, NO_BOOLS, query === undefined ? "pane template list" : "pane template search");
     const client = makeClient(args);
     try {
@@ -323,7 +377,7 @@ async function runArtifactSearch(args, query) {
         failFromError(e);
     }
 }
-async function runArtifactShow(args) {
+async function runTemplateShow(args) {
     assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane template show");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
@@ -340,10 +394,10 @@ async function runArtifactShow(args) {
 }
 // `pane template delete <id|slug> --yes` — remove an template (and, server-
 // side, all its versions). The relay refuses with 409 conflict if any
-// surface still references it; the CLI surfaces that as the relay-supplied
+// pane still references it; the CLI panes that as the relay-supplied
 // envelope. `--yes` is required because there's no Undo button on a delete
 // and the same `pane template create` slug isn't reservable once gone.
-async function runArtifactDelete(args) {
+async function runTemplateDelete(args) {
     assertKnownFlags(args, NO_FLAGS, DELETE_BOOLS, "pane template delete");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
@@ -361,34 +415,188 @@ async function runArtifactDelete(args) {
         failFromError(e);
     }
 }
-export async function runArtifact(args) {
+async function runTemplatePublish(args) {
+    assertKnownFlags(args, PUBLISH_FLAGS, NO_BOOLS, "pane template publish");
+    const idOrSlug = args.positionals[1];
+    if (!idOrSlug) {
+        fail("missing template <id|slug> — usage: pane template publish <id|slug> [--scopes <s1,s2,...>]", "invalid_args");
+    }
+    // --scopes is a comma-separated list of verb:noun strings. Omit to leave
+    // the existing scopes alone (server semantics). Pass an empty string to
+    // explicitly clear them (we send []).
+    const rawScopes = args.flags.get("scopes");
+    const body = {};
+    if (rawScopes !== undefined) {
+        body.scopes = rawScopes
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.publishTemplate(idOrSlug, body);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runTemplateUnpublish(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane template unpublish");
+    const idOrSlug = args.positionals[1];
+    if (!idOrSlug) {
+        fail("missing template <id|slug> — usage: pane template unpublish <id|slug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.unpublishTemplate(idOrSlug);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runTemplateSearchPublic(args) {
+    assertKnownFlags(args, SEARCH_PUBLIC_FLAGS, NO_BOOLS, "pane template search-public");
+    const query = args.positionals[1];
+    const opts = {};
+    const limitRaw = args.flags.get("limit");
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n < 1 || n > 50) {
+            fail("--limit must be an integer between 1 and 50", "invalid_args");
+        }
+        opts.limit = n;
+    }
+    const offsetRaw = args.flags.get("offset");
+    if (offsetRaw !== undefined) {
+        const n = Number(offsetRaw);
+        if (!Number.isInteger(n) || n < 0) {
+            fail("--offset must be a non-negative integer", "invalid_args");
+        }
+        opts.offset = n;
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.searchPublicTemplates(query, opts);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// `pane template set-icon --template-id <id> (--emoji <e> | --image <path> |
+// --clear)` — set or clear a template's icon. --emoji PATCHes icon_emoji
+// directly; --image uploads the file as a template-scoped attachment then
+// PATCHes icon_attachment_id; --clear nulls both.
+async function runTemplateSetIcon(args) {
+    assertKnownFlags(args, SET_ICON_FLAGS, SET_ICON_BOOLS, "pane template set-icon");
+    const templateId = args.flags.get("template-id");
+    if (!templateId) {
+        fail("missing --template-id <id> — usage: pane template set-icon --template-id <id> (--emoji <e> | --image <path> | --clear)", "invalid_args");
+    }
+    const emoji = args.flags.get("emoji");
+    const imagePath = args.flags.get("image");
+    const clear = args.bools.has("clear");
+    // Exactly one of --emoji / --image / --clear.
+    const chosen = [emoji !== undefined, imagePath !== undefined, clear].filter(Boolean).length;
+    if (chosen !== 1) {
+        fail("pass exactly one of --emoji <e>, --image <path>, or --clear", "invalid_args");
+    }
+    const client = makeClient(args);
+    if (clear) {
+        try {
+            const res = await client.updateArtifact(templateId, {
+                icon_emoji: null,
+                icon_attachment_id: null,
+            });
+            printJson(res);
+        }
+        catch (e) {
+            failFromError(e);
+        }
+        return;
+    }
+    if (emoji !== undefined) {
+        // Validate client-side for a clear error before the round trip; the relay
+        // re-validates regardless.
+        const v = validateIconEmoji(emoji);
+        if (!v.ok)
+            fail(`invalid --emoji: ${v.error}`, "invalid_args");
+        try {
+            const res = await client.updateArtifact(templateId, {
+                icon_emoji: emoji,
+            });
+            printJson(res);
+        }
+        catch (e) {
+            failFromError(e);
+        }
+        return;
+    }
+    // --image: upload the file as a template-scoped attachment, then link it.
+    let bytes;
+    try {
+        bytes = readFileSync(imagePath);
+    }
+    catch (e) {
+        fail(`failed to read --image '${imagePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+    }
+    try {
+        const ref = await client.uploadBlob(bytes, {
+            scope: "template",
+            templateId: templateId,
+            filename: basename(imagePath),
+        });
+        const res = await client.updateArtifact(templateId, {
+            icon_attachment_id: ref.attachment_id,
+        });
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runTemplate(args) {
     const sub = args.positionals[0];
     switch (sub) {
         case "create":
-            await runArtifactCreate(args);
+            await runTemplateCreate(args);
             break;
         case "version":
-            await runArtifactVersion(args);
+            await runTemplateVersion(args);
             break;
         case "update":
-            await runArtifactUpdate(args);
+            await runTemplateUpdate(args);
             break;
         case "search":
-            await runArtifactSearch(args, args.positionals[1]);
+            await runTemplateSearch(args, args.positionals[1]);
             break;
         case "list":
-            await runArtifactSearch(args, undefined);
+            await runTemplateSearch(args, undefined);
             break;
         case "show":
-            await runArtifactShow(args);
+            await runTemplateShow(args);
             break;
         case "delete":
-            await runArtifactDelete(args);
+            await runTemplateDelete(args);
+            break;
+        case "publish":
+            await runTemplatePublish(args);
+            break;
+        case "unpublish":
+            await runTemplateUnpublish(args);
+            break;
+        case "search-public":
+            await runTemplateSearchPublic(args);
+            break;
+        case "set-icon":
+            await runTemplateSetIcon(args);
             break;
         case undefined:
-            fail("missing subcommand — usage: pane template <create|version|update|search|list|show|delete> (run 'pane template --help')", "invalid_args");
+            fail("missing subcommand — usage: pane template <create|version|update|search|list|show|delete|publish|unpublish|search-public|set-icon> (run 'pane template --help')", "invalid_args");
             break;
         default:
-            fail(`unknown template subcommand '${sub}' — expected create|version|update|search|list|show|delete (run 'pane template --help')`, "invalid_args");
+            fail(`unknown template subcommand '${sub}' — expected create|version|update|search|list|show|delete|publish|unpublish|search-public|set-icon (run 'pane template --help')`, "invalid_args");
     }
 }

package/dist/commands/trash.js

@@ -0,0 +1,102 @@
+// `pane trash <verb>` — manage the soft-delete trash (#306 / CLI follow-up).
+//
+//   pane trash list                              show soft-deleted panes + templates
+//   pane trash restore <pane-id>                 restore a trashed pane
+//   pane trash restore-template <template-id>    restore a trashed template
+//   pane trash purge <pane-id>                   permanent hard-delete now
+//   pane trash purge-template <template-id>     permanent hard-delete now
+//
+// Why "purge" not "delete": `pane delete <id>` already exists and means
+// "close the live pane" (which, with #303, sends it to trash via the TTL
+// sweeper after it expires). Using "delete" again on a trashed row would
+// be confusing — "purge" reads unambiguously as "the row is gone for good".
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const trashHelp = `pane trash — manage the soft-delete trash
+
+Usage:
+  pane trash list                            Show soft-deleted panes + templates
+  pane trash restore <pane-id>               Restore a trashed pane
+  pane trash restore-template <id-or-slug>   Restore a trashed template
+  pane trash purge <pane-id>                 Permanent hard-delete now (skips
+                                             the retention window)
+  pane trash purge-template <id-or-slug>     Permanent hard-delete now
+
+Soft-deleted rows live in trash until the hard-delete sweeper reclaims them
+(default retention: 30 days free / never paid). 'restore' takes them back
+out of trash; 'purge' deletes them immediately, bypassing the window.
+
+Options:
+  --url <url>         Relay base URL (overrides PANE_URL).
+  --api-key <key>     Agent API key (overrides PANE_API_KEY).
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  list:               { panes: [...], templates: [...] }
+  restore / purge:    { pane_id|template_id, restored|purged: true }`;
+export async function runTrash(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane trash");
+    const verb = args.positionals[0];
+    if (verb === undefined || verb === "-h" || verb === "--help") {
+        process.stdout.write(trashHelp + "\n");
+        return;
+    }
+    const id = args.positionals[1];
+    // Validate positional arguments BEFORE building the client so the
+    // invalid_args envelope is emitted without a second wrap-around via
+    // failFromError (which would clobber it to `internal`).
+    switch (verb) {
+        case "list":
+        case "restore":
+        case "restore-template":
+        case "purge":
+        case "purge-template":
+            break;
+        default:
+            fail(`unknown trash verb '${verb}' — run 'pane trash --help'`, "invalid_args");
+    }
+    if (verb === "restore" || verb === "purge") {
+        if (!id)
+            fail("missing <pane-id>", "invalid_args");
+    }
+    else if (verb === "restore-template" || verb === "purge-template") {
+        if (!id)
+            fail("missing <template-id-or-slug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        switch (verb) {
+            case "list": {
+                const body = await client.listTrash();
+                printJson(body);
+                return;
+            }
+            case "restore": {
+                await client.restorePane(id);
+                printJson({ pane_id: id, restored: true });
+                return;
+            }
+            case "restore-template": {
+                await client.restoreTemplate(id);
+                printJson({ template_id: id, restored: true });
+                return;
+            }
+            case "purge": {
+                await client.permanentDeletePane(id);
+                printJson({ pane_id: id, purged: true });
+                return;
+            }
+            case "purge-template": {
+                await client.permanentDeleteTemplate(id);
+                printJson({ template_id: id, purged: true });
+                return;
+            }
+        }
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/watch.js

@@ -1,4 +1,4 @@
-// `pane surface watch <id>` — long-lived: hold a WebSocket and stream events as
+// `pane watch <id>` — long-lived: hold a WebSocket and stream events as
 // JSON-lines on stdout. This harness-agnostic stdout is the core contract:
 // one compact JSON object per line, flushed after every event, so any
 // pipe-reader (Claude Code's Monitor tool, `while read line`, jq -c, ...)
@@ -11,14 +11,14 @@ import { printJsonLine, fail } from "../output.js";
 import { VERSION } from "../version.js";
 const KNOWN_FLAGS = ["since", "type", "filter-type", "timeout"];
 const KNOWN_BOOLS = ["once"];
-export const watchHelp = `pane surface watch — stream a surface's events as JSON-lines
+export const watchHelp = `pane watch — stream a pane's events as JSON-lines
 
 Usage:
-  pane surface watch <surface-id> [options]
+  pane watch <pane-id> [options]
 
-Holds a WebSocket to WS /v1/surfaces/:id/stream. Prints ONE compact JSON
+Holds a WebSocket to WS /v1/panes/:id/stream. Prints ONE compact JSON
 object per line to stdout, flushing after each — designed to be piped into a
-line-reader. On surface close, prints a final {"type":"_closed"} line and
+line-reader. On pane close, prints a final {"type":"_closed"} line and
 exits 0.
 
 Modes:
@@ -34,7 +34,7 @@ Options:
   --filter-type <t[,t2,…]>
                       Print only events whose type is in this set.
                       system.* events (lifecycle: participant.joined,
-                      surface.expired, …) and the terminal {"type":
+                      pane.expired, …) and the terminal {"type":
                       "_closed"} line always pass through, so the
                       harness still sees them. Combine with --type X
                       --filter-type X for "stream only X events and
@@ -42,7 +42,7 @@ Options:
                       --type alone that agents often expect.
   --since <cursor>    Replay only events after this opaque cursor.
   --timeout <secs>    Wall-clock max wait. Fail with code ws_timeout if
-                      the natural exit condition (--once, --type, surface
+                      the natural exit condition (--once, --type, pane
                       close) doesn't happen within this many seconds.
                       Frames arriving DO NOT reset the timer — this is
                       the budget for "give up on the human", not an idle
@@ -52,17 +52,17 @@ Options:
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
   -h, --help          Show this help.
 
-Each line is one event envelope: { id, surface_id, author, ts, type, data,
+Each line is one event envelope: { id, pane_id, author, ts, type, data,
 causation_id, idempotency_key }. The terminal line is {"type":"_closed"}.
 
-Pattern — Claude Code Monitor tool: run \`pane surface watch <id> --type form.submitted\`
+Pattern — Claude Code Monitor tool: run \`pane watch <id> --type form.submitted\`
 as a monitored process; the harness re-invokes the model when the line lands.
 
 Wait for any of several events:
-  pane surface watch <id> --type form.submitted,form.cancelled --timeout 60
+  pane watch <id> --type form.submitted,form.cancelled --timeout 60
 
 Stream only matching events to stdout, exit on the first:
-  pane surface watch <id> --type form.submitted --filter-type form.submitted`;
+  pane watch <id> --type form.submitted --filter-type form.submitted`;
 // Parse a comma-separated event-type list (e.g. "form.submitted,form.cancelled")
 // into a Set. Empty/whitespace entries are dropped. Returns null when the flag
 // wasn't given (so callers can distinguish "no filter" from "empty filter").
@@ -91,10 +91,10 @@ export function shouldPrintEvent(eventType, filterTypes) {
     return filterTypes.has(eventType);
 }
 export async function runWatch(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface watch");
-    const surfaceId = args.positionals[0];
-    if (!surfaceId)
-        fail("missing <surface-id>", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane watch");
+    const paneId = args.positionals[0];
+    if (!paneId)
+        fail("missing <pane-id>", "invalid_args");
     const cfg = resolveConfig(args);
     const since = args.flags.get("since") ?? null;
     // --type controls the EXIT condition (set of types that trigger exit 0
@@ -135,7 +135,7 @@ export async function runWatch(args) {
         }
         finish(0);
     };
-    // Track whether the relay told us the surface expired before the socket
+    // Track whether the relay told us the pane expired before the socket
     // closed — a 1006/1008/1011 close after that is still a clean shutdown.
     let sawSessionExpired = false;
     // Wall-clock timeout. The reporter's mental model (#137) and the skill
@@ -145,7 +145,7 @@ export async function runWatch(args) {
     // useless once any frame arrived, even a system.participant.joined
     // emitted the moment a human connected. Frames now DO NOT reset the
     // timer; the only ways `--timeout` doesn't fire are the natural exit
-    // conditions (--once, --type match, surface close) finishing first.
+    // conditions (--once, --type match, pane close) finishing first.
     let timer;
     if (timeoutSec !== null) {
         timer = setTimeout(() => {
@@ -154,7 +154,7 @@ export async function runWatch(args) {
     }
     const handle = openStream({
         wsBaseUrl: client.wsBaseUrl,
-        surfaceId: surfaceId,
+        paneId: paneId,
         token: cfg.apiKey,
         since,
     }, {
@@ -167,8 +167,8 @@ export async function runWatch(args) {
             if (shouldPrintEvent(event.type, filterTypes)) {
                 printJsonLine(event);
             }
-            // A system.surface.expired event means the surface is closing.
-            if (event.type === "system.surface.expired") {
+            // A system.pane.expired event means the pane is closing.
+            if (event.type === "system.pane.expired") {
                 sawSessionExpired = true;
                 emitClosed();
                 return;
@@ -184,8 +184,8 @@ export async function runWatch(args) {
         onClose: ({ code, reason }) => {
             // A clean close is 1000 (normal) or 1001 (going away). Any other code
             // — 1006 abnormal, 1008 policy/auth, 1011 server error — is a failure
-            // UNLESS we already saw system.surface.expired, which means the relay
-            // closed us on purpose after a clean surface end.
+            // UNLESS we already saw system.pane.expired, which means the relay
+            // closed us on purpose after a clean pane end.
             if (code === 1000 || code === 1001 || sawSessionExpired) {
                 emitClosed();
                 return;