haac-aikit 0.10.0 → 0.11.1

package/README.md

@@ -4,78 +4,31 @@
 [![GitHub](https://img.shields.io/badge/github-Hamad--Center%2Fhaac--aikit-blue?logo=github)](https://github.com/Hamad-Center/haac-aikit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-One command drops a working AI-coding setup into any repo — rules, skills, safety hooks, subagents, MCP stub, CI templates — for Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini CLI, and Codex.
-
-> [!TIP]
-> **Just want HTML output from Claude Code?** Skip the full kit and install only the html-artifacts skill + 20 templates:
->
-> ```bash
-> npx haac-aikit init html
-> ```
-
-## Quickstart
+**Docs that update themselves.** A cross-tool AI-coding kit (Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini, Codex) that drops opinionated rules + skills + safety hooks into any repo. Headline feature: two new skills that maintain your project's HTML documentation and decision log as the code changes.
 
 ```bash
 npx haac-aikit
 ```
 
-30-second wizard, writes a `.aikitrc.json` you can commit. Re-run anytime with `aikit sync`.
-
-For CI or scripts:
-
-```bash
-npx haac-aikit --yes --tools=claude,cursor,copilot --preset=standard
-```
-
-## What you get
-
-### Minimal scope
-
-| File | Purpose |
-|---|---|
-| `AGENTS.md` | Canonical rules — your edits outside BEGIN/END markers are never touched |
-| `CLAUDE.md` | Five-line shim that imports `@AGENTS.md` |
-| `.cursor/rules/000-base.mdc` | Dialect-translated MDC (not a generic copy) |
-| Per-tool shims | Copilot, Gemini, Windsurf, Aider |
-| `.mcp.json` | MCP stub: filesystem, memory, fetch |
-| `.claude/settings.json` | Hardened permissions: deny list for secrets and destructive commands |
-
-### Standard scope adds
+## The two headline skills (v0.11)
 
-- **18 process skills** in `.claude/skills/` — TDD, brainstorming, debugging, git workflows, and more. Bodies load on demand, ~100 tokens at rest.
-- **14 agents** in `.claude/agents/` — planner, reviewer, debugger, pr-describer, and more.
-- **Safety hooks** — blocks force-push to main, secret commits, `rm -rf`, reads of `.env*` / `.ssh*` / `.aws*`. Fires before the tool call, doesn't rely on the model cooperating.
-- **Rule observability hooks** — logs which rules load and which get violated, feeds `aikit doctor --rules`.
-- **HTML design system** — `docs/aikit-html-design-system.html` ships with every standard install; use `/html` to generate rich browser-viewable artifacts instead of long markdown.
-- CI workflows: gitleaks, standard CI, optional `@claude` PR responder.
+- **`/docs`** — keeps a living HTML documentation tree at `docs/` current. The agent reads only the section it needs (via marker-bounded blocks), proposes the edit in chat, writes after you confirm. Your README stops going stale.
+- **`/decide`** — generates one rich HTML tradeoff page per architectural choice, saved to `docs/decisions/YYYY-MM-DD-<slug>.html`. Options as cards, pros/cons as colored dots, technical bit explained in plain language. A permanent decision log accumulates.
 
-### Everything scope adds
+Built on Thariq Shihipar's [Unreasonable Effectiveness of HTML for Claude Code](https://thariqs.github.io/html-effectiveness/) — generating HTML instead of markdown gives you scannable, interactive output. We took the insight and built the workflows that compound the longest.
 
-Dev container, OTel exporter, plugin wrapper, auto-sync CI, shape-specific agents (frontend / backend / mobile).
+## What else you get
 
-## What makes it different
+Beyond `/docs` and `/decide`, a `standard` install drops in:
 
-**Rule observability.** Telemetry hooks tell you which rules fire, which get violated, and which are dead weight. `aikit doctor --rules` shows the buckets; `aikit report` formats them for a PR comment. → [docs/observability.md](docs/observability.md)
+- **Cross-tool rules** — one canonical `AGENTS.md`, dialect-translated per tool (proper MDC for Cursor, emphasis tokens for Claude, imperative phrasing for Aider). Stop maintaining four copies.
+- **Safety hooks** — block force-push to main, secret commits, `rm -rf`, reads of `.env*` / `.ssh*` / `.aws*`. Fires before the tool call.
+- **Rule observability** — telemetry tells you which rules fire, get violated, or are dead weight. `aikit doctor --rules` shows the buckets.
+- **Learn from PR history** — `aikit learn --limit=30` mines merged PR reviews for repeated corrections, proposes them as new rules.
+- **18 process skills + 14 agents** — TDD, brainstorming, debugging, planner, reviewer, debugger, pr-describer, more.
+- **CI templates** — gitleaks, standard CI, optional `@claude` PR responder.
 
-**Dialect translation.** One canonical `AGENTS.md`, reformatted per tool — proper MDC frontmatter for Cursor, emphasis tokens for Claude, imperative phrasing for Aider. You stop maintaining four copies of the same rules. → [docs/dialects.md](docs/dialects.md)
-
-**Learn from your PR history.** `aikit learn --limit=30` mines merged PR review comments for repeated corrections and proposes them as new rules. No ML — just regex, a stopword list, and Jaccard similarity. → [docs/learn.md](docs/learn.md)
-
-## Commands
-
-```
-aikit                         interactive wizard
-aikit sync                    regenerate from .aikitrc.json (idempotent)
-aikit update                  pull latest templates, show diff, prompt
-aikit diff                    show drift between current state and a fresh sync
-aikit add <item>              add a single skill, command, agent, or hook
-aikit list                    show installed items + catalog availability
-aikit doctor                  schema, triggers, broken-link checks
-aikit doctor --rules          rule observability buckets
-aikit report                  Markdown adherence summary
-aikit report --format=json    same data, structured for CI
-aikit learn --limit=30        propose rules from your PR review history
-```
+Run `npx haac-aikit` for the wizard, or `npx haac-aikit --yes --tools=claude --preset=standard` for headless / CI.
 
 ## How it compares
 
@@ -86,18 +39,28 @@ aikit learn --limit=30        propose rules from your PR review history
 | Rule observability | yes | no | no | no |
 | Dialect translation | yes | no | no | no |
 | Learn from PR history | yes | no | no | no |
+| Living HTML docs (`/docs`) + decision log (`/decide`) | yes | no | no | no |
 | Idempotent BEGIN/END markers | yes | no | `.bak` backups | no |
 
-## Status
-
-0.8.0. Holding 1.0 until at least three external teams have used the observability loop on real PRs. Until then, expect breaking changes between minor versions.
+## Commands
 
-Looking for teams to try it — feedback shapes 1.0. Comment on [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1).
+```
+aikit                       interactive wizard
+aikit sync                  regenerate from .aikitrc.json
+aikit update                pull latest templates, show diff
+aikit add <item>            add a single skill / command / agent / hook
+aikit list                  show installed items + catalog
+aikit doctor [--rules]      sanity / observability check
+aikit report [--format=...] adherence summary (markdown or json)
+aikit learn --limit=30      propose rules from your PR review history
+```
 
-## Contributing
+## Status & links
 
-Issues and PRs welcome at [github.com/Hamad-Center/haac-aikit](https://github.com/Hamad-Center/haac-aikit).
+**0.11.0** — holding 1.0 until at least three external teams have used the observability loop on real PRs. Expect breaking changes between minor versions until then.
 
-## License
+- Site: <https://hamad-center.github.io/haac-aikit/>
+- Discussion / try-it sign-up: [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1)
+- Why we cut the old 20-template HTML skill: [the landing page](https://hamad-center.github.io/haac-aikit/) explains it — short version: developers don't browse a 20-template menu, two real workflows do 100% of the job. Recover the deleted templates with `git checkout v0.10.0 -- catalog/templates/html-artifacts/` if you want them.
 
 MIT. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md).

package/catalog/commands/decide.md

@@ -0,0 +1,24 @@
+Generate a single rich HTML decision page using the `decide` skill.
+
+## Usage
+`/decide <topic>`
+
+Example: `/decide auth strategy: session cookies vs JWT vs Clerk`.
+
+## Steps
+
+1. **Confirm the options** with the user before writing. Say back: *"Decision page on `<topic>` with options `A`, `B`, `C` — okay? My pick will be `<X>` because `<one-sentence reason>`."* Wait for yes.
+
+2. **Read the template** at `.aikit/templates/decide/template.html`. Copy its structure verbatim — design tokens, layout grid, callout patterns, voice + a11y conventions.
+
+3. **Gather concrete inputs** for each option: real cost numbers, real performance figures, real code snippets if relevant. Don't fill cards with hand-waved pros/cons — use facts.
+
+4. **Apply the voice rule** when writing prose: plain-language verb + concrete object, jargon in `<code>` chips not the reading path. Explain the technical bit like the reader is 15.
+
+5. **Write the file** to `docs/decisions/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug).
+
+6. **Report.** Print the file path and suggest `open docs/decisions/YYYY-MM-DD-<slug>.html` (macOS) / `xdg-open` (Linux).
+
+## Fallback
+
+If `.aikit/templates/decide/template.html` is missing, run `aikit sync` first.

package/catalog/commands/docs.md

@@ -0,0 +1,27 @@
+Update the project's HTML documentation in `docs/` using the `docs` skill.
+
+## Usage
+`/docs [optional intent]`
+
+With args: use them as the change to document (e.g. `/docs the new auth refresh flow`).
+Without args: infer from the last 5-10 turns of conversation what's worth documenting.
+
+## Steps
+
+1. **Decide what changed.** Identify (a) the doc file (`docs/<slug>.html`) and (b) the section id inside it (`overview`, `flow`, `gotchas`, etc). If no doc fits, propose creating one.
+
+2. **Read only the affected section.** Use `readSection(content, id, filePath)` from `src/render/markers` — never load the whole file.
+
+3. **Propose before writing.** One sentence in chat:
+   > *"I'll update `<section>` in `docs/<file>.html` to reflect <change>. Okay?"*
+   Wait for explicit yes. No silent edits.
+
+4. **Write through the marker engine.** `writeSection` to replace, `appendSection` for new sections. Anything outside markers is preserved verbatim.
+
+5. **Update `docs/index.html`** if you created a new doc or materially changed an existing one — refresh the matching `summary-<slug>` section.
+
+6. **Report.** Print the modified file paths and one-line summary of what changed.
+
+## Fallback
+
+If `.aikit/templates/docs/starter.html` is missing (project synced before this kit version), run `aikit sync` first.

package/catalog/release-notes.json

@@ -1,6 +1,44 @@
 {
   "version": 1,
   "releases": [
+    {
+      "version": "0.11.1",
+      "date": "2026-05-13",
+      "headline": "Docs-only patch: punchier landing + trimmed README",
+      "highlights": [
+        "Landing: new hero \"Docs that update themselves\" + without/with comparison block",
+        "Landing: Thariq Shihipar's HTML article elevated to a pull-quote attribution",
+        "README: 114 → 66 lines, /docs + /decide pulled to top as headline feature",
+        "No code changes — same surface as 0.11.0"
+      ],
+      "links": {
+        "changelog": "https://github.com/Hamad-Center/haac-aikit/blob/main/CHANGELOG.md#0111---2026-05-13"
+      }
+    },
+    {
+      "version": "0.11.0",
+      "date": "2026-05-13",
+      "headline": "/html replaced by /docs + /decide — fewer templates, sharper jobs",
+      "highlights": [
+        "NEW `/docs` skill (tier1, ~80 lines) — maintains an HTML documentation tree at `docs/` with section-bounded surgical updates",
+        "NEW `/decide` skill (tier2, ~50 lines) — single rich tradeoff page per decision, written to `docs/decisions/YYYY-MM-DD-<slug>.html`",
+        "NEW marker engine helpers `readSection`, `writeSection`, `appendSection` for `<!-- BEGIN:haac-aikit:section:<id> -->` blocks (round-trip tested)",
+        "REMOVED `/html` skill (was 205 lines, 9 patterns, 20 templates) and `aikit scaffold html` CLI",
+        "REMOVED `aikit init html` scope and `docs/aikit-html-design-system.html` shipped doc"
+      ],
+      "breaking": [
+        "`/html` slash command is gone — use `/docs` for living docs and `/decide` for tradeoff pages",
+        "`aikit init html` scope removed — use `aikit init --scope minimal` (or standard) instead",
+        "`aikit scaffold html` removed — agents read templates directly from `.aikit/templates/`"
+      ],
+      "migration": [
+        "Run `aikit sync` to pull new `/docs` and `/decide` templates into `.aikit/templates/`",
+        "Delete the orphaned `.aikit/templates/html-artifacts/` and `docs/aikit-html-design-system.html` if you have no local edits worth keeping"
+      ],
+      "links": {
+        "changelog": "https://github.com/Hamad-Center/haac-aikit/blob/main/CHANGELOG.md#0110---2026-05-13"
+      }
+    },
     {
       "version": "0.9.0",
       "date": "2026-05-12",

package/catalog/skills/tier1/docs.md

@@ -0,0 +1,81 @@
+---
+name: docs
+description: Use when the project's documentation is out of sync with the code or conversation just established a new architectural fact, feature, or gotcha worth recording. Maintains an HTML documentation tree at `docs/` — many small per-area files plus a rolled-up `docs/index.html`. Reads and writes single sections through marker-bounded `<!-- BEGIN:haac-aikit:section:<id> -->` blocks so updates are surgical and cheap.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+
+- User runs `/docs` explicitly.
+- Conversation just produced a documentable fact: a new feature was built, a module was refactored, a gotcha surfaced, an architectural decision was made and you've already used `/decide` to capture the choice itself.
+- A doc is visibly stale (filename or section name appeared in conversation but the file's content contradicts what was just discussed).
+
+Do **not** use for one-off explanations — those belong in chat, not docs.
+
+## File layout
+
+```
+docs/
+  index.html            ← rolled-up overview: short summary per linked doc + link
+  architecture.html     ← one HTML file per area or feature
+  auth.html
+  db.html
+  features/<slug>.html  ← per-feature deep dives (optional sub-folder)
+```
+
+Every HTML file uses the marker engine for sectioning:
+
+```html
+<!-- BEGIN:haac-aikit:section:overview -->
+<section id="overview"><h2>Overview</h2>... </section>
+<!-- END:haac-aikit:section:overview -->
+```
+
+Section IDs are kebab-case alphanumeric (`overview`, `data-flow`, `gotchas`, `adr-001`). They're stable across updates so the agent can find them.
+
+## Update protocol — follow exactly
+
+1. **Identify what changed.** From the recent conversation, name (a) the doc that's affected (`auth.html`, etc.) and (b) the section ID inside it (`overview`, `flow`, etc.). If the doc doesn't exist yet, plan to create it.
+2. **Read only the section you'll edit.** Use the marker engine's `readSection(content, id, filePath)` — never load the whole file.
+3. **Propose the change to the user in chat before writing.** One sentence: *"I'll update `<section>` in `docs/<file>.html` to reflect <change>. Okay?"* Wait for explicit confirmation. No silent writes.
+4. **Write through the marker engine.** Use `writeSection` for replacing an existing section. Use `appendSection` to add a new one. Anything outside markers (user-authored prose, hand-edited content) is preserved automatically.
+5. **Update `docs/index.html`** if you created a new file or materially changed an existing doc's purpose. Replace the matching summary inside its `<!-- BEGIN:haac-aikit:section:summary-<slug> -->` block.
+
+## Starter template
+
+When a doc doesn't exist yet, scaffold from `.aikit/templates/docs/starter.html` (synced from the catalog). The starter has:
+
+- Design tokens in `:root` (`--clay`, `--slate`, `--ivory`, `--oat`, `--olive`, `--gray-*`)
+- Landmark roles (`<main>`, `<nav>`, `<aside>`)
+- One example sectioned block to copy
+- A11y baseline: `<title>`, heading hierarchy, native form controls only
+
+Don't invent HTML structure from scratch — read the starter first.
+
+## index.html maintenance
+
+`docs/index.html` is the navigation hub. Each linked doc gets one summary card inside its own section:
+
+```html
+<!-- BEGIN:haac-aikit:section:summary-auth -->
+<a href="auth.html"><h3>Authentication</h3>
+<p>How sign-in, session, and token refresh work. 1-paragraph summary kept in sync with auth.html.</p></a>
+<!-- END:haac-aikit:section:summary-auth -->
+```
+
+When you update `auth.html`'s overview, also update the matching `summary-auth` section in `index.html` so the rollup stays accurate.
+
+## Visual content
+
+HTML allows inline SVG diagrams, code samples, and graphs when they earn their weight. Default to prose; add a diagram only when it explains something prose can't (a flow, a topology, a sequence).
+
+## Anti-patterns to avoid
+
+- **Loading the whole file to edit one section.** Defeats the token-cost mitigation; always use `readSection` / `writeSection`.
+- **Silent writes.** Every update gets one-sentence confirmation in chat first. Docs are project-facing; surprise edits erode trust.
+- **Editing content outside the markers.** That's user-authored prose; preserve it verbatim.
+- **Inventing HTML from scratch.** Read the starter template first.
+- **Drifting `index.html`.** When a doc's purpose changes, its summary in `index.html` MUST change too — same commit.
+- **One giant doc.** Split per area; the rollup gives the single-page view if the user wants it.

package/catalog/skills/tier2/decide.md

@@ -0,0 +1,52 @@
+---
+name: decide
+description: Use when the user is about to make a non-trivial choice with 2-4 viable options and wants the tradeoffs visualized as a single rich HTML page they can scan, share, and commit to the project's decision log. Generates one self-contained HTML file per decision under `docs/decisions/YYYY-MM-DD-<slug>.html`. Opt-in only — do not invoke without user request.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+
+Explicit invocation only: `/decide <topic>`, "use the decide skill", "make me a decision page on X".
+
+Do not invoke proactively. The user picks the moment they need a tradeoff laid out — silent generation creates noise.
+
+## Structure of a decision page
+
+Every page has the same five blocks. Order matters: decision-makers should never have to scroll to find what they're approving.
+
+1. **Decision needed callout** — the question in one sentence at the top. Recommended option marked with `★`.
+2. **Option cards (2-4)** — each card has: title, one-line summary, pros (olive dots), cons (clay dots), how-it-works in 2-3 plain-language sentences.
+3. **Comparison row** — a small table or chip grid putting the options side by side on the dimensions that matter (cost, complexity, reversibility, performance — pick what's relevant).
+4. **Technical bit, explained 15-year-old simple** — one paragraph per option. Plain verbs + concrete objects. Jargon goes in `<code>` chips, not the reading path.
+5. **Recommendation + reasoning** — clay-bordered callout. State the pick, the one-sentence reason, the conditions under which the recommendation flips.
+
+## Output
+
+- Path: `docs/decisions/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the topic)
+- Template: `.aikit/templates/decide/template.html` — read first, copy structure verbatim, fill placeholders
+- Self-contained: pure HTML/CSS, no CDNs, no build step
+- Committed to git (permanent decision log)
+
+## Voice rule (non-negotiable)
+
+- One concept per sentence.
+- Plain-language verb + concrete object: *"Load images only when the reader scrolls to them"* beats *"Implement lazy-loading via IntersectionObserver."*
+- Jargon lives in `<code>` chips or collapsed `<details>`, never in main prose.
+- Concrete first, abstract term in parens: *"Make sure failed requests retry safely (idempotent)"*.
+
+## A11y baseline (every decision page)
+
+- `<title>`, exactly one `<h1>`, heading hierarchy never skips levels.
+- Landmarks: `<main>`, `<nav>` if linking to other decisions, `<aside>` for the recommendation callout.
+- Color contrast ≥ 4.5:1 for body text — design tokens already meet this; don't override.
+- Inline SVG diagrams get `<title>` + `aria-labelledby`. Decorative icons get `aria-hidden="true"`.
+
+## Anti-patterns
+
+- **More than 4 options.** Decision pages with 5+ options become catalogs; pre-narrow the field.
+- **Recommendation buried below the fold.** First paint must show the recommendation.
+- **Jargon-heavy prose.** If a non-technical stakeholder can't read it, rewrite it.
+- **Silent generation.** This skill is opt-in. Wait for explicit `/decide`.
+- **Skipping the date in the filename.** The decision log sorts chronologically; dates are required.

package/catalog/templates/decide/template.html

@@ -0,0 +1,244 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{TITLE}}</title>
+<meta name="description" content="{{ONE_LINE_DECISION}}">
+<meta name="aikit-doc-type" content="decision">
+<style>
+:root {
+  --clay: #D97757;
+  --slate: #141413;
+  --ivory: #FAF9F5;
+  --oat: #E3DACC;
+  --olive: #788C5D;
+  --gray-150: #F0EEE6;
+  --gray-300: #D1CFC5;
+  --gray-500: #87867F;
+  --gray-700: #3D3D3A;
+  --white: #FFFFFF;
+  --serif: ui-serif, Georgia, "Times New Roman", serif;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  --sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--ivory);
+  color: var(--slate);
+  font-family: var(--sans);
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+}
+main { max-width: 1080px; margin: 0 auto; padding: 48px 24px 96px; }
+
+h1, h2, h3 { font-family: var(--serif); margin: 0 0 8px; }
+h1 { font-size: clamp(28px, 4vw, 38px); }
+h2 { font-size: clamp(20px, 2.4vw, 26px); margin-top: 48px; }
+h3 { font-size: 17px; margin: 0 0 6px; }
+
+.eyebrow {
+  font-family: var(--mono);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--gray-500);
+}
+
+.decision-needed {
+  background: var(--white);
+  border: 1px solid var(--gray-300);
+  border-left: 4px solid var(--clay);
+  border-radius: 6px;
+  padding: 20px 24px;
+  margin: 24px 0 36px;
+  box-shadow: 0 1px 3px rgba(20, 20, 19, 0.06);
+}
+.decision-needed .question {
+  font-family: var(--serif);
+  font-size: 22px;
+  margin: 6px 0 12px;
+}
+.option-chips { display: flex; flex-wrap: wrap; gap: 8px; }
+.option-chips .chip {
+  font-family: var(--mono);
+  font-size: 12px;
+  background: var(--oat);
+  color: var(--slate);
+  padding: 4px 10px;
+  border-radius: 999px;
+}
+.option-chips .chip.recommended { background: var(--olive); color: var(--white); }
+
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 16px; margin-top: 16px; }
+.card {
+  background: var(--white);
+  border: 1px solid var(--gray-300);
+  border-radius: 6px;
+  padding: 18px;
+}
+.card.recommended { border-color: var(--olive); border-width: 2px; }
+.card .summary { color: var(--gray-700); margin: 4px 0 14px; }
+.card ul { list-style: none; padding: 0; margin: 8px 0; font-size: 14px; }
+.card li { padding-left: 18px; position: relative; margin: 4px 0; }
+.card li.pro::before {
+  content: ""; width: 8px; height: 8px; border-radius: 50%; background: var(--olive);
+  position: absolute; left: 2px; top: 8px;
+}
+.card li.con::before {
+  content: ""; width: 8px; height: 8px; border-radius: 50%; background: var(--clay);
+  position: absolute; left: 2px; top: 8px;
+}
+.card .how {
+  background: var(--gray-150); padding: 10px 12px; border-radius: 4px;
+  font-size: 13px; margin-top: 12px;
+}
+
+table { width: 100%; border-collapse: collapse; margin-top: 12px; font-size: 14px; }
+th, td { text-align: left; padding: 10px 12px; border-bottom: 1px solid var(--gray-300); }
+th { background: var(--gray-150); font-weight: 600; font-family: var(--mono); font-size: 12px; text-transform: uppercase; }
+
+.tech-block { background: var(--white); border: 1px solid var(--gray-300); border-radius: 6px; padding: 18px; margin-top: 12px; }
+.tech-block h3 { color: var(--gray-700); }
+
+.recommendation {
+  background: var(--white);
+  border: 1px solid var(--olive);
+  border-left: 4px solid var(--olive);
+  border-radius: 6px;
+  padding: 20px 24px;
+  margin-top: 32px;
+}
+.recommendation .pick {
+  font-family: var(--serif); font-size: 22px; margin: 0 0 8px;
+}
+.recommendation .reason { color: var(--gray-700); }
+.recommendation .flip {
+  margin-top: 12px; font-size: 13px; color: var(--gray-500); font-style: italic;
+}
+
+code { font-family: var(--mono); font-size: 0.9em; background: var(--gray-150); padding: 1px 5px; border-radius: 3px; }
+a { color: var(--clay); text-underline-offset: 2px; }
+a:focus-visible { outline: 2px solid var(--clay); outline-offset: 2px; border-radius: 2px; }
+
+footer.provenance {
+  margin-top: 48px; padding-top: 16px; border-top: 1px solid var(--gray-300);
+  font-family: var(--mono); font-size: 11px; color: var(--gray-500);
+}
+
+@media (max-width: 720px) {
+  main { padding: 24px 16px 64px; }
+  .cards { grid-template-columns: 1fr; }
+}
+</style>
+</head>
+<body>
+
+<main>
+
+<header>
+  <p class="eyebrow">Decision · {{DATE}}</p>
+  <h1>{{TITLE}}</h1>
+</header>
+
+<aside class="decision-needed" aria-labelledby="decision-question">
+  <p class="eyebrow">Decision needed</p>
+  <p id="decision-question" class="question">{{ONE_LINE_DECISION_QUESTION}}</p>
+  <div class="option-chips" role="list">
+    <span class="chip" role="listitem">A — {{OPTION_A_NAME}}</span>
+    <span class="chip recommended" role="listitem">B — {{OPTION_B_NAME}} ★</span>
+    <span class="chip" role="listitem">C — {{OPTION_C_NAME}}</span>
+  </div>
+</aside>
+
+<section id="options" aria-labelledby="options-heading">
+  <h2 id="options-heading">Options</h2>
+  <div class="cards">
+
+    <article class="card">
+      <h3>A — {{OPTION_A_NAME}}</h3>
+      <p class="summary">{{OPTION_A_SUMMARY}}</p>
+      <ul aria-label="Pros and cons of option A">
+        <li class="pro">{{OPTION_A_PRO_1}}</li>
+        <li class="pro">{{OPTION_A_PRO_2}}</li>
+        <li class="con">{{OPTION_A_CON_1}}</li>
+      </ul>
+      <div class="how"><strong>How it works:</strong> {{OPTION_A_HOW}}</div>
+    </article>
+
+    <article class="card recommended" aria-label="Recommended option">
+      <h3>B — {{OPTION_B_NAME}} <span aria-hidden="true">★</span></h3>
+      <p class="summary">{{OPTION_B_SUMMARY}}</p>
+      <ul aria-label="Pros and cons of option B">
+        <li class="pro">{{OPTION_B_PRO_1}}</li>
+        <li class="pro">{{OPTION_B_PRO_2}}</li>
+        <li class="con">{{OPTION_B_CON_1}}</li>
+      </ul>
+      <div class="how"><strong>How it works:</strong> {{OPTION_B_HOW}}</div>
+    </article>
+
+    <article class="card">
+      <h3>C — {{OPTION_C_NAME}}</h3>
+      <p class="summary">{{OPTION_C_SUMMARY}}</p>
+      <ul aria-label="Pros and cons of option C">
+        <li class="pro">{{OPTION_C_PRO_1}}</li>
+        <li class="con">{{OPTION_C_CON_1}}</li>
+        <li class="con">{{OPTION_C_CON_2}}</li>
+      </ul>
+      <div class="how"><strong>How it works:</strong> {{OPTION_C_HOW}}</div>
+    </article>
+
+  </div>
+</section>
+
+<section id="comparison" aria-labelledby="comparison-heading">
+  <h2 id="comparison-heading">Side by side</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Dimension</th>
+        <th>A — {{OPTION_A_NAME}}</th>
+        <th>B — {{OPTION_B_NAME}}</th>
+        <th>C — {{OPTION_C_NAME}}</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td>Cost</td><td>{{A_COST}}</td><td>{{B_COST}}</td><td>{{C_COST}}</td></tr>
+      <tr><td>Complexity</td><td>{{A_COMPLEXITY}}</td><td>{{B_COMPLEXITY}}</td><td>{{C_COMPLEXITY}}</td></tr>
+      <tr><td>Reversibility</td><td>{{A_REVERSIBILITY}}</td><td>{{B_REVERSIBILITY}}</td><td>{{C_REVERSIBILITY}}</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section id="technical" aria-labelledby="technical-heading">
+  <h2 id="technical-heading">The technical bit (in plain language)</h2>
+  <div class="tech-block">
+    <h3>A — {{OPTION_A_NAME}}</h3>
+    <p>{{OPTION_A_TECH_PLAIN}}</p>
+  </div>
+  <div class="tech-block">
+    <h3>B — {{OPTION_B_NAME}}</h3>
+    <p>{{OPTION_B_TECH_PLAIN}}</p>
+  </div>
+  <div class="tech-block">
+    <h3>C — {{OPTION_C_NAME}}</h3>
+    <p>{{OPTION_C_TECH_PLAIN}}</p>
+  </div>
+</section>
+
+<aside class="recommendation" aria-labelledby="recommendation-heading">
+  <p class="eyebrow" id="recommendation-heading">Recommendation</p>
+  <p class="pick">★ Pick {{RECOMMENDED_LETTER}} — {{RECOMMENDED_NAME}}</p>
+  <p class="reason">{{RECOMMENDATION_REASON}}</p>
+  <p class="flip"><strong>Flip to a different option if:</strong> {{FLIP_CONDITION}}</p>
+</aside>
+
+<footer class="provenance">
+  Sources: {{SOURCES}} — generated {{ISO_TIMESTAMP}}
+</footer>
+
+</main>
+
+</body>
+</html>