From bf00b3adea657db8a2d08f396a9fc9d868d6d409 Mon Sep 17 00:00:00 2001
From: mkucharski17 <michal.kucharski17@gmail.com>
Date: Fri, 12 Jun 2026 08:27:41 +0200
Subject: [PATCH] lean-interactive-html: add plugin for generating interactive
 HTML artifacts

Codifies the recurring ask for single-file interactive HTML deliverables
(reports, architecture diagrams, plans, questionnaires, proposals) into a
reusable skill with a copy-first skeleton and per-archetype recipes, so
artifacts share one house style instead of being reinvented per session.
---
 .claude-plugin/marketplace.json               |   9 +
 README.md                                     |   4 +
 .../.claude-plugin/plugin.json                |  21 ++
 plugins/lean-interactive-html/CHANGELOG.md    |   7 +
 plugins/lean-interactive-html/README.md       |  45 ++++
 .../skills/interactive-html/SKILL.md          |  64 +++++
 .../interactive-html/references/archetypes.md | 176 +++++++++++++
 .../interactive-html/references/skeleton.html | 241 ++++++++++++++++++
 .../lean-interactive-html-usage/SKILL.md      |  30 +++
 9 files changed, 597 insertions(+)
 create mode 100644 plugins/lean-interactive-html/.claude-plugin/plugin.json
 create mode 100644 plugins/lean-interactive-html/CHANGELOG.md
 create mode 100644 plugins/lean-interactive-html/README.md
 create mode 100644 plugins/lean-interactive-html/skills/interactive-html/SKILL.md
 create mode 100644 plugins/lean-interactive-html/skills/interactive-html/references/archetypes.md
 create mode 100644 plugins/lean-interactive-html/skills/interactive-html/references/skeleton.html
 create mode 100644 plugins/lean-interactive-html/skills/lean-interactive-html-usage/SKILL.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 8ccadea..00bfef3 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -130,6 +130,15 @@
         "./skills/flutter-read-logs-usage",
         "./skills/read-logs"
       ]
+    },
+    {
+      "name": "lean-interactive-html",
+      "source": "./plugins/lean-interactive-html",
+      "description": "Generate single-file interactive HTML reports, dashboards, plans, architecture diagrams, and decision forms — self-contained, no CDN, no build step, via /interactive-html.",
+      "skills": [
+        "./skills/lean-interactive-html-usage",
+        "./skills/interactive-html"
+      ]
     }
   ]
 }
diff --git a/README.md b/README.md
index 9733f55..111729d 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,10 @@ Most plugins are pure rules and skills with no setup. A few need one-time toolin
 - [`flutter-marionette`](plugins/flutter-marionette/) - runtime interaction with a live debug app through Marionette MCP for exploration, smoke checks, and UI debugging
 - [`flutter-read-logs`](plugins/flutter-read-logs/) - read the running app's latest `flutter run` logs as on-demand context via `/read-logs`
 
+### Docs and reporting
+
+- [`lean-interactive-html`](plugins/lean-interactive-html/) - single-file interactive HTML artifacts (reports, dashboards, plans, architecture diagrams, decision forms) via `/interactive-html` — not Flutter-specific
+
 ### Every plugin has a `-usage` skill
 
 Once a plugin is installed, it exposes a `/<plugin-name>-usage` skill — for example `/flutter-bloc-usage`, `/flutter-cqrs-usage`, `/flutter-ui-usage`. Run it to see what the plugin covers, its conventions, and example prompts to try next. It's the fastest way to learn a plugin without reading its full `README.md`. If you're not sure where to begin, run `/lean-core-usage` for a tour of the whole marketplace.
diff --git a/plugins/lean-interactive-html/.claude-plugin/plugin.json b/plugins/lean-interactive-html/.claude-plugin/plugin.json
new file mode 100644
index 0000000..3e10a7c
--- /dev/null
+++ b/plugins/lean-interactive-html/.claude-plugin/plugin.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "lean-interactive-html",
+  "displayName": "Interactive HTML Artifacts",
+  "description": "Generate single-file interactive HTML reports, dashboards, plans, architecture diagrams, and decision forms.",
+  "version": "0.1.0",
+  "stability": "experimental",
+  "author": {
+    "name": "LeanCode"
+  },
+  "homepage": "https://github.com/leancodepl/ai-plugins",
+  "repository": "https://github.com/leancodepl/ai-plugins",
+  "keywords": [
+    "html",
+    "report",
+    "dashboard",
+    "visualization",
+    "docs"
+  ],
+  "skills": "./skills/"
+}
diff --git a/plugins/lean-interactive-html/CHANGELOG.md b/plugins/lean-interactive-html/CHANGELOG.md
new file mode 100644
index 0000000..d51e9ba
--- /dev/null
+++ b/plugins/lean-interactive-html/CHANGELOG.md
@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial `lean-interactive-html` plugin.
+- `skills/interactive-html/SKILL.md` — generate single-file interactive HTML artifacts via `/interactive-html`, with five archetypes (report, architecture, plan, questionnaire, proposal), a copy-first `skeleton.html`, and per-archetype recipes in `references/archetypes.md`.
+- `skills/lean-interactive-html-usage/SKILL.md` — explain what the plugin does and when to reach for it.
diff --git a/plugins/lean-interactive-html/README.md b/plugins/lean-interactive-html/README.md
new file mode 100644
index 0000000..7f88bac
--- /dev/null
+++ b/plugins/lean-interactive-html/README.md
@@ -0,0 +1,45 @@
+# lean-interactive-html
+
+LeanCode plugin that turns analysis into a single-file interactive HTML artifact you can
+open, click through, and send to someone. Instead of a wall of markdown, you ask:
+
+```
+/interactive-html report summarize this security audit
+```
+
+Claude gathers the real data, builds a self-contained HTML file in the house style, and
+opens it in your browser. Not Flutter-specific — it works in any repo.
+
+## Archetypes
+
+| Archetype | What you get |
+|---|---|
+| `report` | audit / PR-review / stats dashboard: stat cards, status badges, filterable findings, copy-draft button |
+| `architecture` | clickable system diagram: entity boxes, runtime-drawn SVG connectors, detail side panel |
+| `plan` | migration/feature briefing: tabs, phase checklists persisted across reloads, evidence-from-code collapsibles |
+| `questionnaire` | decision form: clickable options, live progress bar, copy-answers button to paste back into the chat |
+| `proposal` | process proposal: current-vs-proposed toggle plus a step-through simulator of the new flow |
+
+The archetype is optional — Claude infers it from the request when omitted.
+
+## Included assets
+
+- `skills/interactive-html/SKILL.md` — the `/interactive-html` workhorse: classifies the
+  request, gathers real data, adapts the skeleton, and opens the result.
+- `skills/interactive-html/references/skeleton.html` — the copy-first base page: design
+  tokens, dark mode, tabs with keyboard shortcuts, stat cards, badges, pure-CSS bar charts,
+  filterable tables, localStorage persistence, and clipboard helpers.
+- `skills/interactive-html/references/archetypes.md` — per-archetype structure and the
+  nontrivial JS recipes (SVG connectors, step-through simulator, sticky answer bar).
+- `skills/lean-interactive-html-usage/SKILL.md` — explains the plugin and routes here.
+
+## Design rules the skill enforces
+
+- **One file, zero dependencies.** No CDN, no frameworks, no fonts from the network, no
+  build step. Recipients open these offline, behind VPNs, from Slack — every external
+  dependency is a way for the file to break on someone else's machine.
+- **Real numbers only.** Every stat must trace to a command Claude actually ran. Invented
+  numbers are the #1 rejection reason for these artifacts.
+- **Audience-aware.** English for anything with an audience beyond the requester; forced
+  dark theme for files sent to other people; no secrets or internal hostnames ever — these
+  files get forwarded.
diff --git a/plugins/lean-interactive-html/skills/interactive-html/SKILL.md b/plugins/lean-interactive-html/skills/interactive-html/SKILL.md
new file mode 100644
index 0000000..e96de61
--- /dev/null
+++ b/plugins/lean-interactive-html/skills/interactive-html/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: interactive-html
+description: Generates a polished single-file interactive HTML artifact — report, stats dashboard, architecture diagram, migration or feature plan, decision questionnaire, process proposal, PR-review or audit summary. Use whenever the user asks for an "interactive html", an HTML report/doc/dashboard/plan, says "show me this in html" or "summarize this as html", or wants a clickable, browsable artifact to review or send to a PO, teammate, or auditor. Always self-contained — no CDN, no frameworks, no build step.
+argument-hint: "[report|architecture|plan|questionnaire|proposal] <topic or data source>"
+---
+
+# Interactive HTML Artifacts
+
+Produce a single self-contained HTML file the user can open, click through, and send to someone. The artifact is a deliverable, not scratch — people forward these to POs, teammates, and auditors.
+
+## Workflow
+
+1. Classify the request into an archetype (table below) from `$ARGUMENTS`; if no archetype is given, infer it from intent and proceed — don't ask.
+2. Decide audience, language, and destination (rules below). If the file will be committed next to existing HTML docs in the target repo, read one of them first and match its style — new repo docs are expected to match the house style.
+3. Gather REAL data: run the `git`/`gh`/`grep` commands that produce every number and claim you will display. Keep the command list — each stat must survive a "where did you take this from?" challenge.
+4. Copy `${CLAUDE_PLUGIN_ROOT}/skills/interactive-html/references/skeleton.html` and adapt — never write the boilerplate from scratch. Read the matching section of [references/archetypes.md](references/archetypes.md) for the chosen archetype.
+5. Embed data as an inline `<script type="application/json">` block or a JS `const` near the top of the script — one place to correct when numbers change.
+6. Write the file to the destination, then ALWAYS open it in the browser (`open <file>` on macOS, `xdg-open` on Linux). The user should never have to ask.
+7. Iterate on feedback (often screenshots). Corrections to facts beat corrections to style — fix the data source, not just the displayed text.
+
+## Archetypes
+
+| Archetype | Use for | Signature elements |
+|---|---|---|
+| `report` | audits, PR reviews, stats dashboards, post-mortems | header with meta chips, big-number stat cards, status badges (In place / Partial / Missing), severity colors, filter buttons, collapsible findings, copy-draft button, pure-CSS bar charts |
+| `architecture` | system or feature architecture docs | one box per entity with per-entity accent colors, SVG connector lines computed at runtime, click-to-inspect detail panel, legend, layer grouping |
+| `plan` | migration plans, feature plans, briefings | tabs with keyboard shortcuts 1–N, overview stat row, filterable table with click-to-expand rows, phase sections, checklist checkboxes persisted to localStorage, collapsible "evidence from code" blocks quoting real files |
+| `questionnaire` | decisions the user answers and pastes back into the chat | one card per question with clickable options, sticky bottom bar with live answer summary and a Copy button producing plain text |
+| `proposal` | process or convention proposals to a team | tabs plus collapsibles, current-vs-proposed toggle, step-through simulator (button-driven log of the proposed flow); ship as a pair: same-basename `.md` and `.html` with identical content |
+
+## Audience, language, destination
+
+- **Language**: English whenever ANY audience beyond the requester exists (PO, teammate, auditor, anything committed). The chat language must never leak into the artifact.
+- **Tone**: informal-professional; jargon only where the audience expects it.
+- **Destination**: committed team doc → the repo's `docs/`; personal or shareable deliverable → `~/Downloads/`; ephemeral review artifact → `/tmp/`.
+
+## Rules
+
+- ONE file, fully self-contained. No `<script src>`, no CDN, no frameworks, no fonts fetched from the network, no build step. Vanilla JS, CSS custom properties in `:root`, system font stack. Charts are pure-CSS bars or inline SVG — never Chart.js/mermaid/d3. Recipients open these offline, behind VPNs, from Slack; every external dependency is a way for the file to break on someone else's machine.
+- Dark mode: `@media (prefers-color-scheme: dark)` for committed repo docs; FORCED always-dark for files sent to other people — their browser theme is unknown.
+- Every number and claim must trace to a command you ran or a file you read. Never estimate, never pad with plausible-sounding stats. Wrong numbers are the #1 rejection reason for these artifacts.
+- Long content needs in-page navigation: tabs or a TOC. Use collapsed-by-default `<details>` for anything secondary.
+- State the user can change (checkboxes, filters, answers) persists to localStorage, keyed by artifact name.
+- Anything the user produces inside the artifact (answers, draft text) gets a copy-to-clipboard button so it can be pasted back into the chat — the artifact is a node in the feedback loop, not a terminal output.
+- Say each fact once. No duplicated stats across sections, no decorative boxes you can't explain, no product or codename branding the user didn't ask for.
+- Never embed secrets, internal hostnames, credentials, or account identifiers — these files get forwarded beyond the original audience.
+
+## Anti-patterns (every one of these caused a rework)
+
+- Invented or unverified numbers. Derive every stat from a command you ran; list raw contributors only after filtering bots and one-off committers.
+- The same information rendered twice in different sections.
+- Boxes, labels, or branding nobody asked for. If you can't justify an element from the source data, delete it.
+- Wrong framing or imprecise naming — calling a milestone "end of project", saying a web app has a "store". Match the domain's actual vocabulary.
+- Chat-language leakage: artifact generated in the chat's language when the audience is international.
+- Light-theme-only files sent to other people.
+- External `<script src>`/CDN — every surviving artifact is dependency-free.
+- Forgetting to open the file after writing it.
+- Diagram connector lines crossing under boxes — compute line endpoints from rendered box positions and redraw on resize.
+- Writing the HTML from scratch instead of copying `skeleton.html`.
+
+## Reach for these references
+
+- [references/skeleton.html](references/skeleton.html) — base page: design tokens, tab machinery, stat cards, badges, bar charts, collapsibles, localStorage + clipboard helpers. Copy and adapt; don't rewrite.
+- [references/archetypes.md](references/archetypes.md) — per-archetype structure, which skeleton blocks to keep or drop, and the nontrivial JS recipes (SVG connectors, step-through simulator, sticky answer bar).
diff --git a/plugins/lean-interactive-html/skills/interactive-html/references/archetypes.md b/plugins/lean-interactive-html/skills/interactive-html/references/archetypes.md
new file mode 100644
index 0000000..d4e7335
--- /dev/null
+++ b/plugins/lean-interactive-html/skills/interactive-html/references/archetypes.md
@@ -0,0 +1,176 @@
+# Archetype recipes
+
+Per-archetype structure: which skeleton blocks to keep, what to add, and the nontrivial JS recipes verbatim. Always start from `skeleton.html`; these sections tell you how to specialize it.
+
+## report
+
+Audits, PR reviews, stats dashboards, post-mortems.
+
+Keep from skeleton: header + chips, stat cards, badges, bar chart, filter row, expandable table, copy button. Drop: tabs if the report fits one page (use a TOC of in-page anchors instead).
+
+Structure, in order:
+
+1. Header — title, one-line scope, chips with the audit/review meta (date, commit range, reviewer).
+2. Stat-card row — the 3–6 numbers that summarize the whole thing.
+3. Status table — one row per checked item, `badge ok/warn/bad` verdicts, click-to-expand evidence.
+4. Findings as `details.expandable`, severity-badged, collapsed by default, each quoting the actual file/line or command output it came from.
+5. Optional "draft response" block with a copy button — e.g. a reply the user can paste to a reviewer or auditor.
+
+## architecture
+
+System or feature architecture documents. The signature element is boxes connected by runtime-computed SVG lines, with a click-to-inspect detail panel.
+
+Keep from skeleton: tokens, header, badges. Add: a `.diagram` container (`position: relative; overflow: hidden`) holding `.row`s of entity boxes and an absolutely-positioned `<svg class="connections">` behind them (`z-index: 1`, boxes at `z-index: 2`, `pointer-events: none` on the svg); a sticky side panel rendering per-entity details from a JS object keyed by `data-key`.
+
+Per-entity accent colors: define `--entityname` and `--entityname-bg` token pairs in `:root` (with dark-mode `-bg` overrides) and a `.block.entityname` class per entity type.
+
+SVG connector recipe — compute endpoints from rendered positions, draw cubic curves with arrowheads and halo-stroked labels, redraw on resize:
+
+```js
+const svg = document.getElementById('connections');
+const diagram = document.getElementById('diagram');
+
+function getCenter(el) {
+  const dr = diagram.getBoundingClientRect();
+  const r = el.getBoundingClientRect();
+  return {
+    cx: r.left + r.width / 2 - dr.left, cy: r.top + r.height / 2 - dr.top,
+    top: r.top - dr.top, bottom: r.bottom - dr.top,
+    left: r.left - dr.left, right: r.right - dr.left,
+  };
+}
+
+function drawLines() {
+  const dr = diagram.getBoundingClientRect();
+  svg.setAttribute('width', dr.width);
+  svg.setAttribute('height', dr.height);
+  const a = getCenter(document.getElementById('block-a'));
+  const b = getCenter(document.getElementById('block-b'));
+  const paths = [{
+    from: { x: a.cx, y: a.bottom }, to: { x: b.cx, y: b.top },
+    cp1: { x: a.cx, y: a.bottom + 60 }, cp2: { x: b.cx, y: b.top - 60 },
+    color: '#2563eb', w: 5, label: 'what flows here',
+    labelAt: { x: a.cx + 18, y: (a.bottom + b.top) / 2 },
+    // dashed: true  — for exception/secondary paths
+  }];
+  const colors = [...new Set(paths.map(p => p.color))];
+  let defs = '<defs>';
+  for (const c of colors) {
+    defs += `<marker id="arrow-${c.replace('#','')}" viewBox="0 0 10 10" refX="9" refY="5"
+      markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="${c}"/></marker>`;
+  }
+  defs += '</defs>';
+  svg.innerHTML = defs + paths.map(p => `
+    <path d="M ${p.from.x},${p.from.y} C ${p.cp1.x},${p.cp1.y} ${p.cp2.x},${p.cp2.y} ${p.to.x},${p.to.y}"
+          fill="none" stroke="${p.color}" stroke-width="${p.w}" stroke-linecap="round"
+          ${p.dashed ? 'stroke-dasharray="12 7"' : ''}
+          marker-end="url(#arrow-${p.color.replace('#','')})" />
+    <text x="${p.labelAt.x}" y="${p.labelAt.y}" fill="${p.color}" font-size="12.5" font-weight="700"
+          paint-order="stroke" stroke="var(--bg)" stroke-width="5">${p.label}</text>`).join('');
+}
+
+const scheduleDraw = () => requestAnimationFrame(drawLines);
+window.addEventListener('load', scheduleDraw);
+window.addEventListener('resize', scheduleDraw);
+if (document.fonts && document.fonts.ready) document.fonts.ready.then(scheduleDraw);
+```
+
+Route curves around boxes (use a side "lane" `x` for the control points when a straight curve would cross a box). Add a legend in the header mapping line colors to meanings.
+
+Detail panel: a `details` JS object keyed by `data-key`, one `renderPanel(key)` function building `innerHTML` from `{ badge, title, sections: [{ h, l: [...] }] }`, click handler on every `.block` toggling an `.active` class.
+
+## plan
+
+Migration plans, feature plans, briefings — content someone works through over days.
+
+Keep from skeleton: everything. Tabs are mandatory (Overview / Phases / Details / FAQ is a good default), with the keyboard shortcuts the skeleton already wires.
+
+Structure:
+
+1. Overview tab — stat row (scope numbers), goal paragraph, timeline or phase list.
+2. One tab or section per phase — each step as a checklist item with a `data-persist` checkbox so progress survives reloads.
+3. Filterable + searchable table of work items, click-to-expand rows holding the per-item details.
+4. "Evidence from code" collapsibles quoting the real files the plan is based on.
+
+## questionnaire
+
+A set of decisions the user answers in the browser and pastes back into the chat. The artifact IS the feedback loop.
+
+Keep from skeleton: tokens, header, copy helper, localStorage. Drop: tabs, stat cards, table.
+
+Structure: one card per question (number, question, context paragraph, 2–4 clickable options + optional free-text input), and a sticky bottom bar showing live progress ("4/7 answered") plus a Copy button that produces a plain-text summary.
+
+Sticky answer bar recipe:
+
+```js
+const answers = JSON.parse(localStorage.getItem(ARTIFACT_KEY + ':answers') || '{}');
+
+function selectOption(qId, value, el) {
+  answers[qId] = value;
+  localStorage.setItem(ARTIFACT_KEY + ':answers', JSON.stringify(answers));
+  el.closest('.options').querySelectorAll('.option').forEach(o => o.classList.remove('selected'));
+  el.classList.add('selected');
+  renderBar();
+}
+
+function renderBar() {
+  const total = document.querySelectorAll('.question-card').length;
+  const done = Object.keys(answers).length;
+  document.getElementById('bar-progress').textContent = `${done}/${total} answered`;
+  document.getElementById('answer-summary').innerText =
+    Object.entries(answers).map(([q, a]) => `${q}: ${a}`).join('\n');
+}
+renderBar();
+```
+
+The copy button copies `#answer-summary` via the skeleton's `copyText` — plain text, one `question: answer` per line, so the user pastes it straight back into the conversation.
+
+CSS: `.option { cursor: pointer; border: 1px solid var(--border); border-radius: 10px; padding: 10px 14px; }`, `.option.selected { border-color: var(--accent); background: var(--accent-bg); }`, bar is `position: sticky; bottom: 0` with a top border.
+
+## proposal
+
+Process or convention proposals to a team — the reader should be able to *try* the proposed flow, not just read it.
+
+Keep from skeleton: tabs (Overview / Try it / Details / FAQ), collapsibles, table. Add: a current-vs-proposed toggle (two content blocks, one visible at a time) and a step-through simulator.
+
+Ship as a pair: a `.md` file and an `.html` file with the same basename and identical content — the markdown is the reviewable/diffable source, the HTML is the presentation. Commit both together and keep them in sync on every edit.
+
+Step-through simulator recipe — buttons drive a state object; every click appends an explained line to a log:
+
+```js
+const START = { /* the initial state of the process being proposed */ };
+let S = JSON.parse(JSON.stringify(START));
+let step = 1;
+const logEl = document.getElementById('log');
+
+function logLine(cls, html) {  // cls: 'info' | 'ok' | 'warnc' | 'err'
+  const line = document.createElement('div');
+  line.className = 'line';
+  line.innerHTML = `<span class="t">${String(step++).padStart(2, '0')}</span><span class="${cls}">${html}</span>`;
+  logEl.appendChild(line);
+  logEl.scrollTop = logEl.scrollHeight;
+}
+
+function render() {
+  // reflect S into the state boxes above the log; disable buttons that are
+  // invalid in the current state (guards teach the rules better than prose)
+}
+
+document.getElementById('action-x').addEventListener('click', () => {
+  // mutate S, logLine() each consequence — including the easy-to-forget ones
+  render();
+});
+
+document.getElementById('action-reset').addEventListener('click', () => {
+  S = JSON.parse(JSON.stringify(START));
+  step = 1; logEl.innerHTML = '';
+  logLine('info', 'Reset. Try: …');
+  render();
+});
+
+logLine('info', 'Start: … Try clicking the guarded action first — the guard will block it.');
+render();
+```
+
+Make invalid actions clickable-but-blocked with an explanatory `err` log line — letting the reader trip the guard is the point. Keep a Reset button.
diff --git a/plugins/lean-interactive-html/skills/interactive-html/references/skeleton.html b/plugins/lean-interactive-html/skills/interactive-html/references/skeleton.html
new file mode 100644
index 0000000..9405820
--- /dev/null
+++ b/plugins/lean-interactive-html/skills/interactive-html/references/skeleton.html
@@ -0,0 +1,241 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>TITLE — one line, matches the h1</title>
+<style>
+  /* ---- Design tokens. Adjust accents per artifact; keep the structure. ---- */
+  :root {
+    --bg: #f6f7fa;
+    --surface: #ffffff;
+    --fg: #0f172a;
+    --muted: #64748b;
+    --border: #cbd5e1;
+    --accent: #2563eb;
+    --accent-bg: #dbeafe;
+    --ok: #047857;
+    --warn: #b45309;
+    --bad: #b91c1c;
+    --info: #6366f1;
+    --code-bg: #e2e8f0;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0b0d11; --surface: #14171c; --fg: #e5e7eb; --muted: #94a3b8;
+      --border: #334155; --accent-bg: #1e3a8a; --code-bg: #1e293b;
+      --ok: #34d399; --warn: #fbbf24; --bad: #f87171; --info: #a5b4fc;
+    }
+  }
+  /* For files SENT TO OTHER PEOPLE: delete the media query above and force dark
+     by moving the dark values into :root — the recipient's browser theme is unknown. */
+
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    background: var(--bg); color: var(--fg);
+    font-family: -apple-system, "SF Pro Text", system-ui, "Segoe UI", Roboto, sans-serif;
+    line-height: 1.5; font-size: 15px;
+  }
+  code {
+    background: var(--code-bg); padding: 1px 6px; border-radius: 4px; font-size: 12.5px;
+    font-family: "SF Mono", ui-monospace, Menlo, Consolas, monospace;
+  }
+  main { max-width: 1040px; margin: 0 auto; padding: 24px 36px 64px; }
+
+  /* ---- Header: title, lead, meta chips ---- */
+  header { padding: 28px 36px 20px; border-bottom: 1px solid var(--border); background: var(--surface); }
+  header .inner { max-width: 1040px; margin: 0 auto; }
+  header h1 { margin: 0 0 4px; font-size: 26px; font-weight: 700; letter-spacing: -0.01em; }
+  header .lead { margin: 0; color: var(--muted); font-size: 14px; }
+  .chips { display: flex; gap: 8px; margin-top: 12px; flex-wrap: wrap; }
+  .chip {
+    font-size: 12px; padding: 3px 10px; border-radius: 999px;
+    background: var(--accent-bg); color: var(--fg); font-weight: 600;
+  }
+
+  /* ---- Tabs (drop if single-page) ---- */
+  nav.tabs { position: sticky; top: 0; background: var(--surface); border-bottom: 1px solid var(--border); z-index: 5; }
+  nav.tabs .inner { max-width: 1040px; margin: 0 auto; display: flex; gap: 2px; }
+  .tab-btn {
+    background: none; border: none; border-bottom: 3px solid transparent; cursor: pointer;
+    padding: 12px 16px; font-size: 14px; font-weight: 600; color: var(--muted);
+  }
+  .tab-btn:hover { color: var(--fg); }
+  .tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); }
+  .tab-panel { display: none; }
+  .tab-panel.active { display: block; }
+
+  /* ---- Stat cards ---- */
+  .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 14px; margin: 20px 0; }
+  .stat { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; padding: 16px 18px; }
+  .stat .num { font-size: 1.8rem; font-weight: 700; color: var(--accent); display: block; line-height: 1.1; }
+  .stat .lbl { font-size: 12px; color: var(--muted); text-transform: uppercase; letter-spacing: .06em; }
+
+  /* ---- Status badges ---- */
+  .badge {
+    display: inline-block; font-size: 12px; font-weight: 700; padding: 2px 10px; border-radius: 999px;
+  }
+  .badge.ok   { background: rgba(4,120,87,.15);  color: var(--ok); }
+  .badge.warn { background: rgba(180,83,9,.15);  color: var(--warn); }
+  .badge.bad  { background: rgba(185,28,28,.15); color: var(--bad); }
+  .badge.info { background: rgba(99,102,241,.15); color: var(--info); }
+
+  /* ---- Pure-CSS bar chart ---- */
+  .bars { display: grid; gap: 8px; margin: 14px 0; }
+  .bar-row { display: grid; grid-template-columns: 160px 1fr 48px; gap: 10px; align-items: center; font-size: 13px; }
+  .bar-track { background: var(--code-bg); border-radius: 6px; height: 14px; overflow: hidden; }
+  .bar-fill { background: var(--accent); height: 100%; border-radius: 6px; }
+  .bar-val { color: var(--muted); text-align: right; }
+
+  /* ---- Collapsible ---- */
+  details.expandable { border: 1px solid var(--border); border-radius: 10px; margin: 10px 0; background: var(--surface); }
+  details.expandable summary { cursor: pointer; padding: 12px 16px; font-weight: 600; user-select: none; }
+  details.expandable .body { padding: 4px 16px 14px; }
+
+  /* ---- Filterable table with expandable rows ---- */
+  .filter-row { margin: 12px 0; display: flex; gap: 6px; flex-wrap: wrap; align-items: center; }
+  .filter-row button {
+    background: var(--surface); border: 1px solid var(--border); border-radius: 999px;
+    padding: 4px 14px; font-size: 13px; cursor: pointer; color: var(--fg);
+  }
+  .filter-row button.active, .filter-row button:hover { background: var(--accent); color: #fff; border-color: var(--accent); }
+  .filter-row input { padding: 6px 12px; border: 1px solid var(--border); border-radius: 8px; background: var(--surface); color: var(--fg); }
+  table { width: 100%; border-collapse: collapse; margin: 12px 0; font-size: 14px; }
+  th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--border); }
+  tr.expandable-row { cursor: pointer; }
+  tr.expandable-row:hover { background: var(--accent-bg); }
+  tr.row-detail { display: none; }
+  tr.row-detail.open { display: table-row; }
+  tr.row-detail td { background: var(--surface); color: var(--muted); }
+
+  /* ---- Copy button ---- */
+  .copy-btn {
+    background: var(--accent); color: #fff; border: none; border-radius: 8px;
+    padding: 8px 16px; font-size: 13px; font-weight: 600; cursor: pointer;
+  }
+  .copy-btn.copied { background: var(--ok); }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="inner">
+    <h1>TITLE</h1>
+    <p class="lead">One-line description · generated DATE · source: COMMANDS-OR-REPO</p>
+    <div class="chips"><span class="chip">meta 1</span><span class="chip">meta 2</span></div>
+  </div>
+</header>
+
+<nav class="tabs">
+  <div class="inner">
+    <button class="tab-btn active" data-tab="tab-overview">Overview</button>
+    <button class="tab-btn" data-tab="tab-details">Details</button>
+  </div>
+</nav>
+
+<main>
+  <section class="tab-panel active" id="tab-overview">
+    <div class="stats">
+      <div class="stat"><span class="num">42</span><span class="lbl">things counted</span></div>
+      <div class="stat"><span class="num">7</span><span class="lbl">other things</span></div>
+    </div>
+    <div class="bars">
+      <div class="bar-row"><span>Label A</span><div class="bar-track"><div class="bar-fill" style="width:80%"></div></div><span class="bar-val">80</span></div>
+      <div class="bar-row"><span>Label B</span><div class="bar-track"><div class="bar-fill" style="width:35%"></div></div><span class="bar-val">35</span></div>
+    </div>
+    <details class="expandable"><summary>Secondary detail <span class="badge ok">In place</span></summary>
+      <div class="body"><p>Collapsed by default. Quote real evidence here.</p></div>
+    </details>
+  </section>
+
+  <section class="tab-panel" id="tab-details">
+    <div class="filter-row">
+      <button class="active" data-filter="all">All</button>
+      <button data-filter="ok">OK</button>
+      <button data-filter="bad">Problems</button>
+      <input type="search" id="table-search" placeholder="Filter rows…">
+    </div>
+    <table id="data-table">
+      <thead><tr><th>Item</th><th>Status</th></tr></thead>
+      <tbody>
+        <tr class="expandable-row" data-status="ok"><td>Row one</td><td><span class="badge ok">OK</span></td></tr>
+        <tr class="row-detail"><td colspan="2">Expanded detail for row one.</td></tr>
+        <tr class="expandable-row" data-status="bad"><td>Row two</td><td><span class="badge bad">Missing</span></td></tr>
+        <tr class="row-detail"><td colspan="2">Expanded detail for row two.</td></tr>
+      </tbody>
+    </table>
+    <label><input type="checkbox" id="check-example" data-persist> Persisted checkbox</label>
+    <p><button class="copy-btn" onclick="copyText('copy-source', this)">Copy summary</button></p>
+    <pre id="copy-source" style="display:none">Plain-text version for pasting back into the chat.</pre>
+  </section>
+</main>
+
+<!-- Embedded data: ONE place to correct when numbers change -->
+<script type="application/json" id="data">
+{ "generated": "DATE", "stats": { "things": 42, "others": 7 } }
+</script>
+
+<script>
+  const ARTIFACT_KEY = 'CHANGE-ME-artifact-name'; // localStorage namespace
+
+  // ---- Tabs + keyboard shortcuts 1..N ----
+  const tabs = document.querySelectorAll('.tab-btn');
+  const panels = document.querySelectorAll('.tab-panel');
+  function activateTab(btn) {
+    tabs.forEach(b => b.classList.remove('active'));
+    panels.forEach(p => p.classList.remove('active'));
+    btn.classList.add('active');
+    document.getElementById(btn.dataset.tab).classList.add('active');
+  }
+  tabs.forEach(btn => btn.addEventListener('click', () => activateTab(btn)));
+  document.addEventListener('keydown', e => {
+    if (e.target.matches('input, textarea')) return;
+    const i = Number(e.key) - 1;
+    if (i >= 0 && i < tabs.length) activateTab(tabs[i]);
+  });
+
+  // ---- Expandable table rows ----
+  document.querySelectorAll('tr.expandable-row').forEach(row => {
+    row.addEventListener('click', () => row.nextElementSibling.classList.toggle('open'));
+  });
+
+  // ---- Status filter + text search ----
+  const filterBtns = document.querySelectorAll('.filter-row button');
+  filterBtns.forEach(btn => btn.addEventListener('click', () => {
+    filterBtns.forEach(b => b.classList.remove('active'));
+    btn.classList.add('active');
+    applyFilters();
+  }));
+  document.getElementById('table-search').addEventListener('input', applyFilters);
+  function applyFilters() {
+    const status = document.querySelector('.filter-row button.active').dataset.filter;
+    const q = document.getElementById('table-search').value.toLowerCase();
+    document.querySelectorAll('#data-table tbody tr.expandable-row').forEach(row => {
+      const show = (status === 'all' || row.dataset.status === status)
+        && row.textContent.toLowerCase().includes(q);
+      row.style.display = show ? '' : 'none';
+      if (!show) row.nextElementSibling.classList.remove('open');
+    });
+  }
+
+  // ---- localStorage persistence for [data-persist] checkboxes ----
+  document.querySelectorAll('input[type=checkbox][data-persist]').forEach(cb => {
+    cb.checked = localStorage.getItem(ARTIFACT_KEY + ':' + cb.id) === '1';
+    cb.addEventListener('change', () =>
+      localStorage.setItem(ARTIFACT_KEY + ':' + cb.id, cb.checked ? '1' : '0'));
+  });
+
+  // ---- Copy to clipboard ----
+  function copyText(sourceId, btn) {
+    const text = document.getElementById(sourceId).innerText;
+    navigator.clipboard.writeText(text).then(() => {
+      btn.classList.add('copied');
+      const old = btn.textContent;
+      btn.textContent = 'Copied';
+      setTimeout(() => { btn.classList.remove('copied'); btn.textContent = old; }, 2000);
+    });
+  }
+</script>
+</body>
+</html>
diff --git a/plugins/lean-interactive-html/skills/lean-interactive-html-usage/SKILL.md b/plugins/lean-interactive-html/skills/lean-interactive-html-usage/SKILL.md
new file mode 100644
index 0000000..4cbb727
--- /dev/null
+++ b/plugins/lean-interactive-html/skills/lean-interactive-html-usage/SKILL.md
@@ -0,0 +1,30 @@
+---
+name: lean-interactive-html-usage
+description: Explain what the `lean-interactive-html` plugin does and how to use it. Use when the user invokes `/lean-interactive-html-usage`, asks what this plugin covers, or needs help generating interactive HTML reports, dashboards, plans, or architecture docs.
+---
+
+# Interactive HTML Usage
+
+## How to respond
+
+- If the user invoked this skill without a concrete task, explain what the plugin does and when to reach for `/interactive-html`.
+- If they already have something to visualize — a plan, an audit, an architecture, stats — briefly explain the fit, then run `/interactive-html`.
+- Do not reply with filler like "skill loaded" or "ready for the task" before explaining the plugin.
+
+## What this plugin does
+
+- Generates polished, single-file interactive HTML artifacts: reports, stats dashboards, architecture diagrams, migration/feature plans, decision questionnaires, and process proposals — via `/interactive-html [archetype] <topic>`.
+- Every artifact is fully self-contained (no CDN, no frameworks, no build step), so it opens offline, behind VPNs, and from Slack on anyone's machine.
+- Ships a copy-first `skeleton.html` (design tokens, tabs, stat cards, badges, filterable tables, localStorage persistence, copy-to-clipboard) plus per-archetype recipes, so artifacts share a consistent house style instead of being reinvented each time.
+
+## When to use it
+
+- "Summarize this audit / PR review as an interactive HTML report."
+- "Draw the architecture of this system as a clickable diagram."
+- "Turn this migration plan into a browsable briefing with progress checkboxes."
+- "Give me an HTML questionnaire for these decisions so I can click through and paste answers back."
+- "Make an interactive proposal of this process change for the team."
+
+## Heads-up
+
+These files get forwarded beyond their original audience — the skill enforces English for any shared artifact and forbids embedding secrets, internal hostnames, or credentials. Every displayed number must trace to a command that was actually run.