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(confirm-ui): merge template selection into Stage 1

hugohe3965e829acebe
diff --git a/AGENTS.md b/AGENTS.md
index d9c6ec4f..3aef1cb9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,8 +11,9 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate
**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.
- Topic-only or fact-insufficient inputs run [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) in Generate Step 1; facts only, no images.
+- Default Generate prepares template candidates internally in Step 3, then confirms the communication contract and free-design/template choice together in Stage 1. Template content stays unread until that confirmation; selected roots are installed before template-aware Stage 2. Quick skips this interaction.
- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.
-- Raw PPTX cannot be consumed as a Generate Step 3 SVG template; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated template workspace root. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.
+- Raw PPTX cannot be consumed as a Generate template workspace; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated workspace root as a Stage-1 candidate. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.
- Explicit quick/fast or skip-strategy generation may use [`quick-generate`](skills/ppt-master/workflows/profiles/quick-generate.md): prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author `svg_output/`, pass its lockless final checker, and export.
- PPTX beautify is a strict 1:1 main-generation [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), not a separate route; any split/merge/drop/reorder uses the default main-pipeline policy.
- Finished PPTX native enhancement uses [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) and must not enter SVG regeneration.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 84105811..a85e5bd4 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -29,7 +29,7 @@ The short path to your first deck, how to use everything around it — templates
For the first, give the AI your `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" — see the [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md). The rest of this section covers create-template.
-**To build a reusable workspace from an existing PowerPoint, explicitly request the Create Template route.** A raw `.pptx` plus new material otherwise belongs to Fill Native PPTX; it is not a Generate PPTX Step 3 template. Create the workspace first:
+**To build a reusable workspace from an existing PowerPoint, explicitly request the Create Template route.** A raw `.pptx` plus new material otherwise belongs to Fill Native PPTX; it is not a Generate template workspace. Create the workspace first:
```
You: Create a reusable Deck template from projects/brand/our_deck.pptx via /create-template
@@ -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 |
-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.
+Default Generate shows the template choice inside Stage 1, beside the communication contract. The initial communication recommendation is written without reading any template. Ordinary requests start with free design; explicit template intent or any exact root starts in template mode, and the user can always switch. 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. Exactly one supplied root may be preselected; multiple supplied roots remain unselected candidates. One confirmation closes communication and template choice together. Only then are selected workspaces validated and installed; template-aware planning begins in final Stage 2. A bare template name never resolves to a workspace. 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. 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:
+2. **Tell the AI in chat** what to turn into a deck. Stage 1 then lets you confirm the communication contract together with free design or template use; add one exact workspace root when you want template mode and that path preselected:
```
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, 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.
+Before generation, Stage 1 confirms the communication contract, canvas/format, and free-design/template choice together. The AI then installs any selected workspace; final Stage 2 reads that installed state and confirms page count, the visual system, template application, and production choices. From there it 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 its two-stage design confirmation, plus Step 3 only when template selection is explicitly triggered. To skip that interaction, explicitly ask for **quick generation**:
+The default flow runs its combined Stage-1 communication/template choice followed by final Stage 2. 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/technical-design.md b/docs/technical-design.md
index 25c62425..ddf0424f 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -59,9 +59,9 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
├── 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, 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
+[Template Candidate Preparation (Step 3)] — internal only; no UI, wait, selection, template read, or installation
+ Prepare indexed Brand/Style/Layout/Deck candidates and supplied exact roots
+ Stage 1 confirms communication plus free design/template use together; selected workspaces are then validated/fused before Stage 2
Raw PPTX template requests route to template-fill; reusable SVG templates are created by create-template first
↓
[Strategist] - Stage 1 communication confirmation + final Stage 2 solution/production confirmation → design_spec.md + spec_lock.md
@@ -168,9 +168,8 @@ Use this table before reasoning about implementation details. Most failed runs s
| Raw PPTX template plus new material/topic | Fill Native PPTX (`template-fill-pptx`) | clone/fill native slides; no SVG generation |
| Existing PPTX, preserve page count/order/wording 1:1, improve layout | Generate PPTX + `beautify-pptx` profile | regenerate through SVG; content and pagination are locked |
| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Enhance Native PPTX (`native-enhance-pptx`) | direct OOXML patch; no design regeneration |
-| User wants a reusable template workspace from 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 |
-| 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 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 as a Generate Stage-1 candidate; structured children may export a review PPTX |
+| Default Generate reaches planning; an exact current-contract workspace root or current Create Template handoff may already be present | Generate PPTX Stage 1 | Step 3 prepares candidates without interaction; Stage 1 confirms communication plus free design/template use together; ordinary requests default to free design, explicit template intent or any root defaults to template mode, and only one root is preselected; selected workspaces are validated/fused before Stage 2 |
| 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 |
@@ -353,7 +352,7 @@ These invariants are stronger than ordinary implementation preferences. If a cha
| PowerPoint Convert to Shape is outside the compatibility contract | `svg_final/` may be inserted as an SVG picture, but the converted structure and visual result are not guaranteed and do not constrain the supported SVG feature set |
| Direct OOXML routes do not enter the SVG pipeline | preservation workflows patch native PPTX parts directly |
| Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; in the default pipeline Strategist uses source context first and inspects only a specifically ambiguous asset when semantics or safe placement cannot otherwise be resolved, while in `quick-generate` the current agent applies the same bounded analysis while preparing resources; SVG authoring does not rescan source pixels |
-| Raw PPTX templates are not Step 3 templates | Step 3 consumes reusable template directories only |
+| Raw PPTX templates are not Step 3 candidates | Step 3 accepts only exact reusable-template workspace roots as candidate input |
---
@@ -365,21 +364,21 @@ The architectural choice worth flagging: **viewBox is in pixels, not absolute un
---
-## Template System & Optional Path
+## Template System & Selection
-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.
+Template use is **opt-in, not inferred**. Default Step 3 only prepares
+candidates; it never opens UI or reads template content. Stage 1 displays its
+template-independent communication recommendation together with a switchable
+free-design/template choice. Ordinary requests default to free design; explicit
+template intent or any supplied root defaults to template mode. Exactly one root
+may be preselected, while multiple roots remain unselected candidates. 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.
+**Why free design remains an explicit option.** 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 reports), while the selector keeps the final choice with the user.
**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 triggered page lists registered
+style" is never fuzzy-matched to a directory. The default 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
@@ -409,11 +408,12 @@ 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>/`. 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
-Stage 1. The source workspace remains portable between
+another exact workspace root such as `projects/<name>/`. Step 3 records it as
+candidate input without reading template content. Once Stage 1 selects it, the
+apply stage validates, fuses, and installs it 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 Stage 1. The source workspace remains portable between
locations without reshaping; global index registration controls whether it
appears as a library choice.
@@ -452,7 +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.
-**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.
+**Template choice and communication share Stage 1.** Step 3 prepares candidates
+without interaction, while the Stage-1 communication recommendation is authored
+without reading those candidates or any template content. The UI confirms that
+communication contract and the switchable free-design/template choice together;
+only afterward does the agent install/fuse a non-free selection. 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 proactive values confirmed in final Stage 2 remain independent raw
evidence. In particular, enabling narration may enable the effective Speaker
@@ -784,7 +789,7 @@ The tempting simplifications below have explicit costs. Treat them as negative c
| Do not collapse or add | Why |
|---|---|
-| Do not fuzzy-match template names or style phrases to library paths | Step 3 must be deterministic; wrong template selection is harder to recover from than free design |
+| Do not fuzzy-match template names or style phrases to library paths | Template selection must be deterministic; applying the wrong workspace is harder to recover from than free design |
| Do not treat a raw PPTX template as a Step 3 template | when used as a template/page shell, it belongs to native cloning/filling; source use, 1:1 beautify, and restructuring instead follow their Generate boundaries rather than passing a PPTX directly to Step 3 |
| Do not merge `template-fill-pptx`, `beautify-pptx`, and `native-enhance-pptx` into one "PPTX optimization" route | their preservation contracts differ: native fill, 1:1 redesign, and direct enhancement are separate operations |
| Do not script-generate batches of Executor SVG pages | cross-page design judgment depends on sequential main-agent authoring |
@@ -808,7 +813,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` | 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 |
+| Template-input stage | `apply-template-workspace` | Runs after Default Stage 1 confirms at least one workspace and before Stage 2; free design skips installation, while Quick may provide direct exact-root input |
| 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 7765cb89..60f1d6ab 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -98,7 +98,13 @@ Both roots have the same core shape:
└── <id>_template_preview.pptx
```
-Empty optional directories are omitted; do not add placeholder files. A preview PPTX is derived review evidence, not a source template asset. It is generated on request and is mandatory for a multi-Master package gate. Step 3 reads the workspace root and consumes `templates/` plus any existing `images/` and `icons/`; it ignores `exports/`. Library `exports/` directories are Git-ignored.
+Empty optional directories are omitted; do not add placeholder files. A preview
+PPTX is derived review evidence, not a source template asset. It is generated
+on request and is mandatory for a multi-Master package gate. Step 3 records the
+workspace root as candidate input without reading its content. After Stage 1
+selects it, the apply stage consumes `templates/` plus any existing `images/`
+and `icons/`; it ignores `exports/`. Library `exports/` directories are
+Git-ignored.
Imported vectors use `data-icon="imported/<name>"` and have one canonical file
at `icons/imported/<name>.svg`. Workspace-aware validation and export resolve
@@ -377,10 +383,11 @@ These indexes cover library scope only. A project-root workspace is intentionall
### Segment ownership (implicit dispatch)
-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:
+When Stage 1 confirms registered and/or specified workspace roots, the
+post-confirmation apply stage 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 |
|---|---|
@@ -431,7 +438,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 explicitly triggered template page already narrows this space: Brand/Style/Layout/Deck each have
+The Default 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
@@ -454,9 +461,25 @@ This lets both AI and humans trace which segment came from where.
---
-## 5. Relationship with Generate PPTX Step 3
-
-**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**:
+## 5. Relationship with Generate PPTX Stage 1
+
+Default Generate [Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-candidate-preparation)
+only prepares candidate input. Stage 1 presents the communication contract and
+the switchable free-design/template choice together. Ordinary requests start in
+free design with detailed controls collapsed; explicit template intent or any
+exact root starts in template mode. Exactly one supplied root is preselected,
+while multiple roots remain unselected candidates. A bare template/brand name
+or style phrase never resolves to or preselects a workspace. For every selected
+workspace, the post-confirmation apply stage 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 selected path**:
| User path's `kind` | Step 3 action (per-kind branch) |
|---|---|
@@ -467,11 +490,11 @@ This lets both AI and humans trace which segment came from where.
| Multi-path | Fuse one `design_spec.md` per the table above, then merge the existing portable roots after resolving collisions |
| Same-kind multiple | Run the "git-style conflict resolution" prompt above to determine the merge |
-Bitmaps share the workspace `images/` pool and template SVGs reference them through `../images/`. If the explicit input root is already the target project's root, Step 3 consumes the workspace in place: do not copy it onto itself and do not move its assets again. Otherwise, the complete core workspace is portable: it may be copied from a project root to a library root, from the library to a project, or reused from another workspace without changing its internal structure. Registration is the only scope-specific step.
+Bitmaps share the workspace `images/` pool and template SVGs reference them through `../images/`. If the explicit input root is already the target project's root, the apply stage consumes the workspace in place: do not copy it onto itself and do not move its assets again. Otherwise, the complete core workspace is portable: it may be copied from a project root to a library root, from the library to a project, or reused from another workspace without changing its internal structure. Registration is the only scope-specific step.
### 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 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.
+Installing a template does not narrow away the communication question. Stage 1 confirms the same open communication contract together with, but independently from, the template choice. The communication recommendation uses only the current request, source facts, conversation constraints, and project initialization; even template canvas is excluded. Only after Stage 1 closes and any selection is installed does final Stage 2 inspect that 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. Confirm UI exposes Free design / Use templates and candidate selectors, but not internal reuse/adherence 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 e0e9321e..28014368 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 → conditional 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 → Stage-1 template controls** | `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.
@@ -43,16 +43,23 @@ stay separate.
The two rules that prevent most mistakes:
-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.
+1. Default Generate [Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-candidate-preparation) only prepares candidates. Stage 1 confirms the communication contract and free-design/template choice together.
+2. Ordinary requests start in free design. Explicit template intent or any exact workspace root opens template mode; exactly one supplied root is preselected, while multiple roots remain unselected candidates. A non-free selection is installed after Stage 1 and before template-aware final Stage 2.
---
## 1. Use an existing template
-### How to trigger
+### How selection works
-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.
+Default Generate places template selection inside **Stage 1**, beside the
+template-independent communication contract. The page first shows switchable
+Free design / Use templates choices. Ordinary requests initialize Free design
+and keep the detailed selectors collapsed. Explicit template intent or any
+exact workspace root initializes Use templates and expands the registered
+Brand/Style/Layout/Deck plus supplied-root candidates. Exactly one supplied root
+is preselected; multiple roots remain unselected candidates. The system does
+not infer a specific template from the topic.
> **Quick Generate exception:** Quick never opens that page. Up to one exact
> workspace root per kind supplied in the request is validated, installed, and
@@ -60,28 +67,45 @@ Ordinary Default Generate does not enter Step 3. It uses free design and opens S
> resolve. Quick remains a lockless flat export, so Layout/Deck prototypes are
> authoring inputs rather than reusable native Master/Layout output.
-### How to enter the template flow
+### How to use the selector
-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:
+On the Stage-1 page, choose Free design or Use templates. Only Use templates
+reveals five compact dropdowns: one each for registered Brand, Style, Layout,
+and Deck workspaces, plus one for exact roots supplied for this run. Each is
+single-select and includes `None`; the four registered kinds can be combined,
+and the specified-root channel contributes at most one workspace. The lists
+come only from the four kind indexes; the workflow never scans the template
+directories. Send an exact Brand/Style/Layout/Deck workspace root in chat when
+you want template mode opened and that sole path preselected. Anywhere in the
+sentence is fine; the path just has to be unambiguous:
> "use this template: `skills/ppt-master/templates/layouts/presentation_core/`" ✅
> "use last deck's template: `projects/last_deck/`" ✅
> "make a product introduction with `/Users/me/Desktop/our_brand_v3/`" ✅
-For every current template kind, 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.
+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. Stage 1 validates the selected candidate roots; after confirmation, 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 the next Stage-1 selector in the same conversation.
-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.
+Template selection shares the Stage-1 screen and submit action but remains a
+separate sidecar decision. The communication recommendation is authored only
+from the current request, source facts, conversation constraints, and project
+initialization; candidate metadata, selected roots, installed content, and
+template canvas cannot influence it. After the combined confirmation, a
+non-free choice runs the common apply stage and installs/fuses the selected
+workspaces into the project's `templates/`, `images/`, and `icons/`. Final
+Stage 2 then compares the confirmed communication contract with that installed
+state; `template_application` describes **how** to use it 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
+### What does NOT select a template automatically
-- **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.
+- **A bare template name in chat**: "presentation_core" / "China Telecom template" does not resolve implicitly or preselect a workspace. Choose the registered 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 selects 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. Explicit template-browsing/selection intent opens the indexed page; an exact root triggers the same stage directly.
+This is intentional: the AI never makes a fuzzy or interpretive judgment about whether wording maps to a template. The Stage-1 mode switch is always available in Default Generate, while only an exact root selected from the indexed controls activates a workspace.
-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.
+To browse in chat, ask "what templates are available?" The chat listing and Stage-1 selector 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
@@ -107,7 +131,7 @@ Make a deck from projects/annual-report/sources/report.md.
Template workspace: projects/acme_template/
```
-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.
+For chat-based explicit root selection, path labels are optional but exact roots are mandatory. The 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.
@@ -120,7 +144,11 @@ 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 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).
+These four indexes are the complete registered-library source for the Default
+Stage-1 template controls 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).
### Free design vs template
@@ -130,16 +158,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 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.
+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 chooses its registered entry, supplies its exact workspace root, or receives it through the current Create Template handoff.
| | Style workspace | Style brief |
|---|---|---|
-| 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 |
+| How invoked | Stage-1 template selection, exact directory path, or current Create Template handoff | Free-form description in your message; does not select a workspace |
| 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 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 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.
+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 on the page or through an exact path. `kind: style`, final Stage-2 `visual_style`, and internal `template_reuse_scope: style` are separate axes.
### How style briefs are interpreted
@@ -246,7 +274,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 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.
+Library registration makes the template **selectable** in the Default Stage-1 template controls and discoverable in chat because both read the same index. For project scope or an exact handoff, supply the workspace root, for example `use this template: projects/<name>/`; this initializes template mode, exactly one supplied root is preselected, multiple supplied roots remain unselected candidates, and 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.
@@ -307,7 +335,14 @@ 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. 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.
+The result is not a private or reduced project-only format. Supplying an exact
+workspace root adds it to the Step-3 candidate input, defaults Stage 1 to
+template mode, and preselects that root only when it is the sole supplied 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.
---
diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.md
index 0b0abd97..80958663 100644
--- a/docs/zh/getting-started.md
+++ b/docs/zh/getting-started.md
@@ -29,7 +29,7 @@
前者:把 `.pptx` 连同素材(或一个主题)给 AI,说「套模板」——见 [套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。本节其余部分讲 create-template。
-**想把某份现成 PowerPoint 做成可复用工作区,必须显式请求 Create Template 路线。** 原生 `.pptx` 加新材料默认属于 Fill Native PPTX,并不是 Generate PPTX Step 3 可以直接消费的模板。先创建工作区:
+**想把某份现成 PowerPoint 做成可复用工作区,必须显式请求 Create Template 路线。** 原生 `.pptx` 加新材料默认属于 Fill Native PPTX,并不是 Generate 可以直接消费的模板工作区。先创建工作区:
```
你:用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 模板
@@ -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;普通自由设计直接跳过。Step 3 会解析 `templates/design_spec.md`;为兼容目录形态,也接受满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 根目录,Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。create-template 可在同一对话里把已验证的精确工作区根目录直接交给 Step 3。两种情况都要求精确选择,绝不认裸模板名。完整工作区可以在全局库与 `projects/` 之间复制或迁移,无需调整目录结构;只有全局库注册不同。
+Default Generate 把模板选择放在 Stage 1,与沟通契约同屏确认;沟通推荐在此之前不会读取任何模板。普通请求默认自由设计;用户明确要求模板或提供任意精确 root 时,默认进入模板模式,但界面始终允许切换。未注册 root 会进入指定地址下拉框;与注册 canonical root 完全相同的路径会归回对应 kind 下拉框。只提供一个 root 时可预选它;提供多个 root 时都只作为候选、不预选。一次确认同时闭合沟通与模板选择,随后才校验、安装所选工作区;最终 Stage 2 才读取安装结果。裸模板名不会被解析为工作区。完整工作区可以在全局库与 `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。普通请求默认自由设计并直接进入 Stage 1;只有需要模板时才显式要求浏览/选择,或附上精确工作区 root 来触发 Step 3:
+2. **在对话里告诉 AI** 要把什么做成 deck。Stage 1 会让你同时确认沟通契约与自由设计/模板使用;只附上一个精确工作区 root 时,页面可默认进入模板模式并预选该路径:
```
你:用 projects/q3-report/sources/report.pdf 做一份 PPT
你:把这份内容做成 PPT:<粘贴你的文字>
```
3. **拿回可编辑的 `.pptx`**,位于 `exports/<名称>_<时间戳>.pptx` —— 真正的 DrawingML 形状、文本框、图表,在 PowerPoint / Keynote / WPS / LibreOffice 里点开就能改。
-生成前,Stage 1 确认沟通契约和画布/格式,最终 Stage 2 确认页数、视觉系统、启用模板时的应用方式与生产选项。只有显式触发时,模板选择才会在 Stage 1 前出现。之后内容分析、排版、配图、SVG 生成、导出都由 AI 完成——这就是其它能力围绕的核心环节。不想走交互确认,见下方[快速模式](#快速模式)。
+生成前,Stage 1 同时确认沟通契约、画布/格式与自由设计/模板选择。AI 随后安装所选工作区;最终 Stage 2 读取安装结果,并确认页数、视觉系统、模板应用方式与生产选项。之后内容分析、排版、配图、SVG 生成、导出都由 AI 完成——这就是其它能力围绕的核心环节。不想走交互确认,见下方[快速模式](#快速模式)。
---
## 快速模式
-默认流程会完成两阶段设计确认;只有显式选模板时才增加 Step 3。不想经过这些交互,就显式要求**快速生成**:
+默认流程会先进行 Stage 1 的沟通/模板合并确认,再进入最终 Stage 2。不想经过这些交互,就显式要求**快速生成**:
```
你:用 sources/report.pdf 快速生成一份 PPT,不用跟我确认
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index b1236ee2..1cc2a95d 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -52,9 +52,9 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
├── 若缺少同 stem 的规范 Markdown,再对该归档 PPTX 运行 ppt_to_md.py
└── sources/ 内容型文件成为内容契约
↓
-[模板选择与安装(Step 3,条件触发)] — 仅在显式浏览 / 选择模板、提供精确工作区 root,或接收本次 Create Template handoff 时进入
- 普通自由设计直接打开 Stage 1,不读取模板索引,也不创建模板选择产物
- 触发后可确认自由设计,或选择索引中的 Brand/Style/Layout/Deck library 条目或精确 explicit 工作区 root;已确认工作区会校验/合成到项目本地 templates/images/icons
+[模板候选准备(Step 3)] — 仅内部执行;不打开 UI、不等待、不选择、不读取或安装模板
+ 准备四类索引候选与本次提供的精确 root
+ Stage 1 同时确认沟通契约与自由设计/模板使用;随后才安装所选工作区供 Stage 2 读取
原生 PPTX 模板请求进入 template-fill;可复用 SVG 模板需先通过 create-template 创建
↓
[Strategist] 策略师 - Stage 1 沟通确认 + 最终 Stage 2 完整方案与生产机制确认 → design_spec.md + spec_lock.md
@@ -159,9 +159,8 @@ narration 标记。
| 原生 PPTX 模板 + 新材料 / 新主题 | Fill Native PPTX(`template-fill-pptx`) | 克隆并填充原生页面;不生成 SVG |
| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | Generate PPTX + `beautify-pptx` profile | 通过 SVG 重新生成;内容和分页锁定 |
| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | Enhance Native PPTX(`native-enhance-pptx`) | 直接 OOXML patch;不重新设计 |
-| 用户想从一个或多个 PPTX/SVG、图片/PDF、文档/网站、品牌资产、直接文字或混合参考材料包构建可复用模板工作区 | Create Template(`create-template`) | 固定入口读取每个适用证据通道,只分派一个 Create Brand、Create Style、Create Layout 或 Create Deck 子工作流,再返回供 Generate Step 3 使用的工作区根目录;结构型子工作流可导出审阅 PPTX |
-| 没有显式模板浏览 / 选择请求、精确工作区 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` |
+| 用户想从一个或多个 PPTX/SVG、图片/PDF、文档/网站、品牌资产、直接文字或混合参考材料包构建可复用模板工作区 | Create Template(`create-template`) | 固定入口读取每个适用证据通道,只分派一个 Create Brand、Create Style、Create Layout 或 Create Deck 子工作流,再返回作为 Generate Stage 1 候选的工作区根目录;结构型子工作流可导出审阅 PPTX |
+| Default Generate 进入规划;本次运行可能已带精确工作区 root 或 Create Template handoff | Generate PPTX Stage 1 | Step 3 只准备候选;Stage 1 同时确认沟通与自由设计/模板使用;普通请求默认自由设计,明确模板意图或任意 root 默认模板模式,且只有单 root 会预选;随后才安装供 Stage 2 读取 |
| 用户要求调整对象级动画顺序 / 效果 / 计时 | Generate PPTX + `customize-animations` 阶段 | 通过 `animations.json` 控制可选导出策略 |
| 用户要求预览、选择、注解或重导出浏览器编辑 | Generate PPTX + `live-preview` 阶段 | 注解只在规定交接点应用 |
@@ -336,7 +335,7 @@ CLI 支持 `--move`、`--copy` 和自动默认,但共享同一条固定的所
| PowerPoint 手工“转换为形状”不属于兼容性契约 | `svg_final/` 可以作为 SVG 图片插入,但转换后的结构与视觉结果不做保证,也不反向约束 SVG 允许能力 |
| 直接 OOXML 路由不进入 SVG 流水线 | 保留型工作流直接 patch 原生 PPTX parts |
| 图片事实来自重算元数据 | `analysis/image_analysis.csv` 从实时 `images/` 目录重算;默认流程由 Strategist 先用源文上下文,只在图片语义或安全放置仍无法确定时查看那一张具体图片;`quick-generate` 由当前 Agent 在备料时采用同样的有界分析,SVG 创作阶段不重新扫描源图像素 |
-| 原生 PPTX 模板不是 Step 3 模板 | Step 3 只消费可复用模板目录 |
+| 原生 PPTX 模板不是 Step 3 候选 | Step 3 只接受精确的可复用模板工作区 root 作为候选输入 |
---
@@ -348,13 +347,13 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
---
-## 模板系统与可选路径
+## 模板系统与选择
-模板是**可选项,不会被自动推断**。普通自由设计会跳过 Step 3,不读取模板索引,也不创建模板选择产物,直接打开 Strategist Stage 1。只有用户显式要求浏览 / 选择模板、为本次运行提供精确工作区 root,或继续使用本次 Create Template handoff 时,Step 3 才会出现。触发后的 UI 只列出已注册的 Brand/Style/Layout/Deck 条目与显式提供的精确 root;系统不会根据主题相似度替用户选模板。
+模板使用是**可选项,不会被自动推断**。Default Step 3 只准备候选,不打开 UI、不读模板内容。Stage 1 把不受模板影响的沟通推荐与可切换的自由设计/模板选择同屏确认。普通请求默认自由设计;明确模板意图或提供任意 root 默认模板模式。只有单 root 会预选,多 root 只作为候选。
-**为什么默认自由设计。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),所以它一直在;但 AI 不主动去抓,是用户去抓。
+**为什么保留自由设计选项。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),最终选择仍由用户完成。
-**精确选择,不做语义匹配。** 像 `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,空的可选目录直接省略:
@@ -370,7 +369,12 @@ 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 只把它记录为候选输入,
+不读取模板内容;Stage 1 选中后,apply 阶段才把它校验、合成并安装到当前项目
+的 `templates/`、`images/`、`icons/`,且不复制 `exports/`。模板感知的
+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。
@@ -401,7 +405,10 @@ PPT Master 把拥有 deck 状态的 Strategist、Image_Generator 和 Executor
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式:不得重选上游方案或漏掉必需属性,但在 Design Spec 留出的范围内仍拥有几何、构图、层级和视觉处理的实现权。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。
-**条件触发的 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 1 同时确认。** Step 3 只在内部准备候选;
+Stage-1 沟通推荐的编写不得读取这些候选或任何模板内容。UI 在同一次提交中
+确认沟通契约与可切换的自由设计/使用模板选择;只有确认后,Agent 才安装或
+合成非自由设计选择。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 2 确认的三个主动执行值始终保留为相互独立的原始证据。
尤其是,启用旁白可以在 Design Spec 中启用 Speaker Notes 的最终有效结果,
@@ -709,7 +716,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu
| 不要合并或新增 | 原因 |
|---|---|
-| 不要把模板名或风格短语模糊匹配到库路径 | Step 3 必须确定性触发;选错模板比自由设计更难恢复 |
+| 不要把模板名或风格短语模糊匹配到库路径 | 模板选择必须是确定性的;套错工作区比自由设计更难恢复 |
| 不要把原生 PPTX 模板当作 Step 3 模板 | 作为模板 / 页面壳时应走原生克隆与填充;作为来源、1:1 beautify 或可重构材料时分别走对应 Generate 边界,而不是把 PPTX 直接交给 Step 3 |
| 不要把 `template-fill-pptx`、`beautify-pptx`、`native-enhance-pptx` 合成一个“PPTX 优化”路线 | 三者的保留契约不同:原生填充、1:1 重排、直接增强是三种操作 |
| 不要用脚本批量生成 Executor SVG 页面 | 跨页设计判断依赖主代理逐页连续创作 |
@@ -733,7 +740,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;仅在显式浏览 / 选择请求、精确 root 或本次 Create Template handoff 确认至少一个工作区后运行 |
+| 模板输入阶段 | `apply-template-workspace` | Default Stage 1 确认至少一个工作区后、Stage 2 前运行;自由设计跳过安装,Quick 可直接提供精确 root |
| 生成阶段 | `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 bb7ae193..48803364 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -6,7 +6,7 @@
> 本文是**架构对齐文档**,定义“模板”在数据模型层面的四种身份、各自的 `design_spec.md` 字段集、以及多路径合成与冲突解决规则。面向贡献者与 AI 工作流,回答“一个模板目录里应该写什么、不写什么;多个模板同时给时怎么合成”。
>
-> 用户视角的用法(怎么触发、怎么选)见 [`templates-guide.md`](./templates-guide.md);本文不重复。
+> 用户视角的用法(怎么选、怎么提供精确路径)见 [`templates-guide.md`](./templates-guide.md);本文不重复。
---
@@ -89,7 +89,11 @@ native_structure_mode: structured
└── <id>_template_preview.pptx
```
-空的可选目录直接省略,不添加占位文件。预览 PPTX 是派生审阅证据,不是模板源资产;单 Master 按需生成,多 Master 必须通过该 package gate。Step 3 读取工作区根目录,只消费 `templates/` 及实际存在的 `images/`、`icons/`,不会复制或使用 `exports/`;全局库下的 `exports/` 统一由 Git 忽略。
+空的可选目录直接省略,不添加占位文件。预览 PPTX 是派生审阅证据,不是模板
+源资产;单 Master 按需生成,多 Master 必须通过该 package gate。Step 3 只把
+工作区 root 记录为候选输入,不读取其内容;Stage 1 选中后,apply 阶段才消费
+`templates/` 及实际存在的 `images/`、`icons/`,不会复制或使用 `exports/`;
+全局库下的 `exports/` 统一由 Git 忽略。
导入向量统一使用 `data-icon="imported/<name>"`,唯一规范文件位于 `icons/imported/<name>.svg`。具备工作区感知的校验与导出会直接解析这个根目录路径;`templates/icons/` 不属于模板包结构。
@@ -336,7 +340,7 @@ Template Overview 写明可重复演示类型、目标受众与结果、交付/
### 片段所有权(隐式触发)
-显式触发的 Step 3 确认已注册和/或指定工作区根目录后,会解析每个 root 的真实
+Step 3 确认已注册和/或指定工作区根目录后,会解析每个 root 的真实
`kind`,再分片段写入一份 `<project>/templates/design_spec.md`。
`library` / `explicit` 只记录发现来源,不改变所有权:
@@ -383,7 +387,7 @@ AI: 你给了两个 brand,检测到段级冲突:
- `style × 2`、`layout × 2`、`deck × 2`、`brand × 2` 同处理
- 每类最多两份(再多让用户先在 chat 里收敛)
-显式触发的模板页面已经把组合空间收窄:Brand/Style/Layout/Deck 各有一个已注册模板
+Default 模板页面已经把组合空间收窄:Brand/Style/Layout/Deck 各有一个已注册模板
单选下拉框,另有一个指定地址下拉框;指定地址按解析出的 kind,最多给该类
增加第二份。服务端强制同一限制;聊天组合仍保留每类最多两份的通用边界。
@@ -404,11 +408,16 @@ AI: 你给了两个 brand,检测到段级冲突:
---
-## 五、与 Generate PPTX Step 3 的关系
+## 五、与 Generate PPTX Stage 1 的关系
-**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 怎么处理**:
+Default Generate 的 [Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-candidate-preparation)
+只准备候选输入。Stage 1 把沟通契约与可切换的自由设计/使用模板选择同屏呈现。
+普通请求默认自由设计并收起详细控件;明确要求使用模板或提供任意精确 root 时
+默认展开模板模式。只提供一个 root 时会预选,多 root 仍只作为未选候选。裸
+模板/品牌名称或风格词不会解析或预选工作区。对于每个已选工作区,确认后的
+apply 阶段解析 `<workspace>/templates/design_spec.md`;为兼容目录形态,也接受根目录直接包含 `<workspace>/design_spec.md`、且满足当前 kind 合同的旧式平铺 Brand/Layout/Deck 工作区。Layout/Deck 还必须带有当前 structured SVG;Style 没有平铺形态。若包仍使用 `native_structure_mode: template`、缺 Master 身份、原子 placeholder 或蒸馏时代标记等旧语义,apply 阶段必须拒绝;先由 `create-template` 产出新工作区,再继续生成。`kind` 字段决定**AI 如何处理已选路径**:
-| 用户路径指向 | Step 3 行为(按 kind 分支)|
+| 用户路径指向 | Stage-1 确认后的 apply 行为(按 kind 分支)|
|---|---|
| `kind: brand` | 把工作区 `templates/` 及实际存在的 `images/`、`icons/` 映射到项目同名目录;忽略 `exports/` |
| `kind: style` | 安装仅含 spec 的方向/方法工作区;要求无 SVG roster,并保持生成页面为 flat |
@@ -417,11 +426,11 @@ AI: 你给了两个 brand,检测到段级冲突:
| 多路径 | 按上表合成单份 `design_spec.md`,解决冲突后再合并实际存在的可移植目录 |
| 同类多份 | 按上节"git 冲突解决"问答,得到合成结果 |
-位图统一进入工作区 `images/`,模板 SVG 通过 `../images/` 引用。如果显式输入根目录本来就是目标项目根目录,Step 3 原地消费:不得复制到自身,也不得再次移动素材。除此之外,完整核心工作区是可移植的:可以从项目根复制到全局库根、从全局库复制到项目,或从另一个工作区直接复用,而不改变内部结构。注册是唯一与范围相关的步骤。
+位图统一进入工作区 `images/`,模板 SVG 通过 `../images/` 引用。如果显式输入根目录本来就是目标项目根目录,apply 阶段原地消费:不得复制到自身,也不得再次移动素材。除此之外,完整核心工作区是可移植的:可以从项目根复制到全局库根、从全局库复制到项目,或从另一个工作区直接复用,而不改变内部结构。注册是唯一与范围相关的步骤。
### 策略师确认阶段在不同 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 7cd54f20..9066f105 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 → Stage 1 模板选择控件** | `用 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。
@@ -37,44 +37,58 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
最容易避免误用的两条规则:
-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 开始,且只读项目本地副本。
+1. Default Generate 的 [Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-candidate-preparation) 只准备候选;Stage 1 在同一次提交中确认沟通契约与自由设计/使用模板。
+2. 普通请求默认自由设计;明确要求使用模板或提供任意精确工作区 root 时默认展开模板模式。只提供一个 root 时会预选,多 root 仍只作为未选候选。非自由设计选择在 Stage 1 后、模板感知的最终 Stage 2 前安装。
---
## 一、选用已有模板
-### 触发方式
+### 选择方式
-普通 Default Generate 不进入 Step 3,而是直接以自由设计打开 Stage 1。只有显式要求浏览/选择模板、提供精确工作区根目录,或接到当前对话中的 Create Template 交接,才会在 Stage 1 前打开独立的 **Step 3 模板选择阶段**。触发后的页面同时提供自由设计、已注册的 Brand/Style/Layout/Deck,以及本次运行已明确给出的工作区根目录;它不会根据主题替用户推断推荐模板,选择必须由用户明确完成。
+Default Generate 把模板选择放进 **Stage 1**,与不受模板影响的沟通契约
+同屏。页面先提供可切换的「自由设计 / 使用模板」;普通请求默认自由设计并
+收起详细选项,明确要求使用模板或提供任意精确 root 时默认展开模板模式。
+模板模式展示已注册 Brand/Style/Layout/Deck 与本次提供的 root;只提供一个
+root 时会预选,多 root 仍只作为未选候选。系统不会根据主题替用户推断具体模板。
> **快速模式例外:** Quick 不会打开这个页面。请求中每个 kind 最多一个精确
> 工作区 root,会被直接校验、安装并使用;没有精确 root 就直接自由设计。
> 裸模板名仍不会被解析。Quick 继续采用无锁 flat 导出,因此 Layout/Deck
> 原型是页面创作输入,不会变成可复用的原生 Master/Layout 输出。
-### 怎么触发模板流程
+### 怎么使用选择器
-触发后的模板页面提供自由设计,以及五个紧凑下拉框:Brand、Style、Layout、Deck 各一个已注册工作区单选框,再加一个本次运行指定地址单选框。每个下拉框都有“无”;四类已注册模板可跨类型组合,指定地址最多选一个。已注册列表只来自四类索引,工作流不会扫描模板目录。也可以直接在对话里写出 Brand/Style/Layout/Deck 工作区根目录来触发 Step 3(位置不重要,只要明确即可):
+Stage-1 页面先让用户选择自由设计或使用模板;只有选择使用模板,才展开五个
+紧凑下拉框:Brand、Style、Layout、Deck 各一个已注册工作区单选框,再加
+一个本次运行指定地址单选框。每个下拉框都有“无”;四类已注册模板可跨类型
+组合,指定地址最多选一个。已注册列表只来自四类索引,工作流不会扫描模板
+目录。需要默认展开模板模式并预选某个 Brand/Style/Layout/Deck 工作区时,
+直接在对话里写出精确 root(位置不重要,只要明确即可):
> "用这个模板做:`skills/ppt-master/templates/layouts/presentation_core/`" ✅
> "用上次那个模板:`projects/last_deck/`" ✅
> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
-对于当前所有模板类型,显式路径都是**模板工作区根目录**。若精确路径与索引中的注册 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。
+对于当前所有模板类型,显式路径都是**模板工作区根目录**。若精确路径与索引中的注册 root 一致,页面可以把它显示为 `library`;未注册 root 则单独标为 `explicit`,并由服务端解析其 frontmatter 中的真实 `kind`。`explicit` 只是来源,不是第五种类型,也不提高优先级。Stage 1 会校验已选候选 root;确认后,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 时,可把精确的已验证工作区根目录直接交给下一次 Stage-1 选择器。
-模板选择不属于 Stage 1。触发 Step 3 后,确认会运行统一 apply 阶段,把所选工作区校验、合成并安装到当前项目的 `templates/`、`images/`、`icons/`;完成后 Strategist 才开始 Stage 1。Stage 1 只使用当前请求、源材料事实、对话约束和项目初始化状态,模板选择、已安装内容及模板画布均不得影响这份契约。Stage 1 确认后,最终 Stage 2 才把它与已安装状态进行适配;`template_application` 只描述**如何使用**,不负责决定**选哪个模板**。
+模板选择与 Stage 1 共用页面和提交动作,但仍作为独立 sidecar 决策保存。
+沟通推荐只使用当前请求、源材料事实、对话约束和项目初始化状态;候选元数据、
+所选 root、已安装内容及模板画布均不得影响它。合并确认后,非自由设计选择才
+运行统一 apply 阶段,把所选工作区校验、合成并安装到当前项目的 `templates/`、
+`images/`、`icons/`。最终 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 风" 仍只是自由设计说明;除非用户另行要求浏览/选择工作区或提供精确 root,否则不会激活模板。
+- **在聊天中只写模板名**:"presentation_core" / "中国电信模板" 不会被隐式解析,也不会预选工作区。请在页面选择注册项,或在聊天中返回精确路径。
+- **风格描述**:"麦肯锡风格" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" 仍只是自由设计说明;除非用户选择工作区或提供精确 root,否则不会激活模板。
-这是有意的——AI 永远**不做模糊 / 解释性判断**,不会替你把普通文字解析成模板。显式的模板浏览/选择意图会打开索引页面;精确 root 会直接触发同一阶段。
+这是有意的——AI 永远**不做模糊 / 解释性判断**,不会替你把普通文字解析成模板。Default Generate 固定提供 Stage-1 模式切换入口,只有在索引控件中选定的精确 root 才会激活工作区。
-想知道内置库有哪些模板,问一句“有哪些模板可以用?”即可。这条显式请求会触发 Step 3,其页面与聊天列表读取同一组四类索引。单纯列出不代表选择;需要返回其中一条精确路径,或在页面完成选择。
+想在聊天中查看内置库,问一句“有哪些模板可以用?”即可。聊天列表与 Stage-1 选择器读取同一组四类索引。单纯列出不代表选择;需要返回其中一条精确路径,或在页面完成选择。
### 可直接复制的用法
@@ -100,7 +114,7 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
模板工作区:projects/acme_template/
```
-在聊天中显式提供 root 时,“模板工作区”这些标签可以不写,但 root 必须精确;触发后的页面中,library 选择已自带精确 root。页面中每个注册 kind 最多选一个,指定地址最多选一个;若指定地址解析出的 kind 与某个注册选择相同,工作流会进入既有的两份同类冲突解决门,不会静默替你选一个。
+在聊天中显式提供 root 时,“模板工作区”这些标签可以不写,但 root 必须精确;页面中的 library 选择已自带精确 root。页面中每个注册 kind 最多选一个,指定地址最多选一个;若指定地址解析出的 kind 与某个注册选择相同,工作流会进入既有的两份同类冲突解决门,不会静默替你选一个。
你不需要选择模板使用模式。对 Layout/Deck,Strategist 会读取真实的 Master/Layout/原型集合和当前内容,决定选哪些页、哪些重复/跳过/重排,以及是否重组。Brand 只提供身份约束,Style 只提供方向/方法默认值;除非另一个工作区提供结构,否则两者都保持页面自由编排。如果你在意某个边界,直接在同一句请求里用普通语言说明即可,例如“封面和结束页原样保留,中间页由你选择”或“只参考视觉语言”;明确文字优先于 AI 判断。
@@ -113,7 +127,10 @@ 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 页面与聊天发现共用的完整已注册模板来源;普通 Default Generate 不读取它们,目录也永远不会被扫描。直接问“有哪些模板可以用?”即可得到带精确工作区路径的可读清单;四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
+这四个索引是 Default Stage 1 模板控件与聊天发现共用的完整已注册模板来源;
+目录永远不会被扫描。直接问“有哪些模板可以用?”即可得到带精确工作区路径的
+可读清单;四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决
+规则见 [`templates-architecture.md`](./templates-architecture.md)。
### 自由设计 vs 模板
@@ -123,16 +140,16 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
### 风格说明不是 Style 工作区
-**风格说明**是解释性语言(“极简风” / “Keynote 风” / “杂志风”),由 Strategist 转化为当前 deck 的具体设计选择。**Style 工作区**则是真实存在的 `kind: style` 模板,预写可复用沟通方法与视觉默认值;只有用户显式打开模板选择并选择注册项、提供精确工作区 root,或接到当前 Create Template 交接后才会消费。
+**风格说明**是解释性语言(“极简风” / “Keynote 风” / “杂志风”),由 Strategist 转化为当前 deck 的具体设计选择。**Style 工作区**则是真实存在的 `kind: style` 模板,预写可复用沟通方法与视觉默认值;只有用户选择注册项、提供精确工作区 root,或接到当前 Create Template 交接后才会消费。
| | Style 工作区 | 风格说明 |
|---|---|---|
-| 怎么触发 | 显式触发 Step 3 后选择注册项、消息里给出精确目录路径,或当前 Create Template 交接 | 消息里写自由描述;不打开 Step 3 |
+| 怎么启用 | 在 Stage 1 选择模板、消息里给出精确目录路径,或当前 Create Template 交接 | 消息里写自由描述;不选择工作区 |
| 提供什么 | 可复用方法、角色/证据纪律和视觉默认值;无身份真值或页面原型 | 由 Strategist 解释为 mode、visual style、色彩、字体、图标与图片方向 |
| 如何确认 | 已存值作为最终 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` 是三条不同轴。
### 风格说明如何被解释
@@ -234,7 +251,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-conditional-template-discovery-selection-and-installation) 中选择它。项目范围或精确交接则提供工作区 root,例如 `用这个模板:projects/<name>/`;未注册 root 仍标记为 `explicit`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要出现在 library 列表中时才执行注册。
+全局注册会让模板出现在 Default Stage-1 模板控件中,也可在聊天中发现,因为两者都读取同一个索引。项目范围或精确交接则提供工作区 root,例如 `用这个模板:projects/<name>/`;这会默认展开模板模式,只提供一个 root 时页面会预选,多 root 保持未选候选,未注册 root 仍标记为 `explicit`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要出现在 library 列表中时才执行注册。
选择 Deck/Layout 模板后,Strategist 会自动生成页面/原型应用计划:可以使用全套或子集,重复或重排原型,并按内容需要重组。`strict` / `adaptive` 只作为内部导出值,不再出现在确认选项中。
@@ -292,7 +309,11 @@ 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
+候选输入,并让 Stage 1 默认展开模板模式;只有该 root 是唯一输入时才会预选。
+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 cc469869..1ae3ec99 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -35,8 +35,8 @@ package postflight as the default profile, but it does not create `svg_final/`.
| `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 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. |
+| `${SKILL_DIR}/templates/{brands,styles,layouts,decks}/*_index.json` | Library discovery indexes | The complete registered option source for Default Stage-1 template selection and chat listing | The UI server or chat branch reads these indexes only to populate the Stage-1 choice, after the communication recommendation is authored. Never scan kind directories to add options or use index summaries as Stage-1 planning evidence. Derive a library root from kind + entry id. Exact unregistered roots remain explicit inputs. Quick does not read the catalog. |
+| `templates/` | Project template reference | Stage-1-confirmed non-free selection 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` | 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/template_options.json`, `template_selection.json`, `template_handoff.json` | Default UI template-selection sidecar | Agent-authored candidate input, user-confirmed selection written beside the Stage-1 result, and agent-authored installation/free-design completion handoff | Step 3 writes options without launching UI. The Stage-1 submission writes `template_selection.json` alongside `result.json`; template choices never enter the Strategist contract. After installation/free-design closure, `--complete-template-selection` writes the bound handoff. Stage 2 is exposed only after that handoff and a fresh recommendation. Chat/delegated flows retain equivalent state without fabricating UI receipts; Quick creates none. |
+| `confirm_ui/recommendations.stage1.json`, `.stage2.json` | Confirmation proposals | Template-independent communication contract, then template-aware complete solution plus production mechanics | Author the Stage-1 communication recommendation without using candidate indexes or workspaces as evidence; candidate display state may be prepared independently. Its page confirms communication plus template mode/selection in one submission. Create Stage 2 only after the selection is installed or free design closes and the handoff/equivalent state is ready. `template_application` decides only how to use installed project-local state. The active unconfirmed stage may be overwritten; normal progression 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 |
@@ -81,7 +81,7 @@ 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 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. |
+| Template selection | Default Step 3 prepares candidates without interaction or template reads. `template_options.default_mode` is `free_design` for ordinary requests and `templates` for explicit template intent or any exact root; Stage 1 keeps the mode switchable and confirms it with communication. Exactly one root may be preselected, while multiple roots remain unselected candidates. Template mode requires at least one selected candidate. Every applied selection becomes one project-local `templates/` state before Stage 2 reads it. Quick bypasses this gate and applies at most one exact root per kind directly. |
| 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/strategist-template.md b/skills/ppt-master/references/strategist-template.md
index 39afba00..5cc9bbe4 100644
--- a/skills/ppt-master/references/strategist-template.md
+++ b/skills/ppt-master/references/strategist-template.md
@@ -4,7 +4,7 @@
Conditional extension for applying an installed Brand/Style/Layout/Deck workspace to Stage 2 recommendations and the execution lock.
-**Trigger**: Load only after Stage 1 is confirmed, when Generate Step 3 validated a library or explicit workspace path and either installed it into `<project_path>/templates/` or confirmed that the target project is consuming it in place. Bare template names, style words, and free-design projects do not trigger this module.
+**Trigger**: Load only after Stage 1 confirms a library or explicit workspace selection and the post-confirmation apply stage either installs it into `<project_path>/templates/` or confirms that the target project is consuming it in place. Bare template names, style words, and free-design projects do not trigger this module.
---
@@ -22,7 +22,7 @@ Immediately before authoring the Stage-2 solution, load each relevant template
resource once per path + SHA and inspect:
- every installed `design_spec.md`; for Layout/Deck only, also inspect the actual Page Roster and relevant SVG prototypes;
-- the resolved Identity, Structure, Reusable Application Context, and Direction / method segment owners from the Step-3 fusion receipt;
+- the resolved Identity, Structure, Reusable Application Context, and Direction / method segment owners from the post-Stage-1 fusion receipt;
- the confirmed current communication contract, source obligations, planned page count, and content shape of every planned page;
- the user's natural-language instructions, including any page names/numbers or elements they explicitly require.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 40724f49..a95bb3cf 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 + any triggered Step-3 template selection/installation complete | **Strategist**: Stage 1–2 confirmation + Design Spec | Image_Generator or Executor |
+| Project creation + template-candidate preparation complete | **Strategist**: Stage 1 communication/template confirmation → installation handoff → Stage 2 solution + Design Spec | Image_Generator or Executor |
---
@@ -25,25 +25,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.
**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:
+Generate Step 3 prepares candidates only. Stage 1 confirms the communication
+contract and template/free-design choice together, while keeping the
+communication recommendation independent of every template candidate. After
+that single confirmation, selected workspaces are installed before the 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 |
+| **1 — communication contract + template choice** | `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 · explicit `free_design` or `templates` choice and selected roots | confirmed together; candidate workspaces do not influence the communication recommendation |
| **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, 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. 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.
+**Hard rule — Stage-1 source boundary**: Build the communication recommendation only from the current user request, source facts, conversation constraints, and project-initialization state. Author it before loading index summaries for a chat listing, and do not read any candidate spec, prototype, asset, or template-owned canvas. The same Stage-1 surface may display template controls, but their values are confirmation state, not recommendation evidence. Do not load or apply [`strategist-template.md`](./strategist-template.md) until Stage 1 is confirmed and the selected workspace has been installed for Stage 2.
-> **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.
+> **Execution discipline**: Step 3 is non-interactive candidate preparation. Stage 1 is the first BLOCKING checkpoint and closes communication plus template/free-design choice in one confirmation. Install/fuse any selection and complete its handoff before authoring final Stage 2. 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 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.
+> **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. In the UI branch, `template_options.json` and `recommendations.stage1.json` open one Stage-1 page; its single submission writes the pure Strategist `result.json` plus the sidecar `template_selection.json`. After installation/free-design closure, `template_handoff.json` gates `.stage2.json`. The chat/delegated branch keeps equivalent state without fabricating those receipts. Replace only the active unconfirmed stage and print the URL plus combined 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:
@@ -154,7 +155,7 @@ The deck's **visual aesthetic** — shape language, decoration density, whitespa
Record the confirmed visual style and rationale in `design_spec.md` first, including the exact catalog basis when a selected custom uses one. Then project `- visual_style:` to `spec_lock.md`; for `custom`, also project `- visual_style_behavior:` and, only when catalog material is actually used, `- visual_style_references: <id>, <id>`. Executor reads one file for a preset. For `custom`, it reads every listed reference before applying the behavior; an unreferenced novel custom follows the behavior directly.
-**Conditional template workspace**: When Generate Step 3 installed a selected workspace into `<project_path>/templates/`, read [`strategist-template.md`](./strategist-template.md) before completing Stage 2. Read the installed project-local spec and prototypes only; never reopen the library/external source root. The module owns the editable natural-language application plan, confirmed-value consumption, AI-authored prototype selection, internal reuse/adherence derivation, inherited design precedence, and structured-lock planning. This plan decides how to use the installed template, never which template to select. Bare names, style words, and free-design projects do not trigger it.
+**Conditional template workspace**: When the Stage-1 template choice has been installed into `<project_path>/templates/`, read [`strategist-template.md`](./strategist-template.md) before completing Stage 2. Read the installed project-local spec and prototypes only; never reopen the library/external source root. The module owns the editable natural-language application plan, confirmed-value consumption, AI-authored prototype selection, internal reuse/adherence derivation, inherited design precedence, and structured-lock planning. This plan decides how to use the installed template, never which template to select. Bare names, style words, and free-design projects do not trigger it.
**Downstream effect**: e / f / g / h realize the locked mode + visual style. Example: `showcase` + `dark-tech` → e applies one luminous accent on a dark field; g pairs a clean sans with mono; f minimal glow icons; h the `digital-dashboard` rendering.
diff --git a/skills/ppt-master/scripts/confirm_ui/server.py b/skills/ppt-master/scripts/confirm_ui/server.py
index ed5adf4e..3da87ea6 100644
--- a/skills/ppt-master/scripts/confirm_ui/server.py
+++ b/skills/ppt-master/scripts/confirm_ui/server.py
@@ -2,14 +2,12 @@
"""
PPT Master - Template and Strategist confirmation UI Server (Steps 3-4)
-Lightweight Flask backend for conditional Step-3 template selection and the
-interactive Step-4 Strategist confirmation page. When triggered, the agent
-writes ``<project>/confirm_ui/template_options.json``; template selection is
-persisted separately from the Strategist contract. Strategist writes each stage to
-``<project>/confirm_ui/recommendations.stageN.json``; this server selects the
-current stage from ``result.json`` and renders it as a clickable page (color
-swatches, live font previews, candidate picks). On submit it writes the user's
-choices to ``<project>/confirm_ui/result.json`` for the AI to read back.
+Lightweight Flask backend for the Default template choice and interactive
+Strategist confirmation page. Stage 1 combines template selection with the
+communication contract; its submit writes ``template_selection.json`` and the
+stage1-confirmed ``result.json`` in one request. After the agent applies the
+choice and completes ``template_handoff.json``, final Stage 2 confirms the deck
+solution and production plan.
This is the default confirmation surface. The chat fallback is used only when
the user explicitly requests chat-only confirmation or the browser launch
@@ -26,8 +24,8 @@ Examples:
python3 scripts/confirm_ui/server.py projects/my-project --no-browser
python3 scripts/confirm_ui/server.py projects/my-project --daemon
python3 scripts/confirm_ui/server.py projects/my-project --wait-only --wait-stage stage1
- python3 scripts/confirm_ui/server.py projects/my-project --complete-template-phase
- python3 scripts/confirm_ui/server.py projects/my-project --reset-template-phase
+ python3 scripts/confirm_ui/server.py projects/my-project --complete-template-selection
+ python3 scripts/confirm_ui/server.py projects/my-project --reset-template-selection
Dependencies:
flask>=3.0.0
@@ -265,6 +263,10 @@ def _read_template_options_input(confirm_dir: Path) -> tuple[dict, list[Path]]:
)
if data.get('phase') != 'template':
raise ValueError(f'{TEMPLATE_OPTIONS_NAME} phase must be template')
+ if data.get('default_mode') not in {'free_design', 'templates'}:
+ raise ValueError(
+ f'{TEMPLATE_OPTIONS_NAME} default_mode must be free_design or templates'
+ )
if 'lang' in data and (
not isinstance(data['lang'], str) or not data['lang'].strip()
):
@@ -278,6 +280,11 @@ def _read_template_options_input(confirm_dir: Path) -> tuple[dict, list[Path]]:
raise ValueError(
f'{TEMPLATE_OPTIONS_NAME} explicit_workspace_roots must be an array'
)
+ if raw_roots and data['default_mode'] != 'templates':
+ raise ValueError(
+ f'{TEMPLATE_OPTIONS_NAME} default_mode must be templates when '
+ 'explicit_workspace_roots is non-empty'
+ )
roots = []
seen = set()
@@ -420,6 +427,7 @@ def _build_template_options(confirm_dir: Path) -> tuple[dict, dict[str, dict]]:
response = {
'schema_version': TEMPLATE_SCHEMA_VERSION,
'phase': 'template',
+ 'default_mode': source['default_mode'],
'library': library,
'explicit': explicit,
'preselected_keys': preselected_keys,
@@ -429,6 +437,7 @@ def _build_template_options(confirm_dir: Path) -> tuple[dict, dict[str, dict]]:
response['options_sha256'] = _json_sha256({
'schema_version': TEMPLATE_SCHEMA_VERSION,
'phase': 'template',
+ 'default_mode': response['default_mode'],
'lang': response.get('lang'),
'explicit_workspace_roots': [str(root) for root in explicit_roots],
'library_indexes': index_contracts,
@@ -665,23 +674,31 @@ def _read_template_handoff(project_path: Path, handoff_file: Path) -> dict:
return data
-def _complete_template_phase(project_path: Path) -> int:
- """Write the agent-owned handoff after free-design or template application."""
+def _complete_template_selection(project_path: Path) -> int:
+ """Write the agent-owned handoff after Stage 1 and template application."""
confirm_dir = project_path / CONFIRM_DIR_NAME
selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
if not selection_file.exists():
- logger.error('%s not found — the user must confirm Step 3 first', selection_file)
+ logger.error('%s not found — the user must confirm Stage 1 first', selection_file)
return 1
try:
selection = _read_template_selection(selection_file)
except (OSError, json.JSONDecodeError, ValueError) as exc:
- logger.error('cannot complete template phase: %s', exc)
+ logger.error('cannot complete template selection: %s', exc)
+ return 1
+
+ result_file = confirm_dir / RESULT_NAME
+ if _result_stage(result_file) != 'stage1':
+ logger.error(
+ 'cannot complete template selection before Stage 1 writes a '
+ 'stage1-confirmed result'
+ )
return 1
if selection['mode'] == 'templates':
installed_spec = project_path / 'templates' / 'design_spec.md'
if not installed_spec.is_file():
logger.error(
- 'cannot complete template phase before template apply writes %s',
+ 'cannot complete template selection before template apply writes %s',
installed_spec,
)
return 1
@@ -695,8 +712,9 @@ def _complete_template_phase(project_path: Path) -> int:
if (
existing is not None
and existing['selection_sha256'] == selection['selection_sha256']
+ and _is_newer(handoff_file, result_file)
):
- logger.info('template phase already complete: %s', handoff_file)
+ logger.info('template selection already complete: %s', handoff_file)
return 0
handoff = {
@@ -709,12 +727,12 @@ def _complete_template_phase(project_path: Path) -> int:
}
_validate_template_handoff(handoff)
_write_json_atomic(handoff_file, handoff)
- logger.info('template phase handoff written to %s', handoff_file)
+ logger.info('template selection handoff written to %s', handoff_file)
return 0
-def _reset_template_phase(confirm_dir: Path) -> int:
- """Remove the one-run Step-3 artifacts before a fresh UI lifecycle."""
+def _reset_template_selection(confirm_dir: Path) -> int:
+ """Remove one-run template-selection artifacts before a fresh UI lifecycle."""
removed = []
for filename in (
TEMPLATE_HANDOFF_NAME,
@@ -731,41 +749,74 @@ def _reset_template_phase(confirm_dir: Path) -> int:
logger.error('cannot remove %s: %s', path, exc)
return 1
if removed:
- logger.info('reset template phase artifacts: %s', ', '.join(removed))
+ logger.info('reset template selection artifacts: %s', ', '.join(removed))
else:
- logger.info('template phase artifacts already absent')
+ logger.info('template selection artifacts already absent')
return 0
-def _template_stage1_ready_error(project_path: Path, confirm_dir: Path) -> Optional[str]:
- """Return why Step 3 has not safely handed off to a fresh Stage 1."""
+def _stage1_ready_error(confirm_dir: Path) -> Optional[str]:
+ """Return why the combined template/Stage-1 page cannot be exposed."""
+ options_file = confirm_dir / TEMPLATE_OPTIONS_NAME
+ if not options_file.exists():
+ return f'{TEMPLATE_OPTIONS_NAME} not found'
+ try:
+ _build_template_options(confirm_dir)
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return f'invalid template options: {exc}'
+
+ stage1_file = confirm_dir / RECOMMENDATION_STAGE_NAMES[1]
+ if not stage1_file.exists():
+ return f'{stage1_file.name} not found'
+ try:
+ stage1_data = _read_json_object(stage1_file)
+ if _recommendation_stage(stage1_data) != 1:
+ return f'{stage1_file.name} does not declare stage1'
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return f'cannot validate Stage 1 recommendations: {exc}'
+
+ result_file = confirm_dir / RESULT_NAME
+ if result_file.exists():
+ if not _is_newer(options_file, result_file):
+ return f'{TEMPLATE_OPTIONS_NAME} must be newer than the prior {RESULT_NAME}'
+ if not _is_newer(stage1_file, result_file):
+ return f'{stage1_file.name} must be newer than the prior {RESULT_NAME}'
+ return None
+
+
+def _stage2_ready_error(
+ project_path: Path,
+ confirm_dir: Path,
+ recommendations_file: Optional[Path] = None,
+) -> Optional[str]:
+ """Return why final Stage 2 cannot follow the confirmed template choice."""
selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
if not selection_file.exists():
- return f'{TEMPLATE_SELECTION_NAME} not found'
+ return f'{TEMPLATE_SELECTION_NAME} not found after Stage 1 confirmation'
try:
_read_template_selection(selection_file)
except (OSError, json.JSONDecodeError, ValueError) as exc:
return f'invalid template selection: {exc}'
+ result_file = confirm_dir / RESULT_NAME
+ if _result_stage(result_file) != 'stage1':
+ return f'{RESULT_NAME} does not contain a stage1-confirmed result'
+
handoff_file = confirm_dir / TEMPLATE_HANDOFF_NAME
if not handoff_file.exists():
- return f'{TEMPLATE_HANDOFF_NAME} not found'
+ return f'{TEMPLATE_HANDOFF_NAME} not found after template application'
try:
_read_template_handoff(project_path, handoff_file)
except (OSError, json.JSONDecodeError, ValueError) as exc:
return f'invalid template handoff: {exc}'
+ if not _is_newer(handoff_file, result_file):
+ return f'{TEMPLATE_HANDOFF_NAME} must be newer than the Stage 1 {RESULT_NAME}'
- stage1_file = confirm_dir / RECOMMENDATION_STAGE_NAMES[1]
- if not stage1_file.exists():
- return f'{stage1_file.name} not found after template handoff'
- try:
- stage1_data = _read_json_object(stage1_file)
- if _recommendation_stage(stage1_data) != 1:
- return f'{stage1_file.name} does not declare stage1'
- if not _is_newer(stage1_file, handoff_file):
- return f'{stage1_file.name} must be newer than {TEMPLATE_HANDOFF_NAME}'
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- return f'cannot validate fresh Stage 1 recommendations: {exc}'
+ if recommendations_file is not None and not _is_newer(
+ recommendations_file,
+ handoff_file,
+ ):
+ return f'{recommendations_file.name} must be newer than {TEMPLATE_HANDOFF_NAME}'
return None
@@ -827,66 +878,49 @@ def _resolve_template_confirmation(
return receipt
-def _confirmation_launch_error(
- confirm_dir: Path,
- *,
- require_template: bool = False,
-) -> Optional[str]:
- """Return why neither the template phase nor current Strategist stage can launch."""
+def _confirmation_launch_error(confirm_dir: Path) -> Optional[str]:
+ """Return why the current Default UI lifecycle cannot launch."""
options_file = confirm_dir / TEMPLATE_OPTIONS_NAME
result_file = confirm_dir / RESULT_NAME
result_stage = _result_stage(result_file)
- fresh_stage1 = _fresh_stage1_restart(confirm_dir)
fresh_template_options = _fresh_template_restart(confirm_dir)
- if (
- result_file.exists()
- and fresh_stage1
- and options_file.exists()
- and not fresh_template_options
- ):
- return (
- f'{TEMPLATE_OPTIONS_NAME} belongs to an earlier Confirm UI run — '
- 'run --reset-template-phase before launching fresh Stage 1'
- )
if (
result_file.exists()
and result_stage is None
- and not fresh_stage1
and not fresh_template_options
):
return (
- f'{RESULT_NAME} is not a current stage1/final receipt — write fresh '
- f'template options or {RECOMMENDATION_STAGE_NAMES[1]} before '
+ f'{RESULT_NAME} is not a current stage1/final receipt — reset the '
+ f'template selection and write fresh {TEMPLATE_OPTIONS_NAME} before '
'starting a new run'
)
if (
result_stage == 'final'
- and not fresh_stage1
and not fresh_template_options
):
return (
- 'the previous Confirm UI run is complete — write fresh template '
- f'options or {RECOMMENDATION_STAGE_NAMES[1]} before starting a new one'
+ 'the previous Confirm UI run is complete — reset the template '
+ f'selection and write fresh {TEMPLATE_OPTIONS_NAME} before starting a new one'
)
if options_file.exists():
try:
_build_template_options(confirm_dir)
selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
+ if result_stage == 'stage1' and not selection_file.exists():
+ return (
+ f'{TEMPLATE_SELECTION_NAME} not found for the confirmed '
+ 'Stage 1 result'
+ )
if selection_file.exists():
_read_template_selection(selection_file)
except (OSError, json.JSONDecodeError, ValueError) as exc:
- return f'invalid template phase input: {exc}'
- return None
- if require_template:
- return f'{options_file} not found — cannot start the template phase'
-
- rec_file = _active_recommendations_path(confirm_dir)
- if rec_file.exists():
+ return f'invalid template selection input: {exc}'
+ if result_stage is None or fresh_template_options:
+ stage1_error = _stage1_ready_error(confirm_dir)
+ if stage1_error:
+ return f'Stage 1 is not ready: {stage1_error}'
return None
- return (
- f'{rec_file} and {options_file} not found — write template options or '
- 'the current Strategist recommendation before launch'
- )
+ return f'{options_file} not found — write template options before launch'
def _server_url(port: int, path: str = '') -> str:
@@ -1053,42 +1087,6 @@ def _wait_for_result(
time.sleep(0.5)
-def _wait_for_template_selection(
- selection_file: Path,
- proc: subprocess.Popen,
- started_at: float,
- timeout: int,
-) -> int:
- """Wait until this launch writes a fresh template-selection receipt."""
- logger.info('waiting for browser template selection...')
- deadline = None if timeout <= 0 else time.time() + timeout
- while True:
- if selection_file.exists():
- try:
- if selection_file.stat().st_mtime >= started_at:
- _read_template_selection(selection_file)
- logger.info('template selection received: %s', selection_file)
- return 0
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- logger.error('invalid template selection: %s', exc)
- return 2
-
- returncode = proc.poll()
- if returncode is not None:
- logger.error('confirm UI exited before a fresh template selection was written')
- return returncode or 1
-
- if deadline is not None and time.time() >= deadline:
- logger.error(
- 'timed out waiting for template selection — the page is still '
- 'open; re-check %s before falling back to chat',
- selection_file,
- )
- return 124
-
- time.sleep(0.5)
-
-
def _result_stage(result_file: Path) -> Optional[str]:
"""Return the current result stage (Stage 1 or final), or None."""
if not result_file.is_file():
@@ -1168,13 +1166,6 @@ def _is_newer(path: Path, baseline: Path) -> bool:
return False
-def _fresh_stage1_restart(confirm_dir: Path) -> bool:
- """Return whether a newly authored Stage 1 starts a fresh UI session."""
- stage1_file = _stage_recommendations_path(confirm_dir, 1)
- result_file = confirm_dir / RESULT_NAME
- return _is_newer(stage1_file, result_file)
-
-
def _fresh_template_restart(confirm_dir: Path) -> bool:
"""Return whether fresh template options start a new UI session."""
return _is_newer(
@@ -1185,7 +1176,7 @@ def _fresh_template_restart(confirm_dir: Path) -> bool:
def _active_recommendations_path(confirm_dir: Path) -> Path:
"""Resolve the recommendation file for the current two-stage session."""
- if _fresh_stage1_restart(confirm_dir) or _fresh_template_restart(confirm_dir):
+ if _fresh_template_restart(confirm_dir):
return _stage_recommendations_path(confirm_dir, 1)
result_stage = _result_stage(confirm_dir / RESULT_NAME)
expected_stage = _expected_recommendation_stage(result_stage)
@@ -1227,13 +1218,11 @@ def _read_active_recommendations(
def _template_confirmation_required(project_path: Path) -> bool:
"""Return whether the confirmed project state has an active template."""
confirm_dir = project_path / CONFIRM_DIR_NAME
- if (confirm_dir / TEMPLATE_OPTIONS_NAME).is_file():
- handoff = _read_template_handoff(
- project_path,
- confirm_dir / TEMPLATE_HANDOFF_NAME,
- )
- return handoff['mode'] == 'templates'
- return (project_path / 'templates' / 'design_spec.md').is_file()
+ handoff = _read_template_handoff(
+ project_path,
+ confirm_dir / TEMPLATE_HANDOFF_NAME,
+ )
+ return handoff['mode'] == 'templates'
def _template_stage2_error(
@@ -1686,7 +1675,7 @@ def _submission_stage_error(
previous_stage = (
None
- if _fresh_stage1_restart(confirm_dir)
+ if _fresh_template_restart(confirm_dir)
else _result_stage(confirm_dir / RESULT_NAME)
)
allowed_predecessors = {
@@ -1834,10 +1823,7 @@ def _build_session_state(
except (OSError, json.JSONDecodeError, ValueError) as exc:
rec_error = str(exc)
- fresh_restart = (
- _fresh_stage1_restart(confirm_dir)
- or _fresh_template_restart(confirm_dir)
- )
+ fresh_restart = _fresh_template_restart(confirm_dir)
result_stage = None if fresh_restart else _result_stage(result_file)
result_stage_number = _result_stage_number(result_stage)
@@ -1877,9 +1863,6 @@ def _build_session_state(
options_file = confirm_dir / TEMPLATE_OPTIONS_NAME
selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
handoff_file = confirm_dir / TEMPLATE_HANDOFF_NAME
- if not options_file.exists():
- return session
-
session.update({
'template_options_file': TEMPLATE_OPTIONS_NAME,
'template_options_version': _file_version(options_file),
@@ -1888,59 +1871,48 @@ def _build_session_state(
'template_handoff_file': TEMPLATE_HANDOFF_NAME,
'template_handoff_version': _file_version(handoff_file),
})
- try:
- _build_template_options(confirm_dir)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
+
+ if result_stage == 'final':
session.update({
- 'phase': 'template',
- 'status': 'error',
- 'current_stage': 'template',
- 'expected_stage': 'template',
- 'expected_stage_number': None,
- 'template_status': 'error',
- 'template_error': str(exc),
+ 'template_status': 'ready',
+ 'template_error': None,
})
return session
- if selection_file.exists():
- try:
- _read_template_selection(selection_file)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
+ if result_stage is None:
+ ready_error = _stage1_ready_error(confirm_dir)
+ if ready_error:
session.update({
- 'phase': 'template',
- 'status': 'waiting_agent',
- 'current_stage': 'template',
- 'expected_stage': 'template',
- 'expected_stage_number': None,
- 'template_status': 'invalid',
- 'template_error': str(exc),
+ 'status': 'error',
+ 'template_status': 'error',
+ 'template_error': ready_error,
})
+ if not session.get('recommendation_error'):
+ session['recommendation_error'] = ready_error
return session
- ready_error = _template_stage1_ready_error(
- confirm_dir.parent,
- confirm_dir,
- )
- if ready_error is None:
- session['template_status'] = 'ready'
- return session
session.update({
- 'phase': 'template',
+ 'template_status': 'ready_user',
+ 'template_error': None,
+ })
+ return session
+
+ ready_error = _stage2_ready_error(
+ confirm_dir.parent,
+ confirm_dir,
+ rec_file if rec_stage_number == 2 else None,
+ )
+ if ready_error:
+ session.update({
'status': 'waiting_agent',
- 'current_stage': 'template',
- 'expected_stage': 'stage1',
- 'expected_stage_number': 1,
- 'template_status': 'confirmed',
+ 'current_stage': 'stage1',
+ 'expected_stage': 'stage2',
+ 'expected_stage_number': 2,
+ 'template_status': 'waiting_agent',
'template_error': ready_error,
})
return session
-
session.update({
- 'phase': 'template',
- 'status': 'ready_user',
- 'current_stage': 'template',
- 'expected_stage': 'template',
- 'expected_stage_number': None,
- 'template_status': 'ready_user',
+ 'template_status': 'ready',
'template_error': None,
})
return session
@@ -2128,6 +2100,24 @@ def _wait_only_for_result(
if result_status is not None:
return result_status
+ confirm_dir = result_file.parent
+ if target_stage == 'stage1':
+ readiness_error = _stage1_ready_error(confirm_dir)
+ else:
+ recommendations_file = _active_recommendations_path(confirm_dir)
+ readiness_error = _stage2_ready_error(
+ confirm_dir.parent,
+ confirm_dir,
+ recommendations_file,
+ )
+ if readiness_error:
+ logger.error(
+ 'confirmation stage=%s is not ready: %s',
+ target_stage,
+ readiness_error,
+ )
+ return 1
+
lock = _read_lock(lock_file)
pid = _lock_pid(lock)
if not pid or not _process_alive(pid):
@@ -2149,13 +2139,21 @@ def _wait_result_status(
target_stage: str,
) -> Optional[int]:
"""Return a terminal wait status when the persisted result resolves the target."""
- if (
- _fresh_stage1_restart(result_file.parent)
- or _fresh_template_restart(result_file.parent)
- ):
+ if _fresh_template_restart(result_file.parent):
return None
current_stage = _result_stage(result_file)
if current_stage == target_stage:
+ if target_stage == 'stage1':
+ try:
+ _read_template_selection(
+ result_file.parent / TEMPLATE_SELECTION_NAME,
+ )
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ logger.error(
+ 'Stage 1 result has no valid template selection: %s',
+ exc,
+ )
+ return 2
logger.info('confirmation stage=%s received: %s', target_stage, result_file)
return 0
if _result_stage_number(current_stage) > _result_stage_number(target_stage):
@@ -2168,52 +2166,6 @@ def _wait_result_status(
return None
-def _wait_template_selection_status(selection_file: Path) -> Optional[int]:
- """Return a terminal wait status for the template-selection receipt."""
- if not selection_file.exists():
- return None
- try:
- _read_template_selection(selection_file)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- logger.error('invalid template selection: %s', exc)
- return 2
- logger.info('template selection received: %s', selection_file)
- return 0
-
-
-def _wait_only_for_template_selection(
- selection_file: Path,
- lock_file: Path,
- timeout: int,
-) -> int:
- """Attach to the running page and wait for Step-3 template selection."""
- logger.info('waiting for browser template selection...')
- deadline = None if timeout <= 0 else time.time() + timeout
- while True:
- selection_status = _wait_template_selection_status(selection_file)
- if selection_status is not None:
- return selection_status
-
- lock = _read_lock(lock_file)
- pid = _lock_pid(lock)
- if not pid or not _process_alive(pid):
- logger.error(
- 'confirm server is no longer running before template selection '
- 'was confirmed'
- )
- return 1
-
- if deadline is not None and time.time() >= deadline:
- logger.error(
- 'timed out waiting for template selection — the page may still '
- 'be open; re-check %s before falling back to chat',
- selection_file,
- )
- return 124
-
- time.sleep(0.5)
-
-
def _shutdown_existing(lock_file: Path) -> int:
"""Stop a confirm server left running for this project (idempotent).
@@ -2451,66 +2403,6 @@ def create_app(
resp.headers['Cache-Control'] = 'no-store'
return resp
- @app.route('/api/template-options')
- def get_template_options():
- """Serve indexed library groups and agent-supplied explicit candidates."""
- options_file = confirm_dir / TEMPLATE_OPTIONS_NAME
- if not options_file.exists():
- return jsonify({'error': f'{TEMPLATE_OPTIONS_NAME} not found'}), 404
- try:
- data, _ = _build_template_options(confirm_dir)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- return jsonify({'error': f'invalid template options: {exc}'}), 409
- resp = jsonify(data)
- resp.headers['Cache-Control'] = 'no-store'
- return resp
-
- @app.route('/api/template-confirm', methods=['POST'])
- def confirm_template():
- """Persist a template choice resolved only from current candidate keys."""
- payload = request.get_json(silent=True)
- if not isinstance(payload, dict):
- return jsonify({'error': 'invalid payload'}), 400
- try:
- options, candidates = _build_template_options(confirm_dir)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- return jsonify({'error': f'invalid template options: {exc}'}), 409
- try:
- receipt = _resolve_template_confirmation(
- payload,
- candidates,
- options['options_sha256'],
- )
- except ValueError as exc:
- return jsonify({'error': str(exc)}), 400
- selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
- if selection_file.exists():
- try:
- existing = _read_template_selection(selection_file)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- return jsonify({
- 'error': (
- f'existing template selection is invalid: {exc}; '
- 'the agent must run --reset-template-phase'
- ),
- }), 409
- if existing['selection_sha256'] == receipt['selection_sha256']:
- return jsonify({'status': 'ok', 'idempotent': True})
- return jsonify({
- 'error': (
- 'template phase is already confirmed with a different '
- 'selection; the agent must run --reset-template-phase'
- ),
- }), 409
- _write_json_atomic(selection_file, receipt)
- _sync_session_state(
- confirm_dir,
- server_port=app.config.get('SERVER_PORT'),
- event='template-submitted',
- )
- logger.info('template selection written to %s', selection_file)
- return jsonify({'status': 'ok'})
-
@app.route('/api/catalogs')
def get_catalogs():
"""Serve the option universe; canvas is synced live from config.py so
@@ -2554,13 +2446,13 @@ def create_app(
result_file = confirm_dir / RESULT_NAME
if (
_result_stage(result_file) == 'final'
- and not _fresh_stage1_restart(confirm_dir)
and not _fresh_template_restart(confirm_dir)
):
return jsonify({
'error': (
- 'the current Confirm UI run is complete; write a fresh '
- f'{RECOMMENDATION_STAGE_NAMES[1]} before starting another'
+ 'the current Confirm UI run is complete; reset the template '
+ f'selection and write fresh {TEMPLATE_OPTIONS_NAME} before '
+ 'starting another'
),
}), 409
rec_file = _active_recommendations_path(confirm_dir)
@@ -2573,17 +2465,35 @@ def create_app(
'error': f'invalid current recommendation file: {exc}',
}), 400
rec_stage_number = _recommendation_stage(data)
- if rec_stage_number == 1 and (confirm_dir / TEMPLATE_OPTIONS_NAME).exists():
- template_error = _template_stage1_ready_error(
+ if rec_stage_number == 1:
+ stage1_error = _stage1_ready_error(confirm_dir)
+ if stage1_error:
+ return jsonify({
+ 'error': f'Stage 1 is not ready: {stage1_error}',
+ }), 409
+ try:
+ template_options, _ = _build_template_options(confirm_dir)
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return jsonify({
+ 'error': f'invalid template options: {exc}',
+ }), 409
+ data['template_options'] = template_options
+ template_required = False
+ else:
+ stage2_error = _stage2_ready_error(
project_path,
confirm_dir,
+ rec_file,
)
- if template_error:
+ if stage2_error:
return jsonify({
- 'error': (
- 'template phase is not ready for Stage 1: '
- f'{template_error}'
- ),
+ 'error': f'Stage 2 is waiting for template handoff: {stage2_error}',
+ }), 409
+ try:
+ template_required = _template_confirmation_required(project_path)
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return jsonify({
+ 'error': f'cannot determine active template mode: {exc}',
}), 409
# Later stages render only downstream sections, so fold earlier confirmed
# choices from result.json back in. An in-run refresh then re-inits from
@@ -2596,12 +2506,6 @@ def create_app(
)
if language_error:
return jsonify({'error': language_error}), 409
- try:
- template_required = _template_confirmation_required(project_path)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- return jsonify({
- 'error': f'cannot determine active template mode: {exc}',
- }), 409
if not template_required:
data.pop('template_application', None)
if rec_stage_number == 2:
@@ -2648,26 +2552,12 @@ def create_app(
return jsonify({'error': 'invalid payload'}), 400
confirm_dir.mkdir(parents=True, exist_ok=True)
result = dict(payload)
+ template_selection_payload = result.pop('template_selection', None)
result_file = confirm_dir / RESULT_NAME
raw_stage = result.get('stage')
stage = _stage_key(raw_stage)
if raw_stage is not None and stage is None:
return jsonify({'error': 'invalid confirmation stage'}), 400
- if stage == 'stage1' and (confirm_dir / TEMPLATE_OPTIONS_NAME).exists():
- template_error = _template_stage1_ready_error(
- project_path,
- confirm_dir,
- )
- if template_error:
- return jsonify({
- 'error': f'template phase is not ready for Stage 1: {template_error}',
- }), 409
- try:
- template_required = _template_confirmation_required(project_path)
- except (OSError, json.JSONDecodeError, ValueError) as exc:
- return jsonify({
- 'error': f'cannot determine active template mode: {exc}',
- }), 409
try:
rec_file, current_recommendations = _read_active_recommendations(
confirm_dir,
@@ -2679,6 +2569,79 @@ def create_app(
f'{exc}'
),
}), 409
+ rec_stage_number = _recommendation_stage(current_recommendations)
+ selection_receipt = None
+ selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
+ write_selection = False
+ if rec_stage_number == 1:
+ stage1_error = _stage1_ready_error(confirm_dir)
+ if stage1_error:
+ return jsonify({
+ 'error': f'Stage 1 is not ready: {stage1_error}',
+ }), 409
+ if not isinstance(template_selection_payload, dict):
+ return jsonify({
+ 'error': (
+ 'Stage 1 payload must include template_selection with '
+ 'mode and selection_keys'
+ ),
+ }), 400
+ try:
+ template_options, template_candidates = _build_template_options(
+ confirm_dir,
+ )
+ selection_receipt = _resolve_template_confirmation(
+ template_selection_payload,
+ template_candidates,
+ template_options['options_sha256'],
+ )
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return jsonify({
+ 'error': f'invalid Stage 1 template selection: {exc}',
+ }), 400
+ template_required = selection_receipt['mode'] == 'templates'
+ if selection_file.exists():
+ try:
+ existing_selection = _read_template_selection(selection_file)
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return jsonify({
+ 'error': (
+ f'existing template selection is invalid: {exc}; '
+ 'the agent must run --reset-template-selection'
+ ),
+ }), 409
+ if (
+ existing_selection['selection_sha256']
+ != selection_receipt['selection_sha256']
+ ):
+ return jsonify({
+ 'error': (
+ 'Stage 1 already has a different template selection; '
+ 'the agent must run --reset-template-selection'
+ ),
+ }), 409
+ else:
+ write_selection = True
+ else:
+ if template_selection_payload is not None:
+ return jsonify({
+ 'error': 'template_selection is accepted only in Stage 1',
+ }), 400
+ stage2_error = _stage2_ready_error(
+ project_path,
+ confirm_dir,
+ rec_file,
+ )
+ if stage2_error:
+ return jsonify({
+ 'error': f'Stage 2 is waiting for template handoff: {stage2_error}',
+ }), 409
+ try:
+ template_required = _template_confirmation_required(project_path)
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ return jsonify({
+ 'error': f'cannot determine active template mode: {exc}',
+ }), 409
stage_error = _submission_stage_error(
confirm_dir,
stage,
@@ -2691,7 +2654,6 @@ def create_app(
custom_error = _custom_selection_error(result)
if custom_error:
return jsonify({'error': custom_error}), 400
- rec_stage_number = _recommendation_stage(current_recommendations)
previous_result = {}
if rec_stage_number >= 2:
try:
@@ -2746,7 +2708,7 @@ def create_app(
result_file,
carry_previous=rec_stage_number > 1,
)
- if not template_required:
+ if rec_stage_number == 1 or not template_required:
result.pop('template_application', None)
locked_values.pop('template_application', None)
result.pop('template_reuse_scope', None)
@@ -2761,6 +2723,8 @@ def create_app(
result['stage'] = 'final'
result['status'] = 'confirmed'
result['confirmed_at'] = time.strftime('%Y-%m-%dT%H:%M:%S')
+ if write_selection and selection_receipt is not None:
+ _write_json_atomic(selection_file, selection_receipt)
_write_json_atomic(result_file, result)
_sync_session_state(
confirm_dir,
@@ -2790,7 +2754,7 @@ def build_parser() -> argparse.ArgumentParser:
)
parser.add_argument(
'--wait', action='store_true',
- help='With --daemon, wait until the requested template/result receipt is written',
+ help='With --daemon, wait until the active result.json stage is written',
)
parser.add_argument(
'--wait-only', action='store_true',
@@ -2800,10 +2764,9 @@ def build_parser() -> argparse.ArgumentParser:
'dead server on the recorded/default port so browser polling can resume.',
)
parser.add_argument(
- '--wait-stage', default='final', metavar='{template,stage1,final}',
- help='Wait for the Step-3 template selection or this result.json stage '
- '(default: final). Use template after the initial template-phase '
- 'launch and stage1 after the communication-contract handoff.',
+ '--wait-stage', default='final', metavar='{stage1,final}',
+ help='Wait for this result.json stage (default: final). Use stage1 '
+ 'after opening the combined template/communication page.',
)
parser.add_argument(
'--wait-timeout', type=int, default=WAIT_TIMEOUT_DEFAULT,
@@ -2821,12 +2784,12 @@ def build_parser() -> argparse.ArgumentParser:
'on its selected port before live preview starts.',
)
parser.add_argument(
- '--complete-template-phase', action='store_true',
- help='Agent-only: bind the current template selection to a ready handoff. '
- 'Template mode requires <project>/templates/design_spec.md.',
+ '--complete-template-selection', action='store_true',
+ help='Agent-only: after Stage 1, bind its template selection to a ready '
+ 'handoff. Template mode requires <project>/templates/design_spec.md.',
)
parser.add_argument(
- '--reset-template-phase', action='store_true',
+ '--reset-template-selection', action='store_true',
help='Agent-only: remove exactly template_options.json, '
'template_selection.json, and template_handoff.json before a '
'fresh one-run UI lifecycle.',
@@ -2855,30 +2818,33 @@ def main(argv: Optional[list[str]] = None) -> int:
if not project_path.is_dir():
logger.error('%s is not a directory', project_path)
return 1
- raw_wait_stage = str(args.wait_stage).strip().lower()
- wait_stage = 'template' if raw_wait_stage == 'template' else _stage_key(raw_wait_stage)
- if wait_stage not in {'template', 'stage1', 'final'}:
- logger.error('--wait-stage must be template, stage1, or final')
+ wait_stage = _stage_key(str(args.wait_stage).strip().lower())
+ if wait_stage not in {'stage1', 'final'}:
+ logger.error('--wait-stage must be stage1 or final')
return 2
- template_control = args.complete_template_phase or args.reset_template_phase
+ template_control = (
+ args.complete_template_selection
+ or args.reset_template_selection
+ )
if template_control and (
args.daemon or args.wait or args.wait_only or args.shutdown
):
logger.error(
- '--complete-template-phase/--reset-template-phase cannot be combined '
+ '--complete-template-selection/--reset-template-selection cannot be combined '
'with server, wait, or shutdown actions'
)
return 2
- if args.complete_template_phase and args.reset_template_phase:
+ if args.complete_template_selection and args.reset_template_selection:
logger.error(
- '--complete-template-phase and --reset-template-phase are mutually exclusive'
+ '--complete-template-selection and --reset-template-selection are '
+ 'mutually exclusive'
)
return 2
- if args.complete_template_phase:
- return _complete_template_phase(project_path)
- if args.reset_template_phase:
- return _reset_template_phase(project_path / CONFIRM_DIR_NAME)
+ if args.complete_template_selection:
+ return _complete_template_selection(project_path)
+ if args.reset_template_selection:
+ return _reset_template_selection(project_path / CONFIRM_DIR_NAME)
# Step 4 cleanup: stop any lingering confirm server and exit. Independent of
# recommendation files (the page may never have been confirmed).
@@ -2886,32 +2852,35 @@ def main(argv: Optional[list[str]] = None) -> int:
return _shutdown_existing(project_path / LOCK_FILE_NAME)
# Staged wait: attach to the server launched by --daemon and block until
- # the page writes the requested template or Strategist receipt.
+ # the page writes the requested Strategist receipt.
if args.wait_only:
lock_file = project_path / LOCK_FILE_NAME
confirm_dir = project_path / CONFIRM_DIR_NAME
result_file = confirm_dir / RESULT_NAME
- selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
- if wait_stage == 'template':
- wait_status = _wait_template_selection_status(selection_file)
- if wait_status is not None:
- return wait_status
- launch_error = _confirmation_launch_error(
+ wait_status = _wait_result_status(result_file, wait_stage)
+ if wait_status is not None:
+ return wait_status
+ if wait_stage == 'stage1':
+ readiness_error = _stage1_ready_error(confirm_dir)
+ else:
+ recommendations_file = _active_recommendations_path(confirm_dir)
+ readiness_error = _stage2_ready_error(
+ project_path,
confirm_dir,
- require_template=True,
+ recommendations_file,
)
+ if readiness_error:
+ logger.error(
+ 'confirmation stage=%s is not ready: %s',
+ wait_stage,
+ readiness_error,
+ )
+ return 1
+ if not _live_lock(lock_file):
+ launch_error = _confirmation_launch_error(confirm_dir)
if launch_error:
logger.error('%s', launch_error)
return 1
- if not _live_lock(lock_file):
- if wait_stage != 'template':
- wait_status = _wait_result_status(result_file, wait_stage)
- if wait_status is not None:
- return wait_status
- launch_error = _confirmation_launch_error(confirm_dir)
- if launch_error:
- logger.error('%s', launch_error)
- return 1
exact_port = args.port is not None
recovery_port = (
args.port
@@ -2935,12 +2904,6 @@ def main(argv: Optional[list[str]] = None) -> int:
'recovered confirm UI for wait-only at %s; the browser polling should resume',
_server_url(actual_port),
)
- if wait_stage == 'template':
- return _wait_only_for_template_selection(
- selection_file,
- lock_file,
- args.wait_timeout,
- )
return _wait_only_for_result(
result_file,
lock_file,
@@ -2949,10 +2912,7 @@ def main(argv: Optional[list[str]] = None) -> int:
)
confirm_dir = project_path / CONFIRM_DIR_NAME
- launch_error = _confirmation_launch_error(
- confirm_dir,
- require_template=args.daemon and args.wait and wait_stage == 'template',
- )
+ launch_error = _confirmation_launch_error(confirm_dir)
if launch_error:
logger.error('%s', launch_error)
return 1
@@ -2972,7 +2932,6 @@ def main(argv: Optional[list[str]] = None) -> int:
confirm_dir = project_path / CONFIRM_DIR_NAME
result_file = confirm_dir / RESULT_NAME
- selection_file = confirm_dir / TEMPLATE_SELECTION_NAME
expected_stage = _expected_result_stage(confirm_dir)
started_at = time.time()
try:
@@ -2987,13 +2946,6 @@ def main(argv: Optional[list[str]] = None) -> int:
logger.error('%s', exc)
return 1
if args.wait:
- if wait_stage == 'template':
- return _wait_for_template_selection(
- selection_file,
- proc,
- started_at,
- args.wait_timeout,
- )
return _wait_for_result(
result_file,
proc,
diff --git a/skills/ppt-master/scripts/confirm_ui/static/app.js b/skills/ppt-master/scripts/confirm_ui/static/app.js
index 35aec5e2..51a82d5e 100644
--- a/skills/ppt-master/scripts/confirm_ui/static/app.js
+++ b/skills/ppt-master/scripts/confirm_ui/static/app.js
@@ -1,7 +1,7 @@
-/* PPT Master - conditional template selection and Strategist confirmation UI
- * Explicit template requests use Generate Step 3 before Stage 1; ordinary free
- * design starts at Stage 1. Stage 2 combines the coherent deck solution and
- * production mechanics, then writes the final result.
+/* PPT Master - Strategist confirmation UI
+ * Stage 1 confirms the communication contract and the free-design/template
+ * choice together. Stage 2 combines the coherent deck solution and production
+ * mechanics, then writes the final result.
* Finite fields use /static/catalogs.json; coordinated design directions seed
* color, typography, icons, generated-image rendering, and conditional
* template-application prose. Final confirm saves result.json.
@@ -14,30 +14,25 @@
en: {
page_title: "PPT Master - Confirm Design",
topbar_hint: "Answer the open questions, or pick and customize recommendations, then continue.",
- template_stage_title: "Choose a template",
- template_stage_hint: "Choose free design, or combine one registered template per type plus one specified path. This selection is separate from Stage 1.",
stage_anchors: "Stage 1 · Communication contract",
stage_final_plan: "Stage 2 · Final plan & production",
loading: "Loading…",
load_error: "Could not load the current recommendation stage. The AI must write it before launch.",
btn_confirm: "Confirm",
- btn_confirm_template: "Confirm template & continue →",
btn_confirm_contract: "Confirm contract & continue →",
btn_confirm_final_plan: "Confirm final plan →",
deriving: "Generating the downstream options from your choices…",
- template_applying: "Applying the template selection and preparing Stage 1…",
- template_load_error: "Could not load the available templates.",
- template_submit_error: "Could not confirm the template selection.",
- template_selection_required: "Choose free design or at least one template.",
- template_free_selected: "Free design selected",
- template_count_selected: "{count} template(s) selected",
+ template_selection_required: "Choose free design or use templates. When using templates, select at least one workspace.",
connection_lost: "Connection to the confirm server was interrupted; retrying. If this keeps failing, return to the chat for confirmation.",
confirmed_title: "✓ Confirmed",
confirmed_hint: "Your choices are saved. You can close this page and return to the chat.",
lang_toggle_title: "Switch language",
- sec_template_free: "Free design",
+ sec_template_choice: "Design basis",
+ template_choice_hint: "Choose how this deck should establish its design system.",
template_free_title: "Design from the current content",
template_free_desc: "Use no reusable template workspace. The Strategist will derive the visual system from this project.",
+ template_use_title: "Use templates",
+ template_use_desc: "Select one or more reusable Brand, Style, Layout, Deck, or specified workspaces.",
sec_template_library: "Template combination",
template_library_hint: "Choose at most one registered template for each type. Brand, Style, Layout, and Deck can be combined.",
sec_template_explicit: "Specified templates",
@@ -197,30 +192,25 @@
ja: {
page_title: "PPT Master - デザイン確認",
topbar_hint: "自由記述の質問に答えるか、提案を選択・調整して次へ進んでください。",
- template_stage_title: "テンプレートを選択",
- template_stage_hint: "自由デザイン、または種類ごとに登録済み1件と指定パス1件までを組み合わせます。この選択はステージ1とは独立しています。",
stage_anchors: "ステージ 1 · コミュニケーション契約",
stage_final_plan: "ステージ 2 · 最終プランと制作",
loading: "読み込み中…",
load_error: "現在の推奨ステージを読み込めませんでした。起動前にAIが書き込む必要があります。",
btn_confirm: "確定",
- btn_confirm_template: "テンプレートを確定して次へ →",
btn_confirm_contract: "契約内容を確定して次へ →",
btn_confirm_final_plan: "最終プランを確定 →",
deriving: "選択内容をもとに後続の選択肢を生成しています…",
- template_applying: "テンプレートの選択を適用し、ステージ1を準備しています…",
- template_load_error: "利用可能なテンプレートを読み込めませんでした。",
- template_submit_error: "テンプレートの選択を確定できませんでした。",
- template_selection_required: "自由デザイン、または1つ以上のテンプレートを選択してください。",
- template_free_selected: "自由デザインを選択中",
- template_count_selected: "{count} 件のテンプレートを選択中",
+ template_selection_required: "自由デザインまたはテンプレート利用を選んでください。テンプレート利用時は、1つ以上のワークスペースを選択してください。",
connection_lost: "確認ページのサーバー接続が中断されました。再試行しています。失敗が続く場合はチャットで確認してください。",
confirmed_title: "✓ 確定しました",
confirmed_hint: "選択内容を保存しました。このページを閉じてチャットに戻ってください。",
lang_toggle_title: "言語を切り替え",
- sec_template_free: "自由デザイン",
+ sec_template_choice: "デザインの基準",
+ template_choice_hint: "この資料のデザインシステムをどう決めるか選択します。",
template_free_title: "現在の内容からデザインする",
template_free_desc: "再利用テンプレートを使わず、Strategist がこのプロジェクトからビジュアルシステムを組み立てます。",
+ template_use_title: "テンプレートを使用",
+ template_use_desc: "Brand、Style、Layout、Deck、または指定ワークスペースから1つ以上選択します。",
sec_template_library: "テンプレートの組み合わせ",
template_library_hint: "登録済みテンプレートは種類ごとに1件まで選択でき、Brand、Style、Layout、Deck を組み合わせられます。",
sec_template_explicit: "指定テンプレート",
@@ -380,30 +370,25 @@
zh: {
page_title: "确认设计方案",
topbar_hint: "回答开放问题,或选择并调整推荐项,然后继续。",
- template_stage_title: "选择模板",
- template_stage_hint: "选择自由设计,或组合每类一个已注册模板与一个指定地址。这个选择独立于 Stage 1。",
stage_anchors: "第一阶段 · 沟通契约",
stage_final_plan: "第二阶段 · 最终方案与制作",
loading: "加载中…",
load_error: "无法加载推荐文件,需在启动前写入。",
btn_confirm: "确认",
- btn_confirm_template: "确认模板并继续 →",
btn_confirm_contract: "确认沟通契约并继续 →",
btn_confirm_final_plan: "确认最终方案 →",
deriving: "正在根据你的选择生成下游选项…",
- template_applying: "正在应用模板选择并准备 Stage 1…",
- template_load_error: "无法加载可用模板。",
- template_submit_error: "无法确认模板选择。",
- template_selection_required: "请选择自由设计或至少一个模板。",
- template_free_selected: "已选择自由设计",
- template_count_selected: "已选择 {count} 个模板",
+ template_selection_required: "请选择自由设计或使用模板;选择使用模板时,至少选择一个工作区。",
connection_lost: "确认页服务连接中断,正在重试;如果持续失败,请回到聊天窗口走聊天确认。",
confirmed_title: "✓ 已确认",
confirmed_hint: "选择已保存,可关闭此页并回到聊天窗口。",
lang_toggle_title: "切换语言",
- sec_template_free: "自由设计",
+ sec_template_choice: "设计基础",
+ template_choice_hint: "选择这份演示文稿如何建立设计系统。",
template_free_title: "根据当前内容从零设计",
template_free_desc: "不使用可复用模板工作区,由 Strategist 根据当前项目推导视觉系统。",
+ template_use_title: "使用模板",
+ template_use_desc: "选择一个或多个 Brand、Style、Layout、Deck 或指定工作区。",
sec_template_library: "模板组合",
template_library_hint: "每种已注册模板最多选择一个;Brand、Style、Layout、Deck 可以组合使用。",
sec_template_explicit: "指定模板",
@@ -693,9 +678,7 @@
var TEMPLATE_CANDIDATES = [];
var TEMPLATE_SELECTED_KEYS = [];
var TEMPLATE_SELECTIONS = { brand: "", style: "", layout: "", deck: "", explicit: "" };
- var TEMPLATE_MODE = "free_design";
- var TEMPLATE_PHASE = false;
- var TEMPLATE_SUBMITTING = false;
+ var TEMPLATE_MODE = "";
var REC_ALIASES = {
icons: {
line: "tabler-outline",
@@ -847,7 +830,7 @@
note.textContent = text;
}
- // ---- Step 3 template selection ---------------------------------------
+ // ---- Stage 1 template selection --------------------------------------
function normalizeTemplateCandidates(raw, source, kind) {
if (!Array.isArray(raw)) return [];
return raw.filter(function (candidate) {
@@ -864,8 +847,13 @@
function initTemplateOptions(data) {
var library = data && data.library && typeof data.library === "object"
? data.library : {};
+ var defaultMode = data && data.default_mode;
+ if (defaultMode !== "free_design" && defaultMode !== "templates") {
+ throw new Error("template_options.default_mode must be free_design or templates");
+ }
var normalized = {
lang: data && data.lang,
+ default_mode: defaultMode,
library: {},
explicit: [],
preselected_keys: Array.isArray(data && data.preselected_keys)
@@ -901,6 +889,7 @@
TEMPLATE_SELECTIONS[slot] = key;
});
syncTemplateSelectionState();
+ TEMPLATE_MODE = normalized.default_mode;
TEMPLATE_OPTIONS = normalized;
}
@@ -931,7 +920,6 @@
});
TEMPLATE_SELECTED_KEYS.push(TEMPLATE_SELECTIONS.explicit);
TEMPLATE_SELECTED_KEYS = TEMPLATE_SELECTED_KEYS.filter(Boolean);
- TEMPLATE_MODE = TEMPLATE_SELECTED_KEYS.length ? "templates" : "free_design";
}
function templateCandidateTitle(candidate) {
@@ -949,12 +937,19 @@
function chooseFreeDesign() {
TEMPLATE_SELECTIONS = emptyTemplateSelections();
syncTemplateSelectionState();
+ TEMPLATE_MODE = "free_design";
+ updateTemplateSelectionControls();
+ }
+
+ function chooseTemplateMode() {
+ TEMPLATE_MODE = "templates";
updateTemplateSelectionControls();
}
function chooseTemplateForSlot(slot, key) {
TEMPLATE_SELECTIONS[slot] = String(key || "");
syncTemplateSelectionState();
+ TEMPLATE_MODE = "templates";
updateTemplateSelectionControls();
}
@@ -1010,25 +1005,40 @@
return field;
}
- function renderTemplateFreeDesign(host) {
- var sec = section("F", "sec_template_free");
- var selected = TEMPLATE_MODE === "free_design";
- var choice = el("button", "template-free-choice" + (selected ? " selected" : ""));
- choice.id = "template-free-choice";
+ function renderTemplateModeChoice(id, mode, titleKey, descKey, onSelect) {
+ var selected = TEMPLATE_MODE === mode;
+ var choice = el("button", "template-mode-choice" + (selected ? " selected" : ""));
+ choice.id = id;
choice.type = "button";
choice.setAttribute("aria-pressed", selected ? "true" : "false");
choice.appendChild(el("span", "template-choice-radio"));
- var copy = el("span", "template-free-copy");
- copy.appendChild(el("span", "template-free-title", t("template_free_title")));
- copy.appendChild(el("span", "template-free-desc", t("template_free_desc")));
+ var copy = el("span", "template-choice-copy");
+ copy.appendChild(el("span", "template-choice-title", t(titleKey)));
+ copy.appendChild(el("span", "template-choice-desc", t(descKey)));
choice.appendChild(copy);
- choice.addEventListener("click", chooseFreeDesign);
- sec.appendChild(choice);
- host.appendChild(sec);
+ choice.addEventListener("click", onSelect);
+ return choice;
}
- function renderTemplateSelectors(host) {
- var sec = section("L", "sec_template_library", t("template_library_hint"));
+ function renderTemplateSelection(host) {
+ if (!TEMPLATE_OPTIONS) return;
+ var sec = section("T", "sec_template_choice", t("template_choice_hint"));
+ var choices = el("div", "template-mode-choices");
+ choices.appendChild(renderTemplateModeChoice(
+ "template-free-choice", "free_design", "template_free_title",
+ "template_free_desc", chooseFreeDesign
+ ));
+ var useChoice = renderTemplateModeChoice(
+ "template-use-choice", "templates", "template_use_title",
+ "template_use_desc", chooseTemplateMode
+ );
+ useChoice.setAttribute("aria-controls", "template-selector-panel");
+ choices.appendChild(useChoice);
+ sec.appendChild(choices);
+
+ var panel = el("div", "template-selector-panel");
+ panel.id = "template-selector-panel";
+ panel.appendChild(el("div", "template-selector-hint", t("template_library_hint")));
var grid = el("div", "template-select-grid");
TEMPLATE_KINDS.forEach(function (kind) {
var candidates = TEMPLATE_OPTIONS.library[kind] || [];
@@ -1039,8 +1049,10 @@
t("template_source_explicit"),
TEMPLATE_OPTIONS.explicit || []
));
- sec.appendChild(grid);
+ panel.appendChild(grid);
+ sec.appendChild(panel);
host.appendChild(sec);
+ updateTemplateSelectionControls();
}
function updateTemplateExplicitPath() {
@@ -1056,49 +1068,27 @@
function updateTemplateSelectionControls() {
var freeChoice = document.getElementById("template-free-choice");
+ var useChoice = document.getElementById("template-use-choice");
+ var selectorPanel = document.getElementById("template-selector-panel");
var freeSelected = TEMPLATE_MODE === "free_design";
+ var templatesSelected = TEMPLATE_MODE === "templates";
if (freeChoice) {
freeChoice.classList.toggle("selected", freeSelected);
freeChoice.setAttribute("aria-pressed", freeSelected ? "true" : "false");
}
+ if (useChoice) {
+ useChoice.classList.toggle("selected", templatesSelected);
+ useChoice.setAttribute("aria-pressed", templatesSelected ? "true" : "false");
+ useChoice.setAttribute("aria-expanded", templatesSelected ? "true" : "false");
+ }
+ if (selectorPanel) selectorPanel.hidden = !templatesSelected;
TEMPLATE_KINDS.concat(["explicit"]).forEach(function (slot) {
var select = document.getElementById("template-select-" + slot);
if (select) select.value = TEMPLATE_SELECTIONS[slot] || "";
});
updateTemplateExplicitPath();
- updateTemplateSelectionStatus();
- }
-
- function updateTemplateSelectionStatus() {
var status = document.getElementById("confirm-status");
- if (!status) return;
- status.textContent = TEMPLATE_MODE === "free_design"
- ? t("template_free_selected")
- : t("template_count_selected").replace("{count}", String(TEMPLATE_SELECTED_KEYS.length));
- }
-
- function renderTemplatePhase() {
- if (!TEMPLATE_OPTIONS) return;
- TEMPLATE_PHASE = true;
- var heading = document.querySelector("#topbar .topbar-titles h1");
- if (heading) heading.textContent = t("template_stage_title");
- var hint = document.getElementById("topbar-hint");
- if (hint) hint.textContent = t("template_stage_hint");
- var previewHost = document.getElementById("topbar-preview");
- if (previewHost) previewHost.innerHTML = "";
- var host = document.getElementById("sections");
- host.innerHTML = "";
- _secCounter = 0;
- renderTemplateFreeDesign(host);
- renderTemplateSelectors(host);
- document.getElementById("error").style.display = "none";
- document.getElementById("loading").style.display = "none";
- host.style.display = "block";
- document.getElementById("actionbar").style.display = "flex";
- var btn = document.getElementById("btn-confirm");
- btn.disabled = false;
- btn.textContent = t("btn_confirm_template");
- updateTemplateSelectionControls();
+ if (status) status.textContent = "";
}
function normalizeRecId(field, value) {
@@ -3277,11 +3267,13 @@
var previewHost = document.getElementById("topbar-preview");
if (previewHost) previewHost.innerHTML = "";
if (stage === 1) {
- // Scene and communication intent come first; no design tool is
- // selected before the contract exists.
+ // Stage 1 closes the communication contract and its design basis in
+ // one submission. Detailed template controls stay hidden until the
+ // user explicitly chooses template-backed design.
renderCommunication(host);
renderDelivery(host);
renderCanvas(host);
+ renderTemplateSelection(host);
} else if (stage === 2) {
if (previewHost) renderStylePreview(previewHost);
if (previewHost) renderImageStrategyPreview(previewHost);
@@ -3467,74 +3459,6 @@
ov.style.display = "flex";
}
- function showTemplateApplying() {
- TEMPLATE_SUBMITTING = true;
- document.getElementById("sections").style.display = "none";
- document.getElementById("actionbar").style.display = "none";
- var loading = document.getElementById("loading");
- loading.textContent = t("template_applying");
- loading.style.display = "block";
- }
-
- function pollForTemplateStage1() {
- fetchJson("/api/session", "session").then(function (session) {
- var readyStage = Number(session && session.recommendation_stage_number || 0);
- if (session && (session.status === "error" || session.template_status === "error")) {
- TEMPLATE_SUBMITTING = false;
- showError(session.template_error || t("template_load_error"));
- return null;
- }
- if (session && session.template_status === "invalid") {
- showError(session.template_error || t("template_load_error"));
- setTimeout(pollForTemplateStage1, 1200);
- return null;
- }
- if (session && session.phase === "template" && session.template_status === "ready_user") {
- TEMPLATE_SUBMITTING = false;
- return loadTemplateUi(session).catch(function (err) {
- showError(t("template_load_error") + " " +
- (err && err.message ? err.message : ""));
- return null;
- });
- }
- if (session && session.phase === "strategist" && readyStage >= 1) {
- return loadStrategistUi(1);
- }
- setTimeout(pollForTemplateStage1, 1200);
- return null;
- }).catch(function (err) {
- var loading = document.getElementById("loading");
- if (loading) {
- loading.textContent = t("connection_lost") + " " +
- (err && err.message ? err.message : "");
- }
- setTimeout(pollForTemplateStage1, 1500);
- });
- }
-
- function submitTemplateSelection() {
- if (TEMPLATE_SUBMITTING) return;
- if (TEMPLATE_MODE !== "free_design" && !TEMPLATE_SELECTED_KEYS.length) {
- document.getElementById("confirm-status").textContent = t("template_selection_required");
- return;
- }
- var payload = {
- mode: TEMPLATE_MODE,
- selection_keys: TEMPLATE_MODE === "templates" ? TEMPLATE_SELECTED_KEYS.slice() : []
- };
- var btn = document.getElementById("btn-confirm");
- btn.disabled = true;
- postJson("/api/template-confirm", payload, "template confirmation").then(function () {
- showTemplateApplying();
- pollForTemplateStage1();
- }).catch(function (err) {
- TEMPLATE_SUBMITTING = false;
- btn.disabled = false;
- document.getElementById("confirm-status").textContent =
- t("template_submit_error") + " " + (err && err.message ? err.message : t("error_retry"));
- });
- }
-
// ---- staged submit + next-stage transitions -------------------------
function communicationPayload() {
var payload = {
@@ -3556,6 +3480,11 @@
function stage1Payload() {
var payload = communicationPayload();
payload.stage = "stage1";
+ payload.template_selection = {
+ mode: TEMPLATE_MODE,
+ selection_keys: TEMPLATE_MODE === "templates"
+ ? TEMPLATE_SELECTED_KEYS.slice() : []
+ };
return payload;
}
@@ -3668,7 +3597,18 @@
return true;
}
+ function templateSelectionValid() {
+ var valid = TEMPLATE_MODE === "free_design" ||
+ (TEMPLATE_MODE === "templates" && TEMPLATE_SELECTED_KEYS.length > 0);
+ if (!valid) {
+ document.getElementById("confirm-status").textContent =
+ t("template_selection_required");
+ }
+ return valid;
+ }
+
function submitStage1() {
+ if (!templateSelectionValid()) return;
submitStage(stage1Payload(), 2);
}
@@ -3789,29 +3729,6 @@
});
}
- function postJson(url, payload, label) {
- return fetch(url, {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify(payload)
- }).then(function (r) {
- return r.text().then(function (text) {
- var data = null;
- if (text) {
- try { data = JSON.parse(text); }
- catch (e) {
- if (r.ok) throw new Error((label || url) + ": invalid JSON");
- }
- }
- if (!r.ok) {
- var serverMsg = data && data.error ? data.error : (text || r.statusText || r.status);
- throw new Error((label || url) + ": " + serverMsg);
- }
- return data || {};
- });
- });
- }
-
function loadCatalogs() {
return fetchJson("/api/catalogs", "catalogs")
.catch(function () { return fetchJson("/static/catalogs.json", "static catalogs"); });
@@ -3851,29 +3768,20 @@
ICON_PREVIEWS = res[2] || {};
AI_IMAGE_COMPARISON = res[3] || {};
applyServerLanguage(REC);
+ var activeStage = forceStage || stageNumber(REC);
+ if (activeStage === 1) {
+ if (!REC.template_options || typeof REC.template_options !== "object" ||
+ Array.isArray(REC.template_options)) {
+ throw new Error("Stage 1 recommendations must include template_options");
+ }
+ initTemplateOptions(REC.template_options);
+ }
initState();
- TEMPLATE_PHASE = false;
- TEMPLATE_SUBMITTING = false;
- enterStage(REC, forceStage || stageNumber(REC));
+ enterStage(REC, activeStage);
return REC;
});
}
- function loadTemplateUi(session) {
- return fetchJson("/api/template-options", "template options").then(function (options) {
- applyServerLanguage(options);
- initTemplateOptions(options);
- TEMPLATE_PHASE = true;
- if (session && (session.template_status === "confirmed" || session.status === "waiting_agent")) {
- showTemplateApplying();
- pollForTemplateStage1();
- } else {
- renderTemplatePhase();
- }
- return options;
- });
- }
-
function boot() {
applyStaticTranslations();
var toggleBtn = document.getElementById("btn-lang-toggle");
@@ -3896,12 +3804,7 @@
try { window.localStorage.setItem("ppt_lang", LANG); } catch (e2) { /* ignore */ }
applyStaticTranslations();
refreshLangToggle(toggleBtn);
- if (TEMPLATE_PHASE && TEMPLATE_SUBMITTING) {
- var loading = document.getElementById("loading");
- if (loading) loading.textContent = t("template_applying");
- } else if (TEMPLATE_PHASE && TEMPLATE_OPTIONS) {
- renderTemplatePhase();
- } else if (REC && CAT) {
+ if (REC && CAT) {
renderAll(); // STATE persists → selections preserved
}
};
@@ -3958,15 +3861,14 @@
if (!langMenu.hidden) setMenuOpen(false);
});
document.getElementById("btn-confirm").addEventListener("click", function () {
- if (TEMPLATE_PHASE) submitTemplateSelection();
- else if (STAGE === 1) submitStage1();
+ if (STAGE === 1) submitStage1();
else if (STAGE === 2) submitStage2();
else confirm();
});
- // Session is the first network read. Explicit template requests expose
- // Step 3; ordinary free design reports `strategist` and starts with
- // Stage 1.
+ // Session remains the first network read so completed runs can close
+ // cleanly. Active runs always load the current Strategist stage; Stage 1
+ // carries its template catalog inside the recommendation payload.
fetchJson("/api/session", "session").catch(function () {
return { phase: "strategist" };
}).then(function (session) {
@@ -3975,13 +3877,6 @@
showConfirmedOverlay();
return null;
}
- if (session && session.phase === "template") {
- return loadTemplateUi(session).catch(function (err) {
- showError(t("template_load_error") + " " +
- (err && err.message ? err.message : ""));
- return null;
- });
- }
return loadStrategistUi().catch(function (err) {
showError(t("load_error") + " " + (err && err.message ? err.message : ""));
return null;
diff --git a/skills/ppt-master/scripts/confirm_ui/static/style.css b/skills/ppt-master/scripts/confirm_ui/static/style.css
index 1165ec85..28f526b4 100644
--- a/skills/ppt-master/scripts/confirm_ui/static/style.css
+++ b/skills/ppt-master/scripts/confirm_ui/static/style.css
@@ -601,8 +601,13 @@ textarea.text-input { resize: vertical; line-height: 1.5; }
.subfield { margin-top: 14px; }
.subfield-label { font-size: 12.5px; color: var(--muted); margin-bottom: 7px; }
-/* ---- Step 3 template selection ---- */
-.template-free-choice {
+/* ---- Stage 1 template selection ---- */
+.template-mode-choices {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 12px;
+}
+.template-mode-choice {
width: 100%;
display: flex;
align-items: flex-start;
@@ -616,14 +621,14 @@ textarea.text-input { resize: vertical; line-height: 1.5; }
cursor: pointer;
transition: border-color .12s ease, background .12s ease, box-shadow .12s ease;
}
-.template-free-choice:hover {
+.template-mode-choice:hover {
border-color: var(--accent);
}
-.template-free-choice:focus-visible {
+.template-mode-choice:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
}
-.template-free-choice.selected {
+.template-mode-choice.selected {
border-color: var(--accent);
background: var(--accent-soft);
box-shadow: 0 0 0 1px var(--accent);
@@ -638,26 +643,39 @@ textarea.text-input { resize: vertical; line-height: 1.5; }
background: #fff;
box-shadow: inset 0 0 0 3px #fff;
}
-.template-free-choice.selected .template-choice-radio {
+.template-mode-choice.selected .template-choice-radio {
border-color: var(--accent);
background: var(--accent);
}
-.template-free-copy {
+.template-choice-copy {
min-width: 0;
display: flex;
flex-direction: column;
gap: 2px;
}
-.template-free-title {
+.template-choice-title {
font-size: 13.5px;
font-weight: 700;
line-height: 1.4;
}
-.template-free-desc {
+.template-choice-desc {
color: var(--muted);
font-size: 12.5px;
line-height: 1.45;
}
+.template-selector-panel {
+ margin-top: 16px;
+ padding-top: 14px;
+ border-top: 1px solid var(--line);
+}
+.template-selector-panel[hidden] {
+ display: none;
+}
+.template-selector-hint {
+ margin-bottom: 11px;
+ color: var(--muted);
+ font-size: 12.5px;
+}
.template-select-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
@@ -1080,4 +1098,7 @@ textarea.text-input { resize: vertical; line-height: 1.5; }
.style-preview-card {
flex-wrap: wrap;
}
+ .template-mode-choices {
+ grid-template-columns: 1fr;
+ }
}
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index f96653a0..987d2c0c 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -1,21 +1,20 @@
-# Confirm UI — Template Selection and Strategist Confirmation Page
+# Confirm UI — Strategist and Template Confirmation Page
> The interactive surface for [`generate-pptx`](../../workflows/generate-pptx.md)
-> 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.
+> Step 4. Stage 1 shows the template-independent communication recommendation
+> and the template/free-design choice on one page and confirms both with one
+> submission. That submission writes the Strategist contract to `result.json`
+> and the selection sidecar to `template_selection.json`. The agent then installs
+> any selected workspace and writes `template_handoff.json`; only afterward does
+> final Stage 2 read installed template state and confirm the coordinated deck
+> solution plus production mechanics. The chat path mirrors these boundaries
+> without fabricating UI receipts.
## Authority and Scope
| Concern | Owner |
|---|---|
-| Step 3 template-selection gate and installation order | [`generate-pptx.md`](../../workflows/generate-pptx.md) |
+| Stage-1 combined confirmation and post-confirmation installation order | [`generate-pptx.md`](../../workflows/generate-pptx.md) |
| 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 |
@@ -27,7 +26,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 a triggered Step 3 or any UI command**: Resolve the most recent
+**Mandatory surface decision — before 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
@@ -35,24 +34,33 @@ 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 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. |
+| The user explicitly delegates confirmation | Make the combined Stage-1 communication/template decision, install it, then present one complete final summary. 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; Stage 1 includes the template/free-design choice. 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 same
-two-stage Strategist confirmation and, when triggered, the independent template
-choice that precedes it.
+Stage-1 communication/template decision, installation handoff, and template-aware
+final Stage 2.
+
+**Chat/delegated Stage-1 listing**: Author the communication recommendation
+before reading the four indexes, then present that recommendation together with
+an explicit free-design/template-mode choice. Only template mode expands the
+registered candidates and supplied exact roots, and it requires at least one
+selection. Ordinary requests initialize free design; explicit template intent
+or any supplied exact root initializes template mode. Exactly one supplied root
+may also seed that candidate, while multiple roots remain unselected. Under
+explicit delegation, make the same decision, install
+it, and only then derive Stage 2. Do not launch the page or fabricate receipts.
**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 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.
+after launch failure/timeout and one re-check of `result.json` plus the
+Stage-1-sidecar `template_selection.json` when Stage 1 is active. A chat-question
+tool alone is not a launch failure. Preserve the combined Stage-1 decision and
+keep communication prompts open-ended.
**In-run UI → chat switch — any phase or stage**: If the user explicitly selects chat
after the UI server has launched—while `--wait-only` is active, before that wait
@@ -64,68 +72,66 @@ starts, or after it times out while the server remains live:
2. Run `server.py <project_path> --shutdown` and require that cleanup to
succeed. The browser tab may remain open, but its stopped server makes it
inactive.
-3. Re-check the active receipt once: `template_selection.json` during Step 3,
- otherwise `result.json`. Retain only values persisted before shutdown; an
- unsubmitted browser draft is not confirmed.
+3. Re-check the active receipt once. During Stage 1, require both `result.json`
+ and `template_selection.json` from the same submission; during Stage 2, check
+ `result.json`. Retain only values persisted before shutdown; an unsubmitted
+ browser draft is not confirmed.
4. Continue the unresolved current phase/stage and everything remaining in chat. Do
not call `--wait-only` again, recover the server, or relaunch the page during
this run.
-**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
-roots; registered options come only from the four kind indexes; and every
-supplied exact root is shown as a library or explicit candidate according to
-exact canonical-root equality. End
-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 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 two-stage
-flow will continue. Only then run `--wait-only --wait-stage stage1`. A chat
+**Always-on Stage-1 chat handoff**: After writing `template_options.json` and
+template-independent `recommendations.stage1.json`, launch the healthy daemon
+without `--wait`. Immediately post its actual URL plus one compact localized
+summary of the current communication recommendation and template choice state:
+audience, communication intent, audience outcome, core message, delivery
+context, artifact afterlife, `content_divergence`, canvas, and whether the
+default is free design or template mode, including any sole preselected root. Explain
+that template mode expands the registered-kind and supplied-root selectors.
+Show a blank prose value as “not specified” without changing it. End with an
+explicit localized line saying that, if the page did not open, the user may
+confirm or revise the same communication and template choices in chat. 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
nothing. After launch failure/timeout and the required result re-check, present
-the same items as open Stage-1 chat questions and wait for an explicit response.
+the same combined Stage-1 items as open chat questions and wait explicitly.
## `confirm_ui/server.py`
The following launch and wait commands belong to the **UI branch only**:
```bash
-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> --daemon # launch combined Stage 1
+python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1 # communication + template selection
+python3 scripts/confirm_ui/server.py <project_path> --complete-template-selection # after Stage-1 free-design closure / template install
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 # clear prior Step-3 artifacts before a fresh UI run
+python3 scripts/confirm_ui/server.py <project_path> --reset-template-selection # clear prior template sidecars 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. 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`.
+- `--daemon` starts the Flask process in the background and returns after the health check. Every Default UI run launches directly into combined Stage 1 and keeps the same process live through final Stage 2. The wait budget defaults to **590 s** (`--wait-timeout`); on timeout the detached server remains live, and the caller re-checks both Stage-1 receipts 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 `stage1` for the combined communication/template submission and the default/final wait for Stage 2.
+- `--complete-template-selection` is agent-only. It validates the Stage-1 sidecar and writes the bound `template_handoff.json`; template mode additionally requires project-local `templates/design_spec.md`. Run it after installation/free-design closure and before writing Stage 2. `--reset-template-selection` removes exactly `template_options.json`, `template_selection.json`, and `template_handoff.json`; it does not alter Strategist files, installed template content, or `result.json`. The old `--*-template-phase` names are not aliases.
- `--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.
-- 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.
+- Every fresh UI run starts with `--reset-template-selection`, then writes valid `<project_path>/confirm_ui/template_options.json` and a newer `recommendations.stage1.json`; `explicit_workspace_roots` is an empty array when no exact root was supplied. Stage 1 writes the bound selection and communication result together. Stage 2 is exposed only when the matching handoff is newer than that selection and its 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.
+- Stage-1 `GET /api/recommendations` embeds the server-built candidate catalog
+ as top-level `template_options`. Its `/api/confirm` submission validates
+ current candidate keys and writes `template_selection.json` beside the pure
+ Strategist `result.json`; there is no independent template-options endpoint,
+ template-confirm endpoint, or template wait stage. The same APIs later serve
+ Stage 2 and strip legacy `template_reuse_scope` / `template_adherence`
+ fields. The completed template handoff is authoritative: `free_design`
+ strips a stray `template_application`, while `templates` exposes that
+ editable natural-language field in Stage 2.
Dependency:
@@ -133,10 +139,11 @@ Dependency:
pip install flask
```
-## Conditional Step-3 template-selection contract
+## Stage-1 template-selection sidecar contract
-When triggered, template selection is a separate pre-Strategist phase. Its files live under
-`<project_path>/confirm_ui/` but never enter `result.json`.
+Template selection shares the Stage-1 page and submit action but remains a
+separate artifact from the Strategist contract. Its files live under
+`<project_path>/confirm_ui/`; selection keys never enter `result.json`.
### Input — `template_options.json` (created before launch)
@@ -145,6 +152,7 @@ When triggered, template selection is a separate pre-Strategist phase. Its files
"schema_version": 1,
"phase": "template",
"lang": "zh",
+ "default_mode": "free_design",
"explicit_workspace_roots": [
"/absolute/path/to/a/project-or-template-workspace"
]
@@ -153,6 +161,9 @@ When triggered, template selection is a separate pre-Strategist phase. Its files
- `schema_version` is exactly `1`; `phase` is exactly `template`.
- `lang` is optional, but when present it is a non-empty UI-language string.
+- `default_mode` is required and is exactly `free_design` or `templates`.
+ Ordinary requests use `free_design`; explicit template intent or any supplied
+ exact root uses `templates`. It initializes the UI but never locks the user.
- `explicit_workspace_roots` is required even when empty. Every item is a
unique absolute path resolving to an existing directory with
`templates/design_spec.md` or compatible legacy `design_spec.md`.
@@ -166,13 +177,15 @@ When triggered, template selection is a separate pre-Strategist phase. Its files
and validates that it exists with `templates/design_spec.md`. It never scans
kind directories.
-`GET /api/template-options` returns the browser catalog:
+Stage-1 `GET /api/recommendations` embeds this browser catalog as top-level
+`template_options`:
```json
{
"schema_version": 1,
"phase": "template",
"lang": "zh",
+ "default_mode": "free_design",
"library": {
"brand": [],
"style": [],
@@ -190,9 +203,10 @@ A library candidate has `key`, `source: "library"`, `kind`, `id`, `label`,
candidate has `key`, `source: "explicit"`, parsed `kind`, `label`, and
canonical absolute `workspace_root`. If a supplied root exactly equals a registered canonical
root, the server reuses the library candidate/key instead of duplicating it as
-explicit. Candidate keys are server-owned; the page posts only
-`{ "mode": "free_design"|"templates", "selection_keys": [...] }` to
-`POST /api/template-confirm`.
+explicit. Candidate keys are server-owned. The Stage-1 submit payload carries
+the current `{ "mode": "free_design"|"templates", "selection_keys": [...] }`
+beside the Strategist fields; the server validates that selection and writes it
+to the sidecar rather than copying keys into `result.json`.
When the input supplies exactly one root, `preselected_keys` contains its
resolved candidate key as a convenience default, including when exact equality
@@ -200,17 +214,20 @@ reclassifies it as library. When several roots are supplied, all remain
candidates but none is preselected; one specified-root dropdown cannot encode
an instruction to use all of them.
-**Page selection model**: The first control is exclusive free design. Below it,
-Brand, Style, Layout, and Deck each have one registered single-select dropdown,
-and Specified has one explicit-root single-select dropdown. Every dropdown
-starts with `None`. Selecting any template exits free design; selecting free
-design clears all dropdowns. The registered kinds may be combined, but each
-contributes at most one root and the specified channel contributes at most one.
-The server enforces the same limits. Because an explicit candidate carries its
-parsed kind, it may coexist with one registered root of that kind and enter the
-two-workspace same-kind conflict gate. Source provenance never grants priority.
-
-### Output — `template_selection.json` (written on confirmation)
+**Page selection model**: Stage 1 first asks the user to choose `Free design` or
+`Use templates`, initialized from `default_mode` but always switchable. Exactly
+one supplied root may initialize its candidate as an editable convenience
+default; multiple roots remain unselected. Only `Use templates` expands the
+candidate controls: Brand, Style, Layout, and Deck each have one registered
+single-select dropdown, and Specified has one explicit-root single-select
+dropdown. Every dropdown includes `None`; template mode cannot submit until at
+least one is non-empty. Free design clears all dropdowns. Registered kinds may
+be combined, but each contributes at most one root and the specified channel at
+most one. Because an explicit candidate carries its parsed kind, it may coexist
+with one registered root of that kind and enter the two-workspace same-kind
+conflict gate. Source provenance never grants priority.
+
+### Output — `template_selection.json` (written with Stage 1)
```json
{
@@ -250,20 +267,21 @@ input, four index files, and resolved candidates. `selection_sha256` binds the
mode and canonical sorted selections to that option hash. Every receipt read
rebuilds the catalog and rejects option/index drift.
-After `--wait-only --wait-stage template` returns, Generate reads this receipt
-once. Free design skips installation but still completes the agent handoff
-below before Stage 1. Template mode runs `apply-template-workspace` against all
-selected roots, waits for complete project-local installation/fusion, and only
-then completes that handoff. Step 3 resolves only template-to-template segment
-ownership and installation; it does not evaluate current-project fit.
-Strategist never reads the source roots.
+The Stage-1 submission writes this receipt and the Stage-1 `result.json`
+together. Generate reads both exactly once after `--wait-only --wait-stage
+stage1` returns. Free design skips installation. Template mode runs
+`apply-template-workspace` against all selected roots and waits for complete
+project-local installation/fusion. Only then does the agent complete the
+handoff below. Installation resolves template-to-template ownership; Stage 2
+later evaluates current-project fit from the installed copy. Strategist never
+reads the source roots.
### Agent handoff — `template_handoff.json`
After free design closes or template installation succeeds, run:
```bash
-python3 scripts/confirm_ui/server.py <project_path> --complete-template-phase
+python3 scripts/confirm_ui/server.py <project_path> --complete-template-selection
```
The command writes, and agents must not hand-author:
@@ -281,12 +299,12 @@ The command writes, and agents must not hand-author:
The handoff must match the current valid selection. Template mode also requires
`<project_path>/templates/design_spec.md`; free design requires no installed
-spec. Write `recommendations.stage1.json` only after this command succeeds, so
-its file time is no earlier than the handoff.
+spec. Write `recommendations.stage2.json` only after this command succeeds, so
+its file time is newer than the handoff.
## Field shapes
-The following fields belong to the Strategist stages, not to any triggered
+The following fields belong to the Strategist stages, not to the
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.
@@ -309,77 +327,77 @@ 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/`. 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.
+In the UI branch, round-trip and session files live under
+`<project_path>/confirm_ui/`. `template_options.json` is prepared beside the
+Stage-1 recommendation. The Stage-1 submit writes `result.json` and
+`template_selection.json` together; after installation/free-design closure,
+`template_handoff.json` unlocks Stage 2. The chat/delegated branch preserves the
+same logical order without fabricating these UI receipts.
### Current two-stage flow
-The page runs a **two-stage Strategist wizard in one browser session**, directly
-for ordinary free design or after triggered template installation. Each stage
+The page runs a **two-stage Strategist wizard in one browser session**. Stage 1
+contains the communication contract and template/free-design controls. 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 a separate prerequisite only
-when template options exist.
+from `result.json`; the bound template handoff is the prerequisite for Stage 2.
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.
+current Stage-1/Stage-2 files. If a project starts UI confirmation again, run
+`--reset-template-selection`, write fresh `template_options.json`, then author a
+fresh `recommendations.stage1.json`. Those two inputs start the new UI
+lifecycle; neither a standalone newer Stage-1 file nor a standalone option file
+does so.
+The completed result cannot be reopened or overwritten, and a standalone newer
+Stage-1 file cannot start its replacement. After Stage 1 writes both receipts,
+the agent completes a newer bound handoff; `recommendations.stage2.json` must be
+newer than that handoff and the Stage-1 result. 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 paired inputs start a new 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.stage1.json` + `template_options.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; free-design/template mode and conditional candidate selectors | **Confirm contract & template choice** | writes Stage-1 `result.json` plus `template_selection.json` in one submission; the page stays open and polls while the agent installs/completes the handoff |
| `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 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
-when present and authors the complete final Stage-2 solution plus production
-mechanics once from the user's actual communication contract. An edit inside
+In the UI branch, the AI authors Stage 1 without reading template candidates,
+then launches the combined page. In chat/delegated confirmation it authors the
+same communication recommendation before listing template candidates. After
+the one Stage-1 confirmation, the AI installs any selection, completes the
+handoff/equivalent state, then inspects only the project-local template 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`
+earlier answers across transitions. `GET /api/session` reports `phase:
+"strategist"` with current Stage 1 from launch; after Stage-1 submission it
+reports `waiting_agent` until the bound handoff and fresh Stage-2 file exist.
+`GET /api/recommendations`
is `no-store`, and the server folds confirmed earlier-stage choices back into
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
-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.
+**Progression guard.** Stage 1 requires current `template_options.json` and a
+fresh `recommendations.stage1.json`; it does not require a prior selection or
+handoff. Its one submit must persist a valid Stage-1 result and selection bound
+to those options. Stage 2 requires a newer `template_handoff.json` bound to that
+selection and a fresh Stage-2 recommendation. This ordering prevents receipts
+from an earlier one-run UI from satisfying a new run. Strategist confirms Stage
+1 → installation/free-design handoff → 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 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)
+### Input — `recommendations.stage1.json` (created beside template options)
-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.
+Author this file before reading candidate index summaries in chat and without
+reading any template spec, prototype, asset, fused segment owner, or template
+canvas. `template_options.json` supplies display state only and never changes
+the communication recommendation.
```json
{
@@ -561,7 +579,7 @@ Template-mode-only Stage-2 fragment:
The shape above is final for Strategist confirmation. It intentionally contains
no template-selection field: `template_selection.json`, its agent handoff, and
-the installed project-local state own that earlier decision. The proactive-execution values
+the installed project-local state own the parallel Stage-1 decision. The proactive-execution values
are independent flat booleans in `result.json`; old recommendations and results
that omit them resolve to `true / false / false`. They remain raw evidence even
when `proactive_speaker_notes` is `false` and `proactive_narration_audio` is
@@ -578,7 +596,7 @@ The Stage-1 intermediate write retains the communication contract for Stage 2.
- 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.
-- 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.
+- Stage-1 **Confirm contract & template choice** writes the Stage-1 `result.json` and `template_selection.json` together, then keeps the page open while the agent installs the selection. The agent runs `--complete-template-selection`, writes fresh Stage 2 only after that handoff, and the page keeps polling. 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 decisions without UI artifacts. 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/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 7787e38c..065b1ebb 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -318,7 +318,7 @@
"max_tokens": 86000
},
"stage.generate.apply-template-workspace": {
- "description": "Conditional Default Step 3 or Quick exact-root workspace validation, installation, and fusion framework.",
+ "description": "Post-Stage-1 Default or Quick exact-root workspace validation, installation, and fusion framework.",
"scope": "incremental",
"files": [
"skills/ppt-master/workflows/stages/apply-template-workspace.md",
diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.md
index 94f45bde..b1e130a2 100644
--- a/skills/ppt-master/templates/README.md
+++ b/skills/ppt-master/templates/README.md
@@ -39,18 +39,21 @@ 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 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,
+The four indexes are the complete library-discovery source for Default
+[`generate-pptx`](../workflows/generate-pptx.md) Stage-1 template selection.
+Step 3 prepares candidate input without interaction or reading template
+content. The Stage-1 page confirms the communication contract together with an
+explicit free-design/template choice; only template mode expands these indexes.
+Exact roots supplied for the run or handed off by Create Template appear as
+specified candidates. Ordinary requests default to free design; explicit
+template intent or any supplied root defaults to template mode. Exactly one root
+may be preselected, while multiple roots remain unselected candidates. The user
+can always switch modes. The page accepts one registered choice per kind plus
+one supplied-root choice. A registered exact root is `library`; any other exact
+root is `explicit`. After that combined 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 final Stage 2 from
+project before Stage 2 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.
@@ -59,7 +62,7 @@ otherwise uses free design.
| 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` | Conditional Step-3 discovery provenance only: exact index-derived root or exact unregistered root; it does not change template semantics |
+| Selection source | `library` / `explicit` | 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,8 +92,8 @@ 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 an explicitly triggered Default Step-3 selection phase or
-the Quick exact-root branch. Brand/Layout/Deck consume package-owned
+stage owns installation and fusion after a non-free Default Stage-1 selection or
+on 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
ignores `exports/`. Compatible legacy-flat Brand/Layout/Deck packages remain
diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.md
index dc1a216b..d6c538a5 100644
--- a/skills/ppt-master/templates/brands/README.md
+++ b/skills/ppt-master/templates/brands/README.md
@@ -10,17 +10,16 @@ lives in the parent [`README.md`](../README.md).
## How brands are consumed
-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
+Brand application follows the parent README's Default Stage-1
+[`generate-pptx`](../../workflows/generate-pptx.md) template-choice contract.
+Its Brand choices come only from `brands_index.json`; no
+directory scan or bare-name match is allowed. A supplied exact root appears in
+the same selector, defaults Stage 1 to template mode, and preselects that
+specific candidate only when it is the sole supplied root.
+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
+same-kind conflict resolution, and provenance after Stage 1 and before Stage 2. Template-aware
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.
@@ -58,9 +57,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 explicitly triggered Step-3 page reads this index as its complete
+The Default Stage-1 template controls read this index as their 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
+workspace roots. Choosing an entry and submitting Stage 1 runs 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 df9c3c63..cb53a27d 100644
--- a/skills/ppt-master/templates/decks/README.md
+++ b/skills/ppt-master/templates/decks/README.md
@@ -29,19 +29,19 @@ Overview when application fit must be judged in detail.
---
-## Trigger and fusion
-
-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
+## Selection and fusion
+
+Selection follows the parent README's Default Stage-1
+[`generate-pptx`](../../workflows/generate-pptx.md) template-choice contract.
+Its Deck choices come only from `decks_index.json`; no
+directory scan or bare-ID/style-phrase match is allowed. A supplied exact root
+appears in the same selector, defaults Stage 1 to template mode, and preselects
+that specific candidate only when it is the sole supplied root. Registered
+exact roots are `library`; other exact roots remain
+`explicit`. Choosing and confirming an entry runs 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 final Stage 2 from the
+fusion after Stage 1 and before Stage 2. Template-aware reading begins in final Stage 2 from the
installed project-local copy.
Quick applies a supplied exact Deck root directly and otherwise uses free
design. It uses installed prototypes as flat authoring inputs; reusable
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index 45aba3bb..0a08ceec 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -44,19 +44,19 @@ kind of rule is never a mirror operation.
---
-## Trigger and identity boundary
-
-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
+## Selection and identity boundary
+
+Selection follows the parent README's Default Stage-1
+[`generate-pptx`](../../workflows/generate-pptx.md) template-choice contract.
+Its Layout choices come only from `layouts_index.json`; no
+directory scan or bare-ID/style-phrase match is allowed. A supplied exact root
+appears in the same selector, defaults Stage 1 to template mode, and preselects
+that specific candidate only when it is the sole supplied root. Registered
+exact roots are `library`; other exact roots remain `explicit`.
+Choosing and confirming an entry runs 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 final Stage 2 from the
+fusion after Stage 1 and before Stage 2. Template-aware reading begins in final Stage 2 from the
installed project-local copy.
Quick applies a supplied exact Layout root directly and otherwise uses free
design. It uses installed prototypes as flat authoring inputs; reusable
diff --git a/skills/ppt-master/templates/styles/README.md b/skills/ppt-master/templates/styles/README.md
index e37fa054..06d92eba 100644
--- a/skills/ppt-master/templates/styles/README.md
+++ b/skills/ppt-master/templates/styles/README.md
@@ -15,16 +15,17 @@ Style is a fourth independent template kind alongside [`brands/`](../brands/), [
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 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
+## Selection, Precedence, and Fusion
+
+Selection follows the parent README's Default Stage-1
+[`generate-pptx`](../../workflows/generate-pptx.md) template-choice contract.
+Its Style choices come only from `styles_index.json`; no
+directory scan or bare-name match is allowed. A supplied exact root appears in
+the same selector, defaults Stage 1 to template mode, and preselects that
+specific candidate only when it is the sole supplied root. A
+consulting label or visual description remains a brief and does not activate
+this workspace. A non-free confirmation runs the
+common installation/fusion stage after Stage 1 and before Stage 2; template-aware reading begins
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.
@@ -92,7 +93,8 @@ 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 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;
+the full method or defaults. The Default Stage-1 template controls read this
+file as their complete registered-Style catalog, and chat discovery returns
+exact roots from the same entries. Choosing an entry and submitting Stage 1
+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 dcce5ade..8f25dee6 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -16,7 +16,7 @@ Create one reusable template workspace under either the **global template librar
**Hard rule — one workspace routing contract**: Output scope changes only the workspace parent and index registration. Both scopes use required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/`, with the same relative asset references and validation command. Create Template must not create an optional directory or placeholder file solely to retain an empty path. An initialized project may already contain empty `images/`, `icons/`, or `exports/` scaffolding; leave it untouched, do not count it as template output, and omit the path from completion unless this workflow wrote or adopted a real file there. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.
-> **Boundary against template-fill and in-place structure edits**: Create Template does not fill content into a PPTX, add Master/Layout structure to an existing PPTX/SVG, or directly output the user's final generated deck. It authors a separate reusable workspace; an optional PPTX is review evidence only. To generate a deck, return the workspace root to [`generate-pptx`](./generate-pptx.md) Step 3 and author new SVG pages from it. A project-scoped workspace is already installed at that project's Step 3 path and is consumed in place.
+> **Boundary against template-fill and in-place structure edits**: Create Template does not fill content into a PPTX, add Master/Layout structure to an existing PPTX/SVG, or directly output the user's final generated deck. It authors a separate reusable workspace; an optional PPTX is review evidence only. To generate a deck, return the workspace root as an exact candidate to [`generate-pptx`](./generate-pptx.md) Step 3, confirm it with Stage 1, then author new SVG pages from the installed state. A project-scoped workspace selected for its own project is consumed in place after that confirmation.
## Child Workflow Dispatch
@@ -836,18 +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
-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
+Default [`generate-pptx`](./generate-pptx.md#step-3-template-candidate-preparation)
+Stage-1 template controls. Step 3 prepares their candidate input without
+interaction; the controls read only the four kind indexes, while 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.
+template directories. Selecting a registered entry and submitting Stage 1
+activates installation. An exact unregistered workspace supplied by the user,
+or the exact validated root handed off by this route in the current
+conversation, appears as a specified candidate and is preselected when it is
+the only supplied root; it remains labelled `explicit` and does not enter 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 or used to preselect a template.
> **Recommended for new templates**: declare a YAML frontmatter block at the top of `design_spec.md`. The registrar prefers it over prose extraction:
>
@@ -912,8 +912,8 @@ root exactly matches a registered canonical root, it may be displayed as
> ```
README files describe each kind in prose only — they do not list templates.
-The explicitly triggered Step-3 selector and chat discovery read the JSON index
-files; the registrar does not touch READMEs.
+The Default Stage-1 template controls and chat discovery read the JSON index files; the
+registrar does not touch READMEs.
---
@@ -953,7 +953,20 @@ 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 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.
+The exact `<template_workspace>/` root in either scope is the
+current-conversation handoff to Default Generate Step 3. It appears as the
+specified candidate, defaults Stage 1 to template mode, and is preselected only
+when it is the sole supplied root. After Stage 1 confirms it, the application
+stage 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.
---
@@ -974,7 +987,7 @@ The exact `<template_workspace>/` root in either scope is the current-conversati
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 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.
+5. **Discovery requirement**: A library template appears in the Default Stage-1 template 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 candidate. Step 3 only prepares candidates; Stage 1 confirms communication plus free design/template use together, and only a non-free confirmed selection installs a workspace before Stage 2.
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 5185efb1..d281aa3e 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 Candidate Preparation → Stage-1 Communication + Template Confirmation → [Template Installation] → Stage-2 Solution → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export`
**Generate-specific execution discipline**:
@@ -25,7 +25,7 @@ hand-authors SVG, runs one lockless final checker, and exports the final PPTX.
It skips Strategist, Confirm UI, Design Spec/lock, the first-page gate, and
`finalize_svg.py`.
-Quick never enters Step 3. When the request supplies at most one exact current
+Quick never enters Steps 3–4. When the request supplies at most one exact current
workspace root for each Brand/Style/Layout/Deck kind, or the current
conversation carries an exact Create Template handoff, Quick runs
[`apply-template-workspace`](./stages/apply-template-workspace.md) directly and
@@ -62,7 +62,7 @@ pipeline; Quick applies templates while authoring complete flat pages.
| Artifact ownership | [`artifact-ownership.md`](../references/artifact-ownership.md) | Owns fact channels, source/derived artifact boundaries, and regeneration rules |
| Failure recovery | [`failure-recovery.md`](./governance/failure-recovery.md) | Owns stop/continue policy and resume pointers |
| Confirm UI details | [`confirm_ui.md`](../scripts/docs/confirm_ui.md) | Owns the JSON schema, launcher behavior, staged-result contract, port strategy, and chat fallback details |
-| Step-3 template selection | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) | Owns validation, installation, and fusion after the user confirms library or explicit workspace roots; skip only for confirmed free design |
+| Confirmed template application | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) | Owns validation, installation, and fusion after Stage 1 confirms library or explicit workspace roots; skip for confirmed free design |
## Workflow
@@ -153,85 +153,74 @@ Direct supported bitmap inputs follow both boundaries: the original is archived
---
-### Step 3: Conditional Template Discovery, Selection, and Installation
+### Step 3: Template Candidate Preparation
-**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.
+**Scope**: Every Default Generate run. This is internal preparation only: do not
+open a page, ask a question, wait for a receipt, select a workspace, read a
+template spec/prototype, or install anything. Quick resolves exact supplied
+roots or free design inside its profile and skips this Step.
-**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.
-
-🚧 **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:
+Prepare the candidate boundary that Stage 1 will confirm. Registered candidates
+come from exactly these discovery sources:
- `templates/brands/brands_index.json`
- `templates/styles/styles_index.json`
- `templates/layouts/layouts_index.json`
- `templates/decks/decks_index.json`
-Derive each library root as `templates/<kind_dir>/<id>/` from its index entry. Never scan kind directories, infer unregistered entries, or resolve a bare name, brand mention, or style phrase to a path. The registered dropdowns may be combined across kinds, with at most one choice from each. The specified dropdown offers the exact roots supplied for this run and allows at most one choice. The server parses that workspace's declared `kind`; the specified choice may therefore coexist with one registered choice of the same kind and enter the existing two-workspace conflict gate. A path the user explicitly supplied remains an `explicit` selection unless its normalized root exactly equals an entry derived from the matching index, in which case the UI may present it as `library`. This source label records discovery provenance only; it never changes segment ownership, fusion precedence, validation, or installation behavior.
+Derive each library root as `templates/<kind_dir>/<id>/` from its index entry.
+Never scan kind directories, infer unregistered entries, or resolve a bare name,
+brand mention, or style phrase to a path. Preserve every exact root supplied for
+this run. A registered-root equality match remains `library`; every other exact
+root remains `explicit`. Candidate provenance never changes later validation,
+fusion, or precedence.
-**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, first clear only the prior one-run template receipts
-(the command is idempotent), then write
+Resolve the confirmation surface under
+[`confirm_ui.md`](../scripts/docs/confirm_ui.md). In the UI branch, run
+`--reset-template-selection`, 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
-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
-```
-
-After the wait, read `confirm_ui/template_selection.json` exactly once and
-require `schema_version: 1`, `phase: "template"`, and `status: "confirmed"`.
-`mode: "free_design"` carries no selections; `mode: "templates"` carries the
-server-resolved exact roots with `source: "library"|"explicit"` and declared
-`kind`. It contains at most one library selection per kind plus at most one
-explicit selection. Keep
-the server live while applying selected workspaces and preparing Stage 1; the
-same page polls for `recommendations.stage1.json`. On a non-zero wait, re-check
-the receipt once, then follow `confirm_ui.md`'s chat fallback/switch contract.
-
-⛔ **BLOCKING — template selection**: Wait for the user to confirm free design or the selected roots. Do not expose Stage 1 before this choice closes.
-
-**Selected workspace path**: For every non-free selection, load and run [`apply-template-workspace.md`](./stages/apply-template-workspace.md) against the exact roots in the confirmed receipt (or their chat-equivalent selection). It validates all roots, resolves template-to-template segment ownership/collisions, and installs one project-local template state under `<project_path>/templates/` plus any real `<project_path>/images/` and `<project_path>/icons/` assets. It does not judge current-project fit or derive any Stage-1 field. Do not proceed until installation completes. Template-aware Strategist work from Stage 2 onward and later roles read only this installed project-local state, never the library or external source root.
-
-**UI handoff**: After free design closes, or after every selected workspace is
-installed, bind that completed state to the current selection before authoring
-Stage 1:
-
-```bash
-python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --complete-template-phase
-```
-
-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 requires Stage 1 to be authored after that handoff. Do
-not write the handoff manually.
-
-**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 — 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.
+`phase: "template"`, the UI language, and all supplied exact roots as absolute
+`explicit_workspace_roots`; use an empty array when none were supplied. Also
+write required `default_mode`: `templates` when the user explicitly asks to use
+or browse templates or supplies any exact root, otherwise `free_design`. The
+server reads the four indexes itself. Do not launch it yet. In chat/delegated
+confirmation, retain the same candidate boundary in context and create no UI
+artifact.
+
+Stage 1 initializes from `default_mode`, but the user can switch modes. Template
+mode alone expands the candidates and must eventually select at least one
+workspace. Exactly one supplied root may be preselected as an editable default;
+multiple supplied roots remain unselected candidates. `free_design` selects none.
+
+**Raw PPTX boundary**: A raw PPTX remains valid source material, but it is not a
+template workspace candidate. 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**: Candidate input is ready for the combined Stage-1
+confirmation. No template has been selected, read, validated, fused, or
+installed. Proceed to Step 4 without a user-visible stop.
---
### Step 4: Strategist Phase (MANDATORY in the default pipeline)
-🚧 **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.
+🚧 **GATE**: Source preparation and Step-3 candidate preparation are
+complete. No template content has entered planning context and no template has
+been installed. Stage 1 has not started before this point.
+
+**Hard rule — Stage 1 is template-independent**: Author every Stage-1
+communication recommendation from the user's current request, source facts,
+conversation constraints, and project-initialization state only. Candidate
+paths, index summaries, template specs/prototypes/assets, and template canvas
+are not recommendation evidence. Author the communication proposal before any
+chat-branch catalog listing. 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 confirms
+both the communication contract and template/free-design choice and any selected
+workspace has been installed.
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,
@@ -249,7 +238,7 @@ 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 |
+| Stage 1 is confirmed and its template choice installed a selected Brand/Style/Layout/Deck workspace into this project | `references/strategist-template.md` before Stage 2 |
| The core's proposed Stage 2 `image_usage` contains a source other than `none`, the user supplied an explicit non-`none` image constraint, or formula-worthy content activates formula planning | `references/strategist-image.md` + `references/image-layout-spec.md` + `references/image-layout-patterns.md` before authoring image renderings, production detail, formula resources, or §VIII |
Core chooses Stage-2 sources. Load it before Stage 2 for non-`none`, or after confirmation if `none` changes; do not backfill candidates. Retain for confirmed non-`none` or formulas; otherwise write no image rows. Only an installed project-local template state loads the template module, and only after Stage 1 is confirmed; a bare template/style name does not.
@@ -264,62 +253,73 @@ 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**: 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 a
-triggered Step-3 template phase or any confirmation server command, apply
+⛔ **BLOCKING**: The two-stage Strategist confirmation is the always-on user
+gate unless explicitly delegated. Stage 1 confirms the communication contract
+and, on the same screen or in the same chat turn, exactly one template mode:
+`free_design` or `templates`. Only `templates` expands the four registered-kind
+selectors plus supplied exact-root candidates, and it requires at least one
+selection. Final Stage 2 confirms the complete deck solution plus production
+mechanics only after the Stage-1 choice is installed or its free-design handoff
+is complete. An enabled `refine_spec` adds the one conditional chat gate after
+Design Spec Gate 1. Author each stage once; submitted values—including blanks or
+unusual overrides—are authoritative.
+
+**Confirmation ownership and surface**: Only the user confirms. Before 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, 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
+instruction, use the default UI branch. 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.
+result state. Delegation applies only to this run: make the Stage-1 communication
+and template decision, install any selection, then derive and show the complete
+Stage-2 summary without fabricating 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` *(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/template_options.json` | Candidate schema/language plus supplied exact roots; library entries remain server-owned index data | Stage-1 submission writes user-owned `template_selection.json` with `phase: template`, `status: confirmed` |
+| `confirm_ui/recommendations.stage1.json` | Communication contract, `content_divergence`, and canvas only; no template-derived recommendation | The same submission writes `result.json` with `status: stage1-confirmed` |
+| `confirm_ui/template_handoff.json` | Only through `--complete-template-selection`, after the Stage-1 selection and free-design closure or successful installation | `status: ready`, bound to the current selection hash; prerequisite for Stage 2 |
| `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** — 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:
-
-```bash
-python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --reset-template-phase
-```
-
-Then create `confirm_ui/recommendations.stage1.json`. The triggered path is
-already live; the ordinary path now launches directly from Stage 1:
+**UI branch only** — Step 3 wrote `template_options.json` but did not launch or
+wait. Create `confirm_ui/recommendations.stage1.json` without reading template
+candidate content, then launch the combined Stage-1 page and post
+`confirm_ui.md`'s required communication + template-choice summary/fallback:
```bash
-# Ordinary free-design path only; triggered Step 3 keeps its existing server.
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon
+python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1
```
-Post `confirm_ui.md`'s actual URL plus the required Stage-1 summary and chat
-fallback, then:
+The single Stage-1 submission writes both `result.json` and
+`template_selection.json`; neither replaces the other. Read each exactly once.
+Require a confirmed communication result and either `free_design` with no roots
+or `templates` with at least one server-resolved root.
-1. Run in order:
+1. For `templates`, load and run
+ [`apply-template-workspace.md`](./stages/apply-template-workspace.md) against
+ every confirmed exact root. It validates/fuses them and installs one
+ project-local state under `templates/` plus any real `images/` and `icons/`.
+ For `free_design`, skip installation. Then bind the completed state:
```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1
+ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --complete-template-selection
```
-2. Read Stage 1. Only now inspect the installed template state and apply
+ This agent-only command writes `template_handoff.json`; do not hand-author
+ it. The server requires this handoff before Stage 2.
+
+2. Only now inspect 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;
@@ -348,13 +348,19 @@ 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 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 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.
+**Chat branch** — present the template mode and Stage-1 communication contract
+together and wait for one explicit response. Show registered candidates only
+when the user chooses `templates`; supplied exact roots remain available in that
+expanded choice. Initialize free design for an ordinary request and template
+mode for explicit template intent or any exact root; with exactly one root it
+may also be the preselected candidate, while multiple roots remain unselected.
+Do not create UI receipts
+or call `--complete-template-selection`. After confirmation, install/fuse any
+selected roots (or close free design) and retain that completed state in context
+as the Stage-2 gate. Then run final Stage 2 in chat and retain one visible
+cumulative summary as the equivalent final state. Under explicit delegation,
+make the same Stage-1 decision, install it, derive Stage 2, and present one
+complete AI-authored summary.
⛔ **GATE — final state → Design Spec → conditional review → lock.** Consume every present final value once into the complete, audited `design_spec.md` under [`strategist.md`](../references/strategist.md) §6.2. Preserve each owning semantic type and all production, typography, image-source, and `image_notes` obligations; acceptance never turns a Reference/Permission into a Literal. Do not reopen `result.json`.
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
index ed10adc3..a4d91b7a 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) | Conditional 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) | Non-free Default Stage-1 selection after confirmation, 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/routing.md b/skills/ppt-master/workflows/routing.md
index 09ae0db9..300064c1 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -45,9 +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 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 |
+| Default Generate reaches planning | Step 3 prepares template candidates without interaction. Stage 1 then confirms the communication contract and free-design/template choice together; only a confirmed non-free choice runs [`apply-template-workspace`](./stages/apply-template-workspace.md) before Stage 2 |
+| Explicit current brand/style/layout/deck workspace root | Default Generate preserves the exact path as a Stage-1 template candidate; Quick Generate validates and installs it directly without Steps 3–4 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 |
| User explicitly requests spec refinement | Run [`refine-spec`](./stages/refine-spec.md) after Design Spec Gate 1 and before lock Gate 2 |
@@ -75,7 +74,7 @@ still requires the default lock-backed Generate pipeline.
**Hard rule — no direct structure grafting**: An existing PPTX or SVG is never upgraded in place by adding Master/Layout/placeholder structure. If reusable native structure is required:
1. Run [`create-template`](./create-template.md) to produce a separate validated workspace.
-2. Pass that workspace root to [`generate-pptx`](./generate-pptx.md) Step 3.
+2. Pass that workspace root to [`generate-pptx`](./generate-pptx.md) as a Stage-1 template candidate.
3. Author new structured SVG pages whose Master/Layout contract exists from their first generated draft.
4. Export a new PPTX from those pages.
@@ -87,7 +86,7 @@ When a PPTX already contains native Master/Layout parts, `create-template` mirro
|---|---|
| Raw PPTX called a template + new content | Fill Native PPTX unless the user explicitly asks for a reusable template workspace |
| Any supported reference bundle or direct-text brief + reusable template request | Create Template |
-| Current template workspace root + content | [`generate-pptx`](./generate-pptx.md) Step 3 |
+| Current template workspace root + content | [`generate-pptx`](./generate-pptx.md) Stage-1 template choice |
| Legacy-flat Brand/Layout/Deck root satisfying its current kind contract; Layout/Deck also require current structured SVGs | [`apply-template-workspace`](./stages/apply-template-workspace.md) compatibility reader; Style has no flat form |
| Semantic-legacy or incomplete structured package | Create a new workspace through Create Template; do not migrate in place |
| Request to add a master directly to an existing PPTX/SVG | Unsupported; explain the Create Template → Generate PPTX lifecycle |
@@ -130,11 +129,12 @@ Object animation for generated SVG projects uses the animation stage. Native PPT
| User input | Behavior |
|---|---|
-| 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 |
+| Default Generate | Step 3 prepares candidates only; Stage 1 confirms one communication contract plus either free design or template use in the same interaction |
+| Explicit current workspace root containing `templates/design_spec.md` | Preserve it as a Stage-1 candidate and initialize template mode; preselect that specific candidate only when it is the sole supplied root. An exact registered-root match may be displayed as `library` |
+| No exact workspace root and no explicit template intent | Initialize Stage 1 to free design; the user may switch to template mode and select an indexed workspace |
+| Explicit template intent or any exact workspace root | Initialize Stage 1 to template mode; exactly one root may be preselected, while multiple roots remain unselected candidates |
+| Bare template/brand name or style label without an explicit template-use request | Do not resolve it to a local path or preselect a template; treat it as a style brief. An explicit request to use templates still initializes template mode, but leaves the specific candidate for the user to choose |
+| “What templates exist?” in chat | List indexed workspace paths; Stage 1 still requires an explicit free-design/template choice |
The default UI and chat discovery read only these indexes. Never scan the
corresponding directories to construct or supplement the catalog:
@@ -146,12 +146,12 @@ 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 — 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.
+**Hard rule — one Stage-1 confirmation, delayed template reading**: Author the
+communication recommendation without reading candidate workspaces. Stage 1
+confirms that contract and the template/free-design choice together. Only then
+validate/install selected roots and complete the handoff. Stage 2 waits for that
+handoff, reads only the installed project-local state, and decides how to apply
+it; it never reselects a template.
**Forbidden — fuzzy resolution**: Never resolve a bare name to a local template
directory on the user's behalf. A library choice comes from an index-derived
diff --git a/skills/ppt-master/workflows/stages/apply-template-workspace.md b/skills/ppt-master/workflows/stages/apply-template-workspace.md
index 875c8b89..11be3ec8 100644
--- a/skills/ppt-master/workflows/stages/apply-template-workspace.md
+++ b/skills/ppt-master/workflows/stages/apply-template-workspace.md
@@ -4,12 +4,12 @@ description: Generate-PPTX runbook for validating, installing, or fusing selecte
# Apply Template Workspace Stage
-> 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.
+> Run from [`generate-pptx.md`](../generate-pptx.md) Step 4 only after Stage 1 confirms at least one exact template workspace. [`quick-generate`](../profiles/quick-generate.md) enters only for exact roots or a current Create Template handoff. Never load for free design, bare names, or style descriptions. This stage applies the completed Stage-1 selection; it never chooses a workspace or changes the communication contract.
## 1. Gate and Normalize Inputs
-🚧 **GATE**: Either Default Step 3 was explicitly triggered and its template
-selection is confirmed, or Quick received exact roots directly from the
+🚧 **GATE**: Either Default Stage 1 confirmed a non-free template selection, 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
@@ -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**: 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.
+**Selection cardinality**: Default Stage 1 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; its validated workspace-root handoff triggers Step 3. 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 template 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 becomes a Stage-1 candidate and is preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
**Compatibility gate**: Reject semantic-legacy or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved. A legacy-flat 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`.
@@ -112,7 +112,7 @@ SVGs and never writes `page_layouts` or Master/Layout/placeholder metadata.
## 5. Fuse Multiple Workspace Paths
-Fuse different kinds or, in Default only, at most two same-kind roots. Resolve template segment/asset conflicts before writing. Never read, predict, or revise Stage 1 here. Default obtains required conflict decisions through its active confirmation surface. Quick follows explicit conflict instructions; an unresolved material compatibility conflict is a hard prerequisite handled in chat, never by launching Confirm UI or by using path order.
+Fuse different kinds or, in Default only, at most two same-kind roots. Resolve template segment/asset conflicts before writing. Never reinterpret, predict, or revise the confirmed Stage-1 communication contract here. Default obtains any additional material conflict decision through the active chat channel after Stage 1; this conditional resolution does not reopen template selection. Quick follows explicit conflict instructions; an unresolved material compatibility conflict is a hard prerequisite handled in chat, never by launching Confirm UI or by using path order.
### 5.1 Different Kinds
@@ -127,11 +127,11 @@ Resolve four whole template segments. This table selects the installed starting
Replace each selected segment wholesale; do not mix its fields implicitly. Brand or Deck identity replaces any identity-adjacent defaults carried by Style. A Style direction may adapt to that resolved identity, but cannot relabel its candidates as official brand facts.
-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 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 resolves only this template-to-template conflict and must not reinterpret the confirmed Stage-1 communication contract; 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 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.
+Field-level micro-adjustments such as a primary-color override are not workspace fusion. Default carries them into the normal final Stage-2 confirmation fields; Quick treats explicit adjustments as direct transient authoring constraints.
### 5.2 Same Kind
@@ -160,4 +160,4 @@ Single-path installs do not add provenance. Set fused frontmatter `kind` from th
- [x] Every kind schema passed preflight; structured SVG checks ran only for Layout/Deck inputs
- [x] All collisions and fusion conflicts were resolved before one atomic install
- [x] `<project_path>/templates/` and any portable sibling assets are complete and are the only downstream template source
-- [ ] **Next**: Default returns to [`generate-pptx.md`](../generate-pptx.md) Step 4; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2
+- [ ] **Next**: Default completes the template-selection handoff and continues [`generate-pptx.md`](../generate-pptx.md) Step 4 Stage 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2