@bli-cockpit/cli 0.2.241 → 0.2.243

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

@@ -16,7 +16,13 @@
  * shared machine and lands in shell history).
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+import { RELATION_VALUE_FLAGS, readRelationFlags } from "./issue-relations.js";
 import { estimateForSize } from "./issue-contracts.js";
+import { INBOX_ACTIONS, INBOX_BOOLEAN_FLAGS, INBOX_VALUE_FLAGS, isInboxAction, parseInboxArgs } from "./inbox-args.js";
+import { NOTIFY_ACTIONS, NOTIFY_VALUE_FLAGS, isNotifyAction, parseNotifyArgs } from "./work-notify-args.js";
+import { VIEW_BOOLEAN_FLAGS, VIEW_VALUE_FLAGS, parseViewArgs } from "./view-args.js";
+import { parseTemplateArgs } from "./template-args.js";
+import { CYCLE_BOOLEAN_FLAGS, CYCLE_VALUE_FLAGS, parseCycleArgs, readCycleField } from "./cycle-args.js";
 const ISSUE_ACTIONS = new Set([
     "mutation-status",
     "board",
@@ -29,6 +35,15 @@ const ISSUE_ACTIONS = new Set([
     "history",
     "versions",
     "restore",
+    "label",
+    "batch",
+    "relations",
+    "relate",
+    "unrelate",
+    "views",
+    "templates", "cycles",
+    ...INBOX_ACTIONS,
+    ...NOTIFY_ACTIONS,
 ]);
 /** Every verb except `list` and `create` names ONE issue first. */
 const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
@@ -40,6 +55,10 @@ const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
     "history",
     "versions",
     "restore",
+    "label",
+    "relations",
+    "relate",
+    "unrelate",
 ]);
 /**
  * The closed state vocabulary, copied verbatim from
@@ -66,6 +85,9 @@ const ISSUE_ALLOWED_FLAGS = [
     "--priority",
     "--size",
     "--parent",
+    "--due",
+    "--add",
+    "--remove",
     "--file",
     "--version",
     "--cursor",
@@ -79,8 +101,15 @@ const ISSUE_ALLOWED_FLAGS = [
     "--all",
     "--body-stdin",
     "--json",
+    ...VIEW_BOOLEAN_FLAGS,
+    ...VIEW_VALUE_FLAGS,
+    ...INBOX_BOOLEAN_FLAGS,
+    ...INBOX_VALUE_FLAGS,
+    ...NOTIFY_VALUE_FLAGS,
+    ...RELATION_VALUE_FLAGS, ...CYCLE_VALUE_FLAGS, ...CYCLE_BOOLEAN_FLAGS,
 ];
 const ISSUE_VALUE_FLAGS = [
+    "--cycle",
     "--request-id",
     "--expected-revision",
     "--home",
@@ -95,6 +124,9 @@ const ISSUE_VALUE_FLAGS = [
     "--priority",
     "--size",
     "--parent",
+    "--due",
+    "--add",
+    "--remove",
     "--file",
     "--version",
     "--cursor",
@@ -105,6 +137,10 @@ const ISSUE_VALUE_FLAGS = [
     "--updated-before",
     "--sort",
     "--dir",
+    ...VIEW_VALUE_FLAGS,
+    ...INBOX_VALUE_FLAGS,
+    ...NOTIFY_VALUE_FLAGS,
+    ...RELATION_VALUE_FLAGS, ...CYCLE_VALUE_FLAGS,
 ];
 export function parseIssueArgs(args) {
     const values = parseNamedArgs(args, {
@@ -112,6 +148,25 @@ export function parseIssueArgs(args) {
         valueFlags: ISSUE_VALUE_FLAGS,
     });
     const { action, rest } = readIssueAction(values);
+    if (action === "views")
+        return parseViewArgs(values, rest);
+    if (action === "templates")
+        return parseTemplateArgs(values, rest);
+    if (action === "cycles")
+        return parseCycleArgs(values, rest);
+    if (isNotifyAction(action))
+        return parseNotifyArgs(values, rest);
+    if (isInboxAction(action))
+        return parseInboxArgs(values, action, rest);
+    const strayNotify = NOTIFY_VALUE_FLAGS.find((flag) => values.flags.has(flag));
+    if (strayNotify)
+        throw new Error(`${strayNotify} belongs to \`cockpit ticket notifications\`.`);
+    const strayInbox = [...INBOX_VALUE_FLAGS, ...INBOX_BOOLEAN_FLAGS].find((flag) => values.flags.has(flag) || values.booleans.has(flag));
+    if (strayInbox)
+        throw new Error(`${strayInbox} belongs to \`cockpit ticket inbox\`.`);
+    const stray = [...VIEW_VALUE_FLAGS, ...VIEW_BOOLEAN_FLAGS].find((flag) => values.flags.has(flag) || values.booleans.has(flag));
+    if (stray)
+        throw new Error(`${stray} belongs to \`cockpit ticket views\`.`);
     const { issueRef, issueRefs, moveState } = readIssueReference(action, rest);
     const requestId = optionalNonEmpty(values.flags.get("--request-id"));
     const expectedRevision = optionalPositiveInteger(values.flags.get("--expected-revision"), "--expected-revision");
@@ -119,11 +174,12 @@ export function parseIssueArgs(args) {
         throw new Error("--request-id must be a UUID.");
     if (action === "mutation-status" && !UUID_PATTERN.test(issueRef ?? ""))
         throw new Error("mutation-status needs a request UUID.");
-    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore"].includes(action)) {
-        throw new Error("Write-safety flags belong to create, update, move, comment or restore.");
+    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore", "label", "batch", "relate", "unrelate"].includes(action)) {
+        throw new Error("Write-safety flags belong to create, update, move, comment, restore, label, relate, unrelate or batch.");
     }
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
+    const fields = readIssueFields(action, values);
     const title = readIssueTitle(action, values);
     if (action !== "board" && values.flags.has("--rows")) {
         throw new Error("--rows widens cockpit tickets board only.");
@@ -140,7 +196,7 @@ export function parseIssueArgs(args) {
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
     const versionNumber = readIssueVersion(action, values);
-    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page);
+    return { ...buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page, fields), ...readRelationFlags(action, values) };
 }
 const INSTANT = /^\d{4}-\d\d-\d\d(?:T\d\d:\d\d:\d\d(?:\.\d{1,6})?(?:Z|[+-]\d\d:\d\d))?$/;
 /** BLI-21315: the cursor contract's flags. Filters and sort belong to `list`; `--cursor` also to `history`. */
@@ -190,7 +246,7 @@ function readIssueAction(values) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!ISSUE_ACTIONS.has(action)) {
-        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, history, versions, restore, or mutation-status.`);
+        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, label, relations, relate, unrelate, views, templates, cycles, inbox, read, unread, subscribe, unsubscribe, notifications, history, versions, restore, batch, or mutation-status.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -237,10 +293,11 @@ function validateIssueState(state, errorPrefix) {
 function readIssueStateFilter(action, values) {
     const stateFilter = optionalNonEmpty(values.flags.get("--state"));
     validateIssueState(stateFilter, "--state must be one of: ");
-    if (stateFilter !== undefined && action !== "list" && action !== "board") {
-        throw new Error("--state filters `cockpit issue list`; to move an issue use `cockpit issue move <id> <state>`.");
+    if (stateFilter !== undefined && action !== "list" && action !== "board" && action !== "create") {
+        throw new Error("--state filters `cockpit issue list` and sets the starting state on `create`; to move an issue use `cockpit issue move <id> <state>`.");
     }
-    return stateFilter;
+    // On create the same flag is the starting state; it is returned separately in readIssueFields.
+    return action === "create" ? undefined : stateFilter;
 }
 function readIssueTitle(action, values) {
     const title = optionalNonEmpty(values.flags.get("--title"));
@@ -270,14 +327,54 @@ function readIssueAssignee(action, values) {
     // email is refused HERE rather than travelling to Postgres as a malformed
     // uuid, which would come back as a 500 that names nothing useful.
     const assignee = optionalNonEmpty(values.flags.get("--assignee"));
-    if (assignee !== undefined && assignee !== "me" && assignee !== "unassigned" && !UUID_PATTERN.test(assignee)) {
-        throw new Error('--assignee must be "me", "unassigned", or a person\'s uuid (see `cockpit team`).');
+    if (assignee !== undefined && assignee !== "me" && assignee !== "unassigned" && assignee !== "none" && !UUID_PATTERN.test(assignee)) {
+        throw new Error('--assignee must be "me", "unassigned" (list), "none" (update), or a person\'s uuid (see `cockpit team`).');
     }
     if (assignee === "unassigned" && action !== "list" && action !== "board") {
-        throw new Error('--assignee unassigned filters `cockpit issue list`; to clear an assignee pass --assignee "" is not supported yet.');
+        throw new Error("--assignee unassigned filters `cockpit ticket list`; to clear an owner on update pass --assignee none.");
     }
+    if (assignee === "none" && action !== "update")
+        throw new Error("--assignee none clears the owner on `cockpit ticket update`.");
     return assignee;
 }
+const CALENDAR_DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** BLI-21422: starting state, due date and label names. Omitted stays omitted; `none` is the only way to clear. */
+function readIssueFields(action, values) {
+    const out = {};
+    const startState = optionalNonEmpty(values.flags.get("--state"));
+    if (action === "create" && startState)
+        out.startState = startState;
+    const due = optionalNonEmpty(values.flags.get("--due"));
+    if (due !== undefined) {
+        if (action !== "create" && action !== "update")
+            throw new Error("--due belongs to `cockpit ticket create` and `update`.");
+        if (due === "none") {
+            if (action === "create")
+                throw new Error("--due none clears a date on `cockpit ticket update`; leave --due off to create without one.");
+            out.due = null;
+        }
+        else {
+            if (!CALENDAR_DAY.test(due) || new Date(`${due}T12:00:00Z`).toISOString().slice(0, 10) !== due) {
+                throw new Error("--due must be a calendar date as YYYY-MM-DD, or none to clear it (update).");
+            }
+            out.due = due;
+        }
+    }
+    const add = (values.flagValues.get("--add") ?? []).map((v) => v.trim()).filter(Boolean);
+    const remove = (values.flagValues.get("--remove") ?? []).map((v) => v.trim()).filter(Boolean);
+    if ((add.length > 0 || remove.length > 0) && action !== "label") {
+        throw new Error("--add and --remove belong to `cockpit ticket label <id>`.");
+    }
+    if (action === "label") {
+        if (add.length === 0 && remove.length === 0)
+            throw new Error("ticket label needs --add <name> and/or --remove <name> (repeat the flag for several).");
+        if (add.length > 50 || remove.length > 50)
+            throw new Error("ticket label changes at most 50 labels per side.");
+        out.addLabels = add;
+        out.removeLabels = remove;
+    }
+    return out;
+}
 /** `restore` names the version it wants; there is no "restore the previous one" (BLI-21300). */
 function readIssueVersion(action, values) {
     const version = optionalPositiveInteger(values.flags.get("--version"), "--version");
@@ -295,7 +392,7 @@ function readIssueLimit(action, values) {
     }
     return limit;
 }
-function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page) {
+function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page, fields) {
     return {
         kind: "issue",
         requestId: optionalNonEmpty(values.flags.get("--request-id")),
@@ -313,6 +410,7 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
         project: optionalNonEmpty(values.flags.get("--project")),
         ...(limit === undefined ? {} : { limit }),
         ...page,
+        ...fields, ...readCycleField(action, values),
         ...(versionNumber === undefined ? {} : { versionNumber }),
         title,
         ...(priority === undefined ? {} : { priority }),
@@ -323,26 +421,4 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
         json: values.booleans.has("--json"),
     };
 }
-export function parseProjectArgs(args) {
-    const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--dashboard-url", "--archived", "--cursor", "--limit", "--json"],
-        valueFlags: ["--home", "--dashboard-url", "--cursor", "--limit"],
-    });
-    const first = values.positionals[0];
-    const action = (first === undefined ? "list" : first);
-    if (action !== "list")
-        throw new Error(`Unknown project command: ${first}. The only verb is list.`);
-    const rest = values.positionals.slice(first === undefined ? 0 : 1);
-    if (rest.length > 0)
-        throw new Error(`project list does not take "${rest[0]}".`);
-    return {
-        kind: "project",
-        action,
-        homeDir: optionalNonEmpty(values.flags.get("--home")),
-        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
-        includeArchived: values.booleans.has("--archived"),
-        ...(optionalNonEmpty(values.flags.get("--cursor")) ? { cursor: optionalNonEmpty(values.flags.get("--cursor")) } : {}),
-        ...(values.flags.has("--limit") ? { limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit") } : {}),
-        json: values.booleans.has("--json"),
-    };
-}
+export { parseProjectArgs } from "./project-args.js";

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

@@ -54,4 +54,5 @@ export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';
 export { parseGlossaryArgs } from "./glossary.js";
 export { parseSpendArgs } from "./spend.js";
+export { parsePushArgs } from "./push.js";
 export { parseCiArgs } from "./ci.js";

package/dist/commands/local-args.js

@@ -17,6 +17,7 @@
  */
 import { parseGlossaryArgs } from "./glossary.js";
 import { parseSpendArgs } from "./spend.js";
+import { parsePushArgs } from "./push.js";
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
@@ -82,6 +83,7 @@ const COMMAND_PARSERS = new Map([
     ["sources", (_command, rest) => parseSourcesArgs(rest)],
     ["glossary", (_command, rest) => parseGlossaryArgs(rest)],
     ["spend", (_command, rest) => parseSpendArgs(rest)],
+    ["push", (_command, rest) => parsePushArgs(rest)],
     ["docs", (_command, rest) => parseDocsArgs(rest)],
     ["msg", (_command, rest) => parseMsgArgs(rest)],
     ["issue", (_command, rest) => parseIssueArgs(rest)],

package/dist/commands/local-auth.js

@@ -235,7 +235,7 @@ async function inferUniqueGitEmail(roots) {
 }
 async function readGitConfigEmail(root) {
     return new Promise((resolve) => {
-        execFile("git", ["config", "user.email"], { cwd: root, encoding: "utf8" }, (error, stdout) => {
+        execFile("git", ["config", "user.email"], { cwd: root, encoding: "utf8", windowsHide: true }, (error, stdout) => {
             if (error) {
                 resolve(null);
                 return;

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

@@ -174,6 +174,8 @@ export const TOWER_OPS_COMMAND_HELP = [
             "  cockpit approvals show <id>                 the card in full: who, why, the exact content, every receipt",
             "  cockpit approvals create                    prepare a card; the POST /api/approvals body as JSON on stdin",
             "  cockpit approvals approve <id> [--edit]     let the guarded act run; --edit reads {\"subject\":...,\"text\":...} or {\"content\":...} on stdin",
+            "      --checked-sent sent|not-sent              on a card whose delivery is unknown or stuck sending, what you found where it was going",
+            "                                                (your Sent folder for mail.send, the channel for msg.send): sent closes it, not-sent sends or posts it now",
             "  cockpit approvals edit <id> [--approve]     save an edit (JSON on stdin), the card stays waiting; --approve then approves it",
             "  cockpit approvals reject <id>               decline it; nothing is sent",
             "  cockpit approvals rules [--active true|false] [--limit <n>]",

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

@@ -11,6 +11,18 @@
  * Every string moved verbatim. Help output is what an intern pastes back when
  * something breaks, so it is a user-visible contract like any other.
  */
+import { DOCS_FILES_HELP } from "./local-help-docs-files.js";
+import { DOCS_REFS_HELP } from "./local-help-docs-refs.js";
+import { DOCS_SYNC_HELP } from "./local-help-docs-sync.js";
+import { DOCS_FORMATTING_HELP } from "./local-help-docs-formatting.js";
+import { DOCS_INBOX_HELP } from "./local-help-docs-inbox.js";
+import { DOCS_RECOVERY_HELP } from "./local-help-docs-recovery.js";
+import { PROJECT_HELP } from "./local-help-project.js";
+import { INBOX_HELP_LINES } from "./local-help-inbox.js";
+import { WORK_NOTIFY_HELP_LINES } from "./local-help-work-notify.js";
+import { VIEWS_HELP_LINES } from "./local-help-views.js";
+import { TEMPLATES_HELP_LINES } from "./local-help-templates.js";
+import { CYCLES_HELP_LINES } from "./local-help-cycles.js";
 /** One entry per Tower noun, in the order `cockpit --help` lists them. */
 export const TOWER_COMMAND_HELP = [
     [
@@ -47,19 +59,20 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|delete <id|slug> [<id|slug>...]|link <id|slug> <notion-page>|sync-status [<id|slug>]|export <id|slug> [--format md|pdf|docx|txt] [--out <path>]|mutation-status <request-uuid>|share <id|slug> --add|--remove <email>|access <id|slug>] [flags]",
+            "Usage: cockpit docs [list|search [words]|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|delete <id|slug> [<id|slug>...]|link <id|slug> <notion-page>|sync-status [<id|slug>]|sync-resolve <id|slug> --version <id> --keep-current|--use-kept|manifest [--under <id|slug>] [--all] [--out <file>]|export <id|slug> [--format md|pdf|docx|txt] [--out <path>]|mutation-status <request-uuid>|share <id|slug> --add|--remove <email>|access <id|slug>|comments <id|slug>|comment <id|slug>|trash|versions <id|slug>|restore <id>|favorite <id|slug>|unfavorite <id|slug>|marks] [flags]",
             "",
             "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
             "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> [<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.",
+            "  --limit <n> caps the rows (1-1000). --cursor <c> continues a list from the `More:` line (keyset paging); --all walks every page (at most 20) and prints requested/returned/unique pages and a status: exhausted, capped or partial. Narrow with these before reading: `cockpit docs list --query onboarding --json` then `cockpit docs read <slug>`.",
+            "search [words] [--word] [--title-only] [--by <me|email|id>] [--under <id|slug>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--timezone <IANA>] [--sort relevance|updated] [--limit <n>] — finds documents by title or text over EVERY page you may read (past the 1,000-row page cap), narrowed by who created them (--by me, an exact email, or a user id), a subtree (--under a page: that page and its descendants), and the local days they were updated (--since/--until inclusive, in --timezone, default this machine's zone). Matching is literal and case-insensitive; --word matches whole words; --title-only matches titles alone. Words may be left out when --by, --under, --since or --until is given. Prints each hit with its id, then matched/returned and a coverage line: exhausted, capped (more exist) or partial (some pages could not be searched). --json shape: { query, filters, sort, matched, requested, returned, coverage, results: [{ id, title, slug, created_by, parent_id, updated_at, matched_in, snippet }] }. A bad filter is invalid_filter (400) and names the field; --under a page you cannot read finds nothing and never names it. Same door as the web box, MCP docs_search and JARVIS.",
+            "tree — the same documents nested under their parent, for a sidebar-shaped view. Walks every page and ends with a coverage line: exhausted, capped (20,000 shown, more exist) or partial (some pages could not load). favorite <id|slug> / unfavorite <id|slug> star or unstar a page for yourself (200 at most; favorites_full). marks — your favorites and your 20 most recent web-opened pages, readable only; --json: { favorites: [{ id, title, slug, marked_at }], recents: [...] }.",
+            "read <id|slug> [<id|slug>...] — one or more documents' title, slug, visibility, and body. This is the ONLY verb that returns a body. Each ref is one exact lookup (id, or slug matched exactly, any case, never fuzzy or prefix; at most 8 in flight), then one GET each — the oldest page opens like the newest and 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 }] }.",
+            "  --json shape: one ref answers { document }, unchanged from before BLI-10450. Several refs answer { documents: [{ ref, ok, document } | { ref, ok: false, error, detail }] }. The meta line (and --json document.revision) shows the page revision. Agent writes are never queued offline: a write that did not reach Tower fails with its reason, and `docs mutation-status <request-id>` tells whether it landed. Pass the revision you read as expected_revision.",
             "read --parent <id>|root --bodies [--limit <n>] — every document filed directly under that parent, bodies included, in ONE call (GET /api/docs/documents?parent_id=...&bodies=true). --limit here caps the DOCUMENT COUNT (1-50), not characters. --json shape: { documents: [{ id, ..., body_markdown }] }.",
             "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default. --json shape: { document }.",
             "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] [--expected-revision <n>] [--request-id <uuid>] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb. --json shape: { document, mutation }.",
@@ -69,30 +82,38 @@ export const TOWER_COMMAND_HELP = [
             "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
             "access <id|slug> — who may do what on a page and why, in plain sentences (BLI-21313): your role (author, admin, granted_editor, reader), can_read/can_edit/can_manage, the named editors you may see (the owner and administrators see all; a named editor sees only their own grant), and the grant history for the owner and administrators. The same explanation the page, its versions and its export carry. --json shape: { ok, document_id, permission: { role, can_read, can_edit, can_manage, editors, editors_complete, reasons }, events }.",
             "share <id|slug> --add <email> | --remove <email> [--reason \"<note>\"] — owner or administrator only. Names (or removes) an editor of an ORGANIZATION page by exact email, never fuzzy. An editor can change the title and text; they cannot change visibility, move, delete or manage editors, and nobody new gains the right to read. A page you made private refuses with private_page_grant_needs_decision (sharing a private page waits for a decision) and nothing is written. Other refusals: not_grant_manager, person_not_found, grantee_is_author, document_not_found_or_unreadable. Adding someone already named, or removing someone not named, answers outcome unchanged. --json shape: { ok, outcome, reason, document_id, grantee_id, request_id, permission }.",
-            "delete <id|slug> [<id|slug>...] — soft-deletes one or more documents (BLI-10555): the browser's own delete, sets deleted_at, never a real SQL DELETE. Recoverable — only a super_admin clearing deleted_at brings it back, there is no self-service undo. Deleting a parent does NOT delete its children; they keep their own parent_id and stay exactly where they were. Several refs resolve against ONE shared list call, then one DELETE each — one bad ref never loses the rest. --json shape: one ref answers { ok, document_id }; several answer { documents: [{ ref, ok, document_id } | { ref, ok: false, error, detail }] }.",
+            "comments <id|slug> [--status open|resolved|all] [--cursor <c>] — the page's discussion (BLI-21701): threads newest activity first, 50 per page, each with its comments (author, time, edited), a \"A comment was deleted by <who> on <when>.\" line for a deleted one, and who resolved a resolved thread. Anyone who can read the page can read it. Ends with the open/resolved counts, a `More: --cursor` line, and a coverage note when some comments could not be read. --json shape: { ok, status, can_comment, counts: { open, resolved }, threads: [{ id, resolved, resolved_at, resolved_by_name, comments: [{ id, author_name, body, created_at, edited_at, deleted, marker, can_edit, can_delete }] }], next_cursor, coverage: exhausted|capped|failed_partial, coverage_note, note }.",
+            "comment <id|slug> \"<text>\" | - [--request-id <uuid>] — starts a thread (the text is the second argument, or `-` to read stdin; 1-10,000 characters). Add --reply <thread id> to answer a thread, --edit <comment id> to replace your own comment's text (earlier text is not kept), --delete <comment id> (its author, the page owner or an administrator; a soft delete), --resolve <thread id> or --reopen <thread id>. Exactly one action. Only the page owner, administrators and named editors of an organization page can write; everyone else who can read the page is refused with not_commenter and nothing is written. Other labels, verbatim: not_comment_author, comment_not_found, thread_not_found, invalid_body, document_not_found_or_unreadable. The same --request-id twice gives one comment (outcome unchanged); resolving a resolved thread answers unchanged. --json shape: { ok, outcome, reason, document_id, thread_id, comment_id, request_id }.",
+            "delete <id|slug> [<id|slug>...] — soft-deletes one or more documents (BLI-10555): the browser's own delete, sets deleted_at, never a real SQL DELETE. Recoverable: `cockpit docs trash` lists what you may restore and `cockpit docs restore <id>` brings it back (BLI-21413). Deleting a parent does NOT delete its children; they keep their own parent_id and stay exactly where they were. Each ref is one exact lookup, then one DELETE each — one bad ref never loses the rest. --json shape: one ref answers { ok, document_id }; several answer { documents: [{ ref, ok, document_id } | { ref, ok: false, error, detail }] }.",
+            ...DOCS_RECOVERY_HELP,
+            ...DOCS_INBOX_HELP,
+            ...DOCS_FILES_HELP,
+            ...DOCS_REFS_HELP,
+            ...DOCS_SYNC_HELP,
+            ...DOCS_FORMATTING_HELP,
             "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.",
             "export <id|slug> [--format md|pdf|docx|txt] [--out <path>] — writes the document as a file (ticket 20694): md is the stored Markdown exactly, txt is readable plain text, docx is a Word file with real headings, lists, tables and links, pdf is a paginated page with the title and last-updated date in the header. Default format md; default path is the document's slug plus the extension in the current directory (--out names a file, or a directory to put it in), and an existing file is replaced. Prints the path; --json shape: { ok, path, bytes, format }. To copy a page's text, `cockpit docs read` already does it.",
-            "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
-            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr. A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
-            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`. --json writes one machine-readable object to stdout; every reason and receipt line stays on stderr. A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on. The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
         ],
     ],
     [
         "msg",
         [
-            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|unread <channel> --from <message-id>|send <channel>|edit <message-id>|delete <message-id>|outcome <request-uuid>|thread <id> --channel <channel>|show <message-id>] [flags]",
+            "Usage: cockpit msg [channels|create <name>|dm <email>...|channel <channel>|members <channel>|hide <channel>|unhide <channel>|read <channel>|unread <channel> --from <message-id>|send <channel>|edit <message-id>|delete <message-id>|outcome <request-uuid>|draft [list|show|save|discard|restore|send] <channel>|file upload|show|download|cancel|list|thread <id> --channel <channel>|show <message-id>|activity|follow <message-id>|unfollow <message-id>|react <message-id> <emoji>|notify [set|quiet|receipts]|search [words]|save <message-id>|saved|pin <message-id>|pins <channel>|forward <message-id> --to <channel>|schedule <channel> --at <time>|remind <message-id> --at <time>|scheduled [change|cancel|done <id>]|context <message-id> [--add <kind:id>|--remove <link-id>]] [flags]",
             "",
             "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
             "channels — every channel you are a member of (or, as a super_admin, every channel).",
             "create <name> [--private] [--members a@x.test,b@y.test] [--description \"<text>\"] — makes a channel and prints its id. A leading # is fine; --private means membership decides who may read it, and --members names who joins at birth BY EMAIL. An address Tower does not carry refuses the whole create — no half-built channel.",
             "dm <email> — opens (or re-opens) the direct message with one person. Idempotent: the same address always resolves to the same channel, and you never have to name yourself.",
+            "dm <email> [<email>...] — with several addresses, opens (or re-opens) the group message with exactly those people plus you; the same set always resolves to the same channel. channel <channel> [--json] — the channel's details: name, description, kind, archived, audience (a public channel is everyone in the org, not a member count), source workspace label (where it came from; it grants no access), whether you can manage it, and whether you hid it. channel <channel> --rename <name> | --describe <text> | --archive | --unarchive — changes it (one update; --rename and --describe can go together). Only the person who made the channel, its owners and its moderators can; anyone else is refused channel_manage_refused, a name in use channel_name_taken, a direct message dm_not_editable. Archiving keeps every message and link and stops new posts (channel_archived); unarchive restores posting. members <channel> [--json] — who is in a private channel or a direct message; a public channel says everyone in the org can read it. members <channel> --add <email> | --remove <email> — private channels only, by the same people who can manage it; a removed person's next read is refused. A direct message keeps the people it started with (dm_not_editable): start a new group with `msg dm a@x b@y`. hide <channel> / unhide <channel> — drops a PUBLIC channel from your own sidebar, or puts it back; it changes nothing for anyone else and nothing about reading, search, mentions or notifications. A private channel or direct message is refused hide_not_public.",
             "read <channel> [--limit <n>] [--thread <id>] [--mark-read] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead. The first page also says where the messages come from (for an imported Slack channel: how long ago the archive was checked, or that it is unknown) and where YOUR read line stands. Reading never moves the read line; --mark-read moves it to the newest message shown, and says plainly if that failed.",
             "unread <channel> --from <message-id> — marks that message and everything after it unread, so the web sidebar badge and the NEW MESSAGES line start there. Opening or reading a channel never clears unseen history.",
-            "send <channel> [--thread <id>] [--request-id <uuid>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`. Every send carries a request id (minted when you give none); retry a send whose answer was lost with the SAME --request-id and the same text and it posts once. The same id with different text is refused request_id_reused, not applied as an edit.",
-            "edit <message-id> [--expected-revision <n>] [--request-id <uuid>] — replaces your own message's text (piped in). With --expected-revision, an edit of a message that has moved on is refused revision_conflict and nothing is saved over it; the current revision is printed. A message you did not write, or one that was deleted, is refused by name. delete <message-id> [--expected-revision <n>] [--request-id <uuid>] — deletes by tombstone: the text is cleared and every surface reads \"This message was deleted\", but the row stays so its thread, replies and reply count survive. Search and unread counts ignore it. A repeat answers already_deleted. outcome <request-uuid> — your own write receipt for a send, edit or delete: committed, not_committed (with the reason) or unknown_check_again. Run it after a timeout before retrying.",
+            "send <channel> [--thread <id>] [--request-id <uuid>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`. Every send carries a request id (minted when you give none); retry a send whose answer was lost with the SAME --request-id and the same text and it posts once. The same id with different text is refused request_id_reused, not applied as an edit. send <channel> --file <id> [--file <id>...] — attaches up to 10 ready files (from `msg file upload`) to the message. The text is optional with a file; it is read from stdin only when something is piped in. file upload <channel> <path|-> [--name <name>] — uploads a file of 1 byte to 25 MB straight to storage (reserve, PUT, finalize) and prints its id and state; `-` reads stdin and needs --name. A file is ready, not sent: attach it with `msg send <channel> --file <id>`. file show <id> — the descriptor (state reserved, ready, attached, cancelled or abandoned). file download <id> [--out <path>] — saves the bytes (60-second signed link; never overwrites). file cancel <id> — ends an unattached file and removes its bytes. file list <channel> — your own unsent uploads there, with coverage. A file is readable only by readers of its channel, and only once attached to a live message. Refusals keep the door's reason: file_too_large, file_not_found_or_unreadable, file_not_uploaded, file_not_ready, file_already_attached, file_wrong_channel, storage_unreachable.",
+            "edit <message-id> [--expected-revision <n>] [--request-id <uuid>] — replaces your own message's text (piped in). With --expected-revision, an edit of a message that has moved on is refused revision_conflict and nothing is saved over it; the current revision is printed. A message you did not write, or one that was deleted, is refused by name. delete <message-id> [--expected-revision <n>] [--request-id <uuid>] — deletes by tombstone: the text is cleared and every surface reads \"This message was deleted\", but the row stays so its thread, replies and reply count survive. Search and unread counts ignore it. A repeat answers already_deleted. outcome <request-uuid> — your own write receipt for a send, edit or delete: committed, not_committed (with the reason) or unknown_check_again. Run it after a timeout before retrying. draft [list|show|save|discard|restore|send] <channel> [--thread <id>] [--expected-revision <n>] [--request-id <uuid>] — the text you have not sent yet, one draft per channel and thread, the same drafts the browser autosaves. list shows all your unsent drafts (newest first, with coverage); show prints one; save takes the body on stdin (`echo \"half a thought\" | cockpit msg draft save general`) and with --expected-revision refuses draft_revision_conflict, naming the stored revision, instead of overwriting; discard keeps the text (state discarded) and restore brings it back; send posts the stored draft with a fresh request id (--request-id to retry the same send) and its revision, prints the receipt, and marks the draft sent only if it did not change meanwhile. Only you can read or change your drafts.",
             "thread <id> --channel <channel> [--before <cursor>] [--limit <n>] — one thread's replies by the parent message's id.",
-            "show <message-id> — exact message, thread root and bounded neighbors. read/thread --before takes the preceding nextCursor; repeat until hasMore is false.",
+            "show <message-id> — exact message, thread root and bounded neighbors. read/thread --before takes the preceding nextCursor; repeat until hasMore is false. activity [--mentions|--threads] [--unread] [--before <cursor>] [--limit <n>] [--mark-read] — your Mentions (messages that mention you) and Threads (replies in threads you follow: you started it, replied natively or followed it by hand), newest first, with unread counts and coverage; items whose message you can no longer read are left out and counted as dropped. Nothing is marked read by looking; --mark-read marks the unread items just printed, and the web marks one when its message is shown. Activity covers native Tower messages only, so the Slack import adds none. follow <message-id> / unfollow <message-id> — the id is the thread's top-level message; an explicit unfollow wins over a later auto follow, and earlier items stay. react <message-id> <emoji> [--remove] — adds or takes off your reaction (idempotent). Refusals: thread_root_not_found_or_unreadable, not_a_thread_root, reaction_not_found. notify — your message notification settings (the same ones the web header menu and Settings change): the default level (all, mentions or none; mentions is the default and covers direct messages, @mentions and replies in threads you follow), quiet hours and per-channel overrides. notify set --level <all|mentions|none> changes the default; add --channel <id|name> for one channel, with --mute / --unmute, or --clear to remove the override. notify quiet <HH:MM-HH:MM> [--timezone <zone>] sets quiet hours (24-hour, may wrap midnight; the zone defaults to this machine's) and notify quiet --off removes them. notify receipts [--message <id>] [--before <cursor>] [--limit <n>] lists what was delivered, suppressed or blocked and why (never message text): outcome shown means Tower told a browser tab to show a banner; push_accepted means the push service took the phone push, not that a phone showed it. Quiet hours and levels hold back banners and phone pushes, never the message or its unread badge. Refusals: invalid_notification_level, invalid_quiet_hours, invalid_timezone. search [words] [--from <email|me>]... [--in <channel>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--timezone <IANA>] [--replies|--top-level] [--has-file] [--before <cursor>] [--limit <n>] — message search on your own access, newest first (not ranked; `cockpit search --kind msg` is the ranked bar). Each hit prints its id, channel, author, time and snippet, then `more: --before <cursor>` or `complete`; repeat with the cursor until complete. --from takes an email, a user id or me and repeats; --in takes a channel id or #name (exact after case folding, an ambiguous name is refused); --since and --until are whole local days in --timezone, both inclusive (this machine's zone when you give none). The words may be left out when a filter is set, so `msg search --has-file` finds attachment-only messages. Inline operators work in the words as in the web box: from:<email|me> in:#name after:<day> before:<day> (exclusive) on:<day> has:file is:reply is:root. Recognised but unsupported operators (has:link, has:pin, has:reaction, is:saved, is:dm, to:, with:, during:) are refused unsupported_search_operator, naming the operator; a bad day, zone, person or channel is refused invalid_search_filter. Messages imported from Slack carry no file links, so has:file does not find them. Deleted messages, channels you cannot read and files you cannot read never appear.",
+            "save <message-id> [--remove] — saves a message for yourself (private: nobody else sees your saves) or, with --remove, unsaves it. Idempotent: a repeat answers changed false. A deleted message cannot be saved but can be unsaved. saved [--before <cursor>] [--limit <n>] — your saved messages, newest save first (1 to 100, default 50), with `more: --before <cursor>` or `complete`; a message you can no longer read is left out and counted as dropped, a deleted one shows as deleted so you can unsave it. pin <message-id> [--remove] — pins a message in its channel for everyone who can read it, or unpins it; any member who can read the channel may, and the history records who. A repeat is changed false. Refusals: pin_limit_reached (a channel holds 100 pins), pin_deleted_message, channel_archived (an archived channel's pins stay as they are), message_not_found_or_unreadable. pins <channel> — the channel's pins, newest first, with who pinned and when. forward <message-id> --to <channel> [--thread <id>] [--request-id <uuid>] — posts ONE new message into the destination holding the comment you pipe in (optional) and the source's exact link; no text, author or channel name of the source is copied, and the people who read the destination gain no access to it: its preview shows only to those who can read the source. You must be able to read the source as a member, and it must be live (forward_source_deleted); an archived destination is channel_archived. Retry a forward whose answer was lost with the SAME --request-id and it posts once. Copying a link posts nothing; `msg show <message-id>` returns the exact link and rechecks your access.", "schedule <channel> --at <time> [--timezone <zone>] [--thread <id>] [--request-id <uuid>] — posts the piped text as you at that time, from the server (your laptop can be closed). <time> is an ISO instant with an offset (2026-11-02T09:00:00+07:00) or a wall time \"YYYY-MM-DD HH:MM\" in --timezone (an IANA name such as Asia/Ho_Chi_Minh or America/Toronto; this machine's zone when omitted, and the answer names it). The answer prints the stored instant and zone. 1 minute to 120 days ahead, at most 100 pending per person. A wall time that does not exist (the spring-forward hour) is invalid_schedule_time; an hour that happens twice takes the earlier one. Delivery lands within about a minute of due. If you are no longer a member of the channel by then it fails author_lost_access and keeps the text; see `scheduled --state failed`. remind <message-id> --at <time> [--timezone <zone>] [--note <text, 500 chars>] [--request-id <uuid>] — a reminder about one message. When due it appears under `scheduled --state fired` with the exact link and posts nothing to the channel (no banner, no push). scheduled [--state <pending|sent|failed|cancelled|fired|done|open|all>] [--before <cursor>] [--limit <n>] — your schedules and reminders only (nobody else sees them); open (the default) is pending plus fired, soonest first; the finished states and all list newest first; 1 to 100, default 50, with `more: --before <cursor>` or `complete`. scheduled change <id> [--at <time>] [--timezone <zone>] [--revision <n>] — move a pending schedule and/or pipe in new text; a stale --revision is schedule_revision_conflict. scheduled cancel <id> — cancels a pending one; if it already went out you get schedule_already_sent and the message id. scheduled done <id> — marks a fired reminder done. Refusals: invalid_schedule_time, invalid_timezone, schedule_limit_reached, schedule_not_found, schedule_already_sent, schedule_revision_conflict, request_id_reused. Retry a schedule whose answer was lost with the SAME --request-id and it stores once.", "context <message-id> [--add doc:<id>|ticket:<BLI-id or uuid>|event:<id>[@<iso occurrence>]|note:<id>] [--remove <link-id>] — the Tower docs, tickets, calendar events and meeting notes pointed at from one message. With no flag it lists them (--json prints the door's body: link_id, kind, id, title, href; a ticket also has identifier and state, an event its start). Every target is read again for YOU: one you cannot open is listed as state unavailable with no title, and a link grants no access to its target. --add attaches one; only the message's author may, and the target must be readable by you (otherwise context_target_unavailable, which never says whether it exists). A message holds 10 live links (context_limit_reached); the same target twice is context_already_linked; a non-author is context_not_author. --remove <link-id> (after the message id) removes it softly: the message's author or whoever attached it may, and the history keeps it. context_link_not_found if it is gone. Web shows the same chips under the message; the keys and the Keyboard sheet are web only.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
             "A refusal keeps Tower's own reason label — needs_rls_client, channel_not_found_or_unreadable, content_too_long, and so on.",
             "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
@@ -101,22 +122,27 @@ export const TOWER_COMMAND_HELP = [
     [
         "issue",
         [
-            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|history <id>|versions <id>|restore <id> --version <n>|mutation-status <request-uuid>] [flags]",
+            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|label <id>|relations <id>|relate <id>|unrelate <id>|views [list|show|save|update|favorite|unfavorite|settings]|templates [list|show|versions|save|update|apply]|cycles [list|show|create|update|map]|inbox|read <notification-id>...|unread <notification-id>...|subscribe <id>|unsubscribe <id>|notifications [set|receipts]|history <id>|versions <id>|restore <id> --version <n>|batch|mutation-status <request-uuid>] [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>] [--label <name>] [--q <text>] [--created-after|--created-before|--updated-after|--updated-before <utc instant|date>] [--sort updated_at|created_at] [--dir desc|asc] [--limit <n>] [--cursor <c>] [--all] — the issues you may see, most recently updated first. A page is 100 by default and at most 500. Filters run in the database BEFORE the page, so a label or title match deep in the set is found. --q is a case-insensitive title contains (% and _ are literal); *-after is inclusive, *-before is exclusive. --json adds next_cursor, has_more, coverage (complete|capped|failed_partial), requested, returned, unique: pass next_cursor back as --cursor with the same other flags. --all walks every page and streams ONE JSON OBJECT PER LINE (NDJSON; rows carry assignee_id, no names), then a final {\"type\":\"coverage\",...} line naming the coverage; an interrupted walk ends with coverage failed_partial, the reason and the resume cursor, and exits 1. 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), and a `size` label (S/M/L) alongside the raw `estimate` when it matches Tower's own scale (BLI-10575). --json shape: { issues: [{ id, identifier, title, state, priority, estimate, size, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
             "board [--json] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <uuid>] [--label <name>] [--rows <state:n,...>] — the Tickets board, counts, coverage and top five cards per column, through GET /api/work/board. Also cockpit tickets board.",
             "show <id> [<id>...] — one or more issues: title, state, priority, size, 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 (plus `estimate`/`size`, BLI-10575). Several ids answer { issues: [{ ref, ok, issue, comments } | { ref, ok: false, error, detail }] }.",
-            "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--size S|M|L] [--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. --size maps onto the existing `estimate` column, Tower's own scale: S=1, M=3, L=5 (BLI-10575) — an estimate outside that scale (an imported Linear point value, say) just has no size label on a read. --json shape: { issue }.",
-            "update <id> [--title \"<t>\"] [--priority 0-4] [--size S|M|L] [--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.",
+            "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--size S|M|L] [--assignee me|<uuid>] [--parent <id>] [--state <state>] [--due YYYY-MM-DD] [--file <path>] — --state is the starting state (default backlog); --due sets a due date. The DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description. --size maps onto the existing `estimate` column, Tower's own scale: S=1, M=3, L=5 (BLI-10575) — an estimate outside that scale (an imported Linear point value, say) just has no size label on a read. --json shape: { issue }.",
+            "update <id> [--title \"<t>\"] [--priority 0-4] [--size S|M|L] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--due YYYY-MM-DD|none] [--file <path>|--body-stdin] — only the fields you pass change: a field you leave off is never touched. --due none clears the due date; --assignee none clears the owner. A size already on the ticket that is not S, M or L (an imported estimate such as 8) stays as it is until you pass --size. State does NOT move here; use move. --json shape: { issue }.",
+            "label <id> [--add <label>]... [--remove <label>]... [--request-id <uuid>] [--expected-revision <n>] — adds and removes EXISTING labels (names match exactly, ignoring case; a uuid also works) in one receipt, one history row and one revision step. An unknown name is refused by name and nothing changes; labels are never created here. Any member may detach. --json shape: { issue, labels, mutation }. relations <id> [--json] — what blocks what: Blocks, Blocked by, Related, Duplicate of, Duplicates, and Not in Tower (an imported Linear edge to a ticket Tower does not have, shown as text). A sub-ticket is NOT a blocker and is not listed here. Edges to a deleted or unreadable ticket are left out and counted (coverage.hidden). --json shape: { relations: { blocks, blocked_by, related, duplicates, duplicate_of, unmapped, coverage } }, each item { relation_id, kind, source: native|linear, issue: { id, identifier, title, state } }. relate <id> --blocks <id> | --blocked-by <id> | --related <id> | --duplicate-of <id> [--request-id <uuid>] [--expected-revision <n>] — exactly one kind flag; records one edge as one receipt, one history row and one revision step (--blocked-by stores the edge from the other ticket). Refusals by name: relation_exists, relation_inverse_blocks, relation_self, relation_target_not_found_or_unreadable. unrelate <id> --relation <relation-id> | the same kind flag plus the other ticket — removes the edge (kept as removed, never re-imported). Refusal: relation_not_found. Setting --parent so a ticket would sit under its own sub-ticket is refused as circular_parent, a chain deeper than 200 as hierarchy_too_deep. --json shape: { issue, relation_id, mutation }. Also: 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`.",
             "Writes accept --request-id <uuid> and --expected-revision <n>. Keep the UUID and identical fields across retries; JSON includes mutation receipt and mirror delivery separately.",
             "mutation-status <request-uuid> — check your own local commit and mirror delivery after a lost response; no receipt means unknown_check_again.",
             "history <id> [--limit <n>] [--cursor <c>] — every recorded state move and reassignment, oldest first; --json carries the same page fields as list.",
             "versions <id> [--limit <n>] — every saved description, newest first, each with its number, id, author, source and time (BLI-21300). --json shape: { versions: [{ id, version, markdown, author_id, source, restored_from_version, created_at }] }.",
-            "restore <id> --version <n> [--request-id <uuid>] [--expected-revision <n>] — writes version <n>'s text back as a NEW version; nothing is rewritten, so the restore can itself be undone. A stale revision conflicts and changes nothing. --json shape: { issue, mutation }.",
+            "restore <id> --version <n> [--request-id <uuid>] [--expected-revision <n>] — writes version <n>'s text back as a NEW version; nothing is rewritten, so the restore can itself be undone. A stale revision conflicts and changes nothing. --json shape: { issue, mutation }. batch [--file <path>] [--request-id <uuid>] — changes up to 50 tickets in one call (BLI-21551). Reads { \"items\": [...] } (or a bare array) from stdin or --file, never argv. Each item is { issue, expected_revision?, request_id?, state? | priority? | assignee? | size? | project? | due_date? }: a state move OR field changes, not both, and one item per ticket. It is NOT all-or-nothing: every item is its own change with its own receipt, one stderr line each. Exit 0 only when every item committed, 1 otherwise; the batch request id is printed, and a retry with --request-id writes nothing twice. --json shape: { ok, request_id, requested, committed, refused, unknown, items: [{ index, issue, outcome, reason?, message?, request_id, revision?, row? }] }. Example: echo '{\"items\":[{\"issue\":\"BLI-1\",\"priority\":2},{\"issue\":\"BLI-2\",\"state\":\"done\"}]}' | cockpit ticket batch --json.",
+            ...VIEWS_HELP_LINES,
+            ...TEMPLATES_HELP_LINES,
+            ...CYCLES_HELP_LINES,
+            ...INBOX_HELP_LINES,
+            ...WORK_NOTIFY_HELP_LINES,
             "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
             "--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, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
@@ -153,7 +179,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "cal",
         [
-            'Usage: cockpit cal [event <id>|export <id>|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|view-settings|view-settings-change|next|find "<words>"|calendars|add-ical|create|duplicate <event id>|batch|undo [<change id>]|rsvp <event id> --response <accepted|declined|tentative>|change <event id>|cancel <event id> --yes|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes] [flags]',
+            'Usage: cockpit cal [event <id>|export <id>|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|view-settings|view-settings-change|people <label>|availability --with <label|email> --from <d> --to <d>|overlays [--pin <label|email>|--remove <email>]|suggest --with <label|email> --from <d> --to <d>|availability-share --range <start>/<end> [--link]|availability-revoke <id>|booking-page [--list|--id <id>]|booking-slots <link>|book <link> --start <iso> --name <n> --email <e>|booking-change <manage link> --start <iso>|booking-cancel <manage link>|next|find "<words>"|calendars|add-ical|create [--recheck]|duplicate <event id>|batch|undo [<change id>]|rsvp <event id> --response <accepted|declined|tentative>|change <event id>|cancel <event id> --yes|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes|remind|join [--event <id> --occurrence <iso>] [--print]|reminders [--on|--off] [--lead <min>] [--sound on|off]|snooze <event id> --occurrence <iso> --minutes <5|10|15>|dismiss <event id> --occurrence <iso>|links <event id> [--occurrence <iso>] [--add doc:<id>|note:<id> [--series]] [--remove <link id>]|agenda [--from <d> --to <d>]] [flags]',
             "",
             "Every calendar you attached, in one place — plus any calendar a colleague marked shared.",
             "today [--offset 1] [--tz <zone>] — what is on today, in YOUR zone (this machine's, unless --tz says otherwise). --offset 1 is tomorrow, -1 yesterday.",
@@ -163,7 +189,7 @@ export const TOWER_COMMAND_HELP = [
             "conflicts [--from <iso> --to <iso>] [--tz <IANA>] — own-account double-bookings with duplicate invitation merging, checked calendars and age. Visible calendars only by default; --all includes hidden calendars. All-day and free events never conflict.",
             "event <id> [--occurrence-start <iso>] [--tz <zone>] [--json] — exact occurrence details, human recurrence, named guests/RSVP, organizer, source zone, HTTPS Join and edit capability. The selector must match a real occurrence; cancelled/missing instances are refused.",
             "export <id> [--occurrence-start <iso>] [--json] — iCalendar text to stdout; redirect to event.ics. Recurring exports include the complete series and exceptions, keeping source zone/recurrence. No calendar credentials.",
-            "calendar-change <id> --color <hex|provider> — persistent owner colour override, or reset to provider colour. Also accepts stdin JSON {color_override, selected}. History is retained. view-settings [--json] reads your saved view settings (default view, N days, week start, weekends, density, up to 3 extra time zones) plus the calendar actions and keyboard shortcuts; never saved means the defaults, said so. view-settings-change [--view day|week|days|month] [--days 2-9] [--week-start monday|sunday] [--hide-weekends on|off] [--density normal|compact] [--zone <IANA>]... changes only what you name; --zone repeats (up to 3), --zone none clears; stdin JSON like {\"day_count\":4} works too.",
+            "calendar-change <id> --color <hex|provider> — persistent owner colour override, or reset to provider colour. Also accepts stdin JSON {color_override, selected}. History is retained. view-settings [--json] reads your saved view settings (default view, N days, week start, weekends, density, up to 3 extra time zones) plus the calendar actions and keyboard shortcuts; never saved means the defaults, said so. view-settings-change [--view day|week|days|month] [--days 2-9] [--week-start monday|sunday] [--hide-weekends on|off] [--density normal|compact] [--zone <IANA>]... changes only what you name; --zone repeats (up to 3), --zone none clears; stdin JSON like {\"day_count\":4} works too. people <label> [--json] — exact team search: a display name or alias (any case) or an email; an address nobody on the team owns comes back as typed. No fuzzy, prefix or nickname match; an ambiguous label lists every match. availability --with <label|email> [--with ...] --from <d> --to <d> [--tz <IANA>] [--account <id>] [--json] — when people are BUSY, start and end only, asked of Google with your own grant (up to 100 people, 31 days). A person Google will not answer for is unknown, never free. Stdin JSON {with|emails, from, to, tz, account_id} works too. overlays — the people pinned on your calendar (at most 10). overlays --pin <label|email> pins one, overlays --remove <email> drops one; history is kept. The web calendar shows pinned people's busy time. suggest --with <label|email> [--with ...] --from <d> --to <d> [--duration 30] [--hours 09:00-17:00] [--weekends] [--tz <IANA>] [--account <id>] [--limit <n>] [--json] — ranked common free slots for several people (up to 10 shown, 50 max; 15 to 480 minutes): everyone free first, then outside someone's local hours, then slots with an unknown person (never shown as free); Tower defaults (30 minutes, 09:00 to 17:00 your zone, no weekends) are named when used; stdin JSON works. create --recheck re-reads everyone's busy time just before writing and refuses with the reason (slot_taken, slot_unconfirmed) instead of double-booking. availability-share --range <start>/<end> [--range ...] [--duration 30] [--tz <IANA>] [--text|--link] [--expires <iso>] [--location <where>] [--meet] [--single-use] [--allow-conflicts] [--label <s>] [--json] offers your free time inside the ranges (a time without an offset is read in --tz; your own busy time is skipped unless --allow-conflicts): --text (default) prints words to paste, stores nothing, names the zone and the time it was made; --link stores a revocable link (14 days by default, 90 at most) whose times are rechecked on every open and prints the URL ONCE; a repeat of the same --key gives no second link. --list shows your links; --id <id> with --expires or --label changes one; availability-revoke <id> turns one off. Stdin JSON works. If your own calendars could not be fully read it says so. booking-page --title <t> --weekly mon/09:00-12:00 [--weekly ...] [--duration 30] [--buffer-before 0] [--buffer-after 0] [--notice 240] [--window 14] [--meet] [--location <s>] [--single-use] [--tz <IANA>] makes a public booking page on your own Google calendar (30 minutes, no buffers, 4 hours notice, 14 days by default; up to 21 weekly ranges) and prints its link ONCE; --list shows pages and upcoming bookings; --id <id> with --rotate, --close|--open or any field above changes one; stdin JSON works. A guest (no Tower login needed) runs booking-slots <link>, book <link> --start <slot start> --name <n> --email <e> [--note <s>] (3 upcoming bookings per email per page), booking-change <manage link> --start <iso> (the old manage link stops working; the new one shows once) and booking-cancel <manage link>; the manage link expires when the meeting starts. Laptop reminders (slice 11): reminders shows or sets your switch (--on|--off, --lead 0 to 60 minutes, default 10, --sound on|off); they are OFF until you turn them on. Once on, a scheduled `cockpit cal remind` tick (every minute, installed with the sync agent) shows one TOWER banner per meeting per lead time across all your laptops, never one for a meeting you declined or that was cancelled, and records a banner more than 5 minutes late as missed. join opens the link of the meeting running now or starting within 15 minutes (or --event <id> --occurrence <iso>); --print only prints it; a missing or non-https link is refused by name. snooze <event id> --occurrence <iso> --minutes 5|10|15 and dismiss <event id> --occurrence <iso> change one nudge. next leaves out meetings you declined (the door takes ?declined=1 to keep them). Event links (slice 12): links <event id> [--occurrence <iso>] lists YOUR docs and meeting notes linked to that occurrence plus its series, each read again for you (a doc or note you can no longer open prints as unavailable, no title), a note showing its status and recording, alternate and missed counts, and suggests notes the bot recorded for exactly this event (never by title); --add doc:<id>|note:<id> --occurrence <iso> (or --series for every occurrence) attaches one you can read now (20 per event; a repeat is already_linked); --remove <link id> removes it and the history keeps it. A link is private to you and gives attendees no access. agenda [--from <d> --to <d>] [--tz <IANA>] [--json] lists events plus tickets due in the window as DUE lines (all-day markers, never busy time, never sent to Google), with how many rows were read.",
             "calendars — every calendar, its provider (google_oauth or ical_url), whether it is shared, and when it last synced. The ids other verbs take are on the last line.",
             "add-ical [--name \"<what to call it>\"] — attaches a personal calendar by its SECRET iCal ADDRESS, read from stdin. There is no flag for it:",
             '      macOS:      printf "%s" "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"',
@@ -189,17 +215,7 @@ export const TOWER_COMMAND_HELP = [
             "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
         ],
     ],
-    [
-        "project",
-        [
-            "Usage: cockpit project [list] [--archived] [--limit <n>] [--cursor <c>] [--json]",
-            "",
-            "The projects issues are filed under. Bare `cockpit project` lists them.",
-            "list [--archived] [--limit <n>] [--cursor <c>] — id, active/archived, name. --archived includes archived projects. A page is at most 500; when more exist the output (and --json: next_cursor, has_more, coverage, requested, returned, unique) carries the cursor to pass back as --cursor.",
-            "There is no create/update/delete verb: `GET /api/work/projects` is the whole of Tower's project door today.",
-            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-        ],
-    ],
+    PROJECT_HELP,
     [
         "speed",
         [
@@ -265,7 +281,7 @@ export const TOWER_COMMAND_HELP = [
             "--categories prints the list Tower offers THIS account, in the order the browser's Command-K",
             "chips use, so the names are never a guess; an unknown --kind is refused by the door with that list.",
             "Omit --kind and every category is searched.",
-            "--limit caps the number of results (default 20, maximum 50).",
+            "--limit caps the number of results (default 20, maximum 50). Document filters (--by, --under, --since, --until, --timezone, --sort, --title-only, --word) work only with --kind doc and mean what they do in `cockpit docs search`; the answer says degraded.doc = filtered_lexical_only. Message filters (--from, --in, --since, --until, --timezone, --replies, --top-level, --has-file) work only with --kind msg and mean what they do in `cockpit msg search`; any other --kind is refused msg_filters_need_msg_kind. Filtered messages come from keyword matching only (the answer says filtered_lexical_only), newest first and not ranked; the words may be left out. Page them with `cockpit msg search --before <cursor>`. Usage: cockpit search [\"<words>\"] --kind msg [--from <email|me>]... [--in <channel>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--timezone <IANA>] [--replies|--top-level] [--has-file].",
             "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
             "",
             "Every result is scoped by what YOU may read: most corpora (and Careers always) are searched on",

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

@@ -23,6 +23,7 @@ import { TOWER_OPS_COMMAND_HELP } from "./local-help-commands-tower-ops.js";
 /** One manual per collector command; the Tower nouns are spread in from their own file. */
 const COMMAND_HELP = new Map([
     ["glossary", ["Usage: cockpit glossary list|add <wrong> --to <name>|remove <wrong> [--json]", "Quote phrases. Removing a form prevents future corrections of it."]],
+    ["push", ["Usage: cockpit push status | test [--dashboard-url <url>] [--json]", "Phone notifications. status lists your saved devices and whether the server has its push keys; test sends a test push to every saved device. Turn a phone on from Settings on the phone."]],
     ["spend", ["Usage: cockpit spend memory [--days 1|7|30] [--dashboard-url <url>] [--json]", "Spend by memory operation (write, recall, dream, update_forget, backfill, label, exam, predictor, people, who, intentions, salience, chat, other), ranked top first with list and real dollars, share, trend against the previous window, and how much of the real OpenAI bill the ledger explains. What it does not explain is shown as untagged. A super_admin reads it."]],
     ["roots", ["Usage: cockpit roots add <dir> [--allow-home-root] [--json]", "Approves a work directory, saves an approval receipt, and adds it to collection. Run cockpit doctor afterward."]],
     // BLI-3709: the Tower nouns live next door, split along the same seam the

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

@@ -0,0 +1,9 @@
+/** `cockpit ticket cycles` help (BLI-21809, P12), one line a verb, joined into the `issue` help. */
+export const CYCLES_HELP_LINES = [
+    "cycles [list] [--phase upcoming|active|ended|closed] [--limit <n>] [--cursor <c>] — native cycles, dates shown with their timezone. --json shape: { cycles: [{ id, name, description, starts_on, ends_on, timezone, starts_at, ends_at, phase, closed_at, linear_cycle_id, updated_at }], next_cursor, has_more, coverage, requested, returned, unique }.",
+    "cycles show <id|name> — one cycle, its factual progress (done, canceled, open, points and how many tickets carry an estimate), the imported-but-unassigned count when known, and its tickets. A name is exact and case-insensitive; two cycles with one name are cycle_ref_ambiguous and the message lists their ids (use an id). --json shape: { cycle, progress, imported_unassigned, issues, next_cursor, has_more, coverage, href }.",
+    "cycles create --name \"<n>\" --starts YYYY-MM-DD --ends YYYY-MM-DD [--timezone <IANA zone>] [--description <text|->] [--request-id <uuid>] — makes a cycle. `--description -` reads the text from stdin. The same --request-id returns the same cycle.",
+    "cycles update <id|name> [--name <n>] [--starts <day>] [--ends <day>] [--timezone <zone>] [--description <text|-|none>] [--expected-updated-at <ts>] [--request-id <uuid>] — changes only the fields you give. `cycles update <ref> --close` or `--reopen` travels alone: a closed cycle refuses new tickets (cycle_closed). A stale --expected-updated-at is revision_conflict.",
+    "cycles map <linear-cycle-id> [--request-id <uuid>] — links an imported Linear cycle to a native one so it is never merged by name. It never moves a ticket; assign tickets with `ticket update <id> --cycle <name|id>`.",
+    "ticket create|update --cycle <name|id> — puts the ticket in a cycle; `update --cycle none` takes it out. Refusals: cycle_closed, cycle_ref_ambiguous, cycle_not_found_or_unreadable.",
+];

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

@@ -0,0 +1,10 @@
+/**
+ * The `cockpit docs files|file` lines of the docs `--help` (BLI-21786), split from `local-help-commands-tower.ts`
+ * to keep that file under the readability ratchet.
+ */
+export const DOCS_FILES_HELP = [
+    "files <id|slug> — the page's files, newest first (a page keeps its files: png, jpeg, gif, webp inline; pdf, txt, md, csv, json, zip, svg as downloads). Anyone who can read the page lists them; a page you cannot read is document_not_found_or_unreadable. Shows `can_edit` for you, and `coverage` (complete, or capped at 100). --json shape: { ok, document_id, files: [{ id, name, media_type, byte_size, alt_text, state, image, href, markdown, created_at }], coverage, returned, can_edit }.",
+    "file upload <id|slug> <path> [--alt <text>] — attaches a local file to a page you may edit (at most 25 MB, 26,214,400 bytes): reserve, PUT the bytes straight to storage, finish. Prints the Markdown to paste into the body (`![alt](/api/docs/attachments/<id>/download?inline=1)` for an image, `[name](/api/docs/attachments/<id>/download)` otherwise); it edits NO body, so add the line with `docs update`. Labels, verbatim: attachment_too_large, attachment_type_refused, attachment_write_refused, storage_unreachable, attachment_not_uploaded. --json shape: { ok, file: { id, state, markdown, href, ... } }.",
+    "file show <fileId> | file remove <fileId> — the descriptor, or a soft remove (the row becomes `removed`, the bytes are kept, a reader of the page sees \"This file was removed\"). Remove needs edit rights on the page: a plain reader gets attachment_write_refused. A file on a page you cannot read is attachment_not_found_or_unreadable. Removing twice answers the same.",
+    "file download <fileId> [--out <path>] — fetches the bytes through a 60-second signed link that Tower checks against the page's access every time. Never overwrites: an existing path is out_exists. Prints the path and size. --json shape: { ok, file, path, bytes }.",
+];