@synap-core/cli 1.6.1 → 1.8.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:
@@ -30,33 +29,23 @@ 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);
 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);
 });
-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")
-    .action(async (opts) => {
-    const { finish } = await import("./commands/finish.js");
-    await finish(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')")
@@ -87,7 +76,7 @@ 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)")
     .action(async (name, opts) => {
     const { podsUse } = await import("./commands/pods.js");
     await podsUse(name, { surface: opts.surface });
@@ -100,19 +89,16 @@ pods
     const { podsRemove } = await import("./commands/pods.js");
     await podsRemove(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")
-    .action(async (opts) => {
-    const { securityAudit } = await import("./commands/security-audit.js");
-    await securityAudit(opts);
+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("status")
-    .description("Show Synap pod and OpenClaw health status")
+    .description("Show Synap pod health and API status")
     .action(async () => {
     const { status } = await import("./commands/status.js");
     await status();
@@ -126,101 +112,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,60 +169,66 @@ 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();
 });
 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 to a Synap pod (self-hosted or managed)")
+    .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}`);
-    }
-    else {
-        spinner.fail("Authentication timed out. Try: synap login --token <token>");
-        console.log(chalk.dim("  Get a token at: https://synap.live/account/tokens"));
+    // Already have pods — show status and offer reconnect if any are unreachable
+    const { checkPodHealth } = await import("./lib/pod.js");
+    const ora = (await import("ora")).default;
+    const spinner = ora("Checking pod health...").start();
+    const checks = await Promise.all(profiles.map(async (p) => {
+        const h = await checkPodHealth(p.config.podUrl).catch(() => ({ healthy: false }));
+        return { ...p, healthy: h.healthy };
+    }));
+    spinner.stop();
+    console.log("\n  Configured pods:\n");
+    for (const p of checks) {
+        const active = p.active ? chalk.green(" ● ") : "   ";
+        const status = p.healthy ? chalk.green("ok") : chalk.red("unreachable");
+        console.log(`  ${active}${chalk.bold(p.name.padEnd(14))} ${status}  ${chalk.dim(p.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})`));
+    console.log();
+    const unreachable = checks.filter((p) => !p.healthy);
+    if (unreachable.length > 0) {
+        console.log(chalk.yellow(`  ${unreachable.length} pod(s) unreachable. To refresh credentials:`));
+        for (const p of unreachable) {
+            console.log(chalk.dim(`    synap login --reconnect ${p.name}`));
+        }
+        console.log();
     }
     else {
-        console.log(chalk.dim("  Not logged in"));
+        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})`));
+        console.log();
+        console.log(chalk.dim("  synap pods use <name>    — switch active pod"));
+        console.log(chalk.dim("  synap pods add           — connect another pod"));
     }
 });
 // ─── orient ───────────────────────────────────────────────────────────────────
@@ -356,68 +253,103 @@ 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")
-    .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);
-});
-// ─── remember / recall ────────────────────────────────────────────────────────
+// ─── note ─────────────────────────────────────────────────────────────────────
+// Quick `note` entity. The one canonical READ verb is `ask`; the one canonical
+// structured-WRITE verb is `capture`. (search / recall / remember removed — they
+// were redundant doors `ask`/`capture`/`note` already cover.)
 program
-    .command("remember <text>")
-    .description("Store a memory on the pod")
-    .option("--context <entity-id>", "Link memory to an entity")
+    .command("note <text>")
+    .description("Quick freeform note → note entity (for structured learnings use `synap capture`)")
+    .option("--context <entity-id>", "Link this note to an entity")
     .option("--json", "Output as 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);
+    const { noteData } = await import("./commands/data.js");
+    await noteData(text, 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("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("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("--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("--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 });
+});
+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")
+    .description("Runtime discovery: entity profiles with property schemas + CLI command tree")
+    .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("--workspace <id>", "Workspace to query (defaults to active workspace)")
+    .action(async (opts) => {
+    const { discover } = await import("./commands/discover.js");
+    await discover(opts);
 });
 // ─── workspace ────────────────────────────────────────────────────────────────
 // Context setup commands. Run once to configure the session — all subsequent
@@ -459,6 +391,18 @@ 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")
@@ -472,6 +416,259 @@ 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);
+});
+// ─── 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("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")
+    .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 (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")
@@ -527,6 +724,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")
@@ -593,5 +791,424 @@ 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("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);
+});
+// ─── 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> <id>")
+    .description("Open an entity, view, cell, or document in the Synap desktop app")
+    .action(async (kind, id) => {
+    if (kind !== "entity" && kind !== "view" && kind !== "cell" && kind !== "document") {
+        console.error(`Unknown kind: "${kind}". Use: entity | view | cell | document`);
+        process.exit(1);
+    }
+    const { openInBrowser } = await import("./commands/open.js");
+    await openInBrowser({ kind: kind, id });
+});
+// ─── 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 { connectorsConnect } = await import("./commands/connectors.js");
+    await connectorsConnect(service, opts);
+});
+// ─── connectors ──────────────────────────────────────────────────────────────
+const connectors = program
+    .command("connectors")
+    .description("Manage pod connector integrations (Nango-powered)");
+connectors
+    .command("list")
+    .description("List available connectors and connection status")
+    .option("--json", "Output as JSON")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (opts) => {
+    const { connectorsList } = await import("./commands/connectors.js");
+    await connectorsList(opts);
+});
+connectors
+    .command("sync <provider>")
+    .description("Trigger a manual sync for a connected provider")
+    .option("--workspace <id>", "Workspace context")
+    .action(async (provider, opts) => {
+    const { connectorsSync } = await import("./commands/connectors.js");
+    await connectorsSync(provider, opts);
+});
+connectors
+    .command("disconnect <provider>")
+    .description("Revoke a connector connection")
+    .option("--workspace <id>", "Workspace context")
+    .option("--force", "Skip confirmation")
+    .action(async (provider, opts) => {
+    const { connectorsDisconnect } = await import("./commands/connectors.js");
+    await connectorsDisconnect(provider, opts);
+});
+connectors
+    .command("schema")
+    .description("Fetch connector schema and supported providers (AI context)")
+    .option("--write-context [path]", "Write to .claude/CONNECTOR_CONTEXT.md")
+    .option("--json", "Output raw JSON instead of formatted markdown")
+    .action(async (opts) => {
+    const { connectorsSchema } = await import("./commands/connectors.js");
+    await connectorsSchema(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({});
+});
 program.parse();
 //# sourceMappingURL=index.js.map