@synap-core/cli 1.10.0 → 1.12.2

package/dist/index.js

@@ -1,32 +1,23 @@
 #!/usr/bin/env node
 /**
- * @synap/cli — Connect AI agents to your Synap data pod
+ * @synap-core/cli — Connect AI agents to your Synap data pod
  *
  * Usage:
- *   npx @synap/cli init              Full setup: detect, harden, connect, install
- *   npx @synap/cli connect           Connect an AI surface to a Synap pod
- *   npx @synap/cli status            Show pod health and API status
- *   npx @synap/cli update            Update skill + check for CLI updates
+ *   npx @synap-core/cli init              Full setup: detect, harden, connect, install
+ *   npx @synap-core/cli connect           Connect an AI surface to a Synap pod
+ *   npx @synap-core/cli status            Show pod health and API status
+ *   npx @synap-core/cli update            Show how to update the CLI
  *
  * Or install globally:
- *   npm i -g @synap/cli
+ *   npm i -g @synap-core/cli
  *   synap init
  */
-import { Command } from "commander";
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
+import { Command, Option } from "commander";
 import { bootstrapPodOverride } from "./lib/pod.js";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-let version = "0.1.0";
-try {
-    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
-    version = pkg.version;
-}
-catch {
-    // use default
-}
+import { INIT_EXIT_HELP } from "./lib/init-exit.js";
+import { cliBuild, formatCliBuild } from "./lib/cli-build.js";
+// The version AND the commit this build came from — a stale build is visible.
+const version = formatCliBuild(cliBuild());
 const program = new Command();
 program
     .name("synap")
@@ -42,7 +33,12 @@ program
     .description("Full setup: connect to a Synap pod and install the skill")
     .option("--pod-url <url>", "Synap pod URL (skip pod choice prompt)")
     .option("--api-key <key>", "Hub Protocol API key (skip key generation)")
-    .option("--skip-is", "Skip Intelligence Service provider setup")
+    // Deprecated no-op, kept so old scripts do not fail on an unknown option.
+    .addOption(new Option("--skip-is", "deprecated, ignored").hideHelp())
+    .option("-y, --yes", "Accept the defaults, no prompts (connects the agents found on this machine)")
+    .option("--agents <list>", "Agents to connect, comma-separated: claude-code,codex,cursor")
+    .option("--json", "Print a JSON summary on stdout: {podUrl, connected, notApproved, failed, pairLink, exitCode}")
+    .addHelpText("after", INIT_EXIT_HELP)
     .action(async (opts) => {
     const { init } = await import("./commands/init.js");
     await init(opts);
@@ -71,31 +67,61 @@ program
     .option("--bot-token <token>", "Discord bot token — provisioned into the pod vault")
     .option("--guild-id <id>", "Discord server (guild) id — written to the bridge .env")
     .option("--bridge-dir <path>", "Path to the telegram-discord-bridge repo")
-    .option("--workspace-id <uuid>", "Target workspace (default: pod profile's)")
+    .option("--workspace-id <uuid>", "Advanced/legacy: pin the bridge to one workspace (default: pod-wide, never prompted)")
+    .option("--project-id <uuid>", "Scope the bridge to one project (default: prompt, pod-wide if declined)")
     .option("--proactive-channel <id>", "Discord channel id for the agent's proactive posts")
     .option("--enable-react", "Turn on ✅-react capture")
+    // Re-running bridge-setup on an already-provisioned pod now DETECTS what is
+    // configured and skips it (the bot token is already in the vault — re-asking
+    // for a secret the pod already holds was the sharpest instance). This flag
+    // restores the old behaviour for a genuine rotation or repoint.
+    .option("--reconfigure", "Re-ask every question and re-provision from scratch (ignore what a previous run configured)")
     .option("--pod <name>", "Pod profile to connect the bridge to (default: prompt)")
-    .option("--governance <mode>", "Agent governance preset: safe | normal | crazy (default: prompt)")
+    .option("--governance <mode>", "Agent approval preset: safe | creates | normal | crazy (default: prompt; \"follow the pod default\" writes nothing)")
     .option("--pod-url <url>", "Synap pod URL (override)")
     .option("--api-key <key>", "Hub Protocol API key (override)")
     .action(async (opts) => {
     const { bridgeSetup } = await import("./commands/bridge-setup.js");
     await bridgeSetup(opts);
 });
+// Hidden: one-shot Proton Mail↔Synap bridge provisioning (dogfood/dev convenience).
+// Fork of bridge-setup for the sovereign self-host Proton Bridge path — see
+// the catalog capability synap-app/packages/workspace-templates/capabilities/proton.capability.json.
 program
-    .command("connect")
-    .description("Connect an AI surface (Claude Code, Claude Desktop, Cursor, Raycast) to a Synap pod")
-    .option("--target <name>", "AI surface: claude-code | claude-desktop | cursor | raycast | custom")
+    .command("proton-setup", { hidden: true })
+    .description("(hidden) One-shot Proton Mail↔Synap bridge provisioning")
+    .option("--proton-email <email>", "Proton account email — provisioned into the pod vault")
+    .option("--proton-password <password>", "Proton account password (not a bridge-generated value) — provisioned into the pod vault")
+    .option("--proton-totp-seed <seed>", "Proton account 2FA/TOTP seed, base32 (optional) — provisioned into the pod vault")
+    .option("--proton-mailbox-password <password>", "Proton mailbox password — ONLY for two-password-mode accounts (optional) — provisioned into the pod vault")
+    .option("--bridge-dir <path>", "Path to the synap-proton-bridge repo")
+    .option("--workspace-id <uuid>", "Advanced/legacy: pin the bridge to one workspace (default: pod-wide, never prompted)")
+    .option("--project-id <uuid>", "Scope the bridge to one project (default: prompt, pod-wide if declined)")
+    .option("--pod <name>", "Pod profile to connect the bridge to (default: prompt)")
+    .option("--governance <mode>", "Agent approval preset: safe | creates | normal | crazy (default: prompt; \"follow the pod default\" writes nothing)")
+    .option("--pod-url <url>", "Synap pod URL (override)")
+    .option("--api-key <key>", "Hub Protocol API key (override)")
+    .action(async (opts) => {
+    const { protonSetup } = await import("./commands/proton-setup.js");
+    await protonSetup(opts);
+});
+program
+    .command("connect [thing]")
+    .description("Plug something into your pod: an AI agent (claude-code, cursor, codex, …) or a tool/account (gmail, github, …)")
+    .option("--tool", "Treat <thing> as a tool/account even if it is also an agent name (no <thing>: list connectable services)")
+    .option("--workspace <id>", "Focus on one workspace (default: pod-wide)")
+    .option("--project <id>", "Focus on one project (agents only; composable with --workspace)")
     .option("--pod-url <url>", "Synap pod URL")
     .option("--api-key <key>", "Hub Protocol API key")
-    .option("--name <name>", "Pod profile name to save credentials under (default: 'default')")
-    .option("--list", "List supported targets and exit")
-    .option("--manual-key", "Skip the browser approval flow and paste a key (or provisioning token)")
-    .option("--pin-workspace <id>", "Pin the connection to one workspace (default: pod-wide lens)")
-    .option("--pin-project <id>", "Pin the connection to one project (composable with --pin-workspace)")
-    .action(async (opts) => {
+    .option("--name <name>", "Pod profile to use (default: active pod)")
+    .option("--list", "List what can be connected and exit")
+    .option("--with-mcp", "Raycast only: also install the full 56-tool MCP server via mcp-remote (names overlap @synap)")
+    .option("--target <name>", "Legacy spelling of <thing>")
+    .option("--pin-workspace <id>", "Legacy spelling of --workspace")
+    .option("--pin-project <id>", "Legacy spelling of --project")
+    .action(async (thing, opts) => {
     const { connect } = await import("./commands/connect.js");
-    await connect(opts);
+    await connect(thing, opts);
 });
 // ─── pods ─────────────────────────────────────────────────────────────────────
 const pods = program
@@ -124,6 +150,15 @@ pods
     const { podsUse } = await import("./commands/pods.js");
     await podsUse(name, { surface: opts.surface, json: opts.json });
 });
+pods
+    .command("update <name> [url]")
+    .description("Change a saved pod's URL in place (verifies health + whether the key must be recreated)")
+    .option("--url <url>", "New pod URL (alternative to the positional arg)")
+    .option("--yes", "Non-interactive: skip prompts (won't recreate a rejected key)")
+    .action(async (name, url, opts) => {
+    const { podsUpdate } = await import("./commands/pods.js");
+    await podsUpdate(name, url, { url: opts.url, yes: opts.yes });
+});
 pods
     .command("remove <name>")
     .alias("rm")
@@ -147,6 +182,16 @@ program
     const { status } = await import("./commands/status.js");
     await status({ json: opts.json });
 });
+program
+    .command("doctor")
+    .description("Coherence preflight: pod host resolves, key authenticates, workspace/project exist on THIS pod, and why each configured key does or does not work — catches config drift in one call")
+    .option("--json", "Output as JSON")
+    .option("--fix", "Fix key problems: finish a pending approval, give this computer its own key, or rewrite stale copies — then verify over MCP")
+    .option("-v, --verbose", "Every check with its details, ids and addresses")
+    .action(async (opts) => {
+    const { doctor } = await import("./commands/doctor.js");
+    await doctor(opts);
+});
 program
     .command("versions")
     .description("Show LOCAL vs NPM vs CONTROL-PLANE vs POD version drift for workspace-templates, api-types, and capabilities")
@@ -157,10 +202,11 @@ program
 });
 program
     .command("whoami")
-    .description("Show the winning API key's identity/scopes/workspace and flag env-vs-surface key divergence")
-    .action(async () => {
+    .description("Show key owner vs EFFECTIVE user (+ isAgent), scopes/workspace, and flag env-vs-surface key divergence")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
     const { whoami } = await import("./commands/whoami.js");
-    await whoami();
+    await whoami(opts);
 });
 // Hidden: compact ANSI line for the Claude Code statusLine (reads stdin JSON).
 program
@@ -173,59 +219,10 @@ program
 });
 program
     .command("update")
-    .description("Update synap skill and check for CLI updates")
-    .option("--server", "Also trigger a Dokploy redeploy of the control-plane")
-    .option("--all", "Trigger a Dokploy redeploy of all registered services")
-    .action(async (opts) => {
-    const { update } = await import("./commands/update.js");
-    await update(opts);
-});
-// ─── infra ────────────────────────────────────────────────────────────────────
-const infra = program
-    .command("infra")
-    .description("Manage servers and deployments via Dokploy");
-infra
-    .command("status", { isDefault: true })
-    .description("Overview: all servers and services status")
-    .action(async () => {
-    const { infraStatus } = await import("./commands/infra.js");
-    await infraStatus();
-});
-infra
-    .command("deploy <app>")
-    .description("Trigger a redeploy for a named service")
-    .action(async (app) => {
-    const { infraDeploy } = await import("./commands/infra.js");
-    await infraDeploy(app);
-});
-infra
-    .command("logs <app>")
-    .description("Tail logs for a service")
-    .option("-n, --lines <n>", "Number of log lines", "100")
-    .option("-f, --follow", "Follow log output")
-    .action(async (app, opts) => {
-    const { infraLogs } = await import("./commands/infra.js");
-    await infraLogs(app, { lines: opts.lines ? parseInt(opts.lines, 10) : 100, follow: opts.follow });
-});
-infra
-    .command("sync")
-    .description("Pull Dokploy state into Synap entities (server + deployment profiles)")
-    .option("--pod-url <url>", "Synap pod URL", process.env.SYNAP_POD_URL)
-    .option("--api-key <key>", "Hub Protocol API key", process.env.SYNAP_API_KEY)
-    .action(async (opts) => {
-    if (!opts.podUrl || !opts.apiKey) {
-        console.error("  --pod-url and --api-key are required (or set SYNAP_POD_URL / SYNAP_API_KEY)");
-        process.exit(1);
-    }
-    const { infraSync } = await import("./commands/infra.js");
-    await infraSync(opts.podUrl, opts.apiKey);
-});
-infra
-    .command("open")
-    .description("Open the Dokploy dashboard in your browser")
+    .description("Show how to update the CLI")
     .action(async () => {
-    const { infraOpen } = await import("./commands/infra.js");
-    infraOpen();
+    const { update } = await import("./commands/update.js");
+    await update();
 });
 program
     .command("switch [name]")
@@ -237,11 +234,31 @@ program
 program
     .command("connections")
     .alias("conn")
-    .description("Show which pod each agent surface (Claude Code, Desktop, Cursor, Raycast) is connected to")
+    .description("Show everything connected: which pod each agent points at, and which tools the pod has connected")
     .action(async () => {
     const { connections } = await import("./commands/connections.js");
     await connections();
 });
+// ─── app ────────────────────────────────────────────────────────────────────
+// The App Connect flow: a `synap.app.json` in your app repo → one command wires
+// the app's key into its deploy target. See APP-CONNECT-SPEC §5.
+const app = program
+    .command("app")
+    .description("Connect an app in this repo to your pod (synap.app.json)");
+app
+    .command("init")
+    .description("Write synap.app.json (asks name, pod, permissions) and register the app")
+    .action(async () => {
+    const { appInitCommand } = await import("./commands/app.js");
+    await appInitCommand();
+});
+app
+    .command("connect")
+    .description("Request the app's access, await approval, then write its key into the deploy target")
+    .action(async () => {
+    const { appConnectCommand } = await import("./commands/app.js");
+    await appConnectCommand();
+});
 // ─── mcp ────────────────────────────────────────────────────────────────────
 // The MCP front door: point any AI client at the pod's /mcp server.
 const mcp = program
@@ -271,13 +288,67 @@ mcp
     const { mcpVerify } = await import("./commands/mcp.js");
     await mcpVerify(opts);
 });
+mcp
+    .command("bridge")
+    .description("Stdio MCP server for Claude Code: forwards to the pod and names the conversation (spawned by Claude Code, not run by hand)")
+    .option("--url <url>", "The pod MCP URL to forward to")
+    .action(async (opts) => {
+    const { mcpBridge } = await import("./commands/mcp.js");
+    await mcpBridge(opts);
+});
+mcp
+    .command("use-bridge")
+    .description("Connect Claude Code through the stdio bridge, so work can be traced to and reopened in its conversation")
+    .option("--off", "Switch back to the direct http connection")
+    .action(async (opts) => {
+    const { mcpUseBridge } = await import("./commands/mcp.js");
+    await mcpUseBridge(opts);
+});
 mcp
     .command("connect [client]")
-    .description("Write the MCP config for a file-configurable client (Claude Code, Cursor, Desktop, …) — alias of `synap connect`")
+    .description("Write the MCP config for a file-configurable client (Claude Code, Cursor, Desktop, ChatGPT, …) — alias of `synap agents add <client>`")
     .option("--name <name>", "Pod profile to connect")
     .action(async (client, opts) => {
     const { connect } = await import("./commands/connect.js");
-    await connect({ target: client, name: opts.name });
+    await connect(client, { name: opts.name });
+});
+mcp
+    .command("connect-chatgpt")
+    .description("Connect ChatGPT (web) to Synap — API-key connector to your pod")
+    .option("--name <name>", "Pod profile to connect")
+    .action(async (opts) => {
+    const { connect } = await import("./commands/connect.js");
+    await connect("chatgpt", { name: opts.name });
+});
+mcp
+    .command("connect-chatgpt-oauth")
+    .description("Connect ChatGPT (web) via Control Plane OAuth — multi-pod, no key to paste")
+    .option("--name <name>", "Pod profile to connect")
+    .action(async (opts) => {
+    const { connect } = await import("./commands/connect.js");
+    await connect("chatgpt-oauth", { name: opts.name });
+});
+mcp
+    .command("connect-claude")
+    .description("Print the claude.ai (web) OAuth connection steps — paste a URL, approve in the browser, done")
+    .option("--cp-url <url>", "Control-plane origin override (default: derived from the pod host)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { mcpConnectClaudeWeb } = await import("./commands/mcp.js");
+    await mcpConnectClaudeWeb(opts);
+});
+mcp
+    .command("ui-setup <client>")
+    .description("Print the exact form fields to fill in the client's MCP/Connector UI (ChatGPT, Codex, Cursor, etc.)")
+    .option("--name <name>", "Pod profile to use (default: active)")
+    .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--project <id>", "Focus the agent on a project")
+    .option("--json", "Output as JSON")
+    .action(async (client, opts) => {
+    const { mcpUiSetup } = await import("./commands/mcp.js");
+    await mcpUiSetup(client, opts);
 });
 program
     .command("login")
@@ -295,11 +366,9 @@ program
     }
     const profiles = listPodProfiles();
     if (profiles.length === 0) {
-        // No pod saved — guide to pods add
-        console.log(chalk.dim("  No pod configured yet."));
-        console.log(chalk.blue("  Adding a new pod...\n"));
-        const { podsAdd } = await import("./commands/pods.js");
-        await podsAdd();
+        // No pod saved: sign in to the account first, it finds the pods.
+        const { podsFirstLogin } = await import("./commands/pods.js");
+        await podsFirstLogin();
         return;
     }
     // Already have pods — show status and offer reconnect if any are unreachable
@@ -338,8 +407,23 @@ program
         console.log(`  ${active}${chalk.bold(p.name.padEnd(14))} ${status}  ${chalk.dim(p.config.podUrl)}`);
     }
     console.log();
+    // A computer key (device flow) that expires within 7 days, or has: connect
+    // this computer again now — the pod offers the same computer, so its
+    // agents, history and rules are kept. Never without a person to approve.
+    const { computerKeyNeedsRenewal, connectThisComputer } = await import("./lib/device-connect.js");
+    const renewed = new Set();
+    for (const p of checks.filter((c) => c.healthy && computerKeyNeedsRenewal(c.config))) {
+        const when = `this computer's key ${p.keyValid ? "expires" : "expired"} ${p.config.keyExpiresAt}`;
+        if (!process.stdin.isTTY) {
+            console.log(chalk.yellow(`  ${p.name}: ${when}. Run synap login in a terminal to renew it.`));
+            continue;
+        }
+        console.log(chalk.yellow(`  ${p.name}: ${when}. Renewing it.`));
+        if (await connectThisComputer(p.config.podUrl, { name: p.name }))
+            renewed.add(p.name);
+    }
     // Anything that won't authenticate — unreachable OR a revoked/expired key.
-    const needsReconnect = checks.filter((p) => !p.healthy || !p.keyValid);
+    const needsReconnect = checks.filter((p) => !renewed.has(p.name) && (!p.healthy || !p.keyValid));
     if (needsReconnect.length > 0) {
         console.log(chalk.yellow(`  ${needsReconnect.length} pod(s) need re-authentication. Refresh credentials:`));
         for (const p of needsReconnect) {
@@ -396,6 +480,7 @@ program
     .description("Show a lightweight lens map: who you are, your projects (companies/initiatives), and workspaces (operational domains)")
     .option("--json", "Output as JSON")
     .option("--details", "Include per-workspace profiles + entity counts (heavier)")
+    .option("--workspace <space>", "Orient ONE space by name or id, for this call only — shows its brief (purpose, kinds, rules, skills) without changing your pinned lens")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (opts) => {
@@ -421,9 +506,9 @@ program
 // See what an AI did across flows: the unified run feed, or one run's activity
 // timeline (for a capture: WHY a facet/entity dropped, with a fixHint).
 program
-    .command("diagnose [runId]")
-    .description("See what an AI did — the run feed, or one run's activity (why it did what it did)")
-    .option("--flow <automation|playbook|capture|session>", "Restrict the feed, or the run's flow (default capture for a runId)")
+    .command("diagnose [run]")
+    .description("See what an AI did — the run feed, or one run's nodes (by id or flow name)")
+    .option("--flow <automation|playbook|capture|capability|session|chat>", "Restrict the feed, or narrow the run lookup to one flow")
     .option("--flow-id <id>", "Restrict the feed to one flow's runs (automationId / playbookId)")
     .option("--limit <n>", "Max runs in the feed")
     .option("--json", "Output raw JSON")
@@ -436,7 +521,9 @@ program
 // ─── use ──────────────────────────────────────────────────────────────────────
 program
     .command("use <workspace>")
-    .description("Set the active workspace (by ID or name) — persisted to ~/.synap/config.json")
+    .description("Set the active workspace (by ID or name) — short form of `synap workspace use`. Default scope: this directory")
+    .option("--session", "Ephemeral: scope only this Claude Code session, don't persist")
+    .option("--global", "Durable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -447,7 +534,7 @@ program
 // ─── project / lens (per-Claude-session scoping) ──────────────────────────────
 const project = program
     .command("project")
-    .description("Manage + focus the cross-cutting project lens (a company/initiative): list, new, use, clear");
+    .description("Manage + focus the project lens (a commitment, spanning workspaces): list, new, use, clear");
 project
     .command("list", { isDefault: true })
     .description("List projects on the active pod, with the pinned one marked (bare `synap project` runs this)")
@@ -460,7 +547,7 @@ project
 });
 project
     .command("new <name>")
-    .description("Create a project (a company/initiative) on the active pod, then guide you to pin + add to it")
+    .description("Create a project (a commitment you are driving, with whom) on the active pod, then guide you to pin + add to it")
     .option("--description <text>", "Optional one-line description")
     .option("--json", "Output as JSON (incl. nextSteps for agents)")
     .option("--pod-url <url>", "Pod URL override")
@@ -473,6 +560,7 @@ project
     .command("use <ref>")
     .description("Pin the active project (durable, like `synap use <workspace>`). Ref = uuid, slug, or <pod>/<slug> — cross-pod refs switch the active pod too")
     .option("--session", "Ephemeral: scope only this Claude Code session, don't persist (cross-pod refs refused)")
+    .option("--global", "Durable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -503,8 +591,10 @@ project
 });
 program
     .command("lens")
-    .description("Show this Claude session's lens (workspace + project + focus session)")
+    .description("Show the effective lens (workspace + project + focus session) and WHICH rung set each one")
     .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
     .action(async (opts) => {
     const { showLens } = await import("./commands/lens.js");
     await showLens(opts);
@@ -514,11 +604,12 @@ program
 // procedural (how-to docs), episodic (captures) — and returns a glass-box answer.
 program
     .command("ask <query>")
-    .description("Ask your pod anything — routes to the right knowledge substrate(s) and shows which answered")
+    .description("Ask your pod anything — returns a synthesized answer with its sources")
     .option("--workspace <id>", "Scope to a specific workspace (omit for pod-wide)")
     .option("--limit <n>", "Max results per substrate", "10")
     .option("--json", "Output as JSON")
     .option("--session", "Scope retrieval to the active session context")
+    .option("--raw", "Skip synthesis: show the raw per-substrate matches instead")
     .option("--compare", "A/B diagnostic: show baseline vs Horizon rankers side-by-side (read-only, does not change the answer)")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -527,21 +618,26 @@ program
     await askKnowledge(query, opts);
 });
 // ─── capture ──────────────────────────────────────────────────────────────────
-// Uses the active pod + workspace from config (set via `synap pods use` /
-// `synap use` / `synap workspace provision-agent`). No auth flags needed.
+// Uses the active pod from config. Work-lane knowledge does NOT default-pin
+// the active workspace (omit workspaceId → server-derived / pod-wide preferred);
+// pin only with --workspace or --team.
 program
     .command("capture [text]")
-    .description("Capture knowledge: smart `capture \"<free text>\"` (AI structures it) OR typed `capture --type gotcha --claim \"…\"`")
-    .option("--type <type>", "Typed mode: gotcha|lesson|decision|reference")
+    .description("Capture knowledge: smart `capture \"<free text>\"` (AI structures it). For canonical typed Knowledge, use `create entity --profile=knowledge --props='{\"knowledgeForm\":\"insight|caution\"}'`.")
+    .option("--type <type>", "Legacy compatibility typed mode (gotcha|lesson|decision|reference); new automation should use knowledgeForm")
     .option("--claim <text>", "Typed mode: one-line assertion (required with --type)")
+    .option("--title <text>", "Typed mode: short name, 80 characters or less (default: the claim's first sentence, never cut)")
+    .option("--content <markdown>", "Typed mode: full Markdown explanation, stored as the linked Knowledge note")
     .option("--why <text>", "Reasoning or context")
     .option("--evidence <text>", "Supporting file path, URL, or code snippet")
     .option("--tags <csv>", "Comma-separated tags e.g. repo:synap-backend,layer:migrations")
     .option("--session", "Link captured knowledge to the active session")
-    .option("--global", "GLOBAL lane: pod-wide cross-cutting runbook (→ knowledge_keys), visible in every workspace")
-    .option("--key <ns:slug>", "Stable key for a --global runbook (derived from --type + --claim if omitted)")
-    .option("--team", "Write to the first product workspace instead of the active workspace")
-    .option("--workspace <id>", "Explicit workspace override")
+    .option("--pod-wide", "GLOBAL lane: pod-wide cross-cutting runbook (→ knowledge_keys), visible in every workspace")
+    .option("--global", "Alias for --pod-wide")
+    .option("--key <ns:slug>", "Stable key for a --pod-wide runbook (derived from --type + --claim if omitted)")
+    .option("--team", "Pin to the first product workspace (default: omit workspaceId — server-derived / pod-wide preferred for knowledge)")
+    .option("--workspace <id>", "Explicit workspace pin (otherwise workspaceId is omitted for knowledge)")
+    .option("--project <id|name>", "Pin the capture to a project (id or name) — overrides SYNAP_PROJECT_ID / the session lens")
     .option("--yes", "Skip the y/N confirmation prompt (smart mode)")
     .option("--json", "Output as JSON")
     .action(async (text, opts) => {
@@ -553,10 +649,14 @@ program
 // the SAME AI capture pipeline (/capture/structure → /capture/execute), so it
 // inherits entity extraction, the relation graph, and workspace/project routing.
 program
-    .command("import <inputs...>")
+    .command("import [inputs...]")
     .description("Import files, folders, or URLs into the pod (AI capture pipeline, or Superwhisper store-first)")
     .option("--workspace <id|name>", "Override AI workspace routing")
     .option("--project <id|name>", "Override AI project routing")
+    .option("--home-map <pairs>", "Multi-home path map: pathSubstring=workspaceNameOrId pairs " +
+    '(e.g. "Projects=Builder,Posts=Content OS"). Matched batch paths are ' +
+    "rewritten with the workspace name as the first segment so placement " +
+    "heuristics pin the right home. No product defaults.")
     .option("--dry-run", "Preview only — do not write")
     .option("--yes", "Skip confirmation / auto-confirm store-first")
     .option("--session", "Link created entities to the active session")
@@ -565,14 +665,49 @@ program
     .option("--api-key <key>", "API key override")
     .option("--source <name>", "Adapter: superwhisper (paired meta.json+output.wav store-first)")
     .option("--store-first", "Skip AI structure; store units as pod-wide notes (+ optional audio)")
+    .option("--keep-raw", "Keep the original file and link it to the created entity (default: extract, then discard the bytes)")
     .option("--with-audio", "Upload WAV provenance (default on for --source superwhisper --store-first)")
     .option("--no-with-audio", "Transcript-only (no WAV upload)")
     .option("--limit <n>", "Max Superwhisper units to process", (v) => parseInt(v, 10))
     .option("--concurrency <n>", "Parallel unit uploads (1–4)", (v) => parseInt(v, 10))
     .option("--no-resume", "Ignore local import ledger (re-import all)")
+    .option("--job-status <jobId>", "Re-poll a background corpus import started by an earlier run (no waiting)")
     .action(async (inputs, opts) => {
-    const { importData } = await import("./commands/import.js");
-    await importData(inputs, opts);
+    const mod = await import("./commands/import.js");
+    if (opts.jobStatus) {
+        await mod.importJobStatus(opts.jobStatus, opts);
+        return;
+    }
+    await mod.importData(inputs ?? [], opts);
+});
+// ─── upload ───────────────────────────────────────────────────────────────────
+// Store a real file (arbitrary bytes) on the pod — the door an AI/CLI needs to
+// persist an actual file, not just text. POSTs multipart to /api/hub/files,
+// which mints a `file` entity for the bytes.
+program
+    .command("upload <path>")
+    .description("Upload a file to the pod as an entity (>10MB goes direct to storage: video ≤500MB, audio ≤100MB, zip ≤200MB)")
+    .option("--workspace <id>", "Pin the entity to this workspace (explicit placement)")
+    .option("--profile <slug>", "Entity kind to create (default: file), e.g. brand-asset")
+    .option("--prop <key=value>", "Entity property (repeatable)", (v, acc = []) => [...acc, v])
+    .option("--attach <entityId>", "After upload, link the document to this entity (references relation)")
+    .option("--title <title>", "Title for the created document")
+    .option("--open", "Open in the Synap desktop app after upload")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .addHelpText("after", `
+Examples:
+  synap upload ./report.pdf
+  synap upload ./logo.png --title "Brand logo" --workspace <id>
+  synap upload ./spec.pdf --attach <entityId>
+  synap upload ./logo.svg --profile brand-asset --prop variant=dark --workspace <id>
+  synap upload ./launch.mp4 --workspace <id>
+  synap upload ./report.pdf --open
+  `)
+    .action(async (path, opts) => {
+    const { uploadFile } = await import("./commands/upload.js");
+    await uploadFile(path, opts);
 });
 program
     .command("subscribe")
@@ -628,7 +763,42 @@ program
 // commands (capture, recall, search, …) inherit the active pod + workspace.
 const workspace = program
     .command("workspace")
-    .description("Set up and switch workspace context (run once — persisted to ~/.synap/config.json)");
+    .description("Manage + focus the workspace lens (an operational domain): list, use, clear");
+// `workspace use|list|clear` mirror `project use|list|clear` so the two
+// composable lenses read as siblings. ADDITIVE: the original short form
+// `synap use <workspace>` and `synap list workspaces` are untouched and keep
+// working exactly as before — these are aliases, not replacements.
+workspace
+    .command("use <workspace>")
+    .description("Pin the active workspace by ID or name (durable, like `synap use <workspace>`). Default scope: this directory")
+    .option("--session", "Ephemeral: scope only this Claude Code session, don't persist")
+    .option("--global", "Durable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (ws, opts) => {
+    const { useWorkspace } = await import("./commands/data.js");
+    await useWorkspace(ws, opts);
+});
+workspace
+    .command("list", { isDefault: true })
+    .description("List workspaces you belong to (bare `synap workspace` runs this)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { listWorkspaces } = await import("./commands/data.js");
+    await listWorkspaces(opts);
+});
+workspace
+    .command("clear")
+    .description("Clear the active workspace focus (durable by default)")
+    .option("--session", "Ephemeral: clear only this Claude Code session's workspace")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { clearWorkspace } = await import("./commands/data.js");
+    await clearWorkspace(opts);
+});
 workspace
     .command("provision-agent")
     .description("Provision an agent-owned workspace and set it as active (idempotent)")
@@ -652,6 +822,54 @@ workspace
     const { workspacePurge } = await import("./commands/purge.js");
     await workspacePurge(target, opts);
 });
+// R8a — governed lifecycle: an agent key gets a proposal, an owner key applies.
+workspace
+    .command("archive <workspace>")
+    .description("Archive a workspace (hides it, pauses its workspace automations). Governed: agents propose")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (target, opts) => {
+    const { workspaceArchive } = await import("./commands/workspace-ops.js");
+    await workspaceArchive(target, opts);
+});
+workspace
+    .command("restore <workspace>")
+    .description("Restore an archived workspace (by id). Re-enables nothing; lists automations still paused")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (target, opts) => {
+    const { workspaceRestore } = await import("./commands/workspace-ops.js");
+    await workspaceRestore(target, opts);
+});
+workspace
+    .command("rename <workspace> <newName>")
+    .description("Rename a workspace. Governed: agents propose")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (target, newName, opts) => {
+    const { workspaceRename } = await import("./commands/workspace-ops.js");
+    await workspaceRename(target, newName, opts);
+});
+// R8a — `synap entity move`. (`get/create/set entity` stay under their verbs.)
+program
+    .command("entity")
+    .description("Entity operations: move")
+    .command("move <entityIds...>")
+    .description("Move entities into another workspace. Governed per entity: moved / proposed / errors")
+    .requiredOption("--to <workspace>", "Destination workspace id or name")
+    .option("--reason <text>", "Why they belong there — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (entityIds, opts) => {
+    const { entityMove } = await import("./commands/workspace-ops.js");
+    await entityMove(entityIds, opts);
+});
 // ─── list ─────────────────────────────────────────────────────────────────────
 const list = program
     .command("list")
@@ -765,8 +983,10 @@ const proposals = program
     .description("Review and act on governance proposals");
 proposals
     .command("list", { isDefault: true })
-    .description("List pending governance proposals for this agent")
+    .description("List governance proposals (default: the pending queue)")
+    .option("--status <status>", "pending (default) | approved | auto_approved (what the agent already did) | rejected | expired (never decided) | all", "pending")
     .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--session <id>", "Scope to one focus session (the agent run that filed them)")
     .option("--limit <n>", "Max results", "20")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -777,8 +997,11 @@ proposals
 });
 proposals
     .command("approve <id>")
-    .description("Approve a pending proposal")
+    .description("Approve a pending proposal (interactive only — requires a TTY and a typed confirmation)")
     .option("--reason <text>", "Optional approval note")
+    .option("--verb <verb>", "Same-name choice: fill_empty | keep_existing | use_capture | separate")
+    .option("--existing <uuid>", "Existing record id — required for fill_empty, keep_existing, and use_capture")
+    .option("--yes", "Accepted for symmetry with other commands, but does NOT skip the typed confirmation — approval is always deliberate")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -797,6 +1020,39 @@ proposals
     const { rejectProposal } = await import("./commands/proposals-actions.js");
     await rejectProposal(id, opts);
 });
+proposals
+    .command("await <id>")
+    .description("Block until a proposal is decided. Exit 0 approved · 1 rejected/expired/withdrawn · 2 timeout")
+    .option("--timeout <duration>", "Give up after this long (e.g. 30m, 2h)", "30m")
+    .option("--interval <duration>", "Delay between checks (e.g. 10s)", "10s")
+    .option("--json", "Output the final status as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { awaitProposalCommand } = await import("./commands/proposals-await.js");
+    await awaitProposalCommand(id, opts);
+});
+// ─── worker ───────────────────────────────────────────────────────────────────
+// Run Claude Code unattended on THIS machine for the sessions handed to an agent
+// (the session roster → orient handedToYou). See src/commands/worker.ts.
+program
+    .command("worker")
+    .description("Run Claude Code unattended here for the sessions handed to an agent")
+    .requiredOption("--agent <name>", "The named agent this machine works as (its key comes from ~/.synap)")
+    .option("--interval <dur>", "How often to check for handed sessions (e.g. 30s, 2m)", "30s")
+    .option("--once", "Check once, run what is handed, wait for it, exit")
+    .option("--cwd <dir>", "Where the launched Claude Code works (default ~/Documents/Code/synap)")
+    .option("--max-parallel <n>", "Runs at the same time", "1")
+    .option("--claude-bin <path>", "The claude binary", "claude")
+    .option("--claude-config-dir <dir>", "CLAUDE_CONFIG_DIR for launched runs — picks which Claude subscription they use")
+    .option("--mcp-server <name>", "Claude Code MCP server name for this pod (detected from ~/.claude.json by default)")
+    .option("--allowed-tools <list>", "Comma-separated Claude tools allowed without asking (the pod MCP server is always added)")
+    .option("--skip-permissions", "Launch with --dangerously-skip-permissions instead of an allow-list")
+    .option("--dry-run", "Claim and log what would launch, without launching Claude")
+    .action(async (opts) => {
+    const { workerCommand } = await import("./commands/worker.js");
+    await workerCommand(opts);
+});
 // ─── session ──────────────────────────────────────────────────────────────────
 // Focus sessions — goal-bound work rooms tracked on the pod.
 // AI agents: use start_session to begin, update_session to report progress,
@@ -810,7 +1066,14 @@ session
     .description("Start a new focus session and return its ID")
     .requiredOption("--goal <text>", "What this session is working toward")
     .option("--workspace <id>", "Workspace that owns the session")
+    .option("--project <id>", "Project that owns the session (defaults to the active project lens; the pod accepts a workspace OR a project)")
     .option("--task-id <id>", "Link session to an existing task entity")
+    .option("--track <id>", "Born inside a track (a project's lasting goal) — implies its project")
+    .option("--template <id>", "Start from a playbook (seeds currentStage from its stages)")
+    .option("--no-template", "Opt out of auto-matching a playbook — start ad-hoc")
+    .option("--parent <id>", "Push from another session — records session --spawned_from--> session (the parent stays open)")
+    .option("--suspended-intent <text>", "With --parent: this session BLOCKS the parent. One line naming what the parent was about to do; the parent waits until this session closes")
+    .option("--criteria <file.json>", "Path to a JSON file of binary acceptance criteria (SessionCriterion[])")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -822,7 +1085,9 @@ session
     .command("list", { isDefault: true })
     .description("List focus sessions in the active workspace")
     .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--project <id>", "Scope to a project (its sessions across spaces)")
     .option("--status <status>", "Filter by status: active | paused | closed")
+    .option("--kind <kind>", "Filter by population: work | run | receipt | all", "all")
     .option("--limit <n>", "Max results", "20")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -833,8 +1098,8 @@ session
 });
 session
     .command("get <id>")
-    .description("Show details for a specific focus session")
-    .option("--workspace <id>", "Workspace that owns the session (required for scoped fetch)")
+    .description("Show details for a specific focus session (works for project-scoped sessions)")
+    .option("--workspace <id>", "Workspace hint if the pod still requires it for GET")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -844,10 +1109,14 @@ session
 });
 session
     .command("update <id>")
-    .description("Update progress or status of a focus session")
-    .requiredOption("--workspace <id>", "Workspace that owns the session")
-    .option("--progress <0-100>", "Progress percentage")
+    .description("Update a focus session's progress, status, stage or goal")
+    // NOT required: `workspaceId` is `.optional()` on the pod's UpdateBodySchema
+    // and the session is addressed by <id>. Demanding it made an already-attached
+    // or project-scoped session un-updatable without restating a known lens.
+    .option("--workspace <id>", "Workspace that owns the session (optional; inferred from the active lens)")
+    .option("--progress <0-100>", "Progress percentage — a whole number 0-100, not prose")
     .option("--status <status>", "New status: active | paused")
+    .option("--stage <key>", "Advance the session's current stage (playbook stage key)")
     .option("--goal <text>", "Revised goal")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -858,10 +1127,16 @@ session
 });
 session
     .command("close <id>")
-    .description("Close a focus session and optionally attach a recap")
-    .requiredOption("--workspace <id>", "Workspace that owns the session")
-    .option("--recap <text>", "Short summary of what was accomplished")
-    .option("--json", "Output as JSON")
+    .description("End a focus session (proposal pack) and optionally attach a recap")
+    .option("--workspace <id>", "Workspace hint (optional; not required for complete)")
+    .option("--recap <text>", "Short summary of what was accomplished (maps to summary)")
+    // Deliberately NOT validated here, unlike --progress. A bad --progress
+    // serialized to NaN and came back as an unreadable zod echo; a bad --as comes
+    // back naming the three legal values, because the pod's enum derives from
+    // TERMINAL_SESSION_STATUSES. Re-listing them here would be a second copy of
+    // an enum this CLI cannot import — the hand-mirrored-vocabulary defect.
+    .option("--as <status>", "How it ended: closed (default, finished) | cancelled (abandoned) | failed (could not complete)")
+    .option("--json", "Output full pack (or close result) as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (id, opts) => {
@@ -888,12 +1163,162 @@ session
 });
 session
     .command("current")
-    .description("Show the active session for this terminal (from .synap-session or SYNAP_SESSION_ID)")
+    .description("Show the active session for this terminal (SYNAP_SESSION_ID, Claude-session lens, or .synap/lens.json)")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
     const { sessionStatus } = await import("./commands/sessions.js");
     sessionStatus(opts);
 });
+session
+    .command("evidence <key>")
+    .description("Post your own pass/fail report for one evidence-checked acceptance criterion")
+    .option("--session <id>", "Focus session ID (defaults to this terminal's active session)")
+    .option("--passed", "The criterion is satisfied")
+    .option("--failed", "The criterion is not satisfied")
+    .option("--detail <text>", "Optional note explaining the verdict")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (key, opts) => {
+    const { evidenceSession } = await import("./commands/sessions.js");
+    await evidenceSession(key, opts);
+});
+session
+    .command("evaluate")
+    .description("Run every pending acceptance-criterion check (evidence, capability, judge) and print the verdicts")
+    .option("--session <id>", "Focus session ID (defaults to this terminal's active session)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { evaluateSession } = await import("./commands/sessions.js");
+    await evaluateSession(opts);
+});
+session
+    .command("wait <sessionId>")
+    .description("Block until the human replies in the session room, then print the reply. Exit 0 replied · 1 timeout · 2 failure (auth/network/broken read)")
+    .option("--since <iso>", "Only answers strictly after this ISO timestamp (default: now — skips anything that predates this wait)")
+    .option("--timeout <duration>", "Give up after this long (e.g. 30m, 2h)", "30m")
+    .option("--interval <duration>", "Delay between checks (e.g. 10s)", "10s")
+    .option("--limit <n>", "Max answers per page, 1-100", "20")
+    .option("--json", "Output the reply(ies) — or the timeout — as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (sessionId, opts) => {
+    const { waitSessionCommand } = await import("./commands/session-wait.js");
+    await waitSessionCommand(sessionId, opts);
+});
+// ─── playbook ─────────────────────────────────────────────────────────────────
+// Start a governed process in one step — the Hub door MCP synap_run_playbook
+// shares. A proposal ("queued for your review") is success.
+const playbookCmd = program
+    .command("playbook")
+    .description("Run playbooks — governed, reusable processes");
+playbookCmd
+    .command("run <name-or-id>")
+    .description("Run a playbook by name or id, optionally on a subject entity")
+    .option("--subject <entityId>", "The entity the playbook runs on")
+    .option("--param <key=value>", "Answer a declared param (repeatable; typed by the playbook)", collect, [])
+    .option("--workspace <id>", "Write home for the run (defaults to the playbook's own workspace)")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (ref, opts) => {
+    const { runPlaybook } = await import("./commands/playbook.js");
+    await runPlaybook(ref, opts);
+});
+// ─── track ────────────────────────────────────────────────────────────────────
+// A LASTING goal inside a project, worked in sessions (`session start --track`).
+// Legacy tracks also run a method with steps. Writes are governed —
+// "queued for your review" is success.
+const track = program
+    .command("track")
+    .description("Manage tracks — the lasting goals a project pursues");
+track
+    .command("list")
+    .description("List a project's tracks (defaults to the active project lens)")
+    .option("--project <id>", "Project id (defaults to the active project lens)")
+    .option("--all", "Include archived tracks")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { listTracks } = await import("./commands/tracks.js");
+    await listTracks(opts);
+});
+track
+    .command("show <id>")
+    .description("Show one track: its steps and where it stands")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { showTrack } = await import("./commands/tracks.js");
+    await showTrack(id, opts);
+});
+track
+    .command("start")
+    .description("Start a track — a lasting goal — on a project")
+    .option("--name <name>", "The track's name (required without --playbook)")
+    .option("--direction <text>", "Where it is heading, one line")
+    .option("--playbook <id>", "Legacy: a track template (project-scoped playbook with steps)")
+    .option("--project <id>", "Project id (defaults to the active project lens)")
+    .option("--param <key=value>", "Answer a declared param (repeatable)", collect, [])
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { startTrack } = await import("./commands/tracks.js");
+    await startTrack(opts);
+});
+track
+    .command("advance <id> <stage>")
+    .description("Legacy (tracks with steps): move a track to a step; prints the session that step offers")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, stage, opts) => {
+    const { advanceTrack } = await import("./commands/tracks.js");
+    await advanceTrack(id, stage, opts);
+});
+track
+    .command("status <id> <status>")
+    .description("Pause, resume or archive a track (active|paused|archived)")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, status, opts) => {
+    const { setTrackStatus } = await import("./commands/tracks.js");
+    await setTrackStatus(id, status, opts);
+});
+track
+    .command("params <id> <pairs...>")
+    .description("Answer the method's params as key=value (merged; key=null clears one)")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, pairs, opts) => {
+    const { setTrackParams } = await import("./commands/tracks.js");
+    await setTrackParams(id, pairs, opts);
+});
+track
+    .command("start-step <id>")
+    .description("Legacy (tracks with steps): start one step's session — on a track with no steps, use 'session start --track'")
+    .option("--stage <key>", "Step key (defaults to the current step)")
+    .option("--title <text>", "Session name (defaults to the step's name)")
+    .option("--goal <text>", "Outcome (defaults to the step's goal)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { startStep } = await import("./commands/tracks.js");
+    await startStep(id, opts);
+});
 // ─── skill ────────────────────────────────────────────────────────────────────
 // Autonomous workspace session skills — context gathering, task planning, etc.
 const skillCmd = program
@@ -953,6 +1378,16 @@ skillCmd
     const { listSkills } = await import("./commands/skill-manage.js");
     await listSkills(opts);
 });
+skillCmd
+    .command("approve <slug-or-id>")
+    .description("Approve a skill so it loads (agent-authored skills are born unapproved)")
+    .option("--revoke", "Revoke approval instead of granting it")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (ref, opts) => {
+    const { approveSkill } = await import("./commands/skill-manage.js");
+    await approveSkill(ref, opts);
+});
 skillCmd
     .command("remove <slug>")
     .alias("rm")
@@ -1015,6 +1450,28 @@ observe
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (text, opts) => {
+    // `write` is the DEFAULT subcommand, so an unrecognized token lands here as
+    // `text` instead of erroring — and this default WRITES. `synap observe recal`
+    // therefore recorded an observation literally reading "recal" into the
+    // AI-maintained user model, silently. Every other `isDefault` group in this
+    // file has a zero-arg default, which commander rejects on its own; this is
+    // the only one that can absorb a typo, and the only one where absorbing it
+    // is a mutation.
+    //
+    // The guard keys off whether `write` was named EXPLICITLY, not off the text:
+    // a mistyped subcommand is always a single bare token, and a real
+    // observation is a sentence. Going through `observe write <text>` skips the
+    // check entirely, so the escape hatch is real rather than circular.
+    const argv = process.argv;
+    const observeAt = argv.indexOf("observe");
+    const explicitWrite = observeAt !== -1 && argv[observeAt + 1] === "write";
+    if (!explicitWrite && !/\s/.test(text.trim())) {
+        const siblings = observe.commands.map((c) => c.name()).filter((n) => n !== "write");
+        console.error(`error: '${text}' looks like a subcommand, not observation text — nothing was recorded.\n` +
+            `  Available: ${siblings.map((n) => `synap observe ${n}`).join(", ")}\n` +
+            `  To record it as an observation anyway: synap observe write ${JSON.stringify(text)}`);
+        process.exit(1);
+    }
     const { observeWrite } = await import("./commands/observe.js");
     await observeWrite(text, opts);
 });
@@ -1054,6 +1511,7 @@ create
     .description("Create a new entity")
     .requiredOption("--profile <slug>", "Profile slug (e.g. person, note, task)")
     .requiredOption("--name <name>", "Entity name")
+    .option("--content <markdown>", "Long-form Markdown body, stored as the entity's linked document")
     .option("--workspace <id>", "Create in this workspace")
     .option("--props <json>", "Properties as JSON string", "{}")
     .option("--json", "Output as JSON")
@@ -1096,43 +1554,48 @@ set
 // ─── agents ───────────────────────────────────────────────────────────────────
 const agents = program
     .command("agents")
-    .description("Manage named agent identities (different keys, different pod access)");
+    .description("Manage agent principals on your pod (one per type for you; local keys are a cache)");
 agents
     .command("list", { isDefault: true })
-    .description("List configured agent identities")
+    .description("List your agents on this pod (one per type). Use --local for ~/.synap cache only.")
     .option("--json", "Output as JSON")
+    .option("--local", "List only the local ~/.synap agent cache")
     .action(async (opts) => {
     const { agentsList } = await import("./commands/agents.js");
-    agentsList(opts);
+    await agentsList(opts);
 });
 agents
-    .command("add")
-    .description("Register a pre-existing agent credential locally. Use `synap agents create` for new agents.")
-    .option("--name <name>", "Agent name (e.g. researcher, builder)")
-    .option("--api-key <key>", "Hub Protocol API key for this agent")
-    .option("--pod <name>", "Pod profile to link (default: active pod)")
-    .option("--workspace <id>", "Default workspace for this agent")
+    .command("add [kind]")
+    .description("Bring an agent into the pod: a client (claude-code, cursor, codex, …), your own (--name → URL + key), or pick from this machine (no kind)")
+    .option("--name <name>", "Name your own agent (e.g. researcher) — prints a URL + key to paste")
+    .option("--template <tmpl>", "Your own agent's template: twin | assistant | custom (default: custom)")
+    .option("--type <type>", "Explicit agent type for your own agent (default: a slug of --name)")
+    .option("--role <role>", "Workspace role: admin | editor | viewer (default: editor)")
+    .option("--workspace <id>", "Focus on one workspace (default: pod-wide)")
+    .option("--project <id>", "Focus on one project (composable with --workspace)")
+    .option("--with-mcp", "Raycast only: also install the full MCP server via mcp-remote")
+    .option("--api-key <key>", "Register a key you already hold, on this machine only (mints nothing)")
     .option("--label <label>", "Human-readable description")
-    .action(async (opts) => {
+    .action(async (kind, opts) => {
     const { agentsAdd } = await import("./commands/agents.js");
-    await agentsAdd(opts);
+    await agentsAdd(kind, opts);
 });
 agents
     .command("create")
-    .description("Create a new agent on the pod (template-aware). Replaces `add` for new agents.")
+    .description("Deprecated — use `synap agents add` (same flags)")
     .option("--template <tmpl>", "Agent template: twin | assistant | custom (default: custom)")
     .option("--name <name>", "Agent name (not needed for twin — auto-generated)")
     .option("--type <type>", "Agent type string for custom agents (default: matches template)")
-    .option("--role <role>", "Workspace role: admin | editor | viewer (default: editor; twin auto-inherits)")
-    .option("--workspace <id>", "Workspace ID to add the agent to (auto-detected if omitted)")
-    .option("--pod <name>", "Pod profile to use (default: active pod)")
+    .option("--role <role>", "Workspace role: admin | editor | viewer (default: editor)")
+    .option("--workspace <id>", "Focus on one workspace (default: pod-wide)")
+    .option("--project <id>", "Focus on one project")
     .action(async (opts) => {
     const { agentsCreate } = await import("./commands/agents.js");
     await agentsCreate(opts);
 });
 agents
     .command("rotate-key <name-or-id>")
-    .description("Rotate the Hub Protocol API key for an agent (invalidates the current key)")
+    .description("Rotate the Hub Protocol API key for an agent (local cache only)")
     .action(async (nameOrId) => {
     const { agentsRotateKey } = await import("./commands/agents.js");
     await agentsRotateKey(nameOrId);
@@ -1140,17 +1603,19 @@ agents
 agents
     .command("remove <name>")
     .alias("rm")
-    .description("Remove a named agent identity")
+    .description("Remove a named agent identity (local cache only)")
     .action(async (name) => {
     const { agentsRemove } = await import("./commands/agents.js");
     agentsRemove(name);
 });
 agents
     .command("info <name>")
-    .description("Show details for a named agent identity")
-    .action(async (name) => {
+    .description("Show details for a named agent identity (local cache only)")
+    .option("--show-key", "Print the MCP URL and the full API key")
+    .option("--snippets", "Print paste-ready configs (Claude Code, Cursor, stdio clients)")
+    .action(async (name, opts) => {
     const { agentsInfo } = await import("./commands/agents.js");
-    agentsInfo(name);
+    await agentsInfo(name, opts);
 });
 // ─── agent (autonomous runner) ───────────────────────────────────────────────
 const agent = program
@@ -1228,6 +1693,52 @@ agent
     const { agentTick } = await import("./commands/agent-run.js");
     await agentTick(opts);
 });
+// ─── automate ───────────────────────────────────────────────────────────────
+// The natural-language automation door. It stays deliberately separate from
+// `automation create`, which remains the expert, explicit-DSL path.
+program
+    .command("automate <instruction>")
+    .description("Ask the workspace agent to prepare a governed automation proposal")
+    .option("--workspace <id|name>", "Workspace to use (uses active workspace/lens if omitted)")
+    .option("--thread <id>", "Continue an existing agent thread/channel")
+    .option("--new", "Start a fresh agent thread")
+    .option("--timeout <seconds>", "How long to wait for the agent's reply (default: 90)")
+    .option("--json", "Machine-readable output { ok, reply, threadId, workspaceId }")
+    .option("--pod-url <url>", "Override pod URL")
+    .option("--api-key <key>", "Override API key")
+    .action(async (instruction, opts) => {
+    const { automate } = await import("./commands/automate.js");
+    await automate(instruction, opts);
+});
+// ─── rule ────────────────────────────────────────────────────────────────────
+// The fourth door, beside `ask` (recall), `capture` (write) and `diagnose`
+// (inspect): a STANDING instruction. It classifies the sentence and shows the
+// reading before writing anything — and it records the rule only. Building the
+// behaviour half is still `synap automate`.
+const ruleCmd = program
+    .command("rule [text]")
+    .description("State a standing rule in plain language — classified, shown, then governed-created")
+    .option("--workspace <id>", "Workspace to scope the rule to (uses active workspace if omitted)")
+    .option("--pod-wide", "Scope the rule to the whole pod, ignoring the active workspace")
+    .option("--yes", "Skip the one-off confirmation (never skips a clarification)")
+    .option("--json", "Output raw JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (text, opts) => {
+    const { rule } = await import("./commands/rule.js");
+    await rule(text ?? "", opts);
+});
+ruleCmd
+    .command("list")
+    .description("List rules with their intent, scope, and whether a behaviour is attached")
+    .option("--workspace <id>", "Filter by workspace")
+    .option("--json", "Output raw JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { ruleList } = await import("./commands/rule.js");
+    await ruleList(opts);
+});
 // ─── automation ──────────────────────────────────────────────────────────────
 function collect(val, prev) { return [...prev, val]; }
 const automation = program
@@ -1419,12 +1930,11 @@ program
     .description("Open in the Synap desktop app. Use: open <kind> <id> or open <id> (auto-resolves type)")
     .action(async (kindOrId, id) => {
     if (id) {
-        // open entity|view|cell|document|proposal <id>
-        const validKinds = ["entity", "view", "cell", "document", "proposal"];
-        if (!validKinds.includes(kindOrId)) {
-            console.error(`Unknown kind: "${kindOrId}". Use: ${validKinds.join(" | ")}`);
-            process.exit(1);
-        }
+        // open <kind> <id> — the browser's object-nav.ts is the one route
+        // table for openable kinds (21 and growing); the CLI doesn't
+        // duplicate it here. An unroutable kind still opens the app and
+        // is reported via the printed deep link (objectNavTarget decides
+        // routability on the other side).
         const { openInBrowser } = await import("./commands/open.js");
         await openInBrowser({ kind: kindOrId, id });
     }
@@ -1461,10 +1971,12 @@ Examples:
 });
 doc
     .command("update <documentId>")
-    .description("Update a document's content (full replacement, proposal-gated)")
+    .description("Update a document's content: the whole body, or one section (--section). Governed: an agent's edit is proposed.")
     .option("--content <text>", "New markdown content (inline)")
     .option("--file <path>", "Read new content from a file")
-    .option("--title <title>", "Update document title (requires --content too)")
+    .option("--section <id>", "Write ONE section by id (content = the section body) instead of the whole document")
+    .option("--section-title <title>", "The section heading (required with --section)")
+    .option("--base-revision <n>", "The revision you read; refused if the document changed since")
     .option("--open", "Open in the Synap desktop app after update")
     .option("--json", "JSON output")
     .option("--pod-url <url>", "Pod URL override")
@@ -1474,11 +1986,29 @@ Examples:
   synap doc update <id> --content "# Updated"
   synap doc update <id> --file ./notes.md
   cat notes.md | synap doc update <id>
+  synap doc update <id> --section risks --section-title "Risks" --file ./risks.md
   `)
     .action(async (documentId, opts) => {
     const { docUpdate } = await import("./commands/doc.js");
     await docUpdate(documentId, opts);
 });
+doc
+    .command("reference <url>")
+    .description("Create an external reference document (points at a URL — no bytes stored)")
+    .requiredOption("--title <title>", "Document title")
+    .option("--workspace <id>", "Workspace to create the reference in")
+    .option("--open", "Open in the Synap desktop app after creation")
+    .option("--json", "JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .addHelpText("after", `
+Examples:
+  synap doc reference https://example.com/spec --title "Vendor spec"
+  `)
+    .action(async (url, opts) => {
+    const { docReference } = await import("./commands/doc.js");
+    await docReference(url, opts);
+});
 // ─── cell ─────────────────────────────────────────────────────────────────────
 const cell = program
     .command("cell")
@@ -1489,17 +2019,30 @@ cell
     .requiredOption("--name <name>", "Cell display name")
     .option("--file <path>", "ESM source file (or pipe stdin)")
     .option("--type-key <key>", "Explicit typeKey (default: generated:<slug>)")
-    .option("--deps <json>", 'Dependency map JSON, e.g. \'{"recharts":"2.12.0"}\' (sent in payload; backend support pending)')
-    .option("--workspace <id>", "Workspace to scope the cell to (omit for pod-global)")
+    .option("--deps <json>", 'Dependency map JSON, e.g. \'{"recharts":"2.12.0"}\'')
+    .option("--view-types <list>", 'Comma-separated view types this cell can render as a VIEW RENDERER, e.g. "list,table,kanban". Omit to leave an existing affinity untouched; pass "" to clear it')
+    .option("--content-kind <kind>", "What this cell renders — entity-detail | entity-card | entity-profile | collection | widget (default: widget, which is placeable but never offered as a profile renderer)")
+    // NOT "omit for pod-wide": `cell.ts` resolves `opts.workspace ?? cfg.workspaceId`,
+    // and `cfg.workspaceId` is the resolved lens (session › directory › env ›
+    // profile default). Omitting therefore scopes the cell to whatever workspace
+    // your lens currently points at — which is pod-wide ONLY when nothing resolves.
+    // Verified 2026-09-05: run from a directory with no `.synap/lens.json` and the
+    // cell silently lands in the pod profile's default workspace.
+    .option("--workspace <id>", "Workspace to scope the cell to (default: your active workspace lens — run `synap lens` to see it)")
     .option("--description <text>", "Short description")
     .option("--open", "Open in the Synap desktop app after define")
     .option("--json", "JSON output")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .addHelpText("after", `
+Without --view-types / --content-kind a cell installs cleanly but can never be
+PICKED as a view or profile renderer — it is only placeable on a bento.
+
 Examples:
   synap cell define --name "Revenue Chart" --file ./chart.js
   synap cell define --name "Revenue Chart" --file ./chart.js --deps '{"recharts":"2.12.0"}'
+  synap cell define --name "Deal Board" --file ./board.js --view-types kanban,table --content-kind collection
+  synap cell define --name "Contact Page" --file ./contact.js --content-kind entity-detail
   cat chart.js | synap cell define --name "Revenue Chart"
   `)
     .action(async (opts) => {
@@ -1510,10 +2053,16 @@ cell
     .command("build <entry>")
     .description("Bundle a multi-file cell/app into a single ESM module the runtime expects")
     .option("--out <file>", "Output file path (default: <entry>.bundle.js)")
+    .option("--bundle-deps", "Inline all third-party deps into the bundle (only react/react-dom stay external) — output has deps={} and the runtime CSP drops esm.sh entirely")
+    .option("--self-contained", 'Build ONE complete HTML document (React, CSS, brand fonts inlined; nothing external) — the code of a rendererType "mcp-app" cell')
+    .option("--fonts", "With --self-contained: require the inlined brand fonts (default: include when @synap-core/design-tokens resolves)")
+    .option("--no-fonts", "With --self-contained: skip the inlined brand fonts")
     .option("--define", "Chain into cell define after bundling (requires --name)")
     .option("--name <name>", "Cell name (required with --define)")
     .option("--type-key <key>", "Explicit typeKey (used with --define)")
     .option("--deps <json>", "Override dependency versions as JSON, e.g. '{\"react\":\"18.3.0\"}'")
+    .option("--view-types <list>", 'Comma-separated view-renderer affinity (used with --define), e.g. "list,table"')
+    .option("--content-kind <kind>", "entity-detail | entity-card | entity-profile | collection | widget (used with --define)")
     .option("--workspace <id>", "Workspace (used with --define)")
     .option("--description <text>", "Description (used with --define)")
     .option("--open", "Open in browser after define (used with --define)")
@@ -1521,12 +2070,20 @@ cell
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .addHelpText("after", `
-Output: a single ESM file. Bare imports (react, recharts, …) are externalized
-and emitted as a deps map. At runtime Synap resolves them via esm.sh importmap.
+Output: a single ESM file.
+
+Default mode: bare imports (react, recharts, …) are externalized and emitted
+as a deps map. At runtime Synap resolves them via esm.sh importmap.
+
+--bundle-deps mode: only react/react-dom are externalized (React is
+host-inlined at runtime, never via esm.sh); everything else is bundled into
+the output, so the deps map is empty. A cell built this way reaches no esm.sh
+origin at runtime — the runtime CSP collapses to drop it entirely.
 
 Examples:
   synap cell build ./src/chart.tsx --out ./dist/chart.js
   synap cell build ./src/chart.tsx --out ./dist/chart.js --define --name "Revenue Chart"
+  synap cell build ./src/chart.tsx --out ./dist/chart.js --bundle-deps
   `)
     .action(async (entry, opts) => {
     const { cellBuild } = await import("./commands/cell.js");
@@ -1576,7 +2133,7 @@ tools
 });
 tools
     .command("connect <service>")
-    .description("Connect a credential to a tool (via Nango OAuth or vault)")
+    .description("Connect a credential to a tool (OAuth via the connection broker, or vault)")
     .option("--workspace <id>", "Workspace context")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -1641,6 +2198,33 @@ podCmd
     const { podAdopt } = await import("./commands/pod.js");
     await podAdopt(workspaceNameOrId, opts);
 });
+// ─── vendor — the author's publisher profile ─────────────────────────────────
+// Attribution is write-time-only at the CP: a package published before a vendor
+// exists is orphaned from its author forever. See src/commands/vendor.ts.
+const vendor = program
+    .command("vendor")
+    .description("Your marketplace publisher profile (what packages are attributed to)");
+vendor
+    .command("create <slug>")
+    .description("Create your publisher profile — do this BEFORE your first publish")
+    .option("--name <name>", "Display name (defaults to a title-cased slug)")
+    .option("--description <text>", "Short description of you or your studio")
+    .option("--website <url>", "Website URL (must be a full URL)")
+    .option("--json", "Output as JSON")
+    .action(async (slug, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const { vendorCreate } = await import("./commands/vendor.js");
+    await vendorCreate(slug, opts);
+});
+vendor
+    .command("show")
+    .description("Show whether you have a publisher profile")
+    .option("--json", "Output as JSON")
+    .action(async (_opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const { vendorShow } = await import("./commands/vendor.js");
+    await vendorShow(opts);
+});
 // ─── market — discover + install ANY package type ────────────────────────────
 // launch is workspace-first (bundled, offline); market reaches every CP package
 // type (capability/skill/workflow/view/cell/workspace), public or private.
@@ -1659,7 +2243,9 @@ market
     .command("install <slug>")
     .description("Install a package by slug into a project — workspaces install now; other types route you to the right surface")
     .option("--project <id>", "Optionally tag the seeded entities to a project (installs are pod-wide by default)")
+    .option("--workspace <id>", "Acting workspace (UUID) a workflow/automation package is added to (required for that kind; defaults to your active lens). Ignored for pod-wide kinds")
     .option("--onto <workspaceId>", "Reconcile this template ONTO an existing workspace (additive) instead of creating a new one")
+    .option("--dry-run", "Preview the create path write-free — report would-create / reuse / conflicts, install nothing")
     .option("--timeout <seconds>", "How long to wait for the apply to finish (default: 120)")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -1678,7 +2264,8 @@ market
 market
     .command("update [slugs...]")
     .description("Check installed packages for drift against the catalog, and re-apply the ones that are stale (all with --yes, specific ones with explicit slugs)")
-    .option("--yes", "Apply every available update without prompting (no slugs required)")
+    .option("--yes", "Apply every available update without prompting (no slugs required), agreeing to every data change it lists")
+    .option("--accept-data-changes <opKeys>", "Agree to exactly these data changes (comma-separated opKeys from the preview)")
     .option("--dry-run", "Force the preview path — never apply, even with --yes")
     .option("--timeout <seconds>", "How long to wait for each package's apply to finish (default: 120)")
     .option("--json", "Output as JSON")
@@ -1703,6 +2290,209 @@ market
     const { marketInstalled } = await import("./commands/market.js");
     await marketInstalled(opts);
 });
+market
+    .command("workspaces")
+    .description("List your workspaces with their template-attachment status — find the one that isn't attached yet (pure read)")
+    .option("--unattached", "Only show workspaces that need attention (unattached or missing a version stamp)")
+    .option("--json", "Output as JSON")
+    .action(async (_opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketWorkspaces } = await import("./commands/market.js");
+    await marketWorkspaces(opts);
+});
+market
+    .command("attach <workspaceId>")
+    .description("Reconcile a marketplace template onto an existing workspace + version-stamp it — how you relink a workspace installed before the marketplace")
+    .option("--slug <slug>", "Template to attach (inferred from the workspace's existing attachment or domain when omitted)")
+    .option("--project <id>", "Optionally tag the reconciled entities to a project")
+    .option("--timeout <seconds>", "How long to wait for the apply to finish (default: 120)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (workspaceId, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketAttach } = await import("./commands/market.js");
+    await marketAttach(workspaceId, opts);
+});
+// ── `synap templates` — the ONE home for workspace ↔ template health ─────────
+// Consolidates `market update`/`workspaces`/`installed`: one grouped, action-
+// ranked view where an UNATTACHED workspace is visible (it wasn't in `update`),
+// with a suggested template and a one-word attach. The `market *` subcommands
+// still work — this is the front door, not a breaking rename.
+const templates = program
+    .command("templates")
+    .description("See every workspace's template status (attached, drifted, or unattached) and connect them — the one home for template health")
+    .option("--needs-attention", "Show only workspaces that need action (drifted / unstamped / unattached-with-suggestion)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (_opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const { marketTemplates } = await import("./commands/market.js");
+    await marketTemplates(opts);
+});
+templates
+    .command("attach <workspace>")
+    .description("Connect a workspace (by NAME or id) to a template — suggests the right one so you don't guess a slug")
+    .option("--slug <slug>", "Force a specific template instead of the suggestion")
+    .option("--yes", "Accept a confident (domain-match) suggestion without prompting — for scripts")
+    .option("--project <id>", "Optionally tag the reconciled entities to a project")
+    .option("--timeout <seconds>", "How long to wait for the apply to finish (default: 120)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (workspace, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const { templatesAttach } = await import("./commands/market.js");
+    await templatesAttach(workspace, opts);
+});
+templates
+    .command("update [slugs...]")
+    .alias("updates")
+    .description("Apply template updates — 'update all' (or --yes) for every drifted workspace, or name specific slugs. Bare 'update' previews what's available.")
+    .option("--yes", "Apply every available update without prompting, agreeing to every data change it lists")
+    .option("--accept-data-changes <opKeys>", "Agree to exactly these data changes (comma-separated opKeys from the preview)")
+    .option("--dry-run", "Preview only — never apply")
+    .option("--timeout <seconds>", "How long to wait for each apply (default: 120)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (slugs, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    // `update all` reads more naturally than `--yes` and is what people type —
+    // treat the literal word "all" as "apply every available update". It is NOT
+    // `--yes`: data changes still need the person's agreement (asked, or flagged).
+    const wantsAll = !!slugs?.some((s) => s.toLowerCase() === "all");
+    const explicit = (slugs ?? []).filter((s) => s.toLowerCase() !== "all");
+    const { marketUpdate } = await import("./commands/market.js");
+    await marketUpdate(explicit.length > 0 ? explicit : undefined, wantsAll ? { ...opts, all: true } : opts);
+});
+templates
+    .command("retire <target>")
+    .description("Move a retired template's space into its replacement (by template slug, workspace name or id). Shows the plan, asks, then moves through the pod — never deletes.")
+    .option("--dry-run", "Show the plan only — move nothing")
+    .option("--yes", "Move without asking (for scripts)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (target, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const { templatesRetire } = await import("./commands/templates-retire.js");
+    await templatesRetire(target, opts);
+});
+// ── Authoring loop: scaffold → validate → publish → unpublish ────────────────
+market
+    .command("scaffold <slug>")
+    .description("Write a minimal valid <slug>.template.yaml to edit in place (refuses to overwrite)")
+    // This list MUST equal `SCAFFOLDABLE_KINDS` (src/lib/kind-package.ts). It is
+    // written out rather than imported because index.ts keeps its eager module
+    // graph to commander + one lib — importing kind-package.ts here would pull
+    // `yaml` into the startup path of every `synap` invocation. What keeps the two
+    // honest is `test/scaffold-kind-help-parity.test.ts`, which source-scans both.
+    //
+    // It advertised `skill` — which `marketScaffold` refuses, since the CP package
+    // schema has no standalone slot for one — and omitted `workflow`, which
+    // `market validate` has always accepted. A help string that offers a refused
+    // option and hides a working one is the documented-loop defect class.
+    .option("--kind <kind>", "Scaffold a standalone package instead of a workspace template: cell, view, workflow, capability, skill")
+    .option("--json", "Output as JSON")
+    .action(async (slug, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketScaffold } = await import("./commands/market-authoring.js");
+    await marketScaffold(slug, opts);
+});
+market
+    .command("validate <file>")
+    .description("Validate a local template file against the shared template validator — fast author feedback")
+    .option("--json", "Output the validator result as JSON")
+    .action(async (file, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketValidate } = await import("./commands/market-authoring.js");
+    await marketValidate(file, opts);
+});
+market
+    .command("publish [targets...]")
+    .description("Validate then publish a template (or a standalone cell/view package) to the marketplace (private by default) — pass a file, --from-workspace <id>, or --from-project <id>. Non-official publish never uses the synap-official vendor. Founder: --official [slug...] publishes the official catalog from the monorepo checkout (alias of `synap catalog publish --official --kind workspace`)")
+    .option("--official", "Publish the OFFICIAL Synap catalog (all templates, or the named slugs) from the monorepo checkout — requires a `synap login` session that owns the synap-official vendor; previews and asks first")
+    .option("--templates-dir <dir>", "With --official: path to the catalog package — synap-app/packages/catalog or workspace-templates (default: found by walking up from cwd)")
+    .option("--dry-run", "With --official: preview what would change against the live catalog, publish nothing")
+    .option("--yes", "With --official: skip the confirmation prompt")
+    .option("--public", "Publish as PUBLIC (default is private)")
+    .option("--private", "Publish as private (the default — stated explicitly)")
+    .option("--from-workspace <id>", "Serialize a live workspace into a template and publish it (instead of a file)")
+    .option("--from-project <id>", "Serialize a live project's used workspaces into a suite package (tags: suite, require deps) and publish it")
+    .option("--price <usd>", "Stamp pricingModel=one_time + priceUsd (dollars→cents). Settlement/Stripe is not this wave — columns only.")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override (for --from-workspace / --from-project)")
+    .option("--api-key <key>", "API key override (for --from-workspace / --from-project)")
+    // Default ON for a cell package's `codeFile` resolution — see `cell build
+    // --bundle-deps`'s doc comment for why: a published cell's `deps` map is
+    // otherwise resolved through esm.sh at RUNTIME, so the artifact reviewed at
+    // publish time isn't what actually executes. `synap cell build` invoked
+    // directly is unaffected — its own default stays external-deps-via-esm.sh.
+    .option("--no-bundle-deps", "Publish a cell's codeFile with external deps via esm.sh instead of bundling them in (default: bundled)")
+    .action(async (targets, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const args = targets ?? [];
+    if (opts.official) {
+        const { marketPublishOfficial } = await import("./commands/market-official.js");
+        process.exitCode = await marketPublishOfficial(args, opts);
+        return;
+    }
+    const { nonOfficialUsageError } = await import("./commands/market-official.js");
+    const usage = nonOfficialUsageError(args, opts);
+    if (usage) {
+        console.error(`  ✗ ${usage}`);
+        process.exitCode = 2;
+        return;
+    }
+    const { marketPublish } = await import("./commands/market-authoring.js");
+    await marketPublish(args[0], opts);
+});
+market
+    .command("unpublish <slug>")
+    .description("Flip a published package back to private (owner only)")
+    .option("--json", "Output as JSON")
+    .action(async (slug, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketUnpublish } = await import("./commands/market-authoring.js");
+    await marketUnpublish(slug, opts);
+});
+// ─── catalog ──────────────────────────────────────────────────────────────────
+// The team's ONE door to the official catalog (every installable kind). Thin
+// wiring: `runCatalog` (commands/catalog.ts) calls the ONE catalog lib in the
+// monorepo checkout. `market publish --official` is its alias (kind workspace).
+const catalog = program
+    .command("catalog")
+    .description("Validate, diff and publish the OFFICIAL template catalog (workspaces, capabilities, skills, packs, automations) from the monorepo checkout");
+for (const verb of ["validate", "diff", "publish"]) {
+    const sub = catalog
+        .command(`${verb} [slugs...]`)
+        .description(verb === "validate"
+        ? "Validate the catalog (per-kind schema, cross-kind refs, goal grammar, duplicates) — offline"
+        : verb === "diff"
+            ? "Show what would change against the live control-plane catalog (new / changed / unchanged)"
+            : "Validate, preview the diff, confirm, then publish to the control plane — founder only: --official + a `synap login` session that owns synap-official")
+        .option("--kind <kind>", "Only this kind: workspace | capability | skill | pack | automation")
+        .option("--catalog-dir <dir>", "Path to the catalog package (default: found by walking up from cwd)")
+        .option("--json", "Output as JSON");
+    if (verb === "publish") {
+        sub
+            .option("--official", "Publish as the synap-official vendor (required)")
+            .option("--dry-run", "Preview the diff only — publish nothing")
+            .option("--yes", "Skip the confirmation prompt");
+    }
+    sub.action(async (slugs, opts) => {
+        const { runCatalog } = await import("./commands/catalog.js");
+        process.exitCode = await runCatalog(verb, slugs ?? [], opts);
+    });
+}
 // ─── capability ───────────────────────────────────────────────────────────────
 const capability = program
     .command("capability")
@@ -1755,6 +2545,7 @@ capability
     .command("connect [name]")
     .description("Connect a service — omit the name to pick from connectable services")
     .option("--workspace <id>", "Workspace context")
+    .option("--reconnect", "Force a fresh sign-in even if a connection already exists — fixes an expired or revoked token")
     .action(async (name, opts) => {
     const { capabilityConnect } = await import("./commands/capability.js");
     await capabilityConnect(name, opts);
@@ -1851,13 +2642,37 @@ capConnections
     const { capabilityConnectionsRemove } = await import("./commands/cap-connections.js");
     await capabilityConnectionsRemove(capability, connectionId, opts);
 });
-// ─── raycast ──────────────────────────────────────────────────────────────────
+capability
+    .command("sync-status [provider]")
+    .description("Show sync status per provider × kind × connection (phase, counts, errors) — omit provider to see all")
+    .option("--workspace <id>", "Workspace context")
+    .option("--json", "Output as JSON")
+    .action(async (provider, opts) => {
+    const { capabilitySyncStatus } = await import("./commands/sync-status.js");
+    await capabilitySyncStatus(provider, opts);
+});
+// ─── sync (thin alias root for `cap sync-status`) ──────────────────────────────
+const sync = program
+    .command("sync")
+    .description("Sync status for connected providers — see `cap sync-status`");
+sync
+    .command("status [provider]")
+    .description("Show sync status per provider × kind × connection (phase, counts, errors) — omit provider to see all. Alias of `synap cap sync-status`.")
+    .option("--workspace <id>", "Workspace context")
+    .option("--json", "Output as JSON")
+    .action(async (provider, opts) => {
+    const { capabilitySyncStatus } = await import("./commands/sync-status.js");
+    await capabilitySyncStatus(provider, opts);
+});
+// ─── raycast (hidden power-user escape) ───────────────────────────────────────
+// Prefer the native Synap Raycast extension (@synap). Capability verbs there go
+// through list-actions / run-action. Script Commands are a per-verb escape hatch.
 const raycast = program
-    .command("raycast")
-    .description("Generate Raycast Script Commands from your enabled capabilities");
+    .command("raycast", { hidden: true })
+    .description("(hidden) Power-user escape: generate Raycast Script Commands per capability verb");
 raycast
     .command("generate")
-    .description("Emit a Raycast Script Command per enabled runnable verb")
+    .description("Power-user escape: emit a Script Command per enabled verb (extension uses list-actions/run-action)")
     .option("--out <dir>", "Output directory (default: ~/.synap/raycast-commands)")
     .option("--workspace <id>", "Workspace context")
     .action(async (opts) => {
@@ -1867,7 +2682,7 @@ raycast
 // ─── providers ───────────────────────────────────────────────────────────────
 const providers = program
     .command("providers")
-    .description("Discover AI providers from the pod and configure local tools");
+    .description("LLM providers on the pod (OpenAI/Anthropic/…) for local coding tools — not capability packs");
 providers
     .command("list", { isDefault: true })
     .description("Show enabled AI providers and their models")
@@ -1880,14 +2695,36 @@ providers
 });
 providers
     .command("pull")
-    .description("Write pod provider config to a local AI tool (opencode, aider)")
+    .description("Write pod LLM credentials into opencode or aider, or print the OpenAI-compatible {pod}/v1 endpoint")
     .option("--target <name>", "Target tool: opencode | aider")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
+    .option("--show-key", "With --target show: print the full API key (default: redacted)")
     .action(async (opts) => {
     const { providersPull } = await import("./commands/providers.js");
     await providersPull(opts);
 });
+providers
+    .command("set-key <providerId>")
+    .description("Store your own API key override for a provider (BYOI)")
+    .option("--workspace <id>", "Workspace ID for workspace-scoped override")
+    .option("--api-key <key>", "API key (prompted if omitted)")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--hub-api-key <key>", "Hub API key override")
+    .action(async (opts) => {
+    const { providersSetKey } = await import("./commands/providers.js");
+    await providersSetKey({ ...opts, providerId: opts.providerId });
+});
+providers
+    .command("list-keys")
+    .description("List user/workspace-level provider key overrides")
+    .option("--workspace <id>", "Workspace ID to check")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--hub-api-key <key>", "Hub API key override")
+    .action(async (opts) => {
+    const { providersListKeys } = await import("./commands/providers.js");
+    await providersListKeys(opts);
+});
 // ─── keys ────────────────────────────────────────────────────────────────────
 const keys = program
     .command("keys")
@@ -1895,9 +2732,10 @@ const keys = program
 keys
     .command("rotate")
     .description("Rotate your CLI key to pick up the latest scope set")
-    .action(async () => {
+    .option("--show-key", "Print the new key in full if it could not be saved to the config")
+    .action(async (opts) => {
     const { keysRotate } = await import("./commands/keys.js");
-    await keysRotate({});
+    await keysRotate({ showKey: opts.showKey });
 });
 // Resolve a global `--pod <name>` before commander parses (it isn't registered
 // per-command). Fails fast with a clear message on an unknown profile name.