PPT Master Skill

Entry precondition — route first: Before loading this full file, workflows/routing.md has selected the main SVG family, or another workflow has explicitly handed off to shared SVG steps. Strict 1:1 selection loads beautify-pptx.md first and loads this file only at that workflow's explicit handoff. Raw template fill and finished-PPTX native enhancement do not load or inherit this file.

AI-driven multi-format SVG content generation system. Converts source documents into high-quality SVG pages through multi-role collaboration and exports to PPTX.

Main SVG Pipeline: Source Document → Create Project → [Template] → Strategist Structured Plan → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export

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/	On-demand derived, self-contained SVG visual preview (deferred by default — generated by Step 7.2 only when SVG previews / manual insertion are requested). 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 may reorganize represented content into Master/Layout/Slide structure but MUST NOT invent new visible page content.
Direct PPTX and presentation-behavior workflows	Remain separate. The ppt-template-fill skill, 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.”

[!IMPORTANT]

Execution Discipline

The pipeline is serial; these rules hold for every run:

1. Serial execution — Run steps 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 = stop — At a step marked ⛔ BLOCKING, stop and wait for an explicit user response before proceeding; do not make decisions on the user's behalf there
3. No cross-phase bundling — Do not bundle work across phases. (Note: the Strategist confirmation stage in Step 4 is ⛔ BLOCKING — 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 lists its prerequisites (🚧 GATE) at the top; verify them before starting that Step
5. No speculative execution — Do not pre-prepare content for later Steps (e.g., writing SVG code during the Strategist phase)
6. No sub-agent SVG generation — Executor Step 6 SVG generation is context-dependent, so the current main agent completes it end-to-end; do not delegate page SVG generation to sub-agents
7. Sequential page generation — In Executor Step 6, after the global design context is confirmed, generate SVG pages sequentially page by page in one continuous pass, not in grouped batches (for example, 5 pages at a time)
8. spec_lock milestone re-read — Executor runs read_file <project_path>/spec_lock.md before the first page of each 4-page block (P01, P05, P09, …) and immediately after any context compaction. All colors / fonts / icons / images come from this file — no values from memory or invented on the fly; between re-reads the in-context copy from the last read is the working reference. Executor also reads pptx_structure.mode, the current page's page_rhythm (anchor / dense / breathing), and page_charts. Only a deck/layout template route (mode: structured) looks up page_layouts (the input template SVG), pptx_masters, pptx_layouts, and template_adherence; free-design and brand-only routes use mode: flat and omit those sections. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
9. Hand-written SVG, not script-generated — Write each page SVG by hand in the main agent, one page at a time (see rules 6 and 7). Do not write or run a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — 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

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	Owns deterministic route choice before the main pipeline or a standalone workflow
Workflow registry	workflows/index.md	Owns standalone workflow trigger/precondition/output inventory
Artifact ownership	references/artifact-ownership.md	Owns fact channels, source/derived artifact boundaries, and regeneration rules
Failure recovery	workflows/failure-recovery.md	Owns stop/continue decisions for common failures
Confirm UI details	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/preflight.py	Pre-pipeline environment gate — run once after Step 2 (--needs-images when the deck will generate AI images) so a long run never dies mid-pipeline
${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 non-destructive inspection projection of PPTX-imported SVGs; never a release source
${SKILL_DIR}/scripts/svg_quality_checker.py	SVG quality check
${SKILL_DIR}/scripts/text_fit.py	Pre-draw line-fit oracle — checker-identical width verdict + balanced-break suggestion before authoring text (free-design speed path; see references/executor-cheatcard.md §4)
${SKILL_DIR}/scripts/validate_spec.py	Planning artifact gate — design_spec.md §IX/§VII + spec_lock.md coherence, run right after the Step 4 spec output
${SKILL_DIR}/scripts/preset_shape_svg.py	Print one registry-backed native PowerPoint preset fragment to stdout for hand-authored SVG insertion
${SKILL_DIR}/scripts/total_md_split.py	Speaker notes splitting
${SKILL_DIR}/scripts/finalize_svg.py	SVG post-processing (unified entry; on-demand — Step 7.2 is deferred by default)
${SKILL_DIR}/scripts/svg_to_pptx.py	Export to PPTX
${SKILL_DIR}/scripts/verify_deck.py	Final deck verification gate — stage parity/freshness, native PPTX integrity, plan + SVG re-check, optional OfficeCLI OpenXML validation + contact-sheet render (run after Step 7)
${SKILL_DIR}/scripts/run_telemetry.py	Opt-in explicit-run lifecycle + fixed low-variance metric telemetry for pre-registered benchmarks
${SKILL_DIR}/scripts/measure_run.py	Explicit telemetry-run report; legacy artifact timestamps remain non-comparable diagnostics only
${SKILL_DIR}/scripts/benchmark_pipeline_ab.py	Clean-worktree paired A/B harness with fixture/source integrity, quality guards, and pre-registered CI/MCID decisions
${SKILL_DIR}/scripts/native_enhance_pptx.py	Existing PPTX enhancement project init / validation / direct OOXML patch export
${SKILL_DIR}/scripts/native_narration_pptx.py	Backward-compatible entrypoint for existing PPTX notes / narration enhancement
${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.

Opt-in benchmark runtime

Normal deck production does not enable instrumentation. Only for an explicit, pre-registered speed experiment, read the complete Run Telemetry and A/B Benchmarks contract in scripts/README.md and use the three measurement scripts above. That contract owns clean-arm, immutable fixture, quality-equivalence, cache-scope, metric, CI/MCID, and drift rules.

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>

Standalone Workflows

Route authority: Load workflows/routing.md before this full skill or any standalone workflow. After selection, the chosen owner defines its gates; do not import this main pipeline into a direct-PPTX route.

Registry: Use workflows/index.md for the complete workflow list, triggers, preconditions, exclusions, outputs, and blocking points.

PPTX Route Boundary

User intent	Route
Raw PPTX template plus new material/topic, generate a PPTX	ppt-template-fill skill
Existing PPTX, preserve page count/order and slide wording 1:1, improve layout	beautify-pptx
Existing PPTX as source material, rethink outline or change page count/order	Main pipeline via source_to_md.py plus PPTX intake
Build a reusable template package from a PPTX/design reference	create-template, then return with the generated template workspace path
Finished PPTX, keep content/layout stable and add notes/audio/timing/transitions	native-enhance-pptx skill

MUST: Raw .pptx template plus "generate PPTX" routes to the ppt-template-fill skill by default. The SVG generation route consumes only an explicit template workspace path with a valid templates/design_spec.md, or a supported direct/legacy package root with design_spec.md.

MUST: Beautify is strictly 1:1. Any split, merge, drop, reorder, or page-count change routes to the main pipeline.

MUST — reusable template mode boundary: create-template has two distinct 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 restoration path: preserve 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 restoration authority; the lightweight authoring projection exists only to keep model context small. 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. Export compiles the selected contract and never infers a different one. Because the current structured roster materializes only identities referenced by emitted page prototypes, mirror is available only when every source Layout is used by a source Slide and every source Master is reachable through those Layouts. Otherwise stop and report the exact unreachable identities; never drop them or invent a carrier page.

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 workflow 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.

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).

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:

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; beautify and template-fill workflows decide separately which fields become locked constraints.

Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own <stem>.* artifacts and a deck entry in source_profile.json. source_profile.json stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify / template-fill workflows remain single-deck (1:1 to one chosen source deck) and read that deck's <stem>.* artifacts.

⚠️ 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.

Environment preflight (recommended): run once here so a long run never dies mid-pipeline on a missing dependency — resolve any FAIL before Step 4; warnings are informational:

python3 ${SKILL_DIR}/scripts/preflight.py            # add --needs-images when the deck will generate AI images

✅ 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 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, then return with the generated template workspace path. Step 3 consumes an explicit workspace whose templates/design_spec.md declares kind: brand / kind: layout / kind: deck, or a compatible legacy-flat package whose root design_spec.md declares one of those kinds.

Do not reinterpret this boundary as 1:1 redesign or free SVG generation. Use template-fill for raw PPTX template + generated PPTX requests; use beautify only when the source deck's page count, order, and wording are preserved.

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
Explicit template-seeking intent without a path ("use a template", "想用个模板", "템플릿 써줘"), or a bare name matching a deck id in decks_index.json ("apple 템플릿으로")	Ask the single narrow disambiguation question below, then either consume the confirmed deck path as a normal explicit-path trigger or take free design
Anything else — bare layout/brand names ("用 academic_defense", "anthropic"), style descriptions ("麦肯锡风格"), or silence	Skip Step 3, free design (the Step 4 template card still offers the deck library)

There is no fuzzy resolution into an install. A deck-id mention or explicit template intent triggers only the single disambiguation question below — never a direct install; every other name flows to free design. The path that enters the install is always one the user confirmed.

Narrow disambiguation (single question, only on the trigger above). List the matched deck(s) — or, for pure intent with no name, up to 3 decks most relevant to the content — each with its workspace path (templates/decks/<id>/) and one-line summary from decks_index.json, plus a "free design" option. In Claude Code surface this with the AskUserQuestion tool; other hosts ask the same single question in chat. A deck answer confirms that explicit path (normal Step 3 install); free design skips Step 3 — the Step 4 template card still allows re-picking. Ask at most once per run, and never when the trigger did not fire.

Structured-template preflight (before copy): For every deck/layout workspace, inspect all SVG roots and slots under its normalized template source. Every page must declare root Master/Layout key and picker names; Master/Layout visuals must be direct atoms rather than <g>; every slot must be a top-level <g> with positive bounds and exactly one compatible carrier, or an explicit composite object proxy. A zero-slot Layout is valid. If the SVG package uses a legacy semantic contract, run restore-pptx-structure first and return to Step 3 with the migrated workspace. A legacy flat directory shape alone is read compatibility and does not trigger restoration.

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 that match a deck id trigger only the disambiguation question above. Layout/brand bare names ("academic_defense", "anthropic") do NOT trigger Step 3 even if a matching directory exists — the user must give a path. AI must never silently resolve a name to a path and install it without the user's answer.

"What templates exist?" is out-of-band Q&A — answer by listing entries from brands_index.json / layouts_index.json / decks_index.json together with their paths. Listing alone does not advance the pipeline; the user must send a path back to trigger Step 3.

To create a new layout or deck, read workflows/create-template.md. To create a new brand, read workflows/create-brand.md.

Three template kinds

The architecture has three independent reference bundles. Full schema in docs/templates-architecture.md. 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	structure-only segment: canvas / page structure / page types / SVG roster	kind: layout
deck	templates/decks/<id>/templates/ inside a complete workspace	full identity + structure reference with the middle (template overview) segment	kind: deck

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 / Page Types / SVG Roster	layout
Middle	Template Overview (use cases / design intent)	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/. Strategist locks identity; structure stays free.
kind: layout	Install templates/ plus any existing images/ and icons/ into the matching project roots; ignore exports/. Strategist locks structure; identity is decided in confirmation fields e–g.
kind: deck	Install templates/ plus any existing images/ and icons/ into the matching project roots; ignore exports/. Strategist locks all segments; confirmation narrows to deck-content fields.

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/, runtime icons in 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 or consume those semantic contracts through Step 3. Run restore-pptx-structure on the package first, then return with the migrated workspace path. Old flat packaging remains readable when its SVG structure is already current.

The Strategist confirmation stage decides whether the selected deck/layout template is used strict or adaptive. Those template projects use pptx_structure.mode: structured, map every page to one input SVG in page_layouts, and write complete pptx_masters / pptx_layouts output mappings before SVG generation. Brand-only projects remain on the free-design mode: flat route. Strict preserves the template's declared Master/Layout/slot contract. Adaptive keeps the template Master and may assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.

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 / middle 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	Middle from
brand only	brand	(free design)	(none)
layout only	(free design)	layout	(none)
deck only	deck	deck	deck
brand + layout	brand	layout	(none)
brand + deck	brand (overrides deck)	deck	deck
layout + deck	deck	layout (overrides deck)	deck
brand + layout + deck	brand	layout	deck

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:

> **Fused from:**
> - deck: `templates/decks/招商银行/` （base）
> - brand: `templates/brands/anthropic/` （identity override）
> - layout: `templates/layouts/academic_defense/` （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 bundle: deck when both identity and structure are present, layout when only structure is present, and brand when only identity is present. Keep this field accurate; the Strategist confirmation server uses it to show template adherence only for bundles that actually own page structure.

Deferred install — template card

When Step 3 took the free-design default, the Step 4 Confirm UI page still offers a decks-only template card (catalog synced live from decks_index.json; free design is the default). If the confirmed result.json carries template: "<deck_id>", run this Step's install for templates/decks/<deck_id>/ at that point — same kind matrix, same structured-template preflight, no bypass — in the same turn, before writing design_spec.md / spec_lock.md (the deck-declared skin then overrides the color / typography fields the user left at your original recommendation — Step 4 reconciliation). On preflight failure do NOT silently fall back to free design: report the error in chat and let the user re-pick (another deck or free design). template: "free" (or the field's absence) keeps the free-design path. When a template was already installed via an explicit path, the card renders locked (informational) and no deferred install happens.

✅ 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. A template-card selection installs later, at the Step 4 confirmation handoff (see Deferred install above).

---

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. 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 one single-pass page (every field authored up front, confirmed at once; see below); the chat fallback mirrors the same single bundle. The staged three-stage flow remains available only when the user explicitly asks to confirm stage by stage (scripts/docs/confirm_ui.md).

1. Canvas format
2. Page count range
3. Target audience
4. Style objective
5. Template adherence — strict / adaptive (only when Step 3 loaded a deck/layout template)
6. Color scheme
7. Icon usage approach
8. Typography plan, including formula rendering policy
9. Image usage approach

Confirm UI Auto-Launch (Mandatory — default visual confirmation surface): by default the Strategist confirmation stage is presented through an interactive local page as one single-pass session — the AI authors every recommendation up front (direction anchors, design system, images / execution) and the page renders all sections at once; the user adjusts any field and confirms once. Color swatches, live font previews, icon samples, image-style reference previews, and candidate picks appear where they help judgment; the chat path is the always-valid fallback. scripts/docs/confirm_ui.md owns the schema, server lifecycle, port strategy, and fallback details; this section keeps the orchestration contract. The field groups:

Group	Fields	Anchored by
direction anchors	template (decks-only card; free-design default — leads the page, a deck pick re-defaults the anchors below it; locked informational when Step 3 already installed a template) · template_adherence (only when Step 3 loaded a deck/layout template, or a deck card is selected) · canvas · audience + core message + content_divergence + delivery_purpose (PPT only — omitted on non-PPT canvases) (all §c key info) · mode + visual_style	the source + user intent
design system	page count · color · typography (font + size) · icons · formula policy	the direction anchors
images / execution	image usage · generated-image style · AI-image generation path · generation mode · refine-spec toggle	direction + design system

Why this order. Design-system fields are anchored by the same few choices (visual_style anchors color / icon / typography; delivery_purpose sets the body size, page density, and the page-count recommendation); image strategy depends on the visual direction and the color system — its palette is color behavior only, while final HEX values follow the confirmed color. Author the bundle in that dependency order so it is internally coherent. Page count is a derived field (content volume × delivery_purpose). Coherence with the user's real choices is restored after the single confirmation: the page's client-side cascades re-default declared fields on a deck pick, and the mandatory reconciliation rule below re-derives downstream fields the user did not edit when an anchor changed.

Steps:

1. Write the complete recommendations to <project_path>/confirm_ui/recommendations.json with no top-level stage key — the page then renders every section in one pass (the stage selector is reserved for the explicit staged flow). One authoring pass carries all fields. Enumerable fields name a recommended canonical id in a recommend block (the page lists common options from confirm_ui/static/catalogs.json): canvas / mode / visual_style / delivery_purpose / icons / formula_policy / image_usage (source-id array; none exclusive) / image_ai_path (only when image_usage includes ai) / generation_mode. visual_style also carries the ≥3-style visual_style_spectrum (safe / shifted / bold — same hard rule as h.5). When Step 3 loaded a deck/layout template, also set recommend.template_adherence to strict or adaptive; omit the field entirely for free design and brand-only templates so the page does not display it. Always set recommend.template for the template card: a deck id from decks_index.json only when the content genuinely matches that deck's use cases, otherwise "free" (the honest default — see strategist.md §1). When a template is already installed via an explicit path the card renders locked and the key may be omitted. audience and content_divergence are plain { "value": "<free text>" } (content_divergence: how closely to follow the source vs how freely to reshape it — blank = balanced; facts stay sourced at every level; consumed for §IX, recorded in design_spec.md §I, never written to spec_lock.md). page_count follows content volume × the recommended delivery_purpose. color and typography are generative ≥3-candidate fields (a hard-locked field — e.g. the install-local Pretendard typography lock or a template-declared skin — is an honest-shortfall case: author the single locked plan instead of 3) (color: core palette with background/secondary_bg/primary/accent/secondary_accent/body_text; typography: CJK + Latin for heading and body with css preview stacks, topic-matched sample_* texts, and body_size in px — one fixed value per recommended delivery_purpose: text 20 / balanced 24 / presentation 32). When image_usage includes ai, image_strategy.candidates carries exactly three non-custom h.5 rendering × palette recommendations (the page adds the fourth Custom card itself), with usage rationale in image_notes. Include refine_spec (recommended boolean). Set lang to the page language (zh / en / ja / ko); visible text matches lang, or provide multilingual name_zh / name_en / name_ja / name_ko + note_zh / note_en / note_ja / note_ko — when the user's language is Japanese or Korean, set lang: "ja" / lang: "ko" and always include the matching _ja / _ko variants (labels resolve in the page language first, so missing _ja / _ko labels silently render in English). Full schema: scripts/docs/confirm_ui.md.
2. Launch + wait for the confirmation (the ⛔ BLOCKING wait). Background launch; the parent returns when the page writes the final result.json (status: confirmed). Long tool timeout — 600000 ms (the --wait ≈590 s budget):

   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. 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: confirmed before dropping to 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.
3. Reconcile the confirmation before writing the spec (Mandatory — same turn). Read result.json. Deferred template install: if the result carries template: "<deck_id>" and no template is installed yet, first run the Step 3 deferred install for that deck (same kind matrix + structured preflight — no bypass); on preflight failure report in chat and let the user re-pick instead of silently downgrading. Then apply the "Upstream override → re-derive untouched downstream" rule below: when the user changed an anchor (or picked a deck template), re-derive only the downstream fields the user did not themselves edit; every value the user set stays verbatim. Spot-illustration lean is not a confirmation field: it derives from the locked visual_style's illustration propensity and is expressed only in image_notes rationale. Generated-image style palettes are color behavior only; final image colors follow the confirmed color.
4. 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):

   python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown
   

   Idempotent and required regardless of whether Confirm was clicked: clicking 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 the recommendations + URL in chat as the always-valid fallback. The chat fallback is a single bundle too: if the page never opens or the wait times out with no fresh result, present the full recommendation bundle in chat → get one confirmation → take those values (step 3 reconciliation still applies). Either path converges. (Only an explicit user request for stage-by-stage confirmation uses the staged flow — stage schema, waits, and progression guard in scripts/docs/confirm_ui.md.)

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:

result.json.image_usage	§VIII Acquire Via	h.5 + Step 5 generation
ai	ai rows	Run h.5 (lock rendering + palette); 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-images.md. Use them on suitable pages and omit them where they would weaken clarity.

Upstream override → re-derive untouched downstream (Mandatory — every single-pass confirmation). Anchors and downstream fields are confirmed together, so "confirmed value wins" governs each field's own value — never recompute a value the user set (a size, canvas, or palette they edited stays verbatim). But the result.json can carry a changed anchor beside downstream fields still holding your original — now incoherent — recommendation (e.g. switched to dark-tech while the light palette you proposed is untouched). Before writing the spec, reconcile: when the user changed an anchor, re-derive the downstream fields the user did not themselves edit so they realize the new anchor; fields the user pinned stay as confirmed.

Anchor the user changed	Re-derive (only the downstream fields the user left at your recommendation)
template (free → deck id — deferred install ran)	color palette + typography from the deck-declared skin (including any body-baseline lock / native type ramp)
visual_style (§d Layer 2 — anchors e–h)	color neutral tiers (§e), icon library / stroke (§f), typography character (§g), image rendering (§h.5)
mode (§d Layer 1)	outline structure + register (§IX)
delivery_purpose (§g)	body baseline + per-page density / rhythm (§6.1)
audience / core message (§c)	tone across e–h, outline emphasis (§IX)
color HEX (§e)	h.5 palette (re-filter for the new HEX)

Reconcile without a new blocking wait — fold the coherent values into design_spec.md / spec_lock.md and state the adjustment in the §8 next-step handoff (e.g. "you switched to dark-tech; the light palette you had left no longer fit, so background / accent were re-derived — tell me if you wanted the original"). Canvas is the explicit exception: font sizes are deliberately not rescaled on a canvas change (see strategist §g).

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 for the reply; reconcile; shutdown is a no-op).

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 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.

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 workflow. Default is OFF: no request → the spec is written in one go and the pipeline auto-proceeds as usual. Only when the user explicitly asks in chat (e.g. "refine the spec first") or confirms refine_spec: true through Confirm UI does the refine-spec workflow take over after the Strategist confirmation stage. This line, like the split-mode line, is required output every run — the user must see the choice exists; whether to act on it is theirs. When the Confirm UI is used, this choice also appears as the in-page refine-spec toggle and is captured in result.json (refine_spec); the chat-summary fallback still prints this line.

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:

   python3 ${SKILL_DIR}/scripts/latex_render.py <project_path>
   

4. Include the rendered formula PNGs as Acquire Via: formula, Status: Rendered, Type: Latex Formula rows in design_spec.md §VIII Image Resource List; also list them 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. 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:

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 §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 facts: take size / ratio / category for images/ assets from analysis/image_analysis.csv (regenerated on use) or the Design Spec's Image Resource List rather than inspecting source files, so every step shares one fact view. Rendered review files (.preview/, _pptx_render/, images/.review/) are meant to be read.

Early background image launch (Mandatory when the confirmed image_usage includes ai and/or web): acquisition wall-clock must overlap spec writing, not block Step 6. Fix the §VIII image resource plan first — rows, filenames, per-row intent — then launch acquisition as background processes and keep authoring while they run:

1. Read references/image-base.md plus the path-specific reference(s) for the confirmed sources (references/image-generator.md for ai, references/image-searcher.md for web) — the same files Step 5 loads; Step 5's re-read is then a no-op.
2. Write <project_path>/images/image_prompts.json (ai rows — the §VIII manifest contract is unchanged) and/or <project_path>/images/image_queries.json (≥2 web rows), then launch in the background (do NOT wait for completion):

   python3 ${SKILL_DIR}/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json    # background process
   python3 ${SKILL_DIR}/scripts/image_search.py --batch <project_path>/images/image_queries.json    # background process
   

3. Continue immediately with the design spec output below. §VIII rows carry Status: Pending until Step 5 reconciles the background results.

The confirmed image path still wins before any launch (codex / api / auto per image-generator.md §7; manual skips generation entirely — launch nothing). The Path A recovery ladder and the web-switch offer move to Step 5's collection point — a failed background run is diagnosed there, never mid-spec. A single web row may use the positional image_search.py form. slice rows stay in Step 5 (sheets must finish before slicing). FALLBACK: if the host cannot run background processes, skip this block — Step 5 acquires in the foreground exactly as before.

Output:

• <project_path>/design_spec.md — human-readable design narrative
• <project_path>/spec_lock.md — machine-readable execution contract (skeleton: templates/spec_lock_reference.md); Executor re-reads on the milestone cadence (executor-base.md §2.1)

Spec validation (Mandatory — run immediately after writing both files): fix every reported error before the checkpoint — a planning defect found after 20 generated pages costs a whole-deck rewrite:

python3 ${SKILL_DIR}/scripts/validate_spec.py <project_path>

✅ Checkpoint — Phase deliverables complete, auto-proceed to next step:

## ✅ 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 workflow)
- [x] Background image acquisition launched before spec writing (only when confirmed `image_usage` includes `ai`/`web`; skipped for `manual` / `none` / hosts without background processes)
- [x] Design Specification & Content Outline generated
- [x] Execution lock (spec_lock.md) generated
- [x] validate_spec.py passed (0 errors) on design_spec.md + spec_lock.md
- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase

---

Step 5: Image Acquisition Phase (Conditional)

🚧 GATE: Step 4 complete; Design Specification & Content Outline generated and user confirmed. Any formula rows already have Acquire Via: formula and Status: Rendered.

Trigger: At least one row in the resource list has Acquire Via: ai, web, and/or slice. If every row is user, formula, or placeholder, skip to Step 6.

Failure recovery: stop/continue behavior for AI/web/slice/image-readiness failures is defined in workflows/failure-recovery.md. This Step keeps the acquisition procedure.

Default — collection point (Step 4 already launched the background acquisition): when the Step 4 early launch ran, this Step collects rather than starts: check the background runs' written-back statuses (image_prompts.json / image_sources.json), run the Path A recovery ladder / web-switch offer (image-generator.md §7) only for rows the runs left Failed, slice sheets (step 2.5), re-run analyze_images.py (step 4), and complete the checkpoint. If a background run is still in flight, do NOT idle-wait here — proceed to Step 6 under its deferred-image-pages rule and finish this collection at the image-page boundary. Only when no early launch happened (confirmed manual, no ai/web rows, or a host without background processes) does this Step acquire in the foreground per the workflow below.

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 (codex → API backend → web-sourcing switch → user-drop)
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, then execute the ladder from image-generator.md §7: Path A codex (with install/login recovery + retry) → Path B API backend (only when a key is already configured) → web-sourcing switch → user-drop. The manifest is a machine/audit artifact — never hand its prompts to the user, and render no Markdown sidecar. The positional form (image_gen.py "prompt" ...) is reserved for out-of-pipeline one-off testing / single-image fixups — it skips the manifest, 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 §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 §4.3.

⚠️ Honor the confirmed image path before running any generation command: a confirmed choice other than auto wins, whether it came from chat (canonical) or, when the page was used, result.json.image_ai_path. codex forces Path A only (unrecovered failure → web/user-drop, never the API backend); api forces Path B. Legacy values: host-native reads as auto; manual skips generation entirely — go straight to the user-drop handoff, never run image_gen.py --manifest. Full selection rule: 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 the first image-placing page is authored. Executor MAY start on image-less pages while a background acquisition finishes (Step 6 deferred-image-pages rule); a foreground acquisition completes all rows here before Step 6
2. Generate prompts (ai rows) and/or run search (web rows) per 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 §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. The agent must resolve every residual Failed item by rerunning the confirmed path or marking it Needs-Manual before Executor starts
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:

## ✅ Image Acquisition Phase Complete
- [x] image_prompts.json created (when any ai rows processed)
- [x] Path A recovery guidance printed and retried (only when Path A failed on a fixable cause)
- [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"), first complete this Step's collection in full (all rows terminal — a background process does not survive the session handoff), then output the planning-session handoff below and stop this conversation:

## ✅ Planning Session Complete
- [x] Spec: `design_spec.md`, `spec_lock.md`
- [x] Resources: `sources/`, `images/`, `templates/`
- [ ] **Next**: open a fresh chat window and input `继续生成 projects/<project_name>` to enter the execution session via the [`resume-execute`](workflows/resume-execute.md) workflow.

On acquisition failure, do NOT halt — follow the Failure Handling rule in 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 complete, and Step 5 (if triggered) either complete or reduced to a still-running Step-4 background acquisition — then enter under the deferred-image-pages rule below. All other 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.

⚡ Speed accelerators (free-design flat decks only — no template, no charts, no images). For the pptx_structure.mode: flat route you MAY:

1. read the one-screen references/executor-cheatcard.md in place of re-reading executor-base.md + shared-standards.md end-to-end (still read the short mode + visual-style files);
2. instantiate page skeletons from references/layout-archetypes.md instead of re-deriving geometry per pattern;
3. pre-check each page's text with one python3 ${SKILL_DIR}/scripts/text_fit.py --batch <page.json> page object (width + vertical + collision; single-line form "text" -s <fs> --x <x> stays valid) before drawing, to skip the write→quality-warning/error→edit loop. These are optional aids, not a new route: the spec_lock values, gates, grouping, and Step 7 export are unchanged. For structured/template, chart, image, mirror/beautify, or notes decks, read the full references below instead — the card omits their contracts.

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 references/native-objects.md                 # CONDITIONAL: deck plans data-chart or text-grid table pages (spec_lock.md `page_charts` / design_spec.md §VII) — marker schemas for executor-base.md §3.2 transcription
Read references/structured-templates.md           # CONDITIONAL: spec_lock.md `pptx_structure.mode: structured` or a mirror template — Master/Layout/placeholder authoring + mirror consumption
Read references/speaker-notes.md                  # CONDITIONAL: design_spec.md §X records a speaker-notes request (default off)
Read .claude/skills/diagram-design/SKILL.md       # CONDITIONAL: deck has structural/conceptual diagram pages (routing: executor-base.md)

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/. Load each CONDITIONAL file only when its trigger holds for this deck — never proactively "just in case"; a mid-deck trigger change (e.g. the user adds a chart page) loads the file once at that point.

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:

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/live-preview.md.
• The editor also supports staged direct edits (text content + SVG element attributes previewed immediately, then written to svg_output/ only when the user clicks Apply changes; Ctrl+Z / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see workflows/live-preview.md Notes.

Pre-generation Batch Read (Mandatory): before the first SVG, batch-read every distinct layout SVG referenced in spec_lock.page_layouts and every distinct chart SVG referenced in spec_lock.page_charts (plus any §VII backup charts). One read per file, up front — do not re-read these during page generation. See executor-base.md §1.0.

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).

Deferred image pages (only while a Step-4 background acquisition is still running): author the pages that place no §VIII image first. Before the FIRST page that places one, complete Step 5's collection: every ai/web/slice row terminal (recovery ladder for Failed rows), sheets sliced, analyze_images.py re-run for measured sizes. If only image-placing pages remain and rows are still generating, wait for the background run (or resolve per workflows/failure-recovery.md) — never lay out an image without its measured facts. Page order is otherwise the author's choice; rules 6/7 (main-agent, sequential one-continuous-pass) are unchanged — this defers which page comes next, not how pages are authored.

Milestone spec_lock re-read (Mandatory): read_file <project_path>/spec_lock.md before the first page of each 4-page block (P01, P05, P09, …) and immediately after any context compaction; use only its colors / fonts / icons / images, plus pptx_structure.mode and the per-page page_rhythm / page_charts lookups. Read page_layouts / pptx_masters / pptx_layouts only on a structured deck/layout template route; they are absent in flat free-design and brand-only projects. Resists context-compression 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: 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. Never infer a preset from contour similarity.

Template 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. Non-mirror fill/stroke/effects/font sizes still follow spec_lock.

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, 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 uses PowerPoint's default Master and Blank Layout; 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-native; 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.

Milestone gate (Mandatory) — after page 1, and after every 4th page thereafter (P04, P08, …):

python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>                    # P01 gate: full run (whole deck = 1 page; contract checks included)
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --pages 2-4        # later gates: ONLY the block authored since the last gate (5-8, 9-12, …)

The page-1 run is the strictest instance — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite; fix every error before drawing page 2. Each later run is incremental: --pages re-checks only the block authored since the last gate, so already-dispositioned earlier-page findings are not re-surfaced (deck-wide contract checks defer to the final full sweep below). Fix every error while the block's context is hot, and disposition each text geometry: warning immediately (same one-line disposition contract as the deck-wide gate below). Clean block: continue to the next page; report the gate only when it found something to fix. Repair scope stays ≤4 hot pages; the deck-wide sweep and the checker's spec-lock drift check backstop the gaps.

Quality Check Gate (Mandatory) — after all SVGs, BEFORE annotation handling and speaker notes (with the milestone gate in force this is a parity sweep — expect only cross-page or late-edit findings; any residual finding still follows the rules below):

python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>

• Any error (banned SVG features, viewBox mismatch, spec_lock drift, text-geometry overflow / cross-group collision, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.
• warning entries (low-res image, non-PPT-safe font tail, etc.): fix when straightforward, otherwise acknowledge and release.
• Text-geometry warnings are never acknowledge-and-release. For each text geometry: warning (unnecessary wrap / over-width copy), output one disposition line: the fix applied (unwrap to one line, redistribute the zone, re-break at a balanced word boundary, or apply a bounded copy trim per the executor-base.md repair ladder — trims are the last resort and capped; never gut the copy to force a fit) or why the flagged break is intended (e.g. a deliberate balanced two-line lead, quoted verse keeping its authored breaks). Default is fix.
• Structured template routes only — PPTX-structure warnings are the exception. For each empty-Layout / framing-only-Layout / bare-Master / duplicate-layout-key warning, output one disposition line: either the fix applied (merge keys in spec_lock.md pptx_layouts + SVG roots, mark the missing slots/layers) or why the flagged state is intended (e.g. "P01 cover is a fixed composition, zero-slot by design"). Flat free-design and brand-only routes have no positive Master/Layout checkpoint; the checker instead enforces a complete flat lock and the absence of Master/Layout/layer/placeholder metadata. "0 errors" alone does not pass a structured template gate when such warnings remain undispositioned.
• Run against svg_output/ (not after finalize_svg.py — finalize rewrites SVG and masks violations).

Selective pixel check (automatic, non-blocking) — after the gate reaches 0 errors: if any page carried text geometry: findings, or overlays text on a full-bleed hero / scrim or a low-opacity watermark (the static checker exempts those zones, so arithmetic alone cannot clear them), render just those pages and eyeball them:

python3 ${SKILL_DIR}/scripts/visual_review.py <project_path> --pages <tokens> --server-url <live-preview URL>

The Step 6 live-preview server is already running — pass its actual URL from the launch log. Read each rendered PNG from <project_path>/.preview/ and fix any real overlap / overflow by hand-editing the SVG (main agent; discipline rules 6 and 9 apply — no sub-agents, no script-generated SVG). If playwright or the server is unavailable, skip silently — the static gate stands alone. This pass is automatic and never a user stop; the full-rubric visual-review workflow remains opt-in.

Logic Construction Phase (opt-in): only when the user requested speaker notes / narration (recorded in design_spec.md §X), generate speaker notes → <project_path>/notes/total.md. Default — no request → skip this phase entirely: write no notes/ files; Step 7.1 is skipped and export simply embeds no notes. A later narration/audio request generates notes on demand via generate-audio.

✅ Checkpoint — Confirm all SVGs (and notes, when requested) are fully generated and quality-checked. Run the applicable conditional gates below, then proceed to Step 7:

## ✅ Executor Phase Complete
- [x] Live preview started before the first SVG and kept available at the reported URL
- [x] text_fit.py page-object batch run before drawing each non-trivial page (pre-clears width + vertical + collision; hand-eyeballing the geometry is the documented miss)
- [x] Milestone gate run (page 1 + every 4 pages via --pages block; errors fixed and text-geometry warnings dispositioned per block)
- [x] All SVGs generated to svg_output/
- [x] svg_quality_checker.py passed (0 errors)
- [x] Text-geometry warnings dispositioned one by one (fix or stated intent)
- [x] Selective pixel check run on flagged + hero/scrim pages (silently skipped when playwright or the preview server is absent)
- [x] Structured-template PPTX warnings dispositioned one by one when applicable
- [x] Speaker notes generated at notes/total.md (only when requested; skipped by default)

Chart pages? If this deck contains data charts (bar / line / pie / radar / etc.), run the standalone verify-charts workflow before Step 7 to calibrate coordinates. Hand-placed chart marks drift from the data; verify-charts recomputes coordinates from the values. Skip if no chart pages.

Visual self-check (opt-in)? If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the standalone visual-review workflow before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.

---

Step 7: Post-processing & Export

🚧 GATE: Step 6 complete; all SVGs generated to svg_output/; speaker notes notes/total.md generated when the user requested them (default no-notes path has no notes/ and satisfies this gate).

🚧 Image readiness GATE (when Step 5 left ai rows in Needs-Manual): every expected file must exist at project/images/<filename> before running 7.1.

Failure recovery: if a Step 7 command fails, fix the owning source artifact and resume from the failed sub-step per workflows/failure-recovery.md. Do not restart the planning session unless the owning source changed.

If files are missing: PAUSE and print the user-drop request — one line per missing image with its exact filename, purpose, and recommended dimensions/ratio (from design_spec.md §VIII) — and ask the user to place their chosen images at 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 (only when notes/total.md exists — skipped on the default no-notes path):

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) — on-demand, deferred by default. The native export (7.3) reads svg_output/ directly and does not need this step. Run it only when the user asks for the self-contained SVG previews (direct open / manual PowerPoint insertion) or a workflow explicitly needs svg_final/; skipping it on the default PPTX-only path is not an error (verify_deck.py treats an absent svg_final/ as deferred finalize):

python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>

This 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 when notes/ files exist; no-notes decks export without notes):

python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
# Output (default-flow mode):
#   exports/<title>_ver<N>.pptx                       ← native pptx (canonical output, reads svg_output/; verN auto-increments per export)
#   backup/<timestamp>/svg_output/                    ← Executor SVG source backup (always written)
# Add --native-objects to emit real editable chart/table objects instead of flattened shapes:
#   exports/<title>_ver<N>_native_charts.pptx         ← native chart/table objects (data-pptx-native markers)
# Re-export with --recorded-narration audio (generate-audio workflow) embeds per-slide narration:
#   exports/<title>_ver<N>_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. The SVG-rendered preview remains the on-demand svg_final/ artifact from Step 7.2 (generate it before relying on it — it is deferred by default); 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.

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 and brand-only projects use pptx_structure.mode: flat, omit pptx_masters / pptx_layouts / page_layouts, and author no Master/Layout/layer/placeholder metadata in SVG. Export keeps every represented object Slide-local under PowerPoint's default Master and Blank Layout.

Deck/layout template projects use pptx_structure.mode: structured, a complete pptx_masters roster, and exactly one pptx_layouts row per page in <master_key> | <layout_key> | <PowerPoint layout name> form. 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 must run restore-pptx-structure before export.

Template structured export — page_layouts records the complete input prototype per page while pptx_masters / pptx_layouts record the output structure from planning onward. 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. Non-mirror skin remains project-controlled, mirror preserves the reused visual identities, and the exporter never reads a template to add visible objects missing from svg_output/. Raw PPTX templates still route to the ppt-template-fill skill; 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.

Native table/chart objects — supported data charts and pure text-grid tables carry data-pptx-native markers by default (Executor transcribes them at draw time; see references/executor-base.md §3.2) and the markers stay dormant. Add --native-objects only when the user explicitly wants PowerPoint-editable native tables/charts and accepts that those objects may render differently across PowerPoint / Keynote / LibreOffice / WPS; marker-local details not represented by native metadata may be omitted. This is a lossy editable-first contract, not a reason to disable an otherwise supported marker. Without the flag, marked groups export through their SVG fallback children like ordinary SVG content. Imported objects that carry data-pptx-native-status are fallback-only; the quality checker and --native-objects export surface their reason as warnings rather than silently claiming editability. An imported chart with no baked preview is a different case: data-pptx-visual-status="placeholder" plus data-pptx-route-status="reconstruction-only" records a diagnostic route. Default export keeps that placeholder with a warning; when the same group has a valid active data-pptx-native="chart" payload, --native-objects may still reconstruct the editable 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-visual-status="normalized"; this is readable reconstruction, not a claim of Office pixel parity. Active imported table/chart markers also carry 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-objects fails rather than discard the edit. Legacy markers without a baseline remain native-compatible and only warn that stale detection is unavailable. 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 normalizes, while 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.

Optional custom animations (only when the user asks to tune animation order/effects/timing for specific objects):

Run the standalone customize-animations workflow. Default export applies page transitions but no per-element entrance animation; create animations.json (or pass -a auto) only when the user asks for element animation or object-level customization.

Optional recorded narration (only when the user asks for narrated/video export):

Run the standalone generate-audio workflow. The AI picks a narration backend (edge by default, or a configured cloud provider such as ElevenLabs / MiniMax / Qwen / CosyVoice for high-quality or cloned voices), asks the user once (backend + voice + rate/settings + embed-or-not, all with recommended values), then executes notes_to_audio.py and (if chosen) re-exports the PPTX with --recorded-narration audio.

Do NOT call notes_to_audio.py directly without going through the workflow — --voice / --voice-id is required and the workflow produces the locale/provider-aware recommendation that makes the choice meaningful.

Full effect list, anchor logic, and limits: 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/.

Final deck verification (mandatory — before declaring the deck done): one command re-checks stage parity/freshness (stale finalize or export), native PPTX integrity (zip, per-slide editable DrawingML, page count), the planning artifacts, and SVG quality; when OfficeCLI is installed it also validates OpenXML and renders one whole-deck contact sheet of the exported PPTX to <project_path>/_pptx_render/<stem>-grid.png (auto-skips when OfficeCLI is absent):

python3 ${SKILL_DIR}/scripts/verify_deck.py <project_path>

Exit 0 is required before completion is reported. The contact-sheet render is the only part --no-render turns off; every other check runs either way.

Iteration speed path: while re-exporting repeatedly (fixing pages, re-running Step 7.2–7.3), add --no-render to skip the render — it costs roughly 7–13s per deck. Drop the flag for the final run before hand-off, so the deck is never delivered without one look at the converted pixels.

Lightweight exported-PPTX visual sanity check (DEFAULT — one pass, not deep verification): Read the _pptx_render/<stem>-grid.png the command above prints, once, for obvious text overflow/collision, missing assets, or font substitution. Open only visibly suspect pages at full resolution; do not render and compare every page individually by default. When OfficeCLI is available, its issues --json scan MAY run alongside as a non-blocking suspicion signal.

• Contact sheet clean and no suspicion signal: deliver immediately and state that the lightweight visual sanity check passed; the full verify-pptx-export workflow was not run.
• Visible or reported suspicion, or no usable exported-PPTX render: identify the page/finding and recommend verify-pptx-export to the user. Do not auto-enter that workflow or start its iterative repair loop. Run it only after explicit user approval.
• This one-pass check does not change the standalone workflow's explicit-request-only boundary.

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 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 Step 1 to start it. If the service is already running, just point them at the URL — do not restart.

---

Role Switching Protocol

Read the role's reference file before acting in that role.

---

Reference Resources

Resource	Path
Shared technical constraints	references/shared-standards.md
Strategist image system (conditional load)	references/strategist-images.md
Native object conversion contracts (conditional load)	references/native-objects.md
Structured template route standards (conditional load)	references/structured-templates.md
Speaker-notes framework (opt-in load)	references/speaker-notes.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

• Local preview: python3 -m http.server -d <project_path>/svg_final 8000 (run Step 7.2 first — svg_final/ is deferred by default)
• Troubleshooting: on generation issues (layout overflow, export errors, blank images, etc.), check docs/faq.md for known solutions