geneseed 3.10.0 → 3.11.0

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
+  ```

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).

package/docs/concepts/lsp.md

@@ -0,0 +1,50 @@
+---
+group: concepts
+order: 13
+title: "Code intelligence (LSP, OpenCode)"
+kind: "concept"
+---
+OpenCode can run **language servers** — the same Language Server Protocol servers your editor uses — so the agent sees real diagnostics, type errors and definitions, not just text. Geneseed turns this on for every language OpenCode ships a server for.
+
+> **You already know this:** the red squiggles in your editor. With LSP on, the agent gets the same squiggles before it tells you a change is done.
+
+### What is covered
+
+| Language | Server | You install |
+| --- | --- | --- |
+| JavaScript, TypeScript, React, React Native | typescript-language-server | nothing — OpenCode downloads it |
+| Python | pyright | nothing — OpenCode downloads it |
+| Java | jdtls | a **JDK 21+** (OpenCode downloads jdtls itself) |
+| SQL | none, on purpose | — |
+
+One server covers JavaScript, TypeScript, React and React Native: they are all TS/JS.
+
+### The one prerequisite: Java 21+
+
+OpenCode downloads the servers that run on Node by itself on first use. It cannot install a JVM, and jdtls needs one, so `geneseed setup` checks for Java 21+ and prints an install hint if it is missing. Any JDK 21 works, for example:
+
+```bash
+brew install openjdk@21
+```
+
+```bash
+sdk install java 21-tem
+```
+
+### Why no SQL server
+
+A SQL language server is tied to one dialect — a PostgreSQL server flags Oracle SQL as errors and the other way round — and a `.sql` file can map to only one server, with nothing telling OpenCode which dialect a repo uses. Rather than be wrong for half of all SQL codebases, Geneseed ships none. If your project knows its dialect, add the matching server under the `lsp` key of the project's own `opencode.json`.
+
+### How it is wired
+
+The install adds `"lsp": true` to your `opencode.json` (LSP is off in OpenCode by default). If you already have an `lsp` key, Geneseed leaves yours alone.
+
+On an air-gapped machine, stop the downloads and pre-install each server yourself:
+
+```bash
+export OPENCODE_DISABLE_LSP_DOWNLOAD=true
+```
+
+### Verify
+
+Open a `.ts` and a `.py` file in a session and ask the agent for diagnostics. The first open triggers the download.

package/docs/{web → concepts}/memory.md

@@ -1,7 +1,7 @@
 ---
 group: concepts
-order: 4
-title: "Memory convention"
+order: 6
+title: "Memory"
 kind: "markdown"
 source: "src/memory/README.md"
 ---

package/docs/{web → concepts}/notebook.md

@@ -1,7 +1,7 @@
 ---
 group: concepts
-order: 5
-title: "Notebook (sovereign space)"
+order: 7
+title: "Notebook"
 kind: "markdown"
 source: "src/notebook/README.md"
 ---

package/docs/concepts/rules.md

@@ -0,0 +1,52 @@
+---
+group: concepts
+order: 2
+title: "Rules (the constitution)"
+kind: "concept"
+link: {"hash": "#/laws", "label": "Browse the constitution →"}
+---
+The **constitution** is the set of standing rules the agent carries into every session. It is authored in `src/`, rendered into the instructions file your host reads (`AGENT.md`, `CLAUDE.md` or `AGENTS.md`), and comes in layers that differ in one thing: whether you can turn them off.
+
+> **You already know this:** a lint config. Some rules are set to `error` and nobody may disable them; some come from presets you opt into; and your project's own overrides sit on top of the presets.
+
+### Cited by name, never by number
+
+Every rule has a name — *Deletion Is Deliberate*, *Consent Before Push* — and the agent, the docs and the hooks cite it by that name. Rules are also numbered in the rendered text, but a number is only the rule's current position: remove a rule and every number after it shifts. So when you write about a rule, in your own notes or in `user-rules.md`, use its name.
+
+The one place you type a position is the command line: `--exclude-rules "process 5"` means "the fifth rule of the process pack in this checkout". Check the name it carries before you exclude it.
+
+### The layers, in precedence order
+
+When two instructions disagree, the higher one wins.
+
+1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Conduct): what the agent is for, how it weighs evidence, how it decides, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
+2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
+3. **Your `user-rules.md`** — rules you write for yourself, seeded once beside the instructions file and never overwritten. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
+4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
+5. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
+
+### Doctrine packs
+
+{N_PACKS} packs ship, one file each under `src/doctrines/`:
+
+| Pack | What it governs |
+| --- | --- |
+| **craft** | how code is written — reuse first, house conventions, docs in the same change, the smallest diff |
+| **rigor** | how work is proven — idempotence, honest tests, cover and verify, gates that can actually fail |
+| **ops** | how the machine is driven — tool discovery, commands that return, complete teardowns, restart is not reload |
+| **process** | how a session runs — planning, context economy, docs first, bounded loops, consent before every commit and push |
+| **comms** | how answers are presented — stable reference codes on tracked items, a diagram or table only where it earns its place |
+
+All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying {N_DOCTRINE_RULES} rules between them. You choose packs at build time with `--doctrines`, or drop single rules with `--exclude-rules`; the how-to is in [Choose your setup](../guides/choose-your-setup.md).
+
+A pack you leave out **still ships**: every pack file lands under `doctrines/` beside the instructions file whether or not it was built in. A rule that cites an inactive pack still resolves on disk, and you can read the alternatives before turning one on. An inactive pack loses its binding force, not its availability.
+
+**process** is the one pack whose removal changes what the machine does, not only what the agent reads: it holds *Consent Before Push*, which a hook enforces. Without it, commits and pushes are no longer stopped for a question — destructive git still is, because that is a Rule ([Hooks](hooks.md)).
+
+### Themes do not move rules
+
+A [theme](themes.md) renames the nouns — an `imperial` install calls the invariants *Dictates* — but the layers, their order and every rule stay exactly where they are.
+
+### Related
+
+[Footprint](footprint.md) — how much of this text loads every turn · [Exclusions](exclusions.md) — switching rules off per rule versus per repo · [Glossary](../reference/glossary.md)

package/docs/concepts/skills.md

@@ -0,0 +1,49 @@
+---
+group: concepts
+order: 4
+title: "Skills"
+kind: "concept"
+link: {"hash": "#/section/skills", "label": "Browse the catalog →"}
+---
+A **skill** is a repeatable workflow written as a markdown playbook: when it applies, the steps, and what "done" looks like. The agent reads the playbook before acting, so a task it has a skill for is done the same careful way every time instead of improvised.
+
+> **You already know this:** a runbook. Nobody deploys from memory — you open the deploy runbook and follow it. A skill is that runbook, addressed to the agent.
+
+{N_SKILLS} skills ship. Each is authored once under `src/skills/` and installed under `skills/` in the install, where the host looks for skills.
+
+### How a skill gets used
+
+- **By name.** Ask for it — "brainstorm this", "run a council on it" — or, on hosts with slash commands, type `/<name>`.
+- **By trigger.** Every skill has a one-line description of its purpose and when it applies. The host shows those descriptions to the agent every turn, and the agent opens the matching skill when your request fits.
+- **User-only skills.** A few skills are marked to open only when *you* call them (a teaching drill, a tool tied to a setup the agent cannot see). They answer `/<name>` but the agent never starts them on its own, and their description stays out of the always-loaded list.
+
+### A tour
+
+| You want to… | Skill |
+| --- | --- |
+| turn a raw idea into an approved design before any code | `brainstorm` |
+| write a plan to a file before a non-trivial task | `plan` |
+| drive a change through smallest change → tests → green suite | `develop` |
+| find a bug by evidence: reproduce, isolate, root-cause, verify | `debug` |
+| answer a question from the open web, every claim cross-checked | `research` |
+| have several viewpoints debate a decision | `council` |
+| get an adversarial critique of anything | `roast-me` |
+| see what a change does before you agree to commit it | `explain-changes` |
+| stage the right paths and write a focused commit | `commit` |
+| open a pull request, or finish and merge a branch | `ship` |
+| decide whether something is a standing rule or a fact to remember | `rule` |
+| be taught a topic, or quizzed on it | `teach`, `quiz` |
+
+The full list, with each description, is in the catalog.
+
+### Skills improve themselves
+
+Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent proposes the exact edit to that skill and applies it only with your assent. Most runs end with nothing to change.
+
+### What they cost
+
+The skill *bodies* are read only when used. The *descriptions* are listed to the agent every turn so it can pick the right one — that list is part of the always-on cost described in [Footprint](footprint.md).
+
+### Related
+
+[Agents](agents.md) — who does the work · [Rules](rules.md) — what every skill obeys · writing your own: [docs/extending.md](../extending.md)

package/docs/concepts/themes.md

@@ -0,0 +1,50 @@
+---
+group: concepts
+order: 12
+title: "Themes"
+kind: "concept"
+---
+A **theme** changes the agent's *voice* and the words the harness uses for its own parts. It never changes structure: the same rules, in the same order, with the same files, folders and links, whatever theme you pick.
+
+> **You already know this:** an editor colour scheme. It changes how everything looks, never what the code does.
+
+### What changes and what does not
+
+| Changes with the theme | Never changes |
+| --- | --- |
+| how the agent phrases its replies | which rules apply, and their order |
+| the nouns for the harness's parts — an `imperial` install calls the Rules *Dictates*, agents *Adepts*, skills *Rites* | folder names: `agents/`, `skills/`, `memory/`, `laws/`, `doctrines/`… |
+| the banner, the readiness line the agent prints when it starts, the closing lines | section layout and the links between files |
+| the names and descriptions shown for rules, agents and skills | rule addresses such as `process 5` |
+
+`neutral` keeps the plain words — Rule, Doctrine, Agent, Skill, Memory — so it is the theme to pick if you want no flavour at all. The [glossary](../reference/glossary.md) shows each themed word beside its neutral one.
+
+### The themes that ship
+
+14 themes ship: `neutral`, `imperial` (Warhammer 40k), `military`, `pirate`, `wizard`, `cyberpunk`, `gamer`, `sports` (play-by-play), `biker`, `commentator`, `joker`, `marvin`, `mean` and `verstappen`.
+
+### Switching
+
+The theme is stored in a `.geneseed-theme` marker in the install, so upgrades and rebuilds keep it.
+
+- **Setup wizard** — lists every theme with a live preview:
+
+  ```bash
+  geneseed setup
+  ```
+
+- **Web console** — the per-install voice dropdown on the Harness page.
+- **Command line** — with the emit target of the install you are changing:
+
+  ```bash
+  geneseed build --emit claude-global --theme pirate
+  ```
+
+<!--harness:opencode-->
+*(OpenCode only)*
+OpenCode also has *colour* themes for its interface. Those are separate from voice themes; `geneseed theme <name>` creates your own colour theme in OpenCode's themes folder, and it survives rebuilds.
+<!--/harness-->
+
+### Writing your own
+
+A theme is one JSON file of voice tokens in `themes/`. How the tokens split between voice and structure, and how to add one, is in the maintainer design notes: [DESIGN.md](../../DESIGN.md).