dsh-office-kit 0.4.2 → 0.4.3

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

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

@@ -1,22 +1,22 @@
-# Remove a region of a page
+# Redact a region of a page
 
-Redaction here means *destruction*, not a black box: the glyphs and vector paths inside a rectangle are deleted from the content stream, so no text extractor can recover them afterwards. A rectangle that only covers them visually is not a redaction, and "black out then flatten" leaks the original text.
+Redaction deletes glyphs and vector paths inside the rectangle from the content stream, so no extractor recovers them. A black box that covers text is not a redaction: "black out then flatten" leaks the original.
 
 ## Fast path: the region script
 
 ```bash
-"<python>" "<skill>/scripts/redact_region.py" --input "<file.pdf>" --out "<file-redacted.pdf>" \
-  --annotations '{"page":1,"region":{"left":0.064,"top":0.318,"width":0.891,"height":0.153}}' \
+"<python>" "<skill>/scripts/redact_region.py" --input "<file.pdf>" --out "<file-redacted.pdf>" \\
+  --annotations '{"page":1,"region":{"left":0.064,"top":0.318,"width":0.891,"height":0.153}}' \\
   --json-out "<redact.json>"
 ```
 
-The payload is the annotation shape: 1-based page plus a region normalised 0–1 against the rendered page. The script converts it, expands the rectangle by `--pad` points (default 2.5), calls `add_redact_annot(rect, fill=None)` then `apply_redactions(images=PDF_REDACT_IMAGE_NONE, graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED, text=PDF_REDACT_TEXT_REMOVE)`, and reports `removed_chars`, `removed_drawings`, the per-page before/after counts, and `leftover_chars_in_rect`. `--region`/`--page` do the same for a single value without JSON. Multiple annotations in one payload are applied page by page.
+The payload is a 1-based `page` plus a region normalised 0–1 against the rendered page. The script converts it, expands the rectangle by `--pad` points (default 2.5), calls `add_redact_annot(rect, fill=None)` then `apply_redactions(images=PDF_REDACT_IMAGE_NONE, graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED, text=PDF_REDACT_TEXT_REMOVE)`, and reports `removed_chars`, `removed_drawings`, per-page before/after counts, and `leftover_chars_in_rect`. `--region`/`--page` take single values without JSON; multiple annotations apply page by page.
 
-## Why the rectangle needs padding
+## Padding
 
-A line of text sits on a baseline and its glyphs can overhang the geometric box by a fraction of a point; selection boxes from a preview are approximate too. Expanding by 2–3 points catches ascenders, descenders, rules that touch the text, and the anti-aliased edge, while staying clear of neighbours. Measure, do not guess: `get_textbox(rect)` before the redaction lists what the rectangle will take, and `leftover_chars_in_rect` after it must be zero.
+Glyphs overhang the geometric text box and preview boxes are approximate. Expand by 2–3 points to catch ascenders, descenders, rules touching the text, and the anti-aliased edge without touching neighbours. Measure: `get_textbox(rect)` lists what the rectangle takes; `leftover_chars_in_rect` must be zero afterwards.
 
-Do it by hand when you need a different shape or a dry run:
+By hand, for another shape or a dry run:
 
 ```bash
 "<python>" - <<'PY'
@@ -40,26 +40,26 @@ PY
 
 ## The flags are not interchangeable
 
-- `fill=None` erases without painting. A fill colour (`fill=(1, 1, 1)`) paints a rectangle, which itself becomes a new drawing and hides the page's own background tint; the drawing count then goes up, not down.
-- `images=PDF_REDACT_IMAGE_NONE` leaves pictures untouched: a scanned region stays visible. Use `PDF_REDACT_IMAGE_PIXELS` to blank the pixels a rectangle covers inside an image, and only use a stronger setting when the user wants the whole image gone.
-- `graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED` deletes paths that intersect the rectangle; paths entirely inside it are always removed. `PDF_REDACT_LINE_ART_NONE` keeps all line art, which is right when only text should disappear.
-- Text removal is the default (`PDF_REDACT_TEXT_REMOVE`); keeping the text while erasing its surroundings is almost never what the user means.
+- `fill=None` erases without painting. `fill=(1, 1, 1)` paints a rectangle that becomes a new drawing and hides the page's background tint; the drawing count goes up, not down.
+- `images=PDF_REDACT_IMAGE_NONE` leaves pictures untouched, so a scanned region stays visible. `PDF_REDACT_IMAGE_PIXELS` blanks the pixels a rectangle covers inside an image; use a stronger setting only when the whole image should go.
+- `graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED` deletes intersecting paths; paths entirely inside are always removed. `PDF_REDACT_LINE_ART_NONE` keeps all line art, for text-only removal.
+- Text removal is the default (`PDF_REDACT_TEXT_REMOVE`); keeping text while erasing its surroundings is almost never what the user means.
 
 ## Counting the result
 
-`removed_chars` is the page-level difference in extracted text; `region_chars_removed` is the text that was inside the rectangle. They differ by the newline or space that joins the removed block to its neighbours, so expect them to be equal or one apart. Document-level totals are the sum over the changed pages. A run that removes fewer characters than the region held means the rectangle missed part of the block — enlarge `--pad` or convert the geometry again.
+`removed_chars` is the page-level difference in extracted text; `region_chars_removed` is what was inside the rectangle. They differ by the newline or space joining the block to its neighbours: expect equal or one apart. Fewer characters removed than the region held means the rectangle missed part of the block — enlarge `--pad` or redo the geometry.
 
-Cross-check on the sample document: page 1, region `{left: 0.064, top: 0.318, width: 0.891, height: 0.153}` deletes the "Latest News" block and nothing else. Measured: 16 drawings → 5, page text 1049 → 879 characters (the block held 169), `leftover_chars_in_rect` 0, and the body paragraph, header, and footer still extract and render.
+Sample: page 1 region `{left: 0.064, top: 0.318, width: 0.891, height: 0.153}` deletes the "Latest News" block alone — 16 drawings → 5, page text 1049 → 879 (block 169), `leftover_chars_in_rect` 0, and the body paragraph, header, and footer still extract and render.
 
 ## Leftovers redaction does not cover
 
-- **Metadata and embedded files**: the info dictionary and attachments are not page content. Clear them when the user asks for a clean file (see `scripts/metadata.py`), and note that a document ID/xref may still fingerprint the file.
-- **Previous revisions**: incrementally saved files can retain old objects. Saving with `garbage=3, deflate=True` compacts the file; when the user needs forensic certainty, say that the output was rebuilt and confirm with a text search that the words are gone.
-- **Images inside the region**: by default they stay. If the region is a screenshot of the sensitive text, switch to `--images pixels` or rebuild the page.
+- **Metadata and embedded files**: the info dictionary and attachments are not page content; clear them for a clean file (`scripts/metadata.py`). An ID/xref may still fingerprint the file.
+- **Previous revisions**: incrementally saved files keep old objects; save with `garbage=3, deflate=True`. For forensic certainty, say the output was rebuilt and confirm by text search that the words are gone.
+- **Images inside the region**: they stay by default. For a screenshot of the sensitive text, use `--images pixels` or rebuild the page.
 
 ## Verify
 
-Render after the redaction and look at the page. The region must be empty, the surrounding text intact, and any ruled boxes that belonged to the block gone rather than half-erased. Then search the output for the removed words:
+Render the page: the region empty, the surrounding text intact, and ruled boxes of the block gone rather than half-erased. Then search the output for the removed words:
 
 ```bash
 "<python>" - <<'PY'

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

@@ -1,6 +1,6 @@
 # Stamp a footer, header, or label
 
-An overlay is a tiny one-page PDF drawn with reportlab and merged onto the target page, so the original content stream is untouched and existing widgets keep working. Position is in points measured from the bottom-left of the page box; a stamp on an A4 page has 842 points of height to work with.
+An overlay is a small one-page PDF drawn with reportlab and merged onto the target page, so the original content stream is untouched and existing widgets keep working. Positions are points from the bottom-left of the page box; an A4 page is 842 points tall.
 
 ## Fast path: the stamp script
 
@@ -9,11 +9,11 @@ An overlay is a tiny one-page PDF drawn with reportlab and merged onto the targe
   --text "Confidential - page {page} of {pages}" --position bottom-center --render-dir "<render>"
 ```
 
-`{page}` and `{pages}` are substituted per page. Positions: `bottom-left`, `bottom-center`, `bottom-right`, `top-left`, `top-center`, `top-right`; `--pages "1,3-5"` limits the stamp; `--font-size`, `--font`, `--color`, `--margin`, and `--opacity` control the look. The script merges page by page with pypdf, refuses to overwrite the input, and can render the stamped pages so you can look at them.
+`{page}` and `{pages}` are substituted per page. Positions: `bottom-left`, `bottom-center`, `bottom-right`, `top-left`, `top-center`, `top-right`. `--pages "1,3-5"` limits the stamp; `--font-size`, `--font`, `--color`, `--margin`, and `--opacity` control the look. The script merges page by page with pypdf, refuses to overwrite the input, and can render the stamped pages for a look.
 
 ## Draw it yourself
 
-Use reportlab directly when the stamp is a bar, a rotated line, or a block of text:
+Use reportlab directly for a bar, a rotated line, or a block of text:
 
 ```bash
 "<python>" - <<'PY'
@@ -45,16 +45,16 @@ with open("out.pdf", "wb") as handle:
 PY
 ```
 
-Use the page's own `mediabox` rather than a hard-coded A4 size when the source may mix page sizes; a stamp drawn for A4 lands in the wrong place on a landscape page. `merge_page` paints over the page, so a solid bar hides whatever it covers — place it in a margin or inside a band you intend to cover.
+Use each page's own `mediabox` when sizes may mix; a stamp drawn for A4 lands in the wrong place on a landscape page. `merge_page` paints over the page, so a solid bar hides what it covers — put it in a margin or inside a band you mean to cover.
 
 ## Pitfalls
 
-- **Collisions with existing footers**: check the bottom margin first; the render is the proof, not the coordinate math. If the document already has a page number, either skip the stamp or put it on the opposite side.
-- **Rotated pages**: a page with `/Rotate 90` renders sideways; text drawn in the unrotated coordinate system will appear rotated in the viewer. Either rotate the stamp with `c.rotate(90)` and adjust the origin, or rotate the page back first.
-- **Repeated stamping**: merging the same overlay twice doubles the opacity and positions identically; re-run from the original input when iterating.
-- **Fonts**: Helvetica handles Latin; a CJK stamp needs a registered TTF, otherwise the text renders as blank boxes. Check the render.
-- **Opacity**: `setFillAlpha` is applied by viewers that honour transparency groups; a stamp that must be visible on any viewer is safer with full opacity.
+- **Existing footers**: check the bottom margin first; the render is the proof, not the coordinate math. If a page number is already there, skip the stamp or use the opposite side.
+- **Rotated pages**: a `/Rotate 90` page renders sideways, so text drawn unrotated appears rotated. Rotate the stamp (`c.rotate(90)`, adjusting the origin), or rotate the page back first.
+- **Repeated stamping**: merging the same overlay twice doubles the opacity at the same position; re-run from the original input when iterating.
+- **Fonts**: Helvetica handles Latin; a CJK stamp needs a registered TTF, or the text renders as blank boxes. Check the render.
+- **Opacity**: `setFillAlpha` works only in viewers that honour transparency groups; a stamp that must show on any viewer is safer at full opacity.
 
 ## Verify
 
-Render every stamped page and check: the text sits inside the margin, does not overlap body text or an existing footer, is the size the user asked for, and appears on exactly the selected pages. Then run `"<python>" "<cli>" pdf read --input "<file-stamped.pdf>"` — the stamp's text will join the page text, so a search for the label confirms it landed once, not twice.
+Render every stamped page: the text sits inside the margin, does not overlap body text or an existing footer, is the size the user asked for, and appears on exactly the selected pages. Then `"<python>" "<cli>" pdf read --input "<file-stamped.pdf>"` — the stamp text joins the page text, so searching for the label confirms it landed once, not twice.

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

@@ -1,94 +1,80 @@
 ---
-description: Build, inspect, restyle, and verify PowerPoint .pptx slide decks with python-pptx plus the bundled Office helper CLI.
+description: Create, edit, inspect, and verify PowerPoint .pptx slide decks — slides, templates, charts, render — with python-pptx and the bundled Office helper CLI.
 ---
 
 # Presentations (.pptx)
 
-A deck is a zip of XML parts: slides, layouts, masters, charts with embedded
-workbooks, notes, media. Everything the audience sees comes from those parts, so
-this pack teaches you to (a) author those parts correctly and (b) read them back
-before delivering.
+A `.pptx` is a zip of XML parts — slides, layouts, masters, charts with embedded
+workbooks, notes, media — and the reader sees only those parts. Author them, then
+read the file back.
 
-Two layers:
-
-- **The helper CLI** — a deterministic accelerator for common cases:
-  `<python> "<cli>" pptx {create|read|render}`, plus `office_status`. It creates
-  from a JSON spec, reads structure back, and renders. It does not mutate.
-- **This pack** — the capability layer. Recipes for anything the CLI does not
-  cover ([`recipes/`](recipes/README.md)), runnable tools for mutation and gates
-  in [`container_tools/`](container_tools/), template-following in
-  [`template_following_scripts/`](template_following_scripts/).
-
-Authoring is `python-pptx`. Not a page-description format, not a screenshot: real
-shapes, real chart parts, real notes.
+`<python> "<cli>" pptx {create|read|render}` plus `office_status` builds from a
+JSON spec, reads structure and renders; it does not mutate. Everything else is
+here: [recipes](recipes/README.md), mutation tools and gates in
+[container_tools/](container_tools/), templates in
+[template_following_scripts/](template_following_scripts/). Author with
+`python-pptx` — real shapes, chart parts, notes, never a screenshot.
 
 ## Before any file work
 
-1. Call the `office_status` tool.
-2. Read the `## Office runtime` JSON block appended to this file and use the
-   absolute `python`, `cli`, `skill` and `shared` values from it. Quote paths.
-3. If that block reports no working runtime, stop: tell the user to run the
-   `node "..."` remedy command it names, then call `office_status` again. Never
-   claim a deck was created or verified without a runtime to create and verify
-   it with.
+Call `office_status`. Read the `## Office runtime` JSON block appended to this
+file for the absolute `python`, `cli`, `skill` and `shared` values; quote paths.
+No working runtime → stop, give the user the `node "..."` remedy command it
+names, call `office_status` again. Never claim a deck was created or verified
+without a runtime.
 
 ## 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.
+`present` the finished file, then state the change in one sentence. A bare path
+is not delivery: chat renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as
+"二进制文件，无法显示改动".
 
-- 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.
+- Create: write into the user's workspace, verify, `present`.
+- Edit: never overwrite the original. Write `<original>-edited.<ext>` (or the
+  user's name), verify, `present`, and give 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.
+An `office-annotations` block — `[{ page, text, requirement, region: { left,
+top, width, height } }]` — is a change request, not editor state. `page` is the
+1-based preview slide; `region` is 0–1 on it, mapped to inches by
+`left_in = region.left * slide_width_in`. Select shapes by bounding-box overlap,
+`text` breaking ties. Apply the smallest edit satisfying `requirement`, re-render,
+confirm. Unmappable → say what you cannot locate; never guess.
 
-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.
-
-**pptx mapping.** `page` is the preview slide index (1-based, the `slide-NN.png`
-you rendered). The region selects shapes whose bounding box overlaps it:
-`left_in = region.left * slide_width_in`, and likewise for top/width/height.
-`text` disambiguates overlapping shapes (a title over a background panel).
-Resolve candidates from
-`container_tools/inspect_presentation_layout_geometry.py --json-out geometry.json`,
-then apply the edit through a mutation tool or a recipe. Full procedure:
-[tasks/apply-annotations.md](tasks/apply-annotations.md).
+Full procedure, mapping arithmetic and the edit table:
+[tasks/apply-annotations.md](tasks/apply-annotations.md). Candidates come from
+`container_tools/inspect_presentation_layout_geometry.py --json-out
+geometry.json`.
 
 ## Verify
 
-Render, look at every page, then deliver — in that order, with nothing skipped.
+Render, look at every page, then deliver.
 
 ```bash
 "<python>" "<skill>/container_tools/render_slides.py" --input "<file.pptx>" --out-dir "<render-dir>"
 ```
 
-`render_slides.py` uses the CLI's `pptx render` — which renders through the DSH
-LibreOffice kit — and falls back to a draft preview when the kit is missing, so
-this one command is always the right entry point. The JSON names the engine it
-used in `engine` (`libreoffice-kit` means a faithful render).
+`render_slides.py` uses the CLI's `pptx render` (DSH LibreOffice kit) and falls
+back to a draft preview without the kit, so it is always the right entry point.
+JSON `engine: "libreoffice-kit"` means a faithful render.
 
-Then open each PNG with `read_image` (or build one sheet with
-`"<skill>/template_following_scripts/make_contact_sheet.py"`). Check: titles
-one or two lines, body ≥ 18 pt, nothing clipped or outside the slide, no empty
-placeholder, table and chart not overlapping, chart readable at thumbnail size.
+`read_image` every PNG, or one sheet via
+`"<skill>/template_following_scripts/make_contact_sheet.py"`. Check: titles one
+or two lines, body ≥ 18 pt, nothing clipped or off-slide, no empty placeholder,
+table and chart not overlapping, chart readable at thumbnail size.
 
-If no office suite is installed, `render_slides.py` falls back to
-`--engine draft`, a PyMuPDF geometry preview. It proves placement, not
-typography — say which one you used.
+No office suite: `--engine draft` is a PyMuPDF geometry preview — placement, not
+typography. Say which you used.
 
-Gates that print JSON with a `passed` field, all blocking when they say `false`:
-`inspect_presentation_package_integrity.py`,
-`inspect_presentation_layout_geometry.py`, `native_chart_title_gate.py`,
-`native_quantitative_chart_gate.py`, `native_table_arithmetic_gate.py`,
-`template_source_fidelity_gate.py`. Details:
-[tasks/inspect-and-verify.md](tasks/inspect-and-verify.md).
+The six blocking gates and their flags are owned by
+[tasks/inspect-and-verify.md](tasks/inspect-and-verify.md); a gate that reports
+`passed: false` stops delivery.
 
 Never present a deck you have not rendered and looked at.
 
 ## Tasks
 
-One file per job:
-
 | Job | Start here |
 |---|---|
 | Create a deck | [tasks/create-deck.md](tasks/create-deck.md) |
@@ -100,32 +86,27 @@ One file per job:
 
 ## Tools and recipes
 
-Mutations (each prints one JSON object, exits non-zero on failure, defaults to
-`<original>-edited.pptx`):
+Mutations: one JSON object, non-zero exit on failure, default
+`<original>-edited.pptx`.
 
 | Need | Command |
 |---|---|
-| Find/replace text, run-level | `"<skill>/container_tools/replace_text.py" --input "<deck>" --find "old" --replace "new"` |
+| Replace text, run-level | `"<skill>/container_tools/replace_text.py" --input "<deck>" --find "old" --replace "new"` |
 | Append slides | `"<skill>/container_tools/add_slides.py" --input "<deck>" --spec "<slides.json>"` |
-| Title/author/subject/keywords | `"<skill>/container_tools/core_properties.py" --input "<deck>" --title "..."` |
-| Render (office, else draft) | `"<skill>/container_tools/render_slides.py" --input "<deck>" --out-dir "<dir>"` |
-| Contact sheet / montage | `"<skill>/template_following_scripts/make_contact_sheet.py" --dir "<dir>" --out "<sheet.png>"` |
+| Core properties | `"<skill>/container_tools/core_properties.py" --input "<deck>" --title "..."` |
+| Render | `"<skill>/container_tools/render_slides.py" --input "<deck>" --out-dir "<dir>"` |
+| Contact sheet | `"<skill>/template_following_scripts/make_contact_sheet.py" --dir "<dir>" --out "<sheet.png>"` |
 
-Template flow: `inspect_template_deck.py` → write a frame map →
+Template flow: `inspect_template_deck.py` → frame map →
 `validate_template_plan.py` → `prepare_template_starter_deck.py` →
 `check_template_fidelity.py`.
 
-Recipes (paste-runnable, each with the pitfall it avoids):
-[README](recipes/README.md) ·
-[textbox at a coordinate](recipes/textbox-at-coordinate.md) ·
-[auto-layout](recipes/autolayout.md) ·
-[tables](recipes/tables.md) ·
-[native charts](recipes/native-charts.md) ·
-[masters and layouts](recipes/master-and-layouts.md) ·
-[speaker notes](recipes/speaker-notes.md) ·
-[theme tokens](recipes/theme-tokens.md) ·
-[rich text runs](recipes/rich-text-runs.md) ·
-[images](recipes/images.md) ·
+Recipes: [README](recipes/README.md) · [textbox at a
+coordinate](recipes/textbox-at-coordinate.md) · [auto-layout](recipes/autolayout.md) ·
+[tables](recipes/tables.md) · [native charts](recipes/native-charts.md) ·
+[masters and layouts](recipes/master-and-layouts.md) · [speaker
+notes](recipes/speaker-notes.md) · [theme tokens](recipes/theme-tokens.md) ·
+[rich text runs](recipes/rich-text-runs.md) · [images](recipes/images.md) ·
 [connectors](recipes/connectors.md).
 
 Guidance: [authoring workflow](references/authoring-workflow.md) ·
@@ -135,31 +116,30 @@ Guidance: [authoring workflow](references/authoring-workflow.md) ·
 [templates](references/templates.md) ·
 [finalization](references/finalization.md) ·
 [finance decks](domain_guidance/finance.md) ·
-[Google Slides hand-off](routing/google_slides.md).
+[Google Slides](routing/google_slides.md).
 
 ## Non-negotiables
 
 - One idea per slide; a title is a claim, not a label.
 - Body ≥ 18 pt, title ≥ 28 pt, captions ≥ 12 pt.
 - Native charts and tables, never a picture of a spreadsheet.
-- Every placeholder filled or deleted; no "Chart Title", no trailing full stop
-  on a heading.
-- Numbers in the deck must agree with the numbers that were supplied.
-- New output lives in the user's workspace; an edit is a new file.
+- Every placeholder filled or deleted; no "Chart Title", no trailing full stop on
+  a heading.
+- Numbers in the deck agree with the numbers supplied.
+- New output in the user's workspace; an edit is a new file.
 
 ## Genuine gaps
 
-- The DSH LibreOffice kit missing (`renderers.can_render.pptx: false`) → no true
-  render; use `--engine draft` and say the check was geometric. A harness install
-  that ships the kit fixes it (the plugin records its path in `config.json` when it
-  loads); a standalone Office/LibreOffice install does not.
-- Fonts the user's machine lacks are substituted by any renderer; the pack
-  cannot install fonts.
-- Google Slides import fidelity is out of our control; see
+- DSH LibreOffice kit missing (`office_status` reports `renderers.available: false`) →
+  no true render. Use `--engine draft` and say the check was geometric; only a harness
+  install shipping the kit fixes it (the plugin records its path in `config.json`
+  on load), not a standalone Office/LibreOffice.
+- Fonts the user lacks are substituted by any renderer; the pack cannot install
+  them.
+- Google Slides import fidelity is outside our control; see
   [routing/google_slides.md](routing/google_slides.md).
 
 ## Shared workflow
 
-Use `"<shared>/common-workflow.md"` for the cross-format delivery and
-verification loop, and `"<shared>/annotation-recipes.md"` when turning an
-annotation payload into an edit.
+Use `"<shared>/common-workflow.md"` for the cross-format delivery loop, and
+`"<shared>/annotation-recipes.md"` to turn an annotation payload into an edit.

package/assets/skills/office-presentations/container_tools/render_slides.py

@@ -58,7 +58,7 @@ def rasterise_pdf(pdf_path: Path, out_dir: Path, dpi: int) -> list[str]:
 
 
 def render_with_office(source: Path, out_dir: Path, dpi: int) -> dict:
-    """Export through the CLI, which tries every installed office suite."""
+    """Export through the CLI, which renders with the bundled LibreOffice kit."""
     scratch = Path(tempfile.mkdtemp(prefix="dsh-render-"))
     try:
         completed = subprocess.run(