geneseed 2.0.0

package/src/skills/daydream/instructions.md

@@ -0,0 +1,422 @@
+# Vault Daydream — Implementation Instructions
+
+You are running the Vault Daydream skill. Follow these steps precisely.
+
+## Step 0: Resolve Vault Root
+
+Determine `VAULT_ROOT`:
+1. **Geneseed `wiki.jsonc` first.** Look for `wiki.jsonc` beside the harness `AGENT.md` (or at `$GENESEED_WIKI`). Strip `//` and `/* */` comments, parse it, and take the first `wikis[].path` whose root exists on disk — that is the vault. Prefer a declared vault whose `path` contains a `.obsidian/` folder; if several qualify, ask which to use. (This is Geneseed's machine-wide knowledge-base manifest — see AGENT.md's Wiki section.)
+2. Otherwise, check if the current working directory contains a `.obsidian/` folder. If yes, use it as `VAULT_ROOT`.
+3. If still unresolved, use `AskUserQuestion` to ask:
+   - Question: "Where is your Obsidian vault located?"
+   - Options: provide 2-3 likely paths if detectable (e.g., from `find ~ -maxdepth 3 -name ".obsidian" -type d 2>/dev/null | head -3`), plus an "Other" option for custom input.
+4. Store the resolved path as `VAULT_ROOT` for all subsequent steps.
+
+## Constants
+
+```
+VAULT_ROOT = (resolved in Step 0)
+DAYDREAMS_DIR = Daydreams
+DIGESTS_DIR = Daydreams/digests
+HISTORY_FILE = ai-research/daydream/history.json
+DAILY_DIR = Daily
+EXCLUDE_DIRS = .obsidian, templates, node_modules, Daydreams, .claude, .git
+LOOKBACK_DAYS = 120
+PAIR_COUNT = 50
+BATCH_SIZE = 5
+SCORE_THRESHOLD = 7.0
+MAX_EXCERPT_WORDS = 500
+```
+
+---
+
+## Step 1: Scan Vault
+
+### 1a. Get today's date
+```bash
+date +"%Y%m%d"
+```
+Store as `TODAY` (e.g., `20260214`).
+
+### 1b. Find recent notes
+Use Bash to list all .md files modified in the last 120 days, excluding certain directories:
+
+```bash
+find $VAULT_ROOT -name "*.md" -type f -mtime -120 \
+  -not -path "*/.obsidian/*" \
+  -not -path "*/templates/*" \
+  -not -path "*/node_modules/*" \
+  -not -path "*/Daydreams/*" \
+  -not -path "*/.claude/*" \
+  -not -path "*/.git/*" \
+  -exec stat -f "%m %N" {} \; | sort -rn
+```
+
+This returns lines like: `1707900000 /path/to/note.md`
+
+Parse into a list of `{path, timestamp}` objects.
+
+### 1c. Load history for dedup
+Read `ai-research/daydream/history.json` if it exists. This contains previously sampled pairs:
+```json
+{
+  "sampled_pairs": [
+    {"a": "Note A.md", "b": "Note B.md", "date": "20260213"}
+  ]
+}
+```
+If file doesn't exist, treat as empty: `{"sampled_pairs": []}`.
+
+---
+
+## Step 2: Extract Excerpts
+
+For each note found in Step 1 (up to 200 notes — if more, take the 200 most recent):
+
+1. **Read the file** using the Read tool
+2. **Strip YAML frontmatter**: Remove everything between the first `---` and the second `---` (inclusive)
+3. **Strip noise**: Remove code blocks (``` fenced blocks), raw URLs (http://...), wikilink brackets (keep the display text or link text), image embeds (![[...]]), HTML tags
+4. **Extract title**: Use the first `# ` heading, or the filename (without .md extension) if no heading
+5. **Take first 500 words** of the cleaned text
+6. **Compute days ago**: `(now_timestamp - file_timestamp) / 86400`
+
+Store as array:
+```json
+{
+  "path": "relative/path.md",
+  "title": "Note Title",
+  "excerpt": "First 500 words...",
+  "days_ago": 5
+}
+```
+
+**Important**: Do NOT read all 200 files sequentially. Read in parallel batches of 20 using the Read tool (call 20 Read tools in a single response).
+
+---
+
+## Step 3: Generate Weighted Random Pairs
+
+### 3a. Assign weights
+For each note, assign a sampling weight based on recency:
+- **days_ago <= 7**: weight = 3
+- **days_ago <= 30**: weight = 2
+- **days_ago > 30**: weight = 1
+
+### 3b. Weighted random sampling
+Generate 50 unique pairs using weighted random sampling:
+
+Use Bash with Node for the random sampling:
+```bash
+node -e "
+const notes = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+const historyPairs = new Set();  // populated from history.json, as 'pathA\0pathB'
+
+// Build weighted pool
+const pool = [];
+notes.forEach((note, i) => {
+  const w = note.days_ago <= 7 ? 3 : (note.days_ago <= 30 ? 2 : 1);
+  for (let k = 0; k < w; k++) pool.push(i);
+});
+
+const draw = () => pool[Math.floor(Math.random() * pool.length)];
+const pairs = new Map();
+for (let attempts = 0; pairs.size < 50 && attempts < 500; attempts++) {
+  const a = draw(), b = draw();
+  if (a === b) continue;
+  const lo = Math.min(a, b), hi = Math.max(a, b);
+  if (pairs.has(lo + ',' + hi)) continue;
+  if (historyPairs.has(notes[lo].path + '\0' + notes[hi].path)) continue;
+  pairs.set(lo + ',' + hi, [lo, hi]);
+}
+
+const result = [...pairs.values()].map(([x, y]) => ({ a: notes[x], b: notes[y] }));
+console.log(JSON.stringify(result));
+" <<< 'NOTES_JSON_HERE'
+```
+
+Replace `NOTES_JSON_HERE` with the actual JSON array from Step 2. Also incorporate history dedup by adding known pairs to `history_pairs`.
+
+If fewer than 50 pairs generated, that's fine — proceed with whatever was generated.
+
+### 3c. Output
+Store the pairs array. Each pair has:
+```json
+{
+  "a": {"path": "...", "title": "...", "excerpt": "..."},
+  "b": {"path": "...", "title": "...", "excerpt": "..."}
+}
+```
+
+---
+
+## Step 4: Synthesize Connections (Parallel Task Agents)
+
+### 4a. Read synthesizer prompt
+Read `synthesizer-prompt.md` from this skill's own folder to get the prompt template (in a deployed Geneseed bundle that is `skills/daydream/synthesizer-prompt.md`; an upstream Claude install uses `.claude/skills/daydream/synthesizer-prompt.md`).
+
+### 4b. Batch pairs
+Split the pairs into batches of 5. This yields up to 10 batches.
+
+### 4c. Launch Task agents in parallel
+For each batch, launch a Task agent with `model: sonnet`:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  model: "sonnet",
+  description: "Synthesize daydream batch N",
+  prompt: "You are processing a batch of note pairs for the Vault Daydream system.
+
+For each pair below, find deep non-obvious connections. Return a JSON array of results.
+
+[SYNTHESIZER PROMPT TEMPLATE — filled in for each pair]
+
+Pair 1:
+Note A: {title} --- {excerpt} ---
+Note B: {title} --- {excerpt} ---
+
+Pair 2:
+...
+
+Pair 5:
+...
+
+Return ONLY a valid JSON array with one object per pair:
+[
+  {
+    \"connection\": \"...\",
+    \"synthesis\": \"...\",
+    \"implication\": \"...\",
+    \"suggested_title\": \"...\",
+    \"title_a\": \"...\",
+    \"title_b\": \"...\",
+    \"path_a\": \"...\",
+    \"path_b\": \"...\"
+  },
+  ...
+]
+
+Do NOT wrap in markdown code fences. Return raw JSON only."
+)
+```
+
+**Launch up to 10 Task agents in a SINGLE message** (all in parallel). Each processes 5 pairs.
+
+### 4d. Collect results
+Parse the JSON arrays returned by each Task agent. Combine into one flat array of synthesis results.
+
+If a Task agent returns malformed JSON, skip that batch and note the error. Do not retry.
+
+---
+
+## Step 5: Critique and Score (Parallel Task Agents)
+
+### 5a. Read critic prompt
+Read `critic-prompt.md` from this skill's own folder to get the prompt template (in a deployed Geneseed bundle that is `skills/daydream/critic-prompt.md`; an upstream Claude install uses `.claude/skills/daydream/critic-prompt.md`).
+
+### 5b. Batch synthesis results
+Split synthesis results into batches of 5 (same pattern as Step 4).
+
+### 5c. Launch Task agents in parallel
+For each batch, launch a Task agent with `model: haiku`:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  model: "haiku",
+  description: "Critique daydream batch N",
+  prompt: "You are scoring synthesized insights for the Vault Daydream system.
+
+For each insight below, rate on Novelty, Coherence, and Usefulness (1-10 each).
+Accept if average >= 7.0. Be genuinely critical.
+
+Insight 1:
+Source notes: \"{title_a}\" and \"{title_b}\"
+Connection: {connection}
+Synthesis: {synthesis}
+Implication: {implication}
+
+Insight 2:
+...
+
+Return ONLY a valid JSON array with one object per insight:
+[
+  {
+    \"novelty\": 8,
+    \"coherence\": 7,
+    \"usefulness\": 9,
+    \"average\": 8.0,
+    \"verdict\": \"accept\",
+    \"reason\": \"...\",
+    \"suggested_title\": \"...\",
+    \"title_a\": \"...\",
+    \"title_b\": \"...\"
+  },
+  ...
+]
+
+Include suggested_title, title_a, title_b from the input for tracking.
+Do NOT wrap in markdown code fences. Return raw JSON only."
+)
+```
+
+**Launch up to 10 Task agents in a SINGLE message** (all in parallel).
+
+### 5d. Filter results
+Combine all critic responses. Merge each critic score with its corresponding synthesis result. Keep only entries where `verdict == "accept"` AND `average >= 7.0`.
+
+---
+
+## Step 6: Write Outputs
+
+### 6a. Create directories
+```bash
+mkdir -p $VAULT_ROOT/Daydreams/digests
+```
+
+### 6b. Write individual insight notes
+For each accepted insight, create a file:
+
+**Filename**: `Daydreams/{TODAY}-{slug}.md`
+
+Generate `slug` from `suggested_title`: lowercase, replace spaces with hyphens, remove special characters, max 50 chars.
+
+**Content template**:
+```markdown
+---
+created_date: '[[{TODAY}]]'
+type: daydream
+source_notes:
+  - '[[{title_a}]]'
+  - '[[{title_b}]]'
+scores:
+  novelty: {novelty}
+  coherence: {coherence}
+  usefulness: {usefulness}
+  average: {average}
+---
+
+# {suggested_title}
+
+> Connection between [[{title_a}]] and [[{title_b}]]
+
+{synthesis}
+
+## Implication
+
+{implication}
+
+## Critic's Note
+
+{reason}
+```
+
+Write each file using the Write tool. If multiple insights, write them in parallel.
+
+### 6c. Write daily digest
+**File**: `Daydreams/digests/{TODAY}-digest.md`
+
+```markdown
+---
+type: daydream-digest
+date: {TODAY}
+pairs_sampled: {total_pairs}
+insights_accepted: {accepted_count}
+---
+
+# Daydream Digest -- {TODAY}
+
+## Stats
+- Pairs sampled: {total_pairs}
+- Insights generated: {total_synthesized}
+- Accepted (avg >= 7.0): {accepted_count}
+- Acceptance rate: {acceptance_rate}%
+
+## Top Insights
+
+{For each accepted insight, sorted by average score descending:}
+
+### {rank}. {suggested_title} (avg: {average})
+**Connecting**: [[{title_a}]] <-> [[{title_b}]]
+{connection}
+
+```
+
+### 6d. Update daily note
+Read `Daily/{TODAY}.md`. If it doesn't exist, create it from template first. Check if a `## Daydream` section already exists — if so, **replace** it entirely (to handle re-runs). If it doesn't exist, append it.
+
+Content:
+```markdown
+## Daydream
+
+Vault daydream found {accepted_count} insights from {total_pairs} pairs ({acceptance_rate}% acceptance).
+
+Top connections:
+{For each accepted insight, up to 5:}
+- [[{TODAY}-{slug}|{suggested_title}]] (avg: {average}) -- [[{title_a}]] <-> [[{title_b}]]
+```
+
+---
+
+## Step 7: Log History
+
+### 7a. Update history.json
+Read the existing `ai-research/daydream/history.json` (or start fresh if missing).
+
+Add ALL sampled pairs (not just accepted ones) to the `sampled_pairs` array:
+```json
+{
+  "sampled_pairs": [
+    ...existing...,
+    {"a": "path/to/note-a.md", "b": "path/to/note-b.md", "date": "{TODAY}"}
+  ],
+  "runs": [
+    ...existing...,
+    {
+      "date": "{TODAY}",
+      "pairs_sampled": {total_pairs},
+      "insights_accepted": {accepted_count},
+      "acceptance_rate": {acceptance_rate}
+    }
+  ]
+}
+```
+
+Write back to `ai-research/daydream/history.json`.
+
+---
+
+## Step 8: Summary
+
+Output a concise summary to the user:
+
+```
+Vault Daydream complete -- {TODAY}
+
+{accepted_count}/{total_pairs} pairs produced insights (acceptance rate: {acceptance_rate}%)
+
+Top insights:
+1. {title} (avg: {score}) -- {title_a} <-> {title_b}
+2. ...
+3. ...
+
+Files: Daydreams/{TODAY}-*.md
+Digest: Daydreams/digests/{TODAY}-digest.md
+```
+
+---
+
+## Error Handling
+
+- **No notes found**: Tell user "No notes modified in last 120 days. Nothing to daydream about."
+- **Fewer than 10 notes**: Warn user, proceed with fewer pairs (minimum 5 pairs if possible)
+- **Task agent returns bad JSON**: Skip that batch, log the error, continue with other batches
+- **All insights rejected**: Write digest with 0 accepted, tell user "All insights scored below threshold -- the vault might need more diverse content, or try again tomorrow."
+- **History file corrupt**: Start fresh, warn user
+
+## Performance Notes
+
+- Reading 200 files: batch into groups of 20 parallel Read calls
+- 10 synthesis Task agents run in parallel (single message)
+- 10 critic Task agents run in parallel (single message)
+- Total: ~3-4 tool-call rounds for the heavy lifting

package/src/skills/daydream/synthesizer-prompt.md

@@ -0,0 +1,41 @@
+# Synthesizer Prompt
+
+Used by Task sub-agents (model: sonnet) to find connections between note pairs.
+
+---
+
+You are a creative synthesizer exploring an Obsidian knowledge vault.
+Your task is to find deep, non-obvious, and potentially groundbreaking
+connections between two notes.
+
+Do NOT state the obvious. Generate insights that the note author
+would find surprising and valuable.
+
+Note A: {title_a}
+---
+{excerpt_a}
+---
+
+Note B: {title_b}
+---
+{excerpt_b}
+---
+
+Explore these dimensions:
+1. Are these concepts analogous in some abstract way?
+2. Could one concept be a metaphor for the other?
+3. Do they represent a similar problem/solution in different domains?
+4. Could they be combined to create a new idea?
+5. What revealing contradiction or tension exists between them?
+
+Respond with ONLY a JSON object (no markdown fences):
+{
+  "connection": "A 1-sentence description of the non-obvious link",
+  "synthesis": "2-3 paragraphs exploring the connection in depth",
+  "implication": "What new question, project, or insight does this suggest?",
+  "suggested_title": "A compelling title for this insight note",
+  "title_a": "{title_a}",
+  "title_b": "{title_b}",
+  "path_a": "{path_a}",
+  "path_b": "{path_b}"
+}

package/src/skills/debug.md

@@ -0,0 +1,37 @@
+# {{SKILL}}: debug
+
+> {{DESC_DEBUG}}
+
+**Trigger:** a bug, test failure, crash, or behaviour that doesn't match expectation — 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.
+The pressure to skip straight to a patch is highest exactly when this rule matters most
+(an emergency, an "obvious" one-liner, a fix that already failed once). Systematic is
+faster than thrashing; do not trade it away under pressure.
+
+## Procedure
+1. Reproduce it first: find the smallest input or command that triggers the failure reliably. If you can't reproduce it, gather evidence (logs, stack trace, recent diff) until you can. Read the error and stack trace in full — they often name the cause outright.
+2. Isolate: binary-search the cause — narrow the input, the code path, or (for a regression) the commit range with `git bisect` (the [git-archaeology {{SKILL}}](git-archaeology.md) carries the full method). Change one variable at a time. In a multi-layer system (CI → build → sign, API → service → DB), instrument each boundary once to see *which* layer breaks before investigating inside it.
+3. State one hypothesis that explains ALL the evidence before touching code. If you can't, you don't yet understand the failure — gather more evidence, don't guess.
+4. Apply the smallest fix that addresses the root cause, not the symptom; resist fixing things the evidence doesn't implicate ({{LAW}} II). One change at a time — no bundled "while I'm here" edits, or you can't tell what worked.
+5. Verify: run the project's checks and read the actual output (universal {{LAW}} III) — the original reproduction now passes and nothing nearby broke. Where a test can pin the bug, add a regression test that fails before the fix and passes after, so it can never silently return. Dispatch the [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for a focused regression check when the blast radius is unclear.
+6. If a fix doesn't work, return to step 1 with what you learned — don't stack a second fix on top. **After three failed fixes, stop fixing:** when each attempt only shifts the symptom elsewhere, the architecture, not the line, is likely wrong. Surface that to the user and decide the approach together before trying again ({{LAW}} II).
+
+**Diagnostic logging is scaffolding.** When you add logging to isolate a bug, use the project's real logger at a DEBUG level rather than scattered `print`/`console.log`, prefer correlation IDs over loose object dumps, and **never log secrets, tokens, or PII** ({{LAW}} I). Treat every temporary log as disposable: remove or downgrade each `print`/`console.log`/`debugger` before the change ships ({{LAW}} XXIV) — leftover debug noise in a diff is a defect, not a free comment.
+
+## Done when
+- The failure is reproduced, root-caused, fixed at the cause, and the reproduction passes with no new breakage.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/decode.md

@@ -0,0 +1,28 @@
+# {{SKILL}}: decode
+
+> {{DESC_DECODE}}
+
+**Trigger:** the user hands over content that confuses them and wants it to *click* — "this is confusing, help me understand it", "break this down for me", "explain this passage". For a from-zero overview of a whole skill use [crash-course](crash-course.md); for practising a concept until it is reflex use [drill](drill.md); to convert a PDF or web doc into readable form first use [ingest](ingest.md).
+
+## Procedure
+1. Read the content the user is stuck on. Before explaining anything, find the one sentence that, once understood, makes the rest fall into place.
+2. Explain only that sentence first — using an everyday analogy, with no technical terms.
+3. Confirm that landed, then let the rest of the content follow from it rather than re-explaining every line.
+4. Ask three questions that only someone who truly understood it could answer. Do not continue until they pass all three.
+5. If they miss one, return to the analogy and re-anchor before asking again — don't just give the answer.
+
+## Done when
+- The user has the keystone idea in plain terms and has answered all three comprehension questions correctly.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/develop.md

@@ -0,0 +1,29 @@
+# {{SKILL}}: develop
+
+> {{DESC_DEVELOP}}
+
+**Trigger:** implementing a feature, fixing a bug, or changing code behaviour in a repo that has (or should have) a test suite.
+
+## Procedure
+1. Orient on the project's own documentation for what you are about to touch ({{LAW}} XVII).
+2. Make the smallest change that advances the task ({{LAW}} XXV).
+3. Cover the behaviour — test-first via the [tdd {{SKILL}}](tdd.md) where the target is known up front; otherwise write the covering test alongside the change ({{LAW}} XXXV).
+4. Run the *affected* tests and read the output ({{LAW}} III); on failure, fix the cause, do not mask it ({{LAW}} XXIV).
+5. Tidy the green code via the [refactor {{SKILL}}](refactor.md) — the tests are your safety net.
+6. Commit the green slice via the [commit {{SKILL}}](commit.md) ({{LAW}} XX). Loop one slice at a time; dispatch the [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for heavier or unfamiliar coverage.
+
+## Done when
+- The behaviour changed is covered by tests written this session, the affected suite is green with its output shown, and each slice was committed.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/document-project.md

@@ -0,0 +1,79 @@
+# {{SKILL}}: document-project
+
+> {{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.
+
+## Procedure
+1. **Find the doc home.** Look for an existing `docs/`, `doc/`, `documentation/`, or
+   `wiki/` folder at the project root, or a `context.json` pointer to one (the same
+   convention [repo-map {{SKILL}}](repo-map.md) and the context loader use). Reuse the one
+   that exists — never create a second. If none exists, create `docs/` at the root.
+2. **Survey the code, not the intent.** Map entry points, the public API / modules,
+   commands, config, and key directories — read the actual behaviour (universal {{LAW}} III,
+   {{LAW}} XVII). 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
+   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
+     ({{LAW}} XV: edit the layer you own, never the reader's additions).
+   - **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:
+   - **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.
+   - **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
+     depth.
+   - **Go deep on the hard parts** — identify the few subsystems that carry the project's
+     essential complexity (the core engine, the load-bearing algorithms, the non-obvious
+     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
+   on consent, via the [commit {{SKILL}}](commit.md) (universal {{LAW}} XX).
+
+## Done when
+- 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
+  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.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/domain-modeling.md

@@ -0,0 +1,38 @@
+# {{SKILL}}: domain-modeling
+
+> {{DESC_DOMAIN_MODELING}}
+
+**Trigger:** pinning down domain terminology, recording an architectural
+decision, or a design conversation keeps stumbling over ambiguous terms.
+
+## Procedure
+1. Before designing, read `CONTEXT.md` at the repo root (the domain glossary)
+   and the ADRs under `docs/adr/` in the area being touched; use their
+   vocabulary verbatim in code, tests, and prose.
+2. When a term is ambiguous, or two words compete for one concept, challenge
+   it: propose one canonical term, test it against edge-case scenarios, and
+   record it in `CONTEXT.md` the moment it crystallises. Create files lazily —
+   the first resolved term creates the glossary.
+3. When a structural decision lands (storage choice, event model, seam
+   placement per the [codebase-design {{SKILL}}](codebase-design.md)), write an
+   ADR at `docs/adr/NNNN-<slug>.md`: context, decision, consequences. One
+   decision per file.
+4. Never re-litigate an existing ADR silently — a changed mind gets a new,
+   superseding ADR that links the one it replaces.
+
+## Done when
+- The glossary and ADRs reflect every term and decision that crystallised this
+  session, and no two names compete for one concept.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.