geneseed 3.10.0 → 3.12.0

package/docs/concepts/loops.md

@@ -0,0 +1,165 @@
+---
+group: concepts
+order: 11
+title: "Loops"
+kind: "concept"
+link: {"hash": "#/docs/reference/cli", "label": "geneseed loop --help →"}
+---
+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
+that talks to it — the agent runs the node it is given and reports the outcome, never its own
+reading of the graph.
+
+> **You already know this:** a checklist a tech lead walks through on a ticket, where some steps
+> need a sign-off before continuing and others don't. The lead doesn't improvise the order; the
+> checklist decides it, and only the risky steps stop for you.
+
+## The ring
+
+A loop is a graph of **bricks** — one node each — wired by **edges**, one per outcome a brick can
+report. One cycle through the graph back to its head is an **iteration**; the graph's `loops`
+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.
+
+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
+out of iteration 1's diff. For the same reason the iteration has exactly one way in: its
+**head** is the first node listed in the iteration loop (normally `identify`), and every edge that
+enters the iteration from outside it — and `start`, when `start` is inside it — must target that
+head. `geneseed loop check` refuses a graph that enters anywhere else.
+
+**A node's re-entry budget is not each loop's `max` added up.** Every node inside one or more
+inner loops gets a single shared counter: `1 + the largest max among the inner loops that contain
+it`. A node in both a `max: 5` and a `max: 3` loop gets 6 re-entries total, not 8 — the loops don't
+stack, the larger one wins and the `+1` is the node's own first run. A node inside no inner loop at
+all gets exactly 1 — no re-entry — which is also why **every cycle inside an iteration must be a
+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
+  responsible for skipping bricks it can't run, not the engine.
+
+## Not foreman mode
+
+A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but
+they solve different problems. A pipeline is a one-shot crew for a single task, uncommitted until
+you accept it. A loop is a long-running, self-scoring state machine that commits each validated
+iteration on its own branch as it goes, and only stops for a person when the risk crosses a
+threshold.

package/docs/concepts/lsp.md

@@ -0,0 +1,50 @@
+---
+group: concepts
+order: 13
+title: "Code intelligence (LSP, OpenCode)"
+kind: "concept"
+---
+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.
+
+> **You already know this:** the red squiggles in your editor. With LSP on, the agent gets the same squiggles before it tells you a change is done.
+
+### What is covered
+
+| Language | Server | You install |
+| --- | --- | --- |
+| JavaScript, TypeScript, React, React Native | typescript-language-server | nothing — OpenCode downloads it |
+| Python | pyright | nothing — OpenCode downloads it |
+| Java | jdtls | a **JDK 21+** (OpenCode downloads jdtls itself) |
+| SQL | none, on purpose | — |
+
+One server covers JavaScript, TypeScript, React and React Native: they are all TS/JS.
+
+### The one prerequisite: Java 21+
+
+OpenCode downloads the servers that run on Node by itself on first use. It cannot install a JVM, and jdtls needs one, so `geneseed setup` checks for Java 21+ and prints an install hint if it is missing. Any JDK 21 works, for example:
+
+```bash
+brew install openjdk@21
+```
+
+```bash
+sdk install java 21-tem
+```
+
+### Why no SQL server
+
+A SQL language server is tied to one dialect — a PostgreSQL server flags Oracle SQL as errors and the other way round — and a `.sql` file can map to only one server, with nothing telling OpenCode which dialect a repo uses. Rather than be wrong for half of all SQL codebases, Geneseed ships none. If your project knows its dialect, add the matching server under the `lsp` key of the project's own `opencode.json`.
+
+### How it is wired
+
+The install adds `"lsp": true` to your `opencode.json` (LSP is off in OpenCode by default). If you already have an `lsp` key, Geneseed leaves yours alone.
+
+On an air-gapped machine, stop the downloads and pre-install each server yourself:
+
+```bash
+export OPENCODE_DISABLE_LSP_DOWNLOAD=true
+```
+
+### Verify
+
+Open a `.ts` and a `.py` file in a session and ask the agent for diagnostics. The first open triggers the download.

package/docs/{web → concepts}/memory.md

@@ -1,7 +1,7 @@
 ---
 group: concepts
-order: 4
-title: "Memory convention"
+order: 6
+title: "Memory"
 kind: "markdown"
 source: "src/memory/README.md"
 ---

package/docs/{web → concepts}/notebook.md

@@ -1,7 +1,7 @@
 ---
 group: concepts
-order: 5
-title: "Notebook (sovereign space)"
+order: 7
+title: "Notebook"
 kind: "markdown"
 source: "src/notebook/README.md"
 ---

package/docs/concepts/rules.md

@@ -0,0 +1,52 @@
+---
+group: concepts
+order: 2
+title: "Rules (the constitution)"
+kind: "concept"
+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.
+
+> **You already know this:** a lint config. Some rules are set to `error` and nobody may disable them; some come from presets you opt into; and your project's own overrides sit on top of the presets.
+
+### Cited by name, never by number
+
+Every rule has a name — *Deletion Is Deliberate*, *Consent Before Push* — and the agent, the docs and the hooks cite it by that name. Rules are also numbered in the rendered text, but a number is only the rule's current position: remove a rule and every number after it shifts. So when you write about a rule, in your own notes or in `user-rules.md`, use its name.
+
+The one place you type a position is the command line: `--exclude-rules "process 5"` means "the fifth rule of the process pack in this checkout". Check the name it carries before you exclude it.
+
+### The layers, in precedence order
+
+When two instructions disagree, the higher one wins.
+
+1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Conduct): what the agent is for, how it weighs evidence, how it decides, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
+2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
+3. **Your `user-rules.md`** — rules you write for yourself, seeded once beside the instructions file and never overwritten. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
+4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
+5. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
+
+### Doctrine packs
+
+{N_PACKS} packs ship, one file each under `src/doctrines/`:
+
+| Pack | What it governs |
+| --- | --- |
+| **craft** | how code is written — reuse first, house conventions, docs 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, restart is not reload |
+| **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).
+
+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.
+
+**process** is the one pack whose removal changes what the machine does, not only what the agent reads: it holds *Consent Before Push*, which a hook enforces. Without it, commits and pushes are no longer stopped for a question — destructive git still is, because that is a Rule ([Hooks](hooks.md)).
+
+### Themes do not move rules
+
+A [theme](themes.md) renames the nouns — an `imperial` install calls the invariants *Dictates* — but the layers, their order and every rule stay exactly where they are.
+
+### Related
+
+[Footprint](footprint.md) — how much of this text loads every turn · [Exclusions](exclusions.md) — switching rules off per rule versus per repo · [Glossary](../reference/glossary.md)

package/docs/concepts/skills.md

@@ -0,0 +1,49 @@
+---
+group: concepts
+order: 4
+title: "Skills"
+kind: "concept"
+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.
+
+> **You already know this:** a runbook. Nobody deploys from memory — you open the deploy runbook and follow it. A skill is that runbook, addressed to the agent.
+
+{N_SKILLS} skills ship. Each is authored once under `src/skills/` and installed under `skills/` in the install, where the host looks for skills.
+
+### How a skill gets used
+
+- **By name.** Ask for it — "brainstorm this", "run a council on it" — or, on hosts with slash commands, type `/<name>`.
+- **By trigger.** Every skill has a one-line description of its purpose and when it applies. The host shows those descriptions to the agent every turn, and the agent opens the matching skill when your request fits.
+- **User-only skills.** A few skills are marked to open only when *you* call them (a teaching drill, a tool tied to a setup the agent cannot see). They answer `/<name>` but the agent never starts them on its own, and their description stays out of the always-loaded list.
+
+### A tour
+
+| You want to… | Skill |
+| --- | --- |
+| turn a raw idea into an approved design before any code | `brainstorm` |
+| write a plan to a file before a non-trivial task | `plan` |
+| drive a change through smallest change → tests → green suite | `develop` |
+| find a bug by evidence: reproduce, isolate, root-cause, verify | `debug` |
+| answer a question from the open web, every claim cross-checked | `research` |
+| have several viewpoints debate a decision | `council` |
+| get an adversarial critique of anything | `roast-me` |
+| see what a change does before you agree to commit it | `explain-changes` |
+| stage the right paths and write a focused commit | `commit` |
+| open a pull request, or finish and merge a branch | `ship` |
+| decide whether something is a standing rule or a fact to remember | `rule` |
+| be taught a topic, or quizzed on it | `teach`, `quiz` |
+
+The full list, with each description, is in the catalog.
+
+### Skills improve themselves
+
+Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent proposes the exact edit to that skill and applies it only with your assent. Most runs end with nothing to change.
+
+### What they cost
+
+The skill *bodies* are read only when used. The *descriptions* are listed to the agent every turn so it can pick the right one — that list is part of the always-on cost described in [Footprint](footprint.md).
+
+### Related
+
+[Agents](agents.md) — who does the work · [Rules](rules.md) — what every skill obeys · writing your own: [docs/extending.md](../extending.md)

package/docs/concepts/themes.md

@@ -0,0 +1,50 @@
+---
+group: concepts
+order: 12
+title: "Themes"
+kind: "concept"
+---
+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.
+
+> **You already know this:** an editor colour scheme. It changes how everything looks, never what the code does.
+
+### What changes and what does not
+
+| Changes with the theme | Never changes |
+| --- | --- |
+| how the agent phrases its replies | which rules apply, and their order |
+| the nouns for the harness's parts — an `imperial` install calls the Rules *Dictates*, agents *Adepts*, skills *Rites* | folder names: `agents/`, `skills/`, `memory/`, `laws/`, `doctrines/`… |
+| the banner, the readiness line the agent prints when it starts, the closing lines | section layout and the links between files |
+| the names and descriptions shown for rules, agents and skills | rule addresses such as `process 5` |
+
+`neutral` keeps the plain words — Rule, Doctrine, Agent, Skill, Memory — so it is the theme to pick if you want no flavour at all. The [glossary](../reference/glossary.md) shows each themed word beside its neutral one.
+
+### The themes that ship
+
+14 themes ship: `neutral`, `imperial` (Warhammer 40k), `military`, `pirate`, `wizard`, `cyberpunk`, `gamer`, `sports` (play-by-play), `biker`, `commentator`, `joker`, `marvin`, `mean` and `verstappen`.
+
+### Switching
+
+The theme is stored in a `.geneseed-theme` marker in the install, so upgrades and rebuilds keep it.
+
+- **Setup wizard** — lists every theme with a live preview:
+
+  ```bash
+  geneseed setup
+  ```
+
+- **Web console** — the per-install voice dropdown on the Harness page.
+- **Command line** — with the emit target of the install you are changing:
+
+  ```bash
+  geneseed build --emit claude-global --theme pirate
+  ```
+
+<!--harness:opencode-->
+*(OpenCode only)*
+OpenCode also has *colour* themes for its interface. Those are separate from voice themes; `geneseed theme <name>` creates your own colour theme in OpenCode's themes folder, and it survives rebuilds.
+<!--/harness-->
+
+### Writing your own
+
+A theme is one JSON file of voice tokens in `themes/`. How the tokens split between voice and structure, and how to add one, is in the maintainer design notes: [DESIGN.md](../../DESIGN.md).

package/docs/extending.md

@@ -26,7 +26,7 @@ Three seams, and almost every question about "where do I edit?" resolves to one
 | Seam | Source of truth | How it reaches a user | Rebuild needed |
 |---|---|---|---|
 | **Harness content** | `src/` (laws, agents, skills, memory/notebook conventions, `AGENT.md.tmpl`) + `themes/*.json` for voice | rendered into a bundle by `geneseed build` / `update` / `rebuild-all` | yes — every active install must be re-emitted |
-| **Console docs** | `docs/web/*.md` + `docs/web/_groups.json` | read off disk at request time by `js/web/docs.mjs:101` | no — not even a daemon restart for content |
+| **Docs** | `docs/{understand,guides,concepts,reference}/*.md` + `docs/_groups.json` | read on GitHub as plain markdown, and off disk at request time by `js/web/docs.mjs` | no — not even a daemon restart for content |
 | **Console app** | `web/src/**` | built by vite into the **tracked** `web/dist/` | yes — rebuild *and commit* dist, then `geneseed web restart` |
 
 Two rules follow from the table and they cause most of the surprises:
@@ -34,7 +34,7 @@ Two rules follow from the table and they cause most of the surprises:
 - **Nothing propagates by itself.** A bundle is a *render*. Editing `src/` changes nothing on any
   machine until something re-emits (`sourceFingerprint` in `js/build/version.mjs` re-fingerprints, `js/inspect/status.mjs`
   reports the drift).
-- **`docs/web/` is data, `web/src/` is code.** A new documentation page is one file and no
+- **`docs/` is data, `web/src/` is code.** A new documentation page is one file and no
   rebuild. A new screen is a new hashed chunk and a mandatory `web/dist` commit.
 
 ### Counts are computed — never type one
@@ -408,10 +408,11 @@ 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/web/plugin-<name>.md` — `group: plugins`, `title: "geneseed-<name>"`, `kind: "concept"`.
-3. `docs/web/plugins.md` — a bullet. The count above it renders from `{N_PLUGINS}`.
-4. `docs/web/model.md` — a second `{N_PLUGINS}` sentence whose **enumeration of the capabilities
-   is hand-written and ungated**.
+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
+   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.
 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`).
@@ -432,14 +433,20 @@ a row to `js/cli-table.json` with a help string over 20 characters.
 
 ### 4c — A documentation page
 
-**One file, no rebuild, no server change.** `docs/web/<id>.md`, where the stem is the id.
-Frontmatter is JSON-per-value, not YAML (`js/web/docs.mjs:63-82`):
-
-- `group` must match an id in `_groups.json` — an unknown group is a **silent skip**.
-- `kind` ∈ `markdown | concept | glossary | about | cli`; anything else 404s.
-- `harness: "claude"|"opencode"` hides the page from the other host. Note the `plugins` group
-  carries this at the **group** level, and `hooks` symmetrically — a Claude-relevant page dropped
-  into `plugins` vanishes with no error.
+**One file, no rebuild, no server change.** `docs/<folder>/<id>.md` — folder ∈ understand,
+guides, concepts, reference; the stem is the id and must be unique across folders (a duplicate
+throws). The same file is what GitHub shows, so write for both
+(`tests/unit/docs_tree.test.mjs` gates it). Frontmatter is JSON-per-value, not YAML
+(`docFrontmatter` in `js/web/docs.mjs`):
+
+- `group` must match an id in `docs/_groups.json` — gated by `docs_tree.test.mjs`.
+- `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.
+- 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.
+- 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`.
 
@@ -593,7 +600,7 @@ text or flags is now an ordinary edit: `js/cli-table.json` is the owned document
 holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
 29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
 `tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
-`README.md`, `SETUP.md`, `QUICKSTART.md` and `SHIPPED.md` against the table.
+`README.md`, `SHIPPED.md` and every page under `docs/{understand,guides,concepts,reference}/` against the table.
 
 ---
 
@@ -607,8 +614,8 @@ only, at best, on its presence.
 | `§N` cross-references into `AGENT.md`'s anatomy | `src/skills/*`, `src/agents/*`, `adapters/**` | **range only.** `constitutionProblems` refuses a `§N` the template declares no section for — which catches a pointer past the end, the shape *removing* a section leaves. It cannot catch one that still resolves and now means something else, which is the shape *inserting* a section leaves, and is what actually happened when `## 2. Doctrines` pushed every later section down one. **Renumbering the anatomy means `grep -rn '§' src/ adapters/` and reading every hit.** Four satellites and a live OpenCode deny message shipped stale because the sweep stopped at `AGENT.md.tmpl` |
 | 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/web/rules.md` | nothing |
-| The plugin capability enumeration | `docs/web/model.md` | nothing (the number substitutes; the list does not) |
+| 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 |
 | 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 |
@@ -678,10 +685,9 @@ answer.
 - **`AGENT_LESSON_PROMPT` has no drift gate.** Its sibling `LEARN_PROMPT_HEAD` is checked for
   extractability; this one's parity test was retired. Reformat the declaration in
   `geneseed-learn.js` and the per-agent lesson prompt silently degrades to a two-line fallback.
-- **The fenced-command gate still covers only four documents.** `tests/unit/docs.test.mjs`
-  validates every `geneseed <verb> <flags>` line against `js/cli-table.json` — but only in
-  `README.md`, `SETUP.md`, `QUICKSTART.md` and `SHIPPED.md`. Adding `DESIGN.md` and the `docs/`
-  tree to that array is one line, and it would have caught item 2 on the day it was written.
+- **The fenced-command gate skips the maintainer docs.** `tests/unit/docs.test.mjs` validates
+  every `geneseed <verb> <flags>` line against `js/cli-table.json` in `README.md`, `SHIPPED.md`
+  and the user docs tree — not in `DESIGN.md` or the `docs/*.md` maintainer pages.
 
 ---
 
@@ -742,6 +748,11 @@ handler falls back to `index.html` at 200 with `text/html`, and the browser repo
 "no running server recorded" and exits 0, and `web restart` starts a *second* daemon. Recovery is
 to kill every pid on the port, then `geneseed web start`.
 
+`--port N` on `web stop|restart|status` names *which* daemon: the verb acts only if the record is
+on N, and refuses (exit 1, nothing sent) when it names another port. A test instance on another
+port is therefore stopped with `--port`, never with a bare `web stop` — that one stops whatever
+the record names, usually the live console on 4747.
+
 ---
 
 ## 10 — What to settle before the next wave

package/docs/guides/autostart.md

@@ -0,0 +1,70 @@
+---
+group: guides
+order: 10
+title: "Start the web console at login"
+kind: "concept"
+---
+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).
+
+```
+geneseed web start --no-browser   # start in the background
+geneseed web status               # is it running?
+geneseed web stop                 # stop it (the login item stays)
+geneseed web restart              # restart it, e.g. after an update
+```
+
+Only one console runs at a time. A second `start` does nothing, so logging in twice is harmless. Each machine and each user runs its own console on its own loopback address.
+
+> **Always use `web start` in a login item, never bare `web`.** Bare `geneseed web` runs in the foreground and leaves no record of itself. `web stop`, `web restart` and `web status` then cannot see it: they report no live server while it keeps serving. A `restart` would then start a second console that cannot take the busy port.
+
+> **This is a file you create. Geneseed never writes or edits a login item**, and that includes `geneseed migrate`. To remove the login item, delete the file.
+
+The examples below assume `geneseed` is on your `PATH` (see [Run geneseed from anywhere](run-anywhere.md)). Login items do not see your shell's `PATH`, so always use the absolute path to the launcher. For an npm install, `npm prefix -g` shows where npm keeps it.
+
+## Windows
+
+Press **Win+R**, type `shell:startup`, and create a file called `geneseed-web.vbs` in the folder that opens:
+
+```vbs
+' geneseed-web.vbs: start the Geneseed web console at login (hidden, no browser).
+CreateObject("WScript.Shell").Run "cmd /c ""C:\Users\you\AppData\Local\Geneseed\bin\geneseed.cmd"" web start --no-browser", 0, False
+```
+
+Write out the full path, as shown. VBS does not expand `%LOCALAPPDATA%` inside a string. The script runs hidden, so no console window flashes at login. To disable it, delete the file.
+
+If you would rather use a scheduled task:
+
+```powershell
+schtasks /Create /TN "Geneseed Web" /SC ONLOGON /TR "\"%LOCALAPPDATA%\Geneseed\bin\geneseed.cmd\" web start --no-browser" /RL LIMITED /F
+schtasks /Delete /TN "Geneseed Web" /F   # to remove it
+```
+
+## macOS
+
+Create a LaunchAgent at `~/Library/LaunchAgents/dev.geneseed.web.plist`. Set `RunAtLoad` and **no** `KeepAlive`. The launcher exits as soon as it has started the background process, which keeps running on its own.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>            <string>dev.geneseed.web</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/Users/you/.local/bin/geneseed</string>
+    <string>web</string>
+    <string>start</string>
+    <string>--no-browser</string>
+  </array>
+  <key>RunAtLoad</key>        <true/>
+</dict>
+</plist>
+```
+
+`/Users/you/.local/bin/geneseed` is where `./geneseed link` puts the launcher by default. Replace it with your own absolute path. Then load the agent, which also starts the console now:
+
+```bash
+launchctl load ~/Library/LaunchAgents/dev.geneseed.web.plist     # enable and start now
+launchctl unload ~/Library/LaunchAgents/dev.geneseed.web.plist   # disable
+```