geneseed 3.17.0 → 3.18.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ 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

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.17.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
@@ -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

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

package/docs/reference/plugin-guard.md

@@ -10,7 +10,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
 
 **What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
 
-- **Blocks** writes to private-key and credential files (*Sealed Secrets*), catastrophic shell commands such as deleting the filesystem root (*Deletion Is Deliberate*), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
+- **Blocks** writes to private-key and credential files (*Sealed Secrets*), catastrophic shell commands such as deleting the filesystem root (*Deletion Is Deliberate*), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
 - **Warns** (logged, allowed) on `.env` writes and force-push.
 - **Speed-bumps** the *first* write to `user-rules.md` or a memory file: it is refused once, naming *Persist Insight* — whether something is a standing rule or a fact to remember is your call, settled through the `rule` skill. The re-issued write goes through.
 

package/docs/token-footprint.md

@@ -4,9 +4,9 @@ What a deployed harness costs in context-window tokens, per host. Token counts a
 chars/4 estimates and shift a little with theme and version.
 
 **Treat every number below as a floor, not a reading.** They were measured on
-2026-09-12 on a `--footprint lean` build (the default) of the neutral theme with
-four doctrine packs, 54 skills and 19 agents, and nothing re-measures this page
-automatically. For a
+2026-10-08 on a `--footprint lean` build (the default) of the neutral theme with
+the default doctrine packs, 47 skills (plus 12 alias stubs) and 18 agents, and nothing
+re-measures this page automatically. For a
 live figure on your own install, ask the agent for the `token-report` skill —
 that is what it is for. A `--footprint full` build runs roughly 5k tokens
 heavier on the root file.
@@ -17,21 +17,21 @@ The context every host injects at session start, before you type anything:
 
 | Component | Claude Code | OpenCode | Bob |
 |---|---|---|---|
-| Root instruction file | ~7.2k (`CLAUDE.md`) | ~7.2k (`AGENT.md`) | ~7.5k (`AGENTS.md`, §3 table inline) |
-| Skill metadata (name + description) | ~4.1k | ~4.1k | ~4.1k (native) |
-| Agent metadata | ~0.5k | ~0.5k | — (no agents directory) |
+| Root instruction file | ~7.7k (`CLAUDE.md`) | ~7.6k (`AGENT.md`) | ~8.0k (`AGENTS.md`, §3 table inline) |
+| Skill metadata (name + description) | ~3.0k | ~3.0k | ~3.0k (native) |
+| Agent metadata | ~1.0k | ~1.0k | — (in the root's §3 table) |
 | Session files (rules, profile, Memory/Notebook indexes, wiki) | 0 fresh, grows with use (SessionStart hook) | 0 fresh, grows with use (context plugin) | 0 fresh, grows with use (SessionStart hook) |
-| **Total** | **~12k** | **~12k** | **~12k** |
+| **Total** | **~12k** | **~12k** | **~11k** |
 
 The emits are at parity by design: ~12k tokens, about 6% of a 200k
-window. Bob catalogues skills natively but has no agents directory, so its
+window. Bob catalogues skills natively but not agents, so its
 root keeps the §3 Agents table and drops the §4 Skills table — the catalogue
 flag is per kind (`hostCatalogsNatively`), not one boolean. Before the 2026-09 footprint pass every hooked host paid roughly double
 this: the context hook re-injected the root file the host had already loaded
 natively, and skill descriptions ran to 900 characters each — see the
-"Where the tokens go" list below for what changed. Bob carries the §3/§4 catalogue tables inline because its host exposes
-no native skill/agent inventory; Claude Code and OpenCode ship a
-pointer to the host's own inventory instead, ~1.9k tokens lighter. A session file still
+"Where the tokens go" list below for what changed. Bob carries the §3 Agents table inline because its host exposes
+no native agent inventory; Claude Code and OpenCode ship a
+pointer to the host's own inventory instead, ~0.3k tokens lighter. A session file still
 byte-identical to its seed is skipped — it says nothing — so a fresh install injects none
 of them; until 2026-10 the hook read them from the repo root, where a Claude-shaped install
 never puts them, and none reached the session at all. The
@@ -85,15 +85,18 @@ until 2026-09 it did, and the whole harness was paid twice per session.
   "dispatched agents never commit or push"), and the folder-Skill list, which
   now sits in the §4 catalogue half and so drops wherever the host catalogues
   Skills natively.
-- **Skill bodies (~53k) and agent bodies (~10k) are lazy** on every host —
+- **Skill bodies (~54k) and agent bodies (~14k) are lazy** on every host —
   loaded only when invoked. A typical skill costs ≤3k per invocation; the
-  heaviest (`react-view-transitions`, ~17.5k with its reference files) loads
+  heaviest (`react-view-transitions`, ~20k with its reference files) loads
   its references progressively.
 - **User-only skills leave the catalogue.** A skill whose source carries
   `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
   Code and Bob then drop its description from the always-on skill metadata and
-  only `/name` opens it. Seven skills carry it today (the five teaching drills,
-  `herdr`, `opencode-theme`), roughly a seventh of the ~1.7k skill-metadata line.
+  only `/name` opens it. The three teaching skills (`teach`, `quiz`, `learn-mode`)
+  and `herdr` carry it today.
+- **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
+  ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
+  on OpenCode — never in the model's catalogue, so a rename or merge is free.
 - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
   never enters the context window.
 

package/docs/understand/take-it-out.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "On your machine"
 description: "What geneseed uninstall removes, and what it keeps for you."
 ---
-`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
+`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
 
 ---
 

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.17.0"
+  "version": "3.18.0"
 }