token-goat 2.6.21 → 2.6.22

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.21";
+    return "2.6.22";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");
@@ -5449,6 +5449,7 @@ function _buildConfig(raw, projectRaw = {}) {
   ix.large_file_skip_kb = validatedInt(ix_raw["large_file_skip_kb"], ix.large_file_skip_kb, ...boundsOf("indexing.large_file_skip_kb"));
   ix.large_file_symbol_only_kb = Math.min(ix.large_file_symbol_only_kb, ix.large_file_skip_kb);
   ix.skip_dirs = validatedStrList(ix_raw["skip_dirs"], ix.skip_dirs);
+  ix.skip_files = validatedStrList(ix_raw["skip_files"], ix.skip_files);
   ix.embeddings_enabled = validatedBool(ix_raw["embeddings_enabled"], ix.embeddings_enabled);
   ix.embeddings_enabled = envBool("TOKEN_GOAT_EMBEDDINGS_ENABLED", ix.embeddings_enabled);
   const cpr_raw = section(raw, "compression");
@@ -5624,6 +5625,7 @@ function saveConfig(config2) {
       large_file_symbol_only_kb: config2.indexing.large_file_symbol_only_kb,
       large_file_skip_kb: config2.indexing.large_file_skip_kb,
       skip_dirs: config2.indexing.skip_dirs,
+      skip_files: config2.indexing.skip_files,
       embeddings_enabled: config2.indexing.embeddings_enabled
     },
     compression: {
@@ -5803,6 +5805,7 @@ var init_config = __esm({
         large_file_symbol_only_kb: 500,
         large_file_skip_kb: 2048,
         skip_dirs: [],
+        skip_files: ["coverage.json", "coverage-final.json"],
         embeddings_enabled: true
       },
       compression: {
@@ -6114,7 +6117,8 @@ CREATE TABLE IF NOT EXISTS symbols (
   line_start INTEGER,
   line_end INTEGER,
   body TEXT,
-  docstring TEXT
+  docstring TEXT,
+  parent TEXT NOT NULL DEFAULT ''
 );
 CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
 CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file_path);
@@ -6317,12 +6321,14 @@ CREATE TRIGGER IF NOT EXISTS cache_recall_au AFTER UPDATE ON cache_recall BEGIN
   VALUES (new.row_id, new.label, new.content);
 END;
 `;
-    SCHEMA_VERSION = 8;
+    SCHEMA_VERSION = 9;
     MIGRATIONS = {
       // v1 -> v2: adds files.embed_sha, tracked separately from files.sha so embedding freshness can be gated independently of parse freshness (see makeIndexer in worker.ts). A pre-existing v1 database's `files` table predates the column, so it needs an explicit ALTER TABLE here; a brand-new database already has the column from SCHEMA_SQL's CREATE TABLE above, so the ALTER TABLE would fail with "duplicate column name" there -- swallow exactly that error and rethrow anything else, so a genuine ALTER TABLE failure is never silently lost.
       1: (conn) => alterTableIdempotent(conn, "ALTER TABLE files ADD COLUMN embed_sha TEXT"),
       // v2 -> v3: adds files.retry_count, a durable per-path counter for consecutive transient-read-failure requeues (see MAX_TRANSIENT_RETRIES / requeueDirtyPath / resetTransientRetryCount in worker.ts). Previously this counter lived only in an in-memory Map inside worker.ts, which meant resetTransientRetryCount -- called from appendDirtyPath (hooks_index.ts) in the short-lived hook CLI process -- could never actually reach the long-lived detached daemon process's own copy of that Map: they are different Node processes with no shared memory, so the reset was a silent no-op in the real deployed topology. Persisting the counter in `files` makes it visible to both processes via the one thing they do share: the index DB. Same swallow-duplicate-column pattern as v1 -> v2 above.
-      2: (conn) => alterTableIdempotent(conn, "ALTER TABLE files ADD COLUMN retry_count INTEGER NOT NULL DEFAULT 0")
+      2: (conn) => alterTableIdempotent(conn, "ALTER TABLE files ADD COLUMN retry_count INTEGER NOT NULL DEFAULT 0"),
+      // v8 -> v9: adds symbols.parent (see SCHEMA_VERSION comment above for why). A pre-existing v8 database's `symbols` table predates the column, so it needs an explicit ALTER TABLE here; a brand-new database already has the column from SCHEMA_SQL's CREATE TABLE above, so the ALTER TABLE would fail with "duplicate column name" there -- swallow exactly that error and rethrow anything else, same pattern as v1 -> v2 / v2 -> v3 above.
+      8: (conn) => alterTableIdempotent(conn, "ALTER TABLE symbols ADD COLUMN parent TEXT NOT NULL DEFAULT ''")
     };
     registerReset(closeAllDbs);
   }
@@ -10522,7 +10528,27 @@ function registerHook(eventName, handler, opts) {
     list = [];
     _handlers.set(eventName, list);
   }
-  list.push({ handler, toolName: opts?.toolName, advisory: opts?.advisory === true });
+  list.push({
+    handler,
+    toolName: opts?.toolName,
+    toolPattern: opts?.toolPattern,
+    advisory: opts?.advisory === true,
+    followsMatcher: opts?.followsMatcher === true
+  });
+}
+function toolMatcherFor(eventName) {
+  const list = _handlers.get(eventName);
+  if (list === void 0 || list.length === 0) return null;
+  const parts = [];
+  for (const { toolName, toolPattern, followsMatcher } of list) {
+    if (followsMatcher) continue;
+    if (toolName === void 0 && toolPattern === void 0) return null;
+    for (const part of [toolName === void 0 ? void 0 : `^${toolName}$`, toolPattern]) {
+      if (part !== void 0 && part !== "" && !parts.includes(part)) parts.push(part);
+    }
+  }
+  if (parts.length === 0) return null;
+  return parts.join("|");
 }
 async function runHook(event) {
   const list = _handlers.get(event.eventName);
@@ -10844,7 +10870,7 @@ var init_hint_stats = __esm({
         resolvePendingHintsForEvent(event);
         return passOutput();
       },
-      { advisory: true }
+      { advisory: true, followsMatcher: true }
     );
   }
 });
@@ -11358,10 +11384,12 @@ function buildGuidanceBody(fallbackToolClause) {
     "",
     `This gate decides *whether* to reach for a read tool at all. ${fallbackToolClause} only pick the *fallback* once token-goat has been ruled out for this read \u2014 they never authorize skipping the gate.`,
     "",
+    "Fallback clauses may name native tools (`Read`, `Grep`, `Glob`, `shell`, `apply_patch`, `view_image`, `edit`, `create`) or PowerShell helpers (`Get-Content`, `Select-String`); shell/editor commands like `rg`, `grep`, `fd`, `sed`, `cat`, `find`, and `ls` are commands, not tool identifiers.",
+    "",
     "Exemptions (gate passes, read directly): the file is under ~200 lines and you need all of it; it was never indexed (new, untracked, or generated this turn); it is binary or an image; the target has no symbol handle (e.g. a literal mid-function).",
     "",
     "Failure shapes to catch yourself in, and the command that replaces each:",
-    '- grep/search with context flags to find a function body \u2192 `read "file::symbol"`',
+    '- shell `rg`/`grep` search with context flags to find a function body \u2192 `read "file::symbol"`',
     '- paging one function with view/view_range \u2192 `read "file::symbol"`',
     '- reading one heading of a large doc \u2192 `section "file::Heading"`',
     "- searching for a symbol's callers \u2192 `refs file::symbol --callers`",
@@ -11467,13 +11495,28 @@ function installHooks(scope = "user") {
       }
     }
     if (groupHasTokenGoat(groups, isCurrentTokenGoatHookCommand)) {
-      if (strippedLegacy) {
+      const narrowed = toolMatcherFor(eventArg);
+      let renarrowed = false;
+      if (narrowed !== null) {
+        for (let i = 0; i < groups.length; i++) {
+          const group = groups[i];
+          if (group === void 0) continue;
+          const ownHooks = group.hooks ?? [];
+          const isOwnGroup = ownHooks.length > 0 && ownHooks.every((h) => isCurrentTokenGoatHookCommand(h.command));
+          if (isOwnGroup && group.matcher !== narrowed) {
+            groups[i] = { ...group, matcher: narrowed };
+            renarrowed = true;
+          }
+        }
+      }
+      if (strippedLegacy || renarrowed) {
         hooks[eventKey] = groups;
         changed = true;
       }
       continue;
     }
-    groups.push({ matcher: "", hooks: [{ type: "command", command: hookCommand(eventArg) }] });
+    const matcher = toolMatcherFor(eventArg) ?? "";
+    groups.push({ matcher, hooks: [{ type: "command", command: hookCommand(eventArg) }] });
     hooks[eventKey] = groups;
     changed = true;
   }
@@ -11606,6 +11649,7 @@ var init_install = __esm({
     "use strict";
     init_define_import_meta_env();
     init_guidance_block();
+    init_hook_registry();
     init_paths();
     init_util2();
     HOOK_EVENT_MAP = [
@@ -11627,6 +11671,20 @@ var init_install = __esm({
     SKILL_MD_FRONTMATTER = `---
 name: token-goat
 description: Use before reading whole files or grepping wide. token-goat commands (symbol, read, section, semantic, outline, skeleton, map, refs, changed, config-get, bash-output, web-output, gdrive-sections) return narrow slices of code and docs at a fraction of the token cost.
+allowed-tools:
+  - symbol
+  - read
+  - section
+  - semantic
+  - outline
+  - skeleton
+  - map
+  - refs
+  - changed
+  - config-get
+  - bash-output
+  - web-output
+  - gdrive-sections
 ---`;
     SKILL_MD_CONTENT = `${SKILL_MD_FRONTMATTER}
 
@@ -11781,7 +11839,7 @@ function buildAgentsBlock() {
   return buildGuidanceBlock({
     beginMarker: AGENTS_BEGIN,
     endMarker: AGENTS_END,
-    fallbackToolClause: "Codex's own `shell` (cat/type), `apply_patch` preview, and `view_image` preferences"
+    fallbackToolClause: "Codex's native `shell`, `apply_patch`, and `view_image` tools (shell commands like `cat`/`type` run inside `shell`)"
   });
 }
 function writeAgentsBlock(p) {
@@ -12171,11 +12229,16 @@ function copilotCliInstructionsPath(opts = {}) {
   return path11.join(path11.dirname(copilotCliHooksDir(opts)), "copilot-instructions.md");
 }
 function buildCopilotInstructionsBlock() {
-  return buildGuidanceBlock({
-    beginMarker: COPILOT_INSTRUCTIONS_BEGIN,
-    endMarker: COPILOT_INSTRUCTIONS_END,
-    fallbackToolClause: "Copilot CLI's own `view`, `grep`, and `glob` tool-preference rules (and `Get-Content`/`Select-String`)"
-  });
+  return stripInlineCodeSpans(
+    buildGuidanceBlock({
+      beginMarker: COPILOT_INSTRUCTIONS_BEGIN,
+      endMarker: COPILOT_INSTRUCTIONS_END,
+      fallbackToolClause: "Copilot CLI's native `view`, `grep`, and `glob` tools (with PowerShell commands `Get-Content`/`Select-String` as search fallbacks)"
+    })
+  );
+}
+function stripInlineCodeSpans(text) {
+  return text.replace(/`([^`]+)`/g, "$1");
 }
 function writeCopilotInstructionsBlock(p) {
   return upsertDelimitedBlock(p, COPILOT_INSTRUCTIONS_BEGIN, COPILOT_INSTRUCTIONS_END, buildCopilotInstructionsBlock());
@@ -13286,23 +13349,23 @@ function isNoisePath(inputPath) {
     }
   }
   const slashIdx = p.lastIndexOf("/");
-  const basename20 = slashIdx >= 0 ? p.slice(slashIdx + 1) : p;
-  if (NOISE_BASENAMES.has(basename20)) {
+  const basename21 = slashIdx >= 0 ? p.slice(slashIdx + 1) : p;
+  if (NOISE_BASENAMES.has(basename21)) {
     return true;
   }
-  if (basename20.startsWith(".improve-state-") || basename20.startsWith("improve_commit_msg_")) {
+  if (basename21.startsWith(".improve-state-") || basename21.startsWith("improve_commit_msg_")) {
     return true;
   }
-  const dotIdx = basename20.lastIndexOf(".");
+  const dotIdx = basename21.lastIndexOf(".");
   if (dotIdx >= 0) {
-    const ext2 = basename20.slice(dotIdx);
+    const ext2 = basename21.slice(dotIdx);
     if (NOISE_EXTS.has(ext2)) {
       return true;
     }
   }
   for (const ext2 of NOISE_EXTS) {
     if (ext2.includes(".") && ext2.split(".").length > 2) {
-      if (basename20.endsWith(ext2)) {
+      if (basename21.endsWith(ext2)) {
         return true;
       }
     }
@@ -13935,15 +13998,15 @@ var init_hints = __esm({
 });
 
 // src/hints/lang_patterns.ts
-function isLockFile(basename20) {
-  return LOCK_FILE_NAMES.has(basename20.toLowerCase());
+function isLockFile(basename21) {
+  return LOCK_FILE_NAMES.has(basename21.toLowerCase());
 }
-function isManifestFile(basename20) {
-  const lower = basename20.toLowerCase();
+function isManifestFile(basename21) {
+  const lower = basename21.toLowerCase();
   if (MANIFEST_FILE_NAMES.has(lower)) return true;
   const dot = lower.lastIndexOf(".");
   if (dot !== -1 && MANIFEST_EXTENSIONS.has(lower.slice(dot))) return true;
-  if (MANIFEST_BASENAME_PATTERNS.some((re) => re.test(basename20))) return true;
+  if (MANIFEST_BASENAME_PATTERNS.some((re) => re.test(basename21))) return true;
   return false;
 }
 function pathSegments(filePath) {
@@ -14282,8 +14345,8 @@ function formatHeadingTree(headings, filePath) {
   }
   return lines2.join("\n");
 }
-function getWellKnownSections(basename20) {
-  return WELL_KNOWN_SECTIONS[basename20] ?? [];
+function getWellKnownSections(basename21) {
+  return WELL_KNOWN_SECTIONS[basename21] ?? [];
 }
 function extractChangelogVersionHint(content, filePath) {
   const lines2 = content.split("\n");
@@ -14326,6 +14389,64 @@ var init_markdown_hints = __esm({
   }
 });
 
+// src/doc_comment.ts
+function precedingDocComment(lines2, lineStart, style) {
+  const aboveIdx = lineStart - 2;
+  if (aboveIdx < 0 || aboveIdx >= lines2.length) return "";
+  const aboveLine = lines2[aboveIdx];
+  if (aboveLine === void 0) return "";
+  const aboveTrimmed = aboveLine.trim();
+  if (style === "hash") {
+    if (!aboveTrimmed.startsWith("#")) return "";
+    const collected = [];
+    let i = aboveIdx;
+    while (i >= 0) {
+      const line = lines2[i];
+      if (line === void 0) break;
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("#")) break;
+      collected.unshift(trimmed.replace(/^#+\s?/, ""));
+      i--;
+    }
+    return collected.join("\n").trim();
+  }
+  if (aboveTrimmed.endsWith("*/")) {
+    let blockStart = aboveIdx;
+    while (blockStart >= 0) {
+      const l = lines2[blockStart];
+      if (l === void 0) break;
+      if (l.trim().startsWith("/*")) break;
+      blockStart--;
+    }
+    if (blockStart < 0) return "";
+    const opener = lines2[blockStart];
+    if (opener === void 0 || !opener.trim().startsWith("/*")) return "";
+    return lines2.slice(blockStart, aboveIdx + 1).map(
+      (l) => l.trim().replace(/^\/\*+/, "").replace(/\*+\/$/, "").replace(/^\*\s?/, "").trim()
+    ).filter((l) => l !== "").join("\n");
+  }
+  if (aboveTrimmed.startsWith("//")) {
+    const collected = [];
+    let i = aboveIdx;
+    while (i >= 0) {
+      const line = lines2[i];
+      if (line === void 0) break;
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("//")) break;
+      collected.unshift(trimmed.replace(/^\/\/[/!]?\s?/, ""));
+      i--;
+    }
+    return collected.join("\n").trim();
+  }
+  return "";
+}
+var init_doc_comment = __esm({
+  "src/doc_comment.ts"() {
+    "use strict";
+    init_define_import_meta_env();
+  }
+});
+
 // src/languages/common.ts
 function buildLineIndex(text) {
   const idx = [0];
@@ -14865,7 +14986,7 @@ function stripMultilineStringSpan(line, state, lang) {
   }
   return { code, state: cur };
 }
-function makeSpanSymbol(filePath, name2, kind, span, docstring = "") {
+function makeSpanSymbol(filePath, name2, kind, span, parent = "", lines2, style) {
   return {
     filePath,
     name: name2,
@@ -14873,10 +14994,11 @@ function makeSpanSymbol(filePath, name2, kind, span, docstring = "") {
     lineStart: span.startLine,
     lineEnd: span.endLine,
     body: span.body,
-    docstring
+    docstring: lines2 !== void 0 && style !== void 0 ? precedingDocComment(lines2, span.startLine, style) : "",
+    parent
   };
 }
-function makeLineSymbol(filePath, name2, kind, line, sig, parent) {
+function makeLineSymbol(filePath, name2, kind, line, sig, parent, lines2, style) {
   return {
     filePath,
     name: name2,
@@ -14884,7 +15006,8 @@ function makeLineSymbol(filePath, name2, kind, line, sig, parent) {
     lineStart: line,
     lineEnd: line,
     body: sig ?? "",
-    docstring: parent ?? ""
+    docstring: lines2 !== void 0 && style !== void 0 ? precedingDocComment(lines2, line, style) : "",
+    parent: parent ?? ""
   };
 }
 function makeSymbolEmitter(symbols, sections, seen, filePath, maxSymbols = 500, maxHeadingLen = 120) {
@@ -14901,7 +15024,8 @@ function makeSymbolEmitter(symbols, sections, seen, filePath, maxSymbols = 500,
       lineStart: line,
       lineEnd: line,
       body: "",
-      docstring: ""
+      docstring: "",
+      parent: ""
     });
     sections.push({ heading: name2, level: 1, line, endLine: line });
   };
@@ -14965,6 +15089,7 @@ var init_common = __esm({
     "use strict";
     init_define_import_meta_env();
     init_util2();
+    init_doc_comment();
     HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
     HTML_SCRIPT_BODY_RE = /(<script\b[^>]*>)([\s\S]*?)(<\/script\s*>)/gi;
     HTML_CDATA_RE = /<!\[CDATA\[[\s\S]*?\]\]>/g;
@@ -16004,19 +16129,19 @@ async function preReadImageHandler(event) {
   }
   const result = await shrinkImage(input, { sizeThresholdBytes: 0 });
   if (result === null) return passOutput();
-  const basename20 = path18.basename(filePath);
+  const basename21 = path18.basename(filePath);
   if (loadConfig().image_shrink.ocr_enabled) {
     const ocr = await ocrImage(result.data);
     if (ocr !== null && isTextHeavy(ocr, loadConfig().image_shrink.ocr_min_confidence)) {
       const textBytes = Buffer.byteLength(ocr.text, "utf8");
       const saved2 = Math.max(0, result.shrunkBytes - textBytes);
-      recordStat("image_ocr", saved2, Math.round(saved2 / 4), void 0, basename20);
-      return contextOutput(formatOcrSummary(ocr, basename20, result.originalBytes));
+      recordStat("image_ocr", saved2, Math.round(saved2 / 4), void 0, basename21);
+      return contextOutput(formatOcrSummary(ocr, basename21, result.originalBytes));
     }
   }
   const saved = result.originalBytes - result.shrunkBytes;
-  const { summary, dataUrl } = formatShrinkSummary(result, basename20);
-  recordStat("image_shrink", saved, Math.round(saved / 4), void 0, basename20);
+  const { summary, dataUrl } = formatShrinkSummary(result, basename21);
+  recordStat("image_shrink", saved, Math.round(saved / 4), void 0, basename21);
   return contextOutput(`${summary}
 ${dataUrl}`);
 }
@@ -16381,8 +16506,8 @@ var init_notebook_compact = __esm({
 // src/hooks_read.ts
 import * as fs21 from "node:fs";
 import * as path21 from "node:path";
-function isTsConfigFile(basename20) {
-  const lower = basename20.toLowerCase();
+function isTsConfigFile(basename21) {
+  const lower = basename21.toLowerCase();
   return /^tsconfig(\..+)?\.json$/i.test(lower) || lower === "jsconfig.json";
 }
 function largeFileDenyBytes() {
@@ -16482,18 +16607,18 @@ function describeSliceAdvice(slice, absPath) {
   }
   return "Use Read with offset/limit to sample specific sections.";
 }
-function isSourceExtension(basename20) {
-  if (SOURCE_EXT_RE.test(basename20)) return true;
-  const language = detectLanguage(basename20);
+function isSourceExtension(basename21) {
+  if (SOURCE_EXT_RE.test(basename21)) return true;
+  const language = detectLanguage(basename21);
   return language === "apex" || language === "salesforce_metadata" || language === "salesforce_markup";
 }
-function isDispatchedFileType(basename20) {
-  return DISPATCHED_FILE_TYPE_EXTS.has(path21.extname(basename20).slice(1).toLowerCase());
+function isDispatchedFileType(basename21) {
+  return DISPATCHED_FILE_TYPE_EXTS.has(path21.extname(basename21).slice(1).toLowerCase());
 }
-function surgicalHint(filePath, basename20, lineCount) {
+function surgicalHint(filePath, basename21, lineCount) {
   if (lineCount < loadConfig().hints.min_file_lines_for_hint) return "";
-  const isDocFile = /\.(md|mdx|rst|txt)$/i.test(basename20);
-  const isSectionFile = /\.(json|jsonc|css|scss|sass|less|yaml|yml|toml)$/i.test(basename20);
+  const isDocFile = /\.(md|mdx|rst|txt)$/i.test(basename21);
+  const isSectionFile = /\.(json|jsonc|css|scss|sass|less|yaml|yml|toml)$/i.test(basename21);
   if (isDocFile) {
     return 'Use `token-goat section "' + filePath + '::HeadingName"` to extract a part.';
   } else if (isSectionFile) {
@@ -16541,7 +16666,7 @@ function buildLineDiff(oldContent, newContent, label) {
   }
   return out2.join("\n");
 }
-function loadSnapshotDiff(sessionId, normalized, basename20) {
+function loadSnapshotDiff(sessionId, normalized, basename21) {
   const oldSnap = load(sessionId, normalized);
   if (oldSnap === null) return { kind: "none" };
   try {
@@ -16553,7 +16678,7 @@ function loadSnapshotDiff(sessionId, normalized, basename20) {
     const truncIdx = oldRaw.indexOf(TRUNC_MARKER);
     const oldContent = truncIdx >= 0 ? oldRaw.slice(0, truncIdx) : oldRaw;
     if (oldContent === currentContent) return { kind: "unchanged", currentContent };
-    const diff = buildLineDiff(oldContent, currentContent, basename20);
+    const diff = buildLineDiff(oldContent, currentContent, basename21);
     if (diff === "") return { kind: "none" };
     const savedBytes = Math.max(0, currentContent.length - diff.length);
     return { kind: "diff", diff, savedBytes, currentContent };
@@ -16626,8 +16751,8 @@ function preReadHandlerInner(event) {
       "node_modules is typically noise; use npm ls, npm outdated, or npm audit instead for dependency info. To force access, use: token-goat read node_modules/package/file.js::symbol-name or token-goat section node_modules/package/file.js::heading"
     );
   }
-  const basename20 = path21.basename(normalized);
-  if (isLockFile(basename20)) {
+  const basename21 = path21.basename(normalized);
+  if (isLockFile(basename21)) {
     return denyOutput(
       'Lock files are rarely useful to read in full. Use `token-goat section "' + normalized + '::<section>"` to extract a specific dependency, or read the relevant manifest instead.'
     );
@@ -16650,20 +16775,20 @@ function preReadHandlerInner(event) {
       return quietContextOutput(manifestHint.text);
     }
   }
-  if (isTsConfigFile(basename20) && wasFileReadThisSession(normalized)) {
+  if (isTsConfigFile(basename21) && wasFileReadThisSession(normalized)) {
     recordActualRead(event, normalized);
     return quietContextOutput(
-      "Already read " + basename20 + '. Use `token-goat section "' + normalized + '::compilerOptions"` to extract compiler options, or `token-goat config-get ' + normalized + " compilerOptions.target` for a single value."
+      "Already read " + basename21 + '. Use `token-goat section "' + normalized + '::compilerOptions"` to extract compiler options, or `token-goat config-get ' + normalized + " compilerOptions.target` for a single value."
     );
   }
-  if (isManifestFile(basename20) && wasFileReadThisSession(normalized)) {
+  if (isManifestFile(basename21) && wasFileReadThisSession(normalized)) {
     recordActualRead(event, normalized);
     return quietContextOutput(
-      "You've already read " + basename20 + '. Use `token-goat section "' + normalized + '::<field>"` or `token-goat config-get ' + normalized + " <key>` to extract just the value you need."
+      "You've already read " + basename21 + '. Use `token-goat section "' + normalized + '::<field>"` or `token-goat config-get ' + normalized + " <key>` to extract just the value you need."
     );
   }
   const skillName = detectSkillFile(normalized);
-  if (skillName && basename20 === "SKILL.md") {
+  if (skillName && basename21 === "SKILL.md") {
     try {
       const body = fs21.readFileSync(normalized, "utf-8");
       const bodySha = contentHash(body);
@@ -16693,7 +16818,7 @@ function preReadHandlerInner(event) {
       }
     }
   }
-  const isNotebook = /\.ipynb$/i.test(basename20);
+  const isNotebook = /\.ipynb$/i.test(basename21);
   if (event.toolName !== "Grep" && isNotebook) {
     try {
       const rawBytes = fs21.readFileSync(normalized);
@@ -16710,7 +16835,7 @@ function preReadHandlerInner(event) {
     } catch {
     }
   }
-  const isMarkdown = /\.(md|mdx|markdown|rst)$/i.test(basename20);
+  const isMarkdown = /\.(md|mdx|markdown|rst)$/i.test(basename21);
   if (event.toolName !== "Grep" && isMarkdown) {
     let fileContent = null;
     let markdownSize = null;
@@ -16728,9 +16853,9 @@ function preReadHandlerInner(event) {
         const alreadyRead = wasFileReadThisSession(normalized);
         const hintText = formatHeadingTree(headings, normalized);
         const headingTextsLower = new Set(headings.map((h) => h.text.trim().toLowerCase()));
-        const wellKnown = getWellKnownSections(basename20).filter((s) => headingTextsLower.has(s.trim().toLowerCase()));
+        const wellKnown = getWellKnownSections(basename21).filter((s) => headingTextsLower.has(s.trim().toLowerCase()));
         const wellKnownText = wellKnown.length > 0 ? "\nQuick access: " + wellKnown.map((s) => 'token-goat section "' + normalized + "::" + s + '"').join(" | ") : "";
-        const changelogExtra = basename20.toLowerCase() === "changelog.md" ? extractChangelogVersionHint(fileContent, normalized) : "";
+        const changelogExtra = basename21.toLowerCase() === "changelog.md" ? extractChangelogVersionHint(fileContent, normalized) : "";
         let message = hintText + wellKnownText + changelogExtra;
         const slice = estimateRequestedSlice(event, normalized);
         const gateSize = slice.kind === "bytes" && markdownSize !== null ? Math.min(slice.bytes, markdownSize) : markdownSize;
@@ -16751,19 +16876,19 @@ function preReadHandlerInner(event) {
   if (isMemoryMd && wasFileReadThisSession(normalized)) {
     recordActualRead(event, normalized);
     recordStat("session_hint", 0, 0);
-    const isMainMemory = basename20.toLowerCase() === "memory.md";
+    const isMainMemory = basename21.toLowerCase() === "memory.md";
     return denyOutput(
       isMainMemory ? "MEMORY.md was read this session. Its content is in the compact manifest as 'session memory'." : normalized + ' was already read this session. Memory files rarely change mid-session. Use `token-goat section "' + normalized + '::SectionHeading"` to extract one section.'
     );
   }
-  if (/^\.improve-state-.*\.json$/.test(basename20) && wasFileReadThisSession(normalized)) {
+  if (/^\.improve-state-.*\.json$/.test(basename21) && wasFileReadThisSession(normalized)) {
     recordActualRead(event, normalized);
     recordStat("session_hint", 0, 0);
     return denyOutput(
       "Orchestrator state already read this session. " + sessionArtifactRecall(normalized)
     );
   }
-  if (/^\.env(\.\w+)?$/.test(basename20) && wasFileReadThisSession(normalized)) {
+  if (/^\.env(\.\w+)?$/.test(basename21) && wasFileReadThisSession(normalized)) {
     recordActualRead(event, normalized);
     recordStat("session_hint", 0, 0);
     return denyOutput(
@@ -16780,19 +16905,19 @@ function preReadHandlerInner(event) {
         );
       }
       const artifactSessionId = getSessionId();
-      const snapDiff = loadSnapshotDiff(artifactSessionId, normalized, basename20);
+      const snapDiff = loadSnapshotDiff(artifactSessionId, normalized, basename21);
       if (snapDiff.kind === "unchanged") {
         recordActualRead(event, normalized);
         recordStat("session_hint", 0, 0);
         return denyOutput(
-          basename20 + " is unchanged since last read. " + sessionArtifactRecall(normalized)
+          basename21 + " is unchanged since last read. " + sessionArtifactRecall(normalized)
         );
       }
       if (snapDiff.kind === "diff") {
         recordActualRead(event, normalized);
         recordStat("session_hint", snapDiff.savedBytes, Math.round(snapDiff.savedBytes / 4));
         return denyOutput(
-          "Content changed since last read of " + basename20 + ". Here is what changed:\n\n```diff\n" + snapDiff.diff + "\n```\n\n" + sessionArtifactRecall(normalized)
+          "Content changed since last read of " + basename21 + ". Here is what changed:\n\n```diff\n" + snapDiff.diff + "\n```\n\n" + sessionArtifactRecall(normalized)
         );
       }
       recordActualRead(event, normalized);
@@ -16815,8 +16940,8 @@ function preReadHandlerInner(event) {
       return quietContextOutput(label + ": " + sessionArtifactRecall(normalized));
     }
   }
-  const isDocDiffable = /\.(md|mdx|markdown|rst|txt)$/i.test(basename20);
-  const isSourceDiffable = loadConfig().hints.serve_diff_on_reread && DIFFABLE_SOURCE_RE.test(basename20);
+  const isDocDiffable = /\.(md|mdx|markdown|rst|txt)$/i.test(basename21);
+  const isSourceDiffable = loadConfig().hints.serve_diff_on_reread && DIFFABLE_SOURCE_RE.test(basename21);
   if ((isDocDiffable || isSourceDiffable) && wasFileReadThisSession(normalized) && !isProtectedRecentRead(normalized, loadConfig().hints.protect_recent_reads)) {
     if (wasFileTruncatedThisSession(normalized)) {
       if (estimateTruncatedLineCount(normalized) >= loadConfig().hints.truncated_read_min_lines) {
@@ -16826,12 +16951,12 @@ function preReadHandlerInner(event) {
       }
     }
     const sessionId = getSessionId();
-    const snapDiff = loadSnapshotDiff(sessionId, normalized, basename20);
+    const snapDiff = loadSnapshotDiff(sessionId, normalized, basename21);
     if (snapDiff.kind === "unchanged") {
       recordActualRead(event, normalized);
       recordStat("session_hint", 0, 0);
       return denyOutput(
-        (basename20 + " is unchanged since last read. " + surgicalHint(normalized, basename20, countTextLines(snapDiff.currentContent))).trimEnd()
+        (basename21 + " is unchanged since last read. " + surgicalHint(normalized, basename21, countTextLines(snapDiff.currentContent))).trimEnd()
       );
     }
     if (snapDiff.kind === "diff") {
@@ -16839,7 +16964,7 @@ function preReadHandlerInner(event) {
         recordActualRead(event, normalized);
         recordStat("diff_hint", snapDiff.savedBytes, Math.round(snapDiff.savedBytes / 4));
         return denyOutput(
-          ("Content changed since last read of " + basename20 + ". Here is what changed:\n\n```diff\n" + snapDiff.diff + "\n```\n\n" + surgicalHint(normalized, basename20, countTextLines(snapDiff.currentContent))).trimEnd()
+          ("Content changed since last read of " + basename21 + ". Here is what changed:\n\n```diff\n" + snapDiff.diff + "\n```\n\n" + surgicalHint(normalized, basename21, countTextLines(snapDiff.currentContent))).trimEnd()
         );
       }
     }
@@ -16885,13 +17010,13 @@ function preReadHandlerInner(event) {
           return denyOutput(truncatedReadDenyMessage(normalized));
         }
       }
-      if (/\.(md|mdx|markdown|rst)$/i.test(basename20)) {
+      if (/\.(md|mdx|markdown|rst)$/i.test(basename21)) {
         recordStat("session_hint", rereadBytes, Math.round(rereadBytes / 4));
         return denyOutput(
           'Markdown file already read this session. Use `token-goat section "' + normalized + '::HeadingName"` to read one section. ' + editAnywayHint(normalized)
         );
       }
-      const isSourceExt = isSourceExtension(basename20);
+      const isSourceExt = isSourceExtension(basename21);
       if (isSourceExt && reads >= 2) {
         recordStat("read_count_deny", rereadBytes, Math.round(rereadBytes / 4));
         recordStat("session_hint", rereadBytes, Math.round(rereadBytes / 4));
@@ -18226,7 +18351,7 @@ function fetchTopSymbols(limit, dbPath, rootDir) {
     const db = getDb(dbPath);
     const { clause, param } = projectScopeClause("file_path");
     const rows = db.prepare(
-      `SELECT file_path, name, kind, line_start, line_end, body, docstring
+      `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,
@@ -18240,7 +18365,8 @@ function fetchTopSymbols(limit, dbPath, rootDir) {
       lineStart: r.line_start,
       lineEnd: r.line_end,
       body: r.body ?? "",
-      docstring: r.docstring ?? ""
+      docstring: r.docstring ?? "",
+      parent: r.parent ?? ""
     }));
   } catch {
     return [];
@@ -18355,9 +18481,9 @@ function formatMemSuggestions(projectRoot) {
   if (suggestions.length === 0) return "";
   const lines2 = ["", "## mem suggestions"];
   for (const s of suggestions) {
-    const basename20 = path24.basename(s.path);
+    const basename21 = path24.basename(s.path);
     lines2.push(
-      "Consider: mem import --from-md " + s.path + "  # migrates " + s.count + " preference-shaped lines from " + basename20 + " as pending facts for review"
+      "Consider: mem import --from-md " + s.path + "  # migrates " + s.count + " preference-shaped lines from " + basename21 + " as pending facts for review"
     );
   }
   return lines2.join(String.fromCharCode(10));
@@ -18436,7 +18562,8 @@ function toSymbolEntry(row) {
     lineStart: row.line_start,
     lineEnd: row.line_end,
     body: row.body ?? "",
-    docstring: row.docstring ?? ""
+    docstring: row.docstring ?? "",
+    parent: row.parent ?? ""
   };
 }
 function toRefEntry(row) {
@@ -18475,7 +18602,7 @@ function buildSymbolWhere(opts) {
 function querySymbols(opts = {}, dbPath = globalDbPath()) {
   const { clause, params } = buildSymbolWhere(opts);
   const limit = opts.limit ?? 100;
-  const sql = `SELECT file_path, name, kind, line_start, line_end, body, docstring FROM symbols ${clause} ORDER BY file_path, line_start LIMIT ?`;
+  const sql = `SELECT file_path, name, kind, line_start, line_end, body, docstring, parent FROM symbols ${clause} ORDER BY file_path, line_start LIMIT ?`;
   const db = getDb(dbPath);
   const rows = db.prepare(sql).all(...params, limit);
   return rows.map(toSymbolEntry);
@@ -18554,7 +18681,7 @@ function sanitizeFtsQuery(query, join46 = "AND") {
   return terms.join(join46 === "OR" ? " OR " : " ");
 }
 function runFtsQuery(db, match2, limit, scope, rootDir) {
-  const sql = `SELECT s.file_path, s.name, s.kind, s.line_start, s.line_end, s.body, s.docstring FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE symbols_fts MATCH ?${scope !== void 0 ? ` AND ${scope.clause}` : ""} ORDER BY bm25(symbols_fts) LIMIT ?`;
+  const sql = `SELECT s.file_path, s.name, s.kind, s.line_start, s.line_end, s.body, s.docstring, s.parent FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE symbols_fts MATCH ?${scope !== void 0 ? ` AND ${scope.clause}` : ""} ORDER BY bm25(symbols_fts) LIMIT ?`;
   const params = [match2];
   if (scope !== void 0 && rootDir !== void 0) {
     params.push(scope.param(rootDir));
@@ -18623,12 +18750,12 @@ function extractCsharp(content, filePath) {
     }
     const nsM = NAMESPACE_RE.exec(stripped);
     if (nsM) {
-      symbols.push(makeLineSymbol(filePath, nsM[1] ?? "", "namespace", lineNum, stripped.slice(0, 200)));
+      symbols.push(makeLineSymbol(filePath, nsM[1] ?? "", "namespace", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
     }
     const delM = DELEGATE_RE.exec(stripLeadingAttributes(stripped));
     if (delM) {
       const delegateParent = classStack.length > 0 ? classStack[classStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, delM[1] ?? "", "interface", lineNum, stripped.slice(0, 200), delegateParent));
+      symbols.push(makeLineSymbol(filePath, delM[1] ?? "", "interface", lineNum, stripped.slice(0, 200), delegateParent, lines2, "c"));
     }
     const cm = CLASS_HEADER_RE.exec(stripLeadingAttributes(stripped));
     if (cm) {
@@ -18636,7 +18763,7 @@ function extractCsharp(content, filePath) {
       const cname = cm[2] ?? "";
       const kind = keyword === "struct" ? "struct" : keyword === "interface" ? "interface" : keyword === "enum" ? "enum" : "class";
       const parent = classStack.length > 0 ? classStack[classStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, cname, kind, lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, cname, kind, lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       classStack.push({ name: cname, startDepth: braceDepth, bodyEntered: false });
     }
     const frame = classStack.length > 0 ? classStack[classStack.length - 1] : null;
@@ -18648,13 +18775,13 @@ function extractCsharp(content, filePath) {
         if (ctorM && ctorM[1] === frame.name) {
           const sigEnd = line.indexOf("{");
           const sig = sigEnd >= 0 ? line.slice(0, sigEnd).trimEnd() : line.trimEnd();
-          symbols.push(makeLineSymbol(filePath, frame.name, "method", lineNum, sig.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, frame.name, "method", lineNum, sig.slice(0, 200), frame.name, lines2, "c"));
         }
         let isPropertyLine = false;
         const propM = PROPERTY_RE.exec(lineNoAttr);
         if (propM) {
           isPropertyLine = true;
-          symbols.push(makeLineSymbol(filePath, propM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, propM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         } else {
           const headerM = PROPERTY_HEADER_RE.exec(lineNoAttr);
           if (headerM) {
@@ -18662,13 +18789,13 @@ function extractCsharp(content, filePath) {
             const accessorLine = (lines2[i + 2] ?? "").trim();
             if (braceLineNext === "{" && (ALLMAN_ACCESSOR_RE.test(accessorLine) || ALLMAN_ACCESSOR_BODY_RE.test(accessorLine))) {
               isPropertyLine = true;
-              symbols.push(makeLineSymbol(filePath, headerM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name));
+              symbols.push(makeLineSymbol(filePath, headerM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
             }
           } else {
             const arrowM = PROPERTY_ARROW_RE.exec(lineNoAttr);
             if (arrowM) {
               isPropertyLine = true;
-              symbols.push(makeLineSymbol(filePath, arrowM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name));
+              symbols.push(makeLineSymbol(filePath, arrowM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
             }
           }
         }
@@ -18678,7 +18805,7 @@ function extractCsharp(content, filePath) {
           if (mname && mname !== frame.name) {
             const sigEnd = line.indexOf("{");
             const sig = sigEnd >= 0 ? line.slice(0, sigEnd).trimEnd() : line.trimEnd();
-            symbols.push(makeLineSymbol(filePath, mname, "method", lineNum, sig.slice(0, 200), frame.name));
+            symbols.push(makeLineSymbol(filePath, mname, "method", lineNum, sig.slice(0, 200), frame.name, lines2, "c"));
           }
         }
       }
@@ -18783,7 +18910,7 @@ function extractPhp(content, filePath) {
     }
     const nsM = NAMESPACE_RE2.exec(stripped);
     if (nsM) {
-      symbols.push(makeLineSymbol(filePath, nsM[1] ?? "", "namespace", lineNum, stripped.slice(0, 200)));
+      symbols.push(makeLineSymbol(filePath, nsM[1] ?? "", "namespace", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
       continue;
     }
     if (contextStack.length === 0) {
@@ -18817,7 +18944,7 @@ function extractPhp(content, filePath) {
       const preLineDepth = braceDepth - openB + closeB;
       const topFrame2 = contextStack.length > 0 ? contextStack[contextStack.length - 1] : void 0;
       const parent = topFrame2 !== void 0 && preLineDepth === topFrame2[1] + 1 ? topFrame2[0] : null;
-      symbols.push(makeLineSymbol(filePath, name2, kind, lineNum, stripped.slice(0, 200), parent ?? void 0));
+      symbols.push(makeLineSymbol(filePath, name2, kind, lineNum, stripped.slice(0, 200), parent ?? void 0, lines2, "c"));
       contextStack.push([name2, braceDepth - openB + closeB, false]);
       if (openB > 0 && openB === closeB) {
         contextStack.pop();
@@ -18834,7 +18961,7 @@ function extractPhp(content, filePath) {
       const kind = parent ? "method" : "function";
       const sigEnd = stripped.indexOf(")");
       const sig = sigEnd >= 0 ? stripped.slice(0, sigEnd + 1) : stripped;
-      symbols.push(makeLineSymbol(filePath, name2, kind, lineNum, sig.slice(0, 200), parent ?? void 0));
+      symbols.push(makeLineSymbol(filePath, name2, kind, lineNum, sig.slice(0, 200), parent ?? void 0, lines2, "c"));
       continue;
     }
     const propM = PROP_RE.exec(stripped);
@@ -18843,7 +18970,7 @@ function extractPhp(content, filePath) {
       const preLineDepth = braceDepth - openB + closeB;
       const topFrame2 = contextStack.length > 0 ? contextStack[contextStack.length - 1] : void 0;
       if (topFrame2 !== void 0 && preLineDepth === topFrame2[1] + 1) {
-        symbols.push(makeLineSymbol(filePath, name2, "var", lineNum, stripped.slice(0, 200), topFrame2[0]));
+        symbols.push(makeLineSymbol(filePath, name2, "var", lineNum, stripped.slice(0, 200), topFrame2[0], lines2, "c"));
       }
       continue;
     }
@@ -18853,12 +18980,12 @@ function extractPhp(content, filePath) {
       const preLineDepth = braceDepth - openB + closeB;
       const topFrame2 = contextStack.length > 0 ? contextStack[contextStack.length - 1] : void 0;
       const parent = topFrame2 !== void 0 && preLineDepth === topFrame2[1] + 1 ? topFrame2[0] : void 0;
-      symbols.push(makeLineSymbol(filePath, name2, "const", lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, name2, "const", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       continue;
     }
     const defineM = DEFINE_RE.exec(stripped);
     if (defineM) {
-      symbols.push(makeLineSymbol(filePath, defineM[1] ?? "", "const", lineNum, stripped.slice(0, 200)));
+      symbols.push(makeLineSymbol(filePath, defineM[1] ?? "", "const", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
     }
   }
   return { symbols, imports };
@@ -18923,7 +19050,7 @@ function extractHtml(content, filePath) {
       const key = `${idVal}\0${line}`;
       if (!seenId.has(key)) {
         seenId.add(key);
-        symbols.push({ filePath, name: idVal, kind: "html_id", lineStart: line, lineEnd: line, body: "", docstring: "" });
+        symbols.push({ filePath, name: idVal, kind: "html_id", lineStart: line, lineEnd: line, body: "", docstring: "", parent: "" });
       }
     }
   }
@@ -18938,7 +19065,7 @@ function extractHtml(content, filePath) {
           const key = `${cls}\0${line}`;
           if (!seenClass.has(key)) {
             seenClass.add(key);
-            symbols.push({ filePath, name: cls, kind: "html_class", lineStart: line, lineEnd: line, body: "", docstring: "" });
+            symbols.push({ filePath, name: cls, kind: "html_class", lineStart: line, lineEnd: line, body: "", docstring: "", parent: "" });
           }
         }
       }
@@ -19041,7 +19168,7 @@ function extractLiquid(content, filePath, relPath) {
         if (name2) {
           const line = offsetToLine(lineIndex, m.index ?? 0);
           const endLine = offsetToLine(lineIndex, (m.index ?? 0) + (m[0]?.length ?? 0));
-          symbols.push({ filePath, name: name2, kind: "liquid_schema", lineStart: line, lineEnd: endLine, body: "", docstring: "" });
+          symbols.push({ filePath, name: name2, kind: "liquid_schema", lineStart: line, lineEnd: endLine, body: "", docstring: "", parent: "" });
         }
       }
     } catch {
@@ -19051,7 +19178,7 @@ function extractLiquid(content, filePath, relPath) {
   const relPosix = resolvedRel.replace(/\\/g, "/");
   if (relPosix.startsWith("sections/") || relPosix.includes("/sections/")) {
     const stem = path27.basename(resolvedRel, path27.extname(resolvedRel));
-    symbols.push({ filePath, name: stem, kind: "liquid_section_file", lineStart: 1, lineEnd: 1, body: "", docstring: "" });
+    symbols.push({ filePath, name: stem, kind: "liquid_section_file", lineStart: 1, lineEnd: 1, body: "", docstring: "", parent: "" });
   }
   const totalLines = content.split("\n").length;
   for (const hm of findHtmlHeadingMatches(content)) {
@@ -19142,14 +19269,14 @@ function extractKotlin(content, filePath) {
     if (companionM) {
       const cname = companionM[1] ?? "Companion";
       const parent = classStack.length > 0 ? classStack[classStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, cname, "object", lineNum, line.trimEnd().slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, cname, "object", lineNum, line.trimEnd().slice(0, 200), parent, lines2, "c"));
       classStack.push({ name: cname, braceDepth, bodyEntered: false, parenBalance: 0, pendingPop: false });
     } else if (cm) {
       const ckeyword = cm[1] ?? "class";
       const cname = cm[2] ?? "";
       const ckind = ckeyword === "interface" ? "interface" : ckeyword === "object" ? "object" : "class";
       const parent = classStack.length > 0 ? classStack[classStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, cname, ckind, lineNum, line.trimEnd().slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, cname, ckind, lineNum, line.trimEnd().slice(0, 200), parent, lines2, "c"));
       classStack.push({ name: cname, braceDepth, bodyEntered: false, parenBalance: 0, pendingPop: false });
     }
     const frame = classStack.length > 0 ? classStack[classStack.length - 1] : null;
@@ -19162,11 +19289,11 @@ function extractKotlin(content, filePath) {
           const fname = fm[1] ?? "";
           const sigEnd = line.indexOf("{");
           const sig = sigEnd >= 0 ? line.slice(0, sigEnd).trim() : line.trimEnd();
-          symbols.push(makeLineSymbol(filePath, fname, "method", lineNum, sig.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, fname, "method", lineNum, sig.slice(0, 200), frame.name, lines2, "c"));
         }
         const constM = CONST_RE2.exec(lineNoAnn);
         if (constM) {
-          symbols.push(makeLineSymbol(filePath, constM[1] ?? "", "const", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, constM[1] ?? "", "const", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         }
       }
     } else if (!isIndented) {
@@ -19176,11 +19303,11 @@ function extractKotlin(content, filePath) {
         const fname = tfm[1] ?? "";
         const sigEnd = line.indexOf("{");
         const sig = sigEnd >= 0 ? line.slice(0, sigEnd).trim() : line.trimEnd();
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, sig.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, sig.slice(0, 200), void 0, lines2, "c"));
       }
       const topConstM = CONST_RE2.exec(lineNoAnn);
       if (topConstM) {
-        symbols.push(makeLineSymbol(filePath, topConstM[1] ?? "", "const", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, topConstM[1] ?? "", "const", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
       }
     }
     const braceLine = stripStringLiterals(line);
@@ -19284,7 +19411,7 @@ function extractSwift(content, filePath) {
       const tname = tm[2] ?? "";
       const kind = keyword === "struct" ? "struct" : keyword === "enum" ? "enum" : keyword === "protocol" ? "protocol" : keyword === "extension" ? "extension" : keyword === "actor" ? "actor" : "class";
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, tname, kind, lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, tname, kind, lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       typeStack.push({ name: tname, startDepth: braceDepth, bodyEntered: false });
     }
     const frame = typeStack.length > 0 ? typeStack[typeStack.length - 1] : null;
@@ -19297,17 +19424,17 @@ function extractSwift(content, filePath) {
         const subscriptM = SUBSCRIPT_RE.exec(lineNoAttr);
         const fm = FUNC_RE.exec(lineNoAttr);
         if (initM) {
-          symbols.push(makeLineSymbol(filePath, initM[1] ?? "init", "method", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, initM[1] ?? "init", "method", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         } else if (deinitM) {
-          symbols.push(makeLineSymbol(filePath, "deinit", "method", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, "deinit", "method", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         } else if (subscriptM) {
-          symbols.push(makeLineSymbol(filePath, subscriptM[1] ?? "subscript", "method", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, subscriptM[1] ?? "subscript", "method", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         } else if (fm) {
-          symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "method", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "method", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         } else {
           const propM = PROPERTY_RE2.exec(lineNoAttr);
           if (propM) {
-            symbols.push(makeLineSymbol(filePath, propM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name));
+            symbols.push(makeLineSymbol(filePath, propM[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
           }
         }
       }
@@ -19315,7 +19442,7 @@ function extractSwift(content, filePath) {
       const lineNoAttr = stripLeadingAttributes2(line);
       const fm = FUNC_RE.exec(lineNoAttr);
       if (fm) {
-        symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
       }
     }
     const braceLine = stripStringLiterals(line);
@@ -19412,7 +19539,7 @@ function extractScala(content, filePath) {
     if (cm) {
       const cname = cm[1] ?? "";
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, cname, "class", lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, cname, "class", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       typeStack.push({ name: cname, startDepth: braceDepth, bodyEntered: false });
       if (/\bcase\s+class\b/.test(stripped) && !stripStringLiterals(line).includes("{")) {
         typeStack.pop();
@@ -19423,7 +19550,7 @@ function extractScala(content, filePath) {
     if (om) {
       const oname = om[1] ?? "";
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, oname, "object", lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, oname, "object", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       typeStack.push({ name: oname, startDepth: braceDepth, bodyEntered: false });
       if (/\bcase\s+object\b/.test(stripped) && !stripStringLiterals(line).includes("{")) {
         typeStack.pop();
@@ -19434,7 +19561,7 @@ function extractScala(content, filePath) {
     if (tm) {
       const tname = tm[1] ?? "";
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, tname, "trait", lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, tname, "trait", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       typeStack.push({ name: tname, startDepth: braceDepth, bodyEntered: false });
       matched = true;
     }
@@ -19442,7 +19569,7 @@ function extractScala(content, filePath) {
     if (enm) {
       const enname = enm[1] ?? "";
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-      symbols.push(makeLineSymbol(filePath, enname, "enum", lineNum, stripped.slice(0, 200), parent));
+      symbols.push(makeLineSymbol(filePath, enname, "enum", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
       typeStack.push({ name: enname, startDepth: braceDepth, bodyEntered: false });
       matched = true;
     }
@@ -19452,36 +19579,36 @@ function extractScala(content, filePath) {
       if (depthInType === 1) {
         const fm = FUNC_RE2.exec(stripped);
         if (fm) {
-          symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
           matched = true;
         }
         const vm = !matched ? VAL_RE.exec(stripped) : null;
         if (vm) {
-          symbols.push(makeLineSymbol(filePath, vm[1] ?? "", "val", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, vm[1] ?? "", "val", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
           matched = true;
         }
         if (!matched) {
           const varm = VAR_RE.exec(stripped);
           if (varm) {
-            symbols.push(makeLineSymbol(filePath, varm[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name));
+            symbols.push(makeLineSymbol(filePath, varm[1] ?? "", "var", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
           }
         }
       }
     } else if (!matched && frame === null && !isIndented) {
       const fm = FUNC_RE2.exec(stripped);
       if (fm) {
-        symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
         matched = true;
       }
       const vm = !matched ? VAL_RE.exec(stripped) : null;
       if (vm) {
-        symbols.push(makeLineSymbol(filePath, vm[1] ?? "", "val", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, vm[1] ?? "", "val", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
         matched = true;
       }
       if (!matched) {
         const varm = VAR_RE.exec(stripped);
         if (varm) {
-          symbols.push(makeLineSymbol(filePath, varm[1] ?? "", "var", lineNum, stripped.slice(0, 200)));
+          symbols.push(makeLineSymbol(filePath, varm[1] ?? "", "var", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
         }
       }
     }
@@ -19660,14 +19787,14 @@ function extractElixir(content, filePath) {
     const modM = MODULE_RE.exec(stripped);
     if (modM) {
       const modName = modM[1] ?? "";
-      symbols.push(makeLineSymbol(filePath, modName, "class", lineNum, stripped.slice(0, 200)));
+      symbols.push(makeLineSymbol(filePath, modName, "class", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
       moduleStack.push({ name: modName, endKeywordNeeded: true, isBlock: false });
       continue;
     }
     const protoM = PROTOCOL_RE.exec(stripped);
     if (protoM) {
       const protoName = protoM[1] ?? "";
-      symbols.push(makeLineSymbol(filePath, protoName, "protocol", lineNum, stripped.slice(0, 200)));
+      symbols.push(makeLineSymbol(filePath, protoName, "protocol", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
       moduleStack.push({ name: protoName, endKeywordNeeded: true, isBlock: false });
       continue;
     }
@@ -19676,9 +19803,9 @@ function extractElixir(content, filePath) {
       const fname = fm[1] ?? "";
       const parent = nearestDefName(moduleStack);
       if (parent !== void 0) {
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), parent, lines2, "hash"));
       } else {
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
       }
       if (opensDoBlock) {
         moduleStack.push({ name: fname, endKeywordNeeded: true, isBlock: false });
@@ -19690,9 +19817,9 @@ function extractElixir(content, filePath) {
       const fname = pfm[1] ?? "";
       const parent = nearestDefName(moduleStack);
       if (parent !== void 0) {
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), parent, lines2, "hash"));
       } else {
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
       }
       if (opensDoBlock) {
         moduleStack.push({ name: fname, endKeywordNeeded: true, isBlock: false });
@@ -19702,7 +19829,7 @@ function extractElixir(content, filePath) {
     if (STRUCT_RE.test(stripped)) {
       const parent = nearestDefName(moduleStack);
       if (parent !== void 0) {
-        symbols.push(makeLineSymbol(filePath, "__struct__", "var", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, "__struct__", "var", lineNum, stripped.slice(0, 200), parent, lines2, "hash"));
       }
       continue;
     }
@@ -19762,7 +19889,7 @@ function extractDart(content, filePath) {
       if (cm) {
         const cname = cm[1] ?? "";
         const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-        symbols.push(makeLineSymbol(filePath, cname, "class", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, cname, "class", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
         typeStack.push({ name: cname, startDepth: braceDepth, bodyEntered: false });
         matched = true;
       }
@@ -19770,7 +19897,7 @@ function extractDart(content, filePath) {
       if (em) {
         const ename = em[1] ?? "";
         const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-        symbols.push(makeLineSymbol(filePath, ename, "enum", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, ename, "enum", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
         typeStack.push({ name: ename, startDepth: braceDepth, bodyEntered: false });
         matched = true;
       }
@@ -19778,7 +19905,7 @@ function extractDart(content, filePath) {
       if (mm) {
         const mname = mm[1] ?? "";
         const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-        symbols.push(makeLineSymbol(filePath, mname, "mixin", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, mname, "mixin", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
         typeStack.push({ name: mname, startDepth: braceDepth, bodyEntered: false });
         matched = true;
       }
@@ -19786,7 +19913,7 @@ function extractDart(content, filePath) {
       if (etm) {
         const etname = etm[1] ?? "";
         const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-        symbols.push(makeLineSymbol(filePath, etname, "extension_type", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, etname, "extension_type", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
         typeStack.push({ name: etname, startDepth: braceDepth, bodyEntered: false });
         matched = true;
       }
@@ -19794,7 +19921,7 @@ function extractDart(content, filePath) {
       if (extm) {
         const extname14 = extm[1] ?? "extension";
         const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
-        symbols.push(makeLineSymbol(filePath, extname14, "extension", lineNum, stripped.slice(0, 200), parent));
+        symbols.push(makeLineSymbol(filePath, extname14, "extension", lineNum, stripped.slice(0, 200), parent, lines2, "c"));
         typeStack.push({ name: extname14, startDepth: braceDepth, bodyEntered: false });
         matched = true;
       }
@@ -19807,7 +19934,7 @@ function extractDart(content, filePath) {
         if (fm) {
           let fname = fm[1] ?? "";
           fname = fname.replace(/^operator\s+/, "");
-          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
         }
       }
     } else if (!matched && frame === null && !isIndented) {
@@ -19815,7 +19942,7 @@ function extractDart(content, filePath) {
       if (fm) {
         let fname = fm[1] ?? "";
         fname = fname.replace(/^operator\s+/, "");
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
       }
     }
     const braceLine = stripStringLiterals(line);
@@ -19887,7 +20014,7 @@ function extractZig(content, filePath) {
         const skind = sm[2] ?? "struct";
         if (sname) {
           const parent = outerFrame !== null ? outerFrame.name : void 0;
-          symbols.push(makeLineSymbol(filePath, sname, skind, lineNum, stripped.slice(0, 200), parent));
+          symbols.push(makeLineSymbol(filePath, sname, skind, lineNum, stripped.slice(0, 200), parent, lines2, "c"));
           scopeStack.push({ name: sname, startDepth: braceDepth, bodyEntered: false });
           matched = true;
         }
@@ -19898,7 +20025,7 @@ function extractZig(content, filePath) {
       const fm = FUNC_RE6.exec(stripped);
       if (fm) {
         const fname = fm[2] ?? "";
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
         matched = true;
       }
     } else if (!matched && frame !== null) {
@@ -19907,7 +20034,7 @@ function extractZig(content, filePath) {
         const fm = FUNC_RE6.exec(stripped);
         if (fm) {
           const fname = fm[2] ?? "";
-          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), frame.name));
+          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), frame.name, lines2, "c"));
           matched = true;
         }
       }
@@ -19915,13 +20042,13 @@ function extractZig(content, filePath) {
     if (!matched && !isIndented) {
       const cm = CONST_RE3.exec(stripped);
       if (cm) {
-        symbols.push(makeLineSymbol(filePath, cm[1] ?? "", "const", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, cm[1] ?? "", "const", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
         matched = true;
       }
       if (!matched) {
         const vm = VAR_RE2.exec(stripped);
         if (vm) {
-          symbols.push(makeLineSymbol(filePath, vm[1] ?? "", "var", lineNum, stripped.slice(0, 200)));
+          symbols.push(makeLineSymbol(filePath, vm[1] ?? "", "var", lineNum, stripped.slice(0, 200), void 0, lines2, "c"));
         }
       }
     }
@@ -19980,17 +20107,17 @@ function extractR(content, filePath) {
     if (!isIndented) {
       const fm = FUNC_ASSIGN_RE.exec(stripped);
       if (fm) {
-        symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, fm[1] ?? "", "function", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
         continue;
       }
       const cm = SETCLASS_RE.exec(stripped);
       if (cm) {
-        symbols.push(makeLineSymbol(filePath, cm[1] ?? "", "class", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, cm[1] ?? "", "class", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
         continue;
       }
       const mm = SETMETHOD_RE.exec(stripped);
       if (mm) {
-        symbols.push(makeLineSymbol(filePath, mm[1] ?? "", "function", lineNum, stripped.slice(0, 200)));
+        symbols.push(makeLineSymbol(filePath, mm[1] ?? "", "function", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
       }
     }
   }
@@ -20524,7 +20651,7 @@ function extractBash(content, filePath) {
       if (funcMatch) {
         const fname = funcMatch[1] ?? "";
         if (fname && symbols.length < MAX_SYMBOLS4) {
-          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200)));
+          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
         }
         if (fname) {
           if (stripped.includes("{")) {
@@ -20545,7 +20672,7 @@ function extractBash(content, filePath) {
         if (varMatch) {
           const vname = varMatch[1] ?? "";
           if (vname && symbols.length < MAX_SYMBOLS4) {
-            symbols.push(makeLineSymbol(filePath, vname, "variable", lineNum, stripped.slice(0, 200)));
+            symbols.push(makeLineSymbol(filePath, vname, "variable", lineNum, stripped.slice(0, 200), void 0, lines2, "hash"));
           }
         }
       }
@@ -21054,7 +21181,7 @@ function extractPowershell(content, filePath) {
       if (funcMatch) {
         const fname = funcMatch[1] ?? "";
         if (symbols.length < MAX_SYMBOLS8) {
-          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, line.trimEnd().slice(0, 200)));
+          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, line.trimEnd().slice(0, 200), void 0, lines2, "hash"));
         }
       }
     }
@@ -21064,7 +21191,7 @@ function extractPowershell(content, filePath) {
         const cname = classMatch[2] ?? "";
         const kind = (classMatch[1] ?? "").toLowerCase() === "enum" ? "enum" : "class";
         if (symbols.length < MAX_SYMBOLS8) {
-          symbols.push(makeLineSymbol(filePath, cname, kind, lineNum, line.trimEnd().slice(0, 200)));
+          symbols.push(makeLineSymbol(filePath, cname, kind, lineNum, line.trimEnd().slice(0, 200), void 0, lines2, "hash"));
         }
         if (kind === "class") {
           const strippedLine = stripPowershellStringLiterals(line);
@@ -21089,7 +21216,7 @@ function extractPowershell(content, filePath) {
           if (mname && symbols.length < MAX_SYMBOLS8) {
             const sigEnd = line.indexOf("{");
             const sig = sigEnd >= 0 ? line.slice(0, sigEnd).trimEnd() : line.trimEnd();
-            symbols.push(makeLineSymbol(filePath, mname, "method", lineNum, sig.slice(0, 200), currentClass));
+            symbols.push(makeLineSymbol(filePath, mname, "method", lineNum, sig.slice(0, 200), currentClass, lines2, "hash"));
           }
         }
       }
@@ -21187,12 +21314,13 @@ function extractApex(content, filePath) {
   const stringFree = stripStringLiterals(blockCommentFree);
   const code = stripCstyleComments(stringFree, /\/\/.*$/gm);
   const codeLines = code.split(/\r?\n/);
-  const emit5 = (name2, kind, span, docstring = "") => {
+  const rawLines = content.split(/\r?\n/);
+  const emit5 = (name2, kind, span, parent = "") => {
     if (!name2 || symbols.length >= MAX_SYMBOLS9) return;
     const key = `${name2}\0${kind}\0${span.startLine}`;
     if (seen.has(key)) return;
     seen.add(key);
-    symbols.push(makeSpanSymbol(filePath, name2, kind, span, docstring));
+    symbols.push(makeSpanSymbol(filePath, name2, kind, span, parent, rawLines, "c"));
   };
   for (const match2 of code.matchAll(TRIGGER_RE2)) {
     const name2 = match2[1] ?? "";
@@ -21638,7 +21766,7 @@ function lwcTagAlias(name2) {
   return `c-${kebab}`;
 }
 function symbol(filePath, name2, kind, lineStart, lineEnd = lineStart) {
-  return { filePath, name: name2, kind, lineStart, lineEnd, body: "", docstring: "" };
+  return { filePath, name: name2, kind, lineStart, lineEnd, body: "", docstring: "", parent: "" };
 }
 function ref(filePath, name2, line, col, context) {
   return { filePath, name: name2, line, col, context };
@@ -21910,7 +22038,7 @@ function maskSpans(content, spans) {
   return chars.join("");
 }
 function componentSymbol(filePath, name2, kind, totalLines) {
-  return { filePath, name: name2, kind, lineStart: 1, lineEnd: totalLines, body: "", docstring: "" };
+  return { filePath, name: name2, kind, lineStart: 1, lineEnd: totalLines, body: "", docstring: "", parent: "" };
 }
 function extractVue(content, filePath) {
   const totalLines = content.split("\n").length;
@@ -22188,15 +22316,17 @@ function nodeName(node) {
   if (named !== null) return named.text;
   return null;
 }
-function makeSymbol(filePath, name2, kind, node) {
+function makeSymbol(filePath, name2, kind, node, lines2, style) {
+  const lineStart = node.startPosition.row + 1;
   return {
     filePath,
     name: name2,
     kind,
-    lineStart: node.startPosition.row + 1,
+    lineStart,
     lineEnd: node.endPosition.row + 1,
     body: node.text,
-    docstring: ""
+    docstring: lines2 !== void 0 && style !== void 0 ? precedingDocComment(lines2, lineStart, style) : "",
+    parent: ""
   };
 }
 function collectPatternBindings(node) {
@@ -22211,7 +22341,7 @@ function collectPatternBindings(node) {
   walk(node);
   return names;
 }
-function extractTsJsSymbols(root, filePath) {
+function extractTsJsSymbols(root, filePath, lines2) {
   const out2 = [];
   const visit = (node, insideFunction) => {
     const kind = TSJS_KIND_BY_TYPE.get(node.type);
@@ -22220,16 +22350,18 @@ function extractTsJsSymbols(root, filePath) {
       if (name2 !== null && name2 !== "") {
         const decorators = leadingTsDecorators(node);
         if (decorators.length === 0) {
-          out2.push(makeSymbol(filePath, name2, kind, node));
+          out2.push(makeSymbol(filePath, name2, kind, node, lines2, "c"));
         } else {
+          const lineStart = decorators[0].startPosition.row + 1;
           out2.push({
             filePath,
             name: name2,
             kind,
-            lineStart: decorators[0].startPosition.row + 1,
+            lineStart,
             lineEnd: node.endPosition.row + 1,
             body: [...decorators, node].map((n) => n.text).join("\n"),
-            docstring: ""
+            docstring: precedingDocComment(lines2, lineStart, "c"),
+            parent: ""
           });
         }
       }
@@ -22242,10 +22374,10 @@ function extractTsJsSymbols(root, filePath) {
         if (name2 === null) continue;
         if (name2.type === "identifier") {
           const isFn = value !== null && (value.type === "arrow_function" || value.type === "function_expression" || value.type === "function");
-          out2.push(makeSymbol(filePath, name2.text, isFn ? "function" : "variable", child));
+          out2.push(makeSymbol(filePath, name2.text, isFn ? "function" : "variable", child, lines2, "c"));
         } else {
           for (const bound of collectPatternBindings(name2)) {
-            out2.push(makeSymbol(filePath, bound, "variable", child));
+            out2.push(makeSymbol(filePath, bound, "variable", child, lines2, "c"));
           }
         }
       }
@@ -22254,7 +22386,7 @@ function extractTsJsSymbols(root, filePath) {
       const fieldName = node.childForFieldName("name") ?? node.childForFieldName("property");
       const value = node.childForFieldName("value");
       if (fieldName !== null && value !== null && (value.type === "arrow_function" || value.type === "function_expression" || value.type === "function")) {
-        out2.push(makeSymbol(filePath, fieldName.text, "method", node));
+        out2.push(makeSymbol(filePath, fieldName.text, "method", node, lines2, "c"));
       }
     }
     const childInside = insideFunction || TSJS_FN_SCOPE_TYPES.has(node.type);
@@ -22318,14 +22450,14 @@ function stripPythonStringQuotes(raw) {
   }
   return s.trim();
 }
-function extractGoSymbols(root, filePath) {
+function extractGoSymbols(root, filePath, lines2) {
   const out2 = [];
   const visit = (node, insideFunction) => {
     const kind = GO_KIND_BY_TYPE.get(node.type);
     if (kind !== void 0 && !(insideFunction && GO_LOCAL_KINDS.has(node.type))) {
       const name2 = nodeName(node);
       if (name2 !== null && name2 !== "") {
-        out2.push(makeSymbol(filePath, name2, kind, node));
+        out2.push(makeSymbol(filePath, name2, kind, node, lines2, "c"));
       }
     }
     const childInside = insideFunction || GO_FN_SCOPE_TYPES.has(node.type);
@@ -22345,7 +22477,7 @@ function leadingRustAttributes(node) {
   }
   return attrs;
 }
-function extractRustSymbols(root, filePath) {
+function extractRustSymbols(root, filePath, lines2) {
   const out2 = [];
   const visit = (node, insideFunction) => {
     const kind = RUST_KIND_BY_TYPE.get(node.type);
@@ -22354,16 +22486,18 @@ function extractRustSymbols(root, filePath) {
       if (name2 !== null && name2 !== "") {
         const attrs = leadingRustAttributes(node);
         if (attrs.length === 0) {
-          out2.push(makeSymbol(filePath, name2, kind, node));
+          out2.push(makeSymbol(filePath, name2, kind, node, lines2, "c"));
         } else {
+          const lineStart = attrs[0].startPosition.row + 1;
           out2.push({
             filePath,
             name: name2,
             kind,
-            lineStart: attrs[0].startPosition.row + 1,
+            lineStart,
             lineEnd: node.endPosition.row + 1,
             body: [...attrs, node].map((n) => n.text).join("\n"),
-            docstring: ""
+            docstring: precedingDocComment(lines2, lineStart, "c"),
+            parent: ""
           });
         }
       }
@@ -22376,14 +22510,14 @@ function extractRustSymbols(root, filePath) {
   visit(root, false);
   return out2;
 }
-function extractSimpleSymbols(root, filePath, kindByType, nameFor = nodeName) {
+function extractSimpleSymbols(root, filePath, kindByType, lines2, style, nameFor = nodeName) {
   const out2 = [];
   const visit = (node) => {
     const kind = kindByType.get(node.type);
     if (kind !== void 0) {
       const name2 = nameFor(node);
       if (name2 !== null && name2 !== "") {
-        out2.push(makeSymbol(filePath, name2, kind, node));
+        out2.push(makeSymbol(filePath, name2, kind, node, lines2, style));
       }
     }
     for (const child of node.namedChildren) {
@@ -22393,17 +22527,19 @@ function extractSimpleSymbols(root, filePath, kindByType, nameFor = nodeName) {
   visit(root);
   return out2;
 }
-function extractRubySymbols(root, filePath) {
-  return extractSimpleSymbols(root, filePath, RUBY_KIND_BY_TYPE);
+function extractRubySymbols(root, filePath, lines2) {
+  return extractSimpleSymbols(root, filePath, RUBY_KIND_BY_TYPE, lines2, "hash");
 }
-function extractJavaSymbols(root, filePath) {
-  return extractSimpleSymbols(root, filePath, JAVA_KIND_BY_TYPE);
+function extractJavaSymbols(root, filePath, lines2) {
+  return extractSimpleSymbols(root, filePath, JAVA_KIND_BY_TYPE, lines2, "c");
 }
-function extractCppSymbols(root, filePath) {
+function extractCppSymbols(root, filePath, lines2) {
   return extractSimpleSymbols(
     root,
     filePath,
     CPP_KIND_BY_TYPE,
+    lines2,
+    "c",
     (node) => node.type === "function_definition" ? cFunctionName(node) : node.type === "type_definition" ? cTypedefAliasName(node) : node.type === "declaration" ? cFunctionPrototypeName(node) : nodeName(node)
   );
 }
@@ -22665,7 +22801,8 @@ function extractMarkdownSymbols(content, filePath) {
           lineStart: i + 1,
           lineEnd: i + 1,
           body: line.trim(),
-          docstring: ""
+          docstring: "",
+          parent: ""
         });
       }
     }
@@ -22724,7 +22861,8 @@ function extractJsonSymbols(content, filePath) {
               lineStart: strStartLine,
               lineEnd,
               body,
-              docstring: ""
+              docstring: "",
+              parent: ""
             });
           }
         }
@@ -22809,7 +22947,8 @@ function extractYamlSymbols(content, filePath) {
         lineStart: i + 1,
         lineEnd: i + 1,
         body: line.trim(),
-        docstring: ""
+        docstring: "",
+        parent: ""
       });
       openQuote = yamlOpenQuoteAfter(line, match2[0].length);
     }
@@ -22861,7 +23000,8 @@ function extractTomlSymbols(content, filePath) {
         lineStart: lineNum + 1,
         lineEnd: lineNum + 1,
         body: line.trim(),
-        docstring: ""
+        docstring: "",
+        parent: ""
       });
     }
     const keyMatch = /^\s*([a-zA-Z_][\w-]*)\s*=/.exec(line);
@@ -22873,7 +23013,8 @@ function extractTomlSymbols(content, filePath) {
         lineStart: lineNum + 1,
         lineEnd: lineNum + 1,
         body: line.trim(),
-        docstring: ""
+        docstring: "",
+        parent: ""
       });
     }
   }
@@ -22947,7 +23088,8 @@ function extractCssSymbols(content, filePath) {
           lineStart: p.line,
           lineEnd: p.line,
           body: p.body,
-          docstring: ""
+          docstring: "",
+          parent: ""
         });
       }
       pending = [];
@@ -22964,7 +23106,8 @@ function extractCssSymbols(content, filePath) {
             lineStart: i + 1,
             lineEnd: i + 1,
             body: line.trim(),
-            docstring: ""
+            docstring: "",
+            parent: ""
           });
         }
       }
@@ -22979,7 +23122,8 @@ function extractCssSymbols(content, filePath) {
           lineStart: p.line,
           lineEnd: p.line,
           body: p.body,
-          docstring: ""
+          docstring: "",
+          parent: ""
         });
       }
       pending = [];
@@ -23023,7 +23167,8 @@ function extractDockerfileSymbols(content, filePath) {
         lineStart: i + 1,
         lineEnd: i + 1,
         body: line.trim(),
-        docstring: ""
+        docstring: "",
+        parent: ""
       });
     }
     continuing = !isComment2 && line.trimEnd().endsWith("\\");
@@ -23036,7 +23181,7 @@ function extractWithRegex(content, filePath) {
   for (let i = 0; i < lines2.length; i++) {
     const line = lines2[i];
     if (line === void 0) continue;
-    for (const { re, kind } of FALLBACK_PATTERNS) {
+    for (const { re, kind, style } of FALLBACK_PATTERNS) {
       const m = re.exec(line);
       if (m !== null && m[1] !== void 0) {
         out2.push({
@@ -23046,7 +23191,8 @@ function extractWithRegex(content, filePath) {
           lineStart: i + 1,
           lineEnd: i + 1,
           body: line.trim(),
-          docstring: ""
+          docstring: precedingDocComment(lines2, i + 1, style),
+          parent: ""
         });
         break;
       }
@@ -23101,17 +23247,17 @@ function parseContent(content, filePath, language) {
         if (language === "python") {
           symbols = extractPythonSymbols(root, filePath);
         } else if (language === "go") {
-          symbols = extractGoSymbols(root, filePath);
+          symbols = extractGoSymbols(root, filePath, content.split(/\r?\n/));
         } else if (language === "rust") {
-          symbols = extractRustSymbols(root, filePath);
+          symbols = extractRustSymbols(root, filePath, content.split(/\r?\n/));
         } else if (language === "ruby") {
-          symbols = extractRubySymbols(root, filePath);
+          symbols = extractRubySymbols(root, filePath, content.split(/\r?\n/));
         } else if (language === "java") {
-          symbols = extractJavaSymbols(root, filePath);
+          symbols = extractJavaSymbols(root, filePath, content.split(/\r?\n/));
         } else if (language === "cpp" || language === "c") {
-          symbols = extractCppSymbols(root, filePath);
+          symbols = extractCppSymbols(root, filePath, content.split(/\r?\n/));
         } else {
-          symbols = extractTsJsSymbols(root, filePath);
+          symbols = extractTsJsSymbols(root, filePath, content.split(/\r?\n/));
         }
         const refs = REF_LANGUAGES.has(language) ? extractRefs(root, filePath, language) : [];
         const parsed = { symbols, refs };
@@ -23130,7 +23276,8 @@ function sectionsToHeadingSymbols(sections, filePath) {
     lineStart: s.line,
     lineEnd: s.endLine,
     body: "",
-    docstring: ""
+    docstring: "",
+    parent: ""
   }));
 }
 function extractNoTreeSitter(content, filePath, language) {
@@ -23166,6 +23313,7 @@ function isUnderSkipDir(filePath, skipDirs) {
 }
 function isParseSkipEligible(filePath, cfg) {
   if (isUnderSkipDir(filePath, cfg.skip_dirs)) return true;
+  if (cfg.skip_files.includes(path31.basename(filePath))) return true;
   try {
     const stat2 = fs26.statSync(filePath);
     if (stat2.size > cfg.large_file_skip_kb * 1024) return true;
@@ -23184,11 +23332,20 @@ function writeParseResult(filePath, content, result, dbPath) {
       "INSERT INTO files (path, sha, mtime, language, indexed_at) VALUES (?, ?, ?, ?, ?)"
     ).run(filePath, sha, mtime, result.language, now);
     const insSym = db.prepare(
-      "INSERT INTO symbols (file_path, name, kind, line_start, line_end, body, docstring) VALUES (?, ?, ?, ?, ?, ?, ?)"
+      "INSERT INTO symbols (file_path, name, kind, line_start, line_end, body, docstring, parent) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
     );
     for (const s of result.symbols) {
       if (s.name === "" || s.kind === "") continue;
-      insSym.run(s.filePath, s.name, s.kind, s.lineStart, s.lineEnd, boundSymbolBody(s.body), boundSymbolDocstring(s.docstring));
+      insSym.run(
+        s.filePath,
+        s.name,
+        s.kind,
+        s.lineStart,
+        s.lineEnd,
+        boundSymbolBody(s.body),
+        boundSymbolDocstring(s.docstring),
+        s.parent
+      );
     }
     const insRef = db.prepare(
       "INSERT INTO refs (file_path, name, line, col, context) VALUES (?, ?, ?, ?, ?)"
@@ -23347,6 +23504,7 @@ var init_parser = __esm({
     init_sql_path();
     init_markdown_lines();
     init_parser_types();
+    init_doc_comment();
     init_index_reader();
     init_markdown_hints();
     init_csharp();
@@ -23376,6 +23534,7 @@ var init_parser = __esm({
     init_sfc_idx();
     init_ipynb_idx();
     init_util2();
+    init_doc_comment();
     _require4 = createRequire5(import.meta.url);
     _grammarCache = /* @__PURE__ */ new Map();
     CPP_HEADER_SNIFF_RE = /\bclass\s+\w|\bnamespace\s+\w|\btemplate\s*<|::\s*\w|\b(?:public|private|protected)\s*:/;
@@ -23818,28 +23977,31 @@ var init_parser = __esm({
     EMPTY_STRING_SET = /* @__PURE__ */ new Set();
     FALLBACK_PATTERNS = [
       // Python
-      { re: /^[ \t]*(?:async\s+)?def\s+([A-Za-z_]\w*)/, kind: "function" },
-      { re: /^[ \t]*class\s+([A-Za-z_]\w*)/, kind: "class" },
+      { re: /^[ \t]*(?:async\s+)?def\s+([A-Za-z_]\w*)/, kind: "function", style: "hash" },
+      { re: /^[ \t]*class\s+([A-Za-z_]\w*)/, kind: "class", style: "hash" },
       // TS/JS function & class declarations (optionally exported/async)
       {
         re: /^[ \t]*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/,
-        kind: "function"
+        kind: "function",
+        style: "c"
       },
       {
         re: /^[ \t]*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/,
-        kind: "class"
+        kind: "class",
+        style: "c"
       },
-      { re: /^[ \t]*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/, kind: "interface" },
-      { re: /^[ \t]*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*=/, kind: "type" },
+      { re: /^[ \t]*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/, kind: "interface", style: "c" },
+      { re: /^[ \t]*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*=/, kind: "type", style: "c" },
       // const/let/var bound to an arrow or function expression
       {
         re: /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/,
-        kind: "function"
+        kind: "function",
+        style: "c"
       },
       // Rust / Go function & struct/type patterns
-      { re: /^[ \t]*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)/, kind: "function" },
-      { re: /^[ \t]*(?:pub\s+)?struct\s+([A-Za-z_]\w*)/, kind: "struct" },
-      { re: /^[ \t]*func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)/, kind: "function" }
+      { re: /^[ \t]*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)/, kind: "function", style: "c" },
+      { re: /^[ \t]*(?:pub\s+)?struct\s+([A-Za-z_]\w*)/, kind: "struct", style: "c" },
+      { re: /^[ \t]*func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)/, kind: "function", style: "c" }
     ];
     NO_TREE_SITTER_EXTRACTORS = {
       markdown: extractMarkdownSymbols,
@@ -30020,6 +30182,8 @@ function findParentName(entry, fileSymbols) {
     }
   }
   if (best !== null) return best.name;
+  const parent = (entry.parent ?? "").trim();
+  if (parent !== "") return parent;
   const doc = entry.docstring.trim();
   if (doc !== "" && PARENT_IDENTIFIER_RE.test(doc)) return doc;
   return null;
@@ -30096,7 +30260,9 @@ function resolveSymbolSpec(spec, forceRefresh, projectRoot) {
     });
     const symBaseLower = symBase.toLowerCase();
     const scoped = candidates.filter((c) => {
-      if (c.docstring.toLowerCase() === symBaseLower) return true;
+      const cParent = c.parent ?? "";
+      if (cParent.toLowerCase() === symBaseLower) return true;
+      if (cParent === "" && c.docstring.toLowerCase() === symBaseLower) return true;
       return containers.some(
         (cls) => cls.filePath === c.filePath && c.lineStart >= cls.lineStart && c.lineEnd <= cls.lineEnd
       );
@@ -30109,6 +30275,10 @@ function runRead(opts) {
   const range2 = parseLineRange(opts.spec);
   if (range2 !== null) return runLineRange(range2, opts);
   const { file: file2, symbol: symbol3 } = parseReadSpec(opts.spec);
+  if (symbol3 !== void 0 && symbol3 !== "" && symbol3.includes(",") && parseColonLineRange(symbol3) === null) {
+    const multiSymbols = symbol3.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    if (multiSymbols.length > 1) return runReadMulti(file2, multiSymbols, opts);
+  }
   if (symbol3 === void 0 || symbol3 === "") {
     const text2 = readFileText(file2);
     if (text2 === null) {
@@ -30136,22 +30306,55 @@ function runRead(opts) {
   }
   const match2 = resolution.entry;
   const fullSourceBytes = sumFileSizes([match2.filePath]);
+  const refCounts = opts.stats === true ? queryRefCounts([match2.name], globalDbPath(), resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })) : void 0;
   if (opts.json === true) {
-    const text2 = JSON.stringify({ ...match2, body: resolveBody(match2) }, null, 2);
-    recordReadStat("read_replacement", fullSourceBytes, text2, opts.spec);
+    const text2 = JSON.stringify(
+      {
+        ...match2,
+        body: resolveBody(match2),
+        ...refCounts !== void 0 ? { refCount: refCounts.get(match2.name) ?? 0 } : {}
+      },
+      null,
+      2
+    );
+    if (opts.suppressStat !== true) recordReadStat("read_replacement", fullSourceBytes, text2, opts.spec);
     return { text: text2, code: 0 };
   }
   const body = resolveBody(match2);
   const bodyLen = match2.lineEnd - match2.lineStart + 1;
+  const statsStr = formatStatsSuffix(refCounts, match2);
   const lines2 = [
-    `# ${bodyLen} lines (~${Math.ceil(body.length / 4)} tok)`,
+    `# ${bodyLen} lines (~${Math.ceil(body.length / 4)} tok)${statsStr}`,
     body
   ];
   const warning = staleWarning(match2.filePath);
   const text = guardText(warning + trimBlankLines(lines2).join("\n"), "symbol");
-  recordReadStat("read_replacement", fullSourceBytes, text, opts.spec);
+  if (opts.suppressStat !== true) recordReadStat("read_replacement", fullSourceBytes, text, opts.spec);
   return { text, code: 0 };
 }
+function runReadMulti(file2, symbols, opts) {
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  for (const sym of symbols) {
+    const sub = runRead({ ...opts, spec: `${file2}::${sym}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    if (opts.json === true) {
+      jsonOut[sym] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${sym}:
+${sub.text}`);
+  }
+  if (anyFound) {
+    const fullSourceBytes = sumFileSizes([resolveIndexPath(file2, opts.projectRoot ?? process.cwd())]);
+    const text2 = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+    recordReadStat("read_replacement", fullSourceBytes, text2, opts.spec);
+    return { text: text2, code: 0 };
+  }
+  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  return { text, code: 1 };
+}
 function runSection(opts) {
   const colonIdx = findSpecSeparator(opts.spec);
   if (colonIdx === -1) {
@@ -30354,6 +30557,13 @@ function noSymbolsMessage(displayPath, resolvedPath) {
   }
   return `No indexed symbols found in '${displayPath}'`;
 }
+function hasRealDocstring(docstring) {
+  const doc = docstring.trim();
+  return doc !== "" && !PARENT_IDENTIFIER_RE.test(doc);
+}
+function formatStatsSuffix(refCounts, sym) {
+  return refCounts !== void 0 ? `  [${refCounts.get(sym.name) ?? 0} refs, ${hasRealDocstring(sym.docstring) ? "documented" : "undocumented"}]` : "";
+}
 function prepareSymbolListing(file2, opts) {
   const resolved = resolveIndexPath(file2, opts.projectRoot ?? process.cwd());
   if (opts.forceRefresh === true) {
@@ -30386,7 +30596,7 @@ function runSkeleton(opts) {
       kind: s.kind,
       lineStart: s.lineStart,
       lineEnd: s.lineEnd,
-      ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: s.docstring.trim().length > 0 } : {}
+      ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: hasRealDocstring(s.docstring) } : {}
     }));
     const capped = guardJsonRows(rows);
     const payload = {
@@ -30402,7 +30612,7 @@ function runSkeleton(opts) {
   const lines2 = [`# Skeleton: ${opts.file}  (${filtered.length} symbols, ${totalLines} lines)`];
   for (const sym of filtered) {
     const lineStr = sym.lineStart.toString().padStart(6);
-    const statsStr = refCounts !== void 0 ? `  [${refCounts.get(sym.name) ?? 0} refs, ${sym.docstring.trim().length > 0 ? "documented" : "undocumented"}]` : "";
+    const statsStr = formatStatsSuffix(refCounts, sym);
     lines2.push(`  ${lineStr}  ${sym.kind.padEnd(10)}  ${sym.name}  ${firstBodyLine(sym.body)}${statsStr}`);
   }
   const text = guardText(staleWarning(resolved) + lines2.join("\n"), "symbol");
@@ -30419,7 +30629,7 @@ function runOutline(opts) {
     const rows = refCounts !== void 0 ? filtered.map((s) => ({
       ...s,
       refCount: refCounts.get(s.name) ?? 0,
-      hasDoc: s.docstring.trim().length > 0
+      hasDoc: hasRealDocstring(s.docstring)
     })) : filtered;
     const capped = guardJsonRows(rows);
     const payload = {
@@ -30436,8 +30646,8 @@ function runOutline(opts) {
     const rangeStr = `${sym.lineStart.toString().padStart(4)}-${sym.lineEnd.toString().padEnd(6)}`;
     const kindStr = sym.kind.padEnd(14);
     const bodyLen = sym.lineEnd - sym.lineStart + 1;
-    const docFirst = sym.docstring ? `  # ${sym.docstring.split("\n")[0] ?? ""}` : "";
-    const statsStr = refCounts !== void 0 ? `  [${refCounts.get(sym.name) ?? 0} refs, ${sym.docstring.trim().length > 0 ? "documented" : "undocumented"}]` : "";
+    const docFirst = hasRealDocstring(sym.docstring) ? `  # ${sym.docstring.split("\n")[0] ?? ""}` : "";
+    const statsStr = formatStatsSuffix(refCounts, sym);
     lines2.push(`  ${rangeStr}  ${kindStr}  ${sym.name}  (${bodyLen}\u2113)${docFirst}${statsStr}`);
   }
   const text = guardText(staleWarning(resolved) + lines2.join("\n"), "symbol");
@@ -47447,21 +47657,23 @@ function createMcpServer() {
   server.registerTool(
     "read",
     {
-      description: "Read one symbol's full body, given a spec of the form file::symbol, or a line range file@N-M / file@N, or a bare file path.",
+      description: "Read one symbol's full body, given a spec of the form file::symbol, or a line range file@N-M / file@N, or a bare file path. Pass a comma-separated spec (file::a,b) to fetch several symbols' bodies from one file in a single call.",
       inputSchema: {
-        spec: external_exports.string().describe("file::symbol, file@N-M, file@N, or a bare file path"),
+        spec: external_exports.string().describe("file::symbol, file@N-M, file@N, a bare file path, or comma-separated file::a,b for a merged multi-symbol view"),
         json: external_exports.boolean().optional().describe("output as JSON"),
         forceRefresh: external_exports.boolean().optional().describe("reparse file from disk before querying (ignore stale index)"),
+        stats: external_exports.boolean().optional().describe("add per-symbol reference count and doc-coverage flag"),
         projectRoot: projectRootField
       }
     },
     (args) => {
-      const { spec, json: json2, forceRefresh, projectRoot } = args;
+      const { spec, json: json2, forceRefresh, stats, projectRoot } = args;
       return toCallToolResult(
         runRead({
           spec,
           ...json2 === true ? { json: true } : {},
           ...forceRefresh === true ? { forceRefresh: true } : {},
+          ...stats === true ? { stats: true } : {},
           ...projectRoot !== void 0 ? { projectRoot } : {}
         })
       );
@@ -49460,7 +49672,7 @@ async function runDoctorAndExit(opts) {
 }
 
 // src/hooks_session_start.ts
-var GENERIC_REMINDER = 'token-goat: prefer surgical reads over Read/Grep on this codebase -- `token-goat symbol <name>`, `token-goat read "file::symbol"`, `token-goat section "file::Heading"`, `token-goat semantic "description"`, `token-goat outline <file>`. Run `token-goat index .` if this project is not indexed yet.';
+var GENERIC_REMINDER = 'token-goat: prefer surgical reads over the Read/Grep tools on this codebase; shell commands like `rg`, `grep`, `fd`, `sed`, `cat`, `find`, and `ls` are just commands, not tool names -- `token-goat symbol <name>`, `token-goat read "file::symbol"`, `token-goat section "file::Heading"`, `token-goat semantic "description"`, `token-goat outline <file>`. Run `token-goat index .` if this project is not indexed yet.';
 function buildReminder(cwd) {
   if (cwd === void 0) return GENERIC_REMINDER;
   let symbolCount;
@@ -49470,7 +49682,7 @@ function buildReminder(cwd) {
     return GENERIC_REMINDER;
   }
   if (symbolCount <= 0) return GENERIC_REMINDER;
-  return `token-goat: this project is indexed (${symbolCount} symbols). Prefer \`symbol <name>\`, \`read "file::symbol"\`, \`section "file::Heading"\`, \`semantic "description"\`, or \`outline <file>\` over a full Read/Grep.`;
+  return `token-goat: this project is indexed (${symbolCount} symbols). Prefer \`symbol <name>\`, \`read "file::symbol"\`, \`section "file::Heading"\`, \`semantic "description"\`, or \`outline <file>\` over a full Read/Grep tool call; shell commands like \`rg\`, \`grep\`, \`fd\`, \`sed\`, \`cat\`, \`find\`, and \`ls\` are still just commands.`;
 }
 function sessionStartHandler(event) {
   try {
@@ -69321,16 +69533,16 @@ function isTempPath(fp) {
   return /^\/tmp\//i.test(norm) || /\/var\/folders\//i.test(norm) || /AppData\/Local\/Temp\//i.test(norm) || norm.startsWith("/c/Users/") && norm.includes("/AppData/Local/Temp/") || isUnderSystemTemp(fp);
 }
 function isOrchestratorStateFile(filePath) {
-  const basename20 = (filePath.includes("/") ? filePath.split("/").at(-1) : filePath.split("\\").at(-1)) ?? filePath;
-  return /^\.improve-state-/.test(basename20);
+  const basename21 = (filePath.includes("/") ? filePath.split("/").at(-1) : filePath.split("\\").at(-1)) ?? filePath;
+  return /^\.improve-state-/.test(basename21);
 }
 function extractCatSourceFile(cmd) {
   const m = /^cat\s+(\S+\.(?:java|py|ts|tsx|js|jsx|go|rb|rs|cpp|cc|cxx|c|h|hpp|kt|swift|cs|php|scala|clj|css|scss|sass|less))\s*$/.exec(cmd);
   return m?.[1] ?? null;
 }
 function classifyFileExtensions(filePath) {
-  const basename20 = (filePath.includes("/") ? filePath.split("/").at(-1) : filePath.split("\\").at(-1)) ?? filePath;
-  const isEnvFile = /^\.env(\.\w+)?$/i.test(basename20);
+  const basename21 = (filePath.includes("/") ? filePath.split("/").at(-1) : filePath.split("\\").at(-1)) ?? filePath;
+  const isEnvFile = /^\.env(\.\w+)?$/i.test(basename21);
   const hasKnownExt = /\.(?:java|py|ts|tsx|js|jsx|go|rb|rs|cpp|cc|cxx|c|h|hpp|kt|swift|cs|php|scala|clj|css|scss|sass|less|md|mdx|rst|txt|json|yaml|yml|toml|xml|conf|cfg|ini|properties|sql|ps1|psm1|env)$/i.test(filePath);
   if (!hasKnownExt && !isEnvFile) return null;
   const isSql = /\.sql$/i.test(filePath);
@@ -71011,8 +71223,8 @@ ${redactSecrets(compressed).text}`
   }
   return passOutput();
 }
-registerHook("pre_tool_use", preMcpHandler);
-registerHook("post_tool_use", postMcpHandler);
+registerHook("pre_tool_use", preMcpHandler, { toolPattern: "^mcp__" });
+registerHook("post_tool_use", postMcpHandler, { toolPattern: "^mcp__" });
 
 // src/hooks_websearch.ts
 init_define_import_meta_env();
@@ -71095,7 +71307,7 @@ function preScreenshotHandler(event) {
     `${toolName} was called with no destination file, so the screenshot would land raw in context (tens of thousands of tokens). Re-issue it with \`${paramName}\` set to an absolute path, then Read the saved file \u2014 the read is automatically compressed by token-goat's image-shrink pipeline.`
   );
 }
-registerHook("pre_tool_use", preScreenshotHandler);
+registerHook("pre_tool_use", preScreenshotHandler, { toolPattern: "^mcp__" });
 
 // src/hooks_browser_image.ts
 init_define_import_meta_env();
@@ -71173,7 +71385,7 @@ async function postBrowserImageHandler(event) {
     return passOutput();
   }
 }
-registerHook("post_tool_use", postBrowserImageHandler);
+registerHook("post_tool_use", postBrowserImageHandler, { toolPattern: "^mcp__" });
 
 // src/hooks_agent_spawn.ts
 init_define_import_meta_env();
@@ -73199,8 +73411,8 @@ function formatTopFiles(ranked) {
   if (ranked.length === 0) return "";
   const lines2 = ["Top files this session:"];
   for (const { path: filePath, count } of ranked) {
-    const basename20 = path49.basename(filePath);
-    lines2.push(`  ${count.toString().padStart(3)}x  ${basename20}  (${filePath})`);
+    const basename21 = path49.basename(filePath);
+    lines2.push(`  ${count.toString().padStart(3)}x  ${basename21}  (${filePath})`);
   }
   return lines2.join("\n");
 }
@@ -81733,9 +81945,16 @@ function buildProgram() {
     )
   );
   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)"
-  ).option("-j, --json", "output as JSON").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").action(
-    (spec, opts) => runExitText(() => runRead({ spec, ...opts.json === true ? { json: true } : {}, ...opts.forceRefresh === true ? { forceRefresh: true } : {} }))
+    "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)"
+  ).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({
+        spec,
+        ...opts.json === true ? { json: true } : {},
+        ...opts.forceRefresh === true ? { forceRefresh: true } : {},
+        ...opts.stats === true ? { stats: true } : {}
+      })
+    )
   );
   program2.command("brief <spec>").description("symbol body + callers + containing doc section in one call (spec: file::symbol)").option("-j, --json", "output as JSON").option("--limit <n>", "max callers to show (default: 20)").action(
     (spec, opts) => runExit(