@bli-cockpit/cli 0.2.237 → 0.2.239

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

@@ -18,6 +18,7 @@
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 import { estimateForSize } from "./issue-contracts.js";
 const ISSUE_ACTIONS = new Set([
+    "mutation-status",
     "board",
     "list",
     "show",
@@ -26,14 +27,19 @@ const ISSUE_ACTIONS = new Set([
     "move",
     "comment",
     "history",
+    "versions",
+    "restore",
 ]);
 /** Every verb except `list` and `create` names ONE issue first. */
 const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
+    "mutation-status",
     "show",
     "update",
     "move",
     "comment",
     "history",
+    "versions",
+    "restore",
 ]);
 /**
  * The closed state vocabulary, copied verbatim from
@@ -45,43 +51,60 @@ const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
  */
 export const ISSUE_STATES = ["backlog", "todo", "in_progress", "in_review", "done", "canceled"];
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ISSUE_ALLOWED_FLAGS = [
+    "--request-id",
+    "--expected-revision",
+    "--home",
+    "--dashboard-url",
+    "--state",
+    "--assignee",
+    "--project",
+    "--label",
+    "--rows",
+    "--limit",
+    "--title",
+    "--priority",
+    "--size",
+    "--parent",
+    "--file",
+    "--version",
+    "--body-stdin",
+    "--json",
+];
+const ISSUE_VALUE_FLAGS = [
+    "--request-id",
+    "--expected-revision",
+    "--home",
+    "--dashboard-url",
+    "--state",
+    "--assignee",
+    "--project",
+    "--label",
+    "--rows",
+    "--limit",
+    "--title",
+    "--priority",
+    "--size",
+    "--parent",
+    "--file",
+    "--version",
+];
 export function parseIssueArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: [
-            "--home",
-            "--dashboard-url",
-            "--state",
-            "--assignee",
-            "--project",
-            "--label",
-            "--rows",
-            "--limit",
-            "--title",
-            "--priority",
-            "--size",
-            "--parent",
-            "--file",
-            "--body-stdin",
-            "--json",
-        ],
-        valueFlags: [
-            "--home",
-            "--dashboard-url",
-            "--state",
-            "--assignee",
-            "--project",
-            "--label",
-            "--rows",
-            "--limit",
-            "--title",
-            "--priority",
-            "--size",
-            "--parent",
-            "--file",
-        ],
+        allowedFlags: ISSUE_ALLOWED_FLAGS,
+        valueFlags: ISSUE_VALUE_FLAGS,
     });
     const { action, rest } = readIssueAction(values);
     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");
+    if (requestId && !UUID_PATTERN.test(requestId))
+        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.");
+    }
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
     const title = readIssueTitle(action, values);
@@ -95,13 +118,14 @@ export function parseIssueArgs(args) {
     const estimate = readIssueSize(values);
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
-    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit);
+    const versionNumber = readIssueVersion(action, values);
+    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber);
 }
 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, or history.`);
+        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, history, versions, restore, or mutation-status.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -189,16 +213,28 @@ function readIssueAssignee(action, values) {
     }
     return assignee;
 }
+/** `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");
+    if (action === "restore" && version === undefined) {
+        throw new Error("issue restore needs --version <n>; list them with `cockpit ticket versions <id>`.");
+    }
+    if (version !== undefined && action !== "restore")
+        throw new Error("--version belongs to `cockpit ticket restore`.");
+    return version;
+}
 function readIssueLimit(action, values) {
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
-    if (limit !== undefined && action !== "list" && action !== "history") {
-        throw new Error("--limit belongs to `cockpit issue list` or `cockpit issue history`.");
+    if (limit !== undefined && action !== "list" && action !== "history" && action !== "versions") {
+        throw new Error("--limit belongs to `cockpit issue list`, `history` or `versions`.");
     }
     return limit;
 }
-function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit) {
+function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber) {
     return {
         kind: "issue",
+        requestId: optionalNonEmpty(values.flags.get("--request-id")),
+        expectedRevision: optionalPositiveInteger(values.flags.get("--expected-revision"), "--expected-revision"),
         action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
@@ -211,6 +247,7 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
         rows: optionalNonEmpty(values.flags.get("--rows")),
         project: optionalNonEmpty(values.flags.get("--project")),
         ...(limit === undefined ? {} : { limit }),
+        ...(versionNumber === undefined ? {} : { versionNumber }),
         title,
         ...(priority === undefined ? {} : { priority }),
         ...(estimate === undefined ? {} : { estimate }),

package/dist/commands/local-args.js

@@ -31,6 +31,82 @@ export { normalizeUrl } from "./local-arg-values.js";
 // parser import them from this path.
 export { DOCTOR_SETUP_ALIASES, } from "./local-command-shapes.js";
 export { SCOUT_MIN_PREFIX_LENGTH, SLACK_WORKSPACE_KEYS, WORKBOOK_MIN_WIDTH, ISSUE_STATES, } from "./local-args-tower.js";
+/**
+ * Which decision table reads the rest of `argv`, by the first word. A word
+ * absent from this table is "Unknown local command". Every entry is a thunk
+ * so an import cycle cannot hand the table an undefined parser at load time.
+ */
+const COMMAND_PARSERS = new Map([
+    ["roots", (_command, rest) => parseRootsArgs(rest)],
+    ["onboard", (_command, rest) => parseOnboardArgs(rest)],
+    ["update", (command, rest) => parseUpdateArgs(command, rest)],
+    ["upgrade", (command, rest) => parseUpdateArgs(command, rest)],
+    // NOT yet aliased to the convergence command. `onboard --ticket <id>` binds
+    // work to a ticket, and routing it here would accept the flag and drop the
+    // binding with no error — the silent breakage BLI-2490 explicitly forbids.
+    // Aliasing lands once the convergence run honours --ticket. See BLI-2494.
+    ["do-everything", (command, rest) => parseDoctorArgs(command, rest)],
+    ["fix", (command, rest) => parseDoctorArgs(command, rest)],
+    // BLI-3768: `doctor` is what the ops board's RED rows, the setup receipt
+    // and the heartbeat all tell a person to run. It routes here exactly like
+    // `fix` — the check table diagnoses, then converges.
+    ["doctor", (command, rest) => parseDoctorArgs(command, rest)],
+    ["install", (_command, rest) => parseInstallArgs(rest)],
+    ["login", (_command, rest) => parseLoginArgs(rest)],
+    ["pair", (_command, rest) => parseLoginArgs(rest)],
+    ["logout", (_command, rest) => parseLogoutArgs(rest)],
+    ["start", (_command, rest) => parseStartArgs(rest)],
+    ["sync", (_command, rest) => parseSyncArgs(rest)],
+    ["analyze", (_command, rest) => parseAnalyzeArgs(rest)],
+    ["jarvis", (_command, rest) => parseJarvisArgs(rest)],
+    ["model", (_command, rest) => parseModelArgs(rest)],
+    ["models", (_command, rest) => parseModelsArgs(rest)],
+    ["scout", (_command, rest) => parseScoutArgs(rest)],
+    ["ci", (_command, rest) => parseCiArgs(rest)],
+    ["ops", (_command, rest) => parseOpsArgs(rest)],
+    ["slack", (_command, rest) => parseSlackArgs(rest)],
+    ["settings", (_command, rest) => parseSettingsArgs(rest)],
+    ["team", (_command, rest) => parseTeamArgs(rest)],
+    ["workbook", (_command, rest) => parseWorkbookArgs(rest)],
+    ["brief", (_command, rest) => parseBriefArgs(rest)],
+    ["correct", (_command, rest) => parseCorrectArgs(rest)],
+    ["notes", (_command, rest) => parseNotesArgs(rest)],
+    ["backfill", (_command, rest) => parseBackfillArgs(rest)],
+    ["status", (_command, rest) => parseStatusArgs(rest)],
+    ["sessions", (_command, rest) => parseSessionsArgs(rest)],
+    ["serve", (_command, rest) => parseServeArgs(rest)],
+    ["autostart", (_command, rest) => parseAutostartArgs(rest)],
+    ["agent-rules", (_command, rest) => parseAgentRulesArgs(rest)],
+    ["memory", (_command, rest) => parseMemoryArgs(rest)],
+    ["clean", (_command, rest) => parseCleanArgs(rest)],
+    ["sources", (_command, rest) => parseSourcesArgs(rest)],
+    ["glossary", (_command, rest) => parseGlossaryArgs(rest)],
+    ["spend", (_command, rest) => parseSpendArgs(rest)],
+    ["docs", (_command, rest) => parseDocsArgs(rest)],
+    ["msg", (_command, rest) => parseMsgArgs(rest)],
+    ["issue", (_command, rest) => parseIssueArgs(rest)],
+    ["mail", (_command, rest) => parseMailArgs(rest)],
+    ["cal", (_command, rest) => parseCalArgs(rest)],
+    ["project", (_command, rest) => parseProjectArgs(rest)],
+    ["search", (_command, rest) => parseSearchArgs(rest)],
+    ["github", (_command, rest) => parseGithubArgs(rest)],
+    ["release", (_command, rest) => parseReleaseArgs(rest)],
+    ["careers", (_command, rest) => parseCareersArgs(rest)],
+    ["rename", (_command, rest) => parseRenameArgs(rest)],
+    ["setup", (_command, rest) => parseSetupArgs(rest)],
+    ["usage", (_command, rest) => parseUsageArgs(rest)],
+    ["speed", (_command, rest) => parseSpeedArgs(rest)],
+    ["logs", (_command, rest) => parseLogsArgs(rest)],
+    ["brain", (_command, rest) => parseBrainArgs(rest)],
+    ["hits", (_command, rest) => parseHitsArgs(rest)],
+    ["intentions", (_command, rest) => parseIntentionsArgs(rest)],
+    ["who", (_command, rest) => parseWhoArgs(rest)],
+    ["people", (_command, rest) => parsePeopleArgs(rest)],
+    ["approvals", (_command, rest) => parseApprovalsArgs(rest)],
+    ["drills", (_command, rest) => parseDrillsArgs(rest)],
+    ["manager", (_command, rest) => parseManagerArgs(rest)],
+    ["image", (_command, rest) => parseImageArgs(rest)],
+]);
 export function parseLocalArgs(argv) {
     // BLI-10431: a Tower page name (`work`, `calendar`, ...) is the same parser
     // as the noun that serves the page — a second spelling, never a second door.
@@ -38,133 +114,8 @@ export function parseLocalArgs(argv) {
     if (aliasTarget)
         return parseLocalArgs([aliasTarget, ...argv.slice(1)]);
     const command = argv[0];
-    switch (command) {
-        case "roots": return parseRootsArgs(argv.slice(1));
-        case "onboard":
-            return parseOnboardArgs(argv.slice(1));
-        case "update":
-        case "upgrade":
-            return parseUpdateArgs(command, argv.slice(1));
-        // NOT yet aliased to the convergence command. `onboard --ticket <id>` binds
-        // work to a ticket, and routing it here would accept the flag and drop the
-        // binding with no error — the silent breakage BLI-2490 explicitly forbids.
-        // Aliasing lands once the convergence run honours --ticket. See BLI-2494.
-        case "do-everything":
-        case "fix":
-        // BLI-3768: `doctor` is what the ops board's RED rows, the setup receipt
-        // and the heartbeat all tell a person to run. It routes here exactly like
-        // `fix` — the check table diagnoses, then converges.
-        case "doctor":
-            return parseDoctorArgs(command, argv.slice(1));
-        case "install":
-            return parseInstallArgs(argv.slice(1));
-        case "login":
-        case "pair":
-            return parseLoginArgs(argv.slice(1));
-        case "logout":
-            return parseLogoutArgs(argv.slice(1));
-        case "start":
-            return parseStartArgs(argv.slice(1));
-        case "sync":
-            return parseSyncArgs(argv.slice(1));
-        case "analyze":
-            return parseAnalyzeArgs(argv.slice(1));
-        case "jarvis":
-            return parseJarvisArgs(argv.slice(1));
-        case "model":
-            return parseModelArgs(argv.slice(1));
-        case "models":
-            return parseModelsArgs(argv.slice(1));
-        case "scout":
-            return parseScoutArgs(argv.slice(1));
-        case "ci": return parseCiArgs(argv.slice(1));
-        case "ops":
-            return parseOpsArgs(argv.slice(1));
-        case "slack":
-            return parseSlackArgs(argv.slice(1));
-        case "settings":
-            return parseSettingsArgs(argv.slice(1));
-        case "team":
-            return parseTeamArgs(argv.slice(1));
-        case "workbook":
-            return parseWorkbookArgs(argv.slice(1));
-        case "brief":
-            return parseBriefArgs(argv.slice(1));
-        case "correct":
-            return parseCorrectArgs(argv.slice(1));
-        case "notes":
-            return parseNotesArgs(argv.slice(1));
-        case "backfill":
-            return parseBackfillArgs(argv.slice(1));
-        case "status":
-            return parseStatusArgs(argv.slice(1));
-        case "sessions":
-            return parseSessionsArgs(argv.slice(1));
-        case "serve":
-            return parseServeArgs(argv.slice(1));
-        case "autostart":
-            return parseAutostartArgs(argv.slice(1));
-        case "agent-rules":
-            return parseAgentRulesArgs(argv.slice(1));
-        case "memory":
-            return parseMemoryArgs(argv.slice(1));
-        case "clean":
-            return parseCleanArgs(argv.slice(1));
-        case "sources":
-            return parseSourcesArgs(argv.slice(1));
-        case "glossary":
-            return parseGlossaryArgs(argv.slice(1));
-        case "spend":
-            return parseSpendArgs(argv.slice(1));
-        case "docs":
-            return parseDocsArgs(argv.slice(1));
-        case "msg":
-            return parseMsgArgs(argv.slice(1));
-        case "issue":
-            return parseIssueArgs(argv.slice(1));
-        case "mail":
-            return parseMailArgs(argv.slice(1));
-        case "cal":
-            return parseCalArgs(argv.slice(1));
-        case "project":
-            return parseProjectArgs(argv.slice(1));
-        case "search":
-            return parseSearchArgs(argv.slice(1));
-        case "github":
-            return parseGithubArgs(argv.slice(1));
-        case "release":
-            return parseReleaseArgs(argv.slice(1));
-        case "careers":
-            return parseCareersArgs(argv.slice(1));
-        case "rename":
-            return parseRenameArgs(argv.slice(1));
-        case "setup":
-            return parseSetupArgs(argv.slice(1));
-        case "usage":
-            return parseUsageArgs(argv.slice(1));
-        case "speed":
-            return parseSpeedArgs(argv.slice(1));
-        case "logs":
-            return parseLogsArgs(argv.slice(1));
-        case "brain":
-            return parseBrainArgs(argv.slice(1));
-        case "hits":
-            return parseHitsArgs(argv.slice(1));
-        case "intentions":
-            return parseIntentionsArgs(argv.slice(1));
-        case "who":
-            return parseWhoArgs(argv.slice(1));
-        case "people":
-            return parsePeopleArgs(argv.slice(1));
-        case "approvals":
-            return parseApprovalsArgs(argv.slice(1));
-        case "drills":
-            return parseDrillsArgs(argv.slice(1));
-        case "manager":
-            return parseManagerArgs(argv.slice(1));
-        case "image":
-            return parseImageArgs(argv.slice(1));
-        default:
-            throw new Error(`Unknown local command: ${command ?? ""}`);
-    }
+    const parse = command === undefined ? undefined : COMMAND_PARSERS.get(command);
+    if (!parse)
+        throw new Error(`Unknown local command: ${command ?? ""}`);
+    return parse(command ?? "", argv.slice(1));
 }

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

@@ -210,13 +210,24 @@ export const TOWER_OPS_COMMAND_HELP = [
     [
         "manager",
         [
-            "Usage: cockpit manager <clients|client|run|list|queue|show|add|edit|done|reopen|link|approve|dismiss|proposal|archive|unarchive> ... [--dashboard-url <url>] [--json]",
+            "Usage: cockpit manager <clients|client|home|summary|run|list|queue|show|add|edit|done|reopen|link|approve|dismiss|proposal|archive|unarchive> ... [--dashboard-url <url>] [--json]",
             "",
-            "Tower Manager's client actions and timeline items, from the terminal: the same things the manager page does.",
+            "Tower Manager's clients, from the terminal: each client's Home and \"Where we are\", its actions and its timeline items, the same things the manager page does.",
             "  cockpit manager clients                      every client, with its id",
             "  cockpit manager client <client>              one client: state, last read, pages waiting;  run <run-id>  one run's receipt",
+            "  cockpit manager home <client>                the client's Home: how fresh its data is (last read, when Notion last changed), \"Where we are\" (health, headline, up to 5 dated bullets,",
+            "                                               next step, blocker, who wrote it and when), live counts, what needs attention by owner (overdue and due within 7 days), what is coming up,",
+            "                                               what the newest read that changed anything did, and how many sync changes wait for review (`queue <client>` lists them).",
+            "  cockpit manager summary <client> --version <v>|none [--health on_track|at_risk|blocked] [--headline <text>] [--bullet \"YYYY-MM-DD: text\"]... [--next <text>|none] [--blocker <text>|none]",
+            "                                               edit \"Where we are\": any field alone, or several at once. --bullet is given 1 to 5 times and REPLACES the whole list; a leading",
+            "                                               \"YYYY-MM-DD: \" dates a bullet, without it the bullet is undated. none clears --next or --blocker. blocked needs a blocker (given, or already on the card),",
+            "                                               and a blocker is kept only while the card is Blocked: with any other health it is dropped.",
+            "                                               --version is summary.updatedAt from `home <client> --json`, or none when the client has no card yet (then --health, --headline and at least one --bullet are all needed).",
+            "                                               Limits: headline 140 characters, each bullet 160, next and blocker 200. The edit is marked as yours and stands until the client's",
+            "                                               data changes or an action goes overdue; the next check after that writes the card again (newest wins).",
             "  cockpit manager list <client> [--timeline] [--needs-review] [--status open|done|dropped|closed|all] [--owner <name>|--no-owner] [--overdue] [--kind <kind>] [--search <text>] [--archived] [--review dismissed|all]",
             "                                               actions (default), or with --timeline the timeline; --status, --owner, --no-owner and --overdue (open actions due before today) are for actions, --kind for the timeline.",
+            "                                               The timeline reads top down: undated items (\"Needs a date\"), then upcoming, a Today line, then the past, newest first (today is Vancouver's day).",
             "                                               Dismissed and archived items are hidden: --review dismissed (or all) and --archived find them. A list holds at most 500 rows and says when it is cut.",
             "  cockpit manager queue <client>               changes from syncs after onboarding that nobody has looked at yet (the onboarding's own items are not in it)",
             "                                               an empty queue does not mean everything is reviewed: list <client> --needs-review --status all, and list <client> --timeline --needs-review",
@@ -239,12 +250,12 @@ export const TOWER_OPS_COMMAND_HELP = [
             "since, the write is refused with a sentence saying so and nothing is written; run show again for the new version and retry.",
             "--owners on an action takes, as the web form says, \"One or more people, separated by commas\" (\"Rowan Ash, Juniper Twig\"), and it REPLACES the whole list. Leave it out and the owners stay;",
             "--owners none clears them. A timeline item has ONE owner: --owner <name> or --owner none. The same pattern clears a date: --due none, --date none.",
-            "Owner names are kept as written, not matched to accounts: use the spelling `list` shows, so one person stays one name. A flag you leave out is never sent, and a flag given twice is refused. A date is YYYY-MM-DD. `cockpit manager`, `manager help` and `manager --help` print this and change nothing.",
+            "Owner names are kept as written, not matched to accounts: use the spelling `list` shows, so one person stays one name. A flag you leave out is never sent, and a flag given twice is refused (all but summary's --bullet). A date is YYYY-MM-DD. `cockpit manager`, `manager help` and `manager --help` print this and change nothing.",
             "add always sends a request id (--request-id <uuid>, else a fresh one) and prints it. If Tower does not answer, nothing was confirmed: rerun the same command with",
             "--request-id <id> and it retries without making a duplicate.",
             "--json writes the door's body to stdout, verbatim, and nothing else (an add's body also carries requestId); a refusal is { ok: false, error, detail, refusal? } and exits 1.",
             "Progress lines on stderr start with [tag]; stdout is the answer (2>/dev/null hides them). Creating a client, syncing, Rebuild brief and merging owners are on the manager page only. Teaching: docs/architecture/tower-manager.md.",
-            "The bli-tower MCP server has the twins: manager_clients, manager_client, manager_run, manager_list, manager_queue, manager_show, manager_add, manager_edit,",
+            "The bli-tower MCP server has the twins: manager_clients, manager_client, manager_home, manager_set_summary (summary), manager_run, manager_list, manager_queue, manager_show, manager_add, manager_edit,",
             "manager_done, manager_reopen, manager_link, manager_approve, manager_dismiss, manager_proposal, manager_archive, manager_unarchive.",
         ],
     ],

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

@@ -47,7 +47,7 @@ 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>]] [flags]",
+            "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>] [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 }] }.",
@@ -62,7 +62,10 @@ export const TOWER_COMMAND_HELP = [
             "  --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 }.",
+            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] [--expected-revision <n>] [--request-id <uuid>] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb. --json shape: { document, mutation }.",
+            "  --expected-revision <n> is the page revision you read (`docs read --json` shows document.revision). The save is one atomic step: if someone saved since, nothing is written and you get revision_conflict with the current page (--json: mutation.current). Omit it for an unconditional save. Every save advances the revision.",
+            "  --request-id <uuid> makes a retry apply once (minted and printed when absent). Reusing it with different input is request_id_reused. If the response is lost, run `cockpit docs mutation-status <uuid>`, then retry the SAME input with the SAME id.",
+            "mutation-status <request-uuid> — your own save receipt: committed (with the stored revision), not_committed (with the reason) or unknown_check_again (no receipt yet; it never proves nothing changed). --json shape: { mutation }.",
             "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
             "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 }] }.",
             "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.",
@@ -77,13 +80,14 @@ export const TOWER_COMMAND_HELP = [
     [
         "msg",
         [
-            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>|show <message-id>] [flags]",
+            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|unread <channel> --from <message-id>|send <channel>|thread <id> --channel <channel>|show <message-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.",
-            "read <channel> [--limit <n>] [--thread <id>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
+            "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>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
             "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.",
@@ -95,7 +99,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "issue",
         [
-            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|history <id>] [flags]",
+            "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]",
             "",
             "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. 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 }] }.",
@@ -106,7 +110,11 @@ export const TOWER_COMMAND_HELP = [
             "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.",
             "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>] — every recorded state move and reassignment, oldest first.",
+            "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 }.",
             "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.",
@@ -143,7 +151,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "cal",
         [
-            'Usage: cockpit cal [today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find "<words>"|calendars|add-ical|create|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>|next|find "<words>"|calendars|add-ical|create|duplicate <event id>|batch|undo [<change id>]|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes] [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.",
@@ -151,6 +159,8 @@ export const TOWER_COMMAND_HELP = [
             "next [--hours 12] — what is coming, from RIGHT NOW rather than from midnight. Defaults to the next 72 hours, so a Friday evening still answers.",
             'find "<words>" — full text over titles, locations and descriptions. A repeating event is answered with the NEXT time it happens, not its first one in 2024.',
             "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.",
             "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:",
@@ -164,7 +174,10 @@ export const TOWER_COMMAND_HELP = [
             "sync <id> [--full] — reads that calendar now instead of waiting for the cron. --full ignores the sync token / ETag and re-reads everything.",
             "sync-status [<id>] — every calendar's health, or one's: last successful sync, the last pass's own reason, how many events it carried, failures in the last 24h, and the lag between an event's own provider clock and when Tower stored it (ticket 10730).",
             "detach <id> — removes the calendar and its stored events from Tower. The calendar itself is untouched at Google.",
-            "change <event id> [--account <name>] [--title <title>] [--at <iso> --until <iso>] [--location <place>] — changes an event on its own account.",
+            "change <event id> [--account <name>] [--title <title>] [--at <iso> --until <iso>] [--location <place>] [--all-day|--timed] [--tz <zone>] [--expected-version <v>] [--idempotency-key <k>] [--reason <why>] — changes an event on its own account and prints the change id (undo it with `undo`). --all-day converts to an all-day event (--at/--until are dates, --until the day AFTER the last day); --timed converts back. --expected-version refuses (version_conflict) instead of overwriting an event that changed since you read it. Recurring events are refused until scoped edits ship.",
+            "duplicate <event id> [--at <iso> --until <iso>] [--calendar <id>|--account <name>] [--keep-invitees] [--idempotency-key <k>] — copies ONE non-recurring event. The copy has NO guests unless you pass --keep-invitees (Google then emails each one) and no Meet room. Same times unless --at/--until are given; --calendar/--account puts the copy on another of your calendars on purpose. The same --idempotency-key twice makes one copy.",
+            'batch [--idempotency-key <k>] [--reason <why>] — up to 25 changes from JSON on stdin: {"changes":[{"event_id":"…","starts_at":"…","ends_at":"…","expected_version":"…"}]} (or a bare array; fields as `change`: title, location, all_day, time_zone). Each is its own write: the output lists every item and the ones left unchanged, and the exit code is 1 unless all were written.',
+            "undo [<change id>] — a NEW write that puts the recorded earlier values back (or removes the event a create or duplicate made), never a deletion of history. No id means your latest change. Refuses when the event changed again since (undo_stale), when that change was already undone, and for guest changes, cancellations and calendar moves.",
             "cancel <event id> --yes [--account <name>] — same door as delete; a named account must own the event.",
             "delete <event id> --yes — removes ONE event, AT GOOGLE first, then here. Refuses without --yes: a delete can email everybody on it, exactly like create's invitations do. Google already having it gone (404/410) is answered as success, not a refusal.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",