dsh-office-kit 0.1.0 → 0.3.0

package/assets/skills/office-presentations/references/finalization.md

@@ -0,0 +1,63 @@
+# Finalization checklist
+
+Run this before `present`. It exists because every item on it has shipped a
+broken deck at least once.
+
+## The file
+
+- [ ] Opens: `"<python>" "<cli>" pptx read --input deck.pptx` returns slides.
+- [ ] Package is coherent:
+      `"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck.pptx`
+      → `passed: true`, no dangling relationships, media and charts present.
+- [ ] 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).
+
+## The content
+
+- [ ] Every placeholder is 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.
+- [ ] Speaker notes carry the provenance of the non-obvious numbers.
+
+## The layout
+
+- [ ] Geometry gate passes:
+      `"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json`
+      → `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.
+- [ ] One idea per slide, one emphasis per paragraph.
+
+## The look
+
+- [ ] Rendered at viewing size and actually looked at:
+      `"<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview`
+      then `read_image` on each PNG (or on the contact sheet from
+      `"<skill>/template_following_scripts/make_contact_sheet.py`).
+- [ ] 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.
+
+## Delivery
+
+- [ ] The file lives in the user's workspace, not in a temp directory.
+- [ ] Output name is either new (`deck.pptx`) or `<original>-edited.pptx`.
+- [ ] `present` called; the reply states what changed in one sentence and, for
+      edits, both paths.
+
+## 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.

package/assets/skills/office-presentations/references/native-bullets.md

@@ -0,0 +1,78 @@
+# Bullets that read as sentences
+
+## The shape of a bullet
+
+A bullet is a claim, not a label. Two forms work:
+
+- **Claim + consequence**: "Picking is 41% of floor labour hours — travel is the
+  cost, not the pick."
+- **Number + meaning**: "12 minutes per order lost to aisle travel."
+
+Forms that do not work: a single noun ("Efficiency"), a truncated clause
+("Picking accounts for…"), a list of three adjectives, or a bullet that restates
+the slide title.
+
+## Length and count
+
+- One line, two at the absolute maximum, per bullet on a 16:9 slide.
+- Three to five bullets. Six is a signal to split; eight is a document.
+- No sub-sub-bullets. If a bullet needs a child, the parent was a section.
+- Keep bullets grammatically parallel: all sentences, or all noun phrases.
+
+## Native bullet glyphs
+
+Bullets in PowerPoint are paragraph properties, not characters. A bullet
+character typed into the text ("• Picking…") is a bullet that cannot re-indent,
+cannot change level, and looks different from every other bullet in the deck.
+
+Set them properly:
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+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(1.8), Inches(11.0), Inches(3.6))
+frame = box.text_frame
+frame.word_wrap = True
+
+for index, text in enumerate((
+    "Picking is 41% of floor labour hours",
+    "Aisle travel costs 12 minutes per order",
+    "Manual cycle counts stop the line twice a week",
+)):
+    paragraph = frame.paragraphs[0] if index == 0 else frame.add_paragraph()
+    paragraph.text = text
+    paragraph.font.size = Pt(20)
+    paragraph.space_after = Pt(12)
+    paragraph.level = 0
+    paragraph.alignment = PP_ALIGN.LEFT
+    # PowerPoint's own bullet: a literal glyph in the paragraph's pPr
+    paragraph._pPr.set("marL", str(Inches(0.3)))
+    paragraph._pPr.set("indent", str(-Inches(0.3)))
+    bu = paragraph._pPr.makeelement(
+        "{http://schemas.openxmlformats.org/drawingml/2006/main}buChar", {"char": "•"}
+    )
+    paragraph._pPr.append(bu)
+
+prs.save("bullets.pptx")
+print("bullets:", len(frame.paragraphs))
+PY
+```
+
+The `marL`/`indent` pair is what pulls the second line of a wrapped bullet under
+the text instead of under the glyph — the most common "malformed bullet" defect
+in generated decks.
+
+## Anti-patterns
+
+- Bullets as a script: a slide is not a transcript, the speaker notes are.
+- Fake bullets via "– " or "→ " prefixes in the text; they do not indent.
+- Six bullets of equal weight where one is the actual point. Make the point the
+  title and the bullets the evidence.
+- Numbered lists where the order does not matter, and bullet lists where it
+  does.

package/assets/skills/office-presentations/references/native-evidence.md

@@ -0,0 +1,67 @@
+# Evidence on slides: charts, tables, notes
+
+"Evidence" is anything on a slide that claims a fact: a number, a chart, a
+table, a quotation. The rules below keep it checkable.
+
+## Native or it did not happen
+
+| Claim | Correct form | Wrong form |
+|---|---|---|
+| Trend over time | Native chart with categories and series | Screenshot of a chart |
+| Exact figures | Native table | Image of a spreadsheet |
+| A single number | A bold run in a sentence | A one-bar chart |
+| A process | Shapes plus connectors | Image of a flowchart |
+
+The wrong column has one shared defect: the audience cannot read it at projector
+size and nobody can verify it. Native charts and tables also keep their numbers
+in the package, which is what lets `container_tools/native_quantitative_chart_gate.py`
+and `container_tools/native_table_arithmetic_gate.py` check them.
+
+## Charts
+
+- The chart title says what the chart means. The slide title says the conclusion.
+  Two titles, two jobs — if they are the same sentence, drop the chart title
+  (`chart.has_title = False`) rather than repeat it.
+- Bars start at zero. Lines may start elsewhere only if the axis is labelled.
+- Categories in the order the audience thinks in (Q1..Q4, not alphabetised).
+- Label the few numbers that matter, not every point. Ten data labels is a
+  table with rounded corners.
+- One axis. Two y-axes on a slide chart is a way to imply a correlation that may
+  not exist.
+- Source and window in the caption: "Driver logs, FY2026, 12 sites".
+
+## Tables
+
+- Column order follows the reader's question: what, then how much, then change.
+- Header row is bold and distinct; total row is bold and separated.
+- Numbers right-aligned, one decimal convention per column.
+- A total is arithmetic the reader can check. Fill it from the data, never by
+  eye, and let the table arithmetic gate confirm it.
+- Do not put units in every cell; put them in the header.
+- A table with more than about 7 rows belongs in an appendix, with the slide
+  stating the conclusion.
+
+## Speaker notes as provenance
+
+Notes are where "where did this number come from" lives, so the presenter can
+answer without the slide turning into a footnote.
+
+- One note per non-obvious number: source, date range, and any caveat.
+- The sentence you will actually say, in spoken words.
+- No bullet-stacking in notes; notes are prose.
+- Notes are invisible to the render loop — verify them from the file, not the
+  PNGs. `container_tools/inspect_presentation_package_integrity.py` counts
+  `notesSlides`, and the package dump shows their text.
+
+## Fidelity gates
+
+Before presenting a deck that carries numbers:
+
+```bash
+"<python>" container_tools/native_quantitative_chart_gate.py --input deck.pptx --all-slides
+"<python>" container_tools/native_table_arithmetic_gate.py --input deck.pptx --contracts totals.json
+"<python>" container_tools/native_chart_title_gate.py --input deck.pptx
+```
+
+Each prints one JSON object whose `passed` field is the decision. A failing gate
+is not advisory: it means the slide asserts something the file cannot support.

package/assets/skills/office-presentations/references/style-guidelines.md

@@ -0,0 +1,66 @@
+# Style guidance
+
+## The type scale
+
+Three sizes are enough: title, body, caption. A fourth size is a decision the
+audience has to make, and they will make it wrongly.
+
+| Role | Size | Weight | Colour |
+|---|---|---|---|
+| Cover title | 40–48 pt | Bold | Ink |
+| Slide title | 28–36 pt | Bold or semibold | Ink |
+| Body | 18–22 pt | Regular | Ink |
+| Lead-in number | Same as body + bold | Bold | Accent |
+| Caption, source | 12–14 pt | Regular | Muted |
+
+Rules that carry the rest:
+
+- One typeface family. A second family means "different voice", so use it for
+  one thing (a quote, a code line) and nothing else.
+- Bold is emphasis, not decoration: at most one bold phrase per paragraph.
+- All-caps for a 2–4 word label is a design choice; all-caps for a sentence is
+  a readability tax.
+- Left-align body text. Centred paragraphs longer than two lines are hard to
+  track back to the next line.
+
+## Colour
+
+- One ink, one muted, one accent, plus the template's own rule colour. More
+  than that and the accent stops meaning "look here".
+- Contrast is a correctness issue: body text on white needs a dark ink
+  (roughly luminance ratio 4.5:1), and text over a photograph needs a scrim,
+  not luck.
+- Never encode meaning in colour alone — an accent bar showing the direction of
+  a metric also needs an arrow or a word.
+- Chart series colours come from the theme; a sixth series colour is a signal
+  that the chart has too many series.
+
+## Density
+
+- Body blocks stop at about 6 lines of 18 pt on a 16:9 slide before the eye
+  stops at the middle.
+- A table on a slide reads at up to about 7 rows × 4 columns. Beyond that it is
+  an appendix, and the slide should carry the one row that matters.
+- Whitespace is a layout element, not leftover space: leave at least 0.6 in
+  between content blocks and the slide edge.
+- One idea per slide. If the title needs "and", split.
+
+## Cover art direction
+
+A cover carries three things: the title, the context line, and the visual that
+sets the tone. Keep them separate roles.
+
+- Abstract geometry, a photograph of the actual subject, or a flat colour field
+  all work. Clip art of a handshake does not.
+- If the visual is photographic, darken it (a scrim at 40–60% black) under the
+  text rather than hoping the text lands on a dark region.
+- If no suitable image exists, use a colour field plus an accent rule. An
+  invented diagram pretending to be a photograph is worse than a plain cover.
+- Encode the deck's palette: if the accent is amber, the cover visual should
+  contain amber, not a random sunset.
+- Never ship a screenshot of a tool, a UI or another slide as cover art.
+
+## Closing slides
+
+The last slide restates the ask in one line and nothing else. "Thank you" alone
+wastes the slot the audience is still looking at while they gather their things.

package/assets/skills/office-presentations/references/templates.md

@@ -0,0 +1,76 @@
+# Working from a supplied template
+
+## Why templates win
+
+A template already answers branding, type scale, slide families and chrome. The
+cheapest correct deck puts the user's content into the template's own slides
+and leaves the design alone. Rebuilding the look from a screenshot produces a
+near-miss that reads as "someone remade our deck in a hurry".
+
+## Order of operations
+
+1. **Inspect the template** before judging it:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/inspect_template_deck.py" --template brand.pptx --out-dir template-inspect
+   ```
+
+   It writes `template-inspect.ndjson` (per slide: layout, placeholders with
+   index, kind, rect and text, background art) and `template-manifest.json`
+   (slide size, aspect, layout names, theme fonts, which slides carry
+   full-bleed art).
+
+2. **Choose the slide families you need** — cover, section, content, table,
+   chart, closing. You want the *fewest* source slides that cover those roles.
+
+3. **Write the frame map** — a JSON plan that names, per output slide, which
+   source slide it duplicates and what happens to each element
+   (`rewrite`, `rewrite-and-reposition`, `fill-placeholder`, `replace`,
+   `delete`, `keep`).
+
+4. **Validate the plan** before building:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/validate_template_plan.py" --plan frame-map.json
+   ```
+
+   It rejects unknown actions, out-of-range zones, new primitives without an
+   explicit justification, and any attempt to edit a brand or chrome element.
+
+5. **Build the starter deck**, then fill it:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/prepare_template_starter_deck.py" --template brand.pptx --plan frame-map.json --out starter.pptx
+   ```
+
+   The starter deck contains only the slides you kept, in your order, with the
+   placeholders filled. From there `container_tools/add_slides.py` and the
+   recipes extend it.
+
+6. **Check fidelity** against the source:
+
+   ```bash
+   "<python>" "<skill>/template_following_scripts/check_template_fidelity.py" --template brand.pptx --final starter.pptx --plan frame-map.json
+   "<python>" "<skill>/container_tools/template_source_fidelity_gate.py" --template brand.pptx --final starter.pptx --requirements fidelity.json
+   ```
+
+   Both print JSON with a `passed` boolean. Leftover placeholders, drifted
+   layout rects and opaque panels covering inherited artwork are failures, not
+   style opinions.
+
+## Reading a template's own geometry
+
+`container_tools/inspect_presentation_layout_geometry.py --input brand.pptx`
+prints every shape's rect in inches, which is what you address when a slide's
+placeholder needs a value that fits its frame.
+
+## Rules
+
+- Placeholders keep their index; fill by index rather than adding a textbox on
+  top of a placeholder.
+- Never restyle the master to match a screenshot you were given. If the brand
+  colours are wrong, ask; guessing produces a deck the brand team rejects.
+- If the template has no suitable family for a slide (say, a two-column
+  comparison), say which family you added and why, rather than silently
+  inventing a look.
+- Keep the template's slide size. Changing it invalidates every inherited rect.

package/assets/skills/office-presentations/routing/google_slides.md

@@ -0,0 +1,45 @@
+# Handing a deck to Google Slides
+
+Google Slides imports `.pptx`, and mostly survives it. What it does not survive
+is worth designing around.
+
+## What converts cleanly
+
+- Text frames, bullet levels, speaker notes, slide size and order.
+- Native tables and native charts (data comes across with the chart).
+- Pictures, shapes, solid fills and theme colours.
+
+## What converts badly
+
+| Feature | What happens | Do instead |
+|---|---|---|
+| Custom `buChar` glyphs and `marL/indent` | Indent shifts, glyphs fall back | Use plain paragraph levels; check the bullet indent after import |
+| Elbow/curved connectors | Re-anchored or detached | Straight connectors between facing sides |
+| Font not on the reader's machine | Substituted, wider, text reflows | Stick to fonts both environments have, and re-check overflow after import |
+| Text-to-fit-shape autosize | Keeps the shrunk size | Fixed frames with measured text |
+| Animations and transitions | Partially dropped | Do not rely on them for meaning |
+| Embedded workbook charts | Data retained, formatting re-derived | Re-apply axis/label settings in Slides if they matter |
+| Master-level chrome via spTree surgery | Usually kept, occasionally duplicated | Prefer layout-level placeholders |
+
+## The workflow
+
+1. Build the deck as a normal `.pptx` — nothing Slides-specific is needed.
+2. Render and inspect the PNGs locally first; fix overflow before importing.
+3. Upload to Drive, open with Google Slides, and check these in order: title
+   wrapping, bullet indentation, connector attachment, chart axes, notes.
+4. If the deck will be edited by other people in Slides, keep shapes distinct
+   and named (right-click → rename) so comments and edits are unambiguous.
+
+## Sharing
+
+- "Anyone with the link" plus a view-only role is the default for a deck that
+  should not be edited in place.
+- Export back to `.pptx` when the user needs a file; Slides' export does not
+  preserve everything either, so state which version is authoritative.
+- Comments and suggestions do not travel in the `.pptx` round trip.
+
+## When the user asks for a Slides-native link
+
+Deliver the `.pptx` (that is what this pack produces), state the upload path,
+and list the three things to check after import: font substitution, bullet
+indent, chart axes. Claiming a clean conversion without those checks is a guess.

package/assets/skills/office-presentations/tasks/apply-annotations.md

@@ -0,0 +1,83 @@
+# Task: apply an annotation payload
+
+The user draws on a rendered slide and sends back an `office-annotations` block.
+Treat it as a change request with coordinates, not as editor state.
+
+## 1. Re-create the geometry the user drew on
+
+Annotations refer to the preview the user saw. Render the same way so the
+coordinates mean the same thing:
+
+```bash
+"<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview
+```
+
+Slide index = `page` in the payload, 1-based. Keep the PNGs — you will compare
+the same slide before and after.
+
+## 2. Resolve each annotation to shapes
+
+The region is normalised 0–1 on that slide image. Map it to inches:
+
+```
+left_in   = region.left   * slide_width_in
+top_in    = region.top    * slide_height_in
+width_in  = region.width  * slide_width_in
+height_in = region.height * slide_height_in
+```
+
+Then select candidate shapes whose bounding box overlaps that rect, largest
+overlap first:
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json
+```
+
+`geometry.json` lists every shape per slide with `left`, `top`, `width`,
+`height` in inches, plus its text. Two overlapping shapes (a title over a
+background panel) are common: use the annotation's `text` to disambiguate —
+match it against each candidate's text, and prefer an exact or prefix match.
+
+## 3. Decide the smallest edit
+
+| Requirement reads like | Do this |
+|---|---|
+| "change this wording" | run-level replace on that shape ([edit-deck](edit-deck.md)) |
+| "move this down" | set `left/top` on that shape only |
+| "make this bigger" | set font size on the runs of that shape, then re-check fit |
+| "this overlaps the table" | resize the shape, or the table, not the whole slide |
+| "recolour" | change the run colour, not the theme |
+| "add a line here" | the rect is a position, not an insertion point: add the shape at that rect, matching nearby type |
+
+Never restyle a slide to satisfy a region. The region identifies *what*, the
+requirement says *how much*.
+
+## 4. Apply, write a copy, re-render
+
+Mutations go through this pack's tools (`replace_text.py`, `add_slides.py`,
+`core_properties.py`) or a focused `python-pptx` snippet — always to
+`<original>-edited.pptx`.
+
+```bash
+"<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx --find "old" --replace "new" --out deck-edited.pptx
+"<python>" "<skill>/container_tools/render_slides.py" --input deck-edited.pptx --out-dir preview-after
+```
+
+## 5. Confirm, in words
+
+Open the same slide number and check the region now looks right. Report which
+shape you changed, what changed, and the slide number.
+
+## When it cannot be mapped
+
+- Empty region, or no shape overlaps it → say that the region covers blank
+  space and ask what object was meant.
+- Overlapping candidates that `text` does not disambiguate → name both and ask.
+- The requirement is about something the file has no geometry for (a font that
+  is not installed, a transition) → say so plainly.
+- The region covers a chart or table whose values would need to change → state
+  that values come from the data, and ask for the corrected figures rather than
+  editing the rendered numbers.
+
+Never guess silently. "I changed the title on slide 3; the region also touched
+the subtitle, which I left alone" is a good answer. Silence plus a diff is not.

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

@@ -0,0 +1,79 @@
+# Task: charts, tables and speaker notes
+
+Three things that look like one job and share one rule: the numbers must be
+checkable from the file.
+
+## Charts
+
+Native, always:
+
+```bash
+"<python>" "<cli>" pptx create --spec with-chart.json --out charted.pptx
+```
+
+or the recipe when you need control of axis, labels or legend:
+[native-charts](../recipes/native-charts.md).
+
+Spec keys the builder accepts: `type` (`bar`/`column`/`line`/`pie`, where bar and
+column both render as a clustered column), `title`, `categories`,
+`series[{name, values}]`, `left`, `top`, `width`, `height`.
+
+- The chart title says what the chart means; the slide title states the
+  conclusion. If both say the same thing, drop the chart title.
+- Categories in the order the reader thinks in.
+- Bars start at zero.
+- A chart that duplicates a table on a neighbouring slide is a review finding,
+  not a second view — pick one.
+
+Verify:
+
+```bash
+"<python>" "<skill>/container_tools/native_chart_title_gate.py" --input charted.pptx
+"<python>" "<skill>/container_tools/native_quantitative_chart_gate.py" --input charted.pptx --all-slides
+```
+
+## Tables
+
+Spec form (`{"headers": [...], "rows": [[...]]}`) puts the table at the cursor,
+full width; the [tables recipe](../recipes/tables.md) gives you the rect, column
+widths, alignment and the total row styling.
+
+Rules: numbers right-aligned, units in the header, total row computed not typed,
+seven rows maximum on a slide.
+
+Declare each total so it can be proved:
+
+```bash
+"<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input charted.pptx --contracts totals.json
+```
+
+A mismatch exit code is a data bug or a rounding bug. Fix the number or declare
+the rounding; never lower the tolerance to make it pass.
+
+## Speaker notes
+
+Notes live beside the slide, not on it:
+
+```bash
+"<python>" "<cli>" pptx read --input deck.pptx   # does not print notes
+```
+
+Write them with the [speaker notes recipe](../recipes/speaker-notes.md), then
+confirm they landed:
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck-notes.pptx
+```
+
+`notesSlides` in the part counts should equal the number of slides you wrote
+notes for.
+
+Notes carry: the sentence you will say, the provenance of any non-obvious
+number, and the answer to the question the slide invites. Nothing that belongs
+on the slide.
+
+## Putting them together
+
+A results slide usually wants: one claim as the title, one chart as the
+evidence, one caption as the source, and the detail in notes. If it needs a
+chart *and* a table, it is two slides — or the table is an appendix.

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

@@ -0,0 +1,106 @@
+# Task: create a deck
+
+## Inputs to settle first
+
+- Audience and setting: live talk, read-on-its-own PDF, or both. A read-only
+  deck needs more words; a live deck needs fewer.
+- Length: number of slides or minutes.
+- Brand: a template file, a colour, or nothing (then use the defaults in
+  [style-guidelines](../references/style-guidelines.md)).
+- Evidence: numbers, charts, tables and images the user already has. Never
+  invent a metric — if a number is needed and missing, say so.
+
+## Route
+
+### Fast path: the spec-driven builder
+
+For the ordinary deck (cover, bullets, section, table, chart, image, closing):
+
+```bash
+"<python>" "<cli>" pptx create --spec deck-spec.json --out deck.pptx
+```
+
+`deck-spec.json`:
+
+```json
+{
+  "title": "Automation Review",
+  "author": "Warehouse Ops",
+  "slides": [
+    { "layout": "title", "title": "Automation Review", "subtitle": "Warehouse network · FY2026" },
+    {
+      "layout": "bullets",
+      "title": "Where the time goes",
+      "bullets": [{ "text": "Picking is 41% of floor labour hours" }, { "text": "Aisle travel costs 12 minutes per order" }]
+    },
+    { "layout": "section", "title": "What the pilot measured" },
+    {
+      "layout": "blank",
+      "title": "Throughput rose while touches fell",
+      "table": {
+        "headers": ["Quarter", "Orders", "Touches"],
+        "rows": [["Q1", 100, 410], ["Q2", 128, 402], ["Total", 228, 812]]
+      }
+    },
+    {
+      "layout": "blank",
+      "title": "Orders per quarter",
+      "chart": {
+        "type": "column",
+        "title": "Orders fulfilled per quarter",
+        "categories": ["Q1", "Q2"],
+        "series": [{ "name": "Orders", "values": [100, 128] }],
+        "left": 0.9,
+        "top": 1.45,
+        "width": 11.5,
+        "height": 5.1
+      }
+    },
+    {
+      "layout": "bullets",
+      "title": "Decision for Thursday",
+      "bullets": [{ "text": "Approve two cells in Q1" }]
+    }
+  ]
+}
+```
+
+Layouts map to `title`, `bullets`, `section`, `title_only`, `blank`. Tables are
+placed at 0.8 in from the left at the running cursor and cannot be positioned —
+put a table on its own slide, or use the [tables recipe](../recipes/tables.md).
+
+### Everything else: build it with the recipes
+
+Anything at a coordinate, any crop, any connector, any master change is a
+`python-pptx` snippet:
+
+- [textbox at a coordinate](../recipes/textbox-at-coordinate.md)
+- [auto-layout rules](../recipes/autolayout.md)
+- [tables](../recipes/tables.md) · [native charts](../recipes/native-charts.md)
+- [images](../recipes/images.md) · [connectors](../recipes/connectors.md)
+- [rich text runs](../recipes/rich-text-runs.md) · [theme tokens](../recipes/theme-tokens.md)
+- [speaker notes](../recipes/speaker-notes.md) · [masters and layouts](../recipes/master-and-layouts.md)
+
+Extending a deck you already built:
+
+```bash
+"<python>" "<skill>/container_tools/add_slides.py" --input deck.pptx --spec extra-slides.json --out deck-2.pptx
+```
+
+### From a template
+
+See [template-following](template-following.md). Do not rebuild a supplied
+template's look by hand.
+
+## Then
+
+1. Set properties: `"<python>" "<skill>/container_tools/core_properties.py" --input deck.pptx --title "..." --author "..."`.
+2. Verify: [inspect-and-verify](inspect-and-verify.md).
+3. Deliver with `present`.
+
+## Writing the slides
+
+Story first. Write the one-sentence claim for every slide, in order, then fill
+the frames. If a claim needs two sentences, it is two slides. Keep bullets as
+claims ([native-bullets](../references/native-bullets.md)) and evidence native
+([native-evidence](../references/native-evidence.md)).