dsh-office-kit 0.2.0 → 0.3.1

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

@@ -0,0 +1,83 @@
+# Connectors
+
+## 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.
+
+- `MSO_CONNECTOR.STRAIGHT | ELBOW | CURVE`
+- `connector.begin_connect(shape, idx)` / `end_connect(shape, idx)`; `idx` is
+  the site index on the shape's outline (0 = top, 1 = left, 2 = bottom,
+  3 = right for a rectangle).
+- Arrowheads are line properties: `line.end_arrowhead = MSO_ARROWHEAD.TRIANGLE`.
+
+## Recipe
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.shapes import MSO_SHAPE, MSO_CONNECTOR
+from pptx.dml.color import RGBColor
+from pptx.enum.dml import MSO_LINE_DASH_STYLE
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+def box(left, top, text, width=2.6, height=1.1):
+    shape = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, Inches(left), Inches(top), Inches(width), Inches(height))
+    shape.text_frame.text = text
+    shape.text_frame.paragraphs[0].font.size = Pt(14)
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = RGBColor(0xF2, 0xF5, 0xF9)
+    shape.line.color.rgb = RGBColor(0xC8, 0xD2, 0xDF)
+    return shape
+
+order = box(0.9, 2.2, "Order booked")
+pick = box(4.4, 2.2, "Picked")
+ship = box(7.9, 2.2, "Shipped")
+
+for start, end in ((order, pick), (pick, ship)):
+    connector = slide.shapes.add_connector(
+        MSO_CONNECTOR.STRAIGHT, 0, 0, Inches(0.1), Inches(0.1)
+    )
+    connector.begin_connect(start, 3)   # right edge
+    connector.end_connect(end, 1)       # left edge
+    connector.line.width = Pt(2)
+    connector.line.color.rgb = RGBColor(0x5F, 0x6B, 0x7A)
+    connector.line.end_arrowhead = 3    # triangle
+
+prs.save("connectors.pptx")
+from pptx.oxml.ns import qn
+print("connectors:", sum(1 for s in slide.shapes if s._element.tag == qn("p:cxnSp")))
+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.
+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.
+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.
+- Arrowhead index confusion: arrowhead values are a bitmask enum, not a boolean.
+- Connectors behind filled shapes because they were added before the boxes.
+
+## CLI fast path
+
+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.

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

@@ -0,0 +1,80 @@
+# Images
+
+## Mechanics
+
+`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.
+- `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.
+- `picture._element.nvPicPr.cNvPr.set("descr", "…")` is the alt text. Decks get
+  read aloud and exported; an untagged picture is an empty sentence.
+
+## Recipe: cover-fit into a fixed frame
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches
+from PIL import Image
+
+def cover(picture, frame_w_in, frame_h_in, source_w, source_h):
+    """Crop the picture so it fills the frame without distortion."""
+    frame_ratio = frame_w_in / frame_h_in
+    source_ratio = source_w / source_h
+    if source_ratio > frame_ratio:          # too wide: crop the sides
+        keep = frame_ratio / source_ratio
+        picture.crop_left = picture.crop_right = (1 - keep) / 2
+    elif source_ratio < frame_ratio:        # too tall: crop top and bottom
+        keep = source_ratio / frame_ratio
+        picture.crop_top = picture.crop_bottom = (1 - keep) / 2
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+with Image.open("aisle.png") as image:
+    source_w, source_h = image.size
+
+frame = slide.shapes.add_picture("aisle.png", Inches(0.9), Inches(1.7), Inches(8.0), Inches(4.5))
+cover(frame, 8.0, 4.5, source_w, source_h)
+frame._element.nvPicPr.cNvPr.set("descr", "Racking aisle in the pilot cell at peak hour")
+
+# full-bleed background, sent to the back
+background = slide.shapes.add_picture("aisle.png", 0, 0, prs.slide_width, prs.slide_height)
+tree = slide.shapes._spTree
+tree.remove(background._element)
+tree.insert(2, background._element)
+prs.save("image.pptx")
+print("placed", source_w, "x", source_h)
+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.
+4. Alt text on every picture, in the language of the deck.
+
+## Pitfalls this avoids
+
+- Passing both width and height and getting a squashed photograph nobody can
+  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.
+
+## CLI fast path
+
+`pptx create` accepts `{"image": {"path": "...", "left": 0.9, "top": 1.6,
+"width": 8.0}}` and derives the height from the aspect ratio — no crop, no alt
+text. Cropping, alt text and background placement are the recipe's job.

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

@@ -0,0 +1,127 @@
+# Masters, layouts and slide families
+
+## Mechanics
+
+A deck has three levels, and 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 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.
+
+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
+master's background moves it everywhere.
+
+`slide.slide_layout` is read-only; the family is fixed when the slide is created.
+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.
+
+## Recipe: restyle a family from the master
+
+```python
+"<python>" - <<'PY'
+import copy
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+from pptx.enum.shapes import MSO_SHAPE
+
+prs = Presentation("template.pptx")
+master = prs.slide_masters[0]
+
+master.background.fill.solid()
+master.background.fill.fore_color.rgb = RGBColor(0x0F, 0x17, 0x22)
+
+# Chrome rule on every slide: build it on a scratch slide, move the XML, drop the slide.
+scratch = prs.slides.add_slide(prs.slide_layouts[6])
+rule = scratch.shapes.add_shape(MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), Inches(13.333), Inches(0.06))
+rule.fill.solid()
+rule.fill.fore_color.rgb = RGBColor(0xE0, 0x9B, 0x2D)
+rule.line.fill.background()
+master.shapes._spTree.append(copy.deepcopy(rule._element))
+
+slide_id = prs.slides._sldIdLst[-1]
+prs.part.drop_rel(slide_id.rId)
+prs.slides._sldIdLst.remove(slide_id)
+
+# Move the title frame for one family only.
+layout = next(l for l in master.slide_layouts if "title and content" in l.name.lower())
+title = next(p for p in layout.placeholders if p.placeholder_format.idx == 0)
+title.left, title.top = Inches(0.9), Inches(0.55)
+title.width, title.height = Inches(11.5), Inches(1.0)
+for paragraph in title.text_frame.paragraphs:
+    paragraph.font.size = Pt(32)
+    paragraph.font.bold = True
+
+prs.save("restyled.pptx")
+print("layouts:", [l.name for l in master.slide_layouts], "slides:", len(prs.slides))
+PY
+```
+
+## Recipe: delete the empty placeholders a layout leaves behind
+
+A layout hands every slide a placeholder, filled or not. Section and title-only
+layouts carry body slots that are empty by design; in edit view they print "Click
+to add text" and there is no CLI verb for removing them, so do it in code:
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+
+prs = Presentation("deck.pptx")
+removed = []
+for index, slide in enumerate(prs.slides, start=1):
+    for placeholder in list(slide.placeholders):
+        if placeholder.has_text_frame and not placeholder.text_frame.text.strip():
+            removed.append((index, placeholder.placeholder_format.idx, placeholder.name))
+            placeholder._element.getparent().remove(placeholder._element)
+prs.save("deck-cleaned.pptx")
+print("removed:", removed)
+PY
+```
+
+This is what 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:
+
+```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.
+
+## 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.
+- 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.
+
+## CLI fast path
+
+`pptx create --spec` starts from the blank default template and maps
+`title|bullets|section|title_only|blank` to built-in layouts. Copying a supplied
+template is `template_following_scripts/prepare_template_starter_deck.py`, which
+keeps and fills the template's own slides.

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

@@ -0,0 +1,87 @@
+# Native charts
+
+## Mechanics
+
+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:
+
+- 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
+  checked, and nobody notices a wrong screenshot.
+- 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.
+
+## Recipe
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.chart.data import CategoryChartData
+from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION, XL_LABEL_POSITION
+from pptx.util import Inches, Pt
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+data = CategoryChartData()
+data.categories = ["Q1", "Q2", "Q3", "Q4"]
+data.add_series("Orders fulfilled", (100, 128, 154, 171))
+data.add_series("Touches", (410, 402, 386, 371))
+
+frame = slide.shapes.add_chart(
+    XL_CHART_TYPE.COLUMN_CLUSTERED, Inches(0.9), Inches(1.6), Inches(11.5), Inches(5.1), data
+)
+chart = frame.chart
+chart.has_title = True
+chart.chart_title.text_frame.text = "Orders fulfilled per quarter"
+chart.chart_title.text_frame.paragraphs[0].font.size = Pt(14)
+chart.has_legend = True
+chart.legend.position = XL_LEGEND_POSITION.BOTTOM
+chart.legend.include_in_layout = False
+
+plot = chart.plots[0]
+plot.has_data_labels = True
+plot.data_labels.number_format = "0"
+plot.data_labels.number_format_is_linked = False
+plot.data_labels.position = XL_LABEL_POSITION.OUTSIDE_END
+plot.gap_width = 60
+
+chart.value_axis.has_major_gridlines = True
+chart.value_axis.tick_labels.font.size = Pt(11)
+chart.category_axis.tick_labels.font.size = Pt(11)
+prs.save("chart.pptx")
+print("saved chart with", len(chart.series), "series")
+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
+   *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.
+
+## 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.
+- Deleting the embedded workbook (by zipping/unzipping carelessly) turns the
+  chart into an uneditable picture in every downstream viewer.
+
+## CLI fast path
+
+`pptx create` accepts
+`{"chart": {"type": "column", "title": "...", "categories": [...], "series":
+[{"name": "...", "values": [...]}], "left": 0.9, "top": 1.45, "width": 11.5,
+"height": 5.1}}`. The recipe above is the route when you need axis, label or
+legend control.

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

@@ -0,0 +1,86 @@
+# Rich text runs
+
+## Mechanics
+
+Text lives at three levels: `text_frame` → `paragraph` → `run`. A run is a span
+with one formatting state. Assigning `paragraph.text` (or `text_frame.text`)
+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
+  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.
+
+## Recipe
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+from pptx.enum.text import PP_ALIGN
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+box = slide.shapes.add_textbox(Inches(0.9), Inches(2.0), Inches(11.0), Inches(1.6))
+frame = box.text_frame
+frame.word_wrap = True
+
+MUTED = RGBColor(0x5F, 0x6B, 0x7A)
+ACCENT = RGBColor(0xD9, 0x8B, 0x1E)
+
+lead = frame.paragraphs[0]
+lead.alignment = PP_ALIGN.LEFT
+for text, bold, size, colour in (
+    ("Orders fulfilled ", False, Pt(28), RGBColor(0x16, 0x1D, 0x28)),
+    ("rose 71%", True, Pt(28), ACCENT),
+    (" across FY2026.", False, Pt(28), RGBColor(0x16, 0x1D, 0x28)),
+):
+    run = lead.add_run()
+    run.text = text
+    run.font.bold = bold
+    run.font.size = size
+    run.font.color.rgb = colour
+
+footnote = frame.add_paragraph()
+footnote.space_before = Pt(10)
+note = footnote.add_run()
+note.text = "Q4 is forecast; the other three quarters are actuals."
+note.font.size = Pt(12)
+note.font.italic = True
+note.font.color.rgb = MUTED
+prs.save("runs.pptx")
+print("runs in paragraph 0:", len(lead.runs))
+PY
+```
+
+## Rules
+
+1. A number you want the reader to remember gets its own run, and usually 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.
+
+## 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
+  interpret; markup in a deck is a run, not a syntax.
+
+## CLI fast path
+
+`pptx create` writes plain paragraphs; bullets and titles are single-run. Mixed
+formatting inside one line is the recipe's job.

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

@@ -0,0 +1,65 @@
+# Speaker notes
+
+## Mechanics
+
+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.
+
+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.
+
+## Recipe
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Pt
+
+NOTES = {
+    1: "Open with the ask: approve two cells, not three.",
+    2: "41% comes from the Q3 time study; the two other numbers are from the driver logs.",
+    4: "Say the total out loud: 553 orders over four quarters.",
+    5: "Peak hour is 14:00-15:00; the bars are Q1-Q4, not hours.",
+}
+
+prs = Presentation("deck.pptx")
+for index, slide in enumerate(prs.slides, start=1):
+    if index not in NOTES:
+        continue
+    frame = slide.notes_slide.notes_text_frame
+    frame.text = NOTES[index]
+    for paragraph in frame.paragraphs:
+        paragraph.font.size = Pt(12)
+prs.save("deck-notes.pptx")
+print("notes written:", len(NOTES))
+PY
+```
+
+## What belongs in a note
+
+- The sentence you will actually say, not a copy of the slide.
+- The provenance of any number the audience may challenge ("Q3 time study,
+  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.
+
+## 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.
+- 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
+`ppt/slides` sibling `notesSlide` parts via
+`inspect_presentation_package_integrity.py` (it counts `notesSlides`).

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

@@ -0,0 +1,88 @@
+# Tables
+
+## Mechanics
+
+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.
+- **Row heights** are a minimum. Text taller than the row pushes it open, which
+  then 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.
+
+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.
+
+## Recipe
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+
+ROWS = [
+    ("Quarter", "Orders", "Touches"),
+    ("Q1", "100", "410"),
+    ("Q2", "128", "402"),
+    ("Q3", "154", "386"),
+    ("Q4", "171", "371"),
+    ("Total", "553", "1569"),
+]
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+shape = slide.shapes.add_table(
+    len(ROWS), len(ROWS[0]), Inches(0.9), Inches(1.7), Inches(9.6), Inches(0.46 * len(ROWS))
+)
+table = shape.table
+table.first_row = True
+for index, width in enumerate((3.4, 3.1, 3.1)):
+    table.columns[index].width = Inches(width)
+for row_index, row in enumerate(ROWS):
+    table.rows[row_index].height = Inches(0.46)
+    for column_index, value in enumerate(row):
+        cell = table.cell(row_index, column_index)
+        cell.text = value
+        cell.margin_left = cell.margin_right = Inches(0.12)
+        cell.margin_top = cell.margin_bottom = Inches(0.04)
+        for paragraph in cell.text_frame.paragraphs:
+            paragraph.font.size = Pt(16)
+            if row_index == 0:
+                paragraph.font.bold = True
+            if column_index > 0:
+                paragraph.alignment = 2  # right
+total = table.cell(len(ROWS) - 1, 0)
+for paragraph in total.text_frame.paragraphs:
+    paragraph.font.bold = True
+prs.save("table.pptx")
+print(f"rows={len(ROWS)} total_width={sum(c.width for c in table.columns) / 914400:.2f}in")
+PY
+```
+
+## Numbers people trust
+
+- Right-align numeric columns, left-align the label column, and 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.
+
+## 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.
+- 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.

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

@@ -0,0 +1,71 @@
+# Textbox at a coordinate
+
+## Mechanics
+
+A free textbox is placed by its rect, not by a layout slot. Four facts control
+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.
+- `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.
+- 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.
+
+## Recipe
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.text import MSO_ANCHOR
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])  # blank
+
+box = slide.shapes.add_textbox(Inches(0.9), Inches(1.35), Inches(6.2), Inches(1.1))
+frame = box.text_frame
+frame.word_wrap = True
+frame.vertical_anchor = MSO_ANCHOR.TOP
+frame.margin_left = frame.margin_right = 0
+frame.margin_top = frame.margin_bottom = 0
+
+paragraph = frame.paragraphs[0]
+paragraph.text = "Picking is 41% of floor labour hours"
+paragraph.font.size = Pt(28)
+paragraph.font.bold = True
+prs.save("textbox.pptx")
+print("saved")
+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.
+
+```python
+def fits(text: str, width_in: float, height_in: float, size_pt: float) -> bool:
+    per_line = max(1, int(width_in * 96 / (0.55 * size_pt)))
+    lines = -(-len(text) // per_line)
+    return lines * 1.2 * size_pt / 72 <= height_in
+```
+
+## 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.
+- `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
+  content slide; anchor per role, not globally.
+
+## CLI fast path
+
+`pptx create` places titles and bullet bodies on the layout's own frames. For
+anything at a coordinate, the snippet above is the route.