@praxisflux/gates 0.5.0

package/spec-bridge/lib/spec-derive.mjs

@@ -0,0 +1,114 @@
+// spec-derive.mjs — derive a kanban status from a Spec Kit spec directory.
+//
+// The spec-bridge contract: the spec dir (specs/NNN-feature/) is the source of truth and this
+// module is the ONLY place its lifecycle is interpreted. It is a pure, stateless read — every
+// call re-reads spec.md / plan.md / tasks.md and re-derives, so a regenerated tasks.md
+// (renamed, added, or removed phases) is a non-event: nothing is cached, no residue survives.
+//
+// Status rules (gaps between the canonical Spec Kit stages resolve to the nearer honest state):
+//   - no spec.md                                        -> "To Do"
+//   - spec.md present, not yet Done-eligible            -> "In Progress"
+//   - plan.md present AND tasks.md has >=1 task, all
+//     checked                                           -> "Done-eligible"
+// "Done-eligible" deliberately isn't "Done": the sync skill may move the Backlog task to Done,
+// and the bridge gate treats a Done status without this derivation as a blocking problem.
+//
+// Strict mode ({ requireAnalysis: true }): checked boxes are necessary but weak proof, so
+// Done-eligible additionally requires an analysis report saved as analysis.md in the spec dir
+// (the durable artifact of /speckit.analyze — chat output doesn't count) with no unresolved
+// CRITICAL findings. The scan is line-based: a line containing the word CRITICAL counts as an
+// unresolved finding unless the same line says "resolved" (or carries a checked box).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const STATUS = {
+  TODO: "To Do",
+  IN_PROGRESS: "In Progress",
+  DONE_ELIGIBLE: "Done-eligible",
+};
+
+const PHASE_HEADING = /^##\s+(.+?)\s*$/;
+const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
+
+/** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
+function phaseName(heading) {
+  return heading.replace(/^phase\s+[\d.]+\s*:\s*/i, "").trim() || heading;
+}
+
+/**
+ * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order.
+ * A phase is a `##` heading; a task is any checkbox list line under it. Checkbox lines before
+ * the first heading are collected under a synthetic "Tasks" phase. Phases with no checkbox
+ * lines (e.g. a "Dependencies" notes section) are dropped.
+ */
+export function parseTasks(markdown) {
+  const phases = [];
+  let current = null;
+  for (const line of String(markdown ?? "").split("\n")) {
+    const heading = line.match(PHASE_HEADING);
+    if (heading) {
+      current = { name: phaseName(heading[1]), done: 0, total: 0 };
+      phases.push(current);
+      continue;
+    }
+    const task = line.match(TASK_LINE);
+    if (task) {
+      if (!current) {
+        current = { name: "Tasks", done: 0, total: 0 };
+        phases.push(current);
+      }
+      current.total += 1;
+      if (task[1] !== " ") current.done += 1;
+    }
+  }
+  return phases.filter((p) => p.total > 0);
+}
+
+/** "Setup: 2/2 · Core: 4/7" — one segment per phase, empty string when there are no tasks. */
+export function progressNote(phases) {
+  return phases.map((p) => `${p.name}: ${p.done}/${p.total}`).join(" · ");
+}
+
+/**
+ * Unresolved CRITICAL findings in an analysis report, line-based: any line containing the
+ * word CRITICAL that isn't marked handled on that same line ("resolved" or a checked box).
+ */
+export function findCriticalFindings(markdown) {
+  return String(markdown ?? "")
+    .split("\n")
+    .filter((l) => /\bCRITICAL\b/.test(l) && !/resolved/i.test(l) && !/\[[xX]\]/.test(l))
+    .map((l) => l.trim());
+}
+
+/**
+ * Derive the bridge state for one spec dir. Never throws: unreadable or malformed files
+ * degrade to "that artifact isn't there yet", so a broken dir derives as an early stage
+ * rather than crashing a sync or a Stop hook.
+ */
+export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
+  const has = (name) => existsSync(join(specDir, name));
+  const read = (name) => {
+    try { return has(name) ? readFileSync(join(specDir, name), "utf8") : ""; } catch { return ""; }
+  };
+
+  const phases = parseTasks(read("tasks.md"));
+  const tasksTotal = phases.reduce((n, p) => n + p.total, 0);
+  const tasksDone = phases.reduce((n, p) => n + p.done, 0);
+
+  const analysisPresent = has("analysis.md");
+  const criticals = requireAnalysis && analysisPresent ? findCriticalFindings(read("analysis.md")) : [];
+  const analysisOk = !requireAnalysis || (analysisPresent && criticals.length === 0);
+
+  let status = STATUS.TODO;
+  if (has("spec.md")) {
+    status = has("plan.md") && tasksTotal > 0 && tasksDone === tasksTotal && analysisOk
+      ? STATUS.DONE_ELIGIBLE
+      : STATUS.IN_PROGRESS;
+  }
+
+  return {
+    status, phases, tasksDone, tasksTotal, progressNote: progressNote(phases),
+    analysis: { required: requireAnalysis, present: analysisPresent, criticals },
+  };
+}

package/spec-bridge/lib/template.mjs

@@ -0,0 +1,11 @@
+// template.mjs — the tiny {{PLACEHOLDER}} substitution used when planting boilerplate.
+
+/**
+ * Replace `{{NAME}}` tokens in `text` with `vars[NAME]`. Unknown tokens are left
+ * verbatim so a template can be rendered in passes. Names are `[A-Z0-9_]+`.
+ */
+export function render(text, vars = {}) {
+  return (text || "").replace(/\{\{\s*([A-Z0-9_]+)\s*\}\}/g, (whole, key) =>
+    Object.prototype.hasOwnProperty.call(vars, key) ? String(vars[key]) : whole,
+  );
+}

package/spec-bridge/lib/toolkit/README.md

@@ -0,0 +1,45 @@
+# lib/toolkit — shared educational content modules
+
+Reusable teaching and visual tools shared across the praxis plugins. Where the rest of `lib/`
+is shared *plumbing* (code the gates and scripts import), `toolkit/` is shared *content*:
+authoring guidance and copy-paste CSS/JS snippets a skill reads while producing a deck, course,
+or briefing. The full convention lives in
+[`docs/skill-patterns.md`](../../docs/skill-patterns.md) ("Shared content modules — the toolkit").
+
+The convention in brief:
+
+- **Vendored, not linked.** `scripts/build.mjs` copies `lib/` wholesale into every packaged
+  plugin, so each installed plugin carries its own copy — no runtime cross-plugin dependency.
+- **Referenced as `${CLAUDE_PLUGIN_ROOT}/lib/toolkit/<module>.md`** from skill prose and
+  templates. Gate code doesn't import from toolkit/ (it's content, not plumbing).
+- **Optional, always.** A skill that uses a module must state a one-line inline fallback and
+  still function when the module is absent (graceful degradation).
+- **Styled by the shared token schema.** Snippets use the shared CSS custom-property *names*
+  (see `lib/html/base.html`) so they inherit whichever palette the consuming plugin defines.
+
+## Modules
+
+| Module | What it provides | Status |
+|---|---|---|
+| `tooltip.md` | Jargon-glossary hover/tap tooltip (overflow-safe, mouse + touch; stamped into consumers by `scripts/sync-shared.mjs`) | shipped |
+| `pedagogy.md` | Visual-teaching principles: one idea per screen, show don't tell, lead with the point, split don't shrink, let visuals breathe | shipped |
+| `svg-diagrams.md` | Inline-SVG authoring rules and pitfalls (`<tspan>` not `<b>`, no `var()` in SVG attrs, both-theme colors) | shipped |
+| `code-translation.md` | Code ↔ plain-English translation (rules + zero-JS comments-on-top panel) | shipped |
+| `quiz-patterns.md` | Quiz design (coverage rule, application-not-memory) + zero-JS reveal quiz | shipped |
+| `diagrams.md` | HTML/CSS flow + annotated file-tree diagram idioms | shipped |
+
+## Plugin-owned versioned chrome (indexed here, lives with its owner)
+
+Some shared visual machinery is too heavy and too domain-specific to vendor into every plugin,
+but still needs one canonical, versioned home. Those modules stay in their owning plugin and are
+*indexed* here so "where does shared visual machinery live" has a single answer:
+
+| Chrome | Canonical source | Version | Convention |
+|---|---|---|---|
+| Course chrome (`styles.css`, `main.js`, `_footer.html`, `build.sh`, `validate.mjs`) | `codebase-to-course/skills/codebase-to-course/references/` | `chrome v2 — inline translation engine (comments-on-top)` | `docs/skill-patterns.md` "Versioned course chrome" |
+
+The rules that keep it from fossilizing: rendering files open with the version stamp (no stamp
+= v1, the retired side-by-side renderer); `validate.mjs` carries `CHROME_VERSION`, and both
+`build.sh` and the course gate fail unstamped or version-mixed copies; `build.sh` refreshes the
+chrome from the canonical source whenever `CLAUDE_PLUGIN_ROOT`/`C2C_REFERENCES` resolves.
+Vendored course copies are build artifacts, never templates.

package/spec-bridge/lib/toolkit/code-translation.md

@@ -0,0 +1,50 @@
+# Code ↔ plain-English translation
+
+The single most valuable tool for teaching code to non-technical readers: never show code
+without a plain-English translation of what each line does, and never write a paragraph
+*about* code when you can annotate the code itself. Originally codebase-to-course's pattern.
+
+**Graceful degradation:** if this module isn't available, follow the code with a short
+"in plain English:" list — one bullet per line that matters.
+
+## The rules (medium-independent)
+
+- **Use real code, verbatim.** Never modify, simplify, or trim snippets — the reader should
+  be able to open the file and see exactly what they learned from. *Choose* naturally short,
+  punchy snippets (5–10 lines) instead of butchering long ones.
+- **No horizontal scrollbars, ever.** `white-space: pre-wrap; word-break: break-word` — this
+  is teaching material, not an IDE; readability beats preserved indentation.
+- **One note per line that matters,** in everyday language, positioned so the pairing is
+  unmistakable. Skip noise lines (braces, imports) rather than annotating them emptily.
+- A metaphor inside a note is welcome; jargon inside a note defeats the point (gloss it —
+  see `tooltip.md`).
+
+## Portable snippet (decks, briefings — zero JS)
+
+Comments-on-top: each plain-English note is a styled line directly ABOVE the code it
+explains, inside one token-styled panel. Inherits the consumer's palette.
+
+```html
+<style>
+.translate{background:var(--ink);color:var(--bg);border-radius:12px;padding:1em 1.2em;
+  font-family:var(--mono);font-size:.9em;line-height:1.6;
+  white-space:pre-wrap;word-break:break-word}
+.translate .note{display:block;color:var(--accent2);font-family:var(--sans);
+  font-style:italic;filter:brightness(1.25)}
+</style>
+
+<pre class="translate"><span class="note">// Ask the server for this user's saved items…</span>
+const res = await fetch(`/api/favorites/${userId}`);
+<span class="note">// …and unpack the JSON body once it arrives.</span>
+const favorites = await res.json();</pre>
+```
+
+Deck usage: give the translation its own slide (shared pedagogy — one idea per slide); the
+deck's 30px body type means 4–8 code lines fill a slide comfortably.
+
+## In codebase-to-course
+
+Courses do NOT use this snippet — the prebuilt assets ship a far richer engine (side-by-side
+panels rebuilt as comments-on-top at render time, syntax highlighting, per-block "hide notes"
+toggle). Author against the `.translation-block` contract in the skill's
+`interactive-elements.md`; this module is the portable variant for every other surface.

package/spec-bridge/lib/toolkit/diagrams.md

@@ -0,0 +1,57 @@
+# HTML/CSS diagram idioms
+
+Diagrams that are plain HTML + CSS (boxes, arrows, trees — often with an emoji as the icon)
+inherit the theme tokens, wrap responsively, and never hit SVG's text pitfalls. This is
+codebase-to-course's native diagram idiom, portable to any praxis surface. For hand-drawn
+SVG figures instead, see `svg-diagrams.md`.
+
+**Graceful degradation:** if this module isn't available, a numbered list of steps or an
+indented mono file listing does the job.
+
+## Flow of steps (boxes with arrow separators)
+
+```html
+<style>
+.flow{display:flex;align-items:stretch;gap:0;flex-wrap:wrap}
+.flow .step{flex:1;min-width:9em;background:var(--card);border:1px solid var(--line);
+  border-radius:12px;padding:.8em 1em;text-align:center}
+.flow .step b{display:block;margin-bottom:.25em}
+.flow .arrow{align-self:center;padding:0 .5em;color:var(--muted);font-size:1.4em}
+</style>
+
+<div class="flow">
+  <div class="step">📨 <b>Input</b><span class="muted">the click arrives</span></div>
+  <div class="arrow">→</div>
+  <div class="step">⚙️ <b>Process</b><span class="muted">the server decides</span></div>
+  <div class="arrow">→</div>
+  <div class="step">📬 <b>Output</b><span class="muted">the page updates</span></div>
+</div>
+```
+
+## Annotated file tree
+
+Use instead of paragraphs saying "this folder does X, that folder does Y":
+
+```html
+<style>
+.tree{font-family:var(--mono);background:var(--chip);border:1px solid var(--line);
+  border-radius:12px;padding:1em 1.2em;line-height:1.8;white-space:pre}
+.tree .why{font-family:var(--sans);color:var(--muted);font-style:italic}
+</style>
+
+<div class="tree">src/
+├─ api/        <span class="why">← every route the frontend can call</span>
+├─ models/     <span class="why">← what the data looks like</span>
+└─ jobs/       <span class="why">← work that runs on a schedule</span></div>
+```
+
+Rules: label every box/branch with WHY it matters, not just its name; keep a flow to 3–5
+steps (split longer chains — shared pedagogy: one idea per screen); emoji are icons, pick
+one each, don't decorate.
+
+## In codebase-to-course
+
+Courses get richer, *animated* versions from the prebuilt assets (flow animations, group-chat
+visualizations, interactive architecture diagrams) — author against the contracts in the
+skill's `interactive-elements.md`. These static idioms are the portable variants for decks
+and briefings.

package/spec-bridge/lib/toolkit/pedagogy.md

@@ -0,0 +1,39 @@
+# Visual-teaching principles
+
+The shared pedagogy behind every praxis teaching surface — codebase-to-course's course screens,
+educate's deck slides, research's briefing pages. Written once here; each skill keeps only its
+medium-specific rules (and a one-line distillation as fallback) and points at this module.
+
+**Graceful degradation:** if this module isn't available, the one-liner to keep: *one idea per
+screen; show, don't tell; lead with the point; split, don't shrink.*
+
+## The principles
+
+1. **One idea per screen/slide.** Each unit of display teaches exactly one thing. If it feels
+   crammed, the fix is always MORE screens/slides, never smaller type or denser text. A
+   20-slide deck that's effortless beats a 6-slide deck you squint at.
+
+2. **Show, don't tell.** Eyes glaze over text blocks. Prefer a diagram, card row, flow, code
+   translation, or animation to a paragraph — if you're writing a fourth sentence, stop and
+   convert it into a visual. Aim closer to an infographic than a textbook.
+
+3. **Lead with the point.** State the claim/verdict/takeaway first, then justify it. A briefing
+   leads with the analysis's verdict; a deck leads with the lesson's claim; a course screen
+   leads with the concept, not the buildup. Don't make the reader reverse-engineer the answer.
+
+4. **Split, don't shrink.** Never reduce type, tighten spacing, or trim whitespace to make
+   content fit. Cut words, or add another screen/slide. Readability is the budget everything
+   else pays from.
+
+5. **Let visuals breathe.** A figure that matters gets the room it needs — its own slide, a
+   full-width screen block, generous whitespace around it. Alternate big visuals with narrow
+   text to create rhythm; don't wedge a diagram into a corner.
+
+## How each medium applies them
+
+- **Course screens** (codebase-to-course): every screen ≥50% visual, max 2–3 sentences per text
+  block, one "hero visual" per module — see the skill's `content-philosophy.md`.
+- **Deck slides** (educate): large type is non-negotiable; verify nothing clips at 16:9 — see
+  the deck template's header rules.
+- **Briefing pages** (research): verdict first, every figure traces to the analysis — see
+  `artifact-layer.md`.

package/spec-bridge/lib/toolkit/quiz-patterns.md

@@ -0,0 +1,65 @@
+# Quiz patterns — test application, not memory
+
+A quiz exists to check whether the learner can *use* what they learned on a new problem, not
+whether they can regurgitate a definition. Originally codebase-to-course's quiz doctrine;
+the design rules are medium-independent.
+
+**Graceful degradation:** if this module isn't available, end the lesson/module with 2–3
+"what would you do?" questions in plain prose and discuss the answers.
+
+## The coverage rule (hard requirement)
+
+A question may only use terms, concepts, components, and scenarios the material has already
+introduced *before* the quiz. Applying knowledge to a brand-new situation is the whole point —
+but every term the question leans on must be 100% guaranteed already taught. A learner should
+never hit a quiz and think "we never talked about this." If a great question needs an
+unintroduced concept, teach it first or cut the question.
+
+## What to quiz (in order of value)
+
+1. **"What would you do?" scenarios** — a new situation, apply what you learned. The gold standard.
+2. **Debugging scenarios** — "X is broken; where would you look first?"
+3. **Architecture decisions** — "would you put this logic here or there — and why?"
+4. **Tracing exercises** — "when a user does X, what path does the data take?"
+
+**Never quiz:** definitions (that's what glossing is for), file-name recall, syntax details,
+or anything answerable by scrolling up and copying.
+
+## Tone
+
+Wrong answers get encouraging explanations that teach something new ("Not quite — here's
+why…"); right answers get brief reinforcement of the principle ("Exactly — this works
+because…"). Never punitive, never score-focused.
+
+## Portable snippet (decks, briefings — zero JS)
+
+`<details>`/`<summary>` gives tap-to-reveal answers with no script, keyboard-accessible,
+token-styled:
+
+```html
+<style>
+.quiz details{border:1px solid var(--line);border-radius:10px;margin:.4em 0;
+  background:var(--chip)}
+.quiz summary{cursor:pointer;padding:.55em .9em;font-weight:600}
+.quiz details p{margin:0;padding:.2em .9em .7em;color:var(--muted)}
+.quiz details.right summary{border-left:4px solid var(--accent2)}
+</style>
+
+<div class="quiz">
+  <p><b>You want to add a "save to favorites" feature. Where does the logic live?</b></p>
+  <details><summary>A. In the browser extension</summary>
+    <p>Not quite — the extension only displays data; it never owns it. Look one hop back.</p></details>
+  <details class="right"><summary>B. In the backend API</summary>
+    <p>Exactly — the API owns the data, so a new feature that stores state starts there.</p></details>
+</div>
+```
+
+Deck usage: one question per slide, reveal by tapping — a natural end-of-lesson slide before
+the takeaways.
+
+## In codebase-to-course
+
+Courses do NOT use this snippet — the prebuilt assets ship graded quiz engines
+(multiple-choice, drag-and-drop, spot-the-bug, scenario) with per-answer explanations; author
+against the contracts in the skill's `interactive-elements.md`. The coverage rule above
+applies everywhere.

package/spec-bridge/lib/toolkit/svg-diagrams.md

@@ -0,0 +1,59 @@
+# Inline-SVG diagram rules
+
+Hand-drawn inline SVG is the praxis idiom for explanatory figures (educate decks draw
+diagrams this way; research briefings draw charts as inline SVG). SVG has sharp edges that
+HTML habits walk straight into — these are the hard-won rules, originally from educate's
+deck template.
+
+**Graceful degradation:** if this module isn't available, the two rules to keep: *no
+`<b>`/`<i>` inside SVG `<text>` (use `<tspan>`), and CSS `var(--…)` does not resolve in SVG
+presentation attributes — use literal values.*
+
+## The pitfalls (hard rules)
+
+1. **Never put `<b>` or `<i>` inside an SVG `<text>` element.** HTML formatting tags are
+   invisible-but-broken inside SVG — the text silently fails to render or renders unstyled.
+   Use `<tspan font-weight="700">` / `<tspan font-style="italic">` instead.
+
+2. **CSS `var(--token)` does NOT resolve in SVG presentation attributes** (`fill="var(--accent)"`
+   silently paints black). Use **literal color values** in SVG attributes — and since literals
+   can't follow the theme, pick colors that read on BOTH light and dark backgrounds, or give
+   the figure its own contrasting panel. (`var()` does work in a `style=""` attribute or CSS
+   rule targeting SVG elements — but only for properties CSS controls, and it's easy to get
+   this half-right; literals are the predictable path.)
+
+3. **Size for reflow:** `width:100%; height:auto` on the `<svg>` plus a `viewBox` — never fixed
+   pixel width/height attributes alone, or the figure won't scale with its container.
+
+4. **Accessibility:** `role="img"` and an `aria-label` describing what the diagram shows.
+
+5. **Give the figure room** (shared pedagogy — "let visuals breathe"): a diagram that carries
+   the point gets its own slide / a full-width block, filling most of the available width and
+   height. Don't wedge it beside a paragraph.
+
+## Skeleton — a boxes-and-arrows flow
+
+```html
+<svg viewBox="0 0 800 300" role="img" aria-label="input flows through process to output">
+  <rect x="40" y="110" width="200" height="80" rx="12" fill="#eef0ff" stroke="#4f46e5" stroke-width="2"/>
+  <text x="140" y="158" text-anchor="middle" font-size="26" fill="#1b2733" font-family="sans-serif">Input</text>
+  <line x1="240" y1="150" x2="320" y2="150" stroke="#5a6776" stroke-width="3" marker-end="url(#a)"/>
+  <rect x="320" y="110" width="200" height="80" rx="12" fill="#eefaf7" stroke="#0e9488" stroke-width="2"/>
+  <text x="420" y="158" text-anchor="middle" font-size="26" fill="#1b2733" font-family="sans-serif">Process</text>
+  <defs><marker id="a" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+    <path d="M0,0 L8,3 L0,6 Z" fill="#5a6776"/></marker></defs>
+</svg>
+```
+
+Notes: pastel fills + saturated strokes read on both themes; the `<marker>` def gives every
+arrow a clean head — define it once per SVG and reference with `marker-end="url(#a)"`; keep
+marker `id`s unique per page if a page holds several SVGs.
+
+## Who uses this
+
+- **educate decks** — the native idiom; the deck template's header carries the one-line
+  distillation and a sample diagram slide.
+- **research briefings** — charts are inline SVG; these rules apply on top of the `dataviz`
+  skill's chart guidance.
+- **codebase-to-course** — courses prefer the HTML/CSS + emoji diagram patterns in the skill's
+  `interactive-elements.md`; when a course page does hand-draw inline SVG, these rules apply.

package/spec-bridge/lib/toolkit/tooltip.md

@@ -0,0 +1,83 @@
+# Jargon glossary tooltip
+
+Gloss every technical term where it appears, so the reader never has to leave the page (or
+ask) to decode jargon. The definition rides a `data-tip` attribute; a popover shows it on
+hover (desktop) or tap (touch). This is the single most valuable accessibility feature for
+non-technical audiences — codebase-to-course's content rules call it "No Term Left Behind."
+
+**Graceful degradation:** if this module isn't available, gloss terms in parentheses on
+first use — `the manifest (the file that declares what the extension may do)` — and move on.
+
+## The contract
+
+Any element — HTML *or* SVG — may carry a `data-tip` attribute with a 1–2 sentence,
+everyday-language definition:
+
+```html
+<span data-tip="A service worker is a background script that runs independently of the
+page — a behind-the-scenes assistant that's on even when you're not looking.">service
+worker</span>
+```
+
+- Give the reader a **visible affordance** so glossed terms are discoverable: a dashed
+  underline, or a small `?` badge (educate's decks use the badge — see the deck template's
+  sample slide).
+- Keep definitions to 1–2 sentences, everyday language; a metaphor helps.
+- Gloss on **first use per screen/slide**, not every repetition.
+
+## The snippet
+
+Self-contained, and written against the **shared token names** (`--ink`, `--bg`) so it
+inherits the consuming plugin's palette in both light and dark themes (the bubble is
+inverted-contrast: dark-on-light pages get a dark bubble and vice versa). Popover text size
+follows `--tip-size` (default `1rem`) — decks set it larger. The popover is appended to
+`document.body` with `position: fixed`, so it is **never clipped** by an ancestor's
+`overflow: hidden`, and it hides when printing.
+
+Consumers embed the marked regions verbatim; `scripts/sync-shared.mjs` re-stamps them (drift
+fails the test suite). Hand-edit only here.
+
+```css
+/* praxis:tooltip-css:start */
+[data-tip]{cursor:help}
+.tip-pop{position:fixed;z-index:1000;max-width:min(420px,80vw);background:var(--ink);color:var(--bg);
+  font-size:var(--tip-size,1rem);line-height:1.4;padding:.65em .9em;border-radius:10px;
+  pointer-events:none;box-shadow:0 8px 24px rgba(0,0,0,.28);opacity:0;transform:translateY(4px);
+  transition:opacity .12s ease,transform .12s ease}
+.tip-pop.show{opacity:1;transform:translateY(0)}
+@media print{ .tip-pop{display:none} }
+/* praxis:tooltip-css:end */
+```
+
+```js
+// praxis:tooltip-js:start
+// One shared popover: follows the cursor on hover, toggles on click/tap (touch), clamps to
+// the viewport, and closes on tap-away. Works for HTML and SVG [data-tip] elements alike.
+(function(){
+  const pop=document.createElement('div'); pop.className='tip-pop'; document.body.appendChild(pop);
+  let shownFor=null;
+  const place=(x,y)=>{ const pad=14, r=pop.getBoundingClientRect();
+    let px=x+pad, py=y+pad;
+    if(px+r.width>innerWidth-8) px=Math.max(8,x-r.width-pad);
+    if(py+r.height>innerHeight-8) py=Math.max(8,y-r.height-pad);
+    pop.style.left=px+'px'; pop.style.top=py+'px'; };
+  const show=(t,x,y)=>{ pop.textContent=t.getAttribute('data-tip'); pop.classList.add('show'); shownFor=t; place(x,y); };
+  const hide=()=>{ pop.classList.remove('show'); shownFor=null; };
+  document.addEventListener('mouseover',e=>{ const t=e.target.closest&&e.target.closest('[data-tip]'); if(t) show(t,e.clientX,e.clientY); });
+  document.addEventListener('mousemove',e=>{ if(shownFor) place(e.clientX,e.clientY); });
+  document.addEventListener('mouseout',e=>{ const t=e.target.closest&&e.target.closest('[data-tip]'); if(t && !t.contains(e.relatedTarget)) hide(); });
+  document.addEventListener('click',e=>{ const t=e.target.closest&&e.target.closest('[data-tip]');
+    if(t){ e.stopPropagation(); (shownFor===t)?hide():show(t,e.clientX,e.clientY); } else hide(); });
+})();
+// praxis:tooltip-js:end
+```
+
+## Where each plugin gets it
+
+- **educate decks** — the deck template carries the stamped regions; nothing to author.
+- **research briefings** — copy both regions into the page (alongside the base.html blocks).
+- **codebase-to-course pages** — courses do NOT use this snippet: the prebuilt assets
+  (`references/styles.css` + `references/main.js`, copied verbatim into every course) ship
+  the same pattern as a course-native engine with the `.term` + `data-definition` contract
+  and a dashed-underline affordance. Author course HTML against that contract and never
+  inline tooltip CSS/JS there (see the skill's `interactive-elements.md`).