dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-presentations/tasks/charts-tables-notes.md

@@ -0,0 +1,79 @@
+# Task: charts, tables and speaker notes
+
+Three things that look like one job and share one rule: the numbers must be
+checkable from the file.
+
+## Charts
+
+Native, always:
+
+```bash
+"<python>" "<cli>" pptx create --spec with-chart.json --out charted.pptx
+```
+
+or the recipe when you need control of axis, labels or legend:
+[native-charts](../recipes/native-charts.md).
+
+Spec keys the builder accepts: `type` (`bar`/`column`/`line`/`pie`, where bar and
+column both render as a clustered column), `title`, `categories`,
+`series[{name, values}]`, `left`, `top`, `width`, `height`.
+
+- The chart title says what the chart means; the slide title states the
+  conclusion. If both say the same thing, drop the chart title.
+- Categories in the order the reader thinks in.
+- Bars start at zero.
+- A chart that duplicates a table on a neighbouring slide is a review finding,
+  not a second view — pick one.
+
+Verify:
+
+```bash
+"<python>" "<skill>/container_tools/native_chart_title_gate.py" --input charted.pptx
+"<python>" "<skill>/container_tools/native_quantitative_chart_gate.py" --input charted.pptx --all-slides
+```
+
+## Tables
+
+Spec form (`{"headers": [...], "rows": [[...]]}`) puts the table at the cursor,
+full width; the [tables recipe](../recipes/tables.md) gives you the rect, column
+widths, alignment and the total row styling.
+
+Rules: numbers right-aligned, units in the header, total row computed not typed,
+seven rows maximum on a slide.
+
+Declare each total so it can be proved:
+
+```bash
+"<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input charted.pptx --contracts totals.json
+```
+
+A mismatch exit code is a data bug or a rounding bug. Fix the number or declare
+the rounding; never lower the tolerance to make it pass.
+
+## Speaker notes
+
+Notes live beside the slide, not on it:
+
+```bash
+"<python>" "<cli>" pptx read --input deck.pptx   # does not print notes
+```
+
+Write them with the [speaker notes recipe](../recipes/speaker-notes.md), then
+confirm they landed:
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck-notes.pptx
+```
+
+`notesSlides` in the part counts should equal the number of slides you wrote
+notes for.
+
+Notes carry: the sentence you will say, the provenance of any non-obvious
+number, and the answer to the question the slide invites. Nothing that belongs
+on the slide.
+
+## Putting them together
+
+A results slide usually wants: one claim as the title, one chart as the
+evidence, one caption as the source, and the detail in notes. If it needs a
+chart *and* a table, it is two slides — or the table is an appendix.

package/assets/skills/office-presentations/tasks/create-deck.md

@@ -0,0 +1,106 @@
+# Task: create a deck
+
+## Inputs to settle first
+
+- Audience and setting: live talk, read-on-its-own PDF, or both. A read-only
+  deck needs more words; a live deck needs fewer.
+- Length: number of slides or minutes.
+- Brand: a template file, a colour, or nothing (then use the defaults in
+  [style-guidelines](../references/style-guidelines.md)).
+- Evidence: numbers, charts, tables and images the user already has. Never
+  invent a metric — if a number is needed and missing, say so.
+
+## Route
+
+### Fast path: the spec-driven builder
+
+For the ordinary deck (cover, bullets, section, table, chart, image, closing):
+
+```bash
+"<python>" "<cli>" pptx create --spec deck-spec.json --out deck.pptx
+```
+
+`deck-spec.json`:
+
+```json
+{
+  "title": "Automation Review",
+  "author": "Warehouse Ops",
+  "slides": [
+    { "layout": "title", "title": "Automation Review", "subtitle": "Warehouse network · FY2026" },
+    {
+      "layout": "bullets",
+      "title": "Where the time goes",
+      "bullets": [{ "text": "Picking is 41% of floor labour hours" }, { "text": "Aisle travel costs 12 minutes per order" }]
+    },
+    { "layout": "section", "title": "What the pilot measured" },
+    {
+      "layout": "blank",
+      "title": "Throughput rose while touches fell",
+      "table": {
+        "headers": ["Quarter", "Orders", "Touches"],
+        "rows": [["Q1", 100, 410], ["Q2", 128, 402], ["Total", 228, 812]]
+      }
+    },
+    {
+      "layout": "blank",
+      "title": "Orders per quarter",
+      "chart": {
+        "type": "column",
+        "title": "Orders fulfilled per quarter",
+        "categories": ["Q1", "Q2"],
+        "series": [{ "name": "Orders", "values": [100, 128] }],
+        "left": 0.9,
+        "top": 1.45,
+        "width": 11.5,
+        "height": 5.1
+      }
+    },
+    {
+      "layout": "bullets",
+      "title": "Decision for Thursday",
+      "bullets": [{ "text": "Approve two cells in Q1" }]
+    }
+  ]
+}
+```
+
+Layouts map to `title`, `bullets`, `section`, `title_only`, `blank`. Tables are
+placed at 0.8 in from the left at the running cursor and cannot be positioned —
+put a table on its own slide, or use the [tables recipe](../recipes/tables.md).
+
+### Everything else: build it with the recipes
+
+Anything at a coordinate, any crop, any connector, any master change is a
+`python-pptx` snippet:
+
+- [textbox at a coordinate](../recipes/textbox-at-coordinate.md)
+- [auto-layout rules](../recipes/autolayout.md)
+- [tables](../recipes/tables.md) · [native charts](../recipes/native-charts.md)
+- [images](../recipes/images.md) · [connectors](../recipes/connectors.md)
+- [rich text runs](../recipes/rich-text-runs.md) · [theme tokens](../recipes/theme-tokens.md)
+- [speaker notes](../recipes/speaker-notes.md) · [masters and layouts](../recipes/master-and-layouts.md)
+
+Extending a deck you already built:
+
+```bash
+"<python>" "<skill>/container_tools/add_slides.py" --input deck.pptx --spec extra-slides.json --out deck-2.pptx
+```
+
+### From a template
+
+See [template-following](template-following.md). Do not rebuild a supplied
+template's look by hand.
+
+## Then
+
+1. Set properties: `"<python>" "<skill>/container_tools/core_properties.py" --input deck.pptx --title "..." --author "..."`.
+2. Verify: [inspect-and-verify](inspect-and-verify.md).
+3. Deliver with `present`.
+
+## Writing the slides
+
+Story first. Write the one-sentence claim for every slide, in order, then fill
+the frames. If a claim needs two sentences, it is two slides. Keep bullets as
+claims ([native-bullets](../references/native-bullets.md)) and evidence native
+([native-evidence](../references/native-evidence.md)).

package/assets/skills/office-presentations/tasks/edit-deck.md

@@ -0,0 +1,93 @@
+# Task: edit an existing deck
+
+Editing is mutation, and mutation lives in this pack's tools, not in the helper
+CLI: `container_tools/replace_text.py`, `add_slides.py`, `core_properties.py`,
+plus the recipes for everything structural.
+
+**Never write over the original.** Every tool defaults to
+`<original>-edited.pptx`; keep that default unless the user names a path.
+
+## 1. Understand the file first
+
+```bash
+"<python>" "<cli>" pptx read --input deck.pptx
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx
+```
+
+`pptx read` gives titles, text, tables and chart data per slide. The geometry
+gate gives every shape's rect in inches, which is what you need to decide
+whether a new block fits.
+
+## 2. Text changes: run-level replace
+
+```bash
+"<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx \
+  --find "Q4 2025" --replace "Q4 2026" --out deck-edited.pptx
+```
+
+Batch form:
+
+```json
+{
+  "replacements": [
+    { "find": "Q4 2025", "replace": "Q4 2026" },
+    { "find": "€", "replace": "EUR ", "match_case": true },
+    { "find": "draft", "replace": "final", "slide": 7 }
+  ]
+}
+```
+
+```bash
+"<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx --spec replacements.json
+```
+
+Semantics that matter: a pattern only matches **inside a single run**. Text that
+PowerPoint split for formatting ("**Q4** 2025") will not match "Q4 2025" and the
+report lists it under `unmatched`. When a pattern cannot match, that is the
+signal to edit that paragraph with a run-level snippet
+([rich text runs](../recipes/rich-text-runs.md)) rather than widening the match.
+
+Exit code 1 means a pattern matched nothing; the file is still written, so read
+`unmatched` before delivering.
+
+## 3. Adding slides
+
+```bash
+"<python>" "<skill>/container_tools/add_slides.py" --input deck.pptx --spec extra-slides.json
+```
+
+The spec is the same slide object as `pptx create` (`layout`, `title`,
+`subtitle`, `bullets`, `table`, `chart`, `image`). For anything outside that
+vocabulary, add the slide with `add_slides.py` and then place content with a
+recipe.
+
+## 4. Metadata
+
+```bash
+"<python>" "<skill>/container_tools/core_properties.py" --input deck.pptx \
+  --title "Automation Review" --author "Warehouse Ops" --subject "FY2026 capital plan"
+```
+
+## 5. Structural changes
+
+| Change | Route |
+|---|---|
+| Move or resize a shape | recipe: set `.left/.top/.width/.height` on the shape from `slide.shapes` |
+| Restyle a family | [masters and layouts](../recipes/master-and-layouts.md) |
+| Add notes | [speaker notes](../recipes/speaker-notes.md) |
+| Replace a chart's data | [native charts](../recipes/native-charts.md) — edit the series, do not paste a picture |
+| Fix a table's total | [tables](../recipes/tables.md), then the arithmetic gate |
+| Delete a slide | `prs.slides._sldIdLst.remove(...)` after `prs.part.drop_rel(rId)` |
+
+## 6. Verify before delivering
+
+Deleting or inserting a slide commonly breaks nothing visible and everything
+relational:
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck-edited.pptx
+"<python>" "<skill>/container_tools/render_slides.py" --input deck-edited.pptx --out-dir preview
+```
+
+Then look at the changed pages. A text replacement that pushes a title onto a
+third line is a layout change, not a text change.

package/assets/skills/office-presentations/tasks/inspect-and-verify.md

@@ -0,0 +1,107 @@
+# Task: inspect and verify a deck
+
+Verification is reading the artefact back and looking at it. The tools below
+print one JSON object each; `passed` is the decision.
+
+## 1. What is in the file
+
+```bash
+"<python>" "<cli>" pptx read --input deck.pptx
+```
+
+Per slide: title, all text, tables as rows, charts with type/title/categories/
+series, image count. This is the cheapest sanity check that the content you
+meant to write is the content that was written.
+
+## 2. Is the package coherent
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck.pptx
+```
+
+Checks required parts, slide/master presence, dangling relationships, XML that
+does not parse, slide count drift and duplicate parts, then reports part counts
+(`slides`, `layouts`, `masters`, `charts`, `notesSlides`, `media`,
+`embeddings`). A chart with an `embeddings` count of zero has lost its data.
+
+## 3. Does the layout hold
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json
+```
+
+`fail` findings (block a delivery): shape outside the slide, degenerate size,
+text that cannot fit its frame, table outside the slide, chart or table covered
+by another shape. `review` findings (read them, then decide): text overlap,
+empty placeholder, title under 28 pt, body under 14 pt, heading ending in a full
+stop, connector across text, a chart duplicating a table's labels.
+
+Add `--strict` to make review findings blocking for a formal deck.
+
+## 4. Are the numbers real
+
+```bash
+"<python>" "<skill>/container_tools/native_chart_title_gate.py" --input deck.pptx
+"<python>" "<skill>/container_tools/native_quantitative_chart_gate.py" --input deck.pptx --all-slides
+"<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input deck.pptx --contracts totals.json
+```
+
+- Chart titles: fails on leftover "Chart Title" or an empty title, unless the
+  chart is explicitly suppressed.
+- Quantitative charts: every declared chart must be a real chart part with a
+  readable series, and in the default `portable` mode must carry its embedded
+  workbook.
+- Table arithmetic: only declared totals are enforced, compared against the
+  displayed rounding; columns whose header is not additive (unit price, ratio,
+  percent) are skipped rather than summed wrongly.
+
+`totals.json` names the contract explicitly:
+
+```json
+{ "contracts": [{ "slide": 4, "table": 1, "total_row": 6, "columns": [1, 2] }] }
+```
+
+## 5. Rendering and looking
+
+```bash
+"<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview
+```
+
+Writes `slide-NN.png` plus `render.json`. Then `read_image` every PNG — an
+unlooked-at render is not verification.
+
+To see the whole deck at once:
+
+```bash
+"<python>" "<skill>/template_following_scripts/make_contact_sheet.py" --dir preview --out sheet.png --columns 3
+```
+
+or `"<skill>/container_tools/create_montage.py` with an explicit file list.
+
+Look for: clipped text, overlapping blocks, a title that reflowed, a chart whose
+point is invisible at thumbnail size, a photograph stretched, a slide with no
+title.
+
+## 6. When nothing can render
+
+With no Microsoft Office, WPS Office, or LibreOffice installed
+(`office_status` → `renderers.kingsoft_wps` / `microsoft_office` / `libreoffice`),
+`render_slides.py` falls back to `--engine draft`, a PyMuPDF geometry preview. It
+shows placement, overflow and overlap — not typography or theme chrome. Say so
+when reporting: "verified as a geometry preview" is honest, "looks great" from an
+approximate render is not.
+
+If even the preview cannot run, the delivery is unverified: report the failing
+command, the file's slide count from `pptx read`, and the gate results, and tell
+the user which renderer to install for a visual check.
+
+## Gate summary
+
+| Gate | Command | Blocking |
+|---|---|---|
+| Package integrity | `inspect_presentation_package_integrity.py` | yes |
+| Layout geometry | `inspect_presentation_layout_geometry.py` | `fail` always, `review` with `--strict` |
+| Chart titles | `native_chart_title_gate.py` | yes |
+| Chart data | `native_quantitative_chart_gate.py` | yes for declared slides |
+| Table arithmetic | `native_table_arithmetic_gate.py` | yes for declared contracts |
+| Template fidelity | `template_source_fidelity_gate.py` | yes when requirements are supplied |

package/assets/skills/office-presentations/tasks/template-following.md

@@ -0,0 +1,132 @@
+# Task: follow a supplied template
+
+Use this when the user hands over a `.pptx` and says "use our template" or "match
+this deck". The design is already decided; your job is to put content into its
+own slides.
+
+## 1. Inspect
+
+```bash
+"<python>" "<skill>/template_following_scripts/inspect_template_deck.py" --template brand.pptx --out-dir template-inspect
+```
+
+Outputs:
+
+- `template-inspect.ndjson` — one JSON line per slide: layout name, layout
+  placeholders, slide placeholders (index, kind, rect in inches, text), shape
+  counts, text excerpt, whether the slide has full-bleed background art.
+- `template-manifest.json` — slide size, aspect ratio, layout names, theme font
+  names, and `backgroundArtSlides`.
+
+Read `backgroundArtSlides` before adding anything: those slides already carry
+artwork, so a new opaque panel will cover it.
+
+## 2. Plan
+
+Write `frame-map.json`:
+
+```json
+{
+  "template": "brand.pptx",
+  "newPrimitives": { "allowed": false, "justification": "" },
+  "outputSlides": [
+    {
+      "slide": 1,
+      "mode": "duplicate-slide",
+      "sourceSlide": 1,
+      "elements": [
+        {
+          "elementId": "title",
+          "action": "fill-placeholder",
+          "target": { "placeholder": "title", "text": "Automation Review" }
+        },
+        {
+          "elementId": "subtitle",
+          "action": "fill-placeholder",
+          "target": { "placeholder": "subtitle", "text": "Warehouse network · FY2026" }
+        }
+      ]
+    },
+    {
+      "slide": 2,
+      "mode": "duplicate-slide",
+      "sourceSlide": 3,
+      "elements": [
+        {
+          "elementId": "title",
+          "action": "rewrite",
+          "target": { "placeholder": "title", "text": "Throughput rose while touches fell" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Allowed actions: `rewrite`, `rewrite-and-reposition`, `replace`, `delete`,
+`keep`, `fill-placeholder`. `target.zone` is `[x, y, w, h]` in 0–1 slide
+fractions, used with `rewrite-and-reposition`. Elements whose `role` is
+`brand`, `logo`, `bumper`, `divider`, `section`, `chrome` or `footer` must stay
+`keep` — they are the template.
+
+Adding new shapes is opt-in: set `newPrimitives.allowed` and write a
+justification. The validator rejects shapes added without it, because "one extra
+box" is how a branded deck stops matching brand.
+
+## 3. Validate
+
+```bash
+"<python>" "<skill>/template_following_scripts/validate_template_plan.py" --plan frame-map.json
+```
+
+Rejects: unknown action, preserved role edited, zone outside 0–1, non-sequential
+slide numbers, missing justification for new primitives, and duplicate source
+slides (a warning — it means two output slides share artwork, usually fine for a
+repeated section divider, usually a copy-paste mistake otherwise).
+
+## 4. Build
+
+```bash
+"<python>" "<skill>/template_following_scripts/prepare_template_starter_deck.py" --template brand.pptx --plan frame-map.json --out starter.pptx
+```
+
+The starter deck keeps only the mapped source slides, in plan order, and applies
+the actions. It refuses duplicate source slides (it reuses slides rather than
+cloning parts). The report lists applied actions and any placeholder left empty.
+
+From here, extend with `container_tools/add_slides.py` or the recipes when the
+template has no family for a slide you need.
+
+## 5. Check fidelity
+
+```bash
+"<python>" "<skill>/template_following_scripts/check_template_fidelity.py" --template brand.pptx --final starter.pptx --plan frame-map.json
+"<python>" "<skill>/container_tools/template_source_fidelity_gate.py" --template brand.pptx --final starter.pptx --requirements fidelity.json
+```
+
+`fidelity.json`:
+
+```json
+{
+  "reference_slide_indices": [1, 3],
+  "mapping": { "1": 1, "2": 3 },
+  "minimum_coverage_ratio": 1.0,
+  "require_exact_dimensions": true,
+  "require_placeholder_geometry": true,
+  "require_photographic_background": false,
+  "geometry_tolerance_emu": 9144
+}
+```
+
+Both print `passed`. With no requirements, the fidelity gate is a deliberate
+no-op pass — pass a requirements file or you have not checked anything.
+
+## 6. Look at it
+
+```bash
+"<python>" "<skill>/container_tools/render_slides.py" --input starter.pptx --out-dir starter-preview
+```
+
+Compare against the source slides. A filled placeholder that overflows, a title
+in the wrong family, or a panel over the corner logo is exactly what this step
+exists to catch.