token-goat 2.9.10 → 2.9.12

package/dist/{token-goat-chunk-YFXFUG3L.mjs → token-goat-chunk-4CK445AW.mjs}

@@ -1,8 +1,32 @@
 import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
-  DEFAULT_QUERY_LIMIT,
   IMPORT_RE,
+  extractAbap,
+  extractAbl,
+  extractAsm,
+  extractBatch,
+  extractCShader,
+  extractCmake,
+  extractCobol,
+  extractErlang,
+  extractFortran,
+  extractGroovy,
+  extractJcl,
+  extractMatlab,
+  extractNatural,
+  extractObjc,
+  extractPascal,
+  extractPerl,
+  extractPli,
+  extractRpg,
+  extractSas,
+  extractSolidity,
+  extractThrift,
+  stripLeadingAttributes
+} from "./token-goat-chunk-6F5TLJC7.mjs";
+import {
+  DEFAULT_QUERY_LIMIT,
   ImageDecodeError,
   MAX_OVER_FETCH,
   MAX_ZIP_INPUT_BYTES,
@@ -11,19 +35,17 @@ import {
   SKIP_DIRS,
   ZipInputTooLargeError,
   ZipOutputTooLargeError,
-  capJsonRows,
   countRefs,
   countSymbols,
   createLazyModuleLoader,
   distinctSymbolKinds,
-  eachUnfencedLine,
   emptyIndexMessage,
   enqueueDirtyPathSafe,
-  estimateTokens,
   extractPdfMeta,
   extractPdfOutline,
   extractPdfText,
   fenceUntrusted,
+  findContainingSection,
   formatCsvProfile,
   formatCsvTable,
   getEmbeddingCoverage,
@@ -35,8 +57,11 @@ import {
   isImagePath,
   isIndexEmptyForProject,
   isOcrEngineAvailable,
+  isPrivateIpv4Octets,
+  isPrivateIpv6Groups,
   isTextHeavy,
-  lineOpenDelimiterAfter,
+  isTreeSitterAvailable,
+  listSections,
   loadBlob,
   locatePdfPages,
   mergeNearbyHits,
@@ -52,36 +77,62 @@ import {
   queryRefs,
   queryRefsByContext,
   querySymbols,
+  readPdfFileWithinBounds,
+  readSection,
   scanAndRecord,
   searchEvidenceSemantically,
   searchSemantic,
   searchSymbolsFts,
   shrinkImage,
   storeBlob,
-  stripLeadingAttributes,
-  stripTomlComment,
-  tomlBracketDelta,
-  trimToBudget,
   unzipBounded,
   urlPolicyDenialReason,
-  walkProject,
-  yamlLineClosesQuote,
-  yamlOpenQuoteAfter
-} from "./token-goat-chunk-PA5UXNOT.mjs";
+  walkProject
+} from "./token-goat-chunk-GM6QZWCF.mjs";
 import {
   Database,
+  FILENAME_LANGUAGE,
+  TREE_SITTER_LANGUAGES,
+  basenameImportsExtension,
+  capJsonRows,
+  colorStdout,
+  detectLanguage,
+  detectLanguageOfFile,
+  estimateTokens,
+  fileIsAbsent,
+  findProject,
+  fingerprintContent,
+  fingerprintFile,
+  getDb,
+  getDisplayRoot,
+  languageLabel,
+  loadConfig,
+  partialRefsReason,
+  recordStat,
+  redactIfDotenv,
+  redactSecrets,
+  resolveProjectRoot,
+  savedTokensFromBytes,
+  shortFingerprint,
+  stripAnsi,
+  trimToBudget,
+  unsupportedLanguageName
+} from "./token-goat-chunk-TOGYS5A7.mjs";
+import {
+  registerReset
+} from "./token-goat-chunk-EEIDFMEM.mjs";
+import {
   PER_FILE_COUNTERFACTUAL_CEILING,
+  UNTRUSTED_FILE_TAG,
   UNTRUSTED_GITHUB_TAG,
-  _detectOpenQuote,
-  _lineClosesQuote,
+  UNTRUSTED_HTML_TAG,
   atomicWriteBytes,
   buildContextWindow,
-  buildLineIndex,
-  colorStdout,
   compileGrepMatcher,
+  compileGuardedRegex,
   countNoun,
   decodeSource,
-  detectLanguage,
+  displaySafeJson,
   displaySafeText,
   ensureNewline,
   escapeRegExp,
@@ -89,370 +140,39 @@ import {
   extractErrorMessage,
   fenceUntrustedContent,
   fenceUntrustedFileContent,
-  fileIsAbsent,
   filtersFilteredToEmptyNotice,
-  findHtmlHeadingMatches,
-  findProject,
-  fingerprintContent,
-  fingerprintFile,
+  foldCaseForContainment,
   foldPath,
-  getDb,
-  getDisplayRoot,
   globalDbPath,
   grepFilteredToEmptyNotice,
+  isAblSource,
   isInsideRoot,
+  isMatlabSource,
+  isObjcHeader,
+  isObjcSource,
+  isPascalSource,
+  isPerlSource,
+  isPrologSource,
   isTestFile,
-  loadConfig,
   normalizePath,
-  offsetToLine,
   pushAll,
-  recordStat,
-  redactIfDotenv,
-  redactSecrets,
   redactUrlQuery,
   renderContextWindow,
   requireNonNegativeStrictInt,
   requirePositiveStrictInt,
   resolveIndexPath,
   resolveOnPath,
-  resolveProjectRoot,
   runGit,
-  savedTokensFromBytes,
-  shortFingerprint,
-  stripAnsi,
   stripBom,
+  supportRequestLine,
   toDisplayPath,
-  unsupportedLanguageName,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-VCEK77ED.mjs";
-import {
-  registerReset
-} from "./token-goat-chunk-EEIDFMEM.mjs";
+} from "./token-goat-chunk-LOCOX2ML.mjs";
 import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";
 
-// src/section_reader.ts
-init_define_import_meta_env();
-import { readFileSync } from "node:fs";
-function parseHeadingSpec(spec, headers) {
-  const m = /^([^#\r\n]+)#(\d+)$/.exec(spec);
-  if (m !== null && m[1] !== void 0 && m[2] !== void 0) {
-    const specLower = spec.trim().toLowerCase();
-    const isLiteralHeading = headers?.some((h) => h.heading.trim().toLowerCase() === specLower) ?? false;
-    if (isLiteralHeading) {
-      return { base: spec.trim(), ordinal: null };
-    }
-    return { base: m[1].trim(), ordinal: Number.parseInt(m[2], 10) };
-  }
-  return { base: spec.trim(), ordinal: null };
-}
-function normalizeHeading(s) {
-  let n = s.replace(/[—–]/g, "-");
-  n = n.replace(/\s*\([^)]+\)\s*$/, "");
-  n = n.replace(/^\d+\.\s+/, "");
-  return n.replace(/\s+/g, " ").trim();
-}
-function normalizeHeadingStrip(s) {
-  let n = s.replace(/\s*[—–].*$/, "");
-  n = n.replace(/\s*\([^)]+\)\s*$/, "");
-  n = n.replace(/^\d+\.\s+/, "");
-  return n.replace(/\s+/g, " ").trim();
-}
-var MIN_WIDEN_WORD_LEN = 3;
-var MARKDOWN_HEADER_RE = /^(#{1,6})\s+([^\r\n]+?)(?:\s+#+)?\s*$/;
-var TABLE_HEADER_RE = /^\s*\[+\s*([^\]]+?)\s*\]+\s*(?:[#;].*)?$/;
-var PYTHON_HEADER_RE = /^(\s*)(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/;
-var KEYVALUE_HEADER_RE = /^([A-Za-z_][\w.-]*)\s*(?:=|:(?!\/\/))/;
-var ENV_KEYVALUE_HEADER_RE = /^(?:export\s+)?([A-Za-z_][\w.-]*)\s*(?:=|:(?!\/\/))/;
-function findMarkdownHeaders(lines) {
-  const headers = [];
-  for (const [i, line] of eachUnfencedLine(lines)) {
-    const m = MARKDOWN_HEADER_RE.exec(line);
-    if (m === null || m[1] === void 0 || m[2] === void 0) continue;
-    headers.push({ heading: m[2].trim(), level: m[1].length, index: i });
-  }
-  return headers;
-}
-function findTableHeaders(lines, isToml) {
-  const headers = [];
-  let openDelim = null;
-  let arrayDepth = 0;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line === void 0) continue;
-    if (openDelim !== null) {
-      const closeIdx = line.indexOf(openDelim);
-      if (closeIdx === -1) continue;
-      const restStart = closeIdx + openDelim.length;
-      const m2 = TABLE_HEADER_RE.exec(line.slice(restStart));
-      if (m2 !== null && m2[1] !== void 0) headers.push({ heading: m2[1].trim(), level: 1, index: i });
-      openDelim = lineOpenDelimiterAfter(stripTomlComment(line.slice(restStart)), 0);
-      continue;
-    }
-    if (isToml && arrayDepth > 0) {
-      arrayDepth = Math.max(0, arrayDepth + tomlBracketDelta(stripTomlComment(line)));
-      continue;
-    }
-    const m = TABLE_HEADER_RE.exec(line);
-    if (m !== null && m[1] !== void 0) headers.push({ heading: m[1].trim(), level: 1, index: i });
-    if (isToml) {
-      const code = stripTomlComment(line);
-      openDelim = lineOpenDelimiterAfter(code, 0);
-      if (openDelim === null) arrayDepth = Math.max(0, tomlBracketDelta(code));
-    }
-  }
-  return headers;
-}
-function findPythonHeaders(lines) {
-  const headers = [];
-  const indentStack = [];
-  let openDelim = null;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line === void 0) continue;
-    if (openDelim !== null) {
-      const closeIdx = line.indexOf(openDelim);
-      if (closeIdx === -1) continue;
-      openDelim = lineOpenDelimiterAfter(line, closeIdx + openDelim.length);
-      continue;
-    }
-    const m = PYTHON_HEADER_RE.exec(line);
-    if (m === null || m[1] === void 0 || m[2] === void 0) {
-      openDelim = lineOpenDelimiterAfter(line, 0);
-      continue;
-    }
-    const indent = m[1].replace(/\t/g, "    ").length;
-    while (indentStack.length > 0 && indent <= (indentStack[indentStack.length - 1] ?? -1)) {
-      indentStack.pop();
-    }
-    const level = indentStack.length + 1;
-    indentStack.push(indent);
-    headers.push({ heading: m[2], level, index: i });
-    openDelim = lineOpenDelimiterAfter(line, 0);
-  }
-  return headers;
-}
-function findKeyValueHeaders(lines, language) {
-  const headers = [];
-  const isEnv = language === "env_file";
-  let openQuote = null;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line === void 0) continue;
-    if (openQuote !== null) {
-      const closed = isEnv ? _lineClosesQuote(line, openQuote) : yamlLineClosesQuote(line, openQuote);
-      if (closed) openQuote = null;
-      continue;
-    }
-    const scanned = isEnv ? line.replace(/^[ \t]+/, "") : line;
-    const m = (isEnv ? ENV_KEYVALUE_HEADER_RE : KEYVALUE_HEADER_RE).exec(scanned);
-    if (m === null || m[1] === void 0) continue;
-    headers.push({ heading: m[1], level: 1, index: i });
-    openQuote = isEnv ? _detectOpenQuote(scanned.slice(m[0].length)) : yamlOpenQuoteAfter(line, m[0].length);
-  }
-  return headers;
-}
-function findHtmlHeaders(text) {
-  const lineIndex = buildLineIndex(text);
-  const headers = [];
-  for (const hm of findHtmlHeadingMatches(text)) {
-    if (!hm.heading) continue;
-    const index = offsetToLine(lineIndex, hm.offset) - 1;
-    headers.push({ heading: hm.heading, level: hm.level, index });
-  }
-  return headers;
-}
-function findHeaders(text, language) {
-  const lines = text.split("\n");
-  if (language === "markdown") return { headers: findMarkdownHeaders(lines), kind: "markdown" };
-  if (language === "html" || language === "liquid") return { headers: findHtmlHeaders(text), kind: "markdown" };
-  if (language === "toml") return { headers: findTableHeaders(lines, true), kind: "table-toml" };
-  if (language === "python") return { headers: findPythonHeaders(lines), kind: "python" };
-  if (language === "ini") return { headers: findTableHeaders(lines, false), kind: "table-flat" };
-  if (language === "yaml" || language === "env_file")
-    return { headers: findKeyValueHeaders(lines, language), kind: "keyvalue" };
-  const md = findMarkdownHeaders(lines);
-  if (md.length > 0) return { headers: md, kind: "markdown" };
-  const tbl = findTableHeaders(lines, false);
-  if (tbl.length > 0) return { headers: tbl, kind: "table-toml" };
-  return { headers: findKeyValueHeaders(lines, language), kind: "keyvalue" };
-}
-function sectionEndIndex(headers, headerPos, totalLines) {
-  const current = headers[headerPos];
-  if (current === void 0) return totalLines;
-  for (let j = headerPos + 1; j < headers.length; j++) {
-    const next = headers[j];
-    if (next === void 0) continue;
-    if (next.level <= current.level) return next.index;
-  }
-  return totalLines;
-}
-function tableSectionEndIndex(headers, headerPos, totalLines) {
-  const current = headers[headerPos];
-  if (current === void 0) return totalLines;
-  const prefix = current.heading + ".";
-  for (let j = headerPos + 1; j < headers.length; j++) {
-    const next = headers[j];
-    if (next === void 0) continue;
-    if (next.heading.startsWith(prefix)) continue;
-    return next.index;
-  }
-  return totalLines;
-}
-function resolveHeaderPos(headers, base, ordinal) {
-  const target = base.toLowerCase();
-  const normalizedTarget = normalizeHeading(base).toLowerCase();
-  const strippedTarget = normalizeHeadingStrip(base).toLowerCase();
-  const exactMatches = [];
-  const normalizedMatches = [];
-  const strippedMatches = [];
-  for (let i = 0; i < headers.length; i++) {
-    const h = headers[i];
-    if (h === void 0) continue;
-    const headingLower = h.heading.toLowerCase();
-    if (headingLower === target) {
-      exactMatches.push(i);
-    } else if (normalizeHeading(h.heading).toLowerCase() === normalizedTarget) {
-      normalizedMatches.push(i);
-    } else if (normalizeHeadingStrip(h.heading).toLowerCase() === strippedTarget) {
-      strippedMatches.push(i);
-    }
-  }
-  const matches = exactMatches.length > 0 ? exactMatches : normalizedMatches.length > 0 ? normalizedMatches : strippedMatches;
-  if (matches.length > 0) {
-    const pick2 = ordinal === null ? 0 : ordinal - 1;
-    const headerPos = matches[pick2];
-    if (headerPos === void 0) return null;
-    let occurrences = null;
-    if (ordinal === null && matches.length > 1) {
-      occurrences = [];
-      for (const i of matches) {
-        const h = headers[i];
-        if (h !== void 0) occurrences.push(h.index + 1);
-      }
-    }
-    return { headerPos, redirectedFrom: null, occurrences };
-  }
-  if (ordinal !== null || normalizedTarget.length === 0) return null;
-  let prefixPos = -1;
-  const distinct = /* @__PURE__ */ new Set();
-  for (let i = 0; i < headers.length; i++) {
-    const h = headers[i];
-    if (h === void 0) continue;
-    const norm = normalizeHeading(h.heading).toLowerCase();
-    if (norm.startsWith(normalizedTarget)) {
-      distinct.add(norm);
-      if (prefixPos === -1) prefixPos = i;
-    }
-  }
-  if (distinct.size === 1 && prefixPos !== -1) {
-    const chosen = headers[prefixPos];
-    if (chosen === void 0) return null;
-    return { headerPos: prefixPos, redirectedFrom: base, occurrences: null };
-  }
-  const queryWords = normalizedTarget.split(/\s+/).filter((w) => w.length >= MIN_WIDEN_WORD_LEN);
-  if (queryWords.length === 0) return null;
-  const widenedMatches = [];
-  for (let i = 0; i < headers.length; i++) {
-    const h = headers[i];
-    if (h === void 0) continue;
-    const headingWords = normalizeHeading(h.heading).toLowerCase().split(/\s+/);
-    const allWordsMatch = queryWords.every((qw) => headingWords.some((hw) => hw.includes(qw)));
-    if (allWordsMatch) widenedMatches.push(i);
-  }
-  if (widenedMatches.length !== 1) return null;
-  const widenedPos = widenedMatches[0];
-  if (widenedPos === void 0) return null;
-  return { headerPos: widenedPos, redirectedFrom: base, occurrences: null };
-}
-function buildSectionResult(headers, kind, lines, headerPos, redirectedFrom) {
-  const header = headers[headerPos];
-  if (header === void 0) return null;
-  const endIndex = kind === "table-toml" ? tableSectionEndIndex(headers, headerPos, lines.length) : sectionEndIndex(headers, headerPos, lines.length);
-  let endExclusive = endIndex;
-  while (endExclusive > header.index + 1 && (lines[endExclusive - 1] === "" || lines[endExclusive - 1] === "\r")) {
-    endExclusive--;
-  }
-  const content = lines.slice(header.index, endExclusive).join("\n");
-  const result = {
-    heading: header.heading,
-    content,
-    lineStart: header.index + 1,
-    lineEnd: endExclusive
-  };
-  return redirectedFrom === null ? result : { ...result, redirectedFrom };
-}
-function resolveSectionFromText(text, headingSpec, language) {
-  const { headers, kind } = findHeaders(text, language);
-  const { base, ordinal } = parseHeadingSpec(headingSpec, headers);
-  if (base.length === 0) return null;
-  const lines = text.split("\n");
-  const resolved = resolveHeaderPos(headers, base, ordinal);
-  if (resolved === null) return null;
-  const built = buildSectionResult(headers, kind, lines, resolved.headerPos, resolved.redirectedFrom);
-  if (built === null || resolved.occurrences === null) return built;
-  return { ...built, occurrences: resolved.occurrences };
-}
-function extractSection(text, headingSpec) {
-  return resolveSectionFromText(text, headingSpec, "unknown");
-}
-function readTextForSections(filePath, readFn) {
-  let text;
-  if (readFn !== void 0) {
-    const read = readFn(filePath);
-    if (read === null) return null;
-    text = read;
-  } else {
-    try {
-      text = decodeSource(readFileSync(filePath));
-    } catch {
-      return null;
-    }
-  }
-  if (text.charCodeAt(0) === 65279) {
-    text = text.slice(1);
-  }
-  return redactIfDotenv(filePath, text);
-}
-function readSection(filePath, headingSpec, readFn) {
-  const text = readTextForSections(filePath, readFn);
-  if (text === null) return null;
-  return resolveSectionFromText(text, headingSpec, detectLanguage(filePath));
-}
-function findContainingSection(filePath, lineStart, lineEnd, readFn) {
-  const text = readTextForSections(filePath, readFn);
-  if (text === null) return null;
-  const language = detectLanguage(filePath);
-  const { headers, kind } = findHeaders(text, language);
-  if (headers.length === 0) return null;
-  const lines = text.split("\n");
-  let bestPos = -1;
-  let bestHeaderLine = -1;
-  for (let i = 0; i < headers.length; i++) {
-    const header = headers[i];
-    if (header === void 0) continue;
-    const endIndex = kind === "table-toml" ? tableSectionEndIndex(headers, i, lines.length) : sectionEndIndex(headers, i, lines.length);
-    const sectionLineStart = header.index + 1;
-    if (sectionLineStart <= lineStart && lineEnd <= endIndex) {
-      if (header.index > bestHeaderLine) {
-        bestHeaderLine = header.index;
-        bestPos = i;
-      }
-    }
-  }
-  if (bestPos === -1) return null;
-  return buildSectionResult(headers, kind, lines, bestPos, null);
-}
-function listSections(filePath, readFn) {
-  const text = readTextForSections(filePath, readFn);
-  if (text === null) return [];
-  const language = detectLanguage(filePath);
-  const { headers } = findHeaders(text, language);
-  return headers.map((h) => h.heading);
-}
-
 // src/graph_commands.ts
 init_define_import_meta_env();
 import * as fs6 from "node:fs";
@@ -480,35 +200,15 @@ function isRefIndexedLanguage(language) {
 function isRefIndexedFile(filePath) {
   return isRefIndexedLanguage(detectLanguage(filePath));
 }
-var LANGUAGE_LABELS = /* @__PURE__ */ new Map([
-  ["csharp", "C#"],
-  ["cpp", "C++"],
-  ["c", "C"],
-  ["php", "PHP"],
-  ["powershell", "PowerShell"],
-  ["sql", "SQL"],
-  ["graphql", "GraphQL"],
-  ["proto", "Protocol Buffers"],
-  ["html", "HTML"],
-  ["css", "CSS"],
-  ["toml", "TOML"],
-  ["json", "JSON"],
-  ["yaml", "YAML"],
-  ["ini", "INI"],
-  ["env_file", "env file"],
-  ["ipynb", "Jupyter notebook"],
-  ["salesforce_metadata", "Salesforce metadata"],
-  ["salesforce_markup", "Salesforce markup"],
-  ["unknown", "this file type"]
-]);
-function languageLabel(language) {
-  return LANGUAGE_LABELS.get(language) ?? language;
-}
 function refBlindLanguageNotice(symbolName, language, displayPath) {
+  const partial = partialRefsReason(language);
+  if (partial !== void 0) {
+    return `No recorded references to '${symbolName}' (${displayPath}). ${partial}, so an empty result is not evidence the name is unused. Search the source directly as well, e.g. \`rg -n -w ${symbolName}\`.`;
+  }
   return `Cannot determine references for '${symbolName}': ${languageLabel(language)} call sites are not indexed (${displayPath}). This is a gap in token-goat's index, not evidence the symbol is unreferenced. Search the source directly instead, e.g. \`rg -n -w ${symbolName}\`.`;
 }
 var REF_BLIND_KIND_REASON = "the index records value-position references only (calls, `new`, macro invocations), never type annotations, so a type declaration has no ref rows however widely it is used";
-var REF_BLIND_DEF_PROBE_LIMIT = 50;
+var REF_BLIND_DEF_PROBE_LIMIT = -1;
 function kindWithArticle(kind) {
   return `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`;
 }
@@ -874,16 +574,16 @@ function outlineXml(xmlText, opts = {}) {
 function formatXmlOutline(summary) {
   const lines = [];
   lines.push(
-    `Root element: <${summary.rootTag}> (${summary.totalElements} total elements, ${summary.uniqueTags.length} unique tags, max depth ${summary.maxDepth})`
+    `Root element: <${displaySafeText(summary.rootTag)}> (${summary.totalElements} total elements, ${summary.uniqueTags.length} unique tags, max depth ${summary.maxDepth})`
   );
   if (summary.doctype) {
-    lines.push(`DOCTYPE: ${summary.doctype}`);
+    lines.push(`DOCTYPE: ${displaySafeText(summary.doctype)}`);
   }
   const nsKeys = Object.keys(summary.namespaces);
   if (nsKeys.length > 0) {
     lines.push("Namespaces:");
     for (const [k, v] of Object.entries(summary.namespaces)) {
-      lines.push(`  ${k}: ${v}`);
+      lines.push(`  ${displaySafeText(k)}: ${displaySafeText(v)}`);
     }
   }
   lines.push("");
@@ -895,12 +595,12 @@ function formatXmlOutline(summary) {
     for (const [k, v] of Object.entries(node.attributes)) {
       if (["id", "name", "type", "key", "class", "code", "status", "value"].includes(k.toLowerCase()) || attrKeys.length <= 3) {
         const valPreview = v.length > 35 ? `${v.slice(0, 32)}...` : v;
-        attrParts.push(`${k}="${valPreview}"`);
+        attrParts.push(`${displaySafeText(k)}="${displaySafeText(valPreview)}"`);
       }
     }
     const attrStr = attrParts.length > 0 ? ` [${attrParts.join(" ")}]` : "";
     const countStr = node.childCount > 0 ? ` (${node.childCount} children)` : node.textLength > 0 ? ` (~${node.textLength} chars text)` : " (empty)";
-    lines.push(`${pad}<${node.tag}>${attrStr}${countStr}`);
+    lines.push(`${pad}<${displaySafeText(node.tag)}>${attrStr}${countStr}`);
     for (const child of node.children) {
       renderNode(child, indent + 1);
     }
@@ -1137,6 +837,693 @@ function queryXml(xmlText, pathStr) {
   return { items: currentCandidates, fanned: hasFanned || currentCandidates.length > 1 };
 }
 
+// src/html_query.ts
+init_define_import_meta_env();
+var HTML_VOID_TAGS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+var RAW_TEXT_TAGS = /* @__PURE__ */ new Set(["script", "style"]);
+function findTagEnd(html, startPos) {
+  let inQuote = null;
+  for (let i = startPos + 1; i < html.length; i++) {
+    const ch = html[i];
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+    } else {
+      if (ch === '"' || ch === "'") {
+        inQuote = ch;
+      } else if (ch === ">") {
+        return i;
+      } else if (ch === "<") {
+        return -1;
+      }
+    }
+  }
+  return -1;
+}
+function findRawTextEnd(html, startPos, tag) {
+  const target = `</${tag}`;
+  const targetLen = target.length;
+  const limit = html.length - targetLen;
+  for (let i = startPos; i <= limit; i++) {
+    if (html[i] === "<" && html[i + 1] === "/") {
+      if (html.slice(i, i + targetLen).toLowerCase() === target) {
+        const nextChar = html[i + targetLen];
+        if (!nextChar || /\s|>|\//.test(nextChar)) {
+          return i;
+        }
+      }
+    }
+  }
+  return html.length;
+}
+function parseHtml(html) {
+  const issues = [];
+  const tagCounts = {};
+  const root = {
+    tag: "#root",
+    attributes: {},
+    children: [],
+    parent: null,
+    text: "",
+    rawHtml: "",
+    startOffset: 0,
+    endOffset: html.length,
+    line: 1,
+    endLine: 1,
+    isVoid: false
+  };
+  let currentParent = root;
+  let currentLine = 1;
+  let pos = 0;
+  const len = html.length;
+  const seenIds = /* @__PURE__ */ new Map();
+  while (pos < len) {
+    if (html[pos] === "\n") {
+      currentLine++;
+      pos++;
+      continue;
+    }
+    if (html.startsWith("<!--", pos)) {
+      const endComment = html.indexOf("-->", pos + 4);
+      const commentEndPos = endComment !== -1 ? endComment + 3 : len;
+      const commentLines = (html.slice(pos, commentEndPos).match(/\n/g) || []).length;
+      currentLine += commentLines;
+      pos = commentEndPos;
+      continue;
+    }
+    if (html.startsWith("<!doctype", pos) || html.startsWith("<!DOCTYPE", pos)) {
+      const endDoc = html.indexOf(">", pos);
+      const docEndPos = endDoc !== -1 ? endDoc + 1 : len;
+      const docLines = (html.slice(pos, docEndPos).match(/\n/g) || []).length;
+      currentLine += docLines;
+      pos = docEndPos;
+      continue;
+    }
+    if (currentParent && RAW_TEXT_TAGS.has(currentParent.tag.toLowerCase())) {
+      const closeTag = `</${currentParent.tag}`;
+      if (!html.slice(pos, pos + closeTag.length).toLowerCase().startsWith(closeTag.toLowerCase())) {
+        const rawTextEnd = findRawTextEnd(html, pos, currentParent.tag.toLowerCase());
+        const textContent = html.slice(pos, rawTextEnd);
+        currentParent.text += textContent;
+        const textLines = (textContent.match(/\n/g) || []).length;
+        currentLine += textLines;
+        pos = rawTextEnd;
+        continue;
+      }
+    }
+    if (html[pos] === "<") {
+      const tagStartLine = currentLine;
+      const closeBracket = findTagEnd(html, pos);
+      if (closeBracket === -1) {
+        issues.push({
+          line: tagStartLine,
+          type: "warning",
+          message: "Unescaped '<' character in text: consider '&lt;'",
+          rule: "unescaped-angle-bracket"
+        });
+        if (currentParent) {
+          currentParent.text += "<";
+        }
+        pos++;
+        continue;
+      }
+      const tagSlice = html.slice(pos, closeBracket + 1);
+      const sliceLines = (tagSlice.match(/\n/g) || []).length;
+      if (html[pos + 1] === "/") {
+        const closeMatch = /^<\/([a-zA-Z][a-zA-Z0-9_-]*)\s*>$/i.exec(tagSlice.trim());
+        if (closeMatch) {
+          const closeTag = closeMatch[1].toLowerCase();
+          if (!tagCounts[closeTag]) tagCounts[closeTag] = { open: 0, close: 0, diff: 0 };
+          if (!HTML_VOID_TAGS.has(closeTag)) {
+            tagCounts[closeTag].close++;
+          }
+          if (HTML_VOID_TAGS.has(closeTag)) {
+            issues.push({
+              line: tagStartLine,
+              type: "warning",
+              message: `Void tag <${closeTag}> should not have a closing tag </${closeTag}>`,
+              rule: "void-tag-closing"
+            });
+          } else {
+            let matchNode = currentParent;
+            while (matchNode && matchNode.tag !== "#root" && matchNode.tag.toLowerCase() !== closeTag) {
+              matchNode = matchNode.parent;
+            }
+            if (matchNode && matchNode.tag !== "#root") {
+              let unclosed = currentParent;
+              while (unclosed && unclosed !== matchNode) {
+                if (!HTML_VOID_TAGS.has(unclosed.tag.toLowerCase())) {
+                  issues.push({
+                    line: unclosed.line,
+                    type: "error",
+                    message: `Unclosed tag <${unclosed.tag}> before closing </${closeTag}> on line ${tagStartLine}`,
+                    rule: "unclosed-tag"
+                  });
+                }
+                unclosed.endLine = tagStartLine;
+                unclosed.endOffset = pos;
+                unclosed = unclosed.parent;
+              }
+              matchNode.endLine = tagStartLine + sliceLines;
+              matchNode.endOffset = closeBracket + 1;
+              currentParent = matchNode.parent || root;
+            } else {
+              issues.push({
+                line: tagStartLine,
+                type: "error",
+                message: `Unexpected closing tag </${closeTag}> with no matching opening tag`,
+                rule: "stray-closing-tag"
+              });
+            }
+          }
+        } else {
+          issues.push({ line: tagStartLine, type: "error", message: `Malformed closing tag: ${tagSlice}`, rule: "syntax" });
+        }
+        currentLine += sliceLines;
+        pos = closeBracket + 1;
+        continue;
+      }
+      let inner = tagSlice.slice(1, -1).trim();
+      let selfClosing = false;
+      if (inner.endsWith("/")) {
+        selfClosing = true;
+        inner = inner.slice(0, -1).trim();
+      }
+      const spaceIdx = inner.search(/\s/);
+      const rawTagName = spaceIdx === -1 ? inner : inner.slice(0, spaceIdx);
+      const attrStr = spaceIdx === -1 ? "" : inner.slice(spaceIdx + 1);
+      if (/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(rawTagName)) {
+        const tagName = rawTagName.toLowerCase();
+        const isVoid = HTML_VOID_TAGS.has(tagName) || selfClosing;
+        if (!tagCounts[tagName]) tagCounts[tagName] = { open: 0, close: 0, diff: 0 };
+        tagCounts[tagName].open++;
+        if (isVoid) {
+          tagCounts[tagName].close++;
+        }
+        const attributes = {};
+        const attrRegex = /([a-zA-Z0-9_:-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+        let attrMatch;
+        while ((attrMatch = attrRegex.exec(attrStr)) !== null) {
+          const attrName = attrMatch[1].toLowerCase();
+          const attrVal = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4] ?? "";
+          attributes[attrName] = attrVal;
+          if (attrName === "id" && attrVal) {
+            const prevLine = seenIds.get(attrVal);
+            if (prevLine !== void 0) {
+              issues.push({
+                line: tagStartLine,
+                type: "error",
+                message: `Duplicate ID '#${attrVal}' previously defined on line ${prevLine}`,
+                rule: "duplicate-id"
+              });
+            } else {
+              seenIds.set(attrVal, tagStartLine);
+            }
+          }
+        }
+        const newNode = {
+          tag: tagName,
+          attributes,
+          children: [],
+          parent: currentParent,
+          text: "",
+          rawHtml: tagSlice,
+          startOffset: pos,
+          endOffset: closeBracket + 1,
+          line: tagStartLine,
+          endLine: tagStartLine + sliceLines,
+          isVoid
+        };
+        currentParent.children.push(newNode);
+        if (!isVoid) {
+          currentParent = newNode;
+        }
+        currentLine += sliceLines;
+        pos = closeBracket + 1;
+        continue;
+      }
+      issues.push({
+        line: tagStartLine,
+        type: "warning",
+        message: "Unescaped '<' character in text: consider '&lt;'",
+        rule: "unescaped-angle-bracket"
+      });
+      if (currentParent) {
+        currentParent.text += "<";
+      }
+      pos++;
+      continue;
+    }
+    const nextBracket = html.indexOf("<", pos);
+    const textChunkEnd = nextBracket !== -1 ? nextBracket : len;
+    const textChunk = html.slice(pos, textChunkEnd);
+    if (textChunk) {
+      if (currentParent) {
+        currentParent.text += textChunk;
+      }
+      currentLine += (textChunk.match(/\n/g) || []).length;
+    }
+    pos = textChunkEnd;
+  }
+  let dangling = currentParent;
+  while (dangling && dangling.tag !== "#root") {
+    if (!HTML_VOID_TAGS.has(dangling.tag.toLowerCase())) {
+      issues.push({
+        line: dangling.line,
+        type: "error",
+        message: `Unclosed tag <${dangling.tag}> at end of document`,
+        rule: "unclosed-tag"
+      });
+    }
+    dangling.endOffset = len;
+    dangling = dangling.parent;
+  }
+  for (const tag of Object.keys(tagCounts)) {
+    const entry = tagCounts[tag];
+    entry.diff = entry.open - entry.close;
+  }
+  root.endLine = currentLine;
+  return { root, issues, tagCounts };
+}
+function lintHtml(htmlText) {
+  const { issues, tagCounts } = parseHtml(htmlText);
+  const errors = issues.filter((i) => i.type === "error");
+  const warnings = issues.filter((i) => i.type === "warning");
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    tagCounts
+  };
+}
+function outlineHtml(htmlText) {
+  const { root } = parseHtml(htmlText);
+  let title = null;
+  let doctype = null;
+  const docMatch = /<!doctype\s+(\S[^>]*)>/i.exec(htmlText);
+  if (docMatch) doctype = docMatch[1].trim();
+  let totalElements = 0;
+  const uniqueTags = /* @__PURE__ */ new Set();
+  let maxDepth = 0;
+  const headings = [];
+  const landmarks = [];
+  const tables = [];
+  const forms = [];
+  let scripts = 0;
+  let styles = 0;
+  const landmarkTags = /* @__PURE__ */ new Set(["header", "nav", "main", "article", "section", "footer", "aside"]);
+  function walk(node, depth) {
+    if (node.tag !== "#root") {
+      totalElements++;
+      uniqueTags.add(node.tag);
+      if (depth > maxDepth) maxDepth = depth;
+      const tag = node.tag.toLowerCase();
+      if (tag === "title" && !title) {
+        title = node.text.trim();
+      } else if (/^h[1-6]$/.test(tag)) {
+        const level = parseInt(tag[1], 10);
+        headings.push({ level, text: node.text.replace(/\s+/g, " ").trim().slice(0, 80), line: node.line });
+      } else if (landmarkTags.has(tag)) {
+        landmarks.push({
+          tag,
+          id: node.attributes["id"],
+          class: node.attributes["class"],
+          line: node.line
+        });
+      } else if (tag === "table") {
+        const rows = node.children.flatMap((c) => c.tag === "tbody" || c.tag === "thead" ? c.children : [c]).filter((c) => c.tag === "tr").length;
+        tables.push({ id: node.attributes["id"], class: node.attributes["class"], rows, line: node.line });
+      } else if (tag === "form") {
+        forms.push({ id: node.attributes["id"], action: node.attributes["action"], method: node.attributes["method"], line: node.line });
+      } else if (tag === "script") {
+        scripts++;
+      } else if (tag === "style") {
+        styles++;
+      }
+    }
+    for (const child of node.children) {
+      walk(child, depth + 1);
+    }
+  }
+  walk(root, 0);
+  return {
+    title,
+    doctype,
+    totalElements,
+    uniqueTags: Array.from(uniqueTags).sort(),
+    maxDepth,
+    headings,
+    landmarks,
+    tables,
+    forms,
+    scripts,
+    styles
+  };
+}
+function formatHtmlOutline(summary) {
+  const lines = [];
+  lines.push(`HTML Document (${summary.totalElements} elements, ${summary.uniqueTags.length} unique tags, max depth ${summary.maxDepth})`);
+  if (summary.title) lines.push(`Title: "${displaySafeText(summary.title)}"`);
+  if (summary.doctype) lines.push(`DOCTYPE: ${displaySafeText(summary.doctype)}`);
+  lines.push(`Assets: ${summary.scripts} scripts, ${summary.styles} stylesheets`);
+  if (summary.headings.length > 0) {
+    lines.push("", "Headings:");
+    for (const h of summary.headings.slice(0, 30)) {
+      lines.push(`  ${"  ".repeat(h.level - 1)}[h${h.level}] ${displaySafeText(h.text)} (line ${h.line})`);
+    }
+    if (summary.headings.length > 30) {
+      lines.push(`  ... (${summary.headings.length - 30} more headings elided)`);
+    }
+  }
+  if (summary.landmarks.length > 0) {
+    lines.push("", "Landmarks:");
+    for (const l of summary.landmarks.slice(0, 25)) {
+      const idStr = l.id ? `#${displaySafeText(l.id)}` : "";
+      const classStr = l.class ? `.${displaySafeText(l.class.trim().split(/\s+/).join("."))}` : "";
+      lines.push(`  <${displaySafeText(l.tag)}${idStr}${classStr}> (line ${l.line})`);
+    }
+  }
+  if (summary.tables.length > 0) {
+    lines.push("", "Tables:");
+    for (const t of summary.tables) {
+      const idStr = t.id ? `#${displaySafeText(t.id)}` : "";
+      lines.push(`  <table${idStr}> with ~${t.rows} rows (line ${t.line})`);
+    }
+  }
+  if (summary.forms.length > 0) {
+    lines.push("", "Forms:");
+    for (const f of summary.forms) {
+      const idStr = f.id ? `#${displaySafeText(f.id)}` : "";
+      lines.push(`  <form${idStr} method="${displaySafeText(f.method || "GET")}" action="${displaySafeText(f.action || "")}"> (line ${f.line})`);
+    }
+  }
+  return lines.join("\n");
+}
+function splitTopLevel(str, delimiter) {
+  const results = [];
+  let start = 0;
+  let inQuote = null;
+  let bracketDepth = 0;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+    } else {
+      if (ch === '"' || ch === "'") {
+        inQuote = ch;
+      } else if (ch === "[") {
+        bracketDepth++;
+      } else if (ch === "]") {
+        if (bracketDepth > 0) bracketDepth--;
+      } else if (bracketDepth === 0 && ch === delimiter) {
+        results.push(str.slice(start, i));
+        start = i + 1;
+      }
+    }
+  }
+  results.push(str.slice(start));
+  return results;
+}
+function tokenizeSelector(sel) {
+  const tokens = [];
+  let i = 0;
+  const n = sel.length;
+  while (i < n) {
+    while (i < n && /\s/.test(sel[i])) i++;
+    if (i >= n) break;
+    if (sel[i] === ">") {
+      tokens.push(">");
+      i++;
+      continue;
+    }
+    const start = i;
+    let inQuote = null;
+    let bracketDepth = 0;
+    while (i < n) {
+      const ch = sel[i];
+      if (inQuote) {
+        if (ch === inQuote) inQuote = null;
+      } else {
+        if (ch === '"' || ch === "'") {
+          inQuote = ch;
+        } else if (ch === "[") {
+          bracketDepth++;
+        } else if (ch === "]") {
+          if (bracketDepth > 0) bracketDepth--;
+        } else if (bracketDepth === 0) {
+          if (/\s/.test(ch) || ch === ">") {
+            break;
+          }
+        }
+      }
+      i++;
+    }
+    if (i > start) {
+      tokens.push(sel.slice(start, i));
+    }
+  }
+  return tokens;
+}
+function parseCompoundSelector(sel) {
+  const result = {
+    ids: [],
+    classes: [],
+    attributes: []
+  };
+  let i = 0;
+  const n = sel.length;
+  if (sel[0] !== "#" && sel[0] !== "." && sel[0] !== "[") {
+    const tagMatch = /^([a-zA-Z*][a-zA-Z0-9_-]*)/.exec(sel);
+    if (tagMatch) {
+      result.tag = tagMatch[1];
+      i = tagMatch[0].length;
+    }
+  }
+  while (i < n) {
+    const ch = sel[i];
+    if (ch === "#") {
+      i++;
+      const idMatch = /^([a-zA-Z0-9_-]+)/.exec(sel.slice(i));
+      if (idMatch) {
+        result.ids.push(idMatch[1]);
+        i += idMatch[0].length;
+      }
+    } else if (ch === ".") {
+      i++;
+      const classMatch = /^([a-zA-Z0-9_-]+)/.exec(sel.slice(i));
+      if (classMatch) {
+        result.classes.push(classMatch[1]);
+        i += classMatch[0].length;
+      }
+    } else if (ch === "[") {
+      let endBracket = -1;
+      let inQuote = null;
+      for (let j = i + 1; j < n; j++) {
+        const c = sel[j];
+        if (inQuote) {
+          if (c === inQuote) inQuote = null;
+        } else {
+          if (c === '"' || c === "'") inQuote = c;
+          else if (c === "]") {
+            endBracket = j;
+            break;
+          }
+        }
+      }
+      if (endBracket === -1) {
+        break;
+      }
+      const inner = sel.slice(i + 1, endBracket).trim();
+      i = endBracket + 1;
+      const attrMatch = /^([a-zA-Z0-9_:-]+)(?:\s*([*^$!~]?=)\s*(?:"([^"]*)"|'([^']*)'|([^\s"'\]]+)))?$/.exec(inner);
+      if (attrMatch) {
+        const attrName = attrMatch[1].toLowerCase();
+        const op = attrMatch[2];
+        const val = attrMatch[3] ?? attrMatch[4] ?? attrMatch[5];
+        result.attributes.push({ name: attrName, op, val });
+      }
+    } else {
+      i++;
+    }
+  }
+  return result;
+}
+function matchesCompoundSelector(node, sel) {
+  if (!sel || node.tag === "#root") return false;
+  if (sel === "*") return true;
+  const parsed = parseCompoundSelector(sel);
+  if (parsed.tag && parsed.tag !== "*") {
+    if (node.tag.toLowerCase() !== parsed.tag.toLowerCase()) return false;
+  }
+  for (const id of parsed.ids) {
+    if (node.attributes["id"] !== id) return false;
+  }
+  if (parsed.classes.length > 0) {
+    const nodeClasses = (node.attributes["class"] || "").split(/\s+/).filter(Boolean);
+    for (const c of parsed.classes) {
+      if (!nodeClasses.includes(c)) return false;
+    }
+  }
+  for (const attr of parsed.attributes) {
+    const hasAttr = Object.prototype.hasOwnProperty.call(node.attributes, attr.name);
+    if (!hasAttr) {
+      if (attr.op === "!=") continue;
+      return false;
+    }
+    if (!attr.op) continue;
+    const actual = node.attributes[attr.name] || "";
+    const val = attr.val ?? "";
+    if (attr.op === "=") {
+      if (actual !== val) return false;
+    } else if (attr.op === "^=") {
+      if (!actual.startsWith(val)) return false;
+    } else if (attr.op === "$=") {
+      if (!actual.endsWith(val)) return false;
+    } else if (attr.op === "*=") {
+      if (!actual.includes(val)) return false;
+    } else if (attr.op === "~=") {
+      if (!actual.split(/\s+/).includes(val)) return false;
+    } else if (attr.op === "!=") {
+      if (actual === val) return false;
+    }
+  }
+  return true;
+}
+function queryHtml(htmlText, selectorStr) {
+  const { root } = parseHtml(htmlText);
+  let selector = selectorStr.trim();
+  let targetAttr;
+  const attrAtMatch = /@([a-zA-Z0-9_:-]+)$/.exec(selector);
+  if (attrAtMatch) {
+    targetAttr = attrAtMatch[1].toLowerCase();
+    selector = selector.slice(0, selector.length - attrAtMatch[0].length).trim();
+    if (!selector) selector = "*";
+  }
+  const rawSubSelectors = splitTopLevel(selector, ",").map((s) => s.trim()).filter(Boolean);
+  const matchedSet = /* @__PURE__ */ new Set();
+  for (const subSel of rawSubSelectors) {
+    let collectAll2 = function(node) {
+      if (node.tag !== "#root") currentCandidates.push(node);
+      for (const c of node.children) collectAll2(c);
+    };
+    var collectAll = collectAll2;
+    const tokens = tokenizeSelector(subSel);
+    let currentCandidates = [];
+    collectAll2(root);
+    let i = 0;
+    while (i < tokens.length) {
+      const token = tokens[i];
+      if (token === ">") {
+        const nextTarget = tokens[i + 1];
+        if (!nextTarget) break;
+        const nextCandidates = [];
+        for (const parent of currentCandidates) {
+          for (const child of parent.children) {
+            if (nextTarget === "*" || matchesCompoundSelector(child, nextTarget)) {
+              nextCandidates.push(child);
+            }
+          }
+        }
+        currentCandidates = nextCandidates;
+        i += 2;
+      } else {
+        if (i === 0) {
+          currentCandidates = currentCandidates.filter((node) => token === "*" || matchesCompoundSelector(node, token));
+        } else {
+          const nextSet = /* @__PURE__ */ new Set();
+          for (const ancestor of currentCandidates) {
+            let findDescendants2 = function(node) {
+              for (const child of node.children) {
+                if (token === "*" || matchesCompoundSelector(child, token)) {
+                  nextSet.add(child);
+                }
+                findDescendants2(child);
+              }
+            };
+            var findDescendants = findDescendants2;
+            findDescendants2(ancestor);
+          }
+          currentCandidates = Array.from(nextSet);
+        }
+        i++;
+      }
+    }
+    for (const match of currentCandidates) {
+      matchedSet.add(match);
+    }
+  }
+  const elements = Array.from(matchedSet);
+  if (targetAttr !== void 0) {
+    const attributeValues = [];
+    for (const el of elements) {
+      if (Object.prototype.hasOwnProperty.call(el.attributes, targetAttr)) {
+        attributeValues.push(el.attributes[targetAttr]);
+      }
+    }
+    return { elements, attributeValues, fanned: attributeValues.length > 1, sourceHtml: htmlText };
+  }
+  return { elements, fanned: elements.length > 1, sourceHtml: htmlText };
+}
+function extractNodeText(node, sourceHtml) {
+  if (RAW_TEXT_TAGS.has(node.tag.toLowerCase())) return "";
+  if (sourceHtml && node.startOffset !== void 0 && node.endOffset !== void 0) {
+    const raw = sourceHtml.slice(node.startOffset, node.endOffset);
+    const clean = raw.replace(/<!--[\s\S]*?-->/g, "").replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+    return clean.replace(/\s+/g, " ").trim();
+  }
+  const parts = [];
+  if (node.text.trim()) parts.push(node.text.trim());
+  for (const child of node.children) {
+    const t = extractNodeText(child);
+    if (t) parts.push(t);
+  }
+  return parts.join(" ");
+}
+function serializeHtmlNode(node, indent = 0, sourceHtml) {
+  if (node.tag === "#root") {
+    return node.children.map((c) => serializeHtmlNode(c, indent, sourceHtml)).join("\n");
+  }
+  if (sourceHtml && node.startOffset !== void 0 && node.endOffset !== void 0) {
+    return sourceHtml.slice(node.startOffset, node.endOffset);
+  }
+  const pad = "  ".repeat(indent);
+  const attrs = Object.entries(node.attributes).map(([k, v]) => v !== "" ? `${k}="${v.replace(/"/g, "&quot;")}"` : k).join(" ");
+  const attrStr = attrs ? ` ${attrs}` : "";
+  if (node.isVoid) {
+    return `${pad}<${node.tag}${attrStr}>`;
+  }
+  if (node.children.length === 0) {
+    const textTrimmed = node.text.trim();
+    if (!textTrimmed) {
+      return `${pad}<${node.tag}${attrStr}></${node.tag}>`;
+    }
+    if (!textTrimmed.includes("\n") && textTrimmed.length < 80) {
+      return `${pad}<${node.tag}${attrStr}>${textTrimmed}</${node.tag}>`;
+    }
+    return `${pad}<${node.tag}${attrStr}>
+${pad}  ${textTrimmed}
+${pad}</${node.tag}>`;
+  }
+  const inner = node.children.map((c) => serializeHtmlNode(c, indent + 1, sourceHtml)).join("\n");
+  return `${pad}<${node.tag}${attrStr}>
+${inner}
+${pad}</${node.tag}>`;
+}
+
 // node_modules/js-yaml/dist/js-yaml.mjs
 init_define_import_meta_env();
 var NOT_RESOLVED = /* @__PURE__ */ Symbol("NOT_RESOLVED");
@@ -3712,17 +4099,17 @@ function findOperation(operations, key) {
   return operations.find((op) => op.method === method && op.path === opPath);
 }
 function operationLabel(op) {
-  return op.operationId !== void 0 ? `${op.operationId}  (${op.method} ${op.path})` : `${op.method} ${op.path}`;
+  return op.operationId !== void 0 ? `${displaySafeText(op.operationId)}  (${displaySafeText(op.method)} ${displaySafeText(op.path)})` : `${displaySafeText(op.method)} ${displaySafeText(op.path)}`;
 }
 function indentedJson(value, indent) {
   return JSON.stringify(value, null, 2).split("\n").map((line) => indent + line).join("\n");
 }
 function formatOperationDetail(op) {
-  const lines = [`${op.method} ${op.path}`];
-  if (op.operationId !== void 0) lines.push(`operationId: ${op.operationId}`);
-  if (op.summary !== void 0) lines.push(`summary: ${op.summary}`);
-  if (op.description !== void 0) lines.push(`description: ${op.description}`);
-  if (op.tags !== void 0 && op.tags.length > 0) lines.push(`tags: ${op.tags.join(", ")}`);
+  const lines = [`${displaySafeText(op.method)} ${displaySafeText(op.path)}`];
+  if (op.operationId !== void 0) lines.push(`operationId: ${displaySafeText(op.operationId)}`);
+  if (op.summary !== void 0) lines.push(`summary: ${displaySafeText(op.summary)}`);
+  if (op.description !== void 0) lines.push(`description: ${displaySafeText(op.description)}`);
+  if (op.tags !== void 0 && op.tags.length > 0) lines.push(`tags: ${op.tags.map(displaySafeText).join(", ")}`);
   if (op.parameters.length > 0) {
     lines.push("", "parameters:");
     for (const paramRaw of op.parameters) {
@@ -3732,7 +4119,7 @@ function formatOperationDetail(op) {
       const location = typeof param["in"] === "string" ? param["in"] : "?";
       const required = param["required"] === true ? " required" : "";
       const description = typeof param["description"] === "string" ? ` - ${param["description"]}` : "";
-      lines.push(`  ${name} (${location})${required}${description}`);
+      lines.push(`  ${displaySafeText(name)} (${displaySafeText(location)})${required}${displaySafeText(description)}`);
       if (param["schema"] !== void 0) lines.push(indentedJson(param["schema"], "    "));
     }
   }
@@ -4001,10 +4388,10 @@ function isSqliteFile(filePath) {
 }
 function openReadonlySqlite(filePath) {
   if (!fs.existsSync(filePath)) {
-    throw new Error(`file not found: ${filePath}`);
+    throw new Error(`file not found: ${displaySafeText(filePath)}`);
   }
   if (!isSqliteFile(filePath)) {
-    throw new Error(`not a valid SQLite database (bad file header): ${filePath}`);
+    throw new Error(`not a valid SQLite database (bad file header): ${displaySafeText(filePath)}`);
   }
   try {
     return new Database(filePath, { readonly: true, fileMustExist: true });
@@ -4057,12 +4444,12 @@ function formatSqliteSchema(result) {
     const lines = [`${t.name}  (${t.kind}${t.rowCount !== null ? `, ${t.rowCount} row${t.rowCount === 1 ? "" : "s"}` : ""})`];
     for (const c of t.columns) {
       const flags = [c.primaryKey ? "PK" : null, c.notNull ? "NOT NULL" : null, c.defaultValue !== null ? `DEFAULT ${c.defaultValue}` : null].filter((f) => f !== null).join(" ");
-      lines.push(`  ${c.name} ${c.type || "(untyped)"}${flags ? `  ${flags}` : ""}`);
+      lines.push(`  ${displaySafeText(c.name)} ${displaySafeText(c.type || "(untyped)")}${flags ? `  ${flags}` : ""}`);
     }
     if (t.indexes.length > 0) {
       lines.push("  indexes:");
       for (const idx of t.indexes) {
-        lines.push(`    ${idx.name}${idx.unique ? " (unique)" : ""}: ${idx.columns.join(", ")}`);
+        lines.push(`    ${displaySafeText(idx.name)}${idx.unique ? " (unique)" : ""}: ${displaySafeText(idx.columns.join(", "))}`);
       }
     }
     if (t.foreignKeys.length > 0) {
@@ -4514,7 +4901,7 @@ function formatRanges(ranges) {
   return ranges.map((r) => r.start === r.end ? String(r.start) : `${r.start}-${r.end}`).join(", ");
 }
 function formatFileGaps(f) {
-  const lines = [f.filePath];
+  const lines = [displaySafeText(f.filePath)];
   lines.push(`  lines: ${f.linesHit}/${f.linesTotal}  functions: ${f.functionsHit}/${f.functionsTotal}  branches: ${f.branchesHit}/${f.branchesTotal}`);
   if (f.summaryOnly) {
     lines.push("  (summary-only report -- no per-line/function/branch detail available)");
@@ -4525,7 +4912,7 @@ function formatFileGaps(f) {
   }
   if (f.uncoveredFunctions.length > 0) {
     lines.push("  uncovered functions:");
-    for (const fn of f.uncoveredFunctions) lines.push(`    ${fn.name} (line ${fn.line})`);
+    for (const fn of f.uncoveredFunctions) lines.push(`    ${displaySafeText(fn.name)} (line ${fn.line})`);
   }
   if (f.uncoveredBranches.length > 0) {
     const branchLines = [...new Set(f.uncoveredBranches.map((br) => br.line))].sort((a, b) => a - b);
@@ -4653,25 +5040,25 @@ function indentBlock(content) {
 function formatSingleFileConflicts(result) {
   const lines = [];
   if (result.regions.length > 0) {
-    lines.push(`${result.filePath} -- ${result.regions.length} conflict${result.regions.length === 1 ? "" : "s"}`);
+    lines.push(`${displaySafeText(result.filePath)} -- ${result.regions.length} conflict${result.regions.length === 1 ? "" : "s"}`);
     for (const r of result.regions) {
       lines.push(`  lines ${r.lineStart}-${r.lineEnd}`);
-      lines.push(`    <<<<<<< ${r.ours.label || "(ours)"}`);
+      lines.push(`    <<<<<<< ${displaySafeText(r.ours.label || "(ours)")}`);
       lines.push(indentBlock(r.ours.content));
       if (r.base !== null) {
-        lines.push(`    ||||||| ${r.base.label || "(base)"}`);
+        lines.push(`    ||||||| ${displaySafeText(r.base.label || "(base)")}`);
         lines.push(indentBlock(r.base.content));
       }
       lines.push("    =======");
       lines.push(indentBlock(r.theirs.content));
-      lines.push(`    >>>>>>> ${r.theirs.label || "(theirs)"}`);
+      lines.push(`    >>>>>>> ${displaySafeText(r.theirs.label || "(theirs)")}`);
     }
   } else {
-    lines.push(`${result.filePath} -- no conflicts`);
+    lines.push(`${displaySafeText(result.filePath)} -- no conflicts`);
   }
   if (result.warnings.length > 0) {
     lines.push("  warnings:");
-    for (const w of result.warnings) lines.push(`    line ${w.line}: ${w.message}`);
+    for (const w of result.warnings) lines.push(`    line ${w.line}: ${displaySafeText(w.message)}`);
   }
   return lines.join("\n");
 }
@@ -4683,17 +5070,17 @@ function formatConflicts(results) {
 function formatSingleFileSummary(summary) {
   const lines = [];
   if (summary.conflictCount > 0) {
-    lines.push(`${summary.filePath} -- ${summary.conflictCount} conflict${summary.conflictCount === 1 ? "" : "s"}`);
+    lines.push(`${displaySafeText(summary.filePath)} -- ${summary.conflictCount} conflict${summary.conflictCount === 1 ? "" : "s"}`);
     for (const r of summary.regions) {
-      const baseText = r.baseLabel !== null ? ` base=${r.baseLabel || "(unlabeled)"}` : "";
-      lines.push(`  lines ${r.lineStart}-${r.lineEnd}  ours=${r.oursLabel || "(unlabeled)"}${baseText} theirs=${r.theirsLabel || "(unlabeled)"}`);
+      const baseText = r.baseLabel !== null ? ` base=${displaySafeText(r.baseLabel || "(unlabeled)")}` : "";
+      lines.push(`  lines ${r.lineStart}-${r.lineEnd}  ours=${displaySafeText(r.oursLabel || "(unlabeled)")}${baseText} theirs=${displaySafeText(r.theirsLabel || "(unlabeled)")}`);
     }
   } else {
-    lines.push(`${summary.filePath} -- no conflicts`);
+    lines.push(`${displaySafeText(summary.filePath)} -- no conflicts`);
   }
   if (summary.warnings.length > 0) {
     lines.push("  warnings:");
-    for (const w of summary.warnings) lines.push(`    line ${w.line}: ${w.message}`);
+    for (const w of summary.warnings) lines.push(`    line ${w.line}: ${displaySafeText(w.message)}`);
   }
   return lines.join("\n");
 }
@@ -4765,36 +5152,12 @@ function resolveBrowserExecutablePath(explicit) {
   }
   return null;
 }
-function isBlockedIpv4Octets(a, b) {
-  if (a === 127) return true;
-  if (a === 169 && b === 254) return true;
-  if (a === 10) return true;
-  if (a === 172 && b >= 16 && b <= 31) return true;
-  if (a === 192 && b === 168) return true;
-  if (a === 0) return true;
-  return false;
-}
-function isBlockedIpv6(groups) {
-  if (groups.every((g) => g === 0)) return true;
-  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return true;
-  if (groups.slice(0, 5).every((g) => g === 0) && (groups[5] === 65535 || groups[5] === 0)) {
-    const embedded = groups[6];
-    return isBlockedIpv4Octets(embedded >> 8, embedded & 255);
-  }
-  if (groups[0] === 100 && groups[1] === 65435 && groups.slice(2, 6).every((g) => g === 0)) {
-    const embedded = groups[6];
-    return isBlockedIpv4Octets(embedded >> 8, embedded & 255);
-  }
-  if ((groups[0] & 65472) === 65152) return true;
-  if ((groups[0] & 65024) === 64512) return true;
-  return false;
-}
 function isBlockedIpAddress(addr) {
   const bare = addr.replace(/^\[/, "").replace(/\]$/, "");
   const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(bare);
-  if (v4) return isBlockedIpv4Octets(Number(v4[1]), Number(v4[2]));
+  if (v4) return isPrivateIpv4Octets(Number(v4[1]), Number(v4[2]), Number(v4[3]));
   const groups = parseIpv6Groups(bare);
-  return groups !== null && isBlockedIpv6(groups);
+  return groups !== null && isPrivateIpv6Groups(groups);
 }
 function blockedAddressAmong(addresses) {
   return addresses.find((addr) => isBlockedIpAddress(addr)) ?? null;
@@ -5063,11 +5426,11 @@ function bodyFromSource(entry) {
   }
 }
 function symbolNamesInFile(filePath, dbPath = globalDbPath()) {
-  const symbols = querySymbols({ filePath, limit: 1e5 }, dbPath);
+  const symbols = querySymbols({ filePath, limit: -1 }, dbPath);
   return [...new Set(symbols.map((s) => s.name))].sort();
 }
 function computeFileFingerprint(filePath, dbPath = globalDbPath()) {
-  const symbols = querySymbols({ filePath, limit: 1e6 }, dbPath);
+  const symbols = querySymbols({ filePath, limit: -1 }, dbPath);
   const manifest = symbols.map((s) => `${s.name}:${s.kind}:${s.lineStart}-${s.lineEnd}`).sort().join("\n");
   return fingerprintContent(manifest);
 }
@@ -5291,6 +5654,39 @@ function findIdentifierNearPosition(ts, sourceFile, line0, position, name) {
 }
 
 // src/read_commands.ts
+var STATEMENT_ADAPTER_IMPORTS = new Map([
+  [".abap", extractAbap],
+  [".sas", extractSas],
+  [".pli", extractPli],
+  [".pl1", extractPli],
+  [".rpgle", extractRpg],
+  [".sqlrpgle", extractRpg],
+  [".jcl", extractJcl],
+  ...[".f", ".for", ".f77", ".f90", ".f95", ".f03", ".f08"].map((e) => [e, extractFortran]),
+  ...[".pas", ".dpr", ".dpk", ".lpr"].map((e) => [e, extractPascal]),
+  [".cmake", extractCmake],
+  ...[".s", ".asm", ".nasm"].map((e) => [e, extractAsm]),
+  ...[".bat", ".cmd"].map((e) => [e, extractBatch]),
+  ...[".erl", ".hrl"].map((e) => [e, extractErlang])
+]);
+var BRACE_ADAPTER_IMPORTS = new Map([
+  [".mm", extractObjc],
+  [".groovy", extractGroovy],
+  [".gvy", extractGroovy],
+  [".gradle", extractGroovy],
+  [".pm", extractPerl],
+  [".sol", extractSolidity],
+  [".thrift", extractThrift],
+  ...[".glsl", ".vert", ".frag", ".comp", ".geom", ".tesc", ".tese", ".hlsl", ".hlsli", ".metal"].map((e) => [e, extractCShader])
+]);
+function braceAdapterImportsFor(e, text) {
+  if (e === ".m") return isObjcSource(text) ? extractObjc : isMatlabSource(text) ? extractMatlab : void 0;
+  if (e === ".pp") return isPascalSource(text) ? extractPascal : void 0;
+  if (e === ".h") return isObjcHeader(text) ? extractObjc : void 0;
+  if (e === ".pl") return isPrologSource(text) ? void 0 : extractPerl;
+  if (e === ".t") return isPerlSource(text) ? extractPerl : void 0;
+  return BRACE_ADAPTER_IMPORTS.get(e);
+}
 var DIDYOUMEAN_LIMIT = 5;
 var SYMBOL_PREVIEW_LINES = 5;
 var AMBIGUOUS_HEADING_LIMIT = 10;
@@ -5482,6 +5878,24 @@ function healStaleIndex(resolvedPath) {
     if (err instanceof ConfinementIdentityError) throw err;
   }
 }
+var STALE_CHECK_FILE_CAP = 25;
+function warnIfFilesStale(filePaths) {
+  const checked = /* @__PURE__ */ new Set();
+  let staleCount = 0;
+  for (const raw of filePaths) {
+    if (checked.size >= STALE_CHECK_FILE_CAP) break;
+    if (checked.has(raw)) continue;
+    checked.add(raw);
+    if (staleWarning(raw) === "") continue;
+    staleCount++;
+    healStaleIndex(raw);
+  }
+  if (staleCount > 0) {
+    console.warn(
+      `token-goat: ${countNoun(staleCount, "file")} behind these results changed on disk since the index last saw ${staleCount === 1 ? "it" : "them"} -- a reindex just ran, so a repeat of this command will reflect the current version.`
+    );
+  }
+}
 function emit(text) {
   const out = colorStdout() ? text : stripAnsi(text);
   process.stdout.write(ensureNewline(out));
@@ -5499,6 +5913,9 @@ function guardText(text, command) {
 function fenceGithubText(text) {
   return fenceUntrusted(text, UNTRUSTED_GITHUB_TAG);
 }
+function fenceHtmlText(text) {
+  return fenceUntrusted(text, UNTRUSTED_HTML_TAG);
+}
 function fenceGithubFieldIfMatched(text) {
   const matches = scanAndRecord(text);
   if (matches.length === 0) return text;
@@ -5642,7 +6059,7 @@ function formatBareNameSpecError(command, name, projectRoot) {
   if (specs.length === 0) {
     return `Invalid spec - expected "file::symbol", got: ${name}`;
   }
-  const lines = [`Not a file: '${name}'. Did you mean:`];
+  const lines = [`Not a file: '${displaySafeText(name)}'. Did you mean:`];
   for (const spec of specs.slice(0, DIDYOUMEAN_LIMIT)) {
     lines.push(`  - token-goat ${command} "${spec}"`);
   }
@@ -5676,7 +6093,7 @@ function formatCrossFileLead(command, name, excludeFilePath, projectRoot) {
   return lines.join("\n");
 }
 function resolveEnclosingSymbol(filePath, chunkStartLine) {
-  const symbols = querySymbols({ filePath, limit: 1e5 }, globalDbPath());
+  const symbols = querySymbols({ filePath, limit: -1 }, globalDbPath());
   let best = null;
   for (const s of symbols) {
     if (s.lineStart <= chunkStartLine && chunkStartLine <= s.lineEnd) {
@@ -5685,7 +6102,7 @@ function resolveEnclosingSymbol(filePath, chunkStartLine) {
       }
     }
   }
-  return best === null ? null : { name: best.name, kind: best.kind };
+  return best === null ? null : { name: best.name, kind: best.kind, lineStart: best.lineStart };
 }
 function trimBlankLines(lines) {
   let start = 0;
@@ -5802,13 +6219,13 @@ function runSymbol(opts) {
     const label = opts.name ?? opts.grep ?? "*";
     const notice = `no non-test matches for '${label}' (${excludeTestsHiddenNote(hiddenByExcludeTests)})`;
     if (opts.json === true) {
-      return { text: JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2), code: 0 };
+      return { text: displaySafeJson({ items: [], truncated: false, totalCount: 0 }), code: 0 };
     }
     return { text: `token-goat: ${notice}`, code: 0 };
   }
   if (matchesGrep !== void 0 && filtered.length === 0 && preFilterCount > 0) {
     if (opts.json === true) {
-      const text2 = JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2);
+      const text2 = displaySafeJson({ items: [], truncated: false, totalCount: 0 });
       return { text: text2, code: 0 };
     }
     return { text: grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "symbol", "symbols"), code: 0 };
@@ -5876,7 +6293,7 @@ ${emptyIndexMessage(emptyIndexRoot)}`;
       ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: hasRealDocstring(s.docstring) } : {}
     }));
     const payload = { items, truncated: truncatedFlag, totalCount: trueTotal };
-    const text2 = JSON.stringify(payload, null, 2);
+    const text2 = displaySafeJson(payload);
     recordReadStat("symbol_lookup", fullSourceBytes, text2, opts.name ?? opts.file ?? opts.grep);
     return { text: text2, code: 0 };
   }
@@ -5990,7 +6407,7 @@ function runLineRange(range, opts) {
   const clampedEnd = Math.min(end, allLines.length);
   const slice = allLines.slice(start - 1, clampedEnd);
   if (opts.json === true) {
-    return { text: JSON.stringify({ file, start, end: clampedEnd, lines: slice }, null, 2), code: 0 };
+    return { text: displaySafeJson({ file, start, end: clampedEnd, lines: slice }), code: 0 };
   }
   const tok = Math.ceil(slice.join("\n").length / 4);
   return {
@@ -6022,7 +6439,8 @@ function formatAmbiguity(symbol, file, candidates, explicitRoot, commandName = "
   const multiFile = new Set(candidates.map((c) => c.filePath)).size > 1;
   const displayRoot = getDisplayRoot(explicitRoot);
   const lines = [
-    `Ambiguous symbol '${symbol}' in '${file}': ${countNoun(candidates.length, "definition")} match. Retry with one of the qualified commands below to pick one:`
+    // A symbol name and a file name are chosen by the repository, and this sentence is token-goat instructing the reader what to do next, so a name shaped like a marker would read as part of that instruction.
+    `Ambiguous symbol '${displaySafeText(symbol)}' in '${displaySafeText(file)}': ${countNoun(candidates.length, "definition")} match. Retry with one of the qualified commands below to pick one:`
   ];
   const fileSymCache = /* @__PURE__ */ new Map();
   const getFileSyms = (filePath) => {
@@ -6133,7 +6551,16 @@ function resolveSymbolSpec(spec, forceRefresh, projectRoot) {
       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
+        (cls) => cls.filePath === c.filePath && // A container is never its own containment match (mirrors findParentName's `sameSpan`
+        // exclusion above): without this, a same-named non-nesting pair on adjacent spans --
+        // e.g. an HTML `heading` symbol and an unrelated `html_id` symbol that both happen to
+        // be named "Overview" -- lets the OUTER one satisfy containment against ITSELF (its
+        // own span trivially contains itself), so `Overview.Overview` (the exact qualifier
+        // `formatAmbiguity` printed as the retry hint for the html_id candidate, since
+        // findParentName resolved its enclosing heading's name to the same string) kept both
+        // candidates in scope and reported ambiguous again -- a disambiguation hint that could
+        // never resolve the ambiguity it was emitted for.
+        !(cls.lineStart === c.lineStart && cls.lineEnd === c.lineEnd) && c.lineStart >= cls.lineStart && c.lineEnd <= cls.lineEnd
       );
     });
     if (scoped.length > 0) candidates = scoped;
@@ -6186,13 +6613,17 @@ function runRead(opts) {
     const closes = rankSimilarNames(scanned, symbol);
     if (closes.length > 0) messages.push(didYouMean(closes));
     else if (scanned.length > 0) messages.push(`Try: token-goat outline ${file}`);
+    else if (fs4.existsSync(resolved)) {
+      const gap = symbolExtractorGap(file, resolved);
+      if (gap !== void 0) messages.push(gap);
+    }
     return { text: messages.join("\n"), code: 1 };
   }
   const match = resolution.entry;
   const fullSourceBytes = sumFileSizes([match.filePath]);
   const refCounts = opts.stats === true ? queryRefCounts([match.name], globalDbPath(), resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })) : void 0;
   if (opts.json === true) {
-    const text2 = JSON.stringify(
+    const text2 = displaySafeJson(
       {
         ...match,
         body: resolveBody(match),
@@ -6200,9 +6631,7 @@ function runRead(opts) {
         // would be the one surface that still passes a deleted file's body off as a live read.
         ...fileIsGone(match.filePath) ? { deleted: true } : {},
         ...refCounts !== void 0 ? { refCount: refCounts.get(match.name) ?? 0 } : {}
-      },
-      null,
-      2
+      }
     );
     if (opts.suppressStat !== true) recordReadStat("read_replacement", fullSourceBytes, text2, opts.spec);
     return { text: text2, code: 0 };
@@ -6238,11 +6667,11 @@ ${sub.text}`);
   }
   if (anyFound) {
     const fullSourceBytes = sumFileSizes(Array.from(distinctFiles, (f) => resolveIndexPath(f, opts.projectRoot ?? process.cwd())));
-    const text2 = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+    const text2 = opts.json === true ? displaySafeJson(jsonOut) : 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");
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
   return { text, code: 1 };
 }
 function resolveAgainstProjectRoot(file, projectRoot) {
@@ -6308,7 +6737,7 @@ function runSection(opts) {
   const kind = result.redirectedFrom !== void 0 ? "section_replacement" : "section_read";
   const fullSourceBytes = sumFileSizes([filePath]);
   if (opts.json === true) {
-    const text2 = JSON.stringify(result, null, 2);
+    const text2 = displaySafeJson(result);
     if (opts.suppressStat !== true) recordReadStat(kind, fullSourceBytes, text2, heading);
     return { text: text2, code: 0 };
   }
@@ -6336,7 +6765,7 @@ function runSectionMulti(specFilePath, resolvedFilePath, headings, opts) {
 ${sub.text}`);
   }
   const fullSourceBytes = sumFileSizes([resolvedFilePath]);
-  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
   if (anyFound) recordReadStat("section_read", fullSourceBytes, text, opts.spec);
   return { text, code: anyFound ? 0 : 1 };
 }
@@ -6358,7 +6787,7 @@ function runSectionCrossFile(pairs, opts) {
 ${sub.text}`);
   }
   const resolvePath = (f) => opts.projectRoot !== void 0 && !path4.isAbsolute(f) ? path4.resolve(opts.projectRoot, f) : f;
-  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
   if (anyFound) {
     const fullSourceBytes = sumFileSizes(Array.from(distinctFiles, resolvePath));
     recordReadStat("section_read", fullSourceBytes, text, opts.spec);
@@ -6378,7 +6807,7 @@ function refsJsonItems(items, contextLines) {
 }
 function renderRefLines(ref, contextLines, indent = "  ") {
   const displayPath = refsDisplayPath(ref.filePath);
-  const base = `${indent}${displayPath}:${ref.line}: ${ref.context}`;
+  const base = `${indent}${displaySafeText(displayPath)}:${ref.line}: ${displaySafeText(ref.context)}`;
   const window = buildContextWindow(ref.filePath, ref.line, contextLines);
   if (window === null) return [base];
   return [base, ...renderContextWindow(displayPath, ref.line, window, "", `${indent}  `)];
@@ -6501,9 +6930,10 @@ function renderRefsTargets(targets, opts, {
       if (notice !== null) lines.push(`  token-goat: ${notice}`);
     }
   }
+  warnIfFilesStale(refRows.map((r) => r.filePath));
   const fullSourceBytes = refsSearchBaselineBytes(refRows);
   if (opts.json === true) {
-    const text2 = JSON.stringify(jsonOut, null, 2);
+    const text2 = displaySafeJson(jsonOut);
     emit(text2);
     if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text2, opts.spec);
     return anyFound ? 0 : 1;
@@ -6591,7 +7021,7 @@ function runRefsSingle(opts) {
   if (results.length === 0) {
     if (matchesGrep !== void 0 && preGrepCount > 0) {
       if (opts.json === true) {
-        emit(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preGrepCount }, null, 2));
+        emit(displaySafeJson({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preGrepCount }));
         return 0;
       }
       emit(grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references"));
@@ -6611,7 +7041,7 @@ function runRefsSingle(opts) {
     const defPaths = defFileHint !== void 0 ? [defFileHint] : defRows.map((r) => r.filePath);
     const firstDefPath = defPaths[0];
     if (firstDefPath !== void 0 && defPaths.every((fp) => !isRefIndexedFile(fp))) {
-      emitErr(refBlindLanguageNotice(symName, detectLanguage(firstDefPath), refsDisplayPath(firstDefPath)));
+      emitErr(refBlindLanguageNotice(symName, detectLanguageOfFile(firstDefPath), refsDisplayPath(firstDefPath)));
       return 1;
     }
     const kindRows = defFileHint !== void 0 ? querySymbols({ name: symName, filePath: defFileHint, rootDir: rootDir2, limit: REF_BLIND_DEF_PROBE_LIMIT }) : defRows;
@@ -6627,6 +7057,7 @@ function runRefsSingle(opts) {
     }
     return 1;
   }
+  warnIfFilesStale(results.map((r) => r.filePath));
   const fullSourceBytes = refsSearchBaselineBytes(results);
   if (opts.json === true) {
     let payload;
@@ -6638,7 +7069,7 @@ function runRefsSingle(opts) {
       payload = { items: refsJsonItems(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
     }
     const hiddenByGrep = matchesGrep !== void 0 ? preGrepCount - (filteredTotal ?? results.length) : 0;
-    const text2 = JSON.stringify({ ...payload, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} }, null, 2);
+    const text2 = displaySafeJson({ ...payload, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} });
     emit(text2);
     recordReadStat("symbol_read", fullSourceBytes, text2, symName);
     return 0;
@@ -6690,24 +7121,34 @@ function renderCallerGroups(refs, contextLines = 0) {
   const lines = [];
   for (const [file, fileRefs] of byFile) {
     const displayPath = refsDisplayPath(file);
-    lines.push(`${displayPath}:`);
+    lines.push(`${displaySafeText(displayPath)}:`);
     for (const ref of fileRefs) {
-      lines.push(`  :${ref.line}  ${ref.context !== "" ? ref.context : "(module scope)"}`);
+      lines.push(`  :${ref.line}  ${ref.context !== "" ? displaySafeText(ref.context) : "(module scope)"}`);
       const window = buildContextWindow(file, ref.line, contextLines);
       if (window !== null) lines.push(...renderContextWindow(displayPath, ref.line, window, "", "    "));
     }
   }
   return lines;
 }
+function symbolExtractorGap(displayPath, resolvedPath) {
+  const ext = path4.extname(resolvedPath).toLowerCase();
+  const named = unsupportedLanguageName(resolvedPath);
+  const language = detectLanguageOfFile(resolvedPath);
+  if (named !== void 0 || language === "unknown") {
+    const what = named !== void 0 ? `${named}, ${ext}` : ext !== "" ? ext : "no extension";
+    return `'${displayPath}': token-goat has no symbol extractor for this file type (${what}), so there are no symbols to list; grep, plain reads and \`token-goat tokens\` still work on it.
+` + supportRequestLine(named ?? (ext !== "" ? `${ext} file` : "this file type"));
+  }
+  if (TREE_SITTER_LANGUAGES.includes(language) && !isTreeSitterAvailable(language)) {
+    return `No symbols found in '${displayPath}', but tree-sitter parsing for this file type (${ext}) is unavailable, so only a coarse regex fallback ran. Run \`token-goat doctor\` for the cause and the fix.`;
+  }
+  return void 0;
+}
 function noSymbolsMessage(displayPath, resolvedPath) {
   if (!fs4.existsSync(resolvedPath)) {
     return `Could not read: ${displayPath}`;
   }
-  const lang = unsupportedLanguageName(resolvedPath);
-  if (lang !== void 0) {
-    return `No indexed symbols found in '${displayPath}' -- ${lang} has no symbol extractor yet, so this file always indexes to 0 symbols regardless of its contents`;
-  }
-  return `No indexed symbols found in '${displayPath}'`;
+  return symbolExtractorGap(displayPath, resolvedPath) ?? `No indexed symbols found in '${displayPath}'`;
 }
 var SKELETON_SYMBOL_CAP = 5e3;
 function hasRealDocstring(docstring) {
@@ -6746,7 +7187,8 @@ function prepareSymbolListing(file, opts) {
   );
   const refCounts = opts.stats === true ? queryRefCounts(filtered.map((s) => s.name), globalDbPath(), resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })) : void 0;
   const fullSourceBytes = sumFileSizes([resolved]);
-  return { kind: "ok", resolved, displayRoot: getDisplayRoot(opts.projectRoot), filtered, preFilterCount: symbols.length, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount };
+  const totalLines = symbols.length > 0 ? Math.max(...symbols.map((s) => s.lineEnd)) : 0;
+  return { kind: "ok", resolved, displayRoot: getDisplayRoot(opts.projectRoot), filtered, preFilterCount: symbols.length, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount, totalLines };
 }
 function runPerFileListing(files, run, json = false) {
   const blocks = [];
@@ -6781,7 +7223,7 @@ function mergeListingJson(files, blocks, anyOk) {
     totalCount += parsed.totalCount ?? parsed.items.length;
   }
   const payload = { items, truncated, totalCount, ...errors.length > 0 ? { errors } : {} };
-  return { text: JSON.stringify(payload, null, 2), code: anyOk ? 0 : 1 };
+  return { text: displaySafeJson(payload), code: anyOk ? 0 : 1 };
 }
 function symbolCountLabel(shown, truncated, trueCount) {
   if (!truncated || trueCount === void 0 || trueCount <= shown) return countNoun(shown, "symbol");
@@ -6794,7 +7236,7 @@ function runSkeleton(opts) {
   if (prep.kind === "confined" || prep.kind === "empty") {
     return { text: prep.text, code: 1 };
   }
-  const { resolved, displayRoot, filtered, preFilterCount, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount } = prep;
+  const { resolved, displayRoot, filtered, preFilterCount, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount, totalLines } = prep;
   if (opts.json === true) {
     const rows = filtered.map((s) => ({
       ...opts.includeFilePath === true ? { filePath: toDisplayPath(displayRoot, s.filePath) } : {},
@@ -6814,11 +7256,10 @@ function runSkeleton(opts) {
       // tests/json_envelope_shape.test.ts pins.
       ...fileIsGone(resolved) ? { deleted: true } : {}
     };
-    const text2 = JSON.stringify(payload, null, 2);
+    const text2 = displaySafeJson(payload);
     recordReadStat("stub_view", fullSourceBytes, text2, opts.file);
     return { text: text2, code: 0 };
   }
-  const totalLines = filtered.length > 0 ? Math.max(...filtered.map((s) => s.lineEnd)) : 0;
   const lines = [`# Skeleton: ${opts.file}  (${symbolCountLabel(filtered.length, symbolsTruncated, trueSymbolCount)}, ${countNoun(totalLines, "line")})`];
   if (filtered.length === 0 && preFilterCount > 0) lines.push(filteredToEmptyNotice(preFilterCount, opts.minLines, opts.grep));
   for (const sym of filtered) {
@@ -6879,7 +7320,7 @@ function runOutline(opts) {
       // Same envelope-level flag, and same reason, as runSkeleton's payload above.
       ...fileIsGone(resolved) ? { deleted: true } : {}
     };
-    const text2 = JSON.stringify(payload, null, 2);
+    const text2 = displaySafeJson(payload);
     recordReadStat("outline", fullSourceBytes, text2, opts.file);
     return { text: text2, code: 0 };
   }
@@ -6921,7 +7362,7 @@ function runCsvQuery(opts) {
       ...opts.noHeader === true ? { noHeader: true } : {}
     });
     if (result.header.length === 0) {
-      emit(`No data rows found in ${opts.file}`);
+      emit(`No data rows found in ${displaySafeText(opts.file)}`);
       return 0;
     }
     const fullSourceBytes = sumFileSizes([opts.file]);
@@ -6929,7 +7370,7 @@ function runCsvQuery(opts) {
       const rowsJson = result.rows.map((r) => Object.fromEntries(result.header.map((h, i) => [h, r[i]])));
       const headTruncated = result.rows.length < result.totalRows;
       const capped = guardJsonRows(rowsJson);
-      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount: result.totalRows, ...result.totalRows === 0 && result.preFilterRows > 0 ? { filteredFromRows: result.preFilterRows } : {} });
+      const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount: result.totalRows, ...result.totalRows === 0 && result.preFilterRows > 0 ? { filteredFromRows: result.preFilterRows } : {} }, 0);
       emit(jsonText);
       recordReadStat("csv_query", fullSourceBytes, jsonText, opts.file);
     } else {
@@ -6955,7 +7396,7 @@ function runCsvProfile(opts) {
       ...opts.noHeader === true ? { noHeader: true } : {}
     });
     if (profiles.length === 0) {
-      emit(`No data rows found in ${opts.file}`);
+      emit(`No data rows found in ${displaySafeText(opts.file)}`);
       return 0;
     }
     const fullSourceBytes = sumFileSizes([opts.file]);
@@ -6984,7 +7425,7 @@ function runOutlineCommand(opts, parse, formatLabel, kind) {
   const outline = outlineJson(data);
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(outline);
+    const jsonText = displaySafeJson(outline, 0);
     emit(jsonText);
     recordReadStat(kind, fullSourceBytes, jsonText, opts.file);
   } else {
@@ -7022,7 +7463,7 @@ function runQueryCommand(opts, parse, formatLabel, guardTag, kind) {
     const fullSourceBytes = sumFileSizes([opts.file]);
     if (!result.fanned) {
       const value = result.items[0];
-      const valueText = opts.json === true ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+      const valueText = opts.json === true ? displaySafeJson(value, 0) : displaySafeJson(value);
       emit(valueText);
       recordReadStat(kind, fullSourceBytes, valueText, opts.file);
       return 0;
@@ -7032,11 +7473,11 @@ function runQueryCommand(opts, parse, formatLabel, guardTag, kind) {
     const headTruncated = limited.length < totalCount;
     if (opts.json === true) {
       const capped = guardJsonRows(limited);
-      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount });
+      const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount }, 0);
       emit(jsonText);
       recordReadStat(kind, fullSourceBytes, jsonText, opts.file);
     } else {
-      const lines = limited.map((item) => JSON.stringify(item));
+      const lines = limited.map((item) => displaySafeJson(item, 0));
       if (headTruncated) {
         lines.push(`...(${totalCount - limited.length} more items elided; use --head to see more)`);
       }
@@ -7101,7 +7542,7 @@ ${extractErrorMessage(e)}`);
   }
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(summary, null, 2);
+    const jsonText = displaySafeJson(summary);
     emit(jsonText);
     recordReadStat("xml_outline", fullSourceBytes, jsonText, opts.file);
   } else {
@@ -7130,17 +7571,17 @@ function runXmlQuery(opts) {
     if (result.attributeValues !== void 0) {
       if (result.attributeValues.length === 0) {
         if (opts.json === true) {
-          const jsonText = JSON.stringify({ items: [], truncated: false, totalCount: 0 });
+          const jsonText = displaySafeJson({ items: [], truncated: false, totalCount: 0 }, 0);
           emit(jsonText);
           recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
         } else {
-          emit(`No attributes matched path: '${opts.path}'`);
+          emit(`No attributes matched path: '${displaySafeText(opts.path)}'`);
         }
         return 0;
       }
       if (!result.fanned) {
         const val = result.attributeValues[0] ?? "";
-        const outText = opts.json === true ? JSON.stringify(val) : val;
+        const outText = opts.json === true ? displaySafeJson(val, 0) : val;
         emit(outText);
         recordReadStat("xml_query", fullSourceBytes, outText, opts.file);
         return 0;
@@ -7150,7 +7591,7 @@ function runXmlQuery(opts) {
       const headTruncated2 = limited2.length < totalCount2;
       if (opts.json === true) {
         const capped = guardJsonRows(limited2);
-        const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated2, totalCount: totalCount2 });
+        const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated2, totalCount: totalCount2 }, 0);
         emit(jsonText);
         recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
       } else {
@@ -7166,11 +7607,11 @@ function runXmlQuery(opts) {
     }
     if (result.items.length === 0) {
       if (opts.json === true) {
-        const jsonText = JSON.stringify({ items: [], truncated: false, totalCount: 0 });
+        const jsonText = displaySafeJson({ items: [], truncated: false, totalCount: 0 }, 0);
         emit(jsonText);
         recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
       } else {
-        emit(`No elements matched path: '${opts.path}'`);
+        emit(`No elements matched path: '${displaySafeText(opts.path)}'`);
       }
       return 0;
     }
@@ -7178,7 +7619,7 @@ function runXmlQuery(opts) {
       const node = result.items[0];
       if (opts.json === true) {
         const jsonVal = xmlNodeToJson(node);
-        const jsonText = JSON.stringify(jsonVal, null, 2);
+        const jsonText = displaySafeJson(jsonVal);
         emit(jsonText);
         recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
       } else {
@@ -7194,7 +7635,7 @@ function runXmlQuery(opts) {
     if (opts.json === true) {
       const jsonItems = limited.map(xmlNodeToJson);
       const capped = guardJsonRows(jsonItems);
-      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount });
+      const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount }, 0);
       emit(jsonText);
       recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
     } else {
@@ -7212,6 +7653,160 @@ function runXmlQuery(opts) {
     return 1;
   }
 }
+function runHtmlOutline(opts) {
+  const text = readFileText(opts.file);
+  if (text === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  const summary = outlineHtml(text);
+  const fullSourceBytes = sumFileSizes([opts.file]);
+  if (opts.json === true) {
+    const jsonText = displaySafeJson(summary);
+    emit(jsonText);
+    recordReadStat("html_outline", fullSourceBytes, jsonText, opts.file);
+  } else {
+    const outlineText = formatHtmlOutline(summary);
+    emitGuarded(outlineText, "html-outline");
+    recordReadStat("html_outline", fullSourceBytes, outlineText, opts.file);
+  }
+  return 0;
+}
+function runHtmlQuery(opts) {
+  const text = readFileText(opts.file);
+  if (text === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  let head;
+  try {
+    head = opts.head !== void 0 ? requireNonNegativeStrictInt("--head", opts.head) : void 0;
+  } catch (e) {
+    emitErr(extractErrorMessage(e));
+    return 1;
+  }
+  try {
+    const querySelector = opts.attr ? `${opts.selector}@${opts.attr}` : opts.selector;
+    const result = queryHtml(text, querySelector);
+    const fullSourceBytes = sumFileSizes([opts.file]);
+    if (result.attributeValues !== void 0) {
+      if (result.attributeValues.length === 0) {
+        if (opts.json === true) {
+          const jsonText = displaySafeJson({ items: [], truncated: false, totalCount: 0 }, 0);
+          emit(jsonText);
+          recordReadStat("html_query", fullSourceBytes, jsonText, opts.file);
+        } else {
+          emit(`No attributes matched selector: '${displaySafeText(opts.selector)}'`);
+        }
+        return 0;
+      }
+      const totalCount2 = result.attributeValues.length;
+      const limited2 = head !== void 0 ? result.attributeValues.slice(0, head) : result.attributeValues;
+      const headTruncated2 = limited2.length < totalCount2;
+      if (opts.json === true) {
+        const capped = guardJsonRows(limited2);
+        const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated2, totalCount: totalCount2 }, 0);
+        emit(jsonText);
+        recordReadStat("html_query", fullSourceBytes, jsonText, opts.file);
+      } else {
+        const lines = limited2.map((item) => item);
+        if (headTruncated2) {
+          lines.push(`...(${totalCount2 - limited2.length} more items elided; use --head to see more)`);
+        }
+        const plainText = lines.join("\n");
+        emitGuarded(fenceHtmlText(plainText), "html-query");
+        recordReadStat("html_query", fullSourceBytes, plainText, opts.file);
+      }
+      return 0;
+    }
+    if (result.elements.length === 0) {
+      if (opts.json === true) {
+        const jsonText = displaySafeJson({ items: [], truncated: false, totalCount: 0 }, 0);
+        emit(jsonText);
+        recordReadStat("html_query", fullSourceBytes, jsonText, opts.file);
+      } else {
+        emit(`No elements matched selector: '${displaySafeText(opts.selector)}'`);
+      }
+      return 0;
+    }
+    const totalCount = result.elements.length;
+    const limited = head !== void 0 ? result.elements.slice(0, head) : result.elements;
+    const headTruncated = limited.length < totalCount;
+    if (opts.json === true) {
+      const jsonItems = limited.map((n) => ({
+        tag: n.tag,
+        attributes: n.attributes,
+        text: extractNodeText(n, text),
+        line: n.line,
+        endLine: n.endLine
+      }));
+      const capped = guardJsonRows(jsonItems);
+      const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount });
+      emit(jsonText);
+      recordReadStat("html_query", fullSourceBytes, jsonText, opts.file);
+    } else if (opts.text === true) {
+      const textLines = limited.map((n) => extractNodeText(n, text)).filter(Boolean);
+      if (headTruncated) {
+        textLines.push(`...(${totalCount - limited.length} more elements elided; use --head to see more)`);
+      }
+      const plainText = textLines.join("\n\n");
+      emitGuarded(fenceHtmlText(plainText), "html-query");
+      recordReadStat("html_query", fullSourceBytes, plainText, opts.file);
+    } else {
+      const blocks = limited.map((node) => serializeHtmlNode(node, 0, text));
+      if (headTruncated) {
+        blocks.push(`...(${totalCount - limited.length} more elements elided; use --head to see more)`);
+      }
+      const plainText = blocks.join("\n\n");
+      emitGuarded(fenceHtmlText(plainText), "html-query");
+      recordReadStat("html_query", fullSourceBytes, plainText, opts.file);
+    }
+    return 0;
+  } catch (e) {
+    emitErr(extractErrorMessage(e));
+    return 1;
+  }
+}
+function runHtmlLint(opts) {
+  const text = readFileText(opts.file);
+  if (text === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  const report = lintHtml(text);
+  const isClean = opts.strict ? report.errors.length === 0 && report.warnings.length === 0 : report.errors.length === 0;
+  if (opts.json === true) {
+    emit(displaySafeJson(report));
+    return isClean ? 0 : 1;
+  }
+  if (report.errors.length === 0 && report.warnings.length === 0) {
+    emit(`\u2713 ${displaySafeText(opts.file)}: HTML structure is valid (all tags balanced, no duplicate IDs, void elements respected).`);
+    return 0;
+  }
+  const lines = [];
+  if (report.errors.length > 0) {
+    lines.push(`Errors found in ${displaySafeText(opts.file)} (${report.errors.length}):`);
+    for (const err of report.errors) {
+      lines.push(`  line ${err.line}: [${err.rule}] ${displaySafeText(err.message)}`);
+    }
+  }
+  if (report.warnings.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`Warnings in ${displaySafeText(opts.file)} (${report.warnings.length}):`);
+    for (const warn of report.warnings) {
+      lines.push(`  line ${warn.line}: [${warn.rule}] ${displaySafeText(warn.message)}`);
+    }
+  }
+  const unbalanced = Object.entries(report.tagCounts).filter(([, c]) => c.diff !== 0);
+  if (unbalanced.length > 0) {
+    lines.push("", "Unbalanced tags:");
+    for (const [tag, counts] of unbalanced) {
+      lines.push(`  <${tag}>: open=${counts.open}, close=${counts.close}, diff=${counts.diff}`);
+    }
+  }
+  emit(lines.join("\n"));
+  return isClean ? 0 : 1;
+}
 function loadOpenApiOperations(file) {
   const text = readFileText(file);
   if (text === null) {
@@ -7232,7 +7827,7 @@ function runOpenApiOutline(opts) {
   if (operations === null) return 1;
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(operations);
+    const jsonText = displaySafeJson(operations, 0);
     emit(jsonText);
     recordReadStat("openapi_outline", fullSourceBytes, jsonText, opts.file);
   } else {
@@ -7256,7 +7851,7 @@ function runOpenApiOp(opts) {
   }
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(match);
+    const jsonText = displaySafeJson(match, 0);
     emit(jsonText);
     recordReadStat("openapi_op", fullSourceBytes, jsonText, opts.operation);
   } else {
@@ -7294,7 +7889,7 @@ async function runZipList(opts) {
   }
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(entries);
+    const jsonText = displaySafeJson(entries, 0);
     emit(jsonText);
     recordReadStat("zip_list", fullSourceBytes, jsonText, opts.file);
   } else {
@@ -7345,7 +7940,7 @@ async function runZipRead(opts) {
   const text = isValidUtf8(buf) ? buf.toString("utf-8") : "[binary content elided by token-goat]";
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify({ path: opts.entry, text });
+    const jsonText = displaySafeJson({ path: opts.entry, text }, 0);
     emit(jsonText);
     recordReadStat("zip_read", fullSourceBytes, jsonText, opts.entry);
   } else {
@@ -7399,7 +7994,7 @@ function runPrSlice(opts) {
         const fullSourceBytes = Buffer.byteLength(JSON.stringify(files), "utf8");
         if (opts.json === true) {
           const capped = guardJsonRows(files);
-          const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
+          const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, 0);
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} files`);
         } else {
@@ -7411,14 +8006,15 @@ function runPrSlice(opts) {
       }
       case "diff": {
         const diffText = fetchPrDiff(opts.pr, repo);
-        const fileDiff = extractFileDiff(diffText, parsed.path);
-        if (fileDiff === null) {
+        const rawFileDiff = extractFileDiff(diffText, parsed.path);
+        if (rawFileDiff === null) {
           emitErr(`No diff found for '${parsed.path}' in PR #${opts.pr}`);
           return 1;
         }
+        const fileDiff = redactSecrets(rawFileDiff).text;
         const fullSourceBytes = Buffer.byteLength(diffText, "utf8");
         if (opts.json === true) {
-          const jsonText = JSON.stringify({ path: parsed.path, diff: fenceGithubFieldIfMatched(fileDiff) });
+          const jsonText = displaySafeJson({ path: parsed.path, diff: fenceGithubFieldIfMatched(fileDiff) }, 0);
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} diff:${parsed.path}`);
         } else {
@@ -7428,12 +8024,17 @@ function runPrSlice(opts) {
         return 0;
       }
       case "comments": {
-        const comments = fetchPrComments(opts.pr, repo);
-        const fullSourceBytes = Buffer.byteLength(JSON.stringify(comments), "utf8");
+        const rawComments = fetchPrComments(opts.pr, repo);
+        const fullSourceBytes = Buffer.byteLength(JSON.stringify(rawComments), "utf8");
+        const comments = rawComments.map((c) => ({
+          ...c,
+          body: redactSecrets(c.body).text,
+          ...c.diffHunk !== void 0 ? { diffHunk: redactSecrets(c.diffHunk).text } : {}
+        }));
         if (opts.json === true) {
           const fencedComments = comments.map((c) => ({ ...c, body: fenceGithubFieldIfMatched(c.body) }));
           const capped = guardJsonRows(fencedComments);
-          const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
+          const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, 0);
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} comments`);
         } else {
@@ -7444,15 +8045,20 @@ function runPrSlice(opts) {
         return 0;
       }
       case "description": {
-        const desc = fetchPrDescription(opts.pr, repo);
-        const fullSourceBytes = Buffer.byteLength(JSON.stringify(desc), "utf8");
+        const rawDesc = fetchPrDescription(opts.pr, repo);
+        const fullSourceBytes = Buffer.byteLength(JSON.stringify(rawDesc), "utf8");
+        const desc = {
+          ...rawDesc,
+          title: redactSecrets(rawDesc.title).text,
+          body: rawDesc.body !== null ? redactSecrets(rawDesc.body).text : null
+        };
         if (opts.json === true) {
           const fencedDesc = {
             ...desc,
             title: fenceGithubFieldIfMatched(desc.title),
             body: desc.body !== null ? fenceGithubFieldIfMatched(desc.body) : null
           };
-          const jsonText = JSON.stringify(fencedDesc);
+          const jsonText = displaySafeJson(fencedDesc, 0);
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} description`);
         } else {
@@ -7473,7 +8079,7 @@ function runSqliteSchema(opts) {
     const schema = getSqliteSchema(opts.file);
     const fullSourceBytes = sumFileSizes([opts.file]);
     if (opts.json === true) {
-      const jsonText = JSON.stringify(schema);
+      const jsonText = displaySafeJson(schema, 0);
       emit(jsonText);
       recordReadStat("sqlite_schema", fullSourceBytes, jsonText, opts.file);
     } else {
@@ -7502,22 +8108,22 @@ function runSqliteQuery(opts) {
     const rows = head !== void 0 ? result.rows.slice(0, head) : result.rows;
     if (opts.json === true) {
       const capped = guardJsonRows(rows);
-      const jsonText = JSON.stringify({
+      const jsonText = displaySafeJson({
         columns: result.columns,
         items: capped.items,
         truncated: capped.truncated || headTruncated || result.rowCapped,
         totalCount,
         rowCapped: result.rowCapped
-      });
+      }, 0);
       emit(jsonText);
       const uncappedFull = guardJsonRows(result.rows);
-      const baselineJsonText = JSON.stringify({
+      const baselineJsonText = displaySafeJson({
         columns: result.columns,
         items: uncappedFull.items,
         truncated: uncappedFull.truncated || result.rowCapped,
         totalCount,
         rowCapped: result.rowCapped
-      });
+      }, 0);
       recordReadStat("sqlite_query", Buffer.byteLength(baselineJsonText, "utf8"), jsonText, opts.file);
     } else {
       const text = formatSqliteQueryTable({ ...result, rows }, { headTruncated });
@@ -7548,7 +8154,7 @@ ${extractErrorMessage(e)}`);
   const scoped = opts.fileFilter !== void 0 ? filterCoverageGapsByFile(report, opts.fileFilter) : report;
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = JSON.stringify(scoped);
+    const jsonText = displaySafeJson(scoped, 0);
     emit(jsonText);
     recordReadStat("coverage_report_gaps", fullSourceBytes, jsonText, opts.file);
   } else {
@@ -7583,7 +8189,7 @@ function runConflicts(opts) {
   const fullSourceBytes = sumFileSizes(files);
   const detail = opts.path ?? ".";
   if (opts.json === true) {
-    const jsonText = JSON.stringify(opts.summary === true ? results.map(summarizeFileConflicts) : results);
+    const jsonText = displaySafeJson(opts.summary === true ? results.map(summarizeFileConflicts) : results, 0);
     emit(jsonText);
     recordReadStat("conflicts", fullSourceBytes, jsonText, detail);
   } else if (opts.summary === true) {
@@ -7597,34 +8203,24 @@ function runConflicts(opts) {
   }
   return 0;
 }
-async function runPdfExtractText(file, pagesSpec, layout = false) {
+async function readPdfBytes(file) {
   if (!fileExists(file)) {
     throw new Error(`Could not read: ${file}`);
   }
-  const data = fs4.readFileSync(file);
-  const result = await extractPdfText(new Uint8Array(data), pagesSpec, layout);
+  return readPdfFileWithinBounds(file);
+}
+async function runPdfExtractText(file, pagesSpec, layout = false) {
+  const result = await extractPdfText(await readPdfBytes(file), pagesSpec, layout);
   return result.text;
 }
 async function runPdfOutline(file) {
-  if (!fileExists(file)) {
-    throw new Error(`Could not read: ${file}`);
-  }
-  const data = fs4.readFileSync(file);
-  return extractPdfOutline(new Uint8Array(data));
+  return extractPdfOutline(await readPdfBytes(file));
 }
 async function runPdfMeta(file) {
-  if (!fileExists(file)) {
-    throw new Error(`Could not read: ${file}`);
-  }
-  const data = fs4.readFileSync(file);
-  return extractPdfMeta(new Uint8Array(data));
+  return extractPdfMeta(await readPdfBytes(file));
 }
 async function runPdfLocate(file, pattern, opts) {
-  if (!fileExists(file)) {
-    throw new Error(`Could not read: ${file}`);
-  }
-  const data = fs4.readFileSync(file);
-  return locatePdfPages(new Uint8Array(data), pattern, opts);
+  return locatePdfPages(await readPdfBytes(file), pattern, opts);
 }
 async function runImageMeta(file) {
   if (!fileExists(file)) {
@@ -7745,14 +8341,15 @@ ${emptyIndexMessage(rootDir2)}`, code: 1 };
       ...hiddenByGrep > 0 ? { hiddenByGrep } : {},
       section
     };
-    const jsonText = JSON.stringify(result, null, 2);
+    const jsonText = displaySafeJson(result);
     if (opts.suppressStat !== true) recordReadStat("brief_view", fullSourceBytes, jsonText, opts.spec);
     return { text: jsonText, code: 0 };
   }
   const body = resolveBody(match);
   const bodyLen = match.lineEnd - match.lineStart + 1;
   const lines = [
-    `# ${match.name}  ${match.kind}  ${toDisplayPath(rootDir, match.filePath)}:${match.lineStart}-${match.lineEnd}`,
+    // This header is token-goat's own line quoting a repo-chosen name, kind and path, so it is escaped. `body` below it is the source the reader asked for and stays byte-for-byte.
+    `# ${displaySafeText(match.name)}  ${displaySafeText(match.kind)}  ${displaySafeText(toDisplayPath(rootDir, match.filePath))}:${match.lineStart}-${match.lineEnd}`,
     `# ${countNoun(bodyLen, "line")} (~${Math.ceil(body.length / 4)} tok)`,
     body,
     ""
@@ -7795,7 +8392,7 @@ function runBriefMulti(file, symbols, opts) {
 ${sub.text}`);
   }
   const fullSourceBytes = sumFileSizes([resolveIndexPath(file, opts.projectRoot ?? process.cwd())]);
-  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
   if (anyFound) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
   return { text, code: anyFound ? 0 : 1 };
 }
@@ -7817,7 +8414,7 @@ function runBriefCrossFile(pairs, opts) {
 ${sub.text}`);
   }
   const fullSourceBytes = sumFileSizes([...distinctFiles].map((f) => resolveIndexPath(f, opts.projectRoot ?? process.cwd())));
-  const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
   if (anyFound) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
   return { text, code: anyFound ? 0 : 1 };
 }
@@ -7874,7 +8471,7 @@ function runFind(opts) {
   }
   if (opts.json === true) {
     const fuzzyPayload = fuzzyNames.length > 0 ? { fuzzy: true, matchedNames: fuzzyNames } : {};
-    emit(JSON.stringify({ files, truncated, totalCount: allFiles.length, ...fuzzyPayload }, null, 2));
+    emit(displaySafeJson({ files, truncated, totalCount: allFiles.length, ...fuzzyPayload }));
     return 0;
   }
   if (fuzzyNames.length > 0) {
@@ -7914,7 +8511,7 @@ function runListSections(opts) {
   const filtered = matchesGrep !== void 0 ? labelled.filter((_, i) => matchesGrep(sections[i] ?? "")) : labelled;
   if (filtered.length === 0) {
     if (opts.json === true) {
-      emit(JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2));
+      emit(displaySafeJson({ items: [], truncated: false, totalCount: 0 }));
       return 0;
     }
     emit(grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "section", "sections"));
@@ -7922,7 +8519,7 @@ function runListSections(opts) {
   }
   if (opts.json === true) {
     const capped = guardJsonRows(filtered);
-    emit(JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, null, 2));
+    emit(displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }));
     return 0;
   }
   for (const heading of filtered) {
@@ -8022,7 +8619,7 @@ function runChanged(opts = {}) {
     return 1;
   }
   const emptyEnvelope = () => {
-    emit(JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2));
+    emit(displaySafeJson({ items: [], truncated: false, totalCount: 0 }));
     return 0;
   };
   if (changedFiles.length === 0) {
@@ -8083,14 +8680,14 @@ function runChanged(opts = {}) {
     const symbolFullBytes = symbolDiffBaselineBytes;
     if (opts.json === true) {
       const capped = guardJsonRows(allSymbols);
-      const text = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, null, 2);
+      const text = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
       emit(text);
       recordReadStat("changed_lookup", symbolFullBytes, text, ref);
       return 0;
     }
     const symbolText = allSymbols.map((s) => `${s.name} (${s.kind}) \u2014 ${toDisplayPath(projectRoot, s.filePath)}:${s.lineStart}`).join("\n");
     for (const s of allSymbols) {
-      emit(`${s.name} (${s.kind}) \u2014 ${toDisplayPath(projectRoot, s.filePath)}:${s.lineStart}`);
+      emit(`${displaySafeText(s.name)} (${displaySafeText(s.kind)}) \u2014 ${displaySafeText(toDisplayPath(projectRoot, s.filePath))}:${s.lineStart}`);
     }
     recordReadStat("changed_lookup", symbolFullBytes, symbolText, ref);
     return 0;
@@ -8098,7 +8695,7 @@ function runChanged(opts = {}) {
   const fullBytes = changedDiffBaselineBytes(cwd, ref, changedFiles);
   if (opts.json === true) {
     const capped = guardJsonRows(changedFiles);
-    const text = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, null, 2);
+    const text = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
     emit(text);
     recordReadStat("changed_lookup", fullBytes, text, ref);
     return 0;
@@ -8199,19 +8796,19 @@ function runDiff(opts) {
     return 1;
   }
   if (diffResult.stdout.trim() === "") {
-    emit(`No changes to '${match.name}' in '${toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)}'.`);
+    emit(`No changes to '${displaySafeText(match.name)}' in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
     return 0;
   }
   const { hunks } = splitDiffHunks(diffResult.stdout);
   const overlapping = hunks.filter((h) => h.start <= match.lineEnd && h.end >= match.lineStart);
   if (overlapping.length === 0) {
-    emit(`No changes to '${match.name}' (lines ${match.lineStart}-${match.lineEnd}) in '${toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)}'.`);
+    emit(`No changes to '${displaySafeText(match.name)}' (lines ${match.lineStart}-${match.lineEnd}) in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
     return 0;
   }
   if (opts.json === true) {
     const capped = guardJsonRows(overlapping.map((h) => ({ start: h.start, end: h.end, text: h.text })));
     emit(
-      JSON.stringify(
+      displaySafeJson(
         {
           symbol: match.name,
           file: match.filePath,
@@ -8220,14 +8817,12 @@ function runDiff(opts) {
           hunks: capped.items,
           truncated: capped.truncated,
           totalCount: capped.totalCount
-        },
-        null,
-        2
+        }
       )
     );
     return 0;
   }
-  const header = `# ${match.name} (${match.kind}) \u2014 ${toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)}:${match.lineStart}-${match.lineEnd}`;
+  const header = `# ${displaySafeText(match.name)} (${displaySafeText(match.kind)}) \u2014 ${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}:${match.lineStart}-${match.lineEnd}`;
   emit(guardText([header, ...overlapping.map((h) => h.text)].join("\n"), "diff"));
   return 0;
 }
@@ -8292,17 +8887,17 @@ function runLog(opts) {
     return 1;
   }
   if (logResult.exitCode !== 0) {
-    emitErr(`git log failed: ${logResult.stderr}`);
+    emitErr(`git log failed: ${displaySafeText(logResult.stderr)}`);
     return 1;
   }
   if (logResult.stdout.trim() === "") {
-    emit(`No history for '${match.name}' (lines ${match.lineStart}-${match.lineEnd}) in '${toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)}'.`);
+    emit(`No history for '${displaySafeText(match.name)}' (lines ${match.lineStart}-${match.lineEnd}) in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
     return 0;
   }
   if (opts.json === true) {
     const capped = guardJsonRows(parseLogDashLOutput(logResult.stdout));
     emit(
-      JSON.stringify(
+      displaySafeJson(
         {
           symbol: match.name,
           file: match.filePath,
@@ -8311,32 +8906,30 @@ function runLog(opts) {
           commits: capped.items,
           truncated: capped.truncated,
           totalCount: capped.totalCount
-        },
-        null,
-        2
+        }
       )
     );
     return 0;
   }
-  const header = `# ${match.name} (${match.kind}) \u2014 ${toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)}:${match.lineStart}-${match.lineEnd}`;
+  const header = `# ${displaySafeText(match.name)} (${displaySafeText(match.kind)}) \u2014 ${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}:${match.lineStart}-${match.lineEnd}`;
   emit(guardText([header, logResult.stdout].join("\n"), "diff"));
   return 0;
 }
 function foldRealpath(p) {
   const n = normalizePath(p);
-  return process.platform === "win32" ? n.toLowerCase() : n;
+  return process.platform === "win32" ? foldCaseForContainment(n) : n;
 }
 function runGrep(opts) {
-  const searchPaths = opts.path === void 0 ? [opts.projectRoot ?? process.cwd()] : Array.isArray(opts.path) ? opts.path : [opts.path];
+  const anchorSearchPath = (p) => opts.projectRoot === void 0 || path4.isAbsolute(p) ? p : path4.resolve(opts.projectRoot, p);
+  const searchPaths = opts.path === void 0 ? [opts.projectRoot ?? process.cwd()] : (Array.isArray(opts.path) ? opts.path : [opts.path]).map(anchorSearchPath);
   const maxLines = opts.maxLines ?? GREP_MAX_LINES;
   const contextLines = opts.context ?? 0;
-  let regex;
-  try {
-    regex = new RegExp(opts.pattern);
-  } catch {
-    emitErr(`Invalid regex: ${opts.pattern}`);
+  const guarded = compileGuardedRegex(opts.pattern);
+  if (!guarded.ok) {
+    emitErr(`Invalid regex: ${opts.pattern} -- ${guarded.reason}`);
     return 1;
   }
+  const regex = guarded.re;
   const hits = [];
   function searchFile(filePath) {
     try {
@@ -8464,7 +9057,7 @@ function runGrep(opts) {
   }
   if (opts.json === true) {
     const payload = { items: truncated, truncated: hits.length > maxLines, totalCount: hits.length };
-    emit(JSON.stringify(payload, null, 2));
+    emit(displaySafeJson(payload));
     return 0;
   }
   for (const hit of truncated) {
@@ -8472,7 +9065,7 @@ function runGrep(opts) {
     if (hit.context !== void 0) {
       for (const line of renderContextWindow(hit.file, hit.line, hit.context, symbolTag)) emit(line);
     } else {
-      emit(`${hit.file}:${hit.line}: ${hit.text}${symbolTag}`);
+      emit(`${displaySafeText(hit.file)}:${hit.line}: ${hit.text}${symbolTag}`);
     }
   }
   if (hits.length > maxLines) {
@@ -8577,7 +9170,7 @@ function runConfigGet(opts) {
           return 1;
         }
       }
-      emit(JSON.stringify(obj));
+      emit(displaySafeJson(obj, 0));
       return 0;
     } catch {
       emitErr(`Failed to parse JSON: ${opts.file}`);
@@ -8673,7 +9266,7 @@ function runExports(opts) {
     return 1;
   }
   const diskPath = resolveAgainstProjectRoot(opts.file, opts.projectRoot);
-  const symbols = querySymbols({ filePath: resolveIndexPath(diskPath), limit: 500 });
+  const symbols = querySymbols({ filePath: resolveIndexPath(diskPath), limit: -1 });
   const kindOf = (name) => symbols.find((s) => s.name === name)?.kind ?? "export";
   const locOf = (name) => {
     const s = symbols.find((sym) => sym.name === name);
@@ -8698,7 +9291,7 @@ function runExports(opts) {
     for (const n of extractExportNames(text, ext)) if (!names.includes(n)) names.push(n);
   }
   if (names.length === 0) {
-    emit(`No exported symbols found in '${opts.file}'`);
+    emit(`No exported symbols found in '${displaySafeText(opts.file)}'`);
     return 0;
   }
   const preFilterCount = names.length;
@@ -8707,7 +9300,7 @@ function runExports(opts) {
   const fullSourceBytes = sumFileSizes([diskPath]);
   if (filteredNames.length === 0) {
     if (opts.json === true) {
-      const jsonText = JSON.stringify([], null, 2);
+      const jsonText = displaySafeJson([]);
       emit(jsonText);
       recordReadStat("exports", fullSourceBytes, jsonText, opts.file);
       return 0;
@@ -8718,13 +9311,11 @@ function runExports(opts) {
     return 0;
   }
   if (opts.json === true) {
-    const jsonText = JSON.stringify(
+    const jsonText = displaySafeJson(
       filteredNames.map((n) => {
         const loc = locOf(n);
         return { name: n, kind: kindOf(n), lineStart: loc?.lineStart ?? null, lineEnd: loc?.lineEnd ?? null };
-      }),
-      null,
-      2
+      })
     );
     emit(jsonText);
     recordReadStat("exports", fullSourceBytes, jsonText, opts.file);
@@ -8929,6 +9520,27 @@ function extractImports(text, ext) {
       let m;
       while ((m = re.exec(line)) !== null) push(m[1]);
     }
+  } else if (e === ".vb" || e === ".bas" || e === ".vbs") {
+    for (const line of lines) {
+      const m = /^\s*Imports\s+([^'<][^']*)/i.exec(line);
+      if (!m) continue;
+      for (const clause of m[1].split(",")) {
+        const c = clause.trim();
+        if (c === "" || c.startsWith("<")) continue;
+        const alias = /^[A-Za-z_]\w*\s*=\s*([\w.]+(?:\(Of[^)]*\))?)/i.exec(c);
+        push(alias ? alias[1] : (/^[\w.]+/.exec(c) ?? [void 0])[0]);
+      }
+    }
+  } else if (/^\.(?:cbl|cob|cpy|cobol)$/i.test(e)) {
+    for (const imp of extractCobol(text, `imports${e}`).imports) push(imp.target);
+  } else if (/^\.ns[pnsalgch]$/i.test(e)) {
+    for (const imp of extractNatural(text, `imports${e}`).imports) push(imp.target);
+  } else if (STATEMENT_ADAPTER_IMPORTS.has(e)) {
+    for (const imp of STATEMENT_ADAPTER_IMPORTS.get(e)(text, `imports${e}`).imports) push(imp.target);
+  } else if (braceAdapterImportsFor(e, text) !== void 0) {
+    for (const imp of braceAdapterImportsFor(e, text)(text, `imports${e}`).imports) push(imp.target);
+  } else if ((e === ".p" || e === ".w" || e === ".cls") && isAblSource(text)) {
+    for (const imp of extractAbl(text, `imports${e}`).imports) push(imp.target);
   } else if (e === ".lua") {
     for (const line of lines) {
       const re = /\brequire\s*\(?\s*["']([^"']+)["']/g;
@@ -9022,9 +9634,9 @@ function extractImports(text, ext) {
   return found;
 }
 function importsExtensionFor(filePath) {
-  const base = path4.basename(filePath).toLowerCase();
-  if (base === "makefile" || base === "gnumakefile" || base === "bsdmakefile") return ".mk";
-  return path4.extname(filePath);
+  const ext = path4.extname(filePath);
+  if (ext === "" || FILENAME_LANGUAGE.has(path4.basename(filePath).toLowerCase())) return basenameImportsExtension(detectLanguage(filePath)) ?? ext;
+  return ext;
 }
 function runImports(opts) {
   const multiFiles = parseMultiFileSpec(opts.file);
@@ -9037,7 +9649,7 @@ function runImports(opts) {
   }
   const imports = extractImports(text, importsExtensionFor(opts.file));
   if (imports.length === 0) {
-    emit(`No imports found in '${opts.file}'`);
+    emit(`No imports found in '${displaySafeText(opts.file)}'`);
     return 0;
   }
   const preFilterCount = imports.length;
@@ -9046,7 +9658,7 @@ function runImports(opts) {
   const fullSourceBytes = sumFileSizes([diskPath]);
   if (filteredImports.length === 0) {
     if (opts.json === true) {
-      const jsonText = JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2);
+      const jsonText = displaySafeJson({ items: [], truncated: false, totalCount: 0 });
       emit(jsonText);
       recordReadStat("imports", fullSourceBytes, jsonText, opts.file);
       return 0;
@@ -9058,7 +9670,7 @@ function runImports(opts) {
   }
   if (opts.json === true) {
     const capped = guardJsonRows(filteredImports);
-    const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, null, 2);
+    const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
     emit(jsonText);
     recordReadStat("imports", fullSourceBytes, jsonText, opts.file);
     return 0;
@@ -9110,7 +9722,7 @@ async function runSemantic(query, opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
     const message = `--limit must be a positive number, got: ${opts.limit}`;
     if (opts.json === true) {
-      return { text: JSON.stringify({ error: message }, null, 2), code: 1 };
+      return { text: displaySafeJson({ error: message }), code: 1 };
     }
     return { text: message, code: 1 };
   }
@@ -9119,32 +9731,39 @@ async function runSemantic(query, opts) {
     if (!path4.isAbsolute(opts.projectRoot) || !fs4.existsSync(opts.projectRoot) || !fs4.statSync(opts.projectRoot).isDirectory()) {
       const message = `token-goat: projectRoot must be an absolute, existing directory, got '${opts.projectRoot}'`;
       if (opts.json === true) {
-        return { text: JSON.stringify({ error: message }, null, 2), code: 1 };
+        return { text: displaySafeJson({ error: message }), code: 1 };
       }
       return { text: message, code: 1 };
     }
   }
   const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
-  if (!isAvailable()) {
+  const embeddingsEnabled = loadConfig().indexing?.embeddings_enabled ?? true;
+  if (embeddingsEnabled && !isAvailable()) {
     console.warn(
       "Matching on meaning is off (onnxruntime-node is not installed); these results come from keyword search alone. Install it with: npm install -g onnxruntime-node (drop -g if token-goat is a project dependency)"
     );
+  } else if (!embeddingsEnabled) {
+    console.warn(
+      "Matching on meaning is off (indexing.embeddings_enabled / TOKEN_GOAT_EMBEDDINGS_ENABLED is disabled); these results come from keyword search alone."
+    );
   }
   const overFetchForMerge = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
   let rawHits = [];
-  try {
-    rawHits = await searchSemantic(
-      getDb(globalDbPath()),
-      query,
-      overFetchForMerge,
-      void 0,
-      void 0,
-      rootDir
-    );
-  } catch (e) {
-    console.warn(
-      `Matching on meaning is off (${extractErrorMessage(e)}); these results come from keyword search alone.`
-    );
+  if (embeddingsEnabled) {
+    try {
+      rawHits = await searchSemantic(
+        getDb(globalDbPath()),
+        query,
+        overFetchForMerge,
+        void 0,
+        void 0,
+        rootDir
+      );
+    } catch (e) {
+      console.warn(
+        `Matching on meaning is off (${extractErrorMessage(e)}); these results come from keyword search alone.`
+      );
+    }
   }
   if (rawHits.length === 0 && isAvailable()) {
     try {
@@ -9164,7 +9783,7 @@ async function runSemantic(query, opts) {
   const fused = /* @__PURE__ */ new Map();
   mergedHits.forEach((h, denseRank) => {
     const enclosing = resolveEnclosingSymbol(h.filePath, h.startLine);
-    const key = enclosing !== null ? `${h.filePath}::${enclosing.name}` : `${h.filePath}::L${h.startLine}`;
+    const key = enclosing !== null ? `${h.filePath}::${enclosing.name}@${enclosing.lineStart}` : `${h.filePath}::L${h.startLine}`;
     fused.set(key, {
       filePath: h.filePath,
       startLine: h.startLine,
@@ -9177,7 +9796,7 @@ async function runSemantic(query, opts) {
     });
   });
   ftsRows.forEach((s, ftsRank) => {
-    const key = `${s.filePath}::${s.name}`;
+    const key = `${s.filePath}::${s.name}@${s.lineStart}`;
     const existing = fused.get(key);
     if (existing !== void 0) {
       existing.rrf += 1 / (RRF_K + ftsRank);
@@ -9210,6 +9829,7 @@ async function runSemantic(query, opts) {
   const hadDense = mergedHits.length > 0;
   const hadFts = ftsRows.length > 0;
   const source = hadDense && hadFts ? "hybrid" : hadDense ? "embeddings" : "fts";
+  warnIfFilesStale(hits.map((h) => h.filePath));
   if (hits.length > 0) {
     if (opts.json === true) {
       const items = hits.map((h) => ({
@@ -9223,7 +9843,7 @@ async function runSemantic(query, opts) {
       }));
       const capped = guardJsonRows(items);
       const limitTruncated = hits.length < eligibleCount;
-      const text3 = JSON.stringify({ source, ...capped, truncated: capped.truncated || limitTruncated, totalCount: eligibleCount, ...candidatesClipped ? { totalCountIsFloor: true } : {} }, null, 2);
+      const text3 = displaySafeJson({ source, ...capped, truncated: capped.truncated || limitTruncated, totalCount: eligibleCount, ...candidatesClipped ? { totalCountIsFloor: true } : {} });
       recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text3, query);
       return { text: text3, code: 0 };
     }
@@ -9247,7 +9867,7 @@ ${previewLines(h.previewText, 3)}`;
     const notice = grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "match", "matches");
     if (opts.json === true) {
       const payload = { source: "fts", items: [], truncated: false, totalCount: 0, grepFilteredToEmpty: true, hint: notice.trim() };
-      return { text: JSON.stringify(payload, null, 2), code: 0 };
+      return { text: displaySafeJson(payload), code: 0 };
     }
     return { text: `token-goat: ${notice.trim()}`, code: 0 };
   }
@@ -9255,7 +9875,7 @@ ${previewLines(h.previewText, 3)}`;
     const notice = `no non-test matches for '${query}' (${excludeTestsHiddenNote(suppressedTotal)})`;
     if (opts.json === true) {
       const payload = { source: "fts", items: [], truncated: false, totalCount: 0, excludeTestsFilteredToEmpty: true, hint: notice };
-      return { text: JSON.stringify(payload, null, 2), code: 0 };
+      return { text: displaySafeJson(payload), code: 0 };
     }
     return { text: `token-goat: ${notice}`, code: 0 };
   }
@@ -9271,7 +9891,7 @@ ${previewLines(h.previewText, 3)}`;
           cachedAt: entry.createdAt
         }));
         const capped = guardJsonRows(items);
-        const text3 = JSON.stringify({ source: "workspace-evidence", ...capped }, null, 2);
+        const text3 = displaySafeJson({ source: "workspace-evidence", ...capped });
         recordReadStat("semantic_search", evidenceFullBytes, text3, query);
         return { text: text3, code: 0 };
       }
@@ -9287,7 +9907,7 @@ ${previewLines(entry.text, 3)}`).join("\n\n"),
   const indexEmpty = isIndexEmptyForProject(globalDbPath(), rootDir);
   if (opts.json === true) {
     const payload = indexEmpty ? { source: "fts", items: [], truncated: false, totalCount: 0, indexEmpty: true, hint: emptyIndexMessage(rootDir) } : { source: "fts", items: [], truncated: false, totalCount: 0 };
-    const text2 = JSON.stringify(payload, null, 2);
+    const text2 = displaySafeJson(payload);
     return { text: text2, code: 1 };
   }
   const text = indexEmpty ? `token-goat: no matches for '${query}'
@@ -9313,7 +9933,7 @@ function runNoteGet(opts) {
       createdAt: note.createdAt,
       updatedAt: note.updatedAt
     };
-    const text2 = JSON.stringify(payload, null, 2);
+    const text2 = displaySafeJson(payload);
     recordStat("note_read");
     return { text: text2, code: 0 };
   }
@@ -9335,7 +9955,7 @@ function runNoteList(opts = {}) {
       updatedAt: note.updatedAt
     }));
     recordStat("note_list");
-    return { text: JSON.stringify(items, null, 2), code: 0 };
+    return { text: displaySafeJson(items), code: 0 };
   }
   recordStat("note_list");
   if (filtered.length === 0) {
@@ -9670,7 +10290,7 @@ function renderModules(result, top) {
 
 // src/graph_commands.ts
 var DEFAULT_REF_QUERY_LIMIT = 500;
-var ALL_SYMBOLS_IN_FILE_LIMIT = 1e4;
+var ALL_SYMBOLS_IN_FILE_LIMIT = -1;
 var UNBOUNDED_REF_LIMIT = -1;
 function emit2(text) {
   const payload = colorStdout() ? text : stripAnsi(text);
@@ -9818,7 +10438,7 @@ function runCallers(opts) {
   if (entries.length === 0) {
     if (matchesGrep !== void 0 && preGrepCount > 0) {
       if (opts.json === true) {
-        emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preGrepCount }, null, 2));
+        emit2(displaySafeJson({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preGrepCount }));
         return 0;
       }
       emit2(grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "caller", "callers"));
@@ -9826,7 +10446,7 @@ function runCallers(opts) {
     }
     if (opts.excludeTests === true && suppressed > 0) {
       if (opts.json === true) {
-        emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByExcludeTests: suppressed }, null, 2));
+        emit2(displaySafeJson({ items: [], truncated: false, totalCount: 0, hiddenByExcludeTests: suppressed }));
         return 1;
       }
       emitErr2(`No non-test references found for '${opts.symbol}' (${excludeTestsHiddenNote(suppressed)})`);
@@ -9841,7 +10461,7 @@ function runCallers(opts) {
     const defPaths = fileHint !== void 0 ? [fileHint] : defRows.map((r) => r.filePath);
     const firstDefPath = defPaths[0];
     if (firstDefPath !== void 0 && defPaths.every((fp) => !isRefIndexedFile(fp))) {
-      emitErr2(refBlindLanguageNotice(name, detectLanguage(firstDefPath), toDisplayPath(rootDir, firstDefPath)));
+      emitErr2(refBlindLanguageNotice(name, detectLanguageOfFile(firstDefPath), toDisplayPath(rootDir, firstDefPath)));
       return 1;
     }
     const kindRows = fileHint !== void 0 ? querySymbols({ name, filePath: fileHint, limit: REF_BLIND_DEF_PROBE_LIMIT }) : defRows;
@@ -9865,7 +10485,7 @@ function runCallers(opts) {
     const capped = guardJsonRows(rows);
     const limitTruncated = entries.length < filtered.length || sqlTruncated;
     const hiddenByGrep = preGrepCount - filtered.length;
-    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || limitTruncated, totalCount: filtered.length, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...opts.excludeTests === true && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
+    emit2(displaySafeJson({ items: capped.items, truncated: capped.truncated || limitTruncated, totalCount: filtered.length, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...opts.excludeTests === true && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }));
     return 0;
   }
   if (opts.excludeTests === true && suppressed > 0) {
@@ -9933,8 +10553,8 @@ function runCallChain(opts) {
     const hiddenByExcludeTests = noCallers && opts.excludeTests === true ? suppressedCount : 0;
     const refBlindKinds = noCallers ? refBlindRootKinds().blindKinds : [];
     const blindRootPath = noCallers ? refBlindRootPath() : void 0;
-    const refBlindLanguage = blindRootPath !== void 0 ? { language: detectLanguage(blindRootPath), definedIn: toDisplayPath(rootDir, blindRootPath) } : void 0;
-    emit2(JSON.stringify({ chains: filteredChains, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...hiddenByExcludeTests > 0 ? { hiddenByExcludeTests } : {}, ...refBlindKinds.length > 0 ? { refBlindKinds } : {}, ...refBlindLanguage !== void 0 ? { refBlindLanguage } : {} }, null, 2));
+    const refBlindLanguage = blindRootPath !== void 0 ? { language: detectLanguageOfFile(blindRootPath), definedIn: toDisplayPath(rootDir, blindRootPath) } : void 0;
+    emit2(displaySafeJson({ chains: filteredChains, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...hiddenByExcludeTests > 0 ? { hiddenByExcludeTests } : {}, ...refBlindKinds.length > 0 ? { refBlindKinds } : {}, ...refBlindLanguage !== void 0 ? { refBlindLanguage } : {} }));
     return 0;
   }
   if (noCallers) {
@@ -9944,7 +10564,7 @@ function runCallChain(opts) {
     }
     const blindRoot = refBlindRootPath();
     if (blindRoot !== void 0) {
-      emitErr2(refBlindLanguageNotice(name, detectLanguage(blindRoot), toDisplayPath(rootDir, blindRoot)));
+      emitErr2(refBlindLanguageNotice(name, detectLanguageOfFile(blindRoot), toDisplayPath(rootDir, blindRoot)));
       emit2(`${name}  (no callers recorded)`);
       return 0;
     }
@@ -10035,7 +10655,7 @@ function runImpact(opts) {
   if (matchesGrep !== void 0 && sorted.length === 0 && allSorted.length > 0) {
     if (opts.json === true) {
       emitErr2(grepFilteredToEmptyNotice(allSorted.length, opts.grep, "impacted symbol", "impacted symbols"));
-      emit2(JSON.stringify([], null, 2));
+      emit2(displaySafeJson([]));
       return 0;
     }
     emit2(grepFilteredToEmptyNotice(allSorted.length, opts.grep, "impacted symbol", "impacted symbols"));
@@ -10044,7 +10664,7 @@ function runImpact(opts) {
   if (sorted.length === 0) {
     if (opts.excludeTests === true && suppressedCount > 0) {
       if (opts.json === true) {
-        emit2(JSON.stringify([], null, 2));
+        emit2(displaySafeJson([]));
         return 1;
       }
       emitErr2(`No non-test impact found for '${opts.symbol}' (${excludeTestsHiddenNote(suppressedCount)})`);
@@ -10058,7 +10678,7 @@ function runImpact(opts) {
     const defPaths = fileHint !== void 0 ? [fileHint] : defRows.map((r) => r.filePath);
     const firstDefPath = defPaths[0];
     if (firstDefPath !== void 0 && defPaths.every((fp) => !isRefIndexedFile(fp))) {
-      emitErr2(refBlindLanguageNotice(rootName, detectLanguage(firstDefPath), toDisplayPath(rootDir, firstDefPath)));
+      emitErr2(refBlindLanguageNotice(rootName, detectLanguageOfFile(firstDefPath), toDisplayPath(rootDir, firstDefPath)));
       return 1;
     }
     const kindRows = fileHint !== void 0 ? querySymbols({ name: rootName, filePath: fileHint, limit: REF_BLIND_DEF_PROBE_LIMIT }) : defRows;
@@ -10072,7 +10692,7 @@ function runImpact(opts) {
     return 1;
   }
   if (opts.json === true) {
-    emit2(JSON.stringify(sorted.map(([symbol, h]) => ({ symbol, hops: h })), null, 2));
+    emit2(displaySafeJson(sorted.map(([symbol, h]) => ({ symbol, hops: h }))));
     return 0;
   }
   const MODULE_SCOPE_PREFIX = "(module scope) ";
@@ -10229,7 +10849,7 @@ function runDead(opts) {
     }));
     const topTruncated = sliced.length < grepped.length;
     const hiddenByGrep = preGrepCount - grepped.length;
-    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || topTruncated, totalCount: grepped.length, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...opts.excludeTests === true && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {}, ...blindKinds.length > 0 ? { excludedKinds: blindKinds, excludedKindsReason: REF_BLIND_KIND_REASON } : {}, ...refBlindByLanguage > 0 ? { unassessableByLanguage: refBlindByLanguage } : {} }, null, 2));
+    emit2(displaySafeJson({ items: capped.items, truncated: capped.truncated || topTruncated, totalCount: grepped.length, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...opts.excludeTests === true && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {}, ...blindKinds.length > 0 ? { excludedKinds: blindKinds, excludedKindsReason: REF_BLIND_KIND_REASON } : {}, ...refBlindByLanguage > 0 ? { unassessableByLanguage: refBlindByLanguage } : {} }));
     return 0;
   }
   if (sliced.length === 0) {
@@ -10249,7 +10869,7 @@ function runDead(opts) {
     emit2(`${countNoun(sliced.length, "dead symbol")} (${excludeTestsHiddenNote(suppressed)})`);
   }
   for (const r of sliced) {
-    emit2(`${r.name}	${toDisplayPath(rootDir, r.file)}:${r.line}`);
+    emit2(`${displaySafeText(r.name)}	${displaySafeText(toDisplayPath(rootDir, r.file))}:${r.line}`);
   }
   return 0;
 }
@@ -10326,7 +10946,7 @@ function runDeps(opts) {
   const filteredExternal = matchesGrep !== void 0 ? external.filter((e) => matchesGrep(e)) : external;
   if (opts.json === true) {
     const hiddenByGrep = preFilterCount - (filteredInternal.length + filteredExternal.length);
-    emit2(JSON.stringify({ file: toDisplayPath(rootDir, normalizePath(opts.file)), internal: filteredInternal, external: filteredExternal, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} }, null, 2));
+    emit2(displaySafeJson({ file: toDisplayPath(rootDir, normalizePath(opts.file)), internal: filteredInternal, external: filteredExternal, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} }));
     return 0;
   }
   if (matchesGrep !== void 0 && preFilterCount > 0 && filteredInternal.length === 0 && filteredExternal.length === 0) {
@@ -10436,7 +11056,7 @@ function refBlindKindVerdict(rows) {
 var CORE_SYMBOL_KINDS = [
   .../* @__PURE__ */ new Set([...GENERIC_SYMBOL_KINDS, ...TYPE_KINDS, ...OTHER_ADAPTER_SYMBOL_KINDS])
 ];
-var TYPES_SCAN_LIMIT = 5e3;
+var TYPES_SCAN_LIMIT = -1;
 function runTypes(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
     emitErr2(`--limit must be a positive number, got: ${opts.limit}`);
@@ -10482,7 +11102,7 @@ function runTypes(opts) {
     const ctx = opts.file !== void 0 ? ` in '${opts.file}'` : "";
     if (excludeTests && suppressed > 0) {
       if (opts.json === true) {
-        emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByExcludeTests: suppressed }, null, 2));
+        emit2(displaySafeJson({ items: [], truncated: false, totalCount: 0, hiddenByExcludeTests: suppressed }));
         return 0;
       }
       emit2(`No non-test type declarations found${ctx} (${excludeTestsHiddenNote(suppressed)})`);
@@ -10506,7 +11126,7 @@ function runTypes(opts) {
   const cappedOut = eligibleCount - filtered.length;
   if (filtered.length === 0) {
     if (opts.json === true) {
-      emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preFilterCount }, null, 2));
+      emit2(displaySafeJson({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preFilterCount }));
       return 0;
     }
     emit2(grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "type declaration", "type declarations"));
@@ -10515,14 +11135,14 @@ function runTypes(opts) {
   if (opts.json === true) {
     const capped = guardJsonRows(filtered.map((r) => ({ ...r, filePath: toDisplayPath(rootDir, r.filePath) })));
     const hiddenByGrep = preFilterCount - eligibleCount;
-    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || cappedOut > 0, totalCount: eligibleCount, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...excludeTests && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
+    emit2(displaySafeJson({ items: capped.items, truncated: capped.truncated || cappedOut > 0, totalCount: eligibleCount, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...excludeTests && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }));
     return 0;
   }
   if (excludeTests && suppressed > 0) {
     emit2(`${countNoun(filtered.length, "type declaration")} (${excludeTestsHiddenNote(suppressed)})`);
   }
   for (const r of filtered) {
-    emit2(`${r.name}	${r.kind}	${toDisplayPath(rootDir, r.filePath)}:${r.lineStart}`);
+    emit2(`${displaySafeText(r.name)}	${displaySafeText(r.kind)}	${displaySafeText(toDisplayPath(rootDir, r.filePath))}:${r.lineStart}`);
   }
   if (cappedOut > 0) {
     emitErr2(`Showing ${filtered.length} of ${eligibleCount} type declarations (--limit is per kind; raise it to see the rest).`);
@@ -10560,7 +11180,7 @@ function runScope(opts) {
         return 1;
       }
       emitErr2(
-        `No indexed symbols in '${file}' \u2014 the file exists but nothing is indexed for it, so every line looks empty`
+        symbolExtractorGap(file, filePath) ?? `No indexed symbols in '${file}' \u2014 the file exists but nothing is indexed for it, so every line looks empty`
       );
       return 1;
     }
@@ -10570,16 +11190,14 @@ function runScope(opts) {
   const scopeDisplayRoot = getDisplayRoot();
   if (opts.json === true) {
     emit2(
-      JSON.stringify(
-        enclosing.map((s) => ({ ...s, filePath: toDisplayPath(scopeDisplayRoot, s.filePath) })),
-        null,
-        2
+      displaySafeJson(
+        enclosing.map((s) => ({ ...s, filePath: toDisplayPath(scopeDisplayRoot, s.filePath) }))
       )
     );
     return 0;
   }
   for (const s of enclosing) {
-    emit2(`${s.name}	${s.kind}	${toDisplayPath(scopeDisplayRoot, s.filePath)}:${s.lineStart}-${s.lineEnd}`);
+    emit2(`${displaySafeText(s.name)}	${displaySafeText(s.kind)}	${displaySafeText(toDisplayPath(scopeDisplayRoot, s.filePath))}:${s.lineStart}-${s.lineEnd}`);
   }
   return 0;
 }
@@ -10709,10 +11327,10 @@ function runSimilar(opts) {
     emitErr2(`Showing top ${results.length} of ${matches.length} similar symbols (raise --top to see the rest).`);
   }
   if (opts.json === true) {
-    emit2(JSON.stringify(results.map((h) => ({ name: h.name, kind: h.kind, file: h.filePath, line: h.lineStart })), null, 2));
+    emit2(displaySafeJson(results.map((h) => ({ name: h.name, kind: h.kind, file: h.filePath, line: h.lineStart }))));
     return 0;
   }
-  for (const h of results) emit2(`${h.name}	${h.kind}	${toDisplayPath(rootDir, h.filePath)}:${h.lineStart}`);
+  for (const h of results) emit2(`${displaySafeText(h.name)}	${displaySafeText(h.kind)}	${displaySafeText(toDisplayPath(rootDir, h.filePath))}:${h.lineStart}`);
   return 0;
 }
 function runContextFor(opts) {
@@ -10748,10 +11366,10 @@ function runContextFor(opts) {
   if (moreBeyondTop) notices.push(`More matches exist beyond --top ${top} (raise it to see them).`);
   for (const n of notices) emitErr2(n);
   if (opts.json === true) {
-    emit2(JSON.stringify(entries, null, 2));
+    emit2(displaySafeJson(entries));
     return 0;
   }
-  for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}@${e.line}"`);
+  for (const e of entries) emit2(`token-goat read "${displaySafeText(toDisplayPath(rootDir, e.file))}::${displaySafeText(e.symbol)}@${e.line}"`);
   return 0;
 }
 function runTestFor(opts) {
@@ -10783,11 +11401,11 @@ function runTestFor(opts) {
   }
   if (opts.json === true) {
     const capped = guardJsonRows(results.map((r) => ({ ...r, testFile: toDisplayPath(rootDir, r.testFile) })));
-    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }, null, 2));
+    emit2(displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }));
     return 0;
   }
   if (results.length === 0) {
-    emit2(`No test files found referencing symbols in '${opts.file}'`);
+    emit2(`No test files found referencing symbols in '${displaySafeText(opts.file)}'`);
     return 0;
   }
   for (const r of results) {
@@ -10819,7 +11437,7 @@ function runCoverageGaps(opts) {
     emitErr2(`Showing top ${sliced.length} of ${gaps.length} coverage gaps (raise --top to see the rest).`);
   }
   if (opts.json === true) {
-    emit2(JSON.stringify(sliced, null, 2));
+    emit2(displaySafeJson(sliced));
     return 0;
   }
   if (sliced.length === 0) {
@@ -10827,7 +11445,7 @@ function runCoverageGaps(opts) {
     if (isIndexEmptyForProject(globalDbPath(), rootDir)) emit2(emptyIndexMessage(rootDir));
     return 0;
   }
-  for (const g of sliced) emit2(`${g.name}	${g.kind}	${toDisplayPath(rootDir, g.file)}:${g.line}`);
+  for (const g of sliced) emit2(`${displaySafeText(g.name)}	${displaySafeText(g.kind)}	${displaySafeText(toDisplayPath(rootDir, g.file))}:${g.line}`);
   return 0;
 }
 function runArch(opts) {
@@ -10852,13 +11470,13 @@ function runArch(opts) {
   const moduleResult = opts.modules === true ? detectModules({ files, graph, importedBy, resolve: resolve5 }, cwd, top) : null;
   if (opts.json === true) {
     const modulePayload = moduleResult === null ? {} : { modules: moduleResult.modules, modulesTotal: moduleResult.modulesTotal, modulesTruncated: moduleResult.modules.length < moduleResult.modulesTotal, modularity: moduleResult.modularity, isolatedCount: moduleResult.isolatedCount, crossImports: moduleResult.crossImports, crossImportsTotal: moduleResult.crossImportsTotal, crossImportsTruncated: moduleResult.crossImports.length < moduleResult.crossImportsTotal, noImportEdges: moduleResult.noEdges };
-    emit2(JSON.stringify({ hubs, hubsTotal, hubsTruncated: hubs.length < hubsTotal, entryPoints, entryPointsTotal, entryPointsTruncated: entryPoints.length < entryPointsTotal, cycles, ...cyclesTruncated ? { cyclesTruncated: true } : {}, ...modulePayload }, null, 2));
+    emit2(displaySafeJson({ hubs, hubsTotal, hubsTruncated: hubs.length < hubsTotal, entryPoints, entryPointsTotal, entryPointsTruncated: entryPoints.length < entryPointsTotal, cycles, ...cyclesTruncated ? { cyclesTruncated: true } : {}, ...modulePayload }));
     return 0;
   }
   emit2(hubs.length < hubsTotal ? `hubs (top ${hubs.length} of ${hubsTotal} most-imported):` : `hubs (${hubsTotal} most-imported):`);
-  for (const h of hubs) emit2(`  ${h.importedBy} importers	${toDisplayPath(getDisplayRoot(opts.cwd), h.file)}`);
+  for (const h of hubs) emit2(`  ${h.importedBy} importers	${displaySafeText(toDisplayPath(getDisplayRoot(opts.cwd), h.file))}`);
   emit2(entryPoints.length < entryPointsTotal ? `entry points (imported by nobody, top ${entryPoints.length} of ${entryPointsTotal}):` : `entry points (imported by nobody, ${entryPointsTotal} found):`);
-  for (const e of entryPoints) emit2(`  ${toDisplayPath(getDisplayRoot(opts.cwd), e.file)}`);
+  for (const e of entryPoints) emit2(`  ${displaySafeText(toDisplayPath(getDisplayRoot(opts.cwd), e.file))}`);
   emit2(cyclesTruncated ? `cycles (first ${cycles.length}, truncated at the ${MAX_CYCLES}-cycle enumeration limit: more cycles exist):` : `cycles (${cycles.length} found):`);
   for (const c of cycles) emit2(`  ${c.map((f) => toDisplayPath(getDisplayRoot(opts.cwd), f)).join(" -> ")}`);
   if (moduleResult !== null) for (const line of renderModules(moduleResult, top)) emit2(line);
@@ -10867,7 +11485,7 @@ function runArch(opts) {
 function runBlame(opts) {
   const sepIdx = opts.spec.lastIndexOf("::");
   if (sepIdx < 0) {
-    emitErr2(`Invalid spec - expected "file::symbol", got: ${opts.spec}`);
+    emitErr2(`Invalid spec - expected "file::symbol", got: ${displaySafeText(opts.spec)}`);
     return 1;
   }
   const cwd = opts.cwd ?? process.cwd();
@@ -10880,7 +11498,7 @@ function runBlame(opts) {
   try {
     const result = runGit(["blame", "-L", `${start},${end}`, "--", filePath], { cwd });
     if (result.exitCode !== 0) {
-      emitErr2(`git blame failed: ${result.stderr}`);
+      emitErr2(`git blame failed: ${displaySafeText(result.stderr)}`);
       return 1;
     }
     raw = result.stdout;
@@ -10894,11 +11512,11 @@ function runBlame(opts) {
       if (!m) return { raw: l };
       return { commit: m[2], boundary: m[1] === "^", author: (m[3] ?? "").trim(), date: (m[4] ?? "").trim(), line: Number.parseInt(m[5] ?? "0", 10), content: m[6] };
     });
-    emit2(JSON.stringify({ symbol: sym.name, file: filePath, lines }, null, 2));
+    emit2(displaySafeJson({ symbol: sym.name, file: filePath, lines }));
     return 0;
   }
-  emit2(`${sym.name}	${toDisplayPath(getDisplayRoot(opts.cwd), filePath)}:${start}-${end}`);
-  emit2(raw.trim());
+  emit2(`${displaySafeText(sym.name)}	${displaySafeText(toDisplayPath(getDisplayRoot(opts.cwd), filePath))}:${start}-${end}`);
+  emit2(fenceUntrusted(raw.trim(), UNTRUSTED_FILE_TAG));
   return 0;
 }
 function runAsk(opts) {
@@ -10914,17 +11532,18 @@ function runAsk(opts) {
   if (moreBeyondTop) {
     emitErr2(`Answer is grounded in the top ${countNoun(top, "match", "matches")}; more matched (raise --top to widen the evidence).`);
   }
+  warnIfFilesStale(hits.map((h) => h.filePath));
   const BACKEND_ENV = "TOKEN_GOAT_ASK_BACKEND";
   const backendLabel = process.env[BACKEND_ENV] ?? "";
   const entries = hits.map((h) => ({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` }));
   const degrade = (reason, extraNote) => {
     if (opts.json === true) {
-      emit2(JSON.stringify({ degraded: true, note: reason, ...extraNote !== void 0 ? { hint: extraNote } : {}, context: entries }, null, 2));
+      emit2(displaySafeJson({ degraded: true, note: reason, ...extraNote !== void 0 ? { hint: extraNote } : {}, context: entries }));
       return 0;
     }
     emit2(`[degraded mode - ${reason}]`);
     if (extraNote !== void 0) emit2(extraNote);
-    for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}@${e.line}"`);
+    for (const e of entries) emit2(`token-goat read "${displaySafeText(toDisplayPath(rootDir, e.file))}::${displaySafeText(e.symbol)}@${e.line}"`);
     return 0;
   };
   if (!backendLabel) return degrade(`set ${BACKEND_ENV}=claude|codex for LLM synthesis`);
@@ -10971,7 +11590,7 @@ ANSWER:`;
     }
     if (answer) {
       if (opts.json === true) {
-        emit2(JSON.stringify({ answer, context: entries }, null, 2));
+        emit2(displaySafeJson({ answer, context: entries }));
       } else {
         emit2(answer);
       }
@@ -11113,9 +11732,8 @@ function resolveHandoff(name, opts = {}) {
 }
 
 export {
-  extractSection,
-  readSection,
-  listSections,
+  isAvailable2 as isAvailable,
+  loadError,
   buildImportGraph,
   ALL_SYMBOLS_IN_FILE_LIMIT,
   enclosingSymbol,
@@ -11139,8 +11757,6 @@ export {
   symbolNamesInFile,
   computeFileFingerprint,
   upsertNote,
-  isAvailable2 as isAvailable,
-  loadError,
   AMBIGUOUS_HEADING_LIMIT,
   ConfinementIdentityError,
   ABSENT_PIN,
@@ -11149,6 +11765,7 @@ export {
   withPinnedReads,
   resolveBody,
   healStaleIndex,
+  warnIfFilesStale,
   findSpecSeparator,
   rankSimilarNames,
   filterSimilarHeadings,
@@ -11169,6 +11786,9 @@ export {
   runYamlQuery,
   runXmlOutline,
   runXmlQuery,
+  runHtmlOutline,
+  runHtmlQuery,
+  runHtmlLint,
   runOpenApiOutline,
   runOpenApiOp,
   runZipList,