kairn-cli 1.5.1 → 1.7.0

package/dist/cli.js

@@ -1,10 +1,11 @@
 // src/cli.ts
 import { Command as Command10 } from "commander";
+import chalk12 from "chalk";
 
 // src/commands/init.ts
 import { Command } from "commander";
 import { password, select } from "@inquirer/prompts";
-import chalk from "chalk";
+import chalk3 from "chalk";
 import Anthropic from "@anthropic-ai/sdk";
 import OpenAI from "openai";
 import { execFileSync } from "child_process";
@@ -61,6 +62,115 @@ async function saveConfig(config) {
   await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
 }
 
+// src/ui.ts
+import chalk from "chalk";
+var maroon = chalk.rgb(139, 0, 0);
+var warm = chalk.rgb(212, 165, 116);
+var ui = {
+  // Brand
+  brand: (text) => maroon.bold(text),
+  accent: (text) => warm(text),
+  // Headers
+  header: (text) => {
+    const line = "\u2500".repeat(50);
+    return `
+  ${maroon("\u250C" + line + "\u2510")}
+  ${maroon("\u2502")} ${maroon.bold(text.padEnd(49))}${maroon("\u2502")}
+  ${maroon("\u2514" + line + "\u2518")}
+`;
+  },
+  // Sections
+  section: (title) => `
+  ${warm("\u2501\u2501")} ${chalk.bold(title)} ${warm("\u2501".repeat(Math.max(0, 44 - title.length)))}`,
+  // Status
+  success: (text) => chalk.green(`  \u2713 ${text}`),
+  warn: (text) => chalk.yellow(`  \u26A0 ${text}`),
+  error: (text) => chalk.red(`  \u2717 ${text}`),
+  info: (text) => chalk.cyan(`  \u2139 ${text}`),
+  // Key-value pairs
+  kv: (key, value) => `  ${chalk.cyan(key.padEnd(14))} ${value}`,
+  // File list
+  file: (path13) => chalk.dim(`    ${path13}`),
+  // Tool display
+  tool: (name, reason) => `    ${warm("\u25CF")} ${chalk.bold(name)}
+      ${chalk.dim(reason)}`,
+  // Divider
+  divider: () => chalk.dim(`  ${"\u2500".repeat(50)}`),
+  // Command suggestion
+  cmd: (command) => `    ${chalk.bold.white("$ " + command)}`,
+  // Env var setup
+  envVar: (name, desc, url) => {
+    let out = `    ${chalk.bold(`export ${name}=`)}${chalk.dim('"your-key-here"')}
+`;
+    out += chalk.dim(`      ${desc}`);
+    if (url) out += `
+      ${chalk.dim("Get one at:")} ${warm(url)}`;
+    return out;
+  },
+  // Clarification question display
+  question: (q, suggestion) => `  ${warm("?")} ${chalk.bold(q)}
+    ${chalk.dim(`suggested: ${suggestion}`)}`,
+  // Branded error box
+  errorBox: (title, message) => {
+    const line = "\u2500".repeat(50);
+    return `
+  ${chalk.red("\u250C" + line + "\u2510")}
+  ${chalk.red("\u2502")} ${chalk.red.bold(title.padEnd(49))}${chalk.red("\u2502")}
+  ${chalk.red("\u2514" + line + "\u2518")}
+
+  ${chalk.red("\u2717")} ${message}
+`;
+  }
+};
+
+// src/logo.ts
+import chalk2 from "chalk";
+var maroon2 = chalk2.rgb(139, 0, 0);
+var darkMaroon = chalk2.rgb(100, 0, 0);
+var warmStone = chalk2.rgb(180, 120, 80);
+var lightStone = chalk2.rgb(212, 165, 116);
+var dimStone = chalk2.rgb(140, 100, 70);
+var KAIRN_WORDMARK = [
+  maroon2("\u2588\u2588\u2557  \u2588\u2588\u2557") + darkMaroon("  ") + maroon2("\u2588\u2588\u2588\u2588\u2588\u2557 ") + darkMaroon(" ") + maroon2("\u2588\u2588\u2557") + darkMaroon("  ") + maroon2("\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ") + darkMaroon("  ") + maroon2("\u2588\u2588\u2588\u2557   \u2588\u2588\u2557"),
+  maroon2("\u2588\u2588\u2551 \u2588\u2588\u2554\u255D") + darkMaroon("  ") + maroon2("\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557") + darkMaroon(" ") + maroon2("\u2588\u2588\u2551") + darkMaroon("  ") + maroon2("\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557") + darkMaroon("  ") + maroon2("\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551"),
+  warmStone("\u2588\u2588\u2588\u2588\u2588\u2554\u255D ") + dimStone("  ") + warmStone("\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551") + dimStone(" ") + warmStone("\u2588\u2588\u2551") + dimStone("  ") + warmStone("\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D") + dimStone("  ") + warmStone("\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551"),
+  warmStone("\u2588\u2588\u2554\u2550\u2588\u2588\u2557 ") + dimStone("  ") + warmStone("\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551") + dimStone(" ") + warmStone("\u2588\u2588\u2551") + dimStone("  ") + warmStone("\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557") + dimStone("  ") + warmStone("\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551"),
+  lightStone("\u2588\u2588\u2551  \u2588\u2588\u2557") + dimStone("  ") + lightStone("\u2588\u2588\u2551  \u2588\u2588\u2551") + dimStone(" ") + lightStone("\u2588\u2588\u2551") + dimStone("  ") + lightStone("\u2588\u2588\u2551  \u2588\u2588\u2551") + dimStone("  ") + lightStone("\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551"),
+  lightStone("\u255A\u2550\u255D  \u255A\u2550\u255D") + dimStone("  ") + lightStone("\u255A\u2550\u255D  \u255A\u2550\u255D") + dimStone(" ") + lightStone("\u255A\u2550\u255D") + dimStone("  ") + lightStone("\u255A\u2550\u255D  \u255A\u2550\u255D") + dimStone("  ") + lightStone("\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D")
+];
+var CAIRN_ART = [
+  dimStone("            \u28C0\u28C0\u28C0            "),
+  warmStone("          \u28F4\u28FF\u28FF\u28FF\u28E6          "),
+  warmStone("           \u2819\u283F\u283F\u280B           "),
+  dimStone("         \u28C0\u28E4\u28E4\u28E4\u28E4\u28C0         "),
+  lightStone("       \u28F4\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28E6       "),
+  lightStone("        \u2819\u283B\u283F\u283F\u283F\u281F\u280B        "),
+  dimStone("      \u28C0\u28E4\u28E4\u28F6\u28F6\u28F6\u28F6\u28E4\u28E4\u28C0      "),
+  warmStone("    \u28F4\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28E6    "),
+  warmStone("     \u2819\u283B\u283F\u283F\u283F\u283F\u283F\u283F\u281F\u280B     "),
+  dimStone("   \u28C0\u28E4\u28F6\u28F6\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28F6\u28F6\u28E4\u28C0   "),
+  lightStone("  \u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF\u28FF  "),
+  dimStone("  \u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809\u2809  ")
+];
+function printFullBanner(subtitle) {
+  console.log("");
+  for (const line of KAIRN_WORDMARK) {
+    console.log("  " + line);
+  }
+  if (subtitle) {
+    console.log(dimStone(`  ${subtitle}`));
+  }
+  console.log("");
+}
+function printCompactBanner() {
+  const line = maroon2("\u2501").repeat(50);
+  console.log(`
+  ${line}`);
+  console.log(`  ${maroon2("  \u25C6")} ${chalk2.bold.rgb(139, 0, 0)("KAIRN")} ${dimStone("\u2014 Agent Environment Compiler")}`);
+  console.log(`  ${line}
+`);
+}
+
 // src/commands/init.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = path2.dirname(__filename);
@@ -95,7 +205,7 @@ async function installSeedTemplates() {
     }
   }
   if (installed > 0) {
-    console.log(chalk.green(`  \u2713 ${installed} template${installed === 1 ? "" : "s"} installed`));
+    console.log(ui.success(`${installed} template${installed === 1 ? "" : "s"} installed`));
   }
 }
 var PROVIDER_MODELS = {
@@ -167,13 +277,11 @@ function detectClaudeCode() {
   }
 }
 var initCommand = new Command("init").description("Set up Kairn with your API key").action(async () => {
-  console.log(chalk.cyan("\n  Kairn Setup\n"));
+  printFullBanner("Setup");
   const existing = await loadConfig();
   if (existing) {
-    console.log(
-      chalk.yellow("  Config already exists at ") + chalk.dim(getConfigPath())
-    );
-    console.log(chalk.yellow("  Running setup will overwrite it.\n"));
+    console.log(ui.warn(`Config already exists at ${chalk3.dim(getConfigPath())}`));
+    console.log(ui.warn("Running setup will overwrite it.\n"));
   }
   const provider = await select({
     message: "LLM provider",
@@ -193,18 +301,16 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
     mask: "*"
   });
   if (!apiKey) {
-    console.log(chalk.red("\n  No API key provided. Aborting."));
+    console.log(ui.error("No API key provided. Aborting."));
     process.exit(1);
   }
-  console.log(chalk.dim("\n  Verifying API key..."));
+  console.log(chalk3.dim("\n  Verifying API key..."));
   const valid = await verifyKey(provider, apiKey, model);
   if (!valid) {
-    console.log(
-      chalk.red("  Invalid API key. Check your key and try again.")
-    );
+    console.log(ui.error("Invalid API key. Check your key and try again."));
     process.exit(1);
   }
-  console.log(chalk.green("  \u2713 API key verified"));
+  console.log(ui.success("API key verified"));
   const config = {
     provider,
     api_key: apiKey,
@@ -213,32 +319,28 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
     created_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   await saveConfig(config);
-  console.log(
-    chalk.green("  \u2713 Config saved to ") + chalk.dim(getConfigPath())
-  );
-  console.log(
-    chalk.dim(`  \u2713 Provider: ${providerInfo.name}, Model: ${model}`)
-  );
+  console.log(ui.success(`Config saved to ${chalk3.dim(getConfigPath())}`));
+  console.log(ui.kv("Provider", providerInfo.name));
+  console.log(ui.kv("Model", model));
   await installSeedTemplates();
   const hasClaude = detectClaudeCode();
   if (hasClaude) {
-    console.log(chalk.green("  \u2713 Claude Code detected"));
+    console.log(ui.success("Claude Code detected"));
   } else {
     console.log(
-      chalk.yellow(
-        "  \u26A0 Claude Code not found. Install it: npm install -g @anthropic-ai/claude-code"
-      )
+      ui.warn("Claude Code not found. Install it: npm install -g @anthropic-ai/claude-code")
     );
   }
   console.log(
-    chalk.cyan("\n  Ready! Run ") + chalk.bold("kairn describe") + chalk.cyan(" to create your first environment.\n")
+    "\n" + ui.success(`Ready! Run ${chalk3.bold("kairn describe")} to create your first environment.`) + "\n"
   );
 });
 
 // src/commands/describe.ts
 import { Command as Command2 } from "commander";
 import { input, confirm } from "@inquirer/prompts";
-import chalk2 from "chalk";
+import chalk4 from "chalk";
+import ora from "ora";
 
 // src/compiler/compile.ts
 import fs4 from "fs/promises";
@@ -260,12 +362,12 @@ You must output a JSON object matching the EnvironmentSpec schema.
 
 - **Minimalism over completeness.** Fewer, well-chosen tools beat many generic ones. Each MCP server costs 500-2000 context tokens.
 - **Workflow-specific, not generic.** Every instruction, command, and rule must relate to the user's actual workflow.
-- **Concise CLAUDE.md.** Under 100 lines. No generic text like "be helpful." Include build/test commands, reference docs/ and skills/.
+- **Concise CLAUDE.md.** Under 120 lines. No generic text like "be helpful." Include build/test commands, reference docs/ and skills/.
 - **Security by default.** Always include deny rules for destructive commands and secret file access.
 
 ## CLAUDE.md Template (mandatory structure)
 
-The \`claude_md\` field MUST follow this exact structure (max 100 lines):
+The \`claude_md\` field MUST follow this exact structure (max 120 lines):
 
 \`\`\`
 # {Project Name}
@@ -290,6 +392,30 @@ The \`claude_md\` field MUST follow this exact structure (max 100 lines):
 
 ## Output
 {where results go, key files}
+
+## Verification
+After implementing any change, verify it works:
+- {build command} \u2014 must pass with no errors
+- {test command} \u2014 all tests must pass
+- {lint command} \u2014 no warnings or errors
+- {type check command} \u2014 no type errors
+
+If any verification step fails, fix the issue before moving on.
+Do NOT skip verification steps.
+
+## Known Gotchas
+<!-- After any correction, add it here: "Update CLAUDE.md so you don't make that mistake again." -->
+<!-- Prune this section when it exceeds 10 items \u2014 keep only the recurring ones. -->
+- (none yet \u2014 this section grows as you work)
+
+## Debugging
+When debugging, paste raw error output. Don't summarize \u2014 Claude works better with raw data.
+Use subagents for deep investigation to keep main context clean.
+
+## Git Workflow
+- Prefer small, focused commits (one feature or fix per commit)
+- Use conventional commits: feat:, fix:, docs:, refactor:, test:
+- Target < 200 lines per PR when possible
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -308,6 +434,10 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 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)
+13. A "Verification" section in CLAUDE.md with concrete verify commands for the project
+14. A "Known Gotchas" section in CLAUDE.md (starts empty, grows with corrections)
+15. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
+16. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 
 ## Shell-Integrated Commands
 
@@ -428,7 +558,7 @@ Merge this into the settings hooks alongside the PreToolUse and PostToolUse hook
 ## Context Budget (STRICT)
 
 - MCP servers: maximum 6. Prefer fewer.
-- CLAUDE.md: maximum 100 lines.
+- CLAUDE.md: maximum 120 lines.
 - Rules: maximum 5 files, each under 20 lines.
 - Skills: maximum 3. Only include directly relevant ones.
 - Agents: maximum 3. QA pipeline + one specialist.
@@ -456,6 +586,10 @@ Each MCP server costs 500-2000 tokens of context window.
   - \`@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
+- \`/project:spec\` command (interview-based spec creation \u2014 asks 5-8 questions one at a time, writes structured spec to docs/SPRINT.md, does NOT start coding until confirmed)
+- \`/project:prove\` command (runs tests, shows git diff vs main, rates confidence HIGH/MEDIUM/LOW with evidence)
+- \`/project:grill\` command (adversarial code review \u2014 challenges each change with "why this approach?", "what if X input?", rates BLOCKER/SHOULD-FIX/NITPICK, blocks until BLOCKERs resolved)
+- \`/project:reset\` command (reads DECISIONS.md and LEARNINGS.md, proposes clean restart, stashes current work, implements elegant solution)
 
 ## For Research Projects, Additionally Include
 
@@ -463,6 +597,7 @@ Each MCP server costs 500-2000 tokens of context window.
 - \`/project:summarize\` command (summarize findings)
 - A research-synthesis skill
 - A researcher agent
+- Note: the Verification section in CLAUDE.md should adapt for research \u2014 e.g. "Verify all sources are cited" instead of build/test commands
 
 ## For Content/Writing Projects, Additionally Include
 
@@ -491,7 +626,7 @@ Return ONLY valid JSON matching this structure:
     { "tool_id": "id-from-registry", "reason": "why this tool fits" }
   ],
   "harness": {
-    "claude_md": "The full CLAUDE.md content (under 100 lines)",
+    "claude_md": "The full CLAUDE.md content (under 120 lines)",
     "settings": {
       "permissions": {
         "allow": ["Bash(npm run *)", "Read", "Write", "Edit"],
@@ -506,7 +641,11 @@ Return ONLY valid JSON matching this structure:
       "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",
-      "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."
+      "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.",
+      "spec": "Before building this feature, interview me to create a complete spec.\\n\\nAsk me 5-8 questions, one at a time:\\n1. What specifically should this feature do?\\n2. Who uses it and how?\\n3. What are the edge cases or error states?\\n4. How will we know it works? (acceptance criteria)\\n5. What should it explicitly NOT do? (scope boundaries)\\n6. Any dependencies, APIs, or constraints?\\n7. How does it fit with existing code?\\n8. Priority: speed, quality, or flexibility?\\n\\nAfter my answers, write a structured spec to docs/SPRINT.md:\\n- Feature name\\n- Description (from my answers, not invented)\\n- Acceptance criteria (testable)\\n- Out of scope\\n- Technical approach\\n\\nDo NOT start coding until I confirm the spec.",
+      "prove": "Prove the current implementation works.\\n\\n1. Run the full test suite:\\n\\n!npm test 2>&1\\n\\n2. Compare against main:\\n\\n!git diff main --stat 2>/dev/null\\n\\n3. Show evidence:\\n   - Test results (pass/fail counts)\\n   - Behavioral diff (main vs this branch)\\n   - Edge cases tested\\n   - Error handling verified\\n\\n4. Rate confidence:\\n   - HIGH: All tests pass, edge cases covered, no regressions\\n   - MEDIUM: Core works, some edges untested\\n   - LOW: Needs more verification\\n\\nIf LOW or MEDIUM, explain what's missing and fix it.",
+      "grill": "Review the current changes adversarially.\\n\\n!git diff --staged 2>/dev/null || git diff HEAD 2>/dev/null\\n\\nAct as a senior engineer. For each file changed:\\n\\n1. \\"Why this approach over X?\\"\\n2. \\"What happens if Y input?\\"\\n3. \\"Performance impact of Z?\\"\\n4. \\"This could break if...\\"\\n\\nFor each concern:\\n- Severity: BLOCKER / SHOULD-FIX / NITPICK\\n- The exact scenario that could fail\\n- A suggested alternative\\n\\nDo NOT approve until all BLOCKERs are resolved.",
+      "reset": "Stop. Read docs/DECISIONS.md and docs/LEARNINGS.md.\\n\\nConsidering everything we've learned:\\n1. What was the original approach?\\n2. What went wrong or feels inelegant?\\n3. What would the clean solution look like?\\n\\nPropose the new approach. Do NOT implement yet.\\nIf I approve, stash current changes:\\n  git stash -m \\"pre-reset: $(date +%Y%m%d-%H%M)\\"\\n\\nThen implement the elegant solution."
     },
     "rules": {
       "continuity": "markdown content for continuity rule",
@@ -531,6 +670,28 @@ Return ONLY valid JSON matching this structure:
 \`\`\`
 
 Do not include any text outside the JSON object. Do not wrap in markdown code fences.`;
+var CLARIFICATION_PROMPT = `You are helping a user define their project for environment compilation.
+
+Given their initial description, generate 3-5 clarifying questions to understand:
+1. Language and framework
+2. What the project specifically does (be precise)
+3. Primary workflow (build, research, write, analyze?)
+4. Key dependencies or integrations
+5. Target audience
+
+For each question, provide a reasonable suggestion based on the description.
+
+Output ONLY a JSON array:
+[
+  { "question": "Language/framework?", "suggestion": "TypeScript + Node.js" },
+  ...
+]
+
+Rules:
+- Suggestions should be reasonable guesses, clearly marked as suggestions
+- Keep questions short (under 10 words)
+- Maximum 5 questions
+- If the description is already very detailed, ask fewer questions`;
 
 // src/registry/loader.ts
 import fs3 from "fs/promises";
@@ -731,10 +892,49 @@ async function compile(intent, onProgress) {
   await fs4.writeFile(envPath, JSON.stringify(spec, null, 2), "utf-8");
   return spec;
 }
+async function generateClarifications(intent, onProgress) {
+  const config = await loadConfig();
+  if (!config) {
+    throw new Error("No config found. Run `kairn init` first.");
+  }
+  onProgress?.("Analyzing your request...");
+  const clarificationConfig = { ...config };
+  if (config.provider === "anthropic") {
+    clarificationConfig.model = "claude-haiku-4-5-20251001";
+  }
+  const response = await callLLM(clarificationConfig, CLARIFICATION_PROMPT + "\n\nUser description: " + intent);
+  try {
+    let cleaned = response.trim();
+    if (cleaned.startsWith("```")) {
+      cleaned = cleaned.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
+    }
+    const jsonMatch = cleaned.match(/\[[\s\S]*\]/);
+    if (!jsonMatch) return [];
+    return JSON.parse(jsonMatch[0]);
+  } catch {
+    return [];
+  }
+}
 
 // src/adapter/claude-code.ts
 import fs5 from "fs/promises";
 import path5 from "path";
+var STATUS_LINE = {
+  command: `printf '%s | %s tasks' "$(git branch --show-current 2>/dev/null || echo 'no-git')" "$(grep -c '\\- \\[ \\]' docs/TODO.md 2>/dev/null || echo 0)"`
+};
+function isCodeProject(spec) {
+  const commands = spec.harness.commands ?? {};
+  return "status" in commands || "test" in commands;
+}
+function resolveSettings(spec) {
+  const settings = spec.harness.settings;
+  if (!settings || Object.keys(settings).length === 0) return null;
+  if ("statusLine" in settings) return settings;
+  if (isCodeProject(spec)) {
+    return { ...settings, statusLine: STATUS_LINE };
+  }
+  return settings;
+}
 async function writeFile(filePath, content) {
   await fs5.mkdir(path5.dirname(filePath), { recursive: true });
   await fs5.writeFile(filePath, content, "utf-8");
@@ -744,11 +944,9 @@ function buildFileMap(spec) {
   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)
-    );
+  const resolvedSettings = resolveSettings(spec);
+  if (resolvedSettings) {
+    files.set(".claude/settings.json", JSON.stringify(resolvedSettings, null, 2));
   }
   if (spec.harness.mcp_config && Object.keys(spec.harness.mcp_config).length > 0) {
     files.set(
@@ -791,9 +989,10 @@ async function writeEnvironment(spec, targetDir) {
     await writeFile(p, spec.harness.claude_md);
     written.push(".claude/CLAUDE.md");
   }
-  if (spec.harness.settings && Object.keys(spec.harness.settings).length > 0) {
+  const resolvedSettings = resolveSettings(spec);
+  if (resolvedSettings) {
     const p = path5.join(claudeDir, "settings.json");
-    await writeFile(p, JSON.stringify(spec.harness.settings, null, 2));
+    await writeFile(p, JSON.stringify(resolvedSettings, null, 2));
     written.push(".claude/settings.json");
   }
   if (spec.harness.mcp_config && Object.keys(spec.harness.mcp_config).length > 0) {
@@ -994,138 +1193,170 @@ async function writeHermesEnvironment(spec, registry) {
 }
 
 // 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) => {
+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("-q, --quick", "Skip clarification questions").option("--runtime <runtime>", "Target runtime (claude-code or hermes)", "claude-code").action(async (intentArg, options) => {
+  printFullBanner("The Agent Environment Compiler");
   const config = await loadConfig();
   if (!config) {
     console.log(
-      chalk2.red("\n  No config found. Run ") + chalk2.bold("kairn init") + chalk2.red(" first.\n")
+      ui.errorBox(
+        "No configuration found",
+        `Run ${chalk4.bold("kairn init")} to set up your API key.`
+      )
     );
     process.exit(1);
   }
-  const intent = intentArg || await input({
+  const intentRaw = intentArg || await input({
     message: "What do you want your agent to do?"
   });
-  if (!intent.trim()) {
-    console.log(chalk2.red("\n  No description provided. Aborting.\n"));
+  if (!intentRaw.trim()) {
+    console.log(chalk4.red("\n  No description provided. Aborting.\n"));
     process.exit(1);
   }
-  console.log("");
+  let finalIntent = intentRaw;
+  if (!options.quick) {
+    console.log(ui.section("Clarification"));
+    console.log(chalk4.dim("  Let me understand your project better."));
+    console.log(chalk4.dim("  Press Enter to accept the suggestion, or type your own answer.\n"));
+    let clarifications = [];
+    try {
+      clarifications = await generateClarifications(intentRaw);
+    } catch {
+    }
+    if (clarifications.length > 0) {
+      const answers = [];
+      for (const c of clarifications) {
+        const answer = await input({
+          message: c.question,
+          default: c.suggestion
+        });
+        answers.push({ question: c.question, answer });
+      }
+      const clarificationLines = answers.map((a) => `- ${a.question}: ${a.answer}`).join("\n");
+      finalIntent = `User intent: "${intentRaw}"
+
+Clarifications:
+${clarificationLines}`;
+    }
+  }
+  console.log(ui.section("Compilation"));
+  const spinner = ora({ text: "Loading tool registry...", indent: 2 }).start();
   let spec;
   try {
-    spec = await compile(intent, (msg) => {
-      process.stdout.write(`\r  ${chalk2.dim(msg)}                    `);
+    spec = await compile(finalIntent, (msg) => {
+      spinner.text = msg;
     });
-    process.stdout.write("\r                                              \r");
+    spinner.succeed("Environment compiled");
   } catch (err) {
-    process.stdout.write("\r                                              \r");
+    spinner.fail("Compilation failed");
     const msg = err instanceof Error ? err.message : String(err);
-    console.log(chalk2.red(`
-  Compilation failed: ${msg}
+    console.log(chalk4.red(`
+  ${msg}
 `));
     process.exit(1);
   }
   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);
-  console.log(chalk2.cyan("  Description: ") + spec.description);
-  console.log(chalk2.cyan("  Tools: ") + summary.toolCount);
-  console.log(chalk2.cyan("  Commands: ") + summary.commandCount);
-  console.log(chalk2.cyan("  Rules: ") + summary.ruleCount);
-  console.log(chalk2.cyan("  Skills: ") + summary.skillCount);
-  console.log(chalk2.cyan("  Agents: ") + summary.agentCount);
+  console.log("");
+  console.log(ui.kv("Name:", spec.name));
+  console.log(ui.kv("Description:", spec.description));
+  console.log(ui.kv("Tools:", String(summary.toolCount)));
+  console.log(ui.kv("Commands:", String(summary.commandCount)));
+  console.log(ui.kv("Rules:", String(summary.ruleCount)));
+  console.log(ui.kv("Skills:", String(summary.skillCount)));
+  console.log(ui.kv("Agents:", String(summary.agentCount)));
   if (spec.tools.length > 0) {
-    console.log(chalk2.dim("\n  Selected tools:"));
+    console.log(ui.section("Selected Tools"));
+    console.log("");
     for (const tool of spec.tools) {
       const regTool = registry.find((t) => t.id === tool.tool_id);
       const name = regTool?.name || tool.tool_id;
-      console.log(chalk2.dim(`    - ${name}: ${tool.reason}`));
-    }
-  }
-  if (summary.pluginCommands.length > 0) {
-    console.log(chalk2.yellow("\n  Plugins to install manually:"));
-    for (const cmd of summary.pluginCommands) {
-      console.log(chalk2.yellow(`    ${cmd}`));
+      console.log(ui.tool(name, tool.reason));
+      console.log("");
     }
   }
-  console.log("");
   const proceed = options.yes || await confirm({
     message: "Generate environment in current directory?",
     default: true
   });
   if (!proceed) {
-    console.log(chalk2.dim("\n  Aborted. Environment saved to ~/.kairn/envs/\n"));
+    console.log(chalk4.dim("\n  Aborted. Environment saved to ~/.kairn/envs/\n"));
     return;
   }
   const targetDir = process.cwd();
   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"));
+    console.log("\n" + ui.success("Environment written for Hermes"));
+    console.log(
+      chalk4.cyan("\n  Ready! Run ") + chalk4.bold("hermes") + chalk4.cyan(" to start.\n")
+    );
   } else {
     const written = await writeEnvironment(spec, targetDir);
-    console.log(chalk2.green("\n  \u2713 Environment written\n"));
+    console.log(ui.section("Files Written"));
+    console.log("");
     for (const file of written) {
-      console.log(chalk2.dim(`    ${file}`));
+      console.log(ui.file(file));
     }
     if (summary.envSetup.length > 0) {
-      console.log(chalk2.yellow("\n  API keys needed (set these environment variables):\n"));
+      console.log(ui.section("Setup Required"));
+      console.log("");
       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(ui.envVar(env.envVar, env.description, env.signupUrl));
         console.log("");
       }
     }
     if (summary.pluginCommands.length > 0) {
-      console.log(chalk2.yellow("  Install plugins by running these in Claude Code:"));
+      console.log(ui.section("Plugins"));
+      console.log("");
       for (const cmd of summary.pluginCommands) {
-        console.log(chalk2.bold(`    ${cmd}`));
+        console.log(ui.cmd(cmd));
       }
+      console.log("");
     }
-    console.log(
-      chalk2.cyan("\n  Ready! Run ") + chalk2.bold("claude") + chalk2.cyan(" to start.\n")
-    );
+    console.log(ui.divider());
+    console.log(ui.success("Ready! Run: $ claude"));
+    console.log("");
   }
 });
 
 // src/commands/list.ts
 import { Command as Command3 } from "commander";
-import chalk3 from "chalk";
+import chalk5 from "chalk";
 import fs7 from "fs/promises";
 import path7 from "path";
 var listCommand = new Command3("list").description("Show saved environments").action(async () => {
+  printCompactBanner();
   const envsDir = getEnvsDir();
   let files;
   try {
     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"));
+    console.log(chalk5.dim("  No environments yet. Run ") + chalk5.bold("kairn describe") + chalk5.dim(" to create one.\n"));
     return;
   }
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   if (jsonFiles.length === 0) {
-    console.log(chalk3.dim("\n  No environments yet. Run ") + chalk3.bold("kairn describe") + chalk3.dim(" to create one.\n"));
+    console.log(chalk5.dim("  No environments yet. Run ") + chalk5.bold("kairn describe") + chalk5.dim(" to create one.\n"));
     return;
   }
-  console.log(chalk3.cyan("\n  Saved Environments\n"));
+  let first = true;
   for (const file of jsonFiles) {
     try {
       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;
-      console.log(chalk3.bold(`  ${spec.name}`));
-      console.log(chalk3.dim(`    ${spec.description}`));
-      console.log(
-        chalk3.dim(`    ${date} \xB7 ${toolCount} tools \xB7 ${spec.id}`)
-      );
+      if (!first) {
+        console.log(ui.divider());
+      }
+      first = false;
+      console.log(ui.kv("Name", chalk5.bold(spec.name)));
+      console.log(ui.kv("Description", spec.description));
+      console.log(ui.kv("Date", `${date} \xB7 ${toolCount} tools`));
+      console.log(ui.kv("ID", chalk5.dim(spec.id)));
       console.log("");
     } catch {
     }
@@ -1134,10 +1365,11 @@ 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 chalk6 from "chalk";
 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) => {
+  printCompactBanner();
   const envsDir = getEnvsDir();
   const templatesDir = getTemplatesDir();
   let sourceDir;
@@ -1166,34 +1398,30 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
       sourceDir = templatesDir;
       fromTemplate = true;
     } else {
-      console.log(chalk4.red(`
-  Environment "${envId}" not found.`));
-      console.log(chalk4.dim("  Run kairn list to see saved environments."));
-      console.log(chalk4.dim("  Run kairn templates to see available templates.\n"));
+      console.log(ui.error(`Environment "${envId}" not found.`));
+      console.log(chalk6.dim("  Run kairn list to see saved environments."));
+      console.log(chalk6.dim("  Run kairn templates to see available templates.\n"));
       process.exit(1);
     }
   }
   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}`) + label);
-  console.log(chalk4.dim(`  ${spec.description}
+  const label = fromTemplate ? chalk6.dim(" (template)") : "";
+  console.log(chalk6.cyan(`  Activating: ${spec.name}`) + label);
+  console.log(chalk6.dim(`  ${spec.description}
 `));
   const targetDir = process.cwd();
   const written = await writeEnvironment(spec, targetDir);
-  console.log(chalk4.green("  \u2713 Environment written\n"));
+  console.log(ui.success("Environment written\n"));
   for (const file of written) {
-    console.log(chalk4.dim(`    ${file}`));
+    console.log(ui.file(file));
   }
-  console.log(
-    chalk4.cyan("\n  Ready! Run ") + chalk4.bold("claude") + chalk4.cyan(" to start.\n")
-  );
+  console.log("\n" + ui.success(`Ready! Run: $ claude`) + "\n");
 });
 
 // src/commands/update-registry.ts
 import { Command as Command5 } from "commander";
-import chalk5 from "chalk";
+import chalk7 from "chalk";
 import fs9 from "fs/promises";
 import path9 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -1217,21 +1445,17 @@ async function getLocalRegistryPath() {
   throw new Error("Could not find local tools.json registry");
 }
 var updateRegistryCommand = new Command5("update-registry").description("Fetch the latest tool registry from GitHub").option("--url <url>", "Custom registry URL").action(async (options) => {
+  printCompactBanner();
   const url = options.url || REGISTRY_URL;
-  console.log(chalk5.dim(`
-  Fetching registry from ${url}...`));
+  console.log(chalk7.dim(`  Fetching registry from ${url}...`));
   try {
     const response = await fetch(url);
     if (!response.ok) {
       console.log(
-        chalk5.red(`  Failed to fetch registry: ${response.status} ${response.statusText}`)
-      );
-      console.log(
-        chalk5.dim("  The remote registry may not be available yet.")
-      );
-      console.log(
-        chalk5.dim("  Your local registry is still active.\n")
+        ui.error(`Failed to fetch registry: ${response.status} ${response.statusText}`)
       );
+      console.log(chalk7.dim("  The remote registry may not be available yet."));
+      console.log(chalk7.dim("  Your local registry is still active.\n"));
       return;
     }
     const text = await response.text();
@@ -1242,7 +1466,7 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
       if (tools.length === 0) throw new Error("Empty registry");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      console.log(chalk5.red(`  Invalid registry format: ${msg}
+      console.log(ui.error(`Invalid registry format: ${msg}
 `));
       return;
     }
@@ -1253,21 +1477,22 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
     } catch {
     }
     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}
+    console.log(ui.success(`Registry updated: ${tools.length} tools`));
+    console.log(chalk7.dim(`  Saved to: ${registryPath}`));
+    console.log(chalk7.dim(`  Backup: ${backupPath}
 `));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    console.log(chalk5.red(`  Network error: ${msg}`));
-    console.log(chalk5.dim("  Your local registry is still active.\n"));
+    console.log(ui.error(`Network error: ${msg}`));
+    console.log(chalk7.dim("  Your local registry is still active.\n"));
   }
 });
 
 // src/commands/optimize.ts
 import { Command as Command6 } from "commander";
 import { confirm as confirm2 } from "@inquirer/prompts";
-import chalk6 from "chalk";
+import chalk8 from "chalk";
+import ora2 from "ora";
 import fs11 from "fs/promises";
 import path11 from "path";
 
@@ -1462,12 +1687,12 @@ function simpleDiff(oldContent, newContent) {
     const oldLine = oldLines[i];
     const newLine = newLines[i];
     if (oldLine === void 0) {
-      output.push(chalk6.green(`+ ${newLine}`));
+      output.push(chalk8.green(`+ ${newLine}`));
     } else if (newLine === void 0) {
-      output.push(chalk6.red(`- ${oldLine}`));
+      output.push(chalk8.red(`- ${oldLine}`));
     } else if (oldLine !== newLine) {
-      output.push(chalk6.red(`- ${oldLine}`));
-      output.push(chalk6.green(`+ ${newLine}`));
+      output.push(chalk8.red(`- ${oldLine}`));
+      output.push(chalk8.green(`+ ${newLine}`));
     }
   }
   return output;
@@ -1486,7 +1711,7 @@ async function generateDiff(spec, targetDir) {
       results.push({
         path: relativePath,
         status: "new",
-        diff: chalk6.green("+ NEW FILE")
+        diff: chalk8.green("+ NEW FILE")
       });
     } else if (oldContent === newContent) {
       results.push({
@@ -1584,33 +1809,33 @@ ${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").option("--diff", "Preview changes as a diff without writing").option("--runtime <runtime>", "Target runtime (claude-code or hermes)", "claude-code").action(async (options) => {
+  printCompactBanner();
   const config = await loadConfig();
   if (!config) {
-    console.log(
-      chalk6.red("\n  No config found. Run ") + chalk6.bold("kairn init") + chalk6.red(" first.\n")
-    );
+    console.log(ui.errorBox("KAIRN \u2014 Error", "No config found. Run kairn init first."));
     process.exit(1);
   }
   const targetDir = process.cwd();
-  console.log(chalk6.dim("\n  Scanning project..."));
+  console.log(ui.section("Project Scan"));
+  const scanSpinner = ora2({ text: "Scanning project...", indent: 2 }).start();
   const profile = await scanProject(targetDir);
-  console.log(chalk6.cyan("\n  Project Profile\n"));
-  if (profile.language) console.log(chalk6.dim(`  Language:   ${profile.language}`));
-  if (profile.framework) console.log(chalk6.dim(`  Framework:  ${profile.framework}`));
-  console.log(chalk6.dim(`  Dependencies: ${profile.dependencies.length}`));
-  if (profile.testCommand) console.log(chalk6.dim(`  Tests:      ${profile.testCommand}`));
-  if (profile.buildCommand) console.log(chalk6.dim(`  Build:      ${profile.buildCommand}`));
-  if (profile.hasDocker) console.log(chalk6.dim("  Docker:     yes"));
-  if (profile.hasCi) console.log(chalk6.dim("  CI/CD:      yes"));
-  if (profile.envKeys.length > 0) console.log(chalk6.dim(`  Env keys:   ${profile.envKeys.join(", ")}`));
+  scanSpinner.stop();
+  if (profile.language) console.log(ui.kv("Language:", profile.language));
+  if (profile.framework) console.log(ui.kv("Framework:", profile.framework));
+  console.log(ui.kv("Dependencies:", String(profile.dependencies.length)));
+  if (profile.testCommand) console.log(ui.kv("Tests:", profile.testCommand));
+  if (profile.buildCommand) console.log(ui.kv("Build:", profile.buildCommand));
+  if (profile.hasDocker) console.log(ui.kv("Docker:", "yes"));
+  if (profile.hasCi) console.log(ui.kv("CI/CD:", "yes"));
+  if (profile.envKeys.length > 0) console.log(ui.kv("Env keys:", profile.envKeys.join(", ")));
   if (profile.hasClaudeDir) {
-    console.log(chalk6.yellow("\n  Existing .claude/ harness detected\n"));
-    console.log(chalk6.dim(`  CLAUDE.md:  ${profile.claudeMdLineCount} lines${profile.claudeMdLineCount > 200 ? chalk6.yellow(" \u26A0 bloated") : chalk6.green(" \u2713")}`));
-    console.log(chalk6.dim(`  MCP servers: ${profile.mcpServerCount}`));
-    console.log(chalk6.dim(`  Commands:   ${profile.existingCommands.length > 0 ? profile.existingCommands.map((c) => c).join(", ") : "none"}`));
-    console.log(chalk6.dim(`  Rules:      ${profile.existingRules.length > 0 ? profile.existingRules.join(", ") : "none"}`));
-    console.log(chalk6.dim(`  Skills:     ${profile.existingSkills.length > 0 ? profile.existingSkills.join(", ") : "none"}`));
-    console.log(chalk6.dim(`  Agents:     ${profile.existingAgents.length > 0 ? profile.existingAgents.join(", ") : "none"}`));
+    console.log(ui.section("Harness Audit"));
+    console.log(ui.kv("CLAUDE.md:", `${profile.claudeMdLineCount} lines${profile.claudeMdLineCount > 200 ? " \u26A0 bloated" : " \u2713"}`));
+    console.log(ui.kv("MCP servers:", String(profile.mcpServerCount)));
+    console.log(ui.kv("Commands:", profile.existingCommands.length > 0 ? profile.existingCommands.join(", ") : "none"));
+    console.log(ui.kv("Rules:", profile.existingRules.length > 0 ? profile.existingRules.join(", ") : "none"));
+    console.log(ui.kv("Skills:", profile.existingSkills.length > 0 ? profile.existingSkills.join(", ") : "none"));
+    console.log(ui.kv("Agents:", profile.existingAgents.length > 0 ? profile.existingAgents.join(", ") : "none"));
     const issues = [];
     if (profile.claudeMdLineCount > 200) issues.push("CLAUDE.md over 200 lines \u2014 move detail to rules/ or docs/");
     if (!profile.existingCommands.includes("help")) issues.push("Missing /project:help command");
@@ -1624,15 +1849,15 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
     const scopedRules = profile.existingRules.filter((r) => r !== "security" && r !== "continuity");
     if (profile.hasSrc && scopedRules.length === 0) issues.push("No path-scoped rules \u2014 consider adding api.md, testing.md, or frontend.md rules");
     if (issues.length > 0) {
-      console.log(chalk6.yellow("\n  Issues Found:\n"));
+      console.log("");
       for (const issue of issues) {
-        console.log(chalk6.yellow(`    \u26A0 ${issue}`));
+        console.log(ui.warn(issue));
       }
     } else {
-      console.log(chalk6.green("\n  \u2713 No obvious issues found"));
+      console.log(ui.success("No obvious issues found"));
     }
     if (options.auditOnly) {
-      console.log(chalk6.dim("\n  Audit complete. Run without --audit-only to generate optimized environment.\n"));
+      console.log(chalk8.dim("\n  Audit complete. Run without --audit-only to generate optimized environment.\n"));
       return;
     }
     if (!options.yes) {
@@ -1642,71 +1867,66 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
         default: false
       });
       if (!proceed) {
-        console.log(chalk6.dim("\n  Aborted.\n"));
+        console.log(chalk8.dim("\n  Aborted.\n"));
         return;
       }
     }
   } else {
-    console.log(chalk6.dim("\n  No existing .claude/ directory found \u2014 generating from scratch.\n"));
+    console.log(chalk8.dim("\n  No existing .claude/ directory found \u2014 generating from scratch.\n"));
     if (!options.yes) {
       const proceed = await confirm2({
         message: "Generate Claude Code environment for this project?",
         default: true
       });
       if (!proceed) {
-        console.log(chalk6.dim("\n  Aborted.\n"));
+        console.log(chalk8.dim("\n  Aborted.\n"));
         return;
       }
     }
   }
   const intent = buildOptimizeIntent(profile);
   let spec;
+  const spinner = ora2({ text: "Compiling optimized environment...", indent: 2 }).start();
   try {
     spec = await compile(intent, (msg) => {
-      process.stdout.write(`\r  ${chalk6.dim(msg)}                    `);
+      spinner.text = msg;
     });
-    process.stdout.write("\r                                              \r");
+    spinner.succeed("Environment compiled");
   } catch (err) {
-    process.stdout.write("\r                                              \r");
+    spinner.fail("Compilation failed");
     const msg = err instanceof Error ? err.message : String(err);
-    console.log(chalk6.red(`
-  Optimization failed: ${msg}
-`));
+    console.log(ui.errorBox("KAIRN \u2014 Error", `Optimization failed: ${msg}`));
     process.exit(1);
   }
   const registry = await loadRegistry();
   const summary = summarizeSpec(spec, registry);
-  console.log(chalk6.green("  \u2713 Environment compiled\n"));
-  console.log(chalk6.cyan("  Name: ") + spec.name);
-  console.log(chalk6.cyan("  Tools: ") + summary.toolCount);
-  console.log(chalk6.cyan("  Commands: ") + summary.commandCount);
-  console.log(chalk6.cyan("  Rules: ") + summary.ruleCount);
-  console.log(chalk6.cyan("  Skills: ") + summary.skillCount);
-  console.log(chalk6.cyan("  Agents: ") + summary.agentCount);
+  console.log("");
+  console.log(ui.kv("Name:", spec.name));
+  console.log(ui.kv("Tools:", String(summary.toolCount)));
+  console.log(ui.kv("Commands:", String(summary.commandCount)));
+  console.log(ui.kv("Rules:", String(summary.ruleCount)));
+  console.log(ui.kv("Skills:", String(summary.skillCount)));
+  console.log(ui.kv("Agents:", String(summary.agentCount)));
   if (spec.tools.length > 0) {
-    console.log(chalk6.dim("\n  Selected tools:"));
+    console.log(ui.section("Selected Tools"));
     for (const tool of spec.tools) {
       const regTool = registry.find((t) => t.id === tool.tool_id);
       const name = regTool?.name || tool.tool_id;
-      console.log(chalk6.dim(`    - ${name}: ${tool.reason}`));
-    }
-  }
-  if (summary.pluginCommands.length > 0) {
-    console.log(chalk6.yellow("\n  Plugins to install manually:"));
-    for (const cmd of summary.pluginCommands) {
-      console.log(chalk6.yellow(`    ${cmd}`));
+      console.log(ui.tool(name, tool.reason));
     }
   }
   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"));
+      console.log(ui.success("No changes needed \u2014 environment is already up to date."));
+      console.log("");
       return;
     }
-    console.log(chalk6.cyan("\n  Changes preview:\n"));
+    console.log(ui.section("Changes Preview"));
     for (const d of changedDiffs) {
-      console.log(chalk6.cyan(`  --- ${d.path}`));
+      console.log(chalk8.cyan(`
+  --- ${d.path}`));
       if (d.status === "new") {
         console.log(`    ${d.diff}`);
       } else {
@@ -1714,57 +1934,55 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
           console.log(`    ${line}`);
         }
       }
-      console.log("");
     }
+    console.log("");
     const apply = await confirm2({
       message: "Apply these changes?",
       default: true
     });
     if (!apply) {
-      console.log(chalk6.dim("\n  Aborted.\n"));
+      console.log(chalk8.dim("\n  Aborted.\n"));
       return;
     }
   }
   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"));
+    console.log(ui.divider());
+    console.log(ui.success(`Ready! Run: $ hermes`));
+    console.log("");
   } else {
     const written = await writeEnvironment(spec, targetDir);
-    console.log(chalk6.green("\n  \u2713 Environment written\n"));
+    console.log(ui.section("Files Written"));
     for (const file of written) {
-      console.log(chalk6.dim(`    ${file}`));
+      console.log(ui.file(file));
     }
     if (summary.envSetup.length > 0) {
-      console.log(chalk6.yellow("\n  API keys needed (set these environment variables):\n"));
+      console.log(ui.section("Setup Required"));
       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(ui.envVar(env.envVar, env.description, env.signupUrl));
         console.log("");
       }
     }
     if (summary.pluginCommands.length > 0) {
-      console.log(chalk6.yellow("  Install plugins by running these in Claude Code:"));
+      console.log(ui.section("Plugins"));
       for (const cmd of summary.pluginCommands) {
-        console.log(chalk6.bold(`    ${cmd}`));
+        console.log(ui.cmd(cmd));
       }
+      console.log("");
     }
-    console.log(
-      chalk6.cyan("\n  Ready! Run ") + chalk6.bold("claude") + chalk6.cyan(" to start.\n")
-    );
+    console.log(ui.divider());
+    console.log(ui.success("Ready! Run: $ claude"));
+    console.log("");
   }
 });
 
 // src/commands/doctor.ts
 import { Command as Command7 } from "commander";
-import chalk7 from "chalk";
+import chalk9 from "chalk";
 function runChecks(profile) {
   const checks = [];
   if (!profile.existingClaudeMd) {
@@ -1894,21 +2112,28 @@ function runChecks(profile) {
 var doctorCommand = new Command7("doctor").description(
   "Validate the current Claude Code environment against best practices"
 ).action(async () => {
+  printFullBanner("Doctor");
   const targetDir = process.cwd();
-  console.log(chalk7.dim("\n  Checking .claude/ environment...\n"));
+  console.log(chalk9.dim("  Checking .claude/ environment...\n"));
   const profile = await scanProject(targetDir);
   if (!profile.hasClaudeDir) {
-    console.log(chalk7.red("  \u274C No .claude/ directory found.\n"));
+    console.log(ui.error("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")
+      chalk9.dim("  Run ") + chalk9.bold("kairn describe") + chalk9.dim(" or ") + chalk9.bold("kairn optimize") + chalk9.dim(" to generate one.\n")
     );
     process.exit(1);
   }
   const checks = runChecks(profile);
+  console.log(ui.section("Health Check"));
+  console.log("");
   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}`);
+    if (check.status === "pass") {
+      console.log(ui.success(`${check.name}: ${check.message}`));
+    } else if (check.status === "warn") {
+      console.log(ui.warn(`${check.name}: ${check.message}`));
+    } else {
+      console.log(ui.error(`${check.name}: ${check.message}`));
+    }
   }
   const maxScore = checks.reduce((sum, c) => sum + c.weight, 0);
   const score = checks.reduce((sum, c) => {
@@ -1917,7 +2142,7 @@ var doctorCommand = new Command7("doctor").description(
     return sum;
   }, 0);
   const percentage = Math.round(score / maxScore * 100);
-  const scoreColor = percentage >= 80 ? chalk7.green : percentage >= 50 ? chalk7.yellow : chalk7.red;
+  const scoreColor = percentage >= 80 ? chalk9.green : percentage >= 50 ? chalk9.yellow : chalk9.red;
   console.log(
     `
   Score: ${scoreColor(`${score}/${maxScore}`)} (${scoreColor(`${percentage}%`)})
@@ -1925,24 +2150,24 @@ var doctorCommand = new Command7("doctor").description(
   );
   if (percentage < 80) {
     console.log(
-      chalk7.dim("  Run ") + chalk7.bold("kairn optimize") + chalk7.dim(" to fix issues.\n")
+      chalk9.dim("  Run ") + chalk9.bold("kairn optimize") + chalk9.dim(" to fix issues.\n")
     );
   }
 });
 
 // src/commands/registry.ts
 import { Command as Command8 } from "commander";
-import chalk8 from "chalk";
+import chalk10 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) => {
+  printCompactBanner();
   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}
+    console.log(ui.error(`Failed to load registry: ${msg}
 `));
     process.exit(1);
   }
@@ -1957,12 +2182,13 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
     );
   }
   if (tools.length === 0) {
-    console.log(chalk8.dim("\n  No tools found.\n"));
+    console.log(chalk10.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"));
+  console.log(ui.section("Registry Tools"));
+  console.log("");
   for (const tool of tools) {
     const isUser = userIds.has(tool.id);
     const meta = [
@@ -1970,13 +2196,13 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
       `tier ${tool.tier}`,
       tool.auth
     ].join(", ");
-    console.log(chalk8.bold(`  ${tool.id}`) + chalk8.dim(` (${meta})`));
-    console.log(chalk8.dim(`    ${tool.description}`));
+    console.log(`  ${ui.accent(tool.id)}` + chalk10.dim(` (${meta})`));
+    console.log(chalk10.dim(`    ${tool.description}`));
     if (tool.best_for.length > 0) {
-      console.log(chalk8.dim(`    Best for: ${tool.best_for.join(", ")}`));
+      console.log(chalk10.dim(`    Best for: ${tool.best_for.join(", ")}`));
     }
     if (isUser) {
-      console.log(chalk8.yellow("    [USER-DEFINED]"));
+      console.log(chalk10.yellow("    [USER-DEFINED]"));
     }
     console.log("");
   }
@@ -1984,7 +2210,7 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
   const shownUser = tools.filter((t) => userIds.has(t.id)).length;
   const shownBundled = totalShown - shownUser;
   console.log(
-    chalk8.dim(
+    chalk10.dim(
       `  ${totalShown} tool${totalShown !== 1 ? "s" : ""} (${shownBundled} bundled, ${shownUser} user-defined)`
     ) + "\n"
   );
@@ -2082,26 +2308,24 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
       ...env_vars.length > 0 ? { env_vars } : {},
       ...signup_url ? { signup_url } : {}
     };
-    let userTools;
+    let userToolsList;
     try {
-      userTools = await loadUserRegistry();
+      userToolsList = await loadUserRegistry();
     } catch {
-      userTools = [];
+      userToolsList = [];
     }
-    const existingIdx = userTools.findIndex((t) => t.id === id);
+    const existingIdx = userToolsList.findIndex((t) => t.id === id);
     if (existingIdx >= 0) {
-      userTools[existingIdx] = tool;
+      userToolsList[existingIdx] = tool;
     } else {
-      userTools.push(tool);
+      userToolsList.push(tool);
     }
-    await saveUserRegistry(userTools);
-    console.log(chalk8.green(`
-  \u2713 Tool ${id} added to user registry
+    await saveUserRegistry(userToolsList);
+    console.log(ui.success(`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}
+    console.log(ui.error(`Failed to add tool: ${msg}
 `));
     process.exit(1);
   }
@@ -2110,19 +2334,20 @@ var registryCommand = new Command8("registry").description("Manage the tool regi
 
 // src/commands/templates.ts
 import { Command as Command9 } from "commander";
-import chalk9 from "chalk";
+import chalk11 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) => {
+  printCompactBanner();
   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(
+      chalk11.dim(
+        "  No templates found. Templates will be installed with "
+      ) + chalk11.bold("kairn init") + chalk11.dim(
         " or you can add .json files to ~/.kairn/templates/\n"
       )
     );
@@ -2131,9 +2356,9 @@ var templatesCommand = new Command9("templates").description("Browse available t
   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(
+      chalk11.dim(
+        "  No templates found. Templates will be installed with "
+      ) + chalk11.bold("kairn init") + chalk11.dim(
         " or you can add .json files to ~/.kairn/templates/\n"
       )
     );
@@ -2161,30 +2386,27 @@ var templatesCommand = new Command9("templates").description("Browse available t
   }
   if (filtered.length === 0) {
     console.log(
-      chalk9.dim(`
-  No templates matched category "${options.category}".
+      chalk11.dim(`  No templates matched category "${options.category}".
 `)
     );
     return;
   }
-  console.log(chalk9.cyan("\n  Available Templates\n"));
+  console.log(ui.section("Templates"));
+  console.log("");
   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(ui.kv("Name", chalk11.bold(spec.name)));
+    console.log(ui.kv("ID", chalk11.dim(spec.id)));
+    console.log(ui.kv("Description", spec.description));
     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}`
-      )
+      ui.kv("Contents", `${toolCount} tools \xB7 ${commandCount} commands \xB7 ${ruleCount} rules`)
     );
     console.log("");
   }
   console.log(
-    chalk9.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
+    chalk11.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
 `)
   );
 });
@@ -2193,7 +2415,7 @@ var templatesCommand = new Command9("templates").description("Browse available t
 var program = new Command10();
 program.name("kairn").description(
   "Compile natural language intent into optimized Claude Code environments"
-).version("1.5.1");
+).version("1.7.0").option("--no-color", "Disable colored output");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);
@@ -2203,5 +2425,8 @@ program.addCommand(updateRegistryCommand);
 program.addCommand(doctorCommand);
 program.addCommand(registryCommand);
 program.addCommand(templatesCommand);
+if (process.argv.includes("--no-color") || process.env.NO_COLOR) {
+  chalk12.level = 0;
+}
 program.parse();
 //# sourceMappingURL=cli.js.map