geneseed 2.0.0

package/docs/web/adapters-opencode-loads.md

@@ -0,0 +1,8 @@
+---
+group: deeper
+order: 3
+title: "OpenCode — how it loads"
+kind: "markdown"
+harness: "opencode"
+source: "adapters/opencode/HOW-OPENCODE-LOADS.md"
+---

package/docs/web/adapters-opencode-spec.md

@@ -0,0 +1,8 @@
+---
+group: deeper
+order: 2
+title: "OpenCode — global harness spec"
+kind: "markdown"
+harness: "opencode"
+source: "adapters/opencode/GLOBAL-HARNESS-SPEC.md"
+---

package/docs/web/adapters-opencode.md

@@ -0,0 +1,8 @@
+---
+group: deeper
+order: 1
+title: "OpenCode adapter"
+kind: "markdown"
+harness: "opencode"
+source: "adapters/opencode/README.md"
+---

package/docs/web/agents.md

@@ -0,0 +1,8 @@
+---
+group: concepts
+order: 2
+title: "Agents"
+kind: "concept"
+link: {"hash": "#/section/agents", "label": "Browse the catalog →"}
+---
+{N_AGENTS} capability specialists — `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, plus a debate **council** the [[council]] skill convenes (`advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian`). You delegate by capability, not by folder: the harness picks the right specialist from the request.

package/docs/web/authoring.md

@@ -0,0 +1,11 @@
+---
+group: extend
+order: 0
+title: "Edit the source"
+kind: "concept"
+---
+Everything theme-independent lives under `src/` — laws, agents, skills, memory and notebook conventions, and the `AGENT.md.tmpl` entrypoint. Voice tokens live under `themes/` as one JSON file per theme. After editing, `geneseed build --emit opencode-global` (or `geneseed update`) re-renders the deployed bundle. The `doctor` action verifies the result: unresolved theme tokens, dead links, hermetic escapes, theme-key parity, and that the committed bundle matches a fresh render.
+
+Each agent and skill also carries a lifecycle status — `experimental`, `approved` or `deprecated` — recorded in `registry.json` at the repo root alongside its version, owner and add-date. The file is maintainer-side: it is never rendered into a bundle, so a status costs no session context. Adding a spec means adding its row; `doctor` fails on a spec with no row and on a row with no spec, and the catalog badges anything that is not `approved`. The same pass refuses to let a credential ship, and holds every vendored skill folder to an immutable upstream commit rather than a moving branch.
+
+A skill you wrote yourself and dropped into the install has no row and never will — the registry describes what Geneseed ships. Those read **personal** and gather under their own class in the Skills ledger, apart from the six-class taxonomy they were never given a place in. A badge reading **no status** means something else entirely: `registry.json` could not be read at all, so nothing is known about anything — run `doctor`.

package/docs/web/autostart.md

@@ -0,0 +1,9 @@
+---
+group: start
+order: 5
+title: "Start the web UI at login"
+kind: "markdown"
+anchor: "start-the-web-ui-at-login"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/claude-hooks.md

@@ -0,0 +1,36 @@
+---
+group: hooks
+order: 0
+title: "How Geneseed binds to Claude Code"
+kind: "concept"
+---
+Claude Code has no `instructions` array and no JS plugin dir — the harness reaches it through **`settings.json` hooks** instead: the same capabilities the OpenCode plugins provide, each driven by a `geneseed-hook` subcommand. `CLAUDE.md` itself auto-loads by location, so it needs no hook at all.
+
+### The four hooks
+
+- **Context injection** — `SessionStart` (startup, clear, resume) runs `geneseed-hook context`: auto-discovers the repo's docs by convention and injects them before your first turn, plus your machine wiki. It honours the same `GENESEED_CONTEXT` manifest as the OpenCode context plugin.
+- **Git gate** — `PreToolUse` on Bash runs `geneseed-hook git-gate`: enforces the safety Laws at the tool boundary, before a shell command executes.
+- **Rule gate** — `PreToolUse` on the write tools runs `geneseed-hook rule-gate`: a write to `user-rules.md` or to a memory file asks first, because whether something you want kept is a standing rule or a durable fact is *your* call, settled through the [rule skill](#/docs/skills) (**Law VI**). Ordinary edits are untouched.
+- **Learn** — `Stop` and `SubagentStop` run `geneseed-hook learn`: distils durable memories into the install's `memory/` store at session end; a subagent's stop routes to the per-agent lesson path (`memory/agents/<name>.md`).
+
+### Where they live
+
+The emit merges the hook groups surgically into your `settings.json` (global `~/.claude/settings.json`, or the project's), preserving every other key and any hooks of your own. The install manifest records exactly which groups Geneseed owns, so an upgrade replaces and an uninstall removes precisely those — never yours.
+
+### The hook shim
+
+Hooks run with the project as their working directory, so every command has to be an absolute path. Rather than write the interpreter and this checkout into your `settings.json`, the emit points all four hooks at one stable file — the **hook shim**, at `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim holds the two volatile paths; the config holds none.
+
+That indirection is what lets the checkout move. Before it, relocating or replacing the clone silently broke the gates in every install at once, and the only repair was re-emitting every config. Now a single build rewrites the shim and every install is live again. The shim is refreshed on **every** emit, so an ordinary `geneseed build` is the repair; `geneseed doctor` reports it if it was ever stale.
+
+Set `GENESEED_HOME` to keep the shim somewhere other than `~/.geneseed`.
+
+The shim prints nothing of its own, deliberately: the gates return success on every path and signal their verdict as JSON on **stdout**, so a single stray byte from the shim would corrupt that verdict and turn a blocking gate into a silently permissive one.
+
+### Verify
+
+Open Claude Code in any repo: the first reply opens with the readiness sigil and your project's docs are already in context. End a session and check the install's `memory/` dir for distilled files.
+
+---
+
+**Deeper:** [Claude Code adapter](#/docs/adapters-claude-code)

package/docs/web/cli.md

@@ -0,0 +1,6 @@
+---
+group: reference
+order: 0
+title: "CLI — every subcommand"
+kind: "cli"
+---

package/docs/web/collaboration.md

@@ -0,0 +1,27 @@
+---
+group: concepts
+order: 11
+title: "The collaboration layer"
+kind: "concept"
+---
+Beyond the Laws, four mechanisms shape *how* the agent works with you — the register, the mutual contract, how memory binds, and who you are. All four are plain content in `AGENT.md` and its neighbours, so they ride to every host (OpenCode, Claude, Bob, Copilot) unchanged.
+
+### Postures — the register
+
+A **posture** is the relationship register the agent works in, chosen by *you* at setup and fixed at build time so it holds steady instead of drifting back toward plain execution mid-session. Five ship: **peer** (default — a candid equal), **mentor** (explains the why), **expert** (maximum density), **assistant** (precise, low-initiative), **artisan** (peer with toolsmith reflexes). Posture is orthogonal to theme: theme is the *voice*, posture is the *relationship*. Change it in the setup wizard, from the **Harnesses** page here (the per-install posture dropdown, next to voice and footprint), or with `geneseed-build --posture <name>`. A rebuild or re-theme preserves it.
+
+### Modes — how work executes
+
+A **mode** is the session's operating register — *how* work gets executed, as opposed to posture's *relationship* register. Two ship: **direct** (default — the agent works every task itself, turn by turn) and **foreman** (the session triages incoming tasks: trivial ones get a direct answer, substantial ones spawn an isolated pipeline — a crew of an analyst, a developer, and a tester, plus whatever specialists the task needs — that reports back and merges only once its own tests and lint pass, while the session keeps answering you). Expect foreman mode to cost more per substantial task, in exchange for a session that never blocks on one. Change it in the setup wizard, from the **Harnesses** page here (the per-install mode dropdown, next to posture), or with `geneseed-build --mode <name>`; switch back any time with `--mode direct`. A rebuild or re-theme preserves it. See [Foreman mode](#/docs/foreman-mode) and [agent pipelines](#/docs/pipelines) for the dedicated pages.
+
+### The Pact — a two-way contract
+
+Where the Laws bind the agent, the **Pact** binds the collaboration. It holds three co-equal protections (you, the truth, the agent) and — unusually — names what *you* owe back: don't punish candour that honours the pact, give context up front, decide when shown a fork. It is framing, not an enforced rule.
+
+### Typed memory — binding force
+
+A memory may carry an optional `force` — **constraint** (imposed, not the agent's to relax), **choice** (revisable with consent), **conviction** (revisable on evidence), or **tempered** (a relaxed constraint). When new evidence contradicts a forced memory, the Bridge rule requires revising it in the open rather than dropping it silently.
+
+### Your profile — identity
+
+`PROFILE.md`, seeded once beside `AGENT.md` and never overwritten, holds *who you are*: role, habits, register preferences. It is identity, not rules — it colours how the agent works but never binds (precedence is Laws, then `user-rules.md`, then the profile). Edit it here under the **Profile** tab, or in the file directly — or let the agent draft it: the [[profile]] skill interviews you (who you are, how you work, how you like answers pitched) and writes the file only with your consent, routing anything that is really a standing rule to `user-rules.md` instead.

package/docs/web/configure-wiki.md

@@ -0,0 +1,9 @@
+---
+group: howto
+order: 1
+title: "Configure a wiki (knowledge base)"
+kind: "markdown"
+anchor: "wiki-your-own-knowledge-base-optional"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/design.md

@@ -0,0 +1,7 @@
+---
+group: deeper
+order: 0
+title: "DESIGN.md — the spec"
+kind: "markdown"
+source: "DESIGN.md"
+---

package/docs/web/env-knobs.md

@@ -0,0 +1,9 @@
+---
+group: reference
+order: 1
+title: "Environment variables"
+kind: "markdown"
+anchor: "environment-knobs"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/exclusions.md

@@ -0,0 +1,26 @@
+---
+group: concepts
+order: 9
+title: "Sovereign repos (exclusions)"
+kind: "concept"
+link: {"hash": "#/harnesses", "label": "Manage in Harnesses →"}
+---
+A **sovereign repo** is a folder where every GLOBAL harness install goes fully dormant: hooks stay silent and the global preamble (`AGENT.md`/`CLAUDE.md`) is never loaded there. A repo that ships its own agent config you don't want a global harness layered onto is the usual case.
+
+### Total dormancy, not a filter
+
+Exclusion is all-or-nothing per folder — it doesn't trim which Rules apply or which Skills load, the global harness simply never engages inside that tree. A per-repo Geneseed install in the same folder is unaffected; exclusions only ever suppress GLOBAL installs.
+
+### How it's wired, per host
+
+- **Claude Code** — native suppression via `claudeMdExcludes` in the repo's `.claude/settings.local.json`.
+- **Bob** — a shadow `rules/geneseed.md` stub that shadows the global one (never overwrites a hand-written stub already there).
+- **OpenCode** — the hook entry's sovereign-bypass guard and its twin in the plugins short-circuit at session start.
+- **Copilot — documented limitation.** GitHub Copilot has no native per-repo suppression hook: the global `copilot-instructions.md` still loads even inside an excluded folder.
+
+### Manage it
+
+- **CLI** — `harness exclude add <path>` / `remove <path>` / `list`.
+- **This console** — the **Excluded folders** card on the **Harnesses** page (shown once a global install exists).
+
+Exclusions live in each global install's own `excludes.json`, so add/remove re-wires every global install in one call — nothing to repeat per host.

package/docs/web/first-session.md

@@ -0,0 +1,28 @@
+---
+group: start
+order: 3
+title: "Your first session"
+kind: "concept"
+---
+Once installed, the agent doesn't change *how* you talk to your tool — it changes what the tool already knows when you do.
+
+### What loaded automatically
+
+- **`AGENT.md`** — {N_LAWS} universal Rules the agent obeys.
+- **Your repo's docs** — `README.md`, `CONTRIBUTING.md`, anything under `docs/` the harness discovers.
+- **Your machine's wiki** (if you [set one up](#/docs/configure-wiki)) — eager entries and a lazy listing of the rest.
+- **The skill and agent catalogue** — invokable by name.
+
+### Try these prompts
+
+- *"Use the **profile** skill"* — a short interview that drafts `PROFILE.md` (seeded empty at install), so the agent knows who you are and how you like answers pitched.
+- *"Use the **clarify** skill on this feature request."*
+- *"Delegate to the **reviewer** agent on the staged diff."*
+- *"Use **brainstorm** then **plan** for how to add X."*
+- *"Use **council** to debate whether we should ship Y now."*
+
+Skills are repeatable workflows; agents are capability specialists. You invoke them by name in plain English.
+
+---
+
+**Catalog:** [Skills](#/section/skills) · [Agents](#/section/agents) · [Rules](#/laws)

package/docs/web/footprint.md

@@ -0,0 +1,31 @@
+---
+group: concepts
+order: 8
+title: "Footprint (lean vs full)"
+kind: "concept"
+link: {"hash": "#/settings", "label": "Toggle it in Settings →"}
+---
+**Footprint** controls how much of the Rules your agent carries *inline* in `AGENT.md` every turn. Two states — **lean** (the default) and **full** — set per install. It's a token-cost dial, not a change to which Rules apply: every Rule is always in force, and across lean and full the emitted files are otherwise identical — same Agents, Skills, plugins, commands, Memory, and Notebook.
+
+### The difference
+
+- **Full** — Section 1 of `AGENT.md` inlines every Rule's complete text *and* its reasoning. The agent sees the full law set, rationale included, on every single turn.
+- **Lean** — Section 1 carries each Rule as its **heading + the rule itself** (one line), followed by a pointer to the complete law file (`laws/universal.md`, shipped beside `AGENT.md`) — the agent reads the rationale on demand when a rule's application is unclear. Lean trims Section 1 by roughly 40%.
+
+### Which to choose
+
+- Keep **full** if token cost is a non-issue, you want the rationale always present, or you run a smaller/cheaper model — with the *why* eagerly in context, a model applies a Rule's nuance more reliably. This is why full is the default.
+- Switch to **lean** to reclaim context and cost on long sessions, large repos, or cost-sensitive runs, trusting the agent to pull the full law when it needs the *why*. Lean is **safe**: the complete law text still ships, and the harness explicitly points the agent there before acting on secrets, deletion, git history, scope, or untrusted content. It's an optimization, not a rules cut.
+
+### How to set it
+
+It's set-and-forget — stored in the `.geneseed-footprint` marker, preserved across every rebuild, identical on every host (OpenCode, Claude Code, Bob, Copilot). Changing it re-emits the install.
+
+- **Settings** — the **Footprint** toggle flips the current install (full ⇄ lean) and rebuilds it in place.
+- **Harnesses tab** — a per-harness dropdown sets it for any one install independently, then **Apply**.
+- **Setup / re-theme wizard** — asks for footprint alongside voice and mode.
+- **CLI** — `geneseed-build --footprint lean` (with any `--emit`).
+
+---
+
+**Related:** [Rules (Laws)](#/laws) · [Voice vs structure](#/docs/themes) · [Token footprint — the numbers](#/docs/token-footprint)

package/docs/web/foreman-mode.md

@@ -0,0 +1,33 @@
+---
+group: concepts
+order: 12
+title: "Foreman mode"
+kind: "concept"
+link: {"hash": "#/harnesses", "label": "Set the mode in Harnesses →"}
+---
+**Mode** is the session's *operating* register — how work gets executed — a separate dial from posture (the *relationship* register) and footprint (how much of the Rules loads inline). Two modes ship, set at build time so the choice holds steady instead of drifting mid-session, and preserved across every rebuild and re-theme.
+
+### direct — the default
+
+The agent works every task itself, turn by turn — exactly as it does without the dial. Nothing spawns; you talk to one agent from start to finish. Keep it unless you specifically want the session managing work for you.
+
+### foreman — a session that triages
+
+The session becomes a triage layer instead of a single worker. It sorts each incoming request:
+
+- **Trivial** — answered directly, in-line, just like direct mode.
+- **Substantial** — handed to an isolated [agent pipeline](#/docs/pipelines): a crew that runs on its own, reports back, and merges only once its own tests and lint pass.
+
+Because the crew runs apart from the conversation, the session stays responsive — you keep talking to the foreman while the work proceeds. Expect foreman to cost more per substantial task (a crew runs instead of one agent), in exchange for a session that never blocks on a long job.
+
+### How to set it
+
+Set-and-forget, stored beside the install and preserved across rebuilds and re-themes:
+
+- **Harnesses tab** — the per-install **Mode** dropdown (beside Voice, Footprint, and Posture), then **Apply**.
+- **Setup / re-theme wizard** — asks for mode alongside voice, posture, and footprint.
+- **CLI** — `geneseed-build --mode foreman`; switch back with `--mode direct`.
+
+---
+
+**Related:** [Agent pipelines](#/docs/pipelines) · [The collaboration layer](#/docs/collaboration)

package/docs/web/glossary.md

@@ -0,0 +1,6 @@
+---
+group: reference
+order: 2
+title: "Glossary (in your deployed voice)"
+kind: "glossary"
+---

package/docs/web/harnesses.md

@@ -0,0 +1,28 @@
+---
+group: start
+order: 4
+title: "Supported harnesses"
+kind: "concept"
+---
+One source, **five emit targets** — each with a per-repo and a global (`-global`) variant, plus a portable `files` bundle any `AGENT.md`-aware tool can read. **OpenCode** runs its own engine (JS plugins, colour themes, LSP); **Claude Code**, **Bob**, and **Copilot** share one Claude-shaped engine that diverges only by host dialect.
+
+The harness itself — Rules, Agents, Skills, Memory, and the preamble voice — is **identical on every host**. What differs is how much of it the host can *automate* (via plugins or hooks) versus carry as preamble discipline.
+
+| Capability | OpenCode | Claude | Bob | Copilot |
+| --- | :---: | :---: | :---: | :---: |
+| Agents · Skills · Memory | ✅ | ✅ | ✅ | ✅ |
+| Context injection | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
+| Memory write-back (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
+| Git-gate consent (Rule XX) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
+| Sovereign-repo excludes | ⚙️ plugin | ✅ | ✅ | ➖ |
+| MCP server wiring | ✅ | ✅ | ✅ | ✅ |
+| Colour themes | ✅ | ➖ | ➖ | ➖ |
+| LSP · workflows · primary-agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
+
+✅ native · ⚙️ OpenCode plugin · 🪝 `settings.json` hook · 📄 preamble prose only · ➖ no host mechanism (harness discipline still applies). ¹ Bob honours Claude-dialect hooks best-effort — inert if unsupported, harness still holds via the preamble.
+
+**No host drops an Agent, Skill, or the memory convention.** The asymmetry is entirely in *automation mechanism*: OpenCode's plugins and Claude/Bob's hooks enforce a few Rules for you, where **Copilot** (no hook mechanism) enforces them through preamble discipline. The OpenCode-only extras (themes, LSP, workflow runner, primary-agent) have no analogue on a Claude-shaped host.
+
+---
+
+**Deeper:** [The harness model](#/docs/model) · [Footprint per host](#/docs/footprint)

package/docs/web/headless.md

@@ -0,0 +1,9 @@
+---
+group: howto
+order: 6
+title: "Run in CI / headless"
+kind: "markdown"
+anchor: "headless-ci-opencode"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/ingest-docs.md

@@ -0,0 +1,9 @@
+---
+group: howto
+order: 3
+title: "Read PDFs / Office docs"
+kind: "markdown"
+anchor: "reading-non-markdown-docs"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/install-paths.md

@@ -0,0 +1,9 @@
+---
+group: howto
+order: 0
+title: "Choose your install path"
+kind: "markdown"
+anchor: "choose-your-path"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/install-quick.md

@@ -0,0 +1,35 @@
+---
+group: start
+order: 0
+title: "Install in 5 minutes"
+kind: "concept"
+---
+Two steps. The only prerequisite is **Node ≥ 22.3** — Geneseed ships as an npm package with zero dependencies.
+
+### 1. Run the setup wizard
+
+```
+npx geneseed setup
+```
+
+The same command on macOS, Linux and Windows (cmd, PowerShell, or any POSIX shell). The wizard asks for a theme and an install mode (OpenCode global is recommended — one install, every repo inherits it), then builds and offers a health check.
+
+To keep the command around: `npm install -g geneseed`, then plain `geneseed …` from any directory.
+
+### 2. Open your agent
+
+Open OpenCode (or Claude Code, Bob, Copilot, or any `AGENT.md`-aware tool) in any repo. The first reply opens with the readiness sigil (`✅` neutral / `🧬` imperial / your theme's equivalent) and your project's docs are already in context.
+
+### Prefer a clone?
+
+```
+git clone https://github.com/Arylmera/Geneseed.git
+cd Geneseed
+./geneseed setup            # Windows: .\geneseed.cmd setup
+```
+
+A checkout needs **git** and the same **Node ≥ 22.3** as everything else — there is nothing extra to install — and is what you want if you intend to change the harness rather than use it. Already installed this way? [Migrate to npx](#/docs/migrate) moves every install across in one pass.
+
+---
+
+**Next:** [Posture & footprint](#/docs/setup-choices) · [Verify it works](#/docs/verify) · [What you just installed](#/docs/model) · [Install by hand instead](#/docs/install-paths)

package/docs/web/lsp-overview.md

@@ -0,0 +1,37 @@
+---
+group: lsp
+order: 0
+title: "Code intelligence (LSP)"
+kind: "concept"
+link: {"hash": "#/docs/adapters-opencode", "label": "OpenCode adapter →"}
+---
+OpenCode can drive Language Server Protocol servers so the agent sees real diagnostics, type errors, and go-to-definition — not just text. Geneseed turns this on for every language OpenCode ships a server for.
+
+### What's covered out of the box
+
+| Language | Server | You install? |
+|---|---|---|
+| JavaScript / TypeScript / React / React Native | typescript-language-server | No — OpenCode self-downloads |
+| Python | pyright | No — OpenCode self-downloads |
+| Java | jdtls | **JDK 21+** (OpenCode downloads jdtls itself) |
+| SQL / PostgreSQL / Oracle | *none — by design* | — |
+
+One server covers JavaScript, TypeScript, React, and React Native — they are all TS/JS, so no extra server is needed.
+
+### The one prerequisite the harness can't self-install
+
+OpenCode downloads the JS-runtime servers automatically on first use. It cannot install a JVM, and jdtls needs one — so the setup wizard checks for it and prints an install hint if missing:
+
+- **Java 21+** — `brew install openjdk@21`, SDKMAN `sdk install java 21-tem`, or your distro's JDK.
+
+### Why no SQL server
+
+A SQL language server is dialect-locked — a Postgres server flags Oracle SQL as errors and vice versa — and a `.sql` file can map to only one server, with no signal for which dialect a repo uses. Rather than guess wrong for half of all SQL codebases, we ship none. A project that knows its dialect can add the matching server in its own `opencode.json` under the `lsp` key.
+
+### How it's wired
+
+`"lsp": true` in your emitted `opencode.json` enables every built-in server (LSP is off by default). To turn auto-download off (air-gapped machines), set `OPENCODE_DISABLE_LSP_DOWNLOAD=true` and pre-install each server.
+
+---
+
+**Verify:** open a `.ts` and a `.py` file in a session and ask the agent for diagnostics — the first open triggers the download.

package/docs/web/mcp-claude-code.md

@@ -0,0 +1,10 @@
+---
+group: mcp
+order: 4
+title: "Claude Code"
+kind: "markdown"
+harness: "claude"
+anchor: "claude-code"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/mcp-filesystem.md

@@ -0,0 +1,9 @@
+---
+group: mcp
+order: 3
+title: "Filesystem"
+kind: "markdown"
+anchor: "filesystem"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/mcp-gitlab.md

@@ -0,0 +1,9 @@
+---
+group: mcp
+order: 2
+title: "GitLab"
+kind: "markdown"
+anchor: "gitlab-one-entry-per-instance"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/mcp-markitdown.md

@@ -0,0 +1,9 @@
+---
+group: mcp
+order: 1
+title: "MarkItDown (PDF/Office)"
+kind: "markdown"
+anchor: "markitdown-via-mcp"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/mcp-overview.md

@@ -0,0 +1,34 @@
+---
+group: mcp
+order: 0
+title: "MCP overview"
+kind: "concept"
+---
+The Harness ships **three** ready-to-wire MCP servers as presets — **MarkItDown** (PDF/Office → Markdown), **GitLab** (shipped as two entries, one per instance), and **Filesystem** (scoped file access) — four config entries in all. Each is a *local* server the agent launches on demand: registering one only points the agent at a command — *you* install the tool (or let `npx`/`pipx` fetch it) and supply any credentials.
+
+### Where they live
+
+<!--harness:opencode-->
+They sit under the `mcp` key of an `opencode.json` (global `~/.config/opencode/opencode.json` or per-repo), each entry shaped:
+
+```json
+"<name>": { "type": "local", "command": ["…"], "environment": {}, "enabled": true }
+```
+<!--/harness-->
+<!--harness:claude-->
+They live in `.mcp.json` under `mcpServers` — note the key is `env` (not `environment`) and the command and its args are split into `command` + `args`. See [Claude Code wiring](#/docs/mcp-claude-code).
+<!--/harness-->
+
+<!--harness:opencode-->
+### Toggle them without hand-editing JSON
+
+`./geneseed` → **Settings** → **MCP servers** toggles any of the presets into your project or global `opencode.json` — and enables, disables, or removes them — for you. The reference config ships MarkItDown enabled and the GitLab / Filesystem entries disabled, so a merge never activates a credential-less server: fill the blanks, then flip the one(s) you want on.
+<!--/harness-->
+
+> **Never commit a real token.** The presets ship with **empty** `GITLAB_PERSONAL_ACCESS_TOKEN` placeholders (and a sample filesystem path) — fill them in your own config, never in a tracked file (universal Law I — secrets).
+
+---
+
+**Wire one up:** [MarkItDown](#/docs/mcp-markitdown) · [GitLab](#/docs/mcp-gitlab) · [Filesystem](#/docs/mcp-filesystem) · [Verify](#/docs/mcp-verify) · [Won't connect?](#/docs/mcp-trouble)
+
+> **Listed ≠ working.** A `local` server is just a command the agent runs — it appears in the list whether or not that command actually launches. The usual cause of "shown but not working" is the command not being on PATH (e.g. `markitdown-mcp` with no `uvx`/pipx install) or a filesystem entry left on its placeholder path. [Walk the fixes →](#/docs/mcp-trouble)

package/docs/web/mcp-trouble.md

@@ -0,0 +1,9 @@
+---
+group: mcp
+order: 6
+title: "Won't connect?"
+kind: "markdown"
+anchor: "mcp-server-wont-connect"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/mcp-verify.md

@@ -0,0 +1,9 @@
+---
+group: mcp
+order: 5
+title: "Verify"
+kind: "markdown"
+anchor: "verify"
+source: "SETUP.md"
+slice: true
+---

package/docs/web/memory.md

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

package/docs/web/migrate.md

@@ -0,0 +1,39 @@
+---
+group: howto
+order: 8
+title: "Migrate an existing install to npx"
+kind: "concept"
+---
+If you installed Geneseed by cloning the repository, your hooks currently run through a small machine-wide shim at `~/.geneseed/bin/geneseed-hook` that hands every call to *your checkout*. Installing from npm changes where that code lives. **`geneseed migrate` moves every install you already have onto the new shape, in one pass, without touching your own settings.**
+
+### What it does
+
+```
+geneseed migrate --dry-run     # survey and print the plan; writes nothing
+geneseed migrate               # do it
+```
+
+It surveys every registered install, re-emits each one **in its own theme, emit, footprint, posture and mode** — nothing is defaulted, so a rebuild never silently changes what you chose — re-bakes the machine-wide hook shim so it points at the new location, and reports anything it is not allowed to fix for you.
+
+Run it once, from the new install. A second run says `already on the npm shape` and writes nothing.
+
+### It is all-or-nothing
+
+Before it changes 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 run exits non-zero. You are never left half on one shape and half on the other. `rebuild-all` deliberately continues past a broken install so one failure cannot block the rest; a migration deliberately does the opposite.
+
+### It refuses rather than guesses
+
+If a registered install carries a `.geneseed-emit` marker that names something this generator does not recognise — a truncated or hand-edited file — `migrate` **refuses the whole run**, names the install, and changes nothing. Rebuilding it would mean guessing which host and scope you installed, and re-emitting an install as something its owner never chose is worse than stopping. Fix or delete the marker and re-run.
+
+### What it will not touch
+
+Two things are yours, and `migrate` reports them instead of rewriting them:
+
+- **Hooks it did not write.** Your own hooks, and any third-party ones, are left exactly as they are — the re-emit only replaces the hook groups Geneseed's own manifest claims.
+- **Autostart entries.** If you set the web UI to [start at login](#/docs/autostart), that VBS script or LaunchAgent is a file you hand-wrote — Geneseed has never created one. If it still names your old checkout, `migrate` prints its path and the command to put there. Edit it yourself.
+
+If your `settings.json` has comments in it, Geneseed will not rewrite the file at all (it never has — your edits are safe), so the hooks in it stay pointing at the old shim until you update them by hand.
+
+### Your old clone keeps working
+
+Nothing breaks the day you install from npm. A cloned checkout continues to work for one full release, printing the migration instructions when you `git pull`. There is no cliff — migrate when it suits you.

package/docs/web/model.md

@@ -0,0 +1,20 @@
+---
+group: concepts
+order: 0
+title: "The harness model"
+kind: "concept"
+---
+Geneseed assembles five runtime pieces around a single `AGENT.md` entrypoint: **Rules** (the laws the agent obeys), **Agents** (capability specialists you delegate to), **Skills** (repeatable workflows the agent can invoke), **Memory** (one-fact-per-file durable knowledge), and a **Notebook** (the agent's own sovereign space).
+<!--harness:opencode-->
+On OpenCode, {N_PLUGINS} **Plugins** bind the pieces to the host: context injection, learn-at-session-end, the safety guard, the saved workflow runner, end-of-run notifications, a live-activity feed for this console, and an opt-in minimal-code mode.
+<!--/harness-->
+<!--harness:claude-->
+On Claude Code, three settings.json **hooks** bind the pieces to the host — context injection, the git safety gate, and learn-at-session-end. See [How Geneseed binds to Claude Code](#/docs/claude-hooks).
+<!--/harness-->
+The structure is theme-independent — a theme only changes the *voice* (banner, sigil, prose), never a folder or a link. A separate dial, the **[footprint](#/docs/footprint)**, sets how much of the Rules load inline each turn (full vs lean), the **[collaboration layer](#/docs/collaboration)** — posture, the Pact, typed memory, your profile — shapes how the agent works *with you*, and the **mode** dial ([direct vs foreman](#/docs/foreman-mode)) sets *how work gets executed* — one agent turn by turn, or a foreman triaging tasks into [pipelines](#/docs/pipelines).
+
+### What this UI actually shows
+
+The **Library** and **Graph** render the Geneseed source live — they show the harness that *would* be deployed if you rebuilt right now. The **Settings** panes and the **Memory** drawer read from the deployed harness on disk (the harness install dir, e.g. `~/.config/opencode/…` for an OpenCode global install).
+
+If you've built recently, the two match. If you edit a file under `src/` and reload this panel, the Library updates immediately — the deployed bundle does not, until the next `geneseed update` or `build`.

package/docs/web/notebook.md

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