@paneui/cli 0.0.6 → 0.0.8

package/README.md

@@ -34,12 +34,12 @@ Uniform `pane <noun> <verb> [options]`:
 ```
 pane agent register            Provision an agent API key and save it locally
 pane agent logout              Clear the locally-saved URL + API key
-pane session create            Create a session — returns session_id, urls, tokens
-pane session show <id>         Non-blocking snapshot: metadata + event log
-pane session send <id>         Emit an agent event into a session
-pane session watch <id>        Stream a session's events as JSON-lines on stdout
-pane session delete <id>       Close / delete a session
-pane artifact <verb>           Manage reusable, versioned artifacts
+pane surface create            Create a surface — returns surface_id, urls, tokens
+pane surface show <id>         Non-blocking snapshot: metadata + event log
+pane surface send <id>         Emit an agent event into a surface
+pane surface watch <id>        Stream a surface's events as JSON-lines on stdout
+pane surface delete <id>       Close / delete a surface
+pane template <verb>           Manage reusable, versioned templates
 pane key list | revoke         Inspect or revoke your agent's API key
 pane taste get | set | clear   Read / write / clear UI-taste notes
 pane feedback create | list    Submit / list one-shot feedback to the operator
@@ -56,12 +56,12 @@ stdout is machine-readable JSON. Errors go to stderr as
 `{"error":{"code","message"}}` with a non-zero exit.
 
 ```sh
-SESSION=$(pane session create --template form --schema ./q.json | jq -r .session_id)
-pane session watch "$SESSION" | jq 'select(.type == "human_response")'
+SESSION=$(pane surface create --template form --schema ./q.json | jq -r .surface_id)
+pane surface watch "$SESSION" | jq 'select(.type == "human_response")'
 ```
 
 ## Links
 
 - Repo: <https://github.com/aerolalit/paneui>
-- Spec: <https://github.com/aerolalit/paneui/blob/main/docs/SPEC.md>
+- Spec: <https://github.com/aerolalit/paneui/attachment/main/docs/SPEC.md>
 - License: MIT

package/dist/commands/agent.js

@@ -9,6 +9,7 @@
 // logout.ts.
 import { runRegister } from "./register.js";
 import { runLogout } from "./logout.js";
+import { runClaim } from "./claim.js";
 import { fail } from "../output.js";
 export const agentHelp = `pane agent — manage this agent's identity on the relay
 
@@ -18,24 +19,36 @@ Usage:
 Verbs:
   register          Provision an agent API key (POST /v1/register) and save it
                     to the CLI config file. Run this once before other commands.
+  claim <code>      Bind this agent to a human via a one-shot claim code the
+                    human generated in their Settings UI (POST /v1/agents/claim).
+                    One-way; no unclaim in v1.
   logout            Clear the locally-saved relay URL + API key. Does NOT
                     revoke the key on the relay — use 'pane key revoke' for
                     that.
 
 Run \`pane agent <verb> --help\` for verb-specific options.`;
 export async function runAgent(args) {
+    // Strip the first positional (the verb) so each verb runner sees its
+    // own arguments at positionals[0..n].
+    const verbArgs = {
+        ...args,
+        positionals: args.positionals.slice(1),
+    };
     const verb = args.positionals[0];
     switch (verb) {
         case "register":
-            await runRegister(args);
+            await runRegister(verbArgs);
+            break;
+        case "claim":
+            await runClaim(verbArgs);
             break;
         case "logout":
-            await runLogout(args);
+            await runLogout(verbArgs);
             break;
         case undefined:
-            fail("missing verb — usage: pane agent <register|logout> (run 'pane agent --help')", "invalid_args");
+            fail("missing verb — usage: pane agent <register|claim|logout> (run 'pane agent --help')", "invalid_args");
             break;
         default:
-            fail(`unknown agent verb '${verb}' — expected register|logout (run 'pane agent --help')`, "invalid_args");
+            fail(`unknown agent verb '${verb}' — expected register|claim|logout (run 'pane agent --help')`, "invalid_args");
     }
 }

package/dist/commands/attachment-delete.js

@@ -0,0 +1,37 @@
+// `pane attachment delete <attachment-id>` — soft-delete a attachment.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const blobDeleteHelp = `pane attachment delete — soft-delete a attachment
+
+Usage:
+  pane attachment delete <attachment-id> [options]
+
+Marks the attachment as deleted (DELETE /v1/attachments/:id). Idempotent: deleting an
+already-deleted attachment still returns success. Tokens minted against this attachment
+become unusable.
+
+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):
+  { attachment_id, deleted: true }`;
+export async function runBlobDelete(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment delete");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment delete <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.deleteBlob(attachmentId);
+        printJson({ attachment_id: attachmentId, ...r });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/{blob-download.js → attachment-download.js}

@@ -1,16 +1,16 @@
-// `pane blob download <blob-id>` — fetch blob bytes by id.
+// `pane attachment download <attachment-id>` — fetch attachment bytes by id.
 import { writeFileSync } from "node:fs";
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
 const KNOWN_FLAGS = ["out"];
 const KNOWN_BOOLS = [];
-export const blobDownloadHelp = `pane blob download — fetch a blob's bytes
+export const blobDownloadHelp = `pane attachment download — fetch a attachment's bytes
 
 Usage:
-  pane blob download <blob-id> [--out <path>] [options]
+  pane attachment download <attachment-id> [--out <path>] [options]
 
-GETs the blob bytes. With --out <path> the bytes are written to that file and
+GETs the attachment bytes. With --out <path> the bytes are written to that file and
 a JSON summary is printed on stdout; without --out the bytes are written to
 stdout verbatim (useful for piping into another tool — but binary on a TTY
 is rarely useful).
@@ -23,20 +23,24 @@ Options:
 
 Output:
   Without --out: raw bytes to stdout.
-  With --out:    { blob_id, written: <path>, bytes: <n> } to stdout.`;
+  With --out:    { attachment_id, written: <path>, bytes: <n> } to stdout.`;
 export async function runBlobDownload(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob download");
-    const blobId = args.positionals[0];
-    if (!blobId) {
-        fail("missing <blob-id> — 'pane blob download <blob-id>'", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment download");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment download <attachment-id>'", "invalid_args");
     }
     const out = args.flags.get("out");
     const client = makeClient(args);
     try {
-        const buf = await client.downloadBlob(blobId);
+        const buf = await client.downloadBlob(attachmentId);
         if (out) {
             writeFileSync(out, Buffer.from(buf));
-            printJson({ blob_id: blobId, written: out, bytes: buf.byteLength });
+            printJson({
+                attachment_id: attachmentId,
+                written: out,
+                bytes: buf.byteLength,
+            });
         }
         else {
             // Binary to stdout — useful for piping into another tool.

package/dist/commands/{blob-list.js → attachment-list.js}

@@ -1,19 +1,19 @@
-// `pane blob list` — enumerate YOUR agent's blobs.
+// `pane attachment list` — enumerate YOUR agent's attachments.
 //
-// Lists blobs owned by the calling agent, newest first. Soft-deleted blobs
-// are excluded; tokens are not enumerated here (use 'pane blob token list
-// <blob-id>' for that).
+// Lists attachments owned by the calling agent, newest first. Soft-deleted attachments
+// are excluded; tokens are not enumerated here (use 'pane attachment token list
+// <attachment-id>' for that).
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { fail, printJson, failFromError } from "../output.js";
 const KNOWN_FLAGS = ["cursor", "limit"];
 const KNOWN_BOOLS = [];
-export const blobListHelp = `pane blob list — enumerate YOUR agent's blobs
+export const blobListHelp = `pane attachment list — enumerate YOUR agent's attachments
 
 Usage:
-  pane blob list [--cursor <token>] [--limit <n>] [options]
+  pane attachment list [--cursor <token>] [--limit <n>] [options]
 
-Returns the agent's non-deleted blobs (newest first). Paginated via opaque
+Returns the agent's non-deleted attachments (newest first). Paginated via opaque
 cursor: when next_cursor is non-null in the response, pass it back as
 --cursor to get the next page.
 
@@ -26,9 +26,9 @@ Options:
   -h, --help             Show this help.
 
 Output (stdout, JSON):
-  { items: BlobRef[], next_cursor: string | null }`;
+  { items: AttachmentRef[], next_cursor: string | null }`;
 export async function runBlobList(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob list");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment list");
     const cursor = args.flags.get("cursor");
     const limitRaw = args.flags.get("limit");
     let limit;

package/dist/commands/{blob-show.js → attachment-show.js}

@@ -1,16 +1,16 @@
-// `pane blob show <blob-id>` — print a blob's metadata.
+// `pane attachment show <attachment-id>` — print a attachment's metadata.
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
 const KNOWN_FLAGS = [];
 const KNOWN_BOOLS = [];
-export const blobShowHelp = `pane blob show — print a blob's metadata (no bytes)
+export const blobShowHelp = `pane attachment show — print a attachment's metadata (no bytes)
 
 Usage:
-  pane blob show <blob-id> [options]
+  pane attachment show <attachment-id> [options]
 
-Looks up the blob by id and prints its BlobRef metadata — owner, scope,
-mime, size, sha256, etc. Does NOT download the bytes; use 'pane blob
+Looks up the attachment by id and prints its AttachmentRef metadata — owner, scope,
+mime, size, sha256, etc. Does NOT download the bytes; use 'pane attachment
 download' for that.
 
 Options:
@@ -19,16 +19,16 @@ Options:
   -h, --help             Show this help.
 
 Output (stdout, JSON):
-  BlobRef`;
+  AttachmentRef`;
 export async function runBlobShow(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob show");
-    const blobId = args.positionals[0];
-    if (!blobId) {
-        fail("missing <blob-id> — 'pane blob show <blob-id>'", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment show");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment show <attachment-id>'", "invalid_args");
     }
     const client = makeClient(args);
     try {
-        const ref = await client.getBlob(blobId);
+        const ref = await client.getBlob(attachmentId);
         printJson(ref);
     }
     catch (e) {

package/dist/commands/{blob-token.js → attachment-token.js}

@@ -1,16 +1,16 @@
-// `pane blob token <mint|revoke|list>` — capability URLs for a blob.
+// `pane attachment token <mint|revoke|list>` — capability URLs for a attachment.
 //
-// A capability URL (/b/<token>) is a participant-facing way to fetch a blob
-// without holding the agent's API key. Tokens are minted per-blob, can be
+// A capability URL (/b/<token>) is a participant-facing way to fetch a attachment
+// without holding the agent's API key. Tokens are minted per-attachment, can be
 // time-bound (--ttl) and/or single-use (--once), and are stored hashed on
 // the relay — the plaintext token is returned ONCE on 'mint' and cannot be
 // recovered.
 //
-// This file is a sub-noun dispatcher under `pane blob`. The blob dispatcher
+// This file is a sub-noun dispatcher under `pane attachment`. The attachment dispatcher
 // hands us a ParsedArgs whose positionals[0] is "token" (our sub-noun
 // marker), so we read the verb from positionals[1] and the args from
 // positionals[2..]. Mirrors how participant.ts dispatches under `pane
-// session participant`.
+// surface participant`.
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
@@ -18,31 +18,31 @@ const MINT_FLAGS = ["ttl"];
 const MINT_BOOLS = ["once"];
 const NO_FLAGS = [];
 const NO_BOOLS = [];
-export const blobTokenHelp = `pane blob token — manage a blob's capability URLs
+export const blobTokenHelp = `pane attachment token — manage a attachment's capability URLs
 
 Capability URLs let a participant (or any browser holding the URL) fetch a
-blob without the agent's API key. Tokens are stored HASHED on the relay; the
+attachment without the agent's API key. Tokens are stored HASHED on the relay; the
 plaintext token is returned only ONCE from 'mint' — save the response before
 delivering the URL.
 
 Usage:
-  pane blob token <verb> <args>
+  pane attachment token <verb> <args>
 
 Verbs:
-  mint <blob-id>          Mint a /b/<token> capability URL for one blob.
+  mint <attachment-id>          Mint a /b/<token> capability URL for one attachment.
                           Optional: --ttl <seconds> (defaults by scope:
-                          30d artifact / session TTL / 24h agent; the caller
+                          30d template / surface TTL / 24h agent; the caller
                           can only shorten), --once (token self-deletes on
                           first successful GET). Returns { token, url,
                           expires_at, ... } — ONCE.
 
-  revoke <blob-id> <token-id>
+  revoke <attachment-id> <token-id>
                           Invalidate one previously-minted token by id.
                           Idempotent: revoking twice still returns success.
 
-  list <blob-id>          Enumerate the tokens minted against one blob,
+  list <attachment-id>          Enumerate the tokens minted against one attachment,
                           including revoked rows (for audit). Returns
-                          { blob_id, items: [...] } where each item carries
+                          { attachment_id, items: [...] } where each item carries
                           { token_id, token_prefix, expires_at, once,
                           created_at, last_used_at, use_count, revoked_at }.
                           The token plaintext is NEVER returned.
@@ -56,10 +56,10 @@ Options:
 
 Output: stdout is machine-readable JSON.`;
 async function runBlobTokenMint(args) {
-    assertKnownFlags(args, MINT_FLAGS, MINT_BOOLS, "pane blob token mint");
-    const blobId = args.positionals[1];
-    if (!blobId) {
-        fail("missing <blob-id> — 'pane blob token mint <blob-id>'", "invalid_args");
+    assertKnownFlags(args, MINT_FLAGS, MINT_BOOLS, "pane attachment token mint");
+    const attachmentId = args.positionals[1];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment token mint <attachment-id>'", "invalid_args");
     }
     const ttlRaw = args.flags.get("ttl");
     const ttl = ttlRaw === undefined ? undefined : Number(ttlRaw);
@@ -68,7 +68,7 @@ async function runBlobTokenMint(args) {
     }
     const client = makeClient(args);
     try {
-        const r = await client.mintBlobToken(blobId, {
+        const r = await client.mintBlobToken(attachmentId, {
             ttlSeconds: ttl,
             once: args.bools.has("once"),
         });
@@ -79,15 +79,15 @@ async function runBlobTokenMint(args) {
     }
 }
 async function runBlobTokenRevoke(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane blob token revoke");
-    const blobId = args.positionals[1];
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane attachment token revoke");
+    const attachmentId = args.positionals[1];
     const tokenId = args.positionals[2];
-    if (!blobId || !tokenId) {
-        fail("missing arguments — 'pane blob token revoke <blob-id> <token-id>'", "invalid_args");
+    if (!attachmentId || !tokenId) {
+        fail("missing arguments — 'pane attachment token revoke <attachment-id> <token-id>'", "invalid_args");
     }
     const client = makeClient(args);
     try {
-        const r = await client.revokeBlobToken(blobId, tokenId);
+        const r = await client.revokeBlobToken(attachmentId, tokenId);
         printJson(r);
     }
     catch (e) {
@@ -95,14 +95,14 @@ async function runBlobTokenRevoke(args) {
     }
 }
 async function runBlobTokenList(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane blob token list");
-    const blobId = args.positionals[1];
-    if (!blobId) {
-        fail("missing <blob-id> — 'pane blob token list <blob-id>'", "invalid_args");
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane attachment token list");
+    const attachmentId = args.positionals[1];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment token list <attachment-id>'", "invalid_args");
     }
     const client = makeClient(args);
     try {
-        const r = await client.listBlobTokens(blobId);
+        const r = await client.listBlobTokens(attachmentId);
         printJson(r);
     }
     catch (e) {
@@ -111,7 +111,7 @@ async function runBlobTokenList(args) {
 }
 export async function runBlobToken(args) {
     // positionals[0] is the verb (mint | revoke | list), positionals[1..] are
-    // the verb's args. (The blob.ts dispatcher already shifted off the "token"
+    // the verb's args. (The attachment.ts dispatcher already shifted off the "token"
     // marker before calling us.)
     const verb = args.positionals[0];
     switch (verb) {
@@ -125,9 +125,9 @@ export async function runBlobToken(args) {
             await runBlobTokenList(args);
             break;
         case undefined:
-            fail("missing verb — usage: pane blob token <mint|revoke|list> (run 'pane blob token --help')", "invalid_args");
+            fail("missing verb — usage: pane attachment token <mint|revoke|list> (run 'pane attachment token --help')", "invalid_args");
             break;
         default:
-            fail(`unknown token verb '${verb}' — expected mint|revoke|list (run 'pane blob token --help')`, "invalid_args");
+            fail(`unknown token verb '${verb}' — expected mint|revoke|list (run 'pane attachment token --help')`, "invalid_args");
     }
 }

package/dist/commands/{blob-upload.js → attachment-upload.js}

@@ -1,4 +1,4 @@
-// `pane blob upload` — POST /v1/blobs (multipart), three scopes.
+// `pane attachment upload` — POST /v1/attachments (multipart), three scopes.
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { assertKnownFlags } from "../argv.js";
@@ -7,24 +7,24 @@ import { fail, failFromError, printJson } from "../output.js";
 const KNOWN_FLAGS = [
     "file",
     "scope",
-    "session-id",
-    "artifact-id",
+    "surface-id",
+    "template-id",
     "filename",
     "mime",
 ];
 const KNOWN_BOOLS = [];
-export const blobUploadHelp = `pane blob upload — upload a local file as a blob
+export const blobUploadHelp = `pane attachment upload — upload a local file as a attachment
 
 Usage:
-  pane blob upload --file <path> [options]
+  pane attachment upload --file <path> [options]
 
 Required:
   --file <path>          Local file to upload.
 
 Scope (default: agent):
-  --scope <s>            "agent" | "session" | "artifact".
-  --session-id <id>      Required when --scope=session.
-  --artifact-id <id>     Required when --scope=artifact.
+  --scope <s>            "agent" | "surface" | "template".
+  --surface-id <id>      Required when --scope=surface.
+  --template-id <id>     Required when --scope=template.
 
 Optional:
   --filename <name>      Display filename (otherwise basename of --file).
@@ -35,12 +35,12 @@ Optional:
   -h, --help             Show this help.
 
 Output (stdout, JSON):
-  BlobRef — { blob_id, scope, mime, size, sha256, ... }`;
+  AttachmentRef — { attachment_id, scope, mime, size, sha256, ... }`;
 export async function runBlobUpload(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob upload");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment upload");
     const filePath = args.flags.get("file");
     if (!filePath) {
-        fail("missing --file <path> — 'pane blob upload' requires a local file to upload", "invalid_args");
+        fail("missing --file <path> — 'pane attachment upload' requires a local file to upload", "invalid_args");
     }
     let bytes;
     try {
@@ -51,23 +51,23 @@ export async function runBlobUpload(args) {
     }
     const scopeRaw = args.flags.get("scope") ?? "agent";
     if (scopeRaw !== "agent" &&
-        scopeRaw !== "session" &&
-        scopeRaw !== "artifact") {
-        fail(`unknown --scope '${scopeRaw}' — expected one of: agent, session, artifact`, "invalid_args");
+        scopeRaw !== "surface" &&
+        scopeRaw !== "template") {
+        fail(`unknown --scope '${scopeRaw}' — expected one of: agent, surface, template`, "invalid_args");
     }
     const scope = scopeRaw;
-    if (scope === "session" && !args.flags.get("session-id")) {
-        fail("--scope=session requires --session-id <id>", "invalid_args");
+    if (scope === "surface" && !args.flags.get("surface-id")) {
+        fail("--scope=surface requires --surface-id <id>", "invalid_args");
     }
-    if (scope === "artifact" && !args.flags.get("artifact-id")) {
-        fail("--scope=artifact requires --artifact-id <id>", "invalid_args");
+    if (scope === "template" && !args.flags.get("template-id")) {
+        fail("--scope=template requires --template-id <id>", "invalid_args");
     }
     const client = makeClient(args);
     try {
         const ref = await client.uploadBlob(bytes, {
             scope,
-            sessionId: args.flags.get("session-id"),
-            artifactId: args.flags.get("artifact-id"),
+            surfaceId: args.flags.get("surface-id"),
+            templateId: args.flags.get("template-id"),
             filename: args.flags.get("filename") ?? basename(filePath),
             mime: args.flags.get("mime"),
         });

package/dist/commands/{blob.js → attachment.js}

@@ -1,77 +1,77 @@
-// `pane blob` — manage binary attachments (blobs) on the relay.
+// `pane attachment` — manage binary attachments (attachments) on the relay.
 //
-// A blob is a typed binary file (image, PDF, audio, video, etc.) owned by an
-// agent and optionally bound to a session or artifact. Pages reference blobs
-// by id with `format: pane-blob-id`; participants can fetch a blob through a
+// 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 (blob-upload.ts, blob-download.ts, blob-show.ts, blob-delete.ts) and
-// the token sub-noun is dispatched via blob-token.ts.
+// 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 blob verbs read their primary positional (the blob_id) at
+// 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 blob`.
-import { runBlobUpload, blobUploadHelp } from "./blob-upload.js";
-import { runBlobDownload, blobDownloadHelp } from "./blob-download.js";
-import { runBlobShow, blobShowHelp } from "./blob-show.js";
-import { runBlobList, blobListHelp } from "./blob-list.js";
-import { runBlobDelete, blobDeleteHelp } from "./blob-delete.js";
-import { runBlobToken, blobTokenHelp } from "./blob-token.js";
+// 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 blob — manage blobs (binary attachments) on the relay
+export const blobHelp = `pane attachment — manage attachments (binary attachments) on the relay
 
-A blob is a typed binary file (image, PDF, audio, video, ...) the agent has
+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 sessions (default)
-  session   — bound to one session; deleted with it
-  artifact  — bound to a reusable artifact; deleted with it
+  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 blobs by id (the relay's schema validates the id with
-\`format: pane-blob-id\`). For a participant-facing URL that bypasses the
-agent's API key, mint a token with 'pane blob token mint'.
+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 blob <verb> [options]
+  pane attachment <verb> [options]
 
 Verbs:
   upload                 Upload a local file. Required: --file. Optional:
-                         --scope, --session-id, --artifact-id, --filename,
-                         --mime. Prints { blob_id, scope, mime, size, sha256,
+                         --scope, --surface-id, --template-id, --filename,
+                         --mime. Prints { attachment_id, scope, mime, size, sha256,
                          ... }.
 
-  download <blob-id>     Download a blob by id. Use --out <path> to write a
+  download <attachment-id>     Download a attachment by id. Use --out <path> to write a
                          file (default: writes to stdout — useful for piping).
 
-  show <blob-id>         Print a blob's metadata (HEAD-based — doesn't
+  show <attachment-id>         Print a attachment's metadata (HEAD-based — doesn't
                          download the bytes).
 
-  list                   Enumerate YOUR agent's non-deleted blobs (newest
+  list                   Enumerate YOUR agent's non-deleted attachments (newest
                          first). Supports --cursor + --limit for pagination.
 
-  delete <blob-id>       Soft-delete a blob. Idempotent.
+  delete <attachment-id>       Soft-delete a attachment. Idempotent.
 
-  token <verb>           Capability URLs for a blob (mint | revoke | list).
+  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 blob's tokens (without
+                         token. 'list' enumerates a attachment's tokens (without
                          the token plaintext, which is unrecoverable).
 
-Run \`pane blob <verb> --help\` for verb-specific options.
+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 blob_id)
+ * 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 session.ts's shiftPositionals.
+ * 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 session.ts's shiftPositionals.
+    // matching note in surface.ts's shiftPositionals.
     const out = {
         positionals: args.positionals.slice(1),
         flags: args.flags,
@@ -84,7 +84,7 @@ function shiftPositionals(args) {
 }
 export async function runBlob(args) {
     const verb = args.positionals[0];
-    // `pane blob token --help` (verb-level help on the token sub-noun, with no
+    // `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.
@@ -94,8 +94,8 @@ export async function runBlob(args) {
         process.stdout.write(blobTokenHelp + "\n");
         return;
     }
-    // `pane blob list --help` — same pattern (list takes no required positional
-    // so the general pre-empt would already fire, but for parity with session.ts
+    // `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") &&
@@ -124,10 +124,10 @@ export async function runBlob(args) {
             await runBlobToken(inner);
             break;
         case undefined:
-            fail("missing verb — usage: pane blob <upload|download|show|list|delete|token> (run 'pane blob --help')", "invalid_args");
+            fail("missing verb — usage: pane attachment <upload|download|show|list|delete|token> (run 'pane attachment --help')", "invalid_args");
             break;
         default:
-            fail(`unknown blob verb '${verb}' — expected upload|download|show|list|delete|token (run 'pane blob --help')`, "invalid_args");
+            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