dsh-office-kit 0.4.1 → 0.4.3

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`.

package/assets/skills/office-pdf/tasks/edit-pages.md

@@ -1,6 +1,6 @@
 # Merge, split, reorder, rotate, delete pages
 
-Pages are objects referenced from a page tree; changing the order or removing a page changes references, not content. Nothing is re-flowed, so a page moved into a document with a different page size keeps its own box and fonts.
+Pages are referenced from a page tree; reordering or removing one changes references, not content. Nothing is re-flowed, so a page moved into a differently sized document keeps its own box and fonts.
 
 ## Fast path: `scripts/page_ops.py`
 
@@ -9,14 +9,14 @@ Pages are objects referenced from a page tree; changing the order or removing a
   --rotate 90 --pages 0,2 --remove 3 --merge "<other.pdf>" --order 2,0,1
 ```
 
-- Operations run in a fixed order: merge, then order, then remove, then rotate — a command means the same thing every time.
-- Every index is zero-based and addresses the combined page list (input pages first, appended pages after).
-- `--order` keeps and reorders; pages it does not list are dropped, which also makes it the duplicate/select tool when you repeat an index.
-- `--remove` drops indices from the list left by `--order`.
+- Fixed operation order: merge, then order, then remove, then rotate — a command always means the same thing.
+- Indices are zero-based over the combined page list (input pages first, appended pages after).
+- `--order` keeps and reorders; unlisted pages are dropped, and a repeated index duplicates it.
+- `--remove` drops indices from the list `--order` leaves.
 - `--rotate` takes 90, 180, or 270 clockwise and defaults to every remaining page; `--pages` limits it.
 - `--out` defaults to `<input>-edited.pdf`; the input is never overwritten.
 
-The script carries page content streams over as they are and reopens the result to report page count, rotation, and page size per page. When one call cannot express the operation, chain two calls into two output files rather than reusing a name.
+The script carries content streams over unchanged and reopens the result to report page count, rotation, and page size per page. When one call cannot express the operation, chain two calls into two output files rather than reusing a name.
 
 ## Metadata
 
@@ -24,7 +24,7 @@ The script carries page content streams over as they are and reopens the result
 "<python>" "<skill>/scripts/metadata.py" --input "<file.pdf>" --set "/Title=Field report" --set "/Author=Ada" --out "<file-edited.pdf>"
 ```
 
-Keys are the document information fields (`Title`, `Author`, `Subject`, `Keywords`, `Creator`, `Producer`, `CreationDate`, `ModDate`), plain or `/Name`, in any case. The script writes a new file and reopens it, so `applied` and `not_applied` tell you what actually persisted.
+Keys are the document information fields (`Title`, `Author`, `Subject`, `Keywords`, `Creator`, `Producer`, `CreationDate`, `ModDate`), plain or `/Name`, in any case. The script writes a new file and reopens it; `applied`/`not_applied` show what persisted.
 
 ## Split
 
@@ -32,7 +32,7 @@ Keys are the document information fields (`Title`, `Author`, `Subject`, `Keyword
 "<python>" "<skill>/scripts/split_pages.py" --input "<file.pdf>" --out-dir "<parts>" --ranges "1-2,3,5-"
 ```
 
-1-based inclusive ranges, `--every N` for equal chunks, default one file per page. The script copies the source metadata, refuses overlapping or out-of-range ranges, and fails if the parts do not add up to the source page count — that check is what catches a typo in the range string. `--prefix` sets the filename stem.
+1-based inclusive ranges, or `--every N` for equal chunks; the default is one file per page. The script copies the source metadata, refuses overlapping or out-of-range ranges, and fails when the parts do not add up to the source page count — the check that catches a typo in the range string. `--prefix` sets the filename stem.
 
 ## Direct page-tree work
 
@@ -53,19 +53,19 @@ print("pages", len(writer.pages))
 PY
 ```
 
-`add_page` copies the page and its resources into the new file; annotations that point across pages (links) can break when their target is removed. After a reorder or deletion, check the links and bookmarks on the render, not only the text.
+`add_page` copies the page and its resources; annotations pointing across pages (links) can break when their target is removed. After a reorder or deletion, check links and bookmarks on the render, not only the text.
 
 ## Rotate
 
-Page rotation is a `/Rotate` entry (multiples of 90) applied by viewers; it does not transpose the content stream. `page.rotate(90)` in pypdf, or `page_ops.py --rotate 90 --pages ...`, is enough. If a page was scanned sideways and also carries a stale `/Rotate`, the two add up — the render shows whether you are looking at the wrong one, and `scripts/render_pages.py` reports each page's rotation.
+Page `/Rotate` (multiples of 90) is applied by viewers and does not transpose the content stream. `page.rotate(90)` in pypdf, or `page_ops.py --rotate 90 --pages ...`, is enough. A page scanned sideways that also carries a stale `/Rotate` accumulates both — the render shows which one you are looking at, and `scripts/render_pages.py` reports each page's rotation.
 
 ## Verify
 
 After any structural edit:
 
 - compare page counts (`pdf read` or the split report) — one missing page is easy to miss in a long render;
-- render at least the first and last page of every part, and every page you rotated or reordered;
-- for merges, confirm the page size and orientation of the appended pages did not change, and that page numbers or bates stamps do not collide;
-- for deletions of numbered pages, tell the user which numbers were removed, because the remaining page labels will shift.
+- render the first and last page of every part, plus every page you rotated or reordered;
+- for merges, confirm appended pages kept their size and orientation, and that page numbers or bates stamps do not collide;
+- for deletions of numbered pages, tell the user which numbers were removed, because the remaining page labels shift.
 
-`scripts/render_pages.py --input "<file.pdf>" --region 0,0,1,1 --json-out ...` prints per-page character and drawing counts, which is a cheap way to confirm a page is not blank before you deliver.
+`scripts/render_pages.py --input "<file.pdf>" --region 0,0,1,1 --json-out ...` prints per-page character and drawing counts — a cheap blank-page check before delivery.

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

@@ -1,6 +1,6 @@
 # AcroForm inspection and filling
 
-A form PDF carries `/AcroForm` in the catalog. Its `/Fields` array holds field dictionaries: `/T` the partial name, `/FT` the type (`Tx` text, `Btn` button, `Ch` choice, `Sig` signature), `/V` the value, `/Ff` flags, `/DA` the default appearance, and `/AP` appearance streams. A widget is the field's visual rectangle (`/Rect`, `/P` parent page, `/AS` its currently selected state name). A field can own several widgets (radio groups), and a widget can be a separate object from its field, reached through `/Parent`. Text in a filled field is usually not in the page content stream — it lives in the widget's `/AP /N` appearance, which is why "the value is in `/V`" and "the page shows the value" are two different facts to check.
+A form PDF carries `/AcroForm` in the catalog. `/Fields` holds field dictionaries: `/T` name, `/FT` type, `/V` value, `/Ff` flags, `/DA` default appearance, `/AP` appearance stream. Widgets carry `/Rect`, `/P`, `/AS`, and a widget can be a separate object reached through `/Parent`. Full field mechanics: `references/form-fields.md`. Text in a filled field usually lives in the widget's `/AP /N`, not the page content stream, so "value in `/V`" and "page shows the value" are two different facts.
 
 ## Inspect first
 
@@ -8,7 +8,7 @@ A form PDF carries `/AcroForm` in the catalog. Its `/Fields` array holds field d
 "<python>" "<skill>/scripts/forms.py" inspect --input "<file.pdf>"
 ```
 
-Reports, per field: id/name, type, value, read-only/required, widget count, page numbers, current states for buttons, and whether each widget has an `/AP` stream. Read the whole report before touching values: duplicate names, missing appearance streams, and read-only flags are the usual reason a fill "does nothing".
+Reports per field: name, type, value, read-only/required, widget count, pages, button states, and whether each widget has `/AP`. Read it all before touching values: duplicate names, missing appearances, and read-only flags are why a fill "does nothing".
 
 ## Fill
 
@@ -20,20 +20,20 @@ Reports, per field: id/name, type, value, read-only/required, widget count, page
 { "full_name": "Ada Lovelace", "email": "ada@example.org", "agree": true, "plan": "/basic" }
 ```
 
-Text fields take strings, checkboxes take booleans or the state name, radio groups take the state you want selected, choice fields take a string or list. The dictionary is keyed by field name (`/T`, nested names joined with dots). The script fails with a non-zero exit when a name does not exist instead of silently skipping it, when a value is not one of the allowed states, and when the saved file fails the verification below. Pass `--flatten` to bake the values into the page and drop the form.
+Text fields take strings; checkboxes booleans or the state name; radio groups the state to select; choice fields a string or list. Keys are field names (`/T`, nested names joined with dots). `--flatten` bakes the values in and drops the form. The script exits non-zero on an unknown name (it never skips silently), a value outside the allowed states, or a saved file that fails the verification below.
 
 ## The discipline that makes a fill real
 
-pypdf writes `/V` and rebuilds the widget appearance. Both must be re-checked after saving, because a writer can update one and not the other:
+pypdf writes `/V` and rebuilds the widget appearance; a writer can do one without the other, so check both after saving.
 
 1. Reopen the saved file.
-2. For every field you set, read `/V` from the field dictionary and compare it with the requested value.
-3. For every widget, confirm `/AP /N` exists and is a non-empty stream with a `/BBox`; for radio and checkbox groups, confirm `/AS` names a state that exists in `/AP /N`.
+2. Read `/V` for every field you set and compare it with the requested value.
+3. Confirm every widget has a non-empty `/AP /N` stream with a `/BBox`; for radio and checkbox groups, `/AS` must name a state present in `/AP /N`.
 4. Render the page and look at the field.
 
-Steps 1–3 catch a stale or missing appearance; step 4 catches a `/V` that is right while the page still shows the old text. The script does 1–3 itself and prints `applied`/`not_applied`; treat `not_applied` as a failure to fix, never as a warning.
+Steps 1–3 catch a stale or missing appearance; step 4 catches a right `/V` over old text. The script does 1–3 and prints `applied`/`not_applied`; `not_applied` is a failure to fix, not a warning.
 
-When you build the check by hand:
+By hand:
 
 ```bash
 "<python>" - <<'PY'
@@ -49,19 +49,19 @@ for name, field in fields.items():
 PY
 ```
 
-Radio groups are the common failure: pypdf updates the group `/V`, but the widget-level `/AS` for the previously selected button can stay behind, so two buttons look selected. The script resynchronises every widget's `/AS` from the group value; if you fill by hand, do the same.
+Radio groups fail most: pypdf updates the group `/V` but leaves the old button's `/AS`, so two look selected. The script resyncs every widget's `/AS` from the group value; do the same by hand.
 
 ## Flatten
 
-Flattening is for files that must no longer be editable. Update with `flatten=True` (the value is painted into the page content), then remove every widget annotation (`subtypes="/Widget"`) and drop `/AcroForm` from the catalog. Verify afterwards: no `/Widget` annotations remain and the catalog has no `/AcroForm`. If widgets remain, the file still looks editable in readers even though the content carries the value.
+Flatten when the file must stay uneditable: fill with `flatten=True` (the value is painted into page content), remove every widget annotation (`subtypes="/Widget"`), and drop `/AcroForm` from the catalog. Then confirm no `/Widget` and no `/AcroForm` remain; otherwise readers still treat the file as editable.
 
 ## What cannot be filled, and the fix
 
-- **A field with no appearance stream and a broken `/DA`**: the reader may refuse to show a new value. Render after filling; if the value is invisible, rebuild that widget's appearance with reportlab and merge it over the page.
-- **A signature field (`/FT /Sig`)**: signing requires a certificate and a signer implementation that this runtime does not ship. Adding text to a signed field invalidates the signature. Tell the user the signature cannot be created here and what would (a certificate plus a signing tool).
-- **A form where the values are drawn as static text, not widgets**: the file is not a form. Inspect with `page.get_text()` — if the labels and lines are plain content and `reader.get_fields()` is empty, treat it as an edit job, not a fill job.
-- **A flat, scanned form**: no field tree exists; filling means drawing text at coordinates (a stamp overlay) and the render decides whether it lines up.
+- **No appearance stream and a broken `/DA`**: the reader may not show a new value. Render after filling; if invisible, rebuild that widget's appearance with reportlab and merge it over the page.
+- **A signature field (`/FT /Sig`)**: needs a certificate and a signer this runtime does not ship, and text on a signed field invalidates the signature. Say it cannot be created here; it needs a certificate plus a signing tool.
+- **Values drawn as static text**: not a form. If `page.get_text()` shows the labels and lines and `reader.get_fields()` is empty, treat it as an edit job.
+- **A flat, scanned form**: no field tree; draw text at coordinates (a stamp overlay) and let the render decide whether it lines up.
 
 ## Verify
 
-Always: reopen, check `/V`, check `/AP`, then `"<python>" "<cli>" pdf render --input "<file-filled.pdf>" --out-dir "render"` and `read_image` the page. The filled value must be visible inside its widget box, without clipping or overlapping the box border.
+Reopen, check `/V`, check `/AP`, then `"<python>" "<cli>" pdf render --input "<file-filled.pdf>" --out-dir "render"` and `read_image`. The value must be visible inside its widget box, not clipped or over the border.

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

@@ -1,6 +1,6 @@
 # Read text, tables, and page images
 
-Text extraction reads the page content stream: glyph runs carry position and a font, and a library groups them into words and lines. A page with no text operators (a scan or a photo export) yields nothing no matter which extractor is used — that is a property of the file, not of the tool.
+Extraction reads the page content stream; glyph runs carry position and font, which a library groups into words and lines. A page without text operators (a scan, a photo export) yields nothing, whatever the extractor — a property of the file, not of the tool.
 
 ## Fast path: plain text and structure
 
@@ -16,7 +16,7 @@ Returns `page_count`, `word_count`, document metadata, per-page text (with chara
 "<python>" "<skill>/scripts/extract_text.py" --input "<file.pdf>" --json-out "<tables.json>"
 ```
 
-Each page reports its characters and detected tables as rows of cell strings. The detection uses the page's ruling lines and word spacing, so a borderless table often comes back as running text; `--layout` keeps the spacing of the original lines for a manual look.
+Detection uses the page's ruling lines and word spacing, so a borderless table often comes back as running text; `--layout` keeps the original line spacing for a manual look.
 
 When the detection looks wrong, inspect rather than guess:
 
@@ -32,11 +32,11 @@ with pdfplumber.open("in.pdf") as pdf:
 PY
 ```
 
-`chars`, `lines`, and `rects` tell you whether the table has rules at all. A table with no lines is best read from `extract_text` with `--layout`, where the column gaps survive as spaces.
+`chars`, `lines`, and `rects` tell you whether the table has rules at all. With no lines, read it from `extract_text` with `--layout`, where column gaps survive as spaces.
 
 ## Page images
 
-A page may contain embedded rasters that are invisible in text extraction. List them with PyMuPDF:
+A page may embed rasters that text extraction does not show. List them with PyMuPDF:
 
 ```bash
 "<python>" - <<'PY'
@@ -48,15 +48,15 @@ for number, page in enumerate(doc, 1):
 PY
 ```
 
-Extract one with `page.get_pixmap(clip=...)` or `doc.extract_image(xref)` when the user needs the picture itself. Rendering the page at 150–200 dpi and cropping with `read_image` is the reliable way to *see* it.
+Extract one with `page.get_pixmap(clip=...)` or `doc.extract_image(xref)` when the user needs the picture itself. To *see* it, render the page at 150–200 dpi and crop with `read_image`.
 
 ## What fails and how to resolve it
 
-- **Scanned page, no text**: there is no text layer to read. Say so; the render shows the image of the words. Resolutions: work from a text-based copy of the file, or read the pages visually and type the content into a rebuild. Do not claim extraction succeeded on an empty result.
-- **Empty string from a page that shows text**: the page may use a font with a broken ToUnicode map, or the text may be drawn as vector outlines. Check the render before concluding; if it is outlines, extraction cannot recover the words.
-- **Wrong reading order in multi-column layouts**: raw extraction follows the operator order. Crop each column with a rect and extract per column, `get_textbox(rect)` on a PyMuPDF page is the simplest split.
+- **Scanned page, no text**: no text layer exists; say so, with resolutions from `references/limits.md`. Never claim extraction succeeded on an empty result.
+- **Empty string from a page that shows text**: broken ToUnicode map, or text drawn as vector outlines. Check the render; outlines cannot be recovered by extraction.
+- **Wrong reading order in multi-column layouts**: extraction follows operator order. Crop each column with a rect and extract per column; `get_textbox(rect)` on a PyMuPDF page is the simplest split.
 - **Ligatures and soft hyphens**: extraction may glue or split words; quote extracted text only after reading the same passage on the render.
 
 ## Verify
 
-Rendering the page is the check for every extraction: the characters you return must be visible in that image. Watch for a page whose extracted text is suspiciously short (a missing text layer), duplicated (headers repeated per page), or full of replacement glyphs (broken encoding) before you build anything on top of it.
+The render is the check: the characters you return must be visible in it. Before building on extracted text, check for a page whose text is suspiciously short (missing text layer), duplicated (headers repeated per page), or full of replacement glyphs (broken encoding).