dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-pdf/tasks/read.md

@@ -0,0 +1,62 @@
+# Read text, tables, and page images
+
+Text extraction reads the page content stream: glyph runs carry position and a font, and a library groups them into words and lines. A page with no text operators (a scan or a photo export) yields nothing no matter which extractor is used — that is a property of the file, not of the tool.
+
+## Fast path: plain text and structure
+
+```bash
+"<python>" "<cli>" pdf read --input "<file.pdf>" --json-out "<read.json>"
+```
+
+Returns `page_count`, `word_count`, document metadata, per-page text (with character counts), and AcroForm field identifiers. `scripts/render_pages.py --input "<file.pdf>"` adds geometry: page size, rotation, drawings, annotations, widgets, and the characters inside an optional crop.
+
+## Tables and layout with pdfplumber
+
+```bash
+"<python>" "<skill>/scripts/extract_text.py" --input "<file.pdf>" --json-out "<tables.json>"
+```
+
+Each page reports its characters and detected tables as rows of cell strings. The detection uses the page's ruling lines and word spacing, so a borderless table often comes back as running text; `--layout` keeps the spacing of the original lines for a manual look.
+
+When the detection looks wrong, inspect rather than guess:
+
+```bash
+"<python>" - <<'PY'
+import pdfplumber
+with pdfplumber.open("in.pdf") as pdf:
+    page = pdf.pages[0]
+    print("chars", len(page.chars), "lines", len(page.lines), "rects", len(page.rects))
+    for table in page.find_tables():
+        print(table.bbox, table.extract()[:3])
+    print(page.extract_text()[:400])
+PY
+```
+
+`chars`, `lines`, and `rects` tell you whether the table has rules at all. A table with no lines is best read from `extract_text` with `--layout`, where the column gaps survive as spaces.
+
+## Page images
+
+A page may contain embedded rasters that are invisible in text extraction. List them with PyMuPDF:
+
+```bash
+"<python>" - <<'PY'
+import pymupdf
+doc = pymupdf.open("in.pdf")
+for number, page in enumerate(doc, 1):
+    for image in page.get_images(full=True):
+        print(number, image[0], image[2], "x", image[3])
+PY
+```
+
+Extract one with `page.get_pixmap(clip=...)` or `doc.extract_image(xref)` when the user needs the picture itself. Rendering the page at 150–200 dpi and cropping with `read_image` is the reliable way to *see* it.
+
+## What fails and how to resolve it
+
+- **Scanned page, no text**: there is no text layer to read. Say so; the render shows the image of the words. Resolutions: work from a text-based copy of the file, or read the pages visually and type the content into a rebuild. Do not claim extraction succeeded on an empty result.
+- **Empty string from a page that shows text**: the page may use a font with a broken ToUnicode map, or the text may be drawn as vector outlines. Check the render before concluding; if it is outlines, extraction cannot recover the words.
+- **Wrong reading order in multi-column layouts**: raw extraction follows the operator order. Crop each column with a rect and extract per column, `get_textbox(rect)` on a PyMuPDF page is the simplest split.
+- **Ligatures and soft hyphens**: extraction may glue or split words; quote extracted text only after reading the same passage on the render.
+
+## Verify
+
+Rendering the page is the check for every extraction: the characters you return must be visible in that image. Watch for a page whose extracted text is suspiciously short (a missing text layer), duplicated (headers repeated per page), or full of replacement glyphs (broken encoding) before you build anything on top of it.

package/assets/skills/office-pdf/tasks/redact.md

@@ -0,0 +1,72 @@
+# Remove a region of a page
+
+Redaction here means *destruction*, not a black box: the glyphs and vector paths inside a rectangle are deleted from the content stream, so no text extractor can recover them afterwards. A rectangle that only covers them visually is not a redaction, and "black out then flatten" leaks the original text.
+
+## Fast path: the region script
+
+```bash
+"<python>" "<skill>/scripts/redact_region.py" --input "<file.pdf>" --out "<file-redacted.pdf>" \
+  --annotations '{"page":1,"region":{"left":0.064,"top":0.318,"width":0.891,"height":0.153}}' \
+  --json-out "<redact.json>"
+```
+
+The payload is the annotation shape: 1-based page plus a region normalised 0–1 against the rendered page. The script converts it, expands the rectangle by `--pad` points (default 2.5), calls `add_redact_annot(rect, fill=None)` then `apply_redactions(images=PDF_REDACT_IMAGE_NONE, graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED, text=PDF_REDACT_TEXT_REMOVE)`, and reports `removed_chars`, `removed_drawings`, the per-page before/after counts, and `leftover_chars_in_rect`. `--region`/`--page` do the same for a single value without JSON. Multiple annotations in one payload are applied page by page.
+
+## Why the rectangle needs padding
+
+A line of text sits on a baseline and its glyphs can overhang the geometric box by a fraction of a point; selection boxes from a preview are approximate too. Expanding by 2–3 points catches ascenders, descenders, rules that touch the text, and the anti-aliased edge, while staying clear of neighbours. Measure, do not guess: `get_textbox(rect)` before the redaction lists what the rectangle will take, and `leftover_chars_in_rect` after it must be zero.
+
+Do it by hand when you need a different shape or a dry run:
+
+```bash
+"<python>" - <<'PY'
+import pymupdf
+doc = pymupdf.open("in.pdf")
+page = doc[0]
+r = page.rect
+rect = pymupdf.Rect(r.x0 + 0.064 * r.width, r.y0 + 0.318 * r.height,
+                    r.x0 + 0.955 * r.width, r.y0 + 0.471 * r.height)
+rect = (rect + (-2.5, -2.5, 2.5, 2.5)) & page.rect
+print("will remove:", repr(page.get_textbox(rect)[:200]))
+before = len(page.get_text()), len(page.get_drawings())
+page.add_redact_annot(rect, fill=None)
+page.apply_redactions(images=pymupdf.PDF_REDACT_IMAGE_NONE,
+                      graphics=pymupdf.PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED)
+after = len(page.get_text()), len(page.get_drawings())
+print("chars/drawings", before, "->", after)
+doc.save("out.pdf", garbage=3, deflate=True)
+PY
+```
+
+## The flags are not interchangeable
+
+- `fill=None` erases without painting. A fill colour (`fill=(1, 1, 1)`) paints a rectangle, which itself becomes a new drawing and hides the page's own background tint; the drawing count then goes up, not down.
+- `images=PDF_REDACT_IMAGE_NONE` leaves pictures untouched: a scanned region stays visible. Use `PDF_REDACT_IMAGE_PIXELS` to blank the pixels a rectangle covers inside an image, and only use a stronger setting when the user wants the whole image gone.
+- `graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED` deletes paths that intersect the rectangle; paths entirely inside it are always removed. `PDF_REDACT_LINE_ART_NONE` keeps all line art, which is right when only text should disappear.
+- Text removal is the default (`PDF_REDACT_TEXT_REMOVE`); keeping the text while erasing its surroundings is almost never what the user means.
+
+## Counting the result
+
+`removed_chars` is the page-level difference in extracted text; `region_chars_removed` is the text that was inside the rectangle. They differ by the newline or space that joins the removed block to its neighbours, so expect them to be equal or one apart. Document-level totals are the sum over the changed pages. A run that removes fewer characters than the region held means the rectangle missed part of the block — enlarge `--pad` or convert the geometry again.
+
+Cross-check on the sample document: page 1, region `{left: 0.064, top: 0.318, width: 0.891, height: 0.153}` deletes the "Latest News" block and nothing else. Measured: 16 drawings → 5, page text 1049 → 879 characters (the block held 169), `leftover_chars_in_rect` 0, and the body paragraph, header, and footer still extract and render.
+
+## Leftovers redaction does not cover
+
+- **Metadata and embedded files**: the info dictionary and attachments are not page content. Clear them when the user asks for a clean file (see `scripts/metadata.py`), and note that a document ID/xref may still fingerprint the file.
+- **Previous revisions**: incrementally saved files can retain old objects. Saving with `garbage=3, deflate=True` compacts the file; when the user needs forensic certainty, say that the output was rebuilt and confirm with a text search that the words are gone.
+- **Images inside the region**: by default they stay. If the region is a screenshot of the sensitive text, switch to `--images pixels` or rebuild the page.
+
+## Verify
+
+Render after the redaction and look at the page. The region must be empty, the surrounding text intact, and any ruled boxes that belonged to the block gone rather than half-erased. Then search the output for the removed words:
+
+```bash
+"<python>" - <<'PY'
+import pymupdf
+text = pymupdf.open("out.pdf")[0].get_text()
+print("latest news" in text.lower(), len(text))
+PY
+```
+
+If they still appear, the rectangle missed them — fix the geometry, do not hand the file over.

package/assets/skills/office-pdf/tasks/stamp.md

@@ -0,0 +1,60 @@
+# Stamp a footer, header, or label
+
+An overlay is a tiny one-page PDF drawn with reportlab and merged onto the target page, so the original content stream is untouched and existing widgets keep working. Position is in points measured from the bottom-left of the page box; a stamp on an A4 page has 842 points of height to work with.
+
+## Fast path: the stamp script
+
+```bash
+"<python>" "<skill>/scripts/stamp_overlay.py" --input "<file.pdf>" --out "<file-stamped.pdf>" \
+  --text "Confidential - page {page} of {pages}" --position bottom-center --render-dir "<render>"
+```
+
+`{page}` and `{pages}` are substituted per page. Positions: `bottom-left`, `bottom-center`, `bottom-right`, `top-left`, `top-center`, `top-right`; `--pages "1,3-5"` limits the stamp; `--font-size`, `--font`, `--color`, `--margin`, and `--opacity` control the look. The script merges page by page with pypdf, refuses to overwrite the input, and can render the stamped pages so you can look at them.
+
+## Draw it yourself
+
+Use reportlab directly when the stamp is a bar, a rotated line, or a block of text:
+
+```bash
+"<python>" - <<'PY'
+import io
+from pypdf import PdfReader, PdfWriter
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.colors import HexColor
+from reportlab.pdfgen import canvas
+
+reader = PdfReader("in.pdf")
+writer = PdfWriter()
+for index, page in enumerate(reader.pages):
+    width = float(page.mediabox.width)
+    height = float(page.mediabox.height)
+    buffer = io.BytesIO()
+    c = canvas.Canvas(buffer, pagesize=(width, height))
+    c.setFillColor(HexColor("#c0392b"))
+    c.setFont("Helvetica-Bold", 10)
+    c.saveState()
+    c.translate(width / 2, 18)
+    c.drawCentredString(0, 0, f"CONFIDENTIAL  |  page {index + 1} of {len(reader.pages)}")
+    c.restoreState()
+    c.save()
+    buffer.seek(0)
+    page.merge_page(PdfReader(buffer).pages[0])
+    writer.add_page(page)
+with open("out.pdf", "wb") as handle:
+    writer.write(handle)
+PY
+```
+
+Use the page's own `mediabox` rather than a hard-coded A4 size when the source may mix page sizes; a stamp drawn for A4 lands in the wrong place on a landscape page. `merge_page` paints over the page, so a solid bar hides whatever it covers — place it in a margin or inside a band you intend to cover.
+
+## Pitfalls
+
+- **Collisions with existing footers**: check the bottom margin first; the render is the proof, not the coordinate math. If the document already has a page number, either skip the stamp or put it on the opposite side.
+- **Rotated pages**: a page with `/Rotate 90` renders sideways; text drawn in the unrotated coordinate system will appear rotated in the viewer. Either rotate the stamp with `c.rotate(90)` and adjust the origin, or rotate the page back first.
+- **Repeated stamping**: merging the same overlay twice doubles the opacity and positions identically; re-run from the original input when iterating.
+- **Fonts**: Helvetica handles Latin; a CJK stamp needs a registered TTF, otherwise the text renders as blank boxes. Check the render.
+- **Opacity**: `setFillAlpha` is applied by viewers that honour transparency groups; a stamp that must be visible on any viewer is safer with full opacity.
+
+## Verify
+
+Render every stamped page and check: the text sits inside the margin, does not overlap body text or an existing footer, is the size the user asked for, and appears on exactly the selected pages. Then run `"<python>" "<cli>" pdf read --input "<file-stamped.pdf>"` — the stamp's text will join the page text, so a search for the label confirms it landed once, not twice.

package/assets/skills/office-presentations/SKILL.md

@@ -1,110 +1,164 @@
 ---
-description: Create, inspect, edit, and render PowerPoint .pptx slide decks with the bundled Office helper CLI.
+description: Build, inspect, restyle, and verify PowerPoint .pptx slide decks with python-pptx plus the bundled Office helper CLI.
 ---
 
 # Presentations (.pptx)
 
-Build local PowerPoint decks with native text, tables, charts, and images, then render them to verify layout. This skill uses `python-pptx`; it does not use the `@oai/artifact-tool` runtime and does not edit Google Slides.
+A deck is a zip of XML parts: slides, layouts, masters, charts with embedded
+workbooks, notes, media. Everything the audience sees comes from those parts, so
+this pack teaches you to (a) author those parts correctly and (b) read them back
+before delivering.
 
-## Before any file work
+Two layers:
 
-1. Call the `office_status` tool.
-2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file.
-3. If no compatible Python is reported, stop and tell the user. Do not deliver a deck you could not create or verify.
+- **The helper CLI** — a deterministic accelerator for common cases:
+  `<python> "<cli>" pptx {create|read|render}`, plus `office_status`. It creates
+  from a JSON spec, reads structure back, and renders. It does not mutate.
+- **This pack** — the capability layer. Recipes for anything the CLI does not
+  cover ([`recipes/`](recipes/README.md)), runnable tools for mutation and gates
+  in [`container_tools/`](container_tools/), template-following in
+  [`template_following_scripts/`](template_following_scripts/).
 
-## Create
+Authoring is `python-pptx`. Not a page-description format, not a screenshot: real
+shapes, real chart parts, real notes.
 
-```bash
-"<python>" "<cli>" pptx create --spec "<spec.json>" --out "<output.pptx>"
-```
+## Before any file work
 
-```json
-{
-  "title": "Annual Review",
-  "author": "DSH Office Suite",
-  "slides": [
-    { "layout": "title", "title": "Annual Review", "subtitle": "FY2026 · Internal" },
-    { "layout": "bullets", "title": "Highlights", "bullets": ["Revenue up 18.4%", { "text": "New markets", "level": 1 }] },
-    {
-      "layout": "blank",
-      "title": "Revenue by quarter",
-      "table": { "headers": ["Quarter", "Revenue"], "rows": [["Q1", 100], ["Q2", 128]] },
-      "chart": {
-        "type": "column",
-        "title": "Quarterly revenue",
-        "left": 3.6,
-        "top": 3.5,
-        "width": 8.8,
-        "height": 3.0,
-        "categories": ["Q1", "Q2"],
-        "series": [{ "name": "Revenue", "values": [100, 128] }]
-      },
-      "image": { "path": "<absolute image path>", "left": 0.8, "top": 3.9, "width": 2.2 }
-    }
-  ]
-}
-```
+1. Call the `office_status` tool.
+2. Read the `## Office runtime` JSON block appended to this file and use the
+   absolute `python`, `cli`, `skill` and `shared` values from it. Quote paths.
+3. If that block reports no working runtime, stop: tell the user to run the
+   `node "..."` remedy command it names, then call `office_status` again. Never
+   claim a deck was created or verified without a runtime to create and verify
+   it with.
 
-Layouts: `title`, `bullets`, `section`, `title_only`, `blank`. The deck is 16:9 (13.333 × 7.5 in).
+## Delivery
 
-- `bullets` uses the body placeholder; items may be strings or `{ "text", "level" }`.
-- `blank` / `title_only` place content with a vertical cursor starting at 1.5 in. A table advances the cursor; a chart without `top` starts at the cursor and gets a fitted height; an image without `top` starts at the cursor. Explicit `left`/`top`/`width`/`height` in inches are honored, so use them when combining elements side by side.
-- A blank slide with a `title` gets a generated title textbox (32 pt bold).
-- Chart types: `column`, `line`, `pie` (`bar` is accepted as a column alias). Each series needs a `name` and numeric `values`.
+Always hand the finished file to the user with the `present` tool, then summarise in one sentence what changed. A bare path is not delivery: the chat transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动" and the user cannot open them.
 
-## Read
+- Creating a file: write it into the user's workspace, verify it, then `present`.
+- Editing an existing file: never overwrite the original. Write `<original>-edited.<ext>` (or a name the user asked for), verify it, `present` it, and state both paths.
 
-```bash
-"<python>" "<cli>" pptx read --input "<file.pptx>"
-```
+## Annotations
 
-Returns slide count, per-slide title, all text, tables, chart categories/series, and image counts. Use it to confirm edits and to inventory a deck you did not create.
+The user may reply with an `office-annotations` block: `[{ page, text, requirement, region: { left, top, width, height } }]`. `region` is normalised 0–1 against the rendered preview page the user drew on; `requirement` is free-form natural language. Treat it as a change request, not as editor state: locate what the region covers, apply the smallest edit that satisfies `requirement`, re-render, and confirm the region now looks right.
 
-## Edit
+When the payload cannot be mapped to a concrete object (the region is empty or the file has no geometry), do not guess silently — say what you could not locate.
 
-```bash
-"<python>" "<cli>" pptx edit --input "<file.pptx>" --spec "<edit.json>" --out "<file-edited.pptx>"
-```
-
-```json
-{
-  "replace": [{ "find": "18.4%", "replace": "21.0%" }],
-  "slides": [{ "layout": "bullets", "title": "Next steps", "bullets": ["Finalize acceptance", "Publish docs"] }],
-  "core": { "title": "Annual Review (final)" }
-}
-```
+**pptx mapping.** `page` is the preview slide index (1-based, the `slide-NN.png`
+you rendered). The region selects shapes whose bounding box overlaps it:
+`left_in = region.left * slide_width_in`, and likewise for top/width/height.
+`text` disambiguates overlapping shapes (a title over a background panel).
+Resolve candidates from
+`container_tools/inspect_presentation_layout_geometry.py --json-out geometry.json`,
+then apply the edit through a mutation tool or a recipe. Full procedure:
+[tasks/apply-annotations.md](tasks/apply-annotations.md).
 
-`replace` edits text runs. It cannot edit text split across runs, chart data labels, notes, or tables; use table replacement only by recreating the table on a new slide. New slides are appended.
+## Verify
 
-## Render and verify
+Render, look at every page, then deliver — in that order, with nothing skipped.
 
 ```bash
-"<python>" "<cli>" pptx render --input "<file.pptx>" --out-dir "<render-dir>"
+"<python>" "<skill>/container_tools/render_slides.py" --input "<file.pptx>" --out-dir "<render-dir>"
 ```
 
-The renderer prefers Microsoft PowerPoint COM on Windows and LibreOffice otherwise, producing a PDF and one PNG per slide. Inspect every slide for:
-
-- title and body within margins;
-- tables and charts not overlapping each other or images;
-- legible font sizes (body ≥ 18 pt, title ≥ 28 pt);
-- no clipped text or empty placeholders;
-- chart labels/categories correct.
-
-If the render shows overlap, fix coordinates and re-render. Do not claim a deck is presentation-ready if it was never rendered.
-
-## Design rules
-
-- One idea per slide. Prefer 3–6 bullets; split dense content.
-- Use sentence case, parallel phrasing, and real figures only.
-- Use native tables/charts, not screenshots of spreadsheets where a native chart fits.
-- Keep a consistent palette and alignment grid; do not decorate with random shapes.
-- Choose `blank` for composed layouts and `bullets`/`title` for simple text slides.
-
-## Not supported
-
-- Google Slides / Google Drive editing.
-- Slide master, theme, template, or layout editing.
-- Animations, transitions, speaker notes, hyperlinks, audio/video, SmartArt.
-- Editing existing chart data in place, or replacing table cells in place.
-- `@oai/artifact-tool` helpers, montage/integrity gates, or template-fidelity workflows.
-- PowerPoint-perfect pagination; rendering is a fidelity check.
+`render_slides.py` uses the CLI's `pptx render` — which drives Microsoft
+PowerPoint, WPS Presentation, or LibreOffice, whichever is installed — and falls
+back to a draft preview when none is, so this one command is always the right
+entry point. The JSON names the engine it used in `engine`.
+
+Then open each PNG with `read_image` (or build one sheet with
+`"<skill>/template_following_scripts/make_contact_sheet.py"`). Check: titles
+one or two lines, body ≥ 18 pt, nothing clipped or outside the slide, no empty
+placeholder, table and chart not overlapping, chart readable at thumbnail size.
+
+If no office suite is installed, `render_slides.py` falls back to
+`--engine draft`, a PyMuPDF geometry preview. It proves placement, not
+typography — say which one you used.
+
+Gates that print JSON with a `passed` field, all blocking when they say `false`:
+`inspect_presentation_package_integrity.py`,
+`inspect_presentation_layout_geometry.py`, `native_chart_title_gate.py`,
+`native_quantitative_chart_gate.py`, `native_table_arithmetic_gate.py`,
+`template_source_fidelity_gate.py`. Details:
+[tasks/inspect-and-verify.md](tasks/inspect-and-verify.md).
+
+Never present a deck you have not rendered and looked at.
+
+## Tasks
+
+One file per job:
+
+| Job | Start here |
+|---|---|
+| Create a deck | [tasks/create-deck.md](tasks/create-deck.md) |
+| Edit an existing deck | [tasks/edit-deck.md](tasks/edit-deck.md) |
+| Inspect, gate and verify | [tasks/inspect-and-verify.md](tasks/inspect-and-verify.md) |
+| Follow a supplied template | [tasks/template-following.md](tasks/template-following.md) |
+| Charts, tables, speaker notes | [tasks/charts-tables-notes.md](tasks/charts-tables-notes.md) |
+| Apply an annotation payload | [tasks/apply-annotations.md](tasks/apply-annotations.md) |
+
+## Tools and recipes
+
+Mutations (each prints one JSON object, exits non-zero on failure, defaults to
+`<original>-edited.pptx`):
+
+| Need | Command |
+|---|---|
+| Find/replace text, run-level | `"<skill>/container_tools/replace_text.py" --input "<deck>" --find "old" --replace "new"` |
+| Append slides | `"<skill>/container_tools/add_slides.py" --input "<deck>" --spec "<slides.json>"` |
+| Title/author/subject/keywords | `"<skill>/container_tools/core_properties.py" --input "<deck>" --title "..."` |
+| Render (office, else draft) | `"<skill>/container_tools/render_slides.py" --input "<deck>" --out-dir "<dir>"` |
+| Contact sheet / montage | `"<skill>/template_following_scripts/make_contact_sheet.py" --dir "<dir>" --out "<sheet.png>"` |
+
+Template flow: `inspect_template_deck.py` → write a frame map →
+`validate_template_plan.py` → `prepare_template_starter_deck.py` →
+`check_template_fidelity.py`.
+
+Recipes (paste-runnable, each with the pitfall it avoids):
+[README](recipes/README.md) ·
+[textbox at a coordinate](recipes/textbox-at-coordinate.md) ·
+[auto-layout](recipes/autolayout.md) ·
+[tables](recipes/tables.md) ·
+[native charts](recipes/native-charts.md) ·
+[masters and layouts](recipes/master-and-layouts.md) ·
+[speaker notes](recipes/speaker-notes.md) ·
+[theme tokens](recipes/theme-tokens.md) ·
+[rich text runs](recipes/rich-text-runs.md) ·
+[images](recipes/images.md) ·
+[connectors](recipes/connectors.md).
+
+Guidance: [authoring workflow](references/authoring-workflow.md) ·
+[style](references/style-guidelines.md) ·
+[bullets](references/native-bullets.md) ·
+[evidence](references/native-evidence.md) ·
+[templates](references/templates.md) ·
+[finalization](references/finalization.md) ·
+[finance decks](domain_guidance/finance.md) ·
+[Google Slides hand-off](routing/google_slides.md).
+
+## Non-negotiables
+
+- One idea per slide; a title is a claim, not a label.
+- Body ≥ 18 pt, title ≥ 28 pt, captions ≥ 12 pt.
+- Native charts and tables, never a picture of a spreadsheet.
+- Every placeholder filled or deleted; no "Chart Title", no trailing full stop
+  on a heading.
+- Numbers in the deck must agree with the numbers that were supplied.
+- New output lives in the user's workspace; an edit is a new file.
+
+## Genuine gaps
+
+- No Microsoft Office, WPS Office, or LibreOffice installed → no true render;
+  use `--engine draft` and say the check was geometric. Installing any of them
+  fixes it.
+- Fonts the user's machine lacks are substituted by any renderer; the pack
+  cannot install fonts.
+- Google Slides import fidelity is out of our control; see
+  [routing/google_slides.md](routing/google_slides.md).
+
+## Shared workflow
+
+Use `"<shared>/common-workflow.md"` for the cross-format delivery and
+verification loop, and `"<shared>/annotation-recipes.md"` when turning an
+annotation payload into an edit.

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

@@ -0,0 +1,143 @@
+"""Append slides to an existing deck using the shared slide builder.
+
+The slide builder lives in `python/office_cli.py` (`_pptx_add_slide`), so this
+tool imports it instead of reimplementing titles, bullet bodies, tables, charts
+and pictures. Anything `pptx create --spec` accepts inside `slides[]` is
+accepted here.
+
+Usage
+-----
+    <python> add_slides.py --input deck.pptx --spec extra-slides.json
+    <python> add_slides.py --input deck.pptx --slide '{"layout":"bullets","title":"Next"}' --out deck-2.pptx
+
+Exit codes
+----------
+0  slides appended
+2  bad arguments, invalid spec, or a slide that the builder rejected
+3  the output file could not be written
+
+The JSON report on stdout is `{ok, input, output, added, slides, counts}`.
+"""
+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
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[4]
+CLI_DIR = PACKAGE_ROOT / "python"
+COUNTERS = ("slides", "bullets", "tables", "charts", "images")
+
+
+def _emit(payload: dict, code: int = 0) -> int:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return code
+
+
+def _load_slides(spec_path: str | None, inline: list[str]) -> list[dict]:
+    slides: list[dict] = []
+    if spec_path:
+        data = json.loads(Path(spec_path).read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            slides.extend(data.get("slides") or [])
+        elif isinstance(data, list):
+            slides.extend(data)
+        else:
+            raise ValueError("spec must be an object with 'slides' or a list of slides")
+    for raw in inline:
+        slides.append(json.loads(raw))
+    for slide in slides:
+        if not isinstance(slide, dict):
+            raise ValueError(f"slide must be an object: {slide!r}")
+    return slides
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Append slides to a .pptx with the same builder the helper CLI uses.",
+        epilog="Exit codes: 0 appended, 2 bad input, 3 write failure.",
+    )
+    parser.add_argument("--input", required=True, help="deck to extend")
+    parser.add_argument("--spec", help="JSON file: {slides:[...]} or a list of slides")
+    parser.add_argument("--slide", action="append", default=[], help="one slide as inline JSON (repeatable)")
+    parser.add_argument("--out", help="output deck (default: <input>-edited.pptx)")
+    args = parser.parse_args()
+
+    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:
+        slides = _load_slides(args.spec, args.slide)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return _emit({"ok": False, "error": f"bad spec: {error}"}, 2)
+    if not slides:
+        return _emit({"ok": False, "error": "nothing to add: pass --spec or --slide"}, 2)
+
+    if not CLI_DIR.is_dir():
+        return _emit({"ok": False, "error": f"helper CLI not found at {CLI_DIR}"}, 2)
+    sys.path.insert(0, str(CLI_DIR))
+    try:
+        import office_cli  # noqa: PLC0415 - optional dependency, resolved at run time
+    except ImportError as error:
+        return _emit({"ok": False, "error": f"cannot import the slide builder: {error}"}, 2)
+
+    from pptx import Presentation  # noqa: PLC0415
+
+    try:
+        prs = Presentation(str(source))
+    except Exception as error:  # noqa: BLE001
+        return _emit({"ok": False, "error": f"cannot open {source}: {error}"}, 2)
+
+    before = len(prs.slides)
+    counters = {key: 0 for key in COUNTERS}
+    added: list[dict] = []
+    for slide_spec in slides:
+        try:
+            slide = office_cli._pptx_add_slide(prs, slide_spec, counters)  # noqa: SLF001
+        except Exception as error:  # noqa: BLE001 - report which slide failed
+            return _emit(
+                {"ok": False, "error": f"slide {len(added) + 1} rejected: {error}", "added": added},
+                2,
+            )
+        added.append(
+            {
+                "position": len(prs.slides),
+                "layout": str(slide_spec.get("layout", "bullets")),
+                "title": slide_spec.get("title"),
+                "placeholder_count": len(slide.placeholders),
+            }
+        )
+
+    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)
+
+    return _emit(
+        {
+            "schema": "add_slides/1",
+            "ok": True,
+            "input": str(source),
+            "output": str(output),
+            "added": len(added),
+            "before": before,
+            "slides": len(prs.slides),
+            "counts": counters,
+            "details": added,
+        }
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())