dsh-office-kit 0.4.1 → 0.4.3

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.

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

@@ -1,7 +1,6 @@
 # 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.
+One rule across all three: the numbers must be checkable from the file.
 
 ## Charts
 
@@ -11,19 +10,18 @@ Native, always:
 "<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).
+Or the [native-charts recipe](../recipes/native-charts.md) when you need control
+of axis, labels or legend.
 
-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`.
+Spec keys: `type` (`bar`/`column`/`line`/`pie`; 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.
+- Categories in the order the reader thinks in. Bars start at zero.
+- A chart duplicating a table on a neighbouring slide is a review finding, not a
+  second view — pick one.
 
 Verify:
 
@@ -35,8 +33,8 @@ Verify:
 ## 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.
+full width; the [tables recipe](../recipes/tables.md) gives the rect, column
+widths, alignment and total-row styling.
 
 Rules: numbers right-aligned, units in the header, total row computed not typed,
 seven rows maximum on a slide.
@@ -47,8 +45,8 @@ Declare each total so it can be proved:
 "<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.
+A mismatch 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
 
@@ -65,15 +63,14 @@ confirm they landed:
 "<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.
+`notesSlides` must 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.
+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.
+A results slide 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

@@ -5,10 +5,10 @@
 - 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.
+- Brand: a template file, a colour, or the defaults in
+  [style-guidelines](../references/style-guidelines.md).
+- Evidence: numbers, charts, tables, images the user has. Never invent a metric —
+  if a number is needed and missing, say so.
 
 ## Route
 
@@ -65,21 +65,20 @@ For the ordinary deck (cover, bullets, section, table, chart, image, closing):
 }
 ```
 
-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).
+Layouts: `title`, `bullets`, `section`, `title_only`, `blank`. Tables sit 0.8 in
+from the left at the running cursor and cannot be positioned — give a table 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)
+Anything at a coordinate, any crop, connector or master change is a `python-pptx`
+snippet: [textbox at a coordinate](../recipes/textbox-at-coordinate.md),
+[auto-layout](../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:
 
@@ -100,7 +99,8 @@ template's look by hand.
 
 ## 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
+Story first: the one-sentence claim for every slide, in order, then fill the
+frames (loop in [authoring-workflow](../references/authoring-workflow.md)). A
+claim needing two sentences is two slides. Bullets are claims
+([native-bullets](../references/native-bullets.md)); evidence is native
 ([native-evidence](../references/native-evidence.md)).

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

@@ -2,7 +2,7 @@
 
 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.
+plus the recipes for anything structural.
 
 **Never write over the original.** Every tool defaults to
 `<original>-edited.pptx`; keep that default unless the user names a path.
@@ -14,9 +14,8 @@ plus the recipes for everything structural.
 "<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.
+`pptx read` gives titles, text, tables and chart data per slide; the geometry
+gate gives every shape's rect in inches, to decide whether a new block fits.
 
 ## 2. Text changes: run-level replace
 
@@ -41,11 +40,11 @@ Batch form:
 "<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.
+A pattern matches **inside a single run** only. Text PowerPoint split for
+formatting ("**Q4** 2025") will not match "Q4 2025" and the report lists it under
+`unmatched`. When a pattern cannot match, 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.
@@ -56,10 +55,9 @@ Exit code 1 means a pattern matched nothing; the file is still written, so read
 "<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.
+The spec uses the same slide object as `pptx create` (`layout`, `title`,
+`subtitle`, `bullets`, `table`, `chart`, `image`). Outside that vocabulary, add
+the slide with `add_slides.py`, then place content with a recipe.
 
 ## 4. Metadata
 
@@ -72,7 +70,7 @@ recipe.
 
 | Change | Route |
 |---|---|
-| Move or resize a shape | recipe: set `.left/.top/.width/.height` on the shape from `slide.shapes` |
+| Move or resize a shape | set `.left/.top/.width/.height` 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 |
@@ -89,5 +87,5 @@ relational:
 "<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.
+Then look at the changed pages. A replacement that pushes a title onto a third
+line is a layout change, not a text change.