@bli-cockpit/cli 0.2.287 → 0.2.288

package/dist/commands/agreements-render.js

@@ -0,0 +1,61 @@
+/**
+ * How `cockpit agreements` prints the doors' answers as plain text. The shapes copy
+ * `apps/dashboard/src/lib/agreements/contracts.ts` (this package does not import the dashboard); only the fields
+ * printed here are named.
+ */
+const STATUS_WORDS = { open: "waiting for your signature", signed: "signed", cancelled: "cancelled" };
+/** One request in `cockpit agreements`: what, its state, and the id to show it. */
+export function rowLines(row) {
+    const when = row.status === "signed" && row.signed_at ? `, ${row.signed_at.slice(0, 10)}` : row.status === "open" && row.due_at ? `, due ${row.due_at.slice(0, 10)}` : "";
+    return [`${row.document_title} (${row.version_label}): ${STATUS_WORDS[row.status] ?? row.status}${when}`, `  cockpit agreements show ${row.request_id}`];
+}
+/** A box as it was answered once signed; empty before then, because a box is never pre-ticked. */
+function boxLine(box, ticked) {
+    return `  ${ticked ? "[x]" : "[ ]"} ${box.wording} (${box.required ? "required" : "optional"})`;
+}
+/** `cockpit agreements show`: the exact text, the boxes, and the record once signed, or where to sign while open. */
+export function agreementLines(agreement, dashboardUrl) {
+    const lines = [
+        `${agreement.document_title} (${agreement.version_label})`,
+        `Status: ${STATUS_WORDS[agreement.status] ?? agreement.status}${agreement.status === "open" && agreement.due_at ? `, due ${agreement.due_at.slice(0, 10)}` : ""}`,
+        `Published ${agreement.published_at}. Text fingerprint (SHA-256): ${agreement.text_sha256}`,
+        "",
+        agreement.body,
+        "",
+    ];
+    const signature = agreement.signature;
+    if (agreement.consent_boxes.length > 0) {
+        lines.push("Boxes:", ...agreement.consent_boxes.map((box) => boxLine(box, signature?.consents[box.key] === true)), "");
+    }
+    if (signature) {
+        lines.push("Signing record:", `  Signed by: ${signature.typed_name}${signature.signer_email ? ` <${signature.signer_email}>` : ""}`, `  Signed at: ${signature.signed_at}`, `  Identified by: ${signature.identity_method === "tower_session+email_code" ? "Tower sign-in and a one-time code sent by email" : signature.identity_method}`, `  Event number in Tower's signing log: ${signature.event_seq}`, `Your copy: cockpit agreements copy ${agreement.request_id} --out <file>`);
+    }
+    else if (agreement.status === "open") {
+        lines.push(`Sign it in Tower in your browser: ${dashboardUrl}/agreements/${agreement.request_id}`);
+    }
+    else {
+        lines.push("This request was cancelled. Nothing was signed.");
+    }
+    return lines;
+}
+function flagWords(doc) {
+    const flags = [doc.needs_countersign ? "needs a countersignature" : "", doc.required_for_access ? "required for Tower access" : "", doc.needs_handwritten_confirmation ? "needs a handwritten confirmation" : ""].filter(Boolean);
+    return flags.length > 0 ? ` (${flags.join("; ")})` : "";
+}
+/** `cockpit agreements documents`: each document, its versions, and who was asked to sign each. */
+export function documentLines(doc) {
+    const lines = [`${doc.title} [${doc.slug}]${flagWords(doc)}`, `  document ${doc.document_id}`];
+    if (doc.versions.length === 0)
+        lines.push("  No versions yet.");
+    for (const version of doc.versions) {
+        const state = version.published_at ? `published ${version.published_at.slice(0, 10)}` : "draft, not published";
+        const boxes = version.consent_boxes.length === 0 ? "no boxes" : `${version.consent_boxes.length} box${version.consent_boxes.length === 1 ? "" : "es"}`;
+        lines.push(`  ${version.label} (${version.language}): ${state}, ${boxes}`, `    version ${version.version_id}`);
+        for (const asked of version.requests) {
+            const who = asked.signer_name ?? asked.signer_user_id;
+            const due = asked.status === "open" && asked.due_at ? `, due ${asked.due_at.slice(0, 10)}` : "";
+            lines.push(`    - ${who}: ${asked.status}${due} (request ${asked.request_id})`);
+        }
+    }
+    return lines;
+}

package/dist/commands/agreements.js

@@ -0,0 +1,196 @@
+/**
+ * `cockpit agreements` (docs/architecture/agreements.md): agreements to sign, from the terminal.
+ *
+ * Plain words: a founder publishes a document as a fixed version and asks named people to sign it. Each person reads it
+ * and signs in Tower in their browser; this command reads their own requests and the signed copy, and lets a founder
+ * draft a document, ask someone to sign a published version, or cancel a request.
+ *
+ * Seven verbs, each one `/api/agreements` door on this machine's device token, the same doors the web page, the MCP
+ * twins (`agreements_*`) and JARVIS use. The door's own words are printed; `--json` carries the raw body on stdout and
+ * nothing else. A draft arrives as JSON on stdin. There is deliberately no verb to ask for a signing code, to sign, or
+ * to publish: those are a person's own act in the browser, and their doors refuse a device token (founders, 2026-10-28).
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, fetchAgentDoorFile, openAgentDoor } from "./agent-door.js";
+import { agreementLines, documentLines, rowLines } from "./agreements-render.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[agreements cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 55_000;
+/** A document's text is at most 200,000 characters (`MAX_BODY_CHARS`); the boxes and names ride on top. */
+const DRAFT_MAX_CHARS = 300_000;
+export async function runAgreements(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("agreements", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    switch (command.action) {
+        case "list": return list(door);
+        case "show": return show(command, door);
+        case "copy": return copy(command, door);
+        case "documents": return documents(door);
+        case "draft": return draft(door);
+        case "request": return request(command, door);
+        case "cancel": return cancel(command, door);
+    }
+}
+async function list(door) {
+    const answer = await askAgentDoor(door, { path: "/api/agreements", method: "GET", label: "agreements list", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const open = body.agreements.filter((row) => row.status === "open").length;
+    writeLine(door.io.stderr, `${TAG} list answered ${JSON.stringify({ returned: body.agreements.length, open })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const out = door.io.stdout;
+    if (body.agreements.length === 0) {
+        writeLine(out, "Nothing to sign, and nothing signed yet.");
+        return 0;
+    }
+    writeLine(out, open === 0 ? "Nothing is waiting for your signature." : `${open} waiting for your signature.`);
+    for (const row of body.agreements) {
+        writeLine(out, "");
+        for (const line of rowLines(row))
+            writeLine(out, line);
+    }
+    return 0;
+}
+async function show(command, door) {
+    const id = command.requestId ?? "";
+    const answer = await askAgentDoor(door, { path: `/api/agreements/${encodeURIComponent(id)}`, method: "GET", label: "agreements show", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} show answered ${JSON.stringify({ request_id: body.agreement.request_id, status: body.agreement.status, boxes: body.agreement.consent_boxes.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    for (const line of agreementLines(body.agreement, door.dashboardUrl))
+        writeLine(door.io.stdout, line);
+    return 0;
+}
+/** The signed copy, as the door wrote it: to `--out`, or on stdout. Only a signed agreement has one. */
+async function copy(command, door) {
+    const id = command.requestId ?? "";
+    const answer = await fetchAgentDoorFile(door, { path: `/api/agreements/${encodeURIComponent(id)}/copy`, label: "agreements copy", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const text = answer.bytes.toString("utf8");
+    if (!command.outPath) {
+        writeLine(door.io.stderr, `${TAG} copy answered ${JSON.stringify({ request_id: id, bytes: answer.bytes.length, written: false })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, request_id: id, filename: answer.filename, text });
+        door.io.stdout.write(text);
+        return 0;
+    }
+    const target = path.resolve(command.outPath);
+    try {
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, answer.bytes);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return failAgentDoor(door, TAG, "copy_write_failed", `Could not write ${target}: ${detail}`);
+    }
+    writeLine(door.io.stderr, `${TAG} copy answered ${JSON.stringify({ request_id: id, bytes: answer.bytes.length, written: true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, request_id: id, path: target, bytes: answer.bytes.length });
+    writeLine(door.io.stdout, `Saved your signed copy: ${target}`);
+    return 0;
+}
+async function documents(door) {
+    const answer = await askAgentDoor(door, { path: "/api/agreements/documents", method: "GET", label: "agreements documents", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} documents answered ${JSON.stringify({ documents: body.documents.length, versions: body.documents.reduce((sum, doc) => sum + doc.versions.length, 0) })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    if (body.documents.length === 0) {
+        writeLine(door.io.stdout, "No documents yet. Draft one with `cockpit agreements draft` (the JSON on stdin).");
+        return 0;
+    }
+    for (const doc of body.documents) {
+        for (const line of documentLines(doc))
+            writeLine(door.io.stdout, line);
+        writeLine(door.io.stdout, "");
+    }
+    return 0;
+}
+async function draft(door) {
+    const piped = await readJsonObject(door);
+    if (!piped.ok)
+        return failAgentDoor(door, TAG, piped.reason, piped.detail);
+    const answer = await askAgentDoor(door, { path: "/api/agreements/documents", method: "POST", label: "agreements draft", timeoutMs: WRITE_DEADLINE_MS, body: piped.value });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} draft saved ${JSON.stringify({ document_id: body.document_id, version_id: body.version_id })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const out = door.io.stdout;
+    writeLine(out, "Saved the draft. Nobody can sign it until a founder publishes it.");
+    writeLine(out, `  document ${body.document_id}`);
+    writeLine(out, `  version  ${body.version_id}`);
+    writeLine(out, "Publishing is done in Tower in your browser, where a founder reads the text and confirms it.");
+    return 0;
+}
+async function request(command, door) {
+    const requestBody = { version_id: command.versionId, signer_user_id: command.personId, ...(command.dueAt ? { due_at: command.dueAt } : {}) };
+    const answer = await askAgentDoor(door, { path: "/api/agreements/requests", method: "POST", label: "agreements request", timeoutMs: WRITE_DEADLINE_MS, body: requestBody });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} request created ${JSON.stringify({ request_id: body.request_id, due: Boolean(command.dueAt) })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    writeLine(door.io.stdout, body.message ?? "Asked.");
+    writeLine(door.io.stdout, `  request ${body.request_id}`);
+    return 0;
+}
+async function cancel(command, door) {
+    const id = command.requestId ?? "";
+    const answer = await askAgentDoor(door, { path: `/api/agreements/requests/${encodeURIComponent(id)}/cancel`, method: "POST", label: "agreements cancel", timeoutMs: WRITE_DEADLINE_MS, body: {} });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} cancelled ${JSON.stringify({ request_id: body.request_id })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    writeLine(door.io.stdout, body.message ?? "Request cancelled.");
+    return 0;
+}
+/** A JSON object from stdin. A document's text never travels on the command line, and a terminal is refused instead of waited on. */
+async function readJsonObject(door) {
+    if (isInteractiveStdin(door.io)) {
+        return { ok: false, reason: "nothing_piped", detail: "Pipe the draft in as JSON, e.g. `cockpit agreements draft < draft.json`. Nothing was saved." };
+    }
+    let text;
+    try {
+        text = await readPipedText(door.io.stdin, { maxChars: DRAFT_MAX_CHARS, overflowMessage: `The JSON on stdin is limited to ${DRAFT_MAX_CHARS} characters.` });
+    }
+    catch (error) {
+        return { ok: false, reason: "body_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "invalid_json_body", detail: `stdin was not valid JSON (${text.length} characters read). Nothing was saved.` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, reason: "invalid_json_body", detail: "stdin must be one JSON object, like {\"slug\":\"...\",\"title\":\"...\",\"label\":\"v1\",\"body\":\"...\"}. Nothing was saved." };
+    }
+    return { ok: true, value: parsed };
+}

package/dist/commands/books-files.js

@@ -0,0 +1,159 @@
+/**
+ * `cockpit books export|import` (BLI-23711, PR A): a book as a folder, `<dir>/<collection>/<doc_id>.json`, each file
+ * the record's data only, pretty JSON with a trailing newline. That is the layout the Claude artifact export already
+ * writes, so the scripts that read a book's export read Tower's the same way.
+ *
+ * Export walks every collection through the list door (keyset pages of 500). Import reads the same layout and writes
+ * through the batch door, 50 writes (and at most ~3 MB) per batch, keeping doc ids and data unchanged, then prints what
+ * it wrote per collection. A doc id holding a character a file name cannot (`<>:"/\|?*%`, control characters, a
+ * trailing dot or space) is written with that character as %XX, and import decodes it back.
+ */
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+export const BOOK_COLLECTIONS = ["meta", "timeline", "actions", "documents", "meetings", "conversations", "workstreams", "sources", "syncs"];
+const BATCH_WRITES = 50;
+const BATCH_CHARS = 3_000_000;
+const TAG = "[books cli]";
+/** One door call; a refusal keeps the door's own reason and message. */
+export async function booksRequest(door, method, path, label, body) {
+    return askAgentDoor(door, { path, method, label: `books ${label}`, timeoutMs: 60_000, ...(body === undefined ? {} : { body }) });
+}
+// eslint-disable-next-line no-control-regex
+const UNSAFE = /[<>:"/\\|?*%\u0000-\u001f]|[. ]$/g;
+/** A doc id as a file name (without `.json`). Reversible: `%` itself is encoded. */
+export function fileNameFor(docId) {
+    return docId.replace(UNSAFE, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+}
+export function docIdFor(fileName) {
+    return fileName.replace(/%([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/** Keys in a stable order, so two exports of the same book are byte-identical. Values are untouched. */
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]));
+    }
+    return value;
+}
+async function isEmptyOrMissing(dir) {
+    try {
+        return (await readdir(dir)).length === 0;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+}
+export async function exportBook(door, book, dir) {
+    if (!(await isEmptyOrMissing(dir)))
+        return failAgentDoor(door, TAG, "export_dir_not_empty", `${dir} is not empty. Export into a new or empty folder so no old record is mixed in.`);
+    const counts = {};
+    for (const collection of BOOK_COLLECTIONS) {
+        counts[collection] = 0;
+        let after = null;
+        do {
+            const query = new URLSearchParams({ collection, limit: "500" });
+            if (after !== null)
+                query.set("after", after);
+            const answer = await booksRequest(door, "GET", `/api/books/${encodeURIComponent(book)}/records?${query}`, "export");
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail, { collection, written: counts });
+            const page = answer.body;
+            if (page.records.length > 0)
+                await mkdir(join(dir, collection), { recursive: true });
+            for (const record of page.records) {
+                await writeFile(join(dir, collection, `${fileNameFor(record.doc_id)}.json`), `${JSON.stringify(sorted(record.data), null, 2)}\n`, "utf8");
+                counts[collection] += 1;
+            }
+            after = page.next_cursor;
+        } while (after !== null);
+    }
+    const total = Object.values(counts).reduce((sum, n) => sum + n, 0);
+    console.error(`${TAG} exported ${JSON.stringify({ book, total })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, book, dir, counts, total });
+    for (const collection of BOOK_COLLECTIONS)
+        writeLine(door.io.stdout, `${collection}\t${counts[collection]}`);
+    writeLine(door.io.stdout, `Exported ${total} records of ${book} to ${dir}.`);
+    return 0;
+}
+async function readLayout(dir) {
+    const writes = [];
+    const skipped = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !BOOK_COLLECTIONS.includes(entry.name)) {
+            skipped.push(entry.name);
+            continue;
+        }
+        for (const file of (await readdir(join(dir, entry.name))).sort()) {
+            if (!file.endsWith(".json")) {
+                skipped.push(`${entry.name}/${file}`);
+                continue;
+            }
+            const text = (await readFile(join(dir, entry.name, file), "utf8")).replace(/^/, "");
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`${entry.name}/${file} is not valid JSON.`);
+            }
+            writes.push({ op: "put", collection: entry.name, doc_id: docIdFor(file.slice(0, -".json".length)), data, merge: false });
+        }
+    }
+    return { writes, skipped };
+}
+/** Batches of at most 50 writes and ~3 MB, in file order. */
+export function batchesOf(writes) {
+    const batches = [];
+    let current = [];
+    let chars = 0;
+    for (const write of writes) {
+        const size = JSON.stringify(write).length;
+        if (current.length > 0 && (current.length >= BATCH_WRITES || chars + size > BATCH_CHARS)) {
+            batches.push(current);
+            current = [];
+            chars = 0;
+        }
+        current.push(write);
+        chars += size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+export async function importBook(door, book, dir) {
+    let layout;
+    try {
+        layout = await readLayout(dir);
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "import_read_failed", error.message);
+    }
+    const counts = Object.fromEntries(BOOK_COLLECTIONS.map((c) => [c, 0]));
+    const batches = batchesOf(layout.writes);
+    for (const [index, batch] of batches.entries()) {
+        const answer = await booksRequest(door, "POST", `/api/books/${encodeURIComponent(book)}/batch`, "import", { writes: batch });
+        if (!answer.ok) {
+            const failed = answer.body?.index;
+            const at = typeof failed === "number" ? batch[failed] : undefined;
+            return failAgentDoor(door, TAG, answer.reason, `${answer.detail} Batch ${index + 1} of ${batches.length} was not written; earlier batches were.`, { written: counts, ...(at ? { record: `${at.collection}/${at.doc_id}` } : {}) });
+        }
+        for (const write of batch)
+            counts[write.collection] = (counts[write.collection] ?? 0) + 1;
+    }
+    const total = layout.writes.length;
+    console.error(`${TAG} imported ${JSON.stringify({ book, total, batches: batches.length, skipped: layout.skipped.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, book, counts, total, batches: batches.length, skipped: layout.skipped });
+    for (const collection of BOOK_COLLECTIONS)
+        writeLine(door.io.stdout, `${collection}\t${counts[collection]}`);
+    if (layout.skipped.length)
+        writeLine(door.io.stdout, `Skipped (not a collection or not .json): ${layout.skipped.join(", ")}`);
+    writeLine(door.io.stdout, `Imported ${total} records into ${book} in ${batches.length} batches.`);
+    return 0;
+}

package/dist/commands/books-usage.js

@@ -0,0 +1,14 @@
+/** `cockpit books` usage text (BLI-23711), in its own module so the help table can print it without loading the command. */
+export const BOOKS_USAGE = [
+    "Usage: cockpit books list [--json]",
+    "       cockpit books create <book> --title \"<title>\" [--json]                      (founders)",
+    "       cockpit books members list|add|remove <book> [<email or user id>] [--edit] [--json]   (founders)",
+    "       cockpit books ls <book> <collection> [--after <doc_id>] [--limit <1-500>] [--deleted] [--json]",
+    "       cockpit books get <book> <collection> <doc_id> [--deleted] [--json]",
+    "       cockpit books put <book> <collection> <doc_id> [--merge] [--version <n>] [--data '<json>'] [--json]   (data on stdin if no --data)",
+    "       cockpit books delete <book> <collection> <doc_id> [--version <n>] [--json]   (soft: the record is kept)",
+    "       cockpit books batch <book> [--json]                       ({\"writes\": [...]} on stdin, 1 to 50 writes, all or nothing)",
+    "       cockpit books export <book> <dir> [--json]                (<dir>/<collection>/<doc_id>.json)",
+    "       cockpit books import <book> <dir> [--json]                (the export layout, through the batch door)",
+    "Collections: meta, timeline, actions, documents, meetings, conversations, workstreams, sources, syncs.",
+].join("\n");

package/dist/commands/books.js

@@ -0,0 +1,214 @@
+import { emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { booksRequest, exportBook, importBook } from "./books-files.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { BOOKS_USAGE } from "./books-usage.js";
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export { BOOKS_USAGE };
+const ACTIONS = ["list", "create", "members", "ls", "get", "put", "delete", "batch", "export", "import"];
+const BODY_MAX_CHARS = 4_000_000;
+function usage() {
+    throw new Error(BOOKS_USAGE);
+}
+function wholeNumber(raw, min, max) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        usage();
+    const n = Number(raw);
+    if (n < min || n > max)
+        usage();
+    return n;
+}
+export function parseBooksArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--title", "--edit", "--after", "--limit", "--deleted", "--merge", "--version", "--data", "--json", "--home", "--dashboard-url"],
+        valueFlags: ["--title", "--after", "--limit", "--version", "--data", "--home", "--dashboard-url"],
+    });
+    const [action, ...rest] = values.positionals;
+    if (!ACTIONS.includes(action ?? ""))
+        usage();
+    const flags = values.flags;
+    const has = (flag) => flags.has(flag) || values.booleans.has(flag);
+    const allowOnly = (...allowed) => {
+        for (const flag of ["--title", "--edit", "--after", "--limit", "--deleted", "--merge", "--version", "--data"])
+            if (has(flag) && !allowed.includes(flag))
+                usage();
+    };
+    const command = {
+        kind: "books",
+        action: action,
+        json: values.booleans.has("--json"),
+        homeDir: optionalNonEmpty(flags.get("--home")),
+        dashboardUrl: optionalUrl(flags.get("--dashboard-url")),
+    };
+    switch (command.action) {
+        case "list":
+            if (rest.length)
+                usage();
+            allowOnly();
+            return command;
+        case "create": {
+            const title = optionalNonEmpty(flags.get("--title"));
+            if (rest.length !== 1 || !title)
+                usage();
+            allowOnly("--title");
+            return { ...command, book: rest[0], title };
+        }
+        case "members": {
+            const [sub, book, member, ...extra] = rest;
+            if (extra.length || !book || (sub !== "list" && sub !== "add" && sub !== "remove"))
+                usage();
+            if (sub === "list" ? member !== undefined : member === undefined)
+                usage();
+            allowOnly(...(sub === "add" ? ["--edit"] : []));
+            return { ...command, membersAction: sub, book, ...(member === undefined ? {} : { member }), ...(sub === "add" ? { canEdit: values.booleans.has("--edit") } : {}) };
+        }
+        case "ls": {
+            if (rest.length !== 2)
+                usage();
+            allowOnly("--after", "--limit", "--deleted");
+            const limit = wholeNumber(flags.get("--limit"), 1, 500);
+            const after = optionalNonEmpty(flags.get("--after"));
+            return { ...command, book: rest[0], collection: rest[1], ...(after === undefined ? {} : { after }), ...(limit === undefined ? {} : { limit }), deleted: values.booleans.has("--deleted") };
+        }
+        case "get":
+            if (rest.length !== 3)
+                usage();
+            allowOnly("--deleted");
+            return { ...command, book: rest[0], collection: rest[1], docId: rest[2], deleted: values.booleans.has("--deleted") };
+        case "put": {
+            if (rest.length !== 3)
+                usage();
+            allowOnly("--merge", "--version", "--data");
+            const version = wholeNumber(flags.get("--version"), 0, 2_147_483_647);
+            const data = flags.get("--data");
+            return { ...command, book: rest[0], collection: rest[1], docId: rest[2], merge: values.booleans.has("--merge"), ...(version === undefined ? {} : { version }), ...(data === undefined ? {} : { data }) };
+        }
+        case "delete": {
+            if (rest.length !== 3)
+                usage();
+            allowOnly("--version");
+            const version = wholeNumber(flags.get("--version"), 0, 2_147_483_647);
+            return { ...command, book: rest[0], collection: rest[1], docId: rest[2], ...(version === undefined ? {} : { version }) };
+        }
+        case "batch":
+            if (rest.length !== 1)
+                usage();
+            allowOnly();
+            return { ...command, book: rest[0] };
+        case "export":
+        case "import":
+            if (rest.length !== 2)
+                usage();
+            allowOnly();
+            return { ...command, book: rest[0], dir: rest[1] };
+    }
+}
+const seg = (value) => encodeURIComponent(value ?? "");
+async function readJsonInput(io, inline, what) {
+    let text = inline;
+    if (text === undefined) {
+        if (isInteractiveStdin(io))
+            return { ok: false, detail: `Pipe the ${what} as JSON on stdin (or pass --data '<json>').` };
+        text = await readPipedText(io.stdin, { maxChars: BODY_MAX_CHARS, overflowMessage: `The JSON on stdin is limited to ${BODY_MAX_CHARS} characters.` });
+    }
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false, detail: `The ${what} is not valid JSON.` };
+    }
+}
+const TAG = "[books cli]";
+export async function runBooks(command, io) {
+    const door = await openAgentDoor("books", command, io);
+    const book = seg(command.book);
+    const record = `/api/books/${book}/records/${seg(command.collection)}/${seg(command.docId)}`;
+    if (command.action === "export")
+        return exportBook(door, command.book, command.dir);
+    if (command.action === "import")
+        return importBook(door, command.book, command.dir);
+    let answer;
+    switch (command.action) {
+        case "list":
+            answer = await booksRequest(door, "GET", "/api/books", "list");
+            if (answer.ok && !command.json) {
+                const books = answer.body.books;
+                if (books.length === 0)
+                    writeLine(io.stdout, "No books you can open.");
+                for (const b of books)
+                    writeLine(io.stdout, `${b.id}\t${b.access}${b.founder ? " (founder)" : ""}\t${b.title}`);
+                return 0;
+            }
+            break;
+        case "create":
+            answer = await booksRequest(door, "POST", "/api/books", "create", { id: command.book, title: command.title });
+            break;
+        case "members":
+            if (command.membersAction === "list") {
+                answer = await booksRequest(door, "GET", `/api/books/${book}/members`, "members list");
+                if (answer.ok && !command.json) {
+                    for (const m of answer.body.members) {
+                        writeLine(io.stdout, `${m.email ?? m.user_id}\t${m.can_edit ? "edit" : "read"}`);
+                    }
+                    return 0;
+                }
+            }
+            else if (command.membersAction === "add") {
+                answer = await booksRequest(door, "POST", `/api/books/${book}/members`, "members add", { member: command.member, can_edit: command.canEdit === true });
+            }
+            else {
+                answer = await booksRequest(door, "DELETE", `/api/books/${book}/members?member=${seg(command.member)}`, "members remove");
+            }
+            break;
+        case "ls": {
+            const query = new URLSearchParams({ collection: command.collection ?? "" });
+            if (command.after !== undefined)
+                query.set("after", command.after);
+            if (command.limit !== undefined)
+                query.set("limit", String(command.limit));
+            if (command.deleted)
+                query.set("include_deleted", "1");
+            answer = await booksRequest(door, "GET", `/api/books/${book}/records?${query}`, "ls");
+            if (answer.ok && !command.json) {
+                const page = answer.body;
+                for (const r of page.records)
+                    writeLine(io.stdout, `${r.doc_id}\tv${r.version}\t${r.updated_at}${r.deleted_at ? "\tdeleted" : ""}`);
+                if (page.next_cursor)
+                    writeLine(io.stdout, `More: --after ${page.next_cursor}`);
+                return 0;
+            }
+            break;
+        }
+        case "get":
+            answer = await booksRequest(door, "GET", `${record}${command.deleted ? "?include_deleted=1" : ""}`, "get");
+            if (answer.ok && !command.json) {
+                writeLine(io.stdout, JSON.stringify(answer.body.record.data, null, 2));
+                return 0;
+            }
+            break;
+        case "put": {
+            const data = await readJsonInput(io, command.data, "record data");
+            if (!data.ok)
+                return failAgentDoor(door, TAG, "invalid_data", data.detail);
+            answer = await booksRequest(door, "PUT", record, "put", { data: data.value, merge: command.merge === true, ...(command.version === undefined ? {} : { expected_version: command.version }) });
+            break;
+        }
+        case "delete":
+            answer = await booksRequest(door, "DELETE", `${record}${command.version === undefined ? "" : `?expected_version=${command.version}`}`, "delete");
+            break;
+        case "batch": {
+            const body = await readJsonInput(io, undefined, "batch");
+            if (!body.ok)
+                return failAgentDoor(door, TAG, "invalid_batch", body.detail);
+            // A bare array is accepted as the writes list.
+            answer = await booksRequest(door, "POST", `/api/books/${book}/batch`, "batch", Array.isArray(body.value) ? { writes: body.value } : body.value);
+            break;
+        }
+    }
+    if (!answer.ok) {
+        const extra = answer.body && typeof answer.body === "object" ? Object.fromEntries(Object.entries(answer.body).filter(([key]) => key === "current_version" || key === "index")) : {};
+        return failAgentDoor(door, TAG, answer.reason, answer.detail, extra);
+    }
+    return emitAgentDoor(door, answer.body);
+}

package/dist/commands/docs-share.js

@@ -1,13 +1,13 @@
 /**
- * `cockpit docs share` and `cockpit docs access` — named page editors from a terminal (BLI-21313).
+ * `cockpit docs share` and `cockpit docs access` — the named people on a page, from a terminal (BLI-21313, BLI-23558).
  * A sibling of `docs.ts`, like `docs-notion.ts`.
  *
- * `access <id|slug>`                      → `GET    /api/docs/documents/[id]/grants`
- * `share <id|slug> --add <email>`         → `POST   /api/docs/documents/[id]/grants`
- * `share <id|slug> --remove <email>`      → `DELETE /api/docs/documents/[id]/grants`
+ * `access <id|slug>`                                    → `GET    /api/docs/documents/[id]/grants`
+ * `share <id|slug> --add <email> [--role viewer|editor]` → `POST   /api/docs/documents/[id]/grants`
+ * `share <id|slug> --remove <email>`                    → `DELETE /api/docs/documents/[id]/grants`
  *
  * The door answers with the shared permission explanation, and every refusal keeps its own reason
- * label verbatim (`private_page_grant_needs_decision`, `not_grant_manager`, `person_not_found`, ...).
+ * label verbatim (`not_grant_manager`, `person_not_found`, `grantee_is_author`, ...).
  * A person is an exact email; the server resolves it, so this file never guesses who someone is.
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
@@ -31,6 +31,8 @@ function printPermission(door, permission) {
         writeLine(door.io.stdout, line);
     for (const editor of permission.editors)
         writeLine(door.io.stdout, `  editor: ${editor.display_name}${editor.email ? ` <${editor.email}>` : ""}`);
+    for (const viewer of permission.viewers ?? [])
+        writeLine(door.io.stdout, `  viewer: ${viewer.display_name}${viewer.email ? ` <${viewer.email}>` : ""}`);
 }
 export async function accessDocs(command, door) {
     const target = await resolveOrFail(command, door);
@@ -45,12 +47,12 @@ export async function accessDocs(command, door) {
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
-    writeLine(door.io.stderr, `${TAG} access ${JSON.stringify({ document_id: target.id, role: body.permission.role, editors: body.permission.editors.length })}`);
+    writeLine(door.io.stderr, `${TAG} access ${JSON.stringify({ document_id: target.id, role: body.permission.role, editors: body.permission.editors.length, viewers: (body.permission.viewers ?? []).length })}`);
     if (door.json)
         return emitAgentDoor(door, { ok: true, ...body });
     printPermission(door, body.permission);
     for (const event of body.events ?? []) {
-        writeLine(door.io.stdout, `  ${event.created_at}: ${event.actor_name} ${event.action === "granted" ? "added" : "removed"} ${event.grantee_name}`);
+        writeLine(door.io.stdout, `  ${event.created_at}: ${event.actor_name} ${event.action === "granted" ? "added" : "removed"} ${event.grantee_name}${event.role ? ` (${event.role})` : ""}`);
     }
     return 0;
 }
@@ -64,18 +66,26 @@ export async function shareDocs(command, door) {
         method: adding ? "POST" : "DELETE",
         label: adding ? "docs share add" : "docs share remove",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: { person: adding ? command.addPerson : command.removePerson, ...(command.reason ? { reason: command.reason } : {}) },
+        body: {
+            person: adding ? command.addPerson : command.removePerson,
+            ...(adding && command.shareRole ? { role: command.shareRole } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
-    writeLine(door.io.stderr, `${TAG} share ${JSON.stringify({ document_id: target.id, action: adding ? "add" : "remove", outcome: body.outcome, reason: body.reason, request_id: body.request_id })}`);
+    writeLine(door.io.stderr, `${TAG} share ${JSON.stringify({ document_id: target.id, action: adding ? "add" : "remove", outcome: body.outcome, reason: body.reason, role: body.role ?? null, request_id: body.request_id })}`);
     if (door.json)
         return emitAgentDoor(door, { ok: true, ...body });
     const person = adding ? command.addPerson : command.removePerson;
+    const role = body.role ?? command.shareRole ?? "editor";
+    const aRole = `${role === "editor" ? "an" : "a"} ${role}`;
     writeLine(door.io.stdout, body.outcome === "unchanged"
-        ? `Nothing changed: ${person} ${adding ? "is already an editor" : "was not an editor"}.`
-        : `${adding ? "Added" : "Removed"} ${person} ${adding ? "as an editor of" : "from the editors of"} ${target.id}.`);
+        ? `Nothing changed: ${person} ${adding ? `is already ${aRole}` : "was not named on this page"}.`
+        : body.reason === "role_changed"
+            ? `Changed ${person} to ${role} on ${target.id}.`
+            : `${adding ? "Added" : "Removed"} ${person} ${adding ? `as ${aRole} of` : "from"} ${target.id}.`);
     printPermission(door, body.permission);
     return 0;
 }

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

@@ -0,0 +1,80 @@
+/**
+ * `cockpit agreements` argument parsing (docs/architecture/agreements.md).
+ *
+ *   cockpit agreements [list]                                   your own requests to sign: open, signed, cancelled
+ *   cockpit agreements show <request-id>                        the text, its boxes, and the record once signed
+ *   cockpit agreements copy <request-id> [--out <file>]         your signed copy as plain text
+ *   cockpit agreements documents                                founders: every document, its versions and who was asked
+ *   cockpit agreements draft                                    founders: save a draft (the DraftInput JSON on stdin)
+ *   cockpit agreements request --version <id> --person <user-id> [--due <date>]    founders: ask a person to sign
+ *   cockpit agreements cancel <request-id>                      founders: withdraw a request that is not signed
+ *
+ * Every verb is one `/api/agreements` door on this machine's device token, the same doors the web page, the MCP twins
+ * and JARVIS use. Asking for a signing code, signing and publishing have no verb: they are a person's own act in the
+ * browser, and those doors refuse a device token.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ID_EXAMPLE = "8f14e45f-ceea-467a-9575-1d3a4e7b2c10";
+const ONE_VERB = "agreements takes one verb: list, show, copy, documents, draft, request or cancel. Example: `cockpit agreements` or `cockpit agreements show <request-id>`.";
+/** Which flags each verb owns, so a flag on the wrong verb is refused by name rather than ignored. */
+const FLAGS_BY_ACTION = {
+    list: [],
+    show: [],
+    copy: ["--out"],
+    documents: [],
+    draft: [],
+    request: ["--version", "--person", "--due"],
+    cancel: [],
+};
+const OWN_FLAGS = ["--out", "--version", "--person", "--due"];
+const COMMON_FLAGS = ["--home", "--dashboard-url", "--json"];
+const NEEDS_REQUEST_ID = ["show", "copy", "cancel"];
+export function parseAgreementsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [...OWN_FLAGS, ...COMMON_FLAGS],
+        valueFlags: [...OWN_FLAGS, "--home", "--dashboard-url"],
+    });
+    const first = values.positionals[0];
+    if (first !== undefined && !Object.keys(FLAGS_BY_ACTION).includes(first))
+        throw new Error(ONE_VERB);
+    const action = (first ?? "list");
+    const given = [...values.flags.keys()].filter((flag) => OWN_FLAGS.includes(flag));
+    const owned = FLAGS_BY_ACTION[action];
+    const stray = given.find((flag) => !owned.includes(flag));
+    if (stray)
+        throw new Error(`${stray} does not belong to \`cockpit agreements ${action}\`.`);
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    const needsId = NEEDS_REQUEST_ID.includes(action);
+    if (needsId ? rest.length !== 1 : rest.length > 0) {
+        throw new Error(needsId ? `\`cockpit agreements ${action}\` takes exactly one request id.` : `\`cockpit agreements ${action}\` takes no positional arguments.`);
+    }
+    const requestId = needsId ? rest[0] : undefined;
+    if (requestId !== undefined && !ID.test(requestId))
+        throw new Error(`A request id looks like ${ID_EXAMPLE} (\`cockpit agreements\` lists yours).`);
+    const versionId = optionalNonEmpty(values.flags.get("--version"));
+    const personId = optionalNonEmpty(values.flags.get("--person"));
+    const dueAt = optionalNonEmpty(values.flags.get("--due"));
+    if (action === "request") {
+        if (!versionId || !personId)
+            throw new Error("`cockpit agreements request` needs --version <version-id> and --person <user-id> (`cockpit agreements documents` lists both).");
+        if (!ID.test(versionId))
+            throw new Error(`--version looks like ${ID_EXAMPLE} (\`cockpit agreements documents\` lists the versions).`);
+        if (!ID.test(personId))
+            throw new Error(`--person is a user id like ${ID_EXAMPLE} (\`cockpit team members\` lists them).`);
+        if (dueAt !== undefined && Number.isNaN(Date.parse(dueAt)))
+            throw new Error("--due wants a date, like 2026-11-15.");
+    }
+    return {
+        kind: "agreements",
+        action,
+        ...(requestId ? { requestId } : {}),
+        ...(optionalNonEmpty(values.flags.get("--out")) ? { outPath: optionalNonEmpty(values.flags.get("--out")) } : {}),
+        ...(versionId ? { versionId } : {}),
+        ...(personId ? { personId } : {}),
+        ...(dueAt ? { dueAt } : {}),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}

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

@@ -47,6 +47,7 @@ const DOCS_ALLOWED_FLAGS = [
     "--out",
     "--add",
     "--remove",
+    "--role",
     "--reason",
     "--cursor",
     "--before",
@@ -70,6 +71,7 @@ const DOCS_VALUE_FLAGS = [
     "--out",
     "--add",
     "--remove",
+    "--role",
     "--reason",
     "--cursor",
     "--before",
@@ -296,24 +298,34 @@ function parseDocsReadFlags(action, values) {
     return { query, wholeWord, limit, bodies, section, offset };
 }
 /**
- * BLI-21313: `docs share <doc> --add <email> | --remove <email> [--reason <text>]` names or removes a page editor;
- * `docs access <doc>` reads who may edit and why. A person is an exact email address, never a fuzzy name.
+ * BLI-21313, BLI-23558: `docs share <doc> --add <email> [--role viewer|editor] | --remove <email> [--reason <text>]` names
+ * or removes a person on a page (a private page too); `docs access <doc>` reads who may read and edit and why. A person
+ * is an exact email address, never a fuzzy name. `--role` is for `--add` only; absent means editor (what share did
+ * before viewers existed).
  */
 function parseDocsShareFlags(action, values) {
     const addPerson = optionalNonEmpty(values.flags.get("--add"));
     const removePerson = optionalNonEmpty(values.flags.get("--remove"));
+    const role = optionalNonEmpty(values.flags.get("--role"));
     const reason = optionalNonEmpty(values.flags.get("--reason"));
-    if ((addPerson || removePerson || reason) && action !== "share") {
-        throw new Error("--add, --remove and --reason belong to `cockpit docs share`.");
+    if ((addPerson || removePerson || reason || role) && action !== "share") {
+        throw new Error("--add, --remove, --role and --reason belong to `cockpit docs share`.");
     }
+    if (role !== undefined && role !== "viewer" && role !== "editor")
+        throw new Error('docs share --role must be "viewer" or "editor".');
     if (action === "share") {
         if (Boolean(addPerson) === Boolean(removePerson)) {
             throw new Error("docs share needs exactly one of --add <email> or --remove <email>.");
         }
+        if (role && !addPerson)
+            throw new Error("--role goes with --add; --remove takes the person off whatever role they hold.");
         if (reason && reason.length > 200)
             throw new Error("--reason can be at most 200 characters.");
     }
-    return { ...(addPerson ? { addPerson } : {}), ...(removePerson ? { removePerson } : {}), ...(reason ? { reason } : {}) };
+    return {
+        ...(addPerson ? { addPerson } : {}), ...(removePerson ? { removePerson } : {}),
+        ...(role ? { shareRole: role } : {}), ...(reason ? { reason } : {}),
+    };
 }
 /**
  * BLI-21413: `docs trash [--cursor C] [--limit N]`, `docs versions <doc> [--before N] [--limit N] [--version V]`,

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

@@ -50,11 +50,13 @@ export { parseWhoArgs } from "./local-args-tower-who.js";
 export { parsePeopleArgs } from "./local-args-tower-people.js";
 export { parseApprovalsArgs } from "./local-args-tower-approvals.js";
 export { parseDrillsArgs } from "./local-args-tower-drills.js";
+export { parseAgreementsArgs } from "./local-args-tower-agreements.js";
 export { parseManagerArgs } from "./local-args-tower-manager.js";
 export { parseImageArgs } from "./local-args-tower-image.js";
 export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';
 export { parseGlossaryArgs } from "./glossary.js";
+export { parseBooksArgs } from "./books.js";
 export { parseSkillsArgs } from "./skills.js";
 export { parseSpendArgs } from "./spend.js";
 export { parsePushArgs } from "./push.js";

package/dist/commands/local-args.js

@@ -16,6 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseGlossaryArgs } from "./glossary.js";
+import { parseBooksArgs } from "./books.js";
 import { parseSkillsArgs } from "./skills.js";
 import { parseSpendArgs } from "./spend.js";
 import { parsePushArgs } from "./push.js";
@@ -25,7 +26,7 @@ import { parseSlackPrivacyArgs } from "./slack-privacy-args.js";
 import { parseMilestoneArgs } from "./local-args-tower-milestone.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseCiArgs, parseDeliveryArgs, parsePrOutputArgs, parseAiSpendArgs, parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseHitsArgs, parseAiSkillsArgs, parseIntentionsArgs, parseWhoArgs, parsePeopleArgs, parseApprovalsArgs, parseDrillsArgs, parseManagerArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseCiArgs, parseDeliveryArgs, parsePrOutputArgs, parseAiSpendArgs, parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseHitsArgs, parseAiSkillsArgs, parseIntentionsArgs, parseWhoArgs, parsePeopleArgs, parseApprovalsArgs, parseDrillsArgs, parseAgreementsArgs, parseManagerArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } 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
@@ -91,6 +92,7 @@ const COMMAND_PARSERS = new Map([
     ["clean", (_command, rest) => parseCleanArgs(rest)],
     ["sources", (_command, rest) => parseSourcesArgs(rest)],
     ["glossary", (_command, rest) => parseGlossaryArgs(rest)],
+    ["books", (_command, rest) => parseBooksArgs(rest)], // BLI-23711: Client Books
     ["skills", (_command, rest) => parseSkillsArgs(rest)], // BLI-23364 D: the Skill Library
     ["spend", (_command, rest) => parseSpendArgs(rest)],
     ["push", (_command, rest) => parsePushArgs(rest)],
@@ -118,6 +120,7 @@ const COMMAND_PARSERS = new Map([
     ["people", (_command, rest) => parsePeopleArgs(rest)],
     ["approvals", (_command, rest) => parseApprovalsArgs(rest)],
     ["drills", (_command, rest) => parseDrillsArgs(rest)],
+    ["agreements", (_command, rest) => parseAgreementsArgs(rest)],
     ["manager", (_command, rest) => parseManagerArgs(rest)],
     ["image", (_command, rest) => parseImageArgs(rest)],
 ]);

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

@@ -0,0 +1,5 @@
+/**
+ * `cockpit agreements` command shape (docs/architecture/agreements.md), beside `local-command-shapes-approvals.ts` for
+ * the same reason: `local-command-shapes.ts` sits at the readability ceiling.
+ */
+export {};

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

@@ -0,0 +1,24 @@
+/** `cockpit agreements` help (docs/architecture/agreements.md), kept beside the parser in local-args-tower-agreements.ts. */
+export const AGREEMENTS_HELP = [
+    "agreements",
+    [
+        "Usage: cockpit agreements [list] [--dashboard-url <url>] [--json]",
+        "",
+        "  cockpit agreements show <request-id>                   the exact text, its boxes (required or optional), the status, and the record once signed",
+        "  cockpit agreements copy <request-id> [--out <file>]    your signed copy as plain text: the text, then the record. Signed agreements only",
+        "  cockpit agreements documents                           founders: every document, its versions, and who was asked to sign each",
+        "  cockpit agreements draft                               founders: save a draft; the POST /api/agreements/documents body as JSON on stdin",
+        "  cockpit agreements request --version <id> --person <user-id> [--due <date>]    founders: ask a person to sign a published version",
+        "  cockpit agreements cancel <request-id>                 founders: withdraw a request that is not signed",
+        "A founder publishes a document as a fixed version and asks named people to sign it. Your own requests are yours to read; only the founders read anyone else's.",
+        "Signing is done in Tower in your browser, never here: show prints the link. Asking for a signing code, signing and publishing a version have no CLI verb or MCP tool,",
+        "because an agent holding your token can often read your inbox and could fetch the code and sign, and a published version freezes text people will sign.",
+        "draft JSON: {slug, title, label, language?, body, consent_boxes: [{key, wording, required}], needs_countersign?, required_for_access?, needs_handwritten_confirmation?}",
+        "creates a document; {document_id, label, ...} adds a draft version to it; {version_id, label, ...} edits a draft that is not published.",
+        "--home <dir> and --dashboard-url <url> are for tests and staging.",
+        "--json writes one object to stdout (the door's body) and nothing else; a refusal is { ok: false, error, detail } and exits 1",
+        "(founders_only, not_found, not_open, not_published, already_asked, slug_taken, label_taken, already_published, invalid_input, not_paired, ...).",
+        "Teaching: docs/architecture/agreements.md. The bli-tower MCP server has the twins: agreements_list, agreements_show, agreements_copy, agreements_documents,",
+        "agreements_draft, agreements_request, agreements_cancel.",
+    ],
+];

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

@@ -41,7 +41,7 @@ export const TOWER_OPS_COMMAND_HELP = [
             "project unknown_project, since_exceeds_retention, stored_read_failed, not_paired, ...",
             "--json writes one object to stdout: { ok, kind, source, window, lines, templates[], routine, notes, text, measure };",
             "a refusal is { ok: false, error, detail } and exits 1. Run list and teaching: docs/runbooks/tower-logs.md.",
-            "cockpit logs keys mint|rotate <source> [--json]: super admin only; prints the source ingest key once. Rotation invalidates the old key.",
+            "cockpit logs keys mint|rotate <source> [--json]: admin or developer only; prints the source ingest key once. Rotation invalidates the old key.",
             "cockpit logs search <project> [--since 30m|6h (default 1h) | --from <iso> [--to <iso>]] [--source gcp|supabase|vercel|railway|deploys|db-host|<label>] [--stream api|postgres|auth]",
             "    [--status 500|5xx|500-503] [--method GET] [--route <text>] [--severity error] [--q <text>] [--limit <n>] [--context] [--json]: owner or admin only.",
             "    Reads the project's RAW logs live (window at most 24h), scrubs every line, caps the answer (default 100, at most 200) and says \"capped at N of M\".",
@@ -75,7 +75,7 @@ export const TOWER_OPS_COMMAND_HELP = [
             "Retry: cockpit brain retry <id...> [--all-needs-human] [--project <p>] --reason <text> [--json]",
             "Ids are incident UUIDs or BLI issue identifiers. Retry reopens needs_human or not_actionable rows, resets attempts and claims,",
             "and records who, why and when. --all-needs-human selects only needs_human; --project narrows every selection. Other states are skipped.",
-            "Only members and super admins can retry. One comment is posted per incident issue. MCP twin: brain_retry.",
+            "Only team members (members, developers and owners) can retry. One comment is posted per incident issue. MCP twin: brain_retry.",
             "",
             "Ladder (BLI-19250, the Tower owner only): cockpit brain ladder show|promote <class> [--anyway] [--note <text>]|demote <class>|predict \"<question>\"|answer \"<reply>\" [--json]",
             "Before the brain or an agent asks you for a call it writes down what it predicts you will answer; your answer scores it. `show` lists",
@@ -403,7 +403,7 @@ export const TOWER_OPS_COMMAND_HELP = [
             "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;",
+            "start, dismiss, and undo move one card and are admin or developer actions on every surface;",
             "a refusal is printed as Tower worded it and the board stays readable underneath.",
             "The id can be the first 6 or more characters printed beside each card; an ambiguous",
             "prefix is refused with the candidates rather than acting on the first match.",

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

@@ -20,6 +20,7 @@ import { DOCS_INBOX_HELP } from "./local-help-docs-inbox.js";
 import { DOCS_RECOVERY_HELP } from "./local-help-docs-recovery.js";
 import { PROJECT_HELP } from "./local-help-project.js";
 import { MILESTONE_HELP } from "./local-help-milestone.js";
+import { AGREEMENTS_HELP } from "./local-help-agreements.js";
 import { INBOX_HELP_LINES } from "./local-help-inbox.js";
 import { WORK_NOTIFY_HELP_LINES } from "./local-help-work-notify.js";
 import { VIEWS_HELP_LINES } from "./local-help-views.js";
@@ -76,14 +77,14 @@ export const TOWER_COMMAND_HELP = [
             "  --offset <n> --limit <n> — a character range of the body, instead of the whole thing.",
             "  --json shape: one ref answers { document }, unchanged from before BLI-10450. Several refs answer { documents: [{ ref, ok, document } | { ref, ok: false, error, detail }] }. The meta line (and --json document.revision) shows the page revision. Agent writes are never queued offline: a write that did not reach Tower fails with its reason, and `docs mutation-status <request-id>` tells whether it landed. Pass the revision you read as expected_revision.",
             "read --parent <id>|root --bodies [--limit <n>] — every document filed directly under that parent, bodies included, in ONE call (GET /api/docs/documents?parent_id=...&bodies=true). --limit here caps the DOCUMENT COUNT (1-50), not characters. --json shape: { documents: [{ id, ..., body_markdown }] }.",
-            "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. --json shape: { document }.",
+            "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. A new page is visible to everyone (org) unless you pass --visibility private; a page made with --parent starts with its parent's visibility and a copy of the parent's named people, and the parent's owner joins it as an editor (share it with `cockpit docs share`). --json shape: { document }.",
             "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] [--expected-revision <n>] [--request-id <uuid>] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb. --json shape: { document, mutation }.",
             "  --expected-revision <n> is the page revision you read (`docs read --json` shows document.revision). The save is one atomic step: if someone saved since, nothing is written and you get revision_conflict with the current page (--json: mutation.current). Omit it for an unconditional save. Every save advances the revision.",
             "  --request-id <uuid> makes a retry apply once (minted and printed when absent). Reusing it with different input is request_id_reused. If the response is lost, run `cockpit docs mutation-status <uuid>`, then retry the SAME input with the SAME id.",
             "mutation-status <request-uuid> — your own save receipt: committed (with the stored revision), not_committed (with the reason) or unknown_check_again (no receipt yet; it never proves nothing changed). --json shape: { mutation }.",
             "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
-            "access <id|slug> — who may do what on a page and why, in plain sentences (BLI-21313): your role (author, admin, granted_editor, reader), can_read/can_edit/can_manage, the named editors you may see (the owner and administrators see all; a named editor sees only their own grant), and the grant history for the owner and administrators. The same explanation the page, its versions and its export carry. --json shape: { ok, document_id, permission: { role, can_read, can_edit, can_manage, editors, editors_complete, reasons }, events }.",
-            "share <id|slug> --add <email> | --remove <email> [--reason \"<note>\"] — owner or administrator only. Names (or removes) an editor of an ORGANIZATION page by exact email, never fuzzy. An editor can change the title and text; they cannot change visibility, move, delete or manage editors, and nobody new gains the right to read. A page you made private refuses with private_page_grant_needs_decision (sharing a private page waits for a decision) and nothing is written. Other refusals: not_grant_manager, person_not_found, grantee_is_author, document_not_found_or_unreadable. Adding someone already named, or removing someone not named, answers outcome unchanged. --json shape: { ok, outcome, reason, document_id, grantee_id, request_id, permission }.",
+            "access <id|slug> — who may do what on a page and why, in plain sentences (BLI-21313, BLI-23558): your role (author, admin, granted_editor, granted_viewer, reader), can_read/can_edit/can_manage, the named editors and viewers you may see (on a private page everyone who can open it sees everyone named; on an Everyone page the owner and administrators do, and a named editor sees only their own entry), and the grant history for the owner. An administrator has no special access to a private page: they read it only if the owner named them. The same explanation the page, its versions and its export carry. --json shape: { ok, document_id, permission: { role, can_read, can_edit, can_manage, editors, viewers, editors_complete, reasons }, events }.",
+            "share <id|slug> --add <email> [--role viewer|editor] | --remove <email> [--reason \"<note>\"] — the page owner only (an administrator too, on an Everyone page). Names a person on a page, private or Everyone, by exact email, never fuzzy. --role viewer lets them read it; --role editor (the default) also lets them change its title and text, but not visibility, move, delete or who has access. Adding someone already named with a different role changes their role; --remove takes them off whatever role they hold. Refusals: not_grant_manager, person_not_found, grantee_is_author, invalid_role, document_not_found_or_unreadable. Adding someone already named in that role, or removing someone not named, answers outcome unchanged. --json shape: { ok, outcome, reason, role, document_id, grantee_id, request_id, permission }.",
             "comments <id|slug> [--status open|resolved|all] [--cursor <c>] — the page's discussion (BLI-21701): threads newest activity first, 50 per page, each with its comments (author, time, edited), a \"A comment was deleted by <who> on <when>.\" line for a deleted one, and who resolved a resolved thread. Anyone who can read the page can read it. Ends with the open/resolved counts, a `More: --cursor` line, and a coverage note when some comments could not be read. --json shape: { ok, status, can_comment, counts: { open, resolved }, threads: [{ id, resolved, resolved_at, resolved_by_name, comments: [{ id, author_name, body, created_at, edited_at, deleted, marker, can_edit, can_delete }] }], next_cursor, coverage: exhausted|capped|failed_partial, coverage_note, note }.",
             "comment <id|slug> \"<text>\" | - [--request-id <uuid>] — starts a thread (the text is the second argument, or `-` to read stdin; 1-10,000 characters). Add --reply <thread id> to answer a thread, --edit <comment id> to replace your own comment's text (earlier text is not kept), --delete <comment id> (its author, the page owner or an administrator; a soft delete), --resolve <thread id> or --reopen <thread id>. Exactly one action. Only the page owner, administrators and named editors of an organization page can write; everyone else who can read the page is refused with not_commenter and nothing is written. Other labels, verbatim: not_comment_author, comment_not_found, thread_not_found, invalid_body, document_not_found_or_unreadable. The same --request-id twice gives one comment (outcome unchanged); resolving a resolved thread answers unchanged. --json shape: { ok, outcome, reason, document_id, thread_id, comment_id, request_id }.",
             "delete <id|slug> [<id|slug>...] — soft-deletes one or more documents (BLI-10555): the browser's own delete, sets deleted_at, never a real SQL DELETE. Recoverable: `cockpit docs trash` lists what you may restore and `cockpit docs restore <id>` brings it back (BLI-21413). Deleting a parent does NOT delete its children; they keep their own parent_id and stay exactly where they were. Each ref is one exact lookup, then one DELETE each — one bad ref never loses the rest. --json shape: one ref answers { ok, document_id }; several answer { documents: [{ ref, ok, document_id } | { ref, ok: false, error, detail }] }.",
@@ -220,6 +221,7 @@ export const TOWER_COMMAND_HELP = [
     ],
     PROJECT_HELP,
     MILESTONE_HELP,
+    AGREEMENTS_HELP,
     [
         "speed",
         [
@@ -241,7 +243,7 @@ export const TOWER_COMMAND_HELP = [
             "--seen reads what REAL visits saw instead: per page the visit count, p50 and p95 first-useful milliseconds (the moment",
             "real content showed, from the last-known screen or the fresh one), the share painted from the snapshot, and median HTML",
             "and script transfer. The browser sends one metadata-only beacon per page view; nothing is measured from this machine.",
-            "--since <n>m|h|d is the window (default 24h, at most 30d). --everyone reads every person's visits (super_admin only).",
+            "--since <n>m|h|d is the window (default 24h, at most 30d). --everyone reads other people's visits (only Vee, Jeetesh and Ed; a founder's visits stay with that founder; anyone else is refused everyone_needs_super_admin and still gets their own).",
             "A member sees their own visits. --page limits the table to those pages. The same read is the speed_seen MCP tool.",
         ],
     ],
@@ -256,7 +258,7 @@ export const TOWER_COMMAND_HELP = [
             "--by-client (ticket 19258) shows which app each person worked in (Claude Code CLI, desktop or IDE; Codex CLI, desktop, IDE or exec): the share of sessions and of session time, and the median hours from session start to the pull request opened and merged and the active minutes per merged PR, each with its N, compared only within one person and only with 5 or more sessions on each side. --by-topic adds topic rows, including (unlabelled). Choose only one grouping. --by-repo adds project rows under each person (top 10; --all shows every repo). --person me uses your signed-in email.",
             "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. Every signed-in role sees everyone's numbers (a team decision, BLI-13026); `usage sessions` still lists a member only their own sessions.",
+            "labelled as such and is never actual spend. You see your own numbers; Vee, Jeetesh and Ed also see everyone else's, except a founder's, which only that founder sees (BLI-23585, BLI-23624). When rows were left out the answer says how many people are shown and how many were withheld. `usage sessions` follows the same rule.",
             "--since takes <n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp; --until an ISO timestamp (default now).",
             "--detail adds Output, Input, Cache read and Cache creation. Counts use K/M/B; dollars are rounded.",
             "PRs opened, PRs merged and Commits come from the pull requests Tower mirrors from GitHub, matched to people by GitHub login. n/a means Tower cannot match that person to a login: unknown, not zero. The footer says how many repositories the mirror holds, the range of its pull requests and what matched nobody; --json lists the repositories.",

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

@@ -17,13 +17,15 @@
  * something breaks, so it is a user-visible contract like any other.
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { BOOKS_USAGE } from "./books-usage.js";
 import { localCommandHelp, SURFACE_ALIASES } from "./local-help.js";
 import { TOWER_COMMAND_HELP } from "./local-help-commands-tower.js";
 import { TOWER_OPS_COMMAND_HELP } from "./local-help-commands-tower-ops.js";
 /** One manual per collector command; the Tower nouns are spread in from their own file. */
 const COMMAND_HELP = new Map([
+    ["books", [BOOKS_USAGE, "Client Books: each engagement's record (timeline, actions, documents, meetings, ...). A member of a book reads it; a member with edit access, or a founder, writes it; only founders create books and manage members. put without --merge replaces the record's data; --merge changes only the fields given. --version <n> makes a write conditional: refused as version_conflict when someone changed the record since you read version n (0 = must not exist yet). delete is soft. export writes <dir>/<collection>/<doc_id>.json; import reads that layout and writes 50 records per batch. MCP twins: books_list, books_create, books_members, books_read, books_write, books_batch. Docs: docs/architecture/client-books.md."]],
     ["glossary", ["Usage: cockpit glossary list|add <wrong> --to <name>|remove <wrong> [--json]", "Quote phrases. Removing a form prevents future corrections of it."]],
-    ["skills", ["Usage: cockpit skills library [--weeks <1-52>] [--json] | cockpit skills refresh [--weeks <1-104>] [--json]", "The Skill Library: every agent skill and command our GitHub repos define (name, description, repo, path, versions) with weekly use by person, from the sessions Tower already collects. Uses that match no scanned skill are listed as unmatched, never dropped. The first line is the coverage: repos scanned, skills, invocations matched of total. A member sees their own usage; a super_admin sees everyone's except an owner's. refresh scans the repos and recomputes the weekly totals now (super_admin only; a stale library also refreshes itself when read). MCP twins: skills_library, skills_refresh. Web: TEAM > Skills."]],
+    ["skills", ["Usage: cockpit skills library [--weeks <1-52>] [--json] | cockpit skills refresh [--weeks <1-104>] [--json]", "The Skill Library: every agent skill and command our GitHub repos define (name, description, repo, path, versions) with weekly use by person, from the sessions Tower already collects. Uses that match no scanned skill are listed as unmatched, never dropped. The first line is the coverage: repos scanned, skills, invocations matched of total. You see your own usage; Vee, Jeetesh and Ed see everyone's except a founder's. refresh scans the repos and recomputes the weekly totals now (super_admin only; a stale library also refreshes itself when read). MCP twins: skills_library, skills_refresh. Web: TEAM > Skills."]],
     ["push", ["Usage: cockpit push status | test [--dashboard-url <url>] [--json]", "Phone notifications. status lists your saved devices and whether the server has its push keys; test sends a test push to every saved device. Turn a phone on from Settings on the phone."]],
     ["spend", ["Usage: cockpit spend memory [--days 1|7|30] [--dashboard-url <url>] [--json]", "Spend by memory operation (write, recall, dream, update_forget, backfill, label, exam, predictor, people, who, intentions, salience, chat, other), ranked top first with list and real dollars, share, trend against the previous window, and how much of the real OpenAI bill the ledger explains. What it does not explain is shown as untagged. A super_admin reads it."]],
     ["roots", [
@@ -212,7 +214,7 @@ const COMMAND_HELP = new Map([
             "  cockpit team invite <email> --role <role> [--team-id <uuid>]",
             "      Admin only. Defaults to your own team; Tower emails them a sign-in link.",
             "  cockpit team role <userId> --role <role> [--yes]",
-            "      Admin only. Asks first unless --yes. You cannot change your own role.",
+            "      Admin only. Asks first unless --yes. You cannot change your own role. Making someone an admin or developer works only from a signed-in browser.",
             "  cockpit team grant <person-uuid> careers [see|act] [--json]",
             "  cockpit team revoke <person-uuid> careers [see|act] [--json]",
             "      Super admins manage separate See and Act grants. Default level: see.",
@@ -223,7 +225,7 @@ const COMMAND_HELP = new Map([
             "      (revoked reason, or when it was approved, or that it's still waiting).",
             "      Admin only.",
             "  cockpit team device scope <id|name> notetaker_bot|none [--json]",
-            "      Super admin only. Gives the meeting bot's device the scope Tower's claim door requires,",
+            "      Admin or developer only. Gives the meeting bot's device the scope Tower's claim door requires,",
             "      or takes it away. Without it the bot is refused every meeting (bot_scope_required).",
             "  cockpit team device mark-service <id|name> --reason <label> [--json]",
             "  cockpit team device unmark-service <id|name> [--json]",

package/dist/commands/local-help.js

@@ -76,6 +76,7 @@ export const rootCommandNames = new Set([
     "clean",
     "sources",
     "glossary",
+    "books",
     "skills",
     "spend",
     "push",
@@ -103,6 +104,7 @@ export const rootCommandNames = new Set([
     "people",
     "approvals",
     "drills",
+    "agreements",
     "manager",
     "image",
     ...SURFACE_ALIASES.keys(),
@@ -166,6 +168,7 @@ const COMMAND_SUMMARY_LINES = [
     "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
     "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|followup <id> [--record-sent-at <iso>]|interview <id> <--at <iso>|--clear>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false> --followup-enabled <true|false> --followup-after-days <n> --takehome-window-hours <n>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
     "  cockpit glossary list|add <wrong> --to <name>|remove <wrong> [--dashboard-url <url>] [--json]",
+    "  cockpit books list|create|members|ls|get|put|delete|batch|export|import ... [--dashboard-url <url>] [--json]",
     "  cockpit skills library [--weeks <1-52>] | refresh [--weeks <1-104>] [--dashboard-url <url>] [--json]",
     "  cockpit spend memory [--days 1|7|30] [--dashboard-url <url>] [--json]",
     "  cockpit push status|test [--dashboard-url <url>] [--json]",
@@ -183,6 +186,7 @@ const COMMAND_SUMMARY_LINES = [
     "  cockpit ai-skills [--who <me|team|email|user-id>] [--weeks <n>] [--week <YYYY-MM-DD>] [--dashboard-url <url>] [--json]",
     "  cockpit approvals [list|show <id>|create|approve <id> [--edit]|edit <id> [--approve]|reject <id>|rules [--active true|false]|rules create <card-id> [--any-audience] [--label <text>]|rules revoke <rule-id> [--reason <text>]] [--status <s>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
     "  cockpit drills [list|start|answer --confidence <1-5> [--text <words>] [--attempt <id>]|theme|theme set <theme> [--play <t>] [--watch <t>] [--train <t>]|review] [--dashboard-url <url>] [--json]",
+    "  cockpit agreements [list|show <request-id>|copy <request-id> [--out <file>]|documents|draft|request --version <id> --person <user-id> [--due <date>]|cancel <request-id>] [--dashboard-url <url>] [--json]",
     "  cockpit manager <clients|client <client>|run <run-id>|list <client>|queue <client>|show <id>|add <client> --title <t>|edit <id> --version <v>|done|reopen|link|approve|dismiss|proposal|archive|unarchive> [--timeline] [--dashboard-url <url>] [--json]",
     "  cockpit image <describe <file> [--session <id>]|show <sha256-or-prefix>> [--dashboard-url <url>] [--json]",
     "  cockpit setup [--since <duration|date>] [--until <date>] [--machines] [--details] [--person <name|email>] [--compare <name,name>] [--json]",

package/dist/commands/local.js

@@ -143,6 +143,7 @@ async function runTowerCommand(command, io) {
         case "correct": return await (await import("./correct.js")).runCorrect(command, io);
         case "notes": return await (await import("./notes.js")).runNotes(command, io);
         case "glossary": return await (await import("./glossary.js")).runGlossary(command, io);
+        case "books": return await (await import("./books.js")).runBooks(command, io);
         case "skills": return await (await import("./skills.js")).runSkills(command, io);
         case "sessions-forget": return await (await import("./sessions-forget.js")).runSessionsForget(command, io);
         case "spend": return await (await import("./spend.js")).runSpend(command, io);
@@ -169,6 +170,7 @@ async function runTowerCommand(command, io) {
         case "people": return await (await import("./people.js")).runPeople(command, io);
         case "approvals": return await (await import("./approvals.js")).runApprovals(command, io);
         case "drills": return await (await import("./approvals.js")).runDrills(command, io);
+        case "agreements": return await (await import("./agreements.js")).runAgreements(command, io);
         case "manager": return await (await import("./manager.js")).runManager(command, io);
         case "image": return await (await import("./image.js")).runImage(command, io);
     }

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.287");
+    writeLine(io?.stdout ?? process.stdout, "0.2.288");
     return 0;
   }
 

package/dist/commands/settings.js

@@ -132,7 +132,7 @@ async function setSwitch(command, tower, io) {
  *
  * Reading it is open to anybody signed in — the person whose laptop is about to
  * update is entitled to know what it is updating to — and raising it is
- * super_admin, decided on the server. `scripts/publish-public-packages.mjs`
+ * an owner or developer (BLI-22248), decided on the server. `scripts/publish-public-packages.mjs`
  * spends the SET verb after a `--tag latest` publish, which is the whole reason
  * this exists: a fix on npm that no machine installs is not shipped.
  */

package/dist/commands/speed-seen.js

@@ -11,8 +11,8 @@
  * median HTML and script transfer where the browser knew them.
  *
  * The door (`GET /api/speed/seen`) does the counting in the database, on the
- * caller's own row policies: a person sees their own visits; `--everyone` needs
- * a super_admin and is refused for anyone else. stdout is `--json`'s alone;
+ * caller's own row policies: a person sees their own visits; `--everyone` is for the
+ * person-data allow-list (Vee, Jeetesh, Ed) and is refused for anyone else. stdout is `--json`'s alone;
  * every log line goes to stderr, metadata only (counts, a window, a reason).
  */
 import { writeLine } from "./cli-io.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.287",
+  "version": "0.2.288",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.89",
-    "@bli-cockpit/mcp": "0.1.174",
+    "@bli-cockpit/mcp": "0.1.175",
     "@bli-cockpit/telemetry-core": "0.1.95",
     "unpdf": "1.8.1"
   },