@bli-cockpit/cli 0.2.237 → 0.2.238

package/dist/commands/local-help.js

@@ -100,92 +100,96 @@ export const rootCommandNames = new Set([
 ]);
 /** Public names omit compatibility spellings while the router keeps accepting them. */
 export const publicCommandNames = new Set([...rootCommandNames].filter((name) => name !== "do-everything" && name !== "fix"));
+/** The one-screen summary `cockpit --help` prints: one line per command, then the shared footnotes. */
+const COMMAND_SUMMARY_LINES = [
+    "  cockpit roots add <dir> [--allow-home-root] [--json]",
+    "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
+    "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
+    "  cockpit upgrade [same flags as update]",
+    "  cockpit doctor [--check | --no-repair] [--lock-wait <seconds>] [--backfill-budget <seconds>] [--json]",
+    "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
+    "  cockpit login [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+    "  cockpit pair [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+    "  cockpit logout [--revoke] [--yes] [--dashboard-url <url>] [--json]",
+    "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
+    "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+    "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+    "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
+    "  cockpit model [show|set <provider:model>] [--json]",
+    "  cockpit models [list|show <provider:model>|compare <provider:model> <provider:model> [...]] [--highlight] [--dashboard-url <url>] [--json]",
+    "  cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+    "  cockpit ci report [--repo <owner/name>] [--json]",
+    "  cockpit ops [status [--job <id>] [--skips] [--memory] [--models] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
+    "  cockpit slack [connect [--workspace bli|blue_pearl] | disconnect --workspace bli|blue_pearl | coverage [--workspace bli|blue_pearl] [--stale-only] [--list] | read [--person <p>] [--channel <c>] [--query <text> [--word]] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--format compact|full]] [--json]",
+    "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | cli-floor [<version>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
+    "  cockpit team github-login add|remove <person> <login> | list <person> [--json]",
+    "  cockpit team timezone set <person> <iana-zone|unknown> | list [--json]",
+    "  cockpit team [members | invite <email> --role <role> [--team-id <uuid>] | role <userId> --role <role> [--yes] | device [list] | device revoke <id|name> --reason <label> [--note \"<text>\"] [--yes]] [--json]",
+    "  cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
+    "  cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
+    "  cockpit brief status [--who <person>] [--render] [--dashboard-url <url>] [--json]",
+    "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
+    "  cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|summarize <id>|move <id>|place <id>] [--folder <path>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--apply] [--yes] [--dashboard-url <url>] [--json]",
+    "  cockpit notes [accounts [--show-webhook <account-id>]|connect --provider fellow --workspace <sub> --key-stdin [--name <n>]|connect --provider wisprflow|recordings <note-id>|recording <id>|webhook <account-id> --secret-stdin|detach <account-id>|sync <account-id>] [--json]   (the key and the signing secret are read from stdin, never a flag)",
+    "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--lock-wait <seconds>] [--yes] [--workspace <path>] [--json]",
+    "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
+    "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
+    "  cockpit serve [--port <port>] [--workspace <path>]",
+    "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+    "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
+    "  cockpit memory [search \"<question>\"|save|update <id>|forget <id>|profile|install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--container <tag>] [--limit <n>] [--no-recent] [--include-originals|--no-originals] [--include-source|--no-source] [--custom-id <id>] [--extract] [--content-stdin] [--reason <label>] [--file <path>] [--dashboard-url <url>] [--dry-run] [--json]",
+    "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
+    "  cockpit sources check [--older-than <days>] [--dashboard-url <url>] [--json]",
+    "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>|delete <id|slug>] [--parent <id>|root|--clear-parent] [--query <text> [--word]] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
+    "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>|show <message-id>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
+    "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--size S|M|L] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
+    "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--attach <path>]... [--dashboard-url <url>] [--json]",
+    "  cockpit cal [event <id> [--occurrence-start <iso>]|export <id> [--occurrence-start <iso>]|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
+    "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
+    "  cockpit github <pr|merge|retitle|rerun> <owner/repo> <n> [--claim <state>] [--method squash|merge|rebase] [--title \"<text>\"] [--run <id>] [--confirm <code>] [--dashboard-url <url>] [--json]",
+    `  cockpit search "<words>" [--kind <category,...>] [--limit <n>] [--dashboard-url <url>] [--json]`,
+    "  cockpit search --categories [--dashboard-url <url>] [--json]",
+    "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+    "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|followup <id> [--record-sent-at <iso>]|interview <id> <--at <iso>|--clear>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false> --followup-enabled <true|false> --followup-after-days <n> --takehome-window-hours <n>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
+    "  cockpit glossary list|add <wrong> --to <name>|remove <wrong> [--dashboard-url <url>] [--json]",
+    "  cockpit spend memory [--days 1|7|30] [--dashboard-url <url>] [--json]",
+    "  cockpit rename [list|resolve <id> --scope <page|everywhere|undo>] [--dashboard-url <url>] [--json]",
+    "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
+    "  cockpit intentions [list [--status open|overdue|done|dropped|all] [--project <name>] [--limit <n>]|show <id>|done <id> --evidence <text>|drop <id> --evidence <text>|reopen <id>] [--dashboard-url <url>] [--json]",
+    "  cockpit who [<topic>] [--layer frontend|backend|data|infrastructure|docs|tooling] [--limit <1-10>] [--dashboard-url <url>] [--json]",
+    "  cockpit people show [<person>] [--dashboard-url <url>] [--json]",
+    "  cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--dashboard-url <url>] [--json]",
+    "  cockpit brain ladder <show|promote <class> [--anyway]|demote <class>|predict \"<question>\"|answer \"<reply>\" --prediction <id>> [--json]",
+    "  cockpit hits [--mine | --person <email|github-login|name> | --agent | --project <id>] [--days <n>] [--patterns] [--learning] [--top <n>] [--dashboard-url <url>] [--json]",
+    "  cockpit hits timeline [--weeks <n>] [--dashboard-url <url>] [--json]",
+    "  cockpit hits coach [--dashboard-url <url>] [--json]",
+    "  cockpit hits approve --scope <team|agents|project:<id>> [--version <n>] [--dashboard-url <url>] [--json]",
+    "  cockpit approvals [list|show <id>|create|approve <id> [--edit]|edit <id> [--approve]|reject <id>|rules [--active true|false]|rules create <card-id> [--any-audience] [--label <text>]|rules revoke <rule-id> [--reason <text>]] [--status <s>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
+    "  cockpit drills [list|start|answer --confidence <1-5> [--text <words>] [--attempt <id>]|theme|theme set <theme> [--play <t>] [--watch <t>] [--train <t>]|review] [--dashboard-url <url>] [--json]",
+    "  cockpit manager <clients|client <client>|run <run-id>|list <client>|queue <client>|show <id>|add <client> --title <t>|edit <id> --version <v>|done|reopen|link|approve|dismiss|proposal|archive|unarchive> [--timeline] [--dashboard-url <url>] [--json]",
+    "  cockpit image <describe <file> [--session <id>]|show <sha256-or-prefix>> [--dashboard-url <url>] [--json]",
+    "  cockpit setup [--since <7d|30d|date>] [--details] [--person <name|email>] [--compare <name,name>] [--json]",
+    "  cockpit usage sessions [--person <exact-name>] [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--tool claude|codex] [--since <window>] [--until <iso>] [--cursor <cursor>] [--limit <n>] [--json]",
+    "  cockpit usage session <id> [--from-window <n>] [--json]",
+    "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",
+    "  cockpit ticket mutation-status <request-uuid> [--json] (check a lost write response)",
+    "  cockpit ticket create|update|move|comment ... [--request-id <uuid>] [--expected-revision <n>] [--json]",
+    "  cockpit ticket [same verbs and flags as cockpit issue]   (the Tickets page; projects: `cockpit project list`)",
+    "  cockpit tickets ...   same as cockpit ticket",
+    "  cockpit work ...      same as cockpit ticket (the older name)",
+    "  cockpit calendar [same verbs and flags as cockpit cal]",
+    "  cockpit messages [same verbs and flags as cockpit msg]",
+    "  cockpit meeting-notes [same verbs and flags as cockpit notes]",
+    "  cockpit speed [--page <name>]... [--runs <n>] [--dashboard-url <url>] [--json]",
+    "  cockpit usage people [--by-repo | --by-topic | --by-subject | --by-task | --by-client] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
+    "",
+    `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
+    "--quiet on any command (or COCKPIT_QUIET=1) drops the `[tower client] responded {...}` trace line from stderr; --json already implies it. A failure still logs — only that success-path trace goes quiet (BLI-10450).",
+];
 export function localCommandHelp(command) {
     if (command)
         return localSubcommandHelp(command);
-    return [
-        "  cockpit roots add <dir> [--allow-home-root] [--json]",
-        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
-        "  cockpit upgrade [same flags as update]",
-        "  cockpit doctor [--check | --no-repair] [--lock-wait <seconds>] [--backfill-budget <seconds>] [--json]",
-        "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
-        "  cockpit login [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
-        "  cockpit pair [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
-        "  cockpit logout [--revoke] [--yes] [--dashboard-url <url>] [--json]",
-        "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
-        "  cockpit model [show|set <provider:model>] [--json]",
-        "  cockpit models [list|show <provider:model>|compare <provider:model> <provider:model> [...]] [--highlight] [--dashboard-url <url>] [--json]",
-        "  cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit ci report [--repo <owner/name>] [--json]",
-        "  cockpit ops [status [--job <id>] [--skips] [--memory] [--models] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
-        "  cockpit slack [connect [--workspace bli|blue_pearl] | disconnect --workspace bli|blue_pearl | coverage [--workspace bli|blue_pearl] [--stale-only] [--list] | read [--person <p>] [--channel <c>] [--query <text> [--word]] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--format compact|full]] [--json]",
-        "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | cli-floor [<version>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
-        "  cockpit team github-login add|remove <person> <login> | list <person> [--json]",
-        "  cockpit team timezone set <person> <iana-zone|unknown> | list [--json]",
-        "  cockpit team [members | invite <email> --role <role> [--team-id <uuid>] | role <userId> --role <role> [--yes] | device [list] | device revoke <id|name> --reason <label> [--note \"<text>\"] [--yes]] [--json]",
-        "  cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
-        "  cockpit brief status [--who <person>] [--render] [--dashboard-url <url>] [--json]",
-        "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
-        "  cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|summarize <id>|move <id>|place <id>] [--folder <path>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--apply] [--yes] [--dashboard-url <url>] [--json]",
-        "  cockpit notes [accounts [--show-webhook <account-id>]|connect --provider fellow --workspace <sub> --key-stdin [--name <n>]|connect --provider wisprflow|recordings <note-id>|recording <id>|webhook <account-id> --secret-stdin|detach <account-id>|sync <account-id>] [--json]   (the key and the signing secret are read from stdin, never a flag)",
-        "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--lock-wait <seconds>] [--yes] [--workspace <path>] [--json]",
-        "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit serve [--port <port>] [--workspace <path>]",
-        "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
-        "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
-        "  cockpit memory [search \"<question>\"|save|update <id>|forget <id>|profile|install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--container <tag>] [--limit <n>] [--no-recent] [--include-originals|--no-originals] [--include-source|--no-source] [--custom-id <id>] [--extract] [--content-stdin] [--reason <label>] [--file <path>] [--dashboard-url <url>] [--dry-run] [--json]",
-        "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
-        "  cockpit sources check [--older-than <days>] [--dashboard-url <url>] [--json]",
-        "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>|delete <id|slug>] [--parent <id>|root|--clear-parent] [--query <text> [--word]] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
-        "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>|show <message-id>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
-        "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--size S|M|L] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
-        "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--attach <path>]... [--dashboard-url <url>] [--json]",
-        "  cockpit cal [today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
-        "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
-        "  cockpit github <pr|merge|retitle|rerun> <owner/repo> <n> [--claim <state>] [--method squash|merge|rebase] [--title \"<text>\"] [--run <id>] [--confirm <code>] [--dashboard-url <url>] [--json]",
-        `  cockpit search "<words>" [--kind <category,...>] [--limit <n>] [--dashboard-url <url>] [--json]`,
-        "  cockpit search --categories [--dashboard-url <url>] [--json]",
-        "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
-        "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|followup <id> [--record-sent-at <iso>]|interview <id> <--at <iso>|--clear>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false> --followup-enabled <true|false> --followup-after-days <n> --takehome-window-hours <n>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
-        "  cockpit glossary list|add <wrong> --to <name>|remove <wrong> [--dashboard-url <url>] [--json]",
-        "  cockpit spend memory [--days 1|7|30] [--dashboard-url <url>] [--json]",
-        "  cockpit rename [list|resolve <id> --scope <page|everywhere|undo>] [--dashboard-url <url>] [--json]",
-        "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
-        "  cockpit intentions [list [--status open|overdue|done|dropped|all] [--project <name>] [--limit <n>]|show <id>|done <id> --evidence <text>|drop <id> --evidence <text>|reopen <id>] [--dashboard-url <url>] [--json]",
-        "  cockpit who [<topic>] [--layer frontend|backend|data|infrastructure|docs|tooling] [--limit <1-10>] [--dashboard-url <url>] [--json]",
-        "  cockpit people show [<person>] [--dashboard-url <url>] [--json]",
-        "  cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--dashboard-url <url>] [--json]",
-        "  cockpit brain ladder <show|promote <class> [--anyway]|demote <class>|predict \"<question>\"|answer \"<reply>\" --prediction <id>> [--json]",
-        "  cockpit hits [--mine | --person <email|github-login|name> | --agent | --project <id>] [--days <n>] [--patterns] [--learning] [--top <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit hits timeline [--weeks <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit hits coach [--dashboard-url <url>] [--json]",
-        "  cockpit hits approve --scope <team|agents|project:<id>> [--version <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit approvals [list|show <id>|create|approve <id> [--edit]|edit <id> [--approve]|reject <id>|rules [--active true|false]|rules create <card-id> [--any-audience] [--label <text>]|rules revoke <rule-id> [--reason <text>]] [--status <s>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
-        "  cockpit drills [list|start|answer --confidence <1-5> [--text <words>] [--attempt <id>]|theme|theme set <theme> [--play <t>] [--watch <t>] [--train <t>]|review] [--dashboard-url <url>] [--json]",
-        "  cockpit manager <clients|client <client>|run <run-id>|list <client>|queue <client>|show <id>|add <client> --title <t>|edit <id> --version <v>|done|reopen|link|approve|dismiss|proposal|archive|unarchive> [--timeline] [--dashboard-url <url>] [--json]",
-        "  cockpit image <describe <file> [--session <id>]|show <sha256-or-prefix>> [--dashboard-url <url>] [--json]",
-        "  cockpit setup [--since <7d|30d|date>] [--details] [--person <name|email>] [--compare <name,name>] [--json]",
-        "  cockpit usage sessions [--person <exact-name>] [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--tool claude|codex] [--since <window>] [--until <iso>] [--cursor <cursor>] [--limit <n>] [--json]",
-        "  cockpit usage session <id> [--from-window <n>] [--json]",
-        "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",
-        "  cockpit ticket [same verbs and flags as cockpit issue]   (the Tickets page; projects: `cockpit project list`)",
-        "  cockpit tickets ...   same as cockpit ticket",
-        "  cockpit work ...      same as cockpit ticket (the older name)",
-        "  cockpit calendar [same verbs and flags as cockpit cal]",
-        "  cockpit messages [same verbs and flags as cockpit msg]",
-        "  cockpit meeting-notes [same verbs and flags as cockpit notes]",
-        "  cockpit speed [--page <name>]... [--runs <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit usage people [--by-repo | --by-topic | --by-subject | --by-task | --by-client] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
-        "",
-        `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
-        "--quiet on any command (or COCKPIT_QUIET=1) drops the `[tower client] responded {...}` trace line from stderr; --json already implies it. A failure still logs — only that success-path trace goes quiet (BLI-10450).",
-    ].join("\n");
+    return COMMAND_SUMMARY_LINES.join("\n");
 }
 /**
  * What an unknown first word answers (BLI-10431). The closest registered name

package/dist/commands/local-run-guards.js

@@ -0,0 +1,100 @@
+import { errorMessage, writeLine } from "./cli-io.js";
+import { localCommandHelp, rootCommandNames } from "./local-help.js";
+import { describeError } from "../health-detail.js";
+/**
+ * BLI-10450: `--quiet` is a global toggle, stripped here so no per-command
+ * parser's `allowedFlags` needs to learn it, and mirrored onto
+ * `COCKPIT_QUIET` so `tower-client.ts` can react without every call site
+ * threading a flag through. `--json` already implies it (tower-client.ts).
+ *
+ * BLI-10746: `--fresh`/`--allow-stale` are global toggles for the
+ * stale-while-revalidate read cache, same reason and same shape — mirrored
+ * onto env vars `read-cache.ts` reads. One `cockpit` process makes at most one
+ * cacheable request, so a process-wide toggle is exactly a per-request one.
+ */
+export function stripGlobalToggles(argv) {
+    if (argv.includes("--quiet")) {
+        argv = argv.filter((token) => token !== "--quiet");
+        process.env.COCKPIT_QUIET = "1";
+    }
+    if (argv.includes("--fresh")) {
+        argv = argv.filter((token) => token !== "--fresh");
+        process.env.COCKPIT_READ_FRESH = "1";
+    }
+    if (argv.includes("--allow-stale")) {
+        argv = argv.filter((token) => token !== "--allow-stale");
+        process.env.COCKPIT_READ_ALLOW_STALE = "1";
+    }
+    return argv;
+}
+export function refuseArguments(argv, error, io) {
+    // BLI-10431: under --json a refused parse still owes stdout one object.
+    // It used to write nothing there, so `cockpit usage sessions --json`
+    // without a filter read to an agent as an empty answer, not a refusal.
+    if (argv.includes("--json")) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: false,
+            error: "invalid_arguments",
+            command: argv[0] ?? "",
+            detail: errorMessage(error),
+        }));
+    }
+    console.error("[cockpit-cli] arguments refused", JSON.stringify({ reason: "invalid_arguments", command: argv[0] ?? "", json: argv.includes("--json") }));
+    writeLine(io.stderr, errorMessage(error));
+    writeLine(io.stderr, "");
+    // A refused `cockpit cal create --meet` used to print its one correct
+    // reason line and then the WHOLE collector wall — onboard, update, forty
+    // more — so the reason drowned and Edward read it as "it just shows usage"
+    // (2026-09-06). A parse error on a KNOWN command gets that command's own
+    // manual, which names the flags the reason line just asked for; only an
+    // unknown command earns the wall.
+    const command = argv[0];
+    writeLine(io.stderr, command && rootCommandNames.has(command) ? localCommandHelp(command) : localCommandHelp());
+    return 1;
+}
+/**
+ * The outermost net under every subcommand. It printed `error.message` and
+ * dropped the name, the code, the syscall and the cause — and never said
+ * WHICH subcommand died, so a scheduled `cockpit sync` and a hand-typed
+ * `cockpit doctor` failing the same way were indistinguishable in
+ * sync.err.log (BLI-3483). The human line is unchanged; the structured one
+ * beside it carries names and codes only, scrubbed by `describeError`.
+ */
+export function reportCommandFailure(command, error, io, stdoutWatch) {
+    console.error("[cockpit-cli] command failed", JSON.stringify({
+        reason: "command_failed",
+        command: command.kind,
+        ...describeError(error),
+    }));
+    if (stdoutWatch && !stdoutWatch.written()) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: false,
+            error: "command_failed",
+            command: command.kind,
+            detail: errorMessage(error),
+        }));
+    }
+    writeLine(io.stderr, errorMessage(error));
+    return 1;
+}
+/**
+ * The same stream, with a flag that flips on the first write. A Proxy rather
+ * than a copied object so `isTTY`, `columns` and every listener method still
+ * reach the real stream.
+ */
+export function watchWrites(stream) {
+    let wrote = false;
+    const watched = new Proxy(stream, {
+        get(target, property) {
+            if (property === "write") {
+                return (...args) => {
+                    wrote = true;
+                    return target.write.apply(target, args);
+                };
+            }
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+    return { stream: watched, written: () => wrote };
+}