dsh-office-kit 0.4.2 → 0.4.3

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

@@ -6,19 +6,19 @@
 "<python>" "<cli>" status
 ```
 
-Look at `renderers.kit` and `renderers.can_render`. `can_render.docx: false` means `docx render` will fail — not with a corrupt file, but with `the LibreOffice renderer is not available`. That is a setup problem, not a document problem.
+Check `renderers.kit` and `renderers.can_render`. `can_render.docx: false` means `docx render` fails with `the LibreOffice renderer is not available` — a setup problem, not a document problem.
 
 ## What renders
 
-Rendering goes through the LibreOffice kit that DeepSeek Harness ships (`@deepseek-ai/libreoffice-kit`). On macOS and Windows it uses the kit's native engine; on Linux it uses the WASM engine. A separately installed Microsoft Office, WPS Office, or system LibreOffice is **not** used and does not make rendering work on its own.
+Rendering goes through the LibreOffice kit DeepSeek Harness ships (`@deepseek-ai/libreoffice-kit`): the kit's native engine on macOS and Windows, the WASM engine on Linux. A separately installed Microsoft Office, WPS Office or system LibreOffice is **not** used and does not make rendering work.
 
 The plugin records the kit's location when the harness loads it, and the helper reads that record before anything else:
 
 1. `DSH_LIBREOFFICE_KIT_CLI` — an explicit override, also handy for a hand-run helper.
-2. `libreofficeKit` in `~/.dsh/office/config.json`. The host half writes this at load, resolving the kit from the harness entry point (`process.argv[1]`, e.g. `<dsh>/node_modules/@deepseek-ai/dsh/lib/bin.js`). This is what makes a profile install work, where the kit lives in the harness tree and not next to the plugin. Configs that pre-0.5 versions wrote in the OS config directory are still read as fallbacks.
+2. `libreofficeKit` in `~/.dsh/office/config.json`. The host half writes it at load, resolving the kit from the harness entry point (`process.argv[1]`, e.g. `<dsh>/node_modules/@deepseek-ai/dsh/lib/bin.js`). This is what makes a profile install work, where the kit lives in the harness tree rather than next to the plugin. Configs that pre-0.5 versions wrote in the OS config directory are still read as fallbacks.
 3. Walking up from the plugin directory through `node_modules/@deepseek-ai/libreoffice-kit/lib/cli.js` — covers a checkout or a plugin-local dependency.
 
-`DSH_OFFICE_CONFIG` points the helper at a different config file; `DSH_NODE` overrides the node binary if `node` is not on `PATH`.
+`DSH_OFFICE_CONFIG` points the helper at a different config file; `DSH_NODE` overrides the node binary when `node` is not on `PATH`.
 
 ## Common failures
 
@@ -33,7 +33,7 @@ The plugin records the kit's location when the harness loads it, and the helper
 
 ## 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:
+Structure, text and metadata are 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.
@@ -43,4 +43,4 @@ 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.
+Render into a fresh temp directory each time (`--out-dir`). A stale PNG from an earlier run reads as a pass — the most common false confirmation.

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

@@ -1,35 +1,35 @@
 # 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.
+A twenty-section document is not one command. Bounded steps keep each change verifiable and stop one failure 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.
+2. **Skeleton** — the file with the outline only: heading blocks, no body text.
+3. **Content, in batches** — one batch per top-level section, appended with `append_blocks.py`.
+4. **Numbers** — captions, cross-references and 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.
+- Captions and TOC are fields over structure; running them after every batch means renumbering noise and a TOC pointing at deleted headings.
+- A one-section batch is small enough to redo when the layout is wrong.
+- The skeleton proves the hierarchy before the text makes changing it expensive.
 
 ## 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.
+- 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 the section files in order, so merging is 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.
+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, and keep that 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.
+- Long sessions lose the document design. Keep the plan and the design defaults (page size, font sizes, table borders) in a workspace file and re-read it instead of trusting recollection.
+- When the user changes a decision mid-job (page size, heading style), record it where they said it and apply it to batches already written.
 
 ## Smoke test after the join
 

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

@@ -1,26 +1,30 @@
 ---
-description: Create, inspect, edit, redact, stamp, and render PDF files with the bundled Office helper CLI and self-contained Python scripts.
+description: Create, extract, fill forms in, merge, split, redact, stamp, render, and verify PDF files with the bundled Office helper CLI and Python scripts.
 ---
 
 # PDF
 
-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.
+A PDF page is a content stream of text and path operators behind a page box. Every job here reads that stream (PyMuPDF, pdfplumber, pypdf), writes a new one (reportlab), or rasterises it to check the result. Inspect first, make the smallest change that satisfies the request, then prove it on a render.
 
-| 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` |
+| User job | Fast path |
+| --- | --- |
+| Look at a page, crop, or measure geometry | `scripts/render_pages.py`, `pdf render` |
+| Extract text, tables, or page images | `scripts/extract_text.py`, `pdf read`, `tasks/read.md` |
+| Inspect or fill an AcroForm | `scripts/forms.py`, `tasks/forms.md` |
+| Remove a region (redaction) | `scripts/redact_region.py`, `tasks/redact.md` |
+| Read or rewrite metadata (info dictionary only, never page content) | `scripts/metadata.py`, `tasks/edit-pages.md` |
+| Merge, split, reorder, rotate, delete pages | `scripts/page_ops.py`, `scripts/split_pages.py`, `tasks/edit-pages.md` |
+| Stamp a footer, header, or label | `scripts/stamp_overlay.py`, `tasks/stamp.md` |
+| Build a new document | `pdf create`, `tasks/create.md` |
+| Resolve an `office-annotations` region | `tasks/annotations.md` |
+| Decide what a PDF cannot do | `references/limits.md` |
+
+Each task file explains the mechanism before giving the command. `references/geometry.md` covers page boxes and normalised regions, `references/layout-quality.md` is the pre-delivery visual checklist, and `references/form-fields.md` covers field flags, appearance streams, and flattening.
 
 ## Before any file work
 
 1. Call the `office_status` tool.
-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"`.
+2. Read the runtime block appended to this file at runtime; 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.
 
 Scripts under `"<skill>/scripts/"` are standalone argparse CLIs. Run `<python> <script> --help` before using one you have not called in this session.
@@ -29,49 +33,45 @@ Scripts under `"<skill>/scripts/"` are standalone argparse CLIs. Run `<python> <
 
 Decide the route before you type a command. Every route ends in the same render check.
 
-- **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.
+- **No file yet** → create it from a `pdf create` spec, or with reportlab when the layout does not fit the block model (`tasks/create.md`).
+- **Existing file to change** → read it first (`pdf read`, plus a render), then mutate it with the script its task file names. The CLI has no edit verb: it creates, reads, renders, and reports status only, so every change is a `scripts/*.py` call.
+- **A script covers the job** → run it, then check its JSON report and its rendered pages. A refused overwrite or a failed self-check exits non-zero: that is a hard stop.
 - **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.
+- **Neither covers it** → run or adapt the snippet in the matching `tasks/*.md` file. Do not invent a CLI verb, and do not call the job impossible because no verb exists.
+- **Take the smallest operation**: metadata change before rebuild, page move before re-creation, one-line patch before re-typing the page.
 
 ## Failure handling
 
 | 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. |
-| `the LibreOffice renderer is not available` | Media conversion for docx/pptx/xlsx is unavailable because the DSH LibreOffice kit was not found | PDF rendering still works (PyMuPDF); for a PDF this is harmless. For other formats report that appearance could not be checked. |
+| `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. |
 | `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. |
+| `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 the widget's appearance stream. |
+| `chars: 0` on a page that shows text | Scanned page, no text layer | Say so; follow `references/limits.md`. Never 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 is usually a cover-up, not an edit. |
+
+General CLI failures, missing runtimes, and the `the LibreOffice renderer is not available` result are covered by `"<shared>/common-workflow.md"`; `pdf render` never needs LibreOffice.
 
 ## Quality rules
 
-- 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.
+- One heading scale, one body size, one margin system per document (`references/layout-quality.md`).
+- Prove every structural change on a render of the changed page, not 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.
+- Never claim redaction while the words are still extractable.
+- Mark deliberate shortcuts (a rebuild instead of a reflow, a stamped patch instead of a content edit) in the reply.
 
 ## Delivery
 
-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.
+Hand the finished file to the user with the `present` tool, then one sentence on what changed. A bare path is not delivery: the transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动", so the user cannot open them.
 
 - 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.
+An `office-annotations` reply is a change request, not editor state: `[{ 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. Locate what the region covers, apply the smallest edit that satisfies `requirement`, re-render, confirm the region looks right, and say what you could not locate rather than guessing.
 
-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"`.
+For PDF, `page` is the 1-based page of the file, and `region × page.rect` is the real rectangle: convert once with PyMuPDF and work in the device rect; `text` wins over the region when they disagree, and `imageName`, when present, is a screenshot of the marked area to open with `read_image`. Full recipe: `tasks/annotations.md`, payload shapes: `"<shared>/annotation-recipes.md"`.
 
 ## Verify
 
@@ -81,22 +81,7 @@ Render before you present, and again after every fix:
 "<python>" "<cli>" pdf render --input "<file.pdf>" --out-dir "<render-dir>" --dpi 110
 ```
 
-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.
+Open each PNG with `read_image` and compare it with the pre-change render, working through `references/layout-quality.md`. Then run `"<python>" "<cli>" pdf read --input "<file.pdf>"` and confirm the text, page count, and form fields match your edit. Two or three passes are normal; past three, say what still looks wrong instead of calling it fixed.
 
 ## Shared workflow
 

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

@@ -4,39 +4,39 @@
 
 `/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.
+- `/T` — partial name; the full name joins ancestor partial names with dots.
+- `/FT` — type, inherited: `Tx` text, `Btn` button, `Ch` choice, `Sig` signature.
+- `/V` — current value: a string for text; the selected state name (`/Yes`, `/Off`, `/basic`) for buttons; a string or array for choice fields; a dictionary for signatures.
+- `/Ff` — inherited flags bitmask: bit 1 (`1`) read-only, bit 2 (`2`) required, bit 13 (`4096`) multiselect, bits 15–17 (`65536`/`131072`/`262144`) button behaviour (no-toggle, radio, pushbutton).
+- `/DA` — default appearance string; 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.
+- `/Rect`, `/P`, `/AS` — widget geometry, owning page, and the state the widget shows.
+- `/NeedAppearances` in `/AcroForm` — asks viewers to regenerate appearances; many 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.
+1. Field `/V` equals the requested value in the field's representation (boolean → state name, radio → that button's on-state, choice → string or list).
+2. The widget's `/AP /N` exists as a stream or state map with a `/BBox` and `/Resources`, and its 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 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.
+Updating `/V` alone satisfies 1 and fails 2–4 — the "filled but blank" failure. Rebuilding the appearance with a stale `/AS` satisfies 1–3 and shows two selected radios. Check 1–3 after saving, then render for 4.
 
-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`.
+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 in `tasks/forms.md`.
 
 ## Flattening
 
-Two meanings, both destructive in different ways:
+Two destructive meanings:
 
 - `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.
+- Post-process: remove `/Widget` annotations with `writer.remove_annotations(subtypes="/Widget")` and pop `/AcroForm` from the catalog. On its own this leaves the appearance, 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.
+Do both for a non-editable form. Verify zero `/Widget` annotations, no `/AcroForm` in the catalog, and the values still rendered.
 
 ## Appearance streams
 
-An appearance stream is a form XObject.
+An appearance stream is a form XObject:
 
 ```
 /Type /XObject
@@ -45,12 +45,12 @@ An appearance stream is a form XObject.
 /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.
+`/BBox` is the drawing area in the widget's own coordinates; the widget's `/Rect` maps it 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 appearance is missing, draw a replacement with reportlab at `/Rect` coordinates and merge it into the page — 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.
+`/FT /Sig` needs a certificate and a signing implementation. Filling text into a signature field, or editing any page of a signed document, breaks the signature. Say so plainly and offer the unsigned rebuild; never 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.
+`/Opt` lists the allowed options; `/V` is the chosen value or values. Single-select takes a string, multi-select an array. A value outside `/Opt` renders blank — validate against `/Opt`, and report the allowed options when the requested value is missing.

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

@@ -1,24 +1,24 @@
 # 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.
+PDF units are points, 1/72 inch: A4 is 595 × 842, 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.
+- **CropBox** — the visible area, defaulting to MediaBox; viewers show 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.
+PyMuPDF's `page.rect` is the CropBox (MediaBox when no CropBox exists), with `x0, y0` normally 0 and `x1, y1` the width and height; pypdf exposes `.mediabox` and `.cropbox`. When moving content between documents, use the page's own box, never 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.
+The origin is the bottom-left of the page box, x right, y up. Rectangle-taking calls (`page.get_textbox(rect)`, `add_redact_annot`, `get_pixmap(clip=...)`) and word-box calls (`page.get_text("words")`, `search_for`) all use that system — a word's box is not a baseline, so a text redaction rect 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.
+reportlab's `drawString(x, y, text)` places a *baseline* measured from the bottom. Convert a top-down measurement: `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.
+`/Rotate` is a per-page multiple of 90 applied by viewers on top of the content. `page.rect` in PyMuPDF is the rotated (visible) geometry; `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, set the rotation back, and let the render prove it.
 
 ## Normalised regions
 
@@ -31,14 +31,14 @@ 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.
+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 show at once 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.
+A raster at `dpi` has `pixels = points * dpi / 72`; a 110 dpi A4 page is roughly 909 × 1287 pixels. A region drawn on a rendered image is a DPI-independent fraction, so you never need the pixel size to convert it. For 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_text("dict")` gives blocks → lines → spans, each span with `size` (points), `font`, `origin` (baseline point), and text. When redrawing a line, use the span measurements, not the bounding box: the box includes ascenders and descenders and changes 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.
+`page.get_textbox(rect)` returns the characters whose boxes intersect `rect`, in reading order — 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

@@ -1,41 +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".
+Run this list on the rendered pages before presenting a file: it separates "the command exited 0" from "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.
+- Page count matches the request; no stray blank page from a trailing `page_break` or an empty `showPage`.
+- Every page has the intended size and orientation — Letter pages inside an A4 merge show 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.
+- The page box is the CropBox the user expects; a crop that hides a footer is a bug.
 
 ## Text
 
-- Body size, leading, and font are consistent; a patched line that uses a different size or face is a visible patch job.
+- Body size, leading, and font are consistent; a patched line in another 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.
+- Non-Latin text renders as characters, not blanks — it needs a registered font with the right coverage.
+- Extracted text matches the visible text: `pdf read` 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.
+- A table split 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.
+- Charts and screenshots are legible at print size; text inside an image is not searchable, so keep the numbers in 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).
+- Page numbers are right 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.
+- Filled form values sit inside their widget boxes, are not clipped by the box border, and keep 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.
+`page.get_fonts(full=True)` lists embedded fonts; a subset font is fine for display and 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 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.
+Open the output one more time with the route the user will use: `"<python>" "<cli>" pdf read --input "<file>"`. It confirms the file parses, the page count, the metadata, and that text extracts. 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

@@ -1,58 +1,14 @@
 # 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.
+State the missing capability, what you can still deliver, and how the user resolves it. Never answer with a bare "unsupported".
+
+| Missing capability | Still possible | Resolution |
+| --- | --- | --- |
+| **Scanned pages with no text layer** — words are pixels only; `render_pages.py` reports `chars: 0` | Render, crop with `read_image`, transcribe; redact image pixels with `--images pixels`; rebuild the page from the transcription | The user supplies a text-based copy, or runs OCR where they have it — this runtime has no OCR engine |
+| **Encrypted or password-protected files** — pypdf/PyMuPDF need the password; every script here exits with "encrypted" and does no work | Nothing until the file opens | Ask the user to decrypt first, then re-run. Never write a password into a command line that will be logged. |
+| **Signing and certificates** — no certificate, signer, or signature field; editing a signed file invalidates its signature | Fill unsigned fields, rebuild the content, deliver unsigned — and say the signature is gone | Signing happens in a tool with a certificate, after the content is final |
+| **Paragraph-level re-editing** — no paragraph model; the content stream is positioned glyphs and paths | Replace a line or block in place (`tasks/annotations.md`), remove a block, stamp a note | Reflow means rebuilding from a spec with the corrected text — say it was rebuilt, not patched |
+| **Lexical repair of broken files** — a damaged xref may render in viewers but fail strict parsers; never emit an empty document | Report the parse error; ask the user to open and re-save in a reader (which repairs it), then re-run | Tell whichever tool produced the file about the corruption |
+| **Tagged PDF and accessibility remediation** — the structure tree can be read but not authored reliably; a visual edit adds no tags | Keep the visual result correct and say the file is untagged | Remediation needs an authoring tool that writes the structure tree |
+| **PDF/A and archival conformance** — font embedding, metadata schemas, and colour profiles are not validated here | Many PDF/A inputs survive a page-level edit and stay close, but claiming conformance would be a guess | Validate with a dedicated PDF/A checker before delivery |
+| **Creating or restructuring form fields** — pypdf fills existing fields; a new interactive field needs a correct `/AP` state map, far beyond a fill | Stamp labels and values at coordinates so the printed result looks filled | An authoring tool for interactive forms, or accept non-interactive output and say so |

package/assets/skills/office-pdf/tasks/annotations.md

@@ -1,6 +1,6 @@
 # Resolve an `office-annotations` region on a PDF
 
-`page` is the 1-based page of the file, and `region × page.rect` is the real rectangle in the page's coordinate system. Convert once; then everything you do — read, redact, stamp, fill — uses that rect.
+`page` is the 1-based page of the file, and `region × page.rect` is the real rectangle in the page's coordinate system. Convert once; then every operation — read, redact, stamp, fill — uses that rect.
 
 ## 1. Reproduce the page first
 
@@ -8,7 +8,7 @@
 "<python>" "<cli>" pdf render --input "<file.pdf>" --out-dir "<render>" --dpi 110
 ```
 
-Open `"<render>/page-<N>.png"` with `read_image`. The geometry is only meaningful against the page the user saw, so never resolve a region on a page you have not rendered.
+Open `"<render>/page-<N>.png"` with `read_image`. Geometry is only meaningful against the page the user saw, so never resolve a region on a page you have not rendered.
 
 ## 2. Convert the region and read what it covers
 
@@ -43,7 +43,7 @@ Compare the words with the annotation's `text`. If `text` is present and those w
 | A single word or sentence to change | redact the old line, then stamp the new text (below) |
 | A picture to replace | overlay a cover rect and draw the new image with reportlab |
 
-A requirement like "make this sentence shorter" is a content edit; do not rebuild the whole page for it when the block is one line.
+A requirement like "make this sentence shorter" is a content edit; do not rebuild the whole page when the block is one line.
 
 ## 4. Patch one line in place
 
@@ -91,8 +91,8 @@ Line height and font size must match the original text; read them from the origi
 
 ## 5. When the payload cannot be tied to an object
 
-Say which part you could not locate: the render page, the words you found under the region, and the item that is missing. Then ask for the text of the target or a clearer region. Genuinely blocked cases and their resolutions are in `references/limits.md` — name the missing capability and what the user can do about it, never a bare "unsupported".
+Say which part you could not locate — render page, the words found under the region, the missing item — and ask for the target text or a clearer region. Blocked cases are in `references/limits.md`: name the missing capability and the way out, never a bare "unsupported".
 
 ## 6. Re-render and confirm
 
-Apply the edit, render the same page, and `read_image` it again. The region must show the requested result, the neighbouring text must be untouched, and the layout must still hold. Then check extraction (`pdf read`) so the change is real in the text layer, not only in pixels. Report what you resolved back to the user in the same terms they annotated with: page number and a one-line description of the change.
+Apply the edit, render the same page, and `read_image` it again: the region must show the requested result, neighbouring text must be untouched, and the layout must hold. Then confirm with `pdf read` that the change is in the text layer, not only in pixels. Report in the user's own terms: page number plus a one-line description of the change.

package/assets/skills/office-pdf/tasks/create.md

@@ -1,7 +1,5 @@
 # Create a PDF
 
-A new PDF is a set of pages, each holding a content stream plus fonts and resources. Two routes exist here, and both end with the same verification.
-
 ## Fast path: the helper CLI spec
 
 ```bash
@@ -27,7 +25,7 @@ Blocks: `title`, `heading` (`level` 1–2), `paragraph`, `quote`, `bullets`, `nu
 
 ## Direct path: reportlab
 
-Reach for reportlab when the layout does not fit the block model — columns, absolute placement, custom rules, rotated text.
+Reach for reportlab when the layout does not fit the block model: columns, absolute placement, custom rules, rotated text.
 
 ```bash
 "<python>" - <<'PY'
@@ -50,26 +48,25 @@ c.save()
 PY
 ```
 
-`drawString` takes a baseline point measured from the bottom-left corner, not the top. Convert top-down coordinates once (for a page height `h`, baseline `y = h - top - font_size`), or every following measurement will drift.
+`drawString` takes a baseline point measured from the bottom-left corner, not the top. Convert top-down coordinates once (for a page height `h`, baseline `y = h - top - font_size`), or every later measurement drifts.
 
 ## Fonts
 
-Base-14 fonts (`Helvetica`, `Times-Roman`, `Courier`) need no embedding and cover Latin text. Non-Latin text needs a real font file registered with `pdfmetrics.registerFont(TTFont("Body", "<path>.ttf"))`; a font that cannot render a glyph produces a blank box in the output, which the render step will show. The CLI tries the first available CJK system font, and says so when none exists.
+Base-14 fonts (`Helvetica`, `Times-Roman`, `Courier`) need no embedding and cover Latin text. Non-Latin text needs a real font file registered with `pdfmetrics.registerFont(TTFont("Body", "<path>.ttf"))`; a font that cannot render a glyph produces a blank box, which the render step shows. The CLI tries the first available CJK system font and says so when none exists.
 
 ## Quality rules
 
-- One heading scale, one body size, one margin system per document.
 - Keep body text inside 12–16 pt leading; below 9 pt text becomes unreliable on print.
 - ASCII hyphens only in prose; do not paste typographic dashes into generated copy unless the source used them.
 - Give every page a consistent header/footer treatment, or none at all.
-- Do not put a table wider than the text column; wrap long cell text instead of letting it clip.
+- Full layout checklist: `references/layout-quality.md`.
 
 ## Verify
 
-Render and look at every page; a created PDF has no text layer surprises, so problems are layout problems: text past the margin, blocks overlapping, table columns squeezed, a `page_break` landing on an empty page, or a CJK line silently blank.
+Render every page: a created PDF has no text-layer surprises, so problems are layout problems — text past the margin, blocks overlapping, table columns squeezed, a `page_break` landing on an empty page, a CJK line silently blank.
 
 ```bash
 "<python>" "<cli>" pdf render --input "out.pdf" --out-dir "render" --dpi 110
 ```
 
-Then confirm the structure you intended with `"<python>" "<cli>" pdf read --input "out.pdf"` (page count and per-page text) before `present`.
+Then confirm the page count and per-page text with `"<python>" "<cli>" pdf read --input "out.pdf"` before `present`.