geneseed 3.11.0 → 3.13.0

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.
 

package/docs/guides/upgrade.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 4
+order: 25
 title: "Upgrade"
 kind: "concept"
+section: "Keep it running"
+description: "Get a new version onto every install, and keep your local edits."
 ---
 Upgrading happens in two steps: get the new Geneseed, then rebuild every install from it. Editing or updating Geneseed changes nothing on your machine until something rebuilds. The route depends on how you installed.
 

package/docs/guides/verify.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 3
+order: 13
 title: "Verify it works"
 kind: "concept"
+section: "Set up"
+description: "Check an install works, right after installing or when something feels off."
 ---
 Four checks, from quickest to most thorough. The first one alone tells you whether the harness loaded.
 

package/docs/guides/wiki.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 7
+order: 15
 title: "Connect your wiki"
 kind: "concept"
+section: "Set up"
+description: "Give the agent your own notes, machine-wide."
 ---
 If you keep a personal knowledge base on this machine, such as an Obsidian vault or any folder of interlinked markdown, you can declare it once. The agent then reads from it and writes to it while following your own structure. This is optional. Until you declare a wiki, the feature stays off.
 

package/docs/guides/worktree.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 12
+order: 30
 title: "Add git-worktree isolation"
 kind: "concept"
+section: "OpenCode extras"
+description: "Add the optional third-party git-worktree isolation to OpenCode."
 harness: "opencode"
 ---
 This is a third-party, optional OpenCode plugin. Geneseed does not ship it or install it.

package/docs/reference/about.md

@@ -1,7 +1,9 @@
 ---
 group: reference
-order: 6
+order: 21
 title: "About — version, license, links"
 kind: "about"
+section: "Glossary & about"
+description: "Your version, theme and host, the license, and where updates come from."
 ---
 The console fills this page from your install: the version, the deployed theme and host, and where updates come from. Geneseed is MIT-licensed; the source is at [github.com/Arylmera/Geneseed](https://github.com/Arylmera/Geneseed).

package/docs/reference/cli.md

@@ -3,5 +3,7 @@ group: reference
 order: 1
 title: "CLI — every subcommand"
 kind: "cli"
+section: "CLI & environment"
+description: "Every geneseed subcommand, from the CLI's own table."
 ---
 The console renders this page from `js/cli-table.json`, the CLI's own description of itself, so it is always in step with the installed version. Outside the console, `geneseed --help` lists every command and `geneseed <command> --help` describes one.

package/docs/reference/env-context.md

@@ -0,0 +1,40 @@
+---
+group: reference
+order: 4
+title: "Context and memory variables"
+kind: "concept"
+section: "CLI & environment"
+description: "The variables that steer what loads at session start and where memory is written."
+---
+The environment variables that steer context injection and memory. None is required. The rest are on [Environment variables](environment.md).
+
+"Plugin" means one of the OpenCode plugins — see [OpenCode plugins](opencode-plugins.md). "Hook" means `geneseed-hook`, the small binary your tool's settings call on Claude Code, Bob and OpenClaude (see the [glossary](glossary.md)).
+
+## Context injection
+
+What gets loaded into the agent's context at session start — your project's docs and your machine wiki. See [Project context](../guides/project-context.md).
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_CONTEXT` | context plugin, context hook | Explicit `context.json` manifest path; overrides discovery. |
+| `GENESEED_ROOT` | context hook | Repo root to discover docs from (default: the current directory). |
+| `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `wiki.jsonc` path (default `$GENESEED_HARNESS/wiki.jsonc`, else beside the install). |
+| `GENESEED_STACK_GLOBAL` | context hook, Claude Code project build | `1` lets a global and a project install of the same host both inject. By default the project install makes the global one stand down. Rebuild the project install after changing it. |
+| `GENESEED_CONTEXT_INJECT` | context plugin | `off` disables injection; the agent is only *asked* to read the docs. |
+| `GENESEED_CONTEXT_VISIBLE` | context plugin | `1` shows the visible `PROJECT CONTEXT` block instead of the invisible per-request delivery. |
+| `GENESEED_CONTEXT_TRANSFORM` | context plugin | Legacy. `0`/`off` = same as `GENESEED_CONTEXT_VISIBLE=1`; `1` matches the default. |
+| `GENESEED_EAGER_FILE_KB` / `GENESEED_EAGER_TOTAL_KB` | context plugin | Per-file / total budget for docs injected in full (default 16 / 48). An oversized file is listed instead, never truncated. |
+| `GENESEED_LAZY_HEADINGS` | context plugin | Cap on headings read for listed docs per session (default 64). |
+| `GENESEED_WIKI_LAZY_LIMIT` | context plugin | Cap on wiki notes listed per wiki per session (default 200; beyond it the listing ends with a count). |
+
+## Memory and learn
+
+Where distilled memories land at session end, and which model distils them. See [Memory](../concepts/memory.md).
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `wiki.jsonc` is looked up). Optional — the plugin finds the in-config store by itself; set it to pin the location. |
+| `GENESEED_MEMORY` | learn plugin, CLI | Explicit memory dir; wins over `GENESEED_HARNESS`. |
+| `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
+| `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, the hook prints the prompt instead of distilling. |
+| `GENESEED_LEARN_DEBOUNCE_MS` | learn plugin | Quiet period before distilling, in ms (default 60000). |

package/docs/reference/environment.md

@@ -1,14 +1,18 @@
 ---
 group: reference
-order: 2
+order: 3
 title: "Environment variables"
 kind: "concept"
+section: "CLI & environment"
+description: "Where Geneseed installs, how the CLI and console behave, and where the other variables are listed."
 ---
-Every environment variable Geneseed reads, grouped by what it changes. None is required: an install works with all of them unset. Set one in your shell profile (or your tool's environment) when you need to move a default.
+The environment variables Geneseed reads, grouped by what they change. None is required: an install works with all of them unset. Set one in your shell profile (or your tool's environment) when you need to move a default.
 
 "Plugin" means one of the OpenCode plugins — see [OpenCode plugins](opencode-plugins.md). "Hook" means `geneseed-hook`, the small binary your tool's settings call on Claude Code, Bob and OpenClaude (see the [glossary](glossary.md)).
 
-### Where things install
+The variables that steer context injection and memory are on [Context and memory variables](env-context.md).
+
+## Where things install
 
 Where Geneseed writes an install, and what an upgrade re-renders.
 
@@ -26,64 +30,11 @@ Where Geneseed writes an install, and what an upgrade re-renders.
 | `GENESEED_PRIMARY` | `geneseed build` | `1` also emits the primary orchestrator agent (OpenCode). |
 | `GENESEED_COMMANDS` | `geneseed build` | `1` also emits the `/slash` command layer (OpenCode). |
 
-### Context injection
-
-What gets loaded into the agent's context at session start — your project's docs and your machine wiki. See [Project context](../guides/project-context.md).
-
-| Variable | Read by | Effect |
-| --- | --- | --- |
-| `GENESEED_CONTEXT` | context plugin, context hook | Explicit `context.json` manifest path; overrides discovery. |
-| `GENESEED_ROOT` | context hook | Repo root to discover docs from (default: the current directory). |
-| `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `wiki.jsonc` path (default `$GENESEED_HARNESS/wiki.jsonc`, else beside the install). |
-| `GENESEED_STACK_GLOBAL` | context hook, Claude Code project build | `1` lets a global and a project install of the same host both inject. By default the project install makes the global one stand down. Rebuild the project install after changing it. |
-| `GENESEED_CONTEXT_INJECT` | context plugin | `off` disables injection; the agent is only *asked* to read the docs. |
-| `GENESEED_CONTEXT_VISIBLE` | context plugin | `1` shows the visible `PROJECT CONTEXT` block instead of the invisible per-request delivery. |
-| `GENESEED_CONTEXT_TRANSFORM` | context plugin | Legacy. `0`/`off` = same as `GENESEED_CONTEXT_VISIBLE=1`; `1` matches the default. |
-| `GENESEED_EAGER_FILE_KB` / `GENESEED_EAGER_TOTAL_KB` | context plugin | Per-file / total budget for docs injected in full (default 16 / 48). An oversized file is listed instead, never truncated. |
-| `GENESEED_LAZY_HEADINGS` | context plugin | Cap on headings read for listed docs per session (default 64). |
-| `GENESEED_WIKI_LAZY_LIMIT` | context plugin | Cap on wiki notes listed per wiki per session (default 200; beyond it the listing ends with a count). |
-
-### Memory and learn
-
-Where distilled memories land at session end, and which model distils them. See [Memory](../concepts/memory.md).
-
-| Variable | Read by | Effect |
-| --- | --- | --- |
-| `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `wiki.jsonc` is looked up). Optional — the plugin finds the in-config store by itself; set it to pin the location. |
-| `GENESEED_MEMORY` | learn plugin, CLI | Explicit memory dir; wins over `GENESEED_HARNESS`. |
-| `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
-| `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, the hook prints the prompt instead of distilling. |
-| `GENESEED_LEARN_DEBOUNCE_MS` | learn plugin | Quiet period before distilling, in ms (default 60000). |
-
-### Guard
-
-The OpenCode safety guard. On Claude Code, Bob and OpenClaude the same gates are hooks and have no environment switch.
+## OpenCode plugin variables
 
-| Variable | Read by | Effect |
-| --- | --- | --- |
-| `GENESEED_GUARD` | guard plugin | `warn` downgrades every block to a logged warning; `off` disables the guard. |
-
-### Notifications
-
-The desktop ping when a long turn finishes (OpenCode).
-
-| Variable | Read by | Effect |
-| --- | --- | --- |
-| `GENESEED_NOTIFY` | notify plugin | `off` disables notifications. |
-| `GENESEED_NOTIFY_MIN_SECONDS` | notify plugin | Minimum turn length before notifying (default 30; `0` = every turn). |
-| `GENESEED_NOTIFY_TITLE` | notify plugin | Notification title (default `Geneseed`). |
-
-### Other OpenCode plugins
-
-| Variable | Read by | Effect |
-| --- | --- | --- |
-| `GENESEED_PONYTAIL` | ponytail plugin | Starting minimal-code level: `lite` \| `full` \| `ultra` \| `off` (default `off`; switch live with `/ponytail <level>`). |
-| `GENESEED_WORKFLOWS_DIR` | workflow plugin | Directory the `workflow` tool loads saved scripts from. |
-| `GENESEED_ACTIVITY` | activity plugin | `off` stops writing the live-activity files the web console reads. |
-| `GENESEED_DEBUG` | every plugin but guard and learn (which always log) | `1` logs what each plugin decided to stderr. |
-| `OPENCODE_DISABLE_LSP_DOWNLOAD` | OpenCode itself | `true` stops OpenCode downloading language servers — for air-gapped machines; install each server yourself. |
+Each OpenCode plugin's page lists its own switches: [guard](plugin-guard.md) (`GENESEED_GUARD`), [notify](plugin-notify.md) (`GENESEED_NOTIFY`, `GENESEED_NOTIFY_MIN_SECONDS`, `GENESEED_NOTIFY_TITLE`), [ponytail](plugin-ponytail.md) (`GENESEED_PONYTAIL`), [workflow](plugin-workflow.md) (`GENESEED_WORKFLOWS_DIR`) and [activity](plugin-activity.md) (`GENESEED_ACTIVITY`). `GENESEED_DEBUG=1` makes every plugin but guard and learn (which always log) say what it decided on stderr. `OPENCODE_DISABLE_LSP_DOWNLOAD` belongs to OpenCode itself: see [Language servers](../concepts/lsp.md).
 
-### Web console and CLI
+## Web console and CLI
 
 How the `geneseed` command behaves and prints.
 

package/docs/reference/glossary.md

@@ -1,8 +1,10 @@
 ---
 group: reference
-order: 3
+order: 20
 title: "Glossary"
 kind: "glossary"
+section: "Glossary & about"
+description: "Every Geneseed word you won't find in a programming glossary, with a dev analogy."
 ---
 Every word Geneseed uses that you would not find in a general programming glossary. The console shows this table in your installed theme's voice beside the neutral words; on GitHub you read the neutral ones.
 
@@ -26,6 +28,10 @@ Every word Geneseed uses that you would not find in a general programming glossa
 | Posture | — | the relationship register the agent works in (peer, mentor, expert, assistant, artisan) | pairing style |
 | Mode | — | how work gets executed — direct (the agent works every task itself) or foreman (substantial tasks spawn an isolated pipeline) | solo vs. delegating to a sub-team |
 | Footprint | — | how much of the Rules loads inline each turn (full vs lean) | eager vs. lazy loading |
+| Loop | — | a requirement worked as small, validated, committed iterations on their own branch, driven by `geneseed loop` | a state machine over a ticket's steps |
+| Iteration | — | one cycle of a loop back to its head; closes into its own commit | one sprint-of-one through a checklist |
+| Brick | — | one node of a loop graph: a prompt for one agent or skill, reporting one of a declared set of outcomes | a step in a runbook |
+| Trust preset | — | the loop's risk tolerance — prudent, balanced (default) or aggressive — set at `loop init` and editable in `LOOP.md` | how much a reviewer lets through without a second look |
 | Profile | — | who you are — seeded once, colours but never binds | your onboarding notes |
 | Memory force | — | a memory's binding strength (constraint, choice, conviction, tempered) | MUST / SHOULD / MAY |
 | Tagline | TAGLINE | the one-line essence of the theme | — |

package/docs/reference/loop-actions.md

@@ -0,0 +1,20 @@
+---
+group: reference
+order: 2
+title: "Loop actions"
+kind: "concept"
+section: "CLI & environment"
+description: "The geneseed loop actions, one line each."
+---
+The actions of `geneseed loop`, the state machine behind [Loops](../concepts/loops.md). The `loop` skill calls them for you; [Finish a loop](../guides/loop-finish.md) shows how to drive one by hand.
+
+| action | what it does |
+|---|---|
+| `check` | lists templates and every brick (available, unavailable, overridden); validates one graph file (`--graph`) or one brick file (`--brick`) |
+| `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
+| `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
+| `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
+| `record` | records a brick's reported outcome and advances the graph; `--note` or `--note-file <path>` carries a finding (a read brick's plan or review findings) into `LOOP.md`'s notes so it survives the unit |
+| `decide` | answers an `awaiting` validation with a verdict and a note |
+
+Run `geneseed loop --help` for the full flag list.

package/docs/reference/opencode-plugins.md

@@ -1,130 +1,28 @@
 ---
 group: reference
-order: 5
-title: "OpenCode plugins"
 kind: "concept"
+section: "OpenCode plugins"
+order: 12
+title: "OpenCode plugins"
+description: "What the OpenCode plugins are, how they install, and the folders that silence them."
 ---
 On OpenCode, Geneseed's automation runs as {N_PLUGINS} plugins: small JavaScript files OpenCode loads from its `plugins/` directory at startup. They are what turns a rule from *asked* into *enforced* — the context load, the safety gates, memory distillation. On Claude Code, Bob and OpenClaude the same jobs are done by hooks instead (see [Hooks](../concepts/hooks.md)).
 
 > **You already know this:** a plugin is a git hook for your agent — code that runs on an event (session start, before a tool call, session idle), not text the model may or may not follow.
 
-Every plugin installs in the same step as the rest of the harness: `geneseed setup`, or `geneseed build --emit opencode-global` (global, into `~/.config/opencode/plugins/`) / `--emit opencode` (per-repo, into `.opencode/plugins/`). Installing by hand is covered in [Install](../guides/install.md). Keep **one** copy of each: OpenCode loads two local copies of the same plugin twice.
-
-Every plugin swallows its own errors — none can block or crash a session. Each variable below is also listed in [Environment variables](environment.md).
-
-## geneseed-context
-
-**What it does.** Puts your project's documentation (and your machine wiki) into the agent's context before your first turn, so the agent never has to be trusted to read it. It needs **no per-repo file**: it discovers docs by convention.
-
-- **Injected in full (eager):** root `README.md`, `CONTRIBUTING.md`, `.cursorrules`, `user-rules.md`, `PROFILE.md`. Budget-capped; an oversized file is listed instead, never silently truncated. (`AGENT.md`, `AGENTS.md` and `CLAUDE.md` are not injected — OpenCode already loads them.)
-- **Listed (lazy, path + first heading, read on demand):** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/`, and `packages/*/README.md` / `apps/*/README.md` in a monorepo. `node_modules`, `.git`, `dist`, `build`, `vendor` and similar are never scanned.
-- **Machine wiki:** the wikis declared in `wiki.jsonc` ride in the same block, on the same budgets. See [Wiki](../guides/wiki.md).
-- **Explicit manifest:** `$GENESEED_CONTEXT`, `.harness/context.json` or a root `context.json` takes over from discovery; `"extend": true` layers it on top instead. See [Project context](../guides/project-context.md).
-
-**When it runs.** On every request: the context rides invisibly in the request's message list, so it also survives compaction. If your OpenCode build lacks that (experimental) hook, the plugin notices and falls back to one visible message at session start, re-pushed when the session compacts.
-
-**What you see.** Normally nothing — the context is there, but not shown. With the visible fallback, a `PROJECT CONTEXT` block at the top of the session.
-
-**Switches.**
-- `GENESEED_CONTEXT_INJECT=off` — no injection; the agent is only *asked* to read the docs.
-- `GENESEED_CONTEXT_VISIBLE=1` — force the visible block (legacy `GENESEED_CONTEXT_TRANSFORM=0` does the same).
-- `GENESEED_EAGER_FILE_KB` / `GENESEED_EAGER_TOTAL_KB` (default 16 / 48), `GENESEED_LAZY_HEADINGS` (64), `GENESEED_WIKI_LAZY_LIMIT` (200) — budgets.
-- `GENESEED_WIKI` — explicit `wiki.jsonc` path.
-- `GENESEED_DEBUG=1` — log what it discovered and injected to stderr. Silence with this set means the plugin did not load.
-
-## geneseed-guard
-
-**What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
-
-- **Blocks** writes to private-key and credential files (*Sealed Secrets*), catastrophic shell commands such as deleting the filesystem root (*Deletion Is Deliberate*), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `wiki.jsonc`.
-- **Warns** (logged, allowed) on `.env` writes and force-push.
-- **Speed-bumps** the *first* write to `user-rules.md` or a memory file: it is refused once, naming *Persist Insight* — whether something is a standing rule or a fact to remember is your call, settled through the `rule` skill. The re-issued write goes through.
-
-It ships whole on every install, whatever [doctrine packs](../concepts/rules.md) you chose. On Claude Code and Bob the same checks are hooks, which can *ask* you instead of refusing; OpenCode's tool hook has no ask tier. Protected wiki folders are enforced only here — on the other hosts they are an instruction.
-
-**When it runs.** Before every tool call (`tool.execute.before`).
-
-**What you see.** A refused tool call: `[geneseed-guard] blocked: <reason> — set GENESEED_GUARD=off to allow`. Warnings go to stderr.
-
-**Switches.**
-- `GENESEED_GUARD=warn` — log every block, allow the call.
-- `GENESEED_GUARD=off` — disable the guard.
-
-## geneseed-learn
-
-**What it does.** Distils durable memories from the conversation into the install's `memory/` directory and keeps `MEMORY.md` up to date, de-duplicating against what is already stored. It is the OpenCode counterpart of the Claude Code `Stop` hook, but needs no API key and no model CLI: it distils with the **same model the session used**, through your OpenCode provider config. See [Memory](../concepts/memory.md).
-
-**When it runs.** After the session goes quiet. OpenCode signals "idle" after every turn, so each idle re-arms a timer and the distil runs once nothing has happened for `GENESEED_LEARN_DEBOUNCE_MS` (default 60 s). Trivial sessions are skipped.
-
-**What you see.** On stderr: `[geneseed-learn] wrote N memory file(s): …`, or `skipped: <reason>`. Total silence means it did not load.
-
-**Where it writes** — the first that resolves:
-1. `GENESEED_MEMORY` — an explicit memory dir;
-2. `$GENESEED_HARNESS/memory` (`/anamnesis` for the imperial theme);
-3. the `memory/` beside the plugin's own install (the global install's store);
-4. `./memory` or `./Harness/memory`, when the bundle lives in the project.
-
-So a global install needs nothing set; use `GENESEED_HARNESS` only to pin the location. If none resolves, it logs `no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY.` and does nothing.
-
-**Switches.**
-- `GENESEED_MODEL=provider/model` — fallback when the session's model can't be read. Without it you get `could not determine a model`.
-- `GENESEED_LEARN_DEBOUNCE_MS` — the quiet period.
-
-## geneseed-workflow
-
-**What it does.** Registers one tool, `workflow`, that runs saved orchestration scripts. The script — not the model — drives the control flow: the deterministic counterpart of the `council` and `parallel-agents` skills.
-
-- **Saved scripts only.** It loads `<name>.js` from the `workflows/` directory beside `plugins/`; nothing the model writes is evaluated. Shipped: `council`, `dispatch`, `research-plan-implement`, `review`.
-- **Call shape:** `workflow({ name, args })`; with no name it lists what is available.
-- **Isolation:** a script can run a child agent in its own git worktree on its own branch. A worktree with no change is removed; one with changes is kept, and the summary lists every kept branch and every file more than one agent changed. Nothing is merged or committed for you. Without git, such a child fails rather than falling back to the shared tree.
-
-**When it runs.** When the agent calls the `workflow` tool — usually because you asked for one.
-
-**What you see.** The tool's summary in the conversation. A phase-by-phase trace and the full result land in `.geneseed/workflow-runs/<runId>.log`.
-
-**Switches.**
-- `GENESEED_WORKFLOWS_DIR` — load scripts from another directory.
-- `GENESEED_DEBUG=1` — log to stderr.
-
-Ask the agent to *"list available workflows"* to check it loaded.
-
-## geneseed-notify
-
-**What it does.** Sends a native desktop notification when the agent finishes a long turn, so you can start a run, walk away, and be called back. macOS uses `osascript`, Linux `notify-send` (install `libnotify` if nothing appears), Windows a PowerShell balloon.
-
-**When it runs.** When a session goes idle, and only if the turn took longer than `GENESEED_NOTIFY_MIN_SECONDS` (default 30) since your last prompt. Sub-agent sessions and the learn plugin's own sessions are skipped.
-
-**What you see.** A notification titled `Geneseed`. With `GENESEED_DEBUG=1`, `[geneseed-notify] notified for …` on stderr.
-
-**Switches.**
-- `GENESEED_NOTIFY=off` — disable.
-- `GENESEED_NOTIFY_MIN_SECONDS=N` — threshold (`0` = every turn).
-- `GENESEED_NOTIFY_TITLE="…"` — the title.
-
-## geneseed-ponytail
-
-**What it does.** Holds an opt-in minimal-code mode: once on, it appends the "laziest solution that works" ruleset to the system prompt **every turn**, so the agent doesn't drift back to over-building mid-session. It is the sustained form of the `ponytail` skill, and it is not part of the [rules](../concepts/rules.md): nothing about it applies until you switch it on.
-
-**When it runs.** Every turn, while a level is set. It starts `off`.
-
-**What you see.** Replies that favour the smallest working change. Switch with `/ponytail lite|full|ultra|off` (bare `/ponytail` means `full`); the level is saved to `.geneseed-ponytail` beside OpenCode's config and applies from the next turn. On an OpenCode build without the experimental system-prompt hook it never injects; the skill still works.
-
-**Switches.**
-- `GENESEED_PONYTAIL=lite|full|ultra` — the starting level (default `off`).
-- `GENESEED_DEBUG=1` — logs `[geneseed-ponytail] ponytail <level>` on each switch.
-
-## geneseed-activity
-
-**What it does.** Feeds the web console's **Activity** view: one small JSON file per session under `activity/` beside OpenCode's config, recording what the session is doing — phase, model, token and cost totals, files touched, plan, last error. The console reads and prunes those files; the two only meet on disk, so a crash on either side never blocks a session.
+Every plugin installs in the same step as the rest of the harness: `geneseed setup`, or `geneseed build --emit opencode-global` (global, into `~/.config/opencode/plugins/`) / `--emit opencode` (per-repo, into `.opencode/plugins/`). Installing by hand is covered in [Install on OpenCode](../guides/install-opencode.md). Keep **one** copy of each: OpenCode loads two local copies of the same plugin twice.
 
-**When it runs.** On session events, for top-level sessions only (sub-agents and learn's sessions are skipped). Entries whose process died or went stale are pruned by the reader.
+Every plugin swallows its own errors — none can block or crash a session. Each plugin's page lists the variables that tune it.
 
-**What you see.** A card per live session in **Activity** (`geneseed web`).
+## The plugins
 
-**Switches.**
-- `GENESEED_ACTIVITY=off` — kill switch at startup.
-- The Activity page's own toggle writes a `.geneseed-activity` flag file, read per event — no restart needed.
-- `GENESEED_DEBUG=1` — logs each write as `[geneseed-activity] …`.
+- [geneseed-context](plugin-context.md): Puts your project docs, rules, profile, memory index and wiki in front of the agent.
+- [geneseed-guard](plugin-guard.md): Blocks credential files, catastrophic commands and protected wiki writes before they run.
+- [geneseed-learn](plugin-learn.md): Distils durable facts into memory/ once a session goes quiet.
+- [geneseed-workflow](plugin-workflow.md): Adds a workflow tool that runs saved orchestration scripts.
+- [geneseed-notify](plugin-notify.md): A desktop notification when a long turn finishes.
+- [geneseed-ponytail](plugin-ponytail.md): An opt-in minimal-code mode, re-applied every turn.
+- [geneseed-activity](plugin-activity.md): Feeds the web console's Activity view, one small file per session.
 
 ## Excluded folders
 

package/docs/reference/plugin-activity.md

@@ -0,0 +1,20 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 19
+title: "geneseed-activity"
+description: "Feeds the web console's Activity view, one small file per session."
+---
+One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](environment.md) points here for its switches.
+
+**What it does.** Feeds the web console's **Activity** view: one small JSON file per session under `activity/` beside OpenCode's config, recording what the session is doing — phase, model, token and cost totals, files touched, plan, last error. The console reads and prunes those files; the two only meet on disk, so a crash on either side never blocks a session.
+
+**When it runs.** On session events, for top-level sessions only (sub-agents and learn's sessions are skipped). Entries whose process died or went stale are pruned by the reader.
+
+**What you see.** A card per live session in **Activity** (`geneseed web`).
+
+**Switches.**
+- `GENESEED_ACTIVITY=off` — kill switch at startup.
+- The Activity page's own toggle writes a `.geneseed-activity` flag file, read per event — no restart needed.
+- `GENESEED_DEBUG=1` — logs each write as `[geneseed-activity] …`.