geneseed 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -8,6 +8,63 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [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-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/)
@@ -41,7 +41,7 @@ A hand-written instructions file is prose the model may or may not honour, copie
 - **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,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.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` |

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/bin/build-driver.mjs

@@ -4,6 +4,8 @@
  * which the CLI verbs import too; this file only hands it argv. Keeping the entry this thin is
  * what lets a `js/` module import the driver without running it on the importer's argv.
  */
+// FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
+import '../js/lib/node-floor.mjs';
 import { main } from '../js/build/driver.mjs';
 
 process.exitCode = main(process.argv.slice(2));

package/bin/geneseed-cli.mjs

@@ -54,6 +54,8 @@
 // table below now holds one LOADER per row (`() => import(…).then(m => m.cmdX)`), so a verb
 // loads its slice of the tree and no other verb's. The spawn allow-list gate still sees the
 // whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
+// FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
+import '../js/lib/node-floor.mjs';
 import { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
 import { parseIntStrict } from '../js/lib/text.mjs';
 import { printErr } from '../js/lib/fs.mjs';
@@ -289,6 +291,21 @@ async function main(argv) {
       validate: "check the source tree without emitting (the generator's --validate-only)",
     });
   }
+  // A DEAD HOOK SHIM, SAID ON EVERY RUN. The shim is machine-wide, so one stale write turns off
+  // every hook of every Claude-shaped install, and the hooks fail into a channel nobody reads —
+  // `doctor` was the only thing that looked. stderr, so no verb's stdout moves; skipped for help
+  // and for scripted callers that opt out. Not in `bin/geneseed-hook.mjs`: a dead shim means
+  // that binary is never reached, and its import graph is paid on every tool call.
+  if (process.env.GENESEED_NO_SHIM_CHECK !== '1' && verb !== 'help'
+    && !argv.some((t) => t === '-h' || t === '--help')) {
+    const { shimDead } = await import('../js/hosts/settings.mjs');
+    const dead = shimDead();
+    if (dead.length) {
+      printErr(`[geneseed] ⚠ hooks are off on this machine: the hook shim points at `
+        + `${dead.join(', ')}, which no longer exists. Fix: geneseed rebuild-all
+`);
+    }
+  }
   // `validate` — the generator's `--validate-only`, and the one verb this entry answers that is NOT
   // in the table above. It is dispatched here, before the lookup, for a reason that is a
   // property of the gates rather than a preference:

package/bin/geneseed-hook.mjs

@@ -37,6 +37,8 @@
  * every Geneseed hook returns 0 and signals through stdout — so "did nothing" and "worked"
  * are the same observation.
  */
+// FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
+import '../js/lib/node-floor.mjs';
 import { cmdContext, cmdGitGate, cmdRuleGate, cmdToolGate, cmdLearn } from '../js/hosts/hooks.mjs';
 // Not a new module on the hot path: `js/hosts/hooks.mjs` above already imports
 // `js/lib/fs.mjs`, so this edge names a file the process has already loaded.

package/docs/README.md

@@ -0,0 +1,42 @@
+# Geneseed documentation
+
+[← Back to README](../README.md)
+
+**New to agent harnesses?** Read **Understand** first — four short pages, about ten minutes, and every other page assumes them. The same pages open the **Docs** tab of the web console (`geneseed web`), which adds an interactive map of your own install and filters host-specific passages to the tool you use.
+
+## 1 · Understand
+
+1. **[What a harness is](understand/harness.md)** — git hooks + CI + a runbook, but for your AI agent.
+2. **[What lands on your machine](understand/on-your-machine.md)** — every file and hook an install writes, what it does for you, what it costs, how to turn it off.
+3. **[A day with the harness](understand/a-day.md)** — the moments you will actually meet: a push that asks first, a skill, a delegation, a memory.
+4. **[Enforced vs. asked](understand/enforced-vs-asked.md)** — what is guaranteed by code, and what the model is only asked to do.
+
+## 2 · Guides
+
+| Guide | When |
+| --- | --- |
+| [Install](guides/install.md) | First time — npx, a clone, or a specific host |
+| [Choose your setup](guides/choose-your-setup.md) | Theme, doctrine packs, one rule at a time, footprint, posture, mode |
+| [Verify it works](guides/verify.md) | Right after installing, or when something feels off |
+| [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
+| [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
+| [Project context](guides/project-context.md) | Choosing which of a repo's docs the agent loads |
+| [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
+| [MCP servers](guides/mcp.md) | MarkItDown, GitLab, Filesystem — and reading non-markdown docs |
+| [Run geneseed from anywhere](guides/run-anywhere.md) | Putting the CLI on your PATH from a clone |
+| [Start the web console at login](guides/autostart.md) | Keeping the console running |
+| [Run in CI / headless](guides/headless.md) | OpenCode without a terminal |
+| [Add git-worktree isolation](guides/worktree.md) | OpenCode, optional third-party add-on |
+| [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
+
+## 3 · Concepts
+
+[Hosts](concepts/hosts.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md) · [Footprint](concepts/footprint.md) · [Collaboration](concepts/collaboration.md) · [Foreman mode](concepts/foreman-mode.md) · [Exclusions](concepts/exclusions.md) · [Themes](concepts/themes.md) · [Code intelligence (LSP)](concepts/lsp.md)
+
+## 4 · Reference
+
+[CLI](reference/cli.md) · [Environment variables](reference/environment.md) · [Glossary](reference/glossary.md) · [Troubleshooting](reference/troubleshooting.md) (by symptom) · [OpenCode plugins](reference/opencode-plugins.md) · [About](reference/about.md)
+
+## For contributors
+
+[Extending Geneseed](extending.md) — what each kind of addition costs · [DESIGN.md](../DESIGN.md) · [Design history](design-history.md) · [Token footprint](token-footprint.md) · [Web console internals](web-ui.md) · [OpenCode plugin wiring](opencode-plugin-setup.md) · [Candidate hosts](candidate-hosts.md) · adapters: [OpenCode](../adapters/opencode/README.md), [Claude Code](../adapters/claude-code/README.md), [Bob](../adapters/bob/README.md), [OpenClaude](../adapters/openclaude/README.md)

package/docs/_groups.json

@@ -0,0 +1,18 @@
+[
+  {
+    "id": "understand",
+    "label": "Understand"
+  },
+  {
+    "id": "guides",
+    "label": "Guides"
+  },
+  {
+    "id": "concepts",
+    "label": "Concepts"
+  },
+  {
+    "id": "reference",
+    "label": "Reference"
+  }
+]

package/docs/concepts/agents.md

@@ -0,0 +1,44 @@
+---
+group: concepts
+order: 3
+title: "Agents"
+kind: "concept"
+link: {"hash": "#/section/agents", "label": "Browse the catalog →"}
+---
+An **agent** is a specialist the main session can hand a piece of work to. Each one is a markdown file with its own instructions, installed where your host looks for subagents (`agents/` in the install). It runs in its own context and returns a result, so its reading and searching does not fill your conversation.
+
+> **You already know this:** handing a ticket to a colleague. You do not explain how to review code to the reviewer — you say what to review, and they come back with findings.
+
+{N_AGENTS} agents ship, in two groups.
+
+### The specialists
+
+| Agent | What it does |
+| --- | --- |
+| `explorer` | reads and searches widely in a throwaway context, returns only distilled findings |
+| `researcher` | searches the open web, cross-checks every claim against two sources, returns sourced findings |
+| `architect` | produces a design or implementation plan before code is written |
+| `developer` | implements a scoped change in an isolated worktree, self-checked, ready for the tester |
+| `tester` | writes, runs and diagnoses tests |
+| `reviewer` | reviews a change for correctness and quality before it merges |
+| `security` | audits changes that touch the security surface |
+| `docs` | writes and updates user-facing documentation after code lands |
+
+### The council
+
+Ten read-only debaters — `advocate`, `skeptic`, `pragmatist`, `steward`, `operator`, `visionary`, `framer`, `empiricist`, `historian`, `user-advocate` — each arguing one fixed stance. You do not call them one by one: the **council** [skill](skills.md) seats the ones that actually disagree on your question, runs bounded rounds of debate, and hands you a verdict with the strongest dissent kept verbatim. The council advises; it writes no code.
+
+### Specialists, not folder owners
+
+An agent is picked by **what the work needs**, not by **where the file lives**. There is no "agent for `src/api/`": a change to any folder goes to the `developer`, and its review to the `reviewer`. You can name one ("have the reviewer look at this"), or let the main session route the request to the right specialist itself.
+
+In [foreman mode](foreman-mode.md) the session chains several of them into a pipeline — explorer, developer and tester, plus whatever specialists the task needs.
+
+### Agents learn too
+
+When a subagent finishes, the learn step can record a lesson for that agent alone, in `memory/agents/<name>.md` — one bullet per lesson, capped so it never grows unbounded. The next time that agent runs, it starts with what it learned. See [Memory](memory.md). (Not on Bob, which has no subagent-finished event.)
+
+<!--harness:opencode-->
+*(OpenCode only)*
+OpenCode also has a **primary agent** — the one your session talks to directly. Geneseed installs it alongside the specialists; the specialists are subagents it delegates to.
+<!--/harness-->