dsh-office-kit 0.4.2 → 0.4.4

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/preview_render.py

@@ -19,6 +19,7 @@ Exit codes: 0 ok, 2 unreadable input, 3 nothing rasterised.
 from __future__ import annotations
 
 import json
+import math
 import sys
 from pathlib import Path
 from typing import Any
@@ -254,7 +255,9 @@ def _draw_chart(page, shape, rect: fitz.Rect, slide_no: int, notes: list[dict[st
         for index, value in enumerate(values):
             sweep = 360.0 * abs(value) / total
             shade = shades[index % len(shades)]
-            page.draw_pie(center, radius, fitz.Point(radius * 1.0, 0), start, start + sweep, color=RULE, fill=(shade, shade, shade * 0.95 + 0.05), width=0.6)
+            # PyMuPDF 1.28 dropped Page.draw_pie; draw_sector has been stable since 1.16.
+            edge = fitz.Point(center.x + radius * math.cos(math.radians(start)), center.y + radius * math.sin(math.radians(start)))
+            page.draw_sector(center, edge, sweep, color=RULE, fill=(shade, shade, shade * 0.95 + 0.05), width=0.6)
             start += sweep
         return
 

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(

package/assets/skills/office-presentations/domain_guidance/finance.md

@@ -5,14 +5,14 @@ The mechanics are the same as any deck; the failure modes are specific.
 ## What a finance audience checks first
 
 1. Does the total add up? A slide whose numbers do not sum loses the argument
-   before the argument starts. Run the arithmetic gate on every declared total.
+   before it starts. Run the arithmetic gate on every declared total.
 2. Is the period stated? "Revenue up 12%" without a base period is not a claim.
-3. Is the unit stated? Thousands, millions, currency, and whether it is gross or
-   net. Put it in the header, once.
-4. Is the comparison like-for-like? Full quarter against full quarter; do not
-   put a 13-week quarter beside a 12-week one without saying so.
-5. Does the chart axis start at zero? For bars, yes, always — a truncated bar
-   chart in a finance deck reads as manipulation even when it is not.
+3. Is the unit stated? Thousands, millions, currency, gross or net. Put it in the
+   header, once.
+4. Is the comparison like-for-like? Full quarter against full quarter; do not put
+   a 13-week quarter beside a 12-week one without saying so.
+5. Does the chart axis start at zero? For bars, always — a truncated bar chart in
+   a finance deck reads as manipulation even when it is not.
 
 ## The financial slide kit
 
@@ -30,11 +30,11 @@ The mechanics are the same as any deck; the failure modes are specific.
 - Two significant figures is usually enough for a headline (`£2.4m`, not
   `£2,384,117`). Keep full precision in the appendix table.
 - Percentages: one decimal at most, and say what they are a percentage *of*.
-- Round consistently: if the headline says 2.4m, the table should not say
-  2.38m in one row and 2.4m in the next.
-- Negative numbers: use a minus sign consistently (`−12%`) and keep
-  parentheses for tables where accounting convention is expected.
-- A variance is meaningless without its sign and its direction; state whether
+- Round consistently: if the headline says 2.4m, the table should not say 2.38m
+  in one row and 2.4m in the next.
+- Negative numbers: one minus sign convention (`−12%`), parentheses kept for
+  tables where accounting convention is expected.
+- A variance is meaningless without its sign and direction; state whether
   favourable is up or down (revenue vs cost).
 
 ## Charts that survive a CFO
@@ -45,14 +45,14 @@ The mechanics are the same as any deck; the failure modes are specific.
 - One series per chart unless the comparison *is* the point.
 - Do not chart a table of six numbers; the table is more honest and faster to
   read.
-- Forecast periods are visually distinct (lighter fill, dashed line) and named
-  in the caption.
+- Forecast periods are visually distinct (lighter fill, dashed line) and named in
+  the caption.
 
 ## Provenance
 
 Every non-obvious number gets a note with: source file or system, extraction
-date, period covered, and any adjustment made. The speaker notes are the right
-place; a footnote-heavy slide is a slide nobody reads.
+date, period covered, any adjustment made. The speaker notes are the right place;
+a footnote-heavy slide is a slide nobody reads.
 
 ## Check before delivery
 

package/assets/skills/office-presentations/recipes/README.md

@@ -1,12 +1,9 @@
 # Slide mechanics and paste-runnable recipes
 
-The helper CLI covers the common path: a small deck with a title, bullet slides,
-a table, a chart and a picture. Everything else — precise coordinates, master
-edits, notes, theme tokens, connectors — is ordinary `python-pptx` work, and
-these recipes are the honest route.
-
-Read the mechanics first, then paste the recipe. Every snippet runs as-is from a
-shell, from any working directory:
+The helper CLI covers the common path: title, bullets, table, chart, picture.
+Everything else — exact coordinates, master edits, notes, theme tokens,
+connectors — is `python-pptx` work. These recipes are the route and run as-is
+from a shell, from any working directory:
 
 ```bash
 "<python>" - <<'PY'
@@ -21,17 +18,16 @@ PY
 |---|---|
 | Where is this shape? | `left`, `top`, `width`, `height` in **EMU** (English Metric Units). |
 | What is an inch? | `914400` EMU. `pptx.util.Inches(1)` is the polite wrapper. |
-| What is a point? | `12700` EMU. Font sizes use points, geometry uses EMU, and mixing them silently breaks layout. |
+| What is a point? | `12700` EMU. Font sizes use points, geometry uses EMU; mixing them silently breaks layout. |
 | What is a slide? | `prs.slide_width` / `prs.slide_height`; check them, never assume 16:9. |
 
-Helper conversions worth memorising: `Emu(914400) == Inches(1)`,
-`Pt(28) == Emu(355600)`, and a fraction of the slide is
+`Emu(914400) == Inches(1)`, `Pt(28) == Emu(355600)`, and a slide fraction is
 `int(0.1 * prs.slide_width)`.
 
 ## Z-order
 
-Shapes paint in the order they live in `slide.shapes`. A shape added later
-covers one added earlier. To reorder without deleting:
+Shapes paint in `slide.shapes` order; later covers earlier. Reorder without
+deleting:
 
 ```python
 tree = slide.shapes._spTree
@@ -40,32 +36,25 @@ tree.remove(shape._element)
 tree.insert(2, shape._element)  # after nvGrpSpPr and grpSpPr
 ```
 
-Index `2` is the first painted shape; that is where a full-bleed background
-image belongs.
+Index `2` is the first painted shape — where a full-bleed background belongs.
 
 ## What this pack ships
 
 | Recipe | Use it when |
 |---|---|
 | [textbox-at-coordinate](textbox-at-coordinate.md) | Text must land on an exact rect, not "somewhere under the title". |
-| [autolayout](autolayout.md) | The same build has to fit 3 bullets or 9 without hand-tuning. |
-| [tables](tables.md) | Numbers need a grid with column widths and per-cell formatting. |
-| [native-charts](native-charts.md) | Data must stay editable, not become a picture of a chart. |
-| [master-and-layouts](master-and-layouts.md) | The whole deck changes at once: title bar, accent line, footer. |
-| [speaker-notes](speaker-notes.md) | The presenter needs a script attached to each slide. |
-| [theme-tokens](theme-tokens.md) | Colours and fonts must come from one place. |
-| [rich-text-runs](rich-text-runs.md) | One paragraph mixes bold, accent colour and a footnote. |
-| [images](images.md) | A picture needs a crop, a cover fit or a real alt text. |
-| [connectors](connectors.md) | Two boxes are joined by a line that must survive a move. |
-
-## Order of work that keeps decks out of trouble
-
-1. Read the target geometry off the template or the user's reference
-   (`container_tools/inspect_presentation_layout_geometry.py` prints it as JSON).
-2. Place shapes in EMU, top-down: background, chrome, title, body, evidence.
-3. Set type sizes by the *smallest* screen the deck will be shown on; body 18 pt
-   and up, footnotes 12 pt and up.
-4. Fill every placeholder you keep and delete the ones you do not — an empty
-   placeholder prints "Click to add text" in edit view and looks unfinished.
-5. Render, look, then fix. `container_tools/render_slides.py` plus `read_image`
-   is the loop; a deck nobody looked at is not verified.
+| [autolayout](autolayout.md) | The same build must fit 3 bullets or 9 without hand-tuning. |
+| [tables](tables.md) | Numbers need column widths and per-cell formatting. |
+| [native-charts](native-charts.md) | Data must stay editable, not a chart picture. |
+| [master-and-layouts](master-and-layouts.md) | Whole-deck changes: title bar, accent line, footer. |
+| [speaker-notes](speaker-notes.md) | A script attached to each slide. |
+| [theme-tokens](theme-tokens.md) | Colours and fonts from one place. |
+| [rich-text-runs](rich-text-runs.md) | One paragraph mixes bold, accent colour, footnote. |
+| [images](images.md) | A crop, a cover fit or real alt text. |
+| [connectors](connectors.md) | A line between boxes that survives a move. |
+
+## Order of work
+
+Follow the loop in [authoring-workflow](../references/authoring-workflow.md):
+story → frame → place top-down in EMU → fill or delete placeholders → render and
+look. Type sizes live in [style-guidelines](../references/style-guidelines.md).

package/assets/skills/office-presentations/recipes/autolayout.md

@@ -2,19 +2,18 @@
 
 ## Mechanics
 
-PowerPoint has two different "autofit" ideas and mixing them up wastes a round
-trip:
+PowerPoint has two "autofit" ideas; mixing them up wastes a round trip:
 
 - `word_wrap` decides whether text wraps inside the width. Turn it on for every
   authored box.
 - `auto_size` decides whether the *frame* follows the text (`MSO_AUTO_SIZE.
   SHAPE_TO_FIT_TEXT`) or the text shrinks to fit the frame
   (`TEXT_TO_FIT_SHAPE`). `TEXT_TO_FIT_SHAPE` is a **render-time** behaviour:
-  PowerPoint recalculates it when the file is opened, so a deck that looks fine
-  in a draft preview can still shrink to 8 pt on a real screen.
+  PowerPoint recalculates it when the file opens, so a deck that looks fine in a
+  draft preview can still shrink to 8 pt on a real screen.
 
-The reliable pattern is: fixed frame, explicit sizes, content measured against
-the frame, no text-to-fit. Estimate, then verify by rendering.
+The reliable pattern: fixed frame, explicit sizes, content measured against the
+frame, no text-to-fit. Estimate, then verify by rendering.
 
 ## Recipe: fit a variable number of bullets
 
@@ -66,7 +65,7 @@ PY
 ## Rules that hold regardless of content
 
 1. Body text is 18 pt or larger; below that the back row cannot read it.
-2. Six bullets or three lines of body is the point where a slide should split.
+2. Six bullets or three lines of body is where a slide should split.
 3. Longer text shrinks the number of *words*, not the type size. If the fit loop
    lands below the body floor, cut copy or split the slide.
 4. Keep 0.5 in of bottom margin for the footer and for projectors that crop.
@@ -77,12 +76,12 @@ PY
 - `frame.text` then `paragraph.font.size` on paragraph 0 only: a multi-paragraph
   assignment leaves paragraphs 1..n at the inherited 18 pt.
 - Text-to-fit hiding the overflow: the file opens fine and the audience reads
-  9 pt. Measure, do not delegate the fit to the renderer.
-- A frame height that exactly equals the text height: one extra word on edit and
-  the block runs into the evidence below. Reserve 10% slack.
+  9 pt. Measure; do not delegate the fit to the renderer.
+- A frame height exactly equal to the text height: one extra word on edit and the
+  block runs into the evidence below. Reserve 10% slack.
 
 ## CLI fast path
 
-`pptx create` with `layout: "bullets"` fills the layout's body placeholder at
-its own size. Use the loop above when the number of bullets is not known before
-the content is written.
+`pptx create` with `layout: "bullets"` fills the layout's body placeholder at its
+own size. Use the loop above when the number of bullets is unknown before the
+content is written.