geneseed 3.10.0 → 3.12.0

package/docs/guides/choose-your-setup.md

@@ -0,0 +1,134 @@
+---
+group: guides
+order: 2
+title: "Choose your setup"
+kind: "concept"
+---
+The setup wizard asks a handful of questions before it builds. Every one has a safe default, so you can accept them all and move on. This page says what each one changes, so you can pick on purpose, and how to change it later.
+
+All of these choices are made **at build time**. The build writes them into the files your agent loads. Nothing switches at runtime. Rebuilds, re-themes and upgrades keep each install's choices, because they are recorded in small marker files beside the install.
+
+> **You already know this:** these are compiler flags. You set them once, the output is built from them, and changing one means rebuilding rather than editing the output by hand.
+
+## Theme: the voice
+
+A theme changes how the harness *sounds*: the banner, the readiness sigil the agent opens with, and the vocabulary of its prose. It never changes which rules apply or which files ship. The wizard previews each theme live as you move through the list.
+
+`neutral` is plain English. The others are `imperial`, `military`, `pirate`, `wizard`, `cyberpunk`, `gamer`, `sports`, `biker`, `commentator`, `joker`, `marvin`, `mean` and `verstappen`.
+
+```
+geneseed build --emit opencode-global --theme imperial
+```
+
+More in [Themes](../concepts/themes.md).
+
+## Posture: how the agent works with you
+
+Posture is the relationship register, fixed at build time so it does not drift mid-session:
+
+- **peer** *(default)*: a candid equal. Dense, challenges you, no flattery.
+- **mentor**: explains the why and checks your understanding.
+- **expert**: maximum density, no basics.
+- **assistant**: precise execution, low initiative. You steer.
+- **artisan**: a peer with toolsmith reflexes, terminal-first.
+
+```
+geneseed build --emit opencode-global --posture mentor
+```
+
+Pick **peer** unless you know you want another register. A theme changes the prose, while a posture changes the relationship. See [Collaboration](../concepts/collaboration.md).
+
+## Mode: who does the work
+
+- **direct** *(default)*: the agent works every task itself, turn by turn.
+- **foreman**: the session sorts each incoming task. A trivial task gets a direct answer. A substantial task goes to a small crew of agents (a **pipeline**) running in its own git worktree, while the session keeps answering you.
+
+A pipeline never commits or merges. It hands back its worktree uncommitted, together with its test and lint output. The session then re-runs those commands itself, shows you the diff and the passing output, and commits and merges only after you accept. Foreman mode costs more per substantial task, because several agents run instead of one. In exchange, the session stays responsive.
+
+```
+geneseed build --emit opencode-global --mode foreman
+geneseed build --emit opencode-global --mode direct    # back to the default
+```
+
+More in [Foreman mode](../concepts/foreman-mode.md).
+
+## Loop trust: how far a loop goes before it asks
+
+The `loop` skill scores every change it validates and stops to ask once the score passes a threshold. `--trust` sets the preset the skill starts a loop with; the user can still name another one per loop.
+
+- **prudent**: asks early, on anything past a rename.
+- **balanced** *(default)*: logic changes and new files pass with a note; API changes and deletions stop.
+- **aggressive**: only an architecture-level change stops the loop.
+
+The preset lives in the `loop` skill only, so it costs nothing in the always-on instructions.
+
+```
+geneseed build --emit opencode-global --trust prudent
+```
+
+## Doctrine packs: which practices bind
+
+The harness's rules come in tiers (see [Rules](../concepts/rules.md)). The Ethos and the Rules are always on. The **doctrines** are practices rather than principles, and they ship as packs you choose:
+
+| Pack | What it governs |
+| --- | --- |
+| **craft** | how code is written: reuse first, house conventions, docs updated 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 |
+| **process** | how a session runs: planning, context economy, docs first, bounded loops, and consent before every commit and push |
+| **comms** | how answers are presented: stable reference codes on tracked items, and a diagram or table only where it earns its place |
+
+Every pack is enabled by default. To keep only some packs, or none:
+
+```
+geneseed build --emit opencode-global --doctrines craft,rigor   # two packs
+geneseed build --emit opencode-global --doctrines none          # Ethos and Rules only
+```
+
+The packs always load in the same order (craft, rigor, ops, process, comms), whatever order you type them in. A pack you leave out still ships on disk under `doctrines/`, so you can read it before you turn it on. A clone can set its own default in `harness.config.json` with a `doctrines` array.
+
+**Dropping `process` changes what the machine does, not only what the agent reads.** The *Consent Before Push* rule in that pack is enforced at the tool boundary as well as in the prose:
+
+- On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push.
+- On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, entries that are already there are left in place and reported, because Geneseed cannot tell its own entries from ones you typed.
+
+The refusals of destructive git and `rm -rf` belong to the always-on Rules, not to the pack, so they stay in every build. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
+
+## One rule at a time
+
+A pack is all-or-nothing. `--exclude-rules` drops single doctrine rules instead. It takes rule addresses, written `<pack> <n>` or `<pack>.<n>`:
+
+```
+geneseed build --emit opencode-global --exclude-rules "process 7"
+geneseed build --emit opencode-global --exclude-rules "process 5,craft 2"
+geneseed build --emit opencode-global --exclude-rules none
+```
+
+The number in an address is the rule's position in its pack, so it can change if a rule is added or removed. To see the current addresses, pass an address that does not exist: the build refuses it and lists every valid address. The web console's **Constitution** page has one switch per rule. You stage the changes there and apply them in a single rebuild.
+
+Excluding *Consent Before Push* (`process 5` today) takes the commit and push consent gate with it, exactly as dropping the whole `process` pack does. The console and the wizard both warn you before applying it. A pack whose every rule is excluded drops out of the build entirely. See [Exclusions](../concepts/exclusions.md) for excluding whole folders instead.
+
+## Footprint: how much loads every turn
+
+Footprint controls how much of the rules text sits inside `AGENT.md`, which is loaded on every turn. It changes the token cost, not which rules apply:
+
+- **lean** *(default)*: each rule appears in a hand-written short form, with a pointer to the full text. The full text ships beside `AGENT.md`, and the agent reads it when a rule's nuance matters.
+- **full**: every rule's complete text and rationale is inline. This costs the most tokens. It can help a smaller model, which applies a rule's nuance more reliably when the reasoning is always in front of it.
+
+```
+geneseed build --emit opencode-global --footprint full
+```
+
+Both footprints install the same agents, skills, hooks and plugins. More in [Footprint](../concepts/footprint.md).
+
+## Changing a choice later
+
+You have three ways to change a choice:
+
+- **Re-run the wizard** with `geneseed setup`. It pre-selects what the install already has, so holding Enter cannot widen a set you narrowed on purpose. The wizard does not ask about single rules, but it keeps any rule exclusions already in place.
+- **Use the web console** (`geneseed web`). **Settings** and the **Harnesses** page change theme, footprint and the rest per install. **Constitution** toggles packs and rules.
+- **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want.
+
+---
+
+**Next:** [Verify it works](verify.md)

package/docs/guides/headless.md

@@ -0,0 +1,22 @@
+---
+group: guides
+order: 11
+title: "Run in CI / headless"
+kind: "concept"
+harness: "opencode"
+---
+Once the harness is installed for OpenCode (global or per repo), OpenCode can run **non-interactively**, without its terminal UI. The harness's rules, agents and skills then apply in scripts and pipelines too:
+
+```
+opencode run "review the staged diff and list any correctness bugs"   # one shot, prints to stdout
+opencode run -m anthropic/claude-sonnet-4-5 "…"                       # pin a model for this run
+cat issue.md | opencode run "triage this and propose a fix plan"      # pipe input in
+```
+
+`opencode run` loads the same `opencode.json` (its `instructions` pointing at `AGENT.md`, its permission rules, any per-agent overrides) and the same agents, skills and plugins as an interactive session. Geneseed writes nothing extra for this. It is ordinary OpenCode usage.
+
+## Things to know
+
+- **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `rm -rf`, and `git commit` and `git push` whenever the *Consent Before Push* rule is built in (it is part of the `process` pack; see [Choose your setup](choose-your-setup.md)). A CI job that has to commit should set those commands back to `"allow"` in its own `permission.bash` map, or limit the run to read-only work. Do not disable the guards wholesale.
+- **`--pure`** runs OpenCode without any local or global config. Use it to reproduce a bug without the harness in the way, or to confirm that a behaviour comes from the harness.
+- **The plugins still load.** The context plugin injects the repo's docs, and the learn plugin still writes memory when the session goes idle. To change their behaviour for a run, set `GENESEED_GUARD=warn` or `off`, `GENESEED_CONTEXT_INJECT=off`, or `GENESEED_DEBUG=1`. See [Environment](../reference/environment.md) and [OpenCode plugins](../reference/opencode-plugins.md).

package/docs/guides/install.md

@@ -0,0 +1,161 @@
+---
+group: guides
+order: 1
+title: "Install"
+kind: "concept"
+---
+Geneseed builds a harness (the rules, agents, skills and hooks your AI coding tool loads; see [What a harness is](../understand/harness.md)) and installs it into the tool you already use. Most people need one command.
+
+## The 5-minute path
+
+The only prerequisite is **Node 22.3 or newer**.
+
+```
+npx geneseed setup
+```
+
+The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH`, then asks for a theme, a posture, a mode, the doctrine packs, an install mode and a footprint. Each one has a safe default, so you can hold Enter through all of them. [Choose your setup](choose-your-setup.md) explains each question. **OpenCode global** is the recommended install mode: you install once and every repo inherits it, with nothing committed into your projects. The wizard then builds the harness and ends with a short summary: the root file your tool loads and where it was written, the hooks it wired (Claude Code, Bob and OpenClaude), whether memory learning is on, which tool to restart, and a link to what was installed. It then offers to run a health check.
+
+To keep the command on your machine:
+
+```
+npm install -g geneseed
+```
+
+This puts three commands on your `PATH`: `geneseed` (the CLI you type), `geneseed-build` (the generator) and `geneseed-hook` (what the host tool calls on every tool use, which you never type yourself).
+
+Next: [Verify it works](verify.md). To see what the install just wrote, read [What lands on your machine](../understand/on-your-machine.md).
+
+## From a clone
+
+Clone the repository when npm is out of reach (for example, a corporate network with no registry access), or when you want to change the harness rather than just use it. A clone needs **git** as well as Node 22.3 or newer. git is what updates the clone.
+
+Each OS has a one-step installer at the root of the clone. It checks for Node and git. If one is missing, it names what to install and where to get it, then stops. **It never installs anything itself.** When the checks pass, it runs the setup wizard and offers to open the web console.
+
+```bash
+git clone https://github.com/Arylmera/Geneseed.git
+cd Geneseed
+./install                 # macOS, Linux, or a POSIX shell on Windows
+```
+
+- **macOS**: you can also double-click `install.command` in the Finder. It opens in Terminal.
+- **Windows**: double-click `install.cmd` in Explorer, or run it from cmd or PowerShell. It needs no bash, WSL or PowerShell script.
+
+```powershell
+git clone https://github.com/Arylmera/Geneseed.git
+cd Geneseed
+.\install.cmd
+```
+
+Later, run the launcher in the clone: `./geneseed setup` (Windows: `.\geneseed.cmd setup`) re-runs the wizard, and bare `./geneseed` opens the web console. Both launchers need `node` on `PATH`. If it is not there (some version managers only patch interactive shells), set `GENESEED_NODE` to the absolute path of the Node binary.
+
+From a clone, every `geneseed …` command on these pages is `./geneseed …` (Windows: `.\geneseed.cmd …`). To drop the `./`, see [Run geneseed from anywhere](run-anywhere.md).
+
+## Prerequisites
+
+- **Node 22.3 or newer.** This is the only hard requirement. Geneseed has zero runtime dependencies, and nothing it installs needs a second interpreter.
+- **Your agent tool**: OpenCode (recommended), Claude Code, IBM Bob, OpenClaude, or any tool that reads a root instructions file.
+- **git**, for a clone only. A clone updates itself with `git pull`.
+- *Optional:* a document converter (MarkItDown, Pandoc or Docling) if you want the agent to read PDFs and Office files. See [MCP servers](mcp.md#reading-non-markdown-docs).
+
+## Without the wizard
+
+`setup` needs an interactive terminal. In a script, a CI job, or any shell without one, it stops with exit code 1 and prints the build command to run instead:
+
+```
+geneseed build --emit opencode-global --theme neutral
+```
+
+`geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md).
+
+To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
+
+## Install paths, one per host
+
+The wizard runs one of these for you. Use them directly when you script an install, or when you want a scope the wizard did not offer you.
+
+### OpenCode, global (recommended)
+
+```
+geneseed build --emit opencode-global
+```
+
+This writes into OpenCode's config directory: `$OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode` (on Windows too: `C:\Users\<you>\.config\opencode`). The install contains `AGENT.md`, `agents/`, `skills/`, the plugins, the `memory/` store, and a merged `opencode.json` whose `instructions` key points at `AGENT.md`. Every repo you open in OpenCode inherits it. You do not need a per-repo file, because the context plugin finds each repo's docs by itself (see [Project context](project-context.md)).
+
+The install is non-destructive. A manifest (`.geneseed-manifest.json`) records the files Geneseed owns. A rebuild replaces and prunes only those files, and never touches your own agents, skills, plugins or memory.
+
+### OpenCode, per repo
+
+```
+geneseed build --emit opencode --out /path/to/repo --root /path/to/repo
+```
+
+This writes the bundle (`AGENT.md`, `agents/`, `skills/`, `memory/`, `notebook/`) and OpenCode's own layer (`opencode.json` and `.opencode/`) into one repository. You can commit them or not. To keep the bundle in a subfolder, point `--out` at the subfolder and keep `--root` on the repo, so instruction paths resolve from the project root:
+
+```
+geneseed build --emit opencode --out /path/to/repo/Harness --root /path/to/repo
+```
+
+### Claude Code
+
+```
+geneseed build --emit claude-global                                  # ~/.claude, every repo
+geneseed build --emit claude --out /path/to/repo --root /path/to/repo   # one repo
+```
+
+The install writes `CLAUDE.md`, `agents/`, `skills/`, `memory/` and `notebook/`, plus hooks in Claude Code's `settings.json`. Hooks are commands Claude Code runs around each tool call. They gate risky actions and load project context (see [Hooks](../concepts/hooks.md)). For a project install the hooks go into `.claude/settings.local.json`, which stays out of git because it names a path on your machine.
+
+Every hook calls `geneseed-hook <verb>` through one stable file, the **hook shim** at `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim knows where Node and Geneseed live. If you move or replace Geneseed, one rebuild rewrites the shim and every install works again. `GENESEED_HOME` moves the shim's folder.
+
+### OpenClaude
+
+```
+geneseed build --emit openclaude-global                                   # ~/.openclaude
+geneseed build --emit openclaude --out /path/to/repo --root /path/to/repo # one repo
+```
+
+[OpenClaude](https://openclaude.gitlawb.com/) is a fork of Claude Code that can drive any model. You get the same agents, skills and hooks as Claude Code, under a different config directory. OpenClaude never reads `~/.claude` or a project `.claude/`, so the two installs can sit side by side. The differences:
+
+- Per repo, the preamble is written to `.openclaude/CLAUDE.md` rather than a root file, and the hooks go into `.openclaude/settings.local.json`.
+- `$OPENCLAUDE_CONFIG_DIR` moves the global directory (default `~/.openclaude`).
+
+OpenClaude support has not yet been verified against a live install.
+
+### IBM Bob
+
+```
+geneseed build --emit bob-global                                   # ~/.bob
+geneseed build --emit bob --out /path/to/repo --root /path/to/repo # one repo
+```
+
+Bob is shaped like Claude Code, so it gets the same agents and skills. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2, and Bob has no `SubagentStop` or `PreCompact` events. Bob support has not yet been verified against a live install.
+
+### Any AGENT.md tool
+
+```
+geneseed build            # renders the plain bundle into ./Harness
+```
+
+Point your tool's instructions or rules setting at `Harness/AGENT.md`. If the tool only loads one specific filename, rename or symlink the file (`AGENT.md` to `AGENTS.md` or `CLAUDE.md`). The rules then rest on the agent's own discipline, because these tools have no hooks or plugins to enforce anything (see [Enforced vs. asked](../understand/enforced-vs-asked.md)).
+
+Some of these tools also load skills. Their own docs list where:
+
+- **Codex CLI** loads a root `AGENTS.md` and `~/.codex/AGENTS.md`, and skills from `~/.codex/skills` or `.agents/skills`.
+- **Cursor** loads `AGENTS.md`, and skills from `.cursor/skills`, `.agents/skills` or `.claude/skills`.
+- **Gemini CLI** reads `GEMINI.md` by default. Set `context.fileName` in its `settings.json` to include `AGENTS.md`. Skills load from `.gemini/skills` or `.agents/skills`.
+
+Copy or symlink the bundle's `skills/` to `.agents/skills/` and all three of them see it.
+
+### No runtime on the target machine
+
+If the machine that will use the harness cannot run Node, run this once on a machine that can:
+
+```
+npx geneseed prompt --theme neutral > install-geneseed.md
+```
+
+This produces one self-contained prompt that recreates the whole file tree. Paste it into any capable agent on the target machine. There is nothing to install and no build step. Any theme works the same way.
+
+---
+
+**Next:** [Verify it works](verify.md) · [Choose your setup](choose-your-setup.md) · [What lands on your machine](../understand/on-your-machine.md)

package/docs/guides/mcp.md

@@ -0,0 +1,195 @@
+---
+group: guides
+order: 8
+title: "MCP servers"
+kind: "concept"
+---
+MCP (Model Context Protocol) servers give your agent extra tools: converting a PDF, opening a merge request, reading files outside the repo. Geneseed ships three ready-made server **presets** (MarkItDown, GitLab and Filesystem) that you can switch on without writing JSON by hand.
+
+> **You already know this:** an MCP entry is a line in a Procfile. It names a command the agent starts on demand. Writing the line does not install the program behind it.
+
+Each preset is a *local* server, a command your agent launches when it needs the server. Registering a preset only points the agent at that command. **You** install the tool behind it (or let `uvx` or `npx` fetch it) and you supply any credentials.
+
+> **Never commit a real token.** The presets ship with an empty `GITLAB_PERSONAL_ACCESS_TOKEN` and a sample filesystem path. Fill them in your own config, never in a tracked file.
+
+## Where the config lives
+
+Each host keeps its servers in its own file and in a slightly different shape:
+
+| Host | Project | Global | Shape |
+| --- | --- | --- | --- |
+| OpenCode | `opencode.json` (or `opencode.jsonc`) | `~/.config/opencode/opencode.json` | key `mcp`; `command` is one list; `environment`; `enabled` |
+| Claude Code | `.mcp.json` | `~/.claude.json` | key `mcpServers`; `command` + `args`; `env` |
+| OpenClaude | `.mcp.json` | `~/.openclaude.json` (or inside `$OPENCLAUDE_CONFIG_DIR`) | as Claude Code |
+| Bob | `.bob/mcp.json` | `~/.bob/settings/mcp.json` | as Claude Code |
+
+The same MarkItDown server in both shapes:
+
+```json
+{ "mcp": { "markitdown": { "type": "local", "command": ["uvx", "markitdown-mcp"], "enabled": true } } }
+```
+
+```json
+{ "mcpServers": { "markitdown": { "command": "uvx", "args": ["markitdown-mcp"] } } }
+```
+
+**Toggle instead of editing.** In the web console (`geneseed web`), **Settings → MCP servers** adds, enables, disables or removes any preset in the right file, already in the right shape. Not sure which file that is? The **Harnesses** page shows the config path for each install, and `geneseed mcp` prints the same paths and lists the servers each install has wired, without starting anything.
+
+The reference OpenCode config ships MarkItDown enabled and the GitLab and Filesystem entries disabled, so a merge never switches on a server that has no credentials yet. Fill in the blanks, then switch the server on.
+
+## MarkItDown
+
+[MarkItDown](https://github.com/microsoft/markitdown) (Microsoft) converts PDF, Word, Excel, PowerPoint and HTML to markdown. It exposes one tool, `convert_to_markdown(uri)`, which accepts `file:`, `http:`, `https:` and `data:` URIs.
+
+**1. Make the command resolve.**
+
+- **`uvx` (recommended, nothing to install).** If you have [uv](https://docs.astral.sh/uv/), `uvx markitdown-mcp` fetches and caches the server on first use. This is the command the preset uses.
+- **`pipx`.** Without uv, run `pipx install markitdown-mcp`, then use `markitdown-mcp` alone as the command (OpenCode: `["markitdown-mcp"]`; Claude: `"command": "markitdown-mcp"`, no args).
+
+```
+uvx markitdown-mcp --help                       # uv route: confirm it resolves
+pipx install markitdown-mcp && markitdown-mcp --help   # pipx route
+```
+
+For scanned or image-only PDFs, which otherwise come back empty, add the OCR extras: `uvx --with "markitdown[all]" markitdown-mcp`, or `pipx inject markitdown-mcp "markitdown[all]"`.
+
+**2. Corporate TLS (only behind an SSL-inspecting proxy).** uv ships its own root certificates and ignores the OS trust store, so a proxy's internal certificate fails with `invalid peer certificate: UnknownIssuer`. Point uv at the OS store rather than turning verification off:
+
+```
+export UV_SYSTEM_CERTS=true      # older uv: UV_NATIVE_TLS=true
+# fallback: export SSL_CERT_FILE=/path/to/corporate-root-ca.pem
+```
+
+**3. Register it**, with the console toggle or one of the blocks above. Then restart your agent.
+
+## GitLab
+
+[`@zereight/mcp-gitlab`](https://github.com/zereight/gitlab-mcp) provides repository, merge request, issue and CI tools over the GitLab API. It runs through `npx`, so nothing is installed globally. The same command serves gitlab.com and any self-hosted instance.
+
+**1. Create a personal access token** on the instance (User Settings → Access Tokens) with the scopes `api` and `read_repository`. Treat it like a password.
+
+**2. Register the server.**
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+```json
+{
+  "mcp": {
+    "gitlab": {
+      "type": "local",
+      "command": ["npx", "-y", "@zereight/mcp-gitlab"],
+      "environment": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@zereight/mcp-gitlab"],
+      "env": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  }
+}
+```
+
+You can also register it with `claude mcp add`.
+<!--/harness-->
+
+Keep the `/api/v4` suffix on the URL.
+
+**A second instance** (gitlab.com plus a self-hosted server, for example) is a copy of the same block under a new name, such as `gitlab-acme`, with its own `GITLAB_API_URL` and token. The preset covers the first instance only. You add the copy by hand.
+
+## Filesystem
+
+[`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) gives the agent file access limited to the folders you list, through `npx`. **The allowed folders are command-line arguments.** The server refuses any path outside them, so grant the narrowest set that works, not `$HOME` or `/`.
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+```json
+{
+  "mcp": {
+    "filesystem": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
+      "enabled": true
+    }
+  }
+}
+```
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+```json
+{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] } } }
+```
+<!--/harness-->
+
+> **Replace the placeholder.** The preset ships with the literal path `/path/to/allowed/dir`. If you enable the server without changing it, the server runs but can reach nothing. This is the classic "the filesystem MCP sees nothing" problem.
+
+## Verify
+
+Restart your agent, then list the servers:
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+`opencode mcp` lists each server and whether it **connected**.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+`/mcp` in a session, or `claude mcp list` in a terminal, shows each server and whether it connected.
+<!--/harness-->
+
+Being listed is not the same as working. A local server appears in the list whether or not its command actually launches.
+
+## A server won't connect
+
+Work through these in order:
+
+1. **Does the command resolve?** Run the exact command in a fresh terminal: `uvx markitdown-mcp --help`, or `npx -y @modelcontextprotocol/server-filesystem --help`. "command not found" means the binary is not on the `PATH` your agent starts from. Use the `uvx` or `npx` form, which needs only uv or Node, or point at the absolute path of the binary. This is the most common cause for MarkItDown.
+2. **Filesystem sees nothing?** The allowed folder is still the placeholder, or it points at a path that does not exist.
+3. **GitLab will not connect?** Almost always a missing or under-scoped token, or a wrong `GITLAB_API_URL`. Keep the `/api/v4` suffix.
+4. **Right file?** Editing a file the host does not read fails silently.
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+OpenCode reads `opencode.jsonc` if it exists, otherwise `opencode.json`, both in the project root and in `~/.config/opencode/`. The console toggle always writes the file OpenCode actually reads.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+Claude Code reads `.mcp.json` in the project and the `mcpServers` block in `~/.claude.json`. `claude mcp list` shows which servers actually loaded.
+<!--/harness-->
+
+## Reading non-markdown docs
+
+The agent's doc discovery only sees markdown. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
+
+- **MarkItDown**: the broadest. Use the MCP server above (preferred on a host with MCP: nothing to install per call, one cheap tool), or `pip install markitdown`.
+- **Pandoc**: excellent for Office and HTML, and a single binary.
+- **Docling** (IBM): best for complex tables and scanned PDFs.
+
+When an MCP converter is available, the skill prefers it. A prompt like *"convert file:///path/to/spec.pdf to markdown"* then just works. The skill never installs a converter silently. If none is present, it tells you which one to add.

package/docs/guides/migrate.md

@@ -0,0 +1,41 @@
+---
+group: guides
+order: 13
+title: "Migrate from a clone to npm"
+kind: "concept"
+---
+If you installed Geneseed by cloning the repository and now want to use the npm package, one command moves every install you already have, without touching your own settings.
+
+## Why there is something to migrate
+
+Claude Code, Bob and OpenClaude call Geneseed's hooks through one small file, the **hook shim** at `~/.geneseed/bin/geneseed-hook`. Every install's `settings.json` points at the shim, and the shim points at the Geneseed code it should run, which is your clone. Installing from npm moves that code. Each install also carries a `.geneseed-emit` marker, a small file that records which host and scope it was built for, so the install can be rebuilt as it was.
+
+## Run it
+
+Install the package first (`npm install -g geneseed`, or prefix each command with `npx`), then:
+
+```
+geneseed migrate --dry-run     # survey every install and print the plan; writes nothing
+geneseed migrate               # do it
+```
+
+`migrate` rebuilds every registered install **with its own theme, host, footprint, posture and mode**. Nothing is reset to a default. It then rewrites the hook shim to point at the npm package, and reports anything it is not allowed to fix for you. A second run prints `already on the npm shape` and writes nothing.
+
+## All or nothing
+
+Before changing anything, `migrate` copies every host settings file and the hook shim into `~/.geneseed/.migrate-backup/`. If any install fails to rebuild, **everything is put back** and the command exits non-zero. You are never left half on one setup and half on the other.
+
+`rebuild-all` behaves the opposite way on purpose: it carries on past a broken install so that one failure cannot block the rest.
+
+## It refuses rather than guesses
+
+If an install's `.geneseed-emit` marker names something this version does not recognise (a truncated or hand-edited file, for example), `migrate` **refuses the whole run**. It names the install and changes nothing. Rebuilding it would mean guessing which host and scope you chose. Fix or delete the marker, then run `migrate` again.
+
+## What it leaves alone
+
+`migrate` reports these instead of rewriting them:
+
+- **Hooks it did not write.** Your own hooks and any third-party hooks stay exactly as they are. A rebuild only replaces the hook groups that Geneseed's manifest says it owns.
+- **Login items.** If you set the web console to [start at login](autostart.md), you wrote that file yourself. If it still names your old clone, `migrate` prints its path and the command to put in it. You edit the file yourself.
+
+Your clone keeps working in the meantime, so you can migrate when it suits you.

package/docs/guides/project-context.md

@@ -0,0 +1,87 @@
+---
+group: guides
+order: 6
+title: "Project context"
+kind: "concept"
+---
+At the start of every session, the harness shows the agent your repo's own documentation. Usually you have nothing to configure. This page explains what gets loaded and what each choice costs, so you know when to override it.
+
+## Eager and lazy: what each costs
+
+The context step sorts every doc it finds into one of two lists:
+
+- **Eager**: the full text is put into the session. The agent knows it from the first turn, but you pay its tokens in **every** session in that repo, whether the task needs it or not.
+- **Lazy**: only the path (and a heading) is listed. The agent reads the file when a task calls for it. The cost is close to zero until the file is read.
+
+> **You already know this:** eager versus lazy loading of imports. Eager is fast to use and always paid for. Lazy costs one extra step and is free until you need it.
+
+## What is found automatically
+
+With no configuration, the context step finds these files:
+
+- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md`. The root file your tool already loads by itself is skipped, so you never pay for it twice.
+- **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`.
+- **Never scanned:** `node_modules`, `.git`, `dist`, `build`, `vendor`, `.next`, `target`, `.venv`, `__pycache__`, `.opencode` and `.harness`.
+
+Eager files share a 48 KB budget per session. An eager file that would go over the budget is listed instead, to be read on demand.
+
+On OpenCode the context plugin does this work. On Claude Code, Bob and OpenClaude, the session-start hook does it (`geneseed-hook context`). Both read the same override file, described next.
+
+## Override it with `context.json`
+
+Add a manifest only when the convention does not fit your repo. Put it at `.harness/context.json`, or at `context.json` in the repo root, or point `$GENESEED_CONTEXT` at it:
+
+```json
+{
+  "extend": true,
+  "context": [
+    { "path": "docs/house-rules.md", "load": "eager", "description": "Branch policy, definition of done." },
+    { "path": "docs/**/*.md", "load": "lazy" },
+    { "path": "internal/secrets.md", "load": "exclude" }
+  ]
+}
+```
+
+- `path` is absolute, relative to the repo, or a glob.
+- `load` is `eager`, `lazy` or `exclude`.
+- `"extend": true` keeps automatic discovery running and adds your entries on top. Without it, the manifest replaces discovery entirely.
+
+### Example: a monorepo
+
+A monorepo with docs scattered across packages might write:
+
+```json
+{
+  "extend": true,
+  "context": [
+    { "path": "docs/architecture.md", "load": "eager", "description": "system map" },
+    { "path": "api/README.md", "load": "eager" },
+    { "path": "web/README.md", "load": "eager" }
+  ]
+}
+```
+
+Keep the eager list to the few files a new teammate would read first. Three sharp docs beat ten broad ones. Use `"load": "lazy"` for anything a session should only read on demand.
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+## What else OpenCode adds
+
+On OpenCode the eager budget is adjustable: 16 KB per file and 48 KB in total by default, changed with `GENESEED_EAGER_FILE_KB` and `GENESEED_EAGER_TOTAL_KB`. When it can, the context block also adds two lines, so the agent starts out oriented:
+
+- the repo's **runnable commands**: targets from `Makefile`, `package.json` scripts (with the right runner for the lockfile), `justfile` and `Taskfile`;
+- the session's **current model**, read from the transcript, with `GENESEED_MODEL=provider/model` as a fallback.
+
+A line is simply left out when its source is missing.
+
+## How OpenCode delivers it
+
+By default, the plugin delivers the context invisibly. It prepends the context to each request through OpenCode's experimental `experimental.chat.messages.transform` hook, so nothing appears in the conversation. Because it is re-sent with every request, the context also survives compaction. If your OpenCode build lacks that hook, the plugin notices and falls back to posting a visible `PROJECT CONTEXT` message.
+
+- `GENESEED_CONTEXT_VISIBLE=1` always shows the visible block, so you can see what the agent received.
+- `GENESEED_CONTEXT_INJECT=off` turns injection off. The agent then relies on the instruction in `AGENT.md` to read the docs itself.
+- `GENESEED_DEBUG=1` logs what was discovered and how it was delivered.
+<!--/harness-->
+
+All the knobs are listed in [Environment](../reference/environment.md). For knowledge that belongs to you rather than to one repo, see [Wiki](wiki.md).