token-goat 2.0.0 → 2.0.1

package/dist/token-goat.mjs

@@ -981,7 +981,7 @@ var require_command = __commonJS({
     init_define_import_meta_env();
     var EventEmitter = __require("node:events").EventEmitter;
     var childProcess = __require("node:child_process");
-    var path12 = __require("node:path");
+    var path14 = __require("node:path");
     var fs14 = __require("node:fs");
     var process2 = __require("node:process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
@@ -1914,9 +1914,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path12.resolve(baseDir, baseName);
+          const localBin = path14.resolve(baseDir, baseName);
           if (fs14.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path12.extname(baseName))) return void 0;
+          if (sourceExt.includes(path14.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
             (ext) => fs14.existsSync(`${localBin}${ext}`)
           );
@@ -1934,17 +1934,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
           } catch (err2) {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path12.resolve(
-            path12.dirname(resolvedScriptPath),
+          executableDir = path14.resolve(
+            path14.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path12.basename(
+            const legacyName = path14.basename(
               this._scriptPath,
-              path12.extname(this._scriptPath)
+              path14.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -1955,7 +1955,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path12.extname(executableFile));
+        launchWithNode = sourceExt.includes(path14.extname(executableFile));
         let proc;
         if (process2.platform !== "win32") {
           if (launchWithNode) {
@@ -2795,7 +2795,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path12.basename(filename, path12.extname(filename));
+        this._name = path14.basename(filename, path14.extname(filename));
         return this;
       }
       /**
@@ -2809,9 +2809,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path13) {
-        if (path13 === void 0) return this._executableDir;
-        this._executableDir = path13;
+      executableDir(path15) {
+        if (path15 === void 0) return this._executableDir;
+        this._executableDir = path15;
         return this;
       }
       /**
@@ -3162,16 +3162,16 @@ var require_filesystem = __commonJS({
     var LDD_PATH = "/usr/bin/ldd";
     var SELF_PATH = "/proc/self/exe";
     var MAX_LENGTH = 2048;
-    var readFileSync10 = (path12) => {
-      const fd = fs14.openSync(path12, "r");
+    var readFileSync11 = (path14) => {
+      const fd = fs14.openSync(path14, "r");
       const buffer = Buffer.alloc(MAX_LENGTH);
       const bytesRead = fs14.readSync(fd, buffer, 0, MAX_LENGTH, 0);
       fs14.close(fd, () => {
       });
       return buffer.subarray(0, bytesRead);
     };
-    var readFile2 = (path12) => new Promise((resolve4, reject) => {
-      fs14.open(path12, "r", (err2, fd) => {
+    var readFile2 = (path14) => new Promise((resolve4, reject) => {
+      fs14.open(path14, "r", (err2, fd) => {
         if (err2) {
           reject(err2);
         } else {
@@ -3187,7 +3187,7 @@ var require_filesystem = __commonJS({
     module.exports = {
       LDD_PATH,
       SELF_PATH,
-      readFileSync: readFileSync10,
+      readFileSync: readFileSync11,
       readFile: readFile2
     };
   }
@@ -3238,7 +3238,7 @@ var require_detect_libc = __commonJS({
     init_define_import_meta_env();
     var childProcess = __require("child_process");
     var { isLinux, getReport } = require_process();
-    var { LDD_PATH, SELF_PATH, readFile: readFile2, readFileSync: readFileSync10 } = require_filesystem();
+    var { LDD_PATH, SELF_PATH, readFile: readFile2, readFileSync: readFileSync11 } = require_filesystem();
     var { interpreterPath } = require_elf();
     var cachedFamilyInterpreter;
     var cachedFamilyFilesystem;
@@ -3292,11 +3292,11 @@ var require_detect_libc = __commonJS({
       }
       return null;
     };
-    var familyFromInterpreterPath = (path12) => {
-      if (path12) {
-        if (path12.includes("/ld-musl-")) {
+    var familyFromInterpreterPath = (path14) => {
+      if (path14) {
+        if (path14.includes("/ld-musl-")) {
           return MUSL;
-        } else if (path12.includes("/ld-linux-")) {
+        } else if (path14.includes("/ld-linux-")) {
           return GLIBC;
         }
       }
@@ -3330,7 +3330,7 @@ var require_detect_libc = __commonJS({
       }
       cachedFamilyFilesystem = null;
       try {
-        const lddContent = readFileSync10(LDD_PATH);
+        const lddContent = readFileSync11(LDD_PATH);
         cachedFamilyFilesystem = getFamilyFromLddContent(lddContent);
       } catch (e) {
       }
@@ -3343,8 +3343,8 @@ var require_detect_libc = __commonJS({
       cachedFamilyInterpreter = null;
       try {
         const selfContent = await readFile2(SELF_PATH);
-        const path12 = interpreterPath(selfContent);
-        cachedFamilyInterpreter = familyFromInterpreterPath(path12);
+        const path14 = interpreterPath(selfContent);
+        cachedFamilyInterpreter = familyFromInterpreterPath(path14);
       } catch (e) {
       }
       return cachedFamilyInterpreter;
@@ -3355,9 +3355,9 @@ var require_detect_libc = __commonJS({
       }
       cachedFamilyInterpreter = null;
       try {
-        const selfContent = readFileSync10(SELF_PATH);
-        const path12 = interpreterPath(selfContent);
-        cachedFamilyInterpreter = familyFromInterpreterPath(path12);
+        const selfContent = readFileSync11(SELF_PATH);
+        const path14 = interpreterPath(selfContent);
+        cachedFamilyInterpreter = familyFromInterpreterPath(path14);
       } catch (e) {
       }
       return cachedFamilyInterpreter;
@@ -3419,7 +3419,7 @@ var require_detect_libc = __commonJS({
       }
       cachedVersionFilesystem = null;
       try {
-        const lddContent = readFileSync10(LDD_PATH);
+        const lddContent = readFileSync11(LDD_PATH);
         const versionMatch = lddContent.match(RE_GLIBC_VERSION);
         if (versionMatch) {
           cachedVersionFilesystem = versionMatch[1];
@@ -5138,9 +5138,9 @@ var require_sharp = __commonJS({
     ];
     var sharp;
     var errors = [];
-    for (const path12 of paths) {
+    for (const path14 of paths) {
       try {
-        sharp = __require(path12);
+        sharp = __require(path14);
         break;
       } catch (err2) {
         errors.push(err2);
@@ -6552,15 +6552,15 @@ var require_route = __commonJS({
       };
     }
     function wrapConversion(toModel, graph) {
-      const path12 = [graph[toModel].parent, toModel];
+      const path14 = [graph[toModel].parent, toModel];
       let fn = conversions[graph[toModel].parent][toModel];
       let cur = graph[toModel].parent;
       while (graph[cur].parent) {
-        path12.unshift(graph[cur].parent);
+        path14.unshift(graph[cur].parent);
         fn = link(conversions[graph[cur].parent][cur], fn);
         cur = graph[cur].parent;
       }
-      fn.conversion = path12;
+      fn.conversion = path14;
       return fn;
     }
     module.exports = function(fromModel) {
@@ -8464,7 +8464,7 @@ var require_output = __commonJS({
   "node_modules/sharp/lib/output.js"(exports, module) {
     "use strict";
     init_define_import_meta_env();
-    var path12 = __require("node:path");
+    var path14 = __require("node:path");
     var is = require_is();
     var sharp = require_sharp();
     var formats = /* @__PURE__ */ new Map([
@@ -8495,9 +8495,9 @@ var require_output = __commonJS({
       let err2;
       if (!is.string(fileOut)) {
         err2 = new Error("Missing output file path");
-      } else if (is.string(this.options.input.file) && path12.resolve(this.options.input.file) === path12.resolve(fileOut)) {
+      } else if (is.string(this.options.input.file) && path14.resolve(this.options.input.file) === path14.resolve(fileOut)) {
         err2 = new Error("Cannot use same file for input and output");
-      } else if (jp2Regex.test(path12.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
+      } else if (jp2Regex.test(path14.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
         err2 = errJp2Save();
       }
       if (err2) {
@@ -9492,7 +9492,7 @@ init_define_import_meta_env();
 import { createRequire } from "node:module";
 function resolveVersion() {
   if (true) {
-    return "2.0.0";
+    return "2.0.1";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");
@@ -10125,23 +10125,23 @@ function isNoisePath(inputPath) {
     }
   }
   const slashIdx = p.lastIndexOf("/");
-  const basename4 = slashIdx >= 0 ? p.slice(slashIdx + 1) : p;
-  if (NOISE_BASENAMES.has(basename4)) {
+  const basename6 = slashIdx >= 0 ? p.slice(slashIdx + 1) : p;
+  if (NOISE_BASENAMES.has(basename6)) {
     return true;
   }
-  if (basename4.startsWith(".improve-state-") || basename4.startsWith("improve_commit_msg_")) {
+  if (basename6.startsWith(".improve-state-") || basename6.startsWith("improve_commit_msg_")) {
     return true;
   }
-  const dotIdx = basename4.lastIndexOf(".");
+  const dotIdx = basename6.lastIndexOf(".");
   if (dotIdx >= 0) {
-    const ext = basename4.slice(dotIdx);
+    const ext = basename6.slice(dotIdx);
     if (NOISE_EXTS.has(ext)) {
       return true;
     }
   }
   for (const ext of NOISE_EXTS) {
     if (ext.includes(".") && ext.split(".").length > 2) {
-      if (basename4.endsWith(ext)) {
+      if (basename6.endsWith(ext)) {
         return true;
       }
     }
@@ -10297,6 +10297,9 @@ function wasFileReadThisSession(filePath) {
 function getSessionWebFetches() {
   return _webFetches;
 }
+function getBashOutputId(commandHash) {
+  return _bashOutputs.get(commandHash) ?? null;
+}
 registerReset(() => {
   _files = /* @__PURE__ */ new Map();
   _hintsShown = /* @__PURE__ */ new Set();
@@ -10362,6 +10365,7 @@ var HOOK_EVENTS = [
 // src/hooks_read.ts
 init_define_import_meta_env();
 import * as fs4 from "node:fs";
+import * as path6 from "node:path";
 
 // src/hooks_common.ts
 init_define_import_meta_env();
@@ -10378,12 +10382,483 @@ function getFilePath(event) {
 function passOutput() {
   return { hookType: "pass" };
 }
+function denyOutput(message) {
+  return { hookType: "deny", message };
+}
 function contextOutput(context) {
   return { hookType: "context", context };
 }
 
+// src/hints.ts
+init_define_import_meta_env();
+var HINT_PRIORITY_MEDIUM = 3;
+var STALE_READ_AGE_SECONDS = 30 * 60;
+function buildPackageManifestHint(options) {
+  try {
+    const hasOffset = options.offset !== null && options.offset !== void 0 && options.offset >= 0;
+    const hasLimit = options.limit !== null && options.limit !== void 0 && options.limit > 0;
+    if (hasOffset || hasLimit) {
+      return null;
+    }
+    const fname = _sanitizeHintPath(options.file_path.split(/[/\\]/).pop() ?? "");
+    const basenameLower = fname.toLowerCase();
+    if (basenameLower === "package.json") {
+      const text = `\`${fname}\` is a package manifest. Consider \`token-goat section package.json::dependencies\` or \`token-goat section package.json::devDependencies\` for focused reads.`;
+      return {
+        text,
+        hint_priority: HINT_PRIORITY_MEDIUM
+      };
+    }
+    if (basenameLower === "package-lock.json") {
+      const text = `\`${fname}\` is a large lockfile. Consider \`npm ls\`, \`npm outdated\`, or \`npm audit\` instead for targeted info.`;
+      return {
+        text,
+        hint_priority: HINT_PRIORITY_MEDIUM
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function _sanitizeHintPath(path14) {
+  if (typeof path14 !== "string") {
+    return "???";
+  }
+  return path14.replace(/[\x00]/g, "").slice(0, 200);
+}
+
+// src/hints/lang_patterns.ts
+init_define_import_meta_env();
+var LOCK_FILE_NAMES = /* @__PURE__ */ new Set([
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "cargo.lock",
+  "poetry.lock",
+  "pipfile.lock",
+  "uv.lock",
+  "gemfile.lock",
+  "go.sum",
+  "composer.lock",
+  "mix.lock",
+  "pubspec.lock",
+  "package.resolved"
+]);
+var MANIFEST_FILE_NAMES = /* @__PURE__ */ new Set([
+  "package.json",
+  "pyproject.toml",
+  "cargo.toml",
+  "go.mod",
+  "go.work",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "settings.gradle",
+  "composer.json",
+  "gemfile",
+  "mix.exs",
+  "pubspec.yaml",
+  "cmakelists.txt",
+  "makefile",
+  "project.clj",
+  // TypeScript / JavaScript project configs
+  "tsconfig.json",
+  "jsconfig.json",
+  // Bundler / framework configs
+  "vite.config.ts",
+  "vite.config.js",
+  "webpack.config.js",
+  "webpack.config.ts",
+  "rollup.config.js",
+  "rollup.config.ts",
+  "esbuild.config.js",
+  "next.config.js",
+  "next.config.ts",
+  "nuxt.config.ts"
+]);
+var MANIFEST_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".cabal"
+]);
+var MANIFEST_BASENAME_PATTERNS = [
+  /^tsconfig(\..+)?\.json$/i
+];
+var BUILD_DIR_NAMES = /* @__PURE__ */ new Set([
+  "dist",
+  "target",
+  "build",
+  "out",
+  "__pycache__",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".gradle",
+  "_build",
+  ".build",
+  "pkg",
+  "obj"
+]);
+var ALWAYS_GENERATED_EXTS = /* @__PURE__ */ new Set([
+  ".pyc",
+  ".pyo",
+  ".pyd",
+  ".class",
+  ".o",
+  ".a",
+  ".so",
+  ".dylib",
+  ".dll",
+  ".tsbuildinfo"
+]);
+var CONDITIONALLY_GENERATED_EXTS = /* @__PURE__ */ new Set([
+  ".map",
+  ".d.ts"
+]);
+var BUILD_COMMAND_PATTERNS = [
+  // Rust / Cargo
+  /^\s*cargo\s+(build|test|run|check|clippy)\b/i,
+  // Go
+  /^\s*go\s+(build|test|run|vet)\b/i,
+  // Maven
+  /^\s*mvn\b/i,
+  // Gradle (direct or wrapper)
+  /^\s*(?:gradle|\.\/gradlew|gradlew)\b/i,
+  // Python / pip
+  /^\s*pip\s+(install|freeze)\b/i,
+  // Poetry
+  /^\s*poetry\s+(install|update)\b/i,
+  // uv
+  /^\s*uv\s+(sync|pip\s+install)\b/i,
+  // Bundler (Ruby)
+  /^\s*bundle\s+(install|update)\b/i,
+  // Mix (Elixir)
+  /^\s*mix\s+(deps\.get|compile|test)\b/i,
+  // dotnet
+  /^\s*dotnet\s+(build|test|restore)\b/i,
+  // Make
+  /^\s*make\b/i,
+  // CMake build
+  /^\s*cmake\s+--build\b/i,
+  // Rake (Ruby)
+  /^\s*rake\b/i,
+  // TypeScript compiler
+  /^\s*tsc\b/i,
+  // Vite
+  /^\s*vite\s+(build|dev|preview)\b/i,
+  // Next.js
+  /^\s*next\s+(build|dev|start)\b/i,
+  // Nuxt
+  /^\s*nuxt\s+(build|dev)\b/i,
+  // Webpack
+  /^\s*webpack\b/i,
+  // esbuild
+  /^\s*esbuild\b/i,
+  // Rollup
+  /^\s*rollup\b/i,
+  // Turbo
+  /^\s*turbo\s+(build|dev)\b/i
+];
+function isLockFile(basename6) {
+  return LOCK_FILE_NAMES.has(basename6.toLowerCase());
+}
+function isManifestFile(basename6) {
+  const lower = basename6.toLowerCase();
+  if (MANIFEST_FILE_NAMES.has(lower)) return true;
+  const dot = lower.lastIndexOf(".");
+  if (dot !== -1 && MANIFEST_EXTENSIONS.has(lower.slice(dot))) return true;
+  if (MANIFEST_BASENAME_PATTERNS.some((re) => re.test(basename6))) return true;
+  return false;
+}
+function pathSegments(filePath) {
+  return filePath.split(/[/\\]/).filter((s) => s.length > 0);
+}
+function isInBuildDir(filePath) {
+  const segments = pathSegments(filePath);
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (seg !== void 0 && BUILD_DIR_NAMES.has(seg.toLowerCase())) return true;
+  }
+  return false;
+}
+function isGeneratedFile(filePath) {
+  const lower = filePath.toLowerCase();
+  for (const ext of ALWAYS_GENERATED_EXTS) {
+    if (lower.endsWith(ext)) return true;
+  }
+  for (const ext of CONDITIONALLY_GENERATED_EXTS) {
+    if (lower.endsWith(ext) && isInBuildDir(filePath)) return true;
+  }
+  return false;
+}
+function isBuildCommand(cmd) {
+  return BUILD_COMMAND_PATTERNS.some((re) => re.test(cmd));
+}
+var MONITORING_COMMAND_PATTERNS = [
+  // GitHub CI
+  { pattern: /^gh run (?:watch|view|list)/, recallHint: '--grep "fail|error|pass|\u2713|\u2717|conclusion"' },
+  { pattern: /^gh run view.*--log/, recallHint: '--tail 100 --grep "Error|FAIL|error"' },
+  { pattern: /^gh pr checks/, recallHint: '--grep "fail|error|pass|pending"' },
+  { pattern: /^gh workflow (?:run|list|view)/, recallHint: '--grep "completed|failed|in_progress"' },
+  // Dev servers (Next, Vite, Nuxt, Remix, Astro)
+  { pattern: /^(?:npx\s+)?next dev/, recallHint: '--tail 30 --grep "error|warn|ready|compiled"' },
+  { pattern: /^(?:npx\s+)?next build/, recallHint: '--grep "error|warn|Failed|\u2713"' },
+  { pattern: /^(?:npx\s+)?vite(?:\s+dev|\s+build|\s+preview)?$/, recallHint: '--tail 20 --grep "error|warn|ready"' },
+  { pattern: /^(?:npx\s+)?nuxt dev/, recallHint: '--tail 30 --grep "error|warn|ready"' },
+  { pattern: /^(?:npx\s+)?remix dev/, recallHint: '--tail 20 --grep "error|warn|ready"' },
+  { pattern: /^(?:npx\s+)?astro dev/, recallHint: '--tail 20 --grep "error|warn|ready"' },
+  // Test watchers
+  { pattern: /^(?:npx\s+)?vitest(?:\s+run|\s+watch)?/, recallHint: '--grep "FAIL|PASS|Error|\u2713|\u2717"' },
+  { pattern: /^(?:npx\s+)?jest(?:\s+--watch)?/, recallHint: '--grep "FAIL|PASS|Error|Tests:"' },
+  { pattern: /^pytest(?:\s|$)/, recallHint: '--grep "FAILED|PASSED|ERROR|passed|failed"' },
+  { pattern: /^(?:cargo\s+test|cargo\s+watch)/, recallHint: '--grep "FAILED|ok|error\\["' },
+  { pattern: /^go test/, recallHint: '--grep "FAIL|ok|---"' },
+  // Docker / compose
+  { pattern: /^docker(?:\s+compose)?\s+logs/, recallHint: '--tail 50 --grep "error|warn|Error|WARN"' },
+  { pattern: /^docker-compose\s+logs/, recallHint: '--tail 50 --grep "error|warn|Error|WARN"' },
+  // File watchers / hot-reload
+  { pattern: /^nodemon/, recallHint: '--tail 20 --grep "error|crash|restart"' },
+  { pattern: /^air(?:\s|$)/, recallHint: '--tail 20 --grep "error|build failed"' },
+  { pattern: /^cargo watch/, recallHint: '--tail 20 --grep "error\\[|warning\\["' },
+  { pattern: /^watchexec/, recallHint: '--tail 20 --grep "error|warn"' },
+  // Linters / formatters run repeatedly
+  { pattern: /^(?:npx\s+)?eslint(?:\s|$)/, recallHint: '--grep "error|warning|\u2716|problems"' },
+  { pattern: /^(?:npx\s+)?prettier(?:\s|$)/, recallHint: '--grep "unchanged|reformatted|error"' },
+  { pattern: /^ruff(?:\s|$)/, recallHint: '--grep "error|warning|Found"' },
+  { pattern: /^(?:cargo\s+)?clippy/, recallHint: '--grep "error\\[|warning\\["' }
+];
+function getMonitoringRecallHint(cmd) {
+  for (const { pattern, recallHint } of MONITORING_COMMAND_PATTERNS) {
+    if (pattern.test(cmd.trim())) return recallHint;
+  }
+  return null;
+}
+
+// src/hints/markdown_hints.ts
+init_define_import_meta_env();
+var MARKDOWN_SIZE_THRESHOLD = 8e3;
+var MAX_HEADINGS = 40;
+var MAX_OUTPUT_LINES = 60;
+function extractMarkdownHeadings(content) {
+  const headings = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const match = /^(#+)\s+(.+?)\s*$/.exec(line);
+    if (!match || match.length < 3) continue;
+    const hashes = match[1];
+    const headingText = match[2];
+    const level = hashes.length;
+    if (level > 3) continue;
+    const text = headingText.trim();
+    if (!text) continue;
+    headings.push({
+      level,
+      text,
+      lineNumber: i + 1
+    });
+    if (headings.length >= MAX_HEADINGS) break;
+  }
+  return headings;
+}
+function formatHeadingTree(headings, filePath) {
+  if (headings.length === 0) return "";
+  const seenTexts = /* @__PURE__ */ new Map();
+  const dedupedHeadings = [];
+  for (const h of headings) {
+    const count = (seenTexts.get(h.text) ?? 0) + 1;
+    seenTexts.set(h.text, count);
+    const suffix = count > 1 ? ` #${count}` : "";
+    dedupedHeadings.push({
+      text: h.text + suffix,
+      level: h.level
+    });
+  }
+  const lines = [];
+  lines.push(`Large markdown file (${headings.length} headings). Use token-goat section to read a specific section:`);
+  lines.push(`  token-goat section "${filePath}::Heading Name"`);
+  lines.push(``);
+  lines.push(`Sections:`);
+  let headingsAdded = 0;
+  for (const h of dedupedHeadings) {
+    if (lines.length + 1 >= MAX_OUTPUT_LINES) {
+      const remaining = dedupedHeadings.length - headingsAdded;
+      lines.push(`  ... (${remaining} more headings)`);
+      break;
+    }
+    const indent = h.level === 1 ? "" : h.level === 2 ? "  " : "    ";
+    const marker = "#".repeat(h.level);
+    lines.push(`  ${indent}${marker} ${h.text}`);
+    headingsAdded++;
+  }
+  return lines.join("\n");
+}
+var WELL_KNOWN_SECTIONS = {
+  "CHANGELOG.md": ["Unreleased"],
+  "README.md": ["Install", "Usage", "API", "Configuration", "Getting Started"],
+  "CONTRIBUTING.md": ["Setup", "Commands", "Testing", "Development"],
+  "CLAUDE.md": ["Commands", "Architecture"],
+  "CLAUDE.arch.md": ["Component Map", "Architecture"]
+};
+function getWellKnownSections(basename6) {
+  return WELL_KNOWN_SECTIONS[basename6] ?? [];
+}
+function extractChangelogVersionHint(content, filePath) {
+  const lines = content.split("\n");
+  let foundUnreleased = false;
+  for (const line of lines) {
+    const m = /^##\s+(\[?[\d]+\.[\d]+\.[\d]+\]?)/.exec(line);
+    if (m) {
+      if (foundUnreleased || !line.toLowerCase().includes("unreleased")) {
+        const ver = m[1];
+        return ` | token-goat section "${filePath}::${ver}"`;
+      }
+    }
+    if (/^##\s+\[?unreleased\]?/i.test(line)) {
+      foundUnreleased = true;
+    }
+  }
+  return "";
+}
+
+// src/hints/file_type_handler.ts
+init_define_import_meta_env();
+var FILE_TYPE_THRESHOLDS = {
+  pdf: 0,
+  // always intercept (any size)
+  html: 5e4,
+  txt: 2e4,
+  csv: 1e4,
+  tsv: 1e4,
+  office: 0,
+  // always block (.docx etc)
+  generic: 1e5
+  // catch-all for unrecognized large files
+};
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1048576) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1048576).toFixed(1)} MB`;
+}
+function handlePdf(filePath, contentLength) {
+  return {
+    shouldBlock: true,
+    message: [
+      `PDF file (${formatBytes(contentLength)}).`,
+      `Use the \`pages\` parameter to scope the read: Read({ file_path: "${filePath}", pages: "1-5" })`,
+      `For the full page count, run: pdfinfo "${filePath}" | grep Pages`
+    ].join("\n")
+  };
+}
+function handleHtml(filePath, content) {
+  if (content.length < FILE_TYPE_THRESHOLDS.html) return { shouldBlock: false, message: "" };
+  const title = content.match(/<title[^>]*>([^<]+)<\/title>/i)?.[1]?.trim();
+  const headings = [...content.matchAll(/<h([1-6])[^>]*>([^<]+)<\/h\1>/gi)].slice(0, 20).map((m) => {
+    const level = m[1];
+    const text = m[2];
+    if (!level || !text) return "";
+    return `${"  ".repeat(Number(level) - 1)}h${level}: ${text.trim()}`;
+  }).filter(Boolean);
+  const isMinified = !content.includes("\n") || content.length > 5e4 && content.split("\n").length < 10;
+  if (isMinified) {
+    return {
+      shouldBlock: true,
+      message: `HTML file appears minified (${formatBytes(content.length)}). Consider fetching the source or converting with: pandoc "${filePath}" -t plain`
+    };
+  }
+  return {
+    shouldBlock: true,
+    message: [
+      `Large HTML file (${formatBytes(content.length)})${title ? `: "${title}"` : ""}.`,
+      headings.length > 0 ? `Headings:
+${headings.join("\n")}` : "",
+      `Use token-goat section to extract a section by heading, or convert to text: pandoc "${filePath}" -t plain`
+    ].filter(Boolean).join("\n")
+  };
+}
+function handleTxt(filePath, content) {
+  if (content.length < FILE_TYPE_THRESHOLDS.txt) return { shouldBlock: false, message: "" };
+  const lines = content.split("\n");
+  const isLog = /\.(log|out|err|trace)$/i.test(filePath) || filePath.includes("/logs/");
+  const preview = [
+    "--- first 5 lines ---",
+    ...lines.slice(0, 5),
+    `... (${lines.length.toLocaleString()} lines total) ...`,
+    "--- last 5 lines ---",
+    ...lines.slice(-5)
+  ].join("\n");
+  const recall = isLog ? 'Log file \u2014 use Read with offset/limit params, or: token-goat bash-output <id> --tail 100 --grep "error|ERROR"' : "Use Read with offset and limit params to sample specific line ranges.";
+  return {
+    shouldBlock: true,
+    message: `Large text file (${formatBytes(content.length)}, ${lines.length.toLocaleString()} lines).
+${preview}
+
+${recall}`
+  };
+}
+function handleOfficeBinary(filePath) {
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  return {
+    shouldBlock: true,
+    message: [
+      `Binary Office file (.${ext}) \u2014 cannot be read as text.`,
+      `Extract content first: pandoc "${filePath}" -t plain > "${filePath}.txt"`,
+      `Then read the extracted .txt file.`
+    ].join("\n")
+  };
+}
+function handleCsv(filePath, content) {
+  if (content.length < FILE_TYPE_THRESHOLDS.csv) return { shouldBlock: false, message: "" };
+  const lines = content.split("\n").filter((l) => l.trim());
+  const headers = lines[0] ?? "";
+  const sampleRows = lines.slice(1, 4);
+  const sep = filePath.endsWith(".tsv") ? "	" : ",";
+  const colCount = headers.split(sep).length;
+  return {
+    shouldBlock: true,
+    message: [
+      `Large CSV file (${formatBytes(content.length)}, ~${lines.length.toLocaleString()} rows, ${colCount} columns).`,
+      `Columns: ${headers}`,
+      `Sample rows:
+${sampleRows.join("\n")}`,
+      `Use Read with offset/limit to sample rows, or query with DuckDB: duckdb -c "SELECT * FROM '${filePath}' LIMIT 10"`
+    ].join("\n")
+  };
+}
+function handleGenericLarge(filePath, contentLength) {
+  if (contentLength < FILE_TYPE_THRESHOLDS.generic) return { shouldBlock: false, message: "" };
+  return {
+    shouldBlock: true,
+    message: `Large file (${formatBytes(contentLength)}). Use Read with offset and limit parameters to read specific line ranges rather than loading the entire file.`
+  };
+}
+function dispatchFileTypeHandler(filePath, content, contentLengthHint) {
+  const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
+  if (["md", "mdx", "markdown", "rst"].includes(ext)) return null;
+  const effectiveLength = contentLengthHint ?? content.length;
+  if (ext === "pdf") return handlePdf(filePath, effectiveLength);
+  if (["html", "htm", "xhtml"].includes(ext)) return handleHtml(filePath, content);
+  if (["txt", "log", "out", "err", "trace"].includes(ext)) return handleTxt(filePath, content);
+  if (["docx", "xlsx", "pptx", "odt", "ods", "ott", "odp"].includes(ext)) return handleOfficeBinary(filePath);
+  if (ext === "csv" || ext === "tsv") return handleCsv(filePath, content);
+  return handleGenericLarge(filePath, effectiveLength);
+}
+
 // src/hooks_read.ts
+function isTsConfigFile(basename6) {
+  const lower = basename6.toLowerCase();
+  return /^tsconfig(\..+)?\.json$/i.test(lower) || lower === "jsconfig.json";
+}
 var LARGE_FILE_BYTES = 100 * 1024;
+function isNodeModulesPath(path14) {
+  const isWindows = process.platform === "win32";
+  const check = isWindows ? path14.toLowerCase() : path14;
+  return check.includes("/node_modules/") || check.includes("\\node_modules\\");
+}
+function _isDocFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.endsWith(".md") || lower.endsWith(".mdx") || lower.endsWith(".markdown") || lower.endsWith(".rst");
+}
 function statSize(absPath) {
   try {
     return fs4.statSync(absPath).size;
@@ -10395,41 +10870,124 @@ function preReadHandler(event) {
   const filePath = getFilePath(event);
   if (filePath === void 0) return passOutput();
   const normalized = normalizePath(filePath);
+  if (isNodeModulesPath(normalized)) {
+    return denyOutput(
+      "node_modules is typically noise; use npm ls, npm outdated, or npm audit instead for dependency info. To force access, use: token-goat read node_modules/package/file.js::symbol-name or token-goat section node_modules/package/file.js::heading"
+    );
+  }
+  const basename6 = path6.basename(normalized);
+  if (isLockFile(basename6)) {
+    return denyOutput(
+      'Lock files are rarely useful to read in full. Use `token-goat section "' + normalized + '::<section>"` to extract a specific dependency, or read the relevant manifest instead.'
+    );
+  }
+  if (normalized.toLowerCase().endsWith(".tsbuildinfo")) {
+    return denyOutput(
+      "This is a TypeScript incremental build cache file. You don't need to read it directly."
+    );
+  }
+  if (isInBuildDir(normalized) || isGeneratedFile(normalized)) {
+    return denyOutput(
+      "Generated/build artifact \u2014 read the source file instead."
+    );
+  }
+  const manifestHint = buildPackageManifestHint({ file_path: normalized });
+  if (manifestHint) {
+    recordFileRead(normalized);
+    return contextOutput(manifestHint.text);
+  }
+  if (isTsConfigFile(basename6) && wasFileReadThisSession(normalized)) {
+    recordFileRead(normalized);
+    return contextOutput(
+      "Already read " + basename6 + '. Use `token-goat section "' + normalized + '::compilerOptions"` to extract compiler options, or `token-goat config-get ' + normalized + " compilerOptions.target` for a single value."
+    );
+  }
+  if (isManifestFile(basename6) && wasFileReadThisSession(normalized)) {
+    recordFileRead(normalized);
+    return contextOutput(
+      "You've already read " + basename6 + '. Use `token-goat section "' + normalized + '::<field>"` or `token-goat config-get ' + normalized + " <key>` to extract just the value you need."
+    );
+  }
+  const isMarkdown = /\.(md|mdx|markdown|rst)$/i.test(basename6);
+  if (isMarkdown) {
+    let fileContent = null;
+    try {
+      const sz = statSize(normalized);
+      if (sz !== null && sz >= MARKDOWN_SIZE_THRESHOLD) {
+        fileContent = fs4.readFileSync(normalized, "utf8");
+      }
+    } catch {
+    }
+    if (fileContent !== null) {
+      const headings = extractMarkdownHeadings(fileContent);
+      if (headings.length >= 3) {
+        recordFileRead(normalized);
+        const hintText = formatHeadingTree(headings, normalized);
+        const wellKnown = getWellKnownSections(basename6);
+        const wellKnownText = wellKnown.length > 0 ? "\nQuick access: " + wellKnown.map((s) => 'token-goat section "' + normalized + "::" + s + '"').join(" | ") : "";
+        const changelogExtra = basename6.toLowerCase() === "changelog.md" ? extractChangelogVersionHint(fileContent, normalized) : "";
+        return denyOutput(hintText + wellKnownText + changelogExtra);
+      }
+    }
+  }
   if (wasFileReadThisSession(normalized)) {
     const entry = getSessionFiles().get(normalized);
     const reads = entry?.readCount ?? 1;
     const plural = reads === 1 ? "read" : "reads";
     recordFileRead(normalized);
+    const hint = _isDocFile(normalized) ? 'Use `token-goat section "' + normalized + '::SectionName"` to read one section.' : "Use token-goat read/section/symbol to re-read surgically.";
     return contextOutput(
-      `Note: ${normalized} was already read this session (${reads} ${plural}). Use token-goat read/section/symbol to re-read surgically.`
+      "Note: " + normalized + " was already read this session (" + reads + " " + plural + "). " + hint
     );
   }
   const size = statSize(normalized);
   if (size !== null && size >= LARGE_FILE_BYTES) {
     const kb = Math.round(size / 1024);
     recordFileRead(normalized);
+    const hint = _isDocFile(normalized) ? 'Use `token-goat section "' + normalized + '::SectionName"` to read one section.' : "Consider token-goat skeleton or token-goat section.";
     return contextOutput(
-      `Note: ${normalized} is large (${kb}kb). Consider token-goat skeleton or token-goat section.`
+      "Note: " + normalized + " is large (" + kb + "kb). " + hint
     );
   }
+  const fileTypeExt = path6.extname(normalized).slice(1).toLowerCase();
+  const binaryExts = /* @__PURE__ */ new Set(["pdf", "docx", "xlsx", "pptx", "odt", "ods", "ott", "odp"]);
+  const textTypeExts = /* @__PURE__ */ new Set(["html", "htm", "xhtml", "txt", "log", "out", "err", "trace", "csv", "tsv"]);
+  const fileStatSize = size ?? statSize(normalized) ?? 0;
+  const isKnownFileType = binaryExts.has(fileTypeExt) || textTypeExts.has(fileTypeExt);
+  if (isKnownFileType || fileStatSize >= FILE_TYPE_THRESHOLDS.generic) {
+    let ftContent = "";
+    if (!binaryExts.has(fileTypeExt)) {
+      try {
+        ftContent = fs4.readFileSync(normalized, "utf8");
+      } catch {
+      }
+    }
+    const ftResult = dispatchFileTypeHandler(normalized, ftContent, fileStatSize);
+    if (ftResult?.shouldBlock) {
+      recordFileRead(normalized);
+      return denyOutput(ftResult.message);
+    }
+  }
   recordFileRead(normalized);
   return passOutput();
 }
 registerHook("pre_tool_use", preReadHandler, { toolName: "Read" });
+registerHook("pre_tool_use", preReadHandler, { toolName: "Grep" });
 
 // src/hooks_edit.ts
 init_define_import_meta_env();
+import * as path8 from "node:path";
 
 // src/hooks_index.ts
 init_define_import_meta_env();
 import * as fs5 from "node:fs";
-import * as path6 from "node:path";
+import * as path7 from "node:path";
 function dirtyQueuePath() {
-  return path6.join(dataDir(), "queue", "dirty.txt");
+  return path7.join(dataDir(), "queue", "dirty.txt");
 }
 function appendDirtyPath(normalizedPath) {
   const queuePath = dirtyQueuePath();
-  fs5.mkdirSync(path6.dirname(queuePath), { recursive: true });
+  fs5.mkdirSync(path7.dirname(queuePath), { recursive: true });
   fs5.appendFileSync(queuePath, `${normalizedPath}
 `);
 }
@@ -10460,9 +11018,9 @@ function clearDirtyQueue() {
 function preCompactIndexHandler(_event) {
   const paths = getDirtyPaths();
   if (paths.length > 0) {
-    const sidecar = path6.join(dataDir(), "queue", "pending.txt");
+    const sidecar = path7.join(dataDir(), "queue", "pending.txt");
     try {
-      fs5.mkdirSync(path6.dirname(sidecar), { recursive: true });
+      fs5.mkdirSync(path7.dirname(sidecar), { recursive: true });
       atomicWriteBytes(sidecar, Buffer.from(`${paths.join("\n")}
 `, "utf8"));
     } catch {
@@ -10480,6 +11038,12 @@ function postEditHandler(event) {
   const normalized = normalizePath(filePath);
   recordFileEdit(normalized);
   appendDirtyPath(normalized);
+  const editedBasename = path8.basename(normalized);
+  if (/\.(md|mdx|markdown|rst)$/i.test(editedBasename)) {
+    return contextOutput(
+      editedBasename + ' was edited. Use `token-goat section "' + normalized + '::HeadingName"` to re-read a specific section rather than the full file.'
+    );
+  }
   return passOutput();
 }
 registerHook("post_tool_use", postEditHandler, { toolName: "Write" });
@@ -10748,10 +11312,75 @@ function postSkillHandler(event) {
 registerHook("pre_tool_use", preSkillHandler, { toolName: "Skill" });
 registerHook("post_tool_use", postSkillHandler, { toolName: "Skill" });
 
-// src/image_shrink.ts
+// src/hooks_bash.ts
 init_define_import_meta_env();
+
+// src/fingerprint.ts
+init_define_import_meta_env();
+import { createHash } from "node:crypto";
 import * as fs6 from "node:fs";
-import * as path7 from "node:path";
+function fingerprintContent(content) {
+  const hash = createHash("sha256");
+  hash.update(typeof content === "string" ? Buffer.from(content, "utf-8") : content);
+  return hash.digest("hex");
+}
+function fingerprintFile(filePath) {
+  let data;
+  try {
+    data = fs6.readFileSync(filePath);
+  } catch {
+    return null;
+  }
+  return fingerprintContent(data);
+}
+
+// src/hooks_bash.ts
+function extractCommand(event) {
+  const cmd = event.toolInput["command"];
+  return typeof cmd === "string" && cmd.trim() !== "" ? cmd.trim() : void 0;
+}
+function isTscCommand(cmd) {
+  return /^\s*tsc(\s|$)/i.test(cmd);
+}
+function isDevServerCommand(cmd) {
+  return /^\s*(vite\s+dev|next\s+dev|nuxt\s+dev)\b/i.test(cmd);
+}
+function buildRecallHint(cmd, outputId) {
+  const cmdPreview = cmd.length > 60 ? cmd.slice(0, 57) + "..." : cmd;
+  if (isTscCommand(cmd)) {
+    return "Output from a prior `" + cmdPreview + "` run is cached. Use `token-goat bash-output " + outputId + ' --grep "error TS"` to filter TypeScript errors, or `--grep "Cannot find"` for missing module errors.';
+  }
+  if (isDevServerCommand(cmd)) {
+    return "Dev server output cached (`" + cmdPreview + "`). Use `token-goat bash-output " + outputId + ' --tail 20` to see the latest output, or `--grep "error\\|warn"` to filter issues.';
+  }
+  return "Output from a prior `" + cmdPreview + "` run is cached. Use `token-goat bash-output " + outputId + "` (or `--tail 50`, `--grep ERROR`) to re-inspect it without re-running.";
+}
+function preBashHandler(event) {
+  const cmd = extractCommand(event);
+  if (cmd === void 0) return passOutput();
+  const monitoringHint = getMonitoringRecallHint(cmd);
+  if (monitoringHint !== null) {
+    const monCmdHash = fingerprintContent(cmd).slice(0, 16);
+    const monOutputId = getBashOutputId(monCmdHash);
+    if (monOutputId !== null) {
+      const cmdSummary = cmd.length > 60 ? cmd.slice(0, 57) + "..." : cmd;
+      return contextOutput(
+        "Prior output from `" + cmdSummary + "` is cached.\nUse `token-goat bash-output " + monOutputId + " " + monitoringHint + "` to re-inspect without re-running."
+      );
+    }
+  }
+  if (!isBuildCommand(cmd)) return passOutput();
+  const cmdHash = fingerprintContent(cmd).slice(0, 16);
+  const outputId = getBashOutputId(cmdHash);
+  if (outputId === null) return passOutput();
+  return contextOutput(buildRecallHint(cmd, outputId));
+}
+registerHook("pre_tool_use", preBashHandler, { toolName: "Bash" });
+
+// src/image_shrink.ts
+init_define_import_meta_env();
+import * as fs7 from "node:fs";
+import * as path9 from "node:path";
 var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".png",
   ".jpg",
@@ -10778,7 +11407,7 @@ async function loadSharp() {
   return _sharpCache;
 }
 function isImagePath(p) {
-  return IMAGE_EXTENSIONS.has(path7.extname(p).toLowerCase());
+  return IMAGE_EXTENSIONS.has(path9.extname(p).toLowerCase());
 }
 async function shrinkImage(input, opts) {
   const maxDimension = opts?.maxDimension ?? DEFAULT_MAX_DIMENSION;
@@ -10816,7 +11445,7 @@ async function shrinkImage(input, opts) {
 }
 function statSize2(absPath) {
   try {
-    const st = fs6.statSync(absPath);
+    const st = fs7.statSync(absPath);
     return st.isFile() ? st.size : null;
   } catch {
     return null;
@@ -10830,7 +11459,7 @@ async function preReadImageHandler(event) {
   if (size === null || size < DEFAULT_SIZE_THRESHOLD_BYTES) return passOutput();
   let input;
   try {
-    input = fs6.readFileSync(filePath);
+    input = fs7.readFileSync(filePath);
   } catch {
     return passOutput();
   }
@@ -10839,7 +11468,7 @@ async function preReadImageHandler(event) {
   const saved = result.originalBytes - result.shrunkBytes;
   const pct = Math.round(saved / result.originalBytes * 100);
   const dataUrl = `data:image/${result.format};base64,${result.data.toString("base64")}`;
-  const summary = `token-goat shrank ${path7.basename(filePath)}: ${Math.round(result.originalBytes / 1024)}kb -> ${Math.round(result.shrunkBytes / 1024)}kb (${pct}% smaller, ${result.width}x${result.height} ${result.format}).`;
+  const summary = `token-goat shrank ${path9.basename(filePath)}: ${Math.round(result.originalBytes / 1024)}kb -> ${Math.round(result.shrunkBytes / 1024)}kb (${pct}% smaller, ${result.width}x${result.height} ${result.format}).`;
   return contextOutput(`${summary}
 ${dataUrl}`);
 }
@@ -10918,7 +11547,7 @@ async function relay(eventName) {
 
 // src/section_reader.ts
 init_define_import_meta_env();
-import { readFileSync as readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 function parseHeadingSpec(spec) {
   const m = /^(.*?)#(\d+)$/.exec(spec);
   if (m !== null && m[1] !== void 0 && m[2] !== void 0) {
@@ -11000,7 +11629,7 @@ function sectionEndIndex(headers, headerPos, totalLines) {
 function readSection(filePath, headingSpec) {
   let text;
   try {
-    text = readFileSync3(filePath, "utf-8");
+    text = readFileSync5(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -11037,9 +11666,9 @@ function readSection(filePath, headingSpec) {
 
 // src/install.ts
 init_define_import_meta_env();
-import * as fs7 from "node:fs";
+import * as fs8 from "node:fs";
 import * as os2 from "node:os";
-import * as path8 from "node:path";
+import * as path10 from "node:path";
 var HOOK_EVENT_MAP = [
   ["PreToolUse", "pre_tool_use"],
   ["PostToolUse", "post_tool_use"],
@@ -11050,13 +11679,13 @@ function hookCommand(eventArg) {
   return `token-goat hook ${eventArg}`;
 }
 function settingsPath(scope) {
-  const base = scope === "user" ? path8.join(os2.homedir(), ".claude") : path8.join(process.cwd(), ".claude");
-  return path8.join(base, "settings.json");
+  const base = scope === "user" ? path10.join(os2.homedir(), ".claude") : path10.join(process.cwd(), ".claude");
+  return path10.join(base, "settings.json");
 }
 function readSettings(p) {
   let raw;
   try {
-    raw = fs7.readFileSync(p, "utf8");
+    raw = fs8.readFileSync(p, "utf8");
   } catch {
     return {};
   }
@@ -11096,7 +11725,7 @@ function installHooks(scope = "user") {
     return { scope, settingsPath: p, alreadyInstalled: true };
   }
   settings.hooks = hooks;
-  fs7.mkdirSync(path8.dirname(p), { recursive: true });
+  fs8.mkdirSync(path10.dirname(p), { recursive: true });
   atomicWriteText(p, `${JSON.stringify(settings, null, 2)}
 `);
   return { scope, settingsPath: p, alreadyInstalled: false };
@@ -11135,7 +11764,7 @@ function uninstallHooks(scope = "user") {
   } else {
     settings.hooks = hooks;
   }
-  fs7.mkdirSync(path8.dirname(p), { recursive: true });
+  fs8.mkdirSync(path10.dirname(p), { recursive: true });
   atomicWriteText(p, `${JSON.stringify(settings, null, 2)}
 `);
   return true;
@@ -11145,36 +11774,15 @@ function uninstallHooks(scope = "user") {
 init_define_import_meta_env();
 import { spawn } from "node:child_process";
 import * as fs9 from "node:fs";
-import * as path9 from "node:path";
+import * as path11 from "node:path";
 import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
-
-// src/fingerprint.ts
-init_define_import_meta_env();
-import { createHash } from "node:crypto";
-import * as fs8 from "node:fs";
-function fingerprintContent(content) {
-  const hash = createHash("sha256");
-  hash.update(typeof content === "string" ? Buffer.from(content, "utf-8") : content);
-  return hash.digest("hex");
-}
-function fingerprintFile(filePath) {
-  let data;
-  try {
-    data = fs8.readFileSync(filePath);
-  } catch {
-    return null;
-  }
-  return fingerprintContent(data);
-}
-
-// src/worker.ts
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
 function dirtyQueuePathFor(dir) {
-  return path9.join(dir, "queue", "dirty.txt");
+  return path11.join(dir, "queue", "dirty.txt");
 }
 function workerPidPath(dir = dataDir()) {
-  return path9.join(dir, "worker.pid");
+  return path11.join(dir, "worker.pid");
 }
 function getDirtyPathsFor(dir) {
   let raw;
@@ -12683,7 +13291,686 @@ function _buildConfig(raw) {
 
 // src/stats.ts
 init_define_import_meta_env();
-import * as path10 from "node:path";
+import * as path12 from "node:path";
+
+// src/render/stats_renderer.ts
+init_define_import_meta_env();
+
+// src/render/ansi.ts
+init_define_import_meta_env();
+function _colorStream(isatty) {
+  if (process.env["NO_COLOR"]) return false;
+  return isatty;
+}
+function colorStdout() {
+  return _colorStream(process.stdout.isTTY === true);
+}
+var USE_COLOR = colorStdout();
+var _E = "\x1B";
+var RESET = `${_E}[0m`;
+var _ANSI_ESCAPE_RE = /\x1B\[[0-?]*[ -/]*[@-~]|\x1B\].*?(?:\x07|\x1B\\)|\x1B[PX^_].*?\x1B\\|\x1B[@-Z\\\-_]/gs;
+var _PUA_RE = /[\u{E000}-\u{F8FF}\u{F0000}-\u{FFFDD}]/gu;
+function stripAnsi(s) {
+  if (!s.includes("\x1B")) {
+    return s;
+  }
+  const text = s.replace(_ANSI_ESCAPE_RE, "");
+  return text.replace(_PUA_RE, "");
+}
+function fg(r, g, b) {
+  return `${_E}[38;2;${r};${g};${b}m`;
+}
+function vlen(s) {
+  return stripAnsi(s).length;
+}
+function padR(s, w) {
+  return s + " ".repeat(Math.max(0, w - vlen(s)));
+}
+function padL(s, w) {
+  return " ".repeat(Math.max(0, w - vlen(s))) + s;
+}
+function lerpRgb(a, b, t) {
+  return [
+    Math.round(a[0] + (b[0] - a[0]) * t),
+    Math.round(a[1] + (b[1] - a[1]) * t),
+    Math.round(a[2] + (b[2] - a[2]) * t)
+  ];
+}
+var C = {
+  TEXT_PRIMARY: [201, 209, 217],
+  TEXT_BRIGHT: [240, 246, 252],
+  TEXT_MUTED: [125, 133, 144],
+  TEXT_DIM: [72, 79, 88],
+  BG_TILE: [22, 27, 34],
+  TRACK: [28, 35, 41],
+  GREEN1: [31, 77, 44],
+  GREEN2: [46, 160, 67],
+  GREEN3: [63, 185, 80],
+  GREEN4: [86, 211, 100],
+  GREEN5: [126, 231, 135],
+  BLUE: [88, 166, 255],
+  PURPLE: [188, 140, 255],
+  TEAL: [138, 212, 255],
+  ORANGE: [235, 165, 80],
+  YELLOW: [240, 215, 80],
+  RED: [200, 60, 60]
+};
+
+// src/render/stats_renderer.ts
+var _STATS_MESSAGES_FALLBACK = {
+  bytesModeOnlyNote: "tracks bytes, not vision tokens",
+  sessionHintSplitNote: "session_hint shows realized savings; session_hint_overhead shows injected hint cost",
+  insights: {
+    biggestSaver: "Biggest saver  ",
+    mostActive: "Most active    ",
+    tokenLeader: "Token leader   "
+  }
+};
+var _STATS_MESSAGES = _STATS_MESSAGES_FALLBACK;
+var _TERM_W = process.stdout.columns || 100;
+var _CONTENT_W = Math.min(Math.max(_TERM_W, 80), 140);
+var _M = "  ";
+var _COL_NAME = 18;
+var _COL_DATA = 10;
+var _COL_TOKENS = 12;
+var _COL_SHARE = 6;
+var _COL_EVENTS = 6;
+var _COLS_FIXED = _COL_NAME + 1 + 2 + _COL_DATA + 2 + _COL_TOKENS + 2 + _COL_SHARE + 2 + _COL_EVENTS;
+var _BAR_W = Math.max(16, _CONTENT_W - _M.length * 2 - _COLS_FIXED);
+var _RULE = _M + fg(...C.TEXT_DIM) + "\u2500".repeat(_CONTENT_W - _M.length * 2) + RESET;
+var _BYTE_TIERS = [
+  { threshold: 1e15, divisor: 1e15, unit: "PB", color: C.PURPLE },
+  { threshold: 1e12, divisor: 1e12, unit: "TB", color: C.BLUE },
+  { threshold: 1e9, divisor: 1e9, unit: "GB", color: C.TEAL },
+  { threshold: 1e6, divisor: 1e6, unit: "MB", color: C.GREEN4 },
+  { threshold: 1e3, divisor: 1e3, unit: "KB", color: C.TEXT_MUTED },
+  { threshold: 0, divisor: 1, unit: "B", color: C.TEXT_DIM }
+];
+var _TOKEN_TIERS = [
+  { threshold: 1e12, divisor: 1e12, unit: "Tt", color: C.GREEN5 },
+  { threshold: 1e9, divisor: 1e9, unit: "Gt", color: C.TEAL },
+  { threshold: 1e6, divisor: 1e6, unit: "Mt", color: C.PURPLE },
+  { threshold: 1e3, divisor: 1e3, unit: "kt", color: C.BLUE },
+  { threshold: 0, divisor: 1, unit: "t", color: C.TEXT_DIM }
+];
+function _fmtMagnitude(n, tiers, zeroLabel) {
+  if (zeroLabel !== void 0 && n === 0) {
+    return `${fg(...C.TEXT_DIM)}${zeroLabel}${RESET}`;
+  }
+  if (n < 0) {
+    const a = -n;
+    const color = C.TEXT_DIM;
+    for (const tier of tiers) {
+      if (a >= tier.threshold && tier.threshold > 0) {
+        return `${fg(...color)}-${(a / tier.divisor).toLocaleString("en", { maximumFractionDigits: 1 })} ${tier.unit}${RESET}`;
+      }
+    }
+    const lastTier2 = tiers[tiers.length - 1];
+    if (lastTier2) {
+      return `${fg(...color)}-${a} ${lastTier2.unit}${RESET}`;
+    }
+    return `${fg(...color)}-${a}${RESET}`;
+  }
+  for (const tier of tiers) {
+    if (n >= tier.threshold && tier.threshold > 0) {
+      return `${fg(...tier.color)}${(n / tier.divisor).toLocaleString("en", { maximumFractionDigits: 1 })} ${tier.unit}${RESET}`;
+    }
+  }
+  const lastTier = tiers[tiers.length - 1];
+  if (lastTier) {
+    return `${fg(...lastTier.color)}${n} ${lastTier.unit}${RESET}`;
+  }
+  return `${n}${RESET}`;
+}
+function _fmtBytes(n) {
+  return _fmtMagnitude(n, _BYTE_TIERS);
+}
+function _fmtTokens(n) {
+  return _fmtMagnitude(n, _TOKEN_TIERS, "0 t");
+}
+function _fmtPct(fraction) {
+  return `${(fraction * 100).toFixed(1)}%`;
+}
+function _fmtDelta(delta) {
+  if (!delta && delta !== 0) {
+    return "";
+  }
+  const up = (delta ?? 0) >= 0;
+  const color = up ? C.GREEN5 : C.RED;
+  const arrow = up ? "\u2191" : "\u2193";
+  return ` ${fg(...color)}${arrow} ${Math.round(Math.abs(delta ?? 0))}%${RESET}`;
+}
+var _EIGHTHS = ["\u258F", "\u258E", "\u258D", "\u258C", "\u258B", "\u258A", "\u2589"];
+var _BLOCK = "\u2588";
+var _TRACK = "\u2591";
+var _GRADIENT = [C.GREEN1, C.GREEN2, C.GREEN3, C.GREEN4, C.GREEN5];
+function _distribute(total, n) {
+  if (total <= 0 || n <= 0) {
+    return Array(Math.max(0, n)).fill(0);
+  }
+  const base = Math.floor(total / n);
+  const rem = total % n;
+  return Array.from({ length: n }, (_, i) => base + (i >= n - rem ? 1 : 0));
+}
+function _renderBar(fraction, width = _BAR_W) {
+  const f = Math.max(0, Math.min(1, fraction));
+  const raw = f * width;
+  let nFull = Math.floor(raw);
+  const eighths = Math.round((raw - nFull) * 8);
+  if (eighths >= 8) {
+    nFull += 1;
+  }
+  const hasPartial = eighths > 0 && eighths < 8;
+  const nTrack = Math.max(0, width - nFull - (hasPartial ? 1 : 0));
+  const counts = _distribute(nFull, _GRADIENT.length);
+  let bar = counts.map((count, i) => count > 0 ? `${fg(_GRADIENT[i][0], _GRADIENT[i][1], _GRADIENT[i][2])}${_BLOCK.repeat(count)}` : "").join("");
+  if (hasPartial) {
+    const lastGrad = _GRADIENT[_GRADIENT.length - 1];
+    bar += `${fg(lastGrad[0], lastGrad[1], lastGrad[2])}${_EIGHTHS[eighths - 1]}`;
+  }
+  if (nTrack > 0) {
+    bar += `${fg(...C.TRACK)}${_TRACK.repeat(nTrack)}`;
+  }
+  return bar + RESET;
+}
+var _SPARK = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+function _resample(vals, length) {
+  if (vals.length === 0) {
+    return Array(length).fill(0);
+  }
+  if (vals.length === length) {
+    return [...vals];
+  }
+  const result = [];
+  for (let i = 0; i < length; i++) {
+    const src = i / (length - 1 || 1) * (vals.length - 1);
+    const lo = Math.floor(src);
+    const hi = Math.min(vals.length - 1, lo + 1);
+    const t = src - lo;
+    const loVal = vals[lo] ?? 0;
+    const hiVal = vals[hi] ?? 0;
+    result.push(loVal * (1 - t) + hiVal * t);
+  }
+  return result;
+}
+function _renderSparkline(values, width = 8) {
+  const pts = _resample(values, width);
+  const hi = pts.length > 0 ? Math.max(...pts) : 1;
+  const lo = pts.length > 0 ? Math.min(...pts) : 0;
+  const span = hi - lo || 1;
+  const chars = [];
+  for (let i = 0; i < pts.length; i++) {
+    const v = pts[i];
+    if (v === void 0) continue;
+    const idx = Math.min(7, Math.floor((v - lo) / span * 8));
+    const color = lerpRgb(C.GREEN1, C.GREEN5, i / (width - 1 || 1));
+    chars.push(`${fg(color[0], color[1], color[2])}${_SPARK[idx]}`);
+  }
+  return chars.join("") + RESET;
+}
+function _tokenOrByteShare(itemTokens, itemBytes, totalTokens, totalBytes) {
+  if (totalTokens > 0) {
+    return itemTokens / totalTokens;
+  }
+  if (totalBytes > 0) {
+    return itemBytes / totalBytes;
+  }
+  return 0;
+}
+function _barFraction(itemBytes, grossBytes) {
+  return itemBytes > 0 ? itemBytes / grossBytes : 0;
+}
+function _computeShareDenominators(items) {
+  let grossBytesSum = 0;
+  let shareByteSum = 0;
+  let shareTokensSum = 0;
+  for (const item of items) {
+    if (item.bytes > 0) {
+      grossBytesSum += item.bytes;
+    }
+    shareByteSum += Math.abs(item.bytes);
+    shareTokensSum += Math.abs(item.tokens);
+  }
+  return {
+    grossBytes: Math.max(grossBytesSum, 1),
+    shareBytesDenom: Math.max(shareByteSum, 1),
+    shareTokensDenom: shareTokensSum
+  };
+}
+function _absShare(itemBytes, itemTokens, shareBytesDenom, shareTokensDenom) {
+  if (shareTokensDenom === 0) {
+    return itemBytes / shareBytesDenom;
+  }
+  return itemTokens / shareTokensDenom;
+}
+function _sectionHeader(title, subtitle = "") {
+  const sub = subtitle ? `  ${fg(...C.TEXT_MUTED)}${subtitle}${RESET}` : "";
+  return [
+    "",
+    `${_M}${fg(...C.TEXT_BRIGHT)}${title}${RESET}${sub}`,
+    _RULE
+  ];
+}
+function _tableHeader(firstColLabel) {
+  return [
+    _M,
+    padR(`${fg(...C.TEXT_DIM)}${firstColLabel}${RESET}`, _COL_NAME),
+    " ",
+    padR(`${fg(...C.TEXT_DIM)}savings${RESET}`, _BAR_W),
+    "  ",
+    padL(`${fg(...C.TEXT_DIM)}data saved${RESET}`, _COL_DATA),
+    "  ",
+    padL(`${fg(...C.TEXT_DIM)}tokens saved${RESET}`, _COL_TOKENS),
+    "  ",
+    padL(`${fg(...C.TEXT_DIM)}share${RESET}`, _COL_SHARE),
+    "  ",
+    padL(`${fg(...C.TEXT_DIM)}events${RESET}`, _COL_EVENTS)
+  ].join("");
+}
+function _tableRow({
+  name,
+  fraction,
+  bytes,
+  tokens,
+  events,
+  share,
+  bytesModeOnly = false,
+  namePrefix = "",
+  nameColor = C.TEXT_PRIMARY
+}) {
+  const prefixW = vlen(namePrefix);
+  const maxName = _COL_NAME - prefixW;
+  const truncated = name.length > maxName ? name.slice(0, maxName - 1) + "\u2026" : name;
+  const nameStr = padR(`${namePrefix}${fg(...nameColor)}${truncated}${RESET}`, _COL_NAME);
+  const dataStr = padL(_fmtBytes(bytes), _COL_DATA);
+  const tokStr = bytesModeOnly ? padL(`${fg(...C.TEXT_DIM)}\u2014${RESET}`, _COL_TOKENS) : padL(_fmtTokens(tokens), _COL_TOKENS);
+  const sharePct = share * 100;
+  let shareColor;
+  if (sharePct < 0) {
+    shareColor = C.RED;
+  } else if (sharePct >= 50) {
+    shareColor = C.GREEN5;
+  } else if (sharePct >= 10) {
+    shareColor = C.TEXT_PRIMARY;
+  } else {
+    shareColor = C.TEXT_MUTED;
+  }
+  const shareStr = padL(`${fg(...shareColor)}${_fmtPct(share)}${RESET}`, _COL_SHARE);
+  const evStr = padL(`${fg(...C.TEXT_PRIMARY)}${events.toLocaleString()}${RESET}`, _COL_EVENTS);
+  return [_M, nameStr, " ", _renderBar(fraction), "  ", dataStr, "  ", tokStr, "  ", shareStr, "  ", evStr].join("");
+}
+function _renderKpiSection(stats) {
+  const totals = stats.totals;
+  const colW = Math.floor((_CONTENT_W - _M.length * 2) / 3);
+  function card(label, value, delta, spark2) {
+    return [
+      padR(`${fg(C.TEXT_MUTED[0], C.TEXT_MUTED[1], C.TEXT_MUTED[2])}${label}${RESET}`, colW),
+      padR(`${fg(C.TEXT_BRIGHT[0], C.TEXT_BRIGHT[1], C.TEXT_BRIGHT[2])}${value}${RESET}${delta}`, colW),
+      spark2 !== null ? padR(spark2, colW) : padR("", colW)
+    ];
+  }
+  const spark = totals.sparklines;
+  const c1 = card(
+    "events",
+    `${totals.events.toLocaleString()}`,
+    _fmtDelta(totals.events_delta ?? null),
+    spark ? _renderSparkline(spark.events) : null
+  );
+  const c2 = card(
+    "data saved",
+    _fmtBytes(totals.bytes),
+    _fmtDelta(totals.bytes_delta ?? null),
+    spark ? _renderSparkline(spark.bytes) : null
+  );
+  const c3 = card(
+    "tokens saved",
+    _fmtTokens(totals.tokens),
+    _fmtDelta(totals.tokens_delta ?? null),
+    spark ? _renderSparkline(spark.tokens) : null
+  );
+  const border = fg(C.TEXT_DIM[0], C.TEXT_DIM[1], C.TEXT_DIM[2]);
+  const frameBar = "\u2500".repeat(colW * 3 + 2);
+  function framed(content) {
+    return `${_M}${border}\u2502${RESET} ${content} ${border}\u2502${RESET}`;
+  }
+  const lines = [
+    "",
+    `${_M}${border}\u256D${frameBar}\u256E${RESET}`,
+    framed(c1[0] + c2[0] + c3[0]),
+    framed(c1[1] + c2[1] + c3[1])
+  ];
+  if (spark) {
+    lines.push(framed(c1[2] + c2[2] + c3[2]));
+  }
+  lines.push(`${_M}${border}\u2570${frameBar}\u256F${RESET}`);
+  return lines;
+}
+var _KIND_GROUPS = [
+  {
+    label: "Read savings",
+    members: /* @__PURE__ */ new Set([
+      "read_replacement",
+      "section_replacement",
+      "symbol_read",
+      "section_read",
+      "stub_view",
+      "outline",
+      "exports"
+    ])
+  },
+  { label: "Lookups", members: /* @__PURE__ */ new Set(["symbol_lookup", "semantic_search", "map_lookup"]) },
+  {
+    label: "Images",
+    members: /* @__PURE__ */ new Set(["image_shrink", "gdrive_image", "webfetch_image", "image_shrink_skipped"])
+  },
+  {
+    label: "Hints",
+    members: /* @__PURE__ */ new Set([
+      "session_hint",
+      "session_hint_overhead",
+      "read_dedup_hint",
+      "grep_dedup_hint",
+      "diff_hint",
+      "predictive_prefetch_hit",
+      "read_partial_overlap_hint"
+    ])
+  },
+  {
+    label: "Bash",
+    members: /* @__PURE__ */ new Set([
+      "bash_dedup_hint",
+      "bash_output_cached",
+      "bash_output_recall",
+      "bash_output_recall_miss",
+      "bash_dedup_stale",
+      "bash_range_read_hint",
+      "bash_streak_hint",
+      "bash_poll_hint",
+      "env_probe_cache_hit",
+      "git_diff_scope_hint",
+      "dep_list_cache_hit",
+      "bash_read_equiv_already_read",
+      "bash_grep_result_cache_hit",
+      "git_diff_context_trimmed"
+    ])
+  },
+  {
+    label: "Web",
+    members: /* @__PURE__ */ new Set([
+      "web_dedup_hint",
+      "web_output_cached",
+      "web_output_recall",
+      "web_output_recall_miss",
+      "web_dedup_stale"
+    ])
+  },
+  {
+    label: "Compact / Skills",
+    members: /* @__PURE__ */ new Set([
+      "compact_manifest",
+      "compact_assist",
+      "compact_recovery",
+      "skill_body_recall",
+      "skill_compact_served",
+      "skill_cached",
+      "resume_packet",
+      "decision_log"
+    ])
+  }
+];
+function _kindGroupLabel(kind) {
+  if (kind.startsWith("bash_compress:")) {
+    return "Bash";
+  }
+  for (const group of _KIND_GROUPS) {
+    if (group.members.has(kind)) {
+      return group.label;
+    }
+  }
+  return "Other";
+}
+function _groupSeparator(label) {
+  return `${_M}  ${fg(...C.TEXT_DIM)}${label}${RESET}`;
+}
+function _renderByKindSection(stats) {
+  if (stats.by_kind.length === 0) {
+    return [];
+  }
+  const lines = [..._sectionHeader("By kind"), _tableHeader("name")];
+  const { grossBytes, shareBytesDenom, shareTokensDenom } = _computeShareDenominators(stats.by_kind);
+  const kindNames = new Set(stats.by_kind.map((k) => k.kind));
+  const bytesModeKinds = stats.by_kind.filter((k) => k.bytes_mode_only).map((k) => k.kind);
+  function share(k) {
+    if (k.bytes_mode_only) {
+      return k.bytes / shareBytesDenom;
+    }
+    return _absShare(k.bytes, k.tokens, shareBytesDenom, shareTokensDenom);
+  }
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const k of stats.by_kind) {
+    const grp = _kindGroupLabel(k.kind);
+    if (!byGroup.has(grp)) {
+      byGroup.set(grp, []);
+    }
+    byGroup.get(grp).push(k);
+  }
+  for (const grpKinds of byGroup.values()) {
+    grpKinds.sort((a, b) => share(b) - share(a));
+  }
+  let firstGroup = true;
+  for (const group of _KIND_GROUPS) {
+    const groupKinds = byGroup.get(group.label);
+    if (!groupKinds || groupKinds.length === 0) {
+      continue;
+    }
+    if (!firstGroup) {
+      lines.push("");
+    }
+    firstGroup = false;
+    lines.push(_groupSeparator(group.label));
+    for (const k of groupKinds) {
+      const s = share(k);
+      lines.push(
+        _tableRow({
+          name: k.kind,
+          fraction: _barFraction(k.bytes, grossBytes),
+          bytes: k.bytes,
+          tokens: k.tokens,
+          events: k.events,
+          share: s,
+          bytesModeOnly: k.bytes_mode_only ?? false
+        })
+      );
+    }
+  }
+  if (bytesModeKinds.length > 0) {
+    const names = bytesModeKinds.join(", ");
+    lines.push(`${_M}${fg(...C.TEXT_DIM)}i  ${names} ${_STATS_MESSAGES.bytesModeOnlyNote}${RESET}`);
+  }
+  if (kindNames.has("session_hint") && kindNames.has("session_hint_overhead")) {
+    lines.push(`${_M}${fg(...C.TEXT_DIM)}i  ${_STATS_MESSAGES.sessionHintSplitNote}${RESET}`);
+  }
+  return lines;
+}
+var _SOURCE_COLORS = {
+  image: C.PURPLE,
+  hint: C.BLUE,
+  read: C.GREEN4,
+  compact: C.TEAL,
+  bash: C.ORANGE,
+  web: C.YELLOW,
+  other: C.TEXT_MUTED
+};
+function _sourceColor(source) {
+  const color = _SOURCE_COLORS[source];
+  return color || C.TEXT_MUTED;
+}
+function _renderBySourceSection(stats) {
+  if (!stats.by_source || stats.by_source.length === 0) {
+    return [];
+  }
+  const lines = [..._sectionHeader("By source"), _tableHeader("source")];
+  const { grossBytes, shareBytesDenom, shareTokensDenom } = _computeShareDenominators(stats.by_source);
+  function share(s) {
+    return _absShare(s.bytes, s.tokens, shareBytesDenom, shareTokensDenom);
+  }
+  for (const s of [...stats.by_source].sort((a, b) => share(b) - share(a))) {
+    const s_val = share(s);
+    const color = _sourceColor(s.source);
+    lines.push(
+      _tableRow({
+        name: s.source,
+        fraction: _barFraction(s.bytes, grossBytes),
+        bytes: s.bytes,
+        tokens: s.tokens,
+        events: s.events,
+        share: s_val,
+        namePrefix: `${fg(...color)}\u25CF${RESET} `,
+        nameColor: C.TEXT_PRIMARY
+      })
+    );
+  }
+  return lines;
+}
+function _renderByCommandSection(stats) {
+  if (!stats.by_command || stats.by_command.length === 0) {
+    return [];
+  }
+  const lines = [..._sectionHeader("By command"), _tableHeader("command")];
+  const { grossBytes, shareBytesDenom, shareTokensDenom } = _computeShareDenominators(stats.by_command);
+  function share(c) {
+    return _absShare(c.bytes, c.tokens, shareBytesDenom, shareTokensDenom);
+  }
+  for (const c of [...stats.by_command].sort((a, b) => share(b) - share(a))) {
+    const s_val = share(c);
+    lines.push(
+      _tableRow({
+        name: c.command,
+        fraction: _barFraction(c.bytes, grossBytes),
+        bytes: c.bytes,
+        tokens: c.tokens,
+        events: c.events,
+        share: s_val,
+        nameColor: C.TEXT_PRIMARY
+      })
+    );
+  }
+  return lines;
+}
+function _renderByDaySection(stats) {
+  if (stats.by_day.length === 0) {
+    return [];
+  }
+  const lines = [..._sectionHeader("By day"), _tableHeader("date")];
+  function share(d) {
+    return _tokenOrByteShare(d.tokens, d.bytes, stats.totals.tokens, stats.totals.bytes);
+  }
+  for (const d of [...stats.by_day].sort((a, b) => b.date.localeCompare(a.date))) {
+    const s = share(d);
+    lines.push(
+      _tableRow({
+        name: d.date,
+        fraction: s,
+        bytes: d.bytes,
+        tokens: d.tokens,
+        events: d.events,
+        share: s
+      })
+    );
+  }
+  return lines;
+}
+var _PROJECT_COLORS = [C.PURPLE, C.TEAL, C.BLUE, C.GREEN4, C.TEXT_MUTED];
+function _hashColor(hashStr) {
+  let n = 0;
+  for (const c of hashStr) {
+    n += c.charCodeAt(0);
+  }
+  return _PROJECT_COLORS[n % _PROJECT_COLORS.length] ?? C.TEXT_MUTED;
+}
+function _renderByProjectSection(stats) {
+  if (stats.by_project.length === 0) {
+    return [];
+  }
+  const projectTotalBytes = stats.by_project.reduce((s, p) => s + p.bytes, 0);
+  const projectTotalTokens = stats.by_project.reduce((s, p) => s + p.tokens, 0);
+  const lines = [..._sectionHeader(`By project (top ${stats.by_project.length})`), _tableHeader("project")];
+  function share(p) {
+    return _tokenOrByteShare(p.tokens, p.bytes, projectTotalTokens, projectTotalBytes);
+  }
+  for (const p of [...stats.by_project].sort((a, b) => share(b) - share(a))) {
+    const s = share(p);
+    const color = _hashColor(p.hash);
+    lines.push(
+      _tableRow({
+        name: p.project,
+        fraction: s,
+        bytes: p.bytes,
+        tokens: p.tokens,
+        events: p.events,
+        share: s,
+        namePrefix: `${fg(...color)}\u25CF${RESET} `,
+        nameColor: C.TEXT_PRIMARY
+      })
+    );
+    lines.push(`${_M}  ${fg(...C.TEXT_DIM)}\u2514\u2500 ${p.hash}  ${stripAnsi(p.path)}${RESET}`);
+  }
+  return lines;
+}
+function _renderInsightsSection(stats) {
+  const lines = [..._sectionHeader("Insights")];
+  const bullet = `${fg(...C.GREEN3)}\u25B8${RESET}`;
+  function dim(s) {
+    return `${fg(...C.TEXT_MUTED)}${s}${RESET}`;
+  }
+  const topKind = stats.by_kind.reduce((max, k) => k.bytes > (max?.bytes || -Infinity) ? k : max, stats.by_kind[0]);
+  if (topKind) {
+    const share = stats.totals.bytes > 0 ? topKind.bytes / stats.totals.bytes : 0;
+    lines.push(
+      `${_M}${bullet} ${dim(_STATS_MESSAGES.insights.biggestSaver)}${fg(...C.TEXT_PRIMARY)}${topKind.kind}${RESET}${dim(" \u2014 ")}${fg(...C.GREEN5)}${_fmtPct(share)}${RESET}${dim(` of saved data across ${topKind.events.toLocaleString()} events`)}`
+    );
+  }
+  const topDay = stats.by_day.reduce((max, d) => d.events > (max?.events || -Infinity) ? d : max, stats.by_day[0]);
+  if (topDay) {
+    lines.push(
+      `${_M}${bullet} ${dim(_STATS_MESSAGES.insights.mostActive)}${fg(...C.TEXT_PRIMARY)}${topDay.date}${RESET}${dim(" \u2014 ")}${topDay.events.toLocaleString()} events, ${_fmtBytes(topDay.bytes)}${dim(" saved")}`
+    );
+  }
+  const tokenKinds = stats.by_kind.filter((k) => !k.bytes_mode_only);
+  const topToken = tokenKinds.reduce((max, k) => k.tokens > (max?.tokens || -Infinity) ? k : max, tokenKinds[0]);
+  if (topToken) {
+    lines.push(
+      `${_M}${bullet} ${dim(_STATS_MESSAGES.insights.tokenLeader)}${fg(...C.TEXT_PRIMARY)}${topToken.kind}${RESET}${dim(" \u2014 ")}${_fmtTokens(topToken.tokens)}${dim(` saved in ${topToken.events.toLocaleString()} events`)}`
+    );
+  }
+  return lines;
+}
+function _renderHeader(stats) {
+  let line = `${_M}${fg(...C.TEXT_BRIGHT)}token-goat${RESET}`;
+  if (stats.version) {
+    line += `  ${fg(...C.TEXT_MUTED)}v${stats.version}${RESET}`;
+  }
+  if (stats.window_label) {
+    line += `  ${fg(...C.TEXT_DIM)}\xB7  ${stats.window_label}${RESET}`;
+  }
+  return [line];
+}
+function renderStats(stats) {
+  const sections = [
+    _renderHeader(stats),
+    _renderKpiSection(stats),
+    _renderByKindSection(stats),
+    _renderBySourceSection(stats),
+    _renderByCommandSection(stats),
+    _renderByDaySection(stats),
+    _renderByProjectSection(stats),
+    _renderInsightsSection(stats),
+    [""]
+  ];
+  return sections.flatMap((s) => s).join("\n");
+}
+
+// src/stats.ts
 var SOURCE_IMAGE = "image";
 var SOURCE_HINT = "hint";
 var SOURCE_READ = "read";
@@ -12692,6 +13979,7 @@ var SOURCE_WEB = "web";
 var SOURCE_MCP = "mcp";
 var SOURCE_SKILL = "skill";
 var SOURCE_OTHER = "other";
+var _BYTES_MODE_ONLY_KINDS = /* @__PURE__ */ new Set(["webfetch_image", "gdrive_image"]);
 var KIND_TO_SOURCE = {
   image_shrink: SOURCE_IMAGE,
   image_shrink_cache_hit: SOURCE_IMAGE,
@@ -12734,7 +14022,15 @@ var COMMAND_KINDS = {
   skeleton: /* @__PURE__ */ new Set(["stub_view"]),
   refs: /* @__PURE__ */ new Set(["symbol_read"]),
   map: /* @__PURE__ */ new Set(["map_lookup"]),
-  changed: /* @__PURE__ */ new Set(["changed_lookup"])
+  changed: /* @__PURE__ */ new Set(["changed_lookup"]),
+  npm: /* @__PURE__ */ new Set([
+    "bash_compress:npm_install",
+    "bash_compress:npm_ci",
+    "bash_compress:npm_audit",
+    "bash_compress:npm_ls",
+    "bash_compress:npm_outdated",
+    "bash_compress:npx"
+  ])
 };
 var OVERHEAD_SUFFIX = "_overhead";
 function kindToSource(kind) {
@@ -12759,7 +14055,7 @@ function incBucket(bucket, bytesSaved, tokensSaved) {
   bucket.tokens_saved += tokensSaved;
 }
 function getGlobalDb() {
-  const dbPath = path10.join(dataDir(), "global.db");
+  const dbPath = path12.join(dataDir(), "global.db");
   return getDb(dbPath);
 }
 function summarize(windowDays = 30, testDb) {
@@ -12833,12 +14129,7 @@ function summarize(windowDays = 30, testDb) {
     window_days: windowDays
   };
 }
-function renderStats(opts) {
-  const summary = summarize(opts?.windowDays ?? 30);
-  if (summary.total_events === 0) {
-    console.log("No stats recorded yet.");
-    return;
-  }
+function _plainTextStats(summary) {
   const fmtBytes = (n) => {
     if (n < 1024) return `${n}B`;
     if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
@@ -12878,11 +14169,71 @@ function renderStats(opts) {
   }
   console.log(lines.join("\n"));
 }
+function renderStats2(opts) {
+  const windowDays = opts?.windowDays ?? 30;
+  const summary = summarize(windowDays);
+  if (summary.total_events === 0) {
+    console.log("No stats recorded yet.");
+    return;
+  }
+  const useTty = process.stdout.isTTY === true && !process.env["NO_COLOR"];
+  if (!useTty) {
+    _plainTextStats(summary);
+    return;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const periodStart = windowDays > 0 ? new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1e3) : /* @__PURE__ */ new Date(0);
+  const sparkDays = [...summary.by_day].reverse().slice(-30);
+  const sparklines = sparkDays.length > 1 ? {
+    events: sparkDays.map((d) => d.events),
+    bytes: sparkDays.map((d) => d.bytes_saved),
+    tokens: sparkDays.map((d) => d.tokens_saved)
+  } : null;
+  const statsData = {
+    period_start: periodStart,
+    period_end: now,
+    version: VERSION,
+    window_label: windowDays > 0 ? `last ${windowDays} days` : "all time",
+    totals: {
+      events: summary.total_events,
+      bytes: summary.total_bytes_saved,
+      tokens: summary.total_tokens_saved,
+      sparklines
+    },
+    by_kind: Object.entries(summary.by_kind).map(([kind, bucket]) => ({
+      kind,
+      bytes: bucket.bytes_saved,
+      tokens: bucket.tokens_saved,
+      events: bucket.events,
+      bytes_mode_only: _BYTES_MODE_ONLY_KINDS.has(kind)
+    })).sort((a, b) => b.bytes - a.bytes),
+    by_day: summary.by_day.map((d) => ({
+      date: d.date,
+      bytes: d.bytes_saved,
+      tokens: d.tokens_saved,
+      events: d.events
+    })),
+    by_project: [],
+    by_source: Object.entries(summary.by_source).filter(([, b]) => b.events > 0).map(([source, bucket]) => ({
+      source,
+      bytes: bucket.bytes_saved,
+      tokens: bucket.tokens_saved,
+      events: bucket.events
+    })).sort((a, b) => b.bytes - a.bytes),
+    by_command: summary.by_command.map((c) => ({
+      command: c.command,
+      bytes: c.bytes_saved,
+      tokens: c.tokens_saved,
+      events: c.events
+    }))
+  };
+  process.stdout.write(renderStats(statsData) + "\n");
+}
 
 // src/cli_doctor.ts
 init_define_import_meta_env();
 import * as fs12 from "fs";
-import * as path11 from "path";
+import * as path13 from "path";
 import { execSync } from "child_process";
 function checkWorkerRunning() {
   try {
@@ -12893,7 +14244,7 @@ function checkWorkerRunning() {
   }
 }
 function checkDbExists(dataDir2) {
-  const dbPath = path11.join(dataDir2, "index.db");
+  const dbPath = path13.join(dataDir2, "index.db");
   if (!fs12.existsSync(dbPath)) {
     return {
       name: "Database",
@@ -12966,9 +14317,9 @@ function runDoctor(dataDir2, configPath2) {
   results.push(checkInstall());
   results.push(checkWorkerRunning() ? { name: "Worker", status: "ok", message: "running" } : { name: "Worker", status: "warn", message: "not running" });
   const homeDir = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  const actualDataDir = dataDir2 || path11.join(homeDir, ".token-goat");
+  const actualDataDir = dataDir2 || path13.join(homeDir, ".token-goat");
   results.push(checkDbExists(actualDataDir));
-  const actualConfigPath = configPath2 || path11.join(actualDataDir, "config.json");
+  const actualConfigPath = configPath2 || path13.join(actualDataDir, "config.json");
   results.push(checkConfigValid(actualConfigPath));
   results.push(checkDiskSpace(actualDataDir));
   return results;
@@ -13258,7 +14609,7 @@ function cmdWorkerStatus() {
   out(isWorkerRunning() ? "Worker is running." : "Worker is not running.");
 }
 function cmdStats() {
-  renderStats({ windowDays: 30 });
+  renderStats2({ windowDays: 30 });
 }
 function cmdDoctor() {
   const code = runDoctorAndExit();
@@ -13266,14 +14617,12 @@ function cmdDoctor() {
     throw new CliError("doctor checks failed");
   }
 }
-function cmdBashOutput(id, opts) {
-  const entry = getBashOutput(id);
-  if (entry === null) {
-    throw new CliError(`no cached bash output for id: ${id}`);
-  }
-  let content = entry.output;
+function _applyFiltersAndPrint(content, opts) {
   if (opts.grep !== void 0) {
-    const pattern = opts.grep;
+    let pattern = opts.grep;
+    if (pattern.startsWith("-E ") || pattern.startsWith("--extended-regexp ")) {
+      pattern = pattern.replace(/^(?:-E\s+|--extended-regexp\s+)/, "");
+    }
     try {
       const re = new RegExp(pattern);
       content = content.split(/\r?\n/).filter((line) => re.test(line)).join("\n");
@@ -13294,6 +14643,26 @@ function cmdBashOutput(id, opts) {
   }
   out(result.join("\n"));
 }
+function cmdBashOutput(id, opts) {
+  if (opts.file !== void 0) {
+    let content;
+    try {
+      content = fs13.readFileSync(opts.file, "utf-8");
+    } catch {
+      throw new CliError(`cannot read file: ${opts.file}`);
+    }
+    _applyFiltersAndPrint(content, opts);
+    return;
+  }
+  if (id === void 0) {
+    throw new CliError("provide an <id> or --file <path>");
+  }
+  const entry = getBashOutput(id);
+  if (entry === null) {
+    throw new CliError(`no cached bash output for id: ${id}`);
+  }
+  _applyFiltersAndPrint(entry.output, opts);
+}
 async function cmdSkillBody(name, opts) {
   const filePath = await getSkillFilePath(name);
   if (filePath === null) {
@@ -13445,7 +14814,7 @@ function buildProgram() {
   worker.command("status").description("check if the indexer is running").action(guard(cmdWorkerStatus));
   program2.command("stats").description("show session statistics").action(guard(cmdStats));
   program2.command("doctor").description("diagnose token-goat health").action(guard(cmdDoctor));
-  program2.command("bash-output <id>").description("retrieve cached bash output by ID").option("--head <n>", "show first N lines").option("--tail <n>", "show last N lines").option("--grep <pattern>", "filter lines matching regex").action(guard(cmdBashOutput));
+  program2.command("bash-output [id]").description("retrieve cached bash output by ID or file").option("--head <n>", "show first N lines").option("--tail <n>", "show last N lines").option("--grep <pattern>", "filter lines matching regex").option("--file <path>", "read from raw output file instead of cache").action(guard(cmdBashOutput));
   program2.command("skill-body <name>").description("retrieve a skill's cached body").option("-c, --compact", "print compact slice instead of full body").action(guard(cmdSkillBody));
   program2.command("skill-compact <name>").description("regenerate and cache compact slice for a skill").action(guard(cmdSkillCompact));
   program2.command("skill-list").description("list all cached skills with token counts").option("-j, --json", "output as JSON").option("--session-id <id>", "filter by session").action(guard(cmdSkillList));