geneseed 3.17.0 → 3.19.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.19.0] — 2026-10-09
+
+### Added
+- Doctrine comms 3, Declare the Judgment Calls: after non-trivial work the agent lists the choices it made alone where a reasonable alternative existed, with the alternative set aside and whether it is cheaply reversible, riskiest first (data, security, production, public interfaces). Only genuine forks count, trivial work owes an empty list, and it never covers a call Echo the Intent says to ask about first. Reviewers read where the agent guessed instead of everything, or nothing. The idea is Victor Rentea's (Devoxx BE 2026, "Responsibly Dimming the Lights in the Software Factory"). It is in the toggleable comms pack, not a law, per DESIGN.md Decision 7; the full-footprint size ceiling rises by 205 characters for it. `explain-changes` now lists these calls among its risks.
+- Reviews apply the nearest `REVIEW.md`: a repo states how its code is judged in a file read only at review time, so the coding context stays lean. The file closest to each changed file wins (folder, then root, then `CODING_STANDARDS.md` / `CONTRIBUTING.md`, then Geneseed's defaults, format included), and it never lifts a law. `geneseed-code-review` and the reviewer agent load it, `ship` runs a review before opening a pull request and stops on a blocking finding, and `review-response` is the only skill that writes it, on your word. One sentence in the always-on core makes host built-in reviews apply it too.
+- `geneseed-code-review` flags architecture drift: when `docs/architecture.md` draws C4 and a diff adds, removes or rewires a container without touching the diagram, it raises a non-blocking issue pointing at `document-project`.
+
+### Changed
+- `roast-me` now attacks your own ask, plan, idea or writing, premise first, and no longer critiques code. Code and diffs, "roast my code" included, go to `geneseed-code-review`, which keeps its findings unsoftened when asked to roast.
+- `daydream` and `react-view-transitions` are user-only: they answer `/daydream` and `/react-view-transitions`, but the agent no longer starts them on its own and their descriptions leave the always-on list.
+- `parallel-agents` and `pipeline` name their boundary: independent units side by side versus a relay in one worktree where each agent builds on the previous one's output.
+
+### Repository
+Not in the package; how Geneseed itself is built and checked.
+- The weekly scorecard run also scores the tree with `geneseed scorecard` and fails when any check differs from the upstream Python tool, so the port cannot drift in silence. The web CI job calls prettier and vitest directly, which the scorecard can see (95.3, 30 of 31 checks).
+- README: the scorecard card sits above "Why Geneseed", the badge takes the upstream look, and the laws badge also counts doctrine rules.
+
+## [3.18.0] — 2026-10-09
+
+### Added
+- `geneseed scorecard [path]` scores the repo a harness is installed in — its CI, tests and docs, not the harness files — with the AI Harness Scorecard's 31 checks and five weighted pillars, ported to JavaScript (no Python). It prints the grade, each pillar and every failing check with its fix, and always exits 0. `--json` gives the raw result; `--svg PATH` writes a grade-and-pillars card (light and dark) and prints the matching badge URL.
+- Skills can carry side files: `src/skills/<name>/<file>.md` is emitted beside the skill's `SKILL.md` on every host and read only when the skill points at it. `debug` moves its CI section and `rule` its memory consolidation into side files, so each costs about 0.5k tokens less per use.
+
+### Changed
+- Fewer, sharper skills: 56 become 47. `dependencies` replaces `deps-audit` and `migrate`, `bruno` replaces `bruno-collection-generator` and `bruno-test-writer`, and `git-history` replaces `git-archaeology` and `git-rescue`. `document-project` absorbs `repo-map`, `codebase-design` absorbs `domain-modeling` (the glossary is now `GLOSSARY.md`, `CONTEXT.md` still read), `debug` absorbs `ci-fix`, `rule` absorbs `consolidate-memory`, and `geneseed` absorbs `opencode-theme`. Every old name still works as a user-only `/name` alias of its new home, and so does `/grill-me` for `brainstorm`; an old name in `--exclude-skills` excludes the skill that absorbed it. Excluding one half of a merged pair (say `deps-audit`) now excludes the whole merged skill (`dependencies`, which also covers `migrate`). Parts of brainstorm, codebase-design, debug, develop, prototype, ship, wayfinder, parallel-agents, rule and geneseed-code-review adapt ideas from Matt Pocock's skills (github.com/mattpocock/skills, MIT).
+- The wiki manifest is now `geneseed-wiki.jsonc`, so a shared `.claude/` or `.opencode/` folder shows who owns it. The next build or upgrade renames an existing `wiki.jsonc` (or older `wiki.json`) to the new name with its contents untouched, and adds the new name to a `.gitignore` that listed the old one. Until then the hook, the OpenCode plugins and the web console still read `wiki.jsonc`; that fallback goes in the release after 3.18.0. `GENESEED_WIKI` is unchanged.
+- `document-project` and the docs agent default to Markdown. AsciiDoc is used only when you ask for it or the project's docs are already `.adoc`; the skill no longer proposes a switch on its own.
+- `upgrade` and `migrate` print the alias and retired-name notices that `rebuild-all` already printed. `codebase-design` now triggers on "where should the seam go".
+
+### Removed
+- The `tickets` skill, with no alias: `wayfinder` charts the decisions and hands execution to `plan`, sliced into thin end-to-end pieces. A `tickets` entry in `--exclude-skills` is dropped with a notice.
+
+### Repository
+Not in the package; how Geneseed itself is built and checked.
+- `SECURITY.md`, `CODEOWNERS`, a PR template and a weekly advisory scorecard run; `ARCHITECTURE.md` and decision records under `docs/adr/`.
+- CI: a blocking `npm audit --audit-level=high` job, Dependabot, conventional PR titles (commitlint), `tsc --noEmit` with `checkJs` over `js/` and `bin/` (`npm run typecheck`), coverage with `c8`, a `lychee` link check, and the doctor scorecard ratchet with the README card and badge.
+- Tests: fast-check property tests on the settings parser, a `fuzz/` target that drives the hook gates through the real entry point, and a weekly Stryker run. The mutation matrix runs on Windows, where two of its rows are real defects, and installs its devDependencies first.
+- ESLint bans `eval`, implied eval, `new Function` and thrown literals in product code. Toolchain and web dependencies bumped by Dependabot (`web/dist` rebuilt).
+
 ## [3.17.0] — 2026-10-08
 
 ### Added

package/DESIGN.md

@@ -44,7 +44,7 @@ vault or a specific tool's hooks.
      and the prose words the docs use: the core nouns `LAW(S)`/`DOCTRINE(S)`/`ONTOLOGY`/
      `AGENT(S)`/`SKILL(S)`/`MEMORY`/`NOTEBOOK`/`VAULT`/`WIKI`, plus `TAGLINE`,
      `LOADED_SIGIL`, `EPI_*`, `BENEDICTION`, `DESC_*`, `ROAST_PERSONA`, the invariant
-     titles `LEX_<ID>`, the 28 doctrine-rule titles `DOC_<ID>` (keyed by stable rule id), the five pack
+     titles `LEX_<ID>`, the 29 doctrine-rule titles `DOC_<ID>` (keyed by stable rule id), the five pack
      names `PACK_CRAFT`/`PACK_RIGOR`/`PACK_OPS`/`PACK_PROCESS`/`PACK_COMMS`, and the section intros
      `INTRO_*`. Each theme defines its own nouns; **neutral keeps the plain words** (Rule,
      Doctrine, Agent, Skill, Memory, Workspace), so neutral output is unchanged.

package/README.md

@@ -6,17 +6,18 @@
 
 [![npm](https://img.shields.io/npm/v/geneseed?color=cb3837&logo=npm)](https://www.npmjs.com/package/geneseed)
 [![CI](https://github.com/Arylmera/Geneseed/actions/workflows/ci.yml/badge.svg)](https://github.com/Arylmera/Geneseed/actions/workflows/ci.yml)
+[![AI Harness Scorecard](https://img.shields.io/badge/AI%20Harness%20Scorecard-A%2095.3%2F100-brightgreen)](#ai-harness-scorecard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
-[![Skills](https://img.shields.io/badge/skills-56-blueviolet)](src/skills/)
+[![Skills](https://img.shields.io/badge/skills-47-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
-[![Laws](https://img.shields.io/badge/laws-9-critical)](src/laws/universal.md)
+[![Laws and doctrines](https://img.shields.io/badge/laws-9%20%2B%2029%20doctrines-critical)](src/doctrines/)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · OpenClaude · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20OpenClaude%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
 
-[**Why**](#-1--why-geneseed) · [**Setup**](#-2--setup) · [**Web & terminal**](#-3--web--terminal) · [**What you get**](#-4--what-you-get)
+[**Why**](#-1--why-geneseed) · [**Setup**](#-2--setup) · [**Web & terminal**](#-3--web--terminal) · [**What you get**](#-4--what-you-get) · [**Harnesses**](#-supported-harnesses) · [**Docs**](#-documentation)
 
 </div>
 
@@ -43,6 +44,12 @@ A hand-written instructions file is prose the model may or may not honour, copie
 
 This page is the overview. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — a short course on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
 
+### Scored, not claimed
+
+<p align="center"><a href="#ai-harness-scorecard"><img src="docs/assets/scorecard.svg" alt="AI Harness Scorecard for this repository: grade and score, with one bar per pillar" width="760"></a></p>
+
+<p align="center"><sub>31 deterministic checks, no LLM — <a href="#ai-harness-scorecard">how this is scored, and how to score your own repo</a></sub></p>
+
 ---
 
 ## 🧬 1 · Why Geneseed
@@ -164,11 +171,11 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 | **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
 | **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
 | **🤖 Agents** (18) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `researcher`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
-| **🛠 Skills** (56) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
+| **🛠 Skills** (47) | repeatable workflows: brainstorm · plan · **codebase-design** · **wayfinder** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno** · geneseed-code-review · **fresh-eyes** · **security-audit** · **dependencies** · **review-response** · commit · **ship** · **release** · **git-history** · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **skill-forge** · **herdr** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
 | **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
 | **📓 Notebook** (`notebook/`) | the agent's sovereign space — any medium (code, tools, data, notes), self-ruled via a seed-once charter, always git-ignored; only its `.gitignore` is build-asserted |
-| **🌐 Wiki** (`wiki.jsonc`) | your own machine-wide knowledge base — typically an Obsidian vault — declared once per machine: entry notes load eager/lazy, the agent reads and **writes** it under the vault's own conventions, with an inbox fallback and guard-enforced protected folders |
+| **🌐 Wiki** (`geneseed-wiki.jsonc`) | your own machine-wide knowledge base — typically an Obsidian vault — declared once per machine: entry notes load eager/lazy, the agent reads and **writes** it under the vault's own conventions, with an inbox fallback and guard-enforced protected folders |
 | **🧭 Context** | the project's own docs — auto-discovered on OpenCode, or via a `context.json` manifest |
 
 ### 🤝 What the harness asks of you
@@ -291,6 +298,17 @@ node --test --test-reporter=tap "tests/**/*.test.mjs"   # the suites (node expan
 
 `doctor` checks each theme for unresolved tokens, dead/non-hermetic links, theme-key parity, author-time gates (every spec has a purpose line, the plugins parse, the learn-prompt literal stays extractable), and that a committed bundle still matches a fresh render of `src/`. CI (`.github/workflows/ci.yml`) runs both on every push and PR, on both Linux and Windows. Publishing is a separate, manually-triggered workflow (`.github/workflows/publish.yml`) — see [Contributing](#-contributing).
 
+### AI Harness Scorecard
+
+The card [at the top of this page](#scored-not-claimed) measures how safe this repository is to change with agents. It comes from the [AI Harness Scorecard](https://github.com/markmishaev76/ai-harness-scorecard): 31 deterministic checks, no LLM, in five weighted pillars. Geneseed ships its own JavaScript port, so you can score any repository a harness is installed in — it grades the repository (CI, tests, docs), not the harness files:
+
+```bash
+geneseed scorecard            # grade, one line per pillar, and what to fix
+geneseed scorecard --json     # every check with its evidence
+```
+
+`geneseed scorecard --svg docs/assets/scorecard.svg` rewrites the card and prints the badge URL for the top of this page; `doctor` fails when either no longer matches the live score, and the checks this repository passes are a floor it may not drop below. A weekly workflow also runs the upstream Python tool as a cross-check.
+
 ## 🔄 Keeping it current
 
 **Installed from npm** — one command, and it rebuilds every active install for you:

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, 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: **3.17.0**.
+> string. Current label: **3.19.0**.
 
 ## Capabilities
 
@@ -29,7 +29,7 @@ Every row below is present in the tree today; "Spec" names 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** | 9 laws, 18 agents, 56 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
+| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 47 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
 | **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |
@@ -40,7 +40,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | **Host hooks, per dialect** | Every host gets the hook surface its runtime offers, spoken in that runtime's own verdict dialect via `--host`: Claude Code asks (`permissionDecision`), OpenClaude asks exactly as Claude does (a Claude Code fork, under `~/.openclaude` / `.openclaude/`), Bob refuses by exit code 2 (five Claude-named events, nested `~/.bob/settings/settings.json`, no subagent event), OpenCode's guard throws. Laws I/IV are the hard tier everywhere; the consent rules ask where a host can ask and warn where it cannot. `tool-gate` fuses the two gates for hosts that run one command per event; `PreCompact` runs `learn` before Claude compacts; every block or ask lands in `notebook/gates.jsonl` on every host | [bob](adapters/bob/README.md) · [claude-code](adapters/claude-code/README.md) · [candidate hosts](docs/candidate-hosts.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 | `2026-06-09-opencode-workflow-primitive` |
 | **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 `SubagentStop`; Bob has no subagent event); `learn --consolidate` rebuilds the index | `2026-07-04-orchestration-memory-upgrade` |
-| **Wiki integration** | Machine-wide knowledge base (`wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | `2026-06-11-wiki-knowledge-base` |
+| **Wiki integration** | Machine-wide knowledge base (`geneseed-wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | `2026-06-11-wiki-knowledge-base` |
 | **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 | `2026-07-12-collaboration-layer` |
 | **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. Doctrine process 1 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 | `2026-07-30-rule-front-door` |
 | **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` | `2026-07-31-entity-registry` |

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

@@ -19,7 +19,7 @@ Pick the first that resolves; remember the path for the rest of the session.
 
 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`, `ontology/universal.md`, `laws/universal.md`, `doctrines/<pack>.md`, `agents/<name>.md`, `skills/<name>/SKILL.md`, `memory/MEMORY.md`, `notebook/NOTEBOOK.md`, `themes/`, and (on OpenCode) `plugins/`, `workflows/`, `opencode.jsonc`, `wiki.jsonc`.
+A live harness root contains: `AGENT.md`, `ontology/universal.md`, `laws/universal.md`, `doctrines/<pack>.md`, `agents/<name>.md`, `skills/<name>/SKILL.md`, `memory/MEMORY.md`, `notebook/NOTEBOOK.md`, `themes/`, and (on OpenCode) `plugins/`, `workflows/`, `opencode.jsonc`, `geneseed-wiki.jsonc`.
 
 The constitution is **three tiers**: an always-on **Ontology** (four prose sections — Telos, Evidence, Decisions, Conduct), nine always-on **Rules** numbered I–IX, and the **Doctrines** — practice packs (`craft`, `rigor`, `ops`, `process`, `comms`) chosen per install at build time. `AGENT.md` carries all three inline (whole at the `full` footprint, heading-plus-first-line at `lean`), *and* the complete text ships as files beside it. All five pack files ship even when a pack was not built in, so a citation into an inactive pack still resolves on disk — which is why a question about a rule is answered from the tier file, never only from `AGENT.md`.
 

package/adapters/opencode/README.md

@@ -207,7 +207,7 @@ the harness live entirely in the global config dir with zero per-repo files.
   context needs re-pushing.
 - **Machine wiki (AGENT.md §8):** the same block carries a `MACHINE WIKI` segment
   for the user's own knowledge base(s) — typically an Obsidian vault — declared in
-  `wiki.jsonc` (`$GENESEED_WIKI` → `$GENESEED_HARNESS/wiki.jsonc` → beside the
+  `geneseed-wiki.jsonc` (`$GENESEED_WIKI` → `$GENESEED_HARNESS/geneseed-wiki.jsonc` → beside the
   install). Per wiki: eager entries inject in full, lazy entries list, and the
   `conventions` / `inbox` / `protected` metadata is surfaced — on the **same**
   budgets, compaction and transform paths as the project context. Schema and
@@ -385,7 +385,7 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
 - **Runtime guard plugin** (`geneseed-guard.js`, installed with the others). Enforces
   the safety Laws at the tool boundary: **blocks** writes to private-key/credential
   files (Sealed Secrets), catastrophic shell like `rm -rf /` (Deletion Is Deliberate), and any mutation under
-  a declared wiki's `protected` folders (AGENT.md §8, from `wiki.jsonc`); **warns** on
+  a declared wiki's `protected` folders (AGENT.md §8, from `geneseed-wiki.jsonc`); **warns** on
   `.env` writes and force-push. `GENESEED_GUARD=off` disables it, `=warn` downgrades
   blocks to warnings. Every **block** appends one line to the install's
   `notebook/gates.jsonl` (rule `law-1` / `law-4` / `process-1` / `wiki`, a timestamp,

package/adapters/opencode/plugins/geneseed-context.js

@@ -27,11 +27,11 @@
 //     is added per request, outside the cached block; unknown -> omitted.
 //
 // MACHINE WIKI (AGENT.md §8): the same block also carries the user's own knowledge
-// base(s) — typically an Obsidian vault — declared once per machine in `wiki.jsonc`
-// ($GENESEED_WIKI -> $GENESEED_HARNESS/wiki.jsonc -> beside this plugin's install).
+// base(s) — typically an Obsidian vault — declared once per machine in `geneseed-wiki.jsonc`
+// ($GENESEED_WIKI -> $GENESEED_HARNESS/geneseed-wiki.jsonc -> beside this plugin's install).
 // Each wiki's eager entries inject in full and lazy entries list, drawing on the
 // SAME budgets as the project context; its conventions/inbox/protected metadata is
-// surfaced so the agent knows the house rules before writing. No wiki.jsonc, or an
+// surfaced so the agent knows the house rules before writing. No wiki manifest, or an
 // empty `wikis` list, costs nothing.
 //
 // DELIVERY (invisible by default): the context rides into each request's message
@@ -159,8 +159,8 @@ const EAGER_ROOT = new Set([
   ".cursorrules", "README.md", "README.adoc", "CONTRIBUTING.md", "CONTRIBUTING.adoc",
   "user-rules.md", "PROFILE.md",
 ])
-// Project docs are Markdown or AsciiDoc (document-project writes AsciiDoc when a project has
-// none yet). Same set as js/hosts/hooks-context.mjs DOC_EXT.
+// Project docs are Markdown or AsciiDoc (document-project writes AsciiDoc when the user asks
+// for it). Same set as js/hosts/hooks-context.mjs DOC_EXT.
 const isDoc = (name) => /\.(md|adoc)$/i.test(name)
 // Doc trees walked recursively; everything found is lazy (listed, not injected).
 const LAZY_DIRS = ["docs", "doc", "documentation", "architecture", "adr", "ADR"]
@@ -178,14 +178,16 @@ async function isDir(p) { try { return (await fs.stat(p)).isDirectory() } catch
 // holds the installed AGENT.md: the repo root for a project install, the config dir for a
 // global one. Same list and seed hashes as SESSION_FILES/SEED_SHA256 in js/hosts/hooks.mjs;
 // tests/unit/claude.test.mjs gates both copies against SESSION_SEEDS in js/build/stubs.mjs.
-// context.json is not here: it is a manifest, honoured by resolveSource. wiki.jsonc is not
-// here either: the MACHINE WIKI block below already renders it in full.
+// context.json is not here: it is a manifest, honoured by resolveSource. geneseed-wiki.jsonc
+// is not here either: the MACHINE WIKI block below already renders it in full.
 const SESSION_FILES = ["user-rules.md", "PROFILE.md", "memory/MEMORY.md", "anamnesis/MEMORY.md",
   "notebook/NOTEBOOK.md"]
 const SEED_SHA256 = new Set([
   "5c2e92fb1acde041e02d9ebf158460d8ff7a07cbc2b447859631604610130721", // user-rules.md
   "29e012c3c4349ea62a9082cbd04bb25599a0ec280d62c33f6e10742809471816", // PROFILE.md
-  "cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8", // wiki.jsonc
+  "3a82c78ccc5d745033c16c354f5eda9d79350c704e9da8d605d380fb1e108d7a", // geneseed-wiki.jsonc
+  // The wiki seed before the rename: the build renames an untouched one byte for byte.
+  "cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8", // wiki.jsonc (legacy)
   "99c786049c260f6baf7aec68a5c0f59907861afe9b867da009440613bdddb907", // MEMORY.md
   "9acb5c9d9cb5dac572104480f05b48cc144e676869bd60e86d8a15b1f6308184", // NOTEBOOK.md
 ])
@@ -221,8 +223,8 @@ async function readJson(p) {
 }
 
 // Strip JSONC niceties — // and /* */ comments plus trailing commas — string-aware,
-// so a "https://…" or "C:/Users/…" inside quotes is untouched. wiki.jsonc is seeded
-// with a commented example, so its readers must tolerate comments.
+// so a "https://…" or "C:/Users/…" inside quotes is untouched. the wiki manifest is
+// seeded with a commented example, so its readers must tolerate comments.
 function stripJsonc(text) {
   let out = "", inStr = false, esc = false
   for (let i = 0; i < text.length; i++) {
@@ -550,13 +552,13 @@ async function resolveSource(root, harness = null) {
   return { mode: "discover" }
 }
 
-// ---- machine wiki (wiki.jsonc) --------------------------------------------------
+// ---- machine wiki (geneseed-wiki.jsonc) ------------------------------------------
 // The user's own knowledge base(s) — typically an Obsidian vault — declared once per
 // machine, not per repo (AGENT.md §8). Same injection mechanics as project context,
 // different scope. Resolution (first match wins, mirroring the learn plugin):
 //   1. $GENESEED_WIKI                      explicit manifest path
-//   2. $GENESEED_HARNESS/wiki.jsonc         pinned install dir
-//   3. <plugin dir>/../wiki.jsonc           auto-locate: beside the installed AGENT.md
+//   2. $GENESEED_HARNESS/geneseed-wiki.jsonc pinned install dir
+//   3. <plugin dir>/../geneseed-wiki.jsonc  auto-locate: beside the installed AGENT.md
 async function resolveWikiFile() {
   const explicit = process.env.GENESEED_WIKI
   if (explicit && (await isFile(explicit))) return explicit
@@ -568,8 +570,8 @@ async function resolveWikiFile() {
   if (harness) bases.push(harness)
   bases.push(path.resolve(PLUGIN_DIR, ".."))
   for (const base of bases) {
-    // wiki.json is the legacy name from earlier seeds — still honoured.
-    for (const name of ["wiki.jsonc", "wiki.json"]) {
+    // wiki.jsonc and wiki.json are the legacy names from earlier seeds — still honoured.
+    for (const name of ["geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) {
       const p = path.join(base, name)
       if (await isFile(p)) return p
     }
@@ -602,7 +604,7 @@ async function walkWikiDir(dir, depth, acc) {
 // folders on demand instead.
 const WIKI_LAZY_LIMIT = envNum("GENESEED_WIKI_LAZY_LIMIT", 200)
 
-// Parse wiki.jsonc into renderable wikis: [{ name, root, desc, conventions, inbox,
+// Parse the wiki manifest into renderable wikis: [{ name, root, desc, conventions, inbox,
 // protected, eager:[{rel,abs,desc}], lazy:[...], truncated }]. Entry paths resolve
 // against the wiki's own root and may name a single note OR a folder — a folder
 // applies its load mode to every note beneath it (`.` covers the whole vault).
@@ -613,7 +615,7 @@ const WIKI_LAZY_LIMIT = envNum("GENESEED_WIKI_LAZY_LIMIT", 200)
 async function wikiSets() {
   const file = await resolveWikiFile()
   if (!file) return []
-  const data = await readJsonc(file)   // wiki.jsonc is JSONC: stub ships commented
+  const data = await readJsonc(file)   // the manifest is JSONC: stub ships commented
   const wikis = Array.isArray(data?.wikis) ? data.wikis : []
   const out = []
   for (const w of wikis) {

package/adapters/opencode/plugins/geneseed-guard.js

@@ -7,7 +7,7 @@
 //   - Persist Insight (rule vs memory):  speed-bump the first write to user-rules.md
 //     memory file — that choice belongs to the user, via the rule skill.
 //   - Wiki (AGENT.md §8):  block mutations under a declared wiki's `protected`
-//     folders — the user's knowledge base sets its own no-go zones in wiki.jsonc.
+//     folders — the user's knowledge base sets its own no-go zones in geneseed-wiki.jsonc.
 // High-confidence patterns only, so legitimate work is never caught. Borderline cases
 // (.env edits, force-push) are WARNED, not blocked.
 //
@@ -171,13 +171,13 @@ const SHELL_TOOLS = ["bash", "shell", "exec", "command", "terminal", "run"]
 const hasAny = (name, parts) => parts.some((s) => name.includes(s))
 
 // ---- protected wiki folders (AGENT.md §8) --------------------------------------
-// wiki.jsonc (the machine-level knowledge-base manifest) may list `protected` folders
+// geneseed-wiki.jsonc (the machine-level knowledge-base manifest) may list `protected` folders
 // per wiki. Mutating anything under one is denied. Same resolution chain as the
-// context plugin: $GENESEED_WIKI -> $GENESEED_HARNESS/wiki.jsonc -> beside the install.
+// context plugin: $GENESEED_WIKI -> $GENESEED_HARNESS/geneseed-wiki.jsonc -> beside the install.
 async function isFile(p) { try { return (await fs.stat(p)).isFile() } catch { return false } }
 async function isDir(p) { try { return (await fs.stat(p)).isDirectory() } catch { return false } }
 
-// wiki.jsonc is JSONC (the seeded stub carries a commented example): strip // and
+// The wiki manifest is JSONC (the seeded stub carries a commented example): strip // and
 // /* */ comments plus trailing commas before parsing — string-aware, so quoted
 // "https://…" or "C:/…" values are untouched. Kept in sync with the context plugin's
 // copy (plugins stay self-contained, like the other shared helpers).
@@ -226,8 +226,8 @@ async function wikiFile() {
   if (process.env.GENESEED_HARNESS) bases.push(process.env.GENESEED_HARNESS)
   bases.push(path.resolve(PLUGIN_DIR, ".."))
   for (const base of bases) {
-    // wiki.json is the legacy name from earlier seeds — still honoured.
-    for (const name of ["wiki.jsonc", "wiki.json"]) {
+    // wiki.jsonc and wiki.json are the legacy names from earlier seeds — still honoured.
+    for (const name of ["geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) {
       const p = path.join(base, name)
       if (await isFile(p)) return p
     }
@@ -235,7 +235,7 @@ async function wikiFile() {
   return null
 }
 
-// Cached absolute prefixes, refreshed on a short TTL so a wiki.jsonc edit lands
+// Cached absolute prefixes, refreshed on a short TTL so a manifest edit lands
 // without a restart. Compared slash-normalized and case-insensitive — vault paths on
 // Windows and macOS are case-insensitive in practice, and for a guard the rare
 // case-only over-match is the safe direction.

package/bin/geneseed-cli.mjs

@@ -155,6 +155,11 @@ const VERBS = {
   // lives entirely inside this port, so — like the three above — it has no recorded cell to
   // compare against, only the absolute gates named beside it in `NATIVE`.
   loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
+  // A fifth native verb, and a port rather than an invention: the AI Harness Scorecard
+  // (upstream Python, pinned in the module's docblock). No Geneseed Python subparser ever
+  // existed for it, so there is no recorded cell — its absolute gate is
+  // tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
+  scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
 };
 
 function die(code, msg) {

package/docs/concepts/exclusions.md

@@ -61,7 +61,7 @@ The install records it (`Excluded rules: process 7` beside its pack list) and ev
 Every installed skill costs a line in the host's skill listing, every session. Skills you never use can be left out of an install:
 
 ```bash
-geneseed build --emit claude-global --exclude-skills "bruno-test-writer,bruno-collection-generator,react-view-transitions"
+geneseed build --emit claude-global --exclude-skills "bruno,react-view-transitions"
 ```
 
 The skill's files are not written, its catalogue row goes, and an OpenCode `/command` that runs it goes too. The install records the list (`Excluded skills: …` under its skill section), and every rebuild and upgrade keeps it. `--exclude-skills none` puts them all back.

package/docs/concepts/skills.md

@@ -17,7 +17,7 @@ A **skill** is a repeatable workflow written as a markdown playbook: when it app
 
 - **By name.** Ask for it — "brainstorm this", "run a council on it" — or, on hosts with slash commands, type `/<name>`.
 - **By trigger.** Every skill has a one-line description of its purpose and when it applies. The host shows those descriptions to the agent every turn, and the agent opens the matching skill when your request fits.
-- **User-only skills.** A few skills are marked to open only when *you* call them (a teaching drill, a tool tied to a setup the agent cannot see). They answer `/<name>` but the agent never starts them on its own, and their description stays out of the always-loaded list.
+- **User-only skills.** A few skills are marked to open only when *you* call them (a teaching drill, a tool tied to a setup the agent cannot see, a guide for one stack or one personal vault). They answer `/<name>` but the agent never starts them on its own, and their description stays out of the always-loaded list.
 
 ### A tour
 
@@ -29,7 +29,7 @@ A **skill** is a repeatable workflow written as a markdown playbook: when it app
 | find a bug by evidence: reproduce, isolate, root-cause, verify | `debug` |
 | answer a question from the open web, every claim cross-checked | `research` |
 | have several viewpoints debate a decision | `council` |
-| get an adversarial critique of anything | `roast-me` |
+| get an adversarial critique of your own ask, plan or idea | `roast-me` |
 | see what a change does before you agree to commit it | `explain-changes` |
 | stage the right paths and write a focused commit | `commit` |
 | open a pull request, or finish and merge a branch | `ship` |
@@ -42,6 +42,10 @@ The full list, with each description, is in the catalog.
 
 Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent proposes the exact edit to that skill and applies it only with your assent. Most runs end with nothing to change.
 
+### Old names keep working
+
+When two skills merge, the old name still works as a slash command: `/deps-audit` runs `dependencies`, and `/ci-fix` runs `debug`. The old names are user-only, so the agent's list shows each skill once. If you had left out a skill that was later merged, a rebuild leaves out the merged skill instead. A skill removed with no replacement is dropped from that list, with a note.
+
 ### What they cost
 
 The skill *bodies* are read only when used. The *descriptions* are listed to the agent every turn so it can pick the right one — that list is part of the always-on cost described in [Footprint](footprint.md).

package/docs/extending.md

@@ -349,6 +349,10 @@ Intent became IX.
 
 ## 3 — Adding a SKILL or an AGENT
 
+**First, try not to.** Skills rot really fast. Can an existing skill absorb this, or can one be
+merged or deleted to make room? Every skill adds a description to the always-on list and one more
+candidate for routing to choose between, so add only what no sharpened existing skill covers.
+
 **Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/bundle.mjs`) *aborts the
 build* when `AGENT.md.tmpl` names a spec with no file — so the file comes before the table row, or
 nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs:265` proves a refused
@@ -396,6 +400,35 @@ Two traps worth knowing before you write the spec:
   which drags in the `web/dist` rebuild — and an unknown category lands under Personal in the
   Library (`splitSkills` in `web/src/pages/Library.jsx`) with no warning.
 
+**Merging or removing a skill keeps its old name working.** When a skill absorbs another, put
+`<!-- aliases: old-name, other-old-name -->` on its own line under the surviving skill's purpose
+blockquote. Every host then answers `/old-name` with the merged skill's body. Claude Code,
+OpenClaude and Bob get a user-only `skills/<alias>/SKILL.md`, and OpenCode gets a
+`command/<alias>.md`. Neither form is counted as a skill. An install that excluded the old name
+now excludes the merged skill (`resolveSkillNames` in `js/build/source.mjs`), so a rebuild still
+works. A skill removed with no successor goes into `RETIRED_SKILL_IDS` in the same file: its
+exclusion is dropped with a notice instead of failing the rebuild, and the name can never be
+used for a new skill. The doctor (`aliasProblems`) refuses an alias that is malformed, duplicated,
+already a skill, retired, or the name of an OpenCode command.
+
+**A rarely-needed half goes in a side file.** A skill body is paid in full every time the skill
+loads. A branch only some runs need, or a big reference, can move into
+`src/skills/<name>/<file>.md` beside the flat spec. The body keeps one pointer line, such as debug's
+`**CI run red** → read [debug/ci.md](debug/ci.md) and follow it.` The side file costs nothing
+until the agent follows that pointer, and then it costs its own size. So move a half only when
+most runs skip it. The flat spec stays the source, so steps 1–9 are unchanged. The side file is
+themed like a spec, and `{{LAW:id}}` citations resolve in it and are gated. Every emit writes it
+next to the skill: `skills/<name>/<file>.md` in the flat bundle, and beside `SKILL.md` on every
+native host, through `claim()`. Native hosts get a code-span path instead of the link:
+`<this-skill-directory>` where the host announces the skill's directory, and the resolved
+directory on Bob and in OpenCode commands, aliases included (`pointSideFiles` in
+`js/hosts/native.mjs`). The doctor (`sideFileProblems`) requires a flat spec for the folder, `.md`
+files one level down, no `SKILL.md`, and a link to every side file from the body.
+`tests/unit/side_files.test.mjs` resolves every emitted pointer. The dead-link scan cannot,
+because a code span is not a link. Measured on 2026-10-08, with the neutral theme at the lean
+footprint: debug's SKILL.md went from 1.64k to 1.18k tokens and rule's from 2.33k to 1.83k
+(chars/4).
+
 
 ---
 

package/docs/guides/project-context.md

@@ -65,6 +65,26 @@ A monorepo with docs scattered across packages might write:
 
 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.
 
+## Review rules: `REVIEW.md`
+
+`AGENTS.md` (or `CLAUDE.md`) holds the rules for *doing* the work, and the agent loads it every session. `REVIEW.md` holds the rules for *judging* the work: what counts as serious, what to skip, how many nits are worth reporting, and checks that hold only in this codebase. It is read only when code is reviewed, so the agent writing the code never pays for it.
+
+- **Nearest wins.** For each changed file, the reviewer applies the nearest `REVIEW.md` above it, up to the repo root. A `REVIEW.md` in `api/` overrides the root one for files under `api/`.
+- **Precedence.** A folder's `REVIEW.md`, then the root `REVIEW.md`, then `CODING_STANDARDS.md` / `CONTRIBUTING.md`, then Geneseed's review defaults, output format included. A `REVIEW.md` never lifts a law: it cannot let the reviewer edit code or skip running the checks.
+- **Who reads it.** The `geneseed-code-review` skill and the `reviewer` agent, which also serves the loop `review` brick and the pipeline reviewer seat. The `ship` skill runs that review before it opens a pull request.
+- **Who writes it.** Nobody by default. Ask for a review rule, or let a finding recur, and the `review-response` skill offers the exact lines for the nearest `REVIEW.md`, creating it if it is missing, and writes them only when you agree.
+
+A host's own review command does not read `REVIEW.md` by itself. The always-loaded root file carries one sentence that tells it to:
+
+| Host | Built-in review command | Reads `REVIEW.md` natively | How it gets applied |
+|---|---|---|---|
+| Claude Code | `/code-review`, `/review` | No (only the managed GitHub Code Review does, root file only) | The sentence in `CLAUDE.md`, which the built-in review follows; or run `/geneseed-code-review` |
+| OpenClaude | Undocumented | No | The sentence in `.openclaude/CLAUDE.md`; or run `/geneseed-code-review` |
+| Bob | `/review`, Review panel | No | The sentence in `AGENTS.md` / `.bob/rules/geneseed.md`, which Bob injects in every mode |
+| OpenCode | None | No | `/code-review` runs `geneseed-code-review`, which reads it |
+
+For OpenClaude and Bob, that the built-in review honours the sentence follows from how each host loads its rules files; it has not been checked live yet. Keep `REVIEW.md` short, because every rule in it competes for the reviewer's attention.
+
 <!--harness:opencode-->
 *(OpenCode only)*
 

package/docs/guides/read-non-markdown.md

@@ -12,6 +12,6 @@ The agent's doc discovery sees markdown (`.md`) and AsciiDoc (`.adoc`) only. The
 - **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.
+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.
 
 Converter not found, or an MCP converter listed but not connecting? See [Model, agent and MCP problems](../reference/troubleshoot-tools.md).

package/docs/guides/uninstall.md

@@ -33,7 +33,7 @@ It also removes the install's row from the registry of installs. Start a new ses
 ## 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.
+- **`geneseed-wiki.jsonc`** (or `wiki.jsonc`, its name before the rename), **`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

package/docs/guides/upgrade.md

@@ -39,7 +39,7 @@ A dirty working tree, or a folder that is not a git clone, is reported rather th
 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`;
+- your `context.json` and `geneseed-wiki.jsonc` (an older `wiki.jsonc` is renamed to it, contents untouched);
 - 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).

package/docs/guides/wiki.md

@@ -18,9 +18,9 @@ If you keep a personal knowledge base on this machine, such as an Obsidian vault
 
 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`
+## Declare it in `geneseed-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:
+The build writes a `geneseed-wiki.jsonc` stub beside `AGENT.md` (for the OpenCode global install, `~/.config/opencode/geneseed-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
 {
@@ -47,7 +47,7 @@ The build writes a `wiki.jsonc` stub beside `AGENT.md` (for the OpenCode global
 
 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.
+Geneseed looks for the file in this order: `$GENESEED_WIKI`, then `$GENESEED_HARNESS/geneseed-wiki.jsonc`, then beside the installed `AGENT.md`. The build renames a `wiki.jsonc` or `wiki.json` left by an older install to `geneseed-wiki.jsonc`, contents untouched, and adds the new name to a `.gitignore` that listed the old one. Until that next build, the old `wiki.jsonc` is still read at each of those places.
 
 ## How each host honours it
 
@@ -60,7 +60,7 @@ The context plugin loads your eager entries and lists your lazy ones at session
 <!--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).
+No hook reads the wiki. The instructions in your harness tell the agent to read `geneseed-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

package/docs/opencode-plugin-setup.md

@@ -27,7 +27,7 @@ echo "export GENESEED_HARNESS=\"$GENESEED_HARNESS\"" >> ~/.zshrc     # persist (
 ```
 
 `GENESEED_HARNESS` points the plugins at your deployed bundle so they find the
-memory store, `context.json`, and `wiki.jsonc` with no hand-typed path. Using a
+memory store, `context.json`, and `geneseed-wiki.jsonc` with no hand-typed path. Using a
 non-default bundle location (`GENESEED_OUT`)? Set `GENESEED_HARNESS` to that
 path instead of `../Harness`.
 

package/docs/reference/env-context.md

@@ -18,7 +18,7 @@ What gets loaded into the agent's context at session start — your project's do
 | --- | --- | --- |
 | `GENESEED_CONTEXT` | context plugin, context hook | Explicit `context.json` manifest path; overrides discovery. |
 | `GENESEED_ROOT` | context hook | Repo root to discover docs from (default: the current directory). |
-| `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `wiki.jsonc` path (default `$GENESEED_HARNESS/wiki.jsonc`, else beside the install). |
+| `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `geneseed-wiki.jsonc` path (default `$GENESEED_HARNESS/geneseed-wiki.jsonc`, else beside the install). |
 | `GENESEED_STACK_GLOBAL` | context hook, Claude Code project build | `1` lets a global and a project install of the same host both inject. By default the project install makes the global one stand down. Rebuild the project install after changing it. |
 | `GENESEED_CONTEXT_INJECT` | context plugin | `off` disables injection; the agent is only *asked* to read the docs. |
 | `GENESEED_CONTEXT_VISIBLE` | context plugin | `1` shows the visible `PROJECT CONTEXT` block instead of the invisible per-request delivery. |
@@ -33,7 +33,7 @@ Where distilled memories land at session end, and which model distils them. See
 
 | Variable | Read by | Effect |
 | --- | --- | --- |
-| `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `wiki.jsonc` is looked up). Optional — the plugin finds the in-config store by itself; set it to pin the location. |
+| `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `geneseed-wiki.jsonc` is looked up). Optional — the plugin finds the in-config store by itself; set it to pin the location. |
 | `GENESEED_MEMORY` | learn plugin, CLI | Explicit memory dir; wins over `GENESEED_HARNESS`. |
 | `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
 | `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, the hook prints the prompt instead of distilling. |

package/docs/reference/plugin-context.md

@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
 
 - **Injected in full (eager):** root `README.md`, `CONTRIBUTING.md` (or `README.adoc`, `CONTRIBUTING.adoc`), `.cursorrules`, `user-rules.md`, `PROFILE.md`. Budget-capped; an oversized file is listed instead, never silently truncated. (`AGENT.md`, `AGENTS.md` and `CLAUDE.md` are not injected — OpenCode already loads them.)
 - **Listed (lazy, path + first heading, read on demand):** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/`, and `packages/*/README.md` / `apps/*/README.md` in a monorepo, AsciiDoc `.adoc` docs included. `node_modules`, `.git`, `dist`, `build`, `vendor` and similar are never scanned.
-- **Machine wiki:** the wikis declared in `wiki.jsonc` ride in the same block, on the same budgets. See [Wiki](../guides/wiki.md).
+- **Machine wiki:** the wikis declared in `geneseed-wiki.jsonc` ride in the same block, on the same budgets. See [Wiki](../guides/wiki.md).
 - **Explicit manifest:** `$GENESEED_CONTEXT`, `.harness/context.json` or a root `context.json` takes over from discovery; `"extend": true` layers it on top instead. See [Project context](../guides/project-context.md).
 
 **When it runs.** On every request: the context rides invisibly in the request's message list, so it also survives compaction. If your OpenCode build lacks that (experimental) hook, the plugin notices and falls back to one visible message at session start, re-pushed when the session compacts.
@@ -23,5 +23,5 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
 - `GENESEED_CONTEXT_INJECT=off` — no injection; the agent is only *asked* to read the docs.
 - `GENESEED_CONTEXT_VISIBLE=1` — force the visible block (legacy `GENESEED_CONTEXT_TRANSFORM=0` does the same).
 - `GENESEED_EAGER_FILE_KB` / `GENESEED_EAGER_TOTAL_KB` (default 16 / 48), `GENESEED_LAZY_HEADINGS` (64), `GENESEED_WIKI_LAZY_LIMIT` (200) — budgets.
-- `GENESEED_WIKI` — explicit `wiki.jsonc` path.
+- `GENESEED_WIKI` — explicit `geneseed-wiki.jsonc` path.
 - `GENESEED_DEBUG=1` — log what it discovered and injected to stderr. Silence with this set means the plugin did not load.