@synap-core/cli 1.6.1 → 1.8.0

package/dist/commands/discover.d.ts

@@ -0,0 +1,18 @@
+/**
+ * synap discover
+ *
+ * Runtime discovery for AI agents: fetches ground-truth entity profiles
+ * (with property schemas) and the canonical CLI command tree from the pod.
+ *
+ * Replaces static skill file profile descriptions — agents call this once
+ * per session to get current schema including any custom workspace profiles.
+ */
+export interface DiscoverOpts {
+    podUrl?: string;
+    apiKey?: string;
+    workspace?: string;
+    json?: boolean;
+    profiles?: boolean;
+    commands?: boolean;
+}
+export declare function discover(opts: DiscoverOpts): Promise<void>;

package/dist/commands/discover.js

@@ -0,0 +1,71 @@
+/**
+ * synap discover
+ *
+ * Runtime discovery for AI agents: fetches ground-truth entity profiles
+ * (with property schemas) and the canonical CLI command tree from the pod.
+ *
+ * Replaces static skill file profile descriptions — agents call this once
+ * per session to get current schema including any custom workspace profiles.
+ */
+import chalk from "chalk";
+import { log } from "../utils/logger.js";
+import { resolveHubConfig, resolveUserId, hubGet } from "../lib/hub-client.js";
+export async function discover(opts) {
+    try {
+        const cfg = await resolveHubConfig(opts);
+        const userId = await resolveUserId(cfg);
+        const workspaceId = opts.workspace ?? cfg.workspaceId;
+        if (!workspaceId) {
+            console.error(chalk.red("No workspace set. Run: synap use <workspace-id>"));
+            process.exit(1);
+        }
+        const res = await hubGet("/discover", { userId, workspaceId }, cfg);
+        // JSON mode — dump everything (or filtered slice)
+        if (opts.json) {
+            if (opts.profiles) {
+                console.log(JSON.stringify({ profiles: res.profiles }, null, 2));
+            }
+            else if (opts.commands) {
+                console.log(JSON.stringify({ commands: res.commands }, null, 2));
+            }
+            else {
+                console.log(JSON.stringify(res, null, 2));
+            }
+            return;
+        }
+        // Human-readable output
+        if (!opts.commands) {
+            log.heading(`Entity profiles (${res.profiles.length})`);
+            for (const p of res.profiles) {
+                const scope = p.scope === "pod" ? chalk.cyan("pod-wide") : chalk.yellow("workspace");
+                console.log(`\n  ${chalk.bold(p.slug)} ${chalk.dim("·")} ${p.displayName} ${chalk.dim(`[${scope}]`)}`);
+                if (p.description)
+                    console.log(`    ${chalk.dim(p.description)}`);
+                if (p.properties.length > 0) {
+                    for (const prop of p.properties) {
+                        const opts_str = prop.options?.length ? chalk.dim(` (${prop.options.join("|")})`) : "";
+                        const req = prop.required ? chalk.red("*") : "";
+                        console.log(`    ${chalk.dim("·")} ${prop.slug}${req}: ${chalk.dim(prop.type)}${opts_str}`);
+                    }
+                }
+                else {
+                    console.log(`    ${chalk.dim("(no typed properties)")}`);
+                }
+                console.log(`    ${chalk.dim("→")} ${chalk.dim(p.createCommand)}`);
+            }
+        }
+        if (!opts.profiles) {
+            console.log();
+            log.heading("Commands");
+            for (const [name, cmd] of Object.entries(res.commands)) {
+                console.log(`  ${chalk.cyan(name.padEnd(18))} ${chalk.dim(cmd)}`);
+            }
+        }
+        console.log(`\n${chalk.dim(res.hint)}`);
+    }
+    catch (e) {
+        console.error(chalk.red("Error: " + e.message));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=discover.js.map

package/dist/commands/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/commands/discover.ts"],"names":[],"mappings":"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"}

package/dist/commands/doc.d.ts

@@ -0,0 +1,39 @@
+/**
+ * synap doc create / synap doc update
+ *
+ * Manage markdown documents on the pod.
+ *
+ * Usage:
+ *   synap doc create --title "My Doc" --content "# Hello" [--workspace <id>] [--open]
+ *   synap doc create --title "My Doc" --file ./notes.md [--open]
+ *   echo "# Hello" | synap doc create --title "My Doc"
+ *
+ *   synap doc update <id> --content "new body" [--title "New Title"]
+ *   synap doc update <id> --file ./notes.md
+ *   echo "updated" | synap doc update <id>
+ *
+ * API:
+ *   POST  /api/hub/documents        — { userId, workspaceId?, title, content?, type? }
+ *   PATCH /api/hub/documents/:id    — { userId, content } (full-replace, proposal-gated)
+ */
+export interface DocCreateOpts {
+    title: string;
+    content?: string;
+    file?: string;
+    workspace?: string;
+    open?: boolean;
+    json?: boolean;
+    podUrl?: string;
+    apiKey?: string;
+}
+export interface DocUpdateOpts {
+    content?: string;
+    file?: string;
+    title?: string;
+    open?: boolean;
+    json?: boolean;
+    podUrl?: string;
+    apiKey?: string;
+}
+export declare function docCreate(opts: DocCreateOpts): Promise<void>;
+export declare function docUpdate(documentId: string, opts: DocUpdateOpts): Promise<void>;

package/dist/commands/doc.js

@@ -0,0 +1,130 @@
+/**
+ * synap doc create / synap doc update
+ *
+ * Manage markdown documents on the pod.
+ *
+ * Usage:
+ *   synap doc create --title "My Doc" --content "# Hello" [--workspace <id>] [--open]
+ *   synap doc create --title "My Doc" --file ./notes.md [--open]
+ *   echo "# Hello" | synap doc create --title "My Doc"
+ *
+ *   synap doc update <id> --content "new body" [--title "New Title"]
+ *   synap doc update <id> --file ./notes.md
+ *   echo "updated" | synap doc update <id>
+ *
+ * API:
+ *   POST  /api/hub/documents        — { userId, workspaceId?, title, content?, type? }
+ *   PATCH /api/hub/documents/:id    — { userId, content } (full-replace, proposal-gated)
+ */
+import { readFileSync } from "fs";
+import { log } from "../utils/logger.js";
+import { resolveHubConfig, resolveUserId, hubPost, hubPatch, } from "../lib/hub-client.js";
+import { openInBrowser } from "./open.js";
+/** Read content from --content flag, --file flag, or stdin (in that priority order). */
+async function resolveContent(content, file) {
+    if (content !== undefined)
+        return content;
+    if (file) {
+        try {
+            return readFileSync(file, "utf-8");
+        }
+        catch (e) {
+            log.error(`Cannot read file: ${file} — ${e.message}`);
+            process.exit(1);
+        }
+    }
+    // stdin — only when it's a pipe (not a TTY)
+    if (!process.stdin.isTTY) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            process.stdin.on("data", (chunk) => chunks.push(chunk));
+            process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+            process.stdin.on("error", reject);
+        });
+    }
+    return undefined;
+}
+export async function docCreate(opts) {
+    try {
+        const cfg = await resolveHubConfig(opts);
+        const userId = await resolveUserId(cfg);
+        const workspaceId = opts.workspace ?? cfg.workspaceId;
+        if (!workspaceId) {
+            log.error("Workspace ID required. Use --workspace <id> or set active workspace with: synap use <id>");
+            process.exit(1);
+        }
+        const content = await resolveContent(opts.content, opts.file);
+        const body = {
+            userId,
+            workspaceId,
+            title: opts.title,
+            type: "markdown",
+        };
+        if (content !== undefined)
+            body.content = content;
+        const res = (await hubPost("/documents", body, cfg));
+        const doc = res.document ?? res;
+        const id = String(doc.id ?? res.id ?? "");
+        if (opts.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const isProposed = res.status === "proposed" || Boolean(res.proposalId);
+        if (isProposed) {
+            log.warn(`Queued for approval (proposal: ${String(res.proposalId ?? "")})`);
+            if (res.reviewUrl)
+                log.dim(`  Review: ${String(res.reviewUrl)}`);
+            return;
+        }
+        log.success(`Document created: ${opts.title}`);
+        log.dim(`  id: ${id}`);
+        log.dim(`  open in browser: synap open document ${id}`);
+        if (opts.open && id) {
+            await openInBrowser({ kind: "document", id });
+        }
+    }
+    catch (e) {
+        log.error("Error: " + e.message);
+        process.exit(1);
+    }
+}
+export async function docUpdate(documentId, opts) {
+    try {
+        const cfg = await resolveHubConfig(opts);
+        const userId = await resolveUserId(cfg);
+        const content = await resolveContent(opts.content, opts.file);
+        if (content === undefined && opts.title === undefined) {
+            log.error("Provide --content, --file, or pipe stdin to supply new content. " +
+                "Title-only updates require --content as well (backend limitation).");
+            process.exit(1);
+        }
+        const body = { userId };
+        if (content !== undefined)
+            body.content = content;
+        if (opts.title !== undefined)
+            body.title = opts.title;
+        const res = (await hubPatch(`/documents/${documentId}`, body, cfg));
+        if (opts.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const isProposed = res.status === "proposed" || Boolean(res.proposalId);
+        if (isProposed) {
+            log.warn(`Queued for approval (proposal: ${String(res.proposalId ?? "")})`);
+            if (res.reviewUrl)
+                log.dim(`  Review: ${String(res.reviewUrl)}`);
+            return;
+        }
+        log.success(`Document updated: ${documentId.slice(0, 8)}…`);
+        if (opts.title)
+            log.dim(`  title: ${opts.title}`);
+        if (opts.open) {
+            await openInBrowser({ kind: "document", id: documentId });
+        }
+    }
+    catch (e) {
+        log.error("Error: " + e.message);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=doc.js.map

package/dist/commands/doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.js","sourceRoot":"","sources":["../../src/commands/doc.ts"],"names":[],"mappings":"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"}

package/dist/commands/events.d.ts

@@ -0,0 +1,26 @@
+/**
+ * synap events
+ *
+ * Show the event chain for an entity or recent pod-wide events.
+ *
+ * Usage:
+ *   synap events --entity <id>            # last 20 events for entity
+ *   synap events --entity <id> --limit 50
+ *   synap events --entity <id> --json
+ *   synap events --limit 20               # recent pod-wide events
+ *
+ * API: GET /api/hub/events
+ * Query params: userId (pinned server-side), subjectId, type, subjectType,
+ *               fromDate, limit (default 50, max 200).
+ * Response: { events: WireEvent[] }  — newest first.
+ * WireEvent shape: { id, type, subjectType?, subjectId?, userId?, workspaceId?,
+ *                    data?, timestamp? }
+ */
+export interface ListEventsOpts {
+    entity?: string;
+    limit?: string;
+    json?: boolean;
+    podUrl?: string;
+    apiKey?: string;
+}
+export declare function listEvents(opts: ListEventsOpts): Promise<void>;

package/dist/commands/events.js

@@ -0,0 +1,68 @@
+/**
+ * synap events
+ *
+ * Show the event chain for an entity or recent pod-wide events.
+ *
+ * Usage:
+ *   synap events --entity <id>            # last 20 events for entity
+ *   synap events --entity <id> --limit 50
+ *   synap events --entity <id> --json
+ *   synap events --limit 20               # recent pod-wide events
+ *
+ * API: GET /api/hub/events
+ * Query params: userId (pinned server-side), subjectId, type, subjectType,
+ *               fromDate, limit (default 50, max 200).
+ * Response: { events: WireEvent[] }  — newest first.
+ * WireEvent shape: { id, type, subjectType?, subjectId?, userId?, workspaceId?,
+ *                    data?, timestamp? }
+ */
+import chalk from "chalk";
+import { log } from "../utils/logger.js";
+import { resolveHubConfig, hubGet } from "../lib/hub-client.js";
+export async function listEvents(opts) {
+    try {
+        const cfg = await resolveHubConfig(opts);
+        const limit = parseInt(opts.limit ?? "20", 10);
+        const params = { limit };
+        if (opts.entity)
+            params.subjectId = opts.entity;
+        const res = await hubGet("/events", params, cfg);
+        const events = (res.events ?? res.items ?? (Array.isArray(res) ? res : []));
+        if (opts.json) {
+            console.log(JSON.stringify(events, null, 2));
+            return;
+        }
+        const scope = opts.entity
+            ? `entity: ${opts.entity.slice(0, 8)}…`
+            : "pod-wide";
+        console.log(chalk.bold(`\nRecent events (${scope})`));
+        console.log("");
+        if (events.length === 0) {
+            log.dim("(no events found)");
+            console.log("");
+            return;
+        }
+        for (const ev of events) {
+            // Normalise timestamp — may be ISO string or Date
+            const raw = ev.timestamp ?? ev.createdAt ?? "";
+            let ts = String(raw);
+            try {
+                if (ts) {
+                    const d = new Date(ts);
+                    ts = d.toISOString().replace("T", " ").slice(0, 16);
+                }
+            }
+            catch { /* leave as-is */ }
+            const evType = String(ev.eventType ?? ev.type ?? "–");
+            const subjectType = ev.subjectType ? chalk.dim(` [${ev.subjectType}]`) : "";
+            const subjectId = ev.subjectId ? chalk.dim(`  → ${String(ev.subjectId).slice(0, 8)}`) : "";
+            console.log(`  ${chalk.dim(ts.padEnd(17))}  ${chalk.cyan(evType.padEnd(36))}${subjectType}${subjectId}`);
+        }
+        console.log("");
+    }
+    catch (e) {
+        log.error("Error: " + e.message);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/commands/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/commands/events.ts"],"names":[],"mappings":"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"}

package/dist/commands/explain.d.ts

@@ -0,0 +1,21 @@
+/**
+ * synap explain [topic]
+ *
+ * Static capability map — no network calls needed. Tells any agent starting
+ * cold what Synap can do and which CLI command to use for each operation.
+ *
+ * Usage:
+ *   synap explain              # full capability map
+ *   synap explain graph        # relations & graph traversal
+ *   synap explain memory       # memory & knowledge
+ *   synap explain automation   # automations
+ *   synap explain agents       # agents & runner
+ *   synap explain governance   # proposals & governance
+ *   synap explain views        # views & bento
+ *   synap explain events       # event chain
+ *   synap explain connectors   # connectors
+ */
+export interface ExplainOpts {
+    topic?: string;
+}
+export declare function explain(opts: ExplainOpts): Promise<void>;

package/dist/commands/explain.js

@@ -0,0 +1,248 @@
+/**
+ * synap explain [topic]
+ *
+ * Static capability map — no network calls needed. Tells any agent starting
+ * cold what Synap can do and which CLI command to use for each operation.
+ *
+ * Usage:
+ *   synap explain              # full capability map
+ *   synap explain graph        # relations & graph traversal
+ *   synap explain memory       # memory & knowledge
+ *   synap explain automation   # automations
+ *   synap explain agents       # agents & runner
+ *   synap explain governance   # proposals & governance
+ *   synap explain views        # views & bento
+ *   synap explain events       # event chain
+ *   synap explain connectors   # connectors
+ */
+import chalk from "chalk";
+// ── Section renderers ──────────────────────────────────────────────────────────
+function sectionEntities() {
+    console.log(chalk.bold("\n## Entities & Profiles"));
+    console.log(chalk.dim("  Every piece of data is an entity with a profile type (schema)."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap orient")}               ${chalk.dim("→ see workspaces, profiles, capabilities")}`);
+    console.log(`  ${chalk.cyan("synap list profiles")}        ${chalk.dim("→ entity types available in active workspace")}`);
+    console.log(`  ${chalk.cyan("synap list entities")}        ${chalk.dim("→ browse entities (--profile, --workspace, --limit)")}`);
+    console.log(`  ${chalk.cyan("synap show <id>")}            ${chalk.dim("→ entity detail + all linked relations")}`);
+    console.log(`  ${chalk.cyan("synap get entity <id>")}      ${chalk.dim("→ raw entity properties")}`);
+    console.log(`  ${chalk.cyan("synap create entity")}        ${chalk.dim("→ --profile task --name 'Fix bug' --props '{}'")}`);
+    console.log(`  ${chalk.cyan("synap set entity <id>")}      ${chalk.dim("→ --props '{\"status\":\"done\"}'")}`);
+    console.log(`  ${chalk.cyan("synap browse [profile]")}     ${chalk.dim("→ paginated entity list (cleanest UX)")}`);
+    console.log(`  ${chalk.cyan("synap ask <query>")}          ${chalk.dim("→ the one read verb — routes across all substrates")}`);
+}
+function sectionGraph() {
+    console.log(chalk.bold("\n## Relations & Graph"));
+    console.log(chalk.dim("  Entities are connected by typed relations forming a traversable graph."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap create relation")}      ${chalk.dim("→ --source <id> --target <id> --type extends")}`);
+    console.log(`  ${chalk.cyan("synap graph --entity <id>")}  ${chalk.dim("→ BFS traversal depth 2 (--depth 3 for deeper)")}`);
+    console.log(`  ${chalk.cyan("synap show <id>")}            ${chalk.dim("→ entity + its relations in one view")}`);
+    console.log("");
+    console.log(chalk.dim("  Relation types are workspace-defined. Check your workspace schema for valid types."));
+    console.log(chalk.dim("  maxDepth clamped to 3. Response: flat array of entity + relation records."));
+}
+function sectionMemory() {
+    console.log(chalk.bold("\n## Memory & Knowledge"));
+    console.log(chalk.dim("  Canonical verbs: ask (read) · capture (structured write) · note (quick)."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap note <text>")}          ${chalk.dim("→ save a quick note (creates a note entity)")}`);
+    console.log(`  ${chalk.cyan("synap ask <query>")}          ${chalk.dim("→ the one read verb — routes semantic/procedural/episodic")}`);
+    console.log(`  ${chalk.cyan("synap capture")}              ${chalk.dim("→ structured knowledge: --type gotcha|lesson|decision|reference")}`);
+    console.log(`                              ${chalk.dim("     --claim 'text' --why 'context' --tags 'repo:x'")}`);
+    console.log(`  ${chalk.cyan("synap context")}              ${chalk.dim("→ session-start: knowledge + proposals + tasks")}`);
+    console.log(`  ${chalk.cyan("synap observe write <text>")} ${chalk.dim("→ record user observation (AI-maintained model)")}`);
+    console.log(`  ${chalk.cyan("synap observe recall <q>")}   ${chalk.dim("→ search user observations")}`);
+}
+function sectionEvents() {
+    console.log(chalk.bold("\n## Events & Event Chain"));
+    console.log(chalk.dim("  Every mutation emits a typed event. Subscribe for real-time feeds."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap events --entity <id>")} ${chalk.dim("→ recent event history for an entity")}`);
+    console.log(`  ${chalk.cyan("synap events --limit 50")}    ${chalk.dim("→ pod-wide recent events")}`);
+    console.log(`  ${chalk.cyan("synap subscribe")}            ${chalk.dim("→ NDJSON stream (long-poll, Ctrl+C to stop)")}`);
+    console.log(`  ${chalk.cyan("synap subscribe --event proposal.*")}  ${chalk.dim("→ filtered stream")}`);
+    console.log("");
+    console.log(chalk.dim("  Event shape: { id, type, subjectType, subjectId, userId, workspaceId, data, timestamp }"));
+    console.log(chalk.dim("  Query params: subjectId, type, subjectType, fromDate, limit (max 200)."));
+}
+function sectionAutomation() {
+    console.log(chalk.bold("\n## Automations"));
+    console.log(chalk.dim("  Trigger→filter→action rules. Triggers: event pattern, cron, webhook, manual."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap automation list")}      ${chalk.dim("→ list automations (--workspace, --status)")}`);
+    console.log(`  ${chalk.cyan("synap automation describe <id>")}`);
+    console.log(`  ${chalk.cyan("synap automation create")}    ${chalk.dim("→ --name X --trigger event:entity.* --action notify")}`);
+    console.log(`  ${chalk.cyan("synap automation enable <id> / disable <id> / delete <id>")}`);
+    console.log(`  ${chalk.cyan("synap automation schema")}    ${chalk.dim("→ fetch DSL schema (AI context)")}`);
+    console.log("");
+    console.log(chalk.dim("  Action types: notify | channel-message | none"));
+    console.log(chalk.dim("  Cron trigger: --trigger cron:0_*_*_*_*   Event: --trigger event:entity.*"));
+}
+function sectionViews() {
+    console.log(chalk.bold("\n## Views"));
+    console.log(chalk.dim("  Named query + rendering configs over the entity store."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap view list")}            ${chalk.dim("→ list views (--workspace)")}`);
+    console.log(`  ${chalk.cyan("synap view create")}          ${chalk.dim("→ --type kanban --profile task --name 'My Board'")}`);
+    console.log("");
+    console.log(chalk.dim("  View types (12):"));
+    console.log(chalk.dim("    table | kanban | bento | list | grid | gallery"));
+    console.log(chalk.dim("    calendar | masonry | flow | matrix | branch_tree | whiteboard"));
+    console.log("");
+    console.log(chalk.dim("  Bento views hold a widget arrangement (react-grid-layout)."));
+    console.log(chalk.dim("  Each bento widget: { id, kind: view|entity|widget|<custom>, x, y, w, h, config }"));
+}
+function sectionGovernance() {
+    console.log(chalk.bold("\n## Proposals & Governance"));
+    console.log(chalk.dim("  AI mutations that require approval go through proposals first."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap proposals list")}       ${chalk.dim("→ pending proposals (--workspace, --limit)")}`);
+    console.log(`  ${chalk.cyan("synap proposals approve <id>")} ${chalk.dim("→ --reason 'text'")}`);
+    console.log(`  ${chalk.cyan("synap proposals reject <id>")} ${chalk.dim("→ --reason 'text'")}`);
+    console.log("");
+    console.log(chalk.dim("  When a mutation is gated: response.status = 'proposed', response.proposalId set."));
+    console.log(chalk.dim("  Proposals are reversible — approve, reject, or revert after execution."));
+}
+function sectionConnectors() {
+    console.log(chalk.bold("\n## Connectors"));
+    console.log(chalk.dim("  39 Nango-powered integrations: Google, GitHub, Notion, Linear, Slack, Jira, …"));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap connectors list")}      ${chalk.dim("→ available connectors + connection status")}`);
+    console.log(`  ${chalk.cyan("synap connect-service [name]")} ${chalk.dim("→ interactive connect flow")}`);
+    console.log(`  ${chalk.cyan("synap connectors sync <provider>")} ${chalk.dim("→ trigger manual sync")}`);
+    console.log(`  ${chalk.cyan("synap connectors disconnect <provider>")}`);
+    console.log(`  ${chalk.cyan("synap connectors schema")}    ${chalk.dim("→ supported providers + field mapping (AI context)")}`);
+}
+function sectionAgents() {
+    console.log(chalk.bold("\n## Agents"));
+    console.log(chalk.dim("  Named agent identities (separate keys) + autonomous runner + recurring schedules."));
+    console.log("");
+    console.log(`  ${chalk.cyan("synap agents list")}          ${chalk.dim("→ configured agent identities")}`);
+    console.log(`  ${chalk.cyan("synap agents create")}        ${chalk.dim("→ --template twin|assistant|custom --name X")}`);
+    console.log(`  ${chalk.cyan("synap agents add")}           ${chalk.dim("→ register pre-existing credential")}`);
+    console.log(`  ${chalk.cyan("synap agent run")}            ${chalk.dim("→ --goal 'text' --persona researcher")}`);
+    console.log(`  ${chalk.cyan("synap agent schedule")}       ${chalk.dim("→ --goal X --name Y --every daily")}`);
+    console.log(`  ${chalk.cyan("synap agent tick")}           ${chalk.dim("→ run due schedules (wire to crontab)")}`);
+    console.log("");
+    console.log(chalk.dim("  Persona types: researcher | assistant | developer"));
+    console.log(chalk.dim("  Model alias: synap/advanced (default). Pass --model to override."));
+}
+function sectionQuickRef() {
+    console.log(chalk.bold("\n## CLI Quick Reference"));
+    console.log("");
+    console.log(chalk.dim("  Auth & setup"));
+    console.log(`  ${chalk.cyan("synap pods list / add / use <name>")}`);
+    console.log(`  ${chalk.cyan("synap use <workspace-id>")}   ${chalk.dim("→ set active workspace")}`);
+    console.log(`  ${chalk.cyan("synap orient")}               ${chalk.dim("→ who am I, what workspaces, capabilities")}`);
+    console.log("");
+    console.log(chalk.dim("  Data"));
+    console.log(`  ${chalk.cyan("synap browse [profile]")}  ${chalk.cyan("synap show <id>")}  ${chalk.cyan("synap ask <q>")}`);
+    console.log(`  ${chalk.cyan("synap create entity")}  ${chalk.cyan("synap set entity <id>")}`);
+    console.log(`  ${chalk.cyan("synap note <text>")}  ${chalk.cyan("synap capture --type lesson")}`);
+    console.log("");
+    console.log(chalk.dim("  Graph"));
+    console.log(`  ${chalk.cyan("synap graph --entity <id> [--depth 2]")}`);
+    console.log(`  ${chalk.cyan("synap create relation --source X --target Y --type related_to")}`);
+    console.log("");
+    console.log(chalk.dim("  Events"));
+    console.log(`  ${chalk.cyan("synap events --entity <id>")}`);
+    console.log(`  ${chalk.cyan("synap subscribe [--event proposal.*]")}`);
+    console.log("");
+    console.log(chalk.dim("  Governance"));
+    console.log(`  ${chalk.cyan("synap proposals list")}  ${chalk.cyan("synap proposals approve <id>")}`);
+    console.log("");
+    console.log(chalk.dim("  Browser navigation (requires desktop app)"));
+    console.log(`  ${chalk.cyan("synap open entity <id>")}     ${chalk.dim("→ open entity in side panel")}`);
+    console.log(`  ${chalk.cyan("synap open view <id>")}       ${chalk.dim("→ open view in main panel")}`);
+    console.log(`  ${chalk.cyan("synap open cell <typeKey>")}  ${chalk.dim("→ open any registered cell in side panel")}`);
+    console.log("");
+    console.log(chalk.dim("  AI-generated cells (Capability B)"));
+    console.log(`  ${chalk.cyan("synap artifact create --html <file>")}  ${chalk.dim("→ define a frame cell from HTML source")}`);
+    console.log(`  ${chalk.cyan("  --name <name> --open")}               ${chalk.dim("→ set cell name + open immediately in browser")}`);
+    console.log("");
+    console.log(chalk.dim("  Context for this session"));
+    console.log(`  ${chalk.cyan("synap context")}              ${chalk.dim("→ knowledge + proposals + tasks")}`);
+    console.log(`  ${chalk.cyan("synap explain [topic]")}      ${chalk.dim("→ full capability map (this command)")}`);
+}
+// ── Main export ───────────────────────────────────────────────────────────────
+export async function explain(opts) {
+    const topic = opts.topic?.toLowerCase();
+    switch (topic) {
+        case "graph":
+        case "relations":
+        case "relation":
+            sectionGraph();
+            break;
+        case "memory":
+        case "knowledge":
+        case "note":
+        case "recall":
+            sectionMemory();
+            break;
+        case "events":
+        case "event":
+        case "subscribe":
+            sectionEvents();
+            break;
+        case "automation":
+        case "automations":
+            sectionAutomation();
+            break;
+        case "views":
+        case "view":
+        case "bento":
+            sectionViews();
+            break;
+        case "governance":
+        case "proposals":
+        case "proposal":
+            sectionGovernance();
+            break;
+        case "connectors":
+        case "connector":
+        case "integrations":
+            sectionConnectors();
+            break;
+        case "agents":
+        case "agent":
+            sectionAgents();
+            break;
+        case "entities":
+        case "entity":
+        case "profiles":
+            sectionEntities();
+            break;
+        case "quickref":
+        case "quick-ref":
+        case "ref":
+        case "commands":
+            sectionQuickRef();
+            break;
+        case undefined:
+        case "":
+        case "all": {
+            // Full capability map
+            console.log(chalk.bold.cyan("\nSynap Capability Map"));
+            console.log(chalk.dim("  Sovereign personal data infrastructure. Run any section with: synap explain <topic>"));
+            console.log(chalk.dim("  Topics: entities | graph | memory | events | automation | views | governance | connectors | agents\n"));
+            sectionEntities();
+            sectionGraph();
+            sectionMemory();
+            sectionEvents();
+            sectionAutomation();
+            sectionViews();
+            sectionGovernance();
+            sectionConnectors();
+            sectionAgents();
+            sectionQuickRef();
+            break;
+        }
+        default:
+            console.log(chalk.yellow(`  Unknown topic: "${opts.topic}". Valid topics:`));
+            console.log(chalk.dim("  entities | graph | memory | events | automation | views | governance | connectors | agents | commands"));
+            process.exit(1);
+    }
+    console.log("");
+}
+//# sourceMappingURL=explain.js.map