pi-quiver 6.4.0 → 6.5.0

package/CHANGELOG.md

@@ -8,6 +8,11 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v6.5.0 - 2026-09-29
+
+- `doc_to_md` converts DOCX directly in the Python child (mammoth -> markdownify, python-docx text fallback) instead of LibreOffice -> PDF: heading styles survive as `#` headings, hyperlinks and footnotes are kept, pictures land under `images/` (#24). DOCX page semantics change: only author-inserted page breaks become `--- end of page.page_number=N ---` markers, `Page-Count` is suffixed `(explicit page breaks, not printed pages)` / `(no explicit page breaks)`, `pages` selects those segments and is rejected on a break-less file, and DOCX that falls back to LibreOffice (no DOCX-capable Python, or both DOCX engines failed) is marked degraded with `(LibreOffice pagination)` and rejects `pages`. LibreOffice is now optional for DOCX and still required for PPTX. Backend probe gains a `DOCX` line and pins `mammoth==1.13.0`, `markdownify==1.2.3`, `python-docx==1.2.0`; the managed venv moves to `doc-to-md-venv-v3` and the older venvs are removed after the first successful build.
+- `doc_to_md` handle: the `Outline` gains a `p<N>` page column (the page whose marker closes each heading's segment) for every format that emits page markers, and prints `Outline: none` when the Markdown has no headings. DOCX `info` returns core properties and a heading TOC with segment pages, or `TOC: none (no heading styles found)`.
+
 ## v6.4.0 - 2026-09-28
 
 - provider-stall-watchdog: per-model threshold overrides via a `models` map on `quiver.providerStallWatchdog` - glob keys like `lmstudio/*` override `firstEventMs`/`warningMs`/`recoveryMs` for matching models, so slow local servers get patience without raising the global defaults (#18).

package/README.md

@@ -65,7 +65,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | Extension | Tool | What it does |
 | --- | --- | --- |
 | `extensions/fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run/actions-job URLs auto-route through `gh` (falls back to HTTP); failed runs/jobs include failed-step logs (best-effort, summary-only otherwise). Same size gate as `fetch`. Behavior lives in `lib/fetch-core.ts`; also exposed as the `pi-quiver fetch` CLI (see [Claude Code support](#claude-code-support)). |
-| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX/XLSX/XLS to a Markdown bundle on disk (`<stem>.md` + `images/` and spreadsheet `sheets/`) and return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` mode inspects first; `pages` selects 1-based pages; every page ends with `--- end of page.page_number=N ---`. Tiers: pymupdf4llm -> PyMuPDF text (degraded) -> unpdf worker (no Python only). Excel -> sheet inventory, full CSVs, bounded previews, and optional rendered views. Settings under `quiver.docToMd`. |
+| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX/XLSX/XLS to a Markdown bundle on disk (`<stem>.md` + `images/` and spreadsheet `sheets/`) and return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` mode inspects first; `pages` selects 1-based pages (DOCX: explicit-page-break segments); every selected PDF/PPTX page or DOCX segment when `pageCount > 1` ends with `--- end of page.page_number=N ---`. Tiers: pymupdf4llm -> PyMuPDF text (degraded) -> unpdf worker (no Python only). Excel -> sheet inventory, full CSVs, bounded previews, and optional rendered views. DOCX converts directly (mammoth, python-docx fallback); LibreOffice pagination marks the degraded route. The Outline lists `L<line>` and `p<page>` per heading. Settings under `quiver.docToMd`. |
 | `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, naming rules and deny list, long-session revisits, and Ghostty/Herdr tab rename. OFF by default. |
 | `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
 | `extensions/fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
@@ -133,8 +133,8 @@ The npm package's bundled JS deps install automatically on `pi install`. A few *
 | Prerequisite | Needed by | If absent |
 | --- | --- | --- |
 | `gh` (GitHub CLI, installed + `gh auth login`) | `fetch` GitHub issue/PR/repo/actions-run/actions-job routing | Falls back to an HTTP fetch of the rendered page (private repos hit a login wall). |
-| `uv` (+ managed Python 3.14, fetched on first use) | `doc_to_md` high-fidelity PDF and Excel conversion (preferred route), with `pymupdf4llm`, `openpyxl`, `xlrd`, and `pillow` | Falls back to a system Python >= 3.12 or one-time managed venv; PDF degrades to `unpdf` only when no capable Python exists. Excel requires the Python backend (no JS fallback). |
-| LibreOffice (`soffice` on `PATH`) | `doc_to_md` DOCX/PPTX conversion | Office inputs error (no JS fallback for office->PDF); PDFs unaffected. |
+| `uv` (+ managed Python 3.14, fetched on first use) | `doc_to_md` high-fidelity PDF and Excel conversion and DOCX (preferred route), with `pymupdf4llm`, `openpyxl`, `xlrd`, `pillow`, `mammoth`, `markdownify`, and `python-docx` | Falls back to a system Python >= 3.12 or one-time managed venv; PDF degrades to `unpdf` only when no capable Python exists. Excel requires the Python backend (no JS fallback). |
+| LibreOffice (`soffice` on `PATH`) | `doc_to_md` PPTX conversion, the DOCX fallback route, and Excel rendered views | PPTX errors with a remedy; DOCX converts directly via the Python backend (LibreOffice fills in when that backend lacks the DOCX packages or its DOCX child exits 1); Excel omits rendered views. |
 
 None is a hard install-time dependency of the package; they are tools you provide in the environment where pi runs.
 
@@ -294,9 +294,9 @@ Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `
 
 | Key | Default | Meaning |
 |---|---|---|
-| `primaryTimeoutMs` | `60000` | pymupdf4llm tier and unpdf tier deadline. |
-| `fallbackTimeoutMs` | `30000` | PyMuPDF text tier, PDF info, and Excel rendered-view rasterization deadline. |
-| `sofficeTimeoutMs` | `120000` | DOCX/PPTX -> PDF deadline; also the Excel rendered-view export. |
+| `primaryTimeoutMs` | `60000` | pymupdf4llm tier, DOCX child (`docx` mode), and unpdf tier deadline. |
+| `fallbackTimeoutMs` | `30000` | PyMuPDF text tier (including the DOCX LibreOffice fallback), PDF and DOCX info, and Excel rendered-view rasterization deadline. |
+| `sofficeTimeoutMs` | `120000` | PPTX -> PDF, the DOCX LibreOffice fallback, and the Excel rendered-view export deadline. |
 | `excelTimeoutMs` | `60000` | Excel child and Excel info deadline. |
 | `warmTimeoutMs` | `120000` | Absolute first-call backend discovery/bootstrap deadline. |
 | `pymupdfVersion` | `1.27.2.3` | pymupdf4llm pin, minimum `1.27.0`. |
@@ -309,7 +309,7 @@ A bundle is `<outputDir>/<stem>.md` plus `<outputDir>/images/` and, for spreadsh
 
 Excel needs a Python backend with openpyxl, xlrd and pillow - otherwise the call fails with `Remedy: install uv, or pip install openpyxl xlrd pillow`. The Markdown opens with a `## Sheets` table listing every sheet in workbook order (0-based `#`, `worksheet`/`chartsheet`, size, hidden, chart and image counts, rendered view, CSV link for non-empty worksheets), then one section per sheet: a `Data:` line linking the full-content CSV under `sheets/` for non-empty worksheets, chart metadata from the workbook model, embedded images, an optional rendered view, a preview of at most the first 100 rows x 50 columns, and - only when the preview is truncated - a `Columns:` profile (type, non-empty count, min/max, distinct up to 50). Sizes are the extent of non-empty cells (the `info` handle reports the raw worksheet dimensions instead, which may be larger). Rendered views (`images/<stem>-s<idx>.<fmt>`) are produced for sheets carrying charts or images when LibreOffice is on `PATH`: the workbook is exported one PDF page per sheet and rasterized under a 16 Mpx budget. Any LibreOffice or rasterization failure degrades to `Rendered view: unavailable (<reason>)` and a handle note; it never fails the conversion. Workbooks whose chartsheet drawings carry a zero-size anchor (openpyxl-authored files; Excel-authored files are unaffected) render as a degenerate page and are reported as such. `.xls` gets the inventory, CSVs and previews but no visual detection or rendering.
 
-Worst-case wall time is `warmTimeoutMs (first call) + sofficeTimeoutMs (Office only) + primaryTimeoutMs + fallbackTimeoutMs + KILL_GRACE_MS x kills` (Excel: `warmTimeoutMs + excelTimeoutMs + sofficeTimeoutMs + fallbackTimeoutMs + 2 * KILL_GRACE_MS`). There is no cap on image count, image bytes, cell count or workbook memory - deliberately; the per-tier timeouts, the rendered-view pixel budget and `maxOutputBytes` are the bounds.
+Worst-case wall time: PDF `warmTimeoutMs (first call) + primaryTimeoutMs + fallbackTimeoutMs`; PPTX adds `sofficeTimeoutMs`; DOCX on the Python path `warmTimeoutMs + primaryTimeoutMs` (success or a terminal child failure), DOCX child exit 1 then LibreOffice `warmTimeoutMs + primaryTimeoutMs + sofficeTimeoutMs + primaryTimeoutMs + fallbackTimeoutMs`, DOCX without a DOCX-capable backend `warmTimeoutMs + sofficeTimeoutMs + primaryTimeoutMs + fallbackTimeoutMs`; Excel `warmTimeoutMs + excelTimeoutMs + sofficeTimeoutMs + fallbackTimeoutMs`. Add `KILL_GRACE_MS` (2000 ms) per kill. There is no cap on image count, image bytes, cell count or workbook memory - deliberately; the per-tier timeouts, the rendered-view pixel budget and `maxOutputBytes` are the bounds.
 
 ### Migrating from flat keys
 

package/dist/bin/pi-quiver.js

@@ -517,7 +517,7 @@ async function fetchUrl(opts) {
 }
 
 // lib/doc-to-md-core.ts
-import { existsSync as existsSync2, mkdtempSync, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync2, mkdtempSync, readdirSync as readdirSync2, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir, tmpdir as tmpdir3 } from "node:os";
 import { basename, dirname, extname as extname3, join as join3, resolve as resolve2 } from "node:path";
@@ -697,11 +697,19 @@ function compactRanges(nums, maxEntries = 20) {
   if (parts.length <= maxEntries) return parts.join(", ");
   return `${parts.slice(0, maxEntries).join(", ")} (+${parts.length - maxEntries} more)`;
 }
+var PAGE_MARKER_RE = /^--- end of page\.page_number=(\d+) ---$/;
 function scanOutline(md, max) {
   const entries = [];
+  let pending = [];
   let total = 0, inFence = false;
   md.split("\n").forEach((raw, i) => {
     const line = raw.replace(/\r$/, "");
+    const marker = line.match(PAGE_MARKER_RE);
+    if (marker) {
+      for (const e of pending) e.page = Number(marker[1]);
+      pending = [];
+      return;
+    }
     if (/^\s*(```|~~~)/.test(line)) {
       inFence = !inFence;
       return;
@@ -710,23 +718,36 @@ function scanOutline(md, max) {
     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) });
+    if (entries.length < max) {
+      const e = { line: i + 1, level: m[1].length, title: trunc(m[2].trim(), TITLE_MAX), page: null };
+      entries.push(e);
+      pending.push(e);
+    }
   });
   return { entries, total };
 }
 function outlineLines(entries, total) {
+  if (total === 0) return ["Outline: none"];
   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)}`)];
+  const lineWidth = Math.max(3, ...entries.map((e) => `L${e.line}`.length)) + 2;
+  const paged = entries.filter((e) => e.page !== null);
+  const pageWidth = paged.length ? Math.max(...paged.map((e) => `p${e.page}`.length)) + 2 : 0;
+  const out = ["Outline:", ...entries.map((e) => `  ${`L${e.line}`.padEnd(lineWidth)}${pageWidth ? (e.page === null ? "" : `p${e.page}`).padEnd(pageWidth) : ""}${"#".repeat(e.level)} ${trunc(e.title, TITLE_MAX)}`)];
   if (total > entries.length) out.push(`  (+${total - entries.length} more)`);
   return out;
 }
+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"})`;
+  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}`);
   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`);
+  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}`);
   if (h.fallbackReason) lines.push(`Fallback-Reason: ${h.fallbackReason}`);
   const fe = [];
@@ -752,9 +773,9 @@ function formatInfoHandle(i, max) {
   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})`));
+    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)`);
-  }
+  } else if (i.type === "docx") lines.push("TOC: none (no heading styles found)");
   return lines.join("\n");
 }
 
@@ -767,11 +788,11 @@ 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: "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: "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 and Excel rendered views" },
+  { 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" },
   { 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)" },
@@ -892,21 +913,22 @@ 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" };
+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 KILL_GRACE_MS = 2e3;
-var VENV_DIR_NAME = "doc-to-md-venv-v2";
-var LEGACY_VENV_DIR_NAME = "pymupdf-venv";
+var VENV_DIR_NAME = "doc-to-md-venv-v3";
+var LEGACY_VENV_DIR_NAMES = ["pymupdf-venv", "doc-to-md-venv-v2"];
 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"]}`];
 function withArgs(cfg) {
-  return ["--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--with", `openpyxl==${PACKAGE_PINS.openpyxl}`, "--with", `xlrd==${PACKAGE_PINS.xlrd}`, "--with", `pillow==${PACKAGE_PINS.pillow}`];
+  return pinSpecs(cfg).flatMap((spec) => ["--with", spec]);
 }
 function pipInstallArgs(cfg) {
-  return ["-m", "pip", "install", `pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`];
+  return ["-m", "pip", "install", ...pinSpecs(cfg)];
 }
 function warmArgs(cfg) {
-  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL"];
+  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL, mammoth, markdownify, docx"];
 }
 function uvChildArgs(cfg, script, mode) {
   return ["run", ...withArgs(cfg), "--python", "3.14", "python", script, mode];
@@ -1058,6 +1080,11 @@ try:
     print("XLSX", "yes")
 except Exception:
     print("XLSX", "no")
+try:
+    import mammoth, markdownify, docx
+    print("DOCX", "yes")
+except Exception:
+    print("DOCX", "no")
 `;
 var PROBE_TIMEOUT_MS = 5e3;
 function probeArgs() {
@@ -1065,8 +1092,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)\s*$/);
-  return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes" } : null;
+  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;
 }
 function meetsFloor(p) {
   return p.major > 3 || p.major === 3 && p.minor >= 12;
@@ -1091,7 +1118,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 };
+  if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true, docx: true };
   const uvAbsent = warm.code === null && !warm.timedOut;
   const isDeadline = (result) => result !== null && "kind" in result;
   const probe = async (exe, tmp) => {
@@ -1107,18 +1134,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 };
+    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx, docx: p.docx };
     eligible ??= { exe, version: `${p.major}.${p.minor}` };
   }
+  const healthy = (p) => meetsFloor(p) && p.pdf && p.xlsx && p.docx;
   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 && meetsFloor(cached) && cached.pdf && cached.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+  if (cached && healthy(cached)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
   if (eligible) {
     const recheck = await probe(venvExe);
     if (isDeadline(recheck)) return recheck;
-    if (recheck && meetsFloor(recheck) && recheck.pdf && recheck.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+    if (recheck && healthy(recheck)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
     const tmp = `${venvDir}.tmp-${deps.pid}`;
     const bootFail = (stderr) => {
       deps.rmrf(tmp);
@@ -1143,19 +1171,19 @@ async function resolveBackend(cfg, deps, signal) {
       }
     };
     if (publish()) {
-      deps.rmrf(join3(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+      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 };
     }
     const winner = await probe(venvExe, tmp);
     if (isDeadline(winner)) return winner;
-    if (winner && meetsFloor(winner) && winner.pdf && winner.xlsx) {
+    if (winner && healthy(winner)) {
       deps.rmrf(tmp);
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
     }
     deps.rmrf(venvDir);
     if (publish()) {
-      deps.rmrf(join3(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+      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 bootFail("rename after competing bootstrap");
   }
@@ -1213,15 +1241,23 @@ async function tryConvertOffice(sofficeTimeoutMs, src, signal, run = runCapped,
     throw e;
   }
 }
-async function convertOffice(sofficeTimeoutMs, src, signal, run = runCapped) {
-  const r = await tryConvertOffice(sofficeTimeoutMs, src, signal, run);
-  if (r.ok) return r;
-  if (r.kind === "missing") 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.kind === "no-pdf") 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.");
-  throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr}`);
+function officeFailure(r) {
+  if (r.kind === "missing") return 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.kind === "no-pdf") return 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.");
+  return new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr}`);
 }
 var DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preserved";
 var DEGRADED_UNPDF = "unpdf text extraction - structure not preserved";
+var DEGRADED_DOCX_TEXT = "python-docx text extraction - footnotes, hyperlinks, images not preserved";
+var DEGRADED_DOCX_OFFICE = "LibreOffice PDF route - heading styles and explicit page breaks not preserved; page numbers are LibreOffice pagination";
+var DOCX_PIP = "pip install mammoth markdownify python-docx";
+var DOCX_PAGES_OFFICE = `--pages on a DOCX needs the Python DOCX backend (explicit page-break segments); the LibreOffice route has none. Remedy: install uv, or ${DOCX_PIP}`;
+var docxRemedy = `Remedy: install uv, or ${DOCX_PIP} into a Python that already has pymupdf4llm`;
+var backendState = (b, missing) => b.kind === "none" ? b.reason : missing;
+var lacksDocx = (b) => b.kind === "none" || !b.docx;
+var clearStaging = (b) => {
+  for (const f of readdirSync2(b.stagingDir)) rmSync2(join3(b.stagingDir, f), { recursive: true, force: true });
+};
 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;
@@ -1291,78 +1327,120 @@ async function convertDocument(o, signal, seams) {
   let office = null;
   try {
     let pdfPath = inputPath;
-    if (type === "docx" || type === "pptx") {
-      office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
-      pdfPath = office.pdfPath;
-    }
-    const base = { path: pdfPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion };
+    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 };
     let tier, engine, json, degraded = null, fallbackReason = null;
+    let explicitBreaks = null;
     let notes = [];
-    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" : "";
-        throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
+    let officeRoute = null;
+    if (type === "docx" && !lacksDocx(backend)) {
+      const d = await s.runTier("docx", base, b, signal, o.primaryTimeoutMs, backend);
+      if (d.ok) {
+        publishStaged(b);
+        tier = "docx";
+        engine = d.json.engine === "python-docx" ? "python-docx" : "mammoth";
+        json = d.json;
+        explicitBreaks = d.json.explicitBreaks ?? 0;
+        if (d.json.degraded) {
+          degraded = DEGRADED_DOCX_TEXT;
+          fallbackReason = d.json.fallbackReason ?? null;
+        }
+      } else if ("userError" in d) throw new Error(d.userError);
+      else if (d.reason === "exit 1") {
+        officeRoute = `docx ${d.reason}${detailSuffix(d)}`;
+        clearStaging(b);
+      } else throw new Error(`Conversion failed: docx ${d.reason}${detailSuffix(d)}`);
+    } else if (type === "docx") officeRoute = backend.kind === "none" ? backend.reason : "python backend lacks DOCX packages";
+    if (type === "docx" && officeRoute !== null) {
+      if (o.pages) throw new Error(officeRoute.startsWith("docx exit") ? `${DOCX_PAGES_OFFICE} (${officeRoute})` : DOCX_PAGES_OFFICE);
+      const r = await s.office(o.sofficeTimeoutMs, inputPath, signal);
+      if (!r.ok && r.kind === "missing") {
+        if (officeRoute.startsWith("docx exit")) throw new Error(`Conversion failed: ${officeRoute}; LibreOffice (soffice) not found on PATH`);
+        throw new Error(`DOCX conversion needs the Python DOCX packages or LibreOffice. Python backend: ${backendState(backend, "found without mammoth/markdownify/python-docx")}. ${docxRemedy}, or install LibreOffice (soffice)`);
       }
-      publishSheetImages(b);
-      publishSheetCsvs(b);
-      tier = "excel";
-      engine = type === "xls" ? "xlrd" : "openpyxl";
-      json = r.json;
-      notes = [...json.notes ?? []];
-      const renderPages = json.renderPages ?? [];
-      let skip = null;
-      const perSheet = /* @__PURE__ */ new Map();
-      if (renderPages.length) {
-        const off = await s.office(o.sofficeTimeoutMs, inputPath, signal, runCapped, EXCEL_PDF_FILTER);
-        if (!off.ok) skip = off.kind === "missing" ? "LibreOffice not found" : off.kind === "timeout" ? `soffice failed: timeout after ${o.sofficeTimeoutMs}ms` : off.kind === "exit" ? `soffice failed: exit ${off.code}` : "soffice produced no PDF";
-        else {
-          try {
-            const rp = await s.runTier("render-pages", { path: off.pdfPath, sheetIndices: renderPages, expectedPages: json.sheetCount, imageDpi: o.imageDpi, imageFormat: o.imageFormat, stagingDir: b.stagingDir, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.fallbackTimeoutMs, backend);
-            if (!rp.ok) skip = `render failed: ${"userError" in rp ? rp.userError : rp.reason}`;
-            else if (rp.json.ok === false) skip = rp.json.reason ?? "render failed";
-            else {
-              publishSheetImages(b);
-              for (const f of rp.json.failed ?? []) perSheet.set(f.idx, f.reason);
-              for (const d of rp.json.rendered ?? []) if (d.dpi < o.imageDpi) notes.push(`Rendered view s${d.idx}: rendered at ${d.dpi} dpi`);
+      if (!r.ok) throw officeRoute.startsWith("docx exit") ? new Error(`Conversion failed: ${officeRoute}; ${officeFailure(r).message}`) : officeFailure(r);
+      office = r;
+      pdfPath = r.pdfPath;
+    }
+    if (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) throw officeFailure(r);
+      office = r;
+      pdfPath = r.pdfPath;
+    }
+    const pdfBase = { ...base, path: pdfPath };
+    if (json === void 0) {
+      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" : "";
+          throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
+        }
+        publishSheetImages(b);
+        publishSheetCsvs(b);
+        tier = "excel";
+        engine = type === "xls" ? "xlrd" : "openpyxl";
+        json = r.json;
+        notes = [...json.notes ?? []];
+        const renderPages = json.renderPages ?? [];
+        let skip = null;
+        const perSheet = /* @__PURE__ */ new Map();
+        if (renderPages.length) {
+          const off = await s.office(o.sofficeTimeoutMs, inputPath, signal, runCapped, EXCEL_PDF_FILTER);
+          if (!off.ok) skip = off.kind === "missing" ? "LibreOffice not found" : off.kind === "timeout" ? `soffice failed: timeout after ${o.sofficeTimeoutMs}ms` : off.kind === "exit" ? `soffice failed: exit ${off.code}` : "soffice produced no PDF";
+          else {
+            try {
+              const rp = await s.runTier("render-pages", { path: off.pdfPath, sheetIndices: renderPages, expectedPages: json.sheetCount, imageDpi: o.imageDpi, imageFormat: o.imageFormat, stagingDir: b.stagingDir, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.fallbackTimeoutMs, backend);
+              if (!rp.ok) skip = `render failed: ${"userError" in rp ? rp.userError : rp.reason}`;
+              else if (rp.json.ok === false) skip = rp.json.reason ?? "render failed";
+              else {
+                publishSheetImages(b);
+                for (const f of rp.json.failed ?? []) perSheet.set(f.idx, f.reason);
+                for (const d of rp.json.rendered ?? []) if (d.dpi < o.imageDpi) notes.push(`Rendered view s${d.idx}: rendered at ${d.dpi} dpi`);
+              }
+            } finally {
+              off.cleanup();
             }
-          } finally {
-            off.cleanup();
           }
+          if (skip) notes.push(`Rendered views skipped: ${skip}`);
+          else if (perSheet.size) notes.push(`Rendered views: ${perSheet.size} of ${renderPages.length} unavailable`);
+        }
+        json = { ...json, markdown: reconcileRenderMarkers(json.markdown ?? "", renderPages, o.imageFormat, b.sourceMap, (idx) => perSheet.get(idx) ?? skip ?? "render failed") };
+      } else if (backend.kind === "none") {
+        const r = await s.runTier("pdf-text", pdfBase, 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", pdfBase, 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", { ...pdfBase, 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}`;
         }
-        if (skip) notes.push(`Rendered views skipped: ${skip}`);
-        else if (perSheet.size) notes.push(`Rendered views: ${perSheet.size} of ${renderPages.length} unavailable`);
-      }
-      json = { ...json, markdown: reconcileRenderMarkers(json.markdown ?? "", renderPages, o.imageFormat, b.sourceMap, (idx) => perSheet.get(idx) ?? skip ?? "render failed") };
-    } 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}`;
       }
     }
+    if (officeRoute !== null) {
+      degraded = DEGRADED_DOCX_OFFICE;
+      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 = json.notes ?? [];
     const body = rewriteLinks(json.markdown ?? "", b.sourceMap);
     validateImageLinks(body, b.manifest, b.csvManifest);
@@ -1377,7 +1455,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, 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 };
+    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 };
     return { output: formatHandle(details), details };
   } catch (e) {
     abortBundle(b);
@@ -1398,9 +1476,13 @@ async function inspectDocument(o, signal, seams) {
   let office = null;
   try {
     let path = inputPath;
-    if (type === "docx" || type === "pptx") {
-      office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
-      path = office.pdfPath;
+    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") {
+      const r2 = await s.office(o.sofficeTimeoutMs, inputPath, signal);
+      if (!r2.ok) throw officeFailure(r2);
+      office = r2;
+      path = r2.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) {

package/extensions/doc_to_md.ts

@@ -35,7 +35,7 @@ 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 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/DOCX/PPTX); every page 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/PPTX need LibreOffice (soffice). 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).",
+			"Convert a local PDF/DOCX/PPTX/XLSX/XLS 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).",
 		promptSnippet: "Convert a local PDF/DOCX/PPTX/XLSX to a Markdown bundle (handle returned; read Saved-To)",
 		parameters: buildSchema(),