@usenaive-sdk/cli 0.15.1 → 1.0.1

package/dist/commands/brain.js

@@ -1,1300 +0,0 @@
-import { Command } from "commander";
-import { readFileSync } from "node:fs";
-import { basename, extname } from "node:path";
-import { apiRequest, handleApiError, handlePendingApproval } from "../client.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",
-    ".txt": "text/plain",
-    ".md": "text/markdown",
-    ".csv": "text/csv",
-    ".json": "application/json",
-    ".html": "text/html",
-    ".htm": "text/html",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-};
-export const brainCmd = new Command("brain")
-    .description("Naive Brain — centralized knowledge base + RAG. Ingest docs, then ask grounded questions")
-    .addHelpText("after", `
-Subcommands:
-  naive brain query <question>   Ask the knowledge base (grounded answer + citations)
-  naive brain recall <query>     Recall structured semantic memory before work
-  naive brain remember <fact>    Write a durable semantic memory episode after work
-  naive brain think <query>      Synthesize from memory + docs with gap notes
-  naive brain graph              Explore the entity/relation knowledge graph
-  naive brain timeline           View memory events/facts in chronological order
-  naive brain forget <scope> <ref>  Tombstone/forget a semantic memory scope
-  naive brain add --file <path>  Ingest a file into the knowledge base
-  naive brain add --text "..."   Ingest raw text
-  naive brain add --url <url>    Ingest a web page
-  naive brain note <fact>        Ingest a short fact as a document (see note vs remember below)
-  naive brain replace-doc <id>   Replace/refresh a document in place
-  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               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
-  extracted and recallable via 'recall'/'think'/'graph'/'timeline').
-  'note' ingests the text as a DOCUMENT into the knowledge base (chunked +
-  embedded, answerable via 'query'). Use 'remember' for durable facts and
-  'note'/'add' for source material.
-
-Workflow:
-  1. naive brain add --file ./handbook.pdf     → ingest a document
-  2. naive brain add --text "Our refund policy is 30 days"
-  3. naive brain docs                          → confirm processing is 'ready'
-  4. naive brain query "What is our refund policy?"
-
-Naive Brain is your company's central, shared knowledge system. Both your own
-agents and Naive agents can read from it via the CLI, SDK, or MCP. Use it for
-company-specific knowledge (docs, policies, decisions) — for the open web use
-'naive search' instead.
-
-Examples:
-  $ naive brain add --file ./product-spec.md
-  $ naive brain query "What are the P0 requirements in the spec?"
-  $ naive brain query "And the P1s?" --session <session_id from the previous answer>
-  $ naive brain docs
-`);
-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)))
-    .action(async (query, opts) => {
-    const kbId = await selectBrainId("brain.recall", brainSelector(opts));
-    const resp = await apiRequest("POST", "/v1/brain/recall", {
-        query,
-        ...(kbId && { knowledge_base_id: kbId }),
-        ...(opts.entity && { entity: opts.entity }),
-        ...(opts.limit && { limit: opts.limit }),
-    });
-    handleApiError("brain.recall", resp);
-    agentOutput({
-        action: "brain.recall",
-        result: resp.data,
-        next_steps: [
-            { command: `naive brain think "${query}"`, description: "Synthesize memory with grounded document context" },
-            { command: 'naive brain remember "..."', description: "Record a durable fact after work" },
-        ],
-        hints: ["Structured memory recalled from the company brain."],
-        related_commands: ["naive brain think", "naive brain remember", "naive brain query"],
-    });
-});
-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"))
-    .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 }),
-        ...(kbId && { knowledge_base_id: kbId }),
-    });
-    handleApiError("brain.remember", resp);
-    agentOutput({
-        action: "brain.remember",
-        result: resp.data,
-        next_steps: [{ command: `naive brain recall "${content.slice(0, 80)}"`, description: "Verify the memory is recallable" }],
-        hints: ["Durable semantic memory recorded."],
-        related_commands: ["naive brain recall", "naive brain think"],
-    });
-});
-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)))
-    .action(async (query, opts) => {
-    const kbId = await selectBrainId("brain.think", brainSelector(opts));
-    const resp = await apiRequest("POST", "/v1/brain/think", {
-        query,
-        ...(kbId && { knowledge_base_id: kbId }),
-        ...(opts.session && { session_id: opts.session }),
-        ...(opts.limit && { limit: opts.limit }),
-    });
-    handleApiError("brain.think", resp);
-    agentOutput({
-        action: "brain.think",
-        result: resp.data,
-        next_steps: [{ command: 'naive brain remember "..."', description: "Record any durable outcome from this work" }],
-        hints: ["Answer synthesized from semantic memory and grounded documents."],
-        related_commands: ["naive brain recall", "naive brain query", "naive brain remember"],
-    });
-});
-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)))
-    .action(async (opts) => {
-    const kbId = await selectBrainId("brain.graph", brainSelector(opts));
-    const resp = await apiRequest("POST", "/v1/brain/graph", {
-        ...(kbId && { knowledge_base_id: kbId }),
-        ...(opts.entity && { entity: opts.entity }),
-        ...(opts.limit && { limit: opts.limit }),
-    });
-    handleApiError("brain.graph", resp);
-    agentOutput({
-        action: "brain.graph",
-        result: resp.data,
-        next_steps: [
-            { command: "naive brain timeline", description: "See how these facts evolved over time" },
-            { command: 'naive brain recall "..."', description: "Recall structured memory for an entity" },
-        ],
-        hints: ["Entity/relation graph derived from the company brain's semantic memory."],
-        related_commands: ["naive brain timeline", "naive brain recall", "naive brain think"],
-    });
-});
-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)))
-    .action(async (opts) => {
-    const kbId = await selectBrainId("brain.timeline", brainSelector(opts));
-    const resp = await apiRequest("POST", "/v1/brain/timeline", {
-        ...(kbId && { knowledge_base_id: kbId }),
-        ...(opts.entity && { entity: opts.entity }),
-        ...(opts.limit && { limit: opts.limit }),
-    });
-    handleApiError("brain.timeline", resp);
-    agentOutput({
-        action: "brain.timeline",
-        result: resp.data,
-        next_steps: [
-            { command: "naive brain graph", description: "Explore the entity/relation graph" },
-            { command: 'naive brain think "..."', description: "Synthesize memory + docs with gap notes" },
-        ],
-        hints: ["Chronological memory events/facts from the company brain."],
-        related_commands: ["naive brain graph", "naive brain recall", "naive brain think"],
-    });
-});
-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"))
-    .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,
-        ...(kbId && { knowledge_base_id: kbId }),
-        ...(opts.reason && { reason: opts.reason }),
-    });
-    handleApiError("brain.forget", resp);
-    if (handlePendingApproval("brain.forget", resp))
-        return;
-    agentOutput({
-        action: "brain.forget",
-        result: resp.data,
-        next_steps: [{ command: "naive brain recall <query>", description: "Confirm forgotten memory no longer appears" }],
-        hints: ["Semantic memory tombstone written; derived projections will purge the scope."],
-        related_commands: ["naive brain recall", "naive brain docs"],
-    });
-});
-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)"))
-    .action(async (question, opts) => {
-    const kbId = await selectBrainId("brain.query", brainSelector(opts));
-    const resp = await apiRequest("POST", "/v1/brain/query", {
-        question,
-        ...(kbId && { knowledge_base_id: kbId }),
-        ...(opts.session && { session_id: opts.session }),
-    });
-    handleApiError("brain.query", resp);
-    const data = resp.data;
-    agentOutput({
-        action: "brain.query",
-        result: resp.data,
-        next_steps: [
-            ...(data.session_id
-                ? [{ command: `naive brain query "<follow-up>" --session ${data.session_id}`, description: "Ask a follow-up in the same conversation" }]
-                : []),
-            { command: "naive brain add --file <path>", description: "Add more knowledge to improve answers" },
-            { command: "naive brain docs", description: "See what's in the knowledge base" },
-        ],
-        hints: [
-            data.answer ? "Answer grounded in the company knowledge base." : "No answer returned — the brain may be empty.",
-            `${data.citations?.length ?? 0} citation(s).`,
-        ],
-        related_commands: ["naive brain add", "naive brain docs"],
-    });
-});
-withBrainFlags(brainCmd
-    .command("add")
-    .description("Ingest a document into the knowledge base (--file, --text, or --url)")
-    .option("--file <path>", "Ingest a local file")
-    .option("--text <text>", "Ingest raw text")
-    .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"))
-    .action(async (opts) => {
-    const provided = [opts.file, opts.text, opts.url].filter((v) => v !== undefined).length;
-    if (provided !== 1) {
-        console.log(JSON.stringify({
-            success: false,
-            action: "brain.add",
-            error: { code: "missing_argument", message: "Provide exactly one of --file, --text, or --url" },
-            recovery_steps: [
-                { command: "naive brain add --file ./doc.pdf", description: "Ingest a file" },
-                { command: 'naive brain add --text "..."', description: "Ingest raw text" },
-                { command: "naive brain add --url https://example.com", description: "Ingest a URL" },
-            ],
-        }, null, 2));
-        process.exit(1);
-    }
-    const kbId = await selectBrainId("brain.add", brainSelector(opts));
-    const body = {};
-    if (kbId)
-        body.knowledge_base_id = kbId;
-    if (opts.source)
-        body.source = opts.source;
-    if (opts.file) {
-        const buf = readFileSync(opts.file);
-        body.file_base64 = buf.toString("base64");
-        body.filename = opts.name ?? basename(opts.file);
-        const contentType = CONTENT_TYPES[extname(opts.file).toLowerCase()];
-        if (contentType)
-            body.content_type = contentType;
-    }
-    else if (opts.url) {
-        body.url = opts.url;
-        if (opts.name)
-            body.filename = opts.name;
-    }
-    else {
-        body.text = opts.text;
-        if (opts.name)
-            body.filename = opts.name;
-    }
-    const resp = await apiRequest("POST", "/v1/brain/documents", body);
-    handleApiError("brain.add", resp);
-    const data = resp.data;
-    agentOutput({
-        action: "brain.add",
-        result: resp.data,
-        next_steps: [
-            ...(data.id ? [{ command: `naive brain doc ${data.id}`, description: "Check this document's processing status" }] : []),
-            { command: "naive brain docs", description: "List all documents + statuses" },
-            { command: 'naive brain query "..."', description: "Ask a question once processing is 'ready'" },
-        ],
-        hints: [
-            `Document '${data.filename ?? "?"}' ingested (status: ${data.status ?? "processing"}).`,
-            "Large documents may take a moment to finish processing before they're queryable.",
-        ],
-        related_commands: ["naive brain query", "naive brain docs", "naive brain doc"],
-    });
-});
-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"))
-    .action(async (fact, opts) => {
-    const kbId = await selectBrainId("brain.note", brainSelector(opts));
-    const body = { text: fact, source: opts.source ?? "note" };
-    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);
-    handleApiError("brain.note", resp);
-    agentOutput({
-        action: "brain.note",
-        result: resp.data,
-        next_steps: [
-            { command: 'naive brain query "..."', description: "Ask the company brain a question" },
-            { command: 'naive brain remember "..."', description: "Record a durable semantic memory instead" },
-        ],
-        hints: ["Fact ingested as a document in the company brain — queryable via 'naive brain query'."],
-        related_commands: ["naive brain query", "naive brain remember", "naive brain docs"],
-    });
-});
-brainCmd
-    .command("replace-doc <id>")
-    .description("Replace/refresh an existing document in place (--file, --text, or --url)")
-    .option("--file <path>", "Replace with a local file")
-    .option("--text <text>", "Replace with raw text")
-    .option("--url <url>", "Replace with the content at a URL")
-    .option("--name <filename>", "Override the stored filename/label")
-    .action(async (id, opts) => {
-    const provided = [opts.file, opts.text, opts.url].filter((v) => v !== undefined).length;
-    if (provided !== 1) {
-        console.log(JSON.stringify({
-            success: false,
-            action: "brain.replace_doc",
-            error: { code: "missing_argument", message: "Provide exactly one of --file, --text, or --url" },
-            recovery_steps: [
-                { command: `naive brain replace-doc ${id} --file ./doc.pdf`, description: "Replace with a file" },
-                { command: `naive brain replace-doc ${id} --text "..."`, description: "Replace with raw text" },
-                { command: `naive brain replace-doc ${id} --url https://example.com`, description: "Replace with a URL" },
-            ],
-        }, null, 2));
-        process.exit(1);
-    }
-    const body = {};
-    if (opts.file) {
-        const buf = readFileSync(opts.file);
-        body.file_base64 = buf.toString("base64");
-        body.filename = opts.name ?? basename(opts.file);
-        const contentType = CONTENT_TYPES[extname(opts.file).toLowerCase()];
-        if (contentType)
-            body.content_type = contentType;
-    }
-    else if (opts.url) {
-        body.url = opts.url;
-        if (opts.name)
-            body.filename = opts.name;
-    }
-    else {
-        body.text = opts.text;
-        if (opts.name)
-            body.filename = opts.name;
-    }
-    const resp = await apiRequest("PUT", `/v1/brain/documents/${id}`, body);
-    handleApiError("brain.replace_doc", resp);
-    const data = resp.data;
-    agentOutput({
-        action: "brain.replace_doc",
-        result: resp.data,
-        next_steps: [
-            { command: `naive brain doc ${data.id ?? id}`, description: "Check this document's processing status" },
-            { command: "naive brain docs", description: "List all documents + statuses" },
-            { command: 'naive brain query "..."', description: "Ask a question once processing is 'ready'" },
-        ],
-        hints: [
-            `Document '${data.filename ?? "?"}' replaced in place (status: ${data.status ?? "processing"}).`,
-            "The document keeps the same Naive id while the provider file is swapped.",
-        ],
-        related_commands: ["naive brain doc", "naive brain docs", "naive brain query"],
-    });
-});
-withBrainFlags(brainCmd
-    .command("docs")
-    .description("List ingested documents and their processing status")
-    .option("--kb <id>", "Filter by knowledge base"))
-    .action(async (opts) => {
-    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;
-    agentOutput({
-        action: "brain.docs",
-        result: resp.data,
-        next_steps: [
-            ...(data.documents?.length
-                ? [{ command: `naive brain doc ${data.documents[0].id}`, description: "Get a document's refreshed status" }]
-                : []),
-            { command: "naive brain add --file <path>", description: "Ingest another document" },
-            { command: 'naive brain query "..."', description: "Ask the knowledge base a question" },
-        ],
-        hints: [`${data.count ?? 0} document(s) in the knowledge base.`],
-        related_commands: ["naive brain add", "naive brain query", "naive brain doc"],
-    });
-});
-brainCmd
-    .command("doc <id>")
-    .description("Get a single ingested document (refreshes processing status)")
-    .action(async (id) => {
-    const resp = await apiRequest("GET", `/v1/brain/documents/${id}`);
-    handleApiError("brain.doc", resp);
-    const data = resp.data;
-    agentOutput({
-        action: "brain.doc",
-        result: resp.data,
-        next_steps: data.status === "processing"
-            ? [{ command: `naive brain doc ${id}`, description: "Check again — still processing" }]
-            : [{ command: 'naive brain query "..."', description: "Ask the knowledge base a question" }],
-        hints: [
-            `Document '${data.filename ?? "?"}' is ${data.status ?? "unknown"}.`,
-        ],
-        related_commands: ["naive brain docs", "naive brain rm-doc", "naive brain query"],
-    });
-});
-brainCmd
-    .command("rm-doc <id>")
-    .description("Delete an ingested document from the knowledge base (permanent)")
-    .action(async (id) => {
-    const resp = await apiRequest("DELETE", `/v1/brain/documents/${id}`);
-    handleApiError("brain.rm_doc", resp);
-    if (handlePendingApproval("brain.rm_doc", resp))
-        return;
-    agentOutput({
-        action: "brain.rm_doc",
-        result: resp.data ?? { deleted: true, id },
-        next_steps: [{ command: "naive brain docs", description: "List remaining documents" }],
-        hints: ["Document deleted from the knowledge base."],
-        related_commands: ["naive brain docs", "naive brain add"],
-    });
-});
-brainCmd
-    .command("list")
-    .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: {
-            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 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 ?? 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 [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 (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", {
-        ...(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({
-        action: "brain.create",
-        result: resp.data,
-        next_steps: [
-            ...(data.id
-                ? [
-                    // 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" },
-        ],
-        hints: [
-            `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 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);
-    if (handlePendingApproval("brain.rm", resp))
-        return;
-    agentOutput({
-        action: "brain.rm",
-        result: resp.data ?? { deleted: true, id },
-        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 (44 `brainRouter.<verb>(` handlers), these six and only these six */
-/* have a route to reach:                                                     */
-/*                                                                            */
-/*   attach       POST   /v1/brain/attach                                     */
-/*   consolidate  POST   /v1/brain/consolidate                                */
-/*   proposals    GET    /v1/brain/proposals   (+ /proposals/:id)             */
-/*   writebacks   GET    /v1/brain/writebacks  (+ /writebacks/:id)            */
-/*   status       GET    /v1/brain/status                                     */
-/*   metrics      GET    /v1/brain/metrics                                    */
-/*                                                                            */
-/* The per-route LINE NUMBERS that used to be on these six are deliberately    */
-/* gone, and the handler count is corrected from 37 to 44. Both had drifted    */
-/* far enough to mislead — `status` was cited at :350 against a real :428 —    */
-/* and re-measuring them proved the point rather than fixing it: the numbers   */
-/* moved another +142 within the same change, because an edit anywhere above   */
-/* a handler renumbers every handler below it. A citation that is wrong more   */
-/* often than it is right stops being evidence and starts being noise.         */
-/*                                                                            */
-/* What this block actually asserts is a SET — "exactly these six of the       */
-/* fourteen have a mount" — and a METHOD+PATH is a stable, greppable key for   */
-/* that claim where a line number is not. The count stays because it is the    */
-/* one number that is cheap to re-check and that changes only when a route is  */
-/* genuinely added or removed, which is the event this block cares about.      */
-/*                                                                            */
-/* 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" },
-        ],
-        // This command is a pure passthrough of the route body, so every field the
-        // API adds shows up here for free — but the REMEDIATION does not, and a
-        // `configured: false` with no next move is where an operator stalls. These
-        // hints name what each provider resolves from, which is the one thing the
-        // payload cannot say for a provider that resolved to nothing.
-        //
-        // Two rungs each, not one: the resolvers accept EITHER the explicit override
-        // OR the hosted key already present on the API
-        // (platform/brain/src/providers/embedder.ts:133 `resolveEmbedderTarget`,
-        // answerer.ts:240 `resolveAnswererTarget`). Naming only BRAIN_EMBED_BASE —
-        // as every doc and error string did until this change — sent operators to
-        // provision an embedding endpoint they did not need.
-        hints: [
-            "Read `services.<leg>.source` first: it names WHICH key answered — `explicit` (a BRAIN_*_BASE override), `openai-default`/`openrouter-default` (the hosted key), or `mock`. A leg carrying `optional: true` is one that `ready` ignores.",
-            "Embeddings (ingest + document recall) resolve from BRAIN_EMBED_BASE if set, else OPENAI_API_KEY, else nothing — and with nothing, ingest refuses at the door rather than writing a broken document.",
-            "Answer synthesis resolves from BRAIN_ANSWER_BASE if set, else OPENROUTER_API_KEY, else nothing. Unlike the embedder its absence is NOT an error: `brain query` falls back to returning grounded chunks.",
-            "A reranker is opt-in only (BRAIN_RERANK_BASE, no hosted fallback) and the GBrain semantic engine needs BOTH BRAIN_SEMANTIC_ENGINE=gbrain AND GBRAIN_BASE_URL. Neither absence is a failure: retrieval falls back to RRF order, reads fall back to the Postgres spine. `ready` never counts the reranker at all, and counts GBrain health only when BOTH gbrain terms are set — so `ready: true` with both reported unconfigured is the correct reading, not a false pass.",
-        ],
-        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