diff --git a/docs/MANAGED-FORK.md b/docs/MANAGED-FORK.md
new file mode 100644
index 0000000..e57d170
--- /dev/null
+++ b/docs/MANAGED-FORK.md
@@ -0,0 +1,48 @@
+# Managed fork workflow
+
+This is a **managed fork** of `nicobailon/visual-explainer`. It carries local
+customizations (a standard self-contained favicon, house-style notes) on top of
+upstream, and stays updatable.
+
+## Philosophy: control over automatic
+
+Updates are **on-demand, not automatic**. Nothing pulls upstream behind your
+back — so your local modifications and pinned behavior are never disturbed by a
+surprise merge. When you *do* want to update, it's one command, and a pi agent
+resolves any conflicts with full repository context.
+
+If a session is already current, everything just loads normally with zero work.
+
+## Remotes
+
+| Remote     | Points at                          | Role                         |
+|------------|------------------------------------|------------------------------|
+| `origin`   | `zereraz/visual-explainer`         | your fork (your commits)     |
+| `upstream` | `nicobailon/visual-explainer`      | the original project         |
+
+## Updating
+
+From this clone (`~/Code/Zereraz/visual-explainer`):
+
+```bash
+bash scripts/update-fork.sh --check     # status only; never modifies
+bash scripts/update-fork.sh --apply     # fetch + merge upstream + push + pi update
+# if conflicts (exit 20): resolve files, then:
+bash scripts/update-fork.sh --continue
+```
+
+Or, inside pi, just run the command (loaded with this plugin):
+
+```
+/update-visual-explainer
+```
+
+The command checks first, applies if behind, and if a merge conflict occurs the
+agent resolves it — **keeping both** upstream's new behavior and our additive
+customizations — then commits, pushes, and refreshes the install.
+
+## Making your own changes
+
+Commit directly on `main` (small tweaks) or via a feature branch + PR to your
+own fork. Because our changes are additive, upstream merges are usually clean.
+`scripts/update-fork.sh` verifies the favicon customizations survived each update.
diff --git a/plugins/visual-explainer/SKILL.md b/plugins/visual-explainer/SKILL.md
index ed59377..bb1e17b 100644
--- a/plugins/visual-explainer/SKILL.md
+++ b/plugins/visual-explainer/SKILL.md
@@ -19,6 +19,17 @@ Generate self-contained HTML pages that explain systems, code changes, plans, da
 - Write files to `~/.agent/diagrams/` or the explicit eval output path. Use descriptive filenames.
 - Open generated pages in the browser when running normally. In Pi package installs, use `visual_explainer` with `prepare` for planning/context and `render` only after the complete HTML document exists.
 - The final page must be a complete self-contained HTML document, including embedded CSS and any needed JS.
+- Always include the standard self-contained data-URI favicon immediately after `</title>` (see "Favicon" below). Never leave a page without a favicon.
+
+## Favicon
+
+Every generated page must include this exact self-contained data-URI favicon, placed immediately after the `</title>` tag. It needs no external file and is a small node-graph glyph that matches the dark/accent palette:
+
+```html
+<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIgZmlsbD0iIzBmMTcyOSIvPjxjaXJjbGUgY3g9IjkiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjZDRhNzNhIi8+PGNpcmNsZSBjeD0iMjMiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjNjBhNWZhIi8+PGNpcmNsZSBjeD0iMTYiIGN5PSIyMi41IiByPSIzIiBmaWxsPSIjNGFkZTgwIi8+PHBhdGggZD0iTTkgMTAuNSBMMTYgMjIuNSBMMjMgMTAuNSIgc3Ryb2tlPSIjZDRhNzNhIiBzdHJva2Utd2lkdGg9IjEuNyIgZmlsbD0ibm9uZSIgb3BhY2l0eT0iMC43NSIvPjwvc3ZnPg==">
+```
+
+If math is rendered with KaTeX, escape `<` as `&lt;` inside `$$...$$` (e.g. `y_{&lt;t}`); a bare `<` makes the HTML parser truncate the formula.
 
 ## Reference routing
 
@@ -68,6 +79,7 @@ Read only the references needed for the current output:
 - Good font pair families: DM Sans + Fira Code; Instrument Serif + JetBrains Mono; IBM Plex Sans + IBM Plex Mono; Bricolage Grotesque + Fragment Mono; Plus Jakarta Sans + Azeret Mono.
 - Good accent directions: terracotta+sage, teal+slate, rose+cranberry, amber+emerald, deep blue+gold.
 - Prevent overflow: `min-width: 0` on grid/flex children, `overflow-wrap: break-word` for long text, and scroll containers for wide tables/code.
+- **Labels must never be clipped.** When a badge/tag straddles a box edge (e.g. a code-block filename pill at `top: -12px`), the box must NOT have `overflow: auto/hidden` — that slices the label. Put the scroll on an inner element instead (`overflow: visible` on the badge container, `overflow-x: auto` on the inner `<pre>`/scroller). Likewise keep SVG/mermaid `<text>` inside the viewBox and tab/section labels within their pill.
 - Do not set `display: flex` directly on `<li>` when list markers matter.
 - Use depth sparingly: hero/elevated only for primary sections; flat/recessed for reference material.
 - Use entrance/hover animation only when it clarifies hierarchy. Respect `prefers-reduced-motion`. Do not use continuous glow, pulse, or breathing effects on static content.
@@ -83,15 +95,63 @@ Use slides only when explicitly requested or when a command asks for slides. Sli
 - Do not drop content to fit a fixed slide count. Add slides instead.
 - Use the 10 slide types from `slide-patterns.md`: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed.
 
+## Reader-first defaults (pages are made to be read and re-read)
+
+The primary use is a reader consuming the page, often over multiple sittings. Build for that:
+
+- **Navigation**: ship the upgraded `SlideEngine` from `slide-deck.html` — it adds deep-link hashes (`#slide-7`), resume-where-you-left-off (localStorage), reading percent in the counter, an outline overlay (press `O`), and a keyboard help panel (press `?`). Don't ship a stripped engine.
+- **Comprehension**: open each section with its one-line takeaway, then expand (TL;DR-first). End a multi-section page with a short "what to remember" recap.
+- **Glossary**: wrap domain jargon in `<abbr title="one-line definition">term</abbr>` so a reader can hover/tap for meaning without leaving the page.
+- **Don't gate content on motion**: every slide must be fully readable even if its animation never plays; animations enhance, never reveal essential text.
+- **Accessibility**: don't rely on color alone (pair with shape/label); respect `prefers-reduced-motion`; keep body text ≥ 16px with generous line-height; ensure keyboard nav reaches everything.
+
+## House design language v2 (make it beautiful)
+
+Default look for decks (reference implementation: any deck styled like `the-gradient-view`):
+
+- **Layout is left-anchored assertion–evidence (research-grounded)**: eye-tracking shows readers scan from a strong left edge (F-pattern) — so slides are **left-aligned and top-anchored**, never a small centered core in empty space. The headline is a **full-sentence assertion** (left-justified, ≤2 lines, consistent position across slides = the eye's anchor); the body is **evidence that fills the canvas** (content column up to ~1160px, blocks stretch full-width, base type larger). Related pairs (equation ↔ English reading ↔ numeric trace) sit **side-by-side** in a 2-column `.duo` grid on wide screens (Mayer's spatial-contiguity principle), collapsing to one column under 980px. Slides never compress content to fit the viewport: the slide is `height:100dvh; overflow-y:auto` so tall content **scrolls within the slide** at its natural size (children `flex-shrink:0`; no forced equal-height block pairs; no max-height squeeze media-queries that shrink type). The content group is **vertically centered** (`justify-content:center` + `gap:clamp(6px,1.6vh,18px)`) so slides never leave a dead bottom half. Scale for presence: assertion headline `clamp(26px,4.4vw,52px)`, display math `clamp(19px,2.7vw,28px)` with generous card padding, callouts/traces at reading size `clamp(15px,2vw,19px)` / mono `clamp(12.5px,1.65vw,17px)` — the equation should dominate the slide, not whisper. Verify layout with a headless-Chrome screenshot (`--headless=new --screenshot ... '#slide-N'`, no virtual-time flags) and actually look at it before delivering.
+- **Type system**: `Space Grotesk` for display (titles/heads, tight tracking), `Inter` body, `JetBrains Mono` for code/kickers, and `Instrument Serif` *italic* as the accent voice — `<i>` inside leads/heads renders serif-italic in gold. Title = gradient text (ink → gold → peach).
+- **Depth, not flatness**: body gets two fixed layers — aurora radial glows (gold top-left, sky bottom-right, mint accent) + an SVG-noise grain at ~3% opacity. Surfaces are **glass**: `rgba(255,255,255,.035)` + `backdrop-filter: blur(12-14px)` + 1px `rgba(255,255,255,.09)` border + deep soft shadow + inset top highlight.
+- **Editorial details**: huge **ghost slide numerals** (Space Grotesk, ~4% opacity) top-right of every slide; kickers flanked by gradient hairlines; progress bar is a glowing gold→peach gradient.
+- **Motion**: reveals rise with slight scale + **blur-in** (`blur(6px)→0`), staggered ~90ms; MCQ options nudge right + glow on hover; correct answers get a soft green glow. All gated by `prefers-reduced-motion`.
+- **Color voice**: gold = emphasis/labels, mint = "in english"/success, sky = structure/where, rose = errors/failures, dim slate for prose. Light scheme maps to warm paper (#f7f3ea).
+- Callout grammar: `.eng` (mint glass, ◍ prefix) for English readings; `.trace` (dark glass, ⌁ prefix) for numeric traces; `.ww` chips for where/why. **Blocks size to their content** (`width:fit-content`, capped by the column, sensible min-widths) — never full-width slabs around two words. **No colored left-border accents** on callouts; differentiate by the small-caps label color and surface tint only.
+
+## Learning-first rules (for teaching/explainer decks)
+
+When the deck's purpose is to teach (concepts, math, papers, systems):
+
+- **Honest evidence tags**: label every claim's status with a small pill — `real` (measured, from actual runs/files), `building` (in progress), `planned`, `polluted/void` (known-bad measurement). Never present illustrative numbers as real.
+- **Code + concept travel together**: a formula or concept slide either includes the minimal code it corresponds to, or explicitly signposts "next slide: the code".
+- **Retrieval practice**: end substantial teaching decks with a "Test yourself" slide before the final bleed — 2–3 **clickable multiple-choice questions** (`.mcq` pattern in `templates/slide-deck.html`: click an option → correct answer highlights green, wrong pick red, explanation appears). Plausible distractors, instant feedback. Recall beats re-reading; feedback beats bare recall.
+- **Prediction before reveal**: for the 1–2 headline results, pose the question on its own slide first ("guess before you advance") and reveal on the next. Prediction-then-feedback beats passive presentation — delegated reading scores &lt;40% on comprehension; active inquiry scores far higher.
+- **Shared vocabulary**: name each core concept once with one vivid metaphor (e.g. KL = "leash", mixed data = "soup", repair = "orthogonal fix") and reuse the exact same term + color across every deck in the series. Never introduce synonyms for an established metaphor — shared words are what let author and reader riff.
+- **At most one explorable**: a single small interactive element (slider/toggle driving a formula or plot) is allowed per deck when direct manipulation genuinely teaches the idea (e.g. vary ε and watch the clip region). Never decorative; the deck must teach fully with it inert.
+- **Verify-yourself ending**: decks explaining work an agent did (code, training runs, changes) end with the one command or check the reader can run themselves to confirm the headline claim — the goal is a reader deeper in the loop, not just informed.
+- **Depth-first (do not hide the concept)**: for technical/teaching decks, derive — don't assert. Every mechanism gets three layers on adjacent slides: (1) the math, derived in steps small enough to follow; (2) the concept the math encodes, named plainly; (3) *why it works* — the gradient/information/geometry-level reason. Plug the run's actual numbers into the derivations (real logprobs, real dims, real lr). Status/narrative slides are allowed only as connective tissue between depth slides, never the substance of the deck.
+- **Executable traces**: when a trace derives from raw values (logprobs, logits), compute it **in-page with JS** from the embedded raw data (`.xtrace[data-lps]` and `.xslider` helpers in `templates/slide-deck.html`) instead of hand-typing results — hand arithmetic can silently be wrong; computed traces can be poked.
+- **Fact ledger (provenance + retraction)**: projects with evolving claims keep a ledger (`scripts/facts.py`; JSONL of id/claim/value/source/status). Deck elements citing a ledger fact carry `data-fact="id"`. Retraction = `facts.py void` (one flag), then `facts.py verify *.html` finds every deck citing dead facts. Never state a `real` number that has no source.
+- **Equation anatomy (no untranslated math)**: every displayed equation must be accompanied, on the same slide, by: (a) **where it fits** — one line locating it in the pipeline; (b) **why it exists** — the problem it solves; (c) **its English reading** — the formula spoken as a sentence, symbol by symbol ("loss = how surprised you were by the correct token"); (d) **a raw numeric trace** — concrete input values flowing through the formula to a concrete output (`p=0.344 → L=−ln 0.344=1.068 nats`). An equation without its sentence and its trace is not done.
+- **Series wiring**: when 3+ decks cover one topic, create/refresh an index page (card grid, reading order, one-line summaries) and wire each deck with `data-series-prev/next/index` attributes on `<body>` — the template's series-nav script renders prev/series/next links (keys `N`/`P`). The last deck's `next` points at the index.
+- **Resume never lands on the end**: the engine must not restore a saved position equal to the final slide (start fresh instead); mid-deck resume stays.
+
 ## Optional generated images
 
 If `surf` is available, generated images may be embedded as base64 for hero banners, conceptual illustrations, or educational visuals. Skip images for data-heavy, structural, or Mermaid/CSS-suitable content. Pages must stand on CSS, typography, and diagrams without images.
 
+## Deck build discipline (agent workflow)
+
+- **Engine source of truth**: inject the SlideEngine from `templates/engine.js` in this skill's directory (resolve relative to SKILL.md). Never depend on `/tmp` copies or retype it.
+- **One validation gate**: after writing any deck, run `python3 <repo>/scripts/check-deck.py <file>.html` (managed clone: `~/Code/Zereraz/visual-explainer`). Fix every FAIL before delivering. Do not hand-roll per-deck validation snippets.
+
 ## Final checklist
 
 Before delivery, verify:
 
 - complete HTML document;
+- standard favicon `<link rel="icon">` present immediately after `</title>`;
+- decks use the upgraded SlideEngine (outline `O`, help `?`, deep-link + resume, reading %);
+- each slide readable with animations disabled; no content depends on motion;
 - output written to the requested path;
 - no console errors when opened;
 - no horizontal overflow at normal desktop width;
diff --git a/plugins/visual-explainer/commands/update-visual-explainer.md b/plugins/visual-explainer/commands/update-visual-explainer.md
new file mode 100644
index 0000000..ead865d
--- /dev/null
+++ b/plugins/visual-explainer/commands/update-visual-explainer.md
@@ -0,0 +1,28 @@
+---
+name: update-visual-explainer
+description: Sync this visual-explainer fork with upstream, preserving local customizations; an agent resolves any merge conflicts.
+---
+
+Update the managed `visual-explainer` fork. This is **on-demand** — only run because the user asked.
+
+Managed clone location (try in order; use the first that exists):
+- `~/Code/Zereraz/visual-explainer`
+- the installed package dir: `~/.pi/agent/git/github.com/zereraz/visual-explainer`
+
+Steps:
+
+1. **Check first.** Run `bash scripts/update-fork.sh --check` from the managed clone.
+   - Exit `0` → already up to date. Tell the user "already current (fork is N commits ahead with your customizations)" and stop.
+   - Exit `10` → behind upstream; show the listed upstream commits, then continue.
+
+2. **Apply.** Run `bash scripts/update-fork.sh --apply`.
+   - Exit `0` → clean merge, pushed to the fork, and `pi update` refreshed the install. Report what upstream commits were merged and confirm the local customizations (favicon / house-style) survived. Done.
+   - Exit `20` → **merge conflict**. Do NOT abandon. Resolve it:
+     a. Read each conflicted file (`git diff --name-only --diff-filter=U`).
+     b. For each conflict, **keep the intent of BOTH sides**: upstream's new behavior AND our customizations (the favicon injection in `extension.ts`, favicon lines in `templates/*.html` and `SKILL.md`, the KaTeX `&lt;` note). Our changes are additive — prefer integrating, not discarding.
+     c. After resolving every file, run `bash scripts/update-fork.sh --continue` to commit, push, and reinstall.
+   - Exit `2` → precondition failure (dirty tree / wrong branch). Read the message, fix it (commit/stash local work, or `git checkout main`), then retry.
+
+3. **Verify** after success: confirm `grep -c ensureFavicon plugins/visual-explainer/extension.ts` is non-zero and the 4 templates still contain `rel="icon"`. If a customization was lost in the merge, re-apply it and amend.
+
+Report concisely: what changed upstream, whether conflicts occurred, how they were resolved, and that customizations are intact. $@
diff --git a/plugins/visual-explainer/extension.ts b/plugins/visual-explainer/extension.ts
index 57de38f..ab0c9c8 100644
--- a/plugins/visual-explainer/extension.ts
+++ b/plugins/visual-explainer/extension.ts
@@ -128,6 +128,41 @@ function outputFilename(input: string) {
   return /\.html?$/i.test(raw) ? raw : `${raw}.html`;
 }
 
+const STANDARD_FAVICON =
+  '<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIgZmlsbD0iIzBmMTcyOSIvPjxjaXJjbGUgY3g9IjkiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjZDRhNzNhIi8+PGNpcmNsZSBjeD0iMjMiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjNjBhNWZhIi8+PGNpcmNsZSBjeD0iMTYiIGN5PSIyMi41IiByPSIzIiBmaWxsPSIjNGFkZTgwIi8+PHBhdGggZD0iTTkgMTAuNSBMMTYgMjIuNSBMMjMgMTAuNSIgc3Ryb2tlPSIjZDRhNzNhIiBzdHJva2Utd2lkdGg9IjEuNyIgZmlsbD0ibm9uZSIgb3BhY2l0eT0iMC43NSIvPjwvc3ZnPg==">';
+
+// Guarantees the house-style favicon is present, regardless of what the agent emitted.
+function ensureFavicon(html: string): string {
+  if (/<link\b[^>]*rel\s*=\s*["']?(?:shortcut\s+)?icon/i.test(html)) return html;
+  if (/<\/title>/i.test(html)) return html.replace(/<\/title>/i, `</title>\n${STANDARD_FAVICON}`);
+  if (/<head[^>]*>/i.test(html)) return html.replace(/<head[^>]*>/i, (m) => `${m}\n${STANDARD_FAVICON}`);
+  return html;
+}
+
+// Reader-safety: inside $$...$$ display math, escape < and > so the HTML
+// parser doesn't treat e.g. y_{<t} as a tag and silently truncate the formula.
+// KaTeX decodes entities, so this is semantically lossless. Scoped to $$ (very
+// unlikely to false-match) and skips already-escaped content.
+function fixDisplayMath(html: string): string {
+  return html.replace(/\$\$([\s\S]*?)\$\$/g, (_m, inner: string) => {
+    const fixed = inner.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    return `$$${fixed}$$`;
+  });
+}
+
+// Reader-safety: a complete, well-formed document for any browser/offline read.
+function ensureDocMeta(html: string): string {
+  let out = html;
+  if (!/<html[^>]*\blang=/i.test(out)) out = out.replace(/<html\b/i, '<html lang="en"');
+  if (/<head[^>]*>/i.test(out)) {
+    if (!/<meta[^>]+name=["']viewport/i.test(out))
+      out = out.replace(/<head[^>]*>/i, (m) => `${m}\n<meta name="viewport" content="width=device-width, initial-scale=1.0">`);
+    if (!/<meta[^>]+name=["']theme-color/i.test(out))
+      out = out.replace(/<head[^>]*>/i, (m) => `${m}\n<meta name="theme-color" content="#0f1729">`);
+  }
+  return out;
+}
+
 function assertHtmlDocument(html: string) {
   const trimmed = html.trim();
   if (!trimmed) throw new Error("html is required");
@@ -276,7 +311,9 @@ async function renderVisualExplanation(params: VisualExplainerParams, signal?: A
   }
 
   signal?.throwIfAborted();
-  writeFileSync(outputPath, params.html, "utf8");
+  // Reader-safety pipeline: fix truncating math, complete the doc head, guarantee favicon.
+  const finalHtml = ensureFavicon(ensureDocMeta(fixDisplayMath(params.html)));
+  writeFileSync(outputPath, finalHtml, "utf8");
 
   signal?.throwIfAborted();
 
diff --git a/plugins/visual-explainer/templates/architecture.html b/plugins/visual-explainer/templates/architecture.html
index edc1b43..87f3548 100644
--- a/plugins/visual-explainer/templates/architecture.html
+++ b/plugins/visual-explainer/templates/architecture.html
@@ -4,6 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Architecture Diagram — Reference Template</title>
+<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIgZmlsbD0iIzBmMTcyOSIvPjxjaXJjbGUgY3g9IjkiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjZDRhNzNhIi8+PGNpcmNsZSBjeD0iMjMiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjNjBhNWZhIi8+PGNpcmNsZSBjeD0iMTYiIGN5PSIyMi41IiByPSIzIiBmaWxsPSIjNGFkZTgwIi8+PHBhdGggZD0iTTkgMTAuNSBMMTYgMjIuNSBMMjMgMTAuNSIgc3Ryb2tlPSIjZDRhNzNhIiBzdHJva2Utd2lkdGg9IjEuNyIgZmlsbD0ibm9uZSIgb3BhY2l0eT0iMC43NSIvPjwvc3ZnPg==">
 <!--
   Reference template for the visual-explainer skill: CSS Grid architecture layout.
   Warm terracotta/sage palette — distinctly different from the teal (mermaid)
diff --git a/plugins/visual-explainer/templates/data-table.html b/plugins/visual-explainer/templates/data-table.html
index 42ab069..33462d5 100644
--- a/plugins/visual-explainer/templates/data-table.html
+++ b/plugins/visual-explainer/templates/data-table.html
@@ -4,6 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Requirements Audit — Reference Template</title>
+<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIgZmlsbD0iIzBmMTcyOSIvPjxjaXJjbGUgY3g9IjkiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjZDRhNzNhIi8+PGNpcmNsZSBjeD0iMjMiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjNjBhNWZhIi8+PGNpcmNsZSBjeD0iMTYiIGN5PSIyMi41IiByPSIzIiBmaWxsPSIjNGFkZTgwIi8+PHBhdGggZD0iTTkgMTAuNSBMMTYgMjIuNSBMMjMgMTAuNSIgc3Ryb2tlPSIjZDRhNzNhIiBzdHJva2Utd2lkdGg9IjEuNyIgZmlsbD0ibm9uZSIgb3BhY2l0eT0iMC43NSIvPjwvc3ZnPg==">
 <!--
   Reference template for the visual-explainer skill: data tables.
   Rose/cranberry palette — distinctly different from terracotta (architecture)
diff --git a/plugins/visual-explainer/templates/engine.js b/plugins/visual-explainer/templates/engine.js
new file mode 100644
index 0000000..9accbd0
--- /dev/null
+++ b/plugins/visual-explainer/templates/engine.js
@@ -0,0 +1,90 @@
+function SlideEngine(){
+    this.deck=document.querySelector('.deck');
+    this.slides=[].slice.call(document.querySelectorAll('.slide'));
+    this.current=0;
+    this.total=this.slides.length;
+    this.storeKey='ve:'+location.pathname;
+    this.buildChrome();
+    this.bindEvents();
+    this.observe();
+    this.restore();
+    this.update();
+  }
+  SlideEngine.prototype.titleOf=function(i){
+    var s=this.slides[i];var el=s.querySelector('.slide__display,.slide__heading,blockquote,.slide__kpi-label');
+    var t=el?el.textContent.trim().replace(/\s+/g,' '):''; if(!t){var n=s.querySelector('.slide__number');t=n?'Section '+n.textContent.trim():'Slide '+(i+1);} return t.length>54?t.slice(0,52)+'\u2026':t;
+  };
+  SlideEngine.prototype.buildChrome=function(){
+    var self=this;
+    var bar=document.createElement('div');bar.className='deck-progress';document.body.appendChild(bar);this.bar=bar;
+    var dots=document.createElement('div');dots.className='deck-dots';
+    this.slides.forEach(function(_,i){var d=document.createElement('button');d.className='deck-dot';d.title=self.titleOf(i);d.onclick=function(){self.goTo(i);};dots.appendChild(d);});
+    document.body.appendChild(dots);this.dots=[].slice.call(dots.children);
+    var ctr=document.createElement('div');ctr.className='deck-counter';document.body.appendChild(ctr);this.counter=ctr;
+    var hints=document.createElement('div');hints.className='deck-hints';hints.textContent='\u2190 \u2192 \u00b7 O outline \u00b7 ? help';document.body.appendChild(hints);this.hints=hints;
+    this.hintTimer=setTimeout(function(){hints.classList.add('faded');},4500);
+    // overlay (outline + help share one panel)
+    var ov=document.createElement('div');ov.setAttribute('style','position:fixed;inset:0;z-index:200;display:none;align-items:center;justify-content:center;background:rgba(0,0,0,.55);backdrop-filter:blur(3px)');
+    var panel=document.createElement('div');panel.setAttribute('role','dialog');panel.setAttribute('aria-label','Outline');
+    panel.setAttribute('style','max-height:80vh;overflow:auto;width:min(560px,86vw);background:var(--surface,#162040);color:var(--text,#e8e4d8);border:1px solid var(--border-bright,rgba(200,180,140,.16));border-radius:14px;padding:18px 14px;font-family:var(--font-mono,monospace)');
+    ov.appendChild(panel);document.body.appendChild(ov);this.ov=ov;this.panel=panel;
+    ov.addEventListener('click',function(e){if(e.target===ov)self.closeOverlay();});
+  };
+  SlideEngine.prototype.renderOutline=function(){
+    var self=this;var h='<div style="font-size:12px;letter-spacing:1px;text-transform:uppercase;opacity:.6;margin:2px 8px 12px">Outline</div>';
+    this.slides.forEach(function(_,i){
+      var act=i===self.current;
+      h+='<button data-i="'+i+'" style="display:flex;gap:10px;width:100%;text-align:left;border:none;cursor:pointer;background:'+(act?'var(--accent-dim,rgba(212,167,58,.1))':'transparent')+';color:inherit;padding:8px 10px;border-radius:8px;font-family:inherit;font-size:13px;line-height:1.3"><span style="opacity:.5;min-width:22px">'+(i+1)+'</span><span style="'+(act?'color:var(--accent,#d4a73a)':'')+'">'+self.titleOf(i).replace(/[<>&]/g,function(c){return{'<':'&lt;','>':'&gt;','&':'&amp;'}[c];})+'</span></button>';
+    });
+    this.panel.innerHTML=h;
+    [].slice.call(this.panel.querySelectorAll('button')).forEach(function(b){b.onclick=function(){self.goTo(+b.getAttribute('data-i'));self.closeOverlay();};});
+  };
+  SlideEngine.prototype.renderHelp=function(){
+    this.panel.innerHTML='<div style="font-size:12px;letter-spacing:1px;text-transform:uppercase;opacity:.6;margin:2px 8px 14px">Keyboard</div>'+
+      [['\u2192 / \u2193 / Space','next'],['\u2190 / \u2191','previous'],['Home / End','first / last'],['O','outline'],['? ','this help'],['Esc','close']].map(function(r){
+        return '<div style="display:flex;justify-content:space-between;padding:7px 10px;font-size:13px"><span style="opacity:.7">'+r[1]+'</span><kbd style="background:var(--surface2,#1d2b52);border-radius:5px;padding:2px 8px">'+r[0]+'</kbd></div>';}).join('');
+  };
+  SlideEngine.prototype.openOverlay=function(mode){this.ov.style.display='flex';mode==='help'?this.renderHelp():this.renderOutline();};
+  SlideEngine.prototype.closeOverlay=function(){this.ov.style.display='none';};
+  SlideEngine.prototype.bindEvents=function(){
+    var self=this;
+    document.addEventListener('keydown',function(e){
+      if(e.target.closest('.mermaid-wrap,.table-scroll,.code-scroll,input,textarea,[contenteditable]'))return;
+      if(e.key==='Escape'){self.closeOverlay();return;}
+      var open=self.ov.style.display==='flex';
+      if(e.key==='o'||e.key==='O'){e.preventDefault();open?self.closeOverlay():self.openOverlay('outline');return;}
+      if(e.key==='?'){e.preventDefault();open?self.closeOverlay():self.openOverlay('help');return;}
+      if(open)return;
+      if(['ArrowDown','ArrowRight',' ','PageDown'].indexOf(e.key)>-1){e.preventDefault();self.next();}
+      else if(['ArrowUp','ArrowLeft','PageUp'].indexOf(e.key)>-1){e.preventDefault();self.prev();}
+      else if(e.key==='Home'){e.preventDefault();self.goTo(0);}
+      else if(e.key==='End'){e.preventDefault();self.goTo(self.total-1);}
+      self.fadeHints();
+    });
+    window.addEventListener('hashchange',function(){var i=self.fromHash();if(i!=null&&i!==self.current)self.goTo(i);});
+    var tY;
+    this.deck.addEventListener('touchstart',function(e){tY=e.touches[0].clientY;},{passive:true});
+    this.deck.addEventListener('touchend',function(e){var dy=tY-e.changedTouches[0].clientY;if(Math.abs(dy)>50){dy>0?self.next():self.prev();}});
+  };
+  SlideEngine.prototype.fromHash=function(){var m=/^#(?:slide-)?(\d+)$/.exec(location.hash);if(!m)return null;var i=(+m[1])-1;return(i>=0&&i<this.total)?i:null;};
+  SlideEngine.prototype.restore=function(){
+    var i=this.fromHash();
+    if(i==null){try{var s=localStorage.getItem(this.storeKey);if(s!=null){var j=+s;if(j>0&&j<this.total-1)i=j;}}catch(e){}}
+    if(i!=null&&i>0){var self=this;this.current=i;setTimeout(function(){self.slides[i].scrollIntoView();},60);}
+  };
+  SlideEngine.prototype.observe=function(){
+    var self=this;
+    var obs=new IntersectionObserver(function(entries){entries.forEach(function(entry){if(entry.isIntersecting){entry.target.classList.add('visible');self.current=self.slides.indexOf(entry.target);self.update();}});},{threshold:0.5});
+    this.slides.forEach(function(s){obs.observe(s);});
+  };
+  SlideEngine.prototype.goTo=function(i){i=Math.max(0,Math.min(i,this.total-1));this.slides[i].scrollIntoView({behavior:'smooth'});};
+  SlideEngine.prototype.next=function(){if(this.current<this.total-1)this.goTo(this.current+1);};
+  SlideEngine.prototype.prev=function(){if(this.current>0)this.goTo(this.current-1);};
+  SlideEngine.prototype.update=function(){
+    var c=this.current,pct=Math.round((c+1)/this.total*100);
+    this.bar.style.width=pct+'%';
+    this.dots.forEach(function(d,i){d.classList.toggle('active',i===c);});
+    this.counter.textContent=(c+1)+' / '+this.total+' \u00b7 '+pct+'%';
+    try{history.replaceState(null,'','#slide-'+(c+1));localStorage.setItem(this.storeKey,String(c));}catch(e){}
+  };
+  SlideEngine.prototype.fadeHints=function(){clearTimeout(this.hintTimer);this.hints.classList.add('faded');};
\ No newline at end of file
diff --git a/plugins/visual-explainer/templates/mermaid-flowchart.html b/plugins/visual-explainer/templates/mermaid-flowchart.html
index 170884b..b20fc37 100644
--- a/plugins/visual-explainer/templates/mermaid-flowchart.html
+++ b/plugins/visual-explainer/templates/mermaid-flowchart.html
@@ -4,6 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>CI/CD Pipeline — Reference Template</title>
+<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIgZmlsbD0iIzBmMTcyOSIvPjxjaXJjbGUgY3g9IjkiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjZDRhNzNhIi8+PGNpcmNsZSBjeD0iMjMiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjNjBhNWZhIi8+PGNpcmNsZSBjeD0iMTYiIGN5PSIyMi41IiByPSIzIiBmaWxsPSIjNGFkZTgwIi8+PHBhdGggZD0iTTkgMTAuNSBMMTYgMjIuNSBMMjMgMTAuNSIgc3Ryb2tlPSIjZDRhNzNhIiBzdHJva2Utd2lkdGg9IjEuNyIgZmlsbD0ibm9uZSIgb3BhY2l0eT0iMC43NSIvPjwvc3ZnPg==">
 <!--
   Reference template for the visual-explainer skill: Mermaid diagrams.
   Teal/cyan palette — distinctly different from terracotta (architecture)
diff --git a/plugins/visual-explainer/templates/slide-deck.html b/plugins/visual-explainer/templates/slide-deck.html
index 7f6c6a9..0d627bc 100644
--- a/plugins/visual-explainer/templates/slide-deck.html
+++ b/plugins/visual-explainer/templates/slide-deck.html
@@ -4,6 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>API Gateway Redesign — Reference Slide Deck</title>
+<link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+PHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIgZmlsbD0iIzBmMTcyOSIvPjxjaXJjbGUgY3g9IjkiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjZDRhNzNhIi8+PGNpcmNsZSBjeD0iMjMiIGN5PSIxMC41IiByPSIzIiBmaWxsPSIjNjBhNWZhIi8+PGNpcmNsZSBjeD0iMTYiIGN5PSIyMi41IiByPSIzIiBmaWxsPSIjNGFkZTgwIi8+PHBhdGggZD0iTTkgMTAuNSBMMTYgMjIuNSBMMjMgMTAuNSIgc3Ryb2tlPSIjZDRhNzNhIiBzdHJva2Utd2lkdGg9IjEuNyIgZmlsbD0ibm9uZSIgb3BhY2l0eT0iMC43NSIvPjwvc3ZnPg==">
 <!--
   Reference template for the visual-explainer skill: slide decks.
   Midnight Editorial preset — deep navy, serif display, warm gold accents.
@@ -95,7 +96,7 @@
 
   .slide {
     height: 100dvh;
-    scroll-snap-align: start;
+    scroll-snap-align: start;scroll-snap-stop:always;
     overflow: hidden;
     position: relative;
     display: flex;
@@ -104,16 +105,12 @@
     padding: clamp(40px, 6vh, 80px) clamp(40px, 8vw, 120px);
     isolation: isolate;
     opacity: 0;
-    transform: translateY(40px) scale(0.98);
     transition:
-      opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1),
-      transform 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+      opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1);
   }
 
   .slide.visible {
-    opacity: 1;
-    transform: none;
-  }
+    opacity: 1;}
 
   .slide .reveal {
     opacity: 0;
@@ -584,6 +581,16 @@
     .slide--split .slide__panels { grid-template-columns: 1fr; }
     .slide--dashboard .slide__kpis { grid-template-columns: repeat(2, 1fr); }
   }
+  .katex-display{overflow-x:auto;overflow-y:hidden;max-width:100%;padding-bottom:4px}
+  .mcqwrap{max-width:640px;width:100%;margin-top:8px;max-height:70vh;overflow-y:auto}
+  .mcq{text-align:left;background:var(--surface,#172136);border:1px solid rgba(200,200,210,.15);border-radius:11px;padding:10px 14px;margin-top:8px}
+  .mcq .q{font-weight:600;font-size:clamp(12px,1.7vw,15px);margin-bottom:6px}
+  .mcq button{display:block;width:100%;text-align:left;font:inherit;font-size:clamp(11px,1.5vw,14px);color:inherit;background:rgba(120,140,180,.12);border:1px solid rgba(200,200,210,.25);border-radius:8px;padding:6px 11px;margin-top:5px;cursor:pointer}
+  .mcq.done button{cursor:default;opacity:.6}
+  .mcq.done button.correct{background:rgba(95,217,138,.14);border-color:#5fd98a;color:#5fd98a;opacity:1}
+  .mcq.done button.wrong{background:rgba(251,138,138,.14);border-color:#fb8a8a;color:#fb8a8a;opacity:1}
+  .mcq .why{display:none;margin-top:7px;opacity:.75;font-size:clamp(11px,1.5vw,13px);line-height:1.5}
+  .mcq.done .why{display:block}
 </style>
 </head>
 <body>
@@ -859,58 +866,139 @@ <h2 class="slide__heading reveal">Ship Shadow Mode This Week</h2>
   function zoomDiagram(b,f){var w=b.closest('.mermaid-wrap');var t=w.querySelector('.mermaid');var c=parseFloat(t.dataset.zoom||INITIAL_ZOOM);var n=Math.min(Math.max(c*f,0.5),5);t.dataset.zoom=n;t.style.zoom=n;}
   function resetZoom(b){var w=b.closest('.mermaid-wrap');var t=w.querySelector('.mermaid');t.dataset.zoom=INITIAL_ZOOM;t.style.zoom=INITIAL_ZOOM;}
   function openDiagramFullscreen(b){openMermaidInNewTab(b.closest('.mermaid-wrap'));}
-  function openMermaidInNewTab(w){var svg=w.querySelector('.mermaid svg');if(!svg)return;var clone=svg.cloneNode(true);clone.style.zoom='';clone.style.transform='';var styles=getComputedStyle(document.documentElement);var bg=styles.getPropertyValue('--bg').trim()||'#ffffff';var html='<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Diagram</title><style>body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:'+bg+';padding:40px;box-sizing:border-box}svg{max-width:100%;max-height:90vh;height:auto}</style></head><body>'+clone.outerHTML+'</body></html>';window.open(URL.createObjectURL(new Blob([html],{type:'text/html'})),'_blank');}
+  function openMermaidInNewTab(w){var svg=w.querySelector('.mermaid svg');if(!svg)return;var clone=svg.cloneNode(true);clone.style.zoom='';clone.style.transform='';var styles=getComputedStyle(document.documentElement);var bg=styles.getPropertyValue('--bg').trim()||'#ffffff';var html='<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Diagram</title><style>body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:'+bg+';padding:40px;box-sizing:border-box}svg{max-width:100%;max-height:90vh;height:auto}</style></head><body>'+clone.outerHTML+'<script>(function(){var b=document.body,p=b.getAttribute('data-series-prev'),x=b.getAttribute('data-series-index'),n=b.getAttribute('data-series-next');if(!p&&!n&&!x)return;var d=document.createElement('div');d.style.cssText='position:fixed;bottom:14px;left:16px;z-index:120;font-family:\'JetBrains Mono\',monospace;font-size:11px;display:flex;gap:8px;opacity:.8';function a(h,t){return h?'<a href="'+h+'" style="color:inherit;text-decoration:none;border:1px solid rgba(150,150,160,.35);border-radius:8px;padding:4px 10px;background:rgba(20,25,45,.55)">'+t+'</a>':'';}d.innerHTML=a(p,'\u2039 prev')+a(x,'series')+a(n,'next \u203a');document.body.appendChild(d);document.addEventListener('keydown',function(e){if(e.target.closest('input,textarea,[contenteditable]'))return;if((e.key==='n'||e.key==='N')&&n)location.href=n;else if((e.key==='p'||e.key==='P')&&p)location.href=p;});})();</script>
+<script>document.querySelectorAll('.mcq').forEach(function(m){var a=+m.getAttribute('data-a');var bs=m.querySelectorAll('button');bs.forEach(function(b,i){b.addEventListener('click',function(e){e.stopPropagation();if(m.classList.contains('done'))return;m.classList.add('done');bs[a].classList.add('correct');if(i!==a)b.classList.add('wrong');});});});</script>
+<script>
+// executable traces: <table class="xtrace" data-lps="-1.068,-0.864"> computes p/loss/grad from raw logprobs
+document.querySelectorAll('.xtrace[data-lps]').forEach(function(t){
+  var lps=t.getAttribute('data-lps').split(',').map(Number);
+  var h='<tr><th>token</th><th>logprob (raw)</th><th>p = e^lp</th><th>loss = −lp</th><th>|grad| = 1−p</th></tr>';
+  lps.forEach(function(lp,i){var pr=Math.exp(lp);
+    h+='<tr><td>t'+(i+1)+'</td><td>'+lp.toFixed(3)+'</td><td>'+pr.toFixed(3)+'</td><td>'+(-lp).toFixed(3)+'</td><td>'+(1-pr).toFixed(3)+'</td></tr>';});
+  t.innerHTML=h;});
+// slider: <div class="xslider"></div> — drag a logprob, watch p/loss/grad update
+document.querySelectorAll('.xslider').forEach(function(d){
+  d.innerHTML='<input type="range" min="-6" max="-0.01" step="0.01" value="-1.068" style="width:min(420px,80%)">'+
+    '<div class="xout" style="font-family:monospace;font-size:14px;margin-top:8px"></div>';
+  var r=d.querySelector('input'),o=d.querySelector('.xout');
+  function u(){var lp=+r.value,p=Math.exp(lp);
+    o.textContent='lp='+lp.toFixed(2)+'  →  p='+p.toFixed(3)+'   loss='+(-lp).toFixed(2)+' nats   |grad|='+(1-p).toFixed(3);}
+  r.addEventListener('input',u);u();});
+</script>
+</body></html>';window.open(URL.createObjectURL(new Blob([html],{type:'text/html'})),'_blank');}
   document.querySelectorAll('.mermaid-wrap').forEach(function(w){w.addEventListener('wheel',function(e){if(!e.ctrlKey&&!e.metaKey)return;e.preventDefault();var t=w.querySelector('.mermaid');var c=parseFloat(t.dataset.zoom||INITIAL_ZOOM);var f=e.deltaY<0?1.1:0.9;var n=Math.min(Math.max(c*f,0.5),5);t.dataset.zoom=n;t.style.zoom=n;},{passive:false});var sX,sY,sL,sT,sTime,didPan;w.addEventListener('mousedown',function(e){if(e.target.closest('.zoom-controls'))return;w.classList.add('is-panning');sX=e.clientX;sY=e.clientY;sL=w.scrollLeft;sT=w.scrollTop;sTime=Date.now();didPan=false;});window.addEventListener('mousemove',function(e){if(!w.classList.contains('is-panning'))return;var dx=e.clientX-sX,dy=e.clientY-sY;if(Math.abs(dx)>5||Math.abs(dy)>5)didPan=true;w.scrollLeft=sL-dx;w.scrollTop=sT-dy;});window.addEventListener('mouseup',function(){if(!w.classList.contains('is-panning'))return;w.classList.remove('is-panning');if(!didPan&&Date.now()-sTime<300)openMermaidInNewTab(w);});});
 
-  // SlideEngine
+  // SlideEngine — reader-first: deep-link + resume, outline (O), help (?), reading %.
   function SlideEngine(){
     this.deck=document.querySelector('.deck');
     this.slides=[].slice.call(document.querySelectorAll('.slide'));
     this.current=0;
     this.total=this.slides.length;
+    this.storeKey='ve:'+location.pathname;
     this.buildChrome();
     this.bindEvents();
     this.observe();
+    this.restore();
     this.update();
   }
+  SlideEngine.prototype.titleOf=function(i){
+    var s=this.slides[i];var el=s.querySelector('.slide__display,.slide__heading,blockquote,.slide__kpi-label');
+    var t=el?el.textContent.trim().replace(/\s+/g,' '):''; if(!t){var n=s.querySelector('.slide__number');t=n?'Section '+n.textContent.trim():'Slide '+(i+1);} return t.length>54?t.slice(0,52)+'\u2026':t;
+  };
   SlideEngine.prototype.buildChrome=function(){
+    var self=this;
     var bar=document.createElement('div');bar.className='deck-progress';document.body.appendChild(bar);this.bar=bar;
-    var dots=document.createElement('div');dots.className='deck-dots';var self=this;
-    this.slides.forEach(function(_,i){var d=document.createElement('button');d.className='deck-dot';d.title='Slide '+(i+1);d.onclick=function(){self.goTo(i);};dots.appendChild(d);});
+    var dots=document.createElement('div');dots.className='deck-dots';
+    this.slides.forEach(function(_,i){var d=document.createElement('button');d.className='deck-dot';d.title=self.titleOf(i);d.onclick=function(){self.goTo(i);};dots.appendChild(d);});
     document.body.appendChild(dots);this.dots=[].slice.call(dots.children);
     var ctr=document.createElement('div');ctr.className='deck-counter';document.body.appendChild(ctr);this.counter=ctr;
-    var hints=document.createElement('div');hints.className='deck-hints';hints.textContent='\u2190 \u2192 or scroll to navigate';document.body.appendChild(hints);this.hints=hints;
-    this.hintTimer=setTimeout(function(){hints.classList.add('faded');},4000);
+    var hints=document.createElement('div');hints.className='deck-hints';hints.textContent='\u2190 \u2192 \u00b7 O outline \u00b7 ? help';document.body.appendChild(hints);this.hints=hints;
+    this.hintTimer=setTimeout(function(){hints.classList.add('faded');},4500);
+    // overlay (outline + help share one panel)
+    var ov=document.createElement('div');ov.setAttribute('style','position:fixed;inset:0;z-index:200;display:none;align-items:center;justify-content:center;background:rgba(0,0,0,.55);backdrop-filter:blur(3px)');
+    var panel=document.createElement('div');panel.setAttribute('role','dialog');panel.setAttribute('aria-label','Outline');
+    panel.setAttribute('style','max-height:80vh;overflow:auto;width:min(560px,86vw);background:var(--surface,#162040);color:var(--text,#e8e4d8);border:1px solid var(--border-bright,rgba(200,180,140,.16));border-radius:14px;padding:18px 14px;font-family:var(--font-mono,monospace)');
+    ov.appendChild(panel);document.body.appendChild(ov);this.ov=ov;this.panel=panel;
+    ov.addEventListener('click',function(e){if(e.target===ov)self.closeOverlay();});
   };
+  SlideEngine.prototype.renderOutline=function(){
+    var self=this;var h='<div style="font-size:12px;letter-spacing:1px;text-transform:uppercase;opacity:.6;margin:2px 8px 12px">Outline</div>';
+    this.slides.forEach(function(_,i){
+      var act=i===self.current;
+      h+='<button data-i="'+i+'" style="display:flex;gap:10px;width:100%;text-align:left;border:none;cursor:pointer;background:'+(act?'var(--accent-dim,rgba(212,167,58,.1))':'transparent')+';color:inherit;padding:8px 10px;border-radius:8px;font-family:inherit;font-size:13px;line-height:1.3"><span style="opacity:.5;min-width:22px">'+(i+1)+'</span><span style="'+(act?'color:var(--accent,#d4a73a)':'')+'">'+self.titleOf(i).replace(/[<>&]/g,function(c){return{'<':'&lt;','>':'&gt;','&':'&amp;'}[c];})+'</span></button>';
+    });
+    this.panel.innerHTML=h;
+    [].slice.call(this.panel.querySelectorAll('button')).forEach(function(b){b.onclick=function(){self.goTo(+b.getAttribute('data-i'));self.closeOverlay();};});
+  };
+  SlideEngine.prototype.renderHelp=function(){
+    this.panel.innerHTML='<div style="font-size:12px;letter-spacing:1px;text-transform:uppercase;opacity:.6;margin:2px 8px 14px">Keyboard</div>'+
+      [['\u2192 / \u2193 / Space','next'],['\u2190 / \u2191','previous'],['Home / End','first / last'],['O','outline'],['? ','this help'],['N / P','next / prev deck (series)'],['Esc','close']].map(function(r){
+        return '<div style="display:flex;justify-content:space-between;padding:7px 10px;font-size:13px"><span style="opacity:.7">'+r[1]+'</span><kbd style="background:var(--surface2,#1d2b52);border-radius:5px;padding:2px 8px">'+r[0]+'</kbd></div>';}).join('');
+  };
+  SlideEngine.prototype.openOverlay=function(mode){this.ov.style.display='flex';mode==='help'?this.renderHelp():this.renderOutline();};
+  SlideEngine.prototype.closeOverlay=function(){this.ov.style.display='none';};
   SlideEngine.prototype.bindEvents=function(){
     var self=this;
     document.addEventListener('keydown',function(e){
       if(e.target.closest('.mermaid-wrap,.table-scroll,.code-scroll,input,textarea,[contenteditable]'))return;
+      if(e.key==='Escape'){self.closeOverlay();return;}
+      var open=self.ov.style.display==='flex';
+      if(e.key==='o'||e.key==='O'){e.preventDefault();open?self.closeOverlay():self.openOverlay('outline');return;}
+      if(e.key==='?'){e.preventDefault();open?self.closeOverlay():self.openOverlay('help');return;}
+      if(open)return;
       if(['ArrowDown','ArrowRight',' ','PageDown'].indexOf(e.key)>-1){e.preventDefault();self.next();}
       else if(['ArrowUp','ArrowLeft','PageUp'].indexOf(e.key)>-1){e.preventDefault();self.prev();}
       else if(e.key==='Home'){e.preventDefault();self.goTo(0);}
       else if(e.key==='End'){e.preventDefault();self.goTo(self.total-1);}
       self.fadeHints();
     });
+    window.addEventListener('hashchange',function(){var i=self.fromHash();if(i!=null&&i!==self.current)self.goTo(i);});
     var tY;
     this.deck.addEventListener('touchstart',function(e){tY=e.touches[0].clientY;},{passive:true});
     this.deck.addEventListener('touchend',function(e){var dy=tY-e.changedTouches[0].clientY;if(Math.abs(dy)>50){dy>0?self.next():self.prev();}});
   };
+  SlideEngine.prototype.fromHash=function(){var m=/^#(?:slide-)?(\d+)$/.exec(location.hash);if(!m)return null;var i=(+m[1])-1;return(i>=0&&i<this.total)?i:null;};
+  SlideEngine.prototype.restore=function(){
+    var i=this.fromHash();
+    if(i==null){try{var s=localStorage.getItem(this.storeKey);if(s!=null){var j=+s;if(j>0&&j<this.total-1)i=j;}}catch(e){}}
+    if(i!=null&&i>0){var self=this;this.current=i;setTimeout(function(){self.slides[i].scrollIntoView();},60);}
+  };
   SlideEngine.prototype.observe=function(){
     var self=this;
     var obs=new IntersectionObserver(function(entries){entries.forEach(function(entry){if(entry.isIntersecting){entry.target.classList.add('visible');self.current=self.slides.indexOf(entry.target);self.update();}});},{threshold:0.5});
     this.slides.forEach(function(s){obs.observe(s);});
   };
-  SlideEngine.prototype.goTo=function(i){this.slides[Math.max(0,Math.min(i,this.total-1))].scrollIntoView({behavior:'smooth'});};
+  SlideEngine.prototype.goTo=function(i){i=Math.max(0,Math.min(i,this.total-1));this.slides[i].scrollIntoView({behavior:'smooth'});};
   SlideEngine.prototype.next=function(){if(this.current<this.total-1)this.goTo(this.current+1);};
   SlideEngine.prototype.prev=function(){if(this.current>0)this.goTo(this.current-1);};
   SlideEngine.prototype.update=function(){
-    this.bar.style.width=((this.current+1)/this.total*100)+'%';
-    var c=this.current;this.dots.forEach(function(d,i){d.classList.toggle('active',i===c);});
-    this.counter.textContent=(this.current+1)+' / '+this.total;
+    var c=this.current,pct=Math.round((c+1)/this.total*100);
+    this.bar.style.width=pct+'%';
+    this.dots.forEach(function(d,i){d.classList.toggle('active',i===c);});
+    this.counter.textContent=(c+1)+' / '+this.total+' \u00b7 '+pct+'%';
+    try{history.replaceState(null,'','#slide-'+(c+1));localStorage.setItem(this.storeKey,String(c));}catch(e){}
   };
   SlideEngine.prototype.fadeHints=function(){clearTimeout(this.hintTimer);this.hints.classList.add('faded');};
 </script>
 
+<script>(function(){var b=document.body,p=b.getAttribute('data-series-prev'),x=b.getAttribute('data-series-index'),n=b.getAttribute('data-series-next');if(!p&&!n&&!x)return;var d=document.createElement('div');d.style.cssText='position:fixed;bottom:14px;left:16px;z-index:120;font-family:\'JetBrains Mono\',monospace;font-size:11px;display:flex;gap:8px;opacity:.8';function a(h,t){return h?'<a href="'+h+'" style="color:inherit;text-decoration:none;border:1px solid rgba(150,150,160,.35);border-radius:8px;padding:4px 10px;background:rgba(20,25,45,.55)">'+t+'</a>':'';}d.innerHTML=a(p,'\u2039 prev')+a(x,'series')+a(n,'next \u203a');document.body.appendChild(d);document.addEventListener('keydown',function(e){if(e.target.closest('input,textarea,[contenteditable]'))return;if((e.key==='n'||e.key==='N')&&n)location.href=n;else if((e.key==='p'||e.key==='P')&&p)location.href=p;});})();</script>
+<script>document.querySelectorAll('.mcq').forEach(function(m){var a=+m.getAttribute('data-a');var bs=m.querySelectorAll('button');bs.forEach(function(b,i){b.addEventListener('click',function(e){e.stopPropagation();if(m.classList.contains('done'))return;m.classList.add('done');bs[a].classList.add('correct');if(i!==a)b.classList.add('wrong');});});});</script>
+<script>
+// executable traces: <table class="xtrace" data-lps="-1.068,-0.864"> computes p/loss/grad from raw logprobs
+document.querySelectorAll('.xtrace[data-lps]').forEach(function(t){
+  var lps=t.getAttribute('data-lps').split(',').map(Number);
+  var h='<tr><th>token</th><th>logprob (raw)</th><th>p = e^lp</th><th>loss = −lp</th><th>|grad| = 1−p</th></tr>';
+  lps.forEach(function(lp,i){var pr=Math.exp(lp);
+    h+='<tr><td>t'+(i+1)+'</td><td>'+lp.toFixed(3)+'</td><td>'+pr.toFixed(3)+'</td><td>'+(-lp).toFixed(3)+'</td><td>'+(1-pr).toFixed(3)+'</td></tr>';});
+  t.innerHTML=h;});
+// slider: <div class="xslider"></div> — drag a logprob, watch p/loss/grad update
+document.querySelectorAll('.xslider').forEach(function(d){
+  d.innerHTML='<input type="range" min="-6" max="-0.01" step="0.01" value="-1.068" style="width:min(420px,80%)">'+
+    '<div class="xout" style="font-family:monospace;font-size:14px;margin-top:8px"></div>';
+  var r=d.querySelector('input'),o=d.querySelector('.xout');
+  function u(){var lp=+r.value,p=Math.exp(lp);
+    o.textContent='lp='+lp.toFixed(2)+'  →  p='+p.toFixed(3)+'   loss='+(-lp).toFixed(2)+' nats   |grad|='+(1-p).toFixed(3);}
+  r.addEventListener('input',u);u();});
+</script>
 </body>
 </html>
diff --git a/scripts/check-deck.py b/scripts/check-deck.py
new file mode 100755
index 0000000..c493dc8
--- /dev/null
+++ b/scripts/check-deck.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""check-deck: quality gate for generated visual-explainer HTML.
+
+Usage: check-deck.py file.html [file2.html ...]
+Exit 0 = all pass. Prints one line per check per file.
+"""
+import re
+import sys
+
+FAVICON = 'rel="icon"'
+
+
+def check(path: str) -> bool:
+    s = open(path, encoding="utf-8").read()
+    ok = True
+
+    def r(name, passed, detail=""):
+        nonlocal ok
+        ok = ok and passed
+        print(f"  {'PASS' if passed else 'FAIL'}  {name}" + (f"  ({detail})" if detail and not passed else ""))
+
+    # 1. complete document
+    r("complete html", s.lstrip().lower().startswith("<!doctype html") and "</html>" in s)
+    # 2. favicon right after title
+    r("favicon", FAVICON in s and "</title>" in s)
+    # 3. title + viewport
+    r("title+viewport", "<title>" in s and 'name="viewport"' in s)
+    # 4. raw '<' inside <code> blocks (must be &lt;) — spans allowed
+    bad = 0
+    for b in re.findall(r"<code>(.*?)</code>", s, re.S):
+        t = re.sub(r"</?span[^>]*>", "", b)
+        bad += len(re.findall(r"<(?!span|/)", t))
+    r("code-block escapes", bad == 0, f"{bad} raw '<' in <code>")
+    # 5. raw '<' inside $$...$$ math (KaTeX truncation bug)
+    m = [x for x in re.findall(r"\$\$[^$]{1,400}\$\$", s) if re.search(r"<[^/]", x) and "&lt;" not in x]
+    r("math escapes", not m, f"{len(m)} display-math with raw '<'")
+    # 6. mermaid blocks: no raw '<' except <br>
+    mer = sum(len(re.findall(r"<(?!br)", x)) for x in re.findall(r'<pre class="mermaid">(.*?)</pre>', s, re.S))
+    r("mermaid escapes", mer == 0, f"{mer} raw '<' (non-br)")
+    # 7. slide engine present if it's a deck
+    is_deck = 'class="deck"' in s or "class='deck'" in s
+    if is_deck:
+        r("SlideEngine present", "SlideEngine" in s)
+        r("resume-fix (no land-on-last)", "j<this.total-1" in s.replace(" ", ""))
+        r("scroll-snap-stop", "scroll-snap-stop" in s)
+        # 8. code blocks: badge labels need overflow:visible container
+        if '<div class="code' in s or "class=\"code\"" in s:
+            r("code badge overflow", "overflow:visible" in s.replace(" ", ""))
+    # 8b. display math present => overflow guard required
+    if "$$" in s:
+        r("math overflow guard", "overflow-x:auto" in s.replace(" ", ""), "katex-display needs overflow-x:auto")
+    # 9. no /*ENGINE*/ placeholder left behind
+    r("no leftover placeholder", "/*ENGINE*/" not in s)
+    return ok
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(__doc__)
+        return 2
+    all_ok = True
+    for p in sys.argv[1:]:
+        print(p)
+        all_ok = check(p) and all_ok
+    print("\nRESULT:", "ALL PASS" if all_ok else "FAILURES")
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/facts.py b/scripts/facts.py
new file mode 100755
index 0000000..3c34614
--- /dev/null
+++ b/scripts/facts.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""facts.py — project fact ledger for visual-explainer decks.
+
+A ledger is JSONL: one fact per line:
+  {"id":"lcb-lite","claim":"liver32lite LCB /100","value":"70/100",
+   "source":"lcb_subset_async_any.py output json","ts":"2026-07-01T16:00Z",
+   "status":"real"}          # real | void | superseded | illustrative
+
+Decks reference facts with data-fact="id" on any element.
+
+Usage:
+  facts.py add    <ledger> --id X --claim "..." --value "..." --source "..." [--status real]
+  facts.py void   <ledger> --id X --reason "..."
+  facts.py list   <ledger> [--status real]
+  facts.py verify <ledger> deck1.html [deck2.html ...]   # flag decks citing void/missing facts
+"""
+import argparse
+import datetime
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def load(ledger: Path) -> dict:
+    facts = {}
+    if ledger.exists():
+        for line in ledger.read_text().splitlines():
+            if line.strip():
+                f = json.loads(line)
+                facts[f["id"]] = f  # last write wins
+    return facts
+
+
+def append(ledger: Path, fact: dict) -> None:
+    fact["ts"] = fact.get("ts") or datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%MZ")
+    with ledger.open("a") as fh:
+        fh.write(json.dumps(fact, ensure_ascii=False) + "\n")
+
+
+def cmd_add(a):
+    append(Path(a.ledger), {"id": a.id, "claim": a.claim, "value": a.value,
+                            "source": a.source, "status": a.status})
+    print(f"added {a.id} [{a.status}]")
+
+
+def cmd_void(a):
+    ledger = Path(a.ledger)
+    facts = load(ledger)
+    if a.id not in facts:
+        sys.exit(f"no such fact: {a.id}")
+    f = dict(facts[a.id])
+    f["status"] = "void"
+    f["reason"] = a.reason
+    f.pop("ts", None)
+    append(ledger, f)
+    print(f"voided {a.id}: {a.reason}")
+
+
+def cmd_list(a):
+    for f in load(Path(a.ledger)).values():
+        if a.status and f["status"] != a.status:
+            continue
+        mark = {"real": "✓", "void": "✗", "superseded": "↻", "illustrative": "~"}.get(f["status"], "?")
+        print(f"{mark} {f['id']:26s} {f['value']:>16s}  {f['claim']}  [{f['status']}]"
+              + (f"  reason: {f.get('reason')}" if f.get("reason") else ""))
+
+
+def cmd_verify(a):
+    facts = load(Path(a.ledger))
+    bad = 0
+    for deck in a.decks:
+        s = Path(deck).read_text()
+        ids = re.findall(r'data-fact="([^"]+)"', s)
+        print(deck)
+        if not ids:
+            print("  (no data-fact references)")
+        for i in ids:
+            f = facts.get(i)
+            if not f:
+                print(f"  FAIL  {i}: not in ledger"); bad += 1
+            elif f["status"] in ("void", "superseded"):
+                print(f"  FAIL  {i}: status={f['status']}" + (f" ({f.get('reason','')})" if f.get("reason") else "")); bad += 1
+            else:
+                print(f"  PASS  {i} = {f['value']} [{f['status']}]")
+    print("\nRESULT:", "ALL PASS" if bad == 0 else f"{bad} FAILURES")
+    return 0 if bad == 0 else 1
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="cmd", required=True)
+    for name, fn in [("add", cmd_add), ("void", cmd_void), ("list", cmd_list), ("verify", cmd_verify)]:
+        sp = sub.add_parser(name)
+        sp.add_argument("ledger")
+        sp.set_defaults(fn=fn)
+        if name == "add":
+            sp.add_argument("--id", required=True); sp.add_argument("--claim", required=True)
+            sp.add_argument("--value", required=True); sp.add_argument("--source", required=True)
+            sp.add_argument("--status", default="real")
+        elif name == "void":
+            sp.add_argument("--id", required=True); sp.add_argument("--reason", required=True)
+        elif name == "list":
+            sp.add_argument("--status")
+        elif name == "verify":
+            sp.add_argument("decks", nargs="+")
+    a = p.parse_args()
+    rc = a.fn(a)
+    sys.exit(rc or 0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/update-fork.sh b/scripts/update-fork.sh
new file mode 100755
index 0000000..996500e
--- /dev/null
+++ b/scripts/update-fork.sh
@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Managed-fork updater for visual-explainer.
+#
+# Keeps this fork (origin = your fork) in sync with the original project
+# (upstream = nicobailon/visual-explainer) while preserving your own commits
+# (favicon, house-style, local tweaks). On-demand by design — nothing here
+# runs automatically; invoke it yourself or via the /update-visual-explainer
+# command, which lets a pi agent resolve conflicts with full context.
+#
+# Exit codes (so an agent can branch on them):
+#   0  = up to date OR update applied cleanly
+#   10 = behind upstream (only with --check; no changes made)
+#   20 = merge conflict — working tree left dirty for an agent to resolve
+#   2  = precondition failure (dirty tree, missing remote, etc.)
+#
+# Usage:
+#   update-fork.sh --check       # report status only, never modify
+#   update-fork.sh --apply       # fetch, merge upstream, push, reinstall  (default)
+#   update-fork.sh --continue    # after conflicts are resolved: commit, push, reinstall
+set -euo pipefail
+
+PKG="git:github.com/zereraz/visual-explainer"   # change if your fork lives elsewhere
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+say() { printf '\033[1;33m• %s\033[0m\n' "$*"; }
+err() { printf '\033[1;31m✗ %s\033[0m\n' "$*" >&2; }
+ok()  { printf '\033[1;32m✓ %s\033[0m\n' "$*"; }
+
+mode="${1:---apply}"
+
+require_remotes() {
+  git remote get-url origin   >/dev/null 2>&1 || { err "no 'origin' remote (your fork)"; exit 2; }
+  git remote get-url upstream >/dev/null 2>&1 || {
+    say "adding 'upstream' = nicobailon/visual-explainer"
+    git remote add upstream git@github.com:nicobailon/visual-explainer.git
+  }
+}
+
+reinstall() {
+  if command -v pi >/dev/null 2>&1; then
+    say "refreshing installed package via 'pi update'"
+    pi update "$PKG" || pi install "$PKG"
+    ok "package refreshed"
+  else
+    say "pi CLI not found — skipping reinstall (push is done; run 'pi update $PKG' later)"
+  fi
+}
+
+case "$mode" in
+  --check)
+    require_remotes
+    git fetch --quiet upstream main
+    behind=$(git rev-list --count HEAD..upstream/main)
+    ahead=$(git rev-list --count upstream/main..HEAD)
+    if [ "$behind" -eq 0 ]; then
+      ok "up to date with upstream (your fork is $ahead commit(s) ahead — your customizations)"
+      exit 0
+    fi
+    say "behind upstream by $behind commit(s); your fork is $ahead ahead"
+    git --no-pager log --oneline HEAD..upstream/main | sed 's/^/   upstream: /'
+    exit 10
+    ;;
+
+  --apply)
+    require_remotes
+    if [ -n "$(git status --porcelain)" ]; then
+      err "working tree is dirty — commit or stash first"; git status --short; exit 2
+    fi
+    branch="$(git branch --show-current)"
+    [ "$branch" = "main" ] || { err "expected to be on 'main' (on '$branch')"; exit 2; }
+
+    git fetch --quiet upstream main
+    behind=$(git rev-list --count HEAD..upstream/main)
+    if [ "$behind" -eq 0 ]; then ok "already up to date — nothing to do"; exit 0; fi
+
+    say "merging upstream/main ($behind new commit(s)) into main, keeping your commits"
+    if git merge --no-edit upstream/main; then
+      ok "clean merge"
+      git push origin main
+      ok "pushed to your fork"
+      reinstall
+      exit 0
+    else
+      err "merge conflict — NOT pushing. Resolve, then run: $0 --continue"
+      echo "conflicted files:"; git diff --name-only --diff-filter=U | sed 's/^/   /'
+      exit 20
+    fi
+    ;;
+
+  --continue)
+    require_remotes
+    if git diff --name-only --diff-filter=U | grep -q .; then
+      err "unresolved conflicts remain:"; git diff --name-only --diff-filter=U | sed 's/^/   /'; exit 20
+    fi
+    say "committing resolved merge"
+    git add -A
+    git commit --no-edit || say "nothing to commit (merge may already be committed)"
+    git push origin main
+    ok "pushed to your fork"
+    reinstall
+    exit 0
+    ;;
+
+  *)
+    err "unknown mode '$mode'"; grep -A12 '^# Usage:' "$0" | sed 's/^# \{0,1\}//'; exit 2 ;;
+esac