@bli-cockpit/cli 0.2.137 → 0.2.140

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

@@ -8,7 +8,10 @@
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "link", "sync-status"]);
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update", "link"]);
+// 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,17 +25,56 @@ 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 link = parseDocsLink(action, rest, values.booleans.has("--clear"));
-    const docRef = parseDocsDocumentReference(action, link.rest);
-    const { visibility, clearParent, parentId, allowEmpty, title, query, limit } = parseDocsFlags(action, values);
-    return buildDocsCommand(values, action, docRef, visibility, clearParent, parentId, allowEmpty, title, query, limit, link);
+    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
@@ -67,23 +109,31 @@ function parseDocsAction(positionals) {
     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 optionalNonEmpty(rest[0]);
+        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"));
@@ -118,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, link) {
+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,
@@ -139,7 +218,11 @@ 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,17 +42,22 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>|link <id|slug> <notion-page>|sync-status [<id|slug>]] [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.",
@@ -82,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.",
@@ -109,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`.",

package/dist/commands/local-help.js

@@ -100,7 +100,7 @@ export function localCommandHelp(command) {
         "  cockpit models [list|show <provider:model>|compare <provider:model> <provider:model> [...]] [--highlight] [--dashboard-url <url>] [--json]",
         "  cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
         "  cockpit ops [status [--job <id>] [--skips] [--memory] [--models] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
-        "  cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] | read [--person <p>] [--channel <c>] [--query <text>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>]] [--json]",
+        "  cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] [--list] | read [--person <p>] [--channel <c>] [--query <text> [--word]] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--format compact|full]] [--json]",
         "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | cli-floor [<version>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
         "  cockpit team [members | invite <email> --role <role> [--team-id <uuid>] | role <userId> --role <role> [--yes] | device [list] | device revoke <id|name> --reason <label> [--note \"<text>\"] [--yes]] [--json]",
         "  cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
@@ -117,7 +117,7 @@ export function localCommandHelp(command) {
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
         "  cockpit memory [search \"<question>\"|save|update <id>|forget <id>|profile|install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--container <tag>] [--limit <n>] [--no-recent] [--custom-id <id>] [--extract] [--content-stdin] [--reason <label>] [--file <path>] [--dashboard-url <url>] [--dry-run] [--json]",
         "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
-        "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text>] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
+        "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text> [--word]] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
         "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
@@ -136,6 +136,7 @@ export function localCommandHelp(command) {
         "  cockpit usage people [--by-repo | --by-topic | --by-subject | --by-task] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
+        "--quiet on any command (or COCKPIT_QUIET=1) drops the `[tower client] responded {...}` trace line from stderr; --json already implies it. A failure still logs — only that success-path trace goes quiet (BLI-10450).",
     ].join("\n");
 }
 /**

package/dist/commands/local.js

@@ -57,6 +57,14 @@ export { assertCollectionRootPersisted } from "./collection-roots.js";
 export { runSelfUpdate, SelfUpdateError, } from "./install-update.js";
 import { runRoots } from "./roots.js";
 export async function runLocalCockpitCli(argv, io = defaultIo()) {
+    // BLI-10450: `--quiet` is a global toggle, stripped here so no per-command
+    // parser's `allowedFlags` needs to learn it, and mirrored onto
+    // `COCKPIT_QUIET` so `tower-client.ts` can react without every call site
+    // threading a flag through. `--json` already implies it (tower-client.ts).
+    if (argv.includes("--quiet")) {
+        argv = argv.filter((token) => token !== "--quiet");
+        process.env.COCKPIT_QUIET = "1";
+    }
     if (isLocalHelpRequest(argv)) {
         writeLine(io.stdout, localCommandHelp(argv[0]));
         return 0;

package/dist/commands/mail.js

@@ -177,7 +177,11 @@ function messageLine(message) {
     const paperclip = message.has_attachments ? "@" : " ";
     const from = message.from_address?.address ?? "(no sender)";
     const day = message.internal_date.slice(0, 16).replace("T", " ");
-    return `${flag}${paperclip} ${day}  ${from.padEnd(30).slice(0, 30)}  ${(message.subject ?? "(no subject)").slice(0, 60)}`;
+    // BLI-10450: a text row carried no thread id, so `mail read` needed a
+    // second call with `--json` just to learn what `search`/`inbox` already
+    // had in hand. `mail read <thread>` takes this verbatim.
+    const thread = message.thread_id ? `  [thread ${message.thread_id}]` : "";
+    return `${flag}${paperclip} ${day}  ${from.padEnd(30).slice(0, 30)}  ${(message.subject ?? "(no subject)").slice(0, 60)}${thread}`;
 }
 async function readThread(command, door) {
     const answer = await askAgentDoor(door, {

package/dist/commands/memory-store.js

@@ -175,6 +175,8 @@ export function runMemoryVerbList(io, json) {
         "The experience log:",
         "  cockpit memory log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"",
         "",
+        "Search: --limit caps the MEMORIES (default 5, at most 20). Up to 3 Tower pages and",
+        "tickets ride beside them whatever --limit says; for more, use `cockpit search`.",
         "Save accepts repeated --alias names (up to 16 names of 64 characters).",
         "Omit --container and this repository's own memory space is used — the same",
         "space the bli-memory MCP server and its hooks read and write.",
@@ -222,7 +224,15 @@ async function searchMemory(command, door) {
     })}`);
     if (door.json)
         return emitAgentDoor(door, answer.body);
-    if (results.length === 0) {
+    if (results.length === 0 && body.degraded) {
+        // BLI-10448: an empty answer from a search that lost a channel is NOT the
+        // record being silent. `semantic_timed_out` is the store answering on
+        // keywords alone after its vector search ran out of time, and saying
+        // "the record is silent" over it sends a person away from memories that
+        // exist.
+        writeLine(door.io.stdout, `No memories matched on the channels that answered, and one did not (${body.degraded}). Do not read this as the record being silent; ask again.`);
+    }
+    else if (results.length === 0) {
         // The distinction the whole store is built on: silence is not an outage.
         // A failure took the `!answer.ok` branch above and named itself there.
         writeLine(door.io.stdout, "No memories matched. The record is silent on this — it does not mean the store is down.");

package/dist/commands/msg.js

@@ -104,15 +104,26 @@ async function readChannel(command, door) {
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const messages = answer.body.messages ?? [];
+    const body = answer.body;
+    const messages = body.messages ?? [];
+    // BLI-10449: whether this channel is Tower's own or a Slack snapshot, and
+    // how fresh — the door's own sentence, printed as sent.
+    const provenance = body.provenance ?? null;
+    const limitApplied = body.limitApplied ?? null;
     if (door.json)
-        return emitAgentDoor(door, { ok: true, channelId: resolved.id, messages });
+        return emitAgentDoor(door, { ok: true, channelId: resolved.id, provenance, limitApplied, messages });
+    if (provenance?.sentence)
+        writeLine(door.io.stdout, provenance.sentence);
+    if (limitApplied !== null) {
+        writeLine(door.io.stdout, `Showing the newest ${limitApplied}: one read returns at most ${limitApplied} messages.`);
+    }
     if (messages.length === 0) {
         writeLine(door.io.stdout, "No messages.");
         return 0;
     }
     for (const message of [...messages].reverse()) {
-        const who = message.agent_label ?? message.user_id;
+        // An imported Slack message has no Tower user; its Slack name is the label.
+        const who = message.agent_label ?? message.user_id ?? message.slack_author_label ?? "someone";
         writeLine(door.io.stdout, `${message.created_at}  ${who}  ${message.content ?? ""}`);
     }
     return 0;

package/dist/commands/notes-reads.js

@@ -4,6 +4,30 @@
  */
 import { writeLine } from "./cli-io.js";
 import { ask, fail, emit, sayScope, READ_DEADLINE_MS } from "./notes-door.js";
+/**
+ * The lines `notes list` prints under the notes: every meeting record the
+ * docs door would show this caller, with the ref `docs read` takes, and which
+ * copy is canonical. Empty when there are none.
+ */
+export function meetingDocumentLines(meeting, readVerb) {
+    if (!meeting || meeting.count === 0)
+        return [];
+    const refOf = new Map(meeting.items.map((item) => [item.id, item.slug ?? item.id]));
+    const copies = meeting.copies > 0 ? `, ${meeting.copies} of them ${meeting.copies === 1 ? "a copy" : "copies"}` : "";
+    const lines = [
+        `Meeting records in Docs, not in Notes (${meeting.count}${copies}). Read one with \`${readVerb} <ref>\`:`,
+    ];
+    for (const item of meeting.items) {
+        const size = `${Math.max(1, Math.round(item.bodyChars / 1000))} KB${item.parts.length > 0 ? ` in ${item.parts.length + 1} parts` : ""}`;
+        const mark = item.canonical
+            ? item.canonicalReason && item.canonicalReason !== "only_copy" ? ` · canonical (${item.canonicalReason})` : ""
+            : ` · copy of ${refOf.get(item.duplicateOf ?? "") ?? item.duplicateOf}`;
+        lines.push(`  ${item.meetingDate ?? "undated   "}  ${refOf.get(item.id)}  ${item.title}  ${item.visibility} · ${item.source} · ${size}${mark}`);
+    }
+    if (meeting.truncated)
+        lines.push("  (the read hit its cap, so there may be more)");
+    return lines;
+}
 function libraryQuery(command) {
     const query = new URLSearchParams();
     if (command.series)
@@ -33,8 +57,11 @@ export async function listNotes(command, door) {
         return emit(door, body);
     sayScope(door, body);
     const series = body.series ?? [];
+    const inDocs = meetingDocumentLines(body.meetingDocuments, "cockpit docs read");
     if (series.length === 0) {
         writeLine(door.io.stdout, "No meeting notes matched.");
+        if (inDocs.length > 0)
+            writeLine(door.io.stdout, ["", ...inDocs].join("\n"));
         return 0;
     }
     for (const one of series) {
@@ -47,6 +74,8 @@ export async function listNotes(command, door) {
     }
     writeLine(door.io.stdout, "");
     writeLine(door.io.stdout, `${body.count ?? 0} note(s)${body.more ? ", and more exist beyond the limit" : ""}.`);
+    if (inDocs.length > 0)
+        writeLine(door.io.stdout, ["", ...inDocs].join("\n"));
     return 0;
 }
 export async function listShelves(command, door) {

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.137");
+    writeLine(io?.stdout ?? process.stdout, "0.2.140");
     return 0;
   }