geneseed 3.12.0 → 3.14.0

package/CHANGELOG.md

@@ -8,6 +8,166 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.14.0] — 2026-10-04
+
+**Upgrading:** re-emit (`geneseed rebuild-all`) so installed hooks pick up the gate fixes and the
+per-verb hook modules; then `geneseed web restart`.
+
+### Security
+- **Sealed Secrets gate** — `sk-ant-` keys containing `_` (base64url, most real keys) no longer
+  slip past; `MultiEdit` (`edits[].new_string`) and `NotebookEdit` (`notebook_path`/`new_source`)
+  are now scanned like `Write`/`Edit`.
+- **Destructive-git gate** — catches `git push -f`, `git push origin +main`, `git reset -q --hard`
+  and `git clean -d -f` (flags anywhere after the verb); `LAW_IV_BASH` mirrors it.
+- **Memory names** — a model-written memory `name:` that is not a plain slug is refused instead
+  of becoming a path outside the memory dir (Claude `learn` hook and the OpenCode learn plugin).
+- **Uninstall** — manifest paths are contained to the install dir before unlinking (as deactivate
+  already did); empty-directory pruning stops at the base.
+
+### Fixed
+- `--exclude-rules` is carried through every re-render: `geneseed diff` no longer reports drift on
+  an install with excluded rules, console Restore and `geneseed migrate` no longer re-admit them,
+  and `validate` honours every render axis. Unknown ids in `harness.config.json` now warn and are
+  dropped instead of breaking every later rebuild.
+- Claude `settings.json` that is not a JSON object, or unreadable, is refused instead of
+  overwritten; every JSON config write is atomic.
+- Loop: a malformed `record --card` is refused before it can wedge the loop; `check` resolves
+  bricks from the git root; `next` no longer rewrites `LOOP.md`; a clean tree is recognised.
+- Console: the Docs host selector follows the deployed install instead of sticking to OpenCode;
+  the About page shows the installed and source fingerprints; the outline strips inline markdown.
+- `theme --transparent-only` names the file it wrote; `validate --help` prints its own usage.
+- Doctor's module-map check keys by folder, so twin module names can no longer hide a missing row.
+- `learn` reports on stderr when it cannot start the model CLI.
+
+### Changed
+- The hook binary loads one verb's module per call (`hooks.mjs` gates, `hooks-context.mjs`,
+  `hooks-learn.mjs`): gate cold import ~16 → ~10 ms, on every tool call. The memory-file helpers
+  live in the no-spawn `memory-files.mjs`, so the CLI no longer reaches `child_process`.
+- Internal splits: `js/hosts/shim.mjs`, `js/build/args.mjs`, `checks-constitution.mjs`,
+  `checks-counts.mjs`; one JSON-object reader and one `CLAUDE_STYLE` host list; dead code and
+  Python-era comments removed.
+
+## [3.13.0] — 2026-10-04
+
+**Upgrading:** re-emit (`geneseed rebuild-all`) so the installed `loop` skill knows the new
+templates, human gates and note files; then `geneseed web restart` (and a hard reload) for the
+new Loops and Docs pages.
+
+### Added
+- **Template `category`** — `architecture`, `tests`, `development`, `refactoring` or `day-to-day`;
+  every shipped template carries one, and the console's Loops page groups templates by it.
+- **Five loop templates** — `tdd` (plan, then write each failing test before the code that passes
+  it), `legacy-tests` (pin undocumented behaviour with characterization tests, mutation-checked,
+  production code untouched), `legacy-refactor` (pin current behaviour once, then refactor behind
+  that net), `deps-upgrade` (upgrade one package or group per iteration, breaking changes read
+  before the bump, lockfiles excluded from the deletion count so their churn doesn't force a
+  blocking score), and `ci-repair` (triage the current commit's failing CI checks and fix one
+  code failure per iteration).
+- **Five bricks** backing the templates above — `red-test`, `characterize`, `mutation-check`
+  (reports `unavailable` rather than a silent `pass` when no mutation tool is on the stack),
+  `upgrade-scout`, `ci-triage` (reports `done` rather than green when CI has no run for HEAD).
+- **`geneseed loop record --note` / `--note-file`** — carries a `read` brick's finding (a plan, a
+  review finding, a mutation gap, a CI classification) into `LOOP.md`'s notes so it survives into
+  the next brick and the next iteration; `--note-file` for anything multi-line or that mentions
+  `git commit`/`push`, which a shell argument can't carry safely.
+- **Console: Loops › Active tab** — every loop `geneseed loop init` has launched, discovered via a
+  new **loop registry** (`$XDG_CONFIG_HOME/geneseed/loops.json`, identity only — `LOOP.md` stays
+  the source of state) instead of a worktree scan. `GET /api/loops/active` reports each loop's
+  branch, status, iteration, current node and preset; a card per loop, an `awaiting` loop
+  highlighted with what it's waiting on (answered in the agent's session, never the page),
+  finished loops kept muted for 7 days. Selecting a card draws its ring with the current node and
+  its iteration history. A per-loop preset picker (`POST /api/loops/preset`) rewrites `LOOP.md`'s
+  `preset`, applying from the next score on — the tab's only write; no `decide` and no relaunch
+  from the page. Only loops launched on this version or later are registered.
+
+- **Seven more loop templates** — `architecture-decision` (one ADR per decision, challenged by a
+  skeptic brick, reviewed by the user), `enforce-architecture-rule` (encode a rule as a test with
+  an allowlist of today's violations, fix one violation per iteration), `update-contract` (expand,
+  migrate one consumer per iteration, contract, with contract files gated for a human by default),
+  `spec-first-feature` (write the spec first, build one task per iteration, closed by an
+  independent `done-check`), `api-endpoint` (plan, apply, test, a Bruno request and a security
+  review per endpoint), `remove-dead-code` (confirm green, delete one coherent unused group per
+  iteration, deletions scored soft) and `fix-flaky-tests` (confirm by repeated runs, fix the root
+  cause per iteration, never a retry or a sleep).
+- **Nine bricks** backing the templates above — `adr-draft`, `adr-challenge`, `fitness-define`,
+  `migration-plan`, `spec`, `done-check`, `compat-check`, `flake-repro`, `flake-check`.
+- **Human gates** — a brick's frontmatter can carry `gate: human` (optionally `gateOn:
+  <outcomes>`), holding its transition for a person regardless of preset or score. `geneseed loop
+  decide --verdict ok|no|amend` answers it: `ok` follows the reported outcome (a held failure
+  still stops), `no` stops the loop, `amend` re-runs the brick with a note and restarts its ring
+  budget, capped at 3 amends per brick per iteration. A passed gate is named under the closing
+  commit's new `Loop-Gates` trailer. In the console, a gated brick carries a person badge on the
+  loop ring ("Human gate", or "Human gate on pass") and a "human gate" tag in its rows, and the
+  Active section shows a gated loop as `Awaiting gate at <node>`.
+- **Template `contracts` and `ignoreDeletions` globs** — `contracts` names interface/schema files
+  that always escalate a touching iteration to at least the `api` risk weight; copied from the
+  template at `loop init`, extendable with `--contracts` or by hand in `LOOP.md`.
+  `ignoreDeletions` excludes matched files from the >20-deleted-lines escalation only — the write
+  set still applies to them.
+- **`rules` on every node** — a template may carry `rules`, a list of one-line instructions
+  (`loop check` refuses anything else); `geneseed loop next` hands them to every brick it runs,
+  not only the iteration head, so a template-wide proviso is visible everywhere, including to
+  `review`. `description` stays the catalogue blurb and is never sent as rules. The shipped
+  templates' instructions moved out of their descriptions into `rules`.
+- **A guide to running a loop** — `docs/guides/run-a-loop.md`, `loop-running.md` and
+  `loop-finish.md`: what you need, how to ask, which template for which job, the trust preset,
+  answering a blocking score or a human gate, watching, stopping, merging, driving the engine by
+  hand, and a symptom table.
+- **Console: rendered brick view** — the Loops page's Bricks reader renders a brick's body as
+  markdown under its facts (effect, outcomes, gate), with the raw source one click away.
+
+### Changed
+- **Categories nest under the selected rail entry** — on the Library (skill types), Docs
+  (sections) and Loops (template categories, brick origins, run statuses) pages, a selected
+  entry's categories open in the rail beneath it, with counts and a share bar, replacing the
+  full-width banner above the page.
+- **The Docs selector names all four hosts** — OpenCode, Claude Code, OpenClaude and IBM Bob. A
+  page or inline block tagged with a family still shows to every host in it; a page can now name
+  several hosts (`harness: ["claude", "openclaude"]`), so Bob no longer sees the Claude Code /
+  OpenClaude machine page.
+- **Docs in the Library layout** — the console's Docs tab is a rail of parts (Understand, Guides,
+  Concepts, Reference), a filterable list grouped by section, and a reader with a breadcrumb,
+  the page's outline and Previous / Next within its section. Pages carry a new `section` and
+  `description` in their frontmatter.
+- **Long doc pages split into short ones**, each a section of its part: the install guide (one
+  page per host, from a clone, without the wizard), what lands on your machine (one page per
+  host, taking it back out), troubleshooting (installing, hooks, updating, doctor, web console),
+  the OpenCode plugins (one page per plugin), loops (templates, bricks, notes and rules, risk,
+  human gates, contracts, the loop branch) and the run-a-loop guide. The `geneseed loop` actions
+  table moved to Reference. Then the rest of the long ones: choose your setup (voice and working
+  style · doctrine packs and single rules · footprint, loop trust and changing later), MCP servers
+  (a hub, one page per preset, reading non-markdown docs; the won't-connect checklist moved to
+  Troubleshooting), hooks (the hooks · gates, settings and the shim), environment variables (the
+  context and memory ones on their own page; plugin switches live on each plugin's page), the
+  host capability matrix, and which loop template. Every first page keeps its old address.
+- **The Understand track has more pages** — what lands on your machine is now one page per host
+  plus taking it back out, so a returning reader's "New here?" progress shows the new steps
+  as unread.
+- **Console Loops page in the Library layout** — a rail (Templates · Bricks · Active, with
+  counts) replaces the tabs; each section is a filterable list grouped like the Library's
+  (templates by `category`, bricks by origin, active loops by status, awaiting first) beside a
+  detail pane: the ring, the template's `rules`, and its bricks as compact rows that a click on a
+  ring node highlights. Inner-ring nodes no longer overlap (`api-endpoint`).
+- **`feature`** now closes through an independent `done-check` — it maps every requirement to a
+  passing test before `$close` instead of trusting the iterations that already ran.
+- **`deps-upgrade`** marks lockfiles with `ignoreDeletions` instead of a lowered `delete` weight,
+  so lockfile churn stays out of the deletion count without lowering the weight for any other
+  deletion in the same iteration.
+- **Write-set entries accept globs** when they have at least one literal path segment (a tool's
+  generated store, say); a wildcard-only entry (`**`, `**/*.java`) still matches nothing rather
+  than declaring the whole repo writable.
+
+### Fixed
+- **Skill and agent descriptions follow the skill-authoring rules** — no trigger sentence is cut
+  mid-way in any theme, and no description carries XML-like tags (#179).
+- **The install page no longer scrolls on open** — the reader's own host is lit (its link on the
+  Install page, its scope's heading on the OpenCode page) without moving the page.
+- The bricks README link on the loops page pointed at a repository that does not exist; the
+  console's wiki button opened a docs page that does not exist.
+- A read-setup brick's plan or review findings no longer vanish between steps — `record --note`
+  / `--note-file` writes them into `LOOP.md`'s notes instead of leaving them in the brick's own,
+  discarded context.
+
 ## [3.12.0] — 2026-10-03
 
 **Upgrading:** re-emit after installing (`geneseed rebuild-all`) to get the `loop` and

package/README.md

@@ -41,7 +41,7 @@ A hand-written instructions file is prose the model may or may not honour, copie
 - **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. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — four short pages on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
+This page is the overview. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — a short course on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
 
 ---
 
@@ -199,7 +199,7 @@ Pick with `--theme NAME` or via the setup wizard; upgrades remember it. More in
 
 ### 🪶 Footprint (lean vs full)
 
-A second per-install dial sets how much of the constitution the root file carries *inline* every turn — a token-cost knob, not a change to which Rules apply. **lean** (the default) carries each rule's hand-written short form and points to the full text on disk; **full** inlines every rule with its rationale. Every rule is in force either way. More in [Footprint](docs/concepts/footprint.md) and [Choose your setup](docs/guides/choose-your-setup.md).
+A second per-install dial sets how much of the constitution the root file carries *inline* every turn — a token-cost knob, not a change to which Rules apply. **lean** (the default) carries each rule's hand-written short form and points to the full text on disk; **full** inlines every rule with its rationale. Every rule is in force either way. More in [Footprint](docs/concepts/footprint.md) and [Footprint, loop trust and changing later](docs/guides/setup-footprint.md).
 
 ---
 

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.12.0**.
+> string. Current label: **3.14.0**.
 
 ## Capabilities
 

package/adapters/bob/README.md

@@ -1,6 +1,6 @@
 # 🤖 IBM Bob adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-bob.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
 
 [IBM Bob](https://bob.ibm.com) is **Claude-Code-shaped**: a project `.bob/`
 layer, an `AGENTS.md` instructions file, `SKILL.md` skills, subagents, and a

package/adapters/claude-code/README.md

@@ -1,6 +1,6 @@
 # 🪝 Claude Code adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-claude-code.md) · [OpenCode adapter](../opencode/README.md)
 
 Optional. Claude Code supports lifecycle **hooks**, so a team using it can make
 parts of the harness fire automatically instead of relying on agent

package/adapters/openclaude/README.md

@@ -1,6 +1,6 @@
 # 🦀 OpenClaude adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-openclaude.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
 
 [OpenClaude](https://openclaude.gitlawb.com/) (`@gitlawb/openclaude`, binary
 `openclaude`) is an open-source coding-agent CLI that "originated from the Claude

package/adapters/opencode/README.md

@@ -1,6 +1,6 @@
 # 🔌 OpenCode adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [How OpenCode loads](HOW-OPENCODE-LOADS.md) · [Global harness spec](GLOBAL-HARNESS-SPEC.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-opencode.md) · [How OpenCode loads](HOW-OPENCODE-LOADS.md) · [Global harness spec](GLOBAL-HARNESS-SPEC.md)
 
 [OpenCode](https://opencode.ai) is `AGENTS.md`-native and has first-class
 **subagents** and **commands**, so Geneseed fits it cleanly. Pick the depth you
@@ -468,9 +468,9 @@ OpenCode runs, so the command has to resolve — the `uvx` form above needs only
 call). No uv? `pipx install markitdown-mcp` and swap the command to `["markitdown-mcp"]`.
 Or drop the block entirely — the skill falls back to a CLI converter (MarkItDown /
 Pandoc / Docling) and never installs one silently. Listed but not connecting? The
-command isn't on PATH — see [the MCP guide](../../docs/guides/mcp.md).
+command isn't on PATH — see [Model, agent and MCP problems](../../docs/reference/troubleshoot-tools.md).
 Full runbook, including the corporate-TLS (`UV_SYSTEM_CERTS`) step and the OCR extras:
-[the MCP guide](../../docs/guides/mcp.md).
+[the MarkItDown guide](../../docs/guides/mcp-markitdown.md).
 
 ## Optional add-on — git-worktree isolation (third-party, not vendored)
 

package/adapters/opencode/plugins/geneseed-learn.js

@@ -251,6 +251,11 @@ function parseFrontmatter(chunk) {
   return fm
 }
 
+// A memory `name:` becomes a FILENAME and the model writes it, so it is a plain slug or
+// nothing — no separator, no `..`, no drive. The same rule as MEMORY_SLUG_RE in
+// js/hosts/hooks.mjs, inlined because this file ships standalone.
+const MEMORY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/
+
 async function writeMemories(output, memDir, existing) {
   const written = []
   const indexLines = []
@@ -259,7 +264,7 @@ async function writeMemories(output, memDir, existing) {
     if (!chunk || chunk.toUpperCase() === "NOTHING") continue
     const fm = parseFrontmatter(chunk)
     const name = (fm.name || "").trim()
-    if (!name || existing.has(name)) continue
+    if (!MEMORY_SLUG_RE.test(name) || existing.has(name)) continue
     await fs.writeFile(path.join(memDir, `${name}.md`), chunk.replace(/\n+$/, "") + "\n", "utf8")
     existing.add(name)
     written.push(name)
@@ -393,4 +398,8 @@ export const GeneseedLearn = async ({ client }) => {
   }
 }
 
+// OpenCode treats every export as a plugin and rejects non-functions; hang the test
+// helpers off the factory instead — reachable via import, invisible to the loader.
+Object.assign(GeneseedLearn, { writeMemories })
+
 export default GeneseedLearn

package/bin/geneseed-cli.mjs

@@ -58,7 +58,7 @@
 import '../js/lib/node-floor.mjs';
 import { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
 import { parseIntStrict } from '../js/lib/text.mjs';
-import { printErr } from '../js/lib/fs.mjs';
+import { printErr, printOut } from '../js/lib/fs.mjs';
 
 /**
  * The verbs this entry answers — and, since P10c, NOTHING ELSE ABOUT THEM.
@@ -302,7 +302,7 @@ async function main(argv) {
   // that binary is never reached, and its import graph is paid on every tool call.
   if (process.env.GENESEED_NO_SHIM_CHECK !== '1' && verb !== 'help'
     && !argv.some((t) => t === '-h' || t === '--help')) {
-    const { shimDead } = await import('../js/hosts/settings.mjs');
+    const { shimDead } = await import('../js/hosts/shim.mjs');
     const dead = shimDead();
     if (dead.length) {
       printErr(`[geneseed] ⚠ hooks are off on this machine: the hook shim points at `
@@ -311,25 +311,21 @@ async function main(argv) {
     }
   }
   // `validate` — the generator's `--validate-only`, and the one verb this entry answers that is NOT
-  // in the table above. It is dispatched here, before the lookup, for a reason that is a
-  // property of the gates rather than a preference:
-  //
-  //   * `VERBS` is asserted to be the twin of `rituals/harness.py`'s SUBPARSERS
-  //     (`test_every_entry_verb_is_a_real_harness_subcommand`), and `--validate-only` is a
-  //     GENERATOR flag — `harness.py` has never had a `validate` subcommand to be a twin of;
-  //   * `test_the_matrix_covers_every_verb_it_claims` demands a recorded cell group per table
-  //     row, and a cell has an `lf` half this host cannot produce.
-  //
-  // So a row would have meant amending two gates and recording a corpus half blind. It takes
-  // the generator's own parser (see `parseDriverArgs`) because its flags are the generator's,
+  // in the table above. It is dispatched here, before the lookup, because its flags are the
+  // GENERATOR's, not a table row's: it takes the generator's own parser (see `parseDriverArgs`),
   // and it is on THIS binary — not on `bin/build-driver.mjs` — because it runs the doctor, which
   // starts a process the driver is banned from reaching.
   if (verb === 'validate') {
     // Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
     // generator driver in, and every OTHER verb was paying for it.
-    const [{ cmdValidate }, { parseDriverArgs }] = await Promise.all([
+    const [{ cmdValidate, VALIDATE_USAGE }, { parseDriverArgs }] = await Promise.all([
       import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
     ]);
+    // Before the borrowed parser, whose own `-h` prints the GENERATOR's usage.
+    if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
+      printOut(VALIDATE_USAGE);
+      return 0;
+    }
     try {
       return cmdValidate(parseDriverArgs(argv.slice(1)));
     } catch (e) {

package/bin/geneseed-hook.mjs

@@ -27,9 +27,10 @@
  * component — so the last driver to emit anything on a machine owns every install's hooks,
  * including installs the other driver wrote. That is safe exactly while the two entry
  * points answer the same verbs identically, which is not a hope:
- * `test_the_entry_carries_exactly_the_verbs_the_emitter_wires` pins the verb set to the
- * hooks the emitter wires, and `tests/harness_golden.py` runs this binary as a process
- * against the Python one on stdout, stderr, exit code and every file written.
+ * `tests/unit/hook_cli.test.mjs`'s "the hook entry carries exactly the verbs the emitter wires"
+ * pins the verb set to the hooks the emitter wires, and `node tests/golden.mjs --cli` runs
+ * this binary as a process with absolute assertions on stdout, stderr, exit code and every file
+ * written.
  *
  * The verb set is deliberately SMALL and refuses the rest by name. `harness.py` has 24
  * subparsers (25 invocable names — `update` is an alias of `upgrade`); a hook entry that
@@ -39,22 +40,29 @@
  */
 // FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
 import '../js/lib/node-floor.mjs';
-import { cmdContext, cmdGitGate, cmdRuleGate, cmdToolGate, cmdLearn } from '../js/hosts/hooks.mjs';
-// Not a new module on the hot path: `js/hosts/hooks.mjs` above already imports
-// `js/lib/fs.mjs`, so this edge names a file the process has already loaded.
+// Not a new module on the hot path: every verb's module imports `js/lib/fs.mjs` too, so this
+// edge only loads early a file the process would load anyway.
 import { printErr } from '../js/lib/fs.mjs';
 
 // `--host` selects the verdict dialect (see js/hosts/hooks.mjs's header); the emitter bakes
 // it into the command for every host that is not Claude Code, so the hook never has to guess
 // its reader from the payload's shape.
+//
+// `load` is a DYNAMIC import per verb, so a process parses only its own verb's module: the gates
+// run on every tool call and must not pay for `context`'s discovery or `learn`'s spawn. The
+// specifiers stay literal strings — `tests/unit/hook_cli.test.mjs`'s import walk reads them.
 const HOSTED = { '--root': 'root', '--host': 'host' };
+const gates = () => import('../js/hosts/hooks.mjs');
 const VERBS = {
-  context: { fn: cmdContext, flags: HOSTED },
-  'git-gate': { fn: cmdGitGate, flags: HOSTED, switches: { '--no-consent': 'noConsent' } },
-  'rule-gate': { fn: cmdRuleGate, flags: HOSTED },
-  'tool-gate': { fn: cmdToolGate, flags: HOSTED },
+  context: { load: () => import('../js/hosts/hooks-context.mjs'), fn: 'cmdContext', flags: HOSTED },
+  'git-gate': {
+    load: gates, fn: 'cmdGitGate', flags: HOSTED, switches: { '--no-consent': 'noConsent' },
+  },
+  'rule-gate': { load: gates, fn: 'cmdRuleGate', flags: HOSTED },
+  'tool-gate': { load: gates, fn: 'cmdToolGate', flags: HOSTED },
   learn: {
-    fn: cmdLearn,
+    load: () => import('../js/hosts/hooks-learn.mjs'),
+    fn: 'cmdLearn',
     flags: { '--memory': 'memory' },
     switches: { '--consolidate': 'consolidate' },
     positional: 'file',
@@ -62,7 +70,7 @@ const VERBS = {
 };
 
 function die(code, msg) {
-  // CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse
+  // CRLF on Windows, for the same reason the hook verbs' funnels translate: argparse
   // writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
   printErr(`geneseed-hook: error: ${msg}\n`);
   return code;
@@ -128,8 +136,7 @@ async function main(argv) {
   // argument. The four hook verbs are four of the reference's 26 and had the same gap.
   // `js/ui/cli.mjs` is imported HERE, not at the top: a static import cost every tool call
   // of every session a module parse (~3 ms of an ~12 ms controllable budget) for a branch
-  // only a human at a terminal ever takes. The hook path never awaits it, so `main` staying
-  // async-shaped costs the hot verbs nothing.
+  // only a human at a terminal ever takes.
   if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
     const { printHelp } = await import('../js/ui/cli.mjs');
     const rc = printHelp('geneseed-hook', verb);
@@ -137,7 +144,7 @@ async function main(argv) {
   }
   const parsed = parse(spec, argv.slice(1));
   if (parsed.error) return die(2, parsed.error);
-  return spec.fn(parsed.args);
+  return (await spec.load())[spec.fn](parsed.args);
 }
 
 main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/docs/README.md

@@ -2,40 +2,59 @@
 
 [← Back to README](../README.md)
 
-**New to agent harnesses?** Read **Understand** first — four short pages, about ten minutes, and every other page assumes them. The same pages open the **Docs** tab of the web console (`geneseed web`), which adds an interactive map of your own install and filters host-specific passages to the tool you use.
+**New to agent harnesses?** Read **Understand** first — a short track, about ten minutes, that every other page assumes. The same pages open the **Docs** tab of the web console (`geneseed web`), which groups each part into sections, adds an interactive map of your own install, and filters host-specific passages to the tool you use.
 
 ## 1 · Understand
 
-1. **[What a harness is](understand/harness.md)** — git hooks + CI + a runbook, but for your AI agent.
-2. **[What lands on your machine](understand/on-your-machine.md)** — every file and hook an install writes, what it does for you, what it costs, how to turn it off.
-3. **[A day with the harness](understand/a-day.md)** — the moments you will actually meet: a push that asks first, a skill, a delegation, a memory.
-4. **[Enforced vs. asked](understand/enforced-vs-asked.md)** — what is guaranteed by code, and what the model is only asked to do.
+**Start here** — [What a harness is](understand/harness.md): git hooks + CI + a runbook, but for your AI agent.
+
+**On your machine** — [What lands on your machine](understand/on-your-machine.md) · [On OpenCode](understand/machine-opencode.md) · [On Claude Code and OpenClaude](understand/machine-claude.md) · [On Bob, or any AGENT.md tool](understand/machine-bob.md) · [Taking it back out](understand/take-it-out.md): every file and hook an install writes, what it does for you, what it costs, how to turn it off.
+
+**Day to day** — [A day with the harness](understand/a-day.md): the moments you will actually meet · [Enforced vs. asked](understand/enforced-vs-asked.md): what is guaranteed by code, and what the model is only asked to do.
 
 ## 2 · Guides
 
-| Guide | When |
-| --- | --- |
-| [Install](guides/install.md) | First time — npx, a clone, or a specific host |
-| [Choose your setup](guides/choose-your-setup.md) | Theme, doctrine packs, one rule at a time, footprint, posture, mode |
-| [Verify it works](guides/verify.md) | Right after installing, or when something feels off |
-| [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
-| [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
-| [Project context](guides/project-context.md) | Choosing which of a repo's docs the agent loads |
-| [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
-| [MCP servers](guides/mcp.md) | MarkItDown, GitLab, Filesystem — and reading non-markdown docs |
-| [Run geneseed from anywhere](guides/run-anywhere.md) | Putting the CLI on your PATH from a clone |
-| [Start the web console at login](guides/autostart.md) | Keeping the console running |
-| [Run in CI / headless](guides/headless.md) | OpenCode without a terminal |
-| [Add git-worktree isolation](guides/worktree.md) | OpenCode, optional third-party add-on |
-| [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
+| Section | Guide | When |
+| --- | --- | --- |
+| Install | [Install](guides/install.md) | First time — one command, and the page for each host |
+| Install | [From a clone](guides/install-clone.md) | npm is out of reach, or you want to change the harness |
+| Install | [OpenCode](guides/install-opencode.md) · [Claude Code](guides/install-claude-code.md) · [OpenClaude](guides/install-openclaude.md) · [IBM Bob](guides/install-bob.md) · [Any AGENT.md tool](guides/install-agent-md.md) | Installing for one host, global or per repo |
+| Install | [Without the wizard](guides/install-scripted.md) | A script, a CI job, a shell with no terminal |
+| Install | [Run geneseed from anywhere](guides/run-anywhere.md) | Putting the CLI on your PATH from a clone |
+| Set up | [Choose your setup](guides/choose-your-setup.md) · [Doctrine packs and single rules](guides/setup-doctrines.md) · [Footprint, loop trust and changing later](guides/setup-footprint.md) | Theme, posture, mode; doctrine packs and single rules; footprint, loop trust, changing a choice |
+| Set up | [Verify it works](guides/verify.md) | Right after installing, or when something feels off |
+| Set up | [Project context](guides/project-context.md) | Choosing which of a repo's docs the agent loads |
+| Set up | [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
+| Set up | [MCP servers](guides/mcp.md) · [MarkItDown](guides/mcp-markitdown.md) · [GitLab](guides/mcp-gitlab.md) · [Filesystem](guides/mcp-filesystem.md) · [Reading non-markdown docs](guides/read-non-markdown.md) | Where the config lives, the three presets, and reading PDF and Office files |
+| Loops | [Run a loop](guides/run-a-loop.md) · [Which loop template](guides/loop-which-template.md) · [While a loop runs](guides/loop-running.md) · [Finish a loop](guides/loop-finish.md) | Working a requirement as small, validated, committed iterations |
+| Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
+| Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
+| Keep it running | [Start the web console at login](guides/autostart.md) | Keeping the console running |
+| Keep it running | [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
+| OpenCode extras | [Run in CI / headless](guides/headless.md) | OpenCode without a terminal |
+| OpenCode extras | [Add git-worktree isolation](guides/worktree.md) | OpenCode, optional third-party add-on |
 
 ## 3 · Concepts
 
-[Hosts](concepts/hosts.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md) · [Footprint](concepts/footprint.md) · [Collaboration](concepts/collaboration.md) · [Foreman mode](concepts/foreman-mode.md) · [Exclusions](concepts/exclusions.md) · [Themes](concepts/themes.md) · [Code intelligence (LSP)](concepts/lsp.md)
+**Harness** — [Hosts](concepts/hosts.md) · [What each host automates](concepts/host-matrix.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Hook gates, settings and the shim](concepts/hook-gates.md)
+
+**Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md)
+
+**Configuration** — [Footprint](concepts/footprint.md) · [Themes](concepts/themes.md) · [Exclusions](concepts/exclusions.md) · [Code intelligence (LSP)](concepts/lsp.md)
+
+**Working together** — [Collaboration](concepts/collaboration.md) · [Foreman mode](concepts/foreman-mode.md)
+
+**Loops** — [Loops](concepts/loops.md) · [Templates](concepts/loop-templates.md) · [Bricks and their origins](concepts/loop-bricks.md) · [Notes and rules](concepts/loop-notes.md) · [Risk, trust and validation levels](concepts/loop-risk.md) · [Human gates](concepts/loop-gates.md) · [Contracts and ignored deletions](concepts/loop-contracts.md) · [LOOP.md, trailers and the loop branch](concepts/loop-branch.md)
 
 ## 4 · Reference
 
-[CLI](reference/cli.md) · [Environment variables](reference/environment.md) · [Glossary](reference/glossary.md) · [Troubleshooting](reference/troubleshooting.md) (by symptom) · [OpenCode plugins](reference/opencode-plugins.md) · [About](reference/about.md)
+**CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
+
+**Troubleshooting** (by symptom) — [Overview](reference/troubleshooting.md) · [Install](reference/troubleshoot-install.md) · [Hooks, context and memory](reference/troubleshoot-hooks.md) · [Model, agents and MCP](reference/troubleshoot-tools.md) · [Updating](reference/troubleshoot-update.md) · [Doctor findings](reference/troubleshoot-doctor.md) · [Web console](reference/troubleshoot-web.md)
+
+**OpenCode plugins** — [Overview](reference/opencode-plugins.md) · [context](reference/plugin-context.md) · [guard](reference/plugin-guard.md) · [learn](reference/plugin-learn.md) · [workflow](reference/plugin-workflow.md) · [notify](reference/plugin-notify.md) · [ponytail](reference/plugin-ponytail.md) · [activity](reference/plugin-activity.md)
+
+**Glossary & about** — [Glossary](reference/glossary.md) · [About](reference/about.md)
 
 ## For contributors
 

package/docs/concepts/agents.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 3
+order: 4
 title: "Agents"
 kind: "concept"
+section: "Harness"
+description: "The specialists the main session can hand work to."
 link: {"hash": "#/section/agents", "label": "Browse the catalog →"}
 ---
 An **agent** is a specialist the main session can hand a piece of work to. Each one is a markdown file with its own instructions, installed where your host looks for subagents (`agents/` in the install). It runs in its own context and returns a result, so its reading and searching does not fill your conversation.

package/docs/concepts/collaboration.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 9
+order: 14
 title: "Collaboration"
 kind: "concept"
+section: "Working together"
+description: "Register, contract, how firmly a memory binds, and who you are."
 ---
 Beside the [rules](rules.md), a few pieces shape *how* the agent works with you: the register it speaks in, the contract between you, how firmly a memory binds, and who you are. All of them are plain text in the install, so they reach every host unchanged.
 

package/docs/concepts/exclusions.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 11
+order: 12
 title: "Exclusions"
 kind: "concept"
+section: "Configuration"
+description: "Two ways to switch things off: one rule, or every hook in a folder."
 link: {"hash": "#/harness", "label": "Manage in Harness →"}
 ---
 Geneseed has two different ways to switch something off, and they work at different scales:
@@ -52,4 +54,4 @@ The finer switch removes a single doctrine rule from an install while keeping th
 geneseed build --emit claude-global --exclude-rules "process 7"
 ```
 
-The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Choose your setup](../guides/choose-your-setup.md); what the layers are is in [Rules](rules.md).
+The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).

package/docs/concepts/footprint.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 8
+order: 10
 title: "Footprint (lean vs full)"
 kind: "concept"
+section: "Configuration"
+description: "Lean or full: how much of the constitution rides inline every turn."
 link: {"hash": "#/settings", "label": "Toggle it in Settings →"}
 ---
 **Footprint** decides how much of the [constitution](rules.md) the agent carries *inline* in its instructions file on every turn. It has two settings, **lean** (the default) and **full**, chosen per install. It is a token-cost dial, not a rules dial: every rule the install adopted is in force at either setting.

package/docs/concepts/foreman-mode.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 10
+order: 15
 title: "Foreman mode"
 kind: "concept"
+section: "Working together"
+description: "Direct or foreman: whether the session does the work or hands it to a crew."
 link: {"hash": "#/harness", "label": "Set the mode in Harness →"}
 ---
 **Mode** decides how work gets executed in a session. Two modes ship: **direct**, the default, where the agent does every task itself, and **foreman**, where the session hands substantial tasks to a crew of [agents](agents.md) and keeps talking to you while they work.