dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-documents/tasks/templates_style_packs.md

@@ -0,0 +1,53 @@
+# Templates and style packs
+
+**Goal.** Make a new or existing document look like the house template, without copying the template's content into it.
+
+A `.dotx` is a `.docx` whose package is a template: `styles.xml` defines the look, `numbering.xml` defines lists, and the body is empty. Copying the body would import placeholder text; what you actually need is the styles part, the numbering definitions they reference, and the theme.
+
+## Ask before guessing
+
+Do not invent a house style. Get from the user: heading fonts and sizes, body font and size, accent colour, margins, table style, and whether a logo or cover page is required. `references/template-elicitation.md` has the question set that produces a spec.
+
+## Apply a template
+
+```bash
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx>"
+```
+
+The script merges the template's style definitions by `styleId` (replacing same-id definitions, appending missing ones, taking the template's `docDefaults`), and copies `numbering.xml` with its relationship and content-type override. The target's body is untouched, so the content survives and the look changes.
+
+Then normalize so direct formatting does not override the template:
+
+```bash
+"<python>" "<skill>/scripts/style_normalize.py" "<draft-styled.docx>" --out "<draft-final.docx>" --clear_paragraph_format
+```
+
+## Restyle without a template
+
+When the user describes the style instead of supplying a file, set it on the styles rather than on runs:
+
+```bash
+"<python>" - <<'PY'
+from docx import Document
+from docx.shared import Pt, RGBColor
+d = Document(r"<draft.docx>")
+normal = d.styles["Normal"]
+normal.font.name = "Calibri"
+normal.font.size = Pt(11)
+for level, size in ((1, 18), (2, 14), (3, 12)):
+    style = d.styles[f"Heading {level}"]
+    style.font.size = Pt(size)
+    style.font.color.rgb = RGBColor(0, 0, 0)
+d.save(r"<draft-styled.docx>")
+PY
+```
+
+## Verify
+
+Render and compare against the template's own preview page by page: heading sizes, body leading, margins, table borders. A style page that looks right in a style list but wrong on the page usually means a direct-formatting run left over — run the lint.
+
+## Pitfalls
+
+- A template applied over content that references missing styles produces the fallback look, not an error; run `style_lint.py` to find undefined references.
+- Themes (`word/theme/theme1.xml`) carry fonts and accent colours; a style that names a theme font changes when the theme does.
+- Keeping the template's `numbering.xml` without its `abstractNum` ids produces lists that all share one counter.

package/assets/skills/office-documents/tasks/toc_workflow.md

@@ -0,0 +1,39 @@
+# Table of contents
+
+**Goal.** Put a navigable contents list at the front of the document, built from heading styles rather than typed by hand.
+
+The TOC is a `TOC` field. Word fills it in when it recalculates; the file stores the last result. A hand-typed list looks identical in a screenshot and then goes wrong on the first edit.
+
+## Insert
+
+```bash
+"<python>" "<skill>/scripts/insert_toc.py" "<file.docx>" --out "<file-toc.docx>" --levels 1-3
+```
+
+The script looks for a placeholder paragraph containing `[[TOC]]` (override with `--placeholder`). If there is none it inserts the field at the start of the body. It writes `TOC \o "1-3" \h \z \u`, sets `w:updateFields`, and adds a short cached hint so the page is not blank before recalculation.
+
+Check that every heading you want in the list uses a heading style: `heading_audit.py` finds headings formatted by hand, which the TOC will silently skip.
+
+## Rebuild after edits
+
+If headings changed, the cached list is stale. Either ask the user to update the field in Word (right-click → Update Field), or regenerate: strip the old field with `fields_materialize.py`? — no, that freezes it. Instead delete the field paragraphs and run `insert_toc.py` again. Freezing a TOC is almost never what a reader wants.
+
+## Static contents list
+
+Sometimes the requirement really is a fixed list — a PDF export that will not be recalculated, or a template with a hand-built contents page. `internal_nav.py` builds one: a heading plus hyperlink entries to every heading, with optional back-links.
+
+```bash
+"<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2
+```
+
+See `tasks/navigation_internal_links.md`.
+
+## Verify
+
+Render the first pages and read them. A TOC that shows one line of grey hint text means the field never recalculated in that renderer; a TOC that shows the old headings means the document was rendered before the field updated. Say which one happened instead of claiming the TOC is correct.
+
+## Pitfalls
+
+- TOC entries come from outline levels, not from text that merely looks like a heading.
+- A TOC inside a header or a text box does not work; it belongs in the body.
+- Level 4+ headings are excluded unless you widen `--levels`.

package/assets/skills/office-documents/tasks/verify_render.md

@@ -0,0 +1,50 @@
+# Visual verification
+
+**Goal.** See the pages before the user does. A document that parses and a document that looks right are different claims.
+
+## Render
+
+```bash
+"<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
+```
+
+Writes a PDF and one PNG per page, and prints their paths plus the renderer it used (Word via COM, or LibreOffice). Use the same command through `render_docx.py` when you want the JSON report and page list:
+
+```bash
+"<python>" "<skill>/render_docx.py" "<file.docx>" --output_dir "<render-dir>" --dpi 150
+```
+
+## Inspect
+
+Open every PNG with `read_image` and check, in this order:
+
+1. **Hierarchy** — does the page show the structure the user asked for, at a glance?
+2. **Fit** — nothing past the right margin, no clipped table column, no text over a watermark.
+3. **Breaks** — no heading alone at the bottom, no orphaned caption, no half-empty page before a section break.
+4. **Text** — the words that were meant to change did change, and nothing else moved.
+5. **Glyphs** — dashes, quotes, CJK, currency symbols and maths render, not as boxes.
+6. **Header and footer** — present, correct, not repeated on a first page that should not have it.
+
+## When no renderer exists
+
+The runtime reports `renderers.libreoffice: null` and no Office installation. `render` then exits non-zero with a JSON error naming the missing renderer, and `render_docx.py` exits 3 with `reason: no_renderer`.
+
+In that state:
+
+- Verify structure with `docx read`, `docx_kit.py parts|text|xml` and the audit scripts.
+- Tell the user plainly that layout was not visually verified, and offer to install Microsoft Office, WPS Office, or LibreOffice instead of describing a page you did not see.
+- Do not claim a file "looks good" from XML evidence alone.
+
+## After any script edit
+
+Re-render. Package-valid is not page-valid: a caption inserted before the paragraph it describes, a table grown past the margin, a style merge that changed heading sizes — all are invisible to the XML and obvious in the image.
+
+## Comparing revisions
+
+`render_and_diff.py` renders two files and writes a heatmapped difference page. Read the diff images yourself; a ratio is not a conclusion.
+
+## Pitfalls
+
+- Different renderers paginate differently. Compare like with like, and do not promise Word-perfect pagination from a LibreOffice render.
+- A render fails silently into a blank page when a font is missing; a blank page is a finding, not a rendering bug.
+- Render into a fresh directory; stale PNGs from an earlier run are the classic false pass.

package/assets/skills/office-documents/tasks/watermarks_background.md

@@ -0,0 +1,35 @@
+# Watermarks and background text
+
+**Goal.** A diagonal DRAFT / CONFIDENTIAL mark behind the page content, and the ability to find and remove one that a template left behind.
+
+A Word watermark is not a document feature with its own element: it is a VML shape (`v:shape` with `v:textpath`) in a header part, positioned behind the text. That is why it disappears if the header is replaced, and why it can appear on some pages and not others when sections have their own headers.
+
+## Add
+
+```bash
+"<python>" "<skill>/scripts/watermark_add.py" "<file.docx>" --out "<file-draft.docx>" --text "DRAFT"
+```
+
+Writes the shape into the default header, light grey, rotated -45°, behind the body. The script refuses to add a second watermark when it finds one — remove the old one first, or you get two overlapping marks.
+
+For a per-page mark across a document with several sections, each section's header needs the shape; that is a loop over sections, not one insertion.
+
+## Find and remove
+
+```bash
+"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode report
+"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode remove --out "<file-clean.docx>"
+```
+
+The report lists the text of every VML text path and the part it lives in, and exits 1 when any watermark exists. `--contains` narrows to a substring, which is the case "the template says Company Confidential and it should not". Remove deletes the enclosing paragraph from the header.
+
+## Verify
+
+Render and read the pages: the mark sits behind the text (not over it), stays inside the page, and appears on every page the user expects. A watermark that vanishes on page two means that section has a different header.
+
+## Pitfalls
+
+- A watermark in a "different first page" header only shows on page one.
+- Removing the header paragraph can leave an empty header that adds vertical space; check the top margin on the rendered page.
+- An image watermark is an `v:imagedata` shape, not a text path — the report will not name it, so inspect the header XML when the visual mark is a logo.
+- Watermarks are not security. See `tasks/protection_restrict_editing.md` for what actually restricts editing.

package/assets/skills/office-documents/troubleshooting/libreoffice_headless.md

@@ -0,0 +1,47 @@
+# Rendering setup and failures
+
+## First: does this machine render
+
+```bash
+"<python>" "<cli>" status
+```
+
+Look at `renderers.libreoffice` and `microsoft_office`. Both null means `docx render` will fail — not with a corrupt file, but with `no document renderer found`. That is a setup problem, not a document problem.
+
+## LibreOffice
+
+Install LibreOffice (Windows: winget `TheDocumentFoundation.LibreOffice`), then check:
+
+```bash
+soffice --headless --version
+```
+
+If the binary is not on `PATH`, the runtime cannot find it; either add its `program` directory to `PATH` or install into the default location the runtime probes. On Windows, `soffice.com` is the console wrapper — use that one, not `soffice.exe`, when a script needs to wait for exit.
+
+## Microsoft Office
+
+When Word is installed, the CLI can drive it through COM and does not need LibreOffice. Office must be activated and able to launch without a first-run dialog; a pending activation or a modal "sign in" blocks the render forever.
+
+## Common failures
+
+| Message | Cause | Fix |
+|---|---|---|
+| `no document renderer found` | Neither installed / not on PATH | Install one, re-check `status` |
+| Render hangs | A dialog is waiting in the headless process | Kill the leftover process, add the `--headless --norestore` flags the CLI uses |
+| Blank pages | Missing font | Install the font or substitute it |
+| Text shifted | Font substitution | Compare with a render from the same renderer the user will use |
+| `soffice already running` | A user profile lock from a crashed run | Remove the stale lock file under the LibreOffice user profile, or wait for the old process to exit |
+
+## Working without a renderer
+
+Structure, text and metadata are all verifiable headlessly (`docx read`, the audit scripts, `docx_kit.py parts|text|xml`). Layout is not. In that state:
+
+1. Do the structural verification.
+2. Tell the user that page layout was not visually checked, and why.
+3. Offer the install, or ask them to open the file and say what looks wrong.
+
+Never describe a page you did not render.
+
+## Keep renders disposable
+
+Render into a fresh temp directory each time (`--out-dir`). A stale PNG from a previous run reads as a pass and is the most common false confirmation.

package/assets/skills/office-documents/troubleshooting/run_splitting.md

@@ -0,0 +1,36 @@
+# Splitting a long job
+
+A twenty-section document is not one command. Splitting it into bounded steps keeps each change verifiable and stops one failure from hiding inside a large edit.
+
+## One step per structural change
+
+1. **Plan** — the outline (headings and what each section must establish), written down before any file work.
+2. **Skeleton** — create the file with the outline only: heading blocks, no body text.
+3. **Content, in batches** — a batch per top-level section, appended with `append_blocks.py`.
+4. **Numbers** — captions, cross-references, TOC once the structure is final, never while sections are still moving.
+5. **Verify** — render, inspect, fix.
+
+## Why this order
+
+- Captions and TOC are fields over structure; running them after every batch means renumbering noise and a TOC that points at deleted headings.
+- A batch of one section is small enough to redo when the layout is wrong.
+- The skeleton proves the heading hierarchy before the text makes it expensive to change.
+
+## Batch boundaries
+
+- One section per file: `section-01.docx`, `section-02.docx`, then `merge_docx_append.py`. This is the only sane way to draft in parallel or across sessions.
+- Keep a `manifest.json` listing section files in order. Merging is then mechanical and the order is not remembered from chat.
+- Merge before numbering, not after.
+
+## When a batch fails
+
+Do not patch a large edit inside a large document. Discard the failed batch's output, fix the batch, re-apply it to the previous good file. Keep the previous good file until the batch is verified.
+
+## Context hygiene
+
+- Long sessions lose the document design. Keep the plan and the design defaults (page size, font sizes, table borders) in a file in the workspace and re-read it, rather than trusting recollection.
+- When the user changes a decision mid-job (page size, heading style), record it at the point they said it, and apply it to batches already written.
+
+## Smoke test after the join
+
+`examples/end_to_end_smoke_test.md` is the checklist to run on the merged file before it becomes a deliverable.

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.