pi-quiver 5.4.0 → 6.0.0

package/CHANGELOG.md

@@ -8,6 +8,18 @@ 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.0.0 - 2026-09-10
+
+- doc_to_md (Excel, breaking): `maxCellsPerSheet` is removed from the tool schema, CLI (`--max-cells-per-sheet`), and `quiver.docToMd` settings; a leftover key is reported by the settings lint. Sheet indices are now 0-based workbook positions covering worksheets and chartsheets, so embedded-image files move from `<stem>-s1-<n>.*` to `<stem>-s0-<n>.*` and `SheetInfo.index` is rebased.
+- doc_to_md (Excel): the Markdown opens with a `## Sheets` inventory (kind, size, hidden, chart/image counts, rendered view, CSV link); every non-empty worksheet's full content is exported to `sheets/<stem>-s<idx>-<slug>.csv`; the in-Markdown preview is capped at 100 rows x 50 columns and, when truncated, followed by a per-column profile (type, non-empty, min/max, distinct). Chartsheets and embedded charts are listed with type, title, and series refs.
+- doc_to_md (Excel): sheets carrying charts or images get a rendered view (`images/<stem>-s<idx>.<fmt>`) when LibreOffice is on `PATH` - one PDF page per sheet via `calc_pdf_Export` `SinglePageSheets`, rasterized by a new PyMuPDF `render-pages` child under a 16 Mpx budget. Any soffice or render failure degrades to `Rendered view: unavailable (<reason>)` plus a handle note; the conversion never fails. `.xls` keeps inventory/CSV/preview but has no visual detection.
+- doc_to_md: handle prints `Sheets-Dir` when CSVs were written; `info` lists chartsheets with kind and chart/image counts. Bundle overwrite now removes only this stem's owned-pattern files in `images/` and `sheets/`.
+
+## v5.5.0 - 2026-09-10
+
+- doc_to_md: rewrite primary-PDF image links correctly on Windows.
+- slack: optionally resolve the user token through a credential command on every user-identity tool call, with a configurable timeout in seconds, allowing running pi sessions to use replaced credentials without leaking secrets on command failure or falling back to stale env tokens.
+
 ## v5.4.0 - 2026-09-10
 
 - Settings: one condensed `pi-quiver settings` warning (each distinct message

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 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 -> per-worksheet matrices with formulas/cached values/merged/hidden. 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; 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/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. |
@@ -93,7 +93,7 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 ## When NOT to use
 
 - You need a general-purpose web scraper (JS-rendered pages, pagination, auth flows) - `fetch` does plain HTTP + Readability extraction, nothing more.
-- You need `.xlsm`, sheet/range selection or chart rendering - out of scope.
+- You need in-grid chart/image placement, `.xls` visual detection, `.xlsm`, or range selection - out of scope; chart/image association is per sheet only.
 - You want automatic session naming, a custom header, fast mode, or stall recovery without opting in - all stay off until you flip the config.
 - You need *mid-stream* stall recovery in JSON, RPC, or print runs - only the pre-first-event tier arms there; mid-stream silence falls through to pi's transport timeout.
 
@@ -274,11 +274,13 @@ Operational notes:
 | --- | --- | --- |
 | `enabled` | `false` | Master switch, checked at `session_start`; toggling takes effect next session. |
 | `cachePath` | user-scope per-OS cache dir | Overrides where the workspace-keyed channel/user name->ID cache file is written; relative paths resolve against the repo root. |
-| `userTokenEnv` | `SLACK_USER_TOKEN` | Env var name holding the user token (required for `slack_search`/`slack_thread`, no bot fallback). |
+| `userTokenEnv` | `SLACK_USER_TOKEN` | Env var name holding the user token when `userTokenCommand` is unset (required for `slack_search`/`slack_thread`, no bot fallback). |
+| `userTokenCommand` | unset | Executable argv array that prints the current user token to stdout; resolved on every user-identity tool call. |
+| `userTokenCommandTimeoutSeconds` | `10` | Positive finite timeout in seconds for `userTokenCommand`. Increase this when an interactive credential helper may need authorization. |
 | `botTokenEnv` | `SLACK_BOT_TOKEN` | Env var name holding the bot token. |
 | `uploadThresholdChars` | `4000` | Link-collapsed length above which an announce/thread detail body is delivered as a file upload instead of inline text. |
 
-Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. Tokens themselves are resolved per call: process env first, then the repo's `.env` file (or the primary checkout's, for a worktree with none) - never a fallback across identities. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
+Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `PI_QUIVER_SLACK_CACHE_PATH`, `PI_QUIVER_SLACK_USER_TOKEN_ENV`, `PI_QUIVER_SLACK_BOT_TOKEN_ENV`, and `PI_QUIVER_SLACK_UPLOAD_THRESHOLD_CHARS` - applied on top of the resolved `settings.json` layers, same override rung the extension's config resolver defines. `userTokenCommand` and `userTokenCommandTimeoutSeconds` are settings-only: pi executes the argv directly, without a shell, on every user-identity Slack tool call. For example, macOS Keychain can supply the token with `"userTokenCommand": ["security", "find-generic-password", "-s", "slack-user-token", "-w"]`. Its stdout is the token; empty output, nonzero exit, or timeout is a sanitized hard error and never falls back to `userTokenEnv`. Without the command, tokens resolve per call from process env and then `.env` (or the primary checkout's, for a worktree with none). Bot resolution is unchanged. Restart pi after changing Slack settings because the extension captures them at session start. Full reference incl. cache layering, the announce protocol, and the `search.messages`/`conversations.replies` throttle caveats: [doc/slack.md](doc/slack.md).
 
 ### doc_to_md settings
 
@@ -287,22 +289,21 @@ 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 and PDF info deadline. |
-| `sofficeTimeoutMs` | `120000` | DOCX/PPTX -> PDF 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. |
 | `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. |
+| `imageDpi` | `150` | Render DPI for page images and Excel rendered views (capped by a 16 Mpx budget). |
 | `imageFormat` | `png` | Rendered image format: `png` or `jpg`; embedded images retain their extension. |
-| `maxCellsPerSheet` | `50000` | Rows x columns budget per worksheet. |
 | `maxOutputBytes` | `20000000` | Child stdout cap in bytes. |
 | `outlineMaxEntries` | `40` | Heading outline, TOC, or sheet inventory entries in the handle. |
 
-A bundle is `<outputDir>/<stem>.md` plus `<outputDir>/images/`; 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 images it owns (`<stem>-p<N>-<n>.*` / `<stem>-s<idx>-<n>.*`), nothing else. Temp bundles are caller-owned - the tool never deletes a bundle it produced.
+A bundle is `<outputDir>/<stem>.md` plus `<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`), 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`.
+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 + KILL_GRACE_MS`). There is no cap on image count, image bytes or workbook memory - deliberately; the per-tier timeouts and `maxOutputBytes` are the bounds.
+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.
 
 ### Migrating from flat keys
 

package/dist/bin/pi-quiver.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // bin/pi-quiver.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { existsSync as existsSync3, readFileSync, realpathSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join4, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
@@ -524,30 +524,24 @@ import { basename, dirname, extname as extname3, join as join3, resolve as resol
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // lib/doc-to-md-bundle.ts
-import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { extname, join as join2, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
+var escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 function ownedPattern(stem) {
-  const esc = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(`^${esc}-(p|s)\\d+-\\d+\\.[a-z0-9]+$`);
+  return new RegExp(`^${escRe(stem)}-(p|s)\\d+(-\\d+)?\\.[a-z0-9]+$`);
 }
+function ownedCsvPattern(stem) {
+  return new RegExp(`^${escRe(stem)}-s\\d+-[a-z0-9-]+\\.csv$`);
+}
+var SHEET_LINK_RE = /\[[^\]]*\]\(\s*(sheets\/[^)\s]+)\s*\)/g;
 var IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
 function imageTarget(m) {
   const target = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "").trim();
   const destination = target.replace(/^<([\s\S]*)>$/, "$1").trim();
   return m[2] === void 0 ? destination : destination.replace(/\s+(?:"[^"]*"|'[^']*'|\([^)]*\))$/, "");
 }
-function linkedFiles(md) {
-  const out = [];
-  for (const m of md.matchAll(IMG_LINK_RE)) {
-    const target = imageTarget(m);
-    if (!target.startsWith("images/")) continue;
-    const file = target.slice("images/".length);
-    if (file && file !== "." && file !== ".." && /^[^/\\]+$/.test(file)) out.push(file);
-  }
-  return out;
-}
 function openBundle(root, stem, overwrite) {
   mkdirSync2(root, { recursive: true });
   const mdPath = join2(root, `${stem}.md`);
@@ -561,20 +555,24 @@ function openBundle(root, stem, overwrite) {
   }
   closeSync(fd);
   const imagesDir = join2(root, "images");
+  const sheetsDir = join2(root, "sheets");
   try {
     if (existsSync(mdPath)) {
       if (!overwrite) throw new Error(`Output exists: ${mdPath} (pass overwrite)`);
-      const owned = ownedPattern(stem);
-      const linked = new Set(linkedFiles(readFileSync(mdPath, "utf8")));
+      const owned = ownedPattern(stem), ownedCsv = ownedCsvPattern(stem);
       unlinkSync(mdPath);
       if (existsSync(imagesDir)) {
-        for (const f of readdirSync(imagesDir)) if (owned.test(f) || linked.has(f)) rmSync(join2(imagesDir, f), { force: true });
+        for (const f of readdirSync(imagesDir)) if (owned.test(f)) rmSync(join2(imagesDir, f), { force: true });
+      }
+      if (existsSync(sheetsDir)) {
+        for (const f of readdirSync(sheetsDir)) if (ownedCsv.test(f)) rmSync(join2(sheetsDir, f), { force: true });
       }
     }
     const lockId = randomBytes(6).toString("hex");
     const stagingDir = join2(imagesDir, `.stage-${lockId}`);
+    const sheetsStagingDir = join2(sheetsDir, `.stage-${lockId}`);
     mkdirSync2(stagingDir, { recursive: true });
-    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, manifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
+    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
   } catch (e) {
     rmSync(lockPath, { force: true });
     throw e;
@@ -608,25 +606,42 @@ function publishStaged(b) {
 }
 function publishSheetImages(b) {
   for (const f of readdirSync(b.stagingDir).sort()) {
-    if (!/^s\d+-\d+\.[a-z0-9]+$/i.test(f)) continue;
+    if (!/^s\d+(-\d+)?\.[a-z0-9]+$/i.test(f)) continue;
     const name = `${b.stem}-${f.toLowerCase()}`;
     renameSync(join2(b.stagingDir, f), join2(b.imagesDir, name));
     b.manifest.add(name);
     b.sourceMap.set(f, `images/${name}`);
   }
 }
-function rewriteImageLinks(md, sourceMap) {
-  return md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
+function publishSheetCsvs(b) {
+  if (!existsSync(b.sheetsStagingDir)) return;
+  for (const f of readdirSync(b.sheetsStagingDir).sort()) {
+    if (!/^s\d+-[a-z0-9-]+\.csv$/.test(f)) continue;
+    const name = `${b.stem}-${f}`;
+    renameSync(join2(b.sheetsStagingDir, f), join2(b.sheetsDir, name));
+    b.csvManifest.add(name);
+    b.sourceMap.set(`sheets/${f}`, `sheets/${name}`);
+  }
+}
+function rewriteLinks(md, sourceMap) {
+  const images = md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
     const target = imageTarget([whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted]);
     const dest = sourceMap.get(target) ?? sourceMap.get(target.replace(/^\.\//, ""));
     return dest ? whole.replace(mdAngle === void 0 ? target : `<${mdAngle}>`, dest) : whole;
   });
+  return images.replace(SHEET_LINK_RE, (whole, target) => {
+    const dest = sourceMap.get(target);
+    return dest ? whole.split(target).join(dest) : whole;
+  });
 }
-function validateImageLinks(md, manifest) {
+function validateImageLinks(md, manifest, csvManifest = /* @__PURE__ */ new Set()) {
   for (const m of md.matchAll(IMG_LINK_RE)) {
     const target = imageTarget(m);
     if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
   }
+  for (const m of md.matchAll(SHEET_LINK_RE)) {
+    if (!csvManifest.has(m[1].slice("sheets/".length))) throw new Error(`unexpected sheet reference in output: ${m[1]}`);
+  }
 }
 function commitBundle(b, markdown) {
   const tmp = `${b.mdPath}.tmp`;
@@ -636,6 +651,10 @@ function commitBundle(b, markdown) {
     fs.rmSync(b.stagingDir, { recursive: true, force: true });
   } catch {
   }
+  try {
+    fs.rmSync(b.sheetsStagingDir, { recursive: true, force: true });
+  } catch {
+  }
   try {
     fs.rmSync(b.lockPath, { force: true });
   } catch {
@@ -643,8 +662,10 @@ function commitBundle(b, markdown) {
 }
 function abortBundle(b) {
   for (const f of b.manifest) rmSync(join2(b.imagesDir, f), { force: true });
+  for (const f of b.csvManifest) rmSync(join2(b.sheetsDir, f), { force: true });
   rmSync(`${b.mdPath}.tmp`, { force: true });
   rmSync(b.stagingDir, { recursive: true, force: true });
+  rmSync(b.sheetsStagingDir, { recursive: true, force: true });
   rmSync(b.lockPath, { force: true });
 }
 function tempBundleRoot() {
@@ -703,6 +724,7 @@ function outlineLines(entries, total) {
 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`);
   if (h.degraded) lines.push(`Degraded: ${h.degraded}`);
@@ -719,7 +741,7 @@ function formatInfoHandle(i, max) {
   if (i.sheets) {
     const lines2 = [`Type: ${i.type}   Sheets: ${i.sheetsTotal}`];
     for (const s of i.sheets.slice(0, max)) {
-      const dims = `rows=${s.rows ?? "?"} cols=${s.cols ?? "?"}`;
+      const dims = `${s.kind} rows=${s.rows ?? "-"} cols=${s.cols ?? "-"} charts=${s.charts} images=${s.images}`;
       const hidden = s.hiddenRows || s.hiddenCols ? ` hiddenRows=${s.hiddenRows} hiddenCols=${s.hiddenCols}` : "";
       lines2.push(`  ${trunc(s.name, TITLE_MAX)}  ${s.hidden ? "hidden " : ""}${dims}${hidden}`);
     }
@@ -749,14 +771,13 @@ 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" },
   { key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
   { key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 6e4, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier; also the unpdf tier" },
-  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier; also info on PDF" },
-  { key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice" },
+  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier; also info on PDF 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)" },
   { key: "pymupdfVersion", flag: "--pymupdf-version", type: "version", default: "1.27.2.3", settable: true, env: "PI_DOC_TO_MD_PYMUPDF_VERSION", help: "pymupdf4llm pin (>= 1.27.0)" },
-  { key: "imageDpi", flag: "--image-dpi", type: "int", default: 150, settable: true, help: "Render DPI for page images" },
+  { key: "imageDpi", flag: "--image-dpi", type: "int", default: 150, settable: true, help: "Render DPI for page images and Excel rendered views" },
   { key: "imageFormat", flag: "--image-format", type: "enum", default: "png", settable: true, enumValues: ["png", "jpg"], help: "Rendered image format (embedded images keep their native extension)" },
-  { key: "maxCellsPerSheet", flag: "--max-cells-per-sheet", type: "int", default: 5e4, settable: true, help: "rows x cols budget per worksheet" },
   { key: "maxOutputBytes", flag: "--max-output-bytes", type: "int", default: 2e7, settable: true, help: "Child stdout cap in bytes" },
   { key: "outlineMaxEntries", flag: "--outline-max-entries", type: "int", default: 40, settable: true, help: "Heading outline / TOC / sheet inventory cap in the handle" }
 ];
@@ -877,6 +898,7 @@ var VENV_DIR_NAME = "doc-to-md-venv-v2";
 var LEGACY_VENV_DIR_NAME = "pymupdf-venv";
 var STDERR_CAP = 1e6;
 var OUTPUT_MAX_BYTES = 2e7;
+var EXCEL_PDF_FILTER = 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}';
 function withArgs(cfg) {
   return ["--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--with", `openpyxl==${PACKAGE_PINS.openpyxl}`, "--with", `xlrd==${PACKAGE_PINS.xlrd}`, "--with", `pillow==${PACKAGE_PINS.pillow}`];
 }
@@ -892,7 +914,7 @@ function uvChildArgs(cfg, script, mode) {
 function pythonChildArgs(script, mode) {
   return [script, mode];
 }
-function soffArgs(src, profileDir, outDir) {
+function soffArgs(src, profileDir, outDir, filter = "pdf") {
   return [
     "--headless",
     "--invisible",
@@ -905,7 +927,7 @@ function soffArgs(src, profileDir, outDir) {
     "--quickstart=no",
     `-env:UserInstallation=${pathToFileURL(profileDir).href}`,
     "--convert-to",
-    "pdf",
+    filter,
     "--outdir",
     outDir,
     src
@@ -1162,37 +1184,42 @@ function getBackend(cfg, deps, signal) {
   }
   return backendPromise;
 }
-async function convertOffice(sofficeTimeoutMs, src, signal, run = runCapped) {
+async function tryConvertOffice(sofficeTimeoutMs, src, signal, run = runCapped, filter = "pdf") {
   const profileDir = mkdtempSync(join3(tmpdir3(), "pi-doc-soffice-prof-"));
   const outDir = mkdtempSync(join3(tmpdir3(), "pi-doc-soffice-out-"));
   const cleanup = () => {
-    for (const d of [profileDir, outDir]) {
-      try {
-        rmSync2(d, { recursive: true, force: true });
-      } catch {
-      }
+    for (const d of [profileDir, outDir]) try {
+      rmSync2(d, { recursive: true, force: true });
+    } catch {
     }
   };
   try {
     const env = { ...process.env, SAL_USE_VCLPLUGIN: "svp", OOO_DISABLE_RECOVERY: "1", SAL_NO_MOUSEGRABS: "1" };
-    const r = await run("soffice", soffArgs(src, profileDir, outDir), { timeoutMs: sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
+    const r = await run("soffice", soffArgs(src, profileDir, outDir, filter), { timeoutMs: sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
     if (signal?.aborted) throw new Error("aborted");
-    if (r.code === null && !r.timedOut) {
-      throw new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
-    }
-    if (r.timedOut || r.code !== 0) throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr.slice(0, 500)}`);
-    const base = basename(src).replace(/\.[^.]+$/, "");
-    const pdfPath = join3(outDir, `${base}.pdf`);
+    const fail = (kind) => {
+      cleanup();
+      return { ok: false, kind, code: r.code, timedOut: r.timedOut, stderr: r.stderr.slice(0, 500) };
+    };
+    if (r.code === null && !r.timedOut) return fail("missing");
+    if (r.timedOut) return fail("timeout");
+    if (r.code !== 0) return fail("exit");
+    const pdfPath = join3(outDir, `${basename(src).replace(/\.[^.]+$/, "")}.pdf`);
     const st = statSync2(pdfPath, { throwIfNoEntry: false });
-    if (!st || !st.isFile() || st.size === 0) {
-      throw new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
-    }
-    return { pdfPath, cleanup };
+    if (!st || !st.isFile() || st.size === 0) return fail("no-pdf");
+    return { ok: true, pdfPath, cleanup };
   } catch (e) {
     cleanup();
     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}`);
+}
 var DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preserved";
 var DEGRADED_UNPDF = "unpdf text extraction - structure not preserved";
 var EXCEL_REMEDY = "Remedy: install uv, or pip install openpyxl xlrd pillow";
@@ -1239,8 +1266,18 @@ async function runTierReal(mode, childOptions, _b, signal, timeoutMs, backend) {
 function detailSuffix(r) {
   return r.detail ? ` (${r.detail})` : "";
 }
+function reconcileRenderMarkers(md, renderPages, fmt, sourceMap, reason) {
+  for (const idx of renderPages) {
+    const file = `s${idx}.${fmt}`;
+    const ok = sourceMap.has(file);
+    md = md.replace(`<!--rv:${idx}-->`, ok ? `Rendered view: ![Rendered view of sheet ${idx}](${file})` : `Rendered view: unavailable (${reason(idx)})`);
+    md = md.replace(`<!--rvs:${idx}-->`, ok ? "yes" : "no");
+  }
+  if (/<!--rvs?:\d+-->/.test(md)) throw new Error("internal: unresolved render marker");
+  return md;
+}
 async function convertDocument(o, signal, seams) {
-  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, ...seams };
+  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, office: tryConvertOffice, ...seams };
   const inputPath = resolve2(o.path);
   const st = statSync2(inputPath, { throwIfNoEntry: false });
   if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
@@ -1258,19 +1295,46 @@ async function convertDocument(o, signal, seams) {
       office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
       pdfPath = office.pdfPath;
     }
-    const base = { path: pdfPath, pages: o.pages, stagingDir: b.stagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxCellsPerSheet: o.maxCellsPerSheet, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion };
+    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 };
     let tier, engine, json, degraded = null, fallbackReason = 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 or lower maxCellsPerSheet" : "";
+        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();
+          }
+        }
+        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)}`);
@@ -1299,20 +1363,21 @@ async function convertDocument(o, signal, seams) {
         fallbackReason = `primary ${p.reason}`;
       }
     }
-    let body = rewriteImageLinks(json.markdown ?? "", b.sourceMap);
-    validateImageLinks(body, b.manifest);
+    if (!isExcel) notes = json.notes ?? [];
+    const body = rewriteLinks(json.markdown ?? "", b.sourceMap);
+    validateImageLinks(body, b.manifest, b.csvManifest);
     const head = [];
     if (degraded) head.push(`Degraded: ${degraded}`);
     if (fallbackReason) head.push(`Fallback-Reason: ${fallbackReason}`);
     if (json.failedPages?.length) head.push(`Failed pages: ${json.failedPages.map((f) => `${f.page} (${f.error})`).join("; ")}`);
     if (json.emptyPages?.length) head.push(`Empty pages: ${json.emptyPages.join(", ")}`);
-    for (const n of json.notes ?? []) head.push(`Notes: ${n}`);
+    for (const n of notes) head.push(`Notes: ${n}`);
     const markdown = (head.length ? `${head.join("\n")}
 
 ` : "") + body;
     commitBundle(b, markdown);
     const outline = scanOutline(markdown, o.outlineMaxEntries);
-    const details = { path: inputPath, backend: backend.kind, pymupdfVersion: o.pymupdfVersion, inputType: type, file: b.mdPath, outputDir: b.root, savedTo: b.mdPath, imagesDir: b.imagesDir, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, imageCount: b.manifest.size, bytes: Buffer.byteLength(markdown, "utf8"), lines: markdown.split("\n").length, degraded, fallbackReason, failedPages: (json.failedPages ?? []).map((f) => f.page), emptyPages: json.emptyPages ?? [], notes: json.notes ?? [], outline: outline.entries, outlineTotal: outline.total };
+    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 };
     return { output: formatHandle(details), details };
   } catch (e) {
     abortBundle(b);
@@ -1322,7 +1387,7 @@ async function convertDocument(o, signal, seams) {
   }
 }
 async function inspectDocument(o, signal, seams) {
-  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, ...seams };
+  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, office: tryConvertOffice, ...seams };
   const inputPath = resolve2(o.path);
   const st = statSync2(inputPath, { throwIfNoEntry: false });
   if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
@@ -1340,7 +1405,7 @@ async function inspectDocument(o, signal, seams) {
     const r = await s.runTier("info", { path, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, { stagingDir: "" }, signal, isExcel ? o.excelTimeoutMs : o.fallbackTimeoutMs, backend);
     if (!r.ok) {
       if ("userError" in r) throw new Error(r.userError);
-      if (isExcel && (r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes")) throw new Error(`Excel inspection failed: ${r.reason}. Remedy: raise excelTimeoutMs or lower maxCellsPerSheet${detailSuffix(r)}`);
+      if (isExcel && (r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes")) throw new Error(`Excel inspection failed: ${r.reason}. Remedy: raise excelTimeoutMs${detailSuffix(r)}`);
       throw new Error(`Inspection failed: ${r.reason}${detailSuffix(r)}`);
     }
     const toc = (r.json.toc ?? []).map(([level, title, page]) => ({ level, title, page }));
@@ -1397,7 +1462,7 @@ function readCliSettings(cwd, env, warn) {
     if (!existsSync3(file)) continue;
     let raw;
     try {
-      raw = JSON.parse(readFileSync2(file, "utf8")).quiver?.docToMd;
+      raw = JSON.parse(readFileSync(file, "utf8")).quiver?.docToMd;
     } catch {
       warn(`pi-quiver: ${file} is not valid JSON; ignored.`);
       continue;

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 per-worksheet matrices with formulas, cached values, merged/hidden disclosure. 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/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).",
 		promptSnippet: "Convert a local PDF/DOCX/PPTX/XLSX to a Markdown bundle (handle returned; read Saved-To)",
 		parameters: buildSchema(),
 

package/extensions/slack.ts

@@ -19,6 +19,7 @@ import {
 	buildPolicyBlock,
 	discoverRepoRoot,
 	resolveSlackConfig,
+	resolveCredential,
 	resolveToken,
 	searchMessages,
 	readThread,
@@ -40,7 +41,7 @@ import {
 import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, resolveMentions, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
 
 const IDENTITY = Type.Union([Type.Literal("user"), Type.Literal("bot")], {
-	description: 'Which token to act as: "user" (a real person, needed for slack_search/slack_thread) or "bot" (an app identity). Determines which token env var is used and whose name shows as the author.',
+	description: 'Which token to act as: "user" (a real person, needed for slack_search/slack_thread) or "bot" (an app identity). Determines which credential source is used and whose name shows as the author.',
 });
 
 // Approved recovery fields only - never dump the raw Slack API response (err.data can carry it
@@ -75,12 +76,13 @@ async function resolveCall(
 	signal: AbortSignal | undefined,
 	repoRoot: string,
 ): Promise<ResolvedCall> {
-	const token = resolveToken(identity, cfg, process.env, repoRoot);
+	const token = await resolveCredential(identity, cfg, process.env, repoRoot);
 	const teamId = await teamIdFor(token, defaultApiCall, signal);
 	const otherIdentity = identity === "user" ? "bot" : "user";
 	const otherTeamId = await (async () => {
+		if (otherIdentity === "user" && cfg.userTokenCommand) return undefined;
 		try {
-			const otherToken = resolveToken(otherIdentity, cfg, process.env, repoRoot);
+			const otherToken = await resolveCredential(otherIdentity, cfg, process.env, repoRoot);
 			return await teamIdFor(otherToken, defaultApiCall, signal);
 		} catch {
 			// Other identity's token can't be resolved/authenticated - best-effort
@@ -99,14 +101,14 @@ async function resolveCall(
 
 /**
  * slack_cache_refresh's identity pick: user token when present, else bot (spec "Cache" section).
- * Pure and network-free - resolveToken only reads env/.env - so it's unit-testable without a
- * transport seam.
+ * Pure and network-free - command configuration counts as a user credential without executing it.
  */
 export function pickCacheRefreshIdentity(
 	cfg: SlackConfig,
 	env: Record<string, string | undefined>,
 	repoRoot: string,
 ): "user" | "bot" {
+	if (cfg.userTokenCommand) return "user";
 	try {
 		resolveToken("user", cfg, env, repoRoot);
 		return "user";