@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/pdf/docs/skill-readme-archive.md

@@ -0,0 +1,152 @@
+# pdf
+
+A unified PDF skill for working with PDFs — generate, reformat, fill,
+and read. **Five routes**, all in one skill:
+
+- **CREATE** — render polished PDFs from scratch via Playwright Chromium
+  (HTML+CSS → PDF), with 8 battle-tested templates.
+- **REFORMAT** — restyle markdown / text / pdf as a clean PDF.
+- **FILL** — write values into AcroForm fields or as a visual overlay
+  on a non-fillable PDF.
+- **READ** — extract text, tables, metadata, and (when needed) charts /
+  scans from existing PDFs (pdfplumber default, vision escalation).
+- **MUTATE** — cookbook-only (merge / split / rotate / crop / watermark /
+  encrypt / annotate / sign / replace text via overlay).
+
+`SKILL.md` is the routing index — it points to the per-route guide in
+`docs/`. Read `SKILL.md` first, then the relevant guide.
+
+## Quick start
+
+```bash
+bash scripts/make.sh check                                    # verify deps
+bash scripts/make.sh fix                                      # auto-install missing deps
+
+# CREATE — copy a template, edit, render
+cp templates/data-viz-report/skeleton.html /tmp/page.html
+$EDITOR /tmp/page.html
+bash scripts/make.sh render --in /tmp/page.html --out /tmp/out.pdf --wait 15000
+
+# REFORMAT — single command, markdown to PDF
+bash scripts/make.sh reformat --input doc.md --out report.pdf --accent "#0a7488"
+
+# FILL — probe then apply / overlay
+bash scripts/make.sh fill probe form.pdf
+
+# READ (default — pdfplumber inline recipe; see docs/read-guide.md §3.1)
+python3 -c 'import pdfplumber; print(pdfplumber.open("doc.pdf").pages[0].extract_text())'
+
+# READ (vision escalation — scanned / chart-heavy / broken layout)
+python3 -m scripts.read_pdf_vision --input report.pdf --pages 1-30
+```
+
+---
+
+## Routes
+
+| Route | Use when | Read next |
+|---|---|---|
+| **CREATE** | Generate a polished PDF from scratch (chart-rich brief, brand guide, menu, report). | `docs/html-pdf-spec.md` → `docs/create-guide.md` |
+| **REFORMAT** | Restyle an existing markdown / text / pdf as a clean PDF. | `docs/reformat-guide.md` |
+| **FILL** | Put values into AcroForm fields, or visually overlay text onto a non-fillable PDF. | `docs/forms-guide.md` |
+| **READ** | Extract text / tables / metadata / coordinates / images from an existing PDF. | `docs/read-guide.md` (+ `docs/vision-guide.md` for the vision escalation) |
+| **MUTATE** | Merge / split / rotate / crop / watermark / encrypt / annotate / sign / replace text. | `docs/advanced-reference.md` (qpdf, pypdf, pdftk, reportlab — no in-skill route) |
+
+---
+
+## Layout
+
+```text
+SKILL.md                      <- route index (read first)
+templates/                    <- 8 distilled HTML templates
+  INDEX.md                    <- master template index
+  bilingual-menu-premium/     <- premium bilingual menu (CREATE)
+  brand-guide-2page/          <- 2-page brand guide (CREATE)
+    cases/minimax-web-brand-guide/ <- MiniMax website→brand-guide exemplar source
+  data-viz-report/            <- chart-rich data brief (CREATE)
+  multi-article-aggregator/   <- article digest with TOC pagination (CREATE)
+  multilang-research-report/  <- multi-jurisdiction regulatory report (CREATE)
+  reformat-default/           <- default markdown→HTML target (REFORMAT)
+  translate-preserve-layout/  <- layout-preserving translation (REFORMAT)
+  form-fill-acroform/         <- AcroForm fill (FILL)
+docs/
+  html-pdf-spec.md            <- HTML→PDF mechanical contract (read before authoring)
+  design-guide.md             <- aesthetic system: palette, typography, cover archetypes
+  create-guide.md             <- CREATE: 4-step flow, primitive cookbook, verification
+  reformat-guide.md           <- REFORMAT: input formats, title-lift, accent re-skin
+  forms-guide.md              <- FILL: probe → AcroForm or visual overlay
+  read-guide.md               <- READ: pdfplumber default + cookbook (text / tables / coords / raster)
+  vision-guide.md             <- READ vision: read_pdf_vision.py reference
+  troubleshooting.md          <- environment / CJK / chart / verification issues
+  advanced-reference.md       <- PDF mutation / annotation / signatures cookbook
+scripts/
+  make.sh                     <- unified CLI (check / fix / render / reformat / fill)
+  render_html.cjs             <- HTML or URL → PDF (Playwright)               [CREATE, REFORMAT]
+  reformat_parse.py           <- md / txt / pdf → HTML (markdown-it-py)        [REFORMAT]
+  merge.py                    <- merge multiple PDFs (pypdf)                   [utility]
+  read_pdf_vision.py          <- pages -> native Matrix images_understand via local-runtime [READ vision]
+  _pdf_read_lib.py            <- vision-side helpers (page-spec, spill, argparse) [READ vision]
+  lib/                                                                         [FILL]
+    geometry.py               <- coordinate transforms (img <-> pdf)
+    acroform_io.py            <- AcroForm field read / write
+    cli_utils.py              <- argparse / exit helpers (also used by READ)
+  pdf_inspect/                                                                 [FILL]
+    acroform_probe.py         <- detect: acroform=true|false
+    acroform_inspect.py       <- AcroForm → field metadata JSON
+    layout_scan.py            <- non-fillable PDF → layout JSON
+  fill/                                                                        [FILL]
+    acroform_apply.py         <- values.json → filled PDF (AcroForm)
+    overlay_apply.py          <- fields.json → annotated PDF (overlay)
+  render/                                                                      [FILL, READ]
+    page_rasterize.py         <- PDF → PNG per page
+    overlay_preview.py        <- page.png + fields.json → overlay PNG
+  validate/                                                                    [FILL]
+    geometry_lint.py          <- lint fields.json bbox geometry
+```
+
+---
+
+## Reference index
+
+| File | Purpose |
+|---|---|
+| `templates/INDEX.md` | Eight battle-tested PDF templates — start here for CREATE / REFORMAT / FILL |
+| `docs/html-pdf-spec.md` | HTML→PDF mechanical contract (page geometry, page-break, Chart.js, CJK, color, quality gate) |
+| `docs/design-guide.md` | Aesthetic system: palette mood table, typography, cover archetypes, anti-patterns |
+| `docs/create-guide.md` | CREATE route: 4-step flow, primitive cookbook, cover archetype re-skinning, verification |
+| `docs/reformat-guide.md` | REFORMAT route: input formats, title-lift, accent re-skinning, "when NOT to REFORMAT" |
+| `docs/forms-guide.md` | FILL route: probe → AcroForm or visual overlay, JSON schemas, geometry lint |
+| `docs/read-guide.md` | READ route: pdfplumber default, library + CLI cookbook, troubleshooting |
+| `docs/vision-guide.md` | READ vision: `read_pdf_vision.py` reference (flags, JSON schema, error matrix) |
+| `docs/troubleshooting.md` | Environment / CJK / chart settle / verification / stale-script issues |
+| `docs/advanced-reference.md` | Deeper cookbook (qpdf / pypdf / pdftk for mutation; pypdf + reportlab for annotation, signatures, text replacement) |
+
+---
+
+## Dependencies
+
+| Tool | Used by | Install |
+|---|---|---|
+| Python 3.9+ | `.py` scripts | system |
+| `markdown-it-py` | `reformat_parse.py` | `pip install markdown-it-py` |
+| `pypdf` | FILL, MUTATE | `pip install pypdf` |
+| `pdfplumber` | READ default | `pip install pdfplumber` |
+| `pdf2image`, `pillow`, `pypdfium2` | READ vision + page rasterise | `pip install pdf2image pillow pypdfium2` |
+| Node.js 18+ | `render_html.cjs` | system |
+| `playwright` + Chromium | `render_html.cjs` | `npm install -g playwright && npx playwright install chromium` |
+| `pdfinfo`, `pdftotext`, `pdfimages` (poppler) | READ + verification | `brew install poppler` |
+| `qpdf` | MUTATE / decryption | `brew install qpdf` (optional) |
+| `reportlab` | advanced overlay / annotation (optional, see `advanced-reference.md`) | `pip install reportlab` |
+
+`bash scripts/make.sh fix` installs everything required by CREATE /
+REFORMAT / FILL / READ automatically. The optional tools are lazily
+imported only when you reach for them in `advanced-reference.md`.
+
+`scripts/read_pdf_vision.py` additionally requires local-runtime to be running
+with authenticated native Matrix tools. Managed Matrix hosts use the Mavis login
+token; custom `MATRIX_BASE_URL` hosts require `MATRIX_TOKEN` in the runtime
+environment. See `docs/vision-guide.md`.
+
+## License
+
+MIT

package/server/assets/skills/pdf/docs/troubleshooting.md

@@ -0,0 +1,86 @@
+# Troubleshooting
+
+The first thing to do, always:
+
+```bash
+bash scripts/make.sh check
+```
+
+If `check` is already green, work through the table below.
+
+## Symptom table
+
+| Symptom | Most likely cause | Fix |
+|---|---|---|
+| `[ ] [ ] [ ]` boxes for CJK text | The host has no system CJK font, or the HTML font cascade is missing PingFang / Hiragino / Apple SD Gothic Neo | Check the cascade in [`html-pdf-spec.md §4`](html-pdf-spec.md#4-typography); install a CJK font (`brew install font-noto-sans-cjk-sc`) |
+| Cover PDF blank / partial / browser not found | Playwright Chromium not installed | `npx playwright install chromium`, or `bash scripts/make.sh fix` |
+| Output PDF is < 5 KB / `render_html.cjs` exits 3 | The source HTML had a JS error (CDN 404, syntax error, etc) | Open the source HTML in a browser, check the Console; vendor the script if a CDN is unreachable |
+| **Blank chart canvases in the PDF** | Chromium snapshotted the page before Chart.js painted | Pass `--wait 15000` to `make.sh render`; set `Chart.defaults.animation = false` once at the top of the page's `<script>` |
+| **Body text in default sans / serif** | Web fonts didn't load before snapshot | Use the system stack from [`html-pdf-spec.md §4`](html-pdf-spec.md#4-typography), or `@font-face` from a local file under `assets/fonts/` (the renderer waits for `document.fonts.ready` automatically) |
+| **Print color desaturated** (cover gradient looks washed out, KPI cards lose tint) | Missing `print-color-adjust: exact` | Apply the rule to the **universal selector** `*`, not just `body` |
+| **Charts split across pages** | Missing `.avoid-break` wrapper around `.chart-card` | Wrap every chart card with `<div class="chart-card avoid-break">` |
+| **A page has > 1/3 blank at the bottom** | A protected element (chart card / table / `page-break-before` H1) didn't fit the remaining space and got pushed to the next page | Don't ship half-empty pages. Three fixes (see [`html-pdf-spec.md` §3.2](html-pdf-spec.md#32-page-balance--every-page-must-be-full--23)): (1) **pull** small primitives from the next section into this page (insight callout, takeaway row, footer note); (2) **expand** current section (longer lead, key-facts table, split one big chart into two); (3) **re-order** so a tall element doesn't get orphaned. Never use `<br>` / spacers / shrunk margins to fake fullness |
+| **Cover / hero squished into top half of page** | HTML used `100vh` / `100%` height (viewport-bound, not page-bound) | A4 portrait at 14 mm margins → use `height: 268mm` (computed: 297 − 2×14 − 1 mm bleed). For other margins, recompute. Never `vh` / `vw` for page-level sizing |
+| **Content overflows / huge empty bands at bottom** | CSS declared `@page { size: 8.5in 11in }` (Letter) but renderer prints `--format A4` (default) | Either change CSS to `@page { size: A4 portrait }` (preferred) or pass `--format Letter` to `make.sh render` so CSS and PDF format match. Audit existing skeleton.html files: `grep -nE "8\.5in 11in\|Letter" templates/**/*.html` |
+| **Hero / section visually short, leaves bottom strip empty** | Designed at 16:9 or 4:3 aspect ratio (laptop-screen mindset) | A4 is **1 : 1.414** (taller than any laptop). Hero blocks should be ≈ 5:7. See [`html-pdf-spec.md` §1](html-pdf-spec.md#1-page-geometry) capacity numbers |
+| **Browser preview shows one giant horizontal page (not A4)** | `@page` is print-only; on screen the body fills the viewport (~1440px laptop) | Add the standard `@media screen` block from [`html-pdf-spec.md` §1](html-pdf-spec.md#screen-emulation-block--make-open-pagehtml-look-like-the-pdf) — every section then renders as a 210×297mm sheet on a gray backdrop. Or temporarily: Chrome DevTools → Rendering → Emulate CSS media type → `print` |
+| **`3nm⊃2;` artifacts in the PDF** | HTML entity typo where superscript was intended | Paste real unicode (`²` `³` `⁺` `™` `°`); never use `&sup` or `⊃` for superscripts |
+| **Class / style / attribute silently ignored, layout broken** | CJK full-width quotes (`"` `"` `'` `'`) in HTML attributes or CSS syntax — Chromium can't parse them | `grep -nP '[""''；：，（）]' page.html` and replace with ASCII `"` `'` `;` `:` `,` `()`. Full-width is fine inside body prose between tags, **never** in code |
+| Tables eat too much horizontal space | Full-width CJK punctuation (`（）`、`：`、`／`) inside narrow cells | Use half-width punctuation (`()`, `:`, `/`) in table cells; keep full-width in body prose |
+| Last page is < 1/3 full | Content didn't expand to fill the budget | Add a takeaway list / footer references / appendix; do **not** shrink margins to force-fit |
+| `ls -la report.pdf` shows a file but content is wrong | Existence is not success | Verify with `pdftotext -layout report.pdf - \| head -40` and `pdfinfo report.pdf \| grep Pages` |
+| `make.sh fix` printed `OK` but `make.sh check` still warns | Re-run `make.sh fix` — the current implementation prints the actual `pip` failure | If `pip` itself is missing (rare venv setup), run `python3 -m ensurepip --upgrade` |
+| `AttributeError: module 'inspect' has no attribute 'signature'` | A directory called `inspect/` is shadowing the stdlib `inspect` module on `sys.path[0]` | The skill ships FILL helpers under `scripts/pdf_inspect/` to avoid this; if you copied an older snapshot with `scripts/inspect/`, rename it. As a one-shot escape, `export PYTHONSAFEPATH=1` (Python 3.11+) drops the script-directory entry from `sys.path` |
+| REFORMAT loses my H1 | `reformat_parse.py` lifts the first H1 as the cover title (intentional) | Pass `--title "Different Title"` explicitly; the source's H1 will then stay in body |
+| Chromium hangs > 60 s during render | Source HTML waiting on a slow / hanging CDN | Vendor the external script (Chart.js, web fonts) next to the HTML and reference with a relative path |
+
+## Chart.js render-timing checklist
+
+When charts render blank in the PDF but look fine in the browser:
+
+1. `Chart.defaults.animation = false;` at the top of the init `<script>`.
+2. `bash scripts/make.sh render --in page.html --out out.pdf --wait 15000`
+   (default `--wait 800` is too short for non-trivial charts).
+3. Each `<canvas>` parent has `.avoid-break` (otherwise mid-chart page split
+   looks like a blank canvas).
+4. Open the source HTML in Chrome, check Console for errors. Common ones:
+   - `Chart is not defined` — the CDN didn't load (vendor it locally).
+   - `Cannot read properties of null` — wrong canvas ID in `getElementById`.
+
+## CJK support
+
+The skill renders CJK via the system font cascade declared in your HTML:
+
+```css
+font-family:
+  -apple-system, BlinkMacSystemFont, "SF Pro Display",
+  "PingFang SC",            /* Simplified Chinese — keep first */
+  "Hiragino Sans",          /* Japanese fallback */
+  "Apple SD Gothic Neo",    /* Korean — required for hangul */
+  "Helvetica Neue", Arial, sans-serif;
+```
+
+**Cascade order matters.** Putting `Hiragino Sans` before `PingFang SC`
+renders simplified-Chinese characters in JP forms. If hangul renders as
+tofu, add `Apple SD Gothic Neo` (macOS) or `Noto Sans CJK KR` (Linux).
+
+If you embed `@font-face` from a CDN, the renderer waits for
+`document.fonts.ready` automatically (15 s cap). Prefer local font files
+under `assets/fonts/` — CDN flakiness is the #1 reason fonts fall back.
+
+## Verification reminder
+
+Before you declare a job done, run at least these checks:
+
+```bash
+pdfinfo out.pdf | grep Pages
+pdftotext -layout out.pdf - | head -40
+ls -lh out.pdf            # should be > 50 KB for a real report
+open out.pdf              # eyeball — do charts actually render?
+```
+
+For a programmatic visual check (compare against a baseline image):
+
+```bash
+pdftoppm -r 90 -png -f 1 -l 1 out.pdf _verify
+```

package/server/assets/skills/pdf/docs/vision-guide.md

@@ -0,0 +1,188 @@
+# vision-guide — `read_pdf_vision.py` reference
+
+> **Read this first — `read_pdf_vision.py` is a fallback, not the default vision path.** The script
+> ships rendered pages to native Matrix vision because text-only models (e.g. M2.7) cannot see
+> images themselves. **If the model running this skill is multimodal / vision-capable (e.g. M3), you
+> do not need this script at all:** rasterise the target page(s) to PNG (read-guide §3.2 `pypdfium2`
+> / `pdftoppm`, or `scripts/render/page_rasterize.py`) and read the PNG(s) directly with the Read
+> tool — faster, offline, and no upstream LLM call. Use `read_pdf_vision.py` only on a text-only
+> model, or when native page reading is unavailable. Everything below describes that fallback.
+
+> Detailed reference for the only in-skill wrapped read route — `read_pdf_vision.py`, which exposes
+> MiniMax's native Matrix vision via local-runtime. All other read scenarios (text / tables /
+> coordinates / raster / decrypt / metadata) are cookbook recipes in [`SKILL.md`](../SKILL.md) §3-§4
+> and §7. There is no wrapped script for them — pdfplumber, pypdfium2, poppler, and qpdf are called
+> directly from a few lines of Python or shell.
+
+## Why a script instead of a recipe
+
+`vision` cannot be expressed as a one-liner: it has to render selected pages with poppler /
+pdf2image, pack them into multi-page chunks under a per-request byte ceiling (Matrix vision rejects
+images larger than ~5 MB), POST each chunk to the local-runtime, and concatenate the descriptions
+back. The chunking, spill-to-disk rule, and JSON envelope unwrap are too much to ask the LLM to
+re-derive every time. Hence the wrapped script.
+
+## Command
+
+```bash
+python3 -m scripts.read_pdf_vision --input file.pdf [opts]
+```
+
+Run from the `pdf` skill root (where `scripts/` lives) so the `scripts` package is importable.
+
+## Common parameters
+
+| Argument                 | Purpose                                                                                                                                                                                                                                                            | Default  |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `--input <path>`         | Path to the PDF (required)                                                                                                                                                                                                                                         | —        |
+| `--pages <spec>`         | Page range: `1-20` / `1,3,5` / `1-3,7,10-15` / `all`. Out-of-range pages are silently dropped with a stderr warning — e.g. `--pages 1-50` on a 26-page PDF runs on 1-26 and warns about 27-50. The script aborts only if **every** requested page is past the end. | `all`    |
+| `--json`                 | Emit structured JSON instead of Markdown                                                                                                                                                                                                                           | Markdown |
+| `--max-stdout-bytes <n>` | Spill outputs larger than `n` bytes to `~/.cache/mavis/pdf-out/<hash>.{md,json}` and return only a preview + path. `0` disables spilling and writes the full output to stdout.                                                                                     | `2048`   |
+
+## Mode-specific arguments
+
+| Argument           | Purpose                                                               | Default   |
+| ------------------ | --------------------------------------------------------------------- | --------- |
+| `--dpi <n>`        | Page-to-PNG render DPI                                                | `150`     |
+| `--max-bytes <n>`  | Per-chunk byte ceiling (default ~3 MB; upstream nginx caps near 5 MB) | `3000000` |
+| `--prompt <text>`  | Custom vision prompt                                                  | see below |
+| `--keep-tmp <dir>` | Keep intermediate page / chunk PNGs for debugging                     | —         |
+
+Default prompt (in Chinese, baked into the script):
+
+> Please output every piece of text in this image in reading order while preserving paragraphs,
+> lists, and tables. Briefly describe any charts.
+
+## Internal chunking (transparent to the model)
+
+1. `pdf2image` renders the selected pages to PNGs (poppler / pdftoppm backend).
+2. **Stitch-and-grow:** assemble one image, measure its true byte size, append the next page if
+   there is room, roll back one page on overflow. Each chunk sits as close to `--max-bytes` as
+   possible.
+3. Multi-page chunks are stitched vertically with PIL (no page cap; only bytes).
+4. A single page that already exceeds the limit is re-rendered at 100 DPI.
+5. Each chunk produces one native `images_understand` call
+   (`POST http://127.0.0.1:5321/mavis/api/matrix/tool/call`); results are concatenated.
+6. The envelope `{code, results: [{description, ...}]}` is unwrapped to the description text
+   automatically.
+
+## Time budget
+
+| Page count | Typical runtime | Suggested caller timeout |
+| ---------- | --------------- | ------------------------ |
+| 5 pages    | 30 s – 1 min    | 3 min                    |
+| 10 pages   | ~1 min          | 5 min                    |
+| 30 pages   | 3 – 5 min       | 10 min                   |
+| 50 pages   | 5 – 8 min       | 15 min                   |
+| 100 pages  | 10 – 15 min     | 25 min                   |
+
+The script applies its own 25-minute per-chunk timeout, but the **outer caller** (bash / agent
+harness) must also raise its timeout — the default 2-minute bash timeout will cut a long run in
+half. For 100+ pages, batch with `--pages 1-30`, `--pages 31-60`, etc., and call the script once per
+batch.
+
+## Error handling
+
+| Error                                                     | Meaning                                          | Action                                                                                                                  |
+| --------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `502 Bad Gateway` / `413 payload too large`               | Upstream nginx rejected the stitched image       | Add `--max-bytes 2000000` (or 1500000), shrink `--pages`, drop to `--dpi 100`                                           |
+| `gemini analysis failed` / `unexpected end of JSON input` | Transient upstream LLM hiccup                    | Retry the same command unchanged                                                                                        |
+| `Cannot connect to local runtime at port 5321`            | Local runtime is down or the port could not be discovered | Restart the MiniMax Code app; if the runtime is up, pass the port explicitly via `__MAVIS_RUNTIME_PORT` |
+| `auth failed` / `401`                                     | Matrix backend token expired or environment mismatch | Verify the managed login token matches the managed Matrix host, or set `MATRIX_TOKEN` for a custom `MATRIX_BASE_URL`     |
+
+The script also prints a one-line stderr hint on 502 / 413 so the model does not need to consult
+this guide first.
+
+## Dependencies
+
+```bash
+pip3 install --user pdf2image pillow
+brew install poppler        # pdftoppm (pdf2image backend) + pdfinfo
+```
+
+Runtime side: managed Matrix hosts use the Mavis login token. For a custom `MATRIX_BASE_URL`, set
+`MATRIX_TOKEN` in the runtime environment, then restart the MiniMax Code app so local-runtime picks it up.
+
+## Output spill (preventing context blow-up)
+
+**Default:** when the output exceeds 2 KB, the script does NOT print the full text to stdout.
+Instead it:
+
+1. Writes the full content to `~/.cache/mavis/pdf-out/<sha256-prefix>.{md,json}` (named by content
+   hash so identical outputs reuse the same file).
+2. Returns the first 2 KB as a preview plus the absolute path on stdout.
+3. Lets the model decide what to do next:
+   - Read the whole file: `cat ~/.cache/mavis/pdf-out/abc...md`
+   - Search for something specific: `grep -i "keyword" ~/.cache/mavis/pdf-out/abc...md`
+   - Re-extract a narrower range: `python3 -m scripts.read_pdf_vision --input <file> --pages 14-18`
+
+**Markdown mode** prepends the preview with:
+
+```markdown
+<!-- mavis-pdf: output truncated, full text spilled to disk -->
+
+> Full output: 12,345 bytes -> /Users/.../<hash>.md Showing first 2,048 bytes below. Read the file
+> with `cat` / `grep`, or re-run with narrower `--pages`.
+```
+
+**JSON mode** wraps the spilled output:
+
+```json
+{
+  "truncated": true,
+  "totalBytes": 12345,
+  "outputFile": "/Users/.../<hash>.json",
+  "previewBytes": 2048,
+  "preview": "..."
+}
+```
+
+**Disable truncation** (full output to stdout): `--max-stdout-bytes 0`. **Adjust threshold:**
+`--max-stdout-bytes 8192`, etc.
+
+## JSON output schema
+
+```jsonc
+{
+  "mode": "vision",
+  "file": "/abs/path.pdf",
+  "pageCount": 18,
+  "selectedPages": [1, 2, ..., 18],
+  "dpi": 150,
+  "chunks": [
+    {
+      "pages": [1, 2, ..., 7],
+      "sizeBytes": 2870055,
+      "width": 1241,
+      "height": 12278,
+      "text": "...",
+      "isError": false
+    }
+  ]
+}
+```
+
+When truncated by `--max-stdout-bytes`, stdout returns the wrapper:
+
+```jsonc
+{
+  "truncated": true,
+  "totalBytes": 12345,
+  "outputFile": "/Users/.../<hash>.json",
+  "previewBytes": 2048,
+  "preview": "...", // first 2 KB of the full JSON above; trailing bytes may be invalid JSON
+}
+```
+
+## Shared helper module
+
+`scripts/_pdf_read_lib.py` — helpers used by `read_pdf_vision.py`:
+
+- `parse_pages(raw)` / `validate_pages(pages, total)` / `format_pages(pages)`
+- `maybe_spill_to_file(content, ext, max_bytes)`
+- `add_common_args(parser)` / `emit(content, ext, max_bytes)`
+- `info(msg)` / `warn(msg)` / `die(msg)` for stderr progress
+
+Kept under the original name `_pdf_read_lib.py` even though `vision` is now the only consumer — the
+helpers are read-side concerns (page spec parsing, output spill, stderr progress) and the leading
+underscore already signals "internal".