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

docs(template): make indexed selection the Generate Step 3 gate

hugohe354f61219bf7a
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 705560a9..5388e4bd 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -59,8 +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 / Brand / Style / Layout (optional)] — default: skip, proceed with free design
- Trigger only on an explicit current-contract Brand/Style/Layout/Deck workspace-root path: either a global-library entry root or a project workspace root
+[Template Selection & Installation (Step 3)] — default UI choice before Stage 1
+ Choose free design, indexed Brand/Style/Layout/Deck library entries, or exact explicit workspace roots; indexes are the complete library source and directories are never scanned
+ Confirmed workspaces are validated/fused into project-local templates/images/icons before Strategist starts
Raw PPTX template requests route to template-fill; reusable SVG templates are created by create-template first
↓
[Strategist] - three-stage Strategist confirmation stage & Design Specifications → design_spec.md + spec_lock.md
@@ -166,7 +167,7 @@ Use this table before reasoning about implementation details. Most failed runs s
| Existing PPTX, preserve page count/order/wording 1:1, improve layout | Generate PPTX + `beautify-pptx` profile | regenerate through SVG; content and pagination are locked |
| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Enhance Native PPTX (`native-enhance-pptx`) | direct OOXML patch; no design regeneration |
| User wants a reusable template workspace from one or more PPTX/SVG files, images/PDFs, documents/websites, brand assets, direct text, or a mixed reference bundle | Create Template (`create-template`) | the fixed entry reads every applicable evidence channel, dispatches one Create Brand, Create Style, Create Layout, or Create Deck child workflow, then returns a workspace root for Generate Step 3; structured children may export a review PPTX |
-| User supplies an explicit current-contract template path | Generate PPTX Step 3 | Current Brand/Style/Layout/Deck workspaces resolve `templates/design_spec.md`; only compatible legacy-flat Brand/Layout/Deck roots may resolve direct `design_spec.md`; semantic-legacy packages are rejected and replaced through Create Template |
+| User selects an indexed library template or supplies an exact current-contract workspace root | Generate PPTX Step 3 | The independent pre-Stage-1 phase confirms free design or exact Brand/Style/Layout/Deck roots, then validates/fuses selected workspaces into the project; only compatible legacy-flat Brand/Layout/Deck roots may resolve direct `design_spec.md` |
| 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 |
@@ -363,11 +364,27 @@ The architectural choice worth flagging: **viewBox is in pixels, not absolute un
## Template System & Optional Path
-Templates are **opt-in, not default**. The default Strategist flow is free design — AI invents the visual system from the source content alone. The template path activates only on an explicit directory path supplied by the user.
+Templates are **opt-in, not inferred**. Before Strategist Stage 1, the default UI
+opens an independent Step-3 choice: free design, registered library workspaces,
+or exact explicit roots supplied for the run. Free design remains the
+content-derived path; 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.
-**Mechanical trigger, not semantic matching.** A bare name like `presentation_core`, a brand mention, or a style phrase such as "McKinsey style" does not trigger Step 3 even if a matching library directory exists. Step 3 consumes an explicit path. Current Brand/Style/Layout/Deck workspaces resolve `templates/design_spec.md`; compatible flat Brand/Layout/Deck packages may resolve direct `design_spec.md` only when they satisfy the current kind contract, including current structured SVGs for Layout/Deck. Style has no legacy-flat form. A free-form style brief remains ordinary Stage-2 input; only an explicit `kind: style` workspace path activates the reusable Style contract. Directory shape never authorizes structure migration. A package with legacy Master/Layout/placeholder semantics must be replaced by a newly created template workspace before Step 3. Discoverability is handled by template indexes and explicit Q&A ("what templates are available?"), not by runtime fuzzy matching.
+**Exact selection, not semantic matching.** A bare name like
+`presentation_core`, a brand mention, or a style phrase such as "McKinsey
+style" is never fuzzy-matched to a directory. The default page lists registered
+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
+displayed as `library`; an unregistered root remains `explicit`. Current
+workspaces resolve `templates/design_spec.md`; compatible flat Brand/Layout/Deck
+packages may resolve direct `design_spec.md` only when they satisfy the current
+kind contract, including current structured SVGs for Layout/Deck. Style has no
+legacy-flat form. A free-form style brief remains ordinary Stage-2 input and
+does not activate a Style workspace. Directory shape never authorizes structure
+migration. A package with legacy Master/Layout/placeholder semantics must be
+replaced by a newly created template workspace before Step 3.
All current Brand/Style/Layout/Deck packages use one workspace routing contract. Brand and Style workspaces omit the SVG roster; empty optional directories are omitted:
@@ -384,7 +401,13 @@ Style narrows this routing shape to `templates/design_spec.md` only; it does
not carry asset or review payloads. Existing project scaffolding is not Style
input.
-`<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or `projects/<name>/`. Step 3 receives that root. The workspace is portable between locations without reshaping; global index registration is the only scope-specific behavior. Empty optional directories are absent, and template application never copies `exports/`.
+`<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or
+another exact workspace root such as `projects/<name>/`. 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. The source workspace remains portable between
+locations without reshaping; global index registration controls whether it
+appears as a library choice.
For Create Layout / Create Deck, `standard` and `fidelity` write new SVG documents and a new Master/Layout/slot system; source topology is visual evidence only and is neither preserved nor distilled. `mirror` materializes a new workspace from the source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals that are actually present and validated, without semantic synthesis or gap filling. Layout mirror is legal only when that preserved source is already brand-neutral and application-neutral; otherwise author a new Layout or retain the facts as Deck. Because structural layers cannot be `<g>`, fixed-layer source group wrappers are mechanically expanded into direct atoms while preserving ownership, paint order, and appearance. Create Brand analyzes identity fragments only; Create Style extracts portable method/direction only. Neither enters structural replication strategies or produces an SVG roster.
@@ -405,7 +428,7 @@ formatting from those rules plus the confirmed reading mode/type scale;
`mirror` preserves literal source formatting and text topology. Export may
place both rule sets into the same native Master/Layout graph.
-When several paths are supplied, fusion is segment-level, not field-level. Brand owns identity, Style owns direction/method defaults, Layout owns compatible structure, and Deck supplies descriptive recurring-application context plus fallback identity/structure under the current Stage-1 communication contract. User confirmation remains highest. Style palette/type defaults never override Brand/Deck identity; its method/composition expectations must be compatible with the selected Deck application and Layout/Deck structure or fusion surfaces a conflict. A project-local Brand + Layout composition gets its application context from Stage 1 and is not automatically promoted into a reusable library Deck. Same-kind conflicts are surfaced rather than resolved by implicit ordering. This keeps template composition debuggable: a fused spec can say exactly which bundle owns each segment.
+When several workspaces are selected, fusion is segment-level, not field-level. Brand owns identity, Style owns direction/method defaults, Layout owns compatible structure, and Deck supplies descriptive recurring-application context plus fallback identity/structure under the current Stage-1 communication contract. User confirmation remains highest. Style palette/type defaults never override Brand/Deck identity; its method/composition expectations must be compatible with the selected Deck application and Layout/Deck structure or fusion surfaces a conflict. A project-local Brand + Layout composition gets its application context from Stage 1 and is not automatically promoted into a reusable library Deck. Same-kind conflicts are surfaced rather than resolved by implicit ordering. This keeps template composition debuggable: a fused spec can say exactly which bundle owns each segment.
**Raw PPTX files cannot be Step 3 workspaces.** Normal Generate may use a PPTX as source material, and `beautify-pptx` may redesign it while preserving page count, order, and per-page wording 1:1; neither treats the source PPTX as a Step 3 template. When a raw PPTX is used as a template or native slide shell and filled with new material, the default route is Fill Native PPTX. If the request permits splitting, merging, dropping, reordering, or narrative restructuring, it remains Generate. Only a request to create a reusable template workspace and reuse that design system in SVG-route Step 3 first runs Create Template and then supplies the generated workspace root.
@@ -421,7 +444,7 @@ PPT Master uses **role switching within one main agent** rather than parallel su
**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode: it may not reselect upstream decisions or omit required attributes, but it still owns geometry, composition, hierarchy, and visual treatment inside implementation dimensions the Design Spec leaves open. Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.
-**The Strategist confirmation stage is the main user design-decision gate on the default continuous route.** Strategist uses one dependency-ordered three-stage gate. Stage 1 confirms an open communication contract and canvas. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Stage 2 is authored once from that contract and confirms the complete deck solution: reading mode, narrative mode, page count, coordinated visual system, image sources, and generated-image rendering. When a template is installed, Strategist also derives its page/prototype application plan from the actual workspace and current content and exposes that plan as editable natural-language prose; only the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. Stage 3 is authored once and contains production mechanics only: conditional AI acquisition, formula policy, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Those three values are fallback policies, not capability bans: the latest explicit user instruction wins, then Stage 3, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. The compatibility key `delivery_purpose` means reading mode. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.
+**The independent Step-3 template choice closes before the Strategist confirmation stage.** It is not Stage 1: the default UI first confirms free design or exact indexed/explicit workspaces, runs the common installation/fusion stage, and only then lets Strategist read the project-local result. Strategist uses one dependency-ordered three-stage gate. Stage 1 confirms an open communication contract and canvas. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Stage 2 is authored once from that contract and confirms the complete deck solution: reading mode, narrative mode, page count, coordinated visual system, image sources, and generated-image rendering. When a template is installed, Strategist also derives **how to apply it** from the project-local workspace and current content and exposes that plan as editable `template_application` prose; Stage 2 never reselects a template, and the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. Stage 3 is authored once and contains production mechanics only: conditional AI acquisition, formula policy, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Those three values are fallback policies, not capability bans: the latest explicit user instruction wins, then Stage 3, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. The compatibility key `delivery_purpose` means reading mode. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.
The three Stage 3 proactive values remain independent raw evidence. In
particular, enabling narration may enable the effective Speaker Notes outcome
@@ -776,7 +799,7 @@ Supporting files stay separate only to keep route contracts focused and load opt
|---|---|---|
| Generation profiles | `beautify-pptx`, `quick-generate` | Generate PPTX with either wording/page invariants or the explicit direct SVG-to-PPTX short circuit |
| Template child workflows | `create-brand`, `create-style`, `create-layout`, `create-deck` | Create Template dispatches exactly one for identity-only, roster-free direction/method, brand-neutral/application-neutral structure, or a recurring application with integrated identity/structure |
-| Template-input stage | `apply-template-workspace` | Generate PPTX Step 3; loaded only when an explicit workspace-root path triggers it |
+| Template-input stage | `apply-template-workspace` | Generate PPTX Step 3; runs after the independent indexed/explicit selection confirms at least one workspace |
| Generation stages | `topic-research`, `resume-execute`, `refine-spec`, `verify-charts`, `visual-review`, `live-preview`, `customize-animations` | Generate PPTX at their defined intake, planning, editing, quality, or post-processing points |
| Shared stage | `generate-audio` | Generate PPTX post-processing or Enhance Native PPTX narration integration |
| Governance | `failure-recovery` | Global stop/continue policy for all four routes; concrete recovery matrix and resume pointers for Generate PPTX |
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index 895be7dc..666763f5 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 with an explicit workspace path** | `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 → Step-3 template selector** | `Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/.` |
| A PPTX, SVG set, brand guide, website, images, or mixed references; first build a reusable system | **Create Template → Generate PPTX** | `Use /create-template to create a reusable Deck workspace from projects/brand/our_deck.pptx.` |
Do not pass a raw `.pptx` as a Generate PPTX template path. Fill it directly when you want its existing pages, or run Create Template first when you want a reusable system.
@@ -43,8 +43,8 @@ stay separate.
The two rules that prevent most mistakes:
-1. Supply the **workspace root**, not its `templates/` subdirectory and not a bare template name.
-2. Provide the explicit workspace path before [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option). A Create Template run may instead hand its validated workspace directly to Generate PPTX in the same conversation.
+1. In the default page, choose free design or an exact registered workspace from [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation). In chat, use the exact workspace root—not its `templates/` subdirectory or a bare template name.
+2. An explicit path and a Create Template handoff remain valid. Step 3 confirms and installs every selected workspace before Stage 1; later roles use only the project-local copy.
---
@@ -52,29 +52,31 @@ The two rules that prevent most mistakes:
### How to trigger
-The workflow **defaults to free design** — it will not ask whether you want a template and will not proactively suggest one. Templates are opt-in by **explicit directory path** only: provide the path before Generate PPTX reaches Step 3.
+The default confirmation page opens an independent **Step-3 template-selection phase before Stage 1**. It offers free design, registered Brand/Style/Layout/Deck workspaces, and any exact workspace roots already supplied for the run. It does not infer a recommendation from the topic: the user makes the selection explicitly.
### How to enter the template flow
-Send the Brand/Style/Layout/Deck workspace root in chat before Generate PPTX reaches Step 3. Anywhere in the sentence is fine; the path just has to be unambiguous:
+On the default page, select one or more compatible registered workspaces, or choose free design. The registered list comes only from the four kind indexes; the workflow never scans the template directories. You can also send an exact Brand/Style/Layout/Deck workspace root in chat before Step 3. Anywhere in the sentence is fine; the path just has to be unambiguous:
> "use this template: `skills/ppt-master/templates/layouts/presentation_core/`" ✅
> "use last deck's template: `projects/last_deck/`" ✅
> "make a product introduction with `/Users/me/Desktop/our_brand_v3/`" ✅
-For every current template kind, the path is the **template workspace root**. Step 3 resolves `templates/design_spec.md`; 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; user-supplied paths and current-conversation Create Template handoffs are the two valid triggers.
+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`. Step 3 resolves `templates/design_spec.md`; Brand/Layout/Deck install their package-owned `templates/` plus any real `images/` and `icons/`, while Style installs only its spec and ignores unrelated project scaffolding. It never copies `exports/`. Deck/Layout workspaces additionally validate the structured SVG contract; Brand/Style validate their roster-free specs. The path may point to a built-in library workspace under `skills/ppt-master/templates/<kind>/<id>/`, a project workspace under `projects/<name>/`, or another workspace with the same routing. A Create Template run may hand its exact validated workspace root directly to Step 3 in the same conversation.
+
+Template selection is not part of Stage 1. After confirmation, Step 3 runs the common apply stage and installs/fuses the selected workspaces into the project's `templates/`, `images/`, and `icons/`. Only then does Strategist begin Stage 1. The Stage-2 `template_application` field describes **how** to use that installed template; it never chooses **which** template to use.
> **Compatibility preflight:** Step 3 also accepts a legacy-flat Brand/Layout/Deck workspace with `design_spec.md` directly at the supplied root when it satisfies the current kind contract. Layout/Deck additionally require current structured SVGs; Style has no flat form. Former atomic-placeholder, unmapped Master/Layout, and other semantic-legacy packages are rejected; run `create-template` to create a new workspace, then generate new structured pages from that workspace. Nothing upgrades the old package in place.
### What does NOT trigger the template flow
-- **A bare template name without a path**: "use the presentation_core template" / "use the China Telecom template" → free design. The AI does not look the name up. You must give a path.
-- **Style descriptions**: "McKinsey style" / "Google style" / "minimalist" / "Keynote style" → free design. The descriptive words flow into Strategist as a style brief, but no template is copied.
-- **Vague intent**: "I want a template" with no path → free design.
+- **A bare template name in chat**: "use the presentation_core template" / "use the China Telecom template" does not resolve implicitly. Select the indexed entry on the page or return its exact path in chat.
+- **Style descriptions**: "McKinsey style" / "Google style" / "minimalist" / "Keynote style" remain design briefs. They never activate a workspace unless the user separately selects one.
+- **Vague intent**: "I want a template" does not authorize fuzzy lookup or directory scanning; the Step-3 choice remains open.
-This is intentional — the AI never makes a fuzzy / interpretive judgment about whether your wording maps to a template, and never resolves a name to a path on your behalf. If you want a template, give the path.
+This is intentional: the AI never makes a fuzzy or interpretive judgment about whether wording maps to a template. Use the indexed page choice or an exact root.
-To browse what's available in the built-in library, ask "what templates are available?" — the AI lists names and paths from the discovery index. Listing alone does not enter the template flow; you still need to send back a path to trigger Step 3.
+To browse in chat, ask "what templates are available?" The AI lists names and exact paths from the same four indexes. Listing alone does not select anything; return one of those exact paths or make the choice on the Step-3 page.
### Copy-ready examples
@@ -100,7 +102,7 @@ Make a deck from projects/annual-report/sources/report.md.
Template workspace: projects/acme_template/
```
-The path labels are optional; the paths themselves are mandatory. If two paths have the same kind, the workflow stops at the existing conflict-resolution gate instead of choosing one silently.
+For chat-based explicit selection, path labels are optional but exact roots are mandatory. Page-based library selection already carries exact roots. If two selections have the same kind, the workflow stops at the existing 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.
@@ -113,7 +115,7 @@ Templates are organized into four kinds, each with a discovery index:
- [`layouts_index.json`](../skills/ppt-master/templates/layouts/layouts_index.json) — structure-only workspaces: canvas / page grammar / page types / SVG roster, with identity selected downstream
- [`decks_index.json`](../skills/ppt-master/templates/decks/decks_index.json) — recurring presentation applications with integrated identity, structure, and factual prototype descriptions
-Ask "what templates are available?" for a readable list with workspace paths. The indexes are the current source of truth; 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 both the default Step-3 page and chat discovery; directories are never scanned. Ask "what templates are available?" for a readable list with exact workspace paths. The kind-specific READMEs define their contracts. Full data model + fusion / conflict-resolution rules: [`templates-architecture.md`](./templates-architecture.md).
### Free design vs template
@@ -123,16 +125,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 from an explicit directory path.
+A **style brief** is interpretive language ("minimalist" / "Keynote-style" / "editorial") that the Strategist turns into concrete design choices for one deck. A **Style workspace** is a real `kind: style` template with pre-authored communication method and visual defaults, consumed after the user selects its registered Step-3 entry or supplies its exact workspace root.
| | Style workspace | Style brief |
|---|---|---|
-| How invoked | Explicit directory path in your message | Free-form description in your message |
+| How invoked | Registered Step-3 page selection or exact directory path | Free-form description in your message |
| What it supplies | Reusable method, role/evidence discipline, and visual defaults; no identity truth or page prototypes | Intent that the Strategist interprets into mode, visual style, color, typography, icons, and imagery |
| Confirmation | Stored values seed Stage 2; Brand/Deck identity and user-confirmed choices remain authoritative | No pre-authored values; the Strategist proposes concrete candidates and the user confirms them |
| Best for | Repeating a design/argument approach across projects without freezing pages | Expressing a desired feel for the current project only |
-A style description and a Style workspace still go through different machinery: "minimalist" is interpretive language, while `templates/styles/<id>/` is a real template directory that requires an explicit path. `kind: style`, Stage-2 `visual_style`, and internal `template_reuse_scope: style` are separate axes.
+A style description and a Style workspace still go through different machinery: "minimalist" is interpretive language, while `templates/styles/<id>/` is a real registered workspace selected by exact index entry or exact path. `kind: style`, Stage-2 `visual_style`, and internal `template_reuse_scope: style` are separate axes.
### How style briefs are interpreted
@@ -239,7 +241,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 **discoverable** — when someone asks "what templates are available?", the AI lists it from the index. To use either scope, follow [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option): provide the workspace root before Step 3 runs, for example `use this template: skills/ppt-master/templates/layouts/<your_template_id>/` or `use this template: projects/<name>/`. A project workspace can also be migrated or reused elsewhere because its core shape is identical; register it only if it is placed in the library and should appear in discovery.
+Library registration makes the template **selectable** on the default page and discoverable in chat because both read the same index. To use a registered workspace, select it in [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation). For project scope or an exact handoff, supply the workspace root, for example `use this template: projects/<name>/`; an unregistered root remains labelled `explicit`. A project workspace can also be migrated or reused elsewhere because its core shape is identical; register it only if it is placed in the library and should appear in the library catalog.
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.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 33c8a67a..60c6512e 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -52,8 +52,9 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
├── 若缺少同 stem 的规范 Markdown,再对该归档 PPTX 运行 ppt_to_md.py
└── sources/ 内容型文件成为内容契约
↓
-[模板 / 品牌 / Style / 布局(可选)] — 默认跳过,直接自由设计
- 仅在用户明确提供符合当前合同的 Brand/Style/Layout/Deck 工作区根路径时触发:可以是全局模板库条目根,也可以是项目工作区根
+[模板选择与安装(Step 3)] — Stage 1 前的默认 UI 选择
+ 选择自由设计、索引中的 Brand/Style/Layout/Deck library 条目,或精确的 explicit 工作区 root;索引是完整 library 来源,不扫描目录
+ 已确认工作区在 Strategist 启动前校验/合成到项目本地 templates/images/icons
原生 PPTX 模板请求进入 template-fill;可复用 SVG 模板需先通过 create-template 创建
↓
[Strategist] 策略师 - 三阶段策略师确认与设计规范 → design_spec.md + spec_lock.md
@@ -157,7 +158,7 @@ narration 标记。
| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | Generate PPTX + `beautify-pptx` profile | 通过 SVG 重新生成;内容和分页锁定 |
| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | Enhance Native PPTX(`native-enhance-pptx`) | 直接 OOXML patch;不重新设计 |
| 用户想从一个或多个 PPTX/SVG、图片/PDF、文档/网站、品牌资产、直接文字或混合参考材料包构建可复用模板工作区 | Create Template(`create-template`) | 固定入口读取每个适用证据通道,只分派一个 Create Brand、Create Style、Create Layout 或 Create Deck 子工作流,再返回供 Generate Step 3 使用的工作区根目录;结构型子工作流可导出审阅 PPTX |
-| 用户提供符合当前合同的明确模板路径 | Generate PPTX Step 3 | 当前 Brand/Style/Layout/Deck 工作区解析 `templates/design_spec.md`;只有兼容的旧平铺 Brand/Layout/Deck 根目录可解析直接 `design_spec.md`;语义旧包会被拒绝,并通过 Create Template 替换 |
+| 用户选择索引中的 library 模板,或提供符合当前合同的精确工作区 root | Generate PPTX Step 3 | 独立的 Stage-1 前置阶段确认自由设计或精确 Brand/Style/Layout/Deck root,再把所选工作区校验/合成到项目;只有兼容的旧平铺 Brand/Layout/Deck 根目录可解析直接 `design_spec.md` |
| 用户要求调整对象级动画顺序 / 效果 / 计时 | Generate PPTX + `customize-animations` 阶段 | 通过 `animations.json` 控制可选导出策略 |
| 用户要求预览、选择、注解或重导出浏览器编辑 | Generate PPTX + `live-preview` 阶段 | 注解只在规定交接点应用 |
@@ -346,11 +347,11 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
## 模板系统与可选路径
-模板是**可选项,不是默认**。Strategist 默认走自由设计——AI 完全凭源内容创造视觉系统。模板路径只在用户明确提供目录路径时启用。
+模板是**可选项,不会被自动推断**。Strategist Stage 1 之前,默认 UI 会先打开独立 Step 3:选择自由设计、已注册 library 工作区,或本次运行明确提供的 root。自由设计仍是从当前内容推导的路径;系统不会根据主题相似度替用户选模板。
**为什么默认自由设计。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),所以它一直在;但 AI 不主动去抓,是用户去抓。
-**机械触发,不做语义匹配。** 像 `presentation_core` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,即使库里存在相似目录,也不会触发 Step 3。Step 3 只消费显式路径。当前 Brand/Style/Layout/Deck 工作区均解析 `templates/design_spec.md`;自由文字风格说明仍只是 Stage 2 输入,只有显式 `kind: style` 工作区路径才启用可复用 Style 合同。旧平铺 Brand/Layout/Deck 目录只有在满足当前 kind 合同时,才兼容从根目录读取 `design_spec.md`;Layout/Deck 还必须满足当前 structured SVG 合同。Style 不存在旧平铺形态。目录形态从不授权结构迁移;带旧 Master/Layout/placeholder 语义的包必须先替换为新建的模板工作区,才能进入 Step 3。发现性交给模板索引和显式问答(“有哪些模板可以用?”),不交给运行时 fuzzy matching。
+**精确选择,不做语义匹配。** 像 `presentation_core` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,永远不会 fuzzy-match 到目录。默认页面只从四个 `*_index.json` 列出已注册 Brand/Style/Layout/Deck;聊天发现也读取同一组索引并返回精确 root。显式路径仍有效;若它与某个已注册 canonical root 精确相同,可显示为 `library`,未注册 root 仍是 `explicit`。当前工作区均解析 `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,空的可选目录直接省略:
@@ -366,7 +367,7 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
Style 将这一路由形态收窄为仅 `templates/design_spec.md`,不携带素材或
审阅 payload;项目中既有的脚手架也不属于 Style 输入。
-`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/`。Step 3 接收这个根目录。工作区可在两个位置之间迁移而不改形;唯一的范围差异是全局索引注册。空的可选目录不创建,`exports/` 也不会复制进新项目。
+`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/` 等其他精确 root。Step 3 会把所选输入校验、合成并安装到当前项目的 `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。
@@ -381,7 +382,7 @@ Style 将这一路由形态收窄为仅 `templates/design_spec.md`,不携带
Theme、Slide Master、Slide Layout 与 Placeholder 是编译生成的 PowerPoint 原生对象,不是新的模板 kind。Layout 决定拓扑、位置、语义文字角色与空间行为,Brand 决定身份值与资产。`template_reuse_scope: layout` 会结合已确认的阅读模式和字号体系解析最终 placeholder 格式;`mirror` 则保留来源的字面格式与文字拓扑。两类规则都可编译进同一套原生 Master/Layout 图谱。
-当用户提供多个路径时,融合是**片段级**而不是字段级:Brand 拥有身份,Style 拥有方向/方法默认值,Layout 拥有兼容结构,Deck 在当前 Stage 1 沟通契约下提供描述性的重复应用语境及兜底身份/结构;用户最终确认最高。Style 的色彩/字体 fallback 不覆盖 Brand/Deck 身份,其方法与构图预期必须兼容所选 Deck 应用和 Layout/Deck 结构,否则显式提出冲突。项目内 Brand + Layout 组合的应用语境来自 Stage 1,不会自动升级成可注册的 Deck。同类冲突也会显式列出,而不是按输入顺序默默决定。这样融合后的 spec 能明确说明每个片段来自哪里,便于审计和复现。
+当用户选择多个工作区时,融合是**片段级**而不是字段级:Brand 拥有身份,Style 拥有方向/方法默认值,Layout 拥有兼容结构,Deck 在当前 Stage 1 沟通契约下提供描述性的重复应用语境及兜底身份/结构;用户最终确认最高。Style 的色彩/字体 fallback 不覆盖 Brand/Deck 身份,其方法与构图预期必须兼容所选 Deck 应用和 Layout/Deck 结构,否则显式提出冲突。项目内 Brand + Layout 组合的应用语境来自 Stage 1,不会自动升级成可注册的 Deck。同类冲突也会显式列出,而不是按输入顺序默默决定。这样融合后的 spec 能明确说明每个片段来自哪里,便于审计和复现。
**原生 PPTX 不能直接作为 Step 3 工作区。** 普通 Generate 可以把 PPTX 作为源材料使用,`beautify-pptx` 也可以在页数、页序和逐页措辞 1:1 的边界下重新设计;这两种情况都不会把原始 PPTX 当作 Step 3 模板。把原生 PPTX 作为模板或页面壳、再用新材料填充时,默认进入 Fill Native PPTX;若请求允许拆分、合并、删页、重排或叙事重构,则仍属于 Generate。只有当目标是创建可复用模板工作区、并在 SVG 路线的 Step 3 中重复使用其设计系统时,才先运行 Create Template,再传入生成的工作区根目录。
@@ -397,7 +398,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式:不得重选上游方案或漏掉必需属性,但在 Design Spec 留出的范围内仍拥有几何、构图、层级和视觉处理的实现权。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。
-**策略师确认阶段是默认连续路线中的主要用户设计决策 gate。** Strategist 阶段以一个按依赖排序的三阶段 gate 作为核心决策点。第一阶段确认开放式沟通契约与画布。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。第二阶段只从该契约计算一次并确认完整 PPT 方案:阅读模式、叙事 mode、页数、成套视觉系统、图片来源和生成图渲染。存在模板时,Strategist 还会根据真实工作区和当前内容推导页面/原型应用计划,并以可编辑的自然语言文本展示;只有内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算第二阶段。第三阶段也只计算一次,并且只处理生产机制:条件式 AI 图片获取路径、公式策略、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。这三项是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → Stage 3 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。JSON 为兼容保留 `delivery_purpose` 键,但用户侧统一称为阅读模式。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。
+**独立 Step 3 模板选择会在 Strategist 确认阶段前完成。** 它不属于 Stage 1:默认 UI 先确认自由设计,或精确的 indexed/explicit 工作区,运行统一安装/合成阶段,再让 Strategist 读项目本地结果。Strategist 阶段以一个按依赖排序的三阶段 gate 作为核心决策点。第一阶段确认开放式沟通契约与画布。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。第二阶段只从该契约计算一次并确认完整 PPT 方案:阅读模式、叙事 mode、页数、成套视觉系统、图片来源和生成图渲染。存在已安装模板时,Strategist 只从项目本地工作区和当前内容推导**如何应用**,并以可编辑的 `template_application` 自然语言展示;Stage 2 不会重新选模板,只有内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算第二阶段。第三阶段也只计算一次,并且只处理生产机制:条件式 AI 图片获取路径、公式策略、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。这三项是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → Stage 3 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。JSON 为兼容保留 `delivery_purpose` 键,但用户侧统一称为阅读模式。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。
Stage 3 的三个主动执行值始终保留为相互独立的原始证据。尤其是,
启用旁白可以在 Design Spec 中启用 Speaker Notes 的最终有效结果,
@@ -729,7 +730,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;只在显式工作区根目录触发时加载 |
+| 模板输入阶段 | `apply-template-workspace` | Generate PPTX Step 3;独立 indexed/explicit 选择确认至少一个工作区后运行 |
| 生成阶段 | `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-guide.md b/docs/zh/templates-guide.md
index f3908b67..03e56c3b 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 + 显式工作区路径** | `用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/。` |
+| 已有可复用 Brand/Style/Layout/Deck 工作区,想生成一份全新 deck | **Generate PPTX → Step 3 模板选择** | `用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/。` |
| 手里是 PPTX、SVG、品牌手册、网站、图片或混合参考,想先建立可复用系统 | **Create Template → Generate PPTX** | `用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 工作区。` |
不要把原始 `.pptx` 当作 Generate PPTX 的模板路径。想沿用它的现有页面就直接回填;想建立可复用系统,就先运行 Create Template。
@@ -37,8 +37,8 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
最容易避免误用的两条规则:
-1. 提供**工作区根目录**,不要只给它的 `templates/` 子目录,也不要只写模板名。
-2. 在 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 之前明确给出工作区路径。同一对话刚完成 Create Template 时,也可直接把已验证工作区交给 Generate PPTX。
+1. 默认页面会在 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation) 选择自由设计或精确的已注册工作区;若在聊天中选择,请给出工作区根目录,不要只给 `templates/` 子目录,也不要只写模板名。
+2. 显式路径和 Create Template 的精确交接仍然有效。Step 3 会先确认并安装全部所选工作区,再进入 Stage 1;后续角色只读项目本地副本。
---
@@ -46,29 +46,31 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是 PowerPoint 原生对象
### 触发方式
-工作流**默认走自由设计**——不会主动问你要不要用模板,也不会基于内容主动推荐模板。模板是 opt-in 的,**只接受显式目录路径**:在 Generate PPTX 进入 Step 3 前把模板目录路径写出来。
+默认确认页面会在 Stage 1 之前打开一个独立的 **Step 3 模板选择阶段**,同时提供自由设计、已注册的 Brand/Style/Layout/Deck,以及本次运行已明确给出的工作区根目录。它不会根据主题替用户推断推荐模板,选择必须由用户明确完成。
### 怎么触发模板流程
-在 Generate PPTX 进入 Step 3 前,于对话里写出 Brand/Style/Layout/Deck 工作区根目录(位置不重要,只要明确即可):
+在默认页面中,可选择一个或多个兼容的已注册工作区,也可以选择自由设计。已注册列表只来自四类索引,工作流不会扫描模板目录。也可以在 Generate PPTX 进入 Step 3 前,于对话里写出 Brand/Style/Layout/Deck 工作区根目录(位置不重要,只要明确即可):
> "用这个模板做:`skills/ppt-master/templates/layouts/presentation_core/`" ✅
> "用上次那个模板:`projects/last_deck/`" ✅
> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
-对于当前所有模板类型,这里给的都是**模板工作区根目录**。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;用户显式提供路径与当前对话的 Create Template 交接是两种合法触发方式。
+对于当前所有模板类型,显式路径都是**模板工作区根目录**。若精确路径与索引中的注册 root 一致,页面可以把它显示为 `library`;未注册 root 则单独标为 `explicit`。Step 3 会解析其中的 `templates/design_spec.md`;Brand/Layout/Deck 安装其包自有 `templates/` 及真实存在的 `images/`、`icons/`,Style 只安装 spec,并忽略项目中无关的脚手架。如果工作区本来就是该项目根目录,则原地消费,并且始终不复制 `exports/`。Deck/Layout 还会校验 structured SVG 合同;Brand/Style 校验各自无 roster 的 spec。路径可以指向 `skills/ppt-master/templates/<kind>/<id>/` 下的内置库工作区、`projects/<name>/` 下的项目工作区,或其他保持同样路由的工作区。当前对话刚完成 Create Template 时,可把精确的已验证工作区根目录直接交给 Step 3。
+
+模板选择不属于 Stage 1。确认后,Step 3 会运行统一 apply 阶段,把所选工作区校验、合成并安装到当前项目的 `templates/`、`images/`、`icons/`;完成后 Strategist 才开始 Stage 1。Stage 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 模板" / "做一份中国电信模板的产品介绍" → 走自由设计。AI 不会替你把名字解析成路径。要用模板,请直接给路径。
-- **风格描述**:"麦肯锡风格" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" → 走自由设计。这些描述会顺着对话流到 Strategist 那边作为风格说明使用,但**不会复制任何模板文件**。
-- **模糊意图**:"想用个模板" / "选一个吧"——没给路径 → 走自由设计。
+- **在聊天中只写模板名**:"用 presentation_core 模板" / "做一份中国电信模板的产品介绍" 不会被隐式解析。请在页面选择对应索引项,或在聊天中返回精确路径。
+- **风格描述**:"麦肯锡风格" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" 仍只是设计说明;除非用户另行选择工作区,否则不会激活模板。
+- **模糊意图**:"想用个模板" / "选一个吧" 不会授权模糊查找或目录扫描,Step 3 选择仍保持未完成。
-这是有意的——AI 永远**不做模糊 / 解释性判断**,不替你把名字解析成路径。要用模板,直接给路径。
+这是有意的——AI 永远**不做模糊 / 解释性判断**,不会替你把普通文字解析成模板。请使用页面中的精确索引项,或提供精确 root。
-想知道内置库里有哪些模板,问一句"有哪些模板可以用?"——AI 会从发现索引里列出名字和对应路径。单纯列出并不进入模板流程,需要你**把其中一条路径**再发回来才会触发 Step 3。
+想在聊天里知道内置库有哪些模板,问一句"有哪些模板可以用?"——AI 会从同一组四类索引列出名字和精确路径。单纯列出不代表选择;需要返回其中一条精确路径,或在 Step 3 页面完成选择。
### 可直接复制的用法
@@ -94,7 +96,7 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
模板工作区:projects/acme_template/
```
-“模板工作区”这些标签可以不写,但路径本身必须明确。如果给出两个相同 kind 的路径,工作流会进入既有冲突解决门,不会静默替你选一个。
+在聊天中显式选择时,“模板工作区”这些标签可以不写,但 root 必须精确;页面中的 library 选择已自带精确 root。如果选择两个相同 kind 的工作区,工作流会进入既有冲突解决门,不会静默替你选一个。
你不需要选择模板使用模式。对 Layout/Deck,Strategist 会读取真实的 Master/Layout/原型集合和当前内容,决定选哪些页、哪些重复/跳过/重排,以及是否重组。Brand 只提供身份约束,Style 只提供方向/方法默认值;除非另一个工作区提供结构,否则两者都保持页面自由编排。如果你在意某个边界,直接在同一句请求里用普通语言说明即可,例如“封面和结束页原样保留,中间页由你选择”或“只参考视觉语言”;明确文字优先于 AI 判断。
@@ -107,7 +109,7 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
- [`layouts_index.json`](../../skills/ppt-master/templates/layouts/layouts_index.json) — 仅结构工作区:canvas / 页面语法 / page types / SVG roster,身份系统下游再选
- [`decks_index.json`](../../skills/ppt-master/templates/decks/decks_index.json) — 可重复演示应用,包含一体化身份、结构与原型事实描述
-直接问“有哪些模板可以用?”即可得到带工作区路径的可读清单。索引是当前安装内容的真值,四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
+这四个索引是默认 Step 3 页面与聊天发现共用的完整已注册模板来源,目录永远不会被扫描。直接问“有哪些模板可以用?”即可得到带精确工作区路径的可读清单;四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
### 自由设计 vs 模板
@@ -117,16 +119,16 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
### 风格说明不是 Style 工作区
-**风格说明**是解释性语言(“极简风” / “Keynote 风” / “杂志风”),由 Strategist 转化为当前 deck 的具体设计选择。**Style 工作区**则是真实存在的 `kind: style` 模板,预写可复用沟通方法与视觉默认值,只有在你给出**显式目录路径**时才会被消费。
+**风格说明**是解释性语言(“极简风” / “Keynote 风” / “杂志风”),由 Strategist 转化为当前 deck 的具体设计选择。**Style 工作区**则是真实存在的 `kind: style` 模板,预写可复用沟通方法与视觉默认值;用户在 Step 3 选择对应注册项,或提供精确工作区 root 后才会消费。
| | Style 工作区 | 风格说明 |
|---|---|---|
-| 怎么触发 | 消息里给出明确的目录路径 | 消息里写自由描述 |
+| 怎么触发 | Step 3 页面选择注册项,或消息里给出精确目录路径 | 消息里写自由描述 |
| 提供什么 | 可复用方法、角色/证据纪律和视觉默认值;无身份真值或页面原型 | 由 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` 是三条不同轴。
### 风格说明如何被解释
@@ -228,7 +230,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 审阅规则 | 跳过全局索引注册 |
-全局注册让模板**可被发现**——下次有人问“有哪些模板可用?”时,AI 会从索引里把它列出来。两种范围的用法相同:按 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 的规则,在 Step 3 运行前给出工作区根目录,例如 `用这个模板:skills/ppt-master/templates/layouts/<your_template_id>/` 或 `用这个模板:projects/<name>/`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要被发现时才执行注册。
+全局注册会让模板出现在默认页面中,也可在聊天中发现,因为两者都读取同一个索引。使用已注册工作区时,在 [Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-selection-and-installation) 中直接选择它。项目范围或精确交接则提供工作区 root,例如 `用这个模板:projects/<name>/`;未注册 root 仍标记为 `explicit`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要出现在 library 列表中时才执行注册。
选择 Deck/Layout 模板后,Strategist 会自动生成页面/原型应用计划:可以使用全套或子集,重复或重排原型,并按内容需要重组。`strict` / `adaptive` 只作为内部导出值,不再出现在确认选项中。
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index 58aed74e..3c94f5b0 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -33,7 +33,8 @@ 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 use any icon in this project-local pool; `spec_lock.icons.inventory` records the default plan's bundled choices rather than an exhaustive whitelist. Exporter global fallback is legacy compatibility only. |
-| `templates/` | Project template reference | Step 3 imported specs, optional Layout/Deck SVG prototypes, and non-image assets | Strategist reads every installed template Design Spec. It reads 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 Step-3 UI selection and chat listing | Read the four index files only; never scan kind directories to add options. Derive a library root from kind + entry id. Exact unregistered roots remain explicit inputs and never enter an index implicitly. |
+| `templates/` | Project template reference | Step 3 installed/fused specs, optional Layout/Deck SVG prototypes, and non-image assets | After selection, Strategist and every later role read this project-local state only, never the library/external installation root. Strategist 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 |
@@ -42,7 +43,8 @@ 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/recommendations.stage1.json`, `.stage2.json`, `.stage3.json` | Confirmation proposals | One Strategist-authored payload per confirmation stage | Confirm UI selects the active file from `result.json`. The active, unconfirmed stage may be overwritten when the user requests a new recommendation; normal progression writes the next stage file and leaves confirmed earlier stages intact. Legacy `recommendations.json` is read only when no stage-specific file exists. |
+| `confirm_ui/template_options.json`, `template_selection.json`, `template_handoff.json` | Step-3 template phase | Agent-authored input, user-confirmed exact selection, and agent-authored installation/free-design completion receipt | The server builds library candidates only from the four indexes and binds selection/handoff hashes. Stage 1 is exposed only after the bound handoff and a fresh recommendation. Template choices never enter `result.json`. |
+| `confirm_ui/recommendations.stage1.json`, `.stage2.json`, `.stage3.json` | Confirmation proposals | One Strategist-authored payload per communication/solution/production stage | Create these only after Step-3 template selection and installation closes. Template choice is not a Stage-1 field; Stage 2 may carry only `template_application`, which decides how to use the installed project-local template. Confirm UI selects the active file from `result.json`. The active, unconfirmed stage may be overwritten when the user requests a new recommendation; normal progression writes the next stage file and leaves confirmed earlier stages intact. Legacy `recommendations.json` is read only when no stage-specific file exists. |
| `confirm_ui/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 |
@@ -77,6 +79,7 @@ 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 | Step 3 confirms free design or exact roots before Stage 1. Library candidates come only from the four `*_index.json` files; unregistered roots require explicit input. Every non-free selection runs the same validator/installer and becomes one project-local `templates/` state before Strategist reads it. Stage 2 owns use, not selection. |
| Proactive production outcomes | Resolve notes/animation/narration from explicit instruction → Stage 3 → defaults, then persist outcomes/provenance only in Design Spec §I. Explicit notes-off/audio-on applies Generate's dependency gate; Stage 3 animation `false` does not suppress a sidecar. |
**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.md b/skills/ppt-master/references/strategist.md
index fbf41c8f..13b5cd4a 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 + Template option confirmed | **Strategist**: Strategist confirmation stage + Design Spec | Image_Generator or Executor |
+| Project creation + independent Step-3 template selection/installation complete | **Strategist**: Stage 1–3 confirmation + Design Spec | Image_Generator or Executor |
---
@@ -24,7 +24,11 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
⛔ **BLOCKING**: After the read, present professional recommendations for the confirmation fields below and wait for explicit user confirmation.
-**Three-stage confirmation (the default Confirm UI flow; chat mirrors it).** The sequence is scene first, complete solution second, production third:
+**Three-stage confirmation (the default Confirm UI flow; chat mirrors it).**
+Generate Step 3 has already confirmed free design or installed the selected
+template into this project. That independent selection is not a Stage-1 field
+and must not be reopened here. The sequence is scene first, complete solution
+second, production third:
| Stage | Items | Role |
|---|---|---|
@@ -32,13 +36,13 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
| **2 — complete deck solution** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering · conditional natural-language template application | derived from the confirmed contract; internal template exporter modes remain hidden |
| **3 — resources / production** (authored once from the user's *actual* Stage 1 + Stage 2) | formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle · proactive speaker notes / custom animations / narration audio | derived from the confirmed solution |
-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, and image direction. With a template, inspect its actual prototypes/content, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Stage 3 covers production. Its proactive defaults are speaker notes `true`, custom animations `false`, and narration audio `false`; a prior explicit user instruction overrides the matching recommendation, and effective narration audio requires effective speaker notes. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
+Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, image direction, and how the already installed template should be used. It never chooses or installs a template. Inspect only the project-local template spec/prototypes, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Stage 3 covers production. Its proactive defaults are speaker notes `true`, custom animations `false`, and narration audio `false`; a prior explicit user instruction overrides the matching recommendation, and effective narration audio requires effective speaker notes. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
-> **Execution discipline**: This is the last always-on BLOCKING checkpoint. After confirmation, proceed without another pause unless spec refinement is enabled.
+> **Execution discipline**: Step 3 template selection was the preceding independent BLOCKING checkpoint. This is the last always-on checkpoint. After confirmation, proceed without another pause unless spec refinement is enabled.
>
> **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 launch, 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, use `<project>/confirm_ui/recommendations.stage1.json`, `.stage2.json`, and `.stage3.json`; replace only the active unconfirmed stage, preserve confirmed files, and print the URL plus Stage-1 summary/fallback without treating that handoff as confirmation. Stage 1 writes canonical BCP-47 `primary_language` apart from UI `lang`; Strategist projects it through Design Spec §I to lock communication. Stage 2 carries ≥3 safe / shifted / bold `design_directions`, each bundling visual style, a six-role HEX palette, primary-language heading/body typography plus an English companion only for non-English decks, icons, and conditional image rendering. Step 4 retains final confirmation from the selected channel for Design Spec authoring. `confirm_ui.md` owns schema and lifecycle.
+> **Default presentation surface — Confirm UI.** Before Step 3, apply [`confirm_ui.md`](../scripts/docs/confirm_ui.md)'s sticky per-run surface decision; its explicit chat branch skips every UI command, and a chat selection after UI launch follows its in-run switch procedure. Chat-question tools alone do not select a branch. The UI branch closes template selection/installation before it exposes Stage 1. Then use `<project>/confirm_ui/recommendations.stage1.json`, `.stage2.json`, and `.stage3.json`; replace only the active unconfirmed stage, preserve confirmed files, and print the URL plus Stage-1 summary/fallback without treating that handoff as confirmation. Stage 1 writes canonical BCP-47 `primary_language` apart from UI `lang`; Strategist projects it through Design Spec §I to lock communication. Stage 2 carries ≥3 safe / shifted / bold `design_directions`, each bundling visual style, a six-role HEX palette, primary-language heading/body typography plus an English companion only for non-English decks, icons, and conditional image rendering. Step 4 retains final confirmation from the selected channel for Design Spec authoring. `confirm_ui.md` owns selection-surface and staged-confirmation lifecycle.
**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:
@@ -149,7 +153,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 an explicit workspace path into `<project_path>/templates/`, read [`strategist-template.md`](./strategist-template.md) before completing Stage 2. It 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. Bare names, style words, and free-design projects do not trigger it.
+**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.
**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/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index 35062c40..39cdd4c2 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -1,11 +1,21 @@
-# Confirm UI — Strategist Confirmation Stage Page
-
-> The interactive, visual surface for [`generate-pptx`](../../workflows/generate-pptx.md) Step 4. Stage 1 is an open communication brief: common purpose paths are prompt text, never checkboxes or a forced single label. Stage 2 offers **≥3 coordinated design directions** and then exposes their component values for deliberate override; color, typography, icons, and generated-image rendering are one system rather than unrelated grids. When a template workspace is active, Stage 2 also shows one editable natural-language template-application plan—never internal mode controls. Generated images inherit the selected deck colors directly—there is no image-palette control. Stage 3 contains production mechanics only. The AI uses one `recommendations.stageN.json` file per stage; the active, unconfirmed stage may be overwritten when the user requests a new recommendation. Confirmed values accumulate into `result.json`. Final confirm saves the result and shuts the server down. The chat path mirrors the same staged semantics.
+# Confirm UI — Template Selection and Strategist Confirmation Page
+
+> The interactive surface for [`generate-pptx`](../../workflows/generate-pptx.md)
+> Step 3 template selection and Step 4 Strategist confirmation. The independent
+> Step-3 phase first confirms free design or exact indexed/explicit template
+> roots; selected workspaces are applied into the project before Stage 1 exists.
+> Stage 1 then confirms the open communication brief, Stage 2 confirms a
+> coordinated deck solution and—when a template is installed—editable prose for
+> **how** to apply it, and Stage 3 confirms production mechanics. Template
+> selection persists separately in `template_selection.json`; Strategist values
+> accumulate into `result.json`. The chat path mirrors the same phase boundary.
## Authority and Scope
| Concern | Owner |
|---|---|
+| Step 3 template-selection gate and 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 |
| Stage 1 / Stage 2 / Stage 3 field membership | This document |
@@ -16,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 any UI command**: Resolve the most recent
+**Mandatory surface decision — before Step 3 or any UI command**: Resolve the most recent
explicit confirmation-surface instruction for this run before running
`--daemon` or `--wait-only`. Unrelated later messages do not reset the selected
branch. A new explicit selection may change it before launch; once confirmation
@@ -24,23 +34,25 @@ starts in chat or UI switches to chat, keep chat for the rest of this run.
| Most recent explicit surface instruction | Branch |
|---|---|
-| The user explicitly delegates confirmation | Present one complete delegated three-stage summary in chat. Do not launch the page or fabricate `result.json`. |
-| Otherwise, the user asks for or agrees to personally confirm in chat, or declines the confirmation page | Use chat for all three stages. Do not launch the page, run `--wait-only`, or require a UI-authored `result.json`. |
+| The user explicitly delegates confirmation | Present one complete delegated template choice plus three-stage summary in chat. Do not launch the page or fabricate either UI receipt. |
+| Otherwise, the user asks for or agrees to personally confirm in chat, or declines the confirmation page | Use chat for Step 3 selection and all three Strategist stages. Do not launch the page, run `--wait-only`, or require UI-authored receipts. |
| 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 three
-stages and confirmed-value semantics.
+chat branch—the user's instruction does. Both branches preserve the independent
+template choice followed by the same three Strategist stages and confirmed-value
+semantics.
**Fallback rule**: When no surface was selected before launch, the page is the
-default. Use chat when the user answers the always-on handoff in chat, or after
-launch failure/timeout and one `result.json` re-check. A chat-question tool
-alone is not a launch failure. Preserve all three stages and keep Stage-1
-prompts open-ended.
+default. Use chat when the user answers either always-on handoff in chat, or
+after launch failure/timeout and one re-check of the receipt for the active
+phase (`template_selection.json` for Step 3, `result.json` afterward). A
+chat-question tool alone is not a launch failure. Preserve template selection
+as an independent choice and keep Stage-1 prompts open-ended.
-**In-run UI → chat switch — any stage**: If the user explicitly selects chat
+**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
starts, or after it times out while the server remains live:
@@ -50,16 +62,26 @@ 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 `result.json` once for the current stage. Retain only values whose
- confirmation was persisted before shutdown; an unsubmitted browser draft is
- not confirmed.
-4. Continue the unresolved current stage and every remaining stage in chat. Do
+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.
+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.
-**Always-on Stage-1 chat handoff**: Launch the healthy daemon without `--wait`.
-After it returns, immediately post its actual URL plus one compact, localized
-summary of the current Stage-1 recommendations: audience, communication intent,
+**Always-on 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; 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 Step 3 confirms and any template is
+installed, write `recommendations.stage1.json`; the same live page changes from
+waiting state to Stage 1. Immediately post the existing actual URL plus one
+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
@@ -76,26 +98,30 @@ the same items as open Stage-1 chat questions and wait for an explicit response.
The following launch and wait commands belong to the **UI branch only**:
```bash
-python3 scripts/confirm_ui/server.py <project_path> --daemon # healthy launch; return for chat handoff
+python3 scripts/confirm_ui/server.py <project_path> --daemon # launch Step 3; return for template chat handoff
+python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage template # Step 3 selection
+python3 scripts/confirm_ui/server.py <project_path> --complete-template-phase # after free-design closure / template install
python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1 # Stage 1
python3 scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage2 # Stage 2: wait for the direction handoff
python3 scripts/confirm_ui/server.py <project_path> --wait-only # Stage 3: wait for the final result
python3 scripts/confirm_ui/server.py <project_path> --daemon --port 5051
python3 scripts/confirm_ui/server.py <project_path> --no-browser
python3 scripts/confirm_ui/server.py <project_path> --timeout 0 # disable idle auto-shutdown
+python3 scripts/confirm_ui/server.py <project_path> --reset-template-phase # re-open Step 3 receipts only
python3 scripts/confirm_ui/server.py <project_path> --shutdown # Step 4 cleanup (idempotent)
```
- Without `--port`, binds the first free port from `127.0.0.1:5050`; the launch log prints the actual URL. `--port N` is exact and fails when unavailable. Auto-open is suppressed by `--no-browser`.
- In `--daemon` mode the launcher starts the child with browser opening suppressed, then accepts readiness only when `GET /api/health` identifies this confirm service, project, and child process. It opens the printed `http://127.0.0.1:<port>` URL only after that check.
- Confirm UI and live preview prefer the same memorable base port but keep separate processes and project-local locks (`.confirm_ui.lock` vs `live_preview/lock.json`). Normal Step 4 cleanup releases the confirm port before Step 6; concurrent projects may use different ports.
-- `--daemon` starts the Flask process in the background and returns after the health check. Generate uses it without `--wait` so the Stage-1 chat handoff appears before blocking. `--daemon --wait` remains a combined compatibility form. The wait budget defaults to **590 s** (`--wait-timeout`); on timeout the detached server remains live, and the caller re-checks `result.json` once before chat fallback.
-- `--wait-only` attaches to the page opened by `--daemon` and blocks until the requested stage. If that stage is already persisted, it 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` only for a fresh Stage-1 launch, `stage2` for the complete-solution handoff, and `final` for Stage 3. It keys on stage alone; resume chooses the target from the persisted result instead of restarting Stage 1.
+- `--daemon` starts the Flask process in the background and returns after the health check. Generate first uses it without `--wait` for the Step-3 handoff; the same process then remains live across installation and all three Strategist stages. `--daemon --wait --wait-stage template` remains a combined compatibility form. The wait budget defaults to **590 s** (`--wait-timeout`); on timeout the detached server remains live, and the caller re-checks the active receipt once before chat fallback.
+- `--wait-only` attaches to the page opened by `--daemon` and blocks until the requested receipt. If it is already persisted, the command returns before recovery, so a fast submit between launch, chat handoff, and wait is not lost. Otherwise, if the recorded server died, it restarts on the recorded/default port. Use `template` for Step 3, `stage1` after installation and the communication handoff, `stage2` for the complete-solution handoff, and `final` for Stage 3. Strategist resume still derives its target from persisted `result.json`; template resume derives it from `template_selection.json`.
+- `--complete-template-phase` is agent-only. It validates the current selection and writes the bound `template_handoff.json`; template mode additionally requires project-local `templates/design_spec.md`. Run it before writing Stage 1. `--reset-template-phase` removes exactly `template_selection.json` and `template_handoff.json`; it does not alter options, Strategist files, installed template content, or `result.json`.
- `--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.
-- Refuses to start unless the recommendation file expected from `result.json` exists (initially `<project_path>/confirm_ui/recommendations.stage1.json`; `--shutdown` needs no recommendations).
+- Initial Step-3 launch requires valid `<project_path>/confirm_ui/template_options.json`. After template selection, the same service exposes Stage 1 only when a matching handoff exists and the Stage-1 recommendation is no older than that handoff. Compatibility launches without a template phase still require the recommendation file expected from `result.json`; `--shutdown` needs neither input.
- 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/recommendations` and `/api/confirm` strip legacy `template_reuse_scope` and `template_adherence` fields. Those exporter values are never user-facing controls; an active template instead exposes the editable natural-language `template_application` field in Stage 2.
+- `/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. Those exporter values are never user-facing controls; an installed template instead exposes editable natural-language `template_application` in Stage 2.
Dependency:
@@ -103,8 +129,138 @@ Dependency:
pip install flask
```
+## Step-3 template-selection contract
+
+Template selection is a separate pre-Strategist phase. Its files live under
+`<project_path>/confirm_ui/` but never enter `result.json`.
+
+### Input — `template_options.json` (created before launch)
+
+```json
+{
+ "schema_version": 1,
+ "phase": "template",
+ "lang": "zh",
+ "explicit_workspace_roots": [
+ "/absolute/path/to/a/project-or-template-workspace"
+ ]
+}
+```
+
+- `schema_version` is exactly `1`; `phase` is exactly `template`.
+- `lang` is optional, but when present it is a non-empty UI-language string.
+- `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`.
+- Do not write library entries into this file. The server reads only
+ `templates/brands/brands_index.json`,
+ `templates/styles/styles_index.json`,
+ `templates/layouts/layouts_index.json`, and
+ `templates/decks/decks_index.json`, derives each direct-child workspace root,
+ and validates that it exists with `templates/design_spec.md`. It never scans
+ kind directories.
+
+`GET /api/template-options` returns the browser catalog:
+
+```json
+{
+ "schema_version": 1,
+ "phase": "template",
+ "lang": "zh",
+ "library": {
+ "brand": [],
+ "style": [],
+ "layout": [],
+ "deck": []
+ },
+ "explicit": [],
+ "preselected_keys": [],
+ "options_sha256": "<64 lowercase hex characters>"
+}
+```
+
+A library candidate has `key`, `source: "library"`, `kind`, `id`, `label`,
+`summary`, and canonical absolute `workspace_root`. An unregistered explicit
+candidate has `key`, `source: "explicit"`, `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`.
+
+### Output — `template_selection.json` (written on confirmation)
+
+```json
+{
+ "schema_version": 1,
+ "phase": "template",
+ "status": "confirmed",
+ "mode": "templates",
+ "selections": [
+ {
+ "source": "library",
+ "kind": "style",
+ "id": "example_style",
+ "workspace_root": "/canonical/library/root/example_style"
+ },
+ {
+ "source": "explicit",
+ "workspace_root": "/canonical/unregistered/workspace/root"
+ }
+ ],
+ "options_sha256": "<64 lowercase hex characters>",
+ "selection_sha256": "<64 lowercase hex characters>",
+ "confirmed_at": "2026-08-04T12:00:00"
+}
+```
+
+`mode: "free_design"` requires `selections: []`; `mode: "templates"` requires
+at least one selection. Roots are unique canonical absolute paths. A library
+selection contains exactly `source`, `kind`, `id`, and `workspace_root`; an
+explicit selection contains exactly `source` and `workspace_root`. The browser
+cannot submit arbitrary paths because the server resolves posted keys against
+the catalog it just built. `options_sha256` binds the receipt to the current
+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. 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
+```
+
+The command writes, and agents must not hand-author:
+
+```json
+{
+ "schema_version": 1,
+ "phase": "template",
+ "status": "ready",
+ "mode": "templates",
+ "selection_sha256": "<64 lowercase hex characters>",
+ "completed_at": "2026-08-04T12:01:00"
+}
+```
+
+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.
+
## Field shapes
+The following fields belong to the Strategist stages after Step 3, 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.
- **Visual examples for hard-to-name choices** — the full-screen confirmation page loads real SVG page samples from `static/style_previews/` for `visual_style`, and renders real sample SVGs from `templates/icons` for `icons`. These thumbnails make style and icon-library choices visually comparable before the user locks them. Preview copy is fixed role text (big title / section title / body / points), not project content from recommendation files, so users compare visual treatment rather than copywriting. These previews are a confirmation aid only: they do not add fields to recommendation stage files or `result.json`, and they do not replace the later Step 6 live preview.
- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. A confirmed non-`none` set is the allowed acquisition-source boundary, not a requirement to use every selected source; only explicit `image_notes` wording can require a source, asset, or page role. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
@@ -125,11 +281,21 @@ 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/`.
+Round-trip and session files live under `<project_path>/confirm_ui/`. The
+Step-3 files (`template_options.json` / `template_selection.json` /
+`template_handoff.json`) close before the Strategist pair
+(`recommendations.stageN.json` / `result.json`) begins.
### Three-stage flow
-The page runs as a **three-stage wizard in one browser session**. 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 filename from `result.json`.
+After template selection and project-local installation, the same page runs a
+**three-stage Strategist wizard in one browser session**. Each stage has its own
+Strategist-authored file and top-level `"stage"` selector. The active,
+unconfirmed stage may be overwritten any number of times when the user asks for
+a better recommendation; refresh the page to load the replacement. Once the
+user confirms it, normal progression writes the next stage file rather than
+repurposing the previous one. The server derives the active Strategist filename
+from `result.json`; `template_selection.json` is its separate prerequisite.
| Recommendation file | Declared stage | Page renders | Button | On submit |
|---|---|---|---|---|
@@ -138,11 +304,37 @@ The page runs as a **three-stage wizard in one browser session**. Each stage has
| `recommendations.stage3.json` | `"stage3"` | production only — confirmed image-source summary, conditional AI acquisition path, formula policy, proactive notes / custom-animation / narration-audio toggles, generation mode, Design Spec review toggle | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
| `recommendations.json` | stage or legacy no-stage payload | read-only compatibility when no stage-specific file exists | matching legacy behavior | preserves the former staged or single-pass behavior; new projects never create this file |
-The AI launches Stage 1, authors the complete Stage-2 solution once from the user's actual contract, then authors Stage-3 production mechanics once from the confirmed solution. An edit inside the current stage never requests another recommendation. The page preserves earlier answers across transitions. `GET /api/session` is the waiting-state endpoint; `GET /api/recommendations` is `no-store`, and the server folds confirmed earlier-stage choices back into later payloads so refresh / reopen restores the user's actual values—including Stage-2 color, typography, icon, image-source, and rendering choices. Once any stage-specific file exists, the server ignores legacy `recommendations.json` to prevent mixed lifecycles.
-
-**Stage progression guard.** Stages confirm strictly in order. `/api/confirm` accepts only the submit stage matching the active filename and its required predecessor; the declared `stage` must also match the filename. A later file that skips ahead (for example `recommendations.stage3.json` while only Stage 1 is confirmed and Stage 2 is absent) is never rendered: `/api/session` keeps reporting `waiting_agent` with `stage_skip: true`, and `--wait` / `--wait-only` exit `2` if a result skips the stage being awaited. An active template does not exempt Stage 2: its recommendations must include `template_application.value`, and an installed workspace or that field disables the no-stage legacy single-pass path. Legacy single-pass remains available only for non-template compatibility payloads.
-
-### Input — `recommendations.stage1.json` (created by Strategist before launch)
+The AI launches the template phase, applies its confirmed receipt, and only then
+authors Stage 1. It authors the complete Stage-2 solution once from the user's
+actual communication contract, then authors Stage-3 production mechanics once
+from the confirmed solution. An edit inside the current stage never requests
+another recommendation. The page preserves earlier answers across transitions.
+`GET /api/session` reports `phase: "template"` until selection closes, its
+bound handoff is ready, and a fresh Stage-1 file exists; only then does it
+report `phase: "strategist"`. `GET /api/recommendations`
+is `no-store`, and the server folds confirmed earlier-stage choices back into
+later payloads so refresh / reopen restores the user's actual values—including
+Stage-2 color, typography, icon, image-source, and rendering choices. Once any
+stage-specific file exists, the server ignores legacy `recommendations.json`
+to prevent mixed lifecycles.
+
+**Progression guard.** Stage 1 must not be exposed while
+`template_options.json` exists without a valid confirmed
+`template_selection.json`. After confirmation the session requires a valid
+`template_handoff.json` bound to that selection and a Stage-1 recommendation
+no older than the handoff. Strategist stages then confirm
+strictly in order. `/api/confirm` accepts only the submit stage matching the
+active filename and its required predecessor; the declared `stage` must also
+match the filename. A later file that skips ahead (for example
+`recommendations.stage3.json` while only Stage 1 is confirmed and Stage 2 is
+absent) is never rendered: `/api/session` keeps reporting `waiting_agent` with
+`stage_skip: true`, and `--wait` / `--wait-only` exit `2` if a result skips the
+stage being awaited. An installed template does not exempt Stage 2: its
+recommendations must include `template_application.value`, and an installed
+workspace or that field disables the no-stage legacy single-pass path. Legacy
+single-pass remains available only for non-template compatibility payloads.
+
+### Input — `recommendations.stage1.json` (created after Step 3 installation)
```json
{
@@ -266,7 +458,7 @@ After Stage 2 is confirmed, create `recommendations.stage3.json` with production
- `custom_candidates` is recommendation-only. Mode / style carry localized `name` + `behavior`; conditional image strategy also carries `rendering: "custom"`, `visual`, and `mood`. When a proposal combines or borrows existing catalog entries, the visible behavior names every exact id and Strategist reads every corresponding file before authoring it; a genuinely novel proposal names none. The server rejects missing required candidates; the UI shows full copy, edits it only after selection, rejects a selected blank, and omits unselected candidates from `result.json`. Template-backed proposals obey inherited identity, prototype capacity, and `template_application`.
- Seed `audience`, `communication_intent`, `audience_outcome`, and `delivery_context` when evidence supports them; users need not supply them, and every Stage-1 prose field may end blank. The contract and `primary_language` stay in `result.json` and `design_spec.md`; `spec_lock.md communication` receives `primary_language`, compact `audience` / `objective` / `core_message`, and reading mode. `communication_intent` may preserve multiple purposes and priority/sequence; never add a `primary_job` enum.
- Do not write `recommend.template_reuse_scope` or `recommend.template_adherence`. Strategist records those internal exporter values later in `spec_lock.md` after inspecting the actual template and current content.
-- For an active template workspace, write one editable prose field as top-level `template_application.value`. It summarizes actual page/prototype use and preservation/reorganization decisions. Omit it for free design. The UI returns the current string through Stage 2, Stage 3, and final confirmation; Strategist then persists the final effective plan as `- **Template Application**: ...` in `design_spec.md §I`, which Executor reads from the retained Design Spec. Never replace it with internal reuse/adherence ids or a fixed option menu.
+- For an installed template workspace, write one editable prose field as top-level `template_application.value`. It summarizes **how to use** the already selected project-local template: actual page/prototype use and preservation/reorganization decisions. It never chooses, changes, or reinstalls a workspace. Omit it for free design. The UI returns the current string through Stage 2, Stage 3, and final confirmation; Strategist then persists the final effective plan as `- **Template Application**: ...` in `design_spec.md §I`, which Executor reads from the retained Design Spec. Never replace it with internal reuse/adherence ids or a fixed option menu.
- `recommend.image_usage` should be an array of source ids when more than one source applies, e.g. `["ai", "provided"]`. A single string is still accepted for backward compatibility. Do not write bare `"custom"` and do not encode a mixed-source plan as prose here; write the prose to top-level `image_notes.value`.
- `image_notes` is the initial strategy note shown under the image source chips. Use it for page-role guidance and constraints: which source applies where, what to avoid, which user assets are authoritative, how realistic / abstract the imagery should be, and what can remain as placeholders. It is intent guidance, not a separate finite option.
- When confirmed Stage-2 `image_usage` includes `ai`, Stage 3 sets `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`. Stage 2 never asks for the acquisition mechanism while the user is still deciding the image role.
@@ -319,13 +511,27 @@ After Stage 2 is confirmed, create `recommendations.stage3.json` with production
}
```
-The shape above is final. 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 `true`; Strategist owns the effective dependency resolution described above. Selected custom values use `mode: custom` + `mode_behavior`, `visual_style: custom` + `visual_style_behavior`, or `image_strategy.rendering: custom` + `behavior`. During Design Spec and lock authoring, Strategist projects optional `mode_references`, `visual_style_references`, or `image_rendering_references` only when that confirmed behavior actually uses named catalog sources; genuinely novel custom behavior has no reference list. Intermediate writes retain accumulated fields; legacy tier names remain read-compatible.
+The 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
+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
+`true`; Strategist owns the effective dependency resolution described above.
+Selected custom values use `mode: custom` + `mode_behavior`, `visual_style:
+custom` + `visual_style_behavior`, or `image_strategy.rendering: custom` +
+`behavior`. During Design Spec and lock authoring, Strategist projects optional
+`mode_references`, `visual_style_references`, or
+`image_rendering_references` only when that confirmed behavior actually uses
+named catalog sources; genuinely novel custom behavior has no reference list.
+Intermediate writes retain accumulated fields; legacy tier names remain
+read-compatible.
**Final-result consumption contract.** A final result is the user-confirmed input contract for the Strategist's Design Spec, not another recommendation input. After the final wait, Generate Step 4 reads the complete final object exactly once and retains it while Strategist writes and audits `design_spec.md` against every explicitly present field. Normal lock authoring and downstream execution do not reopen `result.json`; the completed Design Spec is the durable authority. Only after that audit passes does Strategist author `spec_lock.md` from the Design Spec plus current execution context, selecting stable anchors and routing rather than copying every field or enumerating every legal color/font. Every value must be consumed at the semantic type owned by [`strategist.md`](../../references/strategist.md) §1 and its field owner: do not omit or substitute it, and do not silently strengthen or weaken its type. If a confirmed requirement cannot be honored, the owning workflow reports or pauses under failure recovery; it never deletes the requirement to keep the pipeline moving.
- Bespoke mode / style prose lives only in the required behavior sibling; image custom prose lives in `image_strategy.behavior`. Canvas / icons retain free-text edge cases, color / typography retain `name: "custom"`, and image usage remains a source-id array plus `image_notes`.
- `image_ai_path` and `image_strategy` appear only with `image_usage: ai` and remain confirmed downstream. The page is default; explicit/failure chat fallback keeps identical fields. `image_ai_path` selects the Step 5 path, and [`strategist-image.md`](../../references/strategist-image.md) §2 retains the selected rendering or custom behavior as the deck-level image identity anchor; individual prompts still adapt subject, composition, and atmosphere within it.
-- After the user clicks the **final Confirm** (Stage 3, or single-pass), the page saves `result.json` and shuts the server down (auto-close). Stage-1 **Confirm contract & continue** and Stage-2 **Confirm solution & continue** keep the page open while it polls for the downstream stage file. The default flow is `--daemon` → Stage-1 chat handoff → `--wait-only --wait-stage stage1` → Stage-2 wait → final wait; the AI reads each result immediately. Chat fallback mirrors the same preset/custom choices. Either way, Step 4 ends with `--shutdown` so a never-confirmed page cannot retain its selected port ahead of Step 6 live preview.
+- Step-3 **Confirm template & continue** writes `template_selection.json` and keeps the page open while the agent applies the choice. The agent then runs `--complete-template-phase` and writes fresh Stage 1. Stage-1 **Confirm contract & continue** and Stage-2 **Confirm solution & continue** likewise keep polling for the downstream file. The final Stage-3 Confirm saves `result.json` and shuts the server down (auto-close). The default flow is `template_options.json` → `--daemon` → template chat handoff → `--wait-only --wait-stage template` → installation/free-design closure → `--complete-template-phase` → fresh Stage-1 handoff/wait → Stage-2 wait → final wait. The AI reads each receipt at its owning boundary. Chat fallback mirrors the same choices. Either way, Step 4 ends with `--shutdown` so a never-confirmed page cannot retain its selected port ahead of Step 6 live preview.
## Scope
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 6509b359..2a192881 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -314,7 +314,7 @@
"skills/ppt-master/workflows/stages/apply-template-workspace.md",
"skills/ppt-master/templates/README.md"
],
- "max_tokens": 4500
+ "max_tokens": 5000
},
"stage.generate.template.brand": {
"description": "Conditional Brand workspace application with one selected Brand spec.",
@@ -341,7 +341,7 @@
"files": [
"skills/ppt-master/templates/styles/README.md"
],
- "max_tokens": 5750
+ "max_tokens": 6500
},
"stage.generate.template.layout": {
"description": "Conditional Layout workspace application with one selected Layout spec.",
diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.md
index 5674be12..84bfaa2d 100644
--- a/skills/ppt-master/templates/README.md
+++ b/skills/ppt-master/templates/README.md
@@ -39,15 +39,22 @@ which keeps the fixed route name and dispatches exactly one child workflow:
[`Create Layout`](../workflows/create-template/create-layout.md), or
[`Create Deck`](../workflows/create-template/create-deck.md).
-The indexes are discovery aids only. [`generate-pptx`](../workflows/generate-pptx.md)
-Step 3 activates a template only from an explicit workspace-root path supplied
-by the user or an exact validated Create Template handoff.
+The four indexes are the complete library-discovery source for
+[`generate-pptx`](../workflows/generate-pptx.md) Step 3. The default page shows
+their registered entries alongside free design and any exact workspace roots
+supplied for the run; it never scans the four directories or fuzzy-matches a
+bare name. An exact root that matches a registered index entry may be displayed
+as `library`; an unregistered root remains `explicit`. After confirmation,
+[`apply-template-workspace`](../workflows/stages/apply-template-workspace.md)
+validates, fuses, and installs every selected workspace into the current
+project before Stage 1 starts. Later roles read only that project-local copy.
## Orthogonal contracts
| Axis | Values | Meaning |
|---|---|---|
| Template kind | `brand` / `style` / `layout` / `deck` | Which reusable contract the package owns: identity, direction/method, brand-neutral structure, or a complete recurring application |
+| Selection source | `library` / `explicit` | Step-3 discovery provenance only: exact index-derived root or exact unregistered root; it does not change template semantics |
| 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. |
@@ -77,12 +84,14 @@ 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. Brand/Layout/Deck consume package-owned
+stage owns installation and fusion during the independent Step-3 selection
+phase. 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
readable; Style has no legacy-flat form, and directory shape alone does not
-indicate legacy Master/Layout semantics.
+indicate legacy Master/Layout semantics. Strategist and all later consumers use
+the installed project-local files, never the original library or explicit root.
## Design specification references
diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.md
index d1aab020..4be3c607 100644
--- a/skills/ppt-master/templates/brands/README.md
+++ b/skills/ppt-master/templates/brands/README.md
@@ -10,13 +10,17 @@ lives in the parent [`README.md`](../README.md).
## How brands are consumed
-Brand application follows the common explicit-path trigger in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The conditional
+Brand application follows the independent selection phase in
+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
+lists registered brands only from `brands_index.json`, alongside exact
+workspace roots supplied for this run; it never scans this directory or
+fuzzy-matches a bare brand name. An exact supplied root that matches a
+registered root may be labelled `library`, while an unregistered root remains
+`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. This file owns only the Brand
-schema. `brands_index.json` is discovery-only; listing brands never advances
-the pipeline.
+same-kind conflict resolution, and provenance before Stage 1. Later roles read
+only the installed project-local copy. This file owns only the Brand schema.
## Creating a new brand
@@ -51,4 +55,8 @@ Logo filenames are descriptive, not contractual — `templates/design_spec.md`
[brands_index.json](./brands_index.json) is a slim machine-readable map (`brand_id → { summary, primary_color }`). Refresh it with `register_template.py --kind brand <brand_id>` after a brand is created or edited. Registration rejects incomplete frontmatter, mismatched IDs, page SVGs, missing required identity sections, invalid or inconsistent colors/provenance, and broken workspace-local asset references.
-Listing the index does not trigger any pipeline action — Generate Step 3 triggers only on an explicit directory path supplied by the user or an exact validated Create Template handoff, regardless of whether the brand appears in the index.
+The default Step-3 page reads this index as its complete registered-brand
+catalog; chat discovery reads the same file and returns exact workspace roots.
+Choosing an entry and confirming it triggers installation. Exact directory
+paths and validated Create Template handoffs remain supported, while a bare ID
+never resolves implicitly.
diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.md
index 9e7b0aa7..8ce25a4e 100644
--- a/skills/ppt-master/templates/decks/README.md
+++ b/skills/ppt-master/templates/decks/README.md
@@ -31,12 +31,19 @@ Overview when application fit must be judged in detail.
## Trigger and fusion
-Selection uses the common explicit-path trigger in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. Supplying a bare ID
-or reading the discovery index does not trigger template use. The conditional
+Selection uses the independent phase in
+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
+lists registered Decks only from `decks_index.json`, alongside exact workspace
+roots supplied for this run; it never scans this directory or fuzzy-matches a
+bare ID. An exact supplied root that matches a registered root may be labelled
+`library`, while an unregistered root remains `explicit`. Choosing and
+confirming an entry triggers the conditional
[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)
-stage owns path normalization, compatibility checks, installation, and fusion.
-This file owns the Deck schema and application-context boundary.
+stage, which owns path normalization, compatibility checks, installation, and
+fusion before Stage 1. Later roles read only the installed project-local copy.
+This file owns the Deck schema and application-context boundary. Chat discovery
+reads the same index and returns exact roots; a bare ID never resolves
+implicitly.
---
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index 99f7420e..b24742b2 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -46,12 +46,19 @@ kind of rule is never a mirror operation.
## Trigger and identity boundary
-Selection uses the common explicit-path trigger in
-[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. Supplying a bare ID
-or reading the discovery index does not trigger template use. The conditional
+Selection uses the independent phase in
+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
+lists registered Layouts only from `layouts_index.json`, alongside exact
+workspace roots supplied for this run; it never scans this directory or
+fuzzy-matches a bare ID. An exact supplied root that matches a registered root
+may be labelled `library`, while an unregistered root remains `explicit`.
+Choosing and confirming an entry triggers the conditional
[`apply-template-workspace`](../../workflows/stages/apply-template-workspace.md)
-stage owns path normalization, compatibility checks, installation, and fusion.
-This file owns the Layout schema and its identity/application boundary.
+stage, which owns path normalization, compatibility checks, installation, and
+fusion before Stage 1. Later roles read only the installed project-local copy.
+This file owns the Layout schema and its identity/application boundary. Chat
+discovery reads the same index and returns exact roots; a bare ID never resolves
+implicitly.
---
diff --git a/skills/ppt-master/templates/styles/README.md b/skills/ppt-master/templates/styles/README.md
index d4acf035..faf13901 100644
--- a/skills/ppt-master/templates/styles/README.md
+++ b/skills/ppt-master/templates/styles/README.md
@@ -17,7 +17,16 @@ These names are separate contracts. Style-only and Style + Brand naturally produ
## Trigger, Precedence, and Fusion
-Selection uses the common explicit-path trigger in [`generate-pptx`](../../workflows/generate-pptx.md) Step 3. A bare Style name, consulting label, or ordinary visual description remains a brief or catalog signal and does not activate this workspace. `styles_index.json` is discovery-only.
+Selection uses the independent phase in
+[`generate-pptx`](../../workflows/generate-pptx.md) Step 3. The default page
+lists registered Styles only from `styles_index.json`, alongside exact
+workspace roots supplied for this run; it never scans this directory or
+fuzzy-matches a bare Style name. An exact supplied root that matches a
+registered root may be labelled `library`, while an unregistered root remains
+`explicit`. A consulting label or ordinary visual description remains a brief
+or catalog signal and does not activate this workspace. Confirmation runs the
+common installation/fusion stage before Stage 1; later roles read only the
+project-local copy.
| Decision | Precedence |
|---|---|
@@ -80,4 +89,9 @@ Do not create empty `images/`, `icons/`, or `exports/` directories. Existing ini
2. Validate with `svg_quality_checker.py --template-mode`.
3. In library scope, register with `register_template.py <id> --kind style`.
-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 and never activates Generate Step 3.
+The discovery source of truth is [`styles_index.json`](./styles_index.json).
+Each entry is `style_id → { summary, keywords }`; the index never duplicates
+the full method or defaults. The default Step-3 page reads this file as its
+complete registered-Style catalog, and chat discovery returns exact roots from
+the same entries. Choosing and confirming an entry activates installation;
+reading a name in ordinary prose does not.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index feb425bc..b26513af 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -835,7 +835,15 @@ The Layout/Deck completion card's file roster is collected by globbing
`templates/*.svg` in the workspace. Brand/Style cards are spec-only. Legacy
flat Layout/Deck packages still use their root `*.svg` roster.
-The index file is a **discovery index** — it lets the AI answer "what templates are available?" by listing names and workspace-root paths. It is **not** consulted to trigger [`generate-pptx`](./generate-pptx.md) Step 3. Step 3 triggers on an explicit workspace-root path supplied by the user, regardless of whether that path is registered. An unregistered workspace still works when the user gives its path; it just will not appear in discovery listings.
+The index file is the complete **registered-library discovery source** for
+[`generate-pptx`](./generate-pptx.md) Step 3. The default template-selection
+page reads only the four kind indexes, and chat discovery uses the same entries
+to list exact workspace-root paths; neither path scans template directories.
+Selecting and confirming a registered entry activates installation. An exact
+unregistered workspace still works when supplied by the user or handed off by
+this route, but remains labelled `explicit` and does not appear in the library
+catalog. If an explicit root exactly matches a registered canonical root, it
+may be displayed as `library`. Bare names are never resolved implicitly.
> **Recommended for new templates**: declare a YAML frontmatter block at the top of `design_spec.md`. The registrar prefers it over prose extraction:
>
@@ -899,7 +907,9 @@ The index file is a **discovery index** — it lets the AI answer "what template
> python3 skills/ppt-master/scripts/register_template.py --kind layout --rebuild-all
> ```
-README files describe each kind in prose only — they do not list templates. Discovery happens against the JSON index file; the registrar does not touch READMEs.
+README files describe each kind in prose only — they do not list templates.
+Both the default Step-3 selector and chat discovery read the JSON index files;
+the registrar does not touch READMEs.
---
@@ -960,7 +970,7 @@ The next Generate PPTX Step 3 input is the exact `<template_workspace>/` root in
2. **Color consistency**: Create Deck SVG files must use the same color scheme as `design_spec.md §II Color Scheme`; Create Layout owns no identity colors, Create Style owns only overrideable visual defaults, and Create Brand/Create Style own no SVG files
3. **Native-object mapping**: Treat Theme/Master/Layout/Placeholder as compiled PowerPoint objects, not template kinds. Layout owns topology and placement, Brand owns identity values/assets, Style owns portable direction/method defaults, and Deck adds descriptive recurring-application context.
4. **Placeholder convention**: `{{}}` format only; default names listed in [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). Override per template via `placeholders:` frontmatter when needed.
-5. **Discovery requirement**: A library template is discoverable only after `register_template.py` has been run against it (Step 7). A project-scoped workspace intentionally stays out of global discovery and is consumed by its explicit workspace-root path.
+5. **Discovery requirement**: A library template appears in the default Step-3 selector and chat discovery only after `register_template.py` has updated its kind index (Step 7). A project-scoped workspace intentionally stays out of the library catalog and is consumed as an exact `explicit` workspace-root handoff. In both cases Step 3 confirms the choice and installs the workspace before Stage 1.
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 c5165b24..ac529324 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] → Strategist Structured Plan → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export`
+**Default Core Pipeline**: `Initial Materials → [Fact Research] → Create Project → Template Selection & Installation → Strategist Structured Plan → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export`
**Generate-specific execution discipline**:
@@ -52,7 +52,7 @@ template reuse still requires the default lock-backed pipeline.
| 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 |
-| Explicit template workspace | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) | Owns Step 3 validation, installation, and fusion; load only when Step 3's explicit-path trigger fires |
+| 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 |
## Workflow
@@ -143,30 +143,71 @@ Direct supported bitmap inputs follow both boundaries: the original is archived
---
-### Step 3: Template Option
+### Step 3: Template Selection and Installation
-🚧 **GATE**: Step 2 complete; project directory structure is ready.
+🚧 **GATE**: Step 2 complete; the project workspace exists. Finish this phase before authoring or confirming Stage 1. Template selection is not part of the Stage-1 communication contract.
-**Default — free design**: Proceed directly to Step 4. Do not query any `*_index.json`, ask about templates, suggest a local template, or fuzzy-match a name from content, brand mentions, or style language.
+**Default UI phase**: When the selected confirmation surface is the page, open its template-selection phase first. Offer free design plus registered Brand/Style/Layout/Deck workspaces from exactly these discovery sources:
-**Explicit-path trigger only**: Load and run [`apply-template-workspace.md`](./stages/apply-template-workspace.md) only when either condition is true:
+- `templates/brands/brands_index.json`
+- `templates/styles/styles_index.json`
+- `templates/layouts/layouts_index.json`
+- `templates/decks/decks_index.json`
-- The user supplied one or more explicit workspace-root paths.
-- Create Template completed in the current conversation and handed off its exact validated workspace root.
+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. 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; every selected root passes the same validation.
-Bare names, style descriptions, brand mentions, vague template intent, and silence do not trigger the runbook. There is no slug lookup or fuzzy path resolution.
+**UI branch — executable sequence**: Resolve the confirmation surface under
+[`confirm_ui.md`](../scripts/docs/confirm_ui.md) before the first command. For
+the default page branch, write
+`<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:
-**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.
+```bash
+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 one
+or more server-resolved exact roots with `source: "library"|"explicit"`. 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 fusion/collisions, and installs one project-local template state under `<project_path>/templates/` plus any real `<project_path>/images/` and `<project_path>/icons/` assets. Do not proceed until installation completes. Strategist 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:
-> “What templates exist?” is out-of-band Q&A. List indexed workspace paths, then stop; listing does not trigger Step 3. The user must send an explicit path.
+```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 rejects a Stage-1 file older than the handoff. Do not
+write the handoff manually.
+
+**Explicit-path and chat compatibility**: Preserve the existing exact-workspace-root path. An explicit root supplied in the request, selected in chat, or handed off by Create Template may be applied directly after the user confirms it; no index membership is required. The chat branch mirrors the same free-design-versus-root decision without launching the page. A bare name remains ordinary brief text and never triggers slug lookup or fuzzy resolution. When the user asks what is available in chat, list only the four indexes and require an exact returned root before installation.
+
+**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**: Free design selected without loading template details, or the conditional template runbook completed and `<project_path>/templates/` plus any portable assets are ready.
+**✅ Checkpoint**: The user confirmed free design, or every selected workspace passed validation/fusion and its complete consumed state now exists under the target project. In the UI branch, the matching `template_handoff.json` is ready; in the chat/delegated branch, the equivalent selection and installation state is retained in context without fabricating UI receipts. Proceed to Step 4 and author fresh Stage 1.
---
### Step 4: Strategist Phase (MANDATORY in the default pipeline)
-🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied or confirmed in place in the project.
+🚧 **GATE**: Step 3 selection is confirmed; free design is active, or the selected template state is validated and installed in the project. Stage 1 has not started before this point.
First, read the role core, then only the modules triggered by the current plan:
```
@@ -175,10 +216,10 @@ Read references/strategist.md
| Deterministic trigger | Additional Strategist reference |
|---|---|
-| Step 3 installed an explicit Brand/Style/Layout/Deck workspace | `references/strategist-template.md` |
+| Step 3 installed a selected Brand/Style/Layout/Deck workspace into this project | `references/strategist-template.md` |
| 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. Bare template/style names do not load the template module.
+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; a bare template/style name does not.
> ⚠️ **Mandatory artifact gates**: after final confirmation, author complete `design_spec.md` from `${SKILL_DIR}/templates/design_spec_reference.md`. After Gate 1 and any refinement approval, author `spec_lock.md` from `${SKILL_DIR}/templates/spec_lock_reference.md` plus approved Design Spec/context. Author each new artifact once without placeholders or `scaffold-*` (manual-only). Schema validity does not prove semantic fidelity.
@@ -190,39 +231,44 @@ 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**: Unless explicitly delegated, the three-stage Strategist confirmation is the single always-on user gate. An enabled `refine_spec` adds the one conditional chat gate after Design Spec Gate 1. In the UI branch, keep Stage 1/2 handoffs in one turn and author the next stage after each wait. In the chat branch, wait for an explicit user response at each stage. Author each stage once; submitted values—including blanks or unusual overrides—are authoritative.
-
-**Confirmation ownership and surface**: Only the user confirms. Before any
-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 `--daemon`, every `--wait-only`, and UI `result.json`. Explicit delegation
-is a separate higher-priority branch. With no surface instruction, fresh Stage
-1 uses the default UI branch: launch, post the required chat handoff, then wait.
-A chat-question tool alone does not replace that default. The agent may write
-recommendations, operate the server, and read state, but MUST NOT call
-`/api/confirm`, automate submission, synthesize a payload, or write/replace
-`result.json`. Delegation applies only to this run: show the complete
+⛔ **BLOCKING**: After Step 3 closes, the three-stage Strategist confirmation is the remaining always-on user gate unless explicitly delegated. Template selection is the earlier independent Step-3 gate, not Stage 1. An enabled `refine_spec` adds the one conditional chat gate after Design Spec Gate 1. In the UI branch, keep Stage 1/2 handoffs in one turn and author the next stage after each wait. In the chat branch, wait for an explicit user response at each stage. Author each stage once; submitted values—including blanks or unusual overrides—are authoritative.
+
+**Confirmation ownership and surface**: Only the user confirms. Before Step 3's
+template-selection phase or any server command, apply `confirm_ui.md`'s surface
+decision to this run's most recent explicit surface instruction and retain that
+branch as the owner specifies. A natural-language request or agreement to
+personally confirm in chat, or to avoid the page, selects the chat branch without
+a magic keyword; skip UI launch/wait commands and UI-authored result state.
+Explicit delegation is a separate higher-priority branch. With no surface
+instruction, Step 3 uses the default UI branch, closes template selection and
+installation, then exposes fresh Stage 1. A chat-question tool alone does not
+replace that default. The agent may author recommendations, operate the server,
+read state, and apply the selected template, but MUST NOT confirm on the user's
+behalf, automate submission, synthesize a payload, or write/replace user result
+state. Delegation applies only to this run: show the complete selection plus
three-stage summary and never fabricate UI results. Silence confirms nothing.
**UI branch files and completion evidence:**
-| Stage file (the active unconfirmed stage may be overwritten) | Strategist writes | Completion evidence |
+| Input file (only the active unconfirmed Strategist stage may be overwritten) | Agent writes | Completion evidence |
|---|---|---|
+| `confirm_ui/template_options.json` | Step-3 schema/language plus exact explicit roots; library entries remain server-owned index data | User-owned `template_selection.json` with `phase: template`, `status: confirmed` |
+| `confirm_ui/template_handoff.json` | Only through `--complete-template-phase`, after free-design closure or successful project-local installation | `status: ready`, bound to the current selection hash |
| `confirm_ui/recommendations.stage1.json` | Communication contract, `content_divergence`, and canvas only | `status: stage1-confirmed` |
| `confirm_ui/recommendations.stage2.json` | Complete deck solution from the confirmed contract; never skip for a template | `status: stage2-confirmed` |
| `confirm_ui/recommendations.stage3.json` | Production mechanics only: conditional AI path, formula policy, generation mode, refine-spec, proactive speaker notes, custom animations, and narration audio | `stage: final`, `status: confirmed` |
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** — create `confirm_ui/recommendations.stage1.json`, then:
+**UI branch only** — Step 3 has already launched the page, received
+`template_selection.json`, completed its bound `template_handoff.json`, and
+left the server live. Create
+`confirm_ui/recommendations.stage1.json`, post the required Stage-1 summary and
+chat fallback using the already printed URL, then:
1. Run in order:
```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon
- # Post confirm_ui.md's actual URL + Stage-1 summary/chat fallback here.
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1
```
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index dd903aec..9f7a1f6d 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -30,7 +30,7 @@ route selection. After selection, the route authority owns execution.
| Route | Request shape | Authority | Preconditions | Mutation model | Output contract |
|---|---|---|---|---|---|
-| Generate PPTX | Create a new presentation; regenerate an existing deck visually; use source material or a topic; optionally apply an explicit template workspace | [`generate-pptx`](./generate-pptx.md) | Source facts exist or research can gather them; explicit quick intent activates its profile | Author new SVG pages and export a new PPTX | Default: spec, lock, SVG, validation, and PPTX; Quick: optional source/resource artifacts, no spec/lock, SVG, and one PPTX |
+| Generate PPTX | Create a new presentation; regenerate an existing deck visually; use source material or a topic; optionally select a registered library template or supply an explicit workspace | [`generate-pptx`](./generate-pptx.md) | Source facts exist or research can gather them; explicit quick intent activates its profile | Author new SVG pages and export a new PPTX | Default: spec, lock, SVG, validation, and PPTX; Quick: optional source/resource artifacts, no spec/lock, SVG, and one PPTX |
| Create Template | Create a reusable brand/style/layout/deck template from one or more PPTX/SVG files, images/PDFs, direct or file-based text, documents/websites, brand assets, or a mixed reference bundle | [`create-template`](./create-template.md) | A reusable-template request exists; reference material is optional, and project scope additionally requires an initialized target project | Author a new portable workspace; never modify any reference file in place | Workspace with required `templates/`, optional `images/` / `icons/`, and optional review `exports/` |
| Fill Native PPTX | Use a raw PPTX's native slide shells and replace/fill content | [`template-fill-pptx`](./template-fill-pptx.md) | Source PPTX plus new material/topic | Clone and patch PPTX through OOXML; no SVG pipeline | New filled PPTX in project `exports/` |
| Enhance Native PPTX | Keep a finished PPTX's visible slides stable while adding notes, audio, timings, or transitions | [`native-enhance-pptx`](./native-enhance-pptx.md) | Finished source PPTX exists | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX in project `exports/` |
@@ -45,7 +45,8 @@ route selection. After selection, the route authority owns execution.
| Topic only, or supplied sources leave planning-critical factual gaps | Run [`topic-research`](./stages/topic-research.md) inside the selected Generate profile's source preparation: immediately for topic-only input, or after conversion and reading for source-backed input; research only the identified gaps |
| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through [`generate-pptx`](./generate-pptx.md) Step 1 and its PPTX intake; continue the default pipeline unless explicit Quick Generate intent selected that profile |
| Existing PPTX must preserve wording, page count, and page order 1:1 | Activate the [`beautify-pptx`](./profiles/beautify-pptx.md) profile inside the main pipeline |
-| Explicit current brand/style/layout/deck workspace root | Enter [`generate-pptx`](./generate-pptx.md) Step 3 and conditionally load [`apply-template-workspace`](./stages/apply-template-workspace.md); consume the workspace root, never only its inner `templates/` directory |
+| Default Generate reaches Step 3 | Complete the independent template-selection phase before Stage 1. The UI offers only index-registered library roots plus any user-supplied explicit roots; confirmed non-free selections run [`apply-template-workspace`](./stages/apply-template-workspace.md) |
+| Explicit current brand/style/layout/deck workspace root | Preserve the exact-path path through Step 3. 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 |
@@ -123,15 +124,17 @@ Object animation for generated SVG projects uses the animation stage. Native PPT
---
-## 7. Template Name Boundary
+## 7. Template Selection Boundary
| User input | Behavior |
|---|---|
-| Explicit current workspace root containing `templates/design_spec.md` | Enter [`generate-pptx`](./generate-pptx.md) Step 3 |
+| Default UI reaches Step 3 | Offer free design plus registered library workspaces from the four indexes below; 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?” | List indexed workspace paths as Q&A; do not advance a route |
+| “What templates exist?” in chat | List indexed workspace paths; selection still requires the user to return an exact root |
-For that Q&A only, read the matching discovery indexes:
+The default UI and chat discovery read only these indexes. Never scan the
+corresponding directories to construct or supplement the catalog:
| Kind | Discovery index |
|---|---|
@@ -140,4 +143,13 @@ For that Q&A only, read the matching discovery indexes:
| Layout | [`layouts_index.json`](../templates/layouts/layouts_index.json) |
| Deck | [`decks_index.json`](../templates/decks/decks_index.json) |
-**Forbidden — fuzzy resolution**: Never resolve a bare name to a local template directory on the user's behalf. The explicit workspace root is the only Step 3 template trigger, except the exact validated workspace handed off by Create Template in the current conversation.
+**Hard rule — selection precedes communication confirmation**: Template
+selection is a standalone Step-3 phase. Confirm free design or selected roots,
+run workspace validation/installation, then begin Stage 1. Stage 2
+`template_application` decides how the already installed template is used; it
+never selects 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
+root; an unregistered workspace requires an explicit root, including the exact
+validated workspace handed off by Create Template in the current conversation.
diff --git a/skills/ppt-master/workflows/stages/apply-template-workspace.md b/skills/ppt-master/workflows/stages/apply-template-workspace.md
index a03782ad..2e50971d 100644
--- a/skills/ppt-master/workflows/stages/apply-template-workspace.md
+++ b/skills/ppt-master/workflows/stages/apply-template-workspace.md
@@ -1,14 +1,14 @@
---
-description: Conditional Generate-PPTX runbook for validating, installing, or fusing explicit Brand, Style, Layout, and Deck workspaces.
+description: Generate-PPTX Step-3 runbook for validating, installing, or fusing selected Brand, Style, Layout, and Deck workspaces.
---
# Apply Template Workspace Stage
-> Run only from [`generate-pptx.md`](../generate-pptx.md) Step 3 after the user supplies an explicit workspace-root path, or after Create Template hands off its exact validated workspace root in the current conversation. Never load this stage for free design, a bare template name, a style description, or a brand mention.
+> Run only from [`generate-pptx.md`](../generate-pptx.md) Step 3 after the user confirms one or more library/explicit workspace roots, or after Create Template hands off its exact validated root in the current conversation. Never load this stage for confirmed free design, a bare template name, a style description, or a brand mention. This stage applies a completed selection; it does not move template choice into Stage 1 or Stage 2.
## 1. Gate and Normalize Inputs
-🚧 **GATE**: Every external input resolves to one of these current contracts:
+🚧 **GATE**: Step-3 template selection is confirmed and every selected input resolves to one of these current contracts:
| Input shape | Spec and SVG source | Asset source |
|---|---|---|
@@ -18,6 +18,20 @@ description: Conditional Generate-PPTX runbook for validating, installing, or fu
The spec frontmatter MUST declare `kind: brand`, `kind: style`, `kind: layout`, or `kind: deck`. Do not accept only another project's inner `templates/` directory because that omits sibling assets.
+**Selection-source classification**:
+
+| Source label | Resolution rule |
+|---|---|
+| `library` | The normalized root exactly equals `templates/<kind_dir>/<id>/` derived from an entry in that kind's `*_index.json` |
+| `explicit` | The user or Create Template supplied an exact workspace root that is not registered at that canonical index-derived root |
+
+Read library choices only from `brands_index.json`, `styles_index.json`,
+`layouts_index.json`, and `decks_index.json`. Never scan kind directories or
+promote an unregistered directory into the UI catalog. An explicit root remains
+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.
+
**Hard rule — raw source boundary**: A raw PPTX is not a Step 3 workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first and return with its validated workspace root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
**Compatibility gate**: Reject semantic-legacy or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved. A legacy-flat 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`.
@@ -77,6 +91,12 @@ For a compatible legacy-flat package, route SVG/spec/non-bitmaps to project `tem
If the normalized source root equals the target project root, consume it in place and copy nothing. An in-place workspace cannot participate in multi-path fusion. Ignore source `exports/`; it contains review artifacts, not portable template inputs. Empty optional roots remain absent.
+**Hard rule — project-local consumer boundary**: After installation/fusion,
+Strategist and every later role read only `<project_path>/templates/` and the
+project-local `images/` / `icons/` pools. The original library or external root
+is installation input, not a later prompt source. If source and target are the
+same project root, that in-place root already satisfies this boundary.
+
Template SVGs are authoring prototypes, not export-time overlays. The generated page remains complete in `svg_output/`; `page_layouts` selects the complete prototype and its explicit structure contract for authoring.
@@ -122,12 +142,12 @@ Write one final `<project>/templates/design_spec.md`. Immediately under its H1,
Single-path installs do not add provenance. Set fused frontmatter `kind` from the non-Style capability: `deck` when identity and structure are both present, `layout` for structure only, or `brand` for identity only. Use `kind: style` only for Style-only input. Adding Style to Brand, Layout, Deck, or Brand + Layout does not change that existing capability label; its Direction / method ownership stays explicit in the fused provenance and body. A project-local Brand + Layout fusion uses `kind: deck` for routing but is not automatically a reusable library Deck; its application remains current-project context.
-**Completion receipt**: Report `roots=<normalized roots>; kinds=<kind per root>; segments=identity:<owner>,structure:<owner>,application:<owner>,direction:<owner>; install=<in-place|copied>; final_spec=<project_path>/templates/design_spec.md`.
+**Completion receipt**: Report `roots=<normalized roots>; sources=<library|explicit per root>; kinds=<kind per root>; segments=identity:<owner>,structure:<owner>,application:<owner>,direction:<owner>; install=<in-place|copied>; final_spec=<project_path>/templates/design_spec.md`.
## ✅ Template Workspace Applied
-- [x] Every input was an explicit root satisfying a listed workspace contract or the exact current Create Template handoff
+- [x] Every selected input was an index-derived library root or an exact explicit/Create Template root satisfying a listed workspace contract
- [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
+- [x] `<project_path>/templates/` and any portable sibling assets are complete and are the only downstream template source
- [ ] **Next**: Return to [`generate-pptx.md`](../generate-pptx.md) Step 4