rsc-universal 0.1.1

package/skills/presentations/references/markdown-decks.md

@@ -0,0 +1,290 @@
+# Markdown Decks — Marp & Slidev, Themed from Design Tokens, Exported to PDF + PPTX
+
+The design-led pipeline. Author the deck in Markdown, theme it with CSS driven by the project's design
+tokens, export to **PDF (the hero)** and **PPTX (bonus, image-based)**. Two engines:
+
+- **Marp** — simplest, most portable; one CSS theme; great default for most decks. Exports HTML/PDF/PPTX/PNG.
+- **Slidev** — Vue-based, developer-grade; live code, Monaco, Mermaid, components, motion. Best for technical talks.
+
+Pick Marp unless the deck needs live code / interactive components / Mermaid diagrams → then Slidev.
+Both flatten to **images** on PPTX export — if the user needs *editable* PPTX text, use `pptx-python.md`.
+
+> Versions verified 2026-06: `@marp-team/marp-cli` (Node 18+), `@slidev/cli` (Vue 3). Always confirm in the
+> target project: `npx @marp-team/marp-cli@latest --version`, `npx slidev --version`. Pin versions in `package.json`.
+
+---
+
+## Marp
+
+### Authoring
+
+A Marp deck is one Markdown file. Front-matter sets directives; `---` separates slides.
+
+```markdown
+---
+marp: true
+theme: brand
+paginate: true
+size: 16:9
+math: katex
+---
+
+<!-- _class: title -->
+
+# Onboarding v2 cut churn 40%
+## How we rebuilt the first-run experience
+
+---
+
+## TAM is $12B, growing 24%/yr
+
+- Bottom-up: 40k target accounts × $30k ACV
+- Reachable today via existing channel partners
+
+<!-- Speaker note: this is the slide investors lean in for. Walk the assumptions, don't read them. -->
+
+---
+
+<!-- _class: lead -->
+
+# One in three users never finished setup.
+```
+
+Key directives: `theme`, `paginate`, `size: 16:9`, `math`, `header`/`footer`, `backgroundImage`. Per-slide
+overrides use HTML comments: `<!-- _class: title -->` (leading `_` = this slide only), `<!-- _backgroundColor:
+... -->`. Speaker notes are any `<!-- comment -->` not starting with a directive; they export with `--pdf-notes`
+and `--notes`, and into PPTX notes.
+
+### Theme from design tokens (the part that makes it *flipa*)
+
+Read the project's tokens from `02-DOCS/wiki/stack/design.md` / `design-tokens.json` (the `design` skill's
+output: OKLCH palette, type pairing, type scale, spacing). A Marp theme is a CSS file with a `/* @theme name */`
+banner; register it with `--theme ./theme.css` (or `--theme-set ./themes`). Map tokens → CSS custom properties
+once, then style sections against the variables — never hand-pick hex per slide.
+
+```css
+/* @theme brand */
+/* Marp theme generated from 02-DOCS/wiki/stack/design.md tokens. */
+@import 'default'; /* inherit Marp's reset/layout, then override */
+
+/* Web fonts: self-host or @import so they EMBED in the PDF (see exports). */
+@import url('https://fonts.googleapis.com/css2?family=Fraunces:wght@600;700&family=Inter:wght@400;500;600&display=swap');
+
+:root {
+  /* --- design tokens (OKLCH from the design skill) --- */
+  --brand:      oklch(0.62 0.19 264);
+  --brand-ink:  oklch(0.18 0.03 264);
+  --surface:    oklch(0.98 0.005 264);
+  --muted:      oklch(0.55 0.02 264);
+  --accent:     oklch(0.74 0.17 52);
+
+  /* --- type scale for PROJECTION (bigger than web; body >= 24pt-equiv) --- */
+  --font-display: 'Fraunces', Georgia, serif;
+  --font-body:    'Inter', system-ui, sans-serif;
+  --step-display: 64px;
+  --step-h1:      44px;
+  --step-h2:      32px;
+  --step-body:    26px;   /* legibility floor for a talk */
+  --step-caption: 18px;
+
+  /* --- spacing scale --- */
+  --space-slide: 64px;    /* slide safe-area padding */
+  --space-gap:   24px;
+}
+
+section {                 /* a Marp slide */
+  background: var(--surface);
+  color: var(--brand-ink);
+  font-family: var(--font-body);
+  font-size: var(--step-body);
+  line-height: 1.4;
+  padding: var(--space-slide);
+}
+h1 { font-family: var(--font-display); font-size: var(--step-h1); color: var(--brand-ink); }
+h2 { font-family: var(--font-display); font-size: var(--step-h2); color: var(--brand); }
+strong { color: var(--accent); }
+section::after { color: var(--muted); font-size: var(--step-caption); } /* pagination */
+
+/* Title slide: <!-- _class: title --> */
+section.title { background: var(--brand-ink); color: var(--surface); justify-content: center; }
+section.title h1 { font-size: var(--step-display); color: var(--surface); }
+section.title h2 { color: var(--accent); }
+
+/* Big statement slide: <!-- _class: lead --> */
+section.lead { justify-content: center; text-align: center; }
+section.lead h1 { font-size: var(--step-display); max-width: 22ch; }
+
+/* Dark variant for dark rooms / big screens: <!-- _class: dark --> */
+section.dark { background: var(--brand-ink); color: var(--surface); }
+section.dark h2 { color: var(--accent); }
+```
+
+For a **dark deck** default, swap the `section` background/color and provide a light `.handout` class for the
+printed leave-behind. Keep contrast ≥ 4.5:1 in both. Two-column layouts: use a small utility, e.g.
+`section.split { display: grid; grid-template-columns: 1fr 1fr; gap: var(--space-gap); }` and a `<!-- _class:
+split -->` plus raw HTML columns, or Marp's CSS-grid recipes.
+
+### Export — Marp
+
+```bash
+# PDF — the hero. Vector text, fonts embedded (if @imported/installed). 16:9 from `size:`.
+npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pdf
+
+# PDF with clickable outline (from headings) + presenter notes attached
+npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pdf --pdf-outlines --pdf-notes
+
+# PPTX — one IMAGE per slide (text NOT selectable). Speaker notes carry over.
+npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pptx
+
+# PPTX, experimental editable mode — needs LibreOffice (`soffice`) on PATH
+npx @marp-team/marp-cli@latest deck.md --pptx --pptx-editable
+
+# Speaker notes as a text file
+npx @marp-team/marp-cli@latest deck.md --notes notes.txt
+
+# PNG/JPEG of each slide (thumbnails, social) — also --images png|jpeg
+npx @marp-team/marp-cli@latest deck.md --images png
+
+# Self-contained HTML (no server) for browser presenting
+npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --html -o deck.html
+```
+
+PDF/PPTX/image export drive a **Chromium-family browser** (Chrome/Edge, or Firefox) under the hood — install
+one or set `CHROME_PATH`. CI without a browser → use the official `marpteam/marp-cli` Docker image. Allow remote
+CSS/fonts with `--allow-local-files` for local assets. A `marp.config.js` / `marp.config.mjs` can fix
+`theme`/`pdf`/`html` so you don't repeat flags.
+
+---
+
+## Slidev
+
+For developer-grade / technical talks: live-editable code blocks, Monaco editor, Mermaid/PlantUML diagrams,
+Vue components on slides, click-driven `v-click` builds, and animation via `@vueuse/motion`.
+
+### Scaffold & author
+
+```bash
+npm init slidev@latest        # scaffolds slides.md + Vite project
+cd <project>
+npx slidev                    # dev server at http://localhost:3030 (live reload)
+```
+
+`slides.md` — front-matter headmatter + `---` between slides; per-slide front-matter blocks set `layout`,
+`class`, `background`, `transition`:
+
+````markdown
+---
+theme: ./theme            # local theme, or an npm theme like 'seriph'
+title: Onboarding v2
+transition: fade
+fonts:
+  sans: Inter
+  serif: Fraunces
+---
+
+# Onboarding v2 cut churn 40%
+
+How we rebuilt the first-run experience
+
+---
+layout: two-cols
+class: text-2xl
+---
+
+## What changed
+
+- Single-screen setup
+- Defaults that work
+
+::right::
+
+```ts {2|4|all}
+// builds revealed click-by-click with v-click ranges
+const churn = before * 0.6   // -40%
+```
+
+<!--
+Speaker note: this exports to PDF presenter notes and PPTX notes.
+-->
+````
+
+Builds: wrap content in `<v-click>` or use `{2|4|all}` line-highlight ranges in code blocks — reveal one idea at
+a time (restraint!). Diagrams: ` ```mermaid ` fences render natively.
+
+### Theme from design tokens — Slidev
+
+Slidev styles with **UnoCSS/Tailwind utilities + CSS**. Drive it from the same design tokens. Put global CSS in
+`./style.css` (auto-imported) or a local theme folder:
+
+```css
+/* style.css — Slidev global, from 02-DOCS/wiki/stack/design.md tokens */
+:root {
+  --brand:     oklch(0.62 0.19 264);
+  --brand-ink: oklch(0.18 0.03 264);
+  --surface:   oklch(0.98 0.005 264);
+  --accent:    oklch(0.74 0.17 52);
+}
+.slidev-layout            { background: var(--surface); color: var(--brand-ink); font-family: Inter, sans-serif; }
+.slidev-layout h1         { font-family: Fraunces, serif; color: var(--brand-ink); font-size: 2.75rem; }
+.slidev-layout h2         { color: var(--brand); }
+.slidev-layout strong     { color: var(--accent); }
+.slidev-layout.cover      { background: var(--brand-ink); color: var(--surface); }
+```
+
+Expose tokens to Tailwind/UnoCSS via `uno.config.ts` `theme.colors` so utility classes (`text-brand`, `bg-ink`)
+map to the same OKLCH values — single source of truth. Layouts (`cover`, `center`, `two-cols`, `image-right`,
+`fact`, `quote`, `section`) cover most slide types; build custom ones in `layouts/`.
+
+### Export — Slidev
+
+Export uses **Playwright-Chromium** rendering — install it once in the project.
+
+```bash
+npx playwright install chromium          # one-time (or: npm i -D playwright-chromium)
+npx slidev export                        # PDF (default), vector where possible, notes included
+npx slidev export --format pptx          # PPTX — image-per-slide; notes per slide carry over
+npx slidev export --format png           # one PNG per slide
+npx slidev export --with-clicks          # one page per CLICK step (every build state)
+npx slidev export --dark                 # force dark theme on export
+npx slidev export --output deck.pdf      # explicit output path
+npx slidev build                         # static SPA (deploy the deck as a website)
+```
+
+Like Marp, Slidev **PPTX = images, not editable text** — notes do carry over. Slidev's PDF keeps text selectable
+for HTML-rendered text (better than image-PPTX) but complex components may rasterize.
+
+---
+
+## Export gotchas (both engines, and the fallback)
+
+- **Fonts must embed in the PDF.** Self-host or `@import` web fonts so the renderer has them at export time; otherwise the PDF falls back to system fonts on other machines and the type drifts. Verify with `pdffonts deck.pdf` — every font should show `emb yes`. Subset fonts to shrink the file.
+- **PPTX from Marp/Slidev is image-based** — text is not selectable/editable, search/accessibility suffer, and file size balloons with full-bleed images. If the user must edit text in PowerPoint, switch to `pptx-python.md`. Use Marp's experimental `--pptx-editable` (needs `soffice`) only as a best-effort.
+- **16:9** — set `size: 16:9` (Marp) / default aspect (Slidev). Don't let a 4:3 default ship.
+- **File size** — compress images before embedding (`sips`/`squoosh`/`pngquant`); prefer SVG for logos/diagrams; subset fonts. A 100MB deck won't email.
+- **Browser dependency** — PDF/PPTX/PNG export needs Chromium (Marp) / Playwright-Chromium (Slidev). On headless CI install it explicitly or use the Marp Docker image; otherwise export silently skips.
+- **Local assets** — Marp needs `--allow-local-files` to embed local images into PDF/PPTX.
+- **Reduced motion** — HTML/presenting mode should honor `prefers-reduced-motion`; transitions are for the live talk, irrelevant in the static PDF.
+
+### Fallback: any HTML deck → PDF (decktape / Playwright)
+
+For reveal.js or a hand-rolled HTML deck with no native exporter:
+
+```bash
+# decktape drives a headless browser across the deck and writes a vector-ish PDF
+npx decktape reveal http://localhost:8000 deck.pdf
+npx decktape generic --slides 20 http://localhost:8000 deck.pdf   # generic mode for custom decks
+
+# Or a minimal Playwright print-to-PDF
+npx playwright pdf http://localhost:8000 deck.pdf
+```
+
+## When to choose which engine
+
+| Need | Engine |
+| --- | --- |
+| Fastest path, max portability, one CSS theme | **Marp** |
+| Mostly text/charts/images, PDF is the deliverable | **Marp** |
+| Live code, Monaco, line-highlight builds, Mermaid | **Slidev** |
+| Vue components / interactive widgets on slides | **Slidev** |
+| Deploy the deck as a website too | **Slidev** (`slidev build`) |
+| Recipient must EDIT the slides in PowerPoint | neither → `pptx-python.md` |

package/skills/presentations/references/pptx-python.md

@@ -0,0 +1,242 @@
+# Native Editable PPTX — python-pptx Recipes
+
+The editable pipeline. Use **python-pptx** when the deliverable is a `.pptx` that non-technical people will
+open and edit in PowerPoint, Keynote, or Google Slides — or when you need **native, editable charts** that live
+inside the file. python-pptx is pure Python: it writes Office Open XML directly, **no PowerPoint/LibreOffice
+required to build** (only to render to PDF afterward).
+
+> Version verified 2026-06: `python-pptx` current major `1.x` (e.g. `1.0.x`). Confirm in the target env:
+> `python -c "import pptx; print(pptx.__version__)"`. Install: `pip install python-pptx`.
+
+## Mental model
+
+- A `Presentation` has `slide_masters` → each master has `slide_layouts` → each `slide` is *built from* a layout.
+- A layout's **placeholders** (title, body, picture, etc.) are the editable scaffolding PowerPoint users expect. **Add content via placeholders/layouts**, not only free-floating textboxes, so the result behaves like a "real" template deck (outline view, reflow, theme-aware).
+- **Theme** (colors + fonts) lives on the master. python-pptx can set per-shape colors and fonts directly, and can start from a corporate template (`.potx`/`.pptx`) to inherit a real theme.
+- EMU is the internal unit. Always use helpers: `Inches`, `Pt`, `Emu`. 16:9 at 13.333"×7.5".
+
+## Skeleton: a themed deck from design tokens
+
+Map the project's design tokens (`02-DOCS/wiki/stack/design.md`) into PPTX theme values. PPTX is **sRGB**, so
+convert OKLCH tokens to hex first (the `design` skill's `design-tokens.json` should carry sRGB/hex fallbacks;
+if only OKLCH exists, convert via the design pipeline — do not eyeball it).
+
+```python
+"""build_deck.py — native editable 16:9 deck from design tokens.
+
+Run: python build_deck.py  (writes deck.pptx; no Office needed)
+"""
+from pptx import Presentation
+from pptx.util import Inches, Pt, Emu
+from pptx.dml.color import RGBColor
+from pptx.enum.text import PP_ALIGN, MSO_ANCHOR
+
+# --- design tokens -> sRGB hex (from 02-DOCS/wiki/stack/design.md) ----------
+BRAND      = RGBColor(0x4F, 0x46, 0xE5)   # oklch(0.62 0.19 264) -> #4F46E5
+BRAND_INK  = RGBColor(0x1E, 0x1B, 0x2E)
+SURFACE    = RGBColor(0xFA, 0xFA, 0xFC)
+ACCENT     = RGBColor(0xF5, 0x9E, 0x0B)
+MUTED      = RGBColor(0x6B, 0x70, 0x80)
+FONT_DISPLAY = "Fraunces"
+FONT_BODY    = "Inter"
+
+# --- 16:9 canvas ------------------------------------------------------------
+prs = Presentation()
+prs.slide_width  = Inches(13.333)
+prs.slide_height = Inches(7.5)
+
+EMU_W, EMU_H = prs.slide_width, prs.slide_height
+MARGIN = Inches(0.9)   # safe-area; nothing important outside this
+
+def fill(slide, color):
+    """Solid background fill for a slide."""
+    bg = slide.background
+    bg.fill.solid()
+    bg.fill.fore_color.rgb = color
+
+def textbox(slide, left, top, width, height, anchor=MSO_ANCHOR.TOP):
+    tb = slide.shapes.add_textbox(left, top, width, height)
+    tf = tb.text_frame
+    tf.word_wrap = True
+    tf.vertical_anchor = anchor
+    return tf
+
+def run(paragraph, text, size, color, font=FONT_BODY, bold=False, align=PP_ALIGN.LEFT):
+    paragraph.alignment = align
+    r = paragraph.add_run(); r.text = text
+    f = r.font
+    f.size = Pt(size); f.bold = bold; f.name = font
+    f.color.rgb = color
+    return r
+
+BLANK = prs.slide_layouts[6]   # 6 = blank layout in the default template
+
+# --- Title slide ------------------------------------------------------------
+s = prs.slides.add_slide(BLANK)
+fill(s, BRAND_INK)
+tf = textbox(s, MARGIN, Inches(2.6), EMU_W - 2*MARGIN, Inches(2.4))
+run(tf.paragraphs[0], "Onboarding v2 cut churn 40%", 54, SURFACE, FONT_DISPLAY, bold=True)
+p = tf.add_paragraph()
+run(p, "How we rebuilt the first-run experience", 26, ACCENT, FONT_BODY)
+
+# --- Assertion-headline content slide ---------------------------------------
+s = prs.slides.add_slide(BLANK)
+fill(s, SURFACE)
+tf = textbox(s, MARGIN, MARGIN, EMU_W - 2*MARGIN, Inches(1.4))
+run(tf.paragraphs[0], "TAM is $12B, growing 24%/yr", 38, BRAND_INK, FONT_DISPLAY, bold=True)
+body = textbox(s, MARGIN, Inches(2.6), EMU_W - 2*MARGIN, Inches(3.5))
+for i, line in enumerate([
+    "Bottom-up: 40k target accounts x $30k ACV",
+    "Reachable today via existing channel partners",
+]):
+    p = body.paragraphs[0] if i == 0 else body.add_paragraph()
+    run(p, "•  " + line, 26, BRAND_INK)
+    p.space_after = Pt(12)
+
+# Speaker notes (native, editable pane)
+s.notes_slide.notes_text_frame.text = (
+    "This is the slide investors lean in for. Walk the assumptions, don't read them."
+)
+
+prs.save("deck.pptx")
+print("wrote deck.pptx")
+```
+
+## Native, editable charts (the python-pptx superpower)
+
+Unlike Marp/Slidev (which flatten charts to images), python-pptx writes **live PowerPoint charts** the user can
+restyle and re-data. One chart = one point named in the slide headline (see `slide-design.md`).
+
+```python
+from pptx.chart.data import CategoryChartData
+from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION, XL_TICK_MARK
+
+s = prs.slides.add_slide(BLANK); fill(s, SURFACE)
+tf = textbox(s, MARGIN, MARGIN, EMU_W - 2*MARGIN, Inches(1.2))
+run(tf.paragraphs[0], "Revenue 3x'd in four quarters", 38, BRAND_INK, FONT_DISPLAY, bold=True)
+
+data = CategoryChartData()
+data.categories = ["Q1", "Q2", "Q3", "Q4"]
+data.add_series("ARR ($k)", (220, 360, 540, 680))
+
+gframe = s.shapes.add_chart(
+    XL_CHART_TYPE.COLUMN_CLUSTERED,
+    MARGIN, Inches(2.4), EMU_W - 2*MARGIN, Inches(4.2), data,
+)
+chart = gframe.chart
+chart.has_legend = False           # one series -> no legend needed
+chart.has_title = False            # the SLIDE headline is the title
+
+# De-clutter + brand the plot
+plot = chart.plots[0]
+plot.gap_width = 60
+series = plot.series[0]
+series.format.fill.solid()
+series.format.fill.fore_color.rgb = BRAND   # one brand color, not a rainbow
+# emphasize the final (latest) point in accent — pre-attentive highlight
+series.points[-1].format.fill.solid()
+series.points[-1].format.fill.fore_color.rgb = ACCENT
+
+cat_axis = chart.category_axis
+cat_axis.major_tick_mark = XL_TICK_MARK.NONE
+cat_axis.tick_labels.font.size = Pt(16)
+val_axis = chart.value_axis
+val_axis.has_major_gridlines = False         # remove gridline clutter
+val_axis.tick_labels.font.size = Pt(16)
+val_axis.visible = False                     # direct-label instead if useful
+```
+
+Chart types: `COLUMN_CLUSTERED`, `BAR_CLUSTERED`, `LINE`, `LINE_MARKERS`, `PIE`, `DOUGHNUT`, `XY_SCATTER`,
+`AREA`. Avoid `*_3D` types (banned by the design rules). Add a data point's value as a label via
+`plot.has_data_labels = True` and `plot.data_labels.number_format = '$#,##0'`.
+
+## Tables (native, editable)
+
+```python
+rows, cols = 4, 3
+gframe = s.shapes.add_table(rows, cols, MARGIN, Inches(2.4),
+                            EMU_W - 2*MARGIN, Inches(3.5))
+table = gframe.table
+headers = ["Plan", "Price", "Seats"]
+for c, h in enumerate(headers):
+    cell = table.cell(0, c)
+    cell.text = h
+    cell.fill.solid(); cell.fill.fore_color.rgb = BRAND
+    para = cell.text_frame.paragraphs[0]
+    para.runs[0].font.color.rgb = SURFACE
+    para.runs[0].font.bold = True
+    para.runs[0].font.size = Pt(20)
+# ... fill body rows; set cell.text and per-run font for each
+table.columns[0].width = Inches(5.0)
+```
+
+## Images (full-bleed + safe sizing)
+
+```python
+# Full-bleed background image, then a scrim + text on top (see slide-design.md)
+pic = s.shapes.add_picture("hero.jpg", 0, 0, width=EMU_W, height=EMU_H)
+s.shapes._spTree.remove(pic._element)        # send to back
+s.shapes._spTree.insert(2, pic._element)
+# scrim rectangle for legibility
+from pptx.enum.shapes import MSO_SHAPE
+scrim = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, 0, 0, EMU_W, EMU_H)
+scrim.fill.solid(); scrim.fill.fore_color.rgb = BRAND_INK
+scrim.fill.transparency = 0  # python-pptx has no direct alpha API; see note
+scrim.line.fill.background()
+```
+
+Note: python-pptx has no first-class alpha/transparency API for fills — for a true semi-transparent scrim,
+either pre-render a translucent PNG and `add_picture` it, or set transparency by editing the shape's XML
+(`fill.fore_color` + an `<a:alpha>` element via `lxml`). Keep image files compressed *before* embedding to
+control file size (PPTX embeds the original bytes).
+
+## Starting from a corporate template (inherit a real theme)
+
+The cleanest way to honor a company's brand is to open their `.potx`/`.pptx` and add slides using **its**
+layouts — you inherit theme colors, fonts, masters, and logos for free.
+
+```python
+prs = Presentation("corporate-template.potx")   # or a .pptx
+# Inspect what layouts exist so you pick the right scaffolding:
+for i, layout in enumerate(prs.slide_layouts):
+    print(i, layout.name)
+title_layout = prs.slide_layouts[0]
+s = prs.slides.add_slide(title_layout)
+s.placeholders[0].text = "Onboarding v2 cut churn 40%"   # title placeholder
+s.placeholders[1].text = "How we rebuilt the first-run experience"  # subtitle
+```
+
+Prefer placeholders here (`s.placeholders[idx].text`) so content lands in the template's themed, reflowing
+slots rather than as off-theme floating boxes. List `slide.placeholders` to discover indices/types.
+
+## Speaker notes
+
+```python
+notes = slide.notes_slide.notes_text_frame
+notes.text = "Talk track for this slide. Exports to the PowerPoint notes pane and notes/handout pages."
+```
+
+## Render to PDF (python-pptx can't; convert)
+
+python-pptx only writes `.pptx`. To get a PDF (vector, fonts embedded), convert with LibreOffice headless or
+open in Office and export:
+
+```bash
+soffice --headless --convert-to pdf --outdir out deck.pptx     # LibreOffice
+# verify fonts embedded:
+pdffonts out/deck.pdf            # every font should read 'emb yes'
+```
+
+If LibreOffice substitutes fonts, install the brand fonts on the converting machine first, or embed fonts in
+the `.pptx` via PowerPoint (File → Options → Save → "Embed fonts in the file") before converting.
+
+## python-pptx gotchas
+
+- **No PDF/render engine** — convert via LibreOffice/Office; verify font embedding afterward (`pdffonts`).
+- **No fill transparency API** — pre-render translucent PNGs or edit XML for scrims/overlays.
+- **EMU everywhere** — always wrap measurements in `Inches`/`Pt`/`Emu`; raw ints are EMU and easy to get wrong.
+- **Fonts** — setting `font.name` references the font by name; the viewing machine must have it (or the deck must embed it). Stick to the brand fonts the design tokens specify; provide a safe fallback.
+- **Default template = 4:3 historically** — always set `slide_width/height` to 13.333"×7.5" for 16:9.
+- **Placeholders vs textboxes** — for a deck people will *edit*, prefer layout placeholders so outline view and reflow work; reserve free textboxes for bespoke layouts.
+- **File size** — PPTX embeds original image bytes; compress images before `add_picture`.
+- **SmartArt / advanced animations** — not supported by python-pptx; build those in PowerPoint, or keep motion to the simple build order you control.