dsh-office-kit 0.1.0 → 0.3.0

package/assets/skills/office-pdf/SKILL.md

@@ -1,86 +1,103 @@
 ---
-description: Create, read, edit, merge, rotate, and render PDF files with the bundled Office helper CLI.
+description: Create, inspect, edit, redact, stamp, and render PDF files with the bundled Office helper CLI and self-contained Python scripts.
 ---
 
 # PDF
 
-Create PDFs, extract their content, edit metadata/pages, and rasterize them for visual verification. This skill handles local files only; OCR and cloud PDF services are out of scope.
+A PDF page is a content stream of text-showing and path-painting operators behind a page box. Every job in this pack either reads that stream (PyMuPDF, pdfplumber, pypdf), writes a new one (reportlab), or rasterises the result so you can look at it. Work from the mechanics outward: inspect first, choose the smallest operation that changes what the user asked for, then prove the change on a render. The helper CLI and the scripts are fast paths, not limits — each task file carries a runnable snippet for jobs they do not cover yet.
+
+| User job | What actually happens | Fast path |
+| --- | --- | --- |
+| Look at a page, crop, or measure geometry | Rasterise the page box with PyMuPDF at a DPI, read page size, rotation, text, drawings, widgets | `scripts/render_pages.py`, `pdf render` |
+| Extract text or tables | pdfplumber reads characters and clusters table rules per page | `scripts/extract_text.py`, `pdf read` |
+| Inspect or fill an AcroForm | pypdf walks `/AcroForm` widgets, then rebuilds each `/AP` appearance from `/V` | `scripts/forms.py`, snippet in `tasks/forms.md` |
+| Remove a region (redaction) | PyMuPDF redaction annotations plus `apply_redactions` strip text and line art inside a rect | `scripts/redact_region.py`, snippet in `tasks/redact.md` |
+| Read or rewrite metadata | The document info dictionary; producer keys cannot change page content | `scripts/metadata.py` |
+| Merge, split, reorder, rotate, delete pages | Page-tree rearrangement; content is copied, not re-flowed | `scripts/page_ops.py`, `scripts/split_pages.py`, snippet in `tasks/edit-pages.md` |
+| Stamp a footer, header, or banner | reportlab draws an overlay page, pypdf merges it over the target pages | `scripts/stamp_overlay.py` |
+| Build a new document | reportlab draws primitives and text into a page | `pdf create`, `tasks/create.md` |
 
 ## Before any file work
 
 1. Call the `office_status` tool.
-2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file. They are verified absolute paths.
-3. If no compatible Python is reported, stop and tell the user how to install it. Never claim a PDF was produced when the CLI was unavailable.
+2. Read the `## Office runtime` JSON block at the end of this file and use its `python`, `cli`, `skill`, and `shared` values verbatim, quoted: `"<python>"`, `"<cli>"`, `"<skill>/scripts/<name>.py"`.
+3. If that block reports no working runtime, stop. Give the user the `node "..."` remedy command it names, then call `office_status` again. Never fabricate a PDF result you could not verify.
 
-## Create
+Scripts under `"<skill>/scripts/"` are standalone argparse CLIs. Run `<python> <script> --help` before using one you have not called in this session.
 
-```bash
-"<python>" "<cli>" pdf create --spec "<spec.json>" --out "<output.pdf>"
-```
+## Route selection
 
-```json
-{
-  "title": "Product Brief",
-  "author": "DSH Office Suite",
-  "page_size": "A4",
-  "blocks": [
-    { "type": "heading", "level": 1, "text": "Product Brief" },
-    { "type": "paragraph", "text": "This PDF contains Chinese, English, numbers, and punctuation." },
-    { "type": "bullets", "items": ["Fast", "Local", "Verifiable"] },
-    { "type": "table", "headers": ["Item", "Value"], "rows": [["Version", "1.0"], ["Status", "Draft"]] },
-    { "type": "image", "path": "<absolute image path>", "width": 4.5 },
-    { "type": "page_break" }
-  ]
-}
-```
+Decide the route before you type a command. Every route ends in the same render check.
 
-Supported blocks: `title`, `heading` (`level` 1–2), `paragraph`, `quote`, `bullets`, `numbered`, `table`, `image` (`path`, `width` inches; height is derived at 0.66 aspect), `page_break`, `spacer` (`height` inches). Use `pages: [{ "blocks": [...], "break": true }]` for explicit page grouping.
+- **The file does not exist** → create it from a `pdf create` spec, or with reportlab when the layout does not fit the block model (`tasks/create.md`).
+- **The file exists and must change** → read it first (`pdf read`, and a render), then mutate it with the script named in the task file. The helper CLI has no edit verb: it creates, reads, renders, and reports status only; every change is a `scripts/*.py` call.
+- **A script covers the job** → run it, then verify its JSON report and its rendered pages. Scripts refuse to overwrite their input and exit non-zero on a failed self-check; treat both as hard stops.
+- **A read/render verb covers it** → `pdf read`, `pdf render`, or `pdf status`, then verify in the task's own way. Never route a mutation through the CLI.
+- **Neither covers it** → run the runnable snippet in the matching `tasks/*.md` file, or adapt it. Do not invent a CLI verb, and do not tell the user the job is impossible because no verb exists.
+- **Choose the smallest operation** that satisfies the request: metadata change before rebuild, page move before re-creation, one-line patch before re-typing the page.
 
-CJK text uses the first available system font (`msyh`, `simsun`, PingFang, Noto Sans CJK, DejaVu). If no CJK font exists, Chinese characters may render as blanks; verify before delivery.
+## Failure handling
 
-## Read
+| Symptom | Meaning | Next step |
+| --- | --- | --- |
+| `{"ok": false, ...}` and non-zero exit | Invalid argument, missing file, or a refused overwrite | Read the `error` field, fix what it names, re-run. Never strip a step to make it pass. |
+| `encrypted` in the error | The file needs a password | Ask the user for a decrypted copy; do not guess passwords or write one into a command. |
+| `no document renderer found: install LibreOffice, Microsoft Office, or WPS Office` | Media conversion for docx/pptx/xlsx is unavailable | PDF rendering still works (PyMuPDF); for a PDF this is harmless. For other formats report that appearance could not be checked. |
+| `leftover_chars_in_rect` greater than 0 | The redaction rectangle missed text | Enlarge `--pad` or reconvert the region; re-render before delivering. |
+| `not_applied` is not empty | A form value did not persist after save | Treat as a failure: check the field name, its allowed states, and whether the widget has an appearance stream. |
+| `chars: 0` on a page that shows text | Scanned page, no text layer | Say so; follow `references/limits.md` for the OCR situation. Do not return an empty extraction as success. |
+| Render shows the change, `pdf read` does not | The edit landed in pixels only | Fix the content stream or note the limitation; a visible-only change usually means a cover-up, not an edit. |
 
-```bash
-"<python>" "<cli>" pdf read --input "<file.pdf>"
-```
+## Quality rules
 
-Returns `page_count`, `word_count`, metadata, per-page text and character counts, AcroForm field identifiers, and `ocr: { available: false }`. Extraction quality depends on the source PDF (scanned pages have no text layer).
+- One heading scale, one body size, and one margin system per document (`references/layout-quality.md`).
+- Prove every structural change on a render of the changed page, not only on a text dump.
+- Keep page geometry consistent when merging or stamping: use each page's own box.
+- Do not claim redaction while the words are still extractable.
+- Preserve the user's original: write `<original>-edited.pdf`, never over it.
+- Mark deliberate shortcuts (a rebuild instead of a reflow, a stamped patch instead of a content edit) in the reply, so the user knows what kind of change they received.
+- Deliver with `present`, then one sentence about what changed and where the file is.
 
-## Edit
+## Delivery
 
-```bash
-"<python>" "<cli>" pdf edit --input "<file.pdf>" --spec "<edit.json>" --out "<file-edited.pdf>"
-```
+Always hand the finished file to the user with the `present` tool, then summarise in one sentence what changed. A bare path is not delivery: the chat transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动" and the user cannot open them.
 
-```json
-{
-  "metadata": { "Title": "Product Brief (final)", "Author": "DSH Office Suite" },
-  "merge": ["<other.pdf>"],
-  "rotate": 90,
-  "pages": [0],
-  "remove_pages": [2]
-}
-```
+- Creating a file: write it into the user's workspace, verify it, then `present`.
+- Editing an existing file: never overwrite the original. Write `<original>-edited.<ext>` (or a name the user asked for), verify it, `present` it, and state both paths.
+
+## Annotations
+
+The user may reply with an `office-annotations` block: `[{ page, text, requirement, region: { left, top, width, height } }]`. `region` is normalised 0–1 against the rendered preview page the user drew on; `requirement` is free-form natural language. Treat it as a change request, not as editor state: locate what the region covers, apply the smallest edit that satisfies `requirement`, re-render, and confirm the region now looks right.
+
+When the payload cannot be mapped to a concrete object (the region is empty or the file has no geometry), do not guess silently — say what you could not locate.
 
-- `merge` appends pages from other PDFs.
-- `rotate` is degrees clockwise; `pages` limits it to zero-based page indexes.
-- `remove_pages` is zero-based and applied to the original pages; merged pages are appended after.
-- Metadata keys may be plain (`Title`) or PDF names (`/Title`); the CLI normalizes them.
+For PDF the `page` value is the 1-based page of the file itself, and `region × page.rect` is the real place to operate on: convert once with PyMuPDF and use the device rect directly. `text` is the words under the mark and wins over the region when they disagree; `imageName`, when present, is a screenshot of the marked area that you can open with `read_image`. Full resolution recipe: `tasks/annotations.md` and `"<shared>/annotation-recipes.md"`.
 
-The input file is never modified.
+## Verify
 
-## Render and verify
+Render before you present, and again after every fix:
 
 ```bash
 "<python>" "<cli>" pdf render --input "<file.pdf>" --out-dir "<render-dir>" --dpi 110
 ```
 
-Renders every page to PNG with PyMuPDF. Open the images and check page count, clipping, overlap, missing glyphs, and scanned-page readability. If `read` returns little text and the render shows an image of text, OCR is required; say so instead of pretending the text was extracted.
+Open each PNG with `read_image`, and compare it with the same page rendered before the change. Look for text clipped at the page box, overlapping stamps or form fields, fonts replaced by boxes, rotated pages that now sit sideways, tables spilling past the margin, and scanned pages whose text is an image. Then run `"<python>" "<cli>" pdf read --input "<file.pdf>"` and confirm the text, page count, and form fields match what you edited. Two or three render/patch passes are normal; if a defect survives three, say what still looks wrong instead of calling it fixed.
+
+## Tasks
+
+| Task | Read |
+| --- | --- |
+| Create a PDF from a spec or reportlab | `tasks/create.md` |
+| Extract text, tables, or page images | `tasks/read.md` |
+| Inspect, fill, or flatten an AcroForm | `tasks/forms.md` |
+| Remove a region of a page | `tasks/redact.md` |
+| Merge, split, reorder, rotate, delete pages | `tasks/edit-pages.md` |
+| Stamp a footer, header, or label | `tasks/stamp.md` |
+| Resolve an `office-annotations` region | `tasks/annotations.md` |
+| Decide what a PDF cannot do | `references/limits.md` |
+
+`references/geometry.md` explains page boxes and normalised regions, `references/layout-quality.md` is the pre-delivery visual checklist, `references/form-fields.md` covers field flags, appearance streams, and flattening.
 
-## Not supported
+## Shared workflow
 
-- OCR / scanned-document text recognition.
-- Filling, creating, or flattening AcroForms (field identifiers are reported for inspection only).
-- Digital signatures, encryption/password handling, redaction, annotations, bookmarks editing.
-- PDF/A, tagged-PDF accessibility repair, or exact reflow of an existing document.
-- Google Drive or other online PDF services.
+Follow `"<shared>/common-workflow.md"` for the create-or-edit decision, the failure ladder, and the edit naming rule, and `"<shared>/annotation-recipes.md"` for the payload shapes the client sends.

package/assets/skills/office-pdf/references/form-fields.md

@@ -0,0 +1,56 @@
+# Form field mechanics
+
+## Field tree
+
+`/AcroForm` in the catalog holds `/Fields`, the root field array. A field dictionary has:
+
+- `/T` — partial name; the full name is the partial names of ancestors joined with dots.
+- `/FT` — field type, inherited: `Tx` text, `Btn` button, `Ch` choice, `Sig` signature.
+- `/V` — current value. Text fields store a string; buttons store the selected state name (`/Yes`, `/Off`, `/basic`); choice fields store a string or an array of strings; signature fields store a dictionary.
+- `/Ff` — flags bitmask, inherited. Bit 1 (`1`) read-only, bit 2 (`2`) required, bit 13 (`4096`) multiselect for choices, bits 15–17 (`65536`/`131072`/`262144`) button behaviour (no-toggle, radio, pushbutton).
+- `/DA` — default appearance string; controls the font and colour an appearance generator uses.
+- `/Kids` — child fields or widgets.
+- `/AP` — appearance dictionary: `/N` normal, `/R` rollover, `/D` down. For a button, `/N` maps each state name to a form XObject; for text and choice fields, `/N` is one stream.
+- `/Rect`, `/P`, `/AS` — widget geometry, owning page, and the button state a widget currently shows.
+- `/NeedAppearances` in `/AcroForm` — documented flag that asks viewers to regenerate appearances; many viewers ignore it, which is why a file can hold a correct `/V` and show nothing.
+
+## What a fill must satisfy
+
+1. Field `/V` equals the requested value, in the field's expected representation (boolean → state name, radio → that button's on-state, choice → string or list).
+2. The widget's `/AP /N` exists and is a stream or state map with a `/BBox` and `/Resources`; the stream's content paints the value.
+3. The widget's `/AS` names a state present in `/AP /N`; for a radio group every widget's `/AS` must be the group's chosen state or `/Off`.
+4. The value is visible on the page: rendered inside `/Rect`, not clipped, not hidden behind the page content.
+
+Updating `/V` alone satisfies 1 and fails 2–4. That is the "filled but blank" failure. Rebuilding the appearance and forgetting to remove a stale `/AS` satisfies 1–3 and shows two selected radio buttons. Reopening and checking 1–3 after save, then rendering for 4, is the whole discipline.
+
+pypdf's `update_page_form_field_values(writer, page, values, flags, auto_regenerate, flatten)` handles 1–3 for common field types when the writer cloned the document properly (and `writer.reattach_fields(page)` was called where needed). Button groups need the extra `/AS` synchronisation described in `tasks/forms.md`.
+
+## Flattening
+
+Two meanings, both destructive in different ways:
+
+- `flatten=True` in `update_page_form_field_values` paints each widget's current appearance into the page content and removes the interactive field.
+- Post-process: remove `/Widget` annotations with `writer.remove_annotations(subtypes="/Widget")` and pop `/AcroForm` from the catalog. This alone leaves the widget's appearance in place, so the page looks unchanged while the fields stop responding.
+
+Do both when the user wants a non-editable form. Verify: zero `/Widget` annotations remain, no `/AcroForm` in the catalog, and the rendered page still shows the values.
+
+## Appearance streams
+
+An appearance stream is a form XObject.
+
+```
+/Type /XObject
+/Subtype /Form
+/BBox [0 0 200 14]
+/Resources << /Font << /Helv 5 0 R >> >>
+```
+
+`/BBox` is the drawing area in the widget's own coordinates; the widget's `/Rect` maps that area onto the page. A generated stream usually sets the font from `/DA`, positions text at a small inset, and clips to `/BBox`. When a field must look right and its own appearance is missing, drawing a replacement with reportlab at `/Rect` coordinates and merging it into the page produces the same visual result without lying about the field value.
+
+## Signature fields
+
+`/FT /Sig` requires a certificate and a signing implementation. Filling text into a signature field, or editing any page of an already-signed document, breaks the signature. Say that plainly and offer the unsigned rebuild; do not present an edited document as signed.
+
+## Choice fields
+
+`/Opt` lists the allowed options; `/V` is the chosen value or values. A single-select choice takes a string; multi-select takes an array. If the value is not in `/Opt`, viewers show blank — validate against `/Opt` before writing, and report the allowed options when the requested value is missing.

package/assets/skills/office-pdf/references/geometry.md

@@ -0,0 +1,44 @@
+# Page geometry
+
+PDF units are points: 1/72 inch. A4 is 595 × 842 points, Letter 612 × 792. Numbers in a spec, a region, or a stamp are points unless stated otherwise.
+
+## Boxes
+
+- **MediaBox** — the physical page, the outermost boundary.
+- **CropBox** — the visible area; defaults to MediaBox. A viewer shows the CropBox.
+- **BleedBox / TrimBox / ArtBox** — print-production hints, usually absent in office output.
+
+PyMuPDF's `page.rect` is the CropBox (or MediaBox when no CropBox exists), with `x0, y0` normally 0 and `x1, y1` the width and height. pypdf exposes `.mediabox` and `.cropbox` directly. When you move content between documents, use the page's own box, not a constant: mixed-size sources are common after a merge.
+
+## Coordinates
+
+The origin is the bottom-left of the page box, x to the right, y upward. Library calls that take a rectangle (`page.get_textbox(rect)`, `add_redact_annot`, `get_pixmap(clip=...)`) use that system. Library calls that report word boxes (`page.get_text("words")`, `search_for`) report rectangles in the same system — a word's box is not a baseline, so a text redaction rect is close but may clip the line.
+
+reportlab's `drawString(x, y, text)` places a *baseline*, measured from the bottom. Converting a top-down measurement `top` to that system: `y = page_height - top - font_size * 0.8` puts the glyph body roughly where it was.
+
+## Rotation
+
+`/Rotate` is a multiple of 90 stored per page; viewers apply it on top of the content. `page.rect` in PyMuPDF is already the rotated (visible) geometry, while `page.mediabox` stays unrotated. Redactions and text boxes use the unrotated content stream, so a rotated page needs the rectangle transformed: simplest is `page.set_rotation(0)`, do the work, then set the rotation back — the render proves whether you got it right.
+
+## Normalised regions
+
+`office-annotations` regions are fractions of the rendered preview page:
+
+```
+x0 = page.x0 + left * page.width
+x1 = page.x0 + (left + width) * page.width
+y0 = page.y0 + top * page.height
+y1 = page.y0 + (top + height) * page.height
+```
+
+That is the whole conversion for an unrotated page. For a rotated page, convert against the preview's own orientation and map back; the words under the converted rect tell you immediately if the mapping is off.
+
+## Pixels and DPI
+
+A raster at `dpi` has `pixels = points * dpi / 72`. A 110 dpi A4 page is roughly 909 × 1287 pixels. When the user draws a region on a rendered image, the fraction is DPI-independent — you never need the pixel size to convert it. For image quality on print, 150 dpi is the minimum for a screenshot, 300 dpi for artwork.
+
+## Text measurements
+
+`page.get_text("dict")` gives blocks → lines → spans, each span with `size` (font size in points), `font`, `origin` (the baseline point), and the text. Use the span measurements, not the bounding box, when you redraw a line: the box includes ascenders and descenders that change the apparent size.
+
+`page.get_textbox(rect)` returns the characters whose boxes intersect `rect`, in reading order. That is the correct way to confirm what a region covers; `page.get_text("words", clip=rect)` returns word tuples when you need the boxes too.

package/assets/skills/office-pdf/references/layout-quality.md

@@ -0,0 +1,41 @@
+# Layout and delivery quality
+
+Run this list on the rendered pages before presenting a file. It is the difference between "the command exited 0" and "the document is right".
+
+## Page level
+
+- Page count matches the request; no stray blank page at the end from a trailing `page_break` or an empty `showPage`.
+- Every page has the intended size and orientation — a merged section with Letter pages inside an A4 report is visible in the render.
+- Margins are consistent; nothing is clipped at the page box edge, including stamps and footers.
+- The page box is the CropBox the user expects; a crop that hides a footer is a bug, not a clean-up.
+
+## Text
+
+- Body size, leading, and font are consistent; a patched line that uses a different size or face is a visible patch job.
+- Headings descend in a sensible scale and do not collide with the body.
+- No overflow past the right margin, no hyphen-only line breaks, no replacement boxes for missing glyphs.
+- Non-Latin text renders as characters, not blanks — this needs a registered font with the right coverage.
+- Extracted text matches what is visible: run `pdf read` on the final file and spot-check the edited region.
+
+## Tables and figures
+
+- Table columns fit the text column; long cell text wraps rather than clipping.
+- A table that splits across pages repeats its header row.
+- Images keep their aspect ratio; a stretched logo is a defect.
+- Ruled lines and fills from a redacted block are gone, not half-erased.
+- Charts and screenshots are legible at print size; text inside an image is not searchable, so keep the numbers in the body text too.
+
+## Stamps and annotations
+
+- Footer/header text sits in the margin, not over body copy.
+- Page numbers are correct on the first and last page (off-by-one is the classic overlay bug).
+- A stamp appears once per page; repeated merges double it.
+- Filled form values sit inside their widget boxes, are not clipped by the box border, and use the field's own font where the appearance stream was preserved.
+
+## Fonts and links
+
+`page.get_fonts(full=True)` lists embedded fonts. A subset font is fine for display; it means the file is not intended for text-heavy editing. Check that no font is missing for the glyphs you wrote — the render shows boxes where coverage is absent. Links and bookmarks that pointed at reordered or deleted pages may dangle; the render shows clickable areas only, so trust the original page order rather than assuming the links moved with the content.
+
+## Structural sanity
+
+Open the output one more time with the same route the user will use: `"<python>" "<cli>" pdf read --input "<file>"`. It confirms the file parses, the page count, the metadata, and that text is extractable. A file that renders but fails to parse is worse than an obvious error, because it fails later in someone else's viewer.

package/assets/skills/office-pdf/references/limits.md

@@ -0,0 +1,58 @@
+# When a PDF job is beyond this pack
+
+Every entry names the missing capability, what you can still deliver, and how the user resolves it. Never answer with a bare "unsupported": say what is missing, what the floor is, and give the next step.
+
+## Scanned pages with no text layer
+
+The words exist only as pixels; extraction and search cannot see them. `render_pages.py` reports `chars: 0` for such a page, and the render shows the text as an image.
+
+- Still possible: render, crop with `read_image`, and transcribe the visible text; redact the image pixels with `--images pixels`; rebuild the page as a created PDF from the transcription.
+- Resolution: the user supplies a text-based copy of the file, or runs OCR where they have it (this runtime has no OCR engine, so do not promise the words will be extracted here).
+
+## Encrypted or password-protected files
+
+pypdf and PyMuPDF can open with a password only if it is provided; every script here exits with "encrypted" and does no work.
+
+- Resolution: ask the user to decrypt the file first, then re-run. Never write a password into a command line that will be logged.
+
+## Signing and certificates
+
+Creating a digital signature needs a certificate, a signer, and a signature field; the runtime has none of them. Editing a signed document invalidates its signature.
+
+- Still possible: fill unsigned fields, rebuild the content, deliver an unsigned file — and say clearly that the signature is gone.
+- Resolution: signing must happen in a tool with a certificate; the user applies it after the content is final.
+
+## Paragraph-level re-editing
+
+PDF has no paragraph model: the content stream is positioned glyphs and paths. "Rewrite this paragraph" becomes a block-level operation — redact the old block, stamp the new text, and check the reflow yourself. Truly reflowing a page means rebuilding it from extracted content.
+
+- Still possible: replace a line or a block in place (see `tasks/annotations.md`), remove a block, stamp a note.
+- Resolution for reflow: rebuild the document from a spec with the corrected text, and say that it was rebuilt rather than patched.
+
+## Lexical repair of broken files
+
+A file with a damaged cross-reference table may still render (viewers rebuild the xref) while strict parsers refuse it. If PyMuPDF or pypdf cannot open the file, do not silently produce an empty document.
+
+- Still possible: report the parse error, ask the user to open and re-save the file in a reader (which repairs it), then re-run.
+- Resolution: whichever tool originally produced the file should be told about the corruption.
+
+## Tagged PDF and accessibility remediation
+
+Reading order, alternative text, and tags live in a structure tree that the libraries here can read but not author reliably. A visual edit does not add tags.
+
+- Still possible: keep the visual result correct and say the file is untagged.
+- Resolution: accessibility remediation needs an authoring tool that writes the structure tree.
+
+## PDF/A and archival conformance
+
+Conformance requires font embedding rules, metadata schemas, and colour profiles that these libraries do not validate.
+
+- Still possible: many PDF/A inputs will survive a page-level edit and remain close, but claiming conformance would be a guess.
+- Resolution: validate with a dedicated PDF/A checker before delivery.
+
+## Creating or restructuring form fields
+
+pypdf can fill existing fields; creating a new interactive field with a correct `/AP` state map is much more than a fill. reportlab can draw a form-like appearance, but without a widget tree it is not a form.
+
+- Still possible: stamp labels and values at coordinates so the printed result looks filled.
+- Resolution: an authoring tool for interactive forms, or accept a non-interactive output and say so.

package/assets/skills/office-pdf/scripts/extract_text.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Extract per-page text and tables from a PDF with pdfplumber.
+
+Use this when you need the words, not the picture: page text, word counts, and
+detected tables as row arrays. Visual fidelity is not part of the contract -
+layout, wrapping, and column order may differ from what the rendered page
+shows - so always render before judging a document on this output alone.
+
+Exit codes: 0 success, 1 bad arguments, 2 unreadable input or write failure.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def emit(value, out=None):
+    text = json.dumps(value, ensure_ascii=False, indent=2, default=str)
+    if out:
+        target = Path(out).expanduser()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text + "\n", encoding="utf-8")
+    print(text)
+
+
+def fail(message, code=1, detail=None):
+    payload = {"ok": False, "error": message}
+    if detail is not None:
+        payload["detail"] = detail
+    print(json.dumps(payload, ensure_ascii=False, indent=2, default=str), file=sys.stderr)
+    raise SystemExit(code)
+
+
+def parse_pages(spec, page_count):
+    if not spec or spec.strip().lower() == "all":
+        return list(range(1, page_count + 1))
+    pages = []
+    try:
+        for part in spec.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            if "-" in part:
+                start_text, end_text = part.split("-", 1)
+                start, end = int(start_text), int(end_text)
+            else:
+                start = end = int(part)
+            if start < 1 or end > page_count or start > end:
+                fail(f"page range out of bounds: {part} (document has {page_count} pages)")
+            pages.extend(range(start, end + 1))
+    except ValueError:
+        fail(f"cannot parse page selection: {spec!r}")
+    return sorted(dict.fromkeys(pages))
+
+
+def clean(cell):
+    return "" if cell is None else str(cell).replace("\n", " ").strip()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Extract page text and detected tables from a PDF.",
+        epilog="Example: extract_text.py --input report.pdf --pages 1-2 --layout",
+    )
+    parser.add_argument("--input", required=True, help="PDF file to read")
+    parser.add_argument("--pages", default="all", help='1-based selection such as "1-3,7" (default: all)')
+    parser.add_argument("--layout", action="store_true", help="Keep rough horizontal layout in the text output")
+    parser.add_argument("--no-tables", action="store_true", help="Skip table detection (faster on long documents)")
+    parser.add_argument("--text-out", help="Also save the joined page text to this file")
+    parser.add_argument("--json-out", help="Also write the JSON report to this path")
+    args = parser.parse_args()
+
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        fail(f"input not found: {source}", code=2)
+
+    try:
+        import pdfplumber
+    except ImportError:
+        fail("pdfplumber is not installed; run the plugin postinstall again", code=2)
+
+    try:
+        pdf = pdfplumber.open(str(source))
+    except Exception as exc:
+        fail(f"cannot open PDF: {exc}", code=2)
+
+    with pdf:
+        page_count = len(pdf.pages)
+        selected = parse_pages(args.pages, page_count)
+        reports = []
+        warnings = []
+        joined = []
+        total_chars = 0
+        total_tables = 0
+        for index in selected:
+            page = pdf.pages[index - 1]
+            try:
+                text = page.extract_text(layout=args.layout) or ""
+            except Exception as exc:
+                fail(f"page {index} text extraction failed: {exc}", code=2)
+            report = {
+                "page": index,
+                "width_pt": round(float(page.width), 2),
+                "height_pt": round(float(page.height), 2),
+                "rotation": int(page.rotation or 0),
+                "chars": len(text),
+                "words": len(text.split()),
+                "text": text,
+                "tables": [],
+            }
+            if not args.no_tables:
+                try:
+                    tables = page.find_tables()
+                except Exception as exc:
+                    tables = []
+                    warnings.append(f"page {index}: table detection failed: {exc}")
+                for order, table in enumerate(tables, start=1):
+                    rows = [[clean(cell) for cell in row] for row in table.extract()]
+                    report["tables"].append(
+                        {
+                            "index": order,
+                            "bbox": [round(float(value), 2) for value in table.bbox],
+                            "row_count": len(rows),
+                            "column_count": max((len(row) for row in rows), default=0),
+                            "rows": rows,
+                        }
+                    )
+                total_tables += len(report["tables"])
+            if report["chars"] == 0 and len(page.images) > 0:
+                warnings.append(
+                    f"page {index} has images but no extractable text: it is probably a scan, "
+                    "and this runtime has no OCR"
+                )
+            total_chars += report["chars"]
+            joined.append(f"===== page {index} =====\n{text}")
+            reports.append(report)
+
+    if args.text_out:
+        try:
+            target = Path(args.text_out).expanduser()
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text("\n\n".join(joined).rstrip() + "\n", encoding="utf-8")
+        except OSError as exc:
+            fail(f"cannot write text output: {exc}", code=2)
+
+    emit(
+        {
+            "ok": True,
+            "input": str(source),
+            "page_count": page_count,
+            "pages_read": len(selected),
+            "text_out": str(Path(args.text_out).expanduser()) if args.text_out else None,
+            "total_chars": total_chars,
+            "total_tables": total_tables,
+            "pages": reports,
+            "warnings": warnings,
+        },
+        args.json_out,
+    )
+
+
+if __name__ == "__main__":
+    main()