geneseed 3.12.0 → 3.14.0

package/docs/understand/on-your-machine.md

@@ -2,9 +2,11 @@
 group: understand
 order: 2
 title: "What lands on your machine"
-kind: "map"
+kind: "concept"
+section: "On your machine"
+description: "What an install writes and wires, and the four kinds of piece: enforced, automatic, asked, on demand."
 ---
-An install writes a handful of files into your host's config folder and, where the host allows it, wires small programs that run at fixed moments: when a session starts, before a tool call, when a session ends. Everything below says what each piece does for you, when it runs, what it costs, and how to turn it off. The **Kind** column uses four words:
+An install writes a handful of files into your host's config folder and, where the host allows it, wires small programs that run at fixed moments: when a session starts, before a tool call, when a session ends. The page for your host says what each piece does for you, when it runs, what it costs, and how to turn it off. Its **Kind** column uses four words:
 
 - **enforced**: code runs before the action and can stop it. The model cannot argue past it.
 - **automatic**: runs by itself at a fixed moment, such as session start or session end.
@@ -13,64 +15,19 @@ An install writes a handful of files into your host's config folder and, where t
 
 Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about 5k on the rules file. For a live figure on your own install, ask the agent to use the `token-report` skill.
 
-<!--harness:claude-->
-*(Claude Code only)*
+## One page per host
 
-| Piece | What it does for you | Kind | Cost | Turn it off |
-|---|---|---|---|---|
-| `CLAUDE.md` (managed block) | The rules, the pointers to agents and skills, and how memory works. Geneseed writes only its own block; your own lines in the file stay | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
-| `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
-| `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
-| context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `geneseed exclude add <folder>` silences every hook in that folder |
-| git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --` | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
-| rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory | enforced | ~14 ms per write | `geneseed exclude add <folder>` |
-| learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into `memory/`. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
-| `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
-| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
-| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` |
-| `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
-| hook shim | `~/.geneseed/bin/geneseed-hook`, the one stable path every hook calls, so moving the Geneseed checkout does not break your hooks | automatic | Nothing on its own | Not removed by uninstall, since every install on the machine shares it. `GENESEED_HOME` moves it |
-
-<!--/harness-->
 <!--harness:opencode-->
 *(OpenCode only)*
 
-| Piece | What it does for you | Kind | Cost | Turn it off |
-|---|---|---|---|---|
-| `AGENT.md` | The rules, the pointers to agents and skills, and how memory works | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
-| `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
-| `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
-| `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`, and before every commit and push when the **process** pack is on | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
-| context plugin | Puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `GENESEED_CONTEXT_INJECT=off` |
-| guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block |
-| learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into `memory/` with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
-| activity plugin | Writes one small file per session that the web console's Activity view shows | automatic | No tokens | `GENESEED_ACTIVITY=off` |
-| notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
-| ponytail plugin | Minimal-code mode. `/ponytail lite`, `full` or `ultra` adds a short ruleset to every turn until you switch it off | on demand | 0 while off, which is the default | `/ponytail off` |
-| workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
-| `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
-| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
-| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` |
-| `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
+- [On OpenCode](machine-opencode.md): the plugins and the `opencode.json` entries, piece by piece.
 
 <!--/harness-->
+<!--harness:claude,openclaude-->
+*(Claude Code and OpenClaude only)*
 
-### Where the files are
-
-**OpenCode.** A global install writes to `~/.config/opencode/`. Setting `OPENCODE_CONFIG_DIR` or `XDG_CONFIG_HOME` moves it. Geneseed merges its entries into your existing `opencode.json` and keeps every other key. A per-repo install writes into the repo instead.
-
-**Claude Code.** A global install writes to `~/.claude/`, and its hooks go into `~/.claude/settings.json`, next to any hooks of your own. A per-repo install uses the repo's `.claude/` folder, with the hooks in `.claude/settings.local.json`.
-
-**Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for credentials and destructive git. The commit/push and memory questions become log lines.
-
-**OpenClaude.** Same pieces as Claude Code, under `~/.openclaude/` or `OPENCLAUDE_CONFIG_DIR`. A per-repo install uses `.openclaude/`, with the hooks in `.openclaude/settings.local.json`.
+- [On Claude Code and OpenClaude](machine-claude.md): the hooks in `settings.json`, piece by piece.
 
-**Plain bundle.** The `files` target writes `AGENT.md` and the same folders into `./Harness/` for any tool that reads `AGENT.md`. It installs no hooks and no plugins, so nothing in it is enforced.
-
-### Taking it back out
-
-`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
-
----
-
-**Next:** [A day with the harness](a-day.md)
+<!--/harness-->
+- [On Bob, or any AGENT.md tool](machine-bob.md): where the files go, and what is enforced there.
+- [Taking it back out](take-it-out.md): what `geneseed uninstall` removes, and what it keeps.

package/docs/understand/take-it-out.md

@@ -0,0 +1,13 @@
+---
+group: understand
+order: 6
+title: "Taking it back out"
+kind: "concept"
+section: "On your machine"
+description: "What geneseed uninstall removes, and what it keeps for you."
+---
+`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
+
+---
+
+**Next:** [A day with the harness](a-day.md)

package/docs/web-ui.md

@@ -111,27 +111,47 @@ streams the output of background jobs and keeps their history across reloads.
   **Promote to rule** control turns a recurring lesson into a trial rule in
   `user-rules.md` — provenance recorded, the source fact deleted so it isn't loaded
   twice — landing you on the Rules page.
-- **Loops** (`#/loops`) — the loop catalogue `geneseed loop` runs from, read-only.
-  **Templates** draws the selected template as a ring: the iteration turning clockwise from
-  its head, each inner retry loop hung outside on its head node, the ⛨ *validate* gate the
-  engine adds before the first mutate step, setup entering from the left and `done → close`
-  leaving from the head; a card per brick sits under it, and clicking a node scrolls to its
-  card. A graph a ring cannot draw cleanly (more than eight iteration steps, a node in more
-  than three loops) falls back to left-to-right boxes. **Bricks** lists every brick with its
-  origin (shipped / global / project), what it overrides, why it is unavailable, and its
-  source. **Active** (live runs) is announced for v2 and disabled. Reads `GET /api/loops`,
-  resolved from the selected install's root, so a project install shows its
-  `.geneseed/` bricks and templates.
+- **Loops** (`#/loops`) — the loop catalogue `geneseed loop` runs from, read-only, laid out
+  like the Library: a rail of sections (**Templates**, **Bricks**, **Active**, each with its
+  count; `#/loops/<section>/<item>` opens an entry), with the selected section's groups
+  nested under it in the rail (template categories, brick origins, run statuses — pick one to
+  narrow the list), a filterable list, and a reader.
+  **Templates** are grouped by their `category` (architecture, tests, development,
+  refactoring, day-to-day, then *Other*), a *human gate* pill on any that stops for you. The
+  reader draws the selected template as a ring: the iteration turning clockwise from its head,
+  each inner retry loop hung outside on its head node, the ⛨ *validate* gate the engine adds
+  before the first mutate step, setup entering from the left and `done → close` leaving from
+  the head; its `rules` follow, then a compact row per brick (effect, agent or skill, outcomes,
+  human gate), and clicking a node scrolls to and lights its row. A graph a ring cannot draw
+  cleanly (more than eight iteration steps, a node in more than three loops) falls back to
+  left-to-right boxes. **Bricks** are grouped by origin (project / global / shipped), pilled
+  for *mutate*, *human gate*, what they override and *unavailable*; the reader shows the
+  frontmatter facts (outcomes as pills, availability with its reason), then the body rendered as
+  markdown, with a **View source** toggle for the file as parsed, frontmatter and all. Templates and
+  Bricks read `GET /api/loops`, resolved from the selected install's root, so a project
+  install shows its `.geneseed/` bricks and templates. **Active** is every loop
+  `geneseed loop init` registered on this machine (`GET /api/loops/active`, polled every
+  5 s), grouped awaiting, running, done/stopped, finished/unreadable; the reader shows its
+  branch, `iteration N / max`, current node and a preset picker (`POST /api/loops/preset`,
+  the page's only write), what an awaiting loop waits on (launch / declared / actual / a
+  human gate, with its node) — the answer is given in the agent's session, never here — and
+  its ring with the current node filled, with its iteration history under it.
 - **Profile** (`#/profile`) — `PROFILE.md` beside the deployed AGENT.md: who you are and
   how you like to work. Opens rendered; **Edit** is a whole-file editor. The save carries
   the fingerprint it loaded — if an agent session changed the file first, your edit stays
   on screen and a second Save replaces the newer version.
 - **Skills** (`#/skills`) and **Agents** (`#/agents`) — the deployed catalogue, each entry
-  with its purpose line and full spec.
+  with its purpose line and full spec. While Skills is selected, its skill types sit nested
+  under it in the rail, each with its count, above a thin bar of their shares; pick one to
+  narrow the list.
 - **Docs** (`#/docs`) — rendered documentation: markdown pages, concept pages, a CLI
-  reference (generated from the harness argument parser), and a glossary, grouped into
-  Get started / Core concepts / How-to / MCP servers / Plugins / Reference / Deeper. Filtered
-  for one host family (OpenCode, or Claude Code — which Bob and OpenClaude share); with no
+  reference (generated from the harness argument parser), and a glossary, in the Library's
+  three panes: the parts (Understand / Guides / Concepts / Reference) with their page counts,
+  the open part's sections nested under it in the rail (pick one to narrow the list), the
+  part's pages under their sections with a filter, and the page with its breadcrumb,
+  outline and Previous / Next within the section. Filtered for one host (OpenCode, Claude
+  Code, Bob or OpenClaude; Claude-family pages show to all three Claude-engine hosts, a page
+  tagged with a list of hosts only to those); with no
   choice stored it follows the deployed install.
 
 ### 🩺 Care

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.12.0"
+  "version": "3.14.0"
 }

package/js/README.md

@@ -1,6 +1,6 @@
 # `js/` — the module map
 
-Sixty-one modules in eight folders. This page is the address book: **what each one owns**, and
+Sixty-six modules in eight folders. This page is the address book: **what each one owns**, and
 **which file to open first** for a given task. It is not documentation of behaviour — every module
 has a docblock for that, and the docblock is the thing to read before editing.
 
@@ -46,7 +46,8 @@ as a per-host install at project or global scope.
 | `emit-common.mjs` | Constants, tree walkers, and the three writers BOTH global emits share. Decides no host |
 | `stubs.mjs` | Write-once seed files: context, wiki, rules, excludes, profile, `.gitignore`, memory/notebook indexes |
 | `version.mjs` | The release marker: fingerprint the sources, read/compare/write an install's version, warn on downgrade |
-| `driver.mjs` | The generator driver: `--emit`/`--theme`/`--footprint` flag parsing, the nine emit targets, per-host emit orchestration, the prune and the manifest. `bin/build-driver.mjs` is only its entry |
+| `driver.mjs` | The generator driver: the nine emit targets, per-host emit orchestration, the prune and the manifest. `bin/build-driver.mjs` is only its entry |
+| `args.mjs` | The generator's flag surface: `harness.config.json` defaults, the `--emit`/`--theme`/`--footprint` parse tables and choices, `-h`, and `die` (a throw, so `rebuild-all` survives one bad install) |
 | `generate.mjs` | CLI verbs `build`, `prompt`, `theme`, `rebuild-all` — the thin face over `driver.mjs` |
 | `catalog.mjs` | `geneseed catalog` — prints the shipped roster. Classifies nothing itself |
 | `themes.mjs` | Maintainer-only `--sync-themes`: inserts `_TEMPLATE.json`'s missing keys into the committed themes |
@@ -67,19 +68,25 @@ user co-owns, and the hook verbs those emitted configs then run.
 
 | module | owns |
 |---|---|
-| `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), plus `resolvePath`/`expanduser` |
-| `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), `learn`. `--host` picks the verdict dialect |
+| `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), their `family` (`CLAUDE_STYLE`), plus `resolvePath`/`expanduser` |
+| `hooks.mjs` | The gate verbs, run on every tool call: `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), plus `ask`/the gate ledger/`guardGate`. `--host` picks the verdict dialect |
+| `hooks-context.mjs` | The `context` verb — SessionStart: session files plus the repo's context docs |
+| `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
+| `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`) |
+| `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate. No spawn: the CLI and web console import it |
 | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `currentBranch`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate and `js/loop/cli.mjs`'s commit-message writer |
-| `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json`; owns the hook shim and the managed blocks |
+| `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json` (one `loadJsonObject` reader for all of them) and the managed blocks |
+| `shim.mjs` | The machine-wide hook shim: its path, body, liveness (`shimDead`, read on every CLI run), `hookPrefix`/`hookRunnerEntry`. Kept cheap to import |
 | `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
 | `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
 | `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
 | `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
 | `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
 
-**Before editing:** `hooks.mjs` **is the hook path** — the verdict travels as JSON on stdout and
+**Before editing:** `hooks*.mjs` **are the hook path** — the verdict travels as JSON on stdout and
 every arm exits 0, so one stray printed byte turns a blocking gate silently permissive, and anything
-imported here is paid on every tool call. `hosts.mjs` is shared by the generator, the CLI and the
+`hooks.mjs` or `hooks-prims.mjs` imports is paid on every tool call. `bin/geneseed-hook.mjs` loads
+one verb's module per process, so keep context and learn code out of the gate module. `hosts.mjs` is shared by the generator, the CLI and the
 hook path, so it must stay free of `child_process`. `installs.mjs` reads through `readMaybe`, which
 folds CRLF — a bare `readFileSync` here is a bug.
 
@@ -92,8 +99,10 @@ Everything that inspects an already-built or already-deployed harness and report
 | `doctor.mjs` | The `geneseed doctor` **driver** only: picks themes, runs the checks, prints the verdict |
 | `checks-build.mjs` | Gates over what the build PRODUCED: links, tokens, theme parity, OpenCode colours, bundle drift |
 | `checks-repo.mjs` | Gates over the repo's own records: `registry.json`, committed secrets, the hook shim, vendored pins |
-| `checks-authoring.mjs` | Self-consistency: law/doctrine metadata, constitution numbering, the counts README and the web quote |
-| `scan.mjs` | The shared walk/sort/strip/test primitives all three `checks-*` use. Owns no judgement itself |
+| `checks-authoring.mjs` | `authoringProblems`, the aggregate self-consistency gate: spec purpose lines, the learn-prompt literal, `node --check` over the plugins (the doctor's one spawn), then the groups below |
+| `checks-constitution.mjs` | The constitution: rule declarations and citations, LEAN blocks, `HOOK_PINNED`, theme vocabulary, the console's `LAW_META`/`DOCTRINE_META` |
+| `checks-counts.mjs` | The hand-written counts: AGENT.md tables, README badges and prose, `SHIPPED.md`, held against `src/` |
+| `scan.mjs` | The shared walk/sort/strip/test primitives every `checks-*` uses. Owns no judgement itself |
 | `validate.mjs` | The `--validate-only` verb: renders a sandbox, scans it for tokens and dead links, own exit contract |
 | `inventory.mjs` | The one catalog walk and its taxonomy tables, read by status, the TUI and the web console |
 | `status.mjs` | `geneseed status` and `version` — the panel data, counts, accent colour, version verdict |
@@ -140,12 +149,20 @@ transition, score and stop is computed here.
 | `catalog.mjs` | `loadCatalog` — bricks and loop templates from shipped/global/project origins, later overrides earlier BY NAME |
 | `state.mjs` | The engine itself: `initState`, `nextStep`, `scoreDeclared`/`scoreDiff`, `recordOutcome`, `decideAwaiting`, `renderLoopFile`/`parseLoopFile` |
 | `cli.mjs` | `geneseed loop check\|init\|next\|score\|record\|decide` — the only face either a model or a human reaches this engine through |
+| `registry.mjs` | `loops.json` under XDG — the launched-loop identity list `loop init` records into and the Active tab's `activeLoops`/`setLoopPreset` read and rewrite |
 
 **Before editing:** `score.mjs` is imported by the build driver (the `--trust` choices), so it must
 stay free of every import but node builtins and `graph.mjs`. `state.mjs` excludes `LOOP.md` itself
-from every score and every read-brick porcelain check — it is the engine's own bookkeeping, never
-part of the work being scored. `cli.mjs` may not spawn: git output is piped in on stdin by the
-model, never read by this entry.
+(and its own atomic-write sibling, `LOOP.md.tmp`) from every score and every read-brick porcelain
+check — it is the engine's own bookkeeping, never part of the work being scored. Every LOOP.md
+write goes through `state.mjs`'s `writeLoopFile`, never a bare `writeText`, so a killed process
+cannot leave a torn file. `cli.mjs` may not spawn: git output is piped in on stdin by the model,
+never read by this entry. `registry.mjs` swallows its own errors on `recordLoop`/`activeLoops` on
+purpose, like `js/inspect/registry.mjs` — a registry hiccup must never fail `loop init` or a
+read — but `setLoopPreset` does not: a preset change the caller asked for must be reported when it
+fails. `activeLoops` saves the registry back only when the kept set actually changed (a pruned
+root, a loop newly seen finished or seen running again) — a routine poll from the Active tab must
+never be a write.
 
 ## `js/maintain/` — lifecycle
 
@@ -212,7 +229,7 @@ and inline lists are held against a surface list written out in
 | a doctor check | `js/inspect/checks-{build,repo,authoring}.mjs` | register with `ran(...)` in `doctor.mjs`, then a PLANTED FAULT in `tests/unit/harness.test.mjs` |
 | a web endpoint | GET → `js/web/api.mjs`; POST → `js/web/actions.mjs` | declare it in `js/web/routes.mjs`; the partition test probes the real handler |
 | a CLI verb | `js/cli-table.json` — the table IS the parser | the `VERBS` row in `bin/geneseed-cli.mjs`, the row count in `cli_table.test.mjs`, `NATIVE` in **two** test files |
-| a hook verb | `js/hosts/hooks.mjs` | `claudeHookGroups` in `settings.mjs`, `VERBS` in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
+| a hook verb | `js/hosts/hooks.mjs` (a gate) or its own `js/hosts/hooks-<verb>.mjs` | `claudeHookGroups` in `settings.mjs`, the `VERBS` row (with its `load`) in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
 | a console doc page | `docs/<understand|guides|concepts|reference>/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
 | an OpenCode plugin | `adapters/opencode/plugins/geneseed-<name>.js` | `docs/extending.md` §4a — the `geneseed-` prefix is mechanically load-bearing |
 | to change a `js/lib/` primitive | `tests/fixtures/pure_probe.mjs` **first** | the docblock says which Node default it deliberately departs from — change that sentence too, or the next reader restores the default |