@bli-cockpit/cli 0.2.135 → 0.2.140

package/dist/commands/issue.js

@@ -25,9 +25,10 @@
  * (`agent-door.ts`) — `issue_not_found_or_unreadable`, `invalid_state`,
  * `needs_rls_client`, `comment_too_long`, and so on.
  */
-import { mirroredTicketIdInTitle } from "@bli-cockpit/telemetry-core";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
+import { assigneeLabel, resolveAssigneeDirectory, withAssigneeIdentity } from "./issue-directory.js";
+import { showIssue } from "./issue-show.js";
 import { READ_DEADLINE_MS, TAG, resolveProjectId, } from "./issue-contracts.js";
 import { commentIssue, createIssue, moveIssue, updateIssue } from "./issue-write.js";
 export async function runIssue(command, io) {
@@ -49,8 +50,40 @@ export async function runIssue(command, io) {
             return issueHistory(command, door);
     }
 }
-function issueLine(issue) {
-    return `${issue.identifier.padEnd(9)}  ${issue.state.padEnd(11)}  ${issue.title}`;
+function issueLine(issue, directory) {
+    const assignee = issue.assignee_id ? `  [${assigneeLabel(issue.assignee_id, directory)}]` : "";
+    return `${issue.identifier.padEnd(9)}  ${issue.state.padEnd(11)}  ${issue.title}${assignee}`;
+}
+/**
+ * What the list did not show (BLI-10447): a capped window of a larger set,
+ * and sub-issues of the listed issues that live outside the named project.
+ * A door too old to say anything is judged by whether the read filled its limit.
+ */
+export function listGapLines(body, requestedLimit) {
+    const lines = [];
+    const returned = body.issues?.length ?? 0;
+    const completeness = body.completeness;
+    if (completeness?.status === "partial") {
+        lines.push(`${TAG} partial list: ${completeness.returned} of ${completeness.total} matching issues; narrow the filter or pass --limit (at most 1000).`);
+    }
+    else if (completeness?.status === "unknown") {
+        lines.push(`${TAG} list may be partial: ${completeness.returned} issues filled the limit and Tower could not count the rest.`);
+    }
+    else if (!completeness && returned >= requestedLimit) {
+        lines.push(`${TAG} list may be partial: ${returned} issues filled the limit and this Tower did not say whether more exist.`);
+    }
+    const outside = body.outside_project;
+    if (outside && outside.issues.length > 0) {
+        lines.push(`${TAG} ${outside.issues.length} sub-issue(s) of these issues sit outside the project:`);
+        for (const issue of outside.issues) {
+            lines.push(`  ${issue.identifier} (under ${issue.parent_identifier ?? "?"}, ${issue.project_id ? `project ${issue.project_id}` : "no project"})  ${issue.title}`);
+        }
+    }
+    if (outside?.status === "capped")
+        lines.push(`${TAG} the sub-issue check was capped; more may sit outside the project.`);
+    if (outside?.status === "failed")
+        lines.push(`${TAG} could not check for sub-issues outside the project (read_failed).`);
+    return lines;
 }
 async function listIssues(command, door) {
     const query = new URLSearchParams();
@@ -78,83 +111,33 @@ async function listIssues(command, door) {
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const issues = answer.body.issues ?? [];
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, issues });
+    const body = answer.body;
+    const issues = body.issues ?? [];
+    // BLI-10447: the gaps go to stderr in both modes, so `--json` stdout stays one object.
+    for (const line of listGapLines(body, command.limit ?? 1000))
+        writeLine(door.io.stderr, line);
+    // BLI-10450: one extra call for the whole list, never one per row — the
+    // uuid `assignee_id` alone forced a second `cockpit team members` call and
+    // a join done by hand to answer "who owns what".
+    const directory = await resolveAssigneeDirectory(door, issues.map((issue) => issue.assignee_id));
+    if (door.json) {
+        return emitAgentDoor(door, {
+            ok: true,
+            issues: issues.map((issue) => withAssigneeIdentity(issue, directory)),
+            ...(body.completeness ? { completeness: body.completeness } : {}),
+            ...(body.outside_project ? { outside_project: body.outside_project } : {}),
+        });
+    }
     if (issues.length === 0) {
         writeLine(door.io.stdout, "No issues match that.");
         return 0;
     }
     for (const issue of issues)
-        writeLine(door.io.stdout, issueLine(issue));
+        writeLine(door.io.stdout, issueLine(issue, directory));
     writeLine(door.io.stdout, "");
     writeLine(door.io.stdout, `${issues.length} issue(s).`);
     return 0;
 }
-async function showIssue(command, door) {
-    const ref = command.issueRef ?? "";
-    const answer = await askAgentDoor(door, {
-        path: `/api/work/issues/${encodeURIComponent(ref)}`,
-        method: "GET",
-        label: "issue show",
-        timeoutMs: READ_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const issue = answer.body.issue;
-    if (!issue) {
-        return failAgentDoor(door, TAG, "issue_not_found_or_unreadable", `That issue does not exist, or you cannot read it: ${ref}`);
-    }
-    // A comment read that fails does NOT fail the whole `show` — the issue is
-    // already in hand, and a named gap beats losing what was read.
-    const commentsAnswer = await askAgentDoor(door, {
-        path: `/api/work/issues/${encodeURIComponent(issue.id)}/comments`,
-        method: "GET",
-        label: "issue show comments",
-        timeoutMs: READ_DEADLINE_MS,
-    });
-    const comments = commentsAnswer.ok
-        ? (commentsAnswer.body.comments ?? [])
-        : [];
-    if (!commentsAnswer.ok) {
-        writeLine(door.io.stderr, `${TAG} comments unread ${JSON.stringify({ reason: commentsAnswer.reason, issue_id: issue.id })}`);
-    }
-    // BLI-3779: during the dual-run a Tower-native row stands for a Linear
-    // ticket, and says so in its own title (`… [BLI-3779]`). Read it out rather
-    // than making every caller parse the title — `cockpit start --ticket` binds
-    // a session to both ids, and this is where a person checks which they are.
-    const linearTicketId = mirroredTicketIdInTitle(issue.title ?? "");
-    if (door.json) {
-        return emitAgentDoor(door, {
-            ok: true,
-            issue,
-            comments,
-            ...(linearTicketId ? { linear_ticket_id: linearTicketId } : {}),
-            ...(commentsAnswer.ok ? {} : { comments_unread_reason: commentsAnswer.reason }),
-        });
-    }
-    writeLine(door.io.stdout, `${issue.identifier}  ${issue.title}`);
-    writeLine(door.io.stdout, `${issue.state}  ·  priority ${issue.priority ?? 0}  ·  assignee ${issue.assignee_id ?? "(nobody)"}  ·  updated ${issue.updated_at}`);
-    writeLine(door.io.stdout, `id ${issue.id}${issue.parent_id ? `  ·  parent ${issue.parent_id}` : ""}`);
-    if (linearTicketId)
-        writeLine(door.io.stdout, `Linear: ${linearTicketId}`);
-    writeLine(door.io.stdout, "");
-    writeLine(door.io.stdout, issue.description ?? "(no description)");
-    if (comments.length > 0) {
-        writeLine(door.io.stdout, "");
-        writeLine(door.io.stdout, `--- ${comments.length} comment(s) ---`);
-        for (const comment of comments) {
-            writeLine(door.io.stdout, "");
-            writeLine(door.io.stdout, `[${comment.created_at}] ${comment.author_name ?? comment.author_id ?? "unknown"}`);
-            writeLine(door.io.stdout, comment.body_markdown);
-        }
-    }
-    else if (commentsAnswer.ok) {
-        writeLine(door.io.stdout, "");
-        writeLine(door.io.stdout, "No comments.");
-    }
-    return 0;
-}
 /**
  * What a history row actually says. A row imported from Linear's issue
  * TIMESTAMPS (created/started/completed/canceled) carries no state names at

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

@@ -157,6 +157,7 @@ export const SLACK_WORKSPACE_KEYS = ["bli", "blue_pearl"];
  * `cockpit slack read [--person|--channel|--query|--since|--until|--limit]`
  * (BLI-3462).
  */
+const SLACK_READ_FORMATS = ["compact", "full"];
 export function parseSlackArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -164,12 +165,15 @@ export function parseSlackArgs(args) {
             "--dashboard-url",
             "--workspace",
             "--stale-only",
+            "--list",
             "--person",
             "--channel",
             "--query",
+            "--word",
             "--since",
             "--until",
             "--limit",
+            "--format",
             "--json",
         ],
         valueFlags: [
@@ -182,6 +186,7 @@ export function parseSlackArgs(args) {
             "--since",
             "--until",
             "--limit",
+            "--format",
         ],
     });
     if (values.positionals.length > 1) {
@@ -196,6 +201,12 @@ export function parseSlackArgs(args) {
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         json: values.booleans.has("--json"),
     };
+    if (values.flags.has("--format") && rawAction !== "read") {
+        throw new Error("--format belongs to `cockpit slack read`.");
+    }
+    if (values.booleans.has("--list") && rawAction !== "coverage") {
+        throw new Error("--list belongs to `cockpit slack coverage`.");
+    }
     if (rawAction === "coverage") {
         // `--workspace` here is a Slack workspace key, NOT the collection-root
         // `--workspace <path>` every setup command takes. Named at the point of use
@@ -209,6 +220,8 @@ export function parseSlackArgs(args) {
             action: "coverage",
             workspace,
             staleOnly: values.booleans.has("--stale-only"),
+            // BLI-10450: counts alone could not answer "is there a Kaiben channel?".
+            list: values.booleans.has("--list"),
             ...base,
         };
     }
@@ -219,15 +232,27 @@ export function parseSlackArgs(args) {
         throw new Error("slack read needs at least one of --person, --channel or --query. An unfiltered dump of every " +
             "message is not something this command offers.");
     }
+    const word = values.booleans.has("--word");
+    if (word && !query) {
+        throw new Error("--word needs --query: it says how the query text is matched.");
+    }
+    const format = optionalNonEmpty(values.flags.get("--format"));
+    if (format && !SLACK_READ_FORMATS.includes(format)) {
+        throw new Error(`slack read --format must be one of ${SLACK_READ_FORMATS.join(", ")}; got ${format}.`);
+    }
     return {
         kind: "slack",
         action: "read",
         person,
         channel,
         query,
+        ...(word ? { word } : {}),
         since: optionalNonEmpty(values.flags.get("--since")),
         until: optionalNonEmpty(values.flags.get("--until")),
         limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit"),
+        // BLI-10450: every result printed twice (a summary, then blocks) — one
+        // rendering now, never both. `full` (default) keeps the detailed blocks.
+        format: format ?? "full",
         ...base,
     };
 }

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

@@ -7,8 +7,11 @@
  * added both without stretching either existing family's own doc comment.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update"]);
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update"]);
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "link", "sync-status"]);
+// BLI-10450: `read` moved to its own branch in `parseDocsDocumentReference` —
+// it takes SEVERAL references now, so it no longer shares the "exactly one"
+// rule `update`/`link` still enforce.
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link"]);
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -22,36 +25,115 @@ export function parseDocsArgs(args) {
             "--file",
             "--body-stdin",
             "--query",
+            "--word",
             "--limit",
+            "--clear",
+            "--bodies",
+            "--section",
+            "--offset",
             "--json",
         ],
-        valueFlags: ["--home", "--dashboard-url", "--title", "--parent", "--visibility", "--file", "--query", "--limit"],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--title",
+            "--parent",
+            "--visibility",
+            "--file",
+            "--query",
+            "--limit",
+            "--section",
+            "--offset",
+        ],
     });
     const { action, rest } = parseDocsAction(values.positionals);
-    const docRef = parseDocsDocumentReference(action, rest);
-    const { visibility, clearParent, parentId, allowEmpty, title, query, limit } = parseDocsFlags(action, values);
-    return buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit);
+    const link = parseDocsLink(action, rest, values.booleans.has("--clear"));
+    const { docRef, docRefs } = parseDocsDocumentReference(action, link.rest);
+    const { visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset } = parseDocsFlags(action, values);
+    if (action === "read")
+        validateDocsReadTargets(docRefs, parentId, bodies);
+    return buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link);
+}
+/**
+ * BLI-10450: `read` takes either several document references OR
+ * `--parent <id> --bodies` (every document filed directly under that
+ * parent, with bodies) — never both, and never neither. Checked once flags
+ * are known, not in `parseDocsDocumentReference`, because "was --bodies
+ * given" decides which of the two empty-input refusals is the right one.
+ */
+function validateDocsReadTargets(docRefs, parentId, bodies) {
+    const hasRefs = Boolean(docRefs && docRefs.length > 0);
+    if (hasRefs && parentId) {
+        throw new Error("docs read takes either document references or --parent --bodies, not both.");
+    }
+    if (bodies && !parentId) {
+        throw new Error("--bodies needs --parent, e.g. `cockpit docs read --parent <id> --bodies`.");
+    }
+    if (parentId && !bodies) {
+        throw new Error("docs read --parent needs --bodies too (or use `cockpit docs list --parent <id>` for metadata only).");
+    }
+    if (!hasRefs && !(parentId && bodies)) {
+        throw new Error("docs read needs one or more document ids/slugs, or --parent <id> --bodies.");
+    }
+}
+/**
+ * BLI-10430: `docs link <id|slug> <notion-url|page-id>` ties a document to a
+ * Notion page; `docs link <id|slug> --clear` unties it. Exactly one of the two:
+ * a link with neither says nothing, and one with both says two things.
+ */
+function parseDocsLink(action, rest, clear) {
+    if (action !== "link") {
+        if (clear)
+            throw new Error("--clear belongs to `cockpit docs link`.");
+        return { rest };
+    }
+    // No document at all: the document-reference check says so, first.
+    if (rest.length === 0)
+        return { rest };
+    const notionPage = optionalNonEmpty(rest[1]);
+    if (clear && notionPage)
+        throw new Error("docs link takes a Notion page OR --clear, not both.");
+    if (!clear && !notionPage) {
+        throw new Error("docs link needs a Notion page URL or id after the document, or --clear to unlink it.");
+    }
+    if (rest.length > 2)
+        throw new Error(`docs link takes a document and a Notion page, not ${rest.length} arguments.`);
+    return { rest: rest.slice(0, 1), ...(notionPage ? { notionPage } : {}), ...(clear ? { clearLink: true } : {}) };
 }
 function parseDocsAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!DOCS_ACTIONS.has(action)) {
-        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, or update.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, link, or sync-status.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
 function parseDocsDocumentReference(action, rest) {
+    // BLI-10450: `read` alone takes several references in one call — an agent
+    // reading a folder's worth of documents used to pay a resolve-then-read
+    // pair PER document. Emptiness is validated later, once `--parent`/
+    // `--bodies` are known (`validateDocsReadTargets`).
+    if (action === "read") {
+        const refs = rest.map((token) => optionalNonEmpty(token)).filter((token) => Boolean(token));
+        return { docRef: refs[0], docRefs: refs.length > 0 ? refs : undefined };
+    }
     if (DOCS_ACTIONS_NEEDING_A_DOC.has(action)) {
         const docRef = optionalNonEmpty(rest[0]);
         if (!docRef)
             throw new Error(`docs ${action} needs a document id or slug.`);
         if (rest.length > 1)
             throw new Error(`docs ${action} takes one document reference, not ${rest.length}.`);
-        return docRef;
+        return { docRef, docRefs: undefined };
+    }
+    // BLI-10430: `sync-status` reports the whole linked library, or one document.
+    if (action === "sync-status") {
+        if (rest.length > 1)
+            throw new Error(`docs sync-status takes at most one document reference, not ${rest.length}.`);
+        return { docRef: optionalNonEmpty(rest[0]), docRefs: undefined };
     }
     if (rest.length > 0)
         throw new Error(`docs ${action} does not take "${rest[0]}".`);
-    return undefined;
+    return { docRef: undefined, docRefs: undefined };
 }
 function parseDocsFlags(action, values) {
     const visibility = optionalNonEmpty(values.flags.get("--visibility"));
@@ -86,19 +168,48 @@ function parseDocsFlags(action, values) {
     if (query && action !== "list") {
         throw new Error("--query belongs to `cockpit docs list`.");
     }
+    const wholeWord = values.booleans.has("--word");
+    if (wholeWord && !query) {
+        throw new Error("--word needs --query: it says how the query text is matched.");
+    }
+    // BLI-10450: `--limit` now also belongs to `read`, where it means two
+    // different things depending on the mode it is used in — a row cap in
+    // `--parent --bodies` mode (matching `list`'s own meaning), or a character
+    // cap when slicing an explicit reference's body. The two modes are mutually
+    // exclusive (`validateDocsReadTargets`), so the flag is never ambiguous in
+    // any one call, only overloaded across the command's two shapes.
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
-    if (limit !== undefined && action !== "list") {
-        throw new Error("--limit belongs to `cockpit docs list`.");
+    if (limit !== undefined && action !== "list" && action !== "read") {
+        throw new Error("--limit belongs to `cockpit docs list` or `cockpit docs read`.");
+    }
+    // BLI-10450: `--bodies` pairs with `--parent` to bulk-read a folder;
+    // `--section`/`--offset` slice an explicit reference's body, mirroring
+    // `cockpit workbook --section`.
+    const bodies = values.booleans.has("--bodies");
+    if (bodies && action !== "read")
+        throw new Error("--bodies belongs to `cockpit docs read`.");
+    const section = optionalNonEmpty(values.flags.get("--section"));
+    if (section && action !== "read")
+        throw new Error("--section belongs to `cockpit docs read`.");
+    const offsetRaw = optionalNonEmpty(values.flags.get("--offset"));
+    let offset;
+    if (offsetRaw !== undefined) {
+        offset = Number(offsetRaw);
+        if (!Number.isInteger(offset) || offset < 0)
+            throw new Error("--offset must be a whole number 0 or greater.");
     }
-    return { visibility, clearParent, parentId, allowEmpty, title, query, limit };
+    if (offset !== undefined && action !== "read")
+        throw new Error("--offset belongs to `cockpit docs read`.");
+    return { visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset };
 }
-function buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit) {
+function buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link) {
     return {
         kind: "docs",
         action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         ...(docRef ? { docRef } : {}),
+        ...(docRefs ? { docRefs } : {}),
         title,
         ...(parentId ? { parentId } : {}),
         clearParent,
@@ -107,7 +218,13 @@ function buildDocsCommand(values, action, docRef, visibility, clearParent, paren
         filePath: optionalNonEmpty(values.flags.get("--file")),
         bodyStdin: values.booleans.has("--body-stdin"),
         ...(query ? { query } : {}),
+        ...(wholeWord ? { wholeWord } : {}),
         ...(limit === undefined ? {} : { limit }),
+        ...(bodies ? { bodies } : {}),
+        ...(section ? { section } : {}),
+        ...(offset === undefined ? {} : { offset }),
+        ...(link.notionPage ? { notionPage: link.notionPage } : {}),
+        ...(link.clearLink ? { clearLink: true } : {}),
         json: values.booleans.has("--json"),
     };
 }

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

@@ -73,14 +73,14 @@ export function parseIssueArgs(args) {
         ],
     });
     const { action, rest } = readIssueAction(values);
-    const { issueRef, moveState } = readIssueReference(action, rest);
+    const { issueRef, issueRefs, moveState } = readIssueReference(action, rest);
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
     const title = readIssueTitle(action, values);
     const priority = readIssuePriority(values);
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
-    return buildIssueCommand(values, action, issueRef, moveState, stateFilter, title, priority, assignee, limit);
+    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, assignee, limit);
 }
 function readIssueAction(values) {
     const first = values.positionals[0];
@@ -92,8 +92,19 @@ function readIssueAction(values) {
 }
 function readIssueReference(action, rest) {
     let issueRef;
+    let issueRefs;
     let moveState;
-    if (ISSUE_ACTIONS_NEEDING_AN_ISSUE.has(action)) {
+    // BLI-10450: `show` alone takes several references in one call — an agent
+    // reading a sprint's worth of tickets used to pay one process per issue.
+    // Every other verb here still names exactly one issue.
+    if (action === "show") {
+        const refs = rest.map((token) => optionalNonEmpty(token)).filter((token) => Boolean(token));
+        if (refs.length === 0)
+            throw new Error("issue show needs one or more issue ids or identifiers, e.g. BLI-3654.");
+        issueRefs = refs;
+        issueRef = refs[0];
+    }
+    else if (ISSUE_ACTIONS_NEEDING_AN_ISSUE.has(action)) {
         issueRef = optionalNonEmpty(rest[0]);
         if (!issueRef)
             throw new Error(`issue ${action} needs an issue id or identifier, e.g. BLI-3654.`);
@@ -112,7 +123,7 @@ function readIssueReference(action, rest) {
     else if (rest.length > 0) {
         throw new Error(`issue ${action} does not take "${rest[0]}".`);
     }
-    return { issueRef, moveState };
+    return { issueRef, issueRefs, moveState };
 }
 function validateIssueState(state, errorPrefix) {
     if (state && !ISSUE_STATES.includes(state)) {
@@ -166,13 +177,14 @@ function readIssueLimit(action, values) {
     }
     return limit;
 }
-function buildIssueCommand(values, action, issueRef, moveState, stateFilter, title, priority, assignee, limit) {
+function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, assignee, limit) {
     return {
         kind: "issue",
         action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         ...(issueRef ? { issueRef } : {}),
+        ...(issueRefs ? { issueRefs } : {}),
         ...(moveState ? { moveState } : {}),
         ...(stateFilter ? { stateFilter } : {}),
         ...(assignee ? { assignee } : {}),

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

@@ -42,18 +42,25 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+            "Usage: cockpit docs [list|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|link <id|slug> <notion-page>|sync-status [<id|slug>]] [flags]",
             "",
             "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
-            "list [--parent <id>|root] [--query <text>] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB).",
+            "list [--parent <id>|root] [--query <text> [--word]] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB). --json shape: { documents: [{ id, slug, title, visibility, parent_id, source, updated_at, body_chars }] }.",
             "  --parent <id> lists the documents filed directly under that document; --parent root lists the top of the tree.",
             "  --query <text> keeps the documents whose title OR body contains that text, matched case-insensitively in the database — never fuzzy, and the body still never comes back.",
+            "  --word matches --query as whole words: `--query ott --word` finds \"Ott\" but not \"bottom\" or \"Otter\".",
             "  --limit <n> caps the rows (1-1000). Narrow with these before reading: `cockpit docs list --query onboarding --json` then `cockpit docs read <slug>`.",
             "tree — the same documents nested under their parent, for a sidebar-shaped view.",
-            "read <id|slug> — one document's title, slug, visibility, and its body. This is the ONLY verb that returns a body.",
-            "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
-            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+            "read <id|slug> [<id|slug>...] — one or more documents' title, slug, visibility, and body. This is the ONLY verb that returns a body. Several refs resolve against ONE shared list call, then one GET each — one bad ref never loses the rest.",
+            "  --section \"<heading>\" — one section only, from that heading (any # level, case-insensitive) to the next heading at the same or shallower level. Mirrors `cockpit workbook --section`. A miss refuses (document_section_not_found) and names the headings that ARE there.",
+            "  --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 }] }.",
+            "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 }.",
+            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb. --json shape: { document }.",
             "  --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.",
+            "link <id|slug> <notion-url|page-id> — ties the document to a Notion page so the two-way sync moves it both ways. The page is the truth from then on: the next sync pulls it over this copy and keeps the copy as a version. `link <id|slug> --clear` unties it. Refusals: invalid_notion_page, notion_page_already_linked, document_not_writable.",
+            "sync-status [<id|slug>] — every linked document's Notion sync state, or one's: synced (the body is what both sides last agreed on), tower_changed (edited here since; the next write-back pushes it), never_synced (linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull, not here. Metadata only, never a body.",
             "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
             "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
@@ -80,13 +87,14 @@ export const TOWER_COMMAND_HELP = [
     [
         "issue",
         [
-            "Usage: cockpit issue [list|show <id>|create|update <id>|move <id> <state>|comment <id>|history <id>] [flags]",
+            "Usage: cockpit issue [list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|history <id>] [flags]",
             "",
             "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
-            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first.",
-            "show <id> — one issue: title, state, priority, assignee, description, and every comment on it.",
-            "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description.",
-            "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move.",
+            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first. Each row carries assignee_name/assignee_email alongside the bare assignee_id (BLI-10450, one extra `cockpit team members` call for the whole page, never per row). --json shape: { issues: [{ id, identifier, title, state, priority, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
+            "show <id> [<id>...] — one or more issues: title, state, priority, assignee (name and email, not just its id), description, and every comment on each. Several ids read in one call — one bad id never loses the rest.",
+            "  --json shape: one id answers { issue, comments }, unchanged from before BLI-10450. Several ids answer { issues: [{ ref, ok, issue, comments } | { ref, ok: false, error, detail }] }.",
+            "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description. --json shape: { issue }.",
+            "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move. --json shape: { issue }.",
             "move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
             "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
             "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
@@ -107,14 +115,14 @@ export const TOWER_COMMAND_HELP = [
             "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
             "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
             "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
-            "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
-            "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
-            "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
+            "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment. Every row (text or --json) carries the thread id — `[thread <id>]` in text — so `mail read <thread>` never costs a second --json call to learn it (BLI-10450).",
+            "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox` or `cockpit mail search`, in either --json or plain text.",
+            "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box. Every row (text or --json) carries the thread id.",
             "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
             "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
             "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
             "detach <account> — removes the mailbox, its stored mail and its credential.",
-            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr. Shapes differ by verb: inbox/read answer { messages: [...] }, search answers { matches: [...] } — same MessageRow shape either name, always carrying thread_id.",
             "A refusal keeps Tower's own reason label — needs_rls_client, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
             "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
         ],

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

@@ -372,7 +372,7 @@ export function localSubcommandHelp(command) {
         [
             "slack",
             [
-                "Usage: cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] | read [filters]] [--json]",
+                "Usage: cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] [--list] | read [filters] [--format compact|full]] [--json]",
                 "",
                 "  cockpit slack coverage",
                 "      What Cockpit's Slack bot can see: how many channels it is in, what each",
@@ -380,13 +380,23 @@ export function localSubcommandHelp(command) {
                 "      are open. No message text at all, so anybody signed in can run it.",
                 "      This is the command that tells an empty search apart from a coverage gap.",
                 "      --stale-only drops the per-state breakdown and shows just what is behind.",
-                "  cockpit slack read --person <p> | --channel <c> | --query <text>",
+                "      --list names every channel and its readable state — counts alone could not",
+                "      answer \"is there a Kaiben channel?\". --json's shape: { coverage: { workspaces: [",
+                "      { workspace, channelsKnown, covered, byVisibility, staleChannels, openSkips,",
+                "      channels? } ] } } — channels is present only with --list.",
+                "  cockpit slack read --person <p> | --channel <c> | --query <text> [--word]",
                 "      The messages themselves, through the same reader JARVIS uses. At least one",
                 "      filter is required. --since/--until are YYYY-MM-DD; --limit caps the rows.",
+                "      --query matches a substring; add --word to match whole words, so `excel`",
+                "      stops matching \"Excellent\".",
                 "      Reading Slack reads across the team, so this is for the people who do that",
                 "      job; being refused it never costs you `cockpit slack coverage`.",
                 "      An empty or partial answer prints Tower's own sentence about WHY, word for",
                 "      word — none of those reasons means nothing was said.",
+                "      --format full (default): each message as its own block (channel/author/time,",
+                "      text, permalink). --format compact: one line per message. Always one rendering,",
+                "      never both — a result used to print as a summary AND as blocks (BLI-10450).",
+                "      --json's shape: { result: { status, reason, messages: [...], coverage, note } }.",
             ],
         ],
         [
@@ -585,6 +595,8 @@ export function localSubcommandHelp(command) {
                 "The STORE, over the same /api/memory/* doors the bli-memory MCP server calls:",
                 "  search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent]",
                 "      repeat --container to search more than one space; omit it for this repository's own.",
+                "      --limit caps the memories (default 5); up to 3 Tower pages and tickets ride beside",
+                "      them whatever it says. For more Tower rows, use `cockpit search`.",
                 "  save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>]",
                 "      the memory comes from stdin or --file, never from the command line:",
                 "      `echo \"Edward decided X on 2026-09-10\" | cockpit memory save`.",