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(workflows): align conditional production contracts

hugohe35589c1b5381b
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index 5dcca381..12f65ad0 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -10,7 +10,7 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](
- One audio file per slide under `<project_path>/audio/`, named to match the SVG (`01_cover.mp3`, `02_market_landscape.mp3`, …).
- With edge, one matching subtitle file per slide under `<project_path>/notes/subtitles/` (`01_cover.srt`, `02_market_landscape.srt`, …). Each file uses a page-local timeline with a `00:00:00,000` origin and edge's word-boundary timing.
-- With an SVG-to-SRT timing plan, a rebuilt `animations.json` whose click-free object animations wait for the relevant subtitle cue, plus a deck-wide `<project_path>/notes/subtitles/total.srt` aligned to the final PPTX timeline. After PowerPoint exports a video, the same command can calibrate the page starts against its audio track for frame-accurate sidecar subtitles.
+- When canonical `animations.json` exists, an SVG-to-SRT timing plan derives `narration_animations.json` whose click-free object animations wait for the relevant subtitle cue. When neither animation sidecar exists, narrated export creates no sidecar and keeps the default `fade` page transition with no per-element builds. Both paths can produce a deck-wide `<project_path>/notes/subtitles/total.srt` aligned to the final PPTX timeline; after PowerPoint exports a video, the same command can calibrate page starts against its audio track for frame-accurate sidecar subtitles.
- Optional re-export: a new PPTX in `exports/` with each `m4a` / `mp3` / `wav` file embedded into the matching slide and slide auto-advance timings set to the audio length, so kiosk/auto-play and video export work without manual timing.
- Optional native video export on Windows: `powerpoint_video.py` delegates the final narrated PPTX to PowerPoint 2016+ and waits until its native MP4 encoder succeeds or fails.
- The original speaker notes are preserved.
@@ -20,7 +20,7 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](
1. **Speaker notes are written as pure spoken narration.** PPT Master's notes spec deliberately produces TTS-friendly prose — no bracketed stage markers, no `Key points:` / `Duration:` meta-lines — so what is read aloud is exactly what's on the page.
2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the selected provider's voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "steady male voice for financial reporting"). It also recommends a speaking rate or provider defaults based on notes density.
3. **One question, one answer.** You are asked once — provider, voice, rate, "embed audio back into PPTX", and "continue to video" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.
-4. **Generation runs.** With edge, the script writes each page's MP3 and SRT from the same stream to `audio/` and `notes/subtitles/`; cloud providers currently write audio only. For Generate PPTX, the AI maps current SVG content groups to numbered SRT cues, rebuilds click-free animations, and re-exports the deck with audio attached. It then merges the local SRT files using timing values read from that final PPTX. When automatic video export was selected and compatible Windows PowerPoint is available, it continues through PowerPoint's native encoder and waits for the MP4 before aligning the delivery SRT. Long-audio import and automatic long-audio splitting are not supported.
+4. **Generation runs.** With edge, the script writes each page's MP3 and SRT from the same stream to `audio/` and `notes/subtitles/`; cloud providers currently write audio only. For Generate PPTX with canonical custom animation, the AI maps current SVG content groups to numbered SRT cues and derives click-free `narration_animations.json`; without animation sidecars, it skips that derivation and retains `fade` / no per-element builds. It then re-exports the deck with audio attached and merges the local SRT files using timing values read from that final PPTX. When automatic video export was selected and compatible Windows PowerPoint is available, it continues through PowerPoint's native encoder and waits for the MP4 before aligning the delivery SRT. Long-audio import and automatic long-audio splitting are not supported.
Subtitles remain external artifacts: PPT Master does not embed them into the PPTX or burn them into the MP4. Automatic video export delegates to installed Windows PowerPoint; it is not a separate renderer.
@@ -43,7 +43,9 @@ You: Generate narration for this deck and re-export with audio embedded.
You: Add Japanese voice narration; pick a calm female voice.
```
-The AI handles the rest.
+The Generate route also runs this stage when Stage 3 resolves effective
+Narration Audio to enabled. A later explicit request still wins over the
+proactive default. The AI handles the rest.
## Languages
@@ -95,13 +97,15 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice-id <cosyvoice-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 3. Print the SRT-set fingerprint, then author
+# 3-4. Only when canonical animations.json exists, print the SRT-set
+# fingerprint, then author
# <project_path>/narration_timing.json by comparing each current
# SVG content group with the numbered cues in that page's SRT. A missing
# cue means the group has no spoken counterpart and uses normal sequencing.
+# When neither animation sidecar exists, skip directly to step 5.
python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>
-# 4. Rebuild click-free object animation timing from the formal SRT
+# 4. Derive click-free narration_animations.json from canonical animations.json
python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
--narration-padding 0.5 --force
@@ -126,6 +130,11 @@ python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
-o exports/<powerpoint_exported_video_stem>.srt --force
```
+Before sending any TTS request, `notes_to_audio.py` verifies that every
+Generate SVG page or Native Enhance slide has a readable, non-empty per-slide
+note. Missing or empty notes return exit code `2`; generate those notes first,
+then rerun audio generation.
+
For edge, `--voice` is required. Use `--list-voices --locale <locale>` to see what's available.
Edge generates up to three slide-level audio/SRT pairs concurrently by default.
Use `--concurrency <N>` to tune it or `--concurrency 1` for serial
@@ -133,7 +142,7 @@ troubleshooting. Cloud providers remain serial.
The edge command creates `audio/<stem>.mp3` and `notes/subtitles/<stem>.srt` from the same streaming request. Sentence-ending punctuation closes a cue. A cue over 20 visible characters first splits at commas, semicolons, or colons, then at the nearest word boundary only if it is still too long. Use `--subtitle-max-chars` to change the limit. Adjacent timing overlap up to 100 ms is tolerated by moving the later cue start to the previous cue end; larger overlap fails. Each SRT uses a page-local timebase with a zero origin and preserves edge's `WordBoundary` timing, including any leading silence before the first cue. The cloud-provider commands currently create audio only.
-`narration_timing.json` is deliberately separate from `animations.json`. It records the ordered SRT-set SHA-256, narration padding, ordered SVG group IDs, and optional 1-based cue numbers. `narration_sync.py animations` rejects a stale fingerprint, validates the group IDs against the current SVGs, and replaces the animation sidecar with only supported PowerPoint fields. `narration_sync.py subtitles` reads the final PPTX's actual presentation order plus millisecond slide-advance and transition values, so `total.srt` follows the native PPTX timeline. A relative `--pptx` path is resolved under `<project_path>`.
+When canonical custom animation exists, `narration_timing.json` remains deliberately separate from read-only `animations.json`. It records the ordered SRT-set SHA-256, narration padding, ordered SVG group IDs, and optional 1-based cue numbers. `narration_sync.py animations` rejects a stale fingerprint, validates the group IDs against the current SVGs, and writes the derived `narration_animations.json` with only supported PowerPoint fields. With no animation sidecars, skip that derivation. `narration_sync.py subtitles` reads the final PPTX's actual presentation order plus millisecond slide-advance and transition values, so `total.srt` follows the native PPTX timeline. A relative `--pptx` path is resolved under `<project_path>`.
PowerPoint's video encoder can quantize each slide/media segment to its output frame clock. Those small per-page differences may accumulate even when the PPTX timing values are correct. Passing the finished `.mp4` / `.wmv` / `.mov` with `--video` uses normalized audio correlation to locate each original page narration in the exported audio track. It changes only the page-level offsets: edge's cue text and page-local `WordBoundary` timing remain untouched. This is a post-export subtitle calibration step and does not rewrite the video.
diff --git a/docs/technical-design.md b/docs/technical-design.md
index fcd209e9..ab4904df 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -66,13 +66,13 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
├── Use P01 as a method sample to classify the complete issue set; fix every blocking error and selected advisory warnings
├── Generate P02 through the final page continuously → svg_output/ (no checker calls in between)
├── [Quality Check] svg_quality_checker.py --stage final --json (mandatory — 0 errors; warnings are non-blocking)
- └── Notes generation: complete speaker notes → notes/total.md
+ └── [Speaker notes, conditional] effective Speaker Notes outcome enabled → complete notes/total.md
↓
[Chart calibration (conditional)] → verify-charts stage (required for decks containing data charts)
↓
[Visual self-check (optional, opt-in)] → visual-review stage (only when the user explicitly requests it)
↓
-[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py (defensive validation, then compilation)
+[Post-processing] → [total_md_split.py when notes are enabled] → finalize_svg.py → svg_to_pptx.py (defensive validation, then compilation; --no-notes when disabled)
↓
Output:
svg_final/
@@ -360,7 +360,11 @@ PPT Master uses **role switching within one main agent** rather than parallel su
**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode: it may not reselect upstream decisions or omit required attributes, but it still owns geometry, composition, hierarchy, and visual treatment inside implementation dimensions the Design Spec leaves open. Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.
-**The Strategist confirmation stage is the main user design-decision gate on the default continuous route.** Strategist uses one dependency-ordered three-stage gate. Stage 1 confirms an open communication contract and canvas. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Stage 2 is authored once from that contract and confirms the complete deck solution: reading mode, narrative mode, page count, coordinated visual system, image sources, and generated-image rendering. When a template is installed, Strategist also derives its page/prototype application plan from the actual workspace and current content and exposes that plan as editable natural-language prose; only the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. Stage 3 is authored once and contains production mechanics only: conditional AI acquisition, formula policy, generation mode, and the Design Spec review toggle. The compatibility key `delivery_purpose` means reading mode. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first persist every final value, including production mechanics, into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.
+**The Strategist confirmation stage is the main user design-decision gate on the default continuous route.** Strategist uses one dependency-ordered three-stage gate. Stage 1 confirms an open communication contract and canvas. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Stage 2 is authored once from that contract and confirms the complete deck solution: reading mode, narrative mode, page count, coordinated visual system, image sources, and generated-image rendering. When a template is installed, Strategist also derives its page/prototype application plan from the actual workspace and current content and exposes that plan as editable natural-language prose; only the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. Stage 3 is authored once and contains production mechanics only: conditional AI acquisition, formula policy, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Those three values are fallback policies, not capability bans: the latest explicit user instruction wins, then Stage 3, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. The compatibility key `delivery_purpose` means reading mode. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.
+
+The three Stage 3 proactive values remain independent raw evidence. In
+particular, enabling narration may enable the effective Speaker Notes outcome
+in the Design Spec, but it never rewrites the raw speaker-notes choice.
**Image analysis is metadata-first, with a narrow Strategist visual fallback.** When images exist, `analyze_images.py` supplies the regenerated measured facts in `analysis/image_analysis.csv`; the CSV is a view over the live `images/` folder, not a durable cache. Strategist first resolves supplied images from source placement and nearby prose, captions / alt text / titles, filenames, user notes, existing resource records, and that metadata. It may inspect one specific image only when a material ambiguity remains about selection, factual identity, page role, crop safety, or focal placement—never as a bulk inventory scan. The answer is written into Design Spec §VIII, after which Executor uses the plan and measured geometry without reopening source pixels for semantic discovery. User images, extracted images, web images, AI outputs, formulas, and sliced elements still converge into the same measured fact table.
diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.md
index ddcfe73d..5fbd7e8e 100644
--- a/docs/zh/audio-narration.md
+++ b/docs/zh/audio-narration.md
@@ -10,7 +10,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg
- 每页一个音频文件,存放于 `<project_path>/audio/`,文件名与 SVG 对齐(`01_cover.mp3`、`02_market_landscape.mp3` …)。
- 使用 Edge 时,每页还有一个同名字幕文件,存放于 `<project_path>/notes/subtitles/`(`01_cover.srt`、`02_market_landscape.srt` …)。每个文件使用以 `00:00:00,000` 为原点的页内时间轴,时间来自 Edge 的词边界。
-- 提供 SVG 到 SRT 的计时计划后,还会重建 `animations.json`:无点击对象动画会等待相关字幕 cue;同时生成与最终 PPTX 时间轴一致的 `<project_path>/notes/subtitles/total.srt`。PowerPoint 导出视频后,还可用同一命令根据视频音轨校准每页起点,得到帧级对齐的外挂字幕。
+- 存在规范的 `animations.json` 时,SVG 到 SRT 的计时计划会派生 `narration_animations.json`,让无点击对象动画等待相关字幕 cue。两个动画 sidecar 都不存在时,旁白导出不会创建 sidecar,而是保留默认 `fade` 页间切换和无逐元素动画。两条路径都可以生成与最终 PPTX 时间轴一致的 `<project_path>/notes/subtitles/total.srt`;PowerPoint 导出视频后,还可用同一命令根据视频音轨校准每页起点,得到帧级对齐的外挂字幕。
- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。
- Windows 下可选原生视频导出:`powerpoint_video.py` 把最终带旁白 PPTX 交给 PowerPoint 2016+,并等待其原生 MP4 编码成功或失败。
- 演讲者备注原样保留。
@@ -20,7 +20,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg
1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。
2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。
3. **一次问完,一次回答**。AI 在一条消息里同时确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频;每项都标推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。
-4. **执行**。使用 Edge 时,脚本从同一次流中把每页 MP3 和 SRT 分别写到 `audio/` 与 `notes/subtitles/`;云端 provider 目前仍只写音频。对于 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,重建无点击动画,再导出带音频的 PPTX;最后从该 PPTX 读回实际计时并合并逐页 SRT。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器,等 MP4 完成后再校准交付字幕。不支持长音频导入或自动拆分。
+4. **执行**。使用 Edge 时,脚本从同一次流中把每页 MP3 和 SRT 分别写到 `audio/` 与 `notes/subtitles/`;云端 provider 目前仍只写音频。对于存在规范自定义动画的 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;没有动画 sidecar 时则跳过派生,保留 `fade` / 无逐元素动画。随后再导出带音频的 PPTX,并从该 PPTX 读回实际计时、合并逐页 SRT。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器,等 MP4 完成后再校准交付字幕。不支持长音频导入或自动拆分。
字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不烧录进 MP4。自动视频导出委托给本机 Windows PowerPoint,并不是另一套渲染器。
@@ -43,7 +43,8 @@ deck 导出后,在聊天里直接说就行:
你: Generate narration for this deck and re-export with audio embedded.
```
-剩下的 AI 全包。
+Generate 路线在 Stage 3 把 Narration Audio 的最终有效结果解析为开启时,
+也会主动运行该阶段;后续明确指令仍优先于主动默认值。剩下的 AI 全包。
## 支持的语言
@@ -95,12 +96,13 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice-id <cosyvoice-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 3. 输出整套 SRT 的指纹,再对照每页当前 SVG 内容组与 SRT cue,编写
+# 3-4. 仅当规范 animations.json 存在时,输出整套 SRT 的指纹,
+# 再对照每页当前 SVG 内容组与 SRT cue,编写
# <project_path>/narration_timing.json;没有对应口播的组不写 cue,
-# 后续按正常动画顺序出现。
+# 后续按正常动画顺序出现。两个动画 sidecar 都不存在时直接跳到第 5 步。
python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>
-# 4. 根据正式 SRT 重建无点击对象动画计时
+# 4. 从规范 animations.json 派生无点击的 narration_animations.json
python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
--narration-padding 0.5 --force
@@ -124,13 +126,17 @@ python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
-o exports/<powerpoint_exported_video_stem>.srt --force
```
+发送任何 TTS 请求前,`notes_to_audio.py` 会确认每个 Generate SVG 页面或
+Native Enhance 页面都有可读且非空的逐页备注。缺失或空备注会返回退出码
+`2`;必须先生成这些备注,再重新运行音频生成。
+
edge 模式下 `--voice` 是必填项,可用 `--list-voices --locale <locale>` 查看音色。
Edge 默认同时生成最多 3 页音频/SRT。可用 `--concurrency <N>` 调整;
排查连接问题时可设为 `--concurrency 1`。云端 provider 仍保持串行。
Edge 命令会从同一次流式请求中生成 `audio/<stem>.mp3` 与 `notes/subtitles/<stem>.srt`。句末标点必定结束一条字幕;单条超过默认 20 个可见字符时,优先在逗号、分号或冒号处拆分,仍然过长才在最近的词边界拆分。可用 `--subtitle-max-chars` 调整上限。相邻字幕最多允许 100 毫秒的计时重叠:后一句起点会移到前一句终点;超过该范围则报错。每页 SRT 使用从零计时的页内时间基准,并保留 Edge `WordBoundary` 的实际时间(包括首条字幕前的静音);云端 provider 命令目前只生成音频。
-`narration_timing.json` 与 `animations.json` 刻意分离:前者记录整套有序 SRT 的 SHA-256、旁白 padding、有序 SVG 组 ID 和可选的 1-based cue 编号。`narration_sync.py animations` 会拒绝过期的 SRT 指纹,用当前 SVG 校验组 ID,并用 PowerPoint 支持的字段完整替换动画 sidecar。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级页面推进与转场时间,因此 `total.srt` 使用原生 PPTX 时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。
+存在规范自定义动画时,`narration_timing.json` 与只读的 `animations.json` 刻意分离:前者记录整套有序 SRT 的 SHA-256、旁白 padding、有序 SVG 组 ID 和可选的 1-based cue 编号。`narration_sync.py animations` 会拒绝过期的 SRT 指纹,用当前 SVG 校验组 ID,并把 PowerPoint 支持的字段写入派生的 `narration_animations.json`。没有动画 sidecar 时跳过该派生步骤。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级页面推进与转场时间,因此 `total.srt` 使用原生 PPTX 时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。
PowerPoint 的视频编码器可能把每个页面 / 媒体段落量化到输出帧时钟;即使 PPTX 计时值正确,这些很小的分页误差仍可能逐页累积。把最终 `.mp4` / `.wmv` / `.mov` 通过 `--video` 传入后,脚本会用归一化音频相关性在视频音轨中定位每页原始旁白。它只改页级偏移,Edge 的字幕文本和页内 `WordBoundary` 时间保持不变;这是视频导出后的字幕校准步骤,不会改写视频。
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index e7ebb088..0674c3ae 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -66,13 +66,13 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
├── 把 P01 作为方法样本分类完整 issue set;消除全部 blocking error,并处理选定的 advisory warning
├── P02 至末页连续生成项目规范化 SVG 页面 → svg_output/(中途不再运行 checker)
├── [Quality Check] svg_quality_checker.py --stage final --json(强制通过,0 错误;warning 非阻塞)
- └── 讲稿生成:完整讲稿 → notes/total.md
+ └── [讲稿,条件触发] Speaker Notes 有效结果为开启 → 完整讲稿 notes/total.md
↓
[图表校准(条件触发)] → verify-charts 工作流(含数据图表的 deck 必须在此步骤校准坐标)
↓
[视觉自检(可选,opt-in)] → visual-review 工作流(仅在用户明确请求时触发)
↓
-[后处理] → total_md_split.py(拆分讲稿)→ finalize_svg.py → svg_to_pptx.py(防御校验后编译)
+[后处理] → [开启讲稿时运行 total_md_split.py] → finalize_svg.py → svg_to_pptx.py(防御校验后编译;关闭时显式 --no-notes)
↓
输出:
svg_final/
@@ -354,7 +354,11 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式:不得重选上游方案或漏掉必需属性,但在 Design Spec 留出的范围内仍拥有几何、构图、层级和视觉处理的实现权。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。
-**策略师确认阶段是默认连续路线中的主要用户设计决策 gate。** Strategist 阶段以一个按依赖排序的三阶段 gate 作为核心决策点。第一阶段确认开放式沟通契约与画布。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。第二阶段只从该契约计算一次并确认完整 PPT 方案:阅读模式、叙事 mode、页数、成套视觉系统、图片来源和生成图渲染。存在模板时,Strategist 还会根据真实工作区和当前内容推导页面/原型应用计划,并以可编辑的自然语言文本展示;只有内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算第二阶段。第三阶段也只计算一次,并且只处理生产机制:条件式 AI 图片获取路径、公式策略、生成模式与 Design Spec 审核开关。JSON 为兼容保留 `delivery_purpose` 键,但用户侧统一称为阅读模式。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都先把全部最终值(含生产机制)固化到同一份 `design_spec.md` 并完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。
+**策略师确认阶段是默认连续路线中的主要用户设计决策 gate。** Strategist 阶段以一个按依赖排序的三阶段 gate 作为核心决策点。第一阶段确认开放式沟通契约与画布。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。第二阶段只从该契约计算一次并确认完整 PPT 方案:阅读模式、叙事 mode、页数、成套视觉系统、图片来源和生成图渲染。存在模板时,Strategist 还会根据真实工作区和当前内容推导页面/原型应用计划,并以可编辑的自然语言文本展示;只有内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算第二阶段。第三阶段也只计算一次,并且只处理生产机制:条件式 AI 图片获取路径、公式策略、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。这三项是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → Stage 3 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。JSON 为兼容保留 `delivery_purpose` 键,但用户侧统一称为阅读模式。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。
+
+Stage 3 的三个主动执行值始终保留为相互独立的原始证据。尤其是,
+启用旁白可以在 Design Spec 中启用 Speaker Notes 的最终有效结果,
+但绝不会改写原始的备注选择。
**图片分析以重算元数据为先,Strategist 只保留小范围视觉兜底。** 当项目里存在图片时,`analyze_images.py` 把可度量事实重算到 `analysis/image_analysis.csv`;该 CSV 是实时 `images/` 目录的派生视图,不是持久缓存。Strategist 先根据图片在源文中的位置与前后文、图注 / alt / 标题、文件名、用户说明、已有资源记录和这些元数据判断。只有当某一张具体图片在选用、事实身份、页面角色、裁剪安全或焦点放置上仍有实质歧义时,才可单独查看它,绝不得扫描整个图片目录。结论写入 Design Spec §VIII 后,Executor 只消费该计划与几何数据,不会重新打开源图进行语义探索。用户图、抽取图、网络图、AI 图、公式图和切片图仍统一汇入同一张可度量事实表。
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 74ac3f10..def1a9cb 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -50,9 +50,11 @@ To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the
Per-element animation is off by default. To enable it deck-wide, pass `-a auto` at export (no config needed). When a deck instead needs specific object timing — for example title first, chart second, annotation last — use the optional `animations.json` sidecar. The SVG remains the visual source; the custom stage may rewrite its grouping hierarchy, ids, and bounds to create better semantic anchors without changing visible output, while the sidecar controls PPTX animation behavior.
Run the [`customize-animations`](../workflows/stages/customize-animations.md)
-post-processing stage when Design Spec §IX contains `Motion suggestion`, or
-when the project already carries `animations.json`, or when the user asks to
-tune animation order, effects, timing, or object-level reveals.
+post-processing stage when the project already carries `animations.json`, when
+the user explicitly asks to tune animation order/effects/timing/object-level
+reveals, or when the effective Custom Animations outcome in
+`design_spec.md §I` is enabled. A §IX `Motion suggestion` remains Strategist
+advice and informs an active pass, but never triggers the stage alone.
**Hard rule — semantic anchors before object-targeted sidecar entries**: when
object animation is in scope, derive reveal units from page meaning and
@@ -355,7 +357,7 @@ Flags: `-a/--animation` selects effect/mode; `--animation-trigger` selects Start
`--animation-config` selects a sidecar; `--no-animations` disables page/object
motion but preserves narration audio and recorded advance timing.
-> Note: `--recorded-narration` rejects `on-click` and `trigger_shape`; use its default `narration_animations.json`, pass `--animation-config animations.json` for the canonical presentation animation, or pass `--no-animations`.
+> Note: `--recorded-narration` rejects `on-click` and `trigger_shape`. When either animation sidecar exists, narrated export selects `narration_animations.json`; canonical `animations.json` without that derived file remains a synchronization error. When both are absent, export creates no sidecar and keeps `fade` / no per-element builds. Pass `--animation-config animations.json` to use the canonical presentation animation, or `--no-animations` to remove both page and object motion explicitly.
### 4.1 Slow ambient motion — the page that breathes
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index d2d6feb3..9683db4a 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -18,7 +18,7 @@ Global artifact ownership rules for PPT Master projects.
| `analysis/<stem>.identity.json` | Native deck identity facts | Canvas, theme palette/fonts, observed usage | Read selectively when detailed identity facts are needed |
| `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract |
| `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes |
-| `design_spec.md` | Strategist design authority | Human-readable design intent, page brief, rationale, resources, and production mechanics | Consume final confirmation once, write/audit here, and apply enabled refinement to this same artifact. After Gate 1 plus conditional approval, later roles read it instead of `result.json`; §IX owns Executor page content. |
+| `design_spec.md` | Strategist design authority | Human-readable design intent, page brief, rationale, resources, and production mechanics | Consume final confirmation once, write/audit here, and apply enabled refinement to this same artifact. §I records effective Speaker Notes, Custom Animations, and Narration Audio outcomes plus provenance; a newer explicit user instruction updates only its owning outcome without reopening Confirm UI. After Gate 1 plus conditional approval, later roles read this file instead of `result.json`; §IX owns Executor page content. |
| `spec_lock.md` | Execution anchor and routing contract | Machine-readable stable color/type roles, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist authors the route-specific anchors from the audited Design Spec plus current project/page/template context. Executor retains the complete lock once per valid execution context; local uncertainty consults that retained copy before the owning Design Spec fragment. Sparse page-local color/font garnish needs no lock row; a recurring semantic role or new adaptive Layout identity requires Strategist repair before reuse. |
| `project_manager.py page-context` stdout | Derived on-demand page context | Read-only model-facing anchor set + current-page delta + fingerprints for large references | Use only for explicit diagnostics/telemetry or an unresolved page/template/chart path-SHA projection. Never edit or persist it as a replacement source of truth, and never run it as a routine pre-page gate. `global` is a bounded anchor set, not a whitelist. `reference_set` carries path/SHA/load policy but never appends reference payloads. |
| `analysis/page-context/P<NN>.usage.json` | Derived optional context telemetry | Measured on-demand page-context size plus hashes of owning inputs/references | `page-context --record-usage` deterministically replaces only the invoked page's snapshot; `page-context-report` summarizes existing snapshots. Telemetry may be partial. Use token data to evaluate context cost, never as content or an execution contract. |
@@ -36,14 +36,14 @@ Global artifact ownership rules for PPT Master projects.
| `confirm_ui/recommendations.stage1.json`, `.stage2.json`, `.stage3.json` | Confirmation proposals | One Strategist-authored payload per confirmation stage | Confirm UI selects the active file from `result.json`. The active, unconfirmed stage may be overwritten when the user requests a new recommendation; normal progression writes the next stage file and leaves confirmed earlier stages intact. Legacy `recommendations.json` is read only when no stage-specific file exists. |
| `confirm_ui/result.json` | Confirmation result | Persisted user-confirmed input evidence | Generate Step 4 reads the final object once into active context; Strategist consumes it completely into `design_spec.md`. Normal downstream work does not reopen it; fresh recovery may read it once when no retained final state exists. |
| `svg_output/` | Page-design author source | Main-agent handwritten SVG pages containing the complete visible design | Quality checker and native PPTX export read this as the canonical visual/page-layout source; templates and locks do not add missing visible objects at export |
-| `notes/total.md` | Speaker-note source | Complete notes before splitting | Step 6 writes; Step 7.1 splits |
-| `notes/slide_*.md` | Split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` |
+| `notes/total.md` | Conditional speaker-note source | Complete notes before splitting | Step 6 writes only when the effective Speaker Notes outcome is enabled; Step 7.1 splits |
+| `notes/slide_*.md` | Conditional split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` only when speaker notes are enabled |
| `svg_final/` | Derived visual preview | Self-contained post-processed SVGs that may be opened directly or inserted as SVG pictures | Rebuild from `svg_output/` with `finalize_svg.py`; do not use as a supported PPTX source |
| `validation/svg_quality_report.json` | Quality provenance | Final SVG gate split into blocking / introduced / inherited / source-import categories, bound to the checked SVG bytes by SHA-256 | `svg_quality_checker.py --stage final --json` writes before export; the exporter reads it programmatically and links it only when the export-source fingerprint matches. Agents use successful command output and do not load the full JSON except for targeted failure/audit reads. |
| `validation/<output_stem>.report.json` | Published-package audit | PPTX package/resource postflight status, part counts, and quality-gate linkage | Step 7.3 writes after the PPTX passes package validation and emits a compact `[POSTFLIGHT]` receipt. Agents use the receipt on routine success and keep the full JSON cold unless targeted failure/audit evidence is required. |
| `exports/` | Delivery artifacts | Native DrawingML PPTX and explicit native-object/narration variants | Step 7.3 writes only final deliverables from `svg_output/`. |
| `backup/<timestamp>/svg_output/` | Frozen author-source archive | Re-export source without re-running LLM | `svg_to_pptx.py` writes a snapshot during export |
-| `animations.json` | Optional animation config | Page-transition and object-animation sidecar | Created only when the conditional animation workflow activates; normal export never creates it |
+| `animations.json` | Optional animation config | Page-transition and object-animation sidecar | An existing file always activates preserve/validate handling. Without one, creation requires an explicit animation instruction or an enabled effective Custom Animations outcome; a §IX Motion suggestion alone never activates it |
---
@@ -68,6 +68,7 @@ Global artifact ownership rules for PPT Master projects.
| Export source | The only supported generated-PPTX route reads `svg_output/` through the project SVG-to-DrawingML converter. A diagnostic `-s final` override does not change ownership or create a supported release route. |
| Shape-conversion boundary | PowerPoint's manual Convert-to-Shape operation on `svg_final/` is outside the project compatibility contract. |
| Confirmation | Final UI/chat confirmation overrides recommendations and is consumed once into `design_spec.md`. Enabled refinement applies arbitrary revisions there and requires approval; only then may active-decision fidelity release lock authoring. |
+| Proactive production outcomes | Resolve notes/custom-animation/narration behavior from latest explicit user instruction → Stage 3 proactive policy → compatibility default `enabled` / `disabled` / `disabled`. Narration enabled requires notes enabled without rewriting raw Stage 3 evidence. Persist only each effective outcome plus provenance in `design_spec.md §I`; do not copy these decisions into `spec_lock.md`. |
**Forbidden - mixed ownership**: Do not copy chart values from Markdown into `analysis/` by hand, do not edit `svg_final/` as the source of a fix, do not edit imported lossless SVGs instead of their authoring IR, and do not treat `design_spec.md` prose as a replacement for `spec_lock.md`.
@@ -79,7 +80,7 @@ Global artifact ownership rules for PPT Master projects.
|---|---|---|
| `analysis/image_analysis.csv` | Current `images/` | `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` |
| `<import_workspace>/authoring-svg/authoring_summary.json` | Current authoring SVGs plus tool-only manifest roster | `python3 ${SKILL_DIR}/scripts/svg_authoring_view.py <import_workspace>/authoring-svg --refresh-summary`; in-place vector/picture extraction refreshes it automatically |
-| `notes/slide_*.md` | `notes/total.md` | `python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>` |
+| `notes/slide_*.md` | `notes/total.md`, when speaker notes are enabled | `python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>` |
| `svg_final/` | `svg_output/` plus project assets | `python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>` |
| `validation/svg_quality_report.json` | `svg_output/`, locks, template provenance | `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json` |
| Native PPTX + `validation/<output_stem>.report.json` | `svg_output/` plus notes/assets and final quality report | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 1f1081b6..58472ba4 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -11,7 +11,7 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
| A page will use a preset pattern fill or evaluate native chart/table replacement | [`native-data-interface.md`](./native-data-interface.md) before deciding eligibility or emitting metadata |
| Any image/formula; a cited `#<id>` or optional composition recall also triggers the library | [`executor-image.md`](./executor-image.md); conditionally [`image-layout-patterns.md`](./image-layout-patterns.md) |
| Any `Status: Sourced` web image | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` |
-| Speaker notes generation after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |
+| Effective Speaker Notes outcome is enabled after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |
> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). Technical constraints are in [`shared-standards-core.md`](./shared-standards-core.md).
@@ -40,7 +40,7 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
**Hard rule — discovery does not expand compatibility**: Follow `svg-effects.md` syntax and fallbacks; unsupported blur, blend, mask, dense texture, or skew remains baked/alternative-only.
-**Default — resolve cross-page geometry here, while pages are still being authored (may override when the deck has no continuous action to express)**: object effects, page transitions, and Morph pair keys are post-processing decisions, but the two visible endpoint states are not. A sequence that should read as one continuous action (slide-in, flip, camera push-in, progressive reveal, camera pan) must be authored as consecutive pages in `svg_output/` now. Give each continuing endpoint a compatible direct-root group; source and destination ids or geometry may differ because the later motion stage can bind them explicitly through `animations.json`. A deck that reaches export without both states cannot gain the motion by adding a flag. Adding pages is a §IX roster change and returns to Strategist for Design Spec repair first.
+**Default — resolve active cross-page geometry here, while pages are still being authored (may override when the deck has no continuous action to express)**: object effects, page transitions, and Morph pair keys are post-processing decisions, but the two visible endpoint states are not. Apply this preparation only when an explicit user motion instruction, an enabled effective Custom Animations outcome, or an existing `animations.json` activates motion; a §IX Motion suggestion alone remains non-operative advice. An active sequence that should read as one continuous action (slide-in, flip, camera push-in, progressive reveal, camera pan) must be authored as consecutive pages in `svg_output/` now. Give each continuing endpoint a compatible direct-root group; source and destination ids or geometry may differ because the later motion stage can bind them explicitly through `animations.json`. A deck that reaches export without both states cannot gain the motion by adding a flag. Adding pages is a §IX roster change and returns to Strategist for Design Spec repair first.
---
@@ -81,8 +81,8 @@ Use named lock roles literally when that role applies, and use optional `Templat
| `consumption_mode` | Page execution |
|---|---|
| `text` | Make the visible page independently understandable. Preserve complete prose, explicit labels / captions / sources, tables, and necessary detail; use bullets only for genuinely parallel or ordered items. |
-| `balanced` | Keep the primary claim and its evidence on the page; let notes add interpretation and transitions. Mix prose, structured evidence, and necessary lists according to their semantic relationship. |
-| `presentation` | Make one claim and one dominant visual expression legible at projection distance. Keep visible copy concise; put explanation and transitions in notes instead of creating paragraph dumps or compressed bullet prose. |
+| `balanced` | Keep the primary claim and its evidence on the page; when notes are enabled, let them add interpretation and transitions. Mix prose, structured evidence, and necessary lists according to their semantic relationship. |
+| `presentation` | Make one claim and one dominant visual expression legible at projection distance. Keep visible copy concise; when notes are enabled, put explanation and transitions there instead of creating paragraph dumps or compressed bullet prose. When notes are disabled, rely only on the confirmed presenter/page channels and never omit required content on the assumption that notes will carry it. |
Apply the content-vs-expression contract above within the selected reading mode. Never drop or invent facts to force a mode. When the authored texture materially conflicts with the lock, render the least-destructive faithful composition and surface `warning: P<NN> content texture conflicts with consumption_mode <value>` as an upstream outline issue; do not encode this subjective judgment in the checker.
@@ -142,7 +142,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
- **Template structure**: inherit the native visual framework only for `template_reuse_scope: mirror|layout`; `style` uses the flat route
- **Main-agent ownership**: SVG generation must run in the main agent (not sub-agents) — pages share upstream context for cross-page visual continuity
- **Generation rhythm**: P01 → first-page gate → uninterrupted remaining pages → final gate, in one context without batches or mid-run checker calls.
-- **Fact provenance**: when a §IX page lists `Fact IDs`, resolve each ID from `sources/*.facts.json` and keep the claim/value unchanged. Render a compact source footnote using the source name and a short URL/domain when space permits; state the attribution naturally in speaker notes. When §IX says `Data class: scenario`, place a visible localized `Scenario data` / `情景数据` label adjacent to the affected KPI/chart and state naturally in notes that the number is illustrative. Never attach an external fact ID to scenario data or let an unlabeled invented KPI look factual.
+- **Fact provenance**: when a §IX page lists `Fact IDs`, resolve each ID from `sources/*.facts.json` and keep the claim/value unchanged. Render a compact source footnote using the source name and a short URL/domain when space permits; when speaker notes are enabled, state the attribution naturally there too. When §IX says `Data class: scenario`, place a visible localized `Scenario data` / `情景数据` label adjacent to the affected KPI/chart and, when notes are enabled, state naturally there that the number is illustrative. Never attach an external fact ID to scenario data or let an unlabeled invented KPI look factual.
- **Default — stage each page with the style's composition geometry (may override when the content genuinely calls for a plain grid)**: an SVG page is a canvas, not a DOM. Before defaulting to stacked rounded-rect cards or uniform equal columns, pick one page-scale move from the locked visual style's §1 `Composition geometry` (a bleed shape, diagonal split, oversized numeral, orbit rings, …) to stage the page's primary zone. Card grids are one option among many, not the house layout.
- **Containers are structural**: cards and grids express grouping, hierarchy, or capacity, not a house style. Preserve meaningful template frames; restyle radius, fill, stroke, and depth from the active Design Spec and `spec_lock.md`. Chart-catalog adaptation is owned by [`executor-chart.md`](./executor-chart.md); preview effects never override project styling or structural roles.
- **Reference — prefer semantic geometry over preset stacks**: for relationships such as ascending, converging, breaking through, or stacking, first seek a basic primitive, one exact preset, or a clear Boolean result. Only when none can faithfully express the relationship should one page-specific polygon/path replace a stack of generic arrows.
@@ -150,7 +150,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
- **Phased generation** (recommended):
1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every §IX-planned data-chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every planned native-ready object. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path> --stage first-page --json` without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.
2. **Quality Check Gate**: only after every planned SVG exists, run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
- 3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.
+ 3. **Logic Construction Phase (conditional)**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity only when the effective Speaker Notes outcome is enabled.
### 3.0 Native Shape Selection
@@ -293,11 +293,15 @@ Typography comes from `spec_lock.md`: `<role>_family` wins; otherwise titles use
## 6. Completion Routing
-After every SVG page passes the final quality check, load [`executor-notes.md`](./executor-notes.md) and complete its notes contract before entering the route's Step 7.
+After every SVG page passes the final quality check, load
+[`executor-notes.md`](./executor-notes.md) and complete its notes contract only
+when the effective Speaker Notes outcome in `design_spec.md §I` is enabled.
+When disabled, proceed directly to the route's conditional motion handling and
+Step 7.
## 7. Next Steps After Completion
-> **Auto-continuation**: After Visual Construction Phase (all SVG pages) and Logic Construction Phase (all notes) are complete, the Executor proceeds directly to the post-processing pipeline.
+> **Auto-continuation**: After Visual Construction Phase and any enabled Logic Construction Phase are complete, the Executor proceeds directly to the post-processing pipeline.
**Post-processing & Export**: Follow [`generate-pptx.md`](../workflows/generate-pptx.md)
Step 7. That workflow owns the serial commands, gates, success criteria, and
diff --git a/skills/ppt-master/references/executor-notes.md b/skills/ppt-master/references/executor-notes.md
index 88e3418b..02eadda7 100644
--- a/skills/ppt-master/references/executor-notes.md
+++ b/skills/ppt-master/references/executor-notes.md
@@ -4,7 +4,11 @@
Conditional late-stage authority for generating the complete speaker-notes document.
-**Trigger**: load only after all SVG pages pass the final quality check.
+**Trigger**: load only after all SVG pages pass the final quality check and the
+effective Speaker Notes outcome in `design_spec.md §I` is enabled. A missing
+legacy outcome uses compatibility default `enabled`; effective Narration Audio
+enabled also requires Speaker Notes enabled. When notes are disabled, do not
+load this branch or create `notes/total.md`.
## 1. Complete Speaker-notes Document
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 255cd2ce..0c98427c 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -30,9 +30,9 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
|---|---|---|
| **1 — communication contract** | `c` audience · open-ended communication intent · audience outcome · core message / delivery context (primary + optional secondary) / artifact afterlife · `content_divergence` (all prose fields may be blank) · `a` canvas | confirmed first |
| **2 — complete deck solution** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering · conditional natural-language template application | derived from the confirmed contract; internal template exporter modes remain hidden |
-| **3 — resources / production** (authored once from the user's *actual* Stage 1 + Stage 2) | formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle | derived from the confirmed solution |
+| **3 — resources / production** (authored once from the user's *actual* Stage 1 + Stage 2) | formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle · proactive speaker notes / custom animations / narration audio | derived from the confirmed solution |
-Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, and image direction. With a template, inspect its actual prototypes/content, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Stage 3 covers production. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
+Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, and image direction. With a template, inspect its actual prototypes/content, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Stage 3 covers production. Its proactive defaults are speaker notes `true`, custom animations `false`, and narration audio `false`; a prior explicit user instruction overrides the matching recommendation, and effective narration audio requires effective speaker notes. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
> **Execution discipline**: This is the last always-on BLOCKING checkpoint. After confirmation, proceed without another pause unless spec refinement is enabled.
>
@@ -85,7 +85,7 @@ Seed the following as open-prose recommendations when the source and user reques
The contract is not the narrative mode. `communication_intent` says what change is needed; `mode` is one Stage-2 strategy for organizing the argument. Several intents may share one dominant mode, and one intent may support several possible modes.
-**Reading mode** (PPT only) is a closed Stage-2 information-carriage axis: `text` (read-close) / `balanced` (business, default) / `presentation`. Keep the existing `recommend.delivery_purpose` / `result.json.delivery_purpose` key for compatibility, but label and reason about it as reading mode—never as communication purpose. It decides how meaning is divided among the page, visuals, presenter, and notes, driving page grammar, granularity, density / rhythm, and the §b page-count recommendation. The §g body baseline is a downstream typography default, not the label or definition shown in the reading-mode control.
+**Reading mode** (PPT only) is a closed Stage-2 information-carriage axis: `text` (read-close) / `balanced` (business, default) / `presentation`. Keep the existing `recommend.delivery_purpose` / `result.json.delivery_purpose` key for compatibility, but label and reason about it as reading mode—never as communication purpose. It decides how meaning is divided among the page, visuals, presenter, and, when enabled, notes, driving page grammar, granularity, density / rhythm, and the §b page-count recommendation. The §g body baseline is a downstream typography default, not the label or definition shown in the reading-mode control.
**Material divergence** — a **free-text** source-treatment intent in the Stage-1 delivery section: in their own words, how closely the deck should follow the source vs how freely it may reshape it. This is the user's own call — a free prose field (`content_divergence`), **not** a fixed set of options and **not** something you recommend from analyzing the source. Surface the question plainly (in the confirm UI it appears after the delivery-context fields); leave it for the user to fill. Blank = a balanced default.
@@ -286,6 +286,11 @@ user/template requirements bind.
| Page transition | A section/state change, spatial continuity, recorded/self-running flow, or the same semantic object changing position, scale, crop, or state across adjacent pages benefits from motion | Add an optional §IX `Motion suggestion` describing the communication job and any continuing object's start/end semantic states; leave effect, ids, pairing names, and timing to Executor |
| Object animation | Progressive reveal clarifies sequence, causality, comparison, hierarchy, narration order, full-view → detail, atmosphere → evidence, or hotspot/annotation order | Add an optional §IX `Motion suggestion` describing semantic units/order and any visible image-state relationship; leave group ids, effect, and timing to Executor |
+Write useful motion advice regardless of the effective Custom Animations outcome.
+The suggestion remains non-binding and never activates custom-animation
+execution by itself; only an explicit motion requirement or an enabled outcome
+may require visible endpoint/reveal-state preparation.
+
Review planned pages through two lenses:
| Lens | Content shapes |
@@ -340,11 +345,22 @@ Executor still decides the exact basic primitive, preset, Boolean construction,
or necessary freeform under its native-shape branch; the recommendation never
creates a §VII row or lock field.
-### Speaker Notes Requirements (Default — no discussion needed)
+### Speaker Notes Requirements
+
+Resolve the effective Speaker Notes outcome from the latest explicit user
+instruction, then Stage 3 `proactive_speaker_notes`, then compatibility default
+`true`. Effective Narration Audio `enabled` requires Speaker Notes `enabled`
+without changing the raw proactive preference; when that dependency changes the
+notes outcome, its provenance names enabled Narration Audio.
+
+| Effective outcome | Design Spec §X |
+|---|---|
+| `enabled` | Record filename policy, content/source handling, total duration, notes style, and presentation purpose |
+| `disabled` | Keep §X and write `Generation: disabled`; do not invent note requirements |
-- File naming: Recommended to match SVG names (`01_cover.svg` → `notes/01_cover.md`), also compatible with `notes/slide01.md`
-- Fill in the Design Spec: total presentation duration, notes style (formal / conversational / interactive), presentation purpose (inform / persuade / inspire / instruct / report)
-- Split note files must NOT contain `#` heading lines (`notes/total.md` master document MUST use `#` heading lines)
+When enabled, match SVG names where possible (`01_cover.svg` →
+`notes/01_cover.md`); `notes/slide01.md` remains compatible. Split files contain
+no `#` heading lines; `notes/total.md` uses `#` headings.
---
@@ -392,9 +408,9 @@ Free-design patterns are starting points, not quotas. Adjust composition, spacin
### 6.1 Content Planning Strategy
-Content-outline and speaker-notes strategy follow the deck's locked **mode** — see [`modes/_index.md`](./modes/_index.md), then the locked preset file or every listed custom reference plus its behavior. The guidance below applies within any mode:
+Content-outline strategy and, when enabled, speaker-notes strategy follow the deck's locked **mode** — see [`modes/_index.md`](./modes/_index.md), then the locked preset file or every listed custom reference plus its behavior. The guidance below applies within any mode:
-**Reading mode controls information carriage, not communication intent.** `result.json delivery_purpose` is retained as the compatibility key for `text` (read-close) / `balanced` (business, default) / `presentation`, confirmed with the complete deck solution in Stage 2. It decides how meaning is divided among the page, visuals, presenter, and notes. The body baseline (§g) is one consequence, not the definition:
+**Reading mode controls information carriage, not communication intent.** `result.json delivery_purpose` is retained as the compatibility key for `text` (read-close) / `balanced` (business, default) / `presentation`, confirmed with the complete deck solution in Stage 2. It decides how meaning is divided among the page, visuals, presenter, and enabled notes. The body baseline (§g) is one consequence, not the definition:
| Reading mode | Primary carrier | §IX page grammar | Granularity / rhythm | Speaker notes |
|---|---|---|---|---|
@@ -402,11 +418,14 @@ Content-outline and speaker-notes strategy follow the deck's locked **mode** —
| `balanced` · business (default) | page + presenter | one primary claim with concise explanation, structured evidence, or a necessary list | moderate granularity; mixed rhythm | interpretation and transitions |
| `presentation` | presenter + visuals | one claim per page, keywords / short phrases, a large visual or hero number; no paragraph dumps or prose compressed into bullet fragments | more, sparser pages; leans `anchor` / `breathing` | carries explanation, transitions, and supporting detail |
-**Recommendation signals**: derive the initial reading mode from the confirmed `audience`, `delivery_context`, and `artifact_afterlife`. Asynchronous review, reference, approval, audit, and leave-behind use lean `text`; presenter-led projection, large-room delivery, launch, or classroom explanation lean `presentation`; hybrid review / roadshow use leans `balanced`. When live projection and durable afterlife both matter, recommend `balanced` unless the contract clearly prioritizes one. If the user confirms `presentation`, support afterlife through notes, appendix pages, captions, and visible sources instead of crowding every slide.
+When Speaker Notes is disabled, the final column is unavailable: keep every
+required meaning in the visible page and confirmed presenter channel.
+
+**Recommendation signals**: derive the initial reading mode from the confirmed `audience`, `delivery_context`, and `artifact_afterlife`. Asynchronous review, reference, approval, audit, and leave-behind use lean `text`; presenter-led projection, large-room delivery, launch, or classroom explanation lean `presentation`; hybrid review / roadshow use leans `balanced`. When live projection and durable afterlife both matter, recommend `balanced` unless the contract clearly prioritizes one. If the user confirms `presentation`, support afterlife through enabled notes, appendix pages, captions, and visible sources instead of crowding every slide.
-**Per-block expression**: let the semantic relationship choose the form. Causal explanation, argument, interpretation, and narrative continuity use prose. Truly parallel, ordered, or enumerable items may use bullets / numbers. Never create bullets merely because copy is long or a template exposes a list slot. In `presentation`, distill one assertion and move its explanation into notes rather than turning every sentence into a fragment. Source texture remains a secondary cue: an article / transcript / talk leans prose, while a data sheet or inventory may lean structured labels. Write complete, usable phrasing into §IX; do not leave skeletons for Executor. It is preferred wording unless literal preservation applies; Executor owns faithful expression adaptation under [`executor-base.md`](./executor-base.md) §2.1's content-vs-expression contract.
+**Per-block expression**: let the semantic relationship choose the form. Causal explanation, argument, interpretation, and narrative continuity use prose. Truly parallel, ordered, or enumerable items may use bullets / numbers. Never create bullets merely because copy is long or a template exposes a list slot. In `presentation`, distill one assertion and move its explanation into enabled notes rather than turning every sentence into a fragment; when notes are disabled, keep the necessary explanation in the visible page or confirmed presenter channel. Source texture remains a secondary cue: an article / transcript / talk leans prose, while a data sheet or inventory may lean structured labels. Write complete, usable phrasing into §IX; do not leave skeletons for Executor. It is preferred wording unless literal preservation applies; Executor owns faithful expression adaptation under [`executor-base.md`](./executor-base.md) §2.1's content-vs-expression contract.
-This is what makes the axis meaningful: a `presentation` deck and a `text` deck built from the **same source and communication contract** must differ in page grammar, page count recommendation, per-page text volume, visual burden, layout density, rhythm, and notes—not only in font size. Page count stays the user's call; reading mode informs the recommendation when the user has not fixed one. Record it as **Reading Mode** in `design_spec.md §I` (compatibility key `delivery_purpose`, lock key `consumption_mode`). Separately, `communication_intent` / `audience_outcome` determine what the outline must accomplish, while `delivery_context` and `artifact_afterlife` help select the reading mode and still remain independent constraints after selection. The `page_rhythm` leans are a bias, not a quota. Preservation paths keep source wording and structure verbatim: honor reading mode only in styling and notes, never by rephrasing or re-paginating.
+This is what makes the axis meaningful: a `presentation` deck and a `text` deck built from the **same source and communication contract** must differ in page grammar, page count recommendation, per-page text volume, visual burden, layout density, rhythm, and enabled notes—not only in font size. Page count stays the user's call; reading mode informs the recommendation when the user has not fixed one. Record it as **Reading Mode** in `design_spec.md §I` (compatibility key `delivery_purpose`, lock key `consumption_mode`). Separately, `communication_intent` / `audience_outcome` determine what the outline must accomplish, while `delivery_context` and `artifact_afterlife` help select the reading mode and still remain independent constraints after selection. The `page_rhythm` leans are a bias, not a quota. Preservation paths keep source wording and structure verbatim: honor reading mode only in styling and enabled notes, never by rephrasing or re-paginating.
> Note: §IX is the complete page brief; Executor retains it with the lock until context invalidation, then reloads both once.
@@ -414,8 +433,15 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
Generate Step 4 owns this sequence. `design_spec.md` is the complete human-readable decision; `spec_lock.md` is its context-selected execution subset/routing contract. Consume `result.json` once into the initial Design Spec and never reopen it for the lock. Refinement edits that same Design Spec; affected user revisions become the latest authority. Never treat the planning files as parallel interpretations.
+After final confirmation, a newer explicit user instruction about notes, custom
+animation, or narration updates only the corresponding effective outcome and
+provenance in `design_spec.md §I`. Resume at the owning step without reopening
+Confirm UI or adding the production decision to `spec_lock.md`. Enabling
+Narration Audio also recomputes the dependent Speaker Notes outcome and
+provenance.
+
1. Use the retained complete final-confirmation state already read once by Generate Step 4, then read `templates/design_spec_reference.md`.
-2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/chart patterns remain References unless promoted.
+2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I, including one effective outcome plus provenance for Speaker Notes, Custom Animations, and Narration Audio. Resolve them from latest explicit user instruction → matching Stage 3 proactive value → compatibility default `enabled` / `disabled` / `disabled`; Narration Audio enabled requires Speaker Notes enabled without rewriting the raw proactive evidence, and a dependency-driven notes outcome records that provenance. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/chart patterns remain References unless promoted.
3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before entering an enabled refine-spec review or authoring `spec_lock.md`.
4. If enabled, run [`refine-spec`](../workflows/stages/refine-spec.md) after Gate 1; edit only that Design Spec and create no lock before explicit approval.
5. Read `templates/spec_lock_reference.md`. From the approved Design Spec plus context, create the lock once or resynchronize stale derived state. Retain identity/refinements, select stable roles/routing, omit unnamed page-local values, and do not reopen evidence. This is implementation judgment, not another recommendation.
@@ -432,6 +458,7 @@ Generate Step 4 owns this sequence. `design_spec.md` is the complete human-reada
| Confirmed image-source set, `image_notes`, and AI strategy | §VIII uses only permitted sources and includes every explicitly required source, asset, or page role; a permitted but unused source needs no row |
| Natural-language template application | §I records it and the relevant layout/prototype choices realize it without silently dropping a requested use or exclusion |
| Formula policy, AI-image acquisition path, generation mode, refine-spec toggle | §I records them as production mechanics; their owning Generate stage consumes the Design Spec, and formula policy also shapes §VIII when formula-worthy content exists |
+| Proactive speaker notes, custom animations, and narration audio | §I records the three resolved effective outcomes with provenance, while §X records enabled note requirements or `Generation: disabled`; they remain outside `spec_lock.md`. §IX Motion suggestions remain optional advice regardless of the animation outcome |
⛔ **GATE 1 — active-decision fidelity.** Do not create `spec_lock.md` until the initial Design Spec passes the comparison above and any enabled refinement is explicitly approved. Before Gate 2, every requested revision must be present and every unaffected decision intact. Missing/substituted values, unapplied revisions, or silently changed semantic types block despite schema validity; bounded Reference adaptation and unused Permission remain valid.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 9c098daf..f93e468d 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -251,11 +251,16 @@ the existing references without progressively wrapping more parent geometry.
Post-processing and export:
```bash
+# Run only when the Design Spec's effective Speaker Notes outcome is enabled.
python3 scripts/total_md_split.py <project_path>
python3 scripts/finalize_svg.py <project_path>
python3 scripts/svg_to_pptx.py <project_path>
```
+When Speaker Notes is disabled, skip `total_md_split.py` and append
+`--no-notes` to `svg_to_pptx.py` so stale files under `notes/` cannot be
+embedded.
+
`finalize_svg.py` optimizes ordinary raster images by default using `2x` display pixels and max `2560px`; validated nested crop transports retain source pixel dimensions because their inner `1×1` image is source-unit geometry rather than a rendered-pixel budget. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: images that need neither resizing nor EXIF geometry normalization retain their original bytes, while oversized single-frame raster sources are re-encoded after resizing toward `2560px`. Cropped or stretched placements (including imported picture crops) retain enough source pixels to avoid undersupplying the visible frame. Use `svg_to_pptx.py --image-sizing display --image-scale 2 --image-quality 85` for an explicit compact export, or `--no-image-optimize` to force original image bytes.
`finalize_svg.py` remains mandatory because it creates the self-contained `svg_final/` visual preview. Those SVGs may be opened directly or inserted into PowerPoint as SVG pictures. The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter; `-s final` is diagnostic-only, and PowerPoint's manual Convert-to-Shape operation is unsupported.
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index 3766e581..b56fe17f 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -54,6 +54,7 @@ pip install flask
- **Visual examples for hard-to-name choices** — the full-screen confirmation page loads real SVG page samples from `static/style_previews/` for `visual_style`, and renders real sample SVGs from `templates/icons` for `icons`. These thumbnails make style and icon-library choices visually comparable before the user locks them. Preview copy is fixed role text (big title / section title / body / points), not project content from recommendation files, so users compare visual treatment rather than copywriting. These previews are a confirmation aid only: they do not add fields to recommendation stage files or `result.json`, and they do not replace the later Step 6 live preview.
- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. A confirmed non-`none` set is the allowed acquisition-source boundary, not a requirement to use every selected source; only explicit `image_notes` wording can require a source, asset, or page role. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
- **Closed enumerable** — PPT reading mode (`delivery_purpose` compatibility key), formula policy / generation mode / refine spec, plus AI source only when image usage includes `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option.
+- **Proactive execution booleans** — Stage 3 carries top-level `proactive_speaker_notes`, `proactive_custom_animations`, and `proactive_narration_audio` values. Defaults are `true`, `false`, and `false`, respectively. They control what the Agent does proactively only when the user has not explicitly instructed otherwise; the latest explicit user instruction always wins. These three values are raw confirmation evidence: the UI and server neither couple nor rewrite them, and every boolean combination is valid. When narration audio is enabled, Strategist later resolves the effective Speaker Notes outcome to enabled and records `Narration Audio dependency` as its Design Spec provenance. Disabling proactive custom animation does not suppress the Strategist's advisory motion recommendations.
- **Open prose** — `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, `content_divergence`, and `page_count`. `communication_intent` may carry several purposes plus priority / sequence; common paths appear only as help text. `delivery_context` states one primary presenter-led / reader-led / hybrid / recorded-self-running context plus optional secondary use; a hybrid recommendation names which context leads. `content_divergence` is the source-treatment axis. `page_count` may be a range here; Strategist resolves the exact §IX roster, leaving Executor no pagination latitude.
- **Coordinated generative directions** — `design_directions` carries ≥3 safe / shifted / bold candidates. Each candidate bundles visual style, color, typography, icon id, and conditional generated-image rendering. The page can still render legacy top-level `color`, `typography`, and `image_strategy` candidates, but new staged recommendations use the coordinated bundle.
@@ -79,7 +80,7 @@ The page runs as a **three-stage wizard in one browser session**. Each stage has
|---|---|---|---|---|
| `recommendations.stage1.json` | `"stage1"` | communication contract — audience; open `communication_intent`; audience outcome; core message / primary delivery context + optional secondary use / artifact afterlife / `content_divergence` (all prose fields may be blank); canvas | **Confirm contract & continue** | writes `result.json` `{ stage: "stage1", status: "stage1-confirmed", <communication contract> }`; the page stays open and polls |
| `recommendations.stage2.json` | `"stage2"` | complete deck solution — conditional natural-language template application, reading mode, mode, page count, visual direction, color, icons, typography, image usage, generated-image rendering | **Confirm solution & continue** | writes `result.json` `{ stage: "stage2", status: "stage2-confirmed", <contract + solution> }`; the page stays open and polls |
-| `recommendations.stage3.json` | `"stage3"` | production only — confirmed image-source summary, conditional AI acquisition path, formula policy, generation mode, Design Spec review toggle | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
+| `recommendations.stage3.json` | `"stage3"` | production only — confirmed image-source summary, conditional AI acquisition path, formula policy, proactive notes / custom-animation / narration-audio toggles, generation mode, Design Spec review toggle | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
| `recommendations.json` | stage or legacy no-stage payload | read-only compatibility when no stage-specific file exists | matching legacy behavior | preserves the former staged or single-pass behavior; new projects never create this file |
The AI launches Stage 1, authors the complete Stage-2 solution once from the user's actual contract, then authors Stage-3 production mechanics once from the confirmed solution. An edit inside the current stage never requests another recommendation. The page preserves earlier answers across transitions. `GET /api/session` is the waiting-state endpoint; `GET /api/recommendations` is `no-store`, and the server folds confirmed earlier-stage choices back into later payloads so refresh / reopen restores the user's actual values—including Stage-2 color, typography, icon, image-source, and rendering choices. Once any stage-specific file exists, the server ignores legacy `recommendations.json` to prevent mixed lifecycles.
@@ -197,11 +198,15 @@ After Stage 2 is confirmed, create `recommendations.stage3.json` with production
"formula_policy": "mixed",
"generation_mode": "continuous"
},
+ "proactive_speaker_notes": { "value": true },
+ "proactive_custom_animations": { "value": false },
+ "proactive_narration_audio": { "value": false },
"refine_spec": { "value": false }
}
```
- `recommend.*` names each recommended id. New mode / style values use a catalog id or literal `custom`; arbitrary prose values are legacy-only. Use `recommend.image_strategy: "custom"` only when an explicit user-supplied image direction should start selected. Missing recommendations fall back to the normal preset. Legacy aliases remain accepted; new files write canonical ids.
+- The three proactive-execution fields are top-level boolean `{ "value": ... }` objects, not catalog ids. Omitted fields use `true / false / false` for notes / custom animation / narration audio. These are absence-of-instruction defaults, not permission to override the user's latest explicit request. Preserve all three raw values independently through `result.json`; do not couple or rewrite them. Strategist derives effective Speaker Notes as enabled when audio is `true` and records `Narration Audio dependency` as provenance in the Design Spec. `proactive_custom_animations: false` leaves Strategist animation suggestions unchanged; it only prevents unrequested custom-animation execution.
- `custom_candidates` is recommendation-only. Mode / style carry localized `name` + `behavior`; conditional image strategy also carries `rendering: "custom"`, `visual`, and `mood`. When a proposal combines or borrows existing catalog entries, the visible behavior names every exact id and Strategist reads every corresponding file before authoring it; a genuinely novel proposal names none. The server rejects missing required candidates; the UI shows full copy, edits it only after selection, rejects a selected blank, and omits unselected candidates from `result.json`. Template-backed proposals obey inherited identity, prototype capacity, and `template_application`.
- `audience`, `communication_intent`, `audience_outcome`, and `delivery_context` are load-bearing Stage-1 reasoning inputs, so seed concrete recommendations when the evidence supports them; they are not required user inputs. Every Stage-1 prose field may be blank after confirmation. The complete six-field contract stays in `result.json` and `design_spec.md`; `spec_lock.md communication` receives only the compact `audience` / `objective` / `core_message` execution projection plus the applicable reading mode. `communication_intent` may preserve several purposes plus priority / sequence; never add a `primary_job` enum.
- Do not write `recommend.template_reuse_scope` or `recommend.template_adherence`. Strategist records those internal exporter values later in `spec_lock.md` after inspecting the actual template and current content.
@@ -246,6 +251,9 @@ After Stage 2 is confirmed, create `recommendations.stage3.json` with production
"image_notes": "封面和章节页用 AI 主视觉;产品页优先用户素材,缺口页可用占位符。",
"image_ai_path": "auto",
"image_strategy": { "name": "方案 A", "rendering": "vector-illustration", "visual": "...", "mood": "..." },
+ "proactive_speaker_notes": true,
+ "proactive_custom_animations": false,
+ "proactive_narration_audio": false,
"generation_mode": "continuous",
"refine_spec": false,
"stage": "final",
@@ -254,7 +262,7 @@ After Stage 2 is confirmed, create `recommendations.stage3.json` with production
}
```
-The shape above is final. Selected custom values use `mode: custom` + `mode_behavior`, `visual_style: custom` + `visual_style_behavior`, or `image_strategy.rendering: custom` + `behavior`. During Design Spec and lock authoring, Strategist projects optional `mode_references`, `visual_style_references`, or `image_rendering_references` only when that confirmed behavior actually uses named catalog sources; genuinely novel custom behavior has no reference list. Intermediate writes retain accumulated fields; legacy tier names remain read-compatible.
+The shape above is final. The proactive-execution values are independent flat booleans in `result.json`; old recommendations and results that omit them resolve to `true / false / false`. They remain raw evidence even when `proactive_speaker_notes` is `false` and `proactive_narration_audio` is `true`; Strategist owns the effective dependency resolution described above. Selected custom values use `mode: custom` + `mode_behavior`, `visual_style: custom` + `visual_style_behavior`, or `image_strategy.rendering: custom` + `behavior`. During Design Spec and lock authoring, Strategist projects optional `mode_references`, `visual_style_references`, or `image_rendering_references` only when that confirmed behavior actually uses named catalog sources; genuinely novel custom behavior has no reference list. Intermediate writes retain accumulated fields; legacy tier names remain read-compatible.
**Final-result consumption contract.** A final result is the user-confirmed input contract for the Strategist's Design Spec, not another recommendation input. After the final wait, Generate Step 4 reads the complete final object exactly once and retains it while Strategist writes and audits `design_spec.md` against every explicitly present field. Normal lock authoring and downstream execution do not reopen `result.json`; the completed Design Spec is the durable authority. Only after that audit passes does Strategist author `spec_lock.md` from the Design Spec plus current execution context, selecting stable anchors and routing rather than copying every field or enumerating every legal color/font. Every value must be consumed at the semantic type owned by [`strategist.md`](../../references/strategist.md) §1 and its field owner: do not omit or substitute it, and do not silently strengthen or weaken its type. If a confirmed requirement cannot be honored, the owning workflow reports or pauses under failure recovery; it never deletes the requirement to keep the pipeline moving.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index c76e46a1..ad953b8f 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -468,6 +468,8 @@ Do not confuse this tool with `extract_svg_assets.py`:
Run these steps one at a time. Wait for each command to exit successfully before
starting the next command.
+When the effective Speaker Notes outcome in `design_spec.md §I` is enabled, run:
+
```bash
python3 scripts/total_md_split.py <project_path>
```
@@ -484,6 +486,10 @@ After `finalize_svg.py` exits successfully, run:
python3 scripts/svg_to_pptx.py <project_path>
```
+When Speaker Notes is disabled, skip `total_md_split.py` and use
+`python3 scripts/svg_to_pptx.py <project_path> --no-notes` for the final
+command. This prevents stale files under `notes/` from being embedded.
+
Do not start another post-processing command while the current command is still
running. The canonical gates and success criteria are owned by
[`generate-pptx.md`](../../workflows/generate-pptx.md) Step 7.
@@ -614,7 +620,8 @@ Behavior:
- Narration text is read strictly from the matching `notes/*.md` file; the script only skips Markdown heading lines (`# ...`) and does not summarize, rewrite, or filter delivery notes
- `--recorded-narration audio` prepares PowerPoint's "recorded timings and narrations": every slide must have matching `m4a` / `mp3` / `wav` audio, `ffprobe` must read every duration, and `--animation-trigger on-click` is rejected
- `--recorded-narration audio` keeps speaker notes, embeds each matching audio file, and writes slide auto-advance timings from audio duration
- - Narrated export defaults to `<project>/narration_animations.json`; pass `--animation-config animations.json` for the canonical presentation animation, or `--no-animations` to remove object animations and page-transition motion while retaining narration and slide timings
+ - When either animation sidecar exists, narrated export defaults to `<project>/narration_animations.json`; a canonical `animations.json` without that derived file remains a blocking synchronization error
+ - When both animation sidecars are absent, narrated export creates no sidecar and keeps the exporter defaults (`fade` page transition, no per-element animation); pass `--animation-config animations.json` for canonical animation, or `--no-animations` only to explicitly remove both object and page-transition motion while retaining narration and slide timings
- Non-narrated export keeps the existing optional `<project>/animations.json` default
- Narration timing is merged into the existing slide timing DOM; object-animation rows and the resolved page transition are preserved rather than regenerated
- `--narration-audio-dir audio` is the lower-level embedding path: it embeds whatever files match and allows partial audio coverage
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index f84e9b20..cde8c9b2 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -12,12 +12,12 @@
"skills/ppt-master/templates/schemas/*.json"
],
"exclude": [],
- "max_tokens": 391000
+ "max_tokens": 394500
},
"file_budgets": {
"AGENTS.md": 2400,
"skills/ppt-master/SKILL.md": 850,
- "skills/ppt-master/references/executor-base.md": 8125,
+ "skills/ppt-master/references/executor-base.md": 8250,
"skills/ppt-master/references/executor-structured.md": 5300,
"skills/ppt-master/references/executor-chart.md": 3100,
"skills/ppt-master/references/executor-image.md": 1500,
@@ -28,12 +28,12 @@
"skills/ppt-master/references/svg-effects.md": 11725,
"skills/ppt-master/references/native-data-interface.md": 6200,
"skills/ppt-master/references/pptx-structure-interface.md": 4300,
- "skills/ppt-master/references/strategist.md": 14025,
+ "skills/ppt-master/references/strategist.md": 14200,
"skills/ppt-master/references/strategist-image.md": 2500,
"skills/ppt-master/references/strategist-template.md": 2100,
- "skills/ppt-master/templates/design_spec_reference.md": 3125,
+ "skills/ppt-master/templates/design_spec_reference.md": 3250,
"skills/ppt-master/templates/spec_lock_reference.md": 2375,
- "skills/ppt-master/workflows/generate-pptx.md": 13100,
+ "skills/ppt-master/workflows/generate-pptx.md": 13700,
"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800
},
"load_sets": {
@@ -45,7 +45,7 @@
"skills/ppt-master/SKILL.md",
"skills/ppt-master/workflows/routing.md"
],
- "max_tokens": 5700
+ "max_tokens": 5775
},
"support.sponsor-recommendation.en": {
"description": "English sponsor context for explicit user requests for model, AI image model, API/provider, or hosted-service recommendations.",
@@ -93,7 +93,7 @@
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/decks/README.md"
],
- "max_tokens": 58225
+ "max_tokens": 58300
},
"route.create-template.layout": {
"description": "Create Layout path through Template_Designer, SVG core, and the structured PPTX interface.",
@@ -111,7 +111,7 @@
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/layouts/README.md"
],
- "max_tokens": 58400
+ "max_tokens": 58475
},
"route.enhance-native-pptx": {
"description": "Finished-PPTX native enhancement route.",
@@ -122,7 +122,7 @@
"files": [
"skills/ppt-master/workflows/native-enhance-pptx.md"
],
- "max_tokens": 9600
+ "max_tokens": 9750
},
"route.fill-native-pptx": {
"description": "Raw-PPTX native fill route.",
@@ -133,7 +133,7 @@
"files": [
"skills/ppt-master/workflows/template-fill-pptx.md"
],
- "max_tokens": 11375
+ "max_tokens": 11450
},
"route.generate.planning": {
"description": "Generate-PPTX planning through Strategist, including reference-first whole-document authoring and representative multi-source custom mode/style synthesis; schemas and optional scaffolds are tool-consumed.",
@@ -183,7 +183,7 @@
"skills/ppt-master/workflows/profiles/quick-test.md",
"skills/ppt-master/references/shared-standards-core.md"
],
- "max_tokens": 30825
+ "max_tokens": 31500
},
"route.generate.planning-image": {
"description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed; layout-catalog recall remains optional.",
@@ -203,7 +203,7 @@
"stage.generate.strategist.image"
],
"files": [],
- "max_tokens": 64000
+ "max_tokens": 64225
},
"route.generate.planning-ai": {
"description": "Generate-PPTX planning when AI image direction is available, including representative multi-source custom rendering synthesis.",
@@ -335,7 +335,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 85625
+ "max_tokens": 87450
},
"route.generate.flat-ai-two-types": {
"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",
@@ -383,7 +383,7 @@
"stage.shared.generate-audio"
],
"files": [],
- "max_tokens": 14500
+ "max_tokens": 15100
},
"route.generate.beautify-flat-no-image": {
"description": "Generate-PPTX 1:1 beautify profile on the flat no-image path.",
@@ -393,7 +393,7 @@
"profile.generate.beautify-pptx"
],
"files": [],
- "max_tokens": 92525
+ "max_tokens": 94400
},
"route.generate.flat-no-image-chart": {
"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",
@@ -406,7 +406,7 @@
"stage.generate.verify-charts"
],
"files": [],
- "max_tokens": 109975
+ "max_tokens": 111800
},
"route.generate.brand-flat-no-image": {
"description": "Brand-preset flat Generate-PPTX path without image acquisition.",
@@ -418,7 +418,7 @@
"stage.generate.template.brand"
],
"files": [],
- "max_tokens": 92650
+ "max_tokens": 94500
},
"route.generate.deck-structured-no-image": {
"description": "Deck-preset structured Generate-PPTX path without image acquisition.",
@@ -430,7 +430,7 @@
"stage.generate.template.deck"
],
"files": [],
- "max_tokens": 102600
+ "max_tokens": 104425
},
"route.generate.layout-structured-no-image": {
"description": "Layout-preset structured Generate-PPTX path without image acquisition.",
@@ -442,7 +442,7 @@
"stage.generate.template.layout"
],
"files": [],
- "max_tokens": 103050
+ "max_tokens": 104875
},
"route.generate.topic-only-flat-no-image": {
"description": "Topic research followed by the default flat no-image Generate-PPTX path.",
@@ -452,7 +452,7 @@
"route.generate.flat-no-image"
],
"files": [],
- "max_tokens": 87025
+ "max_tokens": 88850
},
"stage.generate.executor.flat": {
"description": "Incremental flat Executor core with representative multi-source custom mode/style execution.",
@@ -632,7 +632,7 @@
"skills/ppt-master/scripts/docs/pptx-transitions.md",
"skills/ppt-master/scripts/docs/svg-pipeline.md"
],
- "max_tokens": 28750
+ "max_tokens": 28825
},
"stage.generate.video-motion-plan": {
"description": "Conditional resolved animation-to-video handoff contract.",
@@ -656,7 +656,7 @@
"files": [
"skills/ppt-master/workflows/stages/generate-audio.md"
],
- "max_tokens": 4925
+ "max_tokens": 5350
},
"governance.failure-recovery": {
"description": "Global stop, retry, and resume policy.",
@@ -664,7 +664,7 @@
"files": [
"skills/ppt-master/workflows/governance/failure-recovery.md"
],
- "max_tokens": 2500
+ "max_tokens": 2725
},
"stage.shared.conversion-reference": {
"description": "Conditional source-conversion and import compatibility reference.",
@@ -698,7 +698,7 @@
"stage.generate.strategist.template"
],
"files": [],
- "max_tokens": 62275
+ "max_tokens": 63875
},
"route.generate.planning-template-ai": {
"description": "Explicit template workspace plus confirmed AI-image planning.",
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 81d2ad3d..e240ad1f 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -46,6 +46,9 @@ Start with this exact heading order:
| AI Image Acquisition Path | <confirmed path or not applicable> |
| Generation Mode | <continuous or split> |
| Spec Refinement | <enabled or disabled> |
+| Speaker Notes | <enabled or disabled> — <explicit user instruction, Stage 3 proactive policy, compatibility default, or enabled Narration Audio dependency> |
+| Custom Animations | <enabled or disabled> — <explicit user instruction, Stage 3 proactive policy, or compatibility default> |
+| Narration Audio | <enabled or disabled> — <explicit user instruction, Stage 3 proactive policy, or compatibility default> |
| Created Date | <YYYY-MM-DD> |
## II. Canvas Specification
@@ -191,6 +194,7 @@ Write one ordered Slide block per page. Slide count and order must equal §I `Pa
## X. Speaker Notes Requirements
+- **Generation**: <enabled or disabled>
- **Filename**: match each SVG filename under `notes/`
- **Content**: <notes content and source-handling policy>
- **Total duration**: <resolved duration>
@@ -198,6 +202,10 @@ Write one ordered Slide block per page. Slide count and order must equal §I `Pa
- **Presentation purpose**: <inform, persuade, inspire, instruct, report, or resolved combination>
```
+When Speaker Notes is disabled, keep §X with only
+`- **Generation**: disabled`; do not write filename, duration, style, or purpose
+placeholders. Narration Audio enabled requires Speaker Notes enabled.
+
Append either or both optional lines only when the capability earns a place;
never write an empty or `none` placeholder:
@@ -206,7 +214,7 @@ never write an empty or `none` placeholder:
- **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order>
```
-Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visualization; mark it data-driven when source values determine geometry. §IX stays authoritative without a catalog match and may choose a custom visualization or table. Add `Native shape suggestion` only when a preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name the semantic result plus candidate family or Boolean operands, never implementation geometry or keys. Executor chooses the primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` only when transition/reveal strengthens communication; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. Describe any required visible image states in `Layout` / `Images`; the suggestion creates no content and Executor may simplify or omit it unless the user explicitly requires motion. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; chart rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
+Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visualization; mark it data-driven when source values determine geometry. §IX stays authoritative without a catalog match and may choose a custom visualization or table. Add `Native shape suggestion` only when a preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name the semantic result plus candidate family or Boolean operands, never implementation geometry or keys. Executor chooses the primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; chart rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
For free-design pages, describe `Layout` through relationships, hierarchy, regions, and column spans; do not prescribe element-level `x`, `y`, `width`, or `height` or duplicate the global geometry in §II/§V. Exact coordinates belong to Executor SVG authoring. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it.
diff --git a/skills/ppt-master/templates/scaffolds/design_spec.md b/skills/ppt-master/templates/scaffolds/design_spec.md
index 8052bca2..8572d78e 100644
--- a/skills/ppt-master/templates/scaffolds/design_spec.md
+++ b/skills/ppt-master/templates/scaffolds/design_spec.md
@@ -21,6 +21,9 @@
| AI Image Acquisition Path | [fill or not applicable] |
| Generation Mode | [fill] |
| Spec Refinement | [fill] |
+| Speaker Notes | [fill enabled/disabled plus provenance] |
+| Custom Animations | [fill enabled/disabled plus provenance] |
+| Narration Audio | [fill enabled/disabled plus provenance] |
| Created Date | {{CREATED_DATE}} |
## II. Canvas Specification
@@ -118,5 +121,6 @@
## X. Speaker Notes Requirements
+- **Generation**: [fill enabled or disabled]
- **Filename**: match each SVG filename under `notes/`
- **Content**: [fill]
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index d6983717..ad1fc2f5 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -194,7 +194,7 @@ The core first chooses the proposed Stage 2 source ids. Load the image module be
|---|---|---|
| `confirm_ui/recommendations.stage1.json` | Communication contract, `content_divergence`, and canvas only | `status: stage1-confirmed` |
| `confirm_ui/recommendations.stage2.json` | Complete deck solution from the confirmed contract; never skip for a template | `status: stage2-confirmed` |
-| `confirm_ui/recommendations.stage3.json` | Production mechanics only: conditional AI path, formula policy, generation mode, refine-spec | `stage: final`, `status: confirmed` |
+| `confirm_ui/recommendations.stage3.json` | Production mechanics only: conditional AI path, formula policy, generation mode, refine-spec, proactive speaker notes, custom animations, and narration audio | `stage: final`, `status: confirmed` |
If the user rejects the current recommendation before confirming it, regenerate by overwriting that same stage file and have the page refresh; do not create revision-suffixed files. This never authorizes one stage file to carry another stage's payload.
@@ -245,6 +245,28 @@ For the normal/default `continuous` path, print no split-mode reminder and proce
**Formula policy**: Stage 3 confirms `mixed`, `render-all`, or `text-only`. When the confirmed policy requires rendering formula-worthy content, load [`strategist-image.md`](../references/strategist-image.md) even if `image_usage` is `none`, and follow its formula-resource contract before filling the planning artifacts. `text-only` creates no formula image rows.
+**Proactive production decisions**: Stage 3 records
+`proactive_speaker_notes`, `proactive_custom_animations`, and
+`proactive_narration_audio`. They control only what the agent initiates when the
+user has not already given an explicit instruction. Resolve each effective
+outcome in this order: latest explicit user instruction → Stage 3 value → fixed compatibility
+default `true` / `false` / `false`. Narration Audio enabled requires Speaker
+Notes enabled without rewriting the raw `proactive_speaker_notes` preference;
+the Speaker Notes provenance then names the enabled Narration Audio dependency.
+Persist the resolved effective outcomes plus provenance as the `Speaker Notes`,
+`Custom Animations`, and `Narration Audio` rows in `design_spec.md §I`; keep the
+raw proactive fields only as confirmation evidence and do not project either
+form into `spec_lock.md`.
+
+**Post-confirmation override**: A later explicit user request changes the
+corresponding effective outcome and provenance directly in
+`design_spec.md §I`, then resumes at its owning Generate step. Do not reopen
+Confirm UI or rewrite unrelated planning decisions. The latest explicit
+instruction remains authoritative over the earlier proactive policy. Enabling
+Narration Audio also recomputes the dependent Speaker Notes outcome and
+provenance. Before entering `generate-audio`, generate `notes/total.md` and run
+Step 7.1 whenever complete per-slide notes are not already present.
+
If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative regenerated image-fact view in the `analysis/` folder, which MUST be read before authoring §VIII:
```bash
python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
@@ -362,7 +384,7 @@ Read references/visual-styles/<resolved-id>.md # one preset id, or each `visu
| At least one placed image has `Status: Sourced` | `executor-web-image.md` after the image branch |
| The locked style/current page calls for noncanonical or alpha paint, dash/cap/join, tracking/decoration/outline, gradient/filter/glow/shadow, path/transform/clipping, or another constructed effect | `svg-effects.md` before authoring that value or effect |
| §IX contains `Native shape suggestion`, or current page construction calls for a literal PowerPoint stock shape, a stock Connector contour, an explicit Merge Shapes operation or result, or a shape-built dimensional form (cylinder/pedestal, layered diagram, reflection, ground plane), or Executor is about to hand-author a freeform not already required by data geometry or the locked organic / hand-drawn style | `native-shape-authoring.md` before selecting or materializing that geometry. This trigger is image-independent: a text-only, data-only, or icon-only page reaches it the same way |
-| All SVG pages and SVG quality gates are complete | `executor-notes.md` before generating speaker notes |
+| All SVG pages and SVG quality gates are complete, and the effective Speaker Notes outcome in `design_spec.md §I` is enabled | `executor-notes.md` before generating speaker notes |
No branch is loaded by analogy. Evaluate these triggers from `spec_lock.md`, §VII/§VIII, the selected style, and the current page plan.
@@ -392,7 +414,22 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Treat §IX `Native shape suggestion` as a candidate, not a command: inspect the actual page construction, then choose the highest-level faithful construction in this order — editable basic primitive, exact Office preset, Merge Shapes Boolean result, and only then a necessary freeform. Load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before materializing an adopted native treatment. Diagram relationships follow the same Shape-first order; do not infer a preset from contour similarity.
-**Motion-ready image composition**: When an adopted §IX `Motion suggestion` or explicit user requirement depends on distinct in-slide image states or cross-slide image continuity, author those visible states now under [`executor-image.md`](../references/executor-image.md). Give each independently revealable or continuing ordinary Slide-local unit a descriptive direct-root `<g id>`; structured atoms/slots retain their declared boundaries and are targetable only when that contract permits. Do not defer required visible content or reshape structure for the later stage. This is SVG preparation, not early animation authoring: effects, pairing, order, and timing remain in the conditional custom stage after notes. A page-transition-only suggestion requires no extra visible layer; deterministic Morph still needs the continuing object as a direct-root group on both pages.
+**Motion-ready image composition**: Only when an explicit user motion
+instruction, the effective Custom Animations outcome in `design_spec.md §I` is
+enabled, or an existing `animations.json` activates custom motion, evaluate §IX `Motion suggestion`
+rows. If the adopted motion depends on distinct in-slide image states or
+cross-slide image continuity, author those visible states now under
+[`executor-image.md`](../references/executor-image.md). Give each independently
+revealable or continuing ordinary Slide-local unit a descriptive direct-root
+`<g id>`; structured atoms/slots retain their declared boundaries and are
+targetable only when that contract permits. Do not defer required visible
+content or reshape structure for the later stage. This is SVG preparation, not
+early animation authoring: effects, pairing, order, and timing remain in the
+conditional custom stage after the final SVG quality gate and any enabled
+speaker-note pass. A Motion suggestion alone does not activate preparation or
+custom animation. A page-transition-only request requires no extra visible
+layer; deterministic Morph still needs the continuing object as a direct-root
+group on both pages.
`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, validate and read back the affected fragments, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.
@@ -435,36 +472,52 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final
- The JSON report is written to `validation/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`.
- **Hard rule — token-safe report handling**: On a successful checker run, use the exit status and terminal summary as gate evidence. Do not open, `cat`, or otherwise load the complete JSON report into model context. Read it only for failure investigation, an explicit audit request, or a field absent from stdout; extract only the required field(s).
-**Logic Construction Phase**: after the SVG quality gate passes, load [`executor-notes.md`](../references/executor-notes.md), ground each page's narration in all information-bearing content in its final SVG, and generate speaker notes → `<project_path>/notes/total.md`
-
-**✅ Internal checkpoint — execution complete**: verify live preview timing, the P01 method gate, uninterrupted remaining-page generation, consolidated repair of any complete failure set, exact §IX roster coverage, one-frame prose wrapping, a final checker result of 0 errors, and `notes/total.md`. Do not print this checklist. Run the applicable conditional gates below, then proceed to Step 7 under the compact status rule above.
+**Logic Construction Phase (conditional)**: after the SVG quality gate passes,
+when the effective Speaker Notes outcome in `design_spec.md §I` is enabled, load
+[`executor-notes.md`](../references/executor-notes.md), ground each page's
+narration in all information-bearing content in its final SVG, and generate
+speaker notes → `<project_path>/notes/total.md`. When the outcome is `disabled`,
+do not load the notes branch and do not require or create `notes/total.md`.
+
+**✅ Internal checkpoint — execution complete**: verify live preview timing,
+the P01 method gate, uninterrupted remaining-page generation, consolidated
+repair of any complete failure set, exact §IX roster coverage, one-frame prose
+wrapping, a final checker result of 0 errors, and `notes/total.md` only when
+speaker notes are enabled. Do not print this checklist. Run the applicable
+conditional gates below, then proceed to Step 7 under the compact status rule
+above.
> **Chart pages?** If this deck contains data charts, run the [`verify-charts`](stages/verify-charts.md) quality-gate stage before Step 7 to calibrate coordinates. Skip if no chart pages.
> **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the [`visual-review`](stages/visual-review.md) quality-gate stage before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.
> **Motion execution (conditional)?** Visible-layer preparation belongs to the
-> main SVG pass above. After `notes/total.md` exists, inspect §IX
-> `Motion suggestion` rows, explicit user motion requirements, and an existing
-> `<project_path>/animations.json`. With none of the three, keep the exporter
-> defaults (`fade` page transition, per-element animation `none`) and load no
-> motion reference. An existing sidecar always runs
+> main SVG pass above. An existing `<project_path>/animations.json` always runs
> [`customize-animations`](stages/customize-animations.md) to validate and
-> resolve preserve/adjust/replace intent before export. With no sidecar, a
-> deck-wide request loads [`animations.md`](../references/animations.md) and
-> resolves Step 7.3 flags; any `Motion suggestion` or per-slide/per-object
-> request runs the custom stage. Strategist owns the communication purpose;
-> Executor owns exact native effects, options, order, timing, and whether a
-> non-literal suggestion should simplify to `none`. Never add motion for
-> coverage or variation.
+> resolve preserve/adjust/replace intent before export. Without a sidecar, run
+> the custom stage only for an explicit per-slide/per-object motion request or
+> when the effective Custom Animations outcome in `design_spec.md §I` is
+> enabled; §IX `Motion suggestion` rows inform that active pass but never
+> trigger it alone. A deck-wide request loads
+> [`animations.md`](../references/animations.md) and resolves Step 7.3 flags
+> without activating the custom stage. Otherwise keep the exporter defaults
+> (`fade` page transition, per-element animation `none`) and load no motion
+> reference. Strategist owns the communication purpose; Executor owns exact
+> native effects, options, order, timing, and whether a non-literal suggestion
+> should simplify to `none`. Never add motion for coverage or variation.
---
### Step 7: Post-processing & Export
-🚧 **GATE**: Step 6 is complete; `svg_output/` contains every final page, `notes/total.md` exists, all required conditional quality gates passed, and the final SVG quality report has 0 errors.
+🚧 **GATE**: Step 6 is complete; `svg_output/` contains every final page, all
+required conditional quality gates passed, and the final SVG quality report has
+0 errors. When the effective Speaker Notes outcome in `design_spec.md §I` is
+enabled,
+`notes/total.md` also exists and covers every page; when it is disabled, notes
+artifacts are not gate requirements.
-🚧 **Image readiness GATE**: When any required resource row is `Needs-Manual`, every expected file and derived slice output MUST exist under `<project_path>/images/` before Step 7.1. If any file is absent, pause and list the exact filenames. After the files arrive, rerun `analyze_images.py`, replace each dashed placeholder in `svg_output/`, reconcile every `no-crop` container to the measured native ratio, then rerun the final SVG quality check so the gate covers the changed sources.
+🚧 **Image readiness GATE**: When any required resource row is `Needs-Manual`, every expected file and derived slice output MUST exist under `<project_path>/images/` before the first active Step 7 sub-step. If any file is absent, pause and list the exact filenames. After the files arrive, rerun `analyze_images.py`, replace each dashed placeholder in `svg_output/`, reconcile every `no-crop` container to the measured native ratio, then rerun the final SVG quality check so the gate covers the changed sources.
After the separate readiness gate above has supplied every required manual file, the final SVG quality check closes each usable terminal §VIII row through `spec_lock.md images`, the exact locked file, and a real `<image href>`; it rejects unplanned/wrong-path references and also validates Sourced provenance/license records, image-specific visible credits, and effective per-placement pixel scale under `meet` / `slice` / `none`.
@@ -474,11 +527,16 @@ After the separate readiness gate above has supplied every required manual file,
#### Step 7.1 — Split Speaker Notes
+Run this sub-step only when the effective Speaker Notes outcome in
+`design_spec.md §I` is enabled:
+
```bash
python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>
```
-**Success criterion**: Per-slide Markdown files exist under `<project_path>/notes/` and cover every published slide.
+**Success criterion**: When enabled, per-slide Markdown files exist under
+`<project_path>/notes/` and cover every published slide. When disabled, skip the
+command and proceed directly to Step 7.2.
#### Step 7.2 — Build the Self-Contained SVG Preview
@@ -490,9 +548,12 @@ python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
#### Step 7.3 — Export the Native PPTX
-```bash
-python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
-```
+Choose exactly one notes mode:
+
+| Effective decision | Command |
+|---|---|
+| Speaker Notes `enabled` | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` |
+| Speaker Notes `disabled` | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --no-notes` |
For deck-wide motion settings, append the resolved flags from
[`animations.md`](../references/animations.md). When the conditional custom
@@ -514,7 +575,7 @@ The command prints a compact `[POSTFLIGHT]` receipt containing `status`, `qualit
## ✅ Generate PPTX Complete
- [x] Image readiness gate passed
-- [x] Notes split completed
+- [x] Notes split completed when enabled; disabled exports used `--no-notes`
- [x] `svg_final/` preview completed
- [x] Native PPTX published and postflight report written
-- [ ] **Next**: Report the exported PPTX path; run a supporting post-export stage only when its explicit trigger is present
+- [ ] **Next**: Report the exported PPTX path; when the effective Narration Audio outcome in `design_spec.md §I` is enabled, run [`generate-audio`](stages/generate-audio.md), otherwise run a supporting post-export stage only when its explicit trigger is present
diff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.md
index 4d62957d..4d543caa 100644
--- a/skills/ppt-master/workflows/governance/failure-recovery.md
+++ b/skills/ppt-master/workflows/governance/failure-recovery.md
@@ -18,7 +18,7 @@ Global stop/continue rules for all four top-level routes, plus concrete failure
| Confirm UI wait timeout | No, if no final result yet | Re-check `result.json` once; keep server cleanup mandatory | Only if user still wants the page | Step 4 same stage or chat fallback |
| Confirm UI Stage 1 completed then interrupted | Yes until Stage 2 is written/confirmed | Read existing Stage 1 `result.json`, create `recommendations.stage2.json` without changing Stage 1, then `--wait-only --wait-stage stage2` | Usually no | Step 4 Stage 2 write/wait |
| Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation |
-| Final confirmed value is missing, changed, substituted, or weakened in `design_spec.md` | Yes | Repair from the retained final-confirmation object; only a fresh recovery turn with no retained state reads persisted final evidence once | Only when the confirmed value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity |
+| Final confirmed value or a later explicit user override is missing, changed, substituted, or weakened in `design_spec.md` | Yes | Repair from the retained final-confirmation object plus any newer explicit instruction; only a fresh recovery turn with no retained state reads persisted final evidence once | Only when the effective value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity |
| `spec_lock.md` changes confirmed identity or omits a required execution anchor/routing decision | Yes | Re-author the affected lock rows from the completed Design Spec and current context; do not enumerate page-local literals | No unless the Design Spec itself is incomplete | Step 4 Gate 2 — lock context fidelity |
| Execution exposes a missing Strategist-owned role/plan detail | Yes for the affected page | Repair affected Design Spec/lock fragments under [`executor-base.md`](../../references/executor-base.md) §2.1 | Only if confirmed intent changes | Step 4 Gate 1/2 → Step 6 current page |
| Execution context is fresh, resumed, restarted, compacted/summary-only, external, or unknown | Yes until rebuilt | Read complete Design Spec, then lock, once; reload triggered inputs and latest completed SVG when mid-deck | No | Step 6 current page |
@@ -34,9 +34,9 @@ Global stop/continue rules for all four top-level routes, plus concrete failure
| Browser annotations submitted during generation | No | Defer application until after Step 7 | User asks to apply annotations | `live-preview` Step 2 |
| `svg_quality_checker.py` error | Yes | Review the complete issue set from one unfiltered run; fix all errors and selected warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, use that complete result as the next batch; never check between individual fixes | No unless required asset is missing | Step 6 Visual Construction |
| `svg_quality_checker.py` warning | No | Continue without mandatory modification or acknowledgement; preserve compatible user syntax, and report material fidelity/quality advice when useful | No | Step 6 advisory warning handling |
-| Missing `notes/total.md` | Yes | Generate speaker notes before Step 7 | No | Step 6 Logic Construction |
+| Missing `notes/total.md` while the effective Speaker Notes outcome is enabled | Yes | Generate speaker notes before Step 7 | No | Step 6 Logic Construction |
| Step 7 image readiness missing manual files | Yes | None for manual assets; list required filenames and prompts | Yes | Step 7 image readiness gate |
-| `total_md_split.py` failure | Yes | Fix notes format/path, rerun only Step 7.1 | Usually no | Step 7.1 |
+| `total_md_split.py` failure while speaker notes are enabled | Yes | Fix notes format/path, rerun only Step 7.1 | Usually no | Step 7.1 |
| `finalize_svg.py` failure | Yes | Fix SVG/assets, rerun Step 7.2 | Only if source asset is missing | Step 7.2 |
| `svg_to_pptx.py` failure | Yes | Fix conversion issue, rerun Step 7.3 | Only if required artifact is missing | Step 7.3 |
| Export succeeds but user wants direct browser edits re-exported | No | Rerun Step 7.2 and Step 7.3 after applied edits | No | Post-export live-preview handling |
@@ -59,11 +59,21 @@ Global stop/continue rules for all four top-level routes, plus concrete failure
**Forbidden — silent downgrade**: Do not skip a required gate because a downstream command might tolerate the missing file, and do not change a confirmed execution value merely to keep the route moving. Fix, pause, or request a new decision at the owning boundary.
+**Proactive production compatibility**: Stage 3 evidence owns the raw
+`proactive_speaker_notes`, `proactive_custom_animations`, and
+`proactive_narration_audio` policies. Resolve the durable effective outcomes in
+this order: latest explicit user instruction → proactive policy → fixed legacy
+default `enabled` / `disabled` / `disabled`. Narration Audio enabled requires
+Speaker Notes enabled without rewriting the raw proactive preference; record
+that dependency as the Speaker Notes provenance. Record each outcome plus its
+provenance in `design_spec.md §I`; never project these values into
+`spec_lock.md`.
+
---
## 3. Generate PPTX Resume Pointers
-Here, **final confirmation evidence** means either the explicit final confirmation in the current chat or `<project>/confirm_ui/result.json` with `status: confirmed` and `stage: final`. Planning artifacts alone do not prove that the user confirmed their values.
+Here, **final confirmation evidence** means either the explicit final confirmation in the current chat or `<project>/confirm_ui/result.json` with `status: confirmed` and `stage: final`. Planning artifacts alone do not prove that the user confirmed their values. After that gate, a newer explicit user instruction may update only its effective production outcome and provenance in the durable Design Spec; resume from the owning step without reopening Confirm UI.
| Last good state | Resume from |
|---|---|
@@ -76,8 +86,9 @@ Here, **final confirmation evidence** means either the explicit final confirmati
| No final confirmation evidence is available | Resume Step 4 from the latest stage evidenced by `confirm_ui/result.json`; if no stage is persisted, restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. |
| `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/resume-execute.md) |
| Images acquired but SVGs not started | [`generate-pptx`](../generate-pptx.md) Step 6 |
-| SVGs complete and checker passed, notes missing | Step 6 Logic Construction |
-| SVGs and notes complete | Step 7.1 |
+| SVGs complete and checker passed; effective Speaker Notes outcome enabled and notes missing | Step 6 Logic Construction |
+| SVGs complete; effective Speaker Notes outcome disabled | Run any applicable conditional motion handling, then Step 7.2 and export with `--no-notes` |
+| SVGs and enabled notes complete | Step 7.1 |
| Step 7.1 complete, export not complete | Step 7.2 |
| Step 7.2 complete, PPTX not complete | Step 7.3 |
| Browser annotations saved after export | [`live-preview`](../stages/live-preview.md) Step 2 |
diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.md
index 11108f6d..ca194f6f 100644
--- a/skills/ppt-master/workflows/native-enhance-pptx.md
+++ b/skills/ppt-master/workflows/native-enhance-pptx.md
@@ -131,14 +131,20 @@ Present the plan to the user before generating notes or audio:
| Module | Recommended default | Confirmation question |
|---|---|---|
-| `notes` | Enabled | Add/replace speaker notes generated from slide content? |
-| `audio` | Enabled when user wants narration/video/autoplay | Generate one narration audio file per slide? |
+| `notes` | Enabled; required whenever audio is enabled | Add/replace speaker notes generated from slide content? |
+| `audio` | Enabled when user wants narration/video/autoplay | After notes are complete, generate one narration audio file per slide? |
| `timings` | Enabled with audio | Set slide auto-advance from audio duration? |
| `transitions` | Enabled, `fade` 0.5s | Add page transitions? Which canonical native effect, Effect Options, and duration? |
| `delivery.check` | Always on, read-only | No confirmation required; review errors and advisories |
**⛔ BLOCKING**: Stop here and wait for explicit user confirmation. Do not generate notes, generate audio, or patch the PPTX until the user confirms the module plan.
+**Hard dependency — notes before audio**: Confirming `audio.enabled: true`
+also requires `notes.enabled: true`. If complete per-slide notes do not already
+exist, run Step 6 and generate them before entering audio configuration or
+audio generation. Never generate narration directly from slide text or bypass
+the notes artifact.
+
**Transition/timing ownership**:
| Confirmed state | Enter transition | Slide advance |
@@ -271,7 +277,8 @@ Record the confirmed config into `project.json`:
## 8. Run the Shared Audio Stage
-🚧 **GATE**: Step 7 confirmed; notes files exist under `<project>/notes/`.
+🚧 **GATE**: Step 7 confirmed; complete non-empty notes files exist under
+`<project>/notes/` for every slide.
Run [`generate-audio`](./stages/generate-audio.md) Step 4 with `<project>` and the confirmed values. Stop after audio generation; do not run its Generate-PPTX-only `svg_to_pptx.py --recorded-narration` integration. This route integrates audio through Step 9 instead.
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index e3439f4f..a66dd2ce 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -53,8 +53,8 @@ route selection. After selection, the route authority owns execution.
| User explicitly requests visual review | Run [`visual-review`](./stages/visual-review.md) before post-processing |
| User requests preview, selection, or annotation application | Run [`live-preview`](./stages/live-preview.md) at the stage defined there |
| User requests page transitions, auto-advance, or deck-wide animation settings without page-specific motion planning or an existing `animations.json` | Load [`animations`](../references/animations.md) and apply its export-level contract |
-| Generate `design_spec.md §IX` contains `Motion suggestion`, `<project_path>/animations.json` already exists, or the user requests per-slide or object-level animation control | Run [`customize-animations`](./stages/customize-animations.md) after notes readiness and before Generate Step 7 |
-| Generated project needs narration audio | Run [`generate-audio`](./stages/generate-audio.md) after notes/export readiness |
+| `<project_path>/animations.json` already exists, the user explicitly requests per-slide/object-level animation control, or the effective Custom Animations outcome in `design_spec.md §I` is enabled | Run [`customize-animations`](./stages/customize-animations.md) after the final SVG quality gate and any enabled speaker-note pass, before Generate Step 7. A §IX `Motion suggestion` informs an active pass but never triggers it alone |
+| Generate PPTX receives an explicit narration request or has effective Narration Audio enabled in `design_spec.md §I`; Enhance Native PPTX has a confirmed `audio.enabled: true` module | Run [`generate-audio`](./stages/generate-audio.md) after the owning route's notes/export readiness; Generate audio implies effective Speaker Notes enabled |
**Hard rule — profile, not fifth route**: The 1:1 beautify behavior uses the same Strategist → Executor → SVG export lifecycle as Generate PPTX. It changes content/page invariants; it does not define a separate artifact lifecycle.
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index ecb66443..9200a5b2 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -5,25 +5,34 @@ description: Optional post-processing stage for per-slide and per-object animati
# Customize Animations Stage
> Optional Generate-PPTX post-processing stage for per-slide or per-object
-> animation control. Run when Design Spec §IX contains at least one
-> `Motion suggestion`, when `<project_path>/animations.json` already exists, or
-> when the user asks to customize slide-specific motion, object order, effects,
-> timing, or reveals. Deck-wide transitions, auto-advance, and deck-wide
-> per-element settings without page-specific motion or an existing sidecar use
-> [`animations.md`](../../references/animations.md) directly and do not activate
-> this stage.
+> animation control. Run when `<project_path>/animations.json` already exists,
+> when the user explicitly asks to customize slide-specific motion, object
+> order, effects, timing, or reveals, or when the effective Custom Animations
+> outcome in `design_spec.md §I` is enabled. Deck-wide transitions,
+> auto-advance, and deck-wide per-element settings without page-specific motion
+> or an existing sidecar use [`animations.md`](../../references/animations.md)
+> directly and do not activate this stage.
## When to Run
| Condition | Action |
|---|---|
-| Design Spec §IX contains at least one `Motion suggestion` | Run this stage after notes exist and before Generate Step 7 |
+| Effective Custom Animations outcome in `design_spec.md §I` is enabled | Run this stage after the final SVG quality gate and any enabled speaker-note pass, before Generate Step 7; use §IX suggestions as advice |
| User asks for per-slide or per-object animation, reveal order, timing, or effect changes | Run this stage |
| `<project_path>/animations.json` already exists | Run this stage to validate it and resolve preserve/adjust/replace intent before export |
-| No suggestion, motion request, or existing sidecar; user only wants the default deck | Do not run; normal export keeps page transitions and no element builds |
+| §IX contains `Motion suggestion`, but no trigger above is active | Do not run; retain the suggestion as Strategist advice and keep normal export defaults |
+| No motion request, enabled outcome, or existing sidecar; user only wants the default deck | Do not run; normal export keeps page transitions and no element builds |
| No existing sidecar; user only wants deck-wide page transitions, auto-advance, or one per-element object animation policy | Do not run; apply [`animations.md`](../../references/animations.md) with exporter flags such as `-a auto` or `-a emphasis_spin` |
| `svg_output/*.svg` is missing | Complete the main Executor phase first |
+**Decision precedence**: Consume the effective Custom Animations outcome already
+persisted in `design_spec.md §I`; Strategist resolves that outcome from the
+latest explicit user instruction, then the Stage 3 proactive policy, then the
+fixed compatibility default `false`. A post-Stage-3 explicit request updates
+only that outcome and its provenance; it does not reopen Confirm UI or add a
+`spec_lock.md` field. An existing `animations.json` always enters this stage for
+preserve/validate handling.
+
---
## 1. Resolve Intent and Read Semantic Context
@@ -42,7 +51,7 @@ description: Optional post-processing stage for per-slide and per-object animati
|---|---|
| Explicit regeneration / rewrite / replacement | Rebuild the semantic grouping plan and replace `animations.json`; the previous choreography is not a constraint |
| Explicit adjustment / tuning / repair | Validate first, preserve the existing choreography where its semantic units remain valid, and migrate affected group references after any required regrouping |
-| Stage activated by new §IX suggestions without a user replacement request | Validate first; preserve valid existing choreography and adjust only the affected semantic units |
+| Stage activated with an existing sidecar and new §IX suggestions but no user replacement request | Validate first; preserve valid existing choreography and adjust only the affected semantic units |
| Existing sidecar with no new motion instruction | Validate and preserve it unchanged; if invalid, repair the owning sidecar/group reference before export |
| Ambiguous generation request | Ask whether to regenerate from scratch or modify the current animation; do not choose on the user's behalf |
@@ -62,13 +71,14 @@ the animation plan merely because it already exists.
**Decision ownership — advice versus requirement**: A §IX
`Motion suggestion` expresses the Strategist's recommended communication job or
-reveal relationship; it does not lock an effect, Effect Options, timing,
-trigger, group id, or coverage. Explicit user motion requirements remain
-mandatory. Executor maps an adopted suggestion to the native registry, may
-adjust its effect/order/timing or choose `none` when motion would reduce
-clarity, and never changes page content merely to justify animation.
-
-**Hard rule — existing visible-layer boundary**: This stage may regroup existing content only under §2 visual equivalence; it MUST NOT create or modify a crop, comparison layer, scrim, lens, hotspot, annotation, or other visible image state to satisfy motion intent. When a required state is missing and ordinary Slide-local authoring can supply it, return to Generate Step 6, rerun the final SVG gate and notes, then resume here. If a structural boundary prevents that repair, simplify a non-binding suggestion to legal existing units, a page transition, or `none`; an explicit requirement follows failure recovery instead of changing structure.
+reveal relationship; it neither activates this stage nor locks an effect,
+Effect Options, timing, trigger, group id, or coverage. Once another trigger
+activates the stage, Executor may adopt, adjust, or decline the suggestion,
+including choosing `none` when motion would reduce clarity. Explicit user
+motion requirements remain mandatory. Never change page content merely to
+justify animation.
+
+**Hard rule — existing visible-layer boundary**: This stage may regroup existing content only under §2 visual equivalence; it MUST NOT create or modify a crop, comparison layer, scrim, lens, hotspot, annotation, or other visible image state to satisfy motion intent. When a required state is missing and ordinary Slide-local authoring can supply it, return to Generate Step 6, rerun the final SVG gate and regenerate notes only when speaker notes are enabled, then resume here. If a structural boundary prevents that repair, simplify a non-binding suggestion to legal existing units, a page transition, or `none`; an explicit requirement follows failure recovery instead of changing structure.
**No-op is complete**: Evaluate suggestions before regrouping SVG content. If
no `animations.json` exists, every page should retain the normal `fade`
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index c61f6baf..48d5941f 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -8,6 +8,18 @@ description: Shared post-processing stage for narration audio, PPTX embedding, a
This stage is **context-independent**: it reads `notes/*.md` and queries the selected TTS voice catalog, so either owning route may invoke it in a fresh session. It does not choose the top-level route and does not patch slide design.
+**Trigger**: In Generate PPTX, run when the effective `Narration Audio` outcome
+in `design_spec.md` §I is `enabled`; a later explicit request first updates that
+outcome and its provenance. In Enhance Native PPTX, run when its confirmed
+enhancement plan has `audio.enabled: true`.
+
+**Hard dependency — speaker notes**: Audio requires complete per-slide speaker
+notes. Generate PPTX additionally requires its effective `Speaker Notes`
+outcome to be enabled; Enhance Native PPTX follows its confirmed notes/audio
+plan, where enabling audio also enables notes. Do not enter audio generation
+while the owning route's notes are missing or incomplete; generate and validate
+those notes first, then resume this stage.
+
## When to Run
- Per-page narration files exist at `notes/*.md`. In Generate PPTX, split `notes/total.md` during Step 7.1. In Enhance Native PPTX, the notes module writes numeric files such as `001.md`.
@@ -30,7 +42,11 @@ This stage is **context-independent**: it reads `notes/*.md` and queries the sel
- Keys may live in the current process environment or the first `.env` found in this order: current working directory, skill directory (e.g. `~/.agents/skills/ppt-master/.env`), clone repo root, `~/.ppt-master/.env`
- The deck is in a single dominant language (mixed-language decks: pick the dominant one — the AI uses judgment, not a heuristic).
-If `notes/*.md` are missing, run `total_md_split.py <project_path>` first.
+If per-slide notes are missing, recover through the owning route. Generate
+PPTX returns to its enabled notes branch and then runs
+`total_md_split.py <project_path>`; Enhance Native PPTX returns to
+`native-enhance-pptx` Step 6 and writes numeric notes directly. Never run the
+Generate splitter against a Native Enhance project.
---
@@ -124,6 +140,13 @@ Send a single message to the user that resolves all five configuration decisions
## Step 4: Execute (no further interaction)
+**Blocking notes preflight**: `notes_to_audio.py` resolves the complete notes
+roster from `svg_output/*.svg` on Generate projects or
+`analysis/slide_index.json` on Native Enhance projects. Before any TTS request,
+every expected note must exist, be readable, and contain spoken text. Exit code
+`2` returns the caller to its notes-generation step; never continue with partial
+audio generation.
+
Run sequentially — do NOT bundle:
```bash
@@ -152,14 +175,16 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider cosyvoice --voice-id <chosen-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 2A. Before derivation, author or refresh narration_timing.json by matching
-# SVG group semantics to SRT topics while preserving animations.json behavior.
-# Reuse current SVG group/content semantics already present in context;
-# otherwise read only the missing or stale svg_output pages.
+# 2A. When animations.json exists, author or refresh narration_timing.json
+# by matching SVG group semantics to SRT topics, then derive the narrated
+# sidecar. Reuse current SVG semantics when complete; otherwise read only
+# the missing or stale svg_output pages.
python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
--narration-padding 0.5 --force
# 2B. Re-export with audio embedded
+# When both animation sidecars are absent, skip 2A: this command keeps the
+# normal fade page transition and no per-element builds.
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
--no-merge --recorded-narration audio --narration-padding 0.5
@@ -195,17 +220,35 @@ If `notes_to_audio.py` errors with a missing dependency or missing provider API
The edge command writes each MP3 and its internal page SRT from the same `edge-tts` stream. SRT cues use the service's `WordBoundary` timing: sentence-ending punctuation always closes a cue; text over the default 20-visible-character limit first splits at commas, semicolons, or colons, then at the nearest word boundary. Override the limit with `--subtitle-max-chars`. Adjacent timing overlap up to 100 ms is tolerated by moving the later cue start to the previous cue end; larger overlap fails instead of silently distorting timing. Each SRT uses a page-local timeline whose origin is `00:00:00,000`, including any leading silence before the first cue. Cloud-provider commands currently write audio only.
-**Mandatory — semantic animation context**: Before writing or refreshing `<project_path>/narration_timing.json`, determine whether the active context already contains the current top-level SVG group IDs and visible group-content semantics for every affected page. Reuse that context without rereading SVG when it is complete and still matches the current `svg_output/`. If any page is missing, stale, or represented only by group IDs/order without content meaning, read only that page's SVG as a read-only source and extract the missing group semantics. Always combine those semantics with the page SRT topics/timestamps and `animations.json`; group order alone is not a semantic narration mapping.
+**Mandatory when `animations.json` exists — semantic animation context**: Before writing or refreshing `<project_path>/narration_timing.json`, determine whether the active context already contains the current top-level SVG group IDs and visible group-content semantics for every affected page. Reuse that context without rereading SVG when it is complete and still matches the current `svg_output/`. If any page is missing, stale, or represented only by group IDs/order without content meaning, read only that page's SVG as a read-only source and extract the missing group semantics. Always combine those semantics with the page SRT topics/timestamps and `animations.json`; group order alone is not a semantic narration mapping.
-> Authoring `narration_timing.json` is not optional polish. When it is absent, `narration_sync.py animations` still runs but maps groups **positionally** (group N → subtitle cue N) and prints a warning listing at-risk slides (those with more cues than objects, where later objects reveal while the narrator is still on an earlier point). Treat that warning as a required-repair signal: author the semantic plan and re-derive.
+> When `animations.json` exists, authoring `narration_timing.json` is not optional polish. When it is absent, `narration_sync.py animations` still runs but maps groups **positionally** (group N → subtitle cue N) and prints a warning listing at-risk slides (those with more cues than objects, where later objects reveal while the narrator is still on an earlier point). Treat that warning as a required-repair signal: author the semantic plan and re-derive.
-**Narration animation ownership**: `animations.json` must already exist and remains read-only. The audio stage deep-copies it to `narration_animations.json`, preserves transitions, effects, durations, order, and explicit `effect: none`, then changes only the derived trigger/delay values needed for click-free narration playback. The authored `narration_timing.json` maps each animated content group to the SRT cue that speaks about that content. The command may still read an affected SVG page to resolve structural group order when a sparse sidecar cannot identify every effective group; this structural fallback does not replace the semantic-context step and never edits SVG, notes, or `animations.json`. Unmatched groups keep their canonical relative delay.
+**Narration animation ownership**: When `animations.json` exists, it remains read-only. The audio stage deep-copies it to `narration_animations.json`, preserves transitions, effects, durations, order, and explicit `effect: none`, then changes only the derived trigger/delay values needed for click-free narration playback. The authored `narration_timing.json` maps each animated content group to the SRT cue that speaks about that content. The command may still read an affected SVG page to resolve structural group order when a sparse sidecar cannot identify every effective group; this structural fallback does not replace the semantic-context step and never edits SVG, notes, or `animations.json`. Unmatched groups keep their canonical relative delay.
-**Title timing handoff**: preserve the title reveal decision already made by the custom-animation pass. Assign a title group to an SRT cue only when the user's request or the active motion plan explicitly chose `narration-cued`; otherwise leave its `cue` omitted in `narration_timing.json` so it keeps the canonical relative delay from `animations.json`. Do not infer `narration-cued` merely because speaker notes mention the title.
+**Title timing handoff when canonical animation exists**: preserve the title reveal decision already made by the custom-animation pass. Assign a title group to an SRT cue only when the user's request or the active motion plan explicitly chose `narration-cued`; otherwise leave its `cue` omitted in `narration_timing.json` so it keeps the canonical relative delay from `animations.json`. Do not infer `narration-cued` merely because speaker notes mention the title.
-**Narrated export animation selection**: `--recorded-narration` defaults to `<project_path>/narration_animations.json` and fails with a repair hint when that file is missing. Pass `--animation-config animations.json` to keep the canonical presentation animation, or `--no-animations` to disable both object animations and page-transition motion while preserving narration audio and recorded slide-advance timings. Non-narrated export keeps its existing optional `<project_path>/animations.json` default.
+**Narrated export animation selection**:
-`<project_path>/narration_timing.json` is the explicit semantic mapping for narrated object animation. It is fingerprinted to the ordered SRT set; `cue` is the 1-based subtitle cue, and omitted `cue` keeps that group's canonical relative delay. Reuse a complete current mapping when its fingerprint and SVG group semantics remain valid; rebuild only affected pages when either input changed.
+| Sidecar state | Behavior |
+|---|---|
+| `narration_animations.json` exists | Use it by default |
+| Only canonical `animations.json` exists | Block until narration synchronization creates the derived sidecar |
+| Both are absent | Create no sidecar; keep the exporter defaults (`fade` page transition, `none` per-element animation) |
+
+Pass `--animation-config animations.json` to keep the canonical presentation
+animation, or `--no-animations` only when the user explicitly wants to disable
+both object animations and page-transition motion while preserving narration
+audio and recorded slide-advance timings. Non-narrated export keeps its
+existing optional `<project_path>/animations.json` default.
+
+When canonical custom animation is synchronized,
+`<project_path>/narration_timing.json` is the explicit semantic mapping for
+narrated object animation. It is fingerprinted to the ordered SRT set; `cue`
+is the 1-based subtitle cue, and omitted `cue` keeps that group's canonical
+relative delay. Reuse a complete current mapping when its fingerprint and SVG
+group semantics remain valid; rebuild only affected pages when either input
+changed.
Get the exact fingerprint value with:
@@ -245,7 +288,7 @@ This stage keeps subtitles as external SRT files. It does not burn subtitles int
| Caller | After audio generation |
|---|---|
-| Generate PPTX | With Edge SRT and an existing `animations.json`, derive `narration_animations.json`, export with `--recorded-narration audio` (derived animation by default; canonical or no-animation modes remain explicit), optionally continue through `powerpoint_video.py`, then generate the delivery SRT from the finished video. |
+| Generate PPTX | With Edge SRT and an existing `animations.json`, derive `narration_animations.json`; with no animation sidecars, keep exporter `fade` / `none` defaults. Export with `--recorded-narration audio`, optionally continue through `powerpoint_video.py`, then generate the delivery SRT from the finished video. |
| Enhance Native PPTX | Return to [`native-enhance-pptx`](../native-enhance-pptx.md) Step 9; its `apply` command owns audio relationships, timings, transitions, and the enhanced export. If video was selected, pass that final PPTX to `powerpoint_video.py`. |
For Generate PPTX, `--recorded-narration audio` prepares PowerPoint's recorded timings and narrations: every slide must have a matching supported audio file, every duration must be readable by `ffprobe`, and object animations must not use `--animation-trigger on-click`. Use `after-previous` or `with-previous` for narrated/video export. Narration changes the slide-advance layer only: the resolved page-transition effect remains unchanged, `-t none` remains visually transition-free, and narration advance disables click while using audio duration plus padding. The re-export is saved as `exports/<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports.
@@ -261,7 +304,7 @@ Output one summary block listing:
- Number of audio files generated and their location (`<project_path>/audio/*`).
- For edge, number of matching page-local SRT files and their location (`<project_path>/notes/subtitles/*`).
- For narrated object animation, whether current SVG semantics were reused or which missing/stale pages were reread, plus semantic mapping coverage and fallback count.
-- For Generate PPTX with Edge SRT, derived narration animation group count and `narration_animations.json` path.
+- For Generate PPTX with Edge SRT and canonical custom animation, derived narration animation group count and `narration_animations.json` path; otherwise report the default `fade` / `none` path.
- When video export was selected, the final MP4 path and native PowerPoint export status.
- When a finished video exists, the final aligned sidecar SRT path.
- The provider, voice, and rate/settings actually used.
diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.md
index fee94df8..5ffa96c4 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -51,17 +51,31 @@ Read skills/ppt-master/workflows/generate-pptx.md
Then jump to `### Step 6: Executor Phase` and run the documented pipeline:
- Read the complete project Design Spec, then the complete `spec_lock.md`, once to establish the fresh execution context
+- Resolve the effective Speaker Notes, Custom Animations, and Narration Audio
+ outcomes from `design_spec.md §I`. Missing legacy outcomes use
+ `enabled` / `disabled` / `disabled`; these production decisions never come
+ from `spec_lock.md`
- If resuming mid-deck, read the latest completed SVG and current image metadata when images are used
- Read the Step 6 flat core (`executor-base`, `shared-standards-core`, and the locked preset mode / visual-style files); for custom directions, reload every optional `*_references` file from `spec_lock.md` before applying the behavior, then only the branches selected by the condition table
- Design Parameter Confirmation
- When structured, read the template Design Spec and each selected prototype once; retain unchanged references in the fresh context. A later bounded repair follows [`executor-base.md`](../../references/executor-base.md) §2.1 only while that context remains valid and uncompacted
- Generate pages sequentially from the retained planning artifacts. Use `page-context` only for the on-demand diagnostic/telemetry triggers in Executor §2.1, never as a routine pre-page load
- Quality Check Gate
-- Speaker notes generation
-- Step 7: Post-processing & Export (`total_md_split` → `finalize_svg` → `svg_to_pptx`)
+- Speaker notes generation only when the effective Speaker Notes outcome is enabled
+- Conditional custom-animation handling under the effective Custom Animations
+ outcome, explicit user instruction, and existing-sidecar rules
+- Step 7: Post-processing & Export (conditional `total_md_split` → `finalize_svg`
+ → `svg_to_pptx`; disabled speaker notes use `--no-notes`)
+- After the base export, run `generate-audio` when the effective Narration Audio
+ outcome is enabled; narration implies speaker notes are enabled
Reload the Generate authority and required execution references; do not reconstruct or replay the earlier planning conversation.
+If the user gives a newer explicit instruction after Stage 3, update only the
+affected effective outcome and provenance in `design_spec.md §I`, then resume at
+its owning step. Do not reopen Confirm UI or add the decision to
+`spec_lock.md`.
+
**Source verification**: the execution session is fresh. Read only the relevant `sources/` passages needed to resolve explicit `Fact IDs` / source references or verify facts, quotes, names, and data required by the current §IX block. Follow [`executor-base.md`](../../references/executor-base.md) §2.1's content-vs-expression contract; source verification never authorizes a second outline. If §IX lacks executable content or evidence, stop and return to Generate Step 4 for Design Spec repair.
> Note: this stage does NOT duplicate Step 6 / Step 7 content. `generate-pptx.md` is the authoritative procedure; resume-execute only adds the resumption entry, sanity check, and source-verification guidance.