geneseed 3.8.0 → 3.10.0

package/src/skills/consolidate-memory.md

@@ -14,8 +14,8 @@ whole set. The user's wiki is out of scope — that is the [wiki {{SKILL}}](wiki
 1. **Read the whole set once**: `MEMORY.md` and every file it indexes, plus any file in
    `{{DIR_MEMORY}}/` the index forgot. Build a scratch table — name, type, the claim in
    one line, the date it was written — and note which entries the current session
-   already saw contradicted ({{DOCTRINE}} process 3: read to decide, not to reread).
-2. **Verify against the live repo, not memory** ({{LAW}} III). For each memory that
+   already saw contradicted ({{DOCTRINE:context-economy}}: read to decide, not to reread).
+2. **Verify against the live repo, not memory** ({{LAW:verify-before-asserting}}). For each memory that
    names a path, function, flag, command, version, PR or branch: check it still exists
    and still behaves as claimed. A `project` memory about work since merged, a
    `reference` to a moved file, a `feedback` note the code now enforces — each is a
@@ -27,11 +27,11 @@ whole set. The user's wiki is out of scope — that is the [wiki {{SKILL}}](wiki
    `user-rules.md` — hand it to the [rule {{SKILL}}](rule.md)), *retire* (wrong,
    superseded, or a fact a fresh read of the repo re-derives). When in doubt between
    keep and retire, keep and date it.
-4. **Show the plan, then apply it with consent** ({{LAW}} IV — retirement is deletion).
+4. **Show the plan, then apply it with consent** ({{LAW:deletion-is-deliberate}} — retirement is deletion).
    Merges preserve the `[[links]]` of both parents; rewrites keep the file name so
    inbound links hold; every surviving file keeps its frontmatter valid and its
    `**Why** / **How to apply**` lines where the type demands them. Nothing in the set
-   ever holds a secret ({{LAW}} I) — a memory that does is retired on sight.
+   ever holds a secret ({{LAW:sealed-secrets}}) — a memory that does is retired on sight.
 5. **Rebuild the index.** `MEMORY.md` gets exactly one line per surviving file, each
    with a hook that says why a future session would open it; entries the index had
    lost are added, retired ones removed, and the archive lines for old compactions kept

package/src/skills/council.md

@@ -5,7 +5,7 @@
 **Trigger:** the user asks to "convene a council", "debate this", "argue both sides", "stress-test this decision", or wants a change, plan, or claim challenged from several points of view before committing to it.
 
 ## Procedure
-1. Frame the motion in one line — the exact decision, change, or claim under debate — and name what it feeds (a choice to make, a design to accept, a discussion to settle). Ground it in the real artifact and the project's own docs ({{DOCTRINE}} process 4) so the council argues the actual thing; if the motion is unclear or bundles several questions, split it and ask once, then proceed.
+1. Frame the motion in one line — the exact decision, change, or claim under debate — and name what it feeds (a choice to make, a design to accept, a discussion to settle). Ground it in the real artifact and the project's own docs ({{DOCTRINE:read-the-docs-first}}) so the council argues the actual thing; if the motion is unclear or bundles several questions, split it and ask once, then proceed.
 2. Seat the council from the standing roster of read-only debate {{AGENTS}}, each arguing one fixed stance — convene the subset that genuinely clashes on *this* motion (usually 3–6, never the whole bench for its own sake), always anchored by the for/against spine of [advocate](../{{DIR_AGENTS}}/advocate.md) and [skeptic](../{{DIR_AGENTS}}/skeptic.md):
    - [advocate](../{{DIR_AGENTS}}/advocate.md) — the strongest case **for**; [skeptic](../{{DIR_AGENTS}}/skeptic.md) — devil's advocate, failure modes and hidden assumptions.
    - [pragmatist](../{{DIR_AGENTS}}/pragmatist.md) — cost, effort, YAGNI; [steward](../{{DIR_AGENTS}}/steward.md) — long-term architecture and debt; [operator](../{{DIR_AGENTS}}/operator.md) — running it in production.
@@ -15,7 +15,7 @@
    Hand each chosen seat the motion and a one-line charter scoped to this topic; skip the seats with nothing to say here, and add an ad-hoc seat (e.g. the [security](../{{DIR_AGENTS}}/security.md) surface) only when the topic plainly demands a voice the roster doesn't cover.
 3. Round one — positions: convene the seats by dispatching each stance {{AGENT}} as its own subagent in one batch where the tool supports it (the [parallel-agents {{SKILL}}](parallel-agents.md)), so each argues in an isolated context with no groupthink; where no subagent capability exists, voice each seat in turn as a persona. Each returns its steelmanned brief ({{ONTOLOGY}}: {{ONT_CONDUCT}}) — no hedging, no strawmen.
 4. Round two — clash: put the briefs in front of each other and have the seats rebut only on the points that actually conflict, surfacing the cruxes, the load-bearing assumptions, and where the evidence is thin. Hold to a fixed number of rounds so the debate converges instead of looping; the skeptic already pairs every objection with what would resolve it (the [roast-me {{SKILL}}](roast-me.md) discipline).
-5. The chair synthesises in neutral voice: state the verdict and its reasoning, record the strongest surviving dissent verbatim so it is not lost, list what would change the verdict, and name the single next action. Surface it for the user to decide — the council advises, it does not commit: write no code and push nothing on its own ({{LAW}} IV, {{DOCTRINE}} process 5).
+5. The chair synthesises in neutral voice: state the verdict and its reasoning, record the strongest surviving dissent verbatim so it is not lost, list what would change the verdict, and name the single next action. Surface it for the user to decide — the council advises, it does not commit: write no code and push nothing on its own ({{LAW:deletion-is-deliberate}}, {{DOCTRINE:consent-before-push}}).
 
 ## Done when
 - A crisp motion was debated by distinct, steelmanned seats over bounded rounds, and the chair has delivered a verdict, the preserved dissent, and one next action for the user to weigh.

package/src/skills/daydream/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: daydream
+description: "Mine an Obsidian vault for non-obvious connections between notes: samples recency-weighted note pairs, synthesizes links with parallel subagents, keeps only critic-approved insights and writes a daily digest. Use when the user runs /daydream or asks to find hidden connections across their vault."
+---
+
 # Vault Daydream Skill
 
 Multi-agent system that mines the Obsidian vault for non-obvious connections between notes, mimicking the brain's default mode network. Samples random note pairs, synthesizes connections via Sonnet, filters with Haiku critic.
@@ -10,6 +15,9 @@ Inspired by [Gwern's LLM Daydreaming](https://gwern.net/ai-daydreaming).
 /daydream
 ```
 
+To run it, follow `<this-skill-directory>/instructions.md` step by step — that file is the
+procedure; this one is the overview.
+
 ## Setup (Geneseed)
 
 Before the first run, make sure the pieces this skill depends on are in place:
@@ -20,14 +28,13 @@ Before the first run, make sure the pieces this skill depends on are in place:
    asks. No vault → nothing to daydream about.
 2. **Parallel subagents.** Synthesis and critique fan out across ~10–20 subagents per
    run, so the host must be able to dispatch them (Claude Code's `Task`; OpenCode's
-   `task` tool — see the [parallel-agents](../parallel-agents.md) skill). On a host
+   `task` tool — see the `parallel-agents` skill). On a host
    with no subagent mechanism, the skill still works but runs serially and slowly.
 3. **Models.** The upstream prompts request `sonnet` for synthesis and `haiku` for
    critique. Those are Claude model names — on another host, substitute the host's
    capable/cheap pair (a strong model for synthesis, a fast one for scoring).
 4. **Prompt templates.** Steps 4 and 5 read the `synthesizer-prompt.md` and
-   `critic-prompt.md` files **in this skill's own folder** (`skills/daydream/` in a
-   deployed Geneseed bundle). They ship with the skill — nothing to install.
+   `critic-prompt.md` files **in this skill's own folder** (`<this-skill-directory>/`). They ship with the skill — nothing to install.
 5. **Writable output folders.** The run writes `Daydreams/`, `Daydreams/digests/`,
    `Daily/`, and `ai-research/daydream/history.json` into the vault. If any of those
    sit under a `protected` path in `wiki.jsonc`, the guard plugin will block the write —

package/src/skills/daydream/VENDOR.md

@@ -23,5 +23,13 @@ subagents over recency-weighted note pairs. The model-name references (`sonnet`,
 non-Claude host, read the sibling `synthesizer-prompt.md` / `critic-prompt.md`
 directly and dispatch through whatever subagent mechanism the host provides.
 
-To update, re-copy the upstream folder, re-apply the wiki.jsonc adaptation in
-`SKILL.md` / `instructions.md`, and bump the commit above.
+`SKILL.md` also carries a `name`/`description` frontmatter that upstream lacks — without it
+a host that registers skills from frontmatter (the Agent Skills format: Claude Code, Bob, …)
+never lists the skill — and points the agent at `instructions.md`, which upstream leaves to
+its slash command. Sibling files are named through the this-skill-directory placeholder (see
+`SKILL_DIR_PLACEHOLDER` in `js/hosts/native.mjs`), which the emit resolves for a host that
+does not tell the model where a skill lives.
+
+To update, re-copy the upstream folder, re-apply the wiki.jsonc adaptation, the
+frontmatter and the placeholder paths in `SKILL.md` / `instructions.md`, and
+bump the commit above.

package/src/skills/daydream/instructions.md

@@ -152,7 +152,7 @@ Store the pairs array. Each pair has:
 ## 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`).
+Read `synthesizer-prompt.md` from this skill's own folder to get the prompt template (`<this-skill-directory>/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.
@@ -212,7 +212,7 @@ If a Task agent returns malformed JSON, skip that batch and note the error. Do n
 ## 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`).
+Read `critic-prompt.md` from this skill's own folder to get the prompt template (`<this-skill-directory>/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).

package/src/skills/debug.md

@@ -14,11 +14,11 @@ faster than thrashing; do not trade it away under pressure.
 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).
+4. Apply the smallest fix that addresses the root cause, not the symptom; resist fixing things the evidence doesn't implicate ({{LAW:one-intent-one-act}}). 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 ({{LAW:verify-before-asserting}}) — 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:one-intent-one-act}}).
 
-**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}} VIII) — leftover debug noise in a diff is a defect, not a free comment.
+**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:sealed-secrets}}). Treat every temporary log as disposable: remove or downgrade each `print`/`console.log`/`debugger` before the change ships ({{LAW:cure-the-cause}}) — 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.

package/src/skills/deps-audit.md

@@ -9,7 +9,7 @@ to bump first. migrate moves *one* dependency safely; this {{SKILL}} decides *wh
 *in what order*, and *whether at all*.
 
 ## Procedure
-1. **Inventory from the lockfile, not the manifest** ({{LAW}} III): every direct
+1. **Inventory from the lockfile, not the manifest** ({{LAW:verify-before-asserting}}): every direct
    dependency with its pinned version, and the transitive tree where the tooling
    exposes it. Include vendored or copied-in code the manifest does not list — it is
    a dependency with no update channel.
@@ -23,7 +23,7 @@ to bump first. migrate moves *one* dependency safely; this {{SKILL}} decides *wh
    codebase), *behind by a minor/patch* (usually safe, batchable), *abandoned* (no
    release, no maintainer — plan a replacement, not a bump), *unused* (imported
    nowhere — remove it, the cheapest upgrade there is).
-4. **For a proposed new dependency, ask the ladder first** ({{DOCTRINE}} craft 4): does
+4. **For a proposed new dependency, ask the ladder first** ({{DOCTRINE:search-before-creating}}): does
    the stdlib or an already-installed package cover it, and is the cost of a few lines
    lower than the cost of another maintainer's release cadence, licence, and
    transitive tree? Check who publishes it, how maintained it is, its licence
@@ -31,7 +31,7 @@ to bump first. migrate moves *one* dependency safely; this {{SKILL}} decides *wh
 5. **Order the plan by risk, then blast radius:** reachable security fixes first, then
    removals, then patch/minor batches, then majors one at a time with their changelog
    notes attached. Each major is its own [migrate {{SKILL}}](migrate.md) run on its own
-   branch ({{LAW}} II); never bundle unrelated bumps.
+   branch ({{LAW:one-intent-one-act}}); never bundle unrelated bumps.
 6. **Report and hand off.** A ranked table — dependency, current → target, class,
    reachable?, the note that justifies the rank — plus what was left alone and why.
    Nothing is upgraded by the audit itself; the user picks the tranche and migrate

package/src/skills/develop.md

@@ -9,30 +9,30 @@ case where the seam is only known once the change is made.
 
 ## Procedure
 1. Orient on the project's own documentation for what you are about to touch
-   ({{DOCTRINE}} process 4), and confirm the actual starting state — the suite runs,
-   the baseline is green ({{LAW}} III). A red baseline is a [debug {{SKILL}}](debug.md)
+   ({{DOCTRINE:read-the-docs-first}}), and confirm the actual starting state — the suite runs,
+   the baseline is green ({{LAW:verify-before-asserting}}). A red baseline is a [debug {{SKILL}}](debug.md)
    task first, not something to build on.
 2. Agree the seams: name the public interfaces the tests will target and confirm
    them with the user when they are not obvious — no test is written at an
    unconfirmed seam. Testing effort belongs on critical paths and complex logic,
    not every edge.
-3. Pick the next **smallest slice** that advances the task ({{DOCTRINE}} craft 6), then
+3. Pick the next **smallest slice** that advances the task ({{DOCTRINE:smallest-viable-diff}}), then
    cover it:
    - *Seam known up front* — test-first. Write ONE failing test that pins the slice,
      specific about the expected output (for a bug, the test reproduces it). Run it
      and watch it fail **for the right reason** — a test that passes immediately, or
      fails on a typo, proves nothing.
    - *Seam only clear once the change exists* — write the covering test alongside the
-     change ({{DOCTRINE}} rigor 3), then break the implementation on purpose once to
+     change ({{DOCTRINE:cover-and-verify}}), then break the implementation on purpose once to
      see the test go red before trusting it.
 4. Write the minimum code that makes it pass; add nothing the test doesn't demand.
-5. Run the *affected* tests and read the output ({{LAW}} III); on failure fix the
-   cause, never mask it ({{LAW}} VIII). Dispatch the
+5. Run the *affected* tests and read the output ({{LAW:verify-before-asserting}}); on failure fix the
+   cause, never mask it ({{LAW:cure-the-cause}}). Dispatch the
    [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for heavier or unfamiliar coverage,
    or when the blast radius is unclear.
 6. With the slice green, tidy through the [refactor {{SKILL}}](refactor.md) — the tests
    are the safety net — then commit the slice through the [commit {{SKILL}}](commit.md)
-   ({{DOCTRINE}} process 5). Loop from step 3, one slice at a time.
+   ({{DOCTRINE:consent-before-push}}). Loop from step 3, one slice at a time.
 7. **Exit.** When the last slice is in: run the whole affected suite once more, state
    what was run and its result, and hand over — to the [ship {{SKILL}}](ship.md) when
    the change is ready for a PR, or to the [handoff {{SKILL}}](handoff.md) if the

package/src/skills/document-project.md

@@ -13,8 +13,8 @@ write; with none, step 3 proposes them.
    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,
-   {{DOCTRINE}} process 4). If there is no `ARCHITECTURE.md`, run [repo-map {{SKILL}}](repo-map.md)
+   commands, config, and key directories — read the actual behaviour ({{LAW:verify-before-asserting}},
+   {{DOCTRINE:read-the-docs-first}}). If there is no `ARCHITECTURE.md`, run [repo-map {{SKILL}}](repo-map.md)
    first so you have the orientation map to build on.
 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,
@@ -30,7 +30,7 @@ write; with none, step 3 proposes them.
 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
+   longer exist ({{LAW:deletion-is-deliberate}}). 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
@@ -52,9 +52,9 @@ write; with none, step 3 proposes them.
    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).
+   ({{DOCTRINE: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:
+   ({{LAW:verify-before-asserting}}, {{LAW:deletion-is-deliberate}}). 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
@@ -84,7 +84,7 @@ write; with none, step 3 proposes them.
    (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).
+   on consent, via the [commit {{SKILL}}](commit.md) ({{DOCTRINE:consent-before-push}}).
 
 ## The doc set
 

package/src/skills/explain-changes/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: explain-changes
+description: "Renders one offline HTML page explaining a change — intent, risks, walkthrough, side-by-side git diff — and opens it. Use when the user asks to explain, show or review the changes ('what did you change?', 'show me the diff'), for a branch or PR, or offer it (never impose) before asking to commit a non-trivial change."
+---
+
+# explain-changes
+
+> Turn a diff into a page a human can actually verify: why each part changed, what to check first, and the exact diff beside it.
+
+**Trigger:** the user asks to explain, walk through, show or visualise the changes; you are about to ask consent to commit a non-trivial change (offer the report — never make it a condition); or the user wants a branch or PR explained (`--base <ref>`).
+
+## Division of labour
+
+You write the **brief** — the narrative only. `scripts/render_changes.mjs` runs `git diff` itself and puts the exact diff on the page. Never paste diff lines into the brief: you would pay for them in output tokens and could alter the very thing under review. The script only reads git; it never stages anything.
+
+## Procedure
+
+1. **Measure.** `git diff --cached --shortstat`; if empty, `git diff HEAD --shortstat`; for a branch, `git diff <ref>...HEAD --shortstat`. The shortstat leaves out untracked files, which the report includes when nothing is staged: add `git ls-files --others --exclude-standard | wc -l` (or the host equivalent) to the file count.
+2. **Choose who writes the brief.**
+   - You made the change, and it is under ~300 changed lines and ~10 files: write it yourself from what you already know. Read only the hunks you do not remember (`git diff -- <path>`).
+   - Bigger, a change you did not make, or your context is already heavy: delegate to **one fresh subagent** (the `developer` agent where the host has agents). Hand it the user's request verbatim, your intent notes per logical unit (a few lines each), the diff command, this file's brief rules, and the render command. It returns the report path and three lines. The full diff never enters your context.
+   - No subagents on this host: write the brief one logical unit at a time, reading `git diff -- <paths>` for that unit only.
+3. **Write the brief** as JSON to a temporary file outside the repository (schema below).
+4. **Render.**
+   `node <this-skill-directory>/scripts/render_changes.mjs --brief <brief.json> --out <your notebook directory>` — add `--base <ref>` for a branch. Your notebook directory is named in your root instructions; if this install has none, omit `--out` and the report goes under `.git/explain-changes/`.
+   `--base <ref>` covers committed work only (`<ref>...HEAD`); uncommitted changes are not in it — commit first, or explain them separately without `--base`.
+5. **Fix mismatches.** If the script prints narrative mismatches — a file or hunk you cited that is not in the diff, a changed file no unit explains, an unsafe diagram, no risks — fix the brief and re-run. Never hand over a bannered report.
+6. **Open it.** Windows `start "" "<path>"` from cmd or Git Bash, `Start-Process "<path>"` from PowerShell; macOS `open "<path>"`, Linux `xdg-open "<path>"`. If that fails (headless, SSH, container), print the path instead.
+7. **Hand over** in two lines: the path, and the one risk the user should check first. Before you later ask commit consent, run the script with `--hash`: if it differs from the `diff <hash>` in the report's footer, the diff has changed since — regenerate.
+
+## The brief
+
+```json
+{
+  "lang": "en",
+  "title": "HTTP cache with expiry",
+  "request": "the user's request, verbatim",
+  "summary": "3-5 sentences: what changes for the user or the system, and why",
+  "risks": [
+    { "level": "high", "text": "The cache key ignores auth headers: two users can get each other's response.", "unit": "u2" }
+  ],
+  "units": [
+    {
+      "id": "u1",
+      "kind": "entry point",
+      "title": "The client reads the cache before the network",
+      "why": "1-2 sentences",
+      "files": ["src/http/client.js"],
+      "hunks": { "src/http/client.js": [0, 1] },
+      "out_of_scope": false,
+      "svg": "<svg viewBox=\"0 0 760 150\">…</svg>"
+    }
+  ]
+}
+```
+
+- `request` is the user's words, verbatim — not your summary of them.
+- **Units follow execution order** (entry point → core → effects → tests), not file order. One unit = one intent. `hunks` picks hunks by index; omit it to show every hunk of each file in `files`.
+- **`risks` is the section the reader acts on.** Cover, whenever they exist: assumptions you did not verify; what is untested; files touched outside the request (also mark that unit `"out_of_scope": true`); user-visible behaviour changes (API, config, schema, migrations). You are describing your own work — err toward listing. `level` is `high`, `medium` or `low`. An empty list needs `"risks_none_reason"`.
+- **`svg` only when the change alters a flow between components** — a call sequence, a data model, a state machine. A change local to one file gets none. Hand-written inline SVG, one `<svg>` element and nothing after it; no scripts, event handlers, `foreignObject`, `<style>` (use attributes), animated links, external links or `url()` to anything but a `#fragment` — the script drops unsafe diagrams. Use `currentColor`, `var(--muted)`, `var(--add-ink)`, `var(--del-ink)`, `var(--line)` and `var(--code-bg)` so it follows the page theme.
+- `lang` is `en` or `fr`, matching the user's language; write every text field in that language.
+
+## Privacy
+
+The report contains code. It stays in a git-ignored local path; if the diff holds a secret, the report does too — the same exposure as the diff itself. Never commit or publish a report.
+
+## Done when
+
+- A report built from the current diff exists with no mismatch banner, it is open (or its path given), and the user knows the one risk to check first.

package/src/skills/explain-changes/VENDOR.md

@@ -0,0 +1,20 @@
+# Folder skill — explain-changes
+
+Like `token-report`, this folder is **Geneseed-authored**, not third-party. It rides
+the vendored-folder mechanism because it bundles an executable
+(`scripts/render_changes.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, OpenClaude.
+
+- **Upstream:** this repository (first-party)
+- **License:** same as Geneseed (see repository LICENSE)
+
+Consequences of riding this mechanism (deliberate):
+
+- exempt from the flat-skill authoring gates (theme DESC tokens, dead-link,
+  hermeticity) — the SKILL.md carries its own frontmatter `description`, and it
+  names no themed term: the notebook directory reaches the script as `--out`;
+- listed in AGENT.md's folder-skills section, not the main skills table.
+
+The script needs only `node` and `git`, both already present wherever Geneseed runs.