dsh-office-kit 0.1.0 → 0.3.0

package/assets/skills/office-presentations/container_tools/template_source_fidelity_gate.py

@@ -0,0 +1,229 @@
+"""Compare a finished deck against the template it claims to follow.
+
+Purpose: "it looks similar" is not fidelity. This gate takes explicit
+requirements — which source slides must be represented, how close the slide
+size and placeholder geometry must be, whether a photographic background must
+survive — and answers yes or no. No requirements supplied means nothing to
+enforce, so the gate passes neutrally instead of inventing a standard.
+
+Requirements file:
+  {
+    "reference_slide_indices": [1, 3, 4],
+    "mapping": {"1": 1, "2": 3, "3": 4},
+    "minimum_coverage_ratio": 1.0,
+    "require_exact_dimensions": true,
+    "require_placeholder_geometry": true,
+    "require_photographic_background": false,
+    "geometry_tolerance_emu": 9144
+  }
+
+Exit codes: 0 pass, 1 fail, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from ooxml_helpers import box, is_picture, slide_size_in  # noqa: E402
+
+EMU_PER_INCH = 914400
+DEFAULT_TOLERANCE_EMU = 9144  # 0.01 in
+
+
+def _placeholder_map(slide) -> dict[tuple[int, str], tuple[float, float, float, float]]:
+    entries: dict[tuple[int, str], tuple[float, float, float, float]] = {}
+    for shape in slide.shapes:
+        if not shape.is_placeholder:
+            continue
+        geometry = box(shape)
+        if geometry is None:
+            continue
+        entries[(shape.placeholder_format.idx, shape.name)] = geometry
+    return entries
+
+
+def _background_picture(slide, slide_w: float, slide_h: float) -> bool:
+    for shape in slide.shapes:
+        if not is_picture(shape):
+            continue
+        geometry = box(shape)
+        if geometry is None:
+            continue
+        left, top, width, height = geometry
+        if left <= 0.02 and top <= 0.02 and width >= slide_w * 0.98 and height >= slide_h * 0.98:
+            return True
+    return False
+
+
+def check_fidelity(template_path: str | Path, final_path: str | Path, requirements: dict | None) -> dict:
+    from pptx import Presentation
+
+    requirements = requirements or {}
+    template_file = Path(template_path)
+    final_file = Path(final_path)
+    for candidate in (template_file, final_file):
+        if not candidate.is_file():
+            return {"gate": "template-source-fidelity", "passed": False, "findings": [{"kind": "missing_file", "detail": str(candidate)}]}
+
+    if not requirements:
+        return {
+            "gate": "template-source-fidelity",
+            "passed": True,
+            "neutral": True,
+            "note": "no fidelity requirements were supplied, so nothing was enforced",
+            "findings": [],
+        }
+
+    template = Presentation(str(template_file))
+    final = Presentation(str(final_file))
+    template_w, template_h = slide_size_in(template)
+    final_w, final_h = slide_size_in(final)
+    tolerance_in = float(requirements.get("geometry_tolerance_emu", DEFAULT_TOLERANCE_EMU)) / EMU_PER_INCH
+    findings: list[dict] = []
+    checks: list[dict] = []
+
+    if requirements.get("require_exact_dimensions", True):
+        same = abs(template_w - final_w) <= tolerance_in and abs(template_h - final_h) <= tolerance_in
+        checks.append({"check": "dimensions", "passed": same, "template": [template_w, template_h], "final": [final_w, final_h]})
+        if not same:
+            findings.append(
+                {
+                    "kind": "dimension_mismatch",
+                    "severity": "fail",
+                    "message": f"final deck is {final_w:.2f}x{final_h:.2f} in, template is {template_w:.2f}x{template_h:.2f} in",
+                }
+            )
+
+    template_slides = list(template.slides)
+    final_slides = list(final.slides)
+    mapping = requirements.get("mapping") or {}
+    pairs: list[tuple[int, int]] = []
+    for output_index, source_index in mapping.items():
+        pairs.append((int(output_index), int(source_index)))
+    if not pairs:
+        pairs = [(index, index) for index in range(1, min(len(template_slides), len(final_slides)) + 1)]
+
+    matched = 0
+    for output_index, source_index in pairs:
+        if not (1 <= output_index <= len(final_slides) and 1 <= source_index <= len(template_slides)):
+            findings.append(
+                {
+                    "kind": "mapping_out_of_range",
+                    "severity": "fail",
+                    "message": f"mapping {output_index}->{source_index} is outside the deck",
+                }
+            )
+            continue
+        source_slide = template_slides[source_index - 1]
+        output_slide = final_slides[output_index - 1]
+        slide_pass = True
+
+        if source_slide.slide_layout.name != output_slide.slide_layout.name:
+            slide_pass = False
+            findings.append(
+                {
+                    "kind": "layout_changed",
+                    "severity": "fail",
+                    "slide": output_index,
+                    "sourceSlide": source_index,
+                    "message": f"layout went from '{source_slide.slide_layout.name}' to '{output_slide.slide_layout.name}'",
+                }
+            )
+
+        if requirements.get("require_placeholder_geometry", True):
+            source_placeholders = _placeholder_map(source_slide)
+            output_placeholders = _placeholder_map(output_slide)
+            for key, source_box in source_placeholders.items():
+                output_box = output_placeholders.get(key)
+                if output_box is None:
+                    continue
+                drift = max(abs(a - b) for a, b in zip(source_box, output_box))
+                if drift > tolerance_in:
+                    slide_pass = False
+                    findings.append(
+                        {
+                            "kind": "placeholder_geometry_drift",
+                            "severity": "fail",
+                            "slide": output_index,
+                            "placeholder": key[1],
+                            "driftIn": round(drift, 3),
+                            "message": f"placeholder '{key[1]}' moved {drift:.2f} in from the template position",
+                        }
+                    )
+
+        if requirements.get("require_photographic_background"):
+            if _background_picture(source_slide, template_w, template_h) and not _background_picture(output_slide, final_w, final_h):
+                slide_pass = False
+                findings.append(
+                    {
+                        "kind": "background_lost",
+                        "severity": "fail",
+                        "slide": output_index,
+                        "sourceSlide": source_index,
+                        "message": "the template slide carries a full-bleed background image; the output does not",
+                    }
+                )
+
+        checks.append({"check": "slide", "outputSlide": output_index, "sourceSlide": source_index, "passed": slide_pass})
+        matched += 1 if slide_pass else 0
+
+    coverage = matched / len(pairs) if pairs else 0.0
+    minimum = float(requirements.get("minimum_coverage_ratio", 1.0))
+    checks.append({"check": "coverage", "ratio": round(coverage, 4), "minimum": minimum, "passed": coverage + 1e-9 >= minimum})
+    if coverage + 1e-9 < minimum:
+        findings.append(
+            {
+                "kind": "coverage_below_minimum",
+                "severity": "fail",
+                "message": f"{coverage:.0%} of mapped slides preserved the template, minimum is {minimum:.0%}",
+            }
+        )
+
+    reference = requirements.get("reference_slide_indices") or []
+    if reference and not pairs:
+        findings.append({"kind": "no_usable_mapping", "severity": "fail", "message": f"reference slides {reference} could not be mapped to output slides"})
+
+    return {
+        "gate": "template-source-fidelity",
+        "template": str(template_file.resolve()),
+        "final": str(final_file.resolve()),
+        "requirements": requirements,
+        "checks": checks,
+        "findings": findings,
+        "coverage": round(coverage, 4),
+        "passed": not [item for item in findings if item["severity"] == "fail"],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Verify that a deck preserved the template it was built from.")
+    parser.add_argument("--template", required=True, help="the source template .pptx")
+    parser.add_argument("--final", required=True, help="the finished .pptx")
+    parser.add_argument("--requirements", help="JSON file with the fidelity requirements; omit for a neutral pass")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+
+    requirements = None
+    if args.requirements:
+        try:
+            requirements = json.loads(Path(args.requirements).read_text(encoding="utf-8"))
+        except Exception as exc:  # noqa: BLE001
+            json.dump({"gate": "template-source-fidelity", "passed": False, "error": {"code": "bad_requirements", "message": str(exc)}}, sys.stdout)
+            sys.stdout.write("\n")
+            return 2
+    report = check_fidelity(args.template, args.final, requirements)
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,66 @@
+# Finance decks
+
+The mechanics are the same as any deck; the failure modes are specific.
+
+## What a finance audience checks first
+
+1. Does the total add up? A slide whose numbers do not sum loses the argument
+   before the argument starts. Run the arithmetic gate on every declared total.
+2. Is the period stated? "Revenue up 12%" without a base period is not a claim.
+3. Is the unit stated? Thousands, millions, currency, and whether it is gross or
+   net. Put it in the header, once.
+4. Is the comparison like-for-like? Full quarter against full quarter; do not
+   put a 13-week quarter beside a 12-week one without saying so.
+5. Does the chart axis start at zero? For bars, yes, always — a truncated bar
+   chart in a finance deck reads as manipulation even when it is not.
+
+## The financial slide kit
+
+| Slide | Content | Note |
+|---|---|---|
+| Headline | One number, one claim, one source | The number the meeting is about |
+| Bridge | Waterfall from last period to this one | Native chart; label the middle bars, not the ends |
+| Results table | Period rows, metric columns, total row | Totals computed, not typed |
+| Variance | Actual vs plan vs prior, and why | The "why" is a sentence, not a column |
+| Outlook | Ranges, not points | A single forecast point implies precision you do not have |
+| Ask | The decision, the amount, the date | Last slide, one line |
+
+## Numbers on slides
+
+- Two significant figures is usually enough for a headline (`£2.4m`, not
+  `£2,384,117`). Keep full precision in the appendix table.
+- Percentages: one decimal at most, and say what they are a percentage *of*.
+- Round consistently: if the headline says 2.4m, the table should not say
+  2.38m in one row and 2.4m in the next.
+- Negative numbers: use a minus sign consistently (`−12%`) and keep
+  parentheses for tables where accounting convention is expected.
+- A variance is meaningless without its sign and its direction; state whether
+  favourable is up or down (revenue vs cost).
+
+## Charts that survive a CFO
+
+- Waterfall for a bridge, column for periods, line for a trend, never pie for
+  more than three slices.
+- Label the axis unit once, in the caption: "£m, FY2026 actuals".
+- One series per chart unless the comparison *is* the point.
+- Do not chart a table of six numbers; the table is more honest and faster to
+  read.
+- Forecast periods are visually distinct (lighter fill, dashed line) and named
+  in the caption.
+
+## Provenance
+
+Every non-obvious number gets a note with: source file or system, extraction
+date, period covered, and any adjustment made. The speaker notes are the right
+place; a footnote-heavy slide is a slide nobody reads.
+
+## Check before delivery
+
+```bash
+"<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input deck.pptx --contracts totals.json
+"<python>" "<skill>/container_tools/native_quantitative_chart_gate.py" --input deck.pptx --all-slides
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx
+```
+
+Then read the slides as a sceptic: which number would you challenge first, and
+does the deck already answer it?

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

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

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

@@ -0,0 +1,88 @@
+# Auto-layout rules
+
+## Mechanics
+
+PowerPoint has two different "autofit" ideas and mixing them up wastes a round
+trip:
+
+- `word_wrap` decides whether text wraps inside the width. Turn it on for every
+  authored box.
+- `auto_size` decides whether the *frame* follows the text (`MSO_AUTO_SIZE.
+  SHAPE_TO_FIT_TEXT`) or the text shrinks to fit the frame
+  (`TEXT_TO_FIT_SHAPE`). `TEXT_TO_FIT_SHAPE` is a **render-time** behaviour:
+  PowerPoint recalculates it when the file is opened, so a deck that looks fine
+  in a draft preview can still shrink to 8 pt on a real screen.
+
+The reliable pattern is: fixed frame, explicit sizes, content measured against
+the frame, no text-to-fit. Estimate, then verify by rendering.
+
+## Recipe: fit a variable number of bullets
+
+```python
+"<python>" - <<'PY'
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.text import MSO_ANCHOR
+
+BULLETS = [
+    "Picking is 41% of floor labour hours",
+    "Travel between aisles adds 12 minutes per order",
+    "Manual cycle counts stop the line twice a week",
+    "Two cells idle below 60% utilisation",
+    "Overtime covers the Friday peak",
+]
+
+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 = max(1, -(-len(text) // per_line))
+    return lines * 1.2 * size_pt / 72 <= height_in
+
+prs = Presentation()
+prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+width, height = 8.4, 4.6                  # the body rect you reserved
+box = slide.shapes.add_textbox(Inches(0.9), Inches(1.6), Inches(width), Inches(height))
+frame = box.text_frame
+frame.word_wrap = True
+frame.vertical_anchor = MSO_ANCHOR.TOP
+
+size = next(pt for pt in (24, 22, 20, 18) if fits(" ".join(BULLETS), width, height, pt))
+needed = sum(
+    max(1, -(-len(item) // max(1, int(width * 96 / (0.55 * size))))) * 1.2 * size / 72
+    for item in BULLETS
+)
+for index, item in enumerate(BULLETS):
+    paragraph = frame.paragraphs[0] if index == 0 else frame.add_paragraph()
+    paragraph.text = item
+    paragraph.font.size = Pt(size)
+    paragraph.space_after = Pt(10)
+
+prs.save("autofit.pptx")
+print(f"size={size}pt lines_estimate_in={needed:.2f} frame_in={height}")
+PY
+```
+
+## Rules that hold regardless of content
+
+1. Body text is 18 pt or larger; below that the back row cannot read it.
+2. Six bullets or three lines of body is the point where a slide should split.
+3. Longer text shrinks the number of *words*, not the type size. If the fit loop
+   lands below the body floor, cut copy or split the slide.
+4. Keep 0.5 in of bottom margin for the footer and for projectors that crop.
+5. Two columns beat one narrow column: a 4.2 in column of 18 pt text is a wall.
+
+## Pitfalls this avoids
+
+- `frame.text` then `paragraph.font.size` on paragraph 0 only: a multi-paragraph
+  assignment leaves paragraphs 1..n at the inherited 18 pt.
+- Text-to-fit hiding the overflow: the file opens fine and the audience reads
+  9 pt. Measure, do not delegate the fit to the renderer.
+- A frame height that exactly equals the text height: one extra word on edit and
+  the block runs into the evidence below. Reserve 10% slack.
+
+## CLI fast path
+
+`pptx create` with `layout: "bullets"` fills the layout's body placeholder at
+its own size. Use the loop above when the number of bullets is not known before
+the content is written.

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.