geneseed 3.10.0 → 3.11.0

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

package/docs/guides/run-anywhere.md

@@ -0,0 +1,45 @@
+---
+group: guides
+order: 9
+title: "Run geneseed from anywhere"
+kind: "concept"
+---
+**Installed from npm? You have nothing to do.** `npm install -g geneseed` already puts `geneseed`, `geneseed-build` and `geneseed-hook` on your `PATH`.
+
+From a clone, you call the launcher inside the clone: `./geneseed` (Windows: `.\geneseed.cmd`). To type plain `geneseed` from any folder, link it.
+
+## macOS and Linux
+
+```
+./geneseed link                    # a launcher in ~/.local/bin, no sudo
+./geneseed link /usr/local/bin     # or another bin folder (may ask for sudo)
+```
+
+`link` writes a small shell launcher that runs this clone by its absolute path. It also tells you whether the target folder is on your `PATH`, and if it is not, the one line to add to your shell profile. Then:
+
+```
+geneseed            # the web console (or the command list), from any folder
+geneseed build      # and every other command
+```
+
+If you prefer a shell function, add one to your `~/.zshrc` or `~/.bashrc` from inside the clone instead:
+
+```
+echo 'geneseed() { "'"$PWD"'/geneseed" "$@"; }' >> ~/.zshrc
+```
+
+## Windows
+
+```powershell
+.\geneseed.cmd link
+```
+
+This writes a `geneseed.cmd` launcher into `%LOCALAPPDATA%\Geneseed\bin` and adds that folder to your user `PATH`. You need neither admin rights nor symlinks. Open a new terminal, then call `geneseed` from any folder.
+
+## Undo it
+
+```
+geneseed unlink
+```
+
+`unlink` removes the launchers that `link` wrote. It leaves alone any `geneseed` it did not write itself. In the web console, **Settings** has the same link and unlink controls.

package/docs/guides/uninstall.md

@@ -0,0 +1,51 @@
+---
+group: guides
+order: 5
+title: "Uninstall"
+kind: "concept"
+---
+`geneseed uninstall` removes one install at a time. It deletes only what Geneseed wrote and keeps anything you would not be able to rebuild.
+
+## Remove an install
+
+```
+geneseed uninstall                          # the project install in this folder, else the OpenCode global one
+geneseed uninstall --target /path/to/repo   # a project install
+geneseed uninstall --target ~/.claude       # a global install: pass its config directory
+```
+
+Without `--target`, the command picks the project install in the current folder if there is one, and the OpenCode global install otherwise. It prints what it will remove and asks before going on. Pass `--yes` to skip the question. In a shell without an interactive terminal, `--yes` is required: without it, the command refuses and exits 1.
+
+To see where each install lives, run `geneseed status`. The web console's **Harnesses** page can also uninstall.
+
+## What it removes
+
+Each install keeps a manifest, a list of the files Geneseed wrote. **Uninstall deletes exactly those files and nothing else**, then removes any folders they leave empty. A file of yours that sits in the same folder stays.
+
+- **OpenCode global:** `AGENT.md`, `agents/`, `skills/`, `plugins/`, the marker files, and the `instructions` entry in `opencode.json`.
+- **OpenCode per repo:** `AGENT.md`, `.opencode/`, `laws/`, `agents/`, `skills/`, and the `instructions` entry in `opencode.json`.
+- **Claude Code, Bob, OpenClaude:** `agents/`, `skills/`, the marker files, Geneseed's managed block in the instructions file (`CLAUDE.md` or `AGENTS.md`), and Geneseed's own hooks and exclusions in `settings.json`. Your own settings keys and hooks stay.
+
+It also removes the install's row from the registry of installs. Start a new session in your tool afterwards so it stops loading the old files.
+
+## What it keeps
+
+- **`memory/` and `notebook/`.** These are never deleted. `--archive-memory` moves both aside, into sibling `archived-memory/<timestamp>/` and `archived-notebook/<timestamp>/` folders, instead of leaving them in place. Even then they are moved, not deleted.
+- **`wiki.jsonc`**, **`context.json`** and the **`improvements/`** folder. None of these are in the manifest.
+- **Other installs.** Removing the global install does not touch any project install. Uninstall lists the project installs that remain, each with the command that removes it. If a repo carries installs for several hosts, uninstall removes one and tells you to run it again for the next.
+
+## The hook shim
+
+Claude Code, Bob and OpenClaude hooks all run through one shared file, the hook shim at `~/.geneseed/bin/geneseed-hook` (or under `$GENESEED_HOME`). Uninstalling an install removes that install's hooks but leaves the shim, because other installs may still use it. Once no install is left, you can delete the `~/.geneseed` folder yourself.
+
+## Remove the `geneseed` command
+
+The commands themselves are removed separately:
+
+```
+npm uninstall -g geneseed     # installed from npm
+```
+
+From a clone, `geneseed unlink` removes the launcher that `geneseed link` put on your `PATH` (see [Run geneseed from anywhere](run-anywhere.md)). Then delete the clone folder.
+
+If you set the web console to start at login, delete that login item too. It is a file you created, and Geneseed never removes it (see [Start the web console at login](autostart.md)).

package/docs/guides/upgrade.md

@@ -0,0 +1,65 @@
+---
+group: guides
+order: 4
+title: "Upgrade"
+kind: "concept"
+---
+Upgrading happens in two steps: get the new Geneseed, then rebuild every install from it. Editing or updating Geneseed changes nothing on your machine until something rebuilds. The route depends on how you installed.
+
+## Installed from npm
+
+```
+npm install -g geneseed@latest     # get the new version
+geneseed rebuild-all               # rebuild every install with its own settings
+```
+
+`rebuild-all` re-renders each registered install in place, keeping its own theme, host, footprint, posture, mode, packs and rule exclusions. It is best-effort: when one install fails, it reports the failure and carries on with the rest.
+
+`upgrade`, `update`, `sync-self` and `bootstrap` are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
+
+## Installed from a clone
+
+```
+geneseed upgrade              # pull, check, rebuild; keeps theme and install mode
+geneseed upgrade imperial     # the same, switching the theme
+```
+
+`upgrade` does three things:
+
+1. It runs a fast-forward-only `git pull` from the clone's own remote, on the current branch.
+2. It runs a blocking `doctor` pass over the result, and rolls back if it fails.
+3. It rebuilds the bundle and every install in place.
+
+A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` and `sync-self` are aliases of `upgrade`. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
+
+## What an upgrade keeps
+
+A rebuild only replaces files the install's manifest says Geneseed owns. It leaves these alone:
+
+- the `memory/` and `notebook/` stores;
+- your `context.json` and `wiki.jsonc`;
+- the marker files that record each install's choices (theme, footprint, packs, excluded rules), which every rebuild reads back;
+- your own agents, skills, plugins and hooks, and any `opencode.json` or `settings.json` keys you wrote yourself;
+- the `improvements/` folder (see below).
+
+## Local edits, and the improvements file
+
+The agent can refine its own deployed agent and skill files as it works, and so can you. A rebuild would overwrite those edits, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
+
+To see the drift yourself, or to export it on demand:
+
+```
+geneseed diff                          # file-level summary of what diverged
+geneseed diff --full                   # with line-level diffs
+geneseed diff --out improvements.md    # write the improvements file
+```
+
+`diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
+
+## Moving from a clone to npm
+
+If you installed from a clone and now want the npm package, `geneseed migrate` moves every install across in one pass. See [Migrate to npm](migrate.md).
+
+---
+
+**Next:** [Verify it works](verify.md) · [Uninstall](uninstall.md)

package/docs/guides/verify.md

@@ -0,0 +1,65 @@
+---
+group: guides
+order: 3
+title: "Verify it works"
+kind: "concept"
+---
+Four checks, from quickest to most thorough. The first one alone tells you whether the harness loaded.
+
+## 1. The readiness sigil
+
+Open your agent in any repo and say anything. The first reply opens with the readiness line: `✅` for the neutral theme, `🧬` for imperial, or your theme's own sigil.
+
+If the sigil is missing, the tool is not loading `AGENT.md`. Check that your tool's instructions setting points at it. On OpenCode, that is the `instructions` key in `opencode.json`.
+
+## 2. `geneseed doctor`
+
+```
+geneseed doctor
+```
+
+`npx geneseed doctor` runs the same check without installing anything. Doctor renders the harness and checks the result for unresolved theme tokens, dead links, missing files and drift from the source. It checks the theme you installed, unless you pass `--theme NAME` for another theme or `--all` for every theme. A clean run ends with a line like this:
+
+```
+[doctor] ok — 1 theme(s) clean: no unresolved tokens, no dead …
+```
+
+Every failure comes with a hint for fixing it. Doctor also reports a stale hook shim, the file every Claude Code, Bob and OpenClaude hook goes through. If that shim points at a folder that no longer exists, the hooks stop silently. One `geneseed build` (or `geneseed rebuild-all`) rewrites it.
+
+## 3. `geneseed status`
+
+```
+geneseed status
+```
+
+This prints a dashboard with your theme, the components installed, the memory store, the version, the active doctrine packs, and one row per install with its host, scope, theme, footprint, posture, mode and packs. A healthy install reads `active`. If the bottom of the dashboard says the installed build differs from the current source, run `geneseed rebuild-all` (see [Upgrade](upgrade.md)).
+
+The `gates` row counts how often a gate asked or blocked, per rule. It shows the hooks are actually firing. `geneseed status --json` prints the same data as JSON, including the exact `geneseed build` command that rebuilds each install.
+
+## 4. Context delivery
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+Start a session with `GENESEED_DEBUG=1` set. The context plugin then logs what it discovered and injected, and you should see the repo's `README.md` and its docs listed. To check memory, do a little work and end the session. After a quiet period, the learn plugin logs `wrote N memory file(s)` or the reason it skipped. Total silence means the plugin did not load.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+At session start, the context hook adds the repo's docs to the conversation. Ask the agent what project context it received. It should name your `README.md` and list your `docs/`.
+<!--/harness-->
+
+## Dry-run a build before you write it
+
+`geneseed validate` takes the same flags as `geneseed build`. It renders into a throwaway sandbox and runs every doctor check against the result. Nothing is written under the real `--out` or `--root`: no marker files, no settings merge, no registry record.
+
+```
+geneseed validate --theme imperial --emit opencode --out /path/to/repo/Harness
+```
+
+It prints how many files each layer would get (`-v` lists the paths), exits `0` when the build is clean, and exits non-zero on any problem. It is useful in CI, or before you point a real build at a repo you do not want to touch yet. The generator itself (`geneseed-build`) has no dry-run flag. `validate` is a separate command because it runs doctor, and the generator is not allowed to start processes.
+
+---
+
+Something wrong? See [Troubleshooting](../reference/troubleshooting.md).

package/docs/guides/wiki.md

@@ -0,0 +1,69 @@
+---
+group: guides
+order: 7
+title: "Connect your wiki"
+kind: "concept"
+---
+If you keep a personal knowledge base on this machine, such as an Obsidian vault or any folder of interlinked markdown, you can declare it once. The agent then reads from it and writes to it while following your own structure. This is optional. Until you declare a wiki, the feature stays off.
+
+> **You already know this:** a wiki is a shared drive with a README that says "read me before you add anything". The agent reads that note first, files new notes where your structure says they belong, and keeps out of the folders you marked off-limits.
+
+## Wiki, memory, notebook: three different stores
+
+- **[Memory](../concepts/memory.md)**: small facts the agent learns, one per file, private to this machine.
+- **[Notebook](../concepts/notebook.md)**: the agent's own scratch space.
+- **Wiki**: durable knowledge that spans projects, which **you** own and curate.
+
+When a memory fact or a notebook note hardens into knowledge worth keeping across projects, the agent promotes it into the wiki, so the truth lives in one place.
+
+## Declare it in `wiki.jsonc`
+
+The build writes a `wiki.jsonc` stub beside `AGENT.md` (for the OpenCode global install, `~/.config/opencode/wiki.jsonc`) and never overwrites it. The file is JSONC, so comments and trailing commas are fine. The stub contains this example, commented out:
+
+```json
+{
+  "wikis": [{
+    "name": "Brain",
+    "path": "/home/me/Documents/Brain",
+    "description": "my machine-wide knowledge base",
+    "entries": [
+      { "path": "ARCHITECTURE.md", "load": "eager", "description": "the root map" },
+      { "path": ".", "load": "lazy" }
+    ],
+    "conventions": "STYLE.md",
+    "inbox": "Inbox/",
+    "protected": ["Journal/"]
+  }]
+}
+```
+
+- **`path`**: the vault root, absolute. On Windows, use forward slashes (`C:/Users/me/Brain`).
+- **`entries`**: notes the agent sees each session, with the same `eager` and `lazy` meaning as [project context](project-context.md). An eager note is loaded in full. A lazy note is only listed, and the agent reads it on demand. An entry can be one note or a folder (`"."` is the whole vault; dot-folders like `.obsidian` are skipped). A file entry overrides its folder's mode, and `"load": "exclude"` removes a note or folder from the list. The example above is the usual shape: the root index eager, everything else lazy.
+- **`conventions`**: the note the agent must read before its first write, so new notes match your naming, frontmatter and folder rules.
+- **`inbox`**: where the agent drops a note it cannot confidently file, instead of guessing.
+- **`protected`**: folders the agent must never write to.
+
+You can declare several wikis. An empty `wikis` list keeps the feature off. The file may hold private paths. It is specific to this machine and must never be committed. A project install's own `.gitignore` already lists it.
+
+Geneseed looks for the file in this order: `$GENESEED_WIKI`, then `$GENESEED_HARNESS/wiki.jsonc`, then beside the installed `AGENT.md`. A `wiki.json` left by an older install is still read at each of those places.
+
+## How each host honours it
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+The context plugin loads your eager entries and lists your lazy ones at session start. A big vault's lazy list stops at 200 notes and shows a count of the rest (`GENESEED_WIKI_LAZY_LIMIT` changes the limit). The guard plugin **blocks** any write into a `protected` folder at the tool boundary, before the write happens. `GENESEED_GUARD=warn` turns the block into a warning, and `GENESEED_GUARD=off` disables the guard.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+No hook reads the wiki. The instructions in your harness tell the agent to read `wiki.jsonc` at session start and to honour it, including the `protected` folders. That is an instruction the model follows, not a block. Nothing stops a write at the tool boundary. The same applies to Bob, OpenClaude and plain `AGENT.md` tools. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
+<!--/harness-->
+
+## What the agent does with it
+
+The `wiki` skill drives the procedure.
+
+- **Reading.** The agent starts from your entry notes and moves outward by your own structure, following `[[wikilinks]]` and index notes, instead of reading the whole vault. It treats what it reads as true when written, and checks it against the live system before building on it.
+- **Writing.** Durable, reusable facts that span projects go back into the wiki as proper notes: wikilinked, in your house style, filed where your structure says (or in the inbox). Session details stay in memory, and secrets are never written anywhere. The agent never restructures the vault. Moving and renaming notes is your call.