geneseed 3.10.0 → 3.11.0

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.
 
 ---
 

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
+```

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

@@ -0,0 +1,120 @@
+---
+group: guides
+order: 2
+title: "Choose your setup"
+kind: "concept"
+---
+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.
+
+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.
+
+> **You already know this:** these are compiler flags. You set them once, the output is built from them, and changing one means rebuilding rather than editing the output by hand.
+
+## Theme: the voice
+
+A theme changes how the harness *sounds*: the banner, the readiness sigil the agent opens with, and the vocabulary of its prose. It never changes which rules apply or which files ship. The wizard previews each theme live as you move through the list.
+
+`neutral` is plain English. The others are `imperial`, `military`, `pirate`, `wizard`, `cyberpunk`, `gamer`, `sports`, `biker`, `commentator`, `joker`, `marvin`, `mean` and `verstappen`.
+
+```
+geneseed build --emit opencode-global --theme imperial
+```
+
+More in [Themes](../concepts/themes.md).
+
+## Posture: how the agent works with you
+
+Posture is the relationship register, fixed at build time so it does not drift mid-session:
+
+- **peer** *(default)*: a candid equal. Dense, challenges you, no flattery.
+- **mentor**: explains the why and checks your understanding.
+- **expert**: maximum density, no basics.
+- **assistant**: precise execution, low initiative. You steer.
+- **artisan**: a peer with toolsmith reflexes, terminal-first.
+
+```
+geneseed build --emit opencode-global --posture mentor
+```
+
+Pick **peer** unless you know you want another register. A theme changes the prose, while a posture changes the relationship. See [Collaboration](../concepts/collaboration.md).
+
+## Mode: who does the work
+
+- **direct** *(default)*: the agent works every task itself, turn by turn.
+- **foreman**: the session sorts each incoming task. A trivial task gets a direct answer. A substantial task goes to a small crew of agents (a **pipeline**) running in its own git worktree, while the session keeps answering you.
+
+A pipeline never commits or merges. It hands back its worktree uncommitted, together with its test and lint output. The session then re-runs those commands itself, shows you the diff and the passing output, and commits and merges only after you accept. Foreman mode costs more per substantial task, because several agents run instead of one. In exchange, the session stays responsive.
+
+```
+geneseed build --emit opencode-global --mode foreman
+geneseed build --emit opencode-global --mode direct    # back to the default
+```
+
+More in [Foreman mode](../concepts/foreman-mode.md).
+
+## 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)

package/docs/guides/headless.md

@@ -0,0 +1,22 @@
+---
+group: guides
+order: 11
+title: "Run in CI / headless"
+kind: "concept"
+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:
+
+```
+opencode run "review the staged diff and list any correctness bugs"   # one shot, prints to stdout
+opencode run -m anthropic/claude-sonnet-4-5 "…"                       # pin a model for this run
+cat issue.md | opencode run "triage this and propose a fix plan"      # pipe input in
+```
+
+`opencode run` loads the same `opencode.json` (its `instructions` pointing at `AGENT.md`, its permission rules, any per-agent overrides) and the same agents, skills and plugins as an interactive session. Geneseed writes nothing extra for this. It is ordinary OpenCode usage.
+
+## 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.
+- **`--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).

package/docs/guides/install.md

@@ -0,0 +1,161 @@
+---
+group: guides
+order: 1
+title: "Install"
+kind: "concept"
+---
+Geneseed builds a harness (the rules, agents, skills and hooks your AI coding tool loads; see [What a harness is](../understand/harness.md)) and installs it into the tool you already use. Most people need one command.
+
+## The 5-minute path
+
+The only prerequisite is **Node 22.3 or newer**.
+
+```
+npx geneseed setup
+```
+
+The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH`, then asks for a theme, a posture, a mode, the doctrine packs, an install mode and a footprint. Each one has a safe default, so you can hold Enter through all of them. [Choose your setup](choose-your-setup.md) explains each question. **OpenCode global** is the recommended install mode: you install once and every repo inherits it, with nothing committed into your projects. The wizard then builds the harness and ends with a short summary: the root file your tool loads and where it was written, the hooks it wired (Claude Code, Bob and OpenClaude), whether memory learning is on, which tool to restart, and a link to what was installed. It then offers to run a health check.
+
+To keep the command on your machine:
+
+```
+npm install -g geneseed
+```
+
+This puts three commands on your `PATH`: `geneseed` (the CLI you type), `geneseed-build` (the generator) and `geneseed-hook` (what the host tool calls on every tool use, which you never type yourself).
+
+Next: [Verify it works](verify.md). To see what the install just wrote, read [What lands on your machine](../understand/on-your-machine.md).
+
+## From a clone
+
+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).
+
+## Prerequisites
+
+- **Node 22.3 or newer.** This is the only hard requirement. Geneseed has zero runtime dependencies, and nothing it installs needs a second interpreter.
+- **Your agent tool**: OpenCode (recommended), Claude Code, IBM Bob, OpenClaude, or any tool that reads a root instructions file.
+- **git**, for a clone only. A clone updates itself with `git pull`.
+- *Optional:* a document converter (MarkItDown, Pandoc or Docling) if you want the agent to read PDFs and Office files. See [MCP servers](mcp.md#reading-non-markdown-docs).
+
+## Without the wizard
+
+`setup` needs an interactive terminal. In a script, a CI job, or any shell without one, it stops with exit code 1 and prints the build command to run instead:
+
+```
+geneseed build --emit opencode-global --theme neutral
+```
+
+`geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md).
+
+To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
+
+## Install paths, one per host
+
+The wizard runs one of these for you. Use them directly when you script an install, or when you want a scope the wizard did not offer you.
+
+### OpenCode, global (recommended)
+
+```
+geneseed build --emit opencode-global
+```
+
+This writes into OpenCode's config directory: `$OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode` (on Windows too: `C:\Users\<you>\.config\opencode`). The install contains `AGENT.md`, `agents/`, `skills/`, the plugins, the `memory/` store, and a merged `opencode.json` whose `instructions` key points at `AGENT.md`. Every repo you open in OpenCode inherits it. You do not need a per-repo file, because the context plugin finds each repo's docs by itself (see [Project context](project-context.md)).
+
+The install is non-destructive. A manifest (`.geneseed-manifest.json`) records the files Geneseed owns. A rebuild replaces and prunes only those files, and never touches your own agents, skills, plugins or memory.
+
+### OpenCode, per repo
+
+```
+geneseed build --emit opencode --out /path/to/repo --root /path/to/repo
+```
+
+This writes the bundle (`AGENT.md`, `agents/`, `skills/`, `memory/`, `notebook/`) and OpenCode's own layer (`opencode.json` and `.opencode/`) into one repository. You can commit them or not. To keep the bundle in a subfolder, point `--out` at the subfolder and keep `--root` on the repo, so instruction paths resolve from the project root:
+
+```
+geneseed build --emit opencode --out /path/to/repo/Harness --root /path/to/repo
+```
+
+### Claude Code
+
+```
+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.
+
+### OpenClaude
+
+```
+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.
+
+### IBM Bob
+
+```
+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.
+
+### Any AGENT.md tool
+
+```
+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)