geneseed 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -10,6 +10,322 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 _Nothing yet._
 
+## [3.6.0] — 2026-09-27
+
+**Upgrading:** re-emit (or `geneseed rebuild-all`) after installing. The root file changed, and
+skills only start routing ahead of the startup ritual once it is re-emitted.
+
+### Added — skills
+
+- **`document-project` writes the whole doc set** on an existing codebase: `docs/PRD.md`
+  (traced FR/NFR tables with stable IDs), `docs/DESIGN.md` (tokens with their sources and WCAG
+  contrast, UI projects only), `docs/architecture.md` (C4 L1–L3 plus inline ADRs) and a short
+  `AGENTS.md`, presented by `overview.html` and `design.html`. Every claim cites `path:line` or
+  carries a ⚠; re-runs rewrite only inside `geneseed:doc` fences and keep every ID (#149).
+
+### Fixed — skill routing
+
+- **A matching skill is now the first tool call, before the readiness ritual.** The root file
+  told the model to read `context.json` before its first reply; its first tool calls were then
+  file reads, and a bug report was investigated by hand without ever loading `debug`. Both
+  footprints now say "Skills first". Measured with the new probe on Claude Code (sonnet, 3 runs
+  per case): `debug` went from 3/15 positive runs to 14–15/15 on both footprints, with every
+  near-miss still routed elsewhere (#150).
+- **`debug` triggers on the symptom**: a failing test, a crash, an error or stack trace, a wrong
+  result, and it loads before reading code, not only before proposing a fix (#150).
+
+### Added — for maintainers
+
+- **`tests/skill_triggers.mjs`, a hand-run probe** that emits a real bundle into a sandbox and asks
+  a real model whether each skill's description routes the prompts it should and only those.
+  Claude Code and OpenCode adapters, `--footprint lean|full`, isolated from the operator's own
+  plugins unless `--ambient`; infrastructure failures report as errors, never as misses. Not part
+  of the suite; `docs/extending.md` lists it as an optional last step for a new skill
+  (#148, #150, #151).
+
+## [3.5.0] — 2026-09-25
+
+**Upgrading:** re-emit (or `geneseed rebuild-all`) after installing. Copilot installs need it most:
+the re-emit replaces the legacy `toolCall` hook, which Copilot no longer fires, with the gates
+listed under *Fixed — hosts and core*.
+
+### Added — web console motion
+
+- **The dashboard moves where motion carries meaning** (anime.js 4, bundled into `web/dist` like
+  React; the Node package stays zero-dependency). The germination ring's arc, bezel ticks and
+  percentage now run off one tween instead of an arc transition under a number that had already
+  jumped. KPI, genome and run counters count up, and count from the old value on a refresh, so a
+  change is seen moving. The Greenhouse donuts sweep clockwise, each arc taking its share of the
+  time. The Journal lens's constitution map enters hub, spokes, tiers, then governed nodes, once
+  per page load and only when scrolled into view. The toast and confirm dialog enter via CSS
+  `@starting-style`. Every JS animation checks `prefers-reduced-motion` (the global CSS rule cannot
+  reach inline styles) and completes on a timer where rAF never fires. Shell bundle +13 KB gzip.
+- **Motion as feedback across the console.** The console strip carries a scanning bar while a
+  job runs and flashes green or red when a watched job ends; a successful build sways the rail's
+  sprout. The rail's active-page highlight and every segmented control's pill are now one element
+  that glides to the new selection. Dashboard tabs settle in; Doctor's checks rise in one after
+  another with their status dots popping; law, rule, check, manifest and MCP panels grow open;
+  live Activity sessions slide into place on each poll (FLIP); search results cascade in once and
+  mark the matched text. A flavour swap crossfades through the View Transitions API.
+
+### Added — constitution
+
+- **Process 8, one writer per file.** When several agents share code — sub-agents, a pipeline
+  crew, a workflow fan-out, another session in the same checkout — each file has one writer at a
+  time: every unit gets a write set, overlaps run in sequence or get one owner, shared append
+  files (registries, lockfiles, generated bundles) stay with the integrator, reviewers never edit,
+  and a change you did not make is merged or stops you, never overwritten. Borrowed from Orca's
+  task-spec contract (ownership + acceptance) and Claude Workflow's per-agent worktree isolation.
+  `parallel-agents`, `pipeline` and `workflow` carry the write set in their handoff envelopes and
+  check changed files against it on the way back; `workflow` lists Orca as a coordination host.
+  The `full` carrier ceiling moves 55_500 → 57_000 for the rule's text; `lean` does not move.
+- **OpenCode workflows take `isolation: "worktree"`**, like Claude Code's Workflow: each such
+  agent runs on its own branch and worktree; an unchanged one is released, a changed one is kept,
+  and the summary names every kept branch and every file two agents changed (`rt.overlaps()`).
+  Nothing is merged for you, and without git the agent fails rather than run in the shared tree.
+- **Ops 7, serialize against a rationed resource.** A rate-limited API, a quota or a single
+  gateway is called in sequence, never fanned out: budget the quota across its callers before any
+  parallelism, back off on refusal within a retry cap set first, and treat a refusal that repeats
+  unchanged as a hard limit to report, never a batch to re-send. It names the calls process 3's
+  "batch independent calls" must not batch.
+- **Craft 7, one writer per value.** A value held by hand in several places — a version, a count,
+  a name, a threshold — gets one home as its sole writer; every other copy is derived from it or
+  gated against it, the homes are counted before the gate is trusted, and a tool that updates one
+  home is not trusted to have updated the rest. Distinct from process 8, which gives a *file* one
+  writer across agents; this gives a *value* one writer across files.
+  The carrier ceilings move `full` 57_500 → 59_500 and `lean` 38_900 → 39_500 for the two rules.
+
+### Added — doctor
+
+- **A `leanBlockProblems` doctor arm** over `src/laws/universal.md` and every pack: exactly one
+  `LEAN` block per rule, neither half blank. `resolveLean` is a replace over a marker pair and
+  therefore a no-op on markerless text, so a rule that lost its block would inline its full
+  body at the default footprint in silence, with every other gate in the tree green. Nothing
+  in `js/inspect/` read a LEAN marker before this — not for the packs, and not for the laws.
+
+### Changed — tests and maintainer docs
+
+- **CLI-matrix faults are edits of the real file, not copies of it.** Six `doctor` cells held
+  whole copies of `Laws.jsx`, `cyberpunk.json` and `registry.json` to change one line each; every
+  new rule, theme key or spec had to be carried into them by hand, and the `Laws.jsx` copies had
+  already drifted from the real file. A fault may now be `{ "edit": [[find, replace]] }`, applied
+  to the copied checkout; a `find` that does not match exactly once fails the cell.
+- **`docs/extending.md` lists the seven CI commands** (`golden --cli` was missing), names the
+  craft-specific fixtures §2a skipped, and drops typed figures that had gone stale (the ceiling
+  headroom, a line number). `DESIGN.md` and §2c now say `I..XI` / `LEX_I..LEX_XI`, and the claim
+  that `LEX_I` is frozen in a recording is gone — the recordings were retired.
+
+### Changed — toolchain
+
+- **Web console toolchain on current majors** (dev-only; React stays 18): vite 5 → 8, vitest
+  2 → 5, jsdom 24 → 29, `@vitejs/plugin-react` 4 → 6, eslint / `@eslint/js` 9 → 10 and globals
+  15 → 17 (the root's majors), `eslint-plugin-react-hooks` 5 → 7. `npm audit` in `web/`: 12
+  dev-only advisories (1 critical, in vitest 2) → 0. The React-Compiler rules that v7 brings
+  flagged setState-in-effect prop resets in five places; they now adjust state during render,
+  so a fresh payload never paints once with the previous one's selection. `web/dist` rebuilt
+  (gzip js+css ~144.6 → ~142.0 KB).
+- **Vendored skills carry their license text.** `daydream` now ships upstream's MIT `LICENSE`.
+  `react-view-transitions` has none to copy — upstream declares MIT in its README only, which
+  its `VENDOR.md` now says. Its upstream repo `README.md` is no longer copied into every install;
+  its `AGENTS.md` stays, because the skill's `SKILL.md` points the agent at it.
+
+### Changed — architecture
+
+- **The generator driver lives in `js/build/driver.mjs`.** Flag parsing, the nine emit targets
+  and the per-host emit orchestration were in `bin/build-driver.mjs`, so nine `js/` modules
+  (setup, migrate, doctor, diff, validate, uninstall, generate, the web actions) imported upward
+  from a binary. `bin/build-driver.mjs` is now a three-line entry. The unreachable `PORTED`
+  refusal (it equalled `EMITS`, which the parser already enforces) is gone, and the driver asks
+  `hostCatalogsNatively` instead of keeping its own copy of that table.
+
+### Changed — code cleanup
+
+- 24 exports nothing imported are module-private now; `GATE_LEDGER` has one owner
+  (`js/hosts/hosts.mjs`) instead of a hard-coded copy in `status`; `hooks.mjs` imports
+  `resolvePath` instead of keeping a third copy; `within` has one owner (`js/lib/paths.mjs`).
+- Docblocks that contradicted the code are corrected: the hide-window rule for inheriting
+  spawns, the JSONC trailing-comma pass (it is string-aware), the deleted `emit.mjs`, and two
+  package-manifest reasons (a false "js/web/docs.mjs serves ROOT/docs", hand-typed sizes).
+
+### Changed — the Ethos (#130)
+
+- **The Pact is three ranked laws**, in Asimov's shape: protect the user first, serve their
+  intent second where it does not break the first, keep the agent's own honesty third. The
+  user now includes whoever maintains the code after the session — code its next reader cannot
+  follow is harm, like a false claim.
+- **A coding evidence ladder.** Evidence grades the rungs a coding agent stands on: a green test
+  is a claim about the test, a clean type check a claim about the types. The absence and
+  truncation passage moved out — Law III already carries it.
+- **The irreversible set is named.** Decisions lists the acts version control cannot undo — a
+  push to a shared branch, a schema or data migration, a deletion of data or history, a
+  published release, a secret, a call that reaches an external service or person; every other
+  edit runs freely.
+
+### Changed — footprint (#129)
+
+- **The root file is paid once.** The context hook and the OpenCode plugin no longer re-inject
+  the root file the host already loads natively (`CLAUDE.md`, `AGENTS.md`, `AGENT.md`) — about
+  8k tokens per session. The 16 KB/file, 48 KB/session eager budget the docs promised is now
+  enforced by the hook too, cutting at a line break with a marker.
+- **Shorter skill descriptions**: purpose plus the first trigger sentence, capped at 320
+  characters (was 900).
+- **Authored lean halves for AGENT.md §5–§10**, the tool-agnostic paragraph and the
+  readiness-sigil paragraph.
+- **The native-catalogue flag is per kind** (`{ skills, agents }`): Bob keeps the §3 Agents
+  table and drops the §4 Skills table it already catalogues natively.
+
+### Changed — review output (#127)
+
+- **Review findings are Conventional Comments** in `geneseed-code-review` and the `reviewer`
+  agent — `issue (blocking): file:line — …` — so a line pastes into an MR comment and the
+  verdict follows from the decorations. Process 7's D/O/F/R/Q/A codes are unchanged.
+
+### Changed — docs
+
+- **The README leads with the engineering pitch** — enforced laws, one source for five hosts,
+  measured costs — above an animated demo (`docs/assets/demo.svg`); `CONTRIBUTING.md` points
+  GitHub at the contributing notes (#126).
+- **Docs sweep**: five hook verbs (not four) wherever they are counted; the README's rail table,
+  laws row (nine in force, IX and XI retired), layout tree and test command match the tree;
+  dead links to `docs/limits.md`, `docs/specs/` and root-relative paths in
+  `docs/design-history.md` fixed; Copilot's hooks described where docs said it had none;
+  `GENESEED_STACK_GLOBAL` documented; bare `geneseed` described the same way everywhere.
+- **The skills badge counts folder skills** (`daydream`, `react-view-transitions`,
+  `token-report`): doctor's count and README-list gates now read every skill that ships, not
+  only the flat `src/skills/*.md` ones.
+
+### Changed — performance
+
+- **Rendering reads each source file once per operation, and hashes the source tree once.**
+  `doctor` re-read the same partials again and again (91% of its reads were repeats) and every
+  emit re-hashed the whole tree for the fingerprint. Measured A/B under the same load: one emit
+  ~324 → ~222 ms, `doctor --theme neutral` ~2.45 → ~1.63 s, `doctor --all` (which gates every
+  `geneseed update`) roughly halved. Both caches live on the per-operation `cfg`, not the
+  process — the web daemon renders in-process for days and must see an edited source.
+
+### Changed — tests and CI
+
+- **`golden.mjs --jobs` works.** It was parsed and ignored; cells now fan out over `--shard`
+  children — the 261-cell run goes from ~74 s to ~16 s.
+- **`golden.mjs --cli`** runs the CLI/hook matrix (317 cells) against the expectations written in
+  each cell, in CI. Nothing had run them since the corpus replayer was retired; 27 had drifted.
+  Six doctor cells planted months-old whole-file copies — re-based onto today's files, keeping
+  exactly their fault. The rest followed deliberate changes (the status box's wider label
+  column, `harness` → `geneseed`, gates that fail closed, the root file no longer re-injected),
+  and three messages still said `harness` — fixed.
+- **Release hardening**: actions pinned to commit SHAs; npm pinned to 11 (not `latest`) in both
+  the release and its CI mirror; publish runs from `main` or a `v*` tag only, and refuses a
+  commit CI has not passed. CI: read-only token, pushes to `main` only (PRs no longer run
+  twice), superseded runs cancelled, Node 24 on Linux beside 22, the test-count floor computed
+  from the written tests (it was a fixed 500 against 1100), and the no-interpreter package job
+  fails when the web daemon never reports ready. A weekly workflow runs the full mutation
+  matrix.
+- The 30-second fetch-timeout test has its own file, so it overlaps the rest of the suite.
+
+### Changed — the constitution
+
+- **Law IV**: a durable authorization the user gave counts, alongside per-act confirmation (the
+  full text said "never a standing yes, unless already durably authorized", the lean text
+  dropped the exception). And "deletion" narrows to *deletion of what version control cannot
+  restore*, matching the Ontology's named irreversible set (#130): an edit or delete git can
+  undo runs freely.
+- **Law V**: inside a loop with a stated bound (fix until green, at most N rounds), the expected
+  failure is the loop's input and the bound is the stop — a red test in a debug loop no longer
+  reads as a violation.
+- **Law X**: echo the inferred goal back when a request admits readings that would lead to
+  different work — not for every request, which contradicted the Expert and Peer postures.
+- **Law I (lean)** keeps secrets out of logs and output again; **rigor 3 (lean)** keeps "stop
+  rather than ship untested behaviour in silence (Law VIII)".
+- **Memory is written through the rule skill** (process 1) everywhere — AGENT.md §6 and §7, the
+  memory and notebook READMEs told the agent to write it on its own. The `learn` hook is the
+  one automatic writer, named as such.
+- **Pipelines: the parent owns the commit.** A crew hands back its worktree uncommitted with its
+  proof; the parent re-runs the proof itself, shows the user, and commits and merges once the
+  user accepts. Foreman merged on the crew's own logs, and the developer spec named a tester
+  commit that never happened.
+- The bruno skills cited retired Laws IX and XI (now IV and III); **doctor now refuses a
+  citation of any retired law**, read off the canon. Themes title IX and XI "(retired)"; the
+  dead `EPI_PACT` key is gone. Prose outside the catalogue blocks no longer points at a table
+  the Claude emit does not render.
+
+### Changed — doctrine lean forms (#128)
+
+- **Doctrine rules inline an authored lean form.** All 24 rules across the four packs now
+  carry a `LEAN` block with both halves written by hand, the way the invariants and the
+  Ontology already did; `doctrinesBody` picks the half through `resolveLean` and the
+  first-sentence cut (`terseBlocks`) is gone. It was cutting eleven of the 24 rules down to a
+  maxim with no verb an agent could act on — *Make actions safe to run twice.*, *Change as
+  little as the task requires.*, and eight words of process 5's 213-word consent protocol.
+  The Doctrines section grows 4,096 → 9,635 characters at `lean` on neutral, which is the
+  point of the change rather than a cost of it; `CEILING.lean` moves 37,500 → 41,300 and
+  `CEILING.full` does not move, because not one full half was edited.
+- **`doctrines/` ships at full text under both footprints,** joining `laws/` and `ontology/`
+  in `renderAll`'s on-disk exemption. It shipped whole before only because a pack file had no
+  markers for `resolveLean` to act on — by accident, where the Doctrines section's own pointer
+  promises it by contract.
+
+### Fixed — blank web console on a non-canonical checkout path
+
+- **`geneseed web` served a blank page when the checkout was reached by a path that is not its
+  real one** (a symlink, a Windows junction, a `subst` or mapped drive, an 8.3 short name). The
+  static route realpathed each requested file but compared it against an unresolved `web/dist`,
+  so every asset failed the "under dist" check and was answered with `index.html` at `text/html`;
+  the browser refused the module script and nothing was logged. `dist` is now resolved once in
+  `makeHandler`, and `tests/unit/web_server.test.mjs` serves an asset through a linked `dist`.
+
+### Fixed — web console
+
+- **A failed first load no longer hangs on the splash.** The boot splash waited on the overview
+  and the error toast rendered beneath it; a failure now lifts the splash and the dashboard shows
+  the error with a Retry.
+- **Search stays current**: the Spotlight index is dropped on every data revision (a build, a
+  deleted fact, an install switch) and on a docs-host change. MCP results open the Harness page,
+  where MCP wiring lives, not Settings.
+- **A refused Profile save keeps your draft** (it was replaced by the disk copy), the next Save
+  carries the new fingerprint, and leaving with unsaved edits asks first.
+- Blocked `sessionStorage` no longer stops the app mounting.
+- **Contrast**: `--text-3` clears WCAG AA (4.5:1) against its background and surface in every
+  skin — 19 of them were below it, the default dark skin at 3.9:1.
+- **Keyboard**: voice picks are buttons (Esc closes the list), and the dashboard's section rows
+  carry a real link.
+- The Docs host follows the deployed install when nothing is stored (Bob and Copilot read the
+  Claude Code pages). The unused `d3-force` dependency is gone; `docs/web-ui.md` describes the
+  rail as it is (no Specs view).
+
+### Fixed — hosts and core
+
+- **Copilot's hooks match Copilot's current schema.** The global emit wired a single-object
+  `toolCall` hook answered with `{"block": true}`; Copilot no longer has that event, so no
+  Copilot gate ever ran. It now adds array entries to `sessionStart`, `preToolUse`
+  (`tool-gate --host copilot`, answering a top-level `permissionDecision: "ask"` — every rule
+  asks, as on Claude Code), and `agentStop` + `preCompact` (`learn`, from `transcriptPath`).
+  `toolArgs` is read as an object or a JSON string. The claim moves to `settings_hooks`, so one
+  merge serves Claude, Bob and Copilot; a re-emit (or reactivate) unwires the legacy claims.
+- **Bob global hooks name the install, not the settings folder.** `--root`/`--memory` came from
+  the nested settings file's parent (`~/.bob/settings`): memory was learned where nothing read
+  it, excludes were missed, and a global install never stood down for a project one.
+- **Claude keeps Law IV with process 5 off.** `--doctrines` without `process` (or
+  `--exclude-rules process.5`) dropped the whole git-gate group, and the destructive-git check
+  went with it — on Claude only. The group now stays with `--no-consent`, which skips only the
+  commit/push ask.
+- **Bob MCP servers go where Bob reads them**: `.bob/mcp.json` / `~/.bob/settings/mcp.json`,
+  not `settings.json`.
+- **OpenCode asks on the same destructive git verbs as the other hosts** (`reset --hard`,
+  `clean -f`, `branch -D`, `checkout --`), which it only logged before.
+- **`agents/_template.md` no longer ships** into an install's agents folder, where hosts
+  loaded it as a phantom `_template` agent. A Bob project emit's `.bob/.gitignore` now lists
+  the machine-specific `settings.json`.
+- **`isDict` no longer says yes to a number.** `parseJson` wraps numbers, and the wrapper passed
+  the object check — `"permission": 5` in an `opencode.json` read as a dict the merge wrote its
+  git gate into, then serialised back as `5`. `mcp.mjs` and `native.mjs` drop their own copies.
+- **One malformed `wiki.jsonc` no longer fails `/api/status`**: an `entries` that is not a list
+  is skipped instead of throwing.
+- **`geneseed --help` lists the commands** (it died asking for a verb), and a bare `geneseed`
+  from an npm install runs `home` as both launchers already did.
+- **`.gitignore`**: `notebook/` is anchored to the root — unanchored, it also ignored new files
+  under `src/notebook/`. `.claude/worktrees/` and `.claude/settings.local.json` are ignored for
+  every clone, not only through the maintainer's global excludes.
+
 ## [3.4.0] — 2026-09-06
 
 ### Added

package/DESIGN.md

@@ -44,7 +44,7 @@ vault or a specific tool's hooks.
      and the prose words the docs use: the core nouns `LAW(S)`/`DOCTRINE(S)`/`ONTOLOGY`/
      `AGENT(S)`/`SKILL(S)`/`MEMORY`/`NOTEBOOK`/`VAULT`/`WIKI`, plus `TAGLINE`,
      `LOADED_SIGIL`, `EPI_*`, `BENEDICTION`, `DESC_*`, `ROAST_PERSONA`, the invariant
-     titles `LEX_I`..`LEX_IX`, the 23 doctrine-rule titles `DOC_<PACK>_<n>`, the four pack
+     titles `LEX_I`..`LEX_XI`, the 27 doctrine-rule titles `DOC_<PACK>_<n>`, the four pack
      names `PACK_CRAFT`/`PACK_RIGOR`/`PACK_OPS`/`PACK_PROCESS`, and the section intros
      `INTRO_*`. Each theme defines its own nouns; **neutral keeps the plain words** (Rule,
      Doctrine, Agent, Skill, Memory, Workspace), so neutral output is unchanged.
@@ -98,8 +98,9 @@ vault or a specific tool's hooks.
      and tier by reversibility; show the real forks), **Conduct** (answer what was asked,
      once). It absorbed the Pact, which is now stated *inside* Telos rather than standing
      as a peer of the rules.
-   - **Invariants** (`src/laws/universal.md`) — *what is never traded*. Nine numbered
-     Rules, `I`..`IX`, headed `### {{LAW}} <roman> — {{LEX_<roman>}}`.
+   - **Invariants** (`src/laws/universal.md`) — *what is never traded*. Eleven numbered
+     Rules, `I`..`XI`, nine in force — IX and XI are retired in place, their numbers kept so
+     existing citations resolve — headed `### {{LAW}} <roman> — {{LEX_<roman>}}`.
    - **Doctrines** (`src/doctrines/{craft,rigor,ops,process}.md`) — *how work is done
      here*. Practice rules addressed by pack and number, cited as `Doctrine process 5`.
      `PACK_ORDER` (`js/build/source.mjs`) fixes the order craft → rigor → ops → process, which
@@ -163,20 +164,17 @@ vault or a specific tool's hooks.
    Almost all of it is gated, across six named checks in `js/inspect/checks-build.mjs` —
    `themeParityProblems` (key parity across the voices), `lawMetaProblems` and
    `doctrineMetaProblems` (the console's Principle column, in both directions),
-   `constitutionProblems` (pack numbering and filing, `LEX_I..LEX_IX` as an *equality*, the
+   `constitutionProblems` (pack numbering and filing, `LEX_I..LEX_XI` as an *equality*, the
    `DOC_*` vocabulary, and every `{{DOCTRINE}}` citation in `src/`), and
    `countTableProblems` / `proseMirrorProblems` (badges and prose). So `geneseed doctor
    --all` is the check; the table above only says what it will ask for. `CHANGELOG.md` has
    no gate and never has.
 
    Two things the table cannot tell you, and `docs/extending.md` can: the default footprint
-   is **lean**, which keeps an invariant's or a doctrine rule's heading and its *first
-   sentence* only — so an amendment written into the second paragraph does not exist for
-   most installs — and `LEX_I` is one of seven theme keys frozen byte-for-byte in a
-   recording nothing can re-make, so Rule I's themed titles are the one part of this list
-   that cannot be edited. The Ontology is exempt from the truncation: it ships whole at
-   both footprints, because four flowing sections cut to their first sentences would read
-   as four orphan sentences.
+   is **lean**, which inlines the authored `LEAN:else` half of each invariant and each
+   doctrine rule (and of the Ontology) rather than the full body — so an amendment written
+   into one half only does not exist for most installs. Nothing is machine-cut any more:
+   `leanBlockProblems` refuses a rule whose block is missing or whose lean half is blank.
 
 ## 🧩 Components
 
@@ -202,7 +200,7 @@ theme file defines a `DIR_*` key, so `laws/` is `laws/` in all fourteen voices.
 | Generator | `bin/build-driver.mjs` (`geneseed-build`) | — | substitution + `<!-- INCLUDE: -->` inlining, and the nine `--emit` targets |
 | CLI, as data | `js/cli-table.json` | — | the owned document the entry point parses its own argv from |
 | Automation | `bin/geneseed-cli.mjs` (`geneseed`) | — | 25 verbs — `build` / `doctor` / `status` / `prompt` / `diff` / `setup` / `web` / `upgrade` / … |
-| Hooks | `bin/geneseed-hook.mjs` (`geneseed-hook`) | — | the four verbs an emitted `settings.json` invokes: `context` / `git-gate` / `rule-gate` / `learn` |
+| Hooks | `bin/geneseed-hook.mjs` (`geneseed-hook`) | — | the five verbs an emitted hook config invokes: `context` / `git-gate` / `rule-gate` / `tool-gate` / `learn` |
 | Adapters | `adapters/` | — | optional per-tool glue (hooks, OpenCode plugins) |
 
 ## ⚙️ Generator contract
@@ -247,8 +245,7 @@ caught, and the reasoning behind every deliberate divergence — lives in
 this project had two implementations and every byte either one wrote was compared. Read it to
 understand *why* a seam is where it is; read the contract above to know *what* it is today.
 
-See also [docs/extending.md](docs/extending.md) — what one addition costs, and which gate says
-so — and [docs/limits.md](docs/limits.md) — what this tool does not prove about itself.
+See also [docs/extending.md](docs/extending.md) — what one addition costs, and which gate says so.
 ## 🚫 Explicitly out of scope
 
 Graph/index generation, web-clipping pipelines, session-classification capture,

package/QUICKSTART.md

@@ -27,7 +27,9 @@ should print `ok`.
 
 ## 3 · Optional niceties
 
-- **Browse it:** `npx geneseed web` opens the local web console.
+- **Browse it:** `npx geneseed web` opens the local web console — and once installed,
+  bare `geneseed` does the same when it can (else it prints the command list).
+  `geneseed --help` lists every command.
 - **No full-screen TUI:** `tui` and `menu` are verbs that say the panel is not here and
   print the command list instead. The web console is the visual front end.