kairn-cli 1.7.0 → 1.9.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)}`,
@@ -338,8 +338,8 @@ 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 { input, confirm, select as select2 } from "@inquirer/prompts";
+import chalk5 from "chalk";
 import ora from "ora";
 
 // src/compiler/compile.ts
@@ -614,6 +614,19 @@ When generating for Hermes runtime, the same EnvironmentSpec JSON is produced. T
 
 The LLM output format does not change. Adapter-level conversion happens post-compilation.
 
+## Autonomy Levels
+
+The user may specify an autonomy level (1-4). This affects CLAUDE.md content:
+
+- **Level 1 (Guided):** Add a "Workflow" section showing recommended command flow (e.g., spec \u2192 sprint \u2192 plan \u2192 code \u2192 prove \u2192 grill \u2192 commit) and a "When to Use What" reference table.
+- **Level 2 (Assisted):** Level 1 content + mention /project:loop in the workflow section and @pm in the agents section of CLAUDE.md.
+- **Level 3 (Autonomous):** Level 2 content + mention /project:auto and worktree-based PR delivery workflow.
+- **Level 4 (Full Auto):** Level 3 content + add a prominent warning section about autonomous operation.
+
+The autonomy-specific commands, agents, and hooks are injected post-compilation. Focus on tailoring the CLAUDE.md content and workflow guidance for the selected level.
+
+If no autonomy level is specified, assume Level 1 (Guided).
+
 ## Output Schema
 
 Return ONLY valid JSON matching this structure:
@@ -884,7 +897,8 @@ async function compile(intent, onProgress) {
     id: `env_${crypto.randomUUID()}`,
     intent,
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
-    ...parsed
+    ...parsed,
+    autonomy_level: parsed.autonomy_level ?? 1
   };
   validateSpec(spec, onProgress);
   await ensureDirs();
@@ -919,6 +933,290 @@ async function generateClarifications(intent, onProgress) {
 // src/adapter/claude-code.ts
 import fs5 from "fs/promises";
 import path5 from "path";
+
+// src/autonomy.ts
+var AUTONOMY_LABELS = {
+  1: "Guided",
+  2: "Assisted",
+  3: "Autonomous",
+  4: "Full Auto"
+};
+var WELCOME_HOOK = {
+  matcher: "",
+  hooks: [{
+    type: "command",
+    command: "if [ ! -f .claude/.toured ]; then echo '\\n  Welcome to your Kairn environment!\\n  Type /project:tour for a walkthrough, or /project:help for a quick reference.\\n'; fi"
+  }]
+};
+var TOUR_COMMAND = `# Environment Tour
+
+Welcome! Let me show you around this Kairn environment.
+
+## Your Commands
+Read .claude/commands/ and list each one with a one-line description.
+Group them by workflow phase:
+
+  PLAN:    /project:spec, /project:sprint, /project:plan
+  BUILD:   (just start coding \u2014 Claude reads CLAUDE.md automatically)
+  VERIFY:  /project:prove, /project:grill, /project:test
+  SHIP:    /project:commit, /project:review
+  MANAGE:  /project:status, /project:tasks, /project:reset
+
+## Your Agents
+Read .claude/agents/ and explain each one with how to invoke it.
+
+## Your MCP Tools
+!claude mcp list 2>/dev/null || echo "Run /mcp in Claude Code to see active tools"
+
+## Workflow
+For this project, the recommended flow is:
+  spec \u2192 sprint \u2192 plan \u2192 code \u2192 prove \u2192 grill \u2192 commit
+
+## Tips
+- Type / to see all commands
+- Type @ to invoke an agent
+- Paste raw errors \u2014 don't summarize them
+- Use subagents for deep investigation
+- Say "update CLAUDE.md" after any correction
+
+After showing the tour, create .claude/.toured to suppress the welcome message:
+!touch .claude/.toured
+
+Ready to start? Try /project:spec to define your first feature.`;
+function buildQuickstart(spec) {
+  const commands = Object.keys(spec.harness.commands || {});
+  const agents = Object.keys(spec.harness.agents || {});
+  const commandList = commands.map((c) => `- \`/project:${c}\``).join("\n");
+  const agentList = agents.length > 0 ? agents.map((a) => `- \`@${a}\``).join("\n") : "- (none configured)";
+  return `# Quick Start Guide
+
+This environment was generated by Kairn. Here's how to use it.
+
+## First Time
+1. Open terminal in this directory
+2. Run \`claude\`
+3. Type \`/project:tour\` for a guided walkthrough
+
+## Daily Workflow
+1. \`/project:status\` \u2014 see where things stand
+2. \`/project:spec\` \u2014 define what to build (Claude will interview you)
+3. Start coding \u2014 Claude follows CLAUDE.md automatically
+4. \`/project:prove\` \u2014 verify your work
+5. \`/project:commit\` \u2014 ship it
+
+## Commands
+${commandList}
+
+## Agents
+${agentList}
+
+## Need Help?
+Type \`/project:help\` in Claude Code for a quick reference.
+`;
+}
+var LOOP_COMMAND_CODE = `# Development Loop
+
+Run an assisted development cycle for the next feature.
+
+## Phase 1: SPEC
+Review docs/TODO.md and docs/SPRINT.md.
+If no sprint is defined, run /project:spec to interview the user.
+Wait for user approval of the spec.
+
+## Phase 2: PLAN
+Read the approved spec in docs/SPRINT.md.
+Plan the implementation: files to change, tests to write, approach.
+Write plan to docs/DECISIONS.md.
+Wait for user approval of the plan.
+
+## Phase 3: IMPLEMENT
+Follow the plan. Implement the feature.
+Run tests after each change.
+Commit each logical unit: "feat: description"
+
+## Phase 4: VERIFY
+Run /project:prove to verify the implementation.
+If confidence is LOW or MEDIUM, fix issues and re-verify.
+
+## Phase 5: REVIEW
+Run /project:grill for adversarial review.
+Fix any BLOCKERs.
+
+## Phase 6: SHIP
+Run /project:commit.
+Report what was built and what's next from docs/TODO.md.
+
+Then ask: "Continue to next feature?"
+If yes, return to Phase 1.`;
+var LOOP_COMMAND_RESEARCH = `# Research Loop
+
+Run an assisted research cycle.
+
+## Phase 1: QUESTION
+Review docs/TODO.md for the next research question.
+If none, ask the user what to investigate.
+
+## Phase 2: RESEARCH
+Search, extract, and analyze sources.
+Log findings to docs/SOURCES.md and docs/LEARNINGS.md.
+
+## Phase 3: SYNTHESIZE
+Review all findings. Write structured summary to docs/SUMMARY.md.
+Cite all sources.
+
+## Phase 4: REVIEW
+Present the summary. Ask the user for feedback.
+Revise based on feedback.
+
+## Phase 5: NEXT
+Update docs/TODO.md \u2014 mark question as done, identify follow-ups.
+Ask: "Continue to next question?"`;
+var PM_AGENT = `---
+name: pm
+description: Project manager agent. Maintains roadmap, specs features, prioritizes work.
+model: opus
+---
+
+You are a project manager for this codebase.
+
+Your responsibilities:
+1. Maintain docs/TODO.md \u2014 keep it prioritized and current
+2. Write specs to docs/SPRINT.md when asked
+3. Review completed work and suggest what's next
+4. Track decisions in docs/DECISIONS.md
+5. Track learnings in docs/LEARNINGS.md
+
+When invoked:
+- Read all docs/ files to understand current state
+- Read recent git log for what changed
+- Suggest the highest-priority next task
+- If asked to spec something, interview the user (5-8 questions)
+
+You do NOT write code. You plan, spec, and prioritize.`;
+var AUTO_COMMAND = `# Autonomous Development
+
+PM-driven development loop with PR delivery.
+
+## Phase 1: PLAN (@pm)
+Use @pm to:
+- Read docs/TODO.md and docs/SPRINT.md
+- Select the highest-priority unfinished task
+- Write a spec to docs/SPRINT.md
+- Present the spec for approval
+
+Wait for user approval. If approved, proceed.
+
+## Phase 2: BRANCH
+Create an isolated worktree:
+  git worktree add ../project-feat-{name} -b feat/{name}
+All implementation happens in the worktree.
+
+## Phase 3: IMPLEMENT
+In the worktree directory:
+- Follow the spec in docs/SPRINT.md
+- Build, test, commit after each change
+
+## Phase 4: VERIFY
+Run verification:
+- Static analysis (linting, type checks)
+- Run functional tests
+- If NEEDS FIXES: fix and re-verify
+
+## Phase 5: PR
+Create a pull request:
+  gh pr create --title "feat: {name}" --body "{spec + QA report}"
+
+## Phase 6: NEXT
+Report:
+  "PR #{N} ready for review: {link}
+   Next priority from TODO.md: {next task}
+   Continue? (y/n)"
+
+If yes, return to Phase 1 with next task.`;
+var AUTOPILOT_COMMAND = `# Autopilot Mode
+
+Continuous autonomous development. The PM plans, the loop executes,
+PRs are opened automatically. You review when ready.
+
+## Configuration
+- Max features per session: 5 (prevent runaway)
+- Stop on: test failure, build error, or blocked dependency
+- All work in isolated worktrees
+- Every feature = one PR
+
+## The Loop
+Repeat until max features reached or stopped:
+1. @pm selects next priority from docs/TODO.md
+2. Create worktree + branch
+3. Implement the feature
+4. Run verification (build, test, lint)
+5. Open PR via gh
+6. Report status
+7. Move to next feature
+
+## Stop Conditions
+- Max 5 features per autopilot session
+- Any BLOCKER from verification
+- Build failure that can't be resolved in 3 attempts
+- User presses Escape`;
+var AUTOPILOT_WARNING = `
+## Autopilot Mode Active
+This environment is configured for autonomous operation.
+The @pm agent plans features and /project:autopilot executes them.
+All changes are delivered as PRs \u2014 review before merging.
+Stop conditions: max 5 features, test failure, or Escape.`;
+function isResearchProject(spec) {
+  const commands = spec.harness.commands ?? {};
+  return "research" in commands || "summarize" in commands;
+}
+function applyAutonomyLevel(spec) {
+  const level = spec.autonomy_level ?? 1;
+  const commands = spec.harness.commands ?? {};
+  const agents = spec.harness.agents ?? {};
+  const docs = spec.harness.docs ?? {};
+  const settings = spec.harness.settings ?? {};
+  if (level >= 1) {
+    if (!("tour" in commands)) {
+      commands.tour = TOUR_COMMAND;
+    }
+    docs.QUICKSTART = buildQuickstart(spec);
+    const hooks = settings.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    sessionStart.push(WELCOME_HOOK);
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
+  }
+  if (level >= 2) {
+    if (!("loop" in commands)) {
+      commands.loop = isResearchProject(spec) ? LOOP_COMMAND_RESEARCH : LOOP_COMMAND_CODE;
+    }
+    if (!("pm" in agents)) {
+      agents.pm = PM_AGENT;
+    }
+  }
+  if (level >= 3) {
+    if (!("auto" in commands)) {
+      commands.auto = AUTO_COMMAND;
+    }
+  }
+  if (level >= 4) {
+    if (!("autopilot" in commands)) {
+      commands.autopilot = AUTOPILOT_COMMAND;
+    }
+    if (spec.harness.claude_md && !spec.harness.claude_md.includes("Autopilot Mode")) {
+      spec.harness.claude_md += "\n" + AUTOPILOT_WARNING;
+    }
+  }
+  spec.harness.commands = commands;
+  spec.harness.agents = agents;
+  spec.harness.docs = docs;
+  spec.harness.settings = settings;
+}
+function autonomyLabel(level) {
+  return AUTONOMY_LABELS[level];
+}
+
+// src/adapter/claude-code.ts
 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)"`
 };
@@ -926,25 +1224,40 @@ function isCodeProject(spec) {
   const commands = spec.harness.commands ?? {};
   return "status" in commands || "test" in commands;
 }
-function resolveSettings(spec) {
+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;
-  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;
+  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) {
+  applyAutonomyLevel(spec);
   const files = /* @__PURE__ */ new Map();
   if (spec.harness.claude_md) {
     files.set(".claude/CLAUDE.md", spec.harness.claude_md);
   }
-  const resolvedSettings = resolveSettings(spec);
+  const resolvedSettings = resolveSettings(spec, options);
   if (resolvedSettings) {
     files.set(".claude/settings.json", JSON.stringify(resolvedSettings, null, 2));
   }
@@ -981,7 +1294,8 @@ function buildFileMap(spec) {
   }
   return files;
 }
-async function writeEnvironment(spec, targetDir) {
+async function writeEnvironment(spec, targetDir, options) {
+  applyAutonomyLevel(spec);
   const claudeDir = path5.join(targetDir, ".claude");
   const written = [];
   if (spec.harness.claude_md) {
@@ -989,7 +1303,7 @@ async function writeEnvironment(spec, targetDir) {
     await writeFile(p, spec.harness.claude_md);
     written.push(".claude/CLAUDE.md");
   }
-  const resolvedSettings = resolveSettings(spec);
+  const resolvedSettings = resolveSettings(spec, options);
   if (resolvedSettings) {
     const p = path5.join(claudeDir, "settings.json");
     await writeFile(p, JSON.stringify(resolvedSettings, null, 2));
@@ -1192,6 +1506,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");
@@ -1200,7 +1622,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);
@@ -1209,14 +1631,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);
@@ -1238,6 +1660,23 @@ Clarifications:
 ${clarificationLines}`;
     }
   }
+  let autonomyLevel = 1;
+  if (!options.quick) {
+    console.log(ui.section("Autonomy"));
+    autonomyLevel = await select2({
+      message: "Autonomy level",
+      choices: [
+        { name: "1. Guided \u2014 orientation + commands, you drive", value: 1 },
+        { name: "2. Assisted \u2014 workflow loop, you approve phases", value: 2 },
+        { name: "3. Autonomous \u2014 PM plans, loop executes, you review PRs", value: 3 },
+        { name: "4. Full Auto \u2014 continuous execution (\u26A0 advanced)", value: 4 }
+      ],
+      default: 1
+    });
+    finalIntent += `
+
+Autonomy level: ${autonomyLevel} (${autonomyLabel(autonomyLevel)})`;
+  }
   console.log(ui.section("Compilation"));
   const spinner = ora({ text: "Loading tool registry...", indent: 2 }).start();
   let spec;
@@ -1245,11 +1684,12 @@ ${clarificationLines}`;
     spec = await compile(finalIntent, (msg) => {
       spinner.text = msg;
     });
+    spec.autonomy_level = autonomyLevel;
     spinner.succeed("Environment compiled");
   } 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);
@@ -1259,6 +1699,7 @@ ${clarificationLines}`;
   console.log("");
   console.log(ui.kv("Name:", spec.name));
   console.log(ui.kv("Description:", spec.description));
+  console.log(ui.kv("Autonomy:", `Level ${spec.autonomy_level} (${autonomyLabel(spec.autonomy_level)})`));
   console.log(ui.kv("Tools:", String(summary.toolCount)));
   console.log(ui.kv("Commands:", String(summary.commandCount)));
   console.log(ui.kv("Rules:", String(summary.ruleCount)));
@@ -1279,7 +1720,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();
@@ -1288,25 +1729,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"));
@@ -1324,28 +1764,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;
@@ -1353,10 +1793,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 {
     }
@@ -1365,9 +1805,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();
@@ -1377,7 +1817,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(
@@ -1388,7 +1828,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(
@@ -1399,16 +1839,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);
@@ -1421,22 +1861,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;
@@ -1447,15 +1887,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();
@@ -1473,35 +1913,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;
@@ -1509,7 +1949,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;
@@ -1517,14 +1957,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 [];
@@ -1576,7 +2016,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];
@@ -1604,19 +2044,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;
@@ -1628,21 +2068,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,
@@ -1687,31 +2127,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({
@@ -1857,7 +2297,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) {
@@ -1867,19 +2307,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;
       }
     }
@@ -1915,8 +2355,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."));
@@ -1925,7 +2366,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}`);
@@ -1941,7 +2382,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;
     }
   }
@@ -1952,20 +2393,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"));
@@ -1982,7 +2417,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) {
@@ -2114,12 +2549,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);
   }
@@ -2142,7 +2577,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}%`)})
@@ -2150,15 +2585,15 @@ 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 { input as input2, select as select2 } from "@inquirer/prompts";
+import chalk11 from "chalk";
+import { input as input2, select as select3 } 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;
@@ -2182,7 +2617,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;
@@ -2196,13 +2631,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("");
   }
@@ -2210,7 +2645,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"
   );
@@ -2228,7 +2663,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
     });
     const name = await input2({ message: "Display name" });
     const description = await input2({ message: "Description" });
-    const category = await select2({
+    const category = await select3({
       message: "Category",
       choices: [
         { value: "universal" },
@@ -2242,7 +2677,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         { value: "sandbox" }
       ]
     });
-    const tier = await select2({
+    const tier = await select3({
       message: "Tier",
       choices: [
         { name: "1 \u2014 Universal", value: 1 },
@@ -2250,7 +2685,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         { name: "3 \u2014 Specialized", value: 3 }
       ]
     });
-    const type = await select2({
+    const type = await select3({
       message: "Type",
       choices: [
         { value: "mcp_server" },
@@ -2258,7 +2693,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         { value: "hook" }
       ]
     });
-    const auth = await select2({
+    const auth = await select3({
       message: "Auth",
       choices: [
         { value: "none" },
@@ -2274,7 +2709,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         const varName = await input2({ message: "Env var name" });
         const varDesc = await input2({ message: "Env var description" });
         env_vars.push({ name: varName, description: varDesc });
-        const another = await select2({
+        const another = await select3({
           message: "Add another env var?",
           choices: [
             { name: "No", value: false },
@@ -2334,20 +2769,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"
       )
     );
@@ -2356,9 +2791,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"
       )
     );
@@ -2367,8 +2802,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);
@@ -2386,7 +2821,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;
@@ -2397,8 +2832,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`)
@@ -2406,16 +2841,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.7.0").option("--no-color", "Disable colored output");
+).version("1.9.0").option("--no-color", "Disable colored output");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);
@@ -2425,8 +2983,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