geneseed 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -8,6 +8,102 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.12.0] — 2026-10-03
+
+**Upgrading:** re-emit after installing (`geneseed rebuild-all`) to get the `loop` and
+`brick-forge` skills, the loop-branch git-gate rule and the amended consent doctrine; then
+`geneseed web restart` for the Loops page.
+
+### Added
+- **Loops** — work a requirement in small validated iterations on a `loop/*` branch. A loop is a
+  graph of reusable **bricks** (13 shipped in `src/bricks/`; templates `bugfix`, `refactor`,
+  `feature` in `src/loops/`), or a graph the model composes from the catalogue. Your own bricks
+  live in `$XDG_CONFIG_HOME/geneseed/` or a repo's `.geneseed/`, and override shipped ones by name.
+- **`geneseed loop check|init|next|score|record|decide`** — a deterministic state machine: the
+  model only reports outcomes. Each iteration's risk is the max of its declared actions' weights,
+  re-scored on the real diff before commit; `LOOP.md` holds the state and every iteration commit
+  carries `Loop-*` trailers. Ceilings: 20 iterations, 2 empty diffs, one re-split of an exhausted
+  inner ring.
+- **`--trust prudent|balanced|aggressive`** build axis (default balanced, also in the console's
+  install form) — how much a loop may do before it stops: silent (trailers only), soft (listed for
+  review at the end), or blocking (the run ends and `geneseed loop decide` resumes it).
+- **`loop` and `brick-forge` skills.**
+- **Console: Loops page** — templates drawn as rings (inner rings for apply ⇄ test and review ⇄
+  fix, a gate before the first code-changing step), every brick with its source and origin, and
+  catalogue problems.
+- **Documentation for loops** (`docs/concepts/loops.md`): bricks, templates and the three
+  origins, the trust presets and the three validation levels, `LOOP.md` and its trailers, the
+  `loop/*` branch exemption and why merging always asks, and the `geneseed loop` actions table.
+  Cross-linked from `foreman-mode.md`; `glossary.md` gains `brick`, `iteration`, `loop` and
+  `trust preset`.
+
+### Changed
+- **Consent Before Push**: a launched loop's batch covers commit and push on its own `loop/*`
+  branch, in a fixed set of command forms (`git commit -F <file>`, `git push <remote> HEAD:<loop
+  branch>`); anything else asks, the final commit asks, and merging never belongs to the batch.
+  Enforced by the git gate on Claude Code, Bob and OpenClaude, and by `geneseed-guard` on OpenCode.
+
+### Fixed
+- **`geneseed web stop|restart|status --port N`** act on that port only; a stop aimed at a test
+  instance no longer shuts down the console recorded on another port (#175).
+
+## [3.11.0] — 2026-10-03
+
+**Upgrading:** re-emit after installing (`geneseed rebuild-all`) — it also repairs a dead hook
+shim and restarts a console left running on old code.
+
+### Added
+- **`learn-mode` skill** (user-invoked): you design at checkpoints, the agent writes only what an
+  answered checkpoint approved. State lives in `.geneseed/learn.md`, anchored by two lines in
+  `AGENT.md`'s Mode section; no hook changes. Inspired by nykooi1/vibe-wise (MIT), rewritten.
+- **One-step installers** — `install` / `install.cmd` / `install.command` check Node ≥ 22.3 and
+  git with per-OS hints (they never install anything), then run setup and offer the web console.
+- **Setup lists the tools it can install into** — OpenCode, Claude Code, IBM Bob and OpenClaude,
+  each found on PATH or shown with its install link — and asks before going on when none is present.
+
+### Changed
+- **The documentation is one tree, read on GitHub and in the console.** `docs/understand/`,
+  `docs/guides/`, `docs/concepts/` and `docs/reference/` replace `docs/web/`, `SETUP.md`,
+  `QUICKSTART.md` and `docs/wiki.md`; `docs/README.md` is the index. Install paths, every
+  configuration knob and MCP setup now live in `docs/guides/`; environment variables and
+  troubleshooting (organised by symptom) in `docs/reference/`. Every page was audited against
+  the code first, and a dozen wrong or stale claims were corrected on the way.
+- **New: Understand**, four pages for developers new to agent harnesses — what a harness is,
+  what lands on your machine (per host: every file and hook, what it does, what it costs, how to
+  turn it off), a day with it, and what is enforced versus only asked.
+- **Console Docs tab**: a three-column handbook with an "on this page" margin and glossary cards
+  for the terms a page uses; Understand renders as a step-by-step track with progress; "what
+  lands on your machine" is an interactive map; the Overview offers a dismissible "New here?"
+  card. Relative `.md` links work in both places.
+- **The glossary** is a markdown table (`docs/reference/glossary.md`) with a developer analogy
+  per term, so GitHub readers get it too.
+
+### Fixed
+- **Docs no longer claim a foreman pipeline merges on its own.** It hands back an uncommitted
+  worktree; the session re-runs the proof and merges only once you accept. The Claude hooks page
+  no longer says dropping the process pack loses the git gate — destructive git is still refused.
+- The console's CLI reference printed every command as `harness <verb>`; it says `geneseed`.
+- The `pipeline` skill said the parent merges on the crew's own proof without re-verifying; it
+  re-runs the proof and merges only once you accept, as foreman mode always said.
+- **Dead hooks are said out loud.** When the machine's hook shim points at a folder that no
+  longer exists, every Claude Code, Bob and OpenClaude hook is silently off. Every `geneseed`
+  command now warns about it on stderr (`GENESEED_NO_SHIM_CHECK=1` silences it), and the `gates`
+  row of `geneseed status` reads `DEAD` instead of `armed`. `geneseed rebuild-all` repairs it.
+- **Scratch installs stay out of the install list.** Installs built under the OS temp folder
+  (agent scratchpads, throwaway tests) are no longer registered, and existing ones are dropped,
+  so `rebuild-all` and `status` only cover real installs.
+- **A console running old code says so.** After an upgrade replaced the console's files, a
+  still-running console served a page that could not load. `geneseed web status` and a banner on
+  the console now say when it is out of date, the banner restarts it, and `rebuild-all`
+  restarts a stale console by itself.
+- **An old Node gets one sentence.** Below Node 22.3 every Geneseed command — including `npx`,
+  a global npm install and the hooks — says which Node it needs instead of crashing with a
+  stack trace.
+- **The end of setup tells the truth for every host.** It names the file each tool really loads
+  and where it is, the hooks wired for Claude Code, Bob and OpenClaude, whether memory learning
+  is on, the right tool to restart, and where to read what was installed. A successful Claude
+  Code install no longer ends on "expected AGENT.md … but it is not there".
+
 ## [3.10.0] — 2026-10-01
 
 **Upgrading:** re-emit after installing (`geneseed rebuild-all`). A Copilot install is no longer

package/DESIGN.md

@@ -4,7 +4,7 @@
 
 **The spec behind the harness. Read this before changing structure.**
 
-[← Back to README](README.md) · [Setup guide](SETUP.md)
+[← Back to README](README.md) · [Docs](docs/README.md)
 
 </div>
 

package/README.md

@@ -10,7 +10,7 @@
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
-[![Skills](https://img.shields.io/badge/skills-53-blueviolet)](src/skills/)
+[![Skills](https://img.shields.io/badge/skills-56-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
 [![Laws](https://img.shields.io/badge/laws-9-critical)](src/laws/universal.md)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
@@ -37,11 +37,11 @@ Want to read what it leaves behind before installing anything? [**geneseed-demo*
 A hand-written instructions file is prose the model may or may not honour, copied into every repo and drifting in each one. Geneseed is a build, and that changes four things:
 
 - **Laws are enforced, not suggested.** A force-push, a `reset --hard`, or a credential written into a tracked file is caught by a hook *before* the tool runs, in the host's own dialect — a prompt on Claude Code and OpenClaude, a hard block on OpenCode, exit 2 on Bob. The gates fail closed, and every catch is one line in a ledger that `geneseed status` counts.
-- **One source, five targets.** Skills are byte-identical on every host; only the wiring differs. Every commit renders all 261 emit configurations, and a second emit into the same tree must change nothing.
+- **One source, five targets.** Skills are byte-identical on every host; only the wiring differs. Every commit renders all 263 emit configurations, and a second emit into the same tree must change nothing.
 - **Costs are measured, not guessed.** Zero runtime dependencies. The hook path loads in about 14 ms per tool call. The default *lean* footprint keeps the always-on context small and puts the full rationale one read away — the numbers are in [docs/token-footprint.md](docs/token-footprint.md).
 - **It follows you.** Install once, globally; every repo inherits it. One `git pull` or `npm install -g geneseed@latest` rebuilds every active install.
 
-This page is the overview. Four parts: **why** it exists, how to **set it up**, the two ways to **drive it** (web console & command line), and **what you get**. For every install path, configuration knob, and troubleshooting step, read the full [Setup guide](SETUP.md).
+This page is the overview. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — four short pages on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
 
 ---
 
@@ -83,38 +83,43 @@ npm install -g geneseed       # then plain `geneseed <command>` from any directo
 npm install -g geneseed@latest   # …and that is also the update
 ```
 
-**[QUICKSTART.md](QUICKSTART.md)** walks this in 5 minutes. Every other route (Claude Code, plain `AGENT.md`, per-repo installs, MCP servers, troubleshooting) lives in the full **[Setup guide](SETUP.md)**.
+Every other route (Claude Code, Bob, OpenClaude, plain `AGENT.md`, per-repo installs) is in the **[install guide](docs/guides/install.md)**.
 
 ### 🧬 The long way — a git checkout
 
-Cloning still works and is what you want if you intend to *change* the harness rather than use it. It needs **git** and the same **Node ≥ 22.3** as everything else — there is nothing extra to install.
+Cloning is the route when npm is out of reach (a corporate network with no registry access) or when you intend to *change* the harness rather than use it. It needs **git** and the same **Node ≥ 22.3** as everything else — there is nothing extra to install.
+
+**One step: run the installer at the root of the clone.** It checks that Node ≥ 22.3 and git are there and, when one is missing, says exactly what to install and where (on a managed PC: Software Center / Company Portal) — it never installs anything itself. Then it runs the setup wizard — which opens by listing the AI coding tools it can install into (OpenCode, Claude Code, IBM Bob, OpenClaude), each `ok` or with its install link, and asks before going on when none is there — and offers to open the web console.
 
 ```bash
 git clone https://github.com/Arylmera/Geneseed.git
 cd Geneseed
-./geneseed setup          # the wizard — bare `./geneseed` opens the web console
+./install                 # prerequisites, then the wizard
 ```
 
-**Windows** — native, no bash, WSL, curl, or unzip; works from cmd or PowerShell:
+**macOS** — or double-click `install.command` in the Finder (it opens in Terminal). **Linux** — `./install` from any shell. On both, a missing prerequisite comes with the platform's own fix: Homebrew or the Command Line Tools on macOS, nvm/NodeSource or the package manager on Linux.
+
+**Windows** — native, no bash, WSL, curl, unzip or PowerShell script; double-click `install.cmd` in Explorer, or from cmd or PowerShell:
 
 ```powershell
 git clone https://github.com/Arylmera/Geneseed.git
 cd Geneseed
-.\geneseed.cmd setup      # the wizard — bare .\geneseed.cmd opens the web console
-# PowerShell runs a .cmd directly, so this is the PowerShell spelling too
+.\install.cmd             # prerequisites, then the wizard
 ```
 
+Afterwards, `./geneseed setup` (`.\geneseed.cmd setup`) re-runs the wizard and bare `./geneseed` (`.\geneseed.cmd`) opens the web console. PowerShell runs a `.cmd` directly, so that is the PowerShell spelling too.
+
 Both launchers are thin shims over the Node CLI: they need `node` (22.3+) on `PATH`, and nothing else. Set `GENESEED_NODE` to an absolute path if `node` is not on `PATH` — under a version manager that only patches interactive shells, say. The wizard is plain text prompts on every console, old or new.
 
 ### 🟩 One runtime — Node, and nothing else
 
-Node ≥ 22.3 is the entire dependency list — every command, all five hook verbs, the web console and both generators run from it, and nothing any bundle ships needs a second interpreter. The details, and the few honest edges, are in [SETUP.md → One runtime](SETUP.md#-one-runtime--node-and-nothing-else).
+Node ≥ 22.3 is the entire dependency list — every command, all five hook verbs, the web console and both generators run from it, and nothing any bundle ships needs a second interpreter.
 
 ### ✅ After installing
 
-- **Verify** — open your agent in any repo: the first reply starts with the readiness sigil and your project's docs are already in context. `geneseed doctor` should print `ok`.
-- **Run it from anywhere** — a global `npm install -g geneseed` already does this. From a checkout, `./geneseed link` writes a launcher shim into `~/.local/bin`; `.\geneseed.cmd link` writes a shim into `%LOCALAPPDATA%\Geneseed\bin` and adds it to your user PATH (open a new terminal).
-- **Everything else** — other tools (Claude Code, plain `AGENT.md`), per-repo installs, MCP servers, environment knobs, troubleshooting: **[SETUP.md](SETUP.md)**.
+- **Verify** — open your agent in any repo: the first reply starts with the readiness sigil and your project's docs are already in context. `geneseed doctor` should print `ok`. More in [Verify it works](docs/guides/verify.md).
+- **Run it from anywhere** — a global `npm install -g geneseed` already does this; from a checkout see [Run geneseed from anywhere](docs/guides/run-anywhere.md).
+- **Something wrong?** [Troubleshooting](docs/reference/troubleshooting.md) is organised by what you see.
 
 ---
 
@@ -137,14 +142,7 @@ geneseed web stop            # stop the daemon
 geneseed web status          # is it running, and where
 ```
 
-The left rail mirrors the harness's own shape:
-
-| Group | Views |
-| --- | --- |
-| *(ungrouped)* | **Dashboard** — live readout of what's deployed (voice, capabilities, drift, recent jobs) |
-| **📖 Codex** | **Constitution** · **Rules** · **Profile** · **Skills** · **Agents** · **Library** (Memory, Notebook, the wiki) · **Docs** |
-| **🩺 Care** | **Activity** · **Changes** — diff against the source, export an `improvements.md` · **Doctor** — health check across themes, links, parity and authoring gates |
-| **🎨 Setup** | **Harness** — installs, theme, footprint · **Settings** — MCP servers, server controls |
+The sidebar has six pages: **Overview** (what's deployed, health, recent jobs), **Constitution** (the rules and doctrine switches), **Library** (skills, agents, the wiki), **Personal** (your rules, profile, memory, notebook), **Installs** (hosts, local edits, doctor, server) and **Docs** — this documentation, opening on the Understand track, with a map of what Geneseed put on your machine.
 
 It binds to `127.0.0.1` only and runs entirely offline — no npm needed at runtime; the UI build ships in `web/dist/`. Mutating actions run in the background and report back as toasts (fire-and-notify), guarded by a per-session token so other sites can't trigger them. A global **Spotlight** search in the topbar jumps to any agent, skill, rule, doc, or MCP server. Rebuild the UI after changing anything under `web/src/` with `cd web && npm install && npm run build`. If `web/dist/` is missing (fresh clone, never built), `geneseed web` offers to run that build for you — answer `Y` and it installs, builds, and starts the server; in non-interactive shells it prints the manual recipe instead.
 
@@ -166,7 +164,7 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 | **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
 | **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
 | **🤖 Agents** (18) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `researcher`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
-| **🛠 Skills** (53) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
+| **🛠 Skills** (56) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
 | **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
 | **📓 Notebook** (`notebook/`) | the agent's sovereign space — any medium (code, tools, data, notes), self-ruled via a seed-once charter, always git-ignored; only its `.gitignore` is build-asserted |
@@ -197,26 +195,11 @@ Fourteen themes ship — each a single JSON file in `themes/` carrying voice tok
 | 🏟️ **sports** | play-by-play commentary |
 | 🏍 **biker** · 🎤 **commentator** · 🃏 **joker** · 🤖 **marvin** · 😤 **mean** · 🏎 **verstappen** | community-added voices for fun |
 
-Pick with `--theme NAME` or via the setup wizard. The theme is remembered in a `.geneseed-theme` marker, so later upgrades preserve it. `doctor` checks every theme defines the same keys, so flavour drift is impossible. Adding a new voice token to `themes/_TEMPLATE.json`? Run `geneseed-build --sync-themes` to fill it into every theme (template's placeholder value, reported for restyling) before `doctor` is expected to pass again.
+Pick with `--theme NAME` or via the setup wizard; upgrades remember it. More in [Themes](docs/concepts/themes.md).
 
 ### 🪶 Footprint (lean vs full)
 
-A second per-install dial, **footprint**, sets how much of the constitution `AGENT.md` carries *inline* every turn — a token-cost knob, not a change to which Rules apply (every Rule is always in force, and so is the whole of the Ethos).
-
-| Footprint | The Ethos + Sections 1–2 of `AGENT.md` | Trade-off |
-| --- | --- | --- |
-| **lean** *(default)* | the Ethos, each Rule and each active doctrine rule in their **authored** short form; then pointers to the full text | lighter every turn; rationale is one on-demand read away |
-| **full** | the Ethos, every Rule and every active doctrine rule at complete text **and** rationale, inlined | maximum guidance density; largest per-turn token cost |
-
-**Lean is authored, not cut.** The Ethos, every Rule and every doctrine rule carry a hand-written lean form beside their full text (`LEAN` blocks in `src/`), so a rule's lean footprint is decided by its author and not by where its first full stop happens to fall — the earlier first-sentence cut shipped Rule II as one 36-character line and dropped its stop-and-ask mechanism, and shipped a doctrine rule like *Change as little as the task requires.* as six words with no verb to act on.
-
-Both footprints put the full text on disk beside `AGENT.md`: `laws/`, `ontology/` and `doctrines/` all ship in the bundle at **full** text whatever the footprint, and **all five pack files ship whether or not the pack was built in** — which is what lets a citation into an inactive pack resolve. So lean is a context/token optimization, **not** a rules cut.
-
-Lean is the default: the rationale is one read away and the context it frees is paid back on every turn. Switch to **full** when token cost is a non-issue or you run a smaller model, which leans harder on always-present rationale. Set it with `--footprint lean|full`, the Settings toggle, the per-harness dropdown in the Harnesses tab, or the setup wizard. It's remembered in a `.geneseed-footprint` marker and preserved across rebuilds, on every host (OpenCode, Claude Code, Bob, OpenClaude).
-
-Either way the harness is otherwise identical — same files, Rules, capabilities, and guards; lean only relocates the *reasoning* to on-demand (and adds the standalone law, ontology and doctrine files to global/Claude/Bob installs). The one behavioural edge: with the rationale always in context, **full** applies a rule's nuance more reliably on subtle edge cases — or with a weaker model that may not reach for the pointer.
-
-Want to check a build before it touches anything real? `geneseed validate --theme NAME --emit MODE --out TARGET` renders and validates into a throwaway sandbox — nothing under `--out`/`--root` is written — and exits non-zero on any problem. Details: [SETUP.md](SETUP.md#dry-run-a-build-validate).
+A second per-install dial sets how much of the constitution the root file carries *inline* every turn — a token-cost knob, not a change to which Rules apply. **lean** (the default) carries each rule's hand-written short form and points to the full text on disk; **full** inlines every rule with its rationale. Every rule is in force either way. More in [Footprint](docs/concepts/footprint.md) and [Choose your setup](docs/guides/choose-your-setup.md).
 
 ---
 
@@ -292,7 +275,8 @@ Geneseed/
 ├── themes/               voice token maps (14 themes shipped)
 ├── web/                  Vite + React UI source; the committed web/dist/ build is what ships
 ├── tests/                Node test suites, golden.mjs (every emit config) and mutate.mjs
-├── docs/                 guides (web-ui, wiki, …) + docs/web/ (the console's Docs pages);
+├── docs/                 understand/ guides/ concepts/ reference/ — the docs, also the console's
+│                         Docs pages; maintainer notes beside them (extending, design-history…);
 │                         specs/, reviews/, superpowers/ are local working docs — git-ignored
 ├── adapters/             per-host glue (opencode/, claude-code/, bob/, openclaude/)
 └── .github/workflows/    ci.yml (doctor + tests) · publish.yml (npm, OIDC, manual only)
@@ -324,19 +308,17 @@ geneseed rebuild-all   # re-render every registered install in its own theme + m
 ./geneseed upgrade     # just the content refresh (remembers theme + emit mode)
 ```
 
-**Local edits survive.** The self-improvement loops let the agent refine its deployed agent/skill files in place. Before setup, re-theme, or upgrade overwrites them, any drift is auto-exported to a markdown **improvements file** under `improvements/` *inside the deployed harness dir* (e.g. `~/.config/opencode/improvements/` for the global install) — beside the install it describes, untouched by rebuilds and uninstall. Hand it to an agent in this repo to back-port the changes into `src/`. On demand: `./geneseed diff --out FILE`, or the **Changes** page in the web console.
-
-Details and precedence rules: [SETUP.md → Upgrade](SETUP.md#upgrade).
+**Local edits survive.** If the agent refined its deployed agent/skill files in place, an upgrade exports that drift to an `improvements/` file inside the install before overwriting. Details: [Upgrade](docs/guides/upgrade.md).
 
 ## 📚 Documentation
 
 | Page | Read it when… |
 | --- | --- |
-| **[SETUP.md](SETUP.md)** | Installing — every path, configuration knob, env var, verify, troubleshooting |
+| **[docs/](docs/README.md)** | Using Geneseed — Understand, Guides (install, setup choices, MCP, wiki, upgrade, uninstall…), Concepts and Reference (CLI, environment, troubleshooting, glossary) |
 | **[DESIGN.md](DESIGN.md)** | Changing structure — the spec and the decisions behind it |
 | **[SHIPPED.md](SHIPPED.md)** | What's in the harness today — capabilities ↔ the spec behind each |
+| **[docs/extending.md](docs/extending.md)** | Adding to the harness — what each kind of addition costs |
 | **[docs/web-ui.md](docs/web-ui.md)** | The web console — every view, the launch/daemon/PWA surface, security model |
-| **[docs/wiki.md](docs/wiki.md)** | The machine wiki — your personal knowledge base, setup and writing model |
 | **[docs/token-footprint.md](docs/token-footprint.md)** | What the harness costs in context-window tokens, per host |
 | **[docs/opencode-plugin-setup.md](docs/opencode-plugin-setup.md)** | Installing the OpenCode plugins — the one-time wiring they all share |
 | **[CHANGELOG.md](CHANGELOG.md)** | What changed between versions |

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.10.0**.
+> string. Current label: **3.12.0**.
 
 ## Capabilities
 
@@ -29,7 +29,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 53 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
+| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 56 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
 | **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |

package/adapters/bob/README.md

@@ -1,6 +1,6 @@
 # 🤖 IBM Bob adapter
 
-> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
 
 [IBM Bob](https://bob.ibm.com) is **Claude-Code-shaped**: a project `.bob/`
 layer, an `AGENTS.md` instructions file, `SKILL.md` skills, subagents, and a

package/adapters/claude-code/README.md

@@ -1,6 +1,6 @@
 # 🪝 Claude Code adapter
 
-> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [OpenCode adapter](../opencode/README.md)
 
 Optional. Claude Code supports lifecycle **hooks**, so a team using it can make
 parts of the harness fire automatically instead of relying on agent
@@ -14,10 +14,11 @@ bin/geneseed-hook.mjs …` — so at user scope they would fire and fail in ever
 repo that doesn't vendor the harness. A generated global install wires
 absolute-path hooks instead — `geneseed setup` does that for you.) It:
 
-- on **PreToolUse** (matcher `Bash`), **on an install that built the `process` pack in**,
-  runs `harness git-gate` — the tool-boundary half of Doctrine process 5 (*consent before
-  every commit and push*). Drop that pack and this hook is not written at all; the
-  invariant-territory refusals (`rm -rf`, force-push) stay in every build. The hook inspects
+- on **PreToolUse** (matcher `Bash`), runs `geneseed-hook git-gate` — the tool-boundary
+  half of Doctrine process 5 (*consent before every commit and push*) and of the
+  destructive-git Rule. Drop the `process` pack (or exclude process 5) and the hook stays,
+  wired with `--no-consent`: commits and pushes pass without asking, while the
+  invariant-territory refusals (force-push, `reset --hard`) stay in every build. The hook inspects
   command and, when it runs a `git commit` or `git push` (bare, flagged, `-C <path>`,
   or chained like `git add . && git commit … && git push`), returns
   `permissionDecision: "ask"` so Claude Code **prompts on every such call**. Crucially
@@ -31,27 +32,31 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
   `create_or_update_file` / `merge_pull_request`, which bypass Bash. To gate those too,
   widen the matcher to `"Bash|mcp__github__.*"` — `git-gate` ignores any payload it
   doesn't recognise as a commit/push, so over-matching the tool surface is harmless.
+- on **PreToolUse** (matcher `Write|Edit|MultiEdit|NotebookEdit`), runs
+  `geneseed-hook rule-gate` — refuses a write that would put a credential into a tracked
+  file, and asks first on the first write to `user-rules.md` or a memory file (whether
+  something you want kept is a rule or a fact is your call). Ordinary edits pass.
 - on **SessionStart** (`startup`/`clear` only — a fresh context), prints `AGENT.md`
-  so the harness is in context from the first turn, then runs `harness context` to
+  so the harness is in context from the first turn, then runs `geneseed-hook context` to
   **inject the project context** directly into the session — so the project-context load is
   by the hook, not left to the agent to remember (lazy entries are only listed). On
-  **`resume`** it runs `harness context` *without* re-`cat`ting `AGENT.md`: the resumed
+  **`resume`** it runs `geneseed-hook context` *without* re-`cat`ting `AGENT.md`: the resumed
   conversation already carries the harness, so re-injecting the static file each resume
   is pure token waste — only the (possibly changed) project context is refreshed;
-- on **Stop**, runs `harness learn` over the session to capture durable memories.
+- on **Stop**, runs `geneseed-hook learn` over the session to capture durable memories.
   Claude Code pipes the hook payload (with the session's `transcript_path`) to the
   command on stdin; `learn` reads that, flattens the transcript, distils new
   memories, and **writes them into the bundle's `memory/` while updating
   `MEMORY.md`** — deduping against what is already stored. No `< /dev/null` and no
   redirection: the stdin payload is the whole point.
-- on **SubagentStop**, runs the *same* `harness learn` command. `learn` reads the
+- on **SubagentStop**, runs the *same* `geneseed-hook learn` command. `learn` reads the
   payload's `hook_event_name`, sees a subagent dispatch, and routes it to the
   per-agent lesson path instead of the shared store: it distils at most one durable
   lesson and appends it to `memory/agents/<agent-name>.md` (capped, newest kept). If
   the payload does not name the subagent, the step is a silent no-op — never a
   crash, never a wrong write. This is the parity twin of the OpenCode learn plugin's
   child-session branch.
-- on **PreCompact**, runs the same `harness learn` once more. `learn` distils the
+- on **PreCompact**, runs the same `geneseed-hook learn` once more. `learn` distils the
   *tail* of the transcript, so per-turn Stop is a sliding window over the session —
   and auto-compaction is the moment that window is about to be summarised away.
   This captures memory *before* the summary; the SessionStart `compact` matcher
@@ -68,11 +73,11 @@ the commands are identical (`node bin/geneseed-hook.mjs …`).
 
 Why inject rather than instruct? The constitution tells the agent to read the project
 context at startup, but startup rituals are exactly what agents skip. The
-`harness context` hook removes the choice: the eager files' contents land in
+`geneseed-hook context` hook removes the choice: the eager files' contents land in
 context before the first turn regardless of agent discipline. On tools without
 hooks or plugins, the AGENT.md prose still carries the rule.
 
-> **Auto-discovery (parity with OpenCode).** `harness context` no longer needs a
+> **Auto-discovery (parity with OpenCode).** `geneseed-hook context` no longer needs a
 > hand-filled `context.json`: with no manifest (or just the empty stub) it
 > **auto-discovers the repo's docs by convention** — root `AGENTS.md`/`AGENT.md`/
 > `CLAUDE.md`/`README.md`/`CONTRIBUTING.md` injected eager, `docs/`/`adr/`/monorepo

package/adapters/openclaude/README.md

@@ -1,6 +1,6 @@
 # 🦀 OpenClaude adapter
 
-> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
 
 [OpenClaude](https://openclaude.gitlawb.com/) (`@gitlawb/openclaude`, binary
 `openclaude`) is an open-source coding-agent CLI that "originated from the Claude

package/adapters/opencode/README.md

@@ -1,6 +1,6 @@
 # 🔌 OpenCode adapter
 
-> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [How OpenCode loads](HOW-OPENCODE-LOADS.md) · [Global harness spec](GLOBAL-HARNESS-SPEC.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [How OpenCode loads](HOW-OPENCODE-LOADS.md) · [Global harness spec](GLOBAL-HARNESS-SPEC.md)
 
 [OpenCode](https://opencode.ai) is `AGENTS.md`-native and has first-class
 **subagents** and **commands**, so Geneseed fits it cleanly. Pick the depth you
@@ -211,7 +211,7 @@ the harness live entirely in the global config dir with zero per-repo files.
   install). Per wiki: eager entries inject in full, lazy entries list, and the
   `conventions` / `inbox` / `protected` metadata is surfaced — on the **same**
   budgets, compaction and transform paths as the project context. Schema and
-  behaviour: [SETUP.md → Wiki](../../SETUP.md#wiki--your-own-knowledge-base-optional).
+  behaviour: [the wiki guide](../../docs/guides/wiki.md).
 
 It needs no model, writes nothing, skips the learn plugin's throwaway sessions, and
 swallows every error. Output mirrors `geneseed-hook context`.
@@ -468,9 +468,9 @@ OpenCode runs, so the command has to resolve — the `uvx` form above needs only
 call). No uv? `pipx install markitdown-mcp` and swap the command to `["markitdown-mcp"]`.
 Or drop the block entirely — the skill falls back to a CLI converter (MarkItDown /
 Pandoc / Docling) and never installs one silently. Listed but not connecting? The
-command isn't on PATH — see [SETUP.md → MCP server won't connect](../../SETUP.md#mcp-server-wont-connect).
+command isn't on PATH — see [the MCP guide](../../docs/guides/mcp.md).
 Full runbook, including the corporate-TLS (`UV_SYSTEM_CERTS`) step and the OCR extras:
-[SETUP.md → MarkItDown via MCP](../../SETUP.md#markitdown-via-mcp-opencode).
+[the MCP guide](../../docs/guides/mcp.md).
 
 ## Optional add-on — git-worktree isolation (third-party, not vendored)
 

package/adapters/opencode/plugins/geneseed-guard.js

@@ -16,8 +16,22 @@
 //
 // Install: dropped into the plugins dir by `build --emit opencode[-global]` (the *.js
 // glob), exactly like the context and learn plugins. Errors never break a tool call.
+//
+// `permission.ask` — the loop/* exemption (Consent Before Push). OpenCode's static
+// `permission.bash` globs (`git commit*`/`git push*` = "ask", written by
+// js/hosts/settings.mjs) cannot see which branch is checked out — they are a build-time
+// string match with no request-time context. This hook is the ONLY seam where Geneseed can
+// look at the live branch, and it only DOWNGRADES an ask to allow: only a fixed set of
+// commit/push forms (see `loopExempt` below, the twin of js/hosts/hooks.mjs's) on a `loop/*`
+// branch a loop was actually LAUNCHED on — not just named `loop/...`. It is a WHITELIST, not
+// a blacklist: a false ask costs one prompt, a false allow publishes. It never raises the
+// bar: anything not on the whitelist, anything off a launched loop branch, a status this hook
+// did not itself leave as the default "ask", or any non-bash permission leaves `output.status`
+// untouched and OpenCode's own ask (or another hook's deny) stands. A host version that never
+// fires `permission.ask` simply never reaches this hook — the static ask still fires, so the
+// failure mode is one extra prompt, never a silent allow.
 
-import { promises as fs } from "node:fs"
+import { promises as fs, existsSync, statSync, lstatSync, readFileSync, openSync, readSync, closeSync } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath } from "node:url"
 import { homedir } from "node:os"
@@ -267,7 +281,131 @@ function ruleStoreTarget(p) {
 // substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
 const WIKI_MUTATE_TOOLS = [...WRITE_TOOLS, "delete", "remove", "rename", "move", "trash"]
 
-export const GeneseedGuard = async () => {
+// ---- the loop/* exemption (Consent Before Push) --------------------------------
+// Twin of js/hosts/gitref.mjs (currentBranch/loopLaunched) and js/hosts/hooks.mjs's
+// git-gate (the rest) — keep in step. Node's native sync `fs` (not the `fs.promises`
+// import above): a worktree's `.git` is read the same way the Claude/Bob hook reads it, so
+// the two decide the exemption identically. This plugin cannot import from `js/` at all
+// (it is copied whole into an OpenCode install, outside this repo's module graph), so it
+// keeps its own standalone copy rather than the single shared owner the Node side has.
+
+const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/
+
+// No newline, backtick, or `$(` substitution anywhere, no `<`/`>` redirect, and no single
+// `&` (a shell runs `a & b` as two commands exactly like `a && b`) — these can smuggle a
+// second command (or a shared-branch target) past every check below. `(?<!&)&(?!&)` matches
+// a lone `&` without matching either half of a doubled `&&`.
+const UNSAFE_CHARS_RE = /[\n`<>]|\$\(|(?<!&)&(?!&)/
+
+// The only three git shapes a loop's own automation ever needs — see js/hosts/hooks.mjs's
+// identically-named constants for the full rationale. The token class `[\w./:@^~=+,-]`
+// excludes quotes, braces, `!`, `*`, `$` and `&` — a brace/glob expansion is exactly how a
+// shell turns one whitelisted-looking token into several unknown ones, which is also why the
+// `-F`/`--file` path uses this same class rather than the looser `[^\s'"]+` it once did: that
+// loose class let `git commit -F {m,--amend}` brace-expand into an amend of the last commit.
+const ARG_RE = "[\\w./:@^~=+,-]+"
+const SEG_ADD_RE = new RegExp(`^git\\s+add(\\s+${ARG_RE})*$`)
+const SEG_COMMIT_RE = new RegExp(`^git\\s+commit(\\s+-q)?\\s+(-F\\s+|--file[=\\s])${ARG_RE}(\\s+-q)?$`)
+const SEG_READONLY_RE = new RegExp(`^git\\s+(status|diff|log|rev-parse|show)(\\s+${ARG_RE})*$`)
+
+/**
+ * `git push`, exactly: `[-u|--set-upstream] <remote> HEAD:<branch>` or
+ * `HEAD:refs/heads/<branch>` — the ONLY exempt form, same as js/hosts/hooks.mjs's
+ * `pushSegmentOk`. An explicit refspec is immune to `push.default`/`remote.*.push`
+ * redirection and refuses to coexist with a mirror/`+`/`:`-prefixed form; nothing else is.
+ */
+function pushSegmentOk(seg, branch) {
+  const m = /^git\s+push(?:\s+(.*))?$/.exec(seg)
+  if (!m) return false
+  const rest = (m[1] || "").trim()
+  if (!rest) return false
+  const tokens = rest.split(/\s+/)
+  let i = 0
+  if (tokens[i] === "-u" || tokens[i] === "--set-upstream") i += 1
+  const remote = tokens[i]
+  if (remote === undefined || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(remote)) return false
+  i += 1
+  const ref = tokens[i]
+  i += 1
+  if (ref === undefined || i !== tokens.length) return false
+  return ref === `HEAD:${branch}` || ref === `HEAD:refs/heads/${branch}`
+}
+
+const LOOP_STATE_MARKER = "<!-- loop-state:begin -->"
+
+/**
+ * Whether `<root>/LOOP.md` carries the engine's state marker — read at most 64 KB.
+ * `lstatSync` (never `statSync`, which follows a link) must find an ordinary file: a FIFO
+ * would block the read, a symlink could point anywhere outside the repo.
+ */
+function loopLaunched(gitRoot) {
+  let fd
+  try {
+    const p = path.join(gitRoot, "LOOP.md")
+    if (!lstatSync(p).isFile()) return false
+    fd = openSync(p, "r")
+    const buf = Buffer.alloc(65536)
+    const n = readSync(fd, buf, 0, buf.length, 0)
+    return buf.toString("utf8", 0, n).includes(LOOP_STATE_MARKER)
+  } catch {
+    return false
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd) } catch { /* already gone */ } }
+  }
+}
+
+/**
+ * The branch checked out in `cwd`, and the directory holding `.git` for it, read from
+ * .git/HEAD without spawning git — a worktree's `.git` is a FILE naming its gitdir, so both
+ * shapes are followed. `{ branch: null, root: null }` on anything unexpected (detached HEAD,
+ * no repo, unreadable): the caller then leaves the ask alone.
+ */
+function currentBranch(cwd) {
+  try {
+    let dir = path.resolve(cwd)
+    for (;;) {
+      const dotgit = path.join(dir, ".git")
+      if (existsSync(dotgit)) {
+        let gitdir = dotgit
+        if (statSync(dotgit).isFile()) {
+          const m = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotgit, "utf8"))
+          if (!m) return { branch: null, root: null }
+          gitdir = path.resolve(dir, m[1])
+        }
+        const ref = /^ref:\s*refs\/heads\/(.+?)\s*$/m.exec(readFileSync(path.join(gitdir, "HEAD"), "utf8"))
+        return { branch: ref ? ref[1] : null, root: dir }
+      }
+      const up = path.dirname(dir)
+      if (up === dir) return { branch: null, root: null }
+      dir = up
+    }
+  } catch {
+    return { branch: null, root: null }
+  }
+}
+
+/**
+ * Consent Before Push's loop/* exemption — the twin of js/hosts/hooks.mjs's `loopExempt`.
+ * True only when the command carries none of the unsafe characters, every `&&`/`;`/`||`/`|`
+ * segment is one of the three whitelisted git shapes (every push segment also passing
+ * `pushSegmentOk`), and the branch checked out in `cwd` starts with `loop/` AND its git root
+ * carries a launched LOOP.md.
+ */
+function loopExempt(command, cwd) {
+  if (typeof command !== "string" || UNSAFE_CHARS_RE.test(command)) return false
+  const { branch, root } = currentBranch(cwd)
+  if (!branch || !branch.startsWith("loop/")) return false
+  if (!root || !loopLaunched(root)) return false
+  const segments = command.split(/&&|\|\||[;|]/).map((s) => s.trim()).filter(Boolean)
+  if (!segments.length) return false
+  return segments.every((seg) => SEG_ADD_RE.test(seg) || SEG_COMMIT_RE.test(seg)
+    || SEG_READONLY_RE.test(seg) || pushSegmentOk(seg, branch))
+}
+
+export const GeneseedGuard = async (ctx) => {
+  // The session's working directory, the same resolution the context plugin uses — a
+  // worktree session's `.git` is a FILE, which `currentBranch` already follows.
+  const root = () => ctx?.worktree || ctx?.directory || process.cwd()
   return {
     "tool.execute.before": async (input, output) => {
       if (OFF) return
@@ -318,6 +456,23 @@ export const GeneseedGuard = async () => {
         log(`inspect error (ignored): ${err?.message ?? err}`)
       }
     },
+    "permission.ask": async (input, output) => {
+      // Never throw from a permission hook — leave `output.status` untouched on any
+      // error, exactly as a crashed check here must default to the static ask standing.
+      try {
+        if (OFF) return
+        // Never loosen anything but the plain "ask" this hook itself would otherwise leave
+        // alone — a deny (or any other status another hook already set) is never overwritten.
+        if (output?.status && output.status !== "ask") return
+        if (input?.type !== "bash") return
+        // ONLY `input.metadata?.command` — no pattern/title fallback. A value this hook did
+        // not itself read in full is a value it must not reason about.
+        const command = input?.metadata?.command
+        if (typeof command !== "string" || !command || !GIT_GATE_RE.test(command)) return
+        if (await sovereignBypass(root())) return
+        if (loopExempt(command, root())) output.status = "allow"
+      } catch { /* leave output.status untouched */ }
+    },
   }
 }