dsh-office-kit 0.2.0 → 0.3.0

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.

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

@@ -0,0 +1,87 @@
+# Theme tokens
+
+## Mechanics
+
+The theme part (`ppt/theme/theme1.xml`) holds two palettes and two font lists:
+
+- `dk1/lt1/dk2/lt2/accent1..6/hlink/folHlink` — every `RGBColor` you *do not*
+  set falls back to one of these, and PowerPoint's "theme colors" picker edits
+  them for the whole deck.
+- `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.
+
+## Recipe: define the palette once, use it everywhere
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.util import Inches, Pt
+from pptx.enum.dml import MSO_THEME_COLOR
+
+PALETTE = {
+    "ink": RGBColor(0x16, 0x1D, 0x28),
+    "muted": RGBColor(0x5F, 0x6B, 0x7A),
+    "accent": RGBColor(0xD9, 0x8B, 0x1E),
+    "rule": RGBColor(0xD6, 0xDC, 0xE4),
+}
+TYPE = {"title": Pt(34), "body": Pt(18), "caption": Pt(12)}
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+def put(text, left, top, width, size, colour, bold=False):
+    box = slide.shapes.add_textbox(Inches(left), Inches(top), Inches(width), Inches(0.6))
+    frame = box.text_frame
+    frame.word_wrap = True
+    frame.margin_left = frame.margin_right = 0
+    run = frame.paragraphs[0].add_run()
+    run.text = text
+    run.font.size = size
+    run.font.bold = bold
+    run.font.color.rgb = PALETTE[colour]
+    return box
+
+put("Automation Review", 0.9, 2.4, 11.5, TYPE["title"], "ink", bold=True)
+put("Warehouse network · FY2026", 0.9, 3.3, 11.5, TYPE["body"], "muted")
+put("Source: FY2026 capital plan", 0.9, 6.7, 6.0, TYPE["caption"], "muted")
+prs.save("themed.pptx")
+print("palette keys:", sorted(PALETTE), "theme colour sample:", MSO_THEME_COLOR.ACCENT_1)
+PY
+```
+
+## Reading the theme you were given
+
+```python
+from pptx import Presentation
+prs = Presentation("template.pptx")
+theme = prs.slide_masters[0].part.part_related_by(
+    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+)
+blob = theme.blob.decode("utf-8", "ignore")
+print("accent1" in blob, "majorFont" in blob)
+```
+
+`template_following_scripts/inspect_template_deck.py` already reports the font
+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.
+- 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.
+
+## CLI fast path
+
+`pptx create` uses the default template's theme. For a branded deck, start from
+the supplied template (see [master-and-layouts](master-and-layouts.md)) rather
+than recolouring a blank deck.

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

@@ -0,0 +1,65 @@
+# Authoring workflow
+
+## What a deck is, mechanically
+
+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.
+
+Three consequences shape the whole workflow:
+
+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
+   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.
+
+## 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
+   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.
+
+## The numbers that keep a deck readable
+
+| 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 |
+
+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.
+
+## Deciding slide count
+
+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.
+
+A presentation of N minutes needs roughly 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).
+- Bullets that read as sentences: [native-bullets](native-bullets.md).
+- Charts, tables and notes as evidence: [native-evidence](native-evidence.md).
+- Supplied templates: [templates](templates.md).
+- Pre-delivery checklist: [finalization](finalization.md).