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): isolate generate route from skill entry
hugohe3a5c90dc88587
diff --git a/AGENTS.md b/AGENTS.mdindex 723b7699..4ac81b2f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -2,19 +2,17 @@This file is the project entry point for general AI agents.-**You MUST read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before any PPT generation task or repo modification.** This repository exists to generate presentations; SKILL.md is the authoritative workflow that owns project creation, role switching, serial execution, quality gates, post-processing, export, and every per-step command. The rest of this file only points to where related material lives — it never substitutes for SKILL.md.+**You MUST read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before any PPT generation task or repo modification.** It owns global execution discipline and points to the route selector; after routing, the selected route authority owns its steps, gates, and commands. The rest of this file only points to where related material lives.## Project Overview-PPT Master is an AI-driven presentation generation system. Multi-role collaboration (Strategist → Image_Generator → Executor) converts source documents (PDF/DOCX/URL/Markdown) into natively editable PPTX with real PowerPoint shapes (DrawingML).--**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist confirmation stage → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export PPTX`+PPT Master is an AI-driven presentation generation system. Multi-role collaboration (Strategist → Image_Generator → Executor) converts source documents (PDF/DOCX/URL/Markdown) into natively editable PPTX with real PowerPoint shapes (DrawingML). The Generate route owns its pipeline sequence.**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 the [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) intake stage before SKILL.md Step 1.+- Topic-only requests run the [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) intake stage before [`generate-pptx`](skills/ppt-master/workflows/generate-pptx.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. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.+- Raw PPTX cannot be consumed as a Generate 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/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.@@ -39,7 +37,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat## Command Quick Reference-Convenience summary only — full workflow in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).+Convenience summary only — route selection starts in [`SKILL.md`](skills/ppt-master/SKILL.md); the full SVG-generation workflow is [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md).```bash# Source content conversion@@ -86,17 +84,14 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path> #python3 skills/ppt-master/scripts/native_enhance_pptx.py init <PPTX_file> --name <project_slug>python3 skills/ppt-master/scripts/native_enhance_pptx.py validate <project_path>python3 skills/ppt-master/scripts/native_enhance_pptx.py apply <project_path>--# Post-processing pipeline: run sequentially, one command at a time-python3 skills/ppt-master/scripts/total_md_split.py <project_path>-python3 skills/ppt-master/scripts/finalize_svg.py <project_path>-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>-# Mergeable dy-stacked paragraph blocks collapse into one editable text frame by default; add --no-merge to keep every line as its own frame (strict line fidelity). See SKILL.md Step 7.3.```+For serial post-processing and export, follow [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md) Step 7 exactly. See [`svg-pipeline.md`](skills/ppt-master/scripts/docs/svg-pipeline.md) for tool flags and behavior.+## Core Directories-- `skills/ppt-master/SKILL.md` — main workflow authority.+- `skills/ppt-master/SKILL.md` — global discipline and route-entry authority.+- `skills/ppt-master/workflows/generate-pptx.md` — Generate PPTX Step 1–7 authority.- `skills/ppt-master/references/` — role definitions and technical specifications.- `skills/ppt-master/scripts/` — runnable tool scripts.- `skills/ppt-master/scripts/docs/` — topic-focused script docs.diff --git a/docs/faq.md b/docs/faq.mdindex f707ac4a..512eece3 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -195,7 +195,7 @@ Default recommendation: **continuous one-shot generation**. 10–15 page decks fOnly when signals are heavy (≥ 18 pages, thick source material, or `topic-research` ran with substantial web-fetch accumulation) does the AI surface an optional **split mode** hint at the Strategist phase: the planning session (Strategist confirmation stage + image acquisition) ends in the current chat; you open a fresh chat window and type `resume execution projects/<project_name>` to enter the execution session (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there.-Split mode is a **compromise** — it pays ~6K tokens (re-reading SKILL.md) to drop 60–200K of planning-session noise, then reuses the freed budget in the execution session to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode.+Split mode is a **compromise** — the fresh session pays the fixed cost of reloading the Generate authority and required execution references, but drops the planning-session noise and reuses the freed budget to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode.## Q: Can I preview or fix individual pages before the full export?diff --git a/docs/getting-started.md b/docs/getting-started.mdindex fa6ada53..b42db678 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -125,7 +125,7 @@ The [FAQ](./faq.md) is the living troubleshooting reference — continuously upd| Situation | First thing to try ||---|---|-| The AI drifts or forgets a step | Ask it to re-read `skills/ppt-master/SKILL.md`. |+| The AI drifts or forgets a step | Ask it to re-read `skills/ppt-master/SKILL.md`, `skills/ppt-master/workflows/routing.md`, and the selected route authority. || Visual quality disappoints | Switch to a large-context Claude model + `gpt-image-2` — the harness sets the floor, the model sets the ceiling. || Text overflows or elements overlap | Re-run that page, or fix it in live preview; see the [FAQ](./faq.md). || No image-generation API key | Zero-config web search still works as a fallback; see the [FAQ](./faq.md). |diff --git a/docs/roadmap.md b/docs/roadmap.mdindex d838b794..6483f926 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -39,7 +39,7 @@ Structural capability growth since March 2026. Single flags and incremental poli- **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- **AI image `custom` escape hatch** — `rendering` / `palette` / hero composition each accept `custom` + a one-paragraph `*_behavior` prose, replacing the false "default to vector-illustration / cool-corporate" fallback; end-to-end contract spans [`image-renderings/_index.md`](../skills/ppt-master/references/image-renderings/_index.md) §1.5, [`image-palettes/_index.md`](../skills/ppt-master/references/image-palettes/_index.md) §2, Strategist h.5 hard-rule (≤1 custom per dimension; one candidate may carry both), spec_lock fields, and Image_Generator Step 2 consumption branch-- **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"+- **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; [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 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/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)diff --git a/docs/technical-design.md b/docs/technical-design.mdindex fd6138f7..89b23be9 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -256,7 +256,7 @@ Two converter design choices still shape the system:| `exports/` | timestamped native PPTX deliverables || `backup/<timestamp>/` | frozen `svg_output/` snapshots written by default export |-The CLI still supports three source-import modes: `--move`, `--copy`, and an automatic default that moves repo-local files but copies external files. The production workflow in `SKILL.md` deliberately tightens that: agents must call `import-sources ... --move` so every source artifact and generated intermediate enters `sources/` and the working root stays clean. The script-level default exists for ad hoc CLI safety; the workflow-level contract is stricter so AI runs are reproducible and auditable.+The CLI still supports three source-import modes: `--move`, `--copy`, and an automatic default that moves repo-local files but copies external files. The Generate PPTX production workflow in [`workflows/generate-pptx.md`](../skills/ppt-master/workflows/generate-pptx.md) deliberately tightens that: agents must call `import-sources ... --move` so every source artifact and generated intermediate enters `sources/` and the working root stays clean. The script-level default exists for ad hoc CLI safety; the workflow-level contract is stricter so AI runs are reproducible and auditable.---@@ -354,7 +354,7 @@ PPT Master uses **role switching within one main agent** rather than parallel su## Execution Discipline-The 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.+Generate execution is governed by [`workflows/generate-pptx.md`](../skills/ppt-master/workflows/generate-pptx.md), which owns Step 1–7 and the generation-specific rules; [`SKILL.md`](../skills/ppt-master/SKILL.md) owns only global execution discipline and the mandatory handoff to `routing.md`. Together, these rules may 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. They 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.Global stop/continue policy is authoritative in [`failure-recovery.md`](../skills/ppt-master/workflows/governance/failure-recovery.md); its concrete recovery matrix and resume pointers currently cover Generate PPTX. This section does not duplicate those rules.@@ -371,7 +371,7 @@ The Strategist phase produces two artifacts that look redundant but serve differ- `design_spec.md` — human-readable narrative; the "why" of the deck (communication intent, audience outcome, narrative / template / visual rationale, page outline)- `spec_lock.md` — machine-readable execution contract; the compact communication trace plus the exact values Executor must literally use (HEX colors, font stacks, icon library, image resources, and structure mappings)-Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — the SKILL.md mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.+Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — [Generate PPTX Step 6](../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` references that decide which execution rule files are loaded. `template_reuse_scope: mirror|layout` projects additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.@@ -590,7 +590,7 @@ The tempting simplifications below have explicit costs. Treat them as negative c## Routes and Supporting Runbooks-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.+[`workflows/index.md`](../skills/ppt-master/workflows/index.md) is a maintainer-only inventory and does not enter the task-loading chain. Runtime route selection is authoritative 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.Supporting files stay separate only to keep route contracts focused and load optional context on demand:diff --git a/docs/templates-architecture.md b/docs/templates-architecture.mdindex 73468b79..3d32d1b0 100644--- a/docs/templates-architecture.md+++ b/docs/templates-architecture.md@@ -320,7 +320,7 @@ These indexes cover library scope only. A project-root workspace is intentionall### Override priority (implicit dispatch)-When the user supplies a set of paths in their initial message, Step 3 fuses them into `<project>/templates/design_spec.md` per the table below:+When the user supplies a set of explicit workspace-root paths, Step 3 fuses them into `<project>/templates/design_spec.md` per the table below:| User paths | Fusion behavior ||---|---|@@ -384,9 +384,9 @@ This lets both AI and humans trace which segment came from where.----## 5. Relationship with SKILL.md Step 3+## 5. Relationship with Generate PPTX Step 3-**Trigger rule stays path-based** — an explicit workspace-root path is still required ([SKILL.md Step 3](../skills/ppt-master/SKILL.md#step-3-template-option)), 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**:+**Trigger rule stays path-based** — an explicit workspace-root path is still required (see [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option)), 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) ||---|---|diff --git a/docs/templates-guide.md b/docs/templates-guide.mdindex e5c5c43f..aabe258b 100644--- a/docs/templates-guide.md+++ b/docs/templates-guide.md@@ -43,7 +43,7 @@ stay separate.The two rules that prevent most mistakes:1. Supply the **workspace root**, not its `templates/` subdirectory and not a bare template name.-2. Put the explicit workspace path in the initial generation request. The only exception is a Create Template run that immediately hands its validated workspace to Generate PPTX in the same conversation.+2. Provide the explicit workspace path before [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option). A Create Template run may instead hand its validated workspace directly to Generate PPTX in the same conversation.---@@ -51,17 +51,17 @@ The two rules that prevent most mistakes:### How to trigger-The workflow **defaults to free design** — it will not ask whether you want a template and will not proactively suggest one. Templates are opt-in by **explicit directory path** only: name the path in your initial message.+The workflow **defaults to free design** — it will not ask whether you want a template and will not proactively suggest one. Templates are opt-in by **explicit directory path** only: provide the path before Generate PPTX reaches Step 3.### How to enter the template flow-Send the Brand/Layout/Deck workspace root in your initial message. Anywhere in the sentence is fine; the path just has to be unambiguous:+Send the Brand/Layout/Deck workspace root in chat before Generate PPTX reaches Step 3. Anywhere in the sentence is fine; the path just has to be unambiguous:> "use this template: `skills/ppt-master/templates/layouts/presentation_core/`" ✅> "use last deck's template: `projects/last_deck/`" ✅> "make a product introduction with `/Users/me/Desktop/our_brand_v3/`" ✅-For 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.+For 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; user-supplied paths and current-conversation Create Template handoffs are the two valid triggers.> **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.@@ -245,7 +245,7 @@ After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-maste| `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.+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 [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option): provide the workspace root before Step 3 runs, 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.When a deck/layout template is selected, the Strategist confirmation stage asks how it should be used:diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex a97a7ed7..441e99a8 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -197,7 +197,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t只有信号偏重的场景(页数 ≥ 18 / 源材料很厚 / 走过 topic-research 累积大量 web 抓取),AI 才会在策略师阶段给出**拆分模式**的可选提示:规划会话(策略师确认阶段 + 图片获取)结束后停止当前对话;你新开聊天窗口,输入 `继续生成 projects/<项目名>` 进入执行会话(SVG 生成 + 导出)。新会话从磁盘重新加载 `design_spec` / `spec_lock` / `sources` / `images` 继续执行。-两段式是**折中方案**——付出约 6K tokens 的 SKILL.md 重读成本,换得 60–200K 的规划会话噪声丢弃,并把节省下来的窗口空间用于执行会话主动重读 `sources/` 做内容增稠。**信号正常时不需要**,提示也不会出现;用户随时可以忽略提示,走默认连续模式。+两段式是**折中方案**——新会话需付出重载 Generate 权威文档与必需执行引用的固定成本,但可丢弃规划会话噪声,并把节省下来的窗口空间用于主动重读 `sources/` 做内容增稠。**信号正常时不需要**,提示也不会出现;用户随时可以忽略提示,走默认连续模式。## Q: 能在导出前预览或修正某一页吗?diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.mdindex 44be5551..a2365121 100644--- a/docs/zh/getting-started.md+++ b/docs/zh/getting-started.md@@ -123,7 +123,7 @@ PPT Master 最初是纯对话设计;可视化编辑是在很多用户提出后| 情况 | 先试这个 ||---|---|-| AI 跑偏或漏了步骤 | 让它重新读 `skills/ppt-master/SKILL.md`。 |+| AI 跑偏或漏了步骤 | 让它重新读 `skills/ppt-master/SKILL.md`、`skills/ppt-master/workflows/routing.md` 和已选路线的权威文档。 || 视觉质量不理想 | 换成大上下文 Claude 模型 + `gpt-image-2`——harness 决定下限,模型决定上限。 || 文字溢出或元素重叠 | 重跑那一页,或用实时预览修;详见 [FAQ](./faq.md)。 || 没有生图 API key | 零配置的网络图片搜索仍可作为兜底;见 [FAQ](./faq.md)。 |diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex b5e68b04..55fc2086 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -39,7 +39,7 @@- **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 结构扩展性」- **AI 图 `custom` 兜底出口** — `rendering` / `palette` / hero 构图三处允许声明 `custom` + 一段 `*_behavior` prose,替换原"找不到匹配就硬塞 vector-illustration / cool-corporate"的假兜底;端到端契约:[`image-renderings/_index.md`](../../skills/ppt-master/references/image-renderings/_index.md) §1.5 + [`image-palettes/_index.md`](../../skills/ppt-master/references/image-palettes/_index.md) §2 + Strategist h.5 hard-rule(每维 ≤1 custom,单候选可双 custom)+ spec_lock 字段 + Image_Generator Step 2 消费分支-- **Template 架构三分类收口**([`docs/zh/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck 三独立目录 + 每类独立 schema + 段级合成 + git-style 冲突解决;SKILL.md Step 3 按 kind 分支处理,触发规则仍是「显式路径才触发」+- **Template 架构三分类收口**([`docs/zh/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck 三独立目录 + 每类独立 schema + 段级合成 + git-style 冲突解决;[Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 按 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/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 中如实再现)。重新导出仍由对话触发;画布上的缩放手柄尚未实现(缩放走几何输入框)diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex fb69d02b..2c065883 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -257,7 +257,7 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可| `exports/` | 带时间戳的 native PPTX 交付物 || `backup/<timestamp>/` | 默认导出时写入的冻结 `svg_output/` 快照 |-CLI 仍支持三种导入模式:`--move`、`--copy`,以及“仓库内文件 move、仓库外文件 copy”的自动默认。`SKILL.md` 中的生产工作流会刻意收紧这一点:agent 必须调用 `import-sources ... --move`,让所有源文件和中间产物进入 `sources/`,保持工作根目录干净。脚本级默认服务临时 CLI 使用的安全性;工作流级契约更严格,是为了让 AI 执行具备可复现和可审计性。+CLI 仍支持三种导入模式:`--move`、`--copy`,以及“仓库内文件 move、仓库外文件 copy”的自动默认。[`workflows/generate-pptx.md`](../../skills/ppt-master/workflows/generate-pptx.md) 中的 Generate PPTX 生产工作流会刻意收紧这一点:agent 必须调用 `import-sources ... --move`,让所有源文件和中间产物进入 `sources/`,保持工作根目录干净。脚本级默认服务临时 CLI 使用的安全性;工作流级契约更严格,是为了让 AI 执行具备可复现和可审计性。---@@ -350,7 +350,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理## 执行纪律-流水线由 [`SKILL.md` § 全局执行纪律](../../skills/ppt-master/SKILL.md) 中的 10 条规则强制——那份文件是权威,规则住在那里。它们看起来很官僚,但存在的理由是:LLM 默认行为是“让我在这一 turn 里把整个问题搞定”,而这恰好是串行流水线最不该有的形状——串行流水线要求每一步的输出都是有界、过 checkpoint、被下一步消费的。这套规则共同关闭了实际反复出现的失败模式:乱序执行、AI 代为做用户设计决策、跨阶段打包、前置条件未满足、投机预先准备、子代理上下文丢失、分批漂移、长 deck 色彩字体漂移、脚本批量生成 SVG 漂移,以及路由歧义。+Generate 执行以 [`workflows/generate-pptx.md`](../../skills/ppt-master/workflows/generate-pptx.md) 为权威,该文档拥有 Step 1–7 与 Generate 专属规则;[`SKILL.md`](../../skills/ppt-master/SKILL.md) 只拥有全局执行纪律,以及交接到 `routing.md` 的强制入口。这些规则整体看起来很官僚,但存在的理由是:LLM 默认行为是“让我在这一 turn 里把整个问题搞定”,而这恰好是串行流水线最不该有的形状——串行流水线要求每一步的输出都是有界、过 checkpoint、被下一步消费的。它们共同关闭了实际反复出现的失败模式:乱序执行、AI 代为做用户设计决策、跨阶段打包、前置条件未满足、投机预先准备、子代理上下文丢失、分批漂移、长 deck 色彩字体漂移、脚本批量生成 SVG 漂移,以及路由歧义。全路由通用的停止 / 继续规则以 [`failure-recovery.md`](../../skills/ppt-master/workflows/governance/failure-recovery.md) 为准;其中具体故障矩阵与续跑入口目前覆盖 Generate PPTX。本节不复制这些规则。@@ -367,7 +367,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:- `design_spec.md` —— 人类可读叙述;deck 的「为什么」(沟通意图、受众变化、叙事 / 模板 / 视觉理由、页面大纲)- `spec_lock.md` —— 机器可读执行契约;包含紧凑沟通追踪,以及 Executor 必须**字面照搬**的精确值(HEX 颜色、字体栈、图标库、图片资源与结构映射)-为什么两份都要?没有 `spec_lock.md` 的话,Executor 在长 deck 里会逐页重读 `design_spec.md`,LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——SKILL.md 强制要求生成每一页前 `read_file <project>/spec_lock.md`,让数值在 20+ 页里保持字面一致。+为什么两份都要?没有 `spec_lock.md` 的话,Executor 在长 deck 里会逐页重读 `design_spec.md`,LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——[Generate PPTX Step 6](../../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) 强制要求生成每一页前 `read_file <project>/spec_lock.md`,让数值在 20+ 页里保持字面一致。这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。`template_reuse_scope: mirror|layout` 项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。@@ -586,7 +586,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu## 顶层路线与支撑文档-权威注册表是 [`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/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。用户请求只能进入其中一条;任何支撑文档都不与它们竞争。支撑文件保持拆分,只是为了收紧路线合同,并在需要时加载可选上下文:diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.mdindex 03f18a82..2717d39b 100644--- a/docs/zh/templates-architecture.md+++ b/docs/zh/templates-architecture.md@@ -282,7 +282,7 @@ Template Overview 必须写明可重复演示类型、目标受众与结果、### 合成优先级(隐式触发)-用户在第一条消息里给出一组路径,Step 3 按以下表合成 `<project>/templates/design_spec.md`:+用户给出一组显式工作区根目录路径后,Step 3 按以下表合成 `<project>/templates/design_spec.md`:| 用户路径 | 合成行为 ||---|---|@@ -339,9 +339,9 @@ AI: 你给了两个 brand,检测到段级冲突:----## 五、与 SKILL.md Step 3 的关系+## 五、与 Generate PPTX Step 3 的关系-**触发规则仍以路径为准**——仍需显式工作区根目录路径(见 [SKILL.md Step 3](../../skills/ppt-master/SKILL.md#step-3-template-option)),裸名称绝不触发。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 怎么处理**:+**触发规则仍以路径为准**——仍需显式工作区根目录路径(见 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option)),裸名称绝不触发。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 分支)||---|---|diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex 1e3cc2f6..a0e4ee1f 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -37,7 +37,7 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象最容易避免误用的两条规则:1. 提供**工作区根目录**,不要只给它的 `templates/` 子目录,也不要只写模板名。-2. 在首次生成请求里写明工作区路径。唯一例外是同一对话刚完成 Create Template,可立即把已验证工作区交给 Generate PPTX。+2. 在 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 之前明确给出工作区路径。同一对话刚完成 Create Template 时,也可直接把已验证工作区交给 Generate PPTX。---@@ -45,17 +45,17 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象### 触发方式-工作流**默认走自由设计**——不会主动问你要不要用模板,也不会基于内容主动推荐模板。模板是 opt-in 的,**只接受显式目录路径**:你在第一条消息里把模板目录的路径写出来。+工作流**默认走自由设计**——不会主动问你要不要用模板,也不会基于内容主动推荐模板。模板是 opt-in 的,**只接受显式目录路径**:在 Generate PPTX 进入 Step 3 前把模板目录路径写出来。### 怎么触发模板流程-在对话里写出 Brand/Layout/Deck 工作区根目录(位置不重要,只要明确即可):+在 Generate PPTX 进入 Step 3 前,于对话里写出 Brand/Layout/Deck 工作区根目录(位置不重要,只要明确即可):> "用这个模板做:`skills/ppt-master/templates/layouts/presentation_core/`" ✅> "用上次那个模板:`projects/last_deck/`" ✅> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅-对于当前所有模板类型,这里给的都是**模板工作区根目录**。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 会解析其中的 `templates/design_spec.md`,然后把 `templates/` 及实际存在的 `images/`、`icons/` 安装进目标项目;如果工作区本来就是该项目根目录,则原地消费,并且始终不复制 `exports/`。Deck/Layout 还会校验 structured SVG 合同。路径可以指向 `skills/ppt-master/templates/<kind>/<id>/` 下的内置库工作区、`projects/<name>/` 下的项目工作区,或其他保持同样路由的工作区。当前对话刚完成 create-template 时,可把精确的已验证工作区根目录直接交给 Step 3;用户显式提供路径与当前对话的 Create Template 交接是两种合法触发方式。> **兼容性预检:** Step 3 也接受 `design_spec.md` 与 SVG 直接位于所给根目录的平铺工作区,但这些 SVG 必须已经满足当前合同。目录平铺本身没有问题;旧的原子 placeholder、未映射 Master/Layout 等语义旧包会被拒绝。先运行 `create-template` 创建新工作区,再从该工作区生成新的 structured 页面;不会原地升级旧包。@@ -234,7 +234,7 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \| `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>/`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要被发现时才执行注册。+全局注册让模板**可被发现**——下次有人问“有哪些模板可用?”时,AI 会从索引里把它列出来。两种范围的用法相同:按 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 的规则,在 Step 3 运行前给出工作区根目录,例如 `用这个模板:skills/ppt-master/templates/layouts/<your_template_id>/` 或 `用这个模板:projects/<name>/`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要被发现时才执行注册。选择 Deck/Layout 模板后,Strategist 确认阶段会进一步询问模板的使用方式:diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 189c7e63..16fbc9b2 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -1,985 +1,50 @@---name: ppt-masterdescription: >- AI-driven multi-format SVG content generation system. Converts source documents- (PDF/DOCX/URL/Markdown) into high-quality SVG pages and exports to PPTX through- multi-role collaboration. Use when user asks to "create PPT", "make presentation",- "生成PPT", "做PPT", "制作演示文稿", or mentions "ppt-master".+ AI-driven presentation workflow for generating editable PPTX decks, creating+ reusable Brand/Layout/Deck workspaces, filling native PPTX templates, and+ enhancing finished PPTX files. Use when the user asks to create, regenerate,+ template, fill, or enhance a presentation, or mentions ppt-master.---# PPT Master Skill-> AI-driven multi-format SVG content generation system. Converts source documents into high-quality SVG pages through multi-role collaboration and exports to PPTX.+PPT Master is a routed presentation workflow. This entry owns global execution discipline and route selection only; each selected route owns its procedure.-**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist Structured Plan → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export`+## Mandatory Load Order-### SVG Page-Design Boundary+1. Read this file.+2. Read [`workflows/routing.md`](workflows/routing.md).+3. Select exactly one top-level route from the routing authority.+4. Read only that route's authority and its explicitly triggered supporting documents.-| Scope | Contract |+| Selected route | Runtime authority ||---|---|-| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. |-| Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. |-| 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. |-| 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. |+| Generate PPTX | [`workflows/generate-pptx.md`](workflows/generate-pptx.md) |+| Create Template | [`workflows/create-template.md`](workflows/create-template.md) |+| Fill Native PPTX | [`workflows/template-fill-pptx.md`](workflows/template-fill-pptx.md) |+| Enhance Native PPTX | [`workflows/native-enhance-pptx.md`](workflows/native-enhance-pptx.md) |-**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.”--> [!CAUTION]-> ## 🚨 Global Execution Discipline (MANDATORY)->-> **This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:**->-> 1. **SERIAL EXECUTION** — Steps MUST be executed in order; the output of each step is the input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met, without waiting for the user to say "continue"-> 2. **BLOCKING = HARD STOP** — Steps marked ⛔ BLOCKING require a full stop; the AI MUST wait for an explicit user response before proceeding and MUST NOT make any decisions on behalf of the user-> 3. **NO CROSS-PHASE BUNDLING** — Cross-phase bundling is FORBIDDEN. (Note: the Strategist confirmation stage in Step 4 is ⛔ BLOCKING — the AI MUST present recommendations and wait for explicit user confirmation before proceeding. Once the user confirms, all subsequent non-BLOCKING steps — design spec output, SVG generation, speaker notes, and post-processing — may proceed automatically without further user confirmation)-> 4. **GATE BEFORE ENTRY** — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step-> 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)-> 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN-> 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN-> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. Re-read the global `communication` contract, including `consumption_mode`, and use only the locked colors / fonts / icons / images — no values from memory or invented on the fly. Executor MUST also read `pptx_structure.mode`, `template_reuse_scope`, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), and `page_charts`; pair the global contract with the current §IX `Core message` + `Audience move`. `template_reuse_scope: mirror|layout` uses `mode: structured` and looks up `page_layouts` (the input template SVG), `page_pptx_layouts` (the page assignment), `pptx_masters`, `pptx_layouts` (the unique reusable roster), and `template_adherence`; `template_reuse_scope: style`, free-design, and brand-only routes use `mode: flat` and omit those sections. This rule exists to resist both purpose drift and visual drift on long decks-> 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce. **Narrow exception**: `preset_shape_svg.py` may print one deterministic stock-shape fragment to stdout after the main agent has selected its semantic role, frame, and paint. It cannot write `svg_output/`, choose layout, batch shapes, or generate a page; the main agent reads the fragment and inserts it through the normal hand-authored page edit-> 10. **FOLLOW DETERMINISTIC ROUTING RULES** — Do not add blocking routing questions when this skill defines a route. If the user request violates a route precondition, state the required prerequisite and stop that route instead of asking the user to choose around the rule. Ordinary finite options, stylistic preferences, and recoverable details are surfaced with a recommended value plus alternatives at the next existing confirmation gate.--> [!IMPORTANT]-> ## 🌐 Language & Communication Rule->-> - **Response language**: match the user's input and source materials. Explicit user override (e.g., "请用英文回答") takes precedence.-> - **User-facing option labels**: when presenting confirmations, brief proposals, choices, or finite option sets, use the user's language for labels and explanations. English enum IDs / file fields may appear in parentheses for precision, but never rely on English-only labels such as `deck`, `layout`, `mirror`, or `fidelity` without a localized explanation.-> - **Template format**: `design_spec.md` MUST follow its original English template structure (section headings, field names) regardless of conversation language. Content values may be in the user's language.--> [!IMPORTANT]-> ## 🔌 Compatibility With Generic Coding Skills->-> - `ppt-master` is a repository-specific workflow, not a general application scaffold-> - Do NOT create `.worktrees/`, `tests/`, branch workflows, or generic engineering structure by default-> - On conflict with a generic coding skill, follow this skill unless the user explicitly says otherwise-> - Keep this Skill package self-contained: required workflow, reference,-> script, and template documentation MUST resolve inside this Skill directory;-> repository-level documents may link into the package, but package files-> MUST NOT depend on them--## Rule Strength Labels--| Label | Meaning |-|---|---|-| `MUST` | Required behavior; violation is workflow failure |-| `MUST NOT` | Forbidden behavior |-| `DEFAULT` | Used when the user has not specified otherwise |-| `OPTIONAL` | Run only when explicitly triggered or when the route says so |-| `FALLBACK` | Recovery path after the primary path fails |-| `GATE` | Required checkpoint before entering the next step |--## Cross-Cutting Authorities--| Concern | Authority | Contract |-|---|---|---|-| Main pipeline sequencing | This `SKILL.md` | Owns Step 1-7 order, gates, role switching, and mandatory commands |-| Route selection | [`workflows/routing.md`](workflows/routing.md) | Owns deterministic 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/governance/failure-recovery.md`](workflows/governance/failure-recovery.md) | Owns global stop/continue policy; its concrete matrix and resume pointers cover Generate PPTX |-| Confirm UI details | [`scripts/docs/confirm_ui.md`](scripts/docs/confirm_ui.md) | Owns schema, launcher behavior, port strategy, and chat fallback details |--## Main Pipeline Scripts--| Script | Purpose |-|--------|---------|-| `${SKILL_DIR}/scripts/source_to_md.py` | Unified source-to-Markdown dispatcher — default Step 1 entry for explicit file(s) or URL(s) |-| `${SKILL_DIR}/scripts/pptx_intake.py` | Standard PPTX intake enrichment — canvas / identity / slide geometry / tables / native chart data / SmartArt structure |-| `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage |-| `${SKILL_DIR}/scripts/icon_sync.py` | Copy chosen library icons into `<project>/icons/` at selection time; missing names reported + non-zero (re-pick gate) |-| `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis |-| `${SKILL_DIR}/scripts/latex_render.py` | LaTeX formula rendering (manifest-driven PNG assets) |-| `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) |-| `${SKILL_DIR}/scripts/slice_images.py` | Slice one AI illustration sheet into individual spot-illustration elements |-| `${SKILL_DIR}/scripts/svg_authoring_view.py` | Create a lightweight editable authoring IR bundle, model-readable summary, and tool-only provenance manifest from PPTX-imported SVGs |-| `${SKILL_DIR}/scripts/compact_svg_coordinates.py` | Compact safe model-facing page-space metadata and transform coordinates to at most two decimals |-| `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check |-| `${SKILL_DIR}/scripts/preset_shape_svg.py` | Print one compact registry-backed native PowerPoint preset `<g>` to stdout for page or template insertion |-| `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting |-| `${SKILL_DIR}/scripts/finalize_svg.py` | SVG post-processing (unified entry) |-| `${SKILL_DIR}/scripts/svg_to_pptx.py` | Export to PPTX |-| `${SKILL_DIR}/scripts/native_enhance_pptx.py` | Existing PPTX enhancement project init / validation / direct OOXML patch export |-| `${SKILL_DIR}/scripts/update_spec.py` | Propagate a `spec_lock.md` color / font_family change across all generated SVGs |--For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.--> **Windows note**: if a `python3 ...` command fails (common on python.org installs, which provide `python.exe` but not `python3.exe`), rerun the same command with `python` instead.--## Template Index--| Index | Path | Purpose |-|-------|------|---------|-| Layout templates | `${SKILL_DIR}/templates/layouts/layouts_index.json` | Query available page layout templates |-| Brand presets | `${SKILL_DIR}/templates/brands/brands_index.json` | Query available brand identity presets (color / typography / logo / voice) |-| 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>` |--## Top-Level Routes and Supporting Runbooks--**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 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 | 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 Brand, Layout, or Deck workspace from one or more PPTX/SVG files, images/PDFs, documents/websites, brand assets, direct-text requirements, or a mixed reference bundle | [`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 compatible flat-directory current-contract root with `design_spec.md`. Semantic-legacy packages are rejected and must be replaced through Create Template.--**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 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 own-Master/Layout/slot system; source visuals and assets are references, and source-Master/Layout topology is neither preserved nor distilled. `mirror` is a-native-preservation path: preserve only the source slide roster/order, visual appearance,-Master/Layout parentage and identities, placeholder type/index/bounds, native-object ownership, and supported native-shape metadata. The lossless import is-the native-payload backing store; editable SVGs under `authoring-svg/` are the-template-creation IR. Models read `authoring_summary.json` for bundle-orientation and do not load `authoring_manifest.json`; the mirror compiler-reads that machine manifest internally. Stable document-local source-references let mirror materialization reuse unchanged native payload without-putting it in model context. Mechanical normalization-may express the source facts in the current explicit SVG contract and expand-fixed-layer group wrappers into direct atoms, but it MUST NOT merge, split,-promote, demote, rename, or re-parent source structure. The IR is materialized-into validated `templates/*.svg` before export; it is not itself a release SVG-directory. Export compiles the selected contract and never infers a different-one. Mirror emits one complete page prototype per source-Slide plus one definition-only `layout_<layout_key>.svg` prototype for every-source Layout unused by those Slides. The independent Master/Layout roster then-registers the complete supported source graph without publishing synthetic-carrier pages. Stop only when required native evidence is missing or unsupported;-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?-------## Workflow--### Step 1: Source Content Processing--🚧 **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/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 the-unified dispatcher. It preserves the backend converters' existing behavior,-routes by source type, and writes the standard Markdown plus conversion profile.--| User Provides | Action |-|---------------|--------|-| PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` |-| CSV / TSV | Read directly as plain-text table source |-| Markdown | Read directly |--For PPTX sources, Step 1 converts the deck to Markdown content; after Step 2-`import-sources`, standard PPTX intake is also written to `<project>/analysis/`.-Use `source_to_md.py -t <type>` only when extension detection is ambiguous.-Default local conversion writes Markdown/profile outputs beside each source file.-Use `-o` only when a specific output file/directory is required; with multiple-inputs or directory inputs, `-o` is an output directory. Backend converter details are documented in-[`scripts/docs/conversion.md`](scripts/docs/conversion.md).--> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:-> Source conversion extracts embedded Office vector images (.emf/.wmf)-> alongside bitmap images when the source format exposes them. After `import-sources`, these land in `images/`-> together with `image_manifest.json` and are first-class assets in §VIII Image Resource List.->-> **Do NOT convert EMF/WMF to PNG.** The PPT Master pipeline preserves them as external-> references (`finalize_svg.py` skips them) and `svg_to_pptx.py` embeds them as-> PPTX-native media via `image/x-emf` / `image/x-wmf` MIME — PowerPoint renders them at full vector fidelity.-> Converting via LibreOffice/Inkscape introduces CJK font substitution drift and-> rasterization loss; the original EMF/WMF is always higher fidelity than the converted PNG.->-> Browser-based live preview cannot render EMF (will show blank) — this is expected;-> the PPTX output is the source of truth.--**✅ Checkpoint — Confirm source content is ready, proceed to Step 2.**-------### Step 2: Project Initialization--🚧 **GATE**: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid).--```bash-python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>-```--Format options must be named with concrete dimensions. Default: `ppt169` = `1280x720`, `viewBox="0 0 1280 720"`. Other examples: `ppt43` = `1024x768`, `story` = `1080x1920`, `banner` = `1920x1080`. For the full format list, see `references/canvas-formats.md`.--Import source content (choose based on the situation):--| Situation | Action |-|-----------|--------|-| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move` |-| User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |--For PPTX sources, `import-sources` automatically runs the standard intake enrichment:--```bash-python3 ${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; 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 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.--**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**+**Hard rule — selected authority only**: Do not load another top-level route's procedure after routing. Profiles, stages, governance files, and child workflows refine the selected route; they never compete with it.----### Step 3: Template Option--🚧 **GATE**: Step 2 complete; project directory structure is ready.--**Default — free design.** Proceed directly to Step 4. Do NOT query any `*_index.json` unless triggered. Do NOT ask the user. Do NOT proactively suggest, hint at, or fuzzy-match any template based on content, slug-like words, or vague style descriptions.--**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 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:--| User input contains | Step 3 action |-|---|---|-| One or more explicit template workspace paths (each resolves to `templates/design_spec.md`, or to a compatible legacy-flat root `design_spec.md`, with `kind: brand` / `kind: layout` / `kind: deck` in YAML frontmatter) | Normalize each source directory, read its `kind`, dispatch per the kind matrix below, fuse if multiple |-| Current `create-template` workflow just completed project scope and validated its exact `<project>/` workspace | Consume that single workspace in place; it cannot join multi-path fusion |-| Anything else — bare template names ("用 presentation_core"), style descriptions ("麦肯锡风格"), brand mentions ("中国电信风格"), vague intent ("想用个模板"), or silence | Skip Step 3, free design |--There 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. 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).--> Bare names ("presentation_core", "中国电信", "anthropic") do NOT trigger Step 3 even if a matching directory exists in the library. The user must give a path. AI must not "helpfully" resolve a name to a path.--> "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.+## Global Execution Discipline-> 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).+1. **Serial execution** — Follow the selected authority's steps in order. A completed non-blocking step may continue directly to the next eligible step.+2. **Blocking means stop** — At every `⛔ BLOCKING` gate, wait for explicit user confirmation. Do not decide on the user's behalf.+3. **No cross-phase bundling** — Do not combine work across an unclosed gate. Once the route's final user gate closes, later non-blocking steps may continue automatically.+4. **Gate before entry** — Verify every listed prerequisite before entering a step.+5. **No speculative execution** — Do not prepare later-phase artifacts before their owning step.+6. **Deterministic routing** — Do not add a route-choice question when [`routing.md`](workflows/routing.md) resolves the request. If a route prerequisite is missing, state it and stop that route.+7. **Owning-source recovery** — On failure, repair or regenerate the owning source artifact and resume from the route's declared pointer. Do not silently downgrade a required artifact.-#### Three template kinds+## Global Communication Rules-The architecture has three independent reference bundles. The shared package-model and workspace contract live in [`templates/README.md`](templates/README.md);-kind-specific schemas live in the corresponding template-directory README.-Summary:--| Kind | Physical dir | Contains | Frontmatter |-|---|---|---|---|-| **brand** | `templates/brands/<id>/templates/` inside a complete workspace | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` |-| **layout** | `templates/layouts/<id>/templates/` inside a complete workspace | brand-neutral structure: canvas / page structure / semantic text roles / page types / SVG roster | `kind: layout` |-| **deck** | `templates/decks/<id>/templates/` inside a complete workspace | recurring presentation application + integrated identity + structure | `kind: deck` |--Creation-mode eligibility does not weaken kind ownership: a Layout may be-created with `mirror` only when the source contract is already brand-neutral-and application-neutral. A branded or application-bearing source must be-re-authored as Layout through `standard` / `fidelity` or retained as a Deck;-removing identity or application rules is not mirror.--**Segment ownership** (governs fusion override priority):--| Segment | Sections | Owner kind on fusion |-|---|---|---|-| Identity | Color Scheme / Typography / Logo / Voice & Tone / Icon Style | brand |-| Structure | Canvas / Page Structure / semantic text roles and spatial behavior / Page Types / SVG Roster | layout |-| Application | Template Overview (recurring situations, audiences/outcomes, stable narrative/page roles, content reuse policy) | deck (no other kind writes this) |--#### Single-path dispatch--| User path's `kind` | Step 3 action |-|---|---|-| `kind: brand` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Identity is constrained by the brand; structure stays free. |-| `kind: layout` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. The workspace exposes reusable structure; Stage 2 decides from scenario fit whether to consume it as `mirror` / `layout` / `style` where legal, then confirms the complete visual system. |-| `kind: deck` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. The workspace exposes an application contract with integrated identity and structure; Stage 1 independently confirms the current communication contract, then Stage 2 derivation compares the two and decides the legal reuse scope. |--Normalize every explicit path before any write:--| Input shape | Spec / SVG source | Asset source | Install rule |-|---|---|---|---|-| Current workspace: `<root>/templates/design_spec.md` | `<root>/templates/` | Any existing `<root>/images/`, `<root>/icons/` | Map the existing portable roots to the target project's matching roots; ignore `<root>/exports/` |-| Compatible legacy-flat package: `<root>/design_spec.md` | `<root>/` | Package-local files | SVG/spec/non-bitmaps → project `templates/`; bitmaps → project `images/`; route declared icons to project `icons/` |--**Atomic install preflight (mandatory)**: Resolve source and destination paths, enumerate the complete file mapping, and reject every destination collision before copying any file. Equality between a current project workspace root and the target project root means in-place consumption and no copy. For an external single path, a collision stops Step 3 rather than overwriting. For multi-path fusion, do not copy packages sequentially: resolve segment conflicts and asset-name conflicts first, construct one final mapping, then write it once. Never use recursive copy as an implicit conflict policy.--Never infer that a flat directory has legacy Master/Layout semantics solely from packaging.--The same current-workspace routing applies to all three kinds: source/spec in `templates/`, visual assets in `images/`, imported vectors once in `icons/imported/`, other explicitly adopted icon-library namespaces under `icons/`, and on-demand review artifacts in `exports/`. Empty optional roots are omitted rather than retained with placeholder files, so a normal workspace has no `exports/` until a review file is explicitly generated. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.--When `create-template` used project output scope, its workspace root is the target project itself and all core directories are already final. Resolve both roots before copying: equality means **in-place consumption**, so skip the installation. An in-place workspace cannot participate in multi-path fusion; use external workspaces for fusion. Never place the local source under a nested `templates/local_master/` directory because the confirmation and quality gates read the project `templates/` root.--A 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, 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 first decides the selected deck/layout template's `template_reuse_scope`: `mirror`, `layout`, or `style`. `mirror` and `layout` 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. Their second axis, `template_adherence`, is `strict` or `adaptive`: strict preserves the declared Master/Layout/slot contract; adaptive keeps the template Master and may define a new Layout key when the reusable composition genuinely changes. `mirror` is offered only for a workspace whose frontmatter declares `replication_mode: mirror`; it preserves literal visuals and text-node topology. `layout` reuses the structure system without literal mirror visual protection. `style` extracts only color, typography, decoration language, and rhythm, then uses the free-design `mode: flat` route with no template structure mappings. User phrases such as “不要严格复用”, “只参考风格”, or “不必照搬版式” deterministically recommend `style` (or `layout` when they explicitly want the layout system); only “原样复刻”, “替换内容”, or “保持模板页面外观” recommends `mirror`. Brand-only projects remain on `mode: flat`.--#### Multi-path fusion--When the user gives two or more paths of **different kinds**, Step 3 fuses them into a single `<project>/templates/design_spec.md`. **Default granularity is segment-level integer replacement** — entire identity / structure / application segments are taken from the highest-priority source for that segment, no implicit field-level mixing.--Override priority by segment:--| Combination | Identity from | Structure from | Application from |-|---|---|---|---|-| brand only | brand | (free design) | (none) |-| layout only | (free design) | layout | (none) |-| deck only | deck | deck | deck |-| brand + layout | brand | layout | current project's Stage-1 communication contract; no reusable Deck application is invented |-| brand + deck | brand (overrides deck) | deck | deck |-| layout + deck | deck | compatible layout (overrides deck) | deck |-| brand + layout + deck | brand | compatible layout | deck |--Before a Layout overrides a Deck's structure, compare the Deck application-contract with the Layout's page roles, slot types, and capacity. If any required-narrative/content role cannot be represented, stop the fusion and surface a-conflict: retain the Deck structure, select another Layout, or explicitly-revise the application contract. Never keep an application promise that the-installed structure cannot satisfy.--Field-level micro-adjustment (e.g. "use anthropic brand but primary changed to #FF0000") is **not** part of Step 3 fusion — it flows into Strategist confirmation stage e–g as a normal user request.--#### Same-kind multiple paths — conflict resolution--When the user gives two paths of the **same kind** (e.g. `brands/anthropic` + `brands/google`), Step 3 surfaces a conflict prompt before fusing — like resolving a git merge conflict:--```-AI: 你给了两个 brand,检测到段级冲突:- - Color Scheme(Anthropic 橙红 vs Google 多色)- - Typography(Styrene/AnthropicSans vs GoogleSans/Roboto)- - Logo(Anthropic 标 vs Google 标)- - Voice & Tone(restrained vs friendly)- - Icon Style(stroke vs filled)-- 要 (a) 全部按 Anthropic / (b) 全部按 Google / (c) 逐段挑?-```--Rules:-- Default: no implicit ordering — every cross-source segment difference is reported as a conflict-- Only when the user picks `(c)` does AI walk through each segment one by one-- Field-level conflicts are out of scope — segment-level only-- Three or more same-kind paths are not supported — ask the user to converge to at most two--#### Fused spec provenance--When fusion happens (any multi-path case), the resulting `<project>/templates/design_spec.md` carries a provenance block immediately under its H1:--```markdown-> **Fused from:**-> - deck: `templates/decks/中国电信/` (base)-> - brand: `templates/brands/anthropic/` (identity override)-> - layout: `templates/layouts/presentation_core/` (structure override)-> - conflicts resolved: Color Scheme from anthropic(user picked a)-```--Single-path Step 3 does **not** add provenance (the source is self-evident from the copied files).--The fused frontmatter `kind` describes the resulting project capability bundle: `deck` when both identity and structure are present, `layout` when only structure is present, and `brand` when only identity is present. A project-local Brand + Layout fusion uses `kind: deck` for routing but is not thereby promoted into a reusable library Deck; Stage 1 supplies the current project's application context. Keep this field accurate; the Strategist confirmation server uses it to show template adherence only for bundles that actually own page structure.--**✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If the user supplied one or more explicit template paths, those have been copied, staged in place, or fused into `<project_path>/templates/` before advancing.**-------### Step 4: Strategist Phase (MANDATORY — cannot be skipped)--🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied or confirmed in place in the project.--First, read the role definition:-```-Read references/strategist.md-```--> ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–X section structure. See `strategist.md` Section 1.--**Artifact ownership**: fact-channel and source/derived artifact boundaries are defined in [`references/artifact-ownership.md`](references/artifact-ownership.md). This Step uses those ownership rules; it does not redefine them.--**`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Strategist confirmation stage, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table / SmartArt entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.)--**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, chart data values, and SmartArt node wording come from these (`ppt_to_md` transcribes native charts as Markdown tables and SmartArt nodes as hierarchical bullets). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table / diagram entries are a **structural digest** for outline decisions (which slides carried charts, tables, or SmartArt; chart types / series names; SmartArt layout and hierarchy) — not a second copy of the content values; do NOT also pull chart values or SmartArt wording from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract while preserving SmartArt unchanged; beautify uses it for native chart / table data and SmartArt relationships while keeping all wording from the Markdown.--**Strategist confirmation stage** (full template: `templates/design_spec_reference.md`):--⛔ **BLOCKING**: present the Strategist confirmation stage and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation gate — once the final confirmation lands, all subsequent steps proceed automatically. The default Confirm UI delivers the gate in **three stages** (communication contract → complete deck solution → resources / production; see below); the chat fallback mirrors the same staged order.--1. Communication contract — target audience; open-ended `communication_intent` (one or several purposes, with priority / sequence when useful); desired `audience_outcome`; `core_message` / decision ask / action; delivery context; artifact afterlife-2. Source-treatment intent — open-ended `content_divergence`; facts remain sourced at every level-3. Canvas format-4. Complete deck solution — reading mode (JSON compatibility key `delivery_purpose`); narrative mode; page count; visual / template direction; color; icons; typography; image sources and generated-image rendering-5. Production plan — conditional AI-image acquisition path; formula rendering policy; execution mode; optional spec-refinement toggle--**Confirm UI Auto-Launch (Mandatory — default visual confirmation surface)**: by default the Strategist confirmation stage is presented through an interactive local page in **three stages within one browser session**. Stage 1 confirms the scene and communication contract before asking the user to select tools. The AI then authors Stage 2's **complete deck solution once** from the user's actual contract: argument structure, reading density, template use, visual system, and image direction are judged together. After Stage 2 is confirmed, Stage 3 is authored once and asks only how to produce the already-decided solution. A change inside the current page never asks the AI or server to regenerate that stage. Color swatches, live font previews, icon samples, rendering references, and coordinated direction candidates appear where they help judgment; the chat path is the always-valid fallback. [`scripts/docs/confirm_ui.md`](scripts/docs/confirm_ui.md) owns the schema, server lifecycle, port strategy, and fallback details; this section keeps the orchestration contract. The split:--| Stage | Confirms | Driven by |-|---|---|---|-| **1 — communication contract** | audience · open-ended `communication_intent` (may combine several purposes) · `audience_outcome` · `core_message` / delivery context / artifact afterlife · `content_divergence` (all prose fields may be blank) · canvas | the source + user intent |-| **2 — complete deck solution** (derived once from Stage 1) | reading mode (`delivery_purpose`, PPT only) · narrative `mode` · page count · `visual_style` · conditional template reuse / adherence · color · typography · icons · image usage · generated-image rendering | the confirmed communication contract |-| **3 — resources / production** (derived once from Stage 1 + Stage 2) | conditional AI-image acquisition path · formula policy · generation mode · refine-spec toggle | the confirmed solution |--> **Why three stages.** A presentation may serve several purposes at once (for example, report progress, expose risk, and request a decision), so Stage 1 uses open prose rather than a purpose enum. Every editable Stage-1 prose field is non-blocking: the user may retain, revise, or clear the recommendation, and confirmation makes the field's current value authoritative, including an empty string. Blank means no explicit user constraint; derive downstream defaults from the source and request without writing the old recommendation back into `result.json`. Stage 2 chooses tools only after that contract is known and keeps mutually dependent choices together: `mode` is the argument strategy, template reuse is the inheritance strategy, and reading mode decides how meaning is divided among the page, visuals, and presenter. It therefore drives content grammar, page granularity, density / rhythm, speaker-note burden, and the body baseline; the visual / image fields form the remaining deck system. `delivery_purpose` remains the compatibility key for **reading mode**, not communication purpose. Page count is derived from content volume × audience outcome × reading mode. Generated images inherit the chosen deck color roles directly; the user confirms rendering, not a second image palette. Stage 3 therefore contains production mechanics only, never another aesthetic decision. Each stage is authored once; documented deterministic UI dependencies may update visible values locally, but there is no same-stage AI recomputation.--Steps:--> ⛔ **Steps 2 → 3 → 4 are ONE uninterrupted run — do NOT yield to the user mid-flow.** When an intermediate `--wait` returns, the AI **immediately and autonomously** derives and writes the next stage once in the **same turn**: do **not** summarize, ask a question, report progress, or end the turn in between. The browser is sitting on a "deriving…" spinner polling for the next stage you must write — stopping here strands the page and the user must prod you in chat to finish (a bug, not the intended flow). **Stage-1 and Stage-2 confirmations are intermediate machine handoffs, not stopping points.** The single ⛔ BLOCKING wait is the **final** confirmation at the end of step 4. (Chat-fallback path — only when the page never opened — is the exception: there you do present each stage in chat and wait for a reply.)--1. **Write Stage 1** to `<project_path>/confirm_ui/recommendations.json` with `"stage": "stage1"` and only the communication-contract fields. New recommendations MUST use the canonical `stage` selector. Put only the recommended `canvas` id in `recommend`. Write `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, and `content_divergence` as `{ "value": "<free text>" }`. Seed concrete editable recommendations where the source and request support them; all seven prose values may be blank and none blocks confirmation. The submitted current value is the sole truth: preserve a user-cleared field as `""` through every later stage and the final `result.json`; never restore the earlier recommendation. `communication_intent` is deliberately open prose: it may combine several purposes and state their priority or sequence; the nine common paths are prompt examples only and MUST NOT become a checkbox / enum. `content_divergence` asks how closely to follow the source vs how freely to reshape it (blank = balanced; facts stay sourced at every level); it is consumed while authoring `§IX`, recorded in `design_spec.md §I`, and is not written to `spec_lock.md`. A profile may make this field read-only with `{ "value": "...", "locked": true }`; Beautify uses that contract and is the only exception to user editing. Do **not** include reading mode, `mode`, `visual_style`, page count, template, color, typography, icon, or image fields in Stage 1. Set `lang` to the page language (`zh` / `en` / `ja`); visible text matches `lang`, or provide multilingual name / note variants as documented by the Confirm UI.-2. **Launch + wait for Stage 1.** Background launch; the parent returns when the page writes the stage-1 `result.json`. **Long tool timeout — 600000 ms** (the `--wait` ≈590 s budget):- ```bash- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait- ```- Page opens at the launch-log URL such as `http://127.0.0.1:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4). If 5050 is held, the launcher **auto-advances** (5051, …) — read the actual URL from the launch log and report it. The page does **not** close after Stage 1: it shows a "deriving…" state and polls for Stage 2. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host), do **NOT** troubleshoot — **on any non-zero exit, re-check `result.json` once** for a fresh `status: stage1-confirmed` before dropping to the chat fallback. **On success (exit 0 with a stage-1 result), do not pause or report — go straight to step 3 in the same turn.**-3. **Derive Stage 2 once from the confirmed communication contract, write it, then wait for the solution handoff — immediately, same turn (the page is polling for it).** Read the stage-1 `result.json` (`status: stage1-confirmed`). Using the user's **actual** contract (not your originals), **overwrite** `recommendations.json` with `"stage": "stage2"` and author the complete deck solution:- - Recommend PPT-only reading mode through the compatibility key `recommend.delivery_purpose` (`text` / `balanced` / `presentation`) from the confirmed audience, delivery context, and artifact afterlife. `text` makes the page self-contained with complete prose and detail; `balanced` shares meaning between page and presenter; `presentation` uses one idea, concise claims, and visual evidence per page while speech / notes carry explanation. Then recommend one narrative `mode` and page count from source volume × desired audience outcome × reading mode. Reading mode governs content grammar and page granularity as well as the body baseline; it is not a font-size preset. The page applies `reading mode → body baseline → unpinned role sizes` as a deterministic browser-only dependency. This never calls the backend, and a manually edited size is pinned against later reading-mode changes.- - When Step 3 loaded a deck/layout template, recommend `template_reuse_scope` now: `mirror`, `layout`, or `style`; `mirror` is legal only for `replication_mode: mirror`. Include `template_adherence: strict|adaptive` only for `mirror|layout`; `style` hides it and later writes `pptx_structure.mode: flat`. For a Deck, first compare its application contract—situations, audiences/outcomes, required narrative/page roles, and content policy—with the confirmed Stage-1 contract; do not treat the stored application as truth when the current request differs. Select from scenario fit: literal recurring artifact → consider `mirror`; compatible reusable structure with new content → `layout`; identity only or a contract that needs a different structure → `style`. Omit both fields for free design and brand-only templates.- - Author `design_directions` with ≥3 coordinated candidates (safe / shifted / bold; honest-shortfall exception unchanged). Each candidate carries one compatible `visual_style`, color object, typography object, icon id, and—when `image_usage` includes `ai`—one generated-image **rendering** object. The page applies a candidate as one coherent starting point and then exposes the component fields for deliberate override. Do not generate Cartesian combinations or random mix-and-match defaults.- - Color candidates carry background / secondary_bg / primary / accent / secondary_accent / body_text. Typography splits CJK + Latin for heading/body, includes topic-matched sample text, and uses one fixed body baseline per reading mode (`text` 20 / `balanced` 24 / `presentation` 32 on PPT). Font and direction cards change font character while preserving the current reading-mode sizing state. Recommend one or more `image_usage` source ids (`["ai"]`, `["ai","provided"]`, `["web","placeholder"]`, or `["none"]`; `none` is exclusive) and keep mixed-source / page-role guidance in `image_notes`. When AI is included, each direction's `image_strategy` contains rendering / visual / mood only; **never offer or submit a separate image palette**. Image HEX and role behavior come directly from that direction's deck color object. Spot-illustration lean remains rationale, not a field.-- **Stage 2 is never skipped** — an installed template is an input to the decision, not a substitute for deciding how it serves the contract. Never jump `recommendations.json` from `stage1` to `stage3`: the server refuses to render a skipped stage. The still-open page polls, renders Stage 2, and preserves Stage 1. Then attach to the already-running page; if Windows cleaned up the server, `--wait-only` auto-recovers it on the recorded/default port so the browser reconnects:- ```bash- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage2- ```- This returns when the page writes the stage-2 `result.json` (`status: stage2-confirmed`). On a non-zero exit, re-check `result.json` once before falling back to chat — except a `stage skip detected` error, which is not a page failure: you wrote a stage out of order; rewrite `recommendations.json` with the stage the error names and re-attach.-4. **Derive Stage 3 once from the confirmed solution, then wait for the final confirmation.** Read the stage-2 `result.json`. **Do not reopen aesthetic choices.** Overwrite `recommendations.json` with `"stage": "stage3"` and recommend only production mechanics: enumerable `formula_policy`; conditional `image_ai_path` when confirmed `image_usage` includes `ai`; `generation_mode`; and `refine_spec`. The page shows the confirmed image-source summary as read-only context. Then attach to the already-running page; `--wait-only` auto-recovers a dead server as above (same 600000 ms budget):- ```bash- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only- ```- This is the ⛔ BLOCKING completion: returns when the page writes the final `result.json` (`status: confirmed`, `stage: final`, carrying Stage 1 + Stage 2 + Stage 3 fields). On a non-zero exit, re-check `result.json` once (a `stage skip detected` error means Stage 2 was never confirmed — go back to step 3, not the chat fallback). Confirmed sizes are **already px** (the system is px-only — no pt anywhere, no conversion): write `result.json` `typography.body_size` / `sizes` into `design_spec.md` / `spec_lock.md` / SVG verbatim. `generation_mode: "split"` / `refine_spec: true` are explicit user choices.-5. **Close the confirm page (Mandatory cleanup — every path).** Shut the server down before leaving Step 4 so it cannot keep holding port 5050 (which Step 6 live preview reuses):- ```bash- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown- ```- **Idempotent and required regardless of whether Confirm was clicked**: clicking the final Confirm already shuts the page down (then a no-op); the chat-fallback path leaves it running. Run it after reading the confirmation, before Step 5.--**Always also print each stage's recommendations + URL in chat** as the always-valid fallback. **The chat fallback is staged too**: if the page never opens or a wait times out with no fresh result, present Stage 1 as open communication questions (the common purposes are examples, never a numbered pick-list) → get confirmation → derive and present Stage 2 → get confirmation → derive and present Stage 3 → get confirmation → take those values. Either path converges.--**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate). `image_usage` may be either a legacy single string or a Confirm UI multi-select array; for arrays, apply every selected source. `image_notes`, when present, is a user-authored image intent note that Strategist must honor while assigning per-page §VIII rows:--For a confirmed template route, map `template_reuse_scope` mechanically: `style` → `pptx_structure.mode: flat` and omit `template_adherence`, `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`; `layout` / `mirror` → `mode: structured`, retain the confirmed `template_adherence`, and write the complete mappings. Never infer mirror behavior from the template workspace's `replication_mode` alone—the confirmed reuse scope is the downstream execution authority.--| `result.json.image_usage` | §VIII `Acquire Via` | h.5 + Step 5 generation |-|---|---|---|-| `ai` | `ai` rows | Run h.5 (lock rendering; inherit deck colors); Step 5 generates |-| `web` | `web` rows | None |-| `provided` | **`user`** rows | None — never generate |-| `placeholder` | `placeholder` rows | None |-| `none` | no image rows (§h option A) | None |-| Legacy custom prose | Infer the intended rows from the prose | Run h.5 only if the prose includes AI |--When the confirmed `image_usage` does not include `ai` (and no legacy custom prose includes AI), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. `none` is exclusive: if confirmed, write no §VIII image rows. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).--**Small spot illustrations are a Strategist judgment, not a confirmation field.** The user chooses image *source* through `image_usage`; whether the deck leans into decorative illustrations is anchored by the locked `visual_style`'s **illustration propensity** (`core` / `supportive` / `sparse`), expressed only in the `image_notes` rationale — never a new confirmation control. An explicit user request to use or skip illustrations overrides that default either way; `image_usage: none` still wins (write no illustration rows); and source still comes from `image_usage` — a `core` style does not silently generate AI spots when the user did not pick AI. They are ordinary §VIII image rows (`Type: Illustration` / `Illustration Sheet`) using normal `Acquire Via` values. If the plan needs ≥3 same-family AI spot illustrations, use the `ai` Illustration Sheet + `slice` workflow by default; do not generate one AI image per spot. Full rule + precedence: [`references/strategist.md`](references/strategist.md) §h. Use them on suitable pages and omit them where they would weaken clarity.--**One authored recommendation per stage; final visible state wins (Mandatory).** Author each stage exactly once. A user edit inside Stage 2 MUST NOT trigger AI / backend re-recommendation, and confirmation MUST NOT be followed by a hidden repair pass that changes any displayed field. The page may apply only documented deterministic local dependencies: reading mode sets the default body baseline, body sets unpinned role sizes, and manual size edits pin those values. Font / direction changes preserve the current sizing state. No other advanced override silently rewrites a sibling choice.--Writing `design_spec.md` / `spec_lock.md` and later pages is **consumption of the confirmed state**, not another confirmation-stage calculation. Preserve every confirmed field verbatim and use it as an execution constraint:--| Confirmed anchor | Consume it in |-|---|---|-| `communication_intent` / `audience_outcome` / `core_message` | outline obligations, argument emphasis, and audience moves |-| `delivery_context` / `artifact_afterlife` | page-vs-presenter information load, standalone completeness, notes / citation depth, and hand-off structure |-| `visual_style` (§d Layer 2) | layout treatment, shape language, and visual rhythm while preserving the separately confirmed color / icon / typography values |-| `mode` (§d Layer 1) | outline structure and register (§IX) |-| `delivery_purpose` compatibility key (reading mode, §g) | content grammar, page granularity, notes burden, and per-page density / rhythm (§6.1); use the already-confirmed body / role sizes verbatim |-| `audience` (§c) | tone, evidence depth, and outline emphasis (§IX) |-| `color` HEX (§e) | exact deck roles and AI prompt color-role instructions; never invent or restore an image-palette choice |--If a deliberately mixed set of advanced overrides is unusual, honor it rather than silently “fixing” it. Canvas remains the explicit exception only in the sense that changing canvas does not rescale font sizes (see strategist §g); it still does not trigger a second stage calculation.--**Opt-out**: if the user has said they don't want the page (e.g. "不要网页" / "just confirm in chat" / "纯聊天确认"), skip the launch entirely (step 2) and present the Strategist confirmation stage in chat as before — steps 1, 3, 4 still apply (recommendations summary in chat; wait; take chat values).--The page is a **confirmation surface only** — Strategist still authors every recommendation; the page never generates content.--**Mandatory — split-mode note** (not a separate confirmation): after listing the Strategist confirmation stage details, you MUST append exactly one short line (rendered in the user's language, prefixed with 💡) about generation mode. Pick the variant by qualitative read of upstream-load signals — recommended page count, source-material bulk, whether `topic-research` ran with substantial web-fetch accumulation:--| 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/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/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)**:--| Policy | Behavior |-|---|---|-| `mixed` (default) | Strategist renders complex formula-worthy expressions as PNG assets; simple inline expressions remain editable text / Unicode |-| `render-all` | Strategist renders every formula-worthy expression as PNG assets |-| `text-only` | No formula rendering; formulas remain editable text / Unicode |--After the Strategist confirmation stage is approved and **before outputting `design_spec.md` / `spec_lock.md`**, if the confirmed formula policy is `mixed` or `render-all` and the content contains formula-worthy expressions, Strategist MUST:--1. Identify explicit LaTeX and any source expressions that should be faithfully structured as formulas.-2. Write `<project_path>/images/formula_manifest.json` with only the formulas selected for rendering.-3. Run:- ```bash- python3 ${SKILL_DIR}/scripts/latex_render.py <project_path>- ```-4. Include each formula as an `Acquire Via: formula`, `Type: Latex Formula` row in `design_spec.md §VIII Image Resource List`: use `Status: Rendered` when the PNG exists, or `Status: Needs-Manual` after provider exhaustion. List every formula in `spec_lock.md images` with `| no-crop`.--The formula renderer uses a provider fallback chain by default: `codecogs,quicklatex,mathpad,wikimedia`. The first three are color-aware; Wikimedia is an availability fallback. If every provider fails for a selected formula, report its manifest item, LaTeX source, target filename, and provider errors; mark only that row `Needs-Manual` and continue without claiming `Rendered`. The user may supply the exact target PNG before the Step 7 image-readiness gate or change the formula policy. Formula PNGs are transparent by default: manifest `background` is the temporary render matte and transparency-removal reference, not a retained final background unless `transparent: false` is set for that item. Do not scan `spec_lock.md` for `$...$` or `$$...$$`. Dollar-delimited math in source material is only a signal for Strategist; the renderer consumes the explicit manifest.--If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative regenerated image-fact view in the `analysis/` folder, which MUST be read before authoring §VIII:-```bash-python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images-```--> 🔁 **Image facts are regenerated on demand, never a durable store.** `images/` is a live working folder — pictures are extracted from the source at import, the user may drop or replace files at any time, and Step 5 writes web/AI images into it. The single source of truth is therefore the **current contents of `images/`**, and `analysis/image_analysis.csv` is a *regenerated view* of it, not a fact to keep in sync. Re-run `analyze_images.py <project_path>/images` immediately **before any step that reads image facts** so the view reflects the live folder: before the §h image-usage recommendation (see [strategist.md](references/strategist.md) §h), here before authoring §VIII, after Step 5 acquisition (so web/AI files join the view), and again any time the user says they added or replaced images. This is the staleness strategy — re-derive on use, no cache to invalidate.--> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output (`analysis/image_analysis.csv`) or the Design Spec's Image Resource List.--**Output**:-- `<project_path>/design_spec.md` — human-readable design narrative-- `<project_path>/spec_lock.md` — machine-readable communication + execution contract (skeleton: `templates/spec_lock_reference.md`); Executor re-reads before every page--**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:-```markdown-## ✅ Strategist Phase Complete-- [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 stage)-- [x] Design Specification & Content Outline generated-- [x] Execution lock (spec_lock.md) generated-- [x] Communication trace validated: `spec_lock.md ## communication` contains all six contract key lines (optional values may be blank), and every `design_spec.md §IX` Slide block has an `Audience move`-- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase-```-------### Step 5: Image Acquisition Phase (Conditional)--🚧 **GATE**: Step 4 complete; `<project_path>/design_spec.md` and `<project_path>/spec_lock.md` both exist. If either required artifact is missing, stop before any acquisition or generation and follow [`failure-recovery.md`](workflows/governance/failure-recovery.md) §3. Formula rows already have `Acquire Via: formula` and status `Rendered` or `Needs-Manual`.--> **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/governance/failure-recovery.md`](workflows/governance/failure-recovery.md). This Step keeps the acquisition procedure.--**Always load the common framework**:--```-Read references/image-base.md-```--Then **lazy-load the path-specific reference** for each row that actually needs it:--| Acquire Via | Load reference (only if any such row exists) | Run |-|---|---|---|-| `ai` | `references/image-generator.md` | write `<project_path>/images/image_prompts.json`, then follow `image-generator.md §7 Path Selection` (`image_gen.py --manifest` is **Path A only**) |-| `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` (≥2 web rows → `--batch images/image_queries.json`) |-| `slice` | `references/image-generator.md` §4.3 | derived — **after** the parent `ai` sheet row is `Generated`, run `python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha` (see workflow step 2.5) |-| `user` / `formula` / `placeholder` | (skip) | (skip) |--A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.json` and `image_sources.json`.--> ⚠️ **In-pipeline ai rows MUST use the manifest contract** — even when only 1 ai row exists. Always write `images/image_prompts.json` first and render `image_prompts.md` with `image_gen.py --render-md`. Then execute the confirmed path from `image-generator.md §7`: `image_gen.py --manifest` is **Path A only**; `host-native` is **Path B** and MUST skip `--manifest`; `manual` writes the prompts and stops for external generation. The positional form (`image_gen.py "prompt" ...`) is reserved for **out-of-pipeline one-off testing / single-image fixups** — it skips manifest + sidecar, leaving no audit trail.--> ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](references/image-searcher.md) §5.--> 💡 **ai path — spot illustrations as one sheet**: when the §VIII image resource plan needs ≥3 same-family spot illustrations as decorative accessories, generate **one grid sheet** (a single `ai` sheet row) instead of one row per element, then slice it (workflow step 2.5 below). Choose sheet geometry from intended placement: `1xN` / `Nx1` are useful for extreme portrait / landscape cells, and a designed `MxN` grid is valid when its cell ratio fits the planned elements. The sheet row is generated but not placed; each cut **element row** (`Acquire Via: slice`) is placed and must appear in `spec_lock.md images`. One generation = one coherent style across all pieces. Resource contract + the geometry rules: [image-generator.md](references/image-generator.md) §4.3.--> ⚠️ **Honor the confirmed image source before running any generation command**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — a confirmed choice other than `auto` wins, whether it came from chat (canonical) or, when the page was used, `result.json.image_ai_path`. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. Never run `image_gen.py --manifest` when the confirmed value is `host-native` or `manual`. Full selection rule: [image-generator.md](references/image-generator.md) §7 Path Selection.--Workflow:--1. Extract all resource rows from the design spec and group them by `Acquire Via`; rows with `Status: Pending` or `Status: Failed` and `Acquire Via ∈ {ai, web, slice}` must all reach a terminal state before Executor starts-2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](references/image-base.md) §3 dispatch table-2.5. **Slice any spot-illustration sheets (only if `slice` rows exist).** For each generated `ai` **sheet** row, run `slice_images.py` (grid + the element `--names` matching the `slice` rows, `--trim --alpha`) so every element file lands in `images/`; mark each `slice` row `Generated`. A sheet still in `Needs-Manual` cannot be sliced — leave its `slice` rows `Needs-Manual` and surface them at the Step 7 readiness gate. Contract: [image-generator.md](references/image-generator.md) §4.3.-3. Verify every row reaches a terminal status: `Generated` (ai success / sliced element), `Sourced` (web success), or `Needs-Manual`. `Failed` is not a terminal status: it means the current run did not generate that item, but the item remains retryable. On `auto`, follow the owning fallback chain. On an explicitly confirmed `api` or `host-native` path, retry only that path; if it still fails, mark the row `Needs-Manual` without switching to another automated provider.-4. Re-derive image facts now that web / AI / sliced files are in the folder — `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` — so `analysis/image_analysis.csv` reflects every acquired image **including the sliced elements** (real measured sizes) before the Executor lays them out. Image facts are regenerated on use, never a stale store (see Step 4's image-facts note).--**✅ Checkpoint — Confirm acquisition attempted for every row**:-```markdown-## ✅ Image Acquisition Phase Complete-- [x] image_prompts.json created (when any ai rows processed)-- [x] image_prompts.md sidecar rendered (when any ai rows processed)-- [x] image_sources.json created (when any web rows processed)-- [x] Spot-illustration sheets sliced (when any `slice` rows exist); every element file present in `images/` and listed in `spec_lock.md images`-- [x] Each row: status is `Generated` / `Sourced` / `Needs-Manual` (no `Pending` or `Failed` remaining)-- [x] analyze_images.py re-run so image_analysis.csv covers the acquired web / AI / sliced images-```--**Default — auto-proceed to Step 6.** Only when the user's Step 4 response explicitly opted into split mode (in chat or via Confirm UI `result.json` with `generation_mode: "split"`), output the planning-session handoff below and stop this conversation:-- ```markdown- ## ✅ 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/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.-------### Step 6: Executor Phase--🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready.--**Artifact ownership**: `svg_output/` is the author source, `svg_final/` is derived, and image facts come from the regenerated `analysis/image_analysis.csv`; see [`references/artifact-ownership.md`](references/artifact-ownership.md).--Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):-```-Read references/executor-base.md # REQUIRED: common guidelines-Read references/shared-standards.md # REQUIRED: SVG/PPT technical constraints-Read references/native-shape-authoring.md # REQUIRED: stock-shape selection and fragment helper contract-Read references/modes/<locked-mode>.md # narrative skeleton (spec_lock.md `mode`)-Read references/visual-styles/<locked-style>.md # aesthetic (spec_lock.md `visual_style`)-```--> Read executor-base + shared-standards + native-shape-authoring + the one locked mode file + the one locked visual-style file. For `mode: custom` or `visual_style: custom`, skip that preset file and follow `mode_behavior` / `visual_style_behavior` from `spec_lock.md` instead. Never glob `modes/` or `visual-styles/`.--**Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.--**Live Preview Auto-Startup (Mandatory)**: before the first SVG, automatically start the browser editor in live mode and keep it running continuously through Executor + Step 7 export:-```bash-python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon-```-- Start it immediately when Executor begins; `svg_output/` may be empty. Editor opens at the launch-log URL such as `http://127.0.0.1:5050`; if another project already holds it, the launcher **auto-advances to the next free port** — read the actual URL from the launch log and report that.-- 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/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 Template Read (Mandatory)**: first read `templates/template_execution_manifest.json` when present. It is the compact prototype roster and points each prototype to one `text_slots_path`. Use the roster to select prototypes; before each mirror page, read that prototype's text-slot sidecar and complete `templates/<basename>.svg`. Layout reuse reads the selected complete SVG but does not apply mirror-only text topology restrictions. When the manifest or selected sidecar is unavailable, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` once before the first page and apply the full-SVG mirror/layout rules. In all cases, batch-read every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts) once up front. Do not substitute a manifest or sidecar for the selected full prototype. See executor-base.md §1.0.--> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).--**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md`; check the global `communication` contract, including `consumption_mode`, against the current §IX `Core message` + `Audience move`, and use only the lock's colors / fonts / icons / images, plus `pptx_structure.mode`, `template_reuse_scope`, and the per-page `page_rhythm` / `page_charts` lookups. Read `page_layouts` / `page_pptx_layouts` / `pptx_masters` / `pptx_layouts` only on a structured `template_reuse_scope: mirror|layout` route; they are absent in flat `style`, free-design, and brand-only projects. Resists purpose and design drift on long decks. See executor-base.md §2.1.--> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.-> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).--**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`--Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Before drawing a literal stock shape, apply [`native-shape-authoring.md`](references/native-shape-authoring.md): use the stdout-only helper when one PowerPoint preset exactly matches, keep basic SVG primitives for rect/round-rect/ellipse, and keep free SVG for custom semantics. Diagram relationships are Shape-first: use ordinary line/path shapes with registered arrow markers for thin edges and ordinary shape presets for solid block arrows; do not default to connector-family presets or author attachment metadata. Never infer a preset from contour similarity.--`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. `layout` pages may reflow and re-skin to the project lock; `mirror` pages preserve literal visuals and may change only visible `<text>` / `<tspan>` values while keeping text/tspan count, order, nesting, and every attribute unchanged. `template_reuse_scope: style` follows the flat free-design paragraph below and does not inherit template structure metadata.--`template_reuse_scope: style`, free-design, and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.--Do not duplicate specialized identity with `data-pptx-role`. Add it only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-replace-with`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](references/semantic-svg.md).--**First-page gate (Mandatory)** — after the **first** SVG page, before drawing page 2:-```bash-python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page-```-Fix every `error` on page 1 first — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.--**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE annotation handling and speaker notes:-```bash-python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json-```-- Any `error` (banned/unsupported SVG features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.-- Every `warning` is advisory and non-blocking: do not return the page for mandatory modification, do not auto-normalize user-authored compatible syntax, and do not require an acknowledgement/disposition line. Recommendation warnings identify the generated-SVG default; fidelity/quality warnings may be reported when material, but the existing input may ship unchanged. If a condition must be corrected before release, the checker must classify it as an `error`, not a `warning`.-- The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat `style`, free-design, and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks.-- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).-- The JSON report is written to `exports/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`.--**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`--**✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Run the applicable conditional gates below, then proceed to Step 7**:-```markdown-## ✅ Executor Phase Complete-- [x] Live preview started before the first SVG and kept available at the reported URL-- [x] First-page gate run after page 1 (errors fixed before page 2)-- [x] All SVGs generated to svg_output/-- [x] svg_quality_checker.py passed (0 errors)-- [x] Speaker notes generated at notes/total.md-```--> **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 [`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.-------### Step 7: Post-processing & Export--🚧 **GATE**: Step 6 complete; all SVGs generated to `svg_output/`; speaker notes `notes/total.md` generated.--🚧 **Image readiness GATE** (when any required resource row is `Needs-Manual`, including a formula row): every expected file must exist at `project/images/<filename>` before running 7.1. Once the files are supplied, re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images`, then update each affected page in `svg_output/`: replace the dashed placeholder with the real `<image>` reference and, for `no-crop` rows (formulas included), resize the container to the measured native ratio — planned dimensions are estimates, not the supplied file's truth.--**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.--> **Spot-illustration sheets at this gate**: `slice` element files are **derived**, not placed by the user. If a sheet was `Needs-Manual` (offline), the element files do not exist yet — list the **sheet** filename (`images/<sheet>.png`) plus its element target names, and instruct: place the sheet, then run the Step 5 `slice_images.py` command for it, then re-run `analyze_images.py`, before resuming 7.1. Never tell the user to hand-place the individual element files — they only come from slicing the sheet.--> ⚠️ Run the three sub-steps **one at a time** — each must complete successfully before the next.-> ❌ **NEVER** combine them into a single code block or shell invocation.--Canonical three-command pipeline (this step is the workflow authority;-`references/shared-standards.md` §5 points here):--**Step 7.1** — Split speaker notes:-```bash-python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>-```--**Step 7.2** — SVG post-processing (icon embedding / image crop & embed / raster image optimization / text flattening):-```bash-python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>-```-This mandatory step writes self-contained visual-preview SVGs to `svg_final/`. Those files may be opened directly or manually inserted into PowerPoint as SVG pictures. Default raster handling embeds images at the rendered SVG size budget (`--image-scale 2`, `--max-dimension 2560`); opaque PNG photos may be written as JPEG, and transparent assets remain PNG. The existing EMF/WMF exception still applies: Office vector assets stay externally referenced for lossless native-PPTX passthrough, so the native PPTX remains the source of truth for pages that use them. Use `--no-compress` or a higher `--max-dimension` only for diagnostic / high-fidelity SVG previews.--**Step 7.3** — Export PPTX (embeds speaker notes by default):-```bash-python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>-# Output (default-flow mode):-# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output, reads svg_output/)-# exports/<project_name>_<timestamp>.report.json ← package/resource/quality postflight audit-# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)-# backup/<timestamp>/templates/native_payloads.json.gz-# ← copied when compact native metadata refs are used-# 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 stage) embeds per-slide narration:-# exports/<project_name>_<timestamp>_narrated.pptx ← narrated pptx (embedded audio + auto-advance timings)-```--> The native pptx consumes `svg_output/` directly so the converter can preserve-> high-fidelity primitives (icon `<use>` placeholders, image `preserveAspectRatio`-> → native picture crop metadata, rounded rect `rx/ry` → `prstGeom roundRect`).-> Native raster images are optimized by default before writing `ppt/media`-> (`--image-sizing cap`, `--image-max-dimension 2560`, `--image-quality 85`).-> This optimization downscales only oversized full source images; it does not-> crop pixels out of embedded PPTX media, and it does not reduce a small-> placement image merely because it is currently displayed small. Display-> cropping remains editable PPT picture-crop metadata. Add `--no-image-optimize`-> only when the deck must retain original image bytes. Use-> `--image-sizing display --image-scale 2` only for aggressive size reduction.-> The `svg_output/`-> snapshot in `backup/<timestamp>/` is always written so the project can be-> re-exported from frozen SVG sources without re-running the LLM. When those-> SVGs reference compact native template metadata, the matching-> `templates/native_payloads.json.gz` sidecar is copied into the same backup-> timestamp. The SVG-rendered-> preview remains the mandatory `svg_final/` artifact from Step 7.2; it is not-> packaged as a second PPTX. Use the default source selection for release-> exports. `-s final` is diagnostic-only-> when comparing conversion behavior against the post-processed SVGs; it does-> not change `svg_output/` ownership or establish a supported release route.-> Every successful export also writes `<output_stem>.report.json`. It separates-> formal Slides from internal Layout-definition inputs, counts Notes/Masters/-> Layouts from the finished package, reruns ZIP-integrity and published-Slide-> checks, labels relationship/structured/transition/animation validation as-> enforced at build time, inventories unresolved template tokens, generic-only-> font stacks, and image references, records the backup/trace paths, and links-> final SVG quality categories only when the report's SHA-256 source fingerprint-> matches the exact export inputs. A stale or unverified quality gate leaves the-> successful package as `passed-with-warnings`.--> **Supported PPTX boundary** — the only supported generated-PPTX path is-> `svg_output/` → the project SVG-to-DrawingML converter → native PPTX. The-> project does not emit an SVG-image PPTX and does not support PowerPoint's-> manual **Convert to Shape** operation on `svg_final/`. Inserted `svg_final/`-> pages remain ordinary SVG pictures unless the user independently accepts the-> results of an unsupported Office conversion.--> **PPTX structure mode** — release export reads the explicit route from-> `spec_lock.md`. Free-design, brand-only, and `template_reuse_scope: style`-> projects use-> `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` /-> `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata in-> SVG. Export keeps every represented object Slide-local while materializing-> one clean project-owned Master and one Blank Layout from the current lock;-> stock content placeholders and unused built-in Layouts are removed; only the-> standard date/footer/slide-number capability hooks remain.->-> Deck/layout template projects confirmed with `template_reuse_scope:-> mirror|layout` use `pptx_structure.mode: structured`, a-> complete `pptx_masters` roster, one unique `pptx_layouts` definition per-> reusable Layout, and exactly one `page_pptx_layouts` assignment per page.-> A Layout definition records Master key, PowerPoint picker name, and either a-> `P<NN>` or `template:<basename>` prototype source; an unused Layout uses a template prototype-> and is registered without a published carrier slide. Every SVG-> root repeats the Master/Layout keys and picker names. Master/Layout fixed-> visuals are direct root atoms; a `<g data-pptx-layer="master|layout">` is-> forbidden. Reusable slots are direct root `<g id>` elements with positive-> design-zone bounds and exactly one compatible carrier. A composite region-> uses only the explicit `object` + `proxy` fallback, and a Layout may-> intentionally have zero slots.->-> Structured template export creates the declared Masters and Layouts,-> promotes the represented-> atoms, binds slot carriers, installs the locked theme/text defaults, and-> reopens the candidate package to verify Presentation → Master → Layout →-> Slide registration, picker names, static-object rosters, placeholder-> type/index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts.-> It never selects pages, clusters visuals, promotes repeated chrome by-> heuristic, or invents missing structure. Legacy structured/template projects-> using `baseline`, `template`,-> `preserve`, `layout_strategy`, `data-pptx-layout-kind`,-> `distilled`/`utility`, direct atomic placeholders, or incomplete Master-> 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** — `template_reuse_scope: mirror|layout` uses-> `page_layouts` to record the complete-> input prototype per page, `pptx_masters` / `pptx_layouts` record the unique-> reusable output roster, and `page_pptx_layouts` records page assignment.-> Strict keeps the prototype-> Master/Layout/slot contract. Adaptive keeps its Master and may assign a new-> Layout identity during page authoring only when fixed Layout atoms or slot-> topology/bounds change; the lock is updated immediately. `layout` skin-> remains project-controlled; `mirror` preserves literal visuals and text-node-> topology. `template_reuse_scope: style` uses `mode: flat` and omits all-> structure mappings,-> and the exporter never reads a template to add visible objects missing from-> `svg_output/`. Raw PPTX templates still route to `template-fill-pptx`;-> reusable template creation goes through `create-template`.--> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked-> paragraph blocks collapse into one editable PowerPoint text frame with multiple-> `<a:p>`, improving body-text editing and resize/reflow behavior. Add `--no-merge`-> only when the user explicitly asks for strict line-layout fidelity or when a-> layout-tight page must keep every dy-stacked line as its own text frame. The-> merge detector is conservative: adjacent lines with different effective font-> sizes retain a paragraph break, and mixed-layout text falls back to per-line frames.-> A multiline-> text carrier inside a slot must remain one native text frame; do not combine-> it with `--no-merge`. Strict-line text stays Slide-local rather than claiming-> one PowerPoint placeholder.--> **PowerPoint-native Chart/Table replacements** — supported data charts and pure text-grid-> tables carry `data-pptx-replace-with` markers by default (Executor transcribes-> them at draw time; see `references/executor-base.md` §3.2) and the markers-> stay dormant.-> Add `--native-charts-and-tables` only when the user explicitly wants-> data-backed PowerPoint-native Chart/Table objects and their object-specific-> editing controls, and accepts that those objects may-> render differently across PowerPoint / Keynote / LibreOffice / WPS; marker-local-> details not represented by the replacement payload may be omitted. This is a lossy-> data-object-first contract, not a reason to disable an otherwise supported-> marker. Without the flag, marked groups export through their SVG fallback-> children as independently editable DrawingML shapes. Imported objects that carry-> `data-pptx-replacement-status` are fallback-only; the quality checker and-> `--native-charts-and-tables` export surface their reason as warnings rather than silently-> claiming a native data object. An imported chart with no baked preview is a different-> case: `data-pptx-fallback-kind="placeholder"` records its-> reconstruction-only fallback.-> Default export keeps that placeholder with a warning; when the same group has-> a valid active `data-pptx-replace-with="chart"` payload,-> `--native-charts-and-tables` may still-> reconstruct the PowerPoint-native chart. Invalid or contradictory status declarations-> remain export errors. For supported parsed classic families, the importer-> instead emits a deterministic visible fallback with-> `data-pptx-fallback-kind="normalized"`; this is readable reconstruction, not-> a claim of Office pixel parity. Active imported table/chart markers also carry-> `data-pptx-import-source="pptx"` and-> `data-pptx-fallback-sha256`. If their fallback, reachable SVG fragment-> definition, local reference target, or marker transform changes later, default-> export keeps that SVG, the mandatory quality checker warns, and-> `--native-charts-and-tables` fails rather than discard the edit. Generated-> authoring and reusable templates omit import provenance and a static baseline;-> that hashless authored state is normal and does not warn. Hashless legacy-> imported markers that still carry PPTX import provenance remain-> native-compatible and only warn that stale detection is unavailable. Legacy-> `data-pptx-native*`, `data-pptx-visual-status`, and-> `data-pptx-route-status` spellings remain read-compatible; generated SVG uses-> only the canonical replacement/fallback attributes. `--native-objects`-> remains a compatibility alias for `--native-charts-and-tables`.-> Imported table markers may also cover the verified narrow P2 subset:-> exact physical row/grid topology, canonical rectangular merges with blank-> covered cells, safe per-side borders, plain multi-paragraph cells, and closed-> run-level rich text. A rich paragraph contains non-empty `runs`; each run-> requires `text` and may use only-> `bold` / `italic` / `underline` / `strike` / `color` / `font_size` /-> `font_family` / `lang` / `alt_lang`. 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, noncanonical merges, and unsafe direct formatting-> remain fallback-only. Imported classic charts-> additionally cover verified column/line/area combos, canonical OHLC stock,-> area date-axis cases, verified scatter/bubble axes, radar, safe `of_pie`-> `serLines`, and the closed axis/title/legend plus bar-gap/overlap normalization-> cases. The importer also accepts the seven closed ChartEx data models:-> treemap, sunburst, histogram, pareto, box-whisker, waterfall, and funnel.-> ChartEx data topology is retained for native read-back, but style, axis,-> labels, and binning details may normalize. These additions do not create a-> full `AxisSpec`, arbitrary ChartEx import, arbitrary rich OOXML, or new-> normalized-renderer coverage; unmodeled semantics continue to fail closed-> without reducing existing active-marker SVG-to-native conversion.--**Optional animation flags** (page transitions are on by default; per-element entrance is off by default — turn it on only when the user asks for it):-- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`. `none` removes only the visual transition; an explicit automatic advance remains valid.-- `-a <effect>` — per-element entrance animation. **Default `none`** — pages appear as a whole, no auto-firing element builds (the unsolicited cascade reads as the "AI deck" tell). Opt in with `auto` (map effect from group id: chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade; image-like ids `hero` / `figure-` / `image` / `img-` / `kpi` cycle a richer pool — zoom / dissolve / circle / box / diamond / wheel — so multiple images vary across the deck), a specific effect like `fade`, or `mixed` for the legacy 16-effect cycle. Requires top-level `<g id="...">` groups (already required by Executor).-- `--animation-trigger {on-click,with-previous,after-previous}` — Start mode (matches PowerPoint's animation-pane Start dropdown). Default `after-previous` (click-free cascade; pace via `--animation-stagger`). Use `on-click` for presenter-paced reveals, or `with-previous` for all-at-once.-- `--animation-config <path>` — optional object-level sidecar. Default: `<project_path>/animations.json` when present.-- `--auto-advance <seconds>` — kiosk-style auto-play. Click remains enabled, so click or timer may advance the slide.--**Animation compatibility gate**: the default element animation remains `none`.-When animation is enabled, unknown effects/modes/triggers, invalid numeric or-order values, missing slide/group references, and explicit structural layer,-static-role, or static-placeholder targets fail export; they never downgrade-or disappear silently. An explicit-sidecar group may override only the legacy chrome-name heuristic. `random`-resolution is stable for the same effective input; with `--conversion-trace`,-its resolved rows are written to the trace. Generated export performs per-slide semantic-read-back plus package timing/`p:cTn`/`p:spTgt` validation. Narration merges-audio timing into the existing DOM and preserves animation rows. Direct-PPTX-routes preserve source object animation, compare its object-animation fingerprint-before/after allowed edits, and validate structure; they do not author-animation effects. The exact 22 tuples and OOXML rules live in-[`scripts/docs/pptx-animations.md`](scripts/docs/pptx-animations.md).--**Optional custom animations** (only when the user asks to tune animation order/effects/timing for specific objects):--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 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 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-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/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/stages/live-preview.md) Step 1 to start it. If the service is already running, just point them at the URL — do not restart.-------## Role Switching Protocol--Before switching roles, **MUST first read** the corresponding reference file. Output marker:+- Match the user's language and source language unless the user explicitly overrides it.+- Localize user-facing option labels and explanations. Keep exact enum IDs or field names when needed for precision.+- Keep `design_spec.md` section headings and field names in the template's original English; content values may use the user's language.+- Before switching roles, read the corresponding role reference and output:```markdown## [Role Switch: <Role Name>]@@ -989,22 +54,9 @@ Before switching roles, **MUST first read** the corresponding reference file. Ou----## Reference Resources--| Resource | Path |-|----------|------|-| Shared technical constraints | `references/shared-standards.md` |-| Native preset shape authoring | `references/native-shape-authoring.md` |-| Semantic SVG marker contract | `references/semantic-svg.md` |-| Canvas format specification | `references/canvas-formats.md` |-| Image-text layout patterns (Primary structures + Modifier layers — combine freely) | `references/image-layout-patterns.md` |-| Image layout sizing (math for side-by-side container dimensions) | `references/image-layout-spec.md` |-| SVG image embedding | `references/svg-image-embedding.md` |-| Icon library | `templates/icons/README.md` |-------## Notes+## Repository Compatibility-- Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`-- **Troubleshooting**: on generation issues (layout overflow, export errors, blank images, etc.), check [`scripts/docs/troubleshooting.md`](scripts/docs/troubleshooting.md)+- This package is a workflow/skill, not a generic application scaffold. Do not create `.worktrees/`, `tests/`, branch workflows, or generic engineering structure by default.+- Keep required workflow, reference, script, and template documentation inside this Skill directory.+- Repository-level documents may point into the package; package runtime files must not depend on repository-level instructions.+- On Windows, if a documented `python3 ...` command is unavailable, rerun the same command with `python`.diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 87563ff6..327a5724 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -524,7 +524,7 @@ Handle images by their status in the Design Spec's Image Resource List. Status e**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).-**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image (SKILL.md Step 3). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. `template_reuse_scope: mirror` (§1.1) is the one exception — it copies hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.+**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image ([`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md)). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. `template_reuse_scope: mirror` (§1.1) is the one exception — it copies hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text@@ -619,21 +619,9 @@ Auto-split `notes/total.md` into per-page files in `notes/`.> **Auto-continuation**: After Visual Construction Phase (all SVG pages) and Logic Construction Phase (all notes) are complete, the Executor proceeds directly to the post-processing pipeline.-**Post-processing & Export** (canonical workflow: [`SKILL.md` Step 7](../SKILL.md)):--```bash-# 1. Split speaker notes-python3 scripts/total_md_split.py <project_path>--# 2. SVG post-processing (auto-embed icons/images and flatten positioned text)-python3 scripts/finalize_svg.py <project_path>-# Output: svg_final/ self-contained SVG visual previews--# 3. Export PPTX-python3 scripts/svg_to_pptx.py <project_path>-# Output (default-flow mode):-# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output)-# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)-```+**Post-processing & Export**: Follow [`generate-pptx.md`](../workflows/generate-pptx.md)+Step 7. That workflow owns the serial commands, gates, success criteria, and+published artifacts; [`svg-pipeline.md`](../scripts/docs/svg-pipeline.md) owns+tool-specific flags and behavior.`svg_final/` may be opened directly or manually inserted into PowerPoint as an SVG picture. It is not a second PPTX route. Use `-s final` only for converter diagnostics; release exports use the default `svg_output/` source. Manual Convert-to-Shape behavior is unsupported.diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.mdindex e2dbbf16..c32b9004 100644--- a/skills/ppt-master/references/image-generator.md+++ b/skills/ppt-master/references/image-generator.md@@ -95,7 +95,7 @@ Use them directly. Do not create another image-color choice and do not change HE**Declared-inference fallback — when an existing `spec_lock.md` omits the `image_rendering` key** (see [`failure-recovery.md`](../workflows/governance/failure-recovery.md) §2):-This fallback covers a missing key only. An empty or invalid value stops for lock repair. If `spec_lock.md` itself is absent, stop at the [`SKILL.md`](../SKILL.md) Step 5 gate before prompt assembly or image generation; do not use `design_spec.md` as a substitute.+This fallback covers a missing key only. An empty or invalid value stops for lock repair. If `spec_lock.md` itself is absent, stop at [`generate-pptx.md`](../workflows/generate-pptx.md) Step 5 before prompt assembly or image generation; do not use `design_spec.md` as a substitute.| Signal | Maps to ||---|---|diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex d789436b..51b76dc9 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -652,7 +652,7 @@ separate parent content group; never put them inside the preset group itself.## 5. Workflow AuthorityThe serial post-processing and export workflow belongs to-[`SKILL.md` Step 7](../SKILL.md). This file defines SVG authoring boundaries+[`generate-pptx.md`](../workflows/generate-pptx.md) Step 7. This file defines SVG authoring boundariesand intentionally does not mirror commands, flags, or output behavior.---@@ -1954,6 +1954,6 @@ Without an original PPTX or complete current Type B contract, do not claim mirro## 8. Scope Boundary-Project structure, commands, quality-gate order, and export products are owned-by [`SKILL.md`](../SKILL.md). They are intentionally outside this SVG-authoring policy.+Generate project structure, commands, quality-gate order, and export products+are owned by [`generate-pptx.md`](../workflows/generate-pptx.md). They are+intentionally outside this SVG authoring policy.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 064ae767..c34d57b2 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -32,13 +32,13 @@ As a top-tier AI presentation strategist, receive source documents, perform cont| **2 — complete deck solution** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · template reuse / adherence · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering | derived from the confirmed contract || **3 — resources / production** (authored once from the user's *actual* Stage 1 + Stage 2) | formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle | derived from the confirmed solution |-Do not force communication intent into one catalog label. A deck may report progress, expose risk, and request a decision in the same artifact; Stage 1 records that relationship in prose. Its editable prose fields are recommendation drafts, not required inputs: confirmation accepts the current text exactly, including blanks, and a cleared field must not be repopulated later. Stage 2 then confirms one complete solution: narrative spine, reading density, page budget, template strategy, visual system, and image direction. Present ≥3 coordinated design directions (safe / shifted / bold) so color, type, icons, and generated-image rendering begin coherent; the user may still override each component. Generated images inherit the selected deck colors directly—there is no second image-palette confirmation. Stage 3 asks only how to produce the locked solution. **Page count is derived, not an anchor**—it follows content volume × desired audience outcome × reading mode. Author each stage once: same-stage edits update only visible browser state through documented deterministic dependencies and never trigger a new AI / backend recommendation. The launch / derive / wait mechanics live in [SKILL.md Step 4](../SKILL.md); the item specs below keep their `a`–`h` letters.+Do not force communication intent into one catalog label. A deck may report progress, expose risk, and request a decision in the same artifact; Stage 1 records that relationship in prose. Its editable prose fields are recommendation drafts, not required inputs: confirmation accepts the current text exactly, including blanks, and a cleared field must not be repopulated later. Stage 2 then confirms one complete solution: narrative spine, reading density, page budget, template strategy, visual system, and image direction. Present ≥3 coordinated design directions (safe / shifted / bold) so color, type, icons, and generated-image rendering begin coherent; the user may still override each component. Generated images inherit the selected deck colors directly—there is no second image-palette confirmation. Stage 3 asks only how to produce the locked solution. **Page count is derived, not an anchor**—it follows content volume × desired audience outcome × reading mode. Author each stage once: same-stage edits update only visible browser state through documented deterministic dependencies and never trigger a new AI / backend recommendation. The launch / derive / wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; the item specs below keep their `a`–`h` letters.> **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/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.+> **One opt-in exception**: present the spec-refinement line alongside the split-mode note ([`generate-pptx.md`](../workflows/generate-pptx.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 package through the interactive page: write recommendations to `<project>/confirm_ui/recommendations.json`, then launch per [SKILL.md Step 4](../SKILL.md). Stage 2 `design_directions` carries **≥3 coordinated candidates** (safe / shifted / bold); each bundles visual style, color, CJK + Latin typography, icons, and conditional generated-image rendering. This is one set of real alternatives, not independent candidate grids that happen to share a screen. Honest-shortfall exception: if the constraints genuinely cannot yield 3 non-conflicting directions, present the smaller set and say why—never pad with duplicates or conflicts. **Always also print the recommendations + URL in chat** as the 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 schema and lifecycle live in [SKILL.md Step 4](../SKILL.md) + [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md).+> **Default presentation surface — Confirm UI.** Deliver the package through the interactive page: write recommendations to `<project>/confirm_ui/recommendations.json`, then launch per [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4. Stage 2 `design_directions` carries **≥3 coordinated candidates** (safe / shifted / bold); each bundles visual style, color, CJK + Latin typography, icons, and conditional generated-image rendering. This is one set of real alternatives, not independent candidate grids that happen to share a screen. Honest-shortfall exception: if the constraints genuinely cannot yield 3 non-conflicting directions, present the smaller set and say why—never pad with duplicates or conflicts. **Always also print the recommendations + URL in chat** as the 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 schema and lifecycle live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4 + [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md).### a. Canvas Format Confirmation@@ -423,7 +423,7 @@ The script renders PNGs into `images/`, trying `codecogs`, `quicklatex`, `mathpa> **Default — human-scale topics lean illustrated (may override when factual assets dominate)**: When the source is about personal finance, family life, daily routines, education, wellness, healing, or children, and there are no supplied assets that already carry the story, recommend `image_usage: "ai"` instead of `none`. Use `image_notes.value` to name a warm illustration motif (for example a home ledger, school-day routine, care scene, or life-planning metaphor). Do not apply this default to regulated investor decks, B2B finance reports, or data-only dashboards; those stay eligible for `none` / `web` / `provided` by judgment.-> **Confirmed value wins.** The `image_usage` in `result.json` (or the chat reply) **overrides the recommendation here**. It may be a legacy single string or a Confirm UI multi-select array. Map every selected value to §VIII `Acquire Via` (`ai`→`ai`, `web`→`web`, `provided`→**`user`**, `placeholder`→`placeholder`, `none`→option A, no image rows). When it does not include `ai` (and no legacy prose plan includes AI), skip h.5 entirely and write no `ai` rows. If `image_notes` is present, honor it as the user's image intent while assigning per-page rows. See SKILL.md Step 4 for the full mapping.+> **Confirmed value wins.** The `image_usage` in `result.json` (or the chat reply) **overrides the recommendation here**. It may be a legacy single string or a Confirm UI multi-select array. Map every selected value to §VIII `Acquire Via` (`ai`→`ai`, `web`→`web`, `provided`→**`user`**, `placeholder`→`placeholder`, `none`→option A, no image rows). When it does not include `ai` (and no legacy prose plan includes AI), skip h.5 entirely and write no `ai` rows. If `image_notes` is present, honor it as the user's image intent while assigning per-page rows. See [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4 for the full mapping.> **Illustration roles at a glance (Reference).** Within the `image_usage` source boundary, illustrations can play several roles — pick by what the page needs; the **deck illustration motif** rule below threads them into one system. Mechanics live in the linked files.>@@ -762,7 +762,7 @@ Confirmation `d` locks two independent catalog items:- **Mode** — narrative skeleton: [`modes/_index.md`](./modes/_index.md) → `pyramid` / `narrative` / `instructional` / `showcase` / `briefing`.- **Visual style** — aesthetic: [`visual-styles/_index.md`](./visual-styles/_index.md) → presets + `custom`.-Read the relevant `_index.md` at confirmation `d` (Layer 1 / Layer 2) for its catalog table and auto-selection. Executor loads the locked mode + visual-style files at generation (see SKILL Step 6).+Read the relevant `_index.md` at confirmation `d` (Layer 1 / Layer 2) for its catalog table and auto-selection. Executor loads the locked mode + visual-style files at generation (see [`generate-pptx`](../workflows/generate-pptx.md) Step 6).---diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.mdindex e761661d..42de359c 100644--- a/skills/ppt-master/references/svg-image-embedding.md+++ b/skills/ppt-master/references/svg-image-embedding.md@@ -53,7 +53,7 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac├── Rendered formula → <image href="../images/formula_001.png" preserveAspectRatio="xMidYMid meet" .../>└── Placeholder / Needs-Manual without file → Dashed border + description text4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg-5. Post-processing & Export → follow [`SKILL.md` Step 7](../SKILL.md)+5. Post-processing & Export → follow [`generate-pptx.md`](../workflows/generate-pptx.md) Step 7```> Keep external references in `svg_output/` during generation. `finalize_svg.py` auto-embeds images into the mandatory `svg_final/` visual preview; native PPTX export independently reads `svg_output/`.@@ -130,12 +130,11 @@ python3 -m http.server -d <project_path> 8000## Conversion Process-Use the unified pipeline in [`SKILL.md` Step 7](../SKILL.md). `finalize_svg.py` remains mandatory and embeds image references into the self-contained `svg_final/` preview. The following PPTX command still reads `svg_output/` by default and converts it directly to native DrawingML; it does not consume `svg_final/` in the supported release route.--```bash-python3 scripts/finalize_svg.py <project_path>-python3 scripts/svg_to_pptx.py <project_path>-```+Follow [`generate-pptx.md`](../workflows/generate-pptx.md) Step 7; it owns the+serial post-processing and export commands. Its mandatory finalization step+embeds image references into the self-contained `svg_final/` preview, while the+supported native PPTX release still reads `svg_output/` and maps it directly to+DrawingML.### Standalone: align_embed_images.py (advanced)diff --git a/skills/ppt-master/scripts/confirm_ui/server.py b/skills/ppt-master/scripts/confirm_ui/server.pyindex 3641ada7..b2a072ab 100644--- a/skills/ppt-master/scripts/confirm_ui/server.py+++ b/skills/ppt-master/scripts/confirm_ui/server.py@@ -384,7 +384,7 @@ def _stage_skip_error(confirm_dir: Path) -> Optional[str]:return (f'stage skip detected: recommendations.json is {_stage_name(rec_stage_number)} but the last 'f'confirmed result is {result_stage or "absent"} — the page will not render a skipped stage. '- f'Stages confirm in order and an active template does not exempt stage2 (SKILL.md Step 4). '+ f'Stages confirm in order and an active template does not exempt stage2 (generate-pptx Step 4). 'f'Overwrite recommendations.json with the {expected} recommendations, then re-run with {reattach}.')diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex 0f8709a6..ea80d43f 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -1,20 +1,20 @@# Confirm UI — Strategist Confirmation Stage Page-> The interactive, visual surface for SKILL.md Step 4. Stage 1 is an open communication brief: common purpose paths are prompt text, never checkboxes or a forced single label. Stage 2 offers **≥3 coordinated design directions** and then exposes their component values for deliberate override; color, typography, icons, and generated-image rendering are one system rather than unrelated grids. Generated images inherit the selected deck colors directly—there is no image-palette control. Stage 3 contains production mechanics only. The AI writes `recommendations.json`; confirmed values accumulate into `result.json`. Final confirm saves the result and shuts the server down. The chat path mirrors the same staged semantics.+> The interactive, visual surface for [`generate-pptx`](../../workflows/generate-pptx.md) Step 4. Stage 1 is an open communication brief: common purpose paths are prompt text, never checkboxes or a forced single label. Stage 2 offers **≥3 coordinated design directions** and then exposes their component values for deliberate override; color, typography, icons, and generated-image rendering are one system rather than unrelated grids. Generated images inherit the selected deck colors directly—there is no image-palette control. Stage 3 contains production mechanics only. The AI writes `recommendations.json`; confirmed values accumulate into `result.json`. Final confirm saves the result and shuts the server down. The chat path mirrors the same staged semantics.## Authority and Scope| Concern | Owner ||---|---|-| Step 4 gate and pipeline order | `SKILL.md` |+| Step 4 gate and pipeline order | [`generate-pptx.md`](../../workflows/generate-pptx.md) || Confirm UI schema | This document || Stage 1 / Stage 2 / Stage 3 field membership | This document || Server launch / wait / shutdown behavior | This document || Port and lock behavior | This document || Chat fallback equivalence | This document |-| Confirmed-value precedence | `SKILL.md` plus this document's `result.json` contract |+| Confirmed-value precedence | [`generate-pptx.md`](../../workflows/generate-pptx.md) plus this document's `result.json` contract |-**Hard rule**: Keep detailed Confirm UI behavior here. `SKILL.md` may summarize the orchestration, but it should not duplicate the full JSON schema, catalog behavior, or launcher lifecycle.+**Hard rule**: Keep detailed Confirm UI behavior here. The Generate route may summarize orchestration, but it should not duplicate the full JSON schema, catalog behavior, or launcher lifecycle.**Fallback rule**: Browser failure never cancels Step 4. Re-check `result.json` once, then use the chat confirmation path with the same three-stage semantics. Stage-1 chat prompts remain open questions; do not turn the hint vocabulary into a numbered selection.@@ -36,7 +36,7 @@ python3 scripts/confirm_ui/server.py <project_path> --shutdown # Step 4 clean- **Shares port 5050 with the live preview server** (`svg_editor/server.py`). The two never run at once: confirm is Step 4, live preview is Step 6, and Step 4 always shuts this server down on exit (see `--shutdown`) so the port is free. One port = one forward rule for the whole pipeline. They still keep **separate processes and locks** (`.confirm_ui.lock` vs `.live_preview.lock`).- `--daemon` starts the Flask process in the background; add `--wait` in the main pipeline so the parent command returns only after the page writes a fresh `result.json`. The `--wait` budget defaults to **590 s** (`--wait-timeout`), kept under the typical 600 s tool ceiling — run the launch with a long tool timeout (≈600000 ms). On timeout the parent returns non-zero but the detached server keeps running, so the caller must re-check `result.json` once before the chat fallback (a slow user may confirm just after the wait returns).- `--wait-only` attaches to the page already running from the first `--daemon --wait` and blocks until the page writes the requested stage. If the recorded server died, it automatically restarts on the recorded/default port so polling reconnects. Use `--wait-stage stage2` for the complete-solution handoff, then the default `--wait-stage final` for Stage 3. It keys on stage alone (no mtime gate), because a user may submit before the wait command starts.-- `--shutdown` stops a confirm server left running for this project and exits — **idempotent** (a no-op when nothing is running). Tries a graceful `/api/shutdown`, falls back to killing the recorded pid, then clears the lock. SKILL.md Step 4 runs this on every path (page-confirm or chat-fallback) so the page never lingers on the shared port before live preview starts.+- `--shutdown` stops a confirm server left running for this project and exits — **idempotent** (a no-op when nothing is running). Tries a graceful `/api/shutdown`, falls back to killing the recorded pid, then clears the lock. Generate Step 4 runs this on every path (page-confirm or chat-fallback) so the page never lingers on the shared port before live preview starts.- Refuses to start unless `<project_path>/confirm_ui/recommendations.json` exists (except `--shutdown`, which needs no recommendations).- Per-project lock at `<project_path>/.confirm_ui.lock` — duplicate launches are refused; stale locks (dead pid) are overwritten.- Idle auto-shutdown after 900 s by default; `/api/shutdown` exits gracefully and releases the lock.@@ -198,7 +198,7 @@ After Stage 2 is confirmed, overwrite it with Stage-3 production recommendations- **Combined style preview** — a compact live "overall impression" strip sits just above the color section and is **sticky**: it pins under the topbar so it stays visible while the user scrolls through the color / icon / typography sections, keeping the picking controls and their combined effect on screen together. It applies the currently selected color palette **and** typography (heading sample in `primary` over `background`, body sample in `body_text`, an `accent` bar, a `secondary_bg` chip) and repaints on every color / HEX-override / font / `body_size` change. It does not replace the per-candidate swatches or font samples (those stay for picking); it is deliberately an abstract style chip, **not** a slide-layout preview — page layout preview remains the live-preview server's job (Step 6). No schema field; it derives entirely from the existing color + typography selections.- **Generated-image direction** is a rendering decision inside each `design_directions` candidate and is shown only when `image_usage` includes `ai`. Each object records `rendering` plus short `visual` / `mood` prose. The right-side image section renders up to three recommended cards with one reference thumbnail each in a single row; Custom occupies a separate full-width row below them. The left preview simultaneously shows the currently selected generated-image rendering at a larger size, updating immediately when the user changes the right-side selection. The UI writes no `palette` or `color` field: final image colors come directly from the selected deck `color.palette`. Legacy `image_strategy.palette` input is accepted but ignored for color and stripped from new submissions.- **`design_directions`** is the canonical Stage-2 personality spectrum. Each candidate carries localized name / note, `visual_style`, `color`, `typography`, `icons`, and conditional `image_strategy`. Author ≥3 spanning safe / shifted / bold (honest-shortfall exception applies). Selecting one applies the whole bundle; the component controls below are advanced overrides. The bundle itself is presentation-only—`result.json` stores the actual selected components, not a direction id.-- `recommend.generation_mode` and `refine_spec` mirror the two mandatory notes in SKILL.md Step 4. Confirmed `generation_mode: "split"` / `refine_spec: true` are explicit user choices, equivalent to opting in through chat.+- `recommend.generation_mode` and `refine_spec` mirror the two mandatory notes in [`generate-pptx`](../../workflows/generate-pptx.md) Step 4. Confirmed `generation_mode: "split"` / `refine_spec: true` are explicit user choices, equivalent to opting in through chat.- `content_divergence` is a **free-text** Stage-1 source-treatment field. Blank means a balanced default; facts stay sourced at every level. Strategist consumes it while authoring §IX and records it in `design_spec.md §I`; it is not written to `spec_lock.md`. Beautify sends `{ "value": "keep source wording and page structure verbatim", "locked": true }`, so the UI displays it read-only and the server restores it on every staged submit. Template-fill does not use this confirmation flow and does not surface it.- `lang` is a soft default (`zh` / `en` / `ja` — the page UI supports all three); an explicit user language choice in the page (persisted to `localStorage`) wins.diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 623fff26..eec26bf6 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -226,14 +226,29 @@ Do not confuse this tool with `extract_svg_assets.py`:## Recommended Pipeline-Run these steps in order:+Run these steps one at a time. Wait for each command to exit successfully before+starting the next command.```bashpython3 scripts/total_md_split.py <project_path>+```++After `total_md_split.py` exits successfully, run:++```bashpython3 scripts/finalize_svg.py <project_path>+```++After `finalize_svg.py` exits successfully, run:++```bashpython3 scripts/svg_to_pptx.py <project_path>```+Do not start another post-processing command while the current command is still+running. The canonical gates and success criteria are owned by+[`generate-pptx.md`](../../workflows/generate-pptx.md) Step 7.+## `finalize_svg.py`Unified post-processing entry point. This is the preferred way to run SVG cleanup.@@ -264,10 +279,13 @@ python3 scripts/svg_to_pptx.py <project_path> -t nonepython3 scripts/svg_to_pptx.py <project_path> --auto-advance 3python3 scripts/svg_to_pptx.py <project_path> --animation mixed --animation-duration 0.8python3 scripts/svg_to_pptx.py <project_path> --no-merge # strict line-fidelity mode (see below)-python3 scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeuralpython3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio```+For generated-project narration, follow the+[`generate-audio`](../../workflows/stages/generate-audio.md) stage. It owns voice+selection, audio generation, and the narrated re-export workflow.+Behavior:- Default output (default-flow mode, no `-o`):- `exports/<project_name>_<timestamp>.pptx` — native editable pptx (canonical output)diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex a3b5be4f..2ab88f46 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -11,16 +11,18 @@"skills/ppt-master/templates/charts/charts_index.json"],"exclude": [],- "max_tokens": 375000+ "max_tokens": 365000},"file_budgets": {"AGENTS.md": 2200,- "skills/ppt-master/SKILL.md": 25500,+ "skills/ppt-master/SKILL.md": 800,"skills/ppt-master/references/executor-base.md": 16500,"skills/ppt-master/references/shared-standards.md": 33000,"skills/ppt-master/references/strategist.md": 25000,"skills/ppt-master/templates/design_spec_reference.md": 7700,- "skills/ppt-master/templates/spec_lock_reference.md": 5800+ "skills/ppt-master/templates/spec_lock_reference.md": 5800,+ "skills/ppt-master/workflows/generate-pptx.md": 15000,+ "skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800},"load_sets": {"bootstrap.routing": {@@ -29,11 +31,9 @@"files": ["AGENTS.md","skills/ppt-master/SKILL.md",- "skills/ppt-master/workflows/routing.md",- "skills/ppt-master/workflows/index.md",- "skills/ppt-master/references/artifact-ownership.md"+ "skills/ppt-master/workflows/routing.md"],- "max_tokens": 34500+ "max_tokens": 5000},"route.create-template.brand": {"description": "Create Brand path; Template_Designer is not activated.",@@ -47,7 +47,7 @@"skills/ppt-master/templates/README.md","skills/ppt-master/templates/brands/README.md"],- "max_tokens": 59500+ "max_tokens": 30000},"route.create-template.deck": {"description": "Create Deck path through Template_Designer and shared SVG constraints.",@@ -64,7 +64,7 @@"skills/ppt-master/templates/README.md","skills/ppt-master/templates/decks/README.md"],- "max_tokens": 104500+ "max_tokens": 75000},"route.create-template.layout": {"description": "Create Layout path through Template_Designer and shared SVG constraints.",@@ -81,7 +81,7 @@"skills/ppt-master/templates/README.md","skills/ppt-master/templates/layouts/README.md"],- "max_tokens": 104500+ "max_tokens": 75000},"route.enhance-native-pptx": {"description": "Finished-PPTX native enhancement route.",@@ -92,7 +92,7 @@"files": ["skills/ppt-master/workflows/native-enhance-pptx.md"],- "max_tokens": 37500+ "max_tokens": 8000},"route.fill-native-pptx": {"description": "Raw-PPTX native fill route.",@@ -103,7 +103,7 @@"files": ["skills/ppt-master/workflows/template-fill-pptx.md"],- "max_tokens": 40500+ "max_tokens": 11000},"route.generate.planning": {"description": "Fixed Generate-PPTX planning context through Strategist output.",@@ -112,6 +112,8 @@"bootstrap.routing"],"files": [+ "skills/ppt-master/workflows/generate-pptx.md",+ "skills/ppt-master/references/artifact-ownership.md","skills/ppt-master/references/strategist.md","skills/ppt-master/templates/design_spec_reference.md","skills/ppt-master/templates/spec_lock_reference.md",@@ -130,7 +132,7 @@"registry": "visual-styles"}],- "max_tokens": 91500+ "max_tokens": 80000},"route.generate.planning-image": {"description": "Generate-PPTX planning context when the image resource list is active.",@@ -141,7 +143,7 @@"files": ["skills/ppt-master/references/image-layout-patterns.md"],- "max_tokens": 97500+ "max_tokens": 86000},"route.generate.planning-ai": {"description": "Generate-PPTX planning context when AI image direction is available.",@@ -152,7 +154,108 @@"files": ["skills/ppt-master/references/image-renderings/_index.md"],- "max_tokens": 99500+ "max_tokens": 88000+ },+ "stage.generate.apply-template-workspace": {+ "description": "Conditional Step 3 workspace validation, installation, and fusion framework.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/workflows/stages/apply-template-workspace.md",+ "skills/ppt-master/templates/README.md"+ ],+ "max_tokens": 3300+ },+ "stage.generate.template.brand": {+ "description": "Conditional Brand workspace application with one selected Brand spec.",+ "scope": "incremental",+ "include": [+ "stage.generate.apply-template-workspace"+ ],+ "files": [+ "skills/ppt-master/templates/brands/README.md",+ {+ "glob": "skills/ppt-master/templates/brands/*/templates/design_spec.md",+ "select": 1,+ "load_event": "template-application"+ }+ ],+ "max_tokens": 5200+ },+ "stage.generate.template.layout": {+ "description": "Conditional Layout workspace application with one selected Layout spec.",+ "scope": "incremental",+ "include": [+ "stage.generate.apply-template-workspace"+ ],+ "files": [+ "skills/ppt-master/templates/layouts/README.md",+ {+ "glob": "skills/ppt-master/templates/layouts/*/templates/design_spec.md",+ "select": 1,+ "load_event": "template-application"+ }+ ],+ "max_tokens": 6400+ },+ "stage.generate.template.deck": {+ "description": "Conditional Deck workspace application with one selected Deck spec.",+ "scope": "incremental",+ "include": [+ "stage.generate.apply-template-workspace"+ ],+ "files": [+ "skills/ppt-master/templates/decks/README.md",+ {+ "glob": "skills/ppt-master/templates/decks/*/templates/design_spec.md",+ "select": 1,+ "load_event": "template-application"+ }+ ],+ "max_tokens": 6200+ },+ "stage.generate.template.brand-two": {+ "description": "Same-kind conflict path with two selected Brand specs.",+ "scope": "incremental",+ "include": [+ "stage.generate.apply-template-workspace"+ ],+ "files": [+ "skills/ppt-master/templates/brands/README.md",+ {+ "glob": "skills/ppt-master/templates/brands/*/templates/design_spec.md",+ "select": 2,+ "load_event": "template-application"+ }+ ],+ "max_tokens": 6200+ },+ "stage.generate.template.fusion-brand-layout-deck": {+ "description": "Maximum supported cross-kind fusion with one Brand, Layout, and Deck spec.",+ "scope": "incremental",+ "include": [+ "stage.generate.apply-template-workspace"+ ],+ "files": [+ "skills/ppt-master/templates/brands/README.md",+ "skills/ppt-master/templates/layouts/README.md",+ "skills/ppt-master/templates/decks/README.md",+ {+ "glob": "skills/ppt-master/templates/brands/*/templates/design_spec.md",+ "select": 1,+ "load_event": "template-application"+ },+ {+ "glob": "skills/ppt-master/templates/layouts/*/templates/design_spec.md",+ "select": 1,+ "load_event": "template-application"+ },+ {+ "glob": "skills/ppt-master/templates/decks/*/templates/design_spec.md",+ "select": 1,+ "load_event": "template-application"+ }+ ],+ "max_tokens": 11000},"route.generate.flat-no-image": {"description": "Default fixed Generate-PPTX context with no image-acquisition role.",@@ -162,7 +265,7 @@"stage.generate.executor.flat"],"files": [],- "max_tokens": 146500+ "max_tokens": 135000},"route.generate.flat-ai-two-types": {"description": "Generate-PPTX context with AI images, one rendering, and two local types.",@@ -173,7 +276,7 @@"stage.generate.image.ai-two-types"],"files": [],- "max_tokens": 175500+ "max_tokens": 163500},"route.generate.flat-in-hand-image": {"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",@@ -183,7 +286,7 @@"stage.generate.executor.flat"],"files": [],- "max_tokens": 152500+ "max_tokens": 140500},"route.generate.flat-web-image": {"description": "Generate-PPTX context with web image acquisition.",@@ -194,7 +297,7 @@"stage.generate.image.web"],"files": [],- "max_tokens": 159500+ "max_tokens": 147500},"route.enhance-native-pptx.audio": {"description": "Enhance Native PPTX with the shared narration-audio stage.",@@ -204,7 +307,7 @@"stage.shared.generate-audio"],"files": [],- "max_tokens": 40500+ "max_tokens": 11000},"route.generate.beautify-flat-no-image": {"description": "Generate-PPTX 1:1 beautify profile on the flat no-image path.",@@ -214,7 +317,7 @@"profile.generate.beautify-pptx"],"files": [],- "max_tokens": 153000+ "max_tokens": 141500},"route.generate.flat-no-image-chart": {"description": "Default flat Generate-PPTX path with the chart verification stage.",@@ -225,55 +328,40 @@"stage.generate.verify-charts"],"files": [],- "max_tokens": 164500+ "max_tokens": 152500},"route.generate.brand-flat-no-image": {"description": "Brand-preset flat Generate-PPTX path without image acquisition.","scope": "cumulative","include": ["route.generate.planning",- "stage.generate.executor.flat"- ],- "files": [- {- "glob": "skills/ppt-master/templates/brands/*/templates/design_spec.md",- "select": 1,- "load_event": "template-selection"- }+ "stage.generate.executor.flat",+ "stage.generate.template.brand"],- "max_tokens": 147500+ "files": [],+ "max_tokens": 139500},"route.generate.deck-structured-no-image": {"description": "Deck-preset structured Generate-PPTX path without image acquisition.","scope": "cumulative","include": ["route.generate.planning",- "stage.generate.executor.structured"+ "stage.generate.executor.structured",+ "stage.generate.template.deck"],- "files": [- {- "glob": "skills/ppt-master/templates/decks/*/templates/design_spec.md",- "select": 1,- "load_event": "template-selection"- }- ],- "max_tokens": 148000+ "files": [],+ "max_tokens": 140500},"route.generate.layout-structured-no-image": {"description": "Layout-preset structured Generate-PPTX path without image acquisition.","scope": "cumulative","include": ["route.generate.planning",- "stage.generate.executor.structured"+ "stage.generate.executor.structured",+ "stage.generate.template.layout"],- "files": [- {- "glob": "skills/ppt-master/templates/layouts/*/templates/design_spec.md",- "select": 1,- "load_event": "template-selection"- }- ],- "max_tokens": 148000+ "files": [],+ "max_tokens": 141000},"route.generate.topic-only-flat-no-image": {"description": "Topic research followed by the default flat no-image Generate-PPTX path.",@@ -283,7 +371,7 @@"route.generate.flat-no-image"],"files": [],- "max_tokens": 148000+ "max_tokens": 136500},"stage.generate.executor.flat": {"description": "Incremental flat Executor rules with one locked mode and visual style.",@@ -369,17 +457,17 @@"description": "Fresh-session resume plus the shared Executor set and resume-only image references.","scope": "fresh-session","include": [+ "bootstrap.routing","stage.generate.executor.flat"],"files": [- "AGENTS.md",- "skills/ppt-master/SKILL.md",+ "skills/ppt-master/workflows/generate-pptx.md","skills/ppt-master/workflows/stages/resume-execute.md","skills/ppt-master/references/artifact-ownership.md","skills/ppt-master/references/image-layout-spec.md","skills/ppt-master/references/svg-image-embedding.md"],- "max_tokens": 92500+ "max_tokens": 84000},"stage.generate.topic-research": {"description": "Topic-only intake stage.",@@ -451,6 +539,14 @@],"max_tokens": 18500},+ "stage.generate.animation-options": {+ "description": "Conditional deck-wide transition, auto-advance, and entrance-animation options.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/animations.md"+ ],+ "max_tokens": 4500+ },"stage.shared.generate-audio": {"description": "Shared narration-audio stage.","scope": "incremental",@@ -553,7 +649,7 @@},"authority_edges": [{- "concern": "main-workflow",+ "concern": "package-entry","from": "AGENTS.md","to": "skills/ppt-master/SKILL.md"},@@ -563,15 +659,50 @@"to": "skills/ppt-master/workflows/routing.md"},{- "concern": "failure-policy",+ "concern": "route-selection","from": "skills/ppt-master/SKILL.md",+ "to": "skills/ppt-master/workflows/routing.md"+ },+ {+ "concern": "generate-workflow",+ "from": "skills/ppt-master/workflows/routing.md",+ "to": "skills/ppt-master/workflows/generate-pptx.md"+ },+ {+ "concern": "failure-policy",+ "from": "skills/ppt-master/workflows/generate-pptx.md","to": "skills/ppt-master/workflows/governance/failure-recovery.md"},{"concern": "artifact-ownership",- "from": "skills/ppt-master/SKILL.md",+ "from": "skills/ppt-master/workflows/generate-pptx.md","to": "skills/ppt-master/references/artifact-ownership.md"},+ {+ "concern": "template-application",+ "from": "skills/ppt-master/workflows/generate-pptx.md",+ "to": "skills/ppt-master/workflows/stages/apply-template-workspace.md"+ },+ {+ "concern": "template-model",+ "from": "skills/ppt-master/workflows/stages/apply-template-workspace.md",+ "to": "skills/ppt-master/templates/README.md"+ },+ {+ "concern": "template-kind-schema",+ "from": "skills/ppt-master/workflows/stages/apply-template-workspace.md",+ "to": "skills/ppt-master/templates/brands/README.md"+ },+ {+ "concern": "template-kind-schema",+ "from": "skills/ppt-master/workflows/stages/apply-template-workspace.md",+ "to": "skills/ppt-master/templates/layouts/README.md"+ },+ {+ "concern": "template-kind-schema",+ "from": "skills/ppt-master/workflows/stages/apply-template-workspace.md",+ "to": "skills/ppt-master/templates/decks/README.md"+ },{"concern": "svg-technical-contract","from": "skills/ppt-master/references/executor-base.md",@@ -733,6 +864,10 @@],"coverage": {"exempt": [+ {+ "glob": "skills/ppt-master/workflows/index.md",+ "reason": "Maintainer-only workflow inventory; never loaded during task execution."+ },{"glob": "skills/ppt-master/references/ai-image-comparison/README.md","reason": "Maintenance-only comparison-gallery overview; never loaded by generation roles."diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.mdindex b8bc77bf..4350c769 100644--- a/skills/ppt-master/templates/README.md+++ b/skills/ppt-master/templates/README.md@@ -34,8 +34,9 @@ which keeps the fixed route name and dispatches exactly one child workflow:[`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 an-explicit workspace-root path supplied by the user.+The indexes are discovery aids only. [`generate-pptx`](../workflows/generate-pptx.md)+Step 3 activates a template only from an explicit workspace-root path supplied+by the user or an exact validated Create Template handoff.## Orthogonal contracts@@ -66,9 +67,10 @@ initialized project:Empty optional directories are omitted. Template SVGs reference bitmaps through`../images/<name>` and imported vectors through `data-icon="imported/<name>"`.-Step 3 consumes `templates/`, `images/`, and `icons/` and ignores `exports/`.-Compatible legacy-flat packages remain readable; directory shape alone does not-indicate legacy Master/Layout semantics.+The conditional [`apply-template-workspace`](../workflows/stages/apply-template-workspace.md)+stage owns installation and fusion: it consumes `templates/`, `images/`, and+`icons/` and ignores `exports/`. Compatible legacy-flat packages remain+readable; directory shape alone does not indicate legacy Master/Layout semantics.## Design specification referencesdiff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.mdindex 36f04033..b4c054cc 100644--- a/skills/ppt-master/templates/brands/README.md+++ b/skills/ppt-master/templates/brands/README.md@@ -9,18 +9,13 @@ kind and workspace model lives in the parent [`README.md`](../README.md).## How brands are consumed-Brand application follows the **same explicit-path rule and workspace routing as all template kinds** at SKILL.md Step 3:--| User input at SKILL.md Step 3 | Behavior |-|---|---|-| An explicit brand workspace path (e.g. `templates/brands/anthropic/`) | Resolve `templates/design_spec.md`; stage `templates/` plus any existing `images/` and `icons/` into the matching project directories; Strategist locks the identity segment |-| Bare brand name only ("use anthropic brand"), brand mention without path, or silence | Skip — same mechanical rule as all template kinds: bare names never trigger |-| Brand path + layout path | Fuse into one `design_spec.md` — brand owns identity segment (color / typography / logo / voice / icon style); layout owns structure segment (canvas / page roster). See `SKILL.md` Step 3. |-| Brand path + deck path | Fuse — brand identity overrides deck identity; structure + application segments come from deck |-| Brand path + layout path + deck path | Three-way fuse — brand=identity, layout=structure, deck=application, subject to application/structure compatibility |-| Two brand paths | Conflict resolution prompt before fusion — user picks per-segment source |--`brands_index.json` is discovery-only; listing brands never advances the pipeline.+Brand application follows the common explicit-path trigger in+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The conditional+[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)+stage owns path normalization, portable-root installation, multi-kind fusion,+same-kind conflict resolution, and provenance. This file owns only the Brand+schema. `brands_index.json` is discovery-only; listing brands never advances+the pipeline.## Creating a new brand@@ -55,4 +50,4 @@ Logo filenames are descriptive, not contractual — `templates/design_spec.md`[brands_index.json](./brands_index.json) is a slim machine-readable map (`brand_id → { summary, primary_color }`). Refresh it with `register_template.py --kind brand <brand_id>` after a brand is created or edited. Registration rejects incomplete frontmatter, mismatched IDs, page SVGs, missing required identity sections, invalid or inconsistent colors/provenance, and broken workspace-local asset references.-Listing the index does not trigger any pipeline action — Step 3 triggers only on an explicit directory path supplied by the user, regardless of whether the brand appears in the index.+Listing the index does not trigger any pipeline action — Generate Step 3 triggers only on an explicit directory path supplied by the user or an exact validated Create Template handoff, regardless of whether the brand appears in the index.diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.mdindex a8b10879..24f0b8e2 100644--- a/skills/ppt-master/templates/decks/README.md+++ b/skills/ppt-master/templates/decks/README.md@@ -30,21 +30,12 @@ Overview when application fit must be judged in detail.## Trigger and fusion-Selection is opt-in through an explicit workspace-root path such as-`skills/ppt-master/templates/decks/<deck_id>/`. Supplying a bare ID or reading-the discovery index does not trigger template use. Current packages resolve-`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 brand-or layout path, brand replaces the identity segment and layout may replace the-structure segment; the deck remains the source of the application contract.-Before a Layout override is accepted, its page roles and slot capabilities must-support the Deck's required narrative/content roles. Treat an incompatibility-as a fusion conflict instead of retaining an application promise the new-structure cannot satisfy. Fusion never changes the package's stored SVGs in-place.+Selection uses the common explicit-path trigger in+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. Supplying a bare ID+or reading the discovery index does not trigger template use. The conditional+[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)+stage owns path normalization, compatibility checks, installation, and fusion.+This file owns the Deck schema and application contract.---diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.mdindex 6486c735..97731287 100644--- a/skills/ppt-master/templates/layouts/README.md+++ b/skills/ppt-master/templates/layouts/README.md@@ -46,16 +46,12 @@ kind of rule is never a mirror operation.## Trigger and identity boundary-Selection is opt-in through an explicit workspace-root path such as-`skills/ppt-master/templates/layouts/<layout_id>/`. Supplying a bare ID or-reading the discovery index does not trigger template use. A layout path alone-locks structure while identity remains a downstream decision. Combined with a-brand or deck, the layout replaces the complete structure segment.--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.+Selection uses the common explicit-path trigger in+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. Supplying a bare ID+or reading the discovery index does not trigger template use. The conditional+[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)+stage owns path normalization, compatibility checks, installation, and fusion.+This file owns the Layout schema and its identity/application boundary.---diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 13284f7f..9ac0ab11 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -16,7 +16,7 @@ Create one reusable template workspace under either the **global template librar**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. Create Template must not create an optional directory or placeholder file solely to retain an empty path. An initialized project may already contain empty `images/`, `icons/`, or `exports/` scaffolding; leave it untouched, do not count it as template output, and omit the path from completion unless this workflow wrote or adopted a real file there. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.-> **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.+> **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 [`generate-pptx`](./generate-pptx.md) 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.## Child Workflow Dispatch@@ -32,7 +32,7 @@ Select Create Brand only for identity-only intent. Select Create Layout only wheSee [`templates/README.md`](../templates/README.md) for the shared kind andworkspace model. Downstream template application and fusion remain owned by-[`SKILL.md`](../SKILL.md) Step 3.+[`generate-pptx.md`](./generate-pptx.md) Step 3.## Output scope — library (default) vs project@@ -770,7 +770,7 @@ Outputs by kind (the JSON index is the single source of truth — READMEs descriThe completion card's file roster is collected by globbing `templates/*.svg` in the workspace. Legacy flat packages still use their root `*.svg` roster.-The index file is a **discovery index** — it lets the AI answer "what templates are available?" by listing names and workspace-root paths. It is **not** consulted to trigger Step 3 (SKILL.md). Step 3 triggers on an explicit workspace-root path supplied by the user, regardless of whether that path is registered. An unregistered workspace still works when the user gives its path; it just will not appear in discovery listings.+The index file is a **discovery index** — it lets the AI answer "what templates are available?" by listing names and workspace-root paths. It is **not** consulted to trigger [`generate-pptx`](./generate-pptx.md) Step 3. Step 3 triggers on an explicit workspace-root path supplied by the user, regardless of whether that path is registered. An unregistered workspace still works when the user gives its path; it just will not appear in discovery listings.> **Recommended for new templates**: declare a YAML frontmatter block at the top of `design_spec.md`. The registrar prefers it over prose extraction:>diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdnew file mode 100644index 00000000..2e7f67b1--- /dev/null+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -0,0 +1,499 @@+---+description: Generate PPTX route authority for source intake, planning, SVG authoring, quality gates, and native PPTX export.+---++# Generate PPTX Route++> Load only after [`routing.md`](./routing.md) selects Generate PPTX. This file owns the route's Step 1–7 sequence, gates, role switching, and mandatory commands.++**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist Structured Plan → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export`++**Generate-specific execution discipline**:++- The current main agent hand-writes every SVG page; never delegate page generation or run a Python, Node, or shell generator over `svg_output/`.+- Generate pages sequentially, one page at a time, in one continuous pass; grouped page batches are forbidden.+- Before each page, re-read `<project_path>/spec_lock.md` and apply the current communication, design, resource, rhythm, chart, and conditional template mappings.+- `preset_shape_svg.py` may provide one stdout fragment only after the main agent chooses its semantic role, frame, and paint; it cannot choose layout or write a page.++### SVG Page-Design Boundary++| Scope | Contract |+|---|---|+| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. |+| Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. |+| 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. |+| 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.”++## Cross-Cutting Authorities++| Concern | Authority | Contract |+|---|---|---|+| Main pipeline sequencing | This file | Owns Step 1–7 order, gates, role switching, and mandatory commands |+| Artifact ownership | [`artifact-ownership.md`](../references/artifact-ownership.md) | Owns fact channels, source/derived artifact boundaries, and regeneration rules |+| Failure recovery | [`failure-recovery.md`](./governance/failure-recovery.md) | Owns stop/continue policy and resume pointers |+| Confirm UI details | [`confirm_ui.md`](../scripts/docs/confirm_ui.md) | Owns schema, launcher behavior, port strategy, and chat fallback details |+| Explicit template workspace | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) | Owns Step 3 validation, installation, and fusion; load only when Step 3's explicit-path trigger fires |++## Workflow++### Step 1: Source Content Processing++🚧 **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`](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 the+unified dispatcher. It preserves the backend converters' existing behavior,+routes by source type, and writes the standard Markdown plus conversion profile.++| User Provides | Action |+|---------------|--------|+| PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` |+| CSV / TSV | Read directly as plain-text table source |+| Markdown | Read directly |++For PPTX sources, Step 1 converts the deck to Markdown content; after Step 2+`import-sources`, standard PPTX intake is also written to `<project>/analysis/`.+Use `source_to_md.py -t <type>` only when extension detection is ambiguous.+Default local conversion writes Markdown/profile outputs beside each source file.+Use `-o` only when a specific output file/directory is required; with multiple+inputs or directory inputs, `-o` is an output directory. Backend converter details are documented in+[`scripts/docs/conversion.md`](../scripts/docs/conversion.md).++> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:+> Source conversion extracts embedded Office vector images (.emf/.wmf)+> alongside bitmap images when the source format exposes them. After `import-sources`, these land in `images/`+> together with `image_manifest.json` and are first-class assets in §VIII Image Resource List.+>+> **Do NOT convert EMF/WMF to PNG.** The PPT Master pipeline preserves them as external+> references (`finalize_svg.py` skips them) and `svg_to_pptx.py` embeds them as+> PPTX-native media via `image/x-emf` / `image/x-wmf` MIME — PowerPoint renders them at full vector fidelity.+> Converting via LibreOffice/Inkscape introduces CJK font substitution drift and+> rasterization loss; the original EMF/WMF is always higher fidelity than the converted PNG.+>+> Browser-based live preview cannot render EMF (will show blank) — this is expected;+> the PPTX output is the source of truth.++**✅ Checkpoint — Confirm source content is ready, proceed to Step 2.**++---++### Step 2: Project Initialization++🚧 **GATE**: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid).++```bash+python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>+```++Format options must be named with concrete dimensions. Default: `ppt169` = `1280x720`, `viewBox="0 0 1280 720"`. Other examples: `ppt43` = `1024x768`, `story` = `1080x1920`, `banner` = `1920x1080`. For the full format list, see `references/canvas-formats.md`.++Import source content (choose based on the situation):++| Situation | Action |+|-----------|--------|+| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move` |+| User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |++For PPTX sources, `import-sources` automatically runs the standard intake enrichment:++```bash+python3 ${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; 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 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.++**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**++---++### Step 3: Template Option++🚧 **GATE**: Step 2 complete; project directory structure is ready.++**Default — free design**: Proceed directly to Step 4. Do not query any `*_index.json`, ask about templates, suggest a local template, or fuzzy-match a name from content, brand mentions, or style language.++**Explicit-path trigger only**: Load and run [`apply-template-workspace.md`](./stages/apply-template-workspace.md) only when either condition is true:++- The user supplied one or more explicit workspace-root paths.+- Create Template completed in the current conversation and handed off its exact validated workspace root.++Bare names, style descriptions, brand mentions, vague template intent, and silence do not trigger the runbook. There is no slug lookup or fuzzy path resolution.++**Raw PPTX boundary**: A raw PPTX remains valid source material, but it is not a Step 3 workspace. Raw PPTX plus new content uses [`template-fill-pptx`](./template-fill-pptx.md). To create a reusable workspace, run [`create-template`](./create-template.md), then return with the generated root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.++> “What templates exist?” is out-of-band Q&A. List indexed workspace paths, then stop; listing does not trigger Step 3. The user must send an explicit path.++**✅ Checkpoint**: Free design selected without loading template details, or the conditional template runbook completed and `<project_path>/templates/` plus any portable assets are ready.++---++### Step 4: Strategist Phase (MANDATORY — cannot be skipped)++🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied or confirmed in place in the project.++First, read the role definition:+```+Read references/strategist.md+```++> ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–X section structure. See `strategist.md` Section 1.++**Artifact ownership**: fact-channel and source/derived artifact boundaries are defined in [`references/artifact-ownership.md`](../references/artifact-ownership.md). This Step uses those ownership rules; it does not redefine them.++**`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Strategist confirmation stage, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table / SmartArt entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.)++**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, chart data values, and SmartArt node wording come from these (`ppt_to_md` transcribes native charts as Markdown tables and SmartArt nodes as hierarchical bullets). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table / diagram entries are a **structural digest** for outline decisions (which slides carried charts, tables, or SmartArt; chart types / series names; SmartArt layout and hierarchy) — not a second copy of the content values; do NOT also pull chart values or SmartArt wording from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract while preserving SmartArt unchanged; beautify uses it for native chart / table data and SmartArt relationships while keeping all wording from the Markdown.++**Strategist confirmation stage** (full template: `templates/design_spec_reference.md`):++⛔ **BLOCKING**: present the Strategist confirmation stage and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation gate — once the final confirmation lands, all subsequent steps proceed automatically. The default Confirm UI delivers the gate in **three stages** (communication contract → complete deck solution → resources / production; see below); the chat fallback mirrors the same staged order.++1. Communication contract — target audience; open-ended `communication_intent` (one or several purposes, with priority / sequence when useful); desired `audience_outcome`; `core_message` / decision ask / action; delivery context; artifact afterlife+2. Source-treatment intent — open-ended `content_divergence`; facts remain sourced at every level+3. Canvas format+4. Complete deck solution — reading mode (JSON compatibility key `delivery_purpose`); narrative mode; page count; visual / template direction; color; icons; typography; image sources and generated-image rendering+5. Production plan — conditional AI-image acquisition path; formula rendering policy; execution mode; optional spec-refinement toggle++**Confirm UI Auto-Launch (Mandatory — default visual confirmation surface)**: by default the Strategist confirmation stage is presented through an interactive local page in **three stages within one browser session**. Stage 1 confirms the scene and communication contract before asking the user to select tools. The AI then authors Stage 2's **complete deck solution once** from the user's actual contract: argument structure, reading density, template use, visual system, and image direction are judged together. After Stage 2 is confirmed, Stage 3 is authored once and asks only how to produce the already-decided solution. A change inside the current page never asks the AI or server to regenerate that stage. Color swatches, live font previews, icon samples, rendering references, and coordinated direction candidates appear where they help judgment; the chat path is the always-valid fallback. [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the schema, server lifecycle, port strategy, and fallback details; this section keeps the orchestration contract. The split:++| Stage | Confirms | Driven by |+|---|---|---|+| **1 — communication contract** | audience · open-ended `communication_intent` (may combine several purposes) · `audience_outcome` · `core_message` / delivery context / artifact afterlife · `content_divergence` (all prose fields may be blank) · canvas | the source + user intent |+| **2 — complete deck solution** (derived once from Stage 1) | reading mode (`delivery_purpose`, PPT only) · narrative `mode` · page count · `visual_style` · conditional template reuse / adherence · color · typography · icons · image usage · generated-image rendering | the confirmed communication contract |+| **3 — resources / production** (derived once from Stage 1 + Stage 2) | conditional AI-image acquisition path · formula policy · generation mode · refine-spec toggle | the confirmed solution |++> **Why three stages.** A presentation may serve several purposes at once (for example, report progress, expose risk, and request a decision), so Stage 1 uses open prose rather than a purpose enum. Every editable Stage-1 prose field is non-blocking: the user may retain, revise, or clear the recommendation, and confirmation makes the field's current value authoritative, including an empty string. Blank means no explicit user constraint; derive downstream defaults from the source and request without writing the old recommendation back into `result.json`. Stage 2 chooses tools only after that contract is known and keeps mutually dependent choices together: `mode` is the argument strategy, template reuse is the inheritance strategy, and reading mode decides how meaning is divided among the page, visuals, and presenter. It therefore drives content grammar, page granularity, density / rhythm, speaker-note burden, and the body baseline; the visual / image fields form the remaining deck system. `delivery_purpose` remains the compatibility key for **reading mode**, not communication purpose. Page count is derived from content volume × audience outcome × reading mode. Generated images inherit the chosen deck color roles directly; the user confirms rendering, not a second image palette. Stage 3 therefore contains production mechanics only, never another aesthetic decision. Each stage is authored once; documented deterministic UI dependencies may update visible values locally, but there is no same-stage AI recomputation.++Steps:++> ⛔ **Steps 2 → 3 → 4 are ONE uninterrupted run — do NOT yield to the user mid-flow.** When an intermediate `--wait` returns, the AI **immediately and autonomously** derives and writes the next stage once in the **same turn**: do **not** summarize, ask a question, report progress, or end the turn in between. The browser is sitting on a "deriving…" spinner polling for the next stage you must write — stopping here strands the page and the user must prod you in chat to finish (a bug, not the intended flow). **Stage-1 and Stage-2 confirmations are intermediate machine handoffs, not stopping points.** The single ⛔ BLOCKING wait is the **final** confirmation at the end of step 4. (Chat-fallback path — only when the page never opened — is the exception: there you do present each stage in chat and wait for a reply.)++1. **Write Stage 1** to `<project_path>/confirm_ui/recommendations.json` with `"stage": "stage1"` and only the communication-contract fields. New recommendations MUST use the canonical `stage` selector. Put only the recommended `canvas` id in `recommend`. Write `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, and `content_divergence` as `{ "value": "<free text>" }`. Seed concrete editable recommendations where the source and request support them; all seven prose values may be blank and none blocks confirmation. The submitted current value is the sole truth: preserve a user-cleared field as `""` through every later stage and the final `result.json`; never restore the earlier recommendation. `communication_intent` is deliberately open prose: it may combine several purposes and state their priority or sequence; the nine common paths are prompt examples only and MUST NOT become a checkbox / enum. `content_divergence` asks how closely to follow the source vs how freely to reshape it (blank = balanced; facts stay sourced at every level); it is consumed while authoring `§IX`, recorded in `design_spec.md §I`, and is not written to `spec_lock.md`. A profile may make this field read-only with `{ "value": "...", "locked": true }`; Beautify uses that contract and is the only exception to user editing. Do **not** include reading mode, `mode`, `visual_style`, page count, template, color, typography, icon, or image fields in Stage 1. Set `lang` to the page language (`zh` / `en` / `ja`); visible text matches `lang`, or provide multilingual name / note variants as documented by the Confirm UI.+2. **Launch + wait for Stage 1.** Background launch; the parent returns when the page writes the stage-1 `result.json`. **Long tool timeout — 600000 ms** (the `--wait` ≈590 s budget):+ ```bash+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait+ ```+ Page opens at the launch-log URL such as `http://127.0.0.1:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4). If 5050 is held, the launcher **auto-advances** (5051, …) — read the actual URL from the launch log and report it. The page does **not** close after Stage 1: it shows a "deriving…" state and polls for Stage 2. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host), do **NOT** troubleshoot — **on any non-zero exit, re-check `result.json` once** for a fresh `status: stage1-confirmed` before dropping to the chat fallback. **On success (exit 0 with a stage-1 result), do not pause or report — go straight to step 3 in the same turn.**+3. **Derive Stage 2 once from the confirmed communication contract, write it, then wait for the solution handoff — immediately, same turn (the page is polling for it).** Read the stage-1 `result.json` (`status: stage1-confirmed`). Using the user's **actual** contract (not your originals), **overwrite** `recommendations.json` with `"stage": "stage2"` and author the complete deck solution:+ - Recommend PPT-only reading mode through the compatibility key `recommend.delivery_purpose` (`text` / `balanced` / `presentation`) from the confirmed audience, delivery context, and artifact afterlife. `text` makes the page self-contained with complete prose and detail; `balanced` shares meaning between page and presenter; `presentation` uses one idea, concise claims, and visual evidence per page while speech / notes carry explanation. Then recommend one narrative `mode` and page count from source volume × desired audience outcome × reading mode. Reading mode governs content grammar and page granularity as well as the body baseline; it is not a font-size preset. The page applies `reading mode → body baseline → unpinned role sizes` as a deterministic browser-only dependency. This never calls the backend, and a manually edited size is pinned against later reading-mode changes.+ - When Step 3 loaded a deck/layout template, recommend `template_reuse_scope` now: `mirror`, `layout`, or `style`; `mirror` is legal only for `replication_mode: mirror`. Include `template_adherence: strict|adaptive` only for `mirror|layout`; `style` hides it and later writes `pptx_structure.mode: flat`. For a Deck, first compare its application contract—situations, audiences/outcomes, required narrative/page roles, and content policy—with the confirmed Stage-1 contract; do not treat the stored application as truth when the current request differs. Select from scenario fit: literal recurring artifact → consider `mirror`; compatible reusable structure with new content → `layout`; identity only or a contract that needs a different structure → `style`. Omit both fields for free design and brand-only templates.+ - Author `design_directions` with ≥3 coordinated candidates (safe / shifted / bold; honest-shortfall exception unchanged). Each candidate carries one compatible `visual_style`, color object, typography object, icon id, and—when `image_usage` includes `ai`—one generated-image **rendering** object. The page applies a candidate as one coherent starting point and then exposes the component fields for deliberate override. Do not generate Cartesian combinations or random mix-and-match defaults.+ - Color candidates carry background / secondary_bg / primary / accent / secondary_accent / body_text. Typography splits CJK + Latin for heading/body, includes topic-matched sample text, and uses one fixed body baseline per reading mode (`text` 20 / `balanced` 24 / `presentation` 32 on PPT). Font and direction cards change font character while preserving the current reading-mode sizing state. Recommend one or more `image_usage` source ids (`["ai"]`, `["ai","provided"]`, `["web","placeholder"]`, or `["none"]`; `none` is exclusive) and keep mixed-source / page-role guidance in `image_notes`. When AI is included, each direction's `image_strategy` contains rendering / visual / mood only; **never offer or submit a separate image palette**. Image HEX and role behavior come directly from that direction's deck color object. Spot-illustration lean remains rationale, not a field.++ **Stage 2 is never skipped** — an installed template is an input to the decision, not a substitute for deciding how it serves the contract. Never jump `recommendations.json` from `stage1` to `stage3`: the server refuses to render a skipped stage. The still-open page polls, renders Stage 2, and preserves Stage 1. Then attach to the already-running page; if Windows cleaned up the server, `--wait-only` auto-recovers it on the recorded/default port so the browser reconnects:+ ```bash+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage2+ ```+ This returns when the page writes the stage-2 `result.json` (`status: stage2-confirmed`). On a non-zero exit, re-check `result.json` once before falling back to chat — except a `stage skip detected` error, which is not a page failure: you wrote a stage out of order; rewrite `recommendations.json` with the stage the error names and re-attach.+4. **Derive Stage 3 once from the confirmed solution, then wait for the final confirmation.** Read the stage-2 `result.json`. **Do not reopen aesthetic choices.** Overwrite `recommendations.json` with `"stage": "stage3"` and recommend only production mechanics: enumerable `formula_policy`; conditional `image_ai_path` when confirmed `image_usage` includes `ai`; `generation_mode`; and `refine_spec`. The page shows the confirmed image-source summary as read-only context. Then attach to the already-running page; `--wait-only` auto-recovers a dead server as above (same 600000 ms budget):+ ```bash+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only+ ```+ This is the ⛔ BLOCKING completion: returns when the page writes the final `result.json` (`status: confirmed`, `stage: final`, carrying Stage 1 + Stage 2 + Stage 3 fields). On a non-zero exit, re-check `result.json` once (a `stage skip detected` error means Stage 2 was never confirmed — go back to step 3, not the chat fallback). Confirmed sizes are **already px** (the system is px-only — no pt anywhere, no conversion): write `result.json` `typography.body_size` / `sizes` into `design_spec.md` / `spec_lock.md` / SVG verbatim. `generation_mode: "split"` / `refine_spec: true` are explicit user choices.+5. **Close the confirm page (Mandatory cleanup — every path).** Shut the server down before leaving Step 4 so it cannot keep holding port 5050 (which Step 6 live preview reuses):+ ```bash+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown+ ```+ **Idempotent and required regardless of whether Confirm was clicked**: clicking the final Confirm already shuts the page down (then a no-op); the chat-fallback path leaves it running. Run it after reading the confirmation, before Step 5.++**Always also print each stage's recommendations + URL in chat** as the always-valid fallback. **The chat fallback is staged too**: if the page never opens or a wait times out with no fresh result, present Stage 1 as open communication questions (the common purposes are examples, never a numbered pick-list) → get confirmation → derive and present Stage 2 → get confirmation → derive and present Stage 3 → get confirmation → take those values. Either path converges.++**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate). `image_usage` may be either a legacy single string or a Confirm UI multi-select array; for arrays, apply every selected source. `image_notes`, when present, is a user-authored image intent note that Strategist must honor while assigning per-page §VIII rows:++For a confirmed template route, map `template_reuse_scope` mechanically: `style` → `pptx_structure.mode: flat` and omit `template_adherence`, `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`; `layout` / `mirror` → `mode: structured`, retain the confirmed `template_adherence`, and write the complete mappings. Never infer mirror behavior from the template workspace's `replication_mode` alone—the confirmed reuse scope is the downstream execution authority.++| `result.json.image_usage` | §VIII `Acquire Via` | h.5 + Step 5 generation |+|---|---|---|+| `ai` | `ai` rows | Run h.5 (lock rendering; inherit deck colors); Step 5 generates |+| `web` | `web` rows | None |+| `provided` | **`user`** rows | None — never generate |+| `placeholder` | `placeholder` rows | None |+| `none` | no image rows (§h option A) | None |+| Legacy custom prose | Infer the intended rows from the prose | Run h.5 only if the prose includes AI |++When the confirmed `image_usage` does not include `ai` (and no legacy custom prose includes AI), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. `none` is exclusive: if confirmed, write no §VIII image rows. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).++**Small spot illustrations are a Strategist judgment, not a confirmation field.** The user chooses image *source* through `image_usage`; whether the deck leans into decorative illustrations is anchored by the locked `visual_style`'s **illustration propensity** (`core` / `supportive` / `sparse`), expressed only in the `image_notes` rationale — never a new confirmation control. An explicit user request to use or skip illustrations overrides that default either way; `image_usage: none` still wins (write no illustration rows); and source still comes from `image_usage` — a `core` style does not silently generate AI spots when the user did not pick AI. They are ordinary §VIII image rows (`Type: Illustration` / `Illustration Sheet`) using normal `Acquire Via` values. If the plan needs ≥3 same-family AI spot illustrations, use the `ai` Illustration Sheet + `slice` workflow by default; do not generate one AI image per spot. Full rule + precedence: [`references/strategist.md`](../references/strategist.md) §h. Use them on suitable pages and omit them where they would weaken clarity.++**One authored recommendation per stage; final visible state wins (Mandatory).** Author each stage exactly once. A user edit inside Stage 2 MUST NOT trigger AI / backend re-recommendation, and confirmation MUST NOT be followed by a hidden repair pass that changes any displayed field. The page may apply only documented deterministic local dependencies: reading mode sets the default body baseline, body sets unpinned role sizes, and manual size edits pin those values. Font / direction changes preserve the current sizing state. No other advanced override silently rewrites a sibling choice.++Writing `design_spec.md` / `spec_lock.md` and later pages is **consumption of the confirmed state**, not another confirmation-stage calculation. Preserve every confirmed field verbatim and use it as an execution constraint:++| Confirmed anchor | Consume it in |+|---|---|+| `communication_intent` / `audience_outcome` / `core_message` | outline obligations, argument emphasis, and audience moves |+| `delivery_context` / `artifact_afterlife` | page-vs-presenter information load, standalone completeness, notes / citation depth, and hand-off structure |+| `visual_style` (§d Layer 2) | layout treatment, shape language, and visual rhythm while preserving the separately confirmed color / icon / typography values |+| `mode` (§d Layer 1) | outline structure and register (§IX) |+| `delivery_purpose` compatibility key (reading mode, §g) | content grammar, page granularity, notes burden, and per-page density / rhythm (§6.1); use the already-confirmed body / role sizes verbatim |+| `audience` (§c) | tone, evidence depth, and outline emphasis (§IX) |+| `color` HEX (§e) | exact deck roles and AI prompt color-role instructions; never invent or restore an image-palette choice |++If a deliberately mixed set of advanced overrides is unusual, honor it rather than silently “fixing” it. Canvas remains the explicit exception only in the sense that changing canvas does not rescale font sizes (see strategist §g); it still does not trigger a second stage calculation.++**Opt-out**: if the user has said they don't want the page (e.g. "不要网页" / "just confirm in chat" / "纯聊天确认"), skip the launch entirely (step 2) and present the Strategist confirmation stage in chat as before — steps 1, 3, 4 still apply (recommendations summary in chat; wait; take chat values).++The page is a **confirmation surface only** — Strategist still authors every recommendation; the page never generates content.++**Mandatory — split-mode note** (not a separate confirmation): after listing the Strategist confirmation stage details, you MUST append exactly one short line (rendered in the user's language, prefixed with 💡) about generation mode. Pick the variant by qualitative read of upstream-load signals — recommended page count, source-material bulk, whether `topic-research` ran with substantial web-fetch accumulation:++| 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](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](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](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](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)**:++| Policy | Behavior |+|---|---|+| `mixed` (default) | Strategist renders complex formula-worthy expressions as PNG assets; simple inline expressions remain editable text / Unicode |+| `render-all` | Strategist renders every formula-worthy expression as PNG assets |+| `text-only` | No formula rendering; formulas remain editable text / Unicode |++After the Strategist confirmation stage is approved and **before outputting `design_spec.md` / `spec_lock.md`**, if the confirmed formula policy is `mixed` or `render-all` and the content contains formula-worthy expressions, Strategist MUST:++1. Identify explicit LaTeX and any source expressions that should be faithfully structured as formulas.+2. Write `<project_path>/images/formula_manifest.json` with only the formulas selected for rendering.+3. Run:+ ```bash+ python3 ${SKILL_DIR}/scripts/latex_render.py <project_path>+ ```+4. Include each formula as an `Acquire Via: formula`, `Type: Latex Formula` row in `design_spec.md §VIII Image Resource List`: use `Status: Rendered` when the PNG exists, or `Status: Needs-Manual` after provider exhaustion. List every formula in `spec_lock.md images` with `| no-crop`.++The formula renderer uses a provider fallback chain by default: `codecogs,quicklatex,mathpad,wikimedia`. The first three are color-aware; Wikimedia is an availability fallback. If every provider fails for a selected formula, report its manifest item, LaTeX source, target filename, and provider errors; mark only that row `Needs-Manual` and continue without claiming `Rendered`. The user may supply the exact target PNG before the Step 7 image-readiness gate or change the formula policy. Formula PNGs are transparent by default: manifest `background` is the temporary render matte and transparency-removal reference, not a retained final background unless `transparent: false` is set for that item. Do not scan `spec_lock.md` for `$...$` or `$$...$$`. Dollar-delimited math in source material is only a signal for Strategist; the renderer consumes the explicit manifest.++If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative regenerated image-fact view in the `analysis/` folder, which MUST be read before authoring §VIII:+```bash+python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images+```++> 🔁 **Image facts are regenerated on demand, never a durable store.** `images/` is a live working folder — pictures are extracted from the source at import, the user may drop or replace files at any time, and Step 5 writes web/AI images into it. The single source of truth is therefore the **current contents of `images/`**, and `analysis/image_analysis.csv` is a *regenerated view* of it, not a fact to keep in sync. Re-run `analyze_images.py <project_path>/images` immediately **before any step that reads image facts** so the view reflects the live folder: before the §h image-usage recommendation (see [strategist.md](../references/strategist.md) §h), here before authoring §VIII, after Step 5 acquisition (so web/AI files join the view), and again any time the user says they added or replaced images. This is the staleness strategy — re-derive on use, no cache to invalidate.++> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output (`analysis/image_analysis.csv`) or the Design Spec's Image Resource List.++**Output**:+- `<project_path>/design_spec.md` — human-readable design narrative+- `<project_path>/spec_lock.md` — machine-readable communication + execution contract (skeleton: `templates/spec_lock_reference.md`); Executor re-reads before every page++**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:+```markdown+## ✅ Strategist Phase Complete+- [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 stage)+- [x] Design Specification & Content Outline generated+- [x] Execution lock (spec_lock.md) generated+- [x] Communication trace validated: `spec_lock.md ## communication` contains all six contract key lines (optional values may be blank), and every `design_spec.md §IX` Slide block has an `Audience move`+- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase+```++---++### Step 5: Image Acquisition Phase (Conditional)++🚧 **GATE**: Step 4 complete; `<project_path>/design_spec.md` and `<project_path>/spec_lock.md` both exist. If either required artifact is missing, stop before any acquisition or generation and follow [`failure-recovery.md`](governance/failure-recovery.md) §3. Formula rows already have `Acquire Via: formula` and status `Rendered` or `Needs-Manual`.++> **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/governance/failure-recovery.md`](governance/failure-recovery.md). This Step keeps the acquisition procedure.++**Always load the common framework**:++```+Read references/image-base.md+```++Then **lazy-load the path-specific reference** for each row that actually needs it:++| Acquire Via | Load reference (only if any such row exists) | Run |+|---|---|---|+| `ai` | `references/image-generator.md` | write `<project_path>/images/image_prompts.json`, then follow `image-generator.md §7 Path Selection` (`image_gen.py --manifest` is **Path A only**) |+| `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` (≥2 web rows → `--batch images/image_queries.json`) |+| `slice` | `references/image-generator.md` §4.3 | derived — **after** the parent `ai` sheet row is `Generated`, run `python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha` (see workflow step 2.5) |+| `user` / `formula` / `placeholder` | (skip) | (skip) |++A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.json` and `image_sources.json`.++> ⚠️ **In-pipeline ai rows MUST use the manifest contract** — even when only 1 ai row exists. Always write `images/image_prompts.json` first and render `image_prompts.md` with `image_gen.py --render-md`. Then execute the confirmed path from `image-generator.md §7`: `image_gen.py --manifest` is **Path A only**; `host-native` is **Path B** and MUST skip `--manifest`; `manual` writes the prompts and stops for external generation. The positional form (`image_gen.py "prompt" ...`) is reserved for **out-of-pipeline one-off testing / single-image fixups** — it skips manifest + sidecar, leaving no audit trail.++> ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](../references/image-searcher.md) §5.++> 💡 **ai path — spot illustrations as one sheet**: when the §VIII image resource plan needs ≥3 same-family spot illustrations as decorative accessories, generate **one grid sheet** (a single `ai` sheet row) instead of one row per element, then slice it (workflow step 2.5 below). Choose sheet geometry from intended placement: `1xN` / `Nx1` are useful for extreme portrait / landscape cells, and a designed `MxN` grid is valid when its cell ratio fits the planned elements. The sheet row is generated but not placed; each cut **element row** (`Acquire Via: slice`) is placed and must appear in `spec_lock.md images`. One generation = one coherent style across all pieces. Resource contract + the geometry rules: [image-generator.md](../references/image-generator.md) §4.3.++> ⚠️ **Honor the confirmed image source before running any generation command**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — a confirmed choice other than `auto` wins, whether it came from chat (canonical) or, when the page was used, `result.json.image_ai_path`. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. Never run `image_gen.py --manifest` when the confirmed value is `host-native` or `manual`. Full selection rule: [image-generator.md](../references/image-generator.md) §7 Path Selection.++Workflow:++1. Extract all resource rows from the design spec and group them by `Acquire Via`; rows with `Status: Pending` or `Status: Failed` and `Acquire Via ∈ {ai, web, slice}` must all reach a terminal state before Executor starts+2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](../references/image-base.md) §3 dispatch table+2.5. **Slice any spot-illustration sheets (only if `slice` rows exist).** For each generated `ai` **sheet** row, run `slice_images.py` (grid + the element `--names` matching the `slice` rows, `--trim --alpha`) so every element file lands in `images/`; mark each `slice` row `Generated`. A sheet still in `Needs-Manual` cannot be sliced — leave its `slice` rows `Needs-Manual` and surface them at the Step 7 readiness gate. Contract: [image-generator.md](../references/image-generator.md) §4.3.+3. Verify every row reaches a terminal status: `Generated` (ai success / sliced element), `Sourced` (web success), or `Needs-Manual`. `Failed` is not a terminal status: it means the current run did not generate that item, but the item remains retryable. On `auto`, follow the owning fallback chain. On an explicitly confirmed `api` or `host-native` path, retry only that path; if it still fails, mark the row `Needs-Manual` without switching to another automated provider.+4. Re-derive image facts now that web / AI / sliced files are in the folder — `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` — so `analysis/image_analysis.csv` reflects every acquired image **including the sliced elements** (real measured sizes) before the Executor lays them out. Image facts are regenerated on use, never a stale store (see Step 4's image-facts note).++**✅ Checkpoint — Confirm acquisition attempted for every row**:+```markdown+## ✅ Image Acquisition Phase Complete+- [x] image_prompts.json created (when any ai rows processed)+- [x] image_prompts.md sidecar rendered (when any ai rows processed)+- [x] image_sources.json created (when any web rows processed)+- [x] Spot-illustration sheets sliced (when any `slice` rows exist); every element file present in `images/` and listed in `spec_lock.md images`+- [x] Each row: status is `Generated` / `Sourced` / `Needs-Manual` (no `Pending` or `Failed` remaining)+- [x] analyze_images.py re-run so image_analysis.csv covers the acquired web / AI / sliced images+```++**Default — auto-proceed to Step 6.** Only when the user's Step 4 response explicitly opted into split mode (in chat or via Confirm UI `result.json` with `generation_mode: "split"`), output the planning-session handoff below and stop this conversation:++ ```markdown+ ## ✅ 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`](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.++---++### Step 6: Executor Phase++🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready.++**Artifact ownership**: `svg_output/` is the author source, `svg_final/` is derived, and image facts come from the regenerated `analysis/image_analysis.csv`; see [`references/artifact-ownership.md`](../references/artifact-ownership.md).++Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):+```+Read references/executor-base.md # REQUIRED: common guidelines+Read references/shared-standards.md # REQUIRED: SVG/PPT technical constraints+Read references/native-shape-authoring.md # REQUIRED: stock-shape selection and fragment helper contract+Read references/modes/<locked-mode>.md # narrative skeleton (spec_lock.md `mode`)+Read references/visual-styles/<locked-style>.md # aesthetic (spec_lock.md `visual_style`)+```++> Read executor-base + shared-standards + native-shape-authoring + the one locked mode file + the one locked visual-style file. For `mode: custom` or `visual_style: custom`, skip that preset file and follow `mode_behavior` / `visual_style_behavior` from `spec_lock.md` instead. Never glob `modes/` or `visual-styles/`.++**Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.++**Live Preview Auto-Startup (Mandatory)**: before the first SVG, automatically start the browser editor in live mode and keep it running continuously through Executor + Step 7 export:+```bash+python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon+```+- Start it immediately when Executor begins; `svg_output/` may be empty. Editor opens at the launch-log URL such as `http://127.0.0.1:5050`; if another project already holds it, the launcher **auto-advances to the next free port** — read the actual URL from the launch log and report that.+- 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/stages/live-preview.md`](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`](stages/live-preview.md) Notes.++**Pre-generation Template Read (Mandatory)**: first read `templates/template_execution_manifest.json` when present. It is the compact prototype roster and points each prototype to one `text_slots_path`. Use the roster to select prototypes; before each mirror page, read that prototype's text-slot sidecar and complete `templates/<basename>.svg`. Layout reuse reads the selected complete SVG but does not apply mirror-only text topology restrictions. When the manifest or selected sidecar is unavailable, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` once before the first page and apply the full-SVG mirror/layout rules. In all cases, batch-read every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts) once up front. Do not substitute a manifest or sidecar for the selected full prototype. See executor-base.md §1.0.++> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).++**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md`; check the global `communication` contract, including `consumption_mode`, against the current §IX `Core message` + `Audience move`, and use only the lock's colors / fonts / icons / images, plus `pptx_structure.mode`, `template_reuse_scope`, and the per-page `page_rhythm` / `page_charts` lookups. Read `page_layouts` / `page_pptx_layouts` / `pptx_masters` / `pptx_layouts` only on a structured `template_reuse_scope: mirror|layout` route; they are absent in flat `style`, free-design, and brand-only projects. Resists purpose and design drift on long decks. See executor-base.md §2.1.++> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.+> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).++**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`++Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Before drawing a literal stock shape, apply [`native-shape-authoring.md`](../references/native-shape-authoring.md): use the stdout-only helper when one PowerPoint preset exactly matches, keep basic SVG primitives for rect/round-rect/ellipse, and keep free SVG for custom semantics. Diagram relationships are Shape-first: use ordinary line/path shapes with registered arrow markers for thin edges and ordinary shape presets for solid block arrows; do not default to connector-family presets or author attachment metadata. Never infer a preset from contour similarity.++`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. `layout` pages may reflow and re-skin to the project lock; `mirror` pages preserve literal visuals and may change only visible `<text>` / `<tspan>` values while keeping text/tspan count, order, nesting, and every attribute unchanged. `template_reuse_scope: style` follows the flat free-design paragraph below and does not inherit template structure metadata.++`template_reuse_scope: style`, free-design, and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.++Do not duplicate specialized identity with `data-pptx-role`. Add it only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-replace-with`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](../references/semantic-svg.md).++**First-page gate (Mandatory)** — after the **first** SVG page, before drawing page 2:+```bash+python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page+```+Fix every `error` on page 1 first — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.++**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE annotation handling and speaker notes:+```bash+python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json+```+- Any `error` (banned/unsupported SVG features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.+- Every `warning` is advisory and non-blocking: do not return the page for mandatory modification, do not auto-normalize user-authored compatible syntax, and do not require an acknowledgement/disposition line. Recommendation warnings identify the generated-SVG default; fidelity/quality warnings may be reported when material, but the existing input may ship unchanged. If a condition must be corrected before release, the checker must classify it as an `error`, not a `warning`.+- The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat `style`, free-design, and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks.+- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).+- The JSON report is written to `exports/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`.++**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`++**✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Run the applicable conditional gates below, then proceed to Step 7**:+```markdown+## ✅ Executor Phase Complete+- [x] Live preview started before the first SVG and kept available at the reported URL+- [x] First-page gate run after page 1 (errors fixed before page 2)+- [x] All SVGs generated to svg_output/+- [x] svg_quality_checker.py passed (0 errors)+- [x] Speaker notes generated at notes/total.md+```++> **Chart pages?** If this deck contains data charts (bar / line / pie / radar / etc.), run the [`verify-charts`](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 [`visual-review`](stages/visual-review.md) quality-gate stage before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.++---++### Step 7: Post-processing & Export++🚧 **GATE**: Step 6 is complete; `svg_output/` contains every final page, `notes/total.md` exists, all required conditional quality gates passed, and the final SVG quality report has 0 errors.++🚧 **Image readiness GATE**: When any required resource row is `Needs-Manual`, every expected file and derived slice output MUST exist under `<project_path>/images/` before Step 7.1. If any file is absent, pause and list the exact filenames. After the files arrive, rerun `analyze_images.py`, replace each dashed placeholder in `svg_output/`, reconcile every `no-crop` container to the measured native ratio, then rerun the final SVG quality check so the gate covers the changed sources.++**Failure recovery**: On a command failure, repair the owning source artifact and resume from that failed sub-step per [`failure-recovery.md`](./governance/failure-recovery.md). Do not restart planning unless its owning source changed.++**Hard rule — strict serial commands**: Run the following commands one at a time. Do not combine them in one code block or shell invocation. Enter the next sub-step only after the current command exits successfully and its success criterion is true.++#### Step 7.1 — Split Speaker Notes++```bash+python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>+```++**Success criterion**: Per-slide Markdown files exist under `<project_path>/notes/` and cover every published slide.++#### Step 7.2 — Build the Self-Contained SVG Preview++```bash+python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>+```++**Success criterion**: `<project_path>/svg_final/` contains one self-contained preview SVG for every published slide. This mandatory derived preview does not replace `svg_output/` as the native-export source.++#### Step 7.3 — Export the Native PPTX++```bash+python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>+```++**Success criterion**: The command exits successfully and publishes:++- `exports/<project_name>_<timestamp>.pptx`+- `exports/<project_name>_<timestamp>.report.json` with `passed` or `passed-with-warnings` package/resource postflight status++Disclose material postflight warnings to the user. A failed report or missing PPTX is not success.++## ✅ Generate PPTX Complete++- [x] Image readiness gate passed+- [x] Notes split completed+- [x] `svg_final/` preview completed+- [x] Native PPTX and postflight report published+- [ ] **Next**: Report the exported PPTX path; run a supporting post-export stage only when its explicit trigger is presentdiff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.mdindex 8364ccc7..5084f4e7 100644--- a/skills/ppt-master/workflows/governance/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -14,7 +14,7 @@ Global stop/continue rules for all four top-level routes, plus concrete failure| Failure point | Blocking | Automatic recovery | User intervention | Resume entry ||---|---:|---|---|---|-| Confirm UI launch failure | No | Re-check `confirm_ui/result.json` once, then use chat fallback | No | `SKILL.md` Step 4 chat confirmation |+| Confirm UI launch failure | No | Re-check `confirm_ui/result.json` once, then use chat fallback | No | [`generate-pptx`](../generate-pptx.md) Step 4 chat confirmation || Confirm UI wait timeout | No, if no final result yet | Re-check `result.json` once; keep server cleanup mandatory | Only if user still wants the page | Step 4 same 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 |@@ -64,12 +64,12 @@ Here, **final confirmation evidence** means either the explicit final confirmati| 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` |-| Stage 2 confirmation exists, final confirmation missing | Resume [`SKILL.md`](../../SKILL.md) Step 4 substep 4, "Derive Stage 3 once from the confirmed solution, then wait for the final confirmation." |+| Stage 2 confirmation exists, final confirmation missing | Resume [`generate-pptx`](../generate-pptx.md) Step 4 substep 4, "Derive Stage 3 once from the confirmed solution, then wait for the final confirmation." || Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to [`strategist.md`](../../references/strategist.md) §6 steps 1–4 and regenerate `design_spec.md` and `spec_lock.md` together from the source material and confirmed state; do not reconstruct the outline from an orphan lock. || Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to [`strategist.md`](../../references/strategist.md) §6 step 4 and regenerate `spec_lock.md`. || No final confirmation evidence is available | Resume Step 4 from the latest stage evidenced by `confirm_ui/result.json`; if no stage is persisted, restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. || `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/resume-execute.md) |-| Images acquired but SVGs not started | `SKILL.md` Step 6 |+| Images acquired but SVGs not started | [`generate-pptx`](../generate-pptx.md) Step 6 || SVGs complete and checker passed, notes missing | Step 6 Logic Construction || SVGs and notes complete | Step 7.1 || Step 7.1 complete, export not complete | Step 7.2 |diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.mdindex 83d49a9c..00ab34b8 100644--- a/skills/ppt-master/workflows/index.md+++ b/skills/ppt-master/workflows/index.md@@ -1,51 +1,43 @@----description: Registry of PPT Master's top-level routes and supporting child workflows, profiles, stages, and governance documents.+description: Maintainer-only registry of PPT Master's route and supporting-workflow inventory.---# Workflow Registry-Registry for the route authorities and supporting runbooks referenced by [`SKILL.md`](../SKILL.md) and [`routing.md`](./routing.md).+Maintainer-only inventory for adding, moving, or removing workflow documents. Runtime task execution does not consume this file.-**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. Route Authorities------## 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 from one or more reference channels or a direct-text brief | Read the complete reference bundle and author a new template workspace; never add Master/Layout structure to a 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/` |-----+| ID | Class | Authority path |+|---|---|---|+| `generate-pptx` | Top-level route | [`generate-pptx.md`](./generate-pptx.md) |+| `create-template` | Top-level route | [`create-template.md`](./create-template.md) |+| `template-fill-pptx` | Top-level route | [`template-fill-pptx.md`](./template-fill-pptx.md) |+| `native-enhance-pptx` | Top-level route | [`native-enhance-pptx.md`](./native-enhance-pptx.md) |## 2. Supporting Documents-| Class | ID | Path | Owner / trigger |+| ID | Class | Path | Parent / lifecycle slot ||---|---|---|---|-| 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, application-neutral structure intent is selected |-| Template child workflow | `create-deck` | [`create-template/create-deck.md`](./create-template/create-deck.md) | Create Template after a branded structural system or recurring presentation application is selected |-| 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) | Global stop/continue policy across all four routes; Generate PPTX recovery matrix and resume pointers |-------## 3. Update Rules--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 route matrices**: Do not copy the full route matrix from [`routing.md`](./routing.md) into `SKILL.md` or stage documents.+| `beautify-pptx` | Generation profile | [`profiles/beautify-pptx.md`](./profiles/beautify-pptx.md) | Generate PPTX |+| `apply-template-workspace` | Template-input stage | [`stages/apply-template-workspace.md`](./stages/apply-template-workspace.md) | Generate Step 3 |+| `create-brand` | Template child workflow | [`create-template/create-brand.md`](./create-template/create-brand.md) | Create Template |+| `create-layout` | Template child workflow | [`create-template/create-layout.md`](./create-template/create-layout.md) | Create Template |+| `create-deck` | Template child workflow | [`create-template/create-deck.md`](./create-template/create-deck.md) | Create Template |+| `topic-research` | Intake stage | [`stages/topic-research.md`](./stages/topic-research.md) | Before Generate Step 1 |+| `resume-execute` | Control stage | [`stages/resume-execute.md`](./stages/resume-execute.md) | Generate Step 6 resume |+| `refine-spec` | Planning stage | [`stages/refine-spec.md`](./stages/refine-spec.md) | After Generate confirmation |+| `verify-charts` | Quality gate | [`stages/verify-charts.md`](./stages/verify-charts.md) | Before Generate Step 7 |+| `visual-review` | Quality gate | [`stages/visual-review.md`](./stages/visual-review.md) | Before Generate Step 7 |+| `live-preview` | Editor stage | [`stages/live-preview.md`](./stages/live-preview.md) | Generate preview / post-export |+| `customize-animations` | Post-processing stage | [`stages/customize-animations.md`](./stages/customize-animations.md) | Generate conditional export |+| `generate-audio` | Shared audio stage | [`stages/generate-audio.md`](./stages/generate-audio.md) | Generate / Enhance Native |+| `failure-recovery` | Governance | [`governance/failure-recovery.md`](./governance/failure-recovery.md) | All routes |++## 3. Maintenance Rules++1. Add a top-level route only for a distinct artifact lifecycle and mutation model; synchronize [`routing.md`](./routing.md).+2. Register profiles, stages, governance files, and Create Template children only in §2.+3. Keep commands and trigger procedures in the owning authority, not in this registry.+4. Update `scripts/prompt_audit_manifest.json` load sets and coverage in the same change.+5. Keep this registry out of runtime load sets.diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.mdindex c4363762..17ba4aa9 100644--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md@@ -22,7 +22,7 @@ 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 ([`generate-pptx`](../generate-pptx.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.@@ -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 [`generate-pptx`](../generate-pptx.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{@@ -208,7 +208,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 [`generate-pptx`](../generate-pptx.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.@@ -216,12 +216,10 @@ On confirmation, enter SKILL.md Step 4 as Strategist with the plan pre-resolved.## 6. Executor + Export-Run the standard pipeline (SKILL.md Steps 6–7). The Executor re-lays-out each page — hierarchy, spacing, alignment, page rhythm — using **only** the inherited palette + fonts from `spec_lock.md`, regenerates charts / tables as native SVG from the extracted data, and re-lays-out the source pictures.+Run the standard pipeline ([`generate-pptx`](../generate-pptx.md) Steps 6–7). The Executor re-lays-out each page — hierarchy, spacing, alignment, page rhythm — using **only** the inherited palette + fonts from `spec_lock.md`, regenerates charts / tables as native SVG from the extracted data, and re-lays-out the source pictures.-```bash-python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>-python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>-```+Follow [`generate-pptx`](../generate-pptx.md) Step 7 for the canonical serial+post-processing commands, gates, success criteria, and export artifacts.---diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.mdindex 9dfc01ed..d1f06388 100644--- a/skills/ppt-master/workflows/routing.md+++ b/skills/ppt-master/workflows/routing.md@@ -30,7 +30,7 @@ route selection. After selection, the route authority owns execution.| Route | Request shape | Authority | Preconditions | Mutation model | Output contract ||---|---|---|---|---|---|-| Generate PPTX | Create a new presentation; regenerate an existing deck visually; use source material or a topic; optionally 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/` |+| Generate PPTX | Create a new presentation; regenerate an existing deck visually; use source material or a topic; optionally apply an explicit template workspace | [`generate-pptx`](./generate-pptx.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 one or more PPTX/SVG files, images/PDFs, direct or file-based text, documents/websites, brand assets, or a mixed reference bundle | [`create-template`](./create-template.md) | A reusable-template request exists; reference material is optional, and project scope additionally requires an initialized target project | Author a new portable workspace; never modify any reference file in place | Workspace with required `templates/`, optional `images/` / `icons/`, and optional review `exports/` || Fill Native PPTX | Use a raw PPTX's native slide shells and replace/fill content | [`template-fill-pptx`](./template-fill-pptx.md) | Source PPTX plus new material/topic | Clone and patch PPTX through OOXML; no SVG pipeline | New filled PPTX in project `exports/` || Enhance Native PPTX | Keep a finished PPTX's visible slides stable while adding notes, audio, timings, or transitions | [`native-enhance-pptx`](./native-enhance-pptx.md) | Finished source PPTX exists | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX in project `exports/` |@@ -41,16 +41,17 @@ route selection. After selection, the route authority owns execution.| 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 |+| Topic only, no substantive source facts | Run [`topic-research`](./stages/topic-research.md), then return to [`generate-pptx`](./generate-pptx.md) Step 1 |+| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through [`generate-pptx`](./generate-pptx.md) Step 1 and its PPTX intake; use the default Generate 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 |+| Explicit current brand/layout/deck workspace root | Enter [`generate-pptx`](./generate-pptx.md) Step 3 and conditionally load [`apply-template-workspace`](./stages/apply-template-workspace.md); 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 |+| User requests page transitions, auto-advance, or deck-wide animation settings | Load [`animations`](../references/animations.md) and apply its export-level contract |+| User requests per-slide or object-level animation control | 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.@@ -62,7 +63,7 @@ route selection. After selection, the route authority owns execution.**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:1. Run [`create-template`](./create-template.md) to produce a separate validated workspace.-2. Pass that workspace root to Generate PPTX Step 3.+2. Pass that workspace root to [`generate-pptx`](./generate-pptx.md) 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.@@ -74,8 +75,8 @@ When a PPTX already contains native Master/Layout parts, `create-template` mirro|---|---|| Raw PPTX called a template + new content | Fill Native PPTX unless the user explicitly asks for a reusable template workspace || Any supported reference bundle or direct-text brief + 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 |+| Current template workspace root + content | [`generate-pptx`](./generate-pptx.md) Step 3 |+| Legacy-flat root with current `design_spec.md` and current SVG contract | [`apply-template-workspace`](./stages/apply-template-workspace.md) 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 |@@ -114,7 +115,7 @@ Object animation for generated SVG projects uses the animation stage. Native PPT| User input | Behavior ||---|---|-| Explicit current workspace root containing `templates/design_spec.md` | Enter Generate PPTX Step 3 |+| Explicit current workspace root containing `templates/design_spec.md` | Enter [`generate-pptx`](./generate-pptx.md) 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 |diff --git a/skills/ppt-master/workflows/stages/apply-template-workspace.md b/skills/ppt-master/workflows/stages/apply-template-workspace.mdnew file mode 100644index 00000000..d769b103--- /dev/null+++ b/skills/ppt-master/workflows/stages/apply-template-workspace.md@@ -0,0 +1,117 @@+---+description: Conditional Generate-PPTX runbook for validating, installing, or fusing explicit Brand, Layout, and Deck workspaces.+---++# Apply Template Workspace Stage++> Run only from [`generate-pptx.md`](../generate-pptx.md) Step 3 after the user supplies an explicit workspace-root path, or after Create Template hands off its exact validated workspace root in the current conversation. Never load this stage for free design, a bare template name, a style description, or a brand mention.++## 1. Gate and Normalize Inputs++🚧 **GATE**: Every external input resolves to one of these current contracts:++| Input shape | Spec and SVG source | Asset source |+|---|---|---|+| Current workspace root | `<root>/templates/design_spec.md` and `<root>/templates/` | Existing `<root>/images/` and `<root>/icons/` |+| Compatible legacy-flat root | `<root>/design_spec.md` and current-contract SVGs under `<root>/` | Package-local files |+| Current Create Template handoff | Its exact validated library or project workspace root | Existing portable sibling `images/` and `icons/`; already installed only when the root is the target project |++The spec frontmatter MUST declare `kind: brand`, `kind: layout`, or `kind: deck`. Do not accept only another project's inner `templates/` directory because that omits sibling assets.++**Hard rule — raw source boundary**: A raw PPTX is not a Step 3 workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first and return with its validated workspace root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.++**Compatibility gate**: Reject semantic-legacy or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved. A legacy-flat directory is readable only when its SVG contract is current.++## 2. Read the Matching Schema++Read [`templates/README.md`](../../templates/README.md), then only the README for each supplied kind:++| Kind | Schema | Owned segment |+|---|---|---|+| `brand` | [`templates/brands/README.md`](../../templates/brands/README.md) | Identity: color, typography, logo, voice/tone, icon style |+| `layout` | [`templates/layouts/README.md`](../../templates/layouts/README.md) | Structure: canvas, page structure, semantic text roles, page types, SVG roster |+| `deck` | [`templates/decks/README.md`](../../templates/decks/README.md) | Application plus integrated identity and structure |++A Layout created with `mirror` remains eligible only when its source contract is brand-neutral and application-neutral. Keep a branded or application-bearing source as a Deck, or re-author it as Layout through `standard` / `fidelity`; do not remove those semantics through mirror.++## 3. Structured Preflight++Before copying a Deck or Layout workspace, inspect every SVG root and slot:++- Every page declares root Master/Layout keys and PowerPoint picker names.+- Master/Layout visuals are direct atoms, not generic layer `<g>` wrappers.+- Every non-composite slot is a top-level `<g>` with positive bounds and exactly one compatible carrier.+- A composite region uses an explicit `object` proxy; a zero-slot Layout is valid.+- The complete SVG contract is current. Reject a legacy semantic contract instead of repairing it in the target project.++## 4. Install a Single Workspace++| Kind | Install behavior |+|---|---|+| `brand` | Install `templates/` plus existing `images/` and `icons/`; ignore `exports/`. Identity is constrained; structure remains free. |+| `layout` | Install the same portable roots. Expose reusable structure; Strategist later confirms legal `mirror`, `layout`, or `style` reuse. |+| `deck` | Install the same portable roots. Expose application, identity, and structure; Strategist compares the stored application with the current communication contract before choosing reuse. |++For a compatible legacy-flat package, route SVG/spec/non-bitmaps to project `templates/`, bitmaps to project `images/`, and declared icons to project `icons/`. Do not infer legacy Master/Layout semantics from the flat directory shape.++**Atomic install preflight**:++1. Resolve every source and destination path.+2. Enumerate the complete mapping across `templates/`, `images/`, and `icons/`.+3. Reject every destination collision before writing.+4. Write the accepted mapping once; never use recursive copy as an implicit conflict policy.++If the normalized source root equals the target project root, consume it in place and copy nothing. An in-place workspace cannot participate in multi-path fusion. Ignore source `exports/`; it contains review artifacts, not portable template inputs. Empty optional roots remain absent.++Template SVGs are authoring prototypes, not export-time overlays. The generated page remains complete in `svg_output/`; `page_layouts` selects the complete prototype and its explicit structure contract for authoring.+++## 5. Fuse Multiple Workspace Paths++Multi-path fusion supports different kinds, or at most two workspaces of the same kind. Resolve all segment and asset conflicts before writing any target file.++### 5.1 Different Kinds++Use segment-level integer replacement; do not mix fields implicitly:++| Combination | Identity from | Structure from | Application from |+|---|---|---|---|+| brand only | brand | free design | none |+| layout only | free design | layout | none |+| deck only | deck | deck | deck |+| brand + layout | brand | layout | current Stage-1 communication contract |+| brand + deck | brand | deck | deck |+| layout + deck | deck | compatible layout | deck |+| brand + layout + deck | brand | compatible layout | deck |++Before Layout overrides Deck structure, verify that every required application/narrative/content role fits the Layout's page roles, slot types, and capacity. On mismatch, stop and surface exactly three remedies: retain Deck structure, select another Layout, or explicitly revise the application contract.++Field-level micro-adjustments such as a primary-color override are not Step 3 fusion. Carry them into the normal Strategist confirmation fields.++### 5.2 Same Kind++Do not use path order as priority. Report every segment-level difference and ask the user to choose workspace A, workspace B, or select per segment. Only the per-segment choice opens a segment-by-segment resolution. Do not resolve field-level conflicts here. Three or more same-kind paths require the user to converge to at most two.++### 5.3 Fused Provenance++Write one final `<project>/templates/design_spec.md`. Immediately under its H1, record every source kind/path, base or override role, and user-resolved segment conflict:++```markdown+> **Fused from:**+> - deck: `templates/decks/example/` (base)+> - brand: `templates/brands/example/` (identity override)+> - layout: `templates/layouts/example/` (structure override)+> - conflicts resolved: Color Scheme from brand (user selected A)+```++Single-path installs do not add provenance. Set fused frontmatter `kind` from the resulting capability: `deck` when identity and structure are both present, `layout` for structure only, or `brand` for identity only. A project-local Brand + Layout fusion uses `kind: deck` for routing but is not automatically a reusable library Deck; its application remains current-project context.++**Completion receipt**: Report `roots=<normalized roots>; kinds=<kind per root>; install=<in-place|copied>; final_spec=<project_path>/templates/design_spec.md`.++## ✅ Template Workspace Applied++- [x] Every input was an explicit root satisfying a listed workspace contract or the exact current Create Template handoff+- [x] Kind schemas and structured SVG contracts passed preflight+- [x] All collisions and fusion conflicts were resolved before one atomic install+- [x] `<project_path>/templates/` and any portable sibling assets are complete+- [ ] **Next**: Return to [`generate-pptx.md`](../generate-pptx.md) Step 4diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdindex 427f7c3f..6636ae5d 100644--- a/skills/ppt-master/workflows/stages/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -4,17 +4,22 @@ description: Optional post-processing stage for per-slide and per-object animati# Customize Animations Stage-> 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.+> Optional Generate-PPTX post-processing stage for per-slide or per-object+> animation control. Run when the user asks to customize slide-specific motion,+> object order, effects, timing, or reveals. Deck-wide transitions,+> auto-advance, and per-element entrance settings use+> [`animations.md`](../../references/animations.md) directly and do not activate+> this stage.## When to Run| Condition | Action ||---|---|-| User asks for object-level animation, reveal order, timing, or effect changes | Run this stage |+| User asks for per-slide or per-object 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 stage only for per-slide/per-object control |+| User only wants deck-wide page transitions, auto-advance, or per-element entrance animation | Do not run; apply [`animations.md`](../../references/animations.md) with exporter flags such as `-a auto` || `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 |+| This stage is triggered and `animations.json` is present | Validate and edit it; do not overwrite unless the user asks |---@@ -262,7 +267,14 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project_path>python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>```-**Validation**: the exported native PPTX must reflect the object-level overrides. `--animation none` still disables all per-element animation and overrides `animations.json`. Unknown animation effects/modes/triggers; boolean, NaN, or Infinity numeric values; non-positive durations; negative delay/stagger; invalid order; missing slides/groups; and structural-layer targets fail validation. Transition validation remains strict as well. None of these failures substitutes a fallback effect or silently drops a requested target.+**Validation**: the exported native PPTX must reflect the per-slide and+per-object overrides. `--animation none` still disables all per-element+animation and overrides `animations.json`. Unknown animation+effects/modes/triggers; boolean, NaN, or Infinity numeric values; non-positive+durations; negative delay/stagger; invalid order; missing slides/groups; and+structural-layer targets fail validation. Transition validation remains strict+as well. None of these failures substitutes a fallback effect or silently drops+a requested target.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.@@ -272,7 +284,7 @@ Direct-PPTX routes are preserve-only for object animation: they compare the sour## ✅ Customize Animations Complete-- [x] `animations.json` exists only because object-level customization was requested+- [x] `animations.json` exists only because per-slide or per-object customization was requested- [x] `design_spec.md`, `spec_lock.md`, and available speaker notes were checked before editing animation overrides- [x] Every slide in `svg_output/` appears under `slides` with explicit `transition` + `animation` blocks- [x] Group-level entries were added only for groups that diverge from the slide's `animation` blockdiff --git a/skills/ppt-master/workflows/stages/live-preview.md b/skills/ppt-master/workflows/stages/live-preview.mdindex 71571f86..a087618d 100644--- a/skills/ppt-master/workflows/stages/live-preview.md+++ b/skills/ppt-master/workflows/stages/live-preview.md@@ -6,7 +6,7 @@ description: Main-pipeline editor stage for starting live preview and applying s> **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 [`generate-pptx`](../generate-pptx.md) Step 6. Do not re-launch a preview that is already running.## When to Run@@ -61,17 +61,13 @@ Triggered by the user signals listed in "When to Run".- Edit the targeted element in `<project_path>/svg_output/<file>` per the annotation text.- Remove `data-edit-target` and `data-edit-annotation` from that element.- Append one `annotation_applied` JSONL record to `<project_path>/live_preview/annotations.jsonl` with `ts`, `file`, `element_id`, and the original annotation text.-4. Re-export:- ```bash- python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>- python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>- ```+4. Re-enter [`generate-pptx`](../generate-pptx.md) Step 7.2, wait for its success criterion, then run Step 7.3. Do not rerun Step 7.1 unless speaker notes changed.5. Tell the user (in their language): annotations applied, new PPTX exported, preview is still running. If the browser still shows the old slide, refresh or reselect the page.6. Loop: more annotations submitted → repeat from step 1. User signals done or "stop preview" → end.----## Notes (editor invariants — referenced from SKILL.md Step 6)+## Notes (editor invariants — referenced from Generate Step 6)- **UI**: trilingual (中文 / English / 日本語); auto-detects from `navigator.language`, persists in `localStorage`, switched via the language dropdown on the right panel. The right panel is an **Edit / Annotate** surface: direct SVG edits and AI-needed annotations are visually separated, with a pending-status strip showing staged direct edits and pages with unsaved annotations. Slide navigation: first/prev/next/last buttons at the top of the center panel, plus `←` / `→` / `Home` / `End` (suppressed while typing in the annotation textarea).- **Buttons**: `Add annotation` stages annotation text in memory; `Apply changes` writes staged direct edits plus annotation markers to disk and keeps the service running; `Exit preview` is the only UI action that stops Flask.diff --git a/skills/ppt-master/workflows/stages/refine-spec.md b/skills/ppt-master/workflows/stages/refine-spec.mdindex 50bd3fb4..fa438790 100644--- a/skills/ppt-master/workflows/stages/refine-spec.md+++ b/skills/ppt-master/workflows/stages/refine-spec.md@@ -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 stage never starts.+**Default is OFF.** Strategist surfaces this option as one short opt-in line inside the Strategist confirmation stage (see [`generate-pptx`](../generate-pptx.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.@@ -26,7 +26,7 @@ The user **explicitly asks** to refine / review / revise the spec before generat## Step 1: Produce the full spec-Run the default Strategist output exactly as SKILL.md Step 4 specifies: write `design_spec.md` (§I–X) and `spec_lock.md`. Read the relevant `sources/` files so the content outline (`§IX`) carries real facts, not skeleton points. Nothing special here — this is the normal spec, just produced under the knowledge that the user is about to review it.+Run the default Strategist output exactly as [`generate-pptx`](../generate-pptx.md) Step 4 specifies: write `design_spec.md` (§I–X) and `spec_lock.md`. Read the relevant `sources/` files so the content outline (`§IX`) carries real facts, not skeleton points. Nothing special here — this is the normal spec, just produced under the knowledge that the user is about to review it.---@@ -55,6 +55,6 @@ These overlap with what the locked `mode`, visual style, and §6.1 already shape## Step 3: Hand back-Once 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).+Once the user approves, `design_spec.md` and `spec_lock.md` both reflect the final, revised state. Return to [`generate-pptx`](../generate-pptx.md): Step 5 when any `ai` / `web` rows require acquisition, otherwise Step 6.-> 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.+> 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`](../../references/strategist.md) and [`generate-pptx`](../generate-pptx.md) remain authoritative for spec content and route sequencing.diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.mdindex dd2a075d..4036e9b4 100644--- a/skills/ppt-master/workflows/stages/resume-execute.md+++ b/skills/ppt-master/workflows/stages/resume-execute.md@@ -4,9 +4,9 @@ description: Main-pipeline control stage for resuming execution in a fresh chat# Resume Execute Stage-> 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.+> Generate-PPTX control stage for a fresh execution session. Run when [`generate-pptx`](../generate-pptx.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 inside the already selected Generate route.-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.+This stage is **context-independent**: it owns the execution session starting from a fresh chat — no upstream conversation context required. Persisted project artifacts replace the planning session's confirmation dialogue and image-acquisition history.## When to Run@@ -36,15 +36,15 @@ Verify the project's planning-session artifacts before doing anything else:If any required artifact is missing, report it and stop this stage. Do not enter Step 6 or invent a replacement artifact. Recover by artifact owner:- Missing `design_spec.md` / `spec_lock.md` → use [`failure-recovery.md`](../governance/failure-recovery.md) §3.-- Missing `images/`, or a file whose status requires existence → recover by provenance: an `Acquire Via: user` / `Status: Existing` file is a required manual artifact, so use `failure-recovery.md` §2 and wait for the user to restore that exact file; a template-bundled bitmap returns to SKILL.md Step 3 to restore the selected workspace; an AI, web, formula, or slice output uses its matching row in `failure-recovery.md` §1 to reacquire, rerender, or derive it. An absent `Needs-Manual` file is not a Step 1 failure.-- Missing `templates/` inputs → restore the selected workspace through `SKILL.md` Step 3. If the workspace is unavailable or invalid, run Create Template again rather than reconstructing a template inside this stage.+- Missing `images/`, or a file whose status requires existence → recover by provenance: an `Acquire Via: user` / `Status: Existing` file is a required manual artifact, so use `failure-recovery.md` §2 and wait for the user to restore that exact file; a template-bundled bitmap returns to [`generate-pptx`](../generate-pptx.md) Step 3 to restore the selected workspace; an AI, web, formula, or slice output uses its matching row in `failure-recovery.md` §1 to reacquire, rerender, or derive it. An absent `Needs-Manual` file is not a Step 1 failure.+- Missing `templates/` inputs → restore the selected workspace through [`generate-pptx`](../generate-pptx.md) Step 3 and [`apply-template-workspace`](apply-template-workspace.md). If the workspace is unavailable or invalid, run Create Template again rather than reconstructing a template inside this stage.----## Step 2: Load SKILL.md, proceed from Step 6+## Step 2: Load the Generate authority, proceed from Step 6```-Read skills/ppt-master/SKILL.md+Read skills/ppt-master/workflows/generate-pptx.md```Then jump to `### Step 6: Executor Phase` and run the documented pipeline:@@ -57,11 +57,11 @@ Then jump to `### Step 6: Executor Phase` and run the documented pipeline:- Speaker notes generation- Step 7: Post-processing & Export (`total_md_split` → `finalize_svg` → `svg_to_pptx`)-The fresh session pays the cost of re-reading references (~14K tokens) but earns back substantially more headroom by dropping the planning session's accumulated context. Net win in both window pressure and reasoning budget per page.+Reload the Generate authority and required execution references; do not reconstruct or replay the earlier planning conversation.-**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.+**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.-> 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.+> Note: this stage does NOT duplicate Step 6 / Step 7 content. `generate-pptx.md` is the authoritative procedure; resume-execute only adds the resumption entry, sanity check, and source-materials guidance.---@@ -69,4 +69,4 @@ The fresh session pays the cost of re-reading references (~14K tokens) but earnsWhen 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) stage 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 [`generate-pptx`](../generate-pptx.md); resume mode handles it the same way as continuous mode.diff --git a/skills/ppt-master/workflows/stages/topic-research.md b/skills/ppt-master/workflows/stages/topic-research.mdindex 8959891c..9f858517 100644--- a/skills/ppt-master/workflows/stages/topic-research.md+++ b/skills/ppt-master/workflows/stages/topic-research.md@@ -4,18 +4,18 @@ description: Main-pipeline intake stage that gathers source material for topic-o# Topic Research Stage-> 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, a stable fact-provenance file, and an image folder, all shaped to feed `project_manager.py import-sources` directly.+> Generate-PPTX intake stage. Run before [`generate-pptx`](../generate-pptx.md) Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document, a stable fact-provenance file, and an image folder, all shaped to feed `project_manager.py import-sources` directly.-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.+This stage is **context-independent**: it owns source acquisition when no file exists; subsequent [`generate-pptx`](../generate-pptx.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 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 |+| Topic name only (e.g. "做一个关于宫崎骏的 PPT") | Run this stage before Generate Step 1 |+| Requirement description without facts (e.g. "介绍我们公司新产品") | Run this stage before Generate Step 1 |+| ≥1 page of substantive content already in chat | Skip — feed chat content into [`generate-pptx`](../generate-pptx.md) Step 1 directly |+| Source file attached (PDF / DOCX / URL / Markdown) | Skip — go to [`generate-pptx`](../generate-pptx.md) Step 1 source conversion |---@@ -141,7 +141,7 @@ The Research Brief is evidence-facing context, not a locked presentation contrac- [x] Document: `projects/<topic_slug>.md` (N sections)- [x] Facts: `projects/<topic_slug>.facts.json` (N external facts)- [x] Images: `projects/<topic_slug>/` (N files)-- [ ] **Next**: SKILL.md Step 2 →+- [ ] **Next**: [`generate-pptx`](../generate-pptx.md) Step 2 →`project_manager.py init <project_name> --format <format>``project_manager.py import-sources projects/<project_name> projects/<topic_slug>.md projects/<topic_slug>.facts.json projects/<topic_slug>/*.* --move````diff --git a/skills/ppt-master/workflows/stages/verify-charts.md b/skills/ppt-master/workflows/stages/verify-charts.mdindex 87eb82b0..861557fa 100644--- a/skills/ppt-master/workflows/stages/verify-charts.md+++ b/skills/ppt-master/workflows/stages/verify-charts.md@@ -256,10 +256,5 @@ 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)):--```bash-python3 skills/ppt-master/scripts/total_md_split.py <project_path>-python3 skills/ppt-master/scripts/finalize_svg.py <project_path>-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>-```+Continue with [`generate-pptx`](../generate-pptx.md) Step 7. That authority owns+the serial commands, gates, and success criteria for post-processing and export.diff --git a/skills/ppt-master/workflows/stages/visual-review.md b/skills/ppt-master/workflows/stages/visual-review.mdindex e2501f98..5078bc29 100644--- a/skills/ppt-master/workflows/stages/visual-review.md+++ b/skills/ppt-master/workflows/stages/visual-review.md@@ -12,13 +12,13 @@ description: Optional quality-gate stage for per-page rubric-based visual review## Positioning-This is an **optional auxiliary loop**, opt-in only. The main pipeline (SKILL.md Step 1–7) does not invoke it; trigger only when the user explicitly asks for a visual re-pass on the generated SVGs before export.+This is an **optional auxiliary loop**, opt-in only. The [`generate-pptx`](../generate-pptx.md) Step 1–7 pipeline does not invoke it; trigger only when the user explicitly asks for a visual re-pass on the generated SVGs before export.**Token cost**: each batch subagent re-reads the rubric + `design_spec.md` + `spec_lock.md` and processes K SVG+PNG pairs. For a 20-page deck with K=5, expect on the order of 100–150K additional input tokens on top of the main generation run.## When to Run-- Executor (SKILL.md Step 6) has finished all pages+- Executor ([`generate-pptx`](../generate-pptx.md) Step 6) has finished all pages- `svg_quality_checker.py` has passed- Post-processing (`finalize_svg.py`, `svg_to_pptx.py`) has **not** yet run- The user has explicitly requested visual review@@ -131,13 +131,9 @@ 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:--```bash-python3 skills/ppt-master/scripts/total_md_split.py <project_path>-python3 skills/ppt-master/scripts/finalize_svg.py <project_path>-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>-```+After the table is clean, continue to [`generate-pptx`](../generate-pptx.md)+Step 7. That authority owns the serial commands, gates, and success criteria for+post-processing and export.---