kairn-cli 1.3.0 → 1.5.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 // src/cli.ts
-import { Command as Command7 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/commands/init.ts
 import { Command } from "commander";
@@ -8,6 +8,9 @@ import chalk from "chalk";
 import Anthropic from "@anthropic-ai/sdk";
 import OpenAI from "openai";
 import { execFileSync } from "child_process";
+import fs2 from "fs/promises";
+import path2 from "path";
+import { fileURLToPath } from "url";
 
 // src/config.ts
 import fs from "fs/promises";
@@ -16,15 +19,24 @@ import os from "os";
 var KAIRN_DIR = path.join(os.homedir(), ".kairn");
 var CONFIG_PATH = path.join(KAIRN_DIR, "config.json");
 var ENVS_DIR = path.join(KAIRN_DIR, "envs");
+var TEMPLATES_DIR = path.join(KAIRN_DIR, "templates");
+var USER_REGISTRY_PATH = path.join(KAIRN_DIR, "user-registry.json");
 function getConfigPath() {
   return CONFIG_PATH;
 }
 function getEnvsDir() {
   return ENVS_DIR;
 }
+function getTemplatesDir() {
+  return TEMPLATES_DIR;
+}
+function getUserRegistryPath() {
+  return USER_REGISTRY_PATH;
+}
 async function ensureDirs() {
   await fs.mkdir(KAIRN_DIR, { recursive: true });
   await fs.mkdir(ENVS_DIR, { recursive: true });
+  await fs.mkdir(TEMPLATES_DIR, { recursive: true });
 }
 async function loadConfig() {
   try {
@@ -50,6 +62,42 @@ async function saveConfig(config) {
 }
 
 // src/commands/init.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path2.dirname(__filename);
+async function installSeedTemplates() {
+  const templatesDir = getTemplatesDir();
+  await fs2.mkdir(templatesDir, { recursive: true });
+  const candidates = [
+    path2.resolve(__dirname, "../registry/templates"),
+    path2.resolve(__dirname, "../src/registry/templates"),
+    path2.resolve(__dirname, "../../src/registry/templates")
+  ];
+  let seedDir = null;
+  for (const candidate of candidates) {
+    try {
+      await fs2.access(candidate);
+      seedDir = candidate;
+      break;
+    } catch {
+      continue;
+    }
+  }
+  if (!seedDir) return;
+  const files = (await fs2.readdir(seedDir)).filter((f) => f.endsWith(".json"));
+  let installed = 0;
+  for (const file of files) {
+    const dest = path2.join(templatesDir, file);
+    try {
+      await fs2.access(dest);
+    } catch {
+      await fs2.copyFile(path2.join(seedDir, file), dest);
+      installed++;
+    }
+  }
+  if (installed > 0) {
+    console.log(chalk.green(`  \u2713 ${installed} template${installed === 1 ? "" : "s"} installed`));
+  }
+}
 var PROVIDER_MODELS = {
   anthropic: {
     name: "Anthropic",
@@ -171,6 +219,7 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
   console.log(
     chalk.dim(`  \u2713 Provider: ${providerInfo.name}, Model: ${model}`)
   );
+  await installSeedTemplates();
   const hasClaude = detectClaudeCode();
   if (hasClaude) {
     console.log(chalk.green("  \u2713 Claude Code detected"));
@@ -190,13 +239,10 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
 import { Command as Command2 } from "commander";
 import { input, confirm } from "@inquirer/prompts";
 import chalk2 from "chalk";
-import fs4 from "fs/promises";
-import path4 from "path";
 
 // src/compiler/compile.ts
-import fs2 from "fs/promises";
-import path2 from "path";
-import { fileURLToPath } from "url";
+import fs4 from "fs/promises";
+import path4 from "path";
 import crypto from "crypto";
 import Anthropic2 from "@anthropic-ai/sdk";
 import OpenAI2 from "openai";
@@ -261,6 +307,7 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 9. settings.json with deny rules for \`rm -rf\`, \`curl|sh\`, reading \`.env\` and \`secrets/\`
 10. A \`/project:status\` command for code projects (uses ! for live git/test output)
 11. A \`/project:fix\` command for code projects (uses $ARGUMENTS for issue number)
+12. A \`docs/SPRINT.md\` file for sprint contracts (acceptance criteria, verification steps)
 
 ## Shell-Integrated Commands
 
@@ -349,6 +396,26 @@ Generate hooks in settings.json based on project type:
 
 Merge hooks into the \`settings\` object alongside permissions. Choose the formatter hook based on detected dependencies (Prettier \u2192 prettier, ESLint \u2192 eslint, Black \u2192 black).
 
+## PostCompact Hook
+
+All projects should include a PostCompact hook to restore context after compaction:
+
+\`\`\`json
+{
+  "hooks": {
+    "PostCompact": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "prompt",
+        "prompt": "Re-read CLAUDE.md and docs/SPRINT.md (if it exists) to restore project context after compaction."
+      }]
+    }]
+  }
+}
+\`\`\`
+
+Merge this into the settings hooks alongside the PreToolUse and PostToolUse hooks.
+
 ## Tool Selection Rules
 
 - Only select tools directly relevant to the described workflow
@@ -358,6 +425,19 @@ Merge hooks into the \`settings\` object alongside permissions. Choose the forma
 - Maximum 6-8 MCP servers to avoid context bloat
 - Include a \`reason\` for each selected tool explaining why it fits this workflow
 
+## Context Budget (STRICT)
+
+- MCP servers: maximum 6. Prefer fewer.
+- CLAUDE.md: maximum 100 lines.
+- Rules: maximum 5 files, each under 20 lines.
+- Skills: maximum 3. Only include directly relevant ones.
+- Agents: maximum 3. QA pipeline + one specialist.
+- Commands: no limit (loaded on demand, zero context cost).
+- Hooks: maximum 4 (auto-format, block-destructive, PostCompact, plus one contextual).
+
+If the workflow doesn't clearly need a tool, DO NOT include it.
+Each MCP server costs 500-2000 tokens of context window.
+
 ## For Code Projects, Additionally Include
 
 - \`/project:plan\` command (plan before coding)
@@ -366,12 +446,16 @@ Merge hooks into the \`settings\` object alongside permissions. Choose the forma
 - \`/project:commit\` command (conventional commits)
 - \`/project:status\` command (live git status, recent commits, TODO overview using ! prefix)
 - \`/project:fix\` command (takes $ARGUMENTS as issue number, plans fix, implements, tests, commits)
+- \`/project:sprint\` command (define acceptance criteria before coding, writes to docs/SPRINT.md)
 - A TDD skill using the 3-phase isolation pattern (RED \u2192 GREEN \u2192 REFACTOR):
   - RED: Write failing test only. Verify it FAILS.
   - GREEN: Write MINIMUM code to pass. Nothing extra.
   - REFACTOR: Improve while keeping tests green.
   Rules: never write tests and implementation in same step, AAA pattern, one assertion per test.
-- A reviewer agent (read-only, Sonnet model)
+- A multi-agent QA pipeline:
+  - \`@qa-orchestrator\` (sonnet) \u2014 delegates to linter and e2e-tester, compiles QA report
+  - \`@linter\` (haiku) \u2014 runs formatters, linters, security scanners
+  - \`@e2e-tester\` (sonnet, only when Playwright is in tools) \u2014 browser-based QA via Playwright
 
 ## For Research Projects, Additionally Include
 
@@ -386,6 +470,15 @@ Merge hooks into the \`settings\` object alongside permissions. Choose the forma
 - \`/project:edit\` command (review and improve writing)
 - A writing-workflow skill
 
+## Hermes Runtime
+
+When generating for Hermes runtime, the same EnvironmentSpec JSON is produced. The adapter layer handles conversion:
+- MCP config entries \u2192 Hermes config.yaml mcp_servers
+- Commands and skills \u2192 ~/.hermes/skills/ markdown files
+- Rules \u2192 ~/.hermes/skills/rule-*.md files
+
+The LLM output format does not change. Adapter-level conversion happens post-compilation.
+
 ## Output Schema
 
 Return ONLY valid JSON matching this structure:
@@ -412,7 +505,8 @@ Return ONLY valid JSON matching this structure:
       "help": "markdown content for /project:help",
       "tasks": "markdown content for /project:tasks",
       "status": "Show project status:\\n\\n!git status --short\\n\\n!git log --oneline -5\\n\\nRead TODO.md and summarize progress.",
-      "fix": "Fix issue #$ARGUMENTS:\\n\\n1. Read the issue and understand the problem\\n2. Plan the fix\\n3. Implement the fix\\n4. Run tests:\\n\\n!npm test 2>&1 | tail -20\\n\\n5. Commit with: fix: resolve #$ARGUMENTS"
+      "fix": "Fix issue #$ARGUMENTS:\\n\\n1. Read the issue and understand the problem\\n2. Plan the fix\\n3. Implement the fix\\n4. Run tests:\\n\\n!npm test 2>&1 | tail -20\\n\\n5. Commit with: fix: resolve #$ARGUMENTS",
+      "sprint": "Define a sprint contract for the next feature:\\n\\n1. Read docs/TODO.md for context:\\n\\n!cat docs/TODO.md 2>/dev/null\\n\\n2. Write a CONTRACT to docs/SPRINT.md with: feature name, acceptance criteria, verification steps, files to modify, scope estimate.\\n3. Do NOT start coding until contract is confirmed."
     },
     "rules": {
       "continuity": "markdown content for continuity rule",
@@ -422,12 +516,15 @@ Return ONLY valid JSON matching this structure:
       "skill-name/SKILL": "markdown content with YAML frontmatter"
     },
     "agents": {
-      "agent-name": "markdown content with YAML frontmatter"
+      "qa-orchestrator": "---\\nname: qa-orchestrator\\ndescription: Orchestrates QA pipeline\\nmodel: sonnet\\n---\\nRun QA: delegate to @linter for static analysis, @e2e-tester for browser tests. Compile consolidated report.",
+      "linter": "---\\nname: linter\\ndescription: Fast static analysis\\nmodel: haiku\\n---\\nRun available linters (eslint, prettier, biome, ruff, mypy, semgrep). Report issues.",
+      "e2e-tester": "---\\nname: e2e-tester\\ndescription: Browser-based QA via Playwright\\nmodel: sonnet\\n---\\nTest user flows via Playwright. Verify behavior, not just DOM. Screenshot failures."
     },
     "docs": {
       "TODO": "# TODO\\n\\n- [ ] First task based on workflow",
       "DECISIONS": "# Decisions\\n\\nArchitectural decisions for this project.",
-      "LEARNINGS": "# Learnings\\n\\nNon-obvious discoveries and gotchas."
+      "LEARNINGS": "# Learnings\\n\\nNon-obvious discoveries and gotchas.",
+      "SPRINT": "# Sprint Contract\\n\\nDefine acceptance criteria before starting work."
     }
   }
 }
@@ -435,18 +532,21 @@ Return ONLY valid JSON matching this structure:
 
 Do not include any text outside the JSON object. Do not wrap in markdown code fences.`;
 
-// src/compiler/compile.ts
-async function loadRegistry() {
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = path2.dirname(__filename);
+// src/registry/loader.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = path3.dirname(__filename2);
+async function loadBundledRegistry() {
   const candidates = [
-    path2.resolve(__dirname, "../registry/tools.json"),
-    path2.resolve(__dirname, "../src/registry/tools.json"),
-    path2.resolve(__dirname, "../../src/registry/tools.json")
+    path3.resolve(__dirname2, "../registry/tools.json"),
+    path3.resolve(__dirname2, "../src/registry/tools.json"),
+    path3.resolve(__dirname2, "../../src/registry/tools.json")
   ];
   for (const candidate of candidates) {
     try {
-      const data = await fs2.readFile(candidate, "utf-8");
+      const data = await fs3.readFile(candidate, "utf-8");
       return JSON.parse(data);
     } catch {
       continue;
@@ -454,6 +554,32 @@ async function loadRegistry() {
   }
   throw new Error("Could not find tools.json registry");
 }
+async function loadUserRegistry() {
+  try {
+    const data = await fs3.readFile(getUserRegistryPath(), "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return [];
+  }
+}
+async function saveUserRegistry(tools) {
+  await fs3.writeFile(getUserRegistryPath(), JSON.stringify(tools, null, 2), "utf-8");
+}
+async function loadRegistry() {
+  const bundled = await loadBundledRegistry();
+  const user = await loadUserRegistry();
+  if (user.length === 0) return bundled;
+  const merged = /* @__PURE__ */ new Map();
+  for (const tool of bundled) {
+    merged.set(tool.id, tool);
+  }
+  for (const tool of user) {
+    merged.set(tool.id, tool);
+  }
+  return Array.from(merged.values());
+}
+
+// src/compiler/compile.ts
 function buildUserMessage(intent, registry) {
   const registrySummary = registry.map(
     (t) => `- ${t.id} (${t.type}, tier ${t.tier}, auth: ${t.auth}): ${t.description} [best_for: ${t.best_for.join(", ")}]`
@@ -563,6 +689,24 @@ async function callLLM(config, userMessage) {
   }
   throw new Error(`Unsupported provider: ${config.provider}. Run \`kairn init\` to reconfigure.`);
 }
+function validateSpec(spec, onProgress) {
+  const warnings = [];
+  if (spec.tools.length > 8) {
+    warnings.push(`${spec.tools.length} MCP servers selected (recommended: \u22646)`);
+  }
+  if (spec.harness.claude_md) {
+    const lines = spec.harness.claude_md.split("\n").length;
+    if (lines > 150) {
+      warnings.push(`CLAUDE.md is ${lines} lines (recommended: \u2264100)`);
+    }
+  }
+  if (spec.harness.skills && Object.keys(spec.harness.skills).length > 5) {
+    warnings.push(`${Object.keys(spec.harness.skills).length} skills (recommended: \u22643)`);
+  }
+  for (const warning of warnings) {
+    onProgress?.(`\u26A0 ${warning}`);
+  }
+}
 async function compile(intent, onProgress) {
   const config = await loadConfig();
   if (!config) {
@@ -581,69 +725,114 @@ async function compile(intent, onProgress) {
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
     ...parsed
   };
+  validateSpec(spec, onProgress);
   await ensureDirs();
-  const envPath = path2.join(getEnvsDir(), `${spec.id}.json`);
-  await fs2.writeFile(envPath, JSON.stringify(spec, null, 2), "utf-8");
+  const envPath = path4.join(getEnvsDir(), `${spec.id}.json`);
+  await fs4.writeFile(envPath, JSON.stringify(spec, null, 2), "utf-8");
   return spec;
 }
 
 // src/adapter/claude-code.ts
-import fs3 from "fs/promises";
-import path3 from "path";
+import fs5 from "fs/promises";
+import path5 from "path";
 async function writeFile(filePath, content) {
-  await fs3.mkdir(path3.dirname(filePath), { recursive: true });
-  await fs3.writeFile(filePath, content, "utf-8");
+  await fs5.mkdir(path5.dirname(filePath), { recursive: true });
+  await fs5.writeFile(filePath, content, "utf-8");
+}
+function buildFileMap(spec) {
+  const files = /* @__PURE__ */ new Map();
+  if (spec.harness.claude_md) {
+    files.set(".claude/CLAUDE.md", spec.harness.claude_md);
+  }
+  if (spec.harness.settings && Object.keys(spec.harness.settings).length > 0) {
+    files.set(
+      ".claude/settings.json",
+      JSON.stringify(spec.harness.settings, null, 2)
+    );
+  }
+  if (spec.harness.mcp_config && Object.keys(spec.harness.mcp_config).length > 0) {
+    files.set(
+      ".mcp.json",
+      JSON.stringify({ mcpServers: spec.harness.mcp_config }, null, 2)
+    );
+  }
+  if (spec.harness.commands) {
+    for (const [name, content] of Object.entries(spec.harness.commands)) {
+      files.set(`.claude/commands/${name}.md`, content);
+    }
+  }
+  if (spec.harness.rules) {
+    for (const [name, content] of Object.entries(spec.harness.rules)) {
+      files.set(`.claude/rules/${name}.md`, content);
+    }
+  }
+  if (spec.harness.skills) {
+    for (const [skillPath, content] of Object.entries(spec.harness.skills)) {
+      files.set(`.claude/skills/${skillPath}.md`, content);
+    }
+  }
+  if (spec.harness.agents) {
+    for (const [name, content] of Object.entries(spec.harness.agents)) {
+      files.set(`.claude/agents/${name}.md`, content);
+    }
+  }
+  if (spec.harness.docs) {
+    for (const [name, content] of Object.entries(spec.harness.docs)) {
+      files.set(`.claude/docs/${name}.md`, content);
+    }
+  }
+  return files;
 }
 async function writeEnvironment(spec, targetDir) {
-  const claudeDir = path3.join(targetDir, ".claude");
+  const claudeDir = path5.join(targetDir, ".claude");
   const written = [];
   if (spec.harness.claude_md) {
-    const p = path3.join(claudeDir, "CLAUDE.md");
+    const p = path5.join(claudeDir, "CLAUDE.md");
     await writeFile(p, spec.harness.claude_md);
     written.push(".claude/CLAUDE.md");
   }
   if (spec.harness.settings && Object.keys(spec.harness.settings).length > 0) {
-    const p = path3.join(claudeDir, "settings.json");
+    const p = path5.join(claudeDir, "settings.json");
     await writeFile(p, JSON.stringify(spec.harness.settings, null, 2));
     written.push(".claude/settings.json");
   }
   if (spec.harness.mcp_config && Object.keys(spec.harness.mcp_config).length > 0) {
-    const p = path3.join(targetDir, ".mcp.json");
+    const p = path5.join(targetDir, ".mcp.json");
     const mcpContent = { mcpServers: spec.harness.mcp_config };
     await writeFile(p, JSON.stringify(mcpContent, null, 2));
     written.push(".mcp.json");
   }
   if (spec.harness.commands) {
     for (const [name, content] of Object.entries(spec.harness.commands)) {
-      const p = path3.join(claudeDir, "commands", `${name}.md`);
+      const p = path5.join(claudeDir, "commands", `${name}.md`);
       await writeFile(p, content);
       written.push(`.claude/commands/${name}.md`);
     }
   }
   if (spec.harness.rules) {
     for (const [name, content] of Object.entries(spec.harness.rules)) {
-      const p = path3.join(claudeDir, "rules", `${name}.md`);
+      const p = path5.join(claudeDir, "rules", `${name}.md`);
       await writeFile(p, content);
       written.push(`.claude/rules/${name}.md`);
     }
   }
   if (spec.harness.skills) {
     for (const [skillPath, content] of Object.entries(spec.harness.skills)) {
-      const p = path3.join(claudeDir, "skills", `${skillPath}.md`);
+      const p = path5.join(claudeDir, "skills", `${skillPath}.md`);
       await writeFile(p, content);
       written.push(`.claude/skills/${skillPath}.md`);
     }
   }
   if (spec.harness.agents) {
     for (const [name, content] of Object.entries(spec.harness.agents)) {
-      const p = path3.join(claudeDir, "agents", `${name}.md`);
+      const p = path5.join(claudeDir, "agents", `${name}.md`);
       await writeFile(p, content);
       written.push(`.claude/agents/${name}.md`);
     }
   }
   if (spec.harness.docs) {
     for (const [name, content] of Object.entries(spec.harness.docs)) {
-      const p = path3.join(claudeDir, "docs", `${name}.md`);
+      const p = path5.join(claudeDir, "docs", `${name}.md`);
       await writeFile(p, content);
       written.push(`.claude/docs/${name}.md`);
     }
@@ -681,27 +870,131 @@ function summarizeSpec(spec, registry) {
   };
 }
 
-// src/commands/describe.ts
-import { fileURLToPath as fileURLToPath2 } from "url";
-async function loadRegistry2() {
-  const __filename = fileURLToPath2(import.meta.url);
-  const __dirname = path4.dirname(__filename);
-  const candidates = [
-    path4.resolve(__dirname, "../registry/tools.json"),
-    path4.resolve(__dirname, "../src/registry/tools.json"),
-    path4.resolve(__dirname, "../../src/registry/tools.json")
-  ];
-  for (const candidate of candidates) {
-    try {
-      const data = await fs4.readFile(candidate, "utf-8");
-      return JSON.parse(data);
-    } catch {
-      continue;
+// src/adapter/hermes-agent.ts
+import fs6 from "fs/promises";
+import path6 from "path";
+import os2 from "os";
+async function writeFile2(filePath, content) {
+  await fs6.mkdir(path6.dirname(filePath), { recursive: true });
+  await fs6.writeFile(filePath, content, "utf-8");
+}
+function toYaml(obj, indent = 0) {
+  const pad = "  ".repeat(indent);
+  if (obj === null || obj === void 0) {
+    return "~";
+  }
+  if (typeof obj === "boolean") {
+    return obj ? "true" : "false";
+  }
+  if (typeof obj === "number") {
+    return String(obj);
+  }
+  if (typeof obj === "string") {
+    const needsQuotes = obj === "" || /[:#\[\]{}&*!|>'"%@`,]/.test(obj) || /^(true|false|null|~|\d)/.test(obj) || obj.includes("\n");
+    return needsQuotes ? `"${obj.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : obj;
+  }
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) {
+      return "[]";
     }
+    return obj.map((item) => `${pad}- ${toYaml(item, indent + 1).trimStart()}`).join("\n");
   }
-  throw new Error("Could not find tools.json registry");
+  if (typeof obj === "object") {
+    const entries = Object.entries(obj);
+    if (entries.length === 0) {
+      return "{}";
+    }
+    return entries.map(([key, value]) => {
+      const valueStr = toYaml(value, indent + 1);
+      const isScalar = typeof value !== "object" || value === null || Array.isArray(value);
+      if (isScalar && !Array.isArray(value)) {
+        return `${pad}${key}: ${valueStr}`;
+      }
+      if (Array.isArray(value)) {
+        if (value.length === 0) {
+          return `${pad}${key}: []`;
+        }
+        return `${pad}${key}:
+${valueStr}`;
+      }
+      return `${pad}${key}:
+${valueStr}`;
+    }).join("\n");
+  }
+  return String(obj);
 }
-var describeCommand = new Command2("describe").description("Describe your workflow and generate a Claude Code environment").argument("[intent]", "What you want your agent to do").option("-y, --yes", "Skip confirmation prompt").action(async (intentArg, options) => {
+function buildMcpServersYaml(spec, registry) {
+  const servers = {};
+  for (const selected of spec.tools) {
+    const tool = registry.find((t) => t.id === selected.tool_id);
+    if (!tool) continue;
+    if (tool.install.hermes?.mcp_server) {
+      const serverName = tool.id.replace(/_/g, "-");
+      servers[serverName] = tool.install.hermes.mcp_server;
+    } else if (tool.install.mcp_config) {
+      for (const [serverName, serverConfig] of Object.entries(
+        tool.install.mcp_config
+      )) {
+        servers[serverName] = serverConfig;
+      }
+    }
+  }
+  for (const [serverName, serverConfig] of Object.entries(
+    spec.harness.mcp_config || {}
+  )) {
+    if (!(serverName in servers)) {
+      servers[serverName] = serverConfig;
+    }
+  }
+  if (Object.keys(servers).length === 0) {
+    return "";
+  }
+  const lines = [];
+  lines.push(`# Generated by Kairn v1.5.0`);
+  lines.push(`# Environment: ${spec.name}`);
+  lines.push(``);
+  lines.push(`mcp_servers:`);
+  for (const [serverName, serverConfig] of Object.entries(servers)) {
+    lines.push(`  ${serverName}:`);
+    lines.push(toYaml(serverConfig, 2));
+  }
+  return lines.join("\n") + "\n";
+}
+async function writeHermesEnvironment(spec, registry) {
+  const hermesDir = path6.join(os2.homedir(), ".hermes");
+  const written = [];
+  const configYaml = buildMcpServersYaml(spec, registry);
+  if (configYaml) {
+    const configPath = path6.join(hermesDir, "config.yaml");
+    await writeFile2(configPath, configYaml);
+    written.push(".hermes/config.yaml");
+  }
+  if (spec.harness.commands) {
+    for (const [name, content] of Object.entries(spec.harness.commands)) {
+      const skillPath = path6.join(hermesDir, "skills", `${name}.md`);
+      await writeFile2(skillPath, content);
+      written.push(`.hermes/skills/${name}.md`);
+    }
+  }
+  if (spec.harness.skills) {
+    for (const [name, content] of Object.entries(spec.harness.skills)) {
+      const skillPath = path6.join(hermesDir, "skills", `${name}.md`);
+      await writeFile2(skillPath, content);
+      written.push(`.hermes/skills/${name}.md`);
+    }
+  }
+  if (spec.harness.rules) {
+    for (const [name, content] of Object.entries(spec.harness.rules)) {
+      const skillPath = path6.join(hermesDir, "skills", `rule-${name}.md`);
+      await writeFile2(skillPath, content);
+      written.push(`.hermes/skills/rule-${name}.md`);
+    }
+  }
+  return written;
+}
+
+// src/commands/describe.ts
+var describeCommand = new Command2("describe").description("Describe your workflow and generate a Claude Code environment").argument("[intent]", "What you want your agent to do").option("-y, --yes", "Skip confirmation prompt").option("--runtime <runtime>", "Target runtime (claude-code or hermes)", "claude-code").action(async (intentArg, options) => {
   const config = await loadConfig();
   if (!config) {
     console.log(
@@ -731,7 +1024,7 @@ var describeCommand = new Command2("describe").description("Describe your workfl
 `));
     process.exit(1);
   }
-  const registry = await loadRegistry2();
+  const registry = await loadRegistry();
   const summary = summarizeSpec(spec, registry);
   console.log(chalk2.green("\n  \u2713 Environment compiled\n"));
   console.log(chalk2.cyan("  Name: ") + spec.name);
@@ -765,46 +1058,53 @@ var describeCommand = new Command2("describe").description("Describe your workfl
     return;
   }
   const targetDir = process.cwd();
-  const written = await writeEnvironment(spec, targetDir);
-  console.log(chalk2.green("\n  \u2713 Environment written\n"));
-  for (const file of written) {
-    console.log(chalk2.dim(`    ${file}`));
-  }
-  if (summary.envSetup.length > 0) {
-    console.log(chalk2.yellow("\n  API keys needed (set these environment variables):\n"));
-    const seen = /* @__PURE__ */ new Set();
-    for (const env of summary.envSetup) {
-      if (seen.has(env.envVar)) continue;
-      seen.add(env.envVar);
-      console.log(chalk2.bold(`    export ${env.envVar}="your-key-here"`));
-      console.log(chalk2.dim(`      ${env.description}`));
-      if (env.signupUrl) {
-        console.log(chalk2.dim(`      Get one at: ${env.signupUrl}`));
+  const runtime = options.runtime ?? "claude-code";
+  if (runtime === "hermes") {
+    await writeHermesEnvironment(spec, registry);
+    console.log(chalk2.green("\n  \u2713 Environment written for Hermes\n"));
+    console.log(chalk2.cyan("\n  Ready! Run ") + chalk2.bold("hermes") + chalk2.cyan(" to start.\n"));
+  } else {
+    const written = await writeEnvironment(spec, targetDir);
+    console.log(chalk2.green("\n  \u2713 Environment written\n"));
+    for (const file of written) {
+      console.log(chalk2.dim(`    ${file}`));
+    }
+    if (summary.envSetup.length > 0) {
+      console.log(chalk2.yellow("\n  API keys needed (set these environment variables):\n"));
+      const seen = /* @__PURE__ */ new Set();
+      for (const env of summary.envSetup) {
+        if (seen.has(env.envVar)) continue;
+        seen.add(env.envVar);
+        console.log(chalk2.bold(`    export ${env.envVar}="your-key-here"`));
+        console.log(chalk2.dim(`      ${env.description}`));
+        if (env.signupUrl) {
+          console.log(chalk2.dim(`      Get one at: ${env.signupUrl}`));
+        }
+        console.log("");
       }
-      console.log("");
     }
-  }
-  if (summary.pluginCommands.length > 0) {
-    console.log(chalk2.yellow("  Install plugins by running these in Claude Code:"));
-    for (const cmd of summary.pluginCommands) {
-      console.log(chalk2.bold(`    ${cmd}`));
+    if (summary.pluginCommands.length > 0) {
+      console.log(chalk2.yellow("  Install plugins by running these in Claude Code:"));
+      for (const cmd of summary.pluginCommands) {
+        console.log(chalk2.bold(`    ${cmd}`));
+      }
     }
+    console.log(
+      chalk2.cyan("\n  Ready! Run ") + chalk2.bold("claude") + chalk2.cyan(" to start.\n")
+    );
   }
-  console.log(
-    chalk2.cyan("\n  Ready! Run ") + chalk2.bold("claude") + chalk2.cyan(" to start.\n")
-  );
 });
 
 // src/commands/list.ts
 import { Command as Command3 } from "commander";
 import chalk3 from "chalk";
-import fs5 from "fs/promises";
-import path5 from "path";
+import fs7 from "fs/promises";
+import path7 from "path";
 var listCommand = new Command3("list").description("Show saved environments").action(async () => {
   const envsDir = getEnvsDir();
   let files;
   try {
-    files = await fs5.readdir(envsDir);
+    files = await fs7.readdir(envsDir);
   } catch {
     console.log(chalk3.dim("\n  No environments yet. Run ") + chalk3.bold("kairn describe") + chalk3.dim(" to create one.\n"));
     return;
@@ -817,7 +1117,7 @@ var listCommand = new Command3("list").description("Show saved environments").ac
   console.log(chalk3.cyan("\n  Saved Environments\n"));
   for (const file of jsonFiles) {
     try {
-      const data = await fs5.readFile(path5.join(envsDir, file), "utf-8");
+      const data = await fs7.readFile(path7.join(envsDir, file), "utf-8");
       const spec = JSON.parse(data);
       const date = new Date(spec.created_at).toLocaleDateString();
       const toolCount = spec.tools?.length ?? 0;
@@ -835,30 +1135,49 @@ var listCommand = new Command3("list").description("Show saved environments").ac
 // src/commands/activate.ts
 import { Command as Command4 } from "commander";
 import chalk4 from "chalk";
-import fs6 from "fs/promises";
-import path6 from "path";
+import fs8 from "fs/promises";
+import path8 from "path";
 var activateCommand = new Command4("activate").description("Re-deploy a saved environment to the current directory").argument("<env_id>", "Environment ID (from kairn list)").action(async (envId) => {
   const envsDir = getEnvsDir();
-  let files;
+  const templatesDir = getTemplatesDir();
+  let sourceDir;
+  let match;
+  let fromTemplate = false;
+  let envFiles = [];
   try {
-    files = await fs6.readdir(envsDir);
+    envFiles = await fs8.readdir(envsDir);
   } catch {
-    console.log(chalk4.red("\n  No saved environments found.\n"));
-    process.exit(1);
   }
-  const match = files.find(
+  match = envFiles.find(
     (f) => f === `${envId}.json` || f.startsWith(envId)
   );
-  if (!match) {
-    console.log(chalk4.red(`
+  if (match) {
+    sourceDir = envsDir;
+  } else {
+    let templateFiles = [];
+    try {
+      templateFiles = await fs8.readdir(templatesDir);
+    } catch {
+    }
+    match = templateFiles.find(
+      (f) => f === `${envId}.json` || f.startsWith(envId)
+    );
+    if (match) {
+      sourceDir = templatesDir;
+      fromTemplate = true;
+    } else {
+      console.log(chalk4.red(`
   Environment "${envId}" not found.`));
-    console.log(chalk4.dim("  Run kairn list to see saved environments.\n"));
-    process.exit(1);
+      console.log(chalk4.dim("  Run kairn list to see saved environments."));
+      console.log(chalk4.dim("  Run kairn templates to see available templates.\n"));
+      process.exit(1);
+    }
   }
-  const data = await fs6.readFile(path6.join(envsDir, match), "utf-8");
+  const data = await fs8.readFile(path8.join(sourceDir, match), "utf-8");
   const spec = JSON.parse(data);
+  const label = fromTemplate ? chalk4.dim(" (template)") : "";
   console.log(chalk4.cyan(`
-  Activating: ${spec.name}`));
+  Activating: ${spec.name}`) + label);
   console.log(chalk4.dim(`  ${spec.description}
 `));
   const targetDir = process.cwd();
@@ -875,21 +1194,21 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
 // src/commands/update-registry.ts
 import { Command as Command5 } from "commander";
 import chalk5 from "chalk";
-import fs7 from "fs/promises";
-import path7 from "path";
+import fs9 from "fs/promises";
+import path9 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var REGISTRY_URL = "https://raw.githubusercontent.com/ashtonperlroth/kairn/main/src/registry/tools.json";
 async function getLocalRegistryPath() {
-  const __filename = fileURLToPath3(import.meta.url);
-  const __dirname = path7.dirname(__filename);
+  const __filename3 = fileURLToPath3(import.meta.url);
+  const __dirname3 = path9.dirname(__filename3);
   const candidates = [
-    path7.resolve(__dirname, "../registry/tools.json"),
-    path7.resolve(__dirname, "../src/registry/tools.json"),
-    path7.resolve(__dirname, "../../src/registry/tools.json")
+    path9.resolve(__dirname3, "../registry/tools.json"),
+    path9.resolve(__dirname3, "../src/registry/tools.json"),
+    path9.resolve(__dirname3, "../../src/registry/tools.json")
   ];
   for (const candidate of candidates) {
     try {
-      await fs7.access(candidate);
+      await fs9.access(candidate);
       return candidate;
     } catch {
       continue;
@@ -930,10 +1249,10 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
     const registryPath = await getLocalRegistryPath();
     const backupPath = registryPath + ".bak";
     try {
-      await fs7.copyFile(registryPath, backupPath);
+      await fs9.copyFile(registryPath, backupPath);
     } catch {
     }
-    await fs7.writeFile(registryPath, JSON.stringify(tools, null, 2), "utf-8");
+    await fs9.writeFile(registryPath, JSON.stringify(tools, null, 2), "utf-8");
     console.log(chalk5.green(`  \u2713 Registry updated: ${tools.length} tools`));
     console.log(chalk5.dim(`  Saved to: ${registryPath}`));
     console.log(chalk5.dim(`  Backup: ${backupPath}
@@ -949,16 +1268,15 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
 import { Command as Command6 } from "commander";
 import { confirm as confirm2 } from "@inquirer/prompts";
 import chalk6 from "chalk";
-import fs9 from "fs/promises";
-import path9 from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import fs11 from "fs/promises";
+import path11 from "path";
 
 // src/scanner/scan.ts
-import fs8 from "fs/promises";
-import path8 from "path";
+import fs10 from "fs/promises";
+import path10 from "path";
 async function fileExists(p) {
   try {
-    await fs8.access(p);
+    await fs10.access(p);
     return true;
   } catch {
     return false;
@@ -966,7 +1284,7 @@ async function fileExists(p) {
 }
 async function readJsonSafe(p) {
   try {
-    const data = await fs8.readFile(p, "utf-8");
+    const data = await fs10.readFile(p, "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
@@ -974,14 +1292,14 @@ async function readJsonSafe(p) {
 }
 async function readFileSafe(p) {
   try {
-    return await fs8.readFile(p, "utf-8");
+    return await fs10.readFile(p, "utf-8");
   } catch {
     return null;
   }
 }
 async function listDirSafe(p) {
   try {
-    const entries = await fs8.readdir(p);
+    const entries = await fs10.readdir(p);
     return entries.filter((e) => !e.startsWith("."));
   } catch {
     return [];
@@ -1033,7 +1351,7 @@ function extractEnvKeys(content) {
   return keys;
 }
 async function scanProject(dir) {
-  const pkg = await readJsonSafe(path8.join(dir, "package.json"));
+  const pkg = await readJsonSafe(path10.join(dir, "package.json"));
   const deps = pkg?.dependencies ? Object.keys(pkg.dependencies) : [];
   const devDeps = pkg?.devDependencies ? Object.keys(pkg.devDependencies) : [];
   const allDeps = [...deps, ...devDeps];
@@ -1061,19 +1379,19 @@ async function scanProject(dir) {
   const framework = detectFramework(allDeps);
   const typescript = keyFiles.includes("tsconfig.json") || allDeps.includes("typescript");
   const testCommand = scripts.test && scripts.test !== 'echo "Error: no test specified" && exit 1' ? scripts.test : null;
-  const hasTests = testCommand !== null || await fileExists(path8.join(dir, "tests")) || await fileExists(path8.join(dir, "__tests__")) || await fileExists(path8.join(dir, "test"));
+  const hasTests = testCommand !== null || await fileExists(path10.join(dir, "tests")) || await fileExists(path10.join(dir, "__tests__")) || await fileExists(path10.join(dir, "test"));
   const buildCommand = scripts.build || null;
   const lintCommand = scripts.lint || null;
-  const hasSrc = await fileExists(path8.join(dir, "src"));
-  const hasDocker = await fileExists(path8.join(dir, "docker-compose.yml")) || await fileExists(path8.join(dir, "Dockerfile"));
-  const hasCi = await fileExists(path8.join(dir, ".github/workflows"));
-  const hasEnvFile = await fileExists(path8.join(dir, ".env")) || await fileExists(path8.join(dir, ".env.example"));
+  const hasSrc = await fileExists(path10.join(dir, "src"));
+  const hasDocker = await fileExists(path10.join(dir, "docker-compose.yml")) || await fileExists(path10.join(dir, "Dockerfile"));
+  const hasCi = await fileExists(path10.join(dir, ".github/workflows"));
+  const hasEnvFile = await fileExists(path10.join(dir, ".env")) || await fileExists(path10.join(dir, ".env.example"));
   let envKeys = [];
-  const envExample = await readFileSafe(path8.join(dir, ".env.example"));
+  const envExample = await readFileSafe(path10.join(dir, ".env.example"));
   if (envExample) {
     envKeys = extractEnvKeys(envExample);
   }
-  const claudeDir = path8.join(dir, ".claude");
+  const claudeDir = path10.join(dir, ".claude");
   const hasClaudeDir = await fileExists(claudeDir);
   let existingClaudeMd = null;
   let existingSettings = null;
@@ -1085,21 +1403,21 @@ async function scanProject(dir) {
   let mcpServerCount = 0;
   let claudeMdLineCount = 0;
   if (hasClaudeDir) {
-    existingClaudeMd = await readFileSafe(path8.join(claudeDir, "CLAUDE.md"));
+    existingClaudeMd = await readFileSafe(path10.join(claudeDir, "CLAUDE.md"));
     if (existingClaudeMd) {
       claudeMdLineCount = existingClaudeMd.split("\n").length;
     }
-    existingSettings = await readJsonSafe(path8.join(claudeDir, "settings.json"));
-    existingMcpConfig = await readJsonSafe(path8.join(dir, ".mcp.json"));
+    existingSettings = await readJsonSafe(path10.join(claudeDir, "settings.json"));
+    existingMcpConfig = await readJsonSafe(path10.join(dir, ".mcp.json"));
     if (existingMcpConfig?.mcpServers) {
       mcpServerCount = Object.keys(existingMcpConfig.mcpServers).length;
     }
-    existingCommands = (await listDirSafe(path8.join(claudeDir, "commands"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
-    existingRules = (await listDirSafe(path8.join(claudeDir, "rules"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
-    existingSkills = await listDirSafe(path8.join(claudeDir, "skills"));
-    existingAgents = (await listDirSafe(path8.join(claudeDir, "agents"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingCommands = (await listDirSafe(path10.join(claudeDir, "commands"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingRules = (await listDirSafe(path10.join(claudeDir, "rules"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingSkills = await listDirSafe(path10.join(claudeDir, "skills"));
+    existingAgents = (await listDirSafe(path10.join(claudeDir, "agents"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
   }
-  const name = pkg?.name || path8.basename(dir);
+  const name = pkg?.name || path10.basename(dir);
   const description = pkg?.description || "";
   return {
     name,
@@ -1135,23 +1453,57 @@ async function scanProject(dir) {
 }
 
 // src/commands/optimize.ts
-async function loadRegistry3() {
-  const __filename = fileURLToPath4(import.meta.url);
-  const __dirname = path9.dirname(__filename);
-  const candidates = [
-    path9.resolve(__dirname, "../registry/tools.json"),
-    path9.resolve(__dirname, "../src/registry/tools.json"),
-    path9.resolve(__dirname, "../../src/registry/tools.json")
-  ];
-  for (const candidate of candidates) {
+function simpleDiff(oldContent, newContent) {
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+  const output = [];
+  const maxLines = Math.max(oldLines.length, newLines.length);
+  for (let i = 0; i < maxLines; i++) {
+    const oldLine = oldLines[i];
+    const newLine = newLines[i];
+    if (oldLine === void 0) {
+      output.push(chalk6.green(`+ ${newLine}`));
+    } else if (newLine === void 0) {
+      output.push(chalk6.red(`- ${oldLine}`));
+    } else if (oldLine !== newLine) {
+      output.push(chalk6.red(`- ${oldLine}`));
+      output.push(chalk6.green(`+ ${newLine}`));
+    }
+  }
+  return output;
+}
+async function generateDiff(spec, targetDir) {
+  const fileMap = buildFileMap(spec);
+  const results = [];
+  for (const [relativePath, newContent] of fileMap) {
+    const absolutePath = path11.join(targetDir, relativePath);
+    let oldContent = null;
     try {
-      const data = await fs9.readFile(candidate, "utf-8");
-      return JSON.parse(data);
+      oldContent = await fs11.readFile(absolutePath, "utf-8");
     } catch {
-      continue;
+    }
+    if (oldContent === null) {
+      results.push({
+        path: relativePath,
+        status: "new",
+        diff: chalk6.green("+ NEW FILE")
+      });
+    } else if (oldContent === newContent) {
+      results.push({
+        path: relativePath,
+        status: "unchanged",
+        diff: ""
+      });
+    } else {
+      const diffLines = simpleDiff(oldContent, newContent);
+      results.push({
+        path: relativePath,
+        status: "modified",
+        diff: diffLines.join("\n")
+      });
     }
   }
-  throw new Error("Could not find tools.json registry");
+  return results;
 }
 function buildProfileSummary(profile) {
   const lines = [];
@@ -1231,7 +1583,7 @@ ${profile.existingClaudeMd}`);
   }
   return parts.join("\n");
 }
-var optimizeCommand = new Command6("optimize").description("Scan an existing project and generate or optimize its Claude Code environment").option("-y, --yes", "Skip confirmation prompts").option("--audit-only", "Only audit the existing harness, don't generate changes").action(async (options) => {
+var optimizeCommand = new Command6("optimize").description("Scan an existing project and generate or optimize its Claude Code environment").option("-y, --yes", "Skip confirmation prompts").option("--audit-only", "Only audit the existing harness, don't generate changes").option("--diff", "Preview changes as a diff without writing").option("--runtime <runtime>", "Target runtime (claude-code or hermes)", "claude-code").action(async (options) => {
   const config = await loadConfig();
   if (!config) {
     console.log(
@@ -1322,7 +1674,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
 `));
     process.exit(1);
   }
-  const registry = await loadRegistry3();
+  const registry = await loadRegistry();
   const summary = summarizeSpec(spec, registry);
   console.log(chalk6.green("  \u2713 Environment compiled\n"));
   console.log(chalk6.cyan("  Name: ") + spec.name);
@@ -1345,46 +1697,511 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       console.log(chalk6.yellow(`    ${cmd}`));
     }
   }
-  const written = await writeEnvironment(spec, targetDir);
-  console.log(chalk6.green("\n  \u2713 Environment written\n"));
-  for (const file of written) {
-    console.log(chalk6.dim(`    ${file}`));
-  }
-  if (summary.envSetup.length > 0) {
-    console.log(chalk6.yellow("\n  API keys needed (set these environment variables):\n"));
-    const seen = /* @__PURE__ */ new Set();
-    for (const env of summary.envSetup) {
-      if (seen.has(env.envVar)) continue;
-      seen.add(env.envVar);
-      console.log(chalk6.bold(`    export ${env.envVar}="your-key-here"`));
-      console.log(chalk6.dim(`      ${env.description}`));
-      if (env.signupUrl) {
-        console.log(chalk6.dim(`      Get one at: ${env.signupUrl}`));
+  if (options.diff) {
+    const diffs = await generateDiff(spec, targetDir);
+    const changedDiffs = diffs.filter((d) => d.status !== "unchanged");
+    if (changedDiffs.length === 0) {
+      console.log(chalk6.green("\n  \u2713 No changes needed \u2014 environment is already up to date.\n"));
+      return;
+    }
+    console.log(chalk6.cyan("\n  Changes preview:\n"));
+    for (const d of changedDiffs) {
+      console.log(chalk6.cyan(`  --- ${d.path}`));
+      if (d.status === "new") {
+        console.log(`    ${d.diff}`);
+      } else {
+        for (const line of d.diff.split("\n")) {
+          console.log(`    ${line}`);
+        }
       }
       console.log("");
     }
+    const apply = await confirm2({
+      message: "Apply these changes?",
+      default: true
+    });
+    if (!apply) {
+      console.log(chalk6.dim("\n  Aborted.\n"));
+      return;
+    }
   }
-  if (summary.pluginCommands.length > 0) {
-    console.log(chalk6.yellow("  Install plugins by running these in Claude Code:"));
-    for (const cmd of summary.pluginCommands) {
-      console.log(chalk6.bold(`    ${cmd}`));
+  const runtime = options.runtime ?? "claude-code";
+  if (runtime === "hermes") {
+    await writeHermesEnvironment(spec, registry);
+    console.log(chalk6.green("\n  \u2713 Environment written for Hermes\n"));
+    console.log(chalk6.cyan("\n  Ready! Run ") + chalk6.bold("hermes") + chalk6.cyan(" to start.\n"));
+  } else {
+    const written = await writeEnvironment(spec, targetDir);
+    console.log(chalk6.green("\n  \u2713 Environment written\n"));
+    for (const file of written) {
+      console.log(chalk6.dim(`    ${file}`));
+    }
+    if (summary.envSetup.length > 0) {
+      console.log(chalk6.yellow("\n  API keys needed (set these environment variables):\n"));
+      const seen = /* @__PURE__ */ new Set();
+      for (const env of summary.envSetup) {
+        if (seen.has(env.envVar)) continue;
+        seen.add(env.envVar);
+        console.log(chalk6.bold(`    export ${env.envVar}="your-key-here"`));
+        console.log(chalk6.dim(`      ${env.description}`));
+        if (env.signupUrl) {
+          console.log(chalk6.dim(`      Get one at: ${env.signupUrl}`));
+        }
+        console.log("");
+      }
+    }
+    if (summary.pluginCommands.length > 0) {
+      console.log(chalk6.yellow("  Install plugins by running these in Claude Code:"));
+      for (const cmd of summary.pluginCommands) {
+        console.log(chalk6.bold(`    ${cmd}`));
+      }
+    }
+    console.log(
+      chalk6.cyan("\n  Ready! Run ") + chalk6.bold("claude") + chalk6.cyan(" to start.\n")
+    );
+  }
+});
+
+// src/commands/doctor.ts
+import { Command as Command7 } from "commander";
+import chalk7 from "chalk";
+function runChecks(profile) {
+  const checks = [];
+  if (!profile.existingClaudeMd) {
+    checks.push({
+      name: "CLAUDE.md",
+      weight: 3,
+      status: "fail",
+      message: "Missing CLAUDE.md"
+    });
+  } else if (profile.claudeMdLineCount > 200) {
+    checks.push({
+      name: "CLAUDE.md",
+      weight: 2,
+      status: "warn",
+      message: `${profile.claudeMdLineCount} lines (recommended: \u2264100)`
+    });
+  } else {
+    checks.push({
+      name: "CLAUDE.md",
+      weight: 3,
+      status: "pass",
+      message: `${profile.claudeMdLineCount} lines`
+    });
+  }
+  if (!profile.existingSettings) {
+    checks.push({
+      name: "settings.json",
+      weight: 2,
+      status: "fail",
+      message: "Missing settings.json"
+    });
+  } else {
+    const perms2 = profile.existingSettings.permissions;
+    const hasDeny = perms2?.deny && Array.isArray(perms2.deny) && perms2.deny.length > 0;
+    checks.push({
+      name: "Deny rules",
+      weight: 2,
+      status: hasDeny ? "pass" : "warn",
+      message: hasDeny ? "Deny rules configured" : "No deny rules in settings.json"
+    });
+  }
+  if (profile.mcpServerCount > 8) {
+    checks.push({
+      name: "MCP servers",
+      weight: 1,
+      status: "warn",
+      message: `${profile.mcpServerCount} servers (recommended: \u22648)`
+    });
+  } else if (profile.mcpServerCount > 0) {
+    checks.push({
+      name: "MCP servers",
+      weight: 1,
+      status: "pass",
+      message: `${profile.mcpServerCount} servers`
+    });
+  } else {
+    checks.push({
+      name: "MCP servers",
+      weight: 1,
+      status: "warn",
+      message: "No MCP servers configured"
+    });
+  }
+  checks.push({
+    name: "/project:help",
+    weight: 2,
+    status: profile.existingCommands.includes("help") ? "pass" : "fail",
+    message: profile.existingCommands.includes("help") ? "Help command present" : "Missing /project:help command"
+  });
+  checks.push({
+    name: "/project:tasks",
+    weight: 1,
+    status: profile.existingCommands.includes("tasks") ? "pass" : "warn",
+    message: profile.existingCommands.includes("tasks") ? "Tasks command present" : "Missing /project:tasks command"
+  });
+  checks.push({
+    name: "Security rule",
+    weight: 3,
+    status: profile.existingRules.includes("security") ? "pass" : "fail",
+    message: profile.existingRules.includes("security") ? "Security rule present" : "Missing rules/security.md"
+  });
+  checks.push({
+    name: "Continuity rule",
+    weight: 2,
+    status: profile.existingRules.includes("continuity") ? "pass" : "warn",
+    message: profile.existingRules.includes("continuity") ? "Continuity rule present" : "Missing rules/continuity.md"
+  });
+  const hasHooks = profile.existingSettings?.hooks;
+  checks.push({
+    name: "Hooks",
+    weight: 1,
+    status: hasHooks ? "pass" : "warn",
+    message: hasHooks ? "Hooks configured" : "No hooks in settings.json"
+  });
+  const perms = profile.existingSettings?.permissions;
+  const denyList = perms?.deny || [];
+  const envProtected = denyList.some((d) => d.includes(".env"));
+  checks.push({
+    name: ".env protection",
+    weight: 2,
+    status: envProtected ? "pass" : "warn",
+    message: envProtected ? ".env in deny list" : ".env not in deny list"
+  });
+  if (profile.existingClaudeMd) {
+    const requiredSections = ["## Purpose", "## Commands", "## Tech Stack"];
+    const missingSections = requiredSections.filter(
+      (s) => !profile.existingClaudeMd.includes(s)
+    );
+    if (missingSections.length > 0) {
+      checks.push({
+        name: "CLAUDE.md sections",
+        weight: 1,
+        status: "warn",
+        message: `Missing: ${missingSections.join(", ")}`
+      });
+    } else {
+      checks.push({
+        name: "CLAUDE.md sections",
+        weight: 1,
+        status: "pass",
+        message: "Required sections present"
+      });
+    }
+  }
+  return checks;
+}
+var doctorCommand = new Command7("doctor").description(
+  "Validate the current Claude Code environment against best practices"
+).action(async () => {
+  const targetDir = process.cwd();
+  console.log(chalk7.dim("\n  Checking .claude/ environment...\n"));
+  const profile = await scanProject(targetDir);
+  if (!profile.hasClaudeDir) {
+    console.log(chalk7.red("  \u274C No .claude/ directory found.\n"));
+    console.log(
+      chalk7.dim("  Run ") + chalk7.bold("kairn describe") + chalk7.dim(" or ") + chalk7.bold("kairn optimize") + chalk7.dim(" to generate one.\n")
+    );
+    process.exit(1);
+  }
+  const checks = runChecks(profile);
+  for (const check of checks) {
+    const icon = check.status === "pass" ? chalk7.green("\u2705") : check.status === "warn" ? chalk7.yellow("\u26A0\uFE0F ") : chalk7.red("\u274C");
+    const msg = check.status === "pass" ? chalk7.dim(check.message) : check.status === "warn" ? chalk7.yellow(check.message) : chalk7.red(check.message);
+    console.log(`  ${icon} ${check.name}: ${msg}`);
+  }
+  const maxScore = checks.reduce((sum, c) => sum + c.weight, 0);
+  const score = checks.reduce((sum, c) => {
+    if (c.status === "pass") return sum + c.weight;
+    if (c.status === "warn") return sum + Math.floor(c.weight / 2);
+    return sum;
+  }, 0);
+  const percentage = Math.round(score / maxScore * 100);
+  const scoreColor = percentage >= 80 ? chalk7.green : percentage >= 50 ? chalk7.yellow : chalk7.red;
+  console.log(
+    `
+  Score: ${scoreColor(`${score}/${maxScore}`)} (${scoreColor(`${percentage}%`)})
+`
+  );
+  if (percentage < 80) {
+    console.log(
+      chalk7.dim("  Run ") + chalk7.bold("kairn optimize") + chalk7.dim(" to fix issues.\n")
+    );
+  }
+});
+
+// src/commands/registry.ts
+import { Command as Command8 } from "commander";
+import chalk8 from "chalk";
+import { input as input2, select as select2 } from "@inquirer/prompts";
+var listCommand2 = new Command8("list").description("List tools in the registry").option("--category <cat>", "Filter by category").option("--user-only", "Show only user-defined tools").action(async (options) => {
+  let all;
+  let userTools;
+  try {
+    [all, userTools] = await Promise.all([loadRegistry(), loadUserRegistry()]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.log(chalk8.red(`
+  Failed to load registry: ${msg}
+`));
+    process.exit(1);
+  }
+  const userIds = new Set(userTools.map((t) => t.id));
+  let tools = all;
+  if (options.userOnly) {
+    tools = tools.filter((t) => userIds.has(t.id));
+  }
+  if (options.category) {
+    tools = tools.filter(
+      (t) => t.category.toLowerCase() === options.category.toLowerCase()
+    );
+  }
+  if (tools.length === 0) {
+    console.log(chalk8.dim("\n  No tools found.\n"));
+    return;
+  }
+  const bundledCount = all.filter((t) => !userIds.has(t.id)).length;
+  const userCount = userIds.size;
+  console.log(chalk8.cyan("\n  Registry Tools\n"));
+  for (const tool of tools) {
+    const isUser = userIds.has(tool.id);
+    const meta = [
+      tool.category,
+      `tier ${tool.tier}`,
+      tool.auth
+    ].join(", ");
+    console.log(chalk8.bold(`  ${tool.id}`) + chalk8.dim(` (${meta})`));
+    console.log(chalk8.dim(`    ${tool.description}`));
+    if (tool.best_for.length > 0) {
+      console.log(chalk8.dim(`    Best for: ${tool.best_for.join(", ")}`));
+    }
+    if (isUser) {
+      console.log(chalk8.yellow("    [USER-DEFINED]"));
+    }
+    console.log("");
+  }
+  const totalShown = tools.length;
+  const shownUser = tools.filter((t) => userIds.has(t.id)).length;
+  const shownBundled = totalShown - shownUser;
+  console.log(
+    chalk8.dim(
+      `  ${totalShown} tool${totalShown !== 1 ? "s" : ""} (${shownBundled} bundled, ${shownUser} user-defined)`
+    ) + "\n"
+  );
+});
+var addCommand = new Command8("add").description("Add a tool to the user registry").action(async () => {
+  let id;
+  try {
+    id = await input2({
+      message: "Tool ID (kebab-case)",
+      validate: (v) => {
+        if (!v) return "ID is required";
+        if (!/^[a-z][a-z0-9-]*$/.test(v)) return "ID must be kebab-case (e.g. my-tool)";
+        return true;
+      }
+    });
+    const name = await input2({ message: "Display name" });
+    const description = await input2({ message: "Description" });
+    const category = await select2({
+      message: "Category",
+      choices: [
+        { value: "universal" },
+        { value: "code" },
+        { value: "search" },
+        { value: "data" },
+        { value: "communication" },
+        { value: "design" },
+        { value: "monitoring" },
+        { value: "infrastructure" },
+        { value: "sandbox" }
+      ]
+    });
+    const tier = await select2({
+      message: "Tier",
+      choices: [
+        { name: "1 \u2014 Universal", value: 1 },
+        { name: "2 \u2014 Common", value: 2 },
+        { name: "3 \u2014 Specialized", value: 3 }
+      ]
+    });
+    const type = await select2({
+      message: "Type",
+      choices: [
+        { value: "mcp_server" },
+        { value: "plugin" },
+        { value: "hook" }
+      ]
+    });
+    const auth = await select2({
+      message: "Auth",
+      choices: [
+        { value: "none" },
+        { value: "api_key" },
+        { value: "oauth" },
+        { value: "connection_string" }
+      ]
+    });
+    const env_vars = [];
+    if (auth === "api_key" || auth === "connection_string") {
+      let addMore = true;
+      while (addMore) {
+        const varName = await input2({ message: "Env var name" });
+        const varDesc = await input2({ message: "Env var description" });
+        env_vars.push({ name: varName, description: varDesc });
+        const another = await select2({
+          message: "Add another env var?",
+          choices: [
+            { name: "No", value: false },
+            { name: "Yes", value: true }
+          ]
+        });
+        addMore = another;
+      }
+    }
+    const signup_url_raw = await input2({ message: "Signup URL (optional, press enter to skip)" });
+    const signup_url = signup_url_raw.trim() || void 0;
+    const best_for_raw = await input2({ message: "Best-for tags, comma-separated" });
+    const best_for = best_for_raw.split(",").map((s) => s.trim()).filter(Boolean);
+    const install = {};
+    if (type === "mcp_server") {
+      const command = await input2({ message: "MCP command" });
+      const args_raw = await input2({ message: "MCP args, comma-separated (leave blank for none)" });
+      const args = args_raw.split(",").map((s) => s.trim()).filter(Boolean);
+      install.mcp_config = { command, args };
+    }
+    const tool = {
+      id,
+      name,
+      description,
+      category,
+      tier,
+      type,
+      auth,
+      best_for,
+      install,
+      ...env_vars.length > 0 ? { env_vars } : {},
+      ...signup_url ? { signup_url } : {}
+    };
+    let userTools;
+    try {
+      userTools = await loadUserRegistry();
+    } catch {
+      userTools = [];
     }
+    const existingIdx = userTools.findIndex((t) => t.id === id);
+    if (existingIdx >= 0) {
+      userTools[existingIdx] = tool;
+    } else {
+      userTools.push(tool);
+    }
+    await saveUserRegistry(userTools);
+    console.log(chalk8.green(`
+  \u2713 Tool ${id} added to user registry
+`));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.log(chalk8.red(`
+  Failed to add tool: ${msg}
+`));
+    process.exit(1);
+  }
+});
+var registryCommand = new Command8("registry").description("Manage the tool registry").addCommand(listCommand2).addCommand(addCommand);
+
+// src/commands/templates.ts
+import { Command as Command9 } from "commander";
+import chalk9 from "chalk";
+import fs12 from "fs/promises";
+import path12 from "path";
+var templatesCommand = new Command9("templates").description("Browse available templates").option("--category <cat>", "filter templates by category keyword").option("--json", "output raw JSON array").action(async (options) => {
+  const templatesDir = getTemplatesDir();
+  let files;
+  try {
+    files = await fs12.readdir(templatesDir);
+  } catch {
+    console.log(
+      chalk9.dim(
+        "\n  No templates found. Templates will be installed with "
+      ) + chalk9.bold("kairn init") + chalk9.dim(
+        " or you can add .json files to ~/.kairn/templates/\n"
+      )
+    );
+    return;
+  }
+  const jsonFiles = files.filter((f) => f.endsWith(".json"));
+  if (jsonFiles.length === 0) {
+    console.log(
+      chalk9.dim(
+        "\n  No templates found. Templates will be installed with "
+      ) + chalk9.bold("kairn init") + chalk9.dim(
+        " or you can add .json files to ~/.kairn/templates/\n"
+      )
+    );
+    return;
+  }
+  const templates = [];
+  for (const file of jsonFiles) {
+    try {
+      const data = await fs12.readFile(
+        path12.join(templatesDir, file),
+        "utf-8"
+      );
+      const spec = JSON.parse(data);
+      templates.push(spec);
+    } catch {
+    }
+  }
+  const filtered = options.category ? templates.filter((t) => {
+    const keyword = options.category.toLowerCase();
+    return t.intent?.toLowerCase().includes(keyword) || t.description?.toLowerCase().includes(keyword);
+  }) : templates;
+  if (options.json) {
+    console.log(JSON.stringify(filtered, null, 2));
+    return;
+  }
+  if (filtered.length === 0) {
+    console.log(
+      chalk9.dim(`
+  No templates matched category "${options.category}".
+`)
+    );
+    return;
+  }
+  console.log(chalk9.cyan("\n  Available Templates\n"));
+  for (const spec of filtered) {
+    const toolCount = spec.tools?.length ?? 0;
+    const commandCount = Object.keys(spec.harness?.commands ?? {}).length;
+    const ruleCount = Object.keys(spec.harness?.rules ?? {}).length;
+    console.log(
+      chalk9.bold(`  ${spec.name}`) + chalk9.dim(` (ID: ${spec.id})`)
+    );
+    console.log(chalk9.dim(`    ${spec.description}`));
+    console.log(
+      chalk9.dim(
+        `    Tools: ${toolCount} | Commands: ${commandCount} | Rules: ${ruleCount}`
+      )
+    );
+    console.log("");
   }
   console.log(
-    chalk6.cyan("\n  Ready! Run ") + chalk6.bold("claude") + chalk6.cyan(" to start.\n")
+    chalk9.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
+`)
   );
 });
 
 // src/cli.ts
-var program = new Command7();
+var program = new Command10();
 program.name("kairn").description(
   "Compile natural language intent into optimized Claude Code environments"
-).version("1.3.0");
+).version("1.5.0");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);
 program.addCommand(listCommand);
 program.addCommand(activateCommand);
 program.addCommand(updateRegistryCommand);
+program.addCommand(doctorCommand);
+program.addCommand(registryCommand);
+program.addCommand(templatesCommand);
 program.parse();
 //# sourceMappingURL=cli.js.map