geneseed 3.12.0 → 3.14.0

package/docs/concepts/loops.md

@@ -1,10 +1,14 @@
 ---
 group: concepts
-order: 11
-title: "Loops"
 kind: "concept"
-link: {"hash": "#/docs/reference/cli", "label": "geneseed loop --help →"}
+section: "Loops"
+order: 16
+title: "Loops"
+link: {"hash":"#/docs/loop-actions","label":"The geneseed loop actions →"}
+description: "What a loop is, the ring of bricks it runs, and how it differs from foreman mode."
 ---
+To run one, see [Run a loop](../guides/run-a-loop.md).
+
 A **loop** is a requirement worked as small, validated, committed iterations instead of one long
 turn. `geneseed loop` is the state machine: it decides every transition, ceiling, score and stop,
 and hands the agent one node at a time to run. The `loop` [skill](skills.md) is the only thing
@@ -22,10 +26,11 @@ report. One cycle through the graph back to its head is an **iteration**; the gr
 array names every cycle that is allowed to exist, each with a `max` number of times a node inside
 it may be re-entered. Picture it as rings: the outer ring is the iteration itself (plan, apply,
 test, review, back to plan), and inner rings sit inside it for retries (apply failed its test, try
-`apply` again without going all the way back around). The three shipped templates —
-`bugfix`, `feature`, `refactor` — all nest a short `apply`↔`test` retry ring inside the iteration
-ring, and `bugfix` and `feature` nest a second, wider `apply`↔`test`↔`review` ring
-(`review-fix`) around that.
+`apply` again without going all the way back around). The shipped templates that center on
+`apply` — `bugfix`, `feature`, `refactor`, `tdd`, `legacy-refactor`, `deps-upgrade` — all nest a
+short `apply`↔`test` retry ring inside the iteration ring, and most nest a second, wider
+`review-fix` ring around that. `legacy-tests` and `ci-repair` have no `apply` at all: the first
+only ever writes tests, the second repairs CI directly through `ci-fix`.
 
 Work closes into a commit whenever the graph re-enters the iteration loop's head — so any setup
 work before the loop starts (reproducing a bug, say) is its own unit, numbered iteration 0, kept
@@ -42,120 +47,23 @@ all gets exactly 1 — no re-entry — which is also why **every cycle inside an
 named inner loop** in the graph JSON: `geneseed loop check` (and `loop init`, which runs the same
 check) refuses a graph with an undeclared cycle inside an iteration, before a single node runs.
 
-## Bricks, templates, and the three origins
-
-A **brick** is a markdown file: YAML-ish frontmatter (`name`, `description`, `effect` — `read` or
-`mutate` — exactly one of `agent` or `skill`, and `outcomes`) plus a 4-10 line prose body. The
-model never sees the file; `geneseed loop next` hands it the body as the prompt. A **loop
-template** (`bugfix`, `feature`, `refactor`, or one composed by hand) is the graph JSON that wires
-bricks together.
-
-Both are looked up across three origins, each able to override the one before it **by name**:
-
-| origin | path | who writes it |
-|---|---|---|
-| shipped | `src/bricks/`, `src/loops/` | Geneseed itself — read by the CLI from its own source, never emitted into an install |
-| global | `$XDG_CONFIG_HOME/geneseed/{bricks,loops}` (default `~/.config/geneseed/…`) | the user, for every project on this machine |
-| project | `<repo>/.geneseed/{bricks,loops}` | a team, committed and shared |
-
-Precedence is project > global > shipped. A project or global brick named `apply` replaces the
-shipped `apply` everywhere a template references it, without the template changing.
-`geneseed loop check` lists every override it finds, never silently.
-
-A per-install skill exclusion is invisible to the CLI — it has no way to know which skills your
-install carries. The `loop` skill covers the gap itself: when composing a graph it skips a brick
-whose `skill` it doesn't have.
-
-To add or adapt a brick, use the `brick-forge` skill — ask it, or see
-[the bricks README](https://github.com/geneseed-dev/geneseed/blob/main/src/bricks/README.md) in
-the repository.
-
-## Risk, trust, and the three validation levels
-
-Before a `mutate` brick runs, the loop scores the card the brick's setup declared: one risk weight
-per action kind it named, and the score is the **max**, not a sum — one contract change outweighs
-ten trivial renames, and ten trivial renames never add up to one. After the brick runs, the loop
-re-scores against the real diff, and the diff can only raise the score, never lower it:
-
-- a file touched outside the declared write set raises the score to at least **api** (`0.8`);
-- more than 20 deleted lines raises it to at least the **delete** weight;
-- touching a file listed in the loop's `contracts` raises it to at least the **api** weight.
-
-`LOOP.md` itself is excluded from every score and every diff check — it's the engine's own
-bookkeeping, rewritten on every action, never part of the work being judged.
-
-The score is checked against a **trust preset** — `--preset` on `geneseed loop init`, editable
-afterward in `LOOP.md`'s `preset` field, applying from the next score on:
-
-| preset | silent ≤ | soft ≤ | above soft |
-|---|---|---|---|
-| prudent | 0.1 | 0.3 | blocking |
-| balanced (default) | 0.2 | 0.6 | blocking |
-| aggressive | 0.4 | 0.8 | blocking |
-
-Three levels follow from where the score lands:
-
-- **silent** — nothing more than the commit trailers below.
-- **soft** — listed under "to review" in the run's final summary; no notification during the run.
-- **blocking** — the run ends. `LOOP.md` is written with `status: awaiting`, and a person has to
-  answer with `geneseed loop decide --verdict ok|no|amend`. Amending a verdict marks the decision
-  `blocking (amended)` in the trailers rather than silently rewriting it to something else.
-
-## `LOOP.md` and its trailers
-
-`LOOP.md`, at the worktree root, is both the human-readable record (title, requirement, and the
-rule that you may edit `preset` or `contracts` there) and the engine's own JSON state block. Every
-closing commit carries seven trailers, read straight off that state:
-
-```
-Loop-Iteration: <n>
-Loop-Bricks: <every brick name visited this unit, deduplicated>
-Loop-Risk-Declared: <score>
-Loop-Risk-Actual: <score>
-Loop-Threshold: <preset> <silent>/<soft>
-Loop-Decision: silent | soft | blocking[ (amended)]
-Loop-Tests: <what the loop was told about test state>
-```
-
-## The `loop/*` branch, and why merge always asks
-
-A loop runs in its own worktree, on a branch named `loop/<slug>` — the `loop` skill creates both
-with `git worktree add -b loop/<slug>` before `geneseed loop init` writes `LOOP.md` there.
-While that branch is checked out and `LOOP.md` carries the engine's state marker, the git gate lets
-exactly one commit/push form through without asking:
-
-```
-git add -A && git commit -F <message_file> && git push [-u] <remote> HEAD:<loop branch>
-```
-
-Nothing else is exempt — not `git commit -m`, not a quoted refspec, not a plain `git push` with no
-explicit `HEAD:<ref>` — any other shape still asks. The exemption only ever covers a `loop/*`
-branch, and never a shared one (`main`, `master`, `develop`, `development`, `release/*`,
-`hotfix/*`). The **final** commit of a run — the one that removes `LOOP.md` on `$close` — is
-outside the exemption too, because the loop is no longer running when it lands; that ask is your
-consent to close it. **Merging a loop branch into anything else always asks, with no exception.**
-The loop reports the branch to merge and the iterations that landed in "to review" — it never
-merges for you.
-
-## `geneseed loop` actions
-
-| 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 |
-| `decide` | answers an `awaiting` validation with a verdict and a note |
-
-Run `geneseed loop --help` for the full flag list.
-
 ## Limits
 
 - **No parallel nodes.** The graph runs one node at a time; there is no fan-out.
-- **A per-install skill exclusion is invisible to the CLI** (see above) — the `loop` skill is
+- **A per-install skill exclusion is invisible to the CLI** (see [Bricks and their origins](loop-bricks.md)) — the `loop` skill is
   responsible for skipping bricks it can't run, not the engine.
 
+## Read on
+
+- [Loop templates](loop-templates.md): the shipped graphs, and when to use each.
+- [Bricks and their origins](loop-bricks.md): what a brick is, and where your own override the shipped ones.
+- [Notes and rules](loop-notes.md): what survives an iteration, and what every brick must follow.
+- [Risk, trust and validation levels](loop-risk.md): how a change is scored, and when it stops for you.
+- [Human gates](loop-gates.md): the bricks that always wait for a person.
+- [Contracts and ignored deletions](loop-contracts.md): the globs that raise or ignore risk.
+- [LOOP.md, trailers and the loop branch](loop-branch.md): the state file, the commit trailers, and why merging always asks.
+- [Loop actions](../reference/loop-actions.md): the `geneseed loop` commands.
+
 ## Not foreman mode
 
 A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but

package/docs/concepts/lsp.md

@@ -3,6 +3,8 @@ group: concepts
 order: 13
 title: "Code intelligence (LSP, OpenCode)"
 kind: "concept"
+section: "Configuration"
+description: "Language servers on OpenCode, so the agent sees real diagnostics."
 ---
 OpenCode can run **language servers** — the same Language Server Protocol servers your editor uses — so the agent sees real diagnostics, type errors and definitions, not just text. Geneseed turns this on for every language OpenCode ships a server for.
 

package/docs/concepts/memory.md

@@ -1,7 +1,9 @@
 ---
 group: concepts
-order: 6
+order: 8
 title: "Memory"
 kind: "markdown"
+section: "Memory"
+description: "How durable facts are stored, indexed and loaded."
 source: "src/memory/README.md"
 ---

package/docs/concepts/notebook.md

@@ -1,7 +1,9 @@
 ---
 group: concepts
-order: 7
+order: 9
 title: "Notebook"
 kind: "markdown"
+section: "Memory"
+description: "The agent's own working space: plans, notes and the gate log."
 source: "src/notebook/README.md"
 ---

package/docs/concepts/rules.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 2
+order: 3
 title: "Rules (the constitution)"
 kind: "concept"
+section: "Harness"
+description: "The constitution: the standing rules every session carries, in laws and doctrine packs."
 link: {"hash": "#/laws", "label": "Browse the constitution →"}
 ---
 The **constitution** is the set of standing rules the agent carries into every session. It is authored in `src/`, rendered into the instructions file your host reads (`AGENT.md`, `CLAUDE.md` or `AGENTS.md`), and comes in layers that differ in one thing: whether you can turn them off.
@@ -37,7 +39,7 @@ When two instructions disagree, the higher one wins.
 | **process** | how a session runs — planning, context economy, docs first, bounded loops, consent before every commit and push |
 | **comms** | how answers are presented — stable reference codes on tracked items, a diagram or table only where it earns its place |
 
-All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying {N_DOCTRINE_RULES} rules between them. You choose packs at build time with `--doctrines`, or drop single rules with `--exclude-rules`; the how-to is in [Choose your setup](../guides/choose-your-setup.md).
+All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying {N_DOCTRINE_RULES} rules between them. You choose packs at build time with `--doctrines`, or drop single rules with `--exclude-rules`; the how-to is in [Doctrine packs and single rules](../guides/setup-doctrines.md).
 
 A pack you leave out **still ships**: every pack file lands under `doctrines/` beside the instructions file whether or not it was built in. A rule that cites an inactive pack still resolves on disk, and you can read the alternatives before turning one on. An inactive pack loses its binding force, not its availability.
 

package/docs/concepts/skills.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 4
+order: 5
 title: "Skills"
 kind: "concept"
+section: "Harness"
+description: "Written playbooks the agent follows for a repeatable task."
 link: {"hash": "#/section/skills", "label": "Browse the catalog →"}
 ---
 A **skill** is a repeatable workflow written as a markdown playbook: when it applies, the steps, and what "done" looks like. The agent reads the playbook before acting, so a task it has a skill for is done the same careful way every time instead of improvised.

package/docs/concepts/themes.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 12
+order: 11
 title: "Themes"
 kind: "concept"
+section: "Configuration"
+description: "The agent's voice and the words the harness uses, never its structure."
 ---
 A **theme** changes the agent's *voice* and the words the harness uses for its own parts. It never changes structure: the same rules, in the same order, with the same files, folders and links, whatever theme you pick.
 

package/docs/extending.md

@@ -336,7 +336,7 @@ render — no citation moves, because none names a number. Then:
 3. Its `LEX_<ID>`/`DOC_<ID>` key in all fifteen theme files (the equality arm names each).
 4. The number-keyed tables, which the doctor checks against the canon: `LAW_CLASS`
    (`js/inspect/inventory.mjs`), `LAW_META`/`DOCTRINE_META` (their id pins fail on every shifted
-   row), and — only if a hook-gated rule moved — `HOOK_PINNED` in `checks-authoring.mjs` names the
+   row), and — only if a hook-gated rule moved — `HOOK_PINNED` in `checks-constitution.mjs` names the
    ledger keys, `CONSENT_RULE` and `HOOK_GATED` to move with it. `--exclude-rules` addresses are
    `<pack>.<n>` too, and an install that excluded a shifted doctrine rule excludes its neighbour
    after a re-emit: prefer appending in a pack, and say so in the CHANGELOG when you cannot.
@@ -391,9 +391,10 @@ Two traps worth knowing before you write the spec:
   re-opens bash on all three hosts (OpenCode gates it to `ask`), and `<!-- webfetch: allow -->`
   re-opens web fetch — the researcher is the one spec that carries it.
 - **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
-  `web/src/pages/Skills.jsx:19` mirrors `SKILL_CLASS` with nothing comparing them (contrast
+  `web/src/lib/lawCats.js` mirrors `SKILL_CLASS` with nothing comparing them (contrast
   `LAW_META`, which *is* cross-checked). Inventing a new *category* means editing that file —
-  which drags in the `web/dist` rebuild — and an unknown category renders as Build with no warning.
+  which drags in the `web/dist` rebuild — and an unknown category lands under Personal in the
+  Library (`splitSkills` in `web/src/pages/Library.jsx`) with no warning.
 
 
 ---
@@ -408,11 +409,12 @@ The `geneseed-` prefix and the `.js` suffix are mechanically load-bearing: the b
 1. `adapters/opencode/plugins/geneseed-<name>.js` — ESM, zero dependencies. The factory-export
    convention is real (OpenCode requires it) but **ungated**; the only generic gate on plugin
    source is `node --check` (the one spawn in `authoringProblems`).
-2. `docs/reference/opencode-plugins.md` — a `## geneseed-<name>` section (gated: every plugin
-   file needs one). The count in its intro renders from `{N_PLUGINS}`.
-3. `docs/understand/on-your-machine.md` — a row in the OpenCode map table (Piece · What it does
+2. `docs/reference/plugin-<name>.md` — one page titled `geneseed-<name>`, `section: "OpenCode plugins"`,
+   linked from the list in `docs/reference/opencode-plugins.md` (gated: every plugin file needs
+   both). The count in the overview's intro renders from `{N_PLUGINS}`.
+3. `docs/understand/machine-opencode.md` — a row in the OpenCode map table (Piece · What it does
    for you · Kind · Cost · Turn it off). **Hand-written and ungated** beyond the table parsing.
-4. `docs/concepts/hosts.md` — check the capability matrix still tells the truth.
+4. `docs/concepts/host-matrix.md` — check the capability matrix still tells the truth.
 5. `README.md` — **three** sites: the badge, the `N plugins` prose, and the 🔌 Plugins row.
 6. `SHIPPED.md` — the bare name inside `plugins (…)`; that list must equal the directory exactly,
    in both directions (`tests/unit/web_api.test.mjs:1655`).
@@ -440,15 +442,28 @@ throws). The same file is what GitHub shows, so write for both
 (`docFrontmatter` in `js/web/docs.mjs`):
 
 - `group` must match an id in `docs/_groups.json` — gated by `docs_tree.test.mjs`.
+- `section` (optional, a non-empty string — gated by `docs_tree.test.mjs`) files the page under
+  a sub-part of its folder in the console's list, breadcrumb and Previous / Next; without one it
+  sits under **General**. Sections order by the smallest `order` among their pages, pages within
+  a section by `order` (`bySection` in `js/web/docs.mjs`). `description` (optional) is the
+  list row's second line. Keep a page to about 700 words: a longer one becomes a section of
+  short pages, each standing alone (its own intro line, links to its siblings).
 - `kind` ∈ `markdown | concept | map | glossary | about | cli`; anything else 404s. `map` is a
   concept page whose Piece/Kind/Cost table the console turns into the clickable map.
-- `harness: "claude"|"opencode"` hides the page from the other host — keep it for how-tos that
-  cannot run elsewhere; a reference page says its host in its title instead.
+- `harness: "opencode"|"claude"|"openclaude"|"bob"` hides the page from the other hosts — keep it
+  for how-tos that cannot run elsewhere; a reference page says its host in its title instead.
+  `claude` is the Claude-engine family: it shows to Claude Code, OpenClaude and Bob alike.
+  To name several hosts, give a JSON list: `harness: ["claude", "openclaude"]` shows to exactly
+  those hosts — inside a list `claude` is Claude Code alone, never the family — so that page
+  is hidden from Bob. The value is JSON like every frontmatter value; `[claude, openclaude]`
+  unquoted is refused by `tests/unit/docs_tree.test.mjs`.
 - Link pages with relative `.md` links; the console rewrites them to `#/docs/<id>`. A host-only
-  passage is `<!--harness:x-->` + a visible `*(OpenCode only)*` / `*(Claude Code only)*` line.
+  passage is `<!--harness:x-->` + a visible `*(OpenCode only)*` / `*(Claude Code only)*` /
+  `*(OpenClaude only)*` / `*(IBM Bob only)*` line, with the same family rule as pages. A
+  passage for several hosts lists them, `<!--harness:claude,openclaude-->`, labelled
+  `*(Claude Code and OpenClaude only)*` (names in the marker's order, joined by *and*).
 - No `{N_*}` token in `understand/` or `guides/` — GitHub would show it raw.
-- `kind: "markdown"` pulls from a repo file via `source:`, traversal-guarded, optionally sliced to
-  one section with `anchor:` + `slice: true`.
+- `kind: "markdown"` pulls from a repo file via `source:`, traversal-guarded.
 
 Inline `<!-- harness:claude -->` blocks strip per host and **fail open** on an unbalanced marker —
 the page renders, wrong, with nothing red.
@@ -615,7 +630,7 @@ only, at best, on its presence.
 | Per-law Principle lines | `web/src/pages/Laws.jsx` | presence and class only, never accuracy |
 | 588 themed constitution titles (42 keys × 14 voices) — `LEX_<ID>` (one per law), `DOC_<ID>` (one per doctrine rule), `PACK_<NAME>` | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
 | The README keyword enumerations | `README.md`, `docs/concepts/rules.md` | nothing |
-| The per-host map of what lands on a machine | `docs/understand/on-your-machine.md` | table shape only, never accuracy |
+| The per-host map of what lands on a machine | `docs/understand/machine-opencode.md`, `docs/understand/machine-claude.md` | table shape only, never accuracy |
 | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
 | `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
 | `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |

package/docs/guides/autostart.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 10
+order: 27
 title: "Start the web console at login"
 kind: "concept"
+section: "Keep it running"
+description: "Keep the web console running from login."
 ---
 The web console is the only long-running Geneseed process. `geneseed web start` launches it as a background process on `127.0.0.1:4747` and returns immediately. A login item that runs this command once, with `--no-browser`, leaves the console ready whenever you open [http://127.0.0.1:4747](http://127.0.0.1:4747).
 

package/docs/guides/choose-your-setup.md

@@ -1,10 +1,12 @@
 ---
 group: guides
-order: 2
+order: 10
 title: "Choose your setup"
 kind: "concept"
+section: "Set up"
+description: "The voice and working style: theme, posture and mode, and where the other setup choices are."
 ---
-The setup wizard asks a handful of questions before it builds. Every one has a safe default, so you can accept them all and move on. This page says what each one changes, so you can pick on purpose, and how to change it later.
+The setup wizard asks a handful of questions before it builds. Every one has a safe default, so you can accept them all and move on. Three pages say what each one changes, so you can pick on purpose: this one covers the voice and how the agent works with you; [Doctrine packs and single rules](setup-doctrines.md) covers which practices bind; [Footprint, loop trust and changing later](setup-footprint.md) covers the token cost, how far a loop goes, and how to change any of it.
 
 All of these choices are made **at build time**. The build writes them into the files your agent loads. Nothing switches at runtime. Rebuilds, re-themes and upgrades keep each install's choices, because they are recorded in small marker files beside the install.
 
@@ -52,83 +54,6 @@ geneseed build --emit opencode-global --mode direct    # back to the default
 
 More in [Foreman mode](../concepts/foreman-mode.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
-```
-
-## 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.
-
-## 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).
-
-## 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)
+**Next:** [Doctrine packs and single rules](setup-doctrines.md)

package/docs/guides/headless.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 11
+order: 29
 title: "Run in CI / headless"
 kind: "concept"
+section: "OpenCode extras"
+description: "Run OpenCode with the harness in CI, without a terminal."
 harness: "opencode"
 ---
 Once the harness is installed for OpenCode (global or per repo), OpenCode can run **non-interactively**, without its terminal UI. The harness's rules, agents and skills then apply in scripts and pipelines too:
@@ -17,6 +19,6 @@ cat issue.md | opencode run "triage this and propose a fix plan"      # pipe inp
 
 ## Things to know
 
-- **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `rm -rf`, and `git commit` and `git push` whenever the *Consent Before Push* rule is built in (it is part of the `process` pack; see [Choose your setup](choose-your-setup.md)). A CI job that has to commit should set those commands back to `"allow"` in its own `permission.bash` map, or limit the run to read-only work. Do not disable the guards wholesale.
+- **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `rm -rf`, and `git commit` and `git push` whenever the *Consent Before Push* rule is built in (it is part of the `process` pack; see [Doctrine packs and single rules](setup-doctrines.md)). A CI job that has to commit should set those commands back to `"allow"` in its own `permission.bash` map, or limit the run to read-only work. Do not disable the guards wholesale.
 - **`--pure`** runs OpenCode without any local or global config. Use it to reproduce a bug without the harness in the way, or to confirm that a behaviour comes from the harness.
-- **The plugins still load.** The context plugin injects the repo's docs, and the learn plugin still writes memory when the session goes idle. To change their behaviour for a run, set `GENESEED_GUARD=warn` or `off`, `GENESEED_CONTEXT_INJECT=off`, or `GENESEED_DEBUG=1`. See [Environment](../reference/environment.md) and [OpenCode plugins](../reference/opencode-plugins.md).
+- **The plugins still load.** The context plugin injects the repo's docs, and the learn plugin still writes memory when the session goes idle. To change their behaviour for a run, set `GENESEED_GUARD=warn` or `off`, `GENESEED_CONTEXT_INJECT=off`, or `GENESEED_DEBUG=1`. See [Context and memory variables](../reference/env-context.md) and [OpenCode plugins](../reference/opencode-plugins.md).

package/docs/guides/install-agent-md.md

@@ -0,0 +1,37 @@
+---
+group: guides
+order: 7
+title: "Install for any AGENT.md tool"
+kind: "concept"
+section: "Install"
+description: "The plain bundle for Codex CLI, Cursor, Gemini CLI and the like, or a prompt for a machine with no runtime."
+---
+The setup wizard runs this for you (see [Install](install.md)). Use the commands directly when you script an install, or when you want a scope the wizard did not offer you.
+
+```
+geneseed build            # renders the plain bundle into ./Harness
+```
+
+Point your tool's instructions or rules setting at `Harness/AGENT.md`. If the tool only loads one specific filename, rename or symlink the file (`AGENT.md` to `AGENTS.md` or `CLAUDE.md`). The rules then rest on the agent's own discipline, because these tools have no hooks or plugins to enforce anything (see [Enforced vs. asked](../understand/enforced-vs-asked.md)).
+
+Some of these tools also load skills. Their own docs list where:
+
+- **Codex CLI** loads a root `AGENTS.md` and `~/.codex/AGENTS.md`, and skills from `~/.codex/skills` or `.agents/skills`.
+- **Cursor** loads `AGENTS.md`, and skills from `.cursor/skills`, `.agents/skills` or `.claude/skills`.
+- **Gemini CLI** reads `GEMINI.md` by default. Set `context.fileName` in its `settings.json` to include `AGENTS.md`. Skills load from `.gemini/skills` or `.agents/skills`.
+
+Copy or symlink the bundle's `skills/` to `.agents/skills/` and all three of them see it.
+
+## No runtime on the target machine
+
+If the machine that will use the harness cannot run Node, run this once on a machine that can:
+
+```
+npx geneseed prompt --theme neutral > install-geneseed.md
+```
+
+This produces one self-contained prompt that recreates the whole file tree. Paste it into any capable agent on the target machine. There is nothing to install and no build step. Any theme works the same way.
+
+---
+
+**Next:** [Verify it works](verify.md) · [Choose your setup](choose-your-setup.md) · [What lands on your machine](../understand/on-your-machine.md)

package/docs/guides/install-bob.md

@@ -0,0 +1,20 @@
+---
+group: guides
+order: 6
+title: "Install for IBM Bob"
+kind: "concept"
+section: "Install"
+description: "The IBM Bob install, global or per repo, and how its hooks differ."
+---
+The setup wizard runs this for you (see [Install](install.md)). Use the commands directly when you script an install, or when you want a scope the wizard did not offer you.
+
+```
+geneseed build --emit bob-global                                   # ~/.bob
+geneseed build --emit bob --out /path/to/repo --root /path/to/repo # one repo
+```
+
+Bob is shaped like Claude Code, so it gets the same agents and skills. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2, and Bob has no `SubagentStop` or `PreCompact` events. Bob support has not yet been verified against a live install.
+
+---
+
+**Next:** [Verify it works](verify.md) · [Choose your setup](choose-your-setup.md) · [What lands on your machine](../understand/on-your-machine.md)

package/docs/guides/install-claude-code.md

@@ -0,0 +1,22 @@
+---
+group: guides
+order: 4
+title: "Install for Claude Code"
+kind: "concept"
+section: "Install"
+description: "The Claude Code install, global or per repo, and the hook shim every hook calls."
+---
+The setup wizard runs this for you (see [Install](install.md)). Use the commands directly when you script an install, or when you want a scope the wizard did not offer you.
+
+```
+geneseed build --emit claude-global                                  # ~/.claude, every repo
+geneseed build --emit claude --out /path/to/repo --root /path/to/repo   # one repo
+```
+
+The install writes `CLAUDE.md`, `agents/`, `skills/`, `memory/` and `notebook/`, plus hooks in Claude Code's `settings.json`. Hooks are commands Claude Code runs around each tool call. They gate risky actions and load project context (see [Hooks](../concepts/hooks.md)). For a project install the hooks go into `.claude/settings.local.json`, which stays out of git because it names a path on your machine.
+
+Every hook calls `geneseed-hook <verb>` through one stable file, the **hook shim** at `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim knows where Node and Geneseed live. If you move or replace Geneseed, one rebuild rewrites the shim and every install works again. `GENESEED_HOME` moves the shim's folder.
+
+---
+
+**Next:** [Verify it works](verify.md) · [Choose your setup](choose-your-setup.md) · [What lands on your machine](../understand/on-your-machine.md)

package/docs/guides/install-clone.md

@@ -0,0 +1,34 @@
+---
+group: guides
+order: 2
+title: "Install from a clone"
+kind: "concept"
+section: "Install"
+description: "Install from a git clone when npm is out of reach, or when you want to change the harness."
+---
+Clone the repository when npm is out of reach (for example, a corporate network with no registry access), or when you want to change the harness rather than just use it. A clone needs **git** as well as Node 22.3 or newer. git is what updates the clone.
+
+Each OS has a one-step installer at the root of the clone. It checks for Node and git. If one is missing, it names what to install and where to get it, then stops. **It never installs anything itself.** When the checks pass, it runs the setup wizard and offers to open the web console.
+
+```bash
+git clone https://github.com/Arylmera/Geneseed.git
+cd Geneseed
+./install                 # macOS, Linux, or a POSIX shell on Windows
+```
+
+- **macOS**: you can also double-click `install.command` in the Finder. It opens in Terminal.
+- **Windows**: double-click `install.cmd` in Explorer, or run it from cmd or PowerShell. It needs no bash, WSL or PowerShell script.
+
+```powershell
+git clone https://github.com/Arylmera/Geneseed.git
+cd Geneseed
+.\install.cmd
+```
+
+Later, run the launcher in the clone: `./geneseed setup` (Windows: `.\geneseed.cmd setup`) re-runs the wizard, and bare `./geneseed` opens the web console. Both launchers need `node` on `PATH`. If it is not there (some version managers only patch interactive shells), set `GENESEED_NODE` to the absolute path of the Node binary.
+
+From a clone, every `geneseed …` command on these pages is `./geneseed …` (Windows: `.\geneseed.cmd …`). To drop the `./`, see [Run geneseed from anywhere](run-anywhere.md).
+
+---
+
+**Next:** [Verify it works](verify.md) · [Install](install.md)

package/docs/guides/install-openclaude.md

@@ -0,0 +1,25 @@
+---
+group: guides
+order: 5
+title: "Install for OpenClaude"
+kind: "concept"
+section: "Install"
+description: "The OpenClaude install: Claude Code's pieces under OpenClaude's own config folder."
+---
+The setup wizard runs this for you (see [Install](install.md)). Use the commands directly when you script an install, or when you want a scope the wizard did not offer you.
+
+```
+geneseed build --emit openclaude-global                                   # ~/.openclaude
+geneseed build --emit openclaude --out /path/to/repo --root /path/to/repo # one repo
+```
+
+[OpenClaude](https://openclaude.gitlawb.com/) is a fork of Claude Code that can drive any model. You get the same agents, skills and hooks as Claude Code, under a different config directory. OpenClaude never reads `~/.claude` or a project `.claude/`, so the two installs can sit side by side. The differences:
+
+- Per repo, the preamble is written to `.openclaude/CLAUDE.md` rather than a root file, and the hooks go into `.openclaude/settings.local.json`.
+- `$OPENCLAUDE_CONFIG_DIR` moves the global directory (default `~/.openclaude`).
+
+OpenClaude support has not yet been verified against a live install.
+
+---
+
+**Next:** [Verify it works](verify.md) · [Choose your setup](choose-your-setup.md) · [What lands on your machine](../understand/on-your-machine.md)