dsh-office-kit 0.4.2 → 0.4.4

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
 

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.