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): clarify evidence and compact roster contracts
hugohe34e6007248e2c
diff --git a/docs/templates-guide.md b/docs/templates-guide.mdindex 1f0a56b9..e97b1cc3 100644--- a/docs/templates-guide.md+++ b/docs/templates-guide.md@@ -125,7 +125,7 @@ The entry name always remains **Create Template**. It dispatches exactly one chi### Step 1 — Prepare a reference bundle or brief-You may provide direct conversation text, pasted requirements, Markdown/TXT, DOCX/PDF/HTML/URL, websites, images/screenshots, logo/icon/font assets, PPTX/SVG files, or any useful combination. The workflow analyzes every applicable channel, keeps source provenance, and surfaces conflicts in the mandatory brief instead of silently choosing one source. Exact values stated by you are decisions; traceable statements from identified manuals or official sites are facts; visual estimates and vague-text interpretations remain suggestions until confirmed.+You may provide direct conversation text, pasted requirements, Markdown/TXT, DOCX/PDF/HTML/URL, websites, images/screenshots, logo/icon/font assets, PPTX/SVG files, or any useful combination. The workflow analyzes every applicable channel, keeps source provenance, and surfaces conflicts in the mandatory brief instead of silently choosing one source. Exact values authored by you are decisions whether they arrive in chat, pasted text, or your own brief file; a file carrier does not turn them into facts. Facts require independently traceable external authority or machine-observable source metadata. Visual estimates and vague-text interpretations remain suggestions until confirmed.**When an existing deck's native structure matters, hand over the original `.pptx` file.** The importer reads OOXML directly and extracts the Master, Layout, placeholder, theme, native-shape, and reusable-asset facts that are actually present and supported into layered analysis references. In `standard` / `fidelity`, Template_Designer uses them as visual reference and authors a new SVG roster plus a new Master/Layout/slot system. In mirror, it materializes those validated source facts into a new workspace without inventing missing topology or design intent. The original PPTX remains immutable analysis evidence and is not packaged into the new template.@@ -149,7 +149,7 @@ The workflow does not silently infer values — before generation it lists these| **Tone summary** | One line, e.g. "modern, restrained, data-driven" || **Theme mode** | Create Layout/Create Deck only: light / dark / gradient / ... || **Canvas format** | Create Layout/Create Deck only; default `ppt169` (16:9), with other formats specified up front |-| **Replication mode** | Create Layout/Create Deck only: `standard` (default compact roster) / `fidelity` (one variant per reusable semantic family) / `mirror` (one materialized prototype per source slide). `standard` / `fidelity` author new SVG semantics; mirror preserves only validated facts already present in the source package. |+| **Replication mode** | Create Layout/Create Deck only: `standard` (default compact, brief-driven roster; may include a small number of explicitly required distinct variants) / `fidelity` (broader source-aligned coverage of useful semantic families) / `mirror` (one materialized prototype per source slide). `standard` / `fidelity` author new SVG semantics; mirror preserves only validated facts already present in the source package. || **Native structure facts** | Create Layout/Create Deck only: the brief reports source Master/Layout counts, parent relationships, placeholder identities, and multi-master status. `standard` / `fidelity` treat them as reference only; mirror maps the supported facts one-to-one into the current `structured` contract. || **Visual fidelity** | Create Layout/Create Deck only; required for `standard` / `fidelity` when a reference exists. Choose `literal` or `adapted`. **Not asked for `mirror`** — mirror preserves the supported source visual. || **Keywords** | 3–5 tags for index lookup |@@ -157,7 +157,7 @@ The workflow does not silently infer values — before generation it lists theseAfter 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.**-Before either scope writes final files, one hard preflight resolves the required `templates/` destination and any optional asset destinations, requires an empty `templates/` root, and rejects bitmap or imported-vector filename collisions in `images/` and `icons/imported/`. It checks `exports/` only when a review PPTX was requested. Project scope additionally requires an initialized target project. A failed check stops before partial output; the workflow does not merge or overwrite.+Before either scope writes final files, one hard preflight resolves the required `templates/` destination and any optional asset destinations, requires an empty `templates/` root, and rejects bitmap or imported-vector filename collisions in `images/` and `icons/imported/`. It checks `exports/` only when a review PPTX was requested. Project scope additionally requires an initialized target project. Existing empty scaffolding created by project initialization is allowed and left untouched; Create Template does not create optional directories merely to keep empty paths. 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.@@ -167,10 +167,10 @@ This is the most easily confused decision when deriving a structured template. C| | **standard** | **fidelity** | **mirror** ||---|---|---|---|-| Output pages | 4–5 (cover / chapter / content / ending, with optional TOC) | one variant per reusable semantic family — count driven by the source | one materialized prototype per source slide (1:1 roster) |+| Output pages | Usually 4–6: cover / chapter / ending, optional TOC, and one or a small explicitly required set of content Layouts | broader useful semantic-family coverage — count driven by the source evidence | one materialized prototype per source slide (1:1 roster) || Abstraction | High — clean, reusable skeleton | Medium — semantic source families redesigned with cleanup | None at the topology level; only mechanical structured-contract normalization || Authoring placeholders | Yes (`{{TITLE}}`, `{{CONTENT_AREA}}`, …) | Yes | Literal text may remain, but imported native content slots still carry semantic metadata |-| Best for | You want "tone + basic skeleton" to generate brand-new decks later | The source PPTX itself is a customized layout library and every variant matters | Someone else's polished deck is great as-is, you want every page available as a reference |+| Best for | You want "tone + compact skeleton", including a few brief-required structures, to generate brand-new decks later | The source PPTX itself is a customized layout library and broader source-driven coverage matters | Someone else's polished deck is great as-is, you want every page available as a reference || Typical use | Building a base brand template | Replicating a 20-variant government briefing layout set | Keeping all 50 source compositions available as faithful prototypes || Source requirement | None | PPTX or SVG visual reference | PPTX, or SVGs with a complete explicit structure contract || Decoration complexity | Usually simpler | Must preserve sprite-sheet crop structure | Preserves literal geometry while adding explicit layer ownership |@@ -199,7 +199,7 @@ the designer writes that brief against the published roster.### Step 4 — Validation, review export, registration, and discovery-After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) as a hard gate. If you want a PowerPoint review file, run the optional preview export; it creates `exports/<id>_template_preview.pptx` on demand. The only scope-specific action is library registration:+After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) as a hard gate: Brand validates its identity-only spec and asset references, while Layout/Deck validate the SVG roster and structured contract. If you want a PowerPoint review file, run the optional preview export; it creates `exports/<id>_template_preview.pptx` on demand. Authored templates use concise preview-only placeholder samples so long canonical markers stay readable without changing the source SVGs. The only scope-specific action is library registration:| Scope | Workspace root | Preview | Discovery behavior ||---|---|---|---|@@ -224,8 +224,7 @@ Library and project scopes use the same core structure; substitute either `skill│ ├── 01_cover.svg│ ├── 02_toc.svg # optional; without it: 02_chapter, 03_content, 04_ending│ ├── 03_chapter.svg-│ ├── 04_content.svg-│ ├── 04a_content_two_col.svg # fidelity variant+│ ├── 04_content.svg # use 04a/04b siblings when multiple variants exist│ └── 05_ending.svg├── images/ # optional│ └── *.png / *.jpg # SVG references use ../images/<name>diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex 54996adb..0a750e6b 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -125,7 +125,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG### 第一步:准备参考材料包或简报-你可以直接在对话中输入文字或粘贴要求,也可以提供 Markdown/TXT、DOCX/PDF/HTML/URL、网站、图片/截图、logo/icon/字体资产、PPTX/SVG,或这些材料的任意组合。工作流会分析每个适用通道,保留来源,并在强制简报中暴露冲突,而不是静默选择某一个来源。你明确写出的值属于决策;来自已识别手册或官网的可追溯陈述属于事实;视觉估算与模糊文字的解释在确认前都只是建议。+你可以直接在对话中输入文字或粘贴要求,也可以提供 Markdown/TXT、DOCX/PDF/HTML/URL、网站、图片/截图、logo/icon/字体资产、PPTX/SVG,或这些材料的任意组合。工作流会分析每个适用通道,保留来源,并在强制简报中暴露冲突,而不是静默选择某一个来源。凡是你本人明确写出的值,无论来自对话、粘贴文字还是你编写的简报文件,都属于决策;文件载体本身不会把它变成事实。事实必须来自可独立追溯的外部权威,或可由机器直接观察的源文件/包元数据。视觉估算与模糊文字的解释在确认前都只是建议。**当现有演示文稿的原生结构很重要时,请直接提供原始 `.pptx` 文件。** 导入器会读取 OOXML,把包内实际存在且受支持的 Master、Layout、placeholder、主题、原生形状与可复用素材事实提取成分层分析参考。`standard` / `fidelity` 把它们当视觉参考,创作新的 SVG roster 与 Master/Layout/slot 系统;mirror 则把这些已验证的来源事实物化到新工作区,不补造缺失拓扑或设计意图。原 PPTX 始终是不可变的分析证据,不进入新模板包。@@ -149,7 +149,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG| **调性概要** | 一句话,如"现代克制、数据驱动" || **主题模式** | 仅 Create Layout/Create Deck:浅色 / 深色 / 渐变…… || **画布格式** | 仅 Create Layout/Create Deck;默认 `ppt169`(16:9),其他格式需提前指定 |-| **复刻模式** | 仅 Create Layout/Create Deck:`standard`(默认精简基本套)/ `fidelity`(每个可复用语义家族一个变体)/ `mirror`(每张源页一个物化原型)。`standard` / `fidelity` 创作新 SVG 语义;mirror 只保留来源包内已经存在且验证通过的事实。 |+| **复刻模式** | 仅 Create Layout/Create Deck:`standard`(默认精简、由确认简报驱动;可包含少量明确要求的差异化变体)/ `fidelity`(根据来源证据覆盖更广的有用语义家族)/ `mirror`(每张源页一个物化原型)。`standard` / `fidelity` 创作新 SVG 语义;mirror 只保留来源包内已经存在且验证通过的事实。 || **原生结构事实** | 仅 Create Layout/Create Deck:简报会列出源 Master/Layout 数量、父子关系、placeholder 身份和多母版情况。`standard` / `fidelity` 只把它们当参考;mirror 把受支持事实一对一映射进当前 `structured` 合同。 || **保真级别** | 仅 Create Layout/Create Deck;`standard` / `fidelity` 有源时必填,选择 `literal` 或 `adapted`。**`mirror` 模式不询问**——它保留受支持的来源视觉。 || **关键词** | 3–5 个标签,用于索引检索 |@@ -157,7 +157,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG确认后,工作流会回显一份完整简报并写入标记 `[TEMPLATE_BRIEF_CONFIRMED]`,从这一刻起后续步骤才会启动。**这是一个硬门——简报没确认,不会开始生成**。-无论选择哪种范围,第一次写最终文件前都会做一次完整预检:解析必需的 `templates/` 和实际需要的可选素材目录,要求 `templates/` 为空,并检查 `images/` 与 `icons/imported/` 中计划写入的位图和导入向量文件名没有冲突;只有明确要求审阅 PPTX 时才检查 `exports/`。项目范围还要求目标项目已经初始化。任一检查失败都会在写入前停止,不合并、不覆盖,也不会留下半套输出。+无论选择哪种范围,第一次写最终文件前都会做一次完整预检:解析必需的 `templates/` 和实际需要的可选素材目录,要求 `templates/` 为空,并检查 `images/` 与 `icons/imported/` 中计划写入的位图和导入向量文件名没有冲突;只有明确要求审阅 PPTX 时才检查 `exports/`。项目范围还要求目标项目已经初始化。项目初始化时已存在的空脚手架目录可以保留且不会被算作模板产物;Create Template 不会为了保留空路径而新建可选目录。任一检查失败都会在写入前停止,不合并、不覆盖,也不会留下半套输出。> 为什么这么严?无论模板进入全局库,还是只服务当前项目,它都是结构契约。先确认归属和几何,可避免半成品或资产落错目录。@@ -167,10 +167,10 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG| | **standard** | **fidelity** | **mirror** ||---|---|---|---|-| 输出页数 | 4–5 页(封面/章节/内容/结尾,可选目录) | 每个可复用语义家族一个变体——数量由源决定 | 每张源页一个物化原型(1:1 页面集合) |+| 输出页数 | 通常 4–6 页:封面/章节/结尾、可选目录,以及一个或少量简报明确要求的内容 Layout | 覆盖来源证据中更广的有用语义家族——数量由来源决定 | 每张源页一个物化原型(1:1 页面集合) || 抽象程度 | 高 —— 干净可复用骨架 | 中 —— 语义家族重新设计 | 拓扑层面不抽象,只做 structured 合同要求的机械归一化 || 作者占位符 | 是(`{{TITLE}}`、`{{CONTENT_AREA}}` 等) | 是 | 可保留原文字,但导入识别出的原生内容槽仍带语义 metadata |-| 适合场景 | 你只需要"调性 + 基本骨架",未来用模板生成全新 deck | 源 PPTX 本身就是高度定制的版式库 | 别人的精装 deck 直接好用、想把每页都当参考页 |+| 适合场景 | 你需要“调性 + 精简骨架”,也可能包含少量简报明确要求的结构,未来用于生成全新 deck | 源 PPTX 本身就是高度定制的版式库,需要更广的来源驱动覆盖 | 别人的精装 deck 直接好用、想把每页都当参考页 || 典型例子 | 给品牌做基础模板 | 复刻一套政府汇报的 20 种章节版式 | 把 50 张源构图都保留为视觉忠实的模板原型 || 来源要求 | 无 | PPTX 或 SVG 视觉参考 | PPTX,或带完整显式结构合同的 SVG || 装饰复杂度 | 通常较简洁 | 需要保留精灵图裁剪等结构 | 保留原几何,并补齐显式层级归属 |@@ -197,7 +197,7 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \### 第四步:验证、预览导出、注册与发现-模板生成完,两种范围都会先跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 作为硬门。如果需要 PowerPoint 审阅文件,再运行可选预览导出;它会按需创建 `exports/<id>_template_preview.pptx`。唯一按范围分流的动作是全局注册:+模板生成完,两种范围都会先跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 作为硬门:Brand 校验 identity-only 规范与素材引用,Layout/Deck 校验 SVG roster 和 structured 合同。如果需要 PowerPoint 审阅文件,再运行可选预览导出;它会按需创建 `exports/<id>_template_preview.pptx`。创作型模板会只在临时预览副本中使用简短占位示例,避免较长的 canonical marker 换行,不会修改源 SVG。唯一按范围分流的动作是全局注册:| 范围 | 工作区根目录 | 预览 | 发现行为 ||---|---|---|---|@@ -222,8 +222,7 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \│ ├── 01_cover.svg│ ├── 02_toc.svg # 可选;不含时为 02_chapter、03_content、04_ending│ ├── 03_chapter.svg-│ ├── 04_content.svg-│ ├── 04a_content_two_col.svg # fidelity 变体+│ ├── 04_content.svg # 同类有多个变体时改用 04a/04b 兄弟命名│ └── 05_ending.svg├── images/ # 可选│ └── *.png / *.jpg # SVG 统一引用 ../images/<name>diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex 2d64efc5..9bb7d76b 100644--- a/skills/ppt-master/references/template-designer.md+++ b/skills/ppt-master/references/template-designer.md@@ -96,8 +96,8 @@ The output page set is determined by **replication mode**, declared in the final| Mode | When to use | Roster ||------|-------------|--------|-| `standard` (default) | Most templates — clean, reusable, balanced coverage | `01_cover`, `02_chapter`, `03_content`, `04_ending`; with the optional TOC the roster is `01_cover`, `02_toc`, `03_chapter`, `04_content`, `05_ending` |-| `fidelity` | User wants a broader, source-aligned but newly designed template | Standard roster + intentionally designed variants that cover useful reference compositions |+| `standard` (default) | Most templates — clean, reusable, compact coverage driven by the confirmed brief | Cover, chapter, ending, optional TOC, and one or a small explicitly required set of distinct content Layouts; typically 4–6 prototypes |+| `fidelity` | User wants a broader, source-aligned but newly designed template | Canonical roles plus intentionally designed variants that cover the useful source composition range || `mirror` | User wants a new template workspace that preserves validated native source facts | One SVG prototype materialized from the authoring IR per source slide, named `<NNN>_<page_type>.svg` by source order |**Hard rule — mode controls authorship**: `standard` and `fidelity` create new SVG documents and their own Master/Layout system. `mirror` maps the validated imported source contract into a new workspace and must not reauthor, distill, reinterpret, or supplement its structure.@@ -114,7 +114,9 @@ The output page set is determined by **replication mode**, declared in the final**Design philosophy**: Templates define visual consistency and structural pages; content pages maintain maximum flexibility.-**Naming note**: The numeric prefix is the template's own presentation order and stays contiguous with no duplicate index. When the optional TOC page is included it takes `02_toc.svg` and the later types shift by one: `01_cover`, `02_toc`, `03_chapter`, `04_content`, `05_ending`. Numbers carry no meaning across templates — tooling derives the page type from the token after the underscore, so both spellings of each type are equivalent.+**Confirmed compact variants**: `standard` may include more than one Layout for the same canonical role when the user brief explicitly requires genuinely different reusable structures, such as two-column evidence and three-card KPI content. Keep the roster compact and brief-driven rather than mining the source page set. When siblings exist, suffix every sibling (`03a_content_two_col.svg`, `03b_content_three_card.svg`) instead of treating one arbitrary variant as the unsuffixed default. This does not require `fidelity`; use `fidelity` when the broader roster is derived from complete PPTX/SVG page evidence.++**Naming note**: The numeric prefix is the template's own presentation order. Its base sequence stays contiguous; sibling variants share their parent's number only through unique lowercase suffixes such as `03a` / `03b`. When the optional TOC page is included it takes `02_toc.svg` and the later types shift by one: `01_cover`, `02_toc`, `03_chapter`, `04_content`, `05_ending`. Numbers carry no meaning across templates — tooling derives the page type from the token after the underscore, so both spellings of each type are equivalent.### Fidelity mode@@ -533,11 +535,11 @@ Mirror mode emits one SVG per source slide, named by source order:Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. Literal source text and validated native structure facts are preserved when the authoring IR is materialized into the new workspace; IR-only refs and its manifest are not copied into the template output.-**Hard rule — common routing**: Keep `design_spec.md`, template SVGs, and non-bitmap template-source assets in `templates/`; place every bitmap in `images/`; place each imported vector exactly once in `icons/imported/` and reference it as `data-icon="imported/<name>"`. Never create `templates/icons/`. Write a review deck to `exports/` when explicitly requested and always for a multi-Master package gate. Create optional directories only when they contain real files; never add placeholders for empty directories. Do not branch asset placement by output scope.+**Hard rule — common routing**: Keep `design_spec.md`, template SVGs, and non-bitmap template-source assets in `templates/`; place every bitmap in `images/`; place each imported vector exactly once in `icons/imported/` and reference it as `data-icon="imported/<name>"`. Never create `templates/icons/`. Write a review deck to `exports/` when explicitly requested and always for a multi-Master package gate. Create Template must not create optional directories or placeholder files solely to retain empty paths. An initialized project may already contain empty scaffolding; leave it untouched and omit it from completion unless real template files were written or adopted there. Do not branch asset placement by output scope.### Template Preview-When the user requests a PowerPoint review file or the validated roster declares multiple Masters, run `template_preview_pptx.py <template_workspace>` after SVG validation. The command creates `exports/` on demand and verifies one slide per SVG prototype plus the expected Master/Layout counts. The first export refuses a collision; an intentional post-fix replacement uses `--force`. The review PPTX is derived evidence and never a template-application input.+When the user requests a PowerPoint review file or the validated roster declares multiple Masters, run `template_preview_pptx.py <template_workspace>` after SVG validation. The command creates `exports/` on demand and verifies one slide per SVG prototype plus the expected Master/Layout counts. In authored modes, it shortens canonical marker text only in ephemeral review copies so prompts remain readable without changing the source SVG, carrier typography, or placeholder frames. The first export refuses a collision; an intentional post-fix replacement uses `--force`. The review PPTX is derived evidence and never a template-application input.When a review deck was generated, include its path in the completion summary. Omit `exports/` only for an unrequested one-Master package.@@ -587,7 +589,7 @@ templates/- [x] Naming convention applied (standard / fidelity: letter-suffix variants; mirror: `<NNN>_<page_type>.svg`)- [x] Templates follow design spec (colors, fonts, layout)- [x] `standard` / `fidelity` SVGs and Master/Layout contracts were newly authored; `mirror` SVGs were materialized from the authoring IR while preserving the source graph without semantic redesign-- [x] Placeholder markers are clear and standardized for `standard` / `fidelity`; mirror preserves literal source text plus source placeholder type/index/bounds+- [x] Placeholder markers are clear and standardized for `standard` / `fidelity`; preview-only sample text remains readable without changing source markers, while mirror preserves literal source text plus source placeholder type/index/bounds- [x] Every SVG is a complete preview with explicit root Master/Layout identity and `native_structure_mode: structured`; authored modes use canonical fixed layers/slots, while mirror preserves source ownership and mechanically expands fixed-layer groups into direct atoms- [x] Authored `standard` / `fidelity` Layout keys are non-duplicative; mirror keeps distinct source Layout identities even when their current visible contracts are equivalent- [x] Template creation used the authoring IR; lossless expanded imports remained immutable payload backing for mirror materialization, while `standard` / `fidelity` used helper-generated compact canonical preset groups and `design_spec.md` paintdiff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex d111f1b0..0c20b50a 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -14,7 +14,7 @@ Create one reusable template workspace under either the **global template librar**Project scope**: Write the same portable workspace routing at `<project>/` and do not register any global index.-**Hard rule — one workspace routing contract**: Output scope changes only the workspace parent and index registration. Both scopes use required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/`, with the same relative asset references and validation command. Never add placeholder files only to retain an empty directory. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.+**Hard rule — one workspace routing contract**: Output scope changes only the workspace parent and index registration. Both scopes use required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/`, with the same relative asset references and validation command. Create Template must not create an optional directory or placeholder file solely to retain an empty path. An initialized project may already contain empty `images/`, `icons/`, or `exports/` scaffolding; leave it untouched, do not count it as template output, and omit the path from completion unless this workflow wrote or adopted a real file there. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.> **Boundary against template-fill and in-place structure edits**: Create Template does not fill content into a PPTX, add Master/Layout structure to an existing PPTX/SVG, or directly output the user's final generated deck. It authors a separate reusable workspace; an optional PPTX is review evidence only. To generate a deck, return the workspace root to main Step 3 and author new SVG pages from it. A project-scoped workspace is already installed at that project's Step 3 path and is consumed in place.@@ -334,7 +334,7 @@ Extract only what the source actually states:- Structure rules: canvas, page types, grids, zones, placeholders, density, image behavior, and requested variants.- Deck context: use cases, design intent, presentation rhythm, examples, and negative requirements.-Treat an explicit value written by the user as `[decision]`. Treat a statement as `[fact]` only when it comes from an identified source such as an official manual or website. Any interpretation of vague prose remains `[suggested]` and must pass the Step 3 confirmation gate. Text and asset evidence never supplies Master/Layout topology by itself.+Treat an explicit value authored by the user as `[decision]` regardless of carrier: direct chat, pasted text, or a user-written Markdown/TXT/DOCX/PDF brief all retain user authorship. Merely arriving in a file does not make a statement a fact. Treat a statement as `[fact]` only when it is independently traceable to an identified external authority such as an official manual/site, or when it is machine-observable file/package metadata such as dimensions, hashes, or existing PPTX structure. Any interpretation of vague prose remains `[suggested]` and must pass the Step 3 confirmation gate. Text and asset evidence never supplies Master/Layout topology by itself.### 1E. No reference material@@ -346,9 +346,9 @@ Skip the analysis. Step 2 will list every Required item as `[decision]`; nothingCompose a single message that surfaces every Required brief item to the user, **labelling each value's provenance**:-- **`[fact]`** — extracted from a traceable Step 1 source (e.g. theme color from `manifest.json` or an identified official manual)+- **`[fact]`** — independently traceable external authority or machine-observable source metadata (e.g. theme color from `manifest.json`, image dimensions, or an identified official manual); a user-authored brief file is not a fact merely because it is a file- **`[suggested]`** — AI-inferred from analysis or context (e.g. tone summary, applicable scenarios; visually estimated values from type C)-- **`[decision]`** — an explicit user instruction or choice, including exact values supplied directly in conversation (e.g. `template_id`, replication mode, category, palette, or layout rule)+- **`[decision]`** — an explicit user-authored instruction or choice, including exact values supplied in conversation, pasted text, or a user-written brief file (e.g. `template_id`, replication mode, category, palette, or layout rule)**Language adaptation rule**: write the Step 2 brief in the user's language. For technical enum values, show the localized label first and keep the English ID in parentheses only when needed for precision, for example `<localized deck label> (deck)`, `<localized layout label> (layout)`, or `<localized mirror label> (mirror)`. Do not assume users know what each English word means.@@ -378,16 +378,16 @@ Items to surface:| Category | Create Layout/Create Deck only | `[decision]` — Create Deck: `brand` / `general` / `scenario` / `government` / `special`; Create Layout: `general` / `scenario` / `government` / `special` || Applicable scenarios | Yes | `[suggested]` from analysis; user confirms || Identity tone or structural summary | Yes | Create Brand/Create Deck: identity tone. Create Layout: structural use case and density/rhythm summary only. |-| Theme mode | Create Layout/Create Deck only | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[fact]` from an identified source or `[decision]` from direct user text; otherwise `[suggested]`. E: `[decision]`. |-| Canvas format and dimensions | Create Layout/Create Deck only | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[fact]` from an identified source or `[decision]` from direct user text when specified. E: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`). |-| Replication mode | Create Layout/Create Deck only | `[decision]` — `standard` is always available. `fidelity` requires A/B page evidence; `mirror` requires A or B with a complete explicit structure contract. C/D/E channels may supplement an eligible mixed bundle but do not establish mode eligibility. `standard` / `fidelity` author new SVG semantics. Mirror retains one materialized prototype per source slide in source order and adds definition-only prototypes for source Layouts unused by those slides. |+| Theme mode | Create Layout/Create Deck only | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[fact]` from an independently identified external authority, `[decision]` from user-authored text in any carrier, otherwise `[suggested]`. E: `[decision]`. |+| Canvas format and dimensions | Create Layout/Create Deck only | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[fact]` from an independently identified external authority or `[decision]` from user-authored text in any carrier when specified. E: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`). |+| Replication mode | Create Layout/Create Deck only | `[decision]` — `standard` is always available and authors a compact roster from the confirmed brief; it may include a small number of explicitly required distinct variants without becoming source-driven. `fidelity` requires A/B page evidence and expands coverage from the useful source composition range; `mirror` requires A or B with a complete explicit structure contract. C/D/E channels may supplement an eligible mixed bundle but do not establish mode eligibility. `standard` / `fidelity` author new SVG semantics. Mirror retains one materialized prototype per source slide in source order and adds definition-only prototypes for source Layouts unused by those slides. || Native structure facts | Create Layout/Create Deck with Type A or structured Type B | `[fact]` from `native_structure.json` / source SVG contract: master/layout counts, parentage, page assignments, placeholder identities, and multi-master status. Mirror preserves these validated facts in the new workspace; authored modes do not use them as output topology. || Mode-specific ownership | Create Layout/Create Deck only | `standard` / `fidelity`: `[decision]` newly authored Master/Layout ownership, including the reusable-family reason for every additional Master. `mirror`: `[fact]` source ownership mapped without synthesis. Every Master must own at least one emitted Layout and every Layout must have at least one emitted prototype; export never infers either contract. || Visual fidelity for fixed pages | Create Layout/Create Deck `standard` / `fidelity` when reference exists; **N/A for `mirror` and Create Brand** | `[decision]` — `literal` (closely reproduce reference geometry / decoration / sprite crops within a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Different page types may take different settings. || Basic template norms | Yes when reference exists | Create Brand uses the identity fields and provenance rules from its child workflow. Create Layout/Create Deck use `[fact]` / `[suggested]` layout grammar, image system, density rhythm, page roster semantics, and asset policy from Step 1. || Reference source | Optional | already known if Step 1 ran |-| Theme color | Create Brand/Create Deck only | A: `[fact]` from theme XML. B: `[fact]` from dominant SVG `fill`. C: `[suggested]` from visual estimate (HEX is approximate). D: `[fact]` from an identified source or `[decision]` from direct user text; otherwise `[suggested]`. E: `[decision]`. Create Layout may use neutral preview paint but stores no identity color. |-| Fonts | Create Brand/Create Deck only | A: `[fact]` from `manifest.json`. B: `[fact]` from SVG `font-family`. C: font family is not derivable — use `[decision]` if the user supplies one. D: `[fact]` from an identified source or `[decision]` from direct user text. E: `[decision]` when a custom stack is wanted. Create Layout stores no typography system. |+| Theme color | Create Brand/Create Deck only | A: `[fact]` from theme XML. B: `[fact]` from dominant SVG `fill`. C: `[suggested]` from visual estimate (HEX is approximate). D: `[fact]` from an independently identified external authority, `[decision]` from user-authored text in any carrier, otherwise `[suggested]`. E: `[decision]`. Create Layout may use neutral preview paint but stores no identity color. |+| Fonts | Create Brand/Create Deck only | A: `[fact]` from `manifest.json`. B: `[fact]` from SVG `font-family`. C: font family is not derivable — use `[decision]` if the user supplies one. D: `[fact]` from an independently identified external authority or `[decision]` from user-authored text in any carrier. E: `[decision]` when a custom stack is wanted. Create Layout stores no typography system. || Design style | Optional | `[suggested]` from analysis || Assets list | Optional | A: `[fact]` from `assets/` listing; user picks which to bundle. B/C/D: retain each file's source and let the user confirm adoption. E: none. || Keywords | Yes | `[suggested]` from analysis (3–5 short tags); user confirms |@@ -589,13 +589,20 @@ becomes the prototype Slide placeholder, while| Generic text entry | General `body` and text-carried `object` slots begin at the upper-left, use left paragraph alignment, and wrap inside the full frame. Title/subtitle alignment follows the authored composition. || Centered exceptions | Center alignment is reserved for semantically short focal content such as KPI values, short process nodes, hero statements, and compact takeaways. Record a template-wide exception in `design_spec.md §IV` when it is part of the layout grammar. || Review Slide binding | `template_preview_pptx.py` sizes each authored Slide carrier to the same complete frame as its registered Layout placeholder. A review deck whose Slide carrier is only the prompt text's tight box fails Step 6. |+| Review prompt legibility | For `standard` / `fidelity`, the preview exporter substitutes concise sample text only in ephemeral review SVGs so long canonical markers such as `{{CHAPTER_NUM}}` or `{{PAGE_NUM}}` do not wrap. The source SVG markers, carrier font sizes, slot metadata, and Layout frames remain unchanged. || Mirror boundary | `mirror` preserves source Slide carrier geometry exactly; the materializer places the authoritative source `data-pptx-frame` on its text carrier and keeps `data-pptx-placeholder-bounds` as the reusable Layout default. Do not normalize one to the other when the source intentionally overrides that frame. |---## Step 5: Validate Template Assets-**Create Brand branch**: run the child workflow's §4 checklist. In `library` scope, also run the registrar dry-run below; in `project` scope, perform the same file/schema/asset checks without touching a global index. Any failure blocks completion.+**Create Brand branch**: run the child workflow's §4 checklist and the shared project-safe validator below in both scopes. It detects `kind: brand`, validates the identity-only frontmatter/sections/colors/provenance/asset references, and does not require an SVG roster or touch a global index. Any failure blocks completion.++```bash+python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/templates" --template-mode+```++In `library` scope, additionally run the registrar dry-run so `brand_id` is checked against the library directory/index key:```bashpython3 skills/ppt-master/scripts/register_template.py <brand_id> --kind brand --dry-run@@ -643,6 +650,7 @@ This checker validates the authoring contract, not the compiled OOXML package. T- [ ] Every SVG root declares Master/Layout key and picker names; Master/Layout visuals are direct semantic atoms and obey the explicit paint-order contract. Ordinary `<g>` elements remain forbidden there; a validated helper-generated compact canonical preset `<g>` is the sole group exception because it compiles to one native shape. Structural `data-pptx-role` is used only when specialized metadata cannot express required package/page-number/animation behavior- [ ] Every slot is a direct `<g id>` with explicit design-zone bounds and exactly one compatible direct carrier, or an explicit composite `object` proxy. A validated compact canonical preset `<g>` may be the one carrier of an `object` slot; an ordinary multi-object group may not. Zero-slot Layouts remain valid- [ ] For `standard` / `fidelity`, every placeholder bound is the complete editable box rather than the current marker text's tight bounds; general body/object carriers begin at the upper-left and only intentional short focal roles remain centered+- [ ] In review output, authored placeholder prompts remain readable; `template_preview_pptx.py` uses preview-only sample text and leaves every canonical source marker and carrier style unchanged- [ ] `standard` / `fidelity` output SVGs and their Master/Layout/slot contracts were newly authored without preserving or distilling source topology- [ ] Every additional authored Master represents a distinct reusable design family, not one Layout or an equivalent duplicate; every declared Master owns at least one emitted Layout and every declared Layout has at least one emitted prototype- [ ] Mirror output preserves source slide order, Master/Layout identity and parentage, placeholder facts, and ownership; fixed-layer group expansion is mechanical and pixel-equivalent, and the Source Preservation Map lists every source slide@@ -668,7 +676,7 @@ Export the complete SVG roster, one prototype per slide, from the workspace rootpython3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>"```-The default output is `<template_workspace>/exports/<template_id>_template_preview.pptx`; the command creates `exports/` on demand. The script consumes `templates/*.svg` directly, compiles the declared structured Master/Layout contract, and reopens the result. It does not require a project `spec_lock.md`, does not create an intermediate project, and does not infer or distill structure.+The default output is `<template_workspace>/exports/<template_id>_template_preview.pptx`; the command creates `exports/` on demand. The script consumes `templates/*.svg` directly, compiles the declared structured Master/Layout contract, and reopens the result. For `standard` / `fidelity`, it uses ephemeral SVG copies with concise preview-only placeholder samples so long `{{...}}` markers stay readable; canonical source SVGs and placeholder semantics are not modified. It does not require a project `spec_lock.md`, does not create a persistent intermediate project, and does not infer or distill structure.The first export refuses an existing output. After intentionally fixing the template and replacing its prior review deck, rerun with `--force`; never rely on a silent overwrite:@@ -796,8 +804,8 @@ Produce one scope-aware, evidence-driven completion card for either location:**Output Scope**: library | project**Workspace Path**: `<template_workspace>/`**Template Source**: `<template_workspace>/templates/`-**Bitmap Path**: `<template_workspace>/images/` ← omit when absent-**Imported Vector Path**: `<template_workspace>/icons/imported/` ← omit when absent+**Bitmap Path**: `<template_workspace>/images/` ← omit when no bitmap was written or adopted+**Imported Vector Path**: `<template_workspace>/icons/imported/` ← omit when no imported vector was written or adopted**Review PPTX**: `<template_workspace>/exports/<template_id>_template_preview.pptx` ← Create Layout/Create Deck only; omit for Create Brand and when an optional one-Master review was not requested**Primary Color**: <hex> ← Create Brand/Create Deck only; omit for Create Layout**Index Registration**: Done | Not registered (project workspace)diff --git a/skills/ppt-master/workflows/create-template/create-brand.md b/skills/ppt-master/workflows/create-template/create-brand.mdindex 14d1fe5b..608cb977 100644--- a/skills/ppt-master/workflows/create-template/create-brand.md+++ b/skills/ppt-master/workflows/create-template/create-brand.md@@ -39,7 +39,7 @@ Enter this child workflow only after [`Create Template`](../create-template.md)Use these provenance labels in the proposal and final Color Scheme table:- `fact` — literal value from an official asset or manual.-- `user` — value explicitly supplied by the user.+- `user` — value explicitly authored by the user, whether in chat, pasted text, or a user-written brief file.- `approx` — visual estimate or pattern observed in an existing deck/site.**Hard rule — no inferred brand truth**: Do not promote a visual estimate, presentation convention, or observed neutral into an official brand fact. Do not invent semantic success/warning/error colors.@@ -73,7 +73,7 @@ Create Template supplies an already resolved and collision-checked `<template_wo└── icons/ # optional; branded icon overrides only when adopted```-Do not create empty optional directories or `exports/`. Bitmap references from `templates/design_spec.md` use `../images/<name>`; branded icon references use `../icons/<name>`.+Do not create optional directories or `exports/` solely to retain empty paths. An initialized project may already contain empty scaffolding; leave it untouched and do not report it as Brand output. Bitmap references from `templates/design_spec.md` use `../images/<name>`; branded icon references use `../icons/<name>`.Write this personality-only schema:@@ -138,9 +138,15 @@ Return these facts to Create Template:- Required sections I–VI exist; Page Roster and Signature Design Elements do not exist.- No `*.svg`, `native_structure_mode`, Master/Layout, placeholder, canvas, or page-count fields were written.- Every color is `#RRGGBB`, the primary table row matches frontmatter, and provenance is `fact`, `approx`, or `user`.-- Every referenced asset exists under the same workspace; no empty optional directory or `exports/` directory was created.+- Every referenced asset exists under the same workspace; this workflow created no optional directory or `exports/` directory solely to leave it empty. Pre-existing initialized-project scaffolding is allowed and remains untouched.-For `library` scope, Create Template Step 5 validates with:+For both scopes, Create Template Step 5 validates the portable Brand contract without registration:++```bash+python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/templates" --template-mode+```++For `library` scope, additionally validate the directory/index identity with:```bashpython3 skills/ppt-master/scripts/register_template.py <brand_id> --kind brand --dry-run@@ -152,4 +158,4 @@ After that gate passes, Create Template Step 7 registers with:python3 skills/ppt-master/scripts/register_template.py <brand_id> --kind brand```-For `project` scope, skip both commands and report `Not registered (project workspace)`. Downstream consumption always uses the explicit workspace root through Generate PPTX Step 3; a bare brand name never activates it.+For `project` scope, run only the shared validator, skip both registrar commands, and report `Not registered (project workspace)`. Downstream consumption always uses the explicit workspace root through Generate PPTX Step 3; a bare brand name never activates it.diff --git a/skills/ppt-master/workflows/create-template/create-deck.md b/skills/ppt-master/workflows/create-template/create-deck.mdindex 8cbe1b57..20089af1 100644--- a/skills/ppt-master/workflows/create-template/create-deck.md+++ b/skills/ppt-master/workflows/create-template/create-deck.md@@ -32,7 +32,7 @@ Use Create Template Step 1 for source ingestion and replication-mode eligibility- Middle: use cases, design intent, presentation rhythm, and other deck-specific overview context.- `standard` and `fidelity` author a new complete system; source topology is not output topology. `mirror` preserves only validated package/contract facts in a new workspace and never modifies the source.-Direct conversation text, pasted requirements, converted documents/websites, images, and supplied assets are first-class evidence under Create Template Step 1. In a mixed bundle, combine the applicable identity, structure, and middle evidence without erasing provenance. Exact user instructions remain decisions; vague prose remains suggested interpretation until the shared confirmation gate.+Direct conversation text, pasted requirements, converted documents/websites, images, and supplied assets are first-class evidence under Create Template Step 1. In a mixed bundle, combine the applicable identity, structure, and middle evidence without erasing provenance. Exact user-authored instructions remain decisions whether they arrive in chat or a user-written brief file; vague prose remains suggested interpretation until the shared confirmation gate.Create Deck is the default child when identity and structure are both requested or when the source is a specific organization's branded presentation system. If the user explicitly wants identity-only or brand-neutral structure, return to Create Template dispatch before the shared confirmation marker is emitted.@@ -108,7 +108,7 @@ In addition to Create Template Steps 5–6, verify:- Template Overview, Color Scheme, Signature Design Elements, and Page Roster exist; conditional sections match real choices/assets.- Every identity color is `#RRGGBB`; the primary table row matches frontmatter, and SVG paint follows the confirmed identity.- Every SVG in the roster satisfies the shared Master/Layout/slot contract and the roster is bidirectionally complete.-- Every referenced image/icon exists under the same workspace and no empty optional directory was created.+- Every referenced image/icon exists under the same workspace; this workflow created no optional directory solely to leave it empty. Pre-existing initialized-project scaffolding is allowed and remains untouched.For library scope, Create Template validates and registers with:diff --git a/skills/ppt-master/workflows/create-template/create-layout.md b/skills/ppt-master/workflows/create-template/create-layout.mdindex 76473993..7e67c77b 100644--- a/skills/ppt-master/workflows/create-template/create-layout.md+++ b/skills/ppt-master/workflows/create-template/create-layout.md@@ -34,7 +34,7 @@ Use Create Template Step 1 for source ingestion and replication-mode eligibility- When the source is branded, explicitly confirm that Create Layout will strip that identity. If the user wants the identity retained with the structure, return to Create Template dispatch and select Create Deck before the shared confirmation marker is emitted.- `standard` and `fidelity` author a new Master/Layout/slot system. `mirror` is available only when the source contains a complete current structure contract and preserves validated structure facts in a new workspace without modifying the source.-Direct conversation text, pasted requirements, converted documents/websites, images, and supplied assets may define or illustrate reusable structure. In a mixed bundle, combine those channels without treating identity-only evidence as layout ownership. Exact user instructions remain decisions; vague prose remains suggested interpretation until the shared confirmation gate.+Direct conversation text, pasted requirements, converted documents/websites, images, and supplied assets may define or illustrate reusable structure. In a mixed bundle, combine those channels without treating identity-only evidence as layout ownership. Exact user-authored instructions remain decisions whether they arrive in chat or a user-written brief file; vague prose remains suggested interpretation until the shared confirmation gate.## 2. Layout Brief and Schema