geneseed 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -8,6 +8,127 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [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.13.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/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.

package/docs/concepts/hook-gates.md

@@ -0,0 +1,61 @@
+---
+group: concepts
+order: 7
+title: "Hook gates, settings and the shim"
+kind: "concept"
+section: "Harness"
+description: "Gates fail closed, the settings files hooks are written to, Bob and OpenClaude, and the hook shim."
+---
+How Geneseed's [hooks](hooks.md) behave when something goes wrong, where they are written on each host, and the one file they all run through.
+
+## Gates fail closed, and leave a trace
+
+If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the time, never the command or content. `geneseed status` counts them by rule.
+
+```bash
+geneseed status
+```
+
+In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context` hook stands down when the repo has its own per-repo install of the same host, so nothing is injected twice.
+
+## Where they are written
+
+| Host | Global | Per repo |
+| --- | --- | --- |
+| Claude Code | `~/.claude/settings.json` | `.claude/settings.local.json` |
+| OpenClaude | `~/.openclaude/settings.json` | `.openclaude/settings.local.json` |
+| Bob | `~/.bob/settings/settings.json` | `.bob/settings.json` |
+
+Per repo, Claude Code and OpenClaude hooks go into the **local**, untracked settings file: the hook commands contain paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks.
+
+The merge is surgical. Every other key and every hook of your own survive, and the install manifest records exactly which hook groups are Geneseed's, so an upgrade replaces and an uninstall removes only those.
+
+## Bob and OpenClaude
+
+**OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
+
+**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
+
+- `SessionStart` → `geneseed-hook context`.
+- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the two Rules, secrets and destructive git. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
+- `Stop` → `geneseed-hook learn`.
+
+Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
+
+## The hook shim
+
+Hooks run with your project as the working directory, so each command needs an absolute path. Rather than write the Node path and the Geneseed checkout path into every settings file, every hook points at one stable file, the **hook shim**: `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim holds those two paths; your settings hold none. Set `GENESEED_HOME` to keep it somewhere other than `~/.geneseed`.
+
+Every build rewrites the shim, so moving the checkout and running one build repairs every install at once.
+
+**A stale shim fails silently.** Hooks report through their output and exit 0 on every path — that is what keeps a broken hook from breaking your tool calls. The flip side: if the shim points at a checkout that no longer exists, every hook on the machine stops working and nothing tells you. The agent simply stops getting project context and the gates stop asking. `geneseed doctor` checks the shim; a build repairs it.
+
+```bash
+geneseed doctor
+```
+
+See [Hook, context and memory problems](../reference/troubleshoot-hooks.md).
+
+## Cost
+
+The hook program is small on purpose: it adds about 14 ms to each tool call.

package/docs/concepts/hooks.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 5
+order: 6
 title: "Hooks (Claude Code, Bob, OpenClaude)"
 kind: "concept"
+section: "Harness"
+description: "The commands Claude Code, Bob and OpenClaude run at fixed moments, and what each gate does."
 ---
 A **hook** is a command your host runs at a fixed moment — when a session starts, before a tool call, when the agent finishes. On Claude Code, Bob and OpenClaude, hooks are how Geneseed does anything *in code* rather than in prose: load your project's docs, stop a risky command for your confirmation, save what was learned.
 
@@ -10,7 +12,7 @@ A **hook** is a command your host runs at a fixed moment — when a session star
 
 Geneseed writes its hooks into the host's settings file. Every hook calls one program, `geneseed-hook`, with a verb — not the `geneseed` CLI you type yourself. The instructions file (`CLAUDE.md`) needs no hook: the host loads it by location.
 
-### The hooks on Claude Code
+## The hooks on Claude Code
 
 | Event | When | Command | What it does | Conditional? |
 | --- | --- | --- | --- | --- |
@@ -22,7 +24,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
 | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in `memory/agents/<name>.md` | needs `GENESEED_LLM` |
 | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
 
-### What each one does, and what you see
+## What each one does, and what you see
 
 **context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`. Each file is capped at 16 KB and the whole injection at 48 KB; what does not fit is listed for the agent to read on demand. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
 
@@ -44,58 +46,8 @@ export GENESEED_LLM="claude -p"
 
 Unset, `learn` does nothing useful — it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
 
-### Gates fail closed, and leave a trace
-
-If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the time, never the command or content. `geneseed status` counts them by rule.
-
-```bash
-geneseed status
-```
-
-In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context` hook stands down when the repo has its own per-repo install of the same host, so nothing is injected twice.
-
-### Where they are written
-
-| Host | Global | Per repo |
-| --- | --- | --- |
-| Claude Code | `~/.claude/settings.json` | `.claude/settings.local.json` |
-| OpenClaude | `~/.openclaude/settings.json` | `.openclaude/settings.local.json` |
-| Bob | `~/.bob/settings/settings.json` | `.bob/settings.json` |
-
-Per repo, Claude Code and OpenClaude hooks go into the **local**, untracked settings file: the hook commands contain paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks.
-
-The merge is surgical. Every other key and every hook of your own survive, and the install manifest records exactly which hook groups are Geneseed's, so an upgrade replaces and an uninstall removes only those.
-
-### Bob and OpenClaude
-
-**OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
-
-**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
-
-- `SessionStart` → `geneseed-hook context`.
-- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the two Rules, secrets and destructive git. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
-- `Stop` → `geneseed-hook learn`.
-
-Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
-
-### The hook shim
-
-Hooks run with your project as the working directory, so each command needs an absolute path. Rather than write the Node path and the Geneseed checkout path into every settings file, every hook points at one stable file, the **hook shim**: `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim holds those two paths; your settings hold none. Set `GENESEED_HOME` to keep it somewhere other than `~/.geneseed`.
-
-Every build rewrites the shim, so moving the checkout and running one build repairs every install at once.
-
-**A stale shim fails silently.** Hooks report through their output and exit 0 on every path — that is what keeps a broken hook from breaking your tool calls. The flip side: if the shim points at a checkout that no longer exists, every hook on the machine stops working and nothing tells you. The agent simply stops getting project context and the gates stop asking. `geneseed doctor` checks the shim; a build repairs it.
-
-```bash
-geneseed doctor
-```
-
-See [Troubleshooting](../reference/troubleshooting.md).
-
-### Cost
-
-The hook program is small on purpose: it adds about 14 ms to each tool call.
-
-### Verify
+## Verify
 
 Open a session in a repo and ask the agent what it knows about the project — it should answer from the repo's docs without reading them first. Ask it to commit something: you should get a prompt before the commit runs.
+
+What happens when a gate cannot decide, where the hooks are written, and the one file they all run through: [Hook gates, settings and the shim](hook-gates.md).

package/docs/concepts/host-matrix.md

@@ -0,0 +1,38 @@
+---
+group: concepts
+order: 2
+title: "What each host automates"
+kind: "concept"
+section: "Harness"
+description: "Row by row, which checks each host runs in code and which stay prose."
+---
+Every [host](hosts.md) gets the same content. This table is what each one lets Geneseed **automate** (check in code before an action) rather than only **ask** of the model.
+
+| Capability | OpenCode | Claude Code | Bob | OpenClaude |
+| --- | :---: | :---: | :---: | :---: |
+| Instructions file | `AGENT.md` via `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (`.openclaude/` per repo) |
+| Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
+| Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
+| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
+| Destructive git (force-push, `reset --hard`…) | 🔒 permission ask | 🪝 ask | 🪝 block¹ | 🪝 ask² |
+| Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
+| Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
+| Rule-or-memory write needs your call | ⚙️ speed bump³ | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
+| Sovereign-repo exclusions | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
+| MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
+| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
+
+✅ native · ⚙️ OpenCode plugin · 🔒 `permission.bash` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
+
+¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the two always-on rules (secrets, destructive git) and turns the two consent checks into a logged warning. It has no `SubagentStop` or `PreCompact` event, so learn runs on `Stop` only. **Unverified live** — there is no Bob install on the authoring machine; the rules preamble still holds if a hook does not fire.
+² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
+³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so this check stops the first such write once rather than prompting.
+⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
+
+## The one conditional row
+
+The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. Everything else in the table is always on.
+
+One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it.
+
+In plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).