dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-presentations/recipes/theme-tokens.md

@@ -0,0 +1,87 @@
+# Theme tokens
+
+## Mechanics
+
+The theme part (`ppt/theme/theme1.xml`) holds two palettes and two font lists:
+
+- `dk1/lt1/dk2/lt2/accent1..6/hlink/folHlink` — every `RGBColor` you *do not*
+  set falls back to one of these, and PowerPoint's "theme colors" picker edits
+  them for the whole deck.
+- `majorFont` / `minorFont` — the heading and body typefaces inherited by every
+  run without an explicit font.
+
+So: write `RGBColor.rgb` when a colour must never change, and reference a theme
+colour when the user may re-skin the deck. A deck with hard-coded hex
+everywhere cannot be re-branded, which is usually why the user supplied a
+template.
+
+## Recipe: define the palette once, use it everywhere
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.util import Inches, Pt
+from pptx.enum.dml import MSO_THEME_COLOR
+
+PALETTE = {
+    "ink": RGBColor(0x16, 0x1D, 0x28),
+    "muted": RGBColor(0x5F, 0x6B, 0x7A),
+    "accent": RGBColor(0xD9, 0x8B, 0x1E),
+    "rule": RGBColor(0xD6, 0xDC, 0xE4),
+}
+TYPE = {"title": Pt(34), "body": Pt(18), "caption": Pt(12)}
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+def put(text, left, top, width, size, colour, bold=False):
+    box = slide.shapes.add_textbox(Inches(left), Inches(top), Inches(width), Inches(0.6))
+    frame = box.text_frame
+    frame.word_wrap = True
+    frame.margin_left = frame.margin_right = 0
+    run = frame.paragraphs[0].add_run()
+    run.text = text
+    run.font.size = size
+    run.font.bold = bold
+    run.font.color.rgb = PALETTE[colour]
+    return box
+
+put("Automation Review", 0.9, 2.4, 11.5, TYPE["title"], "ink", bold=True)
+put("Warehouse network · FY2026", 0.9, 3.3, 11.5, TYPE["body"], "muted")
+put("Source: FY2026 capital plan", 0.9, 6.7, 6.0, TYPE["caption"], "muted")
+prs.save("themed.pptx")
+print("palette keys:", sorted(PALETTE), "theme colour sample:", MSO_THEME_COLOR.ACCENT_1)
+PY
+```
+
+## Reading the theme you were given
+
+```python
+from pptx import Presentation
+prs = Presentation("template.pptx")
+theme = prs.slide_masters[0].part.part_related_by(
+    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+)
+blob = theme.blob.decode("utf-8", "ignore")
+print("accent1" in blob, "majorFont" in blob)
+```
+
+`template_following_scripts/inspect_template_deck.py` already reports the font
+names it finds in the theme, so check there before introducing a new typeface.
+
+## Pitfalls this avoids
+
+- Two similar hexes drifting apart across slides (`#161d28` on one slide,
+  `#171e29` on the next) because the colour was retyped instead of referenced.
+- A serif body font set from taste rather than from the theme, so the deck
+  contradicts the template it was built in.
+- `font.color.theme_color = MSO_THEME_COLOR.ACCENT_1` *and* `font.color.rgb`
+  on the same run: the last assignment wins and the theme reference vanishes.
+
+## CLI fast path
+
+`pptx create` uses the default template's theme. For a branded deck, start from
+the supplied template (see [master-and-layouts](master-and-layouts.md)) rather
+than recolouring a blank deck.

package/assets/skills/office-presentations/references/authoring-workflow.md

@@ -0,0 +1,65 @@
+# Authoring workflow
+
+## What a deck is, mechanically
+
+A `.pptx` is a zip of XML parts: one `presentation.xml` naming the slide order, one
+part per slide, a slide master per theme, a layout per family, chart parts with
+embedded workbooks, notes parts, and a media folder. Everything the reader sees
+comes from those parts, which is why the verification loop reads the file back
+instead of trusting the code that wrote it.
+
+Three consequences shape the whole workflow:
+
+1. **Geometry is explicit.** Nothing reflows on open except autofit. If two
+   shapes overlap in the XML, they overlap on screen.
+2. **Inheritance is real.** A slide draws its background, type sizes and bullet
+   glyphs from its layout and master. Overriding at slide level is a per-slide
+   decision; overriding at master level is a deck decision.
+3. **Data can stay alive.** A native chart or table keeps its numbers in the
+   file and can be checked; a screenshot cannot.
+
+## The loop
+
+1. **Decide the story**: one sentence per slide, in order, before any XML. A
+   slide without a sentence is a slide the audience will not read.
+2. **Pick the frame**: slide size from the target (`13.333 × 7.5 in` is the 16:9
+   default; check `prs.slide_width` of a supplied template, never assume).
+3. **Place, top-down**: background, chrome, title, body, evidence. Later shapes
+   paint over earlier ones.
+4. **Fill or delete every placeholder.** An empty placeholder is visible in edit
+   view and prints "Click to add text".
+5. **Render, look, fix.** `container_tools/render_slides.py` then `read_image` on
+   every PNG. Repeat until nothing surprises you.
+
+## The numbers that keep a deck readable
+
+| Element | Value | Why |
+|---|---|---|
+| Slide size | 13.333 × 7.5 in | 16:9; 10 × 5.625 in for 16:9 in "wide" templates |
+| Margin | 0.6–0.9 in | Below 0.5 in a projector crops it |
+| Title | 28–36 pt, bold | 44 pt only on covers |
+| Body | 18 pt minimum | The back row rule |
+| Caption / source | 12–14 pt | Never below 11 pt |
+| Line spacing | 1.1–1.2 | Tighter crowds ascenders |
+| Gap between blocks | 0.2–0.4 in | The eye groups by proximity |
+| Footer zone | bottom 0.55 in | Keep text out of it |
+
+Convert once and keep the numbers in EMU or inches, not mixed: `Inches(x)` in
+code, `x * 914400` when you must talk to the XML directly.
+
+## Deciding slide count
+
+One idea per slide. If a slide has two headlines competing, it is two slides. If
+it has one headline and a table too large to read at 14 pt, the table becomes an
+appendix slide and the body slide states the conclusion in one line.
+
+A presentation of N minutes needs roughly N/2 content slides at 60–90 seconds
+each, plus a cover and a closing ask.
+
+## Where the detail lives
+
+- Type, colour, density and cover art: [style-guidelines](style-guidelines.md).
+- Bullets that read as sentences: [native-bullets](native-bullets.md).
+- Charts, tables and notes as evidence: [native-evidence](native-evidence.md).
+- Supplied templates: [templates](templates.md).
+- Pre-delivery checklist: [finalization](finalization.md).

package/assets/skills/office-presentations/references/finalization.md

@@ -0,0 +1,63 @@
+# Finalization checklist
+
+Run this before `present`. It exists because every item on it has shipped a
+broken deck at least once.
+
+## The file
+
+- [ ] Opens: `"<python>" "<cli>" pptx read --input deck.pptx` returns slides.
+- [ ] Package is coherent:
+      `"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck.pptx`
+      → `passed: true`, no dangling relationships, media and charts present.
+- [ ] Slide count matches the intent; nothing left over from an earlier draft.
+- [ ] Core properties set:
+      `"<python>" "<skill>/container_tools/core_properties.py" --input deck.pptx --title "..." --author "..."`
+      (an untitled deck shows up as "PowerPoint Presentation" in every file list).
+
+## The content
+
+- [ ] Every placeholder is filled or deleted — no "Click to add text".
+- [ ] No default chart title ("Chart Title") survives:
+      `"<python>" "<skill>/container_tools/native_chart_title_gate.py" --input deck.pptx`.
+- [ ] Totals are arithmetic:
+      `"<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input deck.pptx --contracts totals.json`.
+- [ ] Charts have their data in the file (portable mode passes) and categories
+      are in a meaningful order.
+- [ ] Numbers in the deck agree with the numbers in the source data, at the
+      precision shown.
+- [ ] Speaker notes carry the provenance of the non-obvious numbers.
+
+## The layout
+
+- [ ] Geometry gate passes:
+      `"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json`
+      → `passed: true`; review findings read and consciously accepted.
+- [ ] Nothing outside the slide edge, nothing overlapping the footer zone.
+- [ ] Titles are one or two lines; no title ends in a full stop.
+- [ ] Body text is at least 18 pt, captions at least 12 pt.
+- [ ] One idea per slide, one emphasis per paragraph.
+
+## The look
+
+- [ ] Rendered at viewing size and actually looked at:
+      `"<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview`
+      then `read_image` on each PNG (or on the contact sheet from
+      `"<skill>/template_following_scripts/make_contact_sheet.py`).
+- [ ] Text is not clipped, ellipsised or shrunk to illegibility.
+- [ ] Photographs are not stretched; their sources are listed.
+- [ ] Charts read at thumbnail size: the point is visible before any label.
+- [ ] The cover and closing slide both say something.
+
+## Delivery
+
+- [ ] The file lives in the user's workspace, not in a temp directory.
+- [ ] Output name is either new (`deck.pptx`) or `<original>-edited.pptx`.
+- [ ] `present` called; the reply states what changed in one sentence and, for
+      edits, both paths.
+
+## When rendering is unavailable
+
+`render_slides.py --engine draft` draws a geometry preview with PyMuPDF when no
+office suite is installed. It is honest about being approximate: type is drawn
+at declared sizes in a substitute face, and layout chrome is not rendered. Use
+it to catch overlap, overflow and placement — not to judge typography.

package/assets/skills/office-presentations/references/native-bullets.md

@@ -0,0 +1,78 @@
+# Bullets that read as sentences
+
+## The shape of a bullet
+
+A bullet is a claim, not a label. Two forms work:
+
+- **Claim + consequence**: "Picking is 41% of floor labour hours — travel is the
+  cost, not the pick."
+- **Number + meaning**: "12 minutes per order lost to aisle travel."
+
+Forms that do not work: a single noun ("Efficiency"), a truncated clause
+("Picking accounts for…"), a list of three adjectives, or a bullet that restates
+the slide title.
+
+## Length and count
+
+- One line, two at the absolute maximum, per bullet on a 16:9 slide.
+- Three to five bullets. Six is a signal to split; eight is a document.
+- No sub-sub-bullets. If a bullet needs a child, the parent was a section.
+- Keep bullets grammatically parallel: all sentences, or all noun phrases.
+
+## Native bullet glyphs
+
+Bullets in PowerPoint are paragraph properties, not characters. A bullet
+character typed into the text ("• Picking…") is a bullet that cannot re-indent,
+cannot change level, and looks different from every other bullet in the deck.
+
+Set them properly:
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.text import PP_ALIGN
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+box = slide.shapes.add_textbox(Inches(0.9), Inches(1.8), Inches(11.0), Inches(3.6))
+frame = box.text_frame
+frame.word_wrap = True
+
+for index, text in enumerate((
+    "Picking is 41% of floor labour hours",
+    "Aisle travel costs 12 minutes per order",
+    "Manual cycle counts stop the line twice a week",
+)):
+    paragraph = frame.paragraphs[0] if index == 0 else frame.add_paragraph()
+    paragraph.text = text
+    paragraph.font.size = Pt(20)
+    paragraph.space_after = Pt(12)
+    paragraph.level = 0
+    paragraph.alignment = PP_ALIGN.LEFT
+    # PowerPoint's own bullet: a literal glyph in the paragraph's pPr
+    paragraph._pPr.set("marL", str(Inches(0.3)))
+    paragraph._pPr.set("indent", str(-Inches(0.3)))
+    bu = paragraph._pPr.makeelement(
+        "{http://schemas.openxmlformats.org/drawingml/2006/main}buChar", {"char": "•"}
+    )
+    paragraph._pPr.append(bu)
+
+prs.save("bullets.pptx")
+print("bullets:", len(frame.paragraphs))
+PY
+```
+
+The `marL`/`indent` pair is what pulls the second line of a wrapped bullet under
+the text instead of under the glyph — the most common "malformed bullet" defect
+in generated decks.
+
+## Anti-patterns
+
+- Bullets as a script: a slide is not a transcript, the speaker notes are.
+- Fake bullets via "– " or "→ " prefixes in the text; they do not indent.
+- Six bullets of equal weight where one is the actual point. Make the point the
+  title and the bullets the evidence.
+- Numbered lists where the order does not matter, and bullet lists where it
+  does.

package/assets/skills/office-presentations/references/native-evidence.md

@@ -0,0 +1,67 @@
+# Evidence on slides: charts, tables, notes
+
+"Evidence" is anything on a slide that claims a fact: a number, a chart, a
+table, a quotation. The rules below keep it checkable.
+
+## Native or it did not happen
+
+| Claim | Correct form | Wrong form |
+|---|---|---|
+| Trend over time | Native chart with categories and series | Screenshot of a chart |
+| Exact figures | Native table | Image of a spreadsheet |
+| A single number | A bold run in a sentence | A one-bar chart |
+| A process | Shapes plus connectors | Image of a flowchart |
+
+The wrong column has one shared defect: the audience cannot read it at projector
+size and nobody can verify it. Native charts and tables also keep their numbers
+in the package, which is what lets `container_tools/native_quantitative_chart_gate.py`
+and `container_tools/native_table_arithmetic_gate.py` check them.
+
+## Charts
+
+- The chart title says what the chart means. The slide title says the conclusion.
+  Two titles, two jobs — if they are the same sentence, drop the chart title
+  (`chart.has_title = False`) rather than repeat it.
+- Bars start at zero. Lines may start elsewhere only if the axis is labelled.
+- Categories in the order the audience thinks in (Q1..Q4, not alphabetised).
+- Label the few numbers that matter, not every point. Ten data labels is a
+  table with rounded corners.
+- One axis. Two y-axes on a slide chart is a way to imply a correlation that may
+  not exist.
+- Source and window in the caption: "Driver logs, FY2026, 12 sites".
+
+## Tables
+
+- Column order follows the reader's question: what, then how much, then change.
+- Header row is bold and distinct; total row is bold and separated.
+- Numbers right-aligned, one decimal convention per column.
+- A total is arithmetic the reader can check. Fill it from the data, never by
+  eye, and let the table arithmetic gate confirm it.
+- Do not put units in every cell; put them in the header.
+- A table with more than about 7 rows belongs in an appendix, with the slide
+  stating the conclusion.
+
+## Speaker notes as provenance
+
+Notes are where "where did this number come from" lives, so the presenter can
+answer without the slide turning into a footnote.
+
+- One note per non-obvious number: source, date range, and any caveat.
+- The sentence you will actually say, in spoken words.
+- No bullet-stacking in notes; notes are prose.
+- Notes are invisible to the render loop — verify them from the file, not the
+  PNGs. `container_tools/inspect_presentation_package_integrity.py` counts
+  `notesSlides`, and the package dump shows their text.
+
+## Fidelity gates
+
+Before presenting a deck that carries numbers:
+
+```bash
+"<python>" container_tools/native_quantitative_chart_gate.py --input deck.pptx --all-slides
+"<python>" container_tools/native_table_arithmetic_gate.py --input deck.pptx --contracts totals.json
+"<python>" container_tools/native_chart_title_gate.py --input deck.pptx
+```
+
+Each prints one JSON object whose `passed` field is the decision. A failing gate
+is not advisory: it means the slide asserts something the file cannot support.

package/assets/skills/office-presentations/references/style-guidelines.md

@@ -0,0 +1,66 @@
+# Style guidance
+
+## The type scale
+
+Three sizes are enough: title, body, caption. A fourth size is a decision the
+audience has to make, and they will make it wrongly.
+
+| Role | Size | Weight | Colour |
+|---|---|---|---|
+| Cover title | 40–48 pt | Bold | Ink |
+| Slide title | 28–36 pt | Bold or semibold | Ink |
+| Body | 18–22 pt | Regular | Ink |
+| Lead-in number | Same as body + bold | Bold | Accent |
+| Caption, source | 12–14 pt | Regular | Muted |
+
+Rules that carry the rest:
+
+- One typeface family. A second family means "different voice", so use it for
+  one thing (a quote, a code line) and nothing else.
+- Bold is emphasis, not decoration: at most one bold phrase per paragraph.
+- All-caps for a 2–4 word label is a design choice; all-caps for a sentence is
+  a readability tax.
+- Left-align body text. Centred paragraphs longer than two lines are hard to
+  track back to the next line.
+
+## Colour
+
+- One ink, one muted, one accent, plus the template's own rule colour. More
+  than that and the accent stops meaning "look here".
+- Contrast is a correctness issue: body text on white needs a dark ink
+  (roughly luminance ratio 4.5:1), and text over a photograph needs a scrim,
+  not luck.
+- Never encode meaning in colour alone — an accent bar showing the direction of
+  a metric also needs an arrow or a word.
+- Chart series colours come from the theme; a sixth series colour is a signal
+  that the chart has too many series.
+
+## Density
+
+- Body blocks stop at about 6 lines of 18 pt on a 16:9 slide before the eye
+  stops at the middle.
+- A table on a slide reads at up to about 7 rows × 4 columns. Beyond that it is
+  an appendix, and the slide should carry the one row that matters.
+- Whitespace is a layout element, not leftover space: leave at least 0.6 in
+  between content blocks and the slide edge.
+- One idea per slide. If the title needs "and", split.
+
+## Cover art direction
+
+A cover carries three things: the title, the context line, and the visual that
+sets the tone. Keep them separate roles.
+
+- Abstract geometry, a photograph of the actual subject, or a flat colour field
+  all work. Clip art of a handshake does not.
+- If the visual is photographic, darken it (a scrim at 40–60% black) under the
+  text rather than hoping the text lands on a dark region.
+- If no suitable image exists, use a colour field plus an accent rule. An
+  invented diagram pretending to be a photograph is worse than a plain cover.
+- Encode the deck's palette: if the accent is amber, the cover visual should
+  contain amber, not a random sunset.
+- Never ship a screenshot of a tool, a UI or another slide as cover art.
+
+## Closing slides
+
+The last slide restates the ask in one line and nothing else. "Thank you" alone
+wastes the slot the audience is still looking at while they gather their things.

package/assets/skills/office-presentations/references/templates.md

@@ -0,0 +1,76 @@
+# Working from a supplied template
+
+## Why templates win
+
+A template already answers branding, type scale, slide families and chrome. The
+cheapest correct deck puts the user's content into the template's own slides
+and leaves the design alone. Rebuilding the look from a screenshot produces a
+near-miss that reads as "someone remade our deck in a hurry".
+
+## Order of operations
+
+1. **Inspect the template** before judging it:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/inspect_template_deck.py" --template brand.pptx --out-dir template-inspect
+   ```
+
+   It writes `template-inspect.ndjson` (per slide: layout, placeholders with
+   index, kind, rect and text, background art) and `template-manifest.json`
+   (slide size, aspect, layout names, theme fonts, which slides carry
+   full-bleed art).
+
+2. **Choose the slide families you need** — cover, section, content, table,
+   chart, closing. You want the *fewest* source slides that cover those roles.
+
+3. **Write the frame map** — a JSON plan that names, per output slide, which
+   source slide it duplicates and what happens to each element
+   (`rewrite`, `rewrite-and-reposition`, `fill-placeholder`, `replace`,
+   `delete`, `keep`).
+
+4. **Validate the plan** before building:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/validate_template_plan.py" --plan frame-map.json
+   ```
+
+   It rejects unknown actions, out-of-range zones, new primitives without an
+   explicit justification, and any attempt to edit a brand or chrome element.
+
+5. **Build the starter deck**, then fill it:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/prepare_template_starter_deck.py" --template brand.pptx --plan frame-map.json --out starter.pptx
+   ```
+
+   The starter deck contains only the slides you kept, in your order, with the
+   placeholders filled. From there `container_tools/add_slides.py` and the
+   recipes extend it.
+
+6. **Check fidelity** against the source:
+
+   ```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
+   ```
+
+   Both print JSON with a `passed` boolean. Leftover placeholders, drifted
+   layout rects and opaque panels covering inherited artwork are failures, not
+   style opinions.
+
+## Reading a template's own geometry
+
+`container_tools/inspect_presentation_layout_geometry.py --input brand.pptx`
+prints every shape's rect in inches, which is what you address when a slide's
+placeholder needs a value that fits its frame.
+
+## Rules
+
+- Placeholders keep their index; fill by index rather than adding a textbox on
+  top of a placeholder.
+- Never restyle the master to match a screenshot you were given. If the brand
+  colours are wrong, ask; guessing produces a deck the brand team rejects.
+- If the template has no suitable family for a slide (say, a two-column
+  comparison), say which family you added and why, rather than silently
+  inventing a look.
+- Keep the template's slide size. Changing it invalidates every inherited rect.

package/assets/skills/office-presentations/routing/google_slides.md

@@ -0,0 +1,45 @@
+# Handing a deck to Google Slides
+
+Google Slides imports `.pptx`, and mostly survives it. What it does not survive
+is worth designing around.
+
+## What converts cleanly
+
+- Text frames, bullet levels, speaker notes, slide size and order.
+- Native tables and native charts (data comes across with the chart).
+- Pictures, shapes, solid fills and theme colours.
+
+## What converts badly
+
+| Feature | What happens | Do instead |
+|---|---|---|
+| Custom `buChar` glyphs and `marL/indent` | Indent shifts, glyphs fall back | Use plain paragraph levels; check the bullet indent after import |
+| Elbow/curved connectors | Re-anchored or detached | Straight connectors between facing sides |
+| Font not on the reader's machine | Substituted, wider, text reflows | Stick to fonts both environments have, and re-check overflow after import |
+| Text-to-fit-shape autosize | Keeps the shrunk size | Fixed frames with measured text |
+| Animations and transitions | Partially dropped | Do not rely on them for meaning |
+| Embedded workbook charts | Data retained, formatting re-derived | Re-apply axis/label settings in Slides if they matter |
+| Master-level chrome via spTree surgery | Usually kept, occasionally duplicated | Prefer layout-level placeholders |
+
+## The workflow
+
+1. Build the deck as a normal `.pptx` — nothing Slides-specific is needed.
+2. Render and inspect the PNGs locally first; fix overflow before importing.
+3. Upload to Drive, open with Google Slides, and check these in order: title
+   wrapping, bullet indentation, connector attachment, chart axes, notes.
+4. If the deck will be edited by other people in Slides, keep shapes distinct
+   and named (right-click → rename) so comments and edits are unambiguous.
+
+## Sharing
+
+- "Anyone with the link" plus a view-only role is the default for a deck that
+  should not be edited in place.
+- Export back to `.pptx` when the user needs a file; Slides' export does not
+  preserve everything either, so state which version is authoritative.
+- Comments and suggestions do not travel in the `.pptx` round trip.
+
+## When the user asks for a Slides-native link
+
+Deliver the `.pptx` (that is what this pack produces), state the upload path,
+and list the three things to check after import: font substitution, bullet
+indent, chart axes. Claiming a clean conversion without those checks is a guess.

package/assets/skills/office-presentations/tasks/apply-annotations.md

@@ -0,0 +1,83 @@
+# Task: apply an annotation payload
+
+The user draws on a rendered slide and sends back an `office-annotations` block.
+Treat it as a change request with coordinates, not as editor state.
+
+## 1. Re-create the geometry the user drew on
+
+Annotations refer to the preview the user saw. Render the same way so the
+coordinates mean the same thing:
+
+```bash
+"<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview
+```
+
+Slide index = `page` in the payload, 1-based. Keep the PNGs — you will compare
+the same slide before and after.
+
+## 2. Resolve each annotation to shapes
+
+The region is normalised 0–1 on that slide image. Map it to inches:
+
+```
+left_in   = region.left   * slide_width_in
+top_in    = region.top    * slide_height_in
+width_in  = region.width  * slide_width_in
+height_in = region.height * slide_height_in
+```
+
+Then select candidate shapes whose bounding box overlaps that rect, largest
+overlap first:
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json
+```
+
+`geometry.json` lists every shape per slide with `left`, `top`, `width`,
+`height` in inches, plus its text. Two overlapping shapes (a title over a
+background panel) are common: use the annotation's `text` to disambiguate —
+match it against each candidate's text, and prefer an exact or prefix match.
+
+## 3. Decide the smallest edit
+
+| Requirement reads like | Do this |
+|---|---|
+| "change this wording" | run-level replace on that shape ([edit-deck](edit-deck.md)) |
+| "move this down" | set `left/top` on that shape only |
+| "make this bigger" | set font size on the runs of that shape, then re-check fit |
+| "this overlaps the table" | resize the shape, or the table, not the whole slide |
+| "recolour" | change the run colour, not the theme |
+| "add a line here" | the rect is a position, not an insertion point: add the shape at that rect, matching nearby type |
+
+Never restyle a slide to satisfy a region. The region identifies *what*, the
+requirement says *how much*.
+
+## 4. Apply, write a copy, re-render
+
+Mutations go through this pack's tools (`replace_text.py`, `add_slides.py`,
+`core_properties.py`) or a focused `python-pptx` snippet — always to
+`<original>-edited.pptx`.
+
+```bash
+"<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx --find "old" --replace "new" --out deck-edited.pptx
+"<python>" "<skill>/container_tools/render_slides.py" --input deck-edited.pptx --out-dir preview-after
+```
+
+## 5. Confirm, in words
+
+Open the same slide number and check the region now looks right. Report which
+shape you changed, what changed, and the slide number.
+
+## When it cannot be mapped
+
+- Empty region, or no shape overlaps it → say that the region covers blank
+  space and ask what object was meant.
+- Overlapping candidates that `text` does not disambiguate → name both and ask.
+- The requirement is about something the file has no geometry for (a font that
+  is not installed, a transition) → say so plainly.
+- The region covers a chart or table whose values would need to change → state
+  that values come from the data, and ask for the corrected figures rather than
+  editing the rendered numbers.
+
+Never guess silently. "I changed the title on slide 3; the region also touched
+the subtitle, which I left alone" is a good answer. Silence plus a diff is not.