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(workflows): clarify route ownership and retire structure restoration
hugohe3c4a82942e6b4
diff --git a/AGENTS.md b/AGENTS.mdindex 37f902a4..fa4f1294 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -10,18 +10,18 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist confirmation stage → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export PPTX`-**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the complete route matrix. The hard boundaries below stay inline because they bypass or redirect the main pipeline and are the most expensive to misroute.+**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.-- Topic-only requests run [`topic-research`](skills/ppt-master/workflows/topic-research.md) before SKILL.md Step 1.+- Topic-only requests run the [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) intake stage before SKILL.md Step 1.- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.-- Raw PPTX cannot be consumed as a Step 3 SVG template; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated template workspace root.-- PPTX beautify is strictly 1:1 page count/order and verbatim wording via [`beautify-pptx`](skills/ppt-master/workflows/beautify-pptx.md); any split/merge/drop/reorder routes to the main pipeline.+- Raw PPTX cannot be consumed as a Step 3 SVG template; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated template workspace root. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.+- PPTX beautify is a strict 1:1 main-generation [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), not a separate route; any split/merge/drop/reorder uses the default main-pipeline policy.- Finished PPTX native enhancement uses [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) and must not enter SVG regeneration.-- [`visual-review`](skills/ppt-master/workflows/visual-review.md), [`customize-animations`](skills/ppt-master/workflows/customize-animations.md), and [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) are explicit-request workflows.+- [`visual-review`](skills/ppt-master/workflows/stages/visual-review.md), [`customize-animations`](skills/ppt-master/workflows/stages/customize-animations.md), and [`generate-audio`](skills/ppt-master/workflows/stages/generate-audio.md) are supporting stages; their trigger rules remain explicit/conditional.## Execution Requirements-- For standalone template creation (no source deck), read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).+- For any `brand`, `layout`, or `deck` workspace creation, enter [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md); it keeps the fixed Create Template name and dispatches exactly one of [`create-brand`](skills/ppt-master/workflows/create-template/create-brand.md), [`create-layout`](skills/ppt-master/workflows/create-template/create-layout.md), or [`create-deck`](skills/ppt-master/workflows/create-template/create-deck.md).- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).@@ -99,7 +99,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>- `skills/ppt-master/scripts/` — runnable tool scripts.- `skills/ppt-master/scripts/docs/` — topic-focused script docs.- `skills/ppt-master/templates/` — layout templates, chart templates, icon library, brand presets.-- `skills/ppt-master/workflows/` — standalone workflow files.+- `skills/ppt-master/workflows/` — top-level route authorities plus supporting child workflows, profiles, stages, and governance runbooks.- `docs/` — user-facing documentation (FAQ, installation, technical design, templates guide, audio narration).- `docs/rules/` — repo-wide style rules.- `examples/` — example projects.diff --git a/docs/audio-narration.md b/docs/audio-narration.mdindex a40fb8ce..5237cb44 100644--- a/docs/audio-narration.md+++ b/docs/audio-narration.md@@ -15,7 +15,7 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](3. **One question, one answer.** You are asked once — voice, rate, and "embed audio back into PPTX (yes/no)" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.4. **Generation runs.** The script writes page-level audio to `audio/`, then (if you kept embedding) re-exports the deck with audio attached. Long-audio import and automatic long-audio splitting are not supported.-The full step-by-step is in [`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md).+The shared stage is documented in [`workflows/stages/generate-audio.md`](../skills/ppt-master/workflows/stages/generate-audio.md).## Two embedding pathsdiff --git a/docs/faq.md b/docs/faq.mdindex 19c3b30e..05fc5e71 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -10,7 +10,7 @@ Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **R## Q: Can I generate a deck with just a topic, no source materials?-Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The AI will trigger the **topic-research workflow** — gathering authoritative sources via web search (Wikipedia / official sites / institutional releases), assembling them into a Markdown research document + image folder, then feeding both into the main pipeline.+Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The Generate PPTX route will run its **topic-research stage** — gathering authoritative sources via web search (Wikipedia / official sites / institutional releases), assembling them into a Markdown research document + image folder, then feeding both into the main pipeline.Quality depends on what's on the open web. If you already have specialized material (papers, internal docs), giving those files to the AI directly produces better results than web research alone.@@ -214,7 +214,7 @@ Think of "using an existing PPT" as two questions: **keep its content or not**,| Keep only content, redo design and pagination | **main pipeline** | Source facts; story structure and page count may change || Keep content + keep design | No generation needed | Use the original file |-Use **beautify** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, only layout / hierarchy / whitespace are redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify workflow](../skills/ppt-master/workflows/beautify-pptx.md).+Use the **beautify profile** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, only layout / hierarchy / whitespace are redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify profile](../skills/ppt-master/workflows/profiles/beautify-pptx.md).Use the **main pipeline** when the source PPT is just material: extract it to Markdown with `ppt_to_md`, read PPTX intake facts from `analysis/`, then let Strategist re-architect the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content" or "turn this into a 10-page executive briefing".@@ -240,7 +240,7 @@ Want to turn a PPT you love into a reusable template for PPT Master? Here's how:**Step 1 — Prepare Reference Material**-The recommended input is the original `.pptx`. PPT Master extracts theme identity, declared Master/Layout topology, placeholder metadata, native-shape evidence, and reusable assets. `standard` and `fidelity` use the source as visual reference and author a new SVG roster plus a new Master/Layout/slot system; they neither preserve nor distill source topology. `mirror` instead restores source slide order, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`.+The recommended input is the original `.pptx`. PPT Master extracts theme identity, declared Master/Layout topology, placeholder metadata, native-shape evidence, and reusable assets that are actually present and supported. `standard` and `fidelity` use the source as visual reference and author a new SVG roster plus a new Master/Layout/slot system; they neither preserve nor distill source topology. `mirror` instead materializes those validated source facts into a new workspace without semantic synthesis or gap filling. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`.Large imported SVGs may contain native-shape metadata, hidden carriers, and preview fingerprints. That lossless representation stays immutable in the temporary analysis workspace as payload backing. Template creation uses a lightweight editable IR with document-local source refs and a compact path/hash manifest. `standard` / `fidelity` author project-canonical SVG and use compact authored-preset groups only for exact registered preset matches. Mirror materializes final templates from the IR, reuses converter-supported payload only for unchanged Slide-local/slot refs, and keeps an SVG fallback for unsupported or edited objects.@@ -260,7 +260,7 @@ You don't need to supply every detail upfront — the AI agent will ask follow-u**Step 3 — Wait for the Result**-The AI agent will handle the rest — analyzing your references, building the layout definitions, and validating the template. If you request PowerPoint review, it also generates `exports/<id>_template_preview.pptx` on demand. Both scopes require `templates/` and use optional `images/`, `icons/`, and `exports/`: library scope writes `skills/ppt-master/templates/<kind>/<id>/` and registers it; project scope writes `projects/<name>/` and skips registration. Empty optional directories are omitted. Give that workspace root to Step 3; it never copies `exports/`, and library review exports are Git-ignored. Older flat packages with `design_spec.md` at the root remain compatible, and flat placement alone is not a reason to run structure restoration.+The AI agent will handle the rest — analyzing your references, building the layout definitions, and validating the template. If you request PowerPoint review, it also generates `exports/<id>_template_preview.pptx` on demand. Both scopes require `templates/` and use optional `images/`, `icons/`, and `exports/`: library scope writes `skills/ppt-master/templates/<kind>/<id>/` and registers it; project scope writes `projects/<name>/` and skips registration. Empty optional directories are omitted. Give that workspace root to Step 3; it never copies `exports/`, and library review exports are Git-ignored. A flat workspace with `design_spec.md` at the root remains compatible only when its SVGs already satisfy the current contract; semantic-legacy packages must be replaced through `create-template` rather than upgraded in place.> **Tip**: The more specific you are about the style and use case, the better the generated template will match your expectations.diff --git a/docs/getting-started.md b/docs/getting-started.mdindex b73c3bd4..09084d46 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -78,7 +78,7 @@ A browser preview opens at `http://localhost:5050` while the deck is being generPPT Master was chat-only by design; visual editing was folded in after enough users asked for it (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85)).-Full guide → [Live Preview Workflow](../skills/ppt-master/workflows/live-preview.md)+Full guide → [Live Preview Stage](../skills/ppt-master/workflows/stages/live-preview.md)---diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.mdindex 0282efe0..21966d0f 100644--- a/docs/powerpoint-svg-mapping.md+++ b/docs/powerpoint-svg-mapping.md@@ -32,7 +32,7 @@ Each row owns one PowerPoint capability. The mapping cardinality is not always o| `Direct preservation` | A direct-PPTX workflow may retain the source OOXML; the main SVG compiler does not recreate it. || `Unsupported` | The main generation route has no registered mapping and must not guess. |-“Import” below means semantic reconstruction by the PPTX-to-SVG route, not recovery of the original SVG syntax. It does not promise the original `<defs>` graph, `<use>` structure, path commands, or `<tspan>` layout.+“Import” below means a semantic projection produced by the PPTX-to-SVG route, not recovery of an original SVG or absent design intent. It does not promise the original `<defs>` graph, `<use>` structure, path commands, or `<tspan>` layout.## 1. Presentation, slide, and coordinate model@@ -56,9 +56,9 @@ See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for|---|---|---|---|---|| Free-design deck structure | `pptx_structure.mode: flat`; page content remains slide-local | One clean project Master and one Blank Layout, with represented objects on slides | `Native-stable` package topology for the flat route | No authored Master/Layout/layer/placeholder metadata is allowed || Template-backed deck structure | `pptx_structure.mode: structured` plus explicit Master/Layout/page assignments | Declared `p:sldMaster`, `p:sldLayout`, registrations, and slide parentage | `Native-stable` within the explicit structure contract | The exporter never guesses a Master, Layout, or placeholder topology |-| Slide Master | Root Master identity plus atomic `data-pptx-layer="master"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Master part and picker identity | Source structure is restored by template/import workflows | Master atoms must be direct, stable, and identical across their slides; ordinary or expanded authored groups do not qualify |-| Slide Layout | Root Layout identity plus atomic `data-pptx-layer="layout"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Layout part under one Master | Source Layouts can be restored; adaptive authoring may allocate a new Layout | Reuse a Layout key only when its fixed atoms and slot contract are identical; ordinary or expanded authored groups do not qualify |-| Imported inherited-shape visibility | Layered analysis records normalized source booleans; a materialized structured mirror writes exact lowercase root `data-pptx-show-inherited-shapes` and `data-pptx-show-master-shapes` | Restored `p:sld@showMasterSp` and `p:sldLayout@showMasterSp` | `Native-stable`: Slide false hides Layout and Master shapes; Layout false hides only Master shapes | Omission means true; every page using one Layout key must agree on the Layout value. Backgrounds, Slide-local objects, placeholder inheritance, parts, and parent relationships remain intact |+| Slide Master | Root Master identity plus atomic `data-pptx-layer="master"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Master part and picker identity | Create Template mirror may preserve validated source-package facts in a new workspace; authored modes create a new identity | Master atoms must be direct, stable, and identical across their slides; ordinary or expanded authored groups do not qualify |+| Slide Layout | Root Layout identity plus atomic `data-pptx-layer="layout"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Layout part under one Master | Create Template mirror may preserve a validated source Layout in a new workspace; adaptive authoring may allocate a new Layout | Reuse a Layout key only when its fixed atoms and slot contract are identical; ordinary or expanded authored groups do not qualify |+| Imported inherited-shape visibility | Layered analysis records normalized source booleans; a materialized structured mirror writes exact lowercase root `data-pptx-show-inherited-shapes` and `data-pptx-show-master-shapes` | Declared source values written to `p:sld@showMasterSp` and `p:sldLayout@showMasterSp` | `Native-stable`: Slide false hides Layout and Master shapes; Layout false hides only Master shapes | Omission means true; every page using one Layout key must agree on the Layout value. Backgrounds, Slide-local objects, placeholder inheritance, parts, and parent relationships remain intact || Strict template Layout | Selected prototype contract | Existing declared Layout topology is preserved | `Native-stable` when the page follows the prototype | Fixed Layout atoms and slot structure may not change || Adaptive template Layout | Selected Master plus an explicit current or newly declared Layout | A new Layout identity may be created when reusable structure changes | `Native-stable` after the lock and page mapping are updated | Never mutate a reused Layout key silently || Slide background fill outside structured mode | First eligible full-canvas `<rect>`, direct or in a simple single-child group, with a registered solid, linear/radial gradient, or preset-pattern fill | Native slide `p:bg` | Fidelity follows the corresponding paint row below | Transform, filter, clip, rounding, visible stroke, or an unmapped fill prevents promotion |@@ -245,9 +245,9 @@ The importer reconstructs supported PowerPoint semantics into the same project v| Supported native table/chart | Visible fallback plus native-object metadata || Unsupported graphic frame or SmartArt | Explicit preview, placeholder, or unsupported status |-This is semantic reconstruction, not a syntax round trip. Master/Layout restoration belongs to the template-structure workflows; an ordinary visual import does not infer reusable topology from slide appearance.+This is semantic projection, not a syntax round trip. Preserving validated source-package Master/Layout facts is confined to Create Template mirror and always produces a new workspace; an ordinary visual import does not infer reusable topology from slide appearance.-### Import operating modes and recovery boundary+### Import operating modes and error-recovery boundary`pptx_to_svg.py` defaults to tolerant import because its inputs are user-owned or third-party PPTX files. `--strict` is available for parser development, contract verification, and reproducing the first source violation. Strict generated-SVG validation and export remain unchanged.diff --git a/docs/roadmap.md b/docs/roadmap.mdindex b9e3c1d2..7ce9a391 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -21,20 +21,20 @@ The past two months' structural capability growth. Single flags / incremental po### 2026-04 — Pipeline at scale-- **Source-less generation**: `topic-research` workflow supports "topic only, no source files"+- **Source-less generation**: the `topic-research` stage supports "topic only, no source files"- **PPTX export step-change**: SVG clipPath → DrawingML picture geometry, marker → native arrows, output consolidated to `exports/`- **Chart library expands to 70 templates + three icon libraries** (simple-icons / phosphor-duotone / brand-logo)- **`spec_lock.md` machine-readable contract**: Strategist locks the spec, Executor re-reads it before every page — cross-page consistency gets a real guarantee-- **Per-element animation support** + recorded narration / video export ([`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md)); the current behavior is opt-in, with element animation defaulting to `none`+- **Per-element animation support** + recorded narration / video export ([`workflows/stages/generate-audio.md`](../skills/ppt-master/workflows/stages/generate-audio.md)); the current behavior is opt-in, with element animation defaulting to `none`### 2026-05 — Visual editing + AI image systematization-- **Live Preview enters the main pipeline** ([`workflows/live-preview.md`](../skills/ppt-master/workflows/live-preview.md)) — browser preview, click elements to write annotations, say "apply my annotations" and the AI rewrites that region (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85))+- **Live Preview enters the main pipeline** ([`workflows/stages/live-preview.md`](../skills/ppt-master/workflows/stages/live-preview.md)) — browser preview, click elements to write annotations, say "apply my annotations" and the AI rewrites that region (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85))- **Replicate any PPTX as a template** ([`workflows/create-template.md`](../skills/ppt-master/workflows/create-template.md)) — PPTX → SVG reverse + OOXML theme / master / layout / asset extraction- **AI image three-dimension system** rendering × palette × type + Strategist h.5 lock, downstream consumes a fixed contract- **AI image `hero_page` dual-track** — local insert + full-canvas hero image coexist-- **Brand identity preset subsystem** ([`workflows/create-brand.md`](../skills/ppt-master/workflows/create-brand.md)) — extract and reuse brand palette / typography / logo / voice-- **Visual self-review workflow** ([`workflows/visual-review.md`](../skills/ppt-master/workflows/visual-review.md)) — rubric-based per-page check of AI-generated SVGs+- **Brand identity preset subsystem** ([`workflows/create-template/create-brand.md`](../skills/ppt-master/workflows/create-template/create-brand.md)) — the Create Brand child workflow extracts and reuses brand palette / typography / logo / voice under the fixed Create Template entry+- **Visual self-review stage** ([`workflows/stages/visual-review.md`](../skills/ppt-master/workflows/stages/visual-review.md)) — rubric-based per-page check of AI-generated SVGs- **AI image: Type concept boundary clarification** — Type is now narrowed to "the internal geometric skeleton of a local infographic block" (11 real skeletons); the four pseudo-types (hero / background / portrait / typography) fold back into `page_role: hero_page` plus four composition primitives (single-subject / portrait / typographic / atmospheric); hero_page text layering rule (visual keywords embedded, editable text via SVG overlay)- **Brutalist AI newspaper example deck shipped** ([`examples/ppt169_brutalist_ai_newspaper_2026/`](../examples/ppt169_brutalist_ai_newspaper_2026/)) — first of the three P0 capability-backing demos: wall-to-wall small type + irregular columns + halftone monochrome + single-spot red + real native shapes; 10-page editorial annual report stressing text-position precision and cross-page consistency- **Kubernetes Blueprint example deck shipped** ([`examples/ppt169_kubernetes_blueprint_2026/`](../examples/ppt169_kubernetes_blueprint_2026/)) — second of the three P0 capability-backing demos: isometric technical-drawing aesthetic + blueprint cyan/amber palette + hand-authored SVG geometry (no raster images) + custom drawing-in animation; 10-page Kubernetes architecture walkthrough stressing geometric shape generalization and chart-structure extensibility@@ -42,25 +42,25 @@ The past two months' structural capability growth. Single flags / incremental po- **Template architecture: three-kind consolidation** ([`docs/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck split into three independent dirs with per-kind schemas + segment-level fusion + git-style conflict resolution; SKILL.md Step 3 dispatches per `kind`, trigger rule remains "explicit path only"- **Pattern fill PPTX safety net** — `svg_quality_checker.py` warns when a referenced `<pattern>` lacks `data-pptx-pattern` and the converter will use its compatible `ltUpDiag` fallback; it still rejects `patternTransform` and values outside OOXML `ST_PresetPatternVal`. `shared-standards.md §7` documents the closed preset enum and color resolution from importer metadata or child paint- **LaTeX math formula rendering shipped** ([`scripts/latex_render.py`](../skills/ppt-master/scripts/latex_render.py)) — Strategist locks one of three policies (`mixed` / `render-all` / `text-only`) inside the Typography confirmation and writes an explicit `images/formula_manifest.json`; the renderer walks a codecogs → quicklatex → mathpad → wikimedia fallback chain and emits transparent PNGs that land in §VIII as `Acquire Via: formula` / `Status: Rendered` rows; formula-heavy decks (academic / engineering / educational) finally have a native rendering route. Formula selection is a Strategist decision — the renderer never scans source files for `$...$` markers-- **Live preview direct editing — L1 / L2 / L3** ([`workflows/live-preview.md`](../skills/ppt-master/workflows/live-preview.md)) — the browser editor gains deterministic in-place edits with no AI round-trip: text content (L1), presentation attributes like fill / stroke / font-size (L2), and on-canvas geometry (L3) — drag a selected element to move it, arrow-key nudge (`Shift` = 10px), multi-select, plus a right-click overlap picker for stacked shapes. Edits stage with `Ctrl+Z` undo + coalescing and write to `svg_output/` on **Apply changes**; moves persist through finalize / export (moved text frames, promoted multi-line tspans, repositioned icons all reproduce in the PPTX). Re-export stays chat-driven; on-canvas resize handles are not yet implemented (resize via the geometry inputs)+- **Live preview direct editing — L1 / L2 / L3** ([`workflows/stages/live-preview.md`](../skills/ppt-master/workflows/stages/live-preview.md)) — the browser editor gains deterministic in-place edits with no AI round-trip: text content (L1), presentation attributes like fill / stroke / font-size (L2), and on-canvas geometry (L3) — drag a selected element to move it, arrow-key nudge (`Shift` = 10px), multi-select, plus a right-click overlap picker for stacked shapes. Edits stage with `Ctrl+Z` undo + coalescing and write to `svg_output/` on **Apply changes**; moves persist through finalize / export (moved text frames, promoted multi-line tspans, repositioned icons all reproduce in the PPTX). Re-export stays chat-driven; on-canvas resize handles are not yet implemented (resize via the geometry inputs)### 2026-06 — Mode & visual-style dual catalogs + PPTX intake & content-strategy expansion-- **Replicate any PPTX's design → refill content route** ([`workflows/template-fill-pptx.md`](../skills/ppt-master/workflows/template-fill-pptx.md)) — when a user supplies an existing `.pptx` plus new material / a topic and asks to "reuse this deck's design / fill the content back in", this standalone workflow edits the PPTX directly and never enters the SVG generation pipeline. Output stays natively editable (it reuses the original slides' shapes / layouts, not a screenshot refill); it isolates private parts on reuse, exposes chart data, and runs capacity checks. Trigger follows the template rule — only on an explicit ask to reuse an existing deck — and it deliberately does not reflow / add pages / swap images (that's the from-scratch main route). Distinguished from Non-goals #53 below+- **Replicate any PPTX's design → refill content route** ([`workflows/template-fill-pptx.md`](../skills/ppt-master/workflows/template-fill-pptx.md)) — when a user supplies an existing `.pptx` plus new material / a topic and asks to "reuse this deck's design / fill the content back in", the Fill Native PPTX route edits the PPTX directly and never enters the SVG generation pipeline. Output stays natively editable (it reuses the original slides' shapes / layouts, not a screenshot refill); it isolates private parts on reuse, exposes chart data, and runs capacity checks. Trigger follows the template rule — only on an explicit ask to reuse an existing deck — and it deliberately does not reflow / add pages / swap images (that's the Generate PPTX route). Distinguished from Non-goals #53 below- **Three executors retired → mode + visual-style dual catalogs** ([`references/modes/`](../skills/ppt-master/references/modes/) + [`references/visual-styles/`](../skills/ppt-master/references/visual-styles/)) — the old three `executor-*.md` (general / consultant / consultant-top) entangled domain · audience · persuasion · narrative on one axis; split into two orthogonal catalogs (following the `image-renderings` pattern: flat dir + `_index` + on-demand read + Strategist locks one). **mode** = narrative skeleton (`pyramid` / `narrative` / `instructional` / `showcase`; consultant + top merge into pyramid since their narrative core is identical); **visual-style** = SVG layout aesthetic (`swiss-minimal` / `editorial` / `soft-rounded` / `dark-tech`, each paired with an image-rendering, **zero HEX** — color truth stays in confirmation e + image-palettes). Strategist `§d` locks `mode` + `visual_style` independently into `spec_lock`; Executor loads the two locked files; any mode × any style. Render coordinates stay in `templates/charts/`- **Prompt constraint-strength decoupling** ([`docs/rules/prompt-style.md`](rules/prompt-style.md) §4) — three explicit strength tiers — rule (`Hard rule` / `Forbidden`) / default (`Default — … may override`) / reference (`Reference — not a constraint`) — plus an "objective failure vs taste" test and a checker boundary, so the model can tell "must keep vs may deviate" at a glance; the visual-style catalog is Reference-strength throughout- **visual-style catalog grows to 18, aligned with image-renderings + examples reclaimed** — first four distilled from the [examples library](../examples/) (`brutalist` / `blueprint` / `memphis` / `zine`), then six filling in the hand-drawn / textured renderings that have a layout twin (`sketch-notes` / `ink-notes` / `chalkboard` / `paper-cut` / `vintage-poster` / `pixel-art`), then four more reclaimed from still-uncovered example aesthetics: `ink-wash` (rice-paper whitespace, from Cangzhuo / Li Ziqi) · `glassmorphism` (dark frosted-glass + gradient light, from glassmorphism_demo, split out of soft-rounded) · `photo-editorial` (full-bleed photography dominates, text captions, from Pritzker / fashion_weekly) · `data-journalism` (Bloomberg/Economist multi-column micro-charts + sidebars, from global_ai_capital). The catalog is regrouped into five families (corporate-product / editorial-publication / expressive-print / hand-drawn-brush / specialty). **The test**: a rendering earns a visual-style twin only when it defines a whole-page layout language, not merely how an inserted image looks — so photo-*led composition* gets `photo-editorial` (paired with corporate-photo), while purely atmospheric renderings (nature / warm-scene / fantasy-animation) stay imagery-only and just pair with a layout style. Zero HEX, Reference strength throughout- **mode catalog grows to 5: add `briefing`** — fills the "neutral information delivery" cell: no thesis, no story, no teaching, no spectacle — topic titles, even weight, complete and scannable, for status updates / reference decks / catalogs / meeting packs / FAQs that inform without arguing. The five now partition presentation *intent* more nearly MECE: persuade (pyramid) · tell a story (narrative) · teach (instructional) · impress (showcase) · simply inform (briefing). `_index` gains a `briefing` vs `pyramid` tie-breaker ("if you'd have to invent a thesis to fit pyramid, it's briefing"). Five presets plus a `custom` escape hatch for a bespoke direction none of them captures (a special cadence, a multi-mode fusion, a particular posture) — either user-requested or Strategist-recommended, confirmed like every lock; a deck always locks one value, and a fusion is one `custom` describing the acts. The only thing to avoid is defaulting to `custom` when a preset genuinely fits. Mirrors the truth-precedence rule that a user-authored outline or direction overrides the mode- **mode / visual-style system validated on real decks + four calibration tightenings landed** — the 5 modes + 18 visual-styles + the `custom` escape hatch were exercised on five covering decks (briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine, with the narrative deck going through the AI-image branch): **zero selection misses** (all four Close-calls tie-breakers fired and held against the real grey-zone pulls), **discipline fully honored** (zero HEX / Reference strength / whole-page layout language), **the `custom` mechanism works** (a `mode_behavior` prose paragraph carried a 10-page generation and reads as plain language at confirmation, not a bare token), **mode ⟂ visual_style holds** (any combination without bleed, including a positive check of the "keynote/launch = mode not style" route), export 5/5 decks × every page with 0 failures. Tightened four spots from the real signal: `strategist §e` now locks the full neutral tier set the visual_style implies up front (killing the mid-deck color top-ups seen in three consecutive decks), `executor-base §1` re-skins chart/layout template gradients-shadows-fills to the deck's visual_style (templates supply structure, not skin; mirror templates retain their declared prototype paint per §1.1), `briefing §1` makes `core_message` state coverage rather than a claim (briefing-only; global §IX assertion semantics stay for narrative/instructional/pyramid), and `svg_quality_checker` fixes font-family drift false positives (delimiter-matched capture + stack normalization) and drops the font-size ceiling for showcase mode and poster visual-styles-- **Optional spec-review checkpoint shipped** ([`workflows/refine-spec.md`](../skills/ppt-master/workflows/refine-spec.md)) — an opt-in pause after the Strategist confirmation stage: when the user explicitly asks (default OFF), the Strategist produces the full `design_spec.md` + `spec_lock.md`, then stops so the user can revise any part of the spec (outline / color / typography / layout / image strategy / page rhythm) before generation, keeping both files in sync. Same shape as the split-mode note — it never fires on its own, the default pipeline is unchanged, and it surfaces as one opt-in line inside the Strategist confirmation stage. Review lenses (logical clarity / information density / focus / register / emotional resonance / chapter balance + the design dimensions) give a direction only, never a numeric threshold (`Reference` strength). Prompted by [@cuberoocp](https://github.com/cuberoocp) in [issue #173](https://github.com/hugohe3/ppt-master/issues/173)+- **Optional spec-review checkpoint shipped** ([`workflows/stages/refine-spec.md`](../skills/ppt-master/workflows/stages/refine-spec.md)) — an opt-in pause after the Strategist confirmation stage: when the user explicitly asks (default OFF), the Strategist produces the full `design_spec.md` + `spec_lock.md`, then stops so the user can revise any part of the spec (outline / color / typography / layout / image strategy / page rhythm) before generation, keeping both files in sync. Same shape as the split-mode note — it never fires on its own, the default pipeline is unchanged, and it surfaces as one opt-in line inside the Strategist confirmation stage. Review lenses (logical clarity / information density / focus / register / emotional resonance / chapter balance + the design dimensions) give a direction only, never a numeric threshold (`Reference` strength). Prompted by [@cuberoocp](https://github.com/cuberoocp) in [issue #173](https://github.com/hugohe3/ppt-master/issues/173)- **Interactive visual Strategist confirmation stage page (Step 4)** ([`scripts/confirm_ui/server.py`](../skills/ppt-master/scripts/confirm_ui/server.py), field schema [`scripts/docs/confirm_ui.md`](../skills/ppt-master/scripts/docs/confirm_ui.md)) — the Strategist confirmation stage moves from chat-only to a browser page that auto-launches by default at Step 4. Template adherence appears only for deck/layout templates and defaults to `adaptive`: every page still maps to the template architecture, while unmatched compositions may create a new explicit Layout under the same Master. `strict` keeps the selected Layout contracts unchanged. The page shares port `5050` with Live Preview and writes authoritative choices to `result.json`.- **A batch of source-conversion fidelity gains** — less information dropped as source material enters the pipeline: `doc_to_md` converts Word OMML / Office Math equations to inline LaTeX, `pdf_to_md` recognizes `Figure N |` pipe-delimited captions, and `ppt_to_md` preserves hyperlinks already in the source deck (run-level external `[text](url)` / slide-internal jumps `[text](#slide-N)` / shape-level clicks, with dangerous-scheme filtering and anchor-text Markdown escaping) and transcribes native chart data into Markdown tables (values survive the conversion instead of collapsing to a single picture). Caption recognition is based on [@suay1113](https://github.com/suay1113)'s [PR #191](https://github.com/hugohe3/ppt-master/pull/191); hyperlink preservation is distilled from [@ZhaoZuohong](https://github.com/ZhaoZuohong)'s [PR #155](https://github.com/hugohe3/ppt-master/pull/155)-- **Content-faithful PPT beautification / re-layout shipped** ([`workflows/beautify-pptx.md`](../skills/ppt-master/workflows/beautify-pptx.md)) — mirror of `template-fill`: template-fill reuses a deck's design with new content, beautify keeps the content and redoes the layout. Given an existing PPTX, **every text string is preserved verbatim (nothing added / removed / reworded)**; it **extracts and inherits the source deck's visual identity (palette / fonts, `theme` or `observed` offered as two confirm-page candidates)** and redoes only layout / hierarchy / whitespace, strict 1:1 page count and order, with charts / tables regenerated natively from extracted data (values frozen) and source pictures re-laid-out. Technically still "generate a native, editable PPTX from scratch" (`ppt_to_md` extracts content → main pipeline → a brand-new deck), not a patch over the original, so it stays clear of Non-goals #53. Adds `beautify_identity.py` / `beautify_inventory.py`; the confirm page is seeded from the source for the user to review. Honest v1 ceiling: it does not relieve information overload (a crowded page improves within itself; true re-pagination is the main pipeline), does not guarantee coordinate-level paste-back, and combo / dual-axis / waterfall charts lose the un-captured plots+- **Content-faithful PPT beautification / re-layout profile shipped** ([`workflows/profiles/beautify-pptx.md`](../skills/ppt-master/workflows/profiles/beautify-pptx.md)) — a main-generation profile that mirrors `template-fill`: template-fill reuses a deck's design with new content, while beautify keeps the content and redoes the layout. Given an existing PPTX, **every text string is preserved verbatim (nothing added / removed / reworded)**; it **extracts and inherits the source deck's visual identity (palette / fonts, `theme` or `observed` offered as two confirm-page candidates)** and redoes only layout / hierarchy / whitespace, strict 1:1 page count and order, with charts / tables regenerated natively from extracted data (values frozen) and source pictures re-laid-out. Technically it remains the Generate PPTX route (`ppt_to_md` extracts content → main pipeline → a brand-new deck), not a patch over the original, so it stays clear of Non-goals #53. Adds `beautify_identity.py` / `beautify_inventory.py`; the confirm page is seeded from the source for the user to review. Honest v1 ceiling: it does not relieve information overload (a crowded page improves within itself; true re-pagination is the normal profile), does not guarantee coordinate-level paste-back, and combo / dual-axis / waterfall charts lose the un-captured plots- **Multi-deck PPTX intake + `analysis/` source-name prefixing** — a main-pipeline project can now combine several source decks: each writes its own `<stem>.identity.json` / `<stem>.slide_library.json`, with every deck's digest inlined under `decks[]` in the single index `source_profile.json` (preserving the "Strategist must-read `source_profile.json`" single-entry contract — one entry for a one-deck project, several for a combined one; re-importing the same stem replaces its entry). `beautify` / `template-fill` stay single-deck (1:1) and read their own `<stem>.*` artifacts-- **Material divergence (a free-text field under §c Audience)** — a main-pipeline content-strategy question added as a **free-text box** under the audience field: the user states in their own words how closely to follow the source vs how freely to reshape it (blank = balanced default). Deliberately not a fixed set of options, not recommended from analyzing the source, and not coupled to page count — it is purely the user's stated intent. However freely they ask, facts **stay sourced** — reorganize / reframe / expand / connect what is in the source, never import facts from outside it (that is the `topic-research` job). The Strategist reads the prose when authoring the §IX outline and records it in `design_spec §I`; it is **not** written to `spec_lock` (the Executor never reads it). `mode` and divergence are orthogonal. Beautify / template-fill freeze content and do not surface this field+- **Material divergence (a free-text field under §c Audience)** — a main-pipeline content-strategy question added as a **free-text box** under the audience field: the user states in their own words how closely to follow the source vs how freely to reshape it (blank = balanced default). Deliberately not a fixed set of options, not recommended from analyzing the source, and not coupled to page count — it is purely the user's stated intent. However freely they ask, facts **stay sourced** — reorganize / reframe / expand / connect what is in the source, never import facts from outside it (that is the `topic-research` stage's job). The Strategist reads the prose when authoring the §IX outline and records it in `design_spec §I`; it is **not** written to `spec_lock` (the Executor never reads it). `mode` and divergence are orthogonal. Beautify / template-fill freeze content and do not surface this field- **A batch of default-behavior and intake standardizations** — per-element entrance animation now defaults off (page transition `fade` only; element builds are opt-in via `-a auto` / `animations.json`), removing the auto-cascade "AI deck" tell; per-project `icons/` copies chosen icons into the project at selection time and embeds project-first; `analysis/` is established as the canonical must-read layer for machine-extracted facts (PPTX intake bundle + `image_analysis.csv`); the main pipeline treats a source deck's identity (palette / fonts / layout) as **reference, not constraint** (inherit or redesign by Strategist judgment, defaulting to fresh design); the confirm page gains a custom color input@@ -84,7 +84,7 @@ The past two months' structural capability growth. Single flags / incremental po- **`--native-charts-and-tables` hardened from dormant marker to usable opt-in** — the narrow native Chart/Table exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts_tables.pptx` to tell it apart from the default shape-based export. **The default route is unchanged** — charts/tables still export as editable SVG-derived DrawingML shapes for cross-renderer fidelity; PowerPoint-native Chart/Table objects add a data source and object-specific editing model and stay the deliberate opt-in trade documented under Non-goals below-- **Native package structure + mode-specific template creation** — deck/layout-template SVG pages declare their final Master/Layout identity while they are authored. Fixed Master/Layout visuals are root-level atoms, reusable slots are bounded top-level groups with real carriers or an explicit composite proxy, and zero-slot Layouts remain valid. Structured export deterministically compiles only that contract and performs final package read-back; it never promotes repeated chrome or infers placeholders. Flat free-design/brand-only export keeps all content Slide-local while replacing the stock Office scaffold with one clean project-owned Master and Blank Layout plus a deck-named current-lock theme. It removes title/body and other stock content, prunes unused Layouts, and retains only the standard date/footer/slide-number capability hooks. Both generated routes write the locked title plus a deterministic nine-level body hierarchy into Master `p:txStyles`, preserving paragraph and bullet settings. `standard` / `fidelity` author new SVG rosters and new Master/Layout systems without preserving or distilling source topology. `mirror` restores the complete supported source graph—including definition-only prototypes for unused Layouts—without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Lossless imports stay immutable in analysis as payload backing, while `authoring-svg/` plus its manifest form the editable template-creation IR. Library and project outputs share required `templates/`, optional `images/` / `icons/`, and optional on-demand review output in `exports/`; only library registration differs. Legacy baseline/template/preserve SVG packages first run `restore-pptx-structure`. Raw one-off PPTX filling remains `template-fill-pptx`.+- **Native package structure + mode-specific template creation** — deck/layout-template SVG pages declare their final Master/Layout identity while they are authored. Fixed Master/Layout visuals are root-level atoms, reusable slots are bounded top-level groups with real carriers or an explicit composite proxy, and zero-slot Layouts remain valid. Structured export deterministically compiles only that contract and performs final package read-back; it never promotes repeated chrome or infers placeholders. Flat free-design/brand-only export keeps all content Slide-local while replacing the stock Office scaffold with one clean project-owned Master and Blank Layout plus a deck-named current-lock theme. It removes title/body and other stock content, prunes unused Layouts, and retains only the standard date/footer/slide-number capability hooks. Both generation modes write the locked title plus a deterministic nine-level body hierarchy into Master `p:txStyles`, preserving paragraph and bullet settings. `standard` / `fidelity` author new SVG rosters and new Master/Layout systems without preserving or distilling source topology. `mirror` materializes a new workspace from the complete set of supported facts actually present in a native source package—including definition-only prototypes for unused Layouts—without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Lossless imports stay immutable in analysis as payload backing, while `authoring-svg/` plus its manifest form the editable template-creation IR. Library and project outputs share required `templates/`, optional `images/` / `icons/`, and optional on-demand review output in `exports/`; only library registration differs. Legacy baseline/template/preserve SVG packages are not migrated: use them only as visual reference while `create-template` authors a new workspace, then generate a new PPTX from that workspace. Raw one-off PPTX filling remains `template-fill-pptx`.- **Native-preset authoring guidance strengthened across roles** — using a real PowerPoint preset (`prstGeom`, with adjustment handles and the non-flat-card look) is reaffirmed as the default for stock geometry (block arrows, chevrons, banners, callouts, flowchart nodes, stars), not an exception. New pages and project-owned templates use the compact atomic `<g>` emitted by `preset_shape_svg.py`: the group owns the preset metadata and base paint once, while its direct visible paths are registry-derived layers with only necessary per-layer paint overrides. The authoring form has no hidden carrier, preview wrapper, or stored fingerprint; it is helper-only, and any change to preset, frame, adjustments, or paint regenerates the whole group instead of editing paths or metadata. A matching compact fragment may therefore live in `templates/charts/` when it expresses an intentional stock shape. The Executor still decides by object intent at draw time rather than scanning finished paths, and the paint boundary remains narrow: gradient fill/stroke or pattern fill stays ordinary SVG. PPTX import and `mirror` keep the separate expanded lossless representation. The Strategist continues to prime likely pages with a non-destructive `native-preset candidate` note; the Executor selects the exact preset, frame, and paint@@ -117,11 +117,11 @@ The directions below come up repeatedly and have been evaluated as **not on the**Issues**: [#53](https://github.com/hugohe3/ppt-master/issues/53), [#118](https://github.com/hugohe3/ppt-master/issues/118)-PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. A structured PPTX can now become a reviewed reusable package in two explicit ways: `standard` / `fidelity` author a new SVG and Master/Layout system from visual evidence, while `mirror` restores the complete supported source graph, including unused Layout definitions. Generic "open any PPTX and blindly refill every placeholder" remains a different product shape.+PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. A structured PPTX can inform a reviewed reusable package in two explicit ways: `standard` / `fidelity` author a new SVG and Master/Layout system from visual evidence, while `mirror` materializes a new workspace from the complete set of supported source facts actually present, including unused Layout definitions. Neither path modifies the source PPTX or recovers absent design intent. Generic "open any PPTX and blindly refill every placeholder" remains a different product shape.**The basic need is actually simple**: if you just need "replace Excel data into fixed positions in a PPT template", have the AI write a few lines of `python-pptx`. You don't need this pipeline.-> **Supported boundaries**: `template-fill-pptx` directly refills selected source slides. `create-template` either authors a new explicit SVG contract (`standard` / `fidelity`) or restores a supported source contract without semantic synthesis (`mirror`). Strict and adaptive downstream use the resulting declared contract to reconstruct native structure. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.+> **Supported boundaries**: Fill Native PPTX (`template-fill-pptx`) directly refills selected source slides. Create Template (`create-template`) either authors a new explicit SVG contract (`standard` / `fidelity`) or maps validated facts from a supported source contract into a new workspace without semantic synthesis (`mirror`). Strict and adaptive downstream compile the resulting declared contract into native structure. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.### Switch to native PowerPoint charts (Excel-native chart)diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 74de324f..9518dec3 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -201,7 +201,7 @@ The canonical exemplars to model new files after:| If you're writing... | Model after ||---|---|-| A role reference (Image_X / Strategist-style) | [`image-searcher.md`](../skills/ppt-master/references/image-searcher.md), [`strategist.md`](../skills/ppt-master/references/strategist.md) |-| A shared spec across roles | [`image-base.md`](../skills/ppt-master/references/image-base.md), [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) |-| A technical / format spec | [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md), [`svg-image-embedding.md`](../skills/ppt-master/references/svg-image-embedding.md), [`image-layout-spec.md`](../skills/ppt-master/references/image-layout-spec.md) |-| Workflow runbook | [`workflows/verify-charts.md`](../skills/ppt-master/workflows/verify-charts.md) |+| A role reference (Image_X / Strategist-style) | [`image-searcher.md`](../../skills/ppt-master/references/image-searcher.md), [`strategist.md`](../../skills/ppt-master/references/strategist.md) |+| A shared spec across roles | [`image-base.md`](../../skills/ppt-master/references/image-base.md), [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) |+| A technical / format spec | [`canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md), [`svg-image-embedding.md`](../../skills/ppt-master/references/svg-image-embedding.md), [`image-layout-spec.md`](../../skills/ppt-master/references/image-layout-spec.md) |+| Stage runbook | [`workflows/stages/verify-charts.md`](../../skills/ppt-master/workflows/stages/verify-charts.md) |diff --git a/docs/technical-design.md b/docs/technical-design.mdindex d657704b..fb498a98 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -59,9 +59,9 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)├── [Quality Check] svg_quality_checker.py (mandatory — 0 errors; warnings are non-blocking)└── Notes generation: complete speaker notes → notes/total.md↓-[Chart calibration (conditional)] → verify-charts workflow (required for decks containing data charts)+[Chart calibration (conditional)] → verify-charts stage (required for decks containing data charts)↓-[Visual self-check (optional, opt-in)] → visual-review workflow (only when the user explicitly requests it)+[Visual self-check (optional, opt-in)] → visual-review stage (only when the user explicitly requests it)↓[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py (defensive validation, then compilation)↓@@ -84,7 +84,7 @@ Output:For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority, but SVG here means project-canonical SVG accepted by the project contract—not any SVG a browser can render. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.-Minimal semantic markers do not weaken that closure. Free-design and brand-only pages use `pptx_structure.mode: flat`: every represented object stays Slide-local and no Master/Layout identity, layer, or placeholder metadata is authored. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks without promoting Slide content. On structured deck/layout-template routes, every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. Legacy structured/template projects whose structure contract is missing or uses an old form first run `restore-pptx-structure`; a flat project is intentionally unmapped, not legacy. Export never infers Master/Layout structure or placeholders.+Minimal semantic markers do not weaken that closure. Free-design and brand-only pages use `pptx_structure.mode: flat`: every represented object stays Slide-local and no Master/Layout identity, layer, or placeholder metadata is authored. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks without promoting Slide content. On structured deck/layout-template routes, every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. A semantic-legacy template package is not upgraded in place or accepted as a structured Step 3 input: create a new workspace through `create-template`, using a native PPTX's still-present package facts or an old SVG's visuals only as reference, then author new structured pages through the Generate PPTX route. A flat project is intentionally unmapped, not legacy. Export never infers, repairs, or migrates Master/Layout structure or placeholders.| Domain | Authority ||---|---|@@ -114,18 +114,18 @@ Use this table before reasoning about implementation details. Most failed runs s| Request shape | Route | Boundary ||---|---|---|-| Topic only, no source file or substantive source text | `topic-research` first, then main pipeline | web/source collection is a pre-pipeline step |-| Source files or conversation text, deck structure may be rethought | main SVG pipeline | Strategist may split, merge, drop, reorder, and redesign |-| PPTX as source material, user allows a new story/page structure | `ppt_to_md` + `pptx_intake`, then main SVG pipeline | PPTX identity/geometry are facts and candidates, not replica constraints |-| Raw PPTX template plus new material/topic | `template-fill-pptx` | clone/fill native slides; no SVG generation |-| Existing PPTX, preserve page count/order/wording 1:1, improve layout | `beautify-pptx` | regenerate through SVG; content and pagination are locked |-| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | `native-enhance-pptx` | direct OOXML patch; no design regeneration |-| User wants a reusable template workspace from a PPTX or design reference | `create-template` or `create-brand` | outputs a workspace root that later triggers Step 3; create-template can export an on-demand review PPTX |-| User supplies an explicit template path | main SVG pipeline Step 3 | current Brand/Layout/Deck workspaces resolve `templates/design_spec.md`; compatible legacy-flat roots resolve direct `design_spec.md`; restore only legacy SVG semantics |-| User asks to tune object-level animation order/effect/timing | `customize-animations` | optional export policy via `animations.json` |-| User asks to preview, select, annotate, or re-export browser edits | `live-preview` | browser workflow; annotations apply only at defined handoff points |--Ambiguous "optimize this PPT" requests reduce to one discriminator: preserve the original page count/order/wording, or treat the deck as source material and rebuild the story. Preserve means `beautify-pptx`; restructure means the main pipeline.+| Topic only, no source file or substantive source text | Generate PPTX + `topic-research` stage | web/source collection is a pre-pipeline stage |+| Source files or conversation text, deck structure may be rethought | Generate PPTX | Strategist may split, merge, drop, reorder, and redesign |+| PPTX as source material, user allows a new story/page structure | Generate PPTX via `ppt_to_md` + `pptx_intake` | PPTX identity/geometry are facts and candidates, not replica constraints |+| Raw PPTX template plus new material/topic | Fill Native PPTX (`template-fill-pptx`) | clone/fill native slides; no SVG generation |+| Existing PPTX, preserve page count/order/wording 1:1, improve layout | Generate PPTX + `beautify-pptx` profile | regenerate through SVG; content and pagination are locked |+| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Enhance Native PPTX (`native-enhance-pptx`) | direct OOXML patch; no design regeneration |+| User wants a reusable template workspace from a PPTX or design reference | Create Template (`create-template`) | the fixed entry dispatches one Create Brand, Create Layout, or Create Deck child workflow; the resulting workspace root later triggers Generate Step 3 and structured children may export a review PPTX |+| User supplies an explicit current-contract template path | Generate PPTX Step 3 | Brand/Layout/Deck workspaces resolve `templates/design_spec.md`; flat roots may resolve direct `design_spec.md`; semantic-legacy packages are rejected and replaced through Create Template |+| User asks to tune object-level animation order/effect/timing | Generate PPTX + `customize-animations` stage | optional export policy via `animations.json` |+| User asks to preview, select, annotate, or re-export browser edits | Generate PPTX + `live-preview` stage | annotations apply only at defined handoff points |++Ambiguous "optimize this PPT" requests reduce to one discriminator: preserve the original page count/order/wording, or treat the deck as source material and rebuild the story. Both use Generate PPTX; preservation selects the `beautify-pptx` profile, while restructuring uses the normal profile.---@@ -288,7 +288,7 @@ Templates are **opt-in, not default**. The default Strategist flow is free desig**Why default to free design.** Templates are floors that easily become ceilings: they lock the deck into the template's visual idioms regardless of how the content actually wants to be presented. Free-design layouts derive structure from the source content rather than imposing it from a fixed grammar, so the visual rhythm tracks the content rather than fighting it. Constrained mode is genuinely better in narrow cases (brand-locked decks, strongly-typed scenarios like academic defense or government report), so it stays available — but the AI doesn't proactively reach for it; the user does.-**Mechanical trigger, not semantic matching.** A bare name like `presentation_core`, a brand mention, or a style phrase such as "McKinsey style" does not trigger Step 3 even if a matching library directory exists. Step 3 consumes an explicit path. Current Brand/Layout/Deck workspaces resolve `templates/design_spec.md`; compatible legacy-flat packages resolve direct `design_spec.md`. Flat placement is not a reason to restore structure; only legacy Master/Layout/placeholder semantics trigger `restore-pptx-structure`. Discoverability is handled by template indexes and explicit Q&A ("what templates are available?"), not by runtime fuzzy matching.+**Mechanical trigger, not semantic matching.** A bare name like `presentation_core`, a brand mention, or a style phrase such as "McKinsey style" does not trigger Step 3 even if a matching library directory exists. Step 3 consumes an explicit path. Current Brand/Layout/Deck workspaces resolve `templates/design_spec.md`; compatible flat-directory packages resolve direct `design_spec.md` only when their SVGs already satisfy the current contract. Directory shape never authorizes structure migration. A package with legacy Master/Layout/placeholder semantics must be replaced by a newly created template workspace before Step 3. Discoverability is handled by template indexes and explicit Q&A ("what templates are available?"), not by runtime fuzzy matching.All current Brand/Layout/Deck packages use one workspace routing contract. Brand workspaces omit the SVG roster; empty optional directories are omitted:@@ -303,7 +303,7 @@ All current Brand/Layout/Deck packages use one workspace routing contract. Brand`<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or `projects/<name>/`. Step 3 receives that root. The workspace is portable between locations without reshaping; global index registration is the only scope-specific behavior. Empty optional directories are absent, and template application never copies `exports/`.-`standard` and `fidelity` write new SVG documents and a new Master/Layout/slot system; source topology is visual evidence only and is neither preserved nor distilled. `mirror` restores source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis. Because structural layers cannot be `<g>`, fixed-layer source group wrappers are mechanically expanded into direct atoms while preserving ownership, paint order, and appearance.+`standard` and `fidelity` write new SVG documents and a new Master/Layout/slot system; source topology is visual evidence only and is neither preserved nor distilled. `mirror` materializes a new workspace from the source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals that are actually present and validated, without semantic synthesis or gap filling. Because structural layers cannot be `<g>`, fixed-layer source group wrappers are mechanically expanded into direct atoms while preserving ownership, paint order, and appearance.The three template kinds own different segments of the design contract:@@ -341,9 +341,9 @@ PPT Master uses **role switching within one main agent** rather than parallel suThe pipeline is enforced by a 10-rule set in [`SKILL.md` § Global Execution Discipline](../skills/ppt-master/SKILL.md) — that file is authoritative; the rules live there. They look bureaucratic but exist because LLMs default to "let me solve the whole problem in this turn", which is exactly the wrong shape for a serial pipeline where each step's output is bounded, checkpointed, and consumed by the next. The rules collectively close failure modes that surfaced repeatedly in practice: out-of-order execution, AI proxying user design decisions, cross-phase bundling, missing prerequisites, speculative pre-work, sub-agent context loss, page-batching drift, long-deck color/font drift, batch/script-generated SVG drift, and routing ambiguity.-Common stop/continue recovery behavior is authoritative in [`failure-recovery.md`](../skills/ppt-master/workflows/failure-recovery.md); this section does not duplicate that matrix.+Common stop/continue recovery behavior is authoritative in [`failure-recovery.md`](../skills/ppt-master/workflows/governance/failure-recovery.md); this section does not duplicate that matrix.-Two newer rules are especially important to the architecture. First, Executor page SVGs must be hand-authored by the current main agent, one page at a time; writing a Python/Node/shell generator to emit pages is prohibited because the resulting deck loses cross-page judgment and visual continuity. Second, routing is deterministic: raw PPTX template requests, beautify requests, native enhancement, custom animation, live preview, and other workflow triggers are not turned into open-ended user route questions when the repository already defines the boundary.+Two newer rules are especially important to the architecture. First, Executor page SVGs must be hand-authored by the current main agent, one page at a time; writing a Python/Node/shell generator to emit pages is prohibited because the resulting deck loses cross-page judgment and visual continuity. Second, routing is deterministic: raw PPTX template requests, beautify-profile requests, native enhancement, custom-animation stages, live-preview stages, and other registered triggers are not turned into open-ended user route questions when the repository already defines the boundary.The Role Switching Protocol (mandated read of `references/<role>.md` before mode change) serves two reinforcing purposes: forcing fresh role instructions into context overrides drift from the previous mode, and the visible marker in the conversation transcript creates an audit trail so the user can see when the agent moved between modes — critical when reviewing why a particular decision was made.@@ -507,7 +507,7 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; when requested, create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is a self-contained visual-preview artifact rather than a PPTX source; users may insert it as an SVG picture, while PowerPoint's manual Convert to Shape command remains outside the supported contract.-**Why structure is authored before visual generation on template routes.** Master and Layout are not post-processing discoveries. On a structured deck/layout-template route, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. Free-design and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export — reusable structure is a template-route deliverable, not a free-design authoring tax. Legacy structured/template projects enter `restore-pptx-structure`; neither route triggers heuristic Master/Layout promotion or placeholder inference.+**Why structure is authored before visual generation on template routes.** Master and Layout are not post-processing discoveries. On a structured deck/layout-template route, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. Free-design and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export — reusable structure is a template-route deliverable, not a free-design authoring tax. Legacy inputs may inform a new `create-template` workspace, but they never enter an in-place structure-upgrade route; neither generation mode triggers heuristic Master/Layout promotion or placeholder inference.**Why Master/Layout visuals are atomic.** A Master or fixed Layout object must be one direct root child. Group-level transforms, opacity, styles, and z-order from imported PPTX objects are pushed into individual atoms during reconstruction. This deliberately gives up source group-editing hierarchy in exchange for a simple, deterministic ownership model that can be compared across pages and rebuilt into native parts without nested structural ambiguity.@@ -515,13 +515,13 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why reusable bounds are design zones, not measured text boxes.** Slot bounds come from the intended safe area, column, panel inset, or picture frame—not glyph width, line count, or the current content's tight box. The current Slide retains its own authored carrier geometry, so 4:6, 3:7, and 5:5 instances may share one Layout when they express the same semantic composition. Text length therefore cannot accidentally split or mutate the reusable Layout contract.-**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master and defines a new Layout only when fixed Layout atoms or slot topology/bounds change; the assignment is updated during page authoring rather than inferred later. A template-backed definition may remain unused and still register in the final package. Non-mirror skin remains project-controlled, while mirror keeps restored output visual identities.+**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master and defines a new Layout only when fixed Layout atoms or slot topology/bounds change; the assignment is updated during page authoring rather than inferred later. A template-backed definition may remain unused and still register in the final package. Non-mirror skin remains project-controlled, while mirror keeps the preserved output visual identities declared by its new workspace.**Why explicit-Layout text defaults are split between Master and Layout.** Both flat and structured export write the locked title size and a deterministic nine-level body hierarchy into Master defaults while preserving indentation and bullet settings. On structured routes, each generated Layout text slot additionally copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged.**Why structured output is read back before publication.** Metadata preflight cannot prove package serialization preserved every relationship and registration. Export therefore reopens the temporary PPTX and validates published Slides separately from the complete Master/Layout roster, including definitions unused by all Slides. It checks Presentation → Master → Layout → Slide registration, physical part/content-type rosters, picker identities, exact static-object order, placeholder type/effective index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts before publishing the file.-**Why template creation has authored and restoration modes.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `standard` / `fidelity` use those assets and visuals as references, then author a new topology from the confirmed reusable behavior. Mirror instead restores the source roster and topology one-to-one, allowing only mechanical normalization required by the explicit structured contract. The original PPTX remains analysis evidence, not a packaged export dependency.+**Why template creation has authored and preservation modes.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `standard` / `fidelity` use those assets and visuals as references, then author a new topology from the confirmed reusable behavior. Mirror instead materializes a new workspace from the validated source roster and topology one-to-one, allowing only mechanical normalization required by the explicit structured contract and never inventing absent facts. The original PPTX remains immutable analysis evidence, not a packaged export dependency.**Why create-template uses one workspace routing contract in both scopes.** `create-template` keeps `library` as its default indexed output and may instead write under an initialized project. Both roots require `templates/`; `images/`, `icons/`, and on-demand `exports/` appear only when they contain real files, and SVG asset references are identical. This makes the workspace migratable and reusable without a library-only package branch or a reduced project branch. The sole scope difference is global index registration, and both use the same `structured` contract.@@ -571,26 +571,18 @@ The tempting simplifications below have explicit costs. Treat them as negative c----## Standalone Workflows+## Routes and Supporting Runbooks-The standalone workflow registry is authoritative in [`workflows/index.md`](../skills/ppt-master/workflows/index.md); this section explains why these capabilities stay separate.+The authoritative registry is [`workflows/index.md`](../skills/ppt-master/workflows/index.md), with trigger precedence in [`workflows/routing.md`](../skills/ppt-master/workflows/routing.md). PPT Master has exactly four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. A user request enters one of those routes; no supporting runbook competes with them.-Standalone workflows are route definitions, not optional decorations. They exist when a capability has a different contract from the main pipeline or is too sparse to justify loading by default.+Supporting files stay separate only to keep route contracts focused and load optional context on demand:-| Workflow | Trigger | Contract |+| Class | Runbooks | Owning route ||---|---|---|-| `topic-research` | user provides only a topic and no source material | gather web materials before Step 1 |-| `template-fill-pptx` | raw PPTX template + new material/topic | direct native slide clone/fill; no SVG pipeline |-| `beautify-pptx` | existing PPTX, preserve page count/order/wording 1:1, improve layout | regenerate through SVG pipeline with source identity/content locked |-| `create-template` | build a reusable layout/deck template workspace | output a portable workspace root; optionally generate `exports/<id>_template_preview.pptx`; only library scope registers it |-| `create-brand` | extract or define a reusable brand identity | output `templates/brands/<id>/` |-| `resume-execute` | fresh chat after the planning session; user says to continue a project | enter the execution session without rerunning Strategist |-| `refine-spec` | user explicitly wants to review/refine the spec before generation | stop after full spec/lock for revision, then resume |-| `verify-charts` | generated deck contains data charts | calibrate chart geometry before export |-| `customize-animations` | user asks for object-level animation order/effect/timing | create/validate `animations.json` and re-export policy |-| `live-preview` | user asks to preview, click/select, apply annotations, or re-export browser edits | start/re-enter browser preview and apply submitted edits only at the defined point |-| `visual-review` | user explicitly requests per-page visual self-check | rubric pass between Executor and post-processing |-| `generate-audio` | user asks for narration/video export | produce narration audio and recorded timing export path |-| `native-enhance-pptx` | finished PPTX should keep existing content/layout while adding native enhancements | direct OOXML patch route |--Keeping these files separate is a dependency-control decision. The main path loads only the roles and references it actually needs; a narration backend, animation sidecar, chart calibration rubric, or template-import contract is pulled into context only when the trigger fires. That keeps the default deck-generation path tight while making the rarer capabilities deterministic rather than improvised.+| Generation profile | `beautify-pptx` | Generate PPTX with wording, page count, and page order frozen 1:1 |+| Template child workflows | `create-brand`, `create-layout`, `create-deck` | Create Template dispatches exactly one based on identity-only, structure-only, or integrated intent |+| Generation stages | `topic-research`, `resume-execute`, `refine-spec`, `verify-charts`, `visual-review`, `live-preview`, `customize-animations` | Generate PPTX at their defined intake, planning, editing, quality, or post-processing points |+| Shared stage | `generate-audio` | Generate PPTX post-processing or Enhance Native PPTX narration integration |+| Governance | `failure-recovery` | Stop/continue decisions across Generate PPTX stages |++This classification is a responsibility boundary, not a filename preference. A new top-level route is justified only by a distinct artifact lifecycle and mutation model; kind-specific execution inside Create Template remains a child workflow, while optional generation behavior remains a profile, stage, or governance document.diff --git a/docs/templates-architecture.md b/docs/templates-architecture.mdindex 7f715034..6fa01929 100644--- a/docs/templates-architecture.md+++ b/docs/templates-architecture.md@@ -10,11 +10,11 @@| Kind | Library workspace root | What it writes | What it does NOT write | Originating workflow ||---|---|---|---|---|-| **Brand** | `templates/brands/<id>/` | Identity segment only: color / typography / logo / voice / icon style | No canvas, page structure, SVG roster | `workflows/create-brand.md` |-| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template.md` (layout branch) |-| **Deck** | `templates/decks/<id>/` | All segments: identity + structure + middle (template overview) | — | `workflows/create-template.md` (deck branch, default) |+| **Brand** | `templates/brands/<id>/` | Identity segment only: color / typography / logo / voice / icon style | No canvas, page structure, SVG roster | `workflows/create-template/create-brand.md` |+| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template/create-layout.md` |+| **Deck** | `templates/decks/<id>/` | All segments: identity + structure + middle (template overview) | — | `workflows/create-template/create-deck.md` (default child) |-Every newly created or restored Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express. `standard` / `fidelity` author new SVGs and new structure without preserving or distilling source topology. Mirror restores the source roster, identities, parentage, placeholder facts, and supported visuals without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Strict keeps the selected declared Layout contract; adaptive retains the Master and may create a new Layout identity while authoring. Both export through `pptx_structure.mode: structured`. Packages with legacy Master/Layout semantics first run `restore-pptx-structure`; a legacy flat directory with `design_spec.md` at its root remains a supported compatibility shape and flat placement alone does not trigger restoration.+Every newly created Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express. `standard` / `fidelity` author new SVGs and new structure without preserving or distilling source topology. Mirror materializes a new workspace from validated authoring IR: a native PPTX contributes only supported facts still present in its package, while a current-contract SVG template contributes only its declared contract. It never reconstructs missing topology from a legacy SVG; fixed-layer source groups that are valid inputs are mechanically expanded into direct atoms. Strict keeps the selected declared Layout contract; adaptive retains the Master and may create a new Layout identity while authoring. Both export through `pptx_structure.mode: structured`. A flat directory with `design_spec.md` at its root remains a supported compatibility shape only when its SVGs satisfy the current contract. Semantic-legacy packages must be replaced by a newly created template workspace; they are never upgraded in place.The three are **parallel reference bundles**. In library scope, the physical directory and the frontmatter `kind` field correspond one-to-one:@@ -89,7 +89,7 @@ To make multi-path fusion override cleanly, every field belongs to a named segmeA deck is the **full identity + structure reference** derived from an existing PPT or confirmed design direction — its geometry, color palette, and typefaces form one coherent system. Its value is "validated cohesion", which a free layout + brand combo can't always reach.-Its construction depends on replication mode. `standard` / `fidelity` author a new system from visual reference; mirror restores source identities and parentage one-to-one. Once packaged, either form is a complete reference solution that can be overridden by an explicitly supplied brand or layout.+Its construction depends on replication mode. `standard` / `fidelity` author a new system from visual reference; mirror maps validated source identities and parentage one-to-one into a new workspace. Once packaged, either form is a complete reference solution that can be overridden by an explicitly supplied brand or layout.---@@ -324,7 +324,7 @@ This lets both AI and humans trace which segment came from where.## 5. Relationship with SKILL.md Step 3-**Trigger rule stays path-based** — an explicit workspace-root path is still required (see [[feedback-template-explicit-path-only]]), and bare names never trigger. Step 3 first resolves `<workspace>/templates/design_spec.md`; for compatibility, it also accepts a legacy flat root containing `<workspace>/design_spec.md`. Flat placement is only a directory-shape compatibility case. It does not trigger `restore-pptx-structure`; restoration is required only when the SVG contract has legacy semantics such as `native_structure_mode: template`, missing Master identity, direct atomic placeholders, or distillation-era markers. The only narrow handoff exception is a `create-template` run in the current conversation: after validation, it may pass its exact workspace root directly into Step 3. The `kind` field decides **how AI handles the path after triggering**:+**Trigger rule stays path-based** — an explicit workspace-root path is still required (see [[feedback-template-explicit-path-only]]), and bare names never trigger. Step 3 first resolves `<workspace>/templates/design_spec.md`; for directory-shape compatibility, it also accepts a flat root containing `<workspace>/design_spec.md` when the SVGs already satisfy the current contract. Packages using legacy semantics such as `native_structure_mode: template`, missing Master identity, direct atomic placeholders, or distillation-era markers are rejected; `create-template` must produce a new workspace before generation continues. The only narrow handoff exception is a `create-template` run in the current conversation: after validation, it may pass its exact workspace root directly into Step 3. The `kind` field decides **how AI handles the path after triggering**:| User path's `kind` | Step 3 action (per-kind branch) ||---|---|@@ -342,14 +342,16 @@ When a deck path is supplied, the user already has a complete solution; the Stra----## 6. Relationship with workflows+## 6. Relationship with routes and child workflows-| Workflow | Produces |+| Route or child workflow | Produces ||---|---|-| `workflows/create-brand.md` | identity-only brand workspace using the common routes; empty optional directories are omitted |-| `workflows/create-template.md` | complete layout or deck workspace. `standard` / `fidelity` author new semantic SVGs; mirror restores the source contract. Output scope is `library` by default (`templates/<kind>/<id>/` + registration) or `project` when confirmed (`projects/<name>/`, no registration). Both use the same optional-directory routing; preview PPTX is on demand for one Master and mandatory for multiple Masters. The internal kind branch still defaults to deck; explicit "structure only / drop the brand color" selects layout |+| `workflows/create-template.md` | Fixed Create Template entry and shared scope, confirmation, preflight, structured-authoring, registration, completion, and handoff contract; dispatches exactly one child workflow |+| `workflows/create-template/create-brand.md` | Identity-only Brand workspace; no SVG roster and empty optional directories are omitted |+| `workflows/create-template/create-layout.md` | Brand-neutral structural Layout workspace with a structured SVG roster |+| `workflows/create-template/create-deck.md` | Integrated identity-and-structure Deck workspace with a structured SVG roster; selected by default when both segments are requested |-In library scope, the frontmatter `kind` field determines which workspace parent is used under `templates/brands/` / `templates/layouts/` / `templates/decks/`. Project scope keeps the same kind semantics at the project workspace root. A complete workspace may migrate between scopes without reshaping; add or remove only the library index registration.+In library scope, the frontmatter `kind` field determines which workspace parent is used under `templates/brands/` / `templates/layouts/` / `templates/decks/`. Project scope keeps the same kind semantics at the project workspace root. A complete workspace may move between scopes without reshaping; add or remove only the library index registration.---diff --git a/docs/templates-guide.md b/docs/templates-guide.mdindex c5912b76..187d2a37 100644--- a/docs/templates-guide.md+++ b/docs/templates-guide.md@@ -1,6 +1,6 @@# Templates Guide: Use, Derive, and Boundaries-A PPT Master "template" is a **structure + style** preset bundle: complete standalone SVG pages whose metadata explicitly identifies one Master and Layout, atomic fixed-layer objects, and grouped content slots, plus `design_spec.md` and matching assets. Export deterministically reconstructs native PowerPoint structure from those SVGs.+A PPT Master "template" is a **structure + style** preset bundle: complete standalone SVG pages whose metadata explicitly identifies one Master and Layout, atomic fixed-layer objects, and grouped content slots, plus `design_spec.md` and matching assets. Export deterministically compiles that declared contract into native PowerPoint structure.This guide answers three questions:@@ -26,7 +26,7 @@ Send the Brand/Layout/Deck workspace root in your initial message. Anywhere in tFor every current template kind, the path is the **template workspace root**. Step 3 resolves `templates/design_spec.md`, then installs `templates/` plus any existing `images/` and `icons/` into the target project or consumes them in place when the workspace is already that project. It never copies `exports/`. Deck/Layout workspaces additionally validate the structured SVG contract. The path may point to a built-in library workspace under `skills/ppt-master/templates/<kind>/<id>/`, a project workspace under `projects/<name>/`, or another workspace with the same routing. A create-template run may hand its exact validated workspace root directly to Step 3 in the same conversation; this is the only exception to the initial-message rule.-> **Compatibility preflight:** Step 3 also accepts an older flat package with `design_spec.md` and SVGs directly at the supplied root. Flat placement by itself does not require restoration. Run [`restore-pptx-structure`](../skills/ppt-master/workflows/restore-pptx-structure.md) only when the SVGs use the former atomic-placeholder/unmapped Master/Layout semantics; Step 3 does not copy such a semantic-legacy package and defer migration.+> **Compatibility preflight:** Step 3 also accepts a flat-directory workspace with `design_spec.md` and SVGs directly at the supplied root, but only when those SVGs already satisfy the current contract. Flat placement by itself is harmless. Former atomic-placeholder, unmapped Master/Layout, and other semantic-legacy packages are rejected; run `create-template` to create a new workspace, then generate new structured pages from that workspace. Nothing upgrades the old package in place.### What does NOT trigger the template flow@@ -121,9 +121,11 @@ Please use the /create-template workflow to generate a new template based on theThe workflow will then **mandatorily** confirm a template brief with you before doing anything (this gate cannot be skipped).+The entry name always remains **Create Template**. It dispatches exactly one child workflow: Create Brand for identity only, Create Layout for brand-neutral structure only, or Create Deck for identity and structure together (the default when both are needed). The selected child is not reconsidered inside the brief.+### Step 1 — Prepare reference material-**Strongly recommended: hand over the original `.pptx` file.** The importer reads OOXML directly and extracts every Master, Layout, placeholder, theme, native-shape fact, and reusable asset into layered analysis references. In `standard` / `fidelity`, Template_Designer uses them as visual reference and authors a new SVG roster plus a new Master/Layout/slot system. In mirror, it restores source identities, parentage, placeholder facts, and supported visuals one-to-one. The original PPTX remains analysis evidence and is not packaged into the new template.+**Strongly recommended: hand over the original `.pptx` file.** The importer reads OOXML directly and extracts the Master, Layout, placeholder, theme, native-shape, and reusable-asset facts that are actually present and supported into layered analysis references. In `standard` / `fidelity`, Template_Designer uses them as visual reference and authors a new SVG roster plus a new Master/Layout/slot system. In mirror, it materializes those validated source facts into a new workspace without inventing missing topology or design intent. The original PPTX remains immutable analysis evidence and is not packaged into the new template.You can also design from scratch from a brand guideline: provide a logo, primary color HEX, fonts, tone description, and a few mood references — the AI will design the page skeletons on the spot. This suits brands that don't yet have a finished PPT, only a VI manual.@@ -137,16 +139,17 @@ The workflow does not silently infer values — before generation it lists these|-------|-------|| **Output scope** | `library` (default) or `project`; both use the same portable workspace routing, while only library scope registers it globally || **Target project** | Required only for `project`; give the exact initialized project path |+| **Selected child workflow** | Create Brand / Create Layout / Create Deck, fixed by the entry dispatch || **Template ID** | Portable template identity; in library scope it is also the directory / index key. Prefer ASCII slug like `acme_consulting`; non-ASCII names work but must be filesystem-safe || **Display name** | Human-readable name for documentation || **Category** | One of `brand` / `general` / `scenario` / `government` / `special` || **Use cases** | Annual report / consulting / defense / government briefing / ... || **Tone summary** | One line, e.g. "modern, restrained, data-driven" |-| **Theme mode** | Light / dark / gradient / ... |-| **Canvas format** | Default `ppt169` (16:9); specify other formats up front |-| **Replication mode** | `standard` (default compact roster) / `fidelity` (one variant per reusable semantic family) / `mirror` (one restored prototype per source slide). `standard` / `fidelity` author new SVG semantics; mirror restores source structure without synthesis. |-| **Native structure facts** | The brief reports source Master/Layout counts, parent relationships, placeholder identities, and multi-master status. `standard` / `fidelity` treat them as reference only; mirror restores them one-to-one through the current `structured` contract. |-| **Visual fidelity** | (required for `standard` / `fidelity` when a reference exists) `literal` (closely reproduce original geometry / decoration / sprite crops inside a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Cover / chapter / ending are usually `literal`. **Not asked for `mirror`** — mirror restores the source visual. |+| **Theme mode** | Create Layout/Create Deck only: light / dark / gradient / ... |+| **Canvas format** | Create Layout/Create Deck only; default `ppt169` (16:9), with other formats specified up front |+| **Replication mode** | Create Layout/Create Deck only: `standard` (default compact roster) / `fidelity` (one variant per reusable semantic family) / `mirror` (one materialized prototype per source slide). `standard` / `fidelity` author new SVG semantics; mirror preserves only validated facts already present in the source package. |+| **Native structure facts** | Create Layout/Create Deck only: the brief reports source Master/Layout counts, parent relationships, placeholder identities, and multi-master status. `standard` / `fidelity` treat them as reference only; mirror maps the supported facts one-to-one into the current `structured` contract. |+| **Visual fidelity** | Create Layout/Create Deck only; required for `standard` / `fidelity` when a reference exists. Choose `literal` or `adapted`. **Not asked for `mirror`** — mirror preserves the supported source visual. || **Keywords** | 3–5 tags for index lookup || Theme color / design notes / asset list | Optional — can be auto-extracted from the source |@@ -156,13 +159,13 @@ Before either scope writes final files, one hard preflight resolves the required> Why so strict? A template is a structural contract, whether it is reused globally or only inside the current project. Confirming ownership and geometry first avoids partial or misplaced output.-### Step 3 — `standard`, `fidelity`, or `mirror`?+### Step 3 — Create Layout/Create Deck: `standard`, `fidelity`, or `mirror`?-This is the most easily confused decision when deriving a template.+This is the most easily confused decision when deriving a structured template. Create Brand skips it because identity-only work has no SVG roster or native structure.| | **standard** | **fidelity** | **mirror** ||---|---|---|---|-| Output pages | 4–5 (cover / chapter / content / ending, with optional TOC) | one variant per reusable semantic family — count driven by the source | one restored prototype per source slide (1:1 roster) |+| Output pages | 4–5 (cover / chapter / content / ending, with optional TOC) | one variant per reusable semantic family — count driven by the source | one materialized prototype per source slide (1:1 roster) || Abstraction | High — clean, reusable skeleton | Medium — semantic source families redesigned with cleanup | None at the topology level; only mechanical structured-contract normalization || Authoring placeholders | Yes (`{{TITLE}}`, `{{CONTENT_AREA}}`, …) | Yes | Literal text may remain, but imported native content slots still carry semantic metadata || Best for | You want "tone + basic skeleton" to generate brand-new decks later | The source PPTX itself is a customized layout library and every variant matters | Someone else's polished deck is great as-is, you want every page available as a reference |@@ -198,8 +201,8 @@ After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-maste| Scope | Workspace root | Preview | Discovery behavior ||---|---|---|---|-| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Optional `exports/<id>_template_preview.pptx` | Register in the matching `layouts_index.json` or `decks_index.json` after validation |-| `project` | `projects/<name>/` | Optional `exports/<id>_template_preview.pptx` | Skip global index registration |+| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Create Brand: N/A; Create Layout/Create Deck: optional for one Master, mandatory for multiple Masters | Register in the matching `brands_index.json`, `layouts_index.json`, or `decks_index.json` after validation |+| `project` | `projects/<name>/` | Same kind-specific review behavior | Skip global index registration |Library registration makes the template **discoverable** — when someone asks "what templates are available?", the AI lists it from the index. To use either scope, follow the SKILL.md Step 3 rule: name the workspace root in your first message, for example `use this template: skills/ppt-master/templates/layouts/<your_template_id>/` or `use this template: projects/<name>/`. A project workspace can also be migrated or reused elsewhere because its core shape is identical; register it only if it is placed in the library and should appear in discovery.@@ -253,7 +256,7 @@ The result is not a private or reduced project-only format. You can point Step 3Common misconceptions to avoid:-- **A reusable template is an explicit SVG contract, not a packaged source PPTX.** Authored modes create that contract; mirror restores source ownership through it. Every page previews independently, and export compiles only declared Master/Layout/Slide structure+- **A reusable template is an explicit SVG contract, not a packaged source PPTX.** Authored modes create that contract; mirror maps validated source ownership facts into it. Every page previews independently, and export compiles only declared Master/Layout/Slide structure- **A template is not a "style skin".** It bundles structure (which blocks per page, how information is hierarchized) with style (colors, fonts, decoration). Trying to swap "skin" without structure tends to put the information architecture and the visuals at odds- **A template does not make content decisions for you.** The Strategist still decides per-page which layout to use and whether to extend a variant. Templates offer candidates, not predetermined results- **`fidelity` mode is not pixel-perfect copying.** Even with `literal` fidelity, the AI still strips noise and unnecessary repetition — geometry stays, redundancy goesdiff --git a/docs/zh/animations.md b/docs/zh/animations.mdindex 2c74d9cf..9f27fd8e 100644--- a/docs/zh/animations.md+++ b/docs/zh/animations.md@@ -15,7 +15,7 @@ PPT Master 导出的 PPTX 同时支持**页间转场**(page transition)与**页内元素动画默认关闭。为整份 deck 开启只需导出时加 `-a auto`(无需配置文件)。若需要更具体的演示节奏,例如标题先淡入、图表第二个出现、关键注释最后飞入,可以使用可选的 `animations.json` sidecar。SVG 仍然只保存静态视觉结构;sidecar 只控制 PPTX 导出动画。-当用户要求调整动画顺序、效果、时长或具体对象出现方式时,运行独立 [`customize-animations`](../../skills/ppt-master/workflows/customize-animations.md) 工作流。+当用户要求调整动画顺序、效果、时长或具体对象出现方式时,运行按需 [`customize-animations`](../../skills/ppt-master/workflows/stages/customize-animations.md) 阶段。```bash# 从真实顶层 <g id> 锚点生成可编辑模板diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 5e1cab1e..480d381e 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -15,7 +15,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg3. **一次问完,一次回答**。AI 在一条消息里同时问三件事——生成模式、音色、是否把音频嵌入回 PPTX——每项都标了推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。4. **执行**。脚本写出逐页音频到 `audio/`,再(如果你保留嵌入)重新导出带音频的 PPTX。不支持长音频导入或自动拆分。-完整流程见 [`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md)。+共享阶段见 [`workflows/stages/generate-audio.md`](../../skills/ppt-master/workflows/stages/generate-audio.md)。## 两条嵌入路径diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex a7ea2700..ba2b7868 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -10,7 +10,7 @@## Q: 只有一个主题或想法、没有任何资料,也能生成吗?-可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),AI 会自动启动 **topic-research 工作流**——通过网页搜索抓取权威来源(Wikipedia / 官网 / 机构发布),整理成 Markdown 资料文档 + 配图集后再走主流程生成幻灯片。+可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会自动运行 **topic-research 阶段**——通过网页搜索抓取权威来源(Wikipedia / 官网 / 机构发布),整理成 Markdown 资料文档 + 配图集后再走主流程生成幻灯片。效果取决于公开网页的覆盖度。如果你已有专业资料(论文、内部文档),直接把文件给 AI 比联网检索更准。@@ -218,7 +218,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t| 只留内容,设计与分页都重来 | **主管线** | 源事实;故事结构和页数都可重构 || 留内容 + 留设计 | 不必生成 | 直接用原文件 |-用 **beautify** 的前提是:原 PPT 的分页本身就是输出要求的一部分。文字逐字不动、页数页序 1:1 保留,只重排版式、层级和留白,并继承原配色字体。典型说法是「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify 工作流](../../skills/ppt-master/workflows/beautify-pptx.md)。+使用 **beautify profile** 的前提是:原 PPT 的分页本身就是输出要求的一部分。文字逐字不动、页数页序 1:1 保留,只重排版式、层级和留白,并继承原配色字体。典型说法是「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify profile](../../skills/ppt-master/workflows/profiles/beautify-pptx.md)。用 **主管线** 的前提是:原 PPT 只是内容材料。流程会用 `ppt_to_md` 抽成 Markdown,并读取 `analysis/` 里的 PPTX intake 事实,再由 Strategist 自由重构大纲(合页 / 拆页 / 换序)。典型说法是「用这份 PPT 的内容重做一份更好的」或「提炼成 10 页高管汇报」。@@ -244,9 +244,9 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息**第一步 — 准备参考材料**-**最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取主题色、字体、Master/Layout、placeholder type/idx、原生形状信息和可复用图片资源。`standard` 与 `fidelity` 把来源当作视觉参考,重新设计 SVG roster 和新的 Master/Layout/slot 系统,不保留、也不蒸馏来源拓扑。`mirror` 则按来源页序恢复 Master/Layout 身份与父子关系、placeholder 事实和受支持的视觉对象,不做语义归纳。由于结构层禁止 `<g>`,来源 Master/Layout 的 group wrapper 只允许机械展开成直接原子。+**最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取包内实际存在且受支持的主题色、字体、Master/Layout、placeholder type/idx、原生形状信息和可复用图片资源。`standard` 与 `fidelity` 把来源当作视觉参考,重新设计 SVG roster 和新的 Master/Layout/slot 系统,不保留、也不蒸馏来源拓扑。`mirror` 则把这些已验证的来源事实物化到新工作区,不做语义归纳或缺口补造。由于结构层禁止 `<g>`,来源 Master/Layout 的 group wrapper 只允许机械展开成直接原子。-完整导入 SVG 可以保留高级 PowerPoint 形状所需的 metadata、隐藏 carrier 和预览指纹,并作为载荷后备留在临时分析工作区且保持不可变。模板创建使用带文档内 source ref 和紧凑路径/hash manifest 的轻量可编辑 IR。`standard` / `fidelity` 创作项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化最终模板,只为未改且 hash 匹配的 Slide-local/slot ref 恢复转换器已经支持的载荷;不支持或已修改的对象保留当前 SVG fallback。+完整导入 SVG 可以保留高级 PowerPoint 形状所需的 metadata、隐藏 carrier 和预览指纹,并作为载荷后备留在临时分析工作区且保持不可变。模板创建使用带文档内 source ref 和紧凑路径/hash manifest 的轻量可编辑 IR。`standard` / `fidelity` 创作项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化最终模板,只为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已经支持的载荷;不支持或已修改的对象保留当前 SVG fallback。没有源 PPTX 时,截图集也能跑(`cover.png` / `toc.png` / `chapter.png` / `content.png` / `closing.png`),但保真度会明显下降。建议优先找原始 PPTX。@@ -264,7 +264,7 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息**第三步 — 等待完成**-AI 代理会自动完成后续工作——分析参考、构建布局定义并验证模板。如果你明确需要 PowerPoint 审阅文件,它还会按需生成 `exports/<id>_template_preview.pptx`。两种范围都要求 `templates/`,并使用可选的 `images/`、`icons/` 与 `exports/`:`library` 写入 `skills/ppt-master/templates/<kind>/<id>/` 并完成全局注册;`project` 写入 `projects/<name>/` 并跳过注册;空的可选目录直接省略。把这个工作区根目录交给 Step 3 即可,Step 3 不会复制 `exports/`,全局库的预览导出也由 Git 忽略。旧式平铺包仍可把 `design_spec.md` 放在根目录,目录平铺本身不要求恢复结构。+AI 代理会自动完成后续工作——分析参考、构建布局定义并验证模板。如果你明确需要 PowerPoint 审阅文件,它还会按需生成 `exports/<id>_template_preview.pptx`。两种范围都要求 `templates/`,并使用可选的 `images/`、`icons/` 与 `exports/`:`library` 写入 `skills/ppt-master/templates/<kind>/<id>/` 并完成全局注册;`project` 写入 `projects/<name>/` 并跳过注册;空的可选目录直接省略。把这个工作区根目录交给 Step 3 即可,Step 3 不会复制 `exports/`,全局库的预览导出也由 Git 忽略。根目录平铺 `design_spec.md` 的工作区只有在 SVG 已满足当前合同时才兼容;语义旧包必须通过 `create-template` 替换,不能原地升级。> **提示**:对风格和使用场景描述得越具体,生成的模板就越符合你的预期。diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.mdindex 4259ecfa..3f260928 100644--- a/docs/zh/getting-started.md+++ b/docs/zh/getting-started.md@@ -78,7 +78,7 @@PPT Master 最初是纯对话设计;可视化编辑是在很多用户提出后融入的(建立在 [@WodenJay](https://github.com/WodenJay) 的 [PR #85](https://github.com/hugohe3/ppt-master/pull/85) 之上)。-完整说明 → [实时预览工作流](../../skills/ppt-master/workflows/live-preview.md)+完整说明 → [实时预览阶段](../../skills/ppt-master/workflows/stages/live-preview.md)---diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex e331bd82..c954b2dc 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -6,7 +6,7 @@本指南从 PowerPoint 使用者的视角回答一个问题:**对于某项 PowerPoint 功能,项目中由什么表达承载,导出或回导时能保留什么?** 因此,PowerPoint 语义是唯一主索引,SVG 元素只作为某项 PowerPoint 能力的具体实现出现。-这是一份公开的能力与导入行为映射表,不是第二份生成 SVG 语法规范,也不承诺转换任意 SVG 或任意 OOXML。规范生成合同仍属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md);生成语法出现差异时,以该合同为准。PPTX 导入的恢复模式与用户可见降级由本文 §11 和[转换命令文档](../../skills/ppt-master/scripts/docs/conversion.md)负责,精确 parser 行为仍以实现代码为真值。本指南未列出的功能不会因此被默认为受支持。+这是一份公开的能力与导入行为映射表,不是第二份生成 SVG 语法规范,也不承诺转换任意 SVG 或任意 OOXML。规范生成合同仍属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md);生成语法出现差异时,以该合同为准。PPTX 导入的容错模式与用户可见降级由本文 §11 和[转换命令文档](../../skills/ppt-master/scripts/docs/conversion.md)负责,精确 parser 行为仍以实现代码为真值。本指南未列出的功能不会因此被默认为受支持。主路线编译的是**项目规范化 SVG**,而不是通用浏览器 SVG:@@ -32,7 +32,7 @@ PowerPoint 意图| `Direct preservation` | 直接 PPTX 工作流可以保留源 OOXML;主 SVG 编译器不重建它。 || `Unsupported` | 主生成路线没有已登记映射,不得猜测。 |-下文中的“回导”是指 PPTX-to-SVG 路线对语义的重建,而不是恢复原始 SVG 语法。它不承诺恢复原始 `<defs>` 图、`<use>` 结构、path 命令或 `<tspan>` 排版。+下文中的“回导”是指 PPTX-to-SVG 路线生成的语义投影,不是恢复原始 SVG 语法或补造缺失设计意图。它不承诺原始 `<defs>` 图、`<use>` 结构、path 命令或 `<tspan>` 排版。## 1. 演示文稿、幻灯片与坐标模型@@ -56,9 +56,9 @@ PowerPoint 意图|---|---|---|---|---|| 自由设计演示文稿结构 | `pptx_structure.mode: flat`;页面内容保持 Slide-local | 一个干净的项目 Master 和一个 Blank Layout,已表达对象留在 Slide | flat 路线包拓扑为 `Native-stable` | 禁止编写 Master/Layout/layer/placeholder metadata || 基于模板的演示文稿结构 | `pptx_structure.mode: structured` 加显式 Master/Layout/页面分配 | 声明的 `p:sldMaster`、`p:sldLayout`、注册与 Slide 父子关系 | 在显式结构合同内为 `Native-stable` | 导出器绝不猜测 Master、Layout 或占位符拓扑 |-| 幻灯片母版 | 根 Master 身份加原子级 `data-pptx-layer="master"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 可复用 Master part 与 picker 身份 | 源结构由模板/导入工作流恢复 | Master atom 必须为直接、稳定对象,并在所属页面间一致;普通组或 expanded authored 组不具备该资格 |-| 幻灯片版式 | 根 Layout 身份加原子级 `data-pptx-layer="layout"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 某个 Master 下的可复用 Layout part | 可恢复源 Layout;adaptive 创作可分配新 Layout | 仅当固定 atom 和 slot 合同完全相同时才复用 Layout key;普通组或 expanded authored 组不具备该资格 |-| 回导的继承图形可见性 | 分层分析记录规范化源布尔值;物化后的 structured mirror 在根写入精确小写的 `data-pptx-show-inherited-shapes` 与 `data-pptx-show-master-shapes` | 恢复 `p:sld@showMasterSp` 与 `p:sldLayout@showMasterSp` | `Native-stable`:Slide 为 false 时隐藏 Layout 与 Master 图形;Layout 为 false 时只隐藏 Master 图形 | 省略即 true;使用同一 Layout key 的页面必须使用相同 Layout 值。背景、Slide-local 对象、占位符继承、part 与父子关系保持不变 |+| 幻灯片母版 | 根 Master 身份加原子级 `data-pptx-layer="master"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 可复用 Master part 与 picker 身份 | Create Template mirror 可把来源包中已验证的事实保留到新工作区;创作模式使用新身份 | Master atom 必须为直接、稳定对象,并在所属页面间一致;普通组或 expanded authored 组不具备该资格 |+| 幻灯片版式 | 根 Layout 身份加原子级 `data-pptx-layer="layout"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 某个 Master 下的可复用 Layout part | Create Template mirror 可把已验证的源 Layout 保留到新工作区;adaptive 创作可分配新 Layout | 仅当固定 atom 和 slot 合同完全相同时才复用 Layout key;普通组或 expanded authored 组不具备该资格 |+| 回导的继承图形可见性 | 分层分析记录规范化源布尔值;物化后的 structured mirror 在根写入精确小写的 `data-pptx-show-inherited-shapes` 与 `data-pptx-show-master-shapes` | 把已声明来源值写入 `p:sld@showMasterSp` 与 `p:sldLayout@showMasterSp` | `Native-stable`:Slide 为 false 时隐藏 Layout 与 Master 图形;Layout 为 false 时只隐藏 Master 图形 | 省略即 true;使用同一 Layout key 的页面必须使用相同 Layout 值。背景、Slide-local 对象、占位符继承、part 与父子关系保持不变 || strict 模板 Layout | 选中的原型合同 | 保留现有已声明 Layout 拓扑 | 页面遵循原型时为 `Native-stable` | 不得改变固定 Layout atom 和 slot 结构 || adaptive 模板 Layout | 选定 Master 加显式的当前或新声明 Layout | 可在可复用结构变化时创建新 Layout 身份 | 更新 lock 与页面映射后为 `Native-stable` | 绝不默默改变已复用 Layout key || structured 模式以外的 Slide 背景填充 | 第一个合格的全幅 `<rect>`,可直接位于根下或位于简单单子组中,使用已登记纯色、线性/径向渐变或预设图案填充 | Slide 的原生 `p:bg` | 保真度遵循下文对应 paint 行 | transform、filter、clip、圆角、可见 stroke 或未映射 fill 会阻止提升 |@@ -96,7 +96,7 @@ PowerPoint 意图| 多边形 | `<polygon>` | 闭合自定义几何 | `Native-normalized` | points 必须有限且合法 || 折线 | `<polyline>` | 开放自定义几何 | `Native-normalized` | points 使用与其他生成几何相同的有限、已登记语法 || PowerPoint 预设形状 | 由 registry 生成的 compact `<g>`,由该组承载 preset 意图与基础 paint,并直接包含可见 `<path>` 子元素 | 一个可编辑 preset `p:sp` | preset 身份与 adjustment 可以经导入/导出保留 | 质检与导出动态重渲染 registry;规范创作表达不含隐藏 carrier、preview wrapper 或已存储 preview hash |-| 导入的预设形状 | 含隐藏原生 carrier、可见 preview 证据与新鲜度 metadata 的 expanded 导入/往返组 | payload 合法且未改变时恢复 preset | 在导入合同内为 `Native-stable` | 不支持的 preset 保留为显式诊断 fallback,不猜测几何 |+| 导入的预设形状 | 含隐藏原生 carrier、可见 preview 证据与新鲜度 metadata 的 expanded 导入/往返组 | payload 合法且未改变时重新接入 preset | 在导入合同内为 `Native-stable` | 不支持的 preset 保留为显式诊断 fallback,不猜测几何 || 动作按钮形状 | compact authored `actionButton*` preset 组 | 仅生成可见 preset 几何 | 形状几何可往返 | 不创建单击动作、导航目标或超链接 || 组 | `<g>` | `p:grpSp`,或对特殊 carrier 执行文档化的 flatten/collapse | 分组内容可重建为 `<g>` | 结构 atom 与 placeholder 合同优先于普通分组 || 复用本地 symbol | 已登记的同文档 `<use>` 合同或项目 icon placeholder | 在生成 Slide 中展开为可编辑 shape | 回导不承诺恢复原 symbol 图 | 拒绝外部 use、不受支持的 symbol 能力和结构 metadata 复用 |@@ -240,9 +240,9 @@ sidecar 工作流见 [`animations.md`](../../skills/ppt-master/references/animat| 受支持原生表格/图表 | 可见 fallback 加原生对象 metadata || 不支持的 graphic frame 或 SmartArt | 显式 preview、placeholder 或 unsupported 状态 |-这是语义重建,不是语法往返。Master/Layout 恢复属于模板结构工作流;普通视觉导入不会从 Slide 外观推断可复用拓扑。+这是语义投影,不是语法往返。只有 Create Template mirror 可把来源包中已验证的 Master/Layout 事实保留到新工作区;普通视觉导入不会从 Slide 外观推断可复用拓扑。-### 导入运行模式与恢复边界+### 导入运行模式与错误恢复边界`pptx_to_svg.py` 默认采用容错导入,因为输入来自用户或第三方 PPTX。`--strict` 用于 parser 开发、合同核验和复现第一个源文件违规点。生成 SVG 的严格校验与导出边界保持不变。@@ -250,11 +250,11 @@ sidecar 工作流见 [`animations.md`](../../skills/ppt-master/references/animat|---|---|---|---|| 可识别颜色语义带无关源 metadata | 规范化已识别颜色与 modifier | 拒绝非规范结构 | warning;可用时包含 part、Slide 与 shape 上下文 || 不支持的填充、轮廓、效果、图片填充、文字体或样式属性 | 保留对象,只省略不支持的属性或功能 | 在第一个违规点停止 | warning 说明省略内容与 fallback |-| 无法按属性恢复的不支持对象 | 只把该对象替换为可见诊断占位;没有可用 frame 时才省略 | 在第一个违规点停止 | warning 标识源对象 |+| 无法按属性映射的不支持对象 | 只把该对象替换为可见诊断占位;没有可用 frame 时才省略 | 在第一个违规点停止 | warning 标识源对象 || 不支持的 Slide 或 part 背景 | 省略该背景,继续当前页面/part | 在第一个违规点停止 | warning 标识所属 part |-| 损坏的包/XML 或缺失必需包结构 | 停止;不存在安全的页面级恢复 | 停止 | 整洁的命令错误,不输出裸 Python traceback |+| 损坏的包/XML 或缺失必需包结构 | 停止;不存在安全的页面级容错 | 停止 | 整洁的命令错误,不输出裸 Python traceback |-每次成功转换都会写入 `<output>/conversion-report.json`。报告记录运行模式、Slide 与 warning 数量、稳定原因码、源错误消息、采用的 fallback、包 part,以及可用时的 Slide 序号和 shape id/name/kind。因此,容错导入不是静默吞错:它尽可能保留可用输出,同时让每一次合同恢复都可复核。+每次成功转换都会写入 `<output>/conversion-report.json`。报告记录运行模式、Slide 与 warning 数量、稳定原因码、源错误消息、采用的 fallback、包 part,以及可用时的 Slide 序号和 shape id/name/kind。因此,容错导入不是静默吞错:它尽可能保留可用输出,同时让每一次合同降级都可复核。## 12. 校验职责diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex 7ac3f44c..df5ae056 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -21,20 +21,20 @@### 2026-04(管线规模化)-- **无源生成**:`topic-research` 工作流支持「只给主题、不给源文件」+- **无源生成**:`topic-research` 阶段支持「只给主题、不给源文件」- **PPTX 导出质变**:SVG clipPath → DrawingML picture geometry、marker → 原生箭头、输出归集到 `exports/`- **图表库 70 个 + 图标三库**(simple-icons / phosphor-duotone / brand-logo)- **`spec_lock.md` 机器可读契约**:Strategist 锁定后 Executor 每页强制重读,跨页一致性有了保证-- **元素级动画能力** + 旁白音频 / 视频导出([`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md));当前行为为按需开启,元素动画默认 `none`+- **元素级动画能力** + 旁白音频 / 视频导出([`workflows/stages/generate-audio.md`](../../skills/ppt-master/workflows/stages/generate-audio.md));当前行为为按需开启,元素动画默认 `none`### 2026-05(视觉编辑 + AI 图系统化)-- **Live Preview 进入主流程**([`workflows/live-preview.md`](../../skills/ppt-master/workflows/live-preview.md)) — 浏览器实时预览 + 点选元素写要求 + 「apply my annotations」让 AI 重做该区域(基于 [@WodenJay](https://github.com/WodenJay) [PR #85](https://github.com/hugohe3/ppt-master/pull/85))-- **任意 PPTX 复刻为模板**([`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md)) — PPTX → SVG 逆向 + OOXML 主题 / 母版 / 版式 / 资源提取+- **Live Preview 进入主流程**([`workflows/stages/live-preview.md`](../../skills/ppt-master/workflows/stages/live-preview.md)) — 浏览器实时预览 + 点选元素写要求 + 「apply my annotations」让 AI 重做该区域(基于 [@WodenJay](https://github.com/WodenJay) [PR #85](https://github.com/hugohe3/ppt-master/pull/85))+- **从原生 PPTX 创建新模板工作区**([`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md)) — 读取 OOXML 中实际存在且受支持的主题 / 母版 / 版式 / 资源事实,物化为新的模板合同;不修改来源 PPTX- **AI 图三维系统** rendering × palette × type + Strategist h.5 锁定,下游消费固定契约- **AI 图 `hero_page` 双档** — 局部插图 + 整页主角图共存-- **品牌身份预设子系统**([`workflows/create-brand.md`](../../skills/ppt-master/workflows/create-brand.md)) — 提取并复用品牌色板 / 字体 / Logo / 语调-- **视觉自检工作流**([`workflows/visual-review.md`](../../skills/ppt-master/workflows/visual-review.md)) — 按 rubric 逐页自查 AI 生成的 SVG+- **品牌身份预设子系统**([`workflows/create-template/create-brand.md`](../../skills/ppt-master/workflows/create-template/create-brand.md)) — 固定 Create Template 入口下的 Create Brand 子工作流,提取并复用品牌色板 / 字体 / Logo / 语调+- **视觉自检阶段**([`workflows/stages/visual-review.md`](../../skills/ppt-master/workflows/stages/visual-review.md)) — 按 rubric 逐页自查 AI 生成的 SVG- **AI 图 Type 概念边界澄清** — Type 收窄回「local 信息图的内部几何骨架」(11 个真骨架);原 4 个伪 type (hero/background/portrait/typography) 折回 `page_role: hero_page` + 4 条构图通则(single-subject / portrait / typographic / atmospheric);hero_page 文字分层规则(关键视觉词 embedded、可改文字走 SVG)- **Brutalist AI 报章示例 deck 交付**([`examples/ppt169_brutalist_ai_newspaper_2026/`](../../examples/ppt169_brutalist_ai_newspaper_2026/)) — P0 三档第一档落地:满版小字 + 不规则栏宽 + halftone 黑白图 + 单点红 + 真原生 shape,10 页编辑部年报实压「文字位置精度 + 跨页一致性」- **Kubernetes Blueprint 示例 deck 交付**([`examples/ppt169_kubernetes_blueprint_2026/`](../../examples/ppt169_kubernetes_blueprint_2026/)) — P0 三档第二档落地:等距工程图美学 + 蓝图青/琥珀色板 + 全手写 SVG 几何(无 raster 图)+ 自定义"逐笔绘制"动画,10 页 Kubernetes 架构走读实压「几何形状泛化 + chart 结构扩展性」@@ -42,25 +42,25 @@- **Template 架构三分类收口**([`docs/zh/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck 三独立目录 + 每类独立 schema + 段级合成 + git-style 冲突解决;SKILL.md Step 3 按 kind 分支处理,触发规则仍是「显式路径才触发」- **Pattern 填充 PPTX 安全网** — 被引用的 `<pattern>` 缺少 `data-pptx-pattern` 时,`svg_quality_checker.py` 现在给出 warning,转换器继续使用兼容的 `ltUpDiag` 回退;`patternTransform` 或超出 OOXML `ST_PresetPatternVal` 枚举的值仍然报错。`shared-standards.md §7` 落地了完整 preset 清单,以及从导入元数据或子元素 paint 解析颜色的合同- **LaTeX 数学公式渲染上线**([`scripts/latex_render.py`](../../skills/ppt-master/scripts/latex_render.py)) — Strategist 在 Typography 确认中锁定 `mixed` / `render-all` / `text-only` 三档策略,显式写 `images/formula_manifest.json`;脚本走 codecogs → quicklatex → mathpad → wikimedia 四源 fallback chain,输出透明 PNG 进 §VIII 表的 `Acquire Via: formula` / `Status: Rendered` 行;公式密集型 deck(学术 / 工程 / 教学)首次拥有原生渲染路径,规则面禁止扫源文件 `$...$` 自动渲染(公式选取是 Strategist 决策)-- **实时预览直接编辑 — L1 / L2 / L3**([`workflows/live-preview.md`](../../skills/ppt-master/workflows/live-preview.md)) — 浏览器编辑器新增无需 AI 往返的确定性就地编辑:文字内容(L1)、fill / stroke / font-size 等样式属性(L2)、以及画布上的几何操作(L3)——在选中元素上拖拽即移动、方向键微调(`Shift` = 10px)、多选、加右键重叠选择器选取堆叠元素。编辑支持 `Ctrl+Z` 撤销 + 合并,点 **Apply changes** 写回 `svg_output/`;移动经 finalize / 导出保位(移动的 text、提升的多行 tspan、重定位的 icon 都在 PPTX 中如实再现)。重新导出仍由对话触发;画布上的缩放手柄尚未实现(缩放走几何输入框)+- **实时预览直接编辑 — L1 / L2 / L3**([`workflows/stages/live-preview.md`](../../skills/ppt-master/workflows/stages/live-preview.md)) — 浏览器编辑器新增无需 AI 往返的确定性就地编辑:文字内容(L1)、fill / stroke / font-size 等样式属性(L2)、以及画布上的几何操作(L3)——在选中元素上拖拽即移动、方向键微调(`Shift` = 10px)、多选、加右键重叠选择器选取堆叠元素。编辑支持 `Ctrl+Z` 撤销 + 合并,点 **Apply changes** 写回 `svg_output/`;移动经 finalize / 导出保位(移动的 text、提升的多行 tspan、重定位的 icon 都在 PPTX 中如实再现)。重新导出仍由对话触发;画布上的缩放手柄尚未实现(缩放走几何输入框)### 2026-06(mode/视觉风格双 catalog + PPTX 入口与内容策略扩展)-- **任意 PPTX 复刻设计 → 内容回填路线**([`workflows/template-fill-pptx.md`](../../skills/ppt-master/workflows/template-fill-pptx.md)) — 用户给一份现成 `.pptx` 加新材料 / 主题、要求「复用这套 deck 的设计 / 把内容填回去」时,走这条独立工作流直接编辑 PPTX,不进 SVG 生成管线。输出仍是原生可编辑 PPTX(复用原 slide 的形状 / 版式而非截图回填),过程做私有部件隔离、暴露图表数据、容量校验;触发同模板规则——显式要求复用既有 deck 才进,刻意不做改版式 / 加页 / 换图(那是从零生成主路线的活)。与下文 Non-goals 的 #53 区分见该节+- **任意 PPTX 复刻设计 → 内容回填路线**([`workflows/template-fill-pptx.md`](../../skills/ppt-master/workflows/template-fill-pptx.md)) — 用户给一份现成 `.pptx` 加新材料 / 主题、要求「复用这套 deck 的设计 / 把内容填回去」时,Fill Native PPTX 路线直接编辑 PPTX,不进 SVG 生成管线。输出仍是原生可编辑 PPTX(复用原 slide 的形状 / 版式而非截图回填),过程做私有部件隔离、暴露图表数据、容量校验;触发同模板规则——显式要求复用既有 deck 才进,刻意不做改版式 / 加页 / 换图(那是 Generate PPTX 路线的职责)。与下文 Non-goals 的 #53 区分见该节- **三个 executor 退役 → mode + visual-style 双 catalog**([`references/modes/`](../../skills/ppt-master/references/modes/) + [`references/visual-styles/`](../../skills/ppt-master/references/visual-styles/)) — 原三个 `executor-*.md`(general / consultant / consultant-top)把「领域 · 受众 · 说服 · 叙事」捆在一条线;拆成两个正交 catalog(照 `image-renderings` 范式:扁平目录 + `_index` + 按需读 + Strategist 锁一个)。**mode** = 讲解骨架(`pyramid` / `narrative` / `instructional` / `showcase`,consultant + top 因叙事内核相同合并为 pyramid);**visual-style** = SVG 排版美学(`swiss-minimal` / `editorial` / `soft-rounded` / `dark-tech`,各 paired 一个 image-rendering,**零 HEX**——颜色真值守在 confirmation e + image-palettes)。Strategist `§d` 双层独立锁定 `mode` + `visual_style` 进 `spec_lock`,Executor 加载两个 locked 文件;任意 mode × 任意 style 自由组合,渲染坐标仍留 `templates/charts/`- **提示词约束强度三档解耦**([`docs/rules/prompt-style.md`](../rules/prompt-style.md) §4) — 规则(`Hard rule` / `Forbidden`)/ 默认(`Default — … may override`)/ 参考(`Reference — not a constraint`)三档显式化 + 「客观失败 vs 品味」判据 + checker 边界,让模型对「该守 vs 可破」一目了然;visual-style catalog 全程用 Reference 强度- **visual-style catalog 扩充至 18 个,与 image-renderings 对齐 + 示例库回收** — 先从[示例库](../../examples/)提炼 4 个(`brutalist` / `blueprint` / `memphis` / `zine`),再补齐 [`image-renderings`](../../skills/ppt-master/references/image-renderings/) 里有排版对应物的手绘 / 纹理风格 6 个(`sketch-notes` / `ink-notes` / `chalkboard` / `paper-cut` / `vintage-poster` / `pixel-art`),再回收示例库里仍未覆盖的独立气质:`ink-wash`(新中式水墨留白,源 藏拙 / 李子柒)· `glassmorphism`(深底磨砂玻璃 + 流光,源 glassmorphism_demo,从 soft-rounded 独立)· `photo-editorial`(满版摄影主导、文字点题,源 Pritzker / fashion_weekly)· `data-journalism`(Bloomberg/Economist 新闻信息图,多栏微图表 + 数据侧栏,源 global_ai_capital)。catalog 重组为 5 组(企业产品 / 编辑出版 / 表现印刷 / 手绘笔触 / 特殊)。**关键判据**:一个 rendering 升 visual-style 的前提是它定义「整页版面语言」而非「插入图的样子」——故 corporate-photo「摄影主导版面」该建(photo-editorial),而 nature / warm-scene / fantasy-animation 等纯氛围 rendering 仍只配对、不单建。全程零 HEX、Reference 强度- **mode catalog 扩档至 5 个:加 `briefing`** — 补上「中性信息平铺」这一格:无论点 / 无故事 / 不教学 / 不冲击,topic 标题、等权铺事实、完整可扫读,服务周报 / 参考册 / 目录 / 会议材料 / FAQ 这类「只告知不论证」的 deck。五个 mode 自此更接近 MECE 地切分**表达意图**:说服(pyramid)· 讲故事(narrative)· 教会(instructional)· 震住(showcase)· 只告知(briefing)。`_index` 加了 `briefing` vs `pyramid` 的灰区判据(「要不要造个 thesis 才塞得进 pyramid → 那就是 briefing」)。五个预设之外加一个 `custom` 兜底,承接预设盖不住的 bespoke 方向(特殊节奏 / 多 mode 融合 / 特定姿态)——用户点名**或策略师推荐**皆可,与所有锁一样由用户确认;一份 deck 永远只锁一个值,融合=一个 custom 描述多幕。唯一要避免的是「预设明明贴合却图省事甩 custom」。这与「用户自带大纲 / 方向覆盖 mode」是同一条真值优先原则-- **mode / visual-style 体系真实 deck 验证完成 + 四项校准收紧落地** — 5 mode + 18 visual-style + `custom` 逃生舱在 5 份覆盖性 deck 上跑过验证(briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine,其中 narrative 一份走 AI 图生成分支):**选型零误判**(四对 Close-calls 灰区引力全被触发且全抗住)、**纪律全落实**(零 HEX / Reference 强度 / 整页版面语言)、**custom 机制可用**(`mode_behavior` 散文段落撑过 10 页生成、能讲成大白话让用户确认)、**mode ⟂ visual_style 正交成立**(任意组合无串味,含「keynote/发布会=mode 不是 style」路由正面验证)、导出 5/5 deck × 全页 0 失败。据真实信号收紧四处:`strategist §e` 按 visual_style 预判中性档位一次锁全(消除连续三份的 Executor 中途补色)、`executor-base §1` 套模板页重皮到当前 visual_style(模板供结构不供皮,mirror 模板保持恢复后的视觉身份)、`briefing §1` 的 `core_message` = 本页覆盖什么而非证明什么(briefing 专属例外,全局 §IX 论断语义保留给 narrative/instructional/pyramid)、`svg_quality_checker` 修字体 drift 误报(按定界符匹配 + font-stack 归一化)+ 放宽 showcase mode 与 poster 类 visual-style 的字号上限-- **可选 spec 复核环节上线**([`workflows/refine-spec.md`](../../skills/ppt-master/workflows/refine-spec.md)) — 策略师确认阶段后新增一个 opt-in 停顿点:用户明确要求时(默认 OFF),Strategist 先产出完整 `design_spec.md` + `spec_lock.md`,停下来让用户对 spec 任意部分(大纲 / 配色 / 排版 / 版式 / 图片策略 / page rhythm)深入讨论修改,改完同步两个文件再进生成。与 split-mode 同构——不主动触发、默认管线零变化,仅在策略师确认阶段里多一行 opt-in 提示。复核视角(逻辑清晰度 / 信息密度 / 焦点 / 口语化 / 感染力 / 章节配比 + 各设计维度)只给方向、不落任何数字阈值(`Reference` 强度)。启发自 [@cuberoocp](https://github.com/cuberoocp) [issue #173](https://github.com/hugohe3/ppt-master/issues/173)+- **mode / visual-style 体系真实 deck 验证完成 + 四项校准收紧落地** — 5 mode + 18 visual-style + `custom` 逃生舱在 5 份覆盖性 deck 上跑过验证(briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine,其中 narrative 一份走 AI 图生成分支):**选型零误判**(四对 Close-calls 灰区引力全被触发且全抗住)、**纪律全落实**(零 HEX / Reference 强度 / 整页版面语言)、**custom 机制可用**(`mode_behavior` 散文段落撑过 10 页生成、能讲成大白话让用户确认)、**mode ⟂ visual_style 正交成立**(任意组合无串味,含「keynote/发布会=mode 不是 style」路由正面验证)、导出 5/5 deck × 全页 0 失败。据真实信号收紧四处:`strategist §e` 按 visual_style 预判中性档位一次锁全(消除连续三份的 Executor 中途补色)、`executor-base §1` 套模板页重皮到当前 visual_style(模板供结构不供皮,mirror 模板保持已声明的视觉身份)、`briefing §1` 的 `core_message` = 本页覆盖什么而非证明什么(briefing 专属例外,全局 §IX 论断语义保留给 narrative/instructional/pyramid)、`svg_quality_checker` 修字体 drift 误报(按定界符匹配 + font-stack 归一化)+ 放宽 showcase mode 与 poster 类 visual-style 的字号上限+- **可选 spec 复核环节上线**([`workflows/stages/refine-spec.md`](../../skills/ppt-master/workflows/stages/refine-spec.md)) — 策略师确认阶段后新增一个 opt-in 停顿点:用户明确要求时(默认 OFF),Strategist 先产出完整 `design_spec.md` + `spec_lock.md`,停下来让用户对 spec 任意部分(大纲 / 配色 / 排版 / 版式 / 图片策略 / page rhythm)深入讨论修改,改完同步两个文件再进生成。与 split-mode 同构——不主动触发、默认管线零变化,仅在策略师确认阶段里多一行 opt-in 提示。复核视角(逻辑清晰度 / 信息密度 / 焦点 / 口语化 / 感染力 / 章节配比 + 各设计维度)只给方向、不落任何数字阈值(`Reference` 强度)。启发自 [@cuberoocp](https://github.com/cuberoocp) [issue #173](https://github.com/hugohe3/ppt-master/issues/173)- **交互式可视化策略师确认页(Step 4)**([`scripts/confirm_ui/server.py`](../../skills/ppt-master/scripts/confirm_ui/server.py),字段 schema [`scripts/docs/confirm_ui.md`](../../skills/ppt-master/scripts/docs/confirm_ui.md)) — 模板遵循方式只在加载 Deck/Layout 模板时显示,默认推荐 `adaptive`:每页仍映射模板架构,无匹配构图时可在同一 Master 下创建新 Layout;`strict` 保持所选 Layout 契约不变。确认页与 Live Preview 共用端口,最终 `result.json` 对下游权威。- **源文档转换保真度提升一批** — 源材料进管线时更少丢信息:`doc_to_md` 把 Word 里的 OMML / Office Math 公式转成内联 LaTeX、`pdf_to_md` 识别 `Figure N |` 竖线分隔的图注、`ppt_to_md` 保留源 deck 已有的超链接(run 级外链 `[text](url)` / slide 内部跳转 `[text](#slide-N)` / shape 级点击,含危险 scheme 过滤与锚文本 Markdown 转义)并把原生图表数据转写成 Markdown 表格(数值随转换存活,不再只剩一张图)。图注识别基于 [@suay1113](https://github.com/suay1113) [PR #191](https://github.com/hugohe3/ppt-master/pull/191),超链接保留提炼自 [@ZhaoZuohong](https://github.com/ZhaoZuohong) [PR #155](https://github.com/hugohe3/ppt-master/pull/155)-- **内容保真的 PPT 美化 / 重排版上线**([`workflows/beautify-pptx.md`](../../skills/ppt-master/workflows/beautify-pptx.md)) — 与 `template-fill` 互为镜像:template-fill 复用某份 deck 的设计换新内容,beautify 反过来保留内容、重做版面。给一份现成 PPTX,**全部文字逐字保留(不增 / 不删 / 不改写)**,从源 deck 提取并**继承其视觉身份(配色 / 字体,`theme` 或 `observed` 两套候选过确认页)**,只重做版面 / 层级 / 留白;严格 1:1 页数页序,图表 / 表格从抽取数据原生重绘(数据冻结)、源配图重新排布。技术上仍走从零生成原生 PPTX 管线(`ppt_to_md` 抽内容 → 主管线 → 全新 deck),不补丁原文件,因此不碰 Non-goals #53。新增 `beautify_identity.py` / `beautify_inventory.py`,confirm 页全字段按源 seed 后用户复核。v1 天花板(诚实标注):不缓解信息过载(挤页只在页内改,真要重排分页属主管线)、不保证坐标级 paste-back、combo / dual-axis / waterfall 图丢未捕获的绘图层+- **内容保真的 PPT 美化 / 重排版 profile 上线**([`workflows/profiles/beautify-pptx.md`](../../skills/ppt-master/workflows/profiles/beautify-pptx.md)) — 它是 Generate PPTX 的一个 profile,与 `template-fill` 互为镜像:template-fill 复用某份 deck 的设计换新内容,beautify 反过来保留内容、重做版面。给一份现成 PPTX,**全部文字逐字保留(不增 / 不删 / 不改写)**,从源 deck 提取并**继承其视觉身份(配色 / 字体,`theme` 或 `observed` 两套候选过确认页)**,只重做版面 / 层级 / 留白;严格 1:1 页数页序,图表 / 表格从抽取数据原生重绘(数据冻结)、源配图重新排布。技术上仍走从零生成原生 PPTX 管线(`ppt_to_md` 抽内容 → 主管线 → 全新 deck),不补丁原文件,因此不碰 Non-goals #53。新增 `beautify_identity.py` / `beautify_inventory.py`,confirm 页全字段按源 seed 后用户复核。v1 天花板(诚实标注):不缓解信息过载(挤页只在页内改,真要重排分页属普通 profile)、不保证坐标级 paste-back、combo / dual-axis / waterfall 图丢未捕获的绘图层- **PPTX intake 多 deck 支持 + `analysis/` 源名前缀** — 主管线项目现在可把多份源 deck 合并进来:每份写 `<stem>.identity.json` / `<stem>.slide_library.json`,各自 digest 内联进单一索引 `source_profile.json` 的 `decks[]`(保住"Strategist 必读 `source_profile.json`"单入口契约,单 deck 即一条、多 deck 列多条;同 stem 重导覆盖该条)。`beautify` / `template-fill` 仍是 1:1 单 deck,按 stem 读自己那份 `<stem>.*`-- **材料发散度(§c 受众下的自由文字项)** — 主管线在 §c 受众文本框下加一个**纯文字**小问:用户用自己的话写要多贴源、还是多放开重塑(留空=平衡默认)。刻意不做固定档位、不按源信号替用户推荐、不联动页数——就是问用户本人意图。无论写得多放开都**事实守源**:只对源内内容重组 / 重框 / 展开 / 连结,绝不引入源外事实(那是 `topic-research` 的活)。Strategist 写 §IX 大纲时读这段 prose 消费、记 `design_spec §I`,**不进 spec_lock**(Executor 不读);`mode` 与发散度正交。beautify / template-fill 内容冻结,不暴露此项+- **材料发散度(§c 受众下的自由文字项)** — 主管线在 §c 受众文本框下加一个**纯文字**小问:用户用自己的话写要多贴源、还是多放开重塑(留空=平衡默认)。刻意不做固定档位、不按源信号替用户推荐、不联动页数——就是问用户本人意图。无论写得多放开都**事实守源**:只对源内内容重组 / 重框 / 展开 / 连结,绝不引入源外事实(那是 `topic-research` 阶段的职责)。Strategist 写 §IX 大纲时读这段 prose 消费、记 `design_spec §I`,**不进 spec_lock**(Executor 不读);`mode` 与发散度正交。beautify / template-fill 内容冻结,不暴露此项- **一批默认行为与入口标准化** — 逐元素入场动画默认关(只留转场 `fade`;元素动画改 opt-in `-a auto` / `animations.json`),消除"自动级联入场"的 AI 味;per-project `icons/` 在选择时把选中图标复制进项目、嵌入优先本地;`analysis/` 确立为机器抽取事实的 canonical 必读层(PPTX intake bundle + `image_analysis.csv`);主管线把源 deck 的身份(配色 / 字体 / 版式)当**参考而非约束**(可继承可重设,由策略师判断,默认从零设计);confirm 页支持自定义配色输入@@ -84,7 +84,7 @@- **`--native-charts-and-tables` 从休眠 marker 硬化为可用级 opt-in** — 那条窄「原生 Chart/Table」例外(见下文 Non-goals)现在导出的图表与纯文本表格会**保留 deck 自己的设计**,不再塌回 PowerPoint 的白底默认主题。classic 原生图表显式写入 chart-area / plot-area / 轴线 / 网格线 / 标签文字颜色——从可见的 SVG fallback 推断(最大面板型 `<rect>` → 背景、fallback 文字 → 标签、fallback 描边 → 轴线/网格),或用 `style` 显式覆盖(`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`,`"none"` 表透明);颜色解析把命名色、`#RGB` 简写、`rgb()` / `rgba()` 归一为 OOXML hex;bar/column 系列关掉负值反色,负值柱保持系列色。激活导出命名为 `<name>_<ts>_native_charts_tables.pptx`,以与默认形状导出区分。**默认路线不变**——图表/表格仍以可编辑的 SVG 派生 DrawingML 形状导出以保跨渲染器保真;PowerPoint 原生 Chart/Table 增加数据源和对象专属编辑模型,仍是下文 Non-goals 里那条刻意的 opt-in 取舍-- **原生 package 结构 + 按模式创建模板** — deck/layout-template SVG 页面在创作时就声明最终 Master/Layout 身份。固定 Master/Layout 视觉是根级原子,可复用槽位是带真实 carrier 或显式 composite proxy 的有界顶层 group,零槽位 Layout 也合法。`structured` 导出只确定性编译该合同并执行最终 package 回读;不提升重复 chrome,也不推断 placeholder。`flat` 自由设计 / brand-only 导出则保持所有内容 Slide-local,同时把 stock Office 脚手架替换成一个属于项目的干净 Master、一个 Blank Layout 和按 deck 命名的当前 lock 主题;删除 title/body 等 stock 内容、裁掉未使用 Layout,仅保留标准日期、页脚和页码能力钩子。两条生成路线都把锁定 title 与确定性的九级 body 层级写入母版 `p:txStyles`,同时保留段落和项目符号设置。`standard` / `fidelity` 重新创作 SVG roster 和新的 Master/Layout 系统,不保留、也不蒸馏来源拓扑。`mirror` 恢复完整且受支持的来源图谱,包括未使用 Layout 的定义专用原型;固定结构层的来源 group 只允许机械展开成直接原子,不做语义归纳。无损导入在分析区保持不可变并作为载荷后备,`authoring-svg/` 及其 manifest 则组成可编辑的模板创建 IR。`library` 与 `project` 都要求 `templates/`,`images/` / `icons/` 可选,`exports/` 仅在按需生成评审文件时出现;只有全局注册不同。旧 baseline/template/preserve SVG 包先运行 `restore-pptx-structure`;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。+- **原生 package 结构 + 按模式创建模板** — deck/layout-template SVG 页面在创作时就声明最终 Master/Layout 身份。固定 Master/Layout 视觉是根级原子,可复用槽位是带真实 carrier 或显式 composite proxy 的有界顶层 group,零槽位 Layout 也合法。`structured` 导出只确定性编译该合同并执行最终 package 回读;不提升重复 chrome,也不推断 placeholder。`flat` 自由设计 / brand-only 导出则保持所有内容 Slide-local,同时把 stock Office 脚手架替换成一个属于项目的干净 Master、一个 Blank Layout 和按 deck 命名的当前 lock 主题;删除 title/body 等 stock 内容、裁掉未使用 Layout,仅保留标准日期、页脚和页码能力钩子。两种生成模式都把锁定 title 与确定性的九级 body 层级写入母版 `p:txStyles`,同时保留段落和项目符号设置。`standard` / `fidelity` 重新创作 SVG roster 和新的 Master/Layout 系统,不保留、也不蒸馏来源拓扑。`mirror` 从原生来源包内实际存在的全部受支持事实物化新工作区,包括未使用 Layout 的定义专用原型;固定结构层的来源 group 只允许机械展开成直接原子,不做语义归纳。无损导入在分析区保持不可变并作为载荷后备,`authoring-svg/` 及其 manifest 则组成可编辑的模板创建 IR。`library` 与 `project` 都要求 `templates/`,`images/` / `icons/` 可选,`exports/` 仅在按需生成评审文件时出现;只有全局注册不同。旧 baseline/template/preserve SVG 包不做迁移:只把它们作为视觉参考,由 `create-template` 创作新工作区,再从新工作区生成新 PPTX;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。- **原生预设创作引导跨角色强化** — 用真正的 PowerPoint 预设(`prstGeom`,带调节手柄、非扁平卡片外观)被重申为库存几何(块箭头、chevron、横幅、标注、流程节点、星形)的**默认**而非例外。新页面与项目自有模板使用 `preset_shape_svg.py` 输出的 compact 原子 `<g>`:group 只写一次 preset metadata 与基础 paint,直接可见 path 是 registry 派生层,只保留必要的分层 paint 覆盖。创作形式没有 hidden carrier、preview wrapper 或持久化 fingerprint;只允许通过 helper 生成,preset、frame、adjustment 或 paint 任一变化都整体重生成,不手改 path 或 metadata。因此,当 compact 片段明确表达所需库存形状时,可以保存在 `templates/charts/` 中。Executor 仍按对象意图在画图当下决定,绝不扫描已完成路径;paint 边界保持收窄:渐变填充/描边或 pattern 填充仍用普通 SVG。PPTX 导入与 `mirror` 继续使用另一套 expanded 无损表达。Strategist 仍给可能适用的 §VII 页面追加非破坏性的 `native-preset candidate` 注记;具体 preset、frame 与 paint 由 Executor 选择@@ -117,11 +117,11 @@**对应 Issue**:[#53](https://github.com/hugohe3/ppt-master/issues/53)、[#118](https://github.com/hugohe3/ppt-master/issues/118)-PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。结构完整的 PPTX 现在可以通过两种显式方式形成经过确认的可复用模板包:`standard` / `fidelity` 以视觉证据为参考,创作新的 SVG 与 Master/Layout 系统;`mirror` 恢复完整且受支持的来源结构,包括未使用的 Layout 定义。但「打开任意 PPTX 后不经规范化就盲填所有占位框」仍是另一种产品形态。+PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。结构完整的 PPTX 可以通过两种显式方式为经过确认的可复用模板包提供依据:`standard` / `fidelity` 以视觉证据为参考,创作新的 SVG 与 Master/Layout 系统;`mirror` 把来源包内实际存在的全部受支持事实物化到新工作区,包括未使用的 Layout 定义。两者都不修改来源 PPTX,也不补造缺失的设计意图。但「打开任意 PPTX 后不经规范化就盲填所有占位框」仍是另一种产品形态。**基础诉求其实很简单**:如果只是「固定位置替换 Excel 数据到 PPT 模板」,直接让 AI 写一段 `python-pptx` 脚本即可,几行代码搞定,不需要本项目这套管线。-> **已支持边界**:`template-fill-pptx` 直接回填选中的源页面;`create-template` 或者创作新的显式 SVG 契约(`standard` / `fidelity`),或者在不做语义归纳的前提下恢复受支持的来源契约(`mirror`)。下游 `strict` / `adaptive` 都从这份已声明契约还原原生结构。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。+> **已支持边界**:Fill Native PPTX(`template-fill-pptx`)直接回填选中的源页面;Create Template(`create-template`)或者创作新的显式 SVG 契约(`standard` / `fidelity`),或者在不做语义归纳的前提下把受支持来源契约中的已验证事实映射进新工作区(`mirror`)。下游 `strict` / `adaptive` 都把这份已声明契约编译成原生结构。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。### 改用原生 PowerPoint 图表(Excel-native chart)diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 72ff49dd..f88fcae4 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -83,7 +83,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威,但这里的 SVG 专指通过项目合同校验的项目规范化 SVG,而不是任意浏览器可渲染的 SVG。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。-最小语义标记不会削弱这条闭包。自由设计与 brand-only 页面使用 `pptx_structure.mode: flat`:所有已表达对象保持 Slide 本地,不创作任何 Master/Layout 身份、分层或 placeholder metadata。导出器根据当前配色/字体 lock 生成一个属于本项目的干净 Master 和一个 Blank Layout,删除 title/body 等内置内容占位符与未使用的内置 Layout,仅保留标准日期、页脚和页码能力钩子,但不提升任何 Slide 内容。结构化 deck/layout 模板路线上,每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。结构合同缺失或使用旧形态的 legacy structured/template 项目必须先运行 `restore-pptx-structure`;flat 项目是有意不带 mapping,不算 legacy。导出器不做 Master/Layout 结构或 placeholder 推断。+最小语义标记不会削弱这条闭包。自由设计与 brand-only 页面使用 `pptx_structure.mode: flat`:所有已表达对象保持 Slide 本地,不创作任何 Master/Layout 身份、分层或 placeholder metadata。导出器根据当前配色/字体 lock 生成一个属于本项目的干净 Master 和一个 Blank Layout,删除 title/body 等内置内容占位符与未使用的内置 Layout,仅保留标准日期、页脚和页码能力钩子,但不提升任何 Slide 内容。结构化 deck/layout 模板路线上,每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。带旧结构语义的模板包不能原地升级,也不能作为 Step 3 的 structured 输入:先通过 `create-template` 创建新工作区;原生 PPTX 只提供包内仍然存在的事实,旧 SVG 只作为视觉参考;随后由 Generate PPTX 路线创作新的 structured 页面。flat 项目是有意不带 mapping,不算 legacy。导出器不推断、修补或迁移 Master/Layout 结构与 placeholder。| 领域 | 权威来源 ||---|---|@@ -115,18 +115,18 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使| 请求形态 | 路线 | 边界 ||---|---|---|-| 只有主题,没有源文件或足够源文本 | 先走 `topic-research`,再进入主流水线 | 网络 / 来源收集是前置步骤 |-| 有源文件或对话文本,deck 结构可以重想 | 主 SVG 流水线 | Strategist 可以拆分、合并、删除、重排和重设计 |-| PPTX 作为源材料,用户允许重构故事和页结构 | `ppt_to_md` + `pptx_intake`,再走主 SVG 流水线 | PPTX 身份和几何是事实与候选,不是复刻约束 |-| 原生 PPTX 模板 + 新材料 / 新主题 | `template-fill-pptx` | 克隆并填充原生页面;不生成 SVG |-| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | `beautify-pptx` | 通过 SVG 重新生成;内容和分页锁定 |-| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | `native-enhance-pptx` | 直接 OOXML patch;不重新设计 |-| 用户想从 PPTX 或设计参考构建可复用模板工作区 | `create-template` 或 `create-brand` | 输出后续能触发 Step 3 的工作区根目录;create-template 可按需导出审阅 PPTX |-| 用户提供明确模板路径 | 主 SVG 流水线 Step 3 | 当前 Brand/Layout/Deck 工作区均解析 `templates/design_spec.md`;兼容的旧式平铺包解析根目录 `design_spec.md`;只有旧 SVG 语义才恢复结构 |-| 用户要求调整对象级动画顺序 / 效果 / 计时 | `customize-animations` | 通过 `animations.json` 控制可选导出策略 |-| 用户要求预览、选择、注解或重导出浏览器编辑 | `live-preview` | 浏览器工作流;注解只在规定交接点应用 |--“优化这份 PPT”这类含糊请求归约为一个判定点:是否保留原始页数、页序和逐页措辞。保留就是 `beautify-pptx`;允许重构就是主流水线。+| 只有主题,没有源文件或足够源文本 | Generate PPTX + `topic-research` 阶段 | 网络 / 来源收集是前置阶段 |+| 有源文件或对话文本,deck 结构可以重想 | Generate PPTX | Strategist 可以拆分、合并、删除、重排和重设计 |+| PPTX 作为源材料,用户允许重构故事和页结构 | Generate PPTX,经 `ppt_to_md` + `pptx_intake` | PPTX 身份和几何是事实与候选,不是复刻约束 |+| 原生 PPTX 模板 + 新材料 / 新主题 | Fill Native PPTX(`template-fill-pptx`) | 克隆并填充原生页面;不生成 SVG |+| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | Generate PPTX + `beautify-pptx` profile | 通过 SVG 重新生成;内容和分页锁定 |+| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | Enhance Native PPTX(`native-enhance-pptx`) | 直接 OOXML patch;不重新设计 |+| 用户想从 PPTX 或设计参考构建可复用模板工作区 | Create Template(`create-template`) | 固定入口只分派一个 Create Brand、Create Layout 或 Create Deck 子工作流;所得工作区根目录后续触发 Generate Step 3,结构型子工作流可导出审阅 PPTX |+| 用户提供符合当前合同的明确模板路径 | Generate PPTX Step 3 | Brand/Layout/Deck 工作区解析 `templates/design_spec.md`;平铺根目录可解析直接 `design_spec.md`;语义旧包会被拒绝,并通过 Create Template 替换 |+| 用户要求调整对象级动画顺序 / 效果 / 计时 | Generate PPTX + `customize-animations` 阶段 | 通过 `animations.json` 控制可选导出策略 |+| 用户要求预览、选择、注解或重导出浏览器编辑 | Generate PPTX + `live-preview` 阶段 | 注解只在规定交接点应用 |++“优化这份 PPT”这类含糊请求归约为一个判定点:是否保留原始页数、页序和逐页措辞。两者都属于 Generate PPTX;保留时选择 `beautify-pptx` profile,允许重构时使用普通 profile。---@@ -201,7 +201,7 @@ SVG 胜出,因为它与 DrawingML 拥有相同的世界观:两者都是绝这张表只展示概念对应关系,不是对整个 SVG 标准的承诺,也不承诺所有映射语义无损。每项受支持能力都必须在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中拥有明确的映射记录,说明项目规范写法、允许的兼容输入、目标 DrawingML 表达、保真度和拒绝条件;涉及 PPTX 回导的能力还要说明来源 PPTX / OOXML 语义。映射状态可以是精确、确定性归一化、显式 fallback、sidecar 或 unsupported;讲稿、动画、relationships 等 package 语义不必强行塞进 SVG,但必须明确由哪条路线承载。-如需从 PowerPoint 功能出发逐项查看这些关系,请参阅 [PowerPoint 功能 ↔ 项目 SVG 映射指南](./powerpoint-svg-mapping.md)。该文档负责公开能力与 PPTX 导入恢复映射;`shared-standards.md` 继续负责生成 SVG 创作合同。+如需从 PowerPoint 功能出发逐项查看这些关系,请参阅 [PowerPoint 功能 ↔ 项目 SVG 映射指南](./powerpoint-svg-mapping.md)。该文档负责公开能力与 PPTX 导入语义映射;`shared-standards.md` 继续负责生成 SVG 创作合同。主生成路线采用**规范窄写入、受控兼容读取**。新生成的 `svg_output/` 与可复用模板只使用项目规范写法,例如不透明的六位大写 `#RRGGBB`,透明度放在对应的 `fill-opacity`、`stroke-opacity`、`stop-opacity`、`flood-opacity` 或原子元素 `opacity` 中。历史或人工输入只有在兼容合同明确登记、转换结果唯一且输出合法时才可继续导出;Checker 对这类写法给出非阻塞 warning,转换器在编译边界统一归一化。任何需要猜测、没有映射或可能产生损坏 PPTX 的表达都必须报 error。@@ -290,7 +290,7 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产**为什么默认自由设计。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),所以它一直在;但 AI 不主动去抓,是用户去抓。-**机械触发,不做语义匹配。** 像 `presentation_core` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,即使库里存在相似目录,也不会触发 Step 3。Step 3 只消费显式路径。当前 Brand/Layout/Deck 工作区均解析 `templates/design_spec.md`;兼容的旧式平铺包从根目录读取 `design_spec.md`。目录平铺本身不是恢复理由;只有旧 Master/Layout/placeholder 语义才触发 `restore-pptx-structure`。发现性交给模板索引和显式问答(“有哪些模板可以用?”),不交给运行时 fuzzy matching。+**机械触发,不做语义匹配。** 像 `presentation_core` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,即使库里存在相似目录,也不会触发 Step 3。Step 3 只消费显式路径。当前 Brand/Layout/Deck 工作区均解析 `templates/design_spec.md`;平铺目录只有在 SVG 已满足当前合同时,才兼容从根目录读取 `design_spec.md`。目录形态从不授权结构迁移;带旧 Master/Layout/placeholder 语义的包必须先替换为新建的模板工作区,才能进入 Step 3。发现性交给模板索引和显式问答(“有哪些模板可以用?”),不交给运行时 fuzzy matching。当前 Brand/Layout/Deck 都采用同一工作区路由合同;Brand 不含 SVG roster,空的可选目录直接省略:@@ -305,7 +305,7 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/`。Step 3 接收这个根目录。工作区可在两个位置之间迁移而不改形;唯一的范围差异是全局索引注册。空的可选目录不创建,`exports/` 也不会复制进新项目。-`standard` 与 `fidelity` 会重新创作 SVG 和新的 Master/Layout/slot 系统;来源拓扑只作为视觉证据,不保留、也不蒸馏。`mirror` 按来源页序恢复 Master/Layout 身份与父子关系、placeholder 事实和受支持视觉,不做语义归纳。由于结构层不能是 `<g>`,固定结构层的来源 group wrapper 只允许机械展开成直接原子,同时保持归属、paint order 和视觉一致。+`standard` 与 `fidelity` 会重新创作 SVG 和新的 Master/Layout/slot 系统;来源拓扑只作为视觉证据,不保留、也不蒸馏。`mirror` 把来源包内实际存在且已验证的页序、Master/Layout 身份与父子关系、placeholder 事实和受支持视觉物化到新工作区,不做语义归纳或缺口补造。由于结构层不能是 `<g>`,固定结构层的来源 group wrapper 只允许机械展开成直接原子,同时保持归属、paint order 和视觉一致。三类模板拥有不同的设计契约片段:@@ -325,7 +325,7 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产## 角色系统:单一流水线中的专业模式-PPT Master 用的是**单主代理内的角色切换**,不是并行子代理。Strategist、Image_Generator、Executor 以及各独立工作流模式,本质上都是按需加载的指令作用域;它们不是带着各自过期 deck 状态的独立 agent。这个选择有三条互相支撑的理由:+PPT Master 用的是**单主代理内的角色切换**,不是并行子代理。Strategist、Image_Generator、Executor,以及各路线中的 child workflow / profile / stage,本质上都是按需加载的指令作用域;它们不是带着各自过期 deck 状态的独立 agent。这个选择有三条互相支撑的理由:**为什么是单代理而非并行子代理。** 页面设计依赖完整的上游上下文——Strategist 的色彩选择、图片资源是否成功获取(还是失败被替代)、之前几页的视觉节奏。子代理拿到的只能是这个上下文的过期局部快照,产出的 deck 视觉会逐页漂。同一逻辑也禁止分批生成(比如一次 5 页):分批加速上下文压缩,deck 的视觉一致性下降速度比节省的速度更快——不划算。@@ -343,7 +343,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理流水线由 [`SKILL.md` § 全局执行纪律](../../skills/ppt-master/SKILL.md) 中的 10 条规则强制——那份文件是权威,规则住在那里。它们看起来很官僚,但存在的理由是:LLM 默认行为是“让我在这一 turn 里把整个问题搞定”,而这恰好是串行流水线最不该有的形状——串行流水线要求每一步的输出都是有界、过 checkpoint、被下一步消费的。这套规则共同关闭了实际反复出现的失败模式:乱序执行、AI 代为做用户设计决策、跨阶段打包、前置条件未满足、投机预先准备、子代理上下文丢失、分批漂移、长 deck 色彩字体漂移、脚本批量生成 SVG 漂移,以及路由歧义。-常见失败的停 / 继续规则以 [`failure-recovery.md`](../../skills/ppt-master/workflows/failure-recovery.md) 为准;本节不复制恢复矩阵。+常见失败的停 / 继续规则以 [`failure-recovery.md`](../../skills/ppt-master/workflows/governance/failure-recovery.md) 为准;本节不复制恢复矩阵。其中两条新边界尤其关键。第一,Executor 页面 SVG 必须由当前主代理逐页手写;禁止写 Python / Node / shell 生成器批量吐 SVG,因为这种输出会丢失跨页判断和视觉连续性。第二,路由是确定性的:原生 PPTX 模板、beautify、native enhancement、自定义动画、live preview 等触发条件已经在仓库里定义清楚时,不再额外抛给用户一个开放式路线选择题。@@ -505,11 +505,11 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器,简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和;这个性质在整体翻译下脆弱,在元素派发下稳健。-**为什么导入型与生成型 metadata 分层。** 导入 PPTX 时,完整 SVG 可以携带高级形状所需的 metadata、隐藏 carrier 和预览指纹,因此作为原生载荷后备留在临时分析工作区且保持不可变。`svg_authoring_view.py` 生成模板创建所用的可编辑 IR:轻量 SVG 通过文档内 source ref 标识对象,`authoring_manifest.json` 只记录路径与初始 hash,不重复保存原始载荷。`standard` / `fidelity` 创作项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化通过校验的模板,只为未改且 hash 匹配的 Slide-local/slot ref 恢复转换器已支持的 metadata;固定结构层保持直接原子,不支持或已修改的对象保留当前 SVG fallback,IR 专用 ref 不进入最终模板 SVG。+**为什么导入型与生成型 metadata 分层。** 导入 PPTX 时,完整 SVG 可以携带高级形状所需的 metadata、隐藏 carrier 和预览指纹,因此作为原生载荷后备留在临时分析工作区且保持不可变。`svg_authoring_view.py` 生成模板创建所用的可编辑 IR:轻量 SVG 通过文档内 source ref 标识对象,`authoring_manifest.json` 只记录路径与初始 hash,不重复保存原始载荷。`standard` / `fidelity` 创作项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化通过校验的模板,只为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已支持的 metadata;固定结构层保持直接原子,不支持或已修改的对象保留当前 SVG fallback,IR 专用 ref 不进入最终模板 SVG。**为什么只有一条 PPTX 编译路线。** Native 导出把作者 SVG 中受支持的元素逐个翻译成 DrawingML 形状。常规 deck 路线读取 `svg_output/`;用户需要时,create-template 对通过校验的模板原型调用同一 structured 编译器,生成 `exports/<id>_template_preview.pptx` 作为审阅证据。项目不会把整页 SVG 媒体或另一套位图渲染打包成第二类 PPTX。`svg_final/` 仍由常规 deck 的强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不为 PowerPoint 手工“转换为形状”提供兼容兜底。-**为什么模板路线的结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。在结构化 deck/layout 模板路线上,Strategist 在 SVG 生成前写出唯一 Master/Layout 定义和完整页面分配;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳——可复用结构是模板路线的交付物,不是自由设计的创作税。legacy structured/template 项目进入 `restore-pptx-structure`;两条路线都不会触发启发式 Master/Layout 提升或 placeholder 推断。+**为什么模板路线的结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。在结构化 deck/layout 模板路线上,Strategist 在 SVG 生成前写出唯一 Master/Layout 定义和完整页面分配;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳——可复用结构是模板路线的交付物,不是自由设计的创作税。旧输入可以为新的 `create-template` 工作区提供参考,但不存在原地升级结构的路线;两种生成模式都不会触发启发式 Master/Layout 提升或 placeholder 推断。**为什么 Master/Layout 视觉必须原子化。** 一个 Master 或固定 Layout 对象必须是根节点的直接子元素。导入 PPTX 时,group 的 transform、opacity、style 和 z-order 会下推到各个原子对象。这个选择有意放弃来源 group 的整体编辑层级,换取简单、可比较、可确定重建的结构归属,避免嵌套结构歧义。@@ -517,13 +517,13 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。-**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才定义新 Layout,并在页面创作时立即更新分配,而不是事后推断。模板定义即使暂时没有页面使用,也能注册进最终文件。非 mirror 的皮肤由项目控制;mirror 保持已恢复的输出视觉身份。+**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才定义新 Layout,并在页面创作时立即更新分配,而不是事后推断。模板定义即使暂时没有页面使用,也能注册进最终文件。非 mirror 的皮肤由项目控制;mirror 保持新工作区声明的已保留视觉身份。**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title 字号和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。**为什么 structured 输出要在发布前回读。** 元数据预检不能证明 package 序列化保留了所有 relationship 与注册信息。导出器会重新打开临时 PPTX,把已发布 Slide 与完整 Master/Layout roster 分开校验,包括没有任何 Slide 使用的定义;同时核对 Presentation → Master → Layout → Slide 注册链、物理 part/content-type roster、选择器身份、固定对象顺序、placeholder 类型/有效索引/bounds、carrier 绑定、隐藏 proxy 与零槽 Layout,只有通过后才发布。-**为什么模板创建分为创作模式和恢复模式。** `pptx_template_import.py` 输出分层 Master/Layout/Slide 参考和 native 结构事实。`standard` / `fidelity` 把这些素材和视觉当参考,再按照确认后的可复用行为创作新拓扑。Mirror 则一对一恢复来源 roster 与拓扑,只允许显式 structured 合同要求的机械归一化。原始 PPTX 保留为分析证据,不成为最终模板依赖。+**为什么模板创建分为创作模式和保留模式。** `pptx_template_import.py` 输出分层 Master/Layout/Slide 参考和 native 结构事实。`standard` / `fidelity` 把这些素材和视觉当参考,再按照确认后的可复用行为创作新拓扑。Mirror 则把已验证的来源 roster 与拓扑一对一物化到新工作区,只允许显式 structured 合同要求的机械归一化,不补造缺失事实。原始 PPTX 保持为不可变分析证据,不成为最终模板依赖。**为什么 create-template 在两种范围都使用同一工作区路由。** `create-template` 仍以写入索引的 `library` 为默认,也可写入已初始化项目。两种根目录都要求 `templates/`;`images/`、`icons/` 和按需生成的 `exports/` 只有存在真实内容时才出现,SVG 素材引用完全一致。因此工作区可直接迁移和复用,不需要全局库专用 package 分支或缩减的项目分支。唯一范围差异是全局索引注册,两种范围都使用同一 `structured` 合同。@@ -573,26 +573,18 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu----## Standalone Workflows(独立工作流)+## 顶层路线与支撑文档-独立工作流注册表以 [`workflows/index.md`](../../skills/ppt-master/workflows/index.md) 为准;本节解释为什么这些能力保持独立。+权威注册表是 [`workflows/index.md`](../../skills/ppt-master/workflows/index.md),触发优先级由 [`workflows/routing.md`](../../skills/ppt-master/workflows/routing.md) 负责。PPT Master 只有四条顶层产物路线:Generate PPTX、Create Template、Fill Native PPTX、Enhance Native PPTX。用户请求只能进入其中一条;任何支撑文档都不与它们竞争。-独立工作流是路线定义,不是可有可无的装饰。只有当某个能力与主流水线契约不同,或触发频率太低、不值得默认加载时,才会独立成 `workflows/<name>.md`。+支撑文件保持拆分,只是为了收紧路线合同,并在需要时加载可选上下文:-| 工作流 | 触发条件 | 契约 |+| 分类 | 文档 | 归属路线 ||---|---|---|-| `topic-research` | 用户只有主题、没有源材料 | 在 Step 1 前收集网络材料 |-| `template-fill-pptx` | 原生 PPTX 模板 + 新材料 / 新主题 | 直接克隆并填充原生页面;不进入 SVG 流水线 |-| `beautify-pptx` | 现有 PPTX,页数/页序/措辞必须 1:1 保留,只改善排版 | 锁定源身份与内容后,通过 SVG 流水线重新生成 |-| `create-template` | 构建可复用 layout/deck 模板工作区 | 输出可移植工作区根目录;可按需生成 `exports/<id>_template_preview.pptx`;只有全局库范围执行注册 |-| `create-brand` | 提取或定义可复用品牌身份 | 输出 `templates/brands/<id>/` |-| `resume-execute` | 规划会话后新开聊天,用户要求继续某项目 | 不重跑 Strategist,直接进入执行会话 |-| `refine-spec` | 用户明确要求生成前先审阅 / 修改 spec | 写出完整 spec/lock 后停下,用户修改后再恢复 |-| `verify-charts` | 生成 deck 含数据图表 | 导出前校准图表几何 |-| `customize-animations` | 用户要求调对象级动画顺序 / 效果 / 计时 | 创建 / 校验 `animations.json` 并控制再导出策略 |-| `live-preview` | 用户要求预览、点击选择、应用注解或重导出浏览器编辑 | 启动 / 重入浏览器预览,并只在规定时机应用提交内容 |-| `visual-review` | 用户明确要求逐页视觉自检 | 在 Executor 与后处理之间做 rubric pass |-| `generate-audio` | 用户要求旁白 / 视频导出 | 生成旁白音频并走录制计时导出路径 |-| `native-enhance-pptx` | 已完成 PPTX 要保留内容/布局,同时追加原生增强 | 直接 OOXML patch 路线 |--保持这些文件独立,是依赖控制决策。主路径只加载当前需要的角色和 reference;旁白 backend、动画 sidecar、图表校准 rubric、模板导入契约等,只有触发命中时才进入上下文。这样默认 deck 生成路径保持紧凑,同时让低频能力也有确定实现,而不是临场发挥。+| 生成 profile | `beautify-pptx` | Generate PPTX;逐字措辞、页数与页序 1:1 冻结 |+| 模板子工作流 | `create-brand`、`create-layout`、`create-deck` | Create Template 根据“仅身份 / 仅结构 / 身份与结构一体化”只分派其中一个 |+| 生成阶段 | `topic-research`、`resume-execute`、`refine-spec`、`verify-charts`、`visual-review`、`live-preview`、`customize-animations` | Generate PPTX 中各自定义的 intake、planning、editing、quality 或 post-processing 节点 |+| 共享阶段 | `generate-audio` | Generate PPTX 后处理,或 Enhance Native PPTX 的旁白集成 |+| 治理文档 | `failure-recovery` | Generate PPTX 各阶段的停止 / 继续决策 |++这种分类是职责边界,不是文件命名偏好。只有出现不同的产物生命周期和修改模型时,才新增顶层路线;Create Template 内按模板类型区分的执行归入子工作流,生成路线内的可选行为归入 profile、stage 或 governance。diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.mdindex 9ab3d27e..bbeaf743 100644--- a/docs/zh/templates-architecture.md+++ b/docs/zh/templates-architecture.md@@ -10,11 +10,11 @@| 分类 | 全局库工作区根目录 | 写什么 | 不写什么 | 出处工作流 ||---|---|---|---|---|-| **Brand** | `templates/brands/<id>/` | 仅身份段:color / typography / logo / voice / icon style | 不写 canvas、page structure、SVG roster | `workflows/create-brand.md` |-| **Layout** | `templates/layouts/<id>/` | 仅结构段:canvas / page structure / page types / SVG roster | 不写品牌身份(无 logo、无品牌色硬约束) | `workflows/create-template.md`(layout 分支)|-| **Deck** | `templates/decks/<id>/` | 全段:身份段 + 结构段 + 中间段(template overview) | —— | `workflows/create-template.md`(deck 分支,默认)|+| **Brand** | `templates/brands/<id>/` | 仅身份段:color / typography / logo / voice / icon style | 不写 canvas、page structure、SVG roster | `workflows/create-template/create-brand.md` |+| **Layout** | `templates/layouts/<id>/` | 仅结构段:canvas / page structure / page types / SVG roster | 不写品牌身份(无 logo、无品牌色硬约束) | `workflows/create-template/create-layout.md` |+| **Deck** | `templates/decks/<id>/` | 全段:身份段 + 结构段 + 中间段(template overview) | —— | `workflows/create-template/create-deck.md`(默认子工作流)|-每张新建或已恢复的 Layout/Deck SVG 都是完整预览,并在根节点声明 Master/Layout key 与选择器名称;固定 Master/Layout 视觉是直接原子元素;语义槽位是顶层 group。普通槽位必须有正数设计区域 bounds 和恰好一个兼容 carrier;复合 `object` 区域走显式 proxy 绑定,零槽 Layout 也合法。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为。`standard` / `fidelity` 重新创作 SVG 和新的结构,不保留、也不蒸馏来源拓扑。Mirror 按来源恢复 roster、身份、父子关系、placeholder 事实和受支持视觉,不做语义归纳;固定结构层的来源 group 只允许机械展开成直接原子。下游 `strict` 保持所选声明合同,`adaptive` 保持 Master 并可在创作时建立新 Layout 身份;两者都使用 `pptx_structure.mode: structured`。只有使用旧 Master/Layout 语义的包才必须先运行 `restore-pptx-structure`;旧包把 `design_spec.md` 平铺在根目录仍属于受支持的兼容目录形态,目录平铺本身不触发恢复。+每张新建的 Layout/Deck SVG 都是完整预览,并在根节点声明 Master/Layout key 与选择器名称;固定 Master/Layout 视觉是直接原子元素;语义槽位是顶层 group。普通槽位必须有正数设计区域 bounds 和恰好一个兼容 carrier;复合 `object` 区域走显式 proxy 绑定,零槽 Layout 也合法。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为。`standard` / `fidelity` 重新创作 SVG 和新的结构,不保留、也不蒸馏来源拓扑。Mirror 从已验证的 authoring IR 物化一个新工作区:原生 PPTX 只贡献包内仍然存在且受支持的事实;满足当前合同的 SVG 模板只贡献其已声明合同。它不会从旧 SVG 重建缺失拓扑;作为有效输入的固定结构层 group 只允许机械展开成直接原子。下游 `strict` 保持所选声明合同,`adaptive` 保持 Master 并可在创作时建立新 Layout 身份;两者都使用 `pptx_structure.mode: structured`。根目录平铺 `design_spec.md` 的目录只有在 SVG 已满足当前合同时才兼容;带旧结构语义的包必须替换为新建模板工作区,不能原地升级。三者是**三种并列的 reference bundle**。在全局库范围内,物理目录与 frontmatter `kind` 字段双向对齐:@@ -69,7 +69,7 @@ native_structure_mode: structured导入向量统一使用 `data-icon="imported/<name>"`,唯一规范文件位于 `icons/imported/<name>.svg`。具备工作区感知的校验与导出会直接解析这个根目录路径;`templates/icons/` 不属于模板包结构。-原生形状 metadata 采用两级模型。完整导入 SVG 保存 native metadata、隐藏 carrier 和预览证据,并作为不可变原生载荷后备;`svg_authoring_view.py` 生成可编辑 authoring IR,其中轻量 SVG 使用文档内 source ref 标识对象,manifest 只保存路径和初始 hash。创作模式使用项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化模板,仅为未改且 hash 匹配的 Slide-local/slot ref 恢复转换器已支持的载荷;固定结构层保持直接原子,不支持或已修改的对象保留 SVG fallback,最终模板不包含 IR 专用 ref。导出只编译声明的结构,不推断归属。+原生形状 metadata 采用两级模型。完整导入 SVG 保存 native metadata、隐藏 carrier 和预览证据,并作为不可变原生载荷后备;`svg_authoring_view.py` 生成可编辑 authoring IR,其中轻量 SVG 使用文档内 source ref 标识对象,manifest 只保存路径和初始 hash。创作模式使用项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化模板,仅为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已支持的载荷;固定结构层保持直接原子,不支持或已修改的对象保留 SVG fallback,最终模板不包含 IR 专用 ref。导出只编译声明的结构,不推断归属。两种范围都在可移植 frontmatter 中保留 `kind: layout` 或 `kind: deck`。`output_scope` 与 `target_project` 只属于工作流简报,不写入 `design_spec.md`。@@ -89,7 +89,7 @@ native_structure_mode: structuredDeck 是从一份现存 PPT 或明确设计方向形成的完整身份与结构参考——配色、字体、视觉节奏与页面类型共同组成一个整体。它的价值是「已验证的整体感」,是 layout + brand 自由拼合未必能达到的成品。-它的构建方式由 replication mode 决定:`standard` / `fidelity` 根据视觉参考创作新系统;mirror 一对一恢复来源身份与父子关系。打包完成后,两者都作为可被显式 brand / layout 覆盖的完整参考方案使用。+它的构建方式由 replication mode 决定:`standard` / `fidelity` 根据视觉参考创作新系统;mirror 把已验证的来源身份与父子关系一对一映射进新工作区。打包完成后,两者都作为可被显式 brand / layout 覆盖的完整参考方案使用。---@@ -316,7 +316,7 @@ AI: 你给了两个 brand,检测到段级冲突:## 五、与 SKILL.md Step 3 的关系-**触发规则仍以路径为准**——仍需显式工作区根目录路径(见 [[feedback-template-explicit-path-only]]),裸名称绝不触发。Step 3 先解析 `<workspace>/templates/design_spec.md`;为兼容旧包,也接受根目录直接包含 `<workspace>/design_spec.md` 的平铺形态。平铺只是目录兼容,不会触发 `restore-pptx-structure`;只有 SVG 合同仍使用 `native_structure_mode: template`、缺 Master 身份、原子 placeholder 或蒸馏时代标记时才需要恢复。唯一的窄例外是当前对话刚完成 `create-template`:验证通过后可把精确的工作区根目录直接交给 Step 3。`kind` 字段决定**触发后 AI 怎么处理**:+**触发规则仍以路径为准**——仍需显式工作区根目录路径(见 [[feedback-template-explicit-path-only]]),裸名称绝不触发。Step 3 先解析 `<workspace>/templates/design_spec.md`;为兼容目录形态,也接受根目录直接包含 `<workspace>/design_spec.md` 的平铺工作区,但其中 SVG 必须已经满足当前合同。若包仍使用 `native_structure_mode: template`、缺 Master 身份、原子 placeholder 或蒸馏时代标记等旧语义,Step 3 必须拒绝;先由 `create-template` 产出新工作区,再继续生成。唯一的窄例外是当前对话刚完成 `create-template`:验证通过后可把精确的工作区根目录直接交给 Step 3。`kind` 字段决定**触发后 AI 怎么处理**:| 用户路径指向 | Step 3 行为(按 kind 分支)||---|---|@@ -334,14 +334,16 @@ Deck 路径下用户已经拿到完整方案,策略师确认阶段收窄到"----## 六、与 workflows 的关系+## 六、与路线和子工作流的关系-| 工作流 | 产出 |+| 路线或子工作流 | 产出 ||---|---|-| `workflows/create-brand.md` | 使用统一路由的 identity-only brand 工作区;空的可选目录省略 |-| `workflows/create-template.md` | 完整 layout 或 deck 工作区。`standard` / `fidelity` 创作新语义 SVG,mirror 恢复来源合同。输出范围默认 `library`(`templates/<kind>/<id>/` + 注册),确认 `project` 时写 `projects/<name>/`(不注册)。两者使用相同的可选目录路由;单 Master 预览 PPTX 按需生成,多 Master 必须生成并通过 package gate。内部 kind 分支仍默认 deck,用户明说"只要结构 / 丢掉品牌色"时走 layout |+| `workflows/create-template.md` | 固定 Create Template 入口,以及范围、确认、预检、结构创作、注册、完成和交接的共享合同;只分派一个子工作流 |+| `workflows/create-template/create-brand.md` | 仅身份的 Brand 工作区;无 SVG roster,空的可选目录省略 |+| `workflows/create-template/create-layout.md` | 品牌中立、带结构化 SVG roster 的 Layout 工作区 |+| `workflows/create-template/create-deck.md` | 身份与结构一体化、带结构化 SVG roster 的 Deck 工作区;两段都需要时默认选择 |-在全局库范围,frontmatter `kind` 字段决定工作区父目录位于 `templates/brands/` / `templates/layouts/` / `templates/decks/`。项目范围在项目工作区根目录保留同一 kind 语义。完整工作区可在两种范围之间迁移而不改形,只需增加或移除全局索引注册。+在全局库范围,frontmatter `kind` 字段决定工作区父目录位于 `templates/brands/` / `templates/layouts/` / `templates/decks/`。项目范围在项目工作区根目录保留同一 kind 语义。完整工作区可在两种范围之间移动而不改形,只需增加或移除全局索引注册。---diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex 079828db..21bcb871 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -1,6 +1,6 @@# 模板指南:选用、派生与边界-PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG 都能独立完整预览,并用 metadata 显式标出 Master、Layout、Slide 与 placeholder;同时包含 `design_spec.md` 和配套素材。导出器据此确定性还原 PowerPoint 原生结构。+PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG 都能独立完整预览,并用 metadata 显式标出 Master、Layout、Slide 与 placeholder;同时包含 `design_spec.md` 和配套素材。导出器据此把已声明合同确定性编译成 PowerPoint 原生结构。本文回答三个问题:@@ -26,7 +26,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG对于当前所有模板类型,这里给的都是**模板工作区根目录**。Step 3 会解析其中的 `templates/design_spec.md`,然后把 `templates/` 及实际存在的 `images/`、`icons/` 安装进目标项目;如果工作区本来就是该项目根目录,则原地消费,并且始终不复制 `exports/`。Deck/Layout 还会校验 structured SVG 合同。路径可以指向 `skills/ppt-master/templates/<kind>/<id>/` 下的内置库工作区、`projects/<name>/` 下的项目工作区,或其他保持同样路由的工作区。当前对话刚完成 create-template 时,可把精确的已验证工作区根目录直接交给 Step 3;这是“首条消息显式路径”规则的唯一例外。-> **兼容性预检:** Step 3 也接受旧式平铺包,即 `design_spec.md` 与 SVG 直接位于所给根目录。目录平铺本身不需要恢复;只有 SVG 仍使用旧的原子 placeholder / 未映射 Master/Layout 语义时,才先运行 [`restore-pptx-structure`](../../skills/ppt-master/workflows/restore-pptx-structure.md)。Step 3 不会先复制语义旧包、再延后恢复。+> **兼容性预检:** Step 3 也接受 `design_spec.md` 与 SVG 直接位于所给根目录的平铺工作区,但这些 SVG 必须已经满足当前合同。目录平铺本身没有问题;旧的原子 placeholder、未映射 Master/Layout 等语义旧包会被拒绝。先运行 `create-template` 创建新工作区,再从该工作区生成新的 structured 页面;不会原地升级旧包。### 什么**不会**触发模板流程@@ -121,9 +121,11 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG接下来工作流会**强制**先和你确认一份模板简报(不允许跳过)。+入口名称始终保持 **Create Template**。它只分派一个子工作流:仅复用身份走 Create Brand,仅复用品牌中立的结构走 Create Layout,身份与结构一起复用走 Create Deck(两者都需要时默认选它)。子工作流一旦选定,不会在简报里再次选 kind。+### 第一步:准备参考材料-**强烈推荐:直接给原始 `.pptx` 文件。** 导入器会读取 OOXML,提取全部 Master、Layout、placeholder、主题、原生形状事实与可复用素材,并生成分层分析参考。`standard` / `fidelity` 把它们当视觉参考,创作新的 SVG roster 与 Master/Layout/slot 系统;mirror 则一对一恢复来源身份、父子关系、placeholder 事实和受支持视觉。原 PPTX 只作分析证据,不进入新模板包。+**强烈推荐:直接给原始 `.pptx` 文件。** 导入器会读取 OOXML,把包内实际存在且受支持的 Master、Layout、placeholder、主题、原生形状与可复用素材事实提取成分层分析参考。`standard` / `fidelity` 把它们当视觉参考,创作新的 SVG roster 与 Master/Layout/slot 系统;mirror 则把这些已验证的来源事实物化到新工作区,不补造缺失拓扑或设计意图。原 PPTX 始终是不可变的分析证据,不进入新模板包。也可以基于品牌指南从零设计:提供 logo、主色 HEX、字体、调性描述、几张氛围参考图,AI 会现场设计页面骨架。适合品牌方还没有成型 PPT、只有 VI 手册的场景。@@ -137,16 +139,17 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG|------|------|| **输出范围** | `library`(默认)或 `project`;两者使用相同的可移植工作区路由,只有 library 会进入全局索引 || **目标项目** | 仅 `project` 必填;必须给出已初始化项目的精确路径 |+| **已选子工作流** | Create Brand / Create Layout / Create Deck,由入口分派后固定 || **模板 ID** | 模板的可移植身份;在 `library` 下同时也是目录名 / 索引键。优先 ASCII slug,如 `acme_consulting`;中文品牌名也行,但要文件系统安全 || **显示名称** | 文档中的人类可读名 || **类别** | `brand` / `general` / `scenario` / `government` / `special` 五选一 || **适用场景** | 年报 / 咨询 / 答辩 / 政府汇报…… || **调性概要** | 一句话,如"现代克制、数据驱动" |-| **主题模式** | 浅色 / 深色 / 渐变…… |-| **画布格式** | 默认 `ppt169`(16:9),其他格式需提前指定 |-| **复刻模式** | `standard`(默认精简基本套)/ `fidelity`(每个可复用语义家族一个变体)/ `mirror`(每张源页一个恢复原型)。`standard` / `fidelity` 创作新 SVG 语义;mirror 恢复来源结构,不做归纳。 |-| **原生结构事实** | 简报会列出源 Master/Layout 数量、父子关系、placeholder 身份和多母版情况。`standard` / `fidelity` 只把它们当参考;mirror 通过当前 `structured` 合同一对一恢复。 |-| **保真级别** | (`standard` / `fidelity` 有源时必填)`literal`(在新创作结构内尽量复现原几何、装饰和精灵图裁剪)/ `adapted`(借调性与构图、允许设计演化)。封面 / 章节 / 结尾通常用 `literal`。**`mirror` 模式不询问**——它恢复来源视觉。 |+| **主题模式** | 仅 Create Layout/Create Deck:浅色 / 深色 / 渐变…… |+| **画布格式** | 仅 Create Layout/Create Deck;默认 `ppt169`(16:9),其他格式需提前指定 |+| **复刻模式** | 仅 Create Layout/Create Deck:`standard`(默认精简基本套)/ `fidelity`(每个可复用语义家族一个变体)/ `mirror`(每张源页一个物化原型)。`standard` / `fidelity` 创作新 SVG 语义;mirror 只保留来源包内已经存在且验证通过的事实。 |+| **原生结构事实** | 仅 Create Layout/Create Deck:简报会列出源 Master/Layout 数量、父子关系、placeholder 身份和多母版情况。`standard` / `fidelity` 只把它们当参考;mirror 把受支持事实一对一映射进当前 `structured` 合同。 |+| **保真级别** | 仅 Create Layout/Create Deck;`standard` / `fidelity` 有源时必填,选择 `literal` 或 `adapted`。**`mirror` 模式不询问**——它保留受支持的来源视觉。 || **关键词** | 3–5 个标签,用于索引检索 || 主题色 / 设计风格 / 素材清单 | 可选,可让 AI 从源里自动提取 |@@ -156,13 +159,13 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG> 为什么这么严?无论模板进入全局库,还是只服务当前项目,它都是结构契约。先确认归属和几何,可避免半成品或资产落错目录。-### 第三步:选 standard、fidelity 还是 mirror?+### 第三步:Create Layout/Create Deck 选择 standard、fidelity 还是 mirror?-这是派生模板里最容易混淆的决策。+这是派生结构型模板里最容易混淆的决策。Create Brand 不执行这一步,因为 identity-only 工作没有 SVG roster 或原生结构。| | **standard** | **fidelity** | **mirror** ||---|---|---|---|-| 输出页数 | 4–5 页(封面/章节/内容/结尾,可选目录) | 每个可复用语义家族一个变体——数量由源决定 | 每张源页一个恢复原型(1:1 页面集合) |+| 输出页数 | 4–5 页(封面/章节/内容/结尾,可选目录) | 每个可复用语义家族一个变体——数量由源决定 | 每张源页一个物化原型(1:1 页面集合) || 抽象程度 | 高 —— 干净可复用骨架 | 中 —— 语义家族重新设计 | 拓扑层面不抽象,只做 structured 合同要求的机械归一化 || 作者占位符 | 是(`{{TITLE}}`、`{{CONTENT_AREA}}` 等) | 是 | 可保留原文字,但导入识别出的原生内容槽仍带语义 metadata || 适合场景 | 你只需要"调性 + 基本骨架",未来用模板生成全新 deck | 源 PPTX 本身就是高度定制的版式库 | 别人的精装 deck 直接好用、想把每页都当参考页 |@@ -172,7 +175,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG**关于精灵图**:PPTX 导出的素材常常是**一张大图 + 多页通过 viewBox 裁剪不同区域**。`fidelity` 和 `mirror` 模式下必须保留这层嵌套 `<svg viewBox=...>` 包装,不能扁平化为单张 `<image>`——否则裁剪信息丢失,画面会错位。工作流会自动校验这一点。-**关于 PowerPoint 原生形状**:完整导入 SVG 作为原生载荷后备留在临时分析工作区且保持不可变;模板创建使用轻量、可编辑的 `authoring-svg/` IR 及其 source-ref/hash manifest。创作模式使用项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化最终模板 SVG,只为未改且 hash 匹配的 Slide-local/slot ref 恢复转换器已支持的载荷;固定 Master/Layout 层保持直接原子,不支持或已修改的对象保留当前 SVG fallback,最终模板不包含 IR 专用 ref。+**关于 PowerPoint 原生形状**:完整导入 SVG 作为原生载荷后备留在临时分析工作区且保持不可变;模板创建使用轻量、可编辑的 `authoring-svg/` IR 及其 source-ref/hash manifest。创作模式使用项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化最终模板 SVG,只为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已支持的载荷;固定 Master/Layout 层保持直接原子,不支持或已修改的对象保留当前 SVG fallback,最终模板不包含 IR 专用 ref。对于 PPTX 来源的 Type A mirror,最终物化统一使用一个确定性命令:@@ -196,8 +199,8 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \| 范围 | 工作区根目录 | 预览 | 发现行为 ||---|---|---|---|-| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | 可选 `exports/<id>_template_preview.pptx` | 校验后注册到对应 `layouts_index.json` 或 `decks_index.json` |-| `project` | `projects/<name>/` | 可选 `exports/<id>_template_preview.pptx` | 跳过全局索引注册 |+| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | Create Brand:不适用;Create Layout/Create Deck:单 Master 可选、多 Master 必须 | 校验后注册到对应 `brands_index.json`、`layouts_index.json` 或 `decks_index.json` |+| `project` | `projects/<name>/` | 沿用同一套 kind-specific 审阅规则 | 跳过全局索引注册 |全局注册让模板**可被发现**——下次有人问“有哪些模板可用?”时,AI 会从索引里把它列出来。两种范围的用法相同:按 SKILL.md Step 3 的规则,在第一条消息里给出工作区根目录,例如 `用这个模板:skills/ppt-master/templates/layouts/<your_template_id>/` 或 `用这个模板:projects/<name>/`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要被发现时才执行注册。@@ -248,7 +251,7 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \避免常见误解:-- **可复用模板是一份显式 SVG 契约,不是打包后的源 PPTX**。创作模式新建该合同,mirror 通过该合同恢复来源归属;每页都能独立预览,导出只编译已声明的 Master/Layout/Slide 结构+- **可复用模板是一份显式 SVG 契约,不是打包后的源 PPTX**。创作模式新建该合同,mirror 把已验证的来源归属事实映射进该合同;每页都能独立预览,导出只编译已声明的 Master/Layout/Slide 结构- **模板不是"风格皮肤"**。它包含结构(页面有几块、信息层级如何分布)+ 风格(配色、字体、装饰),两者不可分割。试图只换"皮肤"不换结构,往往会让信息架构和视觉打架- **模板不会替你做内容决策**。策略师仍然会按内容判断每页用哪个版式、要不要扩展为变体,模板提供候选,不预设结果- **`fidelity` 模式不等于像素级搬运**。即便是 `literal` 保真,AI 仍会把杂质和不必要的重复结构清理掉——载体保留几何,但不照抄冗余diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex a6c0b3f0..f257cfb5 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -22,7 +22,7 @@ description: >| Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. They never replace native SVG geometry, text, styles, grouping, or asset references. || `svg_final/` | Mandatory derived, self-contained SVG visual preview. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. || SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It compiles only the selected route's explicit structure contract: `flat` keeps represented content Slide-local, while `structured` may place explicitly scoped content in Master/Layout/Slide parts. It MUST NOT infer structure, upgrade `flat`, or invent new visible page content. |-| Direct PPTX and presentation-behavior workflows | Remain separate. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |+| Native PPTX routes and presentation-behavior stages | Remain outside SVG page-design closure. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |**MUST — page-design closure**: For an SVG-authoring route, inspect the final page SVG to determine what the exported slide looks like. Do not reinterpret “SVG is the page-design language” as “SVG is the complete PPTX package description language.”@@ -72,10 +72,10 @@ description: >| 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 |+| Route selection | [`workflows/routing.md`](workflows/routing.md) | Owns deterministic selection among the four top-level artifact routes |+| Workflow registry | [`workflows/index.md`](workflows/index.md) | Separates top-level routes from supporting child workflows, profiles, stages, and governance || 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 |+| Failure recovery | [`workflows/governance/failure-recovery.md`](workflows/governance/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@@ -112,31 +112,33 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.| Visualization templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available visualization SVG templates (charts, infographics, diagrams, frameworks) || Icon library | `${SKILL_DIR}/templates/icons/` | See `${SKILL_DIR}/templates/icons/README.md`; search icons on demand with `ls templates/icons/<library>/ \| grep <keyword>` |-## Standalone Workflows+## Top-Level Routes and Supporting Runbooks-**Route authority**: Use [`workflows/routing.md`](workflows/routing.md) before entering the main pipeline or any standalone workflow.+**Route authority**: Use [`workflows/routing.md`](workflows/routing.md) to select exactly one top-level route. Child workflows, profiles, and stages never compete with that route.-**Registry**: Use [`workflows/index.md`](workflows/index.md) for the complete workflow list, triggers, preconditions, exclusions, outputs, and blocking points.+**Registry**: Use [`workflows/index.md`](workflows/index.md) for the route/supporting-document classification and ownership map.### PPTX Route Boundary| 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, preserve page count/order and slide wording 1:1, improve layout | Main pipeline with the [`beautify-pptx`](workflows/profiles/beautify-pptx.md) profile || Existing PPTX as source material, rethink outline or change page count/order | Main pipeline via `source_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 workspace path |+| Build a reusable Brand, Layout, or Deck workspace from a PPTX/design reference | [`create-template`](workflows/create-template.md), which dispatches one matching child workflow, then return with the generated template workspace path || Finished PPTX, keep content/layout stable and add notes/audio/timing/transitions | [`native-enhance-pptx`](workflows/native-enhance-pptx.md) |-**MUST**: Raw `.pptx` template plus "generate PPTX" routes to `template-fill-pptx` by default. The SVG generation route consumes only an explicit template workspace path with a valid `templates/design_spec.md`, or a supported direct/legacy package root with `design_spec.md`.+**MUST**: Raw `.pptx` template plus "generate PPTX" routes to `template-fill-pptx` by default. The SVG generation route consumes only an explicit template workspace path with a valid `templates/design_spec.md`, or a compatible flat-directory current-contract root with `design_spec.md`. Semantic-legacy packages are rejected and must be replaced through Create Template.-**MUST**: Beautify is strictly 1:1. Any split, merge, drop, reorder, or page-count change routes to the main pipeline.+**MUST**: The beautify profile is strictly 1:1. Any split, merge, drop, reorder, or page-count change uses the default main-pipeline policy instead.-**MUST — reusable template mode boundary**: `create-template` has two distinct-contracts. `standard` and `fidelity` author new SVG prototypes and their own+**MUST — reusable template mode boundary**: Create Template keeps its fixed+entry name and dispatches exactly one of `create-brand`, `create-layout`, or+`create-deck`. The Create Layout and Create Deck children have two structured+replication contracts. `standard` and `fidelity` author new SVG prototypes and their ownMaster/Layout/slot system; source visuals and assets are references, and sourceMaster/Layout topology is neither preserved nor distilled. `mirror` is a-restoration path: preserve the source slide roster/order, visual appearance,+native-preservation path: preserve only the source slide roster/order, visual appearance,Master/Layout parentage and identities, placeholder type/index/bounds, nativeobject ownership, and supported native-shape metadata. The lossless import isthe native-payload backing store; the `authoring-svg/` bundle and its@@ -153,7 +155,14 @@ Slide plus one definition-only `layout_<layout_key>.svg` prototype for everysource Layout unused by those Slides. The independent Master/Layout roster thenregisters the complete supported source graph without publishing syntheticcarrier pages. Stop only when required native evidence is missing or unsupported;-never silently drop or merge an identity.+never silently drop or merge an identity. Mirror reads native facts that still+exist in the source package or a complete current contract; it does not infer+missing historical intent or modify the reference file.++**MUST — no direct structure grafting**: Existing PPTX/SVG files are never+upgraded in place with Master/Layout/placeholder structure. Create a separate+validated workspace through `create-template`, pass that workspace to Step 3,+and author new structured `svg_output/` pages before exporting a new PPTX.**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?@@ -165,7 +174,7 @@ never silently drop or merge an identity.🚧 **GATE**: User has provided source material (PDF / DOCX / EPUB / URL / Markdown file / text description / conversation content — any form is acceptable).-> **No source content?** When the user supplies only a topic name or requirements without any file or substantive description, run the [`topic-research`](workflows/topic-research.md) workflow first, then return here with its products as input.+> **No source content?** When the user supplies only a topic name or requirements without any file or substantive description, run the [`topic-research`](workflows/stages/topic-research.md) intake stage first, then return here with its products as input.When the user provides non-Markdown content, convert immediately through theunified dispatcher. It preserves the backend converters' existing behavior,@@ -226,9 +235,9 @@ For PPTX sources, `import-sources` automatically runs the standard intake enrichpython3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx> -o <project_path>/analysis```-For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, observed usage) and `<stem>.slide_library.json` (text slots, geometry, native tables, native chart caches, SmartArt nodes/connections), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; beautify and template-fill workflows decide separately which fields become locked constraints.+For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, observed usage) and `<stem>.slide_library.json` (text slots, geometry, native tables, native chart caches, SmartArt nodes/connections), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; the beautify profile and Fill Native PPTX route decide separately which fields become locked constraints.-Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify / template-fill workflows remain single-deck (1:1 to one chosen source deck) and read that deck's `<stem>.*` artifacts.+Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify profile and Fill Native PPTX route remain single-deck (1:1 to one chosen source deck) and read that deck's `<stem>.*` artifacts.> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. If Step 1 wrote Markdown beside the original sources, pass that source path/directory once. If Step 1 used `-o` to write Markdown elsewhere, pass both the original source path(s)/directory and the Markdown output path(s)/directory. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.@@ -244,7 +253,7 @@ Multi-deck: several PPTX files may be imported into one main-pipeline project**Hard boundary — raw PPTX template references are not Step 3 templates.** PPTX-as-source remains valid in Step 1 / Step 2, and raw PPTX template + generated PPTX routes to `template-fill`. But if the user wants the SVG/template-based generation route from that PPTX, stop before Step 3. The user must first run [`workflows/create-template.md`](workflows/create-template.md), then return with the generated template workspace path. Step 3 consumes an explicit workspace whose `templates/design_spec.md` declares `kind: brand` / `kind: layout` / `kind: deck`, or a compatible legacy-flat package whose root `design_spec.md` declares one of those kinds.-Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use `template-fill` for raw PPTX template + generated PPTX requests; use `beautify` only when the source deck's page count, order, and wording are preserved.+Do **not** reinterpret this boundary as permission to add Master/Layout structure to the raw PPTX or an existing SVG project. Use `template-fill` for raw PPTX template + generated PPTX requests. Use the beautify profile only when the source deck's page count, order, and wording are preserved while new SVG pages are authored.**Template flow triggers ONLY on explicit directory paths** supplied by the user in their initial message, plus one narrow workflow handoff: a project-scoped `create-template` run in the current conversation may pass its exact validated project workspace root directly into this Step. The trigger rule is mechanical, not interpretive:@@ -256,7 +265,7 @@ Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. UseThere is no slug matching, no name lookup, no fuzzy resolution. A name without a path does not trigger — the user must give a path the AI can `cd` into.-**Structured-template preflight (before copy)**: For every deck/layout workspace, inspect all SVG roots and slots under its normalized template source. Every page must declare root Master/Layout key and picker names; Master/Layout visuals must be direct atoms rather than `<g>`; every slot must be a top-level `<g>` with positive bounds and exactly one compatible carrier, or an explicit composite `object` proxy. A zero-slot Layout is valid. If the SVG package uses a legacy semantic contract, run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) first and return to Step 3 with the migrated workspace. A legacy flat directory shape alone is read compatibility and does not trigger restoration.+**Structured-template preflight (before copy)**: For every deck/layout workspace, inspect all SVG roots and slots under its normalized template source. Every page must declare root Master/Layout key and picker names; Master/Layout visuals must be direct atoms rather than `<g>`; every slot must be a top-level `<g>` with positive bounds and exactly one compatible carrier, or an explicit composite `object` proxy. A zero-slot Layout is valid. Reject a legacy semantic contract. Create a new current workspace through [`create-template`](workflows/create-template.md), using the original PPTX when existing native topology must be mirrored; legacy or incomplete SVGs may guide `standard` / `fidelity` only. A legacy-flat directory shape remains readable when its SVG contract is current.> Style descriptions ("麦肯锡风格" / "Keynote 风" / "极简风" / etc.) never trigger Step 3. They flow into the Strategist confirmation stage as a style brief (color / typography / tone in fields e–g).@@ -264,7 +273,7 @@ There is no slug matching, no name lookup, no fuzzy resolution. A name without a> "What templates exist?" is out-of-band Q&A — answer by listing entries from `brands_index.json` / `layouts_index.json` / `decks_index.json` together with their paths. Listing alone does not advance the pipeline; the user must send a path back to trigger Step 3.-> To create a new layout or deck, read [`workflows/create-template.md`](workflows/create-template.md). To create a new brand, read [`workflows/create-brand.md`](workflows/create-brand.md).+> To create any new `brand`, `layout`, or `deck` workspace, enter [`workflows/create-template.md`](workflows/create-template.md). It dispatches exactly one child workflow: [`create-brand`](workflows/create-template/create-brand.md), [`create-layout`](workflows/create-template/create-layout.md), or [`create-deck`](workflows/create-template/create-deck.md).#### Three template kinds@@ -309,7 +318,7 @@ When `create-template` used project output scope, its workspace root is the targA project-scoped workspace has the same portable routing as a library workspace. It may be copied or promoted across roots as one unit (`templates/` plus any existing `images/` and `icons/`); `exports/` stays review-only. Do not pass only another project's `templates/` subdirectory because that would omit sibling assets.-Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy or consume those semantic contracts through Step 3. Run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) on the package first, then return with the migrated workspace path. Old flat packaging remains readable when its SVG structure is already current.+Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy, consume, or migrate those semantic contracts through Step 3. Create a new workspace through [`create-template`](workflows/create-template.md), preferably from the original PPTX when existing native topology matters, then return with that new workspace root. Old flat packaging remains readable when its SVG structure is already current.The Strategist confirmation stage decides whether the selected deck/layout template is used `strict` or `adaptive`. Those template projects use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, declare unique reusable identities in `pptx_masters` / `pptx_layouts`, and assign each page through `page_pptx_layouts` before SVG generation. A Layout definition may remain unused by generated pages when it names an installed template SVG as its prototype source. Brand-only projects remain on the free-design `mode: flat` route. Strict preserves the template's declared Master/Layout/slot contract. Adaptive keeps the template Master and may define and assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.@@ -476,12 +485,12 @@ The page is a **confirmation surface only** — Strategist still authors every r| Signal read | Line content ||---|---|-| Heavy (long page count / bulky sources / heavy web-fetch accumulation) | State estimated page count and large source size; recommend switching to [split mode](workflows/resume-execute.md) after Step 5 — stop this chat, open a fresh window and input `继续生成 projects/<project_name>` to enter the execution session (SVG generation + export); no response or "continue" = default continuous mode. |-| Normal (default) | State scale is moderate, default continuous mode generates in one go; if mid-way window switch is desired, input `继续生成 projects/<project_name>` after Step 5 to switch to [split mode](workflows/resume-execute.md). |+| Heavy (long page count / bulky sources / heavy web-fetch accumulation) | State estimated page count and large source size; recommend switching to [split mode](workflows/stages/resume-execute.md) after Step 5 — stop this chat, open a fresh window and input `继续生成 projects/<project_name>` to enter the execution session (SVG generation + export); no response or "continue" = default continuous mode. |+| Normal (default) | State scale is moderate, default continuous mode generates in one go; if mid-way window switch is desired, input `继续生成 projects/<project_name>` after Step 5 to switch to [split mode](workflows/stages/resume-execute.md). |This line is required output every run — the user must always see the mode choice exists. Whether to act on it is the user's call. When the Confirm UI is used, this choice also appears as the in-page generation-mode toggle and is captured in `result.json` (`generation_mode`); the chat-summary fallback still prints this line.-**Mandatory — spec-refinement note** (not a separate confirmation): after the split-mode line, you MUST append one short opt-in line (rendered in the user's language, prefixed with 💡) telling the user they may **refine the spec first** — Strategist will produce the full design spec, then stop for review/revision of any part of it before any generation, via the [refine-spec](workflows/refine-spec.md) workflow. Default is OFF: no request → the spec is written in one go and the pipeline auto-proceeds as usual. Only when the user explicitly asks in chat (e.g. "refine the spec first") or confirms `refine_spec: true` through Confirm UI does the [refine-spec](workflows/refine-spec.md) workflow take over after the Strategist confirmation stage. This line, like the split-mode line, is required output every run — the user must see the choice exists; whether to act on it is theirs. When the Confirm UI is used, this choice also appears as the in-page refine-spec toggle and is captured in `result.json` (`refine_spec`); the chat-summary fallback still prints this line.+**Mandatory — spec-refinement note** (not a separate confirmation): after the split-mode line, you MUST append one short opt-in line (rendered in the user's language, prefixed with 💡) telling the user they may **refine the spec first** — Strategist will produce the full design spec, then stop for review/revision of any part of it before any generation, via the [refine-spec](workflows/stages/refine-spec.md) stage. Default is OFF: no request → the spec is written in one go and the pipeline auto-proceeds as usual. Only when the user explicitly asks in chat (e.g. "refine the spec first") or confirms `refine_spec: true` through Confirm UI does the [refine-spec](workflows/stages/refine-spec.md) stage take over after the Strategist confirmation stage. This line, like the split-mode line, is required output every run — the user must see the choice exists; whether to act on it is theirs. When the Confirm UI is used, this choice also appears as the in-page refine-spec toggle and is captured in `result.json` (`refine_spec`); the chat-summary fallback still prints this line.**Formula rendering policy lives inside item 7 (Typography plan)**:@@ -522,7 +531,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images- [x] Read the auto-extracted facts already in `analysis/` (e.g. `source_profile.json`) before the Strategist confirmation stage- [x] Strategist confirmation stage completed (user confirmed via Confirm UI `result.json` or chat fallback)- [x] Split-mode note appended below the confirmation fields (heavy or normal variant)-- [x] Spec-refinement opt-in line appended (default OFF; only the user's explicit request enters the refine-spec workflow)+- [x] Spec-refinement opt-in line appended (default OFF; only the user's explicit request enters the refine-spec stage)- [x] Design Specification & Content Outline generated- [x] Execution lock (spec_lock.md) generated- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase@@ -536,7 +545,7 @@ 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.+**Failure recovery**: stop/continue behavior for AI/web/slice/image-readiness failures is defined in [`workflows/governance/failure-recovery.md`](workflows/governance/failure-recovery.md). This Step keeps the acquisition procedure.**Always load the common framework**:@@ -588,7 +597,7 @@ Workflow:## ✅ Planning Session Complete- [x] Spec: `design_spec.md`, `spec_lock.md`- [x] Resources: `sources/`, `images/`, `templates/`- - [ ] **Next**: open a fresh chat window and input `继续生成 projects/<project_name>` to enter the execution session via the [`resume-execute`](workflows/resume-execute.md) workflow.+ - [ ] **Next**: open a fresh chat window and input `继续生成 projects/<project_name>` to enter the execution session via the [`resume-execute`](workflows/stages/resume-execute.md) stage.```> On acquisition failure, do NOT halt — follow the Failure Handling rule in [image-base.md](references/image-base.md) §5: retry once, then mark the row `Needs-Manual`, report to user, and continue to the checkpoint above.@@ -622,8 +631,8 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon- Treat the launch URL as a checkpoint value: before writing the first SVG, either report the actual URL from the launcher or state the launch failure explicitly. Do not silently continue while claiming preview is available.- Run it as a long-running side process/session; do not wait for it to exit before generating SVG pages. Do not wait for user confirmation after startup.- **Service must keep running** until one of: (a) the user clicks **Exit preview** in the browser, or (b) the user explicitly asks in chat to stop it. Generation continues even if the user closes the editor.-- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/live-preview.md`](workflows/live-preview.md).-- The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/live-preview.md`](workflows/live-preview.md) Notes.+- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/stages/live-preview.md`](workflows/stages/live-preview.md).+- The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/stages/live-preview.md`](workflows/stages/live-preview.md) Notes.**Pre-generation Batch Read (Mandatory)**: before the first SVG, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` and every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts). One read per file, up front — do not re-read these during page generation. See executor-base.md §1.0.@@ -671,9 +680,9 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>- [x] Speaker notes generated at notes/total.md```-> **Chart pages?** If this deck contains data charts (bar / line / pie / radar / etc.), run the standalone [`verify-charts`](workflows/verify-charts.md) workflow before Step 7 to calibrate coordinates. AI models routinely introduce 10–50 px errors when mapping data to pixel positions; verify-charts eliminates that class of error. Skip if no chart pages.+> **Chart pages?** If this deck contains data charts (bar / line / pie / radar / etc.), run the [`verify-charts`](workflows/stages/verify-charts.md) quality-gate stage before Step 7 to calibrate coordinates. AI models routinely introduce 10–50 px errors when mapping data to pixel positions; verify-charts eliminates that class of error. Skip if no chart pages.-> **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the standalone [`visual-review`](workflows/visual-review.md) workflow before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.+> **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the [`visual-review`](workflows/stages/visual-review.md) quality-gate stage before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.---@@ -683,7 +692,7 @@ 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 the planning session unless the owning source changed.+**Failure recovery**: if a Step 7 command fails, fix the owning source artifact and resume from the failed sub-step per [`workflows/governance/failure-recovery.md`](workflows/governance/failure-recovery.md). Do not restart the planning session 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.@@ -714,7 +723,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path># backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)# Add --native-charts-and-tables to replace marked fallbacks with PowerPoint-native Chart/Table objects:# exports/<project_name>_<timestamp>_native_charts_tables.pptx ← native Chart/Table replacements (data-pptx-replace-with markers)-# Re-export with --recorded-narration audio (generate-audio workflow) embeds per-slide narration:+# Re-export with --recorded-narration audio (generate-audio stage) embeds per-slide narration:# exports/<project_name>_<timestamp>_narrated.pptx ← narrated pptx (embedded audio + auto-advance timings)```@@ -778,9 +787,9 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> using `baseline`, `template`,> `preserve`, `layout_strategy`, `data-pptx-layout-kind`,> `distilled`/`utility`, direct atomic placeholders, or incomplete Master-> identity must run-> [`restore-pptx-structure`](workflows/restore-pptx-structure.md) before-> export.+> identity cannot enter release export. Create a new current template workspace+> through [`create-template`](workflows/create-template.md), then generate new+> structured SVG pages from that workspace before export.> **Template structured export** — `page_layouts` records the complete@@ -892,13 +901,13 @@ animation effects. The exact 22 tuples and OOXML rules live in**Optional custom animations** (only when the user asks to tune animation order/effects/timing for specific objects):-Run the standalone [`customize-animations`](workflows/customize-animations.md) workflow. Default export applies page transitions but no per-element entrance animation; create `animations.json` (or pass `-a auto`) only when the user asks for element animation or object-level customization.+Run the [`customize-animations`](workflows/stages/customize-animations.md) post-processing stage. Default export applies page transitions but no per-element entrance animation; create `animations.json` (or pass `-a auto`) only when the user asks for element animation or object-level customization.**Optional recorded narration** (only when the user asks for narrated/video export):-Run the standalone [`generate-audio`](workflows/generate-audio.md) workflow. The AI picks a narration backend (`edge` by default, or a configured cloud provider such as ElevenLabs / MiniMax / Qwen / CosyVoice for high-quality or cloned voices), asks the user once (backend + voice + rate/settings + embed-or-not, all with recommended values), then executes `notes_to_audio.py` and (if chosen) re-exports the PPTX with `--recorded-narration audio`.+Run the shared [`generate-audio`](workflows/stages/generate-audio.md) post-processing stage. The AI picks a narration backend (`edge` by default, or a configured cloud provider such as ElevenLabs / MiniMax / Qwen / CosyVoice for high-quality or cloned voices), asks the user once (backend + voice + rate/settings + embed-or-not, all with recommended values), then executes `notes_to_audio.py` and (if chosen) re-exports the PPTX with `--recorded-narration audio`.-Do NOT call `notes_to_audio.py` directly without going through the workflow — `--voice` / `--voice-id` is required and the workflow produces the locale/provider-aware recommendation that makes the choice meaningful.+Do NOT call `notes_to_audio.py` directly without going through the shared stage — `--voice` / `--voice-id` is required and the stage produces the locale/provider-aware recommendation that makes the choice meaningful.Full effect list, anchor logic, and limits: [`references/animations.md`](references/animations.md).The compatibility contract covers PowerPoint OOXML; do not promise identical@@ -907,11 +916,11 @@ animation playback in Keynote or other presentation applications.> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps> ❌ **NEVER** use `-s final` for a release export. It is a diagnostic comparison only; the supported native route reads `svg_output/`.-> **Post-export annotation window**: the preview service from Step 6 typically remains running after export. If the user submitted annotations in the browser (during Executor or after export) and now asks to apply them — they may quote the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`), say "apply my annotations" / "应用注解" / equivalent — run [`live-preview`](workflows/live-preview.md) Step 2 to apply and re-export. Annotations submitted during generation are also handled here, not earlier.+> **Post-export annotation window**: the preview service from Step 6 typically remains running after export. If the user submitted annotations in the browser (during Executor or after export) and now asks to apply them — they may quote the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`), say "apply my annotations" / "应用注解" / equivalent — run [`live-preview`](workflows/stages/live-preview.md) Step 2 to apply and re-export. Annotations submitted during generation are also handled here, not earlier.> **Direct edits in the browser**: the user may also stage text / SVG attribute edits in the preview. These land in `svg_output/` only after the user clicks **Apply changes**. If they ask to "re-export" / "重新导出" after applying such edits, just re-run Step 7.2–7.3 (finalize + export); no annotation-application step is needed unless they also saved AI-needed annotations.-> **Preview not running?** Any time the user mentions "live preview", "preview", "看效果", or wants to select/click a slide element and the service is not running, run [`live-preview`](workflows/live-preview.md) Step 1 to start it. If the service is already running, just point them at the URL — do not restart.+> **Preview not running?** Any time the user mentions "live preview", "preview", "看效果", or wants to select/click a slide element and the service is not running, run [`live-preview`](workflows/stages/live-preview.md) Step 1 to start it. If the service is already running, just point them at the URL — do not restart.---diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex e4d2f28b..d4b0f68a 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -19,7 +19,7 @@ To regenerate a deck with different settings, rerun `svg_to_pptx.py` against thePer-element animation is off by default. To enable it deck-wide, pass `-a auto` at export (no config needed). When a deck instead needs specific object timing — for example title first, chart second, annotation last — use the optional `animations.json` sidecar. The SVG remains static visual source; the sidecar only controls PPTX export behavior.-Run the standalone [`customize-animations`](../workflows/customize-animations.md) workflow when the user asks to tune animation order, effects, timing, or object-level reveals.+Run the [`customize-animations`](../workflows/stages/customize-animations.md) post-processing stage when the user asks to tune animation order, effects, timing, or object-level reveals.```bash# Build an editable scaffold from real top-level <g id> anchorsdiff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex f274b0e8..274f2b78 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -18,7 +18,7 @@ Global artifact ownership rules for PPT Master projects.| `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract || `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes || `design_spec.md` | 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, charts, and the route's PowerPoint structure mode; deck/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist writes the route-specific contract; Executor re-reads it before every page and may add a new adaptive Layout identity only on a structured template route while authoring the page that first needs it; `restore-pptx-structure` owns legacy template migration |+| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, charts, and the route's PowerPoint structure mode; deck/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist writes the route-specific contract; Executor re-reads it before every page and may add a new adaptive Layout identity only on a structured template route while authoring the page that first needs it || `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 |@@ -27,7 +27,7 @@ Global artifact ownership rules for PPT Master projects.| `<import_workspace>/authoring-svg/` | Template-creation author source | Layered editable SVG IR for imported Master, Layout, and Slide objects | Template_Designer reads and edits this bundle; final template SVGs are materialized from it rather than copied from lossless backing || `<import_workspace>/authoring-svg/authoring_manifest.json` | Authoring provenance contract | Per-document source/authoring hashes and document-local source-ref paths | Generated atomically with the IR; materialization validates it before reusing native payload; never duplicate raw payload here || `<import_workspace>/authoring-svg-flat/` | Optional complete-page verification IR | Self-contained page composition view with its own provenance manifest | Generate only from an explicitly requested `svg-flat/`; use to verify composition, while layered `authoring-svg/` remains the canonical editable source |-| `<import_workspace>/icons/imported/` | Imported vector pool | One canonical copy of every factored vector subtree | Authoring SVGs reference `data-icon="imported/<name>"`; vector inventories retain source refs so expansion restores IR identity |+| `<import_workspace>/icons/imported/` | Imported vector pool | One canonical copy of every factored vector subtree | Authoring SVGs reference `data-icon="imported/<name>"`; vector inventories retain source refs so expansion re-establishes IR identity || `confirm_ui/recommendations.json` | Confirmation proposal | Strategist-authored confirmation payload | Confirm UI reads; rewritten between Stage 1, Stage 2, and Stage 3 || `confirm_ui/result.json` | Confirmation result | User-confirmed values | Strategist treats final result as authoritative over recommendations || `svg_output/` | Page-design author source | Main-agent handwritten SVG pages containing the complete visible design | Quality checker and native PPTX export read this as the canonical visual/page-layout source; templates and locks do not add missing visible objects at export |@@ -51,7 +51,7 @@ Global artifact ownership rules for PPT Master projects.| Free-design / brand-only packaging authority | `spec_lock.md` declares `pptx_structure.mode: flat` and omits `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. || Template structure authority | `page_layouts` owns each page's authoring-input prototype. `pptx_masters` / `pptx_layouts` own the unique reusable output definitions, while `page_pptx_layouts` owns page assignment. Strict keeps the prototype contract; adaptive may create a new Layout definition during page authoring and updates its assignment immediately. Unused definitions may register without a published Slide. Templates validate provenance but never add missing visible page objects during export. || Imported-template authoring | `authoring-svg/` plus its `authoring_manifest.json` own edits and source-object identity during create-template. Lossless `svg/` owns immutable native payload and fallback evidence; optional `svg-flat/` owns only complete-page verification. Materialized `templates/*.svg` own the validated deliverable contract and contain no IR-only source refs. |-| Legacy structure migration | [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) owns conversion of old unmapped/distilled/preserve structured projects and legacy template packages into the current template contract. An intentional free-design or brand-only `flat` project is not a migration input. The exporter does not migrate or visually cluster legacy template structure. |+| Legacy template input | Old unmapped/distilled/preserve structured projects and incomplete template packages are not migrated in place. [`create-template`](../workflows/create-template.md) authors a new current workspace: original PPTX Type A may preserve existing native topology in mirror; legacy SVG-only Type B is visual reference for `standard` / `fidelity`. An intentional free-design or brand-only `flat` project is already current. The exporter does not migrate or visually cluster legacy structure. || 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. || Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. |diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex ab732d87..4d6aae08 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -76,7 +76,7 @@ When the project's chosen template is a `mirror` template (`design_spec.md` fron**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.-**Legacy template boundary**: A template with missing root Master identity, direct atomic placeholders, `data-pptx-layout-kind`, unmapped `baseline`, `preserve`, or `layout_strategy: distill` is not a fallback input. Stop and run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation.+**Legacy template boundary**: A template with missing root Master identity, direct atomic placeholders, `data-pptx-layout-kind`, unmapped `baseline`, `preserve`, or `layout_strategy: distill` is not a fallback input. Stop and create a new current workspace through [`create-template`](../workflows/create-template.md) before generation.### Page-Template Mapping Declaration (Required Output)@@ -94,7 +94,7 @@ Before generating each page, output which template is used:This section applies only to deck/layout template routes. `page_layouts` selects the input SVG prototype, `pptx_masters` / `pptx_layouts` declare unique reusable output definitions, and `page_pptx_layouts` assigns every generated page before the first page is drawn. Free-design and brand-only routes use `pptx_structure.mode: flat`, omit all four sections, skip the rest of §1.2, and keep every SVG object Slide-local.-**Hard rule — template mode only**: A deck/layout template project uses `pptx_structure.mode: structured`. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders must stop generation and route to [`restore-pptx-structure`](../workflows/restore-pptx-structure.md). `flat` is valid only when no deck/layout template is active.+**Hard rule — template mode only**: A deck/layout template project uses `pptx_structure.mode: structured`. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders stop generation. Create a new template workspace through [`create-template`](../workflows/create-template.md); do not upgrade the active SVG project in place. `flat` is valid only when no deck/layout template is active.**Hard rule — root identity**: A `page_pptx_layouts` row binds the page to one key in `pptx_layouts`; that unique definition supplies its Master key, Layout picker name, and prototype source. Put the declared Master key/name and Layout key/name on the root SVG. A Layout key belongs to exactly one Master and remains globally unique.@@ -198,7 +198,7 @@ Do **not** invent a prototype entry, and do **not** assume a template just becau**Per-page PowerPoint layout lookup — structured deck/layout templates only**:- When `pptx_structure.mode` is `flat`, skip this lookup and the structured scaffold below. `pptx_masters`, `pptx_layouts`, `page_layouts`, and the corresponding SVG metadata must all be absent; each root still declares its canonical `data-pptx-page-role`.-- When a deck/layout template is active, `pptx_structure.mode` must equal `structured`; any other or missing value routes to legacy restoration.+- When a deck/layout template is active, `pptx_structure.mode` must equal `structured`; any other or missing value is rejected. Do not migrate it in place: create a new current-contract workspace through Create Template before generation resumes.- Read the current page row as `<master_key> | <layout_key> | <layout name>` and resolve `master_key` in `pptx_masters`. Missing, malformed, or partial mappings stop before drawing.- Write matching root Master/Layout key and picker names. Do not write `data-pptx-layout-kind` or `data-pptx-page-role`.- On strict template use, the row and SVG contract match the selected prototype exactly.@@ -256,7 +256,7 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha- **Default — stage each page with the style's composition geometry (may override when the content genuinely calls for a plain grid)**: an SVG page is a canvas, not a DOM. Before defaulting to stacked rounded-rect cards or uniform equal columns, pick one page-scale move from the locked visual style's §1 `Composition geometry` (a bleed shape, diagonal split, oversized numeral, orbit rings, …) to stage the page's primary zone. Card grids are one option among many, not the house layout.- **Reference — image-led promotional pages (not a constraint)**: for travel, venue, product-introduction, hospitality, event, real-estate, and brochure-style decks, let images define the page skeleton before placing text. Consult [`image-layout-patterns.md`](image-layout-patterns.md) §Imported Deck Patterns and prefer patterns such as `#74` TOC image-navigation cards, `#75` asymmetric chapter banners, `#77` photo mosaic with a text cell, `#78` ambient banner + evidence photo + text panel, `#79` ribbon-header image cards, and `#80` side hero image + staggered evidence cards before falling back to plain left/right image-text splits.- **Phased batch generation** (recommended):- 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per §3.1 below on every chart page — coordinate calibration is a post-generation step (see [`workflows/verify-charts.md`](../workflows/verify-charts.md)) that depends on these markers — and **native object metadata** per §3.2 on every eligible data-chart page. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path>/svg_output/<first_page>.svg` and fix every error before drawing page 2 — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.+ 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per §3.1 below on every chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per §3.2 on every eligible data-chart page. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path>/svg_output/<first_page>.svg` and fix every error before drawing page 2 — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path>` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. This includes structured deck/layout-template warnings. If release truly depends on a condition, it belongs in `errors`. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.@@ -305,7 +305,7 @@ into `svg_output/`.### 3.1 Chart Plot-Area Marker (MANDATORY on every chart page)-> The [`verify-charts`](../workflows/verify-charts.md) workflow enumerates chart pages from `design_spec.md §VII`, then reads each page's plot-area marker to feed `svg_position_calculator.py`. Missing marker → verify-charts has to re-derive the plot area from axis lines, paying the cost on every run.+> The [`verify-charts`](../workflows/stages/verify-charts.md) stage enumerates chart pages from `design_spec.md §VII`, then reads each page's plot-area marker to feed `svg_position_calculator.py`. Missing marker → verify-charts has to re-derive the plot area from axis lines, paying the cost on every run.**Hard rule**: every SVG page that contains a data visualization chart includes a plot-area marker inside `<g id="chartArea">`, placed **after axis lines** and **before the first data element** (bar, line, area, point).@@ -484,7 +484,7 @@ Chart SVGs referenced in **VII. Visualization Reference List** are loaded once v### 5.1 Chart Coordinate Calibration-Coordinate calibration runs as a **standalone post-generation workflow**, not inside the executor pipeline. After SVG generation completes, if the deck contains data charts, run [`workflows/verify-charts.md`](../workflows/verify-charts.md) before post-processing.+Coordinate calibration runs as a **conditional post-generation stage**, not inside the Executor authoring loop. After SVG generation completes, if the deck contains data charts, run [`verify-charts`](../workflows/stages/verify-charts.md) before post-processing.The executor's only obligation here is upstream: embed the `<!-- chart-plot-area ... -->` marker on every chart page during initial draft (§3.1). Verify-charts enumerates chart pages from `design_spec.md §VII` (authoritative deck plan) and uses the marker to feed `svg_position_calculator.py`.diff --git a/skills/ppt-master/references/semantic-svg.md b/skills/ppt-master/references/semantic-svg.mdindex bf12550b..2a350039 100644--- a/skills/ppt-master/references/semantic-svg.md+++ b/skills/ppt-master/references/semantic-svg.md@@ -124,4 +124,4 @@ For structured deck/layout template projects, validation rejects:- a slot without positive bounds, a carrier-bound slot without exactly one compatible carrier, or a proxy binding on a non-`object` slot;- incomplete page mappings, cross-Master Layout-key reuse, or conflicting same-key Layout contracts.-Legacy structured/template SVGs using unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`, `utility`, direct atomic placeholders, or an incomplete Master identity are not a second supported structured contract. Run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation or export. An explicit `mode: flat` free-design/brand-only project is current and intentionally has no Master identity. When original PPTX/native facts exist, migration restores those identities first; otherwise the main Agent explicitly derives structured template metadata. Export never performs that derivation.+Legacy structured/template SVGs using unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`, `utility`, direct atomic placeholders, or an incomplete Master identity are not a second supported structured contract. Create a new workspace through [`create-template`](../workflows/create-template.md) before generation or export. An explicit `mode: flat` free-design/brand-only project is current and intentionally has no Master identity. Original PPTX Type A may preserve native identities that still exist in the package; legacy SVG-only Type B may guide `standard` / `fidelity` visually but does not authorize topology recovery. Export never derives, repairs, or migrates structure.diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex 0f91556b..02e4e7f8 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -28,7 +28,7 @@ Other files link here instead of restating its contracts.| Text treatments | Mixed runs, tracking, underline, strikethrough, gradient fill, outline, transparency, watermark text, and text glow | §4.2, §6.7 || Transforms and composition | Translate, scale, rotate, mirror, supported matrix composition, layering, and static local reuse | §1.3, §6.8 || Freeform geometry | Full SVG path vocabulary, curves, organic containers, multi-subpaths, and asymmetric rounded rectangles | §6.9 |-| Imported PowerPoint shapes | Immutable lossless payload backing, editable authoring IR, and selective restoration of preset/custom geometry, connectors, and unchanged native text bodies | §1.4 |+| Imported PowerPoint shapes | Immutable lossless payload backing, editable authoring IR, and selective rehydration of preset/custom geometry, connectors, and unchanged native text bodies | §1.4 || Authored PowerPoint preset shapes | Registry-generated visible fragments that export as one native preset shape or connector | §1.5; [`native-shape-authoring.md`](./native-shape-authoring.md) || Radial/chart geometry | Pie/donut arcs, dashed-circle ring segments, gauges, progress rings, sunbursts, and diagonal polygon arrowheads | §6.10 || Constructed visual styles | Faux glass, hand-drawn marks, ink wash, Riso offset, pixel grid, halftone, isometric facets, paper cut, and line-plus-area data treatment | §6.11 |@@ -267,20 +267,20 @@ the original `<use>` / `<symbol>` structure.`pptx_to_svg.py` emits rendering-neutral metadata when a visible SVG objectoriginates from `p:sp`, `p:cxnSp`, or `p:grpSp`. This contract is for losslessimport SVGs and unchanged imported objects that remain Slide-local or inside a-slot during mirror restoration. Ordinary authored SVG does not need these+slot during mirror materialization. Ordinary authored SVG does not need theseattributes, and no separate source-payload opt-in marker exists.| Metadata | Placement | Required behavior ||---|---|---|| `data-pptx-object` | Logical `<g>` and native carrier | `shape`, `connector`, `group`, or `picture`; never infer the object kind from path appearance. |-| `data-pptx-shape-id` + `data-pptx-shape-scope` | Logical `<g>` and carrier | Preserve the source part-scoped identity. Export remaps duplicate Master/Layout/Slide ids into page-unique ids before restoring connector references. |+| `data-pptx-shape-id` + `data-pptx-shape-scope` | Logical `<g>` and carrier | Preserve the source part-scoped identity. Export remaps duplicate Master/Layout/Slide ids into page-unique ids before rebinding connector references. || `data-pptx-frame="x y width height"` | Logical `<g>` and carrier | Own native `a:xfrm` position and size. Values use sufficient precision for exact EMU recovery; path bounds, stroke, markers, shadows, and text glyph bounds never replace this frame. || `data-pptx-prst` | Preset carrier and logical `<g>` | One of the locked 187 DrawingML `ST_ShapeType` values. || `data-pptx-av-*` | Preset carrier and logical `<g>` | Preserve the complete validated DrawingML adjustment formula, including non-`val` formulas. || `data-pptx-part="geometry"` | One hidden carrier path | The single native export authority for frame, base fill/line/effect, preset/custom geometry, and object identity. || `data-pptx-part="geometry-preview"` / `geometry-detail` | Visible preview group/paths | Render the preset's independent path fill/stroke layers. A hash-locked preview group may mirror the carrier's one filter so a multi-path preset renders one aggregate imported effect; these elements are never emitted as duplicate PowerPoint shapes. |-| `data-pptx-preview-sha256` | Logical preset `<g>` and carrier | Detect edits to visible preset paths or paint. A stale preview fails quality check/export instead of silently restoring old native metadata. |-| `data-pptx-geometry-kind="custom"` + `data-pptx-custgeom` | Custom-geometry carrier | Preserve the validated original `a:custGeom` subtree. If the visible path hash is unchanged, export restores formulas, handles, connection sites, text rectangle, and path list exactly; edited paths compile from current SVG geometry. |+| `data-pptx-preview-sha256` | Logical preset `<g>` and carrier | Detect edits to visible preset paths or paint. A stale preview fails quality check/export instead of silently reusing old native metadata. |+| `data-pptx-geometry-kind="custom"` + `data-pptx-custgeom` | Custom-geometry carrier | Preserve the validated original `a:custGeom` subtree. If the visible path hash is unchanged, export writes formulas, handles, connection sites, text rectangle, and path list exactly; edited paths compile from current SVG geometry. || `data-pptx-start/end-shape-id/site` | Connector logical `<g>` and carrier | Restore `a:stCxn` / `a:endCxn` after scoped shape-id allocation. A connector may retain one zero frame axis; it must not be expanded from visible stroke or marker bounds. || `data-pptx-shape-style` | Native carrier | Preserve a relationship-free `p:style` independently of text, including shapes with no visible text. || `data-pptx-effect-status="unsupported"` + `data-pptx-effect-reason` | Imported `p:sp` / `p:cxnSp` logical object and native carrier; imported `p:pic` carrier and logical object; imported `p:grpSp` logical group; imported table `p:graphicFrame` logical group | Record why an encountered source object or text-run `effectLst` / `effectDag` cannot enter the registered target-specific effect mapping without changing semantics. Checker and export stop with the recorded reason; these attributes are diagnostics, not a preserved effect payload or authoring syntax. |@@ -306,7 +306,7 @@ the create-template authoring IR. Its value is unique within one authoring SVG,not across the workspace, and must be resolved through that document's`authoring_manifest.json` record. Moving a referenced subtree into`icons/imported/` for readability must preserve the attribute and record it in-the vector inventory; re-inlining restores the same mapping. Final materialized+the vector inventory; re-inlining re-establishes the same mapping. Final materializedtemplate SVGs and normal project `svg_output/` must not contain this attribute.**Hard rule — structural-layer boundary**: An unchanged imported logical object@@ -345,7 +345,7 @@ optional PowerPoint-native Chart/Table replacement contract.- Opaque XML payloads containing any `r:*` relationship attribute are nevercopied into a new slide part. Relationship-bearing text content andshape-level `a:blipFill` use the existing rebuilt visual fallback and are- not covered by atomic `p:sp + p:txBody` restoration.+ not covered by atomic `p:sp + p:txBody` rehydration.- Unknown future presets and explicit `unsupported` geometry status neverdowngrade silently to `rect`; native export stops with the recorded reason.@@ -1739,9 +1739,9 @@ defaults to `bottom` and accepts `top`, `left`, or `right`.### PPTX Structure Routing-Every new SVG project declares one deterministic route. Free-design and brand-only projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use restored source identities and parentage.+Every new SVG project declares one deterministic route. Free-design and brand-only projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use the validated source identities and parentage declared by the newly materialized workspace.-**Hard rule — no structure inference**: Flat export performs no promotion or deduplication; every object stays Slide-local. Structured template export compiles only declared root identities, atomic fixed layers, and slot groups—it does not assign Layout families, cluster pages, infer placeholders, or repair missing metadata. Legacy structured/template projects must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.+**Hard rule — no structure inference**: Flat export performs no promotion or deduplication; every object stays Slide-local. Structured template export compiles only declared root identities, atomic fixed layers, and slot groups—it does not assign Layout families, cluster pages, infer placeholders, repair missing metadata, or migrate legacy contracts. Create a new current workspace through [`create-template`](../workflows/create-template.md) before generating structured pages.**Layout reuse**: Reuse one Layout key only when its ordered fixed Layout atoms and slot ids/types/effective indices/default bounds/binding modes are identical. Different wording, data, imagery, crop, or Slide-local carrier geometry does not create a new Layout. A genuinely different reusable contract gets a new key even when both pages are semantically `content`.@@ -1751,15 +1751,15 @@ Every new SVG project declares one deterministic route. Free-design and brand-on### Explicit PPTX Master / Layout / Placeholder Metadata-**Trigger**: This explicit metadata interface applies only to deck/layout template projects and structure-restoration workflows. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. Flat free-design/brand-only SVGs use none of these metadata fields.+**Trigger**: This explicit metadata interface applies only to new pages generated from a current deck/layout template workspace. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. Flat free-design/brand-only SVGs use none of these metadata fields.**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A unique Layout row is `<layout_key>: <master_key> | <PowerPoint picker name> | <prototype source>`, where the source is a generated `P<NN>` or installed `template:<basename>`. A page assignment is `P<NN>: <layout_key>` under `page_pptx_layouts`. The SVG root values MUST match the assigned definition. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when prototypes share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. An unused Layout uses a template SVG source and remains registered without a published carrier slide. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.-**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve restored source identity, literal paint, typography, effects, atomic geometry, and referenced assets. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology.+**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology or fill missing facts.Imported inherited-shape visibility remains an immutable analysis fact until astructured mirror is materialized. The final mirror root carries that fact with-the two optional canonical booleans below so export can restore the source+the two optional canonical booleans below so export can write the preserved sourcepackage fields without inferring visibility from which shapes happen to bepresent. Authored `standard` / `fidelity` templates normally omit both and usethe default `true`. See@@ -1799,8 +1799,8 @@ prototype size remain unchanged.| `data-pptx-master-name="Default Master"` | root `<svg>` | Sets the Master picker/display name || `data-pptx-layout="content"` | root `<svg>` | Binds the slide to one generated reusable layout key || `data-pptx-layout-name="Title and Content"` | root `<svg>` | Sets the PowerPoint layout-picker name; defaults from the layout key |-| `data-pptx-show-master-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and restores the assigned Layout's `p:sldLayout@showMasterSp`; every SVG using the same Layout key must repeat the same value; omission means `true` |-| `data-pptx-show-inherited-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and restores this Slide's `p:sld@showMasterSp`; `false` hides inherited Layout and Master shapes without removing backgrounds, placeholders, parts, or parent relationships; omission means `true` |+| `data-pptx-show-master-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and writes the assigned Layout's `p:sldLayout@showMasterSp`; every SVG using the same Layout key must repeat the same value; omission means `true` |+| `data-pptx-show-inherited-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and writes this Slide's `p:sld@showMasterSp`; `false` hides inherited Layout and Master shapes without removing backgrounds, placeholders, parts, or parent relationships; omission means `true` || `data-pptx-layer="master"` | direct semantic atom | Moves one repeated static object/background into the named Slide Master; ordinary `<g>` is forbidden, while one validated compact authored-preset `<g>` (§1.5) is an atomic exception || `data-pptx-layer="layout"` | direct semantic atom | Moves one repeated static object/background into the selected Layout; ordinary `<g>` is forbidden, while one validated compact authored-preset `<g>` (§1.5) is an atomic exception || `data-pptx-layer="slide"` | direct full-canvas solid `<rect>` only | Writes a one-page override as Slide `p:bg` |@@ -1912,11 +1912,17 @@ group—or the explicit composite proxy downgrade. `media` currently bindsan authored image/crop to a native `media` placeholder; it does not synthesizevideo or audio media from a decorative SVG group.-### Legacy Structure Migration Boundary+### Legacy Template Input Boundary-Existing structured/template projects or packages that carry `native_structure.json` / `source_template.pptx`, `pptx_structure.mode: baseline|template|preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled` / `utility`, direct atomic placeholders, or an incomplete root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation or export. A project explicitly declaring `pptx_structure.mode: flat` is the current free-design/brand-only route and does not require restoration merely because it has no Master/Layout metadata.+Existing structured/template projects or packages that carry `native_structure.json` / `source_template.pptx`, `pptx_structure.mode: baseline|template|preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled` / `utility`, direct atomic placeholders, or an incomplete root Master identity are not generation/export inputs and are never upgraded in place. Create a separate current workspace through [`create-template`](../workflows/create-template.md). A project explicitly declaring `pptx_structure.mode: flat` is the current free-design/brand-only route and needs no conversion merely because it has no Master/Layout metadata.-When original PPTX/native facts exist, migration preserves the complete source Master roster, Layout parent relationships and picker names, placeholder type/index/bounds, and visible supported geometry while normalizing the package into the explicit contract. Source Master/Layout groups are recursively flattened into atomic SVG elements. Create one reusable prototype SVG for every retained Layout, including Layouts unused by source slides; downstream `pptx_layouts` definitions can register those prototypes without manufacturing generated pages. A subsequent `create-template` run treats the result according to its selected mode: `standard` / `fidelity` author a new topology, while mirror keeps the restored source topology. When no native facts exist, the main Agent explicitly derives a structured contract from the complete SVG pages; the exporter never performs that derivation.+| Available source | Allowed create-template behavior |+|---|---|+| Original PPTX Type A | `standard` / `fidelity` author new topology; `mirror` preserves supported Master/Layout/placeholder facts that still exist in the package |+| Legacy or unstructured SVG Type B | `standard` / `fidelity` use pages as visual/contextual reference and author a complete new contract; old metadata is not output topology |+| Complete current SVG Type B | `mirror` may preserve the explicit current contract in a new workspace; authored modes may replace it |++Without an original PPTX or complete current Type B contract, do not claim mirror or source-topology recovery. After template creation, Generate PPTX Step 3 authors new structured `svg_output/` pages; the exporter only compiles those declarations and never derives, repairs, or migrates structure.---diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 7cc93acd..c063e90a 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -36,7 +36,7 @@ The design-system items are anchored by Stage 1 — `visual_style` governs `e` /> **Execution discipline**: This is the last BLOCKING checkpoint in the pipeline. After confirmation, complete the Design Spec and proceed to image generation / SVG / post-processing without further pauses.>-> **One opt-in exception**: present the spec-refinement line alongside the split-mode note (SKILL.md Step 4). It is OFF by default — the above discipline holds unchanged. Only when the user *explicitly* asks to refine the spec do you hand off to the [refine-spec](../workflows/refine-spec.md) workflow, which produces the full spec first and stops for user review/revision of any part before generation. Never enter it unprompted.+> **One opt-in exception**: present the spec-refinement line alongside the split-mode note (SKILL.md Step 4). It is OFF by default — the above discipline holds unchanged. Only when the user *explicitly* asks to refine the spec do you hand off to the [refine-spec](../workflows/stages/refine-spec.md) stage, which produces the full spec first and stops for user review/revision of any part before generation. Never enter it unprompted.> **Default presentation surface — Confirm UI.** Deliver the bundled package through the interactive page: write your recommendations to `<project>/confirm_ui/recommendations.json`, then launch per [SKILL.md Step 4](../SKILL.md). You still author everything — enumerable fields name a recommended `id`; generative fields (color `palette`, CJK + Latin typography, generated-image style) each carry **≥3 distinct candidates**, and the deck's **visual style** (§d Layer 2) carries a **≥3-style personality spectrum** (`visual_style_spectrum`, safe / shifted / bold) — creative recommendations always offer real choice, never a single silent option, same hard rule and thinking as h.5. Honest-shortfall exception (mirrors h.5): if the constraints genuinely cannot yield 3 non-conflicting options, present the smaller set and say why — never pad with duplicates or known-conflicting fillers. **Always also print the recommendations + URL in chat** as the always-valid fallback. On confirm, read `<project>/confirm_ui/result.json` (`generation_mode: "split"` / `refine_spec: true` are explicit user choices). Skip the page if the user wants chat-only. Full launch flow, field rules, and JSON schema live in [SKILL.md Step 4](../SKILL.md) + [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md) — don't restate them here. The page is a confirmation surface only.@@ -60,7 +60,7 @@ Read the user's prose as a point on a spectrum and apply judgment — from *stay**Hard rule — facts stay sourced however free the user asks.** Divergence is freedom to *develop* what is in the source (reorganize / reframe / expand / connect), never licence to invent. Even the freest request must not introduce facts, figures, or claims from outside the source material — that is the `topic-research` job, not divergence. `mode` and divergence are orthogonal (e.g. a pyramid that hews to the source's own points vs. a pyramid built from freely synthesized themes).-**Consumption — outline-authoring only.** Apply the user's stated intent when authoring the `§IX` outline. Record the prose (or "balanced default") in `design_spec.md §I` (Content Strategy). Do **NOT** write it to `spec_lock.md` — it is baked into `§IX` at authoring time and the Executor never reads it. It carries no page-count coupling — the §b page count stays the user's separate call. The beautify / template-fill workflows keep content verbatim, so they do not surface this field.+**Consumption — outline-authoring only.** Apply the user's stated intent when authoring the `§IX` outline. Record the prose (or "balanced default") in `design_spec.md §I` (Content Strategy). Do **NOT** write it to `spec_lock.md` — it is baked into `§IX` at authoring time and the Executor never reads it. It carries no page-count coupling — the §b page count stays the user's separate call. The beautify profile and Fill Native PPTX route keep content verbatim, so they do not surface this field.### d. Style Objective Confirmation@@ -76,7 +76,7 @@ The deck's **narrative + persuasion skeleton** — how the argument is organized**Source**:- User supplied their own outline / structure → it is authoritative. Transcribe it into `§IX` as given (page order + titles preserved); still lock a mode, but for register / voice and page-internal treatment, **not** to reshape — never reorder the user's pages or rewrite their given titles. Note in `design_spec.md` that the structure is user-authored. `briefing` imposes the least if no particular "讲法" is intended.-- Beautify / re-layout workflow ([`beautify-pptx.md`](../workflows/beautify-pptx.md)) → the extracted source content is authoritative and **verbatim**, one step stricter than the user-outline case above. Each source slide becomes exactly one `§IX` page in source order; transcribe every content block word-for-word — never reshape / re-primary / condense / merge / split / reword. Lock `mode: briefing`; color (e) and typography (g) are whatever the user confirmed in the beautify plan — the source identity (theme or observed) by default, or a content / brand-aware alternative the beautify plan offered and the user picked — locked as truth (the beautify plan already ran the recommendation through the confirm UI, so do not re-recommend here). Charts / tables / images are regenerated from their extracted data in the inherited style (route chart/table data to §VII, pictures to §VIII) — data values stay frozen, the rendering is the deck's own; never carried over verbatim. Layout, hierarchy, rhythm, and visual rendering are what gets redesigned.+- Beautify / re-layout profile ([`beautify-pptx.md`](../workflows/profiles/beautify-pptx.md)) → the extracted source content is authoritative and **verbatim**, one step stricter than the user-outline case above. Each source slide becomes exactly one `§IX` page in source order; transcribe every content block word-for-word — never reshape / re-primary / condense / merge / split / reword. Lock `mode: briefing`; color (e) and typography (g) are whatever the user confirmed in the beautify plan — the source identity (theme or observed) by default, or a content / brand-aware alternative the beautify plan offered and the user picked — locked as truth (the beautify plan already ran the recommendation through the confirm UI, so do not re-recommend here). Charts / tables / images are regenerated from their extracted data in the inherited style (route chart/table data to §VII, pictures to §VIII) — data values stay frozen, the rendering is the deck's own; never carried over verbatim. Layout, hierarchy, rhythm, and visual rendering are what gets redesigned.- A bespoke direction the five don't give — a nameable cadence (dialectic 正反合, myth-vs-reality, countdown, Socratic), a multi-act fusion of modes, or the user's own feel (confrontational here, detached there). Either the user asks, **or you recommend it** when a fusion / bespoke direction genuinely serves the deck better than a single preset (a recommendation the user confirms, like every lock). The *kind* doesn't matter → `mode: custom` + a `mode_behavior:` paragraph that **crystallizes the intent** (act sequence or posture shifts, title voice, page rhythm, register) concretely enough for the Executor to follow per page; it reads only `spec_lock.md`, never the chat. One deck locks **one** value — a fusion is one `custom` describing the acts, never several modes. Avoid only the *dodge*: don't default to `custom` when a preset genuinely fits, and prefer a dominant mode + page-level variation when one mode leads.- No user structure or cadence → recommend by the index's auto-selection table (content / audience signal → mode) plus the deck's stated purpose; the mode does the structural lifting. Present as a recommendation; the user may override.@@ -100,7 +100,7 @@ Write the locked value to `spec_lock.md` `- visual_style:` and the rationale to> **Template vs preset**: a style mention and a template name remain different inputs ("minimalist" vs the `presentation_core/` template directory). Step 3 only triggers on an explicit template directory path supplied by the user — bare names and style words never copy templates; they map to a visual-style preset here. If a template was triggered upstream, its files are already in `<project_path>/templates/` and its fused design_spec governs.-**Legacy template boundary**: A template containing `native_structure.json`, `source_template.pptx`, missing root Master identity, direct atomic placeholders, or old `baseline` / `preserve` / distillation metadata must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before Step 3. Do not plan against a legacy compatibility contract.+**Legacy template boundary**: A template containing `native_structure.json`, `source_template.pptx`, missing root Master identity, direct atomic placeholders, or old `baseline` / `preserve` / distillation metadata is not a Step 3 input. Create a new current workspace through [`create-template`](../workflows/create-template.md), preferably from the original PPTX when existing native topology matters. Do not plan against a legacy compatibility contract or mutate the input in place.**Template adherence confirmation**: Surface this closed Stage-1 choice only when Step 3 loaded a `kind: deck` or `kind: layout` template. Omit it for free design and brand-only templates.@@ -252,7 +252,7 @@ See [`../templates/icons/README.md`](../templates/icons/README.md) for the curre>> **Structural roles (page title / body / subtitle / annotation / footnote) resolve to one size each and hold it deck-wide** — that consistency is what reads as professional. Picking an intermediate in-band size is for special / feature elements (hero number, display title, one-off emphasis); a recurring one is declared as its own slot so it stays consistent too.-> **Unit boundary (HARD rule).** The system is **px-only**. `recommendations.json`, the Confirm UI, `result.json`, `design_spec.md`, `spec_lock.md`, and SVG **all carry unitless px** — there is no pt layer anywhere, and no pt→px conversion step. pt exists only as the size PowerPoint happens to show *after export* (`px × 0.75`, rounded to 1 decimal); it is never an input, a confirmation value, or a provenance field (no `body_size_pt` / `sizes_pt`). Never write `pt` / `px` / `em` units; every layer carries bare px numbers. Geometry — margins, gaps, card sizes — is px too. (Beautify reads a source deck's pt at intake but converts to px **before** any recommendation — see [`beautify-pptx.md`](../workflows/beautify-pptx.md); pt never re-enters the contract.)+> **Unit boundary (HARD rule).** The system is **px-only**. `recommendations.json`, the Confirm UI, `result.json`, `design_spec.md`, `spec_lock.md`, and SVG **all carry unitless px** — there is no pt layer anywhere, and no pt→px conversion step. pt exists only as the size PowerPoint happens to show *after export* (`px × 0.75`, rounded to 1 decimal); it is never an input, a confirmation value, or a provenance field (no `body_size_pt` / `sizes_pt`). Never write `pt` / `px` / `em` units; every layer carries bare px numbers. Geometry — margins, gaps, card sizes — is px too. (The beautify profile reads a source deck's pt at intake but converts to px **before** any recommendation — see [`beautify-pptx.md`](../workflows/profiles/beautify-pptx.md); pt never re-enters the contract.)**Baseline — one fixed value per delivery purpose, not a range.** Delivery purpose is a **Stage-1 anchor confirmed in §c key information** (beside audience, not as a separate typography step — see §1 Three-stage confirmation); it is the primary driver because the same canvas reads very differently when read close vs. projected. It is a **deck-wide** axis — beyond the body baseline it also drives page density / count / rhythm; see §6.1 for that side. Here, with the purpose confirmed, it sets the body baseline to a single value:@@ -855,7 +855,7 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck- **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.- **pptx_structure is mandatory**: Free-design and brand-only routes write `mode: flat`. Deck/layout template routes write `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.- **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.- - **Master roster (deck/layout templates only)**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the restored prototype roster. Keys use 1–64 ASCII letters, digits, dots, underscores, or hyphens, start with a letter/digit, and contain no spaces; human-readable spaces belong only in `<picker name>`. Master visuals are root-level atomic elements and may never be `<g>`.+ - **Master roster (deck/layout templates only)**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the template workspace's declared prototype roster. Keys use 1–64 ASCII letters, digits, dots, underscores, or hyphens, start with a letter/digit, and contain no spaces; human-readable spaces belong only in `<picker name>`. Master visuals are root-level atomic elements and may never be `<g>`.- **pptx_layouts (deck/layout template reusable roster)**: Write every unique reusable Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy the installed template roster with `template:<basename>` sources, including Layouts no generated page currently uses. A genuinely new adaptive Layout uses its first generated `P<NN>` as the source. Reuse a key only when fixed Layout atoms plus slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition (`timeline-spine`, `kpi-band-trio`, `content-image-right`), never after page topic. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot.- **page_pptx_layouts (deck/layout template page assignment)**: Write exactly one `P<NN>: <layout_key>` row per generated page. The key must exist in `pptx_layouts`; Master and picker name are inherited from that unique definition. **Self-check before writing the section**: compare distinct assigned keys against distinct compositions in §IX. Distinct compositions collapsing into a handful of role-only keys means pages were clustered by topic label; one shared skeleton splitting into topic-specific keys means pages were split by content wording. Both misstate the roster.- **Slot planning (deck/layout templates only)**: Each reusable slot is a direct root `<g id>` with `data-pptx-placeholder`, positive design-zone bounds, and exactly one compatible direct carrier. Bounds come from the intended safe area, column, panel inset, or media frame—not sample text ink. A genuinely composite region may use only the explicit `object` + `proxy` downgrade.diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex a07228eb..2d64efc5 100644--- a/skills/ppt-master/references/template-designer.md+++ b/skills/ppt-master/references/template-designer.md@@ -4,13 +4,13 @@## Core Mission-Generate reusable page templates inside the complete workspace selected by `create-template`, and write a concise `design_spec.md` that captures the source-derived basic norms that make the template reusable.+Generate reusable structured page templates inside the workspace selected by Create Template's Create Layout or Create Deck child workflow, and write a concise `design_spec.md` that captures the source-derived basic norms that make the template reusable.-> This is a standalone role: only triggered via the `/create-template` workflow. Library and project outputs use one workspace shape; it is not the template selection step in the main PPT generation pipeline.+> This is a standalone role: only triggered by the Create Layout or Create Deck child workflow under `/create-template`. Create Brand never invokes it. Library and project outputs use one workspace shape; this is not the template selection step in the main PPT generation pipeline.## Usage-- **Trigger**: `/create-template` workflow+- **Trigger**: `/create-template` → Create Layout or Create Deck child workflow- **Workspace root**: `library` (default) → `skills/ppt-master/templates/<kind_dir>/<template_name>/`; `project` → the confirmed `<target_project>/`- **Template source**: `<template_workspace>/templates/` in both scopes- **Input**: finalized template brief (output scope, target project when project-scoped, template ID, display name, kind, applicable scenarios, tone, theme mode, canvas format, optional reference assets, accepted basic template norms)@@ -45,7 +45,7 @@ Input priority for PPTX-backed template creation depends on replication mode:| Mode | Authoritative inputs | Model-facing inputs ||---|---|---|| `standard` / `fidelity` | Finalized brief for the newly designed output; `manifest.json` for factual canvas/theme/assets | `authoring-svg/` and optional `authoring-svg-flat/` IR documents plus exported assets as visual references. Source Master/Layout topology is informational only and is not mined into output structure. |-| `mirror` | `manifest.json`, `native_structure.json`, `svg/inheritance.json`, and the authoring manifests | Layered `authoring-svg/` as the editable restoration IR; optional `authoring-svg-flat/` for complete-page verification; matching lossless `svg/` and optional `svg-flat/` only as immutable backing. |+| `mirror` | `manifest.json`, `native_structure.json`, `svg/inheritance.json`, and the authoring manifests | Layered `authoring-svg/` as the editable preservation IR; optional `authoring-svg-flat/` for complete-page verification; matching lossless `svg/` and optional `svg-flat/` only as immutable backing. |Use the compact facts in `manifest.json` for orientation. Open screenshots or the original PPTX only for visual cross-checking.@@ -54,7 +54,7 @@ Use the compact facts in `manifest.json` for orientation. Open screenshots or th| Mode | Output structure contract ||---|---|| `standard` / `fidelity` | Author project-canonical SVG prototypes and an intentional new Master/Layout/slot system. Source visual language and assets may guide the design, but source ownership, keys, picker names, parent relationships, placeholders, and repeated Slide-local elements do not define or seed the output topology. Use the compact authored-preset group only for exact registered preset matches. |-| `mirror` | Restore the source graph one-to-one: keep source Master/Layout identities and parentage, slide assignments, placeholder type/index/bounds, and supported visual/native-object facts. Edit the authoring IR; materialization may rehydrate converter-supported native payload only for unchanged source refs. Mechanical normalization maps fixed-layer source groups into the direct atoms required by the current explicit SVG contract while preserving ownership, paint order, and appearance; it must not semantically redesign the graph. |+| `mirror` | Materialize a new workspace from the validated source graph one-to-one: keep the Master/Layout identities and parentage, slide assignments, placeholder type/index/bounds, and supported visual/native-object facts that are actually present. Edit the authoring IR; materialization may rehydrate converter-supported native payload only for unchanged source refs. Mechanical normalization maps fixed-layer source groups into the direct atoms required by the current explicit SVG contract while preserving ownership, paint order, and appearance; it must not invent missing facts or semantically redesign the graph. |Every page remains a complete standalone SVG preview.@@ -73,7 +73,7 @@ expanded lossless source representation. The exact syntax and validationcontract remain owned by[`shared-standards.md`](./shared-standards.md) and the native-shape reference.-**Hard rule — complete mirror graph**: Restore every supported source Layout,+**Hard rule — complete mirror graph**: Preserve every supported source Layout represented by the validated import,including Layouts unused by source Slides. Emit one complete source-pageprototype per source Slide and one definition-only`layout_<layout_key>.svg` prototype for each otherwise unrepresented Layout.@@ -86,7 +86,7 @@ Never silently drop or merge an identity, and never invent a carrier page.**Downstream boundary**: The Strategist confirmation stage selects `strict` or `adaptive` when a project consumes this package. Both export through `pptx_structure.mode: structured`. Strict keeps the referenced Layout contract; adaptive may create a new Layout identity while retaining the template Master. Template_Designer does not preselect that project-level choice.-For `mirror`, `design_spec.md §V` must be followed by a `Source Restoration Map` that records each source slide's Master/Layout assignment and output file. The map is evidence of one-to-one preservation, not a design-decision log. `standard` and `fidelity` record only their newly authored output roster and structure; do not add a source-topology disposition table.+For `mirror`, `design_spec.md §V` must be followed by a `Source Preservation Map` that records each source slide's Master/Layout assignment and output file. The map is evidence of one-to-one preservation, not a design-decision log. `standard` and `fidelity` record only their newly authored output roster and structure; do not add a source-topology disposition table.---@@ -98,9 +98,9 @@ The output page set is determined by **replication mode**, declared in the final|------|-------------|--------|| `standard` (default) | Most templates — clean, reusable, balanced coverage | `01_cover`, `02_chapter`, `03_content`, `04_ending`; with the optional TOC the roster is `01_cover`, `02_toc`, `03_chapter`, `04_content`, `05_ending` || `fidelity` | User wants a broader, source-aligned but newly designed template | Standard roster + intentionally designed variants that cover useful reference compositions |-| `mirror` | User wants the source template restored | One SVG prototype materialized from the authoring IR per source slide, named `<NNN>_<page_type>.svg` by source order |+| `mirror` | User wants a new template workspace that preserves validated native source facts | One SVG prototype materialized from the authoring IR per source slide, named `<NNN>_<page_type>.svg` by source order |-**Hard rule — mode controls authorship**: `standard` and `fidelity` create new SVG documents and their own Master/Layout system. `mirror` restores the imported source contract and must not reauthor, distill, or reinterpret its structure.+**Hard rule — mode controls authorship**: `standard` and `fidelity` create new SVG documents and their own Master/Layout system. `mirror` maps the validated imported source contract into a new workspace and must not reauthor, distill, reinterpret, or supplement its structure.### Standard mode@@ -141,19 +141,19 @@ Extension page types beyond the canonical four (transition / appendix / disclaim### Mirror mode-When the brief sets `Replication mode: mirror`, restore the imported template rather than designing a new one:+When the brief sets `Replication mode: mirror`, materialize a new template workspace from validated imported facts rather than designing a new system:- Authoring source: layered `authoring-svg/*.svg` plus `authoring-svg/authoring_manifest.json`, `svg/inheritance.json`, and `native_structure.json`. When present, use `authoring-svg-flat/` only for full-page verification. Matching lossless `svg/` and optional `svg-flat/` files are immutable backing; materialization resolves only the layered backing.- Precondition: the import evidence identifies every source Master/Layout, parent relationship, picker name, placeholder contract, and fixed visual layer. Stop only when required facts or supported geometry are missing; unused identities are not a stop condition.- Output: `<template_workspace>/templates/<NNN>_<page_type>.svg` for every source slide, plus `layout_<layout_key>.svg` for every source Layout unused by all source slides. `<NNN>` is the zero-padded source slide index (3 digits) and `<page_type>` is derived from `manifest.json` `pageTypeCandidates` — `cover` / `toc` / `chapter` / `content` / `ending`. When the page-type heuristic is ambiguous, fall back to `content`. Preserve source slide order via the numeric prefix; definition-only files are not generated pages.-- Required restoration: preserve source Master/Layout keys and picker names, Layout-to-Master parentage, slide assignments, placeholder type/index/bounds, supported native-object metadata, geometry, decoration, sprite-sheet wrappers, original example text, chart previews, fonts, effects, and paint order whenever the importer represents them.+- Required preservation: preserve source Master/Layout keys and picker names, Layout-to-Master parentage, slide assignments, placeholder type/index/bounds, supported native-object metadata, geometry, decoration, sprite-sheet wrappers, original example text, chart previews, fonts, effects, and paint order whenever the importer represents them.- Allowed normalization: add or normalize explicit root declarations and asset paths, and recursively expand fixed Master/Layout group wrappers into direct atoms. The mapping must remain one-to-one at the ownership level and must not change paint order or appearance.- Forbidden: commonality extraction, semantic synthesis, merging, splitting, promotion, demotion, renaming, re-parenting, decorative simplification, placeholder invention, or replacement of supported source-native metadata / SVG fallback with a model-authored approximation.-- `design_spec.md` §V Page Roster lists every emitted file and marks definition-only prototypes explicitly. `Source Restoration Map` records each source-slide assignment plus every unused Layout definition and its parent Master.+- `design_spec.md` §V Page Roster lists every emitted file and marks definition-only prototypes explicitly. `Source Preservation Map` records each source-slide assignment plus every unused Layout definition and its parent Master.**Mirror consumption boundary**: `mirror` applies only while creating the template package from the source deck. Once created, the package is consumed as an ordinary deck / layout template roster: downstream generation may select, repeat, skip, reorder, or adapt pages according to the new content. The `replication_mode: mirror` field must not force the generated deck to preserve the source page count, source order, or one-output-slide-per-template-slide mapping.-**What mirror is not**: a redesign or topology-cleanup mode. It may mechanically transcode the imported representation into the current explicit SVG/package contract, so byte identity is not promised. Charts, SmartArt, OLE objects, and EMF / WMF media that fail to round-trip in `pptx_template_import.py` will fail the same way in mirror. If the import workspace has missing media or unsupported objects, mirror inherits those gaps — report them before restoration begins.+**What mirror is not**: a redesign, topology-cleanup, or recovery mode. It may mechanically transcode the imported representation into the current explicit SVG/package contract, so byte identity is not promised. Charts, SmartArt, OLE objects, and EMF / WMF media that fail to round-trip in `pptx_template_import.py` will fail the same way in mirror. If the import workspace has missing media or unsupported objects, mirror inherits those gaps — report them before materialization begins.---@@ -227,9 +227,9 @@ page_count: <N>- Optional XML snippet for any reusable component unique to this template## V. Page Roster-One row per emitted SVG describing what this template's version of cover / chapter / content / ending looks like (background treatment, decorative anchors, layout rhythm, image behavior, content density, intended content slot). For `standard` / `fidelity`, record the newly authored Layout key and PowerPoint picker name. For `mirror`, record the restored source Master/Layout keys and picker names without redesigning them. Roster entries must match the actual SVG files on disk.+One row per emitted SVG describing what this template's version of cover / chapter / content / ending looks like (background treatment, decorative anchors, layout rhythm, image behavior, content density, intended content slot). For `standard` / `fidelity`, record the newly authored Layout key and PowerPoint picker name. For `mirror`, record the preserved source Master/Layout keys and picker names without redesigning them. Roster entries must match the actual SVG files on disk.-For `mirror`, add `### Source Restoration Map` immediately after the roster with columns `Source slide`, `Source Master`, `Source Layout`, `Output SVG`, and `Restoration status`. This is a one-to-one mapping record. Do not add synthesis rationale or source-structure disposition rows to `standard` / `fidelity` templates.+For `mirror`, add `### Source Preservation Map` immediately after the roster with columns `Source slide`, `Source Master`, `Source Layout`, `Output SVG`, and `Preservation status`. This is a one-to-one mapping record. Do not add synthesis rationale or source-structure disposition rows to `standard` / `fidelity` templates.## VI. Assets (omit when none)Logos, cover backgrounds, brand textures bundled with the template package — file name, dimensions, intended usage.@@ -273,7 +273,7 @@ page_types: [cover, toc, chapter, content, ending]## V. Page RosterOne row per emitted SVG with Layout key, picker name, intended content, and slot behavior. Roster entries must match the actual files on disk.-For `mirror`, append the same `### Source Restoration Map` required above.+For `mirror`, append the same `### Source Preservation Map` required above.## VII. Placeholder Overrides (omit when none)Reference the `placeholders:` frontmatter declaration and explain the structural vocabulary deviation.@@ -321,7 +321,7 @@ If PPTX import output exists:- For `standard`, inspect enough lightweight complete-page IR documents to understand the requested visual direction and reusable assets; do not analyze source topology.- For `fidelity`, inspect every lightweight complete-page IR document so the newly designed roster covers the useful source composition range; do not derive output ownership from source Master/Layout recurrence.-- For `mirror`, verify every authoring Master, Layout, and Slide plus its manifest record against `native_structure.json` and `svg/inheritance.json`, then materialize from the IR with matching lossless payload backing. Before restoration begins, report the verified source slide indexes.+- For `mirror`, verify every authoring Master, Layout, and Slide plus its manifest record against `native_structure.json` and `svg/inheritance.json`, then materialize from the IR with matching lossless payload backing. Before materialization begins, report the verified source slide indexes.### 2.1 PPTX Import Mode Rule@@ -331,9 +331,9 @@ The imported PPTX has a different authority level in each replication mode.|---|---|| `standard` | Use source visuals/assets as references, then author the project-canonical roster and its Master/Layout/slot structure from the confirmed brief. Do not preserve or distill source topology. || `fidelity` | Use the complete visual roster as design reference, then author a broader canonical roster and its own Master/Layout/slot structure. Match the source visual language closely, but do not cluster, merge, or split source Layouts into output families. |-| `mirror` | Restore source pages, inheritance, placeholders, native objects, and visuals from the lossless import. Do not simplify, redesign, rename structure, or infer new common structure. |+| `mirror` | Preserve validated source pages, inheritance, placeholders, native objects, and visuals from the lossless import while creating a new workspace. Do not simplify, redesign, rename structure, infer new common structure, or fill gaps. |-**Hard rule — restoration is mechanical**: Mirror may normalize namespaces,+**Hard rule — mirror materialization is mechanical**: Mirror may normalize namespaces,portable asset paths, explicit root declarations, and fixed-layer group wrappersrequired by the current compiler. Expanding a source Master/Layout group mustproduce direct atoms with the same ownership, transforms, paint order, and@@ -347,7 +347,7 @@ template.| Lossless import SVG | Native-payload backing | Retain complete imported metadata, native object boundaries, hidden carriers, and source-scope identity. Keep it immutable and resolve it only through validated source refs. || Authoring IR bundle | Editable template-creation source | Omit opaque native payload and duplicate hidden carriers from model context; retain visible shape intent and stable document-local source refs. `authoring_manifest.json` records source paths and initial hashes without duplicating payload. || `standard` / `fidelity` output | Newly authored contract | Use `preset_shape_svg.py` compact canonical `<g>` output for exact preset matches, with paint from the confirmed brief / `design_spec.md`; use ordinary project SVG for other geometry. Reuse exported image/vector assets, not opaque source shape payload or source topology. |-| `mirror` output | Materialized restored contract | Preserve currently supported imported metadata on unchanged Slide-local/slot refs, use the edited SVG fallback otherwise, and normalize fixed structural layers into semantic atoms. Strip IR-only source refs from final templates. |+| `mirror` output | Materialized preserved contract | Preserve currently supported imported metadata on unchanged Slide-local/slot refs, use the edited SVG fallback otherwise, and normalize fixed structural layers into semantic atoms. Strip IR-only source refs from final templates. |**Validation**: Mirror does not silently use stale metadata. Materializationvalidates source-document hashes and each referenced object's initial authoring@@ -360,18 +360,18 @@ reserved for optional PowerPoint-native Chart/Table replacement markers.**Explicit template SVG contract**:-| Authored/restored fact | Template SVG declaration |+| Authored/preserved fact | Template SVG declaration ||---|---|| Master/Layout identity | Root `data-pptx-master` / `data-pptx-master-name` plus `data-pptx-layout` / `data-pptx-layout-name`; authored keys for `standard` / `fidelity`, source keys for `mirror` || Authored Master/Layout visual | In `standard` / `fidelity`, use a direct atomic child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"`. An ordinary `<g>` is forbidden; one validated compact canonical authored-preset `<g>` is a semantic atom and is the sole group exception. |-| Restored Master/Layout visual | In `mirror`, recursively expand each fixed-layer source group into direct atoms with the same Master/Layout ownership, transforms, styles, paint order, and appearance; semantic regrouping is forbidden |+| Preserved source Master/Layout visual | In `mirror`, recursively expand each fixed-layer source group into direct atoms with the same Master/Layout ownership, transforms, styles, paint order, and appearance; semantic regrouping is forbidden || Content slot | Direct `<g id>` with `data-pptx-placeholder` and explicit `data-pptx-placeholder-bounds`; `standard` / `fidelity` author the slot, while `mirror` preserves source type/index/bounds and carrier identity || Page-only background | Direct full-canvas solid rect with `data-pptx-layer="slide"` || Structural page-frame hint | Optional `data-pptx-role` only when background/decoration/header/footer/logo/watermark/chrome/page-number behavior is not already expressed by layer/placeholder metadata; stable unique `id` required |-Repeat inherited visuals in every standalone SVG so browser preview remains complete. Template export validates their equality and restores or creates the declared Master/Layout parts. It does not infer ownership.+Repeat inherited visuals in every standalone SVG so browser preview remains complete. Template export validates their equality and materializes the declared Master/Layout parts. It does not infer ownership.-**Forbidden — legacy structure contract**: Do not carry `data-pptx-layout-kind`, `distilled`, `utility`, unmapped `baseline`, `preserve`, or direct atomic placeholders into a reusable template package. Route that source through [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.+**Forbidden — legacy structure contract**: Do not carry `data-pptx-layout-kind`, `distilled`, `utility`, unmapped `baseline`, `preserve`, or direct atomic placeholders into a reusable template package. In `standard` / `fidelity`, treat such Type B inputs only as visual reference and author a complete current contract in a new workspace. Require the original PPTX Type A path when mirror must preserve existing native topology; see [`create-template`](../workflows/create-template.md).**Composite slot boundary**: A normal slot group has exactly one compatibledirect carrier. A validated compact canonical authored-preset `<g>` counts as@@ -531,7 +531,7 @@ Mirror mode emits one SVG per source slide, named by source order:└── 050_ending.svg```-Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. Literal source text and the source native structure are restored by materializing the authoring IR; IR-only refs and its manifest are not copied into the template output.+Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. Literal source text and validated native structure facts are preserved when the authoring IR is materialized into the new workspace; IR-only refs and its manifest are not copied into the template output.**Hard rule — common routing**: Keep `design_spec.md`, template SVGs, and non-bitmap template-source assets in `templates/`; place every bitmap in `images/`; place each imported vector exactly once in `icons/imported/` and reference it as `data-icon="imported/<name>"`. Never create `templates/icons/`. Write a review deck to `exports/` when explicitly requested and always for a multi-Master package gate. Create optional directories only when they contain real files; never add placeholders for empty directories. Do not branch asset placement by output scope.@@ -544,7 +544,7 @@ When a review deck was generated, include its path in the completion summary. OmIf the template is based on PPTX import output, briefly note:- which extracted assets were reused directly- for `standard` / `fidelity`, which visual references influenced the newly authored roster-- for `mirror`, whether any source feature could not be restored and the exact affected source object/page+- for `mirror`, whether any source feature could not be preserved and the exact affected source object/page- whether any page-type filename mapping required judgment beyond the import heuristic---diff --git a/skills/ppt-master/references/visual-review.md b/skills/ppt-master/references/visual-review.mdindex 3a5c013c..f3390f3f 100644--- a/skills/ppt-master/references/visual-review.md+++ b/skills/ppt-master/references/visual-review.md@@ -1,6 +1,6 @@# Visual Review Rubric-> Per-page visual self-check rubric for slide SVGs. Read by the subagents spawned during the `visual-review` workflow. Companion to the [`visual-review` workflow](../workflows/visual-review.md) and the [`visual_review.py`](../scripts/visual_review.py) renderer.+> Per-page visual self-check rubric for slide SVGs. Read by the subagents spawned during the `visual-review` stage. Companion to the [`visual-review` stage](../workflows/stages/visual-review.md) and the [`visual_review.py`](../scripts/visual_review.py) renderer.## §0 Prerequisites@@ -188,7 +188,7 @@ Each subagent writes exactly one file to `<project>/.review/<page>.json`:## §6 Dispatch & messaging contract-This rubric is consumed by subagents spawned via the `visual-review` workflow. Mandatory dispatch invariants:+This rubric is consumed by subagents spawned via the `visual-review` stage. Mandatory dispatch invariants:### §6.1 Orchestrator → subagent (batched dispatch)diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex f385822a..15bbf04f 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -204,9 +204,9 @@ Native `svg_to_pptx.py` release export reads the project's explicit structure moStructured template export compiles only the declared structure, maps locked typography/colors into PowerPoint defaults, creates the named Master/Layout parts, and reads the package back before publication. It never clusters pages, promotes repeated chrome heuristically, or invents placeholders. Flat export is the normal free-design/brand-only route: it creates only the clean project-owned shell and performs no promotion or deduplication of Slide content.-Template `page_layouts` records authoring-input provenance, `pptx_masters` / `pptx_layouts` own unique reusable definitions, and `page_pptx_layouts` owns page assignment. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. `standard` / `fidelity` author new SVGs and a new Master/Layout/slot contract. `mirror` restores the complete source identity graph—including unused Layout definitions—without semantic synthesis, while mechanically expanding fixed-layer group wrappers into the direct atoms required by the structured contract.+Template `page_layouts` records authoring-input provenance, `pptx_masters` / `pptx_layouts` own unique reusable definitions, and `page_pptx_layouts` owns page assignment. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. `standard` / `fidelity` author new SVGs and a new Master/Layout/slot contract. `mirror` materializes a new workspace from the complete validated source identity graph—including unused Layout definitions—without semantic synthesis or gap filling, while mechanically expanding fixed-layer group wrappers into the direct atoms required by the structured contract.-Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before release export. Explicit flat free-design/brand-only projects intentionally omit root Master identity.+Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete root Master identity must be replaced by a new workspace created through [`create-template`](../workflows/create-template.md). Generate new structured SVG pages from that workspace; do not upgrade the existing PPTX/SVG in place. Explicit flat free-design/brand-only projects intentionally omit root Master identity.`pptx_to_svg.py` annotates verified text-grid tables and conservative chart data with `data-pptx-replace-with` beside the visible SVG fallback and places the payload in `<metadata type="application/json">`; the parent claim selects the chart or table schema. Imported table/chart groups under this contract carry `data-pptx-import-source="pptx"`, whether active or fallback-only. Table import covers exact physical row/grid topology, canonical rectangular merges, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph schema. Each rich run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. A merge must use the exact `rowSpan` / `gridSpan` / `hMerge` / `vMerge` physical topology with empty merge slaves. Presentation-only source run XML without a non-empty `effectLst` / `effectDag` normalizes; a table-cell run effect disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, broken text topology, unsafe border XML, non-solid fills, and other merge encodings remain fallback-only. For table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`, the normalized SVG fallback resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct cell/run overrides; other built-in/custom style families are not implied.diff --git a/skills/ppt-master/scripts/beautify_identity.py b/skills/ppt-master/scripts/beautify_identity.pyindex 43a82561..a5ac51c4 100644--- a/skills/ppt-master/scripts/beautify_identity.py+++ b/skills/ppt-master/scripts/beautify_identity.py@@ -2,7 +2,7 @@"""PPT Master - Beautify Identity Extractor-Extract a source deck's visual identity as JSON for the beautify-pptx workflow:+Extract a source deck's visual identity as JSON for the beautify-pptx profile:the declared `theme` (palette + major/minor fonts + master placeholder sizes,full bodyStyle ramp in `sizes.body_levels`) plus `observed` usage (run-levelfonts incl. CJK `ea`, explicit point sizes, and frequent explicit fill colors)@@ -23,7 +23,7 @@ Examples:Dependencies:None beyond the standard library (reuses scripts/pptx_to_svg/).-See workflows/beautify-pptx.md for how the emitted identity is consumed.+See workflows/profiles/beautify-pptx.md for how the emitted identity is consumed."""from __future__ import annotationsdiff --git a/skills/ppt-master/scripts/beautify_inventory.py b/skills/ppt-master/scripts/beautify_inventory.pyindex 52013477..40240f3c 100644--- a/skills/ppt-master/scripts/beautify_inventory.py+++ b/skills/ppt-master/scripts/beautify_inventory.py@@ -3,7 +3,7 @@PPT Master - Beautify Inventory BuilderMechanically merge a source deck's extracts into one per-slide ledger for the-beautify-pptx workflow: text blocks + tables + charts + SmartArt structure (from a+beautify-pptx profile: text blocks + tables + charts + SmartArt structure (from a`template_fill_pptx.py analyze` slide_library.json) joined with the imagesbound to each slide (from a `ppt_to_md.py` image_manifest.json). The deterministicjoin only — `ignored` and `needs_confirmation` are emitted empty for the agent@@ -19,7 +19,7 @@ Examples:Dependencies:None (standard library only).-See workflows/beautify-pptx.md Step 4 for how the inventory is consumed.+See workflows/profiles/beautify-pptx.md Step 4 for how the inventory is consumed."""from __future__ import annotationsdiff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex fe00677d..64c247d2 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -208,4 +208,4 @@ The shape above is the **final** (Stage 3) result, carrying Stage 1 anchors, Sta## Scope- Confirmation surface only — Strategist authors every recommendation; the page never generates deck content.-- No SVG / layout preview here — that is the live preview server's job (`workflows/live-preview.md`, Step 6).+- No SVG / layout preview here — that is the live preview server's job (`workflows/stages/live-preview.md`, Step 6).diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 0fc465db..66b3e1ec 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -223,7 +223,7 @@ Outputs (per source deck, prefixed by file stem):- `<stem>.slide_library.json` — text slots, geometry, native tables, native chart display caches, and SmartArt nodes/connections- `source_profile.json` — the single multi-deck index: a compact Strategist-facing digest per deck (over identity, tables, charts, SmartArt, and page types) under `decks[]`, with prefixed artifact pointers-`project_manager.py import-sources` runs this automatically for PPTX/PPTM/PPSX/PPSM/POTX/POTM inputs and stores the bundle directly under `analysis/`. Multi-deck per project: importing several PPTX files gives each its own `<stem>.*` artifacts and a `decks[]` entry in the shared `source_profile.json` index (re-importing the same stem replaces its entry). The beautify / template-fill workflows stay single-deck and read one chosen deck's `<stem>.*` artifacts.+`project_manager.py import-sources` runs this automatically for PPTX/PPTM/PPSX/PPSM/POTX/POTM inputs and stores the bundle directly under `analysis/`. Multi-deck per project: importing several PPTX files gives each its own `<stem>.*` artifacts and a `decks[]` entry in the shared `source_profile.json` index (re-importing the same stem replaces its entry). The beautify profile and Fill Native PPTX route stay single-deck and read one chosen deck's `<stem>.*` artifacts.Usage boundary:- Standard generation uses these fields as facts and recommendation candidates; it does not inherit source slide coordinates or page order by default.diff --git a/skills/ppt-master/scripts/docs/pptx-animations.md b/skills/ppt-master/scripts/docs/pptx-animations.mdindex 808b48d5..23d96a64 100644--- a/skills/ppt-master/scripts/docs/pptx-animations.md+++ b/skills/ppt-master/scripts/docs/pptx-animations.md@@ -15,7 +15,7 @@ defaults to `none`, exactly as before this validation upgrade.| Generated PPTX resolution and validation | `svg_to_pptx/pptx_package/builder.py` || Narration timing merge | `svg_to_pptx/pptx_package/narration.py` || Public authoring contract | `references/animations.md` |-| Customization workflow | `workflows/customize-animations.md` |+| Customization stage | `workflows/stages/customize-animations.md` |**Hard rule**: only the generated SVG-to-PPTX route writes object entranceanimations. Direct-PPTX routes preserve source animations and run structuraldiff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex feb3c5fc..8393f94d 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -76,7 +76,7 @@ generated files for their respective prefixes. In create-template workspaces,`imported` is the fixed namespace: assets live once under `icons/imported/`, andthe working SVGs reference them as `data-icon="imported/<name>"`. Inventoryentries retain source refs from each extracted subtree, allowing expansion to-restore the authoring-manifest mapping. A rerun on an+reconnect the authoring-manifest mapping. A rerun on analready rewritten namespaced projection inventories those references and doesnot progressively extract their remaining parent or sibling geometry.@@ -102,7 +102,7 @@ Materialization preserves source page order and emits one definition-only`layout_<layout_key>.svg` for every source Layout unused by all source Slides.It mechanically expands fixed Master/Layout group wrappers into direct atoms,rehydrates only unchanged converter-supported Slide-local/slot refs, keeps the-current SVG fallback for edited refs, restores explicit text hard breaks, and+current SVG fallback for edited refs, preserves explicit text hard breaks, andremoves every IR-only source ref. Source `p:sldLayout@showMasterSp` and`p:sld@showMasterSp` facts become canonical root`data-pptx-show-master-shapes` and@@ -115,7 +115,7 @@ The output routes reusable vectors once to `icons/imported/`, bitmaps to`images/`, and other referenced files to `templates/assets/`. The JSON reportis written to stdout only. The command intentionally does not create`templates/design_spec.md`; Template_Designer writes that personality and page-roster after materialization. This compiler is for Type A mirror restoration,+roster after materialization. This compiler is for Type A mirror materialization,not `standard` / `fidelity`, loose Type B SVGs, ordinary generation, finalize,or export.@@ -154,7 +154,7 @@ the declared `--resource-root` and are embedded into the asset.This operation belongs only to an explicit `create-template` normalizationdecision in `standard` or `fidelity` mode. It does not choose groups, detectrepetition, infer a Master/Layout, or run during ordinary import, free-generation, mirror restoration, finalize, or export. Placeholder, native+generation, mirror materialization, finalize, or export. Placeholder, nativesingle-shape, table/chart, icon-placeholder, and authored-preset groups arerejected because they already own a different semantic route.@@ -236,7 +236,7 @@ Behavior:- On structured template routes, each normal slot is a direct root `<g id>` with semantic type, positive design-zone bounds, and exactly one compatible carrier. Composite `object` slots use explicit proxy binding; zero-slot Layouts are valid. Flat pages keep all SVG objects Slide-local.- Flat export maps locked typography/colors into a clean project-owned theme/Master, removes stock content placeholders and unused built-in Layouts, retains only the standard date/footer/slide-number capability hooks, and keeps one Blank Layout without promoting Slide content. Structured export additionally creates one reusable Layout per declared key and reopens the package to verify the full Presentation → Master → Layout → Slide graph, fixed-object order, placeholder identities/bounds, carrier bindings, hidden proxies, and zero-slot Layouts.- Template `page_layouts` remains input provenance. Strict preserves the prototype contract; adaptive retains its Master and may use a new Layout identity only when fixed Layout atoms or slot topology/bounds change.-- Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete Master identity are rejected with a pointer to [`restore-pptx-structure`](../../workflows/restore-pptx-structure.md). Explicit flat free-design/brand-only projects intentionally omit Master identity.+- Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete Master identity are rejected with a pointer to [`create-template`](../../workflows/create-template.md). Create a new workspace and generate new structured SVG pages; do not upgrade the existing project in place. Explicit flat free-design/brand-only projects intentionally omit Master identity.- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.pyindex 0b46e5fe..7009e5a1 100644--- a/skills/ppt-master/scripts/notes_to_audio.py+++ b/skills/ppt-master/scripts/notes_to_audio.py@@ -236,7 +236,7 @@ def main() -> int:if args.provider == "edge" and not args.voice:parser.error("--voice is required for --provider edge. Run --list-voices --locale <locale> to discover voices "- "(e.g. --locale zh-CN), or follow skills/ppt-master/workflows/generate-audio.md "+ "(e.g. --locale zh-CN), or follow skills/ppt-master/workflows/stages/generate-audio.md ""for an AI-curated recommendation.")raise AssertionError("unreachable")diff --git a/skills/ppt-master/scripts/pptx_intake.py b/skills/ppt-master/scripts/pptx_intake.pyindex 34e50b46..f9366be9 100644--- a/skills/ppt-master/scripts/pptx_intake.py+++ b/skills/ppt-master/scripts/pptx_intake.py@@ -154,7 +154,7 @@ def build_source_profile("standard_generation": ("Use identity and slide-library fields as source facts and recommendation ""candidates only; do not preserve original page count, order, or coordinates "- "unless the user selected a beautify/template-fill workflow."+ "unless the user selected the beautify profile or Fill Native PPTX route."),"beautify": ("Promote source text, page order, page count, colors, fonts, and font sizes "diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.pyindex d1fd3716..2edbd182 100644--- a/skills/ppt-master/scripts/svg_quality_checker.py+++ b/skills/ppt-master/scripts/svg_quality_checker.py@@ -419,7 +419,7 @@ HEX_VALUE_RE = re.compile(# structure metadata. Template roster/placeholder checks always run. Current# bundled templates opt in to complete structure validation through their# native_structure_mode: structured declaration. Legacy template-mode packages-# fail closed and must run the explicit restoration workflow.+# fail closed; Create Template must author a new current-contract workspace._CHECK_PPTX_STRUCTURED_PROJECT = True_BARE_HEX_VALUE_RE = re.compile(@@ -4577,9 +4577,10 @@ class SVGQualityChecker:'release SVG projects require an explicit spec_lock.md ''pptx_structure.mode: flat (free design / brand-only) or 'f'structured (deck/layout template); found {label}. New '- 'free-design projects use mode: flat; restore legacy '- 'template/structured metadata by following skills/ppt-master/'- 'workflows/restore-pptx-structure.md before export.',+ 'free-design projects use mode: flat; create a new template '+ 'workspace through skills/ppt-master/workflows/create-template.md, '+ 'then generate new structured SVG pages before export. Existing '+ 'PPTX/SVG files are not upgraded in place.',))return@@ -5293,7 +5294,7 @@ class SVGQualityChecker:- **Explicit structure gaps** are errors when positive structure checksare enabled: every current reusable SVG declares its Master and Layoutidentity. Zero-placeholder Layouts are valid. Legacy template-mode- packages fail and must run the structure-restoration workflow.+ packages fail and must be replaced by a new create-template workspace.- **Placeholder gaps** are reported as *warnings*. Templates maylegitimately omit conventional placeholders or swap them out (e.g.``{{CLOSING_MESSAGE}}`` instead of ``{{THANK_YOU}}``), and a content@@ -5315,7 +5316,7 @@ class SVGQualityChecker:'explicit_structure_mode',"design_spec.md frontmatter must declare ""native_structure_mode: structured; legacy template-mode "- "workspaces must run restore-pptx-structure",+ "workspaces must be re-created through create-template",))if check_structure:native_contract_path = dir_path / 'native_structure.json'@@ -5391,8 +5392,8 @@ class SVGQualityChecker:'error','legacy_native_structure_pair',"legacy native_structure.json/source_template.pptx template "- "contracts must be restored through "- "skills/ppt-master/workflows/restore-pptx-structure.md",+ "contracts must be replaced through "+ "skills/ppt-master/workflows/create-template.md",))if declared_structure_mode != 'structured':@@ -5408,9 +5409,9 @@ class SVGQualityChecker:self._template_issues.append(('error','legacy_structure_contract',- "legacy template structure detected; run "- "skills/ppt-master/workflows/restore-pptx-structure.md before "- "Step 3 consumption",+ "legacy template structure detected; create a new current "+ "workspace through skills/ppt-master/workflows/"+ "create-template.md before Step 3 consumption",))spec_pages = self._extract_spec_roster(spec_text) if spec_text else []custom_contract = self._extract_frontmatter_placeholders(spec_text) if spec_text else {}@@ -5928,8 +5929,8 @@ def print_usage() -> None:print(" always enforce roster consistency and emit placeholder hints.")print(" native_structure_mode: structured also enables complete")print(" per-file and cross-page structure validation. Legacy")- print(" native_structure_mode: template fails and must run")- print(" restore-pptx-structure before validation.")+ print(" native_structure_mode: template fails and must be")+ print(" re-created through create-template before validation.")print(" Warnings are advisory: they require no modification and do not affect exit status;")print(" only errors make the command exit with status 1.")diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.pyindex 53d79861..9506bb73 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py@@ -115,8 +115,8 @@ def _declared_canvas_viewbox(project_path: Path) -> str | None:return value.strip() if isinstance(value, str) and value.strip() else None-def _print_structure_migration_error(mode: str | None) -> None:- """Explain how a legacy or absent SVG structure contract is restored."""+def _print_structure_contract_error(mode: str | None) -> None:+ """Explain how to replace a legacy or absent SVG structure contract."""label = repr(mode) if mode else 'missing (legacy implicit baseline)'print("Error: release SVG export requires an explicit spec_lock.md "@@ -125,9 +125,10 @@ def _print_structure_migration_error(mode: str | None) -> None:file=sys.stderr,)print(- " New free-design and brand-only projects use mode: flat. Restore "- "legacy template/structured metadata by following skills/ppt-master/"- "workflows/restore-pptx-structure.md before export.",+ " New free-design and brand-only projects use mode: flat. Create a "+ "new template workspace through skills/ppt-master/workflows/"+ "create-template.md, then generate new structured SVG pages before "+ "export. Existing PPTX/SVG files are not upgraded in place.",file=sys.stderr,)@@ -457,15 +458,15 @@ Recorded narration:pptx_structure = args.pptx_structuredeclared_structure_mode = _declared_pptx_structure_mode(project_path)if pptx_structure in _LEGACY_PPTX_STRUCTURE_MODES:- _print_structure_migration_error(pptx_structure)+ _print_structure_contract_error(pptx_structure)return 1if pptx_structure is None:if declared_structure_mode not in _RELEASE_PPTX_STRUCTURE_MODES:- _print_structure_migration_error(declared_structure_mode)+ _print_structure_contract_error(declared_structure_mode)return 1pptx_structure = declared_structure_modeelif pptx_structure == 'structured' and declared_structure_mode != 'structured':- _print_structure_migration_error(declared_structure_mode)+ _print_structure_contract_error(declared_structure_mode)return 1if (diff --git a/skills/ppt-master/scripts/visual_review.py b/skills/ppt-master/scripts/visual_review.pyindex 668de740..8a3e32b9 100644--- a/skills/ppt-master/scripts/visual_review.py+++ b/skills/ppt-master/scripts/visual_review.py@@ -4,7 +4,7 @@ PPT Master - Visual Review RendererRenders project SVGs to 1280x720 PNGs that match the live-preview browser view(inlined <use data-icon>, resolved <image href>, full font fallback including CJK).-The pure renderer for the visual-review workflow — does not edit SVGs, does not+The pure renderer for the visual-review stage — does not edit SVGs, does notinterpret the rubric.Backend: Playwright (Chromium). The cairosvg backend was evaluated and rejecteddiff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.mdindex 1cea0406..b3dc2926 100644--- a/skills/ppt-master/templates/README.md+++ b/skills/ppt-master/templates/README.md@@ -15,6 +15,12 @@ A brand is not “a layout minus its pages”: it owns a different segment. Usebrand for identity with free page composition, a layout for fixed reusablestructure with downstream identity, and a deck for a coherent complete system.+New workspaces always enter [`Create Template`](../workflows/create-template.md),+which keeps the fixed route name and dispatches exactly one child workflow:+[`Create Brand`](../workflows/create-template/create-brand.md),+[`Create Layout`](../workflows/create-template/create-layout.md), or+[`Create Deck`](../workflows/create-template/create-deck.md).+The indexes are discovery aids only. Step 3 activates a template only from anexplicit workspace-root path supplied by the user.@@ -23,7 +29,7 @@ explicit workspace-root path supplied by the user.| Axis | Values | Meaning ||---|---|---|| Template kind | `brand` / `layout` / `deck` | Which design segments the package owns |-| Creation mode | `standard` / `fidelity` / `mirror` | Newly author a compact or broad roster, or restore a source graph |+| Creation mode | `standard` / `fidelity` / `mirror` | Create Layout/Create Deck only: newly author a compact or broad roster, or materialize validated source-package facts into a new workspace; Create Brand is N/A || Downstream adherence | `strict` / `adaptive` | Preserve the selected Layout contract, or allow explicit new Layout identities || PPTX structure | `flat` / `structured` | Free-design/brand-only content stays Slide-local; layout/deck routes compile declared Masters and Layouts |diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.mdindex e79f6aee..2308186e 100644--- a/skills/ppt-master/templates/brands/README.md+++ b/skills/ppt-master/templates/brands/README.md@@ -21,10 +21,10 @@ Brand application follows the **same explicit-path rule and workspace routing as## Creating a new brand-Run the standalone workflow:+Enter the fixed Create Template route, which dispatches the Create Brand child workflow:```-Read skills/ppt-master/workflows/create-brand.md+Read skills/ppt-master/workflows/create-template.md, which dispatches `kind: brand` to skills/ppt-master/workflows/create-template/create-brand.md```Three input paths are supported: brand asset (logo / brand site URL / branded PPTX / brand PDF), verbal spec dictated in chat, or empty skeleton for the user to fill in later.diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.mdindex 8cea4505..0e9524c4 100644--- a/skills/ppt-master/templates/decks/README.md+++ b/skills/ppt-master/templates/decks/README.md@@ -3,12 +3,12 @@**Deck = a complete reusable template bundle.** It owns both presentationidentity and reusable page structure. A deck template is not a finished contentdeck, and `kind: deck` does not mean “mirror the source PPT”. Its construction-mode decides whether the system is newly authored or restored.+mode decides whether the system is newly authored or materialized from validated source facts.| Axis | Deck behavior ||---|---|| Template kind | `deck`: identity + structure + deck-specific overview |-| Creation mode | `standard` / `fidelity` author a new system; `mirror` restores the source graph |+| Creation mode | `standard` / `fidelity` author a new system; `mirror` materializes validated source-package facts into a new workspace || Downstream adherence | Strategist selects `strict` or `adaptive` when the package is used || PPTX structure | Always `structured`; `flat` is reserved for free design and brand-only routes |@@ -25,8 +25,9 @@ for the complete data model.Selection is opt-in through an explicit workspace-root path such as`skills/ppt-master/templates/decks/<deck_id>/`. Supplying a bare ID or readingthe discovery index does not trigger template use. Current packages resolve-`templates/design_spec.md`; a compatible legacy-flat root may resolve-`design_spec.md` directly. See [`SKILL.md`](../../SKILL.md) Step 3.+`templates/design_spec.md`; a compatible flat-directory current-contract root+may resolve `design_spec.md` directly. Semantic-legacy packages must be replaced+through Create Template rather than upgraded in place. See [`SKILL.md`](../../SKILL.md) Step 3.A deck path alone supplies the complete reference. When combined with a brandor layout path, brand replaces the identity segment and layout replaces the@@ -83,11 +84,11 @@ zero-slot Layouts are valid. `{{...}}` is the authoring vocabulary, while`data-pptx-placeholder*` is the native reconstruction contract.`standard` and `fidelity` author new SVGs and a new Master/Layout/slot system.-`mirror` preserves source identities, parentage, assignments, placeholder-facts, and supported visuals without semantic synthesis. Legacy semantic-contracts must run-[`restore-pptx-structure`](../../workflows/restore-pptx-structure.md); a flat-directory shape alone is not a legacy signal.+`mirror` preserves existing source identities, parentage, assignments,+placeholder facts, and supported visuals in a new workspace without semantic+synthesis. Legacy semantic contracts are not upgraded in place; create a new+workspace through [`create-template`](../../workflows/create-template.md). A+flat directory shape alone is not a legacy signal.---@@ -107,7 +108,7 @@ Library scope writes `skills/ppt-master/templates/decks/<deck_id>/` and updatesthe index. Project scope uses an initialized `projects/<name>/` workspace anddoes not register globally. Empty optional directories are omitted.-1. Run [`workflows/create-template.md`](../../workflows/create-template.md).+1. Enter [`workflows/create-template.md`](../../workflows/create-template.md), which dispatches integrated identity-and-structure output to [`create-deck.md`](../../workflows/create-template/create-deck.md).2. Validate with `svg_quality_checker.py --template-mode`.3. Run `template_preview_pptx.py` when review is requested and always when the roster declares multiple Masters.4. In library scope, register with `register_template.py <id> --kind deck`.diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 4b9acaed..10546642 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -308,7 +308,7 @@ Catalog read: 76 templates## IX. Content Outline-> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design and brand-only routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Deck/layout template routes use `mode: structured`: Strategist writes each unique Master/Layout definition once, assigns every page through `page_pptx_layouts`, and selects its authoring prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may define and assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Legacy prototypes first run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md); no deferred distillation or immediate-compatibility fallback exists.+> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design and brand-only routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Deck/layout template routes use `mode: structured`: Strategist writes each unique Master/Layout definition once, assigns every page through `page_pptx_layouts`, and selects its authoring prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may define and assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Legacy prototypes are not selectable; create a current workspace through [`create-template`](../workflows/create-template.md) and generate new SVG pages from it. No deferred distillation or immediate-compatibility fallback exists.### Part 1: [Chapter Name]diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.mdindex 3d1dfc89..f00ec026 100644--- a/skills/ppt-master/templates/layouts/README.md+++ b/skills/ppt-master/templates/layouts/README.md@@ -13,7 +13,7 @@ projects repaint and retype the selected structure from the project lock.| Axis | Layout behavior ||---|---|| Template kind | `layout`: structure only |-| Creation mode | `standard` / `fidelity` author a new system; `mirror` restores the source graph |+| Creation mode | `standard` / `fidelity` author a new system; `mirror` materializes validated source-package facts into a new workspace || Downstream adherence | Strategist selects `strict` or `adaptive` when the package is used || PPTX structure | Always `structured`; `flat` is reserved for free design and brand-only routes |@@ -33,9 +33,10 @@ reading the discovery index does not trigger template use. A layout path alonelocks structure while identity remains a downstream decision. Combined with abrand or deck, the layout replaces the complete structure segment.-Current packages resolve `templates/design_spec.md`; compatible legacy-flat-roots may resolve `design_spec.md` directly. See [`SKILL.md`](../../SKILL.md)-Step 3.+Current packages resolve `templates/design_spec.md`; compatible flat-directory+current-contract roots may resolve `design_spec.md` directly. Semantic-legacy+packages must be replaced through Create Template rather than upgraded in+place. See [`SKILL.md`](../../SKILL.md) Step 3.---@@ -90,11 +91,11 @@ vocabulary overrides declares a `placeholders:` map in frontmatter. Full rules:[`template-designer.md`](../../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template).`standard` and `fidelity` author new SVGs and a new Master/Layout/slot system.-`mirror` preserves source identities, parentage, assignments, placeholder-facts, and supported visuals without semantic synthesis. Legacy semantic-contracts must run-[`restore-pptx-structure`](../../workflows/restore-pptx-structure.md); a flat-directory shape alone is not a legacy signal.+`mirror` preserves existing source identities, parentage, assignments,+placeholder facts, and supported visuals in a new workspace without semantic+synthesis. Legacy semantic contracts are not upgraded in place; create a new+workspace through [`create-template`](../../workflows/create-template.md). A+flat directory shape alone is not a legacy signal.---@@ -115,7 +116,7 @@ updates the index. Project scope uses an initialized `projects/<name>/`workspace and does not register globally. Empty optional directories areomitted.-1. Run [`workflows/create-template.md`](../../workflows/create-template.md) and explicitly choose structure-only output.+1. Enter [`workflows/create-template.md`](../../workflows/create-template.md), which dispatches structure-only output to [`create-layout.md`](../../workflows/create-template/create-layout.md).2. Validate with `svg_quality_checker.py --template-mode`.3. Run `template_preview_pptx.py` when review is requested and always when the roster declares multiple Masters.4. In library scope, register with `register_template.py <id> --kind layout`.diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.mdindex c1acac7a..602a4347 100644--- a/skills/ppt-master/templates/spec_lock_reference.md+++ b/skills/ppt-master/templates/spec_lock_reference.md@@ -141,7 +141,7 @@> - mode: structured> - template_adherence: strict> ```-> Both values require complete `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before they can be selected.+> Both values require complete `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds cannot be selected or upgraded in place. Create a current workspace through [`create-template`](../workflows/create-template.md), then generate new structured pages from it.## pptx_masters- master-default: Default Masterdiff --git a/skills/ppt-master/workflows/create-brand.md b/skills/ppt-master/workflows/create-brand.mddeleted file mode 100644index cf05b9a6..00000000--- a/skills/ppt-master/workflows/create-brand.md+++ /dev/null@@ -1,231 +0,0 @@-----description: Generate a brand-only workspace under `templates/brands/<id>/` that captures colors, typography, logos, voice, and icon style without an SVG page roster.------# Create Brand Workflow--> Standalone preset-creation workflow. Output is a complete brand workspace at `skills/ppt-master/templates/brands/<brand_id>/`. A brand keeps the common workspace shape but omits the SVG page roster: Strategist locks identity while Executor designs pages freely.--This workflow edits the global brand library, not any specific `projects/<x>/`. Consumption follows the same explicit-path rule as layout templates (see [Downstream consumption](#downstream-consumption-informational) at the end).--> Companion: [`create-template.md`](./create-template.md) generates full templates with SVG pages. Use `create-brand.md` when the user wants identity-only locking with free page layout.--## When to Run--| User signal | Action |-|---|---|-| "set up brand" / "extract brand from this logo" | Run this workflow |-| User provides a brand asset (logo / brand site URL / branded PPTX / brand PDF) and wants it locked across future projects | Run this workflow |-| User mentions brand color or font once for a single deck only | Skip — handle inline via Strategist h.5 |-| `templates/brands/<requested_id>/` already exists | Ask: update / replace / use a new id — never silently overwrite |--⛔ Never auto-trigger. Brand creation is a user-invoked identity setup; an empty `templates/brands/` is not an invitation to create one.-------## Step 1: Detect input type--| Type | User-supplied input | Path |-|---|---|---|-| **A** Brand asset | Logo (SVG/PNG/JPG), brand site URL, branded PPTX, brand PDF | Step 2A — Asset extraction |-| **B** Verbal spec | User dictates HEX / font / tone directly in chat | Step 2B — Verbal capture |-| **C** Nothing | User wants to set up a brand but provides no asset and no spec | Step 2C — Empty skeleton |-------## Step 2A: Asset extraction--Read assets directly using existing converters — no dedicated extraction script.--| Asset format | Read method | Extractable fields |-|---|---|---|-| SVG logo | `Read` the SVG; grep `fill=` / `stroke=` for HEX | colors (literal), logo file |-| PNG/JPG logo | `Read` (multimodal); AI vision identifies dominant colors | colors (approximate HEX, label `[approx]`), logo file |-| Brand site URL | `python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>`, then `Read` the result | color references, font references, voice/tone |-| Branded PPTX | `python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <file>`, then read theme XML | colors, typography (literal) |-| Brand PDF | `python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <file>` | voice/tone; sometimes color/font references |--Identify which of (colors / typography / logo / voice / icon style) the asset did NOT cover, then proceed to Step 3 for the rest. Most single assets cover 1–2 categories well.--**Provenance labels** for each field in the draft `design_spec.md`:-- `[fact]` — extracted directly (SVG fill HEX, PPTX theme XML)-- `[approx]` — visual estimate (PNG/JPG color picking)-- `[user]` — supplied via chat fill-in in Step 3--**Hard rule — brand truth boundary**: Use `fact` only for a literal value extracted from an official asset/manual. Use `user` for values dictated in chat. Values inferred from an existing deck, website appearance, raster sampling, or presentation convention remain `approx`. Keep approximate presentation neutrals minimal; do not invent a semantic info/success/alert palette and lock it as brand identity.-------## Step 2B: Verbal spec capture--Ask once, bundled (do NOT itemize each field). Match the user's language. Example bundled prompt:--> "I'll record: primary / secondary / accent HEX, title font, body font, logo path (optional), tone (formal / neutral / casual), emoji allowed or not. Which do you want to lock now?"--Whatever the user gives is `[user]`-labelled. Skip Step 3 unless the user explicitly invites more fields.-------## Step 2C: Empty skeleton--Write `templates/brands/<brand_id>/templates/design_spec.md` with the full schema, every value as a TODO comment. Tell the user where the file is. Do not register the incomplete skeleton; registration requires concrete identity values. No further prompting — the user owns it from here.-------## Step 3: Chat fill-in (Type A only)--For fields not covered by the asset, ask the user in a single bundled message. Skip fields irrelevant to the user's intent.--| Field | When to ask |-|---|---|-| primary / secondary / accent HEX | always |-| text / bg HEX | only if dark-mode or inverted scheme mentioned |-| title / body font | when the asset gave no font reference |-| logo usage | when a logo file was provided |-| brand scope | when assets mix a company, product, subsidiary, or campaign identity |-| voice & tone | when audience or formality was mentioned |-| icon style preference | when icon consistency was mentioned |-------## Step 4: Materialize the brand workspace--Create the required template source directory. Create `images/`, `icons/`, or `exports/` only when writing a real asset or derived artifact; never add placeholder files for empty directories.--```bash-mkdir -p "skills/ppt-master/templates/brands/<brand_id>/templates"-```--### Mandatory: `templates/design_spec.md`--```markdown-----brand_id: <slug>-kind: brand-summary: <one-line use case, e.g. "ACME Corp marketing decks">-primary_color: "#XXXXXX"------# <Display Name> Brand Specification--> Identity-only preset. No SVG page roster — pages are composed freely under these constraints.--## I. Brand Overview-| Property | Value |-|---|---|-| Brand Name | <display name> |-| Use Cases | <summary> |-| Tone | <one-line tone summary> |-| Sources | <official URL or bundled asset paths; include retrieval/version date when known> |--## II. Color Scheme-| Role | HEX | Provenance |-|---|---|---|-| primary | #XXXXXX | fact \| approx \| user |-| secondary | #XXXXXX | fact \| approx \| user |-| accent | #XXXXXX | fact \| approx \| user |-| text | #XXXXXX | fact \| approx \| user; optional, default `#1A1A1A` |-| bg | #XXXXXX | fact \| approx \| user; optional, default `#FFFFFF` |--## III. Typography-| Role | Family | Weight |-|---|---|---|-| title | <family> | <weight> |-| body | <family> | <weight> |-| mono | <family> | optional |--## IV. Logo-- File: `../images/logo.<ext>` (relative to this design_spec.md)-- Usage: cover-only \| every-page \| never--## V. Voice & Tone-- Formality: formal \| neutral \| casual-- Person: informal-you \| formal-you \| we \| none-- Emoji: allowed \| forbidden-- Abbreviations: spell-out-first \| common-abbrev-allowed--## VI. Icon Style-- Preference: linear \| filled \| duotone # optional, drives icon library search--## VII. Visual Assets (optional)-- Images and illustrations: `../images/` # brand visual assets-- Icons: `../icons/` # branded icon overrides-```--**Section scope rules**:-- Layout / canvas / spacing / radius / shadow / page roster / signature design elements are OUT of brand scope. Those live in layout / deck workspaces (`templates/layouts/<id>/templates/design_spec.md` or `templates/decks/<id>/templates/design_spec.md`) or `shared-standards.md`. Do NOT add those sections here.-- HEX must be `#RRGGBB`-- Font names are free strings; not validated against locally installed fonts-- §VII is fully optional — list only directories that actually exist-- A company/product family may share one preset when the user explicitly wants that scope. Name the combined scope in §I and identify the owner of every logo/lockup in §IV; never relabel a product mark as the company mark.-- One preset has one default presenting entity. Subsidiary/campaign assets may remain as explicit alternates, but they never silently replace the default identity; create a separate brand workspace when their colors, typography, or voice differ.-- Record official usage or trademark restrictions next to the affected asset. Do not turn an observed public logo into permission to imply affiliation, sponsorship, or endorsement.--### Optional: logo file--If the user provided a logo, copy it to `templates/brands/<brand_id>/images/logo.<ext>` and preserve its source extension. Use descriptive filenames when several lockups exist.--### Optional: visual asset directories--Copy brand photos and illustrations into the workspace `images/` directory. Copy branded icon overrides into `icons/`. Reference only directories and assets that actually exist in §VII of `templates/design_spec.md`.--### NOT created here--No SVG page roster, canvas spec, signature design elements, or preview PPTX. Do not create an empty `exports/` directory. If the user later wants brand-anchored page templates, run `create-template.md` with this brand as a style reference.-------## Step 5: Validate, register, and hand off--Run the registrar in dry-run mode first. It validates the mandatory frontmatter, brand ID, required sections, roster-free scope, `#RRGGBB` colors and primary-color consistency, color provenance, and every referenced `images/` / `icons/` asset:--```bash-python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id> --dry-run-```--Fix every reported error, then register the same workspace:--```bash-python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id>-```--Emit the confirmation card:--```markdown-## ✅ Brand Saved-- Path: `skills/ppt-master/templates/brands/<brand_id>/`-- Files: templates/design_spec.md{, images/logo.<ext>}{, images/*}{, icons/*}-- Fields locked: <list>-- Provenance: <fact / approx / user counts>--How to use in a project:-- Include the brand workspace path in the initial Step 3 input, for example: "Create a Q4 summary using skills/ppt-master/templates/brands/<brand_id>/"-- Same explicit-path rule as layout templates: bare brand names never trigger-- May be supplied together with a layout template path; Step 3 fuses both into a single `design_spec.md` (brand wins on identity tokens, layout wins on page structure) — see `SKILL.md` Step 3-- To list available brands: open `templates/brands/brands_index.json`-- To edit: modify `templates/brands/<brand_id>/templates/design_spec.md`, then re-run `python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id>`-```-------## Downstream consumption (informational)--Brand application happens in [`SKILL.md` Step 3](../SKILL.md) under the **same explicit-path rule as layout templates**:--| User input at SKILL.md Step 3 | Behavior |-|---|---|-| Explicit brand workspace path supplied | Step 3 resolves `templates/design_spec.md`, stages `templates/`, `images/`, and `icons/` into their project peers, and locks color / typography / logo / voice as truth at Step 4 |-| Bare brand name, brand mention without path, or silence | Skip — no auto-application based on directory count or any other implicit signal |-| Both a brand path and a layout template path supplied in the same message | Step 3 fuses both into a single `design_spec.md` inside `<project_path>/templates/` (brand wins on identity tokens, layout wins on page structure). See `SKILL.md` Step 3 for the field-precedence table and the two conflict gates that may surface a clarifying question |--`brands_index.json` is discovery-only (mirrors `layouts_index.json` semantics); listing brands never advances the pipeline.-------## Notes--1. **Brand is identity, not layout** — colors / typography / logo / voice / icon style only. Page roster, canvas spec, and signature design elements belong to layout templates; do not duplicate them here.-2. **Common workspace routing** — brand assets use the same `templates/`, `images/`, `icons/`, and `exports/` routes as other template kinds; empty optional directories are omitted.-3. **No script dependency** — Step 2A reuses existing converters plus AI inline reading. A dedicated `brand_extract.py` is not introduced unless future user feedback demands batch processing or precise color picking from raster logos.-4. **Multi-brand support** — `templates/brands/` accepts any number of brands; agency / freelancer / multi-client workflows are natural.-5. **Precedence rule** — when a brand and a layout template both apply, Step 3 fuses them into one `design_spec.md`: brand wins on color / typography / logo / voice / icon style; layout wins on canvas / page roster / spacing / font-size hierarchy / signature visual elements. See `SKILL.md` Step 3 for the full precedence table.diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 7f7afcff..89f77d12 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -1,37 +1,40 @@----description: Generate a new layout or deck template based on existing project files or reference templates+description: Create Template entry workflow and shared contract for the Create Brand, Create Layout, and Create Deck sub-workflows.----# Create New Template Workflow+# Create Template Workflow-> **Role invoked**: [Template_Designer](../references/template-designer.md)+> **Fixed entry name**: user-facing template creation always enters **Create Template**. This workflow selects exactly one child workflow — [`create-brand.md`](./create-template/create-brand.md), [`create-layout.md`](./create-template/create-layout.md), or [`create-deck.md`](./create-template/create-deck.md) — and owns their shared execution contract.+>+> **Role invoked for Create Layout/Create Deck**: [Template_Designer](../references/template-designer.md)-Generate one complete layout/deck template workspace under either the **global template library** or `projects/`.+Create one reusable template workspace under either the **global template library** or `projects/` by dispatching to exactly one child workflow.-**Default — library scope**: Write `skills/ppt-master/templates/<kind>/<id>/` and register it in the matching discovery index.+**Default — library scope**: Write `skills/ppt-master/templates/<kind_dir>/<template_id>/` and register it in the matching discovery index.**Project scope**: Write the same portable workspace routing at `<project>/` and do not register any global index.**Hard rule — one workspace routing contract**: Output scope changes only the workspace parent and index registration. Both scopes use required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/`, with the same relative asset references and validation command. Never add placeholder files only to retain an empty directory. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.-> **Boundary against template-fill**: this workflow does not fill content into a PPTX and does not directly output the user's final generated deck. It creates a reusable template contract; an optional PPTX may be generated later for local review. To generate a deck from the workspace, return its root path to the main SKILL.md pipeline. A project-scoped workspace is already installed at that project's Step 3 path and is consumed in place.--> **Companion workflow**: identity-only locking (colors / typography / logo / voice without SVG pages) is handled by [`create-brand.md`](./create-brand.md). Use that when the user wants brand identity but free page layout; use this when fixed page structures are required.+> **Boundary against template-fill and in-place structure edits**: Create Template does not fill content into a PPTX, add Master/Layout structure to an existing PPTX/SVG, or directly output the user's final generated deck. It authors a separate reusable workspace; an optional PPTX is review evidence only. To generate a deck, return the workspace root to main Step 3 and author new SVG pages from it. A project-scoped workspace is already installed at that project's Step 3 path and is consumed in place.-## Kind decision — deck (default) vs layout+## Child Workflow Dispatch-This workflow produces one of two kinds of templates depending on whether the source PPT carries a specific brand identity:+Create Template is the fixed user-facing entry and common contract. It selects one child workflow, then that child owns the kind-specific lifecycle. Do not execute two children for one workspace or blend their schemas.-| Kind | When | Library-scope output dir | What `design_spec.md` writes |+| Child workflow | Select when | Library-scope output | Exclusive responsibility ||---|---|---|---|-| **deck** (default) | Source is a specific organization's branded PPT (e.g. company report, university defense template); the visual identity is part of the replica | `templates/decks/<id>/templates/` | Full segments: identity + structure + middle |-| **layout** | Source is a generic stylistic template (no specific brand); only the structural skeleton should be reusable; color / typography decided per-deck downstream | `templates/layouts/<id>/templates/` | Structure segments only (canvas / page structure / page types / SVG roster); identity segment omitted |+| [`Create Brand`](./create-template/create-brand.md) | Reuse identity only: colors, typography, logo, voice, and icon style | `templates/brands/<brand_id>/` | Identity analysis and identity-only `design_spec.md`; no SVG roster |+| [`Create Layout`](./create-template/create-layout.md) | Reuse a brand-neutral structural skeleton | `templates/layouts/<layout_id>/` | Canvas, page grammar, Master/Layout/slot contract, and SVG roster; no brand identity |+| [`Create Deck`](./create-template/create-deck.md) | Reuse identity and structure together, including a specific organization's presentation system | `templates/decks/<deck_id>/` | Integrated identity, structure, template overview, and SVG roster |-Default to **deck** unless the user explicitly says "structure only" / "layout only" / "no brand identity". When in doubt, lean deck — losing identity later is easy; reconstructing it from a layout-mode strip is not. See [`docs/zh/templates-architecture.md`](../../../docs/zh/templates-architecture.md) for the full kind / schema / fusion model.+Select Create Brand only for identity-only intent. Select Create Layout only when identity must remain downstream-selectable. Otherwise select Create Deck. Ask one discriminator question only when the user's requested reusable artifact is genuinely ambiguous; once selected, enter that child workflow and do not repeat route selection inside its confirmation gate.++See [`docs/zh/templates-architecture.md`](../../../docs/zh/templates-architecture.md) for the kind/schema/fusion model.## Output scope — library (default) vs project-Output scope is a workflow execution choice, not a new template kind or PPTX structure mode. Surface it in the Step 2 brief; do not invent a CLI flag or persist `output_scope` / `target_project` into portable `design_spec.md` frontmatter.+Output scope is a shared Create Template execution choice, not a new template kind or PPTX structure mode. Surface it in the Step 2 brief; do not invent a CLI flag or persist `output_scope` / `target_project` into portable `design_spec.md` frontmatter.| Scope | `<template_workspace>` | Template source | Registration ||---|---|---|---|@@ -42,7 +45,7 @@ Both scopes write this contract:```text<template_workspace>/-├── templates/ # design_spec.md and template SVGs+├── templates/ # design_spec.md; Create Layout/Create Deck also write SVGs├── images/ # optional; every bitmap; SVG href is ../images/<name>├── icons/│ └── imported/ # optional; one canonical copy of imported vector assets@@ -62,19 +65,23 @@ Any failed check aborts before writing `design_spec.md`, SVGs, images, icons, or## Process Overview```-Reference Intake & Analysis -> Basic Norm Extraction -> Fact-Based Brief Proposal -> User Confirmation Gate -> Preflight + Invoke Template_Designer -> Validate Assets -> [Review PPTX: optional for one Master, required for multi-Master] -> [Register Library Index] -> Output+Reference Intake & Analysis -> Fact-Based Brief Proposal -> User Confirmation Gate -> Preflight + Invoke Selected Child -> Validate Child Output -> [Structured Review PPTX: optional for one Master, required for multi-Master] -> [Register Library Index] -> Output```The first three steps derive the brief from facts, not guesses. **No final template directory may be created and no template SVG / `design_spec.md` may be written until `[TEMPLATE_BRIEF_CONFIRMED]` is emitted in Step 3.** Reference-analysis intermediates produced by `pptx_template_import.py` (typically under `/tmp/pptx_template_import/`) are explicitly **not** subject to this gate — they are temporary workspaces feeding Step 2.+After dispatch, the selected child workflow executes these shared steps with its kind fixed. Child-owned fields and validation rules come from that workflow; Create Template supplies the common mechanics and never reopens the child selection.+---## Step 1: Reference Intake & Analysis-Branch by the type of reference source the user supplied. This step produces analysis artefacts only — it does **not** create the final template directory, write `design_spec.md`, or touch any template index.+Branch by the type of reference source the user supplied. This step produces analysis artefacts only — it does **not** create the final template directory, write `design_spec.md`, or touch any template index. When Create Brand was selected, follow that child workflow's analysis rules and do not run page-topology analysis merely because the reference is a PPTX/PDF.### Input source taxonomy+The replication-mode column applies to Create Layout/Create Deck. Create Brand uses the same reference formats for identity evidence but has no replication mode, SVG roster, or native-structure path.+| Type | What the user supplied | Tool / read path | Replication modes available ||------|-------------------------|------------------|------------------------------|| **A** `.pptx` reference | A `.pptx` file path | `pptx_template_import.py` → `manifest.json` + `native_structure.json` + `source_template.pptx` + layered SVGs + `assets/`; flat verification SVGs are opt-in | `standard` / `fidelity` / `mirror` |@@ -82,18 +89,18 @@ Branch by the type of reference source the user supplied. This step produces ana| **C** Image / visual references | Screenshot folder, single image, PDF pages | `ls` + `Read` each file (multimodal visual recognition) | `standard` only || **D** No reference source | Verbal description only ("McKinsey style", "tech blue", "dark minimal") | — | `standard` only |-`fidelity` and `mirror` are not available for type C / D — visual references and verbal-only briefs cannot drive page-by-page replication. Type A is the canonical mirror path: `manifest.json`, `native_structure.json`, layered lossless `svg/`, and inheritance facts are the restoration authority. Optional `svg-flat/` files are complete-page verification views, never restoration input. In `standard` / `fidelity`, the imported facts and visuals do not define output topology.+`fidelity` and `mirror` are not available for type C / D — visual references and verbal-only briefs cannot drive page-by-page replication. Type A is the canonical mirror path: `manifest.json`, `native_structure.json`, layered lossless `svg/`, and inheritance facts describe the native structure that still exists in the PPTX package. Optional `svg-flat/` files are complete-page verification views, never structure authority. In `standard` / `fidelity`, imported facts and visuals do not define output topology.**Type B source normalization**: when the supplied root contains `templates/design_spec.md`, use `<input>/templates/` as the SVG/spec source and resolve its workspace assets from sibling `<input>/images/` and `<input>/icons/`. Otherwise, use the supplied directory itself as the legacy-flat/loose SVG source. Directory flatness is not a semantic-structure signal.Type B is supported with caveats:-- **mirror on type B** — require a complete explicit source contract. Preserve page count/order, literal visuals, root Master/Layout identities, slot metadata, supported native-object metadata, and source ownership. Page type for `<NNN>_<page_type>.svg` is read from the source filename when it follows the PPT Master naming convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); fall back to `content` otherwise. A loose visual-only SVG folder has no native structure to restore and cannot use mirror.+- **mirror on type B** — require a complete current explicit source contract. Preserve page count/order, literal visuals, root Master/Layout identities, slot metadata, supported native-object metadata, and source ownership in the **new** workspace. Page type for `<NNN>_<page_type>.svg` is read from the source filename when it follows the PPT Master naming convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); fall back to `content` otherwise. A loose visual-only SVG folder has no native structure to preserve and cannot use mirror.- **fidelity on type B** — inspect the complete page roster as visual reference, then design a broader new roster and its own Master/Layout/slot system. Existing keys, families, and repeated source chrome are not output-topology inputs.-- **legacy or unstructured type B** — old `baseline` / `preserve` / `layout_strategy: distill` / `data-pptx-layout-kind` / direct-atomic-placeholder inputs, and SVGs with no root Master identity, first run [`restore-pptx-structure`](./restore-pptx-structure.md). The restored contract is then the Type B input. Do not keep a second compatibility branch inside template creation.-- **selected free-design subset on type B** — restore the named source pages into the current structured contract, then ingest only that explicit subset. Do not scan or copy the whole `svg_output/` directory and silently turn unselected pages into template variants.+- **legacy or unstructured type B** — old `baseline` / `preserve` / `layout_strategy: distill` / `data-pptx-layout-kind` / direct-atomic-placeholder inputs, and SVGs with no root Master identity, are visual/contextual reference for `standard` / `fidelity` only. Author a new current contract in the output workspace. Use the original PPTX Type A path when existing native Master/Layout facts must be mirrored; do not mutate the SVG source or claim topology recovery from incomplete metadata.+- **selected free-design subset on type B** — ingest only the explicitly named pages as visual reference, then author a new current structured contract in the output workspace. Do not scan or copy the whole `svg_output/` directory or silently turn unselected pages into template variants.-**Replication mode boundary**: `standard` and `fidelity` are authored modes: source visuals/assets guide a new SVG roster and a newly designed Master/Layout/slot system, without preserving or distilling source topology. `mirror` is a restoration mode: source page order, visuals, Master/Layout graph, placeholders, ownership, and supported native-object metadata are authoritative. Mirror may mechanically normalize the transport representation for the current compiler, including fixed-layer group expansion, but it never performs semantic synthesis. The modes do not create a downstream generation route, and a completed mirror workspace does not force future decks to preserve the source page count or page order.+**Replication mode boundary**: `standard` and `fidelity` are authored modes: source visuals/assets guide a new SVG roster and a newly designed Master/Layout/slot system, without preserving or distilling source topology. `mirror` is a native-preservation mode: only Master/Layout/placeholder/ownership facts that exist in a PPTX package or complete current Type B contract are authoritative. Mirror may mechanically normalize transport representation for the current compiler, including fixed-layer group expansion, but it never infers missing historical intent or modifies the input. The modes create a template workspace, not a downstream generated deck; future decks are authored anew and do not inherit the source page count/order requirement.### 1A. `.pptx` reference@@ -126,7 +133,7 @@ Import fidelity rules:- Charts, SmartArt, diagrams, and OLE objects are typed placeholders in `svg/`. In `svg-flat/`, they use a preview image with a small badge when one exists; otherwise they stay visible as placeholders. Tables are converted to real SVG.- Missing media and external linked images fail the import. EMF / WMF Office vector media are converted to PNG previews when supported by the local toolchain; otherwise the import fails.-It is a reconstruction aid, not a final direct template conversion.+It is an analysis aid, not a final direct template conversion.**Lossless payload backing + editable authoring IR**:@@ -166,7 +173,7 @@ python3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authpython3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authoring-svg-flat" --icons-dir "<import_workspace>/icons" --icon-namespace imported --reuse-inventory "<import_workspace>/authoring-svg_vector_asset_inventory.json" --inplace --id-prefix flat --min-decoration-bytes 3000 --clean-stale```-The authoring SVGs in `<import_workspace>/authoring-svg/` and, when requested, `<import_workspace>/authoring-svg-flat/` are rewritten in place with compact `<use data-icon="imported/..."/>` placeholders. Extracted assets have one canonical copy under `<import_workspace>/icons/imported/`; never duplicate them under `templates/icons/`. The root `icons/` directory remains a namespace container and must not contain rewritten page SVGs or inventories. The inventory is written beside the processed IR directory and records every preserved `data-pptx-source-ref`; re-inlining an asset therefore restores the referenced object mapping before materialization. The existing icon embedding path re-inlines the extracted assets before final export, preserving multi-color artwork and non-square viewBox geometry as native SVG shapes. Text-bearing groups are never extracted; text must stay readable/editable in the working SVG. Extraction triggers on either many drawable elements or a large pure-vector XML block, so long single-path illustrations are factored out too. Pure-vector decoration runs inside text-bearing groups use a lower size threshold, allowing card borders and decorative paths to be extracted without hiding text. Referenced defs (`gradient` / `pattern` / `filter` / `clipPath` / `marker`) are copied into each asset and namespaced so the asset is self-contained after re-inline. If both layered and flat views are processed into the same icon namespace, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix inside the selected namespace; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.+The authoring SVGs in `<import_workspace>/authoring-svg/` and, when requested, `<import_workspace>/authoring-svg-flat/` are rewritten in place with compact `<use data-icon="imported/..."/>` placeholders. Extracted assets have one canonical copy under `<import_workspace>/icons/imported/`; never duplicate them under `templates/icons/`. The root `icons/` directory remains a namespace container and must not contain rewritten page SVGs or inventories. The inventory is written beside the processed IR directory and records every preserved `data-pptx-source-ref`; re-inlining an asset therefore re-establishes the referenced object mapping before materialization. The existing icon embedding path re-inlines the extracted assets before final export, preserving multi-color artwork and non-square viewBox geometry as native SVG shapes. Text-bearing groups are never extracted; text must stay readable/editable in the working SVG. Extraction triggers on either many drawable elements or a large pure-vector XML block, so long single-path illustrations are factored out too. Pure-vector decoration runs inside text-bearing groups use a lower size threshold, allowing card borders and decorative paths to be extracted without hiding text. Referenced defs (`gradient` / `pattern` / `filter` / `clipPath` / `marker`) are copied into each asset and namespaced so the asset is self-contained after re-inline. If both layered and flat views are processed into the same icon namespace, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix inside the selected namespace; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.The layered pass owns the canonical extracted-vector pool. Each new asset records a source fingerprint before generated ID namespacing. The flat pass MUST consume the layered inventory through `--reuse-inventory`: an exact fingerprint match writes only a `<use>` reference to the existing layered asset, while an unmatched flat-only subtree may create one new asset under the `flat` prefix. Do not independently extract the two views into parallel asset sets. With `--clean-stale`, a rerun also removes obsolete generated `flat_*` duplicates while retaining every reused layered reference.@@ -221,7 +228,7 @@ Use the compact facts in `manifest.json` for orientation. Use screenshots or theInterpretation rule (carries forward into Steps 2 and 4):-- `manifest.json` is the source of truth for facts about the source deck: slide size, theme colors, fonts, background inheritance, reusable asset inventory, declared source layout/master structure, and slide reuse relationships. It dictates mirror restoration facts but not `standard` / `fidelity` output topology.+- `manifest.json` is the source of truth for facts about the source deck: slide size, theme colors, fonts, background inheritance, reusable asset inventory, declared source layout/master structure, and slide reuse relationships. It dictates which source facts mirror may preserve during materialization, but not `standard` / `fidelity` output topology.- `native_structure.json` is the source of truth for source PowerPoint identity: stable layout keys, picker names, parent masters, placeholder types/indices, and the source-package hash. Mirror preserves those facts one-to-one. `standard` / `fidelity` do not mine them into the new structure.- `manifest.json`, `native_structure.json`, and `svg/inheritance.json` intentionally overlap only at contract boundaries so materialization can cross-check source identity, graph ownership, and visibility; do not collapse them into a cache or substitute one for another- exported `assets/` are the canonical reusable image pool — `<image>` references in `svg/` already point at these files directly@@ -251,7 +258,7 @@ Before composing Step 2, extract the template's reusable norms from the previous| Density rhythm | title scale, content block count, whitespace balance, dense vs. breathing pages | Page-type guidance for Strategist / Executor || Page roster semantics | cover / TOC / chapter / content / ending variants and their intended content slots | `design_spec.md §V Page Roster` rows || Asset policy | source images / icons / textures that are part of the template vs. sample-only content | `design_spec.md §VI Assets` or omit sample-only assets |-| Native PowerPoint structure | `native_structure.json` plus inheritance facts | Mirror restores the source graph one-to-one. Standard/fidelity author an independent output graph and do not distill source common structure. |+| Native PowerPoint structure | `native_structure.json` plus inheritance facts | Mirror maps the validated source graph one-to-one into a new workspace. Standard/fidelity author an independent output graph and do not distill source common structure. |Distinguish observed facts from template rules: "`slide_07` uses a left photo crop" is a fact; "content pages may use a left photo rail for location / product / case-study pages" is the reusable rule.@@ -262,7 +269,7 @@ Distinguish observed facts from template rules: "`slide_07` uses a left photo crDo not treat authoring IR documents as final template assets. `standard` / `fidelity` author new SVGs from the confirmed brief and IR references. Mirror edits the IR and materializes it with lossless native-payload backing.-> **Mirror-mode restoration path** — use `native_structure.json`, `svg/inheritance.json`, and the authoring manifest as structural/provenance authority. The cleaned layered IR is the editable source and lossless layered SVGs are immutable payload backing; optional flat SVGs are verification-only. Preserve roster, appearance, ownership, placeholders, converter-supported native metadata, and available SVG fallbacks; do not synthesize a different graph.+> **Mirror-mode materialization path** — use `native_structure.json`, `svg/inheritance.json`, and the authoring manifest as structural/provenance authority. The cleaned layered IR is the editable source and lossless layered SVGs are immutable payload backing; optional flat SVGs are verification-only. Preserve only the roster, appearance, ownership, placeholders, converter-supported native metadata, and available SVG fallbacks that are actually present and validated; do not synthesize missing facts or a different graph.### 1B. Existing SVG assets@@ -325,13 +332,13 @@ Compose a single message that surfaces every Required brief item to the user, **|---|---|| Output scope | Recommended `library` (default) plus `project`; explain that both use the same portable workspace routing and only the parent path / global registration differ || Target project | Required only for `project`; show the exact initialized project workspace path, not a project nickname |-| Template kind | Recommended localized label with English ID, plus both options and the rule for choosing |-| Category | Recommended localized category with English ID, plus `brand` / `general` / `scenario` / `government` / `special` with localized explanations |-| Theme mode | Recommended localized mode with English ID, plus available modes such as `light` / `dark` / `mixed` with localized explanations |-| Canvas format | Recommended canvas, plus other supported formats from [`canvas-formats.md`](../references/canvas-formats.md) that fit the source aspect ratio or user intent. Always show the concrete pixel size and `viewBox`; do not treat two same-ratio formats such as `ppt169` (`1280x720`) and `banner` (`1920x1080`) as interchangeable. |-| Replication mode | Recommended localized mode with English ID, plus all modes available for the current input type; state that `standard` / `fidelity` design a new structure while `mirror` restores the source structure; list unavailable modes with reasons |-| Native structure policy | For `standard` / `fidelity`, state that the designer will author a new Master/Layout/slot system without preserving or distilling source topology. Show the planned Master roster; if it contains more than one Master, explain the distinct reusable family owned by each and which Layouts belong to it. Reject one-Master-per-Layout organization and visually/semantically equivalent duplicate Masters. For `mirror`, summarize the exact source Master/Layout/placeholder graph that will be restored one-to-one. |-| Visual fidelity for fixed pages | Recommended localized choice with English ID, plus both `literal` / `adapted` options when applicable |+| Selected child workflow | Echo the already-dispatched Create Brand, Create Layout, or Create Deck workflow; do not reopen kind selection inside the brief |+| Category | Create Layout/Create Deck only. Show the recommended localized value and alternatives; `brand` is valid for Create Deck but not Create Layout. |+| Theme mode | Create Layout/Create Deck only; recommended localized mode with English ID, plus available modes such as `light` / `dark` / `mixed`. Create Brand records identity colors instead and does not own a page theme mode. |+| Canvas format | Create Layout/Create Deck only; recommended canvas plus other supported formats from [`canvas-formats.md`](../references/canvas-formats.md) that fit the source aspect ratio or user intent. Always show the concrete pixel size and `viewBox`; do not treat two same-ratio formats such as `ppt169` (`1280x720`) and `banner` (`1920x1080`) as interchangeable. |+| Replication mode | Create Layout/Create Deck only; recommended localized mode with English ID, plus all modes available for the current input type. State that `standard` / `fidelity` design a new structure while `mirror` materializes validated source-package facts into a new workspace; list unavailable modes with reasons. Create Brand has no replication mode. |+| Native structure policy | Create Layout/Create Deck only. For `standard` / `fidelity`, state that the designer will author a new Master/Layout/slot system without preserving or distilling source topology. Show the planned Master roster; if it contains more than one Master, explain the distinct reusable family owned by each and which Layouts belong to it. Reject one-Master-per-Layout organization and visually/semantically equivalent duplicate Masters. For `mirror`, summarize the exact source Master/Layout/placeholder facts that are present, supported, and will be mapped one-to-one into the new workspace. |+| Visual fidelity for fixed pages | Create Layout/Create Deck only; recommended localized choice with English ID, plus both `literal` / `adapted` options when applicable || Asset bundling | Recommended included assets, plus excluded candidate assets with a one-line reason when reference assets exist |Items to surface:@@ -340,34 +347,34 @@ Items to surface:|------|----------|--------------------------|| Output scope | Yes | `[decision]` — `library` (default, globally reusable and indexed) or `project` (same portable workspace routing under one initialized project) || Target project | Yes for `project`; N/A for `library` | `[decision]` — explicit path to the initialized target workspace; validate it during the Step 4 preflight |-| New template ID | Yes | `[decision]` — user chooses ASCII slug; if Chinese brand name, it must be filesystem-safe. In library scope it also becomes the matching index key |+| New template ID | Yes | `[decision]` — user chooses a filesystem-safe ASCII slug. In library scope it also becomes the matching index key || Template display name | Yes | `[decision]` (often the source deck title — `[suggested]` from `manifest.json.source.name` for type A) |-| Category | Yes | `[decision]` — one of `brand` / `general` / `scenario` / `government` / `special` |+| Category | Create Layout/Create Deck only | `[decision]` — Create Deck: `brand` / `general` / `scenario` / `government` / `special`; Create Layout: `general` / `scenario` / `government` / `special` || Applicable scenarios | Yes | `[suggested]` from analysis; user confirms |-| Tone summary | Yes | `[suggested]` from analysis (e.g. `Modern, restrained, data-driven`) |-| Theme mode | Yes | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[decision]` |-| Canvas format and dimensions | Yes | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`) |-| Replication mode | Yes | `[decision]` — `standard` always available; `fidelity` is available for A/B; `mirror` is available for A and for B sources with a complete explicit structure contract. `standard` / `fidelity` author new SVG semantics. Mirror retains one restored prototype per source slide in source order and adds definition-only prototypes for source Layouts unused by those slides. Reject `fidelity` / `mirror` for C/D. |-| Native structure facts | Type A and structured Type B | `[fact]` from `native_structure.json` / source SVG contract: master/layout counts, parentage, page assignments, placeholder identities, and multi-master status. Mirror restores these facts; authored modes do not use them as output topology. |-| Mode-specific ownership | Yes | `standard` / `fidelity`: `[decision]` newly authored Master/Layout ownership, including the reusable-family reason for every additional Master. `mirror`: `[fact]` source ownership restored without synthesis. Every Master must own at least one emitted Layout and every Layout must have at least one emitted prototype; export never infers either contract. |-| Visual fidelity for fixed pages | Yes for `standard` / `fidelity` when reference exists; **N/A for `mirror`** (mirror restores the source visual) | `[decision]` — `literal` (closely reproduce reference geometry / decoration / sprite crops within a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Different page types may take different settings. |-| Basic template norms | Yes when reference exists | `[fact]` / `[suggested]` — layout grammar, image system, density rhythm, page roster semantics, and asset policy extracted in Step 1 |+| Identity tone or structural summary | Yes | Create Brand/Create Deck: identity tone. Create Layout: structural use case and density/rhythm summary only. |+| Theme mode | Create Layout/Create Deck only | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[decision]` |+| Canvas format and dimensions | Create Layout/Create Deck only | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`) |+| Replication mode | Create Layout/Create Deck only | `[decision]` — `standard` always available; `fidelity` is available for A/B; `mirror` is available for A and for B sources with a complete explicit structure contract. `standard` / `fidelity` author new SVG semantics. Mirror retains one materialized prototype per source slide in source order and adds definition-only prototypes for source Layouts unused by those slides. Reject `fidelity` / `mirror` for C/D. |+| Native structure facts | Create Layout/Create Deck with Type A or structured Type B | `[fact]` from `native_structure.json` / source SVG contract: master/layout counts, parentage, page assignments, placeholder identities, and multi-master status. Mirror preserves these validated facts in the new workspace; authored modes do not use them as output topology. |+| Mode-specific ownership | Create Layout/Create Deck only | `standard` / `fidelity`: `[decision]` newly authored Master/Layout ownership, including the reusable-family reason for every additional Master. `mirror`: `[fact]` source ownership mapped without synthesis. Every Master must own at least one emitted Layout and every Layout must have at least one emitted prototype; export never infers either contract. |+| Visual fidelity for fixed pages | Create Layout/Create Deck `standard` / `fidelity` when reference exists; **N/A for `mirror` and Create Brand** | `[decision]` — `literal` (closely reproduce reference geometry / decoration / sprite crops within a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Different page types may take different settings. |+| Basic template norms | Yes when reference exists | Create Brand uses the identity fields and provenance rules from its child workflow. Create Layout/Create Deck use `[fact]` / `[suggested]` layout grammar, image system, density rhythm, page roster semantics, and asset policy from Step 1. || Reference source | Optional | already known if Step 1 ran |-| Theme color | Optional | A: `[fact]` from theme XML. B: `[fact]` from dominant SVG `fill`. C: `[suggested]` from visual estimate (HEX is approximate). D: `[decision]` |-| Fonts | Optional | A: `[fact]` from `manifest.json`. B: `[fact]` from SVG `font-family`. C / D: not derivable — `[decision]` if user wants a custom stack |+| Theme color | Create Brand/Create Deck only | A: `[fact]` from theme XML. B: `[fact]` from dominant SVG `fill`. C: `[suggested]` from visual estimate (HEX is approximate). D: `[decision]`. Create Layout may use neutral preview paint but stores no identity color. |+| Fonts | Create Brand/Create Deck only | A: `[fact]` from `manifest.json`. B: `[fact]` from SVG `font-family`. C / D: not derivable — `[decision]` if the child owns a custom stack. Create Layout stores no typography system. || Design style | Optional | `[suggested]` from analysis || Assets list | Optional | A: `[fact]` from `assets/` listing; user picks which to bundle. B / C: `[decision]` per file. D: none || Keywords | Yes | `[suggested]` from analysis (3–5 short tags); user confirms |-For type A, also include in this message:+For type A Create Layout/Create Deck execution, also include in this message:- the exact authoring-manifest documents required by the selected mode and verified during Step 1- a one-line summary of the source Master/Layout structure-- the source structure facts, including master/layout counts, multi-master status, and reason codes; state whether they will be restored (`mirror`) or ignored as output topology (`standard` / `fidelity`)+- the source structure facts, including master/layout counts, multi-master status, and reason codes; state whether they will be preserved in a new workspace (`mirror`) or ignored as output topology (`standard` / `fidelity`)The user replies with corrections, additions, or "all good".-> **Persist the portable brief into `design_spec.md`**. When the Template_Designer writes `design_spec.md` in Step 4, declare a YAML frontmatter block at the top with the kind-specific ID key (`deck_id` or `layout_id`) plus the confirmed portable fields (`kind`, `category`, `summary`, `keywords`, `primary_color` for deck, `page_types` for layout, `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, `source_viewbox`, `replication_mode`, `native_structure_mode`, etc.). Do not persist a generic `template_id` field: it is the workflow's cross-kind name, not a registrar schema key. Do not persist the execution-only `output_scope` or `target_project` fields. In library scope, `register_template.py` reads this frontmatter in Step 7 so the brief flows directly into the index without the AI re-deriving it from prose.+> **Persist the portable brief into `design_spec.md`**. In Step 4, declare a YAML frontmatter block with the child-specific ID key (`brand_id`, `deck_id`, or `layout_id`) and only fields owned by that child. Create Brand follows its identity schema. Create Layout/Create Deck persist the confirmed portable fields (`kind`, `category`, `summary`, `keywords`, `primary_color` for deck, `page_types` for layout, `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, `source_viewbox`, `replication_mode`, `native_structure_mode`, etc.). Do not persist a generic `template_id` field: it is the parent workflow's cross-kind name, not a registrar schema key. Do not persist the execution-only `output_scope` or `target_project` fields. In library scope, `register_template.py` reads this frontmatter in Step 7 so the brief flows directly into the index without the AI re-deriving it from prose.---@@ -378,7 +385,7 @@ The user replies with corrections, additions, or "all good".1. Echo back the finalized brief (post-corrections) in a single message2. Emit the marker `[TEMPLATE_BRIEF_CONFIRMED]` on its own line-Skipping this gate — including silently inferring values from the reference source, opened IDE file, or prior conversation — is a workflow violation. Even if the user said "use this .pptx as a template" upfront, you MUST still surface Step 2 with provenance labels and obtain explicit confirmation here. The reference source informs the brief; it does not substitute for it.+Skipping this gate — including silently inferring values from the reference source, opened IDE file, or prior conversation — is a route violation. Even if the user said "use this .pptx as a template" upfront, you MUST still surface Step 2 with provenance labels and obtain explicit confirmation here. The reference source informs the brief; it does not substitute for it.**Required outcome of Step 3** (all must be true before emitting `[TEMPLATE_BRIEF_CONFIRMED]`):@@ -387,11 +394,12 @@ Skipping this gate — including silently inferring values from the reference so- [ ] User-facing labels and option explanations match the user's language; English enum IDs appear only as precision aids- [ ] User has replied with values or explicit acceptance of suggested defaults- [ ] Output scope is confirmed; both scopes use the same workspace shape, while `project` includes an explicit initialized target-project path-- [ ] The canvas format is fixed before SVG generation-- [ ] Replication mode is consistent with the input type (`fidelity` allowed for A/B; `mirror` allowed for A and structured B only; both forbidden for C/D)-- [ ] Before offering `mirror`, the source graph and supported geometry are complete; every source Layout absent from the source-slide roster is planned as a definition-only prototype, and any genuinely missing/unsupported facts were reported-- [ ] Basic template norms from prior content have been surfaced and accepted, or explicitly marked N/A when no reference exists-- [ ] Mode-specific ownership policy is explicit: `standard` / `fidelity` author a new structure without source-topology distillation; `mirror` restores source ownership one-to-one+- [ ] For Create Layout/Create Deck, the canvas format is fixed before SVG generation+- [ ] For Create Layout/Create Deck, replication mode is consistent with the input type (`fidelity` allowed for A/B; `mirror` allowed for A and structured B only; both forbidden for C/D)+- [ ] For Create Layout/Create Deck mirror, the source graph and supported geometry are complete; every source Layout absent from the source-slide roster is planned as a definition-only prototype, and any genuinely missing/unsupported facts were reported+- [ ] Child-specific norms from prior content have been surfaced and accepted, or explicitly marked N/A when no reference exists: identity/provenance for Create Brand; layout/image/density/asset behavior for Create Layout/Create Deck+- [ ] For Create Layout/Create Deck, mode-specific ownership is explicit: `standard` / `fidelity` author a new structure without source-topology distillation; `mirror` maps validated source ownership one-to-one into a new workspace+- [ ] For Create Brand, all required identity fields from its child workflow are confirmed and canvas/replication/native-structure fields remain N/A- [ ] For `library`, metadata is complete enough to register into the relevant index; for `project`, the same portable template metadata is complete and no global registration is planned- [ ] Marker `[TEMPLATE_BRIEF_CONFIRMED]` emitted on its own line after the echoed brief@@ -399,7 +407,7 @@ Step 4 MUST NOT run until `[TEMPLATE_BRIEF_CONFIRMED]` has been emitted in the c----## Step 4: Preflight Output + Invoke Template_Designer+## Step 4: Preflight Output + Invoke the Selected Child> **Precondition**: `[TEMPLATE_BRIEF_CONFIRMED]` was emitted in Step 3. If not, return to Step 3.@@ -421,9 +429,11 @@ mkdir -p "$template_workspace/templates"| `library` | `skills/ppt-master/templates/<kind_dir>/<template_id>/` | Run the common workspace preflight; the directory name matches the final template ID used in the relevant index || `project` | `<target_project>/` | Run the same workspace preflight against the initialized project root |-The preflight is atomic at workflow level: discover and settle every output filename first, check all destinations together, then begin generation. Do not partially write a workspace and discover a later collision.+The preflight is atomic at the Create Template parent level: discover and settle every output filename first, check all destinations together, then begin generation. Do not partially write a workspace and discover a later collision.++**Create Brand branch**: continue in [`create-brand.md`](./create-template/create-brand.md) §3 with the confirmed identity brief and resolved `<template_workspace>`. Then return to the Create Brand branch in Step 5. Do not invoke Template_Designer, create SVGs, or apply the Create Layout/Create Deck-only material below.-**Switch to the Template_Designer role** and generate per role definition. The role input is the finalized brief from Step 3 plus the analysis bundle from Step 1, including the accepted basic template norms.+**Create Layout/Create Deck branch**: continue in the selected child workflow, switch to the Template_Designer role, and generate per role definition. The role input is the finalized brief from Step 3 plus the analysis bundle from Step 1, including the accepted basic template norms.If the input source is type A, pass the following internal package to the role:@@ -474,13 +484,13 @@ expresses one complete object, they use the compact canonicalpaint comes from the confirmed brief and template `design_spec.md`. Afterinserting the complete helper group, add only the registered structuralattributes required by its Master/Layout or object-slot role; geometry and-paint changes require a new helper render. `mirror` restores the expanded-lossless source contract and may only normalize transport details required by+paint changes require a new helper render. `mirror` preserves the expanded+lossless source contract in a new workspace and may only normalize transport details required bythe current compiler. Mirror never performs commonalityextraction, semantic synthesis, merge/split, promotion/demotion, renaming, orre-parenting.-**Hard rule — multi-Master package boundary**: More than one Master is valid only when `mirror` restores the source graph or an authored template intentionally defines distinct reusable design families. `standard` / `fidelity` must not create one Master per Layout or duplicate equivalent Masters merely for organization. Every declared Master must own at least one emitted Layout, and every declared Layout must be selected by at least one prototype SVG so the complete graph can be compiled and verified.+**Hard rule — multi-Master package boundary**: More than one Master is valid only when `mirror` preserves an existing source graph in the new workspace or an authored template intentionally defines distinct reusable design families. `standard` / `fidelity` must not create one Master per Layout or duplicate equivalent Masters merely for organization. Every declared Master must own at least one emitted Layout, and every declared Layout must be selected by at least one prototype SVG so the complete graph can be compiled and verified.| Package concern | Requirement ||---|---|@@ -493,7 +503,7 @@ SVG authors own the semantic roster, parentage, picker names, direct atoms, andDo not package `native_structure.json` or `source_template.pptx` as template inputs. In `standard` / `fidelity`, author Master/Layout direct semantic atoms and bounded slot groups deliberately from the intended reusable behavior. A validated compact canonical authored-preset `<g>` compiles to one native shape and therefore counts as one semantic atom; it may own a Master/Layout fixed layer or serve as the one direct carrier of an `object` slot. Ordinary groups are not structural atoms or single-object carriers. In `mirror`, edit the layered authoring IR and use inheritance/native facts to preserve source ownership; the lossless trees remain payload backing. Recursively expand fixed Master/Layout group wrappers only because the structured contract requires semantic atoms; preserve transforms, styles, paint order, and appearance, and never flatten or regroup by semantic judgment.-`design_spec.md §V` records the newly authored roster for `standard` / `fidelity`. For `mirror`, add the `Source Restoration Map` required by [template-designer.md](../references/template-designer.md), with one row per source slide and its preserved Master/Layout assignment. Do not add a synthesis-decision table.+`design_spec.md §V` records the newly authored roster for `standard` / `fidelity`. For `mirror`, add the `Source Preservation Map` required by [template-designer.md](../references/template-designer.md), with one row per source slide and its preserved Master/Layout assignment. Do not add a synthesis-decision table.**Native-shape metadata boundary**: The authoring IR removes opaque payloadfrom model context while retaining stable source refs. `standard` / `fidelity`@@ -509,13 +519,13 @@ usage guidance in the native-shape reference.Downstream, both template-adherence choices use `pptx_structure.mode: structured`. `page_layouts` selects one complete authoring prototype per page, `pptx_masters` / `pptx_layouts` declare unique reusable definitions, and `page_pptx_layouts` assigns generated pages. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create and assign a new Layout key/name while authoring the page that needs it. A retained Layout may remain unassigned while still registering through its definition SVG. A mirror-created package does not force a future generated deck to keep the source page count or order.-**Apply the visual-fidelity decision from Step 3 to authored modes**: in `standard` / `fidelity`, pages marked `literal` reproduce the selected reference geometry and decoration while still using a newly designed structure; pages marked `adapted` may evolve the composition. Mirror restores every supported source visual and does not use this authored-page distinction.+**Apply the visual-fidelity decision from Step 3 to authored modes**: in `standard` / `fidelity`, pages marked `literal` reproduce the selected reference geometry and decoration while still using a newly designed structure; pages marked `adapted` may evolve the composition. Mirror preserves every supported source visual represented by the validated IR and does not use this authored-page distinction.**Sprite-sheet preservation (do NOT simplify away)**: PPTX-exported assets are often sprite sheets — a single tall/large image referenced from multiple slides, each cropping a different region via nested `<svg ... viewBox="...">` wrappers around `<image width="1" height="1">`. This nesting is **load-bearing geometry**, not redundant structure. When rebuilding, preserve the exact `viewBox` crop and the outer `<svg>` placement for every image; do not flatten to a single `<image>` with direct `x/y/width/height`. Verify by sampling: if any asset's pixel dimensions don't match the on-page display aspect, it is a sprite and the wrapper must stay.-**Mirror-mode restoration contract** (type A or B): when `Replication mode: mirror`, the Template_Designer role:+**Mirror-mode materialization contract** (type A or B): when `Replication mode: mirror`, the Template_Designer role:-1. **Restores one output SVG per source page** in `<template_workspace>/templates/`. Edit and normalize the matching `authoring-svg/` IR document, then materialize it with the authoring manifest, native structure facts, and immutable payload backing. Type A must use `mirror_template_materialize.py`; do not hand-copy or independently rebuild its graph. Preserve source Master/Layout keys and picker names, Layout parentage, slide assignment, placeholder type/index/bounds, inherited-shape visibility, ownership, paint order, and supported native metadata. Mechanical namespace, root-declaration, asset-path, and fixed-layer group normalization is allowed only when source ownership and appearance remain unchanged.+1. **Materializes one output SVG per source page** in `<template_workspace>/templates/`. Edit and normalize the matching `authoring-svg/` IR document, then materialize it with the authoring manifest, native structure facts, and immutable payload backing. Type A must use `mirror_template_materialize.py`; do not hand-copy or independently rebuild its graph. Preserve the source Master/Layout keys and picker names, Layout parentage, slide assignment, placeholder type/index/bounds, inherited-shape visibility, ownership, paint order, and supported native metadata that are present and validated. Mechanical namespace, root-declaration, asset-path, and fixed-layer group normalization is allowed only when source ownership and appearance remain unchanged.- Type A authoring source: `<import_workspace>/authoring-svg/` plus its `authoring_manifest.json`; `<import_workspace>/svg/`, `svg/inheritance.json`, and `native_structure.json` provide payload and structural backing. Optional `<import_workspace>/svg-flat/` is verification-only.- Type B authoring source: `<svg_analysis_workspace>/authoring-svg/` plus its manifest; the complete explicit source SVG contract is immutable backing- For every source Layout unused by all source slides, additionally materialize one definition-only SVG named `layout_<layout_key>.svg` from its layered authoring IR document and payload backing. It carries the exact root identity, fixed atoms, and placeholder contract but is not a generated page assignment. Use source placeholder prompts/carriers; do not invent business content. This definition SVG lets downstream export register the Layout and any otherwise-unused parent Master without retaining an internal carrier slide.@@ -536,7 +546,7 @@ Mirror mode does not simplify the visual target or synthesize layer ownership. T1. `design_spec.md` — **personality only**. A deck writes Template Overview, Color Scheme, Signature Design Elements, and Page Roster; Typography / Assets / Placeholder Overrides are conditional. A layout writes only structure-owned Signature Design Elements and Page Roster; its frontmatter `summary` carries concise selection context, and it omits the deck-only Template Overview plus every identity section. The Page Roster must match the actual SVG files on disk. Declare portable brief frontmatter; `register_template.py` consumes it only in library scope. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` / `fidelity` / `mirror` mode rosters, variant naming, and TOC handling3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.- - `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native reconstruction contract: root Master/Layout key/name, direct atomic Master/Layout elements, and direct slot `<g>` elements with explicit design-zone bounds plus exactly one compatible carrier. A validated compact canonical authored-preset `<g>` counts as one semantic atom or one `object` carrier; ordinary groups do not. Composite regions use only the explicit `object` + `proxy` downgrade. Minimal structural `data-pptx-role` hints are added only when specialized metadata cannot express required behavior. Both strict and adaptive downstream set `mode: structured` and require complete `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts` from planning onward.+ - `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native structure contract: root Master/Layout key/name, direct atomic Master/Layout elements, and direct slot `<g>` elements with explicit design-zone bounds plus exactly one compatible carrier. A validated compact canonical authored-preset `<g>` counts as one semantic atom or one `object` carrier; ordinary groups do not. Composite regions use only the explicit `object` + `proxy` downgrade. Minimal structural `data-pptx-role` hints are added only when specialized metadata cannot express required behavior. Both strict and adaptive downstream set `mode: structured` and require complete `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts` from planning onward.4. Template assets (optional) — both scopes apply the same `templates/` / `images/` / root `icons/imported/` routing defined above**Hard rule — placeholder examples are executable defaults**: In authored@@ -556,7 +566,15 @@ becomes the prototype Slide placeholder, while## Step 5: Validate Template Assets-Set `<template_source>` to `<template_workspace>/templates/` in both scopes.+**Create Brand branch**: run the child workflow's §4 checklist. In `library` scope, also run the registrar dry-run below; in `project` scope, perform the same file/schema/asset checks without touching a global index. Any failure blocks completion.++```bash+python3 skills/ppt-master/scripts/register_template.py <brand_id> --kind brand --dry-run+```++After Create Brand validation passes, skip the Create Layout/Create Deck-only remainder of this step and all of Step 6; continue at Step 7.++**Create Layout/Create Deck branch**: set `<template_source>` to `<template_workspace>/templates/` in both scopes.```bashls -la "<template_workspace>/templates"@@ -578,7 +596,7 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/t- require every SVG root to declare one output Master and Layout; zero-slot Layouts are valid- reject ordinary Master/Layout `<g>` elements, nested structure markers, missing slot bounds, and carrier-bound slots without exactly one compatible carrier; a validated compact canonical authored-preset `<g>` is the sole fixed-layer group exception and may be one `object` carrier- validate cross-page Master equality plus same-key Layout atom/slot equality-- warn when distinct Layout keys have identical static framing/slot contracts. Resolve this for `standard` / `fidelity`; mirror may retain the distinct source identities and records that fact in its Source Restoration Map+- warn when distinct Layout keys have identical static framing/slot contracts. Resolve this for `standard` / `fidelity`; mirror may retain the distinct source identities and records that fact in its Source Preservation MapThis checker validates the authoring contract, not the compiled OOXML package. Theme ownership, package IDs, and registered part relationships are verified by `template_preview_pptx.py` in Step 6.@@ -598,14 +616,14 @@ This checker validates the authoring contract, not the compiled OOXML package. T- [ ] For `standard` / `fidelity`, every placeholder bound is the complete editable box rather than the current marker text's tight bounds; general body/object carriers begin at the upper-left and only intentional short focal roles remain centered- [ ] `standard` / `fidelity` output SVGs and their Master/Layout/slot contracts were newly authored without preserving or distilling source topology- [ ] Every additional authored Master represents a distinct reusable design family, not one Layout or an equivalent duplicate; every declared Master owns at least one emitted Layout and every declared Layout has at least one emitted prototype-- [ ] Mirror output preserves source slide order, Master/Layout identity and parentage, placeholder facts, and ownership; fixed-layer group expansion is mechanical and pixel-equivalent, and the Source Restoration Map lists every source slide+- [ ] Mirror output preserves source slide order, Master/Layout identity and parentage, placeholder facts, and ownership; fixed-layer group expansion is mechanical and pixel-equivalent, and the Source Preservation Map lists every source slide- [ ] Mirror roots preserve source inherited-shape visibility with canonical lowercase `data-pptx-show-master-shapes` and `data-pptx-show-inherited-shapes`; same-key Layouts agree on the former, while each Slide retains its own latter value- [ ] Mirror preflight covered the complete source graph; each unused Layout has one `layout_<layout_key>.svg` definition prototype and each otherwise-unused Master is retained through at least one such Layout-- [ ] For `standard` / `fidelity`, no duplicate-Layout-contract warning remains; mirror may keep equivalent source Layout identities when the restoration map explains them+- [ ] For `standard` / `fidelity`, no duplicate-Layout-contract warning remains; mirror may keep equivalent source Layout identities when the preservation map explains them- [ ] All template-creation edits used the authoring IR; Type A mirror used `mirror_template_materialize.py`, validated its manifest/hash/graph/source-ref closure before atomic publication, reused only converter-supported payload for hash-matching Slide-local/slot refs, stripped IR-only source-ref metadata, and kept fixed Master/Layout visuals as direct atoms- [ ] If any SVG references an extracted vector, it uses `data-icon="imported/<name>"` and the sole SVG asset exists at `<template_workspace>/icons/imported/<name>.svg`; `templates/icons/` does not exist and no separate illustration embedding script was added- [ ] For `fidelity` mode: every sprite-sheet asset retains its nested `<svg viewBox=...>` crop wrapper; no image whose file aspect differs from its on-page aspect was flattened to a bare `<image>`-- [ ] For `mirror` mode: source-page SVG count equals source page count, while additional files are exactly the required `layout_<layout_key>.svg` definitions for unused source Layouts; source-page filenames follow the `<NNN>_<page_type>.svg` convention; **no new `{{...}}` authoring placeholders were inserted into restored source-page SVGs**; §V Page Roster lists every emitted file and marks definition-only prototypes explicitly+- [ ] For `mirror` mode: source-page SVG count equals source page count, while additional files are exactly the required `layout_<layout_key>.svg` definitions for unused source Layouts; source-page filenames follow the `<NNN>_<page_type>.svg` convention; **no new `{{...}}` authoring placeholders were inserted into materialized source-page SVGs**; §V Page Roster lists every emitted file and marks definition-only prototypes explicitlyThis step is a **hard gate**. Do not generate a review PPTX, register, or hand the workspace to the main pipeline until validation passes. A one-Master template may skip Step 6 when no review was requested; a multi-Master template must continue to Step 6 and may not register or complete before that package gate passes.@@ -613,7 +631,7 @@ This step is a **hard gate**. Do not generate a review PPTX, register, or hand t## Step 6: Template Review PPTX and Multi-Master Package Gate-**Trigger**: Run when the user requests a PowerPoint review file **or** when the validated SVG roster declares more than one unique Master key. A multi-Master template requires this step even when no review artifact was requested. A one-Master template may skip directly to Step 7 when the user did not request a review file.+**Trigger — Create Layout/Create Deck only**: Run when the user requests a PowerPoint review file **or** when the validated SVG roster declares more than one unique Master key. A multi-Master template requires this step even when no review artifact was requested. A one-Master template may skip directly to Step 7 when the user did not request a review file. Create Brand always skips this step because it owns no SVG roster or native structure.Export the complete SVG roster, one prototype per slide, from the workspace root:@@ -658,6 +676,9 @@ Branch on the confirmed output scope:Run the unified registrar with the kind flag; it derives the corresponding index entry from `templates/design_spec.md` (frontmatter when present, prose fallback otherwise) plus the actual `templates/*.svg` file list. The registrar retains read compatibility with old flat library packages; new creation never writes that shape:```bash+# For brand+python3 skills/ppt-master/scripts/register_template.py <template_id> --kind brand+# For deck (default)python3 skills/ppt-master/scripts/register_template.py <template_id> --kind deck@@ -742,14 +763,14 @@ Produce one scope-aware, evidence-driven completion card for either location:## Template Creation Complete**Template Name**: <template_id> (<display_name>)-**Kind**: deck | layout+**Kind**: brand | layout | deck**Output Scope**: library | project**Workspace Path**: `<template_workspace>/`**Template Source**: `<template_workspace>/templates/`**Bitmap Path**: `<template_workspace>/images/` ← omit when absent**Imported Vector Path**: `<template_workspace>/icons/imported/` ← omit when absent-**Review PPTX**: `<template_workspace>/exports/<template_id>_template_preview.pptx` ← omit only when a one-Master template was not requested for review-**Primary Color**: <hex> ← deck only; omit for layout+**Review PPTX**: `<template_workspace>/exports/<template_id>_template_preview.pptx` ← Create Layout/Create Deck only; omit for Create Brand and when an optional one-Master review was not requested+**Primary Color**: <hex> ← Create Brand/Create Deck only; omit for Create Layout**Index Registration**: Done | Not registered (project workspace)### Files Included@@ -764,7 +785,9 @@ Produce one scope-aware, evidence-driven completion card for either location:| `exports/<template_id>_template_preview.pptx` | Verified, when requested or required for multi-Master |```-The next main-pipeline Step 3 input is the exact `<template_workspace>/` root in either scope. Step 3 resolves its `templates/design_spec.md`, ignores `exports/`, and copies or consumes `templates/` plus any existing `images/` and `icons/` as one unit. A legacy flat package root remains readable, but directory flatness alone is not a legacy Master/Layout condition and does not trigger `restore-pptx-structure`.+For Create Brand, replace the SVG/review rows with `templates/design_spec.md` plus only the real `images/*` / `icons/*` assets. Its completion card must explicitly state `SVG roster: N/A` and `Native structure: N/A`.++The next Generate PPTX Step 3 input is the exact `<template_workspace>/` root in either scope. Step 3 resolves its `templates/design_spec.md`, ignores `exports/`, and copies or consumes `templates/` plus any existing `images/` and `icons/` as one unit. It then authors new `svg_output/` pages under the template contract and exports a new PPTX. Neither the reference PPTX/SVG nor the template prototypes are upgraded in place. A legacy-flat package root remains readable only when its semantic SVG contract is current; otherwise create a new workspace through this route.---@@ -782,7 +805,7 @@ The next main-pipeline Step 3 input is the exact `<template_workspace>/` root in## Notes1. **SVG technical constraints**: See [shared-standards.md](../references/shared-standards.md) — do not restate them in the template's `design_spec.md`-2. **Color consistency**: All SVG files must use the same color scheme as `design_spec.md §II Color Scheme`+2. **Color consistency**: Create Deck SVG files must use the same color scheme as `design_spec.md §II Color Scheme`; Create Layout owns no identity colors, and Create Brand owns no SVG files3. **Placeholder convention**: `{{}}` format only; default names listed in [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). Override per template via `placeholders:` frontmatter when needed.4. **Discovery requirement**: A library template is discoverable only after `register_template.py` has been run against it (Step 7). A project-scoped workspace intentionally stays out of global discovery and is consumed by its explicit workspace-root path.5. **Review output**: Generate `exports/<template_id>_template_preview.pptx` on request and always for a multi-Master template. It is derived local evidence, never a source input during template application, and library exports stay Git-ignored.diff --git a/skills/ppt-master/workflows/create-template/create-brand.md b/skills/ppt-master/workflows/create-template/create-brand.mdnew file mode 100644index 00000000..5122dfb7--- /dev/null+++ b/skills/ppt-master/workflows/create-template/create-brand.md@@ -0,0 +1,153 @@+---+description: Create Brand workflow for an identity-only reusable workspace without an SVG page roster.+---++# Create Brand Workflow++Enter this child workflow only after [`Create Template`](../create-template.md) dispatches `kind: brand`.++## Responsibility Boundary++| Owner | Responsibilities |+|---|---|+| Create Template | Child-workflow dispatch plus the shared `library` / `project` scope, confirmation gate, collision preflight, registration, completion, and Generate PPTX handoff contract |+| Create Brand | End-to-end brand-specific analysis, identity brief, identity-only `design_spec.md`, adopted brand assets, and brand-specific validation |++**Hard rule — child workflow, not a top-level route**: Create Brand executes only inside Create Template. It uses the parent workflow's single shared confirmation/preflight/registration contract and never creates a competing entry route or second confirmation gate.++**Hard rule — identity only**: A brand owns color, typography, logo, voice, and icon style. It owns no canvas, spacing system, page roster, SVG prototype, Master/Layout graph, placeholder contract, or preview PPTX.++## Invocation Points++1. Use §1–2 below for brand analysis and identity fields, then execute Create Template Steps 2–3 with those child-owned fields.+2. After Create Template Step 4 resolves and preflights `<template_workspace>`, use §3 to materialize the confirmed identity.+3. Run §4, then return its evidence to Create Template Steps 5, 7, and 8. Create Brand always skips shared Step 6.++## 1. Brand Input Analysis++| Input | Read path | Facts it may support |+|---|---|---|+| SVG logo | Read the SVG and inspect literal `fill` / `stroke` values | Logo asset and literal colors |+| PNG/JPG logo | Inspect visually | Logo asset and approximate colors |+| Official brand site or manual | Convert/read the source | Published colors, fonts, voice, usage restrictions |+| Branded PPTX/PDF | Use the existing source converters and theme/package facts | Observed colors, typography, logo assets, and tone |+| Verbal brief | Use the user's words directly | Any identity field the user explicitly supplies |+| No reference | No analysis | Empty skeleton only when the user explicitly requests it |++Use these provenance labels in the proposal and final Color Scheme table:++- `fact` — literal value from an official asset or manual.+- `user` — value explicitly supplied by the user.+- `approx` — visual estimate or pattern observed in an existing deck/site.++**Hard rule — no inferred brand truth**: Do not promote a visual estimate, presentation convention, or observed neutral into an official brand fact. Do not invent semantic success/warning/error colors.++## 2. Identity Brief Fields++Surface these through Create Template's single shared Step 2–3 gate:++| Field | Requirement |+|---|---|+| Brand display name and use cases | Required |+| Primary color | Required; `#RRGGBB` plus provenance |+| Secondary/accent/text/background colors | Include only when confirmed or supported by evidence; every written color uses `#RRGGBB` plus provenance |+| Title/body typography | Required; retain provenance in surrounding prose when it is not official |+| Logo | Optional; identify the default presenting entity, file, usage rule, and any trademark restriction |+| Voice and tone | Required; formality, grammatical person, emoji policy, abbreviation policy |+| Icon style | Required; `linear`, `filled`, `duotone`, or a confirmed custom description |+| Adopted assets | Optional; list included and excluded candidates with reasons |++When the user explicitly requests an empty skeleton, all identity values remain TODO comments, materialization stops after writing the file, and Create Template reports that the workspace is incomplete and unregistered.++## 3. Materialize the Confirmed Brand++Create Template supplies an already resolved and collision-checked `<template_workspace>`. Write only:++```text+<template_workspace>/+├── templates/+│ └── design_spec.md+├── images/ # optional; logo/photos/illustrations only when adopted+└── icons/ # optional; branded icon overrides only when adopted+```++Do not create empty optional directories or `exports/`. Bitmap references from `templates/design_spec.md` use `../images/<name>`; branded icon references use `../icons/<name>`.++Write this personality-only schema:++```markdown+---+brand_id: <confirmed slug>+kind: brand+summary: <one-line use case>+primary_color: "#XXXXXX"+---++# <Display Name> Brand Specification++> Identity-only preset. No SVG page roster — pages are composed freely under these constraints.++## I. Brand Overview+| Property | Value |+|---|---|+| Brand Name | <display name> |+| Use Cases | <summary> |+| Tone | <one-line tone summary> |+| Sources | <official URL or bundled asset paths; include version/retrieval date when known> |++## II. Color Scheme+| Role | HEX | Provenance |+|---|---|---|+| primary | #XXXXXX | fact \| approx \| user |+| secondary | #XXXXXX | fact \| approx \| user |+| accent | #XXXXXX | fact \| approx \| user |++## III. Typography+| Role | Family | Weight |+|---|---|---|+| title | <family> | <weight> |+| body | <family> | <weight> |++## IV. Logo+- File: `../images/logo.<ext>` or `none`+- Usage: cover-only \| every-page \| never++## V. Voice & Tone+- Formality: formal \| neutral \| casual+- Person: informal-you \| formal-you \| we \| none+- Emoji: allowed \| forbidden+- Abbreviations: spell-out-first \| common-abbrev-allowed++## VI. Icon Style+- Preference: linear \| filled \| duotone \| <custom>++## VII. Visual Assets+- Include this section only when real `images/` or `icons/` assets exist.+```++Preserve a supplied logo's extension. When multiple lockups exist, use descriptive filenames and name exactly one default presenting entity. Keep subsidiary/campaign alternates explicit; create another brand workspace when their identity differs materially.++## 4. Brand Validation++Return these facts to Create Template:++- `templates/design_spec.md` exists and contains `brand_id`, `kind: brand`, `summary`, and `primary_color`.+- `brand_id` matches the confirmed workspace ID in library scope.+- Required sections I–VI exist; Page Roster and Signature Design Elements do not exist.+- No `*.svg`, `native_structure_mode`, Master/Layout, placeholder, canvas, or page-count fields were written.+- Every color is `#RRGGBB`, the primary table row matches frontmatter, and provenance is `fact`, `approx`, or `user`.+- Every referenced asset exists under the same workspace; no empty optional directory or `exports/` directory was created.++For `library` scope, Create Template Step 5 validates with:++```bash+python3 skills/ppt-master/scripts/register_template.py <brand_id> --kind brand --dry-run+```++After that gate passes, Create Template Step 7 registers with:++```bash+python3 skills/ppt-master/scripts/register_template.py <brand_id> --kind brand+```++For `project` scope, skip both commands and report `Not registered (project workspace)`. Downstream consumption always uses the explicit workspace root through Generate PPTX Step 3; a bare brand name never activates it.diff --git a/skills/ppt-master/workflows/create-template/create-deck.md b/skills/ppt-master/workflows/create-template/create-deck.mdnew file mode 100644index 00000000..004ec43e--- /dev/null+++ b/skills/ppt-master/workflows/create-template/create-deck.md@@ -0,0 +1,118 @@+---+description: Create Deck child workflow for a complete reusable identity-and-structure workspace.+---++# Create Deck Workflow++Enter this child workflow only after [`Create Template`](../create-template.md) dispatches `kind: deck`.++## Responsibility Boundary++| Owner | Responsibilities |+|---|---|+| Create Template | Child-workflow dispatch plus the shared source taxonomy, `library` / `project` scope, confirmation gate, collision preflight, structured authoring contract, validation commands, registration, completion, and Generate PPTX handoff |+| Create Deck | Integrated identity-and-structure interpretation, deck-specific brief fields, complete `design_spec.md`, SVG roster, and deck-specific validation |++**Hard rule — child workflow, not a top-level route**: Create Deck executes only inside Create Template. It reuses the parent workflow's Steps 1–8 and never creates a competing entry route or second confirmation gate.++**Hard rule — complete reusable system**: A deck owns the identity segment, the structure segment, and the deck-only Template Overview. It is a reusable template workspace, not the user's finished content deck.++## Invocation Points++1. Use §1–2 below while executing Create Template Steps 1–3.+2. After Create Template Step 4 preflights `<template_workspace>`, use §3 to author or materialize the deck workspace under the shared structured contract.+3. Apply §4 in addition to Create Template Step 5, then continue through shared Steps 6–8.++## 1. Deck Input Interpretation++Use Create Template Step 1 for source ingestion and replication-mode eligibility. Interpret source evidence across both segments:++- Identity: color, typography, logo, visual voice, and icon style, with fact/suggestion provenance preserved in the brief.+- Structure: canvas, page grammar, Master/Layout families, slot geometry, page types, image behavior, and density rhythm.+- Middle: use cases, design intent, presentation rhythm, and other deck-specific overview context.+- `standard` and `fidelity` author a new complete system; source topology is not output topology. `mirror` preserves only validated package/contract facts in a new workspace and never modifies the source.++Create Deck is the default child when identity and structure are both requested or when the source is a specific organization's branded presentation system. If the user explicitly wants identity-only or brand-neutral structure, return to Create Template dispatch before the shared confirmation marker is emitted.++## 2. Deck Brief and Schema++Add these child-owned requirements to Create Template Step 2:++| Field | Requirement |+|---|---|+| Deck ID and display name | Required; `deck_id` is a filesystem-safe ASCII slug |+| Use cases and design intent | Required; becomes the Template Overview |+| Identity | Required; primary color plus supported palette, typography, logo policy, visual voice, and icon style |+| Canvas and page grammar | Required; exact canvas, page types, variants, grids, zones, density rhythm, and image behavior |+| Native structure | Required; Master families, Layout ownership, slot vocabulary, and zero-slot Layouts where intentional |+| Replication mode | Required; `standard`, eligible `fidelity`, or eligible `mirror` under Create Template Step 1 |+| Adopted assets | Optional; list included and excluded candidates with reasons |++Write this complete schema:++```markdown+---+deck_id: <confirmed slug>+kind: deck+category: brand | general | scenario | government | special+summary: <one-line use case and tone>+keywords: [<three-to-five tags>]+primary_color: "#XXXXXX"+canvas_format: ppt169+canvas_width: 1280+canvas_height: 720+canvas_viewbox: "0 0 1280 720"+replication_mode: standard | fidelity | mirror+native_structure_mode: structured+page_count: <N>+---++# <Deck Name> — Design Specification++## I. Template Overview+## II. Color Scheme+## III. Typography+## IV. Signature Design Elements+## V. Page Roster+## VI. Assets+## VII. Placeholder Overrides+```++Omit Typography only when the shared default is intentionally used. Omit Assets and Placeholder Overrides when none exist. Do not restate generic SVG constraints, layout libraries, font-ratio bands, or the canonical placeholder table.++## 3. Author or Materialize the Deck++Follow Create Template Step 4 and the shared Template_Designer contract with `kind: deck`, `kind_dir: decks`, and `id_key: deck_id` fixed. Do not ask the user to choose the kind again.++The output is:++```text+<template_workspace>/+├── templates/ # design_spec.md + SVG prototypes+├── images/ # optional adopted bitmaps+├── icons/+│ └── imported/ # optional imported vectors+└── exports/ # conditional review evidence+```++Every SVG is a complete preview and declares one root Master and Layout under the shared structured contract. The deck's SVG paint, typography, and adopted assets must agree with its identity segment. Every additional authored Master represents a distinct reusable design family, not one Layout or an organizational duplicate.++## 4. Deck Validation++In addition to Create Template Steps 5–6, verify:++- `templates/design_spec.md` contains `deck_id`, `kind: deck`, `summary`, `primary_color`, canvas fields, `replication_mode`, `native_structure_mode: structured`, and `page_count`.+- `deck_id` matches the confirmed workspace ID in library scope.+- Template Overview, Color Scheme, Signature Design Elements, and Page Roster exist; conditional sections match real choices/assets.+- Every identity color is `#RRGGBB`; the primary table row matches frontmatter, and SVG paint follows the confirmed identity.+- Every SVG in the roster satisfies the shared Master/Layout/slot contract and the roster is bidirectionally complete.+- Every referenced image/icon exists under the same workspace and no empty optional directory was created.++For library scope, Create Template validates and registers with:++```bash+python3 skills/ppt-master/scripts/register_template.py <deck_id> --kind deck --dry-run+python3 skills/ppt-master/scripts/register_template.py <deck_id> --kind deck+```++For project scope, skip both commands. The exact workspace root becomes the next Generate PPTX Step 3 input; any separately supplied Brand or Layout workspace overrides the corresponding complete segment downstream without mutating this deck workspace.diff --git a/skills/ppt-master/workflows/create-template/create-layout.md b/skills/ppt-master/workflows/create-template/create-layout.mdnew file mode 100644index 00000000..6751c25e--- /dev/null+++ b/skills/ppt-master/workflows/create-template/create-layout.md@@ -0,0 +1,116 @@+---+description: Create Layout child workflow for a brand-neutral reusable page-structure workspace.+---++# Create Layout Workflow++Enter this child workflow only after [`Create Template`](../create-template.md) dispatches `kind: layout`.++## Responsibility Boundary++| Owner | Responsibilities |+|---|---|+| Create Template | Child-workflow dispatch plus the shared source taxonomy, `library` / `project` scope, confirmation gate, collision preflight, structured authoring contract, validation commands, registration, completion, and Generate PPTX handoff |+| Create Layout | Structure-only interpretation, layout-specific brief fields, brand-neutral `design_spec.md`, SVG roster, and layout-specific validation |++**Hard rule — child workflow, not a top-level route**: Create Layout executes only inside Create Template. It reuses the parent workflow's Steps 1–8 and never creates a competing entry route or second confirmation gate.++**Hard rule — structure only**: A layout owns canvas, page grammar, Master/Layout families, slot geometry, page types, image behavior, density rhythm, and the SVG prototype roster. It owns no brand palette, typography system, logo, voice, or icon identity.++Neutral colors and safe fonts may appear in SVG prototypes so the structure is reviewable. They are preview paint, not a locked identity segment, and must not be written as brand truth in `design_spec.md`.++## Invocation Points++1. Use §1–2 below while executing Create Template Steps 1–3.+2. After Create Template Step 4 preflights `<template_workspace>`, use §3 to author or materialize the layout workspace under the shared structured contract.+3. Apply §4 in addition to Create Template Step 5, then continue through shared Steps 6–8.++## 1. Layout Input Interpretation++Use Create Template Step 1 for source ingestion and replication-mode eligibility. Interpret source evidence only for reusable structure:++- Canvas dimensions, grid, zones, page taxonomy, repeated chrome, image placement, density rhythm, and placeholder geometry may become layout facts or suggestions.+- Colors, fonts, logos, voice, and icon style remain source context only. Do not copy them into the layout identity because a layout has no identity segment.+- When the source is branded, explicitly confirm that Create Layout will strip that identity. If the user wants the identity retained with the structure, return to Create Template dispatch and select Create Deck before the shared confirmation marker is emitted.+- `standard` and `fidelity` author a new Master/Layout/slot system. `mirror` is available only when the source contains a complete current structure contract and preserves validated structure facts in a new workspace without modifying the source.++## 2. Layout Brief and Schema++Add these child-owned requirements to Create Template Step 2:++| Field | Requirement |+|---|---|+| Layout ID and display name | Required; `layout_id` is a filesystem-safe ASCII slug |+| Structural use cases | Required; describe content shapes and presentation contexts, not brand tone |+| Canvas | Required; exact format, dimensions, and `viewBox` |+| Page grammar | Required; page types, variants, grids, zones, density rhythm, and image behavior |+| Native structure | Required; Master families, Layout ownership, slot vocabulary, and zero-slot Layouts where intentional |+| Replication mode | Required; `standard`, eligible `fidelity`, or eligible `mirror` under Create Template Step 1 |+| Identity stripping | Required when branded reference material exists; list the identity facts intentionally excluded |++Write this structure-only schema:++```markdown+---+layout_id: <confirmed slug>+kind: layout+category: general | scenario | government | special+summary: <one-line structural use case>+keywords: [<three-to-five structural tags>]+canvas_format: ppt169+canvas_width: 1280+canvas_height: 720+canvas_viewbox: "0 0 1280 720"+replication_mode: standard | fidelity | mirror+native_structure_mode: structured+page_count: <N>+page_types: [cover, toc, chapter, content, ending]+---++# <Layout Name> — Design Specification++## IV. Signature Design Elements+## V. Page Roster+## VII. Placeholder Overrides+```++Omit `Placeholder Overrides` when no override exists. Omit Template Overview, Color Scheme, Typography, Logo, Voice, and every other identity section. Do not write `primary_color`.++`Signature Design Elements` describes only reusable structure. `Page Roster` lists every SVG with its Master/Layout identity, picker name, intended content shape, and slot behavior.++## 3. Author or Materialize the Layout++Follow Create Template Step 4 and the shared Template_Designer contract with `kind: layout`, `kind_dir: layouts`, and `id_key: layout_id` fixed. Do not ask the user to choose the kind again.++The output is:++```text+<template_workspace>/+├── templates/ # design_spec.md + SVG prototypes+├── images/ # optional structural/example bitmaps+├── icons/+│ └── imported/ # optional imported vectors+└── exports/ # conditional review evidence+```++Every SVG is a complete preview and declares one root Master and Layout under the shared structured contract. For authored modes, neutral preview paint must remain replaceable downstream. For mirror, preserve source structure and supported visuals exactly as allowed by Create Template, while keeping identity fields out of the layout spec.++## 4. Layout Validation++In addition to Create Template Steps 5–6, verify:++- `templates/design_spec.md` contains `layout_id`, `kind: layout`, `summary`, canvas fields, `replication_mode`, `native_structure_mode: structured`, `page_count`, and `page_types`.+- `layout_id` matches the confirmed workspace ID in library scope.+- Signature Design Elements and Page Roster exist; Template Overview and all identity sections do not.+- `primary_color`, brand palette, brand typography, logo, voice, and icon-identity claims are absent.+- Every SVG in the roster satisfies the shared Master/Layout/slot contract and the roster is bidirectionally complete.+- Neutral prototype paint is not described as a locked brand identity.++For library scope, Create Template validates and registers with:++```bash+python3 skills/ppt-master/scripts/register_template.py <layout_id> --kind layout --dry-run+python3 skills/ppt-master/scripts/register_template.py <layout_id> --kind layout+```++For project scope, skip both commands. The exact workspace root becomes the next Generate PPTX Step 3 input; downstream identity remains a Strategist decision unless an explicit Brand or Deck workspace is also supplied.diff --git a/skills/ppt-master/workflows/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.mdsimilarity index 85%rename from skills/ppt-master/workflows/failure-recovery.mdrename to skills/ppt-master/workflows/governance/failure-recovery.mdindex 71cf0604..18ce0990 100644--- a/skills/ppt-master/workflows/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -1,10 +1,10 @@----description: Failure recovery matrix for PPT Master generation routes+description: Governance matrix for stop/continue and recovery decisions across Generate PPTX stages.----# Failure Recovery Matrix+# Failure Recovery Governance-Central recovery rules for common PPT Master failures. Route-specific workflow files may add narrower handling, but must not weaken these stop/continue decisions.+Central recovery rules for common Generate PPTX failures. The route and stage documents 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.@@ -18,6 +18,7 @@ Central recovery rules for common PPT Master failures. Route-specific workflow f| Confirm UI wait timeout | No, if no final result yet | Re-check `result.json` once; keep server cleanup mandatory | Only if user still wants the page | Step 4 same stage or chat fallback || Confirm UI Stage 1 completed then interrupted | Yes until Stage 2 is written/confirmed | Read existing Stage 1 `result.json`, write Stage 2 recommendations, then `--wait-only --wait-stage stage2` | Usually no | Step 4 Stage 2 write/wait || Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation |+| Step 3 rejects a legacy or incomplete template contract | Yes | Stop template consumption; create a new current workspace through Create Template from the original PPTX/reference, then return with its exact workspace root | Only when required source evidence or template choices are unavailable | Create Template → Generate PPTX Step 3 || 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 |@@ -43,7 +44,7 @@ Central recovery rules for common PPT Master failures. Route-specific workflow f| 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. |+| Optional stage 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. |@@ -58,12 +59,12 @@ Central recovery rules for common PPT Master failures. Route-specific workflow f| Last good state | Resume from ||---|---|| Stage 1 confirmation exists, Stage 2 missing | Write Stage 2 recommendations, then `confirm_ui/server.py <project> --wait-only --wait-stage stage2` |-| `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](./resume-execute.md) |+| `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/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 |+| Browser annotations saved after export | [`live-preview`](../stages/live-preview.md) Step 2 |**Default - resume at the owning failed step**: Do not restart the planning session 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.mdindex 29acc13a..1d496e1f 100644--- a/skills/ppt-master/workflows/index.md+++ b/skills/ppt-master/workflows/index.md@@ -1,43 +1,51 @@----description: Registry of standalone PPT Master workflows+description: Registry of PPT Master's top-level routes and supporting child workflows, profiles, stages, and governance documents.---# Workflow Registry-Registry for standalone workflows referenced by `SKILL.md` and [`routing.md`](./routing.md).+Registry for the route authorities and supporting runbooks referenced by [`SKILL.md`](../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.+**Hard rule — four entry routes only**: User requests enter exactly one top-level route. Create Template child workflows, generation profiles, stages, and governance documents refine an active route; they are never presented as competing top-level routes.----## 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, globally or for one initialized project | Design source or explicit template-creation request; project scope also requires an initialized target project | Does not fill final content; an optional PPTX is only an on-demand review artifact | Workflow Step 1 | Both scopes produce one workspace with required `templates/`, optional `images/` / `icons/`, and optional `exports/<id>_template_preview.pptx`; library root is `skills/ppt-master/templates/<kind>/<id>/`, project root is `projects/<name>/`; only library scope is registered | Return the exact workspace root to main Step 3; the target project's own root may continue in place after validation |-| `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 | Complete identity-only workspace under `templates/brands/<id>/` | Blocks on brand evidence and validation defined in the workflow |-| `resume-execute` | [`resume-execute.md`](./resume-execute.md) | Continue an existing split-mode project | Planning-session artifacts exist | Do not re-run planning | Execution-session 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 | Strategist confirmation stage 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 |-| `restore-pptx-structure` | [`restore-pptx-structure.md`](./restore-pptx-structure.md) | Existing structured project or template uses a legacy/unmapped PowerPoint structure contract | Legacy structured SVG project/package exists; original PPTX/native facts are preferred when available; explicit `mode: flat` free-design/brand-only projects and legacy-flat packaging are not triggers | Not part of normal new-project generation; exporter never migrates implicitly | Before Step 3 template use, structured SVG generation, or structured export | Current structured SVGs plus complete Master/Layout lock mapping | Blocks only when restoration requires an unresolved design decision |-| `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 |-| `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 |+## 1. Top-Level Routes++| Route | Authority | Trigger | Mutation model | Output |+|---|---|---|---|---|+| Generate PPTX | [`SKILL.md`](../SKILL.md) | Create or visually regenerate a presentation from source material, a topic, or an existing deck | Author new SVG pages, then export a new PPTX | Project workspace with `design_spec.md`, `spec_lock.md`, `svg_output/`, and `exports/` |+| Create Template | [`create-template.md`](./create-template.md) | Create a reusable `brand`, `layout`, or `deck` workspace | Read reference facts and author a new template workspace; never add Master/Layout structure to the reference file in place | Portable template workspace with required `templates/` and optional assets/review export |+| Fill Native PPTX | [`template-fill-pptx.md`](./template-fill-pptx.md) | Reuse native slides from a raw PPTX and replace/fill their content | Clone and patch PPTX through OOXML; no SVG generation | New filled PPTX under the project `exports/` |+| Enhance Native PPTX | [`native-enhance-pptx.md`](./native-enhance-pptx.md) | Add notes, narration audio, timings, or transitions while preserving finished slides | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX under the project `exports/` |----## 2. Update Checklist+## 2. Supporting Documents++| Class | ID | Path | Owner / trigger |+|---|---|---|---|+| Generation profile | `beautify-pptx` | [`profiles/beautify-pptx.md`](./profiles/beautify-pptx.md) | Generate PPTX route when wording, page count, and page order are frozen 1:1 |+| Template child workflow | `create-brand` | [`create-template/create-brand.md`](./create-template/create-brand.md) | Create Template after identity-only intent is selected |+| Template child workflow | `create-layout` | [`create-template/create-layout.md`](./create-template/create-layout.md) | Create Template after brand-neutral structure-only intent is selected |+| Template child workflow | `create-deck` | [`create-template/create-deck.md`](./create-template/create-deck.md) | Create Template after integrated identity-and-structure intent is selected or defaulted |+| Intake stage | `topic-research` | [`stages/topic-research.md`](./stages/topic-research.md) | Generate PPTX route before Step 1 for topic-only requests |+| Control stage | `resume-execute` | [`stages/resume-execute.md`](./stages/resume-execute.md) | Generate PPTX route when a planned project resumes in a fresh chat |+| Planning stage | `refine-spec` | [`stages/refine-spec.md`](./stages/refine-spec.md) | Generate PPTX route after confirmation when the user explicitly requests spec review |+| Quality gate | `verify-charts` | [`stages/verify-charts.md`](./stages/verify-charts.md) | Generate PPTX route when data charts exist |+| Quality gate | `visual-review` | [`stages/visual-review.md`](./stages/visual-review.md) | Generate PPTX route only on explicit visual-review request |+| Editor stage | `live-preview` | [`stages/live-preview.md`](./stages/live-preview.md) | Generate PPTX route for preview, element selection, or applying annotations |+| Post-processing stage | `customize-animations` | [`stages/customize-animations.md`](./stages/customize-animations.md) | Generate PPTX route on explicit object-animation request |+| Shared audio stage | `generate-audio` | [`stages/generate-audio.md`](./stages/generate-audio.md) | Generate PPTX post-processing or Enhance Native PPTX narration module |+| Governance | `failure-recovery` | [`governance/failure-recovery.md`](./governance/failure-recovery.md) | Stop/continue decisions across generation stages |++----When adding or changing a standalone workflow:+## 3. Update Rules-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.+1. Add a row to §1 only when a request requires a genuinely distinct artifact lifecycle or mutation model.+2. Add child workflows, profiles, stages, and governance documents only to §2; do not add them to the top-level route matrix in [`routing.md`](./routing.md).+3. Update [`routing.md`](./routing.md) whenever a top-level trigger or route boundary changes.+4. Keep execution commands in the owning route or supporting document, 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.+**Forbidden — duplicated route matrices**: Do not copy the full route matrix from [`routing.md`](./routing.md) into `SKILL.md` or stage documents.diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.mdindex c3130e4e..b1f776ab 100644--- a/skills/ppt-master/workflows/native-enhance-pptx.md+++ b/skills/ppt-master/workflows/native-enhance-pptx.md@@ -2,11 +2,11 @@description: Native enhancement platform for existing PPTX files, starting with notes/audio/timings/transitions without SVG conversion----# Native Enhance PPTX Workflow+# Enhance Native PPTX Route-> Standalone workflow for enhancing an existing PowerPoint deck without regenerating it. V1 implements the `narration` module: speaker notes, narration audio, slide auto-advance timings, and page transitions.+> Top-level route for enhancing an existing PowerPoint deck without regenerating it. V1 implements the `narration` module: speaker notes, narration audio, slide auto-advance timings, and page transitions.-This workflow treats a `.pptx` as the artifact to preserve. It archives the source file into a lightweight project, uses `ppt_to_md.py` only to understand slide content, then patches the archived PPTX package directly through OOXML zip operations.+This route treats a `.pptx` as the artifact to preserve. It archives the source file into a lightweight project, uses `ppt_to_md.py` only to understand slide content, then patches the archived PPTX package directly through OOXML zip operations.---@@ -30,7 +30,7 @@ This workflow treats a `.pptx` as the artifact to preserve. It archives the sour**Hard rule — public entrypoint**: Route and document all new work through`native_enhance_pptx.py`. The legacy `native_narration_pptx.py` command remains-only as a thin CLI compatibility shim; it is not a separate workflow. The core+only as a thin CLI compatibility shim; it is not a separate route. The corecontinues to accept the legacy `native_narration_pptx_project.v1` project schema.**OOXML execution model**:@@ -58,7 +58,7 @@ source.pptx| `animation` | Planned | Explicit object-level animation only || `visible-stamp` | Planned | Watermark/footer/logo; requires explicit confirmation |-**Default — V1 only**: Do not implement planned modules inside this workflow yet. Keep V1 focused on the narration module.+**Default — V1 only**: Do not implement planned modules inside this route yet. Keep V1 focused on the narration module.**Object animation boundary**: Object-level animation is not part of V1. If the user asks for it, treat it as a future module or a separate explicitly confirmed task.@@ -68,11 +68,11 @@ source.pptx| Condition | Action ||---|---|-| Existing `.pptx` + wants notes / narration / voiceover / auto-play / page transitions while keeping format stable | Run this workflow |-| Existing `.pptx` + asks to optimize it but says not to change existing content or layout | Run this workflow only for V1 narration enhancements; clarify any visible-slide request |-| Existing `.pptx` + asks to beautify or re-layout | Use [`beautify-pptx`](./beautify-pptx.md) |+| Existing `.pptx` + wants notes / narration / voiceover / auto-play / page transitions while keeping format stable | Run this route |+| Existing `.pptx` + asks to optimize it but says not to change existing content or layout | Run this route only for V1 narration enhancements; clarify any visible-slide request |+| Existing `.pptx` + asks to beautify or re-layout | Enter Generate PPTX with the [`beautify-pptx`](./profiles/beautify-pptx.md) profile || Existing `.pptx` + asks to fill new content into the design | Use [`template-fill-pptx`](./template-fill-pptx.md) |-| PPT Master generated project with `svg_output/` | Use [`generate-audio`](./generate-audio.md) for narration |+| PPT Master generated project with `svg_output/` | Stay in Generate PPTX and run the shared [`generate-audio`](./stages/generate-audio.md) stage |---@@ -198,26 +198,13 @@ python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>"----## 7. Audio Voice Confirmation+## 7. Shared Audio Configuration🚧 **GATE**: Step 6 complete; `audio.enabled` is true.-Follow the same one-shot interaction standard as [`generate-audio`](./generate-audio.md):+Run [`generate-audio`](./stages/generate-audio.md) Steps 1–3. That shared stage exclusively owns language selection, provider/voice catalog lookup, recommendation rules, and the one-shot confirmation. Do not repeat or fork those rules here.-1. Determine the notes' primary language.-2. List available voices for the selected backend.-3. Recommend backend, voice, rate/settings, and whether to embed audio back into the PPTX.-4. Ask the user to accept all recommendations or override any field.--For edge voices:--```bash-python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale <locale>-```--**⛔ BLOCKING**: Stop here and wait for explicit user confirmation of audio backend, voice, rate/settings, and embedding. Do not run `notes_to_audio.py` before this confirmation.--Record the confirmed audio config into `project.json`:+Record the confirmed config into `project.json`:```json{@@ -231,18 +218,11 @@ Record the confirmed audio config into `project.json`:----## 8. Generate Audio+## 8. Run the Shared Audio Stage🚧 **GATE**: Step 7 confirmed; notes files exist under `<project>/notes/`.-Run with the confirmed values:--```bash-python3 skills/ppt-master/scripts/notes_to_audio.py "<project>" \- --voice <chosen-ShortName> --rate <chosen-rate>-```--**Default — edge (may override)**: Use `edge` unless the user requests a cloud provider or supplies a cloned voice ID.+Run [`generate-audio`](./stages/generate-audio.md) Step 4 with `<project>` and the confirmed values. Stop after audio generation; do not run its Generate-PPTX-only `svg_to_pptx.py --recorded-narration` integration. This route integrates audio through Step 9 instead.**Naming contract**: Audio stems match note stems: `001.md` → `001.mp3`.diff --git a/skills/ppt-master/workflows/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.mdsimilarity index 91%rename from skills/ppt-master/workflows/beautify-pptx.mdrename to skills/ppt-master/workflows/profiles/beautify-pptx.mdindex 0b504db4..5c910c76 100644--- a/skills/ppt-master/workflows/beautify-pptx.md+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md@@ -1,10 +1,10 @@----description: Content-faithful PPT beautification — re-layout an existing deck while preserving its text verbatim and inheriting its visual identity, so regenerated elements share the original's palette/fonts and blend with it when pasted back.+description: Main-generation profile for 1:1, content-faithful re-layout of an existing deck through the standard SVG pipeline.----# Beautify PPTX (Re-layout) Workflow+# Beautify PPTX (Re-layout) Profile-> Mirror of [`template-fill-pptx.md`](./template-fill-pptx.md): template-fill reuses a deck's design and swaps in new content; beautify keeps a deck's content and redoes its layout.+> Main-pipeline profile, not a top-level route. [`template-fill-pptx.md`](../template-fill-pptx.md) reuses a deck's design and swaps in new content; this profile keeps a deck's content and redoes its layout.Re-lays-out an existing `.pptx`: the text is preserved **verbatim**, the source deck's visual identity (palette / fonts) is **inherited as truth**, and only layout, hierarchy, and whitespace are redesigned. Output is a brand-new native deck generated through the standard SVG pipeline — not a patch over the original.@@ -22,11 +22,11 @@ Re-lays-out an existing `.pptx`: the text is preserved **verbatim**, the source**Hard rule — content is frozen**: every text string from the source is preserved exactly (no add / remove / reword / reorder). Beautification freedom lives only in layout, hierarchy, spacing, and visual rhythm.-**Hard rule — not a patch, not a fill**: this regenerates a native deck through Strategist → Executor → export (SKILL.md Steps 4–7). It does **not** edit the source file in place, and it is **not** [`template-fill-pptx`](./template-fill-pptx.md) (which clones source slides and replaces text). It also does not parse an arbitrary third-party template for text-only substitution (the rejected #53 direction) — it builds every page from scratch.+**Hard rule — not a patch, not a fill**: this regenerates a native deck through Strategist → Executor → export (SKILL.md Steps 4–7). It does **not** edit the source file in place, and it is **not** [`template-fill-pptx`](../template-fill-pptx.md) (which clones source slides and replaces text). It also does not parse an arbitrary third-party template for text-only substitution (the rejected #53 direction) — it builds every page from scratch.**Distinct from mirror templates**: `replication_mode: mirror` (executor §1.1) keeps layout + visuals verbatim and edits text. Beautify is the inverse — content verbatim, layout redone, identity inherited.-**When this is the wrong route — re-architecture belongs to the main pipeline**: beautify preserves the source's page count and page order 1:1. It is for "keep this deck, just lay it out better". When the user instead wants the original page breakdown reconsidered — merge / split / reorder pages, re-outline the structure, build a *better deck* from the same content rather than a prettier version of the same pages — that is not beautify. This includes re-pagination for fit: "keep every word but split a crowded page so it reads better" changes page count, so it is the main pipeline, not beautify. Convert the deck with [`ppt_to_md`](../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 deciding question: is the source's page split information to preserve, or just the previous author's structure to improve? Preserve → beautify (here); improve → `ppt_to_md` + main pipeline.+**When this profile is wrong — re-architecture belongs to the default main pipeline**: this profile preserves the source's page count and page order 1:1. It is for "keep this deck, just lay it out better". When the user instead wants the original page breakdown reconsidered — merge / split / reorder pages, re-outline the structure, build a *better deck* from the same content rather than a prettier version of the same pages — do not activate this profile. This includes re-pagination for fit: "keep every word but split a crowded page so it reads better" changes page count. Convert the deck with [`ppt_to_md`](../../scripts/source_to_md/ppt_to_md.py) and run the default main pipeline, where the Strategist re-architects the outline freely from the extracted content. The deciding question: is the source's page split information to preserve, or just the previous author's structure to improve? Preserve → activate this profile; improve → default main pipeline.---@@ -49,7 +49,7 @@ Match the canvas to the source so 1:1 pages and paste-back align. Determine the|---|---|| ≈1.778 (16:9) | `ppt169` || ≈1.333 (4:3) | `ppt43` |-| other | nearest format in [`canvas-formats.md`](../references/canvas-formats.md); record the source pixel size in the spec |+| other | nearest format in [`canvas-formats.md`](../../references/canvas-formats.md); record the source pixel size in the spec |```bashpython3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>@@ -165,7 +165,7 @@ This step has two halves:**Visual re-confirm — full confirm UI seeded from the source**:-Write `<project_path>/confirm_ui/recommendations.json` and launch the same confirm server SKILL.md Step 4 uses. Do **not** hide fields: seed **every** targeted-confirmation field with the inherited / source-derived default so the user sees the recommendation and keeps the place to change it. Schema → [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md).+Write `<project_path>/confirm_ui/recommendations.json` and launch the same confirm server SKILL.md Step 4 uses. Do **not** hide fields: seed **every** targeted-confirmation field with the inherited / source-derived default so the user sees the recommendation and keeps the place to change it. Schema → [`scripts/docs/confirm_ui.md`](../../scripts/docs/confirm_ui.md).```json{@@ -202,7 +202,7 @@ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --waitRead the confirmed canvas + palette + typography (incl. `body_size`) and any other overrides from `<project_path>/confirm_ui/result.json`. Chat is the canonical fallback when the page cannot open (remote / headless) — present the same fields in chat and honor the reply identically. Always run `--shutdown` on exit (page-confirm or chat-fallback) so port 5050 is free for Step 6 live preview.-On confirmation, enter SKILL.md Step 4 as Strategist with the plan pre-resolved. The two beautify invariants always hold: the content-faithful clause ([`strategist.md`](../references/strategist.md) §d Layer 1) and page count = source slide count (strict 1:1). Everything else comes from the **confirmed** `result.json` — `mode` (recommended `briefing`), canvas, `visual_style`, color (e) + typography (g) incl. `body_size` (the reviewed values; skip both recommendation flows) — honoring whatever the user kept or overrode. §VII = chart/table data → `templates/charts/`, §VIII = source pictures for re-layout.+On confirmation, enter SKILL.md Step 4 as Strategist with the plan pre-resolved. The two beautify invariants always hold: the content-faithful clause ([`strategist.md`](../../references/strategist.md) §d Layer 1) and page count = source slide count (strict 1:1). Everything else comes from the **confirmed** `result.json` — `mode` (recommended `briefing`), canvas, `visual_style`, color (e) + typography (g) incl. `body_size` (the reviewed values; skip both recommendation flows) — honoring whatever the user kept or overrode. §VII = chart/table data → `templates/charts/`, §VIII = source pictures for re-layout.**Hard rule — §IX is verbatim and 1:1**: each source slide becomes exactly one page, in source order, its text transcribed word-for-word from `sources/<stem>.md`. Do not merge, split, drop, or rewrite. Write `design_spec.md` + `spec_lock.md` per `strategist.md` §6, then hand off to the Executor.diff --git a/skills/ppt-master/workflows/restore-pptx-structure.md b/skills/ppt-master/workflows/restore-pptx-structure.mddeleted file mode 100644index 4f98c554..00000000--- a/skills/ppt-master/workflows/restore-pptx-structure.md+++ /dev/null@@ -1,208 +0,0 @@-----description: Restore legacy SVG projects to the explicit structured Master/Layout contract------# Restore PPTX Structure Workflow--Restore an existing SVG-authored project or template before quality checking or release export when its Master/Layout contract is absent or legacy.--**Trigger**: Run when a structured/template project reports a missing or legacy `pptx_structure.mode`, or when the user explicitly asks to migrate an older structured SVG project. Do not run for a current free-design/brand-only project that explicitly declares `pptx_structure.mode: flat`; missing Master/Layout identity is intentional on that route.--**Hard rule — structure, not packaging**: Directory shape is not PowerPoint structure evidence. A current template workspace uses `templates/design_spec.md`; a compatible legacy-flat package uses `design_spec.md` at its root. Do not run this workflow merely to move a flat package into the current workspace shape.--**Boundary against template creation**: This workflow normalizes one existing project's/package's structure without visual redesign. It does not choose a reusable-template replication mode. When its result becomes type-B input to [`create-template`](./create-template.md), `standard` / `fidelity` treat it as visual reference and author new structure; `mirror` restores its explicit source ownership one-to-one.-------## 1. Route Boundary--| Input state | Action |-|---|---|-| Missing `pptx_structure` or legacy `baseline` / `generated` | Restore structure from the complete SVG deck; use source facts when available |-| Legacy `template`, `layout_strategy: distill`, `data-pptx-layout-kind`, or `utility` | Replace the distillation contract with one explicit structured contract |-| Legacy `preserve` plus `native_structure.json` / `source_template.pptx` | Use the native facts as restoration evidence; rebuild the SVG contract instead of preserving package parts |-| Existing `mode: structured` project | Validate and repair only the reported mismatch; do not re-infer the deck |-| Legacy-flat template package whose SVG roots and slots already satisfy the current structured contract | Consume it through the compatibility reader; do not restore or relocate it solely because `design_spec.md` and SVGs are flat |-| Current template workspace with `templates/` and optional `images/`, `icons/`, or `exports/` | Inspect SVG metadata to decide whether restoration is needed; the workspace folders themselves do not prove or disprove structure |-| Raw PPTX intended as a reusable template | Run [`create-template`](./create-template.md), not this workflow |-| Existing PPTX receiving notes/audio/timing/transitions | Keep the direct [`native-enhance-pptx`](./native-enhance-pptx.md) route; do not create SVGs |-| Raw PPTX template receiving new content | Keep the direct [`template-fill-pptx`](./template-fill-pptx.md) route |--**Hard rule**: Keep restoration in the main agent and inspect the complete page roster. Do not delegate page classification, cluster by visual similarity, or write a batch SVG generator.--🚧 **GATE**: Take the explicit project/template workspace root as input. For a project, read `spec_lock.md`, every file in `svg_output/`, and every template SVG named by `page_layouts`. For a template, resolve `templates/design_spec.md` first and fall back to legacy root `design_spec.md`, then read every sibling template SVG. In either case, read any original PPTX/native structure facts that belong to the workspace.-------## 2. Preserve the Pre-Migration State--Before editing, copy the current `svg_output/` and `spec_lock.md` into one new timestamped directory under:--```text-<project>/backup/<timestamp>/restore-pptx-structure/-```--Record the source evidence used for restoration in a short `README.md` inside that backup directory: original PPTX/native facts, legacy template SVGs, or completed SVG pages only.--**Hard rule**: Never delete the legacy sources during restoration. If the requested migration would rewrite several existing files and the user has not already authorized that operation, obtain the repository-required bulk-modification confirmation first.--**Hard rule — no packaging migration**: Keep the input workspace/package placement unchanged. This workflow edits the semantic SVG/lock contract only; it does not normalize a legacy-flat package into the current `templates/` plus optional `images/`, `icons/`, and `exports/` routing.-------## 3. Determine the Structure--Use this evidence priority:--| Priority | Evidence | Contract |-|---:|---|---|-| 1 | Original PPTX plus verified native structure facts | Use the source contract as compatibility evidence for this no-redesign restoration; record any required normalization |-| 2 | Legacy template SVGs or explicit legacy structure metadata | Preserve stable identities and reusable geometry after removing legacy-only fields |-| 3 | Completed SVG pages only | Classify deliberately across the full deck; do not let the exporter infer structure |--**Hard rule — complete native graph**: Preserve every supported native Layout,-including one unused by every output page. Create a definition-only-`layout_<layout_key>.svg` prototype for each otherwise unrepresented Layout and-record it in the unique `pptx_layouts` roster with a-`template:<basename>` source. A Master reachable only through such Layouts is-retained through their parent relationship. Do not silently drop identities or-synthesize a generated carrier page.--**Hard rule**: Decide from SVG/lock semantics, never from whether `design_spec.md` is at the workspace root or under `templates/`.--Classify each visible object:--| Classification | SVG representation |-|---|---|-| Fixed across every Layout under one Master | Root-level atomic element with `data-pptx-layer="master"` |-| Fixed only for one reusable Layout | Root-level atomic element with `data-pptx-layer="layout"` |-| Replaceable reusable content region | Root-level placeholder `<g>` with explicit design-zone bounds |-| Page-specific content or foreground overlay | Ordinary Slide-local SVG content without Master/Layout ownership |--**Hard rule — no Master/Layout groups**: A fixed Master or Layout visual must not be a `<g>`. Recursively expand every legacy/source group into individual root-level atomic elements. Compose and apply group transforms, opacity, inherited paint, clip behavior, and styles to each atom while preserving paint order. The restoration target preserves supported visual output and Master/Layout topology; it does not preserve source grouping as an editing unit.--**Hard rule — no visual redesign**: Do not change wording, geometry, paint, assets, or z-order except for the normalization required to flatten a fixed Master/Layout group. Render before and after any transform-flattening edit and require pixel equivalence.--**Hard rule — native metadata below structural layers**: Keep the complete lossless import artifact in the backup/evidence set. An unchanged imported shape may keep the source metadata already supported by the converter when it remains Slide-local or inside a slot; no additional opt-in marker exists. A logical `<g>` cannot become Master/Layout because those layers require direct atoms. Normalize fixed-layer objects into direct atom(s), rebuilding a preset when supported and otherwise keeping the current SVG fallback. Any geometry, paint, text, or fingerprint change invalidates stale source metadata. `data-pptx-replace-with` remains reserved for optional PowerPoint-native Chart/Table replacement markers.-------## 4. Write the Structured SVG Contract--Every page root declares its final ownership:--```xml-<svg viewBox="0 0 1280 720"- data-pptx-master="master-default"- data-pptx-master-name="Default Master"- data-pptx-layout="content-two-column"- data-pptx-layout-name="Two Column">-```--Fixed visuals are direct atomic children:--```xml-<path id="master-brand-rule" data-pptx-layer="master" .../>-<rect id="layout-title-rule" data-pptx-layer="layout" .../>-```--An ordinary placeholder is one root-level group with exactly one compatible direct carrier:--```xml-<g id="title-slot"- data-pptx-placeholder="title"- data-pptx-placeholder-bounds="72 48 1136 72">- <text id="title"- data-pptx-placeholder-carrier="true"- x="72" y="100">Actual title</text>-</g>-```--| Slot contract | Rule |-|---|---|-| `title`, `subtitle`, `body`, `date`, `footer`, `slide-number` | Use exactly one direct text carrier |-| `picture`, `media` | Use exactly one compatible direct image/media carrier |-| `chart`, `table` | Use one compatible direct native carrier only when the matching native-object contract is valid |-| Atomic `object` | Use exactly one compatible direct carrier |-| Composite `object` | Set `data-pptx-placeholder-binding="proxy"`; keep the visible children Slide-local inside the slot and declare no carrier |--**Hard rule — bounds**: Every slot group declares `data-pptx-placeholder-bounds="x y width height"` with finite values and positive width/height. Bounds describe the reusable design zone, not the current content's tight box.--**Hard rule — wrapper neutrality**: The slot `<g>` is an authoring boundary, not a rendered object. It may carry only `id` and `data-pptx-*` attributes. Move any transform, opacity, fill/stroke, filter, clip/mask, style, or class behavior onto the visible children before marking the group as a slot.--**Hard rule — proxy boundary**: `proxy` is allowed only for a composite `object` slot. Ordinary slots must use the default carrier binding.--**Zero-slot Layouts are valid**: A cover, poster, or purely visual Layout may declare no placeholder group. Do not manufacture a full-page `object` slot or a `utility` Layout.--Remove legacy `data-pptx-layout-kind`, `layout_strategy`, `distilled`, `utility`, and preserve-only ownership metadata from the restored SVG contract.-------## 5. Replace the Project Lock--After every SVG has its final metadata, replace the legacy structure sections as one complete mapping:--```markdown-## pptx_structure-- mode: structured--## pptx_masters-- master-default: Default Master--## pptx_layouts-- cover-visual: master-default | Cover Visual | P01-- content-two-column: master-default | Two Column | P02--## page_pptx_layouts-- P01: cover-visual-- P02: content-two-column-```--**Hard rule**: `pptx_masters` contains every Master key exactly once. `pptx_layouts` contains every unique reusable Layout exactly once and declares its Master, picker name, and definition source. `page_pptx_layouts` contains exactly one assignment for every generated page. Each page root must match its assigned Layout definition. A Layout unused by generated pages uses `template:<basename>` as its definition source.--**Layout identity**: A Layout key is globally unique. Pages may reuse it only when their Layout atoms and slot id/type/index/bounds/binding/carrier contracts are identical. The same display name under two Masters still uses two different keys.--**Template adherence**: Keep `template_adherence: strict|adaptive` only when a template route already owns that policy. Strict pages keep the referenced contract. Adaptive pages that changed the contract receive a new Layout key and name.-------## 6. Validate and Resume--Before flattening each affected page, render and retain its baseline outside `.preview/`:--```bash-python3 skills/ppt-master/scripts/visual_review.py "<project_path>" --pages "<page_stem>"-cp "<project_path>/.preview/<page_stem>.png" "<backup_path>/<page_stem>.before.png"-```--After restoring that page, render again and compare it with the retained baseline:--```bash-python3 skills/ppt-master/scripts/visual_review.py "<project_path>" --pages "<page_stem>"-python3 -c 'from PIL import Image, ImageChops; import sys; a=Image.open(sys.argv[1]).convert("RGBA"); b=Image.open(sys.argv[2]).convert("RGBA"); raise SystemExit(0 if a.size == b.size and ImageChops.difference(a, b).getbbox() is None else 1)' "<backup_path>/<page_stem>.before.png" "<project_path>/.preview/<page_stem>.png"-```--Require exit code 0. If the render differs, repair the transform/style materialization before continuing. Pure metadata edits that do not change or reparent visible children do not require this comparison.--Then run:--```bash-python3 skills/ppt-master/scripts/svg_quality_checker.py "<project_path>"-```--Fix every error. The gate must confirm root Master/Layout identity, root-level atomic fixed elements, slot bounds, carrier/proxy rules, complete lock mappings, and same-key contract equality.--After the checker reports zero errors, return to `SKILL.md` Step 7.2 and Step 7.3. Run the commands sequentially with the same native-object, animation, narration, notes, and transition flags previously selected.--```markdown-## ✅ PPTX Structure Restoration Complete--- [x] Legacy SVG and lock artifacts backed up with source-evidence notes-- [x] Every page root declares one Master and one Layout-- [x] Fixed Master/Layout visuals are root-level atomic elements, never groups-- [x] Every slot has explicit bounds and a valid carrier or proxy contract-- [x] `spec_lock.md` contains complete `structured` Master and page mappings-- [x] Group-flattening edits are pixel-equivalent and the quality gate reports zero errors-- [x] Imported native metadata is used only through supported existing attributes on unchanged Slide-local/slot objects; Master/Layout objects remain direct atoms-- [ ] **Next**: Resume the canonical post-processing and release export steps-```diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.mdindex 58bcd2d4..d74d3b45 100644--- a/skills/ppt-master/workflows/routing.md+++ b/skills/ppt-master/workflows/routing.md@@ -1,12 +1,12 @@----description: Deterministic route selection rules for PPT Master requests+description: Deterministic selection among PPT Master's four top-level artifact routes.---# Routing Rules-Route selection authority for PPT Master. Use this file before entering the main pipeline or any standalone workflow.+Route selection authority for PPT Master. Select exactly one top-level route, then activate only the child workflows, profiles, and stages owned by that route.-**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.+**Hard rule**: If this file conflicts with a route summary in `SKILL.md`, `AGENTS.md`, or a user-facing document, this file wins for route selection. After selection, the route authority owns execution.---@@ -14,79 +14,100 @@ Route selection authority for PPT Master. Use this file before entering the main| 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. |+| One artifact lifecycle | Every request enters Generate PPTX, Create Template, Fill Native PPTX, or Enhance Native PPTX |+| Supporting documents are not top-level routes | Create Template child workflows, generation profiles, stages, and governance documents refine the selected route; never offer them as competing top-level routes |+| Missing prerequisite | State the missing prerequisite and stop that route; do not invent an alternative |+| Ambiguous existing-deck request | Ask one discriminator question only when needed: regenerate visible slides, fill native slide shells with new content, or preserve slides and add native behavior? |+| Explicit user override | Honor explicit route instructions only when the route preconditions are satisfied |-**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.+**Forbidden — route-choice menus**: Do not present multiple implementation paths when the request already matches one row in §2. Ordinary design choices remain at the selected route's existing confirmation gate.-### 1.1 SVG Page-Design Scope--| Route family | SVG contract |-|---|---|-| Main SVG pipeline and `beautify-pptx` | Every visible output-page object is authored in the completed page SVG; templates and locks guide authoring but are not export-time visual overlays. |-| `create-template` | Each reusable template SVG is a complete visual reference plus explicit PowerPoint structure metadata. Library and project outputs use the same routing: required `templates/`, optional `images/` / `icons/`, and optional on-demand review output under `exports/`. |-| `template-fill-pptx` and `native-enhance-pptx` | Native PPTX editing routes. They retain their OOXML contracts and are not forced through SVG. |-| Animation, transition, speaker-note, and narration workflows | Presentation behavior/content outside the visible page-design layer; keep their dedicated sidecars and package post-processing. |+----**Hard rule — no automatic structure upgrade**: Free-design and brand-only generation in the main SVG pipeline remains `pptx_structure.mode: flat` from planning through export. Repeated Slide-local objects never trigger `structured`, Master/Layout promotion, placeholder inference, or deduplication. A main-pipeline generation that requires reusable native Master/Layout/placeholder behavior must consume an explicit validated deck/layout template workspace in Step 3; when none exists, run [`create-template`](./create-template.md) first and return with its workspace root. The minimal Master plus Blank Layout emitted by flat export is PPTX package scaffolding, not an inferred design master. Raw PPTX template plus new content remains the `template-fill-pptx` route in §3.+## 2. Top-Level Route Matrix-**Hard rule**: Apply SVG page-design closure only after selecting an SVG-authoring route. Do not reroute a native PPTX operation merely to make every package-level capability pass through SVG.+| Route | Request shape | Authority | Preconditions | Mutation model | Output contract |+|---|---|---|---|---|---|+| Generate PPTX | Create a new presentation; regenerate an existing deck visually; use source material or a topic; optionally apply an explicit template workspace | Main [`SKILL.md`](../SKILL.md) | Source facts exist or the topic-research stage can gather them | Author new SVG pages and export a new PPTX | New project with `design_spec.md`, `spec_lock.md`, `svg_output/`, and `exports/` |+| Create Template | Create a reusable brand/layout/deck template from a PPTX, SVG, image/PDF reference, website/brand assets, or a verbal brief | [`create-template`](./create-template.md) | Reference material or an explicit template brief exists; project scope additionally requires an initialized target project | Author a new portable workspace; never modify the reference file in place | Workspace with required `templates/`, optional `images/` / `icons/`, and optional review `exports/` |+| Fill Native PPTX | Use a raw PPTX's native slide shells and replace/fill content | [`template-fill-pptx`](./template-fill-pptx.md) | Source PPTX plus new material/topic | Clone and patch PPTX through OOXML; no SVG pipeline | New filled PPTX in project `exports/` |+| Enhance Native PPTX | Keep a finished PPTX's visible slides stable while adding notes, audio, timings, or transitions | [`native-enhance-pptx`](./native-enhance-pptx.md) | Finished source PPTX exists | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX in project `exports/` |----## 2. Main Route Matrix+## 3. Generate PPTX Profiles and Stages-| 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 workspace path | User provides a current brand/layout/deck workspace root containing `templates/design_spec.md`, or a compatible legacy-flat root containing `design_spec.md` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name; passing a current workspace's inner `templates/` directory instead of its root | Path resolves, frontmatter kind is valid, and every deck/layout SVG satisfies the current structured Master/Layout/slot contract | Stage `templates/` plus any existing `images/` and `icons/` into the target project peers; consume the target project's own root in place; never consume the review-only `exports/` directory | Route only a structurally legacy SVG contract to [`restore-pptx-structure`](./restore-pptx-structure.md) before Step 3; a legacy-flat directory shape alone remains compatible and does not trigger restoration |+| Request condition | Generate-route behavior |+|---|---|+| Topic only, no substantive source facts | Run [`topic-research`](./stages/topic-research.md), then return to main Step 1 |+| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through `ppt_to_md.py` and PPTX intake; use the default main pipeline |+| Existing PPTX must preserve wording, page count, and page order 1:1 | Activate the [`beautify-pptx`](./profiles/beautify-pptx.md) profile inside the main pipeline |+| Explicit current brand/layout/deck workspace root | Apply main Step 3; consume the workspace root, never only its inner `templates/` directory |+| Split-mode project resumes in a fresh chat | Run [`resume-execute`](./stages/resume-execute.md) inside the active Generate route |+| User explicitly requests spec refinement | Run [`refine-spec`](./stages/refine-spec.md) after Strategist confirmation |+| Data charts exist | Run [`verify-charts`](./stages/verify-charts.md) before export |+| User explicitly requests visual review | Run [`visual-review`](./stages/visual-review.md) before post-processing |+| User requests preview, selection, or annotation application | Run [`live-preview`](./stages/live-preview.md) at the stage defined there |+| User requests object-level animation | Run [`customize-animations`](./stages/customize-animations.md) during post-processing |+| Generated project needs narration audio | Run [`generate-audio`](./stages/generate-audio.md) after notes/export readiness |++**Hard rule — profile, not fifth route**: The 1:1 beautify behavior uses the same Strategist → Executor → SVG export lifecycle as Generate PPTX. It changes content/page invariants; it does not define a separate artifact lifecycle.----## 3. PPTX-Specific Routes+## 4. Template and Master/Layout Boundary-| 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", including a template for one named initialized project | [`create-template`](./create-template.md) | `template-fill-pptx` one-off fill | PPTX/design reference exists, or the user gives an explicit template-creation brief; project output additionally requires an initialized target project | Both scopes produce one workspace with required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/<id>_template_preview.pptx`; library root is `skills/ppt-master/templates/<kind>/<id>/`, project root is `projects/<name>/`; only library scope is registered | Return the exact workspace root for main Step 3; the target project's own root may resume in place after validation |+**Hard rule — no direct structure grafting**: An existing PPTX or SVG is never upgraded in place by adding Master/Layout/placeholder structure. If reusable native structure is required:-**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.+1. Run [`create-template`](./create-template.md) to produce a separate validated workspace.+2. Pass that workspace root to Generate PPTX Step 3.+3. Author new structured SVG pages whose Master/Layout contract exists from their first generated draft.+4. Export a new PPTX from those pages.-**Hard rule**: Beautify is strictly 1:1. Any page count or page order change is re-architecture and therefore the main pipeline, not beautify.+When a PPTX already contains native Master/Layout parts, `create-template` mirror may read and preserve those existing package facts in the new workspace. It does not infer missing historical intent. An incomplete or legacy SVG package may guide `standard` / `fidelity` visually, but it is not mutated into a structured template and cannot claim source-topology recovery.++**Hard rule — no automatic structure upgrade**: Free-design and brand-only generation remains `pptx_structure.mode: flat`. Repeated Slide-local objects never trigger `structured`, Master/Layout promotion, placeholder inference, or deduplication. The minimal Master plus Blank Layout emitted by flat export is package scaffolding, not an inferred reusable design master.++| Input | Route behavior |+|---|---|+| Raw PPTX called a template + new content | Fill Native PPTX unless the user explicitly asks for a reusable template workspace |+| PPTX/SVG/reference + reusable template request | Create Template |+| Current template workspace root + content | Generate PPTX Step 3 |+| Legacy-flat root with current `design_spec.md` and current SVG contract | Generate PPTX Step 3 compatibility reader |+| Semantic-legacy or incomplete structured package | Create a new workspace through Create Template; do not migrate in place |+| Request to add a master directly to an existing PPTX/SVG | Unsupported; explain the Create Template → Generate PPTX lifecycle |----## 4. Optional and Post-Route Workflows+## 5. Create Template Child 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 | Complete identity-only workspace under `templates/brands/<id>/` | Stop if no brand source or brand intent exists |-| Continue a split-mode project | "Continue generating `projects/<name>`" after the planning session | [`resume-execute`](./resume-execute.md) | Project has planning-session artifacts | Execution-session SVG generation and export | Stop if required planning 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) | Strategist confirmation stage completed | Revised `design_spec.md` and `spec_lock.md` before Step 5/6 | Stop until user approves the refined spec |-| Restore legacy PowerPoint structure | Existing structured/template SVGs use unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or an incomplete root Master identity | [`restore-pptx-structure`](./restore-pptx-structure.md) before generation/export or before Step 3 template consumption | Legacy structured SVG project/package exists; original PPTX/native facts are used when available; an explicit `mode: flat` free-design/brand-only project and a flat package directory are not triggers | Current structured SVG contract plus unique `pptx_masters` / `pptx_layouts` definitions and complete `page_pptx_layouts` assignments | Stop if structure cannot be restored without an explicit design decision |-| 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 |+| Selected kind | Behavior |+|---|---|+| `brand` | Dispatch to [`create-brand`](./create-template/create-brand.md); write identity only and no SVG roster |+| `layout` | Dispatch to [`create-layout`](./create-template/create-layout.md); author brand-neutral structure and an SVG roster |+| `deck` | Dispatch to [`create-deck`](./create-template/create-deck.md); author identity, structure, template overview, and an SVG roster |++Create Template remains the fixed route name and owns the shared contract. These three documents are mutually exclusive child workflows, not additional top-level routes.++---++## 6. Native and Shared Post-Processing Boundary++| Artifact state | Narration route |+|---|---|+| Main-generated project with notes and exported deck | Shared [`generate-audio`](./stages/generate-audio.md) stage |+| Arbitrary finished PPTX that must preserve visible slides | Enhance Native PPTX; its narration module invokes the same shared audio-stage rules |++Object animation for generated SVG projects uses the animation stage. Native PPTX routes preserve existing object-animation fingerprints and do not silently claim an animation-editing capability.----## 5. Template Name Boundary+## 7. Template Name Boundary-| User input | Route behavior |+| User input | Behavior ||---|---|-| Explicit current brand/layout/deck workspace root containing `templates/design_spec.md` | Enter main Step 3 template option; use the workspace root, not its inner `templates/` directory |-| Explicit legacy-flat root containing `design_spec.md` | Enter main Step 3 through the compatibility reader; flat packaging alone does not require structure restoration |-| Bare template name, brand name, style label, or vague "use a template" | Do not trigger Step 3; treat as style input for Strategist confirmation stage |-| 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 |+| Explicit current workspace root containing `templates/design_spec.md` | Enter Generate PPTX Step 3 |+| Bare template/brand name or style label | Do not resolve it to a local path; treat it as a style brief |+| “What templates exist?” | List indexed workspace paths as Q&A; do not advance a route |-**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. For every current template kind, that path is the workspace root.+**Forbidden — fuzzy resolution**: Never resolve a bare name to a local template directory on the user's behalf. The explicit workspace root is the only Step 3 template trigger, except the exact validated workspace handed off by Create Template in the current conversation.diff --git a/skills/ppt-master/workflows/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdsimilarity index 95%rename from skills/ppt-master/workflows/customize-animations.mdrename to skills/ppt-master/workflows/stages/customize-animations.mdindex 80ecbd9c..9c0b6353 100644--- a/skills/ppt-master/workflows/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -1,18 +1,18 @@----description: Customize default PPTX animations with per-slide and per-object timing/effect overrides+description: Optional post-processing stage for per-slide and per-object animation overrides.----# Customize Animations Workflow+# Customize Animations Stage-> Standalone post-generation step. Run when the user asks to tune animation order, effects, timing, or object-level reveals — including simply turning per-element entrance animation on (it is off by default; page transitions still apply). This workflow creates `animations.json` overrides when the user wants element animation or finer control.+> Optional Generate-PPTX post-processing stage. Run when the user asks to tune animation order, effects, timing, or object-level reveals — including simply turning per-element entrance animation on (it is off by default; page transitions still apply). This stage creates `animations.json` overrides when the user wants element animation or finer control.## When to Run| Condition | Action ||---|---|-| User asks for object-level animation, reveal order, timing, or effect changes | Run this workflow |+| User asks for object-level animation, reveal order, timing, or effect changes | Run this stage || User only wants the default deck (page transitions, no element builds) | Do not run; normal `svg_to_pptx.py` export is enough |-| User just wants per-element entrance animation back on, deck-wide | No config needed — export with `svg_to_pptx.py -a auto`; run this workflow only for per-slide/per-object control |+| User just wants per-element entrance animation back on, deck-wide | No config needed — export with `svg_to_pptx.py -a auto`; run this stage only for per-slide/per-object control || `svg_output/*.svg` is missing | Complete the main Executor phase first || Existing `animations.json` is present | Validate and edit it; do not overwrite unless the user asks |@@ -266,7 +266,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>Generated export performs semantic read-back per slide, comparing row order, trigger, target, resolved effect tuple, duration, and offset. It then validates timing-tree placement, `p:cTn` ids, and `p:spTgt` references across the packaged PPTX. Stable `random` choices appear in the conversion trace when export enables `--conversion-trace`. Narration merges audio into the existing timing tree and must preserve these rows.-Direct-PPTX routes are preserve-only for object animation: they compare the source object-animation fingerprint before and after allowed edits, run structural package validation, and do not write, normalize, or claim ownership of effects. See [`pptx-animations.md`](../scripts/docs/pptx-animations.md) for the exact compatibility and OOXML contract.+Direct-PPTX routes are preserve-only for object animation: they compare the source object-animation fingerprint before and after allowed edits, run structural package validation, and do not write, normalize, or claim ownership of effects. See [`pptx-animations.md`](../../scripts/docs/pptx-animations.md) for the exact compatibility and OOXML contract.---diff --git a/skills/ppt-master/workflows/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.mdsimilarity index 74%rename from skills/ppt-master/workflows/generate-audio.mdrename to skills/ppt-master/workflows/stages/generate-audio.mdindex e36cf3a3..f625a171 100644--- a/skills/ppt-master/workflows/generate-audio.md+++ b/skills/ppt-master/workflows/stages/generate-audio.md@@ -1,18 +1,18 @@----description: Generate per-slide narration audio with AI-recommended voice selection, then optionally re-export PPTX with embedded audio+description: Shared post-processing stage for per-slide narration audio and optional embedding.----# Generate Audio Workflow+# Generate Audio Stage-> Standalone post-export step. Run when the user asks for "生成音频" / "录制旁白" / "narrated PPT" / "video export with voice", or proactively offer it after a deck is exported. Produces one audio file per slide via `edge-tts` by default, or a cloud TTS provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) when the user chooses high-quality narration or a cloned voice, then optionally re-exports a video-ready PPTX with audio embedded and per-slide auto-advance timings.+> Shared narration stage. Run from the Generate PPTX route after notes/export readiness, or from the Enhance Native PPTX narration module after its notes step. Produces one audio file per slide via `edge-tts` by default, or a cloud TTS provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) when the user chooses high-quality narration or a cloned voice. The caller owns final PPTX integration.-This workflow is **independent**: it reads `notes/*.md` and queries the selected TTS voice catalog — no upstream conversation context required. Safe to invoke in a fresh session.+This stage is **context-independent**: it reads `notes/*.md` and queries the selected TTS voice catalog, so either owning route may invoke it in a fresh session. It does not choose the top-level route and does not patch slide design.## When to Run-- `notes/total.md` exists and has been split into per-page files at `notes/*.md` (post-processing Step 7.1 done).+- Per-page narration files exist at `notes/*.md`. In Generate PPTX, split `notes/total.md` during Step 7.1. In Enhance Native PPTX, the notes module writes numeric files such as `001.md`.- Default mode: `edge-tts` is installed (`python3 -m pip install edge-tts`).-- The workflow is page-level only: one notes file becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.+- The stage is page-level only: one notes file becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.- PPT narration assets must be PowerPoint-reliable audio: `m4a` (AAC), `mp3`, or `wav`. The built-in TTS path defaults to `mp3`; provider formats such as `pcm`, `opus`, or `flac` must be transcoded before embedding.- PowerPoint recorded narration export requires `ffprobe` so slide timings can be written from actual audio duration.- High-quality cloud mode: provider API key is set before use:@@ -66,7 +66,7 @@ The output is a flat list of all available voices for the selected provider. Fro- **Cover both genders** when both exist for the locale.- **For edge**: prefer `COMMON_VOICES`-listed voices (curated set inside `notes_to_audio.py`) when the locale has them — they are battle-tested.- **For ElevenLabs**: prefer voices already present in the user's account; if the user provides a specific `voice_id`, do not override it.-- **For MiniMax / Qwen / CosyVoice**: if the user provides a cloned `voice_id`, use it directly. Do not attempt voice cloning inside the narration workflow.+- **For MiniMax / Qwen / CosyVoice**: if the user provides a cloned `voice_id`, use it directly. Do not attempt voice cloning inside this narration stage.- **Match the deck's tone** — pick the strongest recommendation based on style:- Consultant / data-driven / 财报 → 稳重男声(如 `zh-CN-YunjianNeural`)or 清晰女声(如 `zh-CN-XiaoxiaoNeural`)- General / 教学 / 产品介绍 → 明亮女声 / 年轻男声(如 `zh-CN-XiaoyiNeural` / `zh-CN-YunxiNeural`)@@ -84,7 +84,7 @@ Send a single message to the user that asks all three questions at once and prov**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the provider to whichever the user named (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`), pin the `voice_id` they gave you, and only confirm rate + embed-or-not.-**Message template** (Chinese; translate to user's chat language if different):+**Message template** (Chinese; translate to user's chat language if different). “Embed” means caller-specific integration: SVG re-export for Generate PPTX, or native OOXML application for Enhance Native PPTX.> 检测到 notes 主语言为 **<语言>**(locale: `<locale>`)。基于 deck 调性(<风格>),我推荐以下配置:>@@ -142,14 +142,21 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \--provider cosyvoice --voice-id <chosen-voice> \--cosyvoice-model cosyvoice-v3-flash-# 2. (If user kept embedding) Re-export PPTX with audio embedded+# 2A. Generate PPTX caller only: re-export with audio embeddedpython3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \--recorded-narration audio```If `notes_to_audio.py` errors with a missing dependency or missing provider API key, fix the prerequisite and re-run — do NOT swallow the error.-`--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.+**Caller integration**:++| Caller | After audio generation |+|---|---|+| Generate PPTX | When embedding was confirmed, run `svg_to_pptx.py --recorded-narration audio` as shown above |+| 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 |++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.---@@ -159,5 +166,5 @@ Output one summary block listing:- Number of audio files generated and their location (`<project_path>/audio/*`).- The provider, voice, and rate/settings actually used.-- (If embedded) the new narrated PPTX path under `<project_path>/exports/`.-- (If skipped embedding) one-line hint on how to embed later: `python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --recorded-narration audio`.+- The caller-owned integration result: narrated SVG export path, enhanced native PPTX path, or “audio only”.+- For Generate PPTX when embedding was skipped, one-line hint: `python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --recorded-narration audio`.diff --git a/skills/ppt-master/workflows/live-preview.md b/skills/ppt-master/workflows/stages/live-preview.mdsimilarity index 97%rename from skills/ppt-master/workflows/live-preview.mdrename to skills/ppt-master/workflows/stages/live-preview.mdindex ff033516..71571f86 100644--- a/skills/ppt-master/workflows/live-preview.md+++ b/skills/ppt-master/workflows/stages/live-preview.md@@ -1,12 +1,12 @@----description: Start the browser SVG editor when it is not running, and apply submitted annotations after Step 7 export+description: Main-pipeline editor stage for starting live preview and applying submitted annotations.----# Live Preview Workflow+# Live Preview Stage> **Purpose**: (1) start/reopen the browser SVG editor when no preview service is currently running, and (2) apply user-submitted annotations after Step 7 export completes.>-> **Not in scope**: Executor's mandatory auto-startup — that lives in [`SKILL.md`](../SKILL.md) Step 6. Do not re-launch a preview that is already running.+> **Not in scope**: Executor's mandatory auto-startup — that lives in [`SKILL.md`](../../SKILL.md) Step 6. Do not re-launch a preview that is already running.## When to Rundiff --git a/skills/ppt-master/workflows/refine-spec.md b/skills/ppt-master/workflows/stages/refine-spec.mdsimilarity index 63%rename from skills/ppt-master/workflows/refine-spec.mdrename to skills/ppt-master/workflows/stages/refine-spec.mdindex b8cabc85..33a1fa83 100644--- a/skills/ppt-master/workflows/refine-spec.md+++ b/skills/ppt-master/workflows/stages/refine-spec.md@@ -1,12 +1,12 @@----description: Opt-in spec-refinement loop between the Strategist confirmation stage and Image/Executor. Triggered only when the user explicitly asks; the Strategist produces the full design spec, then HARD STOPS so the user can review and revise any part of it before the pipeline continues.+description: Optional main-pipeline stage for reviewing and revising the complete spec before generation.----# Refine Spec Workflow+# Refine Spec Stage-> Standalone, **opt-in** spec-review pass. The default pipeline writes `design_spec.md` + `spec_lock.md` and auto-proceeds. When the user explicitly asks to refine the spec, the Strategist produces the full spec first, then **stops** — the user reviews and revises any part of it (outline, color, typography, layout, image strategy, page rhythm, …) before any image generation or SVG work begins.+> **Opt-in Generate-PPTX stage** for spec review. The default pipeline writes `design_spec.md` + `spec_lock.md` and auto-proceeds. When the user explicitly asks to refine the spec, the Strategist produces the full spec first, then **stops** — the user reviews and revises any part of it (outline, color, typography, layout, image strategy, page rhythm, …) before any image generation or SVG work begins.-This workflow is **conditional**, same shape as the split-mode choice: it never fires on its own and the default path is unchanged. The Strategist confirmation stage settles design directions up front as abstract recommendations; this pass lets the user revise the **concrete spec** the Strategist produced from them. It is most valuable for a zero-background user, who can judge a finished spec far better than the up-front recommendations — and the spec's content outline (`§IX`) is usually what they most want to adjust.+This stage is **conditional**, same shape as the split-mode choice: it never fires on its own and the default path is unchanged. The Strategist confirmation stage settles design directions up front as abstract recommendations; this pass lets the user revise the **concrete spec** the Strategist produced from them. It is most valuable for a zero-background user, who can judge a finished spec far better than the up-front recommendations — and the spec's content outline (`§IX`) is usually what they most want to adjust.## When to Run@@ -18,7 +18,7 @@ The user **explicitly asks** to refine / review / revise the spec before generat| "let me revise the spec, then continue" | "send me the spec to confirm, I'll edit it" || Any request to inspect/iterate the design spec before generation | "draft the full plan, I want to adjust it, then generate" |-**Default is OFF.** Strategist surfaces this option as one short opt-in line inside the Strategist confirmation stage (see SKILL.md Step 4). No request → the spec is written in one go and the pipeline auto-proceeds as usual; this workflow never starts.+**Default is OFF.** Strategist surfaces this option as one short opt-in line inside the Strategist confirmation stage (see SKILL.md Step 4). No request → the spec is written in one go and the pipeline auto-proceeds as usual; this stage never starts.**Prerequisite**: the Strategist confirmation stage is settled (mode + visual style + the rest). This pass revises the spec produced from that stage; it does not re-open the confirmation stage itself.@@ -47,9 +47,9 @@ The user may revise **any part of the spec**, not just the outline — content oThese overlap with what the locked `mode`, visual style, and §6.1 already shape — treat them as discussion angles to surface what is worth talking about, not a second pass to redo.-**Keep both files in sync on every change.** Any revision the user approves must land in both `design_spec.md` and `spec_lock.md`; on divergence `spec_lock.md` wins (see [`strategist.md`](../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.+**Keep both files in sync on every change.** Any revision the user approves must land in both `design_spec.md` and `spec_lock.md`; on divergence `spec_lock.md` wins (see [`strategist.md`](../../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.-**Re-run the structured-template preflight after structural revisions.** If the user changes `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the Strategist preflight in [`strategist.md`](../references/strategist.md) §6.2 before approval and hand-back. Every newly selected prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype must run [`restore-pptx-structure`](./restore-pptx-structure.md); do not create a fallback mode inside refinement.+**Re-run the structured-template preflight after structural revisions.** If the user changes `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the Strategist preflight in [`strategist.md`](../../references/strategist.md) §6.2 before approval and hand-back. Every newly selected prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.---@@ -57,4 +57,4 @@ These overlap with what the locked `mode`, visual style, and §6.1 already shapeOnce the user approves, `design_spec.md` and `spec_lock.md` both reflect the final, revised state. Return to SKILL.md and continue normally: Step 5 (Image Acquisition, if any `ai` / `web` rows) or Step 6 (Executor).-> Note: this workflow does NOT duplicate Strategist content. It only inserts a review-and-revise checkpoint between spec production and the rest of the pipeline. `strategist.md` / SKILL.md remain authoritative for how the spec is written.+> Note: this stage does NOT duplicate Strategist content. It only inserts a review-and-revise checkpoint between spec production and the rest of the pipeline. `strategist.md` / SKILL.md remain authoritative for how the spec is written.diff --git a/skills/ppt-master/workflows/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.mdsimilarity index 69%rename from skills/ppt-master/workflows/resume-execute.mdrename to skills/ppt-master/workflows/stages/resume-execute.mdindex 39f3c8f5..7e61cfc5 100644--- a/skills/ppt-master/workflows/resume-execute.md+++ b/skills/ppt-master/workflows/stages/resume-execute.md@@ -1,12 +1,12 @@----description: Execution-session entry — resume PPT execution in a fresh chat after the planning session (SKILL.md Step 1-5) completed in a previous chat. Reads project state from disk and runs Step 6 + Step 7 with no prior-chat context carry-over.+description: Main-pipeline control stage for resuming execution in a fresh chat after planning completed.----# Resume Execute Workflow+# Resume Execute Stage-> Standalone execution-session entry. Run when the planning session (SKILL.md Step 1–5) completed in a previous chat and the user wants to continue with SVG generation + export. Loads project state from disk and runs Step 6 + Step 7 in a clean session.+> Generate-PPTX control stage for a fresh execution session. Run when planning (SKILL.md Step 1–5) completed in a previous chat and the user wants to continue with SVG generation + export. Loads project state from disk and runs Step 6 + Step 7 without selecting another route.-This workflow is **independent**: it owns the execution session starting from a fresh chat — no upstream conversation context required. By isolating SVG generation in its own session, the model gains 20–40K context headroom by not carrying the planning session's Strategist confirmation dialogue, image search/fetch results, or Strategist references.+This stage is **context-independent**: it owns the execution session starting from a fresh chat — no upstream conversation context required. By isolating SVG generation in its own session, the model gains 20–40K context headroom by not carrying the planning session's Strategist confirmation dialogue, image search/fetch results, or Strategist references.## When to Run@@ -57,12 +57,12 @@ The fresh session pays the cost of re-reading references (~14K tokens) but earns**Source materials**: the execution session is fresh; `<project_path>/sources/<file>.md` is NOT in context. The Executor SHOULD read the relevant `sources/` files when crafting per-page content — they hold the concrete facts, quotes, names, and details that turn skeleton outlines into substantive slides. `design_spec.md §IX` only carries the per-page intent; the source materials carry the texture. The split-mode handoff is designed to free context budget precisely for this kind of high-quality enrichment.-> Note: this workflow does NOT duplicate Step 6 / Step 7 content. SKILL.md is the authoritative procedure; resume-execute only adds the resumption entry (When to Run + Step 1 sanity check above) and the source-materials guidance above.+> Note: this stage does NOT duplicate Step 6 / Step 7 content. SKILL.md is the authoritative procedure; resume-execute only adds the resumption entry (When to Run + Step 1 sanity check above) and the source-materials guidance above.---## Step 3: Hand-back-When Step 7 completes and `exports/<project_name>_<timestamp>.pptx` is produced, the workflow ends. Report the export path to the user.+When Step 7 completes and `exports/<project_name>_<timestamp>.pptx` is produced, the stage ends. Report the export path to the user.-If the deck contains data charts, the [`verify-charts`](verify-charts.md) workflow runs between Step 6 and Step 7 as documented in SKILL.md — resume mode handles it the same way the continuous mode does.+If the deck contains data charts, the [`verify-charts`](verify-charts.md) stage runs between Step 6 and Step 7 as documented in SKILL.md — resume mode handles it the same way the continuous mode does.diff --git a/skills/ppt-master/workflows/topic-research.md b/skills/ppt-master/workflows/stages/topic-research.mdsimilarity index 85%rename from skills/ppt-master/workflows/topic-research.mdrename to skills/ppt-master/workflows/stages/topic-research.mdindex 6eb4df4a..4ee0eb9a 100644--- a/skills/ppt-master/workflows/topic-research.md+++ b/skills/ppt-master/workflows/stages/topic-research.md@@ -1,19 +1,19 @@----description: Gather source materials via web search when the user supplies only a topic or requirements without source files. Produces a Markdown document and an image folder that feed SKILL.md Step 2's import-sources.+description: Main-pipeline intake stage that gathers source material for topic-only requests.----# Topic Research Workflow+# Topic Research Stage-> Standalone pre-processing step. Run before SKILL.md Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document + image folder, both shaped to feed `project_manager.py import-sources` directly.+> Generate-PPTX intake stage. Run before SKILL.md Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document + image folder, both shaped to feed `project_manager.py import-sources` directly.-This workflow is **independent**: it owns the source-acquisition step when no file exists; subsequent SKILL.md steps proceed normally with the produced materials as input.+This stage is **context-independent**: it owns source acquisition when no file exists; subsequent SKILL.md steps proceed normally with the produced materials as input.## When to Run| User-supplied input | Action ||---|---|-| Topic name only (e.g. "做一个关于宫崎骏的 PPT") | Run this workflow |-| Requirement description without facts (e.g. "介绍我们公司新产品") | Run this workflow |+| Topic name only (e.g. "做一个关于宫崎骏的 PPT") | Run this stage before main Step 1 |+| Requirement description without facts (e.g. "介绍我们公司新产品") | Run this stage before main Step 1 || ≥1 page of substantive content already in chat | Skip — feed chat content into SKILL.md Step 1 directly || Source file attached (PDF / DOCX / URL / Markdown) | Skip — go to SKILL.md Step 1 source converter |diff --git a/skills/ppt-master/workflows/verify-charts.md b/skills/ppt-master/workflows/stages/verify-charts.mdsimilarity index 95%rename from skills/ppt-master/workflows/verify-charts.mdrename to skills/ppt-master/workflows/stages/verify-charts.mdindex 8c6f215b..87eb82b0 100644--- a/skills/ppt-master/workflows/verify-charts.md+++ b/skills/ppt-master/workflows/stages/verify-charts.md@@ -1,12 +1,12 @@----description: Verify chart coordinates against the design spec using svg_position_calculator.py+description: Conditional quality-gate stage for chart coordinate verification.----# Verify Charts Workflow+# Verify Charts Stage-> Standalone post-generation step. Run after a deck containing data charts has finished SVG generation, before post-processing & export. Catches the 10–50 px coordinate errors AI models routinely introduce when mapping data to pixel positions.+> Conditional Generate-PPTX quality stage. Run after a deck containing data charts has finished SVG generation, before post-processing & export. Catches the 10–50 px coordinate errors AI models routinely introduce when mapping data to pixel positions.-This workflow is **independent**: it reads `design_spec.md` and the generated SVGs, then runs the calculator script — no upstream conversation context required. Safe to invoke in a fresh session.+This stage is **context-independent**: it reads `design_spec.md` and the generated SVGs, then runs the calculator script — no upstream conversation context required. Safe to invoke in a fresh session.## When to Run@@ -48,7 +48,7 @@ P11 11_share_split.svg type=pie mode=direct-calcP15 15_pareto.svg type=pareto mode=decomposable-calc```-If §VII is absent (legacy project / free-structure deck), skip this workflow and report: "design_spec.md has no §VII — chart pages cannot be enumerated authoritatively, verify-charts skipped". Do NOT fall back to guessing from SVG content; that reintroduces the silent-skip failure this workflow was built to eliminate.+If §VII is absent (legacy project / free-structure deck), skip this stage and report: "design_spec.md has no §VII — chart pages cannot be enumerated authoritatively, verify-charts skipped". Do NOT fall back to guessing from SVG content; that reintroduces the silent-skip failure this stage was built to eliminate.If the filtered list is empty, output `verify-charts: spec declares no data-driven chart geometry, nothing to verify` and stop.@@ -60,7 +60,7 @@ For each page in the Step 1 list:1. Read `<project_path>/svg_output/<page>.svg`.2. Locate the plot-area definition:- - Preferred: `<!-- chart-plot-area: ... -->` marker placed by Executor (see [executor-base.md §3.1](../references/executor-base.md)). Read coordinates directly.+ - Preferred: `<!-- chart-plot-area: ... -->` marker placed by Executor (see [executor-base.md §3.1](../../references/executor-base.md)). Read coordinates directly.- If missing: derive the plot area from the SVG's axis lines (rectangular charts) or center/radius elements (radial charts). Then **add the marker back to the SVG** so future runs are not paying this cost again.3. Read the data series from the SVG's `<text>` label/value elements.4. **Read axis tick labels for every axis-based chart.** Locate the `<text>` elements along the value axis — X-axis labels for horizontal bars, Y-axis labels for vertical bars, and Y-axis labels for line-like charts. Extract the first and last tick values to determine the axis range (e.g. `0%` to `120%` → range `0,120`). Pass this range as `--value-range`, `--y-range`, or `--x-range` as appropriate. Radar uses `--max-value` instead of a range: read the outermost ring's tick value and pass it as `--max-value`. If the SVG has no explicit tick labels (data labels only, no grid), omit the range and let the calculator auto-normalize — but flag the receipt as `scale=auto (no ticks)`.@@ -256,7 +256,7 @@ verify-charts: 19_flow.svg | type=sankey | mode=manual-verify | link widths cons## After verification-Continue with post-processing & export ([SKILL.md Step 7](../SKILL.md)):+Continue with post-processing & export ([SKILL.md Step 7](../../SKILL.md)):```bashpython3 skills/ppt-master/scripts/total_md_split.py <project_path>diff --git a/skills/ppt-master/workflows/visual-review.md b/skills/ppt-master/workflows/stages/visual-review.mdsimilarity index 90%rename from skills/ppt-master/workflows/visual-review.mdrename to skills/ppt-master/workflows/stages/visual-review.mdindex f275c34e..c9bf07a6 100644--- a/skills/ppt-master/workflows/visual-review.md+++ b/skills/ppt-master/workflows/stages/visual-review.md@@ -1,14 +1,14 @@----description: Per-page rubric-based visual self-review via parallel subagents. Run after Executor, before post-processing.+description: Optional quality-gate stage for per-page rubric-based visual review.----# Visual Review Workflow+# Visual Review Stage-> Standalone post-generation step. Goal: reduce human iteration by letting AI subagents visually self-check each rendered slide against a fixed rubric and apply atomic position/spacing fixes.+> Optional Generate-PPTX quality stage. Goal: reduce human iteration by letting AI subagents visually self-check each rendered slide against a fixed rubric and apply atomic position/spacing fixes.>> Reads `<project>/svg_output/<page>.svg` and a pre-rendered PNG of each slide, then either applies a fix or flags `needs_human`. **Never touches** brand decisions, layout structure, or other files.>-> This workflow is **independent** — invokable in a fresh chat session with only `<project_path>` as input. No upstream conversation context required.+> This stage is **context-independent** — invokable in a fresh chat session with only `<project_path>` as input. No upstream conversation context required.## Positioning@@ -29,7 +29,7 @@ For decks containing data charts, run [`verify-charts`](./verify-charts.md) firs- The project has no `svg_output/<page>.svg` files yet — finish Executor first- `svg_quality_checker.py` has not been run or has failed — fix static violations first-- User has already applied annotations via `live-preview` workflow and is in a fixed-edit loop — describe changes directly, do not re-trigger rubric+- User has already applied annotations via the `live-preview` stage and is in a fixed-edit loop — describe changes directly, do not re-trigger rubric- The user has not asked for it — do not auto-invoke based on inferred model capability or deck size---@@ -92,7 +92,7 @@ The orchestrator prompt must be self-contained and is the **single** place where- Batch size `K` (default 5; raise to 10 for token-sensitive runs on large decks, lower to 3 for high-fidelity short decks — see rubric §6.1)- Iteration budget per page (default 1; 2 only for high-stakes / final-cut runs — see [Appendix: Iteration loop](#appendix-iteration-loop-opt-in))- Path to the rubric: `skills/ppt-master/references/visual-review.md`-- Dispatch contract reference: rubric [§6](../references/visual-review.md#6-dispatch--messaging-contract) (batched parallel spawn, self-contained prompts, mandatory `SendMessage` on idle, anonymous-name tolerance)+- Dispatch contract reference: rubric [§6](../../references/visual-review.md#6-dispatch--messaging-contract) (batched parallel spawn, self-contained prompts, mandatory `SendMessage` on idle, anonymous-name tolerance)- Subagent forbid list: do not edit any other page, `design_spec.md`, `spec_lock.md`, `animations.json`, `image_prompts.json`, or `images/`**Host compatibility**: `TeamCreate` and `SendMessage` are Claude-Code-specific multi-agent primitives. On hosts without those primitives (Cursor, VS Code + Copilot, Codebuddy, etc.) the main agent processes batches sequentially — same partitioning, same per-batch prompts, no parallel dispatch. Token savings from shared fixed inputs still apply; wall-clock time grows roughly N/K-fold.@@ -131,7 +131,7 @@ For each row in the table:If `brand_review.json` is non-empty, that's a single decision applied across the deck (e.g., bump footer text color from `#6E7681` to `#8B949E` — one change, every page benefits). Do this once, then optionally re-run visual-review for the affected pages only.-After the table is clean, continue to post-processing per [`SKILL.md`](../SKILL.md) Step 7:+After the table is clean, continue to post-processing per [`SKILL.md`](../../SKILL.md) Step 7:```bashpython3 skills/ppt-master/scripts/total_md_split.py <project_path>@@ -143,12 +143,12 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>## Notes & invariants-- **Single source of truth for rules**: [`references/visual-review.md`](../references/visual-review.md). This workflow file is just the orchestration — never restate or paraphrase rules here.+- **Single source of truth for rules**: [`references/visual-review.md`](../../references/visual-review.md). This stage file is just the orchestration — never restate or paraphrase rules here.- **Concurrency**: `visual_review.py` serializes renders via `<project>/.preview/.render.lock`. Subagents must never call the renderer directly without the lock.- **Iteration budget**: default 1 iteration. Bumping to 2 doubles render cost and roughly triples token cost. Only worth it for high-stakes / final-cut decks.- **Don't-touch (rubric §3)** is hard-enforced by subagents. If you want the subagent to e.g. change a brand color, that is **out of scope** — make the change manually first, then re-render & re-review.- **Backups**: every modified SVG has a `.review/backup/<page>.iter<N>.svg` rollback anchor. Restore by `cp`.-- **The rubric is not the designer**: it catches collisions, drift, and rhythm errors — it does not improve a fundamentally weak layout. If 80%+ of pages come back `needs_human`, the design spec or the executor's choice of layout patterns is the root cause, not this workflow.+- **The rubric is not the designer**: it catches collisions, drift, and rhythm errors — it does not improve a fundamentally weak layout. If 80%+ of pages come back `needs_human`, the design spec or the executor's choice of layout patterns is the root cause, not this stage.- **Playwright output discipline**: when an agent uses the playwright MCP tool `browser_take_screenshot` directly (outside the `visual_review.py` script), the `filename` parameter is resolved against the CWD (typically the repo root) — passing a bare relative path will create stray directories inside the repository. Always pass an absolute path:- One-off probe / ad-hoc inspection → `/tmp/probe-<topic>-<n>.png`- Project artifact (replaces what the script would have produced) → `<project_path>/.preview/<page>.png` (absolute)@@ -160,7 +160,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>## Appendix: Iteration loop (opt-in)-Default behavior is single-iteration review: one scan, fix in place, write the report. The full iteration loop in [`references/visual-review.md`](../references/visual-review.md) §4.1 supports:+Default behavior is single-iteration review: one scan, fix in place, write the report. The full iteration loop in [`references/visual-review.md`](../../references/visual-review.md) §4.1 supports:1. Iteration 1: scan + fix2. Re-render via `visual_review.py --pages <token>`diff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.mdindex 4c71e382..aff1e55a 100644--- a/skills/ppt-master/workflows/template-fill-pptx.md+++ b/skills/ppt-master/workflows/template-fill-pptx.md@@ -1,19 +1,19 @@----description: PPTX template fill workflow — use a native PowerPoint template deck, select fitting pages, and fill new material back without SVG conversion+description: Fill Native PPTX route — use a native PowerPoint template deck, select fitting pages, and fill new material back without SVG conversion----# Template Fill (PPTX) Workflow+# Fill Native PPTX Route-> Run when the user provides a raw `.pptx` template plus new content / a new topic and asks to generate a `.pptx` from that template. Typical requests include "use this PPT template to generate a PPTX", "fill this deck with the new content", "fill this back into the template", "replace the copy in this PowerPoint", or "keep the original PowerPoint pages and swap in this material". This workflow treats the existing `.pptx` as a native slide library and produces a new `.pptx` by selecting, cloning, and patching source slides.+> Run when the user provides a raw `.pptx` template plus new content / a new topic and asks to generate a `.pptx` from that template. Typical requests include "use this PPT template to generate a PPTX", "fill this deck with the new content", "fill this back into the template", "replace the copy in this PowerPoint", or "keep the original PowerPoint pages and swap in this material". This route treats the existing `.pptx` as a native slide library and produces a new `.pptx` by selecting, cloning, and patching source slides.-This workflow is **independent** from the SVG generation pipeline. It treats the source PPTX as a native template / slide library, keeps the original PowerPoint design intact, and writes a new `.pptx` by cloning selected source slides and replacing text directly in OOXML.+This route is **independent** from the SVG generation pipeline. It treats the source PPTX as a native template / slide library, keeps the original PowerPoint design intact, and writes a new `.pptx` by cloning selected source slides and replacing text directly in OOXML.-**Boundary against template-based generation**: run this workflow for raw PPTX template + generated PPTX requests. Skip this workflow only when the user explicitly wants a reusable template package, SVG-derived template roster, or SVG-generated deck that can freely select / repeat / skip / adapt template pages. In that case, they must run [`create-template.md`](./create-template.md) first and then provide the generated template directory path to the main pipeline.+**Boundary against template-based generation**: run this route for raw PPTX template + generated PPTX requests. Skip this route only when the user explicitly wants a reusable template workspace or an SVG-generated deck that can freely select / repeat / skip / adapt template pages. In that case, they must run [`create-template.md`](./create-template.md) first and then provide the generated workspace root to Generate PPTX.| User wants | Route ||---|---|-| Generate a PPTX from a raw PPTX template | This workflow |-| Directly edit / fill cloned PPTX slides | This workflow |+| Generate a PPTX from a raw PPTX template | This route |+| Directly edit / fill cloned PPTX slides | This route || Create a reusable design asset from the PPTX | `create-template` || Generate a new PPT from a reusable template package | Main pipeline Step 3 with the explicit template directory path || Generate through the SVG pipeline directly from a raw PPTX "template" | Not allowed; create the template package first |@@ -31,9 +31,9 @@ Recognize requests that combine an existing PowerPoint template with new content| Native PPT template fill | "Use this PowerPoint template for this content and fill the slides directly" || Direct wording | "Fill this deck with the new content" |-**Hard rule**: Do not run `pptx_to_svg.py`, `pptx_template_import.py`, `finalize_svg.py`, or `svg_to_pptx.py` for this workflow. SVG conversion is for presentation generation / template creation; this workflow is direct PowerPoint editing.+**Hard rule**: Do not run `pptx_to_svg.py`, `pptx_template_import.py`, `finalize_svg.py`, or `svg_to_pptx.py` for this route. SVG conversion is for presentation generation / template creation; this route is direct PowerPoint editing.-**Deterministic routing rule**: do not ask a route-choice question for raw PPTX template + generated PPTX requests; route them here. If the user asks for SVG/template-package generation from a raw PPTX, state that `create-template` must run first and stop this workflow until they provide the generated template directory path.+**Deterministic routing rule**: do not ask a route-choice question for raw PPTX template + generated PPTX requests; route them here. If the user asks for SVG/template-workspace generation from a raw PPTX, state that `create-template` must run first and stop this route until they provide the generated workspace root.---@@ -203,7 +203,7 @@ The plan structure:| Short text | For labels / chapter names / directory items, fit the slot's visual capacity from geometry and font size; do not rely on old placeholder length alone || Body text | May be moderately freer than the original, but keep paragraph count, visual width, and information density near the slot's geometry capacity || Empty slots | Use `scaffold --include-empty` only when a real placeholder is empty in the source deck |-| Native tables | Keep the original table row and column count; edit ordinary cells or a merge anchor only. A merge slave is not visible and is rejected by both `check-plan` and `apply`. This workflow never changes table structure. |+| Native tables | Keep the original table row and column count; edit ordinary cells or a merge anchor only. A merge slave is not visible and is rejected by both `check-plan` and `apply`. This route never changes table structure. || Native charts | Each series `values` list must match the category count. Single-plot classic charts whose every series uses `c:cat/c:val` are editable; analyzer/checker preflight the structure and the runtime writer revalidates the actual chart XML before mutation. || Chart edit boundary | A single classic plot is editable when every series uses `c:cat/c:val`, including stock, 3D, surface, and other classic plot types. Date-axis and multi-level categories are accepted with a warning because replacement categories are flattened to one level. Scatter, bubble, ChartEx/unknown frames, multi-plot/combo charts, missing-series charts, and non-`c:cat/c:val` data models are rejected. Use beautify / main pipeline to redraw unsupported charts, or leave the native chart untouched. || Facts | Every substantive claim must come from the user material |@@ -288,7 +288,7 @@ The script:| Adds timestamp to PPTX filename | Matches the main SVG-to-PPTX export convention || Drops orphaned source parts | Output carries only the selected pages and the layouts / media / charts they still reference (reachability prune) |-**Animation policy**: Template-fill preserves each cloned slide's existing object animation XML (the SVG pipeline's generated object animation defaults are not applied here). Page transitions are the one motion layer this workflow writes directly, and `apply` adds a `fade` transition by default; change it with `apply --transition` / a per-slide `transition` field, or opt out with `--transition keep` (preserve source) or `--transition none`. `keep` preserves direct and `mc:AlternateContent` transition effects without converting unknown effects to `fade`; explicit replacement removes the old logical carrier before writing one new carrier. If the user asks to change object-level animation order / timing / effects, treat that as a separate direct-PPTX animation customization task.+**Animation policy**: Template-fill preserves each cloned slide's existing object animation XML (the SVG pipeline's generated object animation defaults are not applied here). Page transitions are the one motion layer this route writes directly, and `apply` adds a `fade` transition by default; change it with `apply --transition` / a per-slide `transition` field, or opt out with `--transition keep` (preserve source) or `--transition none`. `keep` preserves direct and `mc:AlternateContent` transition effects without converting unknown effects to `fade`; explicit replacement removes the old logical carrier before writing one new carrier. If the user asks to change object-level animation order / timing / effects, treat that as a separate direct-PPTX animation customization task.---@@ -348,4 +348,4 @@ If the extracted text is correct but visual overflow is likely, reduce the text| Edit chart formatting / axes / legend layout | Not in v1 || Edit or generate native SmartArt | Not supported; regenerated visual routes use ordinary editable shapes || Automatic visual overflow detection | Not in v1; use text-capacity judgment from the library slots |-| Material-divergence reshaping (§c content strategy) | Not applicable — this workflow fills text into existing slots, it does not author an outline from a source, so the main pipeline's `content_divergence` free-text field has no role here |+| Material-divergence reshaping (§c content strategy) | Not applicable — this route fills text into existing slots, it does not author an outline from a source, so the Generate PPTX `content_divergence` free-text field has no role here |