geneseed 3.10.0 → 3.12.0

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';
@@ -147,6 +149,10 @@ const VERBS = {
   catalog: () => import('../js/build/catalog.mjs').then((m) => m.cmdCatalog),
   mcp: () => import('../js/hosts/mcp.mjs').then((m) => m.cmdMcp),
   memory: () => import('../js/maintain/memory.mjs').then((m) => m.cmdMemory),
+  // Task 5. A fourth native verb: there was never a Python subparser for a state machine that
+  // lives entirely inside this port, so — like the three above — it has no recorded cell to
+  // compare against, only the absolute gates named beside it in `NATIVE`.
+  loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
 };
 
 function die(code, msg) {
@@ -289,6 +295,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-->

package/docs/concepts/collaboration.md

@@ -0,0 +1,62 @@
+---
+group: concepts
+order: 9
+title: "Collaboration"
+kind: "concept"
+---
+Beside the [rules](rules.md), a few pieces shape *how* the agent works with you: the register it speaks in, the contract between you, how firmly a memory binds, and who you are. All of them are plain text in the install, so they reach every host unchanged.
+
+> **You already know this:** a team's working agreement. The coding standards say what the code must look like; the working agreement says how people treat each other's reviews, questions and decisions.
+
+### Posture — the relationship
+
+A **posture** is the register the agent works in. You choose it at setup and it is fixed at build time, so it does not drift back toward plain execution halfway through a session.
+
+| Posture | For |
+| --- | --- |
+| **peer** (default) | a candid equal — dense, challenges you, no flattery |
+| **mentor** | leaves you more capable — explains the why, checks understanding |
+| **expert** | maximum density for a fluent user — terse, no basics |
+| **assistant** | precise execution, low initiative — you steer |
+| **artisan** | a peer with toolsmith reflexes — terminal-first, automates repetition |
+
+Posture is separate from the [theme](themes.md): the theme is the *voice*, the posture is the *relationship*. Every posture obeys the same rules; what shifts is how firmly and how loudly the agent voices disagreement. Change it with `geneseed setup`, the web console's Harness page, or:
+
+```bash
+geneseed build --emit claude-global --posture mentor
+```
+
+How the agent *executes* work — itself, or through a crew — is the separate **mode** setting: see [Foreman mode](foreman-mode.md).
+
+### The Pact — a two-way contract
+
+The **Pact** is stated in the first section of the Ethos, the layer that is always on, so it holds in every task and every repository. It ranks three duties for the agent, each yielding only to the one above:
+
+1. protect you — and the future maintainer of your code;
+2. serve your intent;
+3. keep its own honesty.
+
+Unusually, it also says what *you* owe back:
+
+- **Don't punish candour.** When the agent contradicts you with evidence, flags a risk or admits a doubt, that is the Pact working. Penalising it teaches the agent to flatter.
+- **Give the context up front.** The agent cannot weigh what it was not told.
+- **Decide when shown a fork.** An unmade decision stalls work as surely as a wrong one.
+
+Your half is not enforced against you. The agent's half binds it.
+
+### Memory force — how firmly a memory binds
+
+A [memory](memory.md) can carry an optional `force`:
+
+| Force | Meaning |
+| --- | --- |
+| **constraint** | imposed; not the agent's to relax |
+| **choice** | revisable, with your consent |
+| **conviction** | revisable on evidence |
+| **tempered** | a constraint that was relaxed |
+
+When new evidence contradicts a memory with a force, the agent must revise it in the open rather than quietly drop it.
+
+### Profile — who you are
+
+`PROFILE.md` sits beside the instructions file, is seeded once and is never overwritten. It holds your role, habits and how you like answers pitched. It colours how the agent works but never binds — it is last in [precedence](rules.md). Edit the file directly, use the Profile tab in the web console, or let the `profile` [skill](skills.md) interview you and draft it; it writes only with your consent, and routes anything that is really a standing rule to `user-rules.md`.

package/docs/concepts/exclusions.md

@@ -0,0 +1,55 @@
+---
+group: concepts
+order: 11
+title: "Exclusions"
+kind: "concept"
+link: {"hash": "#/harness", "label": "Manage in Harness →"}
+---
+Geneseed has two different ways to switch something off, and they work at different scales:
+
+| | Sovereign repo | Per-rule exclusion |
+| --- | --- | --- |
+| **Switches off** | the whole global install, inside one folder | one doctrine rule, everywhere the install applies |
+| **Scope** | a folder and everything under it | the install |
+| **Applies to** | **global** installs only | any install |
+| **Set with** | `geneseed exclude add <path>` | `--exclude-rules` at build time |
+| **Takes effect** | on the next tool call, no rebuild | on rebuild |
+
+> **You already know this:** `.gitignore` versus disabling one lint rule. One makes a tool ignore a whole folder; the other keeps the tool running everywhere with one check turned off.
+
+### Sovereign repos — whole-repo dormancy
+
+A **sovereign repo** is a folder where every *global* Geneseed install goes fully dormant. The usual case is a repo that ships its own complete agent setup — its own rules, hooks and memory — where a global harness layered on top would bring conflicting instructions and wasted tokens.
+
+It is all-or-nothing. It does not trim which rules apply or which skills load; the global harness simply never engages inside that folder. A **per-repo** Geneseed install in the same folder is unaffected — exclusions only ever silence global installs.
+
+```bash
+geneseed exclude add ~/code/my-vault
+geneseed exclude list
+geneseed exclude remove ~/code/my-vault
+```
+
+One command updates every global install on the machine. Each keeps the list in its own `excludes.json`, and every hook and plugin reads it on each call, so a change takes effect at once.
+
+What "dormant" means per host:
+
+- **Claude Code** — every hook exits silently, and the global `CLAUDE.md` is suppressed natively through `claudeMdExcludes` in the repo's `.claude/settings.local.json`.
+- **OpenClaude** — the same, in the repo's `.openclaude/settings.local.json`.
+- **Bob** — every hook exits silently, and a stub `.bob/rules/geneseed.md` in the repo shadows the global rules file. A hand-written stub already there is never overwritten.
+- **OpenCode** — Geneseed's plugins stand down.
+
+`geneseed exclude remove` undoes all of it.
+
+**Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions starts with an empty list: run `geneseed exclude add` again (`geneseed exclude list` flags installs whose lists differ).
+
+The web console has the same controls in the **Excluded folders** card on the Harness page, shown once a global install exists.
+
+### Per-rule exclusion — one rule off
+
+The finer switch removes a single doctrine rule from an install while keeping the rest of its pack:
+
+```bash
+geneseed build --emit claude-global --exclude-rules "process 7"
+```
+
+The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Choose your setup](../guides/choose-your-setup.md); what the layers are is in [Rules](rules.md).

package/docs/concepts/footprint.md

@@ -0,0 +1,52 @@
+---
+group: concepts
+order: 8
+title: "Footprint (lean vs full)"
+kind: "concept"
+link: {"hash": "#/settings", "label": "Toggle it in Settings →"}
+---
+**Footprint** decides how much of the [constitution](rules.md) the agent carries *inline* in its instructions file on every turn. It has two settings, **lean** (the default) and **full**, chosen per install. It is a token-cost dial, not a rules dial: every rule the install adopted is in force at either setting.
+
+> **You already know this:** eager versus lazy loading. Full ships everything in the first payload; lean ships the index and fetches the rest when it is needed.
+
+### The difference
+
+- **Full** — the instructions file carries the Ethos, every Rule and every rule of the active doctrine packs at complete length, reasoning included, every turn.
+- **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). Each layer ends with a pointer to its complete text on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules.
+
+Neither setting hides text from the agent. They decide what is in front of it on *every* turn.
+
+### What is on disk either way
+
+- **Lean** writes the full `laws/`, `ontology/` and `doctrines/` text beside the instructions file, because the inline copy is shorter than what the agent may need.
+- **Full** writes `doctrines/` too: it inlines only the packs this install built in, so the others must be on disk for a citation into them to resolve, and for you to read before turning one on.
+
+Everything else is identical at both settings — the same agents, skills, plugins or hooks, commands, memory and notebook.
+
+### Which to choose
+
+- **Lean** (default) for long sessions, large repos or cost-sensitive work. It is safe: the full text ships, and the instructions tell the agent to read it before acting on secrets, deletion, git history, scope or untrusted content.
+- **Full** when token cost does not matter, or with a smaller or cheaper model — with the reasoning always in context, a model applies a rule's edge cases more reliably.
+
+For measured numbers per host, see [docs/token-footprint.md](../token-footprint.md).
+
+### How to set it
+
+Footprint is stored in a `.geneseed-footprint` marker in the install and kept across every rebuild and upgrade, on every host.
+
+- **Setup wizard** — asks for it alongside voice, posture, mode and doctrine packs:
+
+  ```bash
+  geneseed setup
+  ```
+
+- **Web console** — the **Footprint** toggle in Settings flips the current install and rebuilds it; on the Harness page, each install has its own dropdown.
+- **Command line** — with the emit target of the install you are changing:
+
+  ```bash
+  geneseed build --emit claude-global --footprint full
+  ```
+
+  On the command line, a flag you leave out takes the generator's default, not the install's current value. `geneseed status --json` shows what an install currently has.
+
+The walkthrough for all build-time choices is [Choose your setup](../guides/choose-your-setup.md).

package/docs/concepts/foreman-mode.md

@@ -0,0 +1,69 @@
+---
+group: concepts
+order: 10
+title: "Foreman mode"
+kind: "concept"
+link: {"hash": "#/harness", "label": "Set the mode in Harness →"}
+---
+**Mode** decides how work gets executed in a session. Two modes ship: **direct**, the default, where the agent does every task itself, and **foreman**, where the session hands substantial tasks to a crew of [agents](agents.md) and keeps talking to you while they work.
+
+> **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
+
+Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a pipeline is a one-shot, uncommitted crew for a single task; a loop is a long-running state machine that commits each validated iteration on its own branch.
+
+### direct — the default
+
+The agent works every task itself, turn by turn. Nothing is spawned; you talk to one agent from start to finish. Keep it unless you want the session to manage work for you.
+
+### foreman — a session that triages
+
+The session sorts every request:
+
+- **Trivial** — a quick answer, a one-file tweak, a question: done directly, as in direct mode.
+- **Substantial** — handed to a **pipeline** running in the background. The session tells you it is running and stays free to answer you.
+
+Expect a substantial task to cost more (a crew runs instead of one agent) in exchange for a session that never blocks on a long job.
+
+### What a pipeline is
+
+A **pipeline** is a small crew of agents working one task in isolation. The minimum crew depends on the task:
+
+| Task | Minimum crew |
+| --- | --- |
+| development | `explorer` (analyses the request) → `developer` → `tester`, plus a lint check |
+| documentation | `explorer` → `docs` |
+| research | `explorer`; add `researcher` when the question leaves the repository |
+| review or audit | `reviewer` + `skeptic` |
+
+The session adds specialists on top when the task needs them — `security`, `architect`, `reviewer` and so on — never fewer than the minimum.
+
+The crew works in its own git worktree and branch. When worktrees are unavailable it falls back to the main tree, one pipeline at a time, and says so. Two pipelines whose sets of files overlap do not run at once.
+
+Inside the crew, the developer implements and the tester runs the tests and lint. Failures go back to the developer, at most five rounds; after that the crew stops and reports the failure, leaving the branch for you to inspect.
+
+### A pipeline never commits or merges
+
+When the crew is done, it hands back its worktree **uncommitted**, with the raw test and lint output and the list of files it changed. Then the session:
+
+1. re-runs the tests and lint itself — the crew's log is the crew's account, not proof;
+2. shows you the diff and the green output;
+3. commits and merges **only once you accept**.
+
+Commit, push and merge belong to the session alone, under *Consent Before Push* ([Rules](rules.md)). A crew that cannot get to green reports back instead of landing broken work.
+
+You can also start a pipeline without foreman mode: ask the agent to "run a pipeline" for a task, and the `pipeline` [skill](skills.md) takes it from there.
+
+### How to set it
+
+- **Setup wizard** — asks for mode alongside voice, posture, doctrine packs and footprint:
+
+  ```bash
+  geneseed setup
+  ```
+
+- **Web console** — the per-install **Mode** dropdown on the Harness page, then **Apply**.
+- **Command line** — with the emit target of the install you are changing; switch back with `--mode direct`:
+
+  ```bash
+  geneseed build --emit claude-global --mode foreman
+  ```

package/docs/concepts/hooks.md

@@ -0,0 +1,101 @@
+---
+group: concepts
+order: 5
+title: "Hooks (Claude Code, Bob, OpenClaude)"
+kind: "concept"
+---
+A **hook** is a command your host runs at a fixed moment — when a session starts, before a tool call, when the agent finishes. On Claude Code, Bob and OpenClaude, hooks are how Geneseed does anything *in code* rather than in prose: load your project's docs, stop a risky command for your confirmation, save what was learned.
+
+> **You already know this:** git hooks. A `pre-commit` hook runs before every commit whether or not you remember it exists, and can stop the commit. These run before and after the agent's actions the same way.
+
+Geneseed writes its hooks into the host's settings file. Every hook calls one program, `geneseed-hook`, with a verb — not the `geneseed` CLI you type yourself. The instructions file (`CLAUDE.md`) needs no hook: the host loads it by location.
+
+### The hooks on Claude Code
+
+| Event | When | Command | What it does | Conditional? |
+| --- | --- | --- | --- | --- |
+| `SessionStart` | `startup`, `clear` | `geneseed-hook context` | injects your harness files and the repo's docs | no |
+| `SessionStart` | `resume`, `compact` | `geneseed-hook context` | re-injects them after a resume or an auto-compaction summarised them away | no |
+| `PreToolUse` | `Bash` | `geneseed-hook git-gate` | asks before destructive git; asks before every commit and push | the commit/push question only |
+| `PreToolUse` | `Write`, `Edit`, `MultiEdit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your rules or memory | no |
+| `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into `memory/` | needs `GENESEED_LLM` |
+| `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in `memory/agents/<name>.md` | needs `GENESEED_LLM` |
+| `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
+
+### What each one does, and what you see
+
+**context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`. Each file is capped at 16 KB and the whole injection at 48 KB; what does not fit is listed for the agent to read on demand. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
+
+**git-gate.** Runs before every shell command and looks for `git` in it, including chained one-liners and `git -C <path>` forms.
+- **Destructive git** — `reset --hard`, `clean -f`, `branch -D`, `checkout -- `, a `push --force` — always gets a confirmation prompt, citing *Deletion Is Deliberate*. That is a Rule, so it holds in every build.
+- **Every `git commit` and `git push`** gets a prompt citing *Consent Before Push*. This part belongs to the **process** doctrine pack: build without it, or exclude that rule, and the hook stays wired with `--no-consent` — commits and pushes go through without asking, destructive git is still stopped ([Rules](rules.md)).
+- Any other command passes untouched.
+
+**rule-gate.** Runs before every file write.
+- Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*.
+- A write to `user-rules.md`, `MEMORY.md` or a file in the install's `memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
+- Ordinary edits pass untouched.
+
+**learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`, skipping duplicates. It needs `GENESEED_LLM` set to a model command, for example:
+
+```bash
+export GENESEED_LLM="claude -p"
+```
+
+Unset, `learn` does nothing useful — it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
+
+### Gates fail closed, and leave a trace
+
+If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the time, never the command or content. `geneseed status` counts them by rule.
+
+```bash
+geneseed status
+```
+
+In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context` hook stands down when the repo has its own per-repo install of the same host, so nothing is injected twice.
+
+### Where they are written
+
+| Host | Global | Per repo |
+| --- | --- | --- |
+| Claude Code | `~/.claude/settings.json` | `.claude/settings.local.json` |
+| OpenClaude | `~/.openclaude/settings.json` | `.openclaude/settings.local.json` |
+| Bob | `~/.bob/settings/settings.json` | `.bob/settings.json` |
+
+Per repo, Claude Code and OpenClaude hooks go into the **local**, untracked settings file: the hook commands contain paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks.
+
+The merge is surgical. Every other key and every hook of your own survive, and the install manifest records exactly which hook groups are Geneseed's, so an upgrade replaces and an uninstall removes only those.
+
+### Bob and OpenClaude
+
+**OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
+
+**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
+
+- `SessionStart` → `geneseed-hook context`.
+- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the two Rules, secrets and destructive git. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
+- `Stop` → `geneseed-hook learn`.
+
+Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
+
+### The hook shim
+
+Hooks run with your project as the working directory, so each command needs an absolute path. Rather than write the Node path and the Geneseed checkout path into every settings file, every hook points at one stable file, the **hook shim**: `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim holds those two paths; your settings hold none. Set `GENESEED_HOME` to keep it somewhere other than `~/.geneseed`.
+
+Every build rewrites the shim, so moving the checkout and running one build repairs every install at once.
+
+**A stale shim fails silently.** Hooks report through their output and exit 0 on every path — that is what keeps a broken hook from breaking your tool calls. The flip side: if the shim points at a checkout that no longer exists, every hook on the machine stops working and nothing tells you. The agent simply stops getting project context and the gates stop asking. `geneseed doctor` checks the shim; a build repairs it.
+
+```bash
+geneseed doctor
+```
+
+See [Troubleshooting](../reference/troubleshooting.md).
+
+### Cost
+
+The hook program is small on purpose: it adds about 14 ms to each tool call.
+
+### Verify
+
+Open a session in a repo and ask the agent what it knows about the project — it should answer from the repo's docs without reading them first. Ask it to commit something: you should get a prompt before the commit runs.

package/docs/concepts/hosts.md

@@ -0,0 +1,55 @@
+---
+group: concepts
+order: 1
+title: "Hosts"
+kind: "concept"
+---
+A **host** is the AI coding tool Geneseed installs into — OpenCode, Claude Code, Bob or OpenClaude. Geneseed does not run the model; the host does. Geneseed writes the files the host reads (the instructions file, agents, skills) and, where the host allows it, wires small programs that run around the agent's actions. The *content* is the same on every host. What differs is how much of it the host lets Geneseed **automate** — check in code before an action — rather than only **ask** of the model in prose.
+
+> **You already know this:** one codebase, several CI providers. The pipeline does the same job everywhere, but each provider exposes different hooks, so some checks run natively on one and are a manual step on another.
+
+### What is the same everywhere
+
+One build renders the same text for every host: the constitution ([rules](rules.md)), the {N_AGENTS} [agents](agents.md), the {N_SKILLS} [skills](skills.md), the [memory](memory.md) and [notebook](notebook.md) conventions, and the theme's voice. No host drops an agent, a skill or the memory convention.
+
+Each host has a **global** install (in its config directory, active in every repo) and a **per-repo** install (inside one project). There is also a portable `files` bundle — a plain `Harness/` folder with an `AGENT.md` that any tool reading an instructions file can use, with no automation at all.
+
+### Two engines
+
+- **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
+- **Claude Code**, **Bob** and **OpenClaude** share one Claude-shaped engine: Geneseed wires **hooks** into the host's `settings.json`, each calling `geneseed-hook <verb>`. See [Hooks](hooks.md).
+
+### What each host automates
+
+| Capability | OpenCode | Claude Code | Bob | OpenClaude |
+| --- | :---: | :---: | :---: | :---: |
+| Instructions file | `AGENT.md` via `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (`.openclaude/` per repo) |
+| Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
+| Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
+| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
+| Destructive git (force-push, `reset --hard`…) | 🔒 permission ask | 🪝 ask | 🪝 block¹ | 🪝 ask² |
+| Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
+| Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
+| Rule-or-memory write needs your call | ⚙️ speed bump³ | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
+| Sovereign-repo exclusions | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
+| MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
+| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
+
+✅ native · ⚙️ OpenCode plugin · 🔒 `permission.bash` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
+
+¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the two always-on rules (secrets, destructive git) and turns the two consent checks into a logged warning. It has no `SubagentStop` or `PreCompact` event, so learn runs on `Stop` only. **Unverified live** — there is no Bob install on the authoring machine; the rules preamble still holds if a hook does not fire.
+² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
+³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so this check stops the first such write once rather than prompting.
+⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
+
+### The one conditional row
+
+The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. Everything else in the table is always on.
+
+One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it.
+
+### Where to go next
+
+- What exactly each host writes to disk: [What lands on your machine](../understand/on-your-machine.md).
+- Code-enforced versus asked-of-the-model, in plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).
+- Per-host detail for maintainers: [OpenCode](../../adapters/opencode/README.md) · [Claude Code](../../adapters/claude-code/README.md) · [Bob](../../adapters/bob/README.md) · [OpenClaude](../../adapters/openclaude/README.md).