geneseed 3.9.0 → 3.11.0

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

@@ -56,6 +56,7 @@ import { promises as fs } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath } from "node:url"
 import { homedir } from "node:os"
+import { createHash } from "node:crypto"
 
 const MARKER = "<!-- geneseed-context:v2 -->"
 const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url))
@@ -156,6 +157,49 @@ const EXCLUDE_DIRS = new Set([
 async function isFile(p) { try { return (await fs.stat(p)).isFile() } catch { return false } }
 async function isDir(p) { try { return (await fs.stat(p)).isDirectory() } catch { return false } }
 
+// ---- session files (the harness's own) --------------------------------------
+// The files AGENT.md names for session start, relative to the HARNESS dir — the dir that
+// holds the installed AGENT.md: the repo root for a project install, the config dir for a
+// global one. Same list and seed hashes as SESSION_FILES/SEED_SHA256 in js/hosts/hooks.mjs;
+// tests/unit/claude.test.mjs gates both copies against SESSION_SEEDS in js/build/stubs.mjs.
+// context.json is not here: it is a manifest, honoured by resolveSource. wiki.jsonc is not
+// here either: the MACHINE WIKI block below already renders it in full.
+const SESSION_FILES = ["user-rules.md", "PROFILE.md", "memory/MEMORY.md", "anamnesis/MEMORY.md",
+  "notebook/NOTEBOOK.md"]
+const SEED_SHA256 = new Set([
+  "5c2e92fb1acde041e02d9ebf158460d8ff7a07cbc2b447859631604610130721", // user-rules.md
+  "29e012c3c4349ea62a9082cbd04bb25599a0ec280d62c33f6e10742809471816", // PROFILE.md
+  "cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8", // wiki.jsonc
+  "99c786049c260f6baf7aec68a5c0f59907861afe9b867da009440613bdddb907", // MEMORY.md
+  "9acb5c9d9cb5dac572104480f05b48cc144e676869bd60e86d8a15b1f6308184", // NOTEBOOK.md
+])
+
+// $GENESEED_HARNESS when set, else the first of <plugin dir>/.. (global: the config dir) and
+// <plugin dir>/../.. (project: .opencode/plugins -> the repo root) that holds AGENT.md.
+async function harnessDir() {
+  if (process.env.GENESEED_HARNESS && (await isDir(process.env.GENESEED_HARNESS))) {
+    return process.env.GENESEED_HARNESS
+  }
+  for (const d of [path.resolve(PLUGIN_DIR, ".."), path.resolve(PLUGIN_DIR, "..", "..")]) {
+    if (await isFile(path.join(d, "AGENT.md"))) return d
+  }
+  return null
+}
+
+// Session files present under the harness dir and changed from their seed: [{ rel, abs, text }].
+async function sessionFiles(dir) {
+  const found = []
+  if (!dir) return found
+  for (const rel of SESSION_FILES) {
+    const abs = path.join(dir, rel)
+    let text
+    try { text = (await fs.readFile(abs, "utf8")).replace(/\r\n/g, "\n") } catch { continue }
+    if (SEED_SHA256.has(createHash("sha256").update(text).digest("hex"))) continue
+    found.push({ rel, abs, text: text.replace(/\n+$/, "") })
+  }
+  return found
+}
+
 async function readJson(p) {
   try { return JSON.parse(await fs.readFile(p, "utf8")) } catch { return null }
 }
@@ -474,11 +518,13 @@ async function fromManifest(manifestFile, root) {
   return { eager: eager.sort(byRel), lazy: lazy.sort(byRel) }
 }
 
-async function resolveSource(root) {
+async function resolveSource(root, harness = null) {
   const explicit = process.env.GENESEED_CONTEXT
   if (explicit && (await isFile(explicit))) return { mode: "manifest", file: explicit }
-  for (const rel of [path.join(".harness", "context.json"), "context.json"]) {
-    const p = path.join(root, rel)
+  // The harness dir last: a repo's own manifest outranks the one seeded beside the install.
+  const cands = [path.join(root, ".harness", "context.json"), path.join(root, "context.json")]
+  if (harness) cands.push(path.join(harness, "context.json"))
+  for (const p of cands) {
     if (await isFile(p)) return { mode: "manifest", file: p }
   }
   return { mode: "discover" }
@@ -494,8 +540,12 @@ async function resolveSource(root) {
 async function resolveWikiFile() {
   const explicit = process.env.GENESEED_WIKI
   if (explicit && (await isFile(explicit))) return explicit
+  // The harness dir (which honours $GENESEED_HARNESS) first: on a PROJECT install the plugin
+  // sits in .opencode/plugins, so <plugin dir>/.. is .opencode, not the dir the seed landed in.
+  // <plugin dir>/.. stays as the fallback for an install without an AGENT.md.
   const bases = []
-  if (process.env.GENESEED_HARNESS) bases.push(process.env.GENESEED_HARNESS)
+  const harness = await harnessDir()
+  if (harness) bases.push(harness)
   bases.push(path.resolve(PLUGIN_DIR, ".."))
   for (const base of bases) {
     // wiki.json is the legacy name from earlier seeds — still honoured.
@@ -652,9 +702,27 @@ async function renderSet(out, { eager, lazy }, state) {
   state.lazy += lazyLines.length
 }
 
-async function buildBlock(sets, wikis = [], commands = []) {
+async function buildBlock(sets, wikis = [], commands = [], session = []) {
   const state = { spent: 0, injected: 0, lazy: 0, headingsRead: 0 }
 
+  // A session file discovery also found (user-rules.md at the root of a project install,
+  // whose harness dir IS the repo root) is injected once, in the session block.
+  const seen = new Set(session.map((s) => path.resolve(s.abs)))
+  const fresh = (x) => !seen.has(path.resolve(x.abs))
+  sets = { eager: sets.eager.filter(fresh), lazy: sets.lazy.filter(fresh) }
+  const ses = []
+  for (const s of session) {
+    const size = Buffer.byteLength(s.text, "utf8")
+    ses.push(`----- ${s.rel} -----`)
+    if (size > EAGER_FILE_KB * 1024) {
+      ses.push(`[demoted: ${s.rel} exceeded ${EAGER_FILE_KB} KB — read ${s.abs} on demand]`, "")
+      continue
+    }
+    ses.push(s.text, "")
+    state.spent += size
+    state.injected++
+  }
+
   const proj = []
   await renderSet(proj, sets, state)
 
@@ -675,8 +743,9 @@ async function buildBlock(sets, wikis = [], commands = []) {
     if (w.truncated) wik.push(`  [+${w.truncated} more notes in this wiki — explore its folders on demand]`, "")
   }
 
-  if (!proj.length && !wik.length) return null
+  if (!ses.length && !proj.length && !wik.length) return null
   const out = [MARKER]
+  if (ses.length) out.push("=== SESSION FILES — your harness files, injected at session start (untouched seeds skipped) ===", "", ...ses)
   if (proj.length) out.push("=== PROJECT CONTEXT — binding for this repo ===", "", ...proj)
   if (wik.length) out.push("=== MACHINE WIKI — the user's knowledge base, binding per AGENT.md §8 ===", "", ...wik)
   return { text: out.join("\n"), injected: state.injected, lazy: state.lazy, kb: kb(state.spent) }
@@ -686,13 +755,14 @@ async function buildBlock(sets, wikis = [], commands = []) {
 // and render the injection block — shared by the session.created injection and the
 // compaction hook (the transform path reuses it via cachedBlockText).
 async function resolveBlock(root) {
-  const src = await resolveSource(root)
+  const harness = await harnessDir()
+  const src = await resolveSource(root, harness)
   const sets = src.mode === "manifest"
     ? await fromManifest(src.file, root)
     : await discover(root)
   const wikis = await wikiSets()
   const commands = await discoverCommands(root)
-  return { block: await buildBlock(sets, wikis, commands), src }
+  return { block: await buildBlock(sets, wikis, commands, await sessionFiles(harness)), src }
 }
 
 // Per-process cache of the rendered block text for the transform path (root is fixed

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * The hook entry point — a Node twin of `rituals/harness.py` for the verbs the emitted
- * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Copilot).
+ * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Bob).
  *
  * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/build-driver.mjs`. Three reasons,
  * and each alone would be enough:
@@ -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/candidate-hosts.md

@@ -38,8 +38,7 @@ current host gets. Skills are the largest surface by file count and they cost no
   Claude's, and `permissionDecision: "ask"` exists. The Claude engine with `host: "codex"`
   covers instructions (`AGENTS.md`), skills (`.agents/skills`) and the hook verbs
   unchanged; the only new code is the carrier writer (a `hooks.json` merge or a TOML
-  table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`). Roughly the Copilot
-  port minus the dialect work.
+  table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`).
 
 - **Gemini CLI — Claude's groups, Gemini's names.** The hook groups are Claude's
   `event → [{matcher, hooks}]` and the payload fields are Claude's, but the events are
@@ -54,7 +53,7 @@ current host gets. Skills are the largest surface by file count and they cost no
 - **Cursor — a third verdict dialect.** `AGENTS.md` and `.agents/skills` are free; hooks
   are `hooks.json` with a `{command}` list per event and a `permission: allow|deny`
   verdict, `additional_context` in snake_case for `sessionStart`. Same block-or-warn stance
-  as Copilot, one more output spelling in `js/hosts/hooks.mjs`, one more carrier writer.
+  as Bob, one more output spelling in `js/hosts/hooks.mjs`, one more carrier writer.
   Cursor also reads `.claude/skills/`, so a Claude project install already gives a Cursor
   user the skills.
 
@@ -64,8 +63,16 @@ If a fifth host is wanted, Codex first: it reuses the most and it is the only ca
 where the gates can *ask* rather than block. Before any of them, a `--emit agents` for
 the shared `.agents/skills/` folder would give Codex, Cursor and Gemini users the whole
 skill catalogue for the price of one directory name, with no host-specific code at all.
-A Gemini host would be the fourth verdict spelling in `js/hosts/hooks.mjs` (after Claude's
-ask, Copilot's block, Bob's exit code 2), plus a resolver and a carrier.
+A Gemini host would be the third verdict spelling in `js/hosts/hooks.mjs` (after Claude's
+ask and Bob's exit code 2), plus a resolver and a carrier.
+
+## Evaluated, dropped
+
+- **GitHub Copilot** — shipped as a host through 3.9.0, removed in 3.10.0. Dropped for lack
+  of support: its hooks were never verified live, its `postToolUse` output does not reach
+  the model, and it shared no cross-tool surface with the other hosts (camelCase payloads,
+  matcherless hook entries, its own agent dialect and carrier), so every feature needed a
+  Copilot-only decision.
 
 ## Not verified
 

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).
+
+### 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
+  ```