haac-aikit 0.7.3 → 0.8.1

package/README.md

@@ -4,9 +4,7 @@
 [![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)
 
-A CLI that drops a working AI-coding setup into any repo — rules, skills, safety hooks, subagents, MCP stub, CI templates — and then helps you figure out which of those rules are actually doing anything.
-
-Works with Claude Code, Cursor, GitHub Copilot, Windsurf, Aider, Gemini CLI, and OpenAI Codex CLI.
+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.
 
 ## Quickstart
 
@@ -14,7 +12,7 @@ Works with Claude Code, Cursor, GitHub Copilot, Windsurf, Aider, Gemini CLI, and
 npx haac-aikit
 ```
 
-The wizard takes about 30 seconds and writes a `.aikitrc.json` you can commit. Re-run later with `aikit sync`.
+30-second wizard, writes a `.aikitrc.json` you can commit. Re-run anytime with `aikit sync`.
 
 For CI or scripts:
 
@@ -22,158 +20,39 @@ For CI or scripts:
 npx haac-aikit --yes --tools=claude,cursor,copilot --preset=standard
 ```
 
-## Why this exists
-
-Every AI tool now wants its own rules file: CLAUDE.md, `.cursor/rules/`, `copilot-instructions.md`, AGENTS.md. They all do roughly the same thing — tell the model how your team writes code — but you end up maintaining four copies, none of which you can tell are working.
-
-You write 30 rules and pray. The kit you cloned last quarter ships a CLAUDE.md with rules about Python even though you write Go. You never delete the dead ones because you can't tell they're dead.
-
-haac-aikit gives you the curated baseline like other kits do (skills, hooks, agents, etc.), and on top of that it adds three things no other kit ships:
-
-1. **Observability** — telemetry hooks log which rules are loaded and violated, so `aikit doctor --rules` can tell you which to keep, strengthen, or delete.
-2. **Dialect translation** — Cursor's MDC, Claude's emphasis tokens, Aider's imperative phrasing all want different things. Same canonical AGENTS.md, reformatted per tool.
-3. **`aikit learn`** — mines your team's PR review comments for repeated corrections and proposes them as new rules.
-
-## What changes after you install it
-
-**Right after `aikit init`:**
-
-- One `AGENTS.md` becomes the source of truth for every AI tool you use. You stop maintaining four copies of the same rules.
-- Force-pushing to `main`, committing secrets, reading `.env*` / `.ssh/` / `.aws/` files, `rm -rf` outside the project, and about a dozen other footguns are blocked at the hook level. They don't depend on the AI cooperating — the hook fires before the tool call.
-- 18 process skills (TDD, brainstorming, debugging, etc.) sit in `.claude/skills/` and load on demand. Always-on cost is roughly 100 tokens per skill, so your context window stays clean.
-- Per-PR safety: a `gitleaks` workflow ships in `.github/workflows/` so secrets caught at commit time don't slip through code review either.
-
-**After a week or two of use:**
-
-- `aikit doctor --rules` shows you which rules fire often, which fire and get violated, and which never come up. You delete the dead ones, strengthen the disputed ones, and stop guessing.
-- The `.aikit/events.jsonl` log accumulates a real record of every rule load and pattern violation — local, gitignored, never uploaded. If you opt into the LLM judge it also includes per-turn cited / violated verdicts.
-
-**After a month:**
-
-- `aikit learn --limit=30` mines your merged PRs for repeated review comments and proposes new rules. Patterns like "we always validate at the boundary" or "use named exports here" that used to live only in code review get codified without anyone hand-typing them.
-- The optional GitHub Actions workflow posts a sticky PR comment with a rule-adherence score, so regressions across releases are visible at PR-review time.
-
-**What you don't get locked into:**
-
-- AGENTS.md is portable — Cursor, Copilot, Codex, Aider, and Gemini all read it. Switching tools doesn't mean rewriting your rules.
-- The catalog (skills, hooks, agents) is just markdown and shell scripts under `.claude/`. Take it and walk away whenever — haac-aikit never reaches back into your repo and there's no SaaS to cancel.
-- All telemetry is local. The opt-in LLM judge calls the Anthropic API only with your own key, only on `Stop` events, and you can pull the env var anytime.
-
 ## What you get
 
 ### Minimal scope
 
 | File | Purpose |
 |---|---|
-| `AGENTS.md` | The canonical project rules — your edits outside the BEGIN/END markers are never touched |
-| `CLAUDE.md` | Five-line shim that imports `@AGENTS.md` plus a Claude-only override block |
-| `.cursor/rules/000-base.mdc` | Cursor MDC, dialect-translated from AGENTS.md (not a generic shim) |
-| `.github/copilot-instructions.md`, `GEMINI.md`, `CONVENTIONS.md`, `.windsurf/rules/project.md` | Per-tool shims |
-| `.mcp.json` | MCP stub with filesystem, memory, fetch — three servers, ~1k tokens of tool defs |
+| `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 |
-| `.aikitrc.json` | Versioned config so re-runs are deterministic |
 
-### Standard scope (default) adds
+### Standard scope adds
 
-- 18 process skills, organised into Tier 1 (always-on) and Tier 2 (opt-in). Skill bodies only load when triggered, so the at-rest cost is roughly 100 tokens each.
-- **Agents** in `.claude/agents/`: 10 always-on (planner, reviewer, debugger, pr-describer, …) plus opt-in specialty agents (simplifier, prompt-engineer, evals-author, …) selected via the wizard.
-- **Conflict-aware sync**: if you've modified an installed template (e.g., `.claude/agents/reviewer.md`), `aikit sync` and `aikit update` now prompt before overwriting — instead of silently replacing it.
-- Safety hooks that block dangerous bash, force-push to main, secret commits, and reads of sensitive files.
-- Observability hooks (see below).
-- A starter `.claude/aikit-rules.json` with regex patterns for common things like no `console.log`, no default exports, no `any`.
-- `docs/claude-md-reference.md` — a 2026 reference doc on Anthropic's memory features for your team.
-- `.claude/rules/example.md` — a starter path-scoped rule that only loads when matching files are read.
-- CI workflows: gitleaks, standard CI, optional `@claude` PR responder, optional rule-adherence PR comment.
+- **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.
 
 ### Everything scope adds
 
-Dev container, OTel exporter, plugin wrapper, auto-sync CI, and shape-specific agents (frontend / backend / mobile, picked based on the project shape you select in the wizard).
+Dev container, OTel exporter, plugin wrapper, auto-sync CI, shape-specific agents (frontend / backend / mobile).
 
-## Rule observability
+## What makes it different
 
-After a few Claude Code sessions:
-
-```
-$ aikit doctor --rules
-
-Hot rules (working as intended)
-  commit.conventional-commits — 47 loads
-  security.no-sensitive-files — 12 loads
-
-Disputed rules (>30% violation rate)
-  code-style.no-console-log — 47 loads, 18 pattern violations
-    Frequently violated. Strengthen with IMPORTANT/YOU MUST or move to a hook.
-
-Dead rules (never observed)
-  legacy.bounded-contexts
-    Never loaded, cited, or violated. Consider removing or rephrasing.
-```
-
-This comes from three small hooks shipped at standard scope:
-
-- **`log-rule-event.sh`** runs on `InstructionsLoaded`. It scans loaded files for `<!-- id: code-style.no-any -->` markers and writes one event per rule per session.
-- **`check-pattern-violations.sh`** runs on `PostToolUse` for Edit/Write. It reads `.claude/aikit-rules.json` and flags any pattern matches in the file Claude just wrote.
-- **`judge-rule-compliance.sh`** runs on `Stop`. It's opt-in. If you set `AIKIT_JUDGE=1` and `ANTHROPIC_API_KEY`, it asks Claude Haiku to verdict whether each loaded rule was cited or violated this turn (~$0.001/turn). Without both env vars it returns immediately and does nothing.
-
-All three hooks append to `.aikit/events.jsonl`, which `sync` adds to `.gitignore`. Nothing leaves your machine unless you opt in to the judge.
-
-`aikit report` formats the same data as Markdown (PR-comment ready) or JSON (`--format=json`, for CI). Without judge data, the adherence score is `null` with `basis: "no-evidence"` rather than a fake number derived from load counts.
-
-### Adding observability to your own rules
-
-In any rule file, add a stable HTML-comment ID:
-
-```markdown
-- <!-- id: code-style.no-any emphasis=high paths=src/**/*.ts --> Use `unknown` and type guards, not `any`.
-```
+**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)
 
-The `id` is required for telemetry. `emphasis` and `paths` are optional metadata read by the dialect translators. HTML comments cost zero context tokens — Claude strips them before injection — so this is free observability.
+**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)
 
-## Dialect translation
-
-Other multi-tool kits copy the same content into every per-tool file. haac-aikit reformats per dialect.
-
-For Cursor that means: `.cursor/rules/000-base.mdc` gets proper MDC frontmatter, **bold** emphasis on rules tagged `emphasis=high`, and a paths hint surfaced inline. Rule IDs are preserved so the observability hooks see them load alongside AGENTS.md.
-
-Claude, Aider, Copilot, and Gemini translators are the next thing on the roadmap.
-
-## Learn from your PR history
-
-```
-$ aikit learn --limit=30
-```
-
-Pulls the last 30 merged PRs via `gh`, scans review and issue comments for correction phrases ("we always", "don't here", "actually let's", "nit:"), tokenises them, clusters by Jaccard similarity, and prints proposals in a paste-ready block:
-
-```
-<!-- BEGIN:learned -->
-## Learned conventions
-- <!-- id: learned.use-named-exports --> we always use named exports here, not default
-- <!-- id: learned.validate-input-boundary --> please validate inputs at the API boundary
-<!-- END:learned -->
-```
-
-Review the suggestions, paste the keepers into AGENTS.md. The similarity threshold is intentionally permissive — false positives are easy to reject, missed signal is harder to recover. There are no ML dependencies; it's regex, a stopword list, and a five-line stemmer.
-
-## Update safety
-
-haac-aikit owns content between BEGIN/END markers. Everything outside is yours.
-
-```markdown
-# My Project
-
-My own notes — never touched by aikit.
-
-<!-- BEGIN:haac-aikit -->
-managed content
-<!-- END:haac-aikit -->
-
-More of my notes — also never touched.
-```
-
-`aikit sync` is idempotent: running it twice produces the same files. `aikit diff` shows what would change. `aikit update` shows the diff and prompts before writing.
-
-The marker engine handles four dialects automatically (`.md` → `<!-- ... -->`, `.yml` → `# `, `.json` → `// `, shell → `# `). If a downstream user removes a marker by accident, the hook refuses to silently re-append — it errors out so you can investigate.
+**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
 
@@ -181,7 +60,7 @@ The marker engine handles four dialects automatically (`.md` → `<!-- ... -->`,
 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 generation
+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
@@ -191,39 +70,27 @@ aikit report --format=json    same data, structured for CI
 aikit learn --limit=30        propose rules from your PR review history
 ```
 
-Most prompts have a `--flag` equivalent for headless use.
-
-## Design choices, in case they help you decide
-
-- **Skills are ~100 tokens at rest.** Bodies load only when the skill is triggered. A kit with 30 always-on skill bodies eats your context window before you've started.
-- **AGENTS.md is canonical, CLAUDE.md is a 5-line shim that imports it.** One source of truth across all tools.
-- **Three MCP servers by default.** Five servers can be ~77K tokens of tool definitions. Most projects don't need a search engine *and* a database *and* a filesystem in every conversation.
-- **Marker-protected templates.** This was the first thing I broke in my own setup before adding the marker engine. Your edits outside the markers survive every `sync`.
-- **No LLM-generated content in the catalog.** Every shipped skill / hook / agent is human-curated. ETH Zurich's 2026 study on LLM-augmented context found dumps add cost without improving success rate.
-
-## How haac-aikit compares
+## How it compares
 
 | | haac-aikit | rulesync | ruler | claudekit |
 |---|---|---|---|---|
-| Includes content (skills, agents, hooks) | yes | no — config manager only | no — config manager only | Claude-only |
-| Cross-tool | 7 tools | yes | yes | no |
-| Open Skills standard (agentskills.io) | yes | no | no | no |
-| Config file backed | `.aikitrc.json` | no | no | no |
-| Idempotent BEGIN/END markers | yes | no | `.bak` backups | no |
+| Includes content (skills, agents, hooks) | yes | no | no | Claude-only |
+| Cross-tool (7 tools) | yes | yes | yes | no |
 | Rule observability | yes | no | no | no |
 | Dialect translation | yes | no | no | no |
 | Learn from PR history | yes | no | no | no |
+| Idempotent BEGIN/END markers | yes | no | `.bak` backups | no |
 
 ## Status
 
-This is 0.7.0. The strategy plan reserves 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.7.0 ships the tiered agent system, 8 new agents, interactive conflict resolution, and the Cursor dialect translator; Claude, Aider, Copilot, and Gemini translators are next.
+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.
+
+Looking for teams to try it — feedback shapes 1.0. Comment on [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1).
 
 ## Contributing
 
 Issues and PRs welcome at [github.com/Hamad-Center/haac-aikit](https://github.com/Hamad-Center/haac-aikit).
 
-I'm looking for **three teams** to try the observability loop on a real codebase. Your feedback shapes 1.0. Comment on [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1) if you're up for it.
-
 ## License
 
-MIT. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md) for the list of adapted sources.
+MIT. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md).

package/catalog/commands/html.md

@@ -0,0 +1,26 @@
+Generate an HTML artifact for the current context using the html-artifacts skill.
+
+## Usage
+`/html [optional intent]`
+
+## Steps
+
+1. **Determine intent**
+   - If called with args (e.g. `/html code review of today's PR`): use the args as the intent.
+   - If called with no args: infer intent from the current conversation — what task is in progress, what was just discussed, what files are open.
+
+2. **Pick the use-case pattern**
+   Using the `html-artifacts` skill, identify which of the five patterns fits:
+   Spec/Planning, Code Review, Report/Research, Prototype, or Custom Editor.
+
+3. **Generate the artifact**
+   - Apply the built-in design system CSS tokens
+   - If `docs/aikit-html-design-system.html` exists in the project, read it first and inherit its CSS variable values
+   - Follow the structure guidance for the chosen pattern
+   - Pure HTML/CSS/JS only — no external CDN dependencies
+
+4. **Save and report**
+   - Determine a short slug from the intent (e.g. `code-review-auth-pr`, `weekly-report`)
+   - Save to `.aikit/artifacts/<slug>-<timestamp>.html`
+   - Print the full path
+   - Suggest opening: `open <path>` (macOS) / `xdg-open <path>` (Linux)

package/catalog/docs/html-design-system.html

@@ -0,0 +1,178 @@
+<!-- Customize the CSS variables above. The model reads this file when generating HTML artifacts. -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>haac-aikit HTML Design System</title>
+<style>
+/* ─── Design tokens ────────────────────────────────────────────────────────
+   Edit these variables to retheme all HTML artifacts generated by the model.
+   ──────────────────────────────────────────────────────────────────────── */
+:root {
+  --color-bg:      #0f1117;
+  --color-surface: #1a1d27;
+  --color-border:  #2e3143;
+  --color-text:    #e2e8f0;
+  --color-muted:   #8892a4;
+  --color-accent:  #6366f1;
+  --color-ok:      #22c55e;
+  --color-warn:    #f59e0b;
+  --color-error:   #ef4444;
+  --radius:        6px;
+  --font-sans:     system-ui, -apple-system, sans-serif;
+  --font-mono:     "JetBrains Mono", "Fira Code", monospace;
+  --space:         4px;
+}
+
+/* ─── Reset & base ─────────────────────────────────────────────────────── */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-sans);
+  font-size: 14px;
+  line-height: 1.6;
+  padding: calc(var(--space) * 8);
+  max-width: 900px;
+  margin: 0 auto;
+}
+h1, h2, h3 { font-weight: 600; margin-bottom: calc(var(--space) * 3); }
+h1 { font-size: 1.5rem; margin-bottom: calc(var(--space) * 6); }
+h2 { font-size: 1.1rem; color: var(--color-muted); text-transform: uppercase; letter-spacing: 0.05em; margin-top: calc(var(--space) * 10); }
+p { color: var(--color-muted); margin-bottom: calc(var(--space) * 4); }
+section { margin-bottom: calc(var(--space) * 12); }
+
+/* ─── Card ──────────────────────────────────────────────────────────────── */
+.card {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: calc(var(--space) * 5);
+  margin-bottom: calc(var(--space) * 4);
+}
+
+/* ─── Badge ─────────────────────────────────────────────────────────────── */
+.badge {
+  display: inline-block;
+  font-size: 11px;
+  font-weight: 600;
+  padding: 2px 8px;
+  border-radius: 999px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.badge-ok    { background: color-mix(in srgb, var(--color-ok) 15%, transparent);    color: var(--color-ok); }
+.badge-warn  { background: color-mix(in srgb, var(--color-warn) 15%, transparent);  color: var(--color-warn); }
+.badge-error { background: color-mix(in srgb, var(--color-error) 15%, transparent); color: var(--color-error); }
+.badge-info  { background: color-mix(in srgb, var(--color-accent) 15%, transparent); color: var(--color-accent); }
+
+/* ─── Tabs ──────────────────────────────────────────────────────────────── */
+.tabs { border-bottom: 1px solid var(--color-border); display: flex; gap: calc(var(--space) * 1); margin-bottom: calc(var(--space) * 4); }
+.tab {
+  padding: calc(var(--space) * 2) calc(var(--space) * 4);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+  color: var(--color-muted);
+  font-size: 13px;
+  font-weight: 500;
+  background: none;
+  border-top: none;
+  border-left: none;
+  border-right: none;
+}
+.tab:hover { color: var(--color-text); }
+.tab.active { border-bottom-color: var(--color-accent); color: var(--color-text); }
+.tab-panel { display: none; }
+.tab-panel.active { display: block; }
+
+/* ─── Code block ────────────────────────────────────────────────────────── */
+.code-block {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: calc(var(--space) * 4);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  overflow-x: auto;
+  white-space: pre;
+  color: var(--color-text);
+  margin-bottom: calc(var(--space) * 4);
+}
+
+/* ─── Diff ──────────────────────────────────────────────────────────────── */
+.diff-block { font-family: var(--font-mono); font-size: 12px; border: 1px solid var(--color-border); border-radius: var(--radius); overflow: hidden; margin-bottom: calc(var(--space) * 4); }
+.diff-line { display: flex; padding: 2px calc(var(--space) * 3); }
+.diff-line-add { background: color-mix(in srgb, var(--color-ok) 10%, transparent); }
+.diff-line-del { background: color-mix(in srgb, var(--color-error) 10%, transparent); }
+.diff-line-ctx { color: var(--color-muted); }
+.diff-gutter { user-select: none; color: var(--color-muted); min-width: 32px; text-align: right; margin-right: calc(var(--space) * 3); }
+.diff-sign { min-width: 12px; color: var(--color-muted); }
+.diff-line-add .diff-sign { color: var(--color-ok); }
+.diff-line-del .diff-sign { color: var(--color-error); }
+</style>
+</head>
+<body>
+
+<h1>haac-aikit HTML Design System</h1>
+<p>Reference file for HTML artifacts generated by the model. Edit the CSS custom properties at the top of this file to retheme all output.</p>
+
+<section>
+  <h2>Card</h2>
+  <div class="card">
+    <strong>Card title</strong>
+    <p>Use cards to group related content. Nest inside grid or flex containers for multi-column layouts.</p>
+  </div>
+</section>
+
+<section>
+  <h2>Badges</h2>
+  <span class="badge badge-ok">ok</span>
+  <span class="badge badge-warn">warn</span>
+  <span class="badge badge-error">error</span>
+  <span class="badge badge-info">info</span>
+</section>
+
+<section>
+  <h2>Tabs</h2>
+  <div class="tabs" id="demo-tabs">
+    <button class="tab active" data-panel="p1">Option A</button>
+    <button class="tab" data-panel="p2">Option B</button>
+    <button class="tab" data-panel="p3">Option C</button>
+  </div>
+  <div id="p1" class="tab-panel active"><div class="card">Content for Option A.</div></div>
+  <div id="p2" class="tab-panel"><div class="card">Content for Option B.</div></div>
+  <div id="p3" class="tab-panel"><div class="card">Content for Option C.</div></div>
+  <script>
+    document.querySelectorAll('.tabs').forEach(tabGroup => {
+      tabGroup.addEventListener('click', e => {
+        const btn = e.target.closest('.tab');
+        if (!btn) return;
+        tabGroup.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+        btn.classList.add('active');
+        const panelId = btn.dataset.panel;
+        document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
+        document.getElementById(panelId).classList.add('active');
+      });
+    });
+  </script>
+</section>
+
+<section>
+  <h2>Code block</h2>
+  <div class="code-block">const greeting = "hello, world";
+console.log(greeting);</div>
+</section>
+
+<section>
+  <h2>Diff</h2>
+  <div class="diff-block">
+    <div class="diff-line diff-line-ctx"><span class="diff-gutter">1</span><span class="diff-sign"> </span><span>import { foo } from './foo';</span></div>
+    <div class="diff-line diff-line-del"><span class="diff-gutter">2</span><span class="diff-sign">-</span><span>const x = foo();</span></div>
+    <div class="diff-line diff-line-add"><span class="diff-gutter">3</span><span class="diff-sign">+</span><span>const x = await foo();</span></div>
+    <div class="diff-line diff-line-ctx"><span class="diff-gutter">4</span><span class="diff-sign"> </span><span>export { x };</span></div>
+  </div>
+</section>
+
+</body>
+</html>

package/catalog/skills/tier1/html-artifacts.md

@@ -0,0 +1,80 @@
+---
+name: html-artifacts
+description: Use when generating output that would benefit from rich formatting — specs, plans, reports, code review explainers, design prototypes, or custom editors. Teaches when to proactively offer HTML instead of markdown and how to structure each artifact type.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+- Output is > ~80 lines of content
+- Task involves comparison, multiple options, or visual layout
+- User asks for a spec, plan, report, PR explainer, or prototype
+- User mentions "share", "send to team", or "easy to read"
+
+## Proactive offer rule
+When conditions above are met but the user didn't explicitly ask for HTML, say one sentence before proceeding:
+
+> "I can generate this as an HTML artifact for easier reading — want that?"
+
+Wait for a yes/no. If yes, proceed with HTML. If no, use markdown.
+
+## Five use-case patterns
+
+### 1. Spec / Planning
+**Trigger:** Long spec, multiple options to compare  
+**Structure:** Tabs per option, decision log section, embedded mockup slots  
+**Don't:** Skip the decision rationale — that's the whole point of the doc
+
+### 2. Code Review
+**Trigger:** PR explainer, diff walkthrough, architecture audit  
+**Structure:** Rendered diff with color, severity badges (ok/warn/error), inline margin annotations  
+**Don't:** Show a raw unified diff without color — unreadable
+
+### 3. Report / Research
+**Trigger:** Status report, incident summary, research synthesis  
+**Structure:** Executive summary at top, SVG diagrams, section anchors for navigation  
+**Don't:** Bury the conclusion — lead with it
+
+### 4. Prototype
+**Trigger:** Animation tuning, layout exploration, parameter tweaking  
+**Structure:** Sliders/knobs for live adjustment, preview pane, "copy params" export button  
+**Don't:** Ship without an export mechanism — the params need to go somewhere
+
+### 5. Custom Editor
+**Trigger:** Ticket triage, config editing, dataset curation  
+**Structure:** Drag/sort or form UI, constraint warnings, "copy as JSON/prompt" export button  
+**Don't:** Let the editor be the only output — always export
+
+## Built-in design system
+
+Inject this CSS block into every artifact. If the project has `docs/aikit-html-design-system.html`, read it first and use those variable values instead.
+
+```css
+:root {
+  --color-bg:      #0f1117;
+  --color-surface: #1a1d27;
+  --color-border:  #2e3143;
+  --color-text:    #e2e8f0;
+  --color-muted:   #8892a4;
+  --color-accent:  #6366f1;
+  --color-ok:      #22c55e;
+  --color-warn:    #f59e0b;
+  --color-error:   #ef4444;
+  --radius:        6px;
+  --font-sans:     system-ui, -apple-system, sans-serif;
+  --font-mono:     "JetBrains Mono", "Fira Code", monospace;
+  --space:         4px;
+}
+```
+
+Pre-built components available: `.card`, `.badge` (`.badge-ok/warn/error/info`), `.tabs` + `.tab` + `.tab-panel`, `.code-block`, `.diff-block` + `.diff-line` + `.diff-line-add/del/ctx`.
+
+## Output rules
+- Save to `.aikit/artifacts/<slug>-<timestamp>.html` (this path is gitignored)
+- After saving, print the path and suggest: `open <path>` (macOS) or `xdg-open <path>` (Linux)
+- Pure HTML/CSS/JS only — no external CDN dependencies, no build step
+- Mobile-responsive: use `max-width` + `padding` on body, `<meta name="viewport">`
+
+## Markdown-first rule
+Existing brainstorming and planning skills stay markdown-first. Only switch to HTML when the user accepts the proactive offer or explicitly requests it (e.g. via `/html`). This preserves cross-tool compatibility.

package/dist/cli.mjs

@@ -1280,6 +1280,7 @@ function loadCatalog() {
     mcpJson: () => read("mcp/mcp.json"),
     settingsJson: () => read("settings/settings.json"),
     claudeMdReference: () => read("docs/claude-md-reference.md"),
+    htmlDesignSystem: () => read("docs/html-design-system.html"),
     aikitRulesJson: () => read("rules/aikit-rules.json")
   };
 }
@@ -1536,6 +1537,7 @@ async function runSync(argv) {
     results.push(safeWrite(".claude/settings.json", catalog.settingsJson(), { ...opts, useMarkers: false }));
     if (config.scope !== "minimal") {
       results.push(safeWrite("docs/claude-md-reference.md", catalog.claudeMdReference(), { ...opts, useMarkers: false }));
+      results.push(safeWrite("docs/aikit-html-design-system.html", catalog.htmlDesignSystem(), { ...opts, useMarkers: false }));
       results.push(safeWrite(".claude/aikit-rules.json", catalog.aikitRulesJson(), { ...opts, useMarkers: false }));
       results.push(...syncDir("rules/claude-rules", ".claude/rules", opts, [".md"]));
     }