@bli-cockpit/cli 0.2.239 → 0.2.241

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

@@ -197,10 +197,10 @@ export const TOWER_OPS_COMMAND_HELP = [
             "  cockpit drills start                          open the next drill: the change or command, what it printed, and the question. The cause is NOT shown",
             "  cockpit drills answer --confidence <1-5>      your answer on stdin (or --text), and how sure you are; then the real cause and the guard are shown",
             "  cockpit drills theme                          your theme and the choices",
-            "  cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]    video-game (the default), boxing, muay-thai, crime-drama, anime, sports, or your own words",
+            "  cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]    plain (the default: no theme), video-game, sports, movies-tv, music, anime, cooking, or anything you're into",
             "  cockpit drills review                         your own week: hits, wins, highs, lows, where you have stopped improving, what to practise",
-            "A drill replays a real mistake the team already paid for. You answer first, so a wrong answer you were sure about is the one you remember; it comes back 1, 3 and 7 days later.",
-            "Each of your top patterns is a boss: pass its drills, then a stretch of your own PRs without taking that hit again. There is no leaderboard; these are your own rows only.",
+            "A drill replays a real mistake the team already paid for, shown straight with no theme unless you pick one. You answer first, so a wrong answer you were sure about is the one you remember; it comes back 1, 3 and 7 days later.",
+            "Each of your top patterns is something to beat (a boss, if you pick a theme): pass its drills, then a stretch of your own PRs without taking that hit again. There is no leaderboard; these are your own rows only.",
             "Anything that needs your hit history says so when it is not connected yet, instead of showing a zero.",
             "--home <dir> and --dashboard-url <url> are for tests and staging.",
             "--json writes one object to stdout (the door's body) and nothing else; a refusal is { ok: false, error, detail } and exits 1.",
@@ -210,53 +210,67 @@ export const TOWER_OPS_COMMAND_HELP = [
     [
         "manager",
         [
-            "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]",
+            "Usage: cockpit manager <clients|client|home|summary|run|list|queue|show|add|edit|done|drop|reopen|link|approve|dismiss|proposal|archive|unarchive> ... [--dashboard-url <url>] [--json]",
             "",
             "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 client <client>              one client: state, last read, pages waiting;  run <run-id>  one run's receipt (a summary check says what it did to the card, not \"0 pages seen\"). A run id is a UUID from `queue <client> --json` (a row's changedByRunId), `show <id>` (a suggested change's runId) or `client <client> --json` (lastBriefRebuild.runId); a read's workflow id (lastRead.workflowRunId, like sched_wf_…) is not one",
             "  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]",
+            "                                               next step, blocker, who wrote it and when), live counts, what needs attention by owner in two parts, \"Due this week\" first (today to six days ahead) then \"Overdue\" (rows sit under their owners, oldest first under each; a line \"Overdue longest: <title>, due <day>\" names the one overdue longest), each with its own total and, when cut, \"Showing X of N\" and the `list` command for the rest, what is coming up,",
+            "                                               what the newest read that changed anything did (proposals first), \"In Tower, last 7 days\" (what people and agents added, closed, dropped and dismissed, and who, by name; a count of none is left out, and when all are none: \"nothing added, closed, dropped or dismissed by people or agents\"), and a What changed tally that likewise leaves out a kind with none (\"12 added, 2 proposed\"; \"nothing changed\" when none), and the review line (\"N suggested changes need a decision · M new items to check\"; `queue <client>` lists them), and how many sync changes are \"new from syncs\" (`queue <client>` lists them; `list` counts every unreviewed item as \"need review\", the first read's included).",
+            "                                               Home also says how old the last check of the card is (\"Last checked 2 h ago\"), \"The last check failed; showing the card from Oct 5\" when it did, \"Last checked\" only once a check has looked at the card (a card a person wrote has none yet), a failed read's reason in the page\'s own sentence (\"Why the latest read failed: ...\"), and \"First read not done yet\" for a client no read has finished (\"First read failed\" when it failed: the manager page shows only that failure until a read succeeds, though writes made here are saved); a card computed from counts reads \"AI unavailable · computed from counts\".",
+            "  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.",
+            "                                               and a blocker goes only on a Blocked card: sent with any other health it is refused (summary_blocker_needs_blocked); sending only a new health drops the stored one.",
             "                                               --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).",
+            "                                               Limits: headline 140 characters, each bullet 160, next and blocker 200; a longer text is refused here with its length. A day spelled with a month name at the start of a bullet (\"Oct 3: x\") is refused, never saved undated. --version none is for a client with no card: on one that has a card the write is refused with \"This client already has a card: pass its version\". The edit is marked as yours and stands until the client's",
+            "                                               data changes, an action goes overdue or an open action passes 14 days overdue; the next check after that writes the card again (newest wins).",
+            "                                               A saved card that says On track while an open action is more than 14 days overdue is saved anyway and prints a \"Warning: ...\" line naming the action overdue longest.",
+            "                                               Write the card after your item writes: your own later item writes count as data changes, and the next check rewrites the card.",
+            "                                               Health rule: an open action more than 14 days overdue, as `cockpit manager home` shows it (Tower's today, America/Vancouver), means the card is at_risk (or blocked, with a named blocker).",
+            "                                               Do not set on_track over one; tell the person instead. The headline or a bullet must name the action overdue longest, with the day it was due.",
             "  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)",
+            "                                               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. With --owner or --no-owner the counts under the heading are that filter's (\"N open actions match these filters (M overdue)\"), not the client's. Times print as Tower's day and time (America/Vancouver, \"Oct 16, 1:03 AM PDT\"); --json keeps the raw ISO.",
+            "  cockpit manager queue <client>               changes from syncs after onboarding that nobody has looked at yet (the onboarding's own items are not in it): \"Needs your decision\" first (a suggested change waits on each), then \"New items to check\"",
             "                                               an empty queue does not mean everything is reviewed: list <client> --needs-review --status all, and list <client> --timeline --needs-review",
-            "  cockpit manager show <id> [--timeline]       one item in full: detail, sources, suggested changes with their ids, what a sync changed",
-            "  cockpit manager add <client> --title <text> [--owners \"A, B\"] [--due YYYY-MM-DD] [--meeting <timeline-id>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]",
+            "  cockpit manager show <id> [--timeline]       one item in full: detail, sources, suggested changes with their ids and, beneath each, the page and quote the AI cited for it (or \"not found in the page\"), what a sync changed, and who added, edited, reviewed, closed or archived it (by name)",
+            "  cockpit manager add <client> --title <text> [--owners 'A, B'] [--due YYYY-MM-DD] [--meeting <timeline-id>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]",
             "  cockpit manager add <client> --timeline --kind meeting|document|milestone|internal --title <text> [--date YYYY-MM-DD] [--owner <one name>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]",
             "                                               no --date makes an undated timeline item, which lands in \"Needs a date\"",
             "                                               --source-url (an http(s) link) and --source-note say where it came from, as the web form's Source does; show prints them",
-            "  cockpit manager edit <id> --version <v> [--timeline] [--title <text>] [--detail <text>] [--due <date>|none] [--owners \"A, B\"|none]",
+            "  cockpit manager edit <id> --version <v> [--timeline] [--title <text>] [--detail <text>] [--due <date>|none] [--owners 'A, B'|none]",
             "                                               on a timeline item: [--kind <kind>] [--date <date>|none] [--owner <one name>|none]",
-            "  cockpit manager done <action> --version <v>      tick an action off (an AI action you tick off counts as reviewed by you, and suggested changes it makes moot close);  reopen <action> --version <v>  open it again",
-            "  cockpit manager link <action> --version <v> --meeting <timeline-id>   link an action to the meeting it came from;  --none  unlinks it",
+            "                                               an edit marks the item reviewed by you (an AI item's [needs review] becomes [reviewed], you the reviewer), even a detail-only one; the AI can only propose changes to it afterwards",
+            "  cockpit manager done <action> --version <v>      tick an action off (it marks the action reviewed by you, an AI action too, and suggested changes it makes moot close; on an action already done it writes nothing);  reopen <action> --version <v>  open it again",
+            "  cockpit manager drop <action> --version <v>      drop an action: the work no longer applies and was NOT done (a dropped action is not a done one: summaries and the page tell them apart). Add a dated line saying why to its detail first (`edit <id> --version <v> --detail <text>` replaces the detail: keep what `show <id>` printed, add \"YYYY-MM-DD: dropped because ...\"). Prints \"Dropped: <title>.\", or \"No change; nothing was written.\" when it was already dropped; reopen undoes it. Marks the action reviewed by you when the status changes. On an older Tower server it says it can\'t drop yet; mark it done with a dated line saying why instead.",
+            "  cockpit manager link <action> --version <v> --meeting <timeline-id>   link an action to the meeting it came from;  --none  unlinks it (either marks the action reviewed by you)",
             "  cockpit manager approve <id> --version <v> [--timeline] [--restore]    the AI's item is right: mark it reviewed;  --restore  brings a DISMISSED item back into the lists, marked reviewed by you (without it, a dismissed item is refused)",
             "  cockpit manager dismiss <id> --version <v> [--timeline]    the AI's item is wrong: dismiss it (kept, hidden from the lists)",
             "  cockpit manager proposal <id> <proposal-id> accept|dismiss|add-new --version <v> [--timeline]   decide one suggested change; add-new makes it an item of its own",
             "  cockpit manager archive <id> --version <v> [--timeline]    delete an item: it moves to the Deleted list (list --archived), kept;  unarchive <id> --version <v>  brings it back",
             "approve, dismiss and proposal decide the AI's suggestion as YOU: your name is recorded as the reviewer, and the item leaves the review queue unless a suggested change still waits on it.",
+            "Marking reviewed sets the review state to reviewed, with you as the reviewer and the time of the write: link always does it, and edit does whenever it changes something, even a detail-only one (an edit whose fields all equal the stored ones prints \"No change; nothing was written.\", with no new version and no reviewed mark); done, drop and reopen do it only when the status changes (on an action already in that status nothing is written); approve and an accepted proposal do it too. Dismiss sets it to dismissed with you as the reviewer; archive, unarchive and a proposal you dismiss or add-new leave the item's review state as it was.",
+            "Free text without shell quoting: add, edit and summary take --fields-file <path> (or - for stdin), one JSON object whose keys are the flags in snake_case, so a $12k, an apostrophe, a double quote or an = reaches Tower exactly as written. The file is UTF-8 (a UTF-16 file with a BOM is read too; any other encoding is refused): in Windows PowerShell write it with `-Encoding utf8` (a `>` redirect makes UTF-16 and Set-Content makes the ANSI code page, which breaks a ’), and for stdin on 5.1 set `$OutputEncoding = [System.Text.UTF8Encoding]::new()` first.",
+            "                                               add: title, detail, owners, owner, due, date, kind, meeting, source_url, source_note, request_id;  edit: title, detail, owners, owner, due, date, kind;  summary: health, headline, bullets, next, blocker.",
+            "                                               owners is a list or \"A, B\"; bullets is a list of \"YYYY-MM-DD: text\" strings or {\"date\": \"YYYY-MM-DD\" or null, \"text\": ...} objects; null (or none) clears owners, owner, due, date, next or blocker.",
+            "                                               --version and --timeline stay flags. A field given as a flag and in the file is refused, so is an unknown key. The file gets the flags' own checks. Example:  cat fields.json | cockpit manager summary Acme --version none --fields-file -",
+            "Free text (the flags above and every value in a fields file) that holds a provider key (an sk-, rk_, sb_secret_, ghp_, github_pat_, AKIA/ASIA, xoxb- key, any JWT, a PEM private key) or a password given a value (\"password: x\") is refused, naming the flag or key; ordinary words, a commit sha, a URL and the words \"service-role key\" are plain text.",
+            "On a flag, free text (--headline, --bullet, --title, --detail, --next, --blocker, --owners, --source-note) goes in SINGLE quotes so the shell leaves $ alone: \"$12k\" in double quotes loses the $12k (zsh and bash read it as a variable). In bash and zsh write an apostrophe inside single quotes as '\\'' (end the quote, a backslash-escaped apostrophe, reopen); in PowerShell double the apostrophe ('Rowan''s deck'). The command prints what it saved: check it is your words.",
             "<client> is the client's id, or its exact name (any case; `clients` lists them); a name that matches no client, or several, is refused with the names. Ids and versions are printed by list, queue and show. Items you add are reviewed already.",
             "--version is the item's version exactly as list or show prints it, copied as it is. Every change to an existing item names it: if someone or a sync changed the item",
             "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 (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.",
+            "add always sends a request id and prints it: leave --request-id out on a first add (a fresh one is made). If Tower does not answer, nothing was confirmed: rerun the same command with the",
+            "--request-id the CLI printed and it retries without making a duplicate (\"Already added earlier under this request id; nothing new was written.\"). Never make an id up: reusing one for a different item is refused (request_reused): the request id IS the item's id, so `show <request-id>` shows it, a retry already made it, and a different item is added without --request-id. An add prints the detail (cut to 200 characters) and the source it saved, so you can check they are your words.",
             "--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_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.",
+            "manager_done, manager_drop, 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>]|mutation-status <request-uuid>] [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>|share <id|slug> --add|--remove <email>|access <id|slug>] [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 }] }.",
@@ -67,20 +67,21 @@ export const TOWER_COMMAND_HELP = [
             "  --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.",
+            "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 }] }.",
             "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.",
+            "--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>|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>|edit <message-id>|delete <message-id>|outcome <request-uuid>|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).",
@@ -88,7 +89,8 @@ export const TOWER_COMMAND_HELP = [
             "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>] [--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`.",
+            "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.",
             "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.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
@@ -102,7 +104,7 @@ export const TOWER_COMMAND_HELP = [
             "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 }] }.",
+            "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 }] }.",
@@ -112,7 +114,7 @@ export const TOWER_COMMAND_HELP = [
             "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.",
+            "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 }.",
             "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
@@ -151,7 +153,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "cal",
         [
-            '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]',
+            '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]',
             "",
             "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.",
@@ -161,7 +163,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.",
+            "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.",
             "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"',
@@ -170,6 +172,8 @@ export const TOWER_COMMAND_HELP = [
             "      A work @buildlaunchiterate.ca calendar does not need this: connect Google in the browser and `cockpit cal calendars` will list them.",
             'create [--account <name>|--calendar <id>] --title "<what>" --at <iso> --until <iso> [--location "<where>"] [--attendee a@x,b@y] [--all-day] [--meet] — creates the event AT GOOGLE, then here. Attendees are invited by Google; --meet asks for a Google Meet room and prints its address (or says meet_not_available and keeps the event).',
             "      Only a Google calendar can be written to: an iCal secret address is a read address, and `write_not_supported_for_provider` says so by name.",
+            "rsvp <event id> --response accepted|declined|tentative [--comment \"<text>\"] [--scope instance|series] [--occurrence <iso>] [--account <name>] [--key <k>] — answers YOUR invitation; only your own guest entry changes and nobody else is emailed by Tower. Refuses with not_a_guest when you are not on the guest list.",
+            "change <event id> [--title ..] [--at <iso>] [--until <iso>] [--location ..] [--scope instance|following|series] [--occurrence <iso>] [--color 1-11|none] [--reminder <minutes[:popup|email]>|default]... [--visibility default|public|private|confidential] [--transparency opaque|transparent] — a recurring event REQUIRES --scope (instance and following also need --occurrence): instance = this event, following = this and following events (starts a NEW series), series = all events. --reminder repeats, at most 5; `default` alone means the calendar default. Refusals keep the door's reason (scope_required, occurrence_required, scope_not_supported, following_is_series, write_refused). cancel <event id> --yes [--scope instance|following|series] [--occurrence <iso>] [--account <name>] — same scope rules as change; `following` trims the series and prints the new end. create also takes --color, --reminder, --visibility and --transparency.",
             "share <id> --org-visible|--private — makes one of YOUR calendars readable by everyone at BLI, or private again. Sharing never lets anybody else change it.",
             "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).",
@@ -188,10 +192,10 @@ export const TOWER_COMMAND_HELP = [
     [
         "project",
         [
-            "Usage: cockpit project [list] [--archived] [--json]",
+            "Usage: cockpit project [list] [--archived] [--limit <n>] [--cursor <c>] [--json]",
             "",
             "The projects issues are filed under. Bare `cockpit project` lists them.",
-            "list [--archived] — id, active/archived, name. --archived includes archived projects.",
+            "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.",
         ],

package/dist/commands/local-help.js

@@ -144,7 +144,7 @@ const COMMAND_SUMMARY_LINES = [
     "  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>|duplicate <event id> [--keep-invitees]|batch|undo [<change id>]|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 cal [event <id> [--occurrence-start <iso>]|export <id> [--occurrence-start <iso>]|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|view-settings|view-settings-change|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|duplicate <event id> [--keep-invitees]|batch|undo [<change id>]|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]`,

package/dist/commands/manager-fields-file.js

@@ -0,0 +1,208 @@
+/**
+ * `cockpit manager add|edit|summary --fields-file <path>|-` (BLI-5777, findings Q-10 and Q-33): the free text of a write
+ * as one JSON object, read from a file or from stdin, so no shell quoting touches it (`$12k`, an apostrophe, a double
+ * quote on Windows PowerShell 5.1, an `=`).
+ *
+ * The keys are the flag names in snake_case. This module only READS: it checks the JSON's shape, refuses an unknown key
+ * or a key also given as a flag, runs the secret guard on every string, and turns each key into the same value the flag
+ * would have carried. The parser (`local-args-tower-manager.ts`) then runs the one set of field readers over the merged
+ * values, so a file value gets exactly the flag's validation (`none` clears, blank is refused, dates are real days).
+ *
+ * `--version` and `--timeline` stay flags: the version guards a write against a stale read, and `--timeline` picks the table.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { isInteractiveStdin } from "./cli-io.js";
+import { rejectSecretLikeValue } from "./local-arg-values.js";
+/** The keys a fields file may hold, per verb: every value flag the verb owns except `--version`. */
+export const FIELDS_FILE_KEYS = {
+    add: ["title", "detail", "owners", "owner", "due", "date", "kind", "meeting", "source_url", "source_note", "request_id"],
+    edit: ["title", "detail", "owners", "owner", "due", "date", "kind"],
+    summary: ["health", "headline", "bullets", "next", "blocker"],
+};
+/** Keys whose JSON `null` means "clear it", the same as the flag's `none`. */
+const NULLABLE = new Set(["owners", "owner", "due", "date", "next", "blocker"]);
+/** A file is a few fields of text; this stops a wrong file (a log, a dump) being read whole. */
+export const FIELDS_FILE_MAX_BYTES = 256 * 1024;
+const flagOf = (key) => `--${key.replace(/_/g, "-")}`;
+/** A key is the person's own spelling: cut and cleaned before it goes into a sentence. */
+const shown = (key) => key.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").slice(0, 40);
+/** The sentence for bytes that are not UTF-8 text (a Windows PowerShell 5.1 `>` file is UTF-16, a `Set-Content` file is the ANSI code page). */
+export const NOT_UTF8 = "The file is not UTF-8. Save the file as UTF-8 (PowerShell: -Encoding utf8) and run it again.";
+/**
+ * The bytes of a fields file as text: a UTF-8 BOM is dropped, a UTF-16 LE or BE BOM is decoded (PowerShell 5.1's `>` and Out-File write UTF-16 LE with a
+ * BOM), and anything else must be well-formed UTF-8: a file in the ANSI code page (a `’` saved by Set-Content) is refused, never read as "�".
+ */
+export function decodeFieldsBytes(bytes) {
+    // UTF-16 without a BOM (a program that wrote it raw) is full of NUL bytes, which no UTF-8 text holds: say what is wrong, not "not valid JSON (near character 1)".
+    const utf16Bom = bytes.length >= 2 && ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff));
+    if (!utf16Bom && bytes.includes(0))
+        throw new Error(NOT_UTF8);
+    try {
+        if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
+            return new TextDecoder("utf-16le", { fatal: true }).decode(bytes.subarray(2));
+        if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff)
+            return new TextDecoder("utf-16be", { fatal: true }).decode(bytes.subarray(2));
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes.subarray(bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf ? 3 : 0));
+    }
+    catch {
+        throw new Error(NOT_UTF8);
+    }
+}
+/** Everything the stream holds, as bytes (a string chunk, as a test gives, is its UTF-8), refused over `max` bytes. */
+async function readStreamBytes(stream, max, overflow) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+        total += bytes.length;
+        if (total > max)
+            throw new Error(overflow);
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks);
+}
+/** The text of the fields file: `-` is stdin (piped), anything else a path. Every failure is a sentence that says what to do. */
+export async function readFieldsText(source, io) {
+    if (source === "-") {
+        if (isInteractiveStdin(io)) {
+            throw new Error("--fields-file - reads the JSON from stdin, but stdin is a terminal. Pipe it in (`cat fields.json | cockpit manager ... --fields-file -`) or give a file path.");
+        }
+        const bytes = await readStreamBytes(io.stdin, FIELDS_FILE_MAX_BYTES, `The fields JSON on stdin is longer than ${FIELDS_FILE_MAX_BYTES / 1024} KB. It holds a few fields of text; check you piped the right file.`);
+        let text;
+        try {
+            text = decodeFieldsBytes(bytes);
+        }
+        catch {
+            // From a pipe, Windows PowerShell 5.1 encodes with $OutputEncoding (ASCII by default): the way out is its setting, not the file.
+            throw new Error("The JSON on stdin is not UTF-8. In Windows PowerShell 5.1 set `$OutputEncoding = [System.Text.UTF8Encoding]::new()` before piping, or save the JSON as UTF-8 (PowerShell: -Encoding utf8) and pass its path.");
+        }
+        if (text.trim() === "")
+            throw new Error("--fields-file - got nothing on stdin. Pipe in a JSON object, like {\"title\": \"Send the SOW\"}.");
+        return text;
+    }
+    let info;
+    try {
+        info = await stat(source);
+    }
+    catch (error) {
+        const code = error.code;
+        throw new Error(code === "ENOENT" ? `--fields-file ${source}: no such file.` : `--fields-file ${source}: cannot be read (${code ?? "unknown error"}).`);
+    }
+    if (!info.isFile())
+        throw new Error(`--fields-file ${source} is not a file.`);
+    if (info.size > FIELDS_FILE_MAX_BYTES) {
+        throw new Error(`--fields-file ${source} is ${Math.ceil(info.size / 1024)} KB; the limit is ${FIELDS_FILE_MAX_BYTES / 1024} KB. It holds a few fields of text; check it is the right file.`);
+    }
+    let bytes;
+    try {
+        bytes = await readFile(source);
+    }
+    catch (error) {
+        throw new Error(`--fields-file ${source}: cannot be read (${error.code ?? "unknown error"}).`);
+    }
+    const text = decodeFieldsBytes(bytes);
+    if (text.trim() === "")
+        throw new Error(`--fields-file ${source} is empty. Put a JSON object in it, like {"title": "Send the SOW"}.`);
+    return text;
+}
+function parseObject(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        // The engine's message quotes the file's own words: only the position is kept.
+        const at = /position (\d+)/.exec(error instanceof Error ? error.message : "")?.[1];
+        throw new Error(`The fields file is not valid JSON${at ? ` (near character ${at})` : ""}. It is one object: {"title": "Send the SOW", "detail": "Mo said \\"ok\\""}. A quote inside a value is written \\", a new line \\n.`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("The fields file must be one JSON object, like {\"title\": \"Send the SOW\"}, not a list or a single value.");
+    }
+    return parsed;
+}
+/** A string value: of the right type, and not a secret. */
+function text(key, value) {
+    if (typeof value !== "string")
+        throw new Error(`The fields file's "${key}" must be text${NULLABLE.has(key) ? " (or null to clear it)" : ""}.`);
+    rejectSecretLikeValue(value, `the fields file's "${key}"`);
+    return value;
+}
+/**
+ * Folds the file's fields into `values` as the flags they stand for, and returns the file's bullets (they have a
+ * shape of their own). Throws a sentence for: bad JSON, an unknown key, a key also given as a flag, a wrong type, a secret.
+ */
+export function mergeFieldsFile(values, verb, fileText) {
+    const fields = parseObject(fileText);
+    const allowed = FIELDS_FILE_KEYS[verb];
+    const keys = Object.keys(fields);
+    for (const key of keys) {
+        if (key === "version" || key === "timeline") {
+            throw new Error(`"${key}" is not a field: give ${flagOf(key)} as a flag. It is not read from the fields file.`);
+        }
+        if (!allowed.includes(key)) {
+            throw new Error(`The fields file has a key "${shown(key)}" that \`cockpit manager ${verb}\` does not take. It takes: ${allowed.join(", ")}.`);
+        }
+        const flag = key === "bullets" ? "--bullet" : flagOf(key);
+        if (values.flags.has(flag) || values.flagValues.has(flag)) {
+            throw new Error(`${key} is given both as ${flag} and in the fields file. Give it once, in one place.`);
+        }
+    }
+    const out = { keys: keys.length };
+    for (const key of keys) {
+        const value = fields[key];
+        if (key === "bullets") {
+            out.bullets = readBulletList(value);
+            continue;
+        }
+        const flag = flagOf(key);
+        if (value === null) {
+            if (!NULLABLE.has(key))
+                throw new Error(`The fields file's "${key}" must be text; null clears only ${[...NULLABLE].join(", ")}.`);
+            values.flags.set(flag, "none");
+        }
+        else if (key === "owners" && Array.isArray(value)) {
+            values.flags.set(flag, ownersText(value));
+        }
+        else {
+            // An empty string is allowed from a file (it can clear a detail); the shell parser refuses an empty flag value.
+            values.flags.set(flag, text(key, value));
+        }
+        values.flagValues.set(flag, [values.flags.get(flag)]);
+    }
+    return out;
+}
+/** `["Pip Moss", "Rowan Ash"]` as the flag's `Pip Moss, Rowan Ash`; `[]` clears (`none`), like the flag's `none`. */
+function ownersText(list) {
+    if (list.length === 0)
+        return "none";
+    const names = list.map((entry) => {
+        const name = text("owners", entry).trim();
+        if (name === "")
+            throw new Error("The fields file's \"owners\" has an empty name. Give names, or [] or null to clear them.");
+        if (name.includes(","))
+            throw new Error("A name in the fields file's \"owners\" cannot hold a comma: Tower splits people on commas. Write the name without it.");
+        return name;
+    });
+    return names.join(", ");
+}
+function readBulletList(value) {
+    if (!Array.isArray(value))
+        throw new Error("The fields file's \"bullets\" must be a list: [\"2026-10-14: Signed the SOW\", {\"date\": null, \"text\": \"Export still missing\"}].");
+    return value.map((entry, index) => {
+        if (typeof entry === "string")
+            return text("bullets", entry);
+        if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+            const { date, text: words, ...rest } = entry;
+            const extra = Object.keys(rest)[0];
+            if (extra !== undefined)
+                throw new Error(`Bullet ${index + 1} in the fields file has a key "${shown(extra)}"; a bullet is {"date": "YYYY-MM-DD" or null, "text": "..."}.`);
+            if (date !== null && date !== undefined && typeof date !== "string")
+                throw new Error(`Bullet ${index + 1}'s "date" must be "YYYY-MM-DD" or null.`);
+            if (typeof words !== "string")
+                throw new Error(`Bullet ${index + 1}'s "text" must be text.`);
+            rejectSecretLikeValue(words, `the fields file's "bullets"`);
+            return { date: date ?? null, text: words };
+        }
+        throw new Error(`Bullet ${index + 1} in the fields file must be a "YYYY-MM-DD: text" string or a {"date", "text"} object.`);
+    });
+}

package/dist/commands/manager-hints.js

@@ -0,0 +1,88 @@
+/**
+ * What `cockpit manager` tells a person after a refusal, and the limits it tells them (BLI-5777).
+ *
+ * A leaf module (it imports nothing) so the repo-shape tests can read it without pulling in the collector. Everything here
+ * is a COPY of something the manager server owns, and the CLI cannot import the server:
+ *
+ *   - `MANAGER_LIMITS_COPY` and `LONG_OVERDUE_DAYS_COPY`: the server's `TOWER_MANAGER_SUMMARY_LIMITS` and `SUMMARY_LONG_OVERDUE_DAYS`;
+ *   - `SUMMARY_REFUSAL_NAMES`: the server's `TOWER_MANAGER_SUMMARY_REFUSALS`, same names in the same order;
+ *   - `ITEM_REFUSAL_NAMES`: the server's `ReviewRefusal` (`db/review.ts`) and `item_busy`, less `not_found` (the `not_found` reason answers it);
+ *   - `READ_ONLY_REFUSAL_NAMES`: the door's `ReadOnlyRefusalReason`.
+ *
+ * `apps/dashboard/src/repo-shape/manager-copies.test.ts` fails the moment a copy differs from the server's, and each hint map
+ * is typed against its own name list (`satisfies Record<…>`), so a name added to the list without a hint fails `tsc`.
+ * A new module like this one joins `scripts/build-public-cli.mjs` `runtimeFiles` or the packed CLI breaks while the tests stay green.
+ */
+export const MANAGER_LIMITS_COPY = { headlineMax: 140, bulletsMinPerson: 1, bulletsMax: 5, bulletMax: 160, nextMax: 200, blockerMax: 200 };
+/** More than this many days past due, an open action makes the card at risk: a copy of the server's `SUMMARY_LONG_OVERDUE_DAYS`. */
+export const LONG_OVERDUE_DAYS_COPY = 14;
+const L = MANAGER_LIMITS_COPY;
+export const SUMMARY_REFUSAL_NAMES = [
+    "summary_changed", "summary_empty", "summary_incomplete", "summary_health_invalid", "summary_headline_empty", "summary_headline_too_long",
+    "summary_bullets_count", "summary_bullet_empty", "summary_bullet_too_long", "summary_bullet_date_invalid", "summary_next_too_long",
+    "summary_blocker_too_long", "summary_blocked_needs_blocker", "summary_blocker_needs_blocked",
+];
+/** The way forward after each named refusal of a "Where we are" edit; `home` is the ready-to-run `cockpit manager home <client> --json`. */
+export function summaryHints(home) {
+    // A hint is the next step in this terminal's own words (the flag to pass, the command to run). It never says the server's sentence again.
+    return {
+        summary_changed: `Read the card again with ${home} and retry with its summary.updatedAt as --version (none only when it has no card).`,
+        summary_empty: "Pass at least one of --health, --headline, --bullet, --next, --blocker.",
+        summary_incomplete: "Pass --health, --headline and --bullet together, with --version none.",
+        summary_health_invalid: "Pass --health with one of those words, in lower case with underscores.",
+        summary_headline_empty: "A blank or invisible-only --headline counts as empty.",
+        summary_headline_too_long: `Shorten --headline: the limit (${L.headlineMax}) counts characters, not bytes.`,
+        summary_bullets_count: "Each --bullet is one bullet, and together they replace the whole list.",
+        summary_bullet_empty: "Put words after a --bullet's date, when it has one.",
+        summary_bullet_too_long: `Shorten the long --bullet (the limit is ${L.bulletMax}).`,
+        summary_bullet_date_invalid: "Start a dated --bullet with \"YYYY-MM-DD: \" and a real day.",
+        summary_next_too_long: `Shorten --next (the limit is ${L.nextMax}).`,
+        summary_blocker_too_long: `Shorten --blocker (the limit is ${L.blockerMax}).`,
+        summary_blocked_needs_blocker: "Add --blocker <what blocks it>, or pass another --health.",
+        summary_blocker_needs_blocked: "Add --health blocked, or leave --blocker out (`--blocker none` clears the stored one).",
+    };
+}
+export const ITEM_REFUSAL_NAMES = [
+    "item_changed", "item_busy", "item_archived", "item_not_archived", "item_dismissed", "person_item_not_dismissable",
+    "no_proposal", "proposal_replaced", "timeline_not_live", "request_reused", "proposal_decided", "proposal_not_addable",
+];
+/** Refusals that mean "the item is not as you last saw it": reading it again is the way forward. */
+export const RESEEN_REFUSALS = new Set(["item_changed", "item_busy", "proposal_decided", "no_proposal"]);
+/** The way forward after each named refusal of an item write. `flag` is " --timeline" for a timeline item, else "". */
+export function itemHints(id, flag) {
+    const reread = `Run \`cockpit manager show ${id}${flag}\` for the current version.`;
+    return {
+        item_changed: reread,
+        item_busy: reread,
+        no_proposal: reread,
+        proposal_decided: reread,
+        // The request id IS the item's id (an add made it): show it; a retry already made it, and a different item needs no request id.
+        request_reused: "The request id is that item's id: `cockpit manager show <request-id>` shows it. If you were retrying an add, it is already there: don't add it again. To add a different item, run the add without --request-id.",
+        proposal_replaced: `Run \`cockpit manager show ${id}${flag}\` to see the suggested changes waiting and their ids.`,
+        proposal_not_addable: `Run \`cockpit manager proposal ${id} <proposal-id> accept --version <v>\` (or dismiss).`,
+        item_archived: `Bring it back with \`cockpit manager unarchive ${id}${flag} --version <v>\` (\`list <client>${flag} --archived\` prints its version).`,
+        item_dismissed: `Run \`cockpit manager approve ${id}${flag} --version <v> --restore\` (\`list <client>${flag} --review dismissed\` prints its version).`,
+        person_item_not_dismissable: `Run \`cockpit manager archive ${id}${flag} --version <v>\`.`,
+        timeline_not_live: "`cockpit manager list <client> --timeline` lists the client's live timeline items.",
+        item_not_archived: "Nothing to bring back: it is in the lists already.",
+    };
+}
+/**
+ * The door's own refusals of a read-only device token (`ReadOnlyRefusalReason`): they reach the terminal as the `reason`
+ * (BLI-5777; before, the 403 carried no name and the CLI printed `http_403`).
+ */
+export const READ_ONLY_REFUSAL_NAMES = ["read_only_device_cannot_write", "read_only_device_door_not_listed", "read_only_device_on_admin"];
+export const READ_ONLY_HINTS = {
+    read_only_device_cannot_write: " Sign in as the person who is asking with `cockpit login`.",
+    read_only_device_door_not_listed: " A brain session's key may not read Tower Manager: sign in as the person who is asking with `cockpit login`.",
+    read_only_device_on_admin: " Mint the read-only key for a member instead.",
+};
+/** A read's workflow id (`sched_wf_…`, `wf-…`): what `lastRead.workflowRunId` holds in `client --json` and `home --json`. It is not a run's receipt id. */
+export const looksLikeWorkflowId = (value) => /^(?:[a-z]+_)?wf[-_]/i.test(value);
+/** Where a run's receipt id really comes from, for the refusal of anything else (`run <run-id>`). */
+export function runIdRefusal(value) {
+    const where = "A run id looks like 8f14e45f-ceea-467a-9575-1d3a4e7b2c10. It comes from `cockpit manager queue <client> --json` (a row's changedByRunId), `cockpit manager show <id>` (a suggested change's runId) or `cockpit manager client <client> --json` (lastBriefRebuild.runId); `list` does not print run ids.";
+    return looksLikeWorkflowId(value)
+        ? `That is a read's workflow id (the lastRead.workflowRunId that \`client --json\` and \`home --json\` print), not a run's receipt id. ${where}`
+        : where;
+}