@holt-os/holt 0.15.1 → 0.17.0

package/README.md

@@ -22,7 +22,8 @@
 - **Private memory you can see.** Per-folder semantic recall and distilled facts, an interactive knowledge graph (`holt graph`), and a self-maintaining wiki (`holt wiki`) over everything you tell it. Nothing leaves your machine.
 - **Ambient by default.** `holt hook` wires memory into Claude Code so it recalls and remembers with no manual step, and an MCP server exposes the same memory to Cursor and Codex.
 - **Runs your work.** Run a task once, on a schedule, or as a named routine, and reach it from your phone over Telegram.
-- **Extensible, zero-infra.** Ten built-in skills plus a git-based community registry (`holt skill search`) in the portable `SKILL.md` format.
+- **Useful on day one.** `/skill onboard` interviews you and fills memory in about fifteen minutes, `/skill audit` shows what is still missing, and `/skill level-up` turns one manual chore a week into something Holt does.
+- **Extensible, zero-infra.** Thirteen built-in skills plus a git-based community registry (`holt skill search`) in the portable `SKILL.md` format.
 - **Writes in your voice.** `holt write` drafts in a style Holt learns from you, with built-in anti-AI checks.
 
 > **Status:** shipping and usable today. Every capability above works now.
@@ -43,6 +44,14 @@ Or with npm, if you already have Node:
 npm install -g @holt-os/holt
 ```
 
+**Not comfortable in a terminal?** Install [Claude Code](https://claude.com/claude-code), open it, and paste this:
+
+```
+Set up Holt for me: read https://raw.githubusercontent.com/holt-os/holt/main/docs/INSTALL.md and follow it exactly.
+```
+
+It installs Holt, checks its own work, and fixes what breaks. Full detail, system requirements, and troubleshooting: [docs/INSTALL.md](./docs/INSTALL.md).
+
 ## Quickstart
 
 ```bash
@@ -50,7 +59,7 @@ cd ~/where-you-want-to-work
 holt           # start your assistant (or use your custom command, e.g. `ai`)
 ```
 
-That is it. Bare `holt` sets the folder up the first time (trust, brain, memory hooks) and then launches the **real interactive brain** (Claude Code, Codex, or Gemini), branded as Holt. Run `holt help` for the full command list, and `holt chat` for the lightweight REPL described further down.
+That is it. Bare `holt` sets the folder up the first time (trust, brain, memory hooks) and then launches the **real interactive brain** (Claude Code, Codex, or Gemini), branded as Holt. Run `holt help` for the full command list.
 
 Prefer to step through setup on its own first? `holt init` still does that, then `holt` starts the session.
 
@@ -59,10 +68,12 @@ Prefer to step through setup on its own first? `holt init` still does that, then
 `holt` (with no command) is the front door: **your assistant, with memory of you.**
 
 1. **Sets up if needed.** In a fresh folder it runs onboarding (trust, pick a brain, memory). In an already-configured folder it just makes sure the folder is trusted, the memory directory exists, and the [ambient memory hooks](#ambient-memory-for-claude-code-holt-hook) are installed.
-2. **Launches the real interactive brain.** It hands the terminal to the brain's own interactive session (`claude`, `codex`, or `gemini` with no `-p` and no prompt), so you keep the brain's full power: agentic edits, tool use, the permission UI, MCP. This is different from `holt chat`, which is a lightweight REPL that shells out to the brain once per turn.
+> **Gemini note.** Personal Google accounts can no longer sign in to Gemini CLI (Google retired that login on 18 June 2026 in favour of Antigravity). Gemini still works in Holt with an API key from <https://aistudio.google.com/apikey>; `holt login gemini` walks you through connecting it.
+
+2. **Launches the real interactive brain.** It hands the terminal to the brain's own interactive session (`claude`, `codex`, or `gemini` with no `-p` and no prompt), so you keep the brain's full power: agentic edits, tool use, the permission UI, MCP. That is different from Holt's own built-in REPL, which shells out to the brain once per turn and is used for API brains that have no TUI of their own.
 3. **Brands the session as Holt.** See [Branding](#branding-holt-forward) below.
 
-If your default brain is a **direct API brain** (no interactive TUI), bare `holt` prints a one-line note and starts `holt chat` instead, since that path supports API brains.
+If your default brain is a **direct API brain** (no interactive TUI of its own), bare `holt` opens Holt's own built-in REPL instead, branded the same way. Same command, same intro, no second thing to learn.
 
 ### Branding (Holt-forward)
 
@@ -96,7 +107,7 @@ During `holt init` you:
 
 ## Using it
 
-Inside `holt chat`:
+Inside a Holt session:
 
 ```
 /brain            list your brains and see which is active
@@ -127,7 +138,7 @@ Holt runs the brain in the folder you launched it from, so by default the brain
 - `/allow <path>` grants a folder up front with no prompt.
 - `/allowed` lists what you have granted.
 
-Grants are **in-memory and session-scoped**: nothing is written to disk, and they reset the next time you run `holt chat`. Access is **read-oriented** and only works with a **Claude Code** brain: Holt passes `--add-dir=<dir>` for each granted folder plus `--allowedTools=Read,Glob,Grep` so Claude Code can read (but not write) those files without an interactive permission prompt. With a Codex/Gemini or API brain, external file access is unavailable and Holt says so instead of adding flags. (If you need to tune the flags, they live in one place: `claudeAccessArgs` in `src/access.ts`.)
+Grants are **in-memory and session-scoped**: nothing is written to disk, and they reset the next time you run `holt`. Access is **read-oriented** and only works with a **Claude Code** brain: Holt passes `--add-dir=<dir>` for each granted folder plus `--allowedTools=Read,Glob,Grep` so Claude Code can read (but not write) those files without an interactive permission prompt. With a Codex/Gemini or API brain, external file access is unavailable and Holt says so instead of adding flags. (If you need to tune the flags, they live in one place: `claudeAccessArgs` in `src/access.ts`.)
 
 ***
 
@@ -137,6 +148,8 @@ Every exchange is saved to `<folder>/.holt/memory/turns.jsonl`, private and loca
 
 When you end a chat, Holt asks the brain to distill 1 to 5 durable facts from the session (decisions, preferences, key names, numbers) and writes them to a human-readable `<folder>/.holt/memory/facts.md` you can read and edit. Those facts are also embedded and ranked slightly higher than raw turns during recall, so the signal rises to the top over time. See them with `holt memory facts`. Turn it off by setting `memory.extractFacts` to `false` in `config.json`.
 
+You do not have to wait for the end of a session. `holt memory add "<fact>"` saves one immediately, and duplicates are ignored, so it is safe to run twice. Piping in several facts, one per line, works too. Prefer this over editing `facts.md` by hand: a fact typed straight into that file is never embedded, so semantic recall will not find it.
+
 Two recall modes, picked automatically:
 
 - **Semantic** (best): a local [Ollama](https://ollama.com) with an embedding model, which `holt init` offers to set up for you. Recall matches by meaning: asking "who owns my apartment" finds "my landlord is called Pieter". No API keys, nothing leaves your machine.
@@ -146,6 +159,7 @@ Inspect it any time:
 
 ```bash
 holt memory                    # stats for this folder
+holt memory add "<fact>"       # teach it something durable right now
 holt memory facts              # show the distilled facts (facts.md)
 holt memory search <query>     # find remembered moments
 holt memory embed              # embed older moments for semantic recall
@@ -248,7 +262,7 @@ holt wiki setup               # recommend a local model for this machine's RAM
 
 **How sync works.** `holt wiki sync` gathers facts added since the last sync (a marker in `.holt/wiki/.state.json`), embeds each one locally, and routes it to the nearest existing page by cosine similarity. Related facts land on the same page; a fact that matches nothing new starts a fresh page. Facts are grouped by target page and the maintainer is called **once per changed page** (not once per fact), so it only rewrites the few pages that actually changed. Routing is always local and free, which is what keeps the maintainer's cost minimal. `holt wiki rebuild` folds every fact from scratch.
 
-**Self-maintaining (auto-sync).** Turn on `holt wiki auto on` (persists `wiki.autoSync: true` for the folder) and the wiki keeps itself current with no manual command. It syncs **after fact distillation** at the end of a `holt chat` session, and ambiently when the Claude Code **Stop** hook fires (`holt hook capture`), so newly captured facts fold straight into pages. Auto-sync is silent, best-effort, and never blocks exit: it reuses the exact same sync engine as `holt wiki sync`, so there is no behavior drift. Left off (the default), nothing changes and you sync by hand. `holt wiki auto` with no argument shows the current state; `holt wiki status` surfaces it too.
+**Self-maintaining (auto-sync).** Turn on `holt wiki auto on` (persists `wiki.autoSync: true` for the folder) and the wiki keeps itself current with no manual command. It syncs **after fact distillation** at the end of a Holt session, and ambiently when the Claude Code **Stop** hook fires (`holt hook capture`), so newly captured facts fold straight into pages. Auto-sync is silent, best-effort, and never blocks exit: it reuses the exact same sync engine as `holt wiki sync`, so there is no behavior drift. Left off (the default), nothing changes and you sync by hand. `holt wiki auto` with no argument shows the current state; `holt wiki status` surfaces it too.
 
 **Lint that can fix.** `holt wiki lint` audits pages for contradictions, duplicates, and gaps and prints a report only (files untouched). Add `--fix` and Holt asks the maintainer to return corrected page bodies and **applies them**, rewriting the affected pages (provenance/`sources` is preserved). Because pages are derived and regenerable, applying is safe: a bad `--fix` is fully recoverable with `holt wiki rebuild`, and the command prints a git/backup nudge before writing. Only pages that actually change are rewritten.
 
@@ -313,6 +327,11 @@ Holt ships with a small, curated set of general-purpose skills, available in eve
 - **plan**: break a goal into a concrete, ordered set of steps.
 - **rewrite**: tighten and clarify a piece of text without changing its meaning.
 - **decide**: weigh a decision and give a clear recommendation.
+- **onboard**: a guided first-day interview that fills memory with who you are and what you are working on.
+- **audit**: a read-only health check across the four rungs, naming the gaps and the single next fix.
+- **level-up**: a weekly session that turns one recurring manual chore into something Holt does, and ships it.
+
+The last three are the setup loop. `onboard` on day one, then `audit` and `level-up` weekly. Holt gets useful in four rungs, in order: **Know** (it holds facts about you), **Reach** (it can see your real material), **Do** (it runs your repeated work), **Run** (it acts while you are away). Automating on top of an empty memory just produces confident nonsense on a timer, so the order matters.
 
 ### Skill registry (`holt skill search` / `publish`)
 
@@ -378,7 +397,7 @@ Point the client at the folder whose memory you want it to use; Holt serves what
 
 ## Ambient memory for Claude Code (`holt hook`)
 
-The MCP server above lets Claude Code recall and remember **when it decides to**. `holt hook` goes further: it makes Holt's per-folder memory work **ambiently**, with no `holt chat` and no manual tool call. Two directions, both wired as [Claude Code hooks](https://docs.claude.com/en/docs/claude-code/hooks):
+The MCP server above lets Claude Code recall and remember **when it decides to**. `holt hook` goes further: it makes Holt's per-folder memory work **ambiently**, with no Holt session open and no manual tool call. Two directions, both wired as [Claude Code hooks](https://docs.claude.com/en/docs/claude-code/hooks):
 
 - **Inject** (`UserPromptSubmit`): before each prompt, Holt quietly recalls the most relevant remembered notes for the current folder and adds them to the model's context.
 - **Capture** (`Stop`): when a session ends, Holt distills durable facts from the transcript (via this folder's configured brain) and saves them to the folder's memory.
@@ -394,7 +413,7 @@ holt hook remove                  # remove ONLY Holt's hooks, leaving everything
 
 Install **merges** into any existing `hooks` config, never clobbers unrelated settings or other hooks, is **idempotent** (re-running does not duplicate), and backs the file up to `settings.json.holt-bak` before writing. `remove` deletes only the entries whose command is `holt hook inject` / `holt hook capture`.
 
-**Trusted-folder guard (important).** The two runtime hooks (`holt hook inject` and `holt hook capture`, invoked by Claude Code, not you) no-op **silently** unless the folder is a trusted Holt workspace with an existing `.holt/memory`. So Holt never injects your private notes into an unrelated project, and never creates memory in a folder you never set up. To make a folder ambient, run `holt init` (or `holt chat`) there once so it becomes trusted and gets its `.holt/memory`. The inject hook keeps stdout clean (only the context block is printed, since Claude Code injects it verbatim); all diagnostics go to stderr, and both hooks always exit 0 so a memory step never blocks or slows your prompt.
+**Trusted-folder guard (important).** The two runtime hooks (`holt hook inject` and `holt hook capture`, invoked by Claude Code, not you) no-op **silently** unless the folder is a trusted Holt workspace with an existing `.holt/memory`. So Holt never injects your private notes into an unrelated project, and never creates memory in a folder you never set up. To make a folder ambient, run `holt init` there once so it becomes trusted and gets its `.holt/memory`. The inject hook keeps stdout clean (only the context block is printed, since Claude Code injects it verbatim); all diagnostics go to stderr, and both hooks always exit 0 so a memory step never blocks or slows your prompt.
 
 **Seeing what the hooks did (`~/.holt/hooks.log`).** Since the hooks stay silent, every `holt hook capture` run appends **one** line to `~/.holt/hooks.log` with the outcome or the exact skip reason (untrusted folder, no config, `extractFacts` off, no usable brain, missing or empty transcript, too few exchanges, or `saved N facts`), preceded by a line of the raw hook fields it received. Check this file first if capture seems to save nothing. `inject` uses the same log but stays quiet by default; set `HOLT_HOOK_DEBUG=1` to make it log too.
 
@@ -418,7 +437,7 @@ Run a single task non-interactively. It recalls relevant memory, injects your sk
 holt run "summarize the open items in this folder"
 ```
 
-Options: `--brain <id>` pick a brain, `--out <file>` also write the reply to a file, `--no-store` skip saving, `--no-recall` skip memory, `--quiet` suppress streaming. The folder must be trusted first (`holt init` or `holt chat` once); in a non-interactive context an untrusted folder exits non-zero instead of prompting.
+Options: `--brain <id>` pick a brain, `--out <file>` also write the reply to a file, `--no-store` skip saving, `--no-recall` skip memory, `--quiet` suppress streaming. The folder must be trusted first (`holt init` once); in a non-interactive context an untrusted folder exits non-zero instead of prompting.
 
 ### holt schedule
 
@@ -557,7 +576,6 @@ holt                 start your assistant: set up if needed, then launch the rea
                      interactive brain (Claude Code/Codex/Gemini), branded as Holt
 holt launch          same as bare "holt"
 holt init            set up (trust, brains, sign-in, defaults) for this folder
-holt chat            lightweight REPL that remembers past ones (used for API brains)
 holt run <task>      run one task non-interactively (recall, brain, remember)
 holt schedule        run a task on a timer: add | list | remove
 holt routine         named, reusable, scheduled jobs: add | run | list | show | remove
@@ -577,7 +595,7 @@ holt graph           see your memory as an interactive knowledge graph
 holt mcp             run an MCP server so other tools use this folder's memory (holt mcp setup)
 holt hook            ambient memory for Claude Code: install | remove | status
 holt skill           manage skills: list | show | create | add | remove
-holt memory          inspect memory: holt memory [search <query> | facts | embed | clear]
+holt memory          inspect memory: holt memory [add <fact> | search <query> | facts | embed | clear]
 holt wiki            derived knowledge wiki: holt wiki [sync | auto | rebuild | lint | list | show | status]
 holt setting         configure brains, API brains, and launch command
 holt login <brain>   sign in to claude, codex, or gemini

package/dist/cli.js

@@ -205,12 +205,22 @@ var BRAIN_SETUP = {
   codex: { install: ["npm", "install", "-g", "@openai/codex"], login: ["codex", "login"] },
   gemini: { install: ["npm", "install", "-g", "@google/gemini-cli"], login: ["gemini"] }
 };
+var BRAIN_LOGIN_UNAVAILABLE = {
+  gemini: {
+    reason: 'Google ended "Login with Google" for Gemini Code Assist individual accounts on 18 June 2026. Personal Google accounts (free, AI Pro, AI Ultra) can no longer sign in to Gemini CLI.',
+    provider: "gemini",
+    keyUrl: "https://aistudio.google.com/apikey"
+  }
+};
+function loginUnavailable(id) {
+  return BRAIN_LOGIN_UNAVAILABLE[id] ?? null;
+}
 var BRAIN_IDS = ["claude", "codex", "gemini"];
 var PROVIDERS = ["anthropic", "openai", "gemini", "kimi", "grok"];
 var PROVIDER_MODEL_SUGGESTION = {
-  anthropic: "claude-sonnet-4-6",
+  anthropic: "claude-sonnet-5",
   openai: "gpt-5",
-  gemini: "gemini-2.5-flash",
+  gemini: "gemini-flash-latest",
   kimi: "kimi-k2-turbo-preview",
   grok: "grok-4"
 };
@@ -221,6 +231,11 @@ var PROVIDER_ENV = {
   kimi: "MOONSHOT_API_KEY",
   grok: "XAI_API_KEY"
 };
+function cliBrainUsable(id) {
+  const gone = loginUnavailable(id);
+  if (!gone) return true;
+  return Boolean(process.env[PROVIDER_ENV[gone.provider]]);
+}
 function defaultConfig() {
   const brains = {};
   for (const id of BRAIN_IDS) {
@@ -662,7 +677,7 @@ function clearMemory() {
 function normalizeFact(s) {
   return (s || "").toLowerCase().replace(/\s+/g, " ").trim().replace(/[.,;:!?]+$/, "");
 }
-var FACTS_HEADER = "# Holt facts\n\nDistilled memories for this folder. Safe to edit by hand.\n";
+var FACTS_HEADER = '# Holt facts\n\nDistilled memories for this folder. Edit or delete lines freely.\nTo ADD one, use `holt memory add "<fact>"`: a line typed in here by hand is\nnever embedded, so semantic recall will not find it.\n';
 async function saveFact(content, session) {
   const clean = content.trim();
   if (!clean) return false;
@@ -1509,7 +1524,10 @@ function printStatus(cfg) {
     const b = cfg.brains[id];
     const tags = [
       b.enabled ? c.green("enabled") : isInstalled(b.command) ? c.dim("installed, off") : c.dim("not installed"),
-      cfg.defaultBrain === id ? c.accent("default") : ""
+      cfg.defaultBrain === id ? c.accent("default") : "",
+      // A retired sign-in with no key in the environment is the real reason a
+      // brain will not answer, so name it here rather than at first failure.
+      loginUnavailable(id) && !cliBrainUsable(id) ? c.red("no sign-in, needs API key") : ""
     ].filter(Boolean).join("  ");
     console.log(`  ${id.padEnd(10)} ${b.label.padEnd(16)} ${tags}`);
   }
@@ -1528,8 +1546,9 @@ function printStatus(cfg) {
   console.log("\n  " + c.dim("[d] default brain   [t] toggle brain   [c] connect API brain   [x] remove API brain"));
   console.log("  " + c.dim("[a] launch command   [m] connect Telegram   [enter] done"));
 }
-async function connectApiBrain(ask, cfg) {
-  let provider = null;
+async function connectApiBrain(ask, cfg, preset) {
+  let provider = preset ?? null;
+  if (provider) console.log(c.dim(`  provider: ${provider}`));
   for (let tries = 0; tries < 3 && !provider; tries++) {
     const provRaw = (await ask(`  provider [${PROVIDERS.join("/")}] (enter for ${PROVIDERS[0]}, or "skip"): `) ?? "skip").trim().toLowerCase();
     if (provRaw === "skip" || provRaw === "q" || provRaw === "n" || provRaw === "no") {
@@ -1547,7 +1566,9 @@ async function connectApiBrain(ask, cfg) {
   const suggestion = PROVIDER_MODEL_SUGGESTION[provider];
   const modelRaw = (await ask(`  model (enter for ${suggestion}): `) ?? "").trim();
   const model = modelRaw || suggestion;
-  const idRaw = (await ask("  short name for this brain (e.g. sonnet): ") ?? "").trim();
+  const idHint = preset ? `${preset}-api` : "";
+  const idPrompt = idHint ? `  short name for this brain (enter for ${idHint}): ` : "  short name for this brain (e.g. sonnet): ";
+  const idRaw = (await ask(idPrompt) ?? "").trim() || idHint;
   if (!idRaw) {
     console.log(c.dim("  cancelled (no name)."));
     return null;
@@ -1603,8 +1624,12 @@ async function runSettings(ask) {
     } else if (choice === "t") {
       const pick = (await ask(`  toggle which brain [${BRAIN_IDS.join("/")}]: `) ?? "").trim();
       if (BRAIN_IDS.includes(pick)) {
+        const goneLogin = loginUnavailable(pick);
         if (!cfg.brains[pick].enabled && !isInstalled(cfg.brains[pick].command)) {
           console.log(c.dim(`  ${cfg.brains[pick].label} is not installed. Run "holt init" to install it.`));
+        } else if (!cfg.brains[pick].enabled && goneLogin && !cliBrainUsable(pick)) {
+          console.log(c.dim(`  ${cfg.brains[pick].label} has no sign-in any more and no ${goneLogin.provider.toUpperCase()}_API_KEY set.`));
+          console.log(c.dim(`  Get a key at ${goneLogin.keyUrl}, then connect it here with "c".`));
         } else {
           cfg.brains[pick].enabled = !cfg.brains[pick].enabled;
           if (!cfg.brains[pick].enabled && cfg.defaultBrain === pick) cfg.defaultBrain = selectableIds(cfg)[0] ?? null;
@@ -2139,6 +2164,75 @@ async function voiceClear() {
   console.log(had ? c.green("\n  Voice profile removed.\n") : c.dim("\n  No voice profile to remove.\n"));
 }
 
+// src/commands/login.ts
+function printLoginUnavailable(id, info) {
+  console.log("\n" + c.red(`${BRAIN_DEFS[id].label} sign-in is no longer available.`));
+  console.log(c.dim("  " + info.reason));
+  console.log("\n  It still works on an API key. Two ways:");
+  console.log("    1. " + c.accent(`Get a key at ${info.keyUrl}`));
+  console.log("    2. Either export it as " + c.accent(`${info.provider.toUpperCase()}_API_KEY`) + c.dim(` (the ${BRAIN_DEFS[id].command} CLI reads it too), or connect it to Holt as a direct API brain.`));
+}
+async function offerKeyInstead(ask, id, info) {
+  const cfg = loadConfig();
+  if (!cfg) {
+    console.log(c.dim('\n  This folder is not set up yet. Run "holt init" and connect it as a direct API brain.\n'));
+    return false;
+  }
+  if (!await askYesNo(ask, `
+  Connect ${BRAIN_DEFS[id].label} to Holt with an API key now? [Y/n] `, true)) {
+    console.log(c.dim('  Okay. Run "holt setting" then "c" whenever you have the key.\n'));
+    return false;
+  }
+  const brain = await connectApiBrain(ask, cfg, info.provider);
+  if (!brain) return false;
+  if (!cfg.defaultBrain || cfg.defaultBrain === id) {
+    cfg.defaultBrain = brain.id;
+    console.log(c.dim(`  default brain for this folder is now "${brain.id}".`));
+  }
+  if (cfg.brains[id]?.enabled) {
+    cfg.brains[id].enabled = false;
+    console.log(c.dim(`  turned off the ${BRAIN_DEFS[id].label} brain (no sign-in available).`));
+  }
+  saveConfig(cfg);
+  console.log(c.green("\n  Done. Start Holt: holt\n"));
+  return true;
+}
+async function login(which) {
+  const id = (which || "").toLowerCase();
+  if (!BRAIN_IDS.includes(id)) {
+    if (which) {
+      console.error(`
+  Unknown brain "${which}". Use one of: ${BRAIN_IDS.join(", ")}
+`);
+      process.exitCode = 1;
+    } else {
+      console.log(c.dim(`
+  Usage: holt login <${BRAIN_IDS.join("|")}>
+`));
+    }
+    return;
+  }
+  const gone = loginUnavailable(id);
+  if (gone) {
+    printLoginUnavailable(id, gone);
+    if (cliBrainUsable(id)) {
+      console.log(c.green(`
+  ${PROVIDER_ENV[gone.provider]} is already set, so ${BRAIN_DEFS[id].label} works as it is. Nothing to do.
+`));
+      return;
+    }
+    const { ask, close } = createReader();
+    await offerKeyInstead(ask, id, gone);
+    close();
+    return;
+  }
+  const s = BRAIN_SETUP[id];
+  console.log("\n" + c.accent(`Sign in to ${BRAIN_DEFS[id].label}`));
+  console.log(c.dim(`  Starting "${s.login.join(" ")}". Complete sign-in, then exit that tool.
+`));
+  await runInteractive(s.login[0], s.login.slice(1));
+}
+
 // src/commands/init.ts
 function parseBrains(raw, found) {
   const s = raw.trim().toLowerCase();
@@ -2159,7 +2253,8 @@ async function init() {
   const found = [];
   for (const id of BRAIN_IDS) {
     const ok2 = isInstalled(BRAIN_DEFS[id].command);
-    console.log(`  ${ok2 ? c.green("found  ") : c.dim("missing")}  ${BRAIN_DEFS[id].label} (${BRAIN_DEFS[id].command})`);
+    const note2 = loginUnavailable(id) && !cliBrainUsable(id) ? c.dim("  (needs an API key, no sign-in)") : "";
+    console.log(`  ${ok2 ? c.green("found  ") : c.dim("missing")}  ${BRAIN_DEFS[id].label} (${BRAIN_DEFS[id].command})${note2}`);
     if (ok2) found.push(id);
   }
   console.log("");
@@ -2171,11 +2266,24 @@ async function init() {
   const toInstall = chosen.filter((id) => !isInstalled(BRAIN_DEFS[id].command));
   const loginWanted = /* @__PURE__ */ new Set();
   for (const id of toInstall) {
+    if (loginUnavailable(id)) continue;
     if (await askYesNo(ask, `  ${BRAIN_DEFS[id].label} is not installed. Sign in after install? [Y/n] `, true)) loginWanted.add(id);
   }
   const connectedApiBrains = [];
+  const holder = defaultConfig();
+  for (const id of chosen) {
+    const gone = loginUnavailable(id);
+    if (!gone || cliBrainUsable(id)) continue;
+    printLoginUnavailable(id, gone);
+    if (await askYesNo(ask, `
+  Connect ${BRAIN_DEFS[id].label} with an API key now? [Y/n] `, true)) {
+      const brain = await connectApiBrain(ask, holder, gone.provider);
+      if (brain) connectedApiBrains.push(brain);
+    } else {
+      console.log(c.dim('  Okay. Run "holt setting" then "c" whenever you have the key.'));
+    }
+  }
   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);
   }
@@ -2246,7 +2354,7 @@ Default brain? [${chosen.join("/")}] (${defPick}): `) ?? "").trim();
     }
   }
   const cfg = loadConfig() ?? defaultConfig();
-  for (const id of BRAIN_IDS) cfg.brains[id].enabled = chosen.includes(id) && isInstalled(BRAIN_DEFS[id].command);
+  for (const id of BRAIN_IDS) cfg.brains[id].enabled = chosen.includes(id) && isInstalled(BRAIN_DEFS[id].command) && cliBrainUsable(id);
   for (const b of connectedApiBrains) if (!cfg.apiBrains.some((a) => a.id === b.id)) cfg.apiBrains.push(b);
   cfg.defaultBrain = cfg.brains[defaultBrain].enabled ? defaultBrain : BRAIN_IDS.find((id) => cfg.brains[id].enabled) ?? cfg.apiBrains[0]?.id ?? null;
   saveConfig(cfg);
@@ -2259,9 +2367,9 @@ Default brain? [${chosen.join("/")}] (${defPick}): `) ?? "").trim();
       console.log("\nStart chatting:");
       console.log("  " + c.accent(`source ${aliasNeedsSource}`) + c.dim("   (once; new terminals will not need it)"));
       console.log("  " + c.accent(aliasAns) + "\n");
-      console.log(c.dim("  Or right now, without sourcing: holt chat\n"));
+      console.log(c.dim("  Or right now, without sourcing: holt\n"));
     } else {
-      console.log("Start chatting:  " + c.accent("holt chat") + "\n");
+      console.log("Start chatting:  " + c.accent("holt") + "\n");
     }
   } else {
     console.log(c.dim('No brain is ready yet. Install one, then run "holt init" again.\n'));
@@ -2407,6 +2515,24 @@ function buildCronLine(job, holtPath) {
   const command = buildCommand(job, holtPath);
   return `${minute} ${hour} * * * ${command} # ${CRON_MARKER}${job.id}`;
 }
+function buildWindowsTaskFields(job, holtPath) {
+  let args;
+  if (job.runArgs && job.runArgs.length > 0) {
+    args = [...job.runArgs, "--quiet"];
+  } else {
+    args = ["run", job.task];
+    if (job.brain) args.push("--brain", job.brain);
+    args.push("--quiet", "--out", logPath(job.id));
+  }
+  const quoted = args.map((a) => /[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a);
+  return {
+    program: holtPath,
+    args: quoted.join(" "),
+    startIn: job.workspace,
+    when: job.when,
+    name: `Holt ${job.id}`
+  };
+}
 function stripCronLines(crontab, id) {
   const marker = `# ${CRON_MARKER}${id}`;
   const kept = crontab.split("\n").filter((line) => !line.includes(marker));
@@ -4073,29 +4199,6 @@ function saveReply(reply, format, name) {
   return path;
 }
 
-// src/commands/login.ts
-async function login(which) {
-  const id = (which || "").toLowerCase();
-  if (!BRAIN_IDS.includes(id)) {
-    if (which) {
-      console.error(`
-  Unknown brain "${which}". Use one of: ${BRAIN_IDS.join(", ")}
-`);
-      process.exitCode = 1;
-    } else {
-      console.log(c.dim(`
-  Usage: holt login <${BRAIN_IDS.join("|")}>
-`));
-    }
-    return;
-  }
-  const s = BRAIN_SETUP[id];
-  console.log("\n" + c.accent(`Sign in to ${BRAIN_DEFS[id].label}`));
-  console.log(c.dim(`  Starting "${s.login.join(" ")}". Complete sign-in, then exit that tool.
-`));
-  await runInteractive(s.login[0], s.login.slice(1));
-}
-
 // src/access.ts
 import { existsSync as existsSync11, realpathSync as realpathSync3, statSync as statSync6 } from "fs";
 import { homedir as homedir6 } from "os";
@@ -4235,7 +4338,7 @@ async function chat() {
       return;
     }
     await init();
-    console.log(c.dim('\nSetup done. Run "holt chat" to start talking.\n'));
+    console.log(c.dim('\nSetup done. Run "holt" to start talking.\n'));
     return;
   }
   let active = resolveActive2(cfg, cfg.defaultBrain);
@@ -4363,7 +4466,7 @@ async function chat() {
         sb.detach();
         close();
         await login(targetId);
-        console.log(c.dim('\n  Signed in. Run "holt chat" again to continue.\n'));
+        console.log(c.dim(loginUnavailable(targetId) ? '\n  Run "holt" again to continue.\n' : '\n  Signed in. Run "holt" again to continue.\n'));
         return;
       }
       if (cmd === "brain") {
@@ -4461,7 +4564,8 @@ async function chat() {
     };
     const res = active.kind === "cli" ? await runBrain(cfg.brains[active.id], prompt, onChunk, extraArgs) : await runApiBrain(active.brain, prompt, onChunk);
     if (looksLikeAuthError(res.text)) {
-      const hint = active.kind === "cli" ? `  ${active.label} looks signed out. Run "holt login ${active.id}" in a terminal, or type /login here.` : `  ${active.label} has no working key. Run "holt setting" to add or fix it.`;
+      const goneLogin = active.kind === "cli" ? loginUnavailable(active.id) : null;
+      const hint = goneLogin ? `  ${active.label} has no sign-in any more and no ${PROVIDER_ENV[goneLogin.provider]} to fall back on. Get a key at ${goneLogin.keyUrl}, then run "holt setting" to connect it.` : active.kind === "cli" ? `  ${active.label} looks signed out. Run "holt login ${active.id}" in a terminal, or type /login here.` : `  ${active.label} has no working key. Run "holt setting" to add or fix it.`;
       if (!streamed || !res.text.endsWith("\n")) console.log("");
       console.log(c.red(hint) + "\n");
       showStatus();
@@ -4600,11 +4704,12 @@ function resolveTarget(cfg) {
   if (!id) return null;
   if (BRAIN_IDS.includes(id)) {
     const bid = id;
-    return { kind: "cli", id: bid, label: cfg.brains[bid].label };
+    if (cliBrainUsable(bid)) return { kind: "cli", id: bid, label: cfg.brains[bid].label };
+  } else {
+    const api = findApiBrain(cfg, id);
+    if (api) return { kind: "api", label: `${id} (api: ${api.provider}/${api.model})` };
   }
-  const api = findApiBrain(cfg, id);
-  if (api) return { kind: "api", label: `${id} (api: ${api.provider}/${api.model})` };
-  const fallback = BRAIN_IDS.find((b) => cfg.brains[b].enabled);
+  const fallback = BRAIN_IDS.find((b) => cfg.brains[b].enabled && cliBrainUsable(b));
   if (fallback) return { kind: "cli", id: fallback, label: cfg.brains[fallback].label };
   return null;
 }
@@ -4644,13 +4749,23 @@ async function launch() {
   await ensureSetup();
   const target = resolveTarget(cfg);
   if (!target) {
+    const def = cfg.defaultBrain;
+    const gone = def && BRAIN_IDS.includes(def) ? loginUnavailable(def) : null;
+    if (gone) {
+      console.log("\n  " + c.red(`${cfg.brains[def].label} can no longer sign in.`));
+      console.log(c.dim("  " + gone.reason));
+      console.log(c.dim(`  Get a key at ${gone.keyUrl}, then run "holt setting" and press "c" to connect it.`));
+      if (cfg.apiBrains.length) {
+        console.log(c.dim(`  Or switch this folder to an API brain you already have (${cfg.apiBrains.map((b) => b.id).join(", ")}): "holt setting" then "d".`));
+      }
+      console.log("");
+      return;
+    }
     console.log(c.dim('\n  No brain is ready. Run "holt setting" or "holt init".\n'));
     return;
   }
   if (target.kind === "api") {
-    console.log(c.dim(`
-  launch needs a CLI brain; starting chat instead (default is ${target.label}).
-`));
+    console.log(renderIntroBox());
     await chat();
     return;
   }
@@ -4727,6 +4842,34 @@ async function memoryCmd(sub, rest = []) {
     close();
     return;
   }
+  if (action === "add" || action === "remember") {
+    let items = [];
+    const inline = rest.join(" ").trim();
+    if (inline) items = [inline];
+    else if (!process.stdin.isTTY) {
+      items = readFileSync14(0, "utf8").split("\n").map((l) => l.replace(/^\s*[-*]\s+/, "").trim()).filter(Boolean);
+    }
+    if (items.length === 0) {
+      console.log(c.dim('\n  Usage: holt memory add "<fact>"   (or pipe one fact per line on stdin)\n'));
+      close();
+      return;
+    }
+    const session = newSessionId();
+    let saved = 0;
+    let dupes = 0;
+    for (const item of items) {
+      if (await saveFact(item, session)) saved++;
+      else dupes++;
+    }
+    const dupNote = dupes ? c.dim(`  (${dupes} already known)`) : "";
+    console.log("\n" + c.green(`  Remembered ${saved} fact${saved === 1 ? "" : "s"}.`) + dupNote);
+    if (saved && !await embeddingsAvailable()) {
+      console.log(c.dim('  Saved in keyword mode. Run "holt doctor --fix" for semantic recall.'));
+    }
+    console.log("");
+    close();
+    return;
+  }
   if (action === "facts") {
     if (!existsSync13(factsMdPath())) {
       console.log(c.dim("\n  No facts distilled yet. They form when you end a chat session.\n"));
@@ -4767,9 +4910,9 @@ async function memoryCmd(sub, rest = []) {
     close();
     return;
   }
-  if (action && !["clear", "embed", "facts", "search", "global"].includes(action)) {
+  if (action && !["add", "remember", "clear", "embed", "facts", "search", "global"].includes(action)) {
     console.error(`
-  Unknown memory subcommand: "${sub}". Use: search <query> | facts | embed | global | clear
+  Unknown memory subcommand: "${sub}". Use: add <fact> | search <query> | facts | embed | global | clear
 `);
     process.exitCode = 1;
     close();
@@ -4791,7 +4934,8 @@ async function memoryCmd(sub, rest = []) {
   }
   const gEnabled = isGlobalEnabled(workspace());
   console.log(`  global      ${gEnabled ? c.green("on") + c.dim("  (contributes + reads shared facts)") : c.dim("off  (this folder is isolated, the default)")}`);
-  console.log(c.dim("\n  holt memory search <query>   find remembered moments"));
+  console.log(c.dim('\n  holt memory add "<fact>"     teach it something durable right now'));
+  console.log(c.dim("  holt memory search <query>   find remembered moments"));
   console.log(c.dim("  holt memory facts            show distilled facts (facts.md)"));
   console.log(c.dim("  holt memory embed            embed older memories for semantic recall"));
   console.log(c.dim("  holt memory global           share high-value facts across your folders"));
@@ -7066,7 +7210,7 @@ async function graph(args = []) {
     if (skipNotes.length) console.log(c.dim(`  ingest skipped: ${skipNotes.join(", ")}`));
   }
   if (turns.length === 0 && wikiPages.length === 0 && !codeGraph) {
-    console.log(c.dim('\n  No memory in this folder yet. Have a chat first with "holt chat", then come back.\n'));
+    console.log(c.dim('\n  No memory in this folder yet. Talk to Holt here first with "holt", then come back.\n'));
     console.log(c.dim(`  Or ingest this folder's code/docs: "holt graph --code" / "holt graph --docs".
 `));
     return;
@@ -7389,7 +7533,7 @@ function holtTools() {
 }
 
 // src/version.ts
-var VERSION = "0.15.1";
+var VERSION = "0.17.0";
 
 // src/commands/mcp.ts
 function printSetup() {
@@ -7573,7 +7717,7 @@ async function run(args) {
       close();
       if (!ok2) return;
     } else {
-      process.stderr.write("This folder is not trusted. Run holt init or holt chat here once, then schedule/run.\n");
+      process.stderr.write("This folder is not trusted. Run holt init here once, then schedule/run.\n");
       process.exitCode = 1;
       return;
     }
@@ -7704,11 +7848,28 @@ async function addCmd(rest) {
   console.log(`  log        ${logPath(job.id)}`);
   if (process.platform === "darwin") installDarwin(job, holtPath);
   else if (process.platform === "linux") installLinux(job, holtPath);
-  else {
+  else printManualInstall(job, holtPath);
+  console.log("");
+}
+function printManualInstall(job, holtPath) {
+  if (process.platform !== "win32") {
     console.log(c.dim("\n  Your OS has no built-in installer. Install this entry yourself:"));
     console.log("  " + buildCronLine(job, holtPath));
+    return;
+  }
+  const f = buildWindowsTaskFields(job, holtPath);
+  console.log(c.dim("\n  Saved, but not started: Holt cannot install timers on Windows yet."));
+  console.log(c.dim('  Open Task Scheduler, choose "Create Basic Task", and fill in:'));
+  console.log(`    Name        ${f.name}`);
+  console.log(`    Trigger     Daily at ${f.when}`);
+  console.log(`    Program     ${f.program}`);
+  console.log(`    Arguments   ${f.args}`);
+  console.log(`    Start in    ${f.startIn}`);
+  if (job.notify) {
+    console.log(
+      c.dim("\n  Note: --notify does not carry over to Task Scheduler. Read the log file instead.")
+    );
   }
-  console.log("");
 }
 function listCmd2() {
   const jobs = loadJobs();
@@ -7910,10 +8071,7 @@ function installSchedule(r) {
   addJob(job);
   if (process.platform === "darwin") installDarwin2(job, holtPath);
   else if (process.platform === "linux") installLinux2(job, holtPath);
-  else {
-    console.log(c.dim("\n  Your OS has no built-in installer. Install this entry yourself:"));
-    console.log("  " + buildCronLine(job, holtPath));
-  }
+  else printManualInstall(job, holtPath);
 }
 function removeScheduleDarwin(id) {
   const path = plistPath(id);
@@ -8080,7 +8238,7 @@ async function runCmd(rest) {
       close();
       if (!ok2) return;
     } else {
-      process.stderr.write("This folder is not trusted. Run holt init or holt chat here once, then run the routine.\n");
+      process.stderr.write("This folder is not trusted. Run holt init here once, then run the routine.\n");
       process.exitCode = 1;
       return;
     }
@@ -8483,8 +8641,14 @@ async function doctor(args = []) {
   for (const id of BRAIN_IDS) {
     const def = BRAIN_DEFS[id];
     const here = isInstalled(def.command);
-    if (here) installed.push(def.label);
+    const gone = loginUnavailable(id);
+    const usable = cliBrainUsable(id);
+    if (here && usable) installed.push(def.label);
     console.log(`  ${here ? c.green("installed") : c.dim("missing  ")}  ${def.label} ${c.dim(`(${def.command})`)}`);
+    if (here && gone && !usable) {
+      warn(`${def.label} cannot sign in any more. ${gone.reason}`);
+      steps.push(`Get a ${gone.provider} key at ${gone.keyUrl}, then connect it: holt setting -> "c".`);
+    }
   }
   const cfg = loadConfig();
   const apiBrains = cfg?.apiBrains ?? [];
@@ -8565,7 +8729,7 @@ async function doctor(args = []) {
     steps.unshift('Set up this folder: run "holt init".');
   }
   if (steps.length === 0) {
-    good('You are in good shape. Run "holt chat" to start.');
+    good('You are in good shape. Run "holt" to start.');
   } else {
     let n = 1;
     for (const s of steps) console.log(`  ${c.accent(String(n++) + ".")} ${s}`);
@@ -8875,7 +9039,7 @@ async function write(args) {
       close();
       if (!ok2) return;
     } else {
-      process.stderr.write("This folder is not trusted. Run holt init or holt chat here once first.\n");
+      process.stderr.write("This folder is not trusted. Run holt init here once first.\n");
       process.exitCode = 1;
       return;
     }
@@ -8989,12 +9153,12 @@ From your phone, while you sleep:
 
 Housekeeping:
   setting         Change brains, API connections, and your launch word (per folder)
-  login <brain>   Sign in to a brain: claude, codex, or gemini
+  login <brain>   Sign in to a brain: claude or codex
+                  (Gemini has no sign-in left; it routes you to an API key)
   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
@@ -9032,6 +9196,8 @@ async function main() {
     case "init":
       await init();
       break;
+    // Undocumented: bare `holt` reaches the REPL by itself for API brains.
+    // Kept as a working alias so older scripts and aliases do not break.
     case "chat":
       await chat();
       break;

package/package.json

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

package/skills/audit/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: audit
+description: A read-only health check of your Holt setup across the four rungs (Know, Reach, Do, Run), naming the gaps and the single next thing to fix. Use weekly, or when Holt feels less useful than expected.
+---
+
+# audit
+
+## When to use
+
+The user wants to know whether Holt is actually set up well, or why it feels
+thin. This skill inspects the real state of the folder and reports back. It
+changes nothing: no files written, no settings altered, no facts saved. If a fix
+is obvious, name the command and let the user run it.
+
+## The four rungs
+
+Each rung depends on the one below it. A gap low down makes everything above it
+worse, so always report the lowest gap first.
+
+1. **Know**: it holds facts about the user and their work.
+2. **Reach**: it can see the real material, not just what is typed at it.
+3. **Do**: it runs their repeated work as skills.
+4. **Run**: it acts without the user being present.
+
+## Instructions
+
+### Gather the state
+
+Run these and read the output. If you cannot run commands in this session, ask
+the user to paste the output of the first three rather than guessing.
+
+```
+holt memory                 facts count, embedded count, recall mode
+holt memory facts           what it actually knows
+holt voice show             is there a writing profile
+holt hook status            ambient memory in Claude Code
+holt skill list             which skills exist, and which are built in
+holt routine list           named jobs
+holt schedule list          timers
+holt doctor                 machine level problems
+holt wiki status            derived knowledge, if used
+```
+
+### Score each rung
+
+Be strict. A generous audit is a useless one. Mark each rung **solid**, **thin**,
+or **missing**, and say what the evidence was.
+
+- **Know** is solid when memory holds a few dozen facts that are about the
+  user's actual work, and recall is running on embeddings rather than keyword
+  match. It is thin when the facts are mostly setup trivia, or when
+  `holt memory` shows moments that were never embedded. Read the facts, do not
+  just count them: fifty facts about one afternoon is still thin.
+- **Reach** is solid when Holt sees material without the user pasting it: the
+  hook is installed, or MCP is wired into the tools they use, or the folder
+  holds the real files. It is missing when every session starts by pasting
+  context in by hand.
+- **Do** is solid when at least one skill exists that the user or their
+  registry provided, tuned to their work. Built-in skills alone do not count;
+  everyone has those. Note which ones are actually being used.
+- **Run** is solid when something has produced output while they were away, and
+  they read it. A routine that exists but has never run is thin, not solid.
+
+### Report
+
+1. Name the rung they are on: the highest one that is solid, with everything
+   below it also solid. Say it in one line.
+2. List the gaps, lowest rung first. For each, state what is missing and the
+   command that would close it.
+3. Give **one** next action. Not a menu, not a ranked list of five. The single
+   thing that unblocks the most.
+4. Flag anything actively broken separately from anything merely absent. A
+   scheduled routine that fails every night is worse than no routine, and a
+   memory in keyword mode is quietly degrading every answer.
+
+Keep the whole report short enough to read in a minute. It is a dashboard, not
+an essay.
+
+### Known traps to check for
+
+- **Keyword mode.** If `holt memory` says recall is keyword rather than
+  embeddings, semantic recall is off and every answer is worse. `holt doctor
+  --fix` usually repairs it.
+- **Unembedded moments.** If embedded count is below total, older memories are
+  invisible to semantic recall. `holt memory embed` fixes it in one pass.
+- **Hand-edited facts.** Facts added by editing `facts.md` directly are never
+  embedded, so they never come back through recall. They must be re-added with
+  `holt memory add`.
+- **Windows and timers.** On Windows, `holt schedule` and a routine's `--at`
+  time do not install anything. Anything on rung four there has to run another
+  way, so check the platform before calling rung four solid.
+- **Automation above an empty memory.** If Run looks solid while Know is thin,
+  say so bluntly. That setup produces confident wrong output on a timer, and it
+  is the most expensive failure on this list.
+
+## Example
+
+You are on rung two. Know and Reach are solid, Do is thin.
+
+Know: solid. 41 facts covering the agro project, the job search, and family
+health. Recall is on embeddings.
+Reach: solid. Hook installed, so Claude Code sessions recall automatically.
+Do: thin. Ten skills listed, all built in. Nothing tuned to your work.
+Run: missing. No routines, no schedules.
+
+Broken: 12 of 340 moments have no embeddings, so a slice of last month is
+invisible to recall.
+
+Next action: run `/skill level-up` and turn the weekly client update into a
+skill. Rung four is not worth touching until something on rung three has earned
+its place.

package/skills/level-up/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: level-up
+description: A weekly working session that turns one piece of recurring manual work into something Holt does for you, and ships it before the session ends. Use as a standing ritual once memory has real facts in it.
+---
+
+# level-up
+
+## When to use
+
+The user has been using Holt and wants it to carry more. This is the ritual that
+compounds: once a week, one drain becomes one shipped capability. Run it after
+memory holds real facts about their work; on an empty folder, run `onboard`
+first.
+
+The session fails if it ends in a plan. It succeeds if something exists that did
+not exist an hour ago.
+
+## Instructions
+
+### 1. Find the constraint
+
+Read what memory already knows. Relevant past notes are injected above; also run
+`holt memory facts` and search for the work they complain about:
+
+```
+holt memory search <what they keep doing by hand>
+```
+
+Then ask what ate their time this week, and what they did more than once. Pick
+**one**. The best candidate is frequent, rule-shaped, and low-stakes if it comes
+out slightly wrong. Say plainly why you picked it over the others.
+
+If several are tempting, choose the boring one. A dull thing that runs every
+week beats an ambitious thing that runs once.
+
+### 2. Decide what to do with it
+
+Three options, in this order:
+
+- **Drop it.** Does this task need to exist? Work that only continues out of
+  habit should be stopped, not automated. Ask this first and mean it; the
+  cheapest automation is the one you do not build.
+- **Automate it.** Rule-shaped and repeatable, with a checkable output.
+- **Hand it off.** It needs judgement, relationships, or accountability a
+  machine should not hold. Say so and move to the next candidate.
+
+Automating something that should have been dropped makes the waste permanent
+and harder to see. Push back before building.
+
+### 3. Map it before building
+
+Walk the task through in the user's own words: what starts it, what information
+it needs, what it produces, and who sees the output. Write the steps down. If
+you cannot state the steps in plain sentences, it is not ready to build.
+
+Then set how much rope it gets:
+
+- **Drafts, you send.** Anything that leaves the house: email, posts, messages.
+- **Runs, you review.** Produces a file or a note you read afterwards.
+- **Runs unattended.** Only for work that is reversible and already proven by
+  hand for a few cycles.
+
+Start one level more cautious than feels necessary. Moving up later is easy;
+un-sending is not.
+
+### 4. Build it now
+
+Pick the lightest thing that works:
+
+- A **skill**, when it is a repeatable way of thinking or writing:
+  `holt skill create <name>`, then write the instructions into its `SKILL.md`.
+  Check the registry first with `holt skill search <topic>`, because the work
+  may be done already.
+- A **routine**, when it is a task worth naming and rerunning:
+  `holt routine add <name> "<task>"`, run it with `holt routine run <name>`.
+- A **schedule**, when it should happen without being asked:
+  `holt schedule add`, or a scheduled routine. Only after it has produced good
+  output by hand at least twice.
+- A **connection**, when the blocker is that Holt cannot see the material:
+  `holt hook` for ambient memory in Claude Code, `holt mcp setup` for other
+  tools. Sometimes the whole win is that it can finally read the thing.
+
+Prefer a fixed sequence of steps over an open-ended agent. Predictable and
+slightly dumb beats clever and unrepeatable.
+
+### 5. Test it on something real
+
+Run it once, now, on genuine input, and read the output with the user. If it is
+wrong, fix it in this session. A capability that has never run on real data is
+not shipped.
+
+Then agree how it gets switched off: which command removes it, or which file to
+delete. Anything that runs on a timer needs a way to stop.
+
+### 6. Close the loop
+
+1. Save what was built and why, so next week starts informed:
+   ```
+   holt memory add "Built the <name> routine on <date>: <what it does, what triggers it>"
+   ```
+2. Note what to watch for: the failure mode most likely to show up first.
+3. Name the single next candidate from the list you did not pick, so the next
+   session starts with a running head start.
+
+## Example
+
+This week: forty minutes lost to writing the same client update every Friday.
+
+Not dropped, it is genuinely wanted. Not handed off, the facts live here.
+Automate it, at drafts-you-send, because it goes to a client.
+
+Built as a routine over the folder's memory, run once against this week's real
+work. First draft named the wrong milestone; instructions tightened, second
+draft was sendable. Off switch: `holt routine remove friday-update`.
+
+Watch for: it will keep sounding confident about numbers it has not been given.
+
+Next week's candidate: the invoice chase.

package/skills/onboard/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: onboard
+description: A guided first-day interview that fills Holt's memory with who you are and what you are working on, so recall is useful from day one instead of after weeks of use. Use on a fresh folder, or to top up a thin memory.
+---
+
+# onboard
+
+## When to use
+
+Holt is installed but it does not know the user yet. An empty memory makes every
+answer generic, which is the most common reason people install Holt and drift
+away. This skill front-loads the knowledge that recall needs, in about fifteen
+minutes, and ends with one real piece of work.
+
+Also use it when `holt memory` shows very few facts and answers still feel
+generic, or when the user starts a new folder for a different part of their life.
+
+## The ladder
+
+Holt gets useful in four rungs, in order. Onboarding is rung one.
+
+1. **Know**: it holds facts about you and your work. (`holt memory`)
+2. **Reach**: it can see your real material: files, notes, other tools. (`holt hook`, `holt mcp`)
+3. **Do**: it runs your repeated work as skills. (`holt skill`)
+4. **Run**: it acts without you being there. (`holt routine`, `holt schedule`)
+
+Do not skip ahead. Automation on top of an empty memory produces confident
+nonsense on a timer.
+
+## Instructions
+
+### Before you start
+
+1. Check what is already known: run `holt memory` and, if any facts exist,
+   `holt memory facts`. If the folder already holds real facts, say so and offer
+   a top-up on the thin areas instead of the full interview. Never re-ask
+   something already in memory.
+2. Set expectations in two lines: seven questions, about fifteen minutes, and
+   they can stop at any point because you save as you go.
+
+### Running the interview
+
+Ask **one question at a time.** Wait for the answer before moving on. Never
+present the whole list at once; a wall of questions is the main reason people
+abandon setup. Keep your own words short between questions.
+
+Ask for the real thing, never a description of it. "Paste the last update you
+sent your team" beats "how would you describe your writing style". Concrete
+input is what makes recall work later.
+
+If an answer is thin or abstract, ask one follow-up for a specific name, number,
+or example, then move on. Two follow-ups on one question is too many.
+
+The seven questions:
+
+1. **Who you are.** What is your work, and what does a normal day actually
+   involve? Get the role, and what they are responsible for.
+2. **What is live.** The three to five things genuinely in flight right now, and
+   the state of each. Push for status, not just titles.
+3. **Who matters.** The people, clients, teams, or companies that come up
+   regularly, and how each relates to them. Names matter here.
+4. **Standing rules.** Decisions and preferences you should never re-ask:
+   how they want to be spoken to, what is off limits, choices already made.
+5. **Where the work lives.** Which folders, tools, and accounts hold the real
+   material. This becomes the map for rung two, so note what is not reachable
+   yet rather than pretending it is.
+6. **What drains the time.** The recurring work they resent doing by hand. Ask
+   for the last three times it happened. These are the candidates the `level-up`
+   skill will draw from later.
+7. **Their voice.** Ask them to paste two or three samples of their real
+   writing: a sent email, a message, a published post. Then run
+   `holt voice add <file>` if the samples are in files, or tell them the command
+   so their drafts sound like them rather than like a model.
+
+### Saving as you go
+
+After every two questions, write what you learned to memory with:
+
+```
+holt memory add "<one durable fact>"
+```
+
+One fact per call. Several facts can be piped in at once, one per line.
+
+Write facts that will still be true in a month and that a future session could
+not guess. "Runs product for a fintech in Bhubaneswar, nine years in" is a fact.
+"Wants to be more productive" is noise. Include names, numbers, and dates. Write
+the fact so it stands alone, because recall will surface it without this
+conversation around it.
+
+If you cannot run commands in this session, write the facts out as a block of
+`holt memory add` lines and ask the user to paste them into their terminal.
+Do not hand-edit `facts.md`: facts added that way are never embedded, so
+semantic recall will not find them.
+
+### Finishing
+
+1. Show what was captured: run `holt memory facts` so they see their own words
+   stored in a file they own and can edit.
+2. Prove it works. Ask one question whose answer depends on what they just told
+   you, and answer it from memory. This is the moment the tool becomes real, so
+   do not skip it.
+3. Do one real thing now. Pick the smallest useful task from what they said
+   drains their time and complete it in this session. An artifact beats a plan.
+4. Name rung two. Tell them the single next step, usually `holt hook` so Claude
+   Code remembers automatically, or `holt mcp setup` to reach their other tools.
+   One step, not a menu.
+5. Point at the ritual: `/skill level-up` weekly turns one drain into one
+   automation, and `/skill audit` shows which rung they are on.
+
+## Example
+
+Not: "Tell me about your business, your projects, your clients, your
+preferences, and your writing style."
+
+Instead: "First one. What is your work, and what does a normal Tuesday actually
+look like?" then, after the answer: "Got it. Now the live list: what are the three to five
+things genuinely in flight this week?"
+
+Then, quietly, between questions:
+
+```
+holt memory add "Senior product manager, nine years, currently between roles and job-hunting in the Netherlands"
+holt memory add "Runs Sasyam Agro with an uncle in Bargarh; demo plots are on the uncle's land"
+```