dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,93 @@
+# Task: edit an existing deck
+
+Editing is mutation, and mutation lives in this pack's tools, not in the helper
+CLI: `container_tools/replace_text.py`, `add_slides.py`, `core_properties.py`,
+plus the recipes for everything structural.
+
+**Never write over the original.** Every tool defaults to
+`<original>-edited.pptx`; keep that default unless the user names a path.
+
+## 1. Understand the file first
+
+```bash
+"<python>" "<cli>" pptx read --input deck.pptx
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx
+```
+
+`pptx read` gives titles, text, tables and chart data per slide. The geometry
+gate gives every shape's rect in inches, which is what you need to decide
+whether a new block fits.
+
+## 2. Text changes: run-level replace
+
+```bash
+"<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx \
+  --find "Q4 2025" --replace "Q4 2026" --out deck-edited.pptx
+```
+
+Batch form:
+
+```json
+{
+  "replacements": [
+    { "find": "Q4 2025", "replace": "Q4 2026" },
+    { "find": "€", "replace": "EUR ", "match_case": true },
+    { "find": "draft", "replace": "final", "slide": 7 }
+  ]
+}
+```
+
+```bash
+"<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx --spec replacements.json
+```
+
+Semantics that matter: a pattern only matches **inside a single run**. Text that
+PowerPoint split for formatting ("**Q4** 2025") will not match "Q4 2025" and the
+report lists it under `unmatched`. When a pattern cannot match, that is the
+signal to edit that paragraph with a run-level snippet
+([rich text runs](../recipes/rich-text-runs.md)) rather than widening the match.
+
+Exit code 1 means a pattern matched nothing; the file is still written, so read
+`unmatched` before delivering.
+
+## 3. Adding slides
+
+```bash
+"<python>" "<skill>/container_tools/add_slides.py" --input deck.pptx --spec extra-slides.json
+```
+
+The spec is the same slide object as `pptx create` (`layout`, `title`,
+`subtitle`, `bullets`, `table`, `chart`, `image`). For anything outside that
+vocabulary, add the slide with `add_slides.py` and then place content with a
+recipe.
+
+## 4. Metadata
+
+```bash
+"<python>" "<skill>/container_tools/core_properties.py" --input deck.pptx \
+  --title "Automation Review" --author "Warehouse Ops" --subject "FY2026 capital plan"
+```
+
+## 5. Structural changes
+
+| Change | Route |
+|---|---|
+| Move or resize a shape | recipe: set `.left/.top/.width/.height` on the shape from `slide.shapes` |
+| Restyle a family | [masters and layouts](../recipes/master-and-layouts.md) |
+| Add notes | [speaker notes](../recipes/speaker-notes.md) |
+| Replace a chart's data | [native charts](../recipes/native-charts.md) — edit the series, do not paste a picture |
+| Fix a table's total | [tables](../recipes/tables.md), then the arithmetic gate |
+| Delete a slide | `prs.slides._sldIdLst.remove(...)` after `prs.part.drop_rel(rId)` |
+
+## 6. Verify before delivering
+
+Deleting or inserting a slide commonly breaks nothing visible and everything
+relational:
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck-edited.pptx
+"<python>" "<skill>/container_tools/render_slides.py" --input deck-edited.pptx --out-dir preview
+```
+
+Then look at the changed pages. A text replacement that pushes a title onto a
+third line is a layout change, not a text change.

package/assets/skills/office-presentations/tasks/inspect-and-verify.md

@@ -0,0 +1,107 @@
+# Task: inspect and verify a deck
+
+Verification is reading the artefact back and looking at it. The tools below
+print one JSON object each; `passed` is the decision.
+
+## 1. What is in the file
+
+```bash
+"<python>" "<cli>" pptx read --input deck.pptx
+```
+
+Per slide: title, all text, tables as rows, charts with type/title/categories/
+series, image count. This is the cheapest sanity check that the content you
+meant to write is the content that was written.
+
+## 2. Is the package coherent
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck.pptx
+```
+
+Checks required parts, slide/master presence, dangling relationships, XML that
+does not parse, slide count drift and duplicate parts, then reports part counts
+(`slides`, `layouts`, `masters`, `charts`, `notesSlides`, `media`,
+`embeddings`). A chart with an `embeddings` count of zero has lost its data.
+
+## 3. Does the layout hold
+
+```bash
+"<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json
+```
+
+`fail` findings (block a delivery): shape outside the slide, degenerate size,
+text that cannot fit its frame, table outside the slide, chart or table covered
+by another shape. `review` findings (read them, then decide): text overlap,
+empty placeholder, title under 28 pt, body under 14 pt, heading ending in a full
+stop, connector across text, a chart duplicating a table's labels.
+
+Add `--strict` to make review findings blocking for a formal deck.
+
+## 4. Are the numbers real
+
+```bash
+"<python>" "<skill>/container_tools/native_chart_title_gate.py" --input deck.pptx
+"<python>" "<skill>/container_tools/native_quantitative_chart_gate.py" --input deck.pptx --all-slides
+"<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input deck.pptx --contracts totals.json
+```
+
+- Chart titles: fails on leftover "Chart Title" or an empty title, unless the
+  chart is explicitly suppressed.
+- Quantitative charts: every declared chart must be a real chart part with a
+  readable series, and in the default `portable` mode must carry its embedded
+  workbook.
+- Table arithmetic: only declared totals are enforced, compared against the
+  displayed rounding; columns whose header is not additive (unit price, ratio,
+  percent) are skipped rather than summed wrongly.
+
+`totals.json` names the contract explicitly:
+
+```json
+{ "contracts": [{ "slide": 4, "table": 1, "total_row": 6, "columns": [1, 2] }] }
+```
+
+## 5. Rendering and looking
+
+```bash
+"<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview
+```
+
+Writes `slide-NN.png` plus `render.json`. Then `read_image` every PNG — an
+unlooked-at render is not verification.
+
+To see the whole deck at once:
+
+```bash
+"<python>" "<skill>/template_following_scripts/make_contact_sheet.py" --dir preview --out sheet.png --columns 3
+```
+
+or `"<skill>/container_tools/create_montage.py` with an explicit file list.
+
+Look for: clipped text, overlapping blocks, a title that reflowed, a chart whose
+point is invisible at thumbnail size, a photograph stretched, a slide with no
+title.
+
+## 6. When nothing can render
+
+With no Microsoft Office, WPS Office, or LibreOffice installed
+(`office_status` → `renderers.kingsoft_wps` / `microsoft_office` / `libreoffice`),
+`render_slides.py` falls back to `--engine draft`, a PyMuPDF geometry preview. It
+shows placement, overflow and overlap — not typography or theme chrome. Say so
+when reporting: "verified as a geometry preview" is honest, "looks great" from an
+approximate render is not.
+
+If even the preview cannot run, the delivery is unverified: report the failing
+command, the file's slide count from `pptx read`, and the gate results, and tell
+the user which renderer to install for a visual check.
+
+## Gate summary
+
+| Gate | Command | Blocking |
+|---|---|---|
+| Package integrity | `inspect_presentation_package_integrity.py` | yes |
+| Layout geometry | `inspect_presentation_layout_geometry.py` | `fail` always, `review` with `--strict` |
+| Chart titles | `native_chart_title_gate.py` | yes |
+| Chart data | `native_quantitative_chart_gate.py` | yes for declared slides |
+| Table arithmetic | `native_table_arithmetic_gate.py` | yes for declared contracts |
+| Template fidelity | `template_source_fidelity_gate.py` | yes when requirements are supplied |

package/assets/skills/office-presentations/tasks/template-following.md

@@ -0,0 +1,132 @@
+# Task: follow a supplied template
+
+Use this when the user hands over a `.pptx` and says "use our template" or "match
+this deck". The design is already decided; your job is to put content into its
+own slides.
+
+## 1. Inspect
+
+```bash
+"<python>" "<skill>/template_following_scripts/inspect_template_deck.py" --template brand.pptx --out-dir template-inspect
+```
+
+Outputs:
+
+- `template-inspect.ndjson` — one JSON line per slide: layout name, layout
+  placeholders, slide placeholders (index, kind, rect in inches, text), shape
+  counts, text excerpt, whether the slide has full-bleed background art.
+- `template-manifest.json` — slide size, aspect ratio, layout names, theme font
+  names, and `backgroundArtSlides`.
+
+Read `backgroundArtSlides` before adding anything: those slides already carry
+artwork, so a new opaque panel will cover it.
+
+## 2. Plan
+
+Write `frame-map.json`:
+
+```json
+{
+  "template": "brand.pptx",
+  "newPrimitives": { "allowed": false, "justification": "" },
+  "outputSlides": [
+    {
+      "slide": 1,
+      "mode": "duplicate-slide",
+      "sourceSlide": 1,
+      "elements": [
+        {
+          "elementId": "title",
+          "action": "fill-placeholder",
+          "target": { "placeholder": "title", "text": "Automation Review" }
+        },
+        {
+          "elementId": "subtitle",
+          "action": "fill-placeholder",
+          "target": { "placeholder": "subtitle", "text": "Warehouse network · FY2026" }
+        }
+      ]
+    },
+    {
+      "slide": 2,
+      "mode": "duplicate-slide",
+      "sourceSlide": 3,
+      "elements": [
+        {
+          "elementId": "title",
+          "action": "rewrite",
+          "target": { "placeholder": "title", "text": "Throughput rose while touches fell" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Allowed actions: `rewrite`, `rewrite-and-reposition`, `replace`, `delete`,
+`keep`, `fill-placeholder`. `target.zone` is `[x, y, w, h]` in 0–1 slide
+fractions, used with `rewrite-and-reposition`. Elements whose `role` is
+`brand`, `logo`, `bumper`, `divider`, `section`, `chrome` or `footer` must stay
+`keep` — they are the template.
+
+Adding new shapes is opt-in: set `newPrimitives.allowed` and write a
+justification. The validator rejects shapes added without it, because "one extra
+box" is how a branded deck stops matching brand.
+
+## 3. Validate
+
+```bash
+"<python>" "<skill>/template_following_scripts/validate_template_plan.py" --plan frame-map.json
+```
+
+Rejects: unknown action, preserved role edited, zone outside 0–1, non-sequential
+slide numbers, missing justification for new primitives, and duplicate source
+slides (a warning — it means two output slides share artwork, usually fine for a
+repeated section divider, usually a copy-paste mistake otherwise).
+
+## 4. Build
+
+```bash
+"<python>" "<skill>/template_following_scripts/prepare_template_starter_deck.py" --template brand.pptx --plan frame-map.json --out starter.pptx
+```
+
+The starter deck keeps only the mapped source slides, in plan order, and applies
+the actions. It refuses duplicate source slides (it reuses slides rather than
+cloning parts). The report lists applied actions and any placeholder left empty.
+
+From here, extend with `container_tools/add_slides.py` or the recipes when the
+template has no family for a slide you need.
+
+## 5. Check fidelity
+
+```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
+```
+
+`fidelity.json`:
+
+```json
+{
+  "reference_slide_indices": [1, 3],
+  "mapping": { "1": 1, "2": 3 },
+  "minimum_coverage_ratio": 1.0,
+  "require_exact_dimensions": true,
+  "require_placeholder_geometry": true,
+  "require_photographic_background": false,
+  "geometry_tolerance_emu": 9144
+}
+```
+
+Both print `passed`. With no requirements, the fidelity gate is a deliberate
+no-op pass — pass a requirements file or you have not checked anything.
+
+## 6. Look at it
+
+```bash
+"<python>" "<skill>/container_tools/render_slides.py" --input starter.pptx --out-dir starter-preview
+```
+
+Compare against the source slides. A filled placeholder that overflows, a title
+in the wrong family, or a panel over the corner logo is exactly what this step
+exists to catch.

package/assets/skills/office-presentations/template_following_scripts/check_template_fidelity.py

@@ -0,0 +1,176 @@
+"""Catch the traces an authoring pass leaves in a template-based deck.
+
+Purpose: a deck can keep the template's layouts and still be wrong — a
+"Click to add title" prompt left in place, the template's instruction text
+still sitting in a body, or an opaque panel dropped exactly over the artwork
+the design relies on. None of those are visible in a plan; all of them are
+cheap to detect afterwards.
+
+Exit codes: 0 clean, 1 findings, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "container_tools"))
+
+from ooxml_helpers import box, has_visible_text, is_picture, overlap_ratio, text_of  # noqa: E402
+
+PLACEHOLDER_PATTERNS = [
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"^slide number$",
+        r"^date$",
+        r"^footer$",
+        r"^click to add (title|subtitle|text|body)",
+        r"^(title|subtitle|name|text|body) goes here$",
+        r"^lorem ipsum\b",
+        r"\btemplate instruction\b",
+        r"^\[.*\]$",
+    )
+]
+ART_COVER_MIN_RATIO = 0.9
+
+
+def _has_solid_fill(shape) -> bool:
+    try:
+        from pptx.enum.dml import MSO_FILL
+
+        return shape.fill.type == MSO_FILL.SOLID
+    except Exception:  # noqa: BLE001 - shapes without a fill API are never opaque panels
+        return False
+
+
+def _slide_size_in(slide) -> tuple[float, float]:
+    presentation = slide.part.package.presentation_part.presentation
+    return presentation.slide_width / 914400, presentation.slide_height / 914400
+
+
+def check(template_path: str | Path, final_path: str | Path, plan_path: str | Path | None = None) -> dict:
+    from pptx import Presentation
+
+    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-authoring-fidelity", "passed": False, "findings": [{"kind": "missing_file", "detail": str(candidate)}]}
+
+    template = Presentation(str(template_file))
+    final = Presentation(str(final_file))
+    template_slides = list(template.slides)
+    final_slides = list(final.slides)
+    plan = {}
+    if plan_path and Path(plan_path).is_file():
+        plan = json.loads(Path(plan_path).read_text(encoding="utf-8"))
+
+    findings: list[dict] = []
+    mapping: list[tuple[int, int]] = []
+    for entry in plan.get("outputSlides") or []:
+        mapping.append((int(entry.get("slide", len(mapping) + 1)), int(entry.get("sourceSlide", 0))))
+    if not mapping:
+        mapping = [(index, index) for index in range(1, min(len(template_slides), len(final_slides)) + 1)]
+
+    for output_index, source_index in mapping:
+        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
+        output_slide = final_slides[output_index - 1]
+        source_slide = template_slides[source_index - 1]
+
+        if output_slide.slide_layout.name != source_slide.slide_layout.name:
+            findings.append(
+                {
+                    "kind": "layout_drift",
+                    "severity": "review",
+                    "slide": output_index,
+                    "message": f"layout is '{output_slide.slide_layout.name}', template slide used '{source_slide.slide_layout.name}'",
+                }
+            )
+
+        for shape in output_slide.shapes:
+            if not has_visible_text(shape):
+                continue
+            text = text_of(shape).strip()
+            for pattern in PLACEHOLDER_PATTERNS:
+                if pattern.search(text):
+                    findings.append(
+                        {
+                            "kind": "leftover_placeholder_text",
+                            "severity": "fail",
+                            "slide": output_index,
+                            "shape": shape.name,
+                            "text": text[:80],
+                            "message": "template prompt text is still on the slide",
+                        }
+                    )
+                    break
+            if not text and shape.is_placeholder:
+                findings.append({"kind": "empty_placeholder", "severity": "review", "slide": output_index, "shape": shape.name, "message": "placeholder was left empty"})
+
+        inherited_art = [box(shape) for shape in source_slide.shapes if is_picture(shape) and box(shape)]
+        slide_w, slide_h = _slide_size_in(source_slide)
+        full_bleed = {
+            index
+            for index, art in enumerate(inherited_art)
+            if art[0] <= 0.02 and art[1] <= 0.02 and art[2] >= slide_w * 0.98 and art[3] >= slide_h * 0.98
+        }
+        for shape in output_slide.shapes:
+            # only an opaque panel is a problem: text over a background image is the template working
+            if is_picture(shape) or not _has_solid_fill(shape):
+                continue
+            geometry = box(shape)
+            if geometry is None:
+                continue
+            for art_index, art in enumerate(inherited_art):
+                if art_index in full_bleed:
+                    continue
+                ratio = overlap_ratio(geometry, art)
+                if ratio >= ART_COVER_MIN_RATIO:
+                    findings.append(
+                        {
+                            "kind": "template_art_covered",
+                            "severity": "fail",
+                            "slide": output_index,
+                            "shape": shape.name,
+                            "overlap": round(ratio, 2),
+                            "message": "a text or table block sits on top of the template artwork",
+                        }
+                    )
+                    break
+
+    blocking = [item for item in findings if item["severity"] == "fail"]
+    return {
+        "gate": "template-authoring-fidelity",
+        "template": str(template_file.resolve()),
+        "final": str(final_file.resolve()),
+        "plan": str(plan_path) if plan_path else None,
+        "mappedSlides": len(mapping),
+        "findings": findings,
+        "passed": not blocking,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Find leftover template prompts, layout drift and covered artwork.")
+    parser.add_argument("--template", required=True, help="the template .pptx")
+    parser.add_argument("--final", required=True, help="the finished .pptx")
+    parser.add_argument("--plan", help="optional template-frame-map.json for the slide mapping")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+
+    report = check(args.template, args.final, args.plan)
+    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/template_following_scripts/inspect_template_deck.py

@@ -0,0 +1,154 @@
+"""Read a template deck into records an author can plan against.
+
+Purpose: matching a supplied deck starts with knowing what it actually is —
+slide size, which layouts exist, what each slide inherits, where the title and
+body sit, which elements repeat on every slide, what type and colours the theme
+carries. Guessing from memory of "a normal 16:9 deck" is how a template gets
+flattened.
+
+Writes:
+  <out-dir>/template-inspect.ndjson    one JSON record per slide
+  <out-dir>/template-manifest.json     deck level summary
+
+Exit codes: 0 written, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "container_tools"))
+
+from ooxml_helpers import box, has_visible_text, is_chart, is_picture, is_table, placeholder_kind, slide_size_in, text_of  # noqa: E402
+
+
+def _theme(presentation) -> dict:
+    fonts: set[str] = set()
+    fills: set[str] = set()
+    for master in presentation.slide_masters:
+        for layout in master.slide_layouts:
+            for shape in layout.shapes:
+                if has_visible_text(shape):
+                    for paragraph in shape.text_frame.paragraphs:
+                        for run in paragraph.runs:
+                            if run.font.name:
+                                fonts.add(run.font.name)
+    for slide in presentation.slides:
+        for shape in slide.shapes:
+            if has_visible_text(shape):
+                for paragraph in shape.text_frame.paragraphs:
+                    for run in paragraph.runs:
+                        if run.font.name:
+                            fonts.add(run.font.name)
+    return {"fontsSeen": sorted(fonts), "colourSourcesNote": "check layouts and masters in PowerPoint for exact theme colours"}
+
+
+def inspect_template(template_path: str | Path, out_dir: str | Path) -> dict:
+    from pptx import Presentation
+
+    source = Path(template_path)
+    if not source.is_file():
+        return {"ok": False, "error": {"code": "input_missing", "message": f"no such file: {source}"}}
+    presentation = Presentation(str(source))
+    slide_w, slide_h = slide_size_in(presentation)
+    destination = Path(out_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    records: list[dict] = []
+    for index, slide in enumerate(presentation.slides, start=1):
+        layout = slide.slide_layout
+        placeholders = []
+        for shape in slide.shapes:
+            if not shape.is_placeholder:
+                continue
+            placeholders.append(
+                {
+                    "idx": shape.placeholder_format.idx,
+                    "kind": placeholder_kind(shape) or "",
+                    "type": int(shape.placeholder_format.type) if shape.placeholder_format.type is not None else None,
+                    "bboxIn": [round(value, 3) for value in (box(shape) or (0, 0, 0, 0))],
+                    "text": text_of(shape)[:120],
+                }
+            )
+        layout_placeholders = [
+            {
+                "idx": shape.placeholder_format.idx,
+                "kind": placeholder_kind(shape) or "",
+                "bboxIn": [round(value, 3) for value in (box(shape) or (0, 0, 0, 0))],
+            }
+            for shape in layout.shapes
+            if shape.is_placeholder
+        ]
+        records.append(
+            {
+                "slide": index,
+                "layout": layout.name,
+                "layoutIndex": list(presentation.slide_layouts).index(layout) if layout in list(presentation.slide_layouts) else None,
+                "layoutPlaceholders": layout_placeholders,
+                "placeholders": placeholders,
+                "shapes": len(slide.shapes),
+                "pictures": sum(1 for shape in slide.shapes if is_picture(shape)),
+                "charts": sum(1 for shape in slide.shapes if is_chart(shape)),
+                "tables": sum(1 for shape in slide.shapes if is_table(shape)),
+                "textExcerpt": " | ".join(text_of(shape)[:80] for shape in slide.shapes if has_visible_text(shape))[:240],
+                "backgroundPicture": any(
+                    is_picture(shape) and box(shape) and box(shape)[2] >= slide_w * 0.95 and box(shape)[3] >= slide_h * 0.95
+                    for shape in slide.shapes
+                ),
+            }
+        )
+
+    manifest = {
+        "template": str(source.resolve()),
+        "slideSizeIn": [round(slide_w, 3), round(slide_h, 3)],
+        "aspect": "16:9" if abs(slide_w / slide_h - 16 / 9) < 0.02 else "4:3" if abs(slide_w / slide_h - 4 / 3) < 0.02 else "custom",
+        "slideCount": len(presentation.slides),
+        "layouts": [layout.name for layout in presentation.slide_layouts],
+        "masters": len(presentation.slide_masters),
+        "slides": [{key: record[key] for key in ("slide", "layout", "shapes", "backgroundPicture")} for record in records],
+        "theme": _theme(presentation),
+    }
+
+    ndjson = destination / "template-inspect.ndjson"
+    ndjson.write_text("\n".join(json.dumps(record, ensure_ascii=False) for record in records) + "\n", encoding="utf-8")
+    manifest_path = destination / "template-manifest.json"
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    return {
+        "ok": True,
+        "template": str(source.resolve()),
+        "records": len(records),
+        "ndjson": str(ndjson.resolve()),
+        "manifest": str(manifest_path.resolve()),
+        "summary": {
+            "slideCount": manifest["slideCount"],
+            "slideSizeIn": manifest["slideSizeIn"],
+            "aspect": manifest["aspect"],
+            "layouts": manifest["layouts"],
+            "backgroundArtSlides": [record["slide"] for record in records if record["backgroundPicture"]],
+        },
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Summarise a template deck: layouts, placeholders, geometry, theme.")
+    parser.add_argument("template", nargs="?", help="path to the template .pptx")
+    parser.add_argument("--template", dest="template_opt", help="path to the template .pptx (same as the positional)")
+    parser.add_argument("--out-dir", required=True, help="directory for template-inspect.ndjson and template-manifest.json")
+    args = parser.parse_args(argv)
+    template = args.template_opt or args.template
+    if not template:
+        parser.error("a template .pptx path is required (positional or --template)")
+
+    report = inspect_template(template, args.out_dir)
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report.get("ok") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())