engramx 2.0.2 → 2.1.0

package/dist/cli.js

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
+import {
+  formatInstallDiff,
+  installEngramHooks,
+  uninstallEngramHooks
+} from "./chunk-SMU4WR3D.js";
 import {
   ESTIMATED_TOKENS_PER_READ_DENY,
-  formatHudStatus,
   formatStatsSummary,
-  getComponentStatus,
   summarizeHookLog
-} from "./chunk-533LR4I7.js";
+} from "./chunk-XFE6ZANP.js";
+import {
+  formatHudStatus,
+  getComponentStatus
+} from "./chunk-G4U3QOOW.js";
 import {
   readConfig
 } from "./chunk-22INHMKB.js";
@@ -18,11 +25,12 @@ import {
   install,
   status,
   uninstall
-} from "./chunk-C6GBUOAL.js";
+} from "./chunk-4XA6ENNL.js";
 import {
   benchmark,
   computeKeywordIDF,
   extractFile,
+  formatThousands,
   getDbPath,
   getFileContext,
   getStore,
@@ -35,7 +43,7 @@ import {
   renderFileStructure,
   stats,
   toPosixPath
-} from "./chunk-SJT7VS2G.js";
+} from "./chunk-ZVWRIVWQ.js";
 import "./chunk-PEH54LYC.js";
 
 // src/cli.ts
@@ -50,7 +58,7 @@ import {
   copyFileSync,
   renameSync as renameSync2
 } from "fs";
-import { dirname as dirname4, join as join9, resolve as pathResolve } from "path";
+import { dirname as dirname4, join as join9, resolve as pathResolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { homedir } from "os";
 
@@ -1434,7 +1442,7 @@ async function warmAllProviders(projectRoot, enabledProviders) {
       try {
         const result = await withTimeout2(p.warmup(projectRoot), 5e3);
         if (result && result.entries.length > 0) {
-          const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+          const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
           const store = await getStore2(projectRoot);
           try {
             store.warmCache(
@@ -1969,6 +1977,219 @@ ${result.text}`;
   return buildSessionContextResponse("UserPromptSubmit", text);
 }
 
+// src/intercept/handlers/bash-postool.ts
+import { isAbsolute as isAbsolute2, resolve as pathResolve } from "path";
+var MAX_COMMAND_LEN = 500;
+var BASIC_UNSAFE = /[|&;()$`*?[\]{}"']/;
+var SUBSHELL = /\$\(|`|<\(|>\(/;
+function parseFileOps(command, cwd) {
+  if (!command || typeof command !== "string") return [];
+  if (command.length > MAX_COMMAND_LEN) return [];
+  if (SUBSHELL.test(command)) return [];
+  const trimmed = command.trim();
+  if (!trimmed) return [];
+  const redirectMatch = /\s+(>>?)\s+(\S+)\s*$/.exec(trimmed);
+  if (redirectMatch) {
+    const head = trimmed.slice(0, redirectMatch.index);
+    const dest = redirectMatch[2];
+    if (BASIC_UNSAFE.test(head)) return [];
+    if (dest.startsWith("-") || dest.length === 0) return [];
+    return [{ action: "reindex", path: absolutize(dest, cwd) }];
+  }
+  if (BASIC_UNSAFE.test(trimmed)) return [];
+  const tokens = trimmed.split(/\s+/);
+  if (tokens.length === 0) return [];
+  const first = tokens[0];
+  if (first === "git" && tokens.length >= 3) {
+    const sub = tokens[1];
+    if (sub === "rm") return parseRm(tokens.slice(2), cwd);
+    if (sub === "mv") return parseMv(tokens.slice(2), cwd);
+    return [];
+  }
+  if (first === "rm") return parseRm(tokens.slice(1), cwd);
+  if (first === "mv") return parseMv(tokens.slice(1), cwd);
+  if (first === "cp") return parseCp(tokens.slice(1), cwd);
+  return [];
+}
+function absolutize(path2, cwd) {
+  if (isAbsolute2(path2)) return path2;
+  return pathResolve(cwd, path2);
+}
+function isFlagLike(tok) {
+  return tok.startsWith("-");
+}
+function parseRm(args, cwd) {
+  const paths = args.filter((t) => !isFlagLike(t));
+  if (paths.length === 0) return [];
+  return paths.map((p) => ({ action: "prune", path: absolutize(p, cwd) }));
+}
+function parseMv(args, cwd) {
+  const paths = args.filter((t) => !isFlagLike(t));
+  if (paths.length !== 2) return [];
+  const [src, dst] = paths;
+  return [
+    { action: "prune", path: absolutize(src, cwd) },
+    { action: "reindex", path: absolutize(dst, cwd) }
+  ];
+}
+function parseCp(args, cwd) {
+  const paths = args.filter((t) => !isFlagLike(t));
+  if (paths.length !== 2) return [];
+  const [, dst] = paths;
+  return [{ action: "reindex", path: absolutize(dst, cwd) }];
+}
+function handleBashPostTool(payload) {
+  if (payload.tool_name !== "Bash") return { ops: [] };
+  const cmd = payload.tool_input?.command;
+  if (!cmd || typeof cmd !== "string") return { ops: [] };
+  try {
+    const ops = parseFileOps(cmd, payload.cwd);
+    return { ops };
+  } catch {
+    return { ops: [] };
+  }
+}
+
+// src/watcher.ts
+import { watch, existsSync as existsSync6, statSync as statSync2 } from "fs";
+import { resolve as resolve3, relative as relative3, extname } from "path";
+var WATCHABLE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".c",
+  ".cpp",
+  ".cs",
+  ".rb"
+]);
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ".engram",
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "__pycache__",
+  ".venv",
+  "target",
+  "vendor"
+]);
+var DEBOUNCE_MS = 300;
+function shouldIgnore(relPath) {
+  const parts = relPath.split(/[/\\]/);
+  return parts.some((p) => IGNORED_DIRS.has(p));
+}
+async function syncFile(absPath, projectRoot) {
+  const ext = extname(absPath).toLowerCase();
+  if (!WATCHABLE_EXTENSIONS.has(ext)) return { action: "skipped", count: 0 };
+  const relPath = toPosixPath(relative3(projectRoot, absPath));
+  if (shouldIgnore(relPath)) return { action: "skipped", count: 0 };
+  if (!existsSync6(absPath)) {
+    const store2 = await getStore(projectRoot);
+    try {
+      const prior = store2.countBySourceFile(relPath);
+      if (prior === 0) return { action: "skipped", count: 0 };
+      store2.deleteBySourceFile(relPath);
+      return { action: "pruned", count: prior };
+    } finally {
+      store2.close();
+    }
+  }
+  try {
+    if (statSync2(absPath).isDirectory()) return { action: "skipped", count: 0 };
+  } catch {
+    return { action: "skipped", count: 0 };
+  }
+  const store = await getStore(projectRoot);
+  try {
+    store.deleteBySourceFile(relPath);
+    const { nodes, edges } = extractFile(absPath, projectRoot);
+    if (nodes.length > 0 || edges.length > 0) {
+      store.bulkUpsert(nodes, edges);
+    }
+    return { action: "indexed", count: nodes.length };
+  } finally {
+    store.close();
+  }
+}
+function formatReindexLine(result, displayPath) {
+  if (result.action === "indexed") {
+    return `engram: reindexed ${displayPath} (${formatThousands(result.count)} nodes)`;
+  }
+  if (result.action === "pruned") {
+    return `engram: pruned ${displayPath} (${formatThousands(result.count)} nodes)`;
+  }
+  return null;
+}
+async function runReindexHook(payload) {
+  try {
+    if (payload === null || typeof payload !== "object") return;
+    const p = payload;
+    const cwd = p.cwd;
+    if (typeof cwd !== "string" || !isValidCwd(cwd)) return;
+    const toolInput = p.tool_input;
+    if (toolInput === null || typeof toolInput !== "object") return;
+    const filePath = toolInput.file_path;
+    if (typeof filePath !== "string" || filePath.length === 0) return;
+    const absPath = resolve3(cwd, filePath);
+    const projectRoot = findProjectRoot(absPath);
+    if (projectRoot === null) return;
+    await syncFile(absPath, projectRoot);
+  } catch {
+  }
+}
+function watchProject(projectRoot, options = {}) {
+  const root = resolve3(projectRoot);
+  const controller = new AbortController();
+  if (!existsSync6(getDbPath(root))) {
+    throw new Error(
+      `engram: no graph found at ${root}. Run 'engram init' first.`
+    );
+  }
+  const debounceTimers = /* @__PURE__ */ new Map();
+  const watcher = watch(root, { recursive: true, signal: controller.signal });
+  const handleEvent = (_eventType, filename) => {
+    if (typeof filename !== "string") return;
+    const absPath = resolve3(root, filename);
+    const relPath = toPosixPath(relative3(root, absPath));
+    if (shouldIgnore(relPath)) return;
+    const ext = extname(filename).toLowerCase();
+    if (!WATCHABLE_EXTENSIONS.has(ext)) return;
+    const existing = debounceTimers.get(absPath);
+    if (existing) clearTimeout(existing);
+    debounceTimers.set(
+      absPath,
+      setTimeout(async () => {
+        debounceTimers.delete(absPath);
+        try {
+          const result = await syncFile(absPath, root);
+          if (result.action === "indexed" && result.count > 0) {
+            options.onReindex?.(relPath, result.count);
+          } else if (result.action === "pruned") {
+            options.onDelete?.(relPath, result.count);
+          }
+        } catch (err) {
+          options.onError?.(
+            err instanceof Error ? err : new Error(String(err))
+          );
+        }
+      }, DEBOUNCE_MS)
+    );
+  };
+  watcher.on("change", handleEvent);
+  watcher.on("rename", handleEvent);
+  watcher.on("error", (err) => {
+    options.onError?.(err instanceof Error ? err : new Error(String(err)));
+  });
+  options.onReady?.();
+  return controller;
+}
+
 // src/intercept/handlers/post-tool.ts
 function extractFilePath(toolName, toolInput) {
   if (!toolInput) return void 0;
@@ -2019,13 +2240,34 @@ async function handlePostTool(payload) {
       outputSize,
       success: !hasError
     });
+    if (toolName === "Bash" && !hasError && process.env.ENGRAM_AUTO_REINDEX === "1") {
+      void reindexBashOps(payload, projectRoot).catch(() => {
+      });
+    }
   } catch {
   }
   return PASSTHROUGH;
 }
+async function reindexBashOps(payload, projectRoot) {
+  const result = handleBashPostTool({
+    tool_name: payload.tool_name ?? "",
+    tool_input: payload.tool_input ?? {},
+    cwd: payload.cwd
+  });
+  if (result.ops.length === 0) return;
+  for (const op of result.ops) {
+    await runOp(op, projectRoot);
+  }
+}
+async function runOp(op, projectRoot) {
+  try {
+    await syncFile(op.path, projectRoot);
+  } catch {
+  }
+}
 
 // src/intercept/handlers/pre-compact.ts
-import { basename as basename2, resolve as resolve3 } from "path";
+import { basename as basename2, resolve as resolve4 } from "path";
 var MAX_GOD_NODES_COMPACT = 5;
 var MAX_LANDMINES_COMPACT = 3;
 function formatCompactBrief(args) {
@@ -2075,7 +2317,7 @@ async function handlePreCompact(payload) {
       }))
     ]);
     if (graphStats.nodes === 0 && gods.length === 0) return PASSTHROUGH;
-    const projectName = basename2(resolve3(projectRoot));
+    const projectName = basename2(resolve4(projectRoot));
     const text = formatCompactBrief({
       projectName,
       nodeCount: graphStats.nodes,
@@ -2097,7 +2339,7 @@ async function handlePreCompact(payload) {
 }
 
 // src/intercept/handlers/cwd-changed.ts
-import { basename as basename3, resolve as resolve4 } from "path";
+import { basename as basename3, resolve as resolve5 } from "path";
 var MAX_GOD_NODES_SWITCH = 5;
 async function handleCwdChanged(payload) {
   if (payload.hook_event_name !== "CwdChanged") return PASSTHROUGH;
@@ -2121,7 +2363,7 @@ async function handleCwdChanged(payload) {
       }))
     ]);
     if (graphStats.nodes === 0) return PASSTHROUGH;
-    const projectName = basename3(resolve4(projectRoot));
+    const projectName = basename3(resolve5(projectRoot));
     const lines = [];
     lines.push(
       `[engram] Project switched to ${projectName} (${graphStats.nodes} nodes, ${graphStats.edges} edges)`
@@ -2238,106 +2480,6 @@ function extractPreToolDecision(result) {
   return "passthrough";
 }
 
-// src/watcher.ts
-import { watch, existsSync as existsSync6, statSync as statSync2 } from "fs";
-import { resolve as resolve5, relative as relative3, extname } from "path";
-var WATCHABLE_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".py",
-  ".go",
-  ".rs",
-  ".java",
-  ".c",
-  ".cpp",
-  ".cs",
-  ".rb"
-]);
-var IGNORED_DIRS = /* @__PURE__ */ new Set([
-  ".engram",
-  "node_modules",
-  ".git",
-  "dist",
-  "build",
-  ".next",
-  "__pycache__",
-  ".venv",
-  "target",
-  "vendor"
-]);
-var DEBOUNCE_MS = 300;
-function shouldIgnore(relPath) {
-  const parts = relPath.split(/[/\\]/);
-  return parts.some((p) => IGNORED_DIRS.has(p));
-}
-async function reindexFile(absPath, projectRoot) {
-  const ext = extname(absPath).toLowerCase();
-  if (!WATCHABLE_EXTENSIONS.has(ext)) return 0;
-  if (!existsSync6(absPath)) return 0;
-  try {
-    if (statSync2(absPath).isDirectory()) return 0;
-  } catch {
-    return 0;
-  }
-  const relPath = toPosixPath(relative3(projectRoot, absPath));
-  if (shouldIgnore(relPath)) return 0;
-  const store = await getStore(projectRoot);
-  try {
-    store.deleteBySourceFile(relPath);
-    const { nodes, edges } = extractFile(absPath, projectRoot);
-    if (nodes.length > 0 || edges.length > 0) {
-      store.bulkUpsert(nodes, edges);
-    }
-    return nodes.length;
-  } finally {
-    store.close();
-  }
-}
-function watchProject(projectRoot, options = {}) {
-  const root = resolve5(projectRoot);
-  const controller = new AbortController();
-  if (!existsSync6(getDbPath(root))) {
-    throw new Error(
-      `engram: no graph found at ${root}. Run 'engram init' first.`
-    );
-  }
-  const debounceTimers = /* @__PURE__ */ new Map();
-  const watcher = watch(root, { recursive: true, signal: controller.signal });
-  watcher.on("change", (_eventType, filename) => {
-    if (typeof filename !== "string") return;
-    const absPath = resolve5(root, filename);
-    const relPath = toPosixPath(relative3(root, absPath));
-    if (shouldIgnore(relPath)) return;
-    const ext = extname(filename).toLowerCase();
-    if (!WATCHABLE_EXTENSIONS.has(ext)) return;
-    const existing = debounceTimers.get(absPath);
-    if (existing) clearTimeout(existing);
-    debounceTimers.set(
-      absPath,
-      setTimeout(async () => {
-        debounceTimers.delete(absPath);
-        try {
-          const count = await reindexFile(absPath, root);
-          if (count > 0) {
-            options.onReindex?.(relPath, count);
-          }
-        } catch (err) {
-          options.onError?.(
-            err instanceof Error ? err : new Error(String(err))
-          );
-        }
-      }, DEBOUNCE_MS)
-    );
-  });
-  watcher.on("error", (err) => {
-    options.onError?.(err instanceof Error ? err : new Error(String(err)));
-  });
-  options.onReady?.();
-  return controller;
-}
-
 // src/dashboard.ts
 import chalk from "chalk";
 import { existsSync as existsSync7, statSync as statSync3 } from "fs";
@@ -2353,9 +2495,7 @@ function bar(pct, width = 20) {
   const empty = width - filled;
   return AMBER("\u2588".repeat(filled)) + DIM("\u2591".repeat(empty));
 }
-function fmt(n) {
-  return n.toLocaleString();
-}
+var fmt = formatThousands;
 function topFiles(entries, n) {
   const counts = /* @__PURE__ */ new Map();
   for (const e of entries) {
@@ -2522,156 +2662,6 @@ async function handleCursorBeforeReadFile(payload) {
   }
 }
 
-// src/intercept/installer.ts
-var ENGRAM_HOOK_EVENTS = [
-  "PreToolUse",
-  "PostToolUse",
-  "SessionStart",
-  "UserPromptSubmit",
-  "PreCompact",
-  "CwdChanged"
-];
-var ENGRAM_PRETOOL_MATCHER = "Read|Edit|Write|Bash";
-var DEFAULT_ENGRAM_COMMAND = "engram intercept";
-var DEFAULT_HOOK_TIMEOUT_SEC = 5;
-var DEFAULT_STATUSLINE_COMMAND = "engram hud-label";
-function buildEngramHookEntries(command = DEFAULT_ENGRAM_COMMAND, timeout = DEFAULT_HOOK_TIMEOUT_SEC) {
-  const baseCmd = {
-    type: "command",
-    command,
-    timeout
-  };
-  return {
-    PreToolUse: {
-      matcher: ENGRAM_PRETOOL_MATCHER,
-      hooks: [baseCmd]
-    },
-    PostToolUse: {
-      // Match all tools — PostToolUse is an observer for any completion.
-      matcher: ".*",
-      hooks: [baseCmd]
-    },
-    SessionStart: {
-      // No matcher — SessionStart has no tool name.
-      hooks: [baseCmd]
-    },
-    UserPromptSubmit: {
-      // No matcher — UserPromptSubmit has no tool name.
-      hooks: [baseCmd]
-    },
-    PreCompact: {
-      // No matcher — PreCompact has no tool name.
-      hooks: [baseCmd]
-    },
-    CwdChanged: {
-      // No matcher — CwdChanged has no tool name.
-      hooks: [baseCmd]
-    }
-  };
-}
-function isEngramHookEntry(entry) {
-  if (entry === null || typeof entry !== "object") return false;
-  const e = entry;
-  if (!Array.isArray(e.hooks)) return false;
-  for (const h of e.hooks) {
-    if (h === null || typeof h !== "object") continue;
-    const cmd = h.command;
-    if (typeof cmd === "string" && cmd.includes("engram intercept")) {
-      return true;
-    }
-  }
-  return false;
-}
-function installEngramHooks(settings, command = DEFAULT_ENGRAM_COMMAND) {
-  const entries = buildEngramHookEntries(command);
-  const added = [];
-  const alreadyPresent = [];
-  const hooksClone = {};
-  const existingHooks = settings.hooks ?? {};
-  for (const [key, value] of Object.entries(existingHooks)) {
-    if (Array.isArray(value)) {
-      hooksClone[key] = value.map((entry) => ({ ...entry }));
-    }
-  }
-  for (const event of ENGRAM_HOOK_EVENTS) {
-    const eventArr = hooksClone[event] ?? [];
-    const hasEngram = eventArr.some((e) => isEngramHookEntry(e));
-    if (hasEngram) {
-      alreadyPresent.push(event);
-      hooksClone[event] = eventArr;
-      continue;
-    }
-    hooksClone[event] = [...eventArr, entries[event]];
-    added.push(event);
-  }
-  const hasStatusLine = settings.statusLine && typeof settings.statusLine === "object" && typeof settings.statusLine.command === "string" && settings.statusLine.command.length > 0;
-  const statusLineAdded = !hasStatusLine;
-  const statusLine = hasStatusLine ? settings.statusLine : { type: "command", command: DEFAULT_STATUSLINE_COMMAND };
-  return {
-    updated: { ...settings, hooks: hooksClone, statusLine },
-    added,
-    alreadyPresent,
-    statusLineAdded
-  };
-}
-function uninstallEngramHooks(settings) {
-  const removed = [];
-  const existingHooks = settings.hooks ?? {};
-  const hooksClone = {};
-  for (const [event, arr] of Object.entries(existingHooks)) {
-    if (!Array.isArray(arr)) continue;
-    const filtered = arr.filter((entry) => !isEngramHookEntry(entry));
-    if (filtered.length !== arr.length && isKnownEngramEvent(event)) {
-      removed.push(event);
-    }
-    if (filtered.length > 0) {
-      hooksClone[event] = filtered;
-    }
-  }
-  const updatedSettings = { ...settings };
-  if (Object.keys(hooksClone).length === 0) {
-    delete updatedSettings.hooks;
-  } else {
-    updatedSettings.hooks = hooksClone;
-  }
-  const statusLineRemoved = typeof updatedSettings.statusLine?.command === "string" && updatedSettings.statusLine.command.includes("engram hud-label");
-  if (statusLineRemoved) {
-    delete updatedSettings.statusLine;
-  }
-  return { updated: updatedSettings, removed, statusLineRemoved };
-}
-function isKnownEngramEvent(event) {
-  return ENGRAM_HOOK_EVENTS.includes(event);
-}
-function formatInstallDiff(before, after) {
-  const lines = [];
-  const beforeHooks = before.hooks ?? {};
-  const afterHooks = after.hooks ?? {};
-  for (const event of ENGRAM_HOOK_EVENTS) {
-    const beforeArr = beforeHooks[event] ?? [];
-    const afterArr = afterHooks[event] ?? [];
-    if (beforeArr.length === afterArr.length) continue;
-    lines.push(`+ ${event}: ${beforeArr.length} \u2192 ${afterArr.length} entries`);
-    const added = afterArr.filter((entry) => isEngramHookEntry(entry));
-    const beforeHasEngram = beforeArr.some((entry) => isEngramHookEntry(entry));
-    if (!beforeHasEngram && added.length > 0) {
-      for (const entry of added) {
-        const matcher = entry.matcher ? ` matcher=${JSON.stringify(entry.matcher)}` : "";
-        const cmds = entry.hooks.map((h) => h.command).join(", ");
-        lines.push(`    + {${matcher} command="${cmds}"}`);
-      }
-    }
-  }
-  const hadStatusLine = before.statusLine?.command;
-  const hasStatusLineNow = after.statusLine?.command;
-  if (!hadStatusLine && hasStatusLineNow?.includes("engram hud-label")) {
-    lines.push(`+ statusLine: engram hud-label (HUD enabled)`);
-  } else if (hadStatusLine?.includes("engram hud-label") && !hasStatusLineNow) {
-    lines.push(`- statusLine: engram hud-label (HUD removed)`);
-  }
-  return lines.length > 0 ? lines.join("\n") : "(no changes)";
-}
-
 // src/intercept/memory-md.ts
 import {
   existsSync as existsSync8,
@@ -2786,6 +2776,9 @@ program.command("init").description("Scan codebase and build knowledge graph (ze
 ).option("--from-ccs", "Import .context/index.md (CCS) into graph after init").option(
   "--incremental",
   "Skip unchanged files (mtime-based). Dramatically faster on re-index of large repos."
+).option(
+  "--with-hook",
+  "Also install the Sentinel hook into Claude Code settings.local.json (idempotent)"
 ).action(async (projectPath, opts) => {
   console.log(chalk2.dim(opts.incremental ? "\u{1F50D} Scanning changed files..." : "\u{1F50D} Scanning codebase..."));
   const result = await init(projectPath, {
@@ -2796,7 +2789,7 @@ program.command("init").description("Scan codebase and build knowledge graph (ze
     chalk2.green("\u{1F333} AST extraction complete") + chalk2.dim(` (${result.timeMs}ms, 0 tokens used)`)
   );
   console.log(
-    `   ${chalk2.bold(String(result.nodes))} nodes, ${chalk2.bold(String(result.edges))} edges from ${chalk2.bold(String(result.fileCount))} files (${result.totalLines.toLocaleString()} lines)`
+    `   ${chalk2.bold(String(result.nodes))} nodes, ${chalk2.bold(String(result.edges))} edges from ${chalk2.bold(String(result.fileCount))} files (${formatThousands(result.totalLines)} lines)`
   );
   if (result.incremental && result.skippedFiles && result.skippedFiles > 0) {
     console.log(chalk2.dim(`   ${result.skippedFiles} unchanged files skipped (incremental mode)`));
@@ -2813,12 +2806,12 @@ program.command("init").description("Scan codebase and build knowledge graph (ze
 \u{1F4CA} Token savings: ${chalk2.bold(bench.reductionVsRelevant + "x")} fewer tokens vs relevant files (${bench.reductionVsFull}x vs full corpus)`)
     );
     console.log(
-      chalk2.dim(`   Full corpus: ~${bench.naiveFullCorpus.toLocaleString()} tokens | Graph query: ~${bench.avgQueryTokens.toLocaleString()} tokens`)
+      chalk2.dim(`   Full corpus: ~${formatThousands(bench.naiveFullCorpus)} tokens | Graph query: ~${formatThousands(bench.avgQueryTokens)} tokens`)
     );
   }
   console.log(chalk2.green("\n\u2705 Ready. Your AI now has persistent memory."));
   console.log(chalk2.dim("   Graph stored in .engram/graph.db"));
-  const resolvedProject = pathResolve(projectPath);
+  const resolvedProject = pathResolve2(projectPath);
   const localSettings = join9(resolvedProject, ".claude", "settings.local.json");
   const projectSettings = join9(resolvedProject, ".claude", "settings.json");
   const hasHooks = existsSync9(localSettings) && readFileSync5(localSettings, "utf-8").includes("engram intercept") || existsSync9(projectSettings) && readFileSync5(projectSettings, "utf-8").includes("engram intercept");
@@ -2834,9 +2827,59 @@ program.command("init").description("Scan codebase and build knowledge graph (ze
       )
     );
   }
+  if (opts.withHook) {
+    const localSettingsPath = join9(
+      pathResolve2(projectPath),
+      ".claude",
+      "settings.local.json"
+    );
+    let settings = {};
+    if (existsSync9(localSettingsPath)) {
+      try {
+        const raw = readFileSync5(localSettingsPath, "utf-8");
+        settings = raw.trim() ? JSON.parse(raw) : {};
+      } catch {
+        console.log(
+          chalk2.yellow(
+            "\n   \u26A0 --with-hook: settings.local.json is invalid JSON, skipping hook install."
+          )
+        );
+        settings = {};
+      }
+    }
+    const hookResult = installEngramHooks(settings);
+    if (hookResult.added.length > 0 || hookResult.statusLineAdded) {
+      try {
+        mkdirSync(dirname4(localSettingsPath), { recursive: true });
+        writeFileSync2(
+          localSettingsPath,
+          JSON.stringify(hookResult.updated, null, 2) + "\n"
+        );
+        console.log(
+          chalk2.green(
+            `
+   \u2705 --with-hook: installed ${hookResult.added.length} hook event${hookResult.added.length === 1 ? "" : "s"} into .claude/settings.local.json`
+          )
+        );
+      } catch (err) {
+        console.log(
+          chalk2.yellow(
+            `
+   \u26A0 --with-hook: write failed (${err.message})`
+          )
+        );
+      }
+    } else {
+      console.log(
+        chalk2.dim(
+          "\n   --with-hook: Sentinel hook already installed, nothing to do."
+        )
+      );
+    }
+  }
   if (opts.fromCcs) {
-    const { importCcs } = await import("./importer-V62NGZRK.js");
-    const resolvedProjectPath = pathResolve(projectPath);
+    const { importCcs } = await import("./importer-3Q5M6QBL.js");
+    const resolvedProjectPath = pathResolve2(projectPath);
     const ccsResult = await importCcs(resolvedProjectPath);
     if (ccsResult.nodesCreated > 0) {
       console.log(
@@ -2850,7 +2893,7 @@ program.command("init").description("Scan codebase and build knowledge graph (ze
   }
 });
 program.command("watch").description("Watch project for file changes and re-index incrementally").argument("[path]", "Project directory", ".").action(async (projectPath) => {
-  const resolvedPath = pathResolve(projectPath);
+  const resolvedPath = pathResolve2(projectPath);
   console.log(
     chalk2.dim("\u{1F441}  Watching ") + chalk2.white(resolvedPath) + chalk2.dim(" for changes...")
   );
@@ -2860,6 +2903,11 @@ program.command("watch").description("Watch project for file changes and re-inde
         chalk2.green("  \u21BB ") + chalk2.white(filePath) + chalk2.dim(` (${nodeCount} nodes)`)
       );
     },
+    onDelete: (filePath, prunedCount) => {
+      console.log(
+        chalk2.yellow("  \xD7 ") + chalk2.white(filePath) + chalk2.dim(` pruned (${prunedCount} nodes)`)
+      );
+    },
     onError: (err) => {
       console.error(chalk2.red("  \u2717 ") + err.message);
     },
@@ -2875,8 +2923,68 @@ program.command("watch").description("Watch project for file changes and re-inde
   await new Promise(() => {
   });
 });
+program.command("reindex").description("Re-index a single file into the knowledge graph").argument("<file>", "File path (absolute or relative to --project)").option("-p, --project <path>", "Project directory", ".").option("--verbose", "Print stack traces on error", false).action(
+  async (file, opts) => {
+    const root = pathResolve2(opts.project);
+    if (!existsSync9(join9(root, ".engram", "graph.db"))) {
+      console.error(
+        `engram: no graph found at ${root}. Run 'engram init' first.`
+      );
+      process.exit(1);
+    }
+    const absFile = pathResolve2(root, file);
+    try {
+      const result = await syncFile(absFile, root);
+      const line = formatReindexLine(result, file);
+      if (line !== null) console.log(line);
+      process.exitCode = 0;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`engram: ${msg}`);
+      if (opts.verbose && err instanceof Error && err.stack) {
+        console.error(err.stack);
+      }
+      process.exit(1);
+    }
+  }
+);
+program.command("reindex-hook").description(
+  "PostToolUse hook entry point: reads JSON from stdin, reindexes tool_input.file_path (always exits 0)"
+).action(async () => {
+  const stdinTimeout = setTimeout(() => {
+    process.exit(0);
+  }, 3e3);
+  stdinTimeout.unref();
+  let input = "";
+  let stdinFailed = false;
+  try {
+    for await (const chunk of process.stdin) {
+      input += chunk;
+      if (input.length > 1e6) break;
+    }
+  } catch {
+    stdinFailed = true;
+  }
+  clearTimeout(stdinTimeout);
+  if (stdinFailed || !input.trim()) {
+    process.exitCode = 0;
+    return;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    process.exitCode = 0;
+    return;
+  }
+  try {
+    await runReindexHook(payload);
+  } catch {
+  }
+  process.exitCode = 0;
+});
 program.command("dashboard").alias("hud").description("Live terminal dashboard showing hook activity and token savings").argument("[path]", "Project directory", ".").action(async (projectPath) => {
-  const resolvedPath = pathResolve(projectPath);
+  const resolvedPath = pathResolve2(projectPath);
   const dbPath = join9(resolvedPath, ".engram", "graph.db");
   if (!existsSync9(dbPath)) {
     console.error(
@@ -2895,7 +3003,7 @@ program.command("dashboard").alias("hud").description("Live terminal dashboard s
   });
 });
 program.command("hud-label").description("Output JSON label for Claude HUD --extra-cmd (fast, <20ms)").argument("[path]", "Project directory", ".").action(async (projectPath) => {
-  let resolvedPath = pathResolve(projectPath);
+  let resolvedPath = pathResolve2(projectPath);
   let found = false;
   for (let depth = 0; depth < 20; depth++) {
     if (existsSync9(join9(resolvedPath, ".engram", "graph.db"))) {
@@ -2991,8 +3099,8 @@ program.command("stats").description("Show knowledge graph statistics and token
   if (bench.naiveFullCorpus > 0) {
     console.log(`
   ${chalk2.cyan("Token savings:")}`);
-    console.log(`    Full corpus:   ~${bench.naiveFullCorpus.toLocaleString()} tokens`);
-    console.log(`    Avg query:     ~${bench.avgQueryTokens.toLocaleString()} tokens`);
+    console.log(`    Full corpus:   ~${formatThousands(bench.naiveFullCorpus)} tokens`);
+    console.log(`    Avg query:     ~${formatThousands(bench.avgQueryTokens)} tokens`);
     console.log(`    vs relevant:   ${chalk2.bold.cyan(bench.reductionVsRelevant + "x")} fewer tokens`);
     console.log(`    vs full:       ${chalk2.bold.cyan(bench.reductionVsFull + "x")} fewer tokens`);
   }
@@ -3036,8 +3144,8 @@ program.command("mistakes").description("List known mistakes extracted from past
 program.command("bench").description("Run token reduction benchmark").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
   const result = await benchmark(opts.project);
   console.log(chalk2.bold("\n\u26A1 engram token reduction benchmark\n"));
-  console.log(`  Full corpus:     ~${result.naiveFullCorpus.toLocaleString()} tokens`);
-  console.log(`  Avg graph query: ~${result.avgQueryTokens.toLocaleString()} tokens`);
+  console.log(`  Full corpus:     ~${formatThousands(result.naiveFullCorpus)} tokens`);
+  console.log(`  Avg graph query: ~${formatThousands(result.avgQueryTokens)} tokens`);
   console.log(`  vs relevant:     ${chalk2.bold.green(result.reductionVsRelevant + "x")} fewer tokens`);
   console.log(`  vs full corpus:  ${chalk2.bold.green(result.reductionVsFull + "x")} fewer tokens
 `);
@@ -3065,7 +3173,7 @@ program.command("gen").description("Generate CLAUDE.md / .cursorrules section fr
   }
 );
 program.command("gen-mdc").description("Generate .cursor/rules/engram-context.mdc from knowledge graph").option("-p, --project <path>", "Project directory", ".").option("--watch", "Regenerate on graph changes").action(async (opts) => {
-  const { generateCursorMdc } = await import("./cursor-mdc-GJ7E5LDD.js");
+  const { generateCursorMdc } = await import("./cursor-mdc-VEOFFDVO.js");
   const result = await generateCursorMdc(opts.project);
   console.log(
     chalk2.green(
@@ -3073,11 +3181,15 @@ program.command("gen-mdc").description("Generate .cursor/rules/engram-context.md
     )
   );
   if (opts.watch) {
-    watchProject(pathResolve(opts.project), {
+    watchProject(pathResolve2(opts.project), {
       onReindex: async () => {
         const r = await generateCursorMdc(opts.project);
         console.log(chalk2.dim(`  \u21BB Regenerated MDC (${r.nodes} nodes)`));
       },
+      onDelete: async () => {
+        const r = await generateCursorMdc(opts.project);
+        console.log(chalk2.dim(`  \xD7 Regenerated MDC (${r.nodes} nodes)`));
+      },
       onError: (err) => console.error(chalk2.red(err.message)),
       onReady: () => console.log(chalk2.dim("  Watching for changes..."))
     });
@@ -3086,8 +3198,8 @@ program.command("gen-mdc").description("Generate .cursor/rules/engram-context.md
   }
 });
 program.command("gen-ccs").description("Export knowledge graph as .context/index.md (CCS format)").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { exportCcs } = await import("./exporter-GWU2GF23.js");
-  const result = await exportCcs(pathResolve(opts.project));
+  const { exportCcs } = await import("./exporter-AWXS34AS.js");
+  const result = await exportCcs(pathResolve2(opts.project));
   console.log(
     chalk2.green(
       `\u2705 Generated ${result.filePath} (${result.sectionsWritten} sections, ${result.nodesExported} nodes)`
@@ -3095,19 +3207,23 @@ program.command("gen-ccs").description("Export knowledge graph as .context/index
   );
 });
 program.command("gen-aider").description("Generate .aider-context.md from knowledge graph").option("-p, --project <path>", "Project directory", ".").option("--watch", "Regenerate on graph changes").action(async (opts) => {
-  const { generateAiderContext } = await import("./aider-context-BC5R2ZTA.js");
-  const result = await generateAiderContext(pathResolve(opts.project));
+  const { generateAiderContext } = await import("./aider-context-J557IHIP.js");
+  const result = await generateAiderContext(pathResolve2(opts.project));
   console.log(
     chalk2.green(
       `\u2705 Generated ${result.filePath} (${result.sections} sections, ${result.nodes} nodes)`
     )
   );
   if (opts.watch) {
-    watchProject(pathResolve(opts.project), {
+    watchProject(pathResolve2(opts.project), {
       onReindex: async () => {
         const r = await generateAiderContext(opts.project);
         console.log(chalk2.dim(`  \u21BB Regenerated .aider-context.md (${r.nodes} nodes)`));
       },
+      onDelete: async () => {
+        const r = await generateAiderContext(opts.project);
+        console.log(chalk2.dim(`  \xD7 Regenerated .aider-context.md (${r.nodes} nodes)`));
+      },
       onError: (err) => console.error(chalk2.red(err.message)),
       onReady: () => console.log(chalk2.dim("  Watching for changes..."))
     });
@@ -3116,19 +3232,23 @@ program.command("gen-aider").description("Generate .aider-context.md from knowle
   }
 });
 program.command("gen-windsurfrules").description("Generate .windsurfrules from knowledge graph (Windsurf IDE)").option("-p, --project <path>", "Project directory", ".").option("--watch", "Regenerate on graph changes").action(async (opts) => {
-  const { generateWindsurfRules } = await import("./windsurf-rules-C7SVDHBL.js");
-  const result = await generateWindsurfRules(pathResolve(opts.project));
+  const { generateWindsurfRules } = await import("./windsurf-rules-RWPKBHRD.js");
+  const result = await generateWindsurfRules(pathResolve2(opts.project));
   console.log(
     chalk2.green(
       `\u2705 Generated ${result.filePath} (${result.sections} sections, ${result.nodes} nodes)`
     )
   );
   if (opts.watch) {
-    watchProject(pathResolve(opts.project), {
+    watchProject(pathResolve2(opts.project), {
       onReindex: async () => {
         const r = await generateWindsurfRules(opts.project);
         console.log(chalk2.dim(`  \u21BB Regenerated .windsurfrules (${r.nodes} nodes)`));
       },
+      onDelete: async () => {
+        const r = await generateWindsurfRules(opts.project);
+        console.log(chalk2.dim(`  \xD7 Regenerated .windsurfrules (${r.nodes} nodes)`));
+      },
       onError: (err) => console.error(chalk2.red(err.message)),
       onReady: () => console.log(chalk2.dim("  Watching for changes..."))
     });
@@ -3137,7 +3257,7 @@ program.command("gen-windsurfrules").description("Generate .windsurfrules from k
   }
 });
 function resolveSettingsPath(scope, projectPath) {
-  const absProject = pathResolve(projectPath);
+  const absProject = pathResolve2(projectPath);
   switch (scope) {
     case "local":
       return join9(absProject, ".claude", "settings.local.json");
@@ -3226,7 +3346,11 @@ program.command("cursor-intercept").description(
   }
   process.exit(0);
 });
-program.command("install-hook").description("Install engram hook entries into Claude Code settings").option("--scope <scope>", "local | project | user", "local").option("--dry-run", "Show diff without writing", false).option("-p, --project <path>", "Project directory", ".").action(
+program.command("install-hook").description("Install engram hook entries into Claude Code settings").option("--scope <scope>", "local | project | user", "local").option("--dry-run", "Show diff without writing", false).option("-p, --project <path>", "Project directory", ".").option(
+  "--auto-reindex",
+  "Also register a PostToolUse Edit|Write|MultiEdit entry calling 'engram reindex-hook' (keeps graph fresh after every edit, #8)",
+  false
+).action(
   async (opts) => {
     const settingsPath = resolveSettingsPath(opts.scope, opts.project);
     if (!settingsPath) {
@@ -3256,13 +3380,20 @@ program.command("install-hook").description("Install engram hook entries into Cl
         process.exit(1);
       }
     }
-    const result = installEngramHooks(existing);
+    const result = installEngramHooks(existing, void 0, {
+      autoReindex: opts.autoReindex
+    });
     console.log(
       chalk2.bold(`
 \u{1F4CC} engram install-hook (scope: ${opts.scope})`)
     );
     console.log(chalk2.dim(`   Target: ${settingsPath}`));
-    if (result.added.length === 0 && !result.statusLineAdded) {
+    if (opts.autoReindex) {
+      console.log(
+        chalk2.dim("   Auto-reindex: enabled (engram reindex-hook)")
+      );
+    }
+    if (result.added.length === 0 && !result.statusLineAdded && !result.autoReindexAdded) {
       console.log(
         chalk2.yellow(
           `
@@ -3317,6 +3448,13 @@ program.command("install-hook").description("Install engram hook entries into Cl
         chalk2.green("   \u2705 StatusLine: engram hud-label (HUD visible in Claude Code)")
       );
     }
+    if (result.autoReindexAdded) {
+      console.log(
+        chalk2.green(
+          "   \u2705 PostToolUse: engram reindex-hook (matcher: Edit|Write|MultiEdit)"
+        )
+      );
+    }
     if (result.alreadyPresent.length > 0) {
       console.log(
         chalk2.dim(
@@ -3390,7 +3528,7 @@ program.command("uninstall-hook").description("Remove engram hook entries from C
   }
 });
 program.command("hook-stats").description("Summarize hook-log.jsonl for a project").option("-p, --project <path>", "Project directory", ".").option("--json", "Output as JSON", false).action(async (opts) => {
-  const absProject = pathResolve(opts.project);
+  const absProject = pathResolve2(opts.project);
   const projectRoot = findProjectRoot(absProject) ?? absProject;
   const entries = readHookLog(projectRoot);
   const summary = summarizeHookLog(entries);
@@ -3401,8 +3539,8 @@ program.command("hook-stats").description("Summarize hook-log.jsonl for a projec
   console.log(formatStatsSummary(summary));
 });
 program.command("hook-preview").description("Show what the Read handler would do for a file (dry-run)").argument("<file>", "Target file path").option("-p, --project <path>", "Project directory", ".").action(async (file, opts) => {
-  const absProject = pathResolve(opts.project);
-  const absFile = pathResolve(absProject, file);
+  const absProject = pathResolve2(opts.project);
+  const absFile = pathResolve2(absProject, file);
   const payload = {
     hook_event_name: "PreToolUse",
     tool_name: "Read",
@@ -3451,7 +3589,7 @@ program.command("hook-preview").description("Show what the Read handler would do
   console.log(chalk2.yellow(`   Decision: ${decision ?? "unknown"}`));
 });
 program.command("hook-disable").description("Disable engram hooks via kill switch (does not uninstall)").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const absProject = pathResolve(opts.project);
+  const absProject = pathResolve2(opts.project);
   const projectRoot = findProjectRoot(absProject);
   if (!projectRoot) {
     console.error(
@@ -3478,7 +3616,7 @@ program.command("hook-disable").description("Disable engram hooks via kill switc
   }
 });
 program.command("hook-enable").description("Re-enable engram hooks (remove kill switch flag)").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const absProject = pathResolve(opts.project);
+  const absProject = pathResolve2(opts.project);
   const projectRoot = findProjectRoot(absProject);
   if (!projectRoot) {
     console.error(chalk2.red(`Not an engram project: ${absProject}`));
@@ -3507,7 +3645,7 @@ program.command("memory-sync").description(
   "Write engram's structural facts into MEMORY.md (complementary to Anthropic Auto-Dream)"
 ).option("-p, --project <path>", "Project directory", ".").option("--dry-run", "Print what would be written without writing", false).action(
   async (opts) => {
-    const absProject = pathResolve(opts.project);
+    const absProject = pathResolve2(opts.project);
     const projectRoot = findProjectRoot(absProject);
     if (!projectRoot) {
       console.error(
@@ -3605,13 +3743,13 @@ program.command("stress-test").description("Run stress tests: memory, concurrenc
   }
 });
 program.command("server").description("Start engram HTTP REST server (binds to 127.0.0.1 only)").option("--http", "Enable HTTP server (default)").option("--port <port>", "HTTP port", "7337").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { startHttpServer } = await import("./server-KUG7U6SG.js");
-  await startHttpServer(pathResolve(opts.project), parseInt(opts.port, 10));
+  const { startHttpServer } = await import("./server-A6MUVKQK.js");
+  await startHttpServer(pathResolve2(opts.project), parseInt(opts.port, 10));
 });
 program.command("ui").description("Open the web dashboard (auto-starts HTTP server if needed)").option("--port <port>", "HTTP port", "7337").option("-p, --project <path>", "Project directory", ".").option("--no-open", "Don't launch browser, just print the URL").action(async (opts) => {
   const port = parseInt(opts.port, 10);
   const publicUrl = `http://127.0.0.1:${port}/ui`;
-  const projectRoot = pathResolve(opts.project);
+  const projectRoot = pathResolve2(opts.project);
   const { existsSync: existsSync10, readFileSync: readFileSync6 } = await import("fs");
   const pidPath = join9(projectRoot, ".engram", "http-server.pid");
   let alreadyRunning = false;
@@ -3666,7 +3804,7 @@ program.command("context-server").description("Start Zed-compatible context serv
 });
 program.command("tune").description("Analyze hook-log and propose provider config changes").option("-p, --project <path>", "Project directory", ".").option("--dry-run", "Show proposed changes without applying (default)").option("--apply", "Apply proposed changes to .engram/config.json").action(async (opts) => {
   const { analyzeTuning, applyTuning } = await import("./tuner-KFNNGKG3.js");
-  const proposal = analyzeTuning(pathResolve(opts.project));
+  const proposal = analyzeTuning(pathResolve2(opts.project));
   if (proposal.changes.length === 0) {
     console.log(
       chalk2.dim(
@@ -3688,7 +3826,7 @@ program.command("tune").description("Analyze hook-log and propose provider confi
     );
   }
   if (opts.apply) {
-    applyTuning(pathResolve(opts.project), proposal);
+    applyTuning(pathResolve2(opts.project), proposal);
     console.log(chalk2.green("\n\u2705 Changes applied to .engram/config.json"));
   } else {
     console.log(chalk2.dim("\nRun with --apply to write these changes."));
@@ -3696,9 +3834,9 @@ program.command("tune").description("Analyze hook-log and propose provider confi
 });
 var dbCmd = program.command("db").description("Database management");
 dbCmd.command("status").description("Show schema version and migration status").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+  const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
   const { CURRENT_SCHEMA_VERSION, getSchemaVersion } = await import("./migrate-UKCO6BUU.js");
-  const store = await getStore2(pathResolve(opts.project));
+  const store = await getStore2(pathResolve2(opts.project));
   try {
     const version = getSchemaVersion(store.db);
     const pending = CURRENT_SCHEMA_VERSION - version;
@@ -3713,11 +3851,11 @@ dbCmd.command("status").description("Show schema version and migration status").
   }
 });
 dbCmd.command("migrate").description("Run pending schema migrations").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+  const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
   const { runMigrations } = await import("./migrate-UKCO6BUU.js");
-  const store = await getStore2(pathResolve(opts.project));
+  const store = await getStore2(pathResolve2(opts.project));
   try {
-    const dbPath = join9(pathResolve(opts.project), ".engram", "graph.db");
+    const dbPath = join9(pathResolve2(opts.project), ".engram", "graph.db");
     const result = runMigrations(
       store.db,
       dbPath
@@ -3748,11 +3886,11 @@ dbCmd.command("rollback").description("Roll back to an earlier schema version (D
     console.error(chalk2.red(`Invalid version: ${opts.to}`));
     process.exit(1);
   }
-  const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+  const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
   const { rollback, getSchemaVersion } = await import("./migrate-UKCO6BUU.js");
-  const store = await getStore2(pathResolve(opts.project));
+  const store = await getStore2(pathResolve2(opts.project));
   try {
-    const dbPath = join9(pathResolve(opts.project), ".engram", "graph.db");
+    const dbPath = join9(pathResolve2(opts.project), ".engram", "graph.db");
     const current = getSchemaVersion(
       store.db
     );
@@ -3837,7 +3975,7 @@ pluginCmd.command("install").description("Install a plugin by copying its .mjs f
   const { basename: basename6 } = await import("path");
   const { getPluginsDir, ensurePluginsDir, validatePlugin } = await import("./plugin-loader-STTGYIL5.js");
   const { pathToFileURL } = await import("url");
-  const absPath = pathResolve(file);
+  const absPath = pathResolve2(file);
   if (!existsSync9(absPath)) {
     console.error(chalk2.red(`File not found: ${absPath}`));
     process.exit(1);
@@ -3885,9 +4023,9 @@ pluginCmd.command("remove").description("Remove an installed plugin by filename"
 });
 var cacheCmd = program.command("cache").description("Inspect and manage the context cache");
 cacheCmd.command("stats").description("Show cache hit rate, entries, and LRU sizes").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+  const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
   const { getContextCache, ContextCache } = await import("./cache-AK6CF3BC.js");
-  const store = await getStore2(pathResolve(opts.project));
+  const store = await getStore2(pathResolve2(opts.project));
   try {
     ContextCache.ensureTables(store);
     const cache = getContextCache();
@@ -3919,9 +4057,9 @@ cacheCmd.command("stats").description("Show cache hit rate, entries, and LRU siz
   }
 });
 cacheCmd.command("clear").description("Flush all cache layers (query, pattern, hot files)").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+  const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
   const { getContextCache, ContextCache } = await import("./cache-AK6CF3BC.js");
-  const store = await getStore2(pathResolve(opts.project));
+  const store = await getStore2(pathResolve2(opts.project));
   try {
     ContextCache.ensureTables(store);
     const cache = getContextCache();
@@ -3938,14 +4076,14 @@ cacheCmd.command("clear").description("Flush all cache layers (query, pattern, h
   }
 });
 cacheCmd.command("warm").description("Pre-warm hot file cache from access frequency (top-N)").option("-p, --project <path>", "Project directory", ".").option("-n, --limit <n>", "Number of files to warm", "20").action(async (opts) => {
-  const { getStore: getStore2 } = await import("./core-6IY5L6II.js");
+  const { getStore: getStore2 } = await import("./core-TSXA5XZH.js");
   const { getContextCache, ContextCache } = await import("./cache-AK6CF3BC.js");
-  const store = await getStore2(pathResolve(opts.project));
+  const store = await getStore2(pathResolve2(opts.project));
   try {
     ContextCache.ensureTables(store);
     const cache = getContextCache();
     const topN = parseInt(opts.limit, 10) || 20;
-    const count = cache.warmHotFiles(store, pathResolve(opts.project), topN);
+    const count = cache.warmHotFiles(store, pathResolve2(opts.project), topN);
     if (count === 0) {
       console.log(
         chalk2.dim(
@@ -3959,4 +4097,133 @@ cacheCmd.command("warm").description("Pre-warm hot file cache from access freque
     store.close();
   }
 });
+program.command("update").description("Check for and install the latest engram release").option("--check", "Check only \u2014 do not install", false).option("--force", "Bypass 7-day throttle cache on registry check", false).option(
+  "--manager <mgr>",
+  "Override package manager detection (npm | pnpm | yarn | bun)"
+).option("--dry-run", "Print the upgrade command without executing", false).action(
+  async (opts) => {
+    const { checkForUpdate } = await import("./check-2Z3MPZEJ.js");
+    const result = await checkForUpdate(PKG_VERSION, { force: opts.force });
+    if (result.skipped) {
+      if (result.fromCache === false) {
+        console.log(
+          chalk2.dim("Skipped (opt-out via ENGRAM_NO_UPDATE_CHECK or $CI).")
+        );
+      } else {
+        console.log(chalk2.dim("Skipped (registry unreachable)."));
+      }
+      return;
+    }
+    const ageMin = result.checkedAt ? Math.round((Date.now() - result.checkedAt) / 6e4) : 0;
+    const freshness = result.fromCache ? chalk2.dim(` (cached ${ageMin}m ago)`) : chalk2.dim(" (live)");
+    console.log(
+      `${chalk2.bold("engram")} ${chalk2.dim("installed:")} v${result.current}   ${chalk2.dim("latest:")} ${result.latest ?? chalk2.yellow("unknown")}${freshness}`
+    );
+    if (!result.updateAvailable) {
+      console.log(chalk2.green("\u2713 You are on the latest release."));
+      return;
+    }
+    console.log(
+      chalk2.yellow(
+        `\u2B06 v${result.latest} is available \u2014 you're on v${result.current}.`
+      )
+    );
+    if (opts.check) {
+      console.log(chalk2.dim("Run `engram update` to install it."));
+      return;
+    }
+    const { runUpgrade, manualCommand } = await import("./install-YVMVCFQW.js");
+    const outcome = runUpgrade({
+      dryRun: opts.dryRun,
+      manager: opts.manager === "npm" || opts.manager === "pnpm" || opts.manager === "yarn" || opts.manager === "bun" ? opts.manager : void 0
+    });
+    if (outcome.ok) {
+      console.log(chalk2.green(`\u2713 ${outcome.message}`));
+      if (!opts.dryRun) {
+        console.log(chalk2.dim("  Run `engram --version` to verify."));
+      }
+    } else {
+      console.error(chalk2.red(`\u2717 ${outcome.message}`));
+      if (outcome.stderrTail) {
+        console.error(chalk2.dim(outcome.stderrTail));
+      }
+      console.error(chalk2.dim(`  Manual: ${manualCommand()}`));
+      process.exitCode = 1;
+    }
+  }
+);
+program.command("doctor").description("Component health report with remediation hints").option("-p, --project <path>", "Project directory", ".").option("-v, --verbose", "Show remediation hints for warn/fail checks", false).option("--json", "Output JSON", false).option(
+  "--export",
+  "Redacted JSON for bug reports (same as --json with --verbose)",
+  false
+).action(
+  async (opts) => {
+    const { buildReport, formatReport, exportReport } = await import("./report-C3GTM3HY.js");
+    const root = pathResolve2(opts.project);
+    const report = buildReport(root, PKG_VERSION);
+    if (opts.json || opts.export) {
+      console.log(exportReport(report));
+    } else {
+      console.log(formatReport(report, opts.verbose));
+    }
+    process.exitCode = report.overallSeverity === "ok" ? 0 : report.overallSeverity === "warn" ? 1 : 2;
+  }
+);
+program.command("setup").description("Zero-friction first-run wizard (init + install-hook + doctor)").option("-p, --project <path>", "Project directory", ".").option("-y, --yes", "Accept all defaults (non-interactive)", false).option("--dry-run", "Print what would happen without touching anything", false).option(
+  "--scope <scope>",
+  "Hook scope for install-hook step (local | project | user)",
+  "local"
+).action(
+  async (opts) => {
+    const { runSetup } = await import("./wizard-AOXWMSXW.js");
+    const scope = opts.scope === "local" || opts.scope === "project" || opts.scope === "user" ? opts.scope : "local";
+    const result = await runSetup({
+      projectPath: opts.project,
+      yes: opts.yes,
+      dryRun: opts.dryRun,
+      engramVersion: PKG_VERSION,
+      settingsScope: scope
+    });
+    process.exitCode = result.exitCode;
+  }
+);
+var FIRST_RUN_SILENT_CMDS = /* @__PURE__ */ new Set([
+  "intercept",
+  "cursor-intercept",
+  "hud-label",
+  "setup",
+  "init",
+  "update",
+  "doctor"
+]);
+function maybePrintFirstRunHint() {
+  if (process.env.CI) return;
+  if (process.env.ENGRAM_NO_UPDATE_CHECK === "1") return;
+  const subcommand = process.argv[2];
+  if (!subcommand) return;
+  if (FIRST_RUN_SILENT_CMDS.has(subcommand)) return;
+  try {
+    const cwd = process.cwd();
+    if (existsSync9(join9(cwd, ".engram", "graph.db"))) return;
+    const sentinel = join9(homedir(), ".engram", "first-run-shown");
+    if (existsSync9(sentinel)) return;
+    mkdirSync(dirname4(sentinel), { recursive: true });
+    writeFileSync2(sentinel, (/* @__PURE__ */ new Date()).toISOString(), "utf-8");
+    process.stderr.write(
+      chalk2.dim("\u{1F4A1} ") + chalk2.yellow("First time in this repo?") + chalk2.dim(" Run ") + chalk2.white("engram setup") + chalk2.dim(" for a zero-friction install.\n")
+    );
+  } catch {
+  }
+}
+function maybePrintUpdateHintSafe() {
+  const subcommand = process.argv[2];
+  if (!subcommand || FIRST_RUN_SILENT_CMDS.has(subcommand)) return;
+  try {
+    import("./notify-5POGKMRX.js").then((m) => m.maybePrintUpdateHint(PKG_VERSION)).catch(() => {
+    });
+  } catch {
+  }
+}
+maybePrintFirstRunHint();
+maybePrintUpdateHintSafe();
 program.parse();