@bli-cockpit/cli 0.2.242 → 0.2.243

package/dist/commands/docs-search-args.js

@@ -0,0 +1,79 @@
+/**
+ * The docs-search flags shared by `cockpit docs search` and `cockpit search --kind doc` (BLI-21697, docs parity
+ * step 6): `--title-only`, `--word`, `--by <me|email|id>`, `--under <id|slug>`, `--since` / `--until`
+ * (`YYYY-MM-DD`, inclusive local days on `updated_at`), `--timezone <IANA>` and `--sort relevance|updated`. One
+ * reader and one query-string writer, so the two commands cannot mean different things. The door checks the
+ * values; this file only checks shape.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const DOC_SEARCH_VALUE_FLAGS = ["--by", "--under", "--sort"];
+export const DOC_SEARCH_BOOLEAN_FLAGS = ["--title-only", "--word"];
+/** Flags only a docs search reads (`--since`, `--until` and `--timezone` are shared with the message search). */
+export const DOC_SEARCH_ONLY_FLAGS = [...DOC_SEARCH_VALUE_FLAGS, ...DOC_SEARCH_BOOLEAN_FLAGS];
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+function machineZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+function day(flag, value) {
+    const given = optionalNonEmpty(value);
+    if (given === undefined)
+        return undefined;
+    if (!DAY.test(given))
+        throw new Error(`${flag} takes a day written YYYY-MM-DD, not "${given}".`);
+    return given;
+}
+/** Reads the flags. The machine's IANA zone is sent unless `--timezone` is given. */
+export function readDocSearchFilters(values) {
+    const since = day("--since", values.flags.get("--since"));
+    const until = day("--until", values.flags.get("--until"));
+    if (since && until && since > until)
+        throw new Error(`--since ${since} is after --until ${until}.`);
+    const sort = optionalNonEmpty(values.flags.get("--sort"));
+    if (sort !== undefined && sort !== "relevance" && sort !== "updated") {
+        throw new Error(`--sort takes relevance or updated, not "${sort}".`);
+    }
+    const by = optionalNonEmpty(values.flags.get("--by"));
+    const under = optionalNonEmpty(values.flags.get("--under"));
+    return {
+        ...(values.booleans.has("--title-only") ? { titleOnly: true } : {}),
+        ...(values.booleans.has("--word") ? { wholeWord: true } : {}),
+        ...(by ? { by } : {}),
+        ...(under ? { under } : {}),
+        ...(since ? { since } : {}),
+        ...(until ? { until } : {}),
+        timezone: optionalNonEmpty(values.flags.get("--timezone")) ?? machineZone(),
+        ...(sort ? { sort } : {}),
+    };
+}
+/** True when a flag that narrows by person, subtree or date was given (an empty query is then allowed). */
+export function hasDocScopeFlags(filters) {
+    return Boolean(filters.by || filters.under || filters.since || filters.until);
+}
+/** True when any docs-only flag was given (so `cockpit search` can refuse them without `--kind doc`). */
+export function hasDocSearchFlags(filters) {
+    return Boolean(filters.titleOnly || filters.wholeWord || filters.sort || hasDocScopeFlags(filters));
+}
+/** The query parameters `GET /api/docs/search` and `GET /api/search` read. */
+export function appendDocSearchParams(params, filters) {
+    if (filters.titleOnly)
+        params.set("title_only", "1");
+    if (filters.wholeWord)
+        params.set("word", "1");
+    if (filters.by)
+        params.set("by", filters.by);
+    if (filters.under)
+        params.set("under", filters.under);
+    if (filters.since)
+        params.set("since", filters.since);
+    if (filters.until)
+        params.set("until", filters.until);
+    if (filters.timezone)
+        params.set("tz", filters.timezone);
+    if (filters.sort)
+        params.set("sort", filters.sort);
+}

package/dist/commands/docs-search.js

@@ -0,0 +1,64 @@
+/**
+ * `cockpit docs search` (BLI-21697, docs parity step 6): the library searched by title or text, narrowed by
+ * person, subtree and day, over `GET /api/docs/search` — the SAME door the web box calls, so the ids match the
+ * browser, MCP `docs_search` and JARVIS `searchDocs`. Nothing is matched on this side.
+ *
+ * It prints the hits, `matched/returned` and the coverage line. A walk that stopped early is said out loud
+ * (`capped`, `failed_partial`), never folded into "nothing matched". A door refusal keeps its own `reason` and
+ * sentence (`invalid_filter` names the bad field).
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { appendDocSearchParams } from "./docs-search-args.js";
+const TAG = "[docs search cli]";
+const READ_DEADLINE_MS = 30_000;
+export function docsSearchPath(command) {
+    const params = new URLSearchParams();
+    if (command.query)
+        params.set("q", command.query);
+    appendDocSearchParams(params, command.searchFilters ?? {});
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    return `/api/docs/search?${params.toString()}`;
+}
+/** The sentence under the hits: the walk's honesty, in words. */
+export function docsSearchCoverageLine(body) {
+    const counts = `${body.returned ?? 0} of ${body.matched ?? 0} shown`;
+    if (body.coverage === "capped")
+        return `Coverage: capped after ${body.searched ?? 0} pages searched; more exist (${counts}).`;
+    if (body.coverage === "failed_partial") {
+        return `Coverage: partial, some pages could not be searched${body.coverage_reason ? ` (${body.coverage_reason})` : ""} (${counts}).`;
+    }
+    return `Coverage: exhausted (${counts}).`;
+}
+export async function searchDocs(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: docsSearchPath(command),
+        method: "GET",
+        label: "docs search",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, body);
+    const results = body.results ?? [];
+    if (results.length === 0) {
+        writeLine(door.io.stdout, body.coverage === "exhausted" || body.coverage === undefined
+            ? "Nothing you can read matches that."
+            : "Nothing in the pages searched matches that.");
+    }
+    for (const result of results) {
+        writeLine(door.io.stdout, `${result.title}  (${result.slug ?? result.id})`);
+        const where = result.matched_in ? `matched in ${result.matched_in}  ·  ` : "";
+        writeLine(door.io.stdout, `  ${where}${result.id}  ·  updated ${result.updated_at}`);
+        if (result.snippet)
+            writeLine(door.io.stdout, `  ${result.snippet}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${body.returned ?? results.length}/${body.matched ?? results.length} matched/returned.`);
+    writeLine(door.io.stdout, docsSearchCoverageLine(body));
+    console.error(`${TAG} searched`, JSON.stringify({ matched: body.matched ?? 0, returned: results.length, coverage: body.coverage ?? "unknown" }));
+    return 0;
+}

package/dist/commands/docs-sync-args.js

@@ -0,0 +1,82 @@
+/**
+ * `cockpit docs sync-resolve|manifest` argument parsing (BLI-21875, docs parity step 12). `sync-status` keeps its parser in
+ * `local-args-tower-docs-msg.ts`; its single-page answer gained detail, not flags.
+ *
+ *   sync-resolve <id|slug> --version <id> --keep-current|--use-kept [--expected-revision N] [--request-id U]
+ *   manifest [--under <id|slug>] [--cursor C] [--all] [--out <file>]
+ *
+ * The door checks authority and the revision; this file only checks shape. It never picks a choice for the person.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--version", "--expected-revision", "--request-id", "--under", "--cursor", "--out"];
+const BOOLEAN_FLAGS = ["--json", "--keep-current", "--use-kept", "--all"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isDocsSyncInvocation(args) {
+    return args[0] === "sync-resolve" || args[0] === "manifest";
+}
+export function parseDocsSyncArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: [...VALUE_FLAGS, ...BOOLEAN_FLAGS], valueFlags: VALUE_FLAGS });
+    const verb = args[0];
+    const rest = values.positionals.slice(1);
+    const base = {
+        kind: "docs",
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    const only = (allowed) => {
+        for (const flag of [...VALUE_FLAGS.slice(2), ...BOOLEAN_FLAGS.slice(1)]) {
+            const given = values.flags.has(flag) || values.booleans.has(flag);
+            if (given && !allowed.includes(flag))
+                throw new Error(`${flag} does not belong to \`cockpit docs ${verb}\`.`);
+        }
+    };
+    if (verb === "manifest") {
+        only(["--under", "--cursor", "--all", "--out"]);
+        if (rest.length !== 0)
+            throw new Error("docs manifest takes no page; use --under <id|slug> for one subtree.");
+        const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+        return {
+            ...base,
+            action: "manifest",
+            ...(cursor ? { cursor } : {}),
+            all: values.booleans.has("--all"),
+            outPath: optionalNonEmpty(values.flags.get("--out")),
+            docsSync: { under: optionalNonEmpty(values.flags.get("--under")) },
+        };
+    }
+    only(["--version", "--keep-current", "--use-kept", "--expected-revision", "--request-id"]);
+    if (rest.length !== 1)
+        throw new Error("docs sync-resolve needs exactly one page id or slug, e.g. `cockpit docs sync-resolve runbook --version <id> --use-kept`.");
+    const keep = values.booleans.has("--keep-current");
+    const useKept = values.booleans.has("--use-kept");
+    if (keep === useKept) {
+        throw new Error("docs sync-resolve needs exactly one choice: --keep-current (keep the page's current text) or --use-kept (make the kept version current). Tower does not choose for you.");
+    }
+    const versionId = optionalNonEmpty(values.flags.get("--version"));
+    if (!versionId || !UUID.test(versionId))
+        throw new Error("docs sync-resolve needs --version <id>, the kept version's id (a UUID from `cockpit docs sync-status <page>`).");
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const revisionRaw = optionalNonEmpty(values.flags.get("--expected-revision"));
+    let expectedRevision;
+    if (revisionRaw !== undefined) {
+        if (keep)
+            throw new Error("--expected-revision belongs with --use-kept: --keep-current writes no text.");
+        expectedRevision = /^\d+$/.test(revisionRaw) ? Number(revisionRaw) : Number.NaN;
+        if (!Number.isInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error("--expected-revision is a positive whole number (the page revision you read).");
+    }
+    return {
+        ...base,
+        action: "sync-resolve",
+        docRef: rest[0],
+        versionId,
+        ...(requestId ? { requestId } : {}),
+        ...(expectedRevision !== undefined ? { expectedRevision } : {}),
+        docsSync: { choice: keep ? "keep_current" : "use_kept_version" },
+    };
+}

package/dist/commands/docs-sync.js

@@ -0,0 +1,197 @@
+/**
+ * `cockpit docs sync-status <page>` detail, `sync-resolve` and `manifest` (BLI-21875): the Notion sync of one page and the
+ * library export manifest, over the same doors the browser calls.
+ *
+ *   sync-status <page>   GET  /api/docs/documents/[id]/notion-sync
+ *   sync-resolve <page>  POST /api/docs/documents/[id]/notion-sync/resolve
+ *   manifest             GET  /api/docs/manifest[?cursor=&under=]
+ *
+ * Every line about a receipt, a loss or a conflict is the door's own `sentence`, printed verbatim, so this terminal says
+ * what the web panel, the MCP tool and JARVIS say. Tower never asks Notion from a request: the answer is what the last
+ * passes recorded, with its age. `manifest` reports readiness; it gives no cutover verdict.
+ */
+import { open } from "node:fs/promises";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[docs sync cli]";
+const READ_DEADLINE_MS = 60_000;
+const WRITE_DEADLINE_MS = 60_000;
+/** 100 calls of 2,000 pages: the most `manifest --all` walks before it says `capped`. */
+const MANIFEST_MAX_CALLS = 100;
+const list = (value) => (Array.isArray(value) ? value : []);
+const str = (value) => (typeof value === "string" ? value : "");
+const num = (value) => (typeof value === "number" ? value : 0);
+const object = (value) => (typeof value === "object" && value !== null ? value : {});
+export async function runDocsSync(command, door) {
+    switch (command.action) {
+        case "sync-resolve": return syncResolve(command, door);
+        case "manifest": return manifest(command, door);
+        default: return failAgentDoor(door, TAG, "invalid_body", "Try sync-status <page>, sync-resolve or manifest.");
+    }
+}
+/** One page's sync status: the list row plus the receipts, losses, conflicts and decisions the door's `detail` carries. */
+export function printSyncDetail(door, ref, body) {
+    const detail = object(body["detail"]);
+    const conflicts = object(detail["conflicts"]);
+    writeLine(door.io.stderr, `${TAG} status ${JSON.stringify({ conflicts: conflicts["total"] ?? null, open: conflicts["open"] ?? null, incomplete: list(detail["incomplete"]).length })}`);
+    const row = list(body["documents"])[0] ?? {};
+    writeLine(door.io.stdout, `${str(row["id"])}  ${str(row["state"])}  ${str(row["slug"]) || "(no slug)"}  ${str(row["title"])}`);
+    writeLine(door.io.stdout, str(detail["state_sentence"]));
+    const receipts = object(detail["last_receipt"]);
+    for (const direction of ["push", "pull"]) {
+        const receipt = object(receipts[direction]);
+        writeLine(door.io.stdout, str(receipt["sentence"]) || `${direction === "push" ? "Push" : "Pull"}: no check recorded for this page yet.`);
+    }
+    const losses = object(detail["losses"]);
+    for (const line of Array.isArray(losses["sentences"]) ? losses["sentences"].map(str) : [])
+        writeLine(door.io.stdout, `Loss: ${line}`);
+    for (const name of Array.isArray(detail["incomplete"]) ? detail["incomplete"].map(str) : []) {
+        writeLine(door.io.stdout, `Could not read just now: ${name}`);
+    }
+    const items = list(conflicts["items"]);
+    for (const item of items) {
+        const resolution = object(item["resolution"]);
+        const status = str(item["status"]) === "open" ? "OPEN    " : "resolved";
+        const decided = str(item["status"]) === "open" ? "" : `  decision: ${str(resolution["choice"])} at ${str(resolution["resolved_at"])}`;
+        writeLine(door.io.stdout, `Conflict ${status}  version ${str(item["version_id"])}  (v${num(item["version_number"])}, kept ${str(item["kept_at"])})  ${str(item["sentence"])}${decided}`);
+    }
+    writeLine(door.io.stdout, `${num(conflicts["total"])} conflict(s) kept, ${num(conflicts["open"])} open; showing the newest ${items.length}. As of ${str(detail["as_of"])}.`);
+    if (num(conflicts["open"]) > 0) {
+        writeLine(door.io.stdout, detail["can_edit"] === true
+            ? `Resolve: cockpit docs sync-resolve ${ref} --version <version id> --keep-current | --use-kept [--expected-revision N]. ${str(detail["resolve_note"])}`
+            : "You can read this page but not edit it, so you cannot resolve its conflicts.");
+    }
+    return 0;
+}
+async function syncResolve(command, door) {
+    const ref = command.docRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(ref)}/notion-sync/resolve`,
+        method: "POST",
+        label: "docs sync-resolve",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            version_id: command.versionId,
+            choice: command.docsSync?.choice,
+            ...(command.expectedRevision !== undefined ? { expected_revision: command.expectedRevision } : {}),
+            ...(command.requestId ? { request_id: command.requestId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} resolve ${JSON.stringify({ outcome: body["outcome"] ?? null, choice: object(body["resolution"])["choice"] ?? null, body_written: body["body_written"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ...body, ok: true });
+    const resolution = object(body["resolution"]);
+    writeLine(door.io.stdout, str(body["outcome"]) === "already_resolved"
+        ? `Already resolved (${str(resolution["choice"])}, ${str(resolution["resolved_at"])}). Nothing was changed.`
+        : `Recorded ${str(resolution["choice"])} for version ${str(resolution["version_id"])}. Page revision now ${String(body["revision"] ?? "unknown")}${body["body_written"] === true ? "; the kept text is now current" : ""}.`);
+    writeLine(door.io.stdout, str(body["note"]));
+    return 0;
+}
+async function manifest(command, door) {
+    const totals = { entries: [], seen: new Set(), requested: 0, returned: 0, failures: [] };
+    let cursor = command.cursor ?? null;
+    let calls = 0;
+    let status = "exhausted";
+    let reason;
+    let nextCursor = null;
+    let under = null;
+    let generatedAt = null;
+    for (;;) {
+        const query = new URLSearchParams();
+        if (cursor)
+            query.set("cursor", cursor);
+        if (command.docsSync?.under)
+            query.set("under", command.docsSync.under);
+        const answer = await askAgentDoor(door, {
+            path: `/api/docs/manifest${query.size > 0 ? `?${query.toString()}` : ""}`,
+            method: "GET",
+            label: "docs manifest",
+            timeoutMs: READ_DEADLINE_MS,
+        });
+        if (!answer.ok) {
+            if (calls === 0)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            // A later call failed: the pages already read are kept, and the cursor resumes after them.
+            status = "failed_partial";
+            reason = answer.reason;
+            nextCursor = cursor;
+            writeLine(door.io.stderr, `${TAG} manifest ${JSON.stringify({ call: calls + 1, reason: answer.reason, kept: totals.entries.length })}`);
+            break;
+        }
+        calls += 1;
+        const page = answer.body;
+        const coverage = object(page["coverage"]);
+        totals.requested += num(page["requested"]);
+        totals.returned += num(page["returned"]);
+        for (const entry of list(page["entries"])) {
+            const id = str(entry["id"]);
+            if (!totals.seen.has(id)) {
+                totals.seen.add(id);
+                totals.entries.push(entry);
+            }
+        }
+        totals.failures.push(...list(page["failures"]));
+        under = page["under"] ?? under;
+        generatedAt = page["generated_at"] ?? generatedAt;
+        nextCursor = typeof page["next_cursor"] === "string" ? page["next_cursor"] : null;
+        status = str(coverage["status"]) || "exhausted";
+        reason = str(coverage["reason"]) || undefined;
+        if (status === "failed_partial" || nextCursor === null || !command.all)
+            break;
+        if (calls >= MANIFEST_MAX_CALLS) {
+            status = "capped";
+            reason = "call_ceiling";
+            break;
+        }
+        cursor = nextCursor;
+    }
+    const result = {
+        ok: true,
+        entries: totals.entries,
+        requested: totals.requested,
+        returned: totals.returned,
+        unique: totals.seen.size,
+        coverage: { status, calls, ...(reason ? { reason } : {}) },
+        coverage_text: `${totals.seen.size} unique pages in ${calls} call(s); requested ${totals.requested}, returned ${totals.returned}; read stopped: ${status}${reason ? ` (${reason})` : ""}.`,
+        failures: totals.failures,
+        next_cursor: status === "exhausted" ? null : nextCursor,
+        under,
+        generated_at: generatedAt,
+    };
+    writeLine(door.io.stderr, `${TAG} manifest ${JSON.stringify({ calls, requested: result.requested, returned: result.returned, unique: result.unique, status, failures: result.failures.length })}`);
+    if (command.outPath) {
+        try {
+            // "wx": never overwrite a file someone already has.
+            const handle = await open(command.outPath, "wx");
+            try {
+                await handle.writeFile(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            return failAgentDoor(door, TAG, code === "EEXIST" ? "out_exists" : "out_write_failed", code === "EEXIST" ? `${command.outPath} already exists; choose another path or remove it.` : `Could not write ${command.outPath}.`);
+        }
+        writeLine(door.io.stderr, `${TAG} manifest written ${JSON.stringify({ entries: result.entries.length })}`);
+    }
+    if (door.json)
+        return emitAgentDoor(door, command.outPath ? { ...result, entries: undefined, written_to: command.outPath, entries_written: result.entries.length } : result, status === "failed_partial" ? 1 : 0);
+    for (const entry of totals.entries.slice(0, command.outPath ? 0 : 200)) {
+        const files = Array.isArray(entry["files"]) ? `${entry["files"].length} file(s)` : "files unknown";
+        writeLine(door.io.stdout, `${str(entry["id"])}  r${num(entry["revision"])}  ${str(entry["visibility"])}  ${files}  ${str(entry["slug"]) || "(no slug)"}  ${str(entry["title"])}`);
+    }
+    if (!command.outPath && totals.entries.length > 200)
+        writeLine(door.io.stdout, `… ${totals.entries.length - 200} more; use --out <file> or --json for all of them.`);
+    writeLine(door.io.stdout, result.coverage_text);
+    for (const failure of totals.failures)
+        writeLine(door.io.stdout, `Failure: ${str(failure["stage"])} ${str(failure["reason"])} (${num(failure["count"])})`);
+    if (result.next_cursor)
+        writeLine(door.io.stdout, `More: cockpit docs manifest --cursor ${result.next_cursor}${command.docsSync?.under ? ` --under ${command.docsSync.under}` : ""}`);
+    writeLine(door.io.stdout, "This reports readiness only. It is not a cutover verdict.");
+    return status === "failed_partial" ? 1 : 0;
+}

package/dist/commands/docs-tree.js

@@ -0,0 +1,136 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { docsListPath, resolveDocId } from "./docs.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+const WALK_MAX_PAGES = 20;
+const PAGE_SIZE = 1000;
+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);
+    }
+}
+function coverageSentence(coverage) {
+    const counts = `requested pages ${coverage.pages}, returned ${coverage.returned}, unique ${coverage.unique}`;
+    if (coverage.status === "exhausted")
+        return `Coverage: exhausted (${counts}).`;
+    if (coverage.status === "capped")
+        return `Coverage: capped at ${coverage.unique} documents; more exist (${counts}).`;
+    return `Coverage: partial, some pages could not load${coverage.reason ? ` (${coverage.reason})` : ""} (${counts}).`;
+}
+export 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 body = answer.body;
+    const tree = body.tree ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, tree, ...(body.coverage ? { coverage: body.coverage } : {}) });
+    if (tree.length === 0) {
+        writeLine(door.io.stdout, "No documents.");
+    }
+    else {
+        renderTree(tree, door.io, 0);
+    }
+    if (body.coverage)
+        writeLine(door.io.stdout, coverageSentence(body.coverage));
+    return 0;
+}
+/** `docs list --all`: walks every `?cursor=` page with the same filters, then prints the receipt. */
+export async function listAllDocs(command, door) {
+    const documents = [];
+    const seen = new Set();
+    let returned = 0;
+    let pages = 0;
+    let cursor;
+    let status = "exhausted";
+    let reason;
+    for (;;) {
+        const path = docsListPath({ ...command, cursor, limit: PAGE_SIZE });
+        const answer = await askAgentDoor(door, { path, method: "GET", label: "docs list", timeoutMs: READ_DEADLINE_MS });
+        if (!answer.ok) {
+            if (pages === 0)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            status = "failed_partial";
+            reason = answer.reason;
+            break;
+        }
+        const body = answer.body;
+        pages += 1;
+        for (const doc of body.documents ?? []) {
+            returned += 1;
+            if (seen.has(doc.id))
+                continue;
+            seen.add(doc.id);
+            documents.push(doc);
+        }
+        if (!body.next_cursor)
+            break;
+        if (pages >= WALK_MAX_PAGES) {
+            status = "capped";
+            reason = "page_ceiling";
+            break;
+        }
+        cursor = body.next_cursor;
+    }
+    const coverage = { status, pages, returned, unique: seen.size, ...(reason ? { reason } : {}) };
+    writeLine(door.io.stderr, `${TAG} list-all ${JSON.stringify(coverage)}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, documents, coverage });
+    for (const doc of documents) {
+        const size = typeof doc.body_chars === "number" ? `${doc.body_chars}c`.padStart(8) : "       ?";
+        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${size}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${documents.length} document(s). ${coverageSentence(coverage)}`);
+    return 0;
+}
+export async function favoriteDocs(command, door) {
+    const on = command.action === "favorite";
+    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)}/favorite`,
+        method: on ? "PUT" : "DELETE",
+        label: on ? "docs favorite" : "docs unfavorite",
+        timeoutMs: WRITE_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    writeLine(door.io.stderr, `${TAG} favorite ${JSON.stringify({ document_id: resolved.id, favorite: on })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document_id: resolved.id, favorite: on });
+    writeLine(door.io.stdout, on ? `Favorited ${resolved.id}.` : `Removed ${resolved.id} from your favorites.`);
+    return 0;
+}
+export async function marksDocs(door) {
+    const answer = await askAgentDoor(door, { path: "/api/docs/marks", method: "GET", label: "docs marks", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const favorites = body.favorites ?? [];
+    const recents = body.recents ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, favorites, recents });
+    const print = (heading, rows) => {
+        writeLine(door.io.stdout, `${heading} (${rows.length})`);
+        for (const row of rows)
+            writeLine(door.io.stdout, `  ${row.id}  ${row.marked_at}  ${row.slug ?? "(no slug)"}  ${row.title}`);
+    };
+    print("Favorites", favorites);
+    print("Recent", recents);
+    return 0;
+}