token-goat 2.9.18 → 2.9.20

package/dist/token-goat-chunk-ZHFM4DHJ.mjs

@@ -0,0 +1,324 @@
+import { createRequire as __cjsRequire } from 'node:module';
+const require = __cjsRequire(import.meta.url);
+import {
+  classifyContent,
+  guardDivisor,
+  stripAnsiEscapes
+} from "./token-goat-chunk-K5XPIUVB.mjs";
+import {
+  safeSlice
+} from "./token-goat-chunk-6LJNM4ZZ.mjs";
+import {
+  displaySafeText
+} from "./token-goat-chunk-NMTKNYGF.mjs";
+import {
+  init_define_import_meta_env
+} from "./token-goat-chunk-A37V4PBF.mjs";
+
+// src/claude_config_dir.ts
+init_define_import_meta_env();
+import * as os from "node:os";
+import * as path from "node:path";
+function claudeConfigDir(homeDir = os.homedir()) {
+  const override = process.env["CLAUDE_CONFIG_DIR"];
+  if (override !== void 0 && override !== "") return override;
+  return path.join(homeDir, ".claude");
+}
+
+// src/overflow_guard.ts
+init_define_import_meta_env();
+function estimateTokensFromLength(length, cls = "text") {
+  return Math.max(1, Math.floor(Math.max(0, length) / guardDivisor(cls)) + 1);
+}
+function estimateTokens(text) {
+  const stripped = stripAnsiEscapes(text);
+  return estimateTokensFromLength(stripped.length, classifyContent(stripped));
+}
+function trimToBudget(text, budgetTokens, command) {
+  const markerMarginTokens = 64;
+  const strippedAll = stripAnsiEscapes(text);
+  const contentClass = classifyContent(strippedAll);
+  const totalTokens = estimateTokensFromLength(strippedAll.length, contentClass);
+  if (totalTokens <= budgetTokens) {
+    return text;
+  }
+  const lines = text.split("\n");
+  if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+  const totalLines = lines.length;
+  const bodyBudget = Math.max(1, budgetTokens - markerMarginTokens);
+  const charBudget = bodyBudget * guardDivisor(contentClass);
+  const kept = [];
+  let used = 0;
+  for (const ln of lines) {
+    const stripped = stripAnsiEscapes(ln);
+    const cost = ln.length + 1;
+    if (kept.length === 0 && cost > charBudget) {
+      const truncated = safeSlice(stripped, charBudget);
+      kept.push(truncated);
+      break;
+    }
+    if (kept.length > 0 && used + cost > charBudget) {
+      break;
+    }
+    kept.push(ln);
+    used += cost;
+  }
+  const shown = kept.length;
+  const hint = getHintFor(command);
+  const marker = `[token-goat: output capped at ~${budgetTokens} tokens to protect context \u2014 showing ${shown} of ${totalLines} lines. ${hint}]`;
+  return kept.join("\n") + "\n" + marker;
+}
+function capJsonRows(items, budgetTokens) {
+  const totalCount = items.length;
+  const charBudget = Math.max(1, budgetTokens * guardDivisor());
+  const kept = [];
+  let used = 0;
+  for (const item of items) {
+    const cost = JSON.stringify(item).length + 2;
+    if (kept.length > 0 && used + cost > charBudget) break;
+    kept.push(item);
+    used += cost;
+  }
+  return { items: kept, truncated: kept.length < totalCount, totalCount };
+}
+function getHintFor(command) {
+  const cmd = (command || "").toLowerCase().trim();
+  if (cmd === "symbol") {
+    return "Request a specific method (file.py::Class.method) or use --json for structured access.";
+  }
+  if (cmd === "heading" || cmd === "section") {
+    return "Request a narrower sub-heading, e.g. 'doc.md::Section#2'.";
+  }
+  if (cmd === "lines") {
+    return "Request a smaller line range, e.g. 'file.py@100-150'.";
+  }
+  if (cmd === "bash-output" || cmd === "web-output") {
+    return "Use --grep PATTERN, --section HEADING, or --tail N to narrow the cached output.";
+  }
+  if (cmd === "semantic") {
+    return "Narrow your query text or pass --limit to reduce the number of matches returned.";
+  }
+  return "Narrow your query or raise overflow_guard max_tokens in config.";
+}
+
+// src/resident_context.ts
+init_define_import_meta_env();
+import * as fs from "node:fs";
+var LARGE_TASK_LIST_BYTES = 2e4;
+var LARGE_SKILL_BODY_BYTES = 2e4;
+var SKILL_BODY_REPEAT_THRESHOLD = 2;
+var RESIDENT_TAIL_MAX_BYTES = 1048576;
+function createResidentContextStats() {
+  return {
+    attachmentsByType: /* @__PURE__ */ new Map(),
+    latestTaskList: null,
+    taskReminderCount: 0,
+    taskReminderBytes: 0,
+    skillBodies: /* @__PURE__ */ new Map(),
+    compactionCount: 0
+  };
+}
+function bump(map, key, bytes) {
+  const entry = map.get(key);
+  if (entry === void 0) map.set(key, { count: 1, bytes });
+  else {
+    entry.count += 1;
+    entry.bytes += bytes;
+  }
+}
+function messageText(message) {
+  if (message === null || typeof message !== "object") return "";
+  const content = message["content"];
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  let out = "";
+  for (const block of content) {
+    if (block === null || typeof block !== "object") continue;
+    const text = block["text"];
+    if (typeof text === "string") out += text;
+  }
+  return out;
+}
+function skillNameFromBody(text) {
+  const dir = /^Base directory for this skill:\s*(.+?)\s*$/m.exec(text);
+  if (dir?.[1] !== void 0) {
+    const segments = dir[1].split(/[\\/]/).filter((s) => s.length > 0);
+    const last = segments[segments.length - 1];
+    if (last !== void 0 && last.length > 0) return last;
+  }
+  const heading = /^#\s+(.+?)\s*$/m.exec(text);
+  if (heading?.[1] !== void 0 && heading[1].length > 0) return heading[1];
+  return null;
+}
+function readTaskList(attachment, bytes) {
+  const snapshot = {
+    bytes,
+    itemCount: typeof attachment["itemCount"] === "number" ? attachment["itemCount"] : 0,
+    completed: 0,
+    inProgress: 0,
+    pending: 0,
+    descriptionBytes: 0,
+    completedDescriptionBytes: 0
+  };
+  const content = attachment["content"];
+  if (!Array.isArray(content)) return snapshot;
+  if (content.length > snapshot.itemCount) snapshot.itemCount = content.length;
+  for (const item of content) {
+    if (item === null || typeof item !== "object") continue;
+    const record = item;
+    const status = typeof record["status"] === "string" ? record["status"] : "";
+    const description = typeof record["description"] === "string" ? record["description"] : "";
+    snapshot.descriptionBytes += description.length;
+    if (status === "completed") {
+      snapshot.completed += 1;
+      snapshot.completedDescriptionBytes += description.length;
+    } else if (status === "in_progress") snapshot.inProgress += 1;
+    else if (status === "pending") snapshot.pending += 1;
+  }
+  return snapshot;
+}
+function collectInvokedSkills(acc, record) {
+  const skills = record["skills"];
+  if (!Array.isArray(skills)) return;
+  for (const entry of skills) {
+    if (entry === null || typeof entry !== "object") continue;
+    const skill = entry;
+    const content = skill["content"];
+    if (typeof content !== "string" || content.length < LARGE_SKILL_BODY_BYTES) continue;
+    const name = skillName(skill);
+    if (name !== null) bump(acc.skillBodies, name, content.length);
+  }
+}
+function skillName(skill) {
+  const name = skill["name"];
+  if (typeof name === "string" && name.trim() !== "") return name.trim();
+  const path2 = skill["path"];
+  if (typeof path2 !== "string") return null;
+  const segments = path2.split(/[\\/]/).filter((part) => part !== "");
+  const last = segments[segments.length - 1];
+  return last === void 0 || last === "" ? null : last;
+}
+function accumulateResidentLine(acc, parsed, bytes) {
+  try {
+    if (parsed === null || typeof parsed !== "object") return;
+    const line = parsed;
+    if (line["type"] === "system" && line["subtype"] === "compact_boundary") acc.compactionCount += 1;
+    const attachment = line["attachment"];
+    if (attachment !== null && typeof attachment === "object") {
+      const record = attachment;
+      const type = typeof record["type"] === "string" ? record["type"] : "unknown";
+      bump(acc.attachmentsByType, type, bytes);
+      if (type === "task_reminder") {
+        acc.taskReminderCount += 1;
+        acc.taskReminderBytes += bytes;
+        acc.latestTaskList = readTaskList(record, bytes);
+      }
+      if (type === "invoked_skills") collectInvokedSkills(acc, record);
+    }
+    if (line["isMeta"] === true && line["type"] === "user") {
+      const text = messageText(line["message"]);
+      if (text.length >= LARGE_SKILL_BODY_BYTES) {
+        const skill = skillNameFromBody(text);
+        if (skill !== null) bump(acc.skillBodies, skill, text.length);
+      }
+    }
+  } catch {
+  }
+}
+function summarizeResidentContext(acc) {
+  const attachmentClasses = [...acc.attachmentsByType.entries()].map(([type, v]) => ({ type, count: v.count, bytes: v.bytes })).sort((a, b) => b.bytes - a.bytes || a.type.localeCompare(b.type));
+  const repeatedSkillBodies = [...acc.skillBodies.entries()].filter(([, v]) => v.count >= SKILL_BODY_REPEAT_THRESHOLD).map(([skill, v]) => ({ skill, count: v.count, bytes: v.bytes })).sort((a, b) => b.bytes - a.bytes || a.skill.localeCompare(b.skill));
+  return {
+    attachmentClasses,
+    totalAttachmentBytes: attachmentClasses.reduce((n, c) => n + c.bytes, 0),
+    latestTaskList: acc.latestTaskList,
+    taskReminderCount: acc.taskReminderCount,
+    taskReminderBytes: acc.taskReminderBytes,
+    repeatedSkillBodies,
+    compactionCount: acc.compactionCount
+  };
+}
+function formatBytes(bytes) {
+  if (bytes >= 1e6) return `${(bytes / 1048576).toFixed(1)} MB`;
+  if (bytes >= 1e3) return `${Math.round(bytes / 1024)} KB`;
+  return `${bytes} B`;
+}
+function formatTokenEstimate(tokens) {
+  return tokens >= 1e3 ? `${Math.round(tokens / 1e3)}K` : String(tokens);
+}
+function taskListPruneHint(snapshot) {
+  if (snapshot === null) return null;
+  if (snapshot.bytes < LARGE_TASK_LIST_BYTES) return null;
+  if (snapshot.completed === 0) return null;
+  const tokens = formatTokenEstimate(estimateTokensFromLength(snapshot.bytes));
+  const prunable = formatBytes(snapshot.completedDescriptionBytes);
+  return `Your task list is ${formatBytes(snapshot.bytes)} (~${tokens} tok est) and is re-injected in full whenever it changes; ${snapshot.completed} of ${snapshot.itemCount} items are already completed and their descriptions alone are ${prunable}. Prune completed items or shorten their descriptions with TaskUpdate. Check ownership first if other agents share this list.`;
+}
+function repeatedSkillBodyHint(injections) {
+  const worst = injections[0];
+  if (worst === void 0) return null;
+  if (worst.count < SKILL_BODY_REPEAT_THRESHOLD || worst.bytes < LARGE_SKILL_BODY_BYTES) return null;
+  const skill = displaySafeText(worst.skill);
+  const tokens = formatTokenEstimate(estimateTokensFromLength(worst.bytes));
+  return `The \`${skill}\` skill body has been injected ${worst.count} times this session (${formatBytes(worst.bytes)} total, ~${tokens} tok est). Slash expansion and the Skill tool both send the whole body every time, and no hook can intercept either. If it is already loaded, work from it instead of re-invoking; to reread one part, use \`token-goat skill-section ${skill} '<heading>'\`.`;
+}
+function readTranscriptTail(transcriptPath, maxBytes = RESIDENT_TAIL_MAX_BYTES) {
+  let fd = null;
+  try {
+    const stat = fs.statSync(transcriptPath);
+    if (!stat.isFile() || stat.size === 0) return [];
+    const start = Math.max(0, stat.size - maxBytes);
+    const length = stat.size - start;
+    fd = fs.openSync(transcriptPath, "r");
+    const buf = Buffer.allocUnsafe(length);
+    const read = fs.readSync(fd, buf, 0, length, start);
+    const lines = buf.subarray(0, read).toString("utf8").split("\n");
+    if (start > 0) lines.shift();
+    return lines;
+  } catch {
+    return [];
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+      }
+    }
+  }
+}
+function lineMayCarryResidentSignal(line) {
+  return line.includes('"task_reminder"') || line.includes('"compact_boundary"') || line.includes('"invoked_skills"') || line.includes('"isMeta"');
+}
+function accumulateResidentLines(lines) {
+  const acc = createResidentContextStats();
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    accumulateResidentLine(acc, parsed, trimmed.length);
+  }
+  return acc;
+}
+
+export {
+  claudeConfigDir,
+  estimateTokensFromLength,
+  estimateTokens,
+  trimToBudget,
+  capJsonRows,
+  createResidentContextStats,
+  accumulateResidentLine,
+  summarizeResidentContext,
+  formatBytes,
+  formatTokenEstimate,
+  taskListPruneHint,
+  repeatedSkillBodyHint,
+  readTranscriptTail,
+  lineMayCarryResidentSignal,
+  accumulateResidentLines
+};

package/dist/token-goat-hook.mjs

@@ -2,21 +2,27 @@ import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
   relayInProcess
-} from "./token-goat-chunk-WFX2V3OF.mjs";
-import "./token-goat-chunk-RHHFEXKF.mjs";
-import "./token-goat-chunk-V3ZWBEHM.mjs";
-import "./token-goat-chunk-BFEWOMA3.mjs";
-import "./token-goat-chunk-CTOYJ232.mjs";
-import "./token-goat-chunk-HPOFR6QX.mjs";
+} from "./token-goat-chunk-Z4ALQADF.mjs";
+import "./token-goat-chunk-ITWYDOKP.mjs";
+import "./token-goat-chunk-I5PQRHFE.mjs";
+import "./token-goat-chunk-BQIC3AVL.mjs";
+import "./token-goat-chunk-VSJGPEBB.mjs";
+import "./token-goat-chunk-DPHJU3P7.mjs";
+import "./token-goat-chunk-PAVWB4L4.mjs";
+import "./token-goat-chunk-SP5QR2HN.mjs";
+import "./token-goat-chunk-KT75DZK4.mjs";
+import "./token-goat-chunk-ZHFM4DHJ.mjs";
+import "./token-goat-chunk-SL454EN5.mjs";
+import "./token-goat-chunk-K5XPIUVB.mjs";
 import "./token-goat-chunk-3BTK54F3.mjs";
-import "./token-goat-chunk-W3E65QOW.mjs";
-import "./token-goat-chunk-I67CPTDD.mjs";
-import "./token-goat-chunk-L7VCX33I.mjs";
-import "./token-goat-chunk-CA6V36KW.mjs";
+import "./token-goat-chunk-ERGHDBC6.mjs";
+import "./token-goat-chunk-K3ZNBN4U.mjs";
+import "./token-goat-chunk-T63VHOL3.mjs";
+import "./token-goat-chunk-74ADIZZX.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import "./token-goat-chunk-OSUFN2FV.mjs";
-import "./token-goat-chunk-QIDLJGXZ.mjs";
-import "./token-goat-chunk-ERTXEKB6.mjs";
+import "./token-goat-chunk-6LJNM4ZZ.mjs";
+import "./token-goat-chunk-NMTKNYGF.mjs";
 import "./token-goat-chunk-Y4AFKTHK.mjs";
 import "./token-goat-chunk-GMOUBOX4.mjs";
 import "./token-goat-chunk-RRNZMM3A.mjs";

package/dist/token-goat.core.mjs

@@ -2,34 +2,43 @@ import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
   run
-} from "./token-goat-chunk-LTYWLKAG.mjs";
-import "./token-goat-chunk-QML7ITHJ.mjs";
-import "./token-goat-chunk-H3FONFBO.mjs";
-import "./token-goat-chunk-LMFO66YD.mjs";
-import "./token-goat-chunk-V3ZWBEHM.mjs";
-import "./token-goat-chunk-BFEWOMA3.mjs";
-import "./token-goat-chunk-CTOYJ232.mjs";
-import "./token-goat-chunk-HPOFR6QX.mjs";
+} from "./token-goat-chunk-2Q3N5KUQ.mjs";
+import "./token-goat-chunk-ONMU7BON.mjs";
+import "./token-goat-chunk-EUZKG7ZO.mjs";
+import "./token-goat-chunk-W6QYCWAT.mjs";
+import "./token-goat-chunk-3VTJC7KU.mjs";
+import "./token-goat-chunk-MNJWG2ZO.mjs";
+import "./token-goat-chunk-DA43OE7L.mjs";
+import "./token-goat-chunk-I5PQRHFE.mjs";
+import "./token-goat-chunk-BQIC3AVL.mjs";
+import "./token-goat-chunk-VSJGPEBB.mjs";
+import "./token-goat-chunk-DPHJU3P7.mjs";
+import "./token-goat-chunk-PAVWB4L4.mjs";
+import "./token-goat-chunk-SP5QR2HN.mjs";
+import "./token-goat-chunk-KT75DZK4.mjs";
+import "./token-goat-chunk-ZHFM4DHJ.mjs";
+import "./token-goat-chunk-SL454EN5.mjs";
+import "./token-goat-chunk-K5XPIUVB.mjs";
 import "./token-goat-chunk-LKSXAMJB.mjs";
-import "./token-goat-chunk-UENEL6KX.mjs";
-import "./token-goat-chunk-ARNRFR6M.mjs";
-import "./token-goat-chunk-LA3O4JGD.mjs";
-import "./token-goat-chunk-EPXNOKIV.mjs";
+import "./token-goat-chunk-PTW22MRC.mjs";
+import "./token-goat-chunk-DNAF26L4.mjs";
+import "./token-goat-chunk-ODF7H7WS.mjs";
+import "./token-goat-chunk-P4XBHZXU.mjs";
 import "./token-goat-chunk-3BTK54F3.mjs";
-import "./token-goat-chunk-7VLWNQDQ.mjs";
+import "./token-goat-chunk-T46UKRFM.mjs";
 import "./token-goat-chunk-XTQAOTSO.mjs";
 import "./token-goat-chunk-AH6QILZM.mjs";
-import "./token-goat-chunk-GRI6HWX3.mjs";
-import "./token-goat-chunk-W3E65QOW.mjs";
-import "./token-goat-chunk-I67CPTDD.mjs";
-import "./token-goat-chunk-L7VCX33I.mjs";
-import "./token-goat-chunk-CA6V36KW.mjs";
+import "./token-goat-chunk-MUJV7BR3.mjs";
+import "./token-goat-chunk-ERGHDBC6.mjs";
+import "./token-goat-chunk-K3ZNBN4U.mjs";
+import "./token-goat-chunk-T63VHOL3.mjs";
+import "./token-goat-chunk-74ADIZZX.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import "./token-goat-chunk-OSUFN2FV.mjs";
 import {
   installEpipeGuard
-} from "./token-goat-chunk-QIDLJGXZ.mjs";
-import "./token-goat-chunk-ERTXEKB6.mjs";
+} from "./token-goat-chunk-6LJNM4ZZ.mjs";
+import "./token-goat-chunk-NMTKNYGF.mjs";
 import "./token-goat-chunk-Y4AFKTHK.mjs";
 import "./token-goat-chunk-GMOUBOX4.mjs";
 import "./token-goat-chunk-RRNZMM3A.mjs";

package/docs/C4_RUNTIME_ARCHITECTURE.md

@@ -191,7 +191,7 @@ flowchart TB
     subgraph ParserAdapters ["Parser Language Adapters"]
         TreeSitter["Inline Tree-Sitter Extractors<br/><small>TS, JS, Python, Go, Rust, Java, C/C++, Ruby</small>"]:::adapter
         RegexInline["Inline Regex Extractors<br/><small>Markdown, JSON, YAML, TOML, CSS, Dockerfile</small>"]:::adapter
-        LangAdapters["Regex Adapters, inline and src/languages/ (74 non-tree-sitter languages)<br/><small>C#, PHP, Kotlin, GraphQL, SQL, Proto, Apex, etc.</small>"]:::adapter
+        LangAdapters["Regex Adapters, inline and src/languages/ (77 non-tree-sitter languages)<br/><small>C#, PHP, Kotlin, GraphQL, SQL, Proto, Apex, Nginx, Caddyfile, Apache, etc.</small>"]:::adapter
     end
 
     Parser --> TreeSitter

package/docs/cli.md

@@ -58,6 +58,7 @@ token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120
 | `token-goat call-chain <symbol>` | Trace every caller layer from a symbol back to the entry points — one step deeper than `callers`. Use when you need to know what reaches a function across the whole call graph, not only who invokes it directly. Pairs with `impact` for the downstream direction. Accepts `file::symbol` to disambiguate WHICH same-named definition the chain starts from — the file only narrows which definition, callers can still be found in any file. `--exclude-tests` prunes callers whose call site is a test file BEFORE they're admitted to the traversal, so nothing walks through a test node either (opt-in — omitted, output is unchanged); when every caller was a test, the "no callers" line names how many were hidden instead of reading as genuinely unreferenced. `Symbol not found: <symbol>` for an unindexed name (bare or `file::symbol`) now carries a `Did you mean:` suggestion when a near-name candidate is indexed. `--grep <pattern>` keeps only completed chains containing a symbol name matching this regex (literal substring if it is not valid regex) — the BFS still walks the full graph, this only narrows which finished chains are reported, so a chain passing through a matching symbol on its way to an unrelated root still surfaces; when it matches none of the chains that do exist, the output names how many were filtered out rather than reading as genuinely caller-less. A chain the walk abandoned because it ran out of `--depth` ends in a `(depth-limit)` marker, so a truncated chain is never mistaken for one that reached a real entry point. |
 | `token-goat impact <symbol>` | Walk the call-reference graph forward (breadth-first) and list every function that depends on a symbol, with hop depth; module-scope callers are surfaced as `(module scope) <file>` entries. Run before a refactor to size up the blast radius without starting a build. Accepts `file::symbol` to disambiguate WHICH same-named definition the walk starts from — the file only narrows which definition, callers can still be found in any file. `--exclude-tests` prunes callers (including module-scope entries) whose call site is a test file BEFORE they're enqueued for further traversal, so nothing walks through a test node either (opt-in — omitted, output is unchanged); when every caller was a test, the "no callers found" error names how many were hidden instead of reading as genuinely unreferenced. A bare name that isn't indexed at all reports `Symbol not found: <name>` (with a `Did you mean:` suggestion when a near-name candidate is indexed) instead of the misleading "no callers found", which is reserved for a real, indexed symbol that genuinely has zero impact. `--grep <pattern>` only shows impacted entries whose symbol name (or `(module scope) <file>` key) matches this regex (literal substring if it is not valid regex), the same filter `call-chain --grep`/`dead --grep` apply to their own results — applied BEFORE the `--top` slice, so it selects from the whole impacted set rather than an already-capped page; when it matches none of the impacted entries that do exist, the output names how many were filtered out instead of reading as genuinely impact-free. |
 | `token-goat context-for <task>` | Takes a natural-language task description, runs semantic search across the indexed codebase, and emits a prioritized list of `token-goat read` commands trimmed to a token budget. Fetches only the relevant slices instead of loading entire files. `--budget N` sets the token ceiling; `--top N` limits the file count; `--json` for structured output. Every emitted command carries the `file::symbol@LINE` anchor, so a suggestion still runs when the same symbol name has more than one definition in its file; `--json` entries carry the matching `line` field. |
+| `token-goat answer "<question>"` | Deterministic question router: classifies a plain-English question to one of six intents (where a symbol is, who calls it, what tests cover it, what a file exports, what a file imports, what breaks if a symbol changes), resolves the subject against the index, and delegates in-process to the command that already answers it. No model call, no inference, no fallback to a fuzzy match. Because the subject is looked up before anything runs, the router picks the right ARGUMENT FORM too: `answer "what tests cover foldPath"` resolves `foldPath` to `src/path_containment.ts` and runs `test-for` against the file, where passing a symbol to `test-for` directly fails. A bare basename resolves when exactly one file in the project carries it, and lists the candidates when several do. Every answer is preceded by `via: token-goat <command> <argument>` so the delegate can be verified or re-run with its own flags. Anything else refuses: `cannot answer deterministically: <why>; try: <command>`, exit 1. Questions of judgement, intent or runtime behaviour (`why does X...`, `is X correct`, `should I...`) refuse even when they name a real symbol. |
 | `token-goat ask "<question>"` *(experimental)* | Retrieves relevant slices via full-text (BM25) search over the symbol index — not semantic/embedding search — and lists them as pointer-citations plus `token-goat read` commands. Set `TOKEN_GOAT_ASK_BACKEND=claude` or `TOKEN_GOAT_ASK_BACKEND=codex` to synthesize a short answer via that CLI (whatever model it defaults to; token-goat does not force Haiku or any particular tier); with the env var unset, or the named CLI missing from PATH, `ask` degrades to printing the retrieved pointers with no network call. `--top N` caps the number of FTS hits (default 8); `--json` for structured output. Answers are not cached — each call re-retrieves and re-synthesizes from scratch. Every emitted command carries the `file::symbol@LINE` anchor, so a suggestion still runs when the same symbol name has more than one definition in its file; `--json` entries carry the matching `line` field. |
 | `token-goat changed [<ref>]` | List files (or `--symbol` for symbols) changed since a git ref, without reading the full diff. `<ref>` and `--since <ref>` are equivalent (default `HEAD~5`); `--since` wins if both are given. `--json` for structured output. `--grep <pattern>` only lists changed files whose path matches this regex (literal substring if it is not valid regex) — applied to the file list even in `--symbol` mode, before any downstream slicing; when it matches none of the files that did change, the output names the active filter instead of reading like nothing changed. `--exclude-tests` hides changed files that live in a test file (opt-in — omitted, output is unchanged), completing the flag family already on `refs`/`callers`/`dead`/`call-chain`/`impact`/`semantic`/`symbol`. `--grep` can only ever *select* a path, so there was no reliable way to ask for the non-test half of a diff: the negative-lookahead regex that expresses "not a test" silently degrades to a literal substring match whenever the regex-compile fallback fires. Test files are a large share of a typical diff — measured against this repo, 35–54% of changed files across the last 5, 10 and 20 commits. Like `--grep` it filters the file path, so it applies in `--symbol` mode too, and it prunes before the per-file index lookup rather than after, so a test file is never queried at all. Composable with `--grep` (a file must satisfy both; when both are active and `--grep` is what emptied the list, the `--grep` notice takes priority, and when `--grep` left only test files so that `--exclude-tests` emptied it, the message names both filters rather than claiming no non-test file changed). When it hides every changed file there was, the output names how many were hidden and exits 0, rather than a bare "No files changed." that would read as a clean diff. Every zero-row path emits the shared `{items, truncated, totalCount}` envelope under `--json`. |
 | `token-goat diff "file::symbol" [range]` | Show only the git diff hunk(s) that fall within one symbol's line range, e.g. `token-goat diff "file.ts::myFn" HEAD~3..HEAD`, instead of the whole file's diff. Also accepts `read`'s `symbol@LINE` anchor to pick out an otherwise-ambiguous candidate. |
@@ -81,7 +82,7 @@ token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120
 | `token-goat coverage-gaps` | Find callables in non-test source files that never appear in a test file's reference records. Useful for spotting untested surface area before a refactor or release. `--top N` caps output; `--json` for structured output. |
 | `token-goat recent [N]` | Show the N most recently edited/accessed files with their symbols. |
 | `token-goat grep "<pattern>" [paths...]` | Built-in fallback regex search over files (no `rg` shell-out, no caching) — session-aware dedup for raw `rg`/`grep` Bash calls is a separate hook, not this command. Accepts zero or more paths: omit to walk cwd, or pass several to search them together with hits merged in argument order under one `--max-lines` cap. `-C, --context <n>` shows `n` lines before and after each match. `--symbol` annotates each hit with its enclosing indexed symbol — ` [name (kind)]` appended in text mode, a `symbol: {name, kind, lineStart, lineEnd} | null` field per item under `--json` — `null`/no tag when the hit falls outside any indexed symbol (e.g. module-level code). |
-| `token-goat semantic "<query>"` | Find code by meaning, not by filename: embedding-vector similarity search over indexed file chunks and full-text search (BM25) over symbol names/bodies both run on every query and are fused by Reciprocal Rank Fusion (`score = sum of 1/(60 + rank)` per list), so an exact keyword match can outrank a weak vector hit instead of being shadowed by the vector branch. Covers extracted text from PDF/DOCX/PPTX/XLSX files alongside source code, so a query can surface a spec PDF, design doc, deck, or spreadsheet, not just code. Results are re-ranked with a path-priority multiplier so live source wins ties/near-ties against stale or archival prose (`archive/`, `archived/`, `old/`, `deprecated/`, `plans/`, `drafts/`, `CHANGELOG*`, `*.bak`, `*.orig`) and, more mildly, general docs (`docs/**`, `*.md`) — a nudge, not a hard filter, so a genuinely much better archival match still surfaces. Configure with `token-goat config set semantic.archive_weight <0-1>` / `token-goat config set semantic.docs_weight <0-1>` (both default `<1`; set to `1` to disable that penalty entirely, e.g. for a project with a genuinely live `plans/` directory). `--preflight` runs an advance diagnostic verification of embedding runtime availability, model weight cache presence, and project coverage without executing a query; add `--warm` to load/cache the ONNX model into memory. `--limit <n>` caps result count; `--json` for structured output: `{source, items, truncated, totalCount}`, where `source` is `"hybrid"` when both the embedding and BM25 branches contributed at least one raw hit, `"embeddings"` when only the embedding branch did (e.g. no vector index exists yet: optional embedding deps unavailable, or `indexing.embeddings_enabled` is off), or `"fts"` when only BM25 did, and every item carries the same keys (`filePath`, `name`, `kind`, `startLine`, `endLine`, `distance`, `preview`), with `null` for whichever of `name`/`kind`/`distance` don't apply to that item's source, and `filePath` rendered root-relative when a project root resolves, absolute when none does, matching plain-text output. On an embeddings hit, `name`/`kind` are resolved to the innermost indexed symbol whose line range contains the hit's start line (`null`/`null` when the hit falls outside any symbol, e.g. a top-of-file imports chunk); text output appends the same as a `— inside <name> (<kind>)` suffix. `--grep <pattern>` only shows hits whose FILE PATH matches this regex (literal substring if it is not valid regex), tested against the path exactly as rendered (so an anchored `--grep "^src/"` matches what you see, not the stored absolute path) — the high-value case is dropping test/vendored noise from a project-wide semantic hit list. Applied before the `--limit` slice in both the embeddings and full-text-fallback branches, so it selects from the whole hit set, not an already-capped page; when it matches nothing among hits that do exist, the output names the active filter (and `--json` sets `grepFilteredToEmpty: true`) instead of reading like the search found nothing. `--exclude-tests` hides hits whose file is a test file (opt-in — omitted, output is unchanged), covering the case `--grep` structurally cannot: `--grep` can only ever *select* a path, and the negative-lookahead pattern that would express "not a test" silently degrades to a literal substring match whenever the regex-compile fallback fires. Applied before the `--limit` slice in both branches and composable with `--grep` (a hit must satisfy both); when it hides every hit there was, the output names how many were hidden (and `--json` sets `excludeTestsFilteredToEmpty: true`) and exits 0, instead of the exit-1 "no matches" a genuinely empty search returns. With both filters set and both emptying the view, the `--grep` notice takes priority. |
+| `token-goat semantic "<query>"` | Find code by meaning, not by filename: embedding-vector similarity search over indexed file chunks and full-text search (BM25) over symbol names/bodies both run on every query and are fused by Reciprocal Rank Fusion (`score = sum of 1/(60 + rank)` per list), so an exact keyword match can outrank a weak vector hit instead of being shadowed by the vector branch. Covers extracted text from PDF/DOCX/PPTX/XLSX files alongside source code, so a query can surface a spec PDF, design doc, deck, or spreadsheet, not just code. Results are re-ranked with a path-priority multiplier so live source wins ties/near-ties against stale or archival prose (`archive/`, `archived/`, `old/`, `deprecated/`, `plans/`, `drafts/`, `CHANGELOG*`, `*.bak`, `*.orig`) and, more mildly, general docs (`docs/**`, `*.md`) — a nudge, not a hard filter, so a genuinely much better archival match still surfaces. Configure with `token-goat config set semantic.archive_weight <0-1>` / `token-goat config set semantic.docs_weight <0-1>` (both default `<1`; set to `1` to disable that penalty entirely, e.g. for a project with a genuinely live `plans/` directory). `token-goat config set semantic.max_distance <0.05-2>` is the relevance floor: a vector hit whose raw distance exceeds it is dropped before fusion, so a corpus whose own distances have been measured can stop the vector half answering a question it has nothing for. It defaults to `1.2`, the retrieval bound's own value, so out of the box it filters nothing — measured genuine matches run from 0.635 on a large index to 0.934 on a two-file one, overlapping the off-corpus band, so no fixed number separates them across corpus sizes and the default is deliberately inert. When the floor empties the vector half, the command says so and names the closest distance it rejected, so the number to change is visible rather than inferred. The key is refused from a project's own `.token-goat.toml` (see `docs/security.md`), since a checked-in file setting it near the minimum would withhold that repository's code from the vector half while BM25 went on answering. `--preflight` runs an advance diagnostic verification of embedding runtime availability, model weight cache presence, and project coverage without executing a query; add `--warm` to load/cache the ONNX model into memory. `--limit <n>` caps result count; `--json` for structured output: `{source, items, truncated, totalCount}`, where `source` is `"hybrid"` when both the embedding and BM25 branches contributed at least one raw hit, `"embeddings"` when only the embedding branch did (e.g. no vector index exists yet: optional embedding deps unavailable, or `indexing.embeddings_enabled` is off), or `"fts"` when only BM25 did, and every item carries the same keys (`filePath`, `name`, `kind`, `startLine`, `endLine`, `distance`, `preview`, `rank`, `rrf`, `retrieval`), with `null` for whichever of `name`/`kind`/`distance` don't apply to that item's source. `rank` is the item's 1-based position, `rrf` the fused score it was sorted on, and `retrieval` is `"dense"`, `"lexical"` or `"both"` — together they are what makes the ordering reproducible, since `distance` is only the vector leg's own score and a lexical-only item has none at all, so an item at distance 0.850 legitimately sits above one at 0.776 when the keyword pass voted for the first as well, and `filePath` rendered root-relative when a project root resolves, absolute when none does, matching plain-text output. On an embeddings hit, `name`/`kind` are resolved to the innermost indexed symbol whose line range contains the hit's start line (`null`/`null` when the hit falls outside any symbol, e.g. a top-of-file imports chunk); text output appends the same as a `— inside <name> (<kind>)` suffix. `--grep <pattern>` only shows hits whose FILE PATH matches this regex (literal substring if it is not valid regex), tested against the path exactly as rendered (so an anchored `--grep "^src/"` matches what you see, not the stored absolute path) — the high-value case is dropping test/vendored noise from a project-wide semantic hit list. Applied before the `--limit` slice in both the embeddings and full-text-fallback branches, so it selects from the whole hit set, not an already-capped page; when it matches nothing among hits that do exist, the output names the active filter (and `--json` sets `grepFilteredToEmpty: true`) instead of reading like the search found nothing. `--exclude-tests` hides hits whose file is a test file (opt-in — omitted, output is unchanged), covering the case `--grep` structurally cannot: `--grep` can only ever *select* a path, and the negative-lookahead pattern that would express "not a test" silently degrades to a literal substring match whenever the regex-compile fallback fires. Applied before the `--limit` slice in both branches and composable with `--grep` (a hit must satisfy both); when it hides every hit there was, the output names how many were hidden (and `--json` sets `excludeTestsFilteredToEmpty: true`) and exits 0, instead of the exit-1 "no matches" a genuinely empty search returns. With both filters set and both emptying the view, the `--grep` notice takes priority. |
 | `token-goat map` | Get a compact orientation of the repo. Add `--compact` to fit a fixed 2000-token budget. `--json` emits the project map as JSON instead of text. |
 | `token-goat deps "file"` | One-level import listing for a single file: resolves relative imports to project files (`internal`, root-relative paths) and groups everything else as `external`. `--json` for structured output. `--grep <pattern>` only shows dependencies whose MODULE SPECIFIER (the resolved internal path or the external package name) matches this regex (literal substring if it is not valid regex), applied before output is built; when it matches nothing among real dependencies, the output names the active filter instead of reading like the file has no imports at all. Complemented by `token-goat arch` for the project-wide graph. |
 | `token-goat arch` | Project-wide import graph summary: hub modules (most imported), entry points (nothing imports them), and circular chains. `--modules` adds a grouping of the files that mostly import each other, naming each group by its most connected file, saying whether the group is one directory or spread across several, and listing which groups reach into which. That section also prints the grouping's modularity and calls it out when it is too weak to mean anything, since the algorithm returns groups for any graph, including one with no real structure. `--json` carries each group's full member list. Complements `token-goat deps <file>` for per-file depth. |
@@ -98,7 +99,7 @@ token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120
 | `token-goat waste [--project <path>] [--transcript <path>] [--top <n>] [--json] [--copilot]` | Session spend-ledger: parses the current project's Claude Code session transcript and reports token cost by tool, by file, the top N most expensive individual tool calls, files read once and never referenced again, Bash commands run repeatedly without hitting token-goat's own bash-output cache, and the assistant's own text-output cost (generated tokens plus a cache-unaware re-send upper bound). See [Session waste ledger](#session-waste-ledger) below. |
 | `token-goat mcp-audit [--project <path>] [--json]` | MCP server schema cost report: scans .mcp.json for installed MCP servers, estimates per-server token costs from cached tool calls, correlates schema complexity against real call frequency. Outputs as markdown table or JSON. |
 | `token-goat recall ["<query>"] [--type bash\|web\|mcp] [--limit <n>] [--json]` | Full-text search across every cached bash-output, web-output, and mcp-output entry at once — one command instead of remembering which cache type holds a prior result. Ranked by relevance (BM25 via SQLite FTS5). With **no query**, lists every cached entry newest-first instead of searching, so you can browse when the ids have scrolled out of context and you have no term to search for. `--type` narrows to one cache type; `--limit` caps results (default 10). Each hit shows its cache type, id, the exact recall command (`bash-output <id>` / `web-output <id>` / `mcp-output <id>`), and a content snippet. See [Cross-cache recall](#cross-cache-recall) below. |
-| `token-goat hint-stats [--json] [--reset] [--mark-effective <cat>] [--mark-ineffective <cat>]` | Per-category efficacy report for token-goat's discretionary hint hooks: how often each hint category was emitted, how often the agent actually followed its specific suggestion within the next few tool calls, whether the category is currently auto-suppressed, and the bytes each category spent (injected into context) plus an all-time saved/spent/net summary line. `--reset` clears all tracked data; `--mark-effective`/`--mark-ineffective <category>` record a manual vote as a supplement to the automatic signal. See [Hint efficacy tracking](#hint-efficacy-tracking) below. |
+| `token-goat hint-stats [--json] [--reset] [--mark-effective <cat>] [--mark-ineffective <cat>]` | Per-category efficacy report for token-goat's discretionary hint hooks: how often each hint category was emitted, how often the agent actually followed its specific suggestion within the next few tool calls, whether the category is currently auto-suppressed, and the bytes each category spent (injected into context) plus an all-time saved-bytes/spent-bytes summary line (the two cover disjoint populations and are deliberately never netted against each other). `--reset` clears all tracked data; `--mark-effective`/`--mark-ineffective <category>` record a manual vote as a supplement to the automatic signal. See [Hint efficacy tracking](#hint-efficacy-tracking) below. |
 | `token-goat history` | Show current session access history: bash commands and URLs fetched. |
 | `token-goat session-outline` | Turn-by-turn structure (role, preview, tool calls, approx size) of a Claude Code session JSONL transcript, instead of a raw Read; defaults to the current project's most recent session. |
 | `token-goat session-slice <turns>` | Full content of one turn range from a Claude Code session JSONL transcript (see `session-outline` for turn numbers), instead of a raw Read. |
@@ -151,6 +152,7 @@ token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120
 | `token-goat reclaim-index` | Shrink an oversized symbol index (`VACUUM` + WAL checkpoint). `--rebuild` also drops every derived row — files/symbols/refs/chunks — so the next `token-goat index` re-derives them under current parser rules, which is what actually reclaims space held by rows a since-fixed extractor wrote too large. Refuses to run while the worker daemon is writing to the index unless `--force`. `token-goat doctor` points here when `global.db` grows past 1 GB and at least a tenth of it is free pages (it points to `project prune` instead for scratch files indexed under the OS temp dir), and separately when it finds a stored symbol body above the parser's own size cap — a leftover from a since-fixed extractor bug, which only `--rebuild` can clear (a plain `VACUUM` reclaims freed pages but never deletes row content). |
 | `token-goat prune-cache` | Manually trigger LRU eviction across all cache directories (images, bash, web, skills). |
 | `token-goat session-summary` | Compact one-liner about current session state — designed for orchestrators and multi-agent loops. |
+| `token-goat audit` | Run a session audit on recent agent activity, tracking surgical reads, token burn, cache hits, tool calls, and missed savings across Claude Code and Copilot CLI sessions. `--copilot` scopes to Copilot sessions; `--top <n>` limits item breakdowns; `--json` outputs structured audit data. |
 | `token-goat cache-audit` | Audit your Claude Code config for patterns that bust the prompt cache. |
 | `token-goat pack <patterns>` | Collect files matching glob patterns into a single LLM-ready output — Markdown (default), XML, or plain text — with a manifest table of per-file line and token counts. `--line-numbers` prefixes each line; `--instruction-file` appends a task prompt; `--output` writes to a file; `--no-ignore` bypasses `.tokengoatignore`. `--strip-comments` removes language-appropriate comments before packing (shebangs preserved; `#` inside string literals is a known limitation). `--scan-secrets` checks for credentials and exits 2 with per-file warnings if any are found. `--budget N` exits 3 when the estimated token count exceeds N — lets a shell script treat an oversized context as a hard error. Reads file paths from stdin when no patterns are given. |
 | `token-goat budget <patterns>` | Estimate the token cost of a file set without reading them into context. Prints results sorted by cost descending; `--context <N>` shows each file as a share of an N-thousand-token window. `--json` for machine-readable output. Run before `pack` to decide what to include. |
@@ -177,7 +179,7 @@ token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120
 | `token-goat project prune [--dry-run]` | Remove blocked/excluded roots that no longer exist on disk, and index rows for files under the OS temp dir. `--dry-run` previews removals without touching the config file. Useful after deleting or moving projects. |
 | `token-goat install` | Wire up hooks (and, with the harness flags below, other AI tool integrations). No `--dry-run` or `--verify` flag — run `token-goat doctor` after install to audit the result. |
 | `token-goat upgrade` | Check for updates or upgrade token-goat to the latest version via npm. Pass `--check` to report status without installing. `--json` emits machine-readable version status. |
-| `token-goat doctor` | Confirm everything is wired correctly. Surfaces install state, cold-import timing, cache hit rates, compaction-budget telemetry, opt-in flag status, and canonical-root sanity. A **Parser freshness** check reports how much of the index for this project was written by a different build of the extractor. The stamp only refreshes when something touches a file, so after an upgrade a project goes on answering `symbol`, `read`, `outline` and `skeleton` from the previous extractor with nothing saying so. It warns past a quarter and names the fix: a plain `token-goat index` in that project, which is enough on its own, since a parser mismatch reparses without `--force`. A **Tool names** check reports any tool name a harness sent that reached no handler wanting it, and calls out the ones that differ from a handled name only by capitalisation or punctuation — the signature of a bridge that forgot to rename something, which is otherwise invisible. A **Security** section reports the posture in one place: whether offline mode is on, whether injection scanning is on, whether the Google Drive integration is enabled, whether fetching runs against an allow list or a deny list, whether MCP reads are confined to the project root, and whether the data directory is readable by other local users. It only warns when a protection that ships on has been switched off, so a default install stays quiet. It read-only audits `~/.copilot/mcp-config.json` for globally configured Chrome DevTools or Playwright `npx` launchers, recommending project scope or removal when inactive; it never prints server configuration or secrets. On Windows, it also reports duplicate Chrome DevTools/Playwright MCP launchers and orphaned Node processes without terminating anything. Pass `--context` to show the **Context footprint** section: a fill bar with severity (ok / warn / high / URGENT), per-component breakdown (skills catalog, loaded skill bodies, CLAUDE.md+MEMORY.md, conversation estimate), session-to-session growth trend with sessions-to-URGENT projection, and tiered compaction recommendations (Tier 0–4) naming the exact commands to run. Auto-shown when fill > 40 % or any loaded skill > 2 K tokens lacks a compact. `--json` emits the check results (one entry per check, with `ok`/`warn`/`fail` status) as JSON instead of text. |
+| `token-goat doctor` | Confirm everything is wired correctly. Surfaces install state, cold-import timing, cache hit rates, compaction-budget telemetry, opt-in flag status, and canonical-root sanity. A **Parser freshness** check reports how much of the index for this project was written by a different build of the extractor. The stamp only refreshes when something touches a file, so after an upgrade a project goes on answering `symbol`, `read`, `outline` and `skeleton` from the previous extractor with nothing saying so. It warns past a quarter and names the fix: a plain `token-goat index` in that project, which is enough on its own, since a parser mismatch reparses without `--force`. A **Tool names** check reports any tool name a harness sent that reached no handler wanting it, and calls out the ones that differ from a handled name only by capitalisation or punctuation — the signature of a bridge that forgot to rename something, which is otherwise invisible. When `global.db` passes 1 GB, the warning now also breaks the total down by category (symbol bodies, refs, chunk text, embedding vectors, stats detail) with each one's measured byte share and the exact command that shrinks it -- `reclaim-index --rebuild` for the derived-row categories, disabling `indexing.embeddings_enabled` first for vectors so they don't regrow, and nothing manual for stats detail, which ages out on its own. A **Security** section reports the posture in one place: whether offline mode is on, whether injection scanning is on, whether the Google Drive integration is enabled, whether fetching runs against an allow list or a deny list, whether MCP reads are confined to the project root, and whether the data directory is readable by other local users. It only warns when a protection that ships on has been switched off, so a default install stays quiet. It read-only audits `~/.copilot/mcp-config.json` for globally configured Chrome DevTools or Playwright `npx` launchers, recommending project scope or removal when inactive; it never prints server configuration or secrets. On Windows, it also reports duplicate Chrome DevTools/Playwright MCP launchers and orphaned Node processes without terminating anything. Pass `--context` to show the **Context footprint** section: a fill bar with severity (ok / warn / high / URGENT), per-component breakdown (skills catalog, loaded skill bodies, CLAUDE.md+MEMORY.md, conversation estimate), session-to-session growth trend with sessions-to-URGENT projection, and tiered compaction recommendations (Tier 0–4) naming the exact commands to run. Auto-shown when fill > 40 % or any loaded skill > 2 K tokens lacks a compact. `--json` emits the check results (one entry per check, with `ok`/`warn`/`fail` status) as JSON instead of text. |
 | `token-goat capabilities` | List every capability that can send data off this machine or leave data on it, with whether it is currently on, the config key that decides that, and the exact `file::symbol` where the decision is made — so a reviewer can open the code rather than take the list's word for it. `--json` emits the same thing for a pipeline to assert on, which is the point: the answer comes from the binary installed on your machine, not from documentation that may describe a different build. A test in the suite fails the build when a module that can open a network connection is missing from this list, and equally when the list names one that no longer connects anywhere. |
 | `token-goat baseline` | Emit a project map: file count, per-language file counts, the top indexed symbols (by name/kind/location), and the most recently modified files. `--subagent` emits a terser variant (fewer symbols, fewer recent files) for context handed to a freshly spawned subagent; `--json` for the machine-readable form. |
 | `token-goat compact-doc <path>` | Build an extractive compact sidecar for a large reference doc (`.md`/`.markdown`). The compact is stored in the token-goat data dir as a SHA-keyed sidecar; `pre_read` serves it in place of the full file when it exists and is fresh, typically saving 60–95% of the tokens the full read would cost (measured across this repo's own 44 docs: median 67%, range 5–99%, depending on how much of the doc is prose under headings). Use `--force` to rebuild, `--sentences N` to control lines per section (default 2), `--show` to print the result. The sidecar is automatically marked stale when you edit the source file. Config: `[hints] stable_doc_compacts = true` (default on). |
@@ -307,22 +309,22 @@ worth its keep only if it's actually followed. `token-goat hint-stats` reports,
 category: how many times it fired, how many times a later Bash command in the same session
 actually invoked the specific `token-goat` command (or referenced the specific cached-output id)
 the hint pointed at, the resulting efficacy percentage, whether the category is currently
-auto-suppressed, and the `spent` column (bytes of hint text actually injected into context for
+auto-suppressed, and the `spent-bytes` column (bytes of hint text actually injected into context for
 that category — the real cost of emitting it, not just how often it fired):
 
 ```
 $ token-goat hint-stats
-category              emitted  acted-on  efficacy   suppressed  manual+  manual-  spent
-bash_redirect          42       9         21.4%      no          0        0        3150
-bash_recall            18       15        83.3%      no          0        0        1080
-read_reread_dedup      11       2         18.2% *    no          0        0        660
-read_structural_nav    7        1         14.3%      yes         0        1        420
-edit_reread_suggest    3        0         0% *       no          0        0        180
-
-TOTAL   saved=48200   spent=5490   net=42710
+category              emitted  undisplayed  acted-on  efficacy   suppressed  manual+  manual-  spent-bytes
+bash_redirect          42       -            9         21.4%      no          0        0        3150
+bash_recall            18       -            15        83.3%      no          0        0        1080
+read_reread_dedup      11       -            2         18.2% *    no          0        0        660
+read_structural_nav    7        3            1         14.3%      yes         0        1        420
+edit_reread_suggest    3        -            0         0% *       no          0        0        180
+
+TOTAL   saved-bytes=48200 (all-time, every hint kind)   spent-bytes=5490 (hint_emissions ledger only)
 ```
 
-`spent` (and the `TOTAL` line's `spent`/`net`) render `n/a` instead of a fake `0` whenever a
+`spent-bytes` (and the `TOTAL` line's `spent-bytes`) render `n/a` instead of a fake `0` whenever a
 category — or, for the total, the whole store — has no tracked spend figure at all: either
 nothing has fired yet, or every emission predates this feature and was recorded before spend
 tracking existed. A partially-tracked category shows the real sum plus how many legacy rows it

package/docs/install.md

@@ -360,7 +360,7 @@ For VS Code using the token-goat MCP server (`token-goat install --vscode`), ena
 
 One table in `src/language_specs.ts` drives every per-language list token-goat uses, so this is the whole set. **Symbols** means `symbol`, `read "file::Name"`, `skeleton` and `outline` return named declarations from the file. **Structure only** means the file is indexed for headings, keys or sections rather than code symbols.
 
-**Symbols:** ABAP (`.abap`), Apex (`.cls`, `.trigger`), Assembly (`.s`, `.asm`, `.nasm`), Bash and compatible shells (`.sh`, `.bash`, `.zsh`, `.ksh`, `.bats`), C (`.c`, `.h`), C# (`.cs`), C++ (`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`), Clojure (`.clj`, `.cljs`, `.cljc`), CMake (`.cmake`, `CMakeLists.txt`), COBOL (`.cbl`, `.cob`, `.cobol`, `.cpy`), Common Lisp (`.lisp`, `.lsp`, `.cl`), Dart (`.dart`), Elixir (`.ex`, `.exs`), Emacs Lisp (`.el`), Erlang (`.erl`, `.hrl`), F# (`.fs`, `.fsi`, `.fsx`), Fortran (`.f`, `.for`, `.f77`, `.f90`, `.f95`, `.f03`, `.f08`), GLSL (`.glsl`, `.vert`, `.frag`, `.comp`, `.geom`, `.tesc`, `.tese`), Go (`.go`), GraphQL (`.graphql`, `.gql`), Groovy (`.groovy`, `.gvy`, `.gradle`, `Jenkinsfile`), Haskell (`.hs`), HLSL (`.hlsl`, `.hlsli`), Java (`.java`), JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`), JCL (`.jcl`), Kotlin (`.kt`, `.kts`), Lua (`.lua`), MATLAB, Metal (`.metal`), Natural (`.nsp`, `.nsn`, `.nss`, `.nsa`, `.nsl`, `.nsg`, `.nsc`, `.nsh`), Nix (`.nix`), Objective-C (`.mm`, and a `.h` that declares an `@interface` or `@protocol`), OCaml (`.ml`, `.mli`), OpenEdge ABL, Pascal (`.pas`, `.dpr`, `.dpk`, `.lpr`, `.dfm`), Perl (`.pl`, `.pm`), PHP (`.php`), PL/I (`.pli`, `.pl1`), PowerShell (`.ps1`, `.psm1`), Protocol Buffers (`.proto`), Python and Starlark (`.py`, `.pyi`, `.bzl`, `.star`, `BUILD`, `WORKSPACE`, `MODULE.bazel`), R (`.r`), Racket (`.rkt`, `.rktl`), RPG (`.rpgle`, `.sqlrpgle`), Ruby (`.rb`, `.ruby`, `.rake`, `Gemfile`, `Rakefile`, and the other extensionless Ruby DSL files), Rust (`.rs`), Salesforce markup (`.cmp`, `.app`, `.evt`, `.intf`, `.design`, `.auradoc`, `.tokens`, `.page`, `.component`, `.email`), Salesforce metadata, SAS (`.sas`), Scala (`.scala`, `.sc`), Scheme (`.scm`, `.ss`), Solidity (`.sol`), SQL and PL/SQL (`.sql`, `.pks`, `.pkb`, `.pls`, `.plsql`, `.pck`, `.prc`, `.fnc`, `.trg`, `.tps`, `.tpb`), Swift (`.swift`), Terraform (`.tf`, `.tfvars`, `.hcl`), Thrift (`.thrift`), TypeScript (`.ts`, `.tsx`, `.mts`, `.cts`), VHDL (`.vhd`, `.vhdl`), Visual Basic (`.vb`, `.bas`, `.vbs`, `.frm`), WGSL (`.wgsl`), Windows batch (`.bat`, `.cmd`), Zig (`.zig`).
+**Symbols:** ABAP (`.abap`), Apache (`httpd.conf`, `apache2.conf`, `.htaccess`, `.apache`, `.apache2`), Apex (`.cls`, `.trigger`), Assembly (`.s`, `.asm`, `.nasm`), Bash and compatible shells (`.sh`, `.bash`, `.zsh`, `.ksh`, `.bats`), C (`.c`, `.h`), C# (`.cs`), C++ (`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`), Caddyfile (`Caddyfile`, `.caddy`), Clojure (`.clj`, `.cljs`, `.cljc`), CMake (`.cmake`, `CMakeLists.txt`), COBOL (`.cbl`, `.cob`, `.cobol`, `.cpy`), Common Lisp (`.lisp`, `.lsp`, `.cl`), Dart (`.dart`), Elixir (`.ex`, `.exs`), Emacs Lisp (`.el`), Erlang (`.erl`, `.hrl`), F# (`.fs`, `.fsi`, `.fsx`), Fortran (`.f`, `.for`, `.f77`, `.f90`, `.f95`, `.f03`, `.f08`), GLSL (`.glsl`, `.vert`, `.frag`, `.comp`, `.geom`, `.tesc`, `.tese`), Go (`.go`), GraphQL (`.graphql`, `.gql`), Groovy (`.groovy`, `.gvy`, `.gradle`, `Jenkinsfile`), Haskell (`.hs`), HLSL (`.hlsl`, `.hlsli`), Java (`.java`), JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`), JCL (`.jcl`), Kotlin (`.kt`, `.kts`), Lua (`.lua`), MATLAB, Metal (`.metal`), Natural (`.nsp`, `.nsn`, `.nss`, `.nsa`, `.nsl`, `.nsg`, `.nsc`, `.nsh`), Nginx (`nginx.conf`, `.nginx`), Nix (`.nix`), Objective-C (`.mm`, and a `.h` that declares an `@interface` or `@protocol`), OCaml (`.ml`, `.mli`), OpenEdge ABL, Pascal (`.pas`, `.dpr`, `.dpk`, `.lpr`, `.dfm`), Perl (`.pl`, `.pm`), PHP (`.php`), PL/I (`.pli`, `.pl1`), PowerShell (`.ps1`, `.psm1`), Protocol Buffers (`.proto`), Python and Starlark (`.py`, `.pyi`, `.bzl`, `.star`, `BUILD`, `WORKSPACE`, `MODULE.bazel`), R (`.r`), Racket (`.rkt`, `.rktl`), RPG (`.rpgle`, `.sqlrpgle`), Ruby (`.rb`, `.ruby`, `.rake`, `Gemfile`, `Rakefile`, and the other extensionless Ruby DSL files), Rust (`.rs`), Salesforce markup (`.cmp`, `.app`, `.evt`, `.intf`, `.design`, `.auradoc`, `.tokens`, `.page`, `.component`, `.email`), Salesforce metadata, SAS (`.sas`), Scala (`.scala`, `.sc`), Scheme (`.scm`, `.ss`), Solidity (`.sol`), SQL and PL/SQL (`.sql`, `.pks`, `.pkb`, `.pls`, `.plsql`, `.pck`, `.prc`, `.fnc`, `.trg`, `.tps`, `.tpb`; including DuckDB `CREATE MACRO` and `CREATE SECRET` statements), Swift (`.swift`), Terraform (`.tf`, `.tfvars`, `.hcl`), Thrift (`.thrift`), TypeScript (`.ts`, `.tsx`, `.mts`, `.cts`), VHDL (`.vhd`, `.vhdl`), Visual Basic (`.vb`, `.bas`, `.vbs`, `.frm`), WGSL (`.wgsl`), Windows batch (`.bat`, `.cmd`), Zig (`.zig`).
 
 **Structure only:** Astro (`.astro`), CSS and its preprocessors (`.css`, `.scss`, `.sass`, `.less`), Dockerfile, environment files (`.env`, `.envrc`), HTML (`.html`, `.htm`), INI (`.ini`, `.cfg`, `.conf`), JSON including JSON with comments and Avro schemas (`.json`, `.jsonc`, `.avsc`), Jupyter notebooks (`.ipynb`), Makefiles (`.mk`, `Makefile`), Markdown (`.md`, `.markdown`, `.mdx`), Svelte (`.svelte`), TOML (`.toml`), Vue (`.vue`), YAML (`.yaml`, `.yml`), and seven template-engine dialects read as HTML: Liquid (`.liquid`), Jinja2 (`.j2`, `.jinja`, `.jinja2`), Handlebars (`.hbs`, `.handlebars`), ERB (`.erb`), EJS (`.ejs`), Nunjucks (`.njk`), Twig (`.twig`).
 

package/docs/security.md

@@ -20,9 +20,9 @@ Outbound network is reserved to these explicit cases:
 
 **One switch for all of it.** Set `network.offline = true` (env `TOKEN_GOAT_OFFLINE`) and every one of the paths above refuses instead of connecting, saying so rather than failing quietly. Anything already cached keeps working: a machine that has the embedding model still runs `semantic`, and one that has the language data still reads text out of images. This is one of the settings a per-project config file may not touch, so cloning a repository cannot switch it back off.
 
-**A repository cannot reconfigure the security controls.** A project-root `.token-goat.toml` layers on top of your global config, which is what it is for: hint thresholds, indexing settings, compression tuning. But that file arrives with the repository, so whoever wrote the repository wrote it. Seven whole sections are therefore off limits to it, and come from your global config or the environment only: `injection` (prompt-injection fencing), `webfetch` (the fetch allow and deny lists), `gdrive` (the Google Drive integration), `mcp` (root confinement and the allowed-roots list), `network` (offline mode), `redaction` (the secret-redaction rules), and `screenshot` (the headless browser). Thirteen individual keys inside otherwise-overridable sections are locked the same way. Five decide what gets indexed at all: `indexing.cross_project_symbols`, `indexing.skip_dirs`, `indexing.skip_files`, `indexing.large_file_skip_kb` and `indexing.large_file_symbol_only_kb`, which matter because an unindexed file answers `symbol`, `read` and `semantic` in the same words a name that never existed does. Five more are the switches that decide whether a large file arrives folded rather than whole: `hints.fold_code_bodies`, `hints.fold_comment_blocks`, `hints.fold_prose_paragraphs`, `hints.outline_large_documents` and `hints.skeleton_large_sources`. The last three are `image_shrink.max_image_pixels`, the decompression-bomb cap, `worker.blocked_roots`, the folders you have kept out of the index, and `compact_assist.summary_budget_chars`, the length target token-goat hands to whoever writes your compaction summary, which a repository must not be able to set low enough to erase the session. A project file that sets one of them is ignored, and token-goat prints a line naming what it dropped. Everything else stays project-overridable.
+**A repository cannot reconfigure the security controls.** A project-root `.token-goat.toml` layers on top of your global config, which is what it is for: hint thresholds, indexing settings, compression tuning. But that file arrives with the repository, so whoever wrote the repository wrote it. Seven whole sections are therefore off limits to it, and come from your global config or the environment only: `injection` (prompt-injection fencing), `webfetch` (the fetch allow and deny lists), `gdrive` (the Google Drive integration), `mcp` (root confinement and the allowed-roots list), `network` (offline mode), `redaction` (the secret-redaction rules), and `screenshot` (the headless browser). Seventeen individual keys inside otherwise-overridable sections are locked the same way. Six decide what gets indexed at all: `indexing.cross_project_symbols`, `indexing.skip_dirs`, `indexing.skip_files`, `indexing.large_file_skip_kb`, `indexing.large_file_symbol_only_kb` and `indexing.max_chunks_per_file`, which matter because an unindexed file answers `symbol`, `read` and `semantic` in the same words a name that never existed does. Five more are the switches that decide whether a large file arrives folded rather than whole: `hints.fold_code_bodies`, `hints.fold_comment_blocks`, `hints.fold_prose_paragraphs`, `hints.outline_large_documents` and `hints.skeleton_large_sources`. The last four are `image_shrink.max_image_pixels`, the decompression-bomb cap, `worker.blocked_roots`, the folders you have kept out of the index, `compact_assist.summary_budget_chars`, the length target token-goat hands to whoever writes your compaction summary, which a repository must not be able to set low enough to erase the session, and `semantic.max_distance`, the relevance floor for `semantic`, which a repository must not be able to set low enough that its own code stops matching while the command goes on answering from keyword search as though nothing were missing. Two more govern the shared database: `indexing.max_db_size_mb` and `indexing.auto_reclaim_embeddings`, which prevent a repository from manipulating global database disk caps or forcing vector purging across projects. A project file that sets one of them is ignored, and token-goat prints a line naming what it dropped. Everything else stays project-overridable.
 
-**The lock covers the config file, not the environment.** These settings still read a `TOKEN_GOAT_*` environment variable, and a repository has ways to set one: a `.envrc` for direnv, a `terminal.integrated.env.*` block in a committed `.vscode/settings.json`, a `containerEnv` entry in a devcontainer. Refusing environment overrides would break the operator who exports a variable in their own shell, which is the legitimate case and the common one, so token-goat reports instead of refusing: `token-goat doctor` prints a `Security config overrides` line naming every locked security setting the environment is currently deciding, and the variable to unset. It covers all twenty locked keys that read an environment variable, and it derives that set from the same two tables that define what a project config may not write, rather than from a list kept alongside them. Settings with a safe side (booleans) are reported when the environment holds them open; settings without one (lists, sizes) are reported whenever the environment supplies a value at all, since there is nothing to compare against. A default install, where nothing is set, prints a single ok line.
+**The lock covers the config file, not the environment.** These settings still read a `TOKEN_GOAT_*` environment variable, and a repository has ways to set one: a `.envrc` for direnv, a `terminal.integrated.env.*` block in a committed `.vscode/settings.json`, a `containerEnv` entry in a devcontainer. Refusing environment overrides would break the operator who exports a variable in their own shell, which is the legitimate case and the common one, so token-goat reports instead of refusing: `token-goat doctor` prints a `Security config overrides` line naming every locked security setting the environment is currently deciding, and the variable to unset. It covers all twenty-two locked keys that read an environment variable, and it derives that set from the same two tables that define what a project config may not write, rather than from a list kept alongside them. Settings with a safe side (booleans) are reported when the environment holds them open; settings without one (lists, sizes) are reported whenever the environment supplies a value at all, since there is nothing to compare against. A default install, where nothing is set, prints a single ok line.
 
 **Security reports.** See [SECURITY.md](../SECURITY.md). Email `token-goat@dfkhelper.com`; do not file as a GitHub issue. Reports are acknowledged within 7 days; coordinated disclosure with a 90-day default window.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-goat",
-  "version": "2.9.18",
+  "version": "2.9.20",
   "description": "Surgical token-reduction companion for Claude Code and other AI coding agents",
   "type": "module",
   "main": "./dist/token-goat.mjs",
@@ -132,6 +132,7 @@
     "unzipper": "^0.12.5",
     "adm-zip": "^0.6.0",
     "fast-uri": "^3.1.6",
-    "qs": "^6.16.0"
+    "qs": "^6.16.0",
+    "tesseract.js-core": "6.1.2"
   }
 }