pi-quiver 6.6.0 → 6.7.0

package/dist/bin/pi-quiver.js

@@ -554,20 +554,20 @@ var init_fetch_core = __esm({
 
 // bin/pi-quiver.ts
 init_fetch_core();
-import { existsSync as existsSync3, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, 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";
 
 // lib/doc-to-md-core.ts
-import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync, readFileSync, readdirSync as readdirSync2, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync2, readdirSync as readdirSync2, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir, tmpdir as tmpdir3 } from "node:os";
 import { basename, dirname, extname as extname3, isAbsolute, join as join3, resolve as resolve2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // lib/doc-to-md-bundle.ts
-import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+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";
@@ -578,31 +578,59 @@ function ownedPattern(stem) {
 function ownedCsvPattern(stem) {
   return new RegExp(`^${escRe(stem)}-s\\d+-[a-z0-9-]+\\.csv$`);
 }
-var SHEET_LINK_RE = /\[[^\]]*\]\(\s*(sheets\/[^)\s]+)\s*\)/g;
+function ownedPagePattern(stem) {
+  return new RegExp(`^${escRe(stem)}-p\\d+\\.[a-z0-9]+$`);
+}
+var FILE_LINK_RE = /\[[^\]]*\]\(\s*((?:sheets|attachments)\/[^)\s]+)\s*\)/g;
 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 openBundle(root, stem, overwrite) {
+function openBundle(root, requested, 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})`);
+  let stem, mdPath, lockPath;
+  let renameReason = null;
+  const exists = `${requested}.md exists`;
+  const held = `${requested}.md.lock held; delete it if no conversion is running`;
+  for (let i = 1; ; i++) {
+    stem = i === 1 ? requested : `${requested}-${i}`;
+    mdPath = join2(root, `${stem}.md`);
+    lockPath = `${mdPath}.lock`;
+    if (!overwrite) {
+      const mdExists = existsSync(mdPath);
+      if (mdExists || existsSync(lockPath)) {
+        if (i === 1) renameReason = mdExists ? exists : held;
+        continue;
+      }
+    }
+    let fd;
+    try {
+      fd = openSync(lockPath, "wx");
+    } catch (e) {
+      if (e.code !== "EEXIST") throw new Error(`Output directory not writable: ${root} (${e.message})`);
+      if (overwrite) throw new Error(`Another conversion owns ${mdPath} (lock: ${lockPath}); if no conversion is running, delete the lock`);
+      if (i === 1) renameReason = held;
+      continue;
+    }
+    closeSync(fd);
+    if (!overwrite && existsSync(mdPath)) {
+      unlinkSync(lockPath);
+      if (i === 1) renameReason = exists;
+      continue;
+    }
+    break;
   }
-  closeSync(fd);
+  const renamedFrom = stem === requested ? null : requested;
   const imagesDir = join2(root, "images");
   const sheetsDir = join2(root, "sheets");
+  const pagesDir = join2(root, "pages");
+  const attachmentsDir = join2(root, "attachments");
   try {
-    if (existsSync(mdPath)) {
-      if (!overwrite) throw new Error(`Output exists: ${mdPath} (pass overwrite)`);
-      const owned = ownedPattern(stem), ownedCsv = ownedCsvPattern(stem);
+    if (existsSync(mdPath) && overwrite) {
+      const owned = ownedPattern(stem), ownedCsv = ownedCsvPattern(stem), ownedPage = ownedPagePattern(stem);
+      const attachments = new Set([...readFileSync(mdPath, "utf8").matchAll(FILE_LINK_RE)].filter((m) => m[1].startsWith("attachments/")).map((m) => m[1].slice("attachments/".length)).filter((f) => f.startsWith(`${stem}-`)));
       unlinkSync(mdPath);
       if (existsSync(imagesDir)) {
         for (const f of readdirSync(imagesDir)) if (owned.test(f)) rmSync(join2(imagesDir, f), { force: true });
@@ -610,12 +638,20 @@ function openBundle(root, stem, overwrite) {
       if (existsSync(sheetsDir)) {
         for (const f of readdirSync(sheetsDir)) if (ownedCsv.test(f)) rmSync(join2(sheetsDir, f), { force: true });
       }
+      if (existsSync(pagesDir)) {
+        for (const f of readdirSync(pagesDir)) if (ownedPage.test(f)) rmSync(join2(pagesDir, f), { force: true });
+      }
+      if (existsSync(attachmentsDir)) {
+        for (const f of readdirSync(attachmentsDir)) if (attachments.has(f)) rmSync(join2(attachmentsDir, f), { force: true });
+      }
     }
     const lockId = randomBytes(6).toString("hex");
     const stagingDir = join2(imagesDir, `.stage-${lockId}`);
     const sheetsStagingDir = join2(sheetsDir, `.stage-${lockId}`);
     mkdirSync2(stagingDir, { recursive: true });
-    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
+    const pagesStagingDir = join2(pagesDir, `.stage-${lockId}`);
+    const attachmentsStagingDir = join2(attachmentsDir, `.stage-${lockId}`);
+    return { root, stem, renamedFrom, renameReason, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, pagesDir, pagesStagingDir, attachmentsDir, attachmentsStagingDir, manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), pageManifest: /* @__PURE__ */ new Set(), attachmentManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
   } catch (e) {
     rmSync(lockPath, { force: true });
     throw e;
@@ -666,25 +702,54 @@ function publishSheetCsvs(b) {
     b.sourceMap.set(`sheets/${f}`, `sheets/${name}`);
   }
 }
+function publishPageImages(b, pageCount) {
+  if (!existsSync(b.pagesStagingDir)) return;
+  for (const f of readdirSync(b.pagesStagingDir).sort()) {
+    const m = f.match(/^p(\d+)(\.[a-z0-9]+)$/i);
+    if (!m || !statSync(join2(b.pagesStagingDir, f)).isFile()) continue;
+    const name = `${b.stem}-p${m[1].padStart(String(pageCount).length, "0")}${m[2]}`;
+    mkdirSync2(b.pagesDir, { recursive: true });
+    renameSync(join2(b.pagesStagingDir, f), join2(b.pagesDir, name));
+    b.pageManifest.add(name);
+    b.sourceMap.set(`pages/${f}`, `pages/${name}`);
+  }
+  rmSync(b.pagesStagingDir, { recursive: true, force: true });
+}
+function publishAttachments(b) {
+  if (!existsSync(b.attachmentsStagingDir)) return;
+  for (const f of readdirSync(b.attachmentsStagingDir).sort()) {
+    if (!statSync(join2(b.attachmentsStagingDir, f)).isFile()) continue;
+    const name = `${b.stem}-${f}`;
+    mkdirSync2(b.attachmentsDir, { recursive: true });
+    renameSync(join2(b.attachmentsStagingDir, f), join2(b.attachmentsDir, name));
+    b.attachmentManifest.add(name);
+    b.sourceMap.set(`attachments/${f}`, `attachments/${name}`);
+  }
+  rmSync(b.attachmentsStagingDir, { recursive: true, force: true });
+}
 function rewriteLinks(md, sourceMap) {
   const images = 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;
   });
-  return images.replace(SHEET_LINK_RE, (whole, target) => {
+  return images.replace(FILE_LINK_RE, (whole, target) => {
     const dest = sourceMap.get(target);
     return dest ? whole.split(target).join(dest) : whole;
   });
 }
-function validateImageLinks(md, manifest, csvManifest = /* @__PURE__ */ new Set(), html = false) {
+function validateImageLinks(md, manifest, csvManifest = /* @__PURE__ */ new Set(), html = false, pageManifest = /* @__PURE__ */ new Set(), attachmentManifest = /* @__PURE__ */ new Set()) {
   for (const m of md.matchAll(IMG_LINK_RE)) {
     const target = imageTarget(m);
     if (html && !target.replace(/^\.\//, "").startsWith("p1/")) continue;
-    if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
+    if (target.startsWith("pages/")) {
+      if (!pageManifest.has(target.slice("pages/".length))) throw new Error(`unexpected image reference in output: ${target}`);
+    } else if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
   }
-  for (const m of md.matchAll(SHEET_LINK_RE)) {
-    if (!csvManifest.has(m[1].slice("sheets/".length))) throw new Error(`unexpected sheet reference in output: ${m[1]}`);
+  for (const m of md.matchAll(FILE_LINK_RE)) {
+    if (m[1].startsWith("attachments/")) {
+      if (!attachmentManifest.has(m[1].slice("attachments/".length))) throw new Error(`unexpected attachment reference in output: ${m[1]}`);
+    } else if (!csvManifest.has(m[1].slice("sheets/".length))) throw new Error(`unexpected sheet reference in output: ${m[1]}`);
   }
 }
 function commitBundle(b, markdown) {
@@ -699,6 +764,14 @@ function commitBundle(b, markdown) {
     fs.rmSync(b.sheetsStagingDir, { recursive: true, force: true });
   } catch {
   }
+  try {
+    fs.rmSync(b.pagesStagingDir, { recursive: true, force: true });
+  } catch {
+  }
+  try {
+    fs.rmSync(b.attachmentsStagingDir, { recursive: true, force: true });
+  } catch {
+  }
   try {
     fs.rmSync(b.lockPath, { force: true });
   } catch {
@@ -707,9 +780,13 @@ function commitBundle(b, markdown) {
 function abortBundle(b) {
   for (const f of b.manifest) rmSync(join2(b.imagesDir, f), { force: true });
   for (const f of b.csvManifest) rmSync(join2(b.sheetsDir, f), { force: true });
+  for (const f of b.pageManifest) rmSync(join2(b.pagesDir, f), { force: true });
+  for (const f of b.attachmentManifest) rmSync(join2(b.attachmentsDir, f), { force: true });
   rmSync(`${b.mdPath}.tmp`, { force: true });
   rmSync(b.stagingDir, { recursive: true, force: true });
   rmSync(b.sheetsStagingDir, { recursive: true, force: true });
+  rmSync(b.pagesStagingDir, { recursive: true, force: true });
+  rmSync(b.attachmentsStagingDir, { recursive: true, force: true });
   rmSync(b.lockPath, { force: true });
 }
 function tempBundleRoot() {
@@ -758,7 +835,7 @@ function ocrLine(ocr, type) {
       return "OCR: skipped - image too small";
     case "ran": {
       const clauses = [`OCR: ${ocr.pages.length} ${image ? "image" : "page(s)"} (${ocr.lang})`];
-      if (ocr.noText.length) clauses.push(`${ocr.noText.length} returned no text`);
+      if (ocr.noText.length) clauses.push(`no text on pages ${compactRanges(ocr.noText)}`);
       if (ocr.ocrFailed.length) clauses.push(`${ocr.ocrFailed.length} failed and were converted without OCR`);
       if (ocr.budgetStopped.length) {
         const r = compactRanges(ocr.budgetStopped, Number.POSITIVE_INFINITY).replaceAll(", ", ",");
@@ -810,13 +887,15 @@ function outlineLines(entries, total) {
 function pageCountLabel(h) {
   const n = h.pageCount ?? "?";
   if (h.type !== "docx") return String(n);
-  if (h.tier === "docx") return `${n} (${(h.explicitBreaks ?? 0) > 0 ? "explicit page breaks, not printed pages" : "no explicit page breaks"})`;
+  if (h.tier === "docx") return (h.explicitBreaks ?? 0) > 0 ? `${n} (explicit page breaks, not printed pages)` : `${n} (no explicit page breaks) - no page markers; cite by Outline line`;
   return `${n} (LibreOffice pagination)`;
 }
 function formatHandle(h) {
   const lines = [`Saved-To: ${h.savedTo}`];
   if (h.imagesDir && h.imageCount > 0) lines.push(`Images-Dir: ${h.imagesDir}`);
   if (h.sheetsDir) lines.push(`Sheets-Dir: ${h.sheetsDir}`);
+  if (h.pagesDir && h.pageImageCount > 0) lines.push(`Pages-Dir: ${h.pagesDir} (${h.pageImageCount} pages)`);
+  else if (h.pageImagesReason) lines.push(`Pages-Dir: none - ${h.pageImagesReason}`);
   lines.push(`Type: ${h.type}   Engine: ${h.engine}   Tier: ${h.tier}`);
   lines.push(`Page-Count: ${pageCountLabel(h)}   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}`);
@@ -826,7 +905,7 @@ function formatHandle(h) {
   if (h.emptyPages.length) fe.push(`Empty-Pages: ${compactRanges(h.emptyPages)}`);
   if (fe.length) lines.push(fe.join("    "));
   if (h.ocr) lines.push(ocrLine(h.ocr, h.type));
-  h.notes.slice(0, NOTE_MAX_LINES).forEach((n, i) => lines.push(`${i === 0 ? "Notes: " : "       "}${trunc(n, NOTE_MAX_CHARS)}`));
+  h.notes.slice(0, NOTE_MAX_LINES).forEach((n, i) => lines.push(`${i === 0 ? "Notes: " : "       "}${n.startsWith("preview truncated:") ? n : trunc(n, NOTE_MAX_CHARS)}`));
   lines.push(...outlineLines(h.outline, h.outlineTotal));
   return lines.join("\n");
 }
@@ -860,11 +939,12 @@ var VERSION_RE = /^\d+(\.\d+)*$/;
 var OCR_LANGUAGE_RE = /^[a-z][a-z0-9_]*(\+[a-z][a-z0-9_]*)*$/;
 var IMAGE_EXTS = [".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp", ".gif"];
 var DOC_TO_MD_OPTIONS = [
-  { key: "path", flag: null, type: "string", default: null, settable: false, help: "Local .pdf .docx .pptx .xlsx .xls .html .htm .png .jpg .jpeg .tif .tiff .bmp .gif file" },
+  { key: "path", flag: null, type: "string", default: null, settable: false, help: "Local .pdf .docx .doc .pptx .xlsx .xlsm .xls .msg .eml .html .htm .png .jpg .jpeg .tif .tiff .bmp .gif 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. DOCX: selects explicit-page-break segments; rejected when the file has none' },
-  { 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: "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/DOC/PPTX only); default all; "" means all pages. DOCX: selects explicit-page-break segments; rejected when the file has none' },
+  { key: "outputDir", flag: "--output-dir", type: "string", default: null, settable: false, help: "Bundle root for <stem>.md + images/; default a per-call temp dir. <stem> = basename without extension with [^A-Za-z0-9._-]+ -> _ (empty -> document); a second call on the same stem writes <stem>-2.md" },
   { key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
+  { key: "pageImages", flag: "--page-images", type: "bool", default: false, settable: false, help: "Also render every selected page to pages/<stem>-pNNN.<imageFormat> at imageDpi (PDF, PPTX, .doc, DOCX via LibreOffice); off by default" },
   { key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 6e4, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier and DOCX child (docx mode); also the unpdf tier" },
   { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier (including DOCX LibreOffice fallback); also PDF and DOCX info and Excel rendered views" },
   { 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; also Excel rendered views" },
@@ -927,6 +1007,7 @@ function coerceDocToMdSettings(raw, warn = console.warn) {
   return out;
 }
 function parsePages(spec) {
+  if (spec.trim() === "") return null;
   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"`);
@@ -943,7 +1024,8 @@ 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", ".html": "html", ".htm": "html", ...Object.fromEntries(IMAGE_EXTS.map((ext) => [ext, "image"])) };
+var SUPPORTED = { ".pdf": "pdf", ".docx": "docx", ".pptx": "pptx", ".xlsx": "xlsx", ".xls": "xls", ".xlsm": "xlsm", ".doc": "doc", ".msg": "email", ".eml": "email", ".html": "html", ".htm": "html", ...Object.fromEntries(IMAGE_EXTS.map((ext) => [ext, "image"])) };
+var SUPPORTED_EXTENSIONS = Object.keys(SUPPORTED);
 function classifyInput(filePath) {
   const t = SUPPORTED[extname2(filePath).toLowerCase()];
   if (!t) throw new Error(`Unsupported file type "${extname2(filePath) || "(none)"}"; supported: ${Object.keys(SUPPORTED).join(", ")}`);
@@ -969,8 +1051,8 @@ function resolveOptions(perCall, settings, env) {
     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");
+  if (o.info && (o.pages !== null || o.outputDir !== null || o.overwrite || o.pageImages)) {
+    throw new UsageError("--info cannot be combined with --pages, --output-dir, --overwrite or --page-images");
   }
   return o;
 }
@@ -991,14 +1073,14 @@ function renderHelp() {
 }
 
 // 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", mammoth: "1.13.0", markdownify: "1.2.3", "python-docx": "1.2.0" };
+var PACKAGE_PINS = { pymupdf4llm: TUNABLE_DEFAULTS.pymupdfVersion, openpyxl: "3.1.5", xlrd: "2.0.2", pillow: "12.3.0", mammoth: "1.13.0", markdownify: "1.2.3", "python-docx": "1.2.0", "extract-msg": "0.56.1" };
 var KILL_GRACE_MS = 2e3;
-var VENV_DIR_NAME = "doc-to-md-venv-v3";
-var LEGACY_VENV_DIR_NAMES = ["pymupdf-venv", "doc-to-md-venv-v2"];
+var VENV_DIR_NAME = "doc-to-md-venv-v4";
+var LEGACY_VENV_DIR_NAMES = ["pymupdf-venv", "doc-to-md-venv-v2", "doc-to-md-venv-v3"];
 var STDERR_CAP = 1e6;
 var OUTPUT_MAX_BYTES = 2e7;
 var EXCEL_PDF_FILTER = 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}';
-var pinSpecs = (cfg) => [`pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`, `mammoth==${PACKAGE_PINS.mammoth}`, `markdownify==${PACKAGE_PINS.markdownify}`, `python-docx==${PACKAGE_PINS["python-docx"]}`];
+var pinSpecs = (cfg) => [`pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`, `mammoth==${PACKAGE_PINS.mammoth}`, `markdownify==${PACKAGE_PINS.markdownify}`, `python-docx==${PACKAGE_PINS["python-docx"]}`, `extract-msg==${PACKAGE_PINS["extract-msg"]}`];
 function withArgs(cfg) {
   return pinSpecs(cfg).flatMap((spec) => ["--with", spec]);
 }
@@ -1006,7 +1088,7 @@ function pipInstallArgs(cfg) {
   return ["-m", "pip", "install", ...pinSpecs(cfg)];
 }
 function warmArgs(cfg) {
-  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL, mammoth, markdownify, docx"];
+  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL, mammoth, markdownify, docx, extract_msg"];
 }
 function uvChildArgs(cfg, script, mode) {
   return ["run", ...withArgs(cfg), "--python", "3.14", "python", script, mode];
@@ -1163,6 +1245,11 @@ try:
     print("DOCX", "yes")
 except Exception:
     print("DOCX", "no")
+try:
+    import extract_msg, markdownify
+    print("EMAIL", "yes")
+except Exception:
+    print("EMAIL", "no")
 `;
 var PROBE_TIMEOUT_MS = 5e3;
 function probeArgs() {
@@ -1170,8 +1257,8 @@ function probeArgs() {
 }
 var PYTHON_CANDIDATES = ["python3", "python"];
 function parseProbeOutput(stdout) {
-  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\r?\nDOCX (yes|no)\s*$/);
-  return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes", docx: m[5] === "yes" } : null;
+  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\r?\nDOCX (yes|no)\r?\nEMAIL (yes|no)\s*$/);
+  return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes", docx: m[5] === "yes", email: m[6] === "yes" } : null;
 }
 function meetsFloor(p) {
   return p.major > 3 || p.major === 3 && p.minor >= 12;
@@ -1196,7 +1283,7 @@ async function resolveBackend(cfg, deps, signal) {
   };
   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", pdf: true, xlsx: true, docx: true };
+  if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true, docx: true, email: true };
   const uvAbsent = warm.code === null && !warm.timedOut;
   const isDeadline = (result) => result !== null && "kind" in result;
   const probe = async (exe, tmp) => {
@@ -1212,19 +1299,19 @@ async function resolveBackend(cfg, deps, signal) {
     const p = await probe(exe);
     if (isDeadline(p)) return p;
     if (!p || !meetsFloor(p)) continue;
-    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx, docx: p.docx };
+    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx, docx: p.docx, email: p.email };
     eligible ??= { exe, version: `${p.major}.${p.minor}` };
   }
-  const healthy = (p) => meetsFloor(p) && p.pdf && p.xlsx && p.docx;
+  const healthy = (p) => meetsFloor(p) && p.pdf && p.xlsx && p.docx && p.email;
   const venvDir = join3(deps.cacheRoot, VENV_DIR_NAME);
   const venvExe = venvPython(venvDir, deps.platform);
   const cached = await probe(venvExe);
   if (isDeadline(cached)) return cached;
-  if (cached && healthy(cached)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+  if (cached && healthy(cached)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
   if (eligible) {
     const recheck = await probe(venvExe);
     if (isDeadline(recheck)) return recheck;
-    if (recheck && healthy(recheck)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+    if (recheck && healthy(recheck)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     const tmp = `${venvDir}.tmp-${deps.pid}`;
     const bootFail = (stderr) => {
       deps.rmrf(tmp);
@@ -1250,18 +1337,18 @@ async function resolveBackend(cfg, deps, signal) {
     };
     if (publish()) {
       for (const legacy of LEGACY_VENV_DIR_NAMES) deps.rmrf(join3(deps.cacheRoot, legacy));
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     }
     const winner = await probe(venvExe, tmp);
     if (isDeadline(winner)) return winner;
     if (winner && healthy(winner)) {
       deps.rmrf(tmp);
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     }
     deps.rmrf(venvDir);
     if (publish()) {
       for (const legacy of LEGACY_VENV_DIR_NAMES) deps.rmrf(join3(deps.cacheRoot, legacy));
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     }
     return bootFail("rename after competing bootstrap");
   }
@@ -1337,7 +1424,7 @@ var DATA_SIGNATURES = {
 };
 async function prepareHtml(inputPath, stagingDir) {
   const { JSDOM: JSDOM2 } = await import("jsdom");
-  const bytes = readFileSync(inputPath);
+  const bytes = readFileSync2(inputPath);
   let source = bytes;
   try {
     source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -1479,18 +1566,21 @@ async function convertDocument(o, signal, 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}`);
+  if (st.size === 0) throw new Error(`empty file: ${o.path}`);
   const type = classifyInput(inputPath);
-  if (o.pages && (type === "html" || type === "image")) throw new Error(`--pages does not apply to ${type === "html" ? "HTML files" : "images"}`);
-  const isExcel = type === "xlsx" || type === "xls";
+  if (o.pages && (type === "html" || type === "image" || type === "email")) throw new Error(`--pages does not apply to ${type === "html" ? "HTML files" : type === "image" ? "images" : "email"}`);
+  const isExcel = type === "xlsx" || type === "xlsm" || 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}`);
+  if (type === "email" && extname3(inputPath).toLowerCase() === ".msg" && (backend.kind === "none" || !backend.email)) throw new Error(`MSG conversion needs the extract-msg package. Python backend: ${backendState(backend, "found without extract-msg")}. Remedy: install uv, or pip install extract-msg markdownify into that Python`);
+  if (type === "email" && extname3(inputPath).toLowerCase() !== ".msg" && lacksDocx(backend)) throw new Error(`EML conversion needs the Python DOCX/HTML packages (mammoth, markdownify, python-docx). Python backend: ${backendState(backend, "found without mammoth/markdownify/python-docx")}. ${docxRemedy}`);
   const stem = sanitizeStem(basename(inputPath, extname3(inputPath)));
   const b = openBundle(o.outputDir ? resolve2(o.outputDir) : tempBundleRoot(), stem, o.overwrite);
   let office = null;
   try {
     let pdfPath = inputPath;
-    const base = { path: inputPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion, ocr: o.ocr, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs };
+    const base = { path: inputPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, pageImages: o.pageImages, pagesStagingDir: b.pagesStagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion, ocr: o.ocr, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs };
     let tier, engine, json, degraded = null, fallbackReason = null;
     let explicitBreaks = null;
     let notes = [];
@@ -1576,13 +1666,23 @@ async function convertDocument(o, signal, seams) {
       office = r;
       pdfPath = r.pdfPath;
     }
-    if (type === "pptx") {
+    if (type === "doc" || type === "pptx") {
       const r = await s.office(o.sofficeTimeoutMs, inputPath, signal);
-      if (!r.ok && r.kind === "missing") throw new Error(`PPTX conversion needs LibreOffice (soffice); direct conversion is not available. Python backend: ${backendState(backend, "available")}. Remedy: install LibreOffice`);
+      if (!r.ok && r.kind === "missing") throw new Error(`${type.toUpperCase()} conversion needs LibreOffice (soffice); direct conversion is not available. Python backend: ${backendState(backend, "available")}. Remedy: install LibreOffice`);
       if (!r.ok) throw officeFailure(r);
       office = r;
       pdfPath = r.pdfPath;
     }
+    if (type === "email") {
+      const isMsg = extname3(inputPath).toLowerCase() === ".msg";
+      const r = await s.runTier("email", { ...base, stem: b.stem, attachmentsStagingDir: b.attachmentsStagingDir }, b, signal, o.primaryTimeoutMs, backend);
+      if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: email ${r.reason}${detailSuffix(r)}`);
+      publishStaged(b);
+      publishAttachments(b);
+      tier = "email";
+      engine = isMsg ? "extract-msg" : "email";
+      json = r.json;
+    }
     const pdfBase = { ...base, path: pdfPath };
     if (json === void 0) {
       if (isExcel) {
@@ -1597,7 +1697,7 @@ async function convertDocument(o, signal, seams) {
         tier = "excel";
         engine = type === "xls" ? "xlrd" : "openpyxl";
         json = r.json;
-        notes = [...json.notes ?? []];
+        notes = (json.notes ?? []).map((n) => n.replace(/sheets\/[^\s,;]+/g, (m) => b.sourceMap.get(m) ?? m));
         const renderPages = json.renderPages ?? [];
         let skip = null;
         const perSheet = /* @__PURE__ */ new Map();
@@ -1636,12 +1736,15 @@ async function convertDocument(o, signal, seams) {
           tier = "primary";
           engine = "pymupdf4llm";
           json = p.json;
+          if (json.pageImages?.length) publishPageImages(b, json.pageCount ?? 0);
         } 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]));
+          rmSync2(b.pagesStagingDir, { recursive: true, force: true });
           const f = await s.runTier("pdf-fallback", { ...pdfBase, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
           publishStaged(b);
+          if (f.ok && f.json.pageImages?.length) publishPageImages(b, f.json.pageCount ?? 0);
           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";
@@ -1651,14 +1754,14 @@ async function convertDocument(o, signal, seams) {
         }
       }
     }
-    if (officeRoute !== null) {
-      degraded = DEGRADED_DOCX_OFFICE;
-      fallbackReason = fallbackReason ? `${officeRoute}; ${fallbackReason}` : officeRoute;
-    }
+    if (type === "doc" || officeRoute !== null) degraded = DEGRADED_DOCX_OFFICE;
+    if (officeRoute !== null) fallbackReason = fallbackReason ? `${officeRoute}; ${fallbackReason}` : officeRoute;
     if (tier === void 0 || engine === void 0 || json === void 0) throw new Error("internal: no tier produced output");
     if (!isExcel) notes = [...notes, ...json.notes ?? []];
+    if (b.renamedFrom) notes.splice(notes[0]?.startsWith("preview truncated:") ? 1 : 0, 0, `renamed to ${b.stem} (${b.renameReason})`);
+    const pageImagesReason = !o.pageImages || b.pageManifest.size || tier === "primary" || tier === "fallback" ? null : tier === "unpdf" ? "page images need the Python backend" : `${type} has no page geometry`;
     const body = resolveOcrLabels(rewriteLinks(json.markdown ?? "", b.sourceMap), b.sourceMap);
-    validateImageLinks(body, b.manifest, b.csvManifest, type === "html");
+    validateImageLinks(body, b.manifest, b.csvManifest, type === "html" || type === "email", b.pageManifest, b.attachmentManifest);
     const head = [];
     if (degraded) head.push(`Degraded: ${degraded}`);
     if (fallbackReason) head.push(`Fallback-Reason: ${fallbackReason}`);
@@ -1670,7 +1773,7 @@ async function convertDocument(o, signal, seams) {
 ` : "") + 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, sheetsDir: b.csvManifest.size ? b.sheetsDir : null, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, explicitBreaks, 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, outline: outline.entries, outlineTotal: outline.total, ocr: handleOcr(tier, type, o, json) };
+    const details = { path: inputPath, backend: backend.kind, pymupdfVersion: o.pymupdfVersion, inputType: type, file: b.mdPath, outputDir: b.root, savedTo: b.mdPath, imagesDir: b.imagesDir, sheetsDir: b.csvManifest.size ? b.sheetsDir : null, pagesDir: b.pageManifest.size ? b.pagesDir : null, pageImageCount: b.pageManifest.size, pageImagesReason, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, explicitBreaks, 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, outline: outline.entries, outlineTotal: outline.total, ocr: handleOcr(tier, type, o, json) };
     return { output: formatHandle(details), details };
   } catch (e) {
     abortBundle(b);
@@ -1684,9 +1787,10 @@ async function inspectDocument(o, signal, 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}`);
+  if (st.size === 0) throw new Error(`empty file: ${o.path}`);
   const type = classifyInput(inputPath);
-  if (type === "html" || type === "image") throw new Error(`info does not apply to ${type === "html" ? "HTML files" : "images"}; convert directly`);
-  const isExcel = type === "xlsx" || type === "xls";
+  if (type === "html" || type === "image" || type === "email") throw new Error(`info does not apply to ${type === "html" ? "HTML files" : type === "image" ? "images" : "email"}; convert directly`);
+  const isExcel = type === "xlsx" || type === "xlsm" || 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;
@@ -1694,7 +1798,7 @@ async function inspectDocument(o, signal, seams) {
     let path = inputPath;
     if (type === "docx") {
       if (lacksDocx(backend)) throw new Error(`DOCX inspection needs the Python DOCX packages. Python backend: ${backendState(backend, "found without mammoth/markdownify/python-docx")}. ${docxRemedy}`);
-    } else if (type === "pptx") {
+    } else if (type === "pptx" || type === "doc") {
       const r2 = await s.office(o.sofficeTimeoutMs, inputPath, signal);
       if (!r2.ok) throw officeFailure(r2);
       office = r2;
@@ -1715,13 +1819,15 @@ async function inspectDocument(o, signal, seams) {
 }
 
 // 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 [--info] [--pages <spec>] [--output-dir <dir>] [--overwrite] [tunable flags] <path>   (--help for all flags)';
+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 [--json] [--info] [--page-images] [--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 json = rest.includes("--json");
+  const args = rest.filter((a) => a !== "--json");
   const perCall = {};
   let path;
-  for (let i = 0; i < rest.length; i++) {
-    const arg = rest[i];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (!arg.startsWith("--")) {
       if (path !== void 0) return { ok: false, error: `unexpected argument: ${arg}` };
       path = arg;
@@ -1738,7 +1844,7 @@ function parseDocToMd(rest) {
       perCall[d.key] = true;
       continue;
     }
-    const value = rest[++i];
+    const value = args[++i];
     if (value === void 0) return { ok: false, error: `${arg} requires a value` };
     if (d.type === "int") {
       const n = Number(value);
@@ -1747,7 +1853,7 @@ function parseDocToMd(rest) {
     } else perCall[d.key] = value;
   }
   if (!path) return { ok: false, error: "missing <path>" };
-  return { ok: true, cmd: "doc-to-md", perCall: { ...perCall, path } };
+  return { ok: true, cmd: "doc-to-md", perCall: { ...perCall, path }, json };
 }
 function cliAgentDir(env) {
   const raw = env.PI_CODING_AGENT_DIR;
@@ -1765,7 +1871,7 @@ function readCliSettings(cwd, env, warn) {
     if (!existsSync3(file)) continue;
     let raw;
     try {
-      raw = JSON.parse(readFileSync2(file, "utf8")).quiver?.docToMd;
+      raw = JSON.parse(readFileSync3(file, "utf8")).quiver?.docToMd;
     } catch {
       warn(`pi-quiver: ${file} is not valid JSON; ignored.`);
       continue;
@@ -1860,7 +1966,11 @@ ${USAGE}
     }
     try {
       const r = o.info ? await inspectDocument(o) : await convertDocument(o);
-      process.stdout.write(`${r.output}
+      if (parsed.json) {
+        const payload = o.info ? r.details : (({ path, backend, pymupdfVersion, inputType, file, outputDir, ...handle }) => handle)(r.details);
+        process.stdout.write(`${JSON.stringify(payload)}
+`);
+      } else process.stdout.write(`${r.output}
 `);
       return 0;
     } catch (err) {

package/extensions/doc_to_md.ts

@@ -35,8 +35,8 @@ export default function docToMdExtension(pi: ExtensionAPI) {
 		name: "doc_to_md",
 		label: "Convert doc to Markdown bundle",
 		description:
-			"Convert a local PDF/DOCX/PPTX/XLSX/XLS, HTML (.html/.htm) or image (.png .jpg .jpeg .tif .tiff .bmp .gif) to a Markdown bundle on disk and return a handle (Saved-To, Images-Dir, Page-Count, Outline, diagnostics) - the Markdown itself is never inlined; read the Saved-To file (offset/limit) for content. `info: true` returns page count, metadata and TOC (or the sheet inventory) without converting - use it to pick `pages`. `pages` selects inclusive 1-based pages (PDF/PPTX) or explicit-page-break segments (DOCX; rejected when the file has none); every selected PDF/PPTX page or DOCX segment when `pageCount > 1` ends with `--- end of page.page_number=N ---`. Images are always extracted into images/ with relative links. Primary engine pymupdf4llm, fallback PyMuPDF text (degraded, marked), pure-JS unpdf only when no Python backend exists. Excel yields a sheet inventory (worksheets + chartsheets), a full CSV per non-empty worksheet under sheets/, a bounded preview with formulas and cached values, merged/hidden disclosure, and rendered chart views when LibreOffice is available. DOCX converts directly (mammoth; python-docx text fallback) and keeps heading styles, so the handle Outline lists `L<line>` and `p<segment>` per heading; LibreOffice (soffice) is optional for DOCX (fallback route, degraded) and Excel rendered views, and required for PPTX. Use `outputDir` for a durable bundle; without it the bundle lands in a per-call temp dir. Input must be a local file path (use fetch first for URLs). HTML converts without Readability (markdownify; Turndown fallback): local and data: images are copied into images/, remote images stay links. Pages without a text layer and image inputs always keep their picture in images/. OCR is off by default: `ocr: true` adds recognized text (labeled as OCR) when Tesseract language data is installed; the handle's OCR: line says what ran.",
-		promptSnippet: "Convert a local PDF/DOCX/PPTX/XLSX/HTML/image to a Markdown bundle (handle returned; read Saved-To)",
+			"Convert a local PDF/DOCX/DOC/PPTX/XLSX/XLSM/XLS, email (.msg/.eml), HTML (.html/.htm) or image (.png .jpg .jpeg .tif .tiff .bmp .gif) to a Markdown bundle on disk and return a handle (Saved-To, Images-Dir, Page-Count, Outline, diagnostics) - the Markdown itself is never inlined; read the Saved-To file (offset/limit) for content. `info: true` returns page count, metadata and TOC (or the sheet inventory) without converting - use it to pick `pages`. `pages` selects inclusive 1-based pages (PDF/PPTX) or explicit-page-break segments (DOCX; rejected when the file has none); every selected PDF/PPTX page or DOCX segment when `pageCount > 1` ends with `--- end of page.page_number=N ---`. Images are always extracted into images/ with relative links. Primary engine pymupdf4llm, fallback PyMuPDF text (degraded, marked), pure-JS unpdf only when no Python backend exists. Excel yields a sheet inventory (worksheets + chartsheets), a full CSV per non-empty worksheet under sheets/, a bounded preview with formulas and cached values, merged/hidden disclosure, and rendered chart views when LibreOffice is available. DOCX converts directly (mammoth; python-docx text fallback) and keeps heading styles, so the handle Outline lists `L<line>` and `p<segment>` per heading; LibreOffice (soffice) is optional for DOCX (fallback route, degraded) and Excel rendered views, and required for PPTX. Use `outputDir` for a durable bundle; without it the bundle lands in a per-call temp dir. Input must be a local file path (use fetch first for URLs). HTML converts without Readability (markdownify; Turndown fallback): local and data: images are copied into images/, remote images stay links. Pages without a text layer keep their picture in images/, or pages/ with `pageImages: true`; image inputs keep their picture in images/. `pageImages: true` writes page renders to pages/<stem>-pNNN, and email attachments are saved under attachments/. OCR is off by default: `ocr: true` adds recognized text (labeled as OCR) when Tesseract language data is installed; the handle's OCR: line says what ran.",
+		promptSnippet: "Convert a local PDF/DOCX/DOC/PPTX/XLSX/XLSM/XLS/MSG/EML/HTML/image to a Markdown bundle (handle returned; read Saved-To)",
 		parameters: buildSchema(),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {