@bli-cockpit/cli 0.2.55 → 0.2.57

package/dist/commands/agent-door.js

@@ -0,0 +1,85 @@
+/**
+ * One request, and a refusal that keeps the DOOR'S own words (BLI-3706).
+ *
+ * `docs`/`msg` answer a refusal with `{ code: "BLI-E<status>", reason, message }`
+ * (`lib/docs/api-doors.ts` / `lib/msg/api-doors.ts`), a different shape from
+ * the meeting-notes doors' `{ headline, lines, reason }` that `notes.ts`'s own
+ * `ask()` reads. This is that same discipline for the newer shape: the
+ * `reason` label a door chose travels to the terminal UNCHANGED, and `message`
+ * is the sentence a person reads — never a second wording invented here.
+ *
+ * `cockpit docs` and `cockpit msg` both call this rather than keeping two
+ * copies, because the shape is identical on both surfaces (BLI-3654 Wave 1a
+ * and Wave 3a share `resolveCaller` + a `{code,reason,message}` refusal).
+ */
+import { writeLine } from "./cli-io.js";
+import { loadPairedSession, towerFailureDetail, towerRequest, } from "../tower-client.js";
+import { readResponseJson } from "../upload-http.js";
+/** Loads the paired session and builds the door every verb in one command run shares. */
+export async function openAgentDoor(commandName, command, io) {
+    const session = await loadPairedSession(commandName, command.homeDir);
+    return {
+        dashboardUrl: command.dashboardUrl ?? session.dashboard_url,
+        deviceToken: session.device_token,
+        io,
+        json: command.json,
+    };
+}
+export async function askAgentDoor(door, options) {
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: options.path,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: options.method,
+        label: options.label,
+        timeoutMs: options.timeoutMs,
+        ...(options.body === undefined ? {} : { body: options.body }),
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        const failure = result;
+        return { ok: false, reason: failure.reason, detail: towerFailureDetail(failure.reason, failure.detail) };
+    }
+    const body = await readResponseJson(result.response);
+    if (!result.response.ok) {
+        const status = result.response.status;
+        return {
+            ok: false,
+            httpStatus: status,
+            reason: doorReason(body) ?? `http_${status}`,
+            detail: doorMessage(body) ?? `Tower answered ${status} and said nothing about why.`,
+        };
+    }
+    return { ok: true, httpStatus: result.response.status, body };
+}
+/** The door's own `reason` label (`document_not_found_or_unreadable`, `needs_rls_client`, …), verbatim. */
+function doorReason(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const value = record["reason"] ?? record["error"];
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+function doorMessage(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const value = record["message"];
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+/** One machine-readable object on stdout, and nothing else on it. */
+export function emitAgentDoor(door, body, exitCode = 0) {
+    writeLine(door.io.stdout, JSON.stringify(body));
+    return exitCode;
+}
+export function failAgentDoor(door, tag, reason, detail) {
+    writeLine(door.io.stderr, `${tag} refused ${JSON.stringify({ reason })}`);
+    if (door.json) {
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(door.io.stderr, detail);
+    }
+    return 1;
+}

package/dist/commands/docs.js

@@ -0,0 +1,227 @@
+/**
+ * `cockpit docs` — the document library, typed (BLI-3706).
+ *
+ * Five verbs over `/api/docs/**`, the same doors the `/workbook`… no, the
+ * SEPARATE `/api/docs/**` surface (BLI-3654 Wave 3a) that the browser's own
+ * document editor reads and writes. Every `/api/docs/**` route already opted
+ * into the collector device token via `resolveCaller({ allowDeviceToken: true
+ * })` — this command needed no server-side door change, only a terminal in
+ * front of the existing one.
+ *
+ * `read <id|slug>` and `update <id>` both accept a full document id OR its
+ * slug. There is no `GET` by slug on the server (`getDocument` reads by id
+ * only), so a slug is resolved locally against the flat list `GET
+ * /api/docs/documents` already returns — the same read `docs list` prints,
+ * never a second query the server does not already answer.
+ *
+ * A refusal keeps the door's own `reason` label verbatim (`agent-door.ts`):
+ * `needs_rls_client`, `document_not_found_or_unreadable`,
+ * `document_not_writable`, `title_too_long`, `content_too_long`,
+ * `circular_parent`, and so on — never rephrased here.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+const BODY_MAX_CHARS = 2_000_000;
+export async function runDocs(command, io) {
+    const door = await openAgentDoor("docs", command, io);
+    switch (command.action) {
+        case "list":
+            return listDocs(door);
+        case "tree":
+            return treeDocs(door);
+        case "read":
+            return readDoc(command, door);
+        case "create":
+            return createDoc(command, door);
+        case "update":
+            return updateDoc(command, door);
+    }
+}
+async function listDocs(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "GET",
+        label: "docs list",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const documents = (answer.body.documents ?? []);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, documents });
+    if (documents.length === 0) {
+        writeLine(door.io.stdout, "No documents.");
+        return 0;
+    }
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${documents.length} document(s).`);
+    return 0;
+}
+function renderTree(nodes, io, depth) {
+    for (const node of nodes) {
+        writeLine(io.stdout, `${"  ".repeat(depth)}${node.title} (${node.slug ?? node.id})`);
+        if (node.children.length > 0)
+            renderTree(node.children, io, depth + 1);
+    }
+}
+async function treeDocs(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/tree",
+        method: "GET",
+        label: "docs tree",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const tree = (answer.body.tree ?? []);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, tree });
+    if (tree.length === 0) {
+        writeLine(door.io.stdout, "No documents.");
+        return 0;
+    }
+    renderTree(tree, door.io, 0);
+    return 0;
+}
+/** Finds a document id by exact id or exact slug against the flat list. Never fuzzy. */
+async function resolveDocId(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "GET",
+        label: "docs resolve",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { status: "list_failed", reason: answer.reason, detail: answer.detail };
+    const documents = (answer.body.documents ?? []);
+    const byId = documents.find((doc) => doc.id === ref);
+    if (byId)
+        return { status: "ok", id: byId.id };
+    const bySlug = documents.find((doc) => doc.slug === ref);
+    if (bySlug)
+        return { status: "ok", id: bySlug.id };
+    return { status: "not_found" };
+}
+async function readDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${ref}`);
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}`,
+        method: "GET",
+        label: "docs read",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const document = answer.body.document ?? {};
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document });
+    writeLine(door.io.stdout, String(document["title"] ?? ""));
+    writeLine(door.io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}`);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, String(document["body_markdown"] ?? ""));
+    return 0;
+}
+/** Body on stdin, never argv (BLI-3706) — `--file` is the safest way on Windows, same as `cockpit notes paste`. */
+async function readBody(command, io) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok)
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(io))
+        return { ok: true, text: "" };
+    try {
+        const text = await readPipedText(io.stdin, {
+            maxChars: BODY_MAX_CHARS,
+            overflowMessage: `A document body is limited to ${BODY_MAX_CHARS} characters.`,
+        });
+        return { ok: true, text };
+    }
+    catch (error) {
+        return { ok: false, reason: "body_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function createDoc(command, door) {
+    if (!command.title)
+        return failAgentDoor(door, TAG, "invalid_body", "docs create needs --title.");
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "POST",
+        label: "docs create",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            title: command.title,
+            body_markdown: body.text,
+            ...(command.parentId ? { parent_id: command.parentId } : {}),
+            ...(command.visibility ? { visibility: command.visibility } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const document = answer.body.document ?? {};
+    writeLine(door.io.stderr, `${TAG} created ${JSON.stringify({ document_id: document["id"] ?? null, byte_size: Buffer.byteLength(body.text, "utf8") })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document });
+    writeLine(door.io.stdout, `Created ${String(document["title"] ?? "")} (${String(document["id"] ?? "")}).`);
+    return 0;
+}
+async function updateDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot write to it: ${ref}`);
+    }
+    let bodyMarkdown;
+    if (command.bodyStdin || command.filePath) {
+        const body = await readBody(command, door.io);
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        bodyMarkdown = body.text;
+    }
+    if (bodyMarkdown === undefined
+        && command.title === undefined
+        && command.visibility === undefined
+        && command.parentId === undefined
+        && !command.clearParent) {
+        return failAgentDoor(door, TAG, "invalid_body", "docs update needs at least one of --title, --visibility, --parent/--clear-parent, or a body on --body-stdin/--file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}`,
+        method: "PATCH",
+        label: "docs update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.title !== undefined ? { title: command.title } : {}),
+            ...(bodyMarkdown !== undefined ? { body_markdown: bodyMarkdown } : {}),
+            ...(command.visibility !== undefined ? { visibility: command.visibility } : {}),
+            ...(command.clearParent ? { parent_id: null } : command.parentId ? { parent_id: command.parentId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const document = answer.body.document ?? {};
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ document_id: document["id"] ?? resolved.id })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document });
+    writeLine(door.io.stdout, `Updated ${String(document["title"] ?? "")} (${String(document["id"] ?? resolved.id)}).`);
+    return 0;
+}

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

@@ -0,0 +1,126 @@
+/**
+ * `cockpit docs` and `cockpit msg` argument parsing (BLI-3706). Split into its
+ * own sibling of `local-args-tower.ts` rather than folded into
+ * `local-args-tower-pages.ts`: docs is a page-reading surface like notes and
+ * workbook, but msg is not — it is a live two-way channel, closer to
+ * `cockpit jarvis` in shape. Keeping the pair together names the ticket that
+ * added both without stretching either existing family's own doc comment.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update"]);
+export function parseDocsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--title",
+            "--parent",
+            "--clear-parent",
+            "--visibility",
+            "--file",
+            "--body-stdin",
+            "--json",
+        ],
+        valueFlags: ["--home", "--dashboard-url", "--title", "--parent", "--visibility", "--file"],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!DOCS_ACTIONS.has(action)) {
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, or update.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let docRef;
+    if (DOCS_ACTIONS_NEEDING_A_DOC.has(action)) {
+        docRef = optionalNonEmpty(rest[0]);
+        if (!docRef)
+            throw new Error(`docs ${action} needs a document id or slug.`);
+        if (rest.length > 1)
+            throw new Error(`docs ${action} takes one document reference, not ${rest.length}.`);
+    }
+    else if (rest.length > 0) {
+        throw new Error(`docs ${action} does not take "${rest[0]}".`);
+    }
+    const visibility = optionalNonEmpty(values.flags.get("--visibility"));
+    if (visibility && visibility !== "org" && visibility !== "private") {
+        throw new Error('docs --visibility must be "org" or "private".');
+    }
+    const clearParent = values.booleans.has("--clear-parent");
+    const parentId = optionalNonEmpty(values.flags.get("--parent"));
+    if (clearParent && parentId) {
+        throw new Error("docs update accepts either --parent or --clear-parent, not both.");
+    }
+    if (clearParent && action !== "update") {
+        throw new Error("--clear-parent belongs to `cockpit docs update`.");
+    }
+    const title = optionalNonEmpty(values.flags.get("--title"));
+    if (action === "create" && !title) {
+        throw new Error("docs create needs --title.");
+    }
+    return {
+        kind: "docs",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(docRef ? { docRef } : {}),
+        title,
+        ...(parentId ? { parentId } : {}),
+        clearParent,
+        visibility: visibility,
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        bodyStdin: values.booleans.has("--body-stdin"),
+        json: values.booleans.has("--json"),
+    };
+}
+const MSG_ACTIONS = new Set(["channels", "read", "send", "thread"]);
+const MSG_ACTIONS_NEEDING_A_CHANNEL = new Set(["read", "send"]);
+export function parseMsgArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit", "--json"],
+        valueFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit"],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "channels" : first);
+    if (!MSG_ACTIONS.has(action)) {
+        throw new Error(`Unknown msg command: ${first}. Try channels, read, send, or thread.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let channelRef;
+    if (MSG_ACTIONS_NEEDING_A_CHANNEL.has(action)) {
+        channelRef = optionalNonEmpty(rest[0]);
+        if (!channelRef)
+            throw new Error(`msg ${action} needs a channel id or name.`);
+        if (rest.length > 1)
+            throw new Error(`msg ${action} takes one channel, not ${rest.length}.`);
+    }
+    else if (action === "thread") {
+        // `thread <id> --channel <channel>` — the channel is a flag here because
+        // the positional names the THREAD, not the channel (`--channel` below).
+        if (rest.length > 1)
+            throw new Error(`msg thread takes one thread id, not ${rest.length}.`);
+    }
+    else if (rest.length > 0) {
+        throw new Error(`msg ${action} does not take "${rest[0]}".`);
+    }
+    const threadFlag = optionalNonEmpty(values.flags.get("--thread"));
+    const threadId = action === "thread" ? optionalNonEmpty(rest[0]) : threadFlag;
+    if (action === "thread" && !threadId)
+        throw new Error("msg thread needs a thread id.");
+    const channelFlag = optionalNonEmpty(values.flags.get("--channel"));
+    if (action === "thread")
+        channelRef = channelFlag;
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && action !== "read" && action !== "thread") {
+        throw new Error("--limit belongs to `cockpit msg read` or `cockpit msg thread`.");
+    }
+    return {
+        kind: "msg",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(channelRef ? { channelRef } : {}),
+        ...(threadId ? { threadId } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        json: values.booleans.has("--json"),
+    };
+}

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

@@ -16,9 +16,12 @@
  *   local-args-tower-admin.ts   scout, ops, slack, — managing the account or
  *                                settings, team,      watching the pipeline
  *                                model
+ *   local-args-tower-docs-msg.ts docs, msg          — the document library and
+ *                                                      channels/messages (BLI-3706)
  *
  * Every name this module has ever exported is still importable from here.
  */
 export { parseJarvisArgs, parseCorrectArgs } from "./local-args-tower-chat.js";
 export { parseBriefArgs, WORKBOOK_MIN_WIDTH, parseWorkbookArgs, parseNotesArgs, } from "./local-args-tower-pages.js";
-export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_KEYS, parseSlackArgs, parseSettingsArgs, parseTeamArgs, parseModelArgs, } from "./local-args-tower-admin.js";
+export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_KEYS, parseSlackArgs, parseSettingsArgs, parseTeamArgs, parseModelArgs, } from "./local-args-tower-admin.js";
+export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";

package/dist/commands/local-args.js

@@ -1,5 +1,5 @@
 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, parseJarvisArgs, parseModelArgs, parseNotesArgs, parseOpsArgs, parseScoutArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseJarvisArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseScoutArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } 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
@@ -84,6 +84,10 @@ export function parseLocalArgs(argv) {
             return parseMemoryArgs(argv.slice(1));
         case "clean":
             return parseCleanArgs(argv.slice(1));
+        case "docs":
+            return parseDocsArgs(argv.slice(1));
+        case "msg":
+            return parseMsgArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
         default:

package/dist/commands/local-help.js

@@ -40,6 +40,8 @@ export const rootCommandNames = new Set([
     "agent-rules",
     "memory",
     "clean",
+    "docs",
+    "msg",
     "release",
 ]);
 export function localCommandHelp(command) {
@@ -78,6 +80,8 @@ export function localCommandHelp(command) {
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
         "  cockpit memory [install|status] [--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>|--clear-parent] [--visibility org|private] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
+        "  cockpit msg [channels|read <channel>|send <channel>|thread <id> --channel <channel>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
         "",
         `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.`,
@@ -580,6 +584,38 @@ function localSubcommandHelp(command) {
                 "right now.",
             ],
         ],
+        [
+            "docs",
+            [
+                "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+                "",
+                "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
+                "list — every document you may see: id, visibility, slug, title.",
+                "tree — the same documents nested under their parent, for a sidebar-shaped view.",
+                "read <id|slug> — one document's title, slug, visibility, and its body.",
+                "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
+                "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+                "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "msg",
+            [
+                "Usage: cockpit msg [channels|read <channel>|send <channel>|thread <id> --channel <channel>] [flags]",
+                "",
+                "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
+                "channels — every channel you are a member of (or, as a super_admin, every channel).",
+                "read <channel> [--limit <n>] [--thread <id>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
+                "send <channel> [--thread <id>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
+                "thread <id> --channel <channel> — one thread's replies by the parent message's id.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, channel_not_found_or_unreadable, content_too_long, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
         [
             "release",
             [

package/dist/commands/local.js

@@ -32,6 +32,8 @@ import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
 import { runMemoryInstall } from "./memory-install.js";
 import { runClean } from "./clean.js";
+import { runDocs } from "./docs.js";
+import { runMsg } from "./msg.js";
 import { parseLocalArgs } from "./local-args.js";
 // `./local.js` is the published entry point for this command surface: the
 // public CLI's generated root, commands/root.ts, doctor.ts and the test suite
@@ -131,6 +133,10 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runMemoryInstall(command, io);
             case "clean":
                 return await runClean(command, io);
+            case "docs":
+                return await runDocs(command, io);
+            case "msg":
+                return await runMsg(command, io);
             case "release":
                 return await runRelease(command, io);
         }

package/dist/commands/mcp-bin-resolve.js

@@ -0,0 +1,102 @@
+/**
+ * Where an MCP server's bin lives on THIS machine, for any server shipped as a
+ * dependency of `@bli-cockpit/cli` (BLI-3580's `resolveMemoryMcpBin`,
+ * generalised for BLI-3706's `bli-tower` registration so the second server
+ * does not carry a second copy of this walk).
+ *
+ * Two steps, in this order — see `memory-install.ts`'s `resolveMemoryMcpBin`
+ * doc comment for the full BLI-3580 story of why the walk starts at THIS
+ * module's own file (never a shim) and realpath-resolves every anchor before
+ * walking:
+ *
+ *  1. Beside the CLI that is running — the ONLY lookup that cannot find
+ *     somebody else's copy of the bin.
+ *  2. PATH, as a fallback for a linked checkout or a hand-installed server.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export async function resolveMcpBin(options) {
+    const exists = options.fileExists ?? defaultFileExists;
+    const beside = await resolveBesideCli(options, exists);
+    if (beside)
+        return { path: beside, source: "cli_dependency" };
+    const onPath = await resolveOnPath(options, exists);
+    return onPath ? { path: onPath, source: "path" } : null;
+}
+function besideAnchors(options) {
+    const anchors = [];
+    const own = currentModulePath();
+    if (own)
+        anchors.push(own);
+    const entry = options.cliEntryPoint ?? process.argv[1];
+    if (entry)
+        anchors.push(entry);
+    return anchors;
+}
+function currentModulePath() {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveBesideCli(options, exists) {
+    const platformPath = options.platform === "win32" ? path.win32 : path.posix;
+    const extensions = binExtensions(options.platform);
+    const realpath = options.realpath ?? defaultRealpath;
+    for (const anchor of besideAnchors(options)) {
+        let directory = platformPath.dirname(realpath(platformPath.resolve(anchor)));
+        // Bounded walk: deep enough for `…/node_modules/@scope/pkg/dist/cli.js`
+        // plus a hoisted root above it, and it stops at the filesystem root anyway.
+        for (let depth = 0; depth < 12; depth += 1) {
+            for (const extension of extensions) {
+                const candidate = platformPath.join(directory, "node_modules", ".bin", `${options.binName}${extension}`);
+                if (await exists(candidate))
+                    return candidate;
+            }
+            const parent = platformPath.dirname(directory);
+            if (parent === directory)
+                break;
+            directory = parent;
+        }
+    }
+    return null;
+}
+function defaultRealpath(value) {
+    try {
+        return fs.realpathSync.native(value);
+    }
+    catch {
+        return value;
+    }
+}
+async function resolveOnPath(options, exists) {
+    const platformPath = options.platform === "win32" ? path.win32 : path.posix;
+    const entries = (options.env["PATH"] ?? options.env["Path"] ?? "")
+        .split(platformPath.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const entry of entries) {
+        for (const extension of binExtensions(options.platform)) {
+            const candidate = platformPath.join(entry, `${options.binName}${extension}`);
+            if (await exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** npm writes `.cmd` (and `.ps1`) shims on Windows; POSIX gets the bare name. */
+function binExtensions(platform) {
+    return platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+}
+async function defaultFileExists(file) {
+    const { stat } = await import("node:fs/promises");
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch {
+        return false;
+    }
+}