Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

refactor(generate): streamline planning and restore visual defaults

hugohe380ae59bf2a80
diff --git a/AGENTS.md b/AGENTS.md
index ee8e79b8..d9c6ec4f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,14 +21,14 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate
## Execution Requirements
- For any `brand`, `style`, `layout`, or `deck` workspace creation from PPTX/SVG, images/PDFs, documents/websites, brand assets, direct text, or mixed references, enter [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md); it keeps the fixed Create Template name and dispatches exactly one of [`create-brand`](skills/ppt-master/workflows/create-template/create-brand.md), [`create-style`](skills/ppt-master/workflows/create-template/create-style.md), [`create-layout`](skills/ppt-master/workflows/create-template/create-layout.md), or [`create-deck`](skills/ppt-master/workflows/create-template/create-deck.md).
-- Always-on SVG constraints live in [`skills/ppt-master/references/shared-standards-core.md`](skills/ppt-master/references/shared-standards-core.md). Load [`svg-effects.md`](skills/ppt-master/references/svg-effects.md), [`native-data-interface.md`](skills/ppt-master/references/native-data-interface.md), and [`pptx-structure-interface.md`](skills/ppt-master/references/pptx-structure-interface.md) only when their documented execution triggers apply.
+- Always-on SVG constraints and shared visual-quality defaults live in [`skills/ppt-master/references/shared-standards-core.md`](skills/ppt-master/references/shared-standards-core.md). Default and Quick Generate always load [`svg-effects.md`](skills/ppt-master/references/svg-effects.md); other routes load it, [`native-data-interface.md`](skills/ppt-master/references/native-data-interface.md), and [`pptx-structure-interface.md`](skills/ppt-master/references/pptx-structure-interface.md) only when their documented execution triggers apply.
- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).
- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).
## Required Conventions
- **Repo-wide style rules** — when editing prompt files under [`skills/ppt-master/references/`](skills/ppt-master/references/), Python under [`skills/ppt-master/scripts/`](skills/ppt-master/scripts/), or any other code/prose in the repo, follow the matching style rule in [`docs/rules/`](docs/rules/).
-- **Prompt decision ownership** — follow [`docs/rules/prompt-style.md`](docs/rules/prompt-style.md) §4.1. Default Strategist prepares project-local resources and Executor realizes them; Quick's current agent decides and prepares before SVG authoring. This is not downstream acquisition. Every project icon is prepared material; `icons.inventory` records only the default plan's bundled selection.
+- **Prompt decision ownership** — follow [`docs/rules/prompt-style.md`](docs/rules/prompt-style.md) §4.1. Default Strategist prepares project-local resources and Executor realizes them; Quick's current agent decides and prepares before SVG authoring. This is not downstream acquisition. Every project icon is prepared material; `icons.inventory` indexes the default plan's curated bundled pool, not page usage or an execution whitelist.
- **Markdown language consistency** — Markdown files under `skills/ppt-master/workflows/`, `skills/ppt-master/references/`, and `docs/` are currently single-language per directory. New files mirror the language of their siblings; do not mix English scaffolding with Chinese paragraphs (or vice versa) inside one file. Chat replies are unaffected.
## Compatibility Boundary
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index 4c29ee5d..d5d86f1f 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -43,7 +43,7 @@ You: Generate narration for this deck and re-export with audio embedded.
You: Add Japanese voice narration; pick a calm female voice.
```
-The Generate route also runs this stage when Stage 3 resolves effective
+The Generate route also runs this stage when final Stage 2 resolves effective
Narration Audio to enabled. A later explicit request still wins over the
proactive default. The AI handles the rest.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 50d14f81..84105811 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -46,7 +46,7 @@ A created template lives in one of two places:
| **Registered in the skill library** | `skills/ppt-master/templates/<kind>/<id>/` | Portable workspace plus global registration, so it appears when you ask "what templates are available?" |
| **Under projects** | `projects/<name>/` | The same portable workspace without global registration |
-Use a registered result from its kind dropdown in Step 3. To offer another result, supply its exact **workspace-root path** in chat: an unregistered root appears in the specified-root dropdown, while an exact registered match resolves back to its kind dropdown. Step 3 resolves `templates/design_spec.md`; for directory-shape compatibility it also accepts a legacy-flat Brand/Layout/Deck root that satisfies its current kind contract. Layout/Deck additionally require current structured SVGs; Style has no flat form. A create-template run may hand its exact validated workspace root directly to Step 3 in the same conversation. Both cases require an exact selection; a bare template name never triggers. The complete workspace can be copied or migrated between the library and `projects/` without restructuring it; only library registration changes.
+When you explicitly ask to browse or select a template, use a registered result from its kind dropdown in Step 3. To offer another result, supply its exact **workspace-root path** in chat: an unregistered root appears in the specified-root dropdown, while an exact registered match resolves back to its kind dropdown. Either action triggers Step 3; ordinary free design skips it. Step 3 resolves `templates/design_spec.md`; for directory-shape compatibility it also accepts a legacy-flat Brand/Layout/Deck root that satisfies its current kind contract. Layout/Deck additionally require current structured SVGs; Style has no flat form. A create-template run may hand its exact validated workspace root directly to Step 3 in the same conversation. Both cases require an exact selection; a bare template name never triggers. The complete workspace can be copied or migrated between the library and `projects/` without restructuring it; only library registration changes.
```
You: Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/
@@ -61,20 +61,20 @@ Full guide → [Templates Guide](./templates-guide.md)
The whole loop is three steps. Install first — you only need Python; see [Quick Start](../README.md#quick-start).
1. **Drop your source material** into `projects/` — a PDF, DOCX, Markdown file, a URL, or just text you'll paste.
-2. **Tell the AI in chat** what to turn into a deck. Step 3 then lets you choose free design or combine registered templates; add an exact unregistered template root in chat when you want it offered in the specified-root dropdown:
+2. **Tell the AI in chat** what to turn into a deck. Ordinary requests use free design and go directly to Stage 1. Ask to browse/select templates or add an exact workspace root only when you want the conditional Step-3 selector:
```
You: Make a deck from projects/q3-report/sources/report.pdf
You: Turn this text into a deck: <paste your text>
```
3. **Get an editable `.pptx`** at `exports/<name>_<timestamp>.pptx` — real DrawingML shapes, text boxes, and charts you can click and edit in PowerPoint, Keynote, WPS, or LibreOffice.
-Before generation, Step 3 first confirms free design or the template combination. Stage 1 then independently confirms the communication contract and canvas/format; Stage 2 confirms page count, the visual system, and template application when active. From there the AI handles content analysis, layout, image acquisition, SVG generation, and export — the core loop everything else builds on. To skip interactive confirmation, see [Quick mode](#quick-mode) below.
+Before generation, Stage 1 confirms the communication contract and canvas/format; final Stage 2 confirms page count, the visual system, any active template application, and production choices. A template selector precedes Stage 1 only when explicitly triggered. From there the AI handles content analysis, layout, image acquisition, SVG generation, and export — the core loop everything else builds on. To skip interactive confirmation, see [Quick mode](#quick-mode) below.
---
## Quick mode
-The default flow runs the Step-3 choice and staged design confirmation first. To skip that interaction, explicitly ask for **quick generation**:
+The default flow runs its two-stage design confirmation, plus Step 3 only when template selection is explicitly triggered. To skip that interaction, explicitly ask for **quick generation**:
```
You: Quickly generate a deck from sources/report.pdf — no need to confirm with me
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.md
index 727b303c..7b21c63c 100644
--- a/docs/rules/prompt-style.md
+++ b/docs/rules/prompt-style.md
@@ -102,12 +102,12 @@ Constraint strength and decision ownership are independent. Preserve this chain
| Layer | Owns |
|---|---|
| User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative |
-| Strategist / plan + preparation | Assess material sufficiency; trigger permitted fact research; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution |
-| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. For icons, the complete `<project>/icons/` pool is prepared material and `icons.inventory` is not a whitelist; sparse local font/color garnish is allowed only while non-structural and non-recurring |
+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted fact research; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages |
+| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring |
**Preparation timing**: In the default pipeline, fact research required for planning may run before final confirmation. AI / web / slice acquisition runs only from the completed `design_spec.md §VIII` and `spec_lock.md`, after final confirmation and before Executor. Image_Generator, Image_Searcher, and icon-sync tooling execute Strategist-owned preparation; they are not independent decision owners.
-**Hard rule — default pipeline**: downstream freedom exists only in dimensions left open upstream, including fields explicitly labeled `suggestion` or Reference. A named binding outcome retains identity; a broad semantic request or expression recommendation permits in-class choice. Once the plan resolves a binding choice, execution cannot reopen or substitute it. Executor never searches, generates, downloads, syncs, invents, or replaces a resource; missing material returns to Strategist-owned preparation or upstream repair.
+**Hard rule — default pipeline**: downstream freedom exists only in dimensions left open upstream, including fields explicitly labeled `suggestion` or Reference. A named binding outcome retains identity; a broad semantic request or expression recommendation permits in-class choice. Once the plan resolves a binding choice, execution cannot reopen or substitute it. For icons, library/stroke and the prepared-project boundary bind, while per-page choice within the prepared pool is realization. Executor never searches, generates, downloads, syncs, invents, or replaces a resource; missing material returns to Strategist-owned preparation or upstream repair.
**Explicit Quick Generate exception**: [`quick-generate`](../../skills/ppt-master/workflows/profiles/quick-generate.md) removes the separate Strategist/confirmation handoff. The current main agent therefore owns both its active-context decisions and the preparation of project-local sources, images, icons, formulas, and provenance before it begins SVG realization. This exception does not move acquisition into a default-pipeline Executor and does not permit resource reselection while a page is being realized. Explicit user facts, choices, exclusions, and permissions remain upstream authority; unspecified routine choices are resolved automatically without a confirmation stop.
diff --git a/docs/technical-design.md b/docs/technical-design.md
index e5147b07..25c62425 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -59,12 +59,12 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
├── If canonical same-stem Markdown is absent, run ppt_to_md.py against that archived PPTX
└── Content-type files in sources/ become the content contract
↓
-[Template Selection & Installation (Step 3)] — default UI choice before Stage 1
- Choose free design, indexed Brand/Style/Layout/Deck library entries, or exact explicit workspace roots; indexes are the complete library source and directories are never scanned
- Confirmed workspaces are validated/fused into project-local templates/images/icons before Strategist starts
+[Template Selection & Installation (Step 3, conditional)] — only for an explicit browse/selection request, an exact workspace root, or the current Create Template handoff
+ Ordinary free-design runs skip this phase and open Stage 1 directly without reading template indexes
+ Triggered runs may confirm free design or choose indexed Brand/Style/Layout/Deck entries or exact explicit workspace roots; confirmed workspaces are validated/fused into project-local templates/images/icons
Raw PPTX template requests route to template-fill; reusable SVG templates are created by create-template first
↓
-[Strategist] - three-stage Strategist confirmation stage & Design Specifications → design_spec.md + spec_lock.md
+[Strategist] - Stage 1 communication confirmation + final Stage 2 solution/production confirmation → design_spec.md + spec_lock.md
↓
[Image Acquisition] (when any resource row needs AI generation, web search, or slicing)
↓
@@ -127,6 +127,8 @@ optional native-object and narration flags.
For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority, but SVG here means project-canonical SVG accepted by the project contract—not any SVG a browser can render. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. In the default pipeline, templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; `quick-generate` instead uses active-context decisions and explicit SVG values. The exporter never uses planning inputs as a second visual layer that fills in missing page content.
+The always-loaded core also owns the fallback visual-quality and numeric leading defaults. Explicit user, template / brand, and locked-style requirements override compatible aesthetic defaults; when those authorities are silent, hierarchy, typography, alignment, negative space, purposeful assets, and the core's density-based leading ranges still apply. Default and Quick Generate always load `svg-effects.md` and run its Visual Job Router before completing a page. None of these aesthetic choices can override a technical Required / Forbidden boundary.
+
Minimal semantic markers do not weaken that closure. Free-design, brand-only, `quick-generate`, and `template_reuse_scope: style` pages use flat Slide-local ownership: every represented object stays on the Slide and no Master/Layout identity, layer, or placeholder metadata is authored. Default export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock; lockless `quick-generate` uses converter-default theme scaffolding. Neither promotes Slide content. Only `template_reuse_scope: mirror|layout` uses the structured route, where every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. A semantic-legacy template package is not upgraded in place or accepted as a structured Step 3 input: create a new workspace through `create-template`, using a native PPTX's still-present package facts or an old SVG's visuals only as reference, then author new pages through the AI-derived application route. A flat project is intentionally unmapped, not legacy. Export never infers, repairs, or migrates Master/Layout structure or placeholders.
| Domain | Authority |
@@ -167,7 +169,8 @@ Use this table before reasoning about implementation details. Most failed runs s
| Existing PPTX, preserve page count/order/wording 1:1, improve layout | Generate PPTX + `beautify-pptx` profile | regenerate through SVG; content and pagination are locked |
| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Enhance Native PPTX (`native-enhance-pptx`) | direct OOXML patch; no design regeneration |
| User wants a reusable template workspace from one or more PPTX/SVG files, images/PDFs, documents/websites, brand assets, direct text, or a mixed reference bundle | Create Template (`create-template`) | the fixed entry reads every applicable evidence channel, dispatches one Create Brand, Create Style, Create Layout, or Create Deck child workflow, then returns a workspace root for Generate Step 3; structured children may export a review PPTX |
-| User selects an indexed library template or supplies an exact current-contract workspace root | Generate PPTX Step 3 | The independent pre-Stage-1 phase confirms free design or exact Brand/Style/Layout/Deck roots, then validates/fuses selected workspaces into the project; only compatible legacy-flat Brand/Layout/Deck roots may resolve direct `design_spec.md` |
+| No explicit template browse/selection request, exact workspace root, or current Create Template handoff | Generate PPTX with free design | skip Step 3 and open Stage 1 directly without reading template indexes or creating template-selection artifacts |
+| User explicitly requests template discovery/selection, supplies an exact current-contract workspace root, or continues from the current Create Template handoff | Generate PPTX Step 3 | the conditional pre-Stage-1 phase confirms free design or exact Brand/Style/Layout/Deck roots, then validates/fuses selected workspaces into the project; only compatible legacy-flat Brand/Layout/Deck roots may resolve direct `design_spec.md` |
| User asks to tune object-level animation order/effect/timing | Generate PPTX + `customize-animations` stage | optional export policy via `animations.json` |
| User asks to preview, select, annotate, or re-export browser edits | Generate PPTX + `live-preview` stage | annotations apply only at defined handoff points |
@@ -364,17 +367,19 @@ The architectural choice worth flagging: **viewBox is in pixels, not absolute un
## Template System & Optional Path
-Templates are **opt-in, not inferred**. Before Strategist Stage 1, the default UI
-opens an independent Step-3 choice: free design, four registered single-select
-dropdowns (Brand / Style / Layout / Deck), and one single-select dropdown for
-exact roots supplied for the run. Free design remains the
-content-derived path; the system never chooses a template from topic similarity.
+Templates are **opt-in, not inferred**. An ordinary free-design run skips Step 3,
+does not read template indexes or create template-selection artifacts, and opens
+Strategist Stage 1 directly. Step 3 appears only for an explicit template browse
+or selection request, an exact workspace root supplied for the run, or the
+current Create Template handoff. The triggered UI lists registered Brand / Style /
+Layout / Deck entries and exact supplied roots; the system never chooses a
+template from topic similarity.
**Why default to free design.** Templates are floors that easily become ceilings: they lock the deck into the template's visual idioms regardless of how the content actually wants to be presented. Free-design layouts derive structure from the source content rather than imposing it from a fixed grammar, so the visual rhythm tracks the content rather than fighting it. Constrained mode is genuinely better in narrow cases (brand-locked decks, strongly-typed scenarios like academic defense or government report), so it stays available — but the AI doesn't proactively reach for it; the user does.
**Exact selection, not semantic matching.** A bare name like
`presentation_core`, a brand mention, or a style phrase such as "McKinsey
-style" is never fuzzy-matched to a directory. The default page lists registered
+style" is never fuzzy-matched to a directory. The triggered page lists registered
Brand/Style/Layout/Deck entries only from their four `*_index.json` files;
chat discovery reads the same indexes and returns exact roots. Explicit paths
remain valid, and an exact path matching a registered canonical root may be
@@ -404,7 +409,7 @@ not carry asset or review payloads. Existing project scaffolding is not Style
input.
`<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or
-another exact workspace root such as `projects/<name>/`. Step 3 validates,
+another exact workspace root such as `projects/<name>/`. When triggered, Step 3 validates,
fuses, and installs selected inputs into the current project's `templates/`,
`images/`, and `icons/`; it never copies `exports/`. Strategist and later roles
read only that project-local copy when template-aware planning begins after
@@ -447,11 +452,12 @@ PPT Master keeps deck-state roles—Strategist, Image_Generator, and Executor—
**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode: it may not reselect upstream decisions or omit required attributes, but it still owns geometry, composition, hierarchy, and visual treatment inside implementation dimensions the Design Spec leaves open. Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.
-**The independent Step-3 template choice closes before the Strategist confirmation stage.** It is not Stage 1: the default UI first confirms free design or exact indexed/explicit workspaces and runs the common installation/fusion stage. Stage 1 then confirms an open communication contract and canvas using only the current request, source facts, conversation constraints, and project initialization; it must not read the selection, installed template content, or template canvas. Strategist uses one dependency-ordered three-stage gate. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Stage 2 is authored once from that contract and confirms the complete deck solution: reading mode, narrative mode, page count, coordinated visual system, image sources, and generated-image rendering. Only after Stage 1 is confirmed, when a template is installed, does Strategist read the project-local workspace and current content, derive **how to apply it**, and expose that plan as editable `template_application` prose; Stage 2 never reselects a template, and the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. Stage 3 is authored once and contains production mechanics only: conditional AI acquisition, formula policy, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Those three values are fallback policies, not capability bans: the latest explicit user instruction wins, then Stage 3, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. The compatibility key `delivery_purpose` means reading mode. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.
+**A triggered Step-3 template choice closes before the Strategist confirmation stage.** Ordinary free-design runs skip Step 3 and open Stage 1 directly. When Step 3 is triggered, the UI confirms free design or exact indexed/explicit workspaces and completes installation/fusion before Stage 1. Stage 1 then confirms an open communication contract and canvas using only the current request, source facts, conversation constraints, and project initialization; it must not read the selection, installed template content, or template canvas. Strategist uses one dependency-ordered two-stage gate. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Final Stage 2 is authored once from that contract and confirms both the complete deck solution and its production mechanics: reading mode, narrative mode, page count, coordinated visual system, image sources, generated-image rendering, conditional AI acquisition, formula policy, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Only after Stage 1 is confirmed, when a template is installed, does Strategist read the project-local workspace and current content, derive **how to apply it**, and expose that plan as editable `template_application` prose; Stage 2 never reselects a template, and the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. The three proactive values are fallback policies, not capability bans: the latest explicit user instruction wins, then final Stage 2, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.
-The three Stage 3 proactive values remain independent raw evidence. In
-particular, enabling narration may enable the effective Speaker Notes outcome
-in the Design Spec, but it never rewrites the raw speaker-notes choice.
+The three proactive values confirmed in final Stage 2 remain independent raw
+evidence. In particular, enabling narration may enable the effective Speaker
+Notes outcome in the Design Spec, but it never rewrites the raw speaker-notes
+choice.
**Image analysis is metadata-first, with a narrow visual fallback.** When images exist, `analyze_images.py` supplies the regenerated measured facts in `analysis/image_analysis.csv`; the CSV is a view over the live `images/` folder, not a durable cache. In the default pipeline, Strategist first resolves supplied images from source placement and nearby prose, captions / alt text / titles, filenames, user notes, existing resource records, and that metadata. It may inspect one specific image only when a material ambiguity remains about selection, factual identity, page role, crop safety, or focal placement—never as a bulk inventory scan. The answer is written into Design Spec §VIII, after which Executor uses the plan and measured geometry without reopening source pixels for semantic discovery. In `quick-generate`, the current agent applies the same bounded analysis while automatically preparing the resource roster in active context; no Design Spec projection is written. User images, extracted images, web images, AI outputs, formulas, and sliced elements still converge into the same measured fact table.
@@ -503,8 +509,8 @@ Strategist and confirmation layer; it does not remove preparation.
| Restaurant | PPT Master | Authority |
|---|---|---|
| Customer and initial ingredients | User confirmation and supplied sources/assets | Defines facts, intent, exclusions, acquisition permissions, and how specific the requested outcome is |
-| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart-reference/template-layout keys, fonts, palette anchors, icons, and crop boundaries; records optional capability/expression recommendations; readies the complete project-local inventory before execution |
-| Cook | Executor | Uses only prepared project-local assets and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients; may adapt fields explicitly labeled as suggestions or References |
+| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart-reference/template-layout keys, fonts, palette anchors, icon system and curated pool, and crop boundaries; records optional capability/expression recommendations; readies the complete project-local inventory before execution |
+| Cook | Executor | Uses only prepared project-local assets and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients; chooses suitable prepared icons per page and may adapt fields explicitly labeled as suggestions or References |
**Quick generation collapses planning into the current agent.** Source conversion,
factual-gap research, and resource preparation still run when needed. The agent
@@ -514,9 +520,9 @@ icons, and formulas with their required manifests or provenance records, and
then hand-authors SVG. It does not invoke Strategist, Confirm UI,
`design_spec.md`, or `spec_lock.md`.
-**Default preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.
+**Default preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates a curated project icon pool while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.
-**Prepared project-local assets are the boundary.** In the default pipeline, images and other declared resources remain available only when Strategist has selected them, recorded them in the planning artifacts, and made their project paths resolvable or explicitly `Needs-Manual`. Icons are prepared when their SVG files exist under `<project>/icons/`; `spec_lock.icons.inventory` records the Strategist's planned bundled selection but is not an exhaustive execution whitelist. In quick generation, the active-context resource roster and its project-local files/manifests replace that planning projection; the current agent may acquire and prepare those resources before SVG authoring. Files elsewhere on disk are not authorized. Missing material returns to the owning preparation step; SVG authoring never silently substitutes it.
+**Prepared project-local assets are the boundary.** In the default pipeline, images and other declared resources remain available only when Strategist has selected them, recorded them in the planning artifacts, and made their project paths resolvable or explicitly `Needs-Manual`. Icons are prepared when their SVG files exist under `<project>/icons/`; `spec_lock.icons.inventory` indexes the Strategist's curated synced bundled pool but neither assigns page usage nor exhaustively whitelists execution. Executor chooses among prepared icons per page. In quick generation, the active-context resource roster and its project-local files/manifests replace that planning projection; the current agent may acquire and prepare those resources before SVG authoring. Files elsewhere on disk are not authorized. Missing material returns to the owning preparation step; SVG authoring never silently substitutes it.
**Specificity controls freedom.** “Make Mapo tofu” fixes the result's identity: technique and presentation may vary, but tomato-and-eggs or tofu soup is a substitution. “Make a tofu dish” leaves an in-class choice. In the default pipeline, Strategist may resolve that choice; if the Design Spec deliberately leaves a dimension broad, Executor may realize it within that envelope. Once the Design Spec names a binding choice, execution cannot reopen it. In quick generation, the current agent resolves the equivalent choice in active context and keeps it stable while authoring. Fields explicitly labeled as suggestions or References—including a preferred page-local image pattern—remain expression guidance that may be adapted without changing content, resources, identity, or explicit constraints.
@@ -802,7 +808,7 @@ Supporting files stay separate only to keep route contracts focused and load opt
|---|---|---|
| Generation profiles | `beautify-pptx`, `quick-generate` | Generate PPTX with either wording/page invariants or the explicit direct SVG-to-PPTX short circuit |
| Template child workflows | `create-brand`, `create-style`, `create-layout`, `create-deck` | Create Template dispatches exactly one for identity-only, roster-free direction/method, brand-neutral/application-neutral structure, or a recurring application with integrated identity/structure |
-| Template-input stage | `apply-template-workspace` | Generate PPTX Step 3; runs after the independent indexed/explicit selection confirms at least one workspace |
+| Template-input stage | `apply-template-workspace` | Conditional Generate PPTX Step 3; runs only after an explicit browse/selection request, exact root, or current Create Template handoff confirms at least one workspace |
| Generation stages | `topic-research`, `resume-execute`, `refine-spec`, `verify-charts`, `visual-review`, `live-preview`, `customize-animations` | Generate PPTX at their defined intake, planning, editing, quality, or post-processing points |
| Shared stage | `generate-audio` | Generate PPTX post-processing or Enhance Native PPTX narration integration |
| Governance | `failure-recovery` | Global stop/continue policy for all four routes; concrete recovery matrix and resume pointers for Generate PPTX |
diff --git a/docs/templates-architecture.md b/docs/templates-architecture.md
index 8bfb740b..7765cb89 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -206,7 +206,7 @@ canvas, page count/order, Master/Layout/placeholder structure, or page-specific
resources. Its palette and typography values are overrideable fallbacks:
user-confirmed choices and Brand/Deck identity values take precedence. Review
Focus cannot activate visual review. `kind: style` identifies this reusable
-package; it is distinct from the Stage-2 `visual_style` choice and from the
+package; it is distinct from the final Stage-2 `visual_style` choice and from the
internal `template_reuse_scope: style` flat-export value.
### Layout schema
@@ -377,17 +377,17 @@ These indexes cover library scope only. A project-root workspace is intentionall
### Segment ownership (implicit dispatch)
-When the user confirms registered and/or specified workspace roots, Step 3
+When explicitly triggered Step 3 confirms registered and/or specified workspace roots, it
parses every root's real `kind`, resolves each template segment independently,
and writes one `<project>/templates/design_spec.md`. `library` / `explicit`
records discovery provenance only and never changes ownership:
| Segment | Starting owner |
|---|---|
-| Identity | Brand, otherwise Deck, otherwise unresolved until Stage 2; Style supplies fallback candidates only |
-| Direction / method | Style, otherwise unresolved until Stage 2; actual Deck prototypes and Signature facts inform compatibility only |
-| Structure | Compatible Layout, otherwise Deck, otherwise unresolved/free design until Stage 2 |
-| Reusable application context | Deck only; retained for Stage-2 comparison, never used as the current project's application contract |
+| Identity | Brand, otherwise Deck, otherwise unresolved until final Stage 2; Style supplies fallback candidates only |
+| Direction / method | Style, otherwise unresolved until final Stage 2; actual Deck prototypes and Signature facts inform compatibility only |
+| Structure | Compatible Layout, otherwise Deck, otherwise unresolved/free design until final Stage 2 |
+| Reusable application context | Deck only; retained for final Stage-2 comparison, never used as the current project's application contract |
Current user instructions and final confirmation override every starting
owner. Brand identity remains authoritative over Style palette/type fallbacks.
@@ -401,7 +401,7 @@ Before combining Style with Layout/Deck, verify that its communication method
and composition expectations can be realized by that reusable context and
structure. On mismatch, surface the conflicting template segments; do not
silently mix fields or retain a promise that the selected structure cannot
-satisfy. Current-project fit begins only in Stage 2 after Stage 1 is confirmed.
+satisfy. Current-project fit begins only in final Stage 2 after Stage 1 is confirmed.
### Whole-segment replacement (default granularity)
@@ -431,7 +431,7 @@ Rules:
- `style × 2`, `layout × 2`, `deck × 2`, `brand × 2` handled the same way
- Max two of any one kind (more than that — ask the user to converge in chat first)
-The default page already narrows this space: Brand/Style/Layout/Deck each have
+The explicitly triggered template page already narrows this space: Brand/Style/Layout/Deck each have
one registered single-select dropdown, and one additional specified-root
dropdown may contribute a second workspace of its parsed kind. The server
enforces those limits; chat-based composition retains the general maximum of
@@ -456,7 +456,7 @@ This lets both AI and humans trace which segment came from where.
## 5. Relationship with Generate PPTX Step 3
-**Trigger rule stays exact-choice-based** — use a registered Step-3 dropdown choice or an explicit workspace-root path (see [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option)); bare names never trigger. Step 3 first resolves `<workspace>/templates/design_spec.md`; for directory-shape compatibility, it also accepts a legacy-flat Brand/Layout/Deck root containing `<workspace>/design_spec.md` when the package satisfies its current kind contract. Layout/Deck additionally require current structured SVGs; Style has no flat form. Packages using legacy semantics such as `native_structure_mode: template`, missing Master identity, direct atomic placeholders, or distillation-era markers are rejected; `create-template` must produce a new workspace before generation continues. The only narrow handoff exception is a `create-template` run in the current conversation: after validation, it may pass its exact workspace root directly into Step 3. The `kind` field decides **how AI handles the path after triggering**:
+**Step 3 is conditional.** Ordinary Default Generate uses free design, reads no template index, opens no template page, and proceeds directly to Stage 1. Step 3 runs only after an explicit request to browse/select templates, an exact workspace-root path, or an exact validated root handed off by Create Template in the current conversation (see [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)). A bare template/brand name or style phrase never triggers it. Once triggered, Step 3 first resolves `<workspace>/templates/design_spec.md`; for directory-shape compatibility, it also accepts a legacy-flat Brand/Layout/Deck root containing `<workspace>/design_spec.md` when the package satisfies its current kind contract. Layout/Deck additionally require current structured SVGs; Style has no flat form. Packages using legacy semantics such as `native_structure_mode: template`, missing Master identity, direct atomic placeholders, or distillation-era markers are rejected; `create-template` must produce a new workspace before generation continues. The `kind` field decides **how AI handles the path after triggering**:
| User path's `kind` | Step 3 action (per-kind branch) |
|---|---|
@@ -471,7 +471,7 @@ Bitmaps share the workspace `images/` pool and template SVGs reference them thro
### Strategist confirmation stage behavior per kind
-Installing a template does not narrow away the communication question. Stage 1 always confirms the same open communication contract independently of the template, using only the current request, source facts, conversation constraints, and project initialization; even template canvas is excluded. Only after Stage 1 closes does Stage 2 inspect the installed state. Brand supplies identity constraints while structure stays free; Style supplies method and visual-default seeds while remaining flat; Layout exposes structural capability; Deck contributes descriptive reusable application context for comparison, not the current project's contract. For Style-only use, Strategist does not look for prototypes and deterministically records `template_reuse_scope: style` with flat structure. For Layout/Deck, it inspects the actual prototypes and current content, then authors one page/prototype plan and records `mirror`, `layout`, or `style` only as internal exporter values. A mirror-authored workspace therefore enables literal reuse but never forces it. The Confirm UI exposes no template-mode fields. Planning semantics live in `references/strategist.md` and `references/strategist-template.md`; `templates/schemas/spec_lock.schema.json` owns the machine structure.
+Installing a template does not narrow away the communication question. Stage 1 always confirms the same open communication contract independently of the template, using only the current request, source facts, conversation constraints, and project initialization; even template canvas is excluded. Only after Stage 1 closes does final Stage 2 inspect the installed state and confirm the complete solution and production plan. Brand supplies identity constraints while structure stays free; Style supplies method and visual-default seeds while remaining flat; Layout exposes structural capability; Deck contributes descriptive reusable application context for comparison, not the current project's contract. For Style-only use, Strategist does not look for prototypes and deterministically records `template_reuse_scope: style` with flat structure. For Layout/Deck, it inspects the actual prototypes and current content, then authors one page/prototype plan and records `mirror`, `layout`, or `style` only as internal exporter values. A mirror-authored workspace therefore enables literal reuse but never forces it. The Confirm UI exposes no template-mode fields. Planning semantics live in `references/strategist.md` and `references/strategist-template.md`; `templates/schemas/spec_lock.schema.json` owns the machine structure.
---
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index 1c31d0f1..e0e9321e 100644
--- a/docs/templates-guide.md
+++ b/docs/templates-guide.md
@@ -19,7 +19,7 @@ Choose the route by the artifact you already have and the result you want:
| Starting point and goal | Route | Copy-ready request |
|---|---|---|
| A raw `.pptx`; keep its existing slide shells and replace content | **Fill Native PPTX** | `Fill projects/source/template.pptx with projects/source/content.md.` |
-| A reusable Brand/Style/Layout/Deck workspace; generate a fresh deck | **Generate PPTX → Step-3 template selector** | `Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/.` |
+| A reusable Brand/Style/Layout/Deck workspace; generate a fresh deck | **Generate PPTX → conditional Step-3 template selector** | `Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/.` |
| A PPTX, SVG set, brand guide, website, images, or mixed references; first build a reusable system | **Create Template → Generate PPTX** | `Use /create-template to create a reusable Deck workspace from projects/brand/our_deck.pptx.` |
Do not pass a raw `.pptx` as a Generate PPTX template path. Fill it directly when you want its existing pages, or run Create Template first when you want a reusable system.
@@ -29,7 +29,7 @@ Choose the workspace kind by what must be reused:
| Kind | Reuses | Native PowerPoint result |
|---|---|---|
| **Brand** | Color, typography, logo, voice, icon style | Identity constraints only. Generated pages remain Slide-local under one clean project Master and Blank Layout. |
-| **Style** | Communication method, open page-role vocabulary, evidence/data rules, visual defaults, image/icon direction, and advisory review focus | Flat Slide-local pages. Style values seed Stage 2 but do not become brand identity or reusable Layouts. |
+| **Style** | Communication method, open page-role vocabulary, evidence/data rules, visual defaults, image/icon direction, and advisory review focus | Flat Slide-local pages. Style values seed final Stage 2 but do not become brand identity or reusable Layouts. |
| **Layout** | Brand-neutral page grammar, Master/Layout identities, semantic text roles, slots, and layout roster | A structured deck with reusable native Masters, named Layouts, and placeholders; identity, reading-mode typography, and communication application are resolved separately. |
| **Deck** | A recurring presentation family: descriptive application context, identity, page structure, and actual prototypes | A deck whose page/prototype application plan is derived by AI from the template and current content. |
@@ -43,8 +43,8 @@ stay separate.
The two rules that prevent most mistakes:
-1. In the default page, choose free design or an exact registered workspace from [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation). In chat, use the exact workspace root—not its `templates/` subdirectory or a bare template name.
-2. An explicit path and a Create Template handoff remain valid. Step 3 confirms and installs every selected workspace before Stage 1; template-aware reading begins in Stage 2 from the project-local copy.
+1. Ordinary Default Generate has no template phase: it reads no template index, opens no template page, and goes directly to Stage 1 with free design.
+2. [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation) runs only when you explicitly ask to browse/select templates, provide an exact workspace root, or receive the exact validated root from Create Template in the current conversation. It installs the selection before Stage 1; template-aware reading begins in final Stage 2 from the project-local copy.
---
@@ -52,7 +52,7 @@ The two rules that prevent most mistakes:
### How to trigger
-The default confirmation page opens an independent **Step-3 template-selection phase before Stage 1**. It offers free design, registered Brand/Style/Layout/Deck workspaces, and any exact workspace roots already supplied for the run. It does not infer a recommendation from the topic: the user makes the selection explicitly.
+Ordinary Default Generate does not enter Step 3. It uses free design and opens Stage 1 directly. An independent **Step-3 template-selection phase before Stage 1** opens only after an explicit request to browse/select templates, an exact workspace root, or a current Create Template handoff. The triggered page offers free design, registered Brand/Style/Layout/Deck workspaces, and any exact workspace roots already supplied for the run. It does not infer a recommendation from the topic: the user makes the selection explicitly.
> **Quick Generate exception:** Quick never opens that page. Up to one exact
> workspace root per kind supplied in the request is validated, installed, and
@@ -62,7 +62,7 @@ The default confirmation page opens an independent **Step-3 template-selection p
### How to enter the template flow
-On the default page, choose free design or compose templates through five compact dropdowns: one each for registered Brand, Style, Layout, and Deck workspaces, plus one for exact roots supplied for this run. Each dropdown is single-select and includes `None`; the four registered kinds can be combined, and the specified-root channel contributes at most one workspace. The registered lists come only from the four kind indexes; the workflow never scans the template directories. You can also send an exact Brand/Style/Layout/Deck workspace root in chat before Step 3. Anywhere in the sentence is fine; the path just has to be unambiguous:
+On the triggered template page, choose free design or compose templates through five compact dropdowns: one each for registered Brand, Style, Layout, and Deck workspaces, plus one for exact roots supplied for this run. Each dropdown is single-select and includes `None`; the four registered kinds can be combined, and the specified-root channel contributes at most one workspace. The registered lists come only from the four kind indexes; the workflow never scans the template directories. You can also trigger Step 3 by sending an exact Brand/Style/Layout/Deck workspace root in chat. Anywhere in the sentence is fine; the path just has to be unambiguous:
> "use this template: `skills/ppt-master/templates/layouts/presentation_core/`" ✅
> "use last deck's template: `projects/last_deck/`" ✅
@@ -70,19 +70,18 @@ On the default page, choose free design or compose templates through five compac
For every current template kind, an explicit path is the **template workspace root**. An exact root matching a registered index entry may be displayed as `library`; an unregistered root remains separately labelled `explicit`. The server parses the latter's actual frontmatter `kind`; `explicit` is provenance, not a fifth kind or a priority tier. Step 3 resolves `templates/design_spec.md`; Brand/Layout/Deck install their package-owned `templates/` plus any real `images/` and `icons/`, while Style installs only its spec and ignores unrelated project scaffolding. It never copies `exports/`. Deck/Layout workspaces additionally validate the structured SVG contract; Brand/Style validate their roster-free specs. The path may point to a built-in library workspace under `skills/ppt-master/templates/<kind>/<id>/`, a project workspace under `projects/<name>/`, or another workspace with the same routing. A Create Template run may hand its exact validated workspace root directly to Step 3 in the same conversation.
-Template selection is not part of Stage 1. After confirmation, Step 3 runs the common apply stage and installs/fuses the selected workspaces into the project's `templates/`, `images/`, and `icons/`. Only then does Strategist begin Stage 1, using only the current request, source facts, conversation constraints, and project initialization. Template selection, installed content, and template canvas cannot influence that contract. After Stage 1 is confirmed, Stage 2 compares it with the installed state; `template_application` describes **how** to use that state and never chooses **which** template to use.
+Template selection is not part of Stage 1. When triggered, Step 3 runs the common apply stage after confirmation and installs/fuses the selected workspaces into the project's `templates/`, `images/`, and `icons/`. Only then does Strategist begin Stage 1, using only the current request, source facts, conversation constraints, and project initialization. Template selection, installed content, and template canvas cannot influence that contract. After Stage 1 is confirmed, final Stage 2 compares it with the installed state; `template_application` describes **how** to use that state and never chooses **which** template to use.
> **Compatibility preflight:** Step 3 also accepts a legacy-flat Brand/Layout/Deck workspace with `design_spec.md` directly at the supplied root when it satisfies the current kind contract. Layout/Deck additionally require current structured SVGs; Style has no flat form. Former atomic-placeholder, unmapped Master/Layout, and other semantic-legacy packages are rejected; run `create-template` to create a new workspace, then generate new structured pages from that workspace. Nothing upgrades the old package in place.
### What does NOT trigger the template flow
-- **A bare template name in chat**: "use the presentation_core template" / "use the China Telecom template" does not resolve implicitly. Select the indexed entry on the page or return its exact path in chat.
-- **Style descriptions**: "McKinsey style" / "Google style" / "minimalist" / "Keynote style" remain design briefs. They never activate a workspace unless the user separately selects one.
-- **Vague intent**: "I want a template" does not authorize fuzzy lookup or directory scanning; the Step-3 choice remains open.
+- **A bare template name in chat**: "presentation_core" / "China Telecom template" does not resolve implicitly or open the template page. Explicitly ask to browse/select templates, or return its exact path in chat.
+- **Style descriptions**: "McKinsey style" / "Google style" / "minimalist" / "Keynote style" remain design briefs and proceed through free design. They never activate a workspace unless the user separately asks to browse/select one or supplies its exact root.
-This is intentional: the AI never makes a fuzzy or interpretive judgment about whether wording maps to a template. Use the indexed page choice or an exact root.
+This is intentional: the AI never makes a fuzzy or interpretive judgment about whether wording maps to a template. Explicit template-browsing/selection intent opens the indexed page; an exact root triggers the same stage directly.
-To browse in chat, ask "what templates are available?" The AI lists names and exact paths from the same four indexes. Listing alone does not select anything; return one of those exact paths or make the choice on the Step-3 page.
+To browse, ask "what templates are available?" That explicit request triggers Step 3, whose page and chat listing use the same four indexes. Listing alone does not select anything; return one of those exact paths or make the choice on the page.
### Copy-ready examples
@@ -108,7 +107,7 @@ Make a deck from projects/annual-report/sources/report.md.
Template workspace: projects/acme_template/
```
-For chat-based explicit selection, path labels are optional but exact roots are mandatory. Page-based library selection already carries exact roots. The page allows one registered selection per kind and one specified root. If the specified root has the same parsed kind as a registered selection, the workflow stops at the existing two-workspace conflict-resolution gate instead of choosing one silently.
+For chat-based explicit root selection, path labels are optional but exact roots are mandatory. The triggered page's library selection already carries exact roots. The page allows one registered selection per kind and one specified root. If the specified root has the same parsed kind as a registered selection, the workflow stops at the existing two-workspace conflict-resolution gate instead of choosing one silently.
You do not need to choose a template-use mode. For Layout/Deck, Strategist reads the actual Master/Layout/prototype roster and current content, then decides which pages to select, repeat, skip, reorder, or reorganize. Brand instead supplies identity constraints, while Style supplies direction/method defaults; both leave pages freely composed unless another workspace supplies structure. If you care about a specific boundary, state it in ordinary language in the same request—for example, “keep the cover and closing page exactly, choose suitable middle pages yourself” or “use only the visual language”. That explicit sentence wins over AI judgment.
@@ -121,7 +120,7 @@ Templates are organized into four kinds, each with a discovery index:
- [`layouts_index.json`](../skills/ppt-master/templates/layouts/layouts_index.json) — structure-only workspaces: canvas / page grammar / page types / SVG roster, with identity selected downstream
- [`decks_index.json`](../skills/ppt-master/templates/decks/decks_index.json) — recurring presentation applications with integrated identity, structure, and factual prototype descriptions
-These four indexes are the complete registered-library source for both the default Step-3 page and chat discovery; directories are never scanned. Ask "what templates are available?" for a readable list with exact workspace paths. The kind-specific READMEs define their contracts. Full data model + fusion / conflict-resolution rules: [`templates-architecture.md`](./templates-architecture.md).
+These four indexes are the complete registered-library source for the explicitly triggered Step-3 page and chat discovery; ordinary Default Generate reads none of them, and directories are never scanned. Ask "what templates are available?" for a readable list with exact workspace paths. The kind-specific READMEs define their contracts. Full data model + fusion / conflict-resolution rules: [`templates-architecture.md`](./templates-architecture.md).
### Free design vs template
@@ -131,16 +130,16 @@ Free design is **not** "no structure" or "no style" — the Strategist still pla
### A style brief is not a Style workspace
-A **style brief** is interpretive language ("minimalist" / "Keynote-style" / "editorial") that the Strategist turns into concrete design choices for one deck. A **Style workspace** is a real `kind: style` template with pre-authored communication method and visual defaults, consumed after the user selects its registered Step-3 entry or supplies its exact workspace root.
+A **style brief** is interpretive language ("minimalist" / "Keynote-style" / "editorial") that the Strategist turns into concrete design choices for one deck. A **Style workspace** is a real `kind: style` template with pre-authored communication method and visual defaults, consumed only after the user explicitly opens template selection and chooses its registered entry, supplies its exact workspace root, or receives it through the current Create Template handoff.
| | Style workspace | Style brief |
|---|---|---|
-| How invoked | Registered Step-3 page selection or exact directory path | Free-form description in your message |
+| How invoked | Explicitly triggered Step-3 page selection, exact directory path, or current Create Template handoff | Free-form description in your message; does not open Step 3 |
| What it supplies | Reusable method, role/evidence discipline, and visual defaults; no identity truth or page prototypes | Intent that the Strategist interprets into mode, visual style, color, typography, icons, and imagery |
-| Confirmation | Stored values seed Stage 2; Brand/Deck identity and user-confirmed choices remain authoritative | No pre-authored values; the Strategist proposes concrete candidates and the user confirms them |
+| Confirmation | Stored values seed final Stage 2; Brand/Deck identity and user-confirmed choices remain authoritative | No pre-authored values; the Strategist proposes concrete candidates and the user confirms them |
| Best for | Repeating a design/argument approach across projects without freezing pages | Expressing a desired feel for the current project only |
-A style description and a Style workspace still go through different machinery: "minimalist" is interpretive language, while `templates/styles/<id>/` is a real registered workspace selected by exact index entry or exact path. `kind: style`, Stage-2 `visual_style`, and internal `template_reuse_scope: style` are separate axes.
+A style description and a Style workspace still go through different machinery: "minimalist" is interpretive language and stays in free design, while `templates/styles/<id>/` is a real registered workspace selected through explicit template browsing or an exact path. `kind: style`, final Stage-2 `visual_style`, and internal `template_reuse_scope: style` are separate axes.
### How style briefs are interpreted
@@ -247,7 +246,7 @@ After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-maste
| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Create Brand/Create Style: N/A; Create Layout/Create Deck: optional for one Master, mandatory for multiple Masters | Register in the matching `brands_index.json`, `styles_index.json`, `layouts_index.json`, or `decks_index.json` after validation |
| `project` | `projects/<name>/` | Same kind-specific review behavior | Skip global index registration |
-Library registration makes the template **selectable** on the default page and discoverable in chat because both read the same index. To use a registered workspace, select it in [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation). For project scope or an exact handoff, supply the workspace root, for example `use this template: projects/<name>/`; an unregistered root remains labelled `explicit`. A project workspace can also be migrated or reused elsewhere because its core shape is identical; register it only if it is placed in the library and should appear in the library catalog.
+Library registration makes the template **selectable** on the explicitly triggered template page and discoverable in chat because both read the same index. To use a registered workspace, ask to browse/select templates and choose it in [conditional Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation). For project scope or an exact handoff, supply the workspace root, for example `use this template: projects/<name>/`; an unregistered root remains labelled `explicit`. A project workspace can also be migrated or reused elsewhere because its core shape is identical; register it only if it is placed in the library and should appear in the library catalog.
When a Deck/Layout template is selected, Strategist automatically authors the page/prototype plan. It may use the whole roster or a subset, repeat or reorder prototypes, and reorganize content where needed. `strict` / `adaptive` remain internal exporter values and do not appear as confirmation options.
@@ -308,7 +307,7 @@ nor allowed.
- **Library scope (`library`, default)** writes the workspace under `skills/ppt-master/templates/<kind>/<id>/` and registers it globally.
- **Project scope (`project`)** writes the same portable workspace at `projects/<name>/` and skips registration.
-The result is not a private or reduced project-only format. You can point Step 3 at either workspace root. Brand/Layout/Deck migrate with `templates/` plus any real package-owned `images/` and `icons/`; Style migrates only `templates/design_spec.md`, and unrelated project scaffolding is ignored. If a workspace moves into the library, run its kind-specific registration so discovery reflects the new location.
+The result is not a private or reduced project-only format. Supplying either exact workspace root triggers Step 3 directly. Brand/Layout/Deck migrate with `templates/` plus any real package-owned `images/` and `icons/`; Style migrates only `templates/design_spec.md`, and unrelated project scaffolding is ignored. If a workspace moves into the library, run its kind-specific registration so discovery reflects the new location.
---
diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.md
index 14f3e8ed..4307b48f 100644
--- a/docs/zh/audio-narration.md
+++ b/docs/zh/audio-narration.md
@@ -43,7 +43,7 @@ deck 导出后,在聊天里直接说就行:
你: Generate narration for this deck and re-export with audio embedded.
```
-Generate 路线在 Stage 3 把 Narration Audio 的最终有效结果解析为开启时,
+Generate 路线在最终 Stage 2 把 Narration Audio 的有效结果解析为开启时,
也会主动运行该阶段;后续明确指令仍优先于主动默认值。剩下的 AI 全包。
## 支持的语言
diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.md
index f3a61278..0b0abd97 100644
--- a/docs/zh/getting-started.md
+++ b/docs/zh/getting-started.md
@@ -46,7 +46,7 @@ Create Template 会分析参考材料,确认结果属于 Brand、Style、Layou
| **注册进 skill 库** | `skills/ppt-master/templates/<kind>/<id>/` | 可移植工作区并执行全局注册;问“有哪些模板”时会被列出来 |
| **放在 projects 下** | `projects/<name>/` | 相同的可移植工作区,不执行全局注册 |
-已注册结果可在 Step 3 对应 kind 的下拉框中选择。若要提供其他结果,在对话里给出精确的**工作区根目录路径**:未注册 root 会进入指定地址下拉框;与注册 canonical root 完全相同的路径会归回对应 kind 下拉框。Step 3 会解析 `templates/design_spec.md`;为兼容目录形态,也接受满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 根目录,Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。create-template 可在同一对话里把已验证的精确工作区根目录直接交给 Step 3。两种情况都要求精确选择,绝不认裸模板名。完整工作区可以在全局库与 `projects/` 之间复制或迁移,无需调整目录结构;只有全局库注册不同。
+显式要求浏览或选择模板时,可在 Step 3 对应 kind 的下拉框中选择已注册结果。若要提供其他结果,在对话里给出精确的**工作区根目录路径**:未注册 root 会进入指定地址下拉框;与注册 canonical root 完全相同的路径会归回对应 kind 下拉框。这两种情况都会触发 Step 3;普通自由设计直接跳过。Step 3 会解析 `templates/design_spec.md`;为兼容目录形态,也接受满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 根目录,Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。create-template 可在同一对话里把已验证的精确工作区根目录直接交给 Step 3。两种情况都要求精确选择,绝不认裸模板名。完整工作区可以在全局库与 `projects/` 之间复制或迁移,无需调整目录结构;只有全局库注册不同。
```
你:用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/
@@ -61,20 +61,20 @@ Create Template 会分析参考材料,确认结果属于 Brand、Style、Layou
整个流程就三步。先装好环境——只需要 Python,见 [快速开始](../../README_CN.md#快速开始)。
1. **把源材料放进** `projects/` —— PDF、DOCX、Markdown、一个网址,或直接要粘贴的文字。
-2. **在对话里告诉 AI** 要把什么做成 deck。随后在 Step 3 选择自由设计或组合已注册模板;若要使用未注册模板,把它的精确 root 一并写在对话里,让它出现在指定地址下拉框中:
+2. **在对话里告诉 AI** 要把什么做成 deck。普通请求默认自由设计并直接进入 Stage 1;只有需要模板时才显式要求浏览/选择,或附上精确工作区 root 来触发 Step 3:
```
你:用 projects/q3-report/sources/report.pdf 做一份 PPT
你:把这份内容做成 PPT:<粘贴你的文字>
```
3. **拿回可编辑的 `.pptx`**,位于 `exports/<名称>_<时间戳>.pptx` —— 真正的 DrawingML 形状、文本框、图表,在 PowerPoint / Keynote / WPS / LibreOffice 里点开就能改。
-生成前,Step 3 会先确认自由设计或模板组合;Stage 1 再独立确认沟通契约和画布/格式,Stage 2 确认页数、视觉系统,以及启用模板时的应用方式。之后内容分析、排版、配图、SVG 生成、导出都由 AI 完成——这就是其它能力围绕的核心环节。不想走交互确认,见下方[快速模式](#快速模式)。
+生成前,Stage 1 确认沟通契约和画布/格式,最终 Stage 2 确认页数、视觉系统、启用模板时的应用方式与生产选项。只有显式触发时,模板选择才会在 Stage 1 前出现。之后内容分析、排版、配图、SVG 生成、导出都由 AI 完成——这就是其它能力围绕的核心环节。不想走交互确认,见下方[快速模式](#快速模式)。
---
## 快速模式
-默认流程会先完成 Step 3 选择和分阶段设计确认。不想经过这些交互,就显式要求**快速生成**:
+默认流程会完成两阶段设计确认;只有显式选模板时才增加 Step 3。不想经过这些交互,就显式要求**快速生成**:
```
你:用 sources/report.pdf 快速生成一份 PPT,不用跟我确认
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index cf0eff68..b1236ee2 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -52,12 +52,12 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
├── 若缺少同 stem 的规范 Markdown,再对该归档 PPTX 运行 ppt_to_md.py
└── sources/ 内容型文件成为内容契约
↓
-[模板选择与安装(Step 3)] — Stage 1 前的默认 UI 选择
- 选择自由设计、索引中的 Brand/Style/Layout/Deck library 条目,或精确的 explicit 工作区 root;索引是完整 library 来源,不扫描目录
- 已确认工作区在 Strategist 启动前校验/合成到项目本地 templates/images/icons
+[模板选择与安装(Step 3,条件触发)] — 仅在显式浏览 / 选择模板、提供精确工作区 root,或接收本次 Create Template handoff 时进入
+ 普通自由设计直接打开 Stage 1,不读取模板索引,也不创建模板选择产物
+ 触发后可确认自由设计,或选择索引中的 Brand/Style/Layout/Deck library 条目或精确 explicit 工作区 root;已确认工作区会校验/合成到项目本地 templates/images/icons
原生 PPTX 模板请求进入 template-fill;可复用 SVG 模板需先通过 create-template 创建
↓
-[Strategist] 策略师 - 三阶段策略师确认与设计规范 → design_spec.md + spec_lock.md
+[Strategist] 策略师 - Stage 1 沟通确认 + 最终 Stage 2 完整方案与生产机制确认 → design_spec.md + spec_lock.md
↓
[Image Acquisition] 图片获取(当资源列表中有需要 AI 生成、网络搜索或切片的图片时)
↓
@@ -118,6 +118,8 @@ narration 标记。
凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威,但这里的 SVG 专指项目合同接受的项目规范化 SVG,而不是任意浏览器可渲染的 SVG。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。默认流程由模板、`design_spec.md` 和 `spec_lock.md` 指导 SVG 创作;`quick-generate` 则使用当前上下文决策和 SVG 中的显式值。导出器不能把规划输入当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。
+始终必读的 core 还负责兜底视觉质量与数值行距默认值。显式用户要求、模板 / 品牌和已锁定风格可以覆盖相容的美学默认;这些上层权威未规定时,层级、字体、对齐、留白、有目的的素材使用以及按密度设置的行距范围仍然生效。Default 与 Quick Generate 始终加载 `svg-effects.md`,并在完成每页前运行 Visual Job Router。任何美学选择都不能覆盖技术上的 Required / Forbidden 边界。
+
最小语义标记不会削弱这条闭包。自由设计、brand-only、`quick-generate` 和 `template_reuse_scope: style` 页面都采用 flat 的 Slide 本地所有权:所有已表达对象保持在 Slide,不创作 Master/Layout 身份、分层或 placeholder metadata。默认导出器根据当前配色/字体 lock 生成一个属于本项目的干净 Master 和一个 Blank Layout;无 lock 的 `quick-generate` 使用转换器默认 theme 壳。两者都不会提升任何 Slide 内容。只有 `template_reuse_scope: mirror|layout` 使用 structured 路线,每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。带旧结构语义的模板包不能原地升级,也不能作为 Step 3 的 structured 输入:先通过 `create-template` 创建新工作区;原生 PPTX 只提供包内仍然存在的事实,旧 SVG 只作为视觉参考;随后由 Generate PPTX 路线按照 AI 推导的应用计划创作新页面。flat 项目是有意不带 mapping,不算 legacy。导出器不推断、修补或迁移 Master/Layout 结构与 placeholder。
| 领域 | 权威来源 |
@@ -158,7 +160,8 @@ narration 标记。
| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | Generate PPTX + `beautify-pptx` profile | 通过 SVG 重新生成;内容和分页锁定 |
| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | Enhance Native PPTX(`native-enhance-pptx`) | 直接 OOXML patch;不重新设计 |
| 用户想从一个或多个 PPTX/SVG、图片/PDF、文档/网站、品牌资产、直接文字或混合参考材料包构建可复用模板工作区 | Create Template(`create-template`) | 固定入口读取每个适用证据通道,只分派一个 Create Brand、Create Style、Create Layout 或 Create Deck 子工作流,再返回供 Generate Step 3 使用的工作区根目录;结构型子工作流可导出审阅 PPTX |
-| 用户选择索引中的 library 模板,或提供符合当前合同的精确工作区 root | Generate PPTX Step 3 | 独立的 Stage-1 前置阶段确认自由设计或精确 Brand/Style/Layout/Deck root,再把所选工作区校验/合成到项目;只有兼容的旧平铺 Brand/Layout/Deck 根目录可解析直接 `design_spec.md` |
+| 没有显式模板浏览 / 选择请求、精确工作区 root 或本次 Create Template handoff | Generate PPTX 自由设计 | 跳过 Step 3,直接打开 Stage 1;不读取模板索引,也不创建模板选择产物 |
+| 用户显式要求发现 / 选择模板、提供符合当前合同的精确工作区 root,或继续使用本次 Create Template handoff | Generate PPTX Step 3 | 条件式 Stage-1 前置阶段确认自由设计或精确 Brand/Style/Layout/Deck root,再把所选工作区校验/合成到项目;只有兼容的旧平铺 Brand/Layout/Deck 根目录可解析直接 `design_spec.md` |
| 用户要求调整对象级动画顺序 / 效果 / 计时 | Generate PPTX + `customize-animations` 阶段 | 通过 `animations.json` 控制可选导出策略 |
| 用户要求预览、选择、注解或重导出浏览器编辑 | Generate PPTX + `live-preview` 阶段 | 注解只在规定交接点应用 |
@@ -347,11 +350,11 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
## 模板系统与可选路径
-模板是**可选项,不会被自动推断**。Strategist Stage 1 之前,默认 UI 会先打开独立 Step 3:自由设计、Brand/Style/Layout/Deck 四个已注册模板单选下拉框,以及一个本次运行指定 root 的单选下拉框。自由设计仍是从当前内容推导的路径;系统不会根据主题相似度替用户选模板。
+模板是**可选项,不会被自动推断**。普通自由设计会跳过 Step 3,不读取模板索引,也不创建模板选择产物,直接打开 Strategist Stage 1。只有用户显式要求浏览 / 选择模板、为本次运行提供精确工作区 root,或继续使用本次 Create Template handoff 时,Step 3 才会出现。触发后的 UI 只列出已注册的 Brand/Style/Layout/Deck 条目与显式提供的精确 root;系统不会根据主题相似度替用户选模板。
**为什么默认自由设计。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),所以它一直在;但 AI 不主动去抓,是用户去抓。
-**精确选择,不做语义匹配。** 像 `presentation_core` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,永远不会 fuzzy-match 到目录。默认页面只从四个 `*_index.json` 列出已注册 Brand/Style/Layout/Deck;聊天发现也读取同一组索引并返回精确 root。显式路径仍有效;若它与某个已注册 canonical root 精确相同,可显示为 `library`,未注册 root 仍是 `explicit`。服务端解析每个 explicit root 的真实 `kind`,来源标签本身不参与优先级。当前工作区均解析 `templates/design_spec.md`;自由文字风格说明仍只是 Stage 2 输入,不会启用 Style 工作区。旧平铺 Brand/Layout/Deck 目录只有在满足当前 kind 合同时,才兼容从根目录读取 `design_spec.md`;Layout/Deck 还必须满足当前 structured SVG 合同。Style 不存在旧平铺形态。目录形态从不授权结构迁移;带旧 Master/Layout/placeholder 语义的包必须先替换为新建的模板工作区。
+**精确选择,不做语义匹配。** 像 `presentation_core` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,永远不会 fuzzy-match 到目录。触发后的页面只从四个 `*_index.json` 列出已注册 Brand/Style/Layout/Deck;聊天发现也读取同一组索引并返回精确 root。显式路径仍有效;若它与某个已注册 canonical root 精确相同,可显示为 `library`,未注册 root 仍是 `explicit`。服务端解析每个 explicit root 的真实 `kind`,来源标签本身不参与优先级。当前工作区均解析 `templates/design_spec.md`;自由文字风格说明仍只是 Stage 2 输入,不会启用 Style 工作区。旧平铺 Brand/Layout/Deck 目录只有在满足当前 kind 合同时,才兼容从根目录读取 `design_spec.md`;Layout/Deck 还必须满足当前 structured SVG 合同。Style 不存在旧平铺形态。目录形态从不授权结构迁移;带旧 Master/Layout/placeholder 语义的包必须先替换为新建的模板工作区。
当前 Brand/Style/Layout/Deck 都采用同一工作区路由合同;Brand 与 Style 不含 SVG roster,空的可选目录直接省略:
@@ -367,7 +370,7 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
Style 将这一路由形态收窄为仅 `templates/design_spec.md`,不携带素材或
审阅 payload;项目中既有的脚手架也不属于 Style 输入。
-`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/` 等其他精确 root。Step 3 会把所选输入校验、合成并安装到当前项目的 `templates/`、`images/`、`icons/`,不复制 `exports/`。Stage 1 完成后,模板感知的 Strategist 及后续角色只读该项目本地副本。源工作区可在不同位置间迁移而不改形;全局索引注册决定它是否作为 library 选项出现。
+`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/` 等其他精确 root。触发后,Step 3 会把所选输入校验、合成并安装到当前项目的 `templates/`、`images/`、`icons/`,不复制 `exports/`。Stage 1 完成后,模板感知的 Strategist 及后续角色只读该项目本地副本。源工作区可在不同位置间迁移而不改形;全局索引注册决定它是否作为 library 选项出现。
对 Create Layout / Create Deck,`standard` 与 `fidelity` 会重新创作 SVG 和新的 Master/Layout/slot 系统;来源拓扑只作为视觉证据,不保留、也不蒸馏。`mirror` 把来源包内实际存在且已验证的页序、Master/Layout 身份与父子关系、placeholder 事实和受支持视觉物化到新工作区,不做语义归纳或缺口补造。只有被保留的来源本身已经品牌中立且应用中立时,Layout mirror 才合法;否则应重新创作 Layout,或把这些事实保留为 Deck。由于结构层不能是 `<g>`,固定结构层的来源 group wrapper 只允许机械展开成直接原子,同时保持归属、paint order 和视觉一致。Create Brand 只提取身份片段,Create Style 只提取可移植方法/方向;两者都不进入结构复制策略,也不生成 SVG roster。
@@ -398,10 +401,10 @@ PPT Master 把拥有 deck 状态的 Strategist、Image_Generator 和 Executor
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式:不得重选上游方案或漏掉必需属性,但在 Design Spec 留出的范围内仍拥有几何、构图、层级和视觉处理的实现权。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。
-**独立 Step 3 模板选择会在 Strategist 确认阶段前完成。** 它不属于 Stage 1:默认 UI 先确认自由设计,或精确的 indexed/explicit 工作区,并运行统一安装/合成阶段。Stage 1 随后只使用当前请求、源材料事实、对话约束和项目初始化状态确认开放式沟通契约与画布;不得读取选择结果、已安装模板内容或模板画布。Strategist 阶段以一个按依赖排序的三阶段 gate 作为核心决策点。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。第二阶段只从该契约计算一次并确认完整 PPT 方案:阅读模式、叙事 mode、页数、成套视觉系统、图片来源和生成图渲染。仅在 Stage 1 确认后,存在已安装模板时,Strategist 才读取项目本地工作区和当前内容,推导**如何应用**并以可编辑的 `template_application` 自然语言展示;Stage 2 不会重新选模板,内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算第二阶段。第三阶段也只计算一次,并且只处理生产机制:条件式 AI 图片获取路径、公式策略、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。这三项是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → Stage 3 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。JSON 为兼容保留 `delivery_purpose` 键,但用户侧统一称为阅读模式。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。
+**条件触发的 Step 3 模板选择会在 Strategist 确认阶段前完成。** 普通自由设计跳过 Step 3,直接打开 Stage 1。Step 3 触发后,UI 会确认自由设计或精确的 indexed/explicit 工作区,并在 Stage 1 前完成安装/合成。Stage 1 随后只使用当前请求、源材料事实、对话约束和项目初始化状态确认开放式沟通契约与画布;不得读取选择结果、已安装模板内容或模板画布。Strategist 采用一个按依赖排序的两阶段 gate。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。最终 Stage 2 只从该契约计算一次,同时确认完整 PPT 方案与生产机制:阅读模式、叙事 mode、页数、成套视觉系统、图片来源、生成图渲染、条件式 AI 图片获取路径、公式策略、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。仅在 Stage 1 确认后,存在已安装模板时,Strategist 才读取项目本地工作区和当前内容,推导**如何应用**并以可编辑的 `template_application` 自然语言展示;Stage 2 不会重新选模板,内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算 Stage 2。三个主动执行值是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → 最终 Stage 2 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。
-Stage 3 的三个主动执行值始终保留为相互独立的原始证据。尤其是,
-启用旁白可以在 Design Spec 中启用 Speaker Notes 的最终有效结果,
+最终 Stage 2 确认的三个主动执行值始终保留为相互独立的原始证据。
+尤其是,启用旁白可以在 Design Spec 中启用 Speaker Notes 的最终有效结果,
但绝不会改写原始的备注选择。
**图片分析以重算元数据为先,只保留小范围视觉兜底。** 当项目里存在图片时,`analyze_images.py` 把可度量事实重算到 `analysis/image_analysis.csv`;该 CSV 是实时 `images/` 目录的派生视图,不是持久缓存。默认流程中,Strategist 先根据图片在源文中的位置与前后文、图注 / alt / 标题、文件名、用户说明、已有资源记录和这些元数据判断。只有当某一张具体图片在选用、事实身份、页面角色、裁剪安全或焦点放置上仍有实质歧义时,才可单独查看它,绝不得扫描整个图片目录。结论写入 Design Spec §VIII 后,Executor 只消费该计划与几何数据,不会重新打开源图进行语义探索。`quick-generate` 则由当前 Agent 在上下文中自动准备资源清单时采用同样的有界分析,不写 Design Spec 投影。用户图、抽取图、网络图、AI 图、公式图和切片图仍统一汇入同一张可度量事实表。
@@ -452,14 +455,14 @@ Generate 执行以 [`workflows/generate-pptx.md`](../../skills/ppt-master/workfl
| 餐厅角色 | PPT Master 对应项 | 决策权 |
|---|---|---|
| 顾客与初始食材 | 用户确认与用户提供的原材料/素材 | 决定事实、意图、排除项、材料补充许可,以及要求具体到什么程度 |
-| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表参考 key / 模板版式 key、字体、色板锚点、图标和裁剪边界;记录可选的能力 / 表达建议;在执行前备齐项目级材料清单 |
-| 厨师 | Executor | 只使用项目中已备好的材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料;可以调整明确标为 suggestion 或 Reference 的字段 |
+| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表参考 key / 模板版式 key、字体、色板锚点、图标系统与精选图标池、裁剪边界;记录可选的能力 / 表达建议;在执行前备齐项目级材料清单 |
+| 厨师 | Executor | 只使用项目中已备好的材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料;按页选择适合的已备图标,并可调整明确标为 suggestion 或 Reference 的字段 |
**快速生成把规划职责合并到当前 Agent。** 来源转换、事实缺口研究和资源准备仍按需运行。当前 Agent 在上下文中自动选择内容、页面清单、视觉系统和资源需求,准备用户提供 / 来源抽取 / AI / 网络 / 切片图片、图标和公式及其必要 manifest 或来源记录,随后手写 SVG;不进入 Strategist、Confirm UI、`design_spec.md` 或 `spec_lock.md`。
-**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。
+**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证精选项目图标池。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。
-**项目中已备好的材料就是边界。** 默认流程中,图片和其他声明型资源须由 Strategist 选定、写入规划产物,并保证项目路径可解析或明确标为 `Needs-Manual`。图标 SVG 只要已位于 `<project>/icons/` 就属于已备材料;`spec_lock.icons.inventory` 记录 Strategist 计划选用的内置图标,但不是穷尽式执行白名单。快速生成以当前上下文中的资源清单及其项目级文件 / manifest 代替该规划投影;当前 Agent 可以在手写 SVG 前获取并准备这些资源。其他目录中的文件不构成使用许可。缺料必须回到所属备料步骤;SVG 创作阶段不得静默换料。
+**项目中已备好的材料就是边界。** 默认流程中,图片和其他声明型资源须由 Strategist 选定、写入规划产物,并保证项目路径可解析或明确标为 `Needs-Manual`。图标 SVG 只要已位于 `<project>/icons/` 就属于已备材料;`spec_lock.icons.inventory` 是 Strategist 已同步精选内置图标池的索引,既不分配具体页面,也不是穷尽式执行白名单。Executor 按页从已备图标中选择。快速生成以当前上下文中的资源清单及其项目级文件 / manifest 代替该规划投影;当前 Agent 可以在手写 SVG 前获取并准备这些资源。其他目录中的文件不构成使用许可。缺料必须回到所属备料步骤;SVG 创作阶段不得静默换料。
**具体程度决定自由度。** “做麻婆豆腐”锁定成品身份:火候、口感和摆盘可以发挥,但不能换成番茄炒蛋或豆腐汤。“做一道豆腐菜”则保留了品类内选择空间。默认流程中,Strategist 可以把这个开放要求收敛成具体方案;如果 Design Spec 有意保留某个维度的开放性,Executor 可以在该范围内实现。一旦 Design Spec 已经选定具有约束力的结果,执行阶段不得重新打开选择。快速生成则由当前 Agent 在上下文中解决同等选择,并在手写 SVG 时保持稳定。明确标为 suggestion 或 Reference 的字段——包括页面级首选图片 pattern——仍是表达建议;只要不改变内容、资源、身份和显式约束,就可以调整。
@@ -730,7 +733,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu
|---|---|---|
| 生成 profile | `beautify-pptx`、`quick-generate` | Generate PPTX;分别负责逐字措辞 / 页数 / 页序不变量与显式 SVG→PPTX 直接短路 |
| 模板子工作流 | `create-brand`、`create-style`、`create-layout`、`create-deck` | Create Template 在“仅身份 / 无 roster 的方向与方法 / 品牌中立且应用中立的结构 / 应用语境与身份结构一体化”中只分派一个 |
-| 模板输入阶段 | `apply-template-workspace` | Generate PPTX Step 3;独立 indexed/explicit 选择确认至少一个工作区后运行 |
+| 模板输入阶段 | `apply-template-workspace` | 条件式 Generate PPTX Step 3;仅在显式浏览 / 选择请求、精确 root 或本次 Create Template handoff 确认至少一个工作区后运行 |
| 生成阶段 | `topic-research`、`resume-execute`、`refine-spec`、`verify-charts`、`visual-review`、`live-preview`、`customize-animations` | Generate PPTX 中各自定义的 intake、planning、editing、quality 或 post-processing 节点 |
| 共享阶段 | `generate-audio` | Generate PPTX 后处理,或 Enhance Native PPTX 的旁白集成 |
| 治理文档 | `failure-recovery` | 四条顶层路线的全局停止 / 继续规则;Generate PPTX 的具体故障矩阵与续跑入口 |
diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.md
index c262f689..bb7ae193 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -178,7 +178,7 @@ keywords: [tag1, tag2, tag3]
Style 不写 SVG,也不拥有 Brand 官方身份、Deck 应用契约、canvas、页数/
顺序、Master/Layout/placeholder 结构或逐页资源。其色彩与字体只是可覆盖
fallback:用户最终确认及 Brand/Deck 身份优先。Review Focus 不能启动
-visual review。`kind: style` 表示可复用包类型,区别于 Stage 2 的
+visual review。`kind: style` 表示可复用包类型,区别于最终 Stage 2 的
`visual_style` 选择和内部 flat 导出值 `template_reuse_scope: style`。
### Layout schema
@@ -336,16 +336,16 @@ Template Overview 写明可重复演示类型、目标受众与结果、交付/
### 片段所有权(隐式触发)
-用户确认已注册和/或指定工作区根目录后,Step 3 会解析每个 root 的真实
+显式触发的 Step 3 确认已注册和/或指定工作区根目录后,会解析每个 root 的真实
`kind`,再分片段写入一份 `<project>/templates/design_spec.md`。
`library` / `explicit` 只记录发现来源,不改变所有权:
| 片段 | 起始所有者 |
|---|---|
-| 身份 | Brand,其次 Deck,否则留到 Stage 2;Style 只提供 fallback 候选 |
-| 方向/方法 | Style,否则留到 Stage 2;Deck 的真实原型与 Signature 事实只提供兼容性依据 |
-| 结构 | 兼容 Layout,其次 Deck,否则留到 Stage 2 / 自由设计 |
-| 可复用应用语境 | 仅 Deck;保留供 Stage 2 对照,绝不充当当前项目的应用契约 |
+| 身份 | Brand,其次 Deck,否则留到最终 Stage 2;Style 只提供 fallback 候选 |
+| 方向/方法 | Style,否则留到最终 Stage 2;Deck 的真实原型与 Signature 事实只提供兼容性依据 |
+| 结构 | 兼容 Layout,其次 Deck,否则留到最终 Stage 2 / 自由设计 |
+| 可复用应用语境 | 仅 Deck;保留供最终 Stage 2 对照,绝不充当当前项目的应用契约 |
用户当前明确指令和最终确认高于所有起始所有者。Brand 身份高于 Style
的色彩/字体 fallback。Style-only 或 Style + Brand 使用 flat 创作;Style
@@ -355,7 +355,7 @@ Layout 覆盖 Deck 前,必须把 Deck 的可复用应用角色与 Layout 的
槽位类型和容量对照;Style 与 Layout/Deck 合成前,也要确认其沟通方法和
构图预期能够被该可复用语境与结构兑现。不兼容时显式报告模板片段冲突,
不能静默混合字段或保留一份当前结构无法兑现的承诺。当前项目的适配只在
-Stage 1 确认后的 Stage 2 开始。
+Stage 1 确认后的最终 Stage 2 开始。
### 段级整段替换(默认粒度)
@@ -383,7 +383,7 @@ AI: 你给了两个 brand,检测到段级冲突:
- `style × 2`、`layout × 2`、`deck × 2`、`brand × 2` 同处理
- 每类最多两份(再多让用户先在 chat 里收敛)
-默认页面已经把组合空间收窄:Brand/Style/Layout/Deck 各有一个已注册模板
+显式触发的模板页面已经把组合空间收窄:Brand/Style/Layout/Deck 各有一个已注册模板
单选下拉框,另有一个指定地址下拉框;指定地址按解析出的 kind,最多给该类
增加第二份。服务端强制同一限制;聊天组合仍保留每类最多两份的通用边界。
@@ -406,7 +406,7 @@ AI: 你给了两个 brand,检测到段级冲突:
## 五、与 Generate PPTX Step 3 的关系
-**触发规则仍以精确选择为准**——使用 Step 3 已注册模板下拉选项或显式工作区根目录路径(见 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option));裸名称绝不触发。Step 3 先解析 `<workspace>/templates/design_spec.md`;为兼容目录形态,也接受根目录直接包含 `<workspace>/design_spec.md`、且满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 工作区。Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。若包仍使用 `native_structure_mode: template`、缺 Master 身份、原子 placeholder 或蒸馏时代标记等旧语义,Step 3 必须拒绝;先由 `create-template` 产出新工作区,再继续生成。唯一的窄例外是当前对话刚完成 `create-template`:验证通过后可把精确的工作区根目录直接交给 Step 3。`kind` 字段决定**触发后 AI 怎么处理**:
+**Step 3 是条件阶段。** 普通 Default Generate 直接走自由设计,不读模板索引、不打开模板页面,并直接进入 Stage 1。只有显式要求浏览/选择模板、提供精确工作区根目录,或接到当前对话中 Create Template 交出的精确已验证 root,才进入 Step 3(见 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation));裸模板/品牌名称或风格词绝不触发。触发后,Step 3 先解析 `<workspace>/templates/design_spec.md`;为兼容目录形态,也接受根目录直接包含 `<workspace>/design_spec.md`、且满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 工作区。Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。若包仍使用 `native_structure_mode: template`、缺 Master 身份、原子 placeholder 或蒸馏时代标记等旧语义,Step 3 必须拒绝;先由 `create-template` 产出新工作区,再继续生成。`kind` 字段决定**触发后 AI 怎么处理**:
| 用户路径指向 | Step 3 行为(按 kind 分支)|
|---|---|
@@ -421,7 +421,7 @@ AI: 你给了两个 brand,检测到段级冲突:
### 策略师确认阶段在不同 kind 下的行为
-安装模板不会让沟通问题消失。Stage 1 始终独立确认同一份开放式沟通契约,只使用当前请求、源材料事实、对话约束和项目初始化状态,连模板画布也不能参与。Stage 1 完成后,Stage 2 才读取已安装状态。Brand 提供身份约束、结构仍然自由;Style 提供方法和视觉默认值候选并保持 flat;Layout 提供结构能力;Deck 提供描述性的可复用应用语境供对照,但不充当当前项目契约。Style-only 时 Strategist 不读取原型,固定写入 `template_reuse_scope: style` 与 flat 结构;Layout/Deck 才读取真实原型和当前内容,生成页面/原型计划,并把 `mirror`、`layout` 或 `style` 记录为内部导出值。按 mirror 创建的工作区因此只提供原样复用能力,不会强制使用;Confirm UI 不显示模板模式字段。规划语义由 `references/strategist.md` 与 `references/strategist-template.md` 负责,机器结构由 `templates/schemas/spec_lock.schema.json` 负责。
+安装模板不会让沟通问题消失。Stage 1 始终独立确认同一份开放式沟通契约,只使用当前请求、源材料事实、对话约束和项目初始化状态,连模板画布也不能参与。Stage 1 完成后,最终 Stage 2 才读取已安装状态,并确认完整方案与制作计划。Brand 提供身份约束、结构仍然自由;Style 提供方法和视觉默认值候选并保持 flat;Layout 提供结构能力;Deck 提供描述性的可复用应用语境供对照,但不充当当前项目契约。Style-only 时 Strategist 不读取原型,固定写入 `template_reuse_scope: style` 与 flat 结构;Layout/Deck 才读取真实原型和当前内容,生成页面/原型计划,并把 `mirror`、`layout` 或 `style` 记录为内部导出值。按 mirror 创建的工作区因此只提供原样复用能力,不会强制使用;Confirm UI 不显示模板模式字段。规划语义由 `references/strategist.md` 与 `references/strategist-template.md` 负责,机器结构由 `templates/schemas/spec_lock.schema.json` 负责。
---
diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.md
index 897adbb3..7cd54f20 100644
--- a/docs/zh/templates-guide.md
+++ b/docs/zh/templates-guide.md
@@ -19,7 +19,7 @@ PPT Master 模板是一种可复用工作区,明确分为四类:**Brand**
| 起点与目标 | 路线 | 可直接复制的请求 |
|---|---|---|
| 手里是原始 `.pptx`,想保留现有页面壳并替换内容 | **Fill Native PPTX** | `用 projects/source/template.pptx 套入 projects/source/content.md 的内容。` |
-| 已有可复用 Brand/Style/Layout/Deck 工作区,想生成一份全新 deck | **Generate PPTX → Step 3 模板选择** | `用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/。` |
+| 已有可复用 Brand/Style/Layout/Deck 工作区,想生成一份全新 deck | **Generate PPTX → 条件触发的 Step 3 模板选择** | `用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/。` |
| 手里是 PPTX、SVG、品牌手册、网站、图片或混合参考,想先建立可复用系统 | **Create Template → Generate PPTX** | `用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 工作区。` |
不要把原始 `.pptx` 当作 Generate PPTX 的模板路径。想沿用它的现有页面就直接回填;想建立可复用系统,就先运行 Create Template。
@@ -29,7 +29,7 @@ PPT Master 模板是一种可复用工作区,明确分为四类:**Brand**
| Kind | 复用什么 | 原生 PowerPoint 结果 |
|---|---|---|
| **Brand** | 颜色、字体、Logo、语调、图标风格 | 只提供身份约束。生成页面保持 Slide 本地,文件只有干净的项目 Master 与 Blank Layout 脚手架。 |
-| **Style** | 沟通方法、开放页面角色词汇、证据/数据规则、视觉默认值、图片/图标方向及审阅关注点 | 生成 flat Slide-local 页面;这些值只作为 Stage 2 起点,不升级为品牌身份或可复用 Layout。 |
+| **Style** | 沟通方法、开放页面角色词汇、证据/数据规则、视觉默认值、图片/图标方向及审阅关注点 | 生成 flat Slide-local 页面;这些值只作为最终 Stage 2 起点,不升级为品牌身份或可复用 Layout。 |
| **Layout** | 品牌中立的页面语法、Master/Layout 身份、语义文字角色、槽位与版式 roster | 结构化 deck,包含可复用原生 Master、具名 Layout 与 placeholder;身份、阅读模式字号和沟通应用另行解析。 |
| **Deck** | 一类可重复演示:描述性应用语境、身份、页面结构与真实原型 | AI 根据模板实物与当前内容自动生成页面/原型应用计划。 |
@@ -37,8 +37,8 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
最容易避免误用的两条规则:
-1. 默认页面会在 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation) 选择自由设计或精确的已注册工作区;若在聊天中选择,请给出工作区根目录,不要只给 `templates/` 子目录,也不要只写模板名。
-2. 显式路径和 Create Template 的精确交接仍然有效。Step 3 会先确认并安装全部所选工作区,再进入 Stage 1;模板感知读取从 Stage 2 开始,且只读项目本地副本。
+1. 普通 Default Generate 没有模板阶段:不读模板索引、不打开模板页面,直接以自由设计进入 Stage 1。
+2. 只有显式要求浏览/选择模板、提供精确工作区根目录,或接到当前对话中 Create Template 产出的精确已验证 root,才进入 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)。Step 3 会在 Stage 1 前安装所选工作区;模板感知读取从最终 Stage 2 开始,且只读项目本地副本。
---
@@ -46,7 +46,7 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
### 触发方式
-默认确认页面会在 Stage 1 之前打开一个独立的 **Step 3 模板选择阶段**,同时提供自由设计、已注册的 Brand/Style/Layout/Deck,以及本次运行已明确给出的工作区根目录。它不会根据主题替用户推断推荐模板,选择必须由用户明确完成。
+普通 Default Generate 不进入 Step 3,而是直接以自由设计打开 Stage 1。只有显式要求浏览/选择模板、提供精确工作区根目录,或接到当前对话中的 Create Template 交接,才会在 Stage 1 前打开独立的 **Step 3 模板选择阶段**。触发后的页面同时提供自由设计、已注册的 Brand/Style/Layout/Deck,以及本次运行已明确给出的工作区根目录;它不会根据主题替用户推断推荐模板,选择必须由用户明确完成。
> **快速模式例外:** Quick 不会打开这个页面。请求中每个 kind 最多一个精确
> 工作区 root,会被直接校验、安装并使用;没有精确 root 就直接自由设计。
@@ -55,7 +55,7 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
### 怎么触发模板流程
-默认页面提供自由设计,以及五个紧凑下拉框:Brand、Style、Layout、Deck 各一个已注册工作区单选框,再加一个本次运行指定地址单选框。每个下拉框都有“无”;四类已注册模板可跨类型组合,指定地址最多选一个。已注册列表只来自四类索引,工作流不会扫描模板目录。也可以在 Generate PPTX 进入 Step 3 前,于对话里写出 Brand/Style/Layout/Deck 工作区根目录(位置不重要,只要明确即可):
+触发后的模板页面提供自由设计,以及五个紧凑下拉框:Brand、Style、Layout、Deck 各一个已注册工作区单选框,再加一个本次运行指定地址单选框。每个下拉框都有“无”;四类已注册模板可跨类型组合,指定地址最多选一个。已注册列表只来自四类索引,工作流不会扫描模板目录。也可以直接在对话里写出 Brand/Style/Layout/Deck 工作区根目录来触发 Step 3(位置不重要,只要明确即可):
> "用这个模板做:`skills/ppt-master/templates/layouts/presentation_core/`" ✅
> "用上次那个模板:`projects/last_deck/`" ✅
@@ -63,19 +63,18 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
对于当前所有模板类型,显式路径都是**模板工作区根目录**。若精确路径与索引中的注册 root 一致,页面可以把它显示为 `library`;未注册 root 则单独标为 `explicit`,并由服务端解析其 frontmatter 中的真实 `kind`。`explicit` 只是来源,不是第五种类型,也不提高优先级。Step 3 会解析其中的 `templates/design_spec.md`;Brand/Layout/Deck 安装其包自有 `templates/` 及真实存在的 `images/`、`icons/`,Style 只安装 spec,并忽略项目中无关的脚手架。如果工作区本来就是该项目根目录,则原地消费,并且始终不复制 `exports/`。Deck/Layout 还会校验 structured SVG 合同;Brand/Style 校验各自无 roster 的 spec。路径可以指向 `skills/ppt-master/templates/<kind>/<id>/` 下的内置库工作区、`projects/<name>/` 下的项目工作区,或其他保持同样路由的工作区。当前对话刚完成 Create Template 时,可把精确的已验证工作区根目录直接交给 Step 3。
-模板选择不属于 Stage 1。确认后,Step 3 会运行统一 apply 阶段,把所选工作区校验、合成并安装到当前项目的 `templates/`、`images/`、`icons/`;完成后 Strategist 才开始 Stage 1。Stage 1 只使用当前请求、源材料事实、对话约束和项目初始化状态,模板选择、已安装内容及模板画布均不得影响这份契约。Stage 1 确认后,Stage 2 才把它与已安装状态进行适配;`template_application` 只描述**如何使用**,不负责决定**选哪个模板**。
+模板选择不属于 Stage 1。触发 Step 3 后,确认会运行统一 apply 阶段,把所选工作区校验、合成并安装到当前项目的 `templates/`、`images/`、`icons/`;完成后 Strategist 才开始 Stage 1。Stage 1 只使用当前请求、源材料事实、对话约束和项目初始化状态,模板选择、已安装内容及模板画布均不得影响这份契约。Stage 1 确认后,最终 Stage 2 才把它与已安装状态进行适配;`template_application` 只描述**如何使用**,不负责决定**选哪个模板**。
> **兼容性预检:** Step 3 也接受 `design_spec.md` 直接位于所给根目录、且满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 工作区。Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。旧的原子 placeholder、未映射 Master/Layout 等语义旧包会被拒绝。先运行 `create-template` 创建新工作区,再从该工作区生成新的 structured 页面;不会原地升级旧包。
### 什么**不会**触发模板流程
-- **在聊天中只写模板名**:"用 presentation_core 模板" / "做一份中国电信模板的产品介绍" 不会被隐式解析。请在页面选择对应索引项,或在聊天中返回精确路径。
-- **风格描述**:"麦肯锡风格" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" 仍只是设计说明;除非用户另行选择工作区,否则不会激活模板。
-- **模糊意图**:"想用个模板" / "选一个吧" 不会授权模糊查找或目录扫描,Step 3 选择仍保持未完成。
+- **在聊天中只写模板名**:"presentation_core" / "中国电信模板" 不会被隐式解析,也不会打开模板页面。请明确要求浏览/选择模板,或在聊天中返回精确路径。
+- **风格描述**:"麦肯锡风格" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" 仍只是自由设计说明;除非用户另行要求浏览/选择工作区或提供精确 root,否则不会激活模板。
-这是有意的——AI 永远**不做模糊 / 解释性判断**,不会替你把普通文字解析成模板。请使用页面中的精确索引项,或提供精确 root。
+这是有意的——AI 永远**不做模糊 / 解释性判断**,不会替你把普通文字解析成模板。显式的模板浏览/选择意图会打开索引页面;精确 root 会直接触发同一阶段。
-想在聊天里知道内置库有哪些模板,问一句"有哪些模板可以用?"——AI 会从同一组四类索引列出名字和精确路径。单纯列出不代表选择;需要返回其中一条精确路径,或在 Step 3 页面完成选择。
+想知道内置库有哪些模板,问一句“有哪些模板可以用?”即可。这条显式请求会触发 Step 3,其页面与聊天列表读取同一组四类索引。单纯列出不代表选择;需要返回其中一条精确路径,或在页面完成选择。
### 可直接复制的用法
@@ -101,7 +100,7 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
模板工作区:projects/acme_template/
```
-在聊天中显式选择时,“模板工作区”这些标签可以不写,但 root 必须精确;页面中的 library 选择已自带精确 root。页面中每个注册 kind 最多选一个,指定地址最多选一个;若指定地址解析出的 kind 与某个注册选择相同,工作流会进入既有的两份同类冲突解决门,不会静默替你选一个。
+在聊天中显式提供 root 时,“模板工作区”这些标签可以不写,但 root 必须精确;触发后的页面中,library 选择已自带精确 root。页面中每个注册 kind 最多选一个,指定地址最多选一个;若指定地址解析出的 kind 与某个注册选择相同,工作流会进入既有的两份同类冲突解决门,不会静默替你选一个。
你不需要选择模板使用模式。对 Layout/Deck,Strategist 会读取真实的 Master/Layout/原型集合和当前内容,决定选哪些页、哪些重复/跳过/重排,以及是否重组。Brand 只提供身份约束,Style 只提供方向/方法默认值;除非另一个工作区提供结构,否则两者都保持页面自由编排。如果你在意某个边界,直接在同一句请求里用普通语言说明即可,例如“封面和结束页原样保留,中间页由你选择”或“只参考视觉语言”;明确文字优先于 AI 判断。
@@ -114,7 +113,7 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
- [`layouts_index.json`](../../skills/ppt-master/templates/layouts/layouts_index.json) — 仅结构工作区:canvas / 页面语法 / page types / SVG roster,身份系统下游再选
- [`decks_index.json`](../../skills/ppt-master/templates/decks/decks_index.json) — 可重复演示应用,包含一体化身份、结构与原型事实描述
-这四个索引是默认 Step 3 页面与聊天发现共用的完整已注册模板来源,目录永远不会被扫描。直接问“有哪些模板可以用?”即可得到带精确工作区路径的可读清单;四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
+这四个索引是显式触发的 Step 3 页面与聊天发现共用的完整已注册模板来源;普通 Default Generate 不读取它们,目录也永远不会被扫描。直接问“有哪些模板可以用?”即可得到带精确工作区路径的可读清单;四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
### 自由设计 vs 模板
@@ -124,16 +123,16 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
### 风格说明不是 Style 工作区
-**风格说明**是解释性语言(“极简风” / “Keynote 风” / “杂志风”),由 Strategist 转化为当前 deck 的具体设计选择。**Style 工作区**则是真实存在的 `kind: style` 模板,预写可复用沟通方法与视觉默认值;用户在 Step 3 选择对应注册项,或提供精确工作区 root 后才会消费。
+**风格说明**是解释性语言(“极简风” / “Keynote 风” / “杂志风”),由 Strategist 转化为当前 deck 的具体设计选择。**Style 工作区**则是真实存在的 `kind: style` 模板,预写可复用沟通方法与视觉默认值;只有用户显式打开模板选择并选择注册项、提供精确工作区 root,或接到当前 Create Template 交接后才会消费。
| | Style 工作区 | 风格说明 |
|---|---|---|
-| 怎么触发 | Step 3 页面选择注册项,或消息里给出精确目录路径 | 消息里写自由描述 |
+| 怎么触发 | 显式触发 Step 3 后选择注册项、消息里给出精确目录路径,或当前 Create Template 交接 | 消息里写自由描述;不打开 Step 3 |
| 提供什么 | 可复用方法、角色/证据纪律和视觉默认值;无身份真值或页面原型 | 由 Strategist 解释为 mode、visual style、色彩、字体、图标与图片方向 |
-| 如何确认 | 已存值作为 Stage 2 起点;Brand/Deck 身份和用户最终确认仍然权威 | 没有预写数值;Strategist 给出具体候选,由用户确认 |
+| 如何确认 | 已存值作为最终 Stage 2 起点;Brand/Deck 身份和用户最终确认仍然权威 | 没有预写数值;Strategist 给出具体候选,由用户确认 |
| 适用场景 | 跨项目复用论证与设计方法,但不锁页面 | 只表达当前项目想要的感觉 |
-风格描述和 Style 工作区仍走**两套机制**:“极简风”是解释性语言,`templates/styles/<id>/` 则是真实注册工作区,必须通过精确索引项或精确路径选择。`kind: style`、Stage 2 `visual_style` 与内部 `template_reuse_scope: style` 是三条不同轴。
+风格描述和 Style 工作区仍走**两套机制**:“极简风”是解释性语言并留在自由设计,`templates/styles/<id>/` 则是真实注册工作区,必须通过显式模板浏览或精确路径选择。`kind: style`、最终 Stage 2 `visual_style` 与内部 `template_reuse_scope: style` 是三条不同轴。
### 风格说明如何被解释
@@ -235,7 +234,7 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \
| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | Create Brand/Create Style:不适用;Create Layout/Create Deck:单 Master 可选、多 Master 必须 | 校验后注册到对应 `brands_index.json`、`styles_index.json`、`layouts_index.json` 或 `decks_index.json` |
| `project` | `projects/<name>/` | 沿用同一套 kind-specific 审阅规则 | 跳过全局索引注册 |
-全局注册会让模板出现在默认页面中,也可在聊天中发现,因为两者都读取同一个索引。使用已注册工作区时,在 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation) 中直接选择它。项目范围或精确交接则提供工作区 root,例如 `用这个模板:projects/<name>/`;未注册 root 仍标记为 `explicit`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要出现在 library 列表中时才执行注册。
+全局注册会让模板出现在显式触发的模板页面中,也可在聊天中发现,因为两者都读取同一个索引。使用已注册工作区时,先要求浏览/选择模板,再在[条件触发的 Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation) 中选择它。项目范围或精确交接则提供工作区 root,例如 `用这个模板:projects/<name>/`;未注册 root 仍标记为 `explicit`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要出现在 library 列表中时才执行注册。
选择 Deck/Layout 模板后,Strategist 会自动生成页面/原型应用计划:可以使用全套或子集,重复或重排原型,并按内容需要重组。`strict` / `adaptive` 只作为内部导出值,不再出现在确认选项中。
@@ -293,7 +292,7 @@ Brand 与 Style 只写 `templates/design_spec.md`(Brand 可带真实身份资
- **全局库范围(`library`,默认)**把工作区写入 `skills/ppt-master/templates/<kind>/<id>/`,并完成全局注册。
- **项目范围(`project`)**把同一份可移植工作区写入 `projects/<name>/`,并跳过注册。
-项目范围不是私有或缩减格式。Step 3 可以直接接收任一工作区根目录。Brand/Layout/Deck 迁移 `templates/` 及真实的包自有 `images/`、`icons/`;Style 只迁移 `templates/design_spec.md`,并忽略无关的项目脚手架。迁入全局库后,再按对应 kind 执行注册,让发现索引反映新位置。
+项目范围不是私有或缩减格式。提供任一精确工作区根目录都会直接触发 Step 3。Brand/Layout/Deck 迁移 `templates/` 及真实的包自有 `images/`、`icons/`;Style 只迁移 `templates/design_spec.md`,并忽略无关的项目脚手架。迁入全局库后,再按对应 kind 执行注册,让发现索引反映新位置。
---
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index e8e9c22b..cc469869 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -34,9 +34,9 @@ package postflight as the default profile, but it does not create `svg_final/`.
| `analysis/page-context/P<NN>.usage.json` | Derived optional context telemetry | Measured on-demand page-context size plus hashes of owning inputs/references | `page-context --record-usage` deterministically replaces only the invoked page's snapshot; `page-context-report` summarizes existing snapshots. Telemetry may be partial. Use token data to evaluate context cost, never as content or an execution contract. |
| `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Default Step 5 or Quick Generate resource preparation writes here; `analysis/image_analysis.csv` derives from current contents |
| `images/image_prompts.json`, `image_queries.json`, `image_sources.json`, `formula_manifest.json` | Conditional resource contracts | AI/web/formula execution status and provenance | Create only for a triggered path, including Quick. They guide preparation/attribution, never page design. |
-| `icons/` | Prepared project icon pool | Bundled icons copied by `icon_sync.py` plus user-provided, template, imported, or custom icon SVGs | SVG authoring may use any icon in this project-local pool; `spec_lock.icons.inventory` records the default plan's bundled choices rather than an exhaustive whitelist. Exporter global fallback is legacy compatibility only. |
-| `${SKILL_DIR}/templates/{brands,styles,layouts,decks}/*_index.json` | Library discovery indexes | The complete registered option source for Step-3 UI selection and chat listing | Read the four index files only; never scan kind directories to add options. Derive a library root from kind + entry id. Exact unregistered roots remain explicit inputs and never enter an index implicitly. |
-| `templates/` | Project template reference | Default Step 3 or Quick direct-input installed/fused specs, optional Layout/Deck SVG prototypes, and non-image assets | Default template-aware Strategist work from Stage 2 onward, Quick's current agent before direct authoring, and every later role read this project-local state only, never the library/external installation root. The active planner reads every installed template Design Spec and an actual SVG roster only for Layout/Deck; Brand and Style are intentionally roster-free. Continuous Executor reuses that context; fresh Executor reads the Design Spec once and each selected complete SVG, when any, only before first use or after its SHA changes. |
+| `icons/` | Prepared project icon pool | Bundled icons copied by `icon_sync.py` plus user-provided, template, imported, or custom icon SVGs | SVG authoring may choose any icon in this project-local pool per page; `spec_lock.icons.inventory` indexes the default plan's curated synced bundled pool rather than assigning page usage or defining an exhaustive whitelist. Exporter global fallback is legacy compatibility only. |
+| `${SKILL_DIR}/templates/{brands,styles,layouts,decks}/*_index.json` | Library discovery indexes | The complete registered option source for triggered Step-3 UI selection and chat listing | Read the four index files only when template discovery/selection is explicit; never scan kind directories to add options. Derive a library root from kind + entry id. Exact unregistered roots remain explicit inputs and never enter an index implicitly. |
+| `templates/` | Project template reference | Triggered Default Step 3 or Quick direct-input installed/fused specs, optional Layout/Deck SVG prototypes, and non-image assets | Default template-aware Strategist work from Stage 2 onward, Quick's current agent before direct authoring, and every later role read this project-local state only, never the library/external installation root. The active planner reads every installed template Design Spec and an actual SVG roster only for Layout/Deck; Brand and Style are intentionally roster-free. Continuous Executor reuses that context; fresh Executor reads the Design Spec once and each selected complete SVG, when any, only before first use or after its SHA changes. |
| `templates/template_execution_manifest.json` (`v1`) + `templates/template_execution/*.text-slots.json` (`v2-min`) | Derived template index | Compact prototype/source-import summary plus per-prototype text-slot diagnostics; the sidecar integrity hash is tool-only | Materialization may publish these deterministic records, but page-context does not inject or require them and models do not read them during page authoring. The complete prototype SVG is the sole visual/template authority; never author from either JSON artifact. |
| `<import_workspace>/svg/` | Imported native-payload backing | Complete PPTX-derived metadata, hidden carriers, fallback evidence, and source structure | Keep immutable; create-template materialization may resolve a validated source ref against these files, but models do not edit or bulk-read them |
| `<import_workspace>/svg-flat/` | Optional complete-page verification backing | Self-contained visual composition generated only by explicit `--inheritance-mode both` | Keep immutable when requested; never use as authoring or materialization input |
@@ -45,8 +45,8 @@ package postflight as the default profile, but it does not create `svg_final/`.
| `<import_workspace>/authoring-svg/authoring_manifest.json` | Tool-only authoring provenance contract | Per-document source/authoring hashes and document-local source-ref paths | Generated atomically with the IR; materialization validates it before reusing native payload; never load it into model context or duplicate raw payload here |
| `<import_workspace>/authoring-svg-flat/` | Optional complete-page verification IR | Self-contained page composition view with its own summary and provenance manifest | Generate only from an explicitly requested `svg-flat/`; use to verify composition, while layered `authoring-svg/` remains the canonical editable source |
| `<import_workspace>/icons/imported/` | Imported vector pool | One canonical copy of every factored vector subtree | Authoring SVGs reference `data-icon="imported/<name>"`; vector inventories retain source refs so expansion re-establishes IR identity |
-| `confirm_ui/template_options.json`, `template_selection.json`, `template_handoff.json` | Default Step-3 template phase | Agent-authored input, user-confirmed exact selection, and agent-authored installation/free-design completion receipt | Default only: the server builds library candidates from the four indexes and binds selection/handoff hashes. Stage 1 is exposed only after the bound handoff and a fresh recommendation. Template choices never enter `result.json`. Quick creates none of these files. |
-| `confirm_ui/recommendations.stage1.json`, `.stage2.json`, `.stage3.json` | Confirmation proposals | One Strategist-authored payload per communication/solution/production stage | Create these only after Step-3 template selection and installation closes. Template choice is not a Stage-1 field; Stage 2 may carry only `template_application`, which decides how to use the installed project-local template. Confirm UI selects the active file from `result.json`. The active, unconfirmed stage may be overwritten when the user requests a new recommendation; normal progression writes the next stage file and leaves confirmed earlier stages intact. Legacy `recommendations.json` is read only when no stage-specific file exists. |
+| `confirm_ui/template_options.json`, `template_selection.json`, `template_handoff.json` | Conditional Default Step-3 template phase | Agent-authored input, user-confirmed exact selection, and agent-authored installation/free-design completion receipt | Create only for explicit template discovery/selection, an exact root, or a current Create Template handoff. The server builds library candidates from the four indexes and binds selection/handoff hashes. Stage 1 is exposed only after the bound handoff and a fresh recommendation. Ordinary free design starts Stage 1 without these files; template choices never enter `result.json`; Quick creates none. |
+| `confirm_ui/recommendations.stage1.json`, `.stage2.json` | Confirmation proposals | Strategist-authored communication contract, then complete final solution plus production mechanics | Stage 1 may be created directly for ordinary free design or after a triggered template handoff. `template_application` decides only how to use installed project-local state. Confirm UI selects the active file from `result.json`. The active unconfirmed stage may be overwritten when the user requests a new recommendation; normal progression writes Stage 2 and leaves confirmed Stage 1 intact. |
| `confirm_ui/result.json` | Confirmation result | Persisted user-confirmed input evidence | Generate Step 4 reads the final object once into active context; Strategist consumes it completely into `design_spec.md`. Normal downstream work does not reopen it; fresh recovery may read it once when no retained final state exists. |
| `svg_output/` | Page-design author source | Main-agent handwritten SVG pages containing the complete visible design | Quality checker and native PPTX export read this as the canonical visual/page-layout source; templates and locks do not add missing visible objects at export |
| `notes/total.md` | Conditional speaker-note source | Complete notes before splitting | Step 6 writes only when the effective Speaker Notes outcome is enabled; Step 7.1 splits |
@@ -56,7 +56,7 @@ package postflight as the default profile, but it does not create `svg_final/`.
| `validation/<output_stem>.report.json` | Published-package audit | PPTX package/resource postflight status, part counts, and quality-gate linkage | Both Generate profiles write it and emit `[POSTFLIGHT]` after package validation. |
| `exports/` | Delivery artifacts | Native DrawingML PPTX and explicit native-object/narration variants | Default Step 7.3 or Quick direct export writes final deliverables from `svg_output/`. |
| `backup/<timestamp>/svg_output/` | Default-path frozen author-source archive | Re-export source without re-running LLM | Both Generate profiles write a snapshot for default-path exports; explicit `-o/--output` skips it. |
-| `animations.json` | Optional animation config | Page-transition and object-animation sidecar | Existing files activate intent resolution: Stage 3 `false` preserves, explicit objects-off exports `-a none`, and all-motion-off bypasses with `--no-animations`. Creation requires explicit instruction or enabled outcome; §IX advice never activates it |
+| `animations.json` | Optional animation config | Page-transition and object-animation sidecar | Existing files activate intent resolution: final Stage-2 `false` preserves, explicit objects-off exports `-a none`, and all-motion-off bypasses with `--no-animations`. Creation requires explicit instruction or enabled outcome; §IX advice never activates it |
---
@@ -81,8 +81,8 @@ package postflight as the default profile, but it does not create `svg_final/`.
| Export source | The only supported generated-PPTX route reads `svg_output/` through the project SVG-to-DrawingML converter. A diagnostic `-s final` override does not change ownership or create a supported release route. |
| Shape-conversion boundary | PowerPoint's manual Convert-to-Shape operation on `svg_final/` is outside the project compatibility contract. |
| Confirmation | Final UI/chat confirmation overrides recommendations and is consumed once into `design_spec.md`. Enabled refinement applies arbitrary revisions there and requires approval; only then may active-decision fidelity release lock authoring. |
-| Template selection | Default Step 3 confirms free design or exact roots before Stage 1; library candidates come only from the four `*_index.json` files, and unregistered roots require explicit input. Quick never enters that phase: at most one exact root per kind supplied for the run goes directly through the same validator/installer, while no exact root means free design. Every applied selection becomes one project-local `templates/` state before Default Stage 2 or Quick authoring reads it. |
-| Proactive production outcomes | Resolve notes/animation/narration from explicit instruction → Stage 3 → defaults, then persist outcomes/provenance only in Design Spec §I. Explicit notes-off/audio-on applies Generate's dependency gate; Stage 3 animation `false` does not suppress a sidecar. |
+| Template selection | Default Step 3 exists only for explicit template discovery/selection, an exact root, or a current Create Template handoff; ordinary free design starts Stage 1 directly. Triggered library candidates come only from the four `*_index.json` files, and unregistered roots require explicit input. Quick never enters that phase: at most one exact root per kind supplied for the run goes directly through the same validator/installer, while no exact root means free design. Every applied selection becomes one project-local `templates/` state before Default Stage 2 or Quick authoring reads it. |
+| Proactive production outcomes | Resolve notes/animation/narration from explicit instruction → final Stage 2 → defaults, then persist outcomes/provenance only in Design Spec §I. Explicit notes-off/audio-on applies Generate's dependency gate; final Stage-2 animation `false` does not suppress a sidecar. |
**Forbidden - mixed ownership**: Do not copy chart values from Markdown into `analysis/` by hand, do not edit `svg_final/` as the source of a fix, do not edit imported lossless SVGs instead of their authoring IR, and do not treat `design_spec.md` prose as a replacement for `spec_lock.md`.
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 15c616dc..bb68ea37 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -13,7 +13,7 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
| Any `Status: Sourced` web image | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` |
| Effective Speaker Notes outcome is enabled after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |
-> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). Technical constraints are in [`shared-standards-core.md`](./shared-standards-core.md).
+> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). [`shared-standards-core.md`](./shared-standards-core.md) supplies the technical boundary plus the fallback visual-quality and leading defaults when those authorities are silent.
**Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content.
@@ -65,7 +65,7 @@ Consume stdout directly; stop on non-zero exit. The projection is derived, not a
**Hard rule — exact page roster**: `design_spec.md §IX` is the ordered queue: one final slide per entry, with the same id/order. The UI range no longer applies. Never add, drop, merge, split, or reorder; repair/reconfirm the Design Spec first.
-**Hard rule — binding selection vs realization**: use Strategist-selected semantic content, resources/paths, chart keys, template/layout routing keys, core fonts, palette anchors, icons, and crop boundaries. Adapt realization, never those binding selections, except sparse local font/color garnish allowed below. A §VIII preferred image pattern is not a template/layout routing key; [`executor-image.md`](./executor-image.md) owns its realization freedom. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Binding selection changes require upstream repair.
+**Hard rule — binding selection vs realization**: use Strategist-selected semantic content, resources/paths, chart keys, template/layout routing keys, core fonts, palette anchors, icon-library/stroke anchors, and crop boundaries. Adapt realization—including which prepared project-local icon, if any, best serves each page—without changing those binding selections, except sparse local font/color garnish allowed below. A §VIII preferred image pattern is not a template/layout routing key; [`executor-image.md`](./executor-image.md) owns its realization freedom. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Binding selection changes require upstream repair.
**Hard rule — content vs expression**: `design_spec.md §IX` owns each page's semantic content and supplies complete preferred wording and block texture; those expression choices are not verbatim requirements unless explicitly literal. Executor may paraphrase, condense repetition, regroup or reorder material within the same page, and switch among prose, bullets, keywords, labels, or visual annotation when fit or readability benefits. The result must remain information-equivalent: preserve the `Core message`, `Audience move`, and every substantive claim, fact, data value, proper name, qualifier or caveat, relationship, key argument or evidence, and literal requirement. Never add a claim, move content across pages, or drop information to make the layout fit; return an unfit or underspecified block for Design Spec repair.
@@ -87,7 +87,7 @@ Apply the content-vs-expression contract above within the selected reading mode.
**Default — authored texture (may override when information-equivalent)**: start from each `design_spec.md §IX Content` block's written texture because it is the Strategist's recommended expression. Keep prose when its continuity carries causal, argumentative, narrative, qualification, or emphasis relationships; use bullets or keywords when the material is genuinely parallel or ordered, or another information-equivalent structure is clearer. Never convert solely because a list is easier to lay out or an inherited template exposes a list slot.
-- **Hard rule — one paragraph, one text frame**: use one `<text>` per prose paragraph, never sibling `<text>` elements for its visual lines. Keep the first authored line as direct text; later lines use direct `<tspan>` children that repeat parent `x`, retain effective font size, and use positive relative `dy`. An all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` enables reflow. Choose positive line spacing for the typeface, size, density, and reading distance; no fixed ratio overrides legibility or the selected style.
+- **Hard rule — one paragraph, one text frame**: use one `<text>` per prose paragraph, never sibling `<text>` elements for its visual lines. Keep the first authored line as direct text; later lines use direct `<tspan>` children that repeat parent `x`, retain effective font size, and use positive relative `dy`. An all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` enables reflow. Start from the shared leading ranges in [`shared-standards-core.md`](./shared-standards-core.md) §4.2, then adjust for the typeface, reading distance, explicit user/template requirements, and locked style.
- **Template precedence**: an inherited slot never overrides the content relationship. If faithful expression needs prose, widen or reflow the container, or drop that card; never convert solely to fill a list slot.
- **Mode precedence**: the locked mode shapes voice / register, not §IX's authored titles or page order. When a `§IX` title is a user-authored topic label, keep it — do not upgrade it to an assertion just because the mode (e.g. `pyramid`) favors them; mode title-tendencies apply only to AI-drafted titles.
@@ -99,7 +99,7 @@ Apply the content-vs-expression contract above within the selected reading mode.
**Execution anchors and contextual values**:
-- Icons may use any SVG already prepared under `<project_path>/icons/`. `icons.library` records the Strategist's primary bundled style choice and `icons.inventory` records its planned selection; neither is an execution whitelist over project-local assets.
+- Icons may use any SVG already prepared under `<project_path>/icons/`. `icons.library` records the Strategist's primary bundled style choice and `icons.inventory` indexes its curated synced pool; neither assigns icons to pages or limits other project-local assets.
- Core color roles retain their meaning. Derive tints, shades, alpha, gradients, and effects; preserve natural asset colors; and use sparse page-local accents for differentiation/ornament. They must not become a competing or recurring palette.
- Resolve structural families by role: exact `<role>_family` first, then `title_family` for title roles or `body_family` for other unoverridden roles, then legacy `font_family`. Never flatten declared role overrides. A sparse export-safe accent family may style short non-structural display/ornament only—never title/body/data/annotation. Recurrence requires upstream selection.
- Font sizes use the named `typography` role values as deck-wide anchors. Map every structural text item to a declared role before drawing; never inherit a template placeholder size. Start from the anchor, then use composition and content fit to adjust that occurrence by at most `±2`px. Keep same-page peers consistent and preserve the role hierarchy; bounded adjustment does not create a new role.
@@ -233,7 +233,7 @@ Strategist chooses at most one primary bundled stylistic library and may select
> **Prepared-project boundary.** Any SVG already under `<project_path>/icons/<lib>/` is valid execution material, whether selected from a bundled library or supplied by the user, a template, or an import workflow. New authoring must resolve there. The global fallback in `finalize_svg.py embed-icons` is legacy compatibility, not permission for Executor to discover or use an unprepared global icon.
-> **Icon identifiers are case-sensitive filenames.** Every `data-icon` value must use the exact project-local relative basename (`tabler-outline/award`, never `tabler-outline/Award`). Strategist records its planned bundled choices in `spec_lock.md`; Executor need not add other already-prepared project-local icons to that inventory. Custom identifiers preserve the custom file's exact case; the pipeline never silently lowercases names.
+> **Icon identifiers are case-sensitive filenames.** Every `data-icon` value must use the exact project-local relative basename (`tabler-outline/award`, never `tabler-outline/Award`). Strategist records its curated bundled pool in `spec_lock.md`; Executor need not add other already-prepared project-local icons to that inventory. Custom identifiers preserve the custom file's exact case; the pipeline never silently lowercases names.
**Built-in icons — Placeholder method (recommended)**:
@@ -271,6 +271,8 @@ Strategist chooses at most one primary bundled stylistic library and may select
test -f "<project_path>/icons/<lib>/<name>.svg"
```
+**Default — purposeful icon use**: choose prepared icons per page when they compress a label, distinguish parallel categories, clarify a process / KPI / state, or improve navigation and visual rhythm. Omit them when imagery, charts, or typography already carry the meaning. There is no coverage quota, and the prepared pool need not be exhausted.
+
**Missing project-local icon** → return to Strategist's preparation / `icon_sync.py` gate. Do not search the global library, select an alternative, or copy a candidate in Executor.
**Hard rule — prepared assets**: Executor may freely combine project-local icons, regardless of namespace or style. It may not acquire a new icon or treat a globally resolvable file as prepared material.
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index 2aedbd2a..028a8f89 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -1,15 +1,17 @@
# Shared SVG Core Standards
-Mandatory reference for every route that authors or regenerates slide visuals through SVG. It owns XML validity, the closed generated-authoring surface, basic converter compatibility, page closure, semantic grouping, and shared fidelity vocabulary.
+Mandatory reference for every route that authors or regenerates slide visuals through SVG. It owns XML validity, the closed generated-authoring surface, basic converter compatibility, page closure, semantic grouping, shared visual-quality defaults, and fidelity vocabulary.
**Conditional module routing**:
| Trigger | Load |
|---|---|
-| Noncanonical/alpha paint, advanced line or text treatment, gradient/filter/effect, transform, freeform/radial geometry, or constructed style | [`svg-effects.md`](./svg-effects.md) |
+| Default or Quick Generate; otherwise noncanonical/alpha paint, advanced line or text treatment, gradient/filter/effect, transform, freeform/radial geometry, or constructed style | [`svg-effects.md`](./svg-effects.md) |
| A page will use a preset pattern fill or evaluate native chart/table replacement | [`native-data-interface.md`](./native-data-interface.md) before deciding eligibility or emitting metadata |
| `pptx_structure.mode: structured` | [`pptx-structure-interface.md`](./pptx-structure-interface.md) |
+**Default — shared aesthetic baseline (may be overridden by explicit user, template / brand, or locked visual-style requirements)**: Required / Forbidden technical contracts remain absolute. Within that valid surface, establish quality through clear hierarchy, typography and leading, alignment, negative space, purposeful imagery / icons, and restrained repetition before decoration. Silence at a higher authority does not disable these defaults. Default and Quick Generate also run the already-loaded [`svg-effects.md`](./svg-effects.md) §6.1 Visual Job Router before completing each page; apply a compatible technique only for a diagnosed visual job.
+
**Fidelity labels**:
| Label | Meaning |
@@ -571,7 +573,7 @@ Semantic markers are minimal compiler hints. Flat pages declare one root `data-p
[`../templates/icons/README.md`](../templates/icons/README.md).
- **Local reuse**: ordinary same-document `<use>` follows §1.3.
-### 4.2 Conditional Editability and Package Promotion
+### 4.2 Editability, Package Promotion, and Text Leading
These forms are needed only when the stated PPT behavior matters:
@@ -583,6 +585,8 @@ These forms are needed only when the stated PPT behavior matters:
| Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`. Keep every represented object Slide-local; export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Do not author Master/Layout identities, layers, or placeholder slots. Quick-generate uses the same flat object ownership but converter-default theme scaffolding because no lock exists. |
| Reusable template-based PowerPoint Layout | Select one complete authoring SVG per page in `page_layouts`, declare each unique Master/Layout definition once, and assign pages through `page_pptx_layouts`. Strict preserves the prototype contract; adaptive retains its Master and uses a current or new Layout key already declared and assigned by Strategist. Construction cannot extend or mutate that mapping downstream. Non-mirror skin follows `spec_lock`. |
+**Default — leading by role and density (may be overridden for user, template, typeface, legibility, or locked visual-style fit)**: For direct positioned `<tspan>` rows, start multiline titles around `1.2–1.3 × font-size`, dense / small body around `1.4–1.5 ×`, ordinary body around `1.5–1.6 ×`, and large / sparse / breathing body around `1.6–2.0 ×`. These are starting ranges, not checker quotas; display headlines may be tighter when the selected style calls for it. Author the spacing as positive relative `dy`, not CSS/SVG `line-height`, which has no registered DrawingML mapping.
+
**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.
### 4.3 Element Grouping (Mandatory)
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index b93747eb..409813be 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -1,12 +1,12 @@
# Shared Technical Standards
-Compatibility router for the split SVG technical specifications. Runtime routes load the core plus only the modules triggered by the current lock and page features.
+Compatibility router for the split SVG specifications. Runtime routes load the core plus their route-required and feature-triggered modules.
| Scope | Authority | Trigger |
|---|---|---|
-| XML/SVG foundation, compatibility, page closure, grouping | [`shared-standards-core.md`](./shared-standards-core.md) | Always for SVG authoring |
-| Advanced effects and geometry | [`svg-effects.md`](./svg-effects.md) | Corresponding effect or geometry is used |
+| XML/SVG foundation, shared visual-quality defaults, page closure, grouping | [`shared-standards-core.md`](./shared-standards-core.md) | Always for SVG authoring |
+| Advanced effects and geometry | [`svg-effects.md`](./svg-effects.md) | Always for Default / Quick Generate; otherwise when the corresponding effect or geometry is used |
| Preset patterns and native chart/table metadata | [`native-data-interface.md`](./native-data-interface.md) | Corresponding native-data interface is used |
| Master/Layout/placeholder structure | [`pptx-structure-interface.md`](./pptx-structure-interface.md) | `pptx_structure.mode: structured` |
-**Hard rule**: This file is a routing pointer, not a combined runtime authority. Do not load every conditional module by default.
+**Hard rule**: This file is a routing pointer, not a combined runtime authority. Follow the selected route's required modules; do not load every remaining conditional module by default.
diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.md
index 38d6b555..8b726bcb 100644
--- a/skills/ppt-master/references/strategist-image.md
+++ b/skills/ppt-master/references/strategist-image.md
@@ -16,7 +16,7 @@ For illustration, apply this precedence: confirmed `none` → explicit user inte
**Context-first understanding for provided assets**: Do not visually scan `images/`. First infer identity, role, and crop / focus needs from source position and surrounding prose, captions / alt / titles, filename, user notes / confirmed `image_notes`, existing resource records, and CSV geometry. Inspect only one specific image when a remaining ambiguity would change selection, factual identity, page role, crop safety, or focal placement. Never inspect for inspiration, bulk-open the folder, or infer external facts / provenance from pixels. Record the result in §VIII. Leave an optional unresolved asset unused; route an unresolved must-use asset through failure recovery.
-**Default — one coherent sheet for compatible same-family spots (may override when aspect, detail, quality, or semantic needs differ)**: prefer one Illustration Sheet when several AI-generated spots can share a useful cell shape and production treatment; generate them independently when forcing one sheet would weaken a planned element. When a sheet is chosen, plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element; only slice rows enter `spec_lock.md images`. State the intended placement shape family in the sheet reference and use separate sheets for incompatible shapes. [`image-generator.md`](./image-generator.md) §4.3 owns grid, ratio, slicing, and execution details. Stage 3 chooses the AI execution path under `image-generator.md` §7; do not pre-empt or re-pick it here.
+**Default — one coherent sheet for compatible same-family spots (may override when aspect, detail, quality, or semantic needs differ)**: prefer one Illustration Sheet when several AI-generated spots can share a useful cell shape and production treatment; generate them independently when forcing one sheet would weaken a planned element. When a sheet is chosen, plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element; only slice rows enter `spec_lock.md images`. State the intended placement shape family in the sheet reference and use separate sheets for incompatible shapes. [`image-generator.md`](./image-generator.md) §4.3 owns grid, ratio, slicing, and execution details. Final Stage 2 chooses the AI execution path under `image-generator.md` §7; do not pre-empt or re-pick it here.
## 2. AI Image Strategy — propose only for recommended `ai`; lock any confirmed `ai`
@@ -30,7 +30,7 @@ For specialized or regulated paper-figure subjects, preserve the prompt depth re
## 3. Formula Asset Policy
-Formula rendering is a conditional choice surfaced in Stage 3 production confirmation. Recommend one policy and let the user confirm or override it:
+Formula rendering is a conditional choice surfaced in final Stage 2 production confirmation. Recommend one policy and let the user confirm or override it:
| Policy | Behavior | Use |
|---|---|---|
diff --git a/skills/ppt-master/references/strategist-template.md b/skills/ppt-master/references/strategist-template.md
index cb81e0e1..39afba00 100644
--- a/skills/ppt-master/references/strategist-template.md
+++ b/skills/ppt-master/references/strategist-template.md
@@ -50,7 +50,7 @@ Write only the derived values to `spec_lock.md pptx_structure`; omit `template_a
**Mandatory — natural-language Stage-2 plan**: For Layout/Deck, summarize which prototypes are used/skipped/repeated/reordered, what stays literal, and what may be replaced or reorganized. For Brand/Style, summarize the installed identity or Direction / method constraints and state that pages remain freely composed unless another workspace supplies structure. Write the result to top-level `template_application.value` in `recommendations.stage2.json`; omit it without an active template. After Stage 2, re-read the confirmed `result.json` value (or exact chat answer), never the initial recommendation. Blank returns the decision to Strategist. Persist the effective plan on one line as `- **Template Application**: <prose>` in `design_spec.md §I`, then derive internal reuse/adherence values and mappings; never copy the prose to `spec_lock.md`. Do not add a questionnaire, internal controls, or fixed template-use options.
-**Three-stage boundary**: An installed template changes the content of Stage 2, never the confirmation sequence. Run Stage 1 → Stage 2 → Stage 3 in order in both Confirm UI and chat fallback; do not skip a stage or treat template inspection as user confirmation. On browser timeout, return to the same stage in chat.
+**Two-stage boundary**: An installed template changes the content of final Stage 2, never the confirmation sequence. Run Stage 1 → final Stage 2 in order in both Confirm UI and chat fallback; do not skip a stage or treat template inspection as user confirmation. On browser timeout, return to the same stage in chat.
---
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 4b0f4f02..40724f49 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -8,7 +8,7 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
| Previous Step | Current | Next Step |
|--------------|---------|-----------|
-| Project creation + independent Step-3 template selection/installation complete | **Strategist**: Stage 1–3 confirmation + Design Spec | Image_Generator or Executor |
+| Project creation + any triggered Step-3 template selection/installation complete | **Strategist**: Stage 1–2 confirmation + Design Spec | Image_Generator or Executor |
---
@@ -24,27 +24,26 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
⛔ **BLOCKING**: After the read, present professional recommendations for the confirmation fields below and wait for explicit user confirmation.
-**Three-stage confirmation (the default Confirm UI flow; chat mirrors it).**
-Generate Step 3 has already confirmed free design or installed the selected
-template into this project. That independent selection is not a Stage-1 field
-and must not be reopened here. The sequence is scene first, complete solution
-second, production third:
+**Two-stage confirmation (the default Confirm UI flow; chat mirrors it).**
+Generate Step 3 runs only when explicit template discovery / selection or an
+exact workspace root triggers it. Any resulting selection is not a Stage-1
+field and must not be reopened here. The sequence is communication first, then
+one complete solution + production gate:
| Stage | Items | Role |
|---|---|---|
| **1 — communication contract** | `primary_language` · `c` audience · open-ended communication intent · audience outcome · core message / delivery context (primary + optional secondary) / artifact afterlife · `content_divergence` (all prose fields may be blank) · `a` canvas | confirmed first |
-| **2 — complete deck solution** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering · conditional natural-language template application | derived from the confirmed contract; internal template exporter modes remain hidden |
-| **3 — resources / production** (authored once from the user's *actual* Stage 1 + Stage 2) | formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle · proactive speaker notes / custom animations / narration audio | derived from the confirmed solution |
+| **2 — final solution + production** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering · conditional natural-language template application · formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle · proactive speaker notes / custom animations / narration audio | derived as one coherent plan from the confirmed contract; internal template exporter modes remain hidden |
-Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, image direction, and how the already installed template should be used. It never chooses or installs a template. Inspect only the project-local template spec/prototypes, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Stage 3 covers production. Its proactive defaults are speaker notes `true`, custom animations `false`, and narration audio `false`; a prior explicit user instruction overrides the matching recommendation, and effective narration audio requires effective speaker notes. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
+Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, image direction, production mechanics, and how any installed template should be used. It never chooses or installs a template. Inspect only project-local template spec/prototypes, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Proactive defaults are speaker notes `true`, custom animations `false`, and narration audio `false`; a prior explicit user instruction overrides the matching recommendation, and effective narration audio requires effective speaker notes. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
-**Hard rule — Stage-1 source boundary**: Build Stage 1 only from the current user request, source facts, conversation constraints, and project-initialization state. Ignore the selected template roots, installed/fused template state, template assets/prototypes, and template-owned canvas. Do not load or apply [`strategist-template.md`](./strategist-template.md) until the confirmed Stage-1 contract is available for Stage 2. Early installation is storage preparation, not planning evidence for Stage 1.
+**Hard rule — Stage-1 source boundary**: Build Stage 1 only from the current user request, source facts, conversation constraints, and project-initialization state. When Step 3 ran, ignore the selected roots, installed/fused template state, template assets/prototypes, and template-owned canvas. Do not load or apply [`strategist-template.md`](./strategist-template.md) until the confirmed Stage-1 contract is available for Stage 2. Early installation is storage preparation, not planning evidence for Stage 1.
-> **Execution discipline**: Step 3 template selection was the preceding independent BLOCKING checkpoint. This is the last always-on checkpoint. After confirmation, proceed without another pause unless spec refinement is enabled.
+> **Execution discipline**: A triggered Step 3 template selection is an earlier independent BLOCKING checkpoint; ordinary free design skips it. Stage 1 and final Stage 2 are the always-on Strategist checkpoints. After final confirmation, proceed without another pause unless spec refinement is enabled.
>
> **One opt-in exception**: present the refinement line with the split-mode note ([`generate-pptx.md`](../workflows/generate-pptx.md) Step 4). Only explicit opt-in runs [`refine-spec`](../workflows/stages/refine-spec.md): write the Design Spec once, pass Gate 1, then stop before the lock for unrestricted chat revision. Never enter it unprompted.
-> **Default presentation surface — Confirm UI.** Before Step 3, apply [`confirm_ui.md`](../scripts/docs/confirm_ui.md)'s sticky per-run surface decision; its explicit chat branch skips every UI command, and a chat selection after UI launch follows its in-run switch procedure. Chat-question tools alone do not select a branch. The UI branch closes template selection/installation before it exposes Stage 1. Then use `<project>/confirm_ui/recommendations.stage1.json`, `.stage2.json`, and `.stage3.json`; replace only the active unconfirmed stage, preserve confirmed files, and print the URL plus Stage-1 summary/fallback without treating that handoff as confirmation. Stage 1 writes canonical BCP-47 `primary_language` apart from UI `lang`; Strategist projects it through Design Spec §I to lock communication. Stage 2 carries ≥3 safe / shifted / bold `design_directions`, each bundling visual style, a six-role HEX palette, primary-language heading/body typography plus an English companion only for non-English decks, icons, and conditional image rendering. Step 4 retains final confirmation from the selected channel for Design Spec authoring. `confirm_ui.md` owns selection-surface and staged-confirmation lifecycle.
+> **Default presentation surface — Confirm UI.** Before the first actual confirmation phase, apply [`confirm_ui.md`](../scripts/docs/confirm_ui.md)'s sticky per-run surface decision; its explicit chat branch skips every UI command, and a chat selection after UI launch follows its in-run switch procedure. Chat-question tools alone do not select a branch. A triggered template phase closes selection/installation before Stage 1; ordinary free design opens Stage 1 directly. Then use `<project>/confirm_ui/recommendations.stage1.json` and `.stage2.json`; Stage 2 includes the complete solution and production recommendations. Replace only the active unconfirmed stage, preserve confirmed files, and print the URL plus Stage-1 summary/fallback without treating that handoff as confirmation. Stage 1 writes canonical BCP-47 `primary_language` apart from UI `lang`; Strategist projects it through Design Spec §I to lock communication. Stage 2 carries ≥3 safe / shifted / bold `design_directions`, each bundling visual style, a six-role HEX palette, primary-language heading/body typography plus an English companion only for non-English decks, icons, and conditional image rendering, plus the production fields above. Step 4 retains final confirmation from the selected channel for Design Spec authoring. `confirm_ui.md` owns selection-surface and staged-confirmation lifecycle.
**Confirmed-value semantics**: confirmation preserves both the value and the owning field's semantic type. Apply the type to the affected property, not automatically to the whole object:
@@ -56,7 +55,7 @@ Do not force communication intent into one catalog label; Stage 1 records compos
| Reference | Preserve the selected direction or role; adapt its realization to context. |
| Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. |
-**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, chart/layout keys, fonts, palette anchors, icons, and crop bans. Fact research may precede confirmation; AI/web/slice follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
+**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, chart/layout keys, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Fact research may precede confirmation; AI/web/slice follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement.
@@ -200,13 +199,13 @@ See [`../templates/icons/README.md`](../templates/icons/README.md) for the curre
> - This restriction governs Strategist selection from the bundled catalog, not the prepared project asset pool. User-provided, template-carried, imported, custom, and previously prepared files under `<project_path>/icons/` remain valid material regardless of namespace or visual style.
> 2. **Stroke weight lock (stroke-style libraries only)** — for stroke-based libraries (currently `tabler-outline`), pick one deck-wide value from `{1.5, 2, 3}` (default `2`). For heavier presence, switch library instead of going above `3`.
>
-> **After the Strategist confirmation stage is approved — when writing `design_spec.md` §VI / `spec_lock.md`**, then materialize the icon inventory:
+> **After the Strategist confirmation stage is approved — when writing `design_spec.md` §VI / `spec_lock.md`**, materialize a curated project icon pool:
>
-> 3. Enumerate only the concepts required by the confirmed outline.
+> 3. Choose a reusable set that covers recurring semantics and likely slide needs in the confirmed outline. Do not preassign individual icons to pages or add filler to meet a quota.
> 4. Put known basenames in the final batch. For an uncertain one, search the chosen style library — or `simple-icons` for a real brand mark — with `rg --files "skills/ppt-master/templates/icons/<library>" -g '*<keyword>*.svg'`; do not enumerate broad keyword families.
> 5. **Copy and validate in one batch** — run `python3 skills/ppt-master/scripts/icon_sync.py <project_path> <lib/name> [<lib/name> …]`. This both validates and materializes `<project>/icons/<lib>/`; skip per-file prechecks.
> 6. Keep each successful, case-sensitive `lib/name`: bundled basenames are lowercase (`tabler-outline/award`, never `tabler-outline/Award`); custom icons retain exact case.
-> 7. Record the successful bundled selection, its primary stylistic library, and any stroke-library `stroke_width` in `design_spec.md` §VI and `spec_lock.md icons`. Keep selected `simple-icons/*` ids in the same inventory without treating them as a second stylistic library. The inventory records the plan; it does not revoke other prepared project-local icons.
+> 7. Record each synced bundled path with broad suitable scenarios in `design_spec.md` §VI; record the same curated pool, its primary stylistic library, and any stroke-library `stroke_width` in `spec_lock.md icons`. Keep selected `simple-icons/*` ids in the same inventory without treating them as a second stylistic library. The pool is prepared optional material, not a page-use plan, coverage quota, or whitelist over other prepared project-local icons.
>
> 🚧 **GATE — missing icon = re-pick now**: on non-zero exit, search a missing generic concept only in the chosen stylistic library, or a missing real brand mark in `simple-icons`; re-pick and rerun the final batch until clean. Never carry a missing icon forward or switch among the four stylistic libraries to fill the gap.
>
@@ -366,7 +365,7 @@ creates a §VII row or lock field.
### Speaker Notes Requirements
Resolve the effective Speaker Notes outcome from the latest explicit user
-instruction, then Stage 3 `proactive_speaker_notes`, then compatibility default
+instruction, then final Stage 2 `proactive_speaker_notes`, then workflow default
`true`. Effective Narration Audio `enabled` requires Speaker Notes `enabled`
without changing the raw proactive preference; when that dependency changes the
notes outcome, its provenance names enabled Narration Audio.
@@ -465,11 +464,11 @@ After final confirmation, a newer explicit notes/animation/narration instruction
updates only affected §I outcomes/provenance and resumes their owner; never
reopen Confirm UI or add them to `spec_lock.md`. Before editing, apply
Generate's notes/audio dependency gate. Record animation provenance as
-Stage 3 `false`, explicit objects-off, or explicit all-motion-off; only the last
+final Stage 2 `false`, explicit objects-off, or explicit all-motion-off; only the last
includes transitions.
1. With Generate Step 4's retained complete final-confirmation state, read `${SKILL_DIR}/templates/design_spec_reference.md`.
-2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I, including one effective outcome plus provenance for Speaker Notes, Custom Animations, and Narration Audio. Resolve them from latest explicit user instruction → matching Stage 3 proactive value → compatibility default `enabled` / `disabled` / `disabled`; Narration Audio enabled requires Speaker Notes enabled without rewriting the raw proactive evidence, and a dependency-driven notes outcome records that provenance. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/chart patterns remain References unless promoted.
+2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I, including one effective outcome plus provenance for Speaker Notes, Custom Animations, and Narration Audio. Resolve them from latest explicit user instruction → matching final Stage 2 proactive value → workflow default `enabled` / `disabled` / `disabled`; Narration Audio enabled requires Speaker Notes enabled without rewriting the raw proactive evidence, and a dependency-driven notes outcome records that provenance. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/chart patterns remain References unless promoted.
3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before entering an enabled refine-spec review or authoring `spec_lock.md`.
4. If enabled, run [`refine-spec`](../workflows/stages/refine-spec.md) after Gate 1; edit only that Design Spec and create no lock before explicit approval.
5. Read `${SKILL_DIR}/templates/spec_lock_reference.md`; create the lock once or resynchronize stale derived state from the approved Design Spec and context. Retain identity/refinements and stable roles/routing; omit unnamed page-local values, do not reopen evidence, and make no new recommendation.
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index 9186f54d..48f3e710 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -1,14 +1,15 @@
# Confirm UI — Template Selection and Strategist Confirmation Page
> The interactive surface for [`generate-pptx`](../../workflows/generate-pptx.md)
-> Step 3 template selection and Step 4 Strategist confirmation. The independent
-> Step-3 phase first confirms free design or exact indexed/explicit template
-> roots; selected workspaces are applied into the project before Stage 1 exists.
-> Stage 1 then confirms the open communication brief, Stage 2 confirms a
-> coordinated deck solution and—when a template is installed—editable prose for
-> **how** to apply it, and Stage 3 confirms production mechanics. Template
-> selection persists separately in `template_selection.json`; Strategist values
-> accumulate into `result.json`. The chat path mirrors the same phase boundary.
+> Conditional Step 3 template selection and Step 4 Strategist confirmation.
+> Step 3 exists only for explicit template discovery/selection, an exact
+> workspace root, or a current Create Template handoff; selected workspaces are
+> applied before Stage 1. Ordinary free design starts at Stage 1. Stage 1
+> confirms the open communication brief, and final Stage 2 confirms the
+> coordinated deck solution plus production mechanics—including editable prose
+> for **how** to apply an installed template. When triggered, template selection
+> persists separately in `template_selection.json`; Strategist values accumulate
+> into `result.json`. The chat path mirrors the same active phase boundaries.
## Authority and Scope
@@ -18,7 +19,7 @@
| Template option/selection schema and page transport | This document |
| Step 4 gate and pipeline order | [`generate-pptx.md`](../../workflows/generate-pptx.md) |
| Confirm UI schema | This document |
-| Stage 1 / Stage 2 / Stage 3 field membership | This document |
+| Stage 1 / final Stage 2 field membership | This document |
| Server launch / wait / shutdown behavior | This document |
| Port and lock behavior | This document |
| Chat fallback equivalence | This document |
@@ -26,7 +27,7 @@
**Hard rule**: Keep detailed Confirm UI behavior here. The Generate route may summarize orchestration, but it should not duplicate the full JSON schema, catalog behavior, or launcher lifecycle.
-**Mandatory surface decision — before Step 3 or any UI command**: Resolve the most recent
+**Mandatory surface decision — before a triggered Step 3 or any UI command**: Resolve the most recent
explicit confirmation-surface instruction for this run before running
`--daemon` or `--wait-only`. Unrelated later messages do not reset the selected
branch. A new explicit selection may change it before launch; once confirmation
@@ -34,21 +35,22 @@ starts in chat or UI switches to chat, keep chat for the rest of this run.
| Most recent explicit surface instruction | Branch |
|---|---|
-| The user explicitly delegates confirmation | Present one complete delegated template choice plus three-stage summary in chat. Do not launch the page or fabricate either UI receipt. |
-| Otherwise, the user asks for or agrees to personally confirm in chat, or declines the confirmation page | Use chat for Step 3 selection and all three Strategist stages. Do not launch the page, run `--wait-only`, or require UI-authored receipts. |
+| The user explicitly delegates confirmation | Present one complete two-stage summary plus the template choice when Step 3 is triggered. Do not launch the page or fabricate UI receipts. |
+| Otherwise, the user asks for or agrees to personally confirm in chat, or declines the confirmation page | Use chat for both Strategist stages and any triggered Step-3 selection. Do not launch the page, run `--wait-only`, or require UI-authored receipts. |
| No explicit confirmation-surface instruction exists for this run | Use the page as the default. |
Interpret the instruction semantically: “confirm here”, “use the chat window”, or
“do not open the confirmation page” are sufficient; no literal `chat-only`
keyword is required. Invoking a chat-question tool by itself does not select the
-chat branch—the user's instruction does. Both branches preserve the independent
-template choice followed by the same three Strategist stages and confirmed-value
-semantics.
+chat branch—the user's instruction does. Both branches preserve the same
+two-stage Strategist confirmation and, when triggered, the independent template
+choice that precedes it.
**Fallback rule**: When no surface was selected before launch, the page is the
default. Use chat when the user answers either always-on handoff in chat, or
after launch failure/timeout and one re-check of the receipt for the active
-phase (`template_selection.json` for Step 3, `result.json` afterward). A
+phase (`template_selection.json` for a triggered Step 3, `result.json`
+otherwise). A
chat-question tool alone is not a launch failure. Preserve template selection
as an independent choice and keep Stage-1 prompts open-ended.
@@ -69,7 +71,7 @@ starts, or after it times out while the server remains live:
not call `--wait-only` again, recover the server, or relaunch the page during
this run.
-**Always-on Step-3 chat handoff**: After writing `template_options.json`, launch
+**Triggered Step-3 chat handoff**: After writing `template_options.json`, launch
the healthy daemon without `--wait`. Immediately post its actual URL plus a
compact localized summary: free design is available; the page has one
single-select dropdown for each registered kind plus one for supplied exact
@@ -80,15 +82,16 @@ with a localized line saying the user may select on the page or reply in chat
with free design / exact roots if the page did not open. Only then run
`--wait-only --wait-stage template`. Silence confirms nothing.
-**Always-on Stage-1 chat handoff**: After Step 3 confirms and any template is
-installed, write `recommendations.stage1.json`; the same live page changes from
-waiting state to Stage 1. Immediately post the existing actual URL plus one
+**Always-on Stage-1 chat handoff**: After a triggered Step 3 closes and any
+template is installed—or immediately for ordinary free design—write
+`recommendations.stage1.json`. Reuse the live Step-3 page when present;
+otherwise launch the page directly. Immediately post the actual URL plus one
compact, localized summary of the current Stage-1 recommendations: audience, communication intent,
audience outcome, core message, delivery context, artifact afterlife,
`content_divergence`, and canvas. Show a blank as “not specified” without
changing its value. End with an explicit localized line saying that, if the
page did not open or cannot be reached, the user may reply “continue with these
-recommendations” or revise the same items directly in chat; the same three-stage
+recommendations” or revise the same items directly in chat; the same two-stage
flow will continue. Only then run `--wait-only --wait-stage stage1`. A chat
reply to that handoff applies the in-run switch above without waiting for
timeout. The handoff is context, not confirmation, and silence confirms
@@ -100,27 +103,26 @@ the same items as open Stage-1 chat questions and wait for an explicit response.
The following launch and wait commands belong to the **UI branch only**:
```bash
-python3 scripts/confirm_ui/server.py <project_path> --daemon # launch Step 3; return for template chat handoff
+python3 scripts/confirm_ui/server.py <project_path> --daemon # launch triggered Step 3, or launch ordinary free-design Stage 1
python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage template # Step 3 selection
python3 scripts/confirm_ui/server.py <project_path> --complete-template-phase # after free-design closure / template install
python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1 # Stage 1
-python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage2 # Stage 2: wait for the direction handoff
-python3 scripts/confirm_ui/server.py <project_path> --wait-only # Stage 3: wait for the final result
+python3 scripts/confirm_ui/server.py <project_path> --wait-only # current final Stage 2
python3 scripts/confirm_ui/server.py <project_path> --daemon --port 5051
python3 scripts/confirm_ui/server.py <project_path> --no-browser
python3 scripts/confirm_ui/server.py <project_path> --timeout 0 # disable idle auto-shutdown
-python3 scripts/confirm_ui/server.py <project_path> --reset-template-phase # re-open Step 3 receipts only
+python3 scripts/confirm_ui/server.py <project_path> --reset-template-phase # clear prior Step-3 artifacts before a fresh UI run
python3 scripts/confirm_ui/server.py <project_path> --shutdown # Step 4 cleanup (idempotent)
```
- Without `--port`, binds the first free port from `127.0.0.1:5050`; the launch log prints the actual URL. `--port N` is exact and fails when unavailable. Auto-open is suppressed by `--no-browser`.
- In `--daemon` mode the launcher starts the child with browser opening suppressed, then accepts readiness only when `GET /api/health` identifies this confirm service, project, and child process. It opens the printed `http://127.0.0.1:<port>` URL only after that check.
- Confirm UI and live preview prefer the same memorable base port but keep separate processes and project-local locks (`.confirm_ui.lock` vs `live_preview/lock.json`). Normal Step 4 cleanup releases the confirm port before Step 6; concurrent projects may use different ports.
-- `--daemon` starts the Flask process in the background and returns after the health check. Generate first uses it without `--wait` for the Step-3 handoff; the same process then remains live across installation and all three Strategist stages. `--daemon --wait --wait-stage template` remains a combined compatibility form. The wait budget defaults to **590 s** (`--wait-timeout`); on timeout the detached server remains live, and the caller re-checks the active receipt once before chat fallback.
-- `--wait-only` attaches to the page opened by `--daemon` and blocks until the requested receipt. If it is already persisted, the command returns before recovery, so a fast submit between launch, chat handoff, and wait is not lost. Otherwise, if the recorded server died, it restarts on the recorded/default port. Use `template` for Step 3, `stage1` after installation and the communication handoff, `stage2` for the complete-solution handoff, and `final` for Stage 3. Strategist resume still derives its target from persisted `result.json`; template resume derives it from `template_selection.json`.
-- `--complete-template-phase` is agent-only. It validates the current selection and writes the bound `template_handoff.json`; template mode additionally requires project-local `templates/design_spec.md`. Run it before writing Stage 1. `--reset-template-phase` removes exactly `template_selection.json` and `template_handoff.json`; it does not alter options, Strategist files, installed template content, or `result.json`.
+- `--daemon` starts the Flask process in the background and returns after the health check. A triggered template run first uses it for the Step-3 handoff and keeps the same process live; ordinary free design launches it only after Stage-1 recommendations exist. The current Strategist flow then spans Stage 1 and final Stage 2. `--daemon --wait --wait-stage template` remains a combined form for the triggered phase. The wait budget defaults to **590 s** (`--wait-timeout`); on timeout the detached server remains live, and the caller re-checks the active receipt once before chat fallback.
+- `--wait-only` attaches to the page opened by `--daemon` and blocks until the requested receipt. If it is already persisted, the command returns before recovery, so a fast submit between launch, chat handoff, and wait is not lost. Otherwise, if the recorded server died, it restarts on the recorded/default port. Use `template` only for triggered Step 3, `stage1` for the communication contract, and the default/final wait for final Stage 2. Strategist resume derives its target from persisted `result.json`; template resume derives it from `template_selection.json`.
+- `--complete-template-phase` is agent-only. It validates the current selection and writes the bound `template_handoff.json`; template mode additionally requires project-local `templates/design_spec.md`. Run it before writing Stage 1. `--reset-template-phase` removes exactly `template_options.json`, `template_selection.json`, and `template_handoff.json`; it does not alter Strategist files, installed template content, or `result.json`.
- `--shutdown` stops a confirm server left running for this project and exits — **idempotent** (a no-op when nothing is running). Tries a graceful `/api/shutdown`, falls back to killing the recorded pid, then clears the lock. Generate Step 4 runs this on every path so the selected port is released before live preview starts.
-- Initial Step-3 launch requires valid `<project_path>/confirm_ui/template_options.json`. After template selection, the same service exposes Stage 1 only when a matching handoff exists and the Stage-1 recommendation is no older than that handoff. Compatibility launches without a template phase still require the recommendation file expected from `result.json`; `--shutdown` needs neither input.
+- Every fresh UI run starts with `--reset-template-phase`. A triggered Step-3 run then writes valid `<project_path>/confirm_ui/template_options.json`; ordinary free design leaves all three template-phase artifacts absent and launches from the current Stage-1 recommendation. After template selection, the same service exposes Stage 1 only when the selection is newer than those options, the matching handoff is newer than that selection, and the Stage-1 recommendation is newer than the handoff. `--shutdown` needs neither input.
- Per-project lock at `<project_path>/.confirm_ui.lock` — duplicate launches are refused; stale locks (dead pid) are overwritten.
- Idle auto-shutdown after 900 s by default; `/api/shutdown` exits gracefully and releases the lock.
- `/api/template-options` serves the server-built Step-3 catalog and `/api/template-confirm` accepts only current candidate keys, then writes the trusted receipt. `/api/recommendations` and `/api/confirm` own only the later Strategist stages and strip legacy `template_reuse_scope` / `template_adherence` fields. The completed template handoff is authoritative: `free_design` also strips a stray `template_application`, while `templates` exposes that editable natural-language field in Stage 2.
@@ -131,9 +133,9 @@ Dependency:
pip install flask
```
-## Step-3 template-selection contract
+## Conditional Step-3 template-selection contract
-Template selection is a separate pre-Strategist phase. Its files live under
+When triggered, template selection is a separate pre-Strategist phase. Its files live under
`<project_path>/confirm_ui/` but never enter `result.json`.
### Input — `template_options.json` (created before launch)
@@ -284,14 +286,14 @@ its file time is no earlier than the handoff.
## Field shapes
-The following fields belong to the Strategist stages after Step 3, not to the
+The following fields belong to the Strategist stages, not to any triggered
template-selection receipt.
- **Enumerable + custom** — canvas / icons retain blank manual inputs; mode / visual_style instead show a mandatory AI-authored proposal in full, initially unselected and editable after selection. Selected mode / style writes literal `custom` plus its behavior sibling.
- **Visual examples for hard-to-name choices** — the full-screen confirmation page loads real SVG page samples from `static/style_previews/` for `visual_style`, and renders real sample SVGs from `templates/icons` for `icons`. These thumbnails make style and icon-library choices visually comparable before the user locks them. Preview copy is fixed role text (big title / section title / body / points), not project content from recommendation files, so users compare visual treatment rather than copywriting. These previews are a confirmation aid only: they do not add fields to recommendation stage files or `result.json`, and they do not replace the later Step 6 live preview.
- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. A confirmed non-`none` set is the allowed acquisition-source boundary, not a requirement to use every selected source; only explicit `image_notes` wording can require a source, asset, or page role. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
- **Closed enumerable** — PPT reading mode (`delivery_purpose` compatibility key), formula policy / generation mode / refine spec, plus AI source only when image usage includes `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option.
-- **Proactive execution booleans** — Stage 3 carries top-level `proactive_speaker_notes`, `proactive_custom_animations`, and `proactive_narration_audio` values. Defaults are `true`, `false`, and `false`, respectively. They control what the Agent does proactively only when the user has not explicitly instructed otherwise; the latest explicit user instruction always wins. These three values are raw confirmation evidence: the UI and server neither couple nor rewrite them, and every boolean combination is valid. When narration audio is enabled, Strategist later resolves the effective Speaker Notes outcome to enabled and records `Narration Audio dependency` as its Design Spec provenance. Disabling proactive custom animation does not suppress the Strategist's advisory motion recommendations.
+- **Proactive execution booleans** — Final Stage 2 carries top-level `proactive_speaker_notes`, `proactive_custom_animations`, and `proactive_narration_audio` values. Defaults are `true`, `false`, and `false`, respectively. They control what the Agent does proactively only when the user has not explicitly instructed otherwise; the latest explicit user instruction always wins. These three values are raw confirmation evidence: the UI and server neither couple nor rewrite them, and every boolean combination is valid. When narration audio is enabled, Strategist later resolves the effective Speaker Notes outcome to enabled and records `Narration Audio dependency` as its Design Spec provenance. Disabling proactive custom animation does not suppress the Strategist's advisory motion recommendations.
- **Open prose** — `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, `content_divergence`, and `page_count`. `communication_intent` may carry several purposes plus priority / sequence; common paths appear only as help text. `delivery_context` states one primary presenter-led / reader-led / hybrid / recorded-self-running context plus optional secondary use; a hybrid recommendation names which context leads. `content_divergence` is the source-treatment axis. `page_count` may be a range here; Strategist resolves the exact §IX roster, leaving Executor no pagination latitude.
- **Coordinated generative directions** — `design_directions` carries ≥3 safe / shifted / bold candidates. Each candidate bundles visual style, color, typography, icon id, and conditional generated-image rendering. The page can still render legacy top-level `color`, `typography`, and `image_strategy` candidates, but new staged recommendations use the coordinated bundle.
@@ -307,67 +309,75 @@ The front-end loads `/api/catalogs` (served by the confirm server) and falls bac
## Round-trip data contract
-Round-trip and session files live under `<project_path>/confirm_ui/`. The
-Step-3 files (`template_options.json` / `template_selection.json` /
-`template_handoff.json`) close before the Strategist pair
-(`recommendations.stageN.json` / `result.json`) begins.
+Round-trip and session files live under `<project_path>/confirm_ui/`. When Step
+3 is triggered, its files (`template_options.json` / `template_selection.json`
+/ `template_handoff.json`) close before the Strategist pair
+(`recommendations.stageN.json` / `result.json`) begins. Ordinary free design
+creates none of those template files.
-### Three-stage flow
+### Current two-stage flow
-After template selection and project-local installation, the same page runs a
-**three-stage Strategist wizard in one browser session**. Each stage has its own
-Strategist-authored file and top-level `"stage"` selector. The active,
+The page runs a **two-stage Strategist wizard in one browser session**, directly
+for ordinary free design or after triggered template installation. Each stage
+has its own Strategist-authored file and top-level `"stage"` selector. The active,
unconfirmed stage may be overwritten any number of times when the user asks for
a better recommendation; refresh the page to load the replacement. Once the
user confirms it, normal progression writes the next stage file rather than
repurposing the previous one. The server derives the active Strategist filename
-from `result.json`; `template_selection.json` is its separate prerequisite.
+from `result.json`; `template_selection.json` is a separate prerequisite only
+when template options exist.
+
+Confirm UI is a one-run surface, not a migration layer. It accepts only the
+current Stage-1/Stage-2 files. If a project starts confirmation again, author a
+fresh `recommendations.stage1.json`; when it is newer than the prior
+`result.json`, the server treats it as the start of the new two-stage session.
+The completed result cannot be reopened or overwritten: launching without that
+fresh Stage-1 file fails instead of exposing old choices. After Stage 1 is
+confirmed, `recommendations.stage2.json` must likewise be newer than that
+Stage-1 receipt; a Stage-2 file left by an earlier run remains inactive. An
+existing `result.json` outside the current `stage1` / `final` contract also
+fails closed unless fresh template options or a newer Stage-1 file starts the
+replacement run.
| Recommendation file | Declared stage | Page renders | Button | On submit |
|---|---|---|---|---|
| `recommendations.stage1.json` | `"stage1"` | communication contract — content language; audience; open `communication_intent`; audience outcome; core message / primary delivery context + optional secondary use / artifact afterlife / `content_divergence` (all prose fields may be blank); canvas | **Confirm contract & continue** | writes `result.json` `{ stage: "stage1", status: "stage1-confirmed", <communication contract> }`; the page stays open and polls |
-| `recommendations.stage2.json` | `"stage2"` | complete deck solution — conditional natural-language template application, reading mode, mode, page count, visual direction, color, icons, typography, image usage, generated-image rendering | **Confirm solution & continue** | writes `result.json` `{ stage: "stage2", status: "stage2-confirmed", <contract + solution> }`; the page stays open and polls |
-| `recommendations.stage3.json` | `"stage3"` | production only — confirmed image-source summary, conditional AI acquisition path, formula policy, proactive notes / custom-animation / narration-audio toggles, generation mode, Design Spec review toggle | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
-| `recommendations.json` | stage or legacy no-stage payload | read-only compatibility when no stage-specific file exists | matching legacy behavior | preserves the former staged or single-pass behavior; new projects never create this file |
+| `recommendations.stage2.json` | `"stage2"` | complete deck solution and production — conditional natural-language template application, reading mode, mode, page count, visual direction, color, icons, typography, image usage/rendering, conditional AI acquisition path, formula policy, proactive notes/custom-animation/narration-audio toggles, generation mode, and Design Spec review toggle | **Confirm final plan** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
-The AI launches the template phase, applies its confirmed receipt, and only then
-authors Stage 1. Stage-1 recommendations use only the current user request,
+The AI launches a template phase only when triggered, applies its confirmed
+receipt, and only then authors Stage 1; ordinary free design authors Stage 1
+directly. Stage-1 recommendations use only the current user request,
source facts, conversation constraints, and project initialization; the
selection, installed template content/assets, and template canvas are excluded.
After Stage 1 is confirmed, the AI inspects the installed project-local state
-and authors the complete Stage-2 solution once from the user's actual
-communication contract, then authors Stage-3 production mechanics once
-from the confirmed solution. An edit inside the current stage never requests
-another recommendation. The page preserves earlier answers across transitions.
-`GET /api/session` reports `phase: "template"` until selection closes, its
-bound handoff is ready, and a fresh Stage-1 file exists; only then does it
-report `phase: "strategist"`. `GET /api/recommendations`
+when present and authors the complete final Stage-2 solution plus production
+mechanics once from the user's actual communication contract. An edit inside
+the current stage never requests another recommendation. The page preserves
+earlier answers across transitions. When template options exist,
+`GET /api/session` reports `phase: "template"` until selection closes, its bound
+handoff is ready, and a fresh Stage-1 file exists; otherwise it reports
+`phase: "strategist"` directly. `GET /api/recommendations`
is `no-store`, and the server folds confirmed earlier-stage choices back into
-later payloads so refresh / reopen restores the user's actual values—including
-Stage-2 color, typography, icon, image-source, and rendering choices. Once any
-stage-specific file exists, the server ignores legacy `recommendations.json`
-to prevent mixed lifecycles.
+the final Stage-2 payload so an in-run refresh preserves the confirmed Stage-1
+communication contract. Unsubmitted Stage-2 edits are browser-local and a
+completed final result is never reopened.
**Progression guard.** Stage 1 must not be exposed while
`template_options.json` exists without a valid confirmed
`template_selection.json`. After confirmation the session requires a valid
`template_handoff.json` bound to that selection and a Stage-1 recommendation
-no older than the handoff. Strategist stages then confirm
-strictly in order. `/api/confirm` accepts only the submit stage matching the
+newer than the handoff. Each template selection must be newer than its current
+options, and each handoff newer than that selection, so receipts from an earlier
+one-run UI cannot satisfy a new template phase. Strategist then confirms Stage 1
+→ final Stage 2.
+`/api/confirm` accepts only the submit stage matching the
active filename and its required predecessor; the declared `stage` must also
-match the filename. A later file that skips ahead (for example
-`recommendations.stage3.json` while only Stage 1 is confirmed and Stage 2 is
-absent) is never rendered: `/api/session` keeps reporting `waiting_agent` with
-`stage_skip: true`, and `--wait` / `--wait-only` exit `2` if a result skips the
-stage being awaited. A confirmed templates-mode workspace does not exempt
-Stage 2: its
-recommendations must include `template_application.value`, and that completed
-mode disables the no-stage legacy single-pass path. Legacy
-single-pass remains available only for non-template compatibility payloads.
-
-### Input — `recommendations.stage1.json` (created after the Step 3 handoff)
-
-Installation is only the ordering prerequisite. Do not read template selection,
+match the filename. A confirmed templates-mode workspace does not exempt final
+Stage 2: its recommendations must include `template_application.value`.
+
+### Input — `recommendations.stage1.json` (created directly or after a triggered Step-3 handoff)
+
+When Step 3 ran, installation is only the ordering prerequisite. Do not read template selection,
specs, prototypes, assets, fused segment owners, or template canvas when
authoring this file.
@@ -413,10 +423,17 @@ After Stage 1 is confirmed, create `recommendations.stage2.json` with the comple
"delivery_purpose": "balanced",
"mode": "pyramid",
"visual_style": "swiss-minimal",
- "image_usage": ["ai", "provided"]
+ "image_usage": ["ai", "provided"],
+ "image_ai_path": "auto",
+ "formula_policy": "mixed",
+ "generation_mode": "continuous"
},
"page_count": { "value": "12-15" },
"image_notes": { "value": "封面和章节页用 AI 主视觉;产品页优先用户素材。" },
+ "proactive_speaker_notes": { "value": true },
+ "proactive_custom_animations": { "value": false },
+ "proactive_narration_audio": { "value": false },
+ "refine_spec": { "value": false },
"custom_candidates": {
"mode": {
"name_zh": "冲突到决策",
@@ -465,32 +482,14 @@ After Stage 1 is confirmed, create `recommendations.stage2.json` with the comple
}
```
-The example abbreviates the required ≥3 directions. Custom mode/style candidates remain mandatory; only a recommendation containing AI requires the custom image candidate. Stage 2 rejects fewer than three bundles, incomplete six-role palettes, and incomplete heading/body stacks. Legacy grids remain readable only with three complete palettes and complete typography.
-
-After Stage 2 is confirmed, create `recommendations.stage3.json` with production recommendations only; leave both earlier files unchanged:
-
-```json
-{
- "stage": "stage3",
- "lang": "zh",
- "recommend": {
- "image_ai_path": "auto",
- "formula_policy": "mixed",
- "generation_mode": "continuous"
- },
- "proactive_speaker_notes": { "value": true },
- "proactive_custom_animations": { "value": false },
- "proactive_narration_audio": { "value": false },
- "refine_spec": { "value": false }
-}
-```
+The example abbreviates the required ≥3 directions. Custom mode/style candidates remain mandatory; only a recommendation containing AI requires the custom image candidate. Final Stage 2 rejects fewer than three bundles, incomplete six-role palettes, or incomplete heading/body stacks. Legacy grids remain readable only with three complete palettes and complete typography.
- `recommend.*` names each recommended id. New mode / style values use a catalog id or literal `custom`; arbitrary prose values are legacy-only. Use `recommend.image_strategy: "custom"` only when an explicit user-supplied image direction should start selected. Missing recommendations fall back to the normal preset. Legacy aliases remain accepted; new files write canonical ids.
- The three proactive-execution fields are top-level boolean `{ "value": ... }` objects, not catalog ids. Omitted fields use `true / false / false` for notes / custom animation / narration audio. These are absence-of-instruction defaults, not permission to override the user's latest explicit request. Preserve all three raw values independently through `result.json`; do not couple or rewrite them. Strategist derives effective Speaker Notes as enabled when audio is `true` and records `Narration Audio dependency` as provenance in the Design Spec. `proactive_custom_animations: false` leaves Strategist animation suggestions unchanged; it only prevents unrequested custom-animation execution.
- `custom_candidates` is recommendation-only. Mode / style carry localized `name` + `behavior`; conditional image strategy also carries `rendering: "custom"`, `visual`, and `mood`. When a proposal combines or borrows existing catalog entries, the visible behavior names every exact id and Strategist reads every corresponding file before authoring it; a genuinely novel proposal names none. The server rejects missing required candidates; the UI shows full copy, edits it only after selection, rejects a selected blank, and omits unselected candidates from `result.json`. Template-backed proposals obey inherited identity, prototype capacity, and `template_application`.
- Seed `audience`, `communication_intent`, `audience_outcome`, and `delivery_context` when evidence supports them; users need not supply them, and every Stage-1 prose field may end blank. The contract and `primary_language` stay in `result.json` and `design_spec.md`; `spec_lock.md communication` receives `primary_language`, compact `audience` / `objective` / `core_message`, and reading mode. `communication_intent` may preserve multiple purposes and priority/sequence; never add a `primary_job` enum.
- Do not write `recommend.template_reuse_scope` or `recommend.template_adherence`. Strategist records those internal exporter values later in `spec_lock.md` after inspecting the actual template and current content.
-- For a confirmed templates-mode handoff, write one editable prose field as top-level `template_application.value`. It summarizes **how to use** the already selected project-local template: actual page/prototype use and preservation/reorganization decisions. It never chooses, changes, or reinstalls a workspace. Omit it for free design. The UI returns the current string through Stage 2, Stage 3, and final confirmation; Strategist then persists the final effective plan as `- **Template Application**: ...` in `design_spec.md §I`, which Executor reads from the retained Design Spec. Never replace it with internal reuse/adherence ids or a fixed option menu.
+- For a confirmed templates-mode handoff, write one editable prose field as top-level `template_application.value`. It summarizes **how to use** the already selected project-local template: actual page/prototype use and preservation/reorganization decisions. It never chooses, changes, or reinstalls a workspace. Omit it for free design. The UI returns the current string through final Stage 2; Strategist then persists the final effective plan as `- **Template Application**: ...` in `design_spec.md §I`, which Executor reads from the retained Design Spec. Never replace it with internal reuse/adherence ids or a fixed option menu.
Template-mode-only Stage-2 fragment:
@@ -504,7 +503,7 @@ Template-mode-only Stage-2 fragment:
- `recommend.image_usage` should be an array of source ids when more than one source applies, e.g. `["ai", "provided"]`. A single string is still accepted for backward compatibility. Do not write bare `"custom"` and do not encode a mixed-source plan as prose here; write the prose to top-level `image_notes.value`.
- `image_notes` is the initial strategy note shown under the image source chips. Use it for page-role guidance and constraints: which source applies where, what to avoid, which user assets are authoritative, how realistic / abstract the imagery should be, and what can remain as placeholders. It is intent guidance, not a separate finite option.
-- When confirmed Stage-2 `image_usage` includes `ai`, Stage 3 sets `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`. Stage 2 never asks for the acquisition mechanism while the user is still deciding the image role.
+- Final Stage 2 shows and submits `recommend.image_ai_path` as one of `auto` / `api` / `host-native` / `manual` only while its current `image_usage` includes `ai`; changing sources refreshes that production control on the same page.
- **Color candidates carry the user-facing core `palette`**: `background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, and `body_text`. The page renders every role as a labelled swatch with its HEX value visible, and offers per-role override inputs for precise single-role edits, plus a **Custom color card with a free-text box** — the user can describe the palette in words or paste HEX values instead of filling each role; this writes `color: { "name": "custom", "custom": "<text>" }` to `result.json` for the AI to interpret. Legacy `text` is accepted as an alias for `body_text`, but new files should write `body_text`. Strategist derives secondary text, borders, state colors, and visual-style neutral tiers while writing `design_spec.md`, then projects the machine values to `spec_lock.md`; those are not user-facing confirmation choices.
- **Candidate display text may be multilingual**: color / typography candidates can provide `name_zh` / `name_en` / `name_ja` and `note_zh` / `note_en` / `note_ja`; the page falls back to legacy `name` / `note`. Labels resolve in the page language first, then fall back across the others (a `ja` page: ja → en → zh; zh/en pages keep their zh↔en fallback and try `_ja` last), so when `lang` is `ja` always include the `_ja` variants — otherwise the candidate labels render in English.
- **Typography candidates** use concrete heading/body `primary`; non-English decks also use `english`, while English-primary decks omit it. `cjk` / `latin` remain legacy aliases. Localized `name` labels the pair and `css` only previews. Bundles differ overall; font pairs may repeat without blocking. Fixed pairs require `fixed: true`. Catalog `fonts` supplies language-filtered dropdowns plus Other without limiting recommendations; edits mark Custom and refresh the preview. Include topic samples. PPT baselines are `text` 20 · `balanced` 24 · `presentation` 32 px; cards preserve sizes and submit px.
@@ -566,14 +565,13 @@ custom` + `visual_style_behavior`, or `image_strategy.rendering: custom` +
`mode_references`, `visual_style_references`, or
`image_rendering_references` only when that confirmed behavior actually uses
named catalog sources; genuinely novel custom behavior has no reference list.
-Intermediate writes retain accumulated fields; legacy tier names remain
-read-compatible.
+The Stage-1 intermediate write retains the communication contract for Stage 2.
**Final-result consumption contract.** A final result is the user-confirmed input contract for the Strategist's Design Spec, not another recommendation input. After the final wait, Generate Step 4 reads the complete final object exactly once and retains it while Strategist writes and audits `design_spec.md` against every explicitly present field. Normal lock authoring and downstream execution do not reopen `result.json`; the completed Design Spec is the durable authority. Only after that audit passes does Strategist author `spec_lock.md` from the Design Spec plus current execution context, selecting stable anchors and routing rather than copying every field or enumerating every legal color/font. Every value must be consumed at the semantic type owned by [`strategist.md`](../../references/strategist.md) §1 and its field owner: do not omit or substitute it, and do not silently strengthen or weaken its type. If a confirmed requirement cannot be honored, the owning workflow reports or pauses under failure recovery; it never deletes the requirement to keep the pipeline moving.
- Bespoke mode / style prose lives only in the required behavior sibling; image custom prose lives in `image_strategy.behavior`. Canvas / icons retain free-text edge cases, color / typography retain `name: "custom"`, and image usage remains a source-id array plus `image_notes`.
- `image_ai_path` and `image_strategy` appear only with `image_usage: ai` and remain confirmed downstream. The page is default; explicit/failure chat fallback keeps identical fields. `image_ai_path` selects the Step 5 path, and [`strategist-image.md`](../../references/strategist-image.md) §2 retains the selected rendering or custom behavior as the deck-level image identity anchor; individual prompts still adapt subject, composition, and atmosphere within it.
-- Step-3 **Confirm template & continue** writes `template_selection.json` and keeps the page open while the agent applies the choice. The agent then runs `--complete-template-phase` and writes fresh Stage 1. Stage-1 **Confirm contract & continue** and Stage-2 **Confirm solution & continue** likewise keep polling for the downstream file. The final Stage-3 Confirm saves `result.json` and shuts the server down (auto-close). The default flow is `template_options.json` → `--daemon` → template chat handoff → `--wait-only --wait-stage template` → installation/free-design closure → `--complete-template-phase` → fresh Stage-1 handoff/wait → Stage-2 wait → final wait. The AI reads each receipt at its owning boundary. Chat fallback mirrors the same choices. Either way, Step 4 ends with `--shutdown` so a never-confirmed page cannot retain its selected port ahead of Step 6 live preview.
+- Triggered Step-3 **Confirm template & continue** writes `template_selection.json` and keeps the page open while the agent applies the choice. The agent then runs `--complete-template-phase` and writes fresh Stage 1; ordinary free design writes Stage 1 and launches directly. Stage-1 **Confirm contract & continue** keeps polling for the newly authored Stage 2. Stage-2 **Confirm final plan** saves the final `result.json` and shuts the server down (auto-close). The AI reads each receipt at its owning boundary; chat fallback mirrors the same choices. Either way, Step 4 ends with `--shutdown` so a never-confirmed page cannot retain its selected port ahead of Step 6 live preview.
## Scope
diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.md
index c8da6ff9..94f45bde 100644
--- a/skills/ppt-master/templates/README.md
+++ b/skills/ppt-master/templates/README.md
@@ -39,27 +39,27 @@ which keeps the fixed route name and dispatches exactly one child workflow:
[`Create Layout`](../workflows/create-template/create-layout.md), or
[`Create Deck`](../workflows/create-template/create-deck.md).
-The four indexes are the complete library-discovery source for
-[`generate-pptx`](../workflows/generate-pptx.md) Step 3. The default page shows
-free design, one registered single-select dropdown per kind, and one separate
-single-select dropdown for exact roots supplied for the run; it never scans the
-four directories or fuzzy-matches a bare name. An exact root that matches a
-registered index entry may be displayed in its kind dropdown as `library`; an
-unregistered root remains `explicit` in the specified-root dropdown. After
-confirmation,
+The four indexes are the complete library-discovery source for conditional
+[`generate-pptx`](../workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)
+Step 3. Ordinary Default Generate reads no index or template page and enters
+Stage 1 with free design. Explicit browse/selection intent, exact workspace
+roots, or a current Create Template handoff triggers Step 3. Its page reads only
+these indexes, never scans directories or fuzzy-matches a bare name/style
+phrase, and accepts one registered choice per kind plus one supplied-root
+choice. A registered exact root is `library`; any other exact root is
+`explicit`. After confirmation,
[`apply-template-workspace`](../workflows/stages/apply-template-workspace.md)
validates, fuses, and installs every selected workspace into the current
-project before Stage 1 starts. Template-aware reading begins in Stage 2 from
-that project-local copy. Quick Generate is the non-interactive exception: it
-never opens this selector, directly applies exact roots supplied for the run,
-and uses free design when no exact root exists.
+project before Stage 1 starts. Template-aware reading begins in final Stage 2 from
+that project-local copy. Quick skips the page, applies supplied exact roots, and
+otherwise uses free design.
## Orthogonal contracts
| Axis | Values | Meaning |
|---|---|---|
| Template kind | `brand` / `style` / `layout` / `deck` | Which reusable contract the package owns: identity, direction/method, brand-neutral structure, or a complete recurring application |
-| Selection source | `library` / `explicit` | Step-3 discovery provenance only: exact index-derived root or exact unregistered root; it does not change template semantics |
+| Selection source | `library` / `explicit` | Conditional Step-3 discovery provenance only: exact index-derived root or exact unregistered root; it does not change template semantics |
| Internal creation strategy | `standard` / `fidelity` / `mirror` | AI-derived Create Layout/Create Deck implementation: newly author a compact or broad roster, or materialize validated source-package facts into a new workspace; persisted for tools, never presented as a required user choice |
| Internal application plan | `template_reuse_scope` plus optional `template_adherence` | Strategist derives literal, structural, or style-only use and any strict/adaptive exporter behavior after inspecting the installed template and current content |
| PPTX structure | `flat` / `structured` | Derived application plans that use template structure compile declared Masters and Layouts; Style-only, style-scope, brand-only, and free design remain Slide-local. Style fused with Layout/Deck does not change the non-Style structure plan. |
@@ -89,7 +89,7 @@ Style narrows this shared routing shape to `templates/design_spec.md` only and
does not carry asset or review payloads; initialized-project sibling scaffolding
may exist but is not Style input.
The conditional [`apply-template-workspace`](../workflows/stages/apply-template-workspace.md)
-stage owns installation and fusion during the default Step-3 selection phase or
+stage owns installation and fusion during an explicitly triggered Default Step-3 selection phase or
the Quick exact-root branch. Brand/Layout/Deck consume package-owned
`templates/`, `images/`, and `icons/`; Style consumes only
`templates/design_spec.md` and ignores sibling project scaffolding. Every kind
diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.md
index b889c507..dc1a216b 100644
--- a/skills/ppt-master/templates/brands/README.md
+++ b/skills/ppt-master/templates/brands/README.md
@@ -10,20 +10,20 @@ lives in the parent [`README.md`](../README.md).
## How brands are consumed
-Brand application follows the independent selection phase in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
-fills the Brand dropdown only from `brands_index.json`; unregistered exact roots
-appear only in the separate specified-root dropdown. It never scans this
-directory or fuzzy-matches a bare brand name. An exact supplied root matching a
-registered root may be labelled `library`; otherwise it remains `explicit`. The
+Brand application follows the parent README's conditional
+[`generate-pptx`](../../workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)
+contract. Ordinary Default enters Stage 1 with free design; explicit template
+browsing/selection, an exact root, or a current Create Template handoff triggers
+Step 3. Its Brand choices come only from `brands_index.json`; no directory scan
+or bare-name match is allowed. Registered exact roots are `library`; other exact
+roots remain `explicit`. The
conditional
[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)
stage owns path normalization, portable-root installation, multi-kind fusion,
same-kind conflict resolution, and provenance before Stage 1. Template-aware
-reading begins in Stage 2 from the installed project-local copy. This file owns
-only the Brand schema. Quick Generate never opens the selector: an exact Brand
-root supplied for the run enters the same stage directly, while no exact root
-leaves Quick in free design.
+reading begins in final Stage 2 from the installed project-local copy. This file owns
+only the Brand schema. Quick applies a supplied exact Brand root directly and
+otherwise uses free design.
## Creating a new brand
@@ -58,8 +58,9 @@ Logo filenames are descriptive, not contractual — `templates/design_spec.md`
[brands_index.json](./brands_index.json) is a slim machine-readable map (`brand_id → { summary, primary_color }`). Refresh it with `register_template.py --kind brand <brand_id>` after a brand is created or edited. Registration rejects incomplete frontmatter, mismatched IDs, page SVGs, missing required identity sections, invalid or inconsistent colors/provenance, and broken workspace-local asset references.
-The default Step-3 page reads this index as its complete registered-brand
-catalog; chat discovery reads the same file and returns exact workspace roots.
+The explicitly triggered Step-3 page reads this index as its complete
+registered-brand catalog; chat discovery reads the same file and returns exact
+workspace roots.
Choosing an entry and confirming it triggers installation. Exact directory
paths and validated Create Template handoffs remain supported, while a bare ID
never resolves implicitly.
diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.md
index 3be72c1d..df9c3c63 100644
--- a/skills/ppt-master/templates/decks/README.md
+++ b/skills/ppt-master/templates/decks/README.md
@@ -31,20 +31,20 @@ Overview when application fit must be judged in detail.
## Trigger and fusion
-Selection uses the independent phase in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
-fills the Deck dropdown only from `decks_index.json`; unregistered exact roots
-appear only in the separate specified-root dropdown. It never scans this
-directory or fuzzy-matches a bare ID. An exact supplied root matching a
-registered root may be labelled `library`; otherwise it remains `explicit`. Choosing and
+Selection follows the parent README's conditional
+[`generate-pptx`](../../workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)
+contract. Ordinary Default enters Stage 1 with free design; explicit template
+browsing/selection, an exact root, or a current Create Template handoff triggers
+Step 3. Its Deck choices come only from `decks_index.json`; no directory scan or
+bare-ID/style-phrase match is allowed. Registered exact roots are `library`;
+other exact roots remain `explicit`. Choosing and
confirming an entry triggers the conditional
[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)
stage, which owns path normalization, compatibility checks, installation, and
-fusion before Stage 1. Template-aware reading begins in Stage 2 from the
+fusion before Stage 1. Template-aware reading begins in final Stage 2 from the
installed project-local copy.
-Quick Generate never opens the selector: an exact Deck root supplied for the
-run enters the same stage directly, while no exact root leaves Quick in free
-design. Quick uses the installed prototypes as flat authoring inputs; reusable
+Quick applies a supplied exact Deck root directly and otherwise uses free
+design. It uses installed prototypes as flat authoring inputs; reusable
native Master/Layout compilation remains a default lock-backed capability.
This file owns the Deck schema and application-context boundary. Chat discovery
reads the same index and returns exact roots; a bare ID never resolves
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index de77fe01..2f975997 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -47,9 +47,9 @@ Start with this exact heading order:
| AI Image Acquisition Path | <confirmed path or not applicable> |
| Generation Mode | <continuous or split> |
| Spec Refinement | <enabled or disabled> |
-| Speaker Notes | <enabled or disabled> — <explicit user instruction, Stage 3 proactive policy, compatibility default, or enabled Narration Audio dependency> |
-| Custom Animations | <enabled or disabled> — <explicit instruction and object/all-motion scope, Stage 3 proactive policy, or compatibility default> |
-| Narration Audio | <enabled or disabled> — <explicit user instruction, Stage 3 proactive policy, or compatibility default> |
+| Speaker Notes | <enabled or disabled> — <explicit user instruction, final Stage-2 proactive policy, workflow default, or enabled Narration Audio dependency> |
+| Custom Animations | <enabled or disabled> — <explicit instruction and object/all-motion scope, final Stage-2 proactive policy, or workflow default> |
+| Narration Audio | <enabled or disabled> — <explicit user instruction, final Stage-2 proactive policy, or workflow default> |
| Created Date | <YYYY-MM-DD> |
## II. Canvas Specification
@@ -133,11 +133,11 @@ Use these exact subsections and field shapes:
- **Primary bundled library**: <one of chunk-filled / tabler-filled / tabler-outline / phosphor-duotone, or none>
- **Brand-logo library**: <simple-icons when selected for real brand marks; omit otherwise>
-| Purpose | Icon Path | Page |
-| --- | --- | --- |
+| Icon Path | Suitable Scenarios |
+| --- | --- |
```
-Preserve Title/Body characters and resolved stacks; omit blank Typography upgrade and never place it in a stack. For each justified recurring family override, add the role to Font Plan plus `- **<Role> stack**: <complete ordered stack>`. Possible roles are `Annotation`, `Footer`, `Footnote`, `Data`, `Emphasis`, `Quote`, and `Code`; add only recurring, intentional differences. Add non-locked `Role rationale` only for an extra family. Do not collapse distinct Title/Body stacks or discard a declared optional role. Each Font Size Hierarchy value is a role anchor: Executor may vary one occurrence `±2px`; a short non-structural Hero/Display size may stay unlisted only while the same value is planned at most twice, and its third occurrence needs a named row. Add every recurring palette role and typography-size anchor established by the plan; do not enumerate one-off paint or font-family garnish. For confirmed custom directions, add the applicable `Mode References`, `Mode Behavior`, `Visual Style References`, and `Visual Style Behavior` lines under Theme Style. Include `Stroke Width` under §VI only for a stroke library. `simple-icons` may accompany the one primary bundled library and is recorded only when real brand marks were selected. The icon table records planned usage, but user-provided, template-carried, imported, custom, and other prepared SVGs under the project `icons/` directory remain usable without being forced into that stylistic selection. Leave the §VI table empty when no icons are used.
+Preserve Title/Body characters and resolved stacks; omit blank Typography upgrade and never place it in a stack. For each justified recurring family override, add the role to Font Plan plus `- **<Role> stack**: <complete ordered stack>`. Possible roles are `Annotation`, `Footer`, `Footnote`, `Data`, `Emphasis`, `Quote`, and `Code`; add only recurring, intentional differences. Add non-locked `Role rationale` only for an extra family. Do not collapse distinct Title/Body stacks or discard a declared optional role. Each Font Size Hierarchy value is a role anchor: Executor may vary one occurrence `±2px`; a short non-structural Hero/Display size may stay unlisted only while the same value is planned at most twice, and its third occurrence needs a named row. Add every recurring palette role and typography-size anchor established by the plan; do not enumerate one-off paint or font-family garnish. For confirmed custom directions, add the applicable `Mode References`, `Mode Behavior`, `Visual Style References`, and `Visual Style Behavior` lines under Theme Style. Include `Stroke Width` under §VI only for a stroke library. `simple-icons` may accompany the one primary bundled library and is recorded only when real brand marks were selected. The icon table records the curated synced pool and broad semantic scenarios, not exact page placement or mandatory use. User-provided, template-carried, imported, custom, and other prepared SVGs under the project `icons/` directory remain usable without being forced into that bundled selection. Leave the §VI table empty when no bundled or brand icons are prepared.
When §VIII contains any `Acquire Via: ai` row, add this subsection under §III and preserve the complete confirmed AI direction:
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index 33c05547..45aba3bb 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -46,20 +46,20 @@ kind of rule is never a mirror operation.
## Trigger and identity boundary
-Selection uses the independent phase in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
-fills the Layout dropdown only from `layouts_index.json`; unregistered exact
-roots appear only in the separate specified-root dropdown. It never scans this
-directory or fuzzy-matches a bare ID. An exact supplied root matching a
-registered root may be labelled `library`; otherwise it remains `explicit`.
+Selection follows the parent README's conditional
+[`generate-pptx`](../../workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)
+contract. Ordinary Default enters Stage 1 with free design; explicit template
+browsing/selection, an exact root, or a current Create Template handoff triggers
+Step 3. Its Layout choices come only from `layouts_index.json`; no directory
+scan or bare-ID/style-phrase match is allowed. Registered exact roots are
+`library`; other exact roots remain `explicit`.
Choosing and confirming an entry triggers the conditional
[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)
stage, which owns path normalization, compatibility checks, installation, and
-fusion before Stage 1. Template-aware reading begins in Stage 2 from the
+fusion before Stage 1. Template-aware reading begins in final Stage 2 from the
installed project-local copy.
-Quick Generate never opens the selector: an exact Layout root supplied for the
-run enters the same stage directly, while no exact root leaves Quick in free
-design. Quick uses the installed prototypes as flat authoring inputs; reusable
+Quick applies a supplied exact Layout root directly and otherwise uses free
+design. It uses installed prototypes as flat authoring inputs; reusable
native Master/Layout compilation remains a default lock-backed capability.
This file owns the Layout schema and its identity/application boundary. Chat
discovery reads the same index and returns exact roots; a bare ID never resolves
diff --git a/skills/ppt-master/templates/scaffolds/design_spec.md b/skills/ppt-master/templates/scaffolds/design_spec.md
index 7c8e086a..59da2c97 100644
--- a/skills/ppt-master/templates/scaffolds/design_spec.md
+++ b/skills/ppt-master/templates/scaffolds/design_spec.md
@@ -95,9 +95,9 @@
## VI. Icon Usage Specification
-| Purpose | Icon Path | Page |
-| --- | --- | --- |
-| [fill] | [fill] | [fill] |
+| Icon Path | Suitable Scenarios |
+| --- | --- |
+| [fill] | [fill] |
## VIII. Image Resource List
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 709d6991..28a368e3 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -24,7 +24,7 @@ After Generate Step 4 Gate 1, read the completed Design Spec and current page/re
| `visual_style` | `visual_style` | Preset or `custom` |
| `colors` | Stable semantic color roles | Core identity and recurring roles only; contextual SVG paints need no row; `image_rendering` appears only for AI images |
| `typography` | `font_family`, `body`, `title` | Core family/size anchors; new locks also write explicit `title_family` and `body_family`; size anchors are unitless px numbers |
-| `icons` | `library`, `inventory` | `library` is the Strategist's primary bundled style choice or `none`; `simple-icons/*` may be selected alone or accompany it; `inventory` records the planned bundled selection rather than all usable project-local icons; `stroke_width` is conditional |
+| `icons` | `library`, `inventory` | `library` is the Strategist's primary bundled style choice or `none`; `simple-icons/*` may be selected alone or accompany it; `inventory` indexes the curated synced bundled pool rather than page usage or all usable project-local icons; `stroke_width` is conditional |
| `page_rhythm` | One `P<NN>` row per page | Values: `anchor`, `dense`, `breathing` |
| `pptx_structure` | `mode` | Values: `flat`, `structured` |
| `forbidden` | Literal list items | General standards stay in their owning reference |
@@ -89,7 +89,7 @@ New locks always write `title_family` and `body_family`, even when their values
- `font_family`, `title_family`, `body_family`, and every optional `<role>_family` use one non-empty PPT-safe exported family stack. `font_family` is the body/default compatibility stack, not permission to erase role differences.
- Every non-family `typography` value is a positive finite unitless px anchor. Intermediate values need no lock row when they stay within the mapped role's anchor `±2px`. At most two occurrences of one undeclared short non-structural Hero/Display size may remain sparse; a third occurrence or any structural use requires Design Spec repair and a named anchor.
-- `icons.library` records the primary stylistic library selected from `chunk-filled`, `tabler-filled`, `tabler-outline`, or `phosphor-duotone`, or `none` when no generic bundled icons are selected. Selected `simple-icons/*` brand marks may appear alone or alongside it in `inventory` without becoming a stylistic library. The inventory records planned bundled choices, while every SVG already under `<project_path>/icons/` remains valid prepared execution material.
+- `icons.library` records the primary stylistic library selected from `chunk-filled`, `tabler-filled`, `tabler-outline`, or `phosphor-duotone`, or `none` when no generic bundled icons are selected. Selected `simple-icons/*` brand marks may appear alone or alongside it in `inventory` without becoming a stylistic library. The inventory indexes the curated synced bundled pool without assigning page usage; every SVG already under `<project_path>/icons/` remains valid prepared execution material.
- `objective` grammar: one concise sentence preserving the deck goal and audience success condition.
- `image_rendering` grammar: one catalog id, or `custom` with `image_rendering_behavior`.
- `images`: `- <key>: <path> | source=<via> | pattern=<layout> | crop=<adaptive|no-crop>`; e.g. `- p04: images/a.png | source=user | pattern=full-height image beside the evidence | crop=no-crop`. Use the canonical `images/<filename>` path; `source` and `crop` exactly project §VIII, while `pattern` preserves its non-empty normalized free-form suggestion and any optional hierarchical catalog ids. The pattern remains a recommendation for Executor recall, not a geometry or realization lock. Omit unplaced sheets.
diff --git a/skills/ppt-master/templates/styles/README.md b/skills/ppt-master/templates/styles/README.md
index 39028e1a..e37fa054 100644
--- a/skills/ppt-master/templates/styles/README.md
+++ b/skills/ppt-master/templates/styles/README.md
@@ -9,27 +9,25 @@ Style is a fourth independent template kind alongside [`brands/`](../brands/), [
| Axis | Meaning |
|---|---|
| Template `kind: style` | A portable workspace that coordinates reusable method and non-binding design defaults |
-| Stage-2 `mode` | The current deck's confirmed narrative and persuasion skeleton |
-| Stage-2 `visual_style` | The current deck's confirmed shape, composition, whitespace, typography-character, and texture lock |
+| Final Stage-2 `mode` | The current deck's confirmed narrative and persuasion skeleton |
+| Final Stage-2 `visual_style` | The current deck's confirmed shape, composition, whitespace, typography-character, and texture lock |
| Internal `template_reuse_scope: style` | A flat current-project export plan that reuses no Master/Layout structure |
These names are separate contracts. Style-only and Style + Brand naturally produce a flat application plan, while Style fused with a Layout or Deck may use structured reuse. `kind: style` therefore never forces the internal reuse scope when another workspace supplies structure.
## Trigger, Precedence, and Fusion
-Selection uses the independent phase in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
-fills the Style dropdown only from `styles_index.json`; unregistered exact roots
-appear only in the separate specified-root dropdown. It never scans this
-directory or fuzzy-matches a bare Style name. An exact supplied root matching a
-registered root may be labelled `library`; otherwise it remains `explicit`. A
-consulting label or ordinary visual description remains a brief or catalog
-signal and does not activate this workspace. Confirmation runs the
+Selection follows the parent README's conditional
+[`generate-pptx`](../../workflows/generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)
+contract. Ordinary Default enters Stage 1 with free design; explicit template
+browsing/selection, an exact root, or a current Create Template handoff triggers
+Step 3. Its Style choices come only from `styles_index.json`; no directory scan
+or bare-name match is allowed. A consulting label or visual description remains
+a brief and does not activate this workspace. Confirmation runs the
common installation/fusion stage before Stage 1; template-aware reading begins
-in Stage 2 from the project-local copy. Quick Generate never opens the selector:
-an exact Style root supplied for the run enters the same stage directly, while
-no exact root leaves Quick in free design; its current agent reads the installed
-copy before authoring flat pages.
+in final Stage 2 from the project-local copy. Quick applies a supplied exact
+Style root directly and otherwise uses free design; its current agent reads the
+installed copy before authoring flat pages.
| Decision | Precedence |
|---|---|
@@ -39,7 +37,7 @@ copy before authoring flat pages.
| Reusable structure | Compatible Layout, then Deck structure; Style never supplies structure |
| Recurring application context | Deck, subordinate to the current project's Stage-1 communication contract |
-Style fallback values seed the normal Stage-2 solution when the corresponding decision remains open. They are not identity truth and do not bypass confirmation. If a Style method and a Deck application contract materially conflict, surface the mismatch; do not silently weaken either one.
+Style fallback values seed the final Stage-2 solution when the corresponding decision remains open. They are not identity truth and do not bypass confirmation. If a Style method and a Deck application contract materially conflict, surface the mismatch; do not silently weaken either one.
## `design_spec.md` Contract
@@ -94,7 +92,7 @@ Do not create empty `images/`, `icons/`, or `exports/` directories. Existing ini
The discovery source of truth is [`styles_index.json`](./styles_index.json).
Each entry is `style_id → { summary, keywords }`; the index never duplicates
-the full method or defaults. The default Step-3 page reads this file as its
-complete registered-Style catalog, and chat discovery returns exact roots from
+the full method or defaults. The explicitly triggered Step-3 page reads this
+file as its complete registered-Style catalog, and chat discovery returns exact roots from
the same entries. Choosing and confirming an entry activates installation;
reading a name in ordinary prose does not.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index b26513af..dcce5ade 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -423,7 +423,7 @@ Items to surface:
| Application context and representative page roles | Create Deck only | `[decision]` when supplied explicitly; otherwise `[suggested]` from recurring source patterns. Describe the source and intended family without assigning required/optional/repeatable status or fixed/replaceable/example-only policy. |
| Identity, method, or structural summary | Yes | Create Brand/Create Deck: identity tone. Create Style: communication method and visual-default summary. Create Layout: structural use case and density/rhythm summary only. |
| Communication method and evidence discipline | Create Style only | `[decision]` when explicit; otherwise `[suggested]` from repeated source behavior. State argument flow, message/evidence discipline, page-role vocabulary, and data-expression rules without fixing a page sequence. |
-| Visual-system defaults | Create Style only | `[decision]` when explicit; otherwise `[suggested]` from evidence. Palette, typography, mode, and visual-style values remain overrideable seeds, never Brand identity truth or direct Stage-2 locks. |
+| Visual-system defaults | Create Style only | `[decision]` when explicit; otherwise `[suggested]` from evidence. Palette, typography, mode, and visual-style values remain overrideable seeds, never Brand identity truth or direct final Stage-2 locks. |
| Review focus | Create Style only | `[decision]` when explicit; otherwise `[suggested]`. These checks apply only if the user separately enables visual review; the Style cannot trigger that stage. |
| Theme mode | Create Layout/Create Deck only | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[fact]` from an independently identified external authority, `[decision]` from user-authored text in any carrier, otherwise `[suggested]`. E: `[decision]`. |
| Canvas format and dimensions | Create Layout/Create Deck only | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[fact]` from an independently identified external authority or `[decision]` from user-authored text in any carrier when specified. E: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`). |
@@ -836,14 +836,18 @@ The Layout/Deck completion card's file roster is collected by globbing
flat Layout/Deck packages still use their root `*.svg` roster.
The index file is the complete **registered-library discovery source** for
-[`generate-pptx`](./generate-pptx.md) Step 3. The default template-selection
-page reads only the four kind indexes, and chat discovery uses the same entries
-to list exact workspace-root paths; neither path scans template directories.
-Selecting and confirming a registered entry activates installation. An exact
-unregistered workspace still works when supplied by the user or handed off by
-this route, but remains labelled `explicit` and does not appear in the library
-catalog. If an explicit root exactly matches a registered canonical root, it
-may be displayed as `library`. Bare names are never resolved implicitly.
+conditional [`generate-pptx`](./generate-pptx.md#step-3-conditional-template-discovery-selection-and-installation)
+Step 3. Its template-selection page is opened only after an explicit request to
+browse/select templates and reads only the four kind indexes; chat discovery
+uses the same entries to list exact workspace-root paths. Neither path scans
+template directories. Ordinary Default Generate reads no index, opens no
+template page, and proceeds directly to Stage 1 with free design. Selecting and
+confirming a registered entry activates installation. An exact unregistered
+workspace supplied by the user, or the exact validated root handed off by this
+route in the current conversation, triggers Step 3 directly but remains
+labelled `explicit` and does not appear in the library catalog. If an explicit
+root exactly matches a registered canonical root, it may be displayed as
+`library`. Bare names and style phrases are never resolved implicitly.
> **Recommended for new templates**: declare a YAML frontmatter block at the top of `design_spec.md`. The registrar prefers it over prose extraction:
>
@@ -908,8 +912,8 @@ may be displayed as `library`. Bare names are never resolved implicitly.
> ```
README files describe each kind in prose only — they do not list templates.
-Both the default Step-3 selector and chat discovery read the JSON index files;
-the registrar does not touch READMEs.
+The explicitly triggered Step-3 selector and chat discovery read the JSON index
+files; the registrar does not touch READMEs.
---
@@ -949,7 +953,7 @@ list only `templates/design_spec.md`. Both completion cards must explicitly
state `SVG roster: N/A` and `Native structure: N/A`; Style must also state
`Visual review trigger: N/A (advisory focus only)`.
-The next Generate PPTX Step 3 input is the exact `<template_workspace>/` root in either scope. Step 3 resolves its `templates/design_spec.md` and always ignores `exports/`. Brand/Layout/Deck copy or consume package-owned `templates/` plus any existing `images/` and `icons/`; Style consumes only `templates/design_spec.md` and ignores sibling project scaffolding. It then authors new `svg_output/` pages under the template contract and exports a new PPTX. Neither the reference PPTX/SVG nor the template prototypes are upgraded in place. A legacy-flat Brand/Layout/Deck package root remains readable only when it satisfies its current kind contract; for Layout/Deck that includes the structured SVG contract. Style has no legacy-flat form. Otherwise create a new workspace through this route.
+The exact `<template_workspace>/` root in either scope is the current-conversation handoff to conditional Generate PPTX Step 3; that handoff triggers the stage without a separate discovery request. Step 3 resolves `templates/design_spec.md` and always ignores `exports/`. Brand/Layout/Deck copy or consume package-owned `templates/` plus any existing `images/` and `icons/`; Style consumes only `templates/design_spec.md` and ignores sibling project scaffolding. It then authors new `svg_output/` pages under the template contract and exports a new PPTX. Neither the reference PPTX/SVG nor the template prototypes are upgraded in place. A legacy-flat Brand/Layout/Deck package root remains readable only when it satisfies its current kind contract; for Layout/Deck that includes the structured SVG contract. Style has no legacy-flat form. Otherwise create a new workspace through this route.
---
@@ -970,7 +974,7 @@ The next Generate PPTX Step 3 input is the exact `<template_workspace>/` root in
2. **Color consistency**: Create Deck SVG files must use the same color scheme as `design_spec.md §II Color Scheme`; Create Layout owns no identity colors, Create Style owns only overrideable visual defaults, and Create Brand/Create Style own no SVG files
3. **Native-object mapping**: Treat Theme/Master/Layout/Placeholder as compiled PowerPoint objects, not template kinds. Layout owns topology and placement, Brand owns identity values/assets, Style owns portable direction/method defaults, and Deck adds descriptive recurring-application context.
4. **Placeholder convention**: `{{}}` format only; default names listed in [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). Override per template via `placeholders:` frontmatter when needed.
-5. **Discovery requirement**: A library template appears in the default Step-3 selector and chat discovery only after `register_template.py` has updated its kind index (Step 7). A project-scoped workspace intentionally stays out of the library catalog and is consumed as an exact `explicit` workspace-root handoff. In both cases Step 3 confirms the choice and installs the workspace before Stage 1.
+5. **Discovery requirement**: A library template appears in the explicitly triggered Step-3 selector and chat discovery only after `register_template.py` has updated its kind index (Step 7). A project-scoped workspace intentionally stays out of the library catalog and is consumed as an exact `explicit` workspace-root handoff. Ordinary Default Generate does not read either catalog; an explicit selection/root or this route's current-conversation handoff triggers Step 3, which installs the workspace before Stage 1.
6. **Review output**: Generate `exports/<template_id>_template_preview.pptx` on request and always for a multi-Master template. It is derived local evidence, never a source input during template application, and library exports stay Git-ignored. Brand and Style never generate this preview; Style Review Focus cannot activate visual review.
> **Full role specification**: [template-designer.md](../references/template-designer.md)
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 26d13021..4d45fa01 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -6,7 +6,7 @@ description: Generate PPTX route authority for source intake, planning, SVG auth
> Load only after [`routing.md`](./routing.md) selects Generate PPTX. This file owns the route's Step 1–7 sequence, gates, role switching, and mandatory commands.
-**Default Core Pipeline**: `Initial Materials → [Fact Research] → Create Project → Template Selection & Installation → Strategist Structured Plan → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export`
+**Default Core Pipeline**: `Initial Materials → [Fact Research] → Create Project → [Template Selection & Installation] → Strategist Structured Plan → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export`
**Generate-specific execution discipline**:
@@ -153,15 +153,19 @@ Direct supported bitmap inputs follow both boundaries: the original is archived
---
-### Step 3: Template Selection and Installation
+### Step 3: Conditional Template Discovery, Selection, and Installation
-**Scope**: Default Generate only. Quick Generate resolves exact supplied roots
-or free design inside its profile and never enters this Step or launches Confirm
-UI.
+**Scope**: Default Generate only, and only when the user explicitly asks to
+browse/select a template for this run, supplies an exact current workspace root,
+or returns an exact Create Template handoff in the current conversation. Quick
+Generate resolves exact supplied roots or free design inside its profile and
+never enters this Step or launches Confirm UI.
-🚧 **GATE**: Step 2 complete; the project workspace exists. Finish this phase before authoring or confirming Stage 1. Template selection is not part of the Stage-1 communication contract.
+**Default — free design without a stop**: When none of those triggers is present, use free design, do not read the four indexes, do not create any template-phase artifact, and proceed directly to Step 4 Stage 1. A bare template / brand name, style phrase, or vague template preference remains design brief text and never triggers fuzzy lookup or this phase.
-**Default UI phase**: When the selected confirmation surface is the page, open its template-selection phase first. Show one exclusive free-design choice, four single-select registered-workspace dropdowns (Brand / Style / Layout / Deck), and one single-select specified-root dropdown. Every dropdown has a `None` option. A non-empty dropdown exits free design; choosing free design clears all five dropdowns. Populate the registered dropdowns from exactly these discovery sources:
+🚧 **GATE — only when triggered**: Step 2 complete; the project workspace exists. Finish the selected template path before authoring or confirming Stage 1. Template selection is not part of the Stage-1 communication contract.
+
+**Triggered UI phase**: When the selected confirmation surface is the page, open its template-selection phase first. Show one exclusive free-design choice, four single-select registered-workspace dropdowns (Brand / Style / Layout / Deck), and one single-select specified-root dropdown. Every dropdown has a `None` option. A non-empty dropdown exits free design; choosing free design clears all five dropdowns. Populate the registered dropdowns from exactly these discovery sources:
- `templates/brands/brands_index.json`
- `templates/styles/styles_index.json`
@@ -172,7 +176,8 @@ Derive each library root as `templates/<kind_dir>/<id>/` from its index entry. N
**UI branch — executable sequence**: Resolve the confirmation surface under
[`confirm_ui.md`](../scripts/docs/confirm_ui.md) before the first command. For
-the default page branch, write
+the default page branch, first clear only the prior one-run template receipts
+(the command is idempotent), then write
`<project_path>/confirm_ui/template_options.json` with schema version `1`,
`phase: "template"`, the UI language, and every exact user/Create Template root
as an absolute entry in `explicit_workspace_roots` (use an empty array when
@@ -180,6 +185,7 @@ none were supplied). The server itself reads the four indexes above; do not copy
library entries into this input. Then launch and wait:
```bash
+python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --reset-template-phase
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon
# Post confirm_ui.md's actual URL + template-selection summary/chat fallback here.
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage template
@@ -210,28 +216,37 @@ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --complete-temp
This agent-only command writes `confirm_ui/template_handoff.json`. In template
mode it refuses to succeed until `<project_path>/templates/design_spec.md`
exists. Author `recommendations.stage1.json` only after this command returns
-zero; the server also rejects a Stage-1 file older than the handoff. Do not
-write the handoff manually.
+zero; the server also requires Stage 1 to be authored after that handoff. Do
+not write the handoff manually.
-**Explicit-path and chat compatibility**: Preserve the existing exact-workspace-root path. An explicit root supplied in the request, selected in chat, or handed off by Create Template may be applied directly after the user confirms it; no index membership is required. The chat branch mirrors the same free-design-versus-root decision without launching the page. A bare name remains ordinary brief text and never triggers slug lookup or fuzzy resolution. When the user asks what is available in chat, list only the four indexes and require an exact returned root before installation.
+**Explicit-path and chat compatibility**: Preserve the exact-workspace-root path. An explicit root supplied in the request, selected in chat, or handed off by Create Template may be applied directly after the user confirms it; no index membership is required. The chat branch mirrors the same root decision without launching the page. A bare name remains ordinary brief text and never triggers slug lookup or fuzzy resolution. When the user explicitly asks what is available for this run in chat, list only the four indexes and require an exact returned root before installation.
**Raw PPTX boundary**: A raw PPTX remains valid source material, but it is not a Step 3 workspace. Raw PPTX plus new content uses [`template-fill-pptx`](./template-fill-pptx.md). To create a reusable workspace, run [`create-template`](./create-template.md), then return with the generated root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
-**✅ Checkpoint**: The user confirmed free design, or every selected workspace passed validation/fusion and its complete consumed state now exists under the target project. In the UI branch, the matching `template_handoff.json` is ready; in the chat/delegated branch, the equivalent selection and installation state is retained in context without fabricating UI receipts. Proceed to Step 4 and author fresh Stage 1.
+**✅ Checkpoint — triggered path**: The user closed the template selector with free design, or every selected workspace passed validation/fusion and its complete consumed state now exists under the target project. In the UI branch, the matching `template_handoff.json` is ready; in the chat/delegated branch, the equivalent selection and installation state is retained in context without fabricating UI receipts. Proceed to Step 4 and author fresh Stage 1. The normal untriggered free-design path reaches Step 4 directly and creates none of these receipts.
---
### Step 4: Strategist Phase (MANDATORY in the default pipeline)
-🚧 **GATE**: Step 3 selection is confirmed; free design is active, or the selected template state is validated and installed in the project. Stage 1 has not started before this point.
+🚧 **GATE**: Source preparation is complete. Either the conditional Step 3 was not triggered and free design is the default, or its selection is confirmed and every selected template state is validated and installed in the project. Stage 1 has not started before this point.
**Hard rule — Stage 1 is template-independent**: Author every Stage-1 recommendation from the user's current request, source facts, conversation constraints, and project-initialization state only. Do not read or use the Step-3 selection, installed template spec/prototypes/assets, fused segment owners, or any template canvas when recommending or confirming Stage 1. The project initialization canvas remains the Stage-1 starting value unless the current user/source context changes it. Template inspection and current-project fit begin only after Stage 1 is confirmed, while authoring Stage 2.
-First, read the role core, then only the modules triggered by the current plan:
+At Step-4 entry, load the always-required planning context directly in one
+batch: the role core, every canonical content-type source file defined below,
+and the compact structured analysis facts already present. These inputs are
+known required reads; do not route or rediscover them one file at a time. For a
+multi-deck `source_profile.json`, read its compact `decks[]` digests in that
+batch and open a deck's larger identity/slide-library files only when the
+specific need below arises.
+
```
Read references/strategist.md
```
+Then load only the extra role modules triggered by the current plan:
+
| Deterministic trigger | Additional Strategist reference |
|---|---|
| Stage 1 is confirmed and Step 3 installed a selected Brand/Style/Layout/Deck workspace into this project | `references/strategist-template.md` before Stage 2 |
@@ -249,62 +264,80 @@ Core chooses Stage-2 sources. Load it before Stage 2 for non-`none`, or after co
**Confirmation orchestration**: field meaning and recommendation logic belong to the active Strategist modules; [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the JSON schema, server lifecycle, staged-result contract, port behavior, and equivalent chat fallback.
-⛔ **BLOCKING**: After Step 3 closes, the three-stage Strategist confirmation is the remaining always-on user gate unless explicitly delegated. Template selection is the earlier independent Step-3 gate, not Stage 1. An enabled `refine_spec` adds the one conditional chat gate after Design Spec Gate 1. In the UI branch, keep Stage 1/2 handoffs in one turn and author the next stage after each wait. In the chat branch, wait for an explicit user response at each stage. Author each stage once; submitted values—including blanks or unusual overrides—are authoritative.
+⛔ **BLOCKING**: The two-stage Strategist confirmation is the remaining always-on user gate unless explicitly delegated: Stage 1 confirms the communication contract, and final Stage 2 confirms the complete deck solution plus production mechanics. A triggered template selection is an earlier independent Step-3 gate, not Stage 1. An enabled `refine_spec` adds the one conditional chat gate after Design Spec Gate 1. In the UI branch, keep the Stage-1 handoff and final Stage-2 handoff in one turn, authoring Stage 2 only after the Stage-1 wait. In the chat branch, wait for an explicit user response at each stage. Author each stage once; submitted values—including blanks or unusual overrides—are authoritative.
-**Confirmation ownership and surface**: Only the user confirms. Before Step 3's
-template-selection phase or any server command, apply `confirm_ui.md`'s surface
+**Confirmation ownership and surface**: Only the user confirms. Before a
+triggered Step-3 template phase or any confirmation server command, apply
+`confirm_ui.md`'s surface
decision to this run's most recent explicit surface instruction and retain that
branch as the owner specifies. A natural-language request or agreement to
personally confirm in chat, or to avoid the page, selects the chat branch without
a magic keyword; skip UI launch/wait commands and UI-authored result state.
Explicit delegation is a separate higher-priority branch. With no surface
-instruction, Step 3 uses the default UI branch, closes template selection and
-installation, then exposes fresh Stage 1. A chat-question tool alone does not
-replace that default. The agent may author recommendations, operate the server,
-read state, and apply the selected template, but MUST NOT confirm on the user's
-behalf, automate submission, synthesize a payload, or write/replace user result
-state. Delegation applies only to this run: show the complete selection plus
-three-stage summary and never fabricate UI results. Silence confirms nothing.
+instruction, use the default UI branch: a triggered Step 3 closes template
+selection/installation first; ordinary free design launches directly with fresh
+Stage 1 and creates no template-selection artifacts. A chat-question tool alone
+does not replace that default. The agent may author recommendations, operate the
+server, read state, and apply a selected template, but MUST NOT confirm on the
+user's behalf, automate submission, synthesize a payload, or write/replace user
+result state. Delegation applies only to this run: show the complete selection
+plus two-stage summary and never fabricate UI results. Silence confirms nothing.
**UI branch files and completion evidence:**
| Input file (only the active unconfirmed Strategist stage may be overwritten) | Agent writes | Completion evidence |
|---|---|---|
-| `confirm_ui/template_options.json` | Step-3 schema/language plus exact explicit roots; library entries remain server-owned index data | User-owned `template_selection.json` with `phase: template`, `status: confirmed` |
-| `confirm_ui/template_handoff.json` | Only through `--complete-template-phase`, after free-design closure or successful project-local installation | `status: ready`, bound to the current selection hash |
+| `confirm_ui/template_options.json` *(triggered Step 3 only)* | Step-3 schema/language plus exact explicit roots; library entries remain server-owned index data | User-owned `template_selection.json` with `phase: template`, `status: confirmed` |
+| `confirm_ui/template_handoff.json` *(triggered Step 3 only)* | Only through `--complete-template-phase`, after free-design closure or successful project-local installation | `status: ready`, bound to the current selection hash |
| `confirm_ui/recommendations.stage1.json` | Communication contract, `content_divergence`, and canvas only | `status: stage1-confirmed` |
-| `confirm_ui/recommendations.stage2.json` | Complete deck solution from the confirmed contract; never skip for a template | `status: stage2-confirmed` |
-| `confirm_ui/recommendations.stage3.json` | Production mechanics only: conditional AI path, formula policy, generation mode, refine-spec, proactive speaker notes, custom animations, and narration audio | `stage: final`, `status: confirmed` |
+| `confirm_ui/recommendations.stage2.json` | `stage: stage2`; complete deck solution plus conditional AI path, formula policy, generation mode, refine-spec, proactive speaker notes, custom animations, and narration audio | `stage: final`, `status: confirmed` |
If the user rejects the current recommendation before confirming it, regenerate by overwriting that same stage file and have the page refresh; do not create revision-suffixed files. This never authorizes one stage file to carry another stage's payload.
-**UI branch only** — Step 3 has already launched the page, received
-`template_selection.json`, completed its bound `template_handoff.json`, and
-left the server live. Create
-`confirm_ui/recommendations.stage1.json`, post the required Stage-1 summary and
-chat fallback using the already printed URL, then:
+**UI branch only** — If the triggered Step 3 ran, retain its live server and
+bound `template_handoff.json`. On the ordinary free-design path, clear any
+prior one-run template artifacts before authoring Stage 1:
-1. Run in order:
+```bash
+python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --reset-template-phase
+```
- ```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1
- ```
+Then create `confirm_ui/recommendations.stage1.json`. The triggered path is
+already live; the ordinary path now launches directly from Stage 1:
-2. Read Stage 1. Only now inspect the installed template state and apply `strategist-template.md` when active. Derive proposed image sources, load the triggered image-planning bundle above, and create `confirm_ui/recommendations.stage2.json` without changing Stage 1, then wait:
+```bash
+# Ordinary free-design path only; triggered Step 3 keeps its existing server.
+python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon
+```
+
+Post `confirm_ui.md`'s actual URL plus the required Stage-1 summary and chat
+fallback, then:
+
+1. Run in order:
```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage2
+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1
```
-3. Read Stage 2; load the image bundle if it newly confirms non-`none`. Create `confirm_ui/recommendations.stage3.json` without changing prior stages and wait:
+2. Read Stage 1. Only now inspect the installed template state and apply
+ `strategist-template.md` when active. Derive the complete deck solution and
+ production defaults, loading the triggered image-planning bundle above.
+ Create `confirm_ui/recommendations.stage2.json` without changing Stage 1;
+ declare `stage: "stage2"`, then wait for the final confirmation:
```bash
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only
```
-4. After the final wait returns, read the complete `result.json` exactly once and retain that object through Design Spec authoring and its fidelity audit. Proceed only when it carries `stage: final` and `status: confirmed`. Do not reopen the file during normal lock authoring or downstream execution. On a non-zero wait, this same single read determines whether the persisted result succeeded before using the documented chat fallback. A stage-skip result returns to the missing stage; it is not a browser failure.
+3. After the final wait returns, read the complete `result.json` exactly once
+ and retain that object through Design Spec authoring and its fidelity audit.
+ Proceed only when it carries `stage: final` and `status: confirmed`. Do not
+ reopen the file during normal lock authoring or downstream execution. On a
+ non-zero wait, this same single read determines whether the persisted result
+ succeeded before using the documented chat fallback. A stage-skip result
+ returns to the missing stage; it is not a browser failure.
-5. After final confirmation or chat fallback, always release the server:
+4. After final confirmation or chat fallback, always release the server:
```bash
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown
@@ -315,10 +348,10 @@ apply `confirm_ui.md`'s in-run switch procedure. Continue the unresolved current
stage and all remaining stages in chat; do not enter UI interruption recovery
or relaunch the server.
-**Chat branch** — run the same three stages in chat with explicit user
+**Chat branch** — run the same two stages in chat with explicit user
responses, retaining one visible cumulative confirmation summary as the
equivalent final state; do not create or require a UI result. If the user
-explicitly delegated confirmation, consolidate the same three stages into one
+explicitly delegated confirmation, consolidate the same two stages into one
AI-authored summary. Otherwise the no-selection UI branch uses the always-on
Stage-1 chat handoff, which keeps direct-chat fallback visible without replacing
UI confirmation.
@@ -340,14 +373,14 @@ For the normal/default `continuous` path, print no split-mode reminder and proce
**Mandatory — spec-refinement note** (not another Confirm UI stage): after confirmation details and any split-mode line, append one localized 💡 line offering review of the complete Design Spec before the lock; any part may be revised in chat until explicit approval. Default OFF; only explicit chat opt-in or `refine_spec: true` runs [`refine-spec`](stages/refine-spec.md) after Gate 1. Confirm UI records the toggle; chat fallback prints the same line.
-**Formula policy**: Stage 3 confirms `mixed`, `render-all`, or `text-only`. When rendering is required, load the image-planning bundle even if `image_usage` is `none`, then follow [`strategist-image.md`](../references/strategist-image.md)'s formula-resource contract. `text-only` creates no formula image rows.
+**Formula policy**: Final Stage 2 confirms `mixed`, `render-all`, or `text-only`. When rendering is required, load the image-planning bundle even if `image_usage` is `none`, then follow [`strategist-image.md`](../references/strategist-image.md)'s formula-resource contract. `text-only` creates no formula image rows.
-**Proactive production decisions**: Stage 3 records
+**Proactive production decisions**: Final Stage 2 records
`proactive_speaker_notes`, `proactive_custom_animations`, and
`proactive_narration_audio`. They control only what the agent initiates when the
user has not already given an explicit instruction. Resolve each effective
-outcome as latest explicit user instruction → Stage 3 value → compatibility
-default `true` / `false` / `false`. Stage 3 Narration Audio enabled raises a
+outcome as latest explicit user instruction → final Stage-2 value → workflow
+default `true` / `false` / `false`. Final Stage-2 Narration Audio enabled raises a
non-explicitly-disabled Speaker Notes outcome to enabled and names that
dependency in its provenance without rewriting the raw proactive preference.
Persist the resolved effective outcomes plus provenance as the `Speaker Notes`,
@@ -459,17 +492,21 @@ Workflow:
**Artifact ownership**: `svg_output/` is the author source, `svg_final/` is derived, and image facts come from the regenerated `analysis/image_analysis.csv`; see [`references/artifact-ownership.md`](../references/artifact-ownership.md).
-Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):
+Read the execution references for this deck's locked `mode` + `visual_style`
+(from `spec_lock.md`). Load this fixed required block directly as one batch;
+do not route among its files one at a time:
```
Read references/executor-base.md # REQUIRED: flat/shared execution core
-Read references/shared-standards-core.md # REQUIRED: SVG compatibility core
-Read references/svg-effects.md # REQUIRED: advanced visual effects and construction vocabulary
+Read references/shared-standards-core.md # REQUIRED: SVG compatibility + shared aesthetic/leading baseline
+Read references/svg-effects.md # REQUIRED: Visual Job Router + effects/construction vocabulary
Read references/native-shape-authoring.md # REQUIRED: native-shape selection and Boolean construction
Read references/semantic-svg.md # REQUIRED: semantic metadata boundary
Read references/modes/<resolved-id>.md # one preset id, or each `mode_references` id
Read references/visual-styles/<resolved-id>.md # one preset id, or each `visual_style_references` id
```
+Keep the core's shared visual-quality defaults and `svg-effects.md` §6.1 Visual Job Router active during page authoring; they are not passive compatibility reading. Explicit user/template requirements and the locked style override compatible aesthetic defaults, never technical Required / Forbidden boundaries.
+
> Read only the always-on references above plus the conditionally triggered modules below. A preset reads its one locked file. For `mode: custom` or `visual_style: custom`, read every exact file named by the optional `mode_references` / `visual_style_references`, then synthesize those sources under the corresponding behavior. If the reference field is absent, the direction is genuinely novel: read no preset file and follow the behavior directly. Never infer adjacent references or glob `modes/` / `visual-styles/`.
| Deterministic trigger | Additional references |
@@ -656,7 +693,7 @@ stage preserves or produces `<project_path>/animations.json`, keep the base comm
the exporter reads the sidecar automatically. Explicit motion flags override
the corresponding sidecar default/slide fields, while group overrides remain
unless `-a none` hard-disables object motion. Exception: explicit Custom
-Animations disable keeps the sidecar and appends `-a none`; Stage 3 `false`
+Animations disable keeps the sidecar and appends `-a none`; final Stage-2 `false`
does neither. Only explicit all-motion disable uses `--no-animations`.
Otherwise do not mix deck-wide flags with a sidecar. With no motion input or
sidecar, preserve `fade` / `none`.
diff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.md
index f240ffa0..fe4dd9ab 100644
--- a/skills/ppt-master/workflows/governance/failure-recovery.md
+++ b/skills/ppt-master/workflows/governance/failure-recovery.md
@@ -17,7 +17,7 @@ Global stop/continue rules for all four top-level routes, plus concrete failure
| Confirm UI launch failure | No | Re-check `confirm_ui/result.json` once, then use chat fallback | No | [`generate-pptx`](../generate-pptx.md) Step 4 chat confirmation |
| Confirm UI wait timeout | No, if no final result yet | Re-check `result.json` once; keep server cleanup mandatory | Only if user still wants the page | Step 4 same stage or chat fallback |
| User explicitly switches from Confirm UI to chat during any stage | Yes until the unresolved current stage is confirmed | Follow [`confirm_ui.md`](../../scripts/docs/confirm_ui.md)'s in-run switch, retain persisted confirmed stages, then continue the current and remaining stages in chat; never relaunch UI | Confirm in chat unless explicitly delegated | Step 4 current chat stage |
-| Confirm UI Stage 1 completed then unexpectedly interrupted while UI remains selected | Yes until Stage 2 is written/confirmed | Read existing Stage 1 `result.json`, create `recommendations.stage2.json` without changing Stage 1, then `--wait-only --wait-stage stage2` | Usually no | Step 4 Stage 2 write/wait |
+| Confirm UI Stage 1 completed then unexpectedly interrupted while UI remains selected | Yes until final Stage 2 is written/confirmed | Read existing Stage 1 `result.json`, derive a fresh `recommendations.stage2.json` without changing Stage 1, then `--wait-only` for final confirmation | Usually no | Step 4 final Stage 2 write/wait |
| Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation |
| Final confirmed value or a later explicit user override is missing, changed, substituted, or weakened in `design_spec.md` | Yes | Repair from the retained final-confirmation object plus any newer explicit instruction; only a fresh recovery turn with no retained state reads persisted final evidence once | Only when the effective value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity |
| `spec_lock.md` changes confirmed identity or omits a required execution anchor/routing decision | Yes | Re-author the affected lock rows from the completed Design Spec and current context; do not enumerate page-local literals | No unless the Design Spec itself is incomplete | Step 4 Gate 2 — lock context fidelity |
@@ -60,8 +60,8 @@ Global stop/continue rules for all four top-level routes, plus concrete failure
**Forbidden — silent downgrade**: Do not skip a required gate because a downstream command might tolerate the missing file, and do not change a confirmed execution value merely to keep the route moving. Fix, pause, or request a new decision at the owning boundary.
-**Proactive production compatibility**: Keep Stage 3 raw fields as evidence.
-Resolve durable outcomes as explicit instruction → Stage 3 → legacy defaults
+**Proactive production resolution**: Keep final Stage-2 raw fields as evidence.
+Resolve durable outcomes as explicit instruction → final Stage 2 → workflow defaults
`enabled` / `disabled` / `disabled`. Audio raises Notes only when Notes is not
explicitly disabled; an explicit notes-off/audio-on conflict stops at
Generate's one-question dependency gate. Keep raw values unchanged and record
@@ -79,13 +79,12 @@ in-run switch and resumes the unresolved stage in chat without relaunching UI.
| Last good state | Resume from |
|---|---|
-| Stage 1 confirmation exists, Stage 2 missing, and UI remains selected | Create `recommendations.stage2.json` without changing Stage 1, then `confirm_ui/server.py <project> --wait-only --wait-stage stage2` |
-| Stage 2 confirmation exists, final confirmation missing, and UI remains selected | Resume [`generate-pptx`](../generate-pptx.md) Step 4 confirmation orchestration at Stage 3: derive production mechanics from the confirmed solution, create `recommendations.stage3.json` without changing earlier stages, then perform the final wait. |
+| Stage 1 confirmation exists, final Stage 2 is missing or unconfirmed, and UI remains selected | Derive a fresh `recommendations.stage2.json` from confirmed Stage 1 and current inputs without changing Stage 1, then run `confirm_ui/server.py <project> --wait-only` for final confirmation. |
| Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to Generate Step 4 and [`strategist.md`](../../references/strategist.md) §6.2; read final evidence once into the fresh context, read [`design_spec_reference.md`](../../templates/design_spec_reference.md), author the complete `design_spec.md` from scratch using that state plus source analysis, and pass Gate 1. Then read [`spec_lock_reference.md`](../../templates/spec_lock_reference.md) and re-author the complete `spec_lock.md` from the audited Design Spec plus current context, replacing any orphan lock. Never reconstruct the Design Spec from an orphan lock or retain orphan-lock choices as authority. |
| Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to Generate Step 4; in this fresh recovery context read final evidence once to audit the existing Design Spec, then read [`spec_lock_reference.md`](../../templates/spec_lock_reference.md) and author the complete lock from the audited Design Spec plus current context. |
| Final confirmation evidence and both planning artifacts exist, but Gate 1 fails | In a fresh recovery context read final evidence once, repair `design_spec.md`, then re-author every affected lock row. Do not reopen recommendations or infer a replacement from the current lock. |
| Gate 1 passes but Gate 2 fails | Keep the Design Spec unchanged and re-author only the mismatched lock anchors/routing rows from it plus current context. |
-| No final confirmation evidence is available | Resume Step 4 from the latest stage evidenced by `confirm_ui/result.json`; if no stage is persisted, restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. |
+| No final confirmation evidence is available | If `confirm_ui/result.json` proves Stage 1 confirmation, resume at final Stage 2; otherwise restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. |
| `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/resume-execute.md) |
| Images acquired but SVGs not started | [`generate-pptx`](../generate-pptx.md) Step 6 |
| SVGs complete and checker passed; effective Speaker Notes outcome enabled and notes missing | Step 6 Logic Construction |
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
index 4d566a73..ed10adc3 100644
--- a/skills/ppt-master/workflows/index.md
+++ b/skills/ppt-master/workflows/index.md
@@ -21,7 +21,7 @@ Maintainer-only inventory for adding, moving, or removing workflow documents. Ru
|---|---|---|---|
| `beautify-pptx` | Generation profile | [`profiles/beautify-pptx.md`](./profiles/beautify-pptx.md) | Generate PPTX |
| `quick-generate` | Generation profile | [`profiles/quick-generate.md`](./profiles/quick-generate.md) | Generate PPTX direct SVG-to-PPTX short circuit |
-| `apply-template-workspace` | Template-input stage | [`stages/apply-template-workspace.md`](./stages/apply-template-workspace.md) | Default Generate Step 3 or Quick direct exact-root input |
+| `apply-template-workspace` | Template-input stage | [`stages/apply-template-workspace.md`](./stages/apply-template-workspace.md) | Conditional Default Generate Step 3 or Quick direct exact-root input |
| `create-brand` | Template child workflow | [`create-template/create-brand.md`](./create-template/create-brand.md) | Create Template |
| `create-style` | Template child workflow | [`create-template/create-style.md`](./create-template/create-style.md) | Create Template |
| `create-layout` | Template child workflow | [`create-template/create-layout.md`](./create-template/create-layout.md) | Create Template |
diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.md
index c2fbfebf..bd386623 100644
--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md
+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md
@@ -166,10 +166,10 @@ This step has two halves:
**Visual re-confirm — full confirmation seeded from the source**:
Apply [`generate-pptx`](../generate-pptx.md) Step 4's surface decision first. In
-the default UI branch, use the three
-`<project_path>/confirm_ui/recommendations.stageN.json` files at the same staged
-handoffs and launch the same confirm server. In the chat branch, present the
-same three stages and fields without launching the server or requiring
+the default UI branch, use
+`<project_path>/confirm_ui/recommendations.stage1.json` and
+`recommendations.stage2.json` at the same two handoffs and launch the same
+confirm server. In the chat branch, present the same two stages and fields without launching the server or requiring
`result.json`. The active, unconfirmed UI stage may be overwritten for a
requested regeneration; normal progression leaves confirmed earlier stages
intact. Do **not** hide fields: seed **every** targeted-confirmation field with
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index bf2bc163..18227286 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -157,7 +157,8 @@ silently replace it with unrelated material.
## 3. Direct SVG Authoring
-Always read
+Always read the following fixed authoring references directly in one batch; do
+not route among them one file at a time:
[`shared-standards-core.md`](../../references/shared-standards-core.md),
[`svg-effects.md`](../../references/svg-effects.md), and
[`native-shape-authoring.md`](../../references/native-shape-authoring.md). Do
@@ -171,6 +172,8 @@ this profile. For any image/formula, always read
web image. Load [`canvas-formats.md`](../../references/canvas-formats.md) only
for a non-default canvas.
+Keep the core's shared visual-quality / leading defaults and `svg-effects.md` §6.1 Visual Job Router active while authoring. Explicit user/template requirements and the resolved style override compatible aesthetic defaults, never technical Required / Forbidden boundaries.
+
Use one zero-padded filename width sized for the resolved roster, such as
`01_cover.svg` through `12_end.svg` or `001_cover.svg` through `120_end.svg`.
Never reuse pages from another run: the exporter publishes every SVG discovered
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index f10e6d78..09ae0db9 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -45,7 +45,8 @@ route selection. After selection, the route authority owns execution.
| Topic only, or supplied sources leave planning-critical factual gaps | Run [`topic-research`](./stages/topic-research.md) inside the selected Generate profile's source preparation: immediately for topic-only input, or after conversion and reading for source-backed input; research only the identified gaps |
| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through [`generate-pptx`](./generate-pptx.md) Step 1 and its PPTX intake; continue the default pipeline unless explicit Quick Generate intent selected that profile |
| Existing PPTX must preserve wording, page count, and page order 1:1 | Activate the [`beautify-pptx`](./profiles/beautify-pptx.md) profile inside the main pipeline |
-| Default Generate reaches Step 3 | Complete the independent template-selection phase before Stage 1. The UI offers only index-registered library roots plus any user-supplied explicit roots; confirmed non-free selections run [`apply-template-workspace`](./stages/apply-template-workspace.md) |
+| Default Generate has no explicit template-discovery/selection request, exact workspace root, or current Create Template handoff | Use free design and proceed directly to Stage 1; do not read template indexes or create template-selection artifacts |
+| Default Generate explicitly requests template discovery/selection, supplies an exact current workspace root, or receives a current Create Template handoff | Run the conditional Step-3 template-selection phase before Stage 1. The UI offers only index-registered library roots plus supplied explicit roots; confirmed non-free selections run [`apply-template-workspace`](./stages/apply-template-workspace.md) |
| Explicit current brand/style/layout/deck workspace root | Default Generate preserves the exact-path path through Step 3; Quick Generate validates and installs it directly without Step 3 or Confirm UI. Classify it as `library` only when its normalized root exactly matches a registered index entry; otherwise retain `explicit`. Consume the workspace root, never only its inner `templates/` directory |
| Split-mode project resumes in a fresh chat | Run [`resume-execute`](./stages/resume-execute.md) inside the active Generate route |
| Existing generated project needs a deck-wide `colors.*` or universal `typography.font_family` substitution | Stay in Generate; load [`update_spec.py`](../scripts/docs/update_spec.md), honor its supported-key boundary, then rerun the final quality gate and Step 7 export |
@@ -129,7 +130,8 @@ Object animation for generated SVG projects uses the animation stage. Native PPT
| User input | Behavior |
|---|---|
-| Default UI reaches Step 3 | Offer free design plus registered library workspaces from the four indexes below; confirm and install before Stage 1 |
+| No explicit template intent/root/handoff | Skip Step 3, use free design, and open Stage 1 directly without reading indexes |
+| Explicit template discovery or selection request | Enter Step 3; offer free design plus registered library workspaces from the four indexes below, then confirm and install before Stage 1 |
| Explicit current workspace root containing `templates/design_spec.md` | Preserve it as an `explicit` Step-3 candidate; an exact registered-root match may be displayed as `library` |
| Bare template/brand name or style label | Do not resolve it to a local path; treat it as a style brief |
| “What templates exist?” in chat | List indexed workspace paths; selection still requires the user to return an exact root |
@@ -144,10 +146,11 @@ corresponding directories to construct or supplement the catalog:
| Layout | [`layouts_index.json`](../templates/layouts/layouts_index.json) |
| Deck | [`decks_index.json`](../templates/decks/decks_index.json) |
-**Hard rule — selection precedes communication confirmation**: Template
-selection is a standalone Step-3 phase. Confirm free design or selected roots,
-run workspace validation/installation, then begin Stage 1. Stage 2
-`template_application` decides how the already installed template is used; it
+**Hard rule — triggered selection precedes communication confirmation**: When
+Step 3 is triggered, confirm free design or selected roots and complete
+workspace validation/installation before Stage 1. In an ordinary free-design
+run, no selection phase exists and Stage 1 starts directly. Stage 2
+`template_application` decides how an already installed template is used; it
never selects a template.
**Forbidden — fuzzy resolution**: Never resolve a bare name to a local template
diff --git a/skills/ppt-master/workflows/stages/apply-template-workspace.md b/skills/ppt-master/workflows/stages/apply-template-workspace.md
index 6a9fde0d..875c8b89 100644
--- a/skills/ppt-master/workflows/stages/apply-template-workspace.md
+++ b/skills/ppt-master/workflows/stages/apply-template-workspace.md
@@ -4,13 +4,13 @@ description: Generate-PPTX runbook for validating, installing, or fusing selecte
# Apply Template Workspace Stage
-> Run from [`generate-pptx.md`](../generate-pptx.md) Step 3 after the user confirms the dropdown-composed library/explicit workspace roots, or directly from [`quick-generate`](../profiles/quick-generate.md) when the request supplies exact roots or Create Template hands off its exact validated root in the current conversation. Never load this stage for default confirmed free design, Quick with no exact root, a bare template name, a style description, or a brand mention. This stage applies a completed selection; it never chooses a template or moves template choice into Stage 1 or Stage 2.
+> Run from [`generate-pptx.md`](../generate-pptx.md) Step 3 only for explicit template browsing/selection, exact roots, or a current Create Template handoff. [`quick-generate`](../profiles/quick-generate.md) enters only for exact roots or that handoff. Never load for free design, bare names, or style descriptions. This stage applies a completed selection; it never chooses one or moves template choice into Stage 1/final Stage 2.
## 1. Gate and Normalize Inputs
-🚧 **GATE**: Either the default Step-3 template selection is confirmed, or
-Quick received the exact roots directly from the user/current Create Template
-handoff. In Quick, that explicit input is the complete selection authority: do
+🚧 **GATE**: Either Default Step 3 was explicitly triggered and its template
+selection is confirmed, or Quick received exact roots directly from the
+user/current Create Template handoff. In Quick, that explicit input is the complete selection authority: do
not launch Confirm UI or create `template_options.json`,
`template_selection.json`, or `template_handoff.json`. Every selected input must
resolve to one of these current contracts:
@@ -37,9 +37,9 @@ valid without index membership; exact equality with a registered root may be
reported as `library`. The label changes discovery provenance only, never schema
validation, fusion precedence, or installation behavior.
-**Selection cardinality**: The default page permits one registered root per kind plus one explicit root; its explicit root may pair with a same-kind library root under §5.2. Quick has no page or catalog selection and accepts at most one supplied exact root per declared kind (four roots total). Kinds compose freely in both profiles. Reject larger default receipts server-side; require an oversized or duplicate-kind Quick input to converge in chat before installation, never through Confirm UI.
+**Selection cardinality**: When Default Step 3 is explicitly triggered, its template page permits one registered root per kind plus one explicit root; its explicit root may pair with a same-kind library root under §5.2. Quick has no page or catalog selection and accepts at most one supplied exact root per declared kind (four roots total). Kinds compose freely in both profiles. Reject larger default receipts server-side; require an oversized or duplicate-kind Quick input to converge in chat before installation, never through Confirm UI.
-**Hard rule — raw source boundary**: A raw PPTX is not a Step 3 workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first and return with its validated workspace root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
+**Hard rule — raw source boundary**: A raw PPTX is not a Step 3 workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first; its validated workspace-root handoff triggers Step 3. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
**Compatibility gate**: Reject semantic-legacy or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved. A legacy-flat Brand/Layout/Deck directory is readable only when it satisfies its current kind contract; Layout/Deck also require a current structured SVG contract. Style has no legacy-flat form and always requires `<root>/templates/design_spec.md`.
@@ -99,7 +99,7 @@ For a compatible legacy-flat package, route SVG/spec/non-bitmaps to project `tem
If the normalized source root equals the target project root, consume it in place and copy nothing. An in-place workspace cannot participate in multi-path fusion. Ignore source `exports/`; it contains review artifacts, not portable template inputs. Empty optional roots remain absent.
**Hard rule — project-local consumer boundary**: After installation/fusion,
-Default template-aware Strategist work from Stage 2 onward, Quick's current
+Default template-aware Strategist work in final Stage 2, Quick's current
agent before direct authoring, and every later role read only
`<project_path>/templates/` and the project-local `images/` / `icons/` pools. The original library or external root
is installation input, not a later prompt source. If source and target are the
@@ -120,7 +120,7 @@ Resolve four whole template segments. This table selects the installed starting
| Segment | Starting owner |
|---|---|
-| Identity | Brand, otherwise Deck, otherwise unresolved until the consuming plan (Default Stage 2 or Quick active context). Style color/type/icon/image values are direction candidates, never identity truth. |
+| Identity | Brand, otherwise Deck, otherwise unresolved until the consuming plan (Default final Stage 2 or Quick active context). Style color/type/icon/image values are direction candidates, never identity truth. |
| Structure | A compatible Layout, otherwise Deck, otherwise unresolved/free design until the consuming plan. Style owns no canvas, prototype, Master/Layout, slot, or page mapping. |
| Reusable application context | Deck only when present. Preserve it for the consuming comparison; it never becomes the current project's application contract. |
| Direction / method | Style when present, otherwise unresolved until the consuming plan. Actual Deck prototypes and Signature facts may inform compatibility, but Deck does not own the Style-only method segment. |
@@ -129,7 +129,7 @@ Replace each selected segment wholesale; do not mix its fields implicitly. Brand
Before Layout overrides Deck structure, compare Deck's reusable roles with Layout roles, slots, and capacity. On mismatch, offer exactly three remedies: retain Deck structure, select another Layout, or omit Deck. Default must not invent the current project contract before Stage 1; Quick compares against the current request/content and treats any unresolved material mismatch as a chat hard prerequisite.
-Before Style overlays Deck guidance, verify that its method serves Deck's reusable context and fits the selected structure. On mismatch, require omitting Style or choosing a compatible Style/structure; never silently weaken a segment. Default Stage 2 separately checks the result against the confirmed project contract; Quick checks it against the current request/content before authoring.
+Before Style overlays Deck guidance, verify that its method serves Deck's reusable context and fits the selected structure. On mismatch, require omitting Style or choosing a compatible Style/structure; never silently weaken a segment. Default final Stage 2 separately checks the result against the confirmed project contract; Quick checks it against the current request/content before authoring.
Field-level micro-adjustments such as a primary-color override are not workspace fusion. Default carries them into the normal Strategist confirmation fields; Quick treats explicit adjustments as direct transient authoring constraints.
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index 6aedf8c9..9750633a 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -27,9 +27,9 @@ description: Optional post-processing stage for per-slide and per-object animati
| No existing sidecar; user only wants deck-wide page transitions, auto-advance, or one per-element object animation policy | Do not run; apply [`animations.md`](../../references/animations.md) with exporter flags such as `-a auto` or `-a emphasis_spin` |
| `svg_output/*.svg` is missing | Complete the main Executor phase first |
-**Decision precedence**: latest explicit instruction → Stage 3 policy →
-compatibility default `false`; provenance stays in Design Spec §I, never the
-lock. Stage 3 `false` blocks creation, not an existing sidecar. Existing
+**Decision precedence**: latest explicit instruction → final Stage-2 policy →
+workflow default `false`; provenance stays in Design Spec §I, never the
+lock. Final Stage-2 `false` blocks creation, not an existing sidecar. Existing
sidecars enter this stage; explicit disables follow the table without deletion.
---
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index f9ce937b..85ab1c3b 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -240,7 +240,7 @@ The edge command writes each MP3 and its internal page SRT from the same `edge-t
| Both are absent | Create no sidecar; inherit the base report's deck motion |
Generate passes the base report through `--inherit-motion-from`: inherited
-`-a none` preserves explicit objects-off, while Stage 3 `false` does not.
+`-a none` preserves explicit objects-off, while final Stage-2 `false` does not.
Only explicit all-motion-off uses `--no-animations`. Invalid reports block;
audio duration plus padding owns final advance.
diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.md
index f86da686..4263e670 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -52,7 +52,7 @@ Then jump to `### Step 6: Executor Phase` and run the documented pipeline:
- Read the complete project Design Spec, then the complete `spec_lock.md`, once to establish the fresh execution context
- Resolve the effective Speaker Notes, Custom Animations, and Narration Audio
- outcomes from `design_spec.md §I`. Missing legacy outcomes use
+ outcomes from `design_spec.md §I`. Missing outcomes use the workflow defaults
`enabled` / `disabled` / `disabled`; these production decisions never come
from `spec_lock.md`
- If resuming mid-deck, read the latest completed SVG and current image metadata when images are used
@@ -71,7 +71,7 @@ Then jump to `### Step 6: Executor Phase` and run the documented pipeline:
Reload the Generate authority and required execution references; do not reconstruct or replay the earlier planning conversation.
-If the user gives a newer explicit instruction after Stage 3, update only the
+If the user gives a newer explicit instruction after final Stage 2, update only the
affected effective outcome and provenance in `design_spec.md §I`, then resume at
its owning step. Do not reopen Confirm UI or add the decision to
`spec_lock.md`. Before writing, apply Generate's single notes/audio dependency