Single source of truth via assemble.sh splicer

CLAUDE.md

@@ -31,25 +31,27 @@ skills/
   visual-explainer-core/        shared design system (not a user-facing generator)
     SKILL.md
     assets/      core.css, core.js   ← canonical locked theme
+    scripts/     assemble.sh          ← stamps the core into a draft (zero install)
 ```
 
 **SKILL.md is an orchestrator, kept lean.** It carries when-to-use, the process spine, and a
 reference map; everything else (content shapes, diagram/code detail, primitives, checklists) lives in
 `references/*.md` and is pulled in only when needed. When adding guidance, put detail in a reference
 file and link it from SKILL.md — don't grow the always-loaded SKILL.md.
 
-## Shared core + CDN rendering (no build)
+## Shared core + one zero-install assembly step
 
-The locked theme lives once in `skills/visual-explainer-core/assets/` (`core.css`, `core.js`). Each
-domain `templates/template.html` is **fully self-contained**: it embeds an inline copy of that core
-and loads Mermaid + Prism from a CDN. There is **no build step** — fill in the template, replace
-`{{LANGUAGE}}` in the Prism `<script>` tag, and open the file in a browser. (CDN-dependent, so not
-offline; that's the deliberate trade for simplicity.)
+The locked theme lives **once** in `skills/visual-explainer-core/assets/` (`core.css`, `core.js`).
+Each domain `templates/template.html` is a **marker skeleton** — structure, component markup, the
+Mermaid + Prism CDN tags, and two markers (`<!-- @core:css -->` / `<!-- @core:js -->`). To produce an
+explainer: fill the draft, then run
+`bash skills/visual-explainer-core/scripts/assemble.sh <draft> <output.html>`, which stamps the
+canonical theme into the markers. Open the output in a browser. Zero install (awk/bash) — no Node, no
+toolchain; CDN-dependent at view time, so not offline (the deliberate trade for simplicity).
 
-`core.css`/`core.js` are the **canonical** copy; the templates' inline copies must match them. When
-you change the theme, edit the canonical files first, then paste the update into each template's
-`<style>` / `<script>`. This manual sync is the one discipline that keeps the family consistent —
-there is deliberately no build to automate it.
+`core.css`/`core.js` are the **only** copy — templates never embed the theme, so there is nothing to
+hand-sync and the family can't drift. Change the theme by editing the canonical files; every explainer
+assembled afterward picks it up. Never paste theme rules into a template.
 
 **`visual-explainer-core` is intentionally NOT listed in `.claude-plugin/plugin.json`'s `skills`
 array.** It is shared infrastructure and a contributor contract, not a user-facing explainer

README.md

@@ -53,12 +53,12 @@ visual walkthrough"*, or *"compare these 4 approaches side by side."*
   explanation they finish beats a 100% one they don't open.
 - **Real code, not pseudocode.** Snippets are verified against the source so the reader sees the exact
   symbols they'll find in the codebase.
-- **Single-file output, no build.** One HTML file you just open in a browser — it embeds the shared theme and renders Mermaid diagrams + syntax-highlighted code from a CDN. Nothing to install.
+- **Single-file output, nothing to install.** Each explainer is one self-contained HTML file you just open in a browser — the shared theme is stamped in by a tiny zero-install shell step (awk/bash, no Node), and Mermaid diagrams + syntax-highlighted code render from a CDN.
 
 ## Shipped
 
-- Shared design system in `skills/visual-explainer-core/` (canonical `core.css` + `core.js`) — every skill embeds the same theme, so they can't drift.
-- Self-contained CDN templates: copy, fill in, open. Mermaid + Prism render in the browser with the locked theme — no build step, no Node.
+- Shared design system in `skills/visual-explainer-core/` (canonical `core.css` + `core.js`, plus a one-line `assemble.sh` splicer) — the theme lives in exactly one place and is stamped into every explainer, so they can't drift.
+- Marker-based templates: copy, fill in, run the zero-install splicer, open. Mermaid + Prism render in the browser with the locked theme — no toolchain, no Node.
 - Accessibility (WCAG-AA contrast, focus, keyboard), a print/Save-as-PDF stylesheet, and reading-first comprehension aids (scroll-spy, sidenotes, details-on-demand).
 
 ## Roadmap

skills/code-option-comparison/SKILL.md

@@ -40,7 +40,9 @@ Output: **one self-contained HTML file**, typically `docs/comparisons/<topic>.ht
    actually differentiate.
 3. **Verify against the codebase** if any option is "what we have today" or a small extension of it —
    real symbols, real method names, same rule as `software-visual-explainer`.
-4. **Draft from `templates/template.html`**, filling in N column blocks per `references/column-shape.md`.
+4. **Draft from `templates/template.html`** (copy it to a working draft), filling in N column blocks
+   per `references/column-shape.md`. The draft carries `<!-- @core:* -->` markers, not the theme —
+   `assemble.sh` stamps that in (see Rendering).
 5. **Self-review.** Every column answers every axis; the matrix shows all options against all axes;
    no empty cells.
 6. **Offer to review.** Ask the user to spot-check, noting which option you'd recommend and why — the
@@ -56,18 +58,23 @@ This SKILL.md is the orchestrator. Detail lives in the reference files:
 | The pre-completion checklist (content, build, a11y, print) | [`references/verification.md`](references/verification.md) |
 | The HTML skeleton to start from | `templates/template.html` |
 
-## Rendering (CDN, no build)
+## Rendering (one zero-install step)
 
-`templates/template.html` is **fully self-contained**: it embeds the shared core and loads Mermaid +
-Prism from a CDN. There is **no build step**. Write `.mermaid` blocks and `<pre><code class="language-X">`,
-replace `{{LANGUAGE}}` in the Prism `<script>` tag with the language(s) used, and **open the file in a
-browser** — Mermaid renders the diagrams and Prism highlights the code. Nothing to install, no Node.
-(The page needs a network connection to reach the CDN; it is not offline-self-contained.)
+`templates/template.html` is a **marker skeleton**, not the finished page: it has the grid structure,
+the component markup, the Mermaid + Prism CDN tags, and two markers — `<!-- @core:css -->` /
+`<!-- @core:js -->` — where the shared theme is stamped in. To produce the page:
 
-**Do not fork the palette.** The template's `<style>`/`<script>` are an inline copy of
-`visual-explainer-core`'s `core.css`/`core.js`. Never hand-edit the theme in one template — change the
-canonical `core.css`/`core.js` and re-sync (see that skill). Add only comparison-specific components in
-the template's own `<style>` block.
+1. Fill the draft: `.mermaid` blocks, `<pre><code class="language-X">`, and replace `{{LANGUAGE}}` in
+   the Prism `<script>` tag (plus the other `{{…}}` placeholders).
+2. Run `bash ${CLAUDE_PLUGIN_ROOT}/skills/visual-explainer-core/scripts/assemble.sh <draft> <output.html>`
+   — it inlines the canonical `core.css`/`core.js`. Zero install (awk/bash), no Node.
+3. **Open `<output.html>`** — Mermaid renders the diagrams, Prism highlights the code, both from CDN.
+   (Needs a network connection for the CDN; not offline-self-contained.)
+
+**Do not fork the palette.** The theme is never stored in a template — `assemble.sh` stamps in the
+single canonical `core.css`/`core.js`. To change the theme, edit those canonical files (see
+`visual-explainer-core`); never paste theme rules into a template. The comparison-specific components
+live in the draft's own separate `<style>` block, not in the core.
 
 ## Output file location