haac-aikit 0.10.0 → 0.11.0

package/README.md

@@ -6,13 +6,6 @@
 
 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
 
 ```bash
@@ -46,7 +39,8 @@ npx haac-aikit --yes --tools=claude,cursor,copilot --preset=standard
 - **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.
+- **`/docs` skill** — keeps a small HTML documentation tree at `docs/` current. Section-bounded updates so the agent reads/edits one block, not the whole file.
+- **`/decide` skill (opt-in)** — generates one rich HTML tradeoff page per decision under `docs/decisions/`. Plain-language pros/cons, recommended option marked, written so a non-engineer stakeholder can scan it.
 - CI workflows: gitleaks, standard CI, optional `@claude` PR responder.
 
 ### Everything scope adds
@@ -61,6 +55,23 @@ Dev container, OTel exporter, plugin wrapper, auto-sync CI, shape-specific agent
 
 **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)
 
+## Why the HTML side stays small (one starter, not 20 templates)
+
+An earlier version of this kit shipped 20 HTML templates — PR reviews, slide decks, design systems, prototype animations, feature-flag editors, prompt tuners. Beautiful catalog. **We deleted it.** Here's the honest reason:
+
+- **Developers don't browse a 20-template catalog.** They open the skill, see the wall of patterns, scroll past it, and write whatever HTML they were going to write anyway. Most of those templates were never reached for in practice. A library nobody borrows from is just shelves.
+- **A 205-line always-on skill is expensive to keep around.** Every agent invocation paid for that context, even when the user wasn't generating HTML at all. We were taxing every conversation to support a rare action.
+- **Two real jobs, not twenty edge cases.** When we asked what people actually needed HTML for, two patterns kept surfacing: (1) **living project docs** they could share for handover, and (2) **tradeoff pages** when there's a decision to make. Everything else was a curated showcase, not a tool.
+
+So `/html` got split into two focused skills:
+
+- **`/docs`** — always-on, ~80-line skill, one starter HTML template. Maintains an HTML doc tree at `docs/` with section-bounded surgical updates.
+- **`/decide`** — opt-in tier2, ~50-line skill, one rich tradeoff template. Each call writes a new dated file under `docs/decisions/`.
+
+Both lean on the marker engine for section-level reads/writes (HTML stays cheap because the agent never reloads the whole file). The skill files together are smaller than the old single skill alone. **Less to read, less to maintain, more actual usage.**
+
+If you want the deleted templates back, fork the previous release (`git checkout v0.10.0 -- catalog/templates/html-artifacts/`) — they're forks of [github.com/ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness) and still useful as reference material.
+
 ## Commands
 
 ```
@@ -90,7 +101,7 @@ aikit learn --limit=30        propose rules from your PR review history
 
 ## 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.
+0.11.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.
 
 Looking for teams to try it — feedback shapes 1.0. Comment on [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1).
 

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,30 @@
 {
   "version": 1,
   "releases": [
+    {
+      "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>

package/catalog/templates/docs/starter.html

@@ -0,0 +1,99 @@
+<!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="{{DESCRIPTION}}">
+<meta name="aikit-doc-type" content="reference">
+<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; }
+html { scroll-behavior: smooth; }
+body {
+  margin: 0;
+  background: var(--ivory);
+  color: var(--slate);
+  font-family: var(--sans);
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+}
+
+main {
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 48px 24px 96px;
+}
+
+h1, h2, h3 { font-family: var(--serif); margin: 0 0 12px; }
+h1 { font-size: clamp(28px, 4vw, 40px); }
+h2 { font-size: clamp(22px, 3vw, 28px); margin-top: 40px; }
+h3 { font-size: 18px; margin-top: 24px; }
+
+section { scroll-margin-top: 28px; }
+section + section { margin-top: 32px; }
+
+a { color: var(--clay); text-decoration: underline; text-underline-offset: 2px; }
+a:hover { text-decoration-thickness: 2px; }
+a:focus-visible { outline: 2px solid var(--clay); outline-offset: 2px; border-radius: 2px; }
+
+code { font-family: var(--mono); font-size: 0.92em; background: var(--gray-150); padding: 1px 5px; border-radius: 3px; }
+pre { background: var(--gray-150); padding: 16px; border-radius: 6px; overflow-x: auto; }
+
+.eyebrow {
+  font-family: var(--mono);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--gray-500);
+  margin-bottom: 8px;
+}
+
+@media (max-width: 720px) {
+  main { padding: 24px 16px 64px; }
+}
+</style>
+</head>
+<body>
+
+<main>
+
+<header>
+  <p class="eyebrow">{{DOC_TYPE}}</p>
+  <h1>{{TITLE}}</h1>
+  <p>{{ONE_LINE_DESCRIPTION}}</p>
+</header>
+
+<!--
+  EXAMPLE SECTIONED BLOCK — copy this pattern for each section.
+  The agent reads/writes by section id; the marker pair is load-bearing.
+-->
+
+<!-- BEGIN:haac-aikit:section:overview -->
+<section id="overview" aria-labelledby="overview-heading">
+  <h2 id="overview-heading">Overview</h2>
+  <p>One paragraph: what this doc covers, who it's for, when to read it.</p>
+</section>
+<!-- END:haac-aikit:section:overview -->
+
+<!-- Add more sections below by duplicating the pattern with a new id. -->
+
+</main>
+
+</body>
+</html>