@synap-core/cli 1.8.0 → 1.11.0

package/dist/index.js

@@ -16,6 +16,7 @@ import { Command } from "commander";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
+import { bootstrapPodOverride } from "./lib/pod.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 let version = "0.1.0";
@@ -31,7 +32,11 @@ program
     .name("synap")
     .description("Synap CLI — connect AI agents to your data pod")
     .version(version)
-    .showSuggestionAfterError(true);
+    .showSuggestionAfterError(true)
+    // Global, position-independent: target a saved pod profile for THIS command
+    // only (see `synap pods`). Consumed pre-parse by bootstrapPodOverride so it
+    // works in any position and overrides the default/env pod for one invocation.
+    .option("--pod <name>", "Run this command against a saved pod profile (overrides the default pod for this invocation only)");
 program
     .command("init")
     .description("Full setup: connect to a Synap pod and install the skill")
@@ -42,6 +47,41 @@ program
     const { init } = await import("./commands/init.js");
     await init(opts);
 });
+// ── launch — nothing → a working company (project + domain workspaces) ────────
+// Not a template browser: `--list` shows what's launchable (local, no pod),
+// bare `synap launch` runs the guided one-per-company setup.
+program
+    .command("launch")
+    .description("Stand up a NEW company/OS on a pod — creates a project + its core workspaces (interactive)")
+    .option("--list", "List what can be launched (local templates, no pod needed) and exit")
+    .option("--search <query>", "Filter --list by name/description/slug")
+    .option("--type <type>", "Filter --list by package type (workspace|capability|skill|workflow|view|cell)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { launch } = await import("./commands/launch.js");
+    await launch(opts);
+});
+// Hidden: one-shot Discord↔Synap bridge provisioning (dogfood/dev convenience).
+program
+    .command("bridge-setup", { hidden: true })
+    .description("(hidden) One-shot Discord↔Synap bridge provisioning")
+    .option("--client-id <id>", "Discord application (client) id — prints the invite URL")
+    .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("--proactive-channel <id>", "Discord channel id for the agent's proactive posts")
+    .option("--enable-react", "Turn on ✅-react capture")
+    .option("--pod <name>", "Pod profile to connect the bridge to (default: prompt)")
+    .option("--governance <mode>", "Agent governance preset: safe | normal | crazy (default: prompt)")
+    .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);
+});
 program
     .command("connect")
     .description("Connect an AI surface (Claude Code, Claude Desktop, Cursor, Raycast) to a Synap pod")
@@ -51,6 +91,8 @@ program
     .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) => {
     const { connect } = await import("./commands/connect.js");
     await connect(opts);
@@ -77,9 +119,19 @@ pods
     .command("use <name>")
     .description("Switch active pod and propagate credentials to all agent surfaces")
     .option("--surface <surface>", "Only switch this surface (raycast, claude-code, claude-desktop, cursor)")
+    .option("--json", "Output as JSON (incl. nextSteps for agents; full-switch only)")
     .action(async (name, opts) => {
     const { podsUse } = await import("./commands/pods.js");
-    await podsUse(name, { surface: opts.surface });
+    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>")
@@ -99,9 +151,42 @@ pods
 program
     .command("status")
     .description("Show Synap pod health and API status")
-    .action(async () => {
+    .option("--json", "Dump raw status (incl. release/migration detail) as JSON")
+    .action(async (opts) => {
     const { status } = await import("./commands/status.js");
-    await status();
+    await status({ json: opts.json });
+});
+program
+    .command("doctor")
+    .description("Coherence preflight: pod host resolves, key authenticates, workspace/project exist on THIS pod — catches config drift in one call")
+    .option("--json", "Output as JSON")
+    .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")
+    .option("--json", "Output structured {artifacts:[...]} JSON")
+    .action(async (opts) => {
+    const { versions } = await import("./commands/versions.js");
+    await versions({ json: opts.json });
+});
+program
+    .command("whoami")
+    .description("Show the winning API key's identity/scopes/workspace and flag env-vs-surface key divergence")
+    .action(async () => {
+    const { whoami } = await import("./commands/whoami.js");
+    await whoami();
+});
+// Hidden: compact ANSI line for the Claude Code statusLine (reads stdin JSON).
+program
+    .command("statusline", { hidden: true })
+    .description("(internal) Compact ANSI status line for Claude Code")
+    .option("--refresh", "Refresh the pod cache (run detached in the background)")
+    .action(async (opts) => {
+    const { statusline } = await import("./commands/statusline.js");
+    await statusline({ refresh: opts.refresh });
 });
 program
     .command("update")
@@ -174,9 +259,57 @@ program
     const { connections } = await import("./commands/connections.js");
     await connections();
 });
+// ─── mcp ────────────────────────────────────────────────────────────────────
+// The MCP front door: point any AI client at the pod's /mcp server.
+const mcp = program
+    .command("mcp")
+    .description("Connect any AI client to your pod's MCP server (the ambient tool layer)");
+mcp
+    .command("url")
+    .description("Print a ready-to-paste MCP connection (URL + key + snippets) for UI clients like ChatGPT")
+    .option("--client <name>", "Name the dedicated agent key after the target client")
+    .option("--workspace <id>", "Scope to a specific workspace (omit for pod-wide)")
+    .option("--project <id>", "Focus the agent on a project (narrows every tool call; orthogonal to --workspace)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { mcpUrl } = await import("./commands/mcp.js");
+    await mcpUrl(opts);
+});
+mcp
+    .command("verify")
+    .description("Health-check: is the pod's /mcp endpoint reachable and the key valid?")
+    .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { mcpVerify } = await import("./commands/mcp.js");
+    await mcpVerify(opts);
+});
+mcp
+    .command("connect [client]")
+    .description("Write the MCP config for a file-configurable client (Claude Code, Cursor, Desktop, …) — alias of `synap connect`")
+    .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 });
+});
+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);
+});
 program
     .command("login")
-    .description("Connect to a Synap pod (self-hosted or managed)")
+    .description("Connect your Synap account (private templates) + your pods")
     .option("--reconnect [name]", "Re-authenticate a saved pod without re-entering its URL")
     .action(async (opts) => {
     const chalk = (await import("chalk")).default;
@@ -200,23 +333,44 @@ program
     // Already have pods — show status and offer reconnect if any are unreachable
     const { checkPodHealth } = await import("./lib/pod.js");
     const ora = (await import("ora")).default;
-    const spinner = ora("Checking pod health...").start();
+    const spinner = ora("Checking pods + credentials...").start();
     const checks = await Promise.all(profiles.map(async (p) => {
         const h = await checkPodHealth(p.config.podUrl).catch(() => ({ healthy: false }));
-        return { ...p, healthy: h.healthy };
+        // A pod can be HEALTHY (public /health) while the saved key is REVOKED.
+        // Validate the actual credential too — otherwise a dead key looks "ok"
+        // and the user gets cryptic 401s downstream (the connect trap).
+        let keyValid = false;
+        if (h.healthy && p.config.hubApiKey) {
+            try {
+                const res = await fetch(`${p.config.podUrl.replace(/\/$/, "")}/api/hub/auth/status`, {
+                    headers: { Authorization: `Bearer ${p.config.hubApiKey}` },
+                    signal: AbortSignal.timeout(6000),
+                });
+                keyValid = res.ok;
+            }
+            catch {
+                keyValid = false;
+            }
+        }
+        return { ...p, healthy: h.healthy, keyValid };
     }));
     spinner.stop();
     console.log("\n  Configured pods:\n");
     for (const p of checks) {
         const active = p.active ? chalk.green(" ● ") : "   ";
-        const status = p.healthy ? chalk.green("ok") : chalk.red("unreachable");
+        const status = !p.healthy
+            ? chalk.red("unreachable")
+            : p.keyValid
+                ? chalk.green("ok")
+                : chalk.yellow("key expired");
         console.log(`  ${active}${chalk.bold(p.name.padEnd(14))} ${status}  ${chalk.dim(p.config.podUrl)}`);
     }
     console.log();
-    const unreachable = checks.filter((p) => !p.healthy);
-    if (unreachable.length > 0) {
-        console.log(chalk.yellow(`  ${unreachable.length} pod(s) unreachable. To refresh credentials:`));
-        for (const p of unreachable) {
+    // Anything that won't authenticate — unreachable OR a revoked/expired key.
+    const needsReconnect = checks.filter((p) => !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) {
             console.log(chalk.dim(`    synap login --reconnect ${p.name}`));
         }
         console.log();
@@ -226,22 +380,87 @@ program
         const active = checks.find((p) => p.active);
         if (active)
             console.log(chalk.dim(`  Active: ${active.name} (${active.config.podUrl})`));
-        console.log();
-        console.log(chalk.dim("  synap pods use <name>    — switch active pod"));
-        console.log(chalk.dim("  synap pods add           — connect another pod"));
     }
+    // ── Synap ACCOUNT (control plane) — a FIRST-CLASS half of "login" ──────
+    // Pods authenticate DATA access; the ACCOUNT authenticates the control plane
+    // (private templates like The Arch, hosted pods, marketplace publishing).
+    // They are different credentials, and pods alone never unlock private
+    // templates — so this gets its own headed section, not a footnote. `synap
+    // launch`'s "private templates after 'synap login'" hint lands HERE.
+    const { isLoggedIn: cpLoggedIn, login: cpLogin } = await import("./lib/auth.js");
+    console.log("\n  Synap account:\n");
+    const account = await cpLoggedIn();
+    let accountEmail;
+    if (account.valid) {
+        accountEmail = account.email;
+        console.log(`  ${chalk.green("●")} ${chalk.bold(account.email ?? "logged in")}  ${chalk.dim("— private templates available")}`);
+    }
+    else {
+        console.log(`  ${chalk.yellow("○")} ${chalk.bold("not logged in")}  ${chalk.dim("— your private templates (e.g. The Arch) are hidden until you log in")}`);
+        const prompts = (await import("prompts")).default;
+        const { doLogin } = await prompts({
+            type: "confirm",
+            name: "doLogin",
+            message: "Log in to your Synap account now?",
+            initial: true,
+        });
+        if (doLogin) {
+            const creds = await cpLogin();
+            if (creds?.email) {
+                accountEmail = creds.email;
+                console.log(chalk.green(`  ✓ Logged in as ${creds.email} — private templates unlocked.`));
+            }
+        }
+        else {
+            console.log(chalk.dim("  Later: synap login  ·  or  synap login --token <token>  (synap.live/account/tokens)"));
+        }
+    }
+    const { renderNextSteps, FLOW } = await import("./lib/next-steps.js");
+    renderNextSteps(FLOW.afterLogin(accountEmail));
 });
 // ─── orient ───────────────────────────────────────────────────────────────────
 program
     .command("orient")
-    .description("Show pod orientation: who you are, workspaces, profiles, and entity counts")
+    .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("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (opts) => {
     const { orient } = await import("./commands/data.js");
     await orient(opts);
 });
+// ─── digest ─────────────────────────────────────────────────────────────────
+// A quick read of what's already in a workspace or project (counts + key
+// entities + summary). Default = the active workspace lens.
+program
+    .command("digest")
+    .description("Summarize what's in a workspace or project (counts + key entities)")
+    .option("--workspace <id|name>", "Workspace to digest (defaults to active workspace lens)")
+    .option("--project <id|name>", "Project to digest (cross-cutting lens)")
+    .option("--json", "Output raw JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { digest } = await import("./commands/digest.js");
+    await digest(opts);
+});
+// ─── diagnose ────────────────────────────────────────────────────────────────
+// 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)")
+    .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")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (runId, opts) => {
+    const { diagnose } = await import("./commands/diagnose.js");
+    await diagnose(runId, opts);
+});
 // ─── use ──────────────────────────────────────────────────────────────────────
 program
     .command("use <workspace>")
@@ -253,20 +472,70 @@ program
     const { useWorkspace } = await import("./commands/data.js");
     await useWorkspace(workspace, opts);
 });
-// ─── note ─────────────────────────────────────────────────────────────────────
-// Quick `note` entity. The one canonical READ verb is `ask`; the one canonical
-// structured-WRITE verb is `capture`. (search / recall / remember removed — they
-// were redundant doors `ask`/`capture`/`note` already cover.)
-program
-    .command("note <text>")
-    .description("Quick freeform note → note entity (for structured learnings use `synap capture`)")
-    .option("--context <entity-id>", "Link this note to an entity")
+// ─── 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");
+project
+    .command("list", { isDefault: true })
+    .description("List projects on the active pod, with the pinned one marked (bare `synap project` runs this)")
+    .option("--json", "Output as JSON (incl. nextSteps for agents)")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { projectList } = await import("./commands/lens.js");
+    await projectList(opts);
+});
+project
+    .command("new <name>")
+    .description("Create a project (a company/initiative) 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")
+    .option("--api-key <key>", "API key override")
+    .action(async (name, opts) => {
+    const { projectNew } = await import("./commands/lens.js");
+    await projectNew(name, opts);
+});
+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("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
-    .action(async (text, opts) => {
-    const { noteData } = await import("./commands/data.js");
-    await noteData(text, opts);
+    .action(async (ref, opts) => {
+    const { useProject } = await import("./commands/lens.js");
+    await useProject(ref, opts);
+});
+project
+    .command("clear")
+    .description("Clear the active project focus (durable by default)")
+    .option("--session", "Ephemeral: clear only this Claude Code session's project")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { clearProject } = await import("./commands/lens.js");
+    await clearProject(opts);
+});
+project
+    .command("purge <target>")
+    .description("HARD teardown: delete a project + its pod-wide-exclusive entities (owner-only, irreversible)")
+    .option("--confirm <name>", "Confirm non-interactively by passing the exact project name")
+    .option("--yes", "Skip the interactive name prompt (uses the resolved name)")
+    .option("--json", "Output raw JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (target, opts) => {
+    const { projectPurge } = await import("./commands/purge.js");
+    await projectPurge(target, opts);
+});
+program
+    .command("lens")
+    .description("Show this Claude session's lens (workspace + project + focus session)")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { showLens } = await import("./commands/lens.js");
+    await showLens(opts);
 });
 // ─── ask (unified knowledge access) ─────────────────────────────────────────────
 // The ONE read verb. Routes to the right substrate(s) — semantic (entities),
@@ -277,6 +546,8 @@ program
     .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("--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")
     .action(async (query, opts) => {
@@ -294,16 +565,69 @@ program
     .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("--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) => {
     const { captureKnowledge } = await import("./commands/knowledge.js");
     await captureKnowledge({ ...opts, text });
 });
+// ─── import ─────────────────────────────────────────────────────────────────
+// "capture, but for files and URLs." Each input (file/folder/URL) routes through
+// 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...>")
+    .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("--dry-run", "Preview only — do not write")
+    .option("--yes", "Skip confirmation / auto-confirm store-first")
+    .option("--session", "Link created entities to the active session")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .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("--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)")
+    .action(async (inputs, opts) => {
+    const { importData } = await import("./commands/import.js");
+    await 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 (≤10MB) to the pod as a file entity")
+    .option("--workspace <id>", "Workspace to store the file in")
+    .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 ./report.pdf --open
+  `)
+    .action(async (path, opts) => {
+    const { uploadFile } = await import("./commands/upload.js");
+    await uploadFile(path, opts);
+});
 program
     .command("subscribe")
     .description("Stream pod events as NDJSON (long-poll)")
@@ -346,6 +670,8 @@ program
     .option("--json", "Output as JSON (default: human-readable)")
     .option("--profiles", "Show only profiles (use with --json for machine-readable schema)")
     .option("--commands", "Show only the command tree")
+    .option("--summary", "List profile kinds without property schemas")
+    .option("--profile-slugs <slugs>", "Comma-separated profile slugs to load in full")
     .option("--workspace <id>", "Workspace to query (defaults to active workspace)")
     .action(async (opts) => {
     const { discover } = await import("./commands/discover.js");
@@ -368,6 +694,18 @@ workspace
     const { provisionAgentWorkspace } = await import("./commands/knowledge.js");
     await provisionAgentWorkspace({ ...opts, agentUserId: opts.agentUserId });
 });
+workspace
+    .command("purge <target>")
+    .description("HARD teardown: delete a workspace + all its entities and blobs (owner-only, irreversible)")
+    .option("--confirm <name>", "Confirm non-interactively by passing the exact workspace name")
+    .option("--yes", "Skip the interactive name prompt (uses the resolved name)")
+    .option("--json", "Output raw JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (target, opts) => {
+    const { workspacePurge } = await import("./commands/purge.js");
+    await workspacePurge(target, opts);
+});
 // ─── list ─────────────────────────────────────────────────────────────────────
 const list = program
     .command("list")
@@ -408,6 +746,7 @@ list
     .description("List entities on the pod")
     .option("--workspace <id>", "Scope to a workspace (omit for pod-wide)")
     .option("--profile <slug>", "Filter by profile slug (e.g. person, task, note)")
+    .option("--role <slug>", "Filter to entities carrying this role (e.g. client, partner)")
     .option("--limit <n>", "Max results", "50")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -428,6 +767,51 @@ program
     const { showEntity } = await import("./commands/data-extra.js");
     await showEntity(id, opts);
 });
+// ─── facet ────────────────────────────────────────────────────────────────────
+// Roles — one identity, many roles. A role-profile (client, partner, contact…)
+// attached to an existing entity, never a second entity. Governed writes: an
+// attach/detach may come back "proposed for review" instead of applying live.
+const facet = program
+    .command("facet")
+    .description("Manage roles attached to an entity (client, partner, contact, …)");
+facet
+    .command("attach <entityId> <roleSlug>")
+    .description("Attach a role to an entity")
+    .option("--property <kv>", "Role property as key=value (repeatable)", collect, [])
+    .option("--workspace <id>", "Role's lens (defaults to the active workspace)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (entityId, roleSlug, opts) => {
+    const { attachFacet } = await import("./commands/facet.js");
+    await attachFacet(entityId, roleSlug, opts);
+});
+facet
+    .command("list <entityId>")
+    .description("List the roles attached to an entity")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (entityId, opts) => {
+    const { listFacets } = await import("./commands/facet.js");
+    await listFacets(entityId, opts);
+});
+facet
+    .command("detach [facetId]")
+    .description("Detach a role — pass the facet id, or --entity <id> --role <slug>")
+    .option("--entity <id>", "Entity id (with --role, resolves the facet to detach)")
+    .option("--role <slug>", "Role slug (with --entity)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (facetId, opts) => {
+    if (!facetId && !(opts.entity && opts.role)) {
+        console.error("Provide a facet id, or both --entity <id> and --role <slug>.");
+        process.exit(1);
+    }
+    const { detachFacet } = await import("./commands/facet.js");
+    await detachFacet(facetId ?? "", opts);
+});
 // ─── proposals ────────────────────────────────────────────────────────────────
 // Governance inbox — pending proposals attributed to this agent.
 const proposals = program
@@ -603,6 +987,36 @@ skillCmd
     const { getSkill } = await import("./commands/skills-commands.js");
     await getSkill(slug, opts);
 });
+skillCmd
+    .command("add <source>")
+    .description("Add skill(s) to your pod from: bundled · a local path · ~/.claude/skills/ · owner/repo · a git URL")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (source, opts) => {
+    const { addSkill } = await import("./commands/skill-manage.js");
+    await addSkill(source, opts);
+});
+skillCmd
+    .command("list")
+    .alias("ls")
+    .description("List the instruction skills installed on your pod")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .option("--debug", "Show resolved credentials")
+    .action(async (opts) => {
+    const { listSkills } = await import("./commands/skill-manage.js");
+    await listSkills(opts);
+});
+skillCmd
+    .command("remove <slug>")
+    .alias("rm")
+    .description("Remove a skill from your pod by slug")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (slug, opts) => {
+    const { removeSkill } = await import("./commands/skill-manage.js");
+    await removeSkill(slug, opts);
+});
 skillCmd
     .command("sync")
     .description("Bulk-import local skills from ~/.claude/skills/ into the pod")
@@ -630,8 +1044,9 @@ skillCmd
 // Paginated entity list — cleaner than `list entities`.
 program
     .command("browse [profile]")
-    .description("Browse entities in the active workspace, optionally filtered by profile type")
+    .description("Browse entities in the active workspace, optionally filtered by profile type or role")
     .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--role <slug>", "Filter to entities carrying this role (e.g. client, partner)")
     .option("--limit <n>", "Max results", "20")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -795,6 +1210,35 @@ agents
 const agent = program
     .command("agent")
     .description("Run autonomous agent loops against the IS, or schedule recurring goals");
+agent
+    .command("ask <message>")
+    .description("Send one message to the workspace's deployed agent and print its reply (multi-turn: reuses one thread)")
+    .option("--workspace <id|name>", "Workspace to talk to (uses active workspace/lens if omitted)")
+    .option("--thread <id>", "Target an existing thread/channel id instead of the default CLI chat thread")
+    .option("--new", "Start a fresh thread instead of continuing the persistent CLI chat thread")
+    .option("--agent-type <type>", "Requested agent type hint (backend currently routes to the orchestrator)")
+    .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 (message, opts) => {
+    const { agentAsk } = await import("./commands/agent-chat.js");
+    await agentAsk({ ...opts, message });
+});
+agent
+    .command("chat")
+    .description("Interactive REPL conversation with the workspace's deployed agent")
+    .option("--workspace <id|name>", "Workspace to talk to (uses active workspace/lens if omitted)")
+    .option("--thread <id>", "Target an existing thread/channel id instead of the default CLI chat thread")
+    .option("--new", "Start a fresh thread instead of continuing the persistent CLI chat thread")
+    .option("--agent-type <type>", "Requested agent type hint (backend currently routes to the orchestrator)")
+    .option("--timeout <seconds>", "How long to wait for each reply (default: 90)")
+    .option("--pod-url <url>", "Override pod URL")
+    .option("--api-key <key>", "Override API key")
+    .action(async (opts) => {
+    const { agentChat } = await import("./commands/agent-chat.js");
+    await agentChat(opts);
+});
 agent
     .command("run")
     .description("Run an autonomous agent toward a goal using the Intelligence Service")
@@ -926,6 +1370,32 @@ program
     const { graphTraverse } = await import("./commands/graph.js");
     await graphTraverse(opts);
 });
+// ─── centrality ────────────────────────────────────────────────────────────────
+// Window onto the Phase-3 PageRank centrality signal (entity_centrality):
+// see if it has populated, and trigger a recompute on demand.
+const centrality = program
+    .command("centrality")
+    .description("Inspect PageRank centrality (entity_centrality) and trigger a recompute");
+centrality
+    .command("status", { isDefault: true })
+    .description("Show whether PageRank centrality has populated + the top central entities")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { centralityStatus } = await import("./commands/centrality.js");
+    await centralityStatus(opts);
+});
+centrality
+    .command("recompute")
+    .description("Enqueue a PageRank centrality recompute (runs in the background)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { centralityRecompute } = await import("./commands/centrality.js");
+    await centralityRecompute(opts);
+});
 // ─── events ───────────────────────────────────────────────────────────────────
 program
     .command("events")
@@ -999,15 +1469,24 @@ program
 });
 // ─── open ─────────────────────────────────────────────────────────────────────
 program
-    .command("open <kind> <id>")
-    .description("Open an entity, view, cell, or document in the Synap desktop app")
-    .action(async (kind, id) => {
-    if (kind !== "entity" && kind !== "view" && kind !== "cell" && kind !== "document") {
-        console.error(`Unknown kind: "${kind}". Use: entity | view | cell | document`);
-        process.exit(1);
+    .command("open <kind-or-id> [id]")
+    .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);
+        }
+        const { openInBrowser } = await import("./commands/open.js");
+        await openInBrowser({ kind: kindOrId, id });
+    }
+    else {
+        // open <id> — resolve type automatically
+        const { resolveAndOpen } = await import("./commands/open.js");
+        await resolveAndOpen(kindOrId);
     }
-    const { openInBrowser } = await import("./commands/open.js");
-    await openInBrowser({ kind: kind, id });
 });
 // ─── doc ──────────────────────────────────────────────────────────────────────
 const doc = program
@@ -1054,6 +1533,23 @@ Examples:
     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")
@@ -1133,47 +1629,358 @@ program
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (service, opts) => {
-    const { connectorsConnect } = await import("./commands/connectors.js");
-    await connectorsConnect(service, opts);
-});
-// ─── connectors ──────────────────────────────────────────────────────────────
-const connectors = program
-    .command("connectors")
-    .description("Manage pod connector integrations (Nango-powered)");
-connectors
+    const { toolsConnect } = await import("./commands/tools.js");
+    await toolsConnect(service, opts);
+});
+// ─── tools ──────────────────────────────────────────────────────────────────
+const tools = program
+    .command("tools")
+    .description("Add and manage external service tools and their credentials");
+tools
     .command("list")
-    .description("List available connectors and connection status")
+    .description("List available tools and their connection status")
     .option("--json", "Output as JSON")
     .option("--workspace <id>", "Workspace context")
     .action(async (opts) => {
-    const { connectorsList } = await import("./commands/connectors.js");
-    await connectorsList(opts);
+    const { toolsList } = await import("./commands/tools.js");
+    await toolsList(opts);
+});
+tools
+    .command("connect <service>")
+    .description("Connect a credential to a tool (via Nango OAuth or vault)")
+    .option("--workspace <id>", "Workspace context")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (service, opts) => {
+    const { toolsConnect } = await import("./commands/tools.js");
+    await toolsConnect(service, opts);
 });
-connectors
+tools
     .command("sync <provider>")
-    .description("Trigger a manual sync for a connected provider")
+    .description("Trigger a manual sync for a connected tool")
     .option("--workspace <id>", "Workspace context")
     .action(async (provider, opts) => {
-    const { connectorsSync } = await import("./commands/connectors.js");
-    await connectorsSync(provider, opts);
+    const { toolsSync } = await import("./commands/tools.js");
+    await toolsSync(provider, opts);
 });
-connectors
+tools
     .command("disconnect <provider>")
-    .description("Revoke a connector connection")
+    .description("Revoke a tool's connection")
     .option("--workspace <id>", "Workspace context")
     .option("--force", "Skip confirmation")
     .action(async (provider, opts) => {
-    const { connectorsDisconnect } = await import("./commands/connectors.js");
-    await connectorsDisconnect(provider, opts);
+    const { toolsDisconnect } = await import("./commands/tools.js");
+    await toolsDisconnect(provider, opts);
 });
-connectors
+tools
     .command("schema")
-    .description("Fetch connector schema and supported providers (AI context)")
-    .option("--write-context [path]", "Write to .claude/CONNECTOR_CONTEXT.md")
+    .description("Fetch tool schema and supported providers (AI context)")
+    .option("--write-context [path]", "Write to .claude/TOOLS_CONTEXT.md")
     .option("--json", "Output raw JSON instead of formatted markdown")
     .action(async (opts) => {
-    const { connectorsSchema } = await import("./commands/connectors.js");
-    await connectorsSchema(opts);
+    const { toolsSchema } = await import("./commands/tools.js");
+    await toolsSchema(opts);
+});
+// ─── pod — unified pod-configuration view ─────────────────────────────────────
+// `market installed` shows what packages are installed; `pod` answers the
+// bigger question: what does the WHOLE pod look like — every workspace with
+// its provenance (marketplace/composed/ad-hoc/orphan), pod-wide vs
+// per-workspace capabilities/automations/playbooks, and the give/need feed
+// links between workspaces. Read surface for GET /api/hub/pod/config.
+const podCmd = program
+    .command("pod")
+    .description("Show the whole configured pod — workspaces (with provenance), capabilities/automations/playbooks, and feed links")
+    .option("--json", "Output the full structured graph as JSON")
+    .option("--orphans", "Only show orphan/ad-hoc workspaces and their template-match suggestions")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { pod } = await import("./commands/pod.js");
+    await pod(opts);
+});
+podCmd
+    .command("adopt <workspaceNameOrId>")
+    .description("Link an orphan/ad-hoc workspace (by name or id) to a matching template — makes it version-tracked")
+    .requiredOption("--template <slug>", "The template slug to adopt this workspace into")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (workspaceNameOrId, _opts, cmd) => {
+    // `--json` collides with the parent `pod` command's own `--json` — same
+    // gap `market install` has (see its comment). Merge across the chain.
+    const opts = cmd.optsWithGlobals();
+    const { podAdopt } = await import("./commands/pod.js");
+    await podAdopt(workspaceNameOrId, 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.
+const market = program
+    .command("market")
+    .description("Browse + install packages (workspaces, capabilities, skills, workflows, views, cells) into a project")
+    .option("--list", "List and exit (the default action)")
+    .option("--search <query>", "Filter by name/description/slug")
+    .option("--type <type>", "Filter by package type (workspace|capability|skill|workflow|view|cell)")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { market: marketBrowse } = await import("./commands/market.js");
+    await marketBrowse(opts);
+});
+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("--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")
+    .option("--api-key <key>", "API key override")
+    .action(async (slug, _opts, cmd) => {
+    // `--json` collides with the parent `market` command's own `--json` —
+    // commander then attributes the flag's VALUE to the parent's
+    // `_optionValues`, leaving this action's own `opts` argument `{}` for it
+    // (a real, pre-existing gap: `market install <slug> --json` silently fell
+    // back to human output). `optsWithGlobals()` walks the whole command
+    // chain and merges regardless of which level actually captured the flag.
+    const opts = cmd.optsWithGlobals();
+    const { marketInstall } = await import("./commands/market.js");
+    await marketInstall(slug, opts);
+});
+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("--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")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (slugs, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketUpdate } = await import("./commands/market.js");
+    await marketUpdate(slugs && slugs.length > 0 ? slugs : undefined, opts);
+});
+market
+    .command("installed")
+    .description("List packages installed on this pod — a pure read, no writes (pairs with 'market update' to check drift)")
+    .option("--outdated", "Only show packages with an update available")
+    .option("--tree", "Show the composition graph — package → templates → resulting workspaces, marking shared nodes")
+    .option("--layers", "Show the composition graph as a flat DAG — one row per slug, bedrock-first, with true fan-in counts")
+    .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 { marketInstalled } = await import("./commands/market.js");
+    await marketInstalled(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)")
+    .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 [file]")
+    .description("Validate then publish a template to the marketplace (private by default) — pass a file, or --from-workspace <id>")
+    .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("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override (for --from-workspace)")
+    .option("--api-key <key>", "API key override (for --from-workspace)")
+    .action(async (file, _opts, cmd) => {
+    // Same parent/child `--json` collision as `market install` — see its comment.
+    const opts = cmd.optsWithGlobals();
+    const { marketPublish } = await import("./commands/market-authoring.js");
+    await marketPublish(file, 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);
+});
+// ─── capability ───────────────────────────────────────────────────────────────
+const capability = program
+    .command("capability")
+    .alias("cap")
+    .description("The one capability-first root: list, add, enable, connect, show, run a capability pack");
+capability
+    .command("list")
+    .description("List capabilities — one row per pack, with status, connection, and verbs")
+    .option("--json", "Output as JSON")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (opts) => {
+    const { capabilityList } = await import("./commands/capability.js");
+    await capabilityList(opts);
+});
+capability
+    .command("add [name]")
+    .description("Install a capability from the catalog — omit the name to pick from a list")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (name, opts) => {
+    const { capabilityAdd } = await import("./commands/capability.js");
+    await capabilityAdd(name, opts);
+});
+capability
+    .command("create [file]")
+    .description("Create a capability from a JSON definition (file path, or pipe JSON via stdin)")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (file, opts) => {
+    const { capabilityCreate } = await import("./commands/capability.js");
+    await capabilityCreate(file, opts);
+});
+capability
+    .command("rm <ids...>")
+    .alias("remove")
+    .description("Remove capability container(s) by id or name — member tools/skills untouched")
+    .option("--workspace <id>", "Workspace context")
+    .option("--force", "Skip the confirmation prompt")
+    .action(async (ids, opts) => {
+    const { capabilityRemove } = await import("./commands/capability.js");
+    await capabilityRemove(ids, opts);
+});
+capability
+    .command("enable [name]")
+    .description("Turn on a capability — omit the name to pick from a list; ensures its connection, then pick which verbs it can do")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (name, opts) => {
+    const { capabilityEnable } = await import("./commands/capability.js");
+    await capabilityEnable(name, opts);
+});
+capability
+    .command("connect [name]")
+    .description("Connect a service — omit the name to pick from connectable services")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (name, opts) => {
+    const { capabilityConnect } = await import("./commands/capability.js");
+    await capabilityConnect(name, opts);
+});
+capability
+    .command("disconnect <name>")
+    .description("Disconnect a capability's service — accepts a capability name or a provider id")
+    .option("--workspace <id>", "Workspace context")
+    .option("--force", "Skip confirmation")
+    .action(async (name, opts) => {
+    const { capabilityDisconnect } = await import("./commands/capability.js");
+    await capabilityDisconnect(name, opts);
+});
+capability
+    .command("show <name>")
+    .description("Show one capability's full detail: status, connection, verbs, next action")
+    .option("--json", "Output as JSON")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (name, opts) => {
+    const { capabilityShow } = await import("./commands/capability.js");
+    await capabilityShow(name, opts);
+});
+capability
+    .command("run <verb> [params...]")
+    .description("Launch a verb — pass inputs as `--key value` flags")
+    .option("--workspace <id>", "Workspace context")
+    .option("--connection <id>", "Run against a specific stored connection id")
+    .option("--for <objId>", "Run against the connection bound to this context object id")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(async (verb, params, opts) => {
+    const { capabilityRun } = await import("./commands/capability.js");
+    await capabilityRun(verb, params, opts);
+});
+capability
+    .command("test <verb>")
+    .description("Dry-run a verb (preview side effects without executing)")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (verb, opts) => {
+    const { capabilityTest } = await import("./commands/capability.js");
+    await capabilityTest(verb, opts);
+});
+// ─── cap connections ──────────────────────────────────────────────────────────
+// Manage a capability's stored connections (credentials / OAuth accounts /
+// context bindings). Nested under `cap` — distinct from the top-level
+// `synap connections`, which shows agent-surface → pod wiring.
+const capConnections = capability
+    .command("connections")
+    .alias("conn")
+    .description("Manage a capability's connections: list, add, update, rm");
+capConnections
+    .command("list <capability>")
+    .description("List a capability's connections (label, kind, default, context, id)")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (capability, opts) => {
+    const { capabilityConnectionsList } = await import("./commands/cap-connections.js");
+    await capabilityConnectionsList(capability, opts);
+});
+capConnections
+    .command("add <capability>")
+    .description("Add a connection — prompts for label + masked value unless provided as flags")
+    .option("--label <label>", "Connection label")
+    .option("--value <value>", "Secret / credential value (else prompted, masked)")
+    .option("--context-type <type>", "Context type this connection binds to")
+    .option("--context-id <id>", "Context object id this connection binds to")
+    .option("--account-hint <hint>", "Human-readable account hint (e.g. an email)")
+    .option("--default", "Mark this connection as the capability's default")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (capability, opts) => {
+    const { capabilityConnectionsAdd } = await import("./commands/cap-connections.js");
+    await capabilityConnectionsAdd(capability, opts);
+});
+capConnections
+    .command("update <capability> <connectionId>")
+    .description("Update a connection's fields; --rotate (or --value) rotates its secret")
+    .option("--label <label>", "New connection label")
+    .option("--value <value>", "New secret / credential value")
+    .option("--rotate", "Prompt (masked) for a new secret value")
+    .option("--context-type <type>", "New context type")
+    .option("--context-id <id>", "New context object id")
+    .option("--account-hint <hint>", "New account hint")
+    .option("--default", "Mark this connection as the capability's default")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (capability, connectionId, opts) => {
+    const { capabilityConnectionsUpdate } = await import("./commands/cap-connections.js");
+    await capabilityConnectionsUpdate(capability, connectionId, opts);
+});
+capConnections
+    .command("rm <capability> <connectionId>")
+    .alias("remove")
+    .description("Remove a connection by id (confirms first)")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (capability, connectionId, opts) => {
+    const { capabilityConnectionsRemove } = await import("./commands/cap-connections.js");
+    await capabilityConnectionsRemove(capability, connectionId, opts);
+});
+// ─── raycast ──────────────────────────────────────────────────────────────────
+const raycast = program
+    .command("raycast")
+    .description("Generate Raycast Script Commands from your enabled capabilities");
+raycast
+    .command("generate")
+    .description("Emit a Raycast Script Command per enabled runnable verb")
+    .option("--out <dir>", "Output directory (default: ~/.synap/raycast-commands)")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (opts) => {
+    const { raycastGenerate } = await import("./commands/raycast.js");
+    await raycastGenerate(opts);
 });
 // ─── providers ───────────────────────────────────────────────────────────────
 const providers = program
@@ -1210,5 +2017,32 @@ keys
     const { keysRotate } = await import("./commands/keys.js");
     await keysRotate({});
 });
+// 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.
+try {
+    bootstrapPodOverride(process.argv);
+}
+catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+// Last-resort net. Commander does not await async .action() handlers, so a
+// command that throws without its own catch becomes an unhandled rejection and
+// Node dumps a raw stack trace with dist/ paths at the user — e.g.
+// `synap digest --workspace <inaccessible>` printed the HubError constructor
+// frame. Render it through the one door instead. Commands that already catch
+// and render are unaffected: this only fires when nothing else handled it.
+process.on("unhandledRejection", (err) => {
+    void (async () => {
+        try {
+            const { renderHubError } = await import("./lib/hub-client.js");
+            renderHubError(err);
+        }
+        catch {
+            console.error(err instanceof Error ? err.message : String(err));
+        }
+        process.exit(1);
+    })();
+});
 program.parse();
 //# sourceMappingURL=index.js.map