kairn-cli 1.6.0 → 1.8.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 // src/cli.ts
-import { Command as Command10 } from "commander";
-import chalk12 from "chalk";
+import { Command as Command11 } from "commander";
+import chalk14 from "chalk";
 
 // src/commands/init.ts
 import { Command } from "commander";
@@ -90,7 +90,7 @@ var ui = {
   // Key-value pairs
   kv: (key, value) => `  ${chalk.cyan(key.padEnd(14))} ${value}`,
   // File list
-  file: (path13) => chalk.dim(`    ${path13}`),
+  file: (path15) => chalk.dim(`    ${path15}`),
   // Tool display
   tool: (name, reason) => `    ${warm("\u25CF")} ${chalk.bold(name)}
       ${chalk.dim(reason)}`,
@@ -339,7 +339,7 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
 // src/commands/describe.ts
 import { Command as Command2 } from "commander";
 import { input, confirm } from "@inquirer/prompts";
-import chalk4 from "chalk";
+import chalk5 from "chalk";
 import ora from "ora";
 
 // src/compiler/compile.ts
@@ -362,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}
@@ -392,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.
@@ -410,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
 
@@ -530,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.
@@ -558,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
 
@@ -565,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
 
@@ -593,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"],
@@ -608,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",
@@ -882,20 +919,48 @@ async function generateClarifications(intent, onProgress) {
 // 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;
+}
+var ENV_LOADER_HOOK = {
+  matcher: "",
+  hooks: [{
+    type: "command",
+    command: 'if [ -f .env ] && [ -n "$CLAUDE_ENV_FILE" ]; then grep -v "^#" .env | grep -v "^$" | grep "=" >> "$CLAUDE_ENV_FILE"; fi'
+  }]
+};
+function resolveSettings(spec, options) {
+  const settings = spec.harness.settings;
+  const base = settings && Object.keys(settings).length > 0 ? { ...settings } : {};
+  if (!("statusLine" in base) && isCodeProject(spec)) {
+    base.statusLine = STATUS_LINE;
+  }
+  if (options?.hasEnvVars) {
+    const hooks = base.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    sessionStart.push(ENV_LOADER_HOOK);
+    hooks.SessionStart = sessionStart;
+    base.hooks = hooks;
+  }
+  if (Object.keys(base).length === 0) return null;
+  return base;
+}
 async function writeFile(filePath, content) {
   await fs5.mkdir(path5.dirname(filePath), { recursive: true });
   await fs5.writeFile(filePath, content, "utf-8");
 }
-function buildFileMap(spec) {
+function buildFileMap(spec, options) {
   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)
-    );
+  const resolvedSettings = resolveSettings(spec, options);
+  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(
@@ -930,7 +995,7 @@ function buildFileMap(spec) {
   }
   return files;
 }
-async function writeEnvironment(spec, targetDir) {
+async function writeEnvironment(spec, targetDir, options) {
   const claudeDir = path5.join(targetDir, ".claude");
   const written = [];
   if (spec.harness.claude_md) {
@@ -938,9 +1003,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, options);
+  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) {
@@ -1140,6 +1206,114 @@ async function writeHermesEnvironment(spec, registry) {
   return written;
 }
 
+// src/secrets.ts
+import { password as password2 } from "@inquirer/prompts";
+import chalk4 from "chalk";
+import fs7 from "fs/promises";
+import path7 from "path";
+async function collectAndWriteKeys(envSetup, targetDir) {
+  console.log(ui.section("API Keys"));
+  console.log(
+    chalk4.dim("  Some tools need API keys. Enter them now or press Enter to skip.\n")
+  );
+  const envEntries = [
+    "# Generated by Kairn \u2014 API keys for MCP servers",
+    "# Do NOT commit this file to git",
+    ""
+  ];
+  let keysEntered = 0;
+  let keysSkipped = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const env of envSetup) {
+    if (seen.has(env.envVar)) continue;
+    seen.add(env.envVar);
+    console.log(chalk4.bold(`  ${env.envVar}`) + chalk4.dim(` (${env.toolName})`));
+    if (env.signupUrl) {
+      console.log(chalk4.dim(`    Get one at: ${env.signupUrl}`));
+    }
+    const value = await password2({
+      message: env.envVar,
+      mask: "\u2022"
+    });
+    if (value && value.trim()) {
+      envEntries.push(`${env.envVar}=${value.trim()}`);
+      console.log(chalk4.green("  \u2713 saved\n"));
+      keysEntered++;
+    } else {
+      envEntries.push(`${env.envVar}=`);
+      console.log(chalk4.dim("  (skipped)\n"));
+      keysSkipped++;
+    }
+  }
+  const envPath = path7.join(targetDir, ".env");
+  await fs7.writeFile(envPath, envEntries.join("\n") + "\n", "utf-8");
+  await ensureGitignoreEntry(targetDir, ".env");
+  console.log(chalk4.green(`  \u2713 ${keysEntered} key(s) saved to .env (gitignored)`));
+  if (keysSkipped > 0) {
+    console.log(chalk4.dim("  Skipped keys can be added later: kairn keys"));
+  }
+  return { keysEntered, keysSkipped, envPath };
+}
+async function writeEmptyEnvFile(envSetup, targetDir) {
+  const envEntries = [
+    "# Generated by Kairn \u2014 API keys for MCP servers",
+    "# Do NOT commit this file to git",
+    ""
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const env of envSetup) {
+    if (seen.has(env.envVar)) continue;
+    seen.add(env.envVar);
+    envEntries.push(`${env.envVar}=`);
+  }
+  const envPath = path7.join(targetDir, ".env");
+  await fs7.writeFile(envPath, envEntries.join("\n") + "\n", "utf-8");
+  await ensureGitignoreEntry(targetDir, ".env");
+}
+async function ensureGitignoreEntry(targetDir, entry) {
+  const gitignorePath = path7.join(targetDir, ".gitignore");
+  let gitignore = "";
+  try {
+    gitignore = await fs7.readFile(gitignorePath, "utf-8");
+  } catch {
+  }
+  if (!gitignore.split("\n").some((line) => line.trim() === entry)) {
+    const separator = gitignore.length > 0 && !gitignore.endsWith("\n") ? "\n" : "";
+    await fs7.writeFile(gitignorePath, gitignore + separator + entry + "\n", "utf-8");
+  }
+}
+async function readEnvFile(targetDir) {
+  const envPath = path7.join(targetDir, ".env");
+  const entries = /* @__PURE__ */ new Map();
+  try {
+    const content = await fs7.readFile(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex === -1) continue;
+      const key = trimmed.slice(0, eqIndex);
+      const value = trimmed.slice(eqIndex + 1);
+      entries.set(key, value);
+    }
+  } catch {
+  }
+  return entries;
+}
+async function detectRequiredEnvVars(targetDir) {
+  const mcpPath = path7.join(targetDir, ".mcp.json");
+  const envVars = /* @__PURE__ */ new Set();
+  try {
+    const content = await fs7.readFile(mcpPath, "utf-8");
+    const matches = content.matchAll(/\$\{([A-Z_][A-Z0-9_]*)\}/g);
+    for (const match of matches) {
+      envVars.add(match[1]);
+    }
+  } catch {
+  }
+  return [...envVars];
+}
+
 // 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("-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");
@@ -1148,7 +1322,7 @@ var describeCommand = new Command2("describe").description("Describe your workfl
     console.log(
       ui.errorBox(
         "No configuration found",
-        `Run ${chalk4.bold("kairn init")} to set up your API key.`
+        `Run ${chalk5.bold("kairn init")} to set up your API key.`
       )
     );
     process.exit(1);
@@ -1157,14 +1331,14 @@ var describeCommand = new Command2("describe").description("Describe your workfl
     message: "What do you want your agent to do?"
   });
   if (!intentRaw.trim()) {
-    console.log(chalk4.red("\n  No description provided. Aborting.\n"));
+    console.log(chalk5.red("\n  No description provided. Aborting.\n"));
     process.exit(1);
   }
   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"));
+    console.log(chalk5.dim("  Let me understand your project better."));
+    console.log(chalk5.dim("  Press Enter to accept the suggestion, or type your own answer.\n"));
     let clarifications = [];
     try {
       clarifications = await generateClarifications(intentRaw);
@@ -1197,7 +1371,7 @@ ${clarificationLines}`;
   } catch (err) {
     spinner.fail("Compilation failed");
     const msg = err instanceof Error ? err.message : String(err);
-    console.log(chalk4.red(`
+    console.log(chalk5.red(`
   ${msg}
 `));
     process.exit(1);
@@ -1227,7 +1401,7 @@ ${clarificationLines}`;
     default: true
   });
   if (!proceed) {
-    console.log(chalk4.dim("\n  Aborted. Environment saved to ~/.kairn/envs/\n"));
+    console.log(chalk5.dim("\n  Aborted. Environment saved to ~/.kairn/envs/\n"));
     return;
   }
   const targetDir = process.cwd();
@@ -1236,25 +1410,24 @@ ${clarificationLines}`;
     await writeHermesEnvironment(spec, registry);
     console.log("\n" + ui.success("Environment written for Hermes"));
     console.log(
-      chalk4.cyan("\n  Ready! Run ") + chalk4.bold("hermes") + chalk4.cyan(" to start.\n")
+      chalk5.cyan("\n  Ready! Run ") + chalk5.bold("hermes") + chalk5.cyan(" to start.\n")
     );
   } else {
-    const written = await writeEnvironment(spec, targetDir);
+    const hasEnvVars = summary.envSetup.length > 0;
+    const written = await writeEnvironment(spec, targetDir, { hasEnvVars });
     console.log(ui.section("Files Written"));
     console.log("");
     for (const file of written) {
       console.log(ui.file(file));
     }
-    if (summary.envSetup.length > 0) {
-      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(ui.envVar(env.envVar, env.description, env.signupUrl));
-        console.log("");
+    if (hasEnvVars) {
+      if (options.quick) {
+        await writeEmptyEnvFile(summary.envSetup, targetDir);
+        console.log(ui.success("Empty .env written (gitignored) \u2014 fill in keys later: kairn keys"));
+      } else {
+        await collectAndWriteKeys(summary.envSetup, targetDir);
       }
+      console.log("");
     }
     if (summary.pluginCommands.length > 0) {
       console.log(ui.section("Plugins"));
@@ -1272,28 +1445,28 @@ ${clarificationLines}`;
 
 // src/commands/list.ts
 import { Command as Command3 } from "commander";
-import chalk5 from "chalk";
-import fs7 from "fs/promises";
-import path7 from "path";
+import chalk6 from "chalk";
+import fs8 from "fs/promises";
+import path8 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);
+    files = await fs8.readdir(envsDir);
   } catch {
-    console.log(chalk5.dim("  No environments yet. Run ") + chalk5.bold("kairn describe") + chalk5.dim(" to create one.\n"));
+    console.log(chalk6.dim("  No environments yet. Run ") + chalk6.bold("kairn describe") + chalk6.dim(" to create one.\n"));
     return;
   }
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   if (jsonFiles.length === 0) {
-    console.log(chalk5.dim("  No environments yet. Run ") + chalk5.bold("kairn describe") + chalk5.dim(" to create one.\n"));
+    console.log(chalk6.dim("  No environments yet. Run ") + chalk6.bold("kairn describe") + chalk6.dim(" to create one.\n"));
     return;
   }
   let first = true;
   for (const file of jsonFiles) {
     try {
-      const data = await fs7.readFile(path7.join(envsDir, file), "utf-8");
+      const data = await fs8.readFile(path8.join(envsDir, file), "utf-8");
       const spec = JSON.parse(data);
       const date = new Date(spec.created_at).toLocaleDateString();
       const toolCount = spec.tools?.length ?? 0;
@@ -1301,10 +1474,10 @@ var listCommand = new Command3("list").description("Show saved environments").ac
         console.log(ui.divider());
       }
       first = false;
-      console.log(ui.kv("Name", chalk5.bold(spec.name)));
+      console.log(ui.kv("Name", chalk6.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(ui.kv("ID", chalk6.dim(spec.id)));
       console.log("");
     } catch {
     }
@@ -1313,9 +1486,9 @@ var listCommand = new Command3("list").description("Show saved environments").ac
 
 // src/commands/activate.ts
 import { Command as Command4 } from "commander";
-import chalk6 from "chalk";
-import fs8 from "fs/promises";
-import path8 from "path";
+import chalk7 from "chalk";
+import fs9 from "fs/promises";
+import path9 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();
@@ -1325,7 +1498,7 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
   let fromTemplate = false;
   let envFiles = [];
   try {
-    envFiles = await fs8.readdir(envsDir);
+    envFiles = await fs9.readdir(envsDir);
   } catch {
   }
   match = envFiles.find(
@@ -1336,7 +1509,7 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
   } else {
     let templateFiles = [];
     try {
-      templateFiles = await fs8.readdir(templatesDir);
+      templateFiles = await fs9.readdir(templatesDir);
     } catch {
     }
     match = templateFiles.find(
@@ -1347,16 +1520,16 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
       fromTemplate = true;
     } else {
       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"));
+      console.log(chalk7.dim("  Run kairn list to see saved environments."));
+      console.log(chalk7.dim("  Run kairn templates to see available templates.\n"));
       process.exit(1);
     }
   }
-  const data = await fs8.readFile(path8.join(sourceDir, match), "utf-8");
+  const data = await fs9.readFile(path9.join(sourceDir, match), "utf-8");
   const spec = JSON.parse(data);
-  const label = fromTemplate ? chalk6.dim(" (template)") : "";
-  console.log(chalk6.cyan(`  Activating: ${spec.name}`) + label);
-  console.log(chalk6.dim(`  ${spec.description}
+  const label = fromTemplate ? chalk7.dim(" (template)") : "";
+  console.log(chalk7.cyan(`  Activating: ${spec.name}`) + label);
+  console.log(chalk7.dim(`  ${spec.description}
 `));
   const targetDir = process.cwd();
   const written = await writeEnvironment(spec, targetDir);
@@ -1369,22 +1542,22 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
 
 // src/commands/update-registry.ts
 import { Command as Command5 } from "commander";
-import chalk7 from "chalk";
-import fs9 from "fs/promises";
-import path9 from "path";
+import chalk8 from "chalk";
+import fs10 from "fs/promises";
+import path10 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 __filename3 = fileURLToPath3(import.meta.url);
-  const __dirname3 = path9.dirname(__filename3);
+  const __dirname3 = path10.dirname(__filename3);
   const candidates = [
-    path9.resolve(__dirname3, "../registry/tools.json"),
-    path9.resolve(__dirname3, "../src/registry/tools.json"),
-    path9.resolve(__dirname3, "../../src/registry/tools.json")
+    path10.resolve(__dirname3, "../registry/tools.json"),
+    path10.resolve(__dirname3, "../src/registry/tools.json"),
+    path10.resolve(__dirname3, "../../src/registry/tools.json")
   ];
   for (const candidate of candidates) {
     try {
-      await fs9.access(candidate);
+      await fs10.access(candidate);
       return candidate;
     } catch {
       continue;
@@ -1395,15 +1568,15 @@ async function getLocalRegistryPath() {
 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(chalk7.dim(`  Fetching registry from ${url}...`));
+  console.log(chalk8.dim(`  Fetching registry from ${url}...`));
   try {
     const response = await fetch(url);
     if (!response.ok) {
       console.log(
         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"));
+      console.log(chalk8.dim("  The remote registry may not be available yet."));
+      console.log(chalk8.dim("  Your local registry is still active.\n"));
       return;
     }
     const text = await response.text();
@@ -1421,35 +1594,35 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
     const registryPath = await getLocalRegistryPath();
     const backupPath = registryPath + ".bak";
     try {
-      await fs9.copyFile(registryPath, backupPath);
+      await fs10.copyFile(registryPath, backupPath);
     } catch {
     }
-    await fs9.writeFile(registryPath, JSON.stringify(tools, null, 2), "utf-8");
+    await fs10.writeFile(registryPath, JSON.stringify(tools, null, 2), "utf-8");
     console.log(ui.success(`Registry updated: ${tools.length} tools`));
-    console.log(chalk7.dim(`  Saved to: ${registryPath}`));
-    console.log(chalk7.dim(`  Backup: ${backupPath}
+    console.log(chalk8.dim(`  Saved to: ${registryPath}`));
+    console.log(chalk8.dim(`  Backup: ${backupPath}
 `));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.log(ui.error(`Network error: ${msg}`));
-    console.log(chalk7.dim("  Your local registry is still active.\n"));
+    console.log(chalk8.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 chalk8 from "chalk";
+import chalk9 from "chalk";
 import ora2 from "ora";
-import fs11 from "fs/promises";
-import path11 from "path";
+import fs12 from "fs/promises";
+import path12 from "path";
 
 // src/scanner/scan.ts
-import fs10 from "fs/promises";
-import path10 from "path";
+import fs11 from "fs/promises";
+import path11 from "path";
 async function fileExists(p) {
   try {
-    await fs10.access(p);
+    await fs11.access(p);
     return true;
   } catch {
     return false;
@@ -1457,7 +1630,7 @@ async function fileExists(p) {
 }
 async function readJsonSafe(p) {
   try {
-    const data = await fs10.readFile(p, "utf-8");
+    const data = await fs11.readFile(p, "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
@@ -1465,14 +1638,14 @@ async function readJsonSafe(p) {
 }
 async function readFileSafe(p) {
   try {
-    return await fs10.readFile(p, "utf-8");
+    return await fs11.readFile(p, "utf-8");
   } catch {
     return null;
   }
 }
 async function listDirSafe(p) {
   try {
-    const entries = await fs10.readdir(p);
+    const entries = await fs11.readdir(p);
     return entries.filter((e) => !e.startsWith("."));
   } catch {
     return [];
@@ -1524,7 +1697,7 @@ function extractEnvKeys(content) {
   return keys;
 }
 async function scanProject(dir) {
-  const pkg = await readJsonSafe(path10.join(dir, "package.json"));
+  const pkg = await readJsonSafe(path11.join(dir, "package.json"));
   const deps = pkg?.dependencies ? Object.keys(pkg.dependencies) : [];
   const devDeps = pkg?.devDependencies ? Object.keys(pkg.devDependencies) : [];
   const allDeps = [...deps, ...devDeps];
@@ -1552,19 +1725,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(path10.join(dir, "tests")) || await fileExists(path10.join(dir, "__tests__")) || await fileExists(path10.join(dir, "test"));
+  const hasTests = testCommand !== null || await fileExists(path11.join(dir, "tests")) || await fileExists(path11.join(dir, "__tests__")) || await fileExists(path11.join(dir, "test"));
   const buildCommand = scripts.build || null;
   const lintCommand = scripts.lint || null;
-  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"));
+  const hasSrc = await fileExists(path11.join(dir, "src"));
+  const hasDocker = await fileExists(path11.join(dir, "docker-compose.yml")) || await fileExists(path11.join(dir, "Dockerfile"));
+  const hasCi = await fileExists(path11.join(dir, ".github/workflows"));
+  const hasEnvFile = await fileExists(path11.join(dir, ".env")) || await fileExists(path11.join(dir, ".env.example"));
   let envKeys = [];
-  const envExample = await readFileSafe(path10.join(dir, ".env.example"));
+  const envExample = await readFileSafe(path11.join(dir, ".env.example"));
   if (envExample) {
     envKeys = extractEnvKeys(envExample);
   }
-  const claudeDir = path10.join(dir, ".claude");
+  const claudeDir = path11.join(dir, ".claude");
   const hasClaudeDir = await fileExists(claudeDir);
   let existingClaudeMd = null;
   let existingSettings = null;
@@ -1576,21 +1749,21 @@ async function scanProject(dir) {
   let mcpServerCount = 0;
   let claudeMdLineCount = 0;
   if (hasClaudeDir) {
-    existingClaudeMd = await readFileSafe(path10.join(claudeDir, "CLAUDE.md"));
+    existingClaudeMd = await readFileSafe(path11.join(claudeDir, "CLAUDE.md"));
     if (existingClaudeMd) {
       claudeMdLineCount = existingClaudeMd.split("\n").length;
     }
-    existingSettings = await readJsonSafe(path10.join(claudeDir, "settings.json"));
-    existingMcpConfig = await readJsonSafe(path10.join(dir, ".mcp.json"));
+    existingSettings = await readJsonSafe(path11.join(claudeDir, "settings.json"));
+    existingMcpConfig = await readJsonSafe(path11.join(dir, ".mcp.json"));
     if (existingMcpConfig?.mcpServers) {
       mcpServerCount = Object.keys(existingMcpConfig.mcpServers).length;
     }
-    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", ""));
+    existingCommands = (await listDirSafe(path11.join(claudeDir, "commands"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingRules = (await listDirSafe(path11.join(claudeDir, "rules"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingSkills = await listDirSafe(path11.join(claudeDir, "skills"));
+    existingAgents = (await listDirSafe(path11.join(claudeDir, "agents"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
   }
-  const name = pkg?.name || path10.basename(dir);
+  const name = pkg?.name || path11.basename(dir);
   const description = pkg?.description || "";
   return {
     name,
@@ -1635,31 +1808,31 @@ function simpleDiff(oldContent, newContent) {
     const oldLine = oldLines[i];
     const newLine = newLines[i];
     if (oldLine === void 0) {
-      output.push(chalk8.green(`+ ${newLine}`));
+      output.push(chalk9.green(`+ ${newLine}`));
     } else if (newLine === void 0) {
-      output.push(chalk8.red(`- ${oldLine}`));
+      output.push(chalk9.red(`- ${oldLine}`));
     } else if (oldLine !== newLine) {
-      output.push(chalk8.red(`- ${oldLine}`));
-      output.push(chalk8.green(`+ ${newLine}`));
+      output.push(chalk9.red(`- ${oldLine}`));
+      output.push(chalk9.green(`+ ${newLine}`));
     }
   }
   return output;
 }
-async function generateDiff(spec, targetDir) {
-  const fileMap = buildFileMap(spec);
+async function generateDiff(spec, targetDir, options) {
+  const fileMap = buildFileMap(spec, options);
   const results = [];
   for (const [relativePath, newContent] of fileMap) {
-    const absolutePath = path11.join(targetDir, relativePath);
+    const absolutePath = path12.join(targetDir, relativePath);
     let oldContent = null;
     try {
-      oldContent = await fs11.readFile(absolutePath, "utf-8");
+      oldContent = await fs12.readFile(absolutePath, "utf-8");
     } catch {
     }
     if (oldContent === null) {
       results.push({
         path: relativePath,
         status: "new",
-        diff: chalk8.green("+ NEW FILE")
+        diff: chalk9.green("+ NEW FILE")
       });
     } else if (oldContent === newContent) {
       results.push({
@@ -1805,7 +1978,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       console.log(ui.success("No obvious issues found"));
     }
     if (options.auditOnly) {
-      console.log(chalk8.dim("\n  Audit complete. Run without --audit-only to generate optimized environment.\n"));
+      console.log(chalk9.dim("\n  Audit complete. Run without --audit-only to generate optimized environment.\n"));
       return;
     }
     if (!options.yes) {
@@ -1815,19 +1988,19 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
         default: false
       });
       if (!proceed) {
-        console.log(chalk8.dim("\n  Aborted.\n"));
+        console.log(chalk9.dim("\n  Aborted.\n"));
         return;
       }
     }
   } else {
-    console.log(chalk8.dim("\n  No existing .claude/ directory found \u2014 generating from scratch.\n"));
+    console.log(chalk9.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(chalk8.dim("\n  Aborted.\n"));
+        console.log(chalk9.dim("\n  Aborted.\n"));
         return;
       }
     }
@@ -1863,8 +2036,9 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       console.log(ui.tool(name, tool.reason));
     }
   }
+  const hasEnvVars = summary.envSetup.length > 0;
   if (options.diff) {
-    const diffs = await generateDiff(spec, targetDir);
+    const diffs = await generateDiff(spec, targetDir, { hasEnvVars });
     const changedDiffs = diffs.filter((d) => d.status !== "unchanged");
     if (changedDiffs.length === 0) {
       console.log(ui.success("No changes needed \u2014 environment is already up to date."));
@@ -1873,7 +2047,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
     }
     console.log(ui.section("Changes Preview"));
     for (const d of changedDiffs) {
-      console.log(chalk8.cyan(`
+      console.log(chalk9.cyan(`
   --- ${d.path}`));
       if (d.status === "new") {
         console.log(`    ${d.diff}`);
@@ -1889,7 +2063,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       default: true
     });
     if (!apply) {
-      console.log(chalk8.dim("\n  Aborted.\n"));
+      console.log(chalk9.dim("\n  Aborted.\n"));
       return;
     }
   }
@@ -1900,20 +2074,14 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
     console.log(ui.success(`Ready! Run: $ hermes`));
     console.log("");
   } else {
-    const written = await writeEnvironment(spec, targetDir);
+    const written = await writeEnvironment(spec, targetDir, { hasEnvVars });
     console.log(ui.section("Files Written"));
     for (const file of written) {
       console.log(ui.file(file));
     }
-    if (summary.envSetup.length > 0) {
-      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(ui.envVar(env.envVar, env.description, env.signupUrl));
-        console.log("");
-      }
+    if (hasEnvVars) {
+      await collectAndWriteKeys(summary.envSetup, targetDir);
+      console.log("");
     }
     if (summary.pluginCommands.length > 0) {
       console.log(ui.section("Plugins"));
@@ -1930,7 +2098,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
 
 // src/commands/doctor.ts
 import { Command as Command7 } from "commander";
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function runChecks(profile) {
   const checks = [];
   if (!profile.existingClaudeMd) {
@@ -2062,12 +2230,12 @@ var doctorCommand = new Command7("doctor").description(
 ).action(async () => {
   printFullBanner("Doctor");
   const targetDir = process.cwd();
-  console.log(chalk9.dim("  Checking .claude/ environment...\n"));
+  console.log(chalk10.dim("  Checking .claude/ environment...\n"));
   const profile = await scanProject(targetDir);
   if (!profile.hasClaudeDir) {
     console.log(ui.error("No .claude/ directory found.\n"));
     console.log(
-      chalk9.dim("  Run ") + chalk9.bold("kairn describe") + chalk9.dim(" or ") + chalk9.bold("kairn optimize") + chalk9.dim(" to generate one.\n")
+      chalk10.dim("  Run ") + chalk10.bold("kairn describe") + chalk10.dim(" or ") + chalk10.bold("kairn optimize") + chalk10.dim(" to generate one.\n")
     );
     process.exit(1);
   }
@@ -2090,7 +2258,7 @@ var doctorCommand = new Command7("doctor").description(
     return sum;
   }, 0);
   const percentage = Math.round(score / maxScore * 100);
-  const scoreColor = percentage >= 80 ? chalk9.green : percentage >= 50 ? chalk9.yellow : chalk9.red;
+  const scoreColor = percentage >= 80 ? chalk10.green : percentage >= 50 ? chalk10.yellow : chalk10.red;
   console.log(
     `
   Score: ${scoreColor(`${score}/${maxScore}`)} (${scoreColor(`${percentage}%`)})
@@ -2098,14 +2266,14 @@ var doctorCommand = new Command7("doctor").description(
   );
   if (percentage < 80) {
     console.log(
-      chalk9.dim("  Run ") + chalk9.bold("kairn optimize") + chalk9.dim(" to fix issues.\n")
+      chalk10.dim("  Run ") + chalk10.bold("kairn optimize") + chalk10.dim(" to fix issues.\n")
     );
   }
 });
 
 // src/commands/registry.ts
 import { Command as Command8 } from "commander";
-import chalk10 from "chalk";
+import chalk11 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();
@@ -2130,7 +2298,7 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
     );
   }
   if (tools.length === 0) {
-    console.log(chalk10.dim("\n  No tools found.\n"));
+    console.log(chalk11.dim("\n  No tools found.\n"));
     return;
   }
   const bundledCount = all.filter((t) => !userIds.has(t.id)).length;
@@ -2144,13 +2312,13 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
       `tier ${tool.tier}`,
       tool.auth
     ].join(", ");
-    console.log(`  ${ui.accent(tool.id)}` + chalk10.dim(` (${meta})`));
-    console.log(chalk10.dim(`    ${tool.description}`));
+    console.log(`  ${ui.accent(tool.id)}` + chalk11.dim(` (${meta})`));
+    console.log(chalk11.dim(`    ${tool.description}`));
     if (tool.best_for.length > 0) {
-      console.log(chalk10.dim(`    Best for: ${tool.best_for.join(", ")}`));
+      console.log(chalk11.dim(`    Best for: ${tool.best_for.join(", ")}`));
     }
     if (isUser) {
-      console.log(chalk10.yellow("    [USER-DEFINED]"));
+      console.log(chalk11.yellow("    [USER-DEFINED]"));
     }
     console.log("");
   }
@@ -2158,7 +2326,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(
-    chalk10.dim(
+    chalk11.dim(
       `  ${totalShown} tool${totalShown !== 1 ? "s" : ""} (${shownBundled} bundled, ${shownUser} user-defined)`
     ) + "\n"
   );
@@ -2282,20 +2450,20 @@ var registryCommand = new Command8("registry").description("Manage the tool regi
 
 // src/commands/templates.ts
 import { Command as Command9 } from "commander";
-import chalk11 from "chalk";
-import fs12 from "fs/promises";
-import path12 from "path";
+import chalk12 from "chalk";
+import fs13 from "fs/promises";
+import path13 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);
+    files = await fs13.readdir(templatesDir);
   } catch {
     console.log(
-      chalk11.dim(
+      chalk12.dim(
         "  No templates found. Templates will be installed with "
-      ) + chalk11.bold("kairn init") + chalk11.dim(
+      ) + chalk12.bold("kairn init") + chalk12.dim(
         " or you can add .json files to ~/.kairn/templates/\n"
       )
     );
@@ -2304,9 +2472,9 @@ var templatesCommand = new Command9("templates").description("Browse available t
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   if (jsonFiles.length === 0) {
     console.log(
-      chalk11.dim(
+      chalk12.dim(
         "  No templates found. Templates will be installed with "
-      ) + chalk11.bold("kairn init") + chalk11.dim(
+      ) + chalk12.bold("kairn init") + chalk12.dim(
         " or you can add .json files to ~/.kairn/templates/\n"
       )
     );
@@ -2315,8 +2483,8 @@ var templatesCommand = new Command9("templates").description("Browse available t
   const templates = [];
   for (const file of jsonFiles) {
     try {
-      const data = await fs12.readFile(
-        path12.join(templatesDir, file),
+      const data = await fs13.readFile(
+        path13.join(templatesDir, file),
         "utf-8"
       );
       const spec = JSON.parse(data);
@@ -2334,7 +2502,7 @@ var templatesCommand = new Command9("templates").description("Browse available t
   }
   if (filtered.length === 0) {
     console.log(
-      chalk11.dim(`  No templates matched category "${options.category}".
+      chalk12.dim(`  No templates matched category "${options.category}".
 `)
     );
     return;
@@ -2345,8 +2513,8 @@ var templatesCommand = new Command9("templates").description("Browse available t
     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("Name", chalk12.bold(spec.name)));
+    console.log(ui.kv("ID", chalk12.dim(spec.id)));
     console.log(ui.kv("Description", spec.description));
     console.log(
       ui.kv("Contents", `${toolCount} tools \xB7 ${commandCount} commands \xB7 ${ruleCount} rules`)
@@ -2354,16 +2522,139 @@ var templatesCommand = new Command9("templates").description("Browse available t
     console.log("");
   }
   console.log(
-    chalk11.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
+    chalk12.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
 `)
   );
 });
 
+// src/commands/keys.ts
+import { Command as Command10 } from "commander";
+import { password as password3 } from "@inquirer/prompts";
+import chalk13 from "chalk";
+import fs14 from "fs/promises";
+import path14 from "path";
+var keysCommand = new Command10("keys").description("Add or update API keys for the current environment").option("--show", "Show which keys are set vs missing").action(async (options) => {
+  printCompactBanner();
+  const targetDir = process.cwd();
+  const requiredVars = await detectRequiredEnvVars(targetDir);
+  if (requiredVars.length === 0) {
+    console.log(
+      ui.info("No MCP servers found in .mcp.json \u2014 no API keys needed.")
+    );
+    console.log("");
+    return;
+  }
+  const existing = await readEnvFile(targetDir);
+  const registry = await loadRegistry();
+  const envSetupMap = /* @__PURE__ */ new Map();
+  for (const tool of registry) {
+    if (!tool.env_vars) continue;
+    for (const ev of tool.env_vars) {
+      if (requiredVars.includes(ev.name)) {
+        envSetupMap.set(ev.name, {
+          toolName: tool.name,
+          envVar: ev.name,
+          description: ev.description,
+          signupUrl: tool.signup_url
+        });
+      }
+    }
+  }
+  for (const varName of requiredVars) {
+    if (!envSetupMap.has(varName)) {
+      envSetupMap.set(varName, {
+        toolName: "unknown",
+        envVar: varName,
+        description: "Required by MCP server"
+      });
+    }
+  }
+  if (options.show) {
+    console.log(ui.section("API Key Status"));
+    console.log("");
+    for (const varName of requiredVars) {
+      const value = existing.get(varName);
+      const info = envSetupMap.get(varName);
+      const toolLabel = info?.toolName !== "unknown" ? chalk13.dim(` (${info?.toolName})`) : "";
+      if (value && value.length > 0) {
+        const masked = value.slice(0, 4) + "\u2022".repeat(Math.max(0, value.length - 4));
+        console.log(chalk13.green(`  \u2713 ${varName}`) + toolLabel + chalk13.dim(` = ${masked}`));
+      } else {
+        console.log(chalk13.yellow(`  \u2717 ${varName}`) + toolLabel + chalk13.dim(" = (not set)"));
+        if (info?.signupUrl) {
+          console.log(chalk13.dim(`      Get one at: ${info.signupUrl}`));
+        }
+      }
+    }
+    const setCount = requiredVars.filter((v) => {
+      const val = existing.get(v);
+      return val && val.length > 0;
+    }).length;
+    const missingCount = requiredVars.length - setCount;
+    console.log("");
+    if (missingCount === 0) {
+      console.log(ui.success(`All ${setCount} key(s) configured`));
+    } else {
+      console.log(
+        ui.warn(`${missingCount} key(s) missing \u2014 run ${chalk13.bold("kairn keys")} to add them`)
+      );
+    }
+    console.log("");
+    return;
+  }
+  const missing = requiredVars.filter((v) => {
+    const val = existing.get(v);
+    return !val || val.length === 0;
+  });
+  if (missing.length === 0) {
+    console.log(ui.success("All API keys are already configured."));
+    console.log(chalk13.dim("  Use --show to see current keys.\n"));
+    return;
+  }
+  console.log(ui.section("API Keys"));
+  console.log(chalk13.dim(`  ${missing.length} key(s) need to be set. Press Enter to skip.
+`));
+  const envEntries = new Map(existing);
+  let keysEntered = 0;
+  for (const varName of missing) {
+    const info = envSetupMap.get(varName);
+    console.log(
+      chalk13.bold(`  ${varName}`) + (info?.toolName !== "unknown" ? chalk13.dim(` (${info?.toolName})`) : "")
+    );
+    if (info?.signupUrl) {
+      console.log(chalk13.dim(`    Get one at: ${info.signupUrl}`));
+    }
+    const value = await password3({
+      message: varName,
+      mask: "\u2022"
+    });
+    if (value && value.trim()) {
+      envEntries.set(varName, value.trim());
+      console.log(chalk13.green("  \u2713 saved\n"));
+      keysEntered++;
+    } else {
+      console.log(chalk13.dim("  (skipped)\n"));
+    }
+  }
+  const envLines = [
+    "# Generated by Kairn \u2014 API keys for MCP servers",
+    "# Do NOT commit this file to git",
+    ""
+  ];
+  for (const [key, value] of envEntries) {
+    envLines.push(`${key}=${value}`);
+  }
+  const envPath = path14.join(targetDir, ".env");
+  await fs14.writeFile(envPath, envLines.join("\n") + "\n", "utf-8");
+  console.log(chalk13.green(`  \u2713 ${keysEntered} key(s) saved to .env`));
+  console.log("");
+});
+
 // src/cli.ts
-var program = new Command10();
+var program = new Command11();
 program.name("kairn").description(
   "Compile natural language intent into optimized Claude Code environments"
-).version("1.6.0").option("--no-color", "Disable colored output");
+).version("1.8.0").option("--no-color", "Disable colored output");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);
@@ -2373,8 +2664,9 @@ program.addCommand(updateRegistryCommand);
 program.addCommand(doctorCommand);
 program.addCommand(registryCommand);
 program.addCommand(templatesCommand);
+program.addCommand(keysCommand);
 if (process.argv.includes("--no-color") || process.env.NO_COLOR) {
-  chalk12.level = 0;
+  chalk14.level = 0;
 }
 program.parse();
 //# sourceMappingURL=cli.js.map