geneseed 3.12.0 → 3.13.0

package/docs/guides/loop-running.md

@@ -0,0 +1,66 @@
+---
+group: guides
+order: 23
+title: "While a loop runs"
+kind: "concept"
+section: "Loops"
+description: "What a running loop commits, when it stops to ask you, where to watch it, and how to stop or resume it."
+---
+A loop started with [Run a loop](run-a-loop.md) works on its own `loop/<slug>` branch. This is what you see while it runs, and how to step in.
+
+Each iteration is one commit on `loop/<slug>`, pushed as it lands. Work done before the first iteration, such as reproducing a bug, is its own commit, numbered iteration 0. Every change ends at one of three levels:
+
+| Level | What you see |
+| --- | --- |
+| **silent** | Only the commit and its trailers. |
+| **soft** | The commit lands, and the final report lists it under "to review". |
+| **blocking** | The agent stops and asks you before anything is committed. |
+
+## When it asks you
+
+The agent ends its turn and shows you what it is waiting on:
+
+- **A blocking score**: the change it plans (before it runs) or the staged diff (after), with the reasons for the score. One file outside the declared write set, more than 20 deleted lines, or a file that matches the loop's `contracts` is enough.
+- **A human gate**: some bricks always stop for you, whatever the preset. An ADR that survived its skeptic (`adr-challenge`), an architecture rule and its allowlist (`fitness-define`), a contract migration plan (`migration-plan`) and a feature spec (`spec`) are all gated.
+- **Launch**, under `prudent`: the graph it is about to run.
+
+Answer in the agent's session, in your own words:
+
+| You say | What happens |
+| --- | --- |
+| ok / go ahead | It continues. On a gate held on a failure, ok follows that failure's edge, which usually stops the loop. |
+| no | The loop stops at that node. |
+| amend, with a note ("keep the old field until v3") | The same brick runs again with your note added to `LOOP.md`. A gate can be amended three times per iteration; a fourth amend stops the loop. |
+| amend, at the `prudent` launch prompt | The loop stops ("graph to amend") with your note: nothing has run yet, so ask again for the loop you want. |
+
+The agent passes your answer on as `geneseed loop decide --verdict ok|no|amend --note "<your words>"`. The console never answers for you.
+
+## Where to watch
+
+- **Console: Loops › Active.** Every registered loop, awaiting ones first: the branch, `iteration N / max`, the current node on its ring, what an awaiting loop waits on, and the iteration history.
+- **`LOOP.md`** at the worktree root: the title, the requirement, the preset, the contracts, the notes the bricks left, and the engine's state.
+- **The commits.** Each one carries the iteration, the bricks it ran, its declared and actual risk, the decision and the test state:
+
+```bash
+git log --format='%h %s%n%(trailers)' loop/<slug>
+```
+
+While a loop runs on its `loop/*` branch, the git gate lets exactly one commit-and-push shape through without asking, the one the agent uses to close each iteration. Any other git command still asks, as usual. Bob has no ask prompt, so there the commit and push gate logs a warning instead of asking.
+
+## Stop, resume, and what ends a loop
+
+- **Stop.** Interrupt the agent whenever you like. The state is `LOOP.md` plus the branch, so nothing is lost.
+- **Resume.** Ask "resume the loop" in a session opened in the worktree, or run `geneseed loop next` there. The same goes after you answered a question in a new session.
+
+A loop ends one of two ways:
+
+| End | When |
+| --- | --- |
+| `$close` | The iteration head reports nothing left to do. Some templates first run an independent `done-check`. |
+| `$stop` | A brick reported an outcome wired to stop (a red baseline in `baseline-green`, say), you answered no, a gate was amended a fourth time, two iterations in a row produced no diff, an inner retry ring ran out twice in one iteration, a read-only brick changed files, or the iteration ceiling was reached (the template's `max`, never above 20). |
+
+On `$stop` the agent reports the reason and leaves the branch as it is.
+
+---
+
+**Next:** [Finish a loop](loop-finish.md)

package/docs/guides/loop-which-template.md

@@ -0,0 +1,35 @@
+---
+group: guides
+order: 22
+title: "Which loop template"
+kind: "concept"
+section: "Loops"
+description: "Pick a loop template by what you want to do."
+---
+[Run a loop](run-a-loop.md) takes a template by name, or lets the agent compose a graph from the bricks. Pick one by what you want to do:
+
+| I want to… | Template | Category |
+| --- | --- | --- |
+| Record a design decision as an ADR before any code changes | `architecture-decision` | architecture |
+| Make a rule hold everywhere (a test with an allowlist, then one violation fixed per iteration) | `enforce-architecture-rule` | architecture |
+| Change an API, schema or event that has live consumers, without breaking them | `update-contract` | architecture |
+| Pin untested legacy behaviour with characterization tests, production code untouched | `legacy-tests` | tests |
+| Write each failing test before the code that passes it | `tdd` | tests |
+| Fix a test that fails only sometimes, at its root cause | `fix-flaky-tests` | tests |
+| Fix a reported bug, starting from a failing reproduction | `bugfix` | development |
+| Build a feature in planned iterations | `feature` | development |
+| Pin the acceptance criteria in a spec you review first, then build it | `spec-first-feature` | development |
+| Add or change HTTP endpoints, each with a Bruno request and a security pass | `api-endpoint` | development |
+| Restructure code that the tests already cover | `refactor` | refactoring |
+| Refactor code that has no tests yet | `legacy-refactor` | refactoring |
+| Delete unused code, one coherent group per iteration | `remove-dead-code` | refactoring |
+| Upgrade dependencies one package or group at a time | `deps-upgrade` | day-to-day |
+| Turn a red CI run green on a `loop/*` branch | `ci-repair` | day-to-day |
+
+The console's **Loops › Templates** shows each one as a ring, with its bricks and which of them stop for you.
+
+What each template's bricks do: [Loop templates](../concepts/loop-templates.md).
+
+---
+
+**Next:** [While a loop runs](loop-running.md)

package/docs/guides/mcp-filesystem.md

@@ -0,0 +1,41 @@
+---
+group: guides
+order: 19
+title: "Filesystem (MCP)"
+kind: "concept"
+section: "Set up"
+description: "File access limited to the folders you list, and the placeholder path to replace."
+---
+One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+
+[`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) gives the agent file access limited to the folders you list, through `npx`. **The allowed folders are command-line arguments.** The server refuses any path outside them, so grant the narrowest set that works, not `$HOME` or `/`.
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+```json
+{
+  "mcp": {
+    "filesystem": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
+      "enabled": true
+    }
+  }
+}
+```
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+```json
+{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] } } }
+```
+<!--/harness-->
+
+> **Replace the placeholder.** The preset ships with the literal path `/path/to/allowed/dir`. If you enable the server without changing it, the server runs but can reach nothing. This is the classic "the filesystem MCP sees nothing" problem.
+
+---
+
+**Next:** [Check the servers connected](mcp.md)

package/docs/guides/mcp-gitlab.md

@@ -0,0 +1,66 @@
+---
+group: guides
+order: 18
+title: "GitLab (MCP)"
+kind: "concept"
+section: "Set up"
+description: "Merge requests, issues and CI from the agent: token scopes, the config block, a second instance."
+---
+One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+
+> **Never commit a real token.** The presets ship with an empty `GITLAB_PERSONAL_ACCESS_TOKEN` and a sample filesystem path. Fill them in your own config, never in a tracked file.
+
+[`@zereight/mcp-gitlab`](https://github.com/zereight/gitlab-mcp) provides repository, merge request, issue and CI tools over the GitLab API. It runs through `npx`, so nothing is installed globally. The same command serves gitlab.com and any self-hosted instance.
+
+**1. Create a personal access token** on the instance (User Settings → Access Tokens) with the scopes `api` and `read_repository`. Treat it like a password.
+
+**2. Register the server.**
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+```json
+{
+  "mcp": {
+    "gitlab": {
+      "type": "local",
+      "command": ["npx", "-y", "@zereight/mcp-gitlab"],
+      "environment": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@zereight/mcp-gitlab"],
+      "env": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  }
+}
+```
+
+You can also register it with `claude mcp add`.
+<!--/harness-->
+
+Keep the `/api/v4` suffix on the URL.
+
+**A second instance** (gitlab.com plus a self-hosted server, for example) is a copy of the same block under a new name, such as `gitlab-acme`, with its own `GITLAB_API_URL` and token. The preset covers the first instance only. You add the copy by hand.
+
+---
+
+**Next:** [Filesystem (MCP)](mcp-filesystem.md)

package/docs/guides/mcp-markitdown.md

@@ -0,0 +1,36 @@
+---
+group: guides
+order: 17
+title: "MarkItDown (MCP)"
+kind: "concept"
+section: "Set up"
+description: "Convert PDF and Office files to markdown: uvx or pipx, OCR extras, corporate TLS."
+---
+One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+
+[MarkItDown](https://github.com/microsoft/markitdown) (Microsoft) converts PDF, Word, Excel, PowerPoint and HTML to markdown. It exposes one tool, `convert_to_markdown(uri)`, which accepts `file:`, `http:`, `https:` and `data:` URIs.
+
+**1. Make the command resolve.**
+
+- **`uvx` (recommended, nothing to install).** If you have [uv](https://docs.astral.sh/uv/), `uvx markitdown-mcp` fetches and caches the server on first use. This is the command the preset uses.
+- **`pipx`.** Without uv, run `pipx install markitdown-mcp`, then use `markitdown-mcp` alone as the command (OpenCode: `["markitdown-mcp"]`; Claude: `"command": "markitdown-mcp"`, no args).
+
+```
+uvx markitdown-mcp --help                       # uv route: confirm it resolves
+pipx install markitdown-mcp && markitdown-mcp --help   # pipx route
+```
+
+For scanned or image-only PDFs, which otherwise come back empty, add the OCR extras: `uvx --with "markitdown[all]" markitdown-mcp`, or `pipx inject markitdown-mcp "markitdown[all]"`.
+
+**2. Corporate TLS (only behind an SSL-inspecting proxy).** uv ships its own root certificates and ignores the OS trust store, so a proxy's internal certificate fails with `invalid peer certificate: UnknownIssuer`. Point uv at the OS store rather than turning verification off:
+
+```
+export UV_SYSTEM_CERTS=true      # older uv: UV_NATIVE_TLS=true
+# fallback: export SSL_CERT_FILE=/path/to/corporate-root-ca.pem
+```
+
+**3. Register it**, with the console toggle or one of the blocks in [MCP servers](mcp.md). Then restart your agent.
+
+---
+
+**Next:** [Reading non-markdown docs](read-non-markdown.md)

package/docs/guides/mcp.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 8
+order: 16
 title: "MCP servers"
 kind: "concept"
+section: "Set up"
+description: "Where MCP config lives for each host, the three presets, and how to check a server connected."
 ---
 MCP (Model Context Protocol) servers give your agent extra tools: converting a PDF, opening a merge request, reading files outside the repo. Geneseed ships three ready-made server **presets** (MarkItDown, GitLab and Filesystem) that you can switch on without writing JSON by hand.
 
@@ -37,113 +39,11 @@ The same MarkItDown server in both shapes:
 
 The reference OpenCode config ships MarkItDown enabled and the GitLab and Filesystem entries disabled, so a merge never switches on a server that has no credentials yet. Fill in the blanks, then switch the server on.
 
-## MarkItDown
+## The presets
 
-[MarkItDown](https://github.com/microsoft/markitdown) (Microsoft) converts PDF, Word, Excel, PowerPoint and HTML to markdown. It exposes one tool, `convert_to_markdown(uri)`, which accepts `file:`, `http:`, `https:` and `data:` URIs.
-
-**1. Make the command resolve.**
-
-- **`uvx` (recommended, nothing to install).** If you have [uv](https://docs.astral.sh/uv/), `uvx markitdown-mcp` fetches and caches the server on first use. This is the command the preset uses.
-- **`pipx`.** Without uv, run `pipx install markitdown-mcp`, then use `markitdown-mcp` alone as the command (OpenCode: `["markitdown-mcp"]`; Claude: `"command": "markitdown-mcp"`, no args).
-
-```
-uvx markitdown-mcp --help                       # uv route: confirm it resolves
-pipx install markitdown-mcp && markitdown-mcp --help   # pipx route
-```
-
-For scanned or image-only PDFs, which otherwise come back empty, add the OCR extras: `uvx --with "markitdown[all]" markitdown-mcp`, or `pipx inject markitdown-mcp "markitdown[all]"`.
-
-**2. Corporate TLS (only behind an SSL-inspecting proxy).** uv ships its own root certificates and ignores the OS trust store, so a proxy's internal certificate fails with `invalid peer certificate: UnknownIssuer`. Point uv at the OS store rather than turning verification off:
-
-```
-export UV_SYSTEM_CERTS=true      # older uv: UV_NATIVE_TLS=true
-# fallback: export SSL_CERT_FILE=/path/to/corporate-root-ca.pem
-```
-
-**3. Register it**, with the console toggle or one of the blocks above. Then restart your agent.
-
-## GitLab
-
-[`@zereight/mcp-gitlab`](https://github.com/zereight/gitlab-mcp) provides repository, merge request, issue and CI tools over the GitLab API. It runs through `npx`, so nothing is installed globally. The same command serves gitlab.com and any self-hosted instance.
-
-**1. Create a personal access token** on the instance (User Settings → Access Tokens) with the scopes `api` and `read_repository`. Treat it like a password.
-
-**2. Register the server.**
-
-<!--harness:opencode-->
-*(OpenCode only)*
-
-```json
-{
-  "mcp": {
-    "gitlab": {
-      "type": "local",
-      "command": ["npx", "-y", "@zereight/mcp-gitlab"],
-      "environment": {
-        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
-        "GITLAB_API_URL": "https://gitlab.com/api/v4"
-      },
-      "enabled": true
-    }
-  }
-}
-```
-<!--/harness-->
-
-<!--harness:claude-->
-*(Claude Code only)*
-
-```json
-{
-  "mcpServers": {
-    "gitlab": {
-      "command": "npx",
-      "args": ["-y", "@zereight/mcp-gitlab"],
-      "env": {
-        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
-        "GITLAB_API_URL": "https://gitlab.com/api/v4"
-      }
-    }
-  }
-}
-```
-
-You can also register it with `claude mcp add`.
-<!--/harness-->
-
-Keep the `/api/v4` suffix on the URL.
-
-**A second instance** (gitlab.com plus a self-hosted server, for example) is a copy of the same block under a new name, such as `gitlab-acme`, with its own `GITLAB_API_URL` and token. The preset covers the first instance only. You add the copy by hand.
-
-## Filesystem
-
-[`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) gives the agent file access limited to the folders you list, through `npx`. **The allowed folders are command-line arguments.** The server refuses any path outside them, so grant the narrowest set that works, not `$HOME` or `/`.
-
-<!--harness:opencode-->
-*(OpenCode only)*
-
-```json
-{
-  "mcp": {
-    "filesystem": {
-      "type": "local",
-      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
-      "enabled": true
-    }
-  }
-}
-```
-<!--/harness-->
-
-<!--harness:claude-->
-*(Claude Code only)*
-
-```json
-{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] } } }
-```
-<!--/harness-->
-
-> **Replace the placeholder.** The preset ships with the literal path `/path/to/allowed/dir`. If you enable the server without changing it, the server runs but can reach nothing. This is the classic "the filesystem MCP sees nothing" problem.
+- [MarkItDown](mcp-markitdown.md): converts PDF, Word, Excel, PowerPoint and HTML to markdown.
+- [GitLab](mcp-gitlab.md): repository, merge request, issue and CI tools over the GitLab API.
+- [Filesystem](mcp-filesystem.md): file access limited to the folders you list.
 
 ## Verify
 
@@ -163,33 +63,4 @@ Restart your agent, then list the servers:
 
 Being listed is not the same as working. A local server appears in the list whether or not its command actually launches.
 
-## A server won't connect
-
-Work through these in order:
-
-1. **Does the command resolve?** Run the exact command in a fresh terminal: `uvx markitdown-mcp --help`, or `npx -y @modelcontextprotocol/server-filesystem --help`. "command not found" means the binary is not on the `PATH` your agent starts from. Use the `uvx` or `npx` form, which needs only uv or Node, or point at the absolute path of the binary. This is the most common cause for MarkItDown.
-2. **Filesystem sees nothing?** The allowed folder is still the placeholder, or it points at a path that does not exist.
-3. **GitLab will not connect?** Almost always a missing or under-scoped token, or a wrong `GITLAB_API_URL`. Keep the `/api/v4` suffix.
-4. **Right file?** Editing a file the host does not read fails silently.
-
-<!--harness:opencode-->
-*(OpenCode only)*
-
-OpenCode reads `opencode.jsonc` if it exists, otherwise `opencode.json`, both in the project root and in `~/.config/opencode/`. The console toggle always writes the file OpenCode actually reads.
-<!--/harness-->
-
-<!--harness:claude-->
-*(Claude Code only)*
-
-Claude Code reads `.mcp.json` in the project and the `mcpServers` block in `~/.claude.json`. `claude mcp list` shows which servers actually loaded.
-<!--/harness-->
-
-## Reading non-markdown docs
-
-The agent's doc discovery only sees markdown. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
-
-- **MarkItDown**: the broadest. Use the MCP server above (preferred on a host with MCP: nothing to install per call, one cheap tool), or `pip install markitdown`.
-- **Pandoc**: excellent for Office and HTML, and a single binary.
-- **Docling** (IBM): best for complex tables and scanned PDFs.
-
-When an MCP converter is available, the skill prefers it. A prompt like *"convert file:///path/to/spec.pdf to markdown"* then just works. The skill never installs a converter silently. If none is present, it tells you which one to add.
+Listed but not connecting? See [Model, agent and MCP problems](../reference/troubleshoot-tools.md). To have the agent read PDFs and Office files, see [Reading non-markdown docs](read-non-markdown.md).

package/docs/guides/migrate.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 13
+order: 26
 title: "Migrate from a clone to npm"
 kind: "concept"
+section: "Keep it running"
+description: "Move an old clone install to the npm package."
 ---
 If you installed Geneseed by cloning the repository and now want to use the npm package, one command moves every install you already have, without touching your own settings.
 

package/docs/guides/project-context.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 6
+order: 14
 title: "Project context"
 kind: "concept"
+section: "Set up"
+description: "Choose which of a repo's docs the agent loads."
 ---
 At the start of every session, the harness shows the agent your repo's own documentation. Usually you have nothing to configure. This page explains what gets loaded and what each choice costs, so you know when to override it.
 
@@ -84,4 +86,4 @@ By default, the plugin delivers the context invisibly. It prepends the context t
 - `GENESEED_DEBUG=1` logs what was discovered and how it was delivered.
 <!--/harness-->
 
-All the knobs are listed in [Environment](../reference/environment.md). For knowledge that belongs to you rather than to one repo, see [Wiki](wiki.md).
+All the knobs are listed in [Context and memory variables](../reference/env-context.md). For knowledge that belongs to you rather than to one repo, see [Wiki](wiki.md).

package/docs/guides/read-non-markdown.md

@@ -0,0 +1,17 @@
+---
+group: guides
+order: 20
+title: "Reading non-markdown docs"
+kind: "concept"
+section: "Set up"
+description: "Let the agent read PDF, Word, PowerPoint, Excel and HTML through a converter."
+---
+The agent's doc discovery only sees markdown. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
+
+- **MarkItDown**: the broadest. Use [its MCP server](mcp-markitdown.md) (preferred on a host with MCP: nothing to install per call, one cheap tool), or `pip install markitdown`.
+- **Pandoc**: excellent for Office and HTML, and a single binary.
+- **Docling** (IBM): best for complex tables and scanned PDFs.
+
+When an MCP converter is available, the skill prefers it. A prompt like *"convert file:///path/to/spec.pdf to markdown"* then just works. The skill never installs a converter silently. If none is present, it tells you which one to add.
+
+Converter not found, or an MCP converter listed but not connecting? See [Model, agent and MCP problems](../reference/troubleshoot-tools.md).

package/docs/guides/run-a-loop.md

@@ -0,0 +1,64 @@
+---
+group: guides
+order: 21
+title: "Run a loop"
+kind: "concept"
+section: "Loops"
+description: "Start a loop: what you need, how to ask, which template, and how much it does before it asks."
+---
+A **loop** works one requirement as small iterations. Each one is planned, applied, tested, reviewed, scored for risk and committed on its own branch. You ask for it in plain words. The agent drives `geneseed loop`, which decides every step, and stops for you only when a change is risky or a step needs your sign-off. The loop never merges: the branch is yours to review.
+
+This page is the how-to. For how the engine works (rings, scoring, trailers), see [Loops](../concepts/loops.md). Once it runs, see [While a loop runs](loop-running.md) and [Finish a loop](loop-finish.md).
+
+## Before you start
+
+| You need | Why |
+| --- | --- |
+| An install that carries the `loop` skill | The skill is what talks to `geneseed loop`. After upgrading Geneseed, run `geneseed rebuild-all` so every install gets the current skill. |
+| A git repository with a remote named `origin` | Every iteration ends with `git push -u origin HEAD:loop/<slug>`. With no remote, the agent reports and stops. |
+| A test command the agent can run | The `test` brick runs the project's suite, and most templates retry `apply` until it passes. |
+| For `ci-repair`: CI that runs on `loop/*` branches, and the `gh` CLI | `ci-triage` reads the checks of the HEAD commit with `gh run list --commit`. |
+| For `legacy-tests`: a mutation tool (PIT, Stryker, mutmut, cargo-mutants) | Optional. Without one, `mutation-check` reports `unavailable` and the loop carries on, with a note saying so. |
+
+Check the catalogue the CLI sees from your repo:
+
+```bash
+geneseed loop check
+```
+
+It lists every template and brick, marks the unavailable ones and says why, and names every project or global brick that overrides a shipped one.
+
+## Start a loop
+
+Ask the agent, naming a template or not:
+
+```text
+run a tdd loop to add rate limiting to the /orders endpoint
+run a bugfix loop for issue 412: totals round the wrong way on refunds
+start a loop to remove the dead code knip reports in src/billing
+run a ci-repair loop on this branch, prudent
+```
+
+The agent then:
+
+1. Creates a worktree on a new branch, `git worktree add ../<repo>-loop-<slug> -b loop/<slug>`, and works from there. Your own checkout is not touched.
+2. Picks the template you named (see [Which loop template](loop-which-template.md)). If you named none, it runs `geneseed loop check` and composes a graph from the available bricks, validated with `geneseed loop check --graph <file>`.
+3. Runs `geneseed loop init --title … --requirement … --graph <template> --preset <preset>`. This writes `LOOP.md` at the worktree root and registers the loop so the console can show it.
+
+## Trust: how far it goes before it asks
+
+Before each change, and again after it, the loop scores its risk and compares the score with a **trust preset**:
+
+| Preset | What gets through without asking |
+| --- | --- |
+| `prudent` | Little beyond renames. It also asks you to approve the graph before the first node runs. |
+| `balanced` *(default)* | Logic changes and new files. API changes and deletions stop. |
+| `aggressive` | Everything short of an architecture-level change. |
+
+- **Install default.** The `--trust` choice your install was built with (`geneseed build --emit <target> --trust prudent`; see [Footprint, loop trust and changing later](setup-footprint.md)).
+- **One loop.** Say it when you start: "run it prudent", "aggressive is fine for this one".
+- **Mid-loop.** Pick another preset in the console under **Loops › Active**, or edit the `preset` field in `LOOP.md`. It applies from the next score, not to what already ran.
+
+---
+
+**Next:** [Which loop template](loop-which-template.md)

package/docs/guides/run-anywhere.md

@@ -3,6 +3,8 @@ group: guides
 order: 9
 title: "Run geneseed from anywhere"
 kind: "concept"
+section: "Install"
+description: "Put the geneseed command on your PATH from a clone."
 ---
 **Installed from npm? You have nothing to do.** `npm install -g geneseed` already puts `geneseed`, `geneseed-build` and `geneseed-hook` on your `PATH`.
 

package/docs/guides/setup-doctrines.md

@@ -0,0 +1,55 @@
+---
+group: guides
+order: 11
+title: "Doctrine packs and single rules"
+kind: "concept"
+section: "Set up"
+description: "Which practice packs bind, and how to drop a single rule."
+---
+Part of [Choose your setup](choose-your-setup.md). Like every setup choice, packs and rules are fixed **at build time**: change one by rebuilding, not by editing the output.
+
+## Doctrine packs: which practices bind
+
+The harness's rules come in tiers (see [Rules](../concepts/rules.md)). The Ethos and the Rules are always on. The **doctrines** are practices rather than principles, and they ship as packs you choose:
+
+| Pack | What it governs |
+| --- | --- |
+| **craft** | how code is written: reuse first, house conventions, docs updated in the same change, the smallest diff |
+| **rigor** | how work is proven: idempotence, honest tests, cover-and-verify, gates that can actually fail |
+| **ops** | how the machine is driven: tool discovery, commands that return, complete teardowns |
+| **process** | how a session runs: planning, context economy, docs first, bounded loops, and consent before every commit and push |
+| **comms** | how answers are presented: stable reference codes on tracked items, and a diagram or table only where it earns its place |
+
+Every pack is enabled by default. To keep only some packs, or none:
+
+```
+geneseed build --emit opencode-global --doctrines craft,rigor   # two packs
+geneseed build --emit opencode-global --doctrines none          # Ethos and Rules only
+```
+
+The packs always load in the same order (craft, rigor, ops, process, comms), whatever order you type them in. A pack you leave out still ships on disk under `doctrines/`, so you can read it before you turn it on. A clone can set its own default in `harness.config.json` with a `doctrines` array.
+
+**Dropping `process` changes what the machine does, not only what the agent reads.** The *Consent Before Push* rule in that pack is enforced at the tool boundary as well as in the prose:
+
+- On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push.
+- On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, entries that are already there are left in place and reported, because Geneseed cannot tell its own entries from ones you typed.
+
+The refusals of destructive git and `rm -rf` belong to the always-on Rules, not to the pack, so they stay in every build. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
+
+## One rule at a time
+
+A pack is all-or-nothing. `--exclude-rules` drops single doctrine rules instead. It takes rule addresses, written `<pack> <n>` or `<pack>.<n>`:
+
+```
+geneseed build --emit opencode-global --exclude-rules "process 7"
+geneseed build --emit opencode-global --exclude-rules "process 5,craft 2"
+geneseed build --emit opencode-global --exclude-rules none
+```
+
+The number in an address is the rule's position in its pack, so it can change if a rule is added or removed. To see the current addresses, pass an address that does not exist: the build refuses it and lists every valid address. The web console's **Constitution** page has one switch per rule. You stage the changes there and apply them in a single rebuild.
+
+Excluding *Consent Before Push* (`process 5` today) takes the commit and push consent gate with it, exactly as dropping the whole `process` pack does. The console and the wizard both warn you before applying it. A pack whose every rule is excluded drops out of the build entirely. See [Exclusions](../concepts/exclusions.md) for excluding whole folders instead.
+
+---
+
+**Next:** [Footprint, loop trust and changing later](setup-footprint.md)

package/docs/guides/setup-footprint.md

@@ -0,0 +1,48 @@
+---
+group: guides
+order: 12
+title: "Footprint, loop trust and changing later"
+kind: "concept"
+section: "Set up"
+description: "How much loads every turn, how far a loop goes before it asks, and how to change a choice."
+---
+Part of [Choose your setup](choose-your-setup.md): the last build-time choices, and how to change any of them once the install exists.
+
+## Footprint: how much loads every turn
+
+Footprint controls how much of the rules text sits inside `AGENT.md`, which is loaded on every turn. It changes the token cost, not which rules apply:
+
+- **lean** *(default)*: each rule appears in a hand-written short form, with a pointer to the full text. The full text ships beside `AGENT.md`, and the agent reads it when a rule's nuance matters.
+- **full**: every rule's complete text and rationale is inline. This costs the most tokens. It can help a smaller model, which applies a rule's nuance more reliably when the reasoning is always in front of it.
+
+```
+geneseed build --emit opencode-global --footprint full
+```
+
+Both footprints install the same agents, skills, hooks and plugins. More in [Footprint](../concepts/footprint.md).
+
+## Loop trust: how far a loop goes before it asks
+
+The `loop` skill scores every change it validates and stops to ask once the score passes a threshold. `--trust` sets the preset the skill starts a loop with; the user can still name another one per loop.
+
+- **prudent**: asks early, on anything past a rename.
+- **balanced** *(default)*: logic changes and new files pass with a note; API changes and deletions stop.
+- **aggressive**: only an architecture-level change stops the loop.
+
+The preset lives in the `loop` skill only, so it costs nothing in the always-on instructions.
+
+```
+geneseed build --emit opencode-global --trust prudent
+```
+
+## Changing a choice later
+
+You have three ways to change a choice:
+
+- **Re-run the wizard** with `geneseed setup`. It pre-selects what the install already has, so holding Enter cannot widen a set you narrowed on purpose. The wizard does not ask about single rules, but it keeps any rule exclusions already in place.
+- **Use the web console** (`geneseed web`). **Settings** and the **Harnesses** page change theme, footprint and the rest per install. **Constitution** toggles packs and rules.
+- **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want.
+
+---
+
+**Next:** [Verify it works](verify.md)

package/docs/guides/uninstall.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 5
+order: 28
 title: "Uninstall"
 kind: "concept"
+section: "Keep it running"
+description: "Remove an install, and what stays behind."
 ---
 `geneseed uninstall` removes one install at a time. It deletes only what Geneseed wrote and keeps anything you would not be able to rebuild.