@synap-core/cli 1.10.0 → 1.12.2

package/dist/commands/knowledge.js

@@ -12,43 +12,168 @@
  *     `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.
+ * Workspace routing for Work-lane knowledge: --workspace (explicit pin) >
+ * --team (first product ws, when configured) > omit workspaceId (server-derived
+ * / pod-wide preferred). Never default-pin to the active profile workspace —
+ * that commonly is Pod Admin and would dump domain knowledge into admin.
  */
 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, readActiveSessionId, renderHubError, } from "../lib/hub-client.js";
+import { resolveHubConfig, resolveUserId, hubPost, hubGet, resolveActiveSessionId, renderHubError, } from "../lib/hub-client.js";
+import { unwrapList } from "../lib/unwrapList.js";
 import { getAgentWorkspaceRouting } from "../lib/pod.js";
-import { laneFromSource, resolveWorkspaceName, formatLaneLine, laneJsonFields, } from "../lib/capture-lane.js";
+import { resolvePodWide } from "../lib/pod-wide.js";
+import { laneFromSource, resolveWorkspaceName, formatLaneLine, laneJsonFields, writeGovernance, } from "../lib/capture-lane.js";
+import { isDegraded, degradedMessage, readCaptureExecute, formatWorkspaceRouting, formatPendingWorkspaceSwitch, headlessPlacementFields, projectRoutingHints, workspaceRoutingHints, } from "../lib/capture-structure.js";
+import { UUID_RE } from "../lib/id.js";
+import { chooseKnowledgeTitle } from "../lib/knowledge-title.js";
+// ─── Client-side length guard ────────────────────────────────────────────────
+// Captures used to die SERVER-SIDE with a raw "String length 1404 > maximum
+// 1000" after the user had already composed + confirmed — surface the same
+// caps client-side, BEFORE sending, so a too-long capture gets a heads-up
+// instead of a mid-flight rejection. Not a hard block: --yes/--json paths and
+// a declined truncation still send as-is and let the pod be the final judge
+// (the caps below mirror the pod's contract but are not re-validated here).
+//
+// Mirrors:
+//   - synap-backend CaptureStructureRequestSchema.text
+//     (packages/api/src/routers/hub-protocol/rest/_codecs/misc.ts)
+//   - the `knowledge` profile's ek_claim/ek_why/ek_evidence property defs
+//     (packages/database/src/utils/ensure-system-profiles.ts)
+const SMART_TEXT_MAX = 8000;
+const CLAIM_MAX = 1000;
+const WHY_MAX = 5000;
+const EVIDENCE_MAX = 2000;
+/**
+ * Warn when `value` exceeds `max`, and offer to truncate (interactive) or
+ * proceed as-is. Returns the value to send (possibly truncated), or
+ * `undefined` if the user aborted.
+ *
+ * Non-interactive (`--yes` / `--json`): warns to stderr and proceeds unchanged
+ * — this is a heads-up, not a client-side hard block; the pod is still free to
+ * accept a since-raised cap.
+ */
+async function guardLength(label, value, max, opts) {
+    if (value.length <= max)
+        return value;
+    if (opts.yes || opts.json) {
+        log.warn(`${label} is ${value.length} chars (pod limit ~${max}) — sending as-is; the pod may reject it.`);
+        return value;
+    }
+    log.warn(`${label} is ${value.length} chars — the pod's limit is ~${max}.`);
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(chalk.bold(`  Truncate to ${max} chars and continue? [Y/n/(a)bort] `));
+        const a = answer.trim().toLowerCase();
+        if (a === "n" || a === "abort" || a === "a")
+            return undefined;
+        return value.slice(0, max);
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * 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.
+ * lane).
  *
- * Priority: --workspace > --team (first product ws) > active ws.
+ * Priority: --workspace (explicit pin) > --team (first product ws when
+ * configured) > omit workspaceId.
  *
- * 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.
+ * Default is intentional omit: sending an ambient/active workspaceId is a
+ * backend rung-1 pin. Team profiles often default active workspace to Pod Admin,
+ * which dumped domain knowledge into admin. Leaving workspaceId out lets the
+ * server place knowledge (pod-wide preferred for knowledge kinds / AI routing on
+ * smart capture).
+ *
+ * NOTE: the agent-memory ("AI-self") lane was removed — everything routes to a
+ * real lane: Work (here), Global (`--global` → knowledge_keys), or User
+ * (`record_observation` → user_observation).
  */
-async function resolveKnowledgeWorkspace(opts, _cfg, activeWorkspaceId) {
+async function resolveKnowledgeWorkspace(opts) {
     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)" };
+        if (teamWs) {
+            return { workspaceId: teamWs, source: "team" };
+        }
+        // --team asked for a product pin but none is configured: still omit.
+        // Do not fall back to active workspace (that reintroduces the Admin dump).
+        return {
+            workspaceId: undefined,
+            source: "server-derived (no team workspace configured — pod-wide preferred for knowledge)",
+        };
     }
     return {
-        workspaceId: activeWorkspaceId,
-        source: activeWorkspaceId ? "active" : "active (run `synap use <id>` to set a workspace)",
+        workspaceId: undefined,
+        source: "server-derived (pod-wide preferred for knowledge)",
     };
 }
+/**
+ * Resolve a `--project` value (id or name) to a project id on the active pod.
+ * Mirrors `synap import`'s resolveProjectArg — same shape, same "not found"
+ * wording, kept local here since neither command shares a project-resolution
+ * lib yet. Throws on no match so a typo'd project name fails loud instead of
+ * silently dropping the pin.
+ */
+async function resolveProjectArg(value, cfg) {
+    if (UUID_RE.test(value))
+        return value;
+    const res = (await hubGet("/projects", {}, cfg));
+    const list = unwrapList(res, ["projects"]);
+    const match = list.find((p) => String(p.name ?? "").toLowerCase() === value.toLowerCase());
+    if (!match) {
+        const names = list.map((p) => String(p.name ?? p.id)).join(", ");
+        throw new Error(`Project '${value}' not found.${names ? ` Available: ${names}` : ""}`);
+    }
+    return String(match.id);
+}
+/**
+ * Render the pod's project-link receipt honestly — never a bare "✓ stored"
+ * that hides a dropped project coordinate. Read DEFENSIVELY: the two write
+ * doors this command uses shape their receipt differently —
+ *   - POST /capture/execute → `res.project = { projectId, rung, status }`
+ *   - POST /entities        → `res.writeReceipt.projectId` (present only once
+ *     applied — omitted while the write is still a pending proposal)
+ * and the exact field name may still shift as the backend's receipt work
+ * lands, so this checks both shapes rather than assuming one.
+ */
+function renderProjectReceipt(res, requestedProjectId, isProposed) {
+    if (!requestedProjectId)
+        return;
+    const captureProject = res.project;
+    if (captureProject?.projectId) {
+        if (captureProject.status === "linked") {
+            log.dim(`  → linked to project ${captureProject.projectId.slice(0, 8)}`);
+        }
+        else if (captureProject.status === "proposed") {
+            log.dim(`  → project ${captureProject.projectId.slice(0, 8)} proposed (advisory — awaiting confirm, not yet linked)`);
+        }
+        else {
+            log.dim(`  → project ${captureProject.projectId.slice(0, 8)} (${captureProject.status ?? "unknown"})`);
+        }
+        return;
+    }
+    const writeReceipt = res.writeReceipt;
+    if (writeReceipt?.projectId) {
+        log.dim(`  → linked to project ${writeReceipt.projectId.slice(0, 8)}`);
+        return;
+    }
+    if (isProposed) {
+        // The whole write is pending review — the project link rides along with
+        // it and applies on approval, not dropped.
+        log.dim(`  → project ${requestedProjectId.slice(0, 8)} will link on approval (write is pending review)`);
+        return;
+    }
+    // A project pin was sent but no receipt confirms it — say so plainly rather
+    // than letting a silent drop look like success.
+    log.dim(`  → project NOT linked (pod did not confirm ${requestedProjectId.slice(0, 8)} — it may not be reachable from this workspace)`);
+}
 /** Slugify free text into a knowledge_keys slug fragment. */
 function slugify(text) {
     return text
@@ -101,12 +226,14 @@ async function captureGlobalRunbook(opts, cfg, authorUserId) {
     log.dim(`  key: ${key}`);
     console.log("  " + formatLaneLine(report));
 }
+// ─── Smart capture mode (no --type) ──────────────────────────────────────────
+// Structure/execute wire shapes + the degraded/execute interpreters are shared
+// with `synap import` in lib/capture-structure.ts (ONE mirror, no drift).
 /** 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.");
-    }
+    const proposals = result.proposals ?? [];
+    const relations = result.relations ?? [];
+    const followUp = result.followUp;
     if (proposals.length === 0) {
         log.dim("No entity proposals extracted.");
         return;
@@ -140,11 +267,10 @@ function renderStructureResult(result) {
     }
     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}`);
+        const workspaceLine = formatWorkspaceRouting(result);
+        if (workspaceLine) {
+            // The pod's NAME for its pick, with its confidence once.
+            log.dim(`  → workspace: ${workspaceLine}`);
             if (result.targetWorkspaceReason) {
                 log.dim(`      ${result.targetWorkspaceReason.slice(0, 90)}`);
             }
@@ -174,35 +300,92 @@ function renderStructureResult(result) {
         }
     }
 }
-async function runSmartCapture(text, opts) {
+async function runSmartCapture(rawText, opts) {
+    const guarded = await guardLength("Capture text", rawText, SMART_TEXT_MAX, opts);
+    if (guarded === undefined) {
+        log.dim("Aborted.");
+        return;
+    }
+    const text = guarded;
     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)"));
+    // Do NOT default-pin cfg.workspaceId — omit unless --workspace / --team.
+    const { workspaceId, source } = await resolveKnowledgeWorkspace(opts);
+    // Default Work-lane knowledge omits workspaceId so the pod can place it
+    // (AI routing on smart capture / pod-wide preferred for knowledge kinds).
+    if (!workspaceId && !opts.json) {
+        log.dim(`  Placement: ${source} — workspaceId omitted.`);
+        log.dim("  Pin with --workspace <id> or --team (first product workspace).");
+    }
+    // Project pin: explicit --project (id or name) wins; otherwise the ambient
+    // lens (SYNAP_PROJECT_ID / the active Claude session's pinned project,
+    // already resolved into cfg.projectId by resolveHubConfig).
+    let projectId;
+    try {
+        projectId = opts.project ? await resolveProjectArg(opts.project, cfg) : cfg.projectId;
+    }
+    catch (e) {
+        console.error(chalk.red(e.message));
         process.exit(1);
     }
     // 1. Structure
-    const smartSessionId = opts.session ? readActiveSessionId() : undefined;
-    const structureBody = { userId, text, workspaceId, ...(smartSessionId ? { sessionId: smartSessionId } : {}) };
+    const smartSessionId = opts.session ? resolveActiveSessionId(cfg.podUrl) : undefined;
+    const structureBody = {
+        userId,
+        text,
+        ...(workspaceId ? { workspaceId } : {}),
+        ...(smartSessionId ? { sessionId: smartSessionId } : {}),
+    };
     const structureRes = await hubPost("/capture/structure", structureBody, cfg);
+    // Degraded: the IS structurer is down. The server returns a raw fallback-kind
+    // stand-in (`note`; `degraded: true` on the wire), but we create nothing (browser does the same via
+    // offlineFallback:false) — tell the user, don't silently downgrade the
+    // capture into an unstructured blob behind a success line.
+    if (isDegraded(structureRes)) {
+        if (opts.json) {
+            console.log(JSON.stringify({
+                degraded: true,
+                degradedReason: structureRes.degradedReason ?? null,
+                created: 0,
+                message: degradedMessage(structureRes),
+            }, null, 2));
+        }
+        else {
+            log.warn(degradedMessage(structureRes));
+        }
+        return;
+    }
     // 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.
+    // user is a member).
     const isExplicitOverride = Boolean(opts.workspace);
+    // The AI's advice goes through the ONE structure → execute mapper
+    // (`captureExecuteRoutingHints`, mirrored in capture-structure.ts).
+    // Headless door: the structure step's PLACEMENT decides what is pinned
+    // (`headlessPlacementFields` — the ONE derivation, shared with the pod's own
+    // headless doors). A deterministic placement rides as an explicit
+    // `targetWorkspaceId`; an AI suggestion stays a proposal and is recorded as
+    // `workspaceChoice: "ignored"` — the CLI never shows it before saving.
     const routingFields = isExplicitOverride
         ? {}
         : {
             workspaceRouting: "auto",
-            aiWorkspaceId: structureRes.targetWorkspaceId,
-            aiWorkspaceConfidence: structureRes.targetWorkspaceConfidence,
-            aiWorkspaceReason: structureRes.targetWorkspaceReason,
+            ...headlessPlacementFields(structureRes),
+            ...workspaceRoutingHints(structureRes),
         };
-    if (structureRes.targetProjectId) {
-        routingFields.projectId = structureRes.targetProjectId;
+    // Project: the explicit pin (--project / ambient lens) is the ONE
+    // deterministic field and always wins when present. The AI's own guess is
+    // forwarded ONLY as advisory (aiProjectId) — never promoted to the
+    // deterministic `projectId` field. That promotion was a real bug here
+    // (an AI guess would auto-link and widen cross-workspace access before the
+    // user ever confirmed it); the backend's aiProjectId path records it as a
+    // suggestion instead and never auto-links it.
+    if (projectId) {
+        routingFields.projectId = projectId;
+    }
+    else if (structureRes.targetProjectId) {
+        Object.assign(routingFields, projectRoutingHints(structureRes));
     }
     if (opts.json) {
         // --json without --yes: print structure result and exit
@@ -213,14 +396,19 @@ async function runSmartCapture(text, opts) {
         // --json + --yes: also execute and print combined result
         const executeRes = await hubPost("/capture/execute", {
             userId,
-            workspaceId,
+            ...(workspaceId ? { 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));
+        console.log(JSON.stringify({
+            structure: structureRes,
+            execute: executeRes,
+            ...(projectId ? { requestedProjectId: projectId } : {}),
+            ...laneJsonFields(report),
+        }, null, 2));
         return;
     }
     // 2. Render proposals
@@ -248,39 +436,52 @@ async function runSmartCapture(text, opts) {
     // 4. Execute
     const executeRes = await hubPost("/capture/execute", {
         userId,
-        workspaceId,
+        ...(workspaceId ? { 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.`);
+    // Report what the pod ACTUALLY returned — applied vs proposed vs
+    // nothing-new — never the planned proposal count.
+    const outcome = readCaptureExecute(executeRes);
+    const report = await buildSmartLaneReport(executeRes, workspaceId, source, cfg);
+    if (outcome.proposed) {
+        log.info("Capture proposed — under review, not yet stored.");
+        if (outcome.proposalId)
+            log.dim(`  proposal: ${outcome.proposalId}`);
+        if (outcome.reviewUrl)
+            log.dim(`  review: ${outcome.reviewUrl}`);
     }
-    if (executeRes.movedToWorkspace) {
-        log.dim(`  → filed into workspace ${String(executeRes.movedToWorkspace)}`);
+    else {
+        const n = outcome.entitiesCreated;
+        log.success(`${n} entr${n !== 1 ? "ies" : "y"} created.`);
+        if (outcome.entitiesLinked) {
+            log.dim(`  ${outcome.entitiesLinked} linked to existing entit${outcome.entitiesLinked !== 1 ? "ies" : "y"}.`);
+        }
+        if (outcome.relationsCreated) {
+            log.dim(`  ${outcome.relationsCreated} relation${outcome.relationsCreated !== 1 ? "s" : ""} created.`);
+        }
+        const pending = formatPendingWorkspaceSwitch(outcome);
+        if (pending)
+            log.dim(`  ${pending}`);
     }
-    const report = await buildSmartLaneReport(executeRes, workspaceId, source, cfg);
     console.log("  " + formatLaneLine(report));
+    renderProjectReceipt(executeRes, projectId, outcome.proposed);
 }
 /**
- * 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.
+ * Build the lane report for a smart-capture execute response. Governance
+ * (auto vs proposed) is derived by the ONE shared interpreter so this doesn't
+ * re-implement a third detector.
  */
 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",
+        workspaceName: workspaceId
+            ? await resolveWorkspaceName(workspaceId, cfg)
+            : "server-derived (pod-wide preferred)",
+        governance: readCaptureExecute(executeRes).proposed ? "proposed" : "auto",
     };
 }
 // ─── Legacy engineering-memory capture ────────────────────────────────────────
@@ -308,67 +509,132 @@ export async function captureKnowledge(opts) {
             console.error(chalk.red("Missing required option: --claim <text>"));
             process.exit(1);
         }
+        // Client-side length guard — catch the "String length N > maximum 1000"
+        // server rejection BEFORE it fires, with a chance to truncate/abort
+        // instead of a mid-flight failure after composing + confirming.
+        const guardedClaim = await guardLength("--claim", opts.claim, CLAIM_MAX, opts);
+        if (guardedClaim === undefined) {
+            log.dim("Aborted.");
+            return;
+        }
+        opts.claim = guardedClaim;
+        if (opts.why) {
+            const guardedWhy = await guardLength("--why", opts.why, WHY_MAX, opts);
+            if (guardedWhy === undefined) {
+                log.dim("Aborted.");
+                return;
+            }
+            opts.why = guardedWhy;
+        }
+        if (opts.evidence) {
+            const guardedEvidence = await guardLength("--evidence", opts.evidence, EVIDENCE_MAX, opts);
+            if (guardedEvidence === undefined) {
+                log.dim("Aborted.");
+                return;
+            }
+            opts.evidence = guardedEvidence;
+        }
         const cfg = await resolveHubConfig();
         const userId = await resolveUserId(cfg);
         // GLOBAL lane: pod-wide procedural runbook → knowledge_keys.
-        if (opts.global) {
+        // Canonical spelling is `--pod-wide`; `--global` is the retained alias.
+        if (resolvePodWide(opts)) {
             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 connect   (sets up memory + team workspace routing)\n" +
-                "  synap use <workspace-id>   (manual override)"));
+        // Do NOT default-pin cfg.workspaceId — omit unless --workspace / --team.
+        const { workspaceId, source } = await resolveKnowledgeWorkspace(opts);
+        // Default Work-lane knowledge omits workspaceId so the pod can place it
+        // (server-derived / pod-wide preferred for knowledge kinds).
+        if (!workspaceId && !opts.json) {
+            log.dim(`  Placement: ${source} — workspaceId omitted.`);
+            log.dim("  Pin with --workspace <id> or --team (first product workspace).");
+        }
+        // Project pin: explicit --project (id or name) wins; otherwise the ambient
+        // lens already resolved by resolveHubConfig (SYNAP_PROJECT_ID / the active
+        // Claude session's pinned project). Previously this coordinate was simply
+        // dropped by `capture` — --pod resolved url+key but never the project lens.
+        let projectId;
+        try {
+            projectId = opts.project ? await resolveProjectArg(opts.project, cfg) : cfg.projectId;
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
             process.exit(1);
         }
         const tags = opts.tags
             ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean)
             : [];
-        const title = opts.claim.slice(0, 120);
+        // A title is a short NAME; the claim itself stays in `ek_claim`.
+        const chosen = chooseKnowledgeTitle(opts.claim, opts.title);
+        if (!chosen.ok) {
+            console.error(chalk.red(chosen.reason));
+            process.exit(1);
+        }
+        const title = chosen.title;
         // 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 sessionId = opts.session ? resolveActiveSessionId(cfg.podUrl) : undefined;
         const res = await hubPost("/entities", {
             userId,
-            workspaceId,
+            ...(workspaceId ? { workspaceId } : {}),
             profileSlug: "knowledge",
             title,
             ...(sessionId ? { sessionId } : {}),
+            ...(projectId ? { projectId } : {}),
             properties: {
+                knowledgeForm: opts.type === "gotcha" ? "caution" : "insight",
                 ek_type: opts.type,
                 ek_claim: opts.claim,
                 ...(opts.why ? { ek_why: opts.why } : {}),
                 ...(opts.evidence ? { ek_evidence: opts.evidence } : {}),
                 ...(tags.length > 0 ? { ek_tags: tags } : {}),
             },
+            ...(opts.content?.trim().length ? { content: opts.content } : {}),
         }, cfg);
-        // Governance may queue the write as a proposal rather than creating directly
-        const isProposed = res.status === "proposed" || Boolean(res.proposalId);
+        // Governance may queue the write as a proposal rather than creating
+        // directly — read the real outcome via the ONE shared detector.
+        const isProposed = writeGovernance(res) === "proposed";
+        // The pod's title rubric verdict (absent when the title is clean).
+        const titleLint = readTitleLint(res);
         // 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),
+            workspaceName: workspaceId
+                ? await resolveWorkspaceName(workspaceId, cfg)
+                : "server-derived (pod-wide preferred)",
             governance: isProposed ? "proposed" : "auto",
         };
         if (opts.json) {
+            const writeReceipt = res.writeReceipt;
             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.",
+                    title,
+                    ...(titleLint.length ? { titleLint } : {}),
+                    ...(projectId ? { requestedProjectId: projectId } : {}),
                     ...laneJsonFields(report),
                 }, null, 2));
             }
             else {
-                console.log(JSON.stringify({ id: res.id, stored: true, workspace: source, ...laneJsonFields(report) }, null, 2));
+                console.log(JSON.stringify({
+                    id: res.id,
+                    stored: true,
+                    title,
+                    ...(titleLint.length ? { titleLint } : {}),
+                    workspace: source,
+                    ...(projectId ? { requestedProjectId: projectId, linkedProjectId: writeReceipt?.projectId ?? null } : {}),
+                    ...laneJsonFields(report),
+                }, null, 2));
             }
             return;
         }
@@ -380,18 +646,37 @@ export async function captureKnowledge(opts) {
             else
                 log.dim(`  Open Synap and approve the pending proposal to persist this entry.`);
             console.log("  " + formatLaneLine(report));
+            renderProjectReceipt(res, projectId, true);
         }
         else {
-            log.success(`[${opts.type}] ${opts.claim.slice(0, 80)}`);
+            log.success(`[${opts.type}] ${title}`);
             log.dim(`  workspace: ${source}  id: ${String(res.id ?? "")}`);
             console.log("  " + formatLaneLine(report));
+            renderProjectReceipt(res, projectId, false);
         }
+        renderTitleLint(titleLint);
     }
     catch (e) {
         renderHubError(e);
         process.exit(1);
     }
 }
+/** `writeReceipt.titleLint` from a POST /entities response; [] when clean or absent. */
+export function readTitleLint(res) {
+    const receipt = res.writeReceipt;
+    const raw = Array.isArray(receipt?.titleLint) ? receipt.titleLint : [];
+    return raw.filter((i) => !!i && typeof i === "object" && typeof i.message === "string");
+}
+/** Tell the writer what to rewrite — the title was stored as sent. */
+function renderTitleLint(issues) {
+    const defects = issues.filter((i) => i.severity === "defect");
+    if (!defects.length)
+        return;
+    log.warn("  Title stored as sent, but it should be rewritten:");
+    for (const i of defects)
+        log.dim(`    - ${i.message}`);
+    log.dim(`  Rewrite it with the MCP tool synap_update_entity (title), and pass --title next time.`);
+}
 export async function provisionAgentWorkspace(opts) {
     try {
         const cfg = await resolveHubConfig();