@paneui/cli 0.0.5 → 0.0.7

package/dist/commands/attachment.js

@@ -0,0 +1,135 @@
+// `pane attachment` — manage binary attachments (attachments) on the relay.
+//
+// A attachment is a typed binary file (image, PDF, audio, video, etc.) owned by an
+// agent and optionally bound to a surface or template. Pages reference attachments
+// by id with `format: pane-attachment-id`; participants can fetch a attachment through a
+// minted capability URL (/b/<token>) without needing the agent's API key.
+//
+// This file is a thin dispatcher — each verb's actual logic lives in its own
+// file (attachment-upload.ts, attachment-download.ts, attachment-show.ts, attachment-delete.ts) and
+// the token sub-noun is dispatched via attachment-token.ts.
+//
+// Most attachment verbs read their primary positional (the attachment_id) at
+// positionals[0]; we slice off our own verb before delegating so each verb
+// runner doesn't need to know it was reached through `pane attachment`.
+import { runBlobUpload, blobUploadHelp } from "./attachment-upload.js";
+import { runBlobDownload, blobDownloadHelp } from "./attachment-download.js";
+import { runBlobShow, blobShowHelp } from "./attachment-show.js";
+import { runBlobList, blobListHelp } from "./attachment-list.js";
+import { runBlobDelete, blobDeleteHelp } from "./attachment-delete.js";
+import { runBlobToken, blobTokenHelp } from "./attachment-token.js";
+import { fail } from "../output.js";
+export const blobHelp = `pane attachment — manage attachments (binary attachments) on the relay
+
+A attachment is a typed binary file (image, PDF, audio, video, ...) the agent has
+uploaded to the relay. Blobs are scoped:
+
+  agent     — reusable across the agent's surfaces (default)
+  surface   — bound to one surface; deleted with it
+  template  — bound to a reusable template; deleted with it
+
+Pages reference attachments by id (the relay's schema validates the id with
+\`format: pane-attachment-id\`). For a participant-facing URL that bypasses the
+agent's API key, mint a token with 'pane attachment token mint'.
+
+Usage:
+  pane attachment <verb> [options]
+
+Verbs:
+  upload                 Upload a local file. Required: --file. Optional:
+                         --scope, --surface-id, --template-id, --filename,
+                         --mime. Prints { attachment_id, scope, mime, size, sha256,
+                         ... }.
+
+  download <attachment-id>     Download a attachment by id. Use --out <path> to write a
+                         file (default: writes to stdout — useful for piping).
+
+  show <attachment-id>         Print a attachment's metadata (HEAD-based — doesn't
+                         download the bytes).
+
+  list                   Enumerate YOUR agent's non-deleted attachments (newest
+                         first). Supports --cursor + --limit for pagination.
+
+  delete <attachment-id>       Soft-delete a attachment. Idempotent.
+
+  token <verb>           Capability URLs for a attachment (mint | revoke | list).
+                         'mint' returns a /b/<token> URL anyone can GET, with
+                         optional --ttl and --once. 'revoke' invalidates one
+                         token. 'list' enumerates a attachment's tokens (without
+                         the token plaintext, which is unrecoverable).
+
+Run \`pane attachment <verb> --help\` for verb-specific options.
+
+Output: stdout is machine-readable JSON. Errors go to stderr as
+{"error":{"code","message"}} with a non-zero exit.`;
+/**
+ * Build a new ParsedArgs with the leading positional (the verb) stripped.
+ * The downstream verb runners read their primary positional (the attachment_id)
+ * at positionals[0], so we hand them an args object that looks exactly like
+ * they were called directly — mirrors surface.ts's shiftPositionals.
+ */
+function shiftPositionals(args) {
+    // Propagate danglingValueFlags so the leaf runner's assertKnownFlags
+    // can still distinguish "unknown flag" from "missing value" — see the
+    // matching note in surface.ts's shiftPositionals.
+    const out = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+    };
+    if (args.danglingValueFlags !== undefined) {
+        out.danglingValueFlags = args.danglingValueFlags;
+    }
+    return out;
+}
+export async function runBlob(args) {
+    const verb = args.positionals[0];
+    // `pane attachment token --help` (verb-level help on the token sub-noun, with no
+    // further sub-verb). The general --help pre-empt in index.ts only fires
+    // when no positional follows the noun; here a positional ("token") is
+    // present, so the sub-noun must own its own --help routing.
+    if (verb === "token" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(blobTokenHelp + "\n");
+        return;
+    }
+    // `pane attachment list --help` — same pattern (list takes no required positional
+    // so the general pre-empt would already fire, but for parity with surface.ts
+    // we route through here when args carry the "list" positional explicitly).
+    if (verb === "list" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(blobListHelp + "\n");
+        return;
+    }
+    const inner = shiftPositionals(args);
+    switch (verb) {
+        case "upload":
+            await runBlobUpload(inner);
+            break;
+        case "download":
+            await runBlobDownload(inner);
+            break;
+        case "show":
+            await runBlobShow(inner);
+            break;
+        case "list":
+            await runBlobList(inner);
+            break;
+        case "delete":
+            await runBlobDelete(inner);
+            break;
+        case "token":
+            await runBlobToken(inner);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane attachment <upload|download|show|list|delete|token> (run 'pane attachment --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown attachment verb '${verb}' — expected upload|download|show|list|delete|token (run 'pane attachment --help')`, "invalid_args");
+    }
+}
+// Re-export per-verb helps so tests / docs can import them by canonical name
+// without knowing which file owns each verb.
+export { blobUploadHelp, blobDownloadHelp, blobShowHelp, blobListHelp, blobDeleteHelp, blobTokenHelp, };

package/dist/commands/claim.js

@@ -0,0 +1,68 @@
+// `pane agent claim <code>` — bind this agent to a human via a one-shot
+// claim code the human generated in their settings UI.
+//
+// Flow (§6.1):
+//   1. Alice opens Settings → "Claim an agent" → relay mints a one-shot code,
+//      shows it to her once, 15-min TTL.
+//   2. Alice hands the code to the agent out-of-band (this CLI invocation
+//      is exactly that handoff).
+//   3. CLI calls POST /v1/agents/claim with the calling agent's API key.
+//   4. Relay binds Agent.ownerHumanId = alice.id, migrates surface ownership.
+//
+// The CLI does NOT print the human's email or id — only the relay's response,
+// which is { ok, owner_human_id, claimed_at }. The agent's existing API key
+// keeps working.
+import { PaneClient, PaneApiError } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
+import { resolveConfig } from "../config.js";
+import { printJson, fail } from "../output.js";
+const KNOWN_FLAGS = ["url", "api-key"];
+const KNOWN_BOOLS = [];
+export const claimHelp = `pane agent claim — claim this agent for a human
+
+Usage:
+  pane agent claim <code>
+
+Binds the calling agent to the human whose one-shot claim code is provided.
+The human generates the code in their settings UI (or via the relay's
+POST /v1/self/claim-codes endpoint) and hands it to the agent out-of-band.
+
+Arguments:
+  <code>              The one-shot claim code (begins with cc_). Required.
+
+Options:
+  --url <url>         Relay base URL. Falls back to PANE_URL / config file.
+  --api-key <key>     Agent API key. Falls back to PANE_API_KEY / config file.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { ok: true, owner_human_id, claimed_at }
+
+Errors:
+  invalid_code             code is unknown, expired, or already consumed
+  agent_already_claimed    this agent already has an owning human
+
+Notes:
+  This is a one-way operation. To rotate the owner, revoke this agent
+  (\`pane key revoke\`) and register a new one.`;
+export async function runClaim(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane agent claim");
+    const code = args.positionals[0];
+    if (!code) {
+        fail("missing required argument: <code> — run 'pane agent claim --help'", "invalid_args");
+        return;
+    }
+    const creds = resolveConfig(args);
+    const client = new PaneClient({ url: creds.url, apiKey: creds.apiKey });
+    try {
+        const result = await client.claimAgent(code);
+        printJson(result);
+    }
+    catch (err) {
+        if (err instanceof PaneApiError) {
+            fail(err.message, err.code);
+            return;
+        }
+        throw err;
+    }
+}

package/dist/commands/config.js

@@ -1,14 +1,19 @@
-// `pane config` — show the resolved relay config without a network call.
+// `pane config show` — show the resolved relay config without a network call.
+import { assertKnownFlags } from "../argv.js";
 import { describeConfig } from "../config.js";
-import { printJson } from "../output.js";
+import { printJson, fail } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
 export const configHelp = `pane config — show the resolved relay config
 
 Usage:
-  pane config [options]
+  pane config show [options]
 
-Prints the relay URL and API-key info the CLI would use, and where each value
-came from. Makes NO network call — purely inspects flags, env vars, and the
-saved config file.
+Verbs:
+  show                Print the relay URL and API-key info the CLI would use,
+                      and where each value came from. Makes NO network call —
+                      purely inspects flags, env vars, and the saved config
+                      file.
 
 The API key is never printed in full: only a short masked prefix.
 
@@ -26,6 +31,20 @@ Output (stdout, JSON):
     key_source,     "flag" | "env" | "store" | "none"
     config_path     absolute path to the CLI config file
   }`;
-export async function runConfig(args) {
+async function runConfigShow(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane config show");
     printJson(describeConfig(args));
 }
+export async function runConfig(args) {
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "show":
+            await runConfigShow(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane config show (run 'pane config --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown config verb '${verb}' — expected show (run 'pane config --help')`, "invalid_args");
+    }
+}

package/dist/commands/create.js

@@ -1,8 +1,24 @@
-// `pane create` — create a session via POST /v1/sessions.
+// `pane surface create` — create a surface via POST /v1/surfaces.
 import { createSessionSchema } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { resolveJson, resolveText } from "../input.js";
 import { printJson, fail, failFromError } from "../output.js";
+const KNOWN_FLAGS = [
+    "template",
+    "template-id",
+    "template-type",
+    "version",
+    "event-schema",
+    "input-schema",
+    "title",
+    "input-data",
+    "ttl",
+    "participants",
+    "metadata",
+    "callback",
+];
+const KNOWN_BOOLS = [];
 // Translate a Zod schema path (e.g. ["participants","humans"]) back to the
 // public CLI flag the user actually typed. Without this, a `--participants 0`
 // rejection surfaces as `participants.humans: ...` — which leaks the wire
@@ -10,9 +26,9 @@ import { printJson, fail, failFromError } from "../output.js";
 //
 // Match strategy: longest prefix wins. Schema paths whose top segment isn't
 // in the table fall back to dotted notation so we degrade gracefully on
-// fields that don't have a single corresponding flag (e.g. `artifact.source`
-// — there's no single --artifact-source flag for the inline form, just
-// --artifact pointing at the whole blob).
+// fields that don't have a single corresponding flag (e.g. `template.source`
+// — there's no single --template-source flag for the inline form, just
+// --template pointing at the whole attachment).
 const SCHEMA_PATH_TO_FLAG = {
     participants: "--participants",
     "participants.humans": "--participants",
@@ -20,11 +36,13 @@ const SCHEMA_PATH_TO_FLAG = {
     metadata: "--metadata",
     callback: "--callback",
     input_data: "--input-data",
-    "artifact.id": "--artifact-id",
-    "artifact.version": "--version",
-    "artifact.type": "--artifact-type",
-    "artifact.source": "--artifact",
-    "artifact.event_schema": "--event-schema",
+    title: "--title",
+    "template.id": "--template-id",
+    "template.version": "--version",
+    "template.type": "--template-type",
+    "template.source": "--template",
+    "template.event_schema": "--event-schema",
+    "template.input_schema": "--input-schema",
 };
 function schemaPathToFlag(path) {
     const dotted = path.map(String).join(".");
@@ -39,32 +57,32 @@ function schemaPathToFlag(path) {
     }
     return dotted;
 }
-export const createHelp = `pane create — create a Pane session
+export const createHelp = `pane surface create — create a Pane surface
 
-A session is one use of an artifact. Supply the artifact in ONE of two ways:
+A surface is one use of an template. Supply the template in ONE of two ways:
 
-  Reference form — instance an existing reusable artifact (the cheap path,
+  Reference form — instance an existing reusable template (the cheap path,
   no HTML re-sent):
-    pane create --artifact-id <id|slug> [--version <n>] [--input-data <v>]
+    pane surface create --template-id <id|slug> [--version <n>] [--input-data <v>]
 
-  Inline form — a one-off artifact, defined on this call:
-    pane create --artifact <path|inline> [--event-schema <path|json>] [options]
+  Inline form — a one-off template, defined on this call:
+    pane surface create --template <path|inline> [--event-schema <path|json>] [options]
 
-Exactly one of --artifact-id / --artifact must be given.
+Exactly one of --template-id / --template must be given.
 
-Artifact (choose one):
-  --artifact-id <v>   Reference an existing named artifact by id or slug.
-                      Tip: run 'pane artifact search <keywords>' first — a
-                      suitable artifact may already exist; reuse it instead of
+Template (choose one):
+  --template-id <v>   Reference an existing named template by id or slug.
+                      Tip: run 'pane template search <keywords>' first — a
+                      suitable template may already exist; reuse it instead of
                       regenerating HTML.
-  --version <n>       With --artifact-id: pin a specific version. Defaults to
-                      the artifact's latest version.
-  --artifact <v>      Inline HTML artifact. Either a file path / URL, or inline
-                      HTML. Combine with --artifact-type to control reading.
+  --version <n>       With --template-id: pin a specific version. Defaults to
+                      the template's latest version.
+  --template <v>      Inline HTML template. Either a file path / URL, or inline
+                      HTML. Combine with --template-type to control reading.
   --event-schema <v>  Inline-form event schema. A .json file, or inline JSON.
-                      Optional with --artifact. Omit for a view-only artifact
+                      Optional with --template. Omit for a view-only template
                       (a report/dashboard the human only views — no page/agent
-                      events). Ignored with --artifact-id.
+                      events). Ignored with --template-id.
 
                       Shape — an object with an "events" map, keyed by event
                       type. Each entry declares who may emit it and the JSON
@@ -84,17 +102,31 @@ Artifact (choose one):
                       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>  Inline-form input schema. A .json file, or inline JSON.
+                      Optional with --template, rejected with --template-id
+                      (the schema comes from the pinned template version
+                      there). When present, the surface's --input-data is
+                      validated against it AND any attachment ids declared at a
+                      "format": "pane-attachment-id" site become reachable from the
+                      page via window.pane.downloadBlob. Without it, attachment
+                      refs in --input-data are silently unreachable. See
+                      docs/SPEC.md and #208.
 
 Options:
+  --title <text>      Tab title shown to the human (max 80 chars, single
+                      line). Required, with one ergonomic exception: when
+                      --template-id references a named template, the relay
+                      falls back to Template.name. Inline (--template …) form
+                      always needs --title.
   --input-data <v>    This instance's seed data — a JSON object (file path or
-                      inline JSON), validated by the relay against the artifact
+                      inline JSON), validated by the relay against the template
                       version's input_schema. The page reads it as
                       window.pane.inputData.
-  --artifact-type <t> "html-inline" (default) or "html-ref". With "html-ref"
-                      the --artifact value is treated as a URL. Note: the relay
-                      does not serve "html-ref" artifacts in this release and
-                      will reject the session — use "html-inline".
-  --ttl <seconds>     Session time-to-live in seconds. The relay clamps this
+  --template-type <t> "html-inline" (default) or "html-ref". With "html-ref"
+                      the --template value is treated as a URL. Note: the relay
+                      does not serve "html-ref" templates in this release and
+                      will reject the surface — use "html-inline".
+  --ttl <seconds>     Surface time-to-live in seconds. The relay clamps this
                       to its configured MAX_TTL_SECONDS (defaults: 1 h
                       requested, 24 h max for self-host; hosted may differ).
                       The returned \`expires_at\` is the authoritative value.
@@ -106,18 +138,19 @@ Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { session_id, urls, tokens, expires_at }
+  { surface_id, urls, tokens, expires_at }
 
 Deliver urls.humans to the human(s); keep tokens.agent for the WS stream.`;
 export async function runCreate(args) {
-    const artifactIdVal = args.flags.get("artifact-id");
-    const artifactVal = args.flags.get("artifact");
-    // Exactly one of the two artifact forms must be present.
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface create");
+    const artifactIdVal = args.flags.get("template-id");
+    const artifactVal = args.flags.get("template");
+    // Exactly one of the two template forms must be present.
     if (artifactIdVal !== undefined && artifactVal !== undefined) {
-        fail("pass only one of --artifact-id (reference an existing artifact) or --artifact (inline a one-off)", "invalid_args");
+        fail("pass only one of --template-id (reference an existing template) or --template (inline a one-off)", "invalid_args");
     }
     if (artifactIdVal === undefined && artifactVal === undefined) {
-        fail("missing artifact — pass --artifact-id <id|slug> to reference an existing artifact, or --artifact <path|inline> to inline one", "invalid_args");
+        fail("missing template — pass --template-id <id|slug> to reference an existing template, or --template <path|inline> to inline one", "invalid_args");
     }
     // Assemble a candidate request object, then validate the whole thing with
     // the shared Zod schema (single source of truth, matches what the relay
@@ -125,8 +158,12 @@ export async function runCreate(args) {
     // flag-specific message; the schema then enforces shape and bounds.
     const candidate = {};
     if (artifactIdVal !== undefined) {
-        // Reference form — instance an existing named artifact. --artifact /
-        // --event-schema are not needed here.
+        // Reference form — instance an existing named template. --template /
+        // --event-schema / --input-schema are not used here: the template's
+        // pinned version carries them already.
+        if (args.flags.get("input-schema") !== undefined) {
+            fail("--input-schema is incompatible with --template-id — the input schema comes from the pinned template version. Author the schema on the template (`pane template create --input-schema …`) instead.", "invalid_args");
+        }
         const ref = { id: artifactIdVal };
         const versionRaw = args.flags.get("version");
         if (versionRaw !== undefined) {
@@ -136,32 +173,40 @@ export async function runCreate(args) {
             }
             ref["version"] = version;
         }
-        candidate["artifact"] = ref;
+        candidate["template"] = ref;
     }
     else {
-        // Inline form — the event schema rides inside the `artifact` object; the
-        // relay transparently creates an anonymous artifact behind it.
-        // --event-schema is optional: omitting it makes a view-only one-off (a
-        // report/dashboard the human only views), and the relay then rejects every
-        // page/agent emit.
+        // Inline form — the event + input schemas ride inside the `template`
+        // object; the relay transparently creates an anonymous template behind
+        // it. Both schemas are optional:
+        //  - --event-schema absent → view-only one-off (no page/agent emits)
+        //  - --input-schema absent → no input contract; --input-data passes
+        //    through unvalidated AND any attachment ids in it are unreachable from
+        //    the page (the participant attachment-download bridge walks input_data
+        //    against the template version's inputSchema). Pass --input-schema
+        //    when --input-data carries attachment refs the page needs to render.
+        //    See #208.
         const schemaVal = args.flags.get("event-schema");
-        const artifactType = (args.flags.get("artifact-type") ?? "html-inline");
-        if (artifactType !== "html-inline" && artifactType !== "html-ref") {
-            fail("--artifact-type must be 'html-inline' or 'html-ref'", "invalid_args");
+        const inputSchemaVal = args.flags.get("input-schema");
+        const templateType = (args.flags.get("template-type") ?? "html-inline");
+        if (templateType !== "html-inline" && templateType !== "html-ref") {
+            fail("--template-type must be 'html-inline' or 'html-ref'", "invalid_args");
         }
         // html-ref: the value is a URL, used verbatim. html-inline: file or literal.
         let source;
         try {
             source =
-                artifactType === "html-ref" ? artifactVal : resolveText(artifactVal);
+                templateType === "html-ref" ? artifactVal : resolveText(artifactVal);
         }
         catch (e) {
             fail(e instanceof Error ? e.message : String(e), "invalid_args");
         }
-        // Build the inline artifact object. event_schema is OMITTED entirely (not
-        // set to undefined) when --event-schema is absent — a view-only artifact.
+        // Build the inline template object. event_schema / input_schema are
+        // OMITTED entirely (not set to undefined) when their flags are absent —
+        // omission is meaningful at the relay (view-only template / no input
+        // contract).
         const inlineArtifact = {
-            type: artifactType,
+            type: templateType,
             source,
         };
         if (schemaVal !== undefined) {
@@ -172,7 +217,28 @@ export async function runCreate(args) {
                 fail(e instanceof Error ? e.message : String(e), "invalid_args");
             }
         }
-        candidate["artifact"] = inlineArtifact;
+        if (inputSchemaVal !== undefined) {
+            try {
+                const v = resolveJson(inputSchemaVal, "--input-schema");
+                if (v === null || typeof v !== "object" || Array.isArray(v)) {
+                    fail("--input-schema must be a JSON object", "invalid_args");
+                }
+                inlineArtifact["input_schema"] = v;
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e), "invalid_args");
+            }
+        }
+        candidate["template"] = inlineArtifact;
+    }
+    // --title — passthrough, no client-side requiredness. The relay is the
+    // single source of truth: it enforces "required, with --template-id +
+    // Template.name as the only fallback" and the shape rules (length, control
+    // chars). Keeping all that server-side avoids drift between the CLI's
+    // pre-checks and the relay's actual rules.
+    const titleRaw = args.flags.get("title");
+    if (titleRaw !== undefined) {
+        candidate["title"] = titleRaw;
     }
     // --input-data — per-instance seed data, applies to either form (the relay
     // validates it against the pinned version's input_schema).

package/dist/commands/delete.js

@@ -1,13 +1,16 @@
-// `pane delete <id>` — close/delete a session.
+// `pane surface delete <id>` — close/delete a surface.
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-export const deleteHelp = `pane delete — close/delete a session
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const deleteHelp = `pane surface delete — close/delete a surface
 
 Usage:
-  pane delete <session-id> [options]
+  pane surface delete <surface-id> [options]
 
-Closes and deletes the session (DELETE /v1/sessions/:id). Idempotent on the
-relay side — deleting an already-closed session still succeeds.
+Closes and deletes the surface (DELETE /v1/surfaces/:id). Idempotent on the
+relay side — deleting an already-closed surface still succeeds.
 
 Options:
   --url <url>         Relay base URL (overrides PANE_URL).
@@ -15,15 +18,16 @@ Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { session_id, deleted: true }`;
+  { surface_id, deleted: true }`;
 export async function runDelete(args) {
-    const sessionId = args.positionals[0];
-    if (!sessionId)
-        fail("missing <session-id>", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface delete");
+    const surfaceId = args.positionals[0];
+    if (!surfaceId)
+        fail("missing <surface-id>", "invalid_args");
     const client = makeClient(args);
     try {
-        await client.deleteSession(sessionId);
-        printJson({ session_id: sessionId, deleted: true });
+        await client.deleteSession(surfaceId);
+        printJson({ surface_id: surfaceId, deleted: true });
     }
     catch (e) {
         failFromError(e);

package/dist/commands/feedback.js

@@ -1,5 +1,9 @@
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
+const CREATE_FLAGS = ["type", "message", "surface-id"];
+const LIST_FLAGS = ["limit", "before"];
+const NO_BOOLS = [];
 export const feedbackHelp = `pane feedback — submit / list feedback to the relay operator
 
 Feedback is a one-shot bug report, feature request, or note from YOUR agent
@@ -21,7 +25,7 @@ Options for 'create':
   --type <bug|feature|note>   Feedback category. Required.
   --message <text|->          Message body. Pass '-' to read from stdin.
                               1..4000 chars after trim.
-  --session-id <id>           Optional session this feedback relates to;
+  --surface-id <id>           Optional surface this feedback relates to;
                               must belong to YOUR agent.
 
 Options for 'list':
@@ -34,7 +38,7 @@ Global:
   -h, --help                  Show this help.
 
 Examples:
-  pane feedback create --type bug --message "watch hangs on empty session"
+  pane feedback create --type bug --message "watch hangs on empty surface"
   echo "long-form note..." | pane feedback create --type note --message -
   pane feedback list --limit 20
 
@@ -48,9 +52,10 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runFeedbackCreate(args) {
+    assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "pane feedback create");
     const type = args.flags.get("type");
     const rawMessage = args.flags.get("message");
-    const sessionId = args.flags.get("session-id");
+    const surfaceId = args.flags.get("surface-id");
     if (type === undefined) {
         fail("'pane feedback create' requires --type <bug|feature|note>", "invalid_args");
     }
@@ -78,7 +83,7 @@ async function runFeedbackCreate(args) {
         const res = await client.submitFeedback({
             type: type,
             message,
-            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(surfaceId !== undefined ? { surfaceId } : {}),
         });
         printJson(res);
     }
@@ -87,6 +92,7 @@ async function runFeedbackCreate(args) {
     }
 }
 async function runFeedbackList(args) {
+    assertKnownFlags(args, LIST_FLAGS, NO_BOOLS, "pane feedback list");
     const limitRaw = args.flags.get("limit");
     const before = args.flags.get("before");
     let limit;