pi-quiver 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
+## v4.4.0 - 2026-08-26
+
+- doc_to_md: backend ladder now tries a system Python >= 3.12 with `pymupdf4llm` importable, then a one-time managed venv (bootstrapped at the version pin into a per-OS cache dir) between the existing `uv` and `unpdf` rungs. Data plane extracted to pi-free `lib/doc-to-md-core.ts`; new `pi-quiver doc-to-md <path>` CLI subcommand and `doc-to-md` Claude Code skill. `uv`/`soffice` detection is now spawn-based (Windows-correct). The bundled Python conversion script is now resolved from the package root, fixing a path bug that broke it under the bundled CLI.
+
 ## v4.3.0 - 2026-08-25
 
 - fetch: GitHub Actions job URLs (`.../actions/runs/<runId>/job/<jobId>`, singular `/job/` as GitHub's UI produces) now route through `gh run view --job <jobId> --repo <slug>`; plural `/jobs/<id>` paths still fall back to plain HTTP. Both run and job fetches now make a best-effort second `gh run view ... --log-failed` call and append its output under a `## Failed step logs` heading; when nothing failed, the run is still in progress, or logs have expired, the call yields no section and behavior is unchanged (summary-only).

package/README.md

@@ -63,7 +63,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 `doc_to_md`. 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 to Markdown. High-fidelity via `pymupdf4llm` (run through `uv`); degraded pure-JS fallback (`unpdf`) when `uv`/Python is unavailable or conversion times out. DOCX/PPTX convert via LibreOffice first. |
+| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm`, resolved per process (`uv` -> system Python >= 3.12 with the package -> one-time managed venv in the user cache dir); degraded pure-JS fallback (`unpdf`) otherwise. DOCX/PPTX convert via LibreOffice first. Behavior lives in `lib/doc-to-md-core.ts`; also exposed as the `pi-quiver doc-to-md` CLI (see [Claude Code support](#claude-code-support)). |
 | `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, naming rules and deny list, long-session revisits, and Ghostty 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. |
@@ -130,7 +130,7 @@ 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 conversion | Degrades to the pure-JS `unpdf` fallback (no faithful tables/headings). |
+| `uv` (+ managed Python 3.14, fetched on first use) | `doc_to_md` high-fidelity PDF conversion (preferred route) | Falls back to a system Python >= 3.12 with `pymupdf4llm` (or a one-time managed venv it bootstraps); only when no capable Python exists does it degrade to `unpdf`. |
 | LibreOffice (`soffice` on `PATH`) | `doc_to_md` DOCX/PPTX conversion | Office inputs error (no JS fallback for office->PDF); PDFs unaffected. |
 
 None is a hard install-time dependency of the package; they are tools you provide in the environment where pi runs.
@@ -209,9 +209,9 @@ Operational notes:
 
 `fetch`'s core (`lib/fetch-core.ts`) is also published as a CLI, so Claude Code can use the same routing, size gate, and spill behavior as pi's native tool - without pi ever seeing Claude-only files.
 
-**Exposed:** the `quiver` plugin, served from this repo's `.claude-plugin/marketplace.json`, with one skill: `fetch` (invoked as `quiver:fetch` / `/quiver:fetch`). The skill runs `npx -y pi-quiver@latest fetch <url> [flags]` via Bash - full parameter parity with the pi tool (`--method`, `--header`, `--body`, `--raw`, `--timeout-ms`), same GitHub `gh` routing (including failed-step logs on failed runs/jobs), same size gate, same binary-to-temp-file handling. See [doc/fetch.md](doc/fetch.md#claude-code-cli-pi-quiver-fetch) for exit codes and flags.
+**Exposed:** the `quiver` plugin, served from this repo's `.claude-plugin/marketplace.json`, with two skills: `fetch` (invoked as `quiver:fetch` / `/quiver:fetch`) and `doc-to-md` (invoked as `quiver:doc-to-md` / `/quiver:doc-to-md`). The `fetch` skill runs `npx -y pi-quiver@latest fetch <url> [flags]` via Bash - full parameter parity with the pi tool (`--method`, `--header`, `--body`, `--raw`, `--timeout-ms`), same GitHub `gh` routing (including failed-step logs on failed runs/jobs), same size gate, same binary-to-temp-file handling. See [doc/fetch.md](doc/fetch.md#claude-code-cli-pi-quiver-fetch) for exit codes and flags. The `doc-to-md` skill runs `npx -y pi-quiver@latest doc-to-md <path>` via Bash - same backend ladder, size gate, and degraded-fallback marking as the pi tool. See [doc/doc-to-md.md](doc/doc-to-md.md#cli-pi-quiver-doc-to-md) for exit codes.
 
-**Not exposed:** pi extensions, `doc_to_md`, and everything else in this package - the marketplace allowlists only `./skills/fetch`, and the npm tarball never ships `skills/` or `.claude-plugin/` (pi's own `files` allowlist excludes them, and pi's explicit `pi.extensions` manifest makes them invisible to pi's convention-directory auto-discovery either way).
+**Not exposed:** the other pi extensions in this package (`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`) - the marketplace allowlists only `./skills/fetch` and `./skills/doc-to-md`, and the npm tarball never ships `skills/` or `.claude-plugin/` (pi's own `files` allowlist excludes them, and pi's explicit `pi.extensions` manifest makes them invisible to pi's convention-directory auto-discovery either way).
 
 Add the marketplace and enable the plugin in `.claude/settings.json`:
 

package/dist/bin/pi-quiver.js

@@ -2,8 +2,8 @@
 
 // bin/pi-quiver.ts
 import { realpathSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { resolve } 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 +318,8 @@ function binaryExtension(contentType) {
   return sub || "bin";
 }
 function writeChunk(stream, b) {
-  return new Promise((resolve2, reject) => {
-    stream.write(b, (err) => err ? reject(err) : resolve2());
+  return new Promise((resolve3, reject) => {
+    stream.write(b, (err) => err ? reject(err) : resolve3());
   });
 }
 async function pumpToFile(stream, reader, prefix, exhausted) {
@@ -343,7 +343,7 @@ async function pumpToFile(stream, reader, prefix, exhausted) {
     await writeChunk(stream, chunk);
     bytes += chunk.length;
   }
-  await new Promise((resolve2, reject) => stream.end((err) => err ? reject(err) : resolve2()));
+  await new Promise((resolve3, reject) => stream.end((err) => err ? reject(err) : resolve3()));
   return { bytes, truncated };
 }
 async function collectBody(res, contentType, raw) {
@@ -515,9 +515,479 @@ 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 { 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 { fileURLToPath } 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}")`);
+  }
+  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)
+  };
+}
+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 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 withMarker(md, degraded) {
+  return degraded ? `${DEGRADED_MARKER}
+
+${md}` : md;
+}
+function pagesToMarkdown(pages) {
+  return pages.map((p) => p.trim()).filter((p) => p.length > 0).join(PAGE_SEP);
+}
+function tempFilePath2(inputPath, ext) {
+  const dir = join2(tmpdir2(), "pi-doc-to-md");
+  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}`);
+}
+function spillToFile2(inputPath, body) {
+  const file = tempFilePath2(inputPath, "md");
+  writeFileSync2(file, `${body}
+`, "utf8");
+  return file;
+}
+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]`;
+  }
+  return preview;
+}
+function warmArgs(cfg) {
+  return ["run", "--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--python", "3.14", "python", "-c", "import pymupdf4llm"];
+}
+function convertArgs(cfg, scriptPath2, pdfPath) {
+  return ["run", "--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--python", "3.14", "python", scriptPath2, pdfPath];
+}
+function soffArgs(src, profileDir, outDir) {
+  return [
+    "--headless",
+    "--invisible",
+    "--nocrashreport",
+    "--nodefault",
+    "--nofirststartwizard",
+    "--nolockcheck",
+    "--nologo",
+    "--norestore",
+    "--quickstart=no",
+    `-env:UserInstallation=file://${profileDir}`,
+    "--convert-to",
+    "pdf",
+    "--outdir",
+    outDir,
+    src
+  ];
+}
+async function runCapped(cmd, args, opts) {
+  return new Promise((resolveP) => {
+    let settled = false;
+    let timedOut = false;
+    let capped = false;
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const child = spawn(cmd, args, { env: opts.env ?? process.env });
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      opts.signal?.removeEventListener("abort", onAbort);
+      resolveP({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+        code,
+        timedOut,
+        capped
+      });
+    };
+    const kill = () => child.kill("SIGKILL");
+    const onAbort = () => {
+      kill();
+    };
+    if (opts.signal?.aborted) {
+      kill();
+    } else opts.signal?.addEventListener("abort", onAbort);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, opts.timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      if (capped) return;
+      const remaining = opts.capBytes - stdoutBytes;
+      if (remaining <= 0) {
+        capped = true;
+        kill();
+        return;
+      }
+      if (chunk.length > remaining) {
+        stdoutChunks.push(chunk.subarray(0, remaining));
+        stdoutBytes += remaining;
+        capped = true;
+        kill();
+      } else {
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      if (stderrBytes >= STDERR_CAP) return;
+      const remaining = STDERR_CAP - stderrBytes;
+      const slice = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
+      stderrChunks.push(slice);
+      stderrBytes += slice.length;
+    });
+    child.on("error", (err) => {
+      if (stderrBytes < STDERR_CAP) {
+        const msg = Buffer.from(err.message);
+        const remaining = STDERR_CAP - stderrBytes;
+        stderrChunks.push(msg.length > remaining ? msg.subarray(0, remaining) : msg);
+      }
+      finish(null);
+    });
+    child.on("close", (code) => finish(code));
+  });
+}
+function findPackageRoot(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    if (existsSync(join2(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);
+  }
+}
+var PROBE_PROGRAM = `import sys
+print("PY", sys.version_info[0], sys.version_info[1])
+try:
+    import pymupdf4llm
+    print("PKG", pymupdf4llm.__version__)
+except Exception:
+    print("PKG", "none")
+`;
+var PROBE_TIMEOUT_MS = 5e3;
+function probeArgs() {
+  return ["-c", PROBE_PROGRAM];
+}
+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] };
+}
+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");
+}
+function venvPython(venvDir, platform) {
+  return platform === "win32" ? join2(venvDir, "Scripts", "python.exe") : join2(venvDir, "bin", "python");
+}
+function pythonConvertArgs(script, pdfPath) {
+  return [script, pdfPath];
+}
+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 });
+  if (signal?.aborted) throw new Error("aborted");
+  if (warm.code === 0 && !warm.timedOut) return { kind: "uv" };
+  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 });
+    if (signal?.aborted) throw new Error("aborted");
+    if (r.code !== 0 || r.timedOut) return null;
+    return parseProbeOutput(r.stdout);
+  };
+  let eligible = null;
+  for (const exe of PYTHON_CANDIDATES) {
+    const p = await probe(exe);
+    if (!p || !meetsFloor(p)) continue;
+    if (p.pkg) return { kind: "python", exe, version: p.pkg };
+    eligible ??= { exe, version: `${p.major}.${p.minor}` };
+  }
+  const venvDir = join2(deps.cacheRoot, "pymupdf-venv");
+  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 (eligible) {
+    const recheck = await probe(venvExe);
+    if (recheck && meetsFloor(recheck) && recheck.pkg) return { kind: "venv", exe: venvExe, version: recheck.pkg };
+    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 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 });
+    if (signal?.aborted) throw new Error("aborted");
+    if (pip.code !== 0 || pip.timedOut) return bootFail(pip.stderr);
+    const publish = () => {
+      try {
+        deps.rename(tmp, venvDir);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    if (publish()) return { kind: "venv", exe: venvExe, version: cfg.pymupdfVersion };
+    const winner = await probe(venvExe);
+    if (winner && meetsFloor(winner) && winner.pkg) {
+      deps.rmrf(tmp);
+      return { kind: "venv", exe: venvExe, version: winner.pkg };
+    }
+    deps.rmrf(venvDir);
+    if (publish()) return { kind: "venv", exe: venvExe, version: cfg.pymupdfVersion };
+    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` };
+}
+var backendPromise = null;
+function realDeps() {
+  return {
+    run: runCapped,
+    cacheRoot: cacheDir(process.platform, process.env, homedir()),
+    platform: process.platform,
+    pid: process.pid,
+    rename: renameSync,
+    rmrf: (p) => rmSync(p, { recursive: true, force: true }),
+    now: Date.now,
+    env: process.env
+  };
+}
+function getBackend(cfg, deps, signal) {
+  if (!backendPromise) {
+    const promise = resolveBackend(cfg, deps ?? realDeps(), signal);
+    backendPromise = promise;
+    promise.catch(() => {
+      if (backendPromise === promise) backendPromise = null;
+    });
+  }
+  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-"));
+  const cleanup = () => {
+    for (const d of [profileDir, outDir]) {
+      try {
+        rmSync(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 });
+    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 });
+    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.");
+    }
+    return { pdfPath, cleanup };
+  } catch (e) {
+    cleanup();
+    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;
+  }
+  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" };
+    }
+    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"
+      };
+    }
+  } finally {
+    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}`);
+  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 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>]';
+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] };
+  }
   if (argv[0] !== "fetch") return { ok: false, error: `unknown command: ${argv[0] ?? "(none)"}` };
   const rest = argv.slice(1);
   let url;
@@ -565,7 +1035,7 @@ function parseCliArgs(argv) {
   if (body !== void 0) opts.body = body;
   if (raw !== void 0) opts.raw = raw;
   if (timeoutMs !== void 0) opts.timeoutMs = timeoutMs;
-  return { ok: true, opts };
+  return { ok: true, cmd: "fetch", opts };
 }
 async function main() {
   const parsed = parseCliArgs(process.argv.slice(2));
@@ -575,6 +1045,18 @@ ${USAGE}
 `);
     return 2;
   }
+  if (parsed.cmd === "doc-to-md") {
+    try {
+      const result = await convertDocument(parsed.path, parseConfig(process.env));
+      process.stdout.write(`${result.output}
+`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(`doc-to-md failed: ${err instanceof Error ? err.message : String(err)}
+`);
+      return 1;
+    }
+  }
   try {
     const result = await fetchUrl(parsed.opts);
     process.stdout.write(`${result.output}
@@ -589,7 +1071,7 @@ ${USAGE}
 function isMainEntry() {
   if (!process.argv[1]) return false;
   try {
-    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]));
+    return realpathSync(fileURLToPath2(import.meta.url)) === realpathSync(resolve2(process.argv[1]));
   } catch {
     return false;
   }