geneseed 3.11.0 → 3.13.0

package/docs/guides/install.md

@@ -3,6 +3,8 @@ group: guides
 order: 1
 title: "Install"
 kind: "concept"
+section: "Install"
+description: "The one-command install, what it needs, and the page for each host."
 ---
 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.
 
@@ -26,135 +28,24 @@ This puts three commands on your `PATH`: `geneseed` (the CLI you type), `genesee
 
 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`, `--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).
+- *Optional:* a document converter (MarkItDown, Pandoc or Docling) if you want the agent to read PDFs and Office files. See [Reading non-markdown docs](read-non-markdown.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
-```
+- [OpenCode](install-opencode.md): global (recommended) or per repo.
+- [Claude Code](install-claude-code.md): global or per repo, with hooks.
+- [OpenClaude](install-openclaude.md): Claude Code's pieces under OpenClaude's own folder.
+- [IBM Bob](install-bob.md): global or per repo.
+- [Any AGENT.md tool](install-agent-md.md): the plain bundle, or a machine with no runtime.
 
-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.
+No npm? Install [from a clone](install-clone.md). Scripting it? See [Install without the wizard](install-scripted.md).
 
 ---
 

package/docs/guides/loop-finish.md

@@ -0,0 +1,54 @@
+---
+group: guides
+order: 24
+title: "Finish a loop"
+kind: "concept"
+section: "Loops"
+description: "How a loop ends and gets merged, how to drive one by hand, and fixes for what goes wrong."
+---
+How a loop ends, how to drive the engine by hand, and what to do when a loop misbehaves. To start one, see [Run a loop](run-a-loop.md).
+
+## The end: you merge
+
+On `$close` the agent removes `LOOP.md` in one last commit. That commit is outside the loop's exemption, so the git gate asks you: saying yes is how you close the loop. The agent then reports the iteration count, the soft iterations to review, the notes, and the branch.
+
+**The loop never merges.** Open a pull request from `loop/<slug>`, or review the branch, and merge it yourself. Merging a loop branch always asks, with no exception. Remove the worktree when you are done (`git worktree remove ../<repo>-loop-<slug>`).
+
+## Running one by hand (advanced)
+
+You can drive the engine without the agent, which helps when you debug a template. Work from a worktree on a `loop/*` branch:
+
+```bash
+geneseed loop check --graph my-loop.json          # validate a graph file (keep it outside the worktree)
+geneseed loop init --title "Rate limit /orders" \
+  --requirement "429 after 100 requests a minute per key" \
+  --graph tdd --preset prudent --contracts 'api/openapi.yaml'
+geneseed loop next                                 # what to do now, as one JSON object
+```
+
+Then repeat `geneseed loop next` and act on what it prints:
+
+| `next` prints | You run |
+| --- | --- |
+| `{node, validate: true}` | `geneseed loop score --declared` (or, for a setup brick, `--actions … --write-set '…' --intent …`) |
+| `{node}` | the brick's prompt, then `git status --porcelain \| geneseed loop record --outcome <outcome>` (the iteration head adds `--card '<json>'` when it reports `more`) |
+| `{verify, run}` | exactly the printed `run` command, which pipes the staged numstat into `geneseed loop score --diff` |
+| `{awaiting}` | `geneseed loop decide --verdict ok\|no\|amend --note "…"` |
+| `{commit: true, message_file}` | `git add -A && git commit -F <message_file> && git push -u origin HEAD:loop/<slug>` |
+| `{terminal}` | nothing more: `$close` or `$stop` |
+
+Every flag is in `geneseed loop --help`. The full cycle, including discards and notes, is in [Loops](../concepts/loops.md).
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| It stopped as blocking on a small change | The diff touched a file outside the iteration's declared write set, which raises the score to at least the API weight. Check the reasons it shows. Answer ok if the file belongs to the change, or amend with a note to keep it out. |
+| The git gate asks on every iteration's commit | Only one exact shape is exempt. A `cd …` prefix, `git -C`, a quoted refspec (`"HEAD:loop/x"`), `git commit -m` or a message-file path with a space all fall back to asking. Make sure the session works from the worktree itself. |
+| The final `close` commit asks | Expected. The loop is over, and that ask is your consent to close it. |
+| `mutation-check` reported `unavailable` | No mutation tool is configured. The loop continues and records the gap in `LOOP.md`'s notes. Add PIT, Stryker, mutmut or cargo-mutants to make it bite. |
+| `ci-repair` closed at once with "CI does not run for <sha>" | CI has no run for the pushed commit. Enable your pipeline on `loop/*` branches and check that `gh` is logged in. |
+| `geneseed loop init` says `LOOP.md already exists` | A loop is already running in this worktree. Resume it with `geneseed loop next`, or start the new one in another worktree. |
+| `init` prints `problems` | The graph fails `loop check`, for example a cycle not declared as a loop, or a brick that is missing or unavailable. Fix the graph, or pick a shipped template. |
+| A loop is missing from **Loops › Active** | Only loops started with `geneseed loop init` from a version with the registry appear there. Look in the worktree's `LOOP.md` instead. |
+| The agent does not know about loops | The install predates the `loop` skill. Run `geneseed rebuild-all`, then start a new session. |

package/docs/guides/loop-running.md

@@ -0,0 +1,66 @@
+---
+group: guides
+order: 23
+title: "While a loop runs"
+kind: "concept"
+section: "Loops"
+description: "What a running loop commits, when it stops to ask you, where to watch it, and how to stop or resume it."
+---
+A loop started with [Run a loop](run-a-loop.md) works on its own `loop/<slug>` branch. This is what you see while it runs, and how to step in.
+
+Each iteration is one commit on `loop/<slug>`, pushed as it lands. Work done before the first iteration, such as reproducing a bug, is its own commit, numbered iteration 0. Every change ends at one of three levels:
+
+| Level | What you see |
+| --- | --- |
+| **silent** | Only the commit and its trailers. |
+| **soft** | The commit lands, and the final report lists it under "to review". |
+| **blocking** | The agent stops and asks you before anything is committed. |
+
+## When it asks you
+
+The agent ends its turn and shows you what it is waiting on:
+
+- **A blocking score**: the change it plans (before it runs) or the staged diff (after), with the reasons for the score. One file outside the declared write set, more than 20 deleted lines, or a file that matches the loop's `contracts` is enough.
+- **A human gate**: some bricks always stop for you, whatever the preset. An ADR that survived its skeptic (`adr-challenge`), an architecture rule and its allowlist (`fitness-define`), a contract migration plan (`migration-plan`) and a feature spec (`spec`) are all gated.
+- **Launch**, under `prudent`: the graph it is about to run.
+
+Answer in the agent's session, in your own words:
+
+| You say | What happens |
+| --- | --- |
+| ok / go ahead | It continues. On a gate held on a failure, ok follows that failure's edge, which usually stops the loop. |
+| no | The loop stops at that node. |
+| amend, with a note ("keep the old field until v3") | The same brick runs again with your note added to `LOOP.md`. A gate can be amended three times per iteration; a fourth amend stops the loop. |
+| amend, at the `prudent` launch prompt | The loop stops ("graph to amend") with your note: nothing has run yet, so ask again for the loop you want. |
+
+The agent passes your answer on as `geneseed loop decide --verdict ok|no|amend --note "<your words>"`. The console never answers for you.
+
+## Where to watch
+
+- **Console: Loops › Active.** Every registered loop, awaiting ones first: the branch, `iteration N / max`, the current node on its ring, what an awaiting loop waits on, and the iteration history.
+- **`LOOP.md`** at the worktree root: the title, the requirement, the preset, the contracts, the notes the bricks left, and the engine's state.
+- **The commits.** Each one carries the iteration, the bricks it ran, its declared and actual risk, the decision and the test state:
+
+```bash
+git log --format='%h %s%n%(trailers)' loop/<slug>
+```
+
+While a loop runs on its `loop/*` branch, the git gate lets exactly one commit-and-push shape through without asking, the one the agent uses to close each iteration. Any other git command still asks, as usual. Bob has no ask prompt, so there the commit and push gate logs a warning instead of asking.
+
+## Stop, resume, and what ends a loop
+
+- **Stop.** Interrupt the agent whenever you like. The state is `LOOP.md` plus the branch, so nothing is lost.
+- **Resume.** Ask "resume the loop" in a session opened in the worktree, or run `geneseed loop next` there. The same goes after you answered a question in a new session.
+
+A loop ends one of two ways:
+
+| End | When |
+| --- | --- |
+| `$close` | The iteration head reports nothing left to do. Some templates first run an independent `done-check`. |
+| `$stop` | A brick reported an outcome wired to stop (a red baseline in `baseline-green`, say), you answered no, a gate was amended a fourth time, two iterations in a row produced no diff, an inner retry ring ran out twice in one iteration, a read-only brick changed files, or the iteration ceiling was reached (the template's `max`, never above 20). |
+
+On `$stop` the agent reports the reason and leaves the branch as it is.
+
+---
+
+**Next:** [Finish a loop](loop-finish.md)

package/docs/guides/loop-which-template.md

@@ -0,0 +1,35 @@
+---
+group: guides
+order: 22
+title: "Which loop template"
+kind: "concept"
+section: "Loops"
+description: "Pick a loop template by what you want to do."
+---
+[Run a loop](run-a-loop.md) takes a template by name, or lets the agent compose a graph from the bricks. Pick one by what you want to do:
+
+| I want to… | Template | Category |
+| --- | --- | --- |
+| Record a design decision as an ADR before any code changes | `architecture-decision` | architecture |
+| Make a rule hold everywhere (a test with an allowlist, then one violation fixed per iteration) | `enforce-architecture-rule` | architecture |
+| Change an API, schema or event that has live consumers, without breaking them | `update-contract` | architecture |
+| Pin untested legacy behaviour with characterization tests, production code untouched | `legacy-tests` | tests |
+| Write each failing test before the code that passes it | `tdd` | tests |
+| Fix a test that fails only sometimes, at its root cause | `fix-flaky-tests` | tests |
+| Fix a reported bug, starting from a failing reproduction | `bugfix` | development |
+| Build a feature in planned iterations | `feature` | development |
+| Pin the acceptance criteria in a spec you review first, then build it | `spec-first-feature` | development |
+| Add or change HTTP endpoints, each with a Bruno request and a security pass | `api-endpoint` | development |
+| Restructure code that the tests already cover | `refactor` | refactoring |
+| Refactor code that has no tests yet | `legacy-refactor` | refactoring |
+| Delete unused code, one coherent group per iteration | `remove-dead-code` | refactoring |
+| Upgrade dependencies one package or group at a time | `deps-upgrade` | day-to-day |
+| Turn a red CI run green on a `loop/*` branch | `ci-repair` | day-to-day |
+
+The console's **Loops › Templates** shows each one as a ring, with its bricks and which of them stop for you.
+
+What each template's bricks do: [Loop templates](../concepts/loop-templates.md).
+
+---
+
+**Next:** [While a loop runs](loop-running.md)

package/docs/guides/mcp-filesystem.md

@@ -0,0 +1,41 @@
+---
+group: guides
+order: 19
+title: "Filesystem (MCP)"
+kind: "concept"
+section: "Set up"
+description: "File access limited to the folders you list, and the placeholder path to replace."
+---
+One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+
+[`@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.
+
+---
+
+**Next:** [Check the servers connected](mcp.md)

package/docs/guides/mcp-gitlab.md

@@ -0,0 +1,66 @@
+---
+group: guides
+order: 18
+title: "GitLab (MCP)"
+kind: "concept"
+section: "Set up"
+description: "Merge requests, issues and CI from the agent: token scopes, the config block, a second instance."
+---
+One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+
+> **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.
+
+[`@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.
+
+---
+
+**Next:** [Filesystem (MCP)](mcp-filesystem.md)

package/docs/guides/mcp-markitdown.md

@@ -0,0 +1,36 @@
+---
+group: guides
+order: 17
+title: "MarkItDown (MCP)"
+kind: "concept"
+section: "Set up"
+description: "Convert PDF and Office files to markdown: uvx or pipx, OCR extras, corporate TLS."
+---
+One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+
+[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 in [MCP servers](mcp.md). Then restart your agent.
+
+---
+
+**Next:** [Reading non-markdown docs](read-non-markdown.md)

package/docs/guides/mcp.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 8
+order: 16
 title: "MCP servers"
 kind: "concept"
+section: "Set up"
+description: "Where MCP config lives for each host, the three presets, and how to check a server connected."
 ---
 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.
 
@@ -37,113 +39,11 @@ The same MarkItDown server in both shapes:
 
 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
+## The presets
 
-[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.
+- [MarkItDown](mcp-markitdown.md): converts PDF, Word, Excel, PowerPoint and HTML to markdown.
+- [GitLab](mcp-gitlab.md): repository, merge request, issue and CI tools over the GitLab API.
+- [Filesystem](mcp-filesystem.md): file access limited to the folders you list.
 
 ## Verify
 
@@ -163,33 +63,4 @@ Restart your agent, then list the servers:
 
 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.
+Listed but not connecting? See [Model, agent and MCP problems](../reference/troubleshoot-tools.md). To have the agent read PDFs and Office files, see [Reading non-markdown docs](read-non-markdown.md).

package/docs/guides/migrate.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 13
+order: 26
 title: "Migrate from a clone to npm"
 kind: "concept"
+section: "Keep it running"
+description: "Move an old clone install to the npm package."
 ---
 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.
 

package/docs/guides/project-context.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 6
+order: 14
 title: "Project context"
 kind: "concept"
+section: "Set up"
+description: "Choose which of a repo's docs the agent loads."
 ---
 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.
 
@@ -84,4 +86,4 @@ By default, the plugin delivers the context invisibly. It prepends the context t
 - `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).
+All the knobs are listed in [Context and memory variables](../reference/env-context.md). For knowledge that belongs to you rather than to one repo, see [Wiki](wiki.md).