meetsoma 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to Soma (`meetsoma` on npm).
 
 Format follows [Keep a Changelog](https://keepachangelog.com/). Versioning follows [Semantic Versioning](https://semver.org/).
 
+## [0.1.4] — 2026-03-28
+
+Corresponds to Soma agent v0.6.5.
+
+### New
+
+- **`soma inhale --list`** — see available preloads with age and staleness markers.
+- **`soma inhale <name>`** — load a specific preload by date, session ID, or substring.
+- **`soma inhale --load <path>`** — load any file as a preload.
+- **`soma map <name>`** — run a MAP with prompt-config and targeted preload.
+- **`soma map --list`** — see available MAPs with status and description.
+- **`--preload` flag deprecated** — use `soma inhale` or `soma map` instead (still works).
+
+### Changed
+
+- **Settings-driven heat overrides** — per-project AMPS heat control via `settings.heat.overrides`.
+- **Statusline** shows preload status. Smart `/exhale` detects edit vs write mode.
+- **Restart signal** — auto-detects when extensions change, prompts for restart.
+
+### Fixed
+
+- **Crash on partial settings** — `settings.heat` access now defensive (won't crash with old config files).
+- **Breathe grace period** — was 60s, now correctly 30s matching settings default.
+- **5 auto-breathe UX gaps** — smarter context warnings, resume awareness.
+
+---
+
 ## [0.1.3] — 2026-03-23
 
 ### New

package/dist/personality.js

@@ -246,9 +246,9 @@ const TOPICS = {
   // ── Practical / instructional ───────────────────────────────────────
 
   how_to_install: [
-    `{Three steps|Here's the short version|Pretty quick}. {First|Step one}: run ${"`soma init`"} {right here in your terminal|from any directory|from this CLI}. It'll {check your GitHub identity|verify who you are via GitHub|use your GitHub account} and {set everything up|install the runtime|get you running}. {You'll need|Requirements}: {Node.js 20+|Node 20 or newer} and the {GitHub CLI|gh command-line tool} (${"`brew install gh`"} {if you don't have it|on Mac|to get it}). {That's it|Nothing else|No other dependencies}.`,
+    `{Press Enter|Just hit Enter|Enter} and {I'll walk you through it|Soma handles the rest|the setup takes about a minute}. It {downloads the runtime|grabs everything you need|installs automatically}, {sets up your API key|walks you through authentication|helps you connect an AI provider}, and {you're ready to go|you can start right away|launches your first session}. {All you need is|Requirements:} {Node.js 20+|Node 20 or newer} and {git|git installed}. {That's it|Nothing else to do|One flow, start to finish}.`,
 
-    `Run ${"`soma init`"} — {it handles everything|that's the whole process|one command}. It {downloads the runtime|grabs the latest version|pulls everything you need} and {sets up Soma|installs dependencies|gets you running}. {Takes about a minute|Under 60 seconds|Quick}. {Just need|Requirements:} {Node.js 20+|Node 20 or newer} and {git|git installed}.`,
+    `{Hit Enter|Press Enter|Just Enter} — {Soma walks you through everything|the setup is guided|it's step by step}. {Downloads the runtime|Installs the engine|Gets everything ready}, {helps you set up an API key|handles authentication|connects you to an AI provider}, {done in about a minute|quick setup|takes sixty seconds}. {Need|Requirements:} {Node.js 20+|Node 20 or newer} and {git|git installed}.`,
   ],
 
   how_to_source: [
@@ -266,7 +266,7 @@ const TOPICS = {
   ],
 
   how_to_api_key: [
-    `{Yes|You'll need one|Required for sessions}. Soma uses {an LLM provider|an AI model|a language model} under the hood — {Anthropic (Claude)|Claude by default|Anthropic's Claude}, but {also supports|works with} {Google (Gemini)|OpenAI|other providers}. Set {your API key|it} as an environment variable: ${"`export ANTHROPIC_API_KEY=sk-...`"} {before running|in your shell|in your .bashrc/.zshrc}. {The key is yours|You bring your own key|We don't provide one} — {Soma never sees your key|it stays on your machine|nothing gets sent to us}.`,
+    `{Yes|You'll need one|Required}, but {Soma walks you through it|the setup handles it|we'll set it up together} when you install. {You bring your own key|It's your key|You get one from Anthropic} — {Soma stores it locally|it stays on your machine|nothing gets sent to us}. {If you have a Claude Pro or Max subscription|Got a Claude subscription?|Claude Pro/Max users}, you can {log in with your account instead|skip the API key entirely|use OAuth — no key needed}. {Press Enter to get started|Hit Enter and I'll walk you through it|Ready? Just press Enter}.`,
   ],
 
   how_to_model: [
@@ -274,7 +274,7 @@ const TOPICS = {
   ],
 
   how_to_start: [
-    `{Here's the path|Three steps|Quick start}: {1.|First,} run ${"`soma init`"} to {install the runtime|get set up|install everything}. {2.|Then} ${"`cd`"} into {any project|your project|a directory with code}. {3.|Finally,} run ${"`soma`"} — {it creates|Soma creates|it'll make} a ${"`~/.soma/`"} directory, {detects your stack|scans your project|figures out what you're building}, and {starts learning|begins adapting|you're off}. {First session is minimal|Session one is bare|It starts simple}. {By session five|After a few sessions|Give it a week} — {it knows your patterns|it's adapted to how you work|you'll feel the difference}.`,
+    `{Press Enter|Hit Enter|Just Enter} — {Soma handles everything|the setup is guided|I'll walk you through it}. {Installs the runtime|Downloads what you need|Gets everything ready}, {helps you connect an AI provider|sets up your API key|handles auth}, and {you can launch right away|your first session starts immediately|you're coding in about a minute}. After that, {cd into any project|go to a project directory} and run ${"`soma`"} — {it creates a .soma/ directory|Soma sets up in your project} and {starts learning how you work|begins adapting|picks up your patterns}. {By session five|After a few sessions|Give it a week} — {you'll feel the difference|it knows your workflow|it remembers everything}.`,
   ],
 
   how_to_try: [

package/dist/postinstall.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js — runs after `npm install -g meetsoma`
+ *
+ * If we're in an interactive terminal, launch the welcome/setup flow.
+ * If not (CI, piped, scripts), just print a short message.
+ */
+
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { execFileSync } from "child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+if (process.stdin.isTTY && process.stdout.isTTY) {
+  // Interactive — run the full welcome + setup
+  try {
+    execFileSync("node", [join(__dirname, "thin-cli.js")], {
+      stdio: "inherit",
+      cwd: process.env.HOME || process.env.USERPROFILE || process.cwd(),
+    });
+  } catch {
+    // Non-zero exit is fine (user ctrl+c, etc.)
+  }
+} else {
+  // Non-interactive — just tell them what to do
+  console.log("");
+  console.log("  ✓ Soma installed. Run \x1b[32msoma\x1b[0m to get started.");
+  console.log("");
+}

package/dist/thin-cli.js

@@ -8,7 +8,7 @@
  * For returning users: detects installed runtime → delegates to it.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, statSync } from "fs";
 import { join, dirname } from "path";
 import { homedir, platform } from "os";
 import { fileURLToPath } from "url";
@@ -89,6 +89,11 @@ async function confirm(prompt) {
   return true;
 }
 
+async function confirmYN(prompt) {
+  const key = await waitForKey(`${prompt} ${dim("[y/n]")} `);
+  return key.toLowerCase() === "y";
+}
+
 // ── Typing effect ────────────────────────────────────────────────────
 
 function sleep(ms) {
@@ -281,6 +286,42 @@ function readLine(prompt) {
   });
 }
 
+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.")}`);
@@ -290,7 +331,7 @@ async function interactiveQ() {
   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. I'll do my best.")}`);
+  console.log(`  ${dim("...or ask anything. Press")} ${green("Enter")} ${dim("when you're ready to install.")}`);
 
   let rounds = 0;
   const maxRounds = 8;
@@ -299,56 +340,23 @@ async function interactiveQ() {
     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") {
-      console.log("");
-      await typeOut(`  ${voice.say("bye")}\n`);
       break;
     }
 
-    const match = matchQuestion(input);
-    if (match) {
-      const answer = voice.ask(match.topic);
-      console.log("");
-      await typeParagraph(answer);
-      rounds++;
-
-      if (rounds < maxRounds) {
-        console.log("");
-        console.log(`  ${dim("Ask another, or")} ${green("Enter")} ${dim("to install Soma.")}`);
-      }
-    } else {
-      // 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);
+    await handleQuestion(input);
+    rounds++;
 
+    if (rounds < maxRounds) {
       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 {
-        await typeParagraph(voice.ask("meta_nonsense"));
-      }
+      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 get you in.")}\n`);
-    console.log("");
-    await confirm(`  ${dim("→")} Press ${bold("Enter")} to install Soma`);
-    if (openBrowser(SITE_URL)) {
-      console.log(`  ${green("✓")} Opened ${cyan(SITE_URL)}`);
-    } else {
-      console.log(`  ${dim("→")} Visit: ${cyan(SITE_URL)}`);
-    }
+    await typeOut(`  ${voice.spin("{Curious enough?|Intrigued?|Want to see it in action?}")} ${dim("Let's set you up.")}\n`);
   }
 }
 
@@ -369,6 +377,201 @@ function getGitHubUsername() {
 
 // ── 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 ─────────────────────────────────────────────
+
 async function showWelcome() {
   printSigma();
   console.log(`  ${bold("Soma")} ${dim("—")} ${white("the AI agent that remembers")}`);
@@ -381,32 +584,74 @@ async function showWelcome() {
     if (ghUser) {
       console.log(`  ${green("✓")} ${voice.greetBack(ghUser)}`);
     }
-    console.log(`  ${green("✓")} Core installed. Starting Soma...`);
+
+    if (!hasAnyAuth()) {
+      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.`);
+        console.log(`  ${dim("Restart your terminal and run")} ${green("soma")} ${dim("again.")}`);
+        console.log("");
+        return;
+      }
+
+      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("");
+        console.log(`  ${dim(`v${VERSION} · BSL 1.1 · soma.gravicity.ai`)}`);
+        console.log("");
+        return;
+      }
+    } else {
+      console.log(`  ${green("✓")} Core installed. Starting Soma...`);
+    }
     console.log("");
     await delegateToCore();
     return;
   }
 
-  // Not installed — show a concept + offer to set up
-  const concept = CONCEPTS[getConceptIndex()];
-  const body = getConceptBody(concept.topic);
+  // ── Not installed — first time ever ────────────────────────────────
 
-  console.log(`  ${magenta("❝")} ${bold(concept.title)}`);
+  await typeOut(`  ${voice.greet()}\n`);
   console.log("");
-  await typeParagraph(body);
+  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.");
   console.log("");
   console.log(`  ${dim("─".repeat(58))}`);
   console.log("");
-  console.log(`  ${dim("→")} ${green("Enter")}  Install Soma`);
-  console.log(`  ${dim("→")} ${green("?")}      Ask me something first`);
+  console.log(`  ${dim("→")} Press ${green("Enter")} to set up, or type a question.`);
   console.log("");
 
-  const key = await waitForKey(`  ${dim("Your move:")} `);
+  const input = await readLine(`  ${dim("→")} `);
 
-  if (key === "?") {
+  if (input && input !== "") {
+    await handleQuestion(input);
     await interactiveQ();
-  } else {
-    await initSoma();
+  }
+
+  // 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("");
+    const launch = await confirmYN(`  ${voice.spin("{Ready to go?|Want to start your first session?|Launch Soma?}")}`);
+    if (launch) {
+      console.log("");
+      await delegateToCore();
+      return;
+    }
   }
 
   console.log("");
@@ -429,7 +674,10 @@ function showHelp() {
   console.log(`    ${green("soma")}                   Start a session`);
   console.log(`    ${green("soma focus <keyword>")}   Start a focused session`);
   console.log(`    ${green("soma inhale")}            Resume from last session's preload`);
-  console.log(`    ${green("soma --map <name>")}      Load a specific workflow`);
+  console.log(`    ${green("soma inhale <name>")}     Load a specific preload by name`);
+  console.log(`    ${green("soma inhale --list")}     Show available preloads`);
+  console.log(`    ${green("soma map <name>")}        Load a specific workflow (MAP)`);
+  console.log(`    ${green("soma map --list")}        Show available MAPs`);
   console.log("");
   console.log(`  ${bold("Maintenance")}`);
   console.log(`    ${green("soma doctor")}            Verify installation health`);
@@ -512,7 +760,65 @@ async function initSoma() {
   const installDir = join(SOMA_HOME, "agent");
   mkdirSync(SOMA_HOME, { recursive: true });
 
-  if (existsSync(installDir)) {
+  // 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);
+      if (existsSync(fp)) {
+        try {
+          preservedFiles[f] = readFileSync(fp, "utf-8");
+          console.log(`  ${dim("→")} Preserving ${f}`);
+        } catch {}
+      }
+    }
+
+    // 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;
+
+    if (hasGit) {
+      console.log(`  ${yellow("⏳")} Repairing...`);
+      try {
+        execSync("git fetch origin", { cwd: installDir, stdio: "ignore", timeout: 30000 });
+        execSync("git reset --hard origin/main", { cwd: installDir, stdio: "ignore" });
+        console.log(`  ${green("✓")} Repaired from remote`);
+        repaired = true;
+      } catch {
+        console.log(`  ${yellow("!")} Repair failed — will re-download.`);
+      }
+    }
+
+    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 {
+        execSync(`mv "${installDir}" "${backup}"`, { stdio: "ignore" });
+        console.log(`  ${dim("Old files saved to")} ${dim(backup.replace(homedir(), "~"))}`);
+      } catch {
+        console.log(`  ${red("✗")} Could not move old installation aside.`);
+        console.log(`  ${dim("Try:")} mv ~/.soma/agent ~/.soma/agent-old && soma init`);
+        console.log("");
+        return;
+      }
+    }
+  }
+
+  if (isValidInstall) {
     console.log(`  ${dim("→")} Runtime already installed.`);
 
     // Pull latest
@@ -554,13 +860,30 @@ async function initSoma() {
     }
   }
 
-  // Verify
+  // Restore preserved user files (from broken install repair)
+  if (Object.keys(preservedFiles).length > 0) {
+    for (const [f, content] of Object.entries(preservedFiles)) {
+      try {
+        writeFileSync(join(installDir, f), content, { mode: 0o600 });
+        console.log(`  ${green("✓")} Restored ${f}`);
+      } catch {}
+    }
+  }
+
+  // Verify — gate success on actual working install
   const hasExts = existsSync(join(installDir, "dist", "extensions"));
   const hasCore = existsSync(join(installDir, "dist", "core"));
-  if (hasExts && hasCore) {
-    console.log(`  ${green("✓")} Extensions and core ready`);
+
+  if (!hasExts || !hasCore) {
+    console.log("");
+    console.log(`  ${red("✗")} Installation incomplete — core files missing.`);
+    console.log(`  ${dim("Try:")} rm -rf ~/.soma/agent && soma init`);
+    console.log("");
+    return;
   }
 
+  console.log(`  ${green("✓")} Extensions and core ready`);
+
   // Save config
   const config = readConfig();
   config.installedAt = config.installedAt || new Date().toISOString();
@@ -571,12 +894,118 @@ async function initSoma() {
   console.log("");
   console.log(`  ${green("✓")} ${bold("Soma is installed!")}`);
   console.log("");
-  console.log(`  Next steps:`);
-  console.log(`    ${cyan("1.")} ${green("cd <your-project>")}`);
-  console.log(`    ${cyan("2.")} ${green("soma")} to start your first session`);
+}
+
+async function checkAndUpdate() {
+  printSigma();
+  console.log(`  ${bold("Soma")} — Status`);
+  console.log("");
+
+  const config = readConfig();
+  const installPath = config.installPath || join(SOMA_HOME, "agent");
+
+  // Check current version
+  let currentHash = "";
+  try {
+    currentHash = execSync("git rev-parse --short HEAD", {
+      cwd: installPath, encoding: "utf-8"
+    }).trim();
+    console.log(`  ${green("✓")} Core installed ${dim(`(${currentHash})`)}`);
+  } catch {
+    console.log(`  ${green("✓")} Core installed`);
+  }
+
+  // Check for updates
+  let behind = 0;
+  try {
+    console.log(`  ${yellow("⏳")} Checking for updates...`);
+    execSync("git fetch origin --quiet", { cwd: installPath, stdio: "ignore", timeout: 15000 });
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      cwd: installPath, encoding: "utf-8"
+    }).trim();
+    const behindStr = execSync(
+      `git rev-list HEAD..origin/${branch} --count`,
+      { cwd: installPath, encoding: "utf-8" }
+    ).trim();
+    behind = parseInt(behindStr) || 0;
+  } catch {
+    console.log(`  ${dim("Could not check for updates.")}`);
+    console.log("");
+    return;
+  }
+
+  if (behind === 0) {
+    console.log(`  ${green("✓")} Already up to date.`);
+    console.log("");
+    console.log(`  ${dim("Soma is set up and ready.")} Run ${green("soma")} ${dim("in a project to start a session.")}`);
+    console.log("");
+    return;
+  }
+
+  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`,
+      { cwd: installPath, encoding: "utf-8" }
+    ).trim();
+    if (log) {
+      for (const line of log.split("\n")) {
+        console.log(`    ${dim("•")} ${line.slice(8)}`);
+      }
+      if (behind > 5) {
+        console.log(`    ${dim(`...and ${behind - 5} more`)}`);
+      }
+      console.log("");
+    }
+  } catch {}
+
+  const shouldUpdate = await confirmYN(`  ${dim("→")} Update now?`);
+  if (!shouldUpdate) {
+    console.log("");
+    console.log(`  ${dim("Skipped. Run")} ${green("soma init")} ${dim("anytime to update.")}`);
+    console.log("");
+    return;
+  }
+
+  // Pull + reinstall deps
+  console.log("");
+  try {
+    execSync("git pull --ff-only", { cwd: installPath, stdio: "ignore" });
+    console.log(`  ${green("✓")} Updated`);
+  } catch {
+    console.log(`  ${yellow("!")} Pull failed — trying reset...`);
+    try {
+      execSync("git reset --hard origin/main", { cwd: installPath, stdio: "ignore" });
+      console.log(`  ${green("✓")} Updated (reset)`);
+    } catch {
+      console.log(`  ${red("✗")} Update failed.`);
+      console.log(`  ${dim("Try:")} cd ~/.soma/agent && git pull`);
+      console.log("");
+      return;
+    }
+  }
+
+  // Reinstall deps if package.json changed
+  try {
+    const pkgChanged = execSync(
+      `git diff HEAD~${behind} HEAD --name-only -- package.json package-lock.json`,
+      { cwd: installPath, encoding: "utf-8" }
+    ).trim();
+    if (pkgChanged) {
+      console.log(`  ${yellow("⏳")} Updating dependencies...`);
+      execSync("npm install --omit=dev", { cwd: installPath, stdio: ["ignore", "ignore", "inherit"] });
+      console.log(`  ${green("✓")} Dependencies updated`);
+    }
+  } catch {}
+
+  const newHash = execSync("git rev-parse --short HEAD", {
+    cwd: installPath, encoding: "utf-8"
+  }).trim();
   console.log("");
-  console.log(`  Soma will create a ${dim(".soma/")} directory in your project`);
-  console.log(`  and begin learning how you work.`);
+  console.log(`  ${green("✓")} ${bold("Soma is up to date")} ${dim(`(${currentHash} → ${newHash})`)}`);
   console.log("");
 }
 
@@ -685,11 +1114,18 @@ async function doctor() {
     }
   }
 
-  // API key
-  warn(!!process.env.ANTHROPIC_API_KEY,
-    "ANTHROPIC_API_KEY set",
-    "ANTHROPIC_API_KEY not set — needed for sessions"
-  );
+  // API key (check env + auth.json + shell config)
+  const hasAuth = hasAnyAuth();
+  if (hasAuth) {
+    console.log(`  ${green("✓")} API key configured`);
+  } else {
+    const unloadedKey = detectKeyInShellConfig();
+    if (unloadedKey) {
+      console.log(`  ${yellow("⚠")} ${unloadedKey} found in ${dim(getShellConfigPath())} but not loaded — restart your terminal`);
+    } else {
+      console.log(`  ${yellow("⚠")} No API key — run ${green("soma")} to set one up`);
+    }
+  }
 
   // Git
   try {
@@ -813,7 +1249,20 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
 } else if (cmd === "about") {
   await showAbout();
 } else if (cmd === "init") {
-  await initSoma();
+  const hasProjectArgs = args.includes("--template") || args.includes("--orphan") || args.includes("-o");
+  const runtimeInstalled = isInstalled();
+  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, don't re-run setup
+    await checkAndUpdate();
+  }
 } else if (cmd === "update") {
   checkForUpdates();
 } else if (cmd === "doctor") {
@@ -825,7 +1274,7 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
   await delegateToCore();
 } else {
   // Check if user typed a known post-install command
-  const postInstallCmds = ["focus", "inhale", "content", "install", "list", "--map", "--preload"];
+  const postInstallCmds = ["focus", "inhale", "content", "install", "list", "map", "--map", "--preload"];
   if (cmd && postInstallCmds.includes(cmd)) {
     printSigma();
     console.log(`  ${bold("soma " + cmd)} requires the Soma runtime.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meetsoma",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Soma \u2014 the AI coding agent with self-growing memory",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist/thin-cli.js",
     "dist/personality.js",
+    "dist/postinstall.js",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"
@@ -34,6 +35,9 @@
     "type": "git",
     "url": "git+https://github.com/meetsoma/soma-agent.git"
   },
+  "scripts": {
+    "postinstall": "node dist/postinstall.js"
+  },
   "engines": {
     "node": ">=20.6.0"
   }