token-goat 2.6.23 → 2.6.25

package/dist/token-goat.mjs

@@ -3050,7 +3050,7 @@ var require_commander = __commonJS({
 import { createRequire } from "node:module";
 function resolveVersion() {
   if (true) {
-    return "2.6.23";
+    return "2.6.25";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");
@@ -4283,12 +4283,12 @@ function normalizeDarwinSystemAlias(p) {
 }
 function resolveIndexPath(file2, base = process.cwd()) {
   const isWindowsAbsolute = (s) => /^[a-zA-Z]:[/\\]/.test(s);
-  const resolve24 = isWindowsAbsolute(file2) || isWindowsAbsolute(base) ? path2.win32.resolve : path2.resolve;
-  return normalizePath(resolve24(base, file2));
+  const resolve25 = isWindowsAbsolute(file2) || isWindowsAbsolute(base) ? path2.win32.resolve : path2.resolve;
+  return normalizePath(resolve25(base, file2));
 }
 function toDisplayPath(root, target) {
   if (root === void 0) return target;
-  const rel = path2.relative(root, target).replace(/\\/g, "/");
+  const rel = path2.relative(normalizePath(root), normalizePath(target)).replace(/\\/g, "/");
   if (rel === "" || rel.startsWith("..") || path2.isAbsolute(rel)) {
     return rel === "" ? "." : target;
   }
@@ -4350,6 +4350,15 @@ function foldCase(s) {
 function runGit(args, opts = {}) {
   const subArgs = args[0] === "diff" ? [args[0], "--no-ext-diff", "--no-textconv", ...args.slice(1)] : args;
   const fullArgs = [
+    // Never take an optional lock. Every git call here is on someone else's
+    // working repo, and a `status` that refreshes the index writes
+    // `.git/index.lock`; if this process is killed mid-call -- which the hint
+    // paths deliberately invite, since they spawn under a short timeout -- the
+    // orphaned lock blocks every subsequent commit in that repo until a human
+    // deletes it. Observed doing exactly that on 2026-08-05. `--no-optional-
+    // locks` suppresses only locks git considers optional, so write commands
+    // that genuinely need one are unaffected.
+    "--no-optional-locks",
     "-c",
     "core.fsmonitor=",
     "-c",
@@ -4673,6 +4682,28 @@ function writeIfDifferent(p, content, backup = false) {
   atomicWriteText(p, content);
   return true;
 }
+function buildContextWindow(absPath, line, contextLines) {
+  if (!Number.isFinite(contextLines) || contextLines <= 0) return null;
+  let text;
+  try {
+    text = readFileSync2(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const lines2 = text.split(/\r?\n/);
+  const idx = line - 1;
+  if (idx < 0 || idx >= lines2.length) return null;
+  const start = Math.max(0, idx - contextLines);
+  const end = Math.min(lines2.length - 1, idx + contextLines);
+  const out2 = [];
+  for (let i = start; i <= end; i++) out2.push({ line: i + 1, text: lines2[i] ?? "" });
+  return out2;
+}
+function renderContextWindow(displayFile, matchLine3, window, matchSuffix = "", indent = "") {
+  return window.map(
+    (c) => c.line === matchLine3 ? `${indent}${displayFile}:${c.line}: ${c.text}${matchSuffix}` : `${indent}${displayFile}-${c.line}- ${c.text}`
+  );
+}
 function toKB(bytes) {
   return Math.round(bytes / 1024);
 }
@@ -4725,6 +4756,19 @@ function isCodeFenceDelimiter(line) {
 function pad(s, n) {
   return s.length >= n ? s : s + " ".repeat(n - s.length);
 }
+function installEpipeGuard(streams) {
+  const targets = (streams ?? [process.stdout, process.stderr]).filter((s) => s !== void 0);
+  for (const stream of targets) {
+    stream.on("error", (err2) => {
+      if (err2.code === "EPIPE") {
+        process.exitCode = 0;
+        return;
+      }
+      throw err2;
+    });
+  }
+  return targets;
+}
 function normalizePathForwardSlash(p, toLowerCase) {
   let result = normalizePath(p).replace(/\\/g, "/");
   if (toLowerCase) result = result.toLowerCase();
@@ -5056,7 +5100,8 @@ function defaultConfig() {
     compression: getDefaultConfig("compression"),
     context: getDefaultConfig("context"),
     injection: getDefaultConfig("injection"),
-    hint_stats: getDefaultConfig("hint_stats")
+    hint_stats: getDefaultConfig("hint_stats"),
+    semantic: getDefaultConfig("semantic")
   };
 }
 function validatedBool(raw, def) {
@@ -5498,6 +5543,10 @@ function _buildConfig(raw, projectRaw = {}) {
   const hs = getDefaultConfig("hint_stats");
   hs.suppress_threshold_pct = validatedInt(hs_raw["suppress_threshold_pct"], hs.suppress_threshold_pct, ...boundsOf("hint_stats.suppress_threshold_pct"));
   hs.min_sample_size = validatedInt(hs_raw["min_sample_size"], hs.min_sample_size, ...boundsOf("hint_stats.min_sample_size"));
+  const sem_raw = section(raw, "semantic");
+  const sem = getDefaultConfig("semantic");
+  sem.archive_weight = validatedFloat(sem_raw["archive_weight"], sem.archive_weight, ...boundsOf("semantic.archive_weight"));
+  sem.docs_weight = validatedFloat(sem_raw["docs_weight"], sem.docs_weight, ...boundsOf("semantic.docs_weight"));
   return {
     compact_assist: ca,
     bash_compress: bc,
@@ -5520,7 +5569,8 @@ function _buildConfig(raw, projectRaw = {}) {
     compression: cpr,
     context: ctx,
     injection: inj,
-    hint_stats: hs
+    hint_stats: hs,
+    semantic: sem
   };
 }
 function saveConfig(config2) {
@@ -5677,6 +5727,10 @@ function saveConfig(config2) {
     hint_stats: {
       suppress_threshold_pct: config2.hint_stats.suppress_threshold_pct,
       min_sample_size: config2.hint_stats.min_sample_size
+    },
+    semantic: {
+      archive_weight: config2.semantic.archive_weight,
+      docs_weight: config2.semantic.docs_weight
     }
   };
   const toml = stringify(data);
@@ -5869,6 +5923,10 @@ var init_config = __esm({
       hint_stats: {
         suppress_threshold_pct: 15,
         min_sample_size: 5
+      },
+      semantic: {
+        archive_weight: 0.7,
+        docs_weight: 0.92
       }
     };
     NUMERIC_FIELD_BOUNDS = {
@@ -5932,7 +5990,9 @@ var init_config = __esm({
       "indexing.large_file_skip_kb": { min: 1, max: 1048576 },
       "context.model_window_tokens": { min: 1e4, max: 1e7 },
       "hint_stats.suppress_threshold_pct": { min: 0, max: 100 },
-      "hint_stats.min_sample_size": { min: 1, max: 1e4 }
+      "hint_stats.min_sample_size": { min: 1, max: 1e4 },
+      "semantic.archive_weight": { min: 0.05, max: 1 },
+      "semantic.docs_weight": { min: 0.05, max: 1 }
     };
     ENUM_FIELD_VALUES = {
       "compression.profile": ["auto", "aggressive", "balanced", "minimal"],
@@ -12084,14 +12144,23 @@ const path = require('node:path')
 const { pathToFileURL } = require('node:url')
 
 // Copilot event name -> token-goat internal HookEventName (src/types.ts's
-// HOOK_EVENTS). Only these six have a token-goat handler; every other real
+// HOOK_EVENTS). Only these seven have a token-goat handler; every other real
 // Copilot event (sessionEnd, postToolUseFailure, subagentStart,
 // errorOccurred, notification, permissionRequest) is left unimplemented
 // rather than guessed at, and falls through to the default no-op below.
-// 'sessionStart' is handled as a permanent no-op even though it's a real
-// Copilot event, because token-goat has no internal session_start handler
-// (mirrors PI_EXTENSION_SCRIPT's documented precedent).
+// 'sessionStart' was previously a permanent no-op on the stated grounds that
+// token-goat has no internal session_start handler. That was simply wrong --
+// hooks_session_start.ts has long emitted the command-routing reminder that
+// every other harness receives -- and the no-op was the reason Copilot CLI
+// sessions alone never got told token-goat exists. It is wired now: verified
+// against Copilot CLI 1.0.77 that a hooks.json sessionStart entry returning
+// {additionalContext} does reach the model. The github/copilot-cli#2142
+// fire-and-forget bug that would have made this dead wiring was fixed in a
+// pre-release months before that version, and its companion multi-extension
+// hook-overwrite bug never applied here: it hit runtime *extension* hooks,
+// while this config-file hooks.json path goes through Copilot's own merge.
 const COPILOT_TO_TG_EVENT = {
+  sessionStart: 'session_start',
   preToolUse: 'pre_tool_use',
   postToolUse: 'post_tool_use',
   preCompact: 'pre_compact',
@@ -12203,11 +12272,6 @@ async function tryInProcess(entryPath, tgEvent, canonical) {
 async function main() {
   const copilotEvent = process.argv[2] || ''
 
-  if (copilotEvent === 'sessionStart') {
-    process.stdout.write('{}')
-    return
-  }
-
   const tgEvent = COPILOT_TO_TG_EVENT[copilotEvent]
   if (!tgEvent) {
     process.stdout.write('{}')
@@ -12333,7 +12397,10 @@ function translate(copilotEvent, resp) {
     return {}
   }
 
-  if (copilotEvent === 'postToolUse') {
+  if (copilotEvent === 'postToolUse' || copilotEvent === 'sessionStart') {
+    // Both surface token-goat's context through the same field. sessionStart is
+    // the one channel that reaches the model before it picks its first read
+    // tool, so this is where the routing reminder has to land.
     const context = extractContext(resp)
     if (context) return { additionalContext: context }
     return {}
@@ -12357,9 +12424,8 @@ function translate(copilotEvent, resp) {
   // doc that both are notification-only -- Copilot never reads a response
   // body for either, so any additionalContext/systemMessage token-goat
   // produces has no surfacing channel here. This still routes through the
-  // token-goat hook call above (unlike sessionStart's early no-op) so the
-  // internal handler's own side effects keep running; only the response is
-  // discarded.
+  // token-goat hook call above so the internal handler's own side effects keep
+  // running; only the response is discarded.
   return {}
 }
 
@@ -12399,8 +12465,13 @@ main()
 import * as fs11 from "node:fs";
 import * as os5 from "node:os";
 import * as path11 from "node:path";
+function copilotCliUserRoot() {
+  const override = process.env["COPILOT_HOME"];
+  if (override !== void 0 && override.trim() !== "") return path11.resolve(override);
+  return path11.join(os5.homedir(), ".copilot");
+}
 function copilotCliUserHooksDir() {
-  return path11.join(os5.homedir(), ".copilot", "hooks");
+  return path11.join(copilotCliUserRoot(), "hooks");
 }
 function copilotCliProjectHooksDir() {
   return path11.join(process.cwd(), ".github", "hooks");
@@ -12505,6 +12576,7 @@ var init_copilot_cli_install = __esm({
     init_copilot_cli();
     init_guidance_block();
     COPILOT_CLI_HOOK_EVENTS = [
+      "sessionStart",
       "preToolUse",
       "postToolUse",
       "preCompact",
@@ -15646,16 +15718,16 @@ var init_file_type_handler = __esm({
 
 // src/skill_cache.ts
 import * as fs18 from "fs/promises";
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 import { homedir as homedir7 } from "os";
 import { readdirSync as readdirSync8, readFileSync as readFileSync13, existsSync as existsSync14, statSync as statSync8, unlinkSync as unlinkSync9 } from "node:fs";
 function skillOutputsDir() {
   if (_skillOutputsDirOverride) return _skillOutputsDirOverride;
-  return resolve7(dataDir(), SKILLS_OUTPUT_SUBDIR);
+  return resolve8(dataDir(), SKILLS_OUTPUT_SUBDIR);
 }
 function skillsSourceDir() {
   if (_skillsSourceDirOverride) return _skillsSourceDirOverride;
-  return resolve7(homedir7(), ".claude", "skills");
+  return resolve8(homedir7(), ".claude", "skills");
 }
 async function ensureSkillsDir() {
   try {
@@ -15798,7 +15870,7 @@ async function listOutputs() {
         continue;
       }
       try {
-        const content = await fs18.readFile(resolve7(dir, entry.name), "utf-8");
+        const content = await fs18.readFile(resolve8(dir, entry.name), "utf-8");
         const meta3 = JSON.parse(content);
         metas.push(meta3);
       } catch {
@@ -15832,7 +15904,7 @@ async function findCrossSessionEntry(skillName, contentSha) {
         continue;
       }
       const dir = skillOutputsDir();
-      const bodyPath = resolve7(dir, `${meta3.outputId}.txt`);
+      const bodyPath = resolve8(dir, `${meta3.outputId}.txt`);
       try {
         const bodyExists = await fs18.access(bodyPath).then(() => true).catch(() => false);
         if (bodyExists) {
@@ -15887,7 +15959,7 @@ async function storeOutput(sessionId, skillName, body, opts) {
       const truncBuf = buf.slice(truncStart);
       storedBody = truncBuf.toString("utf-8");
     }
-    await atomicWriteText(resolve7(dir, `${outId}.txt`), storedBody);
+    await atomicWriteText(resolve8(dir, `${outId}.txt`), storedBody);
     const meta3 = {
       outputId: outId,
       skillName: name2,
@@ -15897,7 +15969,7 @@ async function storeOutput(sessionId, skillName, body, opts) {
       truncated,
       sourcePath: opts?.sourcePath || ""
     };
-    await atomicWriteText(resolve7(dir, `${outId}.meta`), JSON.stringify(meta3, null, 2));
+    await atomicWriteText(resolve8(dir, `${outId}.meta`), JSON.stringify(meta3, null, 2));
     pruneSkillOutputs();
     return meta3;
   } catch {
@@ -15917,7 +15989,7 @@ async function storeCompact(sessionId, skillName, compactText, sourceSha) {
       text = `<!-- source_sha: ${sourceSha.slice(0, 12)} -->
 ${text}`;
     }
-    await atomicWriteText(resolve7(dir, fileId), text);
+    await atomicWriteText(resolve8(dir, fileId), text);
   } catch {
   }
 }
@@ -15937,7 +16009,7 @@ function getCompactAnySessionSync(skillName) {
     for (const entry of entries) {
       if (!matchesCompactSuffix(entry.name, entry.isFile(), suffix)) continue;
       try {
-        const text = readFileSync13(resolve7(dir, entry.name), "utf-8");
+        const text = readFileSync13(resolve8(dir, entry.name), "utf-8");
         if (text.trim()) return text;
       } catch {
         continue;
@@ -15965,7 +16037,7 @@ async function readSkillHits(skillName) {
     const name2 = safeSkillName(skillName);
     if (!name2) return { count: 0, lastTs: 0 };
     const dir = skillOutputsDir();
-    const hitsFile = resolve7(dir, `${sanitizeSkillId(name2)}.hits`);
+    const hitsFile = resolve8(dir, `${sanitizeSkillId(name2)}.hits`);
     const content = await fs18.readFile(hitsFile, "utf-8").catch(() => null);
     if (content) {
       const parsed = JSON.parse(content);
@@ -16015,7 +16087,7 @@ async function incrementSkillHit(skillName) {
     if (!name2) return;
     await ensureSkillsDir();
     const dir = skillOutputsDir();
-    const hitsFile = resolve7(dir, `${sanitizeSkillId(name2)}.hits`);
+    const hitsFile = resolve8(dir, `${sanitizeSkillId(name2)}.hits`);
     const lockPath = `${hitsFile}.lock`;
     await runExclusiveInProcess(lockPath, async () => {
       const locked = await acquireSkillHitLock(lockPath);
@@ -16062,14 +16134,14 @@ async function listSkills(sessionId) {
       let compactLen = 0;
       let compactText = "";
       try {
-        const stat2 = await fs18.stat(resolve7(dir, compactFileId));
+        const stat2 = await fs18.stat(resolve8(dir, compactFileId));
         compactLen = stat2.size;
-        compactText = await fs18.readFile(resolve7(dir, compactFileId), "utf-8").catch(() => "");
+        compactText = await fs18.readFile(resolve8(dir, compactFileId), "utf-8").catch(() => "");
       } catch {
         compactLen = 0;
       }
       const hasMarker = extractCompactFromMarker(
-        await fs18.readFile(resolve7(dir, `${meta3.outputId}.txt`), "utf-8").catch(() => "")
+        await fs18.readFile(resolve8(dir, `${meta3.outputId}.txt`), "utf-8").catch(() => "")
       ) !== null;
       const compactStale = isCompactStale(compactText, meta3.skillName, meta3.contentSha);
       const { count: hitCount } = await readSkillHits(meta3.skillName);
@@ -16105,7 +16177,7 @@ async function getSkillFilePath(skillName) {
   }
 }
 async function resolvePluginSkillPath(pluginName, skillSlug) {
-  const manifestPath = _pluginsManifestPathOverride ?? resolve7(homedir7(), ".claude", "plugins", "installed_plugins.json");
+  const manifestPath = _pluginsManifestPathOverride ?? resolve8(homedir7(), ".claude", "plugins", "installed_plugins.json");
   let raw;
   try {
     raw = await fs18.readFile(manifestPath, "utf8");
@@ -16128,7 +16200,7 @@ async function resolvePluginSkillPath(pluginName, skillSlug) {
       if (typeof entry !== "object" || entry === null) continue;
       const installPath = entry["installPath"];
       if (typeof installPath !== "string" || installPath === "") continue;
-      const diskPath = resolve7(installPath, "skills", skillSlug, "SKILL.md");
+      const diskPath = resolve8(installPath, "skills", skillSlug, "SKILL.md");
       try {
         await fs18.access(diskPath);
         return diskPath;
@@ -16147,7 +16219,7 @@ async function installedSkillPath(skillName) {
     const pluginPath = await resolvePluginSkillPath(name2.slice(0, colonIdx), name2.slice(colonIdx + 1));
     if (pluginPath !== null) return pluginPath;
   }
-  const diskPath = resolve7(skillsSourceDir(), name2, "SKILL.md");
+  const diskPath = resolve8(skillsSourceDir(), name2, "SKILL.md");
   try {
     await fs18.access(diskPath);
     return diskPath;
@@ -16167,11 +16239,11 @@ function pruneSkillOutputs(maxCount = DEFAULT_MAX_COUNT, maxAgeMs = DEFAULT_MAX_
       const outputId = file2.slice(0, -".meta".length);
       let ts;
       try {
-        const parsed = JSON.parse(readFileSync13(resolve7(dir, file2), "utf-8"));
+        const parsed = JSON.parse(readFileSync13(resolve8(dir, file2), "utf-8"));
         ts = parsed.ts;
       } catch {
         try {
-          ts = statSync8(resolve7(dir, file2)).mtimeMs;
+          ts = statSync8(resolve8(dir, file2)).mtimeMs;
         } catch {
           continue;
         }
@@ -16181,7 +16253,7 @@ function pruneSkillOutputs(maxCount = DEFAULT_MAX_COUNT, maxAgeMs = DEFAULT_MAX_
     const removeEntry = (outputId) => {
       for (const ext2 of [".meta", ".txt"]) {
         try {
-          unlinkSync9(resolve7(dir, `${outputId}${ext2}`));
+          unlinkSync9(resolve8(dir, `${outputId}${ext2}`));
         } catch {
         }
       }
@@ -16273,7 +16345,7 @@ async function ocrImage(input) {
   if (_ocrUnavailableThisProcess) return null;
   const entryPath = resolveTesseractEntry();
   if (entryPath === null) return null;
-  return new Promise((resolve24) => {
+  return new Promise((resolve25) => {
     let settled = false;
     let child;
     try {
@@ -16282,7 +16354,7 @@ async function ocrImage(input) {
       });
     } catch {
       _ocrUnavailableThisProcess = true;
-      resolve24(null);
+      resolve25(null);
       return;
     }
     const chunks = [];
@@ -16295,7 +16367,7 @@ async function ocrImage(input) {
         child.kill();
       } catch {
       }
-      resolve24(result);
+      resolve25(result);
     };
     const timer = setTimeout(() => finish(null, true), _ocrTimeoutMs);
     child.stdout?.on("data", (c) => chunks.push(c));
@@ -17537,7 +17609,7 @@ import * as readline from "node:readline";
 async function defaultConfirm(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = await new Promise((resolve24) => rl.question(question, resolve24));
+    const answer = await new Promise((resolve25) => rl.question(question, resolve25));
     return /^y(es)?$/i.test(answer.trim());
   } finally {
     rl.close();
@@ -17603,7 +17675,7 @@ function ensureTransformerLoaded() {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve24) => setTimeout(resolve24, ms));
+  return new Promise((resolve25) => setTimeout(resolve25, ms));
 }
 async function buildExtractorWithRetry(pipelineFn, modelName) {
   let lastError;
@@ -17943,7 +18015,8 @@ function rerankHits(hits, query, topK) {
       boost = Math.min(matches2 * _VERBATIM_TOKEN_BOOST, _MAX_VERBATIM_BOOST);
     }
     const penalty = _isGeneratedPath(hit.filePath) ? _GENERATED_PATH_PENALTY : 0;
-    return { hit, index, adjusted: hit.distance - boost + penalty };
+    const pathPenalty = _pathPriorityPenalty(hit.filePath);
+    return { hit, index, adjusted: hit.distance - boost + penalty + pathPenalty };
   });
   scored.sort((a, b) => a.adjusted - b.adjusted || a.index - b.index);
   return scored.slice(0, topK).map((entry) => ({ ...entry.hit, adjustedDistance: entry.adjusted }));
@@ -18069,11 +18142,26 @@ function _isGeneratedPath(filePath) {
   }
   return false;
 }
-var _require3, _transformer, _transformerError, _transformerLoadAttempted, DEFAULT_MODEL, DEFAULT_DIM, QUERY_INSTRUCTION_PREFIX, _extractorCache, _pipelineFnOverride, PIPELINE_RETRY_ATTEMPTS, PIPELINE_RETRY_DELAY_MS, DEFAULT_PIPELINE_RETRY_DELAY_MS, MIN_CHUNK_CHARS, MAX_CHUNK_CHARS, DEFAULT_DISTANCE_THRESHOLD, _GENERATED_PATH_SEGMENTS, _GENERATED_PATH_PENALTY, _VERBATIM_TOKEN_BOOST, _MAX_VERBATIM_BOOST, _TOKEN_RE, _MIN_TOKEN_LEN, OVER_FETCH_FACTOR, MAX_OVER_FETCH, BACKFILL_MULTIPLIER, _chunkVectorsUsable;
+function _pathPriorityPenalty(filePath) {
+  const segments = filePath.split(/[/\\]+/);
+  const basename22 = segments[segments.length - 1] ?? filePath;
+  const weights = loadConfig().semantic;
+  const isArchive = _ARCHIVE_FILE_RE.test(basename22) || segments.some((seg) => _ARCHIVE_PATH_SEGMENTS.has(seg.toLowerCase()));
+  if (isArchive) {
+    return 1 - weights.archive_weight;
+  }
+  const isDocs = _DOCS_FILE_RE.test(basename22) || segments.some((seg) => seg.toLowerCase() === _DOCS_DIR_SEGMENT);
+  if (isDocs) {
+    return 1 - weights.docs_weight;
+  }
+  return 0;
+}
+var _require3, _transformer, _transformerError, _transformerLoadAttempted, DEFAULT_MODEL, DEFAULT_DIM, QUERY_INSTRUCTION_PREFIX, _extractorCache, _pipelineFnOverride, PIPELINE_RETRY_ATTEMPTS, PIPELINE_RETRY_DELAY_MS, DEFAULT_PIPELINE_RETRY_DELAY_MS, MIN_CHUNK_CHARS, MAX_CHUNK_CHARS, DEFAULT_DISTANCE_THRESHOLD, _GENERATED_PATH_SEGMENTS, _GENERATED_PATH_PENALTY, _ARCHIVE_PATH_SEGMENTS, _ARCHIVE_FILE_RE, _DOCS_FILE_RE, _DOCS_DIR_SEGMENT, _VERBATIM_TOKEN_BOOST, _MAX_VERBATIM_BOOST, _TOKEN_RE, _MIN_TOKEN_LEN, OVER_FETCH_FACTOR, MAX_OVER_FETCH, BACKFILL_MULTIPLIER, _chunkVectorsUsable;
 var init_embeddings = __esm({
   "src/embeddings.ts"() {
     "use strict";
     init_define_import_meta_env();
+    init_config();
     init_sql_path();
     init_util2();
     init_reset();
@@ -18122,6 +18210,17 @@ var init_embeddings = __esm({
       ".ruff_cache"
     ]);
     _GENERATED_PATH_PENALTY = 0.5;
+    _ARCHIVE_PATH_SEGMENTS = /* @__PURE__ */ new Set([
+      "archive",
+      "archived",
+      "old",
+      "deprecated",
+      "plans",
+      "drafts"
+    ]);
+    _ARCHIVE_FILE_RE = /(^changelog|\.bak$|\.orig$)/i;
+    _DOCS_FILE_RE = /\.md$/i;
+    _DOCS_DIR_SEGMENT = "docs";
     _VERBATIM_TOKEN_BOOST = 0.05;
     _MAX_VERBATIM_BOOST = 0.25;
     _TOKEN_RE = /\w+/g;
@@ -18664,14 +18763,32 @@ function fetchTopSymbols(limit, dbPath, rootDir) {
   try {
     const db = getDb(dbPath);
     const { clause, param } = projectScopeClause("file_path");
+    const refScope = projectScopeClause("file_path");
     const rows = db.prepare(
+      // refs carry only a bare name, so a name defined N times cannot claim all N copies' references: divide by the number of same-named definitions, and keep one representative per name so a generic helper like `apply` occupies one slot instead of seven.
       `SELECT file_path, name, kind, line_start, line_end, body, docstring, parent
-         FROM symbols
-         WHERE kind IN ('class', 'function', 'interface') AND ${clause}
-         ORDER BY CASE kind WHEN 'class' THEN 0 WHEN 'interface' THEN 1 ELSE 2 END,
+         FROM (
+           SELECT s.file_path, s.name, s.kind, s.line_start, s.line_end, s.body, s.docstring, s.parent,
+                  COALESCE(r.ref_count, 0) * 1.0 / COUNT(*) OVER (PARTITION BY s.name) AS score,
+                  ROW_NUMBER() OVER (
+                    PARTITION BY s.name
+                    ORDER BY LENGTH(COALESCE(s.body, '')) DESC, s.file_path
+                  ) AS rn
+           FROM symbols s
+           LEFT JOIN (
+             SELECT name, COUNT(*) AS ref_count
+             FROM refs
+             WHERE ${refScope.clause}
+             GROUP BY name
+           ) r ON r.name = s.name
+           WHERE s.kind IN ('class', 'function', 'interface') AND ${clause}
+         )
+         WHERE rn = 1
+         ORDER BY score DESC,
+                  CASE kind WHEN 'class' THEN 0 WHEN 'interface' THEN 1 ELSE 2 END,
                   LENGTH(COALESCE(body, '')) DESC
          LIMIT ?`
-    ).all(param(rootDir), limit);
+    ).all(refScope.param(rootDir), param(rootDir), limit);
     return rows.map((r) => ({
       filePath: r.file_path,
       name: r.name,
@@ -18723,13 +18840,12 @@ function formatProjectMap(map3, compact = false) {
     lines2.push("");
     lines2.push("## Top symbols");
     for (const s of map3.topSymbols) {
-      if (compact) {
-        lines2.push(`- ${s.name} (${s.kind})`);
-      } else {
-        const loc = `${path25.basename(s.filePath)}:${s.lineStart}-${s.lineEnd}`;
-        lines2.push(`- ${s.name} (${s.kind}) \u2014 ${loc}`);
-      }
+      const loc = `${toDisplayPath(map3.rootDir, s.filePath)}:${s.lineStart}-${s.lineEnd}`;
+      lines2.push(`- ${s.name} (${s.kind}) \u2014 ${loc}`);
     }
+  } else {
+    lines2.push("");
+    lines2.push("## Top symbols: none \u2014 no files indexed for this project; run 'token-goat index .'");
   }
   if (!compact && map3.recentFiles.length > 0) {
     lines2.push("");
@@ -24655,10 +24771,10 @@ function embedFileSerialized(absPath, dbPath, sha) {
       activeEmbedSlots += 1;
       return dispatchEmbed();
     }
-    return new Promise((resolve24) => {
+    return new Promise((resolve25) => {
       embedSlotWaiters.push(() => {
         activeEmbedSlots += 1;
-        resolve24(dispatchEmbed());
+        resolve25(dispatchEmbed());
       });
     });
   };
@@ -25064,7 +25180,7 @@ async function runWorkerLoop(dir, pollIntervalMs, shouldStop = () => false) {
       lastKnownRootsSweepMs = Date.now();
     }
     if (shouldStop()) break;
-    await new Promise((resolve24) => setTimeout(resolve24, pollIntervalMs));
+    await new Promise((resolve25) => setTimeout(resolve25, pollIntervalMs));
   }
 }
 function runDetachedWorkerDaemon() {
@@ -25750,6 +25866,11 @@ function isDeadSymbol(name2, refCount) {
   if (ENTRY_NAMES.has(name2)) return false;
   return refCount === 0;
 }
+function parseGraphSymbolSpec(spec) {
+  const colonIdx = findSpecSeparator(spec);
+  if (colonIdx === -1) return { name: spec };
+  return { name: spec.slice(colonIdx + 2), file: spec.slice(0, colonIdx) };
+}
 function buildFileSymCache() {
   const cache = /* @__PURE__ */ new Map();
   return (fp) => {
@@ -25767,9 +25888,10 @@ function fileDefinesName(fp, name2, getSyms) {
 function filterRefsForSymbol(refs, name2, filePath, getSyms) {
   return refs.filter((ref2) => ref2.filePath === filePath || !fileDefinesName(ref2.filePath, name2, getSyms));
 }
-function resolveCallers(name2, limit, filePath, rootDir) {
+function resolveCallers(name2, limit, filePath, rootDir, excludeTests) {
   const resolvedRootDir = rootDir ?? resolveProjectRoot({ project: process.cwd() });
-  const refs = queryRefs({ name: name2, limit: limit ?? 500, rootDir: resolvedRootDir });
+  const queryLimit = excludeTests === true ? UNBOUNDED_REF_LIMIT : limit ?? 500;
+  const refs = queryRefs({ name: name2, limit: queryLimit, rootDir: resolvedRootDir });
   const getSyms = buildFileSymCache();
   const scoped = filePath === void 0 ? refs : filterRefsForSymbol(refs, name2, filePath, getSyms);
   return scoped.map((ref2) => {
@@ -25788,17 +25910,37 @@ function runCallers(opts) {
     return 1;
   }
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const entries = resolveCallers(opts.symbol, opts.limit, void 0, rootDir);
+  const { name: name2, file: file2 } = parseGraphSymbolSpec(opts.symbol);
+  const fileHint = file2 !== void 0 ? resolveIndexPath(file2, rootDir) : void 0;
+  if (fileHint !== void 0 && querySymbols({ name: name2, filePath: fileHint, limit: 1 }).length === 0) {
+    emitErr(`Symbol '${name2}' not found in '${file2}'`);
+    return 1;
+  }
+  const resolved = resolveCallers(name2, opts.limit, fileHint, rootDir, opts.excludeTests);
+  const suppressed = opts.excludeTests === true ? resolved.filter((e) => isTestFile(e.file)).length : 0;
+  const entries = opts.excludeTests === true ? resolved.filter((e) => !isTestFile(e.file)).slice(0, opts.limit ?? 500) : resolved;
   if (entries.length === 0) {
+    if (opts.excludeTests === true && suppressed > 0) {
+      emitErr(`No non-test references found for '${opts.symbol}' (${suppressed} in test files hidden by --exclude-tests)`);
+      return 1;
+    }
     emitErr(`No references found for '${opts.symbol}'`);
     return 1;
   }
+  const contextLines = opts.context ?? 0;
   if (opts.json === true) {
-    emit2(JSON.stringify(entries, null, 2));
+    const payload = contextLines > 0 ? entries.map((e) => ({ ...e, contextLines: buildContextWindow(e.file, e.line, contextLines) ?? [] })) : entries;
+    emit2(JSON.stringify(payload, null, 2));
     return 0;
   }
+  if (opts.excludeTests === true && suppressed > 0) {
+    emit2(`${entries.length} callers found (${suppressed} in test files hidden by --exclude-tests)`);
+  }
   for (const e of entries) {
-    emit2(`${e.caller}	${toDisplayPath(rootDir, e.file)}:${e.line}`);
+    const displayPath = toDisplayPath(rootDir, e.file);
+    emit2(`${e.caller}	${displayPath}:${e.line}`);
+    const window = buildContextWindow(e.file, e.line, contextLines);
+    if (window !== null) for (const l of renderContextWindow(displayPath, e.line, window, "", "    ")) emit2(l);
   }
   return 0;
 }
@@ -25809,28 +25951,36 @@ function runCallChain(opts) {
   }
   const maxDepth = opts.depth ?? 8;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  if (querySymbols({ name: opts.symbol, rootDir, limit: 1 }).length === 0) {
+  const { name: name2, file: file2 } = parseGraphSymbolSpec(opts.symbol);
+  const fileHint = file2 !== void 0 ? resolveIndexPath(file2, rootDir) : void 0;
+  if (fileHint !== void 0) {
+    if (querySymbols({ name: name2, filePath: fileHint, limit: 1 }).length === 0) {
+      emitErr(`Symbol '${name2}' not found in '${file2}'`);
+      return 1;
+    }
+  } else if (querySymbols({ name: name2, rootDir, limit: 1 }).length === 0) {
     emitErr(`Symbol not found: ${opts.symbol}`);
     return 1;
   }
   const getSyms = buildFileSymCache();
-  const callersOf = (name2) => {
-    const refs = queryRefs({ name: name2, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
+  const callersOf = (n) => {
+    const refs = queryRefs({ name: n, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
     if (refs.length === 0) return [];
+    const scoped = fileHint !== void 0 && n === name2 ? filterRefsForSymbol(refs, n, fileHint, getSyms) : refs;
     const names = /* @__PURE__ */ new Set();
-    for (const ref2 of refs) {
+    for (const ref2 of scoped) {
       const enc = enclosingSymbol(getSyms(ref2.filePath), ref2.line);
       if (enc !== null) names.add(enc.name);
     }
     return [...names];
   };
-  const chains = bfsCallChains(opts.symbol, callersOf, maxDepth);
+  const chains = bfsCallChains(name2, callersOf, maxDepth);
   if (opts.json === true) {
     emit2(JSON.stringify({ chains }, null, 2));
     return 0;
   }
-  if (chains.length === 1 && chains[0]?.length === 1 && chains[0][0] === opts.symbol) {
-    emit2(`${opts.symbol}  (no callers)`);
+  if (chains.length === 1 && chains[0]?.length === 1 && chains[0][0] === name2) {
+    emit2(`${name2}  (no callers)`);
     return 0;
   }
   for (const chain2 of chains) {
@@ -25850,16 +26000,23 @@ function runImpact(opts) {
   const top = opts.top ?? 20;
   const DEPTH_CAP = 8;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
+  const { name: rootName, file: file2 } = parseGraphSymbolSpec(opts.symbol);
+  const fileHint = file2 !== void 0 ? resolveIndexPath(file2, rootDir) : void 0;
+  if (fileHint !== void 0 && querySymbols({ name: rootName, filePath: fileHint, limit: 1 }).length === 0) {
+    emitErr(`Symbol '${rootName}' not found in '${file2}'`);
+    return 1;
+  }
   const getSyms = buildFileSymCache();
-  const hops = /* @__PURE__ */ new Map([[opts.symbol, 0]]);
-  const queue = [[opts.symbol, 0]];
+  const hops = /* @__PURE__ */ new Map([[rootName, 0]]);
+  const queue = [[rootName, 0]];
   while (queue.length > 0) {
     const item = queue.shift();
     if (item === void 0) break;
     const [name2, depth] = item;
     if (depth >= DEPTH_CAP) continue;
     const refs = queryRefs({ name: name2, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
-    for (const ref2 of refs) {
+    const scoped = fileHint !== void 0 && name2 === rootName ? filterRefsForSymbol(refs, name2, fileHint, getSyms) : refs;
+    for (const ref2 of scoped) {
       const newHop = depth + 1;
       const enc = enclosingSymbol(getSyms(ref2.filePath), ref2.line);
       if (enc === null) {
@@ -25876,7 +26033,7 @@ function runImpact(opts) {
       }
     }
   }
-  hops.delete(opts.symbol);
+  hops.delete(rootName);
   const sorted = [...hops.entries()].sort(compareHopEntries).slice(0, top);
   if (sorted.length === 0) {
     emitErr(`No callers found for '${opts.symbol}'`);
@@ -25928,6 +26085,7 @@ function runDead(opts) {
   const syms = querySymbols({ kind, limit: 5e3, rootDir });
   const getSyms = buildFileSymCache();
   const results = [];
+  let suppressed = 0;
   for (const sym of syms) {
     if (opts.includePrivate !== true && sym.name.startsWith("_")) continue;
     const refs = queryRefs({ name: sym.name, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
@@ -25937,6 +26095,10 @@ function runDead(opts) {
       const ownScope = enclosingNamedScope(getSyms(sym.filePath), sym.lineStart);
       if (ownScope !== null && hasAncestorDispatchRef(sym.name, ownScope.name, sym.filePath, rootDir)) continue;
     }
+    if (opts.excludeTests === true && isTestFile(sym.filePath)) {
+      suppressed += 1;
+      continue;
+    }
     results.push({ name: sym.name, kind: sym.kind, file: sym.filePath, line: sym.lineStart });
   }
   const sliced = results.slice(0, opts.top ?? results.length);
@@ -25945,9 +26107,16 @@ function runDead(opts) {
     return 0;
   }
   if (sliced.length === 0) {
-    emit2("No dead symbols found.");
+    if (opts.excludeTests === true && suppressed > 0) {
+      emit2(`No dead symbols found (${suppressed} in test files hidden by --exclude-tests).`);
+    } else {
+      emit2("No dead symbols found.");
+    }
     return 0;
   }
+  if (opts.excludeTests === true && suppressed > 0) {
+    emit2(`${sliced.length} dead symbols (${suppressed} in test files hidden by --exclude-tests)`);
+  }
   for (const r of sliced) {
     emit2(`${r.name}	${toDisplayPath(rootDir, r.file)}:${r.line}`);
   }
@@ -26197,16 +26366,9 @@ function runSimilar(opts) {
     emitErr(`Invalid spec - expected "file::symbol", got: ${opts.spec}`);
     return 1;
   }
-  const fileArg = opts.spec.slice(0, sepIdx);
-  const symbolArg = opts.spec.slice(sepIdx + 2);
   const top = opts.top ?? 10;
-  const filePath = resolveIndexPath(fileArg);
-  const anchors = querySymbols({ name: symbolArg, filePath });
-  if (anchors.length === 0) {
-    emitErr(`Symbol '${symbolArg}' not found in '${fileArg}'`);
-    return 1;
-  }
-  const anchor = anchors[0];
+  const anchor = resolveSymbolSpecOrEmitError("similar", opts.spec, void 0);
+  if (anchor === null) return 1;
   const words = [anchor.name, ...(anchor.docstring ?? "").split(/\s+/).filter((w) => w.length > 4)];
   const query = words.slice(0, 8).join(" ");
   const rootDir = resolveProjectRoot({ project: process.cwd() });
@@ -26238,13 +26400,13 @@ function runContextFor(opts) {
     const bodyTokens = estimateTokens(h.body ?? "");
     if (budget !== void 0 && tokensSoFar + bodyTokens > budget) continue;
     tokensSoFar += bodyTokens;
-    entries.push({ file: h.filePath, symbol: h.name, kind: h.kind, readCmd: `token-goat read "${h.filePath}::${h.name}"` });
+    entries.push({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` });
   }
   if (opts.json === true) {
     emit2(JSON.stringify(entries, null, 2));
     return 0;
   }
-  for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}"`);
+  for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}@${e.line}"`);
   return 0;
 }
 function runTestFor(opts) {
@@ -26389,16 +26551,10 @@ function runBlame(opts) {
     emitErr(`Invalid spec - expected "file::symbol", got: ${opts.spec}`);
     return 1;
   }
-  const fileArg = opts.spec.slice(0, sepIdx);
-  const symbolArg = opts.spec.slice(sepIdx + 2);
   const cwd = opts.cwd ?? process.cwd();
-  const filePath = resolveIndexPath(fileArg);
-  const syms = querySymbols({ name: symbolArg, filePath });
-  if (syms.length === 0) {
-    emitErr(`Symbol '${symbolArg}' not found in '${fileArg}'`);
-    return 1;
-  }
-  const sym = syms[0];
+  const sym = resolveSymbolSpecOrEmitError("blame", opts.spec, void 0);
+  if (sym === null) return 1;
+  const filePath = sym.filePath;
   const start = sym.lineStart;
   const end = sym.lineEnd;
   let raw;
@@ -26419,10 +26575,10 @@ function runBlame(opts) {
       if (!m) return { raw: l };
       return { commit: m[1], author: (m[2] ?? "").trim(), date: (m[3] ?? "").trim(), line: Number.parseInt(m[4] ?? "0", 10), content: m[5] };
     });
-    emit2(JSON.stringify({ symbol: symbolArg, file: filePath, lines: lines2 }, null, 2));
+    emit2(JSON.stringify({ symbol: sym.name, file: filePath, lines: lines2 }, null, 2));
     return 0;
   }
-  emit2(`${symbolArg}	${toDisplayPath(getDisplayRoot(opts.cwd), filePath)}:${start}-${end}`);
+  emit2(`${sym.name}	${toDisplayPath(getDisplayRoot(opts.cwd), filePath)}:${start}-${end}`);
   emit2(raw.trim());
   return 0;
 }
@@ -26436,14 +26592,14 @@ function runAsk(opts) {
   const hits = searchSymbolsFts(opts.question, top, void 0, rootDir);
   const BACKEND_ENV = "TOKEN_GOAT_ASK_BACKEND";
   const backendLabel = process.env[BACKEND_ENV] ?? "";
-  const entries = hits.map((h) => ({ file: h.filePath, symbol: h.name, kind: h.kind, readCmd: `token-goat read "${h.filePath}::${h.name}"` }));
+  const entries = hits.map((h) => ({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` }));
   const degrade = () => {
     if (opts.json === true) {
       emit2(JSON.stringify({ degraded: true, note: `Set ${BACKEND_ENV}=claude|codex for LLM synthesis`, context: entries }, null, 2));
       return 0;
     }
     emit2(`[degraded mode - set ${BACKEND_ENV}=claude|codex for LLM synthesis]`);
-    for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}"`);
+    for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}@${e.line}"`);
     return 0;
   };
   if (!backendLabel) return degrade();
@@ -30426,6 +30582,42 @@ function formatBareNameSpecError(command, name2, projectRoot) {
   }
   return lines2.join("\n");
 }
+function formatCrossFileLead(command, name2, excludeFilePath, projectRoot) {
+  const rootDir = projectRoot ?? process.cwd();
+  const matches2 = querySymbols({ name: name2, limit: 50, rootDir });
+  const excludeResolved = resolveIndexPath(excludeFilePath, rootDir);
+  const seen = /* @__PURE__ */ new Set();
+  const specs = [];
+  for (const m of matches2) {
+    if (foldPath(m.filePath) === foldPath(excludeResolved)) continue;
+    const spec = `${toDisplayPath(rootDir, m.filePath)}::${m.name}`;
+    if (seen.has(spec)) continue;
+    seen.add(spec);
+    specs.push(spec);
+  }
+  if (specs.length === 0) return "";
+  const firstSpec = specs[0];
+  const lines2 = [`'${name2}' is defined in ${firstSpec !== void 0 ? firstSpec.split("::")[0] : ""}`];
+  for (const spec of specs.slice(0, DIDYOUMEAN_LIMIT)) {
+    lines2.push(`  - token-goat ${command} "${spec}"`);
+  }
+  if (specs.length > DIDYOUMEAN_LIMIT) {
+    lines2.push(`  (${specs.length - DIDYOUMEAN_LIMIT} more not shown)`);
+  }
+  return lines2.join("\n");
+}
+function resolveEnclosingSymbol(filePath, chunkStartLine) {
+  const symbols = querySymbols({ filePath, limit: 1e5 }, globalDbPath());
+  let best = null;
+  for (const s of symbols) {
+    if (s.lineStart <= chunkStartLine && chunkStartLine <= s.lineEnd) {
+      if (best === null || s.lineEnd - s.lineStart < best.lineEnd - best.lineStart) {
+        best = s;
+      }
+    }
+  }
+  return best === null ? null : { name: best.name, kind: best.kind };
+}
 function trimBlankLines(lines2) {
   let start = 0;
   let end = lines2.length;
@@ -30521,10 +30713,21 @@ function parseCrossFileMultiSpec(spec) {
   }
   return pairs.length > 1 ? pairs : null;
 }
+function parseMultiFileSpec(spec) {
+  if (!spec.includes(",")) return null;
+  if (fileExists(spec)) return null;
+  if (findSpecSeparator(spec) !== -1) return null;
+  const parts = spec.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return parts.length > 1 ? parts : null;
+}
+function extraFileArgsNote(command, first2, extras) {
+  return `Note: ${extras.length} extra file argument(s) ignored (${extras.join(", ")}). ${command} reads one file, or a comma-separated list: token-goat ${command} "${[first2, ...extras].join(",")}"`;
+}
 function parseLineRange(spec) {
   const m = /^(.+)@(\d+)(?:-(\d+))?$/.exec(spec);
   if (m === null) return null;
   if (fileExists(spec)) return null;
+  if (m[1].includes("::")) return null;
   const start = parseInt(m[2], 10);
   const end = m[3] !== void 0 ? parseInt(m[3], 10) : start;
   return { file: m[1], start, end };
@@ -30583,30 +30786,49 @@ function findParentName(entry, fileSymbols) {
   if (doc !== "" && PARENT_IDENTIFIER_RE.test(doc)) return doc;
   return null;
 }
-function formatAmbiguity(symbol3, file2, candidates, explicitRoot) {
+function formatAmbiguity(symbol3, file2, candidates, explicitRoot, commandName = "read") {
   const multiFile = new Set(candidates.map((c) => c.filePath)).size > 1;
   const displayRoot = getDisplayRoot(explicitRoot);
   const lines2 = [
     `Ambiguous symbol '${symbol3}' in '${file2}': ${candidates.length} definitions match. Retry with one of the qualified commands below to pick one:`
   ];
   const fileSymCache = /* @__PURE__ */ new Map();
-  for (const c of candidates) {
-    let fileSyms = fileSymCache.get(c.filePath);
+  const getFileSyms = (filePath) => {
+    let fileSyms = fileSymCache.get(filePath);
     if (fileSyms === void 0) {
-      fileSyms = querySymbols({ filePath: c.filePath, limit: 1e3 });
-      fileSymCache.set(c.filePath, fileSyms);
+      fileSyms = querySymbols({ filePath, limit: 1e3 });
+      fileSymCache.set(filePath, fileSyms);
     }
-    const parent = findParentName(c, fileSyms);
-    const qualifier = parent !== null ? `${parent}.${symbol3}` : symbol3;
+    return fileSyms;
+  };
+  const parents = candidates.map((c) => findParentName(c, getFileSyms(c.filePath)));
+  const plainQualifiers = candidates.map((c, i) => parents[i] !== null ? `${parents[i]}.${symbol3}` : symbol3);
+  const qualifierCounts = /* @__PURE__ */ new Map();
+  const fileGroupSize = /* @__PURE__ */ new Map();
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
+    const key = `${c.filePath} ${plainQualifiers[i]}`;
+    qualifierCounts.set(key, (qualifierCounts.get(key) ?? 0) + 1);
+    fileGroupSize.set(c.filePath, (fileGroupSize.get(c.filePath) ?? 0) + 1);
+  }
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
+    const parent = parents[i];
+    const plainQualifier = plainQualifiers[i];
+    const collides = (qualifierCounts.get(`${c.filePath} ${plainQualifier}`) ?? 0) > 1 || parent === null && (fileGroupSize.get(c.filePath) ?? 0) > 1;
+    const qualifier = collides ? `${plainQualifier}@${c.lineStart}` : plainQualifier;
     const retryFile = multiFile ? toDisplayPath(displayRoot, c.filePath) : file2;
     const label = multiFile ? `${toDisplayPath(displayRoot, c.filePath)}::${qualifier}` : qualifier;
-    lines2.push(`  - ${label} (line ${c.lineStart})  ->  token-goat read "${retryFile}::${qualifier}"`);
+    lines2.push(`  - ${label} (line ${c.lineStart})  ->  token-goat ${commandName} "${retryFile}::${qualifier}"`);
   }
   return lines2.join("\n");
 }
 function resolveSymbolSpec(spec, forceRefresh, projectRoot) {
-  const { file: file2, symbol: symbol3 } = parseReadSpec(spec);
-  if (symbol3 === void 0 || symbol3 === "") return { kind: "none" };
+  const { file: file2, symbol: rawSymbol } = parseReadSpec(spec);
+  if (rawSymbol === void 0 || rawSymbol === "") return { kind: "none" };
+  const anchorMatch = /^(.+)@(\d+)$/.exec(rawSymbol);
+  const symbol3 = anchorMatch !== null ? anchorMatch[1] : rawSymbol;
+  const lineAnchor = anchorMatch !== null ? parseInt(anchorMatch[2], 10) : void 0;
   const resolved = resolveIndexPath(file2, projectRoot ?? process.cwd());
   if (forceRefresh === true) {
     indexFileSync(resolved, globalDbPath());
@@ -30623,9 +30845,10 @@ function resolveSymbolSpec(spec, forceRefresh, projectRoot) {
       seen.add(key);
       distinct.push(c);
     }
-    if (distinct.length === 0) return { kind: "none" };
-    if (distinct.length === 1) return { kind: "ok", entry: distinct[0] };
-    return { kind: "ambiguous", symbol: displaySymbol, file: file2, candidates: distinct };
+    const anchored = lineAnchor === void 0 ? distinct : distinct.filter((c) => c.lineStart === lineAnchor);
+    if (anchored.length === 0) return { kind: "none" };
+    if (anchored.length === 1) return { kind: "ok", entry: anchored[0] };
+    return { kind: "ambiguous", symbol: displaySymbol, file: file2, candidates: anchored };
   };
   if (symbol3.includes(".")) {
     const exactMatch = querySymbols({ name: symbol3, filePath: resolved, limit: 10 });
@@ -30705,6 +30928,8 @@ function runRead(opts) {
       return runLineRange({ file: file2, start: lineSpec.start, end: lineSpec.end }, opts);
     }
     const messages = [`Symbol '${symbol3}' not found in '${file2}'`];
+    const crossFileLead = formatCrossFileLead("read", symbol3, file2, opts.projectRoot);
+    if (crossFileLead !== "") messages.push(crossFileLead);
     const resolved = resolveIndexPath(file2, opts.projectRoot ?? process.cwd());
     const closes = querySymbols({ filePath: resolved, limit: DIDYOUMEAN_LIMIT }).map((s) => s.name);
     if (closes.length > 0) messages.push(didYouMean(closes));
@@ -30765,6 +30990,8 @@ ${sub.text}`);
   return { text, code: 1 };
 }
 function runSection(opts) {
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) return runSectionCrossFile(crossFilePairs, opts);
   const colonIdx = findSpecSeparator(opts.spec);
   if (colonIdx === -1) {
     return { text: `Invalid section spec \u2014 expected "file::Heading", got: ${opts.spec}`, code: 1 };
@@ -30821,6 +31048,42 @@ ${sub.text}`);
   if (anyFound) recordReadStat("section_read", fullSourceBytes, text, opts.spec);
   return { text, code: anyFound ? 0 : 1 };
 }
+function runSectionCrossFile(pairs, opts) {
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  for (const { file: file2, symbol: heading } of pairs) {
+    const sub = runSection({ ...opts, spec: `${file2}::${heading}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    const key = keyFor({ file: file2, symbol: heading });
+    if (opts.json === true) {
+      jsonOut[key] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${key}:
+${sub.text}`);
+  }
+  const resolvePath = (f) => opts.projectRoot !== void 0 && !path48.isAbsolute(f) ? path48.resolve(opts.projectRoot, f) : f;
+  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  if (anyFound) {
+    const fullSourceBytes = sumFileSizes(Array.from(distinctFiles, resolvePath));
+    recordReadStat("section_read", fullSourceBytes, text, opts.spec);
+  }
+  return { text, code: anyFound ? 0 : 1 };
+}
+function renderRefLines(ref2, displayRoot, contextLines, indent = "  ") {
+  const displayPath = toDisplayPath(displayRoot, ref2.filePath);
+  const base = `${indent}${displayPath}:${ref2.line}: ${ref2.context}`;
+  const window = buildContextWindow(ref2.filePath, ref2.line, contextLines);
+  if (window === null) return [base];
+  return [base, ...renderContextWindow(displayPath, ref2.line, window, "", `${indent}  `)];
+}
+function withContextLines(items, contextLines) {
+  if (!(contextLines > 0)) return items;
+  return items.map((r) => ({ ...r, contextLines: buildContextWindow(r.filePath, r.line, contextLines) ?? [] }));
+}
 function applyTypedRefsTier(symName, file2, results) {
   if (results.length === 0) return results;
   try {
@@ -30858,6 +31121,8 @@ function runRefs(opts) {
     emitErr2(`--top must be a positive number, got: ${opts.top}`);
     return 1;
   }
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) return runRefsCrossFile(crossFilePairs, opts);
   const { file: file2, symbols } = parseMultiRefsSpec(opts.spec);
   if (symbols.length <= 1) return runRefsSingle(opts);
   const jsonOut = {};
@@ -30866,10 +31131,18 @@ function runRefs(opts) {
   const refFilePaths = [];
   for (const sym of symbols) {
     const queryOpts = { name: sym };
-    if (file2 !== void 0 && opts.callers !== true) queryOpts.filePath = resolveIndexPath(file2);
-    if (opts.limit !== void 0) queryOpts.limit = opts.limit;
+    if (opts.excludeTests === true) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
+    else if (opts.limit !== void 0) queryOpts.limit = opts.limit;
     else if (opts.top !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
-    const results = applyTypedRefsTier(sym, file2, queryRefs(queryOpts));
+    let results = applyTypedRefsTier(sym, file2, queryRefs(queryOpts));
+    let suppressed = 0;
+    let filteredTotal;
+    if (opts.excludeTests === true) {
+      const f = applyExcludeTestsFilter(results);
+      suppressed = f.suppressed;
+      filteredTotal = f.refs.length;
+      results = opts.top !== void 0 ? f.refs : f.refs.slice(0, opts.limit ?? 100);
+    }
     if (results.length > 0) anyFound = true;
     refFilePaths.push(...results.map((r) => r.filePath));
     if (opts.json === true) {
@@ -30877,22 +31150,85 @@ function runRefs(opts) {
         jsonOut[sym] = topFilesJsonPayload(results, opts.top);
       } else {
         const capped = guardJsonRows(results);
-        const trueTotal = countRefs(queryOpts);
-        jsonOut[sym] = { items: capped.items, truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
+        const trueTotal = opts.excludeTests === true ? filteredTotal ?? results.length : countRefs(queryOpts);
+        jsonOut[sym] = { items: withContextLines(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
       }
       continue;
     }
     if (results.length === 0) {
-      lines2.push(`${sym}: (no references found)`);
+      lines2.push(opts.excludeTests === true && suppressed > 0 ? `${sym}: (no non-test references found; ${suppressed} in test files hidden by --exclude-tests)` : `${sym}: (no references found)`);
       continue;
     }
     lines2.push(`${sym}:`);
     if (opts.top !== void 0) {
-      lines2.push(...renderTopFilesSummary(results, opts.top));
+      lines2.push(...renderTopFilesSummary(results, opts.top, void 0, suppressed));
+    } else if (opts.callers === true) {
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      lines2.push(...renderCallerGroups(results, void 0, opts.context ?? 0));
+    } else {
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      for (const ref2 of results) lines2.push(...renderRefLines(ref2, void 0, opts.context ?? 0));
+    }
+  }
+  const fullSourceBytes = sumFileSizes(refFilePaths);
+  if (opts.json === true) {
+    const text2 = JSON.stringify(jsonOut, null, 2);
+    emit3(text2);
+    if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text2, opts.spec);
+    return anyFound ? 0 : 1;
+  }
+  const text = lines2.join("\n");
+  emitGuarded(text, "symbol");
+  if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text, opts.spec);
+  return anyFound ? 0 : 1;
+}
+function runRefsCrossFile(pairs, opts) {
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  const jsonOut = {};
+  let anyFound = false;
+  const lines2 = [];
+  const refFilePaths = [];
+  for (const { file: file2, symbol: symbol3 } of pairs) {
+    const key = keyFor({ file: file2, symbol: symbol3 });
+    const queryOpts = { name: symbol3 };
+    if (opts.excludeTests === true) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
+    else if (opts.limit !== void 0) queryOpts.limit = opts.limit;
+    else if (opts.top !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
+    let results = applyTypedRefsTier(symbol3, file2, queryRefs(queryOpts));
+    let suppressed = 0;
+    let filteredTotal;
+    if (opts.excludeTests === true) {
+      const f = applyExcludeTestsFilter(results);
+      suppressed = f.suppressed;
+      filteredTotal = f.refs.length;
+      results = opts.top !== void 0 ? f.refs : f.refs.slice(0, opts.limit ?? 100);
+    }
+    if (results.length > 0) anyFound = true;
+    refFilePaths.push(...results.map((r) => r.filePath));
+    if (opts.json === true) {
+      if (opts.top !== void 0) {
+        jsonOut[key] = topFilesJsonPayload(results, opts.top);
+      } else {
+        const capped = guardJsonRows(results);
+        const trueTotal = opts.excludeTests === true ? filteredTotal ?? results.length : countRefs(queryOpts);
+        jsonOut[key] = { items: withContextLines(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
+      }
+      continue;
+    }
+    if (results.length === 0) {
+      lines2.push(opts.excludeTests === true && suppressed > 0 ? `${key}: (no non-test references found; ${suppressed} in test files hidden by --exclude-tests)` : `${key}: (no references found)`);
+      continue;
+    }
+    lines2.push(`${key}:`);
+    if (opts.top !== void 0) {
+      lines2.push(...renderTopFilesSummary(results, opts.top, void 0, suppressed));
     } else if (opts.callers === true) {
-      lines2.push(...renderCallerGroups(results));
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      lines2.push(...renderCallerGroups(results, void 0, opts.context ?? 0));
     } else {
-      for (const ref2 of results) lines2.push(`  ${ref2.filePath}:${ref2.line}: ${ref2.context}`);
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      for (const ref2 of results) lines2.push(...renderRefLines(ref2, void 0, opts.context ?? 0));
     }
   }
   const fullSourceBytes = sumFileSizes(refFilePaths);
@@ -30912,11 +31248,23 @@ function runRefsSingle(opts) {
   const symName = symbol3 ?? file2;
   const queryOpts = { name: symName };
   const defFileHint = symbol3 !== void 0 ? resolveIndexPath(file2) : void 0;
-  if (defFileHint !== void 0 && opts.callers !== true) queryOpts.filePath = defFileHint;
-  if (opts.limit !== void 0) queryOpts.limit = opts.limit;
+  if (opts.excludeTests === true) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
+  else if (opts.limit !== void 0) queryOpts.limit = opts.limit;
   else if (opts.top !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
-  const results = applyTypedRefsTier(symName, defFileHint, queryRefs(queryOpts));
+  let results = applyTypedRefsTier(symName, defFileHint, queryRefs(queryOpts));
+  let suppressed = 0;
+  let filteredTotal;
+  if (opts.excludeTests === true) {
+    const f = applyExcludeTestsFilter(results);
+    suppressed = f.suppressed;
+    filteredTotal = f.refs.length;
+    results = opts.top !== void 0 ? f.refs : f.refs.slice(0, opts.limit ?? 100);
+  }
   if (results.length === 0) {
+    if (opts.excludeTests === true && suppressed > 0) {
+      emitErr2(`No non-test references found for '${symName}' (${suppressed} in test files hidden by --exclude-tests)`);
+      return 1;
+    }
     emitErr2(`No references found for '${symName}'`);
     return 1;
   }
@@ -30927,8 +31275,8 @@ function runRefsSingle(opts) {
       payload = topFilesJsonPayload(results, opts.top);
     } else {
       const capped = guardJsonRows(results);
-      const trueTotal = countRefs(queryOpts);
-      payload = { items: capped.items, truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
+      const trueTotal = opts.excludeTests === true ? filteredTotal ?? results.length : countRefs(queryOpts);
+      payload = { items: withContextLines(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
     }
     const text2 = JSON.stringify(payload, null, 2);
     emit3(text2);
@@ -30936,21 +31284,26 @@ function runRefsSingle(opts) {
     return 0;
   }
   const displayRoot = getDisplayRoot();
-  const lines2 = opts.top !== void 0 ? renderTopFilesSummary(results, opts.top, displayRoot) : opts.callers === true ? renderCallerGroups(results, displayRoot) : results.map((ref2) => `${toDisplayPath(displayRoot, ref2.filePath)}:${ref2.line}: ${ref2.context}`);
+  const lines2 = opts.top !== void 0 ? renderTopFilesSummary(results, opts.top, displayRoot, suppressed) : opts.callers === true ? [...opts.excludeTests === true && suppressed > 0 ? [`${results.length} references (${suppressed} in test files hidden by --exclude-tests)`] : [], ...renderCallerGroups(results, displayRoot, opts.context ?? 0)] : [...opts.excludeTests === true && suppressed > 0 ? [`${results.length} references (${suppressed} in test files hidden by --exclude-tests)`] : [], ...results.flatMap((ref2) => renderRefLines(ref2, displayRoot, opts.context ?? 0, ""))];
   const text = lines2.join("\n");
   emitGuarded(text, "symbol");
   recordReadStat("symbol_read", fullSourceBytes, text, symName);
   return 0;
 }
+function applyExcludeTestsFilter(refs) {
+  const filtered = refs.filter((r) => !isTestFile(r.filePath));
+  return { refs: filtered, suppressed: refs.length - filtered.length };
+}
 function groupRefsByFile(refs) {
   const byFile = /* @__PURE__ */ new Map();
   for (const ref2 of refs) byFile.set(ref2.filePath, (byFile.get(ref2.filePath) ?? 0) + 1);
   return [...byFile.entries()].map(([file2, count]) => ({ file: file2, count })).sort((a, b) => b.count - a.count || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
 }
-function renderTopFilesSummary(refs, topN, displayRoot) {
+function renderTopFilesSummary(refs, topN, displayRoot, suppressed) {
   const grouped = groupRefsByFile(refs);
   const shown = grouped.slice(0, topN);
-  const lines2 = [`${refs.length} references across ${grouped.length} files (showing top ${shown.length})`];
+  const suppressedNote = suppressed !== void 0 && suppressed > 0 ? ` (${suppressed} in test files hidden by --exclude-tests)` : "";
+  const lines2 = [`${refs.length} references across ${grouped.length} files (showing top ${shown.length})${suppressedNote}`];
   for (const { file: file2, count } of shown) lines2.push(`  ${count}  ${toDisplayPath(displayRoot, file2)}`);
   const omittedFiles = grouped.length - shown.length;
   if (omittedFiles > 0) {
@@ -30964,7 +31317,7 @@ function topFilesJsonPayload(refs, topN) {
   const shown = grouped.slice(0, topN);
   return { fileCounts: shown, totalFiles: grouped.length, totalRefs: refs.length, shown: shown.length };
 }
-function renderCallerGroups(refs, displayRoot) {
+function renderCallerGroups(refs, displayRoot, contextLines = 0) {
   const byFile = /* @__PURE__ */ new Map();
   for (const ref2 of refs) {
     const bucket = byFile.get(ref2.filePath);
@@ -30976,9 +31329,12 @@ function renderCallerGroups(refs, displayRoot) {
   }
   const lines2 = [];
   for (const [file2, fileRefs] of byFile) {
-    lines2.push(`${toDisplayPath(displayRoot, file2)}:`);
+    const displayPath = toDisplayPath(displayRoot, file2);
+    lines2.push(`${displayPath}:`);
     for (const ref2 of fileRefs) {
       lines2.push(`  :${ref2.line}  ${ref2.context !== "" ? ref2.context : "(module scope)"}`);
+      const window = buildContextWindow(file2, ref2.line, contextLines);
+      if (window !== null) lines2.push(...renderContextWindow(displayPath, ref2.line, window, "", "    "));
     }
   }
   return lines2;
@@ -31017,7 +31373,19 @@ function prepareSymbolListing(file2, opts) {
   const fullSourceBytes = sumFileSizes([resolved]);
   return { kind: "ok", resolved, filtered, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount };
 }
+function runPerFileListing(files, run3) {
+  const blocks = [];
+  let anyOk = false;
+  for (const file2 of files) {
+    const r = run3(file2);
+    if (r.code === 0) anyOk = true;
+    blocks.push(r.text);
+  }
+  return { text: blocks.join("\n\n"), code: anyOk ? 0 : 1 };
+}
 function runSkeleton(opts) {
+  const multiFiles = parseMultiFileSpec(opts.file);
+  if (multiFiles !== null) return runPerFileListing(multiFiles, (file2) => runSkeleton({ ...opts, file: file2 }));
   const prep = prepareSymbolListing(opts.file, opts);
   if (prep.kind === "empty") {
     return { text: prep.text, code: 1 };
@@ -31053,6 +31421,8 @@ function runSkeleton(opts) {
   return { text, code: 0 };
 }
 function runOutline(opts) {
+  const multiFiles = parseMultiFileSpec(opts.file);
+  if (multiFiles !== null) return runPerFileListing(multiFiles, (file2) => runOutline({ ...opts, file: file2 }));
   const prep = prepareSymbolListing(opts.file, opts);
   if (prep.kind === "empty") {
     return { text: prep.text, code: 1 };
@@ -31627,10 +31997,13 @@ function runBriefCore(opts) {
   const resolution = resolveSymbolSpec(opts.spec);
   if (resolution.kind === "ambiguous") {
     return {
+      // Name the command explicitly: formatAmbiguity defaults to 'read', so brief's retry lines would otherwise tell the user to run `token-goat read`, which answers a different question than the one they asked.
       text: formatAmbiguity(
         resolution.symbol,
         resolution.file,
-        resolution.candidates
+        resolution.candidates,
+        void 0,
+        "brief"
       ),
       code: 1
     };
@@ -31653,7 +32026,7 @@ function runBriefCore(opts) {
   if (opts.json === true) {
     const result = {
       symbol: match2,
-      callers: shown,
+      callers: (opts.context ?? 0) > 0 ? shown.map((c) => ({ ...c, contextLines: buildContextWindow(c.file, c.line, opts.context ?? 0) ?? [] })) : shown,
       totalCallers,
       truncated,
       section: section2
@@ -31672,7 +32045,10 @@ function runBriefCore(opts) {
   ];
   lines2.push(`Callers (${totalCallers}):`);
   for (const c of shown) {
-    lines2.push(`  ${c.caller}	${toDisplayPath(rootDir, c.file)}:${c.line}`);
+    const callerDisplayPath = toDisplayPath(rootDir, c.file);
+    lines2.push(`  ${c.caller}	${callerDisplayPath}:${c.line}`);
+    const window = buildContextWindow(c.file, c.line, opts.context ?? 0);
+    if (window !== null) lines2.push(...renderContextWindow(callerDisplayPath, c.line, window, "", "    "));
   }
   if (truncated) {
     lines2.push(`  ...(${totalCallers - shown.length} more elided)`);
@@ -31704,11 +32080,40 @@ ${sub.text}`);
   if (anyFound) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
   return { text, code: anyFound ? 0 : 1 };
 }
+function runBriefCrossFile(pairs, opts) {
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  for (const { file: file2, symbol: symbol3 } of pairs) {
+    const key = keyFor({ file: file2, symbol: symbol3 });
+    const sub = runBriefCore({ ...opts, spec: `${file2}::${symbol3}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    if (opts.json === true) {
+      jsonOut[key] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${key}:
+${sub.text}`);
+  }
+  const fullSourceBytes = sumFileSizes([...distinctFiles].map((f) => resolveIndexPath(f, process.cwd())));
+  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  if (anyFound) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
+  return { text, code: anyFound ? 0 : 1 };
+}
 function runBrief(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
     emitErr2(`--limit must be a positive number, got: ${opts.limit}`);
     return 1;
   }
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) {
+    const { text: text2, code: code2 } = runBriefCrossFile(crossFilePairs, opts);
+    if (code2 === 0) emit3(text2);
+    else emitErr2(text2);
+    return code2;
+  }
   const { file: file2, symbol: symbol3 } = parseReadSpec(opts.spec);
   if (symbol3 !== void 0 && symbol3 !== "" && symbol3.includes(",")) {
     const multiSymbols = symbol3.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
@@ -31800,6 +32205,34 @@ function parseDiffHunks(diffText) {
   }
   return hunksByFile;
 }
+function buildChangedRefHint(cwd, ref2) {
+  const countResult = runGit(["rev-list", "--count", "HEAD"], { cwd });
+  if (countResult.exitCode !== 0) {
+    return null;
+  }
+  const commitCount = Number.parseInt(countResult.stdout.trim(), 10);
+  if (!Number.isFinite(commitCount) || commitCount < 1) {
+    return null;
+  }
+  const refResolves = runGit(["rev-parse", "--verify", "--quiet", ref2], { cwd });
+  if (refResolves.exitCode === 0) {
+    return null;
+  }
+  let suggestedRef = null;
+  for (let n = commitCount - 1; n >= 1; n--) {
+    const candidate = `HEAD~${n}`;
+    const candidateResolves = runGit(["rev-parse", "--verify", "--quiet", candidate], { cwd });
+    if (candidateResolves.exitCode === 0) {
+      suggestedRef = candidate;
+      break;
+    }
+  }
+  if (suggestedRef === null) {
+    suggestedRef = EMPTY_TREE_HASH;
+  }
+  const commitWord = commitCount === 1 ? "1 commit" : `${commitCount} commits`;
+  return `Hint: this repo has only ${commitWord}; '${ref2}' does not exist. Try: token-goat changed --since ${suggestedRef}`;
+}
 function runChanged(opts = {}) {
   const ref2 = opts.ref ?? "HEAD~5";
   const cwd = opts.projectRoot ?? process.cwd();
@@ -31809,6 +32242,10 @@ function runChanged(opts = {}) {
     const result = runGit(["diff", ref2, "--name-only"], { cwd });
     if (result.exitCode !== 0) {
       emitErr2(`git diff failed: ${result.stderr}`);
+      const hint = buildChangedRefHint(cwd, ref2);
+      if (hint !== null) {
+        emitErr2(hint);
+      }
       return 1;
     }
     changedFiles = result.stdout.trim().split(/\r?\n/).filter(Boolean);
@@ -31914,13 +32351,16 @@ function resolveSymbolSpecOrEmitError(commandName, spec, projectRoot) {
         resolution.symbol,
         resolution.file,
         resolution.candidates,
-        projectRoot
+        projectRoot,
+        commandName
       )
     );
     return null;
   }
   if (resolution.kind === "none") {
     const messages = [`Symbol '${symbol3}' not found in '${file2}'`];
+    const crossFileLead = formatCrossFileLead(commandName, symbol3, file2, projectRoot);
+    if (crossFileLead !== "") messages.push(crossFileLead);
     const resolved = resolveIndexPath(file2, projectRoot ?? process.cwd());
     const closes = querySymbols({ filePath: resolved, limit: DIDYOUMEAN_LIMIT }).map((s) => s.name);
     if (closes.length > 0) messages.push(didYouMean(closes));
@@ -32130,22 +32570,29 @@ function runGrep(opts) {
     return 1;
   }
   const truncated = hits.slice(0, maxLines);
+  if (opts.symbol === true) {
+    const symbolsByFile = /* @__PURE__ */ new Map();
+    for (const hit of truncated) {
+      let syms = symbolsByFile.get(hit.file);
+      if (syms === void 0) {
+        syms = querySymbols({ filePath: resolveIndexPath(hit.file), limit: ALL_SYMBOLS_IN_FILE_LIMIT });
+        symbolsByFile.set(hit.file, syms);
+      }
+      const enc = enclosingSymbol(syms, hit.line);
+      hit.symbol = enc === null ? null : { name: enc.name, kind: enc.kind, lineStart: enc.lineStart, lineEnd: enc.lineEnd };
+    }
+  }
   if (opts.json === true) {
     const payload = { items: truncated, truncated: hits.length > maxLines, totalCount: hits.length };
     emit3(JSON.stringify(payload, null, 2));
     return 0;
   }
   for (const hit of truncated) {
+    const symbolTag = opts.symbol === true && hit.symbol != null ? ` [${hit.symbol.name} (${hit.symbol.kind})]` : "";
     if (hit.context !== void 0) {
-      for (const ctxLine of hit.context) {
-        if (ctxLine.line === hit.line) {
-          emit3(`${hit.file}:${ctxLine.line}: ${ctxLine.text}`);
-        } else {
-          emit3(`${hit.file}-${ctxLine.line}- ${ctxLine.text}`);
-        }
-      }
+      for (const line of renderContextWindow(hit.file, hit.line, hit.context, symbolTag)) emit3(line);
     } else {
-      emit3(`${hit.file}:${hit.line}: ${hit.text}`);
+      emit3(`${hit.file}:${hit.line}: ${hit.text}${symbolTag}`);
     }
   }
   if (hits.length > maxLines) {
@@ -32328,9 +32775,24 @@ function extractExportNames(text, ext2) {
   }
   return names;
 }
+function runPerFileEmitting(files, label, run3) {
+  let anyOk = false;
+  files.forEach((file2, i) => {
+    if (i > 0) emit3("");
+    emit3(`# ${label}: ${file2}`);
+    if (run3(file2) === 0) anyOk = true;
+  });
+  return anyOk ? 0 : 1;
+}
 function runExports(opts) {
+  const multiFiles = parseMultiFileSpec(opts.file);
+  if (multiFiles !== null) return runPerFileEmitting(multiFiles, "Exports", (file2) => runExports({ ...opts, file: file2 }));
   const symbols = querySymbols({ filePath: resolveIndexPath(opts.file), limit: 500 });
   const kindOf = (name2) => symbols.find((s) => s.name === name2)?.kind ?? "export";
+  const locOf = (name2) => {
+    const s = symbols.find((sym) => sym.name === name2);
+    return s === void 0 ? null : { lineStart: s.lineStart, lineEnd: s.lineEnd };
+  };
   const names = [];
   for (const s of symbols) {
     if (/^(?:export|pub\b|public\b)/.test(s.body.trimStart()) && !names.includes(s.name)) {
@@ -32355,12 +32817,23 @@ function runExports(opts) {
   }
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(names.map((n) => ({ name: n, kind: kindOf(n) })), null, 2);
+    const jsonText = JSON.stringify(
+      names.map((n) => {
+        const loc = locOf(n);
+        return { name: n, kind: kindOf(n), lineStart: loc?.lineStart ?? null, lineEnd: loc?.lineEnd ?? null };
+      }),
+      null,
+      2
+    );
     emit3(jsonText);
     recordReadStat("exports", fullSourceBytes, jsonText, opts.file);
     return 0;
   }
-  const outLines = names.map((n) => `${kindOf(n).padEnd(10)} ${n}`);
+  const outLines = names.map((n) => {
+    const loc = locOf(n);
+    const locSuffix = loc === null ? "" : ` (${loc.lineStart}-${loc.lineEnd})`;
+    return `${kindOf(n).padEnd(10)} ${n}${locSuffix}`;
+  });
   for (const line of outLines) {
     emit3(line);
   }
@@ -32654,6 +33127,8 @@ function importsExtensionFor(filePath) {
   return path48.extname(filePath);
 }
 function runImports(opts) {
+  const multiFiles = parseMultiFileSpec(opts.file);
+  if (multiFiles !== null) return runPerFileEmitting(multiFiles, "Imports", (file2) => runImports({ ...opts, file: file2 }));
   const text = readFileText(opts.file);
   if (text === null) {
     emitErr2(`Could not read: ${opts.file}`);
@@ -32747,11 +33222,12 @@ async function runSemantic(query, opts) {
   );
   const hits = mergeNearbyHits(rawHits).slice(0, n);
   if (hits.length > 0) {
+    const enclosing = hits.map((h) => resolveEnclosingSymbol(h.filePath, h.startLine));
     if (opts.json === true) {
-      const items = hits.map((h) => ({
+      const items = hits.map((h, i) => ({
         filePath: h.filePath,
-        name: null,
-        kind: null,
+        name: enclosing[i]?.name ?? null,
+        kind: enclosing[i]?.kind ?? null,
         startLine: h.startLine,
         endLine: h.endLine,
         distance: h.distance,
@@ -32762,10 +33238,12 @@ async function runSemantic(query, opts) {
       recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text3, query);
       return { text: text3, code: 0 };
     }
-    const blocks2 = hits.map(
-      (h) => `# ${toDisplayPath(rootDir, h.filePath)}:${h.startLine}-${h.endLine} (distance ${h.distance.toFixed(3)})
-${previewLines(h.text, 3)}`
-    );
+    const blocks2 = hits.map((h, i) => {
+      const enc = enclosing[i] ?? null;
+      const suffix = enc !== null ? ` \u2014 inside ${enc.name} (${enc.kind})` : "";
+      return `# ${toDisplayPath(rootDir, h.filePath)}:${h.startLine}-${h.endLine} (distance ${h.distance.toFixed(3)})${suffix}
+${previewLines(h.text, 3)}`;
+    });
     const text2 = guardText(blocks2.join("\n\n"), "semantic");
     recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text2, query);
     return { text: text2, code: 0 };
@@ -32854,7 +33332,7 @@ function runNoteList(opts = {}) {
   });
   return { text: lines2.join("\n"), code: 0 };
 }
-var DIDYOUMEAN_LIMIT, MIN_REVERSE_MATCH_LEN, GREP_MAX_LINES, FIND_SCAN_LIMIT, REFS_TOP_SCAN_LIMIT, STALE_WARNING, PARENT_IDENTIFIER_RE, SKELETON_SYMBOL_CAP, HUNK_HEADER_RE, DEFAULT_LOG_MAX_COUNT;
+var DIDYOUMEAN_LIMIT, MIN_REVERSE_MATCH_LEN, GREP_MAX_LINES, FIND_SCAN_LIMIT, REFS_TOP_SCAN_LIMIT, STALE_WARNING, PARENT_IDENTIFIER_RE, SKELETON_SYMBOL_CAP, HUNK_HEADER_RE, EMPTY_TREE_HASH, DEFAULT_LOG_MAX_COUNT;
 var init_read_commands = __esm({
   "src/read_commands.ts"() {
     "use strict";
@@ -32899,6 +33377,7 @@ var init_read_commands = __esm({
     PARENT_IDENTIFIER_RE = /^[\w$]+$/;
     SKELETON_SYMBOL_CAP = 5e3;
     HUNK_HEADER_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+    EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
     DEFAULT_LOG_MAX_COUNT = 20;
   }
 });
@@ -48689,6 +49168,7 @@ init_index_reader();
 init_parser_types();
 init_doc_embed_extract();
 init_paths();
+init_project();
 init_hooks_index();
 
 // src/relay.ts
@@ -49089,7 +49569,7 @@ init_util2();
 init_disk_cache();
 init_lang_patterns();
 import { readdirSync as readdirSync13, readFileSync as readFileSync24, statSync as statSync17 } from "fs";
-import { resolve as resolve12 } from "path";
+import { resolve as resolve13 } from "path";
 
 // src/recall_index.ts
 init_define_import_meta_env();
@@ -49322,7 +49802,7 @@ function depLockfileFingerprintSync(cmd, cwd) {
   if (!candidates) return null;
   for (const lockfile of candidates) {
     try {
-      const content = readFileSync24(resolve12(cwd, lockfile));
+      const content = readFileSync24(resolve13(cwd, lockfile));
       return shortFingerprint(content);
     } catch {
       continue;
@@ -49475,7 +49955,7 @@ function extractFirstPathArg(cmd, cwd, fallback) {
     const token2 = tokens[i];
     if (!token2.startsWith("-")) {
       if (!token2.startsWith("/")) {
-        return resolve12(cwd, token2);
+        return resolve13(cwd, token2);
       }
       return token2;
     }
@@ -50023,7 +50503,7 @@ function checkDbExists(dataDir2) {
   return {
     name: "Database",
     status: "ok",
-    message: `global.db exists (${toKB(sizeBytes)} KB)`
+    message: `global.db exists (${toKB(sizeBytes)} KB) at ${dbPath}`
   };
 }
 function checkSymbolBodySize(dbPath) {
@@ -50071,6 +50551,13 @@ function checkSymbolCount(dbPath, rootDir) {
         message: `${fileCount} file(s) indexed but 0 symbols extracted \u2014 the parser may not be running (check the worker log); try 'token-goat index --force'`
       };
     }
+    if (fileCount === 0 && symbolCount === 0) {
+      return {
+        name: "Symbols",
+        status: "warn",
+        message: `no files indexed for this project \u2014 every read command will return empty, which looks like a genuine "not found" rather than a missing index; run 'token-goat index .' here`
+      };
+    }
     return {
       name: "Symbols",
       status: "ok",
@@ -72393,7 +72880,7 @@ init_image_shrink();
 var DEFAULT_STDIN_TIMEOUT_MS = 5e3;
 var MAX_STDIN_BYTES = 64 * 1024 * 1024;
 function readStdinJson(timeoutMs = DEFAULT_STDIN_TIMEOUT_MS, maxBytes = MAX_STDIN_BYTES) {
-  return new Promise((resolve24, reject) => {
+  return new Promise((resolve25, reject) => {
     const chunks = [];
     let totalBytes = 0;
     let settled = false;
@@ -72428,7 +72915,7 @@ function readStdinJson(timeoutMs = DEFAULT_STDIN_TIMEOUT_MS, maxBytes = MAX_STDI
           return;
         }
         try {
-          resolve24(JSON.parse(text));
+          resolve25(JSON.parse(text));
         } catch (err2) {
           reject(err2 instanceof Error ? err2 : new Error(String(err2)));
         }
@@ -73878,15 +74365,19 @@ var BRIDGE_CAPABILITY_MATRIX = [
     harness: "copilot_cli",
     label: "Copilot CLI",
     sourceFile: "src/bridges/copilot_cli_install.ts (COPILOT_CLI_HOOK_EVENTS), src/bridges/copilot_cli.ts (COPILOT_TO_TG_EVENT)",
-    implemented: /* @__PURE__ */ new Set(["pre_tool_use", "post_tool_use", "pre_compact", "stop", "subagent_stop", "user_prompt_submit"]),
+    implemented: /* @__PURE__ */ new Set([
+      "session_start",
+      "pre_tool_use",
+      "post_tool_use",
+      "pre_compact",
+      "stop",
+      "subagent_stop",
+      "user_prompt_submit"
+    ]),
     reasons: [
       {
         events: ["notification"],
         reason: "Copilot CLI has a real 'notification' hook event, but copilot_cli.ts's COPILOT_TO_TG_EVENT deliberately leaves it (and sessionEnd/postToolUseFailure/subagentStart/errorOccurred/permissionRequest) unimplemented rather than guessed at"
-      },
-      {
-        events: ["session_start"],
-        reason: "COPILOT_TO_TG_EVENT has no session-start mapping wired yet -- left unimplemented rather than guessed at"
       }
     ]
   },
@@ -78722,7 +79213,7 @@ import { existsSync as existsSync34, readdirSync as readdirSync20, statSync as s
 import * as http from "http";
 import * as https from "https";
 import { isIPv4, isIPv6 } from "net";
-import { resolve as resolve17, join as join41 } from "path";
+import { resolve as resolve18, join as join41 } from "path";
 import { URL as URL2 } from "url";
 import { promisify } from "util";
 import { lookup as dnsLookup } from "dns";
@@ -78894,7 +79385,7 @@ function cleanupStaleDownloads() {
     const files = readdirSync20(cacheDir);
     for (const file2 of files) {
       if (file2.endsWith(".tmp")) {
-        const filePath = resolve17(cacheDir, file2);
+        const filePath = resolve18(cacheDir, file2);
         try {
           const stat2 = statSync27(filePath);
           if (Date.now() - stat2.mtimeMs < STALE_DOWNLOAD_AGE_MS) continue;
@@ -81171,6 +81662,9 @@ function runHintStatsCommand(opts = {}) {
 `);
     return;
   }
+  if (rows.every((r) => r.emitted === 0 && r.actedOn === 0)) {
+    process.stdout.write("No hint emissions recorded yet \u2014 the zeros below are absence of data, not measured ineffectiveness.\n");
+  }
   printSummary(rows);
 }
 
@@ -81429,7 +81923,11 @@ async function cmdIndex(pathArg, opts = {}) {
 function cmdMap(opts) {
   const map3 = buildProjectMap(process.cwd(), { compact: opts.compact === true });
   const text = formatProjectMap(map3, map3.compact);
-  out(text);
+  if (opts.json === true) {
+    out(JSON.stringify(map3));
+  } else {
+    out(text);
+  }
   const bytesSaved = mapLookupBytesSaved(map3, text);
   recordStat("map_lookup", bytesSaved, Math.round(bytesSaved / 4));
 }
@@ -81471,8 +81969,8 @@ async function cmdMcpServe() {
   const server = createMcpServer2();
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  await new Promise((resolve24) => {
-    server.server.onclose = resolve24;
+  await new Promise((resolve25) => {
+    server.server.onclose = resolve25;
   });
 }
 async function cmdHook(event, opts) {
@@ -81679,6 +82177,14 @@ async function cmdDoctor(opts) {
   if (project !== null) {
     doctorOpts.rootDir = project.root;
   }
+  if (opts.json === true) {
+    const results = runDoctor(doctorOpts.dataDir, doctorOpts.configPath, doctorOpts.rootDir);
+    out(JSON.stringify(results));
+    if (results.some((r) => r.status === "fail")) {
+      throw new CliError("doctor checks failed");
+    }
+    return;
+  }
   const code = await runDoctorAndExit(doctorOpts);
   if (code !== 0) {
     throw new CliError("doctor checks failed");
@@ -82182,6 +82688,16 @@ function runExitText(fn) {
     process.exitCode = 1;
   }
 }
+function noteExtraFileArgs(command, first2, extras, fn) {
+  const result = fn();
+  if (extras === void 0 || extras.length === 0) return result;
+  return { text: `${extraFileArgsNote(command, first2, extras)}
+${result.text}`, code: result.code };
+}
+function emitExtraFileArgsNote(command, first2, extras) {
+  if (extras === void 0 || extras.length === 0) return;
+  out(extraFileArgsNote(command, first2, extras));
+}
 function cmdCompress(opts) {
   try {
     if (opts.compress === false) {
@@ -82306,6 +82822,10 @@ async function cmdSkillList(opts) {
       return `${s.name.padEnd(25)} ${bodyKb.padStart(6)}K  ${compactKb.padStart(6)}K  ${marker}  ${s.hitCount.toString().padStart(3)}  ${age.padStart(3)}  ${staleStatus}`;
     });
     const header = `${"Name".padEnd(25)} ${"Body".padStart(6)}  ${"Compact".padStart(6)}  Marker  Hits  Age  Status`;
+    if (skills.length === 0) {
+      out("No skills cached yet.");
+      return;
+    }
     out([header, ...lines2].join("\n"));
   }
 }
@@ -82684,7 +83204,7 @@ function cmdWriteFile(dest, opts) {
     throw new CliError(`TOKEN_GOAT_MAX_STDIN_MB must be a positive integer; got '${process.env["TOKEN_GOAT_MAX_STDIN_MB"] ?? ""}'`);
   }
   const maxBytes = maxMB * 1024 * 1024;
-  return new Promise((resolve24, reject) => {
+  return new Promise((resolve25, reject) => {
     const chunks = [];
     let totalBytes = 0;
     let settled = false;
@@ -82708,7 +83228,7 @@ function cmdWriteFile(dest, opts) {
       try {
         atomicWriteBuffer(dest, Buffer.concat(chunks));
         enqueueDirtyPathSafe(dest);
-        resolve24();
+        resolve25();
       } catch (e) {
         try {
           mapFsError(e, void 0, dest);
@@ -83143,19 +83663,26 @@ function buildProgram() {
       process.exitCode = 1;
     }
   };
-  program2.command("symbol <name>").description("search for a symbol by name").option("-l, --limit <n>", "max results").option("-f, --file <path>", "restrict to one file").option("-k, --kind <kind>", "restrict to one kind (function, class, ...)").option("-j, --json", "output as JSON").action(
-    (name2, opts) => runExitText(
+  program2.command("symbol <name>").description("search for a symbol by name").option("-l, --limit <n>", "max results").option("-f, --file <path>", "restrict to one file").option("-k, --kind <kind>", "restrict to one kind (function, class, ...)").option("-p, --project [path]", "scope search to one project root instead of the global index (defaults to cwd)").option("-j, --json", "output as JSON").action((name2, opts) => {
+    let projectRoot;
+    if (opts.project === true) {
+      projectRoot = resolveProjectRoot({ project: process.cwd() });
+    } else if (typeof opts.project === "string") {
+      projectRoot = resolveProjectRoot({ project: opts.project });
+    }
+    return runExitText(
       () => runSymbol({
         name: name2,
         limit: opts.limit !== void 0 ? requireNonNegativeInt("--limit", opts.limit) : 20,
         ...opts.file !== void 0 ? { file: opts.file } : {},
         ...opts.kind !== void 0 ? { kind: opts.kind } : {},
+        ...projectRoot !== void 0 ? { projectRoot } : {},
         ...opts.json === true ? { json: true } : {}
       })
-    )
-  );
+    );
+  });
   program2.command("read <spec>").description(
-    "read one symbol's full body (spec: file::symbol; disambiguate a name shared by several classes with file::Parent.symbol; comma-separated file::a,b for a merged multi-symbol view, or a::x,b::y to merge symbols across several files)"
+    "read one symbol's full body (spec: file::symbol; disambiguate a name shared by several classes with file::Parent.symbol; a trailing @LINE anchor -- file::symbol@LINE, or combined as file::Parent.symbol@LINE -- picks out a specific candidate by its exact starting line, for the case a Parent qualifier can't reach (e.g. a top-level definition); comma-separated file::a,b for a merged multi-symbol view, or a::x,b::y to merge symbols across several files)"
   ).option("-j, --json", "output as JSON").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").option("--stats", "add per-symbol reference count and doc-coverage flag").action(
     (spec, opts) => runExitText(
       () => runRead({
@@ -83167,13 +83694,14 @@ function buildProgram() {
     )
   );
   program2.command("brief <spec>").description(
-    "symbol body + callers + containing doc section in one call (spec: file::symbol; comma-separated file::a,b for a merged multi-symbol view)"
-  ).option("-j, --json", "output as JSON").option("--limit <n>", "max callers to show (default: 20)").action(
+    "symbol body + callers + containing doc section in one call (spec: file::symbol; also accepts the file::symbol@LINE anchor form documented under `read`; comma-separated file::a,b for a merged multi-symbol view; cross-file a.ts::x,b.ts::y is also supported)"
+  ).option("-j, --json", "output as JSON").option("--limit <n>", "max callers to show (default: 20)").option("-C, --context <n>", "lines of call-site source to show before and after each caller (default 0)").action(
     (spec, opts) => runExit(
       () => runBrief({
         spec,
         ...opts.json === true ? { json: true } : {},
-        ...opts.limit !== void 0 ? { limit: requireNonNegativeInt("--limit", opts.limit) } : {}
+        ...opts.limit !== void 0 ? { limit: requireNonNegativeInt("--limit", opts.limit) } : {},
+        ...opts.context !== void 0 ? { context: requireNonNegativeInt("--context", opts.context) } : {}
       })
     )
   );
@@ -83183,44 +83711,56 @@ function buildProgram() {
     (spec, opts) => opts.list === true ? runExit(() => runListSections({ file: spec, ...opts.json === true ? { json: true } : {} })) : runExitText(() => runSection({ spec, ...opts.json === true ? { json: true } : {} }))
   );
   program2.command("semantic <query>").description("semantic search (falls back to full-text search)").option("-l, --limit <n>", "max results").option("-j, --json", "output as JSON").action(guard(cmdSemantic));
-  program2.command("skeleton <file>").description("list all symbols in a file without bodies").option("-j, --json", "output as JSON").option("--min-lines <n>", "only show symbols at least N lines long").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").option("--stats", "add per-symbol reference count and doc-coverage flag").action(
-    (file2, opts) => runExitText(
-      () => runSkeleton({
-        file: file2,
-        ...opts.json === true ? { json: true } : {},
-        ...opts.minLines !== void 0 ? { minLines: requireNonNegativeInt("--min-lines", opts.minLines) } : {},
-        ...opts.forceRefresh === true ? { forceRefresh: true } : {},
-        ...opts.stats === true ? { stats: true } : {}
-      })
+  program2.command("skeleton <file> [more...]").description('list all symbols in a file without bodies (also accepts a comma-separated file list "a,b,c" for one headed block per file)').option("-j, --json", "output as JSON").option("--min-lines <n>", "only show symbols at least N lines long").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").option("--stats", "add per-symbol reference count and doc-coverage flag").action(
+    (file2, more, opts) => runExitText(
+      () => noteExtraFileArgs(
+        "skeleton",
+        file2,
+        more,
+        () => runSkeleton({
+          file: file2,
+          ...opts.json === true ? { json: true } : {},
+          ...opts.minLines !== void 0 ? { minLines: requireNonNegativeInt("--min-lines", opts.minLines) } : {},
+          ...opts.forceRefresh === true ? { forceRefresh: true } : {},
+          ...opts.stats === true ? { stats: true } : {}
+        })
+      )
     )
   );
-  program2.command("outline <file>").description("list symbols with line ranges and docstrings").option("-j, --json", "output as JSON").option("--min-lines <n>", "only show symbols at least N lines long").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").option("--stats", "add per-symbol reference count and doc-coverage flag").action(
-    (file2, opts) => runExitText(
-      () => runOutline({
-        file: file2,
-        ...opts.json === true ? { json: true } : {},
-        ...opts.minLines !== void 0 ? { minLines: requireNonNegativeInt("--min-lines", opts.minLines) } : {},
-        ...opts.forceRefresh === true ? { forceRefresh: true } : {},
-        ...opts.stats === true ? { stats: true } : {}
-      })
+  program2.command("outline <file> [more...]").description('list symbols with line ranges and docstrings (also accepts a comma-separated file list "a,b,c" for one headed block per file)').option("-j, --json", "output as JSON").option("--min-lines <n>", "only show symbols at least N lines long").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").option("--stats", "add per-symbol reference count and doc-coverage flag").action(
+    (file2, more, opts) => runExitText(
+      () => noteExtraFileArgs(
+        "outline",
+        file2,
+        more,
+        () => runOutline({
+          file: file2,
+          ...opts.json === true ? { json: true } : {},
+          ...opts.minLines !== void 0 ? { minLines: requireNonNegativeInt("--min-lines", opts.minLines) } : {},
+          ...opts.forceRefresh === true ? { forceRefresh: true } : {},
+          ...opts.stats === true ? { stats: true } : {}
+        })
+      )
     )
   );
-  program2.command("refs <spec>").description("find references to one or more symbols (spec: file::symbol, symbol, or comma-separated a,b,c / file::a,b for a merged multi-symbol view). For an unambiguous TypeScript symbol, automatically type-resolves candidates via the TypeScript compiler API to drop same-named-different-symbol false positives; falls back to name-based matching when that is not possible.").option("--callers", "group references by their enclosing caller symbol").option("-l, --limit <n>", "max results").option(
+  program2.command("refs <spec>").description("find references to one or more symbols (spec: file::symbol, symbol, or comma-separated a,b,c / file::a,b for a merged multi-symbol view; cross-file a.ts::x,b.ts::y is also supported). For an unambiguous TypeScript symbol, automatically type-resolves candidates via the TypeScript compiler API to drop same-named-different-symbol false positives; falls back to name-based matching when that is not possible.").option("--callers", "group references by their enclosing caller symbol").option("-l, --limit <n>", "max results").option(
     "--top <n>",
     "for a high-fanout symbol, group references by file (count only) and show only the top N files by reference count instead of a per-line dump"
-  ).option("-j, --json", "output as JSON").action(
+  ).option("-C, --context <n>", "lines of call-site source to show before and after each reference (default 0)").option("-j, --json", "output as JSON").option("--exclude-tests", "hide references whose call site lives in a test file (opt-in; default output is unchanged)").action(
     (spec, opts) => runExit(
       () => runRefs({
         spec,
         ...opts.callers === true ? { callers: true } : {},
         ...opts.json === true ? { json: true } : {},
         ...opts.limit !== void 0 ? { limit: requireNonNegativeInt("--limit", opts.limit) } : {},
-        ...opts.top !== void 0 ? { top: requireNonNegativeInt("--top", opts.top) } : {}
+        ...opts.top !== void 0 ? { top: requireNonNegativeInt("--top", opts.top) } : {},
+        ...opts.context !== void 0 ? { context: requireNonNegativeInt("--context", opts.context) } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     )
   );
   program2.command("index [path]").description("parse all git-tracked files and (re)build the symbol index").option("--walk", "if not a git repo, index a bounded directory walk instead (skips .env / generated / oversized trees)").option("--force", "bypass the SHA-freshness cache and reindex every tracked file, even byte-identical ones (e.g. after a parser upgrade changes what gets extracted)").option("--force-walk", `index a non-git folder via --walk and raise its ${MAX_FILES_SCANNED} source-file refusal to ${MAX_FILES_SCANNED_FORCED} (slow; produces a large index)`).action(guard(cmdIndex));
-  program2.command("map").description("project overview").option("-c, --compact", "compact, low-token summary").action(guard(cmdMap));
+  program2.command("map").description("project overview").option("-c, --compact", "compact, low-token summary").option("--json", "emit the project map as JSON instead of text").action(guard(cmdMap));
   program2.command("bridges-status").description("hook-event parity matrix across every AI-harness bridge (read-only static analysis, never invokes a real harness binary)").option("--json", "emit the matrix as JSON instead of text").action(guard(cmdBridgesStatus));
   program2.command("commands").description("machine-readable manifest of every registered command, its options, and its arguments").option("--json", "emit the manifest as JSON instead of text").option("--grep <pattern>", "filter to commands whose name, description, or aliases match this regex").action(guard(cmdCommands));
   program2.command("mcp-serve").description("run token-goat as an MCP stdio server exposing surgical reads and local compression/handoff tools").action(guard(cmdMcpServe));
@@ -83236,7 +83776,7 @@ function buildProgram() {
   worker.command("stop").description("stop the background indexer").action(guard(cmdWorkerStop));
   worker.command("status").description("check if the indexer is running").action(guard(cmdWorkerStatus));
   program2.command("stats").description("show session statistics (bare = totals only; --full for the breakdown)").option("-j, --json", "output as JSON").option("--full", "show the full breakdown (by source, by command, by day)").option("--short", "force the rich short KPI view even when stdout is not a TTY (e.g. piped)").option("--window-days <days>", "days to include (0 = all time)", "30").option("--home-dir <path>", "home directory (for testing)").action(guard(cmdStats));
-  program2.command("doctor").description("diagnose token-goat health").option("--context", "include context footprint analysis").action(guard(cmdDoctor));
+  program2.command("doctor").description("diagnose token-goat health").option("--context", "include context footprint analysis").option("--json", "emit check results as JSON instead of text").action(guard(cmdDoctor));
   program2.command("context-stats").description("show context statistics").option("--project <path>", "project root to analyze").option("-j, --json", "output as JSON").option("--fix", "apply automatic fixes (confirm-gated; shows a diff before writing)").option("-y, --yes", "with --fix, apply without prompting (non-interactive / scripted use)").action(guard(cmdContextStats));
   program2.command("bootstrap-audit").description("audit Claude Code startup-context contributors without reading prompt bodies").option("--project <path>", "project root to analyze").option("--home <path>", "home directory override (for CI/testing)").option("--follow-links", "follow external symlink/junction roots and direct children").option("-j, --json", "output as JSON").option("--top <n>", "largest metadata entries to show (default 10)", "10").option("--warn-tokens <n>", "warn when total estimated startup tokens exceed n").option("--fail-tokens <n>", "fail when total estimated startup tokens exceed n").option("--warn-bytes <n>", "warn when agent/skill metadata bytes exceed n").option("--fail-bytes <n>", "fail when agent/skill metadata bytes exceed n").action(guard(cmdBootstrapAudit));
   program2.command("memory").description("analyze CLAUDE.md files for duplicate/overlapping content (--fix to apply safe mechanical fixes)").option("--project <path>", "project root to analyze").option("--analyze", "report-only analysis (default)").option("--fix", "remove exact-duplicate lines (confirm-gated; shows a diff before writing)").option("--yes", "apply --fix changes without prompting (non-interactive)").action(guard(cmdMemory));
@@ -83250,11 +83790,17 @@ function buildProgram() {
   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("--max-matches <n>", "cap --grep output to the first N matching lines").option("--section <heading>", "extract a specific section from the output").option("--full", "print the entire cached entry with no head/tail elision").option("--file <path>", "read from raw output file instead of cache").option("--transcript", "parse the --file as a JSONL agent transcript: keep assistant text blocks in order before filtering").action(guard(cmdBashOutput));
   program2.command("web-output [id]").description("retrieve a cached WebFetch response body by ID").option("--head <n>", "show first N lines").option("--tail <n>", "show last N lines").option("--grep <pattern>", "filter lines matching regex").option("--max-matches <n>", "cap --grep output to the first N matching lines").option("--section <heading>", "extract a specific section from the response").option("--full", "print the entire cached entry with no head/tail elision").action(guard(cmdWebOutput));
   program2.command("mcp-output [id]").description("retrieve a cached MCP tool result by ID (the id an MCP post_tool_use hook cached, or a `[token-goat: compressed, full via mcp-output <id>]` label points here)").option("--head <n>", "show first N lines").option("--tail <n>", "show last N lines").option("--grep <pattern>", "filter lines matching regex").option("--max-matches <n>", "cap --grep output to the first N matching lines").option("--section <heading>", "extract a specific section from the result").option("--full", "print the entire cached entry with no head/tail elision").action(guard(cmdMcpOutput));
-  program2.command("exports <file>").description("list exported (public) symbols in a file").option("-j, --json", "output as JSON").action(
-    (file2, opts) => runExit(() => runExports({ file: file2, ...opts.json === true ? { json: true } : {} }))
+  program2.command("exports <file> [more...]").description('list exported (public) symbols in a file (also accepts a comma-separated file list "a,b,c" for one headed block per file)').option("-j, --json", "output as JSON").action(
+    (file2, more, opts) => runExit(() => {
+      emitExtraFileArgsNote("exports", file2, more);
+      return runExports({ file: file2, ...opts.json === true ? { json: true } : {} });
+    })
   );
-  program2.command("imports <file>").description("list the modules a file imports").option("-j, --json", "output as JSON").action(
-    (file2, opts) => runExit(() => runImports({ file: file2, ...opts.json === true ? { json: true } : {} }))
+  program2.command("imports <file> [more...]").description('list the modules a file imports (also accepts a comma-separated file list "a,b,c" for one headed block per file)').option("-j, --json", "output as JSON").action(
+    (file2, more, opts) => runExit(() => {
+      emitExtraFileArgsNote("imports", file2, more);
+      return runImports({ file: file2, ...opts.json === true ? { json: true } : {} });
+    })
   );
   program2.command("find <pattern>").description("find files containing a symbol matching a pattern").option("-j, --json", "output as JSON").option("-l, --limit <n>", "max results").action(
     (pattern, opts) => runExit(
@@ -83265,7 +83811,7 @@ function buildProgram() {
       })
     )
   );
-  program2.command("grep <pattern> [paths...]").description("regex search over files, caching nothing (session-aware grep)").option("-j, --json", "output as JSON").option("--max-lines <n>", "max matching lines to print").option("--no-recursive", "do not descend into subdirectories").option("-C, --context <n>", "lines of context to show before and after each match").action(
+  program2.command("grep <pattern> [paths...]").description("regex search over files, caching nothing (session-aware grep)").option("-j, --json", "output as JSON").option("--max-lines <n>", "max matching lines to print").option("--no-recursive", "do not descend into subdirectories").option("-C, --context <n>", "lines of context to show before and after each match").option("--symbol", "annotate each hit with its enclosing symbol (name and kind)").action(
     (pattern, paths, opts) => runExit(
       () => runGrep({
         pattern,
@@ -83273,7 +83819,8 @@ function buildProgram() {
         ...opts.json === true ? { json: true } : {},
         ...opts.maxLines !== void 0 ? { maxLines: requirePositiveInt("--max-lines", opts.maxLines) } : {},
         ...opts.recursive === false ? { recursive: false } : {},
-        ...opts.context !== void 0 ? { context: requireNonNegativeInt("--context", opts.context) } : {}
+        ...opts.context !== void 0 ? { context: requireNonNegativeInt("--context", opts.context) } : {},
+        ...opts.symbol === true ? { symbol: true } : {}
       })
     )
   );
@@ -83284,16 +83831,18 @@ function buildProgram() {
   program2.command("skill-history").description("list cached skill versions newest-first").option("-j, --json", "output as JSON").action(guard(cmdSkillHistory));
   program2.command("skill-diff <name>").description("show diff between two cached versions of a skill").action(guard(cmdSkillDiff));
   program2.command("skill-section <nameHeading> [headingArg]").description("extract a named section from a skill").action(guard(cmdSkillSection));
-  program2.command("callers <symbol>").description("find all callers of a symbol, resolved to their enclosing function").option("-j, --json", "output as JSON").option("-l, --limit <n>", "max references to scan").action(
+  program2.command("callers <symbol>").description("find all callers of a symbol, resolved to their enclosing function (accepts file::symbol to disambiguate which same-named definition is meant)").option("-j, --json", "output as JSON").option("-l, --limit <n>", "max references to scan").option("-C, --context <n>", "lines of call-site source to show before and after each caller (default 0)").option("--exclude-tests", "hide callers whose call site lives in a test file (opt-in; default output is unchanged)").action(
     (symbol3, opts) => runExit(
       () => runCallers({
         symbol: symbol3,
         ...opts.json === true ? { json: true } : {},
-        ...opts.limit !== void 0 ? { limit: requireNonNegativeInt("--limit", opts.limit) } : {}
+        ...opts.limit !== void 0 ? { limit: requireNonNegativeInt("--limit", opts.limit) } : {},
+        ...opts.context !== void 0 ? { context: requireNonNegativeInt("--context", opts.context) } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     )
   );
-  program2.command("call-chain <symbol>").description("transitive callers up toward entry points (BFS, cycle-safe)").option("-d, --depth <n>", "max BFS depth (default 8)").option("-j, --json", "output as JSON").action(
+  program2.command("call-chain <symbol>").description("transitive callers up toward entry points (BFS, cycle-safe; accepts file::symbol to disambiguate which same-named definition is meant)").option("-d, --depth <n>", "max BFS depth (default 8)").option("-j, --json", "output as JSON").action(
     (symbol3, opts) => runExit(
       () => runCallChain({
         symbol: symbol3,
@@ -83302,7 +83851,7 @@ function buildProgram() {
       })
     )
   );
-  program2.command("impact <symbol>").description("transitive set of callers impacted by a change (with hop depth)").option("--top <n>", "limit output to top N results").option("-j, --json", "output as JSON").action(
+  program2.command("impact <symbol>").description("transitive set of callers impacted by a change (with hop depth; accepts file::symbol to disambiguate which same-named definition is meant)").option("--top <n>", "limit output to top N results").option("-j, --json", "output as JSON").action(
     (symbol3, opts) => runExit(
       () => runImpact({
         symbol: symbol3,
@@ -83311,13 +83860,14 @@ function buildProgram() {
       })
     )
   );
-  program2.command("dead").description("symbols with zero references (default kind: function)").option("-k, --kind <kind>", "symbol kind to check (function, method, class, ...)").option("--include-private", "include _-prefixed names").option("--top <n>", "limit output to top N results").option("-j, --json", "output as JSON").action(
+  program2.command("dead").description("symbols with zero references (default kind: function)").option("-k, --kind <kind>", "symbol kind to check (function, method, class, ...)").option("--include-private", "include _-prefixed names").option("--top <n>", "limit output to top N results").option("-j, --json", "output as JSON").option("--exclude-tests", "hide dead symbols defined in a test file (opt-in; default output is unchanged)").action(
     (opts) => runExit(
       () => runDead({
         ...opts.kind !== void 0 ? { kind: opts.kind } : {},
         ...opts.includePrivate === true ? { includePrivate: true } : {},
         ...opts.top !== void 0 ? { top: requireNonNegativeInt("--top", opts.top) } : {},
-        ...opts.json === true ? { json: true } : {}
+        ...opts.json === true ? { json: true } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     )
   );
@@ -83336,7 +83886,7 @@ function buildProgram() {
   program2.command("scope <fileColonLine>").description("list symbols enclosing a file:line position, innermost first").option("-j, --json", "output as JSON").action(
     (spec, opts) => runExit(() => runScope({ spec, ...opts.json === true ? { json: true } : {} }))
   );
-  program2.command("similar <spec>").description('find symbols similar to a given "file::symbol" anchor using FTS').option("--top <n>", "max results (default 10)").option("-j, --json", "output as JSON").action(
+  program2.command("similar <spec>").description('find symbols similar to a given "file::symbol" anchor using FTS (also accepts the file::symbol@LINE anchor form documented under `read`)').option("--top <n>", "max results (default 10)").option("-j, --json", "output as JSON").action(
     (spec, opts) => runExit(
       () => runSimilar({
         spec,
@@ -83375,7 +83925,7 @@ function buildProgram() {
       })
     )
   );
-  program2.command("blame <spec>").description('git blame for the line range of a symbol ("file::symbol")').option("-j, --json", "output as JSON").action(
+  program2.command("blame <spec>").description('git blame for the line range of a symbol ("file::symbol"; also accepts the file::symbol@LINE anchor form documented under `read`)').option("-j, --json", "output as JSON").action(
     (spec, opts) => runExit(() => runBlame({ spec, ...opts.json === true ? { json: true } : {} }))
   );
   program2.command("ask <question>").description("(experimental) find relevant code context; synthesize with an LLM if TOKEN_GOAT_ASK_BACKEND is set").option("--top <n>", "max FTS hits to surface (default 8)").option("-j, --json", "output as JSON").action(
@@ -83459,16 +84009,16 @@ function buildProgram() {
   }))());
   program2.command("fetch-image <url>").description("fetch an image URL and shrink it (saves to --out path or a temp file)").option("--out <path>", "output file path").option("-j, --json", "output as JSON").action((url2, opts) => guard(() => cmdFetchImage({ url: url2, ...opts.out !== void 0 ? { out: opts.out } : {}, ...opts.json === true ? { json: true } : {} }))());
   program2.command("history").description("show recent session history: bash commands and web fetches (current-session or recent cache)").option("--limit <n>", "max entries to show (default: 30)").option("-j, --json", "output as JSON").action((opts) => guard(() => cmdHistory(opts))());
-  program2.command("changed").description("list files or symbols changed since a git ref").option("--since <ref>", "git ref to compare against (default: HEAD~5)").option("--symbol", "list symbols instead of files").option("-j, --json", "output as JSON").action(
-    (opts) => runExit(
+  program2.command("changed [ref]").description("list files or symbols changed since a git ref").option("--since <ref>", "git ref to compare against (default: HEAD~5)").option("--symbol", "list symbols instead of files").option("-j, --json", "output as JSON").action(
+    (ref2, opts) => runExit(
       () => runChanged({
-        ref: opts.since ?? "HEAD~5",
+        ref: opts.since ?? ref2 ?? "HEAD~5",
         ...opts.symbol === true ? { symbolMode: true } : {},
         ...opts.json === true ? { json: true } : {}
       })
     )
   );
-  program2.command("diff <spec> [ref]").description('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`').option("-j, --json", "output as JSON").action(
+  program2.command("diff <spec> [ref]").description('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` (also accepts the file::symbol@LINE anchor form documented under `read`)').option("-j, --json", "output as JSON").action(
     (spec, ref2, opts) => runExit(
       () => runDiff({
         spec,
@@ -83477,7 +84027,7 @@ function buildProgram() {
       })
     )
   );
-  program2.command("log <spec> [ref]").description('show git commit history scoped to one symbol\'s line range, e.g. `token-goat log "file.ts::myFn" HEAD~10`').option("--max-count <n>", "maximum number of commits to show (default 20)").option("-j, --json", "output as JSON").action(
+  program2.command("log <spec> [ref]").description('show git commit history scoped to one symbol\'s line range, e.g. `token-goat log "file.ts::myFn" HEAD~10` (also accepts the file::symbol@LINE anchor form documented under `read`)').option("--max-count <n>", "maximum number of commits to show (default 20)").option("-j, --json", "output as JSON").action(
     (spec, ref2, opts) => runExit(
       () => runLog({
         spec,
@@ -83610,6 +84160,8 @@ async function run2(argv = process.argv) {
 }
 
 // src/main.ts
+init_util2();
+installEpipeGuard();
 void run2();
 /*! Bundled license information: