geneseed 3.16.0 → 3.18.0

package/CHANGELOG.md

@@ -8,6 +8,51 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [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
+
+- Docs in AsciiDoc. `document-project`, the docs agent and the `docs-update` brick detect a project's docs format: a `.md`-only tree stays Markdown, an `.adoc`-only tree stays AsciiDoc, a mix asks you, and a project with no docs defaults to AsciiDoc. The choice is recorded as `Docs format:` in `AGENTS.md`. AsciiDoc mode uses header attributes, `.adoc` names and `[source,mermaid]` diagrams that GitHub renders, and it finishes with an `asciidoctor --failure-level=WARN` lint (or an explicit SKIPPED). With no docs yet, `document-project` interviews you first. Agent-runtime files stay Markdown.
+- C4 architecture diagrams in `document-project`. The audience you name sets the levels: L1 and L2 always, L3 only for containers you call complex, never L4. Diagrams are Mermaid `flowchart`s styled as C4 (typed nodes, `intent · protocol` edges, a title and a legend), redrawn only inside their own section. The `AGENTS.md` it writes sends a cross-container change to the L2 diagram first.
+- The context hook and the OpenCode plugin pick up `.adoc` files wherever they pick up `.md`; `README.adoc` and `CONTRIBUTING.adoc` load eagerly.
+- Protected checks. List the checks and tests your agent is judged by in `.geneseed/protected-checks.txt` at the repo root, one path per line, and a write to any of them asks you first on Claude Code, is blocked on Bob and refused on OpenCode, citing *External Gate*. A check the agent can edit is not a check. Nothing changes until a project adds the file. Shell edits are not seen, so keep running the checks in CI.
+
+### Changed
+
+- Loops repair once, then stop for you. The test repair rings of every shipped template (`apply-test`, `fix-test`, `write-run`, `stabilise`) are now `max: 1`: one repair, then the attempt is discarded for one fresh try, then the loop stops. A second revision makes code worse, not better — 0.82 correct after one revision, 0.673 after two ([arXiv 2607.24604](https://arxiv.org/abs/2607.24604)). A ring's `max` now binds its own repair edge even when a wider ring shares its nodes; before, `review-fix` (max 3) quietly let `apply-test` retry four times.
+- The `test` brick runs checks in order — build gate, then every focused check (none hides another), then the full suite only when all passed — and lists each one as `PASS`, `FAIL`, `ERROR` or `SKIPPED (reason)`. Each failure is four lines: purpose, property, a one-line diagnostic, the rerun command.
+- `error` is a reserved loop outcome: a check that crashed or was never wired stops the loop for a human instead of feeding a repair. A brick may declare it without an edge.
+- Each `test` report replaces the earlier `test` notes, so a repair never reads findings about code that has since changed.
+- Doctrine *Bound the Loop* says the same outside the loop engine: one repair, then a fresh attempt or a hand-back; only a verdict on the final artifact counts.
+
+## [3.16.1] — 2026-10-07
+
+### Fixed
+
+- `geneseed upgrade` from a checkout older than the August rename of `bin/geneseed.mjs` to `bin/build-driver.mjs` no longer fails with `Cannot find module '…/bin/geneseed.mjs'` and `[E-BUILD]` after a successful pull and doctor gate. The old updater (and an old web daemon's build jobs) spawn the old path from the code they started with; `bin/geneseed.mjs` is back as a forwarder to the driver. If you already hit it, run `geneseed upgrade` again — it is up to date now and rebuilds with the new code.
+
 ## [3.16.0] — 2026-10-05
 
 **Upgrading:** re-emit (`geneseed rebuild-all`) so the context hook stays under Claude Code's output cap. To drop skills you never use, rebuild an install with `--exclude-skills <name,…>` (see [Exclusions](docs/concepts/exclusions.md)).

package/README.md

@@ -6,11 +6,12 @@
 
 [![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%20%C2%B7%2090.4-1a7f37)](#-validate--test)
 [![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)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
@@ -164,11 +165,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 +292,19 @@ 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
+
+<p align="center"><img src="docs/assets/scorecard.svg" alt="AI Harness Scorecard for this repository: grade and score, with one bar per pillar" width="760"></p>
+
+How safe this repository is to change with agents, scored by 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.16.0**.
+> string. Current label: **3.18.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
@@ -156,8 +156,12 @@ function log(msg) { if (DEBUG) console.error(`[geneseed-context] ${msg}`) }
 // (OpenCode's own native roots) are deliberately absent: OpenCode already has them, and
 // injecting them again re-sent the whole harness on every request until 2026-09.
 const EAGER_ROOT = new Set([
-  ".cursorrules", "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
+  ".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 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"]
 // Never descend into these.
@@ -174,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
 ])
@@ -217,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++) {
@@ -277,11 +283,13 @@ function globToRegExp(glob) {
   return new RegExp("^" + re + "$")
 }
 
-// First H1 / heading line of a markdown file, for the lazy listing.
+// First heading line of a markdown or AsciiDoc file, for the lazy listing. An AsciiDoc
+// title is "= Title"; the space is required so a setext "====" underline never matches.
 function firstHeading(text) {
   for (const line of text.split("\n")) {
     const s = line.trim()
     if (s.startsWith("#")) return s.replace(/^#+\s*/, "").trim()
+    if (/^=+\s/.test(s)) return s.replace(/^=+\s*/, "").trim()
   }
   return ""
 }
@@ -425,7 +433,7 @@ async function walkMd(dir, root, depth, acc) {
     if (e.isDirectory()) {
       if (EXCLUDE_DIRS.has(e.name)) continue
       await walkMd(full, root, depth + 1, acc)
-    } else if (e.isFile() && e.name.toLowerCase().endsWith(".md")) {
+    } else if (e.isFile() && isDoc(e.name)) {
       acc.push(full)
     }
   }
@@ -448,7 +456,7 @@ async function discover(root) {
     if (!e.isFile()) continue
     const abs = path.join(root, e.name)
     if (EAGER_ROOT.has(e.name)) add(eager, abs)
-    else if (e.name.toLowerCase().endsWith(".md")) add(lazy, abs)   // misc root .md
+    else if (isDoc(e.name)) add(lazy, abs)   // misc root .md / .adoc
   }
 
   // 2. Doc trees (recursive) -> lazy.
@@ -469,8 +477,10 @@ async function discover(root) {
     try { pkgs = await fs.readdir(base, { withFileTypes: true }) } catch { continue }
     for (const p of pkgs) {
       if (!p.isDirectory() || EXCLUDE_DIRS.has(p.name)) continue
-      const readme = path.join(base, p.name, "README.md")
-      if (await isFile(readme) && !eager.has(readme)) add(lazy, readme)
+      for (const name of ["README.md", "README.adoc"]) {
+        const readme = path.join(base, p.name, name)
+        if (await isFile(readme) && !eager.has(readme)) add(lazy, readme)
+      }
     }
   }
 
@@ -542,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
@@ -560,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
     }
@@ -594,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).
@@ -605,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.
@@ -288,6 +288,32 @@ function ruleStoreTarget(p) {
   return nocase(abs).startsWith(nocase(mem) + "/") ? "memory" : null
 }
 
+// ---- protected checks (External Gate) ------------------------------------------
+// Twin of js/hosts/hooks.mjs's `protectedCheck` — keep in step. A project lists the checks its agent
+// must not edit in `.geneseed/protected-checks.txt` at its git root, one repo-relative path per
+// line; the list protects itself. Found from the WRITE TARGET up to the first `.git`, re-read on
+// every write (a short file, read only on a write call). No ask tier here, so a hit is a deny.
+const SENSOR_LIST = ".geneseed/protected-checks.txt"
+function protectedCheck(p) {
+  try {
+    const target = path.resolve(p)
+    let root = path.dirname(target)
+    while (!existsSync(path.join(root, ".git"))) {
+      const up = path.dirname(root)
+      if (up === root) return null
+      root = up
+    }
+    const text = readFileSync(path.join(root, SENSOR_LIST), "utf8")
+    const fold = (s) => nocase(s.replace(/\\/g, "/"))
+    const rel = fold(path.relative(root, target))
+    const entries = [SENSOR_LIST, ...text.split(/\r?\n/).map((l) => l.trim().replace(/[\\/]+$/, ""))
+      .filter((l) => l && !l.startsWith("#"))]
+    return entries.find((e) => rel === fold(e) || rel.startsWith(fold(e) + "/")) ?? null
+  } catch {
+    return null // no list (the common case) or an unreadable one: nothing is protected
+  }
+}
+
 // Mutation-class tools for the wiki check — wider than WRITE_TOOLS because moving,
 // renaming, or deleting a protected note is as destructive as overwriting it. Same
 // substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
@@ -437,6 +463,8 @@ export const GeneseedGuard = async (ctx) => {
           const p = pickPath(args)
           if (p && SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Sealed Secrets)`, "law-1"); return }
           if (p && SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Sealed Secrets)`)
+          const sensor = p && protectedCheck(p)
+          if (sensor) { await deny(`${p} is a protected check (${sensor}, listed in ${SENSOR_LIST}) — a check the agent can edit is not a check (External Gate)`, "rigor-5"); return }
           const store = p && ruleStoreTarget(p)
           if (store && !RULE_STORE_BUMPED.has(p)) {
             RULE_STORE_BUMPED.add(p)

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/bin/geneseed.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * The generator's PRE-RENAME path, kept as a forwarder to `bin/build-driver.mjs`.
+ *
+ * WHY A RENAMED FILE STILL HAS TO EXIST. `geneseed upgrade` runs the updater it started with:
+ * its module graph is loaded before the `git pull`, so an updater older than the rename
+ * (5c970dc9, 2026-08) pulls the new tree and then spawns `bin/geneseed.mjs` to rebuild —
+ * a file the tree it just pulled no longer has. The doctor gate passes (it spawns
+ * `geneseed-cli.mjs`, which never moved), and the rebuild dies with MODULE_NOT_FOUND and
+ * `[E-BUILD]`. An old web daemon's build jobs spawn the same path. Nothing in this tree
+ * calls it, and it has no npm name on purpose: it is a landing pad for old processes, not a
+ * fourth entry point.
+ *
+ * Importing the driver entry runs it on this process's argv, which is the argv the old
+ * caller passed — so the forwarding is the import and nothing else.
+ */
+import './build-driver.mjs';

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/hooks.md

@@ -36,6 +36,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
 **rule-gate.** Runs before every file write.
 - Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*.
 - A write to `user-rules.md`, `MEMORY.md` or a file in the install's `memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
+- A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). A project opts in with `.geneseed/protected-checks.txt` at its git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A check the agent can edit is not a check. The list protects itself. Only file-write tools are seen: a shell `sed -i` or redirect is not, so run the same checks in CI as the boundary that holds.
 - Ordinary edits pass untouched.
 
 **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`, skipping duplicates. It needs `GENESEED_LLM` set to a model command, for example:

package/docs/concepts/loop-notes.md

@@ -21,6 +21,9 @@ brick's behalf. This applies to `plan` and `review` as much as to the newer bric
 brick whose finding the next brick needs writes it to a file in the OS temp directory and reports
 that file's path with the outcome.
 
+One exception keeps the verdict fresh: each `test` report replaces every earlier `test` note, so a
+repair reads only the findings for the code as it stands, never a trace from an older version.
+
 ## `description` and `rules`: what a template is for, and what every brick must do
 
 A template's JSON carries two prose fields, and they are never confused:

package/docs/concepts/loops.md

@@ -47,6 +47,17 @@ all gets exactly 1 — no re-entry — which is also why **every cycle inside an
 named inner loop** in the graph JSON: `geneseed loop check` (and `loop init`, which runs the same
 check) refuses a graph with an undeclared cycle inside an iteration, before a single node runs.
 
+**A ring's `max` is also its own repair budget.** The edge that returns to a ring's first node
+from inside it — `test` → `apply` — is charged to the smallest ring holding both ends, and that
+ring stops at its `max` even when a wider ring raises the node's shared budget. The shipped test
+rings (`apply-test`, `fix-test`, `write-run`, `stabilise`) are `max: 1`: one repair, then the
+attempt is discarded for one fresh try, then the loop stops for you. A second revision makes the
+result worse, not better — 0.82 correct after one, 0.673 after two (arXiv 2607.24604).
+
+**`error` always stops.** A brick may declare the outcome `error` without an edge for it; the
+engine sends it to `$stop`. The shipped `test` brick reports it when a check crashed or its
+evidence was never wired — no verdict is not a failure to repair.
+
 ## Limits
 
 - **No parallel nodes.** The graph runs one node at a time; there is no fan-out.

package/docs/concepts/skills.md

@@ -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/headless.md

@@ -11,7 +11,7 @@ Once the harness is installed for OpenCode (global or per repo), OpenCode can ru
 
 ```
 opencode run "review the staged diff and list any correctness bugs"   # one shot, prints to stdout
-opencode run -m anthropic/claude-sonnet-4-5 "…"                       # pin a model for this run
+opencode run -m anthropic/claude-sonnet-5 "…"                         # pin a model for this run
 cat issue.md | opencode run "triage this and propose a fix plan"      # pipe input in
 ```
 

package/docs/guides/project-context.md

@@ -21,8 +21,8 @@ The context step sorts every doc it finds into one of two lists:
 
 With no configuration, the context step finds these files:
 
-- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md`. The root file your tool already loads by itself is skipped, so you never pay for it twice.
-- **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`.
+- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins). The root file your tool already loads by itself is skipped, so you never pay for it twice.
+- **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`. AsciiDoc docs (`.adoc`) are found everywhere a `.md` is.
 - **Never scanned:** `node_modules`, `.git`, `dist`, `build`, `vendor`, `.next`, `target`, `.venv`, `__pycache__`, `.opencode` and `.harness`.
 
 On Claude Code, Bob and OpenClaude the whole injection stays under 9,000 characters, because Claude Code hands the model only a short preview of a hook output past about 10,000 and keeps the rest in a file. Your session files come first, then eager files whole; an eager file that does not fit is listed instead, to be read on demand. On OpenCode eager files share a 48 KB budget. On every host, three or more docs in one folder are listed as that folder with a count (`docs/guides/ — 30 docs`), not file by file.

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

@@ -6,12 +6,12 @@ kind: "concept"
 section: "Set up"
 description: "Let the agent read PDF, Word, PowerPoint, Excel and HTML through a converter."
 ---
-The agent's doc discovery only sees markdown. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
+The agent's doc discovery sees markdown (`.md`) and AsciiDoc (`.adoc`) only. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
 
 - **MarkItDown**: the broadest. Use [its MCP server](mcp-markitdown.md) (preferred on a host with MCP: nothing to install per call, one cheap tool), or `pip install markitdown`.
 - **Pandoc**: excellent for Office and HTML, and a single binary.
 - **Docling** (IBM): best for complex tables and scanned PDFs.
 
-When an MCP converter is available, the skill prefers it. A prompt like *"convert file:///path/to/spec.pdf to markdown"* then just works. The skill never installs a converter silently. If none is present, it tells you which one to add.
+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