@synap-core/cli 1.7.0 → 1.10.0

package/dist/index.js

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 /**
- * @synap/cli — Connect OpenClaw to sovereign knowledge infrastructure
+ * @synap/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 OpenClaw to an existing Synap pod
- *   npx @synap/cli security-audit    Check OpenClaw for known vulnerabilities
- *   npx @synap/cli status            Show pod + OpenClaw health
+ *   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
  *
  * Or install globally:
@@ -17,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";
@@ -30,38 +30,69 @@ catch {
 const program = new Command();
 program
     .name("synap")
-    .description("Synap CLI — connect OpenClaw to sovereign knowledge infrastructure")
-    .version(version);
+    .description("Synap CLI — connect AI agents to your data pod")
+    .version(version)
+    .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: detect OpenClaw, harden security, connect to Synap pod, install skill")
+    .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-security", "Skip security hardening step")
     .option("--skip-is", "Skip Intelligence Service provider setup")
     .action(async (opts) => {
     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("finish")
-    .description("One-shot post-install: skill, AI key, public domain, IS")
-    .option("--skip-is", "Skip Intelligence Service provider setup")
-    .option("--skip-ai-key", "Skip AI provider key setup")
-    .option("--skip-domain", "Skip public domain exposure")
+    .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 { finish } = await import("./commands/finish.js");
-    await finish(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, OpenClaw) to a Synap pod")
-    .option("--target <name>", "AI surface: claude-code | claude-desktop | cursor | raycast | openclaw")
+    .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")
     .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) => {
     const { connect } = await import("./commands/connect.js");
     await connect(opts);
@@ -87,10 +118,11 @@ pods
 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, openclaw)")
+    .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("remove <name>")
@@ -100,22 +132,44 @@ pods
     const { podsRemove } = await import("./commands/pods.js");
     await podsRemove(name);
 });
+pods
+    .command("reconnect [name]")
+    .description("Re-authenticate a saved pod (refresh API key without re-entering the URL)")
+    .action(async (name) => {
+    const { podsReconnect } = await import("./commands/pods.js");
+    await podsReconnect(name);
+});
 program
-    .command("security-audit")
-    .alias("audit")
-    .description("Check OpenClaw configuration for known vulnerabilities")
-    .option("--fix", "Auto-fix issues where possible")
-    .option("--json", "Output results as JSON")
+    .command("status")
+    .description("Show Synap pod health and API status")
+    .option("--json", "Dump raw status (incl. release/migration detail) as JSON")
     .action(async (opts) => {
-    const { securityAudit } = await import("./commands/security-audit.js");
-    await securityAudit(opts);
+    const { status } = await import("./commands/status.js");
+    await status({ json: opts.json });
 });
 program
-    .command("status")
-    .description("Show Synap pod and OpenClaw health status")
+    .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 { status } = await import("./commands/status.js");
-    await status();
+    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")
@@ -126,101 +180,6 @@ program
     const { update } = await import("./commands/update.js");
     await update(opts);
 });
-const oc = program
-    .command("openclaw")
-    .alias("oc")
-    .description("Access, configure, and connect OpenClaw");
-oc
-    .command("status", { isDefault: true })
-    .description("Overview: gateway status, AI key, skill, how to connect")
-    .action(async () => {
-    const { openclawOverview } = await import("./commands/openclaw.js");
-    await openclawOverview();
-});
-oc
-    .command("dashboard")
-    .alias("dash")
-    .description("Open the OpenClaw web UI (or print SSH tunnel instructions for remote servers)")
-    .action(async () => {
-    const { openclawDashboard } = await import("./commands/openclaw.js");
-    openclawDashboard();
-});
-oc
-    .command("connect")
-    .description("Show MCP client configs for Claude Desktop, Cursor, Windsurf")
-    .option("--client <name>", "Specific client: claude, cursor, windsurf")
-    .action(async (opts) => {
-    const { openclawConnect } = await import("./commands/openclaw.js");
-    await openclawConnect(opts);
-});
-oc
-    .command("configure")
-    .alias("config")
-    .description("Set AI provider API key via OpenClaw's own config system")
-    .option("-i, --interactive", "Run OpenClaw's own interactive wizard")
-    .option("--provider <name>", "Provider: anthropic | openai | google")
-    .option("--key <key>", "API key (non-interactive)")
-    .option("--model <id>", "Model id (e.g. anthropic/claude-sonnet-4-6)")
-    .option("--show", "Print the current config")
-    .action(async (opts) => {
-    const { openclawConfigure } = await import("./commands/openclaw.js");
-    await openclawConfigure(opts);
-});
-oc
-    .command("token")
-    .description("Print the OpenClaw gateway token (for MCP clients)")
-    .option("--copy", "Copy to clipboard instead of printing")
-    .option("--for <client>", "Print a pre-filled MCP config (claude, cursor, windsurf)")
-    .action(async (opts) => {
-    const { openclawToken } = await import("./commands/openclaw.js");
-    openclawToken(opts);
-});
-oc
-    .command("doctor")
-    .description("Run OpenClaw's diagnostic (openclaw doctor)")
-    .option("--fix", "Auto-fix detected issues")
-    .action(async (opts) => {
-    const { openclawDoctor } = await import("./commands/openclaw.js");
-    openclawDoctor(opts);
-});
-oc
-    .command("logs")
-    .description("Tail OpenClaw container logs")
-    .option("-n, --lines <n>", "Number of log lines", "50")
-    .option("-f, --follow", "Follow log output")
-    .action(async (opts) => {
-    const { openclawLogs } = await import("./commands/openclaw.js");
-    openclawLogs({ lines: opts.lines ? parseInt(opts.lines, 10) : 50, follow: opts.follow });
-});
-oc
-    .command("restart")
-    .description("Restart the OpenClaw container")
-    .action(async () => {
-    const { openclawRestart } = await import("./commands/openclaw.js");
-    await openclawRestart();
-});
-oc
-    .command("setup-domain")
-    .description("Expose the OpenClaw dashboard via a public HTTPS subdomain (Caddy)")
-    .action(async () => {
-    const { openclawSetupDomain } = await import("./commands/openclaw.js");
-    openclawSetupDomain();
-});
-oc
-    .command("connections")
-    .alias("conn")
-    .description("Unified view: AI providers, skills, channels, MCP clients")
-    .action(async () => {
-    const { openclawConnections } = await import("./commands/openclaw.js");
-    openclawConnections();
-});
-oc
-    .command("open [section]")
-    .description("Open the OpenClaw dashboard (optionally at a section: channels, skills, config, chat, sessions, logs)")
-    .action(async (section) => {
-    const { openclawOpen } = await import("./commands/openclaw.js");
-    openclawOpen(section);
-});
 // ─── infra ────────────────────────────────────────────────────────────────────
 const infra = program
     .command("infra")
@@ -278,73 +237,202 @@ program
 program
     .command("connections")
     .alias("conn")
-    .description("Show which pod each agent surface (Claude Code, Desktop, Cursor, OpenClaw) is connected to")
+    .description("Show which pod each agent surface (Claude Code, Desktop, Cursor, Raycast) is connected to")
     .action(async () => {
     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 });
+});
 program
     .command("login")
-    .description("Sign in to your Synap account via browser")
-    .option("--token <token>", "Provide a Synap API token directly (for headless/server use)")
+    .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;
-    const ora = (await import("ora")).default;
-    const { login, loginWithToken, isLoggedIn } = await import("./lib/auth.js");
-    // Headless path: token provided directly
-    if (opts.token) {
-        const spinner = ora("Validating token...").start();
-        const creds = await loginWithToken(opts.token);
-        if (creds) {
-            spinner.succeed(`Authenticated as ${creds.email}`);
-        }
-        else {
-            spinner.fail("Token is invalid or expired. Get a token at https://synap.live/account/tokens");
-        }
+    const { listPodProfiles } = await import("./lib/pod.js");
+    // --reconnect: delegate to reconnect flow
+    if (opts.reconnect !== undefined) {
+        const name = typeof opts.reconnect === "string" ? opts.reconnect : undefined;
+        const { podsReconnect } = await import("./commands/pods.js");
+        await podsReconnect(name);
         return;
     }
-    const status = await isLoggedIn();
-    if (status.valid) {
-        console.log(chalk.green(`  Already logged in as ${status.email}`));
+    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();
         return;
     }
-    console.log(chalk.blue("  Opening browser to sign in..."));
-    const spinner = ora("Waiting for authentication...").start();
-    const creds = await login();
-    if (creds) {
-        spinner.succeed(`Authenticated as ${creds.email}`);
+    // 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 pods + credentials...").start();
+    const checks = await Promise.all(profiles.map(async (p) => {
+        const h = await checkPodHealth(p.config.podUrl).catch(() => ({ healthy: false }));
+        // 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.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();
+    // 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();
     }
     else {
-        spinner.fail("Authentication timed out. Try: synap login --token <token>");
-        console.log(chalk.dim("  Get a token at: https://synap.live/account/tokens"));
+        console.log(chalk.green("  All pods healthy."));
+        const active = checks.find((p) => p.active);
+        if (active)
+            console.log(chalk.dim(`  Active: ${active.name} (${active.config.podUrl})`));
     }
-});
-program
-    .command("logout")
-    .description("Sign out and remove stored credentials")
-    .action(async () => {
-    const chalk = (await import("chalk")).default;
-    const { logout, getStoredToken } = await import("./lib/auth.js");
-    const creds = getStoredToken();
-    logout();
-    if (creds) {
-        console.log(chalk.green(`  Logged out (was: ${creds.email})`));
+    // ── 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.dim("  Not logged in"));
+        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>")
@@ -356,68 +444,171 @@ program
     const { useWorkspace } = await import("./commands/data.js");
     await useWorkspace(workspace, opts);
 });
-// ─── search ───────────────────────────────────────────────────────────────────
-program
-    .command("search <query>")
-    .description("Search entities, documents, and views (Typesense-powered)")
-    .option("--workspace <id>", "Scope to a specific workspace")
-    .option("--type <type>", "Filter: entity | doc | view")
-    .option("--limit <n>", "Max results", "20")
+// ─── 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 (query, opts) => {
-    const { searchData } = await import("./commands/data.js");
-    await searchData(query, opts);
+    .action(async (ref, opts) => {
+    const { useProject } = await import("./commands/lens.js");
+    await useProject(ref, opts);
 });
-// ─── remember / recall ────────────────────────────────────────────────────────
-program
-    .command("remember <text>")
-    .description("Store a memory on the pod")
-    .option("--context <entity-id>", "Link memory to an entity")
+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 (text, opts) => {
-    const { rememberData } = await import("./commands/data.js");
-    await rememberData(text, opts);
+    .action(async (target, opts) => {
+    const { projectPurge } = await import("./commands/purge.js");
+    await projectPurge(target, opts);
 });
 program
-    .command("recall <query>")
-    .description("Retrieve memories from the pod (add --structured for knowledge entities)")
-    .option("--structured", "Search structured knowledge entities instead of episodic memory")
-    .option("--type <type>", "Filter by entry type: gotcha|lesson|decision|reference (--structured only)")
-    .option("--tags <csv>", "Filter by tags e.g. repo:synap-backend (--structured only)")
-    .option("--workspace <id>", "Workspace to search (--structured only, defaults to active)")
-    .option("--limit <n>", "Max results", "10")
+    .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),
+// 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")
+    .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) => {
-    if (opts.structured) {
-        const { recallStructured } = await import("./commands/knowledge.js");
-        await recallStructured(query, opts);
-    }
-    else {
-        const { recallData } = await import("./commands/data.js");
-        await recallData(query, opts);
-    }
+    const { askKnowledge } = await import("./commands/data.js");
+    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.
 program
-    .command("capture")
-    .description("Capture a structured knowledge entry into the active agent workspace")
-    .requiredOption("--type <type>", "Entry type: gotcha|lesson|decision|reference")
-    .requiredOption("--claim <text>", "One-line assertion")
+    .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")
+    .option("--claim <text>", "Typed mode: one-line assertion (required with --type)")
     .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("--yes", "Skip the y/N confirmation prompt (smart mode)")
     .option("--json", "Output as JSON")
-    .action(async (opts) => {
+    .action(async (text, opts) => {
     const { captureKnowledge } = await import("./commands/knowledge.js");
-    await captureKnowledge(opts);
+    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);
+});
+program
+    .command("subscribe")
+    .description("Stream pod events as NDJSON (long-poll)")
+    .option("--event <pattern>", "Filter by event type pattern (e.g. proposal.*)")
+    .option("--limit <n>", "Events per poll", "20")
+    .option("--json", "NDJSON output")
+    .option("--pod-url <url>")
+    .option("--api-key <key>")
+    .action(async (opts) => {
+    const { subscribeEvents } = await import("./commands/subscribe.js");
+    await subscribeEvents(opts);
+});
+program
+    .command("home")
+    .description("Show the active workspace's home bento layout (what cells are on screen)")
+    .option("--workspace <id>", "Workspace to read (defaults to active workspace)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { showHome } = await import("./commands/home.js");
+    await showHome(opts);
+});
+program
+    .command("context")
+    .description("Session-start context: knowledge, proposals, tasks, active sessions")
+    .option("--repo <name>", "Filter knowledge by repo tag")
+    .option("--limit <n>", "Entries per section", "5")
+    .option("--json", "NDJSON output")
+    .option("--workspace <id>", "Override workspace")
+    .option("--pod-url <url>")
+    .option("--api-key <key>")
+    .action(async (opts) => {
+    const { contextSummary } = await import("./commands/context.js");
+    await contextSummary(opts);
 });
 program
     .command("discover")
@@ -425,6 +616,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");
@@ -447,6 +640,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")
@@ -470,11 +675,24 @@ list
     const { listProfiles } = await import("./commands/data.js");
     await listProfiles(opts);
 });
+list
+    .command("views")
+    .description("List views in a workspace (whiteboard, kanban, bento, …)")
+    .option("--type <type>", "Filter by view type (e.g. whiteboard, kanban, calendar)")
+    .option("--workspace <id>", "Workspace (defaults to active)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { viewList } = await import("./commands/view.js");
+    await viewList(opts);
+});
 list
     .command("entities")
     .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")
@@ -483,6 +701,335 @@ list
     const { listEntities } = await import("./commands/data.js");
     await listEntities(opts);
 });
+// ─── show ─────────────────────────────────────────────────────────────────────
+// Entity detail + its relations — one command to understand any node in the graph.
+program
+    .command("show <id>")
+    .description("Show an entity with its properties and all linked relations")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    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
+    .command("proposals")
+    .description("Review and act on governance proposals");
+proposals
+    .command("list", { isDefault: true })
+    .description("List pending governance proposals for this agent")
+    .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--limit <n>", "Max results", "20")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { listProposals } = await import("./commands/data-extra.js");
+    await listProposals(opts);
+});
+proposals
+    .command("approve <id>")
+    .description("Approve a pending proposal")
+    .option("--reason <text>", "Optional approval note")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { approveProposal } = await import("./commands/proposals-actions.js");
+    await approveProposal(id, opts);
+});
+proposals
+    .command("reject <id>")
+    .description("Reject a pending proposal")
+    .option("--reason <text>", "Rejection reason")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { rejectProposal } = await import("./commands/proposals-actions.js");
+    await rejectProposal(id, opts);
+});
+// ─── session ──────────────────────────────────────────────────────────────────
+// Focus sessions — goal-bound work rooms tracked on the pod.
+// AI agents: use start_session to begin, update_session to report progress,
+// update_session({status:"closed"}) to finish. Sessions link goals, context,
+// plans, execution logs, and verification reports together.
+const session = program
+    .command("session")
+    .description("Manage focus sessions (goal-bound AI work rooms)");
+session
+    .command("start")
+    .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("--task-id <id>", "Link session to an existing task entity")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { startSession } = await import("./commands/sessions.js");
+    await startSession(opts);
+});
+session
+    .command("list", { isDefault: true })
+    .description("List focus sessions in the active workspace")
+    .option("--workspace <id>", "Scope to a specific workspace")
+    .option("--status <status>", "Filter by status: active | paused | closed")
+    .option("--limit <n>", "Max results", "20")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { listSessions } = await import("./commands/sessions.js");
+    await listSessions(opts);
+});
+session
+    .command("get <id>")
+    .description("Show details for a specific focus session")
+    .option("--workspace <id>", "Workspace that owns the session (required for scoped fetch)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { getSession } = await import("./commands/sessions.js");
+    await getSession(id, opts);
+});
+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")
+    .option("--status <status>", "New status: active | paused")
+    .option("--goal <text>", "Revised 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 { updateSession } = await import("./commands/sessions.js");
+    await updateSession(id, opts);
+});
+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")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { closeSession } = await import("./commands/sessions.js");
+    await closeSession(id, opts);
+});
+session
+    .command("attach <id>")
+    .description("Attach a session to this terminal — all hub calls tag X-Session-Id until detached")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { attachSession } = await import("./commands/sessions.js");
+    await attachSession(id, opts);
+});
+session
+    .command("detach")
+    .description("Remove the active session from this terminal")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { detachSession } = await import("./commands/sessions.js");
+    detachSession(opts);
+});
+session
+    .command("current")
+    .description("Show the active session for this terminal (from .synap-session or SYNAP_SESSION_ID)")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { sessionStatus } = await import("./commands/sessions.js");
+    sessionStatus(opts);
+});
+// ─── skill ────────────────────────────────────────────────────────────────────
+// Autonomous workspace session skills — context gathering, task planning, etc.
+const skillCmd = program
+    .command("skill")
+    .description("Execute a skill in an autonomous workspace session")
+    .action(() => {
+    skillCmd.help();
+});
+skillCmd
+    .command("gather-context")
+    .description("Gather pod KG + local context (CLAUDE.md, .claude/kg-verify) for a session")
+    .option("--session <id>", "Focus session ID (required)")
+    .option("--workspace <id>", "Workspace ID (defaults to active workspace)")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .allowUnknownOption()
+    .action(async (opts) => {
+    const { gatherContext } = await import("./commands/skills.js");
+    await gatherContext(opts);
+});
+skillCmd
+    .command("suggest <topic>")
+    .description("Search the skill knowledge base by topic or keyword")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (topic, opts) => {
+    const { suggestSkills } = await import("./commands/skills-commands.js");
+    await suggestSkills(topic, opts);
+});
+skillCmd
+    .command("get <slug>")
+    .description("Fetch a skill from the knowledge base by slug and print its body")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (slug, opts) => {
+    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")
+    .option("--from <path>", "Skills directory path (default: ~/.claude/skills)")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { syncSkills } = await import("./commands/skills-commands.js");
+    await syncSkills(opts);
+});
+skillCmd
+    .command("verify-code")
+    .description("Run the project's type-check/test gate and store the result on the session")
+    .requiredOption("--session <id>", "Focus session ID")
+    .requiredOption("--workspace <id>", "Workspace that owns the session")
+    .requiredOption("--cmd <command>", "Gate command to run (e.g. 'pnpm type-check')")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { verifyCode } = await import("./commands/skills.js");
+    await verifyCode(opts);
+});
+// ─── browse ───────────────────────────────────────────────────────────────────
+// Paginated entity list — cleaner than `list entities`.
+program
+    .command("browse [profile]")
+    .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")
+    .option("--api-key <key>", "API key override")
+    .action(async (profile, opts) => {
+    const { browseEntities } = await import("./commands/data-extra.js");
+    await browseEntities({ ...opts, profile });
+});
+// ─── observe ──────────────────────────────────────────────────────────────────
+// AI-maintained user model — write and query pod-scoped user observations.
+const observe = program
+    .command("observe")
+    .description("Write and recall pod-wide user observations (AI-maintained user model)");
+observe
+    .command("write <text>", { isDefault: true })
+    .description("Record an observation about the user (pod-scoped, AI-maintained)")
+    .option("--category <cat>", "working_style | communication | focus | technical | preference", "preference")
+    .option("--confidence <n>", "Confidence score 0-1", "0.5")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (text, opts) => {
+    const { observeWrite } = await import("./commands/observe.js");
+    await observeWrite(text, opts);
+});
+observe
+    .command("recall <query>")
+    .description("Search recorded user observations")
+    .option("--category <cat>", "Filter by category")
+    .option("--limit <n>", "Max results", "10")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (query, opts) => {
+    const { observeRecall } = await import("./commands/observe.js");
+    await observeRecall(query, opts);
+});
 // ─── get ──────────────────────────────────────────────────────────────────────
 const get = program
     .command("get")
@@ -538,6 +1085,7 @@ set
     .command("entity <id>")
     .description("Update entity properties")
     .requiredOption("--props <json>", "Properties as JSON string")
+    .option("--workspace <id>", "Workspace ID (sent in PATCH body so workspace-scoped automations fire)")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -604,5 +1152,779 @@ agents
     const { agentsInfo } = await import("./commands/agents.js");
     agentsInfo(name);
 });
+// ─── agent (autonomous runner) ───────────────────────────────────────────────
+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")
+    .requiredOption("--goal <text>", "What the agent should accomplish")
+    .option("--persona <type>", "researcher | assistant | developer (default: researcher)")
+    .option("--model <model>", "IS model alias, e.g. synap/advanced (default: synap/advanced)")
+    .option("--workspace <id>", "Workspace to store results in (uses active workspace if omitted)")
+    .option("--max-steps <n>", "Max reasoning steps before auto-saving (default: 12)", parseInt)
+    .option("--dry-run", "Print config without running")
+    .option("--pod-url <url>", "Override pod URL")
+    .option("--api-key <key>", "Override API key")
+    .action(async (opts) => {
+    const { agentRun } = await import("./commands/agent-run.js");
+    await agentRun(opts);
+});
+agent
+    .command("schedule")
+    .description("Add, list, or remove recurring agent schedules")
+    .option("--goal <text>", "Goal for the scheduled agent")
+    .option("--name <label>", "Name for this schedule (required when adding)")
+    .option("--every <interval>", "hourly | daily | weekly")
+    .option("--persona <type>", "researcher | assistant | developer (default: researcher)")
+    .option("--model <model>", "IS model alias (default: synap/advanced)")
+    .option("--workspace <id>", "Workspace to store results in")
+    .option("--run-now", "Also run immediately after creating the schedule")
+    .option("--list", "List all configured schedules")
+    .option("--remove <name>", "Remove a schedule by name")
+    .option("--pod-url <url>", "Override pod URL")
+    .option("--api-key <key>", "Override API key")
+    .action(async (opts) => {
+    const { agentSchedule } = await import("./commands/agent-run.js");
+    await agentSchedule(opts);
+});
+agent
+    .command("tick")
+    .description("Check due schedules and run them — wire this to crontab: `0 * * * * synap agent tick`")
+    .option("--dry-run", "Show what would run without executing")
+    .option("--pod-url <url>", "Override pod URL")
+    .option("--api-key <key>", "Override API key")
+    .action(async (opts) => {
+    const { agentTick } = await import("./commands/agent-run.js");
+    await agentTick(opts);
+});
+// ─── automation ──────────────────────────────────────────────────────────────
+function collect(val, prev) { return [...prev, val]; }
+const automation = program
+    .command("automation")
+    .description("Create, manage, and inspect pod automations");
+automation
+    .command("list")
+    .description("List automations on the pod")
+    .option("--workspace <id>", "Filter by workspace")
+    .option("--status <status>", "Filter by status (active|draft|paused|error)")
+    .option("--json", "Output raw JSON")
+    .action(async (opts) => {
+    const { automationList } = await import("./commands/automation.js");
+    await automationList(opts);
+});
+automation
+    .command("describe <id>")
+    .description("Show full details of an automation")
+    .option("--workspace <id>")
+    .option("--json")
+    .action(async (id, opts) => {
+    const { automationDescribe } = await import("./commands/automation.js");
+    await automationDescribe(id, opts);
+});
+automation
+    .command("create")
+    .description("Create an automation (quick flags or --from file.yaml)")
+    .option("--name <name>", "Automation name (required in quick mode)")
+    .option("--trigger <spec>", "event:<pattern> | cron:<expr> | webhook | manual")
+    .option("--filter <kv>", "key=value filter (event triggers, repeatable)", collect, [])
+    .option("--action <type>", "notify | channel-message | none (default: none)")
+    .option("--message <text>", "Message content for notify/channel-message")
+    .option("--channel <id>", "Channel ID for channel-message action")
+    .option("--status <status>", "draft (default) | active")
+    .option("--description <text>", "Description")
+    .option("--workspace <id>", "Workspace ID")
+    .option("--from <file>", "Create from YAML/JSON file instead of flags")
+    .action(async (opts) => {
+    const { automationCreate } = await import("./commands/automation.js");
+    await automationCreate(opts);
+});
+automation
+    .command("enable <id>")
+    .description("Activate an automation")
+    .option("--workspace <id>")
+    .action(async (id, opts) => {
+    const { automationEnable } = await import("./commands/automation.js");
+    await automationEnable(id, opts);
+});
+automation
+    .command("disable <id>")
+    .description("Pause an automation")
+    .option("--workspace <id>")
+    .action(async (id, opts) => {
+    const { automationDisable } = await import("./commands/automation.js");
+    await automationDisable(id, opts);
+});
+automation
+    .command("delete <id>")
+    .description("Delete an automation")
+    .option("--workspace <id>")
+    .option("--force", "Skip confirmation prompt")
+    .action(async (id, opts) => {
+    const { automationDelete } = await import("./commands/automation.js");
+    await automationDelete(id, opts);
+});
+automation
+    .command("schema")
+    .description("Fetch the automation DSL schema from the pod (AI context)")
+    .option("--write-context [path]", "Write markdown context file for Claude Code")
+    .option("--json", "Output raw JSON instead of formatted markdown")
+    .action(async (opts) => {
+    const { automationSchema } = await import("./commands/automation.js");
+    await automationSchema(opts);
+});
+// ─── graph ────────────────────────────────────────────────────────────────────
+program
+    .command("graph")
+    .description("Low-level BFS graph traversal from an entity (prefer `synap ask` — graph is one of its signals)")
+    .requiredOption("--entity <id>", "Start entity ID")
+    .option("--depth <n>", "Traversal depth (max 3)", "2")
+    .option("--json", "Raw JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    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")
+    .description("Show event chain for an entity or recent pod events")
+    .option("--entity <id>", "Filter by entity ID (subjectId)")
+    .option("--limit <n>", "Number of events", "20")
+    .option("--json", "Raw JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { listEvents } = await import("./commands/events.js");
+    await listEvents(opts);
+});
+// ─── view ─────────────────────────────────────────────────────────────────────
+const view = program
+    .command("view")
+    .description("Manage views");
+view
+    .command("create")
+    .description("Create a view (table, kanban, bento, …)")
+    .requiredOption("--type <type>", "View type: table|kanban|bento|list|grid|gallery|calendar|masonry|flow|matrix|branch_tree|whiteboard")
+    .option("--profile <slug>", "Entity profile to display (passed as profileId)")
+    .option("--name <name>", "View name")
+    .option("--workspace <id>", "Workspace ID")
+    .option("--json", "JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { viewCreate } = await import("./commands/view.js");
+    await viewCreate(opts);
+});
+view
+    .command("list", { isDefault: true })
+    .description("List views in the active workspace")
+    .option("--type <type>", "Filter by view type (e.g. whiteboard, kanban, calendar)")
+    .option("--workspace <id>", "Workspace ID")
+    .option("--json", "JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { viewList } = await import("./commands/view.js");
+    await viewList(opts);
+});
+view
+    .command("arrange <viewId>")
+    .description("Replace the widget arrangement of a bento view")
+    .option("--file <path>", "JSON file containing widget layout (array or { widgets: [...] })")
+    .option("--workspace <id>", "Workspace ID")
+    .option("--json", "JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .addHelpText("after", `
+Examples:
+  synap view arrange <viewId> --file layout.json
+  echo '[{"id":"w1","kind":"widget","x":0,"y":0,"w":6,"h":4}]' | synap view arrange <viewId>
+
+Layout format (array of BentoWidget):
+  [{ "id": "<widgetId>", "kind": "widget|view|entity", "x": 0, "y": 0, "w": 6, "h": 4, "config": {} }]
+  `)
+    .action(async (viewId, opts) => {
+    const { viewArrange } = await import("./commands/view.js");
+    await viewArrange(viewId, opts);
+});
+// ─── explain ──────────────────────────────────────────────────────────────────
+program
+    .command("explain [topic]")
+    .description("Full capability map — what Synap can do and how (no network required)")
+    .action(async (topic) => {
+    const { explain } = await import("./commands/explain.js");
+    await explain({ topic });
+});
+// ─── open ─────────────────────────────────────────────────────────────────────
+program
+    .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);
+    }
+});
+// ─── doc ──────────────────────────────────────────────────────────────────────
+const doc = program
+    .command("doc")
+    .description("Create and update markdown documents on the pod");
+doc
+    .command("create")
+    .description("Create a new markdown document")
+    .requiredOption("--title <title>", "Document title")
+    .option("--content <text>", "Markdown content (inline)")
+    .option("--file <path>", "Read content from a file")
+    .option("--workspace <id>", "Workspace to create the document 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 create --title "My Notes" --content "# Hello"
+  synap doc create --title "My Notes" --file ./notes.md --open
+  echo "# Draft" | synap doc create --title "Draft"
+  `)
+    .action(async (opts) => {
+    const { docCreate } = await import("./commands/doc.js");
+    await docCreate(opts);
+});
+doc
+    .command("update <documentId>")
+    .description("Update a document's content (full replacement, proposal-gated)")
+    .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("--open", "Open in the Synap desktop app after update")
+    .option("--json", "JSON output")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .addHelpText("after", `
+Examples:
+  synap doc update <id> --content "# Updated"
+  synap doc update <id> --file ./notes.md
+  cat notes.md | synap doc update <id>
+  `)
+    .action(async (documentId, opts) => {
+    const { docUpdate } = await import("./commands/doc.js");
+    await docUpdate(documentId, opts);
+});
+// ─── cell ─────────────────────────────────────────────────────────────────────
+const cell = program
+    .command("cell")
+    .description("Define and bundle frame cells for the Synap runtime");
+cell
+    .command("define")
+    .description("Create or update a frame cell on the pod from ESM source")
+    .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("--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", `
+Examples:
+  synap cell define --name "Revenue Chart" --file ./chart.js
+  synap cell define --name "Revenue Chart" --file ./chart.js --deps '{"recharts":"2.12.0"}'
+  cat chart.js | synap cell define --name "Revenue Chart"
+  `)
+    .action(async (opts) => {
+    const { cellDefine } = await import("./commands/cell.js");
+    await cellDefine(opts);
+});
+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("--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("--workspace <id>", "Workspace (used with --define)")
+    .option("--description <text>", "Description (used with --define)")
+    .option("--open", "Open in browser after define (used with --define)")
+    .option("--json", "JSON output")
+    .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.
+
+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"
+  `)
+    .action(async (entry, opts) => {
+    const { cellBuild } = await import("./commands/cell.js");
+    await cellBuild(entry, opts);
+});
+// ─── artifact ─────────────────────────────────────────────────────────────────
+const artifact = program
+    .command("artifact")
+    .description("Create and manage HTML artifacts as Synap documents");
+artifact
+    .command("create")
+    .description("Create an HTML artifact from a local file")
+    .requiredOption("--html <file>", "HTML file to upload")
+    .option("--name <name>", "Document title (default: filename)")
+    .option("--workspace <id>", "Workspace context")
+    .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")
+    .action(async (opts) => {
+    const { artifactCreate } = await import("./commands/artifact.js");
+    await artifactCreate(opts);
+});
+// ─── connect (top-level shorthand) ───────────────────────────────────────────
+program
+    .command("connect-service [service]")
+    .description("Connect an external service (Google, GitHub, Notion, Linear, Slack, …)")
+    .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);
+});
+// ─── tools ──────────────────────────────────────────────────────────────────
+const tools = program
+    .command("tools")
+    .description("Add and manage external service tools and their credentials");
+tools
+    .command("list")
+    .description("List available tools and their connection status")
+    .option("--json", "Output as JSON")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (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);
+});
+tools
+    .command("sync <provider>")
+    .description("Trigger a manual sync for a connected tool")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (provider, opts) => {
+    const { toolsSync } = await import("./commands/tools.js");
+    await toolsSync(provider, opts);
+});
+tools
+    .command("disconnect <provider>")
+    .description("Revoke a tool's connection")
+    .option("--workspace <id>", "Workspace context")
+    .option("--force", "Skip confirmation")
+    .action(async (provider, opts) => {
+    const { toolsDisconnect } = await import("./commands/tools.js");
+    await toolsDisconnect(provider, opts);
+});
+tools
+    .command("schema")
+    .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 { 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("--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);
+});
+// ─── 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
+    .command("providers")
+    .description("Discover AI providers from the pod and configure local tools");
+providers
+    .command("list", { isDefault: true })
+    .description("Show enabled AI providers and their models")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { providersList } = await import("./commands/providers.js");
+    await providersList(opts);
+});
+providers
+    .command("pull")
+    .description("Write pod provider config to a local AI tool (opencode, aider)")
+    .option("--target <name>", "Target tool: opencode | aider")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (opts) => {
+    const { providersPull } = await import("./commands/providers.js");
+    await providersPull(opts);
+});
+// ─── keys ────────────────────────────────────────────────────────────────────
+const keys = program
+    .command("keys")
+    .description("Manage pod API keys");
+keys
+    .command("rotate")
+    .description("Rotate your CLI key to pick up the latest scope set")
+    .action(async () => {
+    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