token-goat 2.9.14 → 2.9.15

package/dist/{token-goat-chunk-RUDOKYPJ.mjs → token-goat-chunk-LCZBPOIN.mjs}

@@ -1,56 +1,44 @@
 import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
+import {
+  formatSqliteQueryTable,
+  formatSqliteSchema,
+  formatSqliteTables,
+  getSqliteSchema,
+  getSqliteTables,
+  runReadOnlySqliteQuery
+} from "./token-goat-chunk-LMFO66YD.mjs";
 import {
   ImageDecodeError,
-  MAX_OVER_FETCH,
   NOTEBOOK_CELL_LINES_SUFFIX,
-  OVER_FETCH_FACTOR,
   SKIP_DIRS,
+  canShrinkFormat,
   emptyIndexMessage,
   enqueueDirtyPathSafe,
   fenceUntrusted,
-  findContainingSection,
   formatSymbolLocation,
   getEmbeddingCoverage,
   getTrackedFiles,
-  indexFileSync,
   indexedSourceText,
-  isAvailable,
   isImagePath,
   isIndexEmptyForProject,
   isPrivateIpv4Octets,
   isPrivateIpv6Groups,
-  isTreeSitterAvailable,
   isVirtualIndexedPath,
-  listSections,
-  mergeNearbyHits,
   parseIpv6Groups,
   probeImageMeta,
-  readSection,
   scanAndRecord,
   searchEvidenceSemantically,
-  searchSemantic,
   shrinkImage,
   urlPolicyDenialReason,
   virtualIndexedScopeNote,
   walkProject
-} from "./token-goat-chunk-IT6O3PNN.mjs";
+} from "./token-goat-chunk-BL5LNGBG.mjs";
 import {
-  DEFAULT_QUERY_LIMIT,
   capJsonRows,
-  countRefs,
-  countSymbols,
-  distinctSymbolKinds,
   estimateTokens,
-  getFileEntry,
-  pathEqClause,
-  queryRefCounts,
-  queryRefs,
-  queryRefsByContext,
-  querySymbols,
-  searchSymbolsFts,
   trimToBudget
-} from "./token-goat-chunk-VZYD4OZB.mjs";
+} from "./token-goat-chunk-YQ7WI2CO.mjs";
 import {
   extractPdfMeta,
   extractPdfOutline,
@@ -64,7 +52,7 @@ import {
   parseWhereSpecs,
   profileCsv,
   queryCsv
-} from "./token-goat-chunk-EG3663UT.mjs";
+} from "./token-goat-chunk-YKG35VHC.mjs";
 import {
   MAX_ZIP_INPUT_BYTES,
   MAX_ZIP_OUTPUT_BYTES,
@@ -75,46 +63,6 @@ import {
 import {
   createLazyModuleLoader
 } from "./token-goat-chunk-AH6QILZM.mjs";
-import {
-  isOcrEngineAvailable,
-  isTextHeavy,
-  ocrImage,
-  ocrIntegrityFailed
-} from "./token-goat-chunk-DBNY4RLN.mjs";
-import {
-  Database,
-  FILENAME_LANGUAGE,
-  TREE_SITTER_LANGUAGES,
-  basenameImportsExtension,
-  colorStdout,
-  detectLanguage,
-  detectLanguageOfFile,
-  getDb,
-  isBlobStale,
-  languageLabel,
-  loadBlob,
-  partialRefsReason,
-  recordStat,
-  redactIfDotenv,
-  redactSecrets,
-  savedTokensFromBytes,
-  storeBlob,
-  stripAnsi,
-  unsupportedLanguageName
-} from "./token-goat-chunk-T2IWWTHB.mjs";
-import {
-  fileIsAbsent,
-  findProject,
-  fingerprintContent,
-  fingerprintFile,
-  getDisplayRoot,
-  loadConfig,
-  resolveProjectRoot,
-  shortFingerprint
-} from "./token-goat-chunk-SAQ5PG4L.mjs";
-import {
-  registerReset
-} from "./token-goat-chunk-EEIDFMEM.mjs";
 import {
   IMPORT_RE,
   extractAbap,
@@ -139,34 +87,92 @@ import {
   extractSolidity,
   extractThrift,
   stripLeadingAttributes
-} from "./token-goat-chunk-HF6H7RNK.mjs";
+} from "./token-goat-chunk-XEPXYDPI.mjs";
+import {
+  MAX_OVER_FETCH,
+  OVER_FETCH_FACTOR,
+  checkEmbeddingPreflight,
+  findContainingSection,
+  indexFileSync,
+  isAvailable,
+  isTreeSitterAvailable,
+  listSections,
+  mergeNearbyHits,
+  readSection,
+  searchSemantic
+} from "./token-goat-chunk-NDRP4KJQ.mjs";
+import {
+  DEFAULT_QUERY_LIMIT,
+  countRefs,
+  countSymbols,
+  distinctSymbolKinds,
+  getFileEntry,
+  pathEqClause,
+  queryRefCounts,
+  queryRefs,
+  queryRefsByContext,
+  querySymbols,
+  searchSymbolsFts
+} from "./token-goat-chunk-2X2EBBC6.mjs";
+import {
+  isOcrEngineAvailable,
+  isTextHeavy,
+  ocrImage,
+  ocrIntegrityFailed
+} from "./token-goat-chunk-SFAS46RE.mjs";
+import {
+  colorStdout,
+  isBlobStale,
+  loadBlob,
+  recordStat,
+  redactSecrets,
+  savedTokensFromBytes,
+  storeBlob,
+  stripAnsi
+} from "./token-goat-chunk-IVUQLQWN.mjs";
 import {
+  FILENAME_LANGUAGE,
+  TREE_SITTER_LANGUAGES,
+  basenameImportsExtension,
+  detectLanguage,
+  detectLanguageOfFile,
+  getDb,
   isAblSource,
   isMatlabSource,
   isObjcHeader,
   isObjcSource,
   isPascalSource,
   isPerlSource,
-  isPrologSource
-} from "./token-goat-chunk-POBYR64E.mjs";
+  isPrologSource,
+  languageLabel,
+  partialRefsReason,
+  redactIfDotenv,
+  unsupportedLanguageName
+} from "./token-goat-chunk-K7F2BFIK.mjs";
+import {
+  fileIsAbsent,
+  findProject,
+  fingerprintContent,
+  fingerprintFile,
+  getDisplayRoot,
+  loadConfig,
+  resolveProjectRoot,
+  shortFingerprint
+} from "./token-goat-chunk-S4XRY446.mjs";
+import {
+  registerReset
+} from "./token-goat-chunk-EEIDFMEM.mjs";
 import {
   PER_FILE_COUNTERFACTUAL_CEILING,
   SKELETON_SYMBOL_CAP,
-  UNTRUSTED_FILE_TAG,
-  UNTRUSTED_GITHUB_TAG,
-  UNTRUSTED_HTML_TAG,
   atomicWriteBytes,
   compileGrepMatcher,
   countNoun,
   decodeSource,
-  displaySafeJson,
-  displaySafeText,
   ensureNewline,
   escapeRegExp,
   excludeTestsHiddenNote,
   extractErrorMessage,
-  fenceUntrustedContent,
-  fenceUntrustedFileContent,
   filtersFilteredToEmptyNotice,
   foldCaseForContainment,
   foldPath,
@@ -174,20 +180,29 @@ import {
   grepFilteredToEmptyNotice,
   isInsideRoot,
   isTestFile,
-  normalizePath,
   pushAll,
   redactUrlQuery,
   requireNonNegativeStrictInt,
   requirePositiveStrictInt,
-  resolveIndexPath,
   resolveOnPath,
   runGit,
   stripBom,
   supportRequestLine,
-  toDisplayPath,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-AMYCQJX4.mjs";
+} from "./token-goat-chunk-PM76YS22.mjs";
+import {
+  UNTRUSTED_FILE_TAG,
+  UNTRUSTED_GITHUB_TAG,
+  UNTRUSTED_HTML_TAG,
+  displaySafeJson,
+  displaySafeText,
+  fenceUntrustedContent,
+  fenceUntrustedFileContent,
+  normalizePath,
+  resolveIndexPath,
+  toDisplayPath
+} from "./token-goat-chunk-ERTXEKB6.mjs";
 import {
   compileGuardedRegex
 } from "./token-goat-chunk-GMOUBOX4.mjs";
@@ -195,185 +210,439 @@ import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";
 
-// src/read_spec.ts
-init_define_import_meta_env();
-import * as fs14 from "node:fs";
-
-// src/read_commands.ts
-init_define_import_meta_env();
-import * as fs13 from "node:fs";
-import * as path12 from "node:path";
-
-// src/import_export_extract.ts
+// src/json_query.ts
 init_define_import_meta_env();
-import * as path from "node:path";
-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);
+function jsonType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
 }
-function extractExportNames(text, ext) {
-  const names = [];
-  const push = (s) => {
-    let v = (s ?? "").trim();
-    if (v.includes(" as ")) v = v.split(/\s+as\s+/).pop()?.trim() ?? v;
-    if (v !== "" && v !== "default" && !names.includes(v)) names.push(v);
-  };
-  const e = ext.toLowerCase();
-  const lines = text.split(/\r?\n/);
-  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"].includes(e)) {
-    const declRe = /\bexport\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/g;
-    const defaultRe = /\bexport\s+default\s+([A-Za-z_$][\w$]*)\s*(?:;|$)/g;
-    const namedRe = /\bexport\s+(?:type\s+)?\{([^}]*)\}/g;
-    let m;
-    while ((m = declRe.exec(text)) !== null) push(m[1]);
-    while ((m = defaultRe.exec(text)) !== null) push(m[1]);
-    while ((m = namedRe.exec(text)) !== null) {
-      for (const part of (m[1] ?? "").split(",")) push(part);
-    }
-  } else if (e === ".py") {
-    for (const line of lines) {
-      const m = /^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/.exec(line);
-      if (m && !(m[1] ?? "").startsWith("_")) push(m[1]);
-    }
-  } else if (e === ".rs") {
-    for (const line of lines) {
-      const m = /^\s*pub(?:\s*\([^)]*\))?\s+(?:async\s+)?(?:fn|struct|enum|trait|type|const|mod|static)\s+([A-Za-z_]\w*)/.exec(line);
-      if (m) push(m[1]);
+function fieldSummary(name, value) {
+  const type = jsonType(value);
+  if (type === "array") return { name, type, size: value.length };
+  if (type === "object") return { name, type, size: Object.keys(value).length };
+  return { name, type };
+}
+function outlineJson(data, opts = {}) {
+  const sampleSize = opts.sampleSize ?? 5;
+  const type = jsonType(data);
+  if (type === "array") {
+    const arr = data;
+    const sample = arr.slice(0, sampleSize);
+    const elementTypes = new Set(sample.map(jsonType));
+    const elementType = elementTypes.size === 0 ? "unknown" : elementTypes.size === 1 ? [...elementTypes][0] : "mixed";
+    const result = { kind: "array", length: arr.length, elementType };
+    if (elementType === "object") {
+      const objects = sample;
+      const keySets = objects.map((el) => Object.keys(el));
+      const allKeys = [...new Set(keySets.flat())];
+      result.sampleKeys = allKeys.map((k) => {
+        const owner = objects.find((el) => Object.prototype.hasOwnProperty.call(el, k));
+        return fieldSummary(k, owner?.[k]);
+      });
+      const firstKeySet = keySets[0] ?? [];
+      result.heterogeneous = keySets.some((ks) => ks.length !== firstKeySet.length || !ks.every((k) => firstKeySet.includes(k)));
     }
-  } else if (e === ".java") {
-    for (const line of lines) {
-      const m = /\bpublic\s+(?:static\s+|final\s+|abstract\s+)*(?:class|interface|enum|record)\s+([A-Za-z_]\w*)/.exec(line);
-      if (m) push(m[1]);
+    return result;
+  }
+  if (type === "object") {
+    const obj = data;
+    return { kind: "object", fields: Object.keys(obj).map((k) => fieldSummary(k, obj[k])) };
+  }
+  return { kind: "primitive", type };
+}
+function formatJsonOutline(outline) {
+  if (outline.kind === "primitive") return `(scalar ${outline.type})`;
+  if (outline.kind === "object") {
+    if (outline.fields.length === 0) return "(empty object)";
+    return outline.fields.map((f) => `${displaySafeText(f.name)}: ${f.type}${f.size !== void 0 ? ` (${f.size})` : ""}`).join("\n");
+  }
+  const lines = [`array of ${outline.length} element${outline.length === 1 ? "" : "s"} (${outline.elementType})`];
+  if (outline.sampleKeys !== void 0) {
+    lines.push(outline.heterogeneous === true ? "keys (from first elements, shape varies across sample):" : "keys (from first elements):");
+    for (const f of outline.sampleKeys) {
+      lines.push(`  ${displaySafeText(f.name)}: ${f.type}${f.size !== void 0 ? ` (${f.size})` : ""}`);
     }
   }
-  return names;
+  return lines.join("\n");
 }
-function splitTopLevelCommas(s) {
-  const parts = [];
-  let depth = 0;
-  let cur = "";
-  for (const ch of s) {
-    if (ch === "{") depth++;
-    if (ch === "}") depth--;
-    if (ch === "," && depth === 0) {
-      parts.push(cur);
-      cur = "";
+var MAX_RECURSIVE_NODES = 5e4;
+var MAX_RECURSIVE_DEPTH = 100;
+function collectRecursiveKey(root, keyName, out, budget) {
+  const seen = /* @__PURE__ */ new Set();
+  function walk(val, depth) {
+    if (depth > MAX_RECURSIVE_DEPTH) {
+      budget.exhausted = true;
+      return;
+    }
+    if (val === null || typeof val !== "object") return;
+    if (seen.has(val)) return;
+    seen.add(val);
+    if (budget.nodesLeft <= 0) {
+      budget.exhausted = true;
+      return;
+    }
+    budget.nodesLeft--;
+    if (Array.isArray(val)) {
+      for (let i = 0; i < val.length; i++) {
+        walk(val[i], depth + 1);
+        if (budget.nodesLeft <= 0) {
+          if (i < val.length - 1) budget.exhausted = true;
+          return;
+        }
+      }
     } else {
-      cur += ch;
+      const obj = val;
+      if (Object.prototype.hasOwnProperty.call(obj, keyName)) {
+        out.push(obj[keyName]);
+      }
+      const keys = Object.keys(obj);
+      for (let i = 0; i < keys.length; i++) {
+        walk(obj[keys[i]], depth + 1);
+        if (budget.nodesLeft <= 0) {
+          if (i < keys.length - 1) budget.exhausted = true;
+          return;
+        }
+      }
     }
   }
-  if (cur.trim() !== "") parts.push(cur);
-  return parts;
+  walk(root, 0);
 }
-function expandRustUseGroup(base, inner) {
-  const results = [];
-  for (const part of splitTopLevelCommas(inner)) {
-    const trimmed = part.trim();
-    if (trimmed === "" || trimmed === "self") {
-      if (trimmed === "self") results.push(base);
+function getNestedField(obj, fieldPath) {
+  if (obj === null || typeof obj !== "object") return void 0;
+  if (Object.prototype.hasOwnProperty.call(obj, fieldPath)) {
+    return obj[fieldPath];
+  }
+  const parts = fieldPath.split(".");
+  let cur = obj;
+  for (const part of parts) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    if (!Object.prototype.hasOwnProperty.call(cur, part)) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function parseJsonPath(spec) {
+  const ops = [];
+  const n = spec.length;
+  let i = 0;
+  while (i < n) {
+    if (spec[i] === "." && i + 1 < n && spec[i + 1] === ".") {
+      i += 2;
+      let j2 = i;
+      while (j2 < n && spec[j2] !== "." && spec[j2] !== "[") j2++;
+      if (j2 === i) throw new Error(`invalid path spec: expected property name after '..' in '${spec}'`);
+      ops.push({ kind: "recursive_key", name: spec.slice(i, j2) });
+      i = j2;
       continue;
     }
-    const nested = /^([\w:]+)::\{([\s\S]*)\}$/.exec(trimmed);
-    if (nested) {
-      results.push(...expandRustUseGroup(`${base}::${nested[1] ?? ""}`, nested[2] ?? ""));
+    const ch = spec[i];
+    if (ch === ".") {
+      i++;
       continue;
     }
-    const name = (trimmed.split(/\s+as\s+/)[0] ?? "").trim();
-    if (name === "" || name === "self") {
-      results.push(base);
+    if (ch === "[") {
+      let inQuote = null;
+      let close = -1;
+      for (let k = i + 1; k < n; k++) {
+        const c = spec[k];
+        if (inQuote !== null) {
+          if (c === "\\") {
+            k++;
+            continue;
+          }
+          if (c === inQuote) {
+            inQuote = null;
+          }
+        } else if (c === '"' || c === "'") {
+          inQuote = c;
+        } else if (c === "]") {
+          close = k;
+          break;
+        }
+      }
+      if (close === -1) throw new Error(`invalid path spec: unterminated '[' in '${spec}'`);
+      const inner = spec.slice(i + 1, close);
+      if (inner === "*") {
+        ops.push({ kind: "wildcard" });
+      } else if (/^-?\d+$/.test(inner)) {
+        ops.push({ kind: "index", index: Number(inner) });
+      } else {
+        let expr = inner.trim();
+        if (expr.startsWith("?(") && expr.endsWith(")")) {
+          expr = expr.slice(2, -1).trim();
+        }
+        if (expr.startsWith("@.")) {
+          expr = expr.slice(2).trim();
+        }
+        const m = /^([^=]+)==?(.*)$/.exec(expr);
+        if (!m) {
+          const bareOperator = /[<>]/.exec(expr);
+          if (bareOperator !== null) {
+            throw new Error(`unsupported comparison operator '${bareOperator[0]}' in '[${inner}]' of path spec '${spec}': this grammar filters by equality only ([field=value])`);
+          }
+          throw new Error(`invalid bracket expression '[${inner}]' in path spec: '${spec}' (expected [n], [*], or [field=value])`);
+        }
+        let field = m[1].trim();
+        if (field.startsWith("@.")) field = field.slice(2).trim();
+        const swallowedOperator = /[!<>]$/.exec(field);
+        if (swallowedOperator !== null) {
+          throw new Error(`unsupported comparison operator '${swallowedOperator[0]}=' in '[${inner}]' of path spec '${spec}': this grammar filters by equality only ([field=value])`);
+        }
+        let rawVal = m[2].trim();
+        if (rawVal.startsWith('"') && rawVal.endsWith('"') || rawVal.startsWith("'") && rawVal.endsWith("'")) {
+          if (rawVal.length >= 2) {
+            rawVal = rawVal.slice(1, -1).replace(/\\(["'\\])/g, "$1");
+          }
+        }
+        ops.push({ kind: "filter", field, value: rawVal });
+      }
+      i = close + 1;
       continue;
     }
-    results.push(`${base}::${name}`);
+    let j = i;
+    while (j < n && spec[j] !== "." && spec[j] !== "[") j++;
+    if (j === i) throw new Error(`invalid path spec: '${spec}'`);
+    ops.push({ kind: "key", name: spec.slice(i, j) });
+    i = j;
   }
-  return results;
+  return ops;
 }
-function extractImports(text, ext) {
-  const found = [];
-  const push = (s) => {
-    const v = (s ?? "").trim();
-    if (v !== "" && !found.includes(v)) found.push(v);
-  };
-  const e = ext.toLowerCase();
-  const lines = text.split(/\r?\n/);
-  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".vue", ".svelte", ".astro"].includes(e)) {
-    const fromRe = /(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g;
-    const bareRe = /^\s*import\s*['"]([^'"]+)['"]/gm;
-    const reqRe = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
-    const dynRe = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
-    const matches = [];
-    let m;
-    while ((m = fromRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
-    while ((m = bareRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
-    while ((m = reqRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
-    while ((m = dynRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
-    matches.sort((a, b) => a.index - b.index);
-    for (const match of matches) push(match.value);
-  } else if (e === ".py") {
-    for (const line of lines) {
-      const from = /^\s*from\s+([.\w]+)\s+import\b/.exec(line);
-      if (from) {
-        push(from[1]);
-        continue;
-      }
-      const imp = /^\s*import\s+(.+)$/.exec(line);
-      if (imp) {
-        const spec = (imp[1] ?? "").split("#")[0] ?? "";
-        for (const part of spec.split(",")) push(part.trim().split(/\s+as\s+/)[0]);
-      }
-    }
-  } else if (e === ".go") {
-    let inBlock = false;
-    for (const line of lines) {
-      if (/^\s*import\s*\(/.test(line)) {
-        inBlock = true;
-        continue;
-      }
-      if (inBlock) {
-        if (/^\s*\)/.test(line)) {
-          inBlock = false;
-          continue;
+function evalJsonPath(data, ops) {
+  let current = [data];
+  let fanned = false;
+  const budget = { nodesLeft: MAX_RECURSIVE_NODES, exhausted: false };
+  for (const op of ops) {
+    const next = [];
+    for (const item of current) {
+      if (op.kind === "key") {
+        if (typeof item === "object" && item !== null && !Array.isArray(item) && Object.prototype.hasOwnProperty.call(item, op.name)) {
+          next.push(item[op.name]);
+        } else if (!fanned) {
+          throw new Error(`path not found: key '${op.name}' does not exist on ${jsonType(item)} value`);
+        }
+      } else if (op.kind === "recursive_key") {
+        fanned = true;
+        collectRecursiveKey(item, op.name, next, budget);
+      } else if (op.kind === "index") {
+        if (Array.isArray(item)) {
+          const idx = op.index < 0 ? item.length + op.index : op.index;
+          if (idx >= 0 && idx < item.length) {
+            next.push(item[idx]);
+          } else if (!fanned) {
+            throw new Error(`path not found: index [${op.index}] out of range (length ${item.length})`);
+          }
+        } else if (!fanned) {
+          throw new Error(`path not found: index [${op.index}] on non-array ${jsonType(item)} value`);
+        }
+      } else if (op.kind === "wildcard") {
+        fanned = true;
+        if (Array.isArray(item)) {
+          pushAll(next, item);
+        } else if (typeof item === "object" && item !== null) {
+          pushAll(next, Object.values(item));
+        }
+      } else {
+        fanned = true;
+        if (Array.isArray(item)) {
+          for (const el of item) {
+            if (typeof el === "object" && el !== null && !Array.isArray(el)) {
+              const val = getNestedField(el, op.field);
+              if (val !== void 0 && String(val) === op.value) {
+                next.push(el);
+              }
+            }
+          }
         }
-        const m = /['"]([^'"]+)['"]/.exec(line);
-        if (m) push(m[1]);
-        continue;
       }
-      const single = /^\s*import\s+(?:[\w.]+\s+)?['"]([^'"]+)['"]/.exec(line);
-      if (single) push(single[1]);
     }
-  } else if (e === ".rs") {
-    for (const line of lines) {
-      const groupM = /^\s*(?:pub(?:\([^)]*\))?\s+)?use\s+([\w:]+)::\{([\s\S]*)\}/.exec(line);
-      if (groupM) {
-        for (const t of expandRustUseGroup(groupM[1] ?? "", groupM[2] ?? "")) push(t);
+    current = next;
+  }
+  return { fanned, items: current, truncated: budget.exhausted };
+}
+function queryJson(data, spec) {
+  return evalJsonPath(data, parseJsonPath(spec));
+}
+
+// src/read_spec.ts
+init_define_import_meta_env();
+import * as fs13 from "node:fs";
+
+// src/read_commands.ts
+init_define_import_meta_env();
+import * as fs12 from "node:fs";
+import * as path12 from "node:path";
+
+// src/import_export_extract.ts
+init_define_import_meta_env();
+import * as path from "node:path";
+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);
+}
+function extractExportNames(text, ext) {
+  const names = [];
+  const push = (s) => {
+    let v = (s ?? "").trim();
+    if (v.includes(" as ")) v = v.split(/\s+as\s+/).pop()?.trim() ?? v;
+    if (v !== "" && v !== "default" && !names.includes(v)) names.push(v);
+  };
+  const e = ext.toLowerCase();
+  const lines = text.split(/\r?\n/);
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"].includes(e)) {
+    const declRe = /\bexport\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/g;
+    const defaultRe = /\bexport\s+default\s+([A-Za-z_$][\w$]*)\s*(?:;|$)/g;
+    const namedRe = /\bexport\s+(?:type\s+)?\{([^}]*)\}/g;
+    let m;
+    while ((m = declRe.exec(text)) !== null) push(m[1]);
+    while ((m = defaultRe.exec(text)) !== null) push(m[1]);
+    while ((m = namedRe.exec(text)) !== null) {
+      for (const part of (m[1] ?? "").split(",")) push(part);
+    }
+  } else if (e === ".py") {
+    for (const line of lines) {
+      const m = /^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/.exec(line);
+      if (m && !(m[1] ?? "").startsWith("_")) push(m[1]);
+    }
+  } else if (e === ".rs") {
+    for (const line of lines) {
+      const m = /^\s*pub(?:\s*\([^)]*\))?\s+(?:async\s+)?(?:fn|struct|enum|trait|type|const|mod|static)\s+([A-Za-z_]\w*)/.exec(line);
+      if (m) push(m[1]);
+    }
+  } else if (e === ".java") {
+    for (const line of lines) {
+      const m = /\bpublic\s+(?:static\s+|final\s+|abstract\s+)*(?:class|interface|enum|record)\s+([A-Za-z_]\w*)/.exec(line);
+      if (m) push(m[1]);
+    }
+  }
+  return names;
+}
+function splitTopLevelCommas(s) {
+  const parts = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of s) {
+    if (ch === "{") depth++;
+    if (ch === "}") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim() !== "") parts.push(cur);
+  return parts;
+}
+function expandRustUseGroup(base, inner) {
+  const results = [];
+  for (const part of splitTopLevelCommas(inner)) {
+    const trimmed = part.trim();
+    if (trimmed === "" || trimmed === "self") {
+      if (trimmed === "self") results.push(base);
+      continue;
+    }
+    const nested = /^([\w:]+)::\{([\s\S]*)\}$/.exec(trimmed);
+    if (nested) {
+      results.push(...expandRustUseGroup(`${base}::${nested[1] ?? ""}`, nested[2] ?? ""));
+      continue;
+    }
+    const name = (trimmed.split(/\s+as\s+/)[0] ?? "").trim();
+    if (name === "" || name === "self") {
+      results.push(base);
+      continue;
+    }
+    results.push(`${base}::${name}`);
+  }
+  return results;
+}
+function extractImports(text, ext) {
+  const found = [];
+  const push = (s) => {
+    const v = (s ?? "").trim();
+    if (v !== "" && !found.includes(v)) found.push(v);
+  };
+  const e = ext.toLowerCase();
+  const lines = text.split(/\r?\n/);
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".vue", ".svelte", ".astro"].includes(e)) {
+    const fromRe = /(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g;
+    const bareRe = /^\s*import\s*['"]([^'"]+)['"]/gm;
+    const reqRe = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    const dynRe = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    const matches = [];
+    let m;
+    while ((m = fromRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
+    while ((m = bareRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
+    while ((m = reqRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
+    while ((m = dynRe.exec(text)) !== null) matches.push({ index: m.index, value: m[1] ?? "" });
+    matches.sort((a, b) => a.index - b.index);
+    for (const match of matches) push(match.value);
+  } else if (e === ".py") {
+    for (const line of lines) {
+      const from = /^\s*from\s+([.\w]+)\s+import\b/.exec(line);
+      if (from) {
+        push(from[1]);
+        continue;
+      }
+      const imp = /^\s*import\s+(.+)$/.exec(line);
+      if (imp) {
+        const spec = (imp[1] ?? "").split("#")[0] ?? "";
+        for (const part of spec.split(",")) push(part.trim().split(/\s+as\s+/)[0]);
+      }
+    }
+  } else if (e === ".go") {
+    let inBlock = false;
+    for (const line of lines) {
+      if (/^\s*import\s*\(/.test(line)) {
+        inBlock = true;
+        continue;
+      }
+      if (inBlock) {
+        if (/^\s*\)/.test(line)) {
+          inBlock = false;
+          continue;
+        }
+        const m = /['"]([^'"]+)['"]/.exec(line);
+        if (m) push(m[1]);
+        continue;
+      }
+      const single = /^\s*import\s+(?:[\w.]+\s+)?['"]([^'"]+)['"]/.exec(line);
+      if (single) push(single[1]);
+    }
+  } else if (e === ".rs") {
+    for (const line of lines) {
+      const groupM = /^\s*(?:pub(?:\([^)]*\))?\s+)?use\s+([\w:]+)::\{([\s\S]*)\}/.exec(line);
+      if (groupM) {
+        for (const t of expandRustUseGroup(groupM[1] ?? "", groupM[2] ?? "")) push(t);
         continue;
       }
       const m = /^\s*(?:pub(?:\([^)]*\))?\s+)?use\s+([^;{]+)/.exec(line);
@@ -5644,737 +5913,483 @@ function parseHtml(html) {
             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);
+                line: tagStartLine,
+                type: "error",
+                message: `Duplicate ID '#${attrVal}' previously defined on line ${prevLine}`,
+                rule: "duplicate-id"
+              });
+            } else {
+              seenIds.set(attrVal, tagStartLine);
+            }
           }
-          currentCandidates = Array.from(nextSet);
         }
-        i++;
+        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;
     }
-    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]);
+    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;
     }
-    return { elements, attributeValues, fanned: attributeValues.length > 1, sourceHtml: htmlText };
+    pos = textChunkEnd;
   }
-  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();
+  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;
   }
-  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);
+  for (const tag of Object.keys(tagCounts)) {
+    const entry = tagCounts[tag];
+    entry.diff = entry.open - entry.close;
   }
-  return parts.join(" ");
+  root.endLine = currentLine;
+  return { root, issues, tagCounts };
 }
-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}>`;
+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++;
+      }
     }
-    if (!textTrimmed.includes("\n") && textTrimmed.length < 80) {
-      return `${pad}<${node.tag}${attrStr}>${textTrimmed}</${node.tag}>`;
+    for (const child of node.children) {
+      walk(child, depth + 1);
     }
-    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}>`;
-}
-
-// src/json_query.ts
-init_define_import_meta_env();
-function jsonType(value) {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return "array";
-  return typeof value;
-}
-function fieldSummary(name, value) {
-  const type = jsonType(value);
-  if (type === "array") return { name, type, size: value.length };
-  if (type === "object") return { name, type, size: Object.keys(value).length };
-  return { name, type };
+  walk(root, 0);
+  return {
+    title,
+    doctype,
+    totalElements,
+    uniqueTags: Array.from(uniqueTags).sort(),
+    maxDepth,
+    headings,
+    landmarks,
+    tables,
+    forms,
+    scripts,
+    styles
+  };
 }
-function outlineJson(data, opts = {}) {
-  const sampleSize = opts.sampleSize ?? 5;
-  const type = jsonType(data);
-  if (type === "array") {
-    const arr = data;
-    const sample = arr.slice(0, sampleSize);
-    const elementTypes = new Set(sample.map(jsonType));
-    const elementType = elementTypes.size === 0 ? "unknown" : elementTypes.size === 1 ? [...elementTypes][0] : "mixed";
-    const result = { kind: "array", length: arr.length, elementType };
-    if (elementType === "object") {
-      const objects = sample;
-      const keySets = objects.map((el) => Object.keys(el));
-      const allKeys = [...new Set(keySets.flat())];
-      result.sampleKeys = allKeys.map((k) => {
-        const owner = objects.find((el) => Object.prototype.hasOwnProperty.call(el, k));
-        return fieldSummary(k, owner?.[k]);
-      });
-      const firstKeySet = keySets[0] ?? [];
-      result.heterogeneous = keySets.some((ks) => ks.length !== firstKeySet.length || !ks.every((k) => firstKeySet.includes(k)));
+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)`);
     }
-    return result;
   }
-  if (type === "object") {
-    const obj = data;
-    return { kind: "object", fields: Object.keys(obj).map((k) => fieldSummary(k, obj[k])) };
+  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})`);
+    }
   }
-  return { kind: "primitive", type };
-}
-function formatJsonOutline(outline) {
-  if (outline.kind === "primitive") return `(scalar ${outline.type})`;
-  if (outline.kind === "object") {
-    if (outline.fields.length === 0) return "(empty object)";
-    return outline.fields.map((f) => `${displaySafeText(f.name)}: ${f.type}${f.size !== void 0 ? ` (${f.size})` : ""}`).join("\n");
+  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})`);
+    }
   }
-  const lines = [`array of ${outline.length} element${outline.length === 1 ? "" : "s"} (${outline.elementType})`];
-  if (outline.sampleKeys !== void 0) {
-    lines.push(outline.heterogeneous === true ? "keys (from first elements, shape varies across sample):" : "keys (from first elements):");
-    for (const f of outline.sampleKeys) {
-      lines.push(`  ${displaySafeText(f.name)}: ${f.type}${f.size !== void 0 ? ` (${f.size})` : ""}`);
+  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");
 }
-var MAX_RECURSIVE_NODES = 5e4;
-var MAX_RECURSIVE_DEPTH = 100;
-function collectRecursiveKey(root, keyName, out, budget) {
-  const seen = /* @__PURE__ */ new Set();
-  function walk(val, depth) {
-    if (depth > MAX_RECURSIVE_DEPTH) {
-      budget.exhausted = true;
-      return;
-    }
-    if (val === null || typeof val !== "object") return;
-    if (seen.has(val)) return;
-    seen.add(val);
-    if (budget.nodesLeft <= 0) {
-      budget.exhausted = true;
-      return;
-    }
-    budget.nodesLeft--;
-    if (Array.isArray(val)) {
-      for (let i = 0; i < val.length; i++) {
-        walk(val[i], depth + 1);
-        if (budget.nodesLeft <= 0) {
-          if (i < val.length - 1) budget.exhausted = true;
-          return;
-        }
-      }
+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 {
-      const obj = val;
-      if (Object.prototype.hasOwnProperty.call(obj, keyName)) {
-        out.push(obj[keyName]);
-      }
-      const keys = Object.keys(obj);
-      for (let i = 0; i < keys.length; i++) {
-        walk(obj[keys[i]], depth + 1);
-        if (budget.nodesLeft <= 0) {
-          if (i < keys.length - 1) budget.exhausted = true;
-          return;
-        }
+      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;
       }
     }
   }
-  walk(root, 0);
-}
-function getNestedField(obj, fieldPath) {
-  if (obj === null || typeof obj !== "object") return void 0;
-  if (Object.prototype.hasOwnProperty.call(obj, fieldPath)) {
-    return obj[fieldPath];
-  }
-  const parts = fieldPath.split(".");
-  let cur = obj;
-  for (const part of parts) {
-    if (cur === null || typeof cur !== "object") return void 0;
-    if (!Object.prototype.hasOwnProperty.call(cur, part)) return void 0;
-    cur = cur[part];
-  }
-  return cur;
+  results.push(str.slice(start));
+  return results;
 }
-function parseJsonPath(spec) {
-  const ops = [];
-  const n = spec.length;
+function tokenizeSelector(sel) {
+  const tokens = [];
   let i = 0;
+  const n = sel.length;
   while (i < n) {
-    if (spec[i] === "." && i + 1 < n && spec[i + 1] === ".") {
-      i += 2;
-      let j2 = i;
-      while (j2 < n && spec[j2] !== "." && spec[j2] !== "[") j2++;
-      if (j2 === i) throw new Error(`invalid path spec: expected property name after '..' in '${spec}'`);
-      ops.push({ kind: "recursive_key", name: spec.slice(i, j2) });
-      i = j2;
-      continue;
-    }
-    const ch = spec[i];
-    if (ch === ".") {
+    while (i < n && /\s/.test(sel[i])) i++;
+    if (i >= n) break;
+    if (sel[i] === ">") {
+      tokens.push(">");
       i++;
       continue;
     }
-    if (ch === "[") {
-      let inQuote = null;
-      let close = -1;
-      for (let k = i + 1; k < n; k++) {
-        const c = spec[k];
-        if (inQuote !== null) {
-          if (c === "\\") {
-            k++;
-            continue;
-          }
-          if (c === inQuote) {
-            inQuote = null;
-          }
-        } else if (c === '"' || c === "'") {
-          inQuote = c;
-        } else if (c === "]") {
-          close = k;
-          break;
-        }
-      }
-      if (close === -1) throw new Error(`invalid path spec: unterminated '[' in '${spec}'`);
-      const inner = spec.slice(i + 1, close);
-      if (inner === "*") {
-        ops.push({ kind: "wildcard" });
-      } else if (/^-?\d+$/.test(inner)) {
-        ops.push({ kind: "index", index: Number(inner) });
+    const start = i;
+    let inQuote = null;
+    let bracketDepth = 0;
+    while (i < n) {
+      const ch = sel[i];
+      if (inQuote) {
+        if (ch === inQuote) inQuote = null;
       } else {
-        let expr = inner.trim();
-        if (expr.startsWith("?(") && expr.endsWith(")")) {
-          expr = expr.slice(2, -1).trim();
-        }
-        if (expr.startsWith("@.")) {
-          expr = expr.slice(2).trim();
-        }
-        const m = /^([^=]+)==?(.*)$/.exec(expr);
-        if (!m) {
-          const bareOperator = /[<>]/.exec(expr);
-          if (bareOperator !== null) {
-            throw new Error(`unsupported comparison operator '${bareOperator[0]}' in '[${inner}]' of path spec '${spec}': this grammar filters by equality only ([field=value])`);
+        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;
           }
-          throw new Error(`invalid bracket expression '[${inner}]' in path spec: '${spec}' (expected [n], [*], or [field=value])`);
-        }
-        let field = m[1].trim();
-        if (field.startsWith("@.")) field = field.slice(2).trim();
-        const swallowedOperator = /[!<>]$/.exec(field);
-        if (swallowedOperator !== null) {
-          throw new Error(`unsupported comparison operator '${swallowedOperator[0]}=' in '[${inner}]' of path spec '${spec}': this grammar filters by equality only ([field=value])`);
         }
-        let rawVal = m[2].trim();
-        if (rawVal.startsWith('"') && rawVal.endsWith('"') || rawVal.startsWith("'") && rawVal.endsWith("'")) {
-          if (rawVal.length >= 2) {
-            rawVal = rawVal.slice(1, -1).replace(/\\(["'\\])/g, "$1");
+      }
+      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;
           }
         }
-        ops.push({ kind: "filter", field, value: rawVal });
       }
-      i = close + 1;
-      continue;
+      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;
     }
-    let j = i;
-    while (j < n && spec[j] !== "." && spec[j] !== "[") j++;
-    if (j === i) throw new Error(`invalid path spec: '${spec}'`);
-    ops.push({ kind: "key", name: spec.slice(i, j) });
-    i = j;
   }
-  return ops;
+  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 evalJsonPath(data, ops) {
-  let current = [data];
-  let fanned = false;
-  const budget = { nodesLeft: MAX_RECURSIVE_NODES, exhausted: false };
-  for (const op of ops) {
-    const next = [];
-    for (const item of current) {
-      if (op.kind === "key") {
-        if (typeof item === "object" && item !== null && !Array.isArray(item) && Object.prototype.hasOwnProperty.call(item, op.name)) {
-          next.push(item[op.name]);
-        } else if (!fanned) {
-          throw new Error(`path not found: key '${op.name}' does not exist on ${jsonType(item)} value`);
-        }
-      } else if (op.kind === "recursive_key") {
-        fanned = true;
-        collectRecursiveKey(item, op.name, next, budget);
-      } else if (op.kind === "index") {
-        if (Array.isArray(item)) {
-          const idx = op.index < 0 ? item.length + op.index : op.index;
-          if (idx >= 0 && idx < item.length) {
-            next.push(item[idx]);
-          } else if (!fanned) {
-            throw new Error(`path not found: index [${op.index}] out of range (length ${item.length})`);
+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);
+            }
           }
-        } else if (!fanned) {
-          throw new Error(`path not found: index [${op.index}] on non-array ${jsonType(item)} value`);
-        }
-      } else if (op.kind === "wildcard") {
-        fanned = true;
-        if (Array.isArray(item)) {
-          pushAll(next, item);
-        } else if (typeof item === "object" && item !== null) {
-          pushAll(next, Object.values(item));
         }
+        currentCandidates = nextCandidates;
+        i += 2;
       } else {
-        fanned = true;
-        if (Array.isArray(item)) {
-          for (const el of item) {
-            if (typeof el === "object" && el !== null && !Array.isArray(el)) {
-              const val = getNestedField(el, op.field);
-              if (val !== void 0 && String(val) === op.value) {
-                next.push(el);
+        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++;
       }
     }
-    current = next;
+    for (const match of currentCandidates) {
+      matchedSet.add(match);
+    }
   }
-  return { fanned, items: current, truncated: budget.exhausted };
+  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 queryJson(data, spec) {
-  return evalJsonPath(data, parseJsonPath(spec));
+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}>`;
 }
 
 // src/openapi_query.ts
@@ -6572,6 +6587,7 @@ function parseXmlTree(xmlText) {
   const namespaces = {};
   let totalElements = 0;
   const doctypeMatch = new RegExp(
+    // eslint-disable-next-line regexp/no-super-linear-backtracking
     `<!DOCTYPE\\s+((?:[^>[\\]"']|"[^"]*"|'[^']*'|\\[[\\s\\S]*?\\])*)\\s*>`,
     "i"
   ).exec(text);
@@ -6594,7 +6610,7 @@ function parseXmlTree(xmlText) {
     return attrs;
   }
   const tagRegex = new RegExp(
-    // eslint-disable-next-line no-misleading-character-class
+    // eslint-disable-next-line no-misleading-character-class, regexp/no-super-linear-backtracking
     `<(\\/)?(${XML_NAME})(${XML_ATTR_REGION})(\\/)?>|<!--[\\s\\S]*?-->|<!\\[CDATA\\[([\\s\\S]*?)\\]\\]>|<\\?[\\s\\S]*?\\?>|${XML_DOCTYPE_TOKEN}`,
     "gi"
   );
@@ -6632,6 +6648,13 @@ function parseXmlTree(xmlText) {
       lineScan++;
     }
     const line = lineOffset + 1;
+    let endScan = match.index;
+    let endLineOffset = lineOffset;
+    while (endScan < tagRegex.lastIndex) {
+      if (text.charCodeAt(endScan) === 10) endLineOffset++;
+      endScan++;
+    }
+    const tagEndLine = endLineOffset + 1;
     if (isClosing) {
       if (stack.length > 0) {
         let popIdx = stack.length - 1;
@@ -6640,7 +6663,8 @@ function parseXmlTree(xmlText) {
         }
         if (popIdx >= 0) {
           while (stack.length > popIdx) {
-            stack.pop();
+            const popped = stack.pop();
+            popped.lineEnd = tagEndLine;
           }
         }
       }
@@ -6652,7 +6676,8 @@ function parseXmlTree(xmlText) {
         attributes: attrs,
         children: [],
         text: "",
-        line
+        line,
+        lineEnd: isSelfClosing ? tagEndLine : line
       };
       if (stack.length === 0) {
         if (!rootNode) rootNode = newNode;
@@ -6665,6 +6690,12 @@ function parseXmlTree(xmlText) {
     }
     lastIndex = tagRegex.lastIndex;
   }
+  while (stack.length > 0) {
+    const unclosed = stack.pop();
+    if (!unclosed.lineEnd || unclosed.lineEnd < unclosed.line) {
+      unclosed.lineEnd = unclosed.line;
+    }
+  }
   return { root: rootNode, namespaces, doctype, totalElements };
 }
 function outlineXml(xmlText, opts = {}) {
@@ -6764,6 +6795,206 @@ function formatXmlOutline(summary) {
   renderNode(summary.tree, 0);
   return lines.join("\n");
 }
+function getLocalName(tag) {
+  const idx = tag.indexOf(":");
+  return idx === -1 ? tag : tag.slice(idx + 1);
+}
+function matchTag(nodeTag, targetTag) {
+  if (targetTag === "*" || targetTag === "") return true;
+  if (nodeTag.toLowerCase() === targetTag.toLowerCase()) return true;
+  if (!targetTag.includes(":")) {
+    return getLocalName(nodeTag).toLowerCase() === targetTag.toLowerCase();
+  }
+  return false;
+}
+function getAttrValue(node, targetAttr) {
+  const clean = targetAttr.startsWith("@") ? targetAttr.slice(1) : targetAttr;
+  if (clean === "*") {
+    const vals = Object.values(node.attributes);
+    return vals.length > 0 ? vals[0] : void 0;
+  }
+  if (node.attributes[clean] !== void 0) return node.attributes[clean];
+  const lowerClean = clean.toLowerCase();
+  for (const [k, v] of Object.entries(node.attributes)) {
+    if (k.toLowerCase() === lowerClean) return v;
+  }
+  if (!clean.includes(":")) {
+    for (const [k, v] of Object.entries(node.attributes)) {
+      if (getLocalName(k).toLowerCase() === lowerClean) return v;
+    }
+  }
+  return void 0;
+}
+function splitTopLevel2(str, delimiter) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  let parenDepth = 0;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (!quote && (ch === '"' || ch === "'")) {
+      quote = ch;
+      current += ch;
+    } else if (quote && ch === quote) {
+      quote = null;
+      current += ch;
+    } else if (!quote && ch === "(") {
+      parenDepth++;
+      current += ch;
+    } else if (!quote && ch === ")") {
+      if (parenDepth > 0) parenDepth--;
+      current += ch;
+    } else if (!quote && parenDepth === 0 && str.startsWith(delimiter, i)) {
+      parts.push(current.trim());
+      current = "";
+      i += delimiter.length - 1;
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+function parseSinglePredicate(predStr) {
+  const s = predStr.trim();
+  if (!s) return null;
+  const orParts = splitTopLevel2(s, " or ");
+  if (orParts.length > 1) {
+    const predicates = orParts.map(parseSinglePredicate);
+    if (predicates.some((p) => p === null)) return null;
+    return { kind: "or", predicates };
+  }
+  const andParts = splitTopLevel2(s, " and ");
+  if (andParts.length > 1) {
+    const predicates = andParts.map(parseSinglePredicate);
+    if (predicates.some((p) => p === null)) return null;
+    return { kind: "and", predicates };
+  }
+  if (/^-?\d+$/.test(s)) {
+    const n = parseInt(s, 10);
+    return { kind: "index", index: n };
+  }
+  if (s === "last()") {
+    return { kind: "index", index: -1 };
+  }
+  if (s === "*") {
+    return { kind: "all" };
+  }
+  const localMatch = /^local-name\(\)\s*(!?=)\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))\s*$/i.exec(s);
+  if (localMatch) {
+    const val = localMatch[2] !== void 0 ? localMatch[2] : localMatch[3] !== void 0 ? localMatch[3] : localMatch[4] ?? "";
+    return {
+      kind: "localNameEquals",
+      value: val,
+      ...localMatch[1] === "!=" ? { notEqual: true } : {}
+    };
+  }
+  const containsAttrMatch = /^contains\(\s*(@[a-zA-Z0-9_:.\\-]+|\*)\s*,\s*(?:"([^"]*)"|'([^']*)')\s*\)$/i.exec(s);
+  if (containsAttrMatch) {
+    const attrName = containsAttrMatch[1].replace(/^@/, "");
+    return { kind: "attrContains", name: attrName, value: containsAttrMatch[2] ?? containsAttrMatch[3] };
+  }
+  const containsTextMatch = /^contains\(\s*(?:text\(\)|\.)\s*,\s*(?:"([^"]*)"|'([^']*)')\s*\)$/i.exec(s);
+  if (containsTextMatch) {
+    return { kind: "textContains", value: containsTextMatch[1] ?? containsTextMatch[2] };
+  }
+  const startsWithAttrMatch = /^starts-with\(\s*(@[a-zA-Z0-9_:.\\-]+|\*)\s*,\s*(?:"([^"]*)"|'([^']*)')\s*\)$/i.exec(s);
+  if (startsWithAttrMatch) {
+    const attrName = startsWithAttrMatch[1].replace(/^@/, "");
+    return { kind: "attrStartsWith", name: attrName, value: startsWithAttrMatch[2] ?? startsWithAttrMatch[3] };
+  }
+  const textMatch = /^(?:text\(\)|\.)\s*(!?=)\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))\s*$/i.exec(s);
+  if (textMatch) {
+    const val = textMatch[2] !== void 0 ? textMatch[2] : textMatch[3] !== void 0 ? textMatch[3] : textMatch[4] ?? "";
+    return {
+      kind: "textEquals",
+      value: val,
+      ...textMatch[1] === "!=" ? { notEqual: true } : {}
+    };
+  }
+  const compMatch = /^(@?[a-zA-Z0-9_:.\\-]+)\s*(!?=)\s*(?:"([^"]*)"|'([^']*)'|([^\s\]]+))$/.exec(s);
+  if (compMatch) {
+    const name = compMatch[1];
+    const op = compMatch[2];
+    const val = compMatch[3] !== void 0 ? compMatch[3] : compMatch[4] !== void 0 ? compMatch[4] : compMatch[5] ?? "";
+    if (name.startsWith("@")) {
+      return {
+        kind: "attrEquals",
+        name: name.slice(1),
+        value: val,
+        ...op === "!=" ? { notEqual: true } : {}
+      };
+    }
+    return {
+      kind: "childEquals",
+      tag: name,
+      value: val,
+      ...op === "!=" ? { notEqual: true } : {}
+    };
+  }
+  if (s.startsWith("@")) {
+    return { kind: "attrExists", name: s.slice(1) };
+  }
+  if (/^[a-zA-Z0-9_:.\\-]+$/.test(s)) {
+    return { kind: "childExists", tag: s };
+  }
+  return null;
+}
+function evalPredicate(node, pred, indexInMatch, totalMatching) {
+  switch (pred.kind) {
+    case "index": {
+      const targetIdx = pred.index < 0 ? totalMatching + pred.index : pred.index;
+      return indexInMatch === targetIdx;
+    }
+    case "all":
+      return true;
+    case "and":
+      return pred.predicates.every((p) => evalPredicate(node, p, indexInMatch, totalMatching));
+    case "or":
+      return pred.predicates.some((p) => evalPredicate(node, p, indexInMatch, totalMatching));
+    case "localNameEquals": {
+      const local = getLocalName(node.tag);
+      const eq = local.toLowerCase() === pred.value.toLowerCase();
+      return pred.notEqual ? !eq : eq;
+    }
+    case "attrExists":
+      return getAttrValue(node, pred.name) !== void 0;
+    case "attrEquals": {
+      const val = getAttrValue(node, pred.name);
+      if (val !== void 0) {
+        return pred.notEqual ? val !== pred.value : val === pred.value;
+      }
+      const child = node.children.find((c) => matchTag(c.tag, pred.name));
+      if (child !== void 0) {
+        return pred.notEqual ? child.text.trim() !== pred.value.trim() : child.text.trim() === pred.value.trim();
+      }
+      return pred.notEqual === true;
+    }
+    case "attrContains": {
+      const val = getAttrValue(node, pred.name);
+      if (val === void 0) return false;
+      return val.toLowerCase().includes(pred.value.toLowerCase());
+    }
+    case "attrStartsWith": {
+      const val = getAttrValue(node, pred.name);
+      if (val === void 0) return false;
+      return val.toLowerCase().startsWith(pred.value.toLowerCase());
+    }
+    case "textEquals": {
+      const eq = node.text.trim() === pred.value.trim();
+      return pred.notEqual ? !eq : eq;
+    }
+    case "textContains":
+      return node.text.toLowerCase().includes(pred.value.toLowerCase());
+    case "childExists":
+      return node.children.some((c) => matchTag(c.tag, pred.tag));
+    case "childEquals": {
+      const child = node.children.find((c) => matchTag(c.tag, pred.tag));
+      if (!child) return pred.notEqual === true;
+      return pred.notEqual ? child.text.trim() !== pred.value.trim() : child.text.trim() === pred.value.trim();
+    }
+  }
+}
 function parseXmlPath(pathStr) {
   let normalized = pathStr.trim();
   if (normalized === "" || normalized === "/") return [];
@@ -6775,16 +7006,23 @@ function parseXmlPath(pathStr) {
   }
   const segments = [];
   let inBracket = false;
+  let quoteChar = null;
   let currentSegment = "";
   for (let i = 0; i < normalized.length; i++) {
     const ch = normalized[i];
-    if (ch === "[") {
+    if (!quoteChar && (ch === '"' || ch === "'")) {
+      quoteChar = ch;
+      currentSegment += ch;
+    } else if (quoteChar && ch === quoteChar) {
+      quoteChar = null;
+      currentSegment += ch;
+    } else if (!quoteChar && ch === "[") {
       inBracket = true;
       currentSegment += ch;
-    } else if (ch === "]") {
+    } else if (!quoteChar && ch === "]") {
       inBracket = false;
       currentSegment += ch;
-    } else if (!inBracket && (ch === "/" || ch === ".")) {
+    } else if (!quoteChar && !inBracket && (ch === "/" || ch === ".")) {
       if (currentSegment) {
         segments.push(currentSegment);
         currentSegment = "";
@@ -6813,54 +7051,167 @@ function parseXmlPath(pathStr) {
       steps.push({ tag: "", isRecursive, attributeSelect: attrSelectMatch[1] });
       continue;
     }
-    const indexMatch = /\[(-?\d+)\]$/.exec(s);
-    const wildcardMatch = /\[\*\]$/.exec(s);
-    const attrMatch = /\[@?([a-zA-Z0-9_:.\\-]+)(?:(!?=)\s*["']?([^"'\]]*)["']?)?\]$/.exec(s);
-    let tag = s.replace(/\[.*\]$/, "");
+    let tag = "";
+    const rawPredicates = [];
+    let inB = false;
+    let qChar = null;
+    let curPred = "";
+    for (let cIdx = 0; cIdx < s.length; cIdx++) {
+      const c = s[cIdx];
+      if (!qChar && (c === '"' || c === "'")) {
+        qChar = c;
+        if (inB) curPred += c;
+      } else if (qChar && c === qChar) {
+        qChar = null;
+        if (inB) curPred += c;
+      } else if (!qChar && c === "[") {
+        if (!inB) {
+          inB = true;
+          curPred = "";
+        } else {
+          curPred += c;
+        }
+      } else if (!qChar && c === "]") {
+        if (inB) {
+          inB = false;
+          rawPredicates.push(curPred.trim());
+          curPred = "";
+        }
+      } else if (!inB) {
+        tag += c;
+      } else {
+        curPred += c;
+      }
+    }
+    tag = tag.trim();
     if (!tag) tag = "*";
-    let index;
-    let allIndices;
-    let attributeFilter;
-    if (indexMatch) {
-      index = parseInt(indexMatch[1], 10);
-    } else if (wildcardMatch) {
-      allIndices = true;
-    } else if (attrMatch) {
-      const [, attrName, op, attrVal] = attrMatch;
-      attributeFilter = {
-        name: attrName,
-        ...attrVal !== void 0 ? { value: attrVal } : {},
-        ...op === "!=" ? { notEqual: true } : {}
-      };
+    if (inB || qChar !== null) {
+      steps.push({ tag: s, isRecursive });
+      continue;
+    }
+    const predicates = [];
+    let legacyIndex;
+    let legacyAllIndices;
+    let legacyAttrFilter;
+    let unreadablePredicate = false;
+    for (const rawP of rawPredicates) {
+      const parsedP = parseSinglePredicate(rawP);
+      if (!parsedP) {
+        unreadablePredicate = true;
+        break;
+      }
+      predicates.push(parsedP);
+      if (parsedP.kind === "index") {
+        legacyIndex = parsedP.index;
+      } else if (parsedP.kind === "all") {
+        legacyAllIndices = true;
+      } else if (parsedP.kind === "attrEquals" || parsedP.kind === "childEquals") {
+        legacyAttrFilter = {
+          name: parsedP.kind === "attrEquals" ? parsedP.name : parsedP.tag,
+          value: parsedP.value,
+          ...parsedP.notEqual ? { notEqual: true } : {}
+        };
+      }
     }
-    const step = { tag, isRecursive };
-    if (index !== void 0) step.index = index;
-    if (allIndices !== void 0) step.allIndices = allIndices;
-    if (attributeFilter !== void 0) step.attributeFilter = attributeFilter;
+    if (unreadablePredicate) {
+      steps.push({ tag: s, isRecursive });
+      continue;
+    }
+    const hasComplexPredicates = rawPredicates.length > 1 || predicates.some(
+      (p) => p.kind === "and" || p.kind === "or" || p.kind === "localNameEquals" || p.kind === "attrContains" || p.kind === "textContains" || p.kind === "attrStartsWith" || p.kind === "textEquals" || p.kind === "attrExists" || p.kind === "childExists"
+    );
+    const step = {
+      tag,
+      isRecursive,
+      ...legacyIndex !== void 0 ? { index: legacyIndex } : {},
+      ...legacyAllIndices !== void 0 ? { allIndices: legacyAllIndices } : {},
+      ...legacyAttrFilter !== void 0 ? { attributeFilter: legacyAttrFilter } : {},
+      ...hasComplexPredicates ? { predicates } : {}
+    };
     steps.push(step);
   }
-  return steps;
+  return steps;
+}
+function tryDecodeEmbeddedXml(content, opts = {}) {
+  const maxLines = opts.maxLines ?? 60;
+  if (!content || typeof content !== "string") return { decoded: false, text: content };
+  let candidate = content.trim();
+  const hadEntities = candidate.includes("&lt;") && candidate.includes("&gt;");
+  if (hadEntities) {
+    candidate = decodeXmlEntities(candidate).trim();
+  }
+  if (!candidate.startsWith("<") || !candidate.endsWith(">")) {
+    return { decoded: false, text: content };
+  }
+  try {
+    const { root } = parseXmlTree(candidate);
+    if (!root) return { decoded: false, text: content };
+    const formatted = serializeXmlNode(root, 0);
+    const lines = formatted.split("\n");
+    if (lines.length > maxLines) {
+      const bounded = lines.slice(0, maxLines);
+      bounded.push(`... (${lines.length - maxLines} more lines of decoded embedded XML elided; bounded)`);
+      return { decoded: true, text: bounded.join("\n") };
+    }
+    return { decoded: true, text: formatted };
+  } catch {
+    return { decoded: false, text: content };
+  }
 }
-function serializeXmlNode(node, indent = 0) {
+function serializeXmlNode(node, indent = 0, opts = {}) {
   const pad = "  ".repeat(indent);
   const attrParts = [];
   for (const [k, v] of Object.entries(node.attributes)) {
+    if (opts.decodeEmbedded) {
+      const decodedAttr = tryDecodeEmbeddedXml(v, { maxLines: 20 });
+      if (decodedAttr.decoded) {
+        attrParts.push(`${k}="[Embedded XML: ${v.length} chars]"`);
+        continue;
+      }
+    }
     attrParts.push(`${k}="${escapeXmlAttr(v)}"`);
   }
   const attrStr = attrParts.length > 0 ? " " + attrParts.join(" ") : "";
+  let textContent = node.text;
+  let decodedTextBanner = "";
+  if (opts.decodeEmbedded && textContent) {
+    const decoded = tryDecodeEmbeddedXml(
+      textContent,
+      opts.maxLines !== void 0 ? { maxLines: opts.maxLines } : {}
+    );
+    if (decoded.decoded) {
+      textContent = decoded.text.split("\n").map((l) => `${pad}  ${l}`).join("\n");
+      decodedTextBanner = `${pad}  <!-- [Decoded Embedded XML] -->
+`;
+    } else {
+      textContent = `${pad}  ${escapeXmlText(textContent)}`;
+    }
+  } else if (textContent) {
+    textContent = `${pad}  ${escapeXmlText(textContent)}`;
+  }
   if (node.children.length === 0 && !node.text) {
     return `${pad}<${node.tag}${attrStr}/>`;
   }
   if (node.children.length === 0) {
+    if (decodedTextBanner) {
+      return `${pad}<${node.tag}${attrStr}>
+${decodedTextBanner}${textContent}
+${pad}</${node.tag}>`;
+    }
     return `${pad}<${node.tag}${attrStr}>${escapeXmlText(node.text)}</${node.tag}>`;
   }
   const lines = [];
   lines.push(`${pad}<${node.tag}${attrStr}>`);
   if (node.text) {
-    lines.push(`${pad}  ${escapeXmlText(node.text)}`);
+    if (decodedTextBanner) {
+      lines.push(decodedTextBanner.trimEnd());
+      lines.push(textContent);
+    } else {
+      lines.push(`${pad}  ${escapeXmlText(node.text)}`);
+    }
   }
   for (const child of node.children) {
-    lines.push(serializeXmlNode(child, indent + 1));
+    lines.push(serializeXmlNode(child, indent + 1, opts));
   }
   lines.push(`${pad}</${node.tag}>`);
   return lines.join("\n");
@@ -6876,23 +7227,24 @@ function getAllDescendants(node) {
   walk(node);
   return desc;
 }
-function xmlNodeToJson(node) {
+function xmlNodeToJson(node, opts = {}) {
   const hasAttrs = Object.keys(node.attributes).length > 0;
   const hasChildren = node.children.length > 0;
   if (!hasChildren && !hasAttrs) {
-    return node.text;
-  }
-  if (!hasChildren) {
-    const result2 = {};
-    for (const [k, v] of Object.entries(node.attributes)) {
-      result2[`@${k}`] = v;
-    }
-    if (node.text) {
-      result2["#text"] = node.text;
+    if (opts.withLines) {
+      return {
+        lineStart: node.line,
+        lineEnd: node.lineEnd,
+        value: node.text
+      };
     }
-    return result2;
+    return node.text;
   }
   const result = {};
+  if (opts.withLines) {
+    result["lineStart"] = node.line;
+    result["lineEnd"] = node.lineEnd;
+  }
   for (const [k, v] of Object.entries(node.attributes)) {
     result[`@${k}`] = v;
   }
@@ -6907,22 +7259,29 @@ function xmlNodeToJson(node) {
   }
   for (const [tag, group] of childGroups) {
     if (group.length === 1) {
-      result[tag] = xmlNodeToJson(group[0]);
+      result[tag] = xmlNodeToJson(group[0], opts);
     } else {
-      result[tag] = group.map(xmlNodeToJson);
+      result[tag] = group.map((c) => xmlNodeToJson(c, opts));
     }
   }
   if (node.text) {
+    if (opts.decodeEmbedded) {
+      const decoded = tryDecodeEmbeddedXml(node.text, { maxLines: 50 });
+      if (decoded.decoded) {
+        result["#decodedXml"] = decoded.text;
+      }
+    }
     result["#text"] = node.text;
   }
   return result;
 }
-function queryXml(xmlText, pathStr) {
+function queryXml(xmlText, pathStr, opts = {}) {
   const { root } = parseXmlTree(xmlText);
   if (!root) {
     throw new Error("No valid XML root element found");
   }
-  const steps = parseXmlPath(pathStr);
+  const queryExpression = (opts.xpath ?? pathStr).trim();
+  const steps = parseXmlPath(queryExpression);
   if (steps.length === 0) {
     return { items: [root], fanned: false };
   }
@@ -6933,22 +7292,31 @@ function queryXml(xmlText, pathStr) {
     const step = steps[sIdx];
     if (step.attributeSelect !== void 0) {
       const attrVals = [];
+      const attrNodes = [];
       const attrName = step.attributeSelect;
       for (const cand of currentCandidates) {
         if (attrName === "*") {
-          pushAll(attrVals, Object.values(cand.attributes));
-        } else if (cand.attributes[attrName] !== void 0) {
-          attrVals.push(cand.attributes[attrName]);
+          for (const [k, v] of Object.entries(cand.attributes)) {
+            attrVals.push(v);
+            attrNodes.push({ value: v, node: cand, attrName: k });
+          }
+        } else {
+          const val = getAttrValue(cand, attrName);
+          if (val !== void 0) {
+            attrVals.push(val);
+            attrNodes.push({ value: val, node: cand, attrName });
+          }
         }
       }
       return {
         items: currentCandidates,
         attributeValues: attrVals,
+        attributeNodes: attrNodes,
         fanned: hasFanned || attrVals.length > 1
       };
     }
     const nextCandidates = [];
-    const evaluateOnCurrentNode = isAtRootLevel && !step.isRecursive && (step.tag === "*" || step.tag.toLowerCase() === root.tag.toLowerCase());
+    const evaluateOnCurrentNode = isAtRootLevel && !step.isRecursive && matchTag(root.tag, step.tag);
     isAtRootLevel = false;
     for (const cand of currentCandidates) {
       let targets;
@@ -6959,34 +7327,35 @@ function queryXml(xmlText, pathStr) {
       } else {
         targets = cand.children;
       }
-      let matching = targets.filter((c) => step.tag === "*" || c.tag.toLowerCase() === step.tag.toLowerCase());
-      if (step.attributeFilter) {
-        const af = step.attributeFilter;
-        matching = matching.filter((c) => {
-          const attrVal = c.attributes[af.name];
-          if (attrVal !== void 0) {
-            if (af.value === void 0) return true;
-            return af.notEqual ? attrVal !== af.value : attrVal === af.value;
-          }
-          const childElem = c.children.find((child) => child.tag.toLowerCase() === af.name.toLowerCase());
-          if (childElem !== void 0) {
-            if (af.value === void 0) return true;
-            return af.notEqual ? childElem.text !== af.value : childElem.text === af.value;
-          }
-          return af.notEqual === true;
-        });
-      }
-      if (step.index !== void 0) {
-        const idx = step.index < 0 ? matching.length + step.index : step.index;
-        if (idx >= 0 && idx < matching.length) {
-          nextCandidates.push(matching[idx]);
+      let matching = targets.filter((c) => matchTag(c.tag, step.tag));
+      const preds = step.predicates && step.predicates.length > 0 ? step.predicates : step.attributeFilter ? [
+        {
+          kind: "attrEquals",
+          name: step.attributeFilter.name,
+          value: step.attributeFilter.value ?? "",
+          ...step.attributeFilter.notEqual ? { notEqual: true } : {}
         }
-      } else {
-        if (step.allIndices || matching.length > 1 || step.attributeFilter !== void 0) {
+      ] : step.index !== void 0 ? [{ kind: "index", index: step.index }] : step.allIndices ? [{ kind: "all" }] : [];
+      for (const pred of preds) {
+        if (pred.kind === "index") {
+          const total = matching.length;
+          const idx = pred.index < 0 ? total + pred.index : pred.index;
+          if (idx >= 0 && idx < total) {
+            matching = [matching[idx]];
+          } else {
+            matching = [];
+          }
+        } else if (pred.kind === "all") {
           hasFanned = true;
+        } else {
+          const total = matching.length;
+          matching = matching.filter((node, idx) => evalPredicate(node, pred, idx, total));
         }
-        pushAll(nextCandidates, matching);
       }
+      if (matching.length > 1 || step.allIndices || step.attributeFilter !== void 0 || step.predicates && step.predicates.length > 0 && step.predicates[0]?.kind !== "index") {
+        hasFanned = true;
+      }
+      pushAll(nextCandidates, matching);
     }
     currentCandidates = nextCandidates;
   }
@@ -7220,6 +7589,11 @@ function runXmlQuery(opts) {
     emitErr4(`Could not read: ${opts.file}`);
     return 1;
   }
+  const queryPath = (opts.xpath ?? opts.path ?? "").trim();
+  if (!queryPath) {
+    emitErr4("Must provide a path or --xpath <expression>");
+    return 1;
+  }
   let head;
   try {
     head = opts.head !== void 0 ? requireNonNegativeStrictInt("--head", opts.head) : void 0;
@@ -7228,7 +7602,7 @@ function runXmlQuery(opts) {
     return 1;
   }
   try {
-    const result = queryXml(text, opts.path);
+    const result = queryXml(text, queryPath, { ...opts.xpath !== void 0 ? { xpath: opts.xpath } : {} });
     const fullSourceBytes = sumFileSizes([opts.file]);
     if (result.attributeValues !== void 0) {
       if (result.attributeValues.length === 0) {
@@ -7237,27 +7611,86 @@ function runXmlQuery(opts) {
           emit4(jsonText);
           recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
         } else {
-          emit4(`No attributes matched path: '${displaySafeText(opts.path)}'`);
+          emit4(`No attributes matched path: '${displaySafeText(queryPath)}'`);
         }
         return 0;
       }
-      if (!result.fanned) {
-        const val = result.attributeValues[0] ?? "";
-        const outText = opts.json === true ? displaySafeJson(val, 0) : val;
+      const totalCount2 = result.attributeValues.length;
+      const limitedNodes = result.attributeNodes !== void 0 ? head !== void 0 ? result.attributeNodes.slice(0, head) : result.attributeNodes : void 0;
+      const limited2 = head !== void 0 ? result.attributeValues.slice(0, head) : result.attributeValues;
+      const headTruncated2 = limited2.length < totalCount2;
+      if (!result.fanned && totalCount2 === 1) {
+        let val = limited2[0] ?? "";
+        if (opts.decodeEmbeddedXml) {
+          const decoded = tryDecodeEmbeddedXml(val);
+          if (decoded.decoded) val = decoded.text;
+        }
+        let outText = "";
+        if (opts.json === true) {
+          if (opts.withLines && limitedNodes && limitedNodes[0]) {
+            outText = displaySafeJson(
+              { value: val, lineStart: limitedNodes[0].node.line, lineEnd: limitedNodes[0].node.lineEnd },
+              0
+            );
+          } else {
+            outText = displaySafeJson(val, 0);
+          }
+        } else {
+          if (opts.withLines && limitedNodes && limitedNodes[0]) {
+            outText = `# Line: L${limitedNodes[0].node.line}
+${val}`;
+          } else {
+            outText = val;
+          }
+        }
         emit4(outText);
         recordReadStat("xml_query", fullSourceBytes, outText, opts.file);
         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);
+        let itemsToSerialize = limited2;
+        if (opts.withLines && limitedNodes) {
+          itemsToSerialize = limitedNodes.map((an) => {
+            let val = an.value;
+            if (opts.decodeEmbeddedXml) {
+              const decoded = tryDecodeEmbeddedXml(val);
+              if (decoded.decoded) val = decoded.text;
+            }
+            return {
+              value: val,
+              lineStart: an.node.line,
+              lineEnd: an.node.lineEnd
+            };
+          });
+        } else if (opts.decodeEmbeddedXml) {
+          itemsToSerialize = limited2.map((val) => {
+            const decoded = tryDecodeEmbeddedXml(val);
+            return decoded.decoded ? decoded.text : val;
+          });
+        }
+        const capped = guardJsonRows(itemsToSerialize);
+        const jsonText = displaySafeJson(
+          { items: capped.items, truncated: capped.truncated || headTruncated2, totalCount: totalCount2 },
+          0
+        );
         emit4(jsonText);
         recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
       } else {
-        const lines = limited2.map((item) => item);
+        const lines = [];
+        for (let i = 0; i < limited2.length; i++) {
+          let val = limited2[i] ?? "";
+          if (opts.decodeEmbeddedXml) {
+            const decoded = tryDecodeEmbeddedXml(val);
+            if (decoded.decoded) val = decoded.text;
+          }
+          const nodeInfo = limitedNodes ? limitedNodes[i] : void 0;
+          if (opts.withLines && nodeInfo) {
+            lines.push(`# Line: L${nodeInfo.node.line}
+${val}`);
+          } else {
+            lines.push(val);
+          }
+        }
         if (headTruncated2) {
           lines.push(`...(${totalCount2 - limited2.length} more items elided; use --head to see more)`);
         }
@@ -7273,19 +7706,30 @@ function runXmlQuery(opts) {
         emit4(jsonText);
         recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
       } else {
-        emit4(`No elements matched path: '${displaySafeText(opts.path)}'`);
+        emit4(`No elements matched path: '${displaySafeText(queryPath)}'`);
       }
       return 0;
     }
-    if (!result.fanned) {
+    if (!result.fanned && result.items.length === 1) {
       const node = result.items[0];
       if (opts.json === true) {
-        const jsonVal = xmlNodeToJson(node);
+        const jsonVal = xmlNodeToJson(node, {
+          ...opts.withLines ? { withLines: true } : {},
+          ...opts.decodeEmbeddedXml ? { decodeEmbedded: true } : {}
+        });
         const jsonText = displaySafeJson(jsonVal);
         emit4(jsonText);
         recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
       } else {
-        const xmlText = serializeXmlNode(node);
+        let xmlText = serializeXmlNode(
+          node,
+          0,
+          opts.decodeEmbeddedXml ? { decodeEmbedded: true } : {}
+        );
+        if (opts.withLines) {
+          xmlText = `# Lines: L${node.line}-L${node.lineEnd}
+${xmlText}`;
+        }
         emitGuarded(xmlText, "xml-query");
         recordReadStat("xml_query", fullSourceBytes, xmlText, opts.file);
       }
@@ -7295,13 +7739,32 @@ function runXmlQuery(opts) {
     const limited = head !== void 0 ? result.items.slice(0, head) : result.items;
     const headTruncated = limited.length < totalCount;
     if (opts.json === true) {
-      const jsonItems = limited.map(xmlNodeToJson);
+      const jsonItems = limited.map(
+        (n) => xmlNodeToJson(n, {
+          ...opts.withLines ? { withLines: true } : {},
+          ...opts.decodeEmbeddedXml ? { decodeEmbedded: true } : {}
+        })
+      );
       const capped = guardJsonRows(jsonItems);
-      const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount }, 0);
+      const jsonText = displaySafeJson(
+        { items: capped.items, truncated: capped.truncated || headTruncated, totalCount },
+        0
+      );
       emit4(jsonText);
       recordReadStat("xml_query", fullSourceBytes, jsonText, opts.file);
     } else {
-      const blocks = limited.map((node) => serializeXmlNode(node));
+      const blocks = limited.map((node) => {
+        let block = serializeXmlNode(
+          node,
+          0,
+          opts.decodeEmbeddedXml ? { decodeEmbedded: true } : {}
+        );
+        if (opts.withLines) {
+          block = `# Lines: L${node.line}-L${node.lineEnd}
+${block}`;
+        }
+        return block;
+      });
       if (headTruncated) {
         blocks.push(`...(${totalCount - limited.length} more elements elided; use --head to see more)`);
       }
@@ -8702,7 +9165,7 @@ function runLog(opts) {
 
 // src/read_inspect.ts
 init_define_import_meta_env();
-import * as fs11 from "node:fs";
+import * as fs10 from "node:fs";
 import * as path10 from "node:path";
 
 // src/archive_query.ts
@@ -9127,317 +9590,10 @@ function isNoteStale(note, dbPath = globalDbPath()) {
   return current === null || current !== note.fingerprint;
 }
 
-// src/sqlite_query.ts
-init_define_import_meta_env();
-import * as fs10 from "node:fs";
-var SQLITE_QUERY_ROW_CAP = 5e3;
-var SQLITE_MAGIC = Buffer.from([83, 81, 76, 105, 116, 101, 32, 102, 111, 114, 109, 97, 116, 32, 51, 0]);
-function readMagicBytes(filePath) {
-  let fd;
-  try {
-    fd = fs10.openSync(filePath, "r");
-  } catch {
-    return null;
-  }
-  try {
-    const buf = Buffer.alloc(SQLITE_MAGIC.length);
-    const bytesRead = fs10.readSync(fd, buf, 0, buf.length, 0);
-    return bytesRead === buf.length ? buf : null;
-  } catch {
-    return null;
-  } finally {
-    fs10.closeSync(fd);
-  }
-}
-function isSqliteFile(filePath) {
-  const magic = readMagicBytes(filePath);
-  return magic !== null && magic.equals(SQLITE_MAGIC);
-}
-function openReadonlySqlite(filePath) {
-  if (!fs10.existsSync(filePath)) {
-    throw new Error(`file not found: ${displaySafeText(filePath)}`);
-  }
-  if (!isSqliteFile(filePath)) {
-    throw new Error(`not a valid SQLite database (bad file header): ${displaySafeText(filePath)}`);
-  }
-  try {
-    return new Database(filePath, { readonly: true, fileMustExist: true });
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    throw new Error(`failed to open SQLite database: ${msg}`, { cause: e });
-  }
-}
-function quoteIdent(name) {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-function getSqliteSchema(filePath) {
-  const db = openReadonlySqlite(filePath);
-  try {
-    const objects = db.prepare("SELECT name, type FROM sqlite_master WHERE type IN ('table','view') AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\' ORDER BY name").all();
-    const tables = objects.map((o) => {
-      const columns = db.prepare(`PRAGMA table_info(${quoteIdent(o.name)})`).all().map(
-        (c) => ({
-          name: c.name,
-          type: c.type || "",
-          notNull: c.notnull === 1,
-          primaryKey: c.pk > 0,
-          defaultValue: c.dflt_value === null || c.dflt_value === void 0 ? null : String(c.dflt_value)
-        })
-      );
-      const indexes = db.prepare(`PRAGMA index_list(${quoteIdent(o.name)})`).all().map(
-        (idx) => {
-          const idxColumns = db.prepare(`PRAGMA index_info(${quoteIdent(idx.name)})`).all().map((c) => c.name);
-          return { name: idx.name, unique: idx.unique === 1, columns: idxColumns };
-        }
-      );
-      const foreignKeys = db.prepare(`PRAGMA foreign_key_list(${quoteIdent(o.name)})`).all().map((fk) => ({ table: fk.table, from: fk.from, to: fk.to }));
-      let rowCount;
-      try {
-        const row = db.prepare(`SELECT COUNT(*) AS c FROM ${quoteIdent(o.name)}`).get();
-        rowCount = row.c;
-      } catch {
-        rowCount = null;
-      }
-      return { name: o.name, kind: o.type === "view" ? "view" : "table", columns, indexes, foreignKeys, rowCount };
-    });
-    return { tables };
-  } finally {
-    db.close();
-  }
-}
-function formatSqliteSchema(result) {
-  if (result.tables.length === 0) return "(no tables or views found)";
-  return result.tables.map((t) => {
-    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(`  ${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(`    ${displaySafeText(idx.name)}${idx.unique ? " (unique)" : ""}: ${displaySafeText(idx.columns.join(", "))}`);
-      }
-    }
-    if (t.foreignKeys.length > 0) {
-      lines.push("  foreign keys:");
-      for (const fk of t.foreignKeys) {
-        lines.push(`    ${fk.from} -> ${fk.table}.${fk.to}`);
-      }
-    }
-    return lines.join("\n");
-  }).join("\n\n");
-}
-function getSqliteTables(filePath) {
-  const db = openReadonlySqlite(filePath);
-  try {
-    const objects = db.prepare(
-      // ESCAPE makes every `_` literal; see getSqliteSchema above. Here it costs three tables rather than one, since `%_fts_%` and `%_vec0_%` exist to hide the shadow tables FTS5 and sqlite-vec create beside a virtual table, and unescaped they also hide anything of the shape `my_ftsx_cache`.
-      "SELECT name, type FROM sqlite_master WHERE type IN ('table','view') AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\' AND name NOT LIKE '%\\_fts\\_%' ESCAPE '\\' AND name NOT LIKE '%\\_vec0\\_%' ESCAPE '\\' ORDER BY name"
-    ).all();
-    return objects.map((o) => {
-      let columnCount;
-      try {
-        const cols = db.prepare(`PRAGMA table_info(${quoteIdent(o.name)})`).all();
-        columnCount = cols.length;
-      } catch {
-        columnCount = 0;
-      }
-      let rowCount;
-      try {
-        const row = db.prepare(`SELECT COUNT(*) AS c FROM ${quoteIdent(o.name)}`).get();
-        rowCount = row.c;
-      } catch {
-        rowCount = null;
-      }
-      return {
-        name: o.name,
-        kind: o.type === "view" ? "view" : "table",
-        rowCount,
-        columnCount
-      };
-    });
-  } finally {
-    db.close();
-  }
-}
-function formatSqliteTables(tables) {
-  if (tables.length === 0) return "(no tables or views found)";
-  return tables.map((t) => {
-    const parts = [t.kind];
-    if (t.rowCount !== null) {
-      parts.push(`${t.rowCount.toLocaleString()} row${t.rowCount === 1 ? "" : "s"}`);
-    }
-    parts.push(`${t.columnCount} col${t.columnCount === 1 ? "" : "s"}`);
-    return `${displaySafeText(t.name)}  (${parts.join(", ")})`;
-  }).join("\n");
-}
-var FORBIDDEN_KEYWORDS = [
-  "INSERT",
-  "UPDATE",
-  "DELETE",
-  "DROP",
-  "ALTER",
-  "CREATE",
-  "ATTACH",
-  "DETACH",
-  "TRUNCATE",
-  "VACUUM",
-  "REINDEX",
-  "PRAGMA",
-  "BEGIN",
-  "COMMIT",
-  "ROLLBACK",
-  "SAVEPOINT",
-  "RELEASE",
-  "GRANT",
-  "REVOKE"
-];
-function stripSqlLiteralsAndComments(sql) {
-  let out = "";
-  let i = 0;
-  const n = sql.length;
-  while (i < n) {
-    const c = sql[i];
-    if (c === "'" || c === '"' || c === "`") {
-      const quote = c;
-      out += " ";
-      i++;
-      while (i < n) {
-        if (sql[i] === quote) {
-          if (sql[i + 1] === quote) {
-            i += 2;
-            continue;
-          }
-          i++;
-          break;
-        }
-        i++;
-      }
-      continue;
-    }
-    if (c === "[") {
-      out += " ";
-      i++;
-      while (i < n && sql[i] !== "]") i++;
-      if (i < n) i++;
-      continue;
-    }
-    if (c === "-" && sql[i + 1] === "-") {
-      while (i < n && sql[i] !== "\n") i++;
-      continue;
-    }
-    if (c === "/" && sql[i + 1] === "*") {
-      i += 2;
-      while (i < n && !(sql[i] === "*" && sql[i + 1] === "/")) i++;
-      i += 2;
-      continue;
-    }
-    out += c;
-    i++;
-  }
-  return out;
-}
-function validateReadOnlySelect(sql) {
-  const stripped = stripSqlLiteralsAndComments(sql);
-  const trimmed = stripped.trim();
-  if (trimmed === "") {
-    throw new Error("empty query");
-  }
-  const withoutTrailingSemicolons = trimmed.replace(/;+\s*$/, "");
-  if (withoutTrailingSemicolons.includes(";")) {
-    throw new Error("multiple statements are not allowed (sqlite-query accepts exactly one read-only SELECT statement)");
-  }
-  const upper = withoutTrailingSemicolons.toUpperCase();
-  if (!/^(SELECT|WITH)\b/.test(upper.trimStart())) {
-    throw new Error("only SELECT statements are allowed (sqlite-query is read-only)");
-  }
-  for (const kw of FORBIDDEN_KEYWORDS) {
-    if (new RegExp(`\\b${kw}\\b`).test(upper)) {
-      throw new Error(`statement contains forbidden keyword '${kw}' (sqlite-query only allows read-only SELECT queries)`);
-    }
-  }
-  if (/\bREPLACE\b(?!\s*\()/.test(upper)) {
-    throw new Error("statement contains forbidden keyword 'REPLACE' (sqlite-query only allows read-only SELECT queries)");
-  }
-}
-function normalizeSqliteScalar(value) {
-  if (typeof value === "bigint") {
-    return Number.isSafeInteger(Number(value)) ? Number(value) : value.toString();
-  }
-  return value;
-}
-function normalizeSqliteRow(row) {
-  const out = {};
-  for (const [k, v] of Object.entries(row)) out[k] = normalizeSqliteScalar(v);
-  return out;
-}
-function runReadOnlySqliteQuery(filePath, sql, opts = {}) {
-  validateReadOnlySelect(sql);
-  const rowCap = opts.rowCap ?? SQLITE_QUERY_ROW_CAP;
-  const db = openReadonlySqlite(filePath);
-  try {
-    let stmt;
-    try {
-      stmt = db.prepare(sql);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      throw new Error(`invalid SQL: ${msg}`, { cause: e });
-    }
-    if (!stmt.reader) {
-      throw new Error("only read-only SELECT statements are allowed (sqlite-query is read-only)");
-    }
-    stmt.safeIntegers(true);
-    let columns = [];
-    try {
-      columns = stmt.columns().map((c) => c.name);
-    } catch {
-      columns = [];
-    }
-    const rows = [];
-    let rowCapped = false;
-    for (const row of stmt.iterate()) {
-      if (rows.length >= rowCap) {
-        rowCapped = true;
-        break;
-      }
-      rows.push(normalizeSqliteRow(row));
-    }
-    return { columns, rows, rowCapped };
-  } finally {
-    db.close();
-  }
-}
-function formatSqliteCell(value) {
-  if (value === null || value === void 0) return "";
-  if (value instanceof Uint8Array) return `<blob ${value.length} bytes>`;
-  return String(value);
-}
-function formatSqliteQueryTable(result, opts = {}) {
-  if (result.columns.length === 0 && result.rows.length === 0) return "(no rows)";
-  const lines = [
-    result.columns.map(quoteCsvCellLocal).join(","),
-    ...result.rows.map((r) => result.columns.map((c) => quoteCsvCellLocal(formatSqliteCell(r[c]))).join(","))
-  ];
-  if (opts.headTruncated === true) {
-    lines.push("...(more rows elided; use --head to see more)");
-  }
-  if (result.rowCapped) {
-    lines.push(`...(result truncated at the ${SQLITE_QUERY_ROW_CAP}-row safety cap; narrow the query with WHERE/LIMIT for a complete result)`);
-  }
-  return lines.join("\n");
-}
-function quoteCsvCellLocal(cell) {
-  if (cell.includes(",") || cell.includes('"') || cell.includes("\n") || cell.includes("\r")) {
-    return `"${cell.replace(/"/g, '""')}"`;
-  }
-  return cell;
-}
-
 // src/read_inspect.ts
 function fileExists(p) {
   try {
-    fs11.statSync(p);
+    fs10.statSync(p);
     return true;
   } catch {
     return false;
@@ -10082,7 +10238,7 @@ function runListSections(opts) {
 
 // src/read_section.ts
 init_define_import_meta_env();
-import * as fs12 from "node:fs";
+import * as fs11 from "node:fs";
 import * as path11 from "node:path";
 var AMBIGUOUS_HEADING_LIMIT = 10;
 function literalHeadingExists(filePath, heading) {
@@ -10107,7 +10263,7 @@ function runSection(opts) {
   }
   const result = readSection(filePath, heading, readFileText);
   if (result === null) {
-    if (!fs12.existsSync(filePath)) {
+    if (!fs11.existsSync(filePath)) {
       return { text: `File not found: '${filePath}'`, code: 1 };
     }
     const ordSpec = /^(.*?)#(\d+)$/.exec(heading);
@@ -10162,7 +10318,39 @@ function runSectionMulti(specFilePath, resolvedFilePath, headings, opts) {
   let anyFound = false;
   const jsonOut = {};
   const textBlocks = [];
+  const includedSections = [];
   for (const heading of headings) {
+    const sectionResult = readSection(resolvedFilePath, heading, readFileText);
+    if (sectionResult !== null) {
+      const parent = includedSections.find(
+        (p) => sectionResult.lineStart >= p.lineStart && sectionResult.lineEnd <= p.lineEnd
+      );
+      if (parent !== void 0) {
+        anyFound = true;
+        const notice = `(already included in section '${parent.heading}', lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
+        if (opts.json === true) {
+          jsonOut[heading] = {
+            heading: sectionResult.heading,
+            subsumedBy: parent.heading,
+            lineStart: sectionResult.lineStart,
+            lineEnd: sectionResult.lineEnd,
+            notice
+          };
+          continue;
+        }
+        textBlocks.push(
+          `${heading}:
+# ${sectionResult.heading} \u2014 ${specFilePath}:${sectionResult.lineStart}-${sectionResult.lineEnd}
+${notice}`
+        );
+        continue;
+      }
+      includedSections.push({
+        heading: sectionResult.heading,
+        lineStart: sectionResult.lineStart,
+        lineEnd: sectionResult.lineEnd
+      });
+    }
     const sub = runSection({ ...opts, spec: `${specFilePath}::${heading}`, suppressStat: true });
     if (sub.code === 0) anyFound = true;
     if (opts.json === true) {
@@ -10181,12 +10369,48 @@ function runSectionCrossFile(pairs, opts) {
   let anyFound = false;
   const jsonOut = {};
   const textBlocks = [];
+  const includedByFile = /* @__PURE__ */ new Map();
   const distinctFiles = new Set(pairs.map((p) => p.file));
   const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  const resolvePath = (f) => opts.projectRoot !== void 0 && !path11.isAbsolute(f) ? path11.resolve(opts.projectRoot, f) : f;
   for (const { file, symbol: heading } of pairs) {
+    const resolved = resolvePath(file);
+    const sectionResult = readSection(resolved, heading, readFileText);
+    const key = keyFor({ file, symbol: heading });
+    const fileIncluded = includedByFile.get(resolved) ?? [];
+    if (sectionResult !== null) {
+      const parent = fileIncluded.find(
+        (p) => sectionResult.lineStart >= p.lineStart && sectionResult.lineEnd <= p.lineEnd
+      );
+      if (parent !== void 0) {
+        anyFound = true;
+        const notice = `(already included in section '${parent.heading}', lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
+        if (opts.json === true) {
+          jsonOut[key] = {
+            heading: sectionResult.heading,
+            subsumedBy: parent.heading,
+            lineStart: sectionResult.lineStart,
+            lineEnd: sectionResult.lineEnd,
+            notice
+          };
+          continue;
+        }
+        textBlocks.push(
+          `${key}:
+# ${sectionResult.heading} \u2014 ${file}:${sectionResult.lineStart}-${sectionResult.lineEnd}
+${notice}`
+        );
+        continue;
+      }
+      fileIncluded.push({
+        heading: sectionResult.heading,
+        lineStart: sectionResult.lineStart,
+        lineEnd: sectionResult.lineEnd
+      });
+      includedByFile.set(resolved, fileIncluded);
+    }
     const sub = runSection({ ...opts, spec: `${file}::${heading}`, suppressStat: true });
     if (sub.code === 0) anyFound = true;
-    const key = keyFor({ file, symbol: heading });
     if (opts.json === true) {
       jsonOut[key] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
       continue;
@@ -10194,7 +10418,6 @@ function runSectionCrossFile(pairs, opts) {
     textBlocks.push(`${key}:
 ${sub.text}`);
   }
-  const resolvePath = (f) => opts.projectRoot !== void 0 && !path11.isAbsolute(f) ? path11.resolve(opts.projectRoot, f) : f;
   const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
   if (anyFound) {
     const fullSourceBytes = sumFileSizes(Array.from(distinctFiles, resolvePath));
@@ -10210,7 +10433,7 @@ var FIND_SCAN_LIMIT2 = 2e4;
 var REFS_TOP_SCAN_LIMIT = 2e4;
 function fileExists2(p) {
   try {
-    fs13.statSync(p);
+    fs12.statSync(p);
     return true;
   } catch {
     return false;
@@ -10241,30 +10464,30 @@ function withPinnedReads(pins, fn) {
   }
 }
 function readPinnedBytes(p, pinned) {
-  const fd = fs13.openSync(p, fs13.constants.O_RDONLY);
+  const fd = fs12.openSync(p, fs12.constants.O_RDONLY);
   try {
-    const actual = fileIdentity(fs13.fstatSync(fd, { bigint: true }));
+    const actual = fileIdentity(fs12.fstatSync(fd, { bigint: true }));
     if (actual !== pinned) {
       throw new ConfinementIdentityError(
         `refused: "${p}" changed identity between validation and read (validated ${pinned}, opened ${actual}). The file was replaced or redirected after the confinement check, so the read was not performed.`
       );
     }
-    return fs13.readFileSync(fd);
+    return fs12.readFileSync(fd);
   } finally {
-    fs13.closeSync(fd);
+    fs12.closeSync(fd);
   }
 }
 function verifyPinnedIdentity(p, pinned) {
-  const fd = fs13.openSync(p, fs13.constants.O_RDONLY);
+  const fd = fs12.openSync(p, fs12.constants.O_RDONLY);
   try {
-    const actual = fileIdentity(fs13.fstatSync(fd, { bigint: true }));
+    const actual = fileIdentity(fs12.fstatSync(fd, { bigint: true }));
     if (actual !== pinned) {
       throw new ConfinementIdentityError(
         `refused: "${p}" changed identity between validation and read (validated ${pinned}, opened ${actual}). The file was replaced or redirected after the confinement check, so the read was not performed.`
       );
     }
   } finally {
-    fs13.closeSync(fd);
+    fs12.closeSync(fd);
   }
 }
 function verifyStillAbsent(p) {
@@ -10311,7 +10534,7 @@ function readFileText(p) {
       return null;
     }
     if (pinned !== void 0) return redactIfDotenv(p, decodeSource(readPinnedBytes(p, pinned)));
-    return redactIfDotenv(p, decodeSource(fs13.readFileSync(p)));
+    return redactIfDotenv(p, decodeSource(fs12.readFileSync(p)));
   } catch (err) {
     if (err instanceof ConfinementIdentityError) throw err;
     return null;
@@ -10329,9 +10552,9 @@ function readFileBytes(p) {
       if (bytes.length > MAX_ZIP_INPUT_BYTES) throw new ZipInputTooLargeError(p, bytes.length, MAX_ZIP_INPUT_BYTES);
       return bytes;
     }
-    const stat = fs13.statSync(p);
+    const stat = fs12.statSync(p);
     if (stat.size > MAX_ZIP_INPUT_BYTES) throw new ZipInputTooLargeError(p, stat.size, MAX_ZIP_INPUT_BYTES);
-    return fs13.readFileSync(p);
+    return fs12.readFileSync(p);
   } catch (err) {
     if (err instanceof ConfinementIdentityError || err instanceof ZipInputTooLargeError) throw err;
     return null;
@@ -10349,6 +10572,8 @@ function resolveBody(entry) {
 var STALE_WARNING = "\u26A0 STALE: index is older than the file on disk (worker hasn't reindexed yet \u2014 retry shortly, or read the file directly)";
 var DELETED_WARNING = "\u26A0 DELETED: this file is no longer on disk \u2014 what follows is what the index last saw of it";
 var DELETED_TAG = "\u26A0 DELETED: file no longer on disk";
+var STALE_TAG = "\u26A0 STALE: file changed on disk and could not be reindexed";
+var EMPTY_PATH_SET = /* @__PURE__ */ new Set();
 function fileIsGone(absPath) {
   if (!path12.isAbsolute(absPath)) return false;
   return fileIsAbsent(absPath);
@@ -10388,6 +10613,21 @@ function healStaleIndex(resolvedPath) {
   }
 }
 var STALE_CHECK_FILE_CAP = 25;
+function healStaleResultFiles(filePaths) {
+  const checked = /* @__PURE__ */ new Set();
+  const stillStale = /* @__PURE__ */ new Set();
+  let healed = false;
+  for (const raw of filePaths) {
+    if (checked.size >= STALE_CHECK_FILE_CAP) break;
+    if (checked.has(raw) || fileIsGone(raw)) continue;
+    checked.add(raw);
+    if (staleWarning(raw) === "") continue;
+    healStaleIndex(raw);
+    if (staleWarning(raw) === "") healed = true;
+    else stillStale.add(raw);
+  }
+  return { healed, stillStale };
+}
 function warnIfFilesStale(filePaths) {
   const checked = /* @__PURE__ */ new Set();
   let staleCount = 0;
@@ -10436,7 +10676,7 @@ function sumFileSizes(filePaths) {
   let total = 0;
   for (const fp of new Set(filePaths)) {
     try {
-      total += Math.min(fs13.statSync(fp).size, PER_FILE_COUNTERFACTUAL_CEILING);
+      total += Math.min(fs12.statSync(fp).size, PER_FILE_COUNTERFACTUAL_CEILING);
     } catch {
     }
   }
@@ -10507,7 +10747,13 @@ function runSymbol(opts) {
   }
   if (opts.file === void 0 && opts.projectRoot !== void 0) queryOpts.rootDir = opts.projectRoot;
   if (opts.file === void 0 && queryOpts.rootDir === void 0 && confinedRoot !== null) queryOpts.rootDir = confinedRoot;
-  const rawResults = querySymbols(queryOpts);
+  let rawResults = querySymbols(queryOpts);
+  let stillStale = EMPTY_PATH_SET;
+  if (opts.file === void 0) {
+    const heal = healStaleResultFiles(rawResults.map((s) => s.filePath));
+    stillStale = heal.stillStale;
+    if (heal.healed) rawResults = querySymbols(queryOpts);
+  }
   const preFilterCount = rawResults.length;
   const effectiveLimit = opts.limit ?? 100;
   const anyClientFilter = matchesGrep !== void 0 || excludeTests;
@@ -10589,6 +10835,7 @@ ${emptyIndexMessage(emptyIndexRoot)}`;
       // Only present when true, so a result set of live files stays byte-identical to what this
       // command has always emitted and only the genuinely-gone rows grow a field.
       ...fileIsGone(s.filePath) ? { deleted: true } : {},
+      ...stillStale.has(s.filePath) ? { stale: true } : {},
       ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: hasRealDocstring(s.docstring) } : {}
     }));
     const payload = { items, truncated: truncatedFlag, totalCount: trueTotal };
@@ -10599,7 +10846,8 @@ ${emptyIndexMessage(emptyIndexRoot)}`;
   const blocks = results.map((sym) => {
     const statsStr = formatStatsSuffix(refCounts, sym);
     const goneTag = fileIsGone(sym.filePath) ? `  ${DELETED_TAG}` : "";
-    const header = `# ${sym.name} (${sym.kind}) \u2014 ${formatSymbolLocation(toDisplayPath(symbolDisplayRoot, sym.filePath), sym.lineStart, sym.lineEnd)}${statsStr}${goneTag}`;
+    const staleTag = stillStale.has(sym.filePath) ? `  ${STALE_TAG}` : "";
+    const header = `# ${sym.name} (${sym.kind}) \u2014 ${formatSymbolLocation(toDisplayPath(symbolDisplayRoot, sym.filePath), sym.lineStart, sym.lineEnd)}${statsStr}${goneTag}${staleTag}`;
     const body = resolveBody(sym);
     const bodyLines = body.split(/\r?\n/);
     const preview = bodyLines.slice(0, SYMBOL_PREVIEW_LINES).join("\n");
@@ -10676,10 +10924,42 @@ function runRead(opts) {
     const scanned = querySymbols({ filePath: resolved, limit: FIND_SCAN_LIMIT2 }).map((s) => s.name);
     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 (fs13.existsSync(resolved)) {
-      const gap = symbolExtractorGap(file, resolved);
-      if (gap !== void 0) messages.push(gap);
+    else if (scanned.length > 0) {
+      if (/\.(yaml|yml)$/i.test(file)) {
+        messages.push(`Try: token-goat yaml-outline ${file}
+Query subtree: token-goat yaml-query ${file} '<path>'`);
+      } else if (/\.xml$/i.test(file)) {
+        messages.push(`Try: token-goat xml-outline ${file}
+Query subtree: token-goat xml-query ${file} '<path>'`);
+      } else if (/\.json$/i.test(file)) {
+        messages.push(`Try: token-goat json-outline ${file}
+Query subtree: token-goat json-query ${file} '<path>'`);
+      } else {
+        messages.push(`Try: token-goat outline ${file}`);
+      }
+    } else if (fs12.existsSync(resolved)) {
+      if (/\.(yaml|yml)$/i.test(file)) {
+        messages.push(
+          `'${file}' is a YAML file -- YAML keys below top level are not symbols; inspect structure or query values with:
+  token-goat yaml-outline ${file}
+  token-goat yaml-query ${file} '<path>'`
+        );
+      } else if (/\.xml$/i.test(file)) {
+        messages.push(
+          `'${file}' is an XML file -- inspect structure or query nodes with:
+  token-goat xml-outline ${file}
+  token-goat xml-query ${file} '<path>'`
+        );
+      } else if (/\.json$/i.test(file)) {
+        messages.push(
+          `'${file}' is a JSON file -- inspect structure or query values with:
+  token-goat json-outline ${file}
+  token-goat json-query ${file} '<path>'`
+        );
+      } else {
+        const gap = symbolExtractorGap(file, resolved);
+        if (gap !== void 0) messages.push(gap);
+      }
     }
     return { text: messages.join("\n"), code: 1 };
   }
@@ -11228,7 +11508,7 @@ async function runImageMeta(file) {
   if (!isImagePath(file)) {
     throw new Error(`Not an image file: ${file}`);
   }
-  const data = fs13.readFileSync(file);
+  const data = fs12.readFileSync(file);
   const bytes = data.length;
   let probe;
   try {
@@ -11240,15 +11520,17 @@ async function runImageMeta(file) {
     throw e;
   }
   if (probe === null) {
-    return { width: 0, height: 0, format: null, bytes, decodable: false, wouldShrink: false, shrunkBytes: null };
+    return { width: 0, height: 0, format: null, bytes, decodable: false, shrinkable: false, wouldShrink: false, shrunkBytes: null };
   }
-  const shrink = await shrinkImage(data, { sizeThresholdBytes: 0 });
+  const shrinkable = canShrinkFormat(probe.format);
+  const shrink = shrinkable ? await shrinkImage(data, { sizeThresholdBytes: 0 }) : null;
   return {
     width: probe.width,
     height: probe.height,
     format: probe.format,
     bytes,
     decodable: true,
+    shrinkable,
     wouldShrink: shrink !== null,
     shrunkBytes: shrink !== null ? shrink.shrunkBytes : null
   };
@@ -11260,7 +11542,7 @@ async function runImageText(file, lang) {
   if (!isImagePath(file)) {
     throw new Error(`Not an image file: ${file}`);
   }
-  const data = fs13.readFileSync(file);
+  const data = fs12.readFileSync(file);
   const ocr = await ocrImage(data, lang);
   if (ocr === null) {
     if (ocrIntegrityFailed()) {
@@ -11333,7 +11615,7 @@ function runGrep(opts) {
     if (activePins !== null) {
       let realDir;
       try {
-        realDir = foldRealpath(fs13.realpathSync(dir));
+        realDir = foldRealpath(fs12.realpathSync(dir));
       } catch {
         return;
       }
@@ -11342,12 +11624,12 @@ function runGrep(opts) {
       visitedRealDirs.add(realDir);
     }
     try {
-      for (const entry of fs13.readdirSync(dir)) {
+      for (const entry of fs12.readdirSync(dir)) {
         if (entry.startsWith(".")) continue;
         const full = path12.join(dir, entry);
         let lst;
         try {
-          lst = fs13.lstatSync(full);
+          lst = fs12.lstatSync(full);
         } catch {
           continue;
         }
@@ -11355,7 +11637,7 @@ function runGrep(opts) {
         if (lst.isSymbolicLink()) {
           let real;
           try {
-            real = fs13.realpathSync(full);
+            real = fs12.realpathSync(full);
           } catch {
             continue;
           }
@@ -11364,7 +11646,7 @@ function runGrep(opts) {
         }
         let stat;
         try {
-          stat = fs13.statSync(target);
+          stat = fs12.statSync(target);
         } catch {
           continue;
         }
@@ -11384,13 +11666,13 @@ function runGrep(opts) {
       emitErr4(`Path not found: ${searchPath}`);
       return 1;
     }
-    const stat = fs13.statSync(searchPath);
+    const stat = fs12.statSync(searchPath);
     if (stat.isDirectory()) {
       const pinned = activePins?.get(pinKey(path12.resolve(searchPath)));
       if (pinned !== void 0) verifyPin(searchPath, pinned);
       let boundaryReal;
       try {
-        boundaryReal = fs13.realpathSync(searchPath);
+        boundaryReal = fs12.realpathSync(searchPath);
       } catch (err) {
         if (pinned === void 0) {
           boundaryReal = path12.resolve(searchPath);
@@ -11456,7 +11738,7 @@ async function runSemantic(query, opts) {
   }
   const n = opts.limit !== void 0 && Number.isFinite(opts.limit) ? opts.limit : 20;
   if (opts.projectRoot !== void 0) {
-    if (!path12.isAbsolute(opts.projectRoot) || !fs13.existsSync(opts.projectRoot) || !fs13.statSync(opts.projectRoot).isDirectory()) {
+    if (!path12.isAbsolute(opts.projectRoot) || !fs12.existsSync(opts.projectRoot) || !fs12.statSync(opts.projectRoot).isDirectory()) {
       const message = `token-goat: projectRoot must be an absolute, existing directory, got '${opts.projectRoot}'`;
       if (opts.json === true) {
         return { text: displaySafeJson({ error: message }), code: 1 };
@@ -11465,6 +11747,39 @@ async function runSemantic(query, opts) {
     }
   }
   const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
+  let projectCoverage;
+  try {
+    projectCoverage = getEmbeddingCoverage(globalDbPath(), rootDir);
+  } catch {
+  }
+  if (opts.preflight === true) {
+    const preflight2 = await checkEmbeddingPreflight({
+      ...opts.warm !== void 0 ? { warm: opts.warm } : {},
+      projectRoot: rootDir,
+      ...projectCoverage !== void 0 ? { coverage: projectCoverage } : {}
+    });
+    if (opts.json === true) {
+      return { text: displaySafeJson(preflight2), code: preflight2.status === "ready" ? 0 : 1 };
+    }
+    const lines = [
+      `Semantic embedding status: ${preflight2.status.toUpperCase()}`,
+      `  Summary: ${preflight2.summary}`,
+      `  Config (indexing.embeddings_enabled): ${preflight2.configEnabled ? "enabled" : "disabled"}`,
+      `  ONNX runtime (onnxruntime-node): ${preflight2.runtimeAvailable ? "available" : "missing"}`,
+      `  Model files (~34 MB): ${preflight2.modelFilesPresent ? "present" : "missing"}`,
+      `  In-memory session: ${preflight2.modelWarmed ? "ready / warmed" : "not loaded"}`,
+      `  Project coverage: ${preflight2.embeddedFiles}/${countNoun(preflight2.indexedFiles, "file")} (${preflight2.coveragePercent}%)`
+    ];
+    if (preflight2.actionRequired) {
+      lines.push(`  Action: ${preflight2.actionRequired}`);
+    }
+    return { text: lines.join("\n"), code: preflight2.status === "ready" ? 0 : 1 };
+  }
+  const preflight = await checkEmbeddingPreflight({
+    ...opts.warm !== void 0 ? { warm: opts.warm } : {},
+    projectRoot: rootDir,
+    ...projectCoverage !== void 0 ? { coverage: projectCoverage } : {}
+  });
   const embeddingsEnabled = loadConfig().indexing?.embeddings_enabled ?? true;
   if (embeddingsEnabled && !isAvailable()) {
     console.warn(
@@ -11474,9 +11789,14 @@ async function runSemantic(query, opts) {
     console.warn(
       "Matching on meaning is off (indexing.embeddings_enabled / TOKEN_GOAT_EMBEDDINGS_ENABLED is disabled); these results come from keyword search alone."
     );
+  } else if (preflight.status !== "ready") {
+    console.warn(
+      `Matching on meaning is degraded (${preflight.summary}); these results come from keyword search alone.${preflight.actionRequired ? ` Action: ${preflight.actionRequired}` : ""}`
+    );
   }
   const overFetchForMerge = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
   let rawHits = [];
+  let searchSemanticError = null;
   if (embeddingsEnabled) {
     try {
       rawHits = await searchSemantic(
@@ -11488,12 +11808,15 @@ async function runSemantic(query, opts) {
         rootDir
       );
     } catch (e) {
-      console.warn(
-        `Matching on meaning is off (${extractErrorMessage(e)}); these results come from keyword search alone.`
-      );
+      searchSemanticError = extractErrorMessage(e);
+      if (preflight.status === "ready") {
+        console.warn(
+          `Matching on meaning is off (${searchSemanticError}); these results come from keyword search alone.`
+        );
+      }
     }
   }
-  if (rawHits.length === 0 && isAvailable()) {
+  if (rawHits.length === 0 && isAvailable() && preflight.status === "ready" && !searchSemanticError) {
     try {
       const enabled = loadConfig().indexing.embeddings_enabled;
       const { indexedFiles, embeddedFiles } = enabled ? getEmbeddingCoverage(globalDbPath(), rootDir) : { indexedFiles: 0, embeddedFiles: 0 };
@@ -11571,7 +11894,21 @@ async function runSemantic(query, opts) {
       }));
       const capped = guardJsonRows(items);
       const limitTruncated = hits.length < eligibleCount;
-      const text3 = displaySafeJson({ source, ...capped, truncated: capped.truncated || limitTruncated, totalCount: eligibleCount, ...candidatesClipped ? { totalCountIsFloor: true } : {} });
+      const text3 = displaySafeJson({
+        source,
+        ...capped,
+        truncated: capped.truncated || limitTruncated,
+        totalCount: eligibleCount,
+        ...candidatesClipped ? { totalCountIsFloor: true } : {},
+        ...preflight.status !== "ready" ? {
+          preflightStatus: preflight.status,
+          warning: preflight.summary,
+          ...preflight.actionRequired ? { actionRequired: preflight.actionRequired } : {}
+        } : searchSemanticError !== null ? {
+          preflightStatus: "degraded",
+          warning: `Matching on meaning failed (${searchSemanticError}); results come from keyword search alone.`
+        } : {}
+      });
       recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text3, query);
       return { text: text3, code: 0 };
     }
@@ -11634,19 +11971,54 @@ ${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 payload = indexEmpty ? {
+      source: "fts",
+      items: [],
+      truncated: false,
+      totalCount: 0,
+      indexEmpty: true,
+      hint: emptyIndexMessage(rootDir),
+      ...preflight.status !== "ready" ? {
+        preflightStatus: preflight.status,
+        warning: preflight.summary,
+        ...preflight.actionRequired ? { actionRequired: preflight.actionRequired } : {}
+      } : searchSemanticError !== null ? {
+        preflightStatus: "degraded",
+        warning: `Matching on meaning failed (${searchSemanticError}); results come from keyword search alone.`
+      } : {}
+    } : {
+      source: "fts",
+      items: [],
+      truncated: false,
+      totalCount: 0,
+      ...preflight.status !== "ready" ? {
+        preflightStatus: preflight.status,
+        warning: preflight.summary,
+        ...preflight.actionRequired ? { actionRequired: preflight.actionRequired } : {}
+      } : searchSemanticError !== null ? {
+        preflightStatus: "degraded",
+        warning: `Matching on meaning failed (${searchSemanticError}); results come from keyword search alone.`
+      } : {}
+    };
     const text2 = displaySafeJson(payload);
     return { text: text2, code: 1 };
   }
-  const text = indexEmpty ? `token-goat: no matches for '${query}'
+  let text = indexEmpty ? `token-goat: no matches for '${query}'
 ${emptyIndexMessage(rootDir)}` : `token-goat: no matches for '${query}'`;
+  if (preflight.status !== "ready") {
+    text += `
+(note: semantic indexing is degraded [${preflight.status}]: ${preflight.summary}${preflight.actionRequired ? ` \u2014 ${preflight.actionRequired}` : ""})`;
+  } else if (searchSemanticError !== null) {
+    text += `
+(note: semantic matching degraded: ${searchSemanticError}; results come from keyword search alone)`;
+  }
   return { text, code: 1 };
 }
 
 // src/read_spec.ts
 function fileExists3(p) {
   try {
-    return fs14.statSync(p).isFile();
+    return fs13.statSync(p).isFile();
   } catch {
     return false;
   }
@@ -12059,6 +12431,7 @@ export {
   runImpact,
   runAsk,
   load,
+  queryJson,
   runCsvQuery,
   runCsvProfile,
   runJsonOutline,