spexcode 0.2.8 → 0.3.0

package/spec-cli/src/help.ts

@@ -1,345 +1,64 @@
 // @@@ help journey - the CLI's three help layers, each pointing at the next so no probe dead-ends:
-//   1. `spex help`            → the MAP: every porcelain command, grouped by the loop it serves.
-//   2. `spex help <cmd>`      → ONE command's usage (also `spex <cmd> --help`, intercepted pre-verb).
+//   1. `spex help`            → the MAP: the whole noun-first surface, one line per drawer/verb.
+//   2. `spex help <cmd>`      → ONE drawer/command's usage (also `spex <cmd> --help`, intercepted pre-verb).
 //   3. `spex guide [topic]`   → the SKILL layer: workflows, file formats, best practice (guide.ts).
 // help answers "what do I type"; guide answers "how do I work". Machine plumbing (hook/launch-script
 // callees) lives under `spex internal` and is deliberately absent from the map — an agent scanning
 // `spex help` sees only verbs meant for it. Governed by the cli-surface spec node.
+//
+// The grammar the map teaches: `spex <noun> <verb> [object] [flags]` — the verb is always the second
+// token after its noun; a bare noun prints its drawer's help; a bare verb exists only where the object is
+// invariably THIS PROJECT. One verb, one spelling: there are no aliases and no promoted twins.
 
 // One command's help entry. `see` renders as a trailing "see also:" journey pointer.
 type Entry = { line: string; body: string; see?: string }
 
 const SEL_NOTE = `SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
-accepts any of the three; none (or @all) means every session.`
-
-const ROUTING_NOTE = `Backend routing: every session verb accepts --api <url> (--port <n> = localhost sugar) to name its
-backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
-recorded backend / fallback / :8787 (spex guide config → BACKEND ROUTING).`
-
-// aliases resolve to a canonical entry so `spex help session` and `spex session new --help` meet the same text.
-// The session-sub tokens mirror the CLI's verb-mirror rule: each typeable sub also answers bare at the top
-// level, so its help probe (`spex send --help`, `spex help send`) must land on the session entry, not dead-end.
-const SESSION_SUB_TOKENS = ['reopen', 'done', 'park', 'ask', 'exit', 'close', 'send', 'capture', 'attach', 'rename', 'rawkey', 'prompt']
-const ALIAS: Record<string, string> = {
-  'review-proof': 'eval',
-  help: 'help',
-  ...Object.fromEntries(SESSION_SUB_TOKENS.map((t) => [t, 'session'])),
-}
+accepts any of the three; on the list verbs (ls/watch), none (or @all) means every session.`
 
-const ENTRIES: Record<string, Entry> = {
-  // ── find & read the graph ─────────────────────────────────────────────────
-  search: {
-    line: 'search <query>        which spec node GOVERNS a topic — ranked by user-story, not grep',
-    body: `Usage: spex search <query…> [--limit N=10] [--json]
-
-Finds the spec node(s) whose INTENT matches your topic — ranked by user-story relevance, which
-surfaces user-facing behaviour a code-grep misses. Run it BEFORE touching code: the returned node's
-spec.md body is the current contract for that area. Prints title, id, path, snippet per hit.
-The corpus is English — query in English (translate first if your question isn't).`,
-    see: 'spex owner (file → node, the reverse edge) · spex guide spec (what a node is)',
-  },
-  owner: {
-    line: 'owner <path>          the reverse edge: which spec node(s) govern or reference a file',
-    body: `Usage: spex owner <path> [--actionable]
-
-Maps a source file to BOTH spec relations: its GOVERNORS (code: — the source of truth; drives
-drift/yatsu) and its REFERENCERS (related: — coverage only), with the verdict spelled out:
-uncovered ("give it a home"), related-only (covered, but nothing tracks its drift), sanely
-governed (read/honor that spec), or over-owned (> maxOwners — split the file). --actionable
-prints NOTHING unless action is needed (hook use): only uncovered / over-owned fire.`,
-    see: 'spex search (topic → node) · spex lint (coverage over the whole tree)',
-  },
-  tree: {
-    line: 'tree                  the graph as a human-readable tree (status-coloured, badges)',
-    body: `Usage: spex tree [--node <id>] [--depth N] [--json]
-
-Prints the assembled spec graph as an indented tree — the CLI twin of the dashboard's tidy-tree,
-built from the same board (merged tree + worktree overlay). One line per node: id, derived status
-(coloured when stdout is a tty; NO_COLOR respected — the status word always prints), title, and
-attention badges: drift:N (drifted files), stale:N (yatsu scenarios whose latest reading aged),
-issues:N (open issues), ghost (being added by a worktree).
-  --node <id>   render just that subtree (unknown id fails loud)
-  --depth N     limit levels below the shown root; prunes are counted, never silent
-  --json        the same filtered subtree as nested objects, badge counts precomputed`,
-    see: 'spex board (the full flat JSON payload) · spex search (find one node by intent)',
-  },
-  board: {
-    line: 'board                 dump the assembled board as JSON (tree · overlay · sessions)',
-    body: `Usage: spex board
+const ROUTING_NOTE = `Backend routing: every backend-touching verb accepts --api <url> (--port <n> = localhost sugar) to name
+its backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
+recorded backend / fallback / :8787 (spex guide settings → BACKEND ROUTING).`
 
-Prints the full dashboard board state as JSON — the merged spec tree, per-worktree overlay, and the
-session list. Identical to GET /api/board; needs the backend (spex serve) reachable.`,
-    see: 'spex tree (the same graph, human-readable) · spex ls (just the sessions, as a table) · spex search (find one node instead of dumping all)',
-  },
-  guide: {
-    line: 'guide [topic]         the manuals: setup workflow · spec/yatsu file formats · spexcode.json · footprint',
-    body: `Usage: spex guide            the human setup workflow (install once, adopt a repo, serve)
-       spex guide spec       the spec.md file format + every lint rule
-       spex guide yatsu      the yatsu.md scenario format + how loss is measured and filed
-       spex guide config     every spexcode.json / spexcode.local.json field, and which file it belongs in
-       spex guide footprint  the footprint model: never-tracked artifacts, exclude + content filter, anchors
+const DOT_NOTE = `\`.\` as a node argument means the node THIS worktree works on (the session's bound node, else the
+node/<id> branch). One-shot payload reads (graph · spec search · session ls/show/review · eval ls ·
+scenario ls · issue ls/show/links) take --json.`
 
-guide is the SKILL layer — workflows and formats. Command usage lives here in help
-(\`spex help <cmd>\`); guide carries what the commands assume you know.`,
-  },
-
-  // ── author & verify (worker loop) ─────────────────────────────────────────
-  lint: {
-    line: 'lint                  check the spec↔code graph (integrity·living·altitude·coverage·drift·owners)',
-    body: `Usage: spex lint
-
-Checks the whole graph and exits non-zero on errors (or a blocked commit-local drift gate):
-  integrity (error)  a code:/related: path doesn't exist
-  living    (error)  a body accretes a "## vN" changelog instead of staying current-state
-  altitude  (warn)   a body slid below contract altitude into a mechanics dump
-  coverage  (warn)   a governed source file no node claims yet
-  drift     (warn)   a governed file changed after its spec's last version
-  owners    (warn)   a file governed by more than maxOwners nodes — split it
-When run from the pre-commit hook, a staged commit touching a heavily-drifted node BLOCKS
-(bypass: SPEXCODE_SKIP_LINT=1); CI/manual runs are advisory beyond errors.`,
-    see: 'spex guide spec (each rule explained) · spex ack (drift that is mechanics-only)',
-  },
-  ack: {
-    line: 'ack <node>… --reason  stamp Spec-OK on HEAD: this change keeps those specs valid',
-    body: `Usage: spex ack <node-id>… --reason "<why the contract still holds>"
-
-Amends HEAD with a Spec-OK trailer per node — the drift remedy when only MECHANICS changed and the
-spec's contract still holds. --reason is required (it forces the check) but NOT stored; git keeps
-only the trailer. If the intent DID change, edit the spec instead — same commit as the code.`,
-    see: 'spex lint (where drift is reported) · spex guide spec (drift remedies)',
-  },
-  yatsu: {
-    line: 'yatsu <sub>           measure a node’s scenarios & file the loss signal: scan | eval | retract | show | clean',
-    body: `Usage: spex yatsu scan [--changed]                       list nodes/scenarios missing readings
-       spex yatsu eval [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>]
-                       [--image <png> …] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
-       spex yatsu retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
-       spex yatsu show [.|<node>] [--json]              readings history for a node
-       spex yatsu clean [--keep-latest | --all]         prune stored readings
-
-Files a reading of a scenario against its expected — the loss signal the optimizer reads. Measure
-through the REAL product surface (run it, drive a browser, capture), never by reasoning about
-the code. Evidence kind follows the behaviour: MOVING/timed behaviour (scroll, animation,
-playback, a multi-step flow) records a \`--video\`; a STATIC end state screenshots \`--image\`;
-backend/CLI files a \`--result\` transcript. A fix's proof is a fail→pass pair on the SAME
-scenario. \`retract\` is the sanctioned undo for a botched filing: it APPENDS a retraction
-event (traceable, never deletes a line).`,
-    see: 'spex guide yatsu (yatsu.md format + evidence rules) · spex blob (stash evidence bytes)',
-  },
-  blob: {
-    line: 'blob put|get          evidence bytes ⇄ content hash: put stashes & prints the hash, get reads back',
-    body: `Usage: spex blob put <file|->
-       spex blob get <hash> [-o <file>]
-
-put writes bytes into the shared content-addressed evidence cache and prints the hash — transport
-only, no reading filed. Use the hash with --evidence on issues/remarks; re-putting the same content
-restores a pruned or cloned-away blob.
-
-get is the symmetric read: hash in, bytes out. Local cache first (no backend needed — the evidence
-is usually on this disk), then the backend's /api/yatsu/blob/:hash on a local miss; both missing
-fails loud naming each path. Bytes go to stdout by default (pipe-friendly); -o writes a file.`,
-    see: 'spex yatsu eval (file a reading with evidence) · spex issues open --evidence <hash>',
-  },
-  issues: {
-    line: 'issues …              THE issue surface: one merged local+forge list, plus all write verbs',
-    body: `Usage: spex issues                                        the merged read (local + forge, store-tagged)
-                  [--node <id>] [--store local|github] [--all] [--json]
-       spex issues open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]
-       spex issues reply <id> --body -|<text> [--evidence <hash>…]     (routes by the issue's store)
-       spex issues close <id>             close by the issue's store: local lands, forge closes remote
-       spex issues promote <id>           move an OPEN local issue to the forge (one recorded action)
-       spex issues on|off|status          toggle/inspect the local-issue workflow
-
-Bare \`spex issues\` is the drain view a supervisor reads. \`open\` welcomes taste, annotations, and
-off-mainline smells — not only bugs; \`--store <host>\` opens straight on the forge (the same port the
-dashboard's New form uses). \`close\` and \`reply\` route by the issue's store — one verb, local or forge,
-the same routing as the dashboard. (\`nudge\` exists but is fired by the post-merge hook, not typed.)
-Mentions: @session · [[node]] work in any concern/body — CLI args included. [[node]] links the topic
-node (it also tags the issue, like --node); @session hands the text to that live agent; @new spawns
-a fresh worker on the thread's node.`,
-    see: 'spex remark (pin a resolvable concern to an issue or scenario) · spex forge (trace forge → nodes)',
-  },
-  remark: {
-    line: 'remark / resolve / retract   pin a resolvable concern to a host; a peer resolves, the author retracts',
-    body: `Usage: spex remark <issue-id | <node> --scenario <name>> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]
-       spex resolve <remark-ref>          (the <thread-id>#<rid> that \`spex remark\` printed)
-       spex retract <remark-ref>
-
-The resolvable interaction primitive: pin a concern to a HOST — a local issue or a yatsu scenario —
-that a second agent can \`resolve\` and the author can \`retract\`. The whole loop is CLI-first; the
-dashboard adds no capability.`,
-    see: 'spex issues (the hosts) · spex yatsu show (scenario hosts)',
-  },
-  forge: {
-    line: 'forge <sub>           read-only trace of forge issues/PRs onto spec nodes: links | eval-pending',
-    body: `Usage: spex forge links        [--host github] [--node <id>] [--json]
-       spex forge eval-pending [--host github] [--node <id>] [--json]
-
-Resolves a forge's open issues/PRs to the spec nodes they serve (the Spec: marker in an issue body;
-a node/<id> branch links its PR for free). Read-only — git/.spec stays the single source of truth.`,
-    see: 'spex issues (the merged read that includes forge threads)',
-  },
-  // ── dispatch & manage sessions (manager loop) ─────────────────────────────
-  new: {
-    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--prompt-file <path>|-] [--node <id>] [--launcher <name>]',
-    body: `Usage: spex new "<task prompt>" [--node <id>] [--launcher <name>]
-       spex new --prompt-file <path>|- [--node <id>] [--launcher <name>]
-
-Creates a session: node branch + worktree + a launched agent carrying your prompt (= session new).
-Give it ONLY its task — the dev-flow contract reaches it through the materialized system prompt.
---node <id> (or the prompt's first [[id]] mention, same effect) binds the session to that node:
-branch name node/<id>-<shortid>, board attribution, and one appended line with the node's spec.md
-path when the node exists. With neither, the session is bound to no node.
---prompt-file <path> reads the prompt from a file (- = stdin), so a long multi-paragraph prompt never
-fights shell quoting; it is exclusive with the inline prompt (both given = error), and an unreadable
-or empty file refuses the launch.
-The launcher name selects both the agent harness and the command/auth profile (built-ins: claude, codex);
-omitting it requires sessions.defaultLauncher in spexcode.json or spexcode.local.json.
-Routes through the running backend (auth env + concurrency cap); prints the created session JSON.
-Then MONITOR it: background \`spex wait <id>\`, or \`spex watch\` for the whole stream.
-Talk to it with \`spex send <id> "<msg>"\` — never raw tmux keystrokes.`,
-    see: 'spex wait / spex watch (monitor) · spex send (talk to it) · spex review (when it proposes) · ' + SEL_NOTE.split('\n')[0],
-  },
-  ls: {
-    line: 'ls [SEL…]             living-sessions table  [--status a,b] [--json] [--api URL]',
-    body: `Usage: spex ls [SEL…] [--status a,b] [--json] [--api <url> | --port <n>]
-
-One-shot table of living sessions and their states, from the resolved backend — bare \`spex ls\` in a
-project's tree hits THAT project's live backend; --api <url> (or --port <n>) points it anywhere,
-including a remote machine's. ${SEL_NOTE}
-${ROUTING_NOTE}`,
-    see: 'spex watch (the live stream) · spex wait (block on one session)',
-  },
-  watch: {
-    line: 'watch [SEL…]          stream actionable transitions — NEVER EXITS; background it, never block on it',
-    body: `Usage: spex watch [SEL…] [--as NAME] [--status a,b] [--idle] [--interval N=5]
-
-Streams session lifecycle transitions (launched → review/done/offline/error/needs-input → closed)
-until killed. It NEVER EXITS — it is the human's forever stream. An agent must background it or use
-\`spex wait <SEL>\` (one-shot) instead; blocking a turn on watch freezes you. Watching draws a
-supervision edge on the session graph and greets the watched sessions once.
-${SEL_NOTE}`,
-    see: 'spex wait (the one-shot, guaranteed-to-exit counterpart)',
-  },
-  wait: {
-    line: 'wait <SEL>            block until <SEL> is actionable, print the status, exit',
-    body: `Usage: spex wait <SEL> [--timeout S=1200] [--interval S=2] [--idle]
-
-Blocks until the session reaches an actionable status, prints it, and EXITS — the supervisor's
-per-worker monitor (background one wait per worker; the exit is your wake-up). Guaranteed to
-terminate: --timeout is the hard wall (exit 1); a vanished session exits 2; a down backend fails
-loud (exit 1), never a false timeout. Draws the watcher→worker edge for the whole wait.
-${SEL_NOTE}`,
-    see: 'spex watch (the forever stream) · spex review (what to run when it prints review/done)',
-  },
-  review: {
-    line: 'review <SEL>          manager cockpit: ahead · merge-base diff · gates · proposal  [--json]',
-    body: `Usage: spex review <SEL> [--json]
-
-The ONE review payload for a session: commits ahead of the trunk, uncommitted files, its proposal,
-the gates (conflicts with the trunk, lint), and the merge-base diff — decide from this, don't
-hand-run git. The MEASURED side of the decision is \`spex eval <SEL>\`: the changed nodes' eval
-readings, and (--export) the self-contained HTML export.
-${SEL_NOTE}`,
-    see: 'spex eval (the session’s measured loss) · spex merge (act on an approved review)',
-  },
-  eval: {
-    line: 'eval <SEL>            the session’s eval readings: its changed nodes’ measured loss  [--export]',
-    body: `Usage: spex eval <SEL> [--json]
-       spex eval <SEL> --export [--open | --out <path> | --json]
-
-The session's evaluation, read from the backend (the dashboard Eval tab's CLI twin): every spec node
-the session's diff touches, each DECLARED scenario at its CURRENT score (latest reading, rooted at
-the session's worktree). Blind spots lead (declared, never measured — the outstanding loss), then
-the session's OWN measurements ✦-marked, then the inherited baseline (other sessions' latest
-readings) under an explicit divider. A frontend change with no yatsu.md is flagged, never hidden.
---export writes the evaluation as ONE self-contained HTML artifact instead (diff · evidence
-inlined · gates; --json = the model) for CI/sharing. (\`spex review proof\` is its deprecated alias.)
-This is the READ; filing a reading stays \`spex yatsu eval\`.
-${SEL_NOTE}`,
-    see: 'spex review (gates + diff — the merge decision) · spex yatsu eval (FILE a reading, the write verb)',
-  },
-  merge: {
-    line: 'merge <SEL>           gated merge into the trunk — dispatched to the session’s own agent',
-    body: `Usage: spex merge <SEL>
-
-Dispatches the merge to the session's OWN agent (it knows the work's intent and resolves conflicts);
-the server never touches the trunk's tree. Gates re-check first. After it lands, confirm HEAD
-advanced before closing the session — closing an unmerged branch discards the work.
-Mutating verbs are PROJECT-BOUND: a backend serving another project's repo refuses the write loudly
-(name the target with --api <url> to write cross-project on purpose).
-${SEL_NOTE}`,
-    see: 'spex review (before) · spex session close (after the merge is confirmed)',
-  },
-  session: {
-    line: 'session <sub>         every session verb answers here: new·ls·watch·wait·review·merge·reopen·done·park·ask·exit·close·send·capture·attach·rename·rawkey·prompt',
-    body: `Worker verbs (declare YOUR OWN state — a claim the board and your supervisor act on):
-  spex session done --propose merge|nothing|close [--note T]   committed and stopping; merge = ready for review
-  spex session park --note <what-you-await>                    a real background task will wake you
-  spex session ask  --note <your-question>                     stopped on the human; resumes when they reply
-
-Manager verbs (control another session; all take SEL):
-  spex session send <SEL> "<msg>"      deliver a message (fail-loud: a dead dispatch exits non-zero)
-  spex session capture <SEL>           the live pane as text
-  spex session rename <SEL> "<name>"   set the display name ("" clears; the right-click rename, as a verb)
-  spex session rawkey <SEL> "<keys>"   raw nav keys to a TUI dialog, in strike order (e.g. "Up Up Enter";
-                                       named keys · single chars · C-/M-/S- combos; fail-loud)
-  spex session prompt <SEL>            the session's originating prompt
-  spex session reopen <SEL> [--force]  relaunch ONLY if confirmed offline (--force for a wedged live one)
-  spex session exit <SEL>              soft stop: kill the agent, KEEP the worktree (resumable)
-  spex session close <SEL>             retire the session and its worktree
-
-Promoted verbs — they answer in this drawer too (same verb, either drawer):
-  spex session new|ls|watch|wait|review|merge …   ≡   spex new|ls|watch|wait|review|merge …
-And the reverse holds for every sub above: it also answers bare at the top level
-(spex send <SEL> "…" ≡ spex session send <SEL> "…"). One implementation, two spellings —
-you never have to guess which drawer a session verb lives in.
+const MENTION_NOTE = `Mentions: @session · [[node]] · @new work in ANY prompt, issue, or remark body — text passed as a CLI
+arg included. [[node]] names the topic node; @session hands the text to that live agent; @new spawns a
+fresh worker on the thread's node.`
 
-Human escape hatch:
-  spex session attach <SEL>            sit in the worker's REAL tmux (detach: C-b d; the session keeps
-                                       running). INTERACTIVE AND BLOCKING — like watch, an agent must
-                                       NEVER run it in a turn (it freezes you): use capture/send/rawkey.
-                                       LOCAL-only — the tmux server is the backend machine's, so it fails
-                                       loud when the resolved backend is remote. Offline session → loud.
-
-Mentions: @session · [[node]] work in ANY prompt, issue, or remark body — text passed as a CLI arg
-included. [[node]] names the topic (a new session derives its node from the prompt's first one);
-@session hands the surrounding text to that live agent; @new dispatches a fresh worker.
-
-(state · fail · idle · commit-gate also exist but are hook-driven — the lifecycle hooks call them;
-never type them.) ${SEL_NOTE}
-Manager verbs that WRITE (send/rename/rawkey/reopen/exit/close) are PROJECT-BOUND: a backend serving
-another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.
-${ROUTING_NOTE}`,
-    see: 'spex new (launch) · spex wait/watch (monitor) · spex review/merge (land)',
+const ENTRIES: Record<string, Entry> = {
+  // ── project verbs (implicit object = this project) ────────────────────────
+  graph: {
+    line: 'graph                 the assembled view: bare = readable tree · --json = the full payload',
+    body: `Usage: spex graph [--focus <id>] [--depth N] [--json]
+
+The ONE assembled view — merged spec tree + worktree overlay + sessions. Bare it renders the
+status-coloured tree (coloured when stdout is a tty; NO_COLOR respected), one line per node: id,
+derived status, title, and attention badges (drift:N · stale:N · issues:N · ghost).
+  --focus <id>  render just that subtree (unknown id fails loud)
+  --depth N     limit levels below the shown root; prunes are counted, never silent
+  --json        the full payload (tree · overlay · sessions), identical to GET /api/graph — machine
+                food; with --focus/--depth it is that filtered subtree as nested objects instead`,
+    see: 'spex spec search (find one node by intent) · spex session ls (just the sessions, as a table)',
   },
-
-  // ── install & serve (operator) ────────────────────────────────────────────
   init: {
     line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
     body: `Usage: spex init [dir=cwd] [--preset default|careful]
 
-Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .config plugins), plants
+Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plugins plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
-shims). Additive — never overwrites your files. --preset picks the .config plugin tier (cumulative).
+shims). Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
 Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
 a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
-    see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex lint (adoption TODO)',
-  },
-  uninstall: {
-    line: 'uninstall [dir]       surgical inverse of init — removes generated artifacts, keeps your .spec  [--hooks]',
-    body: `Usage: spex uninstall [dir=cwd] [--hooks]
-
-Removes every SpexCode-GENERATED artifact (harness shims · contract blocks · trust entries ·
-exclude/ignore blocks · global store · plugin bundle) and never your .spec/.config data or your own
-prose. Git hooks are preserved unless --hooks.`,
-    see: 'spex init (re-adopt later — your .spec survives)',
+    see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)',
   },
   materialize: {
     line: 'materialize           re-materialize the harness artifacts (contract block · shims) for cwd’s project',
     body: `Usage: spex materialize
 
-Materializes the surface:system config nodes into the managed <!-- spexcode --> block of
+Materializes the surface:system plugin nodes into the managed <!-- spexcode --> block of
 CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. The materialize anchors on
 git-native events only (init · this verb · session-worktree creation · the pre-commit/post-checkout/
 post-merge hooks) — run it by hand after a toolchain update, or in the setup step of any clone that
@@ -348,118 +67,304 @@ never arrive via git.`,
     see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
-    line: 'doctor                diagnose whether the workflow actually reaches this agent — per-layer, per-harness',
-    body: `Usage: spex doctor             per-layer coverage report: preconditions · git-hook floor · contract ·
-                               hooks + handler existence · backend — for every harness materialize delivers to
-       spex doctor contract    print the composed surface:system text any agent here reads
-       spex doctor conflicts   detect double-delivery (loose artifacts beside the managed ones)
+    line: 'doctor                diagnose whether the workflow actually reaches this agent  [--contract|--conflicts]',
+    body: `Usage: spex doctor                per-layer coverage report: preconditions · git-hook floor · contract ·
+                                  hooks + handler existence · backend — for every harness materialize delivers to
+       spex doctor --contract     print the composed surface:system text any agent here reads
+       spex doctor --conflicts    detect double-delivery (loose artifacts beside the managed ones)
 
 Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
 repair, instead of you diffing materialized files by hand.`,
     see: 'spex materialize (re-materialize the artifacts doctor checks)',
   },
+  uninstall: {
+    line: 'uninstall [dir]       surgical inverse of init — removes generated artifacts, keeps your .spec  [--hooks]',
+    body: `Usage: spex uninstall [dir=cwd] [--hooks]
+
+Removes every SpexCode-GENERATED artifact (harness shims · contract blocks · trust entries ·
+exclude/ignore blocks · global store · plugin bundle) and never your .spec/.plugins data or your own
+prose. Git hooks are preserved unless --hooks.`,
+    see: 'spex init (re-adopt later — your .spec survives)',
+  },
   serve: {
-    line: 'serve                 run the API backend (default :8787)  [--port N] [--public --password pw]',
-    body: `Usage: spex serve [--port N=8787]
-       spex serve --public --password <pw> [--tls-cert F --tls-key F] [--http]
-
-Runs the backend for the repo at cwd behind a zero-downtime supervisor (hot-reloads on source
-change; the public port never gaps). --port pairs with \`spex dashboard --api-port\`, so many
-projects coexist on one host. On a successful bind it RECORDS its endpoint in the per-project
-runtime tier — that's how a bare \`spex\` run from this project's tree finds this backend (see
-spex guide config → BACKEND ROUTING). --public exposes it on a public IP behind a password +
-self-signed TLS (own cert via --tls-cert/--tls-key; --http drops TLS).`,
-    see: 'spex dashboard (the UI on top) · GET /health (liveness probe)',
+    line: 'serve [api|ui]        api (default) = the backend :8787 · ui = the dashboard :5173 on top of it',
+    body: `Usage: spex serve [api] [--port N=8787]
+       spex serve [api] --public --password <pw> [--tls-cert F --tls-key F] [--http]
+       spex serve ui [--port N=5173] [--api-port N=8787] [--host H=127.0.0.1]
+
+\`serve\` (or \`serve api\`) runs the backend for the repo at cwd behind a zero-downtime supervisor
+(hot-reloads on source change; the public port never gaps). On a successful bind it RECORDS its
+endpoint in the per-project runtime tier — that's how a bare \`spex\` run from this project's tree
+finds this backend (spex guide settings → BACKEND ROUTING). --public exposes it on a public IP behind
+a password + self-signed TLS (own cert via --tls-cert/--tls-key; --http drops TLS).
+
+\`serve ui\` is a SEPARATE process: it serves the bundled dashboard on its own port and proxies /api +
+the terminal socket to a running backend (--api-port pairs with the backend's --port, so many
+projects coexist on one host). Loopback-only by default; --host 0.0.0.0 opens it to a LAN/tailnet —
+still plain HTTP with no gate, so bind wide only on a network you trust.`,
+    see: 'GET /health (backend liveness probe)',
+  },
+
+  // ── the noun drawers ──────────────────────────────────────────────────────
+  spec: {
+    line: 'spec <verb>           the governance graph: search · owner · lint · ack',
+    body: `Usage: spex spec search <query…> [--limit N=10] [--json]
+       spex spec owner <path> [--actionable]
+       spex spec lint
+       spex spec ack <node-id>… --reason "<why the contract still holds>"
+
+search — which spec node GOVERNS a topic, ranked by user-story relevance (which surfaces user-facing
+behaviour a code-grep misses). Run it BEFORE touching code: the node's spec.md body is the current
+contract. The corpus is English — query in English.
+
+owner — the reverse edge: a file's GOVERNORS (code: — drives drift + eval freshness) and REFERENCERS (related:
+— coverage only), with the verdict spelled out (uncovered / related-only / sanely governed /
+over-owned → split the file). --actionable prints NOTHING unless action is needed (hook use).
+
+lint — checks the whole spec↔code graph and exits non-zero on errors (or a blocked commit-local
+drift gate). Errors: integrity (a code:/related: file does not exist) · one-govern (a node governs >1
+file) · living (a "## vN" changelog heading) · id-format (an id char outside the whitelist — ascii
+[a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a leaf id
+reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift ·
+related-drift · owners · confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
+contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
+
+ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
+and the spec's contract still holds. --reason is required but NOT stored. If the intent DID change,
+edit the spec instead — same commit as the code.`,
+    see: 'spex guide spec (the file format + every lint rule) · spex graph (browse the whole tree)',
+  },
+  session: {
+    line: 'session <verb>        the worktree state machine: new · ls · watch · wait · review · merge · send · …',
+    body: `Manager verbs (dispatch, monitor, land):
+  spex session new "<prompt>" [--prompt-file <path>|-] [--node <id>] [--launcher <name>]
+      Launch a worker in its own node worktree. Give it ONLY its task — the dev-flow contract
+      reaches it through the materialized system prompt. --node (or the prompt's first [[id]],
+      same effect) binds the session to that node. --prompt-file <path>|- carries a long prompt
+      without shell quoting (exclusive with the inline prompt). Then MONITOR it (wait/watch below).
+  spex session ls [SEL…] [--status a,b] [--json]        one-shot table of living sessions
+  spex session watch [SEL…] [--as NAME] [--idle] [--interval N=5]
+      Streams lifecycle transitions until killed — it NEVER EXITS; the human's forever stream. An
+      agent must background it or use wait; blocking a turn on watch freezes you.
+  spex session wait <SEL> [--timeout S=1200] [--interval S=2] [--idle]
+      EDGE-TRIGGERED sleep on one session — ALWAYS run it in the BACKGROUND; its exit is your wake-up.
+      Prints the session's current status immediately (stderr), then exits 0 only when it OBSERVES
+      the session TRANSITION from a non-actionable status into an actionable one, printing the
+      observed path on stdout (e.g. working→review — read the LAST token as the status reached).
+      USE IT to sleep until a dispatched worker next needs you — including a dispatched MERGE
+      actually landing (review→working while the merge runs, then the edge back is your wake-up).
+      It NEVER returns just because the session is actionable ALREADY — for "what is it right NOW"
+      use \`session ls\` / \`session review\` instead. --timeout is the guaranteed exit (code 1,
+      observed path on stderr). Background one wait per worker.
+  spex session review <SEL> [--json]     the merge cockpit: ahead · uncommitted · proposal · gates ·
+                                         merge-base diff — decide from this, don't hand-run git
+  spex session merge <SEL>               gated merge, dispatched to the session's OWN agent; confirm
+                                         HEAD advanced before closing — closing unmerged discards work
+
+Control another session (all take SEL):
+  spex session send <SEL> "<msg>"        deliver a message (fail-loud: a dead dispatch exits non-zero)
+  spex session send <SEL> --keys "<keys>"
+      LAST RESORT: raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw
+      key surface is UNSTABLE and can confirm dangerous dialogs — don't reach for it unless a plain
+      \`session send\` text provably cannot land.
+  spex session rename <SEL> "<name>"     set the display name ("" clears)
+  spex session show <SEL> [--capture] [--json]
+      The session record: status · node · branch · launcher · the full originating prompt.
+      --capture prints the LIVE PANE as text instead (empty pane = exit 0; unknown session = exit 2).
+  spex session resume <SEL> [--force]    relaunch ONLY if confirmed offline (--force for a wedged one)
+  spex session stop <SEL>                soft stop: kill the agent, KEEP the worktree (resumable)
+  spex session close <SEL>               retire the session and its worktree
+
+Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on):
+  spex session done --propose merge|nothing|close [--note T]   committed and stopping
+  spex session park --note <what-you-await>                    a real background task will wake you
+  spex session ask  --note <your-question>                     stopped on the human; resumes on reply
+
+Human escape hatch:
+  spex session attach <SEL>              sit in the worker's REAL tmux (detach: C-b d). INTERACTIVE
+                                         AND BLOCKING — an agent must NEVER run it in a turn: use
+                                         show --capture / send. LOCAL-only (fails loud on a remote backend).
+
+${SEL_NOTE}
+Manager verbs that WRITE (send/rename/resume/stop/close/merge) are PROJECT-BOUND: a backend serving
+another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.
+${MENTION_NOTE}`,
+    see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
+  },
+  eval: {
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · retract · clean',
+    body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
+                    [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
+       spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
+       spex eval ls --session <SEL> [--json]           a session's aggregate: its changed nodes' scores
+       spex eval ls --session <SEL> --export [--open | --out <path>]
+       spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; bare = every node
+       spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
+       spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
+       spex eval clean [--keep-latest | --all]         GC the content-addressed evidence cache
+
+add — file an eval of a scenario against its expected: the loss signal the optimizer reads.
+Measure through the REAL product surface, never by reasoning about the code. Evidence kind follows
+the behaviour: MOVING/timed behaviour records a --video; a STATIC end state screenshots --image;
+backend/CLI files a --result transcript. A fix's evidence is a fail→pass pair on the SAME scenario.
+
+ls — node-scoped bare (its per-scenario eval history); session-scoped with an EXPLICIT --session
+(never type-sniffed): every node the session's diff touches, blind spots first, its OWN measurements
+✦-marked ahead of the inherited baseline. --export writes that evaluation as ONE self-contained
+HTML artifact (diff · evidence inlined · gates) for CI/sharing.
+
+scenario ls — the DECLARED contracts (name · tags · latest verdict), no evals: bare lists every
+measurable node's scenarios; --unmeasured keeps only the never-measured — the blind-spot worklist.
+
+lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
+stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source with no eval.md
+(eval-coverage — the same name and shape as spec lint's coverage, one rule per layer) · over-owned
+files (eval-owners). --changed scopes to the nodes THIS branch touched. spec lint's errors block
+commits; eval lint is PURE ADVISORY, always exit 0 — a measurement gap never blocks anyone.
+
+retract — the sanctioned undo for a botched filing: APPENDS a retraction event (traceable, never
+deletes a line); the previous eval becomes latest again, or the scenario honestly returns to
+unmeasured.
+
+${DOT_NOTE}`,
+    see: 'spex guide eval (the eval.md scenario format + evidence rules) · spex evidence (bare byte transport)',
+  },
+  issue: {
+    line: 'issue <verb>          concern threads, local + forge merged: ls · show · open · reply · close · promote · links',
+    body: `Usage: spex issue ls [--node <id>] [--store local|<host>] [--all] [--json]
+       spex issue show <id> [--json]
+       spex issue open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]
+       spex issue reply <id> --body -|<text> [--evidence <hash>…]
+       spex issue close <id>
+       spex issue promote <id>
+       spex issue links [--pending] [--store <host>] [--node <id>] [--json]
+
+ls is the drain view a supervisor reads: ONE store-tagged list, local + forge interleaved by
+creation time. \`show <id>\` is the single-thread detail — the whole thread with its replies (a local
+id, or a forge id like github#12). \`open\` welcomes taste, annotations, and off-mainline smells —
+not only bugs; --store <host> opens straight on the forge. \`reply\` and \`close\` route by the
+issue's store — one verb, local or forge. \`promote\` moves an OPEN local issue to the forge as one
+recorded action. \`links\` is the read-only forge trace: which open forge issues/PRs serve which
+spec node (--pending narrows to threads still awaiting an eval). The issues workflow's
+on/off switch is the \`issues.enabled\` key in spexcode.json (no CLI toggle verb — edit the JSON;
+\`spex doctor\` reports its state).
+${MENTION_NOTE}`,
+    see: 'spex remark (pin a resolvable concern to an issue or scenario) · spex evidence put (stash evidence bytes)',
+  },
+  remark: {
+    line: 'remark <verb>         resolvable pins on a host: add · resolve · retract',
+    body: `Usage: spex remark add <issue-id | <node> --scenario <name>> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]
+       spex remark resolve <ref>          (the <thread-id>#<rid> that \`spex remark add\` printed)
+       spex remark retract <ref>
+
+The resolvable interaction primitive: \`add\` pins a concern to a HOST — a local issue, or a scenario
+(\`--scenario\` present ⇒ the positional is a node; otherwise it is an issue id — the flag decides,
+never type-sniffing). A SECOND agent \`resolve\`s it (never the author); the AUTHOR \`retract\`s their
+own. The whole loop is CLI-first; the dashboard adds no capability.`,
+    see: 'spex issue (the thread hosts) · spex eval ls (scenario hosts)',
+  },
+  evidence: {
+    line: 'evidence put|get      content-addressed bytes: put stashes & prints the hash, get reads back',
+    body: `Usage: spex evidence put <file|->
+       spex evidence get <hash> [-o <file>]
+
+put writes bytes into the shared content-addressed evidence cache and prints the hash — transport
+only, no eval filed. Use the hash with --evidence on issues/remarks; re-putting the same content
+restores pruned or cloned-away evidence.
+
+get is the symmetric read: hash in, bytes out. Local cache first (no backend needed — the evidence
+is usually on this disk), then the backend on a local miss; both missing fails loud naming each
+path. Bytes go to stdout by default (pipe-friendly); -o writes a file.`,
+    see: 'spex eval add (file an eval WITH evidence) · spex issue open --evidence <hash>',
   },
-  dashboard: {
-    line: 'dashboard             serve the dashboard UI (default :5173), proxying /api to a running serve',
-    body: `Usage: spex dashboard [--port N=5173] [--api-port N=8787] [--host H=127.0.0.1]
-
-Serves the bundled dashboard on its own port and proxies /api + the terminal socket to a running
-\`spex serve\`. The installed replacement for the dev-only \`npm run web\`. Loopback-only by default;
---host 0.0.0.0 (or a specific interface) opens it to a LAN/tailnet — still plain HTTP with no gate,
-so bind wide only on a network you trust (for the internet, use \`spex serve --public\`).`,
-    see: 'spex serve (must be running first)',
+
+  // ── help & guide ──────────────────────────────────────────────────────────
+  guide: {
+    line: 'guide [topic]         the manuals: setup workflow · spec/eval file formats · spexcode.json · footprint',
+    body: `Usage: spex guide            the human setup workflow (install once, adopt a repo, serve)
+       spex guide spec       the spec.md file format + every lint rule
+       spex guide eval       the eval.md scenario format + how loss is measured and filed
+       spex guide settings   every spexcode.json / spexcode.local.json field, and which file it belongs in
+       spex guide footprint  the footprint model: never-tracked artifacts, exclude + content filter, anchors
+
+guide is the SKILL layer — workflows and formats. Command usage lives here in help
+(\`spex help <cmd>\`); guide carries what the commands assume you know.`,
   },
 
   // ── plumbing ──────────────────────────────────────────────────────────────
   internal: {
     line: '',   // deliberately not on the map
-    body: `Usage: spex internal <trunk | commit-surgery | refresh-footprint | codex-launch | codex-turn>
+    body: `Usage: spex internal <sub>
 
 Machine plumbing — called by generated hooks and launch scripts, never typed by a human or agent:
   trunk             print the resolved source-of-truth branch (the pre-commit main-guard captures it)
   commit-surgery    pre-commit footprint anchor: unconditional materialize + staged-index repair
   refresh-footprint quiet materialize — the post-checkout/post-merge freshness anchor
-  codex-launch  <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
-  codex-turn    <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
+  check-staged      pre-commit eval backstop: reject staged stray evidence files / malformed eval.md
+  session-state <st> --session <id>   a lifecycle hook authors the session's state
+  session-fail  --session <id>        the StopFailure hook marks the session errored
+  session-idle  --session <id>        the idle-prompt hook marks an active session idle
+  commit-gate       the Stop gate's deterministic commit check (exit 0 = ready to declare done)
+  nudge <node>      the post-merge hook prints the issue nudge for a merged node
+  codex-launch <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
+  codex-turn   <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
 
 If you reached for one of these by hand, the porcelain you want is probably elsewhere: the trunk
-name also lives at GET /api/layout; sessions are driven with spex new / session send.`,
+name also lives at GET /api/settings (.layout); sessions are driven with spex session new / session send;
+your own state is declared with spex session done|park|ask.`,
     see: 'spex help (the porcelain map)',
   },
   help: {
     line: '',
-    body: `Usage: spex help              the command map, grouped by the loop each verb serves
-       spex help <command>    one command's usage (same as spex <command> --help)
+    body: `Usage: spex help              the command map
+       spex help <command>    one command/drawer's usage (same as spex <command> --help)
        spex guide [topic]     the skill layer: workflows, file formats, best practice`,
   },
 }
 
-// `spex <cmd> --help` must meet the user wherever they typed it: sub-namespace tokens map to their
-// canonical entry, so \`spex session send --help\` and \`spex help session\` print the same text.
+// `spex <cmd> --help` must meet the user wherever they typed it: cli.ts intercepts the probe pre-verb and
+// asks for the FIRST token's entry, so `spex session send --help` answers with the session drawer's entry.
 export function commandHelp(name: string): string | null {
-  const key = ALIAS[name] ?? (name === 'resolve' || name === 'retract' ? 'remark' : name)
-  const e = ENTRIES[key]
+  const e = ENTRIES[name]
   if (!e) return null
   const oneLiner = e.line.replace(/^\S+(\s+\S+)*?\s{2,}/, '')   // the map line minus its "cmd args" column
-  const header = oneLiner ? `spex ${key} — ${oneLiner}\n\n` : ''  // unlisted entries (internal, help) lead with their own Usage
+  const header = oneLiner ? `spex ${name} — ${oneLiner}\n\n` : ''  // unlisted entries (internal, help) lead with their own Usage
   return `${header}${e.body}${e.see ? `\n\nsee also: ${e.see}` : ''}\n\nmap: spex help · skills: spex guide`
 }
 
 export function overviewHelp(): string {
   return `spex — SpexCode CLI (spec↔code graph + worktree session state machine)
 
-Usage: spex <command> [args]      one command's usage: spex help <command>  (or spex <command> --help)
-
-Find & read the graph
-  ${ENTRIES.search.line}
-  ${ENTRIES.owner.line}
-  ${ENTRIES.tree.line}
-  ${ENTRIES.board.line}
-  ${ENTRIES.guide.line}
+Usage: spex <noun> <verb> [object] [flags]     the verb is always the token after its noun;
+                                               a bare noun prints that drawer's help
+       spex help <command>                     one command's usage (or spex <command> --help — always
+                                               safe: a help probe never runs the verb)
 
-Author & verify (the worker loop)
-  ${ENTRIES.lint.line}
-  ${ENTRIES.ack.line}
-  ${ENTRIES.yatsu.line}
-  ${ENTRIES.blob.line}
-  ${ENTRIES.issues.line}
-  ${ENTRIES.remark.line}
-  ${ENTRIES.forge.line}
-
-Dispatch & manage sessions (the manager loop)
-  ${ENTRIES.new.line}
-  ${ENTRIES.ls.line}
-  ${ENTRIES.watch.line}
-  ${ENTRIES.wait.line}
-  ${ENTRIES.review.line}
-  ${ENTRIES.eval.line}
-  ${ENTRIES.merge.line}
-  ${ENTRIES.session.line}
-
-Install & serve (the operator loop)
+Project verbs (implicit object = this project)
+  ${ENTRIES.graph.line}
   ${ENTRIES.init.line}
-  ${ENTRIES.uninstall.line}
   ${ENTRIES.materialize.line}
   ${ENTRIES.doctor.line}
+  ${ENTRIES.uninstall.line}
   ${ENTRIES.serve.line}
-  ${ENTRIES.dashboard.line}
 
-${SEL_NOTE}
+Noun drawers
+  ${ENTRIES.spec.line}
+  ${ENTRIES.session.line}
+  ${ENTRIES.eval.line}
+  ${ENTRIES.issue.line}
+  ${ENTRIES.remark.line}
+  ${ENTRIES.evidence.line}
+
+Manuals
+  ${ENTRIES.guide.line}
 
-${ROUTING_NOTE}
+Conventions (stated once, hold everywhere)
+  ${SEL_NOTE.split('\n').join('\n  ')}
+  ${DOT_NOTE.split('\n').join('\n  ')}
+  ${ROUTING_NOTE.split('\n').join('\n  ')}
+  ${MENTION_NOTE.split('\n').join('\n  ')}
 
-Concepts & best practice live in the guide: spex guide (setup) · guide spec · guide yatsu · guide config.
+Concepts & best practice live in the guide: spex guide (setup) · guide spec · guide eval · guide settings · guide footprint.
 Machine plumbing (hook/launch-script callees) lives under \`spex internal\` — not part of your vocabulary.`
 }