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

refactor(workflow-spec): extract routing, registry, artifact, and recovery authorities

hugohe358f9284a9284
diff --git a/CLAUDE.md b/CLAUDE.md
index a5837ae7..35e3b995 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,7 +12,9 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
> Topic-only requests with no source material: run the standalone [`topic-research`](skills/ppt-master/workflows/topic-research.md) workflow before SKILL.md Step 1 to gather web materials.
>
-> Template fill: when the user provides an existing `.pptx` template plus text materials or a topic and asks to reuse the original PPT design or fill content back into it (for example, "fill this deck with the new content", "fill this back into the template", or "reuse this deck's design"), run the standalone [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md) workflow. This route edits PPTX directly and must not enter the SVG generation pipeline.
+> Template fill: when the user provides an existing `.pptx` template plus text materials or a topic and asks to generate a `.pptx` from that raw template, run the standalone [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md) workflow. This route treats the PPTX as a native slide library, edits PPTX directly, and must not enter the SVG generation pipeline.
+>
+> Template creation boundary: a `.pptx` may enter the main pipeline as source material. But SVG/template-based generation cannot consume a raw PPTX as a template. If the user wants the SVG generation route, they must first run the standalone [`create-template`](skills/ppt-master/workflows/create-template.md) workflow and return with the resulting template directory path. SKILL.md Step 3 consumes explicit template directories only.
>
> Beautify / re-layout: when the user provides an existing `.pptx` and asks to beautify or re-layout it while keeping the content (for example, "把这份 PPT 美化一下", "重新排版,内容别动", or wants to paste the regenerated elements back into the original deck), run the standalone [`beautify-pptx`](skills/ppt-master/workflows/beautify-pptx.md) workflow. Mirror of template-fill: content is preserved verbatim, the source's palette/fonts are inherited as truth, only layout is redesigned. Unlike template-fill, it regenerates a native deck through the SVG pipeline (Strategist → Executor → export), one source slide to one page; it does not edit the source in place. Routing boundary — beautify is for "keep this deck, just lay it out better": page count and page order are preserved 1:1. If the original page breakdown itself should be reconsidered (merge / split / reorder pages, re-outline the structure), that is NOT beautify: convert the deck with [`ppt_to_md`](skills/ppt-master/scripts/source_to_md/ppt_to_md.py) and run the main SKILL.md pipeline, where the Strategist re-architects the outline freely from the extracted content. The discriminator is page count / order: any change to it — split, merge, drop, reorder, even just splitting a crowded page so it reads better — is the main pipeline; beautify is strictly 1:1. Decide by one question: is the source's page split information to preserve, or just the previous author's structure to improve?
>
@@ -24,6 +26,8 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
>
> Recorded narration / video export: run the standalone [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) workflow after post-processing.
>
+> Existing PPTX native enhancement without regeneration: when the user provides a finished `.pptx` and asks to optimize it while keeping existing content / layout / format stable — for example adding speaker notes, narration audio, automatic slide advance, or page transitions — run the standalone [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) workflow. This route archives the source PPTX into the project (`projects/` sources are moved; external sources are copied), then patches it directly at the OOXML zip layer and must not enter the SVG generation pipeline.
+>
> Object-level animation tuning: when the user asks to change animation order, effect, timing, or a specific object's reveal behavior, run the standalone [`customize-animations`](skills/ppt-master/workflows/customize-animations.md) workflow. Default export applies page transitions but no per-element entrance animation (element builds are opt-in); create `animations.json` or pass `-a auto` only when the user asks for element animation or object-level customization.
>
> Live preview: any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Step 6 auto-starts it during generation; the workflow covers post-export re-entry and applying submitted annotations.
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 3c34b28a..f29cf94a 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -43,6 +43,28 @@ description: >
> - Do NOT create `.worktrees/`, `tests/`, branch workflows, or generic engineering structure by default
> - On conflict with a generic coding skill, follow this skill unless the user explicitly says otherwise
+## Rule Strength Labels
+
+| Label | Meaning |
+|---|---|
+| `MUST` | Required behavior; violation is workflow failure |
+| `MUST NOT` | Forbidden behavior |
+| `DEFAULT` | Used when the user has not specified otherwise |
+| `OPTIONAL` | Run only when explicitly triggered or when the route says so |
+| `FALLBACK` | Recovery path after the primary path fails |
+| `GATE` | Required checkpoint before entering the next step |
+
+## Cross-Cutting Authorities
+
+| Concern | Authority | Contract |
+|---|---|---|
+| Main pipeline sequencing | This `SKILL.md` | Owns Step 1-7 order, gates, role switching, and mandatory commands |
+| Route selection | [`workflows/routing.md`](workflows/routing.md) | Owns deterministic route choice before the main pipeline or a standalone workflow |
+| Workflow registry | [`workflows/index.md`](workflows/index.md) | Owns standalone workflow trigger/precondition/output inventory |
+| Artifact ownership | [`references/artifact-ownership.md`](references/artifact-ownership.md) | Owns fact channels, source/derived artifact boundaries, and regeneration rules |
+| Failure recovery | [`workflows/failure-recovery.md`](workflows/failure-recovery.md) | Owns stop/continue decisions for common failures |
+| Confirm UI details | [`scripts/docs/confirm_ui.md`](scripts/docs/confirm_ui.md) | Owns schema, launcher behavior, port strategy, and chat fallback details |
+
## Main Pipeline Scripts
| Script | Purpose |
@@ -82,57 +104,25 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
## Standalone Workflows
-| Workflow | Path | Purpose |
-|----------|------|---------|
-| `topic-research` | `workflows/topic-research.md` | Pre-pipeline — gather web sources when the user supplies only a topic with no source files |
-| `template-fill` | `workflows/template-fill-pptx.md` | Give a native PPTX template deck plus source material; select fitting pages (a page may be reused for several output slides) and fill text back without SVG conversion |
-| `beautify` | `workflows/beautify-pptx.md` | Re-layout an existing PPTX through the SVG pipeline — preserve its text verbatim, inherit its palette/fonts as truth, redo only layout; mirror of `template-fill` |
-| `create-template` | `workflows/create-template.md` | Standalone layout template creation workflow |
-| `create-brand` | `workflows/create-brand.md` | Standalone brand-only template creation (identity preset; no SVG page roster) |
-| `resume-execute` | `workflows/resume-execute.md` | Phase B entry — resume execution in a fresh chat after Phase A (Step 1–5) completed in another session (split mode) |
-| `verify-charts` | `workflows/verify-charts.md` | Chart coordinate calibration — run after SVG generation if the deck contains data charts |
-| `customize-animations` | `workflows/customize-animations.md` | Object-level PPTX animation customization — run only when the user explicitly asks to tune animation order/effects/timing |
-| `native-enhance-pptx` | `workflows/native-enhance-pptx.md` | Existing PPTX native enhancement — optimize a finished deck by appending notes / audio / auto-advance / page transitions without changing existing content or layout |
-| `native-narration-pptx` | `workflows/native-narration-pptx.md` | Compatibility reference for the notes / narration subset of `native-enhance-pptx` |
-| `live-preview` | `workflows/live-preview.md` | Browser-based live preview — auto-started during generation and re-enterable any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element |
-| `visual-review` | `workflows/visual-review.md` | Per-page rubric-based visual self-check — run only when the user explicitly asks for a visual re-pass on the generated SVGs (between Executor and post-processing). Opt-in only; never invoked by the main pipeline. |
-
-### PPTX Route Boundary
-
-> [!CAUTION]
-> **Raw PPTX template requests route to `template-fill` by default.** A `.pptx` may enter the main pipeline as source material. But when the user provides a raw `.pptx` template plus new material / a new topic and asks to generate a `.pptx`, use [`workflows/template-fill-pptx.md`](workflows/template-fill-pptx.md). The SVG generation route can consume only an explicit template directory path; if the user wants SVG/template-based generation from that PPTX, they must run [`workflows/create-template.md`](workflows/create-template.md) first and return with the generated template directory path.
-
-When the user provides an existing `.pptx`, route by the role of the source deck:
-
-**Template-fill vs template-based generation — mutually exclusive routes.** Do not treat these as two implementations of the same request. They answer different user intents:
+**Route authority**: Use [`workflows/routing.md`](workflows/routing.md) before entering the main pipeline or any standalone workflow.
-- `template-fill` means **native PPTX fill**: clone selected source slides and patch their existing text / tables / charts.
-- `create-template` first, then main pipeline means **template-based generation**: turn the source deck into a reusable template package, then generate a new deck through the SVG pipeline from that template directory.
-- A raw PPTX template plus a request to output a PPTX defaults to `template-fill`; it does not enter the SVG route unless the user explicitly asks to create / use a reusable template package.
+**Registry**: Use [`workflows/index.md`](workflows/index.md) for the complete workflow list, triggers, preconditions, exclusions, outputs, and blocking points.
-| Axis | `template-fill` | `create-template` first, then main pipeline |
-|---|---|---|
-| Source deck role | Native slide library to clone and patch | Design reference to convert into a reusable template package |
-| Output mechanics | Direct OOXML editing; no SVG pipeline | SVG generation pipeline after a template directory exists |
-| User expectation | "Use this PPT template to generate a PPTX", "fill / replace text / keep these PowerPoint slide shells" | "Create / use this as a reusable template style for SVG-generated decks" |
-| Design freedom | Low to moderate: selected source slides are reused as native shells | Moderate to high: generated deck may select, repeat, skip, reorder, and adapt template pages |
-| Reusability | One-off project output | Reusable `templates/<kind>/<id>/` asset |
-| Direct signal phrases | "fill back", "replace the copy", "keep these slides", "edit this PPTX directly" | "create a template", "make this reusable", "generate from this template directory", "use this SVG template package" |
+### PPTX Route Boundary
-Apply the route deterministically: raw `.pptx` template + "generate PPTX" → `template-fill`. SVG/template-based generation → requires a pre-created template directory path. If the user asks for SVG/template-based generation from a raw PPTX, tell them to run `create-template` first and return with the generated template directory path; do not ask a route-choice question.
+| User intent | Route |
+|---|---|
+| Raw PPTX template plus new material/topic, generate a PPTX | [`template-fill-pptx`](workflows/template-fill-pptx.md) |
+| Existing PPTX, preserve page count/order and slide wording 1:1, improve layout | [`beautify-pptx`](workflows/beautify-pptx.md) |
+| Existing PPTX as source material, rethink outline or change page count/order | Main pipeline via `ppt_to_md.py` plus PPTX intake |
+| Build a reusable template package from a PPTX/design reference | [`create-template`](workflows/create-template.md), then return with the generated template directory path |
+| Finished PPTX, keep content/layout stable and add notes/audio/timing/transitions | [`native-enhance-pptx`](workflows/native-enhance-pptx.md) |
-| User intent | Route | Contract |
-|---|---|---|
-| Preserve the deck's page split, page order, and per-slide wording; improve layout / hierarchy / whitespace | `beautify` | Source page count and order are 1:1; text and data values are frozen; visual identity is inherited after confirmation |
-| Treat the deck as source material; rethink the story, merge / split / drop / reorder pages, or change page count | Main pipeline | `ppt_to_md` + PPTX intake provide content facts and candidates; Strategist may re-architect freely |
-| Use a raw PPTX template to generate a new PPTX with new material | `template-fill` | Clone selected source slides and replace text / table / chart data directly in OOXML; no SVG generation, no reusable template package |
-| Use the SVG generation route with this deck's design language | `create-template` first, then main pipeline | A raw PPTX is not a Step 3 template. The user must create a reusable template package first; once they provide the resulting template directory path, Step 3 can consume it like any other explicit template path |
-| Harvest the deck as a reusable future template | `create-template` | Build a template package, not a one-off generated deck |
-| Keep the finished deck visually stable and append native optimizations such as notes / narration audio / automatic playback | `native-enhance-pptx` | Archive the source PPTX into the project (`projects/` sources move; external sources copy) and patch enhancement metadata/media directly in OOXML; no SVG generation |
+**MUST**: Raw `.pptx` template plus "generate PPTX" routes to `template-fill-pptx` by default. The SVG generation route consumes only an explicit template directory path that already contains a valid template `design_spec.md`.
-**Deciding axis (beautify vs main pipeline) — one question, one discriminator**: is the source's page split a finished artifact to preserve, or a draft structure to overturn? The concrete discriminator is **page count / order**: if it changes at all — any split, merge, drop, or reorder — it is the **main pipeline**, never beautify. Beautify is **strictly 1:1**: same page count, same order, text verbatim, only layout / hierarchy / whitespace redone. Edge case made explicit: "keep all the content but split a crowded page so it reads better" still changes page count, so it is the **main pipeline** (re-pagination is re-architecture), not beautify.
+**MUST**: Beautify is strictly 1:1. Any split, merge, drop, reorder, or page-count change routes to the main pipeline.
-Ambiguous requests such as "make this PPT more professional" or "optimize this deck" MUST be clarified with one question before routing: "Should the original page count/order and each slide's wording be preserved, or should the deck be treated as source material and restructured into a new story?" Preserve → `beautify`; restructure → main pipeline.
+**FALLBACK**: Ambiguous requests such as "make this PPT more professional" require exactly one discriminator question: preserve original page count/order and slide wording, or treat the deck as source material and restructure it?
---
@@ -341,6 +331,8 @@ Read references/strategist.md
> ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–XI section structure. See `strategist.md` Section 1.
+**Artifact ownership**: fact-channel and source/derived artifact boundaries are defined in [`references/artifact-ownership.md`](references/artifact-ownership.md). This Step uses those ownership rules; it does not redefine them.
+
**`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Eight Confirmations, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.)
**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the Markdown** (`sources/<stem>.md`): text, tables, and chart data values all come from there (`ppt_to_md` now transcribes native chart data into Markdown tables). The `analysis/` chart / table entries are a **structural digest** for outline decisions (which slides carried charts, type, series names) — not a second copy of the values; do NOT also pull chart values from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract; beautify uses it for native chart / table data while keeping slide text from the Markdown.
@@ -358,7 +350,7 @@ Read references/strategist.md
7. Typography plan, including formula rendering policy
8. Image usage approach
-**Confirm UI Auto-Launch (Mandatory — default visual confirmation surface)**: by default the Eight Confirmations are presented through an interactive local page in **two tiers within one browser session** — Tier 1 confirms the *anchors*; the AI then re-derives the realization layer from the **user's actual** anchors; Tier 2 confirms that layer. Color swatches, live font previews, candidate picks; the chat path is the always-valid fallback. The split (full field rules: [`scripts/docs/confirm_ui.md`](scripts/docs/confirm_ui.md)):
+**Confirm UI Auto-Launch (Mandatory — default visual confirmation surface)**: by default the Eight Confirmations are presented through an interactive local page in **two tiers within one browser session** — Tier 1 confirms the *anchors*; the AI then re-derives the realization layer from the **user's actual** anchors; Tier 2 confirms that layer. Color swatches, live font previews, candidate picks; the chat path is the always-valid fallback. [`scripts/docs/confirm_ui.md`](scripts/docs/confirm_ui.md) owns the schema, server lifecycle, port strategy, and fallback details; this section keeps the orchestration contract. The split:
| Tier | Confirms | Driven by |
|---|---|---|
@@ -486,6 +478,8 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
> **Trigger**: At least one row in the resource list has `Acquire Via: ai`, `web`, and/or `slice`. If every row is `user`, `formula`, or `placeholder`, skip to Step 6.
+**Failure recovery**: stop/continue behavior for AI/web/slice/image-readiness failures is defined in [`workflows/failure-recovery.md`](workflows/failure-recovery.md). This Step keeps the acquisition procedure.
+
**Always load the common framework**:
```
@@ -547,6 +541,8 @@ Workflow:
🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready.
+**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).
+
Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):
```
Read references/executor-base.md # REQUIRED: common guidelines
@@ -611,6 +607,8 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
🚧 **Image readiness GATE** (when Step 5 left ai rows in `Needs-Manual`): every expected file must exist at `project/images/<filename>` before running 7.1.
+**Failure recovery**: if a Step 7 command fails, fix the owning source artifact and resume from the failed sub-step per [`workflows/failure-recovery.md`](workflows/failure-recovery.md). Do not restart Phase A unless the owning source changed.
+
> If files are missing: PAUSE, list the missing filenames, point the user to `images/image_prompts.md` (each `### Image N:` block is paste-ready for ChatGPT / Gemini / Midjourney; auto-generated from `image_prompts.json`) and the required placement `project/images/<filename>`. Resume Step 7.1 only after all expected files are in place. `finalize_svg.py` and `svg_to_pptx.py` do not detect missing files at this layer — proceeding with gaps produces a deck with broken image references.
> **Spot-illustration sheets at this gate**: `slice` element files are **derived**, not placed by the user. If a sheet was `Needs-Manual` (offline), the element files do not exist yet — list the **sheet** filename (`images/<sheet>.png`) plus its element target names, and instruct: place the sheet, then run the Step 5 `slice_images.py` command for it, then re-run `analyze_images.py`, before resuming 7.1. Never tell the user to hand-place the individual element files — they only come from slicing the sheet.
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
new file mode 100644
index 00000000..fb51ae3c
--- /dev/null
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -0,0 +1,63 @@
+# Artifact Ownership Specification
+
+Global artifact ownership rules for PPT Master projects.
+
+**Hard rule**: Read each fact from its owning artifact. Do not merge multiple channels into a second source of truth.
+
+---
+
+## 1. Ownership Matrix
+
+| Artifact | Owner | Role | Read/write contract |
+|---|---|---|---|
+| `sources/<stem>.md` | Content contract | Main pipeline source for text, tables, and chart data values | Strategist reads for content; do not replace values with PPTX geometry JSON in the main pipeline |
+| `sources/` originals | Source archive | Imported source files and source-adjacent extracted assets | Project manager imports here; downstream reads by route |
+| `analysis/source_profile.json` | Machine fact index | Compact Strategist-facing PPTX intake digest | Main pipeline reads as factual context and recommendation candidates |
+| `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 | 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` | Human design narrative | Explains design intent, outline, rationale, and resource plan | Strategist writes; humans and later roles read for intent |
+| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, templates, and charts | Executor re-reads before every page; values must be used verbatim |
+| `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Step 5 writes here; `analysis/image_analysis.csv` derives from current contents |
+| `icons/` | Project icon inventory | Icons copied by `icon_sync.py` for this project | Executor uses locked project icons; exporter may fall back to global library only as documented |
+| `templates/` | Project template reference | Step 3 imported specs, template SVGs, and non-image assets | Strategist/Executor read only when Step 3 is triggered |
+| `confirm_ui/recommendations.json` | Confirmation proposal | Strategist-authored confirmation payload | Confirm UI reads; rewritten between Tier 1 and Tier 2 |
+| `confirm_ui/result.json` | Confirmation result | User-confirmed values | Strategist treats final result as authoritative over recommendations |
+| `svg_output/` | Author source | Main-agent handwritten SVG pages | Quality checker and native PPTX export read this as canonical page source |
+| `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` |
+| `svg_final/` | Derived preview/export SVGs | Self-contained post-processed SVGs | Rebuild from `svg_output/` with `finalize_svg.py` |
+| `exports/` | Delivery artifacts | Native PPTX and optional SVG snapshot PPTX | Step 7.3 writes final outputs |
+| `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 | Object-level animation sidecar | Created only by explicit animation workflow/request |
+
+---
+
+## 2. Ownership Invariants
+
+| Invariant | Rule |
+|---|---|
+| Content values | Main pipeline text, tables, and chart values come from `sources/<stem>.md`, not from `slide_library.json`. |
+| PPTX structure | `slide_library.json` owns native geometry and slot facts for direct PPTX workflows. |
+| Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. |
+| Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. |
+| SVG source | `svg_output/` is the only author source for generated pages. |
+| Post-processed SVG | `svg_final/` is disposable and must be rebuildable from `svg_output/`. |
+| Export source | Native PPTX export reads `svg_output/` by default. SVG snapshot export reads `svg_final/` only when requested. |
+| Confirmation | Final `confirm_ui/result.json` or chat confirmation overrides recommendations. |
+
+**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, and do not treat `design_spec.md` prose as a replacement for `spec_lock.md`.
+
+---
+
+## 3. Regeneration Rules
+
+| Derived artifact | Regenerate from | Command / owner |
+|---|---|---|
+| `analysis/image_analysis.csv` | Current `images/` | `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` |
+| `notes/slide_*.md` | `notes/total.md` | `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>` |
+| Native PPTX | `svg_output/` plus notes/assets | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` |
+| SVG snapshot PPTX | `svg_final/` | `svg_to_pptx.py --svg-snapshot` |
+
+**Default - regenerate derived views**: When a source artifact changes, regenerate the derived artifact at the owning step instead of patching the derived file directly.
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index d0eee534..d96289ca 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -2,6 +2,22 @@
> The interactive, visual surface for SKILL.md Step 4 (the Eight Confirmations). Enumerable fields list **all** options from a catalog with the AI's recommendation badged; generative fields (color, typography, generated-image style) show **≥3** AI candidates (creative recommendations always offer real choice — same rule as the h.5 image strategy; fewer only on the honest-shortfall exception, with a stated reason). Fields whose universe is open (canvas, mode, visual style, icons) also get a **Custom** box; image usage is a multi-select source list plus a free-text `image_notes` box. Fully closed fields (AI source when applicable, formula policy, generation mode, refine spec) do not. The AI writes its recommendation to `recommendations.json`; the user's final choices are written back to `result.json` for the AI to read. On confirm the page saves the result and shuts the server down (auto-close). The chat path is always a valid fallback — if the browser cannot open (remote / headless / web host), the AI presents the same confirmations in chat.
+## Authority and Scope
+
+| Concern | Owner |
+|---|---|
+| Step 4 gate and pipeline order | `SKILL.md` |
+| Confirm UI schema | This document |
+| Tier 1 / Tier 2 field membership | This document |
+| Server launch / wait / shutdown behavior | This document |
+| Port and lock behavior | This document |
+| Chat fallback equivalence | This document |
+| Confirmed-value precedence | `SKILL.md` plus this document's `result.json` contract |
+
+**Hard rule**: Keep detailed Confirm UI behavior here. `SKILL.md` may summarize the orchestration, but it should not duplicate the full JSON schema, catalog behavior, or launcher lifecycle.
+
+**Fallback rule**: Browser failure never cancels Step 4. Re-check `result.json` once, then use the chat confirmation path with the same two-tier semantics.
+
## `confirm_ui/server.py`
```bash
diff --git a/skills/ppt-master/workflows/failure-recovery.md b/skills/ppt-master/workflows/failure-recovery.md
new file mode 100644
index 00000000..52e4f2cf
--- /dev/null
+++ b/skills/ppt-master/workflows/failure-recovery.md
@@ -0,0 +1,69 @@
+---
+description: Failure recovery matrix for PPT Master generation routes
+---
+
+# Failure Recovery Matrix
+
+Central recovery rules for common PPT Master failures. Route-specific workflow files may add narrower handling, but must not weaken these stop/continue decisions.
+
+**Hard rule**: A failed required artifact blocks the next gate. A failed convenience surface falls back to the canonical channel and does not block generation.
+
+---
+
+## 1. Recovery Matrix
+
+| Failure point | Blocking | Automatic recovery | User intervention | Resume entry |
+|---|---:|---|---|---|
+| Confirm UI launch failure | No | Re-check `confirm_ui/result.json` once, then use chat fallback | No | `SKILL.md` Step 4 chat confirmation |
+| 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 tier or chat fallback |
+| Confirm UI Tier 1 completed then interrupted | Yes until Tier 2 is written/confirmed | Read existing Tier 1 `result.json`, write Tier 2 recommendations, then `--wait-only` | Usually no | Step 4 Tier 2 write/wait |
+| Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation |
+| Formula rendering provider failure | No if fallback succeeds; yes if selected formulas remain missing | Provider fallback chain; otherwise mark affected rows manual only if acceptable | Only if rendered formula files are required and unavailable | Step 4 formula rendering / Step 7 image readiness gate |
+| AI image generation failure | No | Retry once through the confirmed path, then mark row `Needs-Manual` | Only when missing files are required before export | Step 5 / Step 7 image readiness gate |
+| Web image search/download failure | No | Adjust query/source per image-searcher rules, then mark `Needs-Manual` if unresolved | Only if the resource is required and no acceptable substitute exists | Step 5 |
+| Slice sheet missing | Yes for derived slice rows | Wait for parent sheet; run `slice_images.py`; rerun image analysis | Yes when sheet was manual/offline | Step 5 slice handling / Step 7 image readiness gate |
+| Residual `Pending` or `Failed` image row before Executor | Yes | Re-run path or mark `Needs-Manual` | Only if file must be supplied manually | Step 5 terminal-state check |
+| User replaces/adds images after analysis | No | Re-run `analyze_images.py` before reading image facts | No | Step 4/5/6 image-fact read |
+| Live preview fails to start | No | Continue generation; report that preview is unavailable | Only if user requires browser preview | Step 6 or `live-preview` Step 1 |
+| Live preview closed by user | No | Continue generation | No | Restart through `live-preview` only if requested |
+| 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 | Fix the affected SVG, then rerun checker | No unless required asset is missing | Step 6 Visual Construction |
+| `svg_quality_checker.py` warning | No | Fix when straightforward; otherwise acknowledge residual risk | No | Step 6 warning handling |
+| Missing `notes/total.md` | 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 |
+| `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 |
+
+---
+
+## 2. Stop/Continue Rules
+
+| Condition | Action |
+|---|---|
+| Required gate artifact missing | Stop at that gate and name the missing artifact. |
+| Optional workflow not explicitly requested | Do not run it as recovery. |
+| Convenience UI/server failure | Fall back to chat or continue without the surface. |
+| Derived artifact stale | Regenerate it from its owning source. |
+| Manual image asset missing at Step 7 | Pause and list exact filenames; resume only after files exist. |
+| Checker/export error | Fix the source artifact, then rerun the failed command and downstream commands only. |
+
+**Forbidden - silent downgrade**: Do not skip a required gate because a downstream command might tolerate the missing file. Fix or pause at the owning gate.
+
+---
+
+## 3. Resume Pointers
+
+| Last good state | Resume from |
+|---|---|
+| Tier 1 confirmation exists, Tier 2 missing | Write Tier 2 recommendations, then `confirm_ui/server.py <project> --wait-only` |
+| `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](./resume-execute.md) |
+| Images acquired but SVGs not started | `SKILL.md` Step 6 |
+| SVGs complete and checker passed, notes missing | Step 6 Logic Construction |
+| SVGs and 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`](./live-preview.md) Step 2 |
+
+**Default - resume at the owning failed step**: Do not restart Phase A or regenerate prior artifacts unless the owning source has changed.
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
new file mode 100644
index 00000000..1bbf731f
--- /dev/null
+++ b/skills/ppt-master/workflows/index.md
@@ -0,0 +1,43 @@
+---
+description: Registry of standalone PPT Master workflows
+---
+
+# Workflow Registry
+
+Registry for standalone workflows referenced by `SKILL.md` and [`routing.md`](./routing.md).
+
+**Hard rule**: When adding a standalone workflow, update this registry and [`routing.md`](./routing.md) in the same change. The workflow file owns step-by-step execution; this registry owns discoverability and trigger boundaries.
+
+---
+
+## 1. Registry
+
+| ID | Path | Trigger | Preconditions | Route exclusion | Entry step | Output contract | Blocking points |
+|---|---|---|---|---|---|---|---|
+| `topic-research` | [`topic-research.md`](./topic-research.md) | Topic-only request with no substantive source material | Topic or requirements exist | Do not invent facts in the main pipeline | Before `SKILL.md` Step 1 | Source material suitable for Step 1 | Stops if usable source facts cannot be gathered |
+| `template-fill-pptx` | [`template-fill-pptx.md`](./template-fill-pptx.md) | Raw PPTX template plus new material/topic; clone/fill native slides | Source PPTX plus content material or topic brief | No SVG generation; no `create-template` unless reusable package is requested | Workflow Step 1 | Native PPTX in project `exports/` | Stops if no PPTX or no fill material |
+| `beautify-pptx` | [`beautify-pptx.md`](./beautify-pptx.md) | Existing PPTX should be re-laid out while preserving slide count/order and wording 1:1 | Single source PPTX | Not for merge/split/drop/reorder or re-outline | Workflow Step 1 | Regenerated 1:1 deck through SVG pipeline | Blocks on source-slide mapping and final confirmation gates defined in the workflow |
+| `create-template` | [`create-template.md`](./create-template.md) | Build a reusable layout/deck template from a PPTX or design reference | Design source or explicit template-creation request | Not a one-off generated deck | Workflow Step 1 | Template directory with `design_spec.md` and assets | Stops after template creation until user supplies the directory path to main Step 3 |
+| `create-brand` | [`create-brand.md`](./create-brand.md) | Build/extract a reusable brand identity preset | Logo/site/branded deck/PDF or explicit brand setup request | Not a layout/deck template roster | Workflow Step 1 | Brand directory under `templates/brands/<id>/` | Blocks on brand evidence and validation defined in the workflow |
+| `resume-execute` | [`resume-execute.md`](./resume-execute.md) | Continue Phase B for an existing project after split mode | Phase A artifacts exist | Do not re-run Phase A | Phase B entry | SVG generation, post-processing, export | Stops if `design_spec.md` or `spec_lock.md` is missing |
+| `refine-spec` | [`refine-spec.md`](./refine-spec.md) | User explicitly opts into spec refinement before generation | Eight Confirmations completed | Do not enter by default | After Step 4, before Step 5/6 | Revised `design_spec.md` and `spec_lock.md` | Blocks for user review/approval before generation |
+| `verify-charts` | [`verify-charts.md`](./verify-charts.md) | Deck contains data charts that require coordinate calibration | SVG pages exist | Not needed for decks without data charts | Between Step 6 and Step 7 | Verified/fixed chart geometry | Blocks on chart coordinate errors |
+| `customize-animations` | [`customize-animations.md`](./customize-animations.md) | User asks for object-level animation order/effect/timing | Target deck/SVG groups exist | Do not add per-element builds by default | Before or during export configuration | `animations.json` or equivalent validated config | Blocks if target objects cannot be identified |
+| `native-enhance-pptx` | [`native-enhance-pptx.md`](./native-enhance-pptx.md) | Finished PPTX should keep content/layout stable while adding notes/audio/timing/transitions | Source PPTX exists | No SVG regeneration | Workflow Step 1 | Patched PPTX through OOXML | Blocks on source archive/validation failures |
+| `native-narration-pptx` | [`native-narration-pptx.md`](./native-narration-pptx.md) | Compatibility reference for the narration subset of native enhancement | Existing PPTX exists | Prefer `native-enhance-pptx` for new requests | Compatibility entry | Narration-enhanced PPTX | Follow compatibility doc |
+| `live-preview` | [`live-preview.md`](./live-preview.md) | User asks for preview, element selection, browser annotations, or re-entry to the editor | Project exists; SVGs required only for annotation apply/export | Do not apply annotations during active generation | Step 6 auto-start or workflow Step 1/2 | Running preview or applied browser edits/annotations | Blocks only when project/SVG target is missing |
+| `visual-review` | [`visual-review.md`](./visual-review.md) | User explicitly asks for per-page visual review or visual rubric | Generated SVG pages exist | Never inferred from deck size/model identity | Between Step 6 and Step 7 | Findings and fixed SVGs | Blocks on selected severe findings if the workflow says to fix |
+| `generate-audio` | [`generate-audio.md`](./generate-audio.md) | User asks for recorded narration, voiceover, audio, or video-style export | Post-processing/export context exists; notes available | Do not call `notes_to_audio.py` directly | After Step 7 | Audio files and optional narration-embedded PPTX | Single backend/voice/settings confirmation |
+
+---
+
+## 2. Update Checklist
+
+When adding or changing a standalone workflow:
+
+1. Update the row in §1.
+2. Update route selection in [`routing.md`](./routing.md).
+3. Add a short pointer in `SKILL.md` only if the workflow is part of the main pipeline's normal control flow.
+4. Keep detailed commands and recovery behavior in the workflow file, not in this registry.
+
+**Forbidden - duplicated matrices**: Do not copy the full route matrix from [`routing.md`](./routing.md) into `SKILL.md`. Link to the authority instead.
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
new file mode 100644
index 00000000..6b396d99
--- /dev/null
+++ b/skills/ppt-master/workflows/routing.md
@@ -0,0 +1,77 @@
+---
+description: Deterministic route selection rules for PPT Master requests
+---
+
+# Routing Rules
+
+Route selection authority for PPT Master. Use this file before entering the main pipeline or any standalone workflow.
+
+**Hard rule**: If this file conflicts with a route summary in `SKILL.md`, `AGENTS.md`, or a user-facing doc, this file wins for route selection. After a route is selected, the target workflow file or `SKILL.md` owns execution details.
+
+---
+
+## 1. Routing Discipline
+
+| Rule | Behavior |
+|---|---|
+| Deterministic routes | Do not ask the user to choose when a request matches a defined route. Enter the route directly. |
+| Missing prerequisite | State the missing prerequisite and stop that route. Do not route around the prerequisite with an invented alternative. |
+| Ambiguous deck optimization | Ask exactly one discriminator question: preserve original page count/order and slide wording, or treat the deck as source material and restructure it? |
+| Explicit user override | Honor explicit route instructions only when the route preconditions are satisfied. |
+| Summary conflict | Use this file for route choice, then read the route's own workflow file before executing it. |
+
+**Forbidden - route-choice prompts**: Do not present multiple implementation paths when this file already defines the route. Ordinary style choices and finite options belong at the next existing confirmation gate.
+
+---
+
+## 2. Main Route Matrix
+
+| Request shape | Trigger | Route | Forbidden route | Preconditions | Output contract | Stop condition |
+|---|---|---|---|---|---|---|
+| Topic only, no source facts | User supplies only a topic name or requirement and no substantive source material | [`topic-research`](./topic-research.md), then main `SKILL.md` pipeline | Direct main pipeline with invented facts | Web/source gathering is allowed or user supplies facts | Research material becomes source input for Step 1 | Stop if facts cannot be gathered and the user supplies no source |
+| Source material can be reworked into a new story | PDF/DOCX/URL/Markdown/text/conversation content, or PPTX treated as content | Main `SKILL.md` pipeline | Direct PPTX edit workflows | Source content exists or is available in conversation | `design_spec.md`, `spec_lock.md`, `svg_output/`, exported PPTX | Stop at Step gates when required artifacts are missing |
+| PPTX as re-architectable source | User allows page count/order/outline to change, or asks to split/merge/drop/reorder slides | Main `SKILL.md` pipeline with `ppt_to_md.py` plus PPTX intake | [`beautify-pptx`](./beautify-pptx.md) | PPTX source exists | Markdown content plus `analysis/source_profile.json`; Strategist may re-outline | Stop if user requires exact 1:1 page preservation |
+| Explicit template directory path | User provides a directory containing `design_spec.md` with `kind: brand`, `kind: layout`, or `kind: deck` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name | Path resolves and frontmatter kind is valid | Template assets copied/fused into `<project>/templates/` | Stop if the path does not exist or lacks valid `design_spec.md` |
+
+---
+
+## 3. PPTX-Specific Routes
+
+| Request shape | Trigger | Route | Forbidden route | Preconditions | Output contract | Stop condition |
+|---|---|---|---|---|---|---|
+| Raw PPTX template plus new material/topic | "Use this PPT template to generate a PPTX", "fill this deck", "replace copy", native slide shell reuse | [`template-fill-pptx`](./template-fill-pptx.md) | Main SVG pipeline directly from raw PPTX template | Source PPTX plus content material or topic brief | New native PPTX in `exports/`, cloned/patched by OOXML | Stop if user instead wants a reusable template package |
+| Existing PPTX, preserve page split and wording | "Beautify", "re-layout", "make more professional" with same slide count/order and verbatim text | [`beautify-pptx`](./beautify-pptx.md) | Main pipeline if page count/order changes | Single source PPTX | Regenerated deck through SVG pipeline, one source slide to one output slide | Stop if user asks to split/merge/drop/reorder |
+| Finished PPTX, native enhancement only | Add notes, recorded narration, auto-advance, transitions, or stable-layout metadata | [`native-enhance-pptx`](./native-enhance-pptx.md) | SVG regeneration | Finished PPTX exists; content/layout should stay stable | Patched PPTX through direct OOXML | Stop if user asks for visual redesign |
+| PPTX/reference design should become a reusable template | "Create a template", "make reusable", "build template from this deck/design" | [`create-template`](./create-template.md) | `template-fill-pptx` one-off fill | PPTX or design reference exists | Template directory under `templates/<kind>/<id>/` | Stop after creation; main pipeline resumes only when user supplies the generated directory path |
+
+**Hard rule**: Raw PPTX template plus "generate PPTX" routes to `template-fill-pptx` by default. A raw PPTX is not a Step 3 template until `create-template` has produced a reusable template directory.
+
+**Hard rule**: Beautify is strictly 1:1. Any page count or page order change is re-architecture and therefore the main pipeline, not beautify.
+
+---
+
+## 4. Optional and Post-Route Workflows
+
+| Request shape | Trigger | Route | Preconditions | Output contract | Stop condition |
+|---|---|---|---|---|---|
+| Brand identity setup | Brand asset, brand site URL, branded PPTX/PDF, or explicit brand setup request | [`create-brand`](./create-brand.md) | Brand source exists or can be inspected | Brand preset under `templates/brands/<id>/` | Stop if no brand source or brand intent exists |
+| Continue a split-mode project | "Continue generating `projects/<name>`" after Phase A | [`resume-execute`](./resume-execute.md) | Project has Phase A artifacts | Phase B SVG generation and export | Stop if required Phase A artifacts are missing |
+| Refine spec before generation | User explicitly asks to refine/review/revise the spec before SVG work, or confirms `refine_spec: true` | [`refine-spec`](./refine-spec.md) | Eight Confirmations completed | Revised `design_spec.md` and `spec_lock.md` before Step 5/6 | Stop until user approves the refined spec |
+| Data chart calibration | Generated deck contains data charts | [`verify-charts`](./verify-charts.md) between Step 6 and Step 7 | SVG pages exist | Calibrated chart coordinates before export | Stop on chart geometry errors until fixed |
+| Object-level animation tuning | User asks for animation order, timing, effects, or object reveal behavior | [`customize-animations`](./customize-animations.md) | SVG groups / exported context exist | `animations.json` or validated animation config | Stop if requested target objects cannot be identified |
+| Live preview / element selection / annotations | User mentions live preview, preview, visual check in browser, clicking/selecting an element, or applying browser annotations | [`live-preview`](./live-preview.md) | Project exists; for annotation apply, generated SVGs exist | Running preview service or applied annotations plus re-export | Stop only if project path or SVGs are missing |
+| Visual review | User explicitly asks for per-page visual self-check or visual rubric | [`visual-review`](./visual-review.md) between Step 6 and Step 7 | SVG pages exist | Visual review findings and fixes before post-processing | Do not run without explicit user request |
+| Recorded narration / video export | User asks for narration, voiceover, or video-style export | [`generate-audio`](./generate-audio.md) after post-processing | Notes and exported deck exist | Audio files and optional narration-embedded PPTX | Stop for the workflow's single backend/voice confirmation |
+
+---
+
+## 5. Template Name Boundary
+
+| User input | Route behavior |
+|---|---|
+| Explicit directory path containing a valid template `design_spec.md` | Enter main Step 3 template option |
+| Bare template name, brand name, style label, or vague "use a template" | Do not trigger Step 3; treat as style input for Eight Confirmations |
+| User asks "what templates exist?" | Answer as Q&A by listing indexed paths; do not advance the pipeline |
+| Raw `.pptx` called a template | Route by §3, usually `template-fill-pptx`; never treat it as a Step 3 template path |
+
+**Forbidden - fuzzy resolution**: Do not resolve bare names to local template directories on the user's behalf. The user must provide the path that enters Step 3.