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(create-template): support project-scoped thin template output

hugohe39f3ad5b70985
diff --git a/docs/faq.md b/docs/faq.md
index 0bff1009..845b20f7 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -252,12 +252,13 @@ Use an AI coding agent (Claude Code, Codex, etc.) and ask it to use the **PPT Ma
- Desired tone and color palette (e.g., "modern and restrained, dark blue primary")
- Category preference (`brand` / `general` / `scenario` / `government` / `special`)
- Canvas format, if not the default 16:9
+- Output scope: indexed `library` (default) or one already initialized `project`
-You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (template ID, theme mode, etc.).
+You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (output scope, template ID, theme mode, etc.).
**Step 3 — Wait for the Result**
-The AI agent will handle the rest — analyzing your screenshots, building the layout definitions, and registering the template so it appears as a selectable option in the PPT Master workflow.
+The AI agent will handle the rest — analyzing your screenshots, building the layout definitions, and validating the template. Library scope registers it so it appears in global discovery. Project scope writes the thin bundle directly into that project's `templates/` root and deliberately skips global registration.
> **Tip**: The more specific you are about the style and use case, the better the generated template will match your expectations.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 36e78657..ef6d2d0c 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -33,14 +33,16 @@ You: Replicate this as a template via /create-template: projects/brand/our_deck.
That runs `pptx_template_import.py` and rebuilds the file into a reusable bundle — layout SVGs + `design_spec.md` + extracted theme colors, fonts, and images. That bundle is what you point to at generation time.
+During the create-template brief, choose `library` (the existing default) or `project`. Project scope requires an initialized target project, verifies the project template root and asset names before writing, then installs the bundle directly into that project without global registration.
+
A created template lives in one of two places:
| Location | Path | Notes |
|---|---|---|
| **Registered in the skill library** | `skills/ppt-master/templates/layouts/<id>/` | Global, reusable across every project; run `register_template.py` so it shows up when you ask "what templates are available?" |
-| **Inside a project** | `projects/<project>/templates/` | Project-local; works by path, no registration needed |
+| **Inside a project** | `projects/<project>/templates/` | Private to that owning project; consumed in place, no registration needed |
-Either way, you invoke it during generation by giving its **directory path** in chat — the workflow triggers on an explicit path only, never on a bare template name:
+For a library package, invoke it during generation by giving its **directory path** in chat. A project-scoped create-template run may hand its exact validated path directly to Step 3 in the same conversation. Both cases stay path-based; a bare template name never triggers. To reuse a project-scoped design in another project, recreate it with `library` scope because its image/icon pools live beside the owning project's template root.
```
You: Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/academic_defense/
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 6c193668..633f57cb 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -84,7 +84,7 @@ The past two months' structural capability growth. Single flags / incremental po
- **`--native-objects` hardened from dormant marker to usable opt-in** — the narrow native-object exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts.pptx` to tell it apart from the default flattened-shape export. **The default route is unchanged** — charts/tables still export as SVG-derived DrawingML shapes for cross-renderer fidelity; native objects stay the deliberate opt-in trade documented under Non-goals below
-- **Native package structure + conservative PPTX object round-trip** — free-design baseline export promotes only safe shared backgrounds/chrome, assigns marker-backed Layout families, and may lift exact family-wide leading structurally marked chrome without inferring placeholders; marker-free legacy SVGs retain filename/id fallback. Template export deterministically compiles complete SVG pages whose Master/Layout/placeholder ownership is explicit and writes locked title/body sizes into Master `p:txStyles` without changing direct slide-run sizes. `create-template` uses imported source structure as analysis input and always rebuilds explicit SVG structure; strict keeps a selected Layout, adaptive may add a new Layout under the same Master. Legacy `preserve` remains compatibility-only. Raw one-off PPTX filling remains `template-fill-pptx`.
+- **Native package structure + conservative PPTX object round-trip** — free-design baseline export promotes only safe shared backgrounds/chrome, assigns marker-backed Layout families, and may lift exact family-wide leading structurally marked chrome without inferring placeholders; marker-free legacy SVGs retain filename/id fallback. Template export deterministically compiles complete SVG pages whose Master/Layout/placeholder ownership is explicit and writes locked title/body sizes into Master `p:txStyles` without changing direct slide-run sizes. `create-template` uses imported source structure as analysis input and always rebuilds explicit SVG structure; strict keeps a selected Layout, adaptive may add a new Layout under the same Master. Its default library output remains indexed, while project scope installs the same thin contract directly into one initialized project's template root with no global registration. Legacy `preserve` remains compatibility-only. Raw one-off PPTX filling remains `template-fill-pptx`.
---
diff --git a/docs/technical-design.md b/docs/technical-design.md
index d64b5614..bfae986d 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -460,6 +460,8 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why reusable templates rebuild explicit SVG structure.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus source structure facts. `create-template` uses those inputs to rebuild one clean Master and semantic Layouts as complete, explicitly annotated SVG pages; it does not package the original PPTX. Strict use keeps the selected Layout contract, while adaptive use may create a new Layout under the same Master. Both export through deterministic `template` mode. Legacy `preserve` remains readable for existing projects only. Raw PPTX plus one-off generated content still routes to `template-fill-pptx`.
+**Why project-scoped thin templates are an output policy, not another structure mode.** `create-template` keeps `library` as its default indexed output and may instead write the same validated contract directly into an initialized project's `templates/` root. Project bitmaps go to `images/`, extracted icons keep a package copy plus a runtime copy, and no global index is touched. Main-pipeline Step 3 detects that the source and target template roots are identical and consumes the bundle in place. Both scopes still compile through `template + adaptive` or `template + strict`; the exporter has no project-local branch.
+
**Why each template SVG stays complete while still compiling to a Layout.** A generated SVG is a complete standalone preview, so it repeats inherited Master/Layout visuals together with its selectable Slide content. `page_layouts` names the input reference and `pptx_layouts` names the output Layout; both exist for every template page. Strict keeps the selected contract, while adaptive may lock a new Layout key under the same Master. Export removes repeated inherited copies and emits real Master/Layout parts, leaving actual content on the Slide.
**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer can emit SVG fallback content plus `data-pptx-native` metadata for supported unmerged tables and conservative classic-chart caches. It retains source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts when the current schema can represent them. Exporter-canonical classic charts also recover canonical solid series/slice colors and exact one- or two-paragraph title metadata. The default export still consumes fallback children as regular DrawingML shapes; only `--native-objects` activates editable PowerPoint tables/charts. Unsupported table cases — including merged cells, direct borders, non-solid fills, and mixed rich text — keep the rendered SVG table. Unsupported chart cases — including ChartEx, rotated/flipped/3D/combo charts, unsupported data-label scopes/types, custom axis semantics, trendlines/error bars, unsupported subtype options, sparse or non-finite caches, and date/formatted category axes — keep a baked preview when one exists, otherwise an explicit placeholder. Both carry `data-pptx-native-status`; the quality checker and native-object export report them as fallback-only warnings. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.
diff --git a/docs/templates-architecture.md b/docs/templates-architecture.md
index 6d5c6a2a..0916d405 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -8,7 +8,7 @@
## 1. The three kinds
-| Kind | Physical dir | What it writes | What it does NOT write | Originating workflow |
+| Kind | Library-scope dir | What it writes | What it does NOT write | Originating workflow |
|---|---|---|---|---|
| **Brand** | `templates/brands/<id>/` | Identity segment only: color / typography / logo / voice / icon style | No canvas, page structure, SVG roster | `workflows/create-brand.md` |
| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template.md` (layout branch) |
@@ -16,7 +16,7 @@
Every Layout/Deck SVG is a complete preview with explicit `data-pptx-layout`, Master/Layout layers, and semantic placeholders. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express, and ordinary content is not duplicated into a metadata taxonomy. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. The template guides authoring of a complete generated page SVG; export never reaches back into the template to overlay visible content missing from that generated SVG. Strict use keeps the selected Layout contract; adaptive use may create a new Layout under the same Master. Both export through `pptx_structure.mode: template`; legacy `preserve` remains compatibility-only.
-The three are **parallel reference bundles**. The physical directory and the frontmatter `kind` field correspond one-to-one:
+The three are **parallel reference bundles**. In library scope, the physical directory and the frontmatter `kind` field correspond one-to-one:
```yaml
# templates/brands/anthropic/design_spec.md
@@ -40,6 +40,19 @@ native_structure_mode: template
---
```
+### Output scope is separate from kind
+
+`create-template` confirms where a layout/deck contract is owned. This execution choice does not add a fourth kind and does not add a PPTX structure mode:
+
+| Scope | Final location | Asset routing | Discovery |
+|---|---|---|---|
+| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Self-contained package, including package-local bitmaps and `icons/` | Register in the matching global index |
+| `project` | Direct `<target_project>/templates/` root, never `<target_project>/templates/<id>/` | Spec/SVG/non-bitmap package assets in `templates/`; bitmaps in `images/` with `../images/<name>` references; extracted icons copied to both `templates/icons/` and runtime `icons/` | No global index or library README update |
+
+Project scope retains `kind: layout` or `kind: deck` in portable frontmatter. `output_scope` and `target_project` stay in the workflow brief and are not persisted into `design_spec.md`.
+
+Before any project-scoped final write, validate the initialized target, require an empty `templates/` root, and check all planned image/icon destination filenames for conflicts. Fail before writing anything; never merge or overwrite.
+
### Segment partition
To make multi-path fusion override cleanly, every field belongs to a named segment. **Default fusion granularity is whole-segment replacement**:
@@ -155,6 +168,8 @@ primary_color: "<HEX>"
Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick (following the "meta + summary" pattern from `charts_index.json`, but preserving structured metadata that helps selection).
+These indexes cover library scope only. Project-scoped template output is intentionally absent from all three indexes and remains usable through its explicit `<project>/templates/` path.
+
### `templates/brands/brands_index.json`
```json
@@ -266,16 +281,18 @@ This lets both AI and humans trace which segment came from where.
## 5. Relationship with SKILL.md Step 3
-**Trigger rule unchanged** — still "explicit directory path only" (see [[feedback-template-explicit-path-only]]). The `kind` field decides **how AI handles the path after triggering**:
+**Trigger rule stays path-based** — an explicit directory path is still required (see [[feedback-template-explicit-path-only]]), and bare names never trigger. The only narrow handoff exception is a project-scoped `create-template` run in the current conversation: after validation, it may pass its exact `<project>/templates/` output directly into Step 3. The `kind` field decides **how AI handles the path after triggering**:
| User path's `kind` | Step 3 action (per-kind branch) |
|---|---|
-| `kind: brand` | Copy design_spec + logos + asset subdirs to `<project>/templates/` |
-| `kind: layout` | Copy design_spec + SVG roster + assets to `<project>/templates/` |
-| `kind: deck` | Copy design_spec + SVG roster + logos + all assets to `<project>/templates/` |
-| Multi-path | Fuse into one `design_spec.md` per the table above; merge SVG / logo files from each source |
+| `kind: brand` | Spec/non-bitmap assets → `<project>/templates/`; logo/illustration/icon bitmaps → `<project>/images/` |
+| `kind: layout` | Spec/SVG roster → `<project>/templates/`; bitmaps → `<project>/images/` |
+| `kind: deck` | Spec/template SVGs/non-bitmap assets → `<project>/templates/`; logo/background/other bitmaps → `<project>/images/` |
+| Multi-path | Fuse one `design_spec.md` per the table above; merge SVG/non-bitmap assets into `templates/` and bitmaps into `images/` |
| Same-kind multiple | Run the "git-style conflict resolution" prompt above to determine the merge |
+Bitmaps share the project's runtime `images/` pool and template SVGs reference them through `../images/`. If the explicit input path is already that same project's `<project>/templates/` root (the `create-template` project-scope output), Step 3 consumes the bundle in place: do not copy it onto itself and do not move its images again. That in-place directory is one complete bundle and cannot participate in multi-path fusion. It is private to its owning project because its image/icon pools are siblings of `templates/`; cross-project reuse requires a self-contained library-scope package.
+
### Strategist confirmation stage narrowing per kind
When a deck path is supplied, the user already has a complete solution; the Strategist confirmation stage narrows to "target audience / page count / outline / tone tweaks" — deck-content fields. Other fields reuse the locked values directly. The narrowing rules live in `references/strategist.md` and `spec_lock_reference.md`.
@@ -287,9 +304,9 @@ When a deck path is supplied, the user already has a complete solution; the Stra
| Workflow | Produces |
|---|---|
| `workflows/create-brand.md` | brand directory (identity-only), reverse-engineered from brand assets |
-| `workflows/create-template.md` | layout or deck directory, internal kind branch: default to deck (user supplies an existing PPT; extract full identity + structure); when the user explicitly says "structure only / drop the brand color", go to the layout branch |
+| `workflows/create-template.md` | layout or deck contract. Output scope is `library` by default (`templates/<kind>/<id>/` + registration) or `project` when confirmed (direct `<project>/templates/`, project asset routing, no registration). The internal kind branch still defaults to deck; explicit "structure only / drop the brand color" selects layout |
-After production, the frontmatter `kind` field determines whether the file lands under `templates/brands/` / `templates/layouts/` / `templates/decks/`.
+In library scope, the frontmatter `kind` field determines whether the file lands under `templates/brands/` / `templates/layouts/` / `templates/decks/`. Project scope keeps the same kind semantics while writing layout/deck output directly to the project's template root.
---
@@ -298,3 +315,4 @@ After production, the frontmatter `kind` field determines whether the file lands
- **No field-level override syntax in the fusion layer** — field-level adjustment uses the existing Strategist confirmation stage path
- **No batch conflict resolution for three or more of the same kind** — ask the user to narrow it down in chat first
- **No bilingual name mapping table** — templates are named in their brand / scenario's native language (Chinese templates use Chinese names; English templates use snake_case); no forced unification
+- **No new structure mode or output CLI flag** — output scope is a `create-template` brief decision; both layout/deck scopes still declare `native_structure_mode: template`
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index 2e94c97b..f970b058 100644
--- a/docs/templates-guide.md
+++ b/docs/templates-guide.md
@@ -21,10 +21,10 @@ The workflow **defaults to free design** — it will not ask whether you want a
Send a path to a template directory in your initial message. Anywhere in the sentence is fine; the path just has to be unambiguous:
> "use this template: `skills/ppt-master/templates/layouts/academic_defense/`" ✅
-> "用这个模板做汇报:`projects/last_deck/template/`" ✅
+> "用这个模板做汇报:`projects/last_deck/templates/`" ✅
> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
-The AI copies that directory's SVGs, `design_spec.md`, and assets into your project, then proceeds to the Strategist phase. The path can point to anywhere — the built-in library under `skills/ppt-master/templates/layouts/`, a previous project's `template/` folder, or any other location on disk.
+The AI installs that directory's SVGs, `design_spec.md`, and assets into your project, then proceeds to the Strategist phase. The path may point to the built-in library under `skills/ppt-master/templates/layouts/` or another self-contained template directory. When the path already is the current project's own `<project>/templates/` root, the workflow consumes it in place instead of copying it onto itself. A project-scoped create-template run may hand this exact validated path directly to Step 3 in the same conversation; this is the only exception to the initial-message rule. Do not use a different project's `templates/` root as an external package: its `../images/` and runtime icon references are owner-local. Promote that design through library scope first.
### What does NOT trigger the template flow
@@ -133,7 +133,9 @@ The workflow does not silently infer values — before generation it lists these
| Field | Notes |
|-------|-------|
-| **Template ID** | Directory / index key. Prefer ASCII slug like `acme_consulting`; non-ASCII names work but must be filesystem-safe |
+| **Output scope** | `library` (default; reusable by every project and registered globally) or `project` (thin bundle written directly into one initialized project's template root) |
+| **Target project** | Required only for `project`; give the exact initialized project path |
+| **Template ID** | Portable template identity; in library scope it is also the directory / index key. Prefer ASCII slug like `acme_consulting`; non-ASCII names work but must be filesystem-safe |
| **Display name** | Human-readable name for documentation |
| **Category** | One of `brand` / `general` / `scenario` / `government` / `special` |
| **Use cases** | Annual report / consulting / defense / government briefing / ... |
@@ -148,7 +150,9 @@ The workflow does not silently infer values — before generation it lists these
After confirmation the workflow echoes the finalized brief and emits the marker `[TEMPLATE_BRIEF_CONFIRMED]`. Subsequent steps only run after that marker. **This is a hard gate — no brief, no generation.**
-> Why so strict? Because a template is a library asset that future projects will reuse. Getting it right once is far cheaper than regenerating after the fact.
+For project scope, one more hard preflight runs before any final file is written: the target must already be initialized, its `templates/` root must be empty, and the planned bitmap/icon filenames must not collide with anything already in `images/` or `icons/`. A failed check stops before partial output; the workflow does not merge or overwrite.
+
+> Why so strict? A template is a structural contract, whether it is reused globally or only inside the current project. Confirming ownership and geometry first avoids partial or misplaced output.
### Step 3 — `standard`, `fidelity`, or `mirror`?
@@ -168,15 +172,16 @@ This is the most easily confused decision when deriving a template.
**How mirror is consumed**: the Strategist picks one mirror page per project page, and the Executor copies that complete SVG and edits visible text in place while preserving decoration, sprite crops, geometry, and every `data-pptx-*` structure declaration.
-### Step 4 — Registration and discovery
+### Step 4 — Validation, registration, and discovery
-After generation, the workflow:
+After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) as a hard gate. What happens next depends on the confirmed output scope:
-1. Runs [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) (hard gate — no entry without passing)
-2. Registers the template ID in [`layouts_index.json`](../skills/ppt-master/templates/layouts/layouts_index.json)
-3. Syncs the table in [`templates/layouts/README.md`](../skills/ppt-master/templates/layouts/README.md)
+| Scope | Output | Discovery behavior |
+|---|---|---|
+| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Register in the matching `layouts_index.json` or `decks_index.json` after validation |
+| `project` | Direct `<project>/templates/` bundle; bitmaps in `<project>/images/`; extracted icons in both `<project>/templates/icons/` and `<project>/icons/` | Skip every global index and library README update |
-Registration makes the template **discoverable** — when someone asks "what templates are available?", the AI lists it from the index. To use it in a new project, follow the SKILL.md Step 3 rule: name its directory path in your first message, e.g. `use this template: skills/ppt-master/templates/layouts/<your_template_id>/`.
+Library registration makes the template **discoverable** — when someone asks "what templates are available?", the AI lists it from the index. To use it in a new project, follow the SKILL.md Step 3 rule: name its directory path in your first message, e.g. `use this template: skills/ppt-master/templates/layouts/<your_template_id>/`. A project-scoped template is intentionally private to that project and is consumed in place through the explicit `<project>/templates/` path.
When a deck/layout template is selected, the Strategist confirmation stage asks how it should be used:
@@ -185,6 +190,8 @@ When a deck/layout template is selected, the Strategist confirmation stage asks
### What a derived template looks like
+Library scope (the default) remains a self-contained package:
+
```
skills/ppt-master/templates/layouts/<your_template_id>/
├── design_spec.md # design spec; §VI lists every page
@@ -215,14 +222,31 @@ skills/ppt-master/templates/layouts/<your_template_id>/
└── *.png / *.jpg
```
+Project scope writes a thin bundle directly into the initialized project's existing roots. It does not create `<project>/templates/<template_id>/`:
+
+```
+projects/<project>/
+├── templates/
+│ ├── design_spec.md
+│ ├── 01_cover.svg
+│ ├── 02_chapter.svg
+│ ├── 03_content.svg
+│ ├── 04_ending.svg
+│ └── icons/ # package/validation copy
+├── images/
+│ └── *.png / *.jpg # SVG references use ../images/<name>
+└── icons/
+ └── *.svg # runtime copy of extracted icons
+```
+
### Project-level customization vs global template
-Don't confuse the two:
+Choose the output scope according to ownership:
-- **Derive a new template** = enter the global library at `skills/ppt-master/templates/layouts/`, available to all future projects
-- **Project-level customization** = edit only the SVGs under `projects/<project>/templates/` for this one deck; not registered, no impact elsewhere
+- **Library scope (`library`, default)** = enter `skills/ppt-master/templates/<kind>/<id>/`, register globally, and make the package available to future projects
+- **Project scope (`project`)** = create the same validated template contract directly under `projects/<project>/templates/`, keep its runtime images/icons beside that project, and skip global registration
-`/create-template` is for the former. For the latter, just edit the SVGs in the project directory directly — no workflow needed.
+`/create-template` supports both. Project scope is the safe route when the template exists only to drive the current deck; it still gets the normal brief, explicit Master/Layout metadata, and template validation without polluting the global library. Choose library scope when another project must consume the result.
---
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 6fc5bfd3..3d261342 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -256,12 +256,13 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息
- 期望的风格基调和配色(如"现代克制、深蓝主色调")
- 类别偏好(`brand` 品牌 / `general` 通用 / `scenario` 场景 / `government` 政务 / `special` 特殊)
- 画布格式(默认 16:9,如需其他格式请注明)
+- 输出范围:进入索引的 `library`(默认)或一个已经初始化的 `project`
-不需要一次提供所有细节——AI 代理会通过对话追问补齐缺失信息(模板 ID、主题模式等)。
+不需要一次提供所有细节——AI 代理会通过对话追问补齐缺失信息(输出范围、模板 ID、主题模式等)。
**第三步 — 等待完成**
-AI 代理会自动完成后续工作 — 分析截图、构建布局定义、注册模板,使其出现在 PPT Master 工作流的模板选项中。
+AI 代理会自动完成后续工作——分析截图、构建布局定义并验证模板。`library` 范围会完成全局注册,使其进入模板发现;`project` 范围则把薄模板直接写入该项目的 `templates/` 根目录,并明确跳过全局注册。
> **提示**:对风格和使用场景描述得越具体,生成的模板就越符合你的预期。
diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.md
index ae332bca..eb64eabb 100644
--- a/docs/zh/getting-started.md
+++ b/docs/zh/getting-started.md
@@ -33,14 +33,16 @@
这会跑 `pptx_template_import.py`,把文件重建成可复用的资产包——版式 SVG + `design_spec.md` + 抽取出的主题色、字体、图片。生成时引用的就是这个资产包。
+在 create-template brief 中选择 `library`(沿用原默认)或 `project`。项目范围要求给出已初始化的目标项目;写入前统一检查模板根目录和素材文件名,再把 bundle 直接安装到该项目,不做全局注册。
+
复刻出的模板可以放在两个位置之一:
| 位置 | 路径 | 说明 |
|---|---|---|
| **注册进 skill 库** | `skills/ppt-master/templates/layouts/<id>/` | 全局,所有项目可复用;跑 `register_template.py` 后,问"有哪些模板"时会被列出来 |
-| **放进项目里** | `projects/<project>/templates/` | 项目本地;给路径即用,无需注册 |
+| **放进项目里** | `projects/<project>/templates/` | 只归属该项目;原地消费,无需注册 |
-无论放哪,生成时都靠在对话里给出它的**目录路径**来引用——工作流只认显式路径,绝不认裸模板名:
+全局库 package 在生成时靠对话里给出**目录路径**来引用;项目范围 create-template 可在同一对话里把已验证的精确路径直接交给 Step 3。两种情况都以路径为准,绝不认裸模板名。若要把项目范围设计复用于另一个项目,应重新以 `library` 范围创建,因为图片/图标池位于原项目模板根目录的同级位置。
```
你:用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/academic_defense/
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index 1c61bca7..624a31ea 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -84,7 +84,7 @@
- **`--native-objects` 从休眠 marker 硬化为可用级 opt-in** — 那条窄「原生对象」例外(见下文 Non-goals)现在导出的图表与纯文本表格会**保留 deck 自己的设计**,不再塌回 PowerPoint 的白底默认主题。classic 原生图表显式写入 chart-area / plot-area / 轴线 / 网格线 / 标签文字颜色——从可见的 SVG fallback 推断(最大面板型 `<rect>` → 背景、fallback 文字 → 标签、fallback 描边 → 轴线/网格),或用 `style` 显式覆盖(`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`,`"none"` 表透明);颜色解析把命名色、`#RGB` 简写、`rgb()` / `rgba()` 归一为 OOXML hex;bar/column 系列关掉负值反色,负值柱保持系列色。激活导出命名为 `<name>_<ts>_native_charts.pptx` 以与默认压平形状导出区分。**默认路线不变**——图表/表格仍以 SVG 派生的 DrawingML 形状导出以保跨渲染器保真;原生对象仍是下文 Non-goals 里那条刻意的 opt-in 取舍
-- **原生 package 结构 + 保守 PPTX 对象回转** — 自由设计的 baseline 只提升安全共享背景/chrome,分配文件名页型 Layout,并可进一步提升家族内完全一致的前置 chrome,不推断 placeholder。模板路线确定性编译完整 SVG 中显式声明的 Master/Layout/placeholder,并把锁定 title/body 字号写入母版 `p:txStyles`,不改变页面直接 run 字号。`create-template` 只把源结构当分析输入并统一重建显式 SVG;`strict` 保持所选 Layout,`adaptive` 可在同一 Master 下新建 Layout。旧 `preserve` 仅保留兼容读取;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。
+- **原生 package 结构 + 保守 PPTX 对象回转** — 自由设计的 baseline 只提升安全共享背景/chrome,分配文件名页型 Layout,并可进一步提升家族内完全一致的前置 chrome,不推断 placeholder。模板路线确定性编译完整 SVG 中显式声明的 Master/Layout/placeholder,并把锁定 title/body 字号写入母版 `p:txStyles`,不改变页面直接 run 字号。`create-template` 只把源结构当分析输入并统一重建显式 SVG;`strict` 保持所选 Layout,`adaptive` 可在同一 Master 下新建 Layout。默认 `library` 输出继续进入全局索引,`project` 输出则把同一薄模板合同直接安装到一个已初始化项目的模板根目录,不做全局注册。旧 `preserve` 仅保留兼容读取;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。
---
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 2efc8094..725055ed 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -460,6 +460,8 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么可复用模板统一重建显式 SVG 结构。** `pptx_template_import.py` 输出分层的 Master/Layout/Slide 参考和源结构事实;`create-template` 据此重建一个干净 Master 与语义 Layout,并把它们重复标注在可独立预览的完整 SVG 中,不再封装原 PPTX。严格套用保持所选 Layout 契约,自适应使用可在同一 Master 下新建显式 Layout;两者都走确定性的 `template` 导出。`preserve` 只为旧项目保留兼容读取。
+**为什么项目本地薄模板只是输出政策,不是另一种结构模式。** `create-template` 仍以写入索引的 `library` 为默认,也可以把同一份已校验合同直接写到已初始化项目的 `templates/` 根目录。项目位图进入 `images/`,抽取图标同时保留 package 副本与运行时副本,且不修改任何全局索引。主管线 Step 3 发现模板源目录与目标根目录相同时原地消费。两种输出范围仍走 `template + adaptive` 或 `template + strict`;导出器没有项目本地分支。
+
**为什么模板 SVG 保持完整却仍能编译成版式。** 每张生成 SVG 都是可独立预览的完整 slide,因此会重复携带继承的 Master/Layout 视觉和可选择的 Slide 内容。`page_layouts` 指定输入参考,`pptx_layouts` 指定输出版式,两者在模板路线中逐页齐全。严格模式保持所选契约;自适应模式可在同一 Master 下锁定新 Layout。导出器移除重复继承层并生成真实 Master/Layout,实际内容仍留在 Slide。
**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据;当现有 schema 能表达时,还会保留源表格样式继承、受支持的单元格纯色填充 / 基础文字格式,以及图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关。由本 exporter 生成的规范 classic chart 还会回读规范纯色系列 / 切片,以及精确的单段或双段标题元数据。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留实际渲染的 SVG table。ChartEx、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持的图表场景,则在有 baked preview 时保留预览,否则给出明确占位符。两类对象都会写入 `data-pptx-native-status`;质量检查器和 native-object 导出将其报告为 fallback-only warning。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。
diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.md
index b4795476..fa50381f 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -8,7 +8,7 @@
## 一、三分类
-| 分类 | 物理目录 | 写什么 | 不写什么 | 出处工作流 |
+| 分类 | 全局库范围目录 | 写什么 | 不写什么 | 出处工作流 |
|---|---|---|---|---|
| **Brand** | `templates/brands/<id>/` | 仅身份段:color / typography / logo / voice / icon style | 不写 canvas、page structure、SVG roster | `workflows/create-brand.md` |
| **Layout** | `templates/layouts/<id>/` | 仅结构段:canvas / page structure / page types / SVG roster | 不写品牌身份(无 logo、无品牌色硬约束) | `workflows/create-template.md`(layout 分支)|
@@ -16,7 +16,7 @@
Layout/Deck 的每张 SVG 都是完整预览,同时显式声明 `data-pptx-layout`、Master/Layout 层和语义 placeholder。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为,普通内容不会被重复分类到 metadata 词表。PPTX 导入产生的 `native_structure.json` 与 `source_template.pptx` 只用于分析源结构,不进入新模板包。模板负责指导生成完整的页面 SVG;导出时不得再回读模板,向生成 SVG 叠加其中缺失的可见内容。下游 `strict` 保持所选 Layout 契约,`adaptive` 可在同一 Master 下创建新 Layout;两者都使用 `pptx_structure.mode: template`。旧 `preserve` 契约仅保留兼容读取。
-三者是**三种并列的 reference bundle**,物理目录与 frontmatter `kind` 字段双向对齐:
+三者是**三种并列的 reference bundle**。在全局库范围内,物理目录与 frontmatter `kind` 字段双向对齐:
多路径合成后的项目级 `design_spec.md` 也必须保留准确的 `kind`:同时具备身份段和结构段时为 `deck`,只有结构段时为 `layout`,只有身份段时为 `brand`。Strategist 确认页据此只对真正包含页面结构的 Deck/Layout 显示 `adaptive / strict`。
@@ -42,6 +42,19 @@ native_structure_mode: template
---
```
+### 输出范围与 kind 相互独立
+
+`create-template` 会确认 Layout/Deck 契约归属于哪里。这个执行选择不会增加第四种 kind,也不会增加新的 PPTX 结构模式:
+
+| 范围 | 最终位置 | 素材分流 | 发现行为 |
+|---|---|---|---|
+| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | 自包含 package,包括 package 内位图和 `icons/` | 写入对应全局索引 |
+| `project` | 直接写 `<target_project>/templates/` 根目录,禁止再套 `<id>/` | spec / SVG / 非位图 package 资产在 `templates/`;位图在 `images/`,SVG 用 `../images/<name>`;提取图标同时复制到 `templates/icons/` 与运行期 `icons/` | 不更新全局索引与库 README |
+
+项目范围仍在可移植 frontmatter 中保留 `kind: layout` 或 `kind: deck`。`output_scope` 与 `target_project` 只属于工作流简报,不写入 `design_spec.md`。
+
+项目范围第一次写最终文件前,必须一次性确认目标项目已初始化、`templates/` 根目录为空,并检查全部计划写入的图片/图标文件名无冲突。任一失败都在写入前停止,不合并、不覆盖。
+
### 三段的字段切分
为了让多路径合成能干净覆盖,所有字段按段归属,**段级整段替换是默认粒度**:
@@ -157,6 +170,8 @@ primary_color: "<HEX>"
每个 index 跟物理目录一一对应,字段按需精简(参照 [[project-charts-index-full-read-intentional]] 的"meta + summary"模式,但保留对 Strategist 选型有用的结构化元数据)。
+三套索引只覆盖全局库范围。项目范围模板有意不进入任何索引,仍可通过显式 `<project>/templates/` 路径使用。
+
### `templates/brands/brands_index.json`
```json
@@ -266,7 +281,7 @@ AI: 你给了两个 brand,检测到段级冲突:
## 五、与 SKILL.md Step 3 的关系
-**触发规则不变** —— 仍然是「显式目录路径才触发」(见 [[feedback-template-explicit-path-only]])。`kind` 字段决定**触发后 AI 怎么处理**:
+**触发规则仍以路径为准**——仍需显式目录路径(见 [[feedback-template-explicit-path-only]]),裸名称绝不触发。唯一的窄例外是当前对话刚完成项目范围 `create-template`:验证通过后可把精确的 `<project>/templates/` 输出直接交给 Step 3。`kind` 字段决定**触发后 AI 怎么处理**:
| 用户路径指向 | Step 3 行为(按 kind 分支)|
|---|---|
@@ -274,10 +289,10 @@ AI: 你给了两个 brand,检测到段级冲突:
| `kind: layout` | design_spec + SVG roster → `<project>/templates/`;**位图**资产 → `<project>/images/` |
| `kind: deck` | design_spec + 模板 SVG → `<project>/templates/`;logo / 背景 / 其它**位图** → `<project>/images/` |
| 多路径 | 按上表合成单份 `design_spec.md`;SVG 进 `templates/`、位图进 `images/` 合并复制 |
-
-> 位图统一进项目 `images/`(和 AI / 网络 / 用户图片同一个运行期图片池,SVG 里走 `../images/`);`templates/` 只放 spec 和模板 SVG 等供 Strategist/Executor 阅读、不被直接渲染的参考材料。
| 同类多份 | 按上节"git 冲突解决"问答,得到合成结果 |
+位图统一进项目 `images/`(和 AI / 网络 / 用户图片同一个运行期图片池,SVG 里走 `../images/`);`templates/` 只放 spec、模板 SVG 与非位图 package 资产。如果显式输入路径本来就是同一项目的 `<project>/templates/` 根目录(即 `create-template` 的项目范围产物),Step 3 原地消费:不得复制到自身,也不得再次移动 `images/` 中的素材。该原地目录是一份完整 bundle,不参与多路径融合。由于图片/图标池位于 `templates/` 的同级目录,它只归属当前项目;跨项目复用必须改用自包含的全局库范围 package。
+
### 策略师确认阶段在不同 kind 下的收窄
Deck 路径下用户已经拿到完整方案,策略师确认阶段收窄到"目标受众 / 页数 / 大纲 / 调性微调"等 deck 内容相关字段;其他字段直接从锁定值复用。具体收窄规则落在 `references/strategist.md` 与 `spec_lock_reference.md`。
@@ -289,9 +304,9 @@ Deck 路径下用户已经拿到完整方案,策略师确认阶段收窄到"
| 工作流 | 产出 |
|---|---|
| `workflows/create-brand.md` | brand 目录(identity-only),从品牌资产逆向提取 |
-| `workflows/create-template.md` | layout 或 deck 目录,内部按 kind 分支:默认走 deck(用户给了一份现存 PPT,提取完整身份 + 结构);用户明说"只要结构 / 丢掉品牌色"时走 layout |
+| `workflows/create-template.md` | layout 或 deck 契约。输出范围默认 `library`(`templates/<kind>/<id>/` + 注册),确认 `project` 时直接写 `<project>/templates/`,按项目素材规则分流且不注册。内部 kind 分支仍默认 deck;用户明说"只要结构 / 丢掉品牌色"时走 layout |
-产出后 frontmatter `kind` 字段决定文件落到 `templates/brands/` / `templates/layouts/` / `templates/decks/`。
+在全局库范围,frontmatter `kind` 字段决定文件落到 `templates/brands/` / `templates/layouts/` / `templates/decks/`。项目范围保留同一 kind 语义,但 Layout/Deck 直接落在项目模板根目录。
---
@@ -300,3 +315,4 @@ Deck 路径下用户已经拿到完整方案,策略师确认阶段收窄到"
- **不在 fusion 层支持字段级覆盖语法** —— 字段级微调走 策略师确认阶段这条已有路径
- **不为同类三份及以上设计批量冲突解决** —— 用户先在 chat 里收敛到两份
- **不引入双名映射表** —— 模板命名按其品牌/场景母语(中文模板用中文名,英文模板用 snake_case),不强制统一
+- **不新增结构模式或输出 CLI flag** —— 输出范围是 `create-template` 简报里的执行选择;两种范围的 Layout/Deck 都继续声明 `native_structure_mode: template`
diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.md
index 60bc71f9..046dc3ba 100644
--- a/docs/zh/templates-guide.md
+++ b/docs/zh/templates-guide.md
@@ -21,10 +21,10 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
在对话里把模板目录的路径写进去(位置不重要,只要明确即可):
> "用这个模板做:`skills/ppt-master/templates/layouts/academic_defense/`" ✅
-> "用上次那个模板:`projects/last_deck/template/`" ✅
+> "用上次那个模板:`projects/last_deck/templates/`" ✅
> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
-AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目录,然后进入 Strategist 阶段。路径可以是任意位置——内置库的 `skills/ppt-master/templates/layouts/` 下、上一个项目的 `template/` 文件夹、或者磁盘上其他任何地方都行。
+AI 会把这个目录里的 SVG、`design_spec.md` 和素材安装到项目目录,然后进入 Strategist 阶段。路径可以指向内置库 `skills/ppt-master/templates/layouts/` 下的 package,或其他自包含模板目录。如果该路径本来就是当前项目自己的 `<project>/templates/` 根目录,流程会原地消费,不会再复制到自身。项目范围 create-template 可在同一对话里把这个已验证的精确路径直接交给 Step 3;这是“首条消息显式路径”规则的唯一例外。不要把另一个项目的 `templates/` 根目录当外部 package 使用:其中 `../images/` 与运行期图标引用只归属原项目;应先通过 library 范围提升为自包含 package。
### 什么**不会**触发模板流程
@@ -133,7 +133,9 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目
| 字段 | 说明 |
|------|------|
-| **模板 ID** | 目录名 / 索引键。优先 ASCII slug,如 `acme_consulting`;中文品牌名也行,但要文件系统安全 |
+| **输出范围** | `library`(默认;所有项目可复用并进入全局索引)或 `project`(直接写入一个已初始化项目的模板根目录) |
+| **目标项目** | 仅 `project` 必填;必须给出已初始化项目的精确路径 |
+| **模板 ID** | 模板的可移植身份;在 `library` 下同时也是目录名 / 索引键。优先 ASCII slug,如 `acme_consulting`;中文品牌名也行,但要文件系统安全 |
| **显示名称** | 文档中的人类可读名 |
| **类别** | `brand` / `general` / `scenario` / `government` / `special` 五选一 |
| **适用场景** | 年报 / 咨询 / 答辩 / 政府汇报…… |
@@ -148,7 +150,9 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目
确认后,工作流会回显一份完整简报并写入标记 `[TEMPLATE_BRIEF_CONFIRMED]`,从这一刻起后续步骤才会启动。**这是一个硬门——简报没确认,不会开始生成**。
-> 为什么这么严?因为模板是入库资产,未来会被复用。一次说清楚,比生成完再返工便宜得多。
+如果选择 `project`,第一次写最终文件前还会做一次完整预检:目标必须已初始化、`templates/` 根目录必须为空、计划写入的位图与图标文件名不得和现有 `images/` / `icons/` 冲突。任一检查失败都会在写入前停止,不合并、不覆盖,也不会留下半套输出。
+
+> 为什么这么严?无论模板进入全局库,还是只服务当前项目,它都是结构契约。先确认归属和几何,可避免半成品或资产落错目录。
### 第三步:选 standard、fidelity 还是 mirror?
@@ -168,15 +172,16 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目
**`mirror` 模板怎么消费**:Strategist 为每个项目页选择一张 mirror 参考,Executor 复制完整 SVG 并原位修改可见文字,同时保留装饰、精灵图裁剪、几何坐标和全部 `data-pptx-*` 结构声明。
-### 第四步:注册与发现
+### 第四步:验证、注册与发现
-模板生成完,工作流会:
+模板生成完,两种范围都会先跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 作为硬门。之后按确认的输出范围分流:
-1. 跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 验证(硬门,不通过不入库)
-2. 把模板 ID 注册到 [`layouts_index.json`](../../skills/ppt-master/templates/layouts/layouts_index.json)
-3. 同步 [`templates/layouts/README.md`](../../skills/ppt-master/templates/layouts/README.md) 表格
+| 范围 | 产物 | 发现行为 |
+|---|---|---|
+| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | 验证通过后注册到对应 `layouts_index.json` 或 `decks_index.json` |
+| `project` | 直接写 `<project>/templates/`;位图在 `<project>/images/`;提取图标同时保留在 `<project>/templates/icons/` 与 `<project>/icons/` | 跳过全部全局索引和库 README 更新 |
-注册让模板**可被发现**——下次有人问"有哪些模板可用?"时,AI 会从索引里把它列出来。要在新项目里用它,仍然按 SKILL.md Step 3 的规则:在第一条消息里把目录路径写出来,例如 `用这个模板:skills/ppt-master/templates/layouts/<your_template_id>/`。
+全局注册让模板**可被发现**——下次有人问"有哪些模板可用?"时,AI 会从索引里把它列出来。要在新项目里用它,仍然按 SKILL.md Step 3 的规则:在第一条消息里把目录路径写出来,例如 `用这个模板:skills/ppt-master/templates/layouts/<your_template_id>/`。项目范围模板有意保持项目私有,直接通过显式 `<project>/templates/` 路径原地消费。
选择 Deck/Layout 模板后,Strategist 确认阶段会进一步询问模板的使用方式:
@@ -185,6 +190,8 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目
### 派生后的目录长什么样
+全局库范围(默认)保持原有的自包含 package:
+
```
skills/ppt-master/templates/layouts/<your_template_id>/
├── design_spec.md # 设计规范,§VI 列出全部页面
@@ -215,14 +222,31 @@ skills/ppt-master/templates/layouts/<your_template_id>/
└── *.png / *.jpg
```
+项目范围会把薄模板直接写入已初始化项目的现有根目录,不会创建 `<project>/templates/<template_id>/`:
+
+```
+projects/<project>/
+├── templates/
+│ ├── design_spec.md
+│ ├── 01_cover.svg
+│ ├── 02_chapter.svg
+│ ├── 03_content.svg
+│ ├── 04_ending.svg
+│ └── icons/ # package / 验证副本
+├── images/
+│ └── *.png / *.jpg # SVG 统一引用 ../images/<name>
+└── icons/
+ └── *.svg # 提取图标的运行期副本
+```
+
### 项目级一次性定制 vs 全局模板
-二者别搞混:
+按资产归属选择输出范围:
-- **派生新模板** = 入全局库,在 `skills/ppt-master/templates/layouts/` 下,未来所有项目都能调用
-- **项目级定制** = 只在 `projects/<project>/templates/` 里改这一份 deck 的页面,不入库、不影响其他项目
+- **全局库范围(`library`,默认)** = 进入 `skills/ppt-master/templates/<kind>/<id>/`,写入全局索引,供未来项目复用
+- **项目范围(`project`)** = 把同一份经过验证的模板契约直接写进 `projects/<project>/templates/`,运行期图片/图标留在该项目内,不做全局注册
-`/create-template` 工作流只做前者。后者直接在项目目录里改 SVG 即可,不需要走这个流程。
+`/create-template` 两种范围都支持。模板只服务当前 deck 时用 `project`:仍然经过完整简报、显式 Master/Layout metadata 与模板校验,但不会污染全局库。另一个项目也要使用时,应选择 `library`。
---
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 4b656cb6..f4f43c77 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -222,11 +222,12 @@ Multi-deck: several PPTX files may be imported into one main-pipeline project
Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use `template-fill` for raw PPTX template + generated PPTX requests; use `beautify` only when the source deck's page count, order, and wording are preserved.
-**Template flow triggers ONLY on explicit directory paths** supplied by the user in their initial message. The trigger rule is mechanical, not interpretive:
+**Template flow triggers ONLY on explicit directory paths** supplied by the user in their initial message, plus one narrow workflow handoff: a project-scoped `create-template` run in the current conversation may pass its exact validated `<project>/templates/` output directly into this Step. The trigger rule is mechanical, not interpretive:
| User input contains | Step 3 action |
|---|---|
| One or more explicit template directory paths (each resolves to a directory containing `design_spec.md` with `kind: brand` / `kind: layout` / `kind: deck` in its YAML frontmatter) | Read each spec's `kind`, dispatch per the kind matrix below, fuse if multiple |
+| Current `create-template` workflow just completed project scope and validated its exact `<project>/templates/` output | Consume that single directory in place; it cannot join multi-path fusion |
| Anything else — bare template names ("用 academic_defense"), style descriptions ("麦肯锡风格"), brand mentions ("招商银行风格"), vague intent ("想用个模板"), or silence | Skip Step 3, free design |
There is no slug matching, no name lookup, no fuzzy resolution. A name without a path does not trigger — the user must give a path the AI can `cd` into.
@@ -266,16 +267,40 @@ The architecture has three independent reference bundles. Full schema in [`docs/
| `kind: deck` | `design_spec.md` + template SVGs → `<project>/templates/`; logos / backgrounds / other **bitmaps** → `<project>/images/`. Strategist locks all segments; Strategist confirmation stage narrows to deck-content fields (audience / page count / outline / tone tweaks). |
```bash
-TEMPLATE_DIR=<user-supplied path>
+TEMPLATE_DIR="<user-supplied path>"
+PROJECT_TEMPLATES="<project_path>/templates"
+resolve_path() {
+ python3 -c 'from pathlib import Path; import sys; print(Path(sys.argv[1]).resolve())' "$1"
+}
# Bitmaps join the project's single runtime image pool (images/, referenced as
# ../images/); the spec + template SVGs + other non-image assets stay in
# templates/ as design reference the Strategist/Executor read but never render.
-cp -r ${TEMPLATE_DIR}/* <project_path>/templates/
-find <project_path>/templates -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' -o -iname '*.bmp' \) -exec mv {} <project_path>/images/ \;
+if [ "$(resolve_path "${TEMPLATE_DIR}")" = "$(resolve_path "${PROJECT_TEMPLATES}")" ]; then
+ # Project-scoped create-template output is already staged in place.
+ true
+else
+ cp -r "${TEMPLATE_DIR}"/. "${PROJECT_TEMPLATES}/"
+ find "${PROJECT_TEMPLATES}" -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' -o -iname '*.bmp' \) -exec mv {} "<project_path>/images/" \;
+fi
```
The same split applies to all three kinds — bitmaps always land in `images/`, the rest in `templates/`. The spec's `kind` field tells Strategist how to read the `templates/` side; downstream code doesn't distinguish. (Template SVGs in `templates/` are reference material only — the rendered pages live in `svg_output/` and reference images via `../images/`.)
+When `create-template` used project output scope, its directory is already the
+target project's `templates/` root and its bitmap/icon runtime copies are already
+in their final project pools. Resolve both paths before copying: equality means
+**in-place consumption**, so skip both the copy and bitmap move. An in-place
+directory is one complete bundle and cannot participate in multi-path fusion;
+use external library bundles for fusion. Never place the local bundle under a
+nested `templates/local_master/` directory because the confirmation and quality
+gates read the project `templates/` root.
+
+A project-scoped bundle belongs only to its target project: its SVGs may refer
+to sibling `../images/` and runtime `../icons/` pools that are outside the
+template root. Do not copy another project's `templates/` root as an external
+bundle. For cross-project reuse, recreate/promote the design with
+`create-template` library scope so the package is self-contained.
+
Legacy template packages may ship `native_structure.json` + `source_template.pptx`; keep the pair together in `<project>/templates/` for backward-compatible `preserve` export. Current `create-template` output does not package this pair: it rebuilds complete, explicitly layered SVG templates instead. During fusion, never mix one legacy contract with another template's source package.
The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. Both use `pptx_structure.mode: template` for current templates and map every page to one reference SVG plus one output PowerPoint layout. `strict` keeps the referenced layout contract unchanged; `adaptive` may create a new layout key while keeping the template Master contract. Legacy `preserve` remains strict-only compatibility behavior.
@@ -335,13 +360,13 @@ Single-path Step 3 does **not** add provenance (the source is self-evident from
The fused frontmatter `kind` describes the resulting bundle: `deck` when both identity and structure are present, `layout` when only structure is present, and `brand` when only identity is present. Keep this field accurate; the Strategist confirmation server uses it to show template adherence only for bundles that actually own page structure.
-**✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If the user supplied one or more explicit template paths, those have been dispatched (or fused) into `<project_path>/templates/` before advancing.**
+**✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If the user supplied one or more explicit template paths, those have been copied, staged in place, or fused into `<project_path>/templates/` before advancing.**
---
### Step 4: Strategist Phase (MANDATORY — cannot be skipped)
-🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied into the project.
+🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied or confirmed in place in the project.
First, read the role definition:
```
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index a4db2f20..d78725eb 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -4,15 +4,19 @@
## Core Mission
-Generate reusable page templates for the **global template library** based on a finalized template brief, and write a concise `design_spec.md` that captures the source-derived basic norms that make the template reusable.
+Generate reusable page templates at the output scope confirmed by `create-template`, and write a concise `design_spec.md` that captures the source-derived basic norms that make the template reusable.
-> This is a standalone role: only triggered via the `/create-template` workflow. It is **not** the project-level template selection/customization step in the main PPT generation pipeline.
+> This is a standalone role: only triggered via the `/create-template` workflow. It may write a global library package or a project-local thin bundle; it is not the template selection step in the main PPT generation pipeline.
## Usage
- **Trigger**: `/create-template` workflow
-- **Output location**: `templates/<kind_dir>/<template_name>/` where `<kind_dir>` is `decks` (default — full-PPT replica with identity) or `layouts` (structure-only, no identity segment)
-- **Input**: finalized template brief (template ID, display name, kind, applicable scenarios, tone, theme mode, canvas format, optional reference assets, accepted basic template norms)
+- **Output location**: `library` (default) → `skills/ppt-master/templates/<kind_dir>/<template_name>/`; `project` → the confirmed `<target_project>/templates/` root with no nested template-ID directory
+- **Input**: finalized template brief (output scope, target project when project-scoped, template ID, display name, kind, applicable scenarios, tone, theme mode, canvas format, optional reference assets, accepted basic template norms)
+
+**Hard rule — scope is execution metadata**: Use `output_scope` and `target_project` to route files, but do not write either field into portable `design_spec.md` frontmatter. Do not create a new PPTX structure mode; deck/layout output still declares `native_structure_mode: template`.
+
+**Project-scope precondition**: The workflow has already confirmed an initialized target project, an empty `<target_project>/templates/`, and collision-free destination filenames in `images/` and `icons/`. Do not begin final writes before that all-at-once preflight passes.
When the workflow provides a PPTX reference source, the effective input package comes from the unified `pptx_template_import.py` preparation workspace and becomes:
@@ -94,7 +98,7 @@ Extension page types beyond the canonical four (transition / appendix / disclaim
- Cluster slides from `manifest.json` by `pageType` + visual structure (column count, hero-image vs. icon-grid vs. quote, etc.)
- One SVG per cluster — do **not** emit a variant for a cluster represented by a single source slide unless that slide is structurally distinct from existing variants
- One variant per visually distinct cluster — let the source's structural diversity drive the count. Collapse only **near-duplicates** (same column count, same hero element, same content density); do not collapse genuine structural differences just to keep the variant count down. If you find yourself wanting one variant per source slide, that is the signal the user should be in `mirror` mode, not `fidelity`
-- Record every emitted page in `design_spec.md §V Page Roster`; the corresponding index entry (`decks_index.json` or `layouts_index.json`) is generated automatically by `register_template.py` from the directory's actual SVG files
+- Record every emitted page in `design_spec.md §V Page Roster`; in library scope, `register_template.py` generates the corresponding index entry from the directory's actual SVG files. Project scope skips registration
> Variants reuse the parent type's placeholder set — see §4 (Placeholder Reference) below.
@@ -103,7 +107,7 @@ Extension page types beyond the canonical four (transition / appendix / disclaim
When the brief sets `Replication mode: mirror`, preserve literal page appearance while reconstructing layer ownership:
- Visual source: `<import_workspace>/svg-flat/slide_NN.svg` (the self-contained "what PowerPoint shows" view). Structural source: `svg/master_*.svg`, `svg/layout_*.svg`, and `svg/inheritance.json`.
-- Output: `templates/<kind_dir>/<template_id>/<NNN>_<page_type>.svg`, where `<NNN>` is the zero-padded source slide index (3 digits) and `<page_type>` is derived from `manifest.json` `pageTypeCandidates` — `cover` / `toc` / `chapter` / `content` / `ending`. When the page-type heuristic is ambiguous, fall back to `content`. Preserve source slide order via the numeric prefix.
+- Output: `<template_target>/<NNN>_<page_type>.svg`, where `<template_target>` is the library package directory or the project `templates/` root. `<NNN>` is the zero-padded source slide index (3 digits) and `<page_type>` is derived from `manifest.json` `pageTypeCandidates` — `cover` / `toc` / `chapter` / `content` / `ending`. When the page-type heuristic is ambiguous, fall back to `content`. Preserve source slide order via the numeric prefix.
- Required metadata rewrite: declare the output Layout on the root, mark inherited Master/Layout visuals as direct preview layers, and map source content slots to semantic `data-pptx-placeholder` markers where the imported contract exposes them. Add `data-pptx-role` only to structural page-frame objects whose behavior is not already expressed by those specialized markers.
- Other allowed modifications: rewrite `<image href="...">` paths to local assets and rename assets semantically. Keep geometry, decoration, sprite-sheet wrappers, original example text, chart previews, and fonts visually unchanged.
- Forbidden: simplifying decorative complexity, merging similar slides, or dropping inherited preview chrome.
@@ -130,6 +134,10 @@ Re-declaring any of these in a template `design_spec.md` is noise — Strategist
**Required skeleton:**
+The frontmatter is portable across library and project scope. Do not add
+`output_scope` or `target_project`; those belong only to the workflow execution
+brief.
+
```markdown
---
template_id: <id>
@@ -284,7 +292,7 @@ Use clear placeholder markers for replaceable content:
### 4. Placeholder Reference (canonical convention, overridable per template)
-This is the **default vocabulary** used across the library. Newly created templates SHOULD prefer these names so projects that consume the library find familiar slots; designers MAY substitute or extend them when a style genuinely needs different vocabulary (e.g. consulting decks lead with `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`; a brand cover may need `{{BRAND_LOGO}}`).
+This is the **default vocabulary** used across template packages. Newly created templates SHOULD prefer these names so downstream projects find familiar slots; designers MAY substitute or extend them when a style genuinely needs different vocabulary (e.g. consulting decks lead with `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`; a brand cover may need `{{BRAND_LOGO}}`).
`svg_quality_checker.py --template-mode` emits **advisory warnings** when a page lacks the conventional placeholder for its type. To silence those warnings — and document the template's actual contract — declare a `placeholders:` map in `design_spec.md` frontmatter:
@@ -316,13 +324,13 @@ placeholders:
| `{{CLOSING_MESSAGE}}` | Closing message | Ending page | Style-specific |
| `{{COPYRIGHT}}` | Copyright | Ending page | Optional |
-For TOC pages in **newly created library templates**, use indexed placeholders:
+For TOC pages in **newly created templates**, use indexed placeholders:
- `{{TOC_ITEM_1_TITLE}}`, `{{TOC_ITEM_1_DESC}}`
- `{{TOC_ITEM_2_TITLE}}`, `{{TOC_ITEM_2_DESC}}`
- ...
-Do **not** create new TOC placeholder families such as `{{CHAPTER_01_TITLE}}` for new templates. Existing templates may contain legacy placeholder variants, but new library assets should converge on the indexed TOC contract.
+Do **not** create new TOC placeholder families such as `{{CHAPTER_01_TITLE}}` for new templates. Existing templates may contain legacy placeholder variants, but new output should converge on the indexed TOC contract.
Variants reuse their parent type's placeholder set by default: every `03*_content*.svg` shares the content placeholder list above, unless the spec frontmatter declares an override for that specific stem.
@@ -334,7 +342,7 @@ When rebuilding from imported PPTX references, placeholder insertion takes prior
### File Save Location
-Standard mode (default):
+Library scope keeps the existing self-contained package. Standard mode (default):
```
templates/<kind_dir>/<template_name>/
@@ -344,10 +352,11 @@ templates/<kind_dir>/<template_name>/
├── 02_toc.svg # Optional
├── 03_content.svg
├── 04_ending.svg
-└── *.png / *.jpg # Image assets (if any)
+├── icons/ # Extracted vector assets (if any)
+└── *.png / *.jpg # Bitmap assets (if any)
```
-Fidelity mode adds variants and extension pages, e.g.:
+Fidelity mode adds variants and extension pages in the same package, e.g.:
```
templates/<kind_dir>/<template_name>/
@@ -383,6 +392,26 @@ templates/<kind_dir>/<template_name>/
Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. Literal source text may remain, but every page still carries explicit native structure metadata.
+Project scope writes directly into an initialized project's existing roots. The roster names still follow the selected replication mode, but the package is not nested under `<template_name>`:
+
+```
+<target_project>/
+├── templates/
+│ ├── design_spec.md
+│ ├── 01_cover.svg
+│ ├── 02_chapter.svg
+│ ├── 03_content.svg
+│ ├── 04_ending.svg
+│ ├── ... # Fidelity variants or mirror pages
+│ └── icons/ # Package/validation copy
+├── images/
+│ └── *.png / *.jpg # Bitmap assets; template SVG href is ../images/<name>
+└── icons/
+ └── *.svg # Identical runtime copy of extracted icons
+```
+
+**Hard rule — project routing**: Keep `design_spec.md`, template SVGs, and non-bitmap package assets in `templates/`; place every bitmap in `images/`; duplicate each extracted icon into `templates/icons/` and runtime `icons/`. Do not write bitmaps into the project template root and do not create `<target_project>/templates/<template_name>/`. This output belongs only to the target project; use library scope for a self-contained cross-project package.
+
### Template Preview
After each template is generated, provide a brief summary table listing each template's status.
@@ -403,7 +432,7 @@ If suitable template resources already exist, use them directly instead of gener
2. **Adjust colors**: Modify colors per the project design spec
3. **Customize**: Make project-specific adjustments
-This section describes downstream reuse. The `Template_Designer` role itself is responsible for creating or normalizing the reusable library asset first.
+This section describes downstream reuse of an existing library package. The `Template_Designer` role may instead create the same contract directly in project scope when `create-template` selected that output.
**Example library structure** (query the appropriate kind's index — `templates/layouts/layouts_index.json` for structure-only templates, `templates/decks/decks_index.json` for full-PPT replicas, `templates/brands/brands_index.json` for identity-only presets):
@@ -428,11 +457,13 @@ templates/
## Template_Designer Phase Complete
- [x] Read `references/template-designer.md`
+- [x] Output scope confirmed: `library` | `project`; project-scope preflight passed before final writes
- [x] Replication mode confirmed: `standard` | `fidelity` | `mirror`
-- [x] Every page listed in `design_spec.md §V Page Roster` saved to `templates/<layouts|decks>/<template_name>/` (decks for full-PPT replicas, layouts for structure-only)
+- [x] Every page listed in `design_spec.md §V Page Roster` saved to the selected template target (library package directory or project `templates/` root)
- [x] Naming convention applied (standard / fidelity: letter-suffix variants; mirror: `<NNN>_<page_type>.svg`)
- [x] Templates follow design spec (colors, fonts, layout)
- [x] Placeholder markers are clear and standardized; mirror may keep literal text but still maps imported semantic slots
- [x] Every SVG is a complete preview with explicit Master/Layout/Slide/placeholder metadata and `native_structure_mode: template`
-- [ ] **Next step**: Validate assets and register the template via `register_template.py <id> --kind <deck|layout>`
+- [x] Project scope, when selected: bitmaps routed to `images/`; extracted icons copied to both `templates/icons/` and runtime `icons/`
+- [ ] **Next step**: Validate assets; register only library scope, otherwise hand the in-place project bundle to main Step 3
```
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index e4f3052c..31051945 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -6,11 +6,13 @@ description: Generate a new layout or deck template based on existing project fi
> **Role invoked**: [Template_Designer](../references/template-designer.md)
-Generate a complete set of reusable PPT templates for the **global template library**.
+Generate a complete layout/deck template package for either the **global template library** or one initialized project.
-> This workflow is for **library asset creation**, not project-level one-off customization. The output must be reusable by future PPT projects and discoverable from the appropriate index file.
+**Default — library scope**: Preserve the existing reusable-library behavior. Write `skills/ppt-master/templates/<kind>/<id>/` and register it in the matching discovery index.
-> **Boundary against template-fill**: this workflow does not fill content into a PPTX and does not directly output the user's final generated deck. It creates a reusable `templates/<kind>/<id>/` package. To generate a deck from that package, the user must provide the resulting template directory path to the main SKILL.md pipeline.
+**Project scope**: Write a thin template bundle directly into `<project>/templates/` for the named project. Do not add a nested template-ID directory and do not register any global index.
+
+> **Boundary against template-fill**: this workflow does not fill content into a PPTX and does not directly output the user's final generated deck. It creates a reusable template contract at the selected scope. To generate a deck from a library package, return its directory path to the main SKILL.md pipeline. A project-scoped package is already installed at that project's Step 3 path and is consumed in place.
> **Companion workflow**: identity-only locking (colors / typography / logo / voice without SVG pages) is handled by [`create-brand.md`](./create-brand.md). Use that when the user wants brand identity but free page layout; use this when fixed page structures are required.
@@ -18,17 +20,34 @@ Generate a complete set of reusable PPT templates for the **global template libr
This workflow produces one of two kinds of templates depending on whether the source PPT carries a specific brand identity:
-| Kind | When | Output dir | What `design_spec.md` writes |
+| Kind | When | Library-scope output dir | What `design_spec.md` writes |
|---|---|---|---|
| **deck** (default) | Source is a specific organization's branded PPT (e.g. company report, university defense template); the visual identity is part of the replica | `templates/decks/<id>/` | Full segments: identity + structure + middle |
| **layout** | Source is a generic stylistic template (no specific brand); only the structural skeleton should be reusable; color / typography decided per-deck downstream | `templates/layouts/<id>/` | Structure segments only (canvas / page structure / page types / SVG roster); identity segment omitted |
Default to **deck** unless the user explicitly says "structure only" / "layout only" / "no brand identity". When in doubt, lean deck — losing identity later is easy; reconstructing it from a layout-mode strip is not. See [`docs/zh/templates-architecture.md`](../../../docs/zh/templates-architecture.md) for the full kind / schema / fusion model.
+## Output scope — library (default) vs project
+
+Output scope is a workflow execution choice, not a new template kind or PPTX structure mode. Surface it in the Step 2 brief; do not invent a CLI flag or persist `output_scope` / `target_project` into portable `design_spec.md` frontmatter.
+
+| Scope | Final output | Asset routing | Registration |
+|---|---|---|---|
+| `library` (default) | `skills/ppt-master/templates/<kind_dir>/<template_id>/` | Keep the existing self-contained package: SVG/spec/assets under the package, including `icons/` when present | Run `register_template.py` against the matching global index |
+| `project` | `<target_project>/templates/` **root** | `design_spec.md`, template SVGs, and non-bitmap package assets → `templates/`; bitmaps → `images/` and SVG references → `../images/<name>`; extracted icon assets → both `templates/icons/` (package/validation copy) and `icons/` (runtime copy) | Do not update any global index; bundle belongs only to this target project |
+
+For `project`, `target_project` is required and must be an existing project initialized by `project_manager.py init`. Before the first final-output write, run one complete preflight:
+
+1. Confirm the target project and its `templates/`, `images/`, and `icons/` directories exist.
+2. Confirm `<target_project>/templates/` is empty.
+3. Resolve every final bitmap and extracted-icon filename, then confirm none would overwrite an existing file in `<target_project>/images/` or `<target_project>/icons/`.
+
+Any failed check aborts before writing `design_spec.md`, SVGs, images, or icons. Do not merge into a non-empty template root and do not overwrite a name conflict. Temporary Step 1 analysis workspaces remain allowed because they are not final project outputs.
+
## Process Overview
```
-Reference Intake & Analysis -> Basic Norm Extraction -> Fact-Based Brief Proposal -> User Confirmation Gate -> Create Directory + Invoke Template_Designer -> Validate Assets -> Register Index -> Output
+Reference Intake & Analysis -> Basic Norm Extraction -> Fact-Based Brief Proposal -> User Confirmation Gate -> Preflight + Invoke Template_Designer -> Validate Assets -> [Register Library Index] -> Output
```
The first three steps derive the brief from facts, not guesses. **No final template directory may be created and no template SVG / `design_spec.md` may be written until `[TEMPLATE_BRIEF_CONFIRMED]` is emitted in Step 3.** Reference-analysis intermediates produced by `pptx_template_import.py` (typically under `/tmp/pptx_template_import/`) are explicitly **not** subject to this gate — they are temporary workspaces feeding Step 2.
@@ -202,6 +221,8 @@ Compose a single message that surfaces every Required brief item to the user, **
| Field | Must show |
|---|---|
+| Output scope | Recommended `library` (existing default) plus `project`; explain that `project` writes directly into one initialized project's template root and skips global registration |
+| Target project | Required only for `project`; show the exact initialized project directory path, not a project nickname |
| Template kind | Recommended localized label with English ID, plus both options and the rule for choosing |
| Category | Recommended localized category with English ID, plus `brand` / `general` / `scenario` / `government` / `special` with localized explanations |
| Theme mode | Recommended localized mode with English ID, plus available modes such as `light` / `dark` / `mixed` with localized explanations |
@@ -215,7 +236,9 @@ Items to surface:
| Item | Required | Provenance by input type |
|------|----------|--------------------------|
-| New template ID | Yes | `[decision]` — user chooses ASCII slug; if Chinese brand name, must be filesystem-safe and match the target kind's index exactly |
+| Output scope | Yes | `[decision]` — `library` (default, globally reusable and indexed) or `project` (direct thin bundle for one initialized project) |
+| Target project | Yes for `project`; N/A for `library` | `[decision]` — explicit path to the initialized target project; validate it during the Step 4 preflight |
+| New template ID | Yes | `[decision]` — user chooses ASCII slug; if Chinese brand name, it must be filesystem-safe. In library scope it also becomes the matching index key |
| Template display name | Yes | `[decision]` (often the source deck title — `[suggested]` from `summary.md` for type A) |
| Category | Yes | `[decision]` — one of `brand` / `general` / `scenario` / `government` / `special` |
| Applicable scenarios | Yes | `[suggested]` from analysis; user confirms |
@@ -241,7 +264,7 @@ For type A, also include in this message:
The user replies with corrections, additions, or "all good".
-> **Persist the brief into `design_spec.md`**. When the Template_Designer writes `design_spec.md` in Step 4, declare a YAML frontmatter block at the top with the confirmed brief (`template_id`, `category`, `summary`, `keywords`, `primary_color`, `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, `source_viewbox`, `replication_mode`, `native_structure_mode`, etc.). `register_template.py` reads this in Step 6, so the brief flows directly into the index without the AI re-deriving it from prose. See Step 6 for the recommended frontmatter shape.
+> **Persist the portable brief into `design_spec.md`**. When the Template_Designer writes `design_spec.md` in Step 4, declare a YAML frontmatter block at the top with the confirmed portable fields (`template_id`, `category`, `summary`, `keywords`, `primary_color`, `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, `source_viewbox`, `replication_mode`, `native_structure_mode`, etc.). Do not persist the execution-only `output_scope` or `target_project` fields. In library scope, `register_template.py` reads this frontmatter in Step 6 so the brief flows directly into the index without the AI re-deriving it from prose.
---
@@ -260,28 +283,38 @@ Skipping this gate — including silently inferring values from the reference so
- [ ] Every finite-option field has shown a recommended value, other available options, and unavailable options with reasons when applicable
- [ ] User-facing labels and option explanations match the user's language; English enum IDs appear only as precision aids
- [ ] User has replied with values or explicit acceptance of suggested defaults
-- [ ] The template is clearly positioned as a **global library template**
+- [ ] Output scope is confirmed; `library` remains the default, while `project` includes an explicit initialized target-project path
- [ ] The canvas format is fixed before SVG generation
- [ ] Replication mode is consistent with the input type (`fidelity` / `mirror` allowed for A and B with B's caveats noted; forbidden for C / D)
- [ ] Basic template norms from prior content have been surfaced and accepted, or explicitly marked N/A when no reference exists
-- [ ] Metadata is complete enough to register into the relevant index
+- [ ] For `library`, metadata is complete enough to register into the relevant index; for `project`, the portable template metadata is complete and no global registration is planned
- [ ] Marker `[TEMPLATE_BRIEF_CONFIRMED]` emitted on its own line after the echoed brief
Step 4 MUST NOT run until `[TEMPLATE_BRIEF_CONFIRMED]` has been emitted in the current conversation.
---
-## Step 4: Create Template Directory + Invoke Template_Designer
+## Step 4: Preflight Output + Invoke Template_Designer
> **Precondition**: `[TEMPLATE_BRIEF_CONFIRMED]` was emitted in Step 3. If not, return to Step 3.
-Create the final template directory:
+Select the final target from the confirmed output scope:
```bash
+# library scope (default)
mkdir -p "skills/ppt-master/templates/<kind_dir>/<template_id>"
+
+# project scope
+# Do not create a nested template-ID directory. The initialized project already
+# owns <target_project>/templates/, images/, and icons/.
```
-> **Output location**: Templates go to `skills/ppt-master/templates/<kind>/<template_id>/`. The generated directory name must match the final template ID used in the relevant index.
+| Scope | Template target | Required action before generation |
+|---|---|---|
+| `library` | `skills/ppt-master/templates/<kind_dir>/<template_id>/` | Preserve the existing directory creation behavior; the generated directory name matches the final template ID used in the relevant index |
+| `project` | `<target_project>/templates/` | Run the full project preflight from "Output scope" above before any final-output write; stop on a non-empty template root or image/icon filename conflict |
+
+The project preflight is atomic at workflow level: discover and settle every output filename first, check all destinations together, then begin generation. Do not partially write a project bundle and discover a later collision.
**Switch to the Template_Designer role** and generate per role definition. The role input is the finalized brief from Step 3 plus the analysis bundle from Step 1, including the accepted basic template norms.
@@ -318,42 +351,50 @@ Downstream, both template-adherence choices stay on `pptx_structure.mode: templa
2. **Renames each file** using the source-order-first convention `<NNN>_<page_type>.svg`, where `<NNN>` is the source-order index zero-padded to 3 digits and `<page_type>` is typically `cover` / `toc` / `chapter` / `content` / `ending` (fall back to `content` when the type cannot be confidently classified). Examples: `001_cover.svg`, `002_toc.svg`, `003_content.svg`, ..., `050_ending.svg`.
- Type A: derive `<page_type>` from `manifest.json.pageTypeCandidates`
- Type B: derive `<page_type>` from the source filename when it follows the PPT Master convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); otherwise infer from page content or fall back to `content`
-3. **Copies bundled assets** into the template directory and rewrites the `<image href="...">` paths inside each copied SVG to point at the local copies. Asset filenames may be renamed to semantic names (`brand_emblem.png` instead of `image3.png`) when it improves readability — but the rewrite must be consistent across every page.
+3. **Routes bundled assets** according to the selected scope and rewrites every `<image href="...">` consistently. Asset filenames may be renamed to semantic names (`brand_emblem.png` instead of `image3.png`) when it improves readability.
- Type A: assets come from `<import_workspace>/assets/`
- Type B: resolve relative paths in source `<image href="...">` against the source SVG location and copy each unique asset; if the source already follows PPT Master conventions (assets co-located with SVGs in the same directory), copy the whole asset set and then rewrite paths
-4. **Copies `icons/` when present** and preserves every extracted `<use data-icon="..."/>` reference. Do not inline these assets manually in the template working SVGs; the shared icon embedding path owns re-inlining before export.
+ - Library scope: keep bundled assets inside the template package and point SVG references at those package-local files.
+ - Project scope: write bitmap assets to `<target_project>/images/`, point SVG references at `../images/<name>`, and keep other package assets under `<target_project>/templates/`.
+4. **Copies `icons/` when present** and preserves every extracted `<use data-icon="..."/>` reference. Library scope keeps one package copy under the template directory. Project scope writes the package/validation copy to `<target_project>/templates/icons/` and an identical runtime copy to `<target_project>/icons/`. Do not inline these assets manually in the template working SVGs; the shared icon embedding path owns re-inlining before export.
5. Writes `design_spec.md` per [template-designer.md](../references/template-designer.md) §1. The §V Page Roster remains the content-fit index; explicit SVG metadata is the native Master/Layout contract. Mirror is only the template-creation replication mode; downstream generation still treats the finished package as a selectable / reusable roster, not as a forced 1:1 slide sequence.
Mirror mode does not simplify the visual page, but it still reconstructs layer ownership. The sprite-sheet preservation rule applies because flat SVGs already contain the original crop wrappers; do not flatten them when annotating the page.
**Expected outputs from this step** (full spec → [template-designer.md](../references/template-designer.md)):
-1. `design_spec.md` — **personality only**. Required sections: Template Overview, Color Scheme, Signature Design Elements, Page Roster (matching the actual SVG files on disk). Skip Typography / Assets / Placeholder Overrides when they would just restate defaults. Declare brief frontmatter for `register_template.py`. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).
+1. `design_spec.md` — **personality only**. Required sections: Template Overview, Color Scheme, Signature Design Elements, Page Roster (matching the actual SVG files on disk). Skip Typography / Assets / Placeholder Overrides when they would just restate defaults. Declare portable brief frontmatter; `register_template.py` consumes it only in library scope. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).
2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` / `fidelity` / `mirror` mode rosters, variant naming, and TOC handling
3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.
- `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native reconstruction contract: root `data-pptx-layout` / `data-pptx-layout-name`, direct Master/Layout layers, and direct semantic `data-pptx-placeholder` markers. Minimal structural `data-pptx-role` hints are added only when those specialized markers cannot express required behavior. Both strict and adaptive downstream use set `mode: template` and require `page_layouts` plus `pptx_layouts` for every page.
-4. Template assets (optional) — Logos / PNG / JPG / reference SVG bundled with the template package
+4. Template assets (optional) — library scope bundles Logos / PNG / JPG / reference SVG inside the package; project scope applies the `templates/` / `images/` / dual-icon routing defined above
---
## Step 5: Validate Template Assets
+Set `<template_target>` to the selected output directory:
+
+| Scope | `<template_target>` |
+|---|---|
+| `library` | `skills/ppt-master/templates/<kind_dir>/<template_id>` |
+| `project` | `<target_project>/templates` |
+
```bash
-# Replace <kind_dir> with "decks" or "layouts" depending on the kind decided above
-ls -la "skills/ppt-master/templates/<kind_dir>/<template_id>"
+ls -la "<template_target>"
```
Run SVG validation on the template directory:
```bash
-python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/templates/<kind_dir>/<template_id>" --template-mode --format <canvas_format>
+python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_target>" --template-mode --format <canvas_format>
```
`--template-mode` makes the checker:
- glob `*.svg` in the template directory directly (templates do not live under `svg_output/`)
- skip `spec_lock.md` drift checks (templates do not ship a spec_lock)
-- enforce roster ↔ `design_spec.md` consistency as **errors** (orphan files / missing files break the target kind's index)
+- enforce roster ↔ `design_spec.md` consistency as **errors** (orphan files / missing files break the template contract and, in library scope, the target kind's index)
- emit advisory **warnings** when a page lacks a conventional placeholder — these are hints, not failures. Declare a `placeholders:` block in `design_spec.md` frontmatter to silence them when your template intentionally uses a different vocabulary
- require every SVG root to declare an output Layout and every SVG to contain at least one direct Master/Layout/placeholder declaration
- validate cross-page Master equality plus same-key Layout/placeholder equality
@@ -367,18 +408,25 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/temp
- [ ] `design_spec.md` frontmatter declares `canvas_format`, `canvas_width`, `canvas_height`, and `canvas_viewbox`; PPTX/SVG-backed templates also declare `source_canvas_width`, `source_canvas_height`, and `source_viewbox`
- [ ] SVG `viewBox` matches the declared canvas dimensions, not just the aspect ratio (for `ppt169`: `0 0 1280 720`; for `banner`: `0 0 1920 1080`); `width` / `height`, if written, equal it
- [ ] Placeholder names follow the canonical convention where applicable; templates with intentionally different vocabularies (e.g. `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`) should declare a `placeholders:` frontmatter block to silence advisory warnings
-- [ ] Asset files referenced by SVGs actually exist in the template package
+- [ ] Asset files referenced by SVGs exist at their resolved paths. In project scope, bitmap references resolve through `../images/`; no bitmap remains accidentally stranded in `templates/`
- [ ] `design_spec.md` frontmatter declares `native_structure_mode: template`; no `native_structure.json` or `source_template.pptx` is packaged
- [ ] Every SVG root declares `data-pptx-layout` and `data-pptx-layout-name`; direct Master/Layout elements and semantic placeholders obey the explicit paint-order contract. Structural `data-pptx-role` is used only when specialized metadata cannot express required package/page-number/animation behavior
-- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists directly under the package's `icons/` directory; do not add a separate illustration embedding script
+- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists under the package's `icons/` directory. Project scope also has the identical runtime copy under `<target_project>/icons/`; do not add a separate illustration embedding script
- [ ] For `fidelity` mode: every sprite-sheet asset retains its nested `<svg viewBox=...>` crop wrapper; no image whose file aspect differs from its on-page aspect was flattened to a bare `<image>`
-- [ ] For `mirror` mode: file count equals source page count (type A: `ls templates/<kind_dir>/<id>/*_*.svg | wc -l` matches the cleaned flat `<import_workspace>/svg-flat/slide_*.svg | wc -l`; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no `{{...}}` placeholder strings appear in any copied SVG** (`grep -l "{{" templates/<kind_dir>/<id>/*.svg` should return nothing — if the type B source itself contains placeholders, the user should be in `standard` mode, not `mirror`); §V Page Roster in `design_spec.md` lists every emitted file with a one-line description of what the page contains and what content slot it suits
+- [ ] For `mirror` mode: file count equals source page count (type A: `<template_target>/*_*.svg` matches the cleaned flat `<import_workspace>/svg-flat/slide_*.svg` count; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no `{{...}}` placeholder strings appear in any copied SVG** (`grep -l "{{" "<template_target>"/*.svg` should return nothing — if the type B source itself contains placeholders, the user should be in `standard` mode, not `mirror`); §V Page Roster in `design_spec.md` lists every emitted file with a one-line description of what the page contains and what content slot it suits
-This step is a **hard gate**. Do not register a template into the library index until validation passes.
+This step is a **hard gate**. In library scope, do not register until validation passes. In project scope, do not hand the in-place bundle to the main pipeline until validation passes.
---
-## Step 6: Register Template in Library Index
+## Step 6: Register Template in Library Index (Library Scope Only)
+
+Branch on the confirmed output scope:
+
+| Scope | Action |
+|---|---|
+| `library` | Run the registrar below after Step 5 passes |
+| `project` | Skip the registrar entirely. Do not edit `decks_index.json`, `layouts_index.json`, or any library README; continue to Step 7 with index status `Not registered (project-local)` |
Run the unified registrar with the kind flag; it derives the corresponding index entry from `design_spec.md` (frontmatter when present, prose fallback otherwise) plus the actual SVG file list:
@@ -454,7 +502,7 @@ README files describe each kind in prose only — they do not list templates. Di
## Step 7: Output Confirmation
-`register_template.py` already printed a "Template Creation Complete" card during Step 6 — copy it verbatim into the conversation. The card includes the template name, path, category, primary color, index status, and the full SVG file roster (auto-collected from disk, so `fidelity`-mode variant pages and TOC pages are listed correctly without manual editing).
+For `library`, `register_template.py` already printed a "Template Creation Complete" card during Step 6 — copy it verbatim into the conversation. The card includes the template name, path, category, primary color, index status, and the full SVG file roster (auto-collected from disk, so `fidelity`-mode variant pages and TOC pages are listed correctly without manual editing).
For a standard-mode template the card looks like:
@@ -478,6 +526,29 @@ For a standard-mode template the card looks like:
| `04_ending.svg` | Done |
```
+For `project`, produce the same evidence-driven file roster from `<target_project>/templates/*.svg`, but use this scope-aware card:
+
+```markdown
+## Template Creation Complete
+
+**Template Name**: <template_id> (<display_name>)
+**Kind**: deck | layout
+**Output Scope**: project
+**Template Path**: `<target_project>/templates/`
+**Bitmap Path**: `<target_project>/images/`
+**Runtime Icon Path**: `<target_project>/icons/`
+**Index Registration**: Not registered (project-local)
+
+### Files Included
+
+| File | Status |
+|------|--------|
+| `design_spec.md` | Done |
+| `<actual-template>.svg` | Done |
+```
+
+The next main-pipeline Step 3 input is the exact `<target_project>/templates/` path. It is an in-place bundle: do not copy it onto itself and do not move its `../images/` assets again. Do not reuse this root from another project; choose library scope when cross-project portability is required.
+
---
## Color Scheme Quick Reference
@@ -496,6 +567,6 @@ For a standard-mode template the card looks like:
1. **SVG technical constraints**: See [shared-standards.md](../references/shared-standards.md) — do not restate them in the template's `design_spec.md`
2. **Color consistency**: All SVG files must use the same color scheme as `design_spec.md §II Color Scheme`
3. **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.
-4. **Discovery requirement**: A template directory is only discoverable after `register_template.py` has been run against it (Step 6)
+4. **Discovery requirement**: A library template is discoverable only after `register_template.py` has been run against it (Step 6). A project-scoped template intentionally stays out of global discovery and is consumed by its explicit `<project>/templates/` path.
> **Full role specification**: [template-designer.md](../references/template-designer.md)
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
index 140a846b..118ad67e 100644
--- a/skills/ppt-master/workflows/index.md
+++ b/skills/ppt-master/workflows/index.md
@@ -17,7 +17,7 @@ Registry for standalone workflows referenced by `SKILL.md` and [`routing.md`](./
| `topic-research` | [`topic-research.md`](./topic-research.md) | Topic-only request with no substantive source material | Topic or requirements exist | Do not invent facts in the main pipeline | Before `SKILL.md` Step 1 | Source material suitable for Step 1 | Stops if usable source facts cannot be gathered |
| `template-fill-pptx` | [`template-fill-pptx.md`](./template-fill-pptx.md) | Raw PPTX template plus new material/topic; clone/fill native slides | Source PPTX plus content material or topic brief | No SVG generation; no `create-template` unless reusable package is requested | Workflow Step 1 | Native PPTX in project `exports/` | Stops if no PPTX or no fill material |
| `beautify-pptx` | [`beautify-pptx.md`](./beautify-pptx.md) | Existing PPTX should be re-laid out while preserving slide count/order and wording 1:1 | Single source PPTX | Not for merge/split/drop/reorder or re-outline | Workflow Step 1 | Regenerated 1:1 deck through SVG pipeline | Blocks on source-slide mapping and final confirmation gates defined in the workflow |
-| `create-template` | [`create-template.md`](./create-template.md) | Build a reusable layout/deck template from a PPTX or design reference | Design source or explicit template-creation request | Not a one-off generated deck | Workflow Step 1 | Template directory with `design_spec.md` and assets | Stops after template creation until user supplies the directory path to main Step 3 |
+| `create-template` | [`create-template.md`](./create-template.md) | Build a reusable layout/deck template from a PPTX or design reference, globally or for one initialized project | Design source or explicit template-creation request; project scope also requires an initialized target project | Does not fill final content or emit the generated deck | Workflow Step 1 | Library scope (default): indexed `templates/<kind>/<id>/`; project scope: in-place `<project>/templates/` bundle with bitmaps in `images/` and no global registration | Library scope stops until the user supplies the directory path to main Step 3; project scope may continue with its in-place path after validation |
| `create-brand` | [`create-brand.md`](./create-brand.md) | Build/extract a reusable brand identity preset | Logo/site/branded deck/PDF or explicit brand setup request | Not a layout/deck template roster | Workflow Step 1 | Brand directory under `templates/brands/<id>/` | Blocks on brand evidence and validation defined in the workflow |
| `resume-execute` | [`resume-execute.md`](./resume-execute.md) | Continue an existing split-mode project | Planning-session artifacts exist | Do not re-run planning | Execution-session entry | SVG generation, post-processing, export | Stops if `design_spec.md` or `spec_lock.md` is missing |
| `refine-spec` | [`refine-spec.md`](./refine-spec.md) | User explicitly opts into spec refinement before generation | Strategist confirmation stage completed | Do not enter by default | After Step 4, before Step 5/6 | Revised `design_spec.md` and `spec_lock.md` | Blocks for user review/approval before generation |
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index 738e2553..e9fbf189 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -42,7 +42,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Topic only, no source facts | User supplies only a topic name or requirement and no substantive source material | [`topic-research`](./topic-research.md), then main `SKILL.md` pipeline | Direct main pipeline with invented facts | Web/source gathering is allowed or user supplies facts | Research material becomes source input for Step 1 | Stop if facts cannot be gathered and the user supplies no source |
| Source material can be reworked into a new story | PDF/DOCX/URL/Markdown/text/conversation content, or PPTX treated as content | Main `SKILL.md` pipeline | Direct PPTX edit workflows | Source content exists or is available in conversation | `design_spec.md`, `spec_lock.md`, `svg_output/`, exported PPTX | Stop at Step gates when required artifacts are missing |
| PPTX as re-architectable source | User allows page count/order/outline to change, or asks to split/merge/drop/reorder slides | Main `SKILL.md` pipeline with `ppt_to_md.py` plus PPTX intake | [`beautify-pptx`](./beautify-pptx.md) | PPTX source exists | Markdown content plus `analysis/source_profile.json`; Strategist may re-outline | Stop if user requires exact 1:1 page preservation |
-| Explicit template directory path | User provides a directory containing `design_spec.md` with `kind: brand`, `kind: layout`, or `kind: deck` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name | Path resolves and frontmatter kind is valid | Template assets copied/fused into `<project>/templates/` | Stop if the path does not exist or lacks valid `design_spec.md` |
+| Explicit template directory path | User provides a directory containing `design_spec.md` with `kind: brand`, `kind: layout`, or `kind: deck` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name | Path resolves and frontmatter kind is valid | External assets are copied/fused into `<project>/templates/`; the same project's own `templates/` path is consumed in place | Stop if the path does not exist or lacks valid `design_spec.md` |
---
@@ -53,7 +53,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Raw PPTX template plus new material/topic | "Use this PPT template to generate a PPTX", "fill this deck", "replace copy", native slide shell reuse | [`template-fill-pptx`](./template-fill-pptx.md) | Main SVG pipeline directly from raw PPTX template | Source PPTX plus content material or topic brief | New native PPTX in `exports/`, cloned/patched by OOXML | Stop if user instead wants a reusable template package |
| Existing PPTX, preserve page split and wording | "Beautify", "re-layout", "make more professional" with same slide count/order and verbatim text | [`beautify-pptx`](./beautify-pptx.md) | Main pipeline if page count/order changes | Single source PPTX | Regenerated deck through SVG pipeline, one source slide to one output slide | Stop if user asks to split/merge/drop/reorder |
| Finished PPTX, native enhancement only | Add notes, recorded narration, auto-advance, transitions, or stable-layout metadata | [`native-enhance-pptx`](./native-enhance-pptx.md) | SVG regeneration | Finished PPTX exists; content/layout should stay stable | Patched PPTX through direct OOXML | Stop if user asks for visual redesign |
-| PPTX/reference design should become a reusable template | "Create a template", "make reusable", "build template from this deck/design" | [`create-template`](./create-template.md) | `template-fill-pptx` one-off fill | PPTX or design reference exists | Template directory under `templates/<kind>/<id>/` | Stop after creation; main pipeline resumes only when user supplies the generated directory path |
+| PPTX/reference design should become a reusable template | "Create a template", "make reusable", "build template from this deck/design", including a template for one named initialized project | [`create-template`](./create-template.md) | `template-fill-pptx` one-off fill | PPTX/design reference exists, or the user gives an explicit template-creation brief; project output additionally requires an initialized target project | Library scope (default): `templates/<kind>/<id>/` plus index registration; project scope: direct `<project>/templates/` thin bundle with no global registration | Stop after library creation until the user supplies its directory path; project scope may resume main Step 3 with the in-place `<project>/templates/` path |
**Hard rule**: Raw PPTX template plus "generate PPTX" routes to `template-fill-pptx` by default. A raw PPTX is not a Step 3 template until `create-template` has produced a reusable template directory.