geneseed 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -10,6 +10,289 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 _Nothing yet._
 
+## [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.
 

package/README.md

@@ -10,7 +10,7 @@
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
-[![Skills](https://img.shields.io/badge/skills-49-blueviolet)](src/skills/)
+[![Skills](https://img.shields.io/badge/skills-52-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
 [![Laws](https://img.shields.io/badge/laws-11-critical)](src/laws/universal.md)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
@@ -22,7 +22,24 @@
 
 ---
 
-Geneseed distils an agent operating system into a generic harness built around a single `AGENT.md`. Point your tool at it and the agent inherits a set of operating **rules**, a roster of capability **agents**, native **skills**, a **memory** convention, and — on OpenCode — 7 **plugins** that auto-load your project's docs, capture durable memory, enforce the safety laws, run saved workflows, ping you when a long run finishes, hold a minimal-code mode when you ask for one, and stream what each session is doing to the web console. One source builds it; it follows you into every repo.
+<p align="center"><img src="docs/assets/demo.svg" alt="geneseed setup, then two laws catching a force-push and a credential at the tool boundary" width="760"></p>
+
+**Geneseed compiles your agent's rules instead of asking you to write them.** One source in `src/` renders into a ready-made harness for OpenCode, Claude Code, Bob, Copilot, or any `AGENT.md` tool: a constitution of laws and doctrines, a roster of capability agents, native skills, a memory convention — and, wherever the host has a hook surface, gates that *enforce* the laws at the tool boundary instead of hoping the model remembers them.
+
+```bash
+npx geneseed setup
+```
+
+Want to read what it leaves behind before installing anything? [**geneseed-demo**](https://github.com/Arylmera/geneseed-demo) is a repository exactly as the plain bundle emits it — nothing hand-written.
+
+### Why not just a CLAUDE.md?
+
+A hand-written instructions file is prose the model may or may not honour, copied into every repo and drifting in each one. Geneseed is a build, and that changes four things:
+
+- **Laws are enforced, not suggested.** A force-push, a `reset --hard`, or a credential written into a tracked file is caught by a hook *before* the tool runs, in the host's own dialect — a prompt on Claude Code and Copilot, a hard block on OpenCode, exit 2 on Bob. The gates fail closed, and every catch is one line in a ledger that `geneseed status` counts.
+- **One source, five targets.** Skills are byte-identical on every host; only the wiring differs. Every commit renders all 261 emit configurations, and a second emit into the same tree must change nothing.
+- **Costs are measured, not guessed.** Zero runtime dependencies. The hook path loads in about 14 ms per tool call. The default *lean* footprint keeps the always-on context small and puts the full rationale one read away — the numbers are in [docs/token-footprint.md](docs/token-footprint.md).
+- **It follows you.** Install once, globally; every repo inherits it. One `git pull` or `npm install -g geneseed@latest` rebuilds every active install.
 
 This page is the overview. Four parts: **why** it exists, how to **set it up**, the two ways to **drive it** (web console & command line), and **what you get**. For every install path, configuration knob, and troubleshooting step, read the full [Setup guide](SETUP.md).
 
@@ -75,7 +92,7 @@ Cloning still works and is what you want if you intend to *change* the harness r
 ```bash
 git clone https://github.com/Arylmera/Geneseed.git
 cd Geneseed
-./geneseed setup          # the wizard — or bare `./geneseed` for the main menu
+./geneseed setup          # the wizard — bare `./geneseed` opens the web console
 ```
 
 **Windows** — native, no bash, WSL, curl, or unzip; works from cmd or PowerShell:
@@ -83,7 +100,7 @@ cd Geneseed
 ```powershell
 git clone https://github.com/Arylmera/Geneseed.git
 cd Geneseed
-.\geneseed.cmd setup      # the wizard — or bare .\geneseed.cmd for the main menu
+.\geneseed.cmd setup      # the wizard — bare .\geneseed.cmd opens the web console
 # PowerShell runs a .cmd directly, so this is the PowerShell spelling too
 ```
 
@@ -91,13 +108,7 @@ Both launchers are thin shims over the Node CLI: they need `node` (22.3+) on `PA
 
 ### 🟩 One runtime — Node, and nothing else
 
-Node ≥ 22.3 is the entire dependency list. Every subcommand, all four hooks, every web-console endpoint and both generators run from it, and every commit runs the whole unit suite plus `doctor --all` across every theme × host × footprint, on Linux and Windows both. So an install needs no second interpreter — not for the harness, and not for anything it ships. (Until 2026-08-17 the generator's output was also replayed byte for byte against recordings taken from the Python implementation. Those were retired — see [`docs/limits.md`](docs/limits.md) for the measurement that licensed it and the coverage it cost.)
-
-- **One runtime, no second one to install**: every command and all four hook verbs answer from the Node entry points. `catalog`, `mcp` and `memory` are console-facing verbs the CLI table declares alongside them. There is no full-screen browse panel — `geneseed tui` and `geneseed menu` are verbs that refuse it by name and print the command list instead, off a terminal as well as on one.
-- **Nothing you install needs an interpreter.** The `token-report` skill is a script rather than prose, and it ships as `scripts/token_report.mjs`, run with `node`; `daydream` and `herdr` hand their inline code to `node -e`. So **every bundle carries** nothing that needs one: no Python file, and no skill that shells out to an interpreter, on any host, theme or footprint. Three tests freeze that — one scans every tracked file for inline code handed to an interpreter, one globs the bundle source, and one replays the report script over seeded transcripts for all four hosts and compares the bytes.
-- **`upgrade` / `update` / `sync-self` / `bootstrap` are for a git checkout.** They `git pull` the install's own origin. From an npm install they stop before touching anything and name `npm install -g geneseed@latest` as the update instead.
-
-One more honest edge, in the web console rather than the CLI: the **"browse…" folder picker** would open an OS-native dialog on the machine running the daemon, and this server declines to. The button reports that it is unavailable and the field beside it stays editable — type or paste the path.
+Node ≥ 22.3 is the entire dependency list — every command, all five hook verbs, the web console and both generators run from it, and nothing any bundle ships needs a second interpreter. The details, and the few honest edges, are in [SETUP.md → One runtime](SETUP.md#-one-runtime--node-and-nothing-else).
 
 ### ✅ After installing
 
@@ -128,21 +139,20 @@ geneseed web status          # is it running, and where
 
 The left rail mirrors the harness's own shape:
 
-| Group | What's there |
+| Group | Views |
 | --- | --- |
-| **🧬 Harness** | **Dashboard** — live readout of what's deployed (voice, capabilities, drift, recent jobs) · **Library** — browse Laws, Agents, Skills, Memory, Notebook · **Graph** — cross-link constellation across the whole harness |
-| **📚 Learn** | **Docs** — rendered markdown + concept pages + CLI reference + glossary, grouped into Get started / Core concepts / How-to / MCP servers / Plugins / Reference / Deeper · **Specs** — dated implementation specs with design rationale |
-| **🔧 Maintain** | **Changes** — diff between the deployed harness and the source, export an `improvements.md` back-port · **Doctor** — health check across themes, links, parity, and authoring gates |
-| **🎨 Configure** | **Themes** — preview and switch the deployed voice live · **Settings** — MCP servers, server controls |
-| **ℹ️ About** | project + creator credits, source link |
+| *(ungrouped)* | **Dashboard** — live readout of what's deployed (voice, capabilities, drift, recent jobs) |
+| **📖 Codex** | **Constitution** · **Rules** · **Profile** · **Skills** · **Agents** · **Library** (Memory, Notebook, the wiki) · **Docs** |
+| **🩺 Care** | **Activity** · **Changes** — diff against the source, export an `improvements.md` · **Doctor** — health check across themes, links, parity and authoring gates |
+| **🎨 Setup** | **Harness** — installs, theme, footprint · **Settings** — MCP servers, server controls |
 
-It binds to `127.0.0.1` only and runs entirely offline — no npm needed at runtime; the UI build ships in `web/dist/`. Mutating actions run in the background and report back as toasts (fire-and-notify), guarded by a per-session token so other sites can't trigger them. A global **Spotlight** search in the topbar jumps to any agent, skill, law, doc, or spec. Rebuild the UI after changing anything under `web/src/` with `cd web && npm install && npm run build`. If `web/dist/` is missing (fresh clone, never built), `geneseed web` offers to run that build for you — answer `Y` and it installs, builds, and starts the server; in non-interactive shells it prints the manual recipe instead.
+It binds to `127.0.0.1` only and runs entirely offline — no npm needed at runtime; the UI build ships in `web/dist/`. Mutating actions run in the background and report back as toasts (fire-and-notify), guarded by a per-session token so other sites can't trigger them. A global **Spotlight** search in the topbar jumps to any agent, skill, rule, doc, or MCP server. Rebuild the UI after changing anything under `web/src/` with `cd web && npm install && npm run build`. If `web/dist/` is missing (fresh clone, never built), `geneseed web` offers to run that build for you — answer `Y` and it installs, builds, and starts the server; in non-interactive shells it prints the manual recipe instead.
 
 Full reference — every view, the launch/daemon/PWA surface, the security model: **[docs/web-ui.md](docs/web-ui.md)**.
 
 ### ⌨️ Terminal — `geneseed`
 
-No browser? Every action the console offers is also a verb: `build`, `doctor`, `diff`, `rebuild-all`, `status`, `memory`, `catalog`, `exclude`, `mcp`, `link`/`unlink`, `uninstall` (global **or** per-repo). `geneseed setup` runs the install wizard — plain text prompts, every console, every OS; see [Setup](#-2--setup) above for the walkthrough. `geneseed --help` lists the rest. There is no full-screen panel: `tui` and `menu` are verbs that say so and print the command list.
+No browser? Every action the console offers is also a verb: `build`, `doctor`, `diff`, `rebuild-all`, `status`, `memory`, `catalog`, `exclude`, `mcp`, `link`/`unlink`, `uninstall` (global **or** per-repo). `geneseed setup` runs the install wizard — plain text prompts, every console, every OS; see [Setup](#-2--setup) above for the walkthrough. `geneseed --help` lists every command, and bare `geneseed` (or `./geneseed`) opens the web console when it can, else prints the command list. There is no full-screen panel: `tui` and `menu` are verbs that say so and print the command list.
 
 ---
 
@@ -152,11 +162,11 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 
 | Layer | What it is |
 | --- | --- |
-| **🧭 Ontology** (`ontology/`) | the mind the rules govern, in four prose sections — **Telos** (the Pact: protect the user, the truth, the agent), **Evidence** (every claim graded by how it was obtained), **Decisions** (classify and tier by reversibility, show the real forks), **Conduct** (answer what was asked, once). Always in force, never toggleable |
-| **🛡️ Rules** (`laws/`) | 11 universal laws the agent obeys — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-assert, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, root-cause, external-gate, echo-the-intent, absence-is-a-claim |
+| **🧭 Ethos** (`ontology/`) | the mind the rules govern, in four prose sections — **Telos** (the Pact: three ranked laws — protect the user, serve their intent, keep your own honesty), **Evidence** (every claim graded by how it was obtained), **Decisions** (classify and tier by reversibility, show the real forks), **Conduct** (answer what was asked, once). Always in force, never toggleable |
+| **🛡️ Rules** (`laws/`) | 11 universal laws, nine of them in force — always, never toggleable: sealed-secrets, one-intent-one-act, verify-before-assert, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, root-cause, echo-the-intent. Laws IX and XI are retired, their numbers kept so old references resolve |
 | **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all four pack files ship on disk either way, so a citation into a pack you left out still resolves |
 | **🤖 Agents** (18) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `researcher`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
-| **🛠 Skills** (49) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** |
+| **🛠 Skills** (52) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** · **daydream** · **react-view-transitions** · **token-report** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
 | **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
 | **📓 Notebook** (`notebook/`) | the agent's sovereign space — any medium (code, tools, data, notes), self-ruled via a seed-once charter, always git-ignored; only its `.gitignore` is build-asserted |
@@ -165,7 +175,7 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 
 ### 🤝 What the harness asks of you
 
-The Pact in the Ontology is mutual. The agent's side is written into every install. Yours is not enforced — it is what keeps the pact honest, and only you can give it:
+The Pact in the Ethos is mutual. The agent's side is written into every install. Yours is not enforced — it is what keeps the pact honest, and only you can give it:
 
 - **Don't punish candour.** When the agent contradicts you with evidence, flags a risk, or admits a doubt, that is the pact working, not defiance. Meeting it with penalty teaches the agent to flatter instead.
 - **Give the context, don't withhold it.** The agent cannot weigh what it is not told. Front-load the constraint rather than fault its absence after the fact.
@@ -191,14 +201,14 @@ Pick with `--theme NAME` or via the setup wizard. The theme is remembered in a `
 
 ### 🪶 Footprint (lean vs full)
 
-A second per-install dial, **footprint**, sets how much of the constitution `AGENT.md` carries *inline* every turn — a token-cost knob, not a change to which Rules apply (every Rule is always in force, and so is the whole of the Ontology).
+A second per-install dial, **footprint**, sets how much of the constitution `AGENT.md` carries *inline* every turn — a token-cost knob, not a change to which Rules apply (every Rule is always in force, and so is the whole of the Ethos).
 
-| Footprint | The Ontology + Sections 1–2 of `AGENT.md` | Trade-off |
+| Footprint | The Ethos + Sections 1–2 of `AGENT.md` | Trade-off |
 | --- | --- | --- |
-| **lean** *(default)* | the Ontology and each Rule in their **authored** short form; each active doctrine rule as its heading + the rule line; then pointers to the full text | lighter every turn; rationale is one on-demand read away |
-| **full** | the Ontology, every Rule and every active doctrine rule at complete text **and** rationale, inlined | maximum guidance density; largest per-turn token cost |
+| **lean** *(default)* | the Ethos, each Rule and each active doctrine rule in their **authored** short form; then pointers to the full text | lighter every turn; rationale is one on-demand read away |
+| **full** | the Ethos, every Rule and every active doctrine rule at complete text **and** rationale, inlined | maximum guidance density; largest per-turn token cost |
 
-**Lean is authored, not cut.** The Ontology and every Rule carry a hand-written lean form beside their full text (`LEAN` blocks in `src/`), so a Rule's lean footprint is decided by its author and not by where its first full stop happens to fall — the earlier first-sentence cut shipped Rule II as one 36-character line and dropped its stop-and-ask mechanism. Only doctrine rules are still machine-cut to their heading plus first sentence.
+**Lean is authored, not cut.** The Ethos, every Rule and every doctrine rule carry a hand-written lean form beside their full text (`LEAN` blocks in `src/`), so a rule's lean footprint is decided by its author and not by where its first full stop happens to fall — the earlier first-sentence cut shipped Rule II as one 36-character line and dropped its stop-and-ask mechanism, and shipped a doctrine rule like *Change as little as the task requires.* as six words with no verb to act on.
 
 Both footprints put the full text on disk beside `AGENT.md`: `laws/`, `ontology/` and `doctrines/` all ship in the bundle at **full** text whatever the footprint, and **all four pack files ship whether or not the pack was built in** — which is what lets a citation into an inactive pack resolve. So lean is a context/token optimization, **not** a rules cut.
 
@@ -229,16 +239,16 @@ is **identical on every host**. What differs is how much of it the host can
 | **Skills** (byte-identical) | ✅ | ✅ | ✅ | ✅ |
 | **Memory & Notebook** | ✅ | ✅ | ✅ | ✅ |
 | **Context injection** | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ |
-| **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
-| **Git-gate consent** (process 5) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ (warn) |
-| **Rule-gate consent** (process 1) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ (warn) |
-| **Laws I / IV at the boundary** | ⚙️ plugin (block) | 🪝 hook (ask) | 🪝 hook¹ (exit 2) | 🪝 hook³ (block) |
+| **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ |
+| **Git-gate consent** (process 5) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ |
+| **Rule-gate consent** (process 1) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ |
+| **Laws I / IV at the boundary** | ⚙️ plugin (block) | 🪝 hook (ask) | 🪝 hook¹ (exit 2) | 🪝 hook³ (ask) |
 | **Sovereign-repo excludes** | ⚙️ plugin | ✅ `claudeMdExcludes` | ✅ rules-shadow | ➖ none |
-| **MCP server wiring** | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcpServers` | ✅ `mcp-config.json` |
+| **MCP server wiring** | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcp-config.json` |
 | **Colour themes** | ✅ full palette | ➖ | ➖ | ➖ |
 | **LSP · workflow runner · primary-agent · `/`-commands** | ✅ | ➖ | ➖ | ➖ |
 
-<sub>✅ native support · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 carried by preamble prose only · ➖ no host mechanism (harness discipline still applies) · ¹ Bob's own hook contract: global hooks in `~/.bob/settings/settings.json`, Claude's event names but stdout ignored on `PreToolUse` — a refusal is **exit code 2**. So Laws I/IV exit 2, the consent rules are a stderr line, `SessionStart` context is plain stdout, `Stop` runs learn; `SubagentStop`/`PreCompact` are not Bob events and are not written. Unverified live (no Bob install on the authoring machine); the harness still holds via the rules preamble. · ² OpenCode's `tool.execute.before` can only allow or throw, with no "ask the user" tier, so the rule gate is a one-shot speed bump there rather than a prompt. · ³ Copilot's `~/.copilot/settings.json` hooks (`sessionStart`, `toolCall`) wired by the **global** emit only; `toolCall` has no ask tier either, so Laws I/IV block and the two process rules warn on stderr. No learn: Copilot's end-of-session payloads carry no transcript.</sub>
+<sub>✅ native support · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 carried by preamble prose only · ➖ no host mechanism (harness discipline still applies) · ¹ Bob's own hook contract: global hooks in `~/.bob/settings/settings.json`, Claude's event names but stdout ignored on `PreToolUse` — a refusal is **exit code 2**. So Laws I/IV exit 2, the consent rules are a stderr line, `SessionStart` context is plain stdout, `Stop` runs learn; `SubagentStop`/`PreCompact` are not Bob events and are not written. Unverified live (no Bob install on the authoring machine); the harness still holds via the rules preamble. · ² OpenCode's `tool.execute.before` can only allow or throw, with no "ask the user" tier, so the rule gate is a one-shot speed bump there rather than a prompt. · ³ Copilot's `~/.copilot/settings.json` hooks (`sessionStart`, `preToolUse`, `agentStop`, `preCompact`) wired by the **global** emit only; `preToolUse` has an ask tier, so every rule asks as on Claude Code. Unverified live (no Copilot CLI on the authoring machine).</sub>
 
 **Reading the matrix.** Everything above the divider is at full parity — no host
 drops an Agent, Skill, or the memory convention. The asymmetry is entirely in
@@ -259,11 +269,11 @@ Token cost per host: **[docs/token-footprint.md](docs/token-footprint.md)**.
 Geneseed/
 ├── package.json          the npm package: three commands, zero dependencies
 ├── bin/                  the Node entry points — geneseed-cli.mjs (the CLI), geneseed-hook.mjs
-│                         (the four hook verbs), geneseed.mjs (the generator driver)
+│                         (the five hook verbs), build-driver.mjs (the generator driver)
 ├── js/                   the Node harness — generator, hooks, web server, doctor, installs
-│                         (js/cli-table.json is the CLI as data; both runtimes read it)
+│                         (js/cli-table.json is the CLI as data; the CLI reads it)
 ├── geneseed              launcher (bash): a shim over bin/geneseed-cli.mjs — bare `./geneseed`
-│                         = interactive main menu; + every subcommand the CLI carries
+│                         = the web console (else the command list); + every subcommand
 │                         (`./geneseed link` puts it on PATH so `geneseed` runs from anywhere)
 ├── geneseed.cmd          the same shim for cmd.exe / PowerShell — no bash needed
 ├── harness.config.json   default theme + metadata (the one owner of the version)
@@ -280,8 +290,7 @@ Geneseed/
 │   └── notebook/         the agent's own freeform space — convention + index
 ├── themes/               voice token maps (14 themes shipped)
 ├── web/                  Vite + React UI source; the committed web/dist/ build is what ships
-├── tests/                Node test suites + the pure-function/help recordings they replay
-│                         (tests/__snapshots__/ — the emit/cli/web corpora retired 2026-08-17)
+├── tests/                Node test suites, golden.mjs (every emit config) and mutate.mjs
 ├── docs/                 guides (web-ui, wiki, …) + docs/web/ (the console's Docs pages);
 │                         specs/, reviews/, superpowers/ are local working docs — git-ignored
 ├── adapters/             per-host glue (opencode/, claude-code/, bob/, copilot/)
@@ -292,7 +301,7 @@ Geneseed/
 
 ```bash
 node bin/geneseed-cli.mjs doctor      # every theme + parity + authoring + drift
-node --test "tests/**/*.test.mjs"     # the test suites (node expands the glob)
+node --test --test-reporter=tap "tests/**/*.test.mjs"   # the suites (node expands the glob)
 ```
 
 `doctor` checks each theme for unresolved tokens, dead/non-hermetic links, theme-key parity, author-time gates (every spec has a purpose line, the plugins parse, the learn-prompt literal stays extractable), and that a committed bundle still matches a fresh render of `src/`. CI (`.github/workflows/ci.yml`) runs both on every push and PR, on both Linux and Windows. Publishing is a separate, manually-triggered workflow (`.github/workflows/publish.yml`) — see [Contributing](#-contributing).
@@ -335,7 +344,7 @@ Details and precedence rules: [SETUP.md → Upgrade](SETUP.md#upgrade).
 | ⤷ [HOW-OPENCODE-LOADS.md](adapters/opencode/HOW-OPENCODE-LOADS.md) | Why a file shows up twice; plugin loading |
 | **[adapters/claude-code/](adapters/claude-code/README.md)** | The Claude Code hook adapter |
 | **[adapters/bob/](adapters/bob/README.md)** | The IBM Bob adapter — Claude-shaped, rules-file preamble |
-| **[adapters/copilot/](adapters/copilot/README.md)** | The GitHub Copilot adapter — reduced host, no hooks |
+| **[adapters/copilot/](adapters/copilot/README.md)** | The GitHub Copilot adapter — global hooks (`sessionStart`, `preToolUse`, `agentStop`, `preCompact`) |
 | **[src/memory/README.md](src/memory/README.md)** | The memory convention |
 | **[src/notebook/README.md](src/notebook/README.md)** | The agent's own freeform-space convention |
 
@@ -345,7 +354,7 @@ Issues and PRs welcome at [github.com/Arylmera/Geneseed](https://github.com/Aryl
 
 Three things that bite when you don't know them:
 
-- **`js/cli-table.json` IS the CLI.** The argument parser is data, and that file is the owned document — not a generated one. `bin/geneseed-cli.mjs` cannot parse a single verb without it, `bin/geneseed-hook.mjs` renders `--help` from it, and the console's `cli` docs page is a filtered view of it. What holds it honest is `tests/unit/cli_table.test.mjs` plus the recorded help texts under `tests/__snapshots__/help/`, which every verb's `--help` is rendered against — so change a flag here and the fixture for that verb is what tells you. Those recordings are frozen and cannot be re-taken; a red one is a finding, not a re-bless.
+- **`js/cli-table.json` IS the CLI.** The argument parser is data, and that file is the owned document — not a generated one. `bin/geneseed-cli.mjs` cannot parse a single verb without it, `bin/geneseed-hook.mjs` renders `--help` from it, and the console's `cli` docs page is a filtered view of it. What holds it honest is `tests/unit/cli_table.test.mjs` — change a flag here and that suite is what tells you.
 - **The version has one owner: `harness.config.json`.** `package.json` mirrors it and a test fails the fork. Never `npm version` — it edits one of the two.
 - **Publishing is deliberate and manual.** `.github/workflows/publish.yml` uses npm trusted publishing (OIDC); there is no `NPM_TOKEN` in this repository and there must not be one. It runs only from Actions → publish → Run workflow, and the npm-side trusted publisher is keyed on that workflow's **filename** — renaming the file breaks publishing with no local symptom, which is why the file names itself in its own header and a test asserts the two agree.