@synap-core/cli 1.7.0 → 1.10.0

package/dist/commands/keys.js

@@ -0,0 +1,78 @@
+/**
+ * synap keys — Manage pod API keys
+ *
+ * Subcommands: rotate
+ */
+import chalk from "chalk";
+import ora from "ora";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { resolveHubConfig, hubPost, HubError, renderHubError } from "../lib/hub-client.js";
+import { log } from "../utils/logger.js";
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const CONFIG_FILE = path.join(os.homedir(), ".synap", "config.json");
+function updateConfigKey(newApiKey) {
+    const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+    const config = JSON.parse(raw);
+    const activePod = config.activePod;
+    const pods = config.pods;
+    if (activePod && pods && pods[activePod]) {
+        pods[activePod].hubApiKey = newApiKey;
+        config.pods = pods;
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+export async function keysRotate(opts) {
+    let cfg;
+    try {
+        cfg = await resolveHubConfig({ podUrl: opts.podUrl });
+    }
+    catch (err) {
+        log.error(err.message);
+        process.exit(1);
+    }
+    const spinner = ora({ text: "Rotating CLI key…", color: "cyan" }).start();
+    let result;
+    try {
+        result = (await hubPost("/keys/rotate-cli", {}, cfg));
+        spinner.succeed(chalk.green("Key rotated"));
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to rotate key"));
+        if (err instanceof HubError && (err.status === 401 || err.status === 403)) {
+            log.error("The current key is already invalid (401/403).");
+            log.dim("Run `synap init` to fully re-provision your credentials.");
+        }
+        else {
+            renderHubError(err);
+        }
+        process.exit(1);
+    }
+    // Update config file and current process env
+    try {
+        updateConfigKey(result.apiKey);
+    }
+    catch (err) {
+        log.warn(`Key rotated but could not update config file: ${err.message}`);
+        log.dim(`Set it manually: SYNAP_HUB_API_KEY=${result.apiKey}`);
+    }
+    process.env.SYNAP_HUB_API_KEY = result.apiKey;
+    // Print scope table
+    console.log();
+    log.heading("New key details");
+    console.log();
+    console.log(`  ${chalk.dim("Key ID:")}  ${result.keyId}`);
+    console.log();
+    if (result.scopes && result.scopes.length > 0) {
+        console.log(`  ${chalk.dim("Scopes:")}`);
+        for (const scope of result.scopes) {
+            console.log(`    ${chalk.green("✓")} ${scope}`);
+        }
+    }
+    else {
+        console.log(`  ${chalk.dim("Scopes: (none returned)")}`);
+    }
+    console.log();
+}
+//# sourceMappingURL=keys.js.map

package/dist/commands/keys.js.map

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

package/dist/commands/knowledge.d.ts

@@ -1,36 +1,52 @@
 /**
- * synap capture / synap recall --structured
+ * synap capture — the one canonical structured-WRITE verb.
  *
- * Structured knowledge capture and retrieval using the engineering_knowledge
- * entity profile. Backed by Hub Protocol entity endpoints — separate from the
- * episodic /memory endpoints used by `synap remember` / `synap recall`.
+ * SMART MODE (no --type): `synap capture "free text"`
+ *   → POST /capture/structure (AI pipeline: proposals + relations + followUp)
+ *   → renders a proposal table, prompts y/N, then POST /capture/execute.
+ *
+ * TYPED MODE (--type): `synap capture --type gotcha --claim "…" [--why] [--evidence] [--tags]`
+ *   → POST /entities as a typed `knowledge` entity; `ek_type` (gotcha|lesson|decision|
+ *     reference) discriminates the kind — ONE store, type tags (the canonical pattern,
+ *     NOT a residual dump). The workspace lens supplies the domain (no
+ *     `engineering_knowledge`). A formal decision RECORD (rationale/alternatives/status
+ *     lifecycle) comes from smart `capture "<text>"` or `create entity --profile=decision`.
+ *
+ * Workspace routing: --workspace > --team (first product ws) > memory ws (default,
+ * auto-approved, agent-private) > active ws.
  */
-interface BaseOpts {
-    podUrl?: string;
-    apiKey?: string;
-}
 export type KnowledgeType = "gotcha" | "lesson" | "decision" | "reference";
 export interface CaptureOpts {
-    type: KnowledgeType;
-    claim: string;
+    /** Smart mode: positional free-text (no --type). When present, uses AI /capture/structure pipeline. */
+    text?: string;
+    /** Typed mode: one of gotcha|lesson|decision|reference */
+    type?: KnowledgeType;
+    claim?: string;
     why?: string;
     evidence?: string;
     tags?: string;
-    json?: boolean;
-}
-export interface RecallStructuredOpts extends BaseOpts {
-    type?: KnowledgeType;
-    tags?: string;
-    limit?: string;
+    /** Override to first product workspace instead of the active workspace */
+    team?: boolean;
+    /** Explicit workspace override — highest priority */
     workspace?: string;
+    /**
+     * GLOBAL lane: write a pod-wide procedural runbook to `knowledge_keys`
+     * (cross-cutting best-practice/how-to, visible in every workspace) instead of
+     * a domain `knowledge` entity in the active workspace.
+     */
+    global?: boolean;
+    /** Optional stable key (namespace:slug) for a --global runbook; derived if absent. */
+    key?: string;
     json?: boolean;
+    /** Skip the y/N confirmation prompt (smart mode only) */
+    yes?: boolean;
+    /** Link the captured knowledge to the active session */
+    session?: boolean;
 }
 export declare function captureKnowledge(opts: CaptureOpts): Promise<void>;
-export declare function recallStructured(query: string, opts: RecallStructuredOpts): Promise<void>;
 export declare function provisionAgentWorkspace(opts: {
     agentUserId?: string;
     name?: string;
     use?: boolean;
     json?: boolean;
 }): Promise<void>;
-export {};

package/dist/commands/knowledge.js

@@ -1,33 +1,344 @@
 /**
- * synap capture / synap recall --structured
+ * synap capture — the one canonical structured-WRITE verb.
  *
- * Structured knowledge capture and retrieval using the engineering_knowledge
- * entity profile. Backed by Hub Protocol entity endpoints — separate from the
- * episodic /memory endpoints used by `synap remember` / `synap recall`.
+ * SMART MODE (no --type): `synap capture "free text"`
+ *   → POST /capture/structure (AI pipeline: proposals + relations + followUp)
+ *   → renders a proposal table, prompts y/N, then POST /capture/execute.
+ *
+ * TYPED MODE (--type): `synap capture --type gotcha --claim "…" [--why] [--evidence] [--tags]`
+ *   → POST /entities as a typed `knowledge` entity; `ek_type` (gotcha|lesson|decision|
+ *     reference) discriminates the kind — ONE store, type tags (the canonical pattern,
+ *     NOT a residual dump). The workspace lens supplies the domain (no
+ *     `engineering_knowledge`). A formal decision RECORD (rationale/alternatives/status
+ *     lifecycle) comes from smart `capture "<text>"` or `create entity --profile=decision`.
+ *
+ * Workspace routing: --workspace > --team (first product ws) > memory ws (default,
+ * auto-approved, agent-private) > active ws.
  */
 import chalk from "chalk";
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { log } from "../utils/logger.js";
-import { resolveHubConfig, resolveUserId, hubPost, hubGet, } from "../lib/hub-client.js";
+import { resolveHubConfig, resolveUserId, hubPost, readActiveSessionId, renderHubError, } from "../lib/hub-client.js";
+import { getAgentWorkspaceRouting } from "../lib/pod.js";
+import { laneFromSource, resolveWorkspaceName, formatLaneLine, laneJsonFields, } from "../lib/capture-lane.js";
+/**
+ * Resolve the workspace for a DOMAIN capture (the `knowledge` entity, the Work
+ * lane). Knowledge is workspace-scoped, so the destination IS the separation:
+ * a Builder lesson stays in Builder, a marketing one in marketing.
+ *
+ * Priority: --workspace > --team (first product ws) > active ws.
+ *
+ * NOTE: the agent-memory ("AI-self") lane was removed — the AI no longer dumps
+ * captures into a private agent workspace. Everything it learns routes to a real
+ * lane: Work (here), Global (`--global` → knowledge_keys), or User
+ * (`record_observation` → user_observation). The per-adjunct memory workspace is
+ * being decommissioned.
+ */
+async function resolveKnowledgeWorkspace(opts, _cfg, activeWorkspaceId) {
+    if (opts.workspace) {
+        return { workspaceId: opts.workspace, source: "explicit" };
+    }
+    if (opts.team) {
+        const routing = getAgentWorkspaceRouting();
+        const teamWs = routing?.productWorkspaceIds?.[0];
+        return { workspaceId: teamWs ?? activeWorkspaceId, source: teamWs ? "team" : "active (no team workspace configured)" };
+    }
+    return {
+        workspaceId: activeWorkspaceId,
+        source: activeWorkspaceId ? "active" : "active (run `synap use <id>` to set a workspace)",
+    };
+}
+/** Slugify free text into a knowledge_keys slug fragment. */
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "entry";
+}
+/**
+ * GLOBAL lane: write a pod-wide procedural runbook to `knowledge_keys`.
+ * Cross-cutting best-practice/how-to, addressed by a stable `namespace:slug` key
+ * and visible in every workspace (pod-wide). The kind (gotcha/lesson/decision/
+ * reference) becomes the namespace; the claim derives the slug unless --key given.
+ */
+async function captureGlobalRunbook(opts, cfg, authorUserId) {
+    const type = opts.type ?? "reference";
+    const claim = opts.claim ?? opts.text ?? "";
+    const key = opts.key ?? `${type}:${slugify(claim)}`;
+    const [namespace, ...slugParts] = key.split(":");
+    const slug = slugParts.join(":") || slugify(claim);
+    const valueParts = [claim];
+    if (opts.why)
+        valueParts.push(`\n**Why:** ${opts.why}`);
+    if (opts.evidence)
+        valueParts.push(`\n**Evidence:** ${opts.evidence}`);
+    if (opts.tags)
+        valueParts.push(`\n_tags: ${opts.tags}_`);
+    const res = await hubPost("/knowledge", {
+        key,
+        namespace,
+        slug,
+        value: valueParts.join("\n"),
+        author: authorUserId,
+        // workspaceId omitted → pod-wide (null). The Global lane is, by definition,
+        // cross-workspace. (Workspace-scoped knowledge_keys await a backend fix —
+        // POST /knowledge currently drops workspaceId; domain knowledge uses the
+        // `knowledge` entity instead, which IS workspace-scoped.)
+    }, cfg);
+    const report = {
+        lane: "global",
+        workspaceId: undefined,
+        workspaceName: "pod-wide",
+        governance: "auto",
+    };
+    if (opts.json) {
+        console.log(JSON.stringify({ key, id: res.id, stored: true, ...laneJsonFields(report) }, null, 2));
+        return;
+    }
+    log.success(`[${type}] ${claim.slice(0, 80)}`);
+    log.dim(`  key: ${key}`);
+    console.log("  " + formatLaneLine(report));
+}
+/** Render the /capture/structure result as a compact human-readable summary. */
+function renderStructureResult(result) {
+    const { proposals, relations, followUp, degraded } = result;
+    if (degraded) {
+        log.warn("AI structuring unavailable — degraded fallback.");
+    }
+    if (proposals.length === 0) {
+        log.dim("No entity proposals extracted.");
+        return;
+    }
+    log.heading("Proposed entities");
+    // Column widths
+    const typeW = Math.min(18, Math.max(6, ...proposals.map((p) => p.profileSlug.length)));
+    const titleW = Math.min(48, Math.max(10, ...proposals.map((p) => p.title.length)));
+    const header = [
+        chalk.bold("#".padEnd(3)),
+        chalk.bold("Type".padEnd(typeW)),
+        chalk.bold("Title".padEnd(titleW)),
+    ].join("  ");
+    console.log("  " + header);
+    console.log("  " + chalk.dim("-".repeat(3 + 2 + typeW + 2 + titleW)));
+    for (let i = 0; i < proposals.length; i++) {
+        const p = proposals[i];
+        const row = [
+            chalk.dim(String(i + 1).padEnd(3)),
+            chalk.cyan(p.profileSlug.slice(0, typeW).padEnd(typeW)),
+            p.title.slice(0, titleW).padEnd(titleW),
+        ].join("  ");
+        console.log("  " + row);
+        if (p.description) {
+            log.dim(`     ${p.description.slice(0, 80)}`);
+        }
+    }
+    if (relations.length > 0) {
+        log.blank();
+        log.dim(`  ${relations.length} relation${relations.length !== 1 ? "s" : ""} will be created.`);
+    }
+    if (result.targetWorkspaceId || result.targetProjectId) {
+        log.blank();
+        if (result.targetWorkspaceId) {
+            const conf = typeof result.targetWorkspaceConfidence === "number"
+                ? ` (${Math.round(result.targetWorkspaceConfidence * 100)}%)`
+                : "";
+            log.dim(`  → workspace: ${result.targetWorkspaceId}${conf}`);
+            if (result.targetWorkspaceReason) {
+                log.dim(`      ${result.targetWorkspaceReason.slice(0, 90)}`);
+            }
+        }
+        if (result.targetProjectId) {
+            const conf = typeof result.targetProjectConfidence === "number"
+                ? ` (${Math.round(result.targetProjectConfidence * 100)}%)`
+                : "";
+            log.dim(`  → project:   ${result.targetProjectId}${conf}`);
+            if (result.targetProjectReason) {
+                log.dim(`      ${result.targetProjectReason.slice(0, 90)}`);
+            }
+        }
+    }
+    // followUp may be a bare string (previously dropped — the `.question` guard
+    // never matched) or a { question, suggestions[] } object (chips previously
+    // rendered as "[object Object]"). Handle both; render each chip by its label.
+    if (followUp) {
+        const question = typeof followUp === "string" ? followUp : followUp.question;
+        if (question) {
+            log.blank();
+            log.info(`Follow-up: ${question}`);
+            const chips = typeof followUp === "string" ? [] : followUp.suggestions ?? [];
+            for (const c of chips) {
+                log.dim(`  · ${c.label ?? c.value}`);
+            }
+        }
+    }
+}
+async function runSmartCapture(text, opts) {
+    const cfg = await resolveHubConfig();
+    const userId = await resolveUserId(cfg);
+    const { workspaceId, source } = await resolveKnowledgeWorkspace(opts, cfg, cfg.workspaceId);
+    if (!workspaceId) {
+        console.error(chalk.red("No workspace set. Run:\n" +
+            "  synap connect   (sets up memory + team workspace routing)\n" +
+            "  synap use <workspace-id>   (manual override)"));
+        process.exit(1);
+    }
+    // 1. Structure
+    const smartSessionId = opts.session ? readActiveSessionId() : undefined;
+    const structureBody = { userId, text, workspaceId, ...(smartSessionId ? { sessionId: smartSessionId } : {}) };
+    const structureRes = await hubPost("/capture/structure", structureBody, cfg);
+    // Explicit --workspace is a deliberate pin: send it as-is, no AI routing hints.
+    // Otherwise forward the AI's routing signal and let the backend decide
+    // (auto = AI target wins over ambient when confidence is high enough AND the
+    // user is a member). Project from structure is forwarded when present.
+    const isExplicitOverride = Boolean(opts.workspace);
+    const routingFields = isExplicitOverride
+        ? {}
+        : {
+            workspaceRouting: "auto",
+            aiWorkspaceId: structureRes.targetWorkspaceId,
+            aiWorkspaceConfidence: structureRes.targetWorkspaceConfidence,
+            aiWorkspaceReason: structureRes.targetWorkspaceReason,
+        };
+    if (structureRes.targetProjectId) {
+        routingFields.projectId = structureRes.targetProjectId;
+    }
+    if (opts.json) {
+        // --json without --yes: print structure result and exit
+        if (!opts.yes) {
+            console.log(JSON.stringify(structureRes, null, 2));
+            return;
+        }
+        // --json + --yes: also execute and print combined result
+        const executeRes = await hubPost("/capture/execute", {
+            userId,
+            workspaceId,
+            ...(smartSessionId ? { sessionId: smartSessionId } : {}),
+            ...routingFields,
+            entities: structureRes.proposals,
+            relations: structureRes.relations ?? [],
+        }, cfg);
+        const report = await buildSmartLaneReport(executeRes, workspaceId, source, cfg);
+        console.log(JSON.stringify({ structure: structureRes, execute: executeRes, ...laneJsonFields(report) }, null, 2));
+        return;
+    }
+    // 2. Render proposals
+    renderStructureResult(structureRes);
+    const count = structureRes.proposals?.length ?? 0;
+    if (count === 0)
+        return;
+    // 3. Confirm
+    let confirmed = opts.yes ?? false;
+    if (!confirmed) {
+        log.blank();
+        const rl = readline.createInterface({ input, output });
+        try {
+            const answer = await rl.question(chalk.bold(`  Create ${count} entr${count !== 1 ? "ies" : "y"}? [y/N] `));
+            confirmed = answer.trim().toLowerCase() === "y";
+        }
+        finally {
+            rl.close();
+        }
+    }
+    if (!confirmed) {
+        log.dim("Aborted.");
+        return;
+    }
+    // 4. Execute
+    const executeRes = await hubPost("/capture/execute", {
+        userId,
+        workspaceId,
+        ...(smartSessionId ? { sessionId: smartSessionId } : {}),
+        ...routingFields,
+        entities: structureRes.proposals,
+        relations: structureRes.relations ?? [],
+    }, cfg);
+    const created = executeRes.entitiesCreated
+        ?? executeRes.created
+        ?? count;
+    log.success(`${created} entr${created !== 1 ? "ies" : "y"} created.`);
+    if (executeRes.relationsCreated) {
+        log.dim(`  ${executeRes.relationsCreated} relation${Number(executeRes.relationsCreated) !== 1 ? "s" : ""} created.`);
+    }
+    if (executeRes.movedToWorkspace) {
+        log.dim(`  → filed into workspace ${String(executeRes.movedToWorkspace)}`);
+    }
+    const report = await buildSmartLaneReport(executeRes, workspaceId, source, cfg);
+    console.log("  " + formatLaneLine(report));
+}
+/**
+ * Build the lane report for a smart-capture execute response. Smart capture may
+ * land directly or be queued as proposals — detect the latter from the execute
+ * payload (proposed/proposalsCreated/status) and fall back to auto otherwise.
+ */
+async function buildSmartLaneReport(executeRes, workspaceId, source, cfg) {
+    const isProposed = executeRes.status === "proposed" ||
+        Boolean(executeRes.proposalId) ||
+        Number(executeRes.proposalsCreated ?? 0) > 0;
+    return {
+        lane: laneFromSource(source),
+        workspaceId,
+        workspaceName: await resolveWorkspaceName(workspaceId, cfg),
+        governance: isProposed ? "proposed" : "auto",
+    };
+}
+// ─── Legacy engineering-memory capture ────────────────────────────────────────
 export async function captureKnowledge(opts) {
     try {
+        // Mutual exclusion: smart mode (positional text) and typed mode (--type/--claim)
+        // are two distinct flows. Mixing them silently drops one — fail loud instead.
+        if (opts.text !== undefined && opts.type !== undefined) {
+            console.error(chalk.red("Cannot mix smart mode (positional text) with typed mode (--type/--claim)."));
+            console.error(chalk.dim("  Use one: `synap capture \"free text\"`  OR  `synap capture --type gotcha --claim \"…\"`"));
+            process.exit(1);
+        }
+        // Smart mode: positional text with no --type
+        if (opts.text !== undefined && opts.type === undefined) {
+            await runSmartCapture(opts.text, opts);
+            return;
+        }
+        // Legacy mode: --type is required
+        if (!opts.type) {
+            console.error(chalk.red("Missing required option: --type <gotcha|lesson|decision|reference>"));
+            console.error(chalk.dim("  Or pass free text as a positional arg for smart capture: synap capture \"your text\""));
+            process.exit(1);
+        }
+        if (!opts.claim) {
+            console.error(chalk.red("Missing required option: --claim <text>"));
+            process.exit(1);
+        }
         const cfg = await resolveHubConfig();
         const userId = await resolveUserId(cfg);
-        const workspaceId = cfg.workspaceId;
+        // GLOBAL lane: pod-wide procedural runbook → knowledge_keys.
+        if (opts.global) {
+            await captureGlobalRunbook(opts, cfg, userId);
+            return;
+        }
+        const { workspaceId, source } = await resolveKnowledgeWorkspace(opts, cfg, cfg.workspaceId);
         if (!workspaceId) {
             console.error(chalk.red("No workspace set. Run:\n" +
-                "  synap workspace provision-agent   (create your agent workspace)\n" +
-                "  synap use <workspace-id>           (set it as active)"));
+                "  synap connect   (sets up memory + team workspace routing)\n" +
+                "  synap use <workspace-id>   (manual override)"));
             process.exit(1);
         }
         const tags = opts.tags
             ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean)
             : [];
         const title = opts.claim.slice(0, 120);
+        // Every --type entry is a typed `knowledge` entity; ek_type discriminates the
+        // kind. This is "one store, type tags" (the research-canonical pattern) — NOT a
+        // residual catch-all: each row is typed by ek_type and lives in the workspace
+        // lens that supplies its domain (so no `engineering_knowledge`). A structured
+        // decision RECORD (rationale/alternatives/status) is a different artifact, reached
+        // via smart `capture "<text>"` or `create entity --profile=decision`.
+        const sessionId = opts.session ? readActiveSessionId() : undefined;
         const res = await hubPost("/entities", {
             userId,
             workspaceId,
-            profileSlug: "engineering_knowledge",
+            profileSlug: "knowledge",
             title,
+            ...(sessionId ? { sessionId } : {}),
             properties: {
                 ek_type: opts.type,
                 ek_claim: opts.claim,
@@ -36,61 +347,48 @@ export async function captureKnowledge(opts) {
                 ...(tags.length > 0 ? { ek_tags: tags } : {}),
             },
         }, cfg);
-        if (opts.json) {
-            console.log(JSON.stringify({ id: res.id, stored: true }, null, 2));
-            return;
-        }
-        log.success(`[${opts.type}] ${opts.claim.slice(0, 80)}`);
-        if (res.id)
-            log.dim(`  id: ${res.id}`);
-    }
-    catch (e) {
-        console.error(chalk.red("Error: " + e.message));
-        process.exit(1);
-    }
-}
-export async function recallStructured(query, opts) {
-    try {
-        const cfg = await resolveHubConfig(opts);
-        const limit = parseInt(opts.limit ?? "10", 10);
-        const params = {
-            profileSlug: "engineering_knowledge",
-            q: query,
-            limit,
+        // Governance may queue the write as a proposal rather than creating directly
+        const isProposed = res.status === "proposed" || Boolean(res.proposalId);
+        // Declare which lane + workspace + governance this capture took, so the
+        // caller always knows where its knowledge landed.
+        const report = {
+            lane: laneFromSource(source),
+            workspaceId,
+            workspaceName: await resolveWorkspaceName(workspaceId, cfg),
+            governance: isProposed ? "proposed" : "auto",
         };
-        const workspaceId = opts.workspace ?? cfg.workspaceId;
-        if (workspaceId)
-            params.workspaceId = workspaceId;
-        const res = await hubGet("/entities", params, cfg);
-        const entities = (res.entities ?? res.items ?? res);
-        let list = Array.isArray(entities) ? entities : [];
-        if (opts.type) {
-            list = list.filter((e) => {
-                const props = (e.properties ?? {});
-                return props.ek_type === opts.type;
-            });
-        }
         if (opts.json) {
-            console.log(JSON.stringify(list, null, 2));
+            if (isProposed) {
+                console.log(JSON.stringify({
+                    proposed: true,
+                    proposalId: res.proposalId ?? res.id,
+                    reviewUrl: res.reviewUrl ?? null,
+                    message: "Write queued for approval — not yet stored.",
+                    ...laneJsonFields(report),
+                }, null, 2));
+            }
+            else {
+                console.log(JSON.stringify({ id: res.id, stored: true, workspace: source, ...laneJsonFields(report) }, null, 2));
+            }
             return;
         }
-        if (list.length === 0) {
-            log.dim(`No knowledge entries found for "${query}"`);
-            return;
+        if (isProposed) {
+            log.warn(`Queued for approval — not yet stored.`);
+            log.dim(`  The target workspace requires human review for agent writes.`);
+            if (res.reviewUrl)
+                log.dim(`  Review: ${String(res.reviewUrl)}`);
+            else
+                log.dim(`  Open Synap and approve the pending proposal to persist this entry.`);
+            console.log("  " + formatLaneLine(report));
         }
-        for (const item of list) {
-            const props = (item.properties ?? {});
-            const type = String(props.ek_type ?? "–");
-            const claim = String(props.ek_claim ?? item.name ?? "–");
-            const why = props.ek_why ? `\n    why: ${props.ek_why}` : "";
-            const tags = Array.isArray(props.ek_tags) && props.ek_tags.length > 0
-                ? chalk.dim(`  [${props.ek_tags.join(", ")}]`)
-                : "";
-            console.log(`  ${chalk.cyan(type.padEnd(10))} ${claim}${tags}${chalk.dim(why)}`);
+        else {
+            log.success(`[${opts.type}] ${opts.claim.slice(0, 80)}`);
+            log.dim(`  workspace: ${source}  id: ${String(res.id ?? "")}`);
+            console.log("  " + formatLaneLine(report));
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }
@@ -120,7 +418,7 @@ export async function provisionAgentWorkspace(opts) {
         }
     }
     catch (e) {
-        console.error(chalk.red("Error: " + e.message));
+        renderHubError(e);
         process.exit(1);
     }
 }