@spexcode/spec-cli 0.6.5

package/dist/help.js

@@ -0,0 +1,574 @@
+// @@@ help journey - the CLI's three help layers, each pointing at the next so no probe dead-ends:
+//   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.
+const SEL_NOTE = `SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
+accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
+none (or @all) means every session.`;
+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). A password-gated explicit
+gateway accepts --password <pw> (or SPEXCODE_PASSWORD); its self-signed certificate needs explicit --insecure.`;
+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.`;
+const MENTION_NOTE = `Mentions: @session · [[node]] work in ANY prompt, issue, or remark body — text passed as a CLI arg included.
+[[node]] names a topic; @session names a retained session for the receiving agent to inspect, contact with
+\`spex session send\`, or inherit with \`/distill\`. Mentions are references only: they never send or spawn.`;
+// One definition feeds both the complete session drawer and exact `session <verb> --help` projections.
+// Keeping the behavioral prose here prevents a compact probe from becoming a second, drifting manual.
+function sessionHelpDefinitions() {
+    return {
+        new: [['spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]',
+                'spex session new --ssh <address> <FULL-SESSION-ID> "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]'],
+            `Launch a worker in its own node worktree. The materialized system contract reaches it
+automatically; the prompt supplies the task context. Its first [[id]] mention binds the
+session to that node. --prompt-file <path>|- carries a long prompt without shell quoting
+(exclusive with the inline prompt). --name sets the session's initial display name without changing the prompt.
+--base <commit-ish> pins the fork point instead of the source-of-truth branch's current head, so a run can be
+reproduced against a frozen commit; a base that names no commit is refused before anything is created.
+The successful receipt names what to read, monitor, and reply on. --ssh uses an existing gateway-to-gateway
+communication tunnel: its full id anchors the remote project, creation stays parentless and remote, and its
+prompt carries a runnable reply path over that same tunnel.`],
+        ls: [['spex session ls [SEL…] [--children[=<PARENT-SEL>]] [--status a,b] [--all] [--json]', 'spex session ls --ssh <address> <FULL-SESSION-ID> [--children=<PARENT-SEL>] [--status a,b] [--json]'],
+            'One-shot table of this project\'s live sessions, with each direct parent beside the row. --children scopes it to the caller\'s direct children; --children=<PARENT-SEL> names another parent without changing positional selector grammar. The heading summarizes the displayed scope by status. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it. An explicit id missing from the session list is diagnosed from terminal-close history: closed is a successful answer, while no live, archived, or closed history is a named miss. --ssh uses an existing gateway-to-gateway communication tunnel; its full id anchors one remote project rather than filtering the table, and archive projection stays unavailable on that peer route.', ['selector']],
+        resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
+        files: [['spex session files add <path>', 'spex session files ls', 'spex session files retract <path>'],
+            'Publish, list, or withdraw YOUR session’s live file paths. Posting stores an absolute path beside the session record without copying bytes; the dashboard downloads it only when the human clicks.'],
+        web: [['spex session web add <url>', 'spex session web ls', 'spex session web retract <url>'],
+            'Publish, list, or withdraw YOUR session’s live loopback web-service URLs. Posting records no bytes and does not contact the service; the dashboard proxies the current HTTP/WebSocket service only when the human opens its preview.'],
+        watch: [['spex session watch <SEL…>', 'spex session watch list', 'spex session watch cancel <SEL…>', 'spex session watch stream [SEL…] [--as NAME] [--idle] [--interval N=1]'],
+            'With a governed caller, watch registers durable send-backed state delivery and exits. list/cancel manage those relations. Without a governed caller it names the background `session wait` fallback. stream is the human-only continuous log view and blocks until killed.', ['selector']],
+        wait: ['spex session wait [SEL…] [--timeout S=1200] [--interval S=1] [--idle]',
+            `EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own log, and exits 0 on
+the FIRST thing worth waking for — a followed session TRANSITIONING from a non-actionable
+status into an actionable one (stdout = the observed path, e.g. working→review; read the LAST
+token as the status reached), or a message arriving for you (stdout = message). The arrival
+status is printed immediately on stderr but never returns it: it NEVER returns just because a
+session is actionable ALREADY — for "what is it right NOW" use \`session ls\` / \`session review\`.
+It reads files only, so it needs no \`spex serve\` and costs the sessions it follows nothing.
+--timeout is the guaranteed exit (code 1, observed path on stderr); code 2 = a followed
+session's store is gone.`, ['selector']],
+        review: ['spex session review <SEL> [--json]', 'Reports ahead · uncommitted · proposal · gates · merge-base diff.', ['selector']],
+        merge: ['spex session merge <SEL>', 'Dispatches a gated merge to the session\'s own agent; it does not close the session.', ['selector', 'project-bound']],
+        reparent: ['spex session reparent <child-SEL...> --to <parent-SEL>',
+            'Move one or more governed children to a replacement parent, replacing only the former parent\'s managed watch relation. It never restarts a child and works when the former parent is offline.', ['selector', 'project-bound']],
+        send: [['spex session send <SEL> "<msg>"', 'spex session send <SEL> [--api <url> | --port <n>] -- <option-shaped-msg>', 'spex session send --ssh <address> <FULL-SESSION-ID> "<msg>"', 'spex session send <SEL> --keys "<keys>"'],
+            `Plain send delivers a message once its timeline append succeeds; a dead adapter only delays its context. Routing flags may precede or follow ordinary text; use -- before a message that begins with --. --ssh uses an existing gateway-to-gateway communication tunnel and requires a full session id; no tunnel fails loud so an agent may run \`spex peer connect <address>\` then retry. --keys is the 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 — try a plain send first; use keys only when text
+provably cannot land.`, ['selector', 'project-bound']],
+        interrupt: ['spex session interrupt <SEL>', 'Hard-interrupt the current turn through native harness control.', ['selector', 'project-bound']],
+        rename: ['spex session rename <SEL> "<name>"', 'Set the display name; an empty name clears it.', ['selector', 'project-bound']],
+        show: [['spex session show <SEL> [--capture] [--json]', 'spex session show --ssh <address> <FULL-SESSION-ID> [--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). --ssh uses an
+existing gateway-to-gateway communication tunnel and requires a full session id; live-pane capture stays local.`, ['selector']],
+        resume: ['spex session resume <SEL> [--force]', 'Relaunch ONLY if confirmed offline; --force is for a wedged session.', ['selector', 'project-bound']],
+        stop: ['spex session stop <SEL>', 'Soft stop: kill the exact agent and KEEP the worktree resumable.', ['selector', 'project-bound']],
+        archive: ['spex session archive <SEL>', 'Cold-archive it: exact leaf/runtime stopped, worktree and conversation kept.', ['selector']],
+        unarchive: ['spex session unarchive <SEL>', 'Deprecated compatibility spelling: same behavior as resume, relaunching the same conversation.', ['selector']],
+        close: [['spex session close <SEL>', 'spex session close --ssh <address> <FULL-SESSION-ID>'], `Retire ANOTHER session — one you dispatched — deleting its worktree, branch and record.
+<SEL> names that session; it is never \`.\` and never your own id. Closing yourself deletes the worktree
+you are running in, mid-turn. Your own ending is a declaration: \`done --propose close\`. --ssh uses an existing
+gateway-to-gateway communication tunnel and requires a full session id.`, ['selector', 'project-bound']],
+        quarantine: ['spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <id> --worktree <absent-path> --branch <absent-branch> [--restore]',
+            'Move only an unreadable record after the backend proves every named residue absent. --thread is an adapter-native conversation id, never the SpexCode session id; omit it for Claude. Quarantine and --restore both require the original exact id because corrupt rows are outside selectors.', ['project-bound']],
+        done: ['spex session done --propose merge|nothing|close [--note T]',
+            '`merge` declares review: committed work ready for human review, and it is the ONLY declaration that offers a clickable merge. `nothing` is an intended trap: it writes no state and sends the agent to the true merge, close, ask, or park destination. `close` declares close-pending only for settled work: discardable worktree and no outstanding human decision, follow-up, or inspection. The human closes it. This declaration is how a session ends itself; never run `session close` on your own id.'],
+        park: ['spex session park --note <what-you-await>',
+            'Declare parked only when a managed watch delivery or real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.'],
+        ask: ['spex session ask --note <what-you-await>',
+            'Declare asking when a human reply, direction, or decision is needed, including a reported finding/recommendation, handoff, or posted-artifact inspection. It resumes only when the human replies; a background wake-up is parked instead.'],
+        attach: ['spex session attach <SEL>', `Attaches the current terminal to the worker's tmux (detach: C-b d) and blocks until detached.
+LOCAL-only (fails loud on a remote backend); show --capture and send are non-interactive.`, ['selector']],
+    };
+}
+const SESSION_HELP_GROUPS = [
+    { title: 'Manager verbs (dispatch, monitor, land)', verbs: ['new', 'ls', 'resources', 'watch', 'wait', 'review', 'merge', 'reparent'] },
+    { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'archive', 'unarchive', 'close', 'quarantine'] },
+    { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask', 'files', 'web'] },
+    { title: 'Human escape hatch', verbs: ['attach'] },
+];
+const SESSION_WRITE_NOTE = `Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
+another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.`;
+function indent(text, spaces) {
+    const prefix = ' '.repeat(spaces);
+    return text.split('\n').map((line) => `${prefix}${line}`).join('\n');
+}
+function sessionDrawerHelp() {
+    const definitions = sessionHelpDefinitions();
+    const groups = SESSION_HELP_GROUPS.map(({ title, verbs }) => `${title}:\n${verbs.map((verb) => {
+        const [rawUsage, detail] = definitions[verb];
+        const usages = typeof rawUsage === 'string' ? [rawUsage] : rawUsage;
+        return `${usages.map((usage) => `  ${usage}`).join('\n')}\n${indent(detail, 6)}`;
+    }).join('\n')}`).join('\n\n');
+    return `${groups}\n\n${SEL_NOTE}\n${SESSION_WRITE_NOTE}\n${MENTION_NOTE}`;
+}
+function sessionVerbHelp(verb) {
+    const entry = sessionHelpDefinitions()[verb];
+    if (!entry)
+        return null;
+    const [rawUsage, detail, sharedNotes = []] = entry;
+    const usages = typeof rawUsage === 'string' ? [rawUsage] : rawUsage;
+    const notes = [detail];
+    if (sharedNotes.includes('selector'))
+        notes.push(SEL_NOTE);
+    if (sharedNotes.includes('project-bound'))
+        notes.push(SESSION_WRITE_NOTE);
+    return `${usages.map((line, index) => `${index === 0 ? 'Usage: ' : '       '}${line}`).join('\n')}\n\n${notes.join('\n\n')}`;
+}
+const ENTRIES = {
+    // ── project verbs (implicit object = this project) ────────────────────────
+    graph: {
+        line: 'graph                 the assembled view: bare = readable tree · --json = full payload · --public = static graph snapshot',
+        body: `Usage: spex graph [--focus <id>] [--depth N] [--json] | spex graph --public [--out <path>] [--content-dir <path>]
+
+The normal assembled view is 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
+  --public      deterministic read-only Spec Graph payload; excludes sessions, issues, evals, and write state
+  --out <path>  write the public graph index to a file instead of stdout (only with --public)
+  --content-dir <path>  write one read-only spec document per node for a static host (only with --public)`,
+        see: 'spex spec search (find one node by intent) · spex session ls (just the sessions, as a table)',
+    },
+    init: {
+        line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  --harness <ids> [--preset name]',
+        body: `Usage: spex init [dir=cwd] --harness <id[,id]|plugin:<folder>> [--preset default]
+
+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). --harness is REQUIRED — the explicit choice of which harnesses materialize delivers into
+(stamped as spexcode.json "harnesses"; only their launchers are seeded); a pre-existing "harnesses"
+field satisfies it. 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 spec lint (adoption TODO)',
+    },
+    materialize: {
+        line: 'materialize           the base pass of harness adaptation: render .spec/.plugins into your harness’s artifacts',
+        body: `Usage: spex materialize
+
+The base operation of HARNESS ADAPTATION: one pass renders the spec tree's surface nodes into the
+artifacts each selected harness auto-discovers — the managed <!-- spexcode --> block of
+CLAUDE.md/AGENTS.md, the .claude/.codex shims, the skills/agents — and prints the content hash.
+The outputs are derived and never tracked: to change one, edit its source (.plugins, spexcode.json)
+and re-materialize — never the artifact. Not a one-time setup: it anchors on git-native events
+(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 has no spex-planted
+hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arrive via git.`,
+        see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
+    },
+    doctor: {
+        line: 'doctor                diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]',
+        body: `Usage: spex doctor                spec-health findings + delivery report: preconditions · git-hook floor ·
+                                  contract · hooks + handler existence · backend · footprint
+       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)
+
+Bare doctor is the opt-in, read-only health surface: it reports altitude and breadth findings without
+putting them in the lint gate, then audits workflow delivery. Run it directly or let the tidy workflow
+consume the same visible diagnosis.`,
+        see: 'spex spec lint (deterministic graph/contract gate) · spex materialize (repair delivery artifacts)',
+    },
+    flat: {
+        line: 'flat new|site|gallery Flatcode — flatten any repository into a converged .spec tree, then preview it',
+        body: `Usage: spex flat new <repo-url|path> [--out <dir>] [--launcher <name>] [--rounds <n>] [--coverage <pct>] [--lang <code>]
+       spex flat site <flat-dir>
+       spex flat gallery --out <dir> <flat-dir>…
+
+For a repository URL, clones the target into an isolated flat. For a local path, operates directly in that clean
+repository and adds only \`.spec\` work. A new local repository receives the ordinary \`.spec\` adoption seed;
+an initialized one retains its \`.spec\`, configuration, and launcher. It then runs an agent round after round
+until the spec tree passes a gate: zero \`spex spec lint\` errors, coverage at or above --coverage (default
+90%), with \`spex doctor\`'s altitude findings fed back as the next round's instructions. The agent saying it
+finished is not the signal — the measurement is.
+
+Rounds are bounded (--rounds, default 6). Exhausting the budget reports a PARTIAL flat naming what still
+fails and exits non-zero; it never reports a pass it did not measure.
+
+The product is a sibling \`<out>/flat.json\` result record. A URL flat additionally holds its clone at \`<out>/repo\`
+on the \`flatcode\` branch. A local flat commits only \`.spec\` in its source repository's current branch;
+Flatcode rejects a dirty repository and fails if the agent touches anything outside \`.spec\`. Nothing is pushed,
+nothing is served, and no session or project is registered.
+
+--launcher picks the agent exactly like a session does when the current directory already has launcher
+profiles. From a fresh directory, it accepts the built-in names \`claude\`, \`codex\`, \`opencode\`, or \`pi\` and
+uses that choice both for the conversion turn and for \`spex init\` on a new target. An initialized local
+project uses its own configured launcher. Without a configured default or --launcher, an interactive terminal
+asks which agent to use; a non-interactive call must pass --launcher. A launcher whose harness has no
+non-interactive turn is refused by name rather than quietly swapped.
+
+--lang <code> writes the spec PROSE in that language (\`--lang zh\`, \`--lang ja\`, or a spelled-out name):
+every node's title, desc and body, since a spec is written for whoever maintains that repository. Node ids
+stay lowercase ascii-kebab — they are directory names and part of URLs — and so do code paths and mentions.
+
+\`spex flat site <flat-dir>\` writes <flat-dir>/site — the graph-only dashboard over that flat's spec tree,
+plus the node documents, the .spec archive, and a release manifest with a SHA-256 per file. It is plain
+static files with no backend, so any static host serves it and a partial flat still previews (its About
+panel carries the coverage, so a partial tree never reads as a finished one). The directory is relocatable:
+it names everything relative to itself, so the same bytes serve from a domain root or any path prefix.
+
+\`spex flat gallery --out <dir> <flat-dir>…\` assembles many flats into one static tree — each flat's site at
+<out>/<owner>/<repo>/ (the slug comes from the source it read, not from your --out name), a self-contained
+index page listing them, and gallery.json naming every entry with a SHA-256 of its release manifest, so what
+landed on a host can be checked against what was built.`,
+        see: 'spex guide spec (the authoring format the rounds follow) · spex spec lint · spex doctor',
+    },
+    uninstall: {
+        line: 'uninstall [dir]       remove all derived artifacts + local state; preserve tracked intent  [--hooks]',
+        body: `Usage: spex uninstall [dir=cwd] [--hooks]
+
+Removes all SpexCode-derived wiring and project-local state: contract blocks, harness shims,
+generated skills/agents, plugin bundles, trust/filter/exclude entries, and the global per-project
+store. Your tracked intent (.spec including .plugins, plus spexcode.json) and surrounding user prose
+are preserved. Git hooks remain unless --hooks; that flag removes only unmodified canonical copies.`,
+        see: 'spex init (re-adopt later — your tracked intent survives)',
+    },
+    serve: {
+        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)',
+    },
+    dashboard: {
+        line: 'dashboard             ONE dashboard for every project you serve — no --api-port pairing  [--port N=5173]',
+        body: `Usage: spex dashboard [--port N=5173] [--host H=127.0.0.1]
+
+The HOST gateway: serves the built dashboard once and routes to EVERY backend the current user runs —
+the multi-project hub engine plus the host registry on top. It continuously reconciles the per-project
+endpoint records each \`spex serve\` publishes (validating each against the live backend's /api/instance
+identity), keeps a durable known-project catalog, and proxies each project's API + SSE + terminal
+socket under /p/<projectId>/* — the project is named in the path, so nothing is "current" and no
+pairing flag exists.
+
+Admin surface (hub-authorized: implicit from loopback until an admin password is set, then cookie
+sessions): GET /projects (the validated list + gating state) · GET /projects/stream (SSE) ·
+GET /projects/browse?path=… (read-only host folder picker) · POST /projects {root, initGit?, init?}
+(explicit setup, then register) · GET|PUT /projects/<id>/config (raw portable
+spexcode.json, revision-guarded) · POST /projects/<id>/init|doctor|serve
+(run the real \`spex init\`/\`spex doctor\`, or start an offline project's backend, detached — a
+backend never depends on this gateway staying up) · PUT|DELETE /projects/admin-password and
+/projects/<id>/password (the gates). A gated project answers /p/<id>/login with the designed page.
+
+Loopback-only by default; --host widens the bind — the admin surface stays locked to loopback until
+an admin password exists, and ungated projects serve open.`,
+        see: 'spex serve (each project\'s backend) · spex serve ui (explicit one-backend pairing)',
+    },
+    guidance: {
+        line: 'guidance              export the immutable guidance catalog index  [--out <path>]',
+        body: `Usage: spex guidance [--out <path>] [--json]
+
+Prints the deterministic, schema-versioned guidance index. Entries point at the authoritative active plugin,
+help, and guide sources with exact rendered content, content hashes, and git revision provenance. The derived
+effective system-contract view follows materialization order; no separate authoring source is created.
+--out writes the same bytes to a file instead of stdout.`,
+        see: 'spex help · spex guide (the source guidance surfaces)',
+    },
+    // ── the noun drawers ──────────────────────────────────────────────────────
+    peer: {
+        line: 'peer <verb>           gateway-owned SSH communication tunnels between machines',
+        body: `Usage: spex peer connect <SSH-ADDRESS>
+       spex peer ls [--json]
+       spex peer disconnect <SSH-ADDRESS>
+
+connect asks the local host gateway to own one bidirectional SSH tunnel to the opaque address. The
+same tunnel survives session closure and is reused by later sessions. The gateway must already be
+running (\`spex dashboard\`); no command leaves an SSH child owned by the CLI. ls reports known peers;
+disconnect retires the local peer and asks its remote counterpart to do the same.`,
+        see: 'spex session send --ssh <address> <full-session-id> "<msg>" · spex dashboard (the host gateway)',
+    },
+    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 [--json]
+       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. Errors: integrity (a
+code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` selector; a selector
+whose language has no designated extractor or whose extractor can't run here; a duplicate entry, a
+base path both bare and scoped, or a selector on a glob/directory) · anchor-drift (a
+commit since the spec's version touched an ANCHORED unit's lines, unacked — the blocking tier of
+drift; same-file selectors OR'd, one error naming the hit selectors) · one-govern (a node
+governs >1 DISTINCT 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: coverage · drift
+(UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, \`lint.scopedCodeMiss:
+"ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
+per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
+confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the prepared reference hook; bypass SPEXCODE_SKIP_LINT=1);
+contrast \`spex eval lint\`, which is pure advisory and never blocks anyone. \`--json\` writes the
+versioned machine report to stdout (source candidates + structured findings); its exit code still blocks
+on errors.
+
+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 and recorded in the ack commit's body
+(quieting an anchor hit is a strong claim — the why must be durable). 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: sessionDrawerHelp(),
+        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/write · lint · ok · 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; JSON = canonical index
+       spex eval scenario write --mutation <json> < eval.md       propose one canonical metadata mutation
+       spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
+       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
+       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): filed evals are newest-first across nodes and source ownership; own measurements
+are ✦-marked, evals filed by other sessions are unmarked, and blind spots follow measured rows. --export writes ONE self-contained
+HTML artifact (diff · evidence inlined · gates) for CI/sharing.
+
+scenario ls — the DECLARED contracts, no evals: text may show the latest verdict and --unmeasured is its blind-spot
+worklist; --json emits the complete canonical semantic/measurement index with stable hashes and fixed-tree provenance
+(--unmeasured is text-only because the JSON projection never reads the eval sidecar).
+
+scenario write — the fixed-tree declaration writer for an external measurement guard: stdin is the authoritative
+eval.md, --mutation is one closed JSON insert/delete request for one scenario's test metadata, and stdout is only
+the proposed eval.md bytes. It reads no worktree or runner and fails without stdout on malformed or ambiguous input.
+
+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.
+
+ok — the human's reviewed-and-agreed mark on the scenario's LATEST measurement: an appended, monotonic
+sign-off bound to that one immutable measurement (a newer measurement or staleness releases it on its own —
+no un-ok exists). The evals feed default-hides a fresh, ok'd scenario; a governed session is refused
+(an agent's judgment on a measurement is a remark, never a self-blessing).
+
+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>',
+    },
+    // ── 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 <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
+  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)
+  hook-prompt <name>                  render canonical model-facing text for a runtime hook
+  nudge <node>      the post-merge hook prints the issue nudge for a merged node
+  shared-runtime-spawn <cwd> <log> <pid> <scope> <cmd> [args…]  detached adapter control plane (launch script)
+  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)
+  claude-headless-run <id> <runtime> <cmd> -- <tail…>  resident stream-json controller (launch script)
+  pi-headless-run <id> <runtime> <cmd> -- <tail…>      resident pi text-mode controller (launch script)
+
+If you reached for one of these by hand, the porcelain you want is probably elsewhere: the trunk
+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
+       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: cli.ts intercepts the probe pre-verb.
+// Session's noun-verb shape gets one extra projection; a bare noun still returns the complete drawer.
+export function commandHelp(name, verb) {
+    if (name === 'session' && verb) {
+        const exact = sessionVerbHelp(verb);
+        if (exact)
+            return `${exact}\n\nsee also: spex session (the complete drawer)\n\nmap: spex help · skills: spex guide`;
+    }
+    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 ${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`;
+}
+// The guidance catalog consumes this registry projection rather than copying help prose or maintaining a
+// second command list. Each returned text is exactly what the corresponding public help probe prints.
+export function helpCatalogEntries() {
+    const entries = [{ id: 'overview', title: 'spex help', text: overviewHelp() }];
+    for (const name of Object.keys(ENTRIES).sort()) {
+        const text = commandHelp(name);
+        if (text)
+            entries.push({ id: name, title: `spex help ${name}`, text });
+    }
+    for (const verb of Object.keys(sessionHelpDefinitions()).sort()) {
+        const text = commandHelp('session', verb);
+        if (text)
+            entries.push({ id: `session.${verb}`, title: `spex session ${verb} --help`, text });
+    }
+    return entries;
+}
+export function sessionLaunchReceipt(id, managedWatch = false) {
+    return `spex: launched session ${id}
+  current result: the session JSON is on stdout now; \`spex session ls ${id}\` is the later one-shot snapshot
+  next lifecycle change: ${managedWatch
+        ? `managed watch registered (parent source) — this parent receives ${id}'s state changes through its normal send queue; \`spex session reparent ${id} --to <parent>\` moves it, while \`watch cancel\` affects only manual watches`
+        : `background \`spex session wait ${id}\` (edge-triggered; exits on the next non-actionable→actionable transition); \`spex session watch ${id}\` registers send-backed delivery when the caller is governed`}; \`spex session watch stream ${id}\` NEVER EXITS
+  response channel: \`spex session send ${id} "<msg>"\`; \`send --keys\` is an UNSTABLE LAST RESORT after a plain send cannot land`;
+}
+export function peerSessionLaunchReceipt(id, sshAddress) {
+    return `spex: launched remote session ${id}
+  current result: the session JSON is on stdout now; \`spex session ls --ssh ${sshAddress} ${id}\` is the later one-shot snapshot
+  next lifecycle change: no managed watch crosses this machine peer; query the remote snapshot when needed
+  response channel: the launched prompt carries its runnable peer reply path; \`spex session send --ssh ${sshAddress} ${id} "<msg>"\` reaches this remote session`;
+}
+export function overviewHelp() {
+    return `spex — SpexCode CLI (spec↔code graph + worktree session state machine)
+
+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)
+
+Project verbs (implicit object = this project)
+  ${ENTRIES.graph.line}
+  ${ENTRIES.init.line}
+  ${ENTRIES.materialize.line}
+  ${ENTRIES.doctor.line}
+  ${ENTRIES.uninstall.line}
+  ${ENTRIES.serve.line}
+  ${ENTRIES.dashboard.line}
+  ${ENTRIES.guidance.line}
+
+Noun drawers
+  ${ENTRIES.spec.line}
+  ${ENTRIES.session.line}
+  ${ENTRIES.peer.line}
+  ${ENTRIES.eval.line}
+  ${ENTRIES.issue.line}
+  ${ENTRIES.remark.line}
+  ${ENTRIES.evidence.line}
+  ${ENTRIES.flat.line}
+
+Manuals
+  ${ENTRIES.guide.line}
+
+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 eval · guide settings · guide footprint.
+Machine plumbing (hook/launch-script callees) lives under \`spex internal\` — not part of your vocabulary.`;
+}

package/dist/hook-prompts.d.ts

@@ -0,0 +1,18 @@
+export declare const HOOK_PROMPT_SOURCE: "spec-cli/src/hook-prompts.ts";
+export type HookPromptRole = 'prompt' | 'signal';
+export type HookPromptParams = Readonly<Record<string, string | number>>;
+export type HookPromptEntry = Readonly<{
+    name: string;
+    title: string;
+    description: string;
+    role: HookPromptRole;
+    content: string;
+}>;
+/** The single authoring registry for text emitted by runtime hooks and published prompt catalogs. */
+export declare class HookPromptCatalog {
+    readonly entries: readonly HookPromptEntry[];
+    private readonly definitions;
+    constructor();
+    entry(name: string): HookPromptEntry;
+    render(name: string, params?: HookPromptParams): string;
+}