pi-quiver 6.9.0 → 6.11.0

package/CHANGELOG.md

@@ -8,6 +8,19 @@ 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.11.0 - 2026-10-02
+
+- `doc_to_md`: textless PDF pages holding one eligible full-page image deliver the embedded stream without re-encoding; the handle prints `Native-Images:` and tool details / CLI JSON carry `nativeImages` (#27).
+- `doc_to_md`: native probing, PDF page renders, and textless-page inline OCR run in a spawned raster worker with per-job budgets; a toxic page becomes a `Failed pages` note instead of failing the conversion when other pages succeed (#27).
+- `doc_to_md`: the render ceiling rises from 16 to 50 Mpx; clamped PDF renders add Notes and report effective `pageImages[].dpi` plus `requestedDpi` (#27).
+- `doc_to_md`: `hideAnnotations` / `--hide-annotations` hides PDF annotations and form widgets on renders and lets annotated scans use native delivery; default runs keep their painted render (#27).
+- `doc_to_md`: `.done` markers retain native-image and clamp metadata for completed pages across primary-tier failure and fallback; corrupt metadata does not discard completed images (#27).
+
+## v6.10.0 - 2026-10-02
+
+- `doc_to_md`: new per-call `words` option (`--words`; not settable) writes `<stem>.words.json` - per selected PDF/image page, every text-layer word and every word inline OCR recognized in the same run, with display-space bbox (points; source pixels for images) and `source` `text`/`ocr`. Under `--ocr-mode all` each sidecar gets `ocr/<stem>-pNNN.words.json`. Never triggers OCR; Markdown, page stats and OCR outcome are unchanged. Handle gains `Words:`, `--json` gains `wordsPath`, `wordsReason`, `wordsErrors`, `ocr.wordSidecars`; `--info --words` is a usage error (#28).
+- `doc_to_md`: `--help` and the generated skill list every bundle artifact under `Bundle layout` (#28).
+
 ## v6.9.0 - 2026-10-01
 
 - `doc_to_md`: every conversion that goes through the Python PDF tiers (PDF, PPTX, `.doc`, DOCX via LibreOffice) writes `<stem>.pages.json` (per-page `chars`, `images`, `imageCoverage`) and the handle prints `Page-Stats:`; CLI `--json` gains `pageStats`, `pageStatsPath`, `ocrDir`. The unpdf tier writes no stats (#26).

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/DOC/PPTX/XLSX/XLSM/XLS, MSG/EML, HTML, or image file to a Markdown bundle on disk (`<stem>.md` + `images/`, spreadsheet `sheets/`, optional `pageImages` in `pages/`, and email `attachments/`) and return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` inspects PDF/Office inputs; `pages` selects 1-based PDF/Office pages (DOCX: explicit-page-break segments); HTML, image, and email inputs reject both; 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. HTML keeps local and `data:` images in the bundle and remote images as links; image inputs keep the original image. Scanned PDF pages keep a page picture on both Python tiers; opt-in OCR needs Tesseract language data. 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`. Every conversion that goes through the Python PDF tiers (PDF, PPTX, `.doc`, DOCX via LibreOffice) writes `<stem>.pages.json` (per-page chars, image count, image coverage; handle line `Page-Stats:`); unpdf writes no stats. `ocrMode: "all"` with `ocr: true` and an explicit `pages` forces OCR on those pages into `ocr/<stem>-pNNN.md` sidecars, leaving the Markdown byte-identical to the same selected-page call without OCR. |
+| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/DOC/PPTX/XLSX/XLSM/XLS, MSG/EML, HTML, or image file to a Markdown bundle on disk (`<stem>.md` + `images/`, spreadsheet `sheets/`, optional `pageImages` in `pages/`, and email `attachments/`) and return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` inspects PDF/Office inputs; `pages` selects 1-based PDF/Office pages (DOCX: explicit-page-break segments); HTML, image, and email inputs reject both; 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. HTML keeps local and `data:` images in the bundle and remote images as links; image inputs keep the original image. Scanned PDF pages keep a page picture on both Python tiers; eligible single full-page images are delivered as their embedded stream, without re-encoding or render DPI; opt-in OCR needs Tesseract language data. 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`. Every conversion that goes through the Python PDF tiers (PDF, PPTX, `.doc`, DOCX via LibreOffice) writes `<stem>.pages.json` (per-page chars, image count, image coverage; handle line `Page-Stats:`); unpdf writes no stats. `ocrMode: "all"` with `ocr: true` and an explicit `pages` forces OCR on those pages into `ocr/<stem>-pNNN.md` sidecars, leaving the Markdown byte-identical to the same selected-page call without OCR. `words: true` (CLI `--words`, per-call only - no settings key) writes `<stem>.words.json` with every word's bbox per selected PDF/image page (`source` `text` or `ocr`), plus `ocr/<stem>-pNNN.words.json` beside each forced-OCR sidecar; it never triggers OCR. |
 | `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. |
@@ -303,8 +303,9 @@ Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `
 | `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`. |
-| `imageDpi` | `150` | Render DPI for page images and Excel rendered views (capped by a 16 Mpx budget). |
+| `imageDpi` | `150` | Render DPI for page images and Excel rendered views (capped by a 50 Mpx budget). |
 | `imageFormat` | `png` | Rendered image format: `png` or `jpg`; embedded images retain their extension. |
+| `hideAnnotations` | `false` | Hide annotations on PDF textless-page and `pages/` renders, including form-field widgets (filled values disappear). Default paints them. Does not affect OCR text or embedded images; also lets an annotated scan be delivered as its embedded image. |
 | `maxOutputBytes` | `20000000` | Child stdout cap in bytes. |
 | `outlineMaxEntries` | `40` | Heading outline, TOC, or sheet inventory entries in the handle. |
 | `ocr` | `false` | Opt-in OCR for scanned pages and images when Tesseract language data is installed. |
@@ -314,7 +315,7 @@ Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `
 
 A bundle is `<outputDir>/<stem>.md` plus `<outputDir>/<stem>.pages.json` on Python PDF tiers, optional OCR sidecars under `<outputDir>/ocr/`, and `<outputDir>/images/` and, for spreadsheets with data, `<outputDir>/sheets/`; without `outputDir`, the tool creates a per-call temp root. A conversion owns `<stem>.md.lock` until it atomically publishes the Markdown. An existing `<stem>.md` fails the call unless `overwrite` is set; `overwrite` replaces that Markdown and the files it owns (`images/<stem>-p<N>-<n>.*`, `images/<stem>-s<idx>[-<n>].*`, `sheets/<stem>-s<idx>-<slug>.csv`, `<stem>.pages.json`, `ocr/<stem>-pNNN.md`), nothing else. Temp bundles are caller-owned - the tool never deletes a bundle it produced.
 
-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.
+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 50 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: 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.
 

package/dist/bin/pi-quiver.js

@@ -582,7 +582,7 @@ function ownedPagePattern(stem) {
   return new RegExp(`^${escRe(stem)}-p\\d+\\.[a-z0-9]+$`);
 }
 function ownedOcrPattern(stem) {
-  return new RegExp(`^${escRe(stem)}-p\\d+\\.md$`);
+  return new RegExp(`^${escRe(stem)}-p\\d+(?:\\.words\\.json|\\.md)$`);
 }
 var FILE_LINK_RE = /\[[^\]]*\]\(\s*((?:sheets|attachments)\/[^)\s]+)\s*\)/g;
 var IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
@@ -649,6 +649,7 @@ function openBundle(root, requested, overwrite) {
         for (const f of readdirSync(attachmentsDir)) if (attachments.has(f)) rmSync(join2(attachmentsDir, f), { force: true });
       }
       rmSync(join2(root, `${stem}.pages.json`), { force: true });
+      rmSync(join2(root, `${stem}.words.json`), { force: true });
       const ownedOcr = ownedOcrPattern(stem);
       if (existsSync(ocrDir)) {
         for (const f of readdirSync(ocrDir)) if (ownedOcr.test(f)) rmSync(join2(ocrDir, f), { force: true });
@@ -661,7 +662,7 @@ function openBundle(root, requested, overwrite) {
     const pagesStagingDir = join2(pagesDir, `.stage-${lockId}`);
     const attachmentsStagingDir = join2(attachmentsDir, `.stage-${lockId}`);
     const ocrStagingDir = join2(ocrDir, `.stage-${lockId}`);
-    return { root, stem, renamedFrom, renameReason, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, pagesDir, pagesStagingDir, attachmentsDir, attachmentsStagingDir, ocrDir, ocrStagingDir, pageStatsPath: join2(root, `${stem}.pages.json`), ocrManifest: /* @__PURE__ */ new Set(), manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), pageManifest: /* @__PURE__ */ new Set(), attachmentManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
+    return { root, stem, renamedFrom, renameReason, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, pagesDir, pagesStagingDir, attachmentsDir, attachmentsStagingDir, ocrDir, ocrStagingDir, pageStatsPath: join2(root, `${stem}.pages.json`), wordsPath: join2(root, `${stem}.words.json`), ocrManifest: /* @__PURE__ */ new Set(), 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;
@@ -679,6 +680,13 @@ function publishStaged(b) {
       continue;
     }
     const page = Number(m[1]);
+    const raw = readFileSync(join2(pageDir, ".done"), "utf8").trim();
+    let meta = {};
+    try {
+      const v = raw ? JSON.parse(raw) : {};
+      if (v && typeof v === "object" && !Array.isArray(v)) meta = v;
+    } catch {
+    }
     const files = readdirSync(pageDir).filter((f) => f !== ".done" && statSync(join2(pageDir, f)).isFile()).sort();
     const names = [];
     files.forEach((f, i) => {
@@ -688,8 +696,9 @@ function publishStaged(b) {
       b.sourceMap.set(`${dir}/${f}`, `images/${name}`);
       names.push(name);
     });
+    if (meta.native) meta.native = { ...meta.native, file: names[files.indexOf(meta.native.file)] ?? meta.native.file };
     rmSync(pageDir, { recursive: true, force: true });
-    out.set(page, names);
+    out.set(page, { files: names, meta });
   }
   return out;
 }
@@ -729,9 +738,20 @@ function writePageStats(b, stats) {
   writeFileSync2(b.pageStatsPath, `${JSON.stringify(stats, null, 2)}
 `, "utf8");
 }
+function publishWords(b) {
+  const staged = join2(b.stagingDir, "words.json");
+  try {
+    if (!existsSync(staged)) throw new Error("child staged no words.json");
+    renameSync(staged, b.wordsPath);
+    return null;
+  } catch (e) {
+    rmSync(b.wordsPath, { force: true });
+    return `write failed - ${e.message}`;
+  }
+}
 function publishSidecars(b) {
-  const out = /* @__PURE__ */ new Map();
-  if (!existsSync(b.ocrStagingDir)) return out;
+  const sidecars = /* @__PURE__ */ new Map(), wordSidecars = /* @__PURE__ */ new Map();
+  if (!existsSync(b.ocrStagingDir)) return { sidecars, wordSidecars };
   for (const dir of readdirSync(b.ocrStagingDir).sort()) {
     const m = dir.match(/^p(\d+)$/);
     if (!m) continue;
@@ -742,10 +762,16 @@ function publishSidecars(b) {
     mkdirSync2(b.ocrDir, { recursive: true });
     renameSync(join2(pageDir, file), join2(b.ocrDir, file));
     b.ocrManifest.add(file);
-    out.set(Number(m[1]), join2(b.ocrDir, file));
+    sidecars.set(Number(m[1]), join2(b.ocrDir, file));
+    const wfile = `${b.stem}-${dir}.words.json`;
+    if (existsSync(join2(pageDir, wfile))) {
+      renameSync(join2(pageDir, wfile), join2(b.ocrDir, wfile));
+      b.ocrManifest.add(wfile);
+      wordSidecars.set(Number(m[1]), join2(b.ocrDir, wfile));
+    }
   }
   rmSync(b.ocrStagingDir, { recursive: true, force: true });
-  return out;
+  return { sidecars, wordSidecars };
 }
 function publishAttachments(b) {
   if (!existsSync(b.attachmentsStagingDir)) return;
@@ -821,6 +847,7 @@ function abortBundle(b) {
   for (const f of b.ocrManifest) rmSync(join2(b.ocrDir, f), { force: true });
   rmSync(b.ocrStagingDir, { recursive: true, force: true });
   rmSync(b.pageStatsPath, { force: true });
+  rmSync(b.wordsPath, { force: true });
   rmSync(`${b.mdPath}.tmp`, { force: true });
   rmSync(b.stagingDir, { recursive: true, force: true });
   rmSync(b.sheetsStagingDir, { recursive: true, force: true });
@@ -950,6 +977,11 @@ function formatHandle(h) {
   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}`);
   if (h.pageStatsPath) lines.push(`Page-Stats: ${h.pageStatsPath}`);
+  if (h.nativeImages.length) lines.push(`Native-Images: ${h.nativeImages.length === 1 ? "page" : "pages"} ${compactRanges(h.nativeImages.map((n) => n.page))} (embedded image streams, no render DPI)`);
+  if (h.wordsPath) {
+    const bad = Object.keys(h.wordsErrors).map(Number).sort((a, b) => a - b);
+    lines.push(`Words: ${h.wordsPath}${bad.length ? ` (extraction failed for pages ${compactRanges(bad)}: ${h.wordsErrors[bad[0]]})` : ""}`);
+  } else if (h.wordsReason) lines.push(`Words: ${h.wordsReason}`);
   if (h.ocrDir) lines.push(`OCR-Dir: ${h.ocrDir}`);
   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`);
@@ -1000,6 +1032,7 @@ var DOC_TO_MD_OPTIONS = [
   { 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: "words", flag: "--words", type: "bool", default: false, settable: false, help: 'Write word positions: <stem>.words.json beside the Markdown lists every text-layer word of each selected page with its bbox (PDF points, top-left origin, display orientation; image inputs in source pixels) and the words inline OCR recognized, tagged source "text" or "ocr"; under --ocr-mode all the OCR words go to ocr/<stem>-pNNN.words.json beside each sidecar. Never triggers OCR. PDF and image inputs only.' },
   { key: "ocrMode", flag: "--ocr-mode", type: "enum", default: "textless", settable: false, enumValues: ["textless", "all"], help: "OCR policy: textless (default) OCRs only pages with an empty text layer, inline; all OCRs every selected page and writes the recognized text to ocr/<stem>-pNNN.md sidecars, leaving the Markdown untouched. all requires --ocr and an explicit --pages selection (PDF, PPTX, DOC)." },
   { 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" },
@@ -1012,7 +1045,8 @@ var DOC_TO_MD_OPTIONS = [
   { key: "maxOutputBytes", flag: "--max-output-bytes", type: "int", default: 2e7, settable: true, help: "Child stdout cap in bytes" },
   { key: "outlineMaxEntries", flag: "--outline-max-entries", type: "int", default: 40, settable: true, help: "Heading outline / TOC / sheet inventory cap in the handle" },
   { key: "ocr", flag: "--ocr", type: "bool", default: false, settable: true, help: "Run OCR on pages without a text layer and on image inputs when Tesseract language data is installed; off by default (--no-ocr turns a settings-level true off)" },
-  { key: "ocrLanguage", flag: "--ocr-language", type: "lang", default: "eng", settable: true, help: "Tesseract language code(s), +-joined, e.g. deu+eng" }
+  { key: "ocrLanguage", flag: "--ocr-language", type: "lang", default: "eng", settable: true, help: "Tesseract language code(s), +-joined, e.g. deu+eng" },
+  { key: "hideAnnotations", flag: "--hide-annotations", type: "bool", default: false, settable: true, help: "Render PDF pages without annotations (sticky notes, highlights, stamps - and form-field widgets, so filled form values disappear); default paints them, as PyMuPDF does. Applies to pages/ renders and textless-page renders, not to OCR text or embedded images; also lets an annotated scan be delivered as its embedded image." }
 ];
 var TUNABLE_DEFAULTS = Object.fromEntries(
   DOC_TO_MD_OPTIONS.filter((d) => d.settable).map((d) => [d.key, d.default])
@@ -1107,8 +1141,8 @@ function resolveOptions(perCall, settings, env) {
     out[d.key] = value;
   }
   const o = out;
-  if (o.info && (o.pages !== null || o.outputDir !== null || o.overwrite || o.pageImages || o.ocrMode === "all")) {
-    throw new UsageError("--info cannot be combined with --pages, --output-dir, --overwrite, --page-images or --ocr-mode all");
+  if (o.info && (o.pages !== null || o.outputDir !== null || o.overwrite || o.pageImages || o.words || o.ocrMode === "all")) {
+    throw new UsageError("--info cannot be combined with --pages, --output-dir, --overwrite, --page-images, --words or --ocr-mode all");
   }
   return o;
 }
@@ -1129,6 +1163,18 @@ var USAGE_PATTERNS = [
   "  Details: doc/doc-to-md.md (bundle contract, failure buckets)."
 ].join("\n");
 var usagePatterns = (cmd) => USAGE_PATTERNS.replaceAll("<cmd>", cmd);
+var BUNDLE_LAYOUT = [
+  { artifact: "<stem>.md", trigger: "always", content: "the Markdown", namedBy: "Saved-To: / savedTo" },
+  { artifact: "images/", trigger: "embedded or extracted figures", content: "image files linked from the Markdown", namedBy: "Images-Dir: / imagesDir" },
+  { artifact: "pages/<stem>-pNNN.<fmt>", trigger: "--page-images", content: "page renders at --image-dpi", namedBy: "Pages-Dir: / pagesDir" },
+  { artifact: "sheets/", trigger: "Excel input", content: "one CSV per non-empty worksheet", namedBy: "Sheets-Dir: / sheetsDir" },
+  { artifact: "attachments/", trigger: "email input", content: "saved attachments", namedBy: "Markdown attachment list" },
+  { artifact: "<stem>.pages.json", trigger: "Python PDF tiers (PDF, PPTX, DOC, DOCX via LibreOffice; not unpdf)", content: "per-page chars, image count, image coverage", namedBy: "Page-Stats: / pageStatsPath" },
+  { artifact: "<stem>.words.json", trigger: "--words", content: "per-page word boxes, source text/ocr", namedBy: "Words: / wordsPath" },
+  { artifact: "ocr/<stem>-pNNN.md", trigger: "--ocr --ocr-mode all", content: "recognized text of a forced page", namedBy: "OCR-Dir: / ocr.sidecars" },
+  { artifact: "ocr/<stem>-pNNN.words.json", trigger: "--ocr --ocr-mode all --words", content: "word boxes of that OCR", namedBy: "ocr.wordSidecars" }
+];
+var bundleLayoutText = () => BUNDLE_LAYOUT.map((r) => `  ${r.artifact.padEnd(28)} ${r.trigger}; ${r.content}; named by ${r.namedBy}`).join("\n");
 function renderHelp() {
   const row = (d) => `  ${(d.flag ?? "<path>").padEnd(26)} ${d.help}${d.default !== null && d.key !== "info" && d.key !== "overwrite" ? ` (default ${d.default})` : ""}`;
   return [
@@ -1143,6 +1189,9 @@ function renderHelp() {
     "Result: a handle (Saved-To, Images-Dir, Page-Stats, Page-Count, Outline ...). Read the Saved-To file for the Markdown.",
     "Exit codes: 0 success, 1 runtime error, 2 usage error.",
     "",
+    "Bundle layout:",
+    bundleLayoutText(),
+    "",
     usagePatterns("pi-quiver doc-to-md")
   ].join("\n");
 }
@@ -1622,7 +1671,7 @@ function reconcileRenderMarkers(md, renderPages, fmt, sourceMap, reason) {
   if (/<!--rvs?:\d+-->/.test(md)) throw new Error("internal: unresolved render marker");
   return md;
 }
-var emptyOcr = (lang) => ({ status: "off", lang, textless: [], pages: [], noText: [], ocrFailed: [], budgetStopped: [], reason: null, tesseract: null, mode: "textless", sidecars: {}, ocrErrors: {}, killed: null, notAttempted: [], childError: null });
+var emptyOcr = (lang) => ({ status: "off", lang, textless: [], pages: [], noText: [], ocrFailed: [], budgetStopped: [], reason: null, tesseract: null, mode: "textless", sidecars: {}, wordSidecars: {}, ocrErrors: {}, killed: null, notAttempted: [], childError: null });
 var emptyOutcome = () => ({ written: [], noText: [], ocrFailed: [], ocrErrors: {}, budgetStopped: [], killed: null, notAttempted: [], childError: null });
 var ocrPagesTag = (n) => `p${String(n).padStart(3, "0")}`;
 var SIDE_MARKER_RE = /^--- end of page\.page_number=\d+ ---$/;
@@ -1667,6 +1716,22 @@ function handleOcr(tier, type, o, json) {
   if (!x || type !== "image" && !x.textless.length && !x.pages.length && !x.ocrFailed.length) return null;
   return { ...emptyOcr(o.ocrLanguage), ...x };
 }
+var nativeFromChild = (b, json, notes) => (json.nativeImages ?? []).flatMap((e) => {
+  const file = b.sourceMap.get(`p${e.page}/${e.file}`);
+  if (!file) {
+    notes.push(`Native image p${e.page}/${e.file} not published`);
+    return [];
+  }
+  return [{ ...e, file: join3(b.root, file) }];
+});
+function retainedNative(b, kept, notes) {
+  const out = [];
+  for (const [page, k] of kept) {
+    if (k.meta.native) out.push({ page, ...k.meta.native, file: join3(b.imagesDir, k.meta.native.file) });
+    if (k.meta.dpi !== void 0 && k.meta.requestedDpi !== void 0 && k.meta.dpi < k.meta.requestedDpi) notes.push(`Page ${page} rendered at ${k.meta.dpi} dpi (requested ${k.meta.requestedDpi}; 50 Mpx ceiling)`);
+  }
+  return out;
+}
 async function convertDocument(o, signal, seams) {
   const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, office: tryConvertOffice, ...seams };
   const inputPath = resolve2(o.path);
@@ -1693,11 +1758,13 @@ async function convertDocument(o, signal, seams) {
   let office = null;
   try {
     let pdfPath = inputPath;
-    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 && !forced, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs };
+    const base = { path: inputPath, pages: o.pages, ...o.words && (type === "pdf" || type === "image") ? { words: true } : {}, 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 && !forced, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs, hideAnnotations: o.hideAnnotations };
     let tier, engine, json, degraded = null, fallbackReason = null;
     let explicitBreaks = null;
     let notes = [];
+    let nativeImages = [];
     let officeRoute = null;
+    let copyReason = null;
     if (type === "html") {
       const prepared = await prepareHtml(inputPath, b.stagingDir);
       if (signal?.aborted) throw new Error("aborted");
@@ -1737,6 +1804,7 @@ async function convertDocument(o, signal, seams) {
       }
       if (signal?.aborted) throw new Error("aborted");
       if (json === void 0) {
+        copyReason = reason;
         clearStaging(b);
         const file = `original${extname3(inputPath).toLowerCase()}`;
         const dir = join3(b.stagingDir, "p1");
@@ -1849,11 +1917,12 @@ async function convertDocument(o, signal, seams) {
           tier = "primary";
           engine = "pymupdf4llm";
           json = p.json;
+          nativeImages = nativeFromChild(b, json, notes);
           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]));
+          const keepPages = Object.fromEntries([...kept.entries()].map(([k, v]) => [String(k), v.files]));
           rmSync2(b.pagesStagingDir, { recursive: true, force: true });
           const f = await s.runTier("pdf-fallback", { ...pdfBase, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
           publishStaged(b);
@@ -1864,6 +1933,7 @@ async function convertDocument(o, signal, seams) {
           json = f.json;
           degraded = DEGRADED_TEXT;
           fallbackReason = `primary ${p.reason}`;
+          nativeImages = [...retainedNative(b, kept, notes), ...nativeFromChild(b, json, notes)].sort((x, y) => x.page - y.page);
         }
       }
     }
@@ -1872,14 +1942,33 @@ async function convertDocument(o, signal, seams) {
     if (tier === void 0 || engine === void 0 || json === void 0) throw new Error("internal: no tier produced output");
     const pageStats = json.pageStats ?? null;
     if (pageStats) writePageStats(b, pageStats);
+    let wordsPath = null, wordsReason = null;
+    const wordsErrors = {};
+    const takeWordsErrors = (j) => {
+      for (const [k, v] of Object.entries(j?.wordsErrors ?? {})) {
+        const page = Number(k);
+        if (Number.isFinite(page)) wordsErrors[page] = v;
+      }
+    };
+    if (o.words) {
+      if (type !== "pdf" && type !== "image") wordsReason = `none - word positions apply to PDF and image inputs only (${type})`;
+      else if (tier === "unpdf") wordsReason = "none - unpdf tier has no page geometry";
+      else if (engine === "copy") wordsReason = `none - image copied without conversion (${copyReason})`;
+      else if (json?.words === true) {
+        wordsReason = publishWords(b);
+        if (wordsReason === null) wordsPath = b.wordsPath;
+      } else wordsReason = `write failed - ${json?.wordsErrors?.file ?? "child reported no words document"}`;
+      takeWordsErrors(json);
+    }
     let ocr = handleOcr(tier, type, o, json);
     if (forced) {
-      const r = await s.runTier("ocr-pages", { path: pdfPath, pages: o.pages, stem: b.stem, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs, stagingDir: b.ocrStagingDir, dpi: o.imageDpi, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.primaryTimeoutMs, backend);
+      const r = await s.runTier("ocr-pages", { path: pdfPath, pages: o.pages, ...o.words && type === "pdf" ? { words: true } : {}, stem: b.stem, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs, stagingDir: b.ocrStagingDir, dpi: o.imageDpi, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.primaryTimeoutMs, backend);
       if (signal?.aborted || !r.ok && "reason" in r && r.reason === "aborted") throw new Error("aborted");
       if (r.ok && r.json.status === "unavailable") throw new Error(`OCR unavailable: ${r.json.reason} (install Tesseract; see doc/doc-to-md.md)`);
       const outcome = r.ok && r.json.status === "ran" ? outcomeFromChild(r.json) : recoverOcrPages(b.ocrStagingDir, o.pages, !r.ok ? "userError" in r ? r.userError : `${r.reason}${detailSuffix(r)}` : "malformed child output");
-      const sidecars = publishSidecars(b);
-      ocr = { ...emptyOcr(o.ocrLanguage), ...json.ocr, status: "ran", reason: null, mode: "all", pages: outcome.written, noText: outcome.noText, ocrFailed: outcome.ocrFailed, ocrErrors: outcome.ocrErrors, budgetStopped: outcome.budgetStopped, killed: outcome.killed, notAttempted: outcome.notAttempted, childError: outcome.childError, sidecars: Object.fromEntries(sidecars) };
+      const { sidecars, wordSidecars } = publishSidecars(b);
+      ocr = { ...emptyOcr(o.ocrLanguage), ...json.ocr, status: "ran", reason: null, mode: "all", pages: outcome.written, noText: outcome.noText, ocrFailed: outcome.ocrFailed, ocrErrors: outcome.ocrErrors, budgetStopped: outcome.budgetStopped, killed: outcome.killed, notAttempted: outcome.notAttempted, childError: outcome.childError, sidecars: Object.fromEntries(sidecars), wordSidecars: Object.fromEntries(wordSidecars) };
+      if (o.words && r.ok) takeWordsErrors(r.json);
     }
     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})`);
@@ -1897,7 +1986,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, 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, pageStats, pageStatsPath: pageStats ? b.pageStatsPath : null, ocrDir: b.ocrManifest.size ? b.ocrDir : null };
+    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, pageStats, pageStatsPath: pageStats ? b.pageStatsPath : null, ocrDir: b.ocrManifest.size ? b.ocrDir : null, nativeImages, wordsPath, wordsReason, wordsErrors };
     return { output: formatHandle(details), details };
   } catch (e) {
     abortBundle(b);
@@ -1943,7 +2032,7 @@ 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 [--json] [--info] [--page-images] [--pages <spec>] [--output-dir <dir>] [--overwrite] [--ocr] [--ocr-mode textless|all] [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] [--words] [--pages <spec>] [--output-dir <dir>] [--overwrite] [--ocr] [--ocr-mode textless|all] [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");

package/lib/doc-to-md-bundle.ts

@@ -15,7 +15,7 @@ export interface Bundle {
 	sheetsDir: string; sheetsStagingDir: string;
 	pagesDir: string; pagesStagingDir: string;
 	attachmentsDir: string; attachmentsStagingDir: string;
-	ocrDir: string; ocrStagingDir: string; pageStatsPath: string;
+	ocrDir: string; ocrStagingDir: string; pageStatsPath: string; wordsPath: string;
 	manifest: Set<string>;
 	csvManifest: Set<string>;
 	pageManifest: Set<string>;
@@ -36,7 +36,7 @@ export function ownedCsvPattern(stem: string): RegExp {
 
 export function ownedPagePattern(stem: string): RegExp { return new RegExp(`^${escRe(stem)}-p\\d+\\.[a-z0-9]+$`); }
 
-export function ownedOcrPattern(stem: string): RegExp { return new RegExp(`^${escRe(stem)}-p\\d+\\.md$`); }
+export function ownedOcrPattern(stem: string): RegExp { return new RegExp(`^${escRe(stem)}-p\\d+(?:\\.words\\.json|\\.md)$`); }
 
 const FILE_LINK_RE = /\[[^\]]*\]\(\s*((?:sheets|attachments)\/[^)\s]+)\s*\)/g;
 const IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
@@ -94,6 +94,7 @@ export function openBundle(root: string, requested: string, overwrite: boolean):
 			if (existsSync(pagesDir)) for (const f of readdirSync(pagesDir)) if (ownedPage.test(f)) rmSync(join(pagesDir, f), { force: true });
 			if (existsSync(attachmentsDir)) for (const f of readdirSync(attachmentsDir)) if (attachments.has(f)) rmSync(join(attachmentsDir, f), { force: true });
 			rmSync(join(root, `${stem}.pages.json`), { force: true });
+			rmSync(join(root, `${stem}.words.json`), { force: true });
 			const ownedOcr = ownedOcrPattern(stem);
 			if (existsSync(ocrDir)) for (const f of readdirSync(ocrDir)) if (ownedOcr.test(f)) rmSync(join(ocrDir, f), { force: true });
 		}
@@ -104,13 +105,16 @@ export function openBundle(root: string, requested: string, overwrite: boolean):
 		const pagesStagingDir = join(pagesDir, `.stage-${lockId}`);
 		const attachmentsStagingDir = join(attachmentsDir, `.stage-${lockId}`);
 		const ocrStagingDir = join(ocrDir, `.stage-${lockId}`);
-		return { root, stem, renamedFrom, renameReason, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, pagesDir, pagesStagingDir, attachmentsDir, attachmentsStagingDir, ocrDir, ocrStagingDir, pageStatsPath: join(root, `${stem}.pages.json`), ocrManifest: new Set(), manifest: new Set(), csvManifest: new Set(), pageManifest: new Set(), attachmentManifest: new Set(), sourceMap: new Map() };
+		return { root, stem, renamedFrom, renameReason, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, pagesDir, pagesStagingDir, attachmentsDir, attachmentsStagingDir, ocrDir, ocrStagingDir, pageStatsPath: join(root, `${stem}.pages.json`), wordsPath: join(root, `${stem}.words.json`), ocrManifest: new Set(), manifest: new Set(), csvManifest: new Set(), pageManifest: new Set(), attachmentManifest: new Set(), sourceMap: new Map() };
 	} catch (e) { rmSync(lockPath, { force: true }); throw e; }
 }
 
-/** Publish every `p<N>/` staging dir carrying `.done`; discard partial ones. Returns page -> published filenames. */
-export function publishStaged(b: Bundle): Map<number, string[]> {
-	const out = new Map<number, string[]>();
+export interface DoneMeta { native?: { file: string; width: number; height: number }; dpi?: number; requestedDpi?: number }
+export interface StagedPage { files: string[]; meta: DoneMeta }
+
+/** Publish completed pages, retaining metadata with native filenames renamed; discard partial pages. */
+export function publishStaged(b: Bundle): Map<number, StagedPage> {
+	const out = new Map<number, StagedPage>();
 	if (!existsSync(b.stagingDir)) return out;
 	for (const dir of readdirSync(b.stagingDir).sort()) {
 		const m = dir.match(/^p(\d+)$/);
@@ -118,6 +122,12 @@ export function publishStaged(b: Bundle): Map<number, string[]> {
 		const pageDir = join(b.stagingDir, dir);
 		if (!existsSync(join(pageDir, ".done"))) { rmSync(pageDir, { recursive: true, force: true }); continue; }
 		const page = Number(m[1]);
+		const raw = readFileSync(join(pageDir, ".done"), "utf8").trim();
+		let meta: DoneMeta = {};
+		try {
+			const v = raw ? JSON.parse(raw) : {};
+			if (v && typeof v === "object" && !Array.isArray(v)) meta = v;
+		} catch { /* Completed images survive truncated metadata. */ }
 		const files = readdirSync(pageDir).filter((f) => f !== ".done" && statSync(join(pageDir, f)).isFile()).sort();
 		const names: string[] = [];
 		files.forEach((f, i) => {
@@ -127,8 +137,9 @@ export function publishStaged(b: Bundle): Map<number, string[]> {
 			b.sourceMap.set(`${dir}/${f}`, `images/${name}`);
 			names.push(name);
 		});
+		if (meta.native) meta.native = { ...meta.native, file: names[files.indexOf(meta.native.file)] ?? meta.native.file };
 		rmSync(pageDir, { recursive: true, force: true });
-		out.set(page, names);
+		out.set(page, { files: names, meta });
 	}
 	return out;
 }
@@ -174,10 +185,23 @@ export function writePageStats(b: Bundle, stats: PageStat[]): void {
 	writeFileSync(b.pageStatsPath, `${JSON.stringify(stats, null, 2)}\n`, "utf8");
 }
 
-/** Move every `.done`-gated `pNNN/<stem>-pNNN.md` into `ocr/`; partial page dirs and the checkpoint are dropped with the staging dir. Returns page -> absolute sidecar path. */
-export function publishSidecars(b: Bundle): Map<number, string> {
-	const out = new Map<number, string>();
-	if (!existsSync(b.ocrStagingDir)) return out;
+/** Rename within the bundle root keeps the complete words document atomic. */
+export function publishWords(b: Bundle): string | null {
+	const staged = join(b.stagingDir, "words.json");
+	try {
+		if (!existsSync(staged)) throw new Error("child staged no words.json");
+		renameSync(staged, b.wordsPath);
+		return null;
+	} catch (e) {
+		rmSync(b.wordsPath, { force: true });
+		return `write failed - ${(e as Error).message}`;
+	}
+}
+
+/** Move `.done`-gated Markdown and words sidecars into `ocr/`; drop partial dirs and the checkpoint. Returns page -> absolute paths for each kind. */
+export function publishSidecars(b: Bundle): { sidecars: Map<number, string>; wordSidecars: Map<number, string> } {
+	const sidecars = new Map<number, string>(), wordSidecars = new Map<number, string>();
+	if (!existsSync(b.ocrStagingDir)) return { sidecars, wordSidecars };
 	for (const dir of readdirSync(b.ocrStagingDir).sort()) {
 		const m = dir.match(/^p(\d+)$/);
 		if (!m) continue;
@@ -188,10 +212,16 @@ export function publishSidecars(b: Bundle): Map<number, string> {
 		mkdirSync(b.ocrDir, { recursive: true });
 		renameSync(join(pageDir, file), join(b.ocrDir, file));
 		b.ocrManifest.add(file);
-		out.set(Number(m[1]), join(b.ocrDir, file));
+		sidecars.set(Number(m[1]), join(b.ocrDir, file));
+		const wfile = `${b.stem}-${dir}.words.json`;
+		if (existsSync(join(pageDir, wfile))) {
+			renameSync(join(pageDir, wfile), join(b.ocrDir, wfile));
+			b.ocrManifest.add(wfile);
+			wordSidecars.set(Number(m[1]), join(b.ocrDir, wfile));
+		}
 	}
 	rmSync(b.ocrStagingDir, { recursive: true, force: true });
-	return out;
+	return { sidecars, wordSidecars };
 }
 
 export function publishAttachments(b: Bundle): void {
@@ -254,6 +284,7 @@ export function abortBundle(b: Bundle): void {
 	for (const f of b.ocrManifest) rmSync(join(b.ocrDir, f), { force: true });
 	rmSync(b.ocrStagingDir, { recursive: true, force: true });
 	rmSync(b.pageStatsPath, { force: true });
+	rmSync(b.wordsPath, { force: true });
 	rmSync(`${b.mdPath}.tmp`, { force: true });
 	rmSync(b.stagingDir, { recursive: true, force: true });
 	rmSync(b.sheetsStagingDir, { recursive: true, force: true });