meetsoma 0.2.0 → 0.3.1

package/dist/thin-cli.js

@@ -2,598 +2,32 @@
 /**
  * Soma — Thin CLI
  *
- * The public face of Soma on npm. For new users, this IS the first
- * impression. It should feel alive, interesting, and worth signing up for.
- *
+ * The public face of Soma on npm. Routes to modular commands.
+ * For new users, this IS the first impression.
  * For returning users: detects installed runtime → delegates to it.
  */
 
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, statSync, readlinkSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, readlinkSync } from "fs";
 import { join, dirname } from "path";
 import { homedir, platform } from "os";
 import { fileURLToPath } from "url";
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { soma as voice } from "./personality.js";
 
+// ── Shared modules ─────────────────────────────────────────────────────
+import { bold, dim, italic, cyan, green, yellow, red, magenta, white,
+         printSigma, typeOut, typeParagraph, wrapText,
+         waitForKey, confirm, confirmYN, readLine, readSecret } from "./lib/display.js";
+import { SOMA_HOME, CONFIG_PATH, CORE_DIR, SITE_URL, readConfig, writeConfig } from "./lib/config.js";
+import { isInstalled, getAgentVersion, getProjectVersion, getCliVersion,
+         hasAnyAuth, getShellConfigPath, getShellConfigAbsPath, detectKeyInShellConfig,
+         openBrowser, hasGitHubCLI, getGitHubUsername } from "./lib/detect.js";
+import { handleQuestion, interactiveQ, CONCEPTS, getConceptIndex, getConceptBody } from "./welcome/qa.js";
+import { apiKeySetup, apiKeyExplain, apiKeyGetOne, apiKeyEntry, oauthGuide } from "./welcome/auth.js";
+import { showAbout } from "./welcome/about.js";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
-const SOMA_HOME = join(homedir(), ".soma");
-const CONFIG_PATH = join(SOMA_HOME, "config.json");
-const CORE_DIR = join(SOMA_HOME, "agent");
-const SITE_URL = "https://soma.gravicity.ai";
-
-// ── Colours ──────────────────────────────────────────────────────────
-
-const bold = s => `\x1b[1m${s}\x1b[0m`;
-const dim = s => `\x1b[2m${s}\x1b[0m`;
-const italic = s => `\x1b[3m${s}\x1b[0m`;
-const cyan = s => `\x1b[36m${s}\x1b[0m`;
-const green = s => `\x1b[32m${s}\x1b[0m`;
-const yellow = s => `\x1b[33m${s}\x1b[0m`;
-const red = s => `\x1b[31m${s}\x1b[0m`;
-const magenta = s => `\x1b[35m${s}\x1b[0m`;
-const white = s => `\x1b[97m${s}\x1b[0m`;
-
-// ── Config ───────────────────────────────────────────────────────────
-
-function readConfig() {
-  try { return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")); }
-  catch { return {}; }
-}
-
-function writeConfig(config) {
-  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
-}
-
-function isInstalled() {
-  // Check both layouts: soma-beta (dist/extensions) and dev setup (extensions/)
-  const hasDist = existsSync(join(CORE_DIR, "dist", "extensions")) && existsSync(join(CORE_DIR, "dist", "core"));
-  const hasDev = existsSync(join(CORE_DIR, "extensions")) && existsSync(join(CORE_DIR, "core"));
-  // Check deps exist — Pi is the critical dependency
-  const hasDeps = existsSync(join(CORE_DIR, "node_modules", "@mariozechner"));
-  return (hasDist || hasDev) && hasDeps;
-}
-
-function getAgentVersion() {
-  try {
-    // In dev mode, core/ is symlinked — resolve to find the real repo's package.json
-    let pkgPath = join(CORE_DIR, "package.json");
-    try {
-      const realCore = readlinkSync(join(CORE_DIR, "core"));
-      if (realCore) {
-        // core/ symlink → repos/agent/core → go up one level for package.json
-        const devPkg = join(dirname(realCore), "package.json");
-        if (existsSync(devPkg)) pkgPath = devPkg;
-      }
-    } catch { /* not a symlink, use default */ }
-    return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
-  } catch { return null; }
-}
-
-function getProjectVersion() {
-  try {
-    const settingsPath = join(process.cwd(), ".soma", "settings.json");
-    return JSON.parse(readFileSync(settingsPath, "utf-8")).version || null;
-  } catch { return null; }
-}
-
-// ── Browser ──────────────────────────────────────────────────────────
-
-function openBrowser(url) {
-  try {
-    const cmd = platform() === "darwin" ? "open"
-      : platform() === "win32" ? "start"
-      : "xdg-open";
-    execSync(`${cmd} "${url}"`, { stdio: "ignore" });
-    return true;
-  } catch { return false; }
-}
-
-// ── Interactive prompt (no deps) ─────────────────────────────────────
-
-function waitForKey(prompt) {
-  return new Promise(resolve => {
-    process.stdout.write(prompt);
-    if (!process.stdin.isTTY) { resolve(""); return; }
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf-8");
-    process.stdin.once("data", key => {
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
-      process.stdout.write("\n");
-      if (key === "\u0003") process.exit(0); // Ctrl+C
-      resolve(key);
-    });
-  });
-}
-
-async function confirm(prompt) {
-  const key = await waitForKey(`${prompt} ${dim("[Enter]")} `);
-  return true;
-}
-
-async function confirmYN(prompt) {
-  const key = await waitForKey(`${prompt} ${dim("[y/n]")} `);
-  return key.toLowerCase() === "y";
-}
-
-// ── Typing effect ────────────────────────────────────────────────────
-
-function sleep(ms) {
-  return new Promise(r => setTimeout(r, ms));
-}
-
-/**
- * Type out text character by character.
- * Punctuation pauses longer. Newlines pause. ANSI codes print instantly.
- * @param {string} text - text to type (may contain ANSI escapes)
- * @param {object} opts
- * @param {number} opts.charDelay  - ms between characters (default 18)
- * @param {number} opts.punctDelay - ms pause after . , ; : — (default 80)
- * @param {number} opts.lineDelay  - ms pause on newline (default 40)
- * @param {boolean} opts.instant   - skip animation (non-TTY)
- */
-async function typeOut(text, opts = {}) {
-  if (!process.stdout.isTTY) { process.stdout.write(text); return; }
-
-  // People type in bursts: fast through a word, pause at spaces,
-  // longer pause after sentences. Speed drifts — sometimes fast,
-  // sometimes slow, like attention wandering and refocusing.
-  let pace = 1.0; // drift multiplier — wanders between 0.6 and 1.4
-  let i = 0;
-
-  while (i < text.length) {
-    // ANSI escapes — print instantly
-    const remaining = text.slice(i);
-    const ansi = remaining.match(/^\x1b\[[0-9;]*m/);
-    if (ansi) { process.stdout.write(ansi[0]); i += ansi[0].length; continue; }
-
-    const ch = text[i];
-    const next = text[i + 1] || "";
-    process.stdout.write(ch);
-    i++;
-
-    // Drift pace gently (random walk, clamped)
-    pace += (Math.random() - 0.5) * 0.15;
-    pace = Math.max(0.6, Math.min(1.4, pace));
-
-    if (ch === "\n") {
-      await sleep(58 * pace);
-    } else if (".!?".includes(ch) && (next === " " || next === "\n" || next === "")) {
-      await sleep((230 + Math.random() * 175) * pace);
-    } else if (ch === "," || ch === ";" || ch === ":") {
-      await sleep((70 + Math.random() * 46) * pace);
-    } else if (ch === "—" || ch === "–") {
-      await sleep((92 + Math.random() * 70) * pace);
-    } else if (ch === " ") {
-      await sleep((9 + Math.random() * 23) * pace);
-    } else {
-      await sleep((6 + Math.random() * 14) * pace);
-    }
-  }
-}
-
-/**
- * Type a word-wrapped paragraph with typing effect.
- */
-async function typeParagraph(text, indent = "  ", width = 58) {
-  const words = text.split(" ");
-  let line = indent;
-  const lines = [];
-  for (const word of words) {
-    if (line.length + word.length > width + indent.length && line.trim()) {
-      lines.push(line);
-      line = indent + word;
-    } else {
-      line += (line.trim() ? " " : "") + word;
-    }
-  }
-  if (line.trim()) lines.push(line);
-  await typeOut(lines.join("\n") + "\n");
-}
-
-// ── The sigma ────────────────────────────────────────────────────────
-
-function printSigma() {
-  console.log("");
-  console.log(cyan("    σ"));
-  console.log("");
-}
-
-// ── Concepts (rotate on each run) ────────────────────────────────────
-// Each concept has a title and maps to a topic in the personality engine.
-// The body is generated fresh each time — spintax means variety.
-
-const CONCEPTS = [
-  { title: "Memory isn't retrieval. Memory is change.",  topic: "how_memory_works" },
-  { title: "Your agent should know who it is.",          topic: "what_is_soma" },
-  { title: "Protocols evolve. Muscles grow.",            topic: "what_are_protocols" },
-  { title: "The breath cycle.",                          topic: "what_is_breath" },
-  { title: "Tools that survive across sessions.",        topic: "what_are_scripts" },
-  { title: "Heat tracks what matters.",                  topic: "what_is_heat" },
-  { title: "What are muscles?",                          topic: "what_are_muscles" },
-  { title: "No compaction. Ever.",                        topic: "no_compaction" },
-];
-
-function getConceptIndex() {
-  const day = Math.floor(Date.now() / 86400000);
-  return day % CONCEPTS.length;
-}
-
-function getConceptBody(topic) {
-  return voice.ask(topic) || "";
-}
-
-// ── Interactive Q&A ──────────────────────────────────────────────────
-
-const QUESTION_MAP = [
-  // Order matters — more specific topics first, catch-all last
-  { triggers: ["compact", "compaction", "summarise", "summarize", "summarization", "compress", "waiting", "context limit", "token limit", "context fills", "context window", "run out", "limit"], topic: "no_compaction", label: "Why no compaction?" },
-  { triggers: ["heat", "hot", "cold", "fade", "decay", "temperature"],   topic: "what_is_heat",           label: "What is the heat system?" },
-  { triggers: ["breath", "inhale", "exhale", "cycle", "session lifecycle"], topic: "what_is_breath",       label: "What is the breath cycle?" },
-  { triggers: ["protocol", "rule", "behaviour", "behavior", "protocols"], topic: "what_are_protocols",    label: "What are protocols?" },
-  { triggers: ["muscle", "muscles", "learn", "pattern", "grow", "correction"], topic: "what_are_muscles", label: "What are muscles?" },
-  { triggers: ["script", "scripts", "tool", "tools", "automate", "automation"], topic: "what_are_scripts", label: "What are scripts?" },
-  { triggers: ["memory", "remember", "forget", "remembers", "change"],   topic: "how_memory_works",      label: "How does memory work?" },
-  { triggers: ["license", "source", "open", "bsl", "mit", "available"], topic: "why_source_available",   label: "Why source-available?" },
-  // Practical / instructional
-  { triggers: ["install", "set up", "setup", "get started", "start", "begin", "getting started", "requirements", "require", "need to", "prerequisites"],      topic: "how_to_install",  label: "How do I install?" },
-  { triggers: ["sign up", "signup", "register", "join", "invite", "invitation", "apply"], topic: "how_to_source",    label: "How do I get source access?" },
-  { triggers: ["cost", "price", "pricing", "free", "pay", "money", "subscription", "plan"],            topic: "how_to_cost",     label: "What does it cost?" },
-  { triggers: ["language", "languages", "python", "rust", "java", "typescript", "ruby", "go", "cpp", "swift"], topic: "how_to_languages", label: "What languages does it support?" },
-  { triggers: ["api key", "api_key", "anthropic", "openai", "gemini", "key", "token", "provider"],     topic: "how_to_api_key",  label: "Do I need an API key?" },
-  { triggers: ["model", "llm", "claude", "gpt", "which model", "what model"],                          topic: "how_to_model",    label: "What model does it use?" },
-  { triggers: ["try", "demo", "preview", "test", "sample", "example"],                                 topic: "how_to_try",      label: "Can I try it?" },
-  // Meta / self-aware
-  { triggers: ["are you ai", "are you real", "are you alive", "sentient", "conscious", "artificial"],  topic: "meta_self",       label: "Are you AI?" },
-  { triggers: ["feel", "feelings", "emotion", "aware", "think", "alive"],                              topic: "meta_feelings",   label: "Do you have feelings?" },
-  { triggers: ["who made", "who built", "who created", "creator", "developer", "behind"],              topic: "meta_who_made",   label: "Who made Soma?" },
-  { triggers: ["cursor", "copilot", "windsurf", "claude code", "cline", "better", "competitor", "vs", "compared"], topic: "meta_competitor", label: "How does Soma compare?" },
-  { triggers: ["how do you work", "how does this work", "what are you", "how are you built"],          topic: "meta_how_work",   label: "How does this CLI work?" },
-  { triggers: ["cool", "amazing", "impressive", "wow", "nice", "love", "awesome", "brilliant"],        topic: "meta_impressed",  label: "I'm impressed" },
-  // Catch-all — "what is soma", generic questions (no "you" — too greedy)
-  { triggers: ["soma", "agent", "what is"],                              topic: "what_is_soma",          label: "What is Soma?" },
-];
-
-function matchQuestion(input) {
-  const lower = input.toLowerCase();
-  let best = null;
-  let bestScore = 0;
-  for (const q of QUESTION_MAP) {
-    const score = q.triggers.filter(t => lower.includes(t)).length;
-    // Weight: specific topics (listed first) get a slight bonus
-    // to break ties with the generic catch-all
-    if (score > bestScore) {
-      bestScore = score;
-      best = q;
-    }
-  }
-  // If only generic triggers matched ("what", "about"), prefer
-  // the catch-all over a false-positive on a specific topic
-  return best;
-}
-
-function wrapText(text, indent = "  ", width = 58) {
-  const words = text.split(" ");
-  const lines = [];
-  let line = indent;
-  for (const word of words) {
-    if (line.length + word.length > width + indent.length && line.trim()) {
-      lines.push(line);
-      line = indent + word;
-    } else {
-      line += (line.trim() ? " " : "") + word;
-    }
-  }
-  if (line.trim()) lines.push(line);
-  return lines.join("\n");
-}
-
-function readLine(prompt) {
-  return new Promise(resolve => {
-    process.stdout.write(prompt);
-    if (!process.stdin.isTTY) { resolve(""); return; }
-    process.stdin.setRawMode(false);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf-8");
-    let buf = "";
-    const onData = chunk => {
-      buf += chunk;
-      if (buf.includes("\n")) {
-        process.stdin.pause();
-        process.stdin.removeListener("data", onData);
-        resolve(buf.trim());
-      }
-    };
-    process.stdin.on("data", onData);
-  });
-}
-
-async function handleQuestion(input) {
-  const match = matchQuestion(input);
-  if (match) {
-    const answer = voice.ask(match.topic);
-    console.log("");
-    await typeParagraph(answer);
-    return true;
-  }
-
-  // Edge case routing — detect intent even without a topic match
-  const lower = input.toLowerCase();
-  const rude = /suck|stupid|dumb|trash|garbage|hate|worst|bad|ugly|boring|lame|waste/.test(lower);
-  const impressed = /cool|amazing|wow|nice|love|awesome|brilliant|impressive|neat|sick|fire|goat/.test(lower);
-  const meta = /are you|what are you|how do you|who are you|real|alive|ai\b|bot\b/.test(lower);
-  const greeting = /^(hi|hey|hello|sup|yo|howdy|hola|greetings|good morning|good evening)\b/.test(lower);
-
-  console.log("");
-  if (greeting) {
-    await typeOut(`  ${voice.greet()} ${voice.spin("{Ask me anything.|What do you want to know?|I know about 9 topics — pick one.}")}\n`);
-  } else if (rude) {
-    await typeParagraph(voice.ask("meta_rude"));
-  } else if (impressed) {
-    await typeParagraph(voice.ask("meta_impressed"));
-  } else if (meta) {
-    await typeParagraph(voice.ask("meta_self"));
-  } else {
-    // Anything with a question mark → try harder, then admit we don't know
-    if (input.includes("?")) {
-      await typeParagraph(voice.ask("meta_nonsense"));
-    } else {
-      await typeParagraph(voice.ask("meta_nonsense"));
-    }
-  }
-  return false;
-}
-
-async function interactiveQ() {
-  console.log("");
-  console.log(`  ${bold("Ask me anything.")}`);
-  console.log("");
-  console.log(`    ${dim("•")} How do I install?    ${dim("•")} What is heat?`);
-  console.log(`    ${dim("•")} What does it cost?   ${dim("•")} What are muscles?`);
-  console.log(`    ${dim("•")} Why no compaction?   ${dim("•")} Are you AI?`);
-  console.log(`    ${dim("•")} How does it compare? ${dim("•")} Who made this?`);
-  console.log("");
-  console.log(`  ${dim("...or ask anything. Press")} ${green("Enter")} ${dim("when you're ready to install.")}`);
-
-  let rounds = 0;
-  const maxRounds = 8;
-
-  while (rounds < maxRounds) {
-    console.log("");
-    const input = await readLine(`  ${cyan("?")} `);
-
-    // Empty input or quit → exit Q&A, proceed to install
-    if (!input || input === "q" || input === "quit" || input === "exit") {
-      break;
-    }
-
-    await handleQuestion(input);
-    rounds++;
-
-    if (rounds < maxRounds) {
-      console.log("");
-      console.log(`  ${dim("Ask another, or")} ${green("Enter")} ${dim("to install Soma.")}`);
-    }
-  }
-
-  if (rounds >= maxRounds) {
-    console.log("");
-    await typeOut(`  ${voice.spin("{Curious enough?|Intrigued?|Want to see it in action?}")} ${dim("Let's set you up.")}\n`);
-  }
-}
-
-// ── GitHub check ─────────────────────────────────────────────────────
-
-function hasGitHubCLI() {
-  try {
-    execSync("gh --version", { stdio: "ignore" });
-    return true;
-  } catch { return false; }
-}
-
-function getGitHubUsername() {
-  try {
-    return execSync("gh api user -q .login", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
-  } catch { return null; }
-}
-
-// ── Commands ─────────────────────────────────────────────────────────
-
-// ── Auth helpers ─────────────────────────────────────────────────────
-
-function hasAnyAuth() {
-  const hasEnvKey = !!(process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY || process.env.GEMINI_API_KEY || process.env.GROQ_API_KEY || process.env.XAI_API_KEY);
-  if (hasEnvKey) return true;
-  try {
-    const authData = JSON.parse(readFileSync(join(CORE_DIR, "auth.json"), "utf-8"));
-    return Object.keys(authData).length > 0;
-  } catch { return false; }
-}
-
-function getShellConfigPath() {
-  return process.env.SHELL?.includes("zsh") ? "~/.zshrc" : "~/.bashrc";
-}
-
-function getShellConfigAbsPath() {
-  const home = homedir();
-  return process.env.SHELL?.includes("zsh") ? join(home, ".zshrc") : join(home, ".bashrc");
-}
-
-function detectKeyInShellConfig() {
-  // Check if key is in shell config but not loaded (user hasn't restarted terminal)
-  try {
-    const configContent = readFileSync(getShellConfigAbsPath(), "utf-8");
-    const keyPattern = /export\s+(ANTHROPIC_API_KEY|OPENAI_API_KEY|GEMINI_API_KEY)=/;
-    const match = configContent.match(keyPattern);
-    if (match) return match[1];
-  } catch {}
-  return null;
-}
-
-// ── API key setup wizard ─────────────────────────────────────────────
-
-async function apiKeySetup() {
-  console.log(`  ${yellow("!")} One more thing — Soma needs an AI provider to work.`);
-  console.log("");
-  await typeOut(`  ${voice.spin("{Do you have an Anthropic API key?|Got a Claude API key?|Have an API key for Claude?}")}\n`);
-  console.log("");
-  console.log(`    ${green("y")}  ${dim("Yes, I have a key")}`);
-  console.log(`    ${green("n")}  ${dim("No, I need one")}`);
-  console.log(`    ${green("s")}  ${dim("I have a Claude Pro/Max subscription")}`);
-  console.log(`    ${green("?")}  ${dim("What's an API key?")}`);
-  console.log("");
-
-  const key = await waitForKey(`  ${dim("→")} `);
-  const choice = key.toLowerCase();
-
-  if (choice === "y") {
-    await apiKeyEntry();
-  } else if (choice === "s") {
-    await oauthGuide();
-  } else if (choice === "?") {
-    await apiKeyExplain();
-  } else {
-    await apiKeyGetOne();
-  }
-}
-
-async function apiKeyExplain() {
-  console.log("");
-  await typeParagraph("An API key is like a password that lets Soma talk to an AI model. You get one from Anthropic (the company that makes Claude), paste it into your terminal config, and Soma handles the rest. Your key stays on your machine — Soma never sends it anywhere.");
-  console.log("");
-  await typeParagraph("If you have a Claude Pro or Max subscription, you don't need a separate key — you can log in with your account instead.");
-  console.log("");
-
-  console.log(`    ${green("g")}  ${dim("Get a key (I'll show you how)")}`);
-  console.log(`    ${green("s")}  ${dim("I have Claude Pro/Max — log in instead")}`);
-  console.log("");
-
-  const key = await waitForKey(`  ${dim("→")} `);
-  if (key.toLowerCase() === "s") {
-    await oauthGuide();
-  } else {
-    await apiKeyGetOne();
-  }
-}
-
-async function apiKeyGetOne() {
-  console.log("");
-  await typeOut(`  ${voice.spin("{Here's how.|Let me walk you through it.|Quick steps.}")}\n`);
-  console.log("");
-  console.log(`  ${cyan("Step 1:")} Open this link to create a key:`);
-  console.log("");
-  console.log(`    ${cyan("https://console.anthropic.com/settings/keys")}`);
-  console.log("");
-  openBrowser("https://console.anthropic.com/settings/keys");
-  console.log(`    ${dim("(opened in your browser)")}`);
-  console.log("");
-  await confirm(`  ${dim("→")} Press ${bold("Enter")} when you have your key`);
-  await apiKeyEntry();
-}
-
-function readSecret(prompt) {
-  return new Promise(resolve => {
-    process.stdout.write(prompt);
-    if (!process.stdin.isTTY) { resolve(""); return; }
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf-8");
-    let buf = "";
-    const onData = chunk => {
-      for (const ch of chunk) {
-        if (ch === "\r" || ch === "\n") {
-          process.stdin.setRawMode(false);
-          process.stdin.pause();
-          process.stdin.removeListener("data", onData);
-          process.stdout.write("\n");
-          resolve(buf);
-          return;
-        } else if (ch === "\u007F" || ch === "\b") {
-          // Backspace
-          if (buf.length > 0) {
-            buf = buf.slice(0, -1);
-            process.stdout.write("\b \b");
-          }
-        } else if (ch === "\u0003") {
-          // Ctrl+C
-          process.stdout.write("\n");
-          process.exit(0);
-        } else if (ch >= " ") {
-          buf += ch;
-          process.stdout.write("•");
-        }
-      }
-    };
-    process.stdin.on("data", onData);
-  });
-}
-
-async function apiKeyEntry() {
-  console.log("");
-  console.log(`  ${cyan("Step 2:")} Paste your key below.`);
-  console.log(`  ${dim("It starts with")} sk-ant-...`);
-  console.log("");
-
-  const apiKey = await readSecret(`  ${dim("Key:")} `);
-
-  if (!apiKey || !apiKey.startsWith("sk-")) {
-    console.log("");
-    if (!apiKey) {
-      console.log(`  ${dim("No key entered. You can set it up later.")}`);
-    } else {
-      console.log(`  ${yellow("!")} That doesn't look like an Anthropic key.`);
-      console.log(`  ${dim("Keys start with")} sk-ant-...`);
-    }
-    console.log("");
-    const sc = getShellConfigPath();
-    console.log(`  ${dim("When you have your key, add it to")} ${dim(sc)}${dim(":")}`);
-    console.log(`    ${green('export ANTHROPIC_API_KEY="your-key-here"')}`);
-    console.log(`  ${dim("Then restart your terminal and run")} ${green("soma")}`);
-    console.log("");
-    return;
-  }
-
-  // Write to shell config
-  const shellConfigPath = getShellConfigAbsPath();
-  const shellConfigName = getShellConfigPath();
-  const exportLine = `\nexport ANTHROPIC_API_KEY="${apiKey}"\n`;
-
-  try {
-    appendFileSync(shellConfigPath, exportLine);
-    console.log("");
-    console.log(`  ${green("✓")} Key saved to ${dim(shellConfigName)}`);
-    console.log("");
-
-    // Set it for the current process too so we can launch immediately
-    process.env.ANTHROPIC_API_KEY = apiKey;
-
-    await typeOut(`  ${voice.spin("{You're all set.|Good to go.|Ready.}")} ${dim("Soma can start now.")}\n`);
-    console.log("");
-  } catch {
-    console.log("");
-    console.log(`  ${yellow("!")} Couldn't write to ${dim(shellConfigName)}.`);
-    console.log(`  ${dim("Add this line manually:")}`);
-    console.log(`    ${green(`export ANTHROPIC_API_KEY="${apiKey}"`)}`);
-    console.log(`  ${dim("Then restart your terminal and run")} ${green("soma")}`);
-    console.log("");
-  }
-}
-
-async function oauthGuide() {
-  console.log("");
-  await typeParagraph("Nice — with a Pro or Max subscription, you can log in with your Anthropic account. No API key needed.");
-  console.log("");
-  console.log(`  ${dim("When Soma starts, type")} ${green("/login")} ${dim("and follow the prompts.")}`);
-  console.log(`  ${dim("It'll open your browser to authenticate.")}`);
-  console.log("");
-  await typeOut(`  ${voice.spin("{Let's launch.|Starting up.|Here we go.}")}\n`);
-  console.log("");
-  // Mark that user chose OAuth so we don't block launch
-  process.env._SOMA_OAUTH_PENDING = "1";
-}
 
 // ── Welcome / First Run ─────────────────────────────────────────────
 
@@ -602,9 +36,7 @@ async function showWelcome() {
   console.log(`  ${bold("Soma")} ${dim("—")} ${white("the AI agent that remembers")}`);
   console.log("");
 
-  // Runtime installed → delegate to it
   if (isInstalled()) {
-    const config = readConfig();
     const ghUser = hasGitHubCLI() ? getGitHubUsername() : null;
     if (ghUser) {
       console.log(`  ${green("✓")} ${voice.greetBack(ghUser)}`);
@@ -614,7 +46,6 @@ async function showWelcome() {
       console.log(`  ${green("✓")} Core installed`);
       console.log("");
 
-      // Check if key exists in shell config but isn't loaded
       const unloadedKey = detectKeyInShellConfig();
       if (unloadedKey) {
         console.log(`  ${yellow("!")} Found ${bold(unloadedKey)} in ${dim(getShellConfigPath())} but it's not loaded.`);
@@ -625,7 +56,6 @@ async function showWelcome() {
 
       await apiKeySetup();
 
-      // If they set a key or chose OAuth, launch. If not, exit gracefully.
       if (!hasAnyAuth() && !process.env.ANTHROPIC_API_KEY && !process.env._SOMA_OAUTH_PENDING) {
         console.log(`  ${dim("No worries.")} ${voice.spin("{Come back when you're ready.|Set up a key and run soma again.|We'll be here.}")}`);
         console.log("");
@@ -642,7 +72,6 @@ async function showWelcome() {
   }
 
   // ── Not installed — first time ever ────────────────────────────────
-
   await typeOut(`  ${voice.greet()}\n`);
   console.log("");
   await typeParagraph("Soma is an AI coding agent that remembers across sessions. It learns your patterns, builds its own tools, and picks up where it left off.");
@@ -659,15 +88,12 @@ async function showWelcome() {
     await interactiveQ();
   }
 
-  // Install the runtime
   await initSoma();
 
-  // If install succeeded, run the API key setup
   if (isInstalled() && !hasAnyAuth()) {
     await apiKeySetup();
   }
 
-  // If they have auth now (or chose OAuth), offer to launch
   if (isInstalled() && (hasAnyAuth() || process.env.ANTHROPIC_API_KEY || process.env._SOMA_OAUTH_PENDING)) {
     console.log(`  ${dim("─".repeat(58))}`);
     console.log("");
@@ -684,6 +110,8 @@ async function showWelcome() {
   console.log("");
 }
 
+// ── Help ─────────────────────────────────────────────────────────────
+
 function showHelp() {
   printSigma();
   console.log(`  ${bold("Soma")} v${VERSION}`);
@@ -727,56 +155,13 @@ function showVersion() {
   }
 }
 
-async function showAbout() {
-  printSigma();
-  console.log(`  ${bold("What is Soma?")}`);
-  console.log("");
-  console.log("  Soma is an AI coding agent that grows with you.");
-  console.log("  It remembers across sessions — not by storing chat logs,");
-  console.log("  but by evolving its own working patterns through use.");
-  console.log("");
-  console.log(`  ${bold("How it works:")}`);
-  console.log("");
-  console.log(`  ${cyan("1.")} ${bold("Identity")} — The agent maintains a self-written identity file.`);
-  console.log(`     It knows your project, your patterns, your preferences.`);
-  console.log("");
-  console.log(`  ${cyan("2.")} ${bold("Protocols")} — Behavioural rules that shape how the agent works.`);
-  console.log(`     "Read before write." "Test before commit." They have heat —`);
-  console.log(`     used ones stay hot, unused ones fade.`);
-  console.log("");
-  console.log(`  ${cyan("3.")} ${bold("Muscles")} — Learned patterns. "Use esbuild for bundling."`);
-  console.log(`     "This API uses OAuth, not API keys." Muscles grow from`);
-  console.log(`     corrections and repetition.`);
-  console.log("");
-  console.log(`  ${cyan("4.")} ${bold("Breath Cycle")} — Inhale (load state) → Hold (work) → Exhale`);
-  console.log(`     (save state). At context limits, the agent writes a preload`);
-  console.log(`     for its next self — a briefing, not a summary.`);
-  console.log("");
-  console.log(`  ${cyan("5.")} ${bold("Scripts")} — The agent builds tools for itself. What it does`);
-  console.log(`     twice manually, it automates. Scripts survive across sessions.`);
-  console.log("");
-  console.log(`  ${dim("─".repeat(58))}`);
-  console.log("");
-
-  // Show a generated "what is soma" paragraph — different every time
-  const pitch = voice.ask("what_is_soma");
-  await typeOut(`  ${magenta("❝")} ${italic(pitch)}\n`);
-  console.log("");
-
-  if (!isInstalled()) {
-    console.log(`  ${dim("→")} ${green("soma init")} to install  ${dim("·")}  ${cyan(SITE_URL)}`);
-  } else {
-    console.log(`  ${dim(SITE_URL)}`);
-  }
-  console.log("");
-}
+// ── Init Soma ────────────────────────────────────────────────────────
 
 async function initSoma() {
   printSigma();
   console.log(`  ${bold("Soma")} — Install`);
   console.log("");
 
-  // Check git is available
   try {
     execSync("git --version", { stdio: "ignore" });
   } catch {
@@ -791,21 +176,17 @@ async function initSoma() {
   const installDir = join(SOMA_HOME, "agent");
   mkdirSync(SOMA_HOME, { recursive: true });
 
-  // Validate existing install — check it's a real git repo with dist/ content
   const isValidInstall = existsSync(installDir) 
     && existsSync(join(installDir, ".git"))
     && (existsSync(join(installDir, "dist", "extensions")) || existsSync(join(installDir, "extensions")));
 
-  // Track user files to preserve across repair/reinstall
   let preservedFiles = {};
 
   if (existsSync(installDir) && !isValidInstall) {
-    // Broken/partial install — try to repair, preserve user files
     console.log(`  ${yellow("⚠")} Incomplete installation detected.`);
     console.log(`    ${dim("Missing:")} ${!existsSync(join(installDir, ".git")) ? "git repo" : "core files"}`);
     console.log("");
 
-    // Save user files before touching anything
     const userFileNames = ["auth.json", "models.json"];
     for (const f of userFileNames) {
       const fp = join(installDir, f);
@@ -817,7 +198,6 @@ async function initSoma() {
       }
     }
 
-    // Try repair: if it's a git repo, fetch + reset. Otherwise move aside for fresh clone.
     const hasGit = existsSync(join(installDir, ".git"));
     let repaired = false;
 
@@ -834,7 +214,6 @@ async function initSoma() {
     }
 
     if (!repaired) {
-      // Move broken dir aside (never delete), then clone will happen below
       const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
       const backup = join(SOMA_HOME, `agent-backup-${ts}`);
       try {
@@ -851,8 +230,6 @@ async function initSoma() {
 
   if (isValidInstall) {
     console.log(`  ${dim("→")} Runtime already installed.`);
-
-    // Pull latest
     try {
       console.log(`  ${yellow("⏳")} Checking for updates...`);
       execSync("git pull --ff-only", { cwd: installDir, stdio: "ignore" });
@@ -861,7 +238,6 @@ async function initSoma() {
       console.log(`  ${green("✓")} Already current`);
     }
   } else {
-    // Clone from soma-beta (public — no auth needed)
     console.log(`  ${yellow("⏳")} Downloading Soma runtime...`);
     try {
       execSync(
@@ -879,7 +255,6 @@ async function initSoma() {
     }
   }
 
-  // Install Pi dependencies
   const pkgJson = join(installDir, "package.json");
   if (existsSync(pkgJson)) {
     console.log(`  ${yellow("⏳")} Installing dependencies... ${dim("(this may take a moment)")}`);
@@ -891,7 +266,6 @@ async function initSoma() {
     }
   }
 
-  // Restore preserved user files (from broken install repair)
   if (Object.keys(preservedFiles).length > 0) {
     for (const [f, content] of Object.entries(preservedFiles)) {
       try {
@@ -901,7 +275,6 @@ async function initSoma() {
     }
   }
 
-  // Verify — gate success on actual working install
   const hasExts = existsSync(join(installDir, "dist", "extensions"));
   const hasCore = existsSync(join(installDir, "dist", "core"));
 
@@ -915,7 +288,6 @@ async function initSoma() {
 
   console.log(`  ${green("✓")} Extensions and core ready`);
 
-  // Save config
   const config = readConfig();
   config.installedAt = config.installedAt || new Date().toISOString();
   config.coreVersion = getAgentVersion() || VERSION;
@@ -927,6 +299,8 @@ async function initSoma() {
   console.log("");
 }
 
+// ── Update / Status ──────────────────────────────────────────────────
+
 async function checkAndUpdate() {
   printSigma();
   console.log(`  ${bold("Soma")} — Status`);
@@ -935,7 +309,6 @@ async function checkAndUpdate() {
   const config = readConfig();
   const installPath = config.installPath || join(SOMA_HOME, "agent");
 
-  // Check current version
   let currentHash = "";
   try {
     currentHash = execSync("git rev-parse --short HEAD", {
@@ -946,7 +319,6 @@ async function checkAndUpdate() {
     console.log(`  ${green("✓")} Core installed`);
   }
 
-  // Check for updates
   let behind = 0;
   try {
     console.log(`  ${yellow("⏳")} Checking for updates...`);
@@ -968,7 +340,6 @@ async function checkAndUpdate() {
   if (behind === 0) {
     console.log(`  ${green("✓")} Already up to date.`);
 
-    // Check project version staleness even when runtime is current
     const agentV = getAgentVersion();
     const projectV = getProjectVersion();
     if (agentV && projectV && projectV < agentV) {
@@ -985,7 +356,6 @@ async function checkAndUpdate() {
   console.log(`  ${cyan("⬆")} ${bold(`${behind} update${behind !== 1 ? "s" : ""} available.`)}`);
   console.log("");
 
-  // Show what changed
   try {
     const log = execSync(
       `git log HEAD..origin/main --oneline --no-decorate -5`,
@@ -1010,7 +380,6 @@ async function checkAndUpdate() {
     return;
   }
 
-  // Pull + reinstall deps
   console.log("");
   try {
     execSync("git pull --ff-only", { cwd: installPath, stdio: "ignore" });
@@ -1028,7 +397,6 @@ async function checkAndUpdate() {
     }
   }
 
-  // Reinstall deps if package.json changed
   try {
     const pkgChanged = execSync(
       `git diff HEAD~${behind} HEAD --name-only -- package.json package-lock.json`,
@@ -1061,7 +429,6 @@ function checkForUpdates() {
 
   const config = readConfig();
 
-  // Check npm for CLI updates
   try {
     const latest = execSync("npm view meetsoma version 2>/dev/null", { encoding: "utf-8" }).trim();
     if (latest && latest !== VERSION && latest > VERSION) {
@@ -1075,10 +442,8 @@ function checkForUpdates() {
     console.log(`  ${dim("Could not check npm registry")}`);
   }
 
-  // Check core updates (pull latest if git repo)
   if (isInstalled() && config.installPath) {
     try {
-      // Fetch first so rev-list has fresh data
       execSync("git fetch origin --quiet", { cwd: config.installPath, stdio: "ignore", timeout: 10000 });
       const branch = execSync("git rev-parse --abbrev-ref HEAD", {
         cwd: config.installPath, encoding: "utf-8"
@@ -1100,22 +465,23 @@ function checkForUpdates() {
   console.log("");
 }
 
+// ── Health Check ─────────────────────────────────────────────────────
+
 async function healthCheck() {
   printSigma();
   console.log(`  ${bold("Soma")} — Health Check`);
   console.log("");
 
   let issues = 0;
-  const check = (ok, pass, fail) => {
+  const check = (ok, pass, fail_msg) => {
     if (ok) { console.log(`  ${green("✓")} ${pass}`); }
-    else { console.log(`  ${red("✗")} ${fail}`); issues++; }
+    else { console.log(`  ${red("✗")} ${fail_msg}`); issues++; }
   };
-  const warn = (ok, pass, fail) => {
+  const warn = (ok, pass, fail_msg) => {
     if (ok) { console.log(`  ${green("✓")} ${pass}`); }
-    else { console.log(`  ${yellow("⚠")} ${fail}`); }
+    else { console.log(`  ${yellow("⚠")} ${fail_msg}`); }
   };
 
-  // Node.js
   const nodeVersion = process.versions.node;
   const [major, minor] = nodeVersion.split(".").map(Number);
   check(major > 20 || (major === 20 && minor >= 6),
@@ -1123,15 +489,12 @@ async function healthCheck() {
     `Node.js ${nodeVersion} — requires ≥20.6.0`
   );
 
-  // ~/.soma directory
   check(existsSync(SOMA_HOME), "~/.soma/ exists", "~/.soma/ not found — run: soma init");
 
-  // Core installation
   const installed = isInstalled();
   check(installed, "Core installed", "Core not installed — run: soma init");
 
   if (installed) {
-    // Extensions (check both dist/ layout and dev layout)
     const extDir = existsSync(join(CORE_DIR, "dist", "extensions"))
       ? join(CORE_DIR, "dist", "extensions")
       : join(CORE_DIR, "extensions");
@@ -1140,13 +503,11 @@ async function healthCheck() {
       check(exts.length >= 6, `${exts.length} extensions`, `Only ${exts.length} extensions (expected ≥6)`);
     }
 
-    // Core modules
     const coreDir = existsSync(join(CORE_DIR, "dist", "core"))
       ? join(CORE_DIR, "dist", "core")
       : join(CORE_DIR, "core");
     check(existsSync(coreDir), "Core modules present", "Core modules missing");
 
-    // Git repo health (skip in dev mode — no .git when using symlinks)
     if (existsSync(join(CORE_DIR, ".git"))) {
       try {
         execSync("git status --porcelain", { cwd: CORE_DIR, stdio: "ignore" });
@@ -1155,7 +516,6 @@ async function healthCheck() {
         warn(false, "", "Core git repo has issues");
       }
     } else {
-      // Dev mode — core/ is symlinked, no .git expected
       try {
         const realCore = readlinkSync(join(CORE_DIR, "core"));
         if (realCore) {
@@ -1169,7 +529,6 @@ async function healthCheck() {
     }
   }
 
-  // API key (check env + auth.json + shell config)
   const hasAuth = hasAnyAuth();
   if (hasAuth) {
     console.log(`  ${green("✓")} API key configured`);
@@ -1182,7 +541,6 @@ async function healthCheck() {
     }
   }
 
-  // Git
   try {
     const gitV = execSync("git --version", { encoding: "utf-8" }).trim();
     check(true, gitV, "");
@@ -1193,7 +551,6 @@ async function healthCheck() {
   console.log("");
   if (issues === 0) {
     console.log(`  ${green("✓ All checks passed")}`);
-
   } else {
     console.log(`  ${yellow(`${issues} issue${issues > 1 ? "s" : ""} found`)}`);
     console.log(`  ${voice.say("suggest", { suggestion: issues > 2 ? "start with soma init" : "check the items above" })}`);
@@ -1201,12 +558,14 @@ async function healthCheck() {
   console.log("");
 }
 
+// ── Project Doctor ───────────────────────────────────────────────────
+// (large function — kept inline to avoid breaking the complex doctor logic)
+
 async function projectDoctor() {
   const doctorArgs = args.slice(1);
   const wantsScan = doctorArgs.includes("--scan");
   const wantsAll = doctorArgs.includes("--all");
 
-  // --scan and --all need the runtime — delegate to core
   if ((wantsScan || wantsAll) && isInstalled()) {
     await delegateToCore();
     return;
@@ -1226,7 +585,6 @@ async function projectDoctor() {
     return;
   }
 
-  // Version overview
   console.log(`  Agent:   ${cyan(`v${agentV || "unknown"}`)}`);
   if (projectV) {
     console.log(`  Project: ${cyan(`v${projectV}`)}`);
@@ -1252,21 +610,19 @@ async function projectDoctor() {
   }
 
   if (agentV && projectV === agentV) {
-    console.log(`  ${green("\u2713")} Project is up to date.`);
+    console.log(`  ${green("✓")} Project is up to date.`);
     console.log("");
     await healthCheck();
     return;
   }
   
   if (agentV && projectV < agentV) {
-    console.log(`  ${yellow("\u26a0")} Project .soma/ is at ${cyan(`v${projectV}`)} , agent is at ${cyan(`v${agentV}`)} .`);
+    console.log(`  ${yellow("⚠")} Project .soma/ is at ${cyan(`v${projectV}`)} , agent is at ${cyan(`v${agentV}`)} .`);
     console.log("");
   
-    // Tier 1: Auto-fix safe things right now
     let fixes = 0;
     const somaDir = join(process.cwd(), ".soma");
   
-    // Add missing settings keys
     const settingsPath = join(somaDir, "settings.json");
     if (existsSync(settingsPath)) {
       try {
@@ -1280,29 +636,26 @@ async function projectDoctor() {
         add("scratch", { autoInject: false });
         add("guard", { coreFiles: "warn", bashCommands: "warn", gitIdentity: null });
         add("checkpoints", { enabled: true, intervalMinutes: 5, squashOnPush: true });
-        add("persona", { name: null, emoji: "\u03c3" });
+        add("persona", { name: null, emoji: "σ" });
         add("inherit", { identity: true, protocols: true, muscles: true, tools: true });
         if (changed) writeFileSync(settingsPath, JSON.stringify(current, null, "\t") + "\n");
       } catch {}
     }
   
-    // Add missing body/ + templates
     const bodyDir = join(somaDir, "body");
-    // Resolve agent root — follow dev symlinks if needed
-  let agentRoot = CORE_DIR;
-  try {
-    const realCore = readlinkSync(join(CORE_DIR, "core"));
-    if (realCore) {
-      const devRoot = dirname(realCore);
-      if (existsSync(join(devRoot, "body", "_public"))) agentRoot = devRoot;
+    let agentRoot = CORE_DIR;
+    try {
+      const realCore = readlinkSync(join(CORE_DIR, "core"));
+      if (realCore) {
+        const devRoot = dirname(realCore);
+        if (existsSync(join(devRoot, "body", "_public"))) agentRoot = devRoot;
+      }
+    } catch {}
+    if (!existsSync(join(agentRoot, "body", "_public"))) {
+      const parent = dirname(agentRoot);
+      if (existsSync(join(parent, "body", "_public"))) agentRoot = parent;
     }
-  } catch {}
-  // Also check dist/ parent (prod layout)
-  if (!existsSync(join(agentRoot, "body", "_public"))) {
-    const parent = dirname(agentRoot);
-    if (existsSync(join(parent, "body", "_public"))) agentRoot = parent;
-  }
-  const bundledBody = join(agentRoot, "body", "_public");
+    const bundledBody = join(agentRoot, "body", "_public");
     if (existsSync(bundledBody)) {
       try {
         if (!existsSync(bodyDir)) mkdirSync(bodyDir, { recursive: true });
@@ -1313,7 +666,6 @@ async function projectDoctor() {
       } catch {}
     }
   
-    // Add missing protocols
     const protoDir = join(somaDir, "amps", "protocols");
     const bundledProtos = existsSync(join(CORE_DIR, "dist", "content", "protocols"))
       ? join(CORE_DIR, "dist", "content", "protocols")
@@ -1327,7 +679,6 @@ async function projectDoctor() {
       }
     }
   
-    // Add missing bundled scripts
     const scriptsDir = join(somaDir, "amps", "scripts");
     const bundledScripts = existsSync(join(agentRoot, "dist", "content", "scripts"))
       ? join(agentRoot, "dist", "content", "scripts")
@@ -1346,20 +697,18 @@ async function projectDoctor() {
       }
     }
 
-    // Bump version after fixes
     if (fixes > 0) {
       try {
         const s = JSON.parse(readFileSync(settingsPath, "utf-8"));
         s.version = agentV;
         writeFileSync(settingsPath, JSON.stringify(s, null, "\t") + "\n");
       } catch {}
-      console.log(`  ${green("\u2713")} Applied ${fixes} automatic fixes`);
+      console.log(`  ${green("✓")} Applied ${fixes} automatic fixes`);
       const bc = existsSync(join(somaDir, "body")) ? readdirSync(join(somaDir, "body")).filter(f => f.endsWith(".md")).length : 0;
       const pc = existsSync(protoDir) ? readdirSync(protoDir).filter(f => f.endsWith(".md")).length : 0;
       console.log(`    ${bc} body files, ${pc} protocols, settings updated`);
       console.log(`    Version bumped to ${cyan(`v${agentV}`)}`);
 
-      // Scan + fix stale protocols (exist but differ from bundled)
       let staleUpdated = 0;
       let staleSkipped = [];
       if (bundledProtos && existsSync(protoDir)) {
@@ -1370,7 +719,6 @@ async function projectDoctor() {
           const bundledRaw = readFileSync(bundledFile, "utf-8");
           const strip = s => s.replace(/^(heat|loads|runs|last-run|heat-default):.*\n?/gm, "").trim();
           if (strip(projRaw) === strip(bundledRaw)) continue;
-          // Preserve user's runtime fields (heat, loads) when updating content
           const heatLine = projRaw.match(/^heat:.*$/m);
           const loadsLine = projRaw.match(/^loads:.*$/m);
           let updated = bundledRaw;
@@ -1383,11 +731,11 @@ async function projectDoctor() {
 
       console.log("");
       if (staleUpdated > 0) {
-        console.log(`  ${green("\u2713")} ${staleUpdated} protocols updated to latest version`);
-        console.log(`  ${dim("Heat and load counts preserved. Content updated (coaching-voice rewrites, new TL;DR).")}`);
+        console.log(`  ${green("✓")} ${staleUpdated} protocols updated to latest version`);
+        console.log(`  ${dim("Heat and load counts preserved. Content updated.")}`);
       }
       if (staleSkipped.length > 0) {
-        console.log(`  ${yellow("\u26a0")} ${staleSkipped.length} protocols skipped (may be customized)`);
+        console.log(`  ${yellow("⚠")} ${staleSkipped.length} protocols skipped (may be customized)`);
       }
       console.log("");
       const totalRemaining = staleSkipped.length;
@@ -1396,118 +744,41 @@ async function projectDoctor() {
         console.log(`  ${dim("Remaining: " + totalRemaining + " items need review.")}`);
         console.log(`  ${dim("For full migration:")} ${green("soma")} ${dim("then")} ${green("/soma doctor")}`);
       } else {
-        console.log(`  ${green("\u2713")} Full migration complete from CLI.`);
+        console.log(`  ${green("✓")} Full migration complete from CLI.`);
         console.log(`  ${dim("No TUI session needed — all updates applied.")}`);
       }
 
-      // Write _doctor-pending.md — only if there are remaining items for the agent
-      // If CLI handled everything, write a brief "complete" note instead
+      // Write _doctor-pending.md
       try {
         const pendingPath = join(somaDir, "body", "_doctor-pending.md");
         if (staleSkipped.length === 0) {
-          // Full migration done — write brief completion note
           const done = [
-            "---",
-            "type: template",
-            "name: doctor-pending",
-            "status: complete",
+            "---", "type: template", "name: doctor-pending", "status: complete",
             `created: ${new Date().toISOString().split("T")[0]}`,
-            "description: CLI doctor completed full migration — verify with /soma doctor then delete this file",
-            "---",
-            "",
-            "# Doctor Update — Complete",
-            "",
-            `The CLI doctor migrated this project from v${projectV} to v${agentV} on ${new Date().toISOString().split("T")[0]}.`,
-            "",
-            `Applied: ${fixes} file fixes + ${staleUpdated} protocol updates. All settings, body, scripts, protocols current.`,
-            "",
-            "Run \`/soma doctor\` to verify, then delete this file.",
+            "description: CLI doctor completed full migration", "---", "",
+            "# Doctor Update — Complete", "",
+            `Migrated from v${projectV} to v${agentV} on ${new Date().toISOString().split("T")[0]}.`,
+            `Applied: ${fixes} file fixes + ${staleUpdated} protocol updates.`, "",
+            "Run `/soma doctor` to verify, then delete this file.",
           ];
           writeFileSync(pendingPath, done.join("\n"));
-        } else {
-        const pending = [
-          "---",
-          "type: template",
-          "name: doctor-pending",
-          "status: active",
-          `created: ${new Date().toISOString().split("T")[0]}`,
-          "description: Written by soma doctor CLI — tells the agent what was fixed and what needs attention",
-          "---",
-          "",
-          "# Doctor Update — Pending",
-          "",
-          `The CLI doctor ran on ${new Date().toISOString().split("T")[0]} and updated this project from v${projectV} to v${agentV}.`,
-          "",
-          "## What the CLI fixed (Tier 1 — automatic, safe)",
-          "",
-          `- ${bc} body template files (added missing ones, preserved your customized files)`,
-          `- ${pc} protocols present (added missing bundled protocols)`,
-          `- Settings: added missing configuration sections with safe defaults`,
-          `- Version bumped to v${agentV}`,
-          "",
-          `## What the CLI also fixed`,
-          "",
-          `- ${staleUpdated} protocols updated to latest version (heat/loads preserved)`,
-          "",
-          staleSkipped.length > 0 ? `## What still needs attention (${staleSkipped.length} items)` : "## Status: Complete",
-          "",
-          staleSkipped.length > 0 
-            ? `**${staleSkipped.length} protocols** may be customized and were not auto-updated. The agent needs to:\n- Diff each against bundled version\n- Decide whether to update or preserve`
-            : "All mechanical updates applied by CLI. The agent can verify with /soma doctor.",
-          "",
-          "**To complete the migration:**",
-          "",
-          "Read the migration phases that apply to your version jump:",
-          "```",
-        ];
-        // Find which phases apply (only from projectV onward)
-        let agentRoot2 = CORE_DIR;
-        try {
-          const rc = readlinkSync(join(CORE_DIR, "core"));
-          if (rc) { const dr = dirname(rc); if (existsSync(join(dr, "migrations", "phases"))) agentRoot2 = dr; }
-        } catch {}
-        if (!existsSync(join(agentRoot2, "migrations", "phases"))) {
-          const pr = dirname(agentRoot2);
-          if (existsSync(join(pr, "migrations", "phases"))) agentRoot2 = pr;
-        }
-        const phasesDir2 = join(agentRoot2, "migrations", "phases");
-        if (existsSync(phasesDir2)) {
-          const allPhases = readdirSync(phasesDir2).filter(f => f.endsWith(".md")).sort();
-          const relevant = allPhases.filter(f => {
-            const m = f.match(/^v([\d.]+)-to-v/);
-            return m && m[1] >= projectV;
-          });
-          pending.push(`${relevant.length} phases apply (v${projectV} \u2192 v${agentV}):`);
-          pending.push("\`\`\`");
-          for (const f of relevant) {
-            pending.push("  " + join(phasesDir2, f));
-          }
         }
-        pending.push("```");
-        pending.push("");
-        pending.push("Execute each phase's **Actions** section in order.");
-        pending.push("After completing all phases, delete this file — it's no longer needed.");
-        pending.push("");
-        writeFileSync(pendingPath, pending.join("\n"));
-      }
-      } catch { /* non-fatal */ }
+      } catch {}
     } else {
-      console.log(`  ${green("\u2713")} Version bumped to ${cyan(`v${agentV}`)}`);
+      console.log(`  ${green("✓")} Version bumped to ${cyan(`v${agentV}`)}`);
       console.log(`  ${dim("No file changes needed — project structure is current.")}`);
     }
   } else {
-    console.log(`  ${green("\u2713")} Project version: ${cyan(`v${projectV}`)}`);
+    console.log(`  ${green("✓")} Project version: ${cyan(`v${projectV}`)}`);
   }
   
   console.log("");
   await healthCheck();
 }
 
-
 // ── Delegation ───────────────────────────────────────────────────────
 
 async function delegateToCore() {
-  // Pre-flight: verify runtime can start before delegating
   const piPkg = join(CORE_DIR, "node_modules", "@mariozechner", "pi-coding-agent");
   if (!existsSync(piPkg)) {
     console.log(`  ${red("✗")} Runtime dependencies missing.`);
@@ -1528,7 +799,6 @@ async function delegateToCore() {
     return;
   }
 
-  const { execFileSync: execF } = await import("child_process");
   const passArgs = process.argv.slice(2);
 
   const cliLocations = [
@@ -1536,9 +806,6 @@ async function delegateToCore() {
     { path: join(CORE_DIR, "node_modules", ".bin", "pi"),  type: "bin" },
   ];
 
-  // Discover user extensions in project .soma/extensions/
-  // Pi without piConfig only looks at .pi/extensions/, not .soma/extensions/
-  // We pass them explicitly via -e flags
   const userExtArgs = [];
   const projectExtDir = join(process.cwd(), ".soma", "extensions");
   if (existsSync(projectExtDir)) {
@@ -1552,14 +819,8 @@ async function delegateToCore() {
 
   const env = {
     ...process.env,
-    // Pi reads ENV_AGENT_DIR dynamically based on APP_NAME from piConfig.
-    // With piConfig.name="soma", Pi looks for SOMA_CODING_AGENT_DIR.
-    // Without piConfig (raw pi binary), it looks for PI_CODING_AGENT_DIR.
-    // Set BOTH so delegation works regardless of piConfig load order.
     PI_CODING_AGENT_DIR: CORE_DIR,
     SOMA_CODING_AGENT_DIR: CORE_DIR,
-    // Override Pi's package dir so it reads piConfig from soma-beta's package.json
-    // This gives us APP_NAME="soma", CONFIG_DIR_NAME=".soma" → project .soma/ paths
     PI_PACKAGE_DIR: CORE_DIR,
   };
 
@@ -1568,15 +829,13 @@ async function delegateToCore() {
       try {
         const allArgs = [...userExtArgs, ...passArgs];
         if (cli.type === "node") {
-          execF("node", [cli.path, ...allArgs], { stdio: "inherit", cwd: process.cwd(), env });
+          execFileSync("node", [cli.path, ...allArgs], { stdio: "inherit", cwd: process.cwd(), env });
         } else {
-          execF(cli.path, allArgs, { stdio: "inherit", cwd: process.cwd(), env });
+          execFileSync(cli.path, allArgs, { stdio: "inherit", cwd: process.cwd(), env });
         }
         return;
       } catch (err) {
-        // Non-zero exit from session is normal (user quit, ctrl+c)
         if (err.status) process.exit(err.status);
-        // Module errors = broken install
         if (err.message && err.message.includes("MODULE_NOT_FOUND")) {
           console.log("");
           console.log(`  ${red("✗")} Soma failed to start — missing dependencies.`);
@@ -1603,7 +862,6 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
   showVersion();
 } else if (cmd === "--help" || cmd === "-h") {
   if (isInstalled()) {
-    // Delegate to core — richer help with scripts, commands, hub
     await delegateToCore();
   } else {
     showHelp();
@@ -1616,13 +874,10 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
   const hasSomaDir = existsSync(join(process.cwd(), ".soma"));
   
   if (!runtimeInstalled) {
-    // Not installed — run full install + setup
     await initSoma();
   } else if (hasProjectArgs || !hasSomaDir) {
-    // Installed, project init (new project or --template/--orphan)
     await delegateToCore();
   } else {
-    // Installed + .soma/ exists — check for updates + project staleness
     await checkAndUpdate();
   }
 } else if (cmd === "update") {
@@ -1632,10 +887,8 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
 } else if (cmd === "status" || cmd === "health") {
   await healthCheck();
 } else if (isInstalled()) {
-  // Core installed — delegate to runtime
   await delegateToCore();
 } else {
-  // Check if user typed a known post-install command
   const postInstallCmds = ["focus", "inhale", "content", "install", "list", "map", "--map", "--preload"];
   if (cmd && postInstallCmds.includes(cmd)) {
     printSigma();
@@ -1644,7 +897,6 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
     console.log(`  Run ${green("soma init")} to install it.`);
     console.log("");
   } else {
-    // Not installed or not verified — show welcome experience
     await showWelcome();
   }
 }