@holt-os/holt 0.14.3 → 0.15.1

package/README.md

@@ -195,7 +195,7 @@ A brain is an agent CLI installed and logged in on your machine. No API keys to
 
 ### Direct API brains
 
-A brain can also be a direct provider connection: no CLI install, your own key. Run `holt setting` and pick `[c] connect API brain`, or say yes to the API-brain question in `holt init`. Choose a provider (anthropic, openai, gemini), a model (suggestions offered, type anything), and a short name. For the key, paste a raw key (stored in `~/.holt/credentials.json`, mode 600) or give the name of an env var that holds it. Resolution order: the brain's `keyEnv`, the credentials file, then the standard env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`). API brains stream and share memory exactly like CLI brains; switch with `/brain <name>`.
+A brain can also be a direct provider connection: no CLI install, your own key. Run `holt setting` and pick `[c] connect API brain`, or say yes to the API-brain question in `holt init`. Choose a provider (anthropic, openai, gemini, kimi, grok), a model (suggestions offered, type anything), and a short name. Kimi (Moonshot) and Grok (xAI) speak the OpenAI wire format at their own endpoints; any other OpenAI-compatible endpoint (a gateway, a self-hosted server) works too via an optional `baseUrl` on the brain in `.holt/config.json`. For the key, paste a raw key (stored in `~/.holt/credentials.json`, mode 600) or give the name of an env var that holds it. Resolution order: the brain's `keyEnv`, the credentials file, then the standard env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `MOONSHOT_API_KEY`, `XAI_API_KEY`). API brains stream and share memory exactly like CLI brains; switch with `/brain <name>`.
 
 ## See your memory: `holt graph`
 
@@ -494,6 +494,14 @@ It reports, section by section:
 - **Always-on / Telegram**: whether a Telegram bot is set up, and a note on hosting the bot on a low-power always-on machine while keeping heavy local models on a bigger one.
 - **Recommended next steps**: a short checklist built from whatever gaps it found.
 
+And when you would rather not do the steps yourself:
+
+```bash
+holt doctor --fix
+```
+
+`--fix` repairs the common problems in one go: starts Ollama when it is installed but not running, downloads the missing embed model, upgrades any memories saved while embeddings were off, and reports a damaged-config repair if one happened. It ends with a "Repairs" section listing exactly what it did (or "Nothing needed repair"). Every Holt error message points here, so the answer to "something is off" is always the same one command.
+
 It is read-only advice: it changes nothing, needs no trust, and always exits cleanly even when a probe fails.
 
 The RAM-to-model table lives in `src/specs.ts` (`LOCAL_MODEL_RECS` / `recommendLocalModel`), the single source of truth the wiki maintainer reads too.
@@ -556,6 +564,11 @@ holt routine         named, reusable, scheduled jobs: add | run | list | show |
 holt telegram        chat with Holt from your phone: telegram [setup]
 holt notify [msg]    push a message to your phone over Telegram (stdin-friendly)
 holt doctor          check this machine and recommend how best to run Holt here
+                     ("holt doctor --fix" also repairs the common problems it finds:
+                      starts Ollama, pulls the embed model, mends a damaged config)
+holt tour            a 2-minute guided first run: ask, teach one fact, watch it remember
+holt update          get the latest Holt in one word (npm or Homebrew, auto-detected)
+holt reset           start this folder over (typed confirmation; your files untouched)
 holt voice           teach Holt your writing voice: add <file> | show | edit | clear
 holt write <what>    draft content in your voice with anti-AI checks (--type, --out, --fast)
 holt graph           see your memory as an interactive knowledge graph

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/config.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync } from "fs";
 import { join as join2 } from "path";
 
 // src/workspace.ts
@@ -11,6 +11,13 @@ import { mkdirSync, readFileSync, writeFileSync } from "fs";
 
 // src/ui.ts
 import readline from "readline";
+var quiet = false;
+function setQuietMode(q) {
+  quiet = q;
+}
+function isQuietMode() {
+  return quiet;
+}
 var on = process.stdout.isTTY && !process.env.NO_COLOR;
 var wrap = (code) => (s) => on ? `\x1B[${code}m${s}\x1B[0m` : s;
 var c = {
@@ -91,6 +98,18 @@ function createStatusBar() {
     detach
   };
 }
+async function askYesNo(ask, question, def) {
+  for (let tries = 0; tries < 3; tries++) {
+    const raw = await ask(question);
+    if (raw === null) return def;
+    const a = raw.trim().toLowerCase();
+    if (a === "") return def;
+    if (a === "y" || a === "yes") return true;
+    if (a === "n" || a === "no") return false;
+    console.log(c.dim(`  Just "y" or "n" please (enter = ${def ? "yes" : "no"}). You typed "${raw.trim()}".`));
+  }
+  return def;
+}
 function createReader() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const buffer = [];
@@ -148,8 +167,7 @@ async function ensureTrusted(ask) {
   console.log("\n" + c.accent("Trust this folder?"));
   console.log("  " + ws);
   console.log(c.dim("  Holt will read and write here: its config, memory, and any files you ask a brain to touch."));
-  const ans = (await ask("  Trust and continue? [y/N] ") ?? "").trim().toLowerCase();
-  if (ans === "y" || ans === "yes") {
+  if (await askYesNo(ask, "  Trust and continue? [y/N] ", false)) {
     trustDir(ws);
     console.log(c.green("  Trusted.") + c.dim(" (remembered for next time)") + "\n");
     return true;
@@ -162,10 +180,24 @@ function ensureWsDir() {
 }
 
 // src/config.ts
+var PROVIDER_WIRE = {
+  anthropic: "anthropic",
+  openai: "openai",
+  gemini: "gemini",
+  kimi: "openai",
+  grok: "openai"
+};
+var PROVIDER_BASE_URL = {
+  openai: "https://api.openai.com/v1",
+  kimi: "https://api.moonshot.ai/v1",
+  grok: "https://api.x.ai/v1"
+};
 var WIKI_DEFAULT_LOCAL_MODEL = "qwen2.5:7b";
 var BRAIN_DEFS = {
   claude: { label: "Claude Code", command: "claude", args: ["-p"] },
-  codex: { label: "Codex (OpenAI)", command: "codex", args: ["exec"] },
+  // --skip-git-repo-check: codex exec otherwise refuses to run in folders that
+  // are not git repositories, which is nearly every non-developer folder.
+  codex: { label: "Codex (OpenAI)", command: "codex", args: ["exec", "--skip-git-repo-check"] },
   gemini: { label: "Gemini CLI", command: "gemini", args: ["-p"] }
 };
 var BRAIN_SETUP = {
@@ -174,16 +206,20 @@ var BRAIN_SETUP = {
   gemini: { install: ["npm", "install", "-g", "@google/gemini-cli"], login: ["gemini"] }
 };
 var BRAIN_IDS = ["claude", "codex", "gemini"];
-var PROVIDERS = ["anthropic", "openai", "gemini"];
+var PROVIDERS = ["anthropic", "openai", "gemini", "kimi", "grok"];
 var PROVIDER_MODEL_SUGGESTION = {
   anthropic: "claude-sonnet-4-6",
   openai: "gpt-5",
-  gemini: "gemini-2.5-flash"
+  gemini: "gemini-2.5-flash",
+  kimi: "kimi-k2-turbo-preview",
+  grok: "grok-4"
 };
 var PROVIDER_ENV = {
   anthropic: "ANTHROPIC_API_KEY",
   openai: "OPENAI_API_KEY",
-  gemini: "GEMINI_API_KEY"
+  gemini: "GEMINI_API_KEY",
+  kimi: "MOONSHOT_API_KEY",
+  grok: "XAI_API_KEY"
 };
 function defaultConfig() {
   const brains = {};
@@ -201,14 +237,25 @@ function defaultConfig() {
     wiki: { maintainer: "brain", localModel: WIKI_DEFAULT_LOCAL_MODEL }
   };
 }
+var lastConfigRepair = null;
 function loadConfig() {
   const path = wsConfigPath();
   if (!existsSync2(path)) return null;
+  let raw;
   try {
-    const cfg = JSON.parse(readFileSync2(path, "utf8"));
+    raw = readFileSync2(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const cfg = JSON.parse(raw);
     const base = defaultConfig();
     const brains = cfg.brains ?? {};
     for (const id of BRAIN_IDS) if (!brains[id]) brains[id] = base.brains[id];
+    const cx = brains.codex;
+    if (cx && cx.command === "codex" && Array.isArray(cx.args) && !cx.args.includes("--skip-git-repo-check")) {
+      cx.args = [...cx.args, "--skip-git-repo-check"];
+    }
     const wikiIn = cfg.wiki ?? {};
     const wiki = {
       maintainer: wikiIn.maintainer === "local" ? "local" : "brain",
@@ -227,6 +274,18 @@ function loadConfig() {
       wiki
     };
   } catch {
+    const backup2 = `${path}.broken-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/[:T]/g, "")}`;
+    try {
+      renameSync(path, backup2);
+      lastConfigRepair = backup2;
+      if (!isQuietMode()) {
+        console.error(
+          c.red("\n  Your Holt settings file was damaged, so it was moved aside.") + c.dim(`
+  Saved at: ${backup2}`) + c.dim("\n  Holt will set this folder up fresh; your memory is untouched.\n")
+        );
+      }
+    } catch {
+    }
     return null;
   }
 }
@@ -310,7 +369,7 @@ function renderPrompt(history, message, memory = []) {
 function looksLikeAuthError(text) {
   try {
     if (!text) return false;
-    const re = /run\s+\/login|not\s+logged\s+in|invalid\s+api\s+key|please\s+(?:log|sign)\s+in|authentication\s+(?:failed|required)|unauthorized|session\s+(?:has\s+)?expired|no\s+api\s+key|login\s+required|credit\s+balance\s+is\s+too\s+low/i;
+    const re = /run\s+\/login|not\s+logged\s+in|invalid\s+api\s+key|please\s+(?:log|sign)\s+in|authentication\s+(?:failed|required)|unauthorized|session\s+(?:has\s+)?expired|no\s+api\s+key|login\s+required|credit\s+balance\s+is\s+too\s+low|set\s+an\s+auth\s+method|GEMINI_API_KEY/i;
     return re.test(text);
   } catch {
     return false;
@@ -967,7 +1026,8 @@ function dataLines(event) {
   }
   return out;
 }
-function extractDelta(provider, json) {
+function extractDelta(providerIn, json) {
+  const provider = PROVIDER_WIRE[providerIn];
   const j = json;
   if (provider === "anthropic") {
     if (j["type"] === "content_block_delta") {
@@ -987,7 +1047,8 @@ function extractDelta(provider, json) {
   return parts.map((p) => typeof p.text === "string" ? p.text : "").join("");
 }
 function buildRequest(brain, key, prompt) {
-  if (brain.provider === "anthropic") {
+  const wire = PROVIDER_WIRE[brain.provider];
+  if (wire === "anthropic") {
     return {
       url: "https://api.anthropic.com/v1/messages",
       headers: {
@@ -1003,9 +1064,10 @@ function buildRequest(brain, key, prompt) {
       })
     };
   }
-  if (brain.provider === "openai") {
+  if (wire === "openai") {
+    const base = (brain.baseUrl ?? PROVIDER_BASE_URL[brain.provider] ?? "https://api.openai.com/v1").replace(/\/$/, "");
     return {
-      url: "https://api.openai.com/v1/chat/completions",
+      url: `${base}/chat/completions`,
       headers: {
         "content-type": "application/json",
         authorization: `Bearer ${key}`
@@ -1318,9 +1380,9 @@ async function setupTelegram(ask) {
   console.log(c.dim("  Option A: open your new bot in Telegram and send it any message,"));
   console.log(c.dim("            then I will auto-detect the chat id."));
   console.log(c.dim("  Option B: paste a numeric chat id yourself."));
-  const mode = (await ask("\n  Auto-detect from a message you just sent? [Y/n] ") ?? "").trim().toLowerCase();
+  const autoDetect = await askYesNo(ask, "\n  Auto-detect from a message you just sent? [Y/n] ", true);
   let allowedChatId = null;
-  if (mode === "" || mode === "y" || mode === "yes") {
+  if (autoDetect) {
     console.log(c.dim("\n  Checking for a recent message..."));
     const updates = await getUpdates(0, token);
     allowedChatId = latestChatId(updates);
@@ -1861,8 +1923,7 @@ async function runQuestions(ask, depth) {
   return out;
 }
 async function askKeepExcerpt(ask) {
-  const a = (await ask("  Store a short excerpt so Holt can match your tone directly? [y/N] ") ?? "").trim().toLowerCase();
-  return a === "y" || a === "yes";
+  return askYesNo(ask, "  Store a short excerpt so Holt can match your tone directly? [y/N] ", false);
 }
 async function addFileSample(ask, file, v) {
   const path = resolve(process.cwd(), file);
@@ -2110,12 +2171,10 @@ async function init() {
   const toInstall = chosen.filter((id) => !isInstalled(BRAIN_DEFS[id].command));
   const loginWanted = /* @__PURE__ */ new Set();
   for (const id of toInstall) {
-    const a = (await ask(`  ${BRAIN_DEFS[id].label} is not installed. Sign in after install? [Y/n] `) ?? "").trim().toLowerCase();
-    if (a !== "n" && a !== "no") loginWanted.add(id);
+    if (await askYesNo(ask, `  ${BRAIN_DEFS[id].label} is not installed. Sign in after install? [Y/n] `, true)) loginWanted.add(id);
   }
   const connectedApiBrains = [];
-  const apiAns = (await ask("\nAlso connect a direct API brain (raw key, no CLI needed)? [y/N] ") ?? "").trim().toLowerCase();
-  if (apiAns === "y" || apiAns === "yes") {
+  if (await askYesNo(ask, "\nAlso connect a direct API brain (raw key, no CLI needed)? [y/N] ", false)) {
     const holder = defaultConfig();
     const brain = await connectApiBrain(ask, holder);
     if (brain) connectedApiBrains.push(brain);
@@ -2144,13 +2203,11 @@ Default brain? [${chosen.join("/")}] (${defPick}): `) ?? "").trim();
   } else {
     const ollamaHere = isInstalled("ollama");
     const q = ollamaHere ? `Semantic memory needs a local embed model. Pull ${EMBED_MODEL} with Ollama now? [Y/n] ` : "Enable private semantic memory? Installs Ollama plus a small local embed model. Everything stays on your machine. [Y/n] ";
-    const a = (await ask("\n" + q) ?? "").trim().toLowerCase();
-    wantMemorySetup = a !== "n" && a !== "no";
+    wantMemorySetup = await askYesNo(ask, "\n" + q, true);
     if (!wantMemorySetup) console.log(c.dim('  Okay. Memory still works with keyword recall; run "holt init" again anytime.'));
   }
   if (!loadTelegramConfig()) {
-    const tgAns = (await ask("\nChat with Holt from your phone over Telegram? [y/N] ") ?? "").trim().toLowerCase();
-    if (tgAns === "y" || tgAns === "yes") await setupTelegram(ask);
+    if (await askYesNo(ask, "\nChat with Holt from your phone over Telegram? [y/N] ", false)) await setupTelegram(ask);
   }
   close();
   for (const id of toInstall) {
@@ -2210,9 +2267,9 @@ Default brain? [${chosen.join("/")}] (${defPick}): `) ?? "").trim();
     console.log(c.dim('No brain is ready yet. Install one, then run "holt init" again.\n'));
   }
   const voiceReader = createReader();
-  const voiceAns = (await voiceReader.ask("Want Holt to learn how you write, so it can draft in your voice? [y/N] ") ?? "").trim().toLowerCase();
+  const voiceYes = await askYesNo(voiceReader.ask, "Want Holt to learn how you write, so it can draft in your voice? [y/N] ", false);
   voiceReader.close();
-  if (voiceAns === "y" || voiceAns === "yes") {
+  if (voiceYes) {
     await voiceInterview();
   } else {
     console.log(c.dim('  Skipped. Run "holt voice" anytime to set up your writing voice.\n'));
@@ -4171,9 +4228,9 @@ async function chat() {
   }
   let cfg = loadConfig();
   if (!cfg || !cfg.defaultBrain) {
-    const a = (await ask(c.dim("No Holt setup in this folder. Set it up now? [Y/n] ")) ?? "").trim().toLowerCase();
+    const setupYes = await askYesNo(ask, c.dim("No Holt setup in this folder. Set it up now? [Y/n] "), true);
     close();
-    if (a === "n" || a === "no") {
+    if (!setupYes) {
       console.log(c.dim('  Run "holt init" here when ready.\n'));
       return;
     }
@@ -4210,6 +4267,9 @@ async function chat() {
   if (embedOk && stats.withEmbeddings < stats.turns) {
     console.log(c.dim(`  ${stats.turns - stats.withEmbeddings} older moments lack embeddings. Run "holt memory embed" to upgrade them.`));
   }
+  if (!embedOk) {
+    console.log(c.dim('  Recall works, but semantic memory is off. "holt doctor --fix" turns it on.'));
+  }
   console.log(c.dim("Type a message. Commands: /brain  /memory  /output  /save  /allow  /setting  /clear  /help  /exit"));
   showStatus();
   while (true) {
@@ -4372,8 +4432,7 @@ async function chat() {
       const outside = findOutsidePaths(line, workspace());
       for (const dir of outside) {
         if (grantedDirs.has(dir)) continue;
-        const ans = (await ask(c.dim(`  Allow this session to access ${dir} (outside this folder)? [y/N] `)) ?? "").trim().toLowerCase();
-        if (ans === "y" || ans === "yes") {
+        if (await askYesNo(ask, c.dim(`  Allow this session to access ${dir} (outside this folder)? [y/N] `), false)) {
           grantedDirs.add(dir);
           console.log(c.green(`  granted this session: ${dir}`));
         } else {
@@ -4688,6 +4747,9 @@ async function memoryCmd(sub, rest = []) {
     }
     const hits = await recall(q, "__none__", 8);
     console.log("");
+    if (!await embeddingsAvailable()) {
+      console.log(c.dim('  (memory is in keyword mode; run "holt doctor --fix" to turn semantic recall back on)'));
+    }
     if (hits.length === 0) console.log(c.dim("  Nothing relevant found."));
     else for (const h of hits) {
       const when = new Date(h.turn.ts).toISOString().slice(0, 10);
@@ -7327,7 +7389,7 @@ function holtTools() {
 }
 
 // src/version.ts
-var VERSION = "0.14.3";
+var VERSION = "0.15.1";
 
 // src/commands/mcp.ts
 function printSetup() {
@@ -7471,7 +7533,7 @@ function parseArgs2(args) {
   let out;
   let noStore = false;
   let noRecall = false;
-  let quiet = false;
+  let quiet2 = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--brain") {
@@ -7491,12 +7553,12 @@ function parseArgs2(args) {
       continue;
     }
     if (a === "--quiet") {
-      quiet = true;
+      quiet2 = true;
       continue;
     }
     words2.push(a);
   }
-  return { task: words2.join(" ").trim(), brainId, out, noStore, noRecall, quiet };
+  return { task: words2.join(" ").trim(), brainId, out, noStore, noRecall, quiet: quiet2 };
 }
 async function run(args) {
   const p = parseArgs2(args);
@@ -7986,7 +8048,7 @@ function buildRoutinePrompt(r) {
   return { prompt };
 }
 async function runCmd(rest) {
-  let quiet = false;
+  let quiet2 = false;
   let outOverride;
   let notifyOverride = false;
   let brainOverride;
@@ -7994,7 +8056,7 @@ async function runCmd(rest) {
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === void 0) continue;
-    if (a === "--quiet") quiet = true;
+    if (a === "--quiet") quiet2 = true;
     else if (a === "--notify") notifyOverride = true;
     else if (a === "--out") outOverride = rest[++i];
     else if (a === "--brain") brainOverride = rest[++i];
@@ -8035,7 +8097,7 @@ async function runCmd(rest) {
   let streamed = false;
   const result = await runTask(built.prompt, {
     ...brainId ? { brainId } : {},
-    onChunk: quiet ? void 0 : (ch) => {
+    onChunk: quiet2 ? void 0 : (ch) => {
       streamed = true;
       process.stdout.write(ch);
     }
@@ -8046,13 +8108,13 @@ async function runCmd(rest) {
     process.exitCode = 1;
     return;
   }
-  if (!quiet && !streamed) process.stdout.write(result.text);
-  if (!quiet && (streamed || result.text) && !result.text.endsWith("\n")) process.stdout.write("\n");
+  if (!quiet2 && !streamed) process.stdout.write(result.text);
+  if (!quiet2 && (streamed || result.text) && !result.text.endsWith("\n")) process.stdout.write("\n");
   if (outTarget) {
     const target = resolve7(routine2.workspace, outTarget);
     try {
       writeFileSync19(target, result.text, "utf8");
-      if (!quiet) process.stderr.write(c.dim(`saved to ${target}`) + "\n");
+      if (!quiet2) process.stderr.write(c.dim(`saved to ${target}`) + "\n");
     } catch (e) {
       process.stderr.write(c.red(`Could not write ${target}: ${e.message}`) + "\n");
       process.exitCode = 1;
@@ -8228,6 +8290,10 @@ function readStdin3() {
   }
 }
 
+// src/commands/doctor.ts
+import { spawn as spawn5, spawnSync as spawnSync7 } from "child_process";
+import { existsSync as existsSync20 } from "fs";
+
 // src/specs.ts
 import os from "os";
 var BYTES_PER_GB = 1024 ** 3;
@@ -8347,10 +8413,63 @@ function good(text) {
 function warn(text) {
   console.log("  " + c.red(text));
 }
-async function doctor() {
+async function ollamaTags() {
+  const url = process.env.HOLT_OLLAMA_URL || "http://127.0.0.1:11434";
+  try {
+    const res = await fetch(`${url}/api/tags`, { signal: AbortSignal.timeout(1500) });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return (data.models ?? []).map((m) => String(m.name ?? ""));
+  } catch {
+    return null;
+  }
+}
+async function fixSemanticMemory(fixed) {
+  let tags = await ollamaTags();
+  if (tags === null) {
+    if (!isInstalled("ollama")) {
+      note("Ollama is not installed, so there is nothing to start.");
+      note(
+        process.platform === "darwin" ? 'Install it with: brew install ollama   (then run "holt doctor --fix" again)' : 'Install it from https://ollama.com/download, then run "holt doctor --fix" again.'
+      );
+      return false;
+    }
+    note("Ollama is installed but not running. Starting it...");
+    try {
+      const child = spawn5("ollama", ["serve"], { detached: true, stdio: "ignore" });
+      child.unref();
+    } catch {
+      warn('Could not start Ollama. Start it yourself (open the Ollama app or run "ollama serve").');
+      return false;
+    }
+    for (let i = 0; i < 16 && tags === null; i++) {
+      await new Promise((r) => setTimeout(r, 500));
+      tags = await ollamaTags();
+    }
+    if (tags === null) {
+      warn('Ollama did not come up. Open the Ollama app once, then run "holt doctor --fix" again.');
+      return false;
+    }
+    fixed.push("Started the Ollama daemon.");
+  }
+  if (!tags.some((t) => t.startsWith(EMBED_MODEL))) {
+    note(`The "${EMBED_MODEL}" model is missing. Downloading it (one-time, ~275 MB)...`);
+    const r = spawnSync7("ollama", ["pull", EMBED_MODEL], { stdio: "inherit" });
+    if (r.status !== 0) {
+      warn(`Could not download ${EMBED_MODEL}. Check your internet connection and retry.`);
+      return false;
+    }
+    fixed.push(`Downloaded the "${EMBED_MODEL}" model.`);
+  }
+  resetEmbedProbe();
+  return embeddingsAvailable();
+}
+async function doctor(args = []) {
+  const fix = args.includes("--fix");
+  const fixed = [];
   const specs = detect();
   const steps = [];
-  console.log("\n" + c.bold("Holt doctor") + c.dim("  a look at this machine and how best to run Holt on it"));
+  console.log("\n" + c.bold("Holt doctor") + c.dim(" \xB7 a look at this machine and how best to run Holt on it"));
   header("Machine");
   row("platform", `${specs.platform} / ${specs.arch}`);
   row("cpu", `${specs.cpuModel}${specs.cpuCount ? `  (${specs.cpuCount} cores)` : ""}`);
@@ -8387,13 +8506,29 @@ async function doctor() {
   } catch {
     embedOk = false;
   }
+  if (!embedOk && fix) {
+    embedOk = await fixSemanticMemory(fixed);
+  }
   if (embedOk) {
     good(`Ollama reachable and "${EMBED_MODEL}" is present. Memory recall is semantic, private, and local.`);
+    if (fix && existsSync20(wsHoltDir())) {
+      const missing = loadTurns().filter((t) => !Array.isArray(t.emb)).length;
+      if (missing > 0) {
+        note(`${missing} memories in this folder lack embeddings. Upgrading them...`);
+        const r = await backfillEmbeddings((done, total) => {
+          process.stdout.write(`\r  embedding ${done}/${total}...`);
+        });
+        console.log("");
+        if (r.embedded > 0) fixed.push(`Upgraded ${r.embedded} memories to semantic recall.`);
+      }
+    }
   } else {
     note(`Ollama with "${EMBED_MODEL}" not reachable at ${OLLAMA_URL3}.`);
     note("Without it, Holt still remembers, but recall falls back to keyword match.");
-    warn(`Recommendation: enable local embeddings. Install Ollama, then: ollama pull ${EMBED_MODEL}`);
-    steps.push(`Enable semantic memory: ollama pull ${EMBED_MODEL}`);
+    if (!fix) {
+      warn('Recommendation: run "holt doctor --fix" to set this up automatically.');
+      steps.push("Enable semantic memory: holt doctor --fix");
+    }
   }
   header("Knowledge wiki maintainer");
   const rec = recommendLocalModel2(specs.totalRamGB);
@@ -8419,6 +8554,12 @@ async function doctor() {
   }
   note("Hosting tip: a low-power always-on machine (an old laptop, a Pi) is ideal for the bot and scheduled runs.");
   note("Heavy local models want more RAM, so keep those on your bigger machine and let the small box relay.");
+  if (fix) {
+    header("Repairs");
+    if (lastConfigRepair) fixed.push(`Moved a damaged settings file aside (${lastConfigRepair}).`);
+    if (fixed.length === 0) good("Nothing needed repair.");
+    else for (const f of fixed) good(f);
+  }
   header("Recommended next steps");
   if (!cfg) {
     steps.unshift('Set up this folder: run "holt init".');
@@ -8432,6 +8573,163 @@ async function doctor() {
   console.log("");
 }
 
+// src/commands/tour.ts
+function step(n, title) {
+  console.log("\n" + c.accent(`Step ${n} of 3`) + c.bold(`  ${title}`));
+}
+async function tour() {
+  const { ask, close } = createReader();
+  try {
+    if (!await ensureTrusted(ask)) return;
+    const cfg = loadConfig();
+    if (!cfg || !cfg.defaultBrain) {
+      console.log(c.dim('\n  This folder is not set up yet. Run "holt" once, then come back for the tour.\n'));
+      return;
+    }
+    console.log("\n" + c.bold("Welcome. This takes two minutes and shows you the one thing that matters."));
+    step(1, "Ask about your files");
+    console.log(c.dim("  Holt reads the folder it runs in. Asking it what it sees here...\n"));
+    const r = await runTask(
+      "Look at the files in this folder and describe, in two short plain sentences, what this folder seems to be about. If it is empty or nearly empty, say that cheerfully.",
+      { store: false, onChunk: (t) => process.stdout.write(t) }
+    );
+    if (!r.ok) {
+      console.log(c.dim("  (Your brain is not reachable right now, so we will skip this step. The next two work offline.)"));
+      if (r.text) console.log(c.dim(`  ${r.text.trim()}`));
+    }
+    console.log("");
+    step(2, "Teach Holt one thing about you");
+    console.log(c.dim('  Type one fact you want Holt to keep. Examples: "I run a bakery in Pune",'));
+    console.log(c.dim('  "My big project this quarter is the Delhi launch", "I hate long emails".\n'));
+    let fact = (await ask("  Your fact: ") ?? "").trim();
+    if (!fact) fact = "I just finished the Holt tour.";
+    const session = newSessionId();
+    await saveFact(fact, session);
+    console.log(c.green("\n  Kept.") + c.dim("  That went into this folder\u2019s memory, on this laptop, nowhere else."));
+    step(3, "Watch it remember");
+    console.log(c.dim('  Asking Holt\u2019s memory: "what do you know about me?"...\n'));
+    const hits = await recall("what do you know about me? who am I? my work", "__tour__", 4);
+    const shown = hits.filter((h) => h.turn.content.trim().length > 0).slice(0, 3);
+    if (shown.length === 0) {
+      console.log("  " + c.accent("remembered") + `  ${fact}`);
+    } else {
+      for (const h of shown) {
+        console.log("  " + c.accent("remembered") + `  ${h.turn.content.slice(0, 110).replace(/\s+/g, " ")}`);
+      }
+    }
+    const s = memStats();
+    console.log(
+      "\n" + c.bold("  Here is the point: ") + `close this terminal. Come back tomorrow, or next month, and ask again.
+  Still there. This folder now holds ${s.turns} memor${s.turns === 1 ? "y" : "ies"}, and every chat adds more.
+`
+    );
+    console.log(c.dim('  Next: run "holt" to start a real conversation, or "holt help" to see everything it does.\n'));
+  } finally {
+    close();
+  }
+}
+
+// src/commands/reset.ts
+import { existsSync as existsSync21, rmSync as rmSync9 } from "fs";
+async function reset() {
+  const { ask, close } = createReader();
+  try {
+    const dir = wsHoltDir();
+    if (!existsSync21(dir)) {
+      console.log(c.dim("\n  Nothing to reset: Holt has no settings or memory in this folder.\n"));
+      return;
+    }
+    let turns = 0;
+    try {
+      turns = memStats().turns;
+    } catch {
+    }
+    console.log("\n" + c.bold("Reset Holt in this folder"));
+    console.log(c.dim(`  Folder: ${workspace()}`));
+    console.log(c.dim(`  This deletes Holt's settings and all ${turns} remembered moment${turns === 1 ? "" : "s"} here.`));
+    console.log(c.dim("  Your own files are not touched. Other folders are not touched."));
+    const a = (await ask(`
+  Type ${c.bold("reset")} to confirm, or press enter to cancel: `) ?? "").trim().toLowerCase();
+    if (a !== "reset") {
+      console.log(c.dim("  Cancelled. Nothing was changed.\n"));
+      return;
+    }
+    rmSync9(dir, { recursive: true, force: true });
+    console.log(c.green("\n  Done. This folder is a clean slate.") + c.dim('  Run "holt" to set it up again.\n'));
+  } finally {
+    close();
+  }
+}
+
+// src/commands/update.ts
+import { spawnSync as spawnSync8 } from "child_process";
+import { realpathSync as realpathSync4 } from "fs";
+async function latestVersion() {
+  try {
+    const res = await fetch("https://registry.npmjs.org/@holt-os/holt/latest", {
+      signal: AbortSignal.timeout(4e3)
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
+function isBrewInstall() {
+  try {
+    const p = realpathSync4(process.argv[1] ?? "");
+    return p.includes("/Cellar/") || p.includes("/homebrew/") || p.includes("/linuxbrew/");
+  } catch {
+    return false;
+  }
+}
+async function update() {
+  const { ask, close } = createReader();
+  try {
+    console.log(c.dim(`
+  You have holt ${VERSION}. Checking for a newer one...`));
+    const latest = await latestVersion();
+    if (!latest) {
+      console.log(c.dim("  Could not reach the registry. Check your internet connection and try again.\n"));
+      return;
+    }
+    if (latest === VERSION) {
+      console.log(c.green(`  You are on the latest version (${VERSION}).`) + "\n");
+      return;
+    }
+    console.log(`  Newer version available: ${c.bold(latest)}`);
+    if (isBrewInstall()) {
+      if (!await askYesNo(ask, "  Update now via Homebrew? [Y/n] ", true)) {
+        console.log(c.dim("  Later, then. The command is: brew upgrade holt\n"));
+        return;
+      }
+      const r2 = spawnSync8("brew", ["upgrade", "holt"], { stdio: "inherit" });
+      if (r2.status === 0) console.log(c.green(`
+  Updated to ${latest}.`) + "\n");
+      else console.log(c.dim("\n  Homebrew reported a problem above. You can retry with: brew upgrade holt\n"));
+      return;
+    }
+    if (!await askYesNo(ask, "  Update now? [Y/n] ", true)) {
+      console.log(c.dim("  Later, then. The command is: npm install -g @holt-os/holt\n"));
+      return;
+    }
+    const r = spawnSync8("npm", ["install", "-g", "@holt-os/holt"], { stdio: "inherit" });
+    if (r.status === 0) {
+      console.log(c.green(`
+  Updated to ${latest}.`) + "\n");
+    } else {
+      console.log(
+        c.dim(
+          "\n  The install hit a permission problem. Two easy ways out:\n    1. Run it once with sudo: sudo npm install -g @holt-os/holt\n    2. Or install Node with nvm (https://nvm.sh) so no sudo is ever needed.\n"
+        )
+      );
+    }
+  } finally {
+    close();
+  }
+}
+
 // src/commands/write.ts
 import { writeFileSync as writeFileSync20 } from "fs";
 import { resolve as resolve8 } from "path";
@@ -8623,6 +8921,37 @@ async function write(args) {
   }
 }
 
+// src/crash.ts
+import { mkdirSync as mkdirSync18, appendFileSync as appendFileSync3 } from "fs";
+import { join as join20 } from "path";
+function handleCrash(err2) {
+  const stamp = (/* @__PURE__ */ new Date()).toISOString();
+  const detail = err2 instanceof Error ? err2.stack || err2.message : String(err2);
+  let logPath2 = null;
+  const entry = `[${stamp}] holt ${VERSION}  argv: ${process.argv.slice(2).join(" ")}
+${detail}
+
+`;
+  for (const base of [wsHoltDir(), GLOBAL_DIR]) {
+    try {
+      const dir = join20(base, "logs");
+      mkdirSync18(dir, { recursive: true });
+      const p = join20(dir, `crash-${stamp.slice(0, 10)}.log`);
+      appendFileSync3(p, entry, "utf8");
+      logPath2 = p;
+      break;
+    } catch {
+    }
+  }
+  if (!isQuietMode()) {
+    console.error(c.red("\n  Something went wrong, and it is not your fault."));
+    if (logPath2) console.error(c.dim(`  Details saved to: ${logPath2}`));
+    console.error(c.dim("  Try: holt doctor --fix   (it repairs the common causes)"));
+    console.error(c.dim("  Still stuck? https://github.com/holt-os/holt/issues\n"));
+  }
+  process.exit(1);
+}
+
 // src/cli.ts
 var BANNER = `
   \u2588\u2588\u2557  \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
@@ -8636,40 +8965,53 @@ var BANNER = `
 var HELP = `${BANNER}
 Usage: holt <command>
 
-Commands:
-  (no command)    Start your assistant: sets up if needed, then launches the real
-                  interactive brain (Claude Code, Codex, Gemini), branded as Holt
-  init            Trust this folder, choose and install brains, sign in, set defaults
-  launch          Same as bare "holt": start your assistant
-  chat            Lightweight REPL that remembers past sessions (used for API brains)
-  run <task>      Run one task non-interactively: recall, brain executes, remember
-  schedule        Fire "holt run" on a timer: holt schedule [add | list | remove]
-  routine         Named, reusable, scheduled jobs: holt routine [add | run | list | remove]
-  telegram        Chat with Holt from your phone: holt telegram [setup]
-  notify [msg]    Push a message to your phone over Telegram (stdin-friendly)
-  voice           Teach Holt how you write: holt voice [add <file> | show | edit | clear]
+Start here:
+  (no command)    Start your assistant: sets up if needed, then launches your
+                  brain (Claude Code, Codex, Gemini), branded as Holt
+  tour            A 2-minute guided first run: ask, teach it one fact, watch it remember
+  doctor          Health check for this machine
+                  ("holt doctor --fix" also repairs the common problems for you)
+
+Every day:
+  run <task>      Do one task and remember it: holt run "draft my status update"
   write <what>    Draft content in your voice, with anti-AI checks: holt write "..." [--type]
-  memory          Inspect memory: holt memory [search <query> | embed | clear]
-  wiki            Your derived knowledge wiki: holt wiki [sync | rebuild | lint | list | show]
-  graph           See your memory as an interactive knowledge graph in the browser
-  skill           Manage skills: holt skill [list | show | create | add | remove]
-  doctor          Check this machine and recommend how best to run Holt here
-  mcp             Serve this folder's memory to Claude Code, Cursor, Codex (holt mcp setup)
-  hook            Ambient memory for Claude Code: holt hook [install | remove | status]
-  setting         Configure brains, API brains, and your launch command (per folder)
+  voice           Teach Holt how you write: holt voice [add <file> | show | edit | clear]
+  memory          What Holt knows here: holt memory [search <q> | facts | embed | clear]
+  wiki            A tidy, linked notebook Holt keeps from your memory: holt wiki [sync | show]
+  graph           See everything Holt knows as a visual map in your browser
+  skill           Reusable how-tos you can share: holt skill [list | show | create | add]
+
+From your phone, while you sleep:
+  telegram        Chat with Holt from your phone: holt telegram setup
+  notify [msg]    Send yourself a phone message from any script (stdin-friendly)
+  schedule        Run a task on a timer: holt schedule [add | list | remove]
+  routine         Named, reusable, scheduled jobs: holt routine [add | run | list | remove]
+
+Housekeeping:
+  setting         Change brains, API connections, and your launch word (per folder)
   login <brain>   Sign in to a brain: claude, codex, or gemini
-  version         Print the Holt version
-  help            Show this help (bare "holt" starts your assistant, not this)
+  update          Get the latest Holt, in one word
+  reset           Start this folder over (asks first; your own files are untouched)
+  hook            Ambient memory inside plain Claude Code: holt hook [install | status]
+  mcp             Share Holt's memory with other AI apps (Claude Code, Cursor, Codex)
+  chat            Lightweight built-in chat, used for API brains
+  init            Full setup by hand (bare "holt" runs this for you when needed)
+  launch          Same as bare "holt": start your assistant
+  version | help  Print the version / show this help
 
 Holt runs in the folder you launch it from and asks to trust it first.
-Brains are agent CLIs on your machine (claude, codex, gemini) or direct
-API connections you add in settings.
+A "brain" is the AI doing the thinking: an agent CLI on your machine
+(claude, codex, gemini) or a direct API connection you add in settings.
 
 Docs: https://productsdecoded.com/holt
 Repo: https://github.com/holt-os/holt
 `;
 async function main() {
   const cmd = process.argv[2];
+  const sub = process.argv[3];
+  if (cmd === "statusline" || cmd === "mcp" || cmd === "notify" || cmd === "hook" && (sub === "inject" || sub === "capture")) {
+    setQuietMode(true);
+  }
   switch (cmd) {
     case void 0:
       await launch();
@@ -8738,7 +9080,16 @@ async function main() {
       await notify(process.argv.slice(3));
       break;
     case "doctor":
-      await doctor();
+      await doctor(process.argv.slice(3));
+      break;
+    case "tour":
+      await tour();
+      break;
+    case "reset":
+      await reset();
+      break;
+    case "update":
+      await update();
       break;
     case "voice":
       await voice(process.argv[3], process.argv.slice(4));
@@ -8754,4 +9105,6 @@ async function main() {
       process.exitCode = 1;
   }
 }
-main();
+process.on("uncaughtException", handleCrash);
+process.on("unhandledRejection", handleCrash);
+main().catch(handleCrash);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",