dsh-office-kit 0.2.0 → 0.3.1

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

@@ -0,0 +1,175 @@
+"""Replace text inside runs of an existing deck.
+
+Run-level by design: a match only counts when the whole `find` string lives in a
+single run. Text split across runs by earlier formatting is *not* merged, which
+keeps formatting intact and makes the outcome predictable — the tool reports
+what it matched, and reports what it could not match.
+
+Usage
+-----
+    <python> replace_text.py --input deck.pptx --find "Q4 2025" --replace "Q4 2026"
+    <python> replace_text.py --input deck.pptx --spec replacements.json --out fixed.pptx
+
+Exit codes
+----------
+0  every requested pattern was applied at least once
+1  a pattern matched nothing (the file is still written; check the report)
+2  bad arguments, unreadable input or invalid spec
+3  the output file could not be written
+
+The JSON report on stdout is `{ok, input, output, total, slides[], unmatched[]}`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def _emit(payload: dict, code: int = 0) -> int:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return code
+
+
+def _load_spec(path: str | None) -> list[dict]:
+    if not path:
+        return []
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        entries = data.get("replacements") or []
+    elif isinstance(data, list):
+        entries = data
+    else:
+        raise ValueError("spec must be an object with 'replacements' or a list")
+    resolved = []
+    for entry in entries:
+        if not isinstance(entry, dict) or "find" not in entry:
+            raise ValueError(f"replacement needs a 'find' key: {entry!r}")
+        resolved.append(
+            {
+                "find": str(entry["find"]),
+                "replace": str(entry.get("replace", "")),
+                "slide": entry.get("slide"),
+                "match_case": bool(entry.get("match_case", True)),
+            }
+        )
+    return resolved
+
+
+def _frames(slide):
+    for shape in slide.shapes:
+        if shape.has_text_frame:
+            yield shape.text_frame
+        if getattr(shape, "has_table", False) and shape.has_table:
+            for row in shape.table.rows:
+                for cell in row.cells:
+                    yield cell.text_frame
+
+
+def replace_in_slide(slide, rules: list[dict]) -> list[dict]:
+    hits = []
+    for frame in _frames(slide):
+        for paragraph in frame.paragraphs:
+            for run in paragraph.runs:
+                original = run.text
+                updated = original
+                for rule in rules:
+                    needle = rule["find"] if rule["match_case"] else rule["find"].lower()
+                    haystack = updated if rule["match_case"] else updated.lower()
+                    if needle and needle in haystack:
+                        updated = updated.replace(rule["find"], rule["replace"])
+                        hits.append({"find": rule["find"], "before": original, "after": updated})
+                if updated != original:
+                    run.text = updated
+    return hits
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Replace text inside runs of a .pptx (never across runs).",
+        epilog="Exit codes: 0 all patterns applied, 1 a pattern matched nothing, 2 bad input, 3 write failure.",
+    )
+    parser.add_argument("--input", required=True, help="source deck")
+    parser.add_argument("--find", action="append", default=[], help="text to find (repeatable)")
+    parser.add_argument("--replace", action="append", default=[], help="replacement (repeatable, pairs with --find)")
+    parser.add_argument("--spec", help="JSON file: {replacements:[{find, replace, slide?, match_case?}]}")
+    parser.add_argument("--out", help="output deck (default: <input>-edited.pptx)")
+    args = parser.parse_args()
+
+    rules: list[dict] = []
+    try:
+        for index, needle in enumerate(args.find):
+            rules.append(
+                {
+                    "find": needle,
+                    "replace": args.replace[index] if index < len(args.replace) else "",
+                    "slide": None,
+                    "match_case": True,
+                }
+            )
+        rules.extend(_load_spec(args.spec))
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return _emit({"ok": False, "error": f"bad spec: {error}"}, 2)
+
+    if not rules:
+        return _emit({"ok": False, "error": "nothing to replace: pass --find/--replace or --spec"}, 2)
+
+    source = Path(args.input)
+    if not source.is_file():
+        return _emit({"ok": False, "error": f"no such file: {source}"}, 2)
+    output = Path(args.out) if args.out else source.with_name(f"{source.stem}-edited{source.suffix}")
+
+    try:
+        from pptx import Presentation
+    except ImportError as error:
+        return _emit({"ok": False, "error": f"python-pptx is required: {error}"}, 2)
+
+    try:
+        prs = Presentation(str(source))
+    except Exception as error:  # noqa: BLE001 - report, never traceback at the user
+        return _emit({"ok": False, "error": f"cannot open {source}: {error}"}, 2)
+
+    slides_report = []
+    total = 0
+    matched_patterns: set[str] = set()
+    for index, slide in enumerate(prs.slides, start=1):
+        applicable = [rule for rule in rules if rule["slide"] in (None, index)]
+        hits = replace_in_slide(slide, applicable)
+        for hit in hits:
+            matched_patterns.add(hit["find"])
+        total += len(hits)
+        if hits:
+            slides_report.append({"slide": index, "replacements": len(hits), "details": hits[:10]})
+
+    unmatched = sorted({rule["find"] for rule in rules} - matched_patterns)
+
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        prs.save(str(output))
+    except Exception as error:  # noqa: BLE001
+        return _emit({"ok": False, "error": f"cannot write {output}: {error}"}, 3)
+
+    report = {
+        "schema": "replace_text/1",
+        "ok": not unmatched,
+        "input": str(source),
+        "output": str(output),
+        "rules": len(rules),
+        "total": total,
+        "slides": slides_report,
+        "unmatched": unmatched,
+        "note": "matches only inside a single run; text split by formatting is left alone",
+    }
+    return _emit(report, 0 if not unmatched else 1)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,236 @@
+"""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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+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.