@usenaive-sdk/cli 0.12.5 → 0.13.1

package/dist/commands/brain.js

@@ -2,7 +2,34 @@ import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { basename, extname } from "node:path";
 import { apiRequest, handleApiError, handlePendingApproval } from "../client.js";
-import { agentOutput } from "../output.js";
+import { agentError, agentOutput } from "../output.js";
+import { BRAIN_BINDING_KEY, BRAIN_CONNECT_PATH, bindingNextSteps, boundBrainId, listBrains, resolveAgent, resolveBrainId, selectBrainId, setAgentBrain, tryListAgents, } from "../lib/brain-select.js";
+/**
+ * Normalise a command's brain-selection flags into a selector.
+ *
+ * `|| undefined` and not `?? undefined` ON PURPOSE: every one of these
+ * subcommands previously wrote `...(opts.kb && { knowledge_base_id: opts.kb })`,
+ * so an EMPTY `--kb ""` was silently dropped and the call fell through to the
+ * company default. Mapping "" to undefined keeps that exact behaviour instead of
+ * turning a pathological-but-working invocation into an error.
+ */
+function brainSelector(opts) {
+    return { brain: opts.brain || undefined, kb: opts.kb || undefined, agent: opts.agent || undefined };
+}
+/**
+ * The three flags that name a brain, added to every subcommand that already
+ * scoped its call with `--kb`.
+ *
+ * `--kb <id>` is UNCHANGED and stays first in the help: a UUID passes straight
+ * through with no extra request, exactly as it always has. `--brain` is the same
+ * concept spelled the way the command group is (`naive brain …`) and additionally
+ * accepts a name. `--agent` means "whatever brain that agent is connected to".
+ */
+function withBrainFlags(cmd) {
+    return cmd
+        .option("--brain <name|id>", "Use this brain (by name or id)")
+        .option("--agent <id|name>", "Use the brain this agent is connected to");
+}
 /** Trivial extension -> MIME map; anything else omits content_type and lets the API decide. */
 const CONTENT_TYPES = {
     ".pdf": "application/pdf",
@@ -36,9 +63,41 @@ Subcommands:
   naive brain docs               List ingested documents + processing status
   naive brain doc <id>           Get one document (refreshed processing status)
   naive brain rm-doc <id>        Delete an ingested document (permanent)
-  naive brain list               List the company's knowledge bases
-  naive brain create             Create a new knowledge base
+  naive brain list               Every brain: which is default, and who is connected
+  naive brain create <name>      Create a new knowledge base
+  naive brain default <brain>    Make an existing brain the company default
   naive brain rm <id>            Delete a knowledge base + its documents (permanent)
+  naive brain connect <brain> --agent <a>     Connect an agent to a brain
+  naive brain disconnect --agent <a>          Disconnect it again
+
+A company can have SEVERAL brains (the schema has always allowed it: one row per
+brain, one flagged default). Every read/write subcommand takes the brain three ways:
+  --kb <id>          the shipped spelling — an id, passed straight through
+  --brain <name|id>  the same thing, and it accepts a NAME
+  --agent <id|name>  whatever brain that agent is connected to
+Pass none and you get the company default, exactly as before.
+
+CHOOSING THE DEFAULT:
+  naive brain default <name|id>  Promote an existing brain. One request, no new
+                                 brain, idempotent, and only an ACTIVE brain can
+                                 be promoted.
+  naive brain create X --default Create one AND make it the default.
+  naive brain rm <the default>   Succeeds, and promotes the oldest survivor in
+                                 the same transaction — the empty 204 cannot say
+                                 which, so run 'naive brain list' after.
+
+The run loop (attach → work → consolidate → decide):
+  naive brain attach <goal>      What the brain already knows, BEFORE the work
+  naive brain consolidate        Run-end debrief: learned / decided / left open
+  naive brain proposals [id]     The proposal queue; read one, or decide one
+  naive brain writebacks [id]    The envelopes a run produced
+  naive brain status             Operator view of the brain runtime (this company)
+  naive brain metrics            Nervous-system counters (PROCESS-GLOBAL, not per-company)
+
+  A debrief PROPOSES. Nothing it says is a belief until a proposal is accepted:
+  $ naive brain consolidate --objective "refund audit" --learned "acme|refund window|30 days"
+  $ naive brain proposals --status pending
+  $ naive brain proposals prp_01J --accept --because "confirmed against the contract"
 
 note vs remember:
   'remember' writes a durable SEMANTIC MEMORY episode (facts/entities/claims are
@@ -64,16 +123,17 @@ Examples:
   $ naive brain query "And the P1s?" --session <session_id from the previous answer>
   $ naive brain docs
 `);
-brainCmd
+withBrainFlags(brainCmd
     .command("recall <query>")
     .description("Recall structured semantic memory: facts, entities, and relevant episodes")
     .option("--kb <id>", "Recall from a specific knowledge base")
     .option("--entity <name>", "Filter to one entity/subject")
-    .option("--limit <n>", "Maximum memories to return", (v) => Number.parseInt(v, 10))
+    .option("--limit <n>", "Maximum memories to return", (v) => Number.parseInt(v, 10)))
     .action(async (query, opts) => {
+    const kbId = await selectBrainId("brain.recall", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/recall", {
         query,
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
         ...(opts.entity && { entity: opts.entity }),
         ...(opts.limit && { limit: opts.limit }),
     });
@@ -89,21 +149,22 @@ brainCmd
         related_commands: ["naive brain think", "naive brain remember", "naive brain query"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("remember <content>")
     .alias("mem")
     .description("Write a durable semantic memory episode into the shared company brain")
     .option("--title <title>", "Optional title")
     .option("--source <source>", "Provenance tag (default: cli)")
     .option("--confidence <n>", "0-1 confidence", (v) => Number.parseFloat(v))
-    .option("--kb <id>", "Target a specific knowledge base")
+    .option("--kb <id>", "Target a specific knowledge base"))
     .action(async (content, opts) => {
+    const kbId = await selectBrainId("brain.remember", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/remember", {
         content,
         ...(opts.title && { title: opts.title }),
         source: opts.source ?? "cli",
         ...(opts.confidence !== undefined && { confidence: opts.confidence }),
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
     });
     handleApiError("brain.remember", resp);
     agentOutput({
@@ -114,16 +175,17 @@ brainCmd
         related_commands: ["naive brain recall", "naive brain think"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("think <query>")
     .description("Synthesize from semantic memory and grounded Brain documents with gap notes")
     .option("--kb <id>", "Use a specific knowledge base")
     .option("--session <id>", "Continue a query session")
-    .option("--limit <n>", "Maximum memories to include", (v) => Number.parseInt(v, 10))
+    .option("--limit <n>", "Maximum memories to include", (v) => Number.parseInt(v, 10)))
     .action(async (query, opts) => {
+    const kbId = await selectBrainId("brain.think", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/think", {
         query,
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
         ...(opts.session && { session_id: opts.session }),
         ...(opts.limit && { limit: opts.limit }),
     });
@@ -136,15 +198,16 @@ brainCmd
         related_commands: ["naive brain recall", "naive brain query", "naive brain remember"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("graph")
     .description("Explore the company brain's entity/relation knowledge graph")
     .option("--kb <id>", "Use a specific knowledge base")
     .option("--entity <name>", "Center the graph on one entity/subject")
-    .option("--limit <n>", "Maximum nodes/edges to return", (v) => Number.parseInt(v, 10))
+    .option("--limit <n>", "Maximum nodes/edges to return", (v) => Number.parseInt(v, 10)))
     .action(async (opts) => {
+    const kbId = await selectBrainId("brain.graph", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/graph", {
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
         ...(opts.entity && { entity: opts.entity }),
         ...(opts.limit && { limit: opts.limit }),
     });
@@ -160,15 +223,16 @@ brainCmd
         related_commands: ["naive brain timeline", "naive brain recall", "naive brain think"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("timeline")
     .description("View the company brain's memory events and facts in chronological order")
     .option("--kb <id>", "Use a specific knowledge base")
     .option("--entity <name>", "Filter to one entity/subject")
-    .option("--limit <n>", "Maximum entries to return", (v) => Number.parseInt(v, 10))
+    .option("--limit <n>", "Maximum entries to return", (v) => Number.parseInt(v, 10)))
     .action(async (opts) => {
+    const kbId = await selectBrainId("brain.timeline", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/timeline", {
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
         ...(opts.entity && { entity: opts.entity }),
         ...(opts.limit && { limit: opts.limit }),
     });
@@ -184,16 +248,17 @@ brainCmd
         related_commands: ["naive brain graph", "naive brain recall", "naive brain think"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("forget <scope> <scope_ref>")
     .description("Tombstone/forget a semantic memory scope")
     .option("--kb <id>", "Knowledge base id")
-    .option("--reason <reason>", "Reason for the tombstone")
+    .option("--reason <reason>", "Reason for the tombstone"))
     .action(async (scope, scope_ref, opts) => {
+    const kbId = await selectBrainId("brain.forget", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/forget", {
         scope,
         scope_ref,
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
         ...(opts.reason && { reason: opts.reason }),
     });
     handleApiError("brain.forget", resp);
@@ -207,15 +272,16 @@ brainCmd
         related_commands: ["naive brain recall", "naive brain docs"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("query <question>")
     .description("Ask the knowledge base a question; returns a grounded answer with citations")
     .option("--kb <id>", "Query a specific knowledge base (defaults to the company brain)")
-    .option("--session <id>", "Continue a previous conversation (session_id from an earlier answer)")
+    .option("--session <id>", "Continue a previous conversation (session_id from an earlier answer)"))
     .action(async (question, opts) => {
+    const kbId = await selectBrainId("brain.query", brainSelector(opts));
     const resp = await apiRequest("POST", "/v1/brain/query", {
         question,
-        ...(opts.kb && { knowledge_base_id: opts.kb }),
+        ...(kbId && { knowledge_base_id: kbId }),
         ...(opts.session && { session_id: opts.session }),
     });
     handleApiError("brain.query", resp);
@@ -237,7 +303,7 @@ brainCmd
         related_commands: ["naive brain add", "naive brain docs"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("add")
     .description("Ingest a document into the knowledge base (--file, --text, or --url)")
     .option("--file <path>", "Ingest a local file")
@@ -245,11 +311,11 @@ brainCmd
     .option("--url <url>", "Ingest the content at a URL")
     .option("--name <filename>", "Override the stored filename/label")
     .option("--source <source>", "Provenance tag (e.g. upload, web, agent:researcher)")
-    .option("--kb <id>", "Target a specific knowledge base")
+    .option("--kb <id>", "Target a specific knowledge base"))
     .action(async (opts) => {
     const provided = [opts.file, opts.text, opts.url].filter((v) => v !== undefined).length;
     if (provided !== 1) {
-        console.error(JSON.stringify({
+        console.log(JSON.stringify({
             success: false,
             action: "brain.add",
             error: { code: "missing_argument", message: "Provide exactly one of --file, --text, or --url" },
@@ -261,9 +327,10 @@ brainCmd
         }, null, 2));
         process.exit(1);
     }
+    const kbId = await selectBrainId("brain.add", brainSelector(opts));
     const body = {};
-    if (opts.kb)
-        body.knowledge_base_id = opts.kb;
+    if (kbId)
+        body.knowledge_base_id = kbId;
     if (opts.source)
         body.source = opts.source;
     if (opts.file) {
@@ -302,15 +369,16 @@ brainCmd
         related_commands: ["naive brain query", "naive brain docs", "naive brain doc"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("note <fact>")
     .description("Ingest a short fact as a DOCUMENT (queryable). For semantic memory use 'remember' instead")
     .option("--source <source>", "Who/what recorded it (default: note)")
-    .option("--kb <id>", "Target a specific knowledge base")
+    .option("--kb <id>", "Target a specific knowledge base"))
     .action(async (fact, opts) => {
+    const kbId = await selectBrainId("brain.note", brainSelector(opts));
     const body = { text: fact, source: opts.source ?? "note" };
-    if (opts.kb)
-        body.knowledge_base_id = opts.kb;
+    if (kbId)
+        body.knowledge_base_id = kbId;
     // Document ingest is NOT approval-gated (unlike deletes/forget), so there is
     // no pending-approval path to handle here.
     const resp = await apiRequest("POST", "/v1/brain/documents", body);
@@ -336,7 +404,7 @@ brainCmd
     .action(async (id, opts) => {
     const provided = [opts.file, opts.text, opts.url].filter((v) => v !== undefined).length;
     if (provided !== 1) {
-        console.error(JSON.stringify({
+        console.log(JSON.stringify({
             success: false,
             action: "brain.replace_doc",
             error: { code: "missing_argument", message: "Provide exactly one of --file, --text, or --url" },
@@ -385,12 +453,13 @@ brainCmd
         related_commands: ["naive brain doc", "naive brain docs", "naive brain query"],
     });
 });
-brainCmd
+withBrainFlags(brainCmd
     .command("docs")
     .description("List ingested documents and their processing status")
-    .option("--kb <id>", "Filter by knowledge base")
+    .option("--kb <id>", "Filter by knowledge base"))
     .action(async (opts) => {
-    const qs = opts.kb ? `?knowledge_base_id=${encodeURIComponent(opts.kb)}` : "";
+    const kbId = await selectBrainId("brain.docs", brainSelector(opts));
+    const qs = kbId ? `?knowledge_base_id=${encodeURIComponent(kbId)}` : "";
     const resp = await apiRequest("GET", `/v1/brain/documents${qs}`);
     handleApiError("brain.docs", resp);
     const data = resp.data;
@@ -445,33 +514,181 @@ brainCmd
 });
 brainCmd
     .command("list")
-    .description("List the company's knowledge bases")
-    .action(async () => {
+    .description("Every brain the company has: which is the default, and which agents are connected")
+    .option("--no-agents", "Skip the roster read and report brains only")
+    .action(async (opts) => {
     const resp = await apiRequest("GET", "/v1/brain");
     handleApiError("brain.list", resp);
     const data = resp.data;
+    const brains = data.knowledge_bases ?? [];
+    // THE BINDINGS COLUMN. It is an enrichment of a DIFFERENT surface
+    // (the agent roster, behind a different primitive), so a failure to
+    // read it must never cost the caller the brain list. The reason rides the
+    // envelope; a bare empty column would read as "nothing is connected".
+    let bindings = {};
+    let unavailable;
+    let orphaned = [];
+    if (opts.agents === false) {
+        unavailable = "not read: --no-agents was passed";
+    }
+    else {
+        const roster = await tryListAgents();
+        if (!roster.ok) {
+            unavailable = roster.because;
+        }
+        else {
+            const known = new Set(brains.map((b) => b.id));
+            for (const a of roster.agents) {
+                const bound = boundBrainId(a);
+                if (!bound)
+                    continue;
+                if (!known.has(bound)) {
+                    // A binding that points at a deleted brain is a real state, and
+                    // silently dropping it would hide it forever: `brain rm` cannot
+                    // reach into the roster, so the key outlives the row.
+                    orphaned.push({ agent_id: a.id, agent_name: a.name, knowledge_base_id: bound });
+                    continue;
+                }
+                (bindings[bound] ??= []).push({ id: a.id, name: a.name });
+            }
+        }
+    }
+    const knowledge_bases = brains.map((b) => ({
+        ...b,
+        ...(unavailable ? {} : { agents: bindings[b.id] ?? [] }),
+    }));
+    const defaultBrain = brains.find((b) => b.is_default);
+    // Two brains may share a name — the schema has no unique index on
+    // (company_id, name) — and when they do, `--brain <that name>` refuses as
+    // ambiguous. Reported here because this is the command that already has the
+    // whole list in hand; `brain create` deliberately does not pre-flight for it.
+    const byName = new Map();
+    for (const b of brains) {
+        const key = (b.name ?? "").trim().toLowerCase();
+        byName.set(key, [...(byName.get(key) ?? []), b.id]);
+    }
+    const ambiguous = [...byName.entries()]
+        .filter(([, ids]) => ids.length > 1)
+        .map(([key, ids]) => ({ name: brains.find((b) => b.id === ids[0]).name, ids, normalized: key }));
     agentOutput({
         action: "brain.list",
-        result: resp.data,
+        result: {
+            knowledge_bases,
+            count: data.count ?? brains.length,
+            default_knowledge_base_id: defaultBrain?.id ?? null,
+            ...(unavailable ? { agents_unavailable_because: unavailable } : {}),
+            ...(orphaned.length > 0 ? { orphaned_bindings: orphaned } : {}),
+            ...(ambiguous.length > 0 ? { ambiguous_names: ambiguous } : {}),
+        },
         next_steps: [
-            { command: "naive brain add --file <path>", description: "Ingest a document" },
-            { command: 'naive brain query "..."', description: "Ask a question" },
-            { command: "naive brain create --name <name>", description: "Create another knowledge base" },
+            { command: "naive brain create <name>", description: "Create another knowledge base" },
+            { command: "naive brain connect <brain> --agent <agent>", description: "Connect an agent to one of them" },
+            { command: 'naive brain query "..." --brain <name>', description: "Ask a specific brain a question" },
         ],
-        hints: [`${data.count ?? 0} knowledge base(s).`],
-        related_commands: ["naive brain add", "naive brain query", "naive brain docs", "naive brain create"],
+        hints: [
+            `${data.count ?? brains.length} knowledge base(s).`,
+            // "No default" has TWO causes and they need different actions. A company
+            // with no brains has simply not needed one — the API mints it on the first
+            // call. A company WITH brains and none flagged has rows it can promote in
+            // one request, and letting the lazy mint happen instead adds a brain nobody
+            // asked for. (Deleting the default no longer produces this state: measured
+            // on a booted app, the delete promotes the oldest survivor in the same
+            // transaction. An earlier run, before that landed, left zero defaults.)
+            defaultBrain
+                ? `Default: "${defaultBrain.name}" (${defaultBrain.id}) — used whenever no --brain/--kb/--agent is passed.`
+                : brains.length === 0
+                    ? "No brain is flagged default yet; the API provisions one on the first call that needs it."
+                    : `No brain is flagged default, but ${brains.length} exist. The next call that names no brain will CREATE one called "Default Brain" and make it the default — run \`naive brain default <name|id>\` first to promote one of the brains above instead.`,
+            ...(unavailable ? [`Connected agents not shown: ${unavailable}.`] : []),
+            ...(orphaned.length > 0
+                ? [`${orphaned.length} agent(s) are connected to a knowledge base that no longer exists — see orphaned_bindings.`]
+                : []),
+            ...(ambiguous.length > 0
+                ? [
+                    `${ambiguous.length} name(s) are shared by more than one brain (${ambiguous
+                        .map((a) => `"${a.name}" ×${a.ids.length}`)
+                        .join(", ")}). --brain <name> refuses those and asks for an id.`,
+                ]
+                : []),
+        ],
+        related_commands: ["naive brain create", "naive brain connect", "naive brain add", "naive brain query"],
     });
 });
 brainCmd
-    .command("create")
+    .command("create [name]")
     .description("Create (and provision) a new knowledge base")
+    // `--name` SHIPPED FIRST and stays. The positional is the ergonomic form
+    // (`naive brain create "Support"`); passing both is refused rather than
+    // guessed at, and passing `--name` alone behaves exactly as it always did.
     .option("--name <name>", "Name for the knowledge base (1-120 chars)")
-    .option("--default", "Make this the company's default knowledge base")
-    .action(async (opts) => {
+    .option("--default", "Make this the company's default knowledge base (to promote one that already exists, use `naive brain default`)")
+    .action(async (nameArg, opts) => {
+    if (nameArg && opts.name && nameArg !== opts.name) {
+        agentError({
+            action: "brain.create",
+            error: {
+                code: "invalid_input",
+                message: `A brain gets one name. Got "${nameArg}" as an argument and "${opts.name}" as --name.`,
+            },
+            recovery_steps: [
+                { command: `naive brain create "${nameArg}"`, description: "Use the argument" },
+                { command: `naive brain create --name "${opts.name}"`, description: "Use the flag" },
+            ],
+        });
+        return;
+    }
+    const name = nameArg ?? opts.name;
+    // NO PRE-FLIGHT LOOKUP HERE, ON PURPOSE. A duplicate-name warning would be
+    // worth having — `brain_knowledge_bases` has no unique index on
+    // (company_id, name), so two brains may share one and `--brain <name>` then
+    // refuses as ambiguous — but detecting it costs a `GET /v1/brain` that
+    // `naive brain create --name X` has never made. The invariant test
+    // (__tests__/brain-multi.test.ts) compares the WHOLE request stream and
+    // catches exactly that. The same fact is reported by `naive brain list` as
+    // `ambiguous_names`, which already reads the list.
     const resp = await apiRequest("POST", "/v1/brain", {
-        ...(opts.name && { name: opts.name }),
+        ...(name && { name }),
         ...(opts.default && { is_default: true }),
     });
+    // 🔴 A 409 FROM THIS ROUTE DOES NOT MEAN NOTHING WAS CREATED, AND THE FIX IS
+    // `naive brain default`, NOT A RETRY.
+    //
+    // With `is_default: true` the route inserts and provisions the row FIRST and
+    // swaps the default AFTER. The swap now runs under a company advisory lock, so
+    // concurrent creates no longer lose the race — six concurrent creates with
+    // `is_default: true` all returned 201 when measured against a booted app over a
+    // real Postgres (scratchpad/default-probe.mts FACT 1, second run). What is left
+    // is the narrow case where the SWAP fails: the brain exists, and the server says
+    // so — `retryable: false`, `details.knowledge_base_id` naming it, and prose
+    // telling the caller to promote it with `PATCH /v1/brain/{id}`.
+    //
+    // Passing that through verbatim would leave a CLI user holding a raw HTTP call.
+    // So this branch keeps the server's code, message and details EXACTLY as sent
+    // and only turns the instruction into a command that can be run. Nothing else on
+    // this command is intercepted; `handleApiError` still handles every other status.
+    const created = resp.data;
+    const strandedId = created.error?.details?.knowledge_base_id;
+    if (resp.status === 409 && created.error?.code === "duplicate_record" && typeof strandedId === "string") {
+        agentError({
+            action: "brain.create",
+            error: {
+                code: "duplicate_record",
+                message: created.error.message ?? "The knowledge base was created but could not be made the default.",
+                ...(created.error.details ? { details: created.error.details } : {}),
+            },
+            recovery_steps: [
+                {
+                    command: `naive brain default ${strandedId}`,
+                    description: "THE BRAIN EXISTS. Only the default swap failed, so promote it — one request, no new brain.",
+                },
+                {
+                    command: "naive brain list",
+                    description: "Confirm it is there and see which brain currently holds the default.",
+                },
+            ],
+        });
+        return;
+    }
     handleApiError("brain.create", resp);
     const data = resp.data;
     agentOutput({
@@ -479,7 +696,13 @@ brainCmd
         result: resp.data,
         next_steps: [
             ...(data.id
-                ? [{ command: `naive brain add --file <path> --kb ${data.id}`, description: "Ingest a document into this knowledge base" }]
+                ? [
+                    // The ID, not the name: names are not unique, and a next step that
+                    // may be ambiguous the moment a second brain shares the name is
+                    // not a next step.
+                    { command: `naive brain add --file <path> --brain ${data.id}`, description: "Ingest a document into this knowledge base" },
+                    { command: `naive brain connect ${data.id} --agent <agent>`, description: "Connect an agent to it" },
+                ]
                 : []),
             { command: "naive brain list", description: "List all knowledge bases" },
         ],
@@ -487,12 +710,226 @@ brainCmd
             `Knowledge base '${data.name ?? "?"}' created (status: ${data.status ?? "provisioning"}).`,
             ...(data.is_default ? ["This is now the company's default knowledge base."] : []),
         ],
-        related_commands: ["naive brain list", "naive brain add", "naive brain rm"],
+        related_commands: ["naive brain list", "naive brain default", "naive brain connect", "naive brain add", "naive brain rm"],
+    });
+});
+/* ══════════════════════════════════════════════════════════════════════════
+ * CHOOSING THE DEFAULT — the operation that makes a wrong default recoverable
+ *
+ * Until `PATCH /v1/brain/:id` landed, `is_default` was settable at create and
+ * nowhere else, so an operator who ended up with the wrong default could only
+ * create ANOTHER brain to move it — and never re-point at one they already had.
+ * Measured then, against a booted app with a key that read `GET /v1/brain` 200:
+ * PATCH/PUT /v1/brain/{id}, POST /v1/brain/{id}/default, POST /v1/brain/default
+ * and PATCH /v1/brain all answered 404. Re-measured after the route landed: the
+ * PATCH answers 200 and the other four still 404.
+ *
+ * WHY A POSITIONAL AND NOT `--default` ON SOMETHING ELSE. This is one act on one
+ * brain, and the brain is the subject: `naive brain default "Support Brain"`.
+ * It takes the same `<name|id>` every other subcommand's `--brain` takes, through
+ * the same resolver, so a name that two brains share is refused with both ids
+ * rather than resolved to one of them.
+ *
+ * NO `--because`. The route takes exactly one body property (`is_default: true`)
+ * and the server writes its own audit event (`brain.kb.default_changed`, carrying
+ * the previous id); a reason this CLI invented would be dropped on the floor.
+ * ══════════════════════════════════════════════════════════════════════════ */
+brainCmd
+    .command("default <brain>")
+    .description("Make an existing brain the company default (by name or id)")
+    .action(async (ref) => {
+    const id = await resolveBrainId("brain.default", ref);
+    const resp = await apiRequest("PATCH", `/v1/brain/${id}`, { is_default: true });
+    handleApiError("brain.default", resp);
+    const data = resp.data;
+    agentOutput({
+        action: "brain.default",
+        result: resp.data,
+        next_steps: [
+            { command: "naive brain list", description: "Confirm which brain is now the default" },
+            { command: `naive brain query "..." --brain ${data.id ?? id}`, description: "Ask this brain directly" },
+        ],
+        hints: [
+            `"${data.name ?? ref}" (${data.id ?? id}) is now the company default — used whenever no --brain/--kb/--agent is passed.`,
+            // Both of these are the server's rules, not this CLI's, and both are
+            // states a caller can reach: promoting the current default is a no-op,
+            // and a brain still provisioning is refused rather than promoted half-built.
+            "Promoting the brain that is already the default is a no-op and writes no audit event.",
+            "Only an active brain can be promoted; a provisioning or errored one is refused with invalid_input.",
+        ],
+        related_commands: ["naive brain list", "naive brain create", "naive brain connect"],
+    });
+});
+/* ══════════════════════════════════════════════════════════════════════════
+ * CONNECTING A BRAIN TO AN AGENT
+ *
+ * WHAT THIS IS, EXACTLY — because the difference matters and nothing else in
+ * the product states it. MEASURED in this tree:
+ *
+ *   - NO TABLE binds an agent to a `brain_knowledge_bases` row. The
+ *     `knowledge_base_id` FK appears on documents, episodes, entities, claims
+ *     and ops rows — never on an agent, a profile or a tenant user. The binding
+ *     is a KEY IN `agents.metadata`, not a column.
+ *   - THREE ROUTES own it, all under the `brain` primitive gate:
+ *     `POST /v1/brain/connect`, `DELETE /v1/brain/connections/:agentId` and
+ *     `GET /v1/brain/connections` (packages/api/src/routes/brain.ts:1251-1277,
+ *     of 42 `brainRouter` routes).
+ *   - The one place the platform accepts "this work uses that brain" per RUN is
+ *     `POST /v1/runs`, whose body carries `brain_knowledge_base_id`
+ *     (contracts/brain-ops.ts:98) next to `agent_id`. The connect routes write
+ *     the key that surface already consumes, rather than minting a second name.
+ *
+ * 🔴 WHAT THIS COMMAND USED TO DO, AND WHY IT DOES NOT ANY MORE. It wrote the
+ * binding with `PATCH {@link ROSTER_PATH}/:id {metadata:{…}}` — the roster route,
+ * mounted on the ROSTER's own primitive gate. That is a SECOND DOOR to
+ * brain-owned data past the brain gate, which is precisely what
+ * `packages/api/src/routes/brain.ts:17-22` says must not exist. Measured live on
+ * one tenant, one agent, one field: `POST …/brain/connect` → 403
+ * `subprocessor_consent_required`; the roster PATCH of the same key on the same
+ * agent → 200. Three things were also silently skipped by the roster door — the
+ * `brain.agent.connected` `activity_events` row, the `brain_connected_at` stamp
+ * (so `GET /v1/brain/connections` reported a timestamp from an EARLIER binding
+ * to a DIFFERENT brain), and atomicity (it read-modify-wrote the whole metadata
+ * bag). All three come back with the gated route.
+ *
+ * AND HERE IS WHAT IT IS NOT: it is not an enforcement point. Nothing in the
+ * API reads this key to CONSTRAIN what an agent may recall — an agent key that
+ * can reach `/v1/brain` can still name any of its company's knowledge bases.
+ * The binding is a DEFAULT, honoured by every `naive brain … --agent <a>` call
+ * in this CLI. Saying otherwise would describe governance this build does not
+ * have. Governance of the brain is the AccountKit's `brain` primitive and the
+ * statute gates on `brain.kb.delete` / `brain.forget` / `brain.proposal.accept`,
+ * and this command changes neither.
+ * ════════════════════════════════════════════════════════════════════════ */
+brainCmd
+    .command("connect <brain>")
+    .description("Connect an agent to a brain — that agent's default knowledge base")
+    .requiredOption("--agent <id|name>", "The agent to connect (id, display name, or runtime profile name)")
+    .addHelpText("after", `
+Examples:
+  $ naive brain connect "Support Brain" --agent "Support Sam"
+  $ naive brain connect 00a21080-e247-4935-8efb-a6c1051c189b --agent c62c69e3-69aa-4136-b571-fded6ce5a28b
+
+Then, anywhere a brain is named:
+  $ naive brain attach "refund audit" --agent "Support Sam"
+  $ naive brain recall "refunds" --agent "Support Sam"
+
+The binding is a DEFAULT, not a fence: it decides which brain this CLI reads for
+that agent. It does not stop an agent key from naming another knowledge base —
+that is the AccountKit's job, and this command does not touch it.
+`)
+    .action(async (brainRef, opts) => {
+    const action = "brain.connect";
+    const kbId = await resolveBrainId(action, brainRef);
+    const brain = (await listBrains(action)).find((b) => b.id === kbId);
+    const agent = await resolveAgent(action, opts.agent);
+    const previous = boundBrainId(agent);
+    const { agent: updated, connection } = await setAgentBrain(action, agent, kbId);
+    agentOutput({
+        action,
+        result: {
+            agent: { id: agent.id, name: agent.name },
+            knowledge_base: { id: kbId, name: connection?.knowledge_base_name ?? brain?.name ?? null },
+            previous_knowledge_base_id: previous ?? null,
+            binding_key: BRAIN_BINDING_KEY,
+            // The route's own timestamp, not one this CLI invented. Reported because
+            // it is what `naive brain list` and `GET /v1/brain/connections` show, and
+            // because the roster PATCH this replaced left it stale or null.
+            connected_at: connection?.connected_at ?? null,
+            metadata: updated.metadata ?? null,
+        },
+        next_steps: bindingNextSteps(brain, agent.id),
+        hints: [
+            `${agent.name} → "${connection?.knowledge_base_name ?? brain?.name ?? kbId}".`,
+            ...(previous && previous !== kbId ? [`Replaced its previous binding (${previous}).`] : []),
+            ...(previous === kbId ? ["It was already connected to this brain; the binding was re-pointed and `connected_at` refreshed."] : []),
+            `Written by POST ${BRAIN_CONNECT_PATH}, which carries the brain primitive gate and records a \`brain.agent.connected\` ledger event.`,
+            `Stored on the agent as metadata.${BRAIN_BINDING_KEY} — the same field POST /v1/runs accepts to point a run's brain attach.`,
+            "This is the default this CLI uses for --agent. It is not a permission boundary.",
+        ],
+        related_commands: ["naive brain list", "naive brain disconnect", "naive brain attach"],
+    });
+});
+brainCmd
+    .command("disconnect [brain]")
+    .description("Disconnect an agent from its brain (the inverse of 'connect')")
+    .requiredOption("--agent <id|name>", "The agent to disconnect (id, display name, or runtime profile name)")
+    .addHelpText("after", `
+Examples:
+  $ naive brain disconnect --agent "Support Sam"
+  $ naive brain disconnect "Support Brain" --agent "Support Sam"   # refuses if it is bound elsewhere
+
+Naming the brain is optional and is an ASSERTION: if the agent is connected to a
+different one, the command refuses rather than clearing a binding you did not
+mean to clear. Afterwards the agent falls back to the company default brain.
+`)
+    .action(async (brainRef, opts) => {
+    const action = "brain.disconnect";
+    const agent = await resolveAgent(action, opts.agent);
+    const bound = boundBrainId(agent);
+    if (!bound) {
+        agentOutput({
+            action,
+            result: { agent: { id: agent.id, name: agent.name }, knowledge_base: null, changed: false },
+            next_steps: [{ command: `naive brain connect <brain> --agent ${agent.id}`, description: "Connect it to a brain" }],
+            hints: [`${agent.name} was not connected to a brain. Nothing to do.`],
+            related_commands: ["naive brain list", "naive brain connect"],
+        });
+        return;
+    }
+    if (brainRef) {
+        const asserted = await resolveBrainId(action, brainRef);
+        if (asserted !== bound) {
+            const brains = await listBrains(action);
+            const actual = brains.find((b) => b.id === bound);
+            agentError({
+                action,
+                error: {
+                    code: "invalid_input",
+                    message: `${agent.name} is connected to ${actual ? `"${actual.name}" (${bound})` : bound}, not to "${brainRef}". Nothing was changed.`,
+                    agent: { id: agent.id, name: agent.name },
+                    knowledge_base_id: bound,
+                },
+                recovery_steps: [
+                    { command: `naive brain disconnect --agent ${agent.id}`, description: "Disconnect it from whatever it is bound to" },
+                    { command: "naive brain list", description: "See every brain and what is bound to each" },
+                ],
+            });
+            return;
+        }
+    }
+    const brains = await listBrains(action);
+    const was = brains.find((b) => b.id === bound);
+    const { agent: updated } = await setAgentBrain(action, agent, null);
+    agentOutput({
+        action,
+        result: {
+            agent: { id: agent.id, name: agent.name },
+            disconnected_from: { id: bound, name: was?.name ?? null },
+            knowledge_base: null,
+            changed: true,
+            metadata: updated.metadata ?? null,
+        },
+        next_steps: [
+            { command: `naive brain connect <brain> --agent ${agent.id}`, description: "Connect it to a different brain" },
+            { command: "naive brain list", description: "See every brain and what is bound to each" },
+        ],
+        hints: [
+            `${agent.name} is no longer connected to "${was?.name ?? bound}".`,
+            "Its brain calls fall back to the company default, exactly as before it was connected.",
+            "The knowledge base itself is untouched — this removed a binding, not a brain. Use 'naive brain rm <id>' to delete one.",
+        ],
+        related_commands: ["naive brain connect", "naive brain list", "naive brain rm"],
     });
 });
 brainCmd
     .command("rm <id>")
     .description("Delete a knowledge base and all its documents (permanent)")
+    // STILL NO PRE-FLIGHT READ, for the reason `create` gives: a shipped
+    // invocation that made one request may not start making two. What changed is
+    // what the RESULT says. The route answers 204 with an empty body, and two of
+    // its consequences are invisible in that emptiness — both measured, both named
+    // here, and both reported by `naive brain list`, which is already the next step.
     .action(async (id) => {
     const resp = await apiRequest("DELETE", `/v1/brain/${id}`);
     handleApiError("brain.rm", resp);
@@ -501,9 +938,331 @@ brainCmd
     agentOutput({
         action: "brain.rm",
         result: resp.data ?? { deleted: true, id },
-        next_steps: [{ command: "naive brain list", description: "List remaining knowledge bases" }],
-        hints: ["Knowledge base and its documents deleted."],
-        related_commands: ["naive brain list", "naive brain create"],
+        next_steps: [
+            {
+                command: "naive brain list",
+                description: "List remaining knowledge bases — and check `default_knowledge_base_id` and `orphaned_bindings`, " +
+                    "which are the two things this delete can change without saying so.",
+            },
+        ],
+        hints: [
+            "Knowledge base and its documents deleted.",
+            // MEASURED on a booted app over a real Postgres (default-probe.mts FACT 3,
+            // second run): deleting the default answered 204 and the company still held
+            // exactly one default — the delete promotes the oldest surviving brain in
+            // the same transaction. An earlier run of the same probe, before that
+            // landed, left ZERO defaults and the next unscoped call minted a brain.
+            // The 204 body is empty and names no successor, so the only way to learn
+            // which brain it is, is to look.
+            "If this was the DEFAULT brain, another was promoted in the same transaction — the oldest surviving one. The 204 cannot say which: `naive brain list` shows it, and `naive brain default <brain>` picks a different one.",
+            // MEASURED this session: DELETE does not clear
+            // agents.metadata.brain_knowledge_base_id, so a connected agent keeps
+            // pointing at the dead id and its next scoped call 404s.
+            "Agents connected to it are NOT disconnected — they keep pointing at the deleted id and their scoped calls will 404. `naive brain list` reports them as `orphaned_bindings`; `naive brain disconnect --agent <id>` clears one.",
+        ],
+        related_commands: ["naive brain list", "naive brain create", "naive brain disconnect"],
+    });
+});
+/* ========================================================================== */
+/* The durable-runtime era additions (06 §1.7).                               */
+/*                                                                            */
+/* §1.7 specifies FOURTEEN new subcommands:                                   */
+/*   attach beliefs belief reaffirm lessons learn proposals writebacks         */
+/*   retention levels status metrics consolidate decisions                     */
+/*                                                                            */
+/* SIX are shipped here. MEASURED against packages/api/src/routes/brain.ts in  */
+/* this tree (37 handlers, enumerated), these six and only these six have a    */
+/* route to reach:                                                            */
+/*                                                                            */
+/*   attach       POST   /v1/brain/attach          (:454)                     */
+/*   consolidate  POST   /v1/brain/consolidate     (:465)                     */
+/*   proposals    GET    /v1/brain/proposals       (:637, :649)               */
+/*   writebacks   GET    /v1/brain/writebacks      (:617, :629)               */
+/*   status       GET    /v1/brain/status          (:350)                     */
+/*   metrics      GET    /v1/brain/metrics         (:750)                     */
+/*                                                                            */
+/* The other EIGHT — beliefs, belief, reaffirm, lessons, learn, retention,     */
+/* levels, decisions — have no handler on `brainRouter` and no table behind    */
+/* them. They are deliberately NOT shipped. `naive brain` is a working group   */
+/* with sixteen working subcommands; adding eight that can only ever 404       */
+/* degrades a live surface, and a subcommand whose only possible outcome is an */
+/* error is not a command, it is a promise. They land with their routes.       */
+/*                                                                            */
+/* `proposals [id]` is one name at two scopes rather than a `proposals` /      */
+/* `proposal` pair — the same shape the group already uses for a list and its  */
+/* member elsewhere, and one fewer name to keep in step.                      */
+/* ========================================================================== */
+/** Collect a repeatable option into an array (commander's documented idiom). */
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+withBrainFlags(brainCmd
+    .command("attach [goal]")
+    .description("Attach a read capsule for a goal — what the brain already knows, before the work starts")
+    .option("--goal <goal>", "The goal (alternative to the positional argument)")
+    .option("--entity <name>", "An entity the work touches (repeatable, max 20)", collect)
+    .option("--artifact <ref>", "An artifact the work touches (repeatable, max 50)", collect)
+    .option("--since <iso8601>", "Only what changed since this watermark")
+    .option("--kb <id>", "Attach from a specific knowledge base"))
+    .action(async (goalArg, opts) => {
+    const goal = goalArg ?? opts.goal;
+    if (!goal) {
+        agentError({
+            action: "brain.attach",
+            error: { code: "invalid_input", message: "A goal is required — pass it positionally or with --goal" },
+            recovery_steps: [
+                { command: 'naive brain attach "refund audit"', description: "Positional form" },
+                { command: 'naive brain attach --goal "refund audit"', description: "Flag form (same call)" },
+            ],
+        });
+        return;
+    }
+    // `--agent <a>` here is the payoff of `brain connect`: the run loop's read
+    // half runs against the brain that agent is bound to, without the caller
+    // having to carry the id.
+    const kbId = await selectBrainId("brain.attach", brainSelector(opts));
+    const resp = await apiRequest("POST", "/v1/brain/attach", {
+        goal,
+        ...(opts.entity && { entities: opts.entity }),
+        ...(opts.artifact && { artifacts_touched: opts.artifact }),
+        ...(opts.since && { since_watermark: opts.since }),
+        ...(kbId && { knowledge_base_id: kbId }),
+    });
+    handleApiError("brain.attach", resp);
+    agentOutput({
+        action: "brain.attach",
+        result: resp.data,
+        next_steps: [
+            { command: 'naive brain consolidate --objective "..."', description: "Debrief at the end of the run" },
+            { command: "naive brain proposals", description: "See what the run proposed writing back" },
+        ],
+        hints: ["A capsule is what the brain already knows about this goal. Read it before working, not after."],
+        related_commands: ["naive brain consolidate", "naive brain recall", "naive brain proposals"],
+    });
+});
+withBrainFlags(brainCmd
+    .command("consolidate")
+    .description("Run-end debrief — the write half. What was learned, decided and left open")
+    .option("--objective <text>", "What the run was for")
+    .option("--learned <s|p|o>", "A learned fact as subject|predicate|object (repeatable, max 100)", collect)
+    .option("--decided <title>", "A decision the run made (repeatable, max 50)", collect)
+    .option("--open <question>", "A question the run left open (repeatable, max 50)", collect)
+    .option("--kb <id>", "Consolidate into a specific knowledge base"))
+    .action(async (opts) => {
+    // `--learned` is pipe-separated because the API's shape is a TRIPLE, and a
+    // free-text sentence would have to be parsed into one by something. Refusing
+    // a malformed triple here is better than posting a fact with an empty object.
+    const learned = (opts.learned ?? []).map((raw) => {
+        const [subject, predicate, object] = raw.split("|");
+        if (!subject || !predicate || !object) {
+            agentError({
+                action: "brain.consolidate",
+                error: {
+                    code: "invalid_input",
+                    message: `--learned expects subject|predicate|object, got: ${raw}`,
+                },
+                recovery_steps: [
+                    { command: 'naive brain consolidate --learned "acme|refund window|30 days"', description: "Use the triple form" },
+                ],
+            });
+        }
+        return { subject: subject, predicate: predicate, object: object };
+    });
+    const kbId = await selectBrainId("brain.consolidate", brainSelector(opts));
+    const resp = await apiRequest("POST", "/v1/brain/consolidate", {
+        ...(opts.objective && { objective: opts.objective }),
+        ...(learned.length > 0 && { learned }),
+        ...(opts.decided && { decided: opts.decided.map((title) => ({ title })) }),
+        ...(opts.open && { open: opts.open }),
+        ...(kbId && { knowledge_base_id: kbId }),
+    });
+    handleApiError("brain.consolidate", resp);
+    const data = resp.data;
+    agentOutput({
+        action: "brain.consolidate",
+        result: resp.data,
+        next_steps: [
+            { command: "naive brain proposals --status pending", description: "Review what this debrief proposed" },
+            { command: "naive brain writebacks", description: "See the envelope this created" },
+        ],
+        hints: [
+            `Accepted (202). Gateway mode: ${data.mode ?? "unknown"}; ${data.proposals?.length ?? 0} proposal(s).`,
+            "A debrief PROPOSES; it does not commit. Nothing here is a belief until a proposal is accepted.",
+        ],
+        related_commands: ["naive brain proposals", "naive brain writebacks", "naive brain attach"],
+    });
+});
+brainCmd
+    .command("proposals [id]")
+    .description("The proposal queue — list it, read one, or decide one")
+    .option("--status <status>", "Filter by proposal status")
+    .option("--type <objectType>", "Filter by proposed object type")
+    .option("--run <id>", "Filter to one run")
+    .option("--limit <n>", "Maximum proposals to return (1-200)", (v) => Number.parseInt(v, 10))
+    .option("--events", "With <id>: show the proposal's event history instead of the proposal")
+    .option("--accept", "With <id>: accept it (may require human approval)")
+    .option("--reject", "With <id>: reject it")
+    .option("--merge <targetId>", "With <id>: merge it into an existing object")
+    .option("--quarantine", "With <id>: quarantine it")
+    .option("--because <why>", "Why you decided as you did. Recorded on the proposal")
+    .action(async (id, opts) => {
+    const decisions = [
+        opts.accept && "accept",
+        opts.reject && "reject",
+        opts.merge && "merge",
+        opts.quarantine && "quarantine",
+    ].filter(Boolean);
+    if (decisions.length > 0 && !id) {
+        agentError({
+            action: "brain.proposals",
+            error: { code: "invalid_input", message: `--${decisions[0]} needs a proposal id: naive brain proposals <id> --${decisions[0]}` },
+            recovery_steps: [{ command: "naive brain proposals --status pending", description: "List proposals awaiting a decision" }],
+        });
+        return;
+    }
+    if (decisions.length > 1) {
+        agentError({
+            action: "brain.proposals",
+            error: { code: "invalid_input", message: `A proposal gets one decision, not ${decisions.length}: ${decisions.join(", ")}` },
+            recovery_steps: [{ command: "naive brain proposals <id>", description: "Read the proposal before deciding" }],
+        });
+        return;
+    }
+    if (decisions.length === 1) {
+        const verb = decisions[0];
+        const resp = await apiRequest("POST", `/v1/brain/proposals/${encodeURIComponent(id)}/${verb}`, {
+            ...(opts.because && { reason: opts.because }),
+            ...(opts.merge && { merge_target_id: opts.merge }),
+        });
+        handleApiError(`brain.proposals.${verb}`, resp);
+        if (handlePendingApproval(`brain.proposals.${verb}`, resp))
+            return;
+        agentOutput({
+            action: `brain.proposals.${verb}`,
+            result: resp.data,
+            next_steps: [{ command: "naive brain proposals --status pending", description: "Review the rest of the queue" }],
+            hints: [
+                `Proposal ${id} ${verb}ed.`,
+                ...(verb === "accept" ? ["Accepting is a governed action — it may return pending_approval instead of promoting."] : []),
+            ],
+            related_commands: ["naive brain proposals", "naive brain writebacks"],
+        });
+        return;
+    }
+    if (id) {
+        const suffix = opts.events ? "/events" : "";
+        const resp = await apiRequest("GET", `/v1/brain/proposals/${encodeURIComponent(id)}${suffix}`);
+        handleApiError("brain.proposals", resp);
+        agentOutput({
+            action: "brain.proposals",
+            result: resp.data,
+            next_steps: [
+                { command: `naive brain proposals ${id} --accept --because "..."`, description: "Accept it" },
+                { command: `naive brain proposals ${id} --reject --because "..."`, description: "Reject it" },
+                { command: `naive brain proposals ${id} --events`, description: "See its history" },
+            ],
+            related_commands: ["naive brain proposals", "naive brain writebacks"],
+        });
+        return;
+    }
+    const params = new URLSearchParams();
+    if (opts.status)
+        params.set("status", opts.status);
+    if (opts.type)
+        params.set("object_type", opts.type);
+    if (opts.run)
+        params.set("run_id", opts.run);
+    if (opts.limit !== undefined)
+        params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    const resp = await apiRequest("GET", `/v1/brain/proposals${qs ? `?${qs}` : ""}`);
+    handleApiError("brain.proposals", resp);
+    const data = resp.data;
+    agentOutput({
+        action: "brain.proposals",
+        result: resp.data,
+        next_steps: [
+            { command: "naive brain proposals <id>", description: "Read one proposal" },
+            { command: 'naive brain proposals <id> --accept --because "..."', description: "Accept one" },
+        ],
+        hints: [`${data.count ?? 0} proposal(s).`],
+        related_commands: ["naive brain writebacks", "naive brain consolidate"],
+    });
+});
+brainCmd
+    .command("writebacks [id]")
+    .description("Writeback envelopes — what a run asked the brain to record")
+    .option("--run <id>", "Filter to one run")
+    .option("--source <source>", "Filter by source")
+    .option("--status <status>", "Filter by envelope status")
+    .option("--limit <n>", "Maximum envelopes to return (1-200)", (v) => Number.parseInt(v, 10))
+    .action(async (id, opts) => {
+    if (id) {
+        const resp = await apiRequest("GET", `/v1/brain/writebacks/${encodeURIComponent(id)}`);
+        handleApiError("brain.writebacks", resp);
+        agentOutput({
+            action: "brain.writebacks",
+            result: resp.data,
+            next_steps: [{ command: "naive brain proposals --status pending", description: "Decide the proposals it raised" }],
+            related_commands: ["naive brain proposals", "naive brain consolidate"],
+        });
+        return;
+    }
+    const params = new URLSearchParams();
+    if (opts.run)
+        params.set("run_id", opts.run);
+    if (opts.source)
+        params.set("source", opts.source);
+    if (opts.status)
+        params.set("status", opts.status);
+    if (opts.limit !== undefined)
+        params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    const resp = await apiRequest("GET", `/v1/brain/writebacks${qs ? `?${qs}` : ""}`);
+    handleApiError("brain.writebacks", resp);
+    const data = resp.data;
+    agentOutput({
+        action: "brain.writebacks",
+        result: resp.data,
+        next_steps: [{ command: "naive brain writebacks <id>", description: "Read one envelope and its proposals" }],
+        hints: [`${data.count ?? 0} envelope(s).`],
+        related_commands: ["naive brain proposals", "naive brain consolidate"],
+    });
+});
+brainCmd
+    .command("status")
+    .description("Operator view of the brain runtime for this company")
+    .action(async () => {
+    const resp = await apiRequest("GET", "/v1/brain/status");
+    handleApiError("brain.status", resp);
+    agentOutput({
+        action: "brain.status",
+        result: resp.data,
+        next_steps: [
+            { command: "naive brain metrics", description: "Process-global nervous-system counters" },
+            { command: "naive brain list", description: "The company's knowledge bases" },
+        ],
+        related_commands: ["naive brain metrics", "naive brain list", "naive brain docs"],
+    });
+});
+brainCmd
+    .command("metrics")
+    .description("Nervous-system counters. NOT company-scoped — see the hint")
+    .action(async () => {
+    const resp = await apiRequest("GET", "/v1/brain/metrics");
+    handleApiError("brain.metrics", resp);
+    agentOutput({
+        action: "brain.metrics",
+        result: resp.data,
+        next_steps: [{ command: "naive brain status", description: "The company-scoped view" }],
+        hints: [
+            // MEASURED: routes/brain.ts:750 calls getCompanyId(req) as an AUTH GATE ONLY and
+            // then returns snapshotBrainMetrics(), which takes no company and reads
+            // process-wide counters (platform/brain/src/brain-metrics.ts:73). Saying so is
+            // the difference between a number an operator can act on and one they cannot.
+            "These counters are PROCESS-GLOBAL, not company-scoped: they aggregate every tenant served by the API process that answered. Use `naive brain status` for this company.",
+        ],
+        related_commands: ["naive brain status"],
     });
 });
 //# sourceMappingURL=brain.js.map