dsh-office-kit 0.4.2 → 0.4.3

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

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

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

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

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

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

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

@@ -2,11 +2,10 @@
 
 ## Mechanics
 
-A connector is a line with two attachment sites. `add_connector` takes a begin
-and end shape *plus* connection indices, which is what makes the line follow the
-boxes when they move. If you pass coordinates instead, the line is a floating
-line: it looks right in the file you made and wrong the first time a box is
-nudged.
+A connector is a line with two attachment sites. `add_connector` takes begin and
+end shapes *plus* connection indices, which is what makes the line follow the
+boxes when they move. Pass coordinates instead and you get a floating line: right
+in the file you made, wrong the first time a box is nudged.
 
 - `MSO_CONNECTOR.STRAIGHT | ELBOW | CURVE`
 - `connector.begin_connect(shape, idx)` / `end_connect(shape, idx)`; `idx` is
@@ -59,19 +58,19 @@ PY
 
 ## Rules
 
-1. Connect sides that face each other: right → left for a row, bottom → top for
-   a column. A line crossing its own boxes reads as an error.
+1. Connect facing sides: right → left for a row, bottom → top for a column. A
+   line crossing its own boxes reads as an error.
 2. Elbow connectors for orthogonal flows, straight for a single hop, curve almost
    never.
-3. Two crossing connectors in one diagram is the point where the diagram becomes
-   a picture of a diagram; split it.
+3. Two crossing connectors in one diagram makes it a picture of a diagram; split
+   it.
 4. Label the connector ("12 min", "auto") with a small textbox near its middle,
    not with arrow direction alone.
 
 ## Pitfalls this avoids
 
 - `add_connector` with free coordinates: the line is positioned but unattached,
-  and the deck's own edits break it silently.
+  and later edits break it silently.
 - Arrowhead index confusion: arrowhead values are a bitmask enum, not a boolean.
 - Connectors behind filled shapes because they were added before the boxes.
 
@@ -79,5 +78,5 @@ PY
 
 There is no connector verb in `pptx create`; this recipe is the route. After
 building, `container_tools/inspect_presentation_layout_geometry.py` flags
-`connector_over_text` when a line crosses a text shape, which is the failure
-mode you cannot see in a thumbnail.
+`connector_over_text` when a line crosses a text shape — the failure mode you
+cannot see in a thumbnail.

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

@@ -4,13 +4,13 @@
 
 `add_picture(path, left, top, width=…, height=…)`:
 
-- Give **width only** and the height follows the aspect ratio. Give both and
-  the picture is stretched — a deliberate choice for a full-bleed background,
-  a mistake for a product photo.
+- Give **width only** and the height follows the aspect ratio. Give both and the
+  picture stretches — deliberate for a full-bleed background, a mistake for a
+  product photo.
 - `picture.crop_left/right/top/bottom` are fractions of the *source*; they crop
   without changing the frame, which is how a "cover" fit is done.
-- The bytes live in `ppt/media/`; the same file added twice is stored once,
-  keyed by content hash.
+- The bytes live in `ppt/media/`; the same file added twice is stored once, keyed
+  by content hash.
 - `picture._element.nvPicPr.cNvPr.set("descr", "…")` is the alt text. Decks get
   read aloud and exported; an untagged picture is an empty sentence.
 
@@ -57,11 +57,10 @@ PY
 ## Rules
 
 1. Never upscale past the source resolution: a 900 px wide image at 8 in is
-   ~110 ppi and will look soft on a projector. Check `Image.open(...).size`.
-2. One dominant image per slide. A slide with a hero and three thumbnails is two
-   slides.
-3. Full-bleed backgrounds need text contrast handled deliberately — a dark
-   scrim rectangle between picture and text, not hope.
+   ~110 ppi and looks soft on a projector. Check `Image.open(...).size`.
+2. One dominant image per slide. A hero plus three thumbnails is two slides.
+3. Full-bleed backgrounds need deliberate text contrast — a dark scrim rectangle
+   between picture and text, not hope.
 4. Alt text on every picture, in the language of the deck.
 
 ## Pitfalls this avoids
@@ -70,8 +69,8 @@ PY
   name as the cause.
 - `add_picture` after the text: the picture covers the words. Add backgrounds
   first, or move them to index 2.
-- Re-using a screenshot of a chart or a table as "evidence": it is unreadable at
-  projector size and unverifiable. Use a native chart or table.
+- Re-using a screenshot of a chart or table as "evidence": unreadable at
+  projector size, unverifiable. Use a native chart or table.
 
 ## CLI fast path
 

package/assets/skills/office-presentations/recipes/master-and-layouts.md

@@ -2,15 +2,15 @@
 
 ## Mechanics
 
-A deck has three levels, and where you make a change decides how many slides it
+A deck has three levels; where you make a change decides how many slides it
 fixes:
 
-- **Slide master** (`ppt/slideMasters/`) — theme fonts, colours, background,
-  and the shapes every slide inherits (title bar, accent rule, logo).
+- **Slide master** (`ppt/slideMasters/`) — theme fonts, colours, background, and
+  the shapes every slide inherits (title bar, accent rule, logo).
 - **Slide layout** (`ppt/slideLayouts/`) — one per slide family (title, title and
   content, section, blank…), each with named placeholders at fixed rects.
-- **Slide** — holds its own shapes plus *placeholder overrides*: text, and also
-  position, if someone dragged a placeholder.
+- **Slide** — its own shapes plus *placeholder overrides*: text, and position if
+  someone dragged a placeholder.
 
 Editing a placeholder's *text* is a per-slide change. Editing the layout's
 placeholder *rect* moves that frame on every slide of that family. Editing the
@@ -20,9 +20,9 @@ master's background moves it everywhere.
 To change a slide's family, delete it and add a new one from the target layout —
 losing its content, so plan families before filling them.
 
-**One quirk to know:** `master.shapes` and `layout.shapes` are read-only in
-`python-pptx` (`MasterShapes` has no `add_shape`). Chrome shapes are therefore
-built on a scratch slide and their XML moved into the master's shape tree.
+**One quirk:** `master.shapes` and `layout.shapes` are read-only in `python-pptx`
+(`MasterShapes` has no `add_shape`). Build chrome shapes on a scratch slide and
+move their XML into the master's shape tree.
 
 ## Recipe: restyle a family from the master
 
@@ -88,36 +88,36 @@ print("removed:", removed)
 PY
 ```
 
-This is what clears the `empty_placeholder` review finding in
+This clears the `empty_placeholder` review finding in
 `container_tools/inspect_presentation_layout_geometry.py`. Keep a placeholder you
 still intend to fill, and never delete the one slide numbers are linked to.
 
 ## Reusing the source's own layouts
 
-When the user supplies a template, do not rebuild its look — put content into
-its placeholders. The inspection script prints each layout's placeholders with
-index, kind and rect, which is what you need to address them:
+With a supplied template, do not rebuild its look — put content into its
+placeholders. The inspection script prints each layout's placeholders with index,
+kind and rect, which is what you need to address them:
 
 ```bash
 "<python>" container_tools/inspect_presentation_layout_geometry.py --input template.pptx --json-out geometry.json
 ```
 
 Then address a placeholder by index on the slide:
-`slide.placeholders[1].text = "..."`. Slides created from a layout always have
-a placeholder for every non-empty slot, so index-based addressing is stable.
+`slide.placeholders[1].text = "..."`. Slides created from a layout always have a
+placeholder for every non-empty slot, so index-based addressing is stable.
 
 ## Pitfalls this avoids
 
 - Drawing the accent rule on every slide instead of the master: one edit later,
   half the deck has two rules.
-- Dragging a placeholder on a slide to fix one frame; the layout is untouched
-  and the next slide of the same family misbehaves again.
+- Dragging a placeholder on a slide to fix one frame; the layout is untouched and
+  the next slide of the same family misbehaves again.
 - Appending the scratch shape to the master without `drop_rel`: the orphan slide
   part stays in the package and `inspect_presentation_package_integrity.py`
   reports a slide count mismatch.
 - Adding a *blank* slide and a floating textbox where the template has a title
-  placeholder: the deck no longer answers to its own master, and the outline
-  view is empty.
+  placeholder: the deck no longer answers to its own master, and the outline view
+  is empty.
 
 ## CLI fast path
 

package/assets/skills/office-presentations/recipes/native-charts.md

@@ -4,7 +4,7 @@
 
 A chart added with `slide.shapes.add_chart` is a real chart part
 (`ppt/charts/chartN.xml`) with an embedded workbook
-(`ppt/embeddings/*.xlsx`). That matters for three reasons:
+(`ppt/embeddings/*.xlsx`). That matters:
 
 - The audience can edit the numbers in PowerPoint; a picture of a chart cannot.
 - The data is in the file, so a gate can check it. A screenshot cannot be
@@ -12,9 +12,9 @@ A chart added with `slide.shapes.add_chart` is a real chart part
 - The chart inherits the slide's theme for colour and type, so charts match the
   deck without per-chart styling.
 
-`CategoryChartData` holds the numbers; `chart.plots[0]` holds the geometry of
-the marks. Category order is the series' own order — sort before you pass it,
-because a chart does not sort.
+`CategoryChartData` holds the numbers; `chart.plots[0]` holds the geometry of the
+marks. Category order is the series' own order — sort before you pass it, because
+a chart does not sort.
 
 ## Recipe
 
@@ -63,18 +63,18 @@ PY
 ## Rules for charted numbers
 
 1. One idea per chart. Two series is fine; six is a table.
-2. No chart title that repeats the slide title — the title says what the chart
+2. No chart title repeating the slide title — the slide title says what the chart
    *means* ("Throughput rose while touches fell"), the chart shows the numbers.
 3. Start the value axis at zero for bars, and say so in the notes if you do not.
 4. Data labels beat a value axis grid; pick one, not both.
-5. Never leave the default "Chart Title" placeholder text in a shipped deck.
+5. Never leave the default "Chart Title" text in a shipped deck.
 
 ## Pitfalls this avoids
 
 - `number_format` without `number_format_is_linked = False` reverts to the
   workbook's format the next time PowerPoint refreshes the chart.
-- `legend.include_in_layout = False` is what stops the legend from stealing
-  plot height and squashing the bars.
+- `legend.include_in_layout = False` stops the legend stealing plot height and
+  squashing the bars.
 - Deleting the embedded workbook (by zipping/unzipping carelessly) turns the
   chart into an uneditable picture in every downstream viewer.
 

package/assets/skills/office-presentations/recipes/rich-text-runs.md

@@ -9,11 +9,11 @@ replaces every run, so **format runs, never paragraphs**:
 - `paragraph.text = "x"` — one run, all previous formatting gone.
 - `run = paragraph.add_run(); run.text = "x"; run.font.bold = True` — formatting
   survives and can differ inside the paragraph.
-- `paragraph.font.size` is not a thing PowerPoint respects for mixed content; it
+- `paragraph.font.size` is not something PowerPoint respects for mixed content; it
   sets the default for later runs only. Set the size on every run you add.
 
-Paragraph-level properties (`alignment`, `level`, `space_after`,
-`line_spacing`) apply to the whole paragraph and are safe to set once.
+Paragraph-level properties (`alignment`, `level`, `space_after`, `line_spacing`)
+apply to the whole paragraph and are safe to set once.
 
 ## Recipe
 
@@ -62,22 +62,22 @@ PY
 
 ## Rules
 
-1. A number you want the reader to remember gets its own run, and usually a
-   weight change — not a second bullet.
+1. A number the reader should remember gets its own run, usually with a weight
+   change — not a second bullet.
 2. Superscripts, footnote markers and unit symbols are runs, not characters
    smuggled into the sentence.
-3. Keep one family of emphasis per deck: bold+accent for numbers, italic+muted
-   for provenance. Three competing emphases read as decoration.
-4. Strings that repeat (units, currency, product names) belong in a variable so
-   a later edit does not leave two spellings.
+3. One family of emphasis per deck: bold+accent for numbers, italic+muted for
+   provenance. Three competing emphases read as decoration.
+4. Repeated strings (units, currency, product names) belong in a variable so a
+   later edit does not leave two spellings.
 
 ## Pitfalls this avoids
 
 - `paragraph.text = "Total: "` then `add_run()`: the first assignment already
-  replaced the frame's runs, so formatting set beforehand is gone.
-- A run with no `font.size` inherits the layout's size, which is 44 pt on a
-  title layout — footnote markers become headlines.
-- Building the paragraph by f-string with `**` markers that PowerPoint does not
+  replaced the frame's runs, so earlier formatting is gone.
+- A run with no `font.size` inherits the layout's size, which is 44 pt on a title
+  layout — footnote markers become headlines.
+- Building the paragraph by f-string with `**` markers PowerPoint does not
   interpret; markup in a deck is a run, not a syntax.
 
 ## CLI fast path

package/assets/skills/office-presentations/recipes/speaker-notes.md

@@ -6,10 +6,10 @@ Notes live in `ppt/notesMasters/` plus one `ppt/notesSlides/notesSlideN.xml` per
 slide, tied to the slide by a relationship. In `python-pptx` this is
 `slide.notes_slide.notes_text_frame` — the notes slide is created on first
 access, so reading it in a loop silently adds one per slide. Only touch it when
-you are writing.
+writing.
 
-Notes are not visible in the render. That means a notes problem cannot be caught
-by looking at the PNGs: check them with `pptx read` or by reading the XML back.
+Notes are invisible in the render, so a notes problem cannot be caught by looking
+at the PNGs: check them with `pptx read` or by reading the XML back.
 
 ## Recipe
 
@@ -45,21 +45,21 @@ PY
   12 sites").
 - The answer to the question the slide invites.
 - Nothing that belongs on the slide: if the audience needs it, put it on the
-  slide, notes are invisible when the deck is sent as a PDF.
+  slide — notes are invisible when the deck is sent as a PDF.
 
 ## Pitfalls this avoids
 
 - Iterating `prs.slides` and *reading* `notes_slide` on a template with none:
   every slide gains an empty notes part and the file grows.
 - Long notes pasted as one paragraph with line breaks that only look like
-  paragraphs; each intended paragraph should be `add_paragraph()` so the notes
-  pane and the presenter view indent them.
+  paragraphs; use `add_paragraph()` per intended paragraph so the notes pane and
+  presenter view indent them.
 - Assuming notes render into the preview: they do not, so verify them from the
   file.
 
 ## CLI fast path
 
 `pptx create` writes slides without notes. The recipe above is the route; then
-`pptx read --input deck-notes.pptx` does not print notes, so read them back with
+`pptx read --input deck-notes.pptx` does not print notes, so read them back from
 `ppt/slides` sibling `notesSlide` parts via
 `inspect_presentation_package_integrity.py` (it counts `notesSlides`).

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

@@ -6,11 +6,11 @@ A table in a deck is a grid of cells on a canvas; it does not reflow. Three
 properties decide whether it reads as a table or as soup:
 
 - **Column widths** are the layout. `table.columns[i].width = Inches(3.2)` —
-  setting them is mandatory, because `add_table` splits the width evenly.
+  mandatory, because `add_table` splits the width evenly.
 - **Row heights** are a minimum. Text taller than the row pushes it open, which
-  then runs into whatever sits below.
+  runs into whatever sits below.
 - **Cell margins** default to 0.1 in left/right and 0.05 in top/bottom on a
-  0.5 in row, which is most of the row. Reduce them when rows are tight.
+  0.5 in row — most of the row. Reduce them when rows are tight.
 
 Header row emphasis (`table.first_row = True`) is a table style switch, not a
 formatting guess: it turns on the theme's header fill and bold.
@@ -66,23 +66,23 @@ PY
 
 ## Numbers people trust
 
-- Right-align numeric columns, left-align the label column, and keep decimals
+- Right-align numeric columns, left-align the label column, keep decimals
   consistent per column (`553`, not `553.0` next to `171`).
-- A total row is a claim. Show enough rows that the reader can check it, and
-  let `container_tools/native_table_arithmetic_gate.py` prove it from the file.
-- Units belong in the header (`Orders`, `Touches`), not repeated in every cell.
-- Money keeps its currency in the header or the first row; `¥1,240` in every
-  cell of a dense table is noise.
+- A total row is a claim. Show enough rows that the reader can check it, and let
+  `container_tools/native_table_arithmetic_gate.py` prove it from the file.
+- Units belong in the header (`Orders`, `Touches`), not in every cell.
+- Money keeps its currency in the header or first row; `¥1,240` in every cell of
+  a dense table is noise.
 
 ## Pitfalls this avoids
 
 - Even column widths turning "Q1" into a 4 in column while numbers crowd.
-- A table whose declared height is smaller than its content: the last row is
-  drawn below the intended block and collides with the footer.
+- A declared height smaller than the content: the last row is drawn below the
+  intended block and collides with the footer.
 - Colouring cells individually instead of letting `first_row` do the header.
 
 ## CLI fast path
 
-`pptx create` accepts `{"table": {"headers": [...], "rows": [[...]]}}` and
-places it at 0.8 in from the left, full content width, at the running cursor.
-For a chosen rect, column widths or right-aligned numbers, use the recipe.
+`pptx create` accepts `{"table": {"headers": [...], "rows": [[...]]}}` and places
+it at 0.8 in from the left, full content width, at the running cursor. For a
+chosen rect, column widths or right-aligned numbers, use the recipe.

package/assets/skills/office-presentations/recipes/textbox-at-coordinate.md

@@ -7,10 +7,10 @@ what you see:
 
 - `left`/`top` are the **top-left corner** of the frame, not of the glyphs. A
   28 pt line has roughly 4 pt of space above the cap height inside its frame.
-- `width` is the wrap width. `word_wrap = True` must be set explicitly on a new
-  box or long lines run past the slide edge instead of wrapping.
+- `width` is the wrap width. Set `word_wrap = True` explicitly on a new box or
+  long lines run past the slide edge instead of wrapping.
 - `height` is the *frame*, not the content: PowerPoint lets text spill below it
-  (which overlaps whatever is under the box) unless autosize is turned on.
+  (overlapping whatever is under the box) unless autosize is on.
 - Interior margins default to 0.1 in left/right and 0.05 in top/bottom. Setting
   them to 0 makes the rect mean exactly what you measured.
 
@@ -44,10 +44,10 @@ PY
 
 ## Measuring before you place
 
-Do not guess whether the text fits — compute it. A line of 28 pt text fits
-about `width_in * 96 / (0.55 * 28)` characters (0.55 average advance for a
-humanist sans), and each line needs `1.2 * 28 / 72` inches of height. Leave the
-estimate in the script, then let the render confirm it.
+Do not guess whether the text fits — compute it. A line of 28 pt text fits about
+`width_in * 96 / (0.55 * 28)` characters (0.55 average advance for a humanist
+sans), and each line needs `1.2 * 28 / 72` inches of height. Leave the estimate
+in the script, then let the render confirm it.
 
 ```python
 def fits(text: str, width_in: float, height_in: float, size_pt: float) -> bool:
@@ -58,8 +58,8 @@ def fits(text: str, width_in: float, height_in: float, size_pt: float) -> bool:
 
 ## Pitfalls this avoids
 
-- A box sized to the text at 18 pt, later edited to 32 pt, now overlaps the
-  table below. Frame height follows the *largest* run, so size text first.
+- A box sized to text at 18 pt, later edited to 32 pt, now overlaps the table
+  below. Frame height follows the *largest* run, so size text first.
 - `add_textbox` with `width=Inches(13.3)` on a 13.333 in slide plus default
   margins = 0.2 in of overflow past the right edge. Subtract the margins.
 - `MSO_ANCHOR.MIDDLE` on a title looks intentional on a cover and wrong on a

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

@@ -10,10 +10,9 @@ The theme part (`ppt/theme/theme1.xml`) holds two palettes and two font lists:
 - `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.
+Write `RGBColor.rgb` when a colour must never change; reference a theme colour
+when the user may re-skin the deck. A deck with hard-coded hex everywhere cannot
+be re-branded — usually why the user supplied a template.
 
 ## Recipe: define the palette once, use it everywhere
 
@@ -73,12 +72,12 @@ 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.
+- Two similar hexes drifting apart across slides (`#161d28` here, `#171e29`
+  there) 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.
+- `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