dsh-office-kit 0.4.2 → 0.4.3

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

@@ -1,65 +1,60 @@
 # Authoring workflow
 
-## What a deck is, mechanically
+## What a deck is
 
-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.
+A `.pptx` is a zip of XML parts: `presentation.xml` (slide order), one part per
+slide, a slide master per theme, a layout per family, chart parts with embedded
+workbooks, notes parts, a media folder. Read the file back; never trust the code
+that wrote it.
 
-Three consequences shape the whole workflow:
+Three consequences:
 
-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
+1. **Geometry is explicit.** Nothing reflows on open except autofit; shapes that
+   overlap in XML overlap on screen.
+2. **Inheritance is real.** A slide draws 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.
+   decision; at master level a deck decision.
+3. **Data stays alive.** A native chart or table keeps its numbers 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
+1. **Decide the story.** One sentence per slide, in order, before any XML.
+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.
+4. **Fill or delete every placeholder.** An empty one shows 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
+## Layout numbers
 
-| 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 |
+Type, colour and density: [style-guidelines](style-guidelines.md).
 
-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.
+| Value | Rule |
+|---|---|
+| Slide size | 13.333 × 7.5 in (16:9); 10 × 5.625 in for "wide" templates |
+| Margin | 0.6–0.9 in; below 0.5 in a projector crops it |
+| 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 |
 
-## Deciding slide count
+One unit only: `Inches(x)` in code, `x * 914400` for raw XML. Never mix EMU and
+inches.
 
-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.
+## Deciding slide count
 
-A presentation of N minutes needs roughly N/2 content slides at 60–90 seconds
-each, plus a cover and a closing ask.
+One idea per slide; two competing headlines is two slides. One headline plus a
+table too large for 14 pt makes the table an appendix, and the body slide states
+the conclusion in one line. N minutes ≈ 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).
+- Type, colour, density, 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).
+- Charts, tables and notes: [native-evidence](native-evidence.md).
 - Supplied templates: [templates](templates.md).
 - Pre-delivery checklist: [finalization](finalization.md).

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

@@ -1,7 +1,6 @@
 # Finalization checklist
 
-Run this before `present`. It exists because every item on it has shipped a
-broken deck at least once.
+Run this before `present`. Every item has shipped a broken deck at least once.
 
 ## The file
 
@@ -12,19 +11,18 @@ broken deck at least once.
 - [ ] 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).
+      (an untitled deck shows as "PowerPoint Presentation" in every file list).
 
 ## The content
 
-- [ ] Every placeholder is filled or deleted — no "Click to add text".
+- [ ] Every placeholder 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.
+- [ ] Numbers in the deck agree with the source data at the precision shown.
 - [ ] Speaker notes carry the provenance of the non-obvious numbers.
 
 ## The layout
@@ -34,7 +32,7 @@ broken deck at least once.
       → `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.
+- [ ] Body text at least 18 pt, captions at least 12 pt.
 - [ ] One idea per slide, one emphasis per paragraph.
 
 ## The look
@@ -46,7 +44,7 @@ broken deck at least once.
 - [ ] 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.
+- [ ] Cover and closing slide both say something.
 
 ## Delivery
 
@@ -57,7 +55,7 @@ broken deck at least once.
 
 ## 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.
+`render_slides.py --engine draft` draws a PyMuPDF geometry preview when no office
+suite is installed. 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

@@ -8,24 +8,21 @@ A bullet is a claim, not a label. Two forms work:
   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.
+Forms that fail: a single noun ("Efficiency"), a truncated clause ("Picking
+accounts for…"), three adjectives in a row, 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.
+- No sub-sub-bullets. A bullet needing a child means 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:
+Bullets are paragraph properties, not characters. A typed bullet ("• Picking…")
+cannot re-indent, cannot change level, and looks unlike every other bullet.
 
 ```python
 "<python>" - <<'PY'
@@ -64,15 +61,14 @@ 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.
+The `marL`/`indent` pair pulls a wrapped bullet's second line 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.
+- Bullets as a script: a slide is not a transcript; the speaker notes are.
+- Fake bullets via "– " or "→ " prefixes; they do not indent.
+- Six bullets of equal weight where one is the point. Make the point the title,
+  the bullets the evidence.
+- Numbered lists where order does not matter, bullets where it does.

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

@@ -1,7 +1,7 @@
 # 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.
+"Evidence" is anything on a slide that claims a fact: a number, a chart, a table,
+a quotation. These rules keep it checkable.
 
 ## Native or it did not happen
 
@@ -12,56 +12,42 @@ table, a quotation. The rules below keep it checkable.
 | 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.
+The wrong column is unreadable at projector size and unverifiable. Native charts
+and tables keep their numbers in the package, which is what lets the
+quantitative-chart and table-arithmetic gates check them
+([inspect-and-verify](../tasks/inspect-and-verify.md)).
 
 ## 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.
+  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.
+- Label the few numbers that matter, not every point; ten data labels is a table
+  with rounded corners.
+- One axis. Two y-axes 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.
+- Header row bold and distinct; total row 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.
+- No units in every cell; units in the header.
+- A table over 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.
+Notes hold "where did this number come from", so the presenter can answer without
+turning the slide into a footnote.
 
-- One note per non-obvious number: source, date range, and any caveat.
+- One note per non-obvious number: source, date range, 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

@@ -2,8 +2,8 @@
 
 ## 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.
+Three sizes: title, body, caption. A fourth is a decision the audience will make
+wrongly.
 
 | Role | Size | Weight | Colour |
 |---|---|---|---|
@@ -13,54 +13,49 @@ audience has to make, and they will make it wrongly.
 | Lead-in number | Same as body + bold | Bold | Accent |
 | Caption, source | 12–14 pt | Regular | Muted |
 
-Rules that carry the rest:
+44 pt belongs to covers; content titles stay 28–36 pt.
 
-- One typeface family. A second family means "different voice", so use it for
-  one thing (a quote, a code line) and nothing else.
+- One typeface family. A second family means "different voice": 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.
+- All-caps suits a 2–4 word label; in a sentence it is a readability tax.
+- Left-align body text. Centred paragraphs over two lines are hard to track back.
 
 ## 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.
+- One ink, one muted, one accent, plus the template's rule colour. More and the
+  accent stops meaning "look here".
+- Contrast is a correctness issue: body on white needs dark ink (≈4.5:1), and
+  text over a photograph needs a scrim, not luck.
+- Never encode meaning in colour alone: an accent bar also needs an arrow or a
+  word.
+- Chart series colours come from the theme; a sixth series colour signals 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.
+- Body blocks stop at about 6 lines of 18 pt on a 16:9 slide.
+- A slide table reads at about 7 rows × 4 columns. Beyond that it is an appendix,
+  and the slide carries the one row that matters.
+- Keep 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.
+sets the tone. Keep the roles separate.
 
 - 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.
+- Photographic visual: scrim it at 40–60% black under the text rather than
+  hoping the text lands on a dark region.
+- No suitable image: 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: an amber accent means an amber-bearing visual, 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.
+wastes the slot the audience looks at while gathering their things.

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

@@ -1,76 +1,47 @@
 # 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".
+A template already answers branding, type scale, slide families and chrome. Put
+the user's content into the template's own slides and leave 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.
+Commands, JSON shapes and gate flags: [tasks/template-following.md](../tasks/template-following.md).
+This file is the reasoning behind that procedure.
+
+1. **Inspect** with `inspect_template_deck.py`. 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 families** you need — cover, section, content, table, chart,
+   closing. Take the *fewest* source slides that cover those roles.
+3. **Write the frame map**: a JSON plan naming, per output slide, the source
+   slide it duplicates and what happens to each element (`rewrite`,
+   `rewrite-and-reposition`, `fill-placeholder`, `replace`, `delete`, `keep`).
+4. **Validate** with `validate_template_plan.py`: 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 with `prepare_template_starter_deck.py`: only the
+   slides you kept, in your order, with placeholders filled. Extend it with
+   `container_tools/add_slides.py` and the recipes.
+6. **Check fidelity** with `check_template_fidelity.py` and
+   `template_source_fidelity_gate.py`. 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.
+prints every shape's rect in inches — what you address when a 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.
+- Never restyle the master to match a screenshot. 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.
+  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

@@ -1,6 +1,6 @@
 # Handing a deck to Google Slides
 
-Google Slides imports `.pptx`, and mostly survives it. What it does not survive
+Google Slides imports `.pptx` and mostly survives it. What it does not survive
 is worth designing around.
 
 ## What converts cleanly
@@ -25,10 +25,10 @@ is worth designing around.
 
 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
+3. Upload to Drive, open with Google Slides, and check in this 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.
+4. If others will edit the deck in Slides, keep shapes distinct and named
+   (right-click → rename) so comments and edits are unambiguous.
 
 ## Sharing
 

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

@@ -12,8 +12,8 @@ coordinates mean the same thing:
 "<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.
+Slide index = `page` in the payload, 1-based. Keep the PNGs to compare the same
+slide before and after.
 
 ## 2. Resolve each annotation to shapes
 
@@ -26,17 +26,17 @@ 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:
+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.
+`geometry.json` lists every shape per slide with `left`, `top`, `width`, `height`
+in inches, plus its text. Overlapping shapes (a title over a background panel)
+are common: use the annotation's `text` to disambiguate — prefer an exact or
+prefix match.
 
 ## 3. Decide the smallest edit
 
@@ -66,18 +66,18 @@ Mutations go through this pack's tools (`replace_text.py`, `add_slides.py`,
 ## 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.
+shape 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.
+- Empty region, or no shape overlaps it → say 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 requirement is about something the file has no geometry for (an uninstalled
+  font, 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.
+  that values come from the data, and ask for corrected figures rather than
+  editing 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.
+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.