geneseed 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -10,6 +10,46 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 _Nothing yet._
 
+## [3.4.0] — 2026-09-06
+
+### Added
+
+- **Six skills.** `security-audit` (the `security` agent finally has a caller — trust
+  boundaries, the classic classes, secrets, the supply chain, a ship / fix / block verdict),
+  `skill-forge` (author, sharpen, merge or retire a skill, with every satellite the host or
+  the source repo demands), `worktree` (isolate a task in its own tree from a clean base —
+  the first move when `git status` shows changes you did not make), `ci-fix` (a red CI run
+  reproduced under CI's conditions and fixed at the cause), `deps-audit` (a risk-ordered
+  upgrade plan for `migrate` to execute, installing nothing) and `consolidate-memory`
+  (the memory set verified against the live repo, merged, retired, re-indexed).
+- **A `harness` skill class** for the skills about the agent's own apparatus — wiki,
+  geneseed, rule, profile, herdr, skill-forge, consolidate-memory — which sat under
+  `understand` before and made that class a grab-bag. The web console's Skills view
+  grows the chip.
+
+### Changed
+
+- **A skill's emitted `description:` is now purpose + trigger.** Claude Code and Bob
+  match a task against that one line before loading a skill; it used to carry only what
+  the skill does, never when. `skillDescription()` appends `Use when: <the Trigger
+  paragraph>`, links reduced to text, capped at 900 chars at a sentence boundary.
+- **The Self-improvement footer is one file.** `src/skills/_self-improvement.md` is
+  INCLUDEd by every flat skill and the template, with a four-line LEAN half; fifty
+  byte-identical copies are gone.
+- **Merges, keeping the best of each:** `tdd` folded into `develop` (seams first, the
+  failing test seen to fail for the right reason, an explicit exit to ship or handoff);
+  `clarify` folded into `brainstorm` (charitable reading, the key-decision ledger echoed
+  back under Law X, then design only when there is something to design, and a routed
+  exit); the six learning skills folded into `teach` (crash course, decode, path) and
+  `quiz` (drill, feynman, gap check), both user-only. The skill count stays at 49.
+- **`workflow` refined per host:** OpenCode's saved scripts versus Claude Code's native
+  tool (inline or `.claude/workflows/`, and only once the user has opted in), Bob and
+  Copilot falling back to `parallel-agents`; pick saved over inline, pass the task as
+  `args` so a run stays a pure function of its inputs, resume a failed run rather than
+  rerun it, and carry the conclusion yourself.
+- **`registry.json`** stamps `last_verified: 2026-09-06` on every approved skill; the six
+  new ones enter as `experimental`.
+
 ## [3.3.0] — 2026-09-06
 
 The host-gap release: every host now gets the hook surface its runtime actually

package/README.md

@@ -11,7 +11,7 @@
 [![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-49-blueviolet)](src/skills/)
-[![Agents](https://img.shields.io/badge/agents-17-orange)](src/agents/)
+[![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
 [![Laws](https://img.shields.io/badge/laws-11-critical)](src/laws/universal.md)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · Copilot · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20Copilot%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
@@ -155,8 +155,8 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 | **🧭 Ontology** (`ontology/`) | the mind the rules govern, in four prose sections — **Telos** (the Pact: protect the user, the truth, the agent), **Evidence** (every claim graded by how it was obtained), **Decisions** (classify and tier by reversibility, show the real forks), **Conduct** (answer what was asked, once). Always in force, never toggleable |
 | **🛡️ Rules** (`laws/`) | 11 universal laws the agent obeys — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-assert, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, root-cause, external-gate, echo-the-intent, absence-is-a-claim |
 | **📐 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). 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 four pack files ship on disk either way, so a citation into a pack you left out still resolves |
-| **🤖 Agents** (17) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
-| **🛠 Skills** (49) | repeatable workflows: brainstorm · **clarify** · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · tdd · **develop** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **learning-path** · **gap-detector** · **feynman** · **crash-course** · **drill** · **decode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **opencode-theme** · **herdr** · **pipeline** |
+| **🤖 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** (49) | 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** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** |
 | **🔌 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 |

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical pointers, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.3.0**.
+> string. Current label: **3.4.0**.
 
 > **Spec status audit (2026-06-15).** Every dated spec authored before today was
 > verified against the source tree and confirmed implemented (code + tests + docs);
@@ -35,7 +35,7 @@ Every row below is present in the tree today; "Spec" links the design record.
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 11 laws, 17 agents, 49 skills, the memory convention, and the agent's sovereign notebook | [notebook](docs/specs/2026-06-11-notebook-sovereign-space.md) · [agent-own-space](docs/specs/2026-06-10-notebook-agent-own-space.md) |
+| **Laws / Agents / Skills / Memory / Notebook** | 11 laws, 18 agents, 49 skills, the memory convention, and the agent's sovereign notebook | [notebook](docs/specs/2026-06-11-notebook-sovereign-space.md) · [agent-own-space](docs/specs/2026-06-10-notebook-agent-own-space.md) |
 | **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the eleven always-on **Invariants** (IX and XI retired in place — folded into rigor 5 and Law III, numbers kept), and four toggleable **Doctrine** packs (craft, rigor, ops, process) addressed `<pack> <n>`. 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 pack numbering, the per-rule Principle column, every `{{DOCTRINE}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | [three-tier-constitution](docs/specs/2026-08-19-three-tier-constitution-design.md) |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | [theme-aware doctor/diff](docs/specs/2026-06-07-theme-aware-doctor-diff.md) |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | [improvements-export](docs/specs/2026-06-12-improvements-export.md) |

package/adapters/copilot/README.md

@@ -23,7 +23,8 @@ no "ask the user" tier, so this page is mostly about what those hooks *can* and
   - `agents/<name>.agent.md` — Copilot's **custom-agent dialect** (`.agent.md`
     extension; a `tools:` **allowlist**, not Claude's denylist — a read-only
     agent lists the tool ids it keeps: `read, search, todo, agent`, plus
-    `execute` only when the spec opts in with `<!-- bash: allow -->`). Sibling
+    `execute` only when the spec opts in with `<!-- bash: allow -->`, `fetch` only
+    with `<!-- webfetch: allow -->`). Sibling
     agent links are rewritten to the `.agent.md` filename.
   - `skills/<name>/SKILL.md` — **byte-identical** to every other host.
 

package/adapters/opencode/README.md

@@ -57,7 +57,8 @@ your-repo/
 - Read-only agents (their spec says *Read-only*) get an OpenCode `permission` block
   — `edit: deny`, `webfetch: deny`, and `bash: deny`, so a read-only agent can't
   mutate via the shell either. One that must run read-only commands (tests, linters,
-  scanners) declares `<!-- bash: allow -->` in its spec, which gates bash to `ask`
+  scanners) declares `<!-- bash: allow -->` in its spec, which gates bash to `ask`;
+  `<!-- webfetch: allow -->` (the researcher) re-opens web fetch the same way
   instead. The rest keep edit access.
 - OpenCode invokes a subagent via the task tool, e.g. `subagent_type: "reviewer"`.
 - **Skills are native, not slash commands** — model-invoked via the `skill` tool
@@ -357,7 +358,10 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
   { "agents": { "reviewer": { "model": "anthropic/claude-haiku-4-5", "temperature": 0.1, "variant": "high", "steps": 20 } } }
   ```
   Re-emit to apply. (A future TUI screen will edit this map.) Unlisted keys are omitted,
-  so the agent inherits OpenCode's defaults.
+  so the agent inherits OpenCode's defaults. The stub also carries an inert
+  `_recommended.cheap-tier` list — the read-and-summarise seats (explorer, researcher,
+  tester, and the council bench) worth routing to a cheaper model; copy the names you
+  want into `agents`, nothing applies by itself.
 - **Agent colours.** Each capability agent is emitted with a `color:` set to an OpenCode
   *named theme slot*, sourced from the active harness theme's `AGENT_COLORS` map
   (`themes/_TEMPLATE.json`; the shipped default — architect=`primary`, reviewer=`warning`,

package/docs/extending.md

@@ -293,7 +293,7 @@ emit leaves the prior install intact.
    a blank line, then a `>` blockquote holding `{{DESC_<NAME>}}` — title, blockquote, nothing
    between. `doctor` checks both the presence of the purpose line and that the blockquote is the
    *first* block (`authoringProblems`, via `firstBlockquote` and `descBlockProblem`).
-2. One row in the hand-authored table in `src/AGENT.md.tmpl` (agents `125-141`, skills `183-229`).
+2. One row in the hand-authored table in `src/AGENT.md.tmpl` (the `## 3.` table for agents, the `## 4.` one for skills).
    Gated both ways: a row with no file, and a file with no row.
 3. `DESC_<NAME>` in **all fourteen** themes. Theme parity catches a missing one; nothing catches
    an unstyled placeholder.
@@ -318,8 +318,9 @@ and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the top le
 Two traps worth knowing before you write the spec:
 
 - **The word "Read-only" anywhere in an agent spec locks its emit.** It is a bare substring test
-  (`js/hosts/native.mjs:148`). The escape hatch is an explicit `<!-- bash: allow -->` marker, which
-  re-opens bash on all three hosts.
+  (`js/hosts/native.mjs:148`). The escape hatches are explicit markers: `<!-- bash: allow -->`
+  re-opens bash on all three hosts (OpenCode gates it to `ask`), and `<!-- webfetch: allow -->`
+  re-opens web fetch — the researcher is the one spec that carries it.
 - **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
   `web/src/pages/Skills.jsx:19` mirrors `SKILL_CLASS` with nothing comparing them (contrast
   `LAW_META`, which *is* cross-checked). Inventing a new *category* means editing that file —

package/docs/web/agents.md

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

package/docs/web/first-session.md

@@ -16,7 +16,7 @@ Once installed, the agent doesn't change *how* you talk to your tool — it chan
 ### Try these prompts
 
 - *"Use the **profile** skill"* — a short interview that drafts `PROFILE.md` (seeded empty at install), so the agent knows who you are and how you like answers pitched.
-- *"Use the **clarify** skill on this feature request."*
+- *"Use the **brainstorm** skill on this feature request."*
 - *"Delegate to the **reviewer** agent on the staged diff."*
 - *"Use **brainstorm** then **plan** for how to add X."*
 - *"Use **council** to debate whether we should ship Y now."*

package/docs/web/skills.md

@@ -5,4 +5,4 @@ title: "Skills"
 kind: "concept"
 link: {"hash": "#/section/skills", "label": "Browse the catalog →"}
 ---
-{N_SKILLS} repeatable workflows the agent can invoke by name — from [[brainstorm]], [[clarify]], [[plan]], [[tdd]] and [[debug]] through [[council]], [[research]] and [[ship]] to [[roast-me]]. A skill is a markdown playbook under `src/skills/`; the agent reads it before acting. The catalog link lists every one, live.
+{N_SKILLS} repeatable workflows the agent can invoke by name — from [[brainstorm]], [[plan]], [[develop]] and [[debug]] through [[council]], [[research]] and [[ship]] to [[roast-me]]. A skill is a markdown playbook under `src/skills/`; the agent reads it before acting. The catalog link lists every one, live.

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.3.0"
+  "version": "3.4.0"
 }

package/js/hosts/native.mjs

@@ -112,6 +112,53 @@ export function descOf(text) {
   return firstBlockquote(text);
 }
 
+/**
+ * The `**Trigger:**` paragraph of a skill, flattened to one line — markdown links reduced
+ * to their text, HTML comments dropped, whitespace collapsed. '' when the skill has none.
+ *
+ * Why it exists: on Claude Code (and Bob) the frontmatter `description:` is the ONLY text
+ * the model matches a task against before deciding to load a skill. The purpose line says
+ * what a skill does; the trigger says WHEN — and a catalogue of purposes alone left the
+ * model choosing `tdd` from "Drive implementation with tests" without ever seeing "before
+ * writing implementation code". The AGENT.md §4 table carried the triggers, but native
+ * hosts collapse that table to a pointer (`hostCatalogsNatively`), so the trigger reached
+ * no host at all. `skillDescription` below concatenates the two.
+ */
+export function triggerOf(text) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((ln) => /^\*\*Trigger:\*\*/.test(ln.trim()));
+  if (start < 0) return '';
+  const para = [];
+  for (let i = start; i < lines.length; i += 1) {
+    const s = lines[i].trim();
+    if (i > start && (s === '' || s.startsWith('#') || s.startsWith('**'))) break;
+    para.push(s);
+  }
+  return para.join(' ')
+    .replace(/^\*\*Trigger:\*\*\s*/, '')
+    .replace(HTML_COMMENT_RE, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Purpose + trigger, the emitted `description:` of a skill. Capped so a long trigger (a
+ * few carry three sentences of disambiguation) cannot blow past what hosts display —
+ * cut at the last sentence end inside the cap, never mid-word.
+ */
+const DESCRIPTION_CAP = 900;
+export function skillDescription(text) {
+  const desc = descOf(text);
+  const trig = triggerOf(text);
+  if (!trig) return desc;
+  const full = `${desc} Use when: ${trig}`;
+  if (full.length <= DESCRIPTION_CAP) return full;
+  const cut = full.slice(0, DESCRIPTION_CAP);
+  const end = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('; '));
+  return end > desc.length ? cut.slice(0, end + 1) : cut.replace(/\s+\S*$/, '') + '…';
+}
+
 /** `_build_render._HTML_COMMENT_RE`. */
 const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
 
@@ -244,22 +291,28 @@ export function pushOverrideLines(fm, ov) {
   if (given(ov.steps)) fm.push(`steps: ${formatValue(ov.steps)}`);
 }
 
+/** The two opt-in markers a read-only spec may carry. Bare substring tests, like `isReadonly`. */
+const BASH_MARKER = '<!-- bash: allow -->';
+const WEBFETCH_MARKER = '<!-- webfetch: allow -->';
+
 /**
  * The readonly-tool line `claudeAgentFrontmatter`/`copilotAgentFrontmatter` each emit — a
  * DENYLIST for Claude, an ALLOWLIST for Copilot — differing only in the key, the base list,
- * the one extra entry the `<!-- bash: allow -->` marker toggles, and whether the value is
- * bracketed. `extraWhenBashAllowed` is `false` for Claude (Bash is denied UNLESS the marker
- * allows it) and `true` for Copilot (`execute` is allowed ONLY IF the marker is present) —
- * the same marker, read in the opposite sense a denylist and an allowlist require.
+ * the gated entries the markers toggle, and whether the value is bracketed. Each `gated`
+ * row is `[tool, marker, listedWhenMarked]`: `false` for Claude (the tool is denied UNLESS
+ * the marker allows it) and `true` for Copilot (the tool is allowed ONLY IF the marker is
+ * present) — the same marker, read in the opposite sense a denylist and an allowlist
+ * require. Row order is emit order: WebFetch before Bash keeps the unmarked Claude line
+ * byte-identical to what it was before the webfetch marker existed.
  */
 const READONLY_TOOLS = {
   claude: {
-    key: 'disallowedTools', tools: ['Write', 'Edit', 'NotebookEdit', 'WebFetch'],
-    extra: 'Bash', extraWhenBashAllowed: false, brackets: false,
+    key: 'disallowedTools', tools: ['Write', 'Edit', 'NotebookEdit'], brackets: false,
+    gated: [['WebFetch', WEBFETCH_MARKER, false], ['Bash', BASH_MARKER, false]],
   },
   copilot: {
-    key: 'tools', tools: ['read', 'search', 'todo', 'agent'],
-    extra: 'execute', extraWhenBashAllowed: true, brackets: true,
+    key: 'tools', tools: ['read', 'search', 'todo', 'agent'], brackets: true,
+    gated: [['fetch', WEBFETCH_MARKER, true], ['execute', BASH_MARKER, true]],
   },
 };
 
@@ -269,11 +322,11 @@ function claudeCopilotAgentFrontmatter(host, stem, text, overrides) {
   const ov = agentOverride(overrides, stem);
   if (isTruthy(ov.model)) fm.push(`model: ${formatValue(ov.model)}`);
   if (isReadonly(text)) {
-    const {
-      key, tools, extra, extraWhenBashAllowed, brackets,
-    } = READONLY_TOOLS[host];
+    const { key, tools, brackets, gated } = READONLY_TOOLS[host];
     const list = [...tools];
-    if (text.includes('<!-- bash: allow -->') === extraWhenBashAllowed) list.push(extra);
+    for (const [tool, marker, listedWhenMarked] of gated) {
+      if (text.includes(marker) === listedWhenMarked) list.push(tool);
+    }
     fm.push(`${key}: ${brackets ? `[${list.join(', ')}]` : list.join(', ')}`);
   }
   return fm;
@@ -294,8 +347,9 @@ function opencodeAgentFrontmatter(stem, text, overrides, theme = null) {
   fm.push(`color: ${agentColor(stem, theme)}`);
   pushOverrideLines(fm, agentOverride(overrides, stem));
   if (isReadonly(text)) {
-    fm.push('permission:', '  edit: deny', '  webfetch: deny');
-    if (text.includes('<!-- bash: allow -->')) fm.push('  bash:', '    "*": ask');
+    fm.push('permission:', '  edit: deny',
+      `  webfetch: ${text.includes(WEBFETCH_MARKER) ? 'allow' : 'deny'}`);
+    if (text.includes(BASH_MARKER)) fm.push('  bash:', '    "*": ask');
     else fm.push('  bash: deny');
   }
   return fm;
@@ -435,7 +489,7 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
       // Skills are BYTE-IDENTICAL across hosts: name + description, body link-stripped.
       // The user-only key is emitted for every host too — Claude Code and Bob honour it,
       // OpenCode and Copilot ignore an unknown key — so the identity holds.
-      fm = [`name: ${stem}`, `description: ${jsonDumps(descOf(text))}`];
+      fm = [`name: ${stem}`, `description: ${jsonDumps(skillDescription(text))}`];
       if (isUserInvokedOnly(text)) fm.push('disable-model-invocation: true');
       body = stripSkillBodyLinks(body);
       dest = path.join(skillsDir, stem, 'SKILL.md');

package/js/hosts/opencode.mjs

@@ -78,6 +78,20 @@ const AGENT_OVERRIDES_STUB = {
     + 'Host-specific; git-ignored. A future TUI screen edits this — rebuild to apply.'
   ),
   agents: {},
+  // Inert: `loadAgentOverrides` reads `agents` only. This is the starting point the README
+  // used to describe in prose — the seats whose work is read-and-summarise, where a smaller
+  // model loses little and a council convenes 3–6 of them at once.
+  _recommended: {
+    _comment: (
+      'Cheap-tier seats: copy the ones you want into "agents" with your host\'s cheap '
+      + 'model id (OpenCode: "anthropic/claude-haiku-4-5"; Claude Code / Copilot: "haiku"). '
+      + 'Read-and-summarise work — a council convenes several at once, so this is where '
+      + 'the savings compound. Nothing applies until you copy it.'
+    ),
+    'cheap-tier': ['explorer', 'researcher', 'tester', 'advocate', 'skeptic', 'pragmatist',
+      'steward', 'visionary', 'user-advocate', 'framer', 'empiricist', 'operator',
+      'historian'],
+  },
 };
 
 /** Mirrors `_build_emit.COMMAND_SET` — the hot skills worth a one-keystroke trigger. */

package/js/inspect/inventory.mjs

@@ -90,21 +90,26 @@ export const LAW_CLASSES = ['security', 'process', 'verify', 'craft', 'context',
 
 /** `_harness_tui.SKILL_CLASS` — each skill's category, keyed by file stem. */
 export const SKILL_CLASS = {
-  brainstorm: 'design', clarify: 'design', plan: 'design', council: 'design',
+  brainstorm: 'design', plan: 'design', council: 'design',
   workflow: 'design', 'parallel-agents': 'design', pipeline: 'design',
   'codebase-design': 'design', 'domain-modeling': 'design', wayfinder: 'design',
   tickets: 'design',
-  tdd: 'build', develop: 'build', refactor: 'build', debug: 'build', migrate: 'build',
+  develop: 'build', refactor: 'build', debug: 'build', migrate: 'build',
   'frontend-design': 'build', 'opencode-theme': 'build', prototype: 'build',
   'forge-mcp': 'build', 'bruno-collection-generator': 'build', 'bruno-test-writer': 'build',
-  'geneseed-code-review': 'review', 'fresh-eyes': 'review', 'gap-detector': 'review',
+  worktree: 'build', 'ci-fix': 'build', 'deps-audit': 'build',
+  'geneseed-code-review': 'review', 'fresh-eyes': 'review', 'security-audit': 'review',
   'roast-me': 'review', 'review-response': 'review', ponytail: 'review',
   commit: 'ship', ship: 'ship', release: 'ship', handoff: 'ship', 'git-rescue': 'ship',
-  'repo-map': 'understand', 'git-archaeology': 'understand', decode: 'understand',
+  'repo-map': 'understand', 'git-archaeology': 'understand',
   research: 'understand', ingest: 'understand', 'document-project': 'understand',
-  wiki: 'understand', prose: 'understand', geneseed: 'understand', rule: 'understand',
-  profile: 'understand', herdr: 'understand',
-  'crash-course': 'learn', drill: 'learn', feynman: 'learn', 'learning-path': 'learn',
+  prose: 'understand',
+  // `harness` — skills about the agent's own apparatus (its harness, memory, rules,
+  // knowledge base, terminal) rather than about the user's code. They sat under
+  // `understand` before, which made that class a grab-bag.
+  wiki: 'harness', geneseed: 'harness', rule: 'harness', profile: 'harness',
+  herdr: 'harness', 'skill-forge': 'harness', 'consolidate-memory': 'harness',
+  teach: 'learn', quiz: 'learn',
 };
 
 /** `k in dict` — own keys only, where `k in obj` also finds `Object.prototype` members. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",