haac-aikit 0.1.1 → 0.7.2

package/dist/cli.mjs

@@ -972,6 +972,10 @@ var init_kleur = __esm({
 });
 
 // src/wizard.ts
+function defaultSpecialtyAgents(scope) {
+  if (scope === "everything") return SPECIALTY_TIER2_AGENTS.map((a2) => a2.value);
+  return [];
+}
 async function runWizard(projectName) {
   we(kleur_default.bgCyan().black(" haac-aikit ") + "  The batteries-included AI-agentic-coding kit");
   const answers = await be(
@@ -1029,6 +1033,15 @@ async function runWizard(projectName) {
           initialValues: ["web"],
           required: false
         });
+      },
+      specialtyAgents: ({ results }) => {
+        if (results.scope === "minimal") return Promise.resolve(void 0);
+        return pe({
+          message: "Include specialty agents? (debugger and pr-describer always installed)",
+          options: SPECIALTY_TIER2_AGENTS.map((a2) => ({ value: a2.value, label: a2.label })),
+          required: false,
+          initialValues: defaultSpecialtyAgents(results.scope ?? "standard")
+        });
       }
     },
     {
@@ -1044,15 +1057,24 @@ async function runWizard(projectName) {
     tools: answers.tools ?? ALL_TOOLS.map((t) => t.value),
     scope: answers.scope ?? "standard",
     integrations: answers.integrations ?? [],
-    shape: answers.shape ?? []
+    shape: answers.shape ?? [],
+    specialtyAgents: answers.specialtyAgents ?? []
   };
 }
-var ALL_TOOLS, ALL_SHAPES, ALL_INTEGRATIONS;
+var SPECIALTY_TIER2_AGENTS, ALL_TOOLS, ALL_SHAPES, ALL_INTEGRATIONS;
 var init_wizard = __esm({
   "src/wizard.ts"() {
     "use strict";
     init_dist2();
     init_kleur();
+    SPECIALTY_TIER2_AGENTS = [
+      { value: "flake-hunter", label: "flake-hunter \u2014 diagnose intermittent test failures" },
+      { value: "simplifier", label: "simplifier \u2014 DRY, dead code, complexity reduction" },
+      { value: "prompt-engineer", label: "prompt-engineer \u2014 author/optimize prompts" },
+      { value: "evals-author", label: "evals-author \u2014 eval datasets & benchmarks" },
+      { value: "changelog-curator", label: "changelog-curator \u2014 generate CHANGELOG from commits" },
+      { value: "dependency-upgrader", label: "dependency-upgrader \u2014 npm major bumps + codemods" }
+    ];
     ALL_TOOLS = [
       { value: "claude", label: "Claude Code", hint: "CLAUDE.md + .claude/" },
       { value: "cursor", label: "Cursor", hint: ".cursor/rules/" },
@@ -1131,6 +1153,15 @@ ${end}
 `;
   return { hasMarkers: false, replaced };
 }
+function extractMarkerRegion(content, filePath) {
+  const dialect = detectDialect(filePath);
+  const begin = makeBegin(dialect);
+  const end = makeEnd(dialect);
+  const beginIdx = content.indexOf(begin);
+  const endIdx = content.indexOf(end);
+  if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) return null;
+  return content.slice(beginIdx + begin.length, endIdx).trim();
+}
 var MARKER;
 var init_markers = __esm({
   "src/render/markers.ts"() {
@@ -1147,11 +1178,18 @@ function safeWrite(filePath, content, opts = {}) {
   const existed = existsSync2(filePath);
   if (existed) {
     if (useMarkers && managedContent !== void 0) {
-      const existing = readFileSync2(filePath, "utf8");
-      const { replaced } = upsertMarkerRegion(existing, managedContent, filePath);
+      const existing2 = readFileSync2(filePath, "utf8");
+      const { replaced } = upsertMarkerRegion(existing2, managedContent, filePath);
+      if (existing2 === replaced) {
+        return { path: filePath, action: "skipped" };
+      }
       if (!dryRun) writeFileSync2(filePath, replaced, "utf8");
       return { path: filePath, action: "updated" };
     }
+    const existing = readFileSync2(filePath, "utf8");
+    if (existing === content) {
+      return { path: filePath, action: "skipped" };
+    }
     if (!force) {
       return { path: filePath, action: "conflict" };
     }
@@ -1187,6 +1225,7 @@ var init_gitignore = __esm({
     ENTRIES = [
       ".claude/settings.local.json",
       ".claude/backups/",
+      ".aikit/",
       ".env.local",
       ".env*.local"
     ];
@@ -1209,11 +1248,24 @@ var init_template = __esm({
 });
 
 // src/catalog/index.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { fileURLToPath } from "url";
 import { dirname as dirname2, join } from "path";
+function findCatalogRoot() {
+  let dir = dirname2(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, "catalog");
+    if (existsSync4(join(candidate, "rules", "AGENTS.md.tmpl"))) {
+      return candidate;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error("haac-aikit: catalog/ directory not found relative to module location");
+}
 function read(rel) {
-  return readFileSync4(join(ROOT, rel), "utf8");
+  return readFileSync4(join(CATALOG_ROOT, rel), "utf8");
 }
 function loadCatalog() {
   return {
@@ -1226,26 +1278,241 @@ function loadCatalog() {
     aiderConf: () => read("rules/aider.conf.yml"),
     geminiMd: () => read("rules/GEMINI.md.shim"),
     mcpJson: () => read("mcp/mcp.json"),
-    settingsJson: () => read("settings/settings.json")
+    settingsJson: () => read("settings/settings.json"),
+    claudeMdReference: () => read("docs/claude-md-reference.md"),
+    aikitRulesJson: () => read("rules/aikit-rules.json")
   };
 }
-var ROOT;
+var CATALOG_ROOT;
 var init_catalog = __esm({
   "src/catalog/index.ts"() {
     "use strict";
     init_template();
-    ROOT = join(dirname2(fileURLToPath(import.meta.url)), "..", "catalog");
+    CATALOG_ROOT = findCatalogRoot();
+  }
+});
+
+// src/catalog/shape-agents.ts
+function resolveShapeAgents(shapes) {
+  const set = /* @__PURE__ */ new Set();
+  for (const shape of shapes) {
+    for (const agent of SHAPE_AGENTS[shape] ?? []) {
+      set.add(agent);
+    }
+  }
+  return Array.from(set);
+}
+var SHAPE_AGENTS;
+var init_shape_agents = __esm({
+  "src/catalog/shape-agents.ts"() {
+    "use strict";
+    SHAPE_AGENTS = {
+      web: ["frontend"],
+      fullstack: ["frontend", "backend"],
+      backend: ["backend"],
+      mobile: ["mobile"],
+      library: ["backend"]
+    };
+  }
+});
+
+// src/render/dialects/parser.ts
+function parseRuleSet(content, projectName, description) {
+  const rules = [];
+  const rawSections = /* @__PURE__ */ new Map();
+  let currentSection = "";
+  let sectionBuffer = [];
+  const flushSection = () => {
+    if (currentSection && sectionBuffer.length > 0) {
+      rawSections.set(currentSection, sectionBuffer.join("\n").trim());
+    }
+  };
+  for (const line of content.split("\n")) {
+    const sectionMatch = line.match(SECTION_RX);
+    if (sectionMatch?.[1]) {
+      flushSection();
+      currentSection = sectionMatch[1].trim();
+      sectionBuffer = [];
+      continue;
+    }
+    sectionBuffer.push(line);
+    const idMatch = line.match(ID_LINE_RX);
+    if (idMatch?.groups?.id) {
+      const text = line.replace(RULE_PREFIX_RX, "").trim();
+      rules.push({
+        id: idMatch.groups.id,
+        text: text || idMatch.groups.id,
+        meta: parseMeta(idMatch.groups.meta ?? ""),
+        section: currentSection
+      });
+    }
+  }
+  flushSection();
+  return { projectName, description, rules, rawSections };
+}
+function parseMeta(metaString) {
+  const meta = {};
+  for (const part of metaString.trim().split(/\s+/).filter(Boolean)) {
+    const eq = part.indexOf("=");
+    if (eq < 1) continue;
+    const key = part.slice(0, eq);
+    const value = part.slice(eq + 1);
+    if (key === "emphasis" && (value === "high" || value === "normal" || value === "low")) {
+      meta.emphasis = value;
+    } else if (key === "paths") {
+      meta.paths = value.split(",").map((p2) => p2.trim()).filter(Boolean);
+    }
+  }
+  return meta;
+}
+var ID_LINE_RX, RULE_PREFIX_RX, SECTION_RX;
+var init_parser = __esm({
+  "src/render/dialects/parser.ts"() {
+    "use strict";
+    ID_LINE_RX = /<!--\s*id:\s*(?<id>[a-zA-Z][a-zA-Z0-9_-]*\.[a-zA-Z0-9._-]+)(?<meta>(?:\s+[a-zA-Z][a-zA-Z0-9_-]*=[^>\s]+)*)\s*-->/;
+    RULE_PREFIX_RX = /^(\s*[-*]\s*)?<!--\s*id:[^>]+-->\s*/;
+    SECTION_RX = /^##\s+(.+)$/;
+  }
+});
+
+// src/render/dialects/cursor.ts
+function translateForCursor(ruleSet) {
+  const lines = [];
+  lines.push("---");
+  lines.push(`description: Project rules for ${ruleSet.projectName} \u2014 generated from AGENTS.md by haac-aikit`);
+  lines.push("alwaysApply: true");
+  lines.push("---");
+  lines.push("");
+  lines.push("<!-- BEGIN:haac-aikit -->");
+  lines.push(`# ${ruleSet.projectName}`);
+  lines.push("");
+  if (ruleSet.description) {
+    lines.push(ruleSet.description);
+    lines.push("");
+  }
+  lines.push(`See [AGENTS.md](../../AGENTS.md) for the authoritative rule set. Cursor-specific dialect:`);
+  lines.push("");
+  if (ruleSet.rules.length === 0) {
+    lines.push("_No annotated rules found in AGENTS.md. Add `<!-- id: x.y -->` comments to opt rules into Cursor translation._");
+  } else {
+    const bySection = /* @__PURE__ */ new Map();
+    for (const rule of ruleSet.rules) {
+      const section = rule.section || "Rules";
+      const existing = bySection.get(section) ?? [];
+      existing.push(rule);
+      bySection.set(section, existing);
+    }
+    for (const [section, rules] of bySection) {
+      lines.push(`## ${section}`);
+      lines.push("");
+      for (const rule of rules) {
+        const prefix = rule.meta.emphasis === "high" ? "**" : "";
+        const suffix = rule.meta.emphasis === "high" ? "**" : "";
+        const pathsHint = rule.meta.paths && rule.meta.paths.length > 0 ? ` _(applies to: \`${rule.meta.paths.join("`, `")}\`)_` : "";
+        lines.push(`- ${prefix}${rule.text}${suffix}${pathsHint}  <!-- id: ${rule.id} -->`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push("<!-- END:haac-aikit -->");
+  return lines.join("\n");
+}
+var init_cursor = __esm({
+  "src/render/dialects/cursor.ts"() {
+    "use strict";
+  }
+});
+
+// src/render/dialects/index.ts
+var init_dialects = __esm({
+  "src/render/dialects/index.ts"() {
+    "use strict";
+    init_parser();
+    init_cursor();
+  }
+});
+
+// src/fs/diff.ts
+import { createPatch } from "diff";
+function formatUnifiedDiff(local, incoming) {
+  if (local === incoming) return "";
+  const raw = createPatch("local", local, incoming, "", "", { context: 3 });
+  const lines = [];
+  let inHunk = false;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("@@")) {
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk) continue;
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      lines.push(kleur_default.green(`+ ${line.slice(1)}`));
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      lines.push(kleur_default.red(`- ${line.slice(1)}`));
+    } else if (line.startsWith(" ")) {
+      lines.push(kleur_default.dim(`  ${line.slice(1)}`));
+    }
+  }
+  return lines.join("\n");
+}
+var init_diff = __esm({
+  "src/fs/diff.ts"() {
+    "use strict";
+    init_kleur();
+  }
+});
+
+// src/fs/conflict.ts
+import { basename } from "path";
+function inferTier3Slot(filePath) {
+  if ((filePath.includes("/.claude/agents/") || filePath.startsWith(".claude/agents/")) && filePath.endsWith(".md")) return "agents";
+  if ((filePath.includes("/.claude/skills/") || filePath.startsWith(".claude/skills/")) && filePath.endsWith(".md")) return "skills";
+  return null;
+}
+var interactivePrompt;
+var init_conflict = __esm({
+  "src/fs/conflict.ts"() {
+    "use strict";
+    init_dist2();
+    init_diff();
+    interactivePrompt = {
+      async ask(filePath, local, incoming) {
+        while (true) {
+          const choice = await de({
+            message: `Modified locally: ${filePath}`,
+            options: [
+              { value: "replace", label: "Replace with catalog version (recommended)" },
+              { value: "keep", label: "Keep local version (mark as tier3 to silence future prompts)" },
+              { value: "diff", label: "Show diff first" },
+              { value: "replace_all", label: "Replace all remaining conflicts" },
+              { value: "skip_all", label: "Skip all remaining conflicts" }
+            ],
+            initialValue: "replace"
+          });
+          if (BD(choice)) {
+            ve("Sync cancelled");
+            process.exit(0);
+          }
+          if (choice === "diff") {
+            const out = formatUnifiedDiff(local, incoming);
+            ye(out, basename(filePath));
+            continue;
+          }
+          return choice;
+        }
+      }
+    };
   }
 });
 
 // src/commands/sync.ts
 var sync_exports = {};
 __export(sync_exports, {
+  copyAction: () => copyAction,
   runSync: () => runSync
 });
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, copyFileSync, readdirSync, readFileSync as readFileSync5 } from "fs";
-import { join as join2, dirname as dirname3 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, copyFileSync, readdirSync, readFileSync as readFileSync5, chmodSync } from "fs";
+import { basename as basename2, dirname as dirname3, join as join2 } from "path";
 async function runSync(argv) {
   const dryRun = argv["dry-run"];
   const force = argv.force;
@@ -1262,16 +1529,24 @@ async function runSync(argv) {
     projectName: config.projectName,
     description: config.projectDescription ?? ""
   });
-  results.push(safeWrite("AGENTS.md", agentsMdContent, { ...opts, useMarkers: true, managedContent: agentsMdContent }));
+  const agentsMdManaged = extractMarkerRegion(agentsMdContent, "AGENTS.md") ?? agentsMdContent;
+  results.push(safeWrite("AGENTS.md", agentsMdContent, { ...opts, useMarkers: true, managedContent: agentsMdManaged }));
   if (config.tools.includes("claude")) {
     results.push(safeWrite("CLAUDE.md", catalog.claudeMd(), { ...opts, useMarkers: false }));
     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(".claude/aikit-rules.json", catalog.aikitRulesJson(), { ...opts, useMarkers: false }));
+      results.push(...syncDir("rules/claude-rules", ".claude/rules", opts, [".md"]));
+    }
   }
   if (config.tools.includes("copilot")) {
     results.push(safeWrite(".github/copilot-instructions.md", catalog.copilotInstructions(), { ...opts, useMarkers: false }));
   }
   if (config.tools.includes("cursor")) {
-    results.push(safeWrite(".cursor/rules/000-base.mdc", catalog.cursorBase(), { ...opts, useMarkers: false }));
+    const ruleSet = parseRuleSet(agentsMdContent, config.projectName, config.projectDescription ?? "");
+    const cursorContent = translateForCursor(ruleSet);
+    results.push(safeWrite(".cursor/rules/000-base.mdc", cursorContent, { ...opts, useMarkers: false }));
   }
   if (config.tools.includes("windsurf")) {
     results.push(safeWrite(".windsurf/rules/project.md", catalog.windsurfRules(), { ...opts, useMarkers: false }));
@@ -1287,148 +1562,232 @@ async function runSync(argv) {
     results.push(safeWrite(".mcp.json", catalog.mcpJson(), { ...opts, useMarkers: false }));
   }
   if (config.scope !== "minimal") {
-    results.push(...syncSkills("tier1", dryRun));
-    results.push(...syncSkills("tier2", dryRun));
+    results.push(...syncSkills("tier1", opts));
+    results.push(...syncSkills("tier2", opts));
   }
   if (config.integrations.hooks) {
-    results.push(...syncHooks(dryRun));
+    results.push(...syncHooks(opts));
   }
   if (config.integrations.subagents) {
-    results.push(...syncAgents(config.shape, dryRun));
+    results.push(...syncAgents(config, opts));
   }
   if (config.integrations.commands) {
-    results.push(...syncCommands(dryRun));
+    results.push(...syncCommands(opts));
   }
   if (config.integrations.ci) {
-    results.push(...syncCI(dryRun));
+    results.push(...syncCI(opts));
   }
   if (config.integrations.devcontainer) {
-    results.push(...syncDir("devcontainer", ".devcontainer", dryRun, [".json"]));
+    results.push(...syncDir("devcontainer", ".devcontainer", opts, [".json"]));
   }
   if (config.integrations.otel) {
     results.push(safeWrite(".env.example", readCatalogFile("settings/env.example"), { dryRun, useMarkers: false }));
   }
+  if (config.integrations.husky) {
+    results.push(...syncDir("husky", ".husky", opts, []));
+  }
+  if (config.integrations.plugin) {
+    const tmpl = readCatalogFile("plugin/plugin.json");
+    const content = interpolate(tmpl, { projectName: config.projectName });
+    results.push(safeWrite(".claude/plugin/plugin.json", content, { ...opts, useMarkers: false }));
+  }
   ensureGitignoreEntries(dryRun);
+  const conflicts = results.filter((r2) => r2.action === "conflict");
+  if (conflicts.length > 0 && !force) {
+    const isInteractive2 = (Boolean(process.stdin.isTTY) || argv._conflictPrompt != null) && !argv.yes;
+    if (isInteractive2) {
+      const prompt = argv._conflictPrompt ?? interactivePrompt;
+      let bulkAction = null;
+      let configMutated = false;
+      let workingConfig = config;
+      v2.info(`Found ${conflicts.length} file(s) modified locally. Reviewing each\u2026`);
+      for (const conflict of conflicts) {
+        const incomingSrc = conflict.src;
+        if (!incomingSrc) continue;
+        if (bulkAction === "skip_all") {
+          conflict.action = "skipped";
+          continue;
+        }
+        let resolution;
+        if (bulkAction === "replace_all") {
+          resolution = "replace";
+        } else {
+          const local = readFileSync5(conflict.path, "utf8");
+          const incoming = readFileSync5(incomingSrc, "utf8");
+          resolution = await prompt.ask(conflict.path, local, incoming);
+          if (resolution === "replace_all") bulkAction = "replace_all";
+          if (resolution === "skip_all") {
+            bulkAction = "skip_all";
+            conflict.action = "skipped";
+            continue;
+          }
+        }
+        if (resolution === "replace" || resolution === "replace_all") {
+          if (!opts.dryRun) copyFileSync(incomingSrc, conflict.path);
+          conflict.action = "updated";
+        } else if (resolution === "keep") {
+          const slot = inferTier3Slot(conflict.path);
+          if (slot) {
+            const name = basename2(conflict.path).replace(/\.md$/, "");
+            const current = workingConfig[slot] ?? { tier1: "all", tier2: "all", tier3: [] };
+            if (!current.tier3.includes(name)) {
+              workingConfig = {
+                ...workingConfig,
+                [slot]: { ...current, tier3: [...current.tier3, name] }
+              };
+              configMutated = true;
+            }
+          } else {
+            v2.warn(
+              `Kept ${conflict.path} \u2014 no tier3 protection available; this file will be flagged again on next sync.`
+            );
+          }
+          conflict.action = "skipped";
+        }
+      }
+      if (configMutated && !opts.dryRun) {
+        writeConfig(workingConfig);
+      }
+    }
+  }
   const created = results.filter((r2) => r2.action === "created").length;
   const updated = results.filter((r2) => r2.action === "updated").length;
-  const conflicts = results.filter((r2) => r2.action === "conflict");
+  const skipped = results.filter((r2) => r2.action === "skipped").length;
+  const remainingConflicts = results.filter((r2) => r2.action === "conflict");
+  const visible = dryRun ? results : results.filter((r2) => r2.action !== "skipped");
   if (dryRun) {
-    ye(results.map((r2) => `${r2.action.padEnd(9)} ${r2.path}`).join("\n"), "Dry run");
+    ye(visible.map((r2) => `${r2.action.padEnd(9)} ${r2.path}`).join("\n"), "Dry run");
     return;
   }
-  ye(
-    results.map((r2) => `${r2.action.padEnd(9)} ${r2.path}`).join("\n"),
-    `${created} created, ${updated} updated`
-  );
-  if (conflicts.length > 0) {
-    v2.warn(`${conflicts.length} conflict(s) skipped (use --force to overwrite)`);
+  if (visible.length > 0) {
+    ye(
+      visible.map((r2) => `${r2.action.padEnd(9)} ${r2.path}`).join("\n"),
+      `${created} created, ${updated} updated, ${skipped} unchanged`
+    );
+  } else {
+    v2.info(`Already up to date \u2014 ${skipped} files match the catalog.`);
+  }
+  if (remainingConflicts.length > 0) {
+    v2.warn(`${remainingConflicts.length} conflict(s) skipped (use --force to overwrite)`);
   }
   fe("Sync complete.");
 }
-function syncSkills(tier, dryRun) {
+function copyAction(srcPath, destPath, opts) {
+  const existed = existsSync5(destPath);
+  const incoming = readFileSync5(srcPath, "utf8");
+  if (existed) {
+    const current = readFileSync5(destPath, "utf8");
+    if (current === incoming) {
+      return { path: destPath, action: "skipped", src: srcPath };
+    }
+    if (!opts.force) {
+      return { path: destPath, action: "conflict", src: srcPath };
+    }
+  }
+  if (!opts.dryRun) {
+    mkdirSync2(dirname3(destPath), { recursive: true });
+    copyFileSync(srcPath, destPath);
+    if (destPath.endsWith(".sh") || destPath.includes("/.husky/") || destPath.includes("/.claude/hooks/")) {
+      chmodSync(destPath, 493);
+    }
+  }
+  return { path: destPath, action: existed ? "updated" : "created", src: srcPath };
+}
+function syncSkills(tier, opts) {
   const srcDir = join2(CATALOG_ROOT, "skills", tier);
   const destDir = `.claude/skills`;
   const results = [];
-  if (!existsSync4(srcDir)) return results;
+  if (!existsSync5(srcDir)) return results;
   const files = readdirSync(srcDir).filter((f2) => f2.endsWith(".md"));
-  if (!dryRun) mkdirSync2(destDir, { recursive: true });
+  if (!opts.dryRun) mkdirSync2(destDir, { recursive: true });
   for (const file of files) {
-    const dest = join2(destDir, file);
-    if (!dryRun) copyFileSync(join2(srcDir, file), dest);
-    results.push({ path: dest, action: existsSync4(dest) ? "updated" : "created" });
+    results.push(copyAction(join2(srcDir, file), join2(destDir, file), opts));
   }
   return results;
 }
-function syncHooks(dryRun) {
+function syncHooks(opts) {
   const srcDir = join2(CATALOG_ROOT, "hooks");
   const destDir = `.claude/hooks`;
   const results = [];
-  if (!existsSync4(srcDir)) return results;
+  if (!existsSync5(srcDir)) return results;
   const files = readdirSync(srcDir).filter((f2) => f2.endsWith(".sh") || f2 === "hooks.json");
-  if (!dryRun) mkdirSync2(destDir, { recursive: true });
+  if (!opts.dryRun) mkdirSync2(destDir, { recursive: true });
   for (const file of files) {
-    const dest = join2(destDir, file);
-    if (!dryRun) copyFileSync(join2(srcDir, file), dest);
-    results.push({ path: dest, action: existsSync4(dest) ? "updated" : "created" });
+    results.push(copyAction(join2(srcDir, file), join2(destDir, file), opts));
   }
   return results;
 }
-function syncAgents(shapes, dryRun) {
-  const srcDir = join2(CATALOG_ROOT, "agents");
-  const destDir = `.claude/agents`;
+function syncAgents(config, opts) {
   const results = [];
-  if (!existsSync4(srcDir)) return results;
-  const CORE_AGENTS = ["orchestrator", "planner", "researcher", "implementer", "reviewer", "tester", "security-auditor", "devops"];
-  const SHAPE_AGENTS = {
-    web: ["frontend"],
-    fullstack: ["frontend", "backend"],
-    backend: ["backend"],
-    mobile: ["mobile"],
-    library: ["backend"]
-  };
-  const agentsToInstall = new Set(CORE_AGENTS);
-  for (const shape of shapes) {
-    for (const agent of SHAPE_AGENTS[shape] ?? []) {
-      agentsToInstall.add(agent);
-    }
+  results.push(...syncAgentTier("tier1", config.agents?.tier1 ?? "all", opts));
+  results.push(...syncAgentTier("tier2", resolveTier2Set(config), opts));
+  return results;
+}
+function resolveTier2Set(config) {
+  if (config.agents?.tier2 === "all") return "all";
+  const set = new Set(
+    Array.isArray(config.agents?.tier2) ? config.agents.tier2 : []
+  );
+  for (const agent of resolveShapeAgents(config.shape)) {
+    set.add(agent);
   }
-  if (!dryRun) mkdirSync2(destDir, { recursive: true });
+  return Array.from(set);
+}
+function syncAgentTier(tier, selection, opts) {
+  const srcDir = join2(CATALOG_ROOT, "agents", tier);
+  const destDir = ".claude/agents";
+  const results = [];
+  if (!existsSync5(srcDir)) return results;
+  const allAgents = readdirSync(srcDir).filter((f2) => f2.endsWith(".md")).map((f2) => f2.replace(/\.md$/, ""));
+  const agentsToInstall = selection === "all" ? allAgents : allAgents.filter((a2) => selection.includes(a2));
+  if (!opts.dryRun) mkdirSync2(destDir, { recursive: true });
   for (const agent of agentsToInstall) {
     const src = join2(srcDir, `${agent}.md`);
     const dest = join2(destDir, `${agent}.md`);
-    if (!existsSync4(src)) continue;
-    if (!dryRun) copyFileSync(src, dest);
-    results.push({ path: dest, action: existsSync4(dest) ? "updated" : "created" });
+    results.push(copyAction(src, dest, opts));
   }
   return results;
 }
-function syncCommands(dryRun) {
+function syncCommands(opts) {
   const srcDir = join2(CATALOG_ROOT, "commands");
   const destDir = `.claude/commands`;
   const results = [];
-  if (!existsSync4(srcDir)) return results;
+  if (!existsSync5(srcDir)) return results;
   const files = readdirSync(srcDir).filter((f2) => f2.endsWith(".md"));
-  if (!dryRun) mkdirSync2(destDir, { recursive: true });
+  if (!opts.dryRun) mkdirSync2(destDir, { recursive: true });
   for (const file of files) {
-    const dest = join2(destDir, file);
-    if (!dryRun) copyFileSync(join2(srcDir, file), dest);
-    results.push({ path: dest, action: existsSync4(dest) ? "updated" : "created" });
+    results.push(copyAction(join2(srcDir, file), join2(destDir, file), opts));
   }
   return results;
 }
-function syncCI(dryRun) {
+function syncCI(opts) {
   const srcDir = join2(CATALOG_ROOT, "ci");
   const destDir = `.github/workflows`;
   const results = [];
-  if (!existsSync4(srcDir)) return results;
+  if (!existsSync5(srcDir)) return results;
   const files = readdirSync(srcDir).filter((f2) => f2.endsWith(".yml"));
-  if (!dryRun) mkdirSync2(destDir, { recursive: true });
+  if (!opts.dryRun) mkdirSync2(destDir, { recursive: true });
   for (const file of files) {
-    const dest = join2(destDir, file);
-    if (!dryRun) copyFileSync(join2(srcDir, file), dest);
-    results.push({ path: dest, action: existsSync4(dest) ? "updated" : "created" });
+    results.push(copyAction(join2(srcDir, file), join2(destDir, file), opts));
   }
   return results;
 }
-function syncDir(catalogSubdir, destDir, dryRun, extensions = [".md", ".json", ".yml", ".yaml"]) {
+function syncDir(catalogSubdir, destDir, opts, extensions = [".md", ".json", ".yml", ".yaml"]) {
   const srcDir = join2(CATALOG_ROOT, catalogSubdir);
   const results = [];
-  if (!existsSync4(srcDir)) return results;
+  if (!existsSync5(srcDir)) return results;
   const files = readdirSync(srcDir).filter(
-    (f2) => extensions.some((ext) => f2.endsWith(ext))
+    (f2) => extensions.length === 0 || extensions.some((ext) => f2.endsWith(ext))
   );
-  if (!dryRun) mkdirSync2(destDir, { recursive: true });
+  if (!opts.dryRun) mkdirSync2(destDir, { recursive: true });
   for (const file of files) {
-    const dest = join2(destDir, file);
-    if (!dryRun) copyFileSync(join2(srcDir, file), dest);
-    results.push({ path: dest, action: existsSync4(dest) ? "updated" : "created" });
+    results.push(copyAction(join2(srcDir, file), join2(destDir, file), opts));
   }
   return results;
 }
 function readCatalogFile(rel) {
   return readFileSync5(join2(CATALOG_ROOT, rel), "utf8");
 }
-var CATALOG_ROOT;
 var init_sync = __esm({
   "src/commands/sync.ts"() {
     "use strict";
@@ -1437,7 +1796,11 @@ var init_sync = __esm({
     init_safeWrite();
     init_gitignore();
     init_catalog();
-    CATALOG_ROOT = join2(dirname3(fileURLToPath2(import.meta.url)), "..", "catalog");
+    init_shape_agents();
+    init_dialects();
+    init_template();
+    init_markers();
+    init_conflict();
   }
 });
 
@@ -1446,7 +1809,7 @@ var init_exports = {};
 __export(init_exports, {
   runInit: () => runInit
 });
-import { basename } from "path";
+import { basename as basename3 } from "path";
 async function runInit(argv, headless) {
   const dryRun = argv["dry-run"];
   if (!argv["skip-git-check"] && !headless && isGitRepo() && isDirtyTree()) {
@@ -1467,13 +1830,13 @@ async function runInit(argv, headless) {
   }
   let config;
   if (headless || argv.yes) {
-    const projectName = basename(process.cwd());
+    const projectName = basename3(process.cwd());
     const tools = parseTools(argv.tools);
     const scope = argv.preset ?? "standard";
     const integrations = defaultIntegrationsForScope(scope);
-    config = buildDefaultConfig(projectName, "", tools, scope, integrations, []);
+    config = buildDefaultConfig(projectName, "", tools, scope, integrations, [], defaultSpecialtyAgents(scope));
   } else {
-    const answers = await runWizard(basename(process.cwd()));
+    const answers = await runWizard(basename3(process.cwd()));
     const defaultIntegrations = defaultIntegrationsForScope(answers.scope);
     const integrations = answers.integrations.length > 0 ? answers.integrations : defaultIntegrations;
     config = buildDefaultConfig(
@@ -1482,7 +1845,8 @@ async function runInit(argv, headless) {
       answers.tools,
       answers.scope,
       integrations,
-      answers.shape
+      answers.shape,
+      answers.specialtyAgents
     );
   }
   writeConfig(config, argv.config ?? ".aikitrc.json", dryRun);
@@ -1500,7 +1864,9 @@ function defaultIntegrationsForScope(scope) {
   if (scope === "standard") return ["mcp", "hooks", "commands", "subagents", "ci", "husky"];
   return ["mcp", "hooks", "commands", "subagents", "ci", "husky", "devcontainer", "plugin", "otel"];
 }
-function buildDefaultConfig(projectName, projectDescription, tools, scope, integrations, shape) {
+function buildDefaultConfig(projectName, projectDescription, tools, scope, integrations, shape, specialtyAgents) {
+  const allSpecialtyValues = new Set(SPECIALTY_TIER2_AGENTS.map((a2) => a2.value));
+  const agentTier2 = specialtyAgents.length === allSpecialtyValues.size && specialtyAgents.every((a2) => allSpecialtyValues.has(a2)) ? "all" : specialtyAgents;
   return {
     version: 1,
     projectName,
@@ -1520,6 +1886,7 @@ function buildDefaultConfig(projectName, projectDescription, tools, scope, integ
       otel: integrations.includes("otel")
     },
     skills: { tier1: "all", tier2: "all", tier3: [] },
+    agents: { tier1: "all", tier2: agentTier2, tier3: [] },
     canonical: "AGENTS.md"
   };
 }
@@ -1538,9 +1905,8 @@ var diff_exports = {};
 __export(diff_exports, {
   runDiff: () => runDiff
 });
-import { existsSync as existsSync5, readFileSync as readFileSync6, readdirSync as readdirSync2 } from "fs";
-import { dirname as dirname4, join as join3 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { existsSync as existsSync6, readFileSync as readFileSync6, readdirSync as readdirSync2 } from "fs";
+import { join as join3 } from "path";
 async function runDiff(argv) {
   const config = readConfig(argv.config);
   if (!config) {
@@ -1550,7 +1916,7 @@ async function runDiff(argv) {
   const catalog = loadCatalog();
   const drifted = [];
   const missing = [];
-  if (existsSync5("AGENTS.md")) {
+  if (existsSync6("AGENTS.md")) {
     const current = readFileSync6("AGENTS.md", "utf8");
     const freshContent = catalog.agentsMd({
       projectName: config.projectName,
@@ -1568,8 +1934,30 @@ async function runDiff(argv) {
   }
   checkCatalogDir("skills/tier1", ".claude/skills", missing, drifted);
   checkCatalogDir("skills/tier2", ".claude/skills", missing, drifted);
-  checkCatalogDir("agents", ".claude/agents", missing, drifted);
+  checkCatalogDir("agents/tier1", ".claude/agents", missing, drifted);
+  checkCatalogAgentsTier2(config, missing, drifted);
   checkCatalogDir("hooks", ".claude/hooks", missing, drifted, [".sh"]);
+  if (config.tools.includes("claude") && config.scope !== "minimal") {
+    checkCatalogDir("rules/claude-rules", ".claude/rules", missing, drifted);
+    const refPath = "docs/claude-md-reference.md";
+    if (!existsSync6(refPath)) {
+      missing.push(refPath);
+    } else {
+      const fresh = catalog.claudeMdReference();
+      if (readFileSync6(refPath, "utf8") !== fresh) {
+        drifted.push(refPath);
+      }
+    }
+    const rulesPath = ".claude/aikit-rules.json";
+    if (!existsSync6(rulesPath)) {
+      missing.push(rulesPath);
+    } else {
+      const fresh = catalog.aikitRulesJson();
+      if (readFileSync6(rulesPath, "utf8") !== fresh) {
+        drifted.push(rulesPath);
+      }
+    }
+  }
   if (missing.length === 0 && drifted.length === 0) {
     process.stdout.write(kleur_default.green("\u2713 No drift \u2014 project is in sync with catalog.\n"));
     return;
@@ -1596,15 +1984,43 @@ function extractRegion(content, begin, end) {
   if (bi === -1 || ei === -1) return "";
   return content.slice(bi + begin.length, ei).trim();
 }
+function checkCatalogAgentsTier2(config, missing, drifted) {
+  const tier2Selection = config.agents?.tier2;
+  if (tier2Selection === "all") {
+    checkCatalogDir("agents/tier2", ".claude/agents", missing, drifted);
+    return;
+  }
+  const expected = new Set(
+    Array.isArray(tier2Selection) ? tier2Selection : []
+  );
+  for (const agent of resolveShapeAgents(config.shape)) {
+    expected.add(agent);
+  }
+  if (expected.size === 0) return;
+  const tier2Dir = join3(CATALOG_ROOT, "agents", "tier2");
+  if (!existsSync6(tier2Dir)) return;
+  for (const name of expected) {
+    const catalogPath = join3(tier2Dir, `${name}.md`);
+    const installedPath = join3(".claude/agents", `${name}.md`);
+    if (!existsSync6(catalogPath)) continue;
+    if (!existsSync6(installedPath)) {
+      missing.push(`agents/${name}.md`);
+      continue;
+    }
+    if (readFileSync6(catalogPath, "utf8") !== readFileSync6(installedPath, "utf8")) {
+      drifted.push(`agents/${name}.md`);
+    }
+  }
+}
 function checkCatalogDir(catalogSubdir, installedDir, missing, drifted, extensions = [".md"]) {
-  const catalogDir = join3(CATALOG_ROOT2, catalogSubdir);
-  if (!existsSync5(catalogDir)) return;
+  const catalogDir = join3(CATALOG_ROOT, catalogSubdir);
+  if (!existsSync6(catalogDir)) return;
   const files = readdirSync2(catalogDir).filter(
     (f2) => extensions.some((ext) => f2.endsWith(ext))
   );
   for (const file of files) {
     const installedPath = join3(installedDir, file);
-    if (!existsSync5(installedPath)) {
+    if (!existsSync6(installedPath)) {
       missing.push(`${installedDir}/${file}`);
       continue;
     }
@@ -1615,14 +2031,13 @@ function checkCatalogDir(catalogSubdir, installedDir, missing, drifted, extensio
     }
   }
 }
-var CATALOG_ROOT2;
-var init_diff = __esm({
+var init_diff2 = __esm({
   "src/commands/diff.ts"() {
     "use strict";
     init_kleur();
     init_readConfig();
     init_catalog();
-    CATALOG_ROOT2 = join3(dirname4(fileURLToPath3(import.meta.url)), "..", "catalog");
+    init_shape_agents();
   }
 });
 
@@ -1637,13 +2052,20 @@ async function runUpdate(argv) {
     v2.error(".aikitrc.json not found. Run `aikit` to initialise.");
     process.exit(1);
   }
-  const { runDiff: runDiff2 } = await Promise.resolve().then(() => (init_diff(), diff_exports));
+  const { runDiff: runDiff2 } = await Promise.resolve().then(() => (init_diff2(), diff_exports));
   await runDiff2({ ...argv, "dry-run": true });
   if (argv.yes) {
     const { runSync: runSync3 } = await Promise.resolve().then(() => (init_sync(), sync_exports));
     await runSync3(argv);
     return;
   }
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    process.stderr.write(
+      kleur_default.yellow("aikit update is interactive. ") + `In a non-TTY context (CI, pipes, scripts), run ${kleur_default.cyan("aikit update --yes")} or ${kleur_default.cyan("aikit sync --force")} instead.
+`
+    );
+    process.exit(1);
+  }
   const proceed = await me({
     message: "Apply these updates?",
     initialValue: true
@@ -1659,6 +2081,7 @@ var init_update = __esm({
   "src/commands/update.ts"() {
     "use strict";
     init_dist2();
+    init_kleur();
     init_readConfig();
   }
 });
@@ -1668,74 +2091,196 @@ var add_exports = {};
 __export(add_exports, {
   runAdd: () => runAdd
 });
-import { copyFileSync as copyFileSync2, existsSync as existsSync6, mkdirSync as mkdirSync3, readdirSync as readdirSync3 } from "fs";
-import { dirname as dirname5, join as join4 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { copyFileSync as copyFileSync2, existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync as readdirSync3 } from "fs";
+import { join as join4 } from "path";
 async function runAdd(argv) {
   const itemArg = argv._[1];
   if (!itemArg) {
     v2.error("Usage: aikit add <name>  (e.g. aikit add brainstorming)");
     process.exit(1);
   }
-  for (const [_type, spec] of Object.entries(ITEM_DIRS)) {
-    for (const tier of ["tier1", "tier2", ""]) {
-      const catalogDir = join4(CATALOG_ROOT3, tier ? `skills/${tier}` : spec.catalog);
-      if (!existsSync6(catalogDir)) continue;
-      for (const ext of spec.ext) {
-        const srcFile = join4(catalogDir, `${itemArg}${ext}`);
-        if (existsSync6(srcFile)) {
-          const dest = spec.dest;
-          const destFile = join4(dest, `${itemArg}${ext}`);
-          if (existsSync6(destFile) && !argv.force) {
-            v2.warn(`${destFile} already exists. Use --force to overwrite.`);
-            return;
-          }
-          if (!argv["dry-run"]) {
-            mkdirSync3(dest, { recursive: true });
-            copyFileSync2(srcFile, destFile);
-          }
-          process.stdout.write(
-            `${argv["dry-run"] ? "[dry-run] " : ""}${kleur_default.green("\u2713")} Added ${destFile}
-`
-          );
-          return;
-        }
-      }
+  const found = findCatalogItem(itemArg);
+  if (!found) {
+    v2.error(`"${itemArg}" not found in catalog.`);
+    const similar = listAllCatalogItems().filter(
+      (n) => n.includes(itemArg) || itemArg.includes(n.split("-")[0] ?? "")
+    );
+    if (similar.length > 0) {
+      process.stdout.write(`Did you mean: ${similar.slice(0, 5).join(", ")}?
+`);
     }
-  }
-  const allItems = listAllCatalogItems();
-  const similar = allItems.filter((n) => n.includes(itemArg) || itemArg.includes(n.split("-")[0] ?? ""));
-  v2.error(`"${itemArg}" not found in catalog.`);
-  if (similar.length > 0) {
-    process.stdout.write(`Did you mean: ${similar.slice(0, 5).join(", ")}?
+    process.stdout.write(`Run ${kleur_default.cyan("aikit list")} to see all available items.
 `);
+    process.exit(1);
+  }
+  if (existsSync7(found.destFile) && !argv.force) {
+    v2.warn(`${found.destFile} already exists. Use --force to overwrite.`);
+    return;
   }
-  process.stdout.write(`Run ${kleur_default.cyan("aikit list")} to see all available items.
+  if (!argv["dry-run"]) {
+    mkdirSync3(found.destDir, { recursive: true });
+    copyFileSync2(found.srcFile, found.destFile);
+  }
+  const dryPrefix = argv["dry-run"] ? "[dry-run] " : "";
+  process.stdout.write(`${dryPrefix}${kleur_default.green("\u2713")} Added ${found.destFile}
 `);
-  process.exit(1);
+  if (!argv["dry-run"]) {
+    const configChange = updateConfigForAddition(argv.config, found);
+    if (configChange) {
+      process.stdout.write(`  ${kleur_default.dim(configChange)}
+`);
+    }
+  }
+}
+function findCatalogItem(name) {
+  for (const tier of ["tier1", "tier2"]) {
+    const dir = join4(CATALOG_ROOT, "skills", tier);
+    if (existsSync7(dir)) {
+      const candidate = join4(dir, `${name}.md`);
+      if (existsSync7(candidate)) {
+        return {
+          type: "skill",
+          name,
+          srcFile: candidate,
+          destFile: join4(".claude/skills", `${name}.md`),
+          destDir: ".claude/skills"
+        };
+      }
+    }
+  }
+  for (const tier of ["tier1", "tier2"]) {
+    const dir = join4(CATALOG_ROOT, "agents", tier);
+    if (existsSync7(dir)) {
+      const candidate = join4(dir, `${name}.md`);
+      if (existsSync7(candidate)) {
+        return {
+          type: "agent",
+          name,
+          srcFile: candidate,
+          destFile: join4(".claude/agents", `${name}.md`),
+          destDir: ".claude/agents"
+        };
+      }
+    }
+  }
+  for (const type of ["hook"]) {
+    const spec = ITEM_DIRS[type];
+    const catalogDir = join4(CATALOG_ROOT, spec.catalog);
+    if (!existsSync7(catalogDir)) continue;
+    for (const ext of spec.ext) {
+      const candidate = join4(catalogDir, `${name}${ext}`);
+      if (existsSync7(candidate)) {
+        return {
+          type,
+          name,
+          srcFile: candidate,
+          destFile: join4(spec.dest, `${name}${ext}`),
+          destDir: spec.dest
+        };
+      }
+    }
+  }
+  return null;
+}
+function updateConfigForAddition(configPath, item) {
+  const config = readConfig(configPath);
+  if (!config) return null;
+  let updated = null;
+  let message = "";
+  if (item.type === "agent") {
+    const shape = AGENT_TO_SHAPE[item.name];
+    if (shape && !config.shape.includes(shape)) {
+      updated = { ...config, shape: [...config.shape, shape] };
+      message = `Added "${shape}" to .aikitrc.json shape (so sync re-installs ${item.name})`;
+    }
+    const agentTier = detectAgentTier(item.name);
+    if (agentTier === "tier2" && !shape) {
+      const currentAgents = config.agents ?? { tier1: "all", tier2: "all", tier3: [] };
+      const tier2 = currentAgents.tier2;
+      if (tier2 !== "all" && !tier2.includes(item.name)) {
+        updated = {
+          ...updated ?? config,
+          agents: { ...currentAgents, tier2: [...tier2, item.name] }
+        };
+        message = `Added "${item.name}" to .aikitrc.json agents.tier2`;
+      }
+    }
+    if (agentTier === "tier3" && !(config.agents?.tier3 ?? []).includes(item.name)) {
+      const currentAgents = config.agents ?? { tier1: "all", tier2: "all", tier3: [] };
+      updated = {
+        ...updated ?? config,
+        agents: { ...currentAgents, tier3: [...currentAgents.tier3, item.name] }
+      };
+      message = `Added "${item.name}" to .aikitrc.json agents.tier3`;
+    }
+  } else if (item.type === "skill") {
+    const skillTier = detectSkillTier(item.name);
+    if (skillTier === "tier3" && !config.skills.tier3.includes(item.name)) {
+      updated = {
+        ...config,
+        skills: { ...config.skills, tier3: [...config.skills.tier3, item.name] }
+      };
+      message = `Added "${item.name}" to .aikitrc.json skills.tier3`;
+    }
+  } else if (item.type === "hook") {
+    if (!config.integrations.hooks) {
+      updated = {
+        ...config,
+        integrations: { ...config.integrations, hooks: true }
+      };
+      message = "Set integrations.hooks=true in .aikitrc.json";
+    }
+  }
+  if (updated) {
+    writeConfig(updated, configPath);
+    return message;
+  }
+  return null;
+}
+function detectSkillTier(name) {
+  for (const tier of ["tier1", "tier2"]) {
+    if (existsSync7(join4(CATALOG_ROOT, "skills", tier, `${name}.md`))) {
+      return tier;
+    }
+  }
+  return "tier3";
+}
+function detectAgentTier(name) {
+  for (const tier of ["tier1", "tier2"]) {
+    if (existsSync7(join4(CATALOG_ROOT, "agents", tier, `${name}.md`))) {
+      return tier;
+    }
+  }
+  return "tier3";
 }
 function listAllCatalogItems() {
   const items = [];
-  for (const subdir of ["skills/tier1", "skills/tier2", "agents", "hooks"]) {
-    const dir = join4(CATALOG_ROOT3, subdir);
-    if (existsSync6(dir)) {
+  for (const subdir of ["skills/tier1", "skills/tier2", "agents/tier1", "agents/tier2", "hooks"]) {
+    const dir = join4(CATALOG_ROOT, subdir);
+    if (existsSync7(dir)) {
       readdirSync3(dir).filter((f2) => f2.endsWith(".md") || f2.endsWith(".sh")).forEach((f2) => items.push(f2.replace(/\.(md|sh)$/, "")));
     }
   }
   return items;
 }
-var CATALOG_ROOT3, ITEM_DIRS;
+var ITEM_DIRS, AGENT_TO_SHAPE;
 var init_add = __esm({
   "src/commands/add.ts"() {
     "use strict";
     init_dist2();
     init_kleur();
-    CATALOG_ROOT3 = join4(dirname5(fileURLToPath4(import.meta.url)), "..", "catalog");
+    init_catalog();
+    init_readConfig();
     ITEM_DIRS = {
       skill: { catalog: "skills/tier1", dest: ".claude/skills", ext: [".md"] },
-      agent: { catalog: "agents", dest: ".claude/agents", ext: [".md"] },
+      agent: { catalog: "agents/tier1", dest: ".claude/agents", ext: [".md"] },
       hook: { catalog: "hooks", dest: ".claude/hooks", ext: [".sh"] }
     };
+    AGENT_TO_SHAPE = {
+      frontend: "web",
+      backend: "backend",
+      mobile: "mobile"
+    };
   }
 });
 
@@ -1744,16 +2289,17 @@ var list_exports = {};
 __export(list_exports, {
   runList: () => runList
 });
-import { existsSync as existsSync7, readdirSync as readdirSync4 } from "fs";
-import { dirname as dirname6, join as join5 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
+import { existsSync as existsSync8, readdirSync as readdirSync4 } from "fs";
+import { join as join5 } from "path";
 async function runList(_argv) {
   const sections = [
     { label: "Skills \u2014 Tier 1", items: listCategory("skills/tier1", ".claude/skills") },
     { label: "Skills \u2014 Tier 2", items: listCategory("skills/tier2", ".claude/skills") },
+    { label: "Agents \u2014 Tier 1", items: listCategory("agents/tier1", ".claude/agents") },
+    { label: "Agents \u2014 Tier 2", items: listCategory("agents/tier2", ".claude/agents") },
     { label: "Slash commands", items: listCategory("commands", ".claude/commands") },
-    { label: "Agents", items: listCategory("agents", ".claude/agents") },
-    { label: "Hooks", items: listCategory("hooks", ".claude/hooks", [".sh"]) }
+    { label: "Hooks", items: listCategory("hooks", ".claude/hooks", [".sh"]) },
+    { label: "Path-scoped rules", items: listClaudeRules() }
   ];
   let total = 0;
   let installed = 0;
@@ -1782,19 +2328,52 @@ ${installed}/${total} catalog items installed.
   }
 }
 function listCategory(catalogSubdir, installedDir, extensions = [".md"]) {
-  const catalogDir = join5(CATALOG_ROOT4, catalogSubdir);
-  if (!existsSync7(catalogDir)) return [];
+  const catalogDir = join5(CATALOG_ROOT, catalogSubdir);
+  if (!existsSync8(catalogDir)) return [];
   const installedFiles = new Set(
-    existsSync7(installedDir) ? readdirSync4(installedDir).filter((f2) => extensions.some((ext) => f2.endsWith(ext))) : []
+    existsSync8(installedDir) ? readdirSync4(installedDir).filter((f2) => extensions.some((ext) => f2.endsWith(ext))) : []
   );
-  return readdirSync4(catalogDir).filter((f2) => extensions.some((ext) => f2.endsWith(ext))).map((f2) => ({ name: f2.replace(/\.md$/, ""), installed: installedFiles.has(f2) }));
+  return readdirSync4(catalogDir).filter((f2) => extensions.some((ext) => f2.endsWith(ext))).map((f2) => ({
+    name: stripExtension(f2, extensions),
+    installed: installedFiles.has(f2)
+  }));
+}
+function listClaudeRules() {
+  const catalogDir = join5(CATALOG_ROOT, "rules", "claude-rules");
+  if (!existsSync8(catalogDir)) return [];
+  const installedDir = ".claude/rules";
+  const installedFiles = new Set(
+    existsSync8(installedDir) ? readdirSync4(installedDir).filter((f2) => f2.endsWith(".md")) : []
+  );
+  return readdirSync4(catalogDir).filter((f2) => f2.endsWith(".md")).map((f2) => ({ name: stripExtension(f2, [".md"]), installed: installedFiles.has(f2) }));
+}
+function stripExtension(filename, extensions) {
+  for (const ext of extensions) {
+    if (filename.endsWith(ext)) return filename.slice(0, -ext.length);
+  }
+  return filename;
 }
-var CATALOG_ROOT4;
 var init_list = __esm({
   "src/commands/list.ts"() {
     "use strict";
     init_kleur();
-    CATALOG_ROOT4 = join5(dirname6(fileURLToPath5(import.meta.url)), "..", "catalog");
+    init_catalog();
+  }
+});
+
+// src/render/rule-ids.ts
+function extractRuleIds(content) {
+  const ids = [];
+  for (const m3 of content.matchAll(RULE_ID_REGEX)) {
+    if (m3[1]) ids.push(m3[1]);
+  }
+  return ids;
+}
+var RULE_ID_REGEX;
+var init_rule_ids = __esm({
+  "src/render/rule-ids.ts"() {
+    "use strict";
+    RULE_ID_REGEX = /<!--\s*id:\s*([a-zA-Z][a-zA-Z0-9_-]*\.[a-zA-Z0-9._-]+)(?:\s+[a-zA-Z][a-zA-Z0-9_-]*=[^>\s]+)*\s*-->/g;
   }
 });
 
@@ -1803,9 +2382,13 @@ var doctor_exports = {};
 __export(doctor_exports, {
   runDoctor: () => runDoctor
 });
-import { existsSync as existsSync8, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "fs";
 import { join as join6 } from "path";
 async function runDoctor(argv) {
+  if (argv.rules) {
+    runRulesReport(argv.format === "json" ? "json" : "text");
+    return;
+  }
   const findings = [];
   const config = readConfig(argv.config);
   if (!config) {
@@ -1814,7 +2397,7 @@ async function runDoctor(argv) {
     return;
   }
   findings.push({ level: "ok", check: ".aikitrc.json", message: `version ${config.version}, scope: ${config.scope}` });
-  if (existsSync8("AGENTS.md")) {
+  if (existsSync9("AGENTS.md")) {
     const content = readFileSync7("AGENTS.md", "utf8");
     if (content.includes("<!-- BEGIN:haac-aikit -->")) {
       const lines = content.split("\n").length;
@@ -1840,14 +2423,14 @@ async function runDoctor(argv) {
   for (const tool of config.tools) {
     const file = toolChecks[tool];
     if (!file) continue;
-    if (existsSync8(file)) {
+    if (existsSync9(file)) {
       findings.push({ level: "ok", check: `${tool} shim`, message: file });
     } else {
       findings.push({ level: "warn", check: `${tool} shim`, message: `${file} missing \u2014 run \`aikit sync\`` });
     }
   }
   if (config.tools.includes("claude")) {
-    if (existsSync8(".claude/settings.json")) {
+    if (existsSync9(".claude/settings.json")) {
       findings.push({ level: "ok", check: "settings.json", message: ".claude/settings.json present" });
     } else {
       findings.push({ level: "warn", check: "settings.json", message: "Missing \u2014 run `aikit sync`" });
@@ -1855,7 +2438,7 @@ async function runDoctor(argv) {
   }
   if (config.scope !== "minimal") {
     const skillsDir2 = ".claude/skills";
-    if (existsSync8(skillsDir2)) {
+    if (existsSync9(skillsDir2)) {
       const count = readdirSync5(skillsDir2).filter((f2) => f2.endsWith(".md")).length;
       findings.push({ level: "ok", check: "skills", message: `${count} installed` });
     } else {
@@ -1863,7 +2446,7 @@ async function runDoctor(argv) {
     }
   }
   const skillsDir = ".claude/skills";
-  if (existsSync8(skillsDir)) {
+  if (existsSync9(skillsDir)) {
     const skills = readdirSync5(skillsDir).filter((f2) => f2.endsWith(".md"));
     let descErrors = 0;
     for (const skill of skills) {
@@ -1882,14 +2465,37 @@ async function runDoctor(argv) {
       findings.push({ level: "ok", check: "skill descriptions", message: "All within 600-char limit" });
     }
   }
+  if (config.tools.includes("claude") && config.scope !== "minimal") {
+    for (const path of [
+      ".claude/aikit-rules.json",
+      "docs/claude-md-reference.md",
+      ".claude/rules/example.md"
+    ]) {
+      if (existsSync9(path)) {
+        findings.push({ level: "ok", check: path, message: "present" });
+      } else {
+        findings.push({ level: "warn", check: path, message: "Missing \u2014 run `aikit sync`" });
+      }
+    }
+    if (config.integrations.hooks) {
+      for (const hook of ["log-rule-event.sh", "check-pattern-violations.sh", "judge-rule-compliance.sh"]) {
+        const path = `.claude/hooks/${hook}`;
+        if (existsSync9(path)) {
+          findings.push({ level: "ok", check: `telemetry:${hook}`, message: "installed" });
+        } else {
+          findings.push({ level: "warn", check: `telemetry:${hook}`, message: "Missing \u2014 run `aikit sync`" });
+        }
+      }
+    }
+  }
   if (config.integrations.hooks) {
-    if (existsSync8(".claude/hooks/hooks.json")) {
+    if (existsSync9(".claude/hooks/hooks.json")) {
       findings.push({ level: "ok", check: "hooks", message: "hooks.json present" });
     } else {
       findings.push({ level: "warn", check: "hooks", message: "hooks.json missing \u2014 run `aikit sync`" });
     }
   }
-  if (existsSync8(".gitignore")) {
+  if (existsSync9(".gitignore")) {
     const gi = readFileSync7(".gitignore", "utf8");
     if (gi.includes(".env")) {
       findings.push({ level: "ok", check: ".gitignore", message: ".env* entries present" });
@@ -1923,11 +2529,730 @@ function printFindings(findings) {
 `));
   }
 }
+function runRulesReport(format) {
+  const eventsPath = ".aikit/events.jsonl";
+  if (!existsSync9(eventsPath)) {
+    if (format === "json") {
+      process.stdout.write(
+        JSON.stringify({ status: "no_telemetry", message: ".aikit/events.jsonl not found" }, null, 2) + "\n"
+      );
+    } else {
+      process.stdout.write(
+        kleur_default.yellow("No telemetry yet. ") + "Hooks log to .aikit/events.jsonl on first session.\nRun a Claude Code session in this repo, then re-run `aikit doctor --rules`.\n"
+      );
+    }
+    return;
+  }
+  const { events, malformed } = parseEvents(readFileSync7(eventsPath, "utf8"));
+  if (events.length === 0) {
+    if (format === "json") {
+      process.stdout.write(JSON.stringify({ status: "empty_log", malformed }, null, 2) + "\n");
+    } else {
+      process.stdout.write(kleur_default.yellow("Telemetry log is empty. No rule events recorded yet.\n"));
+    }
+    return;
+  }
+  const known = collectKnownRuleIds();
+  const stats = aggregateStats(events, known);
+  const compileErrors = collectCompileErrors(events);
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(toRulesJson(stats, events.length, malformed, compileErrors), null, 2) + "\n");
+    return;
+  }
+  printRulesReport(stats, events.length, malformed, compileErrors);
+}
+function toRulesJson(stats, totalEvents, malformed, compileErrors) {
+  return {
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    total_events: totalEvents,
+    malformed_lines: malformed,
+    rules: [...stats.entries()].map(([id, s]) => {
+      const cls = classifyRule(s);
+      return {
+        id,
+        bucket: cls.bucket,
+        loaded: s.loadedCount,
+        cited: s.citedCount,
+        violations: s.violationCount,
+        judged_violations: s.judgedCount,
+        last_seen: s.lastSeen,
+        advice: cls.advice
+      };
+    }),
+    compile_errors: compileErrors.map((ce2) => ({
+      rule_id: ce2.ruleId,
+      pattern: ce2.pattern,
+      error: ce2.error,
+      ts: ce2.ts
+    }))
+  };
+}
+function collectCompileErrors(events) {
+  const latestByRule = /* @__PURE__ */ new Map();
+  for (const e2 of events) {
+    if (e2.event !== "rule_compile_error") continue;
+    const existing = latestByRule.get(e2.rule_id);
+    if (!existing || e2.ts > existing.ts) {
+      latestByRule.set(e2.rule_id, {
+        ruleId: e2.rule_id,
+        pattern: e2.pattern ?? "",
+        error: e2.error ?? "(no detail)",
+        ts: e2.ts
+      });
+    }
+  }
+  return [...latestByRule.values()];
+}
+function parseEvents(content) {
+  const out = [];
+  let malformed = 0;
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed.rule_id && parsed.event) out.push(parsed);
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { events: out, malformed };
+}
+function collectKnownRuleIds() {
+  const ids = /* @__PURE__ */ new Set();
+  const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];
+  if (existsSync9(".claude/rules")) {
+    for (const f2 of readdirSync5(".claude/rules")) {
+      if (f2.endsWith(".md")) candidates.push(join6(".claude/rules", f2));
+    }
+  }
+  for (const path of candidates) {
+    if (!existsSync9(path)) continue;
+    for (const id of extractRuleIds(readFileSync7(path, "utf8"))) ids.add(id);
+  }
+  return ids;
+}
+function aggregateStats(events, known) {
+  const stats = /* @__PURE__ */ new Map();
+  const seenIds = /* @__PURE__ */ new Set([...known]);
+  for (const e2 of events) {
+    seenIds.add(e2.rule_id);
+    let s = stats.get(e2.rule_id);
+    if (!s) {
+      s = { loadedCount: 0, violationCount: 0, citedCount: 0, judgedCount: 0, lastSeen: e2.ts, firstSeen: e2.ts, sources: /* @__PURE__ */ new Set() };
+      stats.set(e2.rule_id, s);
+    }
+    if (e2.event === "loaded") s.loadedCount++;
+    else if (e2.event === "violation") s.violationCount++;
+    else if (e2.event === "cited") s.citedCount++;
+    else if (e2.event === "judged_violation") s.judgedCount++;
+    if (e2.source) s.sources.add(e2.source);
+    if (e2.file) s.sources.add(e2.file);
+    if (e2.ts > s.lastSeen) s.lastSeen = e2.ts;
+    if (e2.ts < s.firstSeen) s.firstSeen = e2.ts;
+  }
+  for (const id of seenIds) {
+    if (!stats.has(id)) {
+      stats.set(id, {
+        loadedCount: 0,
+        violationCount: 0,
+        citedCount: 0,
+        judgedCount: 0,
+        lastSeen: "",
+        firstSeen: "",
+        sources: /* @__PURE__ */ new Set()
+      });
+    }
+  }
+  return stats;
+}
+function classifyRule(s) {
+  const negative = s.violationCount + s.judgedCount;
+  const interactions = s.loadedCount + s.citedCount + negative;
+  if (interactions === 0) {
+    return { bucket: "dead", advice: "Never loaded, cited, or violated \u2014 consider removing or rephrasing." };
+  }
+  if (s.loadedCount === 0 && s.citedCount === 0) {
+    return { bucket: "unused", advice: "Pattern violations recorded but rule not loaded \u2014 check rule file presence." };
+  }
+  if (negative > 0) {
+    const denominator = s.citedCount > 0 ? s.citedCount + negative : Math.max(s.loadedCount, 1);
+    const ratio = negative / denominator;
+    if (ratio > 0.3) {
+      return { bucket: "disputed", advice: "Frequently violated \u2014 strengthen with IMPORTANT/YOU MUST or move to a hook." };
+    }
+    return { bucket: "hot", advice: "Active rule with occasional violations \u2014 keep monitoring." };
+  }
+  return { bucket: "hot", advice: "Loaded and obeyed \u2014 keep." };
+}
+function printRulesReport(stats, totalEvents, malformed, compileErrors) {
+  const rows = [];
+  for (const [id, s] of stats) {
+    const cls = classifyRule(s);
+    rows.push({ id, stats: s, bucket: cls.bucket, advice: cls.advice });
+  }
+  const hot = rows.filter((r2) => r2.bucket === "hot");
+  const disputed = rows.filter((r2) => r2.bucket === "disputed");
+  const dead = rows.filter((r2) => r2.bucket === "dead");
+  const unused = rows.filter((r2) => r2.bucket === "unused");
+  process.stdout.write(kleur_default.bold("Rule observability \u2014 ") + kleur_default.dim(`${totalEvents} events across ${rows.length} rules`) + "\n\n");
+  if (hot.length > 0) {
+    process.stdout.write(kleur_default.green("\u2713 Hot rules (working as intended)\n"));
+    for (const r2 of hot) {
+      const v3 = r2.stats.violationCount > 0 ? kleur_default.yellow(` ${r2.stats.violationCount} violations`) : "";
+      process.stdout.write(`  ${kleur_default.bold(r2.id)} \u2014 ${r2.stats.loadedCount} loads${v3}
+`);
+    }
+    process.stdout.write("\n");
+  }
+  if (disputed.length > 0) {
+    process.stdout.write(kleur_default.yellow("\u26A0 Disputed rules (>30% violation rate)\n"));
+    for (const r2 of disputed) {
+      process.stdout.write(`  ${kleur_default.bold(r2.id)} \u2014 ${r2.stats.loadedCount} loads, ${r2.stats.violationCount} violations
+`);
+      process.stdout.write(`    ${kleur_default.dim(r2.advice)}
+`);
+    }
+    process.stdout.write("\n");
+  }
+  if (dead.length > 0) {
+    process.stdout.write(kleur_default.red("\u2717 Dead rules (never observed)\n"));
+    for (const r2 of dead) {
+      process.stdout.write(`  ${kleur_default.bold(r2.id)}
+`);
+      process.stdout.write(`    ${kleur_default.dim(r2.advice)}
+`);
+    }
+    process.stdout.write("\n");
+  }
+  if (unused.length > 0) {
+    process.stdout.write(kleur_default.yellow("\u26A0 Pattern hits without rule load\n"));
+    for (const r2 of unused) {
+      process.stdout.write(`  ${kleur_default.bold(r2.id)} \u2014 ${r2.stats.violationCount} pattern hits
+`);
+      process.stdout.write(`    ${kleur_default.dim(r2.advice)}
+`);
+    }
+    process.stdout.write("\n");
+  }
+  process.stdout.write(kleur_default.dim(`Hot: ${hot.length}  \xB7  Disputed: ${disputed.length}  \xB7  Dead: ${dead.length}  \xB7  Unmatched: ${unused.length}
+`));
+  if (compileErrors.length > 0) {
+    process.stdout.write(kleur_default.red(`
+\u2717 Rule pattern compile errors (${compileErrors.length})
+`));
+    for (const ce2 of compileErrors) {
+      process.stdout.write(`  ${kleur_default.bold(ce2.ruleId)} \u2014 ${kleur_default.dim(ce2.error)}
+`);
+      if (ce2.pattern) process.stdout.write(`    pattern: ${kleur_default.dim(ce2.pattern)}
+`);
+    }
+    process.stdout.write(kleur_default.dim("  Fix these regex patterns in .claude/aikit-rules.json.\n"));
+  }
+  if (malformed > 0) {
+    process.stdout.write(
+      kleur_default.yellow(`
+\u26A0  ${malformed} malformed line(s) in .aikit/events.jsonl were skipped.
+`) + kleur_default.dim("   This usually means a hook crashed mid-write. Adherence numbers reflect only the parsed lines.\n")
+    );
+  }
+}
 var init_doctor = __esm({
   "src/commands/doctor.ts"() {
     "use strict";
     init_kleur();
     init_readConfig();
+    init_rule_ids();
+  }
+});
+
+// src/commands/report.ts
+var report_exports = {};
+__export(report_exports, {
+  runReport: () => runReport
+});
+import { existsSync as existsSync10, readFileSync as readFileSync8, readdirSync as readdirSync6 } from "fs";
+import { join as join7 } from "path";
+async function runReport(argv) {
+  const format = argv.format ?? "markdown";
+  if (!existsSync10(EVENTS_PATH)) {
+    process.stdout.write(noTelemetryReport(format));
+    return;
+  }
+  const { events, malformed } = parseEvents2(readFileSync8(EVENTS_PATH, "utf8"));
+  if (events.length === 0) {
+    process.stdout.write(noTelemetryReport(format));
+    return;
+  }
+  const since = argv.since ? new Date(argv.since).toISOString() : null;
+  const filtered = since ? events.filter((e2) => e2.ts >= since) : events;
+  const known = collectKnownRuleIds2();
+  const stats = aggregate(filtered, known);
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(toJsonReport(stats, filtered.length, since, malformed), null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(toMarkdownReport(stats, filtered.length, since, malformed));
+}
+function parseEvents2(content) {
+  const out = [];
+  let malformed = 0;
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed.rule_id && parsed.event) out.push(parsed);
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { events: out, malformed };
+}
+function collectKnownRuleIds2() {
+  const ids = /* @__PURE__ */ new Set();
+  const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];
+  if (existsSync10(".claude/rules")) {
+    for (const f2 of readdirSync6(".claude/rules")) {
+      if (f2.endsWith(".md")) candidates.push(join7(".claude/rules", f2));
+    }
+  }
+  for (const path of candidates) {
+    if (!existsSync10(path)) continue;
+    for (const id of extractRuleIds(readFileSync8(path, "utf8"))) ids.add(id);
+  }
+  return ids;
+}
+function aggregate(events, known) {
+  const stats = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set([...known]);
+  for (const e2 of events) {
+    seen.add(e2.rule_id);
+    let s = stats.get(e2.rule_id);
+    if (!s) {
+      s = { loaded: 0, cited: 0, violations: 0, judged: 0, files: /* @__PURE__ */ new Set(), lastSeen: e2.ts };
+      stats.set(e2.rule_id, s);
+    }
+    if (e2.event === "loaded") s.loaded++;
+    else if (e2.event === "cited") s.cited++;
+    else if (e2.event === "violation") s.violations++;
+    else if (e2.event === "judged_violation") s.judged++;
+    if (e2.file) s.files.add(e2.file);
+    if (e2.ts > s.lastSeen) s.lastSeen = e2.ts;
+  }
+  for (const id of seen) {
+    if (!stats.has(id)) {
+      stats.set(id, { loaded: 0, cited: 0, violations: 0, judged: 0, files: /* @__PURE__ */ new Set(), lastSeen: "" });
+    }
+  }
+  return stats;
+}
+function adherence(stats) {
+  let observed = 0;
+  let followed = 0;
+  let totalCited = 0;
+  for (const s of stats.values()) {
+    const negative = s.violations + s.judged;
+    const positive = s.cited;
+    totalCited += positive;
+    if (positive + negative === 0) continue;
+    observed++;
+    followed += positive / (positive + negative);
+  }
+  if (totalCited === 0) {
+    return { score: null, observed: 0, basis: "no-evidence" };
+  }
+  return { score: Math.round(followed / observed * 100), observed, basis: "judge" };
+}
+function noTelemetryReport(format) {
+  if (format === "json") {
+    return JSON.stringify({ status: "no_telemetry", message: "No .aikit/events.jsonl found yet." }, null, 2) + "\n";
+  }
+  return [
+    "## Rule Observability",
+    "",
+    "_No telemetry yet. Run a Claude Code session in this repo, then re-run the report._",
+    ""
+  ].join("\n");
+}
+function toJsonReport(stats, totalEvents, since, malformedLines) {
+  const { score, observed, basis } = adherence(stats);
+  return {
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    since,
+    total_events: totalEvents,
+    malformed_lines: malformedLines,
+    rule_count: stats.size,
+    observed_rules: observed,
+    adherence_score: score,
+    adherence_basis: basis,
+    rules: [...stats.entries()].map(([id, s]) => ({
+      id,
+      loaded: s.loaded,
+      cited: s.cited,
+      violations: s.violations,
+      judged_violations: s.judged,
+      files: [...s.files],
+      last_seen: s.lastSeen
+    }))
+  };
+}
+function toMarkdownReport(stats, totalEvents, since, malformedLines) {
+  const { score, observed, basis } = adherence(stats);
+  const rows = [...stats.entries()].sort(([, a2], [, b2]) => b2.loaded + b2.violations - (a2.loaded + a2.violations));
+  const hot = rows.filter(([, s]) => s.loaded > 0 && s.violations + s.judged === 0);
+  const disputed = rows.filter(
+    ([, s]) => (s.loaded > 0 || s.cited > 0) && s.violations + s.judged > 0
+  );
+  const unmatched = rows.filter(
+    ([, s]) => s.loaded === 0 && s.cited === 0 && s.violations + s.judged > 0
+  );
+  const dead = rows.filter(([, s]) => s.loaded === 0 && s.cited === 0 && s.violations === 0 && s.judged === 0);
+  const out = [];
+  out.push("## \u{1F52D} Rule Observability");
+  out.push("");
+  if (since) out.push(`_Since: \`${since}\`_`);
+  if (basis === "judge" && score !== null) {
+    out.push(`_Adherence: **${score}%** across ${observed} judge-observed rules \xB7 ${totalEvents} events recorded_`);
+  } else {
+    out.push(`_Adherence: **N/A** \u2014 enable \`AIKIT_JUDGE=1\` for compliance scoring \xB7 ${totalEvents} events recorded_`);
+  }
+  out.push("");
+  if (disputed.length > 0) {
+    out.push("### \u26A0\uFE0F Rules under pressure");
+    out.push("_Declared rules with violations \u2014 strengthen wording or move to a hook._");
+    out.push("");
+    out.push("| Rule | Loads | Cited | Pattern violations | Judged violations |");
+    out.push("|---|---:|---:|---:|---:|");
+    for (const [id, s] of disputed) {
+      out.push(`| \`${id}\` | ${s.loaded} | ${s.cited} | ${s.violations} | ${s.judged} |`);
+    }
+    out.push("");
+  }
+  if (unmatched.length > 0) {
+    out.push("### \u{1F7E1} Pattern hits without a declared rule");
+    out.push(
+      "_Pattern matched in `aikit-rules.json` but no rule with this ID is in your AGENTS.md / `.claude/rules/`. Either declare the rule or remove the pattern config._"
+    );
+    out.push("");
+    out.push("| Rule ID | Pattern hits |");
+    out.push("|---|---:|");
+    for (const [id, s] of unmatched) {
+      out.push(`| \`${id}\` | ${s.violations + s.judged} |`);
+    }
+    out.push("");
+  }
+  if (hot.length > 0) {
+    out.push("### \u2705 Hot rules (loaded, no violations)");
+    out.push("");
+    for (const [id, s] of hot) {
+      out.push(`- \`${id}\` \u2014 ${s.loaded} loads`);
+    }
+    out.push("");
+  }
+  if (dead.length > 0) {
+    out.push("### \u{1F480} Dead rules (declared but never observed)");
+    out.push("");
+    for (const [id] of dead) {
+      out.push(`- \`${id}\` \u2014 consider removing or rephrasing`);
+    }
+    out.push("");
+  }
+  if (malformedLines > 0) {
+    out.push(`> \u26A0\uFE0F  ${malformedLines} malformed line(s) in \`.aikit/events.jsonl\` were skipped \u2014 adherence reflects only parsed events.`);
+    out.push("");
+  }
+  out.push("---");
+  out.push(`<sub>Generated by \`aikit report\` \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}</sub>`);
+  out.push("");
+  return out.join("\n");
+}
+var EVENTS_PATH;
+var init_report = __esm({
+  "src/commands/report.ts"() {
+    "use strict";
+    init_rule_ids();
+    EVENTS_PATH = ".aikit/events.jsonl";
+  }
+});
+
+// src/commands/learn.ts
+var learn_exports = {};
+__export(learn_exports, {
+  clusterCandidates: () => clusterCandidates,
+  idFromText: () => idFromText,
+  isTeachingComment: () => isTeachingComment,
+  runLearn: () => runLearn
+});
+import { execFile } from "child_process";
+import { promisify } from "util";
+async function runLearn(argv) {
+  const limit = Number(argv.limit ?? 30);
+  if (!Number.isFinite(limit) || limit <= 0) {
+    process.stderr.write("--limit must be a positive number\n");
+    process.exit(1);
+  }
+  if (!await ensureGh()) {
+    process.stderr.write(
+      kleur_default.red("aikit learn requires the GitHub CLI (`gh`) to be installed and authenticated.\n") + "Install: https://cli.github.com/  \xB7  Authenticate: `gh auth login`\n"
+    );
+    process.exit(1);
+  }
+  if (!await hasGitHubRemote()) {
+    process.stderr.write(
+      kleur_default.red("This repo has no GitHub remote. ") + "`aikit learn` mines PR review history via `gh`, which requires a GitHub-hosted repo.\nAdd a remote with `git remote add origin <url>` then re-run.\n"
+    );
+    process.exit(1);
+  }
+  process.stdout.write(kleur_default.dim(`Fetching last ${limit} merged PRs...
+`));
+  let prs;
+  try {
+    prs = await fetchMergedPRs(limit);
+  } catch (err) {
+    process.stderr.write(kleur_default.red(`Failed to list PRs via gh: ${ghErrorMessage(err)}
+`));
+    process.exit(1);
+  }
+  if (prs.length === 0) {
+    process.stdout.write(kleur_default.yellow("No merged PRs found in this repo.\n"));
+    return;
+  }
+  process.stdout.write(kleur_default.dim(`Pulling review comments from ${prs.length} PRs...
+`));
+  const comments = [];
+  let skipped = 0;
+  for (const pr of prs) {
+    const prComments = await fetchReviewComments(pr.number);
+    if (prComments === null) {
+      skipped++;
+      continue;
+    }
+    for (const c2 of prComments) comments.push({ body: c2, prNumber: pr.number });
+  }
+  if (skipped > 0) {
+    process.stdout.write(kleur_default.yellow(`  warn: ${skipped}/${prs.length} PRs skipped due to gh fetch errors
+`));
+  }
+  if (comments.length === 0) {
+    process.stdout.write(kleur_default.yellow("No review comments found across the scanned PRs.\n"));
+    return;
+  }
+  const teachingComments = comments.filter((c2) => isTeachingComment(c2.body));
+  process.stdout.write(
+    kleur_default.dim(`Found ${teachingComments.length} teaching comments out of ${comments.length} total.
+
+`)
+  );
+  const candidates = clusterCandidates(teachingComments);
+  printCandidates(candidates);
+}
+async function ensureGh() {
+  try {
+    await runCmd("gh", ["auth", "status"], { encoding: "utf8" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function hasGitHubRemote() {
+  try {
+    const { stdout } = await runCmd("git", ["remote", "-v"], { encoding: "utf8" });
+    return stdout.includes("github.com");
+  } catch {
+    return false;
+  }
+}
+function ghErrorMessage(err) {
+  const e2 = err;
+  const stderr = typeof e2?.stderr === "string" ? e2.stderr.trim() : "";
+  if (stderr) return stderr.split("\n")[0] ?? stderr;
+  if (typeof e2?.message === "string") return e2.message.split("\n")[0] ?? e2.message;
+  return String(err);
+}
+async function fetchMergedPRs(limit) {
+  const { stdout } = await runCmd(
+    "gh",
+    ["pr", "list", "--state", "merged", "--limit", String(limit), "--json", "number,title"],
+    { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 }
+  );
+  return JSON.parse(stdout);
+}
+async function fetchReviewComments(prNumber) {
+  try {
+    const { stdout } = await runCmd(
+      "gh",
+      ["pr", "view", String(prNumber), "--json", "reviews,comments"],
+      { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 }
+    );
+    const data = JSON.parse(stdout);
+    const out = [];
+    for (const r2 of data.reviews ?? []) if (r2.body) out.push(r2.body);
+    for (const c2 of data.comments ?? []) if (c2.body) out.push(c2.body);
+    return out;
+  } catch {
+    return null;
+  }
+}
+function isTeachingComment(body) {
+  if (body.length < 10 || body.length > 1500) return false;
+  return CORRECTION_PHRASES.some((rx) => rx.test(body));
+}
+function tokens(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9 ]+/g, " ").split(/\s+/).filter((t) => t.length > 2 && !STOPWORDS.has(t)).map(stem)
+  );
+}
+function stem(t) {
+  if (t.length < 5) return t;
+  if (t.endsWith("ies")) return t.slice(0, -3) + "y";
+  if (t.endsWith("ing")) return t.slice(0, -3);
+  if (t.endsWith("ed")) return t.slice(0, -2);
+  if (t.endsWith("es")) return t.slice(0, -2);
+  if (t.endsWith("s")) return t.slice(0, -1);
+  return t;
+}
+function jaccard(a2, b2) {
+  if (a2.size === 0 || b2.size === 0) return 0;
+  let intersect = 0;
+  for (const t of a2) if (b2.has(t)) intersect++;
+  return intersect / (a2.size + b2.size - intersect);
+}
+function clusterCandidates(comments) {
+  const clusters = [];
+  const SIMILARITY_THRESHOLD = 0.15;
+  for (const c2 of comments) {
+    const tk = tokens(c2.body);
+    if (tk.size < 2) continue;
+    let placed = false;
+    for (const cluster of clusters) {
+      if (jaccard(tk, cluster.seedTokens) >= SIMILARITY_THRESHOLD) {
+        cluster.comments.push(c2);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) clusters.push({ seedTokens: tk, comments: [c2] });
+  }
+  return clusters.filter((c2) => c2.comments.length >= 2).map((c2) => candidateFromCluster(c2.comments)).sort((a2, b2) => b2.evidenceCount - a2.evidenceCount);
+}
+function candidateFromCluster(comments) {
+  const exemplar = [...comments].map((c2) => c2.body.trim().split("\n").find((l2) => l2.trim().length > 10) ?? c2.body.trim()).sort((a2, b2) => a2.length - b2.length)[0] ?? comments[0]?.body ?? "";
+  const id = idFromText(exemplar);
+  return {
+    id,
+    text: exemplar.slice(0, 240),
+    evidenceCount: comments.length,
+    exemplar,
+    prs: [...new Set(comments.map((c2) => c2.prNumber))].sort((a2, b2) => a2 - b2)
+  };
+}
+function idFromText(text) {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").split("-").filter((t) => t.length > 2 && !STOPWORDS.has(t)).slice(0, 4).join("-");
+  return `learned.${slug || "unnamed"}`;
+}
+function printCandidates(candidates) {
+  if (candidates.length === 0) {
+    process.stdout.write(kleur_default.yellow("No repeated correction patterns found. Try increasing --limit.\n"));
+    return;
+  }
+  process.stdout.write(kleur_default.bold(`Proposed rule candidates (${candidates.length})
+`));
+  process.stdout.write(kleur_default.dim("Each candidate is backed by \u22652 PR review comments.\n\n"));
+  for (const c2 of candidates) {
+    const prList = c2.prs.slice(0, 5).map((n) => `#${n}`).join(", ");
+    const more = c2.prs.length > 5 ? `, +${c2.prs.length - 5} more` : "";
+    process.stdout.write(kleur_default.bold(`\u25B8 ${c2.id}
+`));
+    process.stdout.write(`  ${kleur_default.dim("evidence:")} ${c2.evidenceCount} comments across ${prList}${more}
+`);
+    process.stdout.write(`  ${kleur_default.dim("exemplar:")} ${truncate(c2.exemplar, 200)}
+
+`);
+  }
+  process.stdout.write(kleur_default.bold("Suggested AGENTS.md additions\n"));
+  process.stdout.write(kleur_default.dim("Copy the block below into AGENTS.md inside a <!-- BEGIN:learned --> ... <!-- END:learned --> region:\n\n"));
+  process.stdout.write("<!-- BEGIN:learned -->\n");
+  process.stdout.write("## Learned conventions\n");
+  for (const c2 of candidates) {
+    process.stdout.write(`- <!-- id: ${c2.id} --> ${truncate(c2.exemplar, 240)}
+`);
+  }
+  process.stdout.write("<!-- END:learned -->\n");
+}
+function truncate(s, n) {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > n ? `${flat.slice(0, n - 1)}\u2026` : flat;
+}
+var runCmd, CORRECTION_PHRASES, STOPWORDS;
+var init_learn = __esm({
+  "src/commands/learn.ts"() {
+    "use strict";
+    init_kleur();
+    runCmd = promisify(execFile);
+    CORRECTION_PHRASES = [
+      /\bwe (?:always|usually|never|don't|do not|prefer|tend to|should|shouldn't)\b/i,
+      /\b(?:please )?(?:always|never|don't|do not) [a-z]/i,
+      /\bactually,?\s+(?:we|let's|i'd)/i,
+      /\bshould (?:always |never |)be /i,
+      /\b(?:our )?convention is to\b/i,
+      /\bnit:?\s+/i,
+      /\b(?:can we|could we|would prefer)\b/i
+    ];
+    STOPWORDS = /* @__PURE__ */ new Set([
+      "the",
+      "a",
+      "an",
+      "and",
+      "or",
+      "but",
+      "if",
+      "is",
+      "are",
+      "was",
+      "were",
+      "be",
+      "been",
+      "being",
+      "to",
+      "of",
+      "in",
+      "on",
+      "at",
+      "by",
+      "for",
+      "with",
+      "from",
+      "this",
+      "that",
+      "these",
+      "those",
+      "it",
+      "its",
+      "we",
+      "you",
+      "i",
+      "my",
+      "your",
+      "our",
+      "their",
+      "as",
+      "so",
+      "do",
+      "does",
+      "did",
+      "have",
+      "has",
+      "had",
+      "can",
+      "could",
+      "would",
+      "should",
+      "will",
+      "may"
+    ]);
   }
 });
 
@@ -2052,7 +3377,7 @@ function isInteractive() {
 }
 
 // src/cli.ts
-var VERSION = "0.1.0";
+var VERSION = "0.7.1";
 var HELP = `
 haac-aikit \u2014 the batteries-included AI-agentic-coding kit
 
@@ -2061,13 +3386,16 @@ USAGE
   aikit [command] [flags]       (if installed globally)
 
 COMMANDS
-  (default)      Interactive wizard \u2014 drop a complete AI setup into this repo
-  sync           Regenerate per-tool files from .aikitrc.json (idempotent)
-  update         Pull latest templates; show diff; prompt before writing
-  diff           Show drift between current state and a fresh generation
-  add <item>     Add a single skill, command, agent, or hook
-  list           Show installed items + available catalog
-  doctor         Sanity-check: schema, triggers, broken links
+  (default)         Interactive wizard \u2014 drop a complete AI setup into this repo
+  sync              Regenerate per-tool files from .aikitrc.json (idempotent)
+  update            Pull latest templates; show diff; prompt before writing
+  diff              Show drift between current state and a fresh generation
+  add <item>        Add a single skill, command, agent, or hook
+  list              Show installed items + available catalog
+  doctor            Sanity-check: schema, triggers, broken links
+  doctor --rules    Rule observability report \u2014 which rules fire, are followed, are dead
+  report            Markdown / JSON rule-adherence summary (for PR comments / CI)
+  learn             Mine recent PR review comments for repeated corrections; propose rules
 
 FLAGS
   --yes, -y           Accept all defaults
@@ -2078,13 +3406,17 @@ FLAGS
   --config=<path>     Use a specific .aikitrc.json location
   --tools=<list>      Comma-separated tool list (claude,cursor,copilot,...)
   --preset=<scope>    minimal | standard | everything
+  --rules             (with doctor)  Show rule-observability buckets
+  --format=<fmt>      (with report / doctor --rules)  markdown | json
+  --since=<date>      (with report)  Restrict events to after this ISO date
+  --limit=<n>         (with learn)   How many merged PRs to scan (default 30)
   --help, -h          Show this help
   --version, -v       Show version
 `;
 async function main() {
   const argv = lib_default(process.argv.slice(2), {
-    boolean: ["yes", "dry-run", "force", "skip-git-check", "no-color", "help", "version"],
-    string: ["config", "tools", "preset"],
+    boolean: ["yes", "dry-run", "force", "skip-git-check", "no-color", "help", "version", "rules"],
+    string: ["config", "tools", "preset", "format", "since", "limit"],
     alias: { y: "yes", h: "help", v: "version" },
     default: {
       yes: false,
@@ -2093,7 +3425,8 @@ async function main() {
       "skip-git-check": false,
       "no-color": false,
       help: false,
-      version: false
+      version: false,
+      rules: false
     }
   });
   if (argv.version) {
@@ -2125,7 +3458,7 @@ async function main() {
       break;
     }
     case "diff": {
-      const { runDiff: runDiff2 } = await Promise.resolve().then(() => (init_diff(), diff_exports));
+      const { runDiff: runDiff2 } = await Promise.resolve().then(() => (init_diff2(), diff_exports));
       await runDiff2(argv);
       break;
     }
@@ -2144,6 +3477,16 @@ async function main() {
       await runDoctor2(argv);
       break;
     }
+    case "report": {
+      const { runReport: runReport2 } = await Promise.resolve().then(() => (init_report(), report_exports));
+      await runReport2(argv);
+      break;
+    }
+    case "learn": {
+      const { runLearn: runLearn2 } = await Promise.resolve().then(() => (init_learn(), learn_exports));
+      await runLearn2(argv);
+      break;
+    }
     default:
       process.stderr.write(`Unknown command: ${command}
 Run --help for usage.