@bli-cockpit/cli 0.2.97 → 0.2.99

package/dist/cli.js

@@ -1,5 +1,18 @@
 #!/usr/bin/env node
 import { runCockpitCli } from "./commands/public-root.js";
+import {
+  EXIT_DIED_MID_RUN,
+  installCrashGuard,
+  markCommandReturned,
+} from "./crash-guard.js";
+
+// BLI-4110. Success is EARNED, not assumed — see crash-guard.js. This
+// entry point is GENERATED, so it must mirror src/cli.ts; the packed CLI
+// is the one the fleet runs.
+process.exitCode = EXIT_DIED_MID_RUN;
+installCrashGuard();
 
 const exitCode = await runCockpitCli(process.argv.slice(2));
+
+markCommandReturned();
 process.exitCode = exitCode;

package/dist/commands/doctor.js

@@ -1,3 +1,4 @@
+import { withStage } from "../crash-guard.js";
 import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
 import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
 import { checkMcpAnswersState } from "./doctor-mcp.js";
@@ -14,7 +15,7 @@ export async function runDoctorWithDeps(command, io, deps) {
     const context = { command, io, deps };
     const rows = [];
     for (const invariant of doctorInvariants()) {
-        const checked = await invariant.check(context);
+        const checked = await withStage(`doctor:check:${invariant.id}`, () => invariant.check(context));
         if (checked.status === "ok" || checked.status === "skipped") {
             rows.push(checked);
             continue;
@@ -31,7 +32,10 @@ export async function runDoctorWithDeps(command, io, deps) {
                 break;
             continue;
         }
-        const fixed = await invariant.fix(context, checked);
+        // BLI-4110: named so a crash inside a repair says WHICH repair. The
+        // 2026-09-09 incident printed a bare `read ENOTCONN` stack and the only
+        // way to place it was the log line that happened to precede it.
+        const fixed = await withStage(`doctor:fix:${invariant.id}`, () => invariant.fix(context, checked));
         rows.push({ ...fixed, fixed: fixed.status !== "fail" });
         if (fixed.hardStop)
             break;

package/dist/commands/local-args-collector-status.js

@@ -11,6 +11,7 @@
 import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
 import { assertNoPositionals, normalizeUrl, optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { MEMORY_STORE_ACTIONS, parseMemoryStoreArgs, } from "./local-args-tower-memory.js";
 export function parseStatusArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -164,11 +165,30 @@ export function parseAgentRulesArgs(args) {
     };
 }
 /**
- * BLI-3580. `install` is the default action on purpose: this command exists to
- * be run unasked (by `do-everything` and by the sync tick), and a bare
- * `cockpit memory` should do the thing rather than print usage.
+ * BLI-3580, amended by BLI-4047.
+ *
+ * `cockpit memory` is now SIX verbs behind one noun: the two that configure
+ * this machine (`install`, `status`), the experience log (`log`), and the four
+ * that read and write the memory store itself (`search`, `save`, `update`,
+ * `forget`, parsed next door in `local-args-tower-memory.ts`).
+ *
+ * **A bare `cockpit memory` prints the verb list; it no longer installs.**
+ * BLI-3580 made `install` the default because the command is run unasked by
+ * `do-everything` and by the sync tick — but those callers build
+ * `{ kind: "memory", action: "install" }` in code (`doctor-registration.ts`,
+ * `sync-followups-memory.ts`, `onboard-completion.ts`) and never pass through
+ * this parser. The only caller the default ever served was a PERSON typing the
+ * noun to find out what it does, and what they got was an MCP server and three
+ * hooks registered on their machine. Installing stays one word away.
  */
 export function parseMemoryArgs(args) {
+    // The verb word first, always: reading it off `args[0]` rather than "the
+    // first token without a leading dash" is what keeps `cockpit memory --home
+    // /tmp/x status` from being read as the verb `/tmp/x`.
+    const first = args[0];
+    if (first !== undefined && MEMORY_STORE_ACTIONS.has(first)) {
+        return parseMemoryStoreArgs(first, args);
+    }
     const values = parseNamedArgs(args, {
         allowedFlags: ["--home", "--dashboard-url", "--dry-run", "--json", "--store", "--reason-stdin"],
         valueFlags: ["--home", "--dashboard-url", "--store"],
@@ -192,9 +212,10 @@ export function parseMemoryArgs(args) {
     if (values.positionals.length > 1) {
         throw new Error("memory accepts at most one action (install|status).");
     }
-    const action = values.positionals[0] ?? "install";
-    if (action !== "install" && action !== "status") {
-        throw new Error("memory action must be install or status.");
+    // BLI-4047: no positional means "tell me what this noun does", not "install".
+    const action = values.positionals[0] ?? "help";
+    if (action !== "install" && action !== "status" && action !== "help") {
+        throw new Error("memory action must be install, status, help, log, search, save, update, or forget.");
     }
     return {
         kind: "memory",

package/dist/commands/local-args-tower-admin.js

@@ -14,9 +14,17 @@ import { isTeamDeviceRevokeReasonLabel, TEAM_DEVICE_REVOKE_REASON_LABELS, } from
 /** The shortest prefix `cockpit scout start` will resolve. Below this, ids collide. */
 export const SCOUT_MIN_PREFIX_LENGTH = 6;
 /**
- * `cockpit scout [--days <n>]` reads the board; `cockpit scout start|dismiss|undo
- * <id>` moves one card. Positional shape modelled on `autostart`: an optional
- * action word first, then what it acts on.
+ * `cockpit scout [board] [--days <n>]` reads the board; `cockpit scout
+ * start|dismiss|undo <id>` moves one card. Positional shape modelled on
+ * `autostart`: an optional action word first, then what it acts on.
+ *
+ * `board` is spellable as well as implied (BLI-4048). The parsed command has
+ * always carried `action: "board"`, the MCP twin has always been `scout_board`,
+ * and three documents printed `cockpit scout board` under a "CLI verb" heading
+ * while the parser answered "scout action must be start, dismiss, or undo" —
+ * the promise was older than the refusal. Every sibling noun (`ops status`,
+ * `slack coverage`, `notes list`) lets a person name the read it defaults to,
+ * so scout does too, and the word costs one branch.
  */
 export function parseScoutArgs(args) {
     const values = parseNamedArgs(args, {
@@ -24,7 +32,7 @@ export function parseScoutArgs(args) {
         valueFlags: ["--home", "--dashboard-url", "--days"],
     });
     if (values.positionals.length > 2) {
-        throw new Error("scout accepts at most an action (start|dismiss|undo) and one experiment id.");
+        throw new Error("scout accepts at most an action (board|start|dismiss|undo) and one experiment id.");
     }
     const [rawAction, rawRef] = values.positionals;
     const base = {
@@ -33,10 +41,13 @@ export function parseScoutArgs(args) {
         days: optionalPositiveInteger(values.flags.get("--days"), "--days"),
         json: values.booleans.has("--json"),
     };
-    if (!rawAction)
+    if (!rawAction || rawAction === "board") {
+        if (rawRef)
+            throw new Error("scout board reads the whole board; it takes no experiment id.");
         return { kind: "scout", action: "board", ...base };
+    }
     if (rawAction !== "start" && rawAction !== "dismiss" && rawAction !== "undo") {
-        throw new Error("scout action must be start, dismiss, or undo.");
+        throw new Error("scout action must be board, start, dismiss, or undo.");
     }
     const experimentRef = optionalNonEmpty(rawRef);
     if (!experimentRef) {

package/dist/commands/local-args-tower-memory.js

@@ -0,0 +1,151 @@
+/**
+ * `cockpit memory search|save|update|forget` — the argument table (BLI-4047).
+ *
+ * BLI Memory was the one Tower surface with no command-line door: the browser
+ * had one, the `bli-memory` MCP server had one, and a person or a script at a
+ * terminal had nothing. These four verbs are the twins of that server's four
+ * tools, over the SAME `/api/memory/*` doors.
+ *
+ * Two rules this table exists to enforce, both of them the same discipline
+ * `cockpit docs create` and `cockpit notes paste` already follow:
+ *
+ *  - **A body never travels on the command line.** `save`, `update` and
+ *    `forget --content` read their text from stdin (or `--file`, which is the
+ *    safest way to say it on Windows). An argument list is visible in `ps`,
+ *    lands in a shell history file, and is quoted wrong on the first line that
+ *    contains a newline. A QUERY is not a body — `search` takes one
+ *    positional, the same way `cockpit search` and `cockpit docs list --query`
+ *    do — but the text of a memory always is.
+ *  - **The container tag is derived, not typed.** Omit `--container` and the
+ *    tag comes from this repository, resolved by `@bli-cockpit/memory-mcp`'s
+ *    own resolver, so a memory saved from the terminal lands in the same space
+ *    the MCP server and the hooks write to. `--container` may be repeated on
+ *    `search` alone, because searching two spaces is meaningful and saving
+ *    into two is not.
+ *
+ * The verbs live in their own `kind` (`memory-store`) rather than widening
+ * `kind: "memory"`, because that command acts on THIS MACHINE (it registers an
+ * MCP server and three hooks) and these act on Tower. `memory-store.ts` runs
+ * them; `parseMemoryArgs` in `local-args-collector-status.ts` routes to here.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
+export const MEMORY_STORE_ACTIONS = new Set([
+    "search",
+    "save",
+    "update",
+    "forget",
+]);
+const ALLOWED_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--workspace",
+    "--repo",
+    "--container",
+    "--limit",
+    "--no-recent",
+    "--custom-id",
+    "--extract",
+    "--file",
+    "--content-stdin",
+    "--reason",
+    "--json",
+];
+const VALUE_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--workspace",
+    "--repo",
+    "--container",
+    "--limit",
+    "--custom-id",
+    "--file",
+    "--reason",
+];
+export function parseMemoryStoreArgs(action, args) {
+    const values = parseNamedArgs(args, { allowedFlags: ALLOWED_FLAGS, valueFlags: VALUE_FLAGS });
+    const rest = values.positionals.slice(1);
+    const containers = values.flagValues.get("--container") ?? [];
+    if (action !== "search" && containers.length > 1) {
+        throw new Error(`memory ${action} takes at most one --container.`);
+    }
+    if (action !== "search" && (values.flags.has("--limit") || values.booleans.has("--no-recent"))) {
+        throw new Error("--limit and --no-recent only apply to memory search.");
+    }
+    if (action !== "save" && (values.flags.has("--custom-id") || values.booleans.has("--extract"))) {
+        throw new Error("--custom-id and --extract only apply to memory save.");
+    }
+    if (action !== "forget" && (values.flags.has("--reason") || values.booleans.has("--content-stdin"))) {
+        throw new Error("--reason and --content-stdin only apply to memory forget.");
+    }
+    if (values.flags.has("--file") && action !== "save" && action !== "update") {
+        throw new Error("--file only applies to memory save and memory update.");
+    }
+    const command = {
+        kind: "memory-store",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        workspace: optionalNonEmpty(workRootFlagValue(values)),
+        containerTags: containers
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0),
+        json: values.booleans.has("--json"),
+    };
+    if (action === "search") {
+        // Every remaining positional joined, so `cockpit memory search what did we
+        // decide about pagination` needs no quotes — the same shape `cockpit
+        // search` and `cockpit cal find` already have.
+        const query = rest.join(" ").trim();
+        if (!query)
+            throw new Error("memory search needs a question, e.g. `cockpit memory search \"pagination rule\"`.");
+        return { ...command, action, query, limit: readLimit(values.flags.get("--limit")), includeRecent: !values.booleans.has("--no-recent") };
+    }
+    if (action === "save") {
+        if (rest.length > 0) {
+            throw new Error("memory save reads the memory from stdin or --file, never from the command line: `echo \"...\" | cockpit memory save`.");
+        }
+        return {
+            ...command,
+            action,
+            customId: optionalNonEmpty(values.flags.get("--custom-id")),
+            extract: values.booleans.has("--extract"),
+            filePath: optionalNonEmpty(values.flags.get("--file")),
+        };
+    }
+    if (action === "update") {
+        const memoryId = optionalNonEmpty(rest[0]);
+        if (!memoryId)
+            throw new Error("memory update needs the memory id `cockpit memory search` printed.");
+        if (rest.length > 1) {
+            throw new Error("memory update takes one id; the replacement text comes from stdin or --file, never from the command line.");
+        }
+        return { ...command, action, memoryId, filePath: optionalNonEmpty(values.flags.get("--file")) };
+    }
+    const memoryId = optionalNonEmpty(rest[0]);
+    if (rest.length > 1)
+        throw new Error("memory forget takes one id, or --content-stdin with a --container.");
+    const contentStdin = values.booleans.has("--content-stdin");
+    if (memoryId && contentStdin) {
+        throw new Error("memory forget takes an id OR --content-stdin, never both — they name different rows.");
+    }
+    if (!memoryId && !contentStdin) {
+        throw new Error("memory forget needs an id, or --content-stdin plus --container to forget by exact text.");
+    }
+    return {
+        ...command,
+        action,
+        memoryId,
+        contentStdin,
+        reason: optionalNonEmpty(values.flags.get("--reason")),
+    };
+}
+/** 1..20, the same window the MCP tool and the door both accept. */
+function readLimit(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 20) {
+        throw new Error("--limit must be between 1 and 20.");
+    }
+    return parsed;
+}

package/dist/commands/local-args-tower-pages.js

@@ -162,6 +162,7 @@ const NOTES_ACTIONS = new Set([
     "share",
     "unshare",
     "move",
+    "place",
 ]);
 /** Actions whose first positional is the note it acts on. */
 const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
@@ -169,6 +170,7 @@ const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
     "share",
     "unshare",
     "move",
+    "place",
 ]);
 export function parseNotesArgs(args) {
     const values = parseNamedArgs(args, {
@@ -180,6 +182,7 @@ export function parseNotesArgs(args) {
             "--exclude",
             "--to",
             "--clear-shelf",
+            "--apply",
             "--series",
             "--kind",
             "--since",
@@ -207,7 +210,7 @@ export function parseNotesArgs(args) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!NOTES_ACTIONS.has(action)) {
-        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, or move.`);
+        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, move, or place.`);
     }
     const rest = values.positionals.slice(first === undefined ? 0 : 1);
     const json = values.booleans.has("--json");
@@ -259,6 +262,8 @@ export function parseNotesArgs(args) {
         exclude: optionalNonEmpty(values.flags.get("--exclude")),
         ...(to ? { to } : {}),
         ...(clearShelf ? { clearShelf } : {}),
+        // BLI-4058. `place` says where a note belongs; only `--apply` moves it.
+        ...(values.booleans.has("--apply") ? { apply: true } : {}),
         series: optionalNonEmpty(values.flags.get("--series")),
         meetingKind: optionalNonEmpty(values.flags.get("--kind")),
         since: optionalNonEmpty(values.flags.get("--since")),

package/dist/commands/local-args-tower-usage.js

@@ -0,0 +1,8 @@
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export function parseUsageArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: ["--since", "--until", "--include-automated", "--home", "--dashboard-url", "--json"], valueFlags: ["--since", "--until", "--home", "--dashboard-url"] });
+    const action = values.positionals[0] ?? "people";
+    if (action !== "people" || values.positionals.length > 1)
+        throw new Error("usage takes one verb: people.");
+    return { kind: "usage", action: "people", since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), includeAutomated: values.booleans.has("--include-automated"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), json: values.booleans.has("--json") };
+}

package/dist/commands/local-args-tower.js

@@ -35,4 +35,5 @@ export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-to
 export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
 export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";
-export { parseCalArgs } from "./local-args-tower-cal.js";
+export { parseCalArgs } from "./local-args-tower-cal.js";
+export { parseUsageArgs } from "./local-args-tower-usage.js";

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -115,6 +115,8 @@ export function parseLocalArgs(argv) {
             return parseSearchArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
+        case "usage":
+            return parseUsageArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

package/dist/commands/local-command-shapes-memory.js

@@ -0,0 +1,22 @@
+/**
+ * The `cockpit memory` family's command shapes (BLI-4047).
+ *
+ * Split out of `local-command-shapes.ts` the same way `SearchCommandShape` and
+ * the product shapes were: that file crossed the repo's 500-line band floor
+ * when the store verbs arrived, and one noun's shapes are exactly the kind of
+ * thing that reads better in its own file than as a third of a 540-line union.
+ *
+ * Three kinds, and the difference between them is the point:
+ *
+ *   `memory`        install / status / help — acts on THIS MACHINE, writing an
+ *                   MCP registration and three hooks into a home directory.
+ *   `memory-store`  search / save / update / forget — acts on TOWER, over
+ *                   `/api/memory/*`, the same doors the `bli-memory` MCP
+ *                   server and the browser call.
+ *   `memory-log`    the agent-experience opinion, part local file part Tower.
+ *
+ * They are separate kinds rather than one widening `action` union because they
+ * refuse different things, run on different credentials, and one of them can
+ * be run unasked by a scheduler while the others never are.
+ */
+export {};

package/dist/commands/local-help-commands-tower.js

@@ -11,6 +11,15 @@
  * Every string moved verbatim. Help output is what an intern pastes back when
  * something breaks, so it is a user-visible contract like any other.
  */
+import { SEARCH_KINDS } from "./local-args-tower-search.js";
+/**
+ * The corpora `cockpit search` can name, spelled the way `--kind` takes them.
+ * Read off `SEARCH_KINDS` rather than typed out: the help string said five for
+ * the two months `mail` and `cal` were searchable, so a person was told the
+ * door was narrower than it is (BLI-4048).
+ */
+const SEARCH_KIND_LIST = SEARCH_KINDS.join(",");
+const SEARCH_CORPORA_COUNT = SEARCH_KINDS.length;
 /** One entry per Tower noun, in the order `cockpit --help` lists them. */
 export const TOWER_COMMAND_HELP = [
     [
@@ -130,12 +139,27 @@ export const TOWER_COMMAND_HELP = [
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
         ],
     ],
+    [
+        "usage",
+        [
+            "Usage: cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--json]",
+            "",
+            "Claude Code and Codex usage per person: sessions observed and extracted, tokens (total, output,",
+            "and the input / cache split when the row carries it), and an API list-price equivalent that is",
+            "labelled as such and is never actual spend. A super_admin sees everyone; a member sees their own row.",
+            "--since takes 7d, 30d, 90d or an ISO timestamp; --until an ISO timestamp (default now).",
+            "--include-automated adds harness, subagent and scheduled sessions, which are excluded by default.",
+            "It presses the same door as the /usage page and the usage_people MCP tool (GET /api/usage/people).",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+        ],
+    ],
     [
         "search",
         [
-            'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
+            `Usage: cockpit search "<words>" [--kind ${SEARCH_KIND_LIST}] [--limit <n>] [--json]`,
             "",
-            "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
+            `One bar over ${SEARCH_CORPORA_COUNT} corpora: documents, messages, issues, meeting notes, mail, calendar`,
+            "events and memory.",
             "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
             "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
             "",
@@ -144,12 +168,14 @@ export const TOWER_COMMAND_HELP = [
             "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
             "websearch parser, which shrugs at anything a person can type instead of raising.",
             "",
-            "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
+            `--kind narrows to one or more corpora, comma separated: ${SEARCH_KIND_LIST}.`,
+            `Omit it and all ${SEARCH_CORPORA_COUNT} are searched.`,
             "--limit caps the number of results (default 20, maximum 50).",
             "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
             "",
-            "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
-            "own database session, so a document or a channel you cannot open is not in the list.",
+            `Every result is scoped by what YOU may read: ${SEARCH_CORPORA_COUNT - 1} of the ${SEARCH_CORPORA_COUNT} corpora are`,
+            "searched on your own database session, so a document or a channel you cannot open is not in",
+            "the list; memory runs on the service role behind the memory doors' own gate.",
             "",
             "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
             "those are different facts and folding them together would let a broken search read as silence.",

package/dist/commands/local-help-commands.js

@@ -305,12 +305,14 @@ export function localSubcommandHelp(command) {
         [
             "scout",
             [
-                "Usage: cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
                 "",
                 "Prints the same Scout board the Tower page shows, in the same words: the standing",
                 "watch line, the cards waiting on a decision, and the raw signal watch underneath.",
                 "This is the board itself. To ask a QUESTION about it — what it means, whether it is",
                 "worth doing here — use `cockpit jarvis`, whose readScout tool reads the same rows.",
+                "`cockpit scout board` and a bare `cockpit scout` are the same command; the MCP twin",
+                "is `scout_board` on the bli-tower server, over the same GET /api/cockpit/scout door.",
                 "--days <n> widens or narrows the window (1 to 90; the board defaults to 14).",
                 "Reading follows the Scout page audience setting, so whoever can open /scout can run this.",
                 "start, dismiss, and undo move one card and are super_admin actions on every surface;",
@@ -461,6 +463,7 @@ export function localSubcommandHelp(command) {
                 "share <id> [--yes] — let everyone signed in read the statements that are safe to share. Asks first in a terminal; --yes is required without one, and --json implies --yes.",
                 "unshare <id> — take it back. Never asks: it only ever narrows who can read.",
                 "move <id> (--to \"<shelf>\"|--clear-shelf) — put it on a different shelf, or take the shelf off.",
+                "place <id> [--apply] — say which shelf this note belongs on and why, from the meeting it is part of, who was in the room and its own name. Moves nothing without --apply, and never overrules a shelf somebody typed.",
                 "A large note is read by a model on the server and can take a couple of minutes; the terminal says so before it waits.",
                 "--json writes one machine-readable object to stdout; every reason, receipt and progress line stays on stderr.",
                 "Sharing and moving need a signed-in session the database can see. If this deployment cannot mint one, they are refused as needs_signed_in_session rather than done with no permission check — and reads say when they came back narrower than the browser's.",
@@ -555,15 +558,32 @@ export function localSubcommandHelp(command) {
         [
             "memory",
             [
-                "Usage: cockpit memory [install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--dashboard-url <url>] [--dry-run] [--json]",
-                "",
-                "Registers BLI Memory on this machine: the `bli-memory` MCP server plus the",
+                "Usage: cockpit memory [search|save|update|forget|install|status|log] [flags]",
+                "",
+                "The STORE, over the same /api/memory/* doors the bli-memory MCP server calls:",
+                "  search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent]",
+                "      repeat --container to search more than one space; omit it for this repository's own.",
+                "  save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>]",
+                "      the memory comes from stdin or --file, never from the command line:",
+                "      `echo \"Edward decided X on 2026-09-10\" | cockpit memory save`.",
+                "      --custom-id makes a repeat save update instead of duplicating;",
+                "      --extract distils atomic facts first (one model call) instead of storing as given.",
+                "  update <id> [--file <path>]   replacement text on stdin; the old row is kept as history.",
+                "  forget <id> [--reason <label>]",
+                "  forget --content-stdin --container <tag> [--reason <label>]   forget by exact text.",
+                "Refusals keep the door's own label — needs_rls_client, unknown_memory,",
+                "already_superseded, no_match — and --json prints the door's answer unchanged.",
+                "",
+                "BARE `cockpit memory` PRINTS THIS LIST AND DOES NOTHING ELSE (BLI-4047).",
+                "It used to run the installer; installing is now `cockpit memory install`.",
+                "",
+                "install/status register BLI Memory on this machine: the `bli-memory` MCP server plus the",
                 "recall/save hooks, for Claude Code (~/.claude.json, ~/.claude/settings.json)",
                 "and for Codex (~/.codex/config.toml, ~/.codex/skills/bli-memory/).",
                 "Idempotent: it merges with what is already there, never duplicates its own",
                 "entries, and reads the stored config back before reporting success.",
                 "`do-everything` runs it, and the sync tick re-runs it at most once a day.",
-                "Action defaults to `install`. See docs/runbooks/bli-memory-install.md.",
+                "See docs/runbooks/bli-memory-install.md.",
                 "log appends an opinion to ~/.codex/AGENT-EXPERIENCE.md and posts it to Tower.",
                 "Use --reason-stdin instead of a quoted reason; --json reports shipped status.",
                 "Reasons: one line, max 500 characters; no prompts, memory bodies or secrets.",

package/dist/commands/local-help.js

@@ -8,6 +8,7 @@
  * user-visible contract like any other.
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { SEARCH_KINDS } from "./local-args-tower-search.js";
 import { localSubcommandHelp } from "./local-help-commands.js";
 export const rootCommandNames = new Set([
     "onboard",
@@ -51,6 +52,7 @@ export const rootCommandNames = new Set([
     "project",
     "search",
     "release",
+    "usage",
 ]);
 export function localCommandHelp(command) {
     if (command)
@@ -72,7 +74,7 @@ export function localCommandHelp(command) {
         "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
         "  cockpit model [show|set <provider:model>] [--json]",
         "  cockpit models [list|show <provider:model>|compare <provider:model> <provider:model> [...]] [--highlight] [--dashboard-url <url>] [--json]",
-        "  cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+        "  cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
         "  cockpit ops [status [--job <id>] [--skips] [--memory] [--models] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
         "  cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] | read [--person <p>] [--channel <c>] [--query <text>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>]] [--json]",
         "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | cli-floor [<version>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
@@ -81,14 +83,14 @@ export function localCommandHelp(command) {
         "  cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
         "  cockpit brief status [--who <person>] [--render] [--dashboard-url <url>] [--json]",
         "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
-        "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--yes] [--dashboard-url <url>] [--json]",
+        "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>|place <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--apply] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit serve [--port <port>] [--workspace <path>]",
         "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
-        "  cockpit memory [install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--dashboard-url <url>] [--dry-run] [--json]",
+        "  cockpit memory [search \"<question>\"|save|update <id>|forget <id>|install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--container <tag>] [--limit <n>] [--no-recent] [--custom-id <id>] [--extract] [--content-stdin] [--reason <label>] [--file <path>] [--dashboard-url <url>] [--dry-run] [--json]",
         "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text>] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
@@ -96,8 +98,9 @@ export function localCommandHelp(command) {
         "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
         "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
-        "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
+        `  cockpit search "<words>" [--kind ${SEARCH_KINDS.join(",")}] [--limit <n>] [--dashboard-url <url>] [--json]`,
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+        "  cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
     ].join("\n");