backthread 0.7.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "backthread",
   "displayName": "Backthread",
   "description": "Backthread helps you understand your codebase while AI ships features. It captures the why behind every Claude Code session so you can ask \"how does X work?\" without digging through PRs.",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "author": {
     "name": "Backthread"
   },

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/backthread?logo=npm)](https://www.npmjs.com/package/backthread)
 [![license](https://img.shields.io/npm/l/backthread?label=license)](./LICENSE)
 
-**Keep the thread on what your AI agent actually shipped.**
+**Backthread keeps the thread on what your AI coding agent ships — it captures the why behind every change and turns it into a living 'How it works' view of your codebase you can actually query.**
 
 ```bash
 npx backthread
@@ -63,8 +63,9 @@ The bare command is the unified front door. Under the hood it:
 
 Then keep coding. At the end of every Claude Code session, Backthread captures
 the decisions automatically — nothing to remember. Ask *"how does X work?"* right
-inside Claude Code (the `backthread` MCP server exposes a `query` tool), or open
-the live diagram at [app.backthread.dev](https://app.backthread.dev).
+from the terminal (`backthread how "how does auth work?"`) or inside Claude Code
+(the `backthread` MCP server exposes a `query` tool + a `/backthread:how` slash
+command), or open the live diagram at [app.backthread.dev](https://app.backthread.dev).
 
 ### Claude Code plugin (alternative)
 
@@ -102,15 +103,18 @@ instead, and Codex users the [plugin](https://github.com/backthread/backthread/t
 ## Commands
 
 ```
-backthread           Set up Backthread — the unified front door (sign in + connect + capture).
-                     Idempotent: a returning user is told they're good to go.
-backthread install   Set up capture for this repo (sign in + hook + backfill)
-backthread start     First-run for the Claude Code plugin (sign in + your next step)
-backthread login     Authorize this device (opens your browser)
-backthread whoami    Show this device's config (your token is never printed)
-backthread capture   Capture a session's decisions (run automatically by the hook)
-backthread mcp       Start the MCP server — the capture + "how does X work?" query tools
-backthread help      Show usage
+backthread                     Set up Backthread — the front door (sign in + connect + capture).
+                               Idempotent: a returning user is told they're good to go.
+backthread how "<question>"    Ask how/why something works — a grounded, cited answer from your log
+backthread install             Set up capture for this repo (sign in + hook + backfill)
+backthread login / logout      Authorize this device / sign it out (drops the local token)
+backthread doctor              Diagnose your setup (auth, hook, connectivity, version, repo)
+backthread update              Update a global install to the latest (also -u)
+backthread version             Print the installed version (also --version, -v)
+backthread whoami              Show this device's config (your token is never printed)
+backthread capture             Capture a session's decisions (run automatically by the hook)
+backthread mcp                 Start the MCP server — the capture + "how does X work?" query tools
+backthread help                Show the full usage (also --help, -h)
 ```
 
 ## Requirements

package/dist-bundle/backthread.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -6887,7 +6891,7 @@ var require_dist = __commonJS({
 
 // src/bin/backthread.ts
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { realpathSync } from "node:fs";
+import { realpathSync as realpathSync2 } from "node:fs";
 
 // src/login.ts
 import { hostname } from "node:os";
@@ -6945,7 +6949,7 @@ function browserCommand(platform) {
     case "darwin":
       return { cmd: "open", prefixArgs: [] };
     case "win32":
-      return { cmd: "cmd", prefixArgs: ["/c", "start", ""] };
+      return { cmd: "rundll32", prefixArgs: ["url.dll,FileProtocolHandler"] };
     default:
       return { cmd: "xdg-open", prefixArgs: [] };
   }
@@ -7258,7 +7262,7 @@ async function pollForToken(sessionId, keypair, opts = {}) {
       return { ok: false, reason: "expired", message: "the login session expired before you authorized" };
     }
     if (status === "consumed") {
-      return { ok: false, reason: "error", message: "this login was already used \u2014 start a fresh `bt login`" };
+      return { ok: false, reason: "error", message: "this login was already used \u2014 start a fresh `backthread login`" };
     }
     await sleep(interval);
   }
@@ -7348,8 +7352,416 @@ async function ensureAuth(opts = {}) {
   return readConfig(env);
 }
 
+// src/logout.ts
+async function runLogout(env = process.env) {
+  const where = configLocationHint3(env);
+  let cfg;
+  try {
+    cfg = await readConfig(env);
+  } catch (err) {
+    return { ok: false, cleared: false, message: `Couldn't read ${where} to sign out (${err.message ?? err}). Check its permissions and retry.` };
+  }
+  if (!cfg.device_token) {
+    return { ok: true, cleared: false, message: `Already signed out \u2014 no device token in ${where}.` };
+  }
+  const next = {};
+  if (cfg.account !== void 0) next.account = cfg.account;
+  if (cfg.repo !== void 0) next.repo = cfg.repo;
+  await writeConfig(next, env);
+  const kept = cfg.repo ? ` (kept your ${cfg.repo} link)` : "";
+  return {
+    ok: true,
+    cleared: true,
+    message: `Signed out. Removed this device's token from ${where}${kept}.
+Revoke it server-side under Account \u2192 Connected devices; \`backthread login\` re-authorizes.`
+  };
+}
+function configLocationHint3(env) {
+  return env.BACKTHREAD_CONFIG_DIR ? configPath(env) : "~/.backthread/config.json";
+}
+
+// src/update.ts
+import { realpathSync } from "node:fs";
+
+// src/upgradeNudge.ts
+import { join as join3 } from "node:path";
+import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, chmod as chmod2 } from "node:fs/promises";
+function upgradeNudgeStatePath(env = process.env) {
+  return join3(configDir(env), "upgrade-nudge.json");
+}
+var UPGRADE_NUDGE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+function parseState(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+      const at = obj.lastUpgradeNudgeAt;
+      if (typeof at === "number" && Number.isFinite(at)) return { lastUpgradeNudgeAt: at };
+    }
+  } catch {
+  }
+  return {};
+}
+async function readState(env) {
+  try {
+    return parseState(await readFile2(upgradeNudgeStatePath(env), "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function writeState(state, env) {
+  try {
+    const dir = configDir(env);
+    await mkdir2(dir, { recursive: true, mode: DIR_MODE });
+    await chmod2(dir, DIR_MODE).catch(() => {
+    });
+    const path = upgradeNudgeStatePath(env);
+    await writeFile2(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
+    await chmod2(path, CONFIG_MODE).catch(() => {
+    });
+  } catch {
+  }
+}
+async function maybeUpgradeNudge(upgrade, deps = {}) {
+  try {
+    if (typeof upgrade !== "string" || upgrade.trim().length === 0) return null;
+    const env = deps.env ?? process.env;
+    const now = deps.now ? deps.now() : Date.now();
+    const state = await readState(env);
+    if (typeof state.lastUpgradeNudgeAt === "number" && now - state.lastUpgradeNudgeAt < UPGRADE_NUDGE_THROTTLE_MS) {
+      return null;
+    }
+    await writeState({ lastUpgradeNudgeAt: now }, env);
+    return upgrade.trim();
+  } catch {
+    return null;
+  }
+}
+async function resetUpgradeNudge(deps = {}) {
+  try {
+    const env = deps.env ?? process.env;
+    const now = deps.now ? deps.now() : Date.now();
+    await writeState({ lastUpgradeNudgeAt: now }, env);
+  } catch {
+  }
+}
+
+// src/npm.ts
+import { execFile } from "node:child_process";
+function runNpm(args) {
+  const isWin = process.platform === "win32";
+  const npm = isWin ? "npm.cmd" : "npm";
+  return new Promise((resolve) => {
+    try {
+      execFile(
+        npm,
+        args,
+        { timeout: 12e4, windowsHide: true, shell: isWin, maxBuffer: 8 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          resolve({
+            ok: !err,
+            stdout: (stdout ?? "").toString().trim(),
+            stderr: (stderr ?? "").toString().trim()
+          });
+        }
+      );
+    } catch (e) {
+      resolve({ ok: false, stdout: "", stderr: e.message ?? String(e) });
+    }
+  });
+}
+
+// src/update.ts
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+var NPX_SEGMENT_RE = /(?:^|[\\/])_npx[\\/]/;
+function detectInstallContext(env, scriptPath) {
+  if (typeof env.CLAUDE_PLUGIN_ROOT === "string" && env.CLAUDE_PLUGIN_ROOT.trim().length > 0) return "plugin";
+  if (scriptPath && NPX_SEGMENT_RE.test(scriptPath)) return "npx";
+  return "global";
+}
+function resolveScriptPath() {
+  const raw = process.argv[1] ?? "";
+  if (!raw) return "";
+  if (NPX_SEGMENT_RE.test(raw)) return raw;
+  try {
+    return realpathSync(raw);
+  } catch {
+    return raw;
+  }
+}
+function firstLine(s) {
+  const line = s.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  return line ?? "unknown npm error";
+}
+async function runUpdate(deps = {}) {
+  const env = deps.env ?? process.env;
+  const log = deps.log ?? ((m) => console.error(m));
+  const current = (deps.currentVersion ?? cliVersion)();
+  const runNpm2 = deps.runNpm ?? runNpm;
+  const resetNudge = deps.resetNudge ?? ((e) => resetUpgradeNudge({ env: e }));
+  const scriptPath = deps.scriptPath ?? resolveScriptPath();
+  const context = detectInstallContext(env, scriptPath);
+  if (context === "npx") {
+    return {
+      ok: true,
+      context,
+      updated: false,
+      message: "You're running Backthread via `npx`, which already fetches the latest published version\non every run \u2014 nothing to update. Want a pinned, always-available binary?\n  npm i -g backthread\nThen `backthread update` pulls new releases on demand."
+    };
+  }
+  if (context === "plugin") {
+    return {
+      ok: true,
+      context,
+      updated: false,
+      message: "This is the Claude Code plugin's bundled copy of Backthread \u2014 the plugin manages it,\nnot npm. Update it from Claude Code:\n  /plugin update backthread\nFor a standalone terminal CLI too: `npm i -g backthread`."
+    };
+  }
+  log("Checking npm for the latest backthread\u2026");
+  const view = await runNpm2(["view", "backthread", "version"]);
+  if (!view.ok || !SEMVER_RE.test(view.stdout)) {
+    const why = view.ok ? `unexpected npm output "${view.stdout}"` : firstLine(view.stderr);
+    return {
+      ok: false,
+      context,
+      updated: false,
+      message: `Couldn't check npm for the latest version (${why}). Are you online? Your current install (${current}) is untouched.`
+    };
+  }
+  const latest = view.stdout;
+  if (current === latest) {
+    await resetNudge(env);
+    return { ok: true, context, updated: false, message: `Backthread is already up to date (${current} is the latest).` };
+  }
+  log(`Updating backthread ${current} \u2192 ${latest} (npm i -g backthread@latest)\u2026`);
+  const install = await runNpm2(["install", "-g", "backthread@latest"]);
+  if (!install.ok) {
+    return {
+      ok: false,
+      context,
+      updated: false,
+      message: `npm couldn't install backthread@latest: ${firstLine(install.stderr)}
+Your current install (${current}) is untouched. If this is a permissions error, retry with your global-install method (e.g. a Node version manager, or sudo).`
+    };
+  }
+  await resetNudge(env);
+  return {
+    ok: true,
+    context,
+    updated: true,
+    message: `Updated Backthread ${current} \u2192 ${latest}. Restart any long-running sessions to pick it up.`
+  };
+}
+
+// src/doctor.ts
+import { homedir as homedir2 } from "node:os";
+import { join as join4 } from "node:path";
+import { readFile as readFile3, stat } from "node:fs/promises";
+var SEMVER_RE2 = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+var REPO_SLUG_RE = /^[^/\s]+\/[^/\s]+$/;
+async function loadConfig(env) {
+  try {
+    return { config: await readConfig(env), error: null };
+  } catch (e) {
+    return { config: null, error: e };
+  }
+}
+function authCheck(loaded, env) {
+  if (loaded.error) {
+    return {
+      key: "auth",
+      label: "Auth",
+      status: "fail",
+      critical: true,
+      detail: `couldn't read ${configHint(env)} (${loaded.error.message ?? loaded.error}) \u2014 check its permissions`
+    };
+  }
+  if (loaded.config?.device_token) {
+    return { key: "auth", label: "Auth", status: "ok", detail: "signed in (device token present)" };
+  }
+  return { key: "auth", label: "Auth", status: "fail", critical: true, detail: "not signed in \u2014 run `backthread login`" };
+}
+async function permsCheck(deps, env) {
+  if (process.platform === "win32") {
+    return { key: "perms", label: "Config perms", status: "info", detail: "n/a on Windows (POSIX modes not enforced)" };
+  }
+  const doStat = deps.statImpl ?? ((p) => stat(p));
+  const filePath = configPath(env);
+  const dirPath = configDir(env);
+  let fileMode = null;
+  let dirMode = null;
+  try {
+    fileMode = (await doStat(filePath)).mode & 511;
+  } catch {
+    return { key: "perms", label: "Config perms", status: "info", detail: "no config file yet (run `backthread login`)" };
+  }
+  try {
+    dirMode = (await doStat(dirPath)).mode & 511;
+  } catch {
+    dirMode = null;
+  }
+  const fileLoose = (fileMode & 63) !== 0;
+  const dirLoose = dirMode !== null && (dirMode & 63) !== 0;
+  if (fileLoose || dirLoose) {
+    return {
+      key: "perms",
+      label: "Config perms",
+      status: "warn",
+      detail: `too open (config ${octal(fileMode)}${dirMode !== null ? `, dir ${octal(dirMode)}` : ""}) \u2014 run \`chmod 600 ${configHint(env)}\` (dir 700)`
+    };
+  }
+  return { key: "perms", label: "Config perms", status: "ok", detail: `config 0600${dirMode !== null ? ", dir 0700" : ""}` };
+}
+function repoCheck(loaded) {
+  if (loaded.error) {
+    return { key: "repo", label: "Repo", status: "warn", detail: "could not read the connected repo" };
+  }
+  const repo = loaded.config?.repo;
+  if (repo && REPO_SLUG_RE.test(repo)) {
+    return { key: "repo", label: "Repo", status: "ok", detail: repo };
+  }
+  if (repo) {
+    return { key: "repo", label: "Repo", status: "warn", detail: `connected slug "${repo}" is not owner/name \u2014 reconnect in the web app` };
+  }
+  return { key: "repo", label: "Repo", status: "warn", detail: "no repo connected \u2014 run `backthread install` (or connect it in the web app)" };
+}
+var AGENT_HOOK_FILES = [
+  { agent: "claude-code", files: (h) => [join4(h, ".claude", "settings.json")] },
+  { agent: "gemini", files: (h) => [join4(h, ".gemini", "settings.json")] },
+  { agent: "codex", files: (h) => [join4(h, ".codex", "hooks.json"), join4(h, ".codex", "config.toml")] },
+  { agent: "cursor", files: (h) => [join4(h, ".cursor", "hooks.json"), join4(h, ".cursor", "mcp.json")] }
+];
+async function hookCheck(deps, env) {
+  const home = deps.home ?? homedir2();
+  const cwd = deps.cwd ?? process.cwd();
+  const doRead = deps.readFileImpl ?? ((p) => readFile3(p, "utf8"));
+  const mentions = async (path) => {
+    try {
+      return (await doRead(path)).includes("backthread");
+    } catch {
+      return false;
+    }
+  };
+  const asPlugin = typeof env.CLAUDE_PLUGIN_ROOT === "string" && env.CLAUDE_PLUGIN_ROOT.trim().length > 0;
+  const wired = [];
+  if (asPlugin) wired.push("claude-code (plugin)");
+  for (const { agent, files } of AGENT_HOOK_FILES) {
+    for (const f of files(home)) {
+      if (await mentions(f)) {
+        wired.push(agent);
+        break;
+      }
+    }
+  }
+  const projectScoped = await mentions(join4(cwd, ".claude", "settings.json")) || await mentions(join4(cwd, ".claude", "settings.local.json"));
+  const userScopedCC = asPlugin || await mentions(join4(home, ".claude", "settings.json"));
+  const uniqueWired = Array.from(new Set(wired));
+  if (projectScoped && !userScopedCC) {
+    return {
+      key: "hook",
+      label: "Capture hook",
+      status: "warn",
+      detail: "PROJECT-scoped only \u2014 blind in git worktrees + other repos (ARP-680). Re-run `backthread install` for the user-scope hook."
+    };
+  }
+  if (uniqueWired.length > 0) {
+    return { key: "hook", label: "Capture hook", status: "ok", detail: `wired for ${uniqueWired.join(", ")}` };
+  }
+  return {
+    key: "hook",
+    label: "Capture hook",
+    status: "warn",
+    detail: "not detected \u2014 run `backthread install` here (or `backthread install --agent <codex|cursor|gemini>`)"
+  };
+}
+async function connectivityCheck(deps, env) {
+  const doFetch = deps.fetchImpl ?? fetch;
+  const timeout = deps.connectTimeoutMs ?? 5e3;
+  const targets = [
+    { name: "worker", url: workerBaseUrl(env) },
+    { name: "functions", url: functionsBaseUrl(env) }
+  ];
+  const results = await Promise.all(
+    targets.map(async ({ name, url: url2 }) => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      try {
+        const res = await doFetch(url2, { method: "GET", signal: controller.signal });
+        await res.body?.cancel?.().catch(() => {
+        });
+        return { name, reachable: true };
+      } catch {
+        return { name, reachable: false };
+      } finally {
+        clearTimeout(timer);
+      }
+    })
+  );
+  const down = results.filter((r) => !r.reachable).map((r) => r.name);
+  if (down.length === 0) {
+    return { key: "connectivity", label: "Connectivity", status: "ok", detail: "worker + functions reachable" };
+  }
+  return {
+    key: "connectivity",
+    label: "Connectivity",
+    status: "warn",
+    detail: `couldn't reach ${down.join(" + ")} (offline, or blocked by a proxy/firewall?)`
+  };
+}
+async function versionCheck(deps) {
+  const current = cliVersion();
+  const redact = redactVersion();
+  const base = `backthread ${current} \xB7 redact ${redact}`;
+  const runNpm2 = deps.runNpm ?? runNpm;
+  const view = await runNpm2(["view", "backthread", "version"]);
+  if (!view.ok || !SEMVER_RE2.test(view.stdout)) {
+    return { key: "version", label: "Version", status: "info", detail: `${base} (couldn't check npm for the latest \u2014 offline?)` };
+  }
+  const latest = view.stdout;
+  if (current === latest) {
+    return { key: "version", label: "Version", status: "ok", detail: `${base} (latest)` };
+  }
+  return { key: "version", label: "Version", status: "info", detail: `${base} \u2014 update available (${latest}): \`backthread update\`` };
+}
+async function collectChecks(deps = {}) {
+  const env = deps.env ?? process.env;
+  const loaded = await loadConfig(env);
+  const [perms, hook, connectivity, version2] = await Promise.all([
+    permsCheck(deps, env),
+    hookCheck(deps, env),
+    connectivityCheck(deps, env),
+    versionCheck(deps)
+  ]);
+  return [authCheck(loaded, env), perms, repoCheck(loaded), hook, connectivity, version2];
+}
+var GLYPH = { ok: "\u2713", fail: "\u2717", warn: "\u26A0", info: "\u2139" };
+function formatReport(checks) {
+  const width = Math.max(...checks.map((c) => c.label.length));
+  const lines = checks.map((c) => `${GLYPH[c.status]} ${c.label.padEnd(width)}  ${c.detail}`);
+  const fails = checks.filter((c) => c.status === "fail").length;
+  const warns = checks.filter((c) => c.status === "warn").length;
+  let summary;
+  if (fails > 0) summary = `
+${fails} issue${fails === 1 ? "" : "s"} to fix \u2014 see the \u2717 above, then re-run \`backthread doctor\`.`;
+  else if (warns > 0) summary = `
+Mostly good \u2014 the \u26A0 above are worth a look but capture can still run.`;
+  else summary = `
+All good \u2014 Backthread is set up. \u{1F9F5}`;
+  return ["backthread doctor\n", ...lines, summary].join("\n");
+}
+async function runDoctor(deps = {}) {
+  const checks = await collectChecks(deps);
+  const exitCode = checks.some((c) => c.status === "fail" && c.critical) ? 1 : 0;
+  return { text: formatReport(checks), exitCode, checks };
+}
+function octal(mode) {
+  return "0" + mode.toString(8).padStart(3, "0");
+}
+function configHint(env) {
+  return env.BACKTHREAD_CONFIG_DIR ? configPath(env) : "~/.backthread/config.json";
+}
+
 // src/capture.ts
-import { readFile as readFile9 } from "node:fs/promises";
+import { readFile as readFile10 } from "node:fs/promises";
 
 // ../packages/redact/src/index.ts
 var CODE_REDACTION = "[code redacted]";
@@ -7709,8 +8121,8 @@ async function inferDecisions(transcript, config2, opts = {}) {
 }
 
 // src/connectNudge.ts
-import { join as join3 } from "node:path";
-import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, chmod as chmod2 } from "node:fs/promises";
+import { join as join5 } from "node:path";
+import { readFile as readFile4, writeFile as writeFile3, mkdir as mkdir3, chmod as chmod3 } from "node:fs/promises";
 function parseRepoStatus(value) {
   return value === "connected" || value === "not_connected" || value === "disconnected" ? value : null;
 }
@@ -7723,10 +8135,10 @@ function parseNextStep(value) {
   return "absent";
 }
 function nudgeStatePath(env = process.env) {
-  return join3(configDir(env), "connect-nudge.json");
+  return join5(configDir(env), "connect-nudge.json");
 }
 var MAX_REMEMBERED = 50;
-function parseState(raw) {
+function parseState2(raw) {
   try {
     const obj = JSON.parse(raw);
     if (obj && typeof obj === "object" && Array.isArray(obj.nudged)) {
@@ -7737,22 +8149,22 @@ function parseState(raw) {
   }
   return { nudged: [] };
 }
-async function readState(env) {
+async function readState2(env) {
   try {
-    return parseState(await readFile2(nudgeStatePath(env), "utf8"));
+    return parseState2(await readFile4(nudgeStatePath(env), "utf8"));
   } catch {
     return { nudged: [] };
   }
 }
-async function writeState(state, env) {
+async function writeState2(state, env) {
   try {
     const dir = configDir(env);
-    await mkdir2(dir, { recursive: true, mode: DIR_MODE });
-    await chmod2(dir, DIR_MODE).catch(() => {
+    await mkdir3(dir, { recursive: true, mode: DIR_MODE });
+    await chmod3(dir, DIR_MODE).catch(() => {
     });
     const path = nudgeStatePath(env);
-    await writeFile2(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
-    await chmod2(path, CONFIG_MODE).catch(() => {
+    await writeFile3(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
+    await chmod3(path, CONFIG_MODE).catch(() => {
     });
   } catch {
   }
@@ -7790,12 +8202,12 @@ async function maybeNudge(status, repo, sessionId, deps = {}) {
     }
     if (line === null) return false;
     const log = deps.log ?? ((m) => console.error(m));
-    const state = await readState(env);
+    const state = await readState2(env);
     if (state.nudged.includes(sessionId)) return false;
     log(line);
     const nudged = [...state.nudged, sessionId];
     if (nudged.length > MAX_REMEMBERED) nudged.splice(0, nudged.length - MAX_REMEMBERED);
-    await writeState({ nudged }, env);
+    await writeState2({ nudged }, env);
     return true;
   } catch {
     return false;
@@ -7803,84 +8215,28 @@ async function maybeNudge(status, repo, sessionId, deps = {}) {
 }
 
 // src/firstRun.ts
-import { join as join10 } from "node:path";
-import { readFile as readFile8, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod6 } from "node:fs/promises";
+import { join as join11 } from "node:path";
+import { readFile as readFile9, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod6 } from "node:fs/promises";
 
 // src/install.ts
-import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir6 } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
-import { join as join9 } from "node:path";
-
-// src/captureCommand.ts
-import { stat } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { join as join5 } from "node:path";
-
-// src/upgradeNudge.ts
-import { join as join4 } from "node:path";
-import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3, chmod as chmod3 } from "node:fs/promises";
-function upgradeNudgeStatePath(env = process.env) {
-  return join4(configDir(env), "upgrade-nudge.json");
-}
-var UPGRADE_NUDGE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
-function parseState2(raw) {
-  try {
-    const obj = JSON.parse(raw);
-    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
-      const at = obj.lastUpgradeNudgeAt;
-      if (typeof at === "number" && Number.isFinite(at)) return { lastUpgradeNudgeAt: at };
-    }
-  } catch {
-  }
-  return {};
-}
-async function readState2(env) {
-  try {
-    return parseState2(await readFile3(upgradeNudgeStatePath(env), "utf8"));
-  } catch {
-    return {};
-  }
-}
-async function writeState2(state, env) {
-  try {
-    const dir = configDir(env);
-    await mkdir3(dir, { recursive: true, mode: DIR_MODE });
-    await chmod3(dir, DIR_MODE).catch(() => {
-    });
-    const path = upgradeNudgeStatePath(env);
-    await writeFile3(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
-    await chmod3(path, CONFIG_MODE).catch(() => {
-    });
-  } catch {
-  }
-}
-async function maybeUpgradeNudge(upgrade, deps = {}) {
-  try {
-    if (typeof upgrade !== "string" || upgrade.trim().length === 0) return null;
-    const env = deps.env ?? process.env;
-    const now = deps.now ? deps.now() : Date.now();
-    const state = await readState2(env);
-    if (typeof state.lastUpgradeNudgeAt === "number" && now - state.lastUpgradeNudgeAt < UPGRADE_NUDGE_THROTTLE_MS) {
-      return null;
-    }
-    await writeState2({ lastUpgradeNudgeAt: now }, env);
-    return upgrade.trim();
-  } catch {
-    return null;
-  }
-}
+import { readFile as readFile8, writeFile as writeFile6, mkdir as mkdir6 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join10 } from "node:path";
 
 // src/captureCommand.ts
+import { stat as stat2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { join as join6 } from "node:path";
 function slugifyCwd(cwd) {
   return cwd.replace(/[^A-Za-z0-9]/g, "-");
 }
 function deriveTranscriptPath(sessionId, cwd, home) {
   if (!sessionId || sessionId.trim().length === 0) return null;
-  return join5(home, ".claude", "projects", slugifyCwd(cwd), `${sessionId}.jsonl`);
+  return join6(home, ".claude", "projects", slugifyCwd(cwd), `${sessionId}.jsonl`);
 }
 async function defaultStat(path) {
   try {
-    const s = await stat(path);
+    const s = await stat2(path);
     return s.isFile();
   } catch {
     return false;
@@ -7889,7 +8245,7 @@ async function defaultStat(path) {
 async function resolveTranscriptPath(input, deps = {}) {
   const explicit = input.transcriptPath;
   if (explicit && explicit.trim().length > 0) return explicit;
-  const home = (deps.homedirImpl ?? homedir2)();
+  const home = (deps.homedirImpl ?? homedir3)();
   const cwd = input.cwd ?? process.cwd();
   const derived = deriveTranscriptPath(input.sessionId, cwd, home);
   if (!derived) return null;
@@ -7980,17 +8336,17 @@ function parseManualArgs(argv) {
 }
 
 // src/sweep.ts
-import { readFile as readFile5, stat as stat2, readdir } from "node:fs/promises";
+import { readFile as readFile6, stat as stat3, readdir } from "node:fs/promises";
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { homedir as homedir3 } from "node:os";
-import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join7 } from "node:path";
+import { homedir as homedir4 } from "node:os";
+import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join8 } from "node:path";
 
 // src/sweepLedger.ts
-import { join as join6 } from "node:path";
-import { readFile as readFile4, writeFile as writeFile4, mkdir as mkdir4, chmod as chmod4 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4, chmod as chmod4 } from "node:fs/promises";
 var MAX_PROCESSED = 2e4;
 function sweepStatePath(env = process.env) {
-  return join6(configDir(env), "sweep-state.json");
+  return join7(configDir(env), "sweep-state.json");
 }
 function parseSweepState(raw) {
   try {
@@ -8015,7 +8371,7 @@ function serializeSweepState(state) {
 }
 async function readSweepState(env = process.env) {
   try {
-    return parseSweepState(await readFile4(sweepStatePath(env), "utf8"));
+    return parseSweepState(await readFile5(sweepStatePath(env), "utf8"));
   } catch {
     return { processed: [], lastSweptAt: {} };
   }
@@ -8118,7 +8474,7 @@ async function defaultReadDir(dir) {
 }
 async function defaultPathExists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch {
     return false;
@@ -8132,7 +8488,7 @@ function defaultMainRoot(cwd) {
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     if (!out) return null;
-    const abs = isAbsolute2(out) ? out : join7(cwd, out);
+    const abs = isAbsolute2(out) ? out : join8(cwd, out);
     return dirname2(abs.replace(/\/+$/, ""));
   } catch {
     return null;
@@ -8150,7 +8506,7 @@ async function runSweep(input = {}, deps = {}) {
       return [];
     }
   };
-  const baseReadFile = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const baseReadFile = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
   const doReadFile = async (p) => {
     try {
       return await baseReadFile(p);
@@ -8179,7 +8535,7 @@ async function runSweep(input = {}, deps = {}) {
   const doReadState = deps.readSweepStateImpl ?? readSweepState;
   const doWriteState = deps.writeSweepStateImpl ?? writeSweepState;
   try {
-    const home = (deps.homedirImpl ?? homedir3)();
+    const home = (deps.homedirImpl ?? homedir4)();
     const now = (deps.nowImpl ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
     const cwd = input.cwd ?? process.cwd();
     const target = resolveRepo(cwd, readRemote);
@@ -8207,7 +8563,7 @@ async function runSweep(input = {}, deps = {}) {
     }
     const mainRoot = doMainRoot(cwd) ?? cwd;
     const mainSlug = slugifyCwd(mainRoot);
-    const projectsRoot = join7(home, ".claude", "projects");
+    const projectsRoot = join8(home, ".claude", "projects");
     const entries = await doReadDir(projectsRoot);
     const candidates = entries.filter((n) => n === mainSlug || n.startsWith(mainSlug + "-")).sort();
     const skip = new Set(state.processed);
@@ -8220,12 +8576,12 @@ async function runSweep(input = {}, deps = {}) {
     let captured = 0;
     let decisions = 0;
     for (const dirName of candidates) {
-      const dir = join7(projectsRoot, dirName);
+      const dir = join8(projectsRoot, dirName);
       const files = (await doReadDir(dir)).filter((n) => n.endsWith(".jsonl")).sort();
       if (files.length === 0) continue;
       let embeddedCwd = null;
       for (const file2 of files) {
-        embeddedCwd = extractCwdFromRaw(await doReadFile(join7(dir, file2)));
+        embeddedCwd = extractCwdFromRaw(await doReadFile(join8(dir, file2)));
         if (embeddedCwd) break;
       }
       const cwdExists = embeddedCwd ? await doPathExists(embeddedCwd) : false;
@@ -8264,7 +8620,7 @@ async function runSweep(input = {}, deps = {}) {
         try {
           outcome = await run(
             {
-              transcript_path: join7(dir, file2),
+              transcript_path: join8(dir, file2),
               cwd: cls.cwd ?? mainRoot,
               session_id: sid,
               hook_event_name: "SessionEnd"
@@ -8325,12 +8681,12 @@ async function runBackfill(input = {}, deps = {}) {
 }
 
 // src/installAgent.ts
-import { execFile } from "node:child_process";
+import { execFile as execFile2 } from "node:child_process";
 import { promisify } from "node:util";
-import { homedir as homedir4 } from "node:os";
-import { join as join8, dirname as dirname3 } from "node:path";
-import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir5, chmod as chmod5 } from "node:fs/promises";
-var execFileP = promisify(execFile);
+import { homedir as homedir5 } from "node:os";
+import { join as join9, dirname as dirname3 } from "node:path";
+import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5, chmod as chmod5 } from "node:fs/promises";
+var execFileP = promisify(execFile2);
 var MCP_COMMAND = "npx";
 var MCP_ARGS = ["-y", "backthread", "mcp"];
 function hookCommand(agent) {
@@ -8425,8 +8781,8 @@ async function writeJson(deps, path, obj) {
   await doWrite(path, JSON.stringify(obj, null, 2) + "\n");
 }
 async function installGemini(home, deps) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
-  const path = join8(home, ".gemini", "settings.json");
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
+  const path = join9(home, ".gemini", "settings.json");
   const current = await loadJsonObject(doRead, path);
   const a = withMcpServer(current);
   const b = withNestedHook(a.next, "SessionEnd", hookCommand("gemini-cli"), { name: "backthread-capture" }, [
@@ -8436,9 +8792,9 @@ async function installGemini(home, deps) {
   return [{ path, wrote: a.changed || b.changed }];
 }
 async function installCodex(home, deps) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
   const writes = [];
-  const tomlPath = join8(home, ".codex", "config.toml");
+  const tomlPath = join9(home, ".codex", "config.toml");
   let toml = "";
   try {
     toml = await doRead(tomlPath);
@@ -8459,7 +8815,7 @@ args = [${MCP_ARGS.map((a) => `"${a}"`).join(", ")}]
     await doWrite(tomlPath, toml + sep + block);
     writes.push({ path: tomlPath, wrote: true });
   }
-  const hooksPath = join8(home, ".codex", "hooks.json");
+  const hooksPath = join9(home, ".codex", "hooks.json");
   const current = await loadJsonObject(doRead, hooksPath);
   const h = withNestedHook(current, "Stop", hookCommand("codex"), { timeout: 60 }, [legacyHookCommand("codex")]);
   if (h.changed) await writeJson(deps, hooksPath, h.next);
@@ -8467,12 +8823,12 @@ args = [${MCP_ARGS.map((a) => `"${a}"`).join(", ")}]
   return writes;
 }
 async function installCursor(home, deps) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
   const nodeBinDir = deps.nodeBinDir ?? dirname3(process.execPath);
   const writes = [];
-  const scriptDir = join8(home, ".cursor", "hooks");
-  const captureScriptPath = join8(scriptDir, "backthread-capture.sh");
-  const mcpScriptPath = join8(scriptDir, "backthread-mcp.sh");
+  const scriptDir = join9(home, ".cursor", "hooks");
+  const captureScriptPath = join9(scriptDir, "backthread-capture.sh");
+  const mcpScriptPath = join9(scriptDir, "backthread-mcp.sh");
   writes.push(
     await writeCursorScript(
       deps,
@@ -8482,12 +8838,12 @@ async function installCursor(home, deps) {
     )
   );
   writes.push(await writeCursorScript(deps, mcpScriptPath, cursorWrapperScript(nodeBinDir, "mcp")));
-  const mcpPath = join8(home, ".cursor", "mcp.json");
+  const mcpPath = join9(home, ".cursor", "mcp.json");
   const mcpCurrent = await loadJsonObject(doRead, mcpPath);
   const m = withCursorMcpServer(mcpCurrent, mcpScriptPath);
   if (m.changed) await writeJson(deps, mcpPath, m.next);
   writes.push({ path: mcpPath, wrote: m.changed });
-  const hooksPath = join8(home, ".cursor", "hooks.json");
+  const hooksPath = join9(home, ".cursor", "hooks.json");
   const hooksCurrent = await loadJsonObject(doRead, hooksPath);
   const c = withCursorStopHook(hooksCurrent, captureScriptPath);
   if (c.changed) await writeJson(deps, hooksPath, c.next);
@@ -8521,7 +8877,7 @@ function cursorWrapperScript(nodeBinDir, backthreadArgs, latest = false) {
   ].join("\n") + "\n";
 }
 async function writeCursorScript(deps, path, content) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
   const doChmod = deps.chmodImpl ?? ((p, mode) => chmod5(p, mode));
   let existing = null;
   try {
@@ -8595,7 +8951,7 @@ async function versionGate(agent, deps) {
   return null;
 }
 async function runInstallAgent(agent, deps = {}) {
-  const home = deps.home ?? homedir4();
+  const home = deps.home ?? homedir5();
   const versionWarning = await versionGate(agent, deps);
   let writes;
   switch (agent) {
@@ -8637,12 +8993,12 @@ var LEGACY_HOOK_COMMANDS = [
 ];
 var OUR_HOOK_COMMANDS = /* @__PURE__ */ new Set([HOOK_COMMAND, ...LEGACY_HOOK_COMMANDS]);
 async function registerHook(deps = {}) {
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile8(p, "utf8"));
   const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile6(p, d));
   const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir6(d, { recursive: true }));
-  const home = deps.home ?? homedir5();
-  const settingsDir = join9(home, ".claude");
-  const settingsPath = join9(settingsDir, "settings.json");
+  const home = deps.home ?? homedir6();
+  const settingsDir = join10(home, ".claude");
+  const settingsPath = join10(settingsDir, "settings.json");
   let settings = {};
   let raw = null;
   try {
@@ -8754,9 +9110,9 @@ function stripSessionEndHook(settings) {
   return next;
 }
 async function unregisterProjectHook(cwd, deps = {}) {
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile8(p, "utf8"));
   const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile6(p, d));
-  const settingsPath = join9(cwd, ".claude", "settings.json");
+  const settingsPath = join10(cwd, ".claude", "settings.json");
   let raw;
   try {
     raw = await doReadFile(settingsPath);
@@ -9021,7 +9377,7 @@ function normalizeState(raw) {
 
 // src/firstRun.ts
 function firstRunStatePath(env = process.env) {
-  return join10(configDir(env), "first-run.json");
+  return join11(configDir(env), "first-run.json");
 }
 function parseFirstRunState(raw) {
   try {
@@ -9040,7 +9396,7 @@ function parseFirstRunState(raw) {
 }
 async function readFirstRunState(env = process.env) {
   try {
-    return parseFirstRunState(await readFile8(firstRunStatePath(env), "utf8"));
+    return parseFirstRunState(await readFile9(firstRunStatePath(env), "utf8"));
   } catch {
     return {};
   }
@@ -9215,7 +9571,7 @@ function readStream(stream) {
 async function runCapture(input, deps = {}) {
   const env = deps.env ?? process.env;
   const log = deps.log ?? ((m) => console.error(m));
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile9(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile10(p, "utf8"));
   const doReadConfig = deps.readConfigImpl ?? readConfig;
   const fireEnsureAuth = deps.ensureAuthImpl ?? ((e) => {
     void ensureAuth({ env: e }).catch(() => {
@@ -9395,8 +9751,8 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
 
 // src/fromHook.ts
 import { spawn as spawn2 } from "node:child_process";
-import { join as join11 } from "node:path";
-import { readFile as readFile10, writeFile as writeFile8, mkdir as mkdir8, chmod as chmod7 } from "node:fs/promises";
+import { join as join12 } from "node:path";
+import { readFile as readFile11, writeFile as writeFile8, mkdir as mkdir8, chmod as chmod7 } from "node:fs/promises";
 var KNOWN_AGENTS = /* @__PURE__ */ new Set([
   "claude-code",
   "codex",
@@ -9437,7 +9793,7 @@ function normalizeHookInput(payload, _agent) {
   return out;
 }
 function captureStatePath(env = process.env) {
-  return join11(configDir(env), "capture-sessions.json");
+  return join12(configDir(env), "capture-sessions.json");
 }
 var MAX_REMEMBERED2 = 200;
 function parseState3(raw) {
@@ -9460,7 +9816,7 @@ function parseState3(raw) {
 }
 async function readState3(env) {
   try {
-    return parseState3(await readFile10(captureStatePath(env), "utf8"));
+    return parseState3(await readFile11(captureStatePath(env), "utf8"));
   } catch {
     return { captured: [], watermarks: {} };
   }
@@ -9633,6 +9989,45 @@ function codexStdout(agent, status, outcome) {
   return ack;
 }
 
+// src/suggest.ts
+var MAX_DISTANCE = 2;
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+function preferable(candidate, incumbent) {
+  if (candidate.length !== incumbent.length) return candidate.length < incumbent.length;
+  return candidate < incumbent;
+}
+function nearestCommand(input, commands) {
+  const needle = input.toLowerCase();
+  if (needle.length === 0) return null;
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of commands) {
+    const d = editDistance(needle, cmd.toLowerCase());
+    if (d > MAX_DISTANCE || d >= needle.length) continue;
+    if (d < bestDist || d === bestDist && best !== null && preferable(cmd, best)) {
+      best = cmd;
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
 // ../node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -33921,15 +34316,15 @@ async function startMcpServer(deps = {}) {
 }
 
 // src/routingStats.ts
-import { join as join12 } from "node:path";
-import { readFile as readFile11, writeFile as writeFile9, mkdir as mkdir9, chmod as chmod8 } from "node:fs/promises";
+import { join as join13 } from "node:path";
+import { readFile as readFile12, writeFile as writeFile9, mkdir as mkdir9, chmod as chmod8 } from "node:fs/promises";
 var STATS_FILE = "routing-stats.json";
 function statsPath(env) {
-  return join12(configDir(env), STATS_FILE);
+  return join13(configDir(env), STATS_FILE);
 }
 async function readRoutingStats(deps = {}) {
   const env = deps.env ?? process.env;
-  const read = deps.readFileImpl ?? readFile11;
+  const read = deps.readFileImpl ?? readFile12;
   try {
     const raw = await read(statsPath(env), "utf8");
     const obj = JSON.parse(raw);
@@ -34002,40 +34397,60 @@ async function runSessionStart(deps = {}) {
 }
 
 // src/bin/backthread.ts
-var USAGE = `backthread \u2014 capture the "why" of your AI-coded changes
+var USAGE = `backthread \u2014 keep the thread on what your AI agent actually shipped
 
 Usage:
-  backthread                    Set up Backthread (the unified front door \u2014 same as
-                          \`backthread start\`): trust copy + one-tap auth + your next
-                          step. Idempotent. [--claim <code>]
-  backthread start              First-run setup (backs the /backthread:start slash command):
-                          trust copy + one-tap auth + your next step. Idempotent.
+  backthread [command] [flags]
+
+Setup
+  backthread                    Set up Backthread here (the front door): sign in, connect
+                          this repo, wire up capture. Idempotent \u2014 re-run it anytime.
                           [--claim <code>]
-  backthread login              Authorize this device (opens your browser)
-  backthread login --claim <code>
-                          Authorize with a single-use claim code from the web app
-                          (no browser needed \u2014 codes expire in ~10 minutes)
-  backthread login --device     Headless / SSH login (device-code flow \u2014 coming soon)
-  backthread whoami             Show the current device's config (token is never printed)
-  backthread how <question>     Ask how/why something in this repo works \u2014 prints a
-                          grounded, cited answer from your Backthread decision log
-                          (backs the /backthread:how slash command). [--cwd <path>]
+  backthread start              Same as above, behind the /backthread:start slash command.
+  backthread login              Authorize this device (opens your browser; works over SSH \u2014
+                          the printed URL opens on any device) [--claim <code>] [--device]
+  backthread logout             Sign this device out \u2014 drop the local token, keep the repo link
+  backthread whoami             Show this device's config (the token is never printed)
+
+Ask
+  backthread how <question>     Ask how/why something here works \u2014 a grounded, cited answer
+                          from your decision log (backs /backthread:how). [--cwd <path>]
+
+Capture
   backthread capture            Capture this session's decisions (run by the SessionEnd/Stop hook)
-  backthread capture --from-hook
-                          Shared multi-agent hook entrypoint: read the hook payload off
-                          STDIN and capture the named transcript (always exits 0)
-                          [--agent <codex|cursor|gemini-cli>] [--detach]
-  backthread capture --manual   Manually capture a session now (the /backthread capture slash command)
+  backthread capture --manual   Capture the current session now (the /backthread capture command)
                           [--session <id>] [--transcript <path>] [--cwd <dir>]
   backthread mcp                Start the MCP server (capture + query tools) over stdio
-  backthread install            Set up capture for this repo (login + hook + backfill history)
-                          [--claim <code>] [--skip-auth] [--skip-hook] [--skip-backfill]
-  backthread install --agent <codex|cursor|gemini>
-                          Set up capture for another agent: write its USER-GLOBAL
-                          MCP server config + session-end capture hook (idempotent)
-  backthread help               Show this message
 
-Docs: https://app.backthread.dev`;
+Manage
+  backthread install            Set up capture for this repo (login + hook + backfill history)
+                          [--claim <code>] [--agent <codex|cursor|gemini>] [--skip-auth]
+                          [--skip-hook] [--skip-backfill]
+  backthread update             Update a global install to the latest (also -u). npx is
+                          always latest already; the plugin updates via /plugin update.
+  backthread doctor             Diagnose your setup \u2014 auth, capture hook, connectivity,
+                          version, repo. Prints \u2713/\u2717 with fix hints; exits non-zero if broken.
+  backthread version            Print the installed version (also --version, -v)
+  backthread help               Show this message (also --help, -h)
+
+Your source never leaves your machine unredacted \u2014 it's checkable in this OSS repo.
+Docs:     https://app.backthread.dev
+Security: https://backthread.dev/security`;
+var KNOWN_COMMANDS = [
+  "start",
+  "login",
+  "logout",
+  "whoami",
+  "how",
+  "ask",
+  "capture",
+  "mcp",
+  "install",
+  "update",
+  "doctor",
+  "version",
+  "help"
+];
 function parseClaimFlag(rest) {
   const i = rest.indexOf("--claim");
   if (i === -1) return void 0;
@@ -34089,6 +34504,18 @@ async function main(argv, deps = {}) {
       console.log(lines.join("\n"));
       return cfg.device_token ? 0 : 1;
     }
+    case "logout": {
+      const logoutImpl = deps.runLogoutImpl ?? runLogout;
+      const result = await logoutImpl();
+      console.log(result.message);
+      return result.ok ? 0 : 1;
+    }
+    case "doctor": {
+      const doctorImpl = deps.runDoctorImpl ?? runDoctor;
+      const result = await doctorImpl();
+      console.log(result.text);
+      return result.exitCode;
+    }
     case "capture": {
       if (rest.includes("--from-hook")) {
         const raw = await readRawHookInput();
@@ -34165,6 +34592,19 @@ async function main(argv, deps = {}) {
     }
     case void 0:
       return onboarding(rest);
+    case "update":
+    case "--update":
+    case "-u": {
+      const updateImpl = deps.runUpdateImpl ?? runUpdate;
+      const result = await updateImpl();
+      console.log(result.message);
+      return result.ok ? 0 : 1;
+    }
+    case "version":
+    case "--version":
+    case "-v":
+      console.log(cliVersion());
+      return 0;
     case "help":
     case "--help":
     case "-h":
@@ -34172,9 +34612,14 @@ async function main(argv, deps = {}) {
       return 0;
     default:
       if (command.startsWith("-")) return onboarding(argv);
-      console.error(`Unknown command: ${command}
-
-${USAGE}`);
+      {
+        const guess = nearestCommand(command, KNOWN_COMMANDS);
+        const didYouMean = guess ? ` Did you mean \`backthread ${guess}\`?` : "";
+        console.error(
+          `Unknown command: ${command}.${didYouMean}
+Run \`backthread help\` to see everything backthread can do.`
+        );
+      }
       return 1;
   }
 }
@@ -34185,7 +34630,7 @@ function isEntryPoint() {
     const self = fileURLToPath2(import.meta.url);
     const resolve = (p) => {
       try {
-        return realpathSync(p);
+        return realpathSync2(p);
       } catch {
         return p;
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "backthread",
-  "version": "0.7.0",
-  "description": "Backthread helps you understand your codebase while AI ships features. The CLI captures the why behind every AI session and lets you ask how your codebase works, right from the terminal.",
+  "version": "0.8.0",
+  "description": "Backthread keeps the thread on what your AI coding agent ships — it captures the why behind every change and turns it into a living 'How it works' view of your codebase you can actually query.",
   "license": "MIT",
   "author": "Backthread",
   "homepage": "https://backthread.dev",
@@ -12,14 +12,20 @@
   },
   "bugs": "https://github.com/backthread/backthread/issues",
   "keywords": [
+    "backthread",
+    "ai-coding-agent",
     "claude-code",
-    "ai",
+    "cursor",
+    "codex",
+    "codebase-context",
+    "code-comprehension",
+    "how-it-works",
     "architecture",
-    "codebase",
-    "documentation",
-    "backthread",
+    "decision-log",
+    "ai",
+    "mcp",
     "cli",
-    "mcp"
+    "developer-tools"
   ],
   "type": "module",
   "comment": "PUBLISHED BIN = the self-contained esbuild bundle (dist-bundle/backthread.js), NOT the tsc dist/. Reason: @backthread/redact ships SOURCE-ONLY (.ts), and Node refuses to strip types for files inside node_modules — so a registry install of the tsc dist/ would fail to load redact at runtime. The bundle inlines redact (and the MCP SDK), so the published CLI has ZERO runtime dependencies and `npx backthread` stays fast and robust. Dev/test resolve @backthread/redact via the workspace symlink (realpath escapes node_modules → stripping applies).",