@clearlysh/beehaven 0.8.16

package/dist/commands/help.js

@@ -0,0 +1,2418 @@
+/**
+ * beehaven help <command> — deep per-command help.
+ *
+ * `beehaven --help` prints the whole surface in one shot (great for
+ * humans scanning). `beehaven help <cmd>` prints just one command's
+ * synopsis, flags, and 2-3 examples. Agents use this before running
+ * unfamiliar commands.
+ *
+ * The help text lives inline here (not as a parallel docs directory)
+ * so it stays in lockstep with the CLI's actual behavior. Each entry
+ * mirrors the dispatch logic in cli.ts; change both together.
+ *
+ * Design constraint: every help page MUST end with "Related:" so the
+ * agent can navigate to adjacent commands without re-reading the
+ * top-level help. Keeps the "pwd → actions → call" loop tight.
+ */
+import { HIDDEN_PUBLIC_COMMANDS } from '../public-surface.js';
+/** Cheap edit distance for "did you mean" — ranking only, not optimal. */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (Math.abs(a.length - b.length) > 3)
+        return 99;
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+const PAGES = {
+    /**
+     * ⚠⚠ THE WORK ARTIFACTS — `ticket`, `board`, `sheet`, `slides`. `ticket` and `board` shipped
+     * 2026-09-04 in NEITHER help output, which is how the busiest new domain on the surface
+     * (1,062 calls) became findable only by already knowing it was there. `sheet` and `slides`
+     * are new here and documented in the same commit, per this package's own rule: a verb is added
+     * to `printHelp()` AND given a page.
+     */
+    /**
+     * ⚠ `open` IS IN THE DEFAULT HELP AND HAD NO PAGE — the same gap the block below records for
+     * the first-run commands, on a verb three of these pages point at. A "Related" link to a page
+     * that does not exist is a dead end at exactly the moment someone is looking for more.
+     */
+    open: {
+        synopsis: 'beehaven open <id|key|title> [--browser]',
+        description: 'Put something on screen. Takes a composition, document, board, project or ticket — addressed by '
+            + 'id, by a KEY like CLR-42, or by an exact title — and navigates an already-open tab to it. It '
+            + 'ALWAYS prints the URL, so it is useful with no tab open and safe in a script.\n\n'
+            + 'This is how you hand a person the thing you just made: create it, then open it.\n\n'
+            + '⚠⚠ THE KEY FORM DID NOT WORK UNTIL 2026-09-05 (CBH2-5) — the example below, printed on this '
+            + 'very page, answered "Nothing in this workspace has id \'CLR-42\'". Only a uuid resolved, so the '
+            + 'one verb whose whole job is handing someone a link required a SQL query first, on a workspace '
+            + 'that mints keys precisely so nobody carries a uuid. An ambiguous key or title is now refused '
+            + 'with the candidates listed, never guessed.\n\n'
+            + '⚠ THE PRINTED URL FOLLOWS `beehaven env`. It used to be whichever origin a connected browser '
+            + 'last reported, so a colleague\'s localhost dev tab could make this print a dead link (CBH-45).',
+        flags: [
+            { name: '--browser', desc: 'Also open it in your local browser, rather than only navigating an existing tab.' },
+        ],
+        examples: [
+            { cmd: 'beehaven open CLR-42' },
+            { cmd: 'beehaven open S1-14', note: 'a ticket key — opens its board with the card up' },
+            { cmd: 'beehaven open <compositionId> --browser' },
+        ],
+        related: ['ticket', 'sheet', 'slides'],
+    },
+    comment: {
+        synopsis: 'beehaven comment <ref> "text" [--quote|--slide|--cell|--sheet|--column|--pin|--x --y] [--reply <id>]',
+        description: 'Comment on ANY workspace item — a document, sheet, deck, ticket, board, thought or canvas — by id, '
+            + 'key (SS-41, CLR-42) or exact title. It dispatches to that surface\'s own comment verb, so every '
+            + 'anchor rule and permission applies unchanged; an anchor the surface cannot carry is REFUSED, never '
+            + 'silently dropped.\n\n'
+            + '`@handle` in the text mentions a person (they are notified) or an agent (it is queued in that '
+            + 'agent\'s inbox and shown in its next brief until acknowledged). The receipt says who was reached '
+            + 'and names any handle that matched nobody. `beehaven mention who` lists the handles that resolve.',
+        flags: [
+            { name: '--quote <text>', desc: 'Document: the exact passage to anchor to.' },
+            { name: '--slide <n|id>', desc: 'Deck: the slide (1-based or id). Required on a deck.' },
+            { name: '--cell <A1>', desc: 'Sheet: the cell, optionally with its tab ("Q1!B4"). Omit for the whole sheet.' },
+            { name: '--sheet <tab>', desc: 'Sheet: the tab name or id, when --cell names none.' },
+            { name: '--column <key|label>', desc: 'Board: pin the comment to a column.' },
+            { name: '--pin <id>', desc: 'Canvas: reply to an existing comment pin.' },
+            { name: '--x <n> --y <n>', desc: 'Canvas: drop a new pin at these world coordinates.' },
+            { name: '--reply <id>', desc: 'Reply to an existing comment.' },
+            { name: '--kind <k>', desc: 'Disambiguate a <ref> that names two kinds of thing.' },
+            { name: '--json', desc: 'Raw result instead of the summary.' },
+        ],
+        examples: [
+            { cmd: 'beehaven comment SS-41 "Ready for review @admin"' },
+            { cmd: 'beehaven comment "Q3 plan" "This total looks off @omni" --cell "Plan!D12"' },
+            { cmd: 'beehaven comment <deckId> "Tighten this headline" --slide 3' },
+            { cmd: 'beehaven comments SS-41 --all' },
+        ],
+        related: ['mention', 'ticket'],
+    },
+    mention: {
+        synopsis: 'beehaven mention [list|ack <id>|who [query]|resolve "text"]',
+        description: 'Where you were @mentioned, and who an @ can reach. As an agent, `beehaven mention` lists the '
+            + 'mentions queued in your inbox — the same list your brief prints under "Addressed to you". Act on '
+            + 'one (reply with `beehaven comment`), then `ack` it: an unacknowledged mention replays in every '
+            + 'brief, and you will do the work twice. `who` lists people and agents from the same index the '
+            + 'server delivers against, so a handle it offers always resolves.',
+        flags: [
+            { name: '--all', desc: 'On list: include acknowledged mentions.' },
+            { name: '--json', desc: 'Raw result.' },
+        ],
+        examples: [
+            { cmd: 'beehaven mention' },
+            { cmd: 'beehaven mention ack 3f2a9c1e' },
+            { cmd: 'beehaven mention who jin' },
+            { cmd: 'beehaven mention resolve "cc @omni and @bob"' },
+        ],
+        related: ['comment'],
+    },
+    ticket: {
+        synopsis: 'beehaven ticket <create|list|move|edit|show|comment|comments|delete> [args]',
+        description: 'Cards on a board. A card IS a ticket — one board model — so this is what files work, not `task`, '
+            + 'which makes a NOTE. Every subcommand takes a key (CLR-42) or a row id.\n\n'
+            + 'The verb exists to make three already-shipped traps untypeable: --priority takes a WORD, because '
+            + 'the API scale is 0-3 with 3 the MOST urgent (the opposite of P0/P1, and a card meant as top '
+            + 'priority filed as 0 becomes the least urgent thing on the board with nothing to say so); the body '
+            + 'is sent as `body`, never `description`, which validation would strip; and the type is sent as '
+            + '`issueType`, never `type`, which the wire uses as its own action discriminator.\n\n'
+            + 'WHERE a card is lives on `move` (its column, and its board); WHAT a card says lives on `edit`. '
+            + 'Two verbs writing one field is the two-doors failure this CLI names repeatedly, so `edit` '
+            + 'refuses --status and --board rather than duplicating them.\n\n'
+            + '`delete` is the only DESTRUCTIVE subcommand and behaves unlike `board delete`: it PREVIEWS '
+            + 'the card and refuses without --yes. Board deletion is safe to fire because the server refuses '
+            + 'while any card references the board; nothing equivalent protects a card. Measured against a '
+            + 'real workspace: it is a HARD delete (the row is gone, not archived, with nothing to restore '
+            + 'from), it is NOT idempotent (a second attempt answers not-found, identical to a typo\'d key), '
+            + 'and it ORPHANS the card\'s comments rather than removing them.',
+        flags: [
+            { name: '--board <id>', desc: 'Which board. Defaults to the oldest non-archived one. On `move`, where to move it TO.' },
+            { name: '--body <text>', desc: 'The card description. Sent as `body` — `description` would be stripped.' },
+            { name: '--type <t>', desc: 'epic | story | task | bug | subtask' },
+            { name: '--priority <p>', desc: 'low | medium | high | urgent — a WORD, never a number.' },
+            { name: '--status <s>', desc: 'todo | in-progress | in-review | done. On `create` only — to change one, use `move`.' },
+            { name: '--assignee <who>', desc: 'Who owns it.' },
+            { name: '--due <when>', desc: 'ISO date (2026-10-01), a full timestamp, or epoch ms. Parsed to a number — the column is epoch ms.' },
+            { name: '--allow-duplicate', desc: 'On `create`: file a second card with a title already open on this board.' },
+            { name: '--limit <n>', desc: 'On `list`: how many cards, default 100, ceiling 500 (the server\'s). A full page says so.' },
+            { name: '--title <t>', desc: 'On `edit`: rename the card.' },
+            { name: '--points <n>', desc: 'On `edit`: size it. A board nobody sizes reports 0 points in `board report`.' },
+            { name: '--epic <id>', desc: 'On `edit`: file it under an epic.' },
+            { name: '--parent <id>', desc: 'On `edit`: its parent card (a subtask needs one).' },
+            { name: '--sprint <id>', desc: 'On `edit`: the sprint it belongs to. `beehaven sprint plan` is the bulk form.' },
+            { name: '--resolution <r>', desc: 'On `edit`: WHY it closed. Its own column — a reason in `body` is indistinguishable from the report.' },
+            { name: '--reply <id>', desc: 'On `comment`: reply to an existing note.' },
+            { name: '--all', desc: 'On `comments`: include resolved notes.' },
+            { name: '--yes', desc: 'On `delete`: actually destroy the card. Without it the card is shown and nothing is deleted.' },
+            { name: '--json', desc: 'Raw result instead of the summary.' },
+        ],
+        examples: [
+            { cmd: 'beehaven ticket create "Fix the login redirect" --priority high --type bug' },
+            { cmd: 'beehaven ticket list --board <id> --status todo --limit 300' },
+            { cmd: 'beehaven ticket move CLR-42 done' },
+            { cmd: 'beehaven ticket edit CLR-42 --points 3 --due 2026-10-01' },
+            { cmd: 'beehaven ticket comment CLR-42 "shipped in 0.8.2"' },
+        ],
+        related: ['board', 'sprint', 'task', 'open'],
+    },
+    board: {
+        // ⚠ NO `show`. The synopsis said `<list|create|show>` while the description below explained
+        //   there deliberately is no `board show` — a page contradicting itself in eight lines, and
+        //   `cmdBoard` implements exactly two subcommands. A synopsis is the part people copy.
+        synopsis: 'beehaven board <list|create|delete|columns|report|backlog> [args]',
+        description: 'Boards hold cards. A ticket REQUIRES a board — `ticket-create` refuses without one, because a card '
+            + 'with no board is one you made, were told about, and cannot find.\n\n'
+            + 'The board title derives the ticket key prefix ("Sprint 1" → S1-14), and the prefix records where '
+            + 'a card was BORN, not where it lives now: moving a card between boards does not re-key it.\n\n'
+            + 'To read a board WITH its cards, `cat "~/<Board>.board.json"` does it in one call — there is '
+            + 'deliberately no `board show` duplicating that.\n\n'
+            + '`delete` REFUSES while any ticket still references the board, closed ones included — unpinning '
+            + 'them would leave real cards on no board, which is the state `ticket-create` requires a board to '
+            + 'prevent. Move them first. It must be given a name: with none, board resolution falls back to the '
+            + 'OLDEST board in the workspace, which is right for filing a card and catastrophic for a delete.\n\n'
+            + '`columns` is the board\'s WORKFLOW, and it is read-only here. A column key IS a legal status '
+            + 'on that board, so the column set is the vocabulary cards are filed in — and it had no human '
+            + 'reader at all: `board-get` returns it as a JSON STRING in a raw row and says nothing about '
+            + 'cards. This joins it to the cards, so it also reports STRANDED statuses: words held by real '
+            + 'cards that no column defines, which draw in no column and cannot be dragged.\n\n'
+            + 'Changing the workflow stays `beehaven call board-columns-set` on purpose while CBH2-143 is '
+            + 'in review — that ticket is deciding whether the action reports, refuses or migrates stranded '
+            + 'cards, and a CLI writer would be a second implementation of the same safety rule. Read first, '
+            + 'then call: the action migrates nothing, so a card whose status word you remove keeps it.\n\n'
+            + '`report` is the tracker metric (velocity, burndown, cycle-time) — server-computed, so nobody '
+            + 'derives velocity by hand. Points come from the `points` COLUMN, so a board nobody sized reports '
+            + 'zero truthfully. `backlog` is what sprint planning pulls from; it is NOT status-filtered, so '
+            + 'finished cards that were never put in a sprint appear in it too.',
+        flags: [
+            { name: '--project <id>', desc: 'On `create`: file the board under a project.' },
+            { name: '--kind <k>', desc: 'On `report`: summary (default) | velocity | burndown | cycle-time.' },
+            { name: '--sprint <id>', desc: 'On `report`: scope a burndown to one sprint.' },
+            { name: '--board <b>', desc: 'Name the board, instead of passing it as a positional.' },
+            { name: '--json', desc: 'Raw result instead of the summary.' },
+        ],
+        examples: [
+            { cmd: 'beehaven board list' },
+            { cmd: 'beehaven board create "Sprint 2"' },
+            { cmd: 'beehaven board delete "Old probe board"', note: 'refuses while cards are on it' },
+            { cmd: 'beehaven board report "Sprint 2" --kind velocity' },
+            { cmd: 'beehaven board backlog "Sprint 2"' },
+            { cmd: 'cat "~/Sprint 2.board.json"', note: 'the board and every card on it' },
+        ],
+        related: ['ticket', 'sprint', 'open'],
+    },
+    /**
+     * ⚠⚠ THIS PAGE EXISTS BECAUSE A SHIPPED PROMPT POINTED AT VERBS THE CLI DID NOT HAVE — CBH2-107.
+     * `daemon-omni-company.ts` tells agents to call `sprint-create` / `-plan` / `-start` / `-complete`
+     * and `burndown`; all of it was `beehaven call`-only.
+     */
+    sprint: {
+        synopsis: 'beehaven sprint <list|create|plan|start|complete|delete> [args]',
+        description: 'The planning cycle on a board. A sprint is created `planned`, `start` makes it `active` (one per '
+            + 'board at a time), and `complete` closes it and records the velocity datapoint.\n\n'
+            + 'STARTING FREEZES THE COMMITMENT. `committed_points` is captured at `start` and never recomputed, '
+            + 'because velocity measured against a denominator that grows as cards are added mid-sprint always '
+            + 'looks fine — which is the failure the metric exists to catch. So size the cards BEFORE you start; '
+            + 'a card sized afterwards does not count.\n\n'
+            + '⚠ `delete`, NOT `complete`, IS THE UNDO. A completed sprint is a permanent velocity datapoint '
+            + 'that `board report` averages over, so completing a junk sprint corrupts the metric instead of '
+            + 'discarding it. `delete` sends its cards back to the backlog and never deletes them.\n\n'
+            + 'Sprints are addressed by NAME here (or by id). Auto-numbering means two boards routinely both '
+            + 'hold a "Sprint 1", so an ambiguous name is refused rather than guessed — narrow it with --board.\n\n'
+            + '⚠ `sprint plan` resolves card KEYS to row ids before calling. The underlying `sprint-plan` action '
+            + 'takes ROW IDS and answers `{ ok: true, moved: 1 }` for a key it never moved, so `beehaven call '
+            + 'sprint-plan` with keys silently does nothing.',
+        flags: [
+            { name: '--board <b>', desc: 'Which board. Required in effect on `create`; narrows an ambiguous name elsewhere.' },
+            { name: '--state <s>', desc: 'On `list`: planned | active | completed. A SPRINT\'s lifecycle, not a card\'s column.' },
+            { name: '--goal "<g>"', desc: 'On `create`: what the sprint is for.' },
+            { name: '--remove', desc: 'On `plan`: take the cards OUT, back to the backlog.' },
+            { name: '--sprint <id>', desc: 'On `complete`: where unfinished cards go. Omitted, they go to the backlog.' },
+            { name: '--force', desc: 'On `delete`: delete an ACTIVE sprint — the one people are working in.' },
+            { name: '--json', desc: 'Raw result instead of the summary.' },
+        ],
+        examples: [
+            { cmd: 'beehaven sprint list --board "Sprint 2"' },
+            { cmd: 'beehaven sprint create "Sprint 3" --board "Sprint 2" --goal "Close the parity gaps"' },
+            { cmd: 'beehaven sprint plan "Sprint 3" CLR-42 CLR-43' },
+            { cmd: 'beehaven sprint start "Sprint 3"' },
+            { cmd: 'beehaven sprint complete "Sprint 3"' },
+            { cmd: 'beehaven board report --kind velocity', note: 'how the last sprints actually went' },
+        ],
+        related: ['board', 'ticket'],
+    },
+    sheet: {
+        synopsis: 'beehaven sheet <list|new|get|set|append|import> [args]',
+        description: 'Spreadsheets. A sheet is a document row — key, project filing, trash and search like anything else.\n\n'
+            + '⚠ `set` and `append` are not synonyms. `set` writes a block at an ANCHOR cell and replaces what is '
+            + 'there; `append` adds after the last populated row and never overwrites. The underlying action takes '
+            + '`{ at, rows }`, not a range and a blob — this verb takes the anchor and does the TSV parse, because '
+            + 'sending `{ range, tsv }` is two unknown keys that validation strips, leaving a call that returns ok '
+            + 'having written nothing.\n\n'
+            + 'Formulas work: `=SUM(B2:B9)` comes back as its computed total, not as text.',
+        flags: [
+            { name: '--range <a1>', desc: 'get only — the range to read, e.g. A1:D20.' },
+            { name: '--project <id>', desc: 'File a new sheet into a project.' },
+            { name: '--title <t>', desc: 'import only — title for the created sheet.' },
+            { name: '--json', desc: 'Raw result instead of the table.' },
+        ],
+        examples: [
+            { cmd: 'beehaven sheet new "Q1 revenue"' },
+            { cmd: 'beehaven sheet set CLR-42 A1 "Region\\tQ1\\nAPAC\\t7"', note: 'A1 is the top-left cell, not a range' },
+            { cmd: 'beehaven sheet append CLR-42 "EMEA\\t9"' },
+            { cmd: 'beehaven teleport ./data.csv && beehaven sheet import <fileId>' },
+        ],
+        related: ['slides', 'teleport', 'doc'],
+    },
+    brand: {
+        synopsis: 'beehaven brand <list|show|tokens|new|set|edit|default|bind|board|history|revert|rm|restore> [args]',
+        description: 'The workspace brand — colours by role (light + dark), five type roles, logos, voice and shape — '
+            + 'the same object agents read with `brand` / clearly_brand and the Brand studio edits.\n\n'
+            + '⚠ `brand set <brand> color.<role> <hex>` changes ONE colour. It always sends the role map; '
+            + 'sending `colors` as an array (e.g. via `brand edit --patch`) REPLACES the whole palette.\n\n'
+            + '`show`, `tokens` and `board` use the workspace default brand when you omit one. Every edit is a '
+            + 'version (`history`, `revert`), and `rm` is recoverable with `restore`.',
+        flags: [
+            { name: '--format css|json', desc: 'tokens — CSS custom properties or the token map (default json).' },
+            { name: '--mode dark', desc: 'tokens — the dark-mode values.' },
+            { name: '--composition <id>', desc: "tokens/show — that canvas's bound brand; bind/board — the target canvas." },
+            { name: '--patch <json|@file>', desc: 'edit — any brand patch.' },
+            { name: '--from <brand>', desc: 'new — duplicate an existing brand.' },
+            { name: '-o, --output <file>', desc: 'tokens — write to a file.' },
+            { name: '--json', desc: 'Raw result.' },
+        ],
+        examples: [
+            { cmd: 'beehaven brand show' },
+            { cmd: "beehaven brand set Harbor color.accent '#FF5500'", note: 'one role; the rest of the palette is untouched' },
+            { cmd: 'beehaven brand set Harbor type.heading Fraunces' },
+            { cmd: 'beehaven brand tokens --format css -o brand.css' },
+            { cmd: 'beehaven brand board Harbor', note: 'an editable brand board on a new canvas' },
+        ],
+        related: ['component', 'open'],
+    },
+    component: {
+        synopsis: 'beehaven component <list|show|render|place|save|new|edit|dup|history|revert|rm|restore> [args]',
+        description: 'The workspace component library — reusable blocks whose colours and faces are brand tokens, so '
+            + 'they render in whatever brand a canvas uses. The same library as the editor\'s Assets tab and '
+            + 'the agent tool `component` / clearly_component.\n\n'
+            + '`place` puts a component on a canvas (resolved in its brand); `save` turns a canvas node and its '
+            + 'layers into a component, re-binding brand colours and faces to tokens.\n\n'
+            + '⚠ Placing into a canvas you have open in the editor: prefer the Assets tab or ⌘⌥K — the editor '
+            + 'owns its scene while it is open.',
+        flags: [
+            { name: '--composition <id>', desc: 'place/save — the canvas.' },
+            { name: '--x <n> --y <n>', desc: 'place — top-left, world coords (frame-relative with --parent).' },
+            { name: '--parent <frame>', desc: 'place — nest inside this frame (id or name).' },
+            { name: '--variant <name>', desc: 'place/render — e.g. Secondary.' },
+            { name: '--props <json>', desc: 'place/render — prop values, e.g. \'{"label":"Buy now"}\'.' },
+            { name: '--brand <brand>', desc: 'place/render/show — render in this brand instead.' },
+            { name: '--patch <json|@file>', desc: 'new/edit — a component spec or patch.' },
+            { name: '--category <c>', desc: 'list/save — actions, inputs, display, navigation, feedback, layout, marketing, brand.' },
+            { name: '-o, --output <file>', desc: 'render — write the SVG.' },
+            { name: '--json', desc: 'Raw result.' },
+        ],
+        examples: [
+            { cmd: 'beehaven component list --category marketing' },
+            { cmd: 'beehaven component render pricing-card --variant Featured -o card.svg' },
+            { cmd: 'beehaven component place button --composition <id> --x 120 --y 80 --props \'{"label":"Start"}\'' },
+            { cmd: 'beehaven component save --composition <id> "Hero frame" --name "Marketing hero"' },
+        ],
+        related: ['brand', 'canvas', 'open'],
+    },
+    slides: {
+        synopsis: 'beehaven slides <list|new|get|add|move|rm|layouts|show|export> [args]',
+        description: 'Presentations. A deck is a document row like any other artifact here.\n\n'
+            + '⚠ `show` renders a deck to LOOK at; `export` produces a FILE to take away. They are different '
+            + 'actions with near-identical names, so they are two subcommands named for the job.\n\n'
+            + '⚠ `move` needs a destination and the action refuses without one — so this verb takes it '
+            + 'positionally (`slides move <id> <n> <to>`) rather than as a flag you can forget.\n\n'
+            + '⚠ A layout typed from memory does not error: an unrecognised one silently falls back to '
+            + '`titleBody`. Run `slides layouts` first.',
+        flags: [
+            { name: '--layout <id>', desc: 'A layout id from `slides layouts`.' },
+            { name: '--bullets "a|b|c"', desc: 'PIPE-separated — a bullet often contains a comma.' },
+            { name: '--notes <text>', desc: 'Speaker notes.' },
+            { name: '--at <n>', desc: 'add only — 1-based insert position. Omit to append.' },
+            { name: '--slide <n>', desc: 'get / show — one slide instead of the whole deck.' },
+            { name: '--aspect <a>', desc: 'new only — 16:9 (default) or 4:3.' },
+            { name: '--format <f>', desc: 'export — pptx | html | markdown | notes | svg.' },
+            { name: '--json', desc: 'Raw result instead of the outline.' },
+        ],
+        examples: [
+            { cmd: 'beehaven slides new "Q1 review" --aspect 16:9' },
+            { cmd: 'beehaven slides add CLR-42 "Results" --bullets "Revenue up 12%|Churn flat"' },
+            { cmd: 'beehaven slides move CLR-42 5 2', note: '<to> is required — the action refuses without it' },
+            { cmd: 'beehaven slides export CLR-42 --format pptx' },
+        ],
+        related: ['sheet', 'open', 'teleport'],
+    },
+    /**
+     * ⚠⚠ THE FIRST-RUN COMMANDS HAD NO HELP PAGES AT ALL — CLR-1150. `beehaven help login`
+     * answered *"No help page for \"login\""* and exited 1. Every command a new user runs in
+     * their first five minutes — login, start, stop, restart, status, doctor, env, whoami —
+     * was absent, while `cd`, `canvas` and `sql` were richly documented.
+     *
+     * That is backwards: deep help matters most where the user has least context, and least
+     * where they have already found the verb.
+     */
+    login: {
+        synopsis: 'beehaven login',
+        description: `Sign in. Opens your browser, then starts (or restarts) the daemon so the
+    new tokens take effect — the daemon reads credentials at startup and has no hot-reload.
+
+    A restart alone will NOT refresh an expired token; \`login\` is the fix for that.`,
+        examples: [
+            { cmd: 'beehaven login' },
+            { cmd: 'beehaven status', note: 'confirms the relay actually connected' },
+        ],
+        related: ['logout', 'whoami', 'status', 'doctor'],
+    },
+    logout: {
+        synopsis: 'beehaven logout',
+        description: 'Clear stored credentials (keychain + ~/.beehaven/config.json).',
+        related: ['login', 'whoami'],
+    },
+    whoami: {
+        synopsis: 'beehaven whoami',
+        description: 'Print the signed-in account and the workspace it resolves to.',
+        related: ['login', 'status'],
+    },
+    start: {
+        synopsis: 'beehaven start [--headless] [--dev]',
+        description: `Bring up the daemon — the local process every other command talks to.
+
+    \`--headless\` is the CLI-owned daemon and works on every platform. Bare \`start\`
+    opens the Hive Mac tray app instead, which is macOS-only; the tray is required only for
+    the LOCAL hive (avatar building, voice, mood), never for calls, MCP or SQL.
+
+    Only one daemon runs at a time. If one already owns the socket, \`--headless\` refuses.`,
+        flags: [
+            { name: '--headless', desc: 'Spawn a standalone daemon (no Mac app needed)' },
+            { name: '--dev', desc: 'Grant developer scope (same as HIVE_DEV_MODE=1)' },
+        ],
+        examples: [
+            { cmd: 'beehaven start --headless' },
+            { cmd: 'HIVE_DEV_MODE=1 beehaven start --headless', note: 'needed for admin:* and raw-VFS commands' },
+            { cmd: 'beehaven stop && beehaven start --headless', note: 'the reliable way to pick up a deploy' },
+        ],
+        related: ['stop', 'restart', 'status', 'doctor', 'env'],
+    },
+    stop: {
+        synopsis: 'beehaven stop',
+        description: `Stop the daemon and release the IPC socket.
+
+    Also the first half of the sequence that makes a fresh worker deploy visible: a resident
+    Durable Object keeps serving the OLD code while any client holds a socket open.`,
+        examples: [{ cmd: 'beehaven stop && sleep 15 && beehaven start --headless' }],
+        related: ['start', 'restart', 'status'],
+    },
+    restart: {
+        synopsis: 'beehaven restart [--dev]',
+        description: `Stop and start in one step.
+
+    It does NOT refresh an expired token — that is \`beehaven login\`. And a bare restart
+    DROPS developer scope: pass --dev (or set HIVE_DEV_MODE=1) to keep it.`,
+        related: ['start', 'stop', 'login', 'status'],
+    },
+    doctor: {
+        synopsis: 'beehaven doctor',
+        description: `Diagnose the whole chain — Node version, daemon process, IPC socket, relay
+    state (splitting "token expired" from "socket dropped"), and a live list-actions
+    round-trip. Every failing line carries the command that fixes it.
+
+    Reach for this before debugging anything else.`,
+        related: ['status', 'start', 'login', 'env'],
+    },
+    env: {
+        synopsis: 'beehaven env [staging|prod|dev] [--confirm]',
+        description: `Show or switch which backend the daemon talks to.
+
+    Prod requires --confirm: a safety interlock, so a billable or destructive command is not
+    run against live customer data in the belief that it is staging.
+
+    A switch is not live until the daemon cycles.
+
+    ⚠ --env on other commands does NOT do this. Every call goes wherever the daemon points.`,
+        examples: [
+            { cmd: 'beehaven env', note: 'print the active env + relay URL' },
+            { cmd: 'beehaven env staging' },
+            { cmd: 'beehaven env prod --confirm' },
+        ],
+        related: ['status', 'doctor', 'restart'],
+    },
+    cd: {
+        synopsis: 'beehaven cd <addr>',
+        description: `Set the active target. Writes ~/.beehaven/target.json so subsequent
+    commands (call, actions, ls, etc.) know where to route.
+
+    Address shapes:
+      home                            Your default workspace (alias)
+      workspace/<id>                  Any explicit workspace DO
+      <type>/<id>                     Another cloud DO — e.g. shopifyStore/clearly-demo
+      <appName>                       A local installed app — e.g. recorder, avatar
+
+    Inside a workspace, each signed human or agent has a personal layer for private drafts,
+    recents, sessions and memory. Changing identity changes that layer; it does not change DOs.
+
+    Aliases: connect, nav, navigate`,
+        examples: [
+            { cmd: 'beehaven cd home', note: 'back to default workspace' },
+            { cmd: 'beehaven cd workspace/<workspaceId>', note: 'another workspace' },
+            { cmd: 'beehaven cd shopifyStore/clearly-demo', note: 'cloud DO' },
+            { cmd: 'beehaven cd recorder', note: 'local app' },
+        ],
+        related: ['pwd', 'disconnect', 'buildings', 'actions'],
+    },
+    pwd: {
+        synopsis: 'beehaven pwd',
+        description: `Show the current target + "what you can do here" hints. Reads
+    ~/.beehaven/target.json — works even when the daemon isn't running.
+    Agents should call this FIRST in any new session to self-orient.
+
+    ⚠⚠ ITS OWN HINT LINE \`call project-list '{}' --building home\` IS REFUSED IF
+    YOU ARE SIGNED IN AS AN AGENT, which almost every reader of pwd is:
+        Cannot use --building while signed in as "<name>".
+        A proxied call cannot be attributed to an agent in the target workspace.
+    Drop the flag — \`beehaven call project-list '{}'\` works and is attributed to
+    you. \`--building\` is for a HUMAN making one call against another target;
+    an agent switches with \`beehaven connect <address>\` instead.
+
+    Aliases: where`,
+        examples: [
+            { cmd: 'beehaven pwd' },
+            { cmd: `beehaven call project-list '{}'`, note: 'the hint line, without --building' },
+            { cmd: 'beehaven workspaces', note: 'what else could I connect to' },
+        ],
+        related: ['cd', 'status', 'actions', 'workspaces'],
+    },
+    canvas: {
+        synopsis: 'beehaven canvas <open|invoke|query|actions|help|record> [args]',
+        description: `Interact with the FAB canvas (notes editor) from the CLI.
+
+    Subcommands:
+      open <noteId>          Open a note in the canvas editor
+      invoke <action> [json] Call an editor-client action (local UI ops)
+      query <action>         Read editor-client state
+      actions / list          List editor-client UI actions (LOCAL — what the
+                             canvas UI can do)
+      help [domain]          Show the workspace RPC catalog (CLOUD — what
+                             agents can call). Different surface from actions.
+      help --search <q>      Keyword search the workspace RPC catalog
+      record start [sessionId] / stop   Record canvas interactions
+
+    Note: 'canvas actions' lists EDITOR-CLIENT UI actions (local). 'canvas
+    help' lists WORKSPACE RPC actions (cloud, agent-callable). They're
+    different surfaces — both names exist intentionally.`,
+        flags: [
+            { name: '--note <noteId>', desc: 'Stamp noteId on the envelope' },
+            { name: '--search <q>', desc: '(help) keyword search the catalog' },
+            { name: '--compact', desc: '(help) condensed markdown output' },
+            { name: '--json', desc: 'Output raw JSON' },
+        ],
+        examples: [
+            { cmd: 'beehaven canvas open note-abc123' },
+            { cmd: 'beehaven canvas actions', note: 'editor UI actions (local)' },
+            { cmd: 'beehaven canvas help', note: 'workspace RPC catalog (cloud)' },
+            { cmd: 'beehaven canvas help --search "image"', note: 'find image-related RPCs' },
+            { cmd: 'beehaven canvas invoke insert-block \'{"type":"text","text":"hi"}\'' },
+        ],
+        related: ['conversations', 'call', 'actions'],
+    },
+    conversations: {
+        synopsis: 'beehaven conversations [list | resume | export <sessionId>]',
+        description: `List, resume, or export Clearly FAB conversations.
+
+    Wraps the workspace's conversation-list / conversation-export RPCs.
+    Pairs with the FAB conversation switcher (#51): the GUI picker and
+    the CLI list show the same sessions.`,
+        flags: [
+            { name: '--limit <N>', desc: 'Max rows (default 20, max 100)' },
+            { name: '--composition <id>', desc: 'Filter to one canvas' },
+            { name: '--out <path>', desc: 'Export destination (export only)' },
+            { name: '--stdout', desc: 'Write export to stdout (export only)' },
+            { name: '--json', desc: 'Raw JSON output' },
+        ],
+        examples: [
+            { cmd: 'beehaven conversations', note: 'list 20 most recent' },
+            { cmd: 'beehaven conversations --composition abc123' },
+            { cmd: 'beehaven conversations resume', note: 'print top sessionId for shell pipelines' },
+            { cmd: 'beehaven conversations export composition:abc --out thread.md' },
+            { cmd: 'beehaven conversations export $(beehaven conversations resume) --stdout' },
+        ],
+        related: ['canvas', 'actions'],
+    },
+    composition: {
+        synopsis: 'beehaven composition <bind|unbind|list> [args]',
+        description: `Bind a Clearly composition (canvas board) to a local repo, so a
+    daemon-spawned coding agent runs in the real codebase — and shares a
+    Claude Code project 1:1 with that repo (its cwd → ~/.claude/projects/<encoded-cwd>).
+
+    Subcommands:
+      bind <compositionId> <repoPath>   Bind a board to a local repo
+      unbind <compositionId>            Remove the binding (back to scratch dir)
+      list                              Show all board→repo bindings
+
+    The binding lives in ~/.clearly/composition-repos.json and is read fresh
+    by the daemon on the next Claude-model run for that board — no daemon
+    restart needed. A stale binding (repo moved/deleted) falls back to the
+    per-composition scratch dir ~/.clearly/compositions/<id>/.
+
+    Alias: comp`,
+        flags: [{ name: '--json', desc: 'Machine-readable output' }],
+        examples: [
+            {
+                cmd: 'beehaven composition bind 70f779d1-… ~/projects/motion_studio',
+                note: 'board → repo',
+            },
+            { cmd: 'beehaven composition list' },
+            { cmd: 'beehaven composition unbind 70f779d1-…' },
+        ],
+        related: ['conversations', 'canvas', 'agent'],
+    },
+    disconnect: {
+        synopsis: 'beehaven disconnect',
+        description: `Clear the active target. Subsequent commands route to home.
+    Same effect as \`beehaven cd home\`.`,
+        examples: [{ cmd: 'beehaven disconnect' }],
+        related: ['cd', 'pwd'],
+    },
+    actions: {
+        synopsis: 'beehaven actions [--category <cat>] [--search <substr>] [--format <fmt>] [--json]',
+        description: `List callable RPCs on the current target.
+
+    On stale routing (you're on a target that doesn't expose list-actions),
+    transparently retries against home. See the dim "retrying against home"
+    line in stderr.`,
+        flags: [
+            {
+                name: '--category <cat>',
+                desc: 'Filter by action category (e.g. notes, projects, shopify)',
+            },
+            { name: '--search <substr>', desc: 'Substring match on action name or description' },
+            { name: '--format <fmt>', desc: 'summary (default), full, or tool-use (LLM-friendly JSON)' },
+            { name: '--json', desc: 'Raw JSON output; skips breadcrumb + formatting' },
+            { name: '--building <type>:<id>', desc: 'Explicit target (overrides active session)' },
+        ],
+        examples: [
+            { cmd: 'beehaven actions' },
+            { cmd: 'beehaven actions --category shopify' },
+            { cmd: 'beehaven actions --format tool-use', note: 'raw JSON with Zod-like schemas' },
+        ],
+        related: ['call', 'pwd', 'workspace'],
+    },
+    call: {
+        synopsis: 'beehaven call <action> [json-input] [--building <type>:<id>] [--json]',
+        description: `Invoke an RPC on the current target. Input is a JSON string.
+    Schema comes from the action's manifest — use \`beehaven actions\` first
+    to see what's available, or \`beehaven explain <action>\` for the exact
+    input shape + examples.
+
+    Emits a routing breadcrumb "→ <target> <action>" to stderr on success/failure.`,
+        flags: [
+            { name: '--building <type>:<id>', desc: 'Explicit target (e.g. shopifyStore:clearly-demo)' },
+            { name: '--json', desc: 'Suppress breadcrumb + hint blocks; raw stdout only' },
+            { name: '--timeout <ms>', desc: 'Override the 30s default' },
+        ],
+        examples: [
+            { cmd: 'beehaven call note-create \'{"title":"Hello"}\'' },
+            { cmd: "beehaven call project-list '{}' --building home" },
+            {
+                cmd: 'beehaven call admin-agent-chat \'{"conversationId":"c1","message":"top sellers?","scope":"read"}\'',
+                note: 'Shopify admin agent chat',
+            },
+        ],
+        related: ['actions', 'explain', 'pwd', 'workspace'],
+    },
+    doc: {
+        synopsis: 'beehaven doc add <file> [--project <id>] [--title <t>] [--json]',
+        description: `Add a local file to the workspace as a searchable DOCUMENT.
+    Reads the file, mints a note (note-create) + seeds its body
+    (note-content-seed) — the content lands in the workspace SQLite
+    note-content table + FTS5 index, so \`search-notes\` and the cloud agent
+    can retrieve it.
+
+    Markdown/text is stored verbatim; code files (.ts/.py/.go/…) are wrapped in
+    a fenced block (with the language) so they render and stay full-text
+    searchable. Title defaults to the markdown H1 or the filename. The
+    single-document guideline is ~1MB — for whole folders or large files,
+    prefer the doc-indexer (chunked, agent memory) or \`teleport\` (raw R2 blob).`,
+        flags: [
+            { name: '--project <id>', desc: 'Attach the document to a project' },
+            { name: '--title <t>', desc: 'Override the inferred title' },
+            { name: '--json', desc: 'Machine-readable output (noteId, title, bytes)' },
+        ],
+        examples: [
+            { cmd: 'beehaven doc add ./seo_perf/PLAN.md --project 9834a399-...' },
+            {
+                cmd: 'beehaven doc add ./lib/pricing/tiers.ts --project 9834a399-...',
+                note: 'code → fenced + FTS-indexed',
+            },
+        ],
+        related: ['teleport', 'search', 'call', 'recall'],
+    },
+    explain: {
+        synopsis: 'beehaven explain <action> [--json]',
+        description: `Show input schema + example invocations for one action.
+    Use this BEFORE \`beehaven call\` when you're not sure what JSON payload
+    the action expects.
+
+    Falls back through: \`describe-action\` (home) → \`list-actions --format=full\`
+    → raw manifest at /.workspace.json. At least one of these works on every
+    DO with a manifest.`,
+        flags: [
+            { name: '--json', desc: 'Print the raw manifest object' },
+            { name: '--building <type>:<id>', desc: 'Explicit target' },
+        ],
+        examples: [
+            { cmd: 'beehaven explain note-create' },
+            { cmd: 'beehaven explain shop:create-draft-order' },
+            {
+                cmd: 'beehaven explain project-create --json',
+                note: 'pipe to jq / consume programmatically',
+            },
+        ],
+        related: ['actions', 'call'],
+    },
+    /**
+     * ⚠⚠ THE SHELL VERBS ADDRESS TWO FILESYSTEMS, AND THE DEFAULT ONE IS `~`.
+     *
+     * Every page below used to document the RAW VFS only (`/folders/<collection>/<uuid>.json`),
+     * which is the namespace these verbs answered from BEFORE they were repointed at the notes
+     * shell. Measured 2026-09-05: 4 of 4 shell pages had examples that failed on a default daemon
+     * with "RPC 'shell:exec' requires developer scope" — 0 of them mentioned `~` even once.
+     *
+     * The runtime error handler already knew better than the help did: when a raw-VFS example
+     * fails it prints "beehaven ls ~ # the notes workspace (no extra scope)". A help page that
+     * contradicts the CLI's own error message is worse than no page.
+     *
+     * The rule for anything added here: `~` FIRST, because it is what the top-level help leads
+     * with, what the product uses, and what needs no extra scope. The raw VFS is documented as
+     * the second namespace, with its scope requirement stated rather than discovered.
+     */
+    ls: {
+        synopsis: 'beehaven ls [path]',
+        description: `List a directory. Two namespaces answer, and the breadcrumb on
+    stderr says which — a "(notes)" suffix means the notes shell replied.
+
+    ~  THE WORKSPACE (default, no extra scope)
+       Folders are PROJECTS, documents are .md files named "<KEY> <Title>.md".
+         beehaven ls ~                 every project + unfiled document
+         beehaven ls '~/Q1'            inside one project
+       ⚠ Quote any path with a space — a document filename usually has one.
+       ⚠ Folders NEST (since 2026-09-05) — \`ls '~/A/B'\` is a real path. Before
+         that, mkdir flattened, so older notes describing a flat workspace are stale.
+
+    /  THE RAW VFS (needs developer scope)
+       Data rows as files — /folders/<collection>/, /apps/, /proc/, /etc/, /var/,
+       /.workspace.json. Every path here goes through shell:exec, so a default
+       daemon refuses it with "requires developer scope"; start it as
+       HIVE_DEV_MODE=1 beehaven start --headless to reach it.`,
+        examples: [
+            { cmd: 'beehaven ls ~', note: 'projects + unfiled documents' },
+            { cmd: "beehaven ls '~/Q1'", note: 'inside one project — quote the path' },
+            { cmd: 'beehaven ls /', note: 'the raw VFS — developer scope only' },
+        ],
+        related: ['cat', 'tree', 'grep', 'find', 'workspace'],
+    },
+    cat: {
+        synopsis: 'beehaven cat <path>',
+        description: `Read a document. Works on anything ls shows.
+
+    Three spellings resolve, and they do NOT behave alike:
+
+      beehaven cat '~/CH-1.md'                          the KEY — from ANYWHERE
+      beehaven cat '~/CRUD Hunt/CH-1 CRUD Hunt Report.md'  the full name ls prints
+      beehaven cat '~/CRUD Hunt/CRUD Hunt Report.md'       the title alone
+
+    ⚠⚠ THE KEY IGNORES THE FOLDER; THE OTHER TWO DO NOT. A key names exactly one
+    document in the whole workspace, so \`cat '~/CH-1.md'\` works even though CH-1
+    is filed under "CRUD Hunt". Give the NAME or TITLE with the wrong folder and
+    you get "No such file or directory" for a document that is really there —
+    which reads as missing rather than as mis-addressed. When in doubt use the key.
+
+    ⚠ Two documents may share a title, and then the title form is refused as
+    ambiguous. A key never is.
+
+    A raw-VFS path (/folders/…, /.workspace.json) also works but needs developer
+    scope — see \`beehaven help ls\`.`,
+        examples: [
+            { cmd: "beehaven cat '~/CH-1.md'", note: 'by key — resolves from anywhere' },
+            { cmd: "beehaven cat '~/CRUD Hunt/CH-1 CRUD Hunt Report.md'", note: 'the name ls prints' },
+            { cmd: "beehaven cat '~/Q1/Board.board.json'", note: 'a board, with its cards' },
+        ],
+        related: ['ls', 'tree', 'grep', 'head', 'search'],
+    },
+    grep: {
+        synopsis: 'beehaven grep [flags] <pattern> <path>',
+        description: `Search document BODIES for a pattern. A directory target
+    auto-recurses (no -r needed).
+
+    Takes the usual flags: -i (ignore case), -l (names only), -r, and they
+    combine — \`grep -ril pricing ~\` is the everyday call.
+
+    ⚠ grep MATCHES SUBSTRINGS; \`search\` RANKS. Reach for grep when you know the
+    literal string (an identifier, a URL, an error message) and for \`search\` when
+    you know the idea — it is BM25 over the same bodies and it stems, so it finds
+    "crediting" from "credits" where grep cannot.
+
+    On the raw VFS (/compositions/, developer scope) it pushes the search into each
+    composition's blocks, decompressing the canvas blob, so it finds text \`sql\`
+    cannot — that column is gzip-compressed.`,
+        examples: [
+            { cmd: 'beehaven grep -ril pricing ~', note: 'which documents mention it' },
+            { cmd: "beehaven grep TODO '~/Q1'", note: 'scoped to one project' },
+            { cmd: 'beehaven grep checkout /compositions/', note: 'raw VFS — developer scope only' },
+        ],
+        related: ['search', 'ls', 'cat', 'find', 'sql'],
+    },
+    tree: {
+        synopsis: 'beehaven tree [path]',
+        description: `Recursive view under a path. On \`~\` this is the fastest way to
+    see the whole workspace at once: every project, and what is filed in each.
+
+    ⚠ It prints the WHOLE tree — on a workspace with hundreds of documents, pipe it
+    (\`| head -40\`) or point it at one project.
+
+    A raw-VFS path needs developer scope — see \`beehaven help ls\`.`,
+        examples: [
+            { cmd: 'beehaven tree ~', note: 'the whole workspace' },
+            { cmd: "beehaven tree '~/Q1'", note: 'one project' },
+            { cmd: 'beehaven tree /', note: 'raw VFS — developer scope only' },
+        ],
+        related: ['ls', 'cat', 'find'],
+    },
+    write: {
+        synopsis: 'beehaven write <path> <content>',
+        description: `Create or overwrite a document. Content is ONE argument — quote it.
+
+    ⚠⚠ THE BASENAME YOU TYPE IS THE NAME (fixed 2026-09-05, CBH2-8).
+      beehaven write '~/HelpProbe/probe-write.md' '# Written Title'
+      → wrote ~/HelpProbe/HEL-1 probe-write.md
+    It used to DISCARD the basename and name the note from line one of the
+    content, so \`cat\` of the path you had just written answered "no such file".
+    The heading in the body is now just a heading.
+
+    ⚠ THE FILENAME STILL LEADS WITH A KEY (\`HEL-1\`), which is minted at create
+    time and cannot be known in advance — so the path it echoes is still the one
+    to trust. Both \`~/HelpProbe/probe-write.md\` and \`~/HEL-1.md\` resolve.
+
+    ⚠ TWO PATHS NAME NOTHING, and for those line one is still the title: a bare
+    key (\`~/CLR-42.md\` — that is an address, not a name) and an empty basename.
+
+    ⚠⚠ FOR A MULTI-LINE BODY USE $'...', NOT '...\\n...'. A plain single-quoted
+    string passes the backslash-n through literally, so the body arrives as one
+    line containing "-n-n". No error, just a document that reads as garbage.
+    $'…' is bash/zsh ANSI-C quoting and interprets the \\n.
+
+    ⚠ It OVERWRITES the whole body. To change one passage use \`edit\`, which
+    leaves the rest alone and cannot lose what you did not retype.
+
+    On a raw-VFS /compositions block file (developer scope) the JSON is spliced
+    into the canvas blob, so the edit shows on the user's canvas. Single quotes
+    inside the content are not supported there — use \`call composition-patch\`.`,
+        examples: [
+            {
+                cmd: `beehaven write '~/Q1/notes.md' $'# Kickoff notes\\n\\nfirst line'`,
+                note: 'names it "notes" — the basename wins; the heading is just a heading',
+            },
+            {
+                cmd: `beehaven write /compositions/<id>/blocks/<bid>.json '{"id":"<bid>","type":"text","data":{"type":"text","text":"hi"}}'`,
+                note: 'raw VFS — developer scope only',
+            },
+        ],
+        related: ['cat', 'edit', 'rm', 'ls'],
+    },
+    edit: {
+        synopsis: 'beehaven edit <path> <old> <new>',
+        description: `Find/replace inside a document: read → replace every <old> with
+    <new> → write back. Reports "edited <path>" naming what it touched.
+
+    ⚠ PREFER THIS OVER \`write\` FOR AN EXISTING DOCUMENT. \`write\` replaces the
+    whole body, so anything you do not retype is gone with no error; \`edit\`
+    changes the passage and leaves the rest untouched.
+
+    ⚠ It replaces EVERY occurrence, not the first. If <old> appears more than once
+    and you meant one of them, make the string long enough to be unique.
+
+    ⚠ A <old> that is not in the body is REFUSED ("find text not present"), never
+    silently applied — so a failed edit costs you nothing. Re-read with \`cat\`
+    and retry with the passage as it now reads.
+
+    On a raw-VFS /compositions block (developer scope) this updates the canvas.`,
+        examples: [
+            { cmd: `beehaven edit '~/HEL-3.md' 'first line' 'second line'`, note: 'by key' },
+            { cmd: `beehaven edit '~/Q1/Kickoff notes.md' 'TODO' 'DONE'` },
+        ],
+        related: ['cat', 'write', 'grep', 'rm'],
+    },
+    rm: {
+        synopsis: 'beehaven rm <path>',
+        description: `Remove a document from the workspace listing.
+
+    ⚠⚠ IT ARCHIVES, IT DOES NOT DESTROY — and the KEY KEEPS RESOLVING. The row is
+    flagged archived and drops out of \`ls\`, but \`cat '~/HEL-1.md'\` still
+    returns the body afterwards. So this is "put it in the trash", not "shred it".
+    Treat a successful rm as reversible, and never as proof something is gone.
+
+    ⚠⚠ THE UNDO IS \`document-archive\`, NOT \`document-restore\`. This page said
+    \`document-restore\` and that is a DIFFERENT verb: it restores an earlier
+    VERSION of a document's body and answers \`versionId is required\`, so
+    following the old advice got you an error about a field you were never told
+    about, on a document that was never rolled back. Un-archive with:
+
+      call document-archive '{"id":"HEL-1","archived":false}'
+
+    ⚠ A FOLDER'S UNDO IS A DIFFERENT SHAPE AGAIN. \`rm -r <folder>\` routes to
+    \`project-delete\`, and a project is un-archived through its updates bag with
+    \`is_archived\` — the underscored column name, not \`archived\`:
+
+      call project-update '{"id":"<folder-id>","updates":{"is_archived":false}}'
+
+    You do not have to remember either: rm PRINTS the exact call for what it just
+    archived, with the id already filled in. Read the line it prints — it also
+    reports what it did ("moved to Trash …"), so older notes telling you to
+    confirm with \`ls\` describe a CLI that no longer exists.
+
+    On a raw-VFS /compositions block (developer scope) it removes the block from
+    the canvas. The sibling mutation verbs \`mv\`, \`cp\` and \`mkdir\` pass through
+    to the same shell.`,
+        examples: [
+            { cmd: `beehaven rm '~/HelpProbe/HEL-1 Written Title.md'`, note: 'prints the undo call' },
+            { cmd: `beehaven restore HEL-1`, note: 'undo — the verb form' },
+            { cmd: `beehaven call document-archive '{"id":"HEL-1","archived":false}'`, note: 'undo — the raw call' },
+        ],
+        related: ['ls', 'write', 'edit', 'mv', 'trash', 'restore'],
+    },
+    /**
+     * ⚠⚠ THESE TWO EXIST BECAUSE `rm` HAD NO WAY BACK FROM THE EVERYDAY SURFACE (CBH2-34).
+     *
+     * `rm` archives rather than destroys and its page has said so for a while — but the only undo it
+     * could offer was a raw `beehaven call document-archive '{"archived":false}'`, and the ticket's
+     * own reproduction was `beehaven help | grep -iE 'restore|trash|undelete|unarchive'` returning
+     * NOTHING. A reversible delete whose reversal is undiscoverable is, for anyone who does not read
+     * the worker, an irreversible one.
+     *
+     * ⚠ Adding the pages is what puts the verbs in the top-level grid — it is `Object.keys(PAGES)`.
+     * So a page here is not documentation ABOUT the verb; it is how the verb becomes findable.
+     */
+    trash: {
+        synopsis: 'beehaven trash',
+        description: `Documents \`rm\` put away. It archives rather than destroys, so this is the
+    list of things you can still get back.
+
+    ⚠ THE COUNT IS A PAGE, NOT A TOTAL. It says so when the page is full; raise it
+    with \`--limit\` (max 500). A list that stops at its own default and looks
+    complete is the failure this workspace keeps finding.
+
+    Nothing is destroyed by archiving and nothing here expires. Put one back with
+    \`beehaven restore <key>\`.`,
+        examples: [
+            { cmd: 'beehaven trash' },
+            { cmd: 'beehaven trash --limit 200', note: 'more than the default page' },
+        ],
+        related: ['rm', 'restore', 'ls'],
+    },
+    restore: {
+        synopsis: 'beehaven restore <key|title|id>',
+        description: `Un-archive a document and return it to \`ls\`.
+
+    Takes the same references everything else does — the KEY is the one to use
+    (\`beehaven trash\` prints it), because two documents may share a title.
+
+    ⚠ IT REPORTS A NO-OP AS A NO-OP. Restoring something that was never archived
+    answers "was not archived — nothing to do" rather than "restored". Claiming
+    work that did not happen is the defect class this whole sprint was about.
+
+    ⚠ THIS IS NOT \`document-restore\`. That verb rolls a document's BODY back to
+    an earlier VERSION and needs a \`versionId\`. This one only flips the archived
+    flag, and leaves the body exactly as it was.
+
+    ⚠ A FOLDER IS A DIFFERENT SHAPE. \`rm -r <folder>\` routes to \`project-delete\`;
+    un-archive it through its updates bag with the underscored column name:
+
+      call project-update '{"id":"<folder-id>","updates":{"is_archived":false}}'`,
+        examples: [
+            { cmd: 'beehaven restore HEL-1' },
+            { cmd: 'beehaven trash', note: 'see the keys first' },
+        ],
+        related: ['trash', 'rm', 'ls'],
+    },
+    /**
+     * ⚠⚠ THE ORGANISE VERBS — `mkdir`, `mv`, `cp`. All three shipped in the top-level help under a
+     * heading called "Organise", were named BY `help rm`, and had no page of their own: the CLI told
+     * you they existed, told you to run `beehaven help <command>` before anything unfamiliar, and
+     * then had nothing to show.
+     *
+     * ⚠ They are also the three that most need a page, because ALL THREE PRINT NOTHING ON SUCCESS —
+     * so their failure mode and their success mode are byte-identical on screen. Every page below
+     * says what silence means and how to confirm.
+     */
+    mkdir: {
+        synopsis: 'beehaven mkdir [-p] <path>',
+        description: `Create a project. A folder in \`~\` IS a project — there is no
+    separate "make a project" step.
+
+    ⚠⚠ NESTING IS REAL NOW (fixed 2026-09-05, CBH2-7). \`mkdir '~/A/B'\` creates
+    B INSIDE A. It used to FLATTEN — creating a root project called "B" beside A
+    — and then echo back \`~/A/B\`, a path that would never resolve.
+
+    ⚠ WITHOUT -p A MISSING INTERMEDIATE IS REFUSED, as in any shell. \`mkdir
+    '~/A/B/C'\` when A/B does not exist answers "No such file or directory" and
+    creates nothing; \`mkdir -p '~/A/B/C'\` creates the whole chain. -p used to
+    be accepted and ignored.
+
+    ⚠ An existing folder is still SUCCESS, not a collision (find-or-create), so
+    re-running is safe. A bare name (\`mkdir '~/Prepress'\`) still matches a
+    folder of that name ANYWHERE in the tree rather than minting a second one.
+
+    ⚠ It prints the path it actually created — read that, because a name that
+    collides with a sibling is suffixed with a short id.
+
+    A new project is not empty: it arrives with a \`clearly.md\` and its own
+    \`<Name> board.board.json\`.`,
+        examples: [
+            { cmd: "beehaven mkdir '~/Q2 Planning'", note: 'creates the project' },
+            { cmd: "beehaven mkdir -p '~/Q2 Planning/Research/Interviews'", note: 'creates the whole chain' },
+            { cmd: "beehaven ls '~/Q2 Planning'", note: 'confirm the nesting landed' },
+        ],
+        related: ['ls', 'mv', 'cp', 'tree'],
+    },
+    mv: {
+        synopsis: 'beehaven mv <src> <dest>',
+        description: `Move a document into a project, or rename it. Two jobs, told
+    apart by whether <dest> is a folder or a filename.
+
+      beehaven mv '~/PLA-3584.md' '~/HelpProbe'
+        → files it under HelpProbe
+      beehaven mv '~/HelpProbe/PLA-3584 Old.md' '~/HelpProbe/PLA-3584 New.md'
+        → renames it to "New"
+
+    ⚠ THE KEY IS NOT PART OF THE NAME YOU ARE SETTING. Renaming to
+    "PLA-3584 New.md" sets the title to "New", not "PLA-3584 New" — the key prefix
+    is stripped. Leave it on: a bare key as the destination is refused outright,
+    because a caller never chooses a key.
+
+    ⚠ A MOVE DOES NOT RE-KEY. The prefix records where a document was BORN, not
+    where it lives now, so a document moved into another project keeps its
+    original prefix. That is deliberate — a key that came back pointing at
+    different work would turn every past mention of it into a quiet lie.
+
+    It reports the move ("id … · movedTo HP2"). ⚠ It used to print nothing, so
+    older notes describing a silent \`mv\` are stale.`,
+        examples: [
+            { cmd: "beehaven mv '~/PLA-3584.md' '~/HelpProbe'", note: 'file it into a project' },
+            {
+                cmd: "beehaven mv '~/HelpProbe/PLA-3584 Old.md' '~/HelpProbe/PLA-3584 New.md'",
+                note: 'rename — the title becomes "New"',
+            },
+            { cmd: "beehaven ls '~/HelpProbe'", note: 'mv is silent — this is how you confirm' },
+        ],
+        related: ['ls', 'cp', 'mkdir', 'rm'],
+    },
+    cp: {
+        synopsis: 'beehaven cp <src> <dest>   ·   beehaven cp -r <folder> <dest>',
+        description: `Copy a document into a project.
+
+    ⚠⚠ THE COPY GETS A NEW KEY, DERIVED FROM WHERE IT LANDS. Measured: copying
+    "PLA-3790 HP2 Doc.md" into ~/Q1 reported
+    \`key Q1-4 · copiedTo ~/Q1 · title HP2 Doc (copy)\` — a NEW key taking the
+    destination's prefix, and "(copy)" appended to the title. So the copy is a
+    genuinely separate document with its own address; anything that referenced the
+    old key still means the ORIGINAL. Read the reported key rather than guessing it.
+
+    ⚠⚠ \`cp -r\` ON A FOLDER REPORTS A DESTINATION IT DID NOT CREATE — VERIFIED
+    2026-09-05. \`cp -r '~/HP2' '~/HP2Copy'\` prints
+    \`copiedFolder {"from":"~/HP2","to":"~/HP2Copy"}\` and then
+    \`ls '~/HP2Copy'\` answers "No such file or directory", because the project it
+    actually made is called **"HP2 (copy)"**. The copy is real; only the name in
+    the report is wrong. **Do not trust the \`to\` field — \`ls ~\` and use the
+    name you find.** To choose the name, use the RPC, which honours \`title\`:
+        beehaven call project-copy '{"projectId":"<id>","title":"Q2 Planning"}'
+
+    Both forms report what they did. ⚠ They used to print nothing, so older notes
+    describing a silent \`cp\` are stale.`,
+        examples: [
+            {
+                cmd: "beehaven cp '~/HP2/PLA-3790 HP2 Doc.md' '~/Q1'",
+                note: 'reports the NEW key it minted',
+            },
+            { cmd: 'beehaven ls ~', note: "after cp -r — the report's name is not the real one" },
+            {
+                cmd: `beehaven call project-copy '{"projectId":"<id>","title":"Q2 Planning"}'`,
+                note: 'copy a whole project with the title honoured',
+            },
+        ],
+        related: ['mv', 'ls', 'mkdir', 'call'],
+    },
+    /**
+     * ⚠ THE THREE READ VERBS — `head`, `tail`, `wc`. Documented in the top-level help as
+     * "beehaven head|tail|wc <path>  The usual three" and undocumented anywhere deeper. They are
+     * what an agent reaches for immediately after `ls` and `cat`, on exactly the documents too long
+     * to `cat` whole.
+     */
+    head: {
+        synopsis: 'beehaven head [-n <lines>] <path>',
+        description: `First lines of a document. Defaults to 10.
+
+    This is the cheap way to identify a long document without pulling the whole
+    body through your context — and \`~\` documents lead with their heading, so
+    \`head -n 3\` is usually enough to know what one is.
+
+    Addressing is the same as \`cat\`: the KEY resolves from anywhere, a name or
+    title needs the right folder.`,
+        examples: [
+            { cmd: "beehaven head -n 3 '~/CH-1.md'" },
+            { cmd: "beehaven head '~/CRUD Hunt/CH-1 CRUD Hunt Report.md'" },
+        ],
+        related: ['tail', 'wc', 'cat', 'ls'],
+    },
+    tail: {
+        synopsis: 'beehaven tail [-n <lines>] <path>',
+        description: `Last lines of a document. Defaults to 10.
+
+    Useful on the documents that GROW — a running log, a report an agent keeps
+    appending to with \`document-append\` — where the newest material is at the
+    bottom and \`head\` shows you the oldest.
+
+    Addressing is the same as \`cat\`.`,
+        examples: [
+            { cmd: "beehaven tail -n 2 '~/CH-1.md'" },
+            { cmd: "beehaven tail '~/Q1/Kickoff notes.md'" },
+        ],
+        related: ['head', 'wc', 'cat'],
+    },
+    wc: {
+        synopsis: 'beehaven wc <path>',
+        description: `Lines, words and characters — the three, in that order.
+
+      $ beehaven wc '~/CH-1.md'
+            6      18     101 /home/CH-1.md
+
+    Reach for it before reading something you are not sure you can afford, and to
+    check an append landed. For a richer answer on a document — headings, reading
+    time, what it contains — \`call document-stats\` is the workspace's own version.`,
+        examples: [
+            { cmd: "beehaven wc '~/CH-1.md'" },
+            { cmd: `beehaven call document-stats '{"id":"CH-1"}'`, note: 'the richer version' },
+        ],
+        related: ['head', 'tail', 'cat', 'call'],
+    },
+    jq: {
+        synopsis: 'beehaven jq <filter> <path>',
+        description: `Run a jq filter over a JSON file in the workspace. The workspace
+    is full of them: \`<Board>.board.json\`, \`<name>.scene.json\`, and anything
+    under the raw VFS.
+
+    ⚠ It needs REAL JSON. Pointed at a markdown document it answers
+    "jq: invalid JSON" — which is a type error, not a missing file.`,
+        examples: [
+            { cmd: `beehaven jq '.title' '~/Q1/Board.board.json'` },
+            { cmd: `beehaven jq '.' '~/Q1/Board.board.json'`, note: 'pretty-print the whole thing' },
+        ],
+        related: ['cat', 'sql', 'ls'],
+    },
+    /**
+     * ⚠⚠ `find` IS NOT AN ALIAS OF `search`, THOUGH `help` CLAIMED IT WAS.
+     *
+     * The ALIASES table carried `find: 'search'`, so `beehaven help find` rendered the SEARCH page
+     * while dispatch sent the word to the shell's POSIX find. `find HunterProbe` answered
+     * "No such file or directory" — which reads as "that note does not exist", not "you used the
+     * wrong verb". A silent false negative produced by the CLI's own documented alias.
+     *
+     * ⚠ THE ALIAS WAS REMOVED RATHER THAN HONOURED, DELIBERATELY. Making `find` mean `search` would
+     * have deleted a working, useful capability: POSIX find matches on NAME and PATH
+     * (`find ~ -name '*.board.json'` enumerates every board in the workspace), where `search` is
+     * BM25 over CONTENT. They answer different questions, so one cannot be the other's alias — and
+     * this CLI has a public installer, so silently changing what a working verb does has a real
+     * cost. The bug was the documentation claiming a synonym; the fix is to document the difference
+     * and signpost the other verb by name.
+     */
+    find: {
+        synopsis: 'beehaven find <path> [-name <glob>]',
+        description: `POSIX find over the workspace — matches on NAME and PATH.
+
+    ⚠⚠ THIS IS NOT \`search\`, AND ITS FAILURE LOOKS LIKE AN EMPTY WORKSPACE.
+    \`beehaven find HunterProbe\` treats the word as a PATH and answers
+    "find: /home/HunterProbe: No such file or directory" — which reads as "no such
+    note". It is not: it is the wrong verb. To search CONTENT use \`search\`
+    (ranked, BM25, stems) or \`grep\` (literal substring).
+
+      find    → what is this thing CALLED / where does it live
+      grep    → which documents CONTAIN this exact string
+      search  → which documents are ABOUT this
+
+    ⚠ The first argument is a path, so it always starts with \`~\` or a folder.`,
+        examples: [
+            { cmd: "beehaven find '~/Q1'", note: 'everything under one project' },
+            { cmd: `beehaven find ~ -name '*.board.json'`, note: 'every board in the workspace' },
+            { cmd: 'beehaven search "revenue attribution"', note: 'searching CONTENT is a different verb' },
+        ],
+        related: ['search', 'grep', 'ls', 'tree'],
+    },
+    // `claude` was a documented verb with no page — the exact gap this file's
+    // test exists to catch, surfaced when `omni` tried to link to it.
+    claude: {
+        synopsis: 'beehaven claude "<task>"  ·  beehaven claude login | status | logout',
+        description: `ONE local Claude Code turn, on YOUR own subscription, in THIS process.
+
+    Runs the Claude Agent SDK's \`query()\` in the CLI itself, authenticated by the
+    OAuth credential \`beehaven claude login\` writes (a \`claude setup-token\` browser
+    flow). Nothing syncs a token to the cloud and nothing remote can drive it —
+    cloud→daemon Claude orchestration is disabled for Anthropic credential-use
+    compliance.
+
+    It is a one-shot: the session lives and dies with the command, carries no
+    beehaven tools, and nothing else on the machine can see it. When you want the
+    shared, daemon-hosted session with the beehaven surface mounted — the one the
+    avatar's chat panel also talks to — use \`beehaven omni\`.
+
+    --composition runs the turn in a per-composition workspace
+    (~/.clearly/compositions/<id>, with a seeded CLAUDE.md) so Claude opens
+    knowing where it is.`,
+        flags: [
+            { name: '--composition <id>', desc: 'Run in that composition\'s workspace dir.' },
+            { name: '--cwd <dir>', desc: 'Working directory for the turn.' },
+            { name: '--model <m>', desc: 'Model for this turn.' },
+            { name: '--continue / --resume <sid>', desc: 'Pick up the previous conversation at this cwd.' },
+        ],
+        examples: [
+            { cmd: 'beehaven claude login', note: 'authorize once (opens a browser)' },
+            { cmd: 'beehaven claude "refactor auth.ts"', note: 'one turn in the current directory' },
+            { cmd: 'beehaven claude status', note: 'which credential is active' },
+        ],
+        related: ['omni', 'treehouse'],
+    },
+    omni: {
+        synopsis: 'beehaven omni "<task>"  ·  beehaven omni sessions | end',
+        description: `DAEMON OMNI — Claude Code hosted in the daemon, with the beehaven
+    surface as first-party tools.
+
+    Same Claude Agent SDK runtime as \`beehaven claude\`, one important difference:
+    \`claude\` runs it in THIS process (one Claude per invocation, dying with the
+    command, no beehaven tools, invisible to anything else). \`omni\` drives the
+    session living in the DAEMON — the same one the avatar's chat panel talks to.
+    One warm session, one conversation, one set of tools, shared by every client.
+
+    That matters because the daemon is the only process holding the relay socket
+    and the local buildings, which is what lets the beehaven surface be ~32 real
+    in-process MCP tools (mcp__clearly__canvas_add_text, avatar_say,
+    composition_create, …) instead of Claude shelling out to \`beehaven call\`.
+
+    Everything else is Claude Code as you know it: the full built-in tool set,
+    your skills and slash commands, your MCP servers, subagents, session resume.
+
+    LOCAL ONLY. This rides the IPC socket (chmod 0600 — the kernel proving the
+    caller is you, driving your own subscription). Cloud→daemon Claude
+    orchestration stays disabled for Anthropic credential-use compliance; nothing
+    here opens that path.
+
+    A turn returns as soon as it is ACCEPTED — text, tool calls and the result
+    stream back as they happen, so a long coding turn prints as it works.
+
+    Every step renders INLINE: the tool name, each argument, then a ✓/✗ with a
+    preview of what came back. Omni's own working text streams in dim as it is
+    produced — that is its thinking, not its answer; the answer is the undimmed
+    prose. Use --quiet to keep only the answers.`,
+        flags: [
+            { name: '--session <id>', desc: 'Name the thread. Defaults to "default" — one shared conversation.' },
+            { name: '--cwd <dir>', desc: 'Where the turn runs. Defaults to the current directory.' },
+            { name: '--quiet, -q', desc: 'Replies only — drop the streamed working text and the step log. For scripts. Failed steps still print.' },
+        ],
+        examples: [
+            { cmd: 'beehaven omni "add a red rectangle to my canvas"', note: 'uses the first-party canvas tools' },
+            { cmd: 'beehaven omni --session build "run the tests and fix what fails"', note: 'a named thread' },
+            { cmd: 'beehaven omni -q "summarise the open tickets"', note: 'just the answer, for piping' },
+            { cmd: 'beehaven omni sessions', note: 'what is live, and whether the beehaven tools are mounted' },
+            { cmd: 'beehaven omni end --session build', note: 'end a thread' },
+        ],
+        related: ['claude', 'treehouse', 'status'],
+    },
+    treehouse: {
+        synopsis: 'beehaven treehouse <claude|codex|gemini|pi> "<message>"',
+        description: `Send ONE turn to a BYOK room in the Clearly desktop app and print its
+    reply. The rooms run the user's OWN coding agents (Claude Code / Codex CLI /
+    Gemini CLI / pi) on their own login — nothing bills Clearly's AI pool.
+
+    DEVELOPER MODE ONLY. A turn spends the user's own subscription and runs with
+    their ~/Clearly filesystem, so the desktop app mounts this route only when
+    developer mode is on; otherwise it 404s. Enable with HIVE_DEV_MODE=1 (or the
+    tray's Settings entry) and relaunch.
+
+    Talks to the desktop app over loopback HTTP (127.0.0.1:3456), authorised with
+    ~/.beehaven/browser-token — NOT the daemon, which holds no rooms. The app must
+    be running.
+
+    Synchronous: it waits for the whole turn (which can take minutes for a real
+    build) and returns the final text. --verbose also prints each tool call.`,
+        flags: [
+            { name: '--verbose', desc: 'print every tool call/result, not just the final text' },
+            { name: '--model <id>', desc: "the room's model (see `beehaven treehouse` in the app's settings for the catalog)" },
+            { name: '--session <id>', desc: 'continue a named thread instead of the default room session' },
+            { name: '--port <n>', desc: 'desktop RPC port (default 3456)' },
+        ],
+        examples: [
+            { cmd: 'beehaven treehouse gemini "design a landing page for a hair salon"', note: 'the agent drives the canvas itself via the beehaven CLI' },
+            { cmd: 'beehaven treehouse claude "what did you build?" --session design-1', note: 'continue a named thread' },
+            { cmd: 'beehaven treehouse pi "list your skills" --verbose', note: 'watch the tool calls' },
+        ],
+        related: ['call', 'actions', 'canvas'],
+    },
+    sql: {
+        synopsis: 'beehaven sql "<query>"',
+        description: `Run a SQL query against the target DO's SQLite tables — best for
+    STRUCTURE: filter/sort/join/count on columns (title, type, project_id, dates).
+    It CANNOT search composition content: the \`data\` blob is gzip-compressed, so
+    \`WHERE data LIKE '%term%'\` silently misses everything compressed. For content,
+    use \`grep\` (terminal) or the \`composition-search\` action (agent).
+    Tables + columns: \`beehaven workspace\`.`,
+        examples: [
+            { cmd: 'beehaven sql "SELECT COUNT(*) FROM notes"' },
+            {
+                cmd: 'beehaven sql "SELECT id, title FROM compositions ORDER BY updated_at DESC LIMIT 10"',
+            },
+        ],
+        related: ['workspace', 'grep', 'ls'],
+    },
+    d1: {
+        synopsis: 'beehaven d1 <list|exec|dump|migrate> [args]',
+        description: `Cloudflare D1 wrapper. Reads bindings from wrangler.toml/wrangler.jsonc
+    so you don't have to pass --database-id. Defaults to --remote; pass --local
+    to hit the wrangler emulator. Different layer from \`beehaven sql\` — that
+    runs against a DO's SQLite, this runs against the account's D1 databases.
+
+    Subcommands:
+      list                                 Show D1 bindings declared in wrangler config
+      exec <db> "<sql>" [--local] [--json] Execute SQL
+      dump <db> <table> [--out file]       Dump a table (JSON to stdout or file)
+      migrate <db> apply [--local]         Apply pending migrations
+      migrate <db> list                    List applied/pending migrations
+      migrate <db> create <name>           Create a new migration file`,
+        flags: [
+            { name: '--local', desc: 'Use local emulator instead of remote' },
+            { name: '--json', desc: 'Raw JSON output (exec)' },
+            { name: '--out <path>', desc: 'Write to file (dump)' },
+            { name: '--env <name>', desc: 'wrangler env (staging, etc.)' },
+        ],
+        examples: [
+            { cmd: 'beehaven d1 list', note: 'show all configured D1 dbs' },
+            { cmd: 'beehaven d1 exec lumen-index "SELECT * FROM referrals LIMIT 5"' },
+            { cmd: 'beehaven d1 exec lumen-index --local "SELECT 1"', note: 'hit local emulator' },
+            { cmd: 'beehaven d1 dump lumen-index users --out users.json' },
+            { cmd: 'beehaven d1 migrate lumen-index apply' },
+        ],
+        related: ['sql', 'workspace', 'status'],
+    },
+    secrets: {
+        synopsis: 'beehaven secrets <list|set|delete|diff|check> [NAME] [--env <name>|all]',
+        description: `Workers secrets wrapper. Defaults to operating on EVERY declared env
+    (the parity-enforcement the root project CLAUDE.md flags as a recurring bug
+    source — "when setting a secret on staging, ALWAYS set it on prod too").
+    Detects envs from \`[env.<name>]\` blocks in wrangler.toml.
+
+    Subcommands:
+      list [--env all|prod|...]      Show secret names per env (matrix view)
+      set <NAME> [--env all|...]     Prompt for value, set on all envs by default
+      delete <NAME> --yes            Delete on all envs (requires --yes)
+      diff                           Show secrets present on one env but not another
+      check                          Verify required secrets (from beehaven.json
+                                     "requiredSecrets") are set on every env`,
+        flags: [
+            { name: '--env <name>|all', desc: 'Target a specific env or all (default: all)' },
+            { name: '--yes', desc: 'Skip confirmation (delete only)' },
+            { name: '--json', desc: 'Raw JSON output (list)' },
+        ],
+        examples: [
+            { cmd: 'beehaven secrets list', note: 'matrix view across all envs' },
+            { cmd: 'beehaven secrets set GCP_SERVICE_ACCOUNT_JSON', note: 'sets on prod + staging' },
+            { cmd: 'beehaven secrets set FOO --env staging', note: 'one env only' },
+            { cmd: 'beehaven secrets diff', note: 'find parity gaps' },
+            { cmd: 'beehaven secrets check', note: 'verify against beehaven.json requiredSecrets' },
+        ],
+        related: ['d1', 'workspace', 'status'],
+    },
+    user: {
+        synopsis: 'beehaven user <userId> <inspect|dump|sql|export|wipe> [args]',
+        description: `Per-user admin sugar over the DO admin surface. Resolves the user's
+    DO class from --workspace, or \`userWorkspace\` in beehaven.json. Auth via
+    --url + --secret flags (or BEEHAVEN_WORKER_URL / BEEHAVEN_ADMIN_SECRET env).
+    Daemon-optional — works against any deployed worker.
+
+    Subcommands:
+      inspect                       Storage breakdown + per-table row counts
+      sql "<query>"                 Sugar over admin:sql for this user's DO
+      dump <folder> [--out file]    Dump one folder as JSON
+      export [--out file]           Dump all folders into one JSON file
+                                    (uses cfg.user.exportAction if defined)
+      wipe --yes                    Delete all data (uses cfg.user.wipeAction
+                                    if defined; otherwise DELETE per-table)
+
+    beehaven.json hints:
+      { "userWorkspace": "User" }
+      { "user": { "workspace": "User", "wipeAction": "delete-account",
+                  "exportAction": "export-account" } }`,
+        flags: [
+            { name: '--workspace <type>', desc: 'DO class for the user (default: from beehaven.json)' },
+            { name: '--url <url>', desc: 'Worker URL (default: BEEHAVEN_WORKER_URL env)' },
+            { name: '--secret <token>', desc: 'Admin bearer (default: BEEHAVEN_ADMIN_SECRET env)' },
+            { name: '--out <path>', desc: 'Write to file (dump/export)' },
+            { name: '--yes', desc: 'Skip confirm (wipe)' },
+            { name: '--json', desc: 'Raw JSON output (sql)' },
+        ],
+        examples: [
+            { cmd: 'beehaven user abc123 inspect' },
+            { cmd: 'beehaven user abc123 sql "SELECT * FROM readings LIMIT 5"' },
+            { cmd: 'beehaven user abc123 dump journal --out journal.json' },
+            { cmd: 'beehaven user abc123 export --out user-abc.json', note: 'GDPR export' },
+            { cmd: 'beehaven user abc123 wipe --yes', note: 'GDPR delete' },
+        ],
+        related: ['sql', 'workspace', 'd1'],
+    },
+    webhook: {
+        synopsis: 'beehaven webhook <list|show|replay|dlq> <type>/<id> [args]',
+        description: `Inspect + replay the outgoing webhook DLQ. Operates on the
+    \`_bh_webhooks\` table that the SDK's \`this.webhooks()\` writes into.
+    Different layer from incoming webhook receivers (those handle in your
+    app code; the SDK doesn't queue failed inbound deliveries).
+
+    Subcommands:
+      list <type>/<id> [--status dead|pending|delivered] [--limit N]
+      dlq <type>/<id>            Shortcut for list --status dead
+      show <type>/<id> <id>      Full row for one event (JSON)
+      replay <type>/<id> <id>    Re-arm: flips status to pending, resets attempts.
+                                 The next alarm tick drains it. For immediate drain,
+                                 expose a webhook-drain action on your workspace.
+
+    Auth: --url + --secret (or BEEHAVEN_WORKER_URL / BEEHAVEN_ADMIN_SECRET).`,
+        flags: [
+            { name: '--status <s>', desc: 'Filter: pending | dead | delivered' },
+            { name: '--limit <N>', desc: 'Max rows (default 50)' },
+            { name: '--url <url>', desc: 'Worker URL' },
+            { name: '--secret <token>', desc: 'Admin bearer' },
+            { name: '--json', desc: 'Raw JSON output' },
+        ],
+        examples: [
+            { cmd: 'beehaven webhook list User/abc123' },
+            { cmd: 'beehaven webhook dlq User/abc123', note: 'just the failures' },
+            { cmd: 'beehaven webhook show User/abc123 wh-789' },
+            { cmd: 'beehaven webhook replay User/abc123 wh-789' },
+        ],
+        related: ['user', 'sql', 'workspace'],
+    },
+    workspace: {
+        synopsis: 'beehaven workspace',
+        description: `Overview of the target DO — tables (name + row count + top 5 columns) and actions (grouped by category). The fastest way to understand a DO's shape after \`cd\`.`,
+        examples: [{ cmd: 'beehaven workspace' }],
+        related: ['actions', 'sql', 'ls'],
+    },
+    watch: {
+        synopsis: 'beehaven watch [--format <fmt>]',
+        description: `Stream live events from the target DO (table mutations, deltas,
+    broadcast events). One JSON event per line by default.`,
+        flags: [
+            { name: '--format tool-use', desc: 'Structured {event, table, id, delta} shapes for agents' },
+        ],
+        examples: [
+            { cmd: 'beehaven watch' },
+            { cmd: 'beehaven watch --format tool-use | grep row-changed' },
+        ],
+        related: ['workspace', 'sql'],
+    },
+    shop: {
+        synopsis: 'beehaven shop <find|at|search|get|checkout> [...]',
+        description: `Shop via the shop@0 protocol. "find" searches Yellow Pages;
+    "at <addr>" routes to a specific shop; bare "search/get/checkout" uses
+    the active target.`,
+        examples: [
+            { cmd: 'beehaven shop find "running shoes" --category footwear --geo US' },
+            { cmd: 'beehaven shop at shopifyStore/clearly-demo search "hoodie"' },
+            { cmd: 'beehaven shop checkout --items \'[{"variantId":"v1","quantity":1}]\'' },
+        ],
+        related: ['cd', 'call', 'actions'],
+    },
+    status: {
+        synopsis: 'beehaven status',
+        description: `Daemon + account health + current target + "what to do next" hint.
+    Use when something seems wrong and you're not sure if it's the daemon,
+    auth, or the target.`,
+        examples: [{ cmd: 'beehaven status' }],
+        related: ['pwd', 'buildings'],
+    },
+    buildings: {
+        synopsis: 'beehaven buildings',
+        description: `List every DO you can reach — local apps (installed),
+    common cloud DO types. Useful before \`cd\` when you don't know the address.`,
+        examples: [{ cmd: 'beehaven buildings' }],
+        related: ['cd', 'pwd'],
+    },
+    task: {
+        synopsis: 'beehaven task "<title>" [--status active|idea|shipped]',
+        description: `Create a task note on the active target. Shorthand for
+    \`beehaven call note-create '{"title":"...","fileType":"board","status":"active"}'\`.
+
+    ⚠⚠ --status IS APPLIED NOW (fixed 2026-09-05, CBH2-4). It used to be dropped
+    on the way to note-create — every task stored "active" — while this command
+    printed the status you ASKED for, so the terminal confirmed a write that had
+    not happened. The line now echoes what the SERVER stored.
+
+    ⚠ An unrecognised status is REFUSED rather than stored. Nothing renders a
+    status outside active|idea|shipped, so it would file the task somewhere no
+    view can show it.`,
+        examples: [
+            { cmd: 'beehaven task "Fix the IPC auth bug"' },
+            { cmd: 'beehaven task "Voice CLI idea" --status idea' },
+        ],
+        related: ['search', 'call'],
+    },
+    search: {
+        synopsis: 'beehaven search "<query>" [--limit N]',
+        description: `Ranked full-text search across documents on the active target
+    (FTS5/BM25, stemmed — "credits" finds "crediting").
+
+    ⚠⚠ --limit IS HONOURED NOW (fixed 2026-09-05, CBH2-29). It was accepted and
+    ignored — every search returned 20 rows whatever you asked for — which reads
+    as support, because this CLI rejects flags it does not know. 1-200; a
+    non-number or 0 is refused, and above 200 it clamps and says so.
+
+    ⚠ Each hit prints its KEY (\`CLR-42\`), so a result can be handed straight to
+    \`cat ~/CLR-42.md\` or \`open\`. A title is not an address — two notes can
+    share one.
+
+    ⚠ THREE VERBS SEARCH, AND THEY ANSWER DIFFERENT QUESTIONS:
+      search  → which documents are ABOUT this      (ranked, stems)
+      grep    → which documents CONTAIN this string (literal, substring)
+      find    → what is this CALLED / where is it   (POSIX, name + path)
+
+    ⚠ \`find\` IS NOT A SYNONYM FOR THIS, though \`help\` used to say so. It runs
+    POSIX find and reports a missing PATH, which reads as an empty workspace.
+
+    ⚠ It searches BODIES, so a document created with no body is invisible here
+    however good its title.`,
+        examples: [
+            { cmd: 'beehaven search "revenue attribution"' },
+            { cmd: 'beehaven search "pricing" --limit 5', note: 'bound the output' },
+            { cmd: 'beehaven grep -ril pricing ~', note: 'literal string instead' },
+        ],
+        related: ['grep', 'find', 'cat', 'task', 'call'],
+    },
+    /**
+     * ⚠ `workspaces` WAS INVISIBLE TWICE OVER — no help page AND not named in the top-level verb
+     * list, yet it is the command that prints the connect string for every workspace you can reach.
+     * A verb you can only find by already knowing it exists is not on the surface.
+     */
+    workspaces: {
+        synopsis: 'beehaven workspaces',
+        description: `Every workspace this account can reach, with your role in each
+    and the exact \`beehaven connect\` line for it.
+
+    This is the answer to "what else is there" and to "how do I address the other
+    one" — the ids are 64-hex and nobody types them from memory, so copy the
+    printed connect line.
+
+    ⚠ ENUMERATING IS NOT SWITCHING. This lists them; \`beehaven connect
+    workspace/<id>\` is what moves you. The one marked (default) is where a bare
+    \`connect home\` lands.`,
+        examples: [
+            { cmd: 'beehaven workspaces' },
+            { cmd: 'beehaven connect workspace/<id>', note: 'copy the printed line' },
+            { cmd: 'beehaven pwd', note: 'which one am I in now' },
+        ],
+        related: ['cd', 'pwd', 'buildings', 'status'],
+    },
+    library: {
+        synopsis: 'beehaven library <list|get|add|rm|search> [args]',
+        description: `The reference library — saved images, components and sources the
+    agent can look at again. Bare \`library\` lists.
+
+    Entries are addressed by the short id in the first column of \`library list\`.
+
+    ⚠⚠ THAT SENTENCE WAS FALSE UNTIL 2026-09-05 (CBH2-30). \`list\` and \`search\`
+    print \`id.slice(0,8)\` so the columns line up, and \`get\` / \`rm\` refused
+    exactly that string with a bare "Not found" — which is what you print for a
+    DELETED row, so it sent readers hunting for a data problem. There was no
+    route from \`list\` to \`get\` inside the CLI at all; the full uuid was only
+    reachable via \`beehaven call library-list\` — the actions door, which a
+    person reading \`library list\` output has no reason to go looking for.
+
+    Both forms work now. A prefix of 6+ characters resolves; one that matches
+    two entries is REFUSED with the candidates rather than guessed — which
+    matters most for \`rm\`, where guessing destroys the wrong asset and its
+    R2 object.`,
+        examples: [
+            { cmd: 'beehaven library list' },
+            { cmd: 'beehaven library search "card"' },
+            { cmd: 'beehaven library get bbd9fd21', note: 'the short id from the list — a prefix is fine' },
+        ],
+        related: ['teleport', 'doc', 'ls'],
+    },
+    /**
+     * ⚠ `help` HAD NO PAGE FOR ITSELF — caught by the derived coverage guard, which is the point of
+     * deriving it. The CLI's top-level help points every agent at `beehaven help <command>`, so the
+     * one verb guaranteed to be tried is the one that answered "No help page for help".
+     */
+    help: {
+        synopsis: 'beehaven help [command]',
+        description: `Deep help for one command. Bare \`beehaven help\` prints the
+    index of every page and alias; \`beehaven --help\` prints the whole surface at
+    once.
+
+    ⚠ A page is a CLAIM, and its examples are meant to be runnable as printed. If
+    one is not, that is a bug worth filing — four shell pages once documented a
+    namespace that needed a scope the reader did not have, and every example on
+    them failed.
+
+    An unknown name exits non-zero and suggests near matches.`,
+        examples: [
+            { cmd: 'beehaven help', note: 'the index' },
+            { cmd: 'beehaven help ls' },
+            { cmd: 'beehaven --help', note: 'the whole surface' },
+        ],
+        related: ['actions', 'explain', 'workspace'],
+    },
+    link: {
+        synopsis: 'beehaven link [--project <id>]   ·   beehaven unlink',
+        description: `Bind THIS local folder to a Clearly project, so a coding agent
+    working in it can be given the project's own notes. With no \`--project\` it
+    offers the projects it can see.
+
+    ⚠ THIS IS THE PREREQUISITE FOR \`context\`. Unlinked, \`beehaven context\`
+    does nothing and says so — that is the whole failure mode, and it is not a
+    workspace error.
+
+    ⚠ Local, per-folder state. It changes nothing in the workspace.`,
+        examples: [
+            { cmd: 'beehaven link --project <id>' },
+            { cmd: 'beehaven context', note: 'what the link is for' },
+            { cmd: 'beehaven unlink' },
+        ],
+        related: ['context', 'pwd', 'workspace'],
+    },
+    'mcp-config': {
+        synopsis: 'beehaven mcp-config [--name <server-name>]',
+        description: `Print the MCP server block instead of writing it — for a client
+    \`mcp install\` does not know about, or a config you keep in version control.
+
+    ⚠⚠ IT MINTS A REAL TOKEN. The printed block contains a live \`ck_mcp_*\`
+    credential, so this is not a dry run: treat the output as a secret, and
+    revoke with \`beehaven mcp remove\` rather than just deleting the text.
+
+    ⚠ The block is minted for the workspace you are CONNECTED to — \`beehaven
+    pwd\` first.`,
+        examples: [
+            { cmd: 'beehaven mcp-config --name clearly' },
+            { cmd: 'beehaven mcp install', note: 'write it for detected clients instead' },
+            { cmd: 'beehaven mcp remove', note: 'revoke the token' },
+        ],
+        related: ['mcp', 'pwd', 'workspaces'],
+    },
+    mcp: {
+        synopsis: 'beehaven mcp <install|status|remove>',
+        description: `Connect the AI clients on THIS machine to the workspace you are
+    connected to. \`install\` detects Claude Code, Claude Desktop, Cursor and Codex
+    and writes the server entry into each; \`status\` shows which are configured;
+    \`remove\` deletes the entries and revokes the token.
+
+    ⚠ IT WRITES FOR THE WORKSPACE YOU ARE IN. \`beehaven pwd\` first — installing
+    from the wrong target points every client at the wrong workspace.
+
+    ⚠ For a client that is not on this machine (claude.ai, another laptop) there is
+    nothing to install: point it at the endpoint and let it sign you in. Print the
+    block instead of writing it with \`beehaven mcp-config\`.`,
+        examples: [
+            { cmd: 'beehaven mcp status', note: 'which clients are configured' },
+            { cmd: 'beehaven mcp install' },
+            { cmd: 'beehaven mcp-config --name clearly', note: 'print, do not write' },
+        ],
+        related: ['pwd', 'workspaces', 'agent', 'skills'],
+    },
+    context: {
+        synopsis: 'beehaven context',
+        description: `Refresh \`.clearly/CLAUDE.md\` in the CURRENT LOCAL FOLDER from
+    the Clearly project it is linked to — so a coding agent opening this repo
+    starts with the project's own notes in front of it.
+
+    ⚠ IT NEEDS A LINK FIRST. In an unlinked folder it says so and does nothing:
+    "This folder is not linked to a Clearly project. Run 'beehaven link'."
+    That is the whole failure mode — it is not a workspace error.
+
+    ⚠ This is the one verb here that writes to your LOCAL disk rather than to the
+    workspace.`,
+        examples: [
+            { cmd: 'beehaven context' },
+            { cmd: 'beehaven link --project <id>', note: 'required first, once per folder' },
+        ],
+        related: ['workspace', 'pwd', 'doc'],
+    },
+    remember: {
+        synopsis: 'beehaven remember <key> <value>',
+        description: `Store an agent memory — key/value pair retrievable via recall.`,
+        examples: [{ cmd: 'beehaven remember favorite-color blue' }],
+        related: ['recall'],
+    },
+    recall: {
+        synopsis: 'beehaven recall [query]',
+        description: `Retrieve agent memories. With a query, semantic-matches.
+    Without, lists recent.`,
+        examples: [{ cmd: 'beehaven recall "favorite color"' }],
+        related: ['remember'],
+    },
+    teleport: {
+        synopsis: 'beehaven teleport <file> [--to <path>] [--composition <id>] [--no-document]',
+        description: `Upload a file into workspace storage. This is the terminal
+    equivalent of dragging a file onto the gallery, and it does the same four
+    things:
+
+      1. put the bytes in R2 (under uploads/, or --to <dir>)
+      2. insert the \`files\` row that /recents reads
+      3. index it for search, when the format carries text
+      4. hand back the file id
+
+    ⚠⚠ STEP 4 DID NOT HAPPEN UNTIL 2026-09-05 (CBH2-38). The output was a VFS
+    path and nothing else, so the two-step printed in \`beehaven help sheet\` —
+    \`teleport ./data.csv && sheet import <fileId>\` — had no <fileId> to
+    substitute, and the only way to get one was
+    \`beehaven sql "SELECT id FROM files WHERE name LIKE …"\`. The id is printed
+    on both upload paths now, with the \`sheet import\` line for a .csv/.tsv.
+
+    Step 3 is what most callers forget they need. \`document-search\` is
+    full-text over the document BODY, so a file that is never projected into a
+    document is stored, listed, and invisible to every search you will run
+    afterwards. Pass --no-document only when you want an opaque blob.
+
+    HOW THE BYTES TRAVEL, and why you do not choose: under ~900KB the file
+    rides inline over the relay; above it, teleport asks for a presigned URL and
+    PUTs straight to R2, so large files never cross the WebSocket. The switch is
+    automatic. The overall ceiling is 100MB.
+
+    PDFs are stored and openable but NOT searchable — text extraction for PDF
+    runs in the browser, which a terminal has no equivalent of.
+
+    --composition <id> stores the file as that composition's own asset instead,
+    so it does not appear in /recents and is not projected into a document.`,
+        flags: [
+            { name: '--to <dir>', desc: 'Destination directory in workspace storage (default: uploads/)' },
+            { name: '--composition <id>', desc: 'Store as a composition asset instead of a workspace file' },
+            { name: '--no-document', desc: 'Skip the search-indexing step; store an opaque blob' },
+        ],
+        examples: [
+            { cmd: 'beehaven teleport ./report.pdf' },
+            { cmd: 'beehaven teleport ./notes.md --to research/' },
+            { cmd: 'beehaven teleport ./photo.png --no-document' },
+        ],
+        related: ['ls', 'cat', 'call'],
+    },
+    agent: {
+        synopsis: 'beehaven agent [<identity-cmd>] | ["<msg>"] [-c] [-l] [-p <provider>] [-m <model>]',
+        description: `Two surfaces under one verb:
+
+    IDENTITY — sign in as a per-agent principal so a runtime can drive its
+    OWN avatar. Each terminal carries a different identity via the
+    BEEHAVEN_AGENT env var (per-tty), so 4 windows = 4 avatars:
+      agent login <name> [--label <work>] [--client <client>]  — identity + ONE work session + brief
+      agent use <name>     — prints \`export BEEHAVEN_AGENT=<name>\`; eval it
+      agent list           — list stored identities, mark the active one
+      agent whoami         — show the active identity + TTL
+      agent logout [<name>]— end its local session, keep the identity
+      agent delete <name>  — archive the current workspace projection + remove this device copy
+      agent delete <name> --account --yes
+                           — delete the portable account identity across workspaces + this device copy
+      agent rebind <name> --avatar <id>  — re-bind to a different avatar
+
+    REPL — a bare \`agent\` (or \`agent "<msg>"\`) launches the Omni terminal
+    REPL / one-shot message on the active target.
+
+    Canonical start: select the target first, then run
+    \`beehaven agent login <name> --label "<work>" --client cli\`. Login already
+    starts one workspace work session and prints its brief. Do not immediately
+    call \`agent-login\`; that RPC aliases \`agent-session-start\` and starts another.
+
+    The active identity (BEEHAVEN_AGENT or --agent <name>) is attached to
+    \`app call\` / \`say\` / \`speak\`, routing avatar calls to that agent's
+    avatar instance.`,
+        flags: [
+            { name: '--avatar <id>', desc: 'Avatar routing id (login/rebind)' },
+            { name: '--avatar-skin <skin>', desc: 'Mwah skin to wear; auto-assigned when omitted' },
+            { name: '--kind <k>', desc: 'claude-code | daemon-agent | clearly-ai (login)' },
+            { name: '--label <work>', desc: 'Label the workspace work session started by login' },
+            { name: '--client <client>', desc: 'Session client label (default: cli)' },
+            { name: '--agent <name>', desc: 'Per-call active-identity override (any command)' },
+            { name: '-c, --continue', desc: 'REPL: continue the last conversation' },
+            { name: '-l, --local', desc: 'REPL: use local LLM (Ollama)' },
+            { name: '-p <provider>', desc: 'REPL: openrouter, gemini, anthropic (default: platform)' },
+            { name: '-m <model>', desc: 'REPL: model name' },
+        ],
+        examples: [
+            { cmd: 'beehaven connect home && beehaven agent login monet --label "audit launch" --client cli', note: 'identity + one labelled work session + brief' },
+            { cmd: 'eval "$(beehaven agent use monet)"', note: 'activate in this terminal' },
+            { cmd: 'beehaven say "hi from monet"', note: "speaks via monet's avatar" },
+            { cmd: 'beehaven agent rebind monet --avatar studio-2' },
+            { cmd: 'beehaven agent whoami' },
+            { cmd: 'beehaven agent "what can you do?"', note: 'REPL one-shot' },
+        ],
+        related: ['app', 'pipe', 'pwd'],
+    },
+    swarm: {
+        synopsis: 'beehaven swarm <list|queen|role|dispatch|bees|sample-honey|forge-omni> [args]',
+        description: `The distributed HIVE MESH + its two AI bees. A "beehive" is a
+    node running the daemon + hives (this Mac, a headless server via
+    \`start --headless\`, or a Cloudflare container). A QUEEN hive orchestrates;
+    WORKER hives execute the work the queen dispatches. This machine registers
+    itself when the daemon connects — the Mac defaults to QUEEN, a
+    headless/container node to WORKER.
+
+    Mesh subcommands:
+      list                     Every beehive: role, kind, hives, online state
+      queen                    Which NODE is orchestrating right now
+      role <queen|worker>      Make THIS machine the queen (or a worker)
+      whoami                   This machine's beehive identity
+      dispatch <cap> <action> [json]   Route work to the best worker (--target pins one)
+      forget <deviceId>        Drop a stale OFFLINE node
+
+    The bees (AI):
+      bees                     👑 Queen + 🐝 Omni status
+      sample-honey             👑 Queen ingests the WHOLE workspace corpus
+                               (memories, brain, prompts, brand voice) and gets fat
+      forge-omni [--force]     👑 Queen distills a LEAN copy of you → 🐝 Omni,
+                               your personal-assistant AI TWIN (--force re-samples)
+
+    The Queen bee runs on the queen hive — same crown, two layers (the NODE vs.
+    the AI). Omni is the owner's twin: log in as it with \`agent login omni-bee\`.
+    Distinct from \`hives\` (local apps) — a beehive is a whole NODE.`,
+        flags: [
+            {
+                name: '--target <deviceId>',
+                desc: 'dispatch: pin to a specific beehive instead of auto-selecting',
+            },
+            { name: '--force', desc: 'forge-omni: re-sample the honey before distilling' },
+        ],
+        examples: [
+            { cmd: 'beehaven swarm list', note: 'see the whole swarm' },
+            { cmd: 'beehaven swarm role queen', note: 'make this machine the queen' },
+            { cmd: 'beehaven swarm sample-honey', note: 'Queen ingests everything' },
+            { cmd: 'beehaven swarm forge-omni', note: 'forge your AI twin' },
+            { cmd: 'beehaven agent login omni-bee', note: 'log in as your twin' },
+        ],
+        related: ['hives', 'app', 'agent', 'status'],
+    },
+    pipe: {
+        synopsis: 'beehaven pipe',
+        description: `JSON-RPC 2.0 over stdin/stdout — for Claude Code and other
+    agents that want structured interaction. Methods: actions.list,
+    actions.describe, workspace.info, plus any action name as a method.`,
+        examples: [
+            {
+                cmd: `echo '{"jsonrpc":"2.0","id":1,"method":"actions.list","params":{}}' | beehaven pipe`,
+                note: 'one-shot action listing',
+            },
+        ],
+        related: ['actions', 'call'],
+    },
+    batch: {
+        synopsis: 'beehaven batch <json|@file|-> [--json]',
+        description: `Run the workspace's existing 'batch' action without hand-encoding
+    the generic 'call' envelope. The payload is JSON (inline, from '@file', or
+    from stdin with '-') and must contain the server action's 'steps' array.
+    Steps execute sequentially and the operation is NOT transactional: earlier
+    successful steps are not rolled back when a later step fails. The server
+    enforces its action-count/payload limits and 'stopOnError' policy. This is
+    a thin adapter, so the active target, agent identity, permission re-gating,
+    spend guard and non-zero failure semantics are the same as 'beehaven call'.`,
+        flags: [
+            { name: '--json', desc: 'Keep stdout machine-readable (suppresses the routing breadcrumb).' },
+        ],
+        examples: [
+            { cmd: `beehaven batch '{"steps":[{"action":"ticket-list","input":{"limit":10}}]}' --json` },
+            { cmd: 'beehaven batch @steps.json --json', note: 'read a large payload from a file' },
+            { cmd: 'cat steps.json | beehaven batch - --json', note: 'read the payload from stdin' },
+        ],
+        related: ['call', 'actions', 'code-run'],
+    },
+    'code-run': {
+        synopsis: 'beehaven code-run <file|-> [--json]',
+        description: `Run JavaScript inside the workspace's existing 'code-run'
+    sandbox. Pass a source file as '@script.js', or use '-' to read source
+    from stdin. A JSON object containing 'code' is also accepted when optional
+    'maxCalls' or 'timeoutMs' limits need to be supplied. The sandbox can call
+    workspace actions and return computed data; it is not a shell. This adapter
+    delegates through 'beehaven call', so target routing, agent attribution,
+    policy gates and failure exits stay identical.`,
+        flags: [
+            { name: '--json', desc: 'Keep stdout machine-readable (suppresses the routing breadcrumb).' },
+        ],
+        examples: [
+            { cmd: 'beehaven code-run @summarize.mjs --json', note: 'run a source file' },
+            { cmd: 'cat summarize.mjs | beehaven code-run - --json', note: 'run source from stdin' },
+            { cmd: `beehaven code-run '{"code":"return await clearly.call(\\"workspace-info\\", {})","maxCalls":4}' --json` },
+        ],
+        related: ['batch', 'call', 'actions'],
+    },
+    hives: {
+        synopsis: 'beehaven help hives',
+        description: `Local hives — installable apps that run inside the daemon on
+    this machine. Each hive contains one or more buildings (DO-shaped
+    classes) plus optional tray settings + companion window. Examples:
+    recorder (system audio), avatar (mwah desktop companion), memory-cloud
+    (agent memory), elevenlabs (BYOK TTS).
+
+    Mental model:
+      install   →  add an app to the daemon's tool palette
+      connect   →  set the active target to that app
+      call      →  invoke one of its actions
+      uninstall →  remove it (drops its tools from the agent surface)
+
+    Local-hive workflow (every install, same four steps):
+      beehaven install <name>                   # add to ~/.beehaven/apps/
+      beehaven restart                          # daemon picks up the new building
+      beehaven connect <name>                   # set active target
+      beehaven actions                          # see what it exposes
+      beehaven call <action> '{"...":"..."}'    # run one
+
+    Hives ship in three lanes:
+      bundled    — first-party hives included with the Hive Mac app
+      catalog    — published marketplace hives, install by name
+      sideload   — local dev .hive archives, install by path (signed) or
+                   --allow-unsigned (dev only)
+
+    The daemon is tray-coupled: hives only run while the Hive Mac app is
+    open. Uninstalling makes a hive's actions vanish from the agent's tool
+    palette on the next daemon start — there is no per-action toggle.
+
+    Paired Claude Code skills:
+      A hive can declare \`agentDocs.claudeCode\` in its app.json pointing
+      at a SKILL.md. On install the CLI offers to drop that file under
+      ~/.claude/skills/beehaven-<name>/ so Claude Code automatically loads
+      the hive's verb surface as context. Flags: --with-skills (skip the
+      prompt and install) / --no-skills (skip install entirely). Manage
+      via \`beehaven skills <list|sync|remove>\`.
+
+    Reference: docs/LOCAL_HIVES.md (manifest schema, capabilities, dev
+    workflow, sign + publish, agent docs).`,
+        examples: [
+            { cmd: 'beehaven install memory-cloud', note: 'install by name from catalog' },
+            { cmd: 'beehaven install ./my-app.hive', note: 'install a signed local archive' },
+            { cmd: 'beehaven install ./my-app.hive --allow-unsigned', note: 'install a dev build' },
+            {
+                cmd: 'beehaven install ./my-app.hive --with-skills',
+                note: 'install + paired SKILL.md, no prompt',
+            },
+            { cmd: 'beehaven app list', note: 'see installed + available hives' },
+            { cmd: 'beehaven app pack .', note: 'build a .hive from cwd (app.json required)' },
+            { cmd: 'beehaven connect recorder && beehaven actions', note: "inspect a hive's actions" },
+            { cmd: 'beehaven call record \'{"source":"mic"}\'', note: 'invoke an action once connected' },
+            { cmd: 'beehaven skills sync', note: 'install paired skills for already-installed hives' },
+        ],
+        related: ['app', 'install', 'pack', 'uninstall', 'skills', 'connect', 'call', 'buildings'],
+    },
+    app: {
+        synopsis: 'beehaven app <list|install|pack|uninstall|call|actions|run|setup> [...]',
+        description: `Manage installed hives (apps). All verbs route through the
+    daemon when it's running so the Clearly account stays in sync; offline,
+    list/uninstall fall back to filesystem-only operations under
+    ~/.beehaven/apps/.
+
+    Verbs:
+      app list                      Installed + available from the catalog
+      app install <name|path|url>   Add a hive. Names hit the catalog; paths
+                                    and URLs install local/remote .hive
+                                    archives (signature required unless
+                                    --allow-unsigned)
+      app pack <dir> [-o out.hive]  Zip <dir> into a .hive archive. Optional
+                                    --key + --signer for signed releases
+      app uninstall <name>          Remove from ~/.beehaven/apps/. Daemon
+                                    drops the building on next restart
+      app call <building>[/<id>] <action> [json]   One-shot action call
+                                    (escape hatch — prefer connect + call)
+      app actions [<building>]      List actions on one building or all
+                                    registered buildings
+      app run <app>/<recipe>        Execute a pipeline recipe an app ships
+      app setup <name>              Re-run an app's setup.sh (driver install,
+                                    model download, etc.)
+
+    The canonical agent workflow is connect + call, not app call. app call
+    exists for scripting and for cases where you don't want to change the
+    active target.`,
+        flags: [
+            {
+                name: '--allow-unsigned',
+                desc: '(install) Accept archives without a .sig file. Dev only.',
+            },
+            {
+                name: '--with-skills',
+                desc: '(install) Install paired Claude Code SKILL.md without prompting.',
+            },
+            { name: '--no-skills', desc: '(install) Never install paired SKILL.md.' },
+            { name: '-o, --output <path>', desc: '(pack) Output path. Default: ./<name>-<version>.hive' },
+            { name: '--key <pem>', desc: '(pack) Ed25519 private key for signing' },
+            { name: '--signer <id>', desc: '(pack) Signer identifier baked into the .sig envelope' },
+            { name: '--instance <id>', desc: '(call/actions) Building instance id. Default: live' },
+            { name: '--timeout <ms>', desc: '(call) Override the 30s default' },
+            { name: '--json', desc: '(actions) Raw JSON output' },
+        ],
+        examples: [
+            { cmd: 'beehaven app list' },
+            { cmd: 'beehaven app install mwah', note: 'by name (catalog + cloud sync)' },
+            { cmd: 'beehaven app install ./build/recorder-0.1.0.hive' },
+            {
+                cmd: 'beehaven app install ./build/my-app.hive --with-skills',
+                note: 'no prompt; install paired SKILL.md',
+            },
+            { cmd: 'beehaven app pack . -o dist/my-app.hive --key ~/.keys/ed25519.pem --signer my-org' },
+            { cmd: 'beehaven app actions recorder', note: "see one building's action surface" },
+            {
+                cmd: 'beehaven app call avatar say \'{"text":"hello"}\'',
+                note: 'one-shot, no connect needed',
+            },
+            { cmd: 'beehaven app run nitepunk-piano/build', note: 'execute a shipped recipe' },
+            { cmd: 'beehaven app uninstall elevenlabs' },
+        ],
+        related: ['hives', 'install', 'pack', 'uninstall', 'skills', 'connect', 'call', 'buildings'],
+    },
+    install: {
+        synopsis: 'beehaven install <name|path|url> [--allow-unsigned] [--with-skills|--no-skills]',
+        description: `Shorthand for \`beehaven app install\`. Three source shapes:
+
+      name   — resolves through the catalog (e.g. mwah, ableton, recorder).
+               Requires the daemon to be running (catalog lookup + account
+               sync happen daemon-side). Installs to ~/.beehaven/apps/.
+      path   — a local .hive archive (e.g. ./build/my-app.hive). Looks for
+               a sibling .sig file; without one, refuses unless
+               --allow-unsigned is passed.
+      url    — http(s) URL to a .hive archive. Best-effort fetches <url>.sig
+               alongside; same signature policy as path installs.
+
+    After install, the daemon needs a restart to pick up new building
+    classes (\`beehaven restart\`, or quit + relaunch the Mac app).
+
+    Signature policy (default-deny): production CLI builds pin
+    trusted-signer public keys. An archive with a missing or invalid
+    signature is refused. Pass --allow-unsigned for local dev builds.
+
+    Paired Claude Code skills: if the hive's app.json declares
+    \`agentDocs.claudeCode\`, the CLI offers to drop that SKILL.md under
+    ~/.claude/skills/beehaven-<name>/ for Claude Code to pick up. By
+    default this is INTERACTIVE — you see a preview and confirm. In
+    non-TTY runs (CI) the skill is skipped unless --with-skills is set.
+    --no-skills always skips the prompt and install.`,
+        flags: [
+            { name: '--allow-unsigned', desc: 'Accept archives without a .sig file. Dev only.' },
+            { name: '--with-skills', desc: 'Install paired Claude Code SKILL.md without prompting.' },
+            { name: '--no-skills', desc: 'Never install paired SKILL.md (skip the prompt entirely).' },
+        ],
+        examples: [
+            { cmd: 'beehaven install memory-cloud', note: 'by name from catalog' },
+            { cmd: 'beehaven install ./build/recorder-0.1.0.hive' },
+            { cmd: 'beehaven install https://hives.example.com/cool-tool.hive' },
+            { cmd: 'beehaven install ./my-dev-build.hive --allow-unsigned' },
+            {
+                cmd: 'beehaven install memory-cloud --with-skills',
+                note: 'no prompt; install paired SKILL.md',
+            },
+            { cmd: 'beehaven install memory-cloud --no-skills', note: 'no prompt; skip SKILL.md' },
+        ],
+        related: ['app', 'hives', 'pack', 'uninstall', 'skills', 'connect'],
+    },
+    skills: {
+        synopsis: 'beehaven skills <list|sync|remove> [args]',
+        description: `Manage Claude Code skills paired with installed hives.
+
+    A hive can ship a SKILL.md and reference it from app.json:
+      { "agentDocs": { "claudeCode": "skills/SKILL.md" } }
+
+    On install, the CLI prompts to drop that file under
+    ~/.claude/skills/beehaven-<hive-name>/ so Claude Code auto-loads the
+    hive's verb surface as context. The \`beehaven-\` prefix namespaces
+    these so they're visually identifiable and so this command can mass-
+    manage them without touching your own skills.
+
+    Subcommands:
+      list (default)         Show paired skills installed under
+                             ~/.claude/skills/beehaven-*/, with the
+                             owning hive name + version + install date.
+      sync                   Re-scan ~/.beehaven/apps/ and install any
+                             missing paired skills. Honors --with-skills
+                             / --no-skills for non-interactive runs.
+      remove <hive-name>     Remove the paired skill for one hive.
+      remove all             Remove every beehaven- prefixed skill.
+
+    Each installed skill dir carries a \`.beehaven-source\` marker so this
+    command never deletes a directory it didn't write — your own skills
+    are safe even if you name one \`beehaven-foo\`.
+
+    Trust note: a SKILL.md is essentially injected instructions for
+    Claude. Defaulting to a prompt with preview keeps that explicit.`,
+        flags: [
+            { name: '--with-skills', desc: '(sync) Install without per-hive prompt' },
+            { name: '--no-skills', desc: '(sync) Skip every install (effectively a dry-run)' },
+        ],
+        examples: [
+            { cmd: 'beehaven skills', note: 'lists installed paired skills (default subcommand)' },
+            { cmd: 'beehaven skills sync', note: 'install missing skills for already-installed hives' },
+            { cmd: 'beehaven skills sync --with-skills', note: 'non-interactive: install everything' },
+            { cmd: 'beehaven skills remove memory-cloud' },
+            { cmd: 'beehaven skills remove all', note: 'nuke every beehaven-paired skill' },
+        ],
+        related: ['hives', 'install', 'app', 'uninstall'],
+    },
+    pack: {
+        synopsis: 'beehaven app pack <dir> [-o out.hive] [--key <pem>] [--signer <id>]',
+        description: `Build a distributable .hive archive from <dir>. The directory
+    must contain app.json at its root; the manifest is validated before
+    packing — referenced building entries (\`buildings[].entry\`) and
+    frontend dir must exist on disk.
+
+    The archive is a plain zip with app.json + dist/ + ui/ + scripts/ +
+    bundled assets. The build skips node_modules, .git, .DS_Store, .turbo,
+    .cache.
+
+    With --key, also writes <out>.sig — a JSON envelope containing the
+    archive's SHA-256 + an Ed25519 signature by the given signer. The
+    signer id is baked into the envelope; consumers verify against pinned
+    trusted public keys (TRUSTED_SIGNERS in app-signing.ts).
+
+    Output defaults to ./<name>-<version>.hive (from the manifest).`,
+        flags: [
+            { name: '-o, --output <path>', desc: 'Output path' },
+            { name: '--key <pem>', desc: 'Ed25519 private key for signing' },
+            { name: '--signer <id>', desc: 'Signer identifier (default: clearly-release)' },
+        ],
+        examples: [
+            { cmd: 'beehaven app pack .' },
+            { cmd: 'beehaven app pack ./hives/recorder -o dist/recorder.hive' },
+            {
+                cmd: 'beehaven app pack . --key ~/.keys/ed25519.pem --signer my-org',
+                note: 'signed release',
+            },
+        ],
+        related: ['install', 'app', 'hives', 'uninstall'],
+    },
+    uninstall: {
+        synopsis: 'beehaven app uninstall <name>',
+        description: `Remove an installed hive from ~/.beehaven/apps/. Routes
+    through the daemon so the user's Clearly account sees the change;
+    falls back to direct filesystem removal when the daemon is offline
+    (no cloud sync in that case).
+
+    The strip is by name — version suffixes (\`name@1.2.3\`) are accepted
+    but ignored; all matching versions are removed. The in-memory building
+    instance lives until the daemon restarts; until then, calls that
+    target the removed building will keep working against the cached
+    class. Restart to fully drop it.`,
+        examples: [
+            { cmd: 'beehaven app uninstall elevenlabs' },
+            {
+                cmd: 'beehaven app uninstall recorder@0.1.0',
+                note: 'version suffix ignored — removes all versions',
+            },
+        ],
+        related: ['app', 'install', 'hives', 'pack'],
+    },
+    say: {
+        synopsis: 'beehaven say "<text>"',
+        description: `Put words on the character — a card in its transcript lane, readable after it
+    has been said. No model, no Python venv, nothing to install.
+
+    ⚠ THIS IS THE ONE THAT WORKS. \`speak\` is deprecated and exits 1; it walked a ladder of four
+    TTS engines, so a failed rung SUBSTITUTED a different voice and the same command sounded like
+    two different products depending on whether a daemon happened to be up. \`say\` has no ladder
+    to fall down.
+
+    ⚠ IT NEEDS AN AGENT IDENTITY, like every verb that reaches the workspace — the card is
+    attributed to whoever said it. \`beehaven agent login <name>\` mints one if it is new.`,
+        examples: [
+            { cmd: 'beehaven say "deploying now"', note: 'appears on the character' },
+            { cmd: 'beehaven agent login monet && beehaven say "hi"', note: "says it as monet" },
+        ],
+        related: ['agent', 'voice', 'speak'],
+    },
+    avatar: {
+        synopsis: 'beehaven [--mood <mood>] [--lifecycle <wake|sleep>] [--emote <reaction> [reason]]',
+        description: 'Drive the active agent avatar from the CLI. Use --mood for a persistent mood, --lifecycle for wake/sleep, and '
+            + '--emote for a one-shot reaction. An agent identity routes the call to that '
+            + "agent's own on-screen avatar; without one, it targets the house avatar.\n\n"
+            + 'Moods: neutral, happy, sad, surprised, angry, confused, curious, flirty. Lifecycles: wake, sleep. '
+            + 'One-shot reactions: wave, cheer, hearts, laugh, dance, buzz, nod, shake, think, surprise, sleep.\n\n'
+            + 'An optional --emote reason is capped at 200 characters. MCP equivalents: '
+            + 'avatar_emote({ emotion }), avatar_react({ reaction, reason? }), and avatar_get_state({}) for the current sticky mood and dynamic PAD mood.',
+        examples: [
+            { cmd: 'beehaven --mood curious' },
+            { cmd: 'beehaven --lifecycle sleep', note: 'holds the sleeping lifecycle' },
+            { cmd: 'beehaven --lifecycle wake', note: 'returns to the awake idle pose' },
+            { cmd: 'beehaven --emote cheer "tests passed"' },
+            { cmd: 'beehaven agent login codex && beehaven --emote wave', note: "play it on codex's avatar" },
+            { cmd: 'beehaven avatar react cheer', note: 'compatibility form' },
+        ],
+        related: ['agent', 'say', 'app'],
+    },
+    /**
+     * ⚠ A PAGE FOR `update` EXISTS BECAUSE THE VERB HAS A REFUSAL PATH, and a refusal nobody can
+     * look up reads as the command being broken. Two of the three installs deliberately decline.
+     */
+    update: {
+        synopsis: 'beehaven update',
+        description: `Update this CLI in place — but only when this CLI is one that updates itself.
+
+    THREE INSTALLS, and only one of them may:
+
+      curl install (~/.beehaven/cli)   updates — re-runs the published installer
+      the Mac app bundle               REFUSES — the app ships this CLI and updates it
+      Clearly Dev.app bundle           REFUSES — rebuild and reinstall the development app
+      a linked dev build               REFUSES — that is your working tree
+
+    The Mac app owns its bundled CLI. Its managed wrapper chooses the newer version if a curl
+    install also exists. Updating the bundled copy separately would bypass the app's release and
+    signature checks. A curl install downloads the published manifest and verifies the tarball's
+    sha256 before invoking the installer.
+
+    ⚠ IT NEEDS NO AGENT LOGIN. Replacing this binary never opens a workspace, and requiring an
+    identity would refuse the one command a stale install needs.`,
+        examples: [
+            { cmd: 'beehaven update', note: 'self-update a curl install' },
+            { cmd: 'beehaven --version', note: 'what you are running, and from where' },
+        ],
+        related: ['install', 'doctor', 'status'],
+    },
+    speak: {
+        synopsis: 'beehaven speak "<text>"   (deprecated — use `beehaven say`)',
+        description: `⚠ DEPRECATED — this command no longer synthesizes speech. It exits 1
+    and points here.
+
+    Use \`beehaven say "<text>"\` instead. It puts the words on the avatar as a card
+    in its transcript lane: no model, no Python venv, nothing to install, and the
+    text stays readable after it has been said.
+
+    WHY IT WENT. \`speak\` shipped four engines over its life — cloud Kokoro, the
+    workspace's MiniMax clone, the Mac app's Kokoro and macOS \`say\` — walking a
+    ladder between them, which meant a failed rung SUBSTITUTED a different voice and
+    the same command sounded like two different products depending on whether a
+    daemon happened to be up. Cutting it to one on-device engine (Qwen3-TTS under
+    MLX) fixed the substitution and left the real problem:
+
+      • the voice still was not stable — with nothing pinned the model re-draws a
+        speaker on EVERY utterance, so one agent sounded like a different person
+        sentence to sentence;
+      • pinning it meant deriving a speaker per identity from the THREE presets
+        measured usable out of nine (the other six generate for minutes on a
+        six-second sentence);
+      • and it needed a ~2 minute install and a Python venv before it could say a
+        single word, for a command whose job is a one-line status ping.
+
+    \`beehaven voice *\` still exists and still clones voices, but it configured this
+    command and nothing else now calls it.`,
+        flags: [],
+        examples: [
+            { cmd: 'beehaven say "build is green"', note: 'the replacement' },
+        ],
+        related: ['say', 'voice', 'agent'],
+    },
+    voice: {
+        synopsis: 'beehaven voice [status|provider|setup|clone|list|use|remove|test]',
+        description: `Choose how \`beehaven speak\` makes sound, and manage locally CLONED
+    voices. A bare \`beehaven voice\` (no subcommand) is the push-to-talk REPL:
+    record → transcribe → ask the connected DO → speak the reply.
+
+      status                    active provider + voice, runtime state
+      provider [<name>]         show or set the TTS provider (persisted)
+      setup                     install the local Qwen3-TTS (MLX) runtime
+      clone <name> <audio>      clone a voice from a recording
+      list                      cloned voices
+      use <name>                which cloned voice speak uses (\`none\` clears)
+      remove <name>             forget a cloned voice
+      test ["text"]             synthesize + play a sample
+
+    CLONING runs entirely on this machine (Apple Silicon only) via Qwen3-TTS
+    under MLX — no relay, no API key, no audio leaves the box. 3-30 seconds of
+    clean single-speaker reference is plenty. Qwen3 clones by in-context
+    learning, so it needs the recording AND its transcript; \`clone\` transcribes
+    once with whisper and stores the result, so synthesis never loads an STT
+    model again. Pass \`--ref-text\` to skip transcription.
+
+    The provider + voice persist in ~/.beehaven/config.json (speak is one
+    process per utterance, so an exported env var wouldn't survive).`,
+        flags: [
+            { name: '--ref-text "<text>"', desc: 'clone: supply the transcript, skip whisper' },
+            { name: '--force', desc: 'clone: overwrite an existing voice of that name' },
+            { name: '--tts-voice <name>', desc: 'test: one-shot voice override' },
+            { name: 'BEEHAVEN_TTS_PROVIDER', desc: 'Env override for the provider flag' },
+            { name: 'BEEHAVEN_TTS_VOICE', desc: 'Env override for the cloned voice' },
+            { name: 'BEEHAVEN_QWEN3_TTS_MODEL', desc: 'Env: a different Qwen3-TTS -Base checkpoint' },
+        ],
+        examples: [
+            { cmd: 'beehaven voice setup', note: 'one-time: install mlx-audio' },
+            { cmd: 'beehaven voice clone cove ~/Downloads/cove_export.mp3' },
+            { cmd: 'beehaven voice use cove && beehaven voice provider qwen3-mlx' },
+            { cmd: 'beehaven voice test "hello from the hive"' },
+            { cmd: 'beehaven voice status' },
+        ],
+        related: ['speak', 'status', 'app'],
+    },
+};
+// Aliases — same page, different lookup name.
+const ALIASES = {
+    tts: 'voice',
+    connect: 'cd',
+    nav: 'cd',
+    navigate: 'cd',
+    where: 'pwd',
+    // ⚠ `find` IS DELIBERATELY NOT AN ALIAS OF `search` — it has its own page.
+    //   It used to be listed here, so `help find` rendered the search page while
+    //   dispatch ran POSIX find; see the block above the `find` page for why the
+    //   claim was removed rather than the behaviour changed.
+    ask: 'agent',
+    get: 'cat',
+    describe: 'explain',
+    hive: 'hives',
+    apps: 'app',
+    comp: 'composition',
+    // `unlink` is the same job as `link`, undone — one page covers both.
+    unlink: 'link',
+    // SS-41 — reading a thread is the other half of posting one; `mentions` is the plural people type.
+    comments: 'comment',
+    mentions: 'mention',
+};
+// ── Render ──────────────────────────────────────────────────────────────
+/**
+ * Does this verb have a deep-help page? Exported so `cli.ts` can route `<verb> --help` here —
+ * the pages already existed and were reachable only via `beehaven help <verb>`, i.e. not by the
+ * flag every CLI trains you to type. Returns false for an unknown verb so the caller can fall
+ * back to the global help rather than printing nothing.
+ */
+export function hasHelpPage(command) {
+    if (!command)
+        return false;
+    const canonical = ALIASES[command] ?? command;
+    return !HIDDEN_PUBLIC_COMMANDS.has(canonical) && !!PAGES[canonical];
+}
+/** Print one verb's deep-help page. Precondition: `hasHelpPage(command)`. */
+export function printHelpPage(command) {
+    cmdHelp(command);
+}
+export function cmdHelp(command) {
+    if (!command) {
+        printHelpIndex();
+        return;
+    }
+    const canonical = ALIASES[command] ?? command;
+    if (HIDDEN_PUBLIC_COMMANDS.has(canonical)) {
+        console.error(`beehaven ${canonical} is temporarily unavailable.`);
+        process.exit(1);
+    }
+    const page = PAGES[canonical];
+    if (!page) {
+        /**
+         * ⚠ A BUILDING ADDRESS IS NOT A MISTYPED VERB — CLR-1150. `cli.ts` implements a rich
+         * `beehaven help shopifyStore/clearly-demo` that fetches the DO's live action list, and
+         * it is UNREACHABLE: the intercept in `cli.ts` routes every `help <x>` here before the
+         * switch can see it. Rather than duplicate that fetch, recognise the shape and name the
+         * command that does the job.
+         */
+        if (command.includes('/')) {
+            console.error(`"${command}" looks like a building address, not a command.`);
+            console.error('');
+            console.error('  To see what a building exposes, connect and list its actions:');
+            console.error(`      beehaven connect ${command}`);
+            console.error('      beehaven actions');
+            console.error('');
+            process.exit(1);
+        }
+        console.error(`No help page for "${command}".`);
+        /**
+         * ⚠ Suggest a NEAR MATCH before dumping 50 page names. The top-level unknown-command
+         * handler guesses the wrong axis entirely — it treats an unrecognised word as a
+         * building TYPE — so a plain typo has never been answered with the obvious correction.
+         */
+        const near = Object.keys(PAGES)
+            .map((n) => ({ n, d: editDistance(command, n) }))
+            .filter((x) => x.d <= 3)
+            .sort((a, b) => a.d - b.d)
+            .slice(0, 3)
+            .map((x) => x.n);
+        if (near.length) {
+            console.error('');
+            console.error(`Did you mean: ${near.join(', ')}?`);
+        }
+        console.error('');
+        console.error('Available pages:');
+        const names = Object.keys(PAGES).filter((name) => !HIDDEN_PUBLIC_COMMANDS.has(name)).sort();
+        const cols = 4;
+        for (let i = 0; i < names.length; i += cols) {
+            console.error('  ' +
+                names
+                    .slice(i, i + cols)
+                    .map((n) => n.padEnd(14))
+                    .join(''));
+        }
+        console.error('');
+        console.error('See also: beehaven --help  (top-level overview)');
+        process.exit(1);
+    }
+    console.log('');
+    console.log(`  ${bold(page.synopsis)}`);
+    console.log('');
+    console.log(indent(page.description));
+    console.log('');
+    if (page.flags && page.flags.length > 0) {
+        console.log(`  ${bold('Flags')}`);
+        const maxW = Math.max(...page.flags.map((f) => f.name.length));
+        for (const f of page.flags) {
+            console.log(`    ${f.name.padEnd(maxW + 2)} ${f.desc}`);
+        }
+        console.log('');
+    }
+    if (page.examples && page.examples.length > 0) {
+        console.log(`  ${bold('Examples')}`);
+        for (const ex of page.examples) {
+            console.log(`    ${ex.cmd}`);
+            if (ex.note)
+                console.log(`      ${dim('# ' + ex.note)}`);
+        }
+        console.log('');
+    }
+    console.log(`  ${bold('Related')}`);
+    console.log(`    ${page.related.map((r) => `beehaven help ${r}`).join('  ·  ')}`);
+    console.log('');
+}
+function printHelpIndex() {
+    console.log('');
+    console.log(`  ${bold('beehaven help <command>')}`);
+    console.log(`  ${dim('Deep help for a single command. Agents: call this before running anything unfamiliar.')}`);
+    console.log('');
+    const names = Object.keys(PAGES).filter((name) => !HIDDEN_PUBLIC_COMMANDS.has(name)).sort();
+    console.log(`  ${bold('Pages')}`);
+    const cols = 4;
+    for (let i = 0; i < names.length; i += cols) {
+        console.log('    ' +
+            names
+                .slice(i, i + cols)
+                .map((n) => n.padEnd(14))
+                .join(''));
+    }
+    console.log('');
+    console.log(`  ${bold('Aliases')}`);
+    const aliasLines = Object.entries(ALIASES).map(([a, c]) => `    ${a.padEnd(10)} → ${c}`);
+    for (const line of aliasLines)
+        console.log(line);
+    console.log('');
+    console.log(`  ${dim('See also: beehaven --help  (top-level surface)')}`);
+    console.log('');
+}
+// ── Format helpers ──────────────────────────────────────────────────────
+function bold(s) {
+    return `\x1b[1m${s}\x1b[0m`;
+}
+function dim(s) {
+    return `\x1b[2m${s}\x1b[0m`;
+}
+function indent(s) {
+    return s
+        .split('\n')
+        .map((l) => '  ' + l.trim())
+        .join('\n');
+}
+// Exposed for tests — avoids cross-file spelunking.
+export const __testing = { PAGES, ALIASES };