Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs: surface page transitions and per-element animations

hugohe3ae380b97eb4f
diff --git a/README.md b/README.md
index f0379be7..90863c36 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ English | [中文](./README_CN.md)
Drop in a PDF, DOCX, URL, or Markdown — get back a **natively editable PowerPoint** with real shapes, real text boxes, and real charts. Not images. Click anything and edit it.
+> **Animations** — exported decks support **page transitions** and **per-element entrance animations** as real OOXML, not embedded video. Click-by-click cascade in PowerPoint and Keynote, no extra tooling. See [Animations & Transitions →](./docs/animations.md).
+
> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.
>
> **What you'll do**: install Python, install an AI IDE, drop in your material.
@@ -236,6 +238,7 @@ Multiple backends are supported across Core / Extended / Experimental tiers. Run
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules |
| 🎨 | [Create a Custom Template](./skills/ppt-master/workflows/create-template.md) | Standalone workflow for building your own brand or industry template |
| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
+| 🎬 | [Animations & Transitions](./docs/animations.md) | Page transitions and per-element entrance animations |
| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |
| 💼 | [Examples](./examples/README.md) | 22 projects, 309 pages |
| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |
diff --git a/README_CN.md b/README_CN.md
index 91ecad9c..9d348da0 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -38,6 +38,8 @@
丢进一份 PDF、DOCX、网址或 Markdown,拿回一份**原生可编辑的 PowerPoint**——真正的形状、真正的文本框、真正的图表,不是图片。点击任何元素即可编辑。
+> **动画** —— 导出的 deck 支持**页间转场**和**页内元素入场动画**,输出为真正的 OOXML 动画(不是嵌入视频),在 PowerPoint 和 Keynote 中按点击逐次播放,无需额外工具。详见 [转场与动画使用指南 →](./docs/zh/animations.md)。
+
> **运作方式** —— PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot / Codebuddy 等)里运行的工作流(一个 "skill")。你在 IDE 的对话框里跟 AI 说"用这份 PDF 做一份 PPT",AI 按这套工作流在你本机生成一个真正可编辑的 `.pptx`。你不写任何代码——IDE 只是你和 AI 对话的地方。
>
> **你要做的**:装 Python、装一个 AI IDE、把资料放进来。
@@ -240,6 +242,7 @@ OPENAI_MODEL=gpt-image-2
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 |
| 🎨 | [创建自定义模板](./skills/ppt-master/workflows/create-template.md) | 独立工作流,构建你自己的品牌或行业模板 |
| 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 |
+| 🎬 | [转场与动画](./docs/zh/animations.md) | 页间转场和页内元素入场动画 |
| 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 |
| 💼 | [示例](./examples/README.md) | 22 个项目,309 页 |
| 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG |
diff --git a/docs/animations.md b/docs/animations.md
new file mode 100644
index 00000000..4f66ff7b
--- /dev/null
+++ b/docs/animations.md
@@ -0,0 +1,94 @@
+# Page Transitions & Per-Element Animations
+
+PPT Master's exported PPTX supports **page transitions** (slide-to-slide) and **per-element entrance animations** (within a slide). Both are controlled by `svg_to_pptx.py` CLI flags and ship as real OOXML — they animate inside PowerPoint and Keynote, no embedded video.
+
+## Defaults
+
+| Layer | Default | Why |
+|---|---|---|
+| Page transition | `fade`, 0.4s | Calm baseline that suits most decks |
+| Per-element animation | off | Existing users see no behavior change |
+
+To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` (or `svg_final/`) — no need to rerun the LLM.
+
+## Page Transitions
+
+```bash
+# Pick a different effect
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6
+
+# Disable
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none
+
+# Auto-advance every 5 seconds (kiosk-style playback)
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
+```
+
+Available effects: `fade`, `push`, `wipe`, `split`, `strips`, `cover`, `random`.
+
+Flags:
+
+- `-t/--transition` — effect name, or `none` to disable. Default: `fade`.
+- `--transition-duration` — seconds, default `0.4`.
+- `--auto-advance` — seconds; omit for presenter-controlled advance.
+
+## Per-Element Animations
+
+Off by default. When enabled, entering a slide → first click reveals the first semantic group; each subsequent click reveals the next group in z-order.
+
+```bash
+# Cascade every group with fade (recommended starting point)
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade
+
+# Auto-vary effects within a slide (title fades; later groups cycle a curated pool)
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed
+
+# Slow each reveal down to 0.5s
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade --animation-duration 0.5
+```
+
+22 single effects: `appear`, `fade`, `fly`, `cut`, `zoom`, `wipe`, `split`, `blinds`, `checkerboard`, `dissolve`, `random_bars`, `peek`, `wheel`, `box`, `circle`, `diamond`, `plus`, `strips`, `wedge`, `stretch`, `expand`, `swivel`. Plus two auto-vary modes:
+
+- `mixed` — deterministic. The first animated group on each slide uses `fade`; later groups cycle through a curated visible-effect pool across the deck.
+- `random` — samples from the same pool.
+
+The pool excludes `appear` because it has no visible motion.
+
+Flags:
+
+- `-a/--animation` — effect name, `mixed`, `random`, or `none`. Default: `none`.
+- `--animation-duration` — per-element seconds, default `0.3`.
+- `--animation-stagger` — kept for backward compatibility; ignored by click-by-click timing.
+
+## Anchor Logic — Top-Level `<g id="...">`
+
+Per-element animations are anchored on **top-level `<g id="...">` groups** in the SVG (e.g. `<g id="cover-title">`, `<g id="card-1">`). One group = one click reveal.
+
+Aim for **3–8 semantic groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation.
+
+**Fallback for flat SVGs** (no top-level `<g>` wrappers, only raw `<rect>` / `<text>` / `<path>` at the root):
+
+- ≤ 8 visible top-level primitives → each becomes one anchor (capped to avoid 70+ atom cascades on dense pages).
+- > 8 → animation is skipped on that slide. The slide still renders, just without entrance animation.
+
+Executors should wrap logical sections in `<g id>` regardless of whether you plan to animate. The Executor reference (`skills/ppt-master/references/shared-standards.md`) requires it.
+
+## Limitations
+
+- **Native shapes mode only.** Per-element animation needs editable shape anchors. `--only legacy` produces one image per slide and has no element granularity to animate; that mode is unaffected by `-a/--animation` and only honors `-t/--transition`.
+- **Office version drift on element animations.** Effects use the `<p:animEffect filter=...>` path (vs. `presetID` lookup tables) to stay stable across Office versions. Most filters render identically in PowerPoint 2016+; older Office may downgrade some filters to plain Appear.
+- **PNG fallback (compat mode) is for visual rendering only.** Transitions and animations live in the slide XML, not in the PNG, so disabling compat mode does not affect either layer.
+
+## Quick Reference
+
+| Goal | Command |
+|---|---|
+| Disable transitions | `-t none` |
+| Change transition effect | `-t push` (or any from the list above) |
+| Slower transition | `--transition-duration 0.8` |
+| Auto-play | `--auto-advance 5` |
+| Enable element animation | `--animation fade` |
+| Auto-vary element animation | `--animation mixed` |
+| Slower per-element reveal | `--animation-duration 0.5` |
+
+See also: [`scripts/docs/svg-pipeline.md`](../skills/ppt-master/scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference.
diff --git a/docs/faq.md b/docs/faq.md
index c09349d1..f680cc50 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -56,46 +56,16 @@ If your workflow specifically requires Excel-driven data editing, manually creat
## Q: Can I change page transitions and element animations?
-Yes. The exported PPTX supports both **page transitions** and **per-element entrance animations**, controlled via `svg_to_pptx.py` CLI flags.
-
-**Page transitions** (on by default, 0.4s `fade`)
-
-```bash
-# Pick a different effect: fade / push / wipe / split / strips / cover / random
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6
-
-# Disable transitions
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none
-
-# Auto-advance every 5 seconds
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
-```
-
-**Per-element animations** (off by default — existing users see no behavior change)
-
-Enter a slide → click once → semantic groups cascade in by z-order. To enable:
+Yes. Page transitions (`fade` 0.4s by default) and per-element entrance animations (off by default) are both controlled by `svg_to_pptx.py` flags — `-t/--transition` for page-level and `-a/--animation` for element-level. Common one-liners:
```bash
-# Cascade every element with fade (recommended starting point)
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade
-
-# Auto-vary visible effects within a slide (title fades; content cycles through a curated pool)
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed
-
-# Slower pace: 0.5s per click-revealed element
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade \
- --animation-duration 0.5 --animation-stagger 0.2
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # disable transitions
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade # enable per-element
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed # auto-vary effects
```
-22 single effects: `appear / fade / fly / cut / zoom / wipe / split / blinds / checkerboard / dissolve / random_bars / peek / wheel / box / circle / diamond / plus / strips / wedge / stretch / expand / swivel`, plus `mixed` and `random` auto-vary modes.
-
-`mixed` is deterministic: the first animated group on each slide uses `fade`, then later groups cycle through a curated visible-effect pool across the whole deck. `random` samples from the same visible-effect pool. The pool excludes `appear` because it is too subtle for presenter-controlled reveals.
-
-`--animation-stagger` is kept for backward compatibility but is ignored by click-by-click timing. Use `--animation-duration` to control how obvious each reveal feels.
-
-**Anchor logic**: animations are anchored on top-level SVG `<g id="...">` groups (e.g. `<g id="cover-title">`, `<g id="card-1">`) — this is the cleanest cascade granularity. Aim for 3–8 semantic groups per slide. Slides whose root is flat `<rect>` / `<text>` / `<path>` (no top-level `<g>` wrappers) **fall back automatically**: if there are ≤8 top-level visible elements, each becomes one animation anchor; beyond 8, animation is skipped on that slide. So Executors should wrap logical sections in `<g id>` regardless of animation, since it also improves PowerPoint's group-select / group-move ergonomics.
-
-**Note**: per-element animations only apply in native shapes mode (the default); `--only legacy` produces one image per slide and has no element anchors to animate.
+Full effect list, anchor logic (top-level `<g id="...">`), fallback behavior, and limitations: see [Animations & Transitions](./animations.md).
## Q: Which AI model works best?
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
new file mode 100644
index 00000000..a75866b9
--- /dev/null
+++ b/docs/zh/animations.md
@@ -0,0 +1,94 @@
+# 页间转场与页内元素动画
+
+PPT Master 导出的 PPTX 同时支持**页间转场**(page transition)与**页内元素入场动画**(per-element entrance animation)。两者都通过 `svg_to_pptx.py` 的 CLI 参数控制,输出为真正的 OOXML 动画——在 PowerPoint 和 Keynote 中原生播放,不是嵌入视频。
+
+## 默认行为
+
+| 层级 | 默认 | 原因 |
+|---|---|---|
+| 页间转场 | `fade`,0.4 秒 | 适合大多数 deck 的中性基线 |
+| 页内元素动画 | 关闭 | 老用户更新后行为不变 |
+
+修改设置只需对同一份 `svg_output/`(或 `svg_final/`)重跑 `svg_to_pptx.py`,无需重新跑 LLM。
+
+## 页间转场
+
+```bash
+# 换效果
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6
+
+# 关闭转场
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none
+
+# 每 5 秒自动翻页(展厅 / 自动循环)
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
+```
+
+可选效果:`fade`、`push`、`wipe`、`split`、`strips`、`cover`、`random`。
+
+参数:
+
+- `-t/--transition` — 效果名,或 `none` 禁用。默认 `fade`。
+- `--transition-duration` — 秒数,默认 `0.4`。
+- `--auto-advance` — 秒数;不写则由演示者手动翻页。
+
+## 页内元素动画
+
+默认关闭。开启后:进入页面 → 第一次点击显示第一个语义组,后续每次点击按 z-order 显示下一个组。
+
+```bash
+# 全部用 fade 入场(推荐起点)
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade
+
+# 同页自动轮换效果(首组 fade,后续组在精选效果池中轮换)
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed
+
+# 让每次入场放慢到 0.5 秒
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade --animation-duration 0.5
+```
+
+22 种单一效果:`appear`、`fade`、`fly`、`cut`、`zoom`、`wipe`、`split`、`blinds`、`checkerboard`、`dissolve`、`random_bars`、`peek`、`wheel`、`box`、`circle`、`diamond`、`plus`、`strips`、`wedge`、`stretch`、`expand`、`swivel`。再加两种自动轮换模式:
+
+- `mixed` — 确定性轮换。每页第一个动画组使用 `fade`,后续组在整份 deck 范围内按精选效果池连续轮换。
+- `random` — 在同一效果池中随机抽取。
+
+效果池排除了 `appear`,因为它没有可见动画过程。
+
+参数:
+
+- `-a/--animation` — 效果名、`mixed`、`random` 或 `none`。默认 `none`。
+- `--animation-duration` — 单个元素入场秒数,默认 `0.3`。
+- `--animation-stagger` — 仅保留兼容旧命令;当前逐次点击入场逻辑会忽略它。
+
+## 锚点机制 — 顶层 `<g id="...">`
+
+页内动画锚定在 SVG 的**顶层 `<g id="...">` 组**上(如 `<g id="cover-title">`、`<g id="card-1">`),一个组对应一次点击入场。
+
+每页建议 **3–8 个语义组**。这同时也是 PowerPoint 框选 / 整体移动的颗粒度,与是否启用动画无关,都能改善编辑体验。
+
+**扁平 SVG 的回退逻辑**(顶层没有 `<g>`,只有裸 `<rect>` / `<text>` / `<path>`):
+
+- 顶层可见图元 ≤ 8 → 每个图元作为一个锚点(设上限以避免密集页面出现 70+ 次点击)。
+- 顶层可见图元 > 8 → 该页跳过页内动画。页面照常显示,只是不带入场。
+
+无论是否打算开启动画,Executor 都应该把逻辑分块包进 `<g id>`。`skills/ppt-master/references/shared-standards.md` 已将这一点列为强制要求。
+
+## 限制
+
+- **仅原生形状模式生效。** 页内动画需要可编辑形状作为锚点。`--only legacy` 模式每页一张大图,没有元素粒度,因此不响应 `-a/--animation`,只受 `-t/--transition` 影响。
+- **不同 Office 版本对元素动画存在轻微差异。** 实现走 `<p:animEffect filter=...>` 路径(而非 `presetID` 查找表),在 PowerPoint 2016+ 上表现一致;更老的 Office 可能把部分效果降级为 Appear。
+- **兼容模式的 PNG fallback 只用于显示。** 转场与动画都在 slide XML 里,不在 PNG 中;关掉兼容模式不影响两个动画层。
+
+## 常用速查
+
+| 目标 | 命令 |
+|---|---|
+| 关闭转场 | `-t none` |
+| 切换转场效果 | `-t push`(或上文列表中任一) |
+| 转场放慢 | `--transition-duration 0.8` |
+| 自动播放 | `--auto-advance 5` |
+| 启用元素动画 | `--animation fade` |
+| 元素动画自动轮换 | `--animation mixed` |
+| 元素入场放慢 | `--animation-duration 0.5` |
+
+完整 `svg_to_pptx.py` 参考:[`scripts/docs/svg-pipeline.md`](../../skills/ppt-master/scripts/docs/svg-pipeline.md)。
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 20809fbd..2d393f1f 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -56,46 +56,16 @@ PPT Master 本身免费开源,唯一的成本来自你自己的 AI 模型用
## Q: 页面切换和元素动画可以调吗?
-可以。导出的 PPTX 同时支持**页间转场**和**页内元素入场动画**,都通过 `svg_to_pptx.py` 的 CLI 参数控制。
-
-**页间转场**(默认开启 0.4s `fade`)
-
-```bash
-# 换效果:fade / push / wipe / split / strips / cover / random
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6
-
-# 关闭转场
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none
-
-# 自动定时翻页(每 5 秒)
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
-```
-
-**页内动画**(默认关闭 —— 老用户更新后行为不变)
-
-进入新页 → 单击一次 → 各语义组按 z-order 依次入场。开启方式:
+可以。页间转场(默认 `fade` 0.4s)和页内元素入场动画(默认关闭)都通过 `svg_to_pptx.py` 的参数控制——`-t/--transition` 控制页级,`-a/--animation` 控制元素级。常用一行命令:
```bash
-# 全部元素淡入级联(推荐起步)
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade
-
-# 同页内自动混搭明显可见的效果(标题 fade,内容按精选池轮换)
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed
-
-# 调慢节奏:每次点击出现的元素入场 0.5s
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade \
- --animation-duration 0.5 --animation-stagger 0.2
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # 关闭转场
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade # 开启页内动画
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed # 自动混搭效果
```
-22 种单效果可选:`appear / fade / fly / cut / zoom / wipe / split / blinds / checkerboard / dissolve / random_bars / peek / wheel / box / circle / diamond / plus / strips / wedge / stretch / expand / swivel`,外加 `mixed`、`random` 两种自动混搭模式。
-
-`mixed` 是确定性轮换:每页第一个动画组使用 `fade`,后续组按精选的明显效果池在整份 deck 内连续轮换。`random` 从同一个明显效果池中随机抽取。效果池会排除 `appear`,因为它对演示点击入场来说太不明显。
-
-`--animation-stagger` 仅保留作兼容旧命令,当前逐次点击入场逻辑会忽略它。需要让动画更明显时,使用 `--animation-duration` 调整每个入场效果的持续时间。
-
-**锚点逻辑**:动画以 SVG 顶层 `<g id="语义名">` 分组为单位(如 `<g id="cover-title">`、`<g id="card-1">`),这是最干净的级联粒度。建议每页控制在 3–8 个语义组。如果某页根节点是平铺的 `<rect>`/`<text>`/`<path>`(没有顶层 `<g>` 包裹),导出器会**自动降级**:当顶层可见元素 ≤8 个时,每个元素作为一个动画锚点;超过 8 个则跳过该页动画。所以 Executor 输出应该把逻辑组都用 `<g id>` 包起来,既利于动画,也利于 PowerPoint 里成组选择/移动。
-
-**注意**:页内动画只在 native shapes 模式(默认)生效,`--only legacy` 整页一张图无可锚定元素。
+完整效果列表、`<g id="...">` 锚点机制、降级行为、限制:见 [转场与动画](./animations.md)。
## Q: 推荐用什么 AI 模型?
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index d5e07b82..c2a5d4b1 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -305,9 +305,16 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final
# backup/<timestamp>/svg_output/ ← Executor SVG source backup
```
+**Optional animation flags** (add to the command above when the user asks for them; otherwise omit):
+- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`.
+- `-a <effect>` — per-element entrance animation. Default off. Common picks: `fade` (every group fades in by click), `mixed` (auto-vary across the deck). Requires top-level `<g id="...">` groups (already required by Executor).
+- `--auto-advance <seconds>` — kiosk-style auto-play.
+
+Full effect list, anchor logic, and limits: [`docs/animations.md`](../../docs/animations.md).
+
> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps
> ❌ **NEVER** export from `svg_output/` — MUST use `-s final` (exports from `svg_final/`)
-> ❌ **NEVER** add extra flags like `--only`
+> ❌ **NEVER** use `--only` (it suppresses one of the two output files)
---
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index e1d6d4a2..f013c3dd 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -306,10 +306,17 @@ python3 scripts/svg_to_pptx.py <project_path> -s final
# backup/<timestamp>/svg_output/ ← Executor SVG source backup
```
+**Optional animation flags** (only when the user asks):
+- `-t <effect>` — page transition (`fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`; default `fade`)
+- `-a <effect>` — per-element entrance animation (`fade` / `mixed` / `random` / one of 22 named effects; default off). Anchors on top-level `<g id="...">` groups.
+- `--auto-advance <seconds>` — kiosk-style auto-play
+
+Full reference: [`docs/animations.md`](../../../docs/animations.md).
+
**Prohibited**:
- NEVER use `cp` as a substitute for `finalize_svg.py`
- NEVER export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)
-- NEVER add extra flags like `--only`
+- NEVER use `--only` (it suppresses one of the two output files)
**Re-run rule**: Any change to `svg_output/` after post-processing requires re-running Steps 2-3. Step 1 only re-runs if `notes/total.md` changed.