pi-quiver 5.2.4 → 5.4.0

package/dist/bin/pi-quiver.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 // bin/pi-quiver.ts
-import { realpathSync } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join4, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { resolve as resolve2 } from "node:path";
 
 // lib/fetch-core.ts
 import { mkdirSync, writeFileSync, createWriteStream } from "node:fs";
@@ -318,8 +319,8 @@ function binaryExtension(contentType) {
   return sub || "bin";
 }
 function writeChunk(stream, b) {
-  return new Promise((resolve3, reject) => {
-    stream.write(b, (err) => err ? reject(err) : resolve3());
+  return new Promise((resolve4, reject) => {
+    stream.write(b, (err) => err ? reject(err) : resolve4());
   });
 }
 async function pumpToFile(stream, reader, prefix, exhausted) {
@@ -343,7 +344,7 @@ async function pumpToFile(stream, reader, prefix, exhausted) {
     await writeChunk(stream, chunk);
     bytes += chunk.length;
   }
-  await new Promise((resolve3, reject) => stream.end((err) => err ? reject(err) : resolve3()));
+  await new Promise((resolve4, reject) => stream.end((err) => err ? reject(err) : resolve4()));
   return { bytes, truncated };
 }
 async function collectBody(res, contentType, raw) {
@@ -516,93 +517,380 @@ async function fetchUrl(opts) {
 }
 
 // lib/doc-to-md-core.ts
-import { existsSync, mkdirSync as mkdirSync2, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync2, mkdtempSync, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
 import { spawn } from "node:child_process";
-import { homedir, tmpdir as tmpdir2 } from "node:os";
-import { basename, dirname, extname, join as join2, resolve } from "node:path";
-import { createHash as createHash2 } from "node:crypto";
+import { homedir, tmpdir as tmpdir3 } from "node:os";
+import { basename, dirname, extname as extname3, join as join3, resolve as resolve2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { extractText, getDocumentProxy } from "unpdf";
-var DEFAULT_PYMUPDF_VERSION = "1.27.2.3";
-var WARM_TIMEOUT_DEFAULT = 12e4;
-var CONVERT_TIMEOUT_DEFAULT = 6e4;
-var SOFFICE_TIMEOUT_DEFAULT = 12e4;
-var STDERR_CAP = 1e6;
-var INLINE_MAX_BYTES2 = 32e3;
-var INLINE_MAX_LINES2 = 1e3;
-var PREVIEW_LINES2 = 60;
-var PREVIEW_MAX_BYTES2 = 4e3;
-var VERSION_RE = /^\d+(\.\d+)*$/;
-var PAGE_SEP = "\n\n---\n\n";
-var OUTPUT_MAX_BYTES = 2e7;
-var DEGRADED_MARKER = "[Note: degraded extraction via unpdf \u2014 structure (tables/headings) not preserved]";
-function parseConfig(env) {
-  const version = env.PI_DOC_TO_MD_PYMUPDF_VERSION ?? DEFAULT_PYMUPDF_VERSION;
-  if (!VERSION_RE.test(version)) {
-    throw new Error(`PI_DOC_TO_MD_PYMUPDF_VERSION must be digits and dots (got "${version}")`);
+
+// lib/doc-to-md-bundle.ts
+import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { extname, join as join2, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+function ownedPattern(stem) {
+  const esc = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${esc}-(p|s)\\d+-\\d+\\.[a-z0-9]+$`);
+}
+var IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
+function imageTarget(m) {
+  const target = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "").trim();
+  const destination = target.replace(/^<([\s\S]*)>$/, "$1").trim();
+  return m[2] === void 0 ? destination : destination.replace(/\s+(?:"[^"]*"|'[^']*'|\([^)]*\))$/, "");
+}
+function linkedFiles(md) {
+  const out = [];
+  for (const m of md.matchAll(IMG_LINK_RE)) {
+    const target = imageTarget(m);
+    if (!target.startsWith("images/")) continue;
+    const file = target.slice("images/".length);
+    if (file && file !== "." && file !== ".." && /^[^/\\]+$/.test(file)) out.push(file);
   }
-  const num = (key, def) => {
-    const raw = env[key];
-    if (raw === void 0) return def;
-    const n = Number.parseInt(raw, 10);
-    if (!Number.isInteger(n) || n <= 0) throw new Error(`${key} must be a positive integer (got "${raw}")`);
-    return n;
-  };
-  return {
-    pymupdfVersion: version,
-    warmTimeoutMs: num("PI_DOC_TO_MD_WARM_TIMEOUT_MS", WARM_TIMEOUT_DEFAULT),
-    convertTimeoutMs: num("PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", CONVERT_TIMEOUT_DEFAULT),
-    sofficeTimeoutMs: num("PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", SOFFICE_TIMEOUT_DEFAULT)
-  };
+  return out;
 }
-var SUPPORTED = { ".pdf": "pdf", ".docx": "docx", ".pptx": "pptx" };
-function classifyInput(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  const t = SUPPORTED[ext];
-  if (!t) throw new Error(`Unsupported file type "${ext || "(none)"}"; supported: .pdf, .docx, .pptx`);
-  return t;
+function openBundle(root, stem, overwrite) {
+  mkdirSync2(root, { recursive: true });
+  const mdPath = join2(root, `${stem}.md`);
+  const lockPath = `${mdPath}.lock`;
+  let fd;
+  try {
+    fd = openSync(lockPath, "wx");
+  } catch (e) {
+    if (e.code === "EEXIST") throw new Error(`Another conversion owns ${mdPath} (lock: ${lockPath}); if no conversion is running, delete the lock`);
+    throw new Error(`Output directory not writable: ${root} (${e.message})`);
+  }
+  closeSync(fd);
+  const imagesDir = join2(root, "images");
+  try {
+    if (existsSync(mdPath)) {
+      if (!overwrite) throw new Error(`Output exists: ${mdPath} (pass overwrite)`);
+      const owned = ownedPattern(stem);
+      const linked = new Set(linkedFiles(readFileSync(mdPath, "utf8")));
+      unlinkSync(mdPath);
+      if (existsSync(imagesDir)) {
+        for (const f of readdirSync(imagesDir)) if (owned.test(f) || linked.has(f)) rmSync(join2(imagesDir, f), { force: true });
+      }
+    }
+    const lockId = randomBytes(6).toString("hex");
+    const stagingDir = join2(imagesDir, `.stage-${lockId}`);
+    mkdirSync2(stagingDir, { recursive: true });
+    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, manifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
+  } catch (e) {
+    rmSync(lockPath, { force: true });
+    throw e;
+  }
 }
-function applyGate2(body) {
-  const bytes = Buffer.byteLength(body, "utf8");
-  const lines = body.length ? body.split("\n").length : 0;
-  const spill = body.length > 0 && (bytes > INLINE_MAX_BYTES2 || lines > INLINE_MAX_LINES2);
-  return { spill, bytes, lines };
+function publishStaged(b) {
+  const out = /* @__PURE__ */ new Map();
+  if (!existsSync(b.stagingDir)) return out;
+  for (const dir of readdirSync(b.stagingDir).sort()) {
+    const m = dir.match(/^p(\d+)$/);
+    if (!m) continue;
+    const pageDir = join2(b.stagingDir, dir);
+    if (!existsSync(join2(pageDir, ".done"))) {
+      rmSync(pageDir, { recursive: true, force: true });
+      continue;
+    }
+    const page = Number(m[1]);
+    const files = readdirSync(pageDir).filter((f) => f !== ".done" && statSync(join2(pageDir, f)).isFile()).sort();
+    const names = [];
+    files.forEach((f, i) => {
+      const name = `${b.stem}-p${page}-${i + 1}${extname(f).toLowerCase()}`;
+      renameSync(join2(pageDir, f), join2(b.imagesDir, name));
+      b.manifest.add(name);
+      b.sourceMap.set(`${dir}/${f}`, `images/${name}`);
+      names.push(name);
+    });
+    rmSync(pageDir, { recursive: true, force: true });
+    out.set(page, names);
+  }
+  return out;
 }
-function withMarker(md, degraded) {
-  return degraded ? `${DEGRADED_MARKER}
-
-${md}` : md;
+function publishSheetImages(b) {
+  for (const f of readdirSync(b.stagingDir).sort()) {
+    if (!/^s\d+-\d+\.[a-z0-9]+$/i.test(f)) continue;
+    const name = `${b.stem}-${f.toLowerCase()}`;
+    renameSync(join2(b.stagingDir, f), join2(b.imagesDir, name));
+    b.manifest.add(name);
+    b.sourceMap.set(f, `images/${name}`);
+  }
+}
+function rewriteImageLinks(md, sourceMap) {
+  return md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
+    const target = imageTarget([whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted]);
+    const dest = sourceMap.get(target) ?? sourceMap.get(target.replace(/^\.\//, ""));
+    return dest ? whole.replace(mdAngle === void 0 ? target : `<${mdAngle}>`, dest) : whole;
+  });
 }
-function pagesToMarkdown(pages) {
-  return pages.map((p) => p.trim()).filter((p) => p.length > 0).join(PAGE_SEP);
+function validateImageLinks(md, manifest) {
+  for (const m of md.matchAll(IMG_LINK_RE)) {
+    const target = imageTarget(m);
+    if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
+  }
 }
-function tempFilePath2(inputPath, ext) {
-  const dir = join2(tmpdir2(), "pi-doc-to-md");
+function commitBundle(b, markdown) {
+  const tmp = `${b.mdPath}.tmp`;
+  writeFileSync2(tmp, markdown, "utf8");
+  renameSync(tmp, b.mdPath);
+  try {
+    fs.rmSync(b.stagingDir, { recursive: true, force: true });
+  } catch {
+  }
+  try {
+    fs.rmSync(b.lockPath, { force: true });
+  } catch {
+  }
+}
+function abortBundle(b) {
+  for (const f of b.manifest) rmSync(join2(b.imagesDir, f), { force: true });
+  rmSync(`${b.mdPath}.tmp`, { force: true });
+  rmSync(b.stagingDir, { recursive: true, force: true });
+  rmSync(b.lockPath, { force: true });
+}
+function tempBundleRoot() {
+  const dir = join2(tmpdir2(), `pi-quiver-doc-to-md-${randomBytes(4).toString("hex")}`);
   mkdirSync2(dir, { recursive: true });
-  const base = basename(inputPath).replace(/\.[^.]+$/, "").replace(/[^\w.-]+/g, "-");
-  const hash = createHash2("sha1").update(resolve(inputPath)).digest("hex").slice(0, 8);
-  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  return join2(dir, `${stamp}-${base}-${hash}.${ext}`);
+  return resolve(dir);
 }
-function spillToFile2(inputPath, body) {
-  const file = tempFilePath2(inputPath, "md");
-  writeFileSync2(file, `${body}
-`, "utf8");
-  return file;
+
+// lib/doc-to-md-handle.ts
+var TITLE_MAX = 80;
+var NOTE_MAX_LINES = 5;
+var NOTE_MAX_CHARS = 200;
+var META_MAX_CHARS = 120;
+function formatSize2(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
-function buildPreview2(body) {
-  let preview = body.split("\n").slice(0, PREVIEW_LINES2).join("\n");
-  if (preview.length > PREVIEW_MAX_BYTES2) {
-    preview = `${preview.slice(0, PREVIEW_MAX_BYTES2)}
-\u2026[preview truncated]`;
+var trunc = (s, max) => s.length > max ? `${s.slice(0, max - 3)}...` : s;
+function compactRanges(nums, maxEntries = 20) {
+  const sorted = [...new Set(nums)].sort((a, b) => a - b);
+  const parts = [];
+  for (let i = 0; i < sorted.length; ) {
+    let j = i;
+    while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j++;
+    parts.push(j > i ? `${sorted[i]}-${sorted[j]}` : `${sorted[i]}`);
+    i = j + 1;
   }
-  return preview;
+  if (parts.length <= maxEntries) return parts.join(", ");
+  return `${parts.slice(0, maxEntries).join(", ")} (+${parts.length - maxEntries} more)`;
+}
+function scanOutline(md, max) {
+  const entries = [];
+  let total = 0, inFence = false;
+  md.split("\n").forEach((raw, i) => {
+    const line = raw.replace(/\r$/, "");
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      return;
+    }
+    if (inFence) return;
+    const m = line.match(/^(#{1,6}) (.*)$/);
+    if (!m) return;
+    total++;
+    if (entries.length < max) entries.push({ line: i + 1, level: m[1].length, title: trunc(m[2].trim(), TITLE_MAX) });
+  });
+  return { entries, total };
+}
+function outlineLines(entries, total) {
+  if (entries.length === 0) return [];
+  const width = Math.max(5, Math.max(...entries.map((e) => `L${e.line}`.length)) + 2);
+  const out = ["Outline:", ...entries.map((e) => `  ${`L${e.line}`.padEnd(width)}${"#".repeat(e.level)} ${trunc(e.title, TITLE_MAX)}`)];
+  if (total > entries.length) out.push(`  (+${total - entries.length} more)`);
+  return out;
+}
+function formatHandle(h) {
+  const lines = [`Saved-To: ${h.savedTo}`];
+  if (h.imagesDir && h.imageCount > 0) lines.push(`Images-Dir: ${h.imagesDir}`);
+  lines.push(`Type: ${h.type}   Engine: ${h.engine}   Tier: ${h.tier}`);
+  lines.push(`Page-Count: ${h.pageCount ?? "?"}   Pages: ${h.pages ? compactRanges(h.pages) : "all"}   Images: ${h.imageCount}   Size: ${formatSize2(h.bytes)} / ${h.lines} lines`);
+  if (h.degraded) lines.push(`Degraded: ${h.degraded}`);
+  if (h.fallbackReason) lines.push(`Fallback-Reason: ${h.fallbackReason}`);
+  const fe = [];
+  if (h.failedPages.length) fe.push(`Failed-Pages: ${compactRanges(h.failedPages)}`);
+  if (h.emptyPages.length) fe.push(`Empty-Pages: ${compactRanges(h.emptyPages)}`);
+  if (fe.length) lines.push(fe.join("    "));
+  h.notes.slice(0, NOTE_MAX_LINES).forEach((n, i) => lines.push(`${i === 0 ? "Notes: " : "       "}${trunc(n, NOTE_MAX_CHARS)}`));
+  lines.push(...outlineLines(h.outline, h.outlineTotal));
+  return lines.join("\n");
+}
+function formatInfoHandle(i, max) {
+  if (i.sheets) {
+    const lines2 = [`Type: ${i.type}   Sheets: ${i.sheetsTotal}`];
+    for (const s of i.sheets.slice(0, max)) {
+      const dims = `rows=${s.rows ?? "?"} cols=${s.cols ?? "?"}`;
+      const hidden = s.hiddenRows || s.hiddenCols ? ` hiddenRows=${s.hiddenRows} hiddenCols=${s.hiddenCols}` : "";
+      lines2.push(`  ${trunc(s.name, TITLE_MAX)}  ${s.hidden ? "hidden " : ""}${dims}${hidden}`);
+    }
+    if (i.sheetsTotal > max) lines2.push(`  (+${i.sheetsTotal - max} more)`);
+    return lines2.join("\n");
+  }
+  const lines = [`Type: ${i.type}   Page-Count: ${i.pageCount ?? "?"}   Backend: ${i.backend}`];
+  const meta = Object.entries(i.metadata).filter(([, v]) => v).map(([k, v]) => `${k[0].toUpperCase()}${k.slice(1)}: ${trunc(v, META_MAX_CHARS)}`);
+  if (meta.length) lines.push(meta.join("   "));
+  if (i.toc.length) {
+    lines.push("TOC:", ...i.toc.slice(0, max).map((t) => `  L${t.level} ${trunc(t.title, TITLE_MAX)} (p${t.page})`));
+    if (i.tocTotal > max) lines.push(`  (+${i.tocTotal - max} more)`);
+  }
+  return lines.join("\n");
+}
+
+// lib/doc-to-md-options.ts
+import { extname as extname2 } from "node:path";
+var UsageError = class extends Error {
+};
+var MIN_PYMUPDF4LLM = "1.27.0";
+var VERSION_RE = /^\d+(\.\d+)*$/;
+var DOC_TO_MD_OPTIONS = [
+  { key: "path", flag: null, type: "string", default: null, settable: false, help: "Local .pdf .docx .pptx .xlsx .xls file" },
+  { key: "info", flag: "--info", type: "bool", default: false, settable: false, help: "Inspect only (page count, metadata, TOC or sheet inventory); no bundle" },
+  { key: "pages", flag: "--pages", type: "pages", default: null, settable: false, help: 'Inclusive 1-based pages, e.g. "12-15" or "3,7,10-12" (PDF/DOCX/PPTX only); default all' },
+  { key: "outputDir", flag: "--output-dir", type: "string", default: null, settable: false, help: "Bundle root for <stem>.md + images/; default a per-call temp dir" },
+  { key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
+  { key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 6e4, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier; also the unpdf tier" },
+  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier; also info on PDF" },
+  { key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice" },
+  { key: "excelTimeoutMs", flag: "--excel-timeout", type: "int", default: 6e4, settable: true, help: "Excel child (both openpyxl loads); also info on Excel" },
+  { key: "warmTimeoutMs", flag: "--warm-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_WARM_TIMEOUT_MS", help: "Absolute backend discovery/bootstrap deadline (first call per process)" },
+  { key: "pymupdfVersion", flag: "--pymupdf-version", type: "version", default: "1.27.2.3", settable: true, env: "PI_DOC_TO_MD_PYMUPDF_VERSION", help: "pymupdf4llm pin (>= 1.27.0)" },
+  { key: "imageDpi", flag: "--image-dpi", type: "int", default: 150, settable: true, help: "Render DPI for page images" },
+  { key: "imageFormat", flag: "--image-format", type: "enum", default: "png", settable: true, enumValues: ["png", "jpg"], help: "Rendered image format (embedded images keep their native extension)" },
+  { key: "maxCellsPerSheet", flag: "--max-cells-per-sheet", type: "int", default: 5e4, settable: true, help: "rows x cols budget per worksheet" },
+  { key: "maxOutputBytes", flag: "--max-output-bytes", type: "int", default: 2e7, settable: true, help: "Child stdout cap in bytes" },
+  { key: "outlineMaxEntries", flag: "--outline-max-entries", type: "int", default: 40, settable: true, help: "Heading outline / TOC / sheet inventory cap in the handle" }
+];
+var TUNABLE_DEFAULTS = Object.fromEntries(
+  DOC_TO_MD_OPTIONS.filter((d) => d.settable).map((d) => [d.key, d.default])
+);
+function versionAtLeast(v, min) {
+  const a = v.split(".").map(Number), b = min.split(".").map(Number);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0, y = b[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return true;
+}
+function coerceValue(d, raw, fromString = false) {
+  switch (d.type) {
+    case "int": {
+      const n = fromString && typeof raw === "string" ? Number(raw) : raw;
+      return typeof n === "number" && Number.isInteger(n) && n > 0 ? { ok: true, value: n } : { ok: false, reason: "must be a positive integer" };
+    }
+    case "bool":
+      return typeof raw === "boolean" ? { ok: true, value: raw } : { ok: false, reason: "must be true or false" };
+    case "enum":
+      return typeof raw === "string" && d.enumValues.includes(raw) ? { ok: true, value: raw } : { ok: false, reason: `must be one of ${d.enumValues.join(", ")}` };
+    case "version":
+      if (typeof raw !== "string" || !VERSION_RE.test(raw)) return { ok: false, reason: "must be digits and dots" };
+      if (!versionAtLeast(raw, MIN_PYMUPDF4LLM)) return { ok: false, reason: `must be >= ${MIN_PYMUPDF4LLM}` };
+      return { ok: true, value: raw };
+    case "string":
+      return typeof raw === "string" && raw.length > 0 ? { ok: true, value: raw } : { ok: false, reason: "must be a non-empty string" };
+    case "pages":
+      return typeof raw === "string" ? { ok: true, value: parsePages(raw) } : { ok: false, reason: "must be a string" };
+  }
+}
+function coerceDocToMdSettings(raw, warn = console.warn) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) {
+    const d = DOC_TO_MD_OPTIONS.find((o) => o.key === k);
+    if (!d || !d.settable) continue;
+    const c = coerceValue(d, v);
+    if (!c.ok) {
+      warn(`pi-quiver: quiver.docToMd.${k} ${c.reason}; ignored.`);
+      continue;
+    }
+    out[k] = c.value;
+  }
+  return out;
+}
+function parsePages(spec) {
+  const out = /* @__PURE__ */ new Set();
+  const parts = spec.split(",").map((s) => s.trim());
+  if (parts.length === 0 || parts.some((p) => p === "")) throw new UsageError(`invalid --pages "${spec}": expected e.g. "12-15" or "3,7,10-12"`);
+  for (const p of parts) {
+    const m = p.match(/^(\d+)(?:-(\d+))?$/);
+    if (!m) throw new UsageError(`invalid --pages "${spec}": bad token "${p}"`);
+    const a = Number(m[1]), b = m[2] === void 0 ? a : Number(m[2]);
+    if (a < 1 || b < a) throw new UsageError(`invalid --pages "${spec}": pages are 1-based and ranges ascend`);
+    for (let i = a; i <= b; i++) out.add(i);
+  }
+  return [...out].sort((x, y) => x - y);
+}
+function sanitizeStem(base) {
+  const s = base.replace(/[^A-Za-z0-9._-]+/g, "_");
+  return s.length ? s : "document";
+}
+var SUPPORTED = { ".pdf": "pdf", ".docx": "docx", ".pptx": "pptx", ".xlsx": "xlsx", ".xls": "xls" };
+function classifyInput(filePath) {
+  const t = SUPPORTED[extname2(filePath).toLowerCase()];
+  if (!t) throw new Error(`Unsupported file type "${extname2(filePath) || "(none)"}"; supported: .pdf, .docx, .pptx, .xlsx, .xls`);
+  return t;
+}
+function resolveOptions(perCall, settings, env) {
+  const out = { path: perCall.path };
+  for (const d of DOC_TO_MD_OPTIONS) {
+    if (d.key === "path") continue;
+    let value = d.default;
+    if (d.env && env[d.env] !== void 0) {
+      const c = coerceValue(d, env[d.env], true);
+      if (!c.ok) throw new UsageError(`${d.env} ${c.reason} (got "${env[d.env]}")`);
+      value = c.value;
+    }
+    if (d.settable && settings[d.key] !== void 0) value = settings[d.key];
+    const pc = perCall[d.key];
+    if (pc !== void 0 && pc !== null) {
+      const c = coerceValue(d, pc);
+      if (!c.ok) throw new UsageError(`${d.flag} ${c.reason}`);
+      value = c.value;
+    }
+    out[d.key] = value;
+  }
+  const o = out;
+  if (o.info && (o.pages !== null || o.outputDir !== null || o.overwrite)) {
+    throw new UsageError("--info cannot be combined with --pages, --output-dir or --overwrite");
+  }
+  return o;
+}
+function renderHelp() {
+  const row = (d) => `  ${(d.flag ?? "<path>").padEnd(26)} ${d.help}${d.default !== null && d.key !== "info" && d.key !== "overwrite" ? ` (default ${d.default})` : ""}`;
+  return [
+    "Usage: pi-quiver doc-to-md [flags] <path>",
+    "",
+    "Per-call:",
+    ...DOC_TO_MD_OPTIONS.filter((d) => !d.settable).map(row),
+    "",
+    "Tunables (also settable under quiver.docToMd in settings.json; per-call > settings > default):",
+    ...DOC_TO_MD_OPTIONS.filter((d) => d.settable).map(row),
+    "",
+    "Result: a handle (Saved-To, Images-Dir, Page-Count, Outline ...). Read the Saved-To file for the Markdown.",
+    "Exit codes: 0 success, 1 runtime error, 2 usage error."
+  ].join("\n");
+}
+
+// lib/doc-to-md-core.ts
+var PACKAGE_PINS = { pymupdf4llm: TUNABLE_DEFAULTS.pymupdfVersion, openpyxl: "3.1.5", xlrd: "2.0.2", pillow: "12.3.0" };
+var KILL_GRACE_MS = 2e3;
+var VENV_DIR_NAME = "doc-to-md-venv-v2";
+var LEGACY_VENV_DIR_NAME = "pymupdf-venv";
+var STDERR_CAP = 1e6;
+var OUTPUT_MAX_BYTES = 2e7;
+function withArgs(cfg) {
+  return ["--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--with", `openpyxl==${PACKAGE_PINS.openpyxl}`, "--with", `xlrd==${PACKAGE_PINS.xlrd}`, "--with", `pillow==${PACKAGE_PINS.pillow}`];
+}
+function pipInstallArgs(cfg) {
+  return ["-m", "pip", "install", `pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`];
 }
 function warmArgs(cfg) {
-  return ["run", "--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--python", "3.14", "python", "-c", "import pymupdf4llm"];
+  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL"];
+}
+function uvChildArgs(cfg, script, mode) {
+  return ["run", ...withArgs(cfg), "--python", "3.14", "python", script, mode];
 }
-function convertArgs(cfg, scriptPath2, pdfPath) {
-  return ["run", "--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--python", "3.14", "python", scriptPath2, pdfPath];
+function pythonChildArgs(script, mode) {
+  return [script, mode];
 }
 function soffArgs(src, profileDir, outDir) {
   return [
@@ -623,20 +911,41 @@ function soffArgs(src, profileDir, outDir) {
     src
   ];
 }
+var LIVE = /* @__PURE__ */ new Set();
+function killTree(child) {
+  if (child.pid === void 0) return;
+  try {
+    if (process.platform === "win32") spawn("taskkill", ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore" });
+    else process.kill(-child.pid, "SIGKILL");
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+  }
+}
+process.on("exit", () => {
+  for (const c of LIVE) killTree(c);
+});
 async function runCapped(cmd, args, opts) {
   return new Promise((resolveP) => {
     let settled = false;
     let timedOut = false;
     let capped = false;
+    let timer;
+    let graceTimer;
     const stdoutChunks = [];
     const stderrChunks = [];
     let stdoutBytes = 0;
     let stderrBytes = 0;
-    const child = spawn(cmd, args, { env: opts.env ?? process.env });
+    const child = spawn(cmd, args, { env: opts.env ?? process.env, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
+    LIVE.add(child);
     const finish = (code) => {
       if (settled) return;
       settled = true;
+      LIVE.delete(child);
       clearTimeout(timer);
+      clearTimeout(graceTimer);
       opts.signal?.removeEventListener("abort", onAbort);
       resolveP({
         stdout: Buffer.concat(stdoutChunks).toString("utf8"),
@@ -646,17 +955,25 @@ async function runCapped(cmd, args, opts) {
         capped
       });
     };
-    const kill = () => child.kill("SIGKILL");
+    const kill = () => {
+      killTree(child);
+      graceTimer ??= setTimeout(() => finish(null), KILL_GRACE_MS);
+    };
     const onAbort = () => {
       kill();
     };
     if (opts.signal?.aborted) {
       kill();
     } else opts.signal?.addEventListener("abort", onAbort);
-    const timer = setTimeout(() => {
+    timer = setTimeout(() => {
       timedOut = true;
       kill();
     }, opts.timeoutMs);
+    child.stdin.on("error", (err) => {
+      if (err.code !== "EPIPE") throw err;
+    });
+    child.stdin.write(opts.stdin ?? "");
+    child.stdin.end();
     child.stdout.on("data", (chunk) => {
       if (capped) return;
       const remaining = opts.capBytes - stdoutBytes;
@@ -696,73 +1013,29 @@ async function runCapped(cmd, args, opts) {
 function findPackageRoot(startDir) {
   let dir = startDir;
   for (; ; ) {
-    if (existsSync(join2(dir, "package.json"))) return dir;
+    if (existsSync2(join3(dir, "package.json"))) return dir;
     const parent = dirname(dir);
     if (parent === dir) throw new Error(`package.json not found walking up from ${startDir}`);
     dir = parent;
   }
 }
 function scriptPath() {
-  return join2(findPackageRoot(dirname(fileURLToPath(import.meta.url))), "scripts", "pdf_to_md.py");
-}
-function formatSize2(bytes) {
-  if (bytes < 1024) {
-    return `${bytes}B`;
-  } else if (bytes < 1024 * 1024) {
-    return `${(bytes / 1024).toFixed(1)}KB`;
-  } else {
-    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-  }
-}
-async function convertViaUv(cfg, pdfPath, signal) {
-  const r = await runCapped("uv", convertArgs(cfg, scriptPath(), pdfPath), {
-    timeoutMs: cfg.convertTimeoutMs,
-    capBytes: OUTPUT_MAX_BYTES,
-    signal
-  });
-  if (r.timedOut || r.capped || r.code !== 0) {
-    throw new Error(`code=${r.code} timedOut=${r.timedOut} capped=${r.capped}: ${r.stderr.slice(0, 500)}`);
-  }
-  return r.stdout;
-}
-async function convertViaPython(cfg, exe, pdfPath, signal) {
-  const r = await runCapped(exe, pythonConvertArgs(scriptPath(), pdfPath), {
-    timeoutMs: cfg.convertTimeoutMs,
-    capBytes: OUTPUT_MAX_BYTES,
-    signal
-  });
-  if (r.timedOut || r.capped || r.code !== 0) {
-    throw new Error(`code=${r.code} timedOut=${r.timedOut} capped=${r.capped}: ${r.stderr.slice(0, 500)}`);
-  }
-  return r.stdout;
-}
-async function convertViaUnpdf(pdfPath, cfg, signal) {
-  if (signal?.aborted) throw new Error("aborted");
-  const buf = readFileSync(pdfPath);
-  const work = (async () => {
-    const pdf = await getDocumentProxy(new Uint8Array(buf));
-    const { text } = await extractText(pdf, { mergePages: false });
-    const md = pagesToMarkdown(text);
-    if (Buffer.byteLength(md, "utf8") > OUTPUT_MAX_BYTES) throw new Error("unpdf output exceeded cap");
-    return md;
-  })();
-  let timer;
-  const timeout = new Promise((_, rej) => {
-    timer = setTimeout(() => rej(new Error("unpdf conversion timed out")), cfg.convertTimeoutMs);
-  });
-  try {
-    return await Promise.race([work, timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
+  return join3(findPackageRoot(dirname(fileURLToPath(import.meta.url))), "scripts", "doc_to_md.py");
 }
 var PROBE_PROGRAM = `import sys
 print("PY", sys.version_info[0], sys.version_info[1])
 try:
-    import pymupdf4llm
-    print("PKG", pymupdf4llm.__version__)
+    # pymupdf4llm.__version__ >= 1.27.0
+    import pymupdf, pymupdf4llm
+    v = tuple(int(x) for x in pymupdf4llm.__version__.split(".")[:3])
+    print("PDF", "yes" if v >= (1, 27, 0) else "no")
+except Exception:
+    print("PDF", "no")
+try:
+    import openpyxl, xlrd, PIL
+    print("XLSX", "yes")
 except Exception:
-    print("PKG", "none")
+    print("XLSX", "no")
 `;
 var PROBE_TIMEOUT_MS = 5e3;
 function probeArgs() {
@@ -770,33 +1043,39 @@ function probeArgs() {
 }
 var PYTHON_CANDIDATES = ["python3", "python"];
 function parseProbeOutput(stdout) {
-  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPKG (\S+)\s*$/);
-  if (!m) return null;
-  return { major: Number(m[1]), minor: Number(m[2]), pkg: m[3] === "none" ? null : m[3] };
+  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\s*$/);
+  return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes" } : null;
 }
 function meetsFloor(p) {
   return p.major > 3 || p.major === 3 && p.minor >= 12;
 }
 function cacheDir(platform, env, home) {
-  if (platform === "win32") return join2(env.LOCALAPPDATA ?? join2(home, "AppData", "Local"), "pi-quiver");
-  if (platform === "darwin") return join2(home, "Library", "Caches", "pi-quiver");
-  return join2(env.XDG_CACHE_HOME ?? join2(home, ".cache"), "pi-quiver");
+  if (platform === "win32") return join3(env.LOCALAPPDATA ?? join3(home, "AppData", "Local"), "pi-quiver");
+  if (platform === "darwin") return join3(home, "Library", "Caches", "pi-quiver");
+  return join3(env.XDG_CACHE_HOME ?? join3(home, ".cache"), "pi-quiver");
 }
 function venvPython(venvDir, platform) {
-  return platform === "win32" ? join2(venvDir, "Scripts", "python.exe") : join2(venvDir, "bin", "python");
-}
-function pythonConvertArgs(script, pdfPath) {
-  return [script, pdfPath];
+  return platform === "win32" ? join3(venvDir, "Scripts", "python.exe") : join3(venvDir, "bin", "python");
 }
 var tail = (s) => s.slice(-500).trim();
 async function resolveBackend(cfg, deps, signal) {
   if (signal?.aborted) throw new Error("aborted");
-  const warm = await deps.run("uv", warmArgs(cfg), { timeoutMs: cfg.warmTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
+  const deadline = deps.now() + cfg.warmTimeoutMs;
+  const left = () => Math.max(1, deadline - deps.now());
+  const expired = (tmp) => {
+    if (deadline - deps.now() > 0) return null;
+    if (tmp) deps.rmrf(tmp);
+    return { kind: "none", reason: `backend discovery exceeded warmTimeoutMs (${cfg.warmTimeoutMs}ms) - raise warmTimeoutMs, or install uv` };
+  };
+  const warm = await deps.run("uv", warmArgs(cfg), { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
   if (signal?.aborted) throw new Error("aborted");
-  if (warm.code === 0 && !warm.timedOut) return { kind: "uv" };
+  if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true };
   const uvAbsent = warm.code === null && !warm.timedOut;
-  const probe = async (exe) => {
-    const r = await deps.run(exe, probeArgs(), { timeoutMs: PROBE_TIMEOUT_MS, capBytes: 4e3, env: deps.env, signal });
+  const isDeadline = (result) => result !== null && "kind" in result;
+  const probe = async (exe, tmp) => {
+    const timeout = expired(tmp);
+    if (timeout) return timeout;
+    const r = await deps.run(exe, probeArgs(), { timeoutMs: Math.min(PROBE_TIMEOUT_MS, left()), capBytes: 4e3, env: deps.env, signal });
     if (signal?.aborted) throw new Error("aborted");
     if (r.code !== 0 || r.timedOut) return null;
     return parseProbeOutput(r.stdout);
@@ -804,28 +1083,33 @@ async function resolveBackend(cfg, deps, signal) {
   let eligible = null;
   for (const exe of PYTHON_CANDIDATES) {
     const p = await probe(exe);
+    if (isDeadline(p)) return p;
     if (!p || !meetsFloor(p)) continue;
-    if (p.pkg) return { kind: "python", exe, version: p.pkg };
+    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx };
     eligible ??= { exe, version: `${p.major}.${p.minor}` };
   }
-  const venvDir = join2(deps.cacheRoot, "pymupdf-venv");
+  const venvDir = join3(deps.cacheRoot, VENV_DIR_NAME);
   const venvExe = venvPython(venvDir, deps.platform);
   const cached = await probe(venvExe);
-  if (cached && meetsFloor(cached) && cached.pkg) return { kind: "venv", exe: venvExe, version: cached.pkg };
+  if (isDeadline(cached)) return cached;
+  if (cached && meetsFloor(cached) && cached.pdf && cached.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
   if (eligible) {
     const recheck = await probe(venvExe);
-    if (recheck && meetsFloor(recheck) && recheck.pkg) return { kind: "venv", exe: venvExe, version: recheck.pkg };
+    if (isDeadline(recheck)) return recheck;
+    if (recheck && meetsFloor(recheck) && recheck.pdf && recheck.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
     const tmp = `${venvDir}.tmp-${deps.pid}`;
-    const deadline = deps.now() + cfg.warmTimeoutMs;
-    const left = () => Math.max(1, deadline - deps.now());
     const bootFail = (stderr) => {
       deps.rmrf(tmp);
       return { kind: "none", reason: `python ${eligible.version} found but venv bootstrap failed: ${tail(stderr)} - install python3-venv, or uv` };
     };
+    const mkTimeout = expired(tmp);
+    if (mkTimeout) return mkTimeout;
     const mk = await deps.run(eligible.exe, ["-m", "venv", tmp], { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
     if (signal?.aborted) throw new Error("aborted");
     if (mk.code !== 0 || mk.timedOut) return bootFail(mk.stderr);
-    const pip = await deps.run(venvPython(tmp, deps.platform), ["-m", "pip", "install", `pymupdf4llm==${cfg.pymupdfVersion}`], { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
+    const pipTimeout = expired(tmp);
+    if (pipTimeout) return pipTimeout;
+    const pip = await deps.run(venvPython(tmp, deps.platform), pipInstallArgs(cfg), { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
     if (signal?.aborted) throw new Error("aborted");
     if (pip.code !== 0 || pip.timedOut) return bootFail(pip.stderr);
     const publish = () => {
@@ -836,14 +1120,21 @@ async function resolveBackend(cfg, deps, signal) {
         return false;
       }
     };
-    if (publish()) return { kind: "venv", exe: venvExe, version: cfg.pymupdfVersion };
-    const winner = await probe(venvExe);
-    if (winner && meetsFloor(winner) && winner.pkg) {
+    if (publish()) {
+      deps.rmrf(join3(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+    }
+    const winner = await probe(venvExe, tmp);
+    if (isDeadline(winner)) return winner;
+    if (winner && meetsFloor(winner) && winner.pdf && winner.xlsx) {
       deps.rmrf(tmp);
-      return { kind: "venv", exe: venvExe, version: winner.pkg };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
     }
     deps.rmrf(venvDir);
-    if (publish()) return { kind: "venv", exe: venvExe, version: cfg.pymupdfVersion };
+    if (publish()) {
+      deps.rmrf(join3(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+    }
     return bootFail("rename after competing bootstrap");
   }
   return uvAbsent ? { kind: "none", reason: "uv not found; no python >= 3.12 on PATH - install uv, or Python 3.12+" } : { kind: "none", reason: `uv warm-up failed: ${tail(warm.stderr)}; no python >= 3.12 on PATH` };
@@ -855,8 +1146,8 @@ function realDeps() {
     cacheRoot: cacheDir(process.platform, process.env, homedir()),
     platform: process.platform,
     pid: process.pid,
-    rename: renameSync,
-    rmrf: (p) => rmSync(p, { recursive: true, force: true }),
+    rename: renameSync2,
+    rmrf: (p) => rmSync2(p, { recursive: true, force: true }),
     now: Date.now,
     env: process.env
   };
@@ -871,28 +1162,28 @@ function getBackend(cfg, deps, signal) {
   }
   return backendPromise;
 }
-async function convertOffice(cfg, src, signal, run = runCapped) {
-  const profileDir = mkdtempSync(join2(tmpdir2(), "pi-doc-soffice-prof-"));
-  const outDir = mkdtempSync(join2(tmpdir2(), "pi-doc-soffice-out-"));
+async function convertOffice(sofficeTimeoutMs, src, signal, run = runCapped) {
+  const profileDir = mkdtempSync(join3(tmpdir3(), "pi-doc-soffice-prof-"));
+  const outDir = mkdtempSync(join3(tmpdir3(), "pi-doc-soffice-out-"));
   const cleanup = () => {
     for (const d of [profileDir, outDir]) {
       try {
-        rmSync(d, { recursive: true, force: true });
+        rmSync2(d, { recursive: true, force: true });
       } catch {
       }
     }
   };
   try {
     const env = { ...process.env, SAL_USE_VCLPLUGIN: "svp", OOO_DISABLE_RECOVERY: "1", SAL_NO_MOUSEGRABS: "1" };
-    const r = await run("soffice", soffArgs(src, profileDir, outDir), { timeoutMs: cfg.sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
+    const r = await run("soffice", soffArgs(src, profileDir, outDir), { timeoutMs: sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
     if (signal?.aborted) throw new Error("aborted");
     if (r.code === null && !r.timedOut) {
       throw new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
     }
     if (r.timedOut || r.code !== 0) throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr.slice(0, 500)}`);
     const base = basename(src).replace(/\.[^.]+$/, "");
-    const pdfPath = join2(outDir, `${base}.pdf`);
-    const st = statSync(pdfPath, { throwIfNoEntry: false });
+    const pdfPath = join3(outDir, `${base}.pdf`);
+    const st = statSync2(pdfPath, { throwIfNoEntry: false });
     if (!st || !st.isFile() || st.size === 0) {
       throw new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
     }
@@ -902,92 +1193,228 @@ async function convertOffice(cfg, src, signal, run = runCapped) {
     throw e;
   }
 }
-async function runPipeline(cfg, inputPath, type, signal, seams) {
-  const s = {
-    backend: (c) => getBackend(c, void 0, signal),
-    convertPymupdf: (c, b, p, sig) => b.kind === "uv" ? convertViaUv(c, p, sig) : convertViaPython(c, b.exe, p, sig),
-    convertUnpdf: convertViaUnpdf,
-    ...seams
-  };
-  let pdfPath = inputPath;
-  let cleanup = null;
-  if (type === "docx" || type === "pptx") {
-    const o = await convertOffice(cfg, inputPath, signal);
-    pdfPath = o.pdfPath;
-    cleanup = o.cleanup;
+var DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preserved";
+var DEGRADED_UNPDF = "unpdf text extraction - structure not preserved";
+var EXCEL_REMEDY = "Remedy: install uv, or pip install openpyxl xlrd pillow";
+function resolveUnpdfWorker(candidates, exists) {
+  for (const candidate of candidates) if (exists(candidate)) return candidate;
+  throw new Error("unpdf worker not found");
+}
+function unpdfWorkerPath() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolveUnpdfWorker([
+    join3(findPackageRoot(here), "dist", "lib", "unpdf-worker.js"),
+    join3(here, "unpdf-worker.js"),
+    join3(here, "unpdf-worker.ts")
+  ], existsSync2);
+}
+async function runTierReal(mode, childOptions, _b, signal, timeoutMs, backend) {
+  const cfg = { pymupdfVersion: String(childOptions.pymupdfVersion), warmTimeoutMs: 0 };
+  let cmd, args;
+  if (mode === "pdf-text" || mode === "info" && backend.kind === "none") {
+    cmd = process.execPath;
+    args = [unpdfWorkerPath(), mode];
+  } else if (backend.kind === "uv") {
+    cmd = "uv";
+    args = uvChildArgs(cfg, scriptPath(), mode);
+  } else if (backend.kind === "python" || backend.kind === "venv") {
+    cmd = backend.exe;
+    args = pythonChildArgs(scriptPath(), mode);
+  } else return { ok: false, reason: backend.reason };
+  const r = await runCapped(cmd, args, { timeoutMs, capBytes: Number(childOptions.maxOutputBytes), signal, stdin: JSON.stringify(childOptions) });
+  if (signal?.aborted) return { ok: false, reason: "aborted" };
+  if (r.timedOut) return { ok: false, reason: `timeout after ${timeoutMs}ms` };
+  if (r.capped) return { ok: false, reason: "output exceeded maxOutputBytes" };
+  const detail = r.stderr.slice(-300).trim();
+  let json;
+  try {
+    json = JSON.parse(r.stdout);
+  } catch {
+    return r.code === 0 ? { ok: false, reason: "invalid-json" } : { ok: false, reason: `exit ${r.code ?? -1}`, ...detail ? { detail } : {} };
   }
+  if (r.code === 3) return { ok: false, userError: json.error ?? "user error", ...json.pageCount !== void 0 ? { pageCount: json.pageCount } : {} };
+  if (r.code !== 0) return { ok: false, reason: `exit ${r.code ?? -1}`, ...detail ? { detail } : {} };
+  return { ok: true, json };
+}
+function detailSuffix(r) {
+  return r.detail ? ` (${r.detail})` : "";
+}
+async function convertDocument(o, signal, seams) {
+  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, ...seams };
+  const inputPath = resolve2(o.path);
+  const st = statSync2(inputPath, { throwIfNoEntry: false });
+  if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
+  const type = classifyInput(inputPath);
+  const isExcel = type === "xlsx" || type === "xls";
+  if (isExcel && o.pages) throw new Error("--pages does not apply to spreadsheets: worksheets have no stable page numbering");
+  const backend = await s.backend({ pymupdfVersion: o.pymupdfVersion, warmTimeoutMs: o.warmTimeoutMs });
+  if (isExcel && (backend.kind === "none" || !backend.xlsx)) throw new Error(`Excel conversion needs a Python backend with openpyxl, xlrd and pillow (${backend.kind === "none" ? backend.reason : `${backend.kind} lacks the Excel packages`}). ${EXCEL_REMEDY}`);
+  const stem = sanitizeStem(basename(inputPath, extname3(inputPath)));
+  const b = openBundle(o.outputDir ? resolve2(o.outputDir) : tempBundleRoot(), stem, o.overwrite);
+  let office = null;
   try {
-    const backend = await s.backend(cfg);
-    if (backend.kind === "none") {
-      return { markdown: await s.convertUnpdf(pdfPath, cfg, signal), engine: "unpdf", degraded: true, fallbackReason: backend.reason, backend: "unpdf" };
+    let pdfPath = inputPath;
+    if (type === "docx" || type === "pptx") {
+      office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
+      pdfPath = office.pdfPath;
     }
-    try {
-      const markdown = await s.convertPymupdf(cfg, backend, pdfPath, signal);
-      return {
-        markdown,
-        engine: "pymupdf4llm",
-        degraded: false,
-        backend: backend.kind,
-        ...backend.kind === "python" || backend.kind === "venv" ? { pymupdfVersion: backend.version } : {}
-      };
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return {
-        markdown: await s.convertUnpdf(pdfPath, cfg, signal),
-        engine: "unpdf",
-        degraded: true,
-        fallbackReason: `pymupdf4llm (${backend.kind}) conversion failed: ${msg} - fell back to unpdf`,
-        backend: "unpdf"
-      };
+    const base = { path: pdfPath, pages: o.pages, stagingDir: b.stagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxCellsPerSheet: o.maxCellsPerSheet, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion };
+    let tier, engine, json, degraded = null, fallbackReason = null;
+    if (isExcel) {
+      const r = await s.runTier("xlsx", base, b, signal, o.excelTimeoutMs, backend);
+      if (!r.ok) {
+        if ("userError" in r) throw new Error(r.userError);
+        const remedy = r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes" ? ". Remedy: raise excelTimeoutMs or lower maxCellsPerSheet" : "";
+        throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
+      }
+      publishSheetImages(b);
+      tier = "excel";
+      engine = type === "xls" ? "xlrd" : "openpyxl";
+      json = r.json;
+    } else if (backend.kind === "none") {
+      const r = await s.runTier("pdf-text", base, b, signal, o.primaryTimeoutMs, backend);
+      if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: unpdf ${r.reason}${detailSuffix(r)}`);
+      tier = "unpdf";
+      engine = "unpdf";
+      json = r.json;
+      degraded = DEGRADED_UNPDF;
+    } else {
+      const p = await s.runTier("pdf-primary", base, b, signal, o.primaryTimeoutMs, backend);
+      const kept = publishStaged(b);
+      if (p.ok) {
+        tier = "primary";
+        engine = "pymupdf4llm";
+        json = p.json;
+      } else if ("userError" in p) throw new Error(p.userError);
+      else {
+        if (signal?.aborted) throw new Error("aborted");
+        const keepPages = Object.fromEntries([...kept.entries()].map(([k, v]) => [String(k), v]));
+        const f = await s.runTier("pdf-fallback", { ...base, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
+        publishStaged(b);
+        if (!f.ok) throw new Error("userError" in f ? f.userError : `Conversion failed: primary ${p.reason}; fallback ${f.reason}${detailSuffix(f)}`);
+        tier = "fallback";
+        engine = "pymupdf-text";
+        json = f.json;
+        degraded = DEGRADED_TEXT;
+        fallbackReason = `primary ${p.reason}`;
+      }
     }
+    let body = rewriteImageLinks(json.markdown ?? "", b.sourceMap);
+    validateImageLinks(body, b.manifest);
+    const head = [];
+    if (degraded) head.push(`Degraded: ${degraded}`);
+    if (fallbackReason) head.push(`Fallback-Reason: ${fallbackReason}`);
+    if (json.failedPages?.length) head.push(`Failed pages: ${json.failedPages.map((f) => `${f.page} (${f.error})`).join("; ")}`);
+    if (json.emptyPages?.length) head.push(`Empty pages: ${json.emptyPages.join(", ")}`);
+    for (const n of json.notes ?? []) head.push(`Notes: ${n}`);
+    const markdown = (head.length ? `${head.join("\n")}
+
+` : "") + body;
+    commitBundle(b, markdown);
+    const outline = scanOutline(markdown, o.outlineMaxEntries);
+    const details = { path: inputPath, backend: backend.kind, pymupdfVersion: o.pymupdfVersion, inputType: type, file: b.mdPath, outputDir: b.root, savedTo: b.mdPath, imagesDir: b.imagesDir, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, imageCount: b.manifest.size, bytes: Buffer.byteLength(markdown, "utf8"), lines: markdown.split("\n").length, degraded, fallbackReason, failedPages: (json.failedPages ?? []).map((f) => f.page), emptyPages: json.emptyPages ?? [], notes: json.notes ?? [], outline: outline.entries, outlineTotal: outline.total };
+    return { output: formatHandle(details), details };
+  } catch (e) {
+    abortBundle(b);
+    throw e;
   } finally {
-    cleanup?.();
+    office?.cleanup();
   }
 }
-async function convertDocument(path, cfg, signal, seams) {
-  const inputPath = resolve(path);
-  const st = statSync(inputPath, { throwIfNoEntry: false });
-  if (!st || !st.isFile()) throw new Error(`Not a readable file: ${path}`);
+async function inspectDocument(o, signal, seams) {
+  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, ...seams };
+  const inputPath = resolve2(o.path);
+  const st = statSync2(inputPath, { throwIfNoEntry: false });
+  if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
   const type = classifyInput(inputPath);
-  const { markdown, engine, degraded, fallbackReason, backend, pymupdfVersion } = await runPipeline(cfg, inputPath, type, signal, seams);
-  const body = withMarker(markdown, degraded).replace(/\s+$/, "");
-  const { spill, bytes, lines } = applyGate2(body);
-  const details = { path: inputPath, inputType: type, engine, backend, ...pymupdfVersion !== void 0 ? { pymupdfVersion } : {}, degraded, bytes, lines, spilled: spill };
-  const header = [
-    `Source: ${inputPath}`,
-    `Type: ${type}  Engine: ${engine}${degraded ? " (degraded fallback)" : ""}`
-  ];
-  if (fallbackReason) header.push(`Fallback-Reason: ${fallbackReason}`);
-  const compose = (parts) => parts.join("\n").replace(/\n+$/, "");
-  if (!spill) {
-    return { output: compose([...header, `Length: ${bytes} bytes, ${lines} lines`, "", body]), details };
+  const isExcel = type === "xlsx" || type === "xls";
+  const backend = await s.backend({ pymupdfVersion: o.pymupdfVersion, warmTimeoutMs: o.warmTimeoutMs });
+  if (isExcel && (backend.kind === "none" || !backend.xlsx)) throw new Error(`Excel inspection needs a Python backend with openpyxl, xlrd and pillow. ${EXCEL_REMEDY}`);
+  let office = null;
+  try {
+    let path = inputPath;
+    if (type === "docx" || type === "pptx") {
+      office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
+      path = office.pdfPath;
+    }
+    const r = await s.runTier("info", { path, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, { stagingDir: "" }, signal, isExcel ? o.excelTimeoutMs : o.fallbackTimeoutMs, backend);
+    if (!r.ok) {
+      if ("userError" in r) throw new Error(r.userError);
+      if (isExcel && (r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes")) throw new Error(`Excel inspection failed: ${r.reason}. Remedy: raise excelTimeoutMs or lower maxCellsPerSheet${detailSuffix(r)}`);
+      throw new Error(`Inspection failed: ${r.reason}${detailSuffix(r)}`);
+    }
+    const toc = (r.json.toc ?? []).map(([level, title, page]) => ({ level, title, page }));
+    const details = { type, backend: backend.kind, pageCount: r.json.pageCount ?? null, metadata: r.json.metadata ?? {}, toc: toc.slice(0, o.outlineMaxEntries), tocTotal: toc.length, sheets: r.json.sheets ? r.json.sheets.slice(0, o.outlineMaxEntries) : null, sheetsTotal: r.json.sheets?.length ?? 0 };
+    return { output: formatInfoHandle(details, o.outlineMaxEntries), details };
+  } finally {
+    office?.cleanup();
   }
-  const file = spillToFile2(inputPath, body);
-  return {
-    output: compose([
-      ...header,
-      `Body: ${formatSize2(bytes)} across ${lines} lines \u2014 written to file (too large to inline)`,
-      `Saved-To: ${file}`,
-      "",
-      "Read slices of this file with the read tool (offset/limit) or grep it; do not read the whole file unless you must. Markdown is grep-able by heading (^#).",
-      "",
-      "----- preview (first 60 lines) -----",
-      buildPreview2(body)
-    ]),
-    details: { ...details, spilled: true, file }
-  };
 }
 
 // bin/pi-quiver.ts
-var USAGE = 'Usage: pi-quiver fetch <url> [--method GET|HEAD|POST] [--header "K: V"]... [--body <str>] [--raw] [--timeout-ms <n>]\n       pi-quiver doc-to-md <path>';
-function parseCliArgs(argv) {
-  if (argv[0] === "doc-to-md") {
-    const rest2 = argv.slice(1);
-    if (rest2.length === 0) return { ok: false, error: "missing <path>" };
-    if (rest2[0].startsWith("--")) return { ok: false, error: `unknown flag: ${rest2[0]}` };
-    if (rest2.length > 1) return { ok: false, error: `unexpected argument: ${rest2[1]}` };
-    return { ok: true, cmd: "doc-to-md", path: rest2[0] };
+var USAGE = 'Usage: pi-quiver fetch <url> [--method GET|HEAD|POST] [--header "K: V"]... [--body <str>] [--raw] [--timeout-ms <n>]\n       pi-quiver doc-to-md [--info] [--pages <spec>] [--output-dir <dir>] [--overwrite] [tunable flags] <path>   (--help for all flags)';
+function parseDocToMd(rest) {
+  if (rest.includes("--help") || rest.includes("-h")) return { ok: true, cmd: "doc-to-md-help" };
+  const perCall = {};
+  let path;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (!arg.startsWith("--")) {
+      if (path !== void 0) return { ok: false, error: `unexpected argument: ${arg}` };
+      path = arg;
+      continue;
+    }
+    const d = DOC_TO_MD_OPTIONS.find((o) => o.flag === arg);
+    if (!d) return { ok: false, error: `unknown flag: ${arg}` };
+    if (d.type === "bool") {
+      perCall[d.key] = true;
+      continue;
+    }
+    const value = rest[++i];
+    if (value === void 0) return { ok: false, error: `${arg} requires a value` };
+    if (d.type === "int") {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n <= 0) return { ok: false, error: `invalid ${arg}: ${value}` };
+      perCall[d.key] = n;
+    } else perCall[d.key] = value;
+  }
+  if (!path) return { ok: false, error: "missing <path>" };
+  return { ok: true, cmd: "doc-to-md", perCall: { ...perCall, path } };
+}
+function cliAgentDir(env) {
+  const raw = env.PI_CODING_AGENT_DIR;
+  const home = env.HOME ?? env.USERPROFILE ?? homedir2();
+  if (raw && raw.length > 0) {
+    if (raw === "~") return home;
+    if (raw.startsWith("~/") || process.platform === "win32" && raw.startsWith("~\\")) return join4(home, raw.slice(2));
+    return raw;
+  }
+  return join4(home, ".pi", "agent");
+}
+function readCliSettings(cwd, env, warn) {
+  const out = {};
+  for (const file of [join4(cliAgentDir(env), "settings.json"), join4(cwd, ".pi", "settings.json")]) {
+    if (!existsSync3(file)) continue;
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync2(file, "utf8")).quiver?.docToMd;
+    } catch {
+      warn(`pi-quiver: ${file} is not valid JSON; ignored.`);
+      continue;
+    }
+    if (raw === void 0) continue;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      const unknown = Object.keys(raw).filter((k) => !DOC_TO_MD_OPTIONS.some((o) => o.key === k && o.settable));
+      if (unknown.length > 0) warn(`pi-quiver: quiver.docToMd in ${file} has keys that are not tunable settings; ignored: ${unknown.join(", ")}`);
+    }
+    const patch = coerceDocToMdSettings(raw, warn);
+    if (patch) Object.assign(out, patch);
+    else warn(`pi-quiver: "docToMd" in ${file} has an unrecognized value; ignored.`);
   }
+  return out;
+}
+function parseCliArgs(argv) {
+  if (argv[0] === "doc-to-md") return parseDocToMd(argv.slice(1));
   if (argv[0] !== "fetch") return { ok: false, error: `unknown command: ${argv[0] ?? "(none)"}` };
   const rest = argv.slice(1);
   let url;
@@ -1006,18 +1433,15 @@ function parseCliArgs(argv) {
       const value = rest[++i];
       if (value === void 0) return { ok: false, error: `${arg} requires a value` };
       if (arg === "--method") {
-        if (value !== "GET" && value !== "HEAD" && value !== "POST") {
-          return { ok: false, error: `invalid --method: ${value}` };
-        }
+        if (value !== "GET" && value !== "HEAD" && value !== "POST") return { ok: false, error: `invalid --method: ${value}` };
         method = value;
       } else if (arg === "--header") {
         const sep = value.indexOf(": ");
         if (sep <= 0) return { ok: false, error: `malformed --header (expected "Key: Value"): ${value}` };
         headers ??= {};
         headers[value.slice(0, sep)] = value.slice(sep + 2);
-      } else if (arg === "--body") {
-        body = value;
-      } else {
+      } else if (arg === "--body") body = value;
+      else {
         const n = Number(value);
         if (!Number.isFinite(n) || n <= 0) return { ok: false, error: `invalid --timeout-ms: ${value}` };
         timeoutMs = n;
@@ -1045,10 +1469,30 @@ ${USAGE}
 `);
     return 2;
   }
+  if (parsed.cmd === "doc-to-md-help") {
+    process.stdout.write(`${renderHelp()}
+`);
+    return 0;
+  }
   if (parsed.cmd === "doc-to-md") {
+    let o;
     try {
-      const result = await convertDocument(parsed.path, parseConfig(process.env));
-      process.stdout.write(`${result.output}
+      const settings = readCliSettings(process.cwd(), process.env, (m) => process.stderr.write(`${m}
+`));
+      const pc = parsed.perCall;
+      o = resolveOptions({ ...pc, path: resolve3(process.cwd(), pc.path), ...pc.outputDir ? { outputDir: resolve3(process.cwd(), pc.outputDir) } : {} }, settings, process.env);
+    } catch (err) {
+      if (err instanceof UsageError) {
+        process.stderr.write(`${err.message}
+${USAGE}
+`);
+        return 2;
+      }
+      throw err;
+    }
+    try {
+      const r = o.info ? await inspectDocument(o) : await convertDocument(o);
+      process.stdout.write(`${r.output}
 `);
       return 0;
     } catch (err) {
@@ -1071,16 +1515,16 @@ ${USAGE}
 function isMainEntry() {
   if (!process.argv[1]) return false;
   try {
-    return realpathSync(fileURLToPath2(import.meta.url)) === realpathSync(resolve2(process.argv[1]));
+    return realpathSync(fileURLToPath2(import.meta.url)) === realpathSync(resolve3(process.argv[1]));
   } catch {
     return false;
   }
 }
-if (isMainEntry()) {
-  main().then((code) => {
-    process.exitCode = code;
-  });
-}
+if (isMainEntry()) main().then((code) => {
+  process.exitCode = code;
+});
 export {
-  parseCliArgs
+  cliAgentDir,
+  parseCliArgs,
+  readCliSettings
 };