geneseed 3.5.0 → 3.7.0

package/js/maintain/setup.mjs

@@ -228,6 +228,7 @@ const DOCTRINE_BLURBS = {
   ops: 'how the machine is driven — tool discovery, non-blocking commands, teardown',
   process: 'how a session runs — planning, context economy, docs first, and the consent gate '
     + 'on every commit and push (drop this pack and that gate goes with it)',
+  comms: 'how answers are presented — stable reference codes, a diagram or a table only where it earns its place',
 };
 
 /**
@@ -279,7 +280,7 @@ export function doctrineOptions() {
 /**
  * `_harness_setup.EMIT_OPTIONS`.
  *
- * Exported since P6b: `/api/themes` returns the same nine as its `emits` list, and a copy
+ * Exported since P6b: `/api/themes` returns the same eleven as its `emits` list, and a copy
  * of a table under test silently stops being the table under test.
  */
 export const EMIT_OPTIONS = [
@@ -292,6 +293,10 @@ export const EMIT_OPTIONS = [
   ['copilot-global', 'GitHub Copilot personal config dir (~/.copilot) — copilot-instructions.md, agents, skills.'],
   ['copilot', 'Per-repo AGENTS.md + .github/ for GitHub Copilot, committed into one repository.'],
   ['files', 'Plain bundle for any AGENT.md tool.'],
+  // Appended AFTER `files`, not beside the other hosts: the menu is answered by number, and a
+  // scripted `setup` that pipes its answers must keep meaning what it meant.
+  ['openclaude-global', 'OpenClaude global config dir (~/.openclaude) — CLAUDE.md, agents, skills, hooks.'],
+  ['openclaude', 'Per-repo .openclaude/ (CLAUDE.md, agents, skills, hooks) for OpenClaude, committed into one repository.'],
 ];
 
 /** `_harness_setup.FOOTPRINT_OPTIONS`. */
@@ -375,7 +380,7 @@ export function collectSetupLines() {
   // Every PROJECT emit needs the repo root — claude/bob/copilot included: without `--out`
   // their CLAUDE.md/.claude land in the generator's default ./Harness, where the host never
   // looks.
-  if (['opencode', 'claude', 'bob', 'copilot'].includes(emit)) {
+  if (['opencode', 'claude', 'bob', 'copilot', 'openclaude'].includes(emit)) {
     root = ask('Repo root to install into', '.');
     out = root;
   } else if (emit === 'files') {

package/js/maintain/uninstall.mjs

@@ -71,7 +71,7 @@ import { comparePaths, isAbsolutePath, within } from '../lib/paths.mjs';
 const hostSpec = (host) => HOSTS.find((h) => h.host === host);
 
 /** The Claude-STYLE hosts — one manifest shape, one reversal. Spelled once. */
-const CLAUDE_STYLE = ['claude', 'bob', 'copilot'];
+const CLAUDE_STYLE = ['claude', 'bob', 'copilot', 'openclaude'];
 
 /**
  * `shutil.rmtree(p, ignore_errors=True)`.
@@ -681,7 +681,7 @@ export function cmdUninstall(args) {
     const targetDesc = resolvePath(expanduser(args.target));
     printErr(`[uninstall] no Geneseed install detected at ${targetDesc}.\n`
       + '[uninstall] pass --target <repo> for a project install (.opencode/.claude/'
-      + '.bob/.github) or --target <config dir> for a global one.\n');
+      + '.bob/.github/.openclaude) or --target <config dir> for a global one.\n');
     return 1;
   }
   const [host, scope, root] = hit;
@@ -700,7 +700,7 @@ export function cmdUninstall(args) {
       + `${hostSpec(host).agentFile} managed block, and Geneseed's `
       + '~/.copilot/settings.json hooks on a global install (your own keys/hooks and '
       + '.github files are kept).\n');
-  } else if (host === 'claude' || host === 'bob') {
+  } else if (['claude', 'bob', 'openclaude'].includes(host)) {
     printOut('[uninstall] removes: agents/, skills/, markers, the '
       + `${hostSpec(host).agentFile} managed block, and Geneseed's `
       + 'settings.json hooks/excludes (your own keys/hooks are kept).\n');

package/js/web/actions.mjs

@@ -41,8 +41,8 @@ import { excludeAdd, excludeRemove } from '../inspect/excludes.mjs';
 import { setupBuildArgs } from '../build/generate.mjs';
 import { frontmatter, memoryDropIndex } from '../hosts/hooks.mjs';
 import {
-  HOSTS, bobConfigDir, claudeConfigDir, copilotConfigDir, expanduser, opencodeConfigDir,
-  resolvePath,
+  HOSTS, bobConfigDir, claudeConfigDir, copilotConfigDir, expanduser, openclaudeConfigDir,
+  opencodeConfigDir, resolvePath,
 } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, doctrinesForBuild, excludedRulesOfDir, footprintOfDir, installState,
@@ -644,7 +644,7 @@ export function apiMcpToggle(state, body) {
     return { ok: false, error: 'config holds comments — edit it by hand to keep them' };
   }
   let cfg;
-  if (['claude', 'bob', 'copilot'].includes(host)) {
+  if (['claude', 'bob', 'copilot', 'openclaude'].includes(host)) {
     if (isFile(p)) {
       let parsed;
       try {
@@ -817,6 +817,7 @@ const EMIT_FOR = new Map([
   ['claude global', 'claude-global'], ['claude project', 'claude'],
   ['bob global', 'bob-global'], ['bob project', 'bob'],
   ['copilot global', 'copilot-global'], ['copilot project', 'copilot'],
+  ['openclaude global', 'openclaude-global'], ['openclaude project', 'openclaude'],
 ]);
 
 /**
@@ -951,7 +952,8 @@ export function apiDeployCmd(state, body) {
     return { error: `folder not writable: ${root}` };
   }
   const cfgdirs = new Set();
-  for (const fn of [opencodeConfigDir, claudeConfigDir, bobConfigDir, copilotConfigDir]) {
+  for (const fn of [opencodeConfigDir, claudeConfigDir, bobConfigDir, copilotConfigDir,
+    openclaudeConfigDir]) {
     try {
       cfgdirs.add(resolvePath(fn()));
     } catch { /* not every host has a resolvable config dir; skip it */ }
@@ -976,7 +978,7 @@ export function apiDeployCmd(state, body) {
   // and `PreToolUse::Bash` went with them. `doctrinesForBuild` resolves unknown to ALL packs.
   const doctrines = bodyDoctrines(body) ?? doctrinesForBuild(root);
   const excludeRules = bodyExcludeRules(body) ?? excludedRulesOfDir(root);
-  // project-scope emit name == host name (opencode / claude / bob / copilot)
+  // project-scope emit name == host name (opencode / claude / bob / copilot / openclaude)
   const argv = setupBuildArgs(theme || 'neutral', host, root, root, fp, pos, mode, doctrines,
     PACK_ORDER, excludeRules);
   return { cmd: [process.execPath, path.join(ROOT, 'bin', 'build-driver.mjs'), ...argv] };

package/js/web/api.mjs

@@ -724,7 +724,7 @@ export const apiExcludes = () => excludesSnapshot();
  * nested-marker host cannot silently read the bare root.
  */
 export function viewCfg(host, scope, root) {
-  if (scope === 'project' && ['claude', 'bob', 'copilot'].includes(host)) {
+  if (scope === 'project' && ['claude', 'bob', 'copilot', 'openclaude'].includes(host)) {
     return path.join(root, HOSTS.find((h) => h.host === host).projectMarker);
   }
   return root;
@@ -790,7 +790,7 @@ export function apiOverview(state) {
   // can re-emit exactly it. Mirrors `viewCfg`'s rule, spelled out separately here.
   let install = null;
   for (const [host, scope, root] of installTargets()) {
-    const data = (scope === 'project' && ['claude', 'bob', 'copilot'].includes(host))
+    const data = (scope === 'project' && ['claude', 'bob', 'copilot', 'openclaude'].includes(host))
       ? path.join(root, HOSTS.find((h) => h.host === host).projectMarker) : root;
     try {
       if (samePath(data, state.target)) {

package/js/web/docs.mjs

@@ -207,7 +207,7 @@ const HARNESS_HINT_RE = /<!--\s*harness:/;
 export function normHarness(value, state) {
   const v = (value || '').trim().toLowerCase();
   if (HARNESSES.includes(v)) return v;
-  return String(state.emit || '').startsWith('claude') ? 'claude' : 'opencode';
+  return /^(claude|openclaude)/.test(String(state.emit || '')) ? 'claude' : 'opencode';
 }
 
 /**

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.5.0",
+  "version": "3.7.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",
@@ -9,6 +9,7 @@
     "claude-code",
     "opencode",
     "copilot",
+    "openclaude",
     "agents-md",
     "skills",
     "harness",

package/src/AGENT.md.tmpl

@@ -30,11 +30,14 @@ ritual: read this file and its {{LAWS}}, then **load the project context** — i
 (§9). Only then emit your first reply, which MUST begin with the
 exact line below, before any other text. Do not paraphrase it and do not skip it —
 a first reply that omits the sigil signals the harness was not read, and emitting
-it certifies you have loaded the {{LAWS}} *and* the project context.
+it certifies you have loaded the {{LAWS}} *and* the project context. **{{SKILLS}}
+first:** when a request matches a {{SKILL}}, invoke it as your first tool
+call — before loading context or touching files.
 <!-- LEAN:else -->
-**Readiness sigil — required.** Before your first reply: read this file and its
-{{LAWS}}, then load `context.json` and its `eager` entries (§9). Your first reply
-then MUST begin with the exact line below, verbatim — it certifies both were loaded.
+**Readiness sigil — required.** Your first reply MUST begin with the exact line below,
+verbatim — it certifies you have read this file and its {{LAWS}} and loaded `context.json`
+and its `eager` entries (§9). **{{SKILLS}} first:** when the request matches a {{SKILL}}, invoke
+it as your very first tool call — before loading context, reading files, or searching.
 <!-- LEAN:end -->
 
 > {{LOADED_SIGIL}}
@@ -206,7 +209,7 @@ subset that productively clashes on a given motion.
 | [debug]({{DIR_SKILLS}}/debug.md) | a bug or failure to diagnose before fixing |
 | [prototype]({{DIR_SKILLS}}/prototype.md) | a design question needs a runnable answer before real implementation |
 | [repo-map]({{DIR_SKILLS}}/repo-map.md) | orienting to the repo, or structure changed |
-| [document-project]({{DIR_SKILLS}}/document-project.md) | the project's own docs or HTML overview are missing or have drifted from the code |
+| [document-project]({{DIR_SKILLS}}/document-project.md) | missing/drifted docs, or a PRD, design system, architecture doc or AGENTS.md |
 | [ingest]({{DIR_SKILLS}}/ingest.md) | a task needs content from a PDF, Office doc, or URL |
 | [research]({{DIR_SKILLS}}/research.md) | a question needs answers gathered and verified from the open web |
 | [teach]({{DIR_SKILLS}}/teach.md) | the user wants to be taught — a crash course, confusing material decoded, or a day-by-day path to a deadline |

package/src/doctrines/README.md

@@ -8,7 +8,7 @@ documentation repo and a production service do not need the same practices.
 The selected packs are inlined into `AGENT.md`'s Doctrines section at build time;
 every pack ships here as a catalogue so you can read the alternatives and switch.
 Change the active set by rebuilding with `--doctrines <list>` (or via the setup
-wizard); the choice is stored in `harness.config.json`. All four are active by
+wizard); the choice is stored in `harness.config.json`. All five are active by
 default.
 
 A pack is **orthogonal to theme and posture**: the theme sets the *voice*, the
@@ -21,9 +21,10 @@ composes.
 | [rigor](rigor.md) | How work is proven — idempotence, honest tests, coverage, gates that can fail. |
 | [ops](ops.md) | How the machine is operated — tool discovery, non-blocking commands, source-layer edits, teardown. |
 | [process](process.md) | How a task is run — planning, context economy, docs-first, consent before push. |
+| [comms](comms.md) | How answers are presented — stable reference codes, a diagram or a table only where it earns its place. |
 
 A rule in one pack may cite a rule in another. That is safe because the **full
-catalogue ships in every bundle** — all four pack files are installed whether or not
+catalogue ships in every bundle** — all five pack files are installed whether or not
 their pack is built into `AGENT.md` — so a cross-pack reference is always readable
 even when the pack it names is not active.
 

package/src/doctrines/comms.md

@@ -0,0 +1,53 @@
+**{{PACK_COMMS}}** — how answers are presented.
+
+### {{DOCTRINE}} comms 1 — {{DOC_COMMS_1}}
+<!-- LEAN:begin -->
+Give every tracked item a short reference code and keep it unchanged for the rest of
+the session — `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions,
+`A` actions. The trigger is countable: any reply naming two or more such items takes
+codes, a {{SKILL}}'s or an {{AGENT}}'s report included, whatever layout its template
+shows; a reply with one item or none takes none. The code opens the item's line —
+`**F1** — the token is logged in plain text`, `**Q2** — keep the v1 route?` — not a
+bare `1.` or a bullet. Number from one within each kind, keep counting across turns
+(the next finding after `F3` is `F4`, even three replies later), invent a new letter
+for a kind the list omits, and never renumber a code once issued — the user will cite
+it back, and a moved code makes their reply mean something you did not say. A code is an address, not an ornament:
+it lets a long exchange be answered by reference, and a decision taken on turn
+three still be named on turn thirty. Where the {{ONTOLOGY}}'s {{ONT_CONDUCT}}
+governs how an answer speaks, this is only the addressing convention — a practice
+a repository adopts or drops like any other rule in these {{DOCTRINES}}.
+<!-- LEAN:else -->
+Give every tracked item a short reference code, unchanged for the session —
+`D` decisions, `O` options, `F` findings, `R` risks, `Q` questions, `A` actions.
+Any reply naming two or more such items takes codes, a {{SKILL}}'s or {{AGENT}}'s
+report included; one item or none takes none. The code opens the line, never a bare
+`1.` or bullet: `**F1** — token logged in plain text`, `**Q2** — keep the v1 route?`
+Number from one within each kind and keep counting across turns (after `F3` comes
+`F4`), invent letters for missing kinds, never renumber a code once issued.
+<!-- LEAN:end -->
+
+### {{DOCTRINE}} comms 2 — {{DOC_COMMS_2}}
+<!-- LEAN:begin -->
+Prose and structure are distinct: beside the prose, pick **either** a diagram **or** a
+table — whichever the matter needs, rarely both — and let the prose keep the context, the
+why, the pitfall and the decision. Draw a boxes-and-arrows diagram only when its arrows
+carry meaning: links to follow (a flow, a sequence, dependencies, a causal chain, a
+topology), a visual or spatial subject, four or more interlinked elements, or when the
+user asks. The test: erase the arrows — if nothing is lost, it was never a diagram.
+Classifications, inventories and attribute comparisons take a table or a list; a chain of
+three steps or fewer stays inline (`A -> B -> C`); a trivial fact stays plain text. A small
+diagram replaces prose only where the prose would run long describing a structure. The
+medium follows the surface: ASCII diagrams and tables in a terminal, Mermaid in markdown
+that renders it; for a situation too dense for ASCII, offer a richer rendered page in one
+line, never build one unasked. This is strictly additive to {{DOCTRINE}} comms 1: tracked
+items keep their codes, one coded line each, and a diagram or table may carry a code as a
+tag but never absorbs, merges or renumbers an item.
+<!-- LEAN:else -->
+Prose and structure are distinct: beside the prose, pick a diagram or a table, rarely
+both; prose keeps the why and the decision. Draw a diagram only when its arrows carry
+meaning — flow, dependencies, topology, a spatial subject, four or more linked elements,
+or on request; if erasing them loses nothing, use a table or list. Three steps or fewer
+stay inline (`A -> B -> C`). ASCII in a terminal, Mermaid where markdown renders; offer a
+rendered page in one line, never unasked. Codes stay ({{DOCTRINE}} comms 1): a diagram
+may tag an item, never absorb or renumber it.
+<!-- LEAN:end -->

package/src/doctrines/process.md

@@ -130,32 +130,6 @@ stalls, halt with a structured summary of what was tried, learned, and remains (
 
 ### {{DOCTRINE}} process 7 — {{DOC_PROCESS_7}}
 <!-- LEAN:begin -->
-Give every tracked item a short reference code and keep it unchanged for the rest of
-the session — `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions,
-`A` actions. The trigger is countable: any reply naming two or more such items takes
-codes, a {{SKILL}}'s or an {{AGENT}}'s report included, whatever layout its template
-shows; a reply with one item or none takes none. The code opens the item's line —
-`**F1** — the token is logged in plain text`, `**Q2** — keep the v1 route?` — not a
-bare `1.` or a bullet. Number from one within each kind, keep counting across turns
-(the next finding after `F3` is `F4`, even three replies later), invent a new letter
-for a kind the list omits, and never renumber a code once issued — the user will cite
-it back, and a moved code makes their reply mean something you did not say. A code is an address, not an ornament:
-it lets a long exchange be answered by reference, and a decision taken on turn
-three still be named on turn thirty. Where the {{ONTOLOGY}}'s {{ONT_CONDUCT}}
-governs how an answer speaks, this is only the addressing convention — a practice
-a repository adopts or drops like any other rule in these {{DOCTRINES}}.
-<!-- LEAN:else -->
-Give every tracked item a short reference code, unchanged for the session —
-`D` decisions, `O` options, `F` findings, `R` risks, `Q` questions, `A` actions.
-Any reply naming two or more such items takes codes, a {{SKILL}}'s or {{AGENT}}'s
-report included; one item or none takes none. The code opens the line, never a bare
-`1.` or bullet: `**F1** — token logged in plain text`, `**Q2** — keep the v1 route?`
-Number from one within each kind and keep counting across turns (after `F3` comes
-`F4`), invent letters for missing kinds, never renumber a code once issued.
-<!-- LEAN:end -->
-
-### {{DOCTRINE}} process 8 — {{DOC_PROCESS_8}}
-<!-- LEAN:begin -->
 When several {{AGENTS}} work on the same code — sub-{{AGENTS}}, a pipeline crew, a
 workflow fan-out, another session or tool in this checkout — each file has one writer at
 a time. Before dispatch, give every unit a **write set** (the files or globs it may

package/src/skills/debug.md

@@ -2,7 +2,7 @@
 
 > {{DESC_DEBUG}}
 
-**Trigger:** a bug, test failure, crash, or behaviour that doesn't match expectation — before proposing a fix.
+**Trigger:** a test fails, something crashes, an error or stack trace appears, or code returns the wrong result — load this FIRST, before reading code or investigating, not only before proposing a fix.
 
 **No fix without a root cause.** A change you cannot tie to a cause you understand is
 a guess — and a guess that happens to pass is worse than a failure, because it hides.

package/src/skills/document-project.md

@@ -2,9 +2,10 @@
 
 > {{DESC_DOCUMENT_PROJECT}}
 
-**Trigger:** the project's own documentation is missing, or it has drifted from the
-current code — and you want the markdown docs *and* a single visual overview brought back
-into line with the implementation.
+**Trigger:** the project's docs are missing or have drifted from the code, or it needs a PRD, a design system, an architecture document or an AGENTS.md. Existing codebases only — every document is extracted from the code, never written ahead of it.
+
+**Argument:** `[prd|design|architecture|agents|all]` — optional. It names the doc-set members to
+write; with none, step 3 proposes them.
 
 ## Procedure
 1. **Find the doc home.** Look for an existing `docs/`, `doc/`, `documentation/`, or
@@ -15,35 +16,53 @@ into line with the implementation.
    commands, config, and key directories — read the actual behaviour (universal {{LAW}} III,
    {{DOCTRINE}} process 4). If there is no `ARCHITECTURE.md`, run [repo-map {{SKILL}}](repo-map.md)
    first so you have the orientation map to build on.
-3. **Reconcile the markdown (whole tree).** Check every existing page against the current
+3. **Select the doc set.** Unless the argument names the targets, propose which of the four
+   documents apply and wait for the user's go-ahead — e.g. "no UI detected (no stylesheet,
+   theme, or component tree) — skipping `DESIGN.md`". `AGENTS.md`, `PRD.md` and
+   `architecture.md` apply to every project; `DESIGN.md` only when a UI exists.
+   `all` still skips `DESIGN.md` when no UI exists, and says so in one line.
+4. **Write or refresh each selected document** from its template in *The doc set* below,
+   under the rules in *Re-runs*. **Invent nothing**: every claim cites `path:line`, or carries
+   the marker `⚠ to confirm` (in the user's language). When drafting is done, put every `⚠` to
+   the user as **one** batch of questions — not one at a time — and fold the answers in as plain
+   text. A command you could not run is recorded as `⚠ fails: <error>`, never as working.
+   Every document follows the three page conventions in step 5.
+5. **Reconcile the markdown (whole tree).** Check every existing page against the current
    implementation — renamed or removed APIs, changed flags, dead examples — and fix the
    drift. Add pages for significant undocumented surfaces; remove docs for features that no
    longer exist (deletion is deliberate — {{LAW}} IV). For substantial writing, dispatch
    the [docs {{AGENT}}](../{{DIR_AGENTS}}/docs.md). Keep examples runnable — run them.
    Every generated page follows three conventions:
    - **Typed frontmatter.** Open each page with YAML frontmatter carrying `type:` (one of
-     `overview`, `module`, `api`, `flow`, `how-to`), `mirrors-commit: <sha>`, and
-     `generated: <date>` — so drift is auditable per page, not only in the HTML footer. The
-     doc-home `index.md` is reserved and carries no frontmatter.
-   - **Fenced generated regions.** Wrap the auto-generated body between
-     `<!-- geneseed:doc:start -->` and `<!-- geneseed:doc:end -->` markers, and on re-runs
-     rewrite *only* inside them — hand-authored prose outside the markers is never touched
-     ({{DOCTRINE}} process 3: edit the layer you own, never the reader's additions).
+     `overview`, `module`, `api`, `flow`, `how-to`, `prd`, `design-system`, `architecture`),
+     `mirrors-commit: <sha>`, and `generated: <date>` — so drift is auditable per page, not only
+     in the HTML footer. The doc-home `index.md` is reserved and carries no frontmatter, and
+     neither does the root `AGENTS.md` (agents read it raw) — though it still takes the
+     fences below.
+   - **Fenced generated regions.** Wrap each generated **section** between
+     `<!-- geneseed:doc:start -->` and `<!-- geneseed:doc:end -->` markers — one pair per
+     section, so prose a reader adds between sections survives — and on re-runs rewrite *only*
+     inside them; hand-authored prose outside the markers is never touched.
    - **Diagrams as Mermaid, keyed by purpose.** In the markdown, render diagrams as fenced
      `mermaid` code blocks — they render natively on GitHub, Obsidian, and VS Code with no
      dependency. Pick the kind by what you are showing: sequence for runtime/request flows,
-     ER for data models, state for lifecycles, flowchart for control flow. Reserve
-     hand-authored inline SVG for the offline HTML hero only (step 5).
-4. **Keep an index.** Ensure the doc home has an index/README linking every page, current
-   with the set you just reconciled.
-5. **Regenerate the HTML overview** — one self-contained file at the doc home (e.g.
-   `docs/overview.html`), a visual parallel to the markdown. Overwrite the previous one,
-   but confirm it is the generated artifact before clobbering ({{LAW}} III, {{LAW}} IV). It
-   must:
+     ER for data models, state for lifecycles, flowchart for control flow and C4 views. Reserve
+     hand-authored inline SVG for the offline HTML only (step 7).
+6. **Keep an index.** Ensure the doc home has an index/README linking every page, the doc-set
+   members included, current with the set you just reconciled.
+7. **Regenerate the HTML** — self-contained files at the doc home, a visual parallel to the
+   markdown and never a source of truth: regenerate them whole from the markdown each run
+   ({{DOCTRINE}} ops 3: edit the source, not the surface).
+   Overwrite the previous ones, but confirm each is the generated artifact before clobbering
+   ({{LAW}} III, {{LAW}} IV). Both files:
    - **Stand alone, fully offline** — a single file, content pre-rendered to semantic HTML,
      all styling in one inline `<style>`, at most minimal vanilla JS (light/dark toggle, TOC
      scroll). No CDN, no external assets, no web fonts (use a system-font stack). Render any
      diagram as hand-authored inline SVG or CSS — never a CDN library.
+   - **Stay project-facing** — clean and professional styling, never the harness voice; and
+     footer it with `mirrors commit <sha> · generated <date>` so the sync is auditable.
+
+   **`overview.html`** (always) must:
    - **Carry the digest** — hero (project name + one-line purpose), a quick-facts strip
      (language, entry point, build/test/run, license), an architecture section (component
      cards and an inline-SVG or CSS directory tree), and links out to the markdown docs for
@@ -53,16 +72,99 @@ into line with the implementation.
      control or data flow) and render *those* in depth: a plain-language explanation, the
      key code excerpt(s) in a styled monospace block, and the flow as inline SVG. Leave
      peripheral code at digest level.
-   - **Stay project-facing** — clean and professional styling, never the harness voice; and
-     footer it with `mirrors commit <sha> · generated <date>` so the sync is auditable.
-6. **Do not auto-publish.** Leave the changes for the user to review; stage and commit only
+   - **Present the doc set** that exists — *Product*: the one-line problem, FR and NFR counts
+     per status as ✅ ◐ ✗ pills, journeys as cards, a link to `PRD.md`. *Architecture*: C4 L1
+     and L2 as inline SVG, the ADR list (ID, title, one-line decision), a link to
+     `architecture.md` for L3. *Design*: the main palette as a strip and a link to
+     `design.html`.
+
+   **`design.html`** (only when `DESIGN.md` exists) renders the design system as seen, not
+   read: colour swatches with role and a computed AA/AAA contrast badge; the type scale at real
+   sizes and weights; spacing, radius and shadow on sample squares; components as cards
+   (variants, states, path) — no live rendering, which would need the project's framework; and
+   the hard-coded-value drift in a separate callout.
+8. **Do not auto-publish.** Leave the changes for the user to review; stage and commit only
    on consent, via the [commit {{SKILL}}](commit.md) ({{DOCTRINE}} process 5).
 
+## The doc set
+
+### `docs/PRD.md` — `type: prd`
+One product PRD for the whole project — the intent reconstructed from the code and the user.
+1. **Problem** — 2–4 sentences.
+2. **Users** — the roles, inferred from auth, permissions, and screens.
+3. **Goals**, then 4. **Non-goals** — the least code-derivable sections; expect most `⚠` here.
+5. **User journeys** — the top 3–5, as "As a … I want … so that …"; add a Mermaid sequence
+   diagram when more than two actors take part.
+6. **Functional requirements** — a table `ID | Requirement | Acceptance criteria | Status | Code`.
+   IDs run `FR-001`, `FR-002`, …; the requirement is one present-tense sentence; the acceptance
+   criteria a checklist; the status ✅ implemented, ◐ partial, ✗ absent, or `retired`; the code
+   the implementing path. Source them from routes, commands, screens, and tests.
+7. **Non-functional requirements** — the same table plus a `Threshold` column, IDs `NFR-001`, ….
+   The threshold is the measurable value the code or config fixes (timeout, rate limit, size
+   budget), else `⚠`.
+
+### `docs/DESIGN.md` — `type: design-system`
+Only when a UI exists.
+1. **Principles** — 3–5 lines on the visual character the code shows.
+2. **Tokens** — one table per family (colour, typography, spacing, radius, shadow, motion):
+   `Name | Value | Role | Source`. Colours add their semantic role and their WCAG 2.x contrast
+   ratio (relative luminance) against the reference background; flag every pair below WCAG AA.
+   A family the code has no scale for keeps its heading and one line: `⚠ no <family> scale
+   found`. List **hard-coded values** found outside the token system separately, as drift —
+   never legitimise them as tokens.
+3. **Components** — each reusable component: role, variants, states, key props, path.
+4. **Usage rules** — do / don't for layout, accessibility, and UI copy tone. Only rules the code
+   actually follows — never generic best practice.
+
+### `docs/architecture.md` — `type: architecture`
+The detailed architecture. Open with a link to the root `ARCHITECTURE.md` (repo-map's short
+map) and make sure the map links back — one fenced `geneseed:doc` line at its top, nothing else
+in that file touched; repeat nothing between the two.
+1. **Context (C4 L1)** — the system, its actors, and the external systems (APIs, SSO, shared
+   databases), as a Mermaid flowchart.
+2. **Containers (C4 L2)** — the deployable units and the protocols between them.
+3. **Components (C4 L3)** — one diagram per *significant* container, not one per module. On a
+   monorepo, work one container or package at a time.
+4. **Decisions** — lightweight inline ADRs, `ADR-001`, …, four lines each: *context · decision ·
+   consequences · evidence*. Structural choices only (framework, storage, architectural style,
+   decomposition) — not details.
+
+### `AGENTS.md` — repo root, at most ~60 lines
+The short manual an agent reads before touching the repo.
+1. **Commands** — build, test, lint, run: exact, and verified by running each one.
+2. **Non-obvious conventions**.
+3. **Do not touch** — generated files, vendored code, applied migrations.
+4. **Before you change…** — targeted pointers: a UI → `docs/DESIGN.md`; a new flow or
+   container → `docs/architecture.md`; a feature → `docs/PRD.md` (its FR ID).
+
+Geneseed may own a block in this file, between `<!-- BEGIN GENESEED -->` and
+`<!-- END GENESEED -->` — never write inside it. Create the file if it is absent; if it holds
+only that block, add the project sections below it.
+
+## Re-runs
+- **Reader prose is sacred.** Rewrite only inside a section's `geneseed:doc` fences. A
+  document that already exists **without** fences (a hand-written `PRD.md`, say) is never
+  rewritten: offer to fence the sections you recognise, or to leave it and report its drift —
+  the user chooses.
+- **IDs are stable.** Before rewriting, read the existing FR, NFR and ADR tables. Keep every
+  ID and any wording the user corrected; update only *Status*, *Code*, *Threshold*, and
+  *Evidence*; append new rows with the next free number. A requirement that disappears becomes
+  `retired` — never deleted, never renumbered. An ADR the code no longer bears is marked
+  `superseded`, never deleted.
+- **`mirrors-commit` moves only with a rewrite.** A document outside this run's target keeps
+  its old value, so its staleness stays visible.
+- **An answered `⚠` stays answered** — it is plain text now, not re-asked unless the code
+  contradicts it.
+
 ## Done when
+- Every selected doc-set member exists, follows its template, and cites its evidence or
+  carries `⚠`; the batch of `⚠` questions has been put to the user.
 - The doc home mirrors the current implementation: every markdown page carries typed
-  frontmatter, wraps its generated body in `geneseed:doc` markers, and is verified against
+  frontmatter, wraps its generated sections in `geneseed:doc` markers, and is verified against
   the code or flagged; examples run, Mermaid fences are well-formed, and the index links
-  them all; the single-file `overview.html` opens offline and shows both the digest and the
-  complex-core deep-dives; and any surface left undocumented is named explicitly.
+  them all.
+- `overview.html` opens offline and shows the digest, the complex-core deep-dives, and the
+  doc set; `design.html` does too wherever `DESIGN.md` exists; and any surface left
+  undocumented is named explicitly.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/parallel-agents.md

@@ -5,7 +5,7 @@
 **Trigger:** two or more independent subtasks with no shared state or ordering between them — and a tool that can run subagents.
 
 ## Procedure
-1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE}} process 8). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
+1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE}} process 7). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
 2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return.
 3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE}} process 5 stays with you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW}} VII). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE}} process 3). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
 4. Keep the main context lean: collect each subagent's distilled result, not its working transcript.

package/src/skills/pipeline.md

@@ -23,7 +23,7 @@ The minimum roster per task type. The parent may add specialists on top — secu
 
 1. Confirm the task is genuinely substantial — a trivial one-file tweak or a question does not warrant a crew; do it directly instead.
 2. Compose the crew from the floor above, adding specialists only where the task demands them.
-3. Isolate the crew's work in its own git worktree/branch (the SETUP.md worktree add-on). Where worktrees are unavailable, fall back to a single tree, one pipeline at a time, and say so. Give the crew a **write set** and check it against every other pipeline in flight ({{DOCTRINE}} process 8): two crews whose sets overlap do not run at once, and shared append files (registries, index tables, lockfiles, generated bundles) are the parent's to apply, never a crew's.
+3. Isolate the crew's work in its own git worktree/branch (the SETUP.md worktree add-on). Where worktrees are unavailable, fall back to a single tree, one pipeline at a time, and say so. Give the crew a **write set** and check it against every other pipeline in flight ({{DOCTRINE}} process 7): two crews whose sets overlap do not run at once, and shared append files (registries, index tables, lockfiles, generated bundles) are the parent's to apply, never a crew's.
 4. **The dev↔tester loop:** the developer implements, the tester validates — runs the tests and lint, produces raw logs. On failure, the findings go back to the developer. Cap at **5** iterations; on exhaustion, stop, do not merge, and report the failure with the branch left in place for inspection.
 5. **Two execution shapes**, chosen by host capability (same pattern as the [workflow {{SKILL}}](workflow.md)):
    - *Deterministic:* where the host exposes a `workflow` tool, run a saved script encoding analyst → developer → (tester ⇄ developer)×≤5 → proof.

package/src/skills/token-report/SKILL.md

@@ -28,9 +28,10 @@ picking the most recently active source:
 | Claude Code | `~/.claude/projects/<slug>/*.jsonl` | exact usage per request |
 | IBM Bob | `~/.bob/projects/<slug>/*.jsonl` (Claude-shaped, `$BOB_CONFIG_DIR` honoured) | exact usage per request |
 | OpenCode | `~/.local/share/opencode/opencode.db` (SQLite, v1.2+; pre-1.2 falls back to `storage/` JSON files) | exact `tokens` per request; child sessions attributed as subagents |
+| OpenClaude | `~/.openclaude/projects/<slug>/*.jsonl` (Claude-shaped, `$OPENCLAUDE_CONFIG_DIR` honoured) | exact usage per request |
 | GitHub Copilot | `~/.copilot/history-session-state/` | best effort — undocumented schema; token-like fields harvested, else estimates only |
 
-Useful flags: `--host claude|bob|opencode|copilot` to force a host,
+Useful flags: `--host claude|bob|openclaude|opencode|copilot` to force a host,
 `--transcript <path>` / `--session <id>` for a specific session,
 `--limit <tokens>` for the context-window limit used in the % columns
 (default 200000), `--top <n>` for the heaviest-items list.

package/src/skills/token-report/VENDOR.md

@@ -5,7 +5,7 @@ not third-party. It rides the vendored-folder mechanism because it bundles an
 executable (`scripts/token_report.mjs`) and Geneseed's flat-skill pipeline renders
 single `.md` files only. Listing it in the generator's `VENDORED_SKILL_DIRS`
 makes the whole folder ride along verbatim into every host emit — Claude Code,
-IBM Bob, OpenCode, GitHub Copilot — which is exactly what a multi-file skill needs.
+IBM Bob, OpenCode, GitHub Copilot, OpenClaude — which is exactly what a multi-file skill needs.
 
 - **Upstream:** this repository (first-party)
 - **License:** same as Geneseed (see repository LICENSE)
@@ -17,7 +17,7 @@ Consequences of riding this mechanism (deliberate):
   `description` and blockquote purpose line instead;
 - listed in AGENT.md's folder-skills section, not the main skills table.
 
-The script supports all four emitted hosts (exact usage on Claude Code, Bob and
-OpenCode; best-effort on Copilot, whose session-state schema is undocumented).
+The script supports all five emitted hosts (exact usage on Claude Code, Bob,
+OpenClaude and OpenCode; best-effort on Copilot, whose session-state schema is undocumented).
 If a host changes its session storage layout, fix the corresponding finder or
 parser in `scripts/token_report.mjs`.