geneseed 3.9.0 → 3.11.0

package/CHANGELOG.md

@@ -8,7 +8,95 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
-_Nothing yet._
+## [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
+maintained: `geneseed uninstall` it before upgrading, or leave its files as they are — nothing
+re-emits them any more. Breaking for Copilot users only; every other host gains features.
+
+### Removed
+- **GitHub Copilot is no longer a host** — dropped for lack of support and of cross-tool
+  support. `--emit copilot` / `--emit copilot-global`, the `--host copilot` hook dialect, the
+  Copilot agent dialect, its MCP target, the setup and web-console options and
+  `adapters/copilot/` are gone. Geneseed now emits for OpenCode, Claude Code, Bob and
+  OpenClaude, plus the plain `AGENT.md` bundle (#166).
+
+### Fixed
+- **The session files reach the session.** The root file names `user-rules.md`, `PROFILE.md`,
+  the Memory and Notebook indexes, `wiki.jsonc` and `context.json` for session start, but on a
+  Claude-shaped install (Claude Code, Bob, OpenClaude) the context hook only looked at the repo
+  root — so none of them were ever injected, and the root told the model they sit "beside this
+  file", where they are not. The hook and the OpenCode context plugin now inject them from the
+  install's own folder as a `SESSION FILES` block, skipping any file still at its seed; the root
+  gives each host's real path; Claude-shaped installs now seed `context.json`; and the OpenCode
+  plugin finds `wiki.jsonc` on a project install (#167).
+- **Bob folder skills know where they live.** Bob hands a skill's text without its directory, so
+  a folder skill's `<this-skill-directory>/…` paths were unresolvable; the Bob emit now writes the
+  real path. `daydream` gained its missing frontmatter, `react-view-transitions` is named after
+  its folder, and `doctor` checks every folder skill's `name`/`description` (#164).
+
+### Changed
+- **A lighter lean root.** Restated prose is full-footprint only: the laws, Ethos, doctrine,
+  posture and mode intros, §3's dispatch envelope and council roster (they live in the
+  parallel-agents and council skills), §10 Scripts, and the folder-skill list on hosts that list
+  skills natively. The lean Claude root drops from ~33k to ~29k characters (#165).
 
 ## [3.9.0] — 2026-09-30
 

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,11 +10,11 @@
 [![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-54-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/)
-[![OpenCode · Claude Code · Bob · Copilot · OpenClaude · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20Copilot%20·%20OpenClaude%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
+[![OpenCode · Claude Code · Bob · OpenClaude · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20OpenClaude%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
 
 [**Why**](#-1--why-geneseed) · [**Setup**](#-2--setup) · [**Web & terminal**](#-3--web--terminal) · [**What you get**](#-4--what-you-get)
 
@@ -24,7 +24,7 @@
 
 <p align="center"><img src="docs/assets/demo.svg" alt="geneseed setup, then two laws catching a force-push and a credential at the tool boundary" width="760"></p>
 
-**Geneseed compiles your agent's rules instead of asking you to write them.** One source in `src/` renders into a ready-made harness for OpenCode, Claude Code, Bob, Copilot, OpenClaude, or any `AGENT.md` tool: a constitution of laws and doctrines, a roster of capability agents, native skills, a memory convention — and, wherever the host has a hook surface, gates that *enforce* the laws at the tool boundary instead of hoping the model remembers them.
+**Geneseed compiles your agent's rules instead of asking you to write them.** One source in `src/` renders into a ready-made harness for OpenCode, Claude Code, Bob, OpenClaude, or any `AGENT.md` tool: a constitution of laws and doctrines, a roster of capability agents, native skills, a memory convention — and, wherever the host has a hook surface, gates that *enforce* the laws at the tool boundary instead of hoping the model remembers them.
 
 ```bash
 npx geneseed setup
@@ -36,12 +36,12 @@ 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, Copilot 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, six targets.** Skills are byte-identical on every host; only the wiring differs. Every commit renders all 317 emit configurations, and a second emit into the same tree must change nothing.
+- **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.
 - **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** (54) | 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** · **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,62 +195,47 @@ 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, Copilot).
-
-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).
 
 ---
 
 ## 🔌 Supported harnesses
 
-One source, six emit targets. Geneseed builds into whichever host you point it
+One source, five emit targets. Geneseed builds into whichever host you point it
 at — each with a per-repo and a global (`-global`) variant — plus a portable
 `files` bundle any `AGENT.md`-aware tool can read. **OpenCode** runs its own
-engine (JS plugins, colour themes, LSP); **Claude Code**, **Bob**, **Copilot**
+engine (JS plugins, colour themes, LSP); **Claude Code**, **Bob**
 and **OpenClaude** share one Claude-shaped engine that diverges only by host dialect.
 
 The harness — its Rules, Agents, Skills, Memory convention, and preamble voice —
 is **identical on every host**. What differs is how much of it the host can
 *automate* for you (via plugins or hooks) versus carry as preamble discipline.
 
-| Capability | OpenCode | Claude Code | Bob | Copilot | OpenClaude |
-| --- | :---: | :---: | :---: | :---: | :---: |
-| **Instructions file** | `AGENT.md` + `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `AGENTS.md` / `copilot-instructions.md` | `CLAUDE.md` (in `.openclaude/` per repo) |
-| **Agents** (capability specialists) | ✅ native | ✅ | ✅ | ✅ `.agent.md` | ✅ |
-| **Skills** (byte-identical) | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Memory & Notebook** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Context injection** | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ | 🪝 hook⁴ |
-| **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ | 🪝 hook⁴ |
-| **Git-gate consent** (process 5) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ | 🪝 hook⁴ |
-| **Rule-gate consent** (process 1) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ | 🪝 hook⁴ |
-| **Laws I / IV at the boundary** | ⚙️ plugin (block) | 🪝 hook (ask) | 🪝 hook¹ (exit 2) | 🪝 hook³ (ask) | 🪝 hook⁴ (ask) |
-| **Sovereign-repo excludes** | ⚙️ plugin | ✅ `claudeMdExcludes` | ✅ rules-shadow | ➖ none | ✅ `claudeMdExcludes` |
-| **MCP server wiring** | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcp-config.json` | ✅ `mcpServers` |
-| **Colour themes** | ✅ full palette | ➖ | ➖ | ➖ | ➖ |
-| **LSP · workflow runner · primary-agent · `/`-commands** | ✅ | ➖ | ➖ | ➖ | ➖ |
-
-<sub>✅ native support · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 carried by preamble prose only · ➖ no host mechanism (harness discipline still applies) · ¹ Bob's own hook contract: global hooks in `~/.bob/settings/settings.json`, Claude's event names but stdout ignored on `PreToolUse` — a refusal is **exit code 2**. So Laws I/IV exit 2, the consent rules are a stderr line, `SessionStart` context is plain stdout, `Stop` runs learn; `SubagentStop`/`PreCompact` are not Bob events and are not written. Unverified live (no Bob install on the authoring machine); the harness still holds via the rules preamble. · ² OpenCode's `tool.execute.before` can only allow or throw, with no "ask the user" tier, so the rule gate is a one-shot speed bump there rather than a prompt. · ³ Copilot's `~/.copilot/settings.json` hooks (`sessionStart`, `preToolUse`, `agentStop`, `preCompact`) wired by the **global** emit only; `preToolUse` has an ask tier, so every rule asks as on Claude Code. Unverified live (no Copilot CLI on the authoring machine). · ⁴ OpenClaude is a Claude Code fork: Claude's hook groups and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). Unverified live (no OpenClaude install on the authoring machine).</sub>
+| Capability | OpenCode | Claude Code | Bob | OpenClaude |
+| --- | :---: | :---: | :---: | :---: |
+| **Instructions file** | `AGENT.md` + `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (in `.openclaude/` per repo) |
+| **Agents** (capability specialists) | ✅ native | ✅ | ✅ | ✅ |
+| **Skills** (byte-identical) | ✅ | ✅ | ✅ | ✅ |
+| **Memory & Notebook** | ✅ | ✅ | ✅ | ✅ |
+| **Context injection** | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ |
+| **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook³ |
+| **Git-gate consent** (process 5) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ |
+| **Rule-gate consent** (process 1) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ (warn) | 🪝 hook³ |
+| **Laws I / IV at the boundary** | ⚙️ plugin (block) | 🪝 hook (ask) | 🪝 hook¹ (exit 2) | 🪝 hook³ (ask) |
+| **Sovereign-repo excludes** | ⚙️ plugin | ✅ `claudeMdExcludes` | ✅ rules-shadow | ✅ `claudeMdExcludes` |
+| **MCP server wiring** | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
+| **Colour themes** | ✅ full palette | ➖ | ➖ | ➖ |
+| **LSP · workflow runner · primary-agent · `/`-commands** | ✅ | ➖ | ➖ | ➖ |
+
+<sub>✅ native support · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 carried by preamble prose only · ➖ no host mechanism (harness discipline still applies) · ¹ Bob's own hook contract: global hooks in `~/.bob/settings/settings.json`, Claude's event names but stdout ignored on `PreToolUse` — a refusal is **exit code 2**. So Laws I/IV exit 2, the consent rules are a stderr line, `SessionStart` context is plain stdout, `Stop` runs learn; `SubagentStop`/`PreCompact` are not Bob events and are not written. Unverified live (no Bob install on the authoring machine); the harness still holds via the rules preamble. · ² OpenCode's `tool.execute.before` can only allow or throw, with no "ask the user" tier, so the rule gate is a one-shot speed bump there rather than a prompt. · ³ OpenClaude is a Claude Code fork: Claude's hook groups and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). Unverified live (no OpenClaude install on the authoring machine).</sub>
 
 **Reading the matrix.** Everything above the divider is at full parity — no host
 drops an Agent, Skill, or the memory convention. The asymmetry is entirely in
-*automation mechanism*: OpenCode's plugin surface and the Claude/Bob/Copilot/OpenClaude hook
+*automation mechanism*: OpenCode's plugin surface and the Claude/Bob/OpenClaude hook
 surfaces enforce a few Rules for you, each in the tier its host offers (a prompt on
 Claude Code, a hard block or a logged warning where the host has no prompt to
 give), and what no host can automate rides the preamble. The OpenCode-only extras (themes, LSP,
@@ -260,7 +243,7 @@ workflow runner, primary-agent) have no analogue on a Claude-shaped host.
 
 Per-host wiring in depth: **[OpenCode](adapters/opencode/README.md)** ·
 **[Claude Code](adapters/claude-code/README.md)** ·
-**[Bob](adapters/bob/README.md)** · **[Copilot](adapters/copilot/README.md)** ·
+**[Bob](adapters/bob/README.md)** ·
 **[OpenClaude](adapters/openclaude/README.md)**.
 Token cost per host: **[docs/token-footprint.md](docs/token-footprint.md)**.
 
@@ -292,9 +275,10 @@ 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/, copilot/, openclaude/)
+├── 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 |
@@ -345,7 +327,6 @@ Details and precedence rules: [SETUP.md → Upgrade](SETUP.md#upgrade).
 | ⤷ [HOW-OPENCODE-LOADS.md](adapters/opencode/HOW-OPENCODE-LOADS.md) | Why a file shows up twice; plugin loading |
 | **[adapters/claude-code/](adapters/claude-code/README.md)** | The Claude Code hook adapter |
 | **[adapters/bob/](adapters/bob/README.md)** | The IBM Bob adapter — Claude-shaped, rules-file preamble |
-| **[adapters/copilot/](adapters/copilot/README.md)** | The GitHub Copilot adapter — global hooks (`sessionStart`, `preToolUse`, `agentStop`, `preCompact`) |
 | **[adapters/openclaude/](adapters/openclaude/README.md)** | The OpenClaude adapter — the Claude engine under `~/.openclaude` / `.openclaude/` |
 | **[src/memory/README.md](src/memory/README.md)** | The memory convention |
 | **[src/notebook/README.md](src/notebook/README.md)** | The agent's own freeform-space convention |

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.9.0**.
+> string. Current label: **3.11.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, 54 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` |
@@ -37,7 +37,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | **Terminal rendering** | There is no full-screen control panel: `tui` and `menu` are verbs that say so and print the command list. The display-width and glyph layer ships on, behind `status` and the install animation | `2026-06-07-tui-refactor-polish` · `2026-06-08-tui-modern-refresh` · `2026-06-11-windows-tui` |
 | **Web console** | Local browser UI (Dashboard; Codex: Constitution, Rules, Profile, Skills, Agents, Library, Docs; Care: Activity, Changes, Doctor; Setup: Harness, Settings), auto-build, in-app docs menu | `2026-06-12-web-ui-v2` · `2026-06-12-web-auto-build` · `2026-06-13-docs-menu` |
 | **OpenCode adapter** | Native agents/skills mapping + plugins (context, learn, guard, workflow, notify, ponytail, activity); global-emit link integrity; JSONC config target | `2026-06-07-opencode-adapter-features` · `2026-06-07-global-emit-link-integrity` · `2026-06-12-opencode-jsonc-target` · `2026-06-16-ponytail-minimal-code-mode` |
-| **Host hooks, per dialect** | Every host gets the hook surface its runtime offers, spoken in that runtime's own verdict dialect via `--host`: Claude Code asks (`permissionDecision`), OpenClaude asks exactly as Claude does (a Claude Code fork, under `~/.openclaude` / `.openclaude/`), Copilot asks as Claude does (`sessionStart`, `preToolUse`, `agentStop`, `preCompact` in `~/.copilot/settings.json`, global scope only), Bob refuses by exit code 2 (five Claude-named events, nested `~/.bob/settings/settings.json`, no subagent event), OpenCode's guard throws. Laws I/IV are the hard tier everywhere; the consent rules ask where a host can ask and warn where it cannot. `tool-gate` fuses the two gates for hosts that run one command per event; `PreCompact` runs `learn` before Claude compacts; every block or ask lands in `notebook/gates.jsonl` on every host | [copilot](adapters/copilot/README.md) · [bob](adapters/bob/README.md) · [claude-code](adapters/claude-code/README.md) · [candidate hosts](docs/candidate-hosts.md) |
+| **Host hooks, per dialect** | Every host gets the hook surface its runtime offers, spoken in that runtime's own verdict dialect via `--host`: Claude Code asks (`permissionDecision`), OpenClaude asks exactly as Claude does (a Claude Code fork, under `~/.openclaude` / `.openclaude/`), Bob refuses by exit code 2 (five Claude-named events, nested `~/.bob/settings/settings.json`, no subagent event), OpenCode's guard throws. Laws I/IV are the hard tier everywhere; the consent rules ask where a host can ask and warn where it cannot. `tool-gate` fuses the two gates for hosts that run one command per event; `PreCompact` runs `learn` before Claude compacts; every block or ask lands in `notebook/gates.jsonl` on every host | [bob](adapters/bob/README.md) · [claude-code](adapters/claude-code/README.md) · [candidate hosts](docs/candidate-hosts.md) |
 | **Workflow primitive** | Saved, code-driven subagent orchestration (`workflow` tool + runtime); shipped scripts include `dispatch` — decompose a goal, route each subtask to its owning agent, converge | `2026-06-09-opencode-workflow-primitive` |
 | **Per-agent memory** | Each capability agent keeps durable lessons in `memory/agents/<name>.md`: read at dispatch, written back mechanically by `learn` on session/subagent end (OpenCode plugin + Claude `SubagentStop`; Bob has no subagent event); `learn --consolidate` rebuilds the index | `2026-07-04-orchestration-memory-upgrade` |
 | **Wiki integration** | Machine-wide knowledge base (`wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | `2026-06-11-wiki-knowledge-base` |

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
@@ -23,7 +23,8 @@ limitation to be aware of on a shared repo.
   - `agents/<name>.md` — the **Claude subagent dialect** verbatim (`name` +
     `description` + a `disallowedTools:` denylist for read-only agents).
   - `skills/<name>/SKILL.md` — **byte-identical** to every other host; skills
-    are model-invoked via the `skill` tool.
+    are model-invoked via the `skill` tool. The one exception is the folder skills'
+    own directory — see *Bob-ism 3*.
   - `rules/geneseed.md` — a **slim shadow stub** (see *Bob-ism 1* below).
   - `settings.json` — Geneseed's lifecycle hooks (gitignored by the emit's
     `.bob/.gitignore`, see the caveat below).
@@ -64,6 +65,21 @@ never gets one; the `rules/geneseed.md` shadow above covers the same
 project-bypasses-global need. An older Bob install that wrote a stale exclude is
 **self-healed** (the entry is removed) on the next emit.
 
+## Bob-ism 3 — a folder skill is told where it lives
+
+A folder skill (`explain-changes`, `token-report`, `daydream`, …) ships scripts or
+prompts beside its `SKILL.md` and names them `<this-skill-directory>/…`. Claude Code
+answers that placeholder itself — it gives the model each skill's base directory on load.
+Bob gives the skill's text only, so the model was left with a path it could not resolve
+and fell back to searching the filesystem. The Bob emit therefore writes the directory in:
+
+- per repo, relative to the workspace root — `node .bob/skills/token-report/scripts/…` —
+  which is where Bob runs commands, and stays valid in a teammate's checkout;
+- globally, the absolute path under `~/.bob/skills/`.
+
+`doctor` also requires every folder skill's `SKILL.md` to open with a frontmatter whose
+`name` is the folder's and which has a `description` — what any host registers a skill from.
+
 ## Hooks — Bob's own protocol
 
 Bob documents lifecycle hooks (its hooks page and the 2.0.2 changelog; see

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
@@ -58,7 +58,7 @@ which root file OpenClaude already loads (`AGENTS.md` when present, else
 ## Not supported
 
 - **Workflows.** OpenClaude ships its `WorkflowTool` disabled, so the `workflow`
-  skill falls back to parallel agents, as on Bob and Copilot.
+  skill falls back to parallel agents, as on Bob.
 - **Live verification.** The emit follows OpenClaude's source (`src/utils/envUtils.ts`,
   `src/utils/claudemd.ts`, `src/utils/config.ts`, `src/types/hooks.ts`) as of
   2026-09. It has not been run against an installed OpenClaude yet.

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)