geneseed 2.0.0

package/SHIPPED.md

@@ -0,0 +1,70 @@
+<div align="center">
+
+# 🧬 Geneseed — What's Shipped
+
+**A registry of the harness's capabilities and the dated spec behind each.**
+
+[← README](README.md) · [Design](DESIGN.md)
+
+</div>
+
+---
+
+This page answers "what is actually in the harness, and where is its rationale?"
+The dated `docs/specs/*` files were the *design record* — the problem and the
+decisions behind each feature; this is the *index* over them, marking what has
+landed in the source tree. Specs are working documents: they live git-ignored on
+the authoring machine and are dropped once shipped, so the spec links below are
+historical pointers, not files distributed with the repo.
+
+> **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
+> human-readable label only. The canonical identity of an installed harness is the
+> **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
+> string. Current label: **2.0.0**.
+
+> **Spec status audit (2026-06-15).** Every dated spec authored before today was
+> verified against the source tree and confirmed implemented (code + tests + docs);
+> their `**Status:**` headers were flipped from `approved`/`implementing`/`Accepted`/`spec`
+> to `implemented`. The only open spec is the same-day
+> [shell-completion](docs/specs/2026-06-15-shell-completion.md) draft.
+
+## Capabilities
+
+Every row below is present in the tree today; "Spec" links the design record.
+
+| Capability | What it is | Spec |
+| --- | --- | --- |
+| **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
+| **Laws / Agents / Skills / Memory / Notebook** | 37 laws, 17 agents, 47 skills, the memory convention, and the agent's sovereign notebook | [notebook](docs/specs/2026-06-11-notebook-sovereign-space.md) · [agent-own-space](docs/specs/2026-06-10-notebook-agent-own-space.md) |
+| **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | [theme-aware doctor/diff](docs/specs/2026-06-07-theme-aware-doctor-diff.md) |
+| **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | [improvements-export](docs/specs/2026-06-12-improvements-export.md) |
+| **`status` / `version`** | Headless dashboard + fingerprint verdict (no TUI needed) | [status-command](docs/specs/2026-06-07-status-command.md) · [version-and-uninstall](docs/specs/2026-06-07-version-and-uninstall.md) |
+| **Terminal rendering** | There is no full-screen control panel: `tui` and `menu` are verbs that say so and print the command list. The display-width and glyph layer ships on, behind `status` and the install animation | [refactor-polish](docs/specs/2026-06-07-tui-refactor-polish.md) · [modern-refresh](docs/specs/2026-06-08-tui-modern-refresh.md) · [windows-tui](docs/specs/2026-06-11-windows-tui.md) |
+| **Web console** | Local browser UI (Dashboard, Library, Graph, Docs, Specs, Changes, Doctor, Themes, Settings), auto-build, in-app docs menu | [web-ui-v2](docs/specs/2026-06-12-web-ui-v2.md) · [web-auto-build](docs/specs/2026-06-12-web-auto-build.md) · [docs-menu](docs/specs/2026-06-13-docs-menu.md) |
+| **OpenCode adapter** | Native agents/skills mapping + plugins (context, learn, guard, workflow, notify, ponytail, activity); global-emit link integrity; JSONC config target | [adapter-features](docs/specs/2026-06-07-opencode-adapter-features.md) · [global-emit](docs/specs/2026-06-07-global-emit-link-integrity.md) · [jsonc-target](docs/specs/2026-06-12-opencode-jsonc-target.md) · [ponytail](docs/specs/2026-06-16-ponytail-minimal-code-mode.md) |
+| **Workflow primitive** | Saved, code-driven subagent orchestration (`workflow` tool + runtime); shipped scripts include `dispatch` — decompose a goal, route each subtask to its owning agent, converge | [workflow-primitive](docs/specs/2026-06-09-opencode-workflow-primitive.md) |
+| **Per-agent memory** | Each capability agent keeps durable lessons in `memory/agents/<name>.md`: read at dispatch, written back mechanically by `learn` on session/subagent end (OpenCode plugin + claude/bob `SubagentStop`); `learn --consolidate` rebuilds the index | [orchestration-memory-upgrade](docs/specs/2026-07-04-orchestration-memory-upgrade.md) |
+| **Wiki integration** | Machine-wide knowledge base (`wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | [wiki-knowledge-base](docs/specs/2026-06-11-wiki-knowledge-base.md) |
+| **Collaboration layer** | Negotiated postures (peer/mentor/expert/assistant/artisan, chosen at setup, inlined in AGENT.md), the bidirectional Pact, epistemically-typed memory (`force:` + Bridge rule), and a seed-once `PROFILE.md` identity with a web editor tab and a `profile` skill that interviews the user to draft it | [collaboration-layer](docs/specs/2026-07-12-collaboration-layer.md) |
+| **Rule front door** | Both durable stores enter through the `rule` skill's fork (*standing rule, or fact to remember?* — always asked, never inferred): the memory branch elicits the binding `force` and shows the file before writing, the rule branch pressure-tests by reformulation and a mandatory counter-example. Law VI carries the norm on every host; a `rule-gate` PreToolUse hook (Claude, Bob) and a `geneseed-guard` speed bump (OpenCode) hold it at the tool boundary | [rule-front-door](docs/specs/2026-07-30-rule-front-door.md) |
+| **Entity registry** | `registry.json` records a lifecycle status, version, owner and add-date for every agent and skill in the tree (maintainer-side — never rendered into a bundle, so it costs no session context). `doctor` gates it against `src/` in both directions, sweeps everything that ships for credentials, and holds each vendored skill folder to an immutable upstream commit. The status surfaces as a badge in the web catalog, shown only where it deviates from `approved` | [entity-registry](docs/specs/2026-07-31-entity-registry.md) |
+| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all four hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. What each of them emits is replayed against frozen recordings on every commit, across every theme × host × footprint. It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` and `herdr` call `node -e` | [npx-distribution](docs/specs/2026-08-06-npx-distribution.md) |
+| **Runtime awareness** | MCP discovery, web research, tool-call batching, review discipline baked into the laws | [runtime-awareness](docs/specs/2026-06-07-runtime-awareness-and-review-discipline.md) |
+| **Run from anywhere / uninstall** | `link`/`unlink` onto PATH; global uninstall that keeps the memory store | [version-and-uninstall](docs/specs/2026-06-07-version-and-uninstall.md) |
+
+## Workplans (not features)
+
+A few `docs/specs/` entries are multi-agent *workplans / audits*, not single features —
+they record direction, and their individual items landed across the capabilities above:
+
+- [2026-06-08-harness-perfection-workplan](docs/specs/2026-06-08-harness-perfection-workplan.md)
+- [2026-06-08-opencode-feature-coverage](docs/specs/2026-06-08-opencode-feature-coverage.md)
+- [2026-06-08-tui-professional-workplan](docs/specs/2026-06-08-tui-professional-workplan.md)
+
+## Exploratory archive
+
+`docs/superpowers/` held early implementation *plans* for the web console (and the
+"Cultivar" re-skin) written in a checkbox-driven planning format. The work they
+describe has since shipped (see the **Web console** row above); like the specs, that
+folder is now a local working area — git-ignored, kept as history on the authoring
+machine only.

package/adapters/bob/README.md

@@ -0,0 +1,100 @@
+# 🤖 IBM Bob adapter
+
+> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+
+[IBM Bob](https://bob.ibm.com) is **Claude-Code-shaped**: a project `.bob/`
+layer, an `AGENTS.md` instructions file, `SKILL.md` skills, subagents, and a
+`settings.json` that also carries `mcpServers`. So the Bob emit **reuses the
+Claude engine** verbatim — only the marker dir (`.bob`) and the instructions
+filename (`AGENTS.md`) change. There is nothing to install by hand: `geneseed
+setup` (or `geneseed build --emit bob` / `--emit bob-global`) writes everything.
+
+This page documents the two verified **Bob-isms** the engine handles, and one
+limitation to be aware of on a shared repo.
+
+## What the emit writes
+
+### Per-repo (`--emit bob`)
+
+- **`AGENTS.md`** at the repo root — auto-loaded by Bob, carries the harness
+  preamble as a delimited **managed block** (your prose around it survives a
+  re-emit; the block is replaced, never stacked).
+- **`.bob/`** layer:
+  - `agents/<name>.md` — the **Claude subagent dialect** verbatim (`name` +
+    `description` + a `disallowedTools:` denylist for read-only agents).
+  - `skills/<name>/SKILL.md` — **byte-identical** to every other host; skills
+    are model-invoked via the `skill` tool.
+  - `rules/geneseed.md` — a **slim shadow stub** (see *Bob-ism 1* below).
+  - `settings.json` — Geneseed's lifecycle hooks + any `mcpServers` you wire.
+  - `memory/`, `notebook/` stores + their indices.
+
+### Global (`--emit bob-global` → `~/.bob`, or `$BOB_CONFIG_DIR`)
+
+Self-contained under `~/.bob`: agents, skills, `settings.json`, memory and
+notebook. **No `AGENTS.md` is written** — a global `~/.bob/AGENTS.md` is *not*
+auto-loaded by Bob, so the preamble rides `rules/geneseed.md` instead (Bob's
+always-injected channel). An `AGENTS.md` left by an older install is removed on
+re-emit.
+
+## Bob-ism 1 — the preamble rides `rules/geneseed.md`
+
+Only a **project-root `AGENTS.md`** is auto-loaded; a global one is not. So:
+
+- at **global** scope the *full* preamble is written to
+  `~/.bob/rules/geneseed.md` (with `../`-prefixed pointers, since the rules file
+  sits one level down from the `laws/`/`memory/` stores);
+- at **project** scope the root `AGENTS.md` already carries the preamble, so
+  `.bob/rules/geneseed.md` is a **slim stub** whose only job is to *shadow* the
+  global rules file by filename.
+
+This same-named workspace rule **is** Bob's project-bypasses-global mechanism:
+the workspace copy wins over the global one, so a project install suppresses the
+global voice without re-paying the preamble's per-turn token cost. (Because this
+is filename-shadowing, Bob never needs Claude's `claudeMdExcludes` — see
+*Bob-ism 2*.) A **global** emit warns, non-blocking, when project Bob installs
+already exist, since both preambles may load together in those repos unless
+Bob's precedence is honoured.
+
+## Bob-ism 2 — no `claudeMdExcludes`
+
+`claudeMdExcludes` is a Claude-Code-only knob with unknown Bob semantics, so Bob
+never gets one; the `rules/geneseed.md` shadow above covers the same
+project-bypasses-global need. An older Bob install that wrote a stale exclude is
+**self-healed** (the entry is removed) on the next emit.
+
+## Hooks — best-effort
+
+The `settings.json` hooks use the **Claude dialect** (a `PreToolUse:Bash`
+git-gate for Rule XX consent, `SessionStart` context injection, and
+`Stop`/`SubagentStop` learn/memory capture — the same three `harness.py`
+subcommands the OpenCode plugins drive). Bob's hook execution is **unverified**:
+if Bob honours Claude-shaped hooks they fire; if not, they are inert and the
+harness still works fully through the `AGENTS.md`/`rules` preamble prose. This is
+the same behaviour-contract parity every non-OpenCode host gets — the mechanism
+differs, the discipline does not.
+
+### ⚠️ Shared-repo caveat
+
+At **project** scope the hooks land in `.bob/settings.json`, and Bob documents no
+personal `settings.local.json` variant (Claude uses one precisely to keep this
+out of shared git). Those hook commands name the **per-user hook shim**
+(`~/.geneseed/bin/geneseed-hook`) — no longer this machine's interpreter and
+checkout, but still a path under *your* home, and now also OS-specific (`.cmd` on
+Windows, extensionless elsewhere). If you commit `.bob/settings.json`, a teammate
+still inherits hooks pointing at a path they do not have. **Add
+`.bob/settings.json` to `.gitignore`** on a team repo, or keep the Bob install
+personal/global.
+
+## MCP
+
+MCP servers are wired at runtime by `geneseed mcp` into the `mcpServers` key of
+the relevant `settings.json` (`.bob/settings.json` per-repo, `~/.bob/settings.json`
+global) — see [`geneseed mcp`](../../README.md) and `rituals/_harness_mcp.py`.
+
+## What Bob does not get
+
+Bob rides the Claude engine, so — like Claude — it has no OpenCode-only extras:
+colour themes, JS plugins, the saved-workflow runner, the primary-agent
+orchestrator, LSP enablement, or the `/`-command layer. Those capabilities have
+no analogue on a Claude-shaped host; the harness discipline is carried by the
+preamble and skills instead. See the [host matrix](../../README.md#-supported-harnesses).

package/adapters/claude-code/README.md

@@ -0,0 +1,101 @@
+# 🪝 Claude Code adapter
+
+> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [OpenCode adapter](../opencode/README.md)
+
+Optional. Claude Code supports lifecycle **hooks**, so a team using it can make
+parts of the harness fire automatically instead of relying on agent
+self-discipline.
+
+## Install
+
+Merge [`settings.json`](settings.json) into your repo's `.claude/settings.json`.
+(Not your *user* settings: the hook commands are repo-relative — `node
+bin/geneseed-hook.mjs …` — so at user scope they would fire and fail in every
+repo that doesn't vendor the harness. A generated global install wires
+absolute-path hooks instead — `geneseed setup` does that for you.) It:
+
+- on **PreToolUse** (matcher `Bash`), runs `harness git-gate` — a tool-boundary
+  backstop for Rule XX (*consent before every commit and push*). The hook inspects the
+  command and, when it runs a `git commit` or `git push` (bare, flagged, `-C <path>`,
+  or chained like `git add . && git commit … && git push`), returns
+  `permissionDecision: "ask"` so Claude Code **prompts on every such call**. Crucially
+  this is **not** suppressible by a one-time *"Yes, and don't ask again"*: the allow
+  rule that choice writes is only consulted *after* the hook runs, so the hook re-asks
+  next time regardless. Every other Bash command (and any unreadable payload) is
+  deferred to the normal permission flow — the hook never blocks unrelated work.
+
+  **Caveat — the GitHub MCP vector.** The hook matches the `Bash` tool only. If your
+  session has the GitHub MCP server, an agent can commit/push via `push_files` /
+  `create_or_update_file` / `merge_pull_request`, which bypass Bash. To gate those too,
+  widen the matcher to `"Bash|mcp__github__.*"` — `git-gate` ignores any payload it
+  doesn't recognise as a commit/push, so over-matching the tool surface is harmless.
+- on **SessionStart** (`startup`/`clear` only — a fresh context), prints `AGENT.md`
+  so the harness is in context from the first turn, then runs `harness context` to
+  **inject the project context** directly into the session — so Rule XVIII is enforced
+  by the hook, not left to the agent to remember (lazy entries are only listed). On
+  **`resume`** it runs `harness context` *without* re-`cat`ting `AGENT.md`: the resumed
+  conversation already carries the harness, so re-injecting the static file each resume
+  is pure token waste — only the (possibly changed) project context is refreshed;
+- on **Stop**, runs `harness learn` over the session to capture durable memories.
+  Claude Code pipes the hook payload (with the session's `transcript_path`) to the
+  command on stdin; `learn` reads that, flattens the transcript, distils new
+  memories, and **writes them into the bundle's `memory/` while updating
+  `MEMORY.md`** — deduping against what is already stored. No `< /dev/null` and no
+  redirection: the stdin payload is the whole point.
+- on **SubagentStop**, runs the *same* `harness learn` command. `learn` reads the
+  payload's `hook_event_name`, sees a subagent dispatch, and routes it to the
+  per-agent lesson path instead of the shared store: it distils at most one durable
+  lesson and appends it to `memory/agents/<agent-name>.md` (capped, newest kept). If
+  the payload does not name the subagent, the step is a silent no-op — never a
+  crash, never a wrong write. This is the parity twin of the OpenCode learn plugin's
+  child-session branch.
+
+  This step is **opt-in on a model CLI**: set `GENESEED_LLM` (e.g. `claude -p`,
+  `llm`, `ollama run …`) for `learn` to actually distil. With it unset the hook is
+  a harmless no-op that just prints the prompt. Geneseed never embeds an API key.
+  If your bundle's `memory/` is not at `./memory` or `./Harness/memory`, point at
+  it with `GENESEED_MEMORY=/abs/path/to/memory`.
+
+Adjust the paths if your harness bundle is not at the repository root. On Windows
+the commands are identical (`node bin/geneseed-hook.mjs …`).
+
+Why inject rather than instruct? Rule XVIII tells the agent to read the project
+context at startup, but startup rituals are exactly what agents skip. The
+`harness context` hook removes the choice: the eager files' contents land in
+context before the first turn regardless of agent discipline. On tools without
+hooks or plugins, the AGENT.md prose still carries the rule.
+
+> **Auto-discovery (parity with OpenCode).** `harness context` no longer needs a
+> hand-filled `context.json`: with no manifest (or just the empty stub) it
+> **auto-discovers the repo's docs by convention** — root `AGENTS.md`/`AGENT.md`/
+> `CLAUDE.md`/`README.md`/`CONTRIBUTING.md` injected eager, `docs/`/`adr/`/monorepo
+> package READMEs listed lazy — using the same convention as the OpenCode context
+> plugin. A `context.json` still overrides, and `"extend": true` layers a manifest
+> on top of discovery.
+
+## Bundled skill — `herdr`
+
+The canonical herdr skill lives in the Geneseed source tree at
+[`src/skills/herdr.md`](../../src/skills/herdr.md). The build renders it into
+every emit — `.opencode/skills/herdr/SKILL.md` for OpenCode hosts, the
+portable bundle for everyone else — so a deployed harness picks it up
+automatically alongside every other Geneseed skill.
+
+A copy is also kept at
+[`.claude/skills/herdr/SKILL.md`](../../.claude/skills/herdr/SKILL.md) so Claude
+Code running **inside this repo** (i.e. people working on Geneseed itself)
+discovers it directly, since the build doesn't write into `.claude/`. The two
+copies share content; keep them in sync when you edit either.
+
+Either way, you only need:
+
+- the **`herdr` binary** on your `PATH` (install via [herdr.dev](https://herdr.dev)),
+- the agent launched **inside a herdr pane** — the skill self-gates on
+  `HERDR_ENV=1` and stays silent everywhere else, so shipping it is harmless
+  for users who don't run herdr.
+
+## Other tools
+
+This adapter is Claude-Code-specific. On tools without hooks, the harness still
+works fully via the instructions in `AGENT.md` — the hooks are a convenience, not
+a requirement.

package/adapters/claude-code/settings.json

@@ -0,0 +1,47 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "node bin/geneseed-hook.mjs git-gate" }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "node bin/geneseed-hook.mjs rule-gate" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|clear",
+        "hooks": [
+          { "type": "command", "command": "node -e \"process.stdout.write(require('fs').readFileSync('AGENT.md','utf8'))\"" },
+          { "type": "command", "command": "node bin/geneseed-hook.mjs context" }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          { "type": "command", "command": "node bin/geneseed-hook.mjs context" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node bin/geneseed-hook.mjs learn || exit 0" }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node bin/geneseed-hook.mjs learn || exit 0" }
+        ]
+      }
+    ]
+  }
+}

package/adapters/claude-code/skills/geneseed/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: geneseed
+description: "Interact with a deployed Geneseed harness from any repo — locate the install, read its laws/agents/skills/memory/notebook by name, run status/doctor/diff, distill memory with learn, and manage the local web UI. Use when the user mentions Geneseed, AGENT.md, the harness, an agent operating system, or asks you to inspect, refresh, or read from the deployed bundle."
+---
+
+# geneseed — agent skill
+
+Geneseed is a portable AI-agent harness deployed once and used everywhere. This skill lets you talk to whichever deployment is in scope from any repo: read the canonical files (laws, agents, skills, memory, notebook), probe state (status, version, doctor, diff), distill durable memory, and drive the local web UI. The harness is theme-independent in structure — directory and section names are always plain English — so the paths below are stable across themes.
+
+## Find the deployed harness before doing anything
+
+Pick the first that resolves; remember the path for the rest of the session.
+
+1. `command -v geneseed` — if the launcher is on PATH, use it. The CLI knows its own install and is the source of truth for `status`, `version`, `doctor`, etc.
+2. `$GENESEED_HARNESS` — if set, that directory is the deployment root.
+3. `~/.config/opencode/AGENT.md` — the default OpenCode global install.
+4. `./.opencode/AGENT.md` (walking up from `pwd`) — a per-repo OpenCode install.
+5. Any `AGENT.md` in the repo root — a plain bundle install.
+
+If none resolve, the user does not have Geneseed deployed here — say so and stop. Do not run `setup`, `build`, or `upgrade` on your own to "fix" this; that is a user decision.
+
+A live harness root contains: `AGENT.md`, `agents/<name>.md`, `skills/<name>/SKILL.md`, `memory/MEMORY.md`, `notebook/NOTEBOOK.md`, `themes/`, and (on OpenCode) `plugins/`, `workflows/`, `opencode.jsonc`, `wiki.jsonc`. Laws live as numbered sections inside `AGENT.md`, not as separate files in the deployed bundle — read them from `AGENT.md` directly.
+
+## Read-only verbs (safe, no confirmation needed)
+
+- **Inventory** — `ls <harness>/agents`, `ls <harness>/skills`, `ls <harness>/memory`, `ls <harness>/notebook`. Counts also appear in `geneseed status`.
+- **Status** — `geneseed status`. One-screen dashboard: theme, install mode, component counts, memory path & fact count, version fingerprint, whether `AGENT.md` is present, and whether the install matches its source.
+- **Version** — `geneseed version`. Source vs installed fingerprint; `up to date` / `differs` / `unknown source`.
+- **Doctor** — `geneseed doctor`. Health check on every theme + parity + links + drift. Exit 0 means `ok`.
+- **Diff** — `geneseed diff` (or `geneseed diff --out FILE`). Shows local edits the agent has made in the deployed bundle vs the canonical source; the same content the TUI shows under *Review local edits*. Useful to find drift worth back-porting into `src/` of the Geneseed repo.
+- **Prompt** — `geneseed prompt`. Prints the install prompt Geneseed uses to ask an external agent to recreate the bundle by hand. Safe to read; do not pipe it into another agent unless the user asks.
+- **Read a specific piece** — read the file directly:
+  - Agent by name: `<harness>/agents/<name>.md`
+  - Skill by name: `<harness>/skills/<name>/SKILL.md`
+  - Law by number: section `## N. …` inside `<harness>/AGENT.md`
+  - Memory fact: `<harness>/memory/<file>.md`; index at `MEMORY.md`
+  - Notebook entry: `<harness>/notebook/<file>.md`; index at `NOTEBOOK.md`
+
+When the user asks "what does the X skill say" or "what's law VI", read the file directly — do not summarise from memory.
+
+## Side-effecting verbs (confirm with the user first)
+
+- **`geneseed learn`** — distills the current session into memory under `<harness>/memory/`. Writes new files and may update `MEMORY.md`. Confirm before running, and only at end-of-session or when the user explicitly asks.
+- **`geneseed context`** — refreshes the project-docs context manifest. Touches `context.json` in the current repo. Confirm before running.
+- **`geneseed web start`** / **`stop`** / **`status`** — manages the local web UI daemon on `127.0.0.1:4747` (offline, per-session token). `status` is read-only; `start`/`stop` need user assent. Use `start` only if the user asks to "open the web UI" or similar.
+
+## Hard no without explicit user ask
+
+These are destructive or scope-changing and must be initiated by the user:
+
+- `geneseed setup` — interactive install wizard.
+- `geneseed build` — re-renders the bundle from `src/` (only meaningful inside the Geneseed source repo anyway).
+- `geneseed upgrade` / `bootstrap` / `update` / `sync-self` — pull-and-rebuild from the published source; overwrites the deployed bundle. Local edits are auto-exported to an `improvements/` markdown beside the install before being overwritten, but still: user decision.
+- `geneseed link` / `unlink` — modifies PATH symlinks.
+- `geneseed uninstall` — removes a global or per-repo (project-scoped) install.
+
+If the user asks for any of these, run them as requested. Do not run them as a side effect of a more general request.
+
+## Common patterns
+
+- **"What harness do I have here?"** — `geneseed status` (if launcher on PATH); else resolve via the fallback list and report theme, install mode, path, and version.
+- **"What does the `<X>` skill / agent / law say?"** — read the file directly. For laws, grep `AGENT.md` for `## N\.` or `Law N`.
+- **"Show me what's drifted in my install."** — `geneseed diff`. Offer to write the output to a file (`--out`) if it's long.
+- **"Distill what we did today into memory."** — confirm scope, then `geneseed learn`. Afterwards, `git status` inside the harness dir to show what landed.
+- **"Open the dashboard / web UI."** — `geneseed web start`. Tell the user the URL it printed and that it binds to localhost only.
+- **End-of-session check-in** — if the user is wrapping up and there's something memorable, offer `geneseed learn`; if there are edits the agent made to the deployed bundle, offer `geneseed diff` so they can back-port them.
+
+## Notes
+
+- The launcher is `./geneseed` in the Geneseed source repo and plain `geneseed` once linked. Inside a non-Geneseed repo, only the linked form is available — if it's not on PATH, you cannot drive the CLI and must fall back to reading the deployed files directly.
+- The deployed bundle's directory and section names are theme-independent; only voice (descriptions, prose, sigils) changes per theme. Don't pattern-match on flavor words.
+- `memory/` and `notebook/` are personal and git-ignored. Anything you write there with `learn` does not leave the user's machine.

package/adapters/copilot/README.md

@@ -0,0 +1,76 @@
+# 🐙 GitHub Copilot adapter
+
+> [← Back to README](../../README.md) · [Setup guide](../../SETUP.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+
+[GitHub Copilot](https://docs.github.com/copilot) is the **second Claude-shaped
+host**, and a closer fit than Bob: skills are the same `SKILL.md` dirs (Copilot
+Agent Skills), custom agents are markdown-with-frontmatter, and the repo-root
+`AGENTS.md` is auto-loaded. So the Copilot emit **reuses the Claude engine** with
+a `host="copilot"` flag. Nothing to install by hand: `geneseed setup` (or
+`geneseed build --emit copilot` / `--emit copilot-global`) writes everything.
+
+Copilot is a **deliberately reduced host** — it has no hook mechanism — so this
+page is mostly about *what it does not automate* and why the harness still holds.
+
+## What the emit writes
+
+### Per-repo (`--emit copilot`)
+
+- **`AGENTS.md`** at the repo root — auto-loaded by the Copilot CLI, the coding
+  agent, and VS Code agent mode. Carries the preamble as a managed block.
+- **`.github/`** layer (Copilot's *shared* repo config surface):
+  - `agents/<name>.agent.md` — Copilot's **custom-agent dialect** (`.agent.md`
+    extension; a `tools:` **allowlist**, not Claude's denylist — a read-only
+    agent lists the tool ids it keeps: `read, search, todo, agent`, plus
+    `execute` only when the spec opts in with `<!-- bash: allow -->`). Sibling
+    agent links are rewritten to the `.agent.md` filename.
+  - `skills/<name>/SKILL.md` — **byte-identical** to every other host.
+
+  Writing into the shared `.github/` dir is safe because the engine's manifest +
+  claim-on-create machinery never touches a file it doesn't own — your own
+  workflows, agents, and skills there are never clobbered, and uninstall removes
+  only manifest-owned files.
+
+### Personal / global (`--emit copilot-global` → `~/.copilot`, or `$COPILOT_CONFIG_DIR`)
+
+- **`copilot-instructions.md`** — the Copilot CLI auto-loads this in every repo;
+  the preamble rides it as a managed block. (Unlike Bob, Copilot *has* a real
+  personal instructions carrier, so no rules-folder workaround is needed.)
+- `agents/<name>.agent.md` + `skills/` under `~/.copilot`.
+
+## No hooks — the reduced-host reality
+
+Copilot has **no `settings.json` and no lifecycle-hook mechanism**, so the whole
+settings/hooks/excludes stage is skipped. Concretely, Copilot does **not** get:
+
+- **automated context injection** — Rule XVIII's project-context load falls back
+  to the preamble instructing the agent to read the docs itself;
+- **automated memory / learn write-back** — no `Stop`/`SubagentStop` hook; the
+  memory convention rides the preamble's instructions (the agent writes its own
+  memories) rather than a session-end distiller;
+- **the git-gate consent backstop** — Rule XX (*consent before every commit and
+  push*) is enforced by the **preamble prose only**, not at the tool boundary.
+  There is no hook to force the prompt;
+- **sovereign-repo excludes** — Copilot documents no exclude/shadow mechanism
+  (nothing like Claude's `claudeMdExcludes` or Bob's same-named workspace rule),
+  so a global install's `copilot-instructions.md` and a repo's own `AGENTS.md`
+  simply **stack**. A global emit warns, non-blocking, when project Copilot
+  installs already exist.
+
+None of this is a build gap — it is Copilot's ceiling. The harness still applies
+in full: every Rule, agent, and skill is present; only the *automation* of a few
+Rules degrades to instruction-only. This is behaviour-contract parity, the same
+principle every non-OpenCode host follows.
+
+## MCP
+
+MCP servers are wired at runtime by `geneseed mcp` into `~/.copilot/mcp-config.json`
+(with a `tools` allowlist) — see `rituals/_harness_mcp.py`.
+
+## What Copilot does not get
+
+As a Claude-shaped host Copilot has none of the OpenCode-only extras (colour
+themes, JS plugins, workflow runner, primary-agent, LSP, `/`-commands), **and**
+— uniquely among the four hosts — none of the hook-driven automation Claude and
+Bob get. See the [host matrix](../../README.md#-supported-harnesses) for the full
+comparison.