anymous 1.2.7 → 1.3.0

package/skills/pptx/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: pptx
+description: "Use this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill."
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# PPTX creation, editing, and analysis
+
+A `.pptx` is a ZIP archive of XML files. Choose your approach by task:
+
+| Task | Approach |
+|---|---|
+| **Create** a new deck | Write a `pptxgenjs` script — see gotchas below |
+| **Edit** an existing deck, or build from a template | unzip → edit `ppt/slides/slideN.xml` → zip |
+| **Read** content | `markitdown deck.pptx` (one block per slide under `<!-- Slide number: N -->` markers); visual grid: `python scripts/thumbnail.py deck.pptx` |
+
+## Scripts
+
+Paths are relative to this skill's directory. Everything else is plain Python, `node`, or shell.
+
+| Script | What it does |
+|---|---|
+| `scripts/thumbnail.py deck.pptx [prefix]` | Labeled grid of every slide, for picking template layouts. `.pptx` only. Pass `prefix` — it defaults to `thumbnails`, which overwrites the grids of any other deck done in the same directory |
+| `scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml]` | Duplicate a slide (or a `slideLayoutN.xml`) with all the package bookkeeping. Also takes a `.pptx` directly with `-o out.pptx` |
+| `scripts/clean.py unpacked/` | Delete slides, media, and rels no longer referenced. Run **after** `<p:sldIdLst>` is final |
+| `scripts/office/validate.py deck.pptx [--original src.pptx]` | Schema, relationship, content-type, chart and slide checks; each failure names its fix. Pass `--original` for any template-derived deck — it baselines the schema checks against the template, so the template's own XSD errors don't read as yours |
+| `scripts/office/soffice.py --headless --convert-to pdf deck.pptx` | LibreOffice wrapper — bare `soffice` hangs in this sandbox |
+
+## Creating with pptxgenjs — gotchas
+
+`pptxgenjs` is preinstalled — do not run `npm install` first; write the script and `require('pptxgenjs')` directly. Only if that require fails: `npm install pptxgenjs`. The model knows the API; these are the footguns:
+
+- **Set `pres.layout` before adding slides.** The default canvas is `LAYOUT_16x9` = **10" × 5.625"**, not 13.3" wide. Coordinates past the edge are written, not clamped — the shape just isn't on the slide. (`LAYOUT_WIDE` is 13.3" × 7.5".)
+- **Hex colors: never `#`, never 8 digits.** `color: "FF0000"`. Both `"#FF0000"` and alpha baked into the hex (`"00000020"`) **corrupt the file**. For translucency: `transparency: 0-100` on fills and images, `opacity: 0.0-1.0` on shadows — each is silently ignored on the other.
+- **pptxgenjs mutates option objects in place** (converts values to EMU on first use). Never share one `shadow`/options object across two `add*` calls — build a fresh object each time.
+- **Shadow `offset` must be ≥ 0** — a negative offset corrupts the file. To cast a shadow upward, use `angle: 270` with a positive offset.
+- **`letterSpacing` is silently ignored** — the real option is `charSpacing`.
+- **Lists:** `bullet: true` on each item, never a literal `•` (renders double bullets). Set `breakLine: true` on every array item except the last. Space bulleted paragraphs with `paraSpaceAfter`, not `lineSpacing` (huge gaps).
+- **One `new pptxgen()` per output file** — never reuse an instance.
+- **`rectRadius` only works on `ROUNDED_RECTANGLE`**, not `RECTANGLE`.
+- **Gradient fills aren't supported** — use a gradient image as the background instead.
+- **Text boxes have built-in internal padding** — set `margin: 0` whenever text must align with a shape, line, or icon at the same x.
+- **Speaker notes go in `slide.addNotes("...")`** (plain text, once per slide), never in a text box on the slide.
+- **Keep charts native.** Use `addChart()` for everything PowerPoint can chart (pass an array of `{type, data, options}` for combos). For PowerPoint-native features the library doesn't expose (trendlines, error bars), compute the extra series yourself or post-process the generated OOXML — do not fall back to a rendered image. Only chart types PowerPoint has no native form for (Sankey, network, chord) go in as images.
+- **Default charts render bare** — no title, no data labels, dated palette. Set `showTitle` + `title`, `showValue: true` + `dataLabelPosition`, `chartColors: [...]` from your palette, and quiet the frame (`catAxisLabelColor`/`valAxisLabelColor`, `valGridLine: { color, size }`, `catGridLine: { style: "none" }`, `showLegend: false` for a single series).
+- **On a stacked bar or column chart, `dataLabelPosition` must be `ctr`, `inEnd`, or `inBase`.** `outEnd` **corrupts the file**.
+- **A combo series using `secondaryValAxis`/`secondaryCatAxis` needs both `valAxes` and `catAxes` on the chart options, two entries each.** Without them pptxgenjs writes axis *ids* it never declares, and PowerPoint **discards that chart** and reports the file as corrupt. Supplying only `valAxes` is not enough.
+- **After `writeFile()`, run `python scripts/office/validate.py deck.pptx`.** It reports the two chart faults above and the slide-XML defects PowerPoint refuses, and names the fix for each. Fix them in your generator, not by hand-editing the packed XML.
+- **Never reorder the children of `<p:presentation>`.** pptxgenjs writes `<p:notesMasterIdLst>` right after `<p:sldIdLst>` and points both masters at one theme part. PowerPoint reads that happily — move the element and the same deck becomes unopenable.
+- **Icons:** render `react-icons` to SVG (`ReactDOMServer.renderToStaticMarkup`), rasterize with `sharp` at ≥256px, and insert via `addImage({ data: "image/png;base64," + buf.toString("base64") })` — the `image/png;base64,` prefix is required (`react-icons`, `react`, `react-dom`, and `sharp` are preinstalled — `npm install react-icons react react-dom sharp` only if a require fails).
+
+## Editing existing decks and templates
+
+Pick layouts first: `python scripts/thumbnail.py template.pptx template-thumbs` writes a labeled grid of every slide and prints the file(s) it created — `template-thumbs.jpg`, split into `template-thumbs-N.jpg` past 12 slides. **Always pass that second argument, named after the deck.** It defaults to `thumbnails`, so two decks thumbnailed in one directory silently overwrite each other's grids — the first deck's are simply gone (template analysis only — visual QA needs the full-resolution renders from [Converting to Images](#converting-to-images); it only accepts `.pptx`, so copy a `.potx` to a `.pptx` name first). Use it with `markitdown` to map each content section onto a template slide, and vary the layouts — don't put every section on the same title-and-bullets slide.
+
+```bash
+python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
+python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # duplicate a slide (or slideLayoutN.xml); prints the new slide's path
+# reorder / delete slides = edit <p:sldIdLst> in ppt/presentation.xml
+python scripts/clean.py unpacked/                                     # after deletions: removes orphaned slides, media, rels
+# edit slide content in ppt/slides/slideN.xml
+(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)           # zip from INSIDE the dir; rm first or deleted parts survive
+python scripts/office/validate.py out.pptx --original deck.pptx
+```
+
+- **Do all structural work — add, delete, reorder — before editing any slide's content.** `add_slide.py` copies a slide file verbatim, so duplicating after you edit clones the edited content; and `clean.py` deletes any slide missing from `<p:sldIdLst>`, including one you just wrote.
+- **Never copy a slide file by hand** — `add_slide.py` does every registration a new slide needs and reports what it made (`Created ppt/slides/slide17.xml from slide2.xml`). It also works directly on a file: `add_slide.py deck.pptx slide2.xml -o out.pptx` — **pass `-o`, or it rewrites the input deck in place.** A duplicated slide still *references* its source's chart/SmartArt/embedded-object parts rather than cloning them, so editing one slide's chart changes the other's.
+- **If you use `python-pptx`**, three things it won't do: duplicate a slide (its only entry point is `add_slide(layout)`), preserve formatting through `text_frame.text = "..."` (that collapses the paragraph to a single unstyled run — assign `run.text` instead), or read the SVG/EMF most template art uses (`add_picture` raises `UnidentifiedImageError`).
+- Legacy `.ppt` must be converted first: `python scripts/office/soffice.py --headless --convert-to pptx file.ppt`. `.potx` templates unpack and pack identically — keep the `.potx` extension on the output.
+- To reuse a template icon or image, duplicate a slide or layout that already contains it.
+
+When filling in a template:
+
+- If you script an XML transform, parse with `defusedxml.minidom` — round-tripping OOXML through `xml.etree.ElementTree` rewrites namespace prefixes and corrupts the deck.
+- **Template slots ≠ source items.** If the template shows 4 team members and you have 3, delete the 4th member's entire group (image + text boxes), not just its text — then check for orphaned visuals in QA.
+- One `<a:p>` per list item — never concatenate items into a single paragraph. Copy the sibling `<a:pPr>` to preserve spacing, and put `b="1"` on the `<a:rPr>` of titles, section headers, and inline labels (`Status:`, `Owner:`).
+- Let bullets inherit from the layout; only add `<a:buChar>`, `<a:buAutoNum>` (numbered), or `<a:buNone>` to override — never a literal `•` in the text.
+- Text with leading or trailing spaces needs `xml:space="preserve"` on its `<a:t>`.
+
+## Design Ideas
+
+**Don't create boring slides.** Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.
+
+### Before Starting
+
+- **Pick a bold, content-informed color palette**: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
+- **Dominance over equality**: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
+- **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
+- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles. Carry it across every slide. **Do not use a color bar or accent stripe as your motif** (see Avoid list).
+
+### Color Palettes
+
+Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:
+
+| Theme | Primary | Secondary | Accent |
+|-------|---------|-----------|--------|
+| **Midnight Executive** | `1E2761` (navy) | `CADCFC` (ice blue) | `FFFFFF` (white) |
+| **Forest & Moss** | `2C5F2D` (forest) | `97BC62` (moss) | `F5F5F5` (cream) |
+| **Coral Energy** | `F96167` (coral) | `F9E795` (gold) | `2F3C7E` (navy) |
+| **Warm Terracotta** | `B85042` (terracotta) | `E7E8D1` (sand) | `A7BEAE` (sage) |
+| **Ocean Gradient** | `065A82` (deep blue) | `1C7293` (teal) | `21295C` (midnight) |
+| **Charcoal Minimal** | `36454F` (charcoal) | `F2F2F2` (off-white) | `212121` (black) |
+| **Teal Trust** | `028090` (teal) | `00A896` (seafoam) | `02C39A` (mint) |
+| **Berry & Cream** | `6D2E46` (berry) | `A26769` (dusty rose) | `ECE2D0` (cream) |
+| **Sage Calm** | `84B59F` (sage) | `69A297` (eucalyptus) | `50808E` (slate) |
+| **Cherry Bold** | `990011` (cherry) | `FCF6F5` (off-white) | `2F3C7E` (navy) |
+
+### For Each Slide
+
+**Every slide needs a visual element** — image, chart, icon, or shape. Text-only slides are forgettable.
+
+**Layout options:**
+- Two-column (text left, illustration on right)
+- Icon + text rows (icon in colored circle, bold header, description below)
+- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
+- Half-bleed image (full left or right side) with content overlay
+
+**Data display:**
+- Large stat callouts (big numbers 60-72pt with small labels below)
+- Comparison columns (before/after, pros/cons, side-by-side options)
+- Timeline or process flow (numbered steps, arrows)
+
+**Visual polish:**
+- Icons in small colored circles next to section headers
+- Italic accent text for key stats or taglines
+
+### Typography
+
+**Font names you write into the .pptx are rendered by the user's PowerPoint, not by this environment.** Your visual QA renders via LibreOffice, which substitutes fonts it doesn't have — and for some fonts the substitute has different widths, so your QA preview can show text overflow (or fit) that the real deck won't have. To keep your QA trustworthy:
+
+- **Safe fonts** (render true-to-width in QA *and* ship with Office): **Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook**. Use these for body text and anything where fit matters.
+- **Headers with personality at zero QA risk**: pair a safe-list serif header (Cambria, Bookman Old Style, Century Schoolbook) with a safe-list sans body (Calibri or Arial). You get visual contrast without giving up reliable overflow checks.
+- **If the user asks for a font outside the safe list** (e.g. Georgia or Trebuchet MS): use it where the user asked, but size those containers with extra slack (~10%) and don't trust QA text-fit on those elements — the preview of that font is approximate. If the user hasn't specified, prefer safe-list fonts for body text.
+- **QA-unreliable fonts** (substitute has different widths — overflow checks can be wrong): Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype. Calibri Light substitution varies by environment; treat as QA-unreliable. Fine for titles/accents with slack; don't trust QA text-fit on these.
+- **Never default to Aptos** — Office's post-2023 default has no metric-compatible substitute here *and* is missing from older Office installs, so it's unreliable on both ends.
+
+| Element | Size |
+|---------|------|
+| Slide title | 36-44pt bold |
+| Section header | 20-24pt bold |
+| Body text | 14-16pt |
+| Captions | 10-12pt muted |
+
+### Spacing
+
+- 0.5" minimum margins
+- 0.3-0.5" between content blocks
+- Leave breathing room—don't fill every inch
+
+### Avoid (Common Mistakes)
+
+- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
+- **Don't center body text** — left-align paragraphs and lists; center only titles
+- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
+- **Don't default to blue** — pick colors that reflect the specific topic
+- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
+- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
+- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
+- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
+- **Don't use low-contrast elements** — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds
+- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
+- **NEVER add decorative color bars or accent stripes** — this includes: header/footer bars spanning the slide width, vertical sidebar stripes down one edge of the slide, thin accent stripes along one edge of a card or content block, and "single-side borders" on rectangles. These read as AI-generated filler. If you want to set a card apart, use a subtle background tint, a drop shadow, or an icon — not an edge stripe.
+- **Don't default to cream/beige backgrounds** — when no background is specified, use white (`FFFFFF`) or the user's brand palette; avoid warm-neutral defaults like `F5F5DC`, `FAF0E6`, `FAEBD7`, `FFF8E1`
+- **Don't ship text that overflows its shape** — if text doesn't fit, reduce font size, split across slides, or enlarge the container; never leave content cut off or spilling past bounds
+
+## QA (Required)
+
+Your first render usually has a few real issues — overlaps, overflow, misalignment. Find and fix those, re-render only the slides you changed, and stop.
+
+### Content QA
+
+```bash
+markitdown output.pptx
+```
+
+Check for missing content, typos, wrong order.
+
+**When using templates, check for leftover placeholder text:**
+
+```bash
+markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"
+```
+
+If grep returns results, fix them before declaring success.
+
+### File QA (required)
+
+```bash
+python scripts/office/validate.py output.pptx                      # built from scratch
+python scripts/office/validate.py output.pptx --original src.pptx  # built from a template
+```
+
+**If the deck came from a template, always pass `--original`.** A template may itself
+contain parts the XSD rejects, so a bare run can report failures you never caused — and
+a genuine regression can hide among them. `--original` baselines
+the schema and slide checks against the template, suppressing errors it already had.
+The structural checks — relationships, content types, charts — ignore `--original` and
+report template-inherited problems either way, so read those on their own merits.
+
+pptxgenjs emits chart XML PowerPoint refuses to open, and every other tool
+accepts: python-pptx opens those decks, LibreOffice renders them, the XSD
+passes them. Every failure names its fix. Fix it in the generator and rebuild.
+
+### Visual QA
+
+Convert the slides to images (see [Converting to Images](#converting-to-images)) and inspect every one. After staring at the generating code you tend to see what you expect rather than what rendered, so look at the images fresh (a subagent works well for this if you have one). User-visible defects to look for:
+
+- **Text overflow or text cut off at a box or slide boundary — check this first.** It is the most common defect and always user-visible. (For a font the previewer renders unreliably per Typography, the preview is approximate: trust the ~10% slack you left, not its apparent fit.)
+- Overlapping elements (text through shapes, lines through words, stacked elements)
+- Source citations or footers colliding with content above
+- Elements too close (< 0.3" gaps) or cards/sections nearly touching
+- Uneven gaps (large empty area in one place, cramped in another)
+- Insufficient margin from slide edges (< 0.5")
+- Columns or similar elements not aligned consistently
+- Low-contrast text (e.g., light gray text on cream-colored background)
+- Template decoration mispositioned after text replacement — e.g., a title underline positioned for one line, but the replaced title wrapped to two
+- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)
+- Text boxes too narrow causing excessive wrapping
+- Leftover placeholder content
+
+## Converting to Images
+
+Convert presentations to individual slide images for visual inspection:
+
+```bash
+python scripts/office/soffice.py --headless --convert-to pdf output.pptx
+rm -f slide-*.jpg
+pdftoppm -jpeg -r 150 output.pdf slide
+ls -1 "$PWD"/slide-*.jpg
+```
+
+**Pass the absolute paths printed above directly to the view tool.** The `rm` clears stale images from prior runs. `pdftoppm` zero-pads based on page count: `slide-1.jpg` for decks under 10 pages, `slide-01.jpg` for 10-99, `slide-001.jpg` for 100+.
+
+**After fixes, rerun all four commands above** — the PDF must be regenerated from the edited `.pptx` before `pdftoppm` can reflect your changes.
+
+## Dependencies
+
+`pptxgenjs` (npm, preinstalled — install only if `require('pptxgenjs')` fails) · `markitdown[pptx]`, `Pillow`, `defusedxml`, `lxml` (pip — text dump, thumbnail, clean, validate) · LibreOffice (`soffice`, auto-configured for sandboxed environments via `scripts/office/soffice.py`) · `pdftoppm` (Poppler)

package/skills/pptx/scripts/add_slide.py

@@ -0,0 +1,367 @@
+"""Add a slide to a PPTX: duplicate an existing slide or instantiate a layout.
+
+Does all of the package bookkeeping, so the deck stays valid:
+  - writes the new ppt/slides/slideN.xml (and its .rels, minus any
+    notesSlide reference, so the source's speaker notes aren't shared)
+  - registers it in [Content_Types].xml
+  - adds a slide relationship with a fresh rId to presentation.xml.rels
+  - inserts <p:sldId id="..." r:id="..."/> with a fresh id into
+    <p:sldIdLst> — at the end, or after --after SLIDE
+
+Works on an unpacked directory (during an editing session) or directly on a
+.pptx/.potx file (extracted to a temp dir, then rezipped atomically; the
+temp dir is discarded, so unpack the output if you still need to edit the
+new slide's content).
+
+Usage:
+    python add_slide.py unpacked/ slide2.xml                 # duplicate slide2
+    python add_slide.py unpacked/ slideLayout3.xml           # new slide from a layout
+    python add_slide.py unpacked/ slide2.xml --after slide2.xml
+    python add_slide.py deck.pptx slide2.xml                 # rewrite deck.pptx in place
+    python add_slide.py deck.pptx slide2.xml -o out.pptx
+
+A duplicated slide still holds the source's content: edit ppt/slides/slideN.xml
+(printed on success) to change it. To list layouts: ls <dir>/ppt/slideLayouts/
+"""
+
+import argparse
+import re
+import shutil
+import sys
+from typing import NoReturn
+import tempfile
+import zipfile
+from pathlib import Path
+
+from office.helpers import rezip, safe_extract
+
+MINIMAL_SLIDE_XML = '''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">
+  <p:cSld>
+    <p:spTree>
+      <p:nvGrpSpPr>
+        <p:cNvPr id="1" name=""/>
+        <p:cNvGrpSpPr/>
+        <p:nvPr/>
+      </p:nvGrpSpPr>
+      <p:grpSpPr>
+        <a:xfrm>
+          <a:off x="0" y="0"/>
+          <a:ext cx="0" cy="0"/>
+          <a:chOff x="0" y="0"/>
+          <a:chExt cx="0" cy="0"/>
+        </a:xfrm>
+      </p:grpSpPr>
+    </p:spTree>
+  </p:cSld>
+  <p:clrMapOvr>
+    <a:masterClrMapping/>
+  </p:clrMapOvr>
+</p:sld>'''
+
+SHARED_PART_TYPES = ("chart", "diagramData", "oleObject", "package")
+
+NOTES_SLIDE_TYPE_RE = re.compile(r"""Type=["'][^"']*/relationships/notesSlide["']""")
+RELATIONSHIP_RE = re.compile(r"<Relationship\b[^>]*?(?:/>|>.*?</Relationship\s*>)", re.DOTALL)
+
+SLIDE_ID_MIN = 256
+SLIDE_ID_MAX = 2147483647
+
+
+def _die(msg: str) -> NoReturn:
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def get_next_slide_number(slides_dir: Path) -> int:
+    existing = [int(m.group(1)) for f in slides_dir.glob("slide*.xml")
+                if (m := re.match(r"slide(\d+)\.xml", f.name))]
+    return max(existing) + 1 if existing else 1
+
+
+def parse_source(source: str) -> tuple[str, str | None]:
+    if source.startswith("slideLayout") and source.endswith(".xml"):
+        return ("layout", source)
+
+    return ("slide", None)
+
+
+def create_slide_from_layout(unpacked_dir: Path, layout_file: str, after: str | None = None) -> str:
+    slides_dir = unpacked_dir / "ppt" / "slides"
+    rels_dir = slides_dir / "_rels"
+    layout_path = unpacked_dir / "ppt" / "slideLayouts" / layout_file
+
+    if not layout_path.exists():
+        _die(f"{layout_path} not found")
+
+    next_num = get_next_slide_number(slides_dir)
+    dest = f"slide{next_num}.xml"
+    after_rid = _precheck_registration(unpacked_dir, after, dest)
+    slides_dir.mkdir(parents=True, exist_ok=True)
+
+    (slides_dir / dest).write_text(MINIMAL_SLIDE_XML, encoding="utf-8")
+
+    rels_dir.mkdir(exist_ok=True)
+    rels_xml = f'''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/{layout_file}"/>
+</Relationships>'''
+    (rels_dir / f"{dest}.rels").write_text(rels_xml, encoding="utf-8")
+
+    _register_slide(unpacked_dir, dest, layout_file, after_rid)
+    return dest
+
+
+def duplicate_slide(unpacked_dir: Path, source: str, after: str | None = None) -> str:
+    slides_dir = unpacked_dir / "ppt" / "slides"
+    rels_dir = slides_dir / "_rels"
+    source_slide = slides_dir / source
+
+    if not source_slide.exists():
+        _die(f"{source_slide} not found")
+
+    next_num = get_next_slide_number(slides_dir)
+    dest = f"slide{next_num}.xml"
+    after_rid = _precheck_registration(unpacked_dir, after, dest)
+
+    shutil.copy2(source_slide, slides_dir / dest)
+
+    source_rels = rels_dir / f"{source}.rels"
+    shared_parts: list[str] = []
+    if source_rels.exists():
+        dest_rels = rels_dir / f"{dest}.rels"
+        shutil.copy2(source_rels, dest_rels)
+        rels_content = dest_rels.read_text(encoding="utf-8")
+        rels_content = RELATIONSHIP_RE.sub(
+            lambda m: "" if NOTES_SLIDE_TYPE_RE.search(m.group(0)) else m.group(0),
+            rels_content,
+        )
+        dest_rels.write_text(rels_content, encoding="utf-8")
+        shared_parts = sorted({
+            t for t in re.findall(r'Type="[^"]*/relationships/(\w+)"', rels_content)
+            if t in SHARED_PART_TYPES
+        })
+
+    _register_slide(unpacked_dir, dest, source, after_rid)
+    if shared_parts:
+        print(
+            f"Note: {dest} shares its {', '.join(shared_parts)} part(s) with {source} "
+            f"(they are referenced, not copied) — editing those parts changes both slides"
+        )
+    return dest
+
+
+def _precheck_registration(unpacked_dir: Path, after: str | None, dest: str) -> str | None:
+    pres_path = unpacked_dir / "ppt" / "presentation.xml"
+    if not pres_path.exists():
+        _die(f"{pres_path} not found — is this an unpacked PPTX?")
+    xml = pres_path.read_text(encoding="utf-8")
+
+    has_slot = (
+        "</p:sldIdLst>" in xml
+        or re.search(r"<p:sldIdLst\s*/>", xml)
+        or "</p:sldMasterIdLst>" in xml
+    )
+    if not has_slot:
+        _die("presentation.xml has no <p:sldIdLst> (or <p:sldMasterIdLst> to anchor a new one)")
+
+    stale = []
+    content_types = unpacked_dir / "[Content_Types].xml"
+    if content_types.exists() and f'PartName="/ppt/slides/{dest}"' in content_types.read_text(encoding="utf-8"):
+        stale.append("[Content_Types].xml")
+    pres_rels = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
+    if pres_rels.exists() and _find_slide_relationship(
+        pres_rels.read_text(encoding="utf-8"), dest
+    ):
+        stale.append("presentation.xml.rels")
+    if stale:
+        _die(
+            f"{dest} is still registered in {' and '.join(stale)} but absent from ppt/slides/ — "
+            f"run clean.py first"
+        )
+
+    if not after:
+        return None
+    after_rid = _rid_for_slide(unpacked_dir, after)
+    if not re.search(rf'<p:sldId\b[^>]*r:id="{re.escape(after_rid)}"[^>]*>', xml):
+        _die(f"{after} ({after_rid}) is not listed in <p:sldIdLst>")
+    return after_rid
+
+
+def _register_slide(unpacked_dir: Path, dest: str, source_desc: str, after_rid: str | None) -> None:
+    _add_to_content_types(unpacked_dir, dest)
+    rid = _add_to_presentation_rels(unpacked_dir, dest)
+    slide_id = _get_next_slide_id(unpacked_dir)
+    pos, total = _insert_into_sld_id_lst(unpacked_dir, slide_id, rid, after_rid)
+
+    print(f"Created ppt/slides/{dest} from {source_desc}")
+    print(
+        f'Inserted <p:sldId id="{slide_id}" r:id="{rid}"/> into <p:sldIdLst> '
+        f"at position {pos} of {total}"
+    )
+
+
+def _add_to_content_types(unpacked_dir: Path, dest: str) -> None:
+    content_types_path = unpacked_dir / "[Content_Types].xml"
+    content_types = content_types_path.read_text(encoding="utf-8")
+
+    new_override = f'<Override PartName="/ppt/slides/{dest}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>'
+
+    if f'PartName="/ppt/slides/{dest}"' not in content_types:
+        content_types = content_types.replace("</Types>", f"  {new_override}\n</Types>")
+        content_types_path.write_text(content_types, encoding="utf-8")
+
+
+def _add_to_presentation_rels(unpacked_dir: Path, dest: str) -> str:
+    pres_rels_path = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
+    pres_rels = pres_rels_path.read_text(encoding="utf-8")
+
+    existing = _find_slide_relationship(pres_rels, dest)
+    if existing:
+        return existing
+
+    pres_xml = (unpacked_dir / "ppt" / "presentation.xml").read_text(encoding="utf-8")
+    used = {int(n) for n in re.findall(r'\bId="rId(\d+)"', pres_rels)}
+    used |= {int(n) for n in re.findall(r'\br:id="rId(\d+)"', pres_xml)}
+    rid = f"rId{max(used) + 1 if used else 1}"
+
+    new_rel = f'<Relationship Id="{rid}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="slides/{dest}"/>'
+    pres_rels = pres_rels.replace("</Relationships>", f"  {new_rel}\n</Relationships>")
+    pres_rels_path.write_text(pres_rels, encoding="utf-8")
+
+    return rid
+
+
+def _find_slide_relationship(pres_rels: str, slide_name: str) -> str | None:
+    for m in re.finditer(r"<Relationship\b[^>]*>", pres_rels):
+        element = m.group(0)
+        if re.search(rf'Target="(?:/ppt/)?slides/{re.escape(slide_name)}"', element):
+            id_match = re.search(r'\bId="([^"]+)"', element)
+            if id_match:
+                return id_match.group(1)
+    return None
+
+
+def _get_next_slide_id(unpacked_dir: Path) -> int:
+    pres_content = (unpacked_dir / "ppt" / "presentation.xml").read_text(encoding="utf-8")
+    used = {int(m) for m in re.findall(r'<p:sldId[^>]*\bid="(\d+)"', pres_content)}
+
+    candidate = max((i for i in used if i >= SLIDE_ID_MIN), default=SLIDE_ID_MIN - 1) + 1
+    if candidate <= SLIDE_ID_MAX and candidate not in used:
+        return candidate
+    for i in range(SLIDE_ID_MIN, SLIDE_ID_MAX + 1):
+        if i not in used:
+            return i
+    _die("no slide id available in [256, 2147483647] — the deck is full")
+
+
+def _insert_into_sld_id_lst(
+    unpacked_dir: Path, slide_id: int, rid: str, after_rid: str | None = None
+) -> tuple[int, int]:
+    pres_path = unpacked_dir / "ppt" / "presentation.xml"
+    xml = pres_path.read_text(encoding="utf-8")
+    entry = f'<p:sldId id="{slide_id}" r:id="{rid}"/>'
+
+    if f'r:id="{rid}"' in xml:
+        _die(f"presentation.xml already references {rid}; refusing to add a duplicate")
+
+    if after_rid:
+        open_tag = re.search(rf'<p:sldId\b[^>]*r:id="{re.escape(after_rid)}"[^>]*>', xml)
+        if not open_tag:
+            _die(f"{after_rid} is not listed in <p:sldIdLst>")
+        end = open_tag.end()
+        if not open_tag.group(0).endswith("/>"):
+            close = xml.find("</p:sldId>", end)
+            if close == -1:
+                _die(f"unclosed <p:sldId> for {after_rid} in presentation.xml")
+            end = close + len("</p:sldId>")
+        xml = xml[:end] + entry + xml[end:]
+    elif "</p:sldIdLst>" in xml:
+        xml = xml.replace("</p:sldIdLst>", f"{entry}</p:sldIdLst>", 1)
+    elif re.search(r"<p:sldIdLst\s*/>", xml):
+        xml = re.sub(r"<p:sldIdLst\s*/>", f"<p:sldIdLst>{entry}</p:sldIdLst>", xml, count=1)
+    elif "</p:sldMasterIdLst>" in xml:
+        xml = xml.replace(
+            "</p:sldMasterIdLst>", f"</p:sldMasterIdLst><p:sldIdLst>{entry}</p:sldIdLst>", 1
+        )
+    else:
+        _die("presentation.xml has no <p:sldIdLst> (or <p:sldMasterIdLst> to anchor a new one)")
+
+    pres_path.write_text(xml, encoding="utf-8")
+
+    lst = re.search(r"<p:sldIdLst>(.*)</p:sldIdLst>", xml, re.DOTALL)
+    entries = re.findall(r"<p:sldId\b[^>]*>", lst.group(1)) if lst else []
+    position = next(
+        (i for i, e in enumerate(entries, 1) if f'r:id="{rid}"' in e), len(entries)
+    )
+    return position, len(entries)
+
+
+def _rid_for_slide(unpacked_dir: Path, slide_name: str) -> str:
+    pres_rels_path = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
+    rid = _find_slide_relationship(pres_rels_path.read_text(encoding="utf-8"), slide_name)
+    if not rid:
+        _die(f"{slide_name} has no relationship in presentation.xml.rels")
+    return rid
+
+
+def add_slide(unpacked_dir: Path, source: str, after: str | None = None) -> str:
+    source_type, layout_file = parse_source(source)
+    if source_type == "layout" and layout_file is not None:
+        return create_slide_from_layout(unpacked_dir, layout_file, after)
+    return duplicate_slide(unpacked_dir, source, after)
+
+
+def add_slide_to_package(
+    package: Path, source: str, after: str | None = None, output: Path | None = None
+) -> str:
+    out = output or package
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        with zipfile.ZipFile(package) as zf:
+            safe_extract(zf, tmp_path)
+        dest = add_slide(tmp_path, source, after)
+        rezip(tmp_path, out)
+    print(f"Wrote {out} — the new slide is ppt/slides/{dest} inside it (unpack to edit its content)")
+    return dest
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Add a slide to a PPTX: duplicate a slide or instantiate a layout. "
+        "Registers content types, relationships, and <p:sldIdLst>."
+    )
+    parser.add_argument("target", help="Unpacked PPTX directory OR a .pptx/.potx file")
+    parser.add_argument(
+        "source",
+        help="slideN.xml to duplicate, or slideLayoutN.xml to create from a layout "
+        "(list layouts with: ls <dir>/ppt/slideLayouts/)",
+    )
+    parser.add_argument(
+        "--after",
+        metavar="SLIDE",
+        help="insert after this slide, e.g. slide2.xml (default: append at the end)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="output file (only with a .pptx/.potx target; default: rewrite the input in place)",
+    )
+    args = parser.parse_args()
+
+    target = Path(args.target)
+    if target.is_dir():
+        if args.output:
+            parser.error("--output is only valid for .pptx/.potx input; a directory is modified in place")
+        add_slide(target, args.source, args.after)
+    elif target.is_file() and target.suffix.lower() in (".pptx", ".potx"):
+        try:
+            add_slide_to_package(target, args.source, args.after, Path(args.output) if args.output else None)
+        except (OSError, ValueError, zipfile.BadZipFile) as e:
+            _die(str(e))
+    else:
+        _die(f"{target} is neither a directory nor a .pptx/.potx file")
+
+
+if __name__ == "__main__":
+    main()