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 production overrides and Stage 1 fallback

hugohe3f650a054ae9e
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index 9683db4a..730346cd 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -43,7 +43,7 @@ Global artifact ownership rules for PPT Master projects.
| `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 | 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 |
+| `animations.json` | Optional animation config | Page-transition and object-animation sidecar | Existing files activate intent resolution: Stage 3 `false` preserves, explicit objects-off exports `-a none`, and all-motion-off bypasses with `--no-animations`. Creation requires explicit instruction or enabled outcome; §IX advice never activates it |
---
@@ -68,7 +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`. |
+| Proactive production outcomes | Resolve notes/animation/narration from explicit instruction → Stage 3 → defaults, then persist outcomes/provenance only in Design Spec §I. Explicit notes-off/audio-on applies Generate's dependency gate; Stage 3 animation `false` does not suppress a sidecar. |
**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`.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 0c98427c..7cc2d7a9 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -38,7 +38,7 @@ Do not force communication intent into one catalog label; Stage 1 records compos
>
> **One opt-in exception**: present the refinement line with the split-mode note ([`generate-pptx.md`](../workflows/generate-pptx.md) Step 4). Only explicit opt-in runs [`refine-spec`](../workflows/stages/refine-spec.md): write the Design Spec once, pass Gate 1, then stop before the lock for unrestricted chat revision. Never enter it unprompted.
-> **Default presentation surface — Confirm UI.** Use `<project>/confirm_ui/recommendations.stage1.json`, `.stage2.json`, and `.stage3.json` at their documented handoffs and launch per Generate Step 4. The active, unconfirmed stage may be overwritten when the user asks for a new recommendation; normal progression writes the next stage file and leaves confirmed earlier stages intact. Stage 2 carries ≥3 safe / shifted / bold `design_directions`; each bundles visual style, a six-role HEX palette, CJK + Latin heading/body typography, icons, and conditional image rendering. Also print the recommendations + URL in chat as fallback context. Skip launch only for an explicit chat-only request; a chat-question tool is not a substitute. Generate Step 4 reads the final confirmed `result.json` once and retains that object for Design Spec authoring. [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns schema and lifecycle.
+> **Default presentation surface — Confirm UI.** Use `<project>/confirm_ui/recommendations.stage1.json`, `.stage2.json`, and `.stage3.json` at their documented handoffs and launch per Generate Step 4. The active, unconfirmed stage may be overwritten when the user asks for a new recommendation; normal progression writes the next stage file and leaves confirmed earlier stages intact. Stage 2 carries ≥3 safe / shifted / bold `design_directions`; each bundles visual style, a six-role HEX palette, CJK + Latin heading/body typography, icons, and conditional image rendering. Immediately print the actual URL, current Stage-1 compact summary, and direct-chat fallback line required by `confirm_ui.md`; this context is not confirmation. Skip launch only for an explicit chat-only request; a chat-question tool is not a substitute. Generate Step 4 reads the final confirmed `result.json` once and retains that object for Design Spec authoring. [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns schema and lifecycle.
**Confirmed-value semantics**: confirmation preserves both the value and the owning field's semantic type. Apply the type to the affected property, not automatically to the whole object:
@@ -433,12 +433,12 @@ 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.
+After final confirmation, a newer explicit notes/animation/narration instruction
+updates only affected §I outcomes/provenance and resumes their owner; never
+reopen Confirm UI or add them to `spec_lock.md`. Before editing, apply
+Generate's notes/audio dependency gate. Record animation provenance as
+Stage 3 `false`, explicit objects-off, or explicit all-motion-off; only the last
+includes transitions.
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, 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.
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index b56fe17f..8e2d9174 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -18,6 +18,19 @@
**Fallback rule**: The page is default. Use chat only on explicit chat-only request or launch failure/timeout after one `result.json` re-check; a chat-question tool is not a launch failure. Preserve all three stages and keep Stage-1 prompts open-ended.
+**Always-on Stage-1 chat handoff**: As soon as the healthy daemon prints its
+actual URL, immediately post that URL plus one compact, localized summary of
+the current Stage-1 recommendations: audience, communication intent, audience
+outcome, core message, delivery context, artifact afterlife,
+`content_divergence`, and canvas. Show a blank as “not specified” without
+changing its value. End with an explicit localized line saying that, if the
+page did not open or cannot be reached, the user may revise or confirm the same
+items directly in chat and the same three-stage flow will continue. Keep the
+wait active; do not defer this handoff until launch failure. The handoff is
+context, not confirmation, and silence confirms nothing. After an actual
+launch failure/timeout and the required result re-check, present these same
+items as open Stage-1 chat questions and wait for an explicit response.
+
## `confirm_ui/server.py`
```bash
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index d672b8a2..3d4f00b0 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -623,7 +623,7 @@ Behavior:
- 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
- Without animation sidecars, Generate narration reads base-report deck motion via `--inherit-motion-from`; direct low-level omission keeps legacy `fade` / no object builds. Use `--animation-config animations.json` for canonical animation, or `--no-animations` to remove object/page motion while retaining narration 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 timing merges into the existing slide timing DOM. While motion remains enabled, object-animation rows and the resolved page transition are preserved rather than regenerated; inherited `-a none` suppresses object rows, and `--no-animations` removes both motion layers
- `--narration-audio-dir audio` is the lower-level embedding path: it embeds whatever files match and allows partial audio coverage
- Either narration flag names the default-flow export `<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports in the same directory
- This is intended for direct PowerPoint video export with "Use recorded timings and narrations"
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index cde8c9b2..1fbf7258 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -12,7 +12,7 @@
"skills/ppt-master/templates/schemas/*.json"
],
"exclude": [],
- "max_tokens": 394500
+ "max_tokens": 394750
},
"file_budgets": {
"AGENTS.md": 2400,
@@ -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": 14200,
+ "skills/ppt-master/references/strategist.md": 14225,
"skills/ppt-master/references/strategist-image.md": 2500,
"skills/ppt-master/references/strategist-template.md": 2100,
"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": 13700,
+ "skills/ppt-master/workflows/generate-pptx.md": 13775,
"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800
},
"load_sets": {
@@ -170,7 +170,7 @@
"registry": "visual-styles"
}
],
- "max_tokens": 62000
+ "max_tokens": 62075
},
"route.generate.quick-test": {
"description": "Explicit disposable Generate quick-test short circuit with the shared SVG authoring core.",
@@ -183,7 +183,7 @@
"skills/ppt-master/workflows/profiles/quick-test.md",
"skills/ppt-master/references/shared-standards-core.md"
],
- "max_tokens": 31500
+ "max_tokens": 31550
},
"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": 64225
+ "max_tokens": 64500
},
"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": 87450
+ "max_tokens": 87725
},
"route.generate.flat-ai-two-types": {
"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",
@@ -393,7 +393,7 @@
"profile.generate.beautify-pptx"
],
"files": [],
- "max_tokens": 94400
+ "max_tokens": 94675
},
"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": 111800
+ "max_tokens": 112075
},
"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": 94500
+ "max_tokens": 94750
},
"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": 104425
+ "max_tokens": 104700
},
"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": 104875
+ "max_tokens": 105150
},
"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": 88850
+ "max_tokens": 89125
},
"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": 28825
+ "max_tokens": 28850
},
"stage.generate.video-motion-plan": {
"description": "Conditional resolved animation-to-video handoff contract.",
@@ -698,7 +698,7 @@
"stage.generate.strategist.template"
],
"files": [],
- "max_tokens": 63875
+ "max_tokens": 64150
},
"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 e240ad1f..81f91e06 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -47,7 +47,7 @@ Start with this exact heading order:
| 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> |
+| Custom Animations | <enabled or disabled> — <explicit instruction and object/all-motion scope, 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> |
@@ -204,7 +204,7 @@ Write one ordered Slide block per page. Slide count and order must equal §I `Pa
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.
+placeholders. An explicit notes-off/audio-on conflict blocks before authoring.
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 c2840505..38d7160f 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -204,6 +204,10 @@ If the user rejects the current recommendation before confirming it, regenerate
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait
```
+ When the launch log prints the actual URL, keep the wait active and
+ immediately emit the required Stage-1 chat handoff from `confirm_ui.md`;
+ do not wait for command completion or a browser failure.
+
2. Read the Stage 1 result. Derive proposed image sources in core and load `strategist-image.md` before constructing Stage 2 when its trigger fires; apply `strategist-template.md` when active. Create `confirm_ui/recommendations.stage2.json` without changing Stage 1, then wait:
```bash
@@ -224,7 +228,7 @@ If the user rejects the current recommendation before confirming it, regenerate
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown
```
-If the user opted out of the page but did not delegate confirmation, skip launch and run the same three stages in chat with explicit user responses. If the user explicitly delegated confirmation, consolidate the same three stages into one AI-authored summary and proceed without `result.json`. Otherwise report the launch URL and keep the staged chat summaries available as fallback.
+If the user opted out of the page but did not delegate confirmation, skip launch and run the same three stages in chat with explicit user responses. If the user explicitly delegated confirmation, consolidate the same three stages into one AI-authored summary and proceed without `result.json`. Otherwise use the always-on Stage-1 chat handoff; it keeps the current contract and direct-chat fallback visible without replacing UI confirmation.
⛔ **GATE — final state → Design Spec → conditional review → lock.** Consume every present final value once into the complete, audited `design_spec.md` under [`strategist.md`](../references/strategist.md) §6.2. Preserve each owning semantic type and all production, typography, image-source, and `image_notes` obligations; acceptance never turns a Reference/Permission into a Literal. Do not reopen `result.json`.
@@ -249,23 +253,21 @@ For the normal/default `continuous` path, print no split-mode reminder and proce
`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.
+outcome as latest explicit user instruction → Stage 3 value → compatibility
+default `true` / `false` / `false`. Stage 3 Narration Audio enabled raises a
+non-explicitly-disabled Speaker Notes outcome to enabled and names that
+dependency in its provenance without rewriting the raw proactive preference.
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.
+**Post-confirmation override**: A later explicit request updates only affected
+§I outcomes/provenance and resumes their owning step; do not reopen Confirm UI.
+If it disables Speaker Notes while Narration Audio remains enabled, write
+neither row and ask one question: disable audio too, or retain its required
+notes. Wait, then update both. Before `generate-audio`, create and split notes
+when complete per-slide files are absent.
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
@@ -494,7 +496,7 @@ above.
> **Motion execution (conditional)?** Visible-layer preparation belongs to the
> 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. Without a sidecar, run
+> resolve preserve/adjust/replace/suppress 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
@@ -560,9 +562,11 @@ For deck-wide motion settings, append the resolved flags from
stage preserves or produces `<project_path>/animations.json`, keep the base command above:
the exporter reads the sidecar automatically. Explicit motion flags override
the corresponding sidecar default/slide fields, while group overrides remain
-unless `-a none` hard-disables all object motion; do not mix deck-wide flags
-with a custom sidecar in the normal workflow. With no adopted motion input or
-existing sidecar, preserve the normal `fade` / `none` defaults.
+unless `-a none` hard-disables object motion. Exception: explicit Custom
+Animations disable keeps the sidecar and appends `-a none`; Stage 3 `false`
+does neither. Only explicit all-motion disable uses `--no-animations`.
+Otherwise do not mix deck-wide flags with a sidecar. With no motion input or
+sidecar, preserve `fade` / `none`.
**Success criterion**: The command exits successfully and produces:
diff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.md
index 4d543caa..1adb269b 100644
--- a/skills/ppt-master/workflows/governance/failure-recovery.md
+++ b/skills/ppt-master/workflows/governance/failure-recovery.md
@@ -59,15 +59,12 @@ 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`.
+**Proactive production compatibility**: Keep Stage 3 raw fields as evidence.
+Resolve durable outcomes as explicit instruction → Stage 3 → legacy defaults
+`enabled` / `disabled` / `disabled`. Audio raises Notes only when Notes is not
+explicitly disabled; an explicit notes-off/audio-on conflict stops at
+Generate's one-question dependency gate. Keep raw values unchanged and record
+outcomes/provenance only in Design Spec §I, never the lock.
---
diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.md
index d2f8c3ed..28e86184 100644
--- a/skills/ppt-master/workflows/native-enhance-pptx.md
+++ b/skills/ppt-master/workflows/native-enhance-pptx.md
@@ -125,7 +125,11 @@ If the project already existed or notes/audio coverage changed, refresh the draf
python3 skills/ppt-master/scripts/native_enhance_pptx.py plan "<project>"
```
-Refresh preserves user-owned module enablement, timing padding, global transition settings, and `transitions.slides`; it recomputes file presence/coverage, resets the plan to `draft`, and requires confirmation again. Audio coverage in the plan is explicitly `decodability: unchecked`; `validate` owns the ffprobe gate. CLI flags override only fields explicitly supplied.
+`plan` preserves module settings, refreshes coverage, and emits a
+reconfirmation `draft`. It changes `audio.enabled: true` /
+`notes.enabled: false` to `notes.enabled: true`; `validate`/`apply` reject the
+old state. Audio remains unchecked until `validate` runs ffprobe. Supplied CLI
+flags override.
Present the plan to the user before generating notes or audio:
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index 9200a5b2..1e25a35e 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -19,19 +19,16 @@ description: Optional post-processing stage for per-slide and per-object animati
|---|---|
| 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 |
+| `<project_path>/animations.json` already exists | Run this stage to resolve preserve/adjust/replace/suppress intent before export |
| §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.
+**Decision precedence**: latest explicit instruction → Stage 3 policy →
+compatibility default `false`; provenance stays in Design Spec §I, never the
+lock. Stage 3 `false` blocks creation, not an existing sidecar. Existing
+sidecars enter this stage; explicit disables follow the table without deletion.
---
@@ -49,14 +46,16 @@ preserve/validate handling.
| User intent | Action |
|---|---|
+| Explicit Custom Animations disable | Preserve and validate the sidecar; return `-a none` |
+| Explicit all-motion disable | Preserve and bypass the sidecar; return `--no-animations` |
| 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 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 |
-Whenever an existing sidecar is present, validate it before deciding to
-preserve or modify it:
+Unless explicit all-motion disable bypasses it, validate an existing sidecar
+before deciding to preserve, modify, or suppress object motion:
```bash
python3 skills/ppt-master/scripts/animation_config.py validate <project_path>
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index 26fedae6..b6601271 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -175,7 +175,7 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider cosyvoice --voice-id <chosen-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 2A. When animations.json exists, author or refresh narration_timing.json
+# 2A. When animations.json is active, 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.
@@ -221,11 +221,11 @@ 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 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.
+**Mandatory when `animations.json` is consumed — 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.
-> 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.
+> Active `animations.json` requires `narration_timing.json`; explicit `--no-animations` bypasses both. Without a sidecar, `narration_sync.py animations` maps groups **positionally** (group N → cue N) and warns when later objects may reveal during an earlier topic. Treat that warning as required repair: author the semantic plan and re-derive.
-**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.
+**Narration animation ownership**: When `animations.json` is consumed, 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 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.
@@ -237,9 +237,10 @@ The edge command writes each MP3 and its internal page SRT from the same `edge-t
| Only canonical `animations.json` exists | Block until narration synchronization creates the derived sidecar |
| Both are absent | Create no sidecar; inherit the base report's deck motion |
-Except for explicit `--no-animations`, every Generate narration re-export
-passes the exact base report through `--inherit-motion-from`; missing, stale,
-or narrated reports block. Audio duration plus padding owns final slide advance.
+Generate passes the base report through `--inherit-motion-from`: inherited
+`-a none` preserves explicit objects-off, while Stage 3 `false` does not.
+Only explicit all-motion-off uses `--no-animations`. Invalid reports block;
+audio duration plus padding owns final advance.
When canonical custom animation is synchronized,
`<project_path>/narration_timing.json` is the explicit semantic mapping for
@@ -287,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`; 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. |
+| Generate PPTX | With Edge SRT and an existing `animations.json`, derive `narration_animations.json`; with no sidecar, inherit the base report's resolved motion, while explicit all-motion-off uses `--no-animations`. 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.
@@ -303,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 and canonical custom animation, derived narration animation group count and `narration_animations.json` path; otherwise report the default `fade` / `none` path.
+- For Generate PPTX with Edge SRT and canonical custom animation, derived narration animation group count and `narration_animations.json` path; otherwise report inherited base motion or explicit all-motion-off.
- 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 5ffa96c4..bbf69bf4 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -62,8 +62,8 @@ Then jump to `### Step 6: Executor Phase` and run the documented pipeline:
- 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 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
+- Conditional custom-animation handling under the effective outcome,
+ provenance, explicit 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
@@ -74,7 +74,8 @@ Reload the Generate authority and required execution references; do not reconstr
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`.
+`spec_lock.md`. Before writing, apply Generate's single notes/audio dependency
+gate; at export, apply its sidecar suppression rules.
**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.