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

feat(generate): add conditional video-delivery design

hugohe383f9c8c271bd
diff --git a/AGENTS.md b/AGENTS.md
index a31bfcc4..dedacf85 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,7 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate
- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.
- Raw PPTX cannot be consumed as a Generate template workspace; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated workspace root as a Stage-1 candidate. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.
- Explicit quick/fast or skip-strategy generation may use [`quick-generate`](skills/ppt-master/workflows/profiles/quick-generate.md): prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author `svg_output/`, pass its lockless final checker, and export.
+- Recorded, self-running, or video-directed Generate work conditionally loads [`video-design`](skills/ppt-master/references/video-design.md) inside the selected Default or explicit Quick runtime before page planning. It changes scene, script, and motion design—not the runtime/profile or artifact route.
- PPTX beautify is a strict 1:1 Generate [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), not a separate route. Explicit Quick intent uses the Quick runtime; otherwise it uses Default. Any split/merge/drop/reorder disables Beautify and returns to ordinary Generate in the selected runtime.
- Finished PPTX native enhancement uses [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) and must not enter SVG regeneration.
- [`visual-review`](skills/ppt-master/workflows/stages/visual-review.md), [`customize-animations`](skills/ppt-master/workflows/stages/customize-animations.md), and [`generate-audio`](skills/ppt-master/workflows/stages/generate-audio.md) are supporting stages; their trigger rules remain explicit/conditional.
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index e6e52b6d..9af6d1d5 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -4,7 +4,8 @@ description: >
AI-driven presentation workflow for generating editable PPTX decks, creating
reusable Brand/Style/Layout/Deck workspaces, filling native PPTX templates, and
enhancing finished PPTX files. Use when the user asks to create, regenerate,
- template, fill, or enhance a presentation, or mentions ppt-master.
+ template, fill, or enhance a presentation, requests a presentation-authored
+ narrated/self-running video, or mentions ppt-master.
metadata:
version: "4.5.0"
copyright: "Copyright (c) 2025-2026 Hugo He"
diff --git a/skills/ppt-master/references/executor-notes.md b/skills/ppt-master/references/executor-notes.md
index d99752b4..baf525fa 100644
--- a/skills/ppt-master/references/executor-notes.md
+++ b/skills/ppt-master/references/executor-notes.md
@@ -2,7 +2,7 @@
# Executor Speaker-notes Branch
-Conditional late-stage authority for generating the complete speaker-notes document.
+Conditional late-stage authority for generating or validating the complete speaker-notes document.
**Trigger**: Default Generate loads this after the final quality check when the
effective Speaker Notes outcome in `design_spec.md §I` is enabled. Quick
@@ -15,6 +15,12 @@ create `notes/total.md`.
Write the complete deck to `notes/total.md` in one batch for coherent transitions. Use `# <number>_<page_title>` per page and `---` between pages; only the heading is stripped before TTS.
+**Frozen final-script branch**: when `notes/total.md` already exists because the
+user supplied an explicit final/literal script, do not rewrite it. Retain every
+spoken word and segment boundary; this pass validates script-to-page consistency
+only. A `# Slide <number>` heading is valid before SVG filenames exist and is
+resolved by Generate Step 7.1 after the roster is authored.
+
**Pure spoken narration**: `notes_to_audio.py` reads the body verbatim. Write prose only; never add Markdown list/bullet markup, stage markers, key-point labels, duration lines, or other metadata.
**Length follows content**: size natural sentences to semantic burden. Two to five is typical, not a cap; anchor pages may use less and dense pages more. Honor the active Design Spec or Quick context plus source rules. Duration is pacing guidance only: never pad, repeat, compress, or omit meaning to hit it.
@@ -25,6 +31,13 @@ Write the complete deck to `notes/total.md` in one batch for coherent transition
Before drafting, internally inventory the visible title/subtitle and every information-bearing direct-root `<g id>`; structured placeholder content still counts. Coverage requires its unique claim, evidence, example, relationship, qualifier, or implication—not merely its label—to enter the narration.
+For the frozen final-script branch, apply the same inventory in reverse: every
+independent visible claim or relationship must already be supported by the
+corresponding exact script segment. Repair the visual page or return to planning
+when it is not; never add spoken text merely to make coverage pass. Every spoken
+idea that requires orientation must likewise have a visible state or an explicit
+speech-only role in the active plan.
+
- Text blocks, comparisons, and processes retain every independent fact or relationship; combine related short groups causally or comparatively.
- Charts, tables, and KPIs state the takeaway, decisive values or trend, comparison basis, implication, and material uncertainty—not every axis, row, or cell.
- Quotes retain the decisive clause, material attribution, and relevance. Explain semantic images or text-free diagrams only from the SVG plus locked plan/source; never infer facts from appearance.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index f4750b06..fedbc8f8 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -384,6 +384,13 @@ 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.
+**Prepared final narration**: when the user explicitly marks a script as
+final/literal and intends it for notes or generated audio, preserve its wording
+and order. Segment it by semantic scene while resolving §IX, record its source
+and verbatim policy in §X `Content`, and let Generate write the frozen
+`notes/total.md` only after the final roster and lock pass their gates. Do not
+copy the full script into on-slide `Content` or rewrite it as visible body text.
+
---
## 2. Mode & Visual-Style Catalogs (Reference for Confirmation Item d)
@@ -491,6 +498,7 @@ includes transitions.
| 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 |
+| Explicit final/literal narration script | §IX segments the argument by semantic scene and gives each segment a supporting visible state; §X records the source plus verbatim policy, and Generate freezes the actual segments in `notes/total.md` after Gate 2 |
⛔ **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/references/video-design.md b/skills/ppt-master/references/video-design.md
new file mode 100644
index 00000000..d476ed46
--- /dev/null
+++ b/skills/ppt-master/references/video-design.md
@@ -0,0 +1,177 @@
+# Video-delivery Design Reference Manual
+
+Conditional design guidance for presentations whose intended use is a recorded,
+self-running, or video delivery.
+
+**Trigger**: load this reference when the effective delivery purpose is video,
+recorded narration, or unattended playback. Also load its script rules for an
+explicit final/literal narration input. Speaker notes, animation, audio, or MP4
+export requested for an otherwise ordinary deck do not activate it alone.
+
+**Ownership**: this is a conditional Generate reference, not a profile or a new
+artifact route. Default keeps its Strategist and confirmation flow; Quick keeps
+its one-pass active-context flow. Existing notes, animation, audio, and native
+PowerPoint export stages retain their schemas and commands.
+When Beautify is active, its wording/page/order invariants still bind; apply
+this reference only inside the design and motion freedom that profile permits.
+
+---
+
+## 1. Intake and Script State
+
+Classify supplied spoken material before planning:
+
+| Material | Treatment |
+|---|---|
+| Ordinary source or rough transcript | Use as source material; edit, condense, and reorganize under the selected route's normal content-divergence contract |
+| Explicit final/literal narration script | Preserve every spoken word and its order; segment only at semantic scene boundaries |
+| SRT used to generate new TTS | Preserve cue text when it is explicitly final; use source timecodes only as pacing evidence because the new synthesis timing becomes authoritative |
+| SRT bound to an existing recording | Preserve its text/audio timing authority; do not regenerate TTS or pretend that one long recording was split automatically |
+| Already page-separated final script | Preserve the supplied page boundaries unless the user explicitly permits restructuring |
+| Target platform, canvas, or duration | Use the existing canvas registry; resolve scene granularity, page count, and notes length together |
+
+**Hard rule — final means explicit**: freeze wording only when the user identifies
+the script as final, literal, or verbatim. Never promote ASR output, subtitles,
+or a draft transcript into a literal contract by inference.
+
+**Default — semantic segmentation (may override for a user-authored page
+plan)**: one scene represents one coherent visual state or mental-map step, not
+one sentence, subtitle cue, or effect. Several cues may share a scene; one scene
+may contain several ordered reveals.
+
+**Final-script production input**: after the page roster is final but before SVG
+authoring, write the resolved per-slide script once to `notes/total.md`. Use
+`# Slide <number>` headings and `---` separators so the file can exist before SVG
+filenames do; preserve each body segment verbatim. It is a production input, not
+a storyboard or substitute Design Spec. Run `total_md_split.py` only after the
+SVG roster exists.
+
+---
+
+## 2. Scene and Page Planning
+
+Judge quality by reduced audience understanding cost, not spectacle. Resolve the
+spoken argument, visible evidence, mental map, and motion job together before
+choosing effects.
+
+| Narrative relationship | Page treatment |
+|---|---|
+| Several lines explain one idea | Keep one page/scene and reveal only the semantic units needed for that explanation |
+| One process or system persists | Retain its main roles and relative positions as a stable visual anchor |
+| New evidence expands one part of a known map | Keep the map, enlarge or emphasize the active region, and de-emphasize context only as needed |
+| The same object changes position, scale, containment, or state | Author compatible adjacent endpoints and use the Morph contract when motion is active |
+| The audience must adopt a genuinely new mental map | Start a new composition and make the transition explicit |
+
+**Default — stable visual anchors (may override when the subject resets)**:
+within one explanation, keep recurring roles, relative positions, and governing
+structure stable. Prefer moving, enlarging, revealing, or dimming within that
+map over replacing the entire layout at every beat.
+
+**Default — one semantic focus change per beat (may override for one inseparable
+idea)**: several elements may change together only when they communicate one
+unit. Do not change unrelated title, diagram, annotation, and footer regions at
+the same moment merely to make the frame busier.
+
+**Default — screen for orientation, notes for speech (may override for literal
+on-screen copy)**: place keywords, structure, evidence, and relationships on the
+slide; keep full explanation in notes. Do not duplicate the narration script as
+body copy.
+
+**Page-count rule**: derive page count from semantic scenes, visual-state
+endpoints, and target duration. Never derive it from subtitle-cue or sentence
+count.
+
+---
+
+## 3. Default and Quick Planning Handoff
+
+**Default**: Stage 1 confirms the existing open-text `delivery_context`; it does
+not ask a separate video question. When the confirmed value identifies
+recorded/self-running/video delivery, load this reference before authoring the
+three Stage-2 whole solutions. Apply its scene grammar to every direction; it
+does not add a style catalog or confirmation field. Record delivery context and
+afterlife in §I, visible states and optional motion jobs in §IX, and script/notes
+policy plus target duration in §X. When the final-script branch is active,
+create the frozen `notes/total.md` after the approved roster/lock is final and
+before Step 5 or split-mode handoff.
+
+**Default — reading mode (may override for durable close reading)**: recorded
+explanation leans `presentation`; choose `balanced` when close-reading afterlife
+materially outweighs video delivery.
+
+**Quick**: there is no Stage 1 or separate video-purpose confirmation. Explicit
+video/recorded/self-running intent activates this reference after source
+sufficiency is known and before the one-pass roster, resource, and motion
+decisions; absent that intent, keep ordinary Quick behavior. Load the script
+rules alone when an explicit final/literal narration will become notes/audio.
+Keep the applicable scene grammar and final-script handling in active context.
+A pre-SVG `notes/total.md` is an enabled production artifact, not a forbidden
+planning checkpoint; Quick still creates no root Design Spec, lock,
+confirmation payload, or storyboard.
+
+**Production outcomes**:
+
+| Need | Decision |
+|---|---|
+| Spoken delivery or a supplied final script | Enable Speaker Notes |
+| User asks the workflow to synthesize narration | Enable Narration Audio; Speaker Notes is its dependency |
+| Progressive reveal, continuing geometry, or timed emphasis materially aids explanation | Enable/load the appropriate animation capability |
+| Video is manually narrated or static playback is sufficient | Keep Narration Audio and/or object animation off as applicable |
+
+**Capability boundary**: video purpose does not force object animation or
+generated audio. Explicit user instructions and the selected runtime's ordinary
+production-decision precedence remain authoritative.
+
+---
+
+## 4. SVG, Notes, and Motion Realization
+
+When `notes/total.md` contains a frozen final script, read it once before the
+first SVG and design each page around its corresponding spoken segment. Give
+every independently narrated or timed semantic unit a descriptive direct-root
+`<g id>`; keep inseparable units grouped.
+
+**Hard rule — script/design consistency**: a final script is literal content.
+If the finished visual page introduces an independent claim or relationship the
+script does not explain, repair the page or return to planning; never rewrite or
+pad the final script during the late notes pass. Conversely, every spoken idea
+that requires visual orientation must have a visible state or deliberate
+speech-only treatment.
+
+**Motion readiness**: load `animations.md` before SVG authoring whenever the
+plan needs compatible Morph endpoints or page/object-specific motion. Author
+every required start/end state and real semantic group before the final checker;
+post-processing cannot invent missing visual endpoints or target IDs.
+
+**Motion restraint**: use transitions, reveals, emphasis, and Morph only for a
+named communication job. There is no motion-coverage quota, and `effect: none`
+remains valid. Auto-running narration uses `after-previous` / `with-previous`,
+never `on-click`.
+
+**Sound effects**: add them only on explicit request and only from prepared,
+project-local assets. Do not introduce sound search, trimming, or normalization
+as an implicit video step.
+
+**Production sequence**: after the final SVG check, the notes branch validates a frozen final script
+against the visible pages without rewriting it. Draft-source runs instead use
+the ordinary final-SVG-grounded notes generation. Both paths then split notes,
+run any triggered custom-animation stage, export the canonical editable PPTX,
+and invoke `generate-audio` only when narration synthesis is enabled.
+
+---
+
+## 5. Delivery Boundary
+
+**Canonical artifact**: the editable PPTX remains canonical. `generate-audio` owns provider/voice/rate
+selection, page audio/SRT generation, semantic narration timing, narrated PPTX
+export, and optional native PowerPoint video export.
+
+**Conditional MP4**: run `powerpoint_video.py --check` only when MP4 delivery is
+selected. If native Windows PowerPoint export is unavailable, keep the narrated
+PPTX as the successful upstream artifact; do not substitute screenshots, HTML,
+or a third-party renderer and call it equivalent.
+
+**Current boundary**: importing and automatically splitting one long finished
+recording is unsupported. Require page-level audio or an explicit page/time map;
+otherwise deliver the designed deck and frozen notes without claiming audio
+integration.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 8dd9d29d..97945a74 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -49,7 +49,7 @@
"skills/ppt-master/SKILL.md",
"skills/ppt-master/workflows/routing.md"
],
- "max_tokens": 6750
+ "max_tokens": 7750
},
"support.sponsor-recommendation.en": {
"description": "English sponsor context for explicit user requests for model, AI image model, API/provider, or hosted-service recommendations.",
@@ -258,6 +258,19 @@
"files": [],
"max_tokens": 100000
},
+ "route.generate.quick-generate.video-design": {
+ "description": "Quick Generate with conditional video-delivery design, frozen-script notes, custom animation, and narration/audio delivery.",
+ "scope": "cumulative",
+ "include": [
+ "route.generate.quick-generate",
+ "stage.generate.video-design",
+ "stage.generate.executor.notes",
+ "stage.generate.customize-animations",
+ "stage.shared.generate-audio"
+ ],
+ "files": [],
+ "max_tokens": 140000
+ },
"route.generate.quick-generate.template-fusion": {
"description": "Quick Generate with the maximum Brand, Style, Layout, and Deck exact-root fusion loaded for flat authoring.",
"scope": "cumulative",
@@ -570,6 +583,18 @@
"files": [],
"max_tokens": 175000
},
+ "route.generate.flat-no-image.video-design": {
+ "description": "Default flat Generate-PPTX path with conditional video-delivery design, custom animation, and narration/audio delivery.",
+ "scope": "cumulative",
+ "include": [
+ "route.generate.flat-no-image",
+ "stage.generate.video-design",
+ "stage.generate.customize-animations",
+ "stage.shared.generate-audio"
+ ],
+ "files": [],
+ "max_tokens": 215000
+ },
"route.generate.flat-no-image-visualization": {
"description": "Default flat Generate-PPTX path with visualization-reference consumption, all three information-model branches, optional native-data replacement, and chart verification.",
"scope": "cumulative",
@@ -773,6 +798,14 @@
],
"max_tokens": 7750
},
+ "stage.generate.video-design": {
+ "description": "Conditional recorded/self-running delivery design and prepared final-script handling shared by Default and Quick.",
+ "scope": "incremental",
+ "files": [
+ "skills/ppt-master/references/video-design.md"
+ ],
+ "max_tokens": 2250
+ },
"stage.generate.refine-spec": {
"description": "Explicit post-confirmation spec refinement runbook.",
"scope": "incremental",
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 94ed63c4..d657d3dc 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -216,6 +216,10 @@ When Speaker Notes is disabled, keep §X with only
`- **Generation**: disabled`; do not write filename, duration, style, or purpose
placeholders. An explicit notes-off/audio-on conflict blocks before authoring.
+When an explicit final/literal narration script will become notes or generated
+audio, make §X `Content` name that source and say `preserve verbatim`; keep the
+full segmented script in `notes/total.md`, not in §IX or this Design Spec.
+
Append either or both optional lines only when the capability earns a place;
never write an empty or `none` placeholder:
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index a90885c2..e2779e1f 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -254,6 +254,7 @@ Then load only the extra role modules triggered by the current plan:
| Deterministic trigger | Additional Strategist reference |
|---|---|
| Stage 1 is confirmed and its template choice installed a selected Brand/Style/Layout/Deck workspace into this project | `references/strategist-template.md` before Stage 2 |
+| The confirmed Stage-1 `delivery_context` identifies recorded/self-running/video delivery, or input is an explicit final/literal narration script | `references/video-design.md` before the three Stage-2 whole solutions and page roster |
| The confirmed Stage 2 `image_usage` contains a source other than `none`, the user supplied an explicit non-`none` image constraint, or formula-worthy content activates formula planning | `references/image-layout-spec.md` + `references/image-layout-patterns.md` before production detail, formula resources, or §VIII |
After Stage 1 and template handoff, load `strategist-image.md` plus only the
@@ -448,6 +449,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
**Output**:
- `<project_path>/design_spec.md` — complete human-readable design narrative and durable confirmed production state
- `<project_path>/spec_lock.md` — machine-readable stable execution anchors/routing, authored after conditional review approval
+- `<project_path>/notes/total.md` — only when the prepared final narration branch is active; frozen verbatim production input
For a new project, use the reference-first whole-document sequence:
@@ -459,6 +461,13 @@ For a new project, use the reference-first whole-document sequence:
Final state → initial Design Spec mismatch, approved Design Spec/context → lock mismatch, or an unapplied revision blocks despite schema validity. `validate` does not prove fidelity. Repair from retained confirmation before refinement; during it, preserve unaffected values and apply explicit revisions. After approval, derive the lock from that Design Spec/context. Resume/refine edits existing files, never scaffolds. Fresh recovery alone may reread persisted final evidence once.
+**Prepared final narration branch**: follow `video-design.md` §1 and §3 when an
+explicit final/literal script will become notes or generated audio. Segment it
+by semantic scene during Stage 2; §IX gives each segment a supporting visible
+state and §X records its source/verbatim policy. After Gate 2, before Step 5 or
+split handoff, write the exact segments once to `notes/total.md`; split them only
+in Step 7.1. This is frozen production input, not a third planning artifact.
+
**✅ Internal checkpoint — Phase deliverables complete**: facts read; confirmation consumed once; final Stage-2 production fields resolved (formula policy, generation mode, refine-spec, proactive choices, and conditional AI path); Design Spec passed Gate 1; enabled refinement approved; lock derived from it; split handling resolved; communication and every §IX `Audience move` validated. Do not print this checklist; auto-proceed.
---
@@ -529,6 +538,10 @@ Workflow:
**Page content**: §IX is preferred wording and semantic authority. Use it when it works; adapt it when presentation benefits while preserving intent, facts, and explicit literal requirements. Read sources only to verify requested evidence; return incomplete blocks to Step 4 instead of enriching them during execution.
+**Prepared final narration**: when §X records a literal script, read the frozen
+`notes/total.md` once before P01 and design each visible state/semantic group
+around its exact segment; never edit or pad it.
+
**Planning context**: follow [`executor-base.md`](../references/executor-base.md) §2.1. Reuse the complete Design Spec and lock in an unchanged, uncompacted context. Fresh/resumed/restarted, compacted/summary-only, or externally/unknown changed execution reads both once and reloads triggered inputs. For a local question, consult the retained lock first, then only the owning Design Spec fragment; do not poll files merely to prove validity.
**Artifact ownership**: `svg_output/` is the author source, `svg_final/` is derived, and image facts come from the regenerated `analysis/image_analysis.csv`; see [`references/artifact-ownership.md`](../references/artifact-ownership.md).
@@ -561,6 +574,7 @@ Keep the core's shared visual-quality defaults and `svg-effects.md` §6.1 Visual
| Used preset pattern fill, or independent Chart/Table with §IX `<object-key>=yes` | `native-data-interface.md` before that object |
| `spec_lock.md images` / §VIII has an image/formula row, or the template has bundled images | `executor-image.md` + `image-layout-spec.md` + `image-layout-patterns.md` + `svg-image-embedding.md` |
| At least one placed image has `Status: Sourced` | `executor-web-image.md` after the image branch |
+| §I records recorded/self-running/video delivery, or §X records a final/literal narration script | `video-design.md` before the first SVG; retain it through notes/motion handling |
| 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. For each page, after §IX content/communication
@@ -661,10 +675,13 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final
**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`.
+[`executor-notes.md`](../references/executor-notes.md). When the prepared final
+narration branch already created `notes/total.md`, validate its exact segments
+against every information-bearing final SVG group and repair the visual page or
+upstream plan on mismatch; never rewrite the script. Otherwise ground each
+page's narration in its final SVG and generate complete 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
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index 11f4b9cc..85c63bed 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -106,6 +106,13 @@ require inventing, omitting, or leaving unsupported an externally verifiable
claim. File presence or length does not establish sufficiency. Research gathers
facts only; image acquisition remains part of the resource preparation below.
+**Conditional video-delivery context**: when the intended use is recorded,
+self-running, or video-directed—or an explicit final/literal narration script
+will become notes/audio—read
+[`video-design.md`](../../references/video-design.md) now and retain it through
+roster, SVG, notes, and motion decisions. This changes neither the Quick profile
+nor its artifacts.
+
Before initialization, resolve exactly one template branch:
- **Direct template application**: one or more exact current workspace roots
@@ -227,6 +234,7 @@ checkpoint, or persist a page/resource plan.
Before writing P01, resolve in active context:
- the exact slide roster and one compact core message for every page, used to choose its composition and hierarchy;
+- the effective Speaker Notes, Custom Animations, and Narration Audio outcomes; generated narration requires notes, while video purpose alone forces neither audio nor object animation;
- the canvas, visual direction, palette, wording, and one concrete typography plan using installed font families, with stable size anchors for title, body, annotation, and every other recurring role the roster uses; explicit user, template, or resolved-style requirements may call for a deliberate exception;
- an ordinary body-content frame and a density judgment for every page, adapted to the canvas and any user / template / style geometry; use `anchor`, `dense`, `breathing`, or an equivalent active-context distinction instead of one uniform fill level;
- for each page not bound to literal supplied geometry, a primary visual zone and page-scale composition direction tied to its core message; use cards or equal grids when the content relationship calls for them, not as the automatic page grammar;
@@ -242,6 +250,15 @@ Before writing P01, resolve in active context:
otherwise choose the registered automatic/default path without another
interaction.
+**Prepared final narration**: when the user explicitly marks a script as
+final/literal and intends it for notes or generated audio, segment it by semantic
+scene while resolving the roster and preserve every spoken word. Before writing
+P01, write the ordered segments once to `notes/total.md` with
+`# Slide <number>` headings and `---` separators. Keep that file as exact
+production input for page design; it is not a planning checkpoint. Do not split
+it until the SVG roster exists. Draft narration instead remains source material
+and uses the ordinary post-SVG notes branch when notes are enabled.
+
**Mandatory — subject-layer capability scan**: Before resource preparation,
inspect the intended layer relationship rather than treating every reference
visual as one flat image. When a subject crosses a native title, panel, frame,
@@ -418,6 +435,11 @@ Keep the core's shared visual-quality / leading defaults and `svg-effects.md` §
**Per-page execution anchors**: apply the transient core-message, typography-role, body-frame, density, and composition anchors resolved in §2 while authoring; they guide the current run without creating a persisted planning artifact.
+When `notes/total.md` was frozen from a final script, retain its corresponding
+segment while authoring each page. The visible state and real direct-root
+semantic groups must support that spoken segment without duplicating the full
+script as body copy or changing its wording.
+
Use one zero-padded filename width sized for the resolved roster, such as
`01_cover.svg` through `12_end.svg` or `001_cover.svg` through `120_end.svg`.
Never reuse pages from another run: the exporter publishes every SVG discovered
@@ -473,15 +495,37 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> \
Fix every blocking error and rerun the same command. Then export:
+When Speaker Notes is enabled, load
+[`executor-notes.md`](../../references/executor-notes.md) after the passing final
+check. Validate an already frozen final script without rewriting it; otherwise
+generate `notes/total.md` from the final SVG roster. Then run:
+
+```bash
+python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>
+```
+
+Run [`customize-animations`](../stages/customize-animations.md) after that notes
+pass when the active-context outcome or an existing sidecar triggers it. Resolve
+deck-wide-only motion through the selected exporter flags instead.
+
+Choose exactly one notes mode for the base export:
+
```bash
+# Speaker Notes enabled
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --quick-generate
+
+# Speaker Notes disabled
+python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> \
+ --quick-generate --no-notes
```
`--quick-generate` reads `svg_output/` as the page source and resolves the
project-local assets referenced by those SVGs. It infers one consistent canvas,
uses a lockless flat PowerPoint package, and does not force-disable ordinary
export options. Notes, custom object animation, and narration remain off unless
-selected by the agent. Do not run `finalize_svg.py`.
+selected by the agent. Do not run `finalize_svg.py`. After the validated base
+export, run [`generate-audio`](../stages/generate-audio.md) when Narration Audio
+is enabled; it owns page audio/SRT, narrated PPTX, and optional native MP4.
The exporter requires a passing `final` report whose SVG fingerprint matches
the current `svg_output/`; missing, blocking, non-final, or stale reports stop
@@ -502,7 +546,8 @@ or lock.
- [x] Every role declared by an installed template spec is locatable in the finished pages, or its non-use is deliberate — checked per installed spec, not from memory
- [x] Every triggered capability-specific preparation and pre-checker verification completed
- [x] The lockless final SVG quality report passes and matches the current SVGs
+- [x] Enabled notes were validated/generated and split; enabled custom motion ran through its owning stage
- [x] One native PPTX exists under `exports/` or the explicit output path
- [x] No Strategist, confirmation, root project Design Spec, or lock artifact was created
-- [ ] **Next**: Report the PPTX path
+- [ ] **Next**: Report the base PPTX and any enabled narrated PPTX/MP4 outputs
```
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index cef01e4c..a458a0d1 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -30,7 +30,7 @@ route selection. After selection, the active runtime authority owns execution.
| Route | Request shape | Authority | Preconditions | Mutation model | Output contract |
|---|---|---|---|---|---|
-| Generate PPTX | Create a new presentation; regenerate an existing deck visually; use source material or a topic; optionally select a registered library template or supply an explicit workspace | Beautify: [`beautify-pptx`](./profiles/beautify-pptx.md), which selects Default or Quick; ordinary Default: [`generate-pptx`](./generate-pptx.md); ordinary explicit Quick: [`quick-generate`](./profiles/quick-generate.md) | Source facts exist or research can gather them; explicit quick intent activates its runtime | Author new SVG pages and export a new PPTX | Default: spec, lock, SVG, validation, and PPTX; Quick: optional source/resource artifacts, no spec/lock, SVG, and one PPTX |
+| Generate PPTX | Create a new presentation or presentation-authored video; regenerate an existing deck visually; use source material or a topic; optionally select a registered library template or supply an explicit workspace | Beautify: [`beautify-pptx`](./profiles/beautify-pptx.md), which selects Default or Quick; ordinary Default: [`generate-pptx`](./generate-pptx.md); ordinary explicit Quick: [`quick-generate`](./profiles/quick-generate.md) | Source facts exist or research can gather them; explicit quick intent activates its runtime | Author new SVG pages and export a new PPTX | Default: spec, lock, SVG, validation, and PPTX; Quick: optional source/resource artifacts, no spec/lock, SVG, and one PPTX; either runtime may derive narrated PPTX/MP4 delivery through existing stages |
| Create Template | Create a reusable brand/style/layout/deck template from one or more PPTX/SVG files, images/PDFs, direct or file-based text, documents/websites, brand assets, or a mixed reference bundle | [`create-template`](./create-template.md) | A reusable-template request exists; reference material is optional, and project scope additionally requires an initialized target project | Author a new portable workspace; never modify any reference file in place | Workspace with required `templates/`, optional `images/` / `icons/`, and optional review `exports/` |
| Fill Native PPTX | Use a raw PPTX's native slide shells and replace/fill content | [`template-fill-pptx`](./template-fill-pptx.md) | Source PPTX plus new material/topic | Clone and patch PPTX through OOXML; no SVG pipeline | New filled PPTX in project `exports/` |
| Enhance Native PPTX | Keep a finished PPTX's visible slides stable while adding notes, audio, timings, or transitions | [`native-enhance-pptx`](./native-enhance-pptx.md) | Finished source PPTX exists | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX in project `exports/` |
@@ -42,9 +42,10 @@ route selection. After selection, the active runtime authority owns execution.
| Request condition | Generate-route behavior |
|---|---|
| Existing PPTX must preserve wording, page count, and page order 1:1 | Activate [`beautify-pptx`](./profiles/beautify-pptx.md); it selects `quick-generate` when that profile's explicit trigger also matches, otherwise `generate-pptx` |
+| The effective delivery purpose is recorded, self-running, or video-directed | Inside the already selected Default or explicit Quick runtime, load [`video-design`](../references/video-design.md) before whole-solution/page planning. This is a conditional design reference, not a profile or fifth route; notes, animation, audio, and optional native MP4 remain owned by their existing stages |
| Explicit quick/fast, skip-strategy, or direct SVG-to-PPTX intent without Beautify | Load [`quick-generate`](./profiles/quick-generate.md) directly without loading `generate-pptx.md`: prepare sources/resources as needed, let the current agent decide without interaction, directly apply at most one exact workspace root per kind supplied for this run, otherwise use free design, omit Strategist/Confirm UI/spec/lock, hand-author SVG, run the lockless final checker, and export the final PPTX |
| Topic only, or supplied sources leave planning-critical factual gaps | Run [`topic-research`](./stages/topic-research.md) inside the selected Generate profile's source preparation: immediately for topic-only input, or after conversion and reading for source-backed input; research only the identified gaps |
-| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through the selected Generate authority's source intake; continue the default pipeline unless explicit Quick Generate intent selected that profile |
+| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through the selected Generate authority's source intake; continue Default unless explicit Quick intent selected that runtime |
| Default Generate reaches planning | Step 3 prepares template candidates without interaction. Stage 1 then confirms the communication contract and free-design/template choice together; only a confirmed non-free choice runs [`apply-template-workspace`](./stages/apply-template-workspace.md) before Stage 2 |
| Explicit current brand/style/layout/deck workspace root | Default Generate preserves the exact path as a Stage-1 template candidate; Quick Generate validates and installs it directly without Steps 3–4 or Confirm UI. Classify it as `library` only when its normalized root exactly matches a registered index entry; otherwise retain `explicit`. Consume the workspace root, never only its inner `templates/` directory |
| Split-mode project resumes in a fresh chat | Run [`resume-execute`](./stages/resume-execute.md) inside the active Generate route |
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index 4855c0ee..c134ddcb 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -27,6 +27,8 @@ this stage.
- 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`.
- Default mode: `edge-tts` is installed (`python3 -m pip install edge-tts`).
- The stage is page-level only: one note becomes `audio/<stem>.<audio-ext>` plus `audio/<stem>.srt` on provider-timed paths, or one audio file with Qwen / explicit CosyVoice audio-only mode. Never substitute one long track or automatic splitting.
+- Final/literal script notes are synthesized verbatim. Source SRT timecodes are pacing evidence only; new provider timing owns the generated audio/SRT set.
+- SRT bound to an authoritative existing recording does not enter TTS. Recorded narration requires page-level audio or an explicit page/time map; automatic long-track splitting is unsupported.
- A fully successful run writes a compact `audio/manifest.json` with only provider/model, audio/subtitle format, relevant voice settings, and a SHA-256 fingerprint instead of the raw cloud voice ID. It has no per-slide inventory, artifact hashes, or API keys and is not a normal generation input. The flat `audio/` directory is the single active narration set; do not create provider subdirectories unless the user explicitly asks to preserve multiple variants.
- PPT narration assets must be PowerPoint-reliable audio: `m4a` (AAC), `mp3`, or `wav`. The built-in TTS path defaults to `mp3`; provider formats such as `pcm`, `opus`, or `flac` must be transcoded before embedding.
- PowerPoint recorded narration export requires `ffprobe` so slide timings can be written from actual audio duration.
diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.md
index ade7ec5a..141d7aca 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -37,6 +37,7 @@ Verify the project's planning-session artifacts before doing anything else:
|---|---|---|
| `<project_path>/spec_lock.md` | Always | Strategist's execution anchors and routing contract; read it completely once in this fresh execution context |
| `<project_path>/design_spec.md` | Always | Complete approved design narrative and Section IX page outline; read it completely once in this fresh execution context |
+| `<project_path>/notes/total.md` | Design Spec §X records a supplied final/literal narration script | Frozen verbatim narration input; read it once before SVG authoring and never reconstruct it from the planning chat |
| `<project_path>/images/` plus files whose row status requires existence | `spec_lock images` references any image | `Existing` / `Generated` / `Sourced` / `Rendered` files must exist; an absent `Needs-Manual` file remains allowed until the Step 7 readiness gate |
| `<project_path>/templates/` | `spec_lock page_layouts` references any | Layout / mirror prototypes required by execution |
| Resolver-returned Chart/Table SVG | `spec_lock page_visualizations` or legacy `page_charts` references a live Chart/Table key | Shared page-local SVG selected through the two live catalogs |
@@ -62,6 +63,7 @@ recover its relationship from §IX, or return to Step 4 when §IX is insufficien
If any required artifact is missing, report it and stop this stage. Do not enter Step 6 or invent a replacement artifact. Recover by artifact owner:
- Missing `design_spec.md` / `spec_lock.md` → use [`failure-recovery.md`](../governance/failure-recovery.md) §3.
+- Missing frozen `notes/total.md` when §X declares a final/literal script → return to Generate Step 4's prepared final narration branch; never rewrite the script from memory.
- Missing `images/`, or a file whose status requires existence → recover by provenance: an `Acquire Via: user` / `Status: Existing` file is a required manual artifact, so use `failure-recovery.md` §2 and wait for the user to restore that exact file; a template-bundled bitmap returns to [`generate-pptx`](../generate-pptx.md) Step 3 to restore the selected workspace; an AI, web, formula, or slice output uses its matching row in `failure-recovery.md` §1 to reacquire, rerender, or derive it. An absent `Needs-Manual` file is not a Step 1 failure.
- Missing `templates/` inputs → restore the selected workspace through [`generate-pptx`](../generate-pptx.md) Step 3 and [`apply-template-workspace`](apply-template-workspace.md). If the workspace is unavailable or invalid, run Create Template again rather than reconstructing a template inside this stage.
@@ -76,6 +78,7 @@ 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
+- When §X records a final/literal narration script, read the frozen `notes/total.md` once and retain its page segments through SVG authoring and the late notes validation
- Resolve the effective Speaker Notes, Custom Animations, and Narration Audio
outcomes from `design_spec.md §I`. Missing outcomes use the workflow defaults
`enabled` / `disabled` / `disabled`; these production decisions never come