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

fix(workflow): surface advanced presentation capabilities

hugohe3239fbc8ae04e
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.md
index 3596c290..2938fea4 100644
--- a/docs/rules/prompt-style.md
+++ b/docs/rules/prompt-style.md
@@ -102,16 +102,16 @@ Constraint strength and decision ownership are independent. Preserve this chain
| Layer | Owns |
|---|---|
| User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative |
-| Strategist / plan + preparation | Assess material sufficiency; trigger permitted fact research; decide the approved content, resources, keys, identity anchors, and exact page roster; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution |
-| Executor / realization | Use only prepared project-local assets and realize the approved selections through geometry, composition, hierarchy, and treatment; for icons, the complete `<project>/icons/` pool is prepared material and `icons.inventory` is not a whitelist; sparse local font/color garnish is allowed only while non-structural and non-recurring |
+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted fact research; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution |
+| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. For icons, the complete `<project>/icons/` pool is prepared material and `icons.inventory` is not a whitelist; sparse local font/color garnish is allowed only while non-structural and non-recurring |
**Preparation timing**: Fact research required for planning may run before final confirmation. AI / web / slice acquisition runs only from the completed `design_spec.md §VIII` and `spec_lock.md`, after final confirmation and before Executor. Image_Generator, Image_Searcher, and icon-sync tooling execute Strategist-owned preparation; they are not independent decision owners.
-**Hard rule**: downstream freedom exists only in dimensions left open upstream. A named outcome retains identity; a broad semantic request permits in-class choice. Once the plan resolves that choice, execution cannot reopen or substitute it. Executor never searches, generates, downloads, syncs, invents, or replaces a resource; missing material returns to Strategist-owned preparation or upstream repair.
+**Hard rule**: downstream freedom exists only in dimensions left open upstream, including fields explicitly labeled `suggestion` or Reference. A named binding outcome retains identity; a broad semantic request or expression recommendation permits in-class choice. Once the plan resolves a binding choice, execution cannot reopen or substitute it. Executor never searches, generates, downloads, syncs, invents, or replaces a resource; missing material returns to Strategist-owned preparation or upstream repair.
> Mnemonic — restaurant contract: the customer supplies initial ingredients and the desired dish; Strategist plans the dish and prepares the complete mise en place; Executor cooks from that prepared inventory. “Mapo tofu” cannot become tomato-and-eggs or tofu soup, while “a tofu dish” leaves deliberate in-class freedom.
-**Review gate**: treat any prompt refactor that erases this ownership chain, moves acquisition into Executor, turns a permission into a quota, or turns flexible realization into silent reselection as a semantic regression even when the compressed wording is shorter.
+**Review gate**: treat any prompt refactor that erases this ownership chain, moves acquisition into Executor, turns a permission into a quota, or turns flexible realization into silent resource/identity reselection as a semantic regression even when the compressed wording is shorter.
---
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 2c13da41..8900e59d 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -410,18 +410,18 @@ The cooking analogy is the canonical ownership model for generation, not just ex
| Restaurant | PPT Master | Authority |
|---|---|---|
| Customer and initial ingredients | User confirmation and supplied sources/assets | Defines facts, intent, exclusions, acquisition permissions, and how specific the requested outcome is |
-| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart-reference/layout keys, fonts, palette anchors, icons, and crop boundaries; readies the complete project-local inventory before execution |
-| Cook | Executor | Uses only prepared project-local assets and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients |
+| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart-reference/template-layout keys, fonts, palette anchors, icons, and crop boundaries; records optional capability/expression recommendations; readies the complete project-local inventory before execution |
+| Cook | Executor | Uses only prepared project-local assets and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients; may adapt fields explicitly labeled as suggestions or References |
**Preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners.
**Prepared project-local assets are the boundary.** Images and other declared resources remain available only when Strategist has selected them, recorded them in the planning artifacts, and made their project paths resolvable or explicitly `Needs-Manual`. Icons are prepared when their SVG files exist under `<project>/icons/`; `spec_lock.icons.inventory` records the Strategist's planned bundled selection but is not an exhaustive execution whitelist. Files elsewhere on disk are not authorized. Missing material returns upstream; Executor never searches, generates, downloads, syncs, or substitutes it.
-**Specificity controls freedom.** “Make Mapo tofu” fixes the result's identity: technique and presentation may vary, but tomato-and-eggs or tofu soup is a substitution. “Make a tofu dish” leaves an in-class choice. Strategist may resolve that choice; if the Design Spec deliberately leaves a dimension broad, Executor may realize it within that envelope. Once the Design Spec names a concrete choice, execution cannot reopen it.
+**Specificity controls freedom.** “Make Mapo tofu” fixes the result's identity: technique and presentation may vary, but tomato-and-eggs or tofu soup is a substitution. “Make a tofu dish” leaves an in-class choice. Strategist may resolve that choice; if the Design Spec deliberately leaves a dimension broad, Executor may realize it within that envelope. Once the Design Spec names a binding choice, execution cannot reopen it. Fields explicitly labeled as suggestions or References—including a preferred page-local image pattern—remain expression guidance that Executor may adapt without changing content, resources, identity, or explicit constraints.
-**Garnish remains local.** Sparse page-local font or color accents may add hierarchy, differentiation, or atmosphere without becoming a second visual system. Structural/recurring fonts, palette roles, resources, or patterns remain Strategist decisions and require an upstream Design Spec/lock update before reuse.
+**Garnish remains local.** Sparse page-local font or color accents may add hierarchy, differentiation, or atmosphere without becoming a second visual system. Structural/recurring fonts, palette roles, resources, or recurring cross-page identity patterns remain Strategist decisions and require an upstream Design Spec/lock update before reuse. A page-local §VIII image pattern remains a preferred composition reference.
-**Prompt-refactor invariant.** Compression must preserve initial materials, user confirmation, Strategist-owned preparation, planning ownership, and execution freedom as separate layers. Moving acquisition into Executor, turning permission into quota, flexible realization into reselection, or an exact plan into an approximate target is a semantic regression. Runtime authority lives in [`strategist.md`](../skills/ppt-master/references/strategist.md) and [`executor-base.md`](../skills/ppt-master/references/executor-base.md); prompt-writing governance lives in [`prompt-style.md`](./rules/prompt-style.md).
+**Prompt-refactor invariant.** Compression must preserve initial materials, user confirmation, Strategist-owned preparation, planning ownership, and execution freedom as separate layers. Moving acquisition into Executor, turning permission into quota, flexible realization into silent resource/identity reselection, or an exact binding plan into an approximate target is a semantic regression. Runtime authority lives in [`strategist.md`](../skills/ppt-master/references/strategist.md) and [`executor-base.md`](../skills/ppt-master/references/executor-base.md); prompt-writing governance lives in [`prompt-style.md`](./rules/prompt-style.md).
---
@@ -458,7 +458,7 @@ The catalog of *how an image is placed on a slide* (full vocabulary in [`referen
**Why the layers are physically separated, not just tagged.** Patterns are reorganized so all Primary structures appear first, then all Modifiers — a Strategist or Executor reading the file once internalizes the two-layer mental model from the table of contents alone. Numbers are stable identifiers (`#38` is still image-as-canvas + annotation cards regardless of where it sits in the file), so existing references across `spec_lock.md`, `design_spec.md §VIII`, executor logs, and historical examples all keep resolving.
-**Why composition flows through Strategist's resource list, not just Executor's improvisation.** The `Layout pattern` column in `§VIII Image Resource List` accepts a `#<id> + #<id> ...` expression — Primary id plus optional Modifier ids — while `Crop Policy` records `adaptive` or `no-crop`. Strategist therefore selects the semantic composition and information-integrity boundary before SVG generation, and both survive session re-entry through the lock projection. Executor owns realization, not selection: it may resize, reflow, reposition, and rebalance the chosen pattern for the real asset ratio and content hierarchy, and an `adaptive` row may use complete display or a focal-safe crop. Replacing the pattern or changing the crop strategy requires a Design Spec update.
+**Why composition flows through Strategist's resource list instead of being discovered only during drawing.** The `Layout pattern` column in `§VIII Image Resource List` accepts a `#<id> + #<id> ...` expression—Primary id plus optional Modifier ids—while `Crop Policy` records `adaptive` or `no-crop`. Strategist must inspect the full catalog and record a concrete preferred composition plus the information-integrity boundary before SVG generation; both survive session re-entry through the lock projection. Executor then chooses the actual realization: it may resize, reflow, reposition, rebalance, switch to another catalog pattern, or use an ordinary composition when that communicates better. Resource identity, must-use/content obligations, `no-crop`, and explicit user/template constraints remain binding; only changing those requires an upstream Design Spec update.
**Why true hard constraints stay upstream.** Cross-cutting SVG authoring and PPTX-compatibility exceptions live in the authority set routed by [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). The layout patterns file points to that router rather than restating the contract, so each rule still has one owning module and no stale duplicate in the pattern catalog.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index bdc4b70e..caab1afc 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -404,18 +404,18 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
| 餐厅角色 | PPT Master 对应项 | 决策权 |
|---|---|---|
| 顾客与初始食材 | 用户确认与用户提供的原材料/素材 | 决定事实、意图、排除项、材料补充许可,以及要求具体到什么程度 |
-| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表参考 key / 版式 key、字体、色板锚点、图标和裁剪边界;在执行前备齐项目级材料清单 |
-| 厨师 | Executor | 只使用项目中已备好的材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料 |
+| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表参考 key / 模板版式 key、字体、色板锚点、图标和裁剪边界;记录可选的能力 / 表达建议;在执行前备齐项目级材料清单 |
+| 厨师 | Executor | 只使用项目中已备好的材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料;可以调整明确标为 suggestion 或 Reference 的字段 |
**备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。
**项目中已备好的材料就是边界。** 图片和其他声明型资源,仍须由 Strategist 选定、写入规划产物,并保证项目路径可解析或明确标为 `Needs-Manual`。图标 SVG 只要已位于 `<project>/icons/` 就属于已备材料;`spec_lock.icons.inventory` 记录 Strategist 计划选用的内置图标,但不是穷尽式执行白名单。其他目录中的文件不构成使用许可。缺料必须返回上游;Executor 不得搜索、生成、下载、同步或替换资源。
-**具体程度决定自由度。** “做麻婆豆腐”锁定成品身份:火候、口感和摆盘可以发挥,但不能换成番茄炒蛋或豆腐汤。“做一道豆腐菜”则保留了品类内选择空间。Strategist 可以把这个开放要求收敛成具体方案;如果 Design Spec 有意保留某个维度的开放性,Executor 可以在该范围内实现。一旦 Design Spec 已经选定具体结果,执行阶段不得重新打开选择。
+**具体程度决定自由度。** “做麻婆豆腐”锁定成品身份:火候、口感和摆盘可以发挥,但不能换成番茄炒蛋或豆腐汤。“做一道豆腐菜”则保留了品类内选择空间。Strategist 可以把这个开放要求收敛成具体方案;如果 Design Spec 有意保留某个维度的开放性,Executor 可以在该范围内实现。一旦 Design Spec 已经选定具有约束力的结果,执行阶段不得重新打开选择。明确标为 suggestion 或 Reference 的字段——包括页面级首选图片 pattern——仍是表达建议;Executor 可以在不改变内容、资源、身份和显式约束的前提下调整。
-**点缀只能保持局部。** 零星的页面级字体或颜色可以用于增加层级、区分和氛围,但不能发展成第二套视觉系统。结构性或重复出现的字体、色板角色、资源与 pattern 仍属于 Strategist 决策;复用前必须先更新 Design Spec/lock。
+**点缀只能保持局部。** 零星的页面级字体或颜色可以用于增加层级、区分和氛围,但不能发展成第二套视觉系统。结构性或重复出现的字体、色板角色、资源与跨页身份 pattern 仍属于 Strategist 决策;复用前必须先更新 Design Spec/lock。页面级 §VIII 图片 pattern 仍是首选构图参考。
-**提示词重构不变量。** 压缩提示词时,必须继续区分初始材料、用户确认、Strategist 负责的备料、策略规划和执行自由。把材料获取下放给 Executor、把许可变成配额、把灵活实现变成重新选型,或把精确计划降级成近似目标,均属于语义回归。运行时权威位于 [`strategist.md`](../../skills/ppt-master/references/strategist.md) 与 [`executor-base.md`](../../skills/ppt-master/references/executor-base.md),提示词编写规则位于 [`prompt-style.md`](../rules/prompt-style.md)。
+**提示词重构不变量。** 压缩提示词时,必须继续区分初始材料、用户确认、Strategist 负责的备料、策略规划和执行自由。把材料获取下放给 Executor、把许可变成配额、把灵活实现变成静默更换资源 / 身份,或把精确的约束计划降级成近似目标,均属于语义回归。运行时权威位于 [`strategist.md`](../../skills/ppt-master/references/strategist.md) 与 [`executor-base.md`](../../skills/ppt-master/references/executor-base.md),提示词编写规则位于 [`prompt-style.md`](../rules/prompt-style.md)。
---
@@ -452,7 +452,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
**为什么物理拆分两层,而不是只打标签。** 词表被重排成「Primary 全部在前,Modifier 全部在后」——Strategist 或 Executor 读一次目录,就能从结构上内化「两层」心智模型。编号是稳定 id(`#38` 永远是「图作画布 + 注解卡」,不论它在文件里的物理位置),所以 `spec_lock.md`、`design_spec.md §VIII`、历史 executor 输出、过往示例里所有 `#<id>` 引用照样解析。
-**为什么组合走 Strategist 资源列表,不只交给 Executor 临场发挥。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id;`Crop Policy` 则记录 `adaptive` 或 `no-crop`。Strategist 会在 SVG 生成前同时选定语义构图和信息完整性边界,并通过 lock 投影让两者在 session 重入后继续存在。Executor 负责实现方式,而不是重新选型:它可以根据真实图片比例和内容层级调整所选 pattern 的尺寸、位置、流向与权重;`adaptive` 行既可完整显示,也可安全裁剪。若要更换 pattern 或改变裁剪策略,必须先更新 Design Spec。
+**为什么组合走 Strategist 资源列表,而不是到绘制时才第一次发现。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id;`Crop Policy` 则记录 `adaptive` 或 `no-crop`。Strategist 必须在 SVG 生成前完整查看目录,写出具体的首选构图和信息完整性边界,并通过 lock 投影让两者在 session 重入后继续存在。Executor 再决定实际表达:它可以调整尺寸、位置、流向与权重,也可以换成另一个目录 pattern 或普通构图。资源身份、必用 / 内容义务、`no-crop` 和显式用户 / 模板约束仍具有约束力;只有改变这些边界才需要先更新 Design Spec。
**为什么真正的硬约束留在上游。** 跨切的 SVG 创作与 PPTX 兼容性例外属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由的权威集。版式词表只指向该路由,不再复述合同;每条规则仍只有一个所属模块,词表里也不会留下过期副本。
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 9600cc80..04a504a0 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -48,11 +48,15 @@ To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the
Per-element animation is off by default. To enable it deck-wide, pass `-a auto` at export (no config needed). When a deck instead needs specific object timing — for example title first, chart second, annotation last — use the optional `animations.json` sidecar. The SVG remains the visual source; the custom stage may rewrite its grouping hierarchy, ids, and bounds to create better semantic anchors without changing visible output, while the sidecar controls PPTX animation behavior.
-Run the [`customize-animations`](../workflows/stages/customize-animations.md) post-processing stage when the user asks to tune animation order, effects, timing, or object-level reveals.
+Run the [`customize-animations`](../workflows/stages/customize-animations.md)
+post-processing stage when Design Spec §IX contains `Motion suggestion`, or
+when the project already carries `animations.json`, or when the user asks to
+tune animation order, effects, timing, or object-level reveals.
-**Hard rule — semantic anchors before sidecar**: derive reveal units from page
-meaning and narration, then regroup coarse/fragmented Slide-local content
-without changing its appearance. Only post-regroup top-level ids are valid.
+**Hard rule — semantic anchors before object-targeted sidecar entries**: when
+object animation is in scope, derive reveal units from page meaning and
+narration, then regroup coarse/fragmented Slide-local content without changing
+its appearance. Only post-regroup top-level ids are valid object targets.
```bash
# Inspect the real anchors after the semantic regrouping pass
@@ -139,11 +143,13 @@ Rules:
- Unknown effects, modes, or triggers and invalid numeric/order fields fail validation; no fallback effect is substituted.
**Inheritance**: the sidecar is optional. Sparse legacy slides inherit
-`defaults.transition` / `defaults.animation`, then CLI resolution; explicit CLI
-flags win. Groups inherit the resolved slide duration, timing modifiers,
-after-effect, and sound. `effect_options` remains coupled to an explicit effect;
-`trigger_shape` is never inherited; omitted `order`/`delay` use exporter
-defaults. New authoring writes complete slide blocks.
+`defaults.transition` / `defaults.animation`, then CLI resolution. Explicit CLI
+flags override the corresponding sidecar default/slide fields; explicit group
+overrides remain unless `-a none` hard-disables all object motion. Groups
+inherit the resolved slide duration, timing modifiers, after-effect, and sound.
+`effect_options` remains coupled to an explicit effect; `trigger_shape` is
+never inherited; omitted `order`/`delay` use exporter defaults. New authoring
+writes complete slide blocks.
---
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index ce34752d..d2d6feb3 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -43,7 +43,7 @@ Global artifact ownership rules for PPT Master projects.
| `validation/<output_stem>.report.json` | Published-package audit | PPTX package/resource postflight status, part counts, and quality-gate linkage | Step 7.3 writes after the PPTX passes package validation and emits a compact `[POSTFLIGHT]` receipt. Agents use the receipt on routine success and keep the full JSON cold unless targeted failure/audit evidence is required. |
| `exports/` | Delivery artifacts | Native DrawingML PPTX and explicit native-object/narration variants | Step 7.3 writes only final deliverables from `svg_output/`. |
| `backup/<timestamp>/svg_output/` | Frozen author-source archive | Re-export source without re-running LLM | `svg_to_pptx.py` writes a snapshot during export |
-| `animations.json` | Optional animation config | Object-level animation sidecar | Created only by explicit animation workflow/request |
+| `animations.json` | Optional animation config | Page-transition and object-animation sidecar | Created only when the conditional animation workflow activates; normal export never creates it |
---
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 12113ba5..c534e70d 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -66,7 +66,7 @@ Consume stdout directly; stop on non-zero exit. The projection is derived, not a
**Hard rule — exact page roster**: `design_spec.md §IX` is the ordered queue: one final slide per entry, with the same id/order. The UI range no longer applies. Never add, drop, merge, split, or reorder; repair/reconfirm the Design Spec first.
-**Hard rule — selection vs realization**: use Strategist-selected semantic content, resources/paths, chart/layout keys, core fonts, palette anchors, icons, and crop boundaries. Adapt realization, never selection, except sparse local font/color garnish allowed below. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Selection changes require upstream repair.
+**Hard rule — binding selection vs realization**: use Strategist-selected semantic content, resources/paths, chart keys, template/layout routing keys, core fonts, palette anchors, icons, and crop boundaries. Adapt realization, never those binding selections, except sparse local font/color garnish allowed below. A §VIII preferred image pattern is not a template/layout routing key; [`executor-image.md`](./executor-image.md) owns its realization freedom. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Binding selection changes require upstream repair.
**Hard rule — content vs expression**: `design_spec.md §IX` owns each page's semantic content and supplies complete preferred wording and block texture; those expression choices are not verbatim requirements unless explicitly literal. Executor may paraphrase, condense repetition, regroup or reorder material within the same page, and switch among prose, bullets, keywords, labels, or visual annotation when fit or readability benefits. The result must remain information-equivalent: preserve the `Core message`, `Audience move`, and every substantive claim, fact, data value, proper name, qualifier or caveat, relationship, key argument or evidence, and literal requirement. Never add a claim, move content across pages, or drop information to make the layout fit; return an unfit or underspecified block for Design Spec repair.
@@ -152,7 +152,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
2. **Quality Check Gate**: only after every planned SVG exists, run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.
-### 3.0 Native Preset Shape Selection
+### 3.0 Native Shape Selection
**Reach for a native preset whenever one expresses a complete object — this is
the default, not the exception.** Block arrows, chevrons, banners / ribbons,
@@ -164,22 +164,29 @@ one of these, use the preset. Apply the decision gate in
[`native-shape-authoring.md`](./native-shape-authoring.md) to pick the right
shape and to keep only the exceptions below as ordinary SVG.
+§IX `Native shape suggestion` records a semantic opportunity, not a literal
+tool command. Decide from the actual page construction whether a preset,
+Boolean result, or ordinary SVG best realizes it; a different implementation
+is valid when it preserves the intended object and content.
+
| Decision | Action |
|---|---|
| Plain rect / symmetric round rect / circle / ellipse | Keep the ordinary SVG primitive; it is already natively editable. |
| Exact single-preset match | Call `preset_shape_svg.py render` and paste its complete stdout fragment into the current hand-authored SVG. |
+| Two or more closed operands whose final semantic object depends on union, cutout, overlap-only coverage, symmetric difference, or fragmentation | Evaluate `shape_boolean_svg.py` at draw time and use it when Boolean materialization is the clearest faithful construction; follow [`native-shape-authoring.md`](./native-shape-authoring.md) §6. |
| Stock shape that needs a gradient fill/stroke or a pattern fill | Keep ordinary SVG — the helper paints `none` or a solid HEX on both fill and stroke only ([`native-shape-authoring.md`](./native-shape-authoring.md) §5). |
-| Page-specific, compound, organic, branded, icon, or data geometry | Keep ordinary SVG path/polygon geometry. |
+| Page-specific freeform, organic, branded, icon, data geometry, or overlaps that remain separate objects | Keep ordinary SVG path/polygon geometry. |
| Similar-looking contour only | Never guess; keep ordinary SVG. |
-This automatic decision applies only before drawing a new object. Do not scan
-existing SVG, classify path contours, or upgrade ordinary SVG during export.
+This decision applies only while drawing a new object. A suggestion never
+triggers retrospective scanning, contour classification, or automatic
+upgrading of ordinary SVG during export.
**Hard rule**: do not hand-write `data-pptx-authoring`, `data-pptx-prst`,
-`data-pptx-frame`, adjustment metadata, or registry paths. The helper generates
-one compact atomic `<g>` from the shared 187-shape registry, with semantic
-metadata and base paint written once. Rerun the helper when geometry or paint
-changes; never edit one of its direct paths.
+`data-pptx-frame`, adjustment metadata, or registry paths. The preset helper
+generates one compact atomic `<g>` from the shared 187-shape registry, with
+semantic metadata and base paint written once. Rerun that helper when geometry
+or paint changes; never edit one of its direct paths.
For chart-template and diagram authoring, thin relationships use ordinary
`<line>` / supported open `<path>` geometry with registered arrow markers;
@@ -190,10 +197,10 @@ remain available only for an explicit request for a standalone unconnected
`p:cxnSp`; imported Connector topology stays under the preserve/mirror contract.
`actionButton*` presets provide visual geometry only, not actions or hyperlinks.
-**Hard rule — narrow helper scope**: the helper prints one shape fragment to
-stdout. It does not write a page or choose layout. Read the fragment and insert
-it through the normal `apply_patch` page edit; never redirect, loop, or batch it
-into `svg_output/`.
+**Hard rule — narrow helper scope**: Both helpers print only their documented
+stdout fragment(s); neither writes a page or chooses layout. Read every returned
+fragment and insert it through the normal `apply_patch` page edit; never
+redirect, loop, or batch helper output into `svg_output/`.
### SVG File Naming Convention
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.md
index 29f9fd0a..372525e2 100644
--- a/skills/ppt-master/references/executor-image.md
+++ b/skills/ppt-master/references/executor-image.md
@@ -23,7 +23,7 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
**Template-bundled images**: [`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md) copies them into project `images/`. Outside `mirror`, reference `../images/<name>` and never copy a template SVG's bare sibling href: the rendered page lives in `svg_output/`. `mirror` ([`executor-structured.md`](./executor-structured.md) §1.1) keeps hrefs verbatim; export resolves them against `images/`.
-**Mandatory — selected pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once when this branch loads, then resolve every primary/modifier id in each active §VIII/lock row to its exact catalog entry. Preserve the selected semantic composition. Adapt geometry, ratio, placement, spacing, and hierarchy for the actual page; never replace the pattern, role, file/source, must-use, or crop policy downstream. If another pattern is needed, return upstream to update the Design Spec. Only explicit user/template preservation locks exact geometry. Avoid generic left/right repetition.
+**Reference — preferred pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once when this branch loads, then resolve every primary/modifier id in each active §VIII/lock row so the Strategist's recommendation is understood. Use it as a strong starting point, but adapt its geometry or choose another catalog/ordinary composition when the actual page can communicate better. Preserve the resource role, file/source, must-use status, crop policy, content, and explicit user/template constraints; a pattern-only change needs no upstream rewrite. Avoid generic left/right repetition.
**No semantic re-reading**: §VIII owns image identity, purpose, and focus / crop constraints. Executor uses its `Reference` plus regenerated dimensions; it never opens source images to rediscover subjects, substitute assets, or invent focus. For `adaptive` without reliable focus, use `meet`; missing or contradictory required constraints return upstream.
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
index 4e613c2d..c673f8ee 100644
--- a/skills/ppt-master/references/image-base.md
+++ b/skills/ppt-master/references/image-base.md
@@ -23,7 +23,7 @@ Defined in `design_spec.md §VIII`. Status enum: see [`svg-image-embedding.md`](
| Filename | Dimensions | Purpose / Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference |
|---|---|---|---|---|---|---|---|
-| `<planned file>` | `<planned size>` | `<planned role>` | `<Strategist selection>` | `adaptive` / `no-crop` | `ai` / `web` / `slice` | Pending | `<acquisition brief>` |
+| `<planned file>` | `<planned size>` | `<planned role>` | `<Strategist recommendation>` | `adaptive` / `no-crop` | `ai` / `web` / `slice` | Pending | `<acquisition brief>` |
**Required per non-skipped row**: `Acquire Via` and `Status`. `Reference` is required for every `web` / `slice` row and every newly authored `ai` row. An existing `ai` row whose `Reference` is omitted or blank may continue only through the declared inference in [`image-generator.md`](./image-generator.md) §8; no other path may infer it.
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index dceaddac..55428145 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -279,7 +279,7 @@ If one deck needs mixed shapes, create separate sheets per shape family unless o
**Resource contract — the sheet and its elements are different row kinds.** A sliced element can only be placed if it exists as a resource the Executor is allowed to reference (`spec_lock.md images`). So §VIII carries two row kinds (planning authority: [`strategist-image.md`](./strategist-image.md)):
- **Sheet row** — `Acquire Via: ai`, `Type: Illustration Sheet`, the intent prompt, named as the slice source with its intended cell shape and placement purpose (`Reference: landscape footer-vignette spot set`). It is generated in Step 5 but **never placed on a slide** — keep it **out of** `spec_lock.md images`. Image_Generator resolves the exact `aspect_ratio`, grid, and slice command from this intent.
-- **Element rows** — one per used element, `Acquire Via: slice`, filename matching a `--names` output, `Reference` naming the parent sheet + cell/element. These **are** placed — list every one in `spec_lock.md images`, normally with `crop=no-crop` (a tight-trimmed transparent spot should be fit, not cover-cropped). Their dimensions are filled in after slicing (Step 5 re-runs `analyze_images.py`). Each row must already carry a Strategist-selected decorative-cutout Layout pattern, never a boxed container — see Placement below.
+- **Element rows** — one per used element, `Acquire Via: slice`, filename matching a `--names` output, `Reference` naming the parent sheet + cell/element. These **are** placed — list every one in `spec_lock.md images`, normally with `crop=no-crop` (a tight-trimmed transparent spot should be fit, not cover-cropped). Their dimensions are filled in after slicing (Step 5 re-runs `analyze_images.py`). Each row must already carry a Strategist-recommended decorative-cutout Layout pattern rather than a boxed-container recommendation; Executor owns the actual placement — see Placement below.
For traceability, add optional `slice_grid` and `slice_names` fields to the sheet item in `image_prompts.json` after choosing the geometry. `image_gen.py` ignores unknown item fields but preserves them in the manifest, so these fields document the exact command that must be used for slicing.
@@ -296,7 +296,7 @@ python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \
2. **Clean grid, or it cuts ugly.** The model will not place every element perfectly; force a clear grid with gutters, and generate **a few sheets** (re-roll the same prompt) to pick the cleanest-laid-out one before slicing. State the exact row/column structure and cell shape so the model does not invent a square matrix. `--trim` absorbs the rest.
3. **Generate only as large as needed.** Each cell is a fraction of the sheet. Pick the smallest sheet size that keeps each sliced cell at least **1.5-2x** the intended display size. `1K` is usually enough for small 80-160px decorative spots; use `2K` for medium 180-320px placements; reserve `4K` for large, cropped, or potentially enlarged elements.
-**Placement — these are decorative accessories, not boxed pictures.** Strategist selects each element row's pattern from the decorative-cutout family in [`image-layout-patterns.md`](./image-layout-patterns.md): `#63` sticker/cutout, `#4` bleed off the canvas edge, `#58` corner fragment, `#66` fade into the background, `#69` slight editorial rotation, or `#49` asymmetric cluster. Executor realizes that choice through margin position, off-edge treatment, overlap, scale, and angle rather than reserving a tidy tile. Anchor most pages on one primary element and let the rest stay small ([primary-per-page](./strategist-image.md)).
+**Placement — these are decorative accessories, not boxed pictures.** Strategist recommends each element row's pattern from the decorative-cutout family in [`image-layout-patterns.md`](./image-layout-patterns.md): `#63` sticker/cutout, `#4` bleed off the canvas edge, `#58` corner fragment, `#66` fade into the background, `#69` slight editorial rotation, or `#49` asymmetric cluster. Executor uses that recall to choose the actual unboxed composition through margin position, off-edge treatment, overlap, scale, angle, or another suitable decorative placement while preserving the resource role and crop/content constraints. Anchor most pages on one primary element and let the rest stay small ([primary-per-page](./strategist-image.md)).
**Through-line — one family, many roles.** A spot sheet pays off more when the same motif family also drives the cover and section dividers. A large cover / divider anchor is not a giant sheet cell—generate it as its own `hero_page` image sharing the sheet's `deck_rendering`, `color_scheme`, and subject world. Plan this only when the deck leans into illustration, never as a quota.
diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.md
index 452313d6..9ee4409f 100644
--- a/skills/ppt-master/references/image-layout-spec.md
+++ b/skills/ppt-master/references/image-layout-spec.md
@@ -2,9 +2,9 @@
# Image Layout Specification
-Sizing reference for side-by-side or multi-image pages. Use only after Strategist selects the composition; this file never selects layout or crop policy.
+Sizing reference for side-by-side or multi-image pages. Use after Strategist proposes a preferred composition; this file never locks layout or crop policy.
-**Selected pattern, flexible geometry**: Let original aspect ratio inform the container. A `no-crop` asset displays completely; an `adaptive` asset may use `meet` or a focal-safe `slice`. Rework geometry within the selected pattern when either mode produces weak hierarchy, unsafe cropping, or excessive dead space; changing the pattern requires an upstream Design Spec update.
+**Preferred pattern, Executor-owned realization**: Let original aspect ratio inform the container. A `no-crop` asset displays completely; an `adaptive` asset may use `meet` or a focal-safe `slice`. Rework geometry or choose another composition when the recommendation produces weak hierarchy, unsafe cropping, excessive dead space, or a poorer communication result. Preserve binding resource/content/crop constraints; a pattern-only change needs no upstream update.
> **Scope**: The ratio tables and formulas are calculation aids for a selected side-by-side or multi-image plan. Hero, background, accent, and other compositions stay outside this file. Layout never overrides the `no-crop` boundary owned by [`strategist-image.md`](./strategist-image.md) and [`executor-image.md`](./executor-image.md).
@@ -13,13 +13,13 @@ Sizing reference for side-by-side or multi-image pages. Use only after Strategis
## Layout Decision Flow
```
-1. Read the selected narrative intent, hierarchy, and primary/modifier ids from Strategist's plan.
-2. If the selected pattern is not side-by-side or multi-image, this spec does not apply.
+1. Read the narrative intent, hierarchy, and preferred primary/modifier ids from Strategist's plan.
+2. If the preferred or Executor-selected pattern is not side-by-side or multi-image, this spec does not apply.
3. Read the asset's `no-crop` boundary and original dimensions; calculate ratio (width/height).
4. Use the tables as candidate structures, not an automatic selector.
5. Calculate the image/text rectangles, then choose `meet` or focal-safe `slice` within the crop boundary.
-6. Revise geometry within the selected ids when the result weakens hierarchy, legibility, or required image content.
-7. Return upstream for a different pattern, resource, role, or crop boundary; Executor never rewrites selection.
+6. Revise geometry or choose another composition when the result weakens hierarchy, legibility, or required image content.
+7. Return upstream only for a different resource, role, must-use decision, crop boundary, or another binding constraint; Executor owns pattern-only realization changes.
```
**When to run**: after `analyze_images.py` has produced current dimensions and a side-by-side or multi-image composition is under consideration. Skip this sizing reference for other page structures.
@@ -63,8 +63,8 @@ Image height = W / R = 1160 / R px
Text area height = H - image height - gap(20px)
Review: if the remaining text area cannot carry the planned copy legibly,
-rebalance the rectangles within the selected pattern; otherwise return upstream
-for a Design Spec pattern update.
+rebalance the rectangles or choose another composition while preserving binding
+resource/content/crop constraints.
```
### Left-Right Layout Calculation
@@ -83,7 +83,7 @@ Image height = image width / R
Text area width = W - image width - gap(20px)
```
-**Review**: if the remaining text area cannot carry the planned copy legibly, rebalance the image/text rectangles within the selected pattern; otherwise return upstream for a Design Spec pattern update.
+**Review**: if the remaining text area cannot carry the planned copy legibly, rebalance the image/text rectangles or choose another composition while preserving binding resource/content/crop constraints.
---
@@ -108,7 +108,7 @@ Image: 773x560 (left), Text area: 367x560 (right) → 7:3 left-right
```
Original: 1820x1040, R=1.75
Strategist compares top-bottom: image height=663, text area=-43 ❌
-Strategist selects left-right: image 780x446 (left), text area 360x600 (right) → 7:3 left-right
+Strategist recommends left-right: image 780x446 (left), text area 360x600 (right) → 7:3 left-right
```
---
@@ -177,7 +177,7 @@ Image positions:
| Proportion does not reflect information weight | Rebalance image and text rectangles |
| Container conflicts with the native ratio | Change the container, choose `meet`, or use a focal-safe crop |
| Required pixels, labels, identity, or evidence would be cropped | Use `preserveAspectRatio="xMidYMid meet"` and recompose around the complete image |
-| Text area cannot carry the planned copy legibly | Increase its area within the selected pattern; otherwise return upstream |
+| Text area cannot carry the planned copy legibly | Increase its area or choose another composition while preserving binding constraints |
---
@@ -188,7 +188,7 @@ This spec only defines layout calculation. Write computed fields into the Image
| Field | Meaning |
|-------|---------|
| `Ratio` | Original image width / height |
-| `Layout pattern` | Strategist-selected catalog pattern; semantic composition fixed, geometry flexible |
+| `Layout pattern` | Strategist-recommended catalog pattern; preferred composition, Executor-owned realization |
| `Crop Policy` | `no-crop` protects complete pixels; `adaptive` lets Executor choose `meet` or focal-safe `slice` |
| `Reference` | Optional calculated image/text rectangles, focal notes, and composition intent |
| `spec_lock.md images` value | `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` |
@@ -231,5 +231,5 @@ python3 scripts/analyze_images.py <project_path>/images --canvas xiaohongshu #
| Role | Responsibility |
|------|---------------|
-| **Strategist** | Run `analyze_images.py`, select the catalog pattern/resources, and record the crop boundary |
-| **Executor** | Realize the selected pattern for the actual asset/page while preserving its ids, role, source, must-use, and `no-crop` constraints |
+| **Strategist** | Run `analyze_images.py`, recommend a catalog pattern, select resources, and record the crop boundary |
+| **Executor** | Choose the actual composition for the asset/page while preserving role, source, must-use, content, and `no-crop` constraints |
diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.md
index 1284e33e..17434e38 100644
--- a/skills/ppt-master/references/strategist-image.md
+++ b/skills/ppt-master/references/strategist-image.md
@@ -49,13 +49,13 @@ Follow `latex_render.py --help` for the manifest fields. The renderer writes dim
## 4. Image Resource List
-Add §VIII rows for the image resources actually planned from the confirmed source boundary and for every selected formula; a formula-only plan contains only formula rows. A permitted but unused source needs no row. Author each row's filename, dimensions/ratio, layout pattern, crop policy, purpose/type, acquisition, status, reference, and conditional AI fields as part of the complete Design Spec. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). When a planned or explicitly required asset is not yet available, retain its row as `Pending` or `Needs-Manual`; never remove the row or change `Acquire Via` to make the Design Spec look complete. After §VIII passes final confirmation, project every placed row into `spec_lock.md images` as `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` and omit unplaced Illustration Sheets. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.
+Add §VIII rows for the image resources actually planned from the confirmed source boundary and for every selected formula; a formula-only plan contains only formula rows. A permitted but unused source needs no row. Author each row's filename, dimensions/ratio, preferred layout pattern, crop policy, purpose/type, acquisition, status, reference, and conditional AI fields as part of the complete Design Spec. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). When a planned or explicitly required asset is not yet available, retain its row as `Pending` or `Needs-Manual`; never remove the row or change `Acquire Via` to make the Design Spec look complete. After §VIII passes final confirmation, project every placed row into `spec_lock.md images` as `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` and omit unplaced Illustration Sheets. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.
**Prepared-user fast path**: For initial imported or user-supplied assets confirmed as `provided`, copy the exact `Filename` basename and derive `Dimensions` / `Ratio` from that row's `Width` / `Height` / `AspectRatio` in the latest `analysis/image_analysis.csv`; drop source-side directories, set `Acquire Via: user` and `Status: Existing`, and decide the remaining §VIII fields normally. Existing §VIII / lock / provenance-manifest records override this inference. Assets declared as `ai`, `web`, `slice`, `formula`, or manual fulfillment retain that provenance and advance through their own status lifecycle after entering `images/`; location never reclassifies them as `user / Existing`.
-🚧 **GATE — non-formula rows**: read every entry in [`image-layout-patterns.md`](./image-layout-patterns.md), starting from its `High-Yield Patterns` router. Copy one primary `#<id> <name>` plus any modifier names verbatim into each row; no empty, paraphrased, or invented ids.
+🚧 **GATE — non-formula rows**: read every entry in [`image-layout-patterns.md`](./image-layout-patterns.md), starting from its `High-Yield Patterns` router. Copy one primary `#<id> <name>` plus any modifier names verbatim into each row as a concrete preferred composition; no empty, paraphrased, or invented ids.
-**Default — resolve each row against the high-yield router before selecting a plain split or grid (may override when the content genuinely wants one):** the boolean-geometry family costs no extra asset and is the largest single lever on how designed the exported deck looks. A deck whose rows are all bare `#2` / `#3` / `#5` / `#6` with no modifier ids did not consult the catalog; reopen it before finalizing §VIII. Strategist owns that pattern selection; Executor adapts its geometry while retaining the selected primary/modifier semantics, resource role, and explicit constraints. Audit the completed column against page intent: repeated left/right or top/bottom structures are valid when the narrative calls for them, but catalog families and modifiers must remain available without a usage quota.
+**Default — resolve each row against the high-yield router before selecting a plain split or grid (may override when the content genuinely wants one):** the boolean-geometry family costs no extra asset and is the largest single lever on how designed the exported deck looks. A deck whose rows are all bare `#2` / `#3` / `#5` / `#6` with no modifier ids did not consult the catalog; reopen it before finalizing §VIII. This is a Strategist recommendation, not a geometry or pattern lock. Executor may adapt or replace it after seeing the actual page while preserving the resource role, file/source, must-use status, crop boundary, content, and explicit user/template constraints; a pattern-only change needs no upstream rewrite. Audit the completed column against page intent: repeated left/right or top/bottom structures are valid when the narrative calls for them, but catalog families and modifiers must remain available without a usage quota.
Choose narrative intent before dimensions: hero/full-bleed, atmosphere/background, side-by-side, or accent/inline. Portrait and multi-image calculations belong to [`image-layout-spec.md`](./image-layout-spec.md). Write `Crop Policy: no-crop` whenever cropping could remove required pixels, labels, evidence, identity, or edge content; screenshots, charts, certificates/contracts, dense diagrams, logos, product markings, and formulas are common triggers rather than an exhaustive list. Otherwise write `Crop Policy: adaptive`: Executor may use complete display or a focal-safe crop, and the value never commands cropping. Formula rows use `Type: Latex Formula`, `Acquire Via: formula`, `Crop Policy: no-crop`, and `Rendered` or `Needs-Manual`.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 947b96c3..ce9445b0 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -270,7 +270,23 @@ Formula policy and formula-asset planning are conditional. If the source contain
The module owns formula policy, AI rendering alternatives, acquisition paths, resource rows, prompt depth, page roles, and placement intent.
-### Visualization Candidate Recall (Non-blocking — Strategist recommends, no user confirmation needed)
+### Presentation Capability & Visualization Recall (Non-blocking — Strategist recommends, no user confirmation needed)
+
+**Per-page capability recall**: Before finalizing §IX, consider the short menu
+below. Select only capabilities that strengthen the page's communication or
+visual expression; no page or deck owes a usage quota. Record semantic intent
+in existing Design Spec fields, never commands, coordinates, group ids, or
+effect parameters. Omit unused recommendation lines instead of writing `none`.
+Executor owns realization under the receiving capability contract and may adapt
+or decline the two non-literal §IX suggestion lines while preserving content
+and intent; explicit user/template requirements remain binding.
+
+| Capability | Opportunity signal | Design Spec handoff |
+|---|---|---|
+| Image composition | Image-as-canvas plus native overlay, editorial crop, collage, cutout, or another image-led composition carries the page better than an adjacent rectangle | Propose a permitted image source; when selected, load [`strategist-image.md`](./strategist-image.md) and record an exact catalog §VIII `Layout pattern` as the preferred composition |
+| Native preset / Merge Shapes | A literal Office symbol or a compound silhouette, negative-space cutout, overlap-only region, or meaningful fragmentation strengthens the visual idea | Add an optional §IX `Native shape suggestion` with the semantic result plus a candidate preset or Boolean operation/operands |
+| Page transition | A section/state change, spatial continuity, or recorded/self-running flow benefits from motion between pages | Add an optional §IX `Motion suggestion` describing the communication job; leave effect and timing to Executor |
+| Object animation | Progressive reveal clarifies sequence, causality, comparison, hierarchy, or narration order | Add an optional §IX `Motion suggestion` describing reveal units/order; leave group ids, effect, and timing to Executor |
Review planned pages through two lenses:
@@ -314,7 +330,14 @@ A failed validation must be corrected with a recalled key. `no-template-match` i
| P03 | line_chart | Compare the source metrics over time |
```
-**Flag native-preset candidates**: In the affected page's §IX `Layout` / `Visualization`, note when the content calls for a literal stock PowerPoint chevron, block arrow, standard flowchart node, callout, banner, or star. Executor still decides the exact preset under its native-shape branch; this note never creates a §VII row by itself.
+**Native-geometry candidate detail**: Add `Native shape suggestion` to the
+affected §IX page when the content calls for a literal stock PowerPoint
+chevron, block arrow, standard flowchart node, callout, banner, or star. For a
+compound silhouette, cutout, common region, or meaningful fragmentation, name
+the candidate Union / Combine / Fragment / Intersect / Subtract operation,
+semantic operands, and intended result. Executor still decides the exact preset,
+Boolean construction, or ordinary SVG under its native-shape branch; the
+recommendation never creates a §VII row or lock field.
### Speaker Notes Requirements (Default — no discussion needed)
@@ -391,7 +414,7 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
Generate Step 4 owns this sequence. `design_spec.md` is the complete human-readable decision; `spec_lock.md` is its context-selected execution subset/routing contract. Consume `result.json` once into the initial Design Spec and never reopen it for the lock. Refinement edits that same Design Spec; affected user revisions become the latest authority. Never treat the planning files as parallel interpretations.
1. Use the retained complete final-confirmation state already read once by Generate Step 4, then read `templates/design_spec_reference.md`.
-2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, and image/chart patterns remain References unless promoted.
+2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/chart patterns remain References unless promoted.
3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before entering an enabled refine-spec review or authoring `spec_lock.md`.
4. If enabled, run [`refine-spec`](../workflows/stages/refine-spec.md) after Gate 1; edit only that Design Spec and create no lock before explicit approval.
5. Read `templates/spec_lock_reference.md`. From the approved Design Spec plus context, create the lock once or resynchronize stale derived state. Retain identity/refinements, select stable roles/routing, omit unnamed page-local values, and do not reopen evidence. This is implementation judgment, not another recommendation.
@@ -413,9 +436,9 @@ Generate Step 4 owns this sequence. `design_spec.md` is the complete human-reada
⛔ **GATE 2 — lock context fidelity.** After Gate 1 closes, author machine-relevant anchors/routing into `spec_lock.md`. The lock may normalize syntax and add justified recurring roles, but must not change identity, discard a refinement, introduce a direction, or become a field copy/allowlist. On contradiction, return to Gate 1 using retained confirmation by default or the approved revised Design Spec after refinement; fresh recovery reads persisted final evidence once only when active state is absent.
-**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, pattern, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor context policy lives in [executor-base.md](executor-base.md) §2.1. Repair from Gate 2's active decision authority, then re-author affected lock rows.
+**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, preferred-pattern reference, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor context policy lives in [executor-base.md](executor-base.md) §2.1. Repair from Gate 2's active decision authority, then re-author affected lock rows.
-**Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or patterns require upstream repair; Executor never reverse-projects a choice as fact. Promote garnish upstream before reuse, read back and validate the affected planning fragments, and never add values to silence a comparison.
+**Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or recurring cross-page identity patterns require upstream repair; a page-local §VIII preferred image pattern follows [`executor-image.md`](./executor-image.md) and may change during realization. Executor never reverse-projects a local choice as planning fact. Promote recurring garnish upstream before reuse, read back and validate the affected planning fragments, and never add values to silence a comparison.
- **Communication trace is mandatory**: Keep the full confirmed communication contract in `design_spec.md §I`, then project only `audience`, `objective`, `core_message`, and canonical `consumption_mode` into `spec_lock.md communication`. Write `objective` as one concise execution sentence that preserves both the confirmed `communication_intent` and the success condition in `audience_outcome`; do not copy `delivery_context`, `artifact_afterlife`, dates, provenance, or conflict-resolution commentary into the lock. Before finalizing §IX, check that every named purpose has at least one outline obligation and **every Slide block**, including cover / divider / closing pages, has an `Audience move` that advances the global outcome. A page that advances no purpose or outcome should be merged, rewritten, or cut. `project_manager.py validate` and `svg_quality_checker.py` enforce the compact lock fields and per-page move presence, not their subjective quality.
- **Custom behavior is concise and executable**: For confirmed `custom` mode or visual style, project one resolved `mode_behavior` / `visual_style_behavior` sentence or short paragraph. When the direction actually combines or borrows catalog entries, also project the exact, comma-separated `mode_references` / `visual_style_references`; omit the field for a genuinely novel direction and never fabricate a nearby reference. Preserve the confirmed direction, reference locked role names such as `colors.primary` when needed, and omit selection history, contradictions, precedence explanations, or other Design Spec provenance. Executor reads these fields from the retained lock and loads every referenced catalog entry once per valid context.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 971ee0e5..5cec815e 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -12,12 +12,12 @@
"skills/ppt-master/templates/schemas/*.json"
],
"exclude": [],
- "max_tokens": 365600
+ "max_tokens": 367500
},
"file_budgets": {
"AGENTS.md": 2350,
"skills/ppt-master/SKILL.md": 850,
- "skills/ppt-master/references/executor-base.md": 7450,
+ "skills/ppt-master/references/executor-base.md": 7650,
"skills/ppt-master/references/executor-structured.md": 5300,
"skills/ppt-master/references/executor-chart.md": 3100,
"skills/ppt-master/references/executor-image.md": 900,
@@ -28,10 +28,10 @@
"skills/ppt-master/references/svg-effects.md": 11600,
"skills/ppt-master/references/native-data-interface.md": 6200,
"skills/ppt-master/references/pptx-structure-interface.md": 4300,
- "skills/ppt-master/references/strategist.md": 13475,
- "skills/ppt-master/references/strategist-image.md": 2250,
+ "skills/ppt-master/references/strategist.md": 13900,
+ "skills/ppt-master/references/strategist-image.md": 2300,
"skills/ppt-master/references/strategist-template.md": 2100,
- "skills/ppt-master/templates/design_spec_reference.md": 2850,
+ "skills/ppt-master/templates/design_spec_reference.md": 2975,
"skills/ppt-master/templates/spec_lock_reference.md": 2350,
"skills/ppt-master/workflows/generate-pptx.md": 12700,
"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800
@@ -45,7 +45,7 @@
"skills/ppt-master/SKILL.md",
"skills/ppt-master/workflows/routing.md"
],
- "max_tokens": 5425
+ "max_tokens": 5475
},
"support.sponsor-recommendation.en": {
"description": "English sponsor context for explicit user requests for model, AI image model, API/provider, or hosted-service recommendations.",
@@ -93,7 +93,7 @@
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/decks/README.md"
],
- "max_tokens": 57650
+ "max_tokens": 57775
},
"route.create-template.layout": {
"description": "Create Layout path through Template_Designer, SVG core, and the structured PPTX interface.",
@@ -111,7 +111,7 @@
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/layouts/README.md"
],
- "max_tokens": 57825
+ "max_tokens": 57950
},
"route.enhance-native-pptx": {
"description": "Finished-PPTX native enhancement route.",
@@ -122,7 +122,7 @@
"files": [
"skills/ppt-master/workflows/native-enhance-pptx.md"
],
- "max_tokens": 8450
+ "max_tokens": 8500
},
"route.fill-native-pptx": {
"description": "Raw-PPTX native fill route.",
@@ -133,7 +133,7 @@
"files": [
"skills/ppt-master/workflows/template-fill-pptx.md"
],
- "max_tokens": 11100
+ "max_tokens": 11150
},
"route.generate.planning": {
"description": "Generate-PPTX planning through Strategist, including reference-first whole-document authoring and representative multi-source custom mode/style synthesis; schemas and optional scaffolds are tool-consumed.",
@@ -322,7 +322,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 82500
+ "max_tokens": 83800
},
"route.generate.flat-ai-two-types": {
"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",
@@ -335,7 +335,7 @@
"stage.generate.image.ai-two-types"
],
"files": [],
- "max_tokens": 123000
+ "max_tokens": 124375
},
"route.generate.flat-in-hand-image": {
"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",
@@ -347,7 +347,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 96325
+ "max_tokens": 97675
},
"route.generate.flat-web-image": {
"description": "Generate-PPTX context with web image acquisition.",
@@ -360,7 +360,7 @@
"stage.generate.image.web"
],
"files": [],
- "max_tokens": 103575
+ "max_tokens": 104925
},
"route.enhance-native-pptx.audio": {
"description": "Enhance Native PPTX with the shared narration-audio stage.",
@@ -370,7 +370,7 @@
"stage.shared.generate-audio"
],
"files": [],
- "max_tokens": 13375
+ "max_tokens": 13425
},
"route.generate.beautify-flat-no-image": {
"description": "Generate-PPTX 1:1 beautify profile on the flat no-image path.",
@@ -380,7 +380,7 @@
"profile.generate.beautify-pptx"
],
"files": [],
- "max_tokens": 89400
+ "max_tokens": 90700
},
"route.generate.flat-no-image-chart": {
"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",
@@ -393,7 +393,7 @@
"stage.generate.verify-charts"
],
"files": [],
- "max_tokens": 106575
+ "max_tokens": 107875
},
"route.generate.brand-flat-no-image": {
"description": "Brand-preset flat Generate-PPTX path without image acquisition.",
@@ -405,7 +405,7 @@
"stage.generate.template.brand"
],
"files": [],
- "max_tokens": 89525
+ "max_tokens": 90825
},
"route.generate.deck-structured-no-image": {
"description": "Deck-preset structured Generate-PPTX path without image acquisition.",
@@ -417,7 +417,7 @@
"stage.generate.template.deck"
],
"files": [],
- "max_tokens": 99475
+ "max_tokens": 100750
},
"route.generate.layout-structured-no-image": {
"description": "Layout-preset structured Generate-PPTX path without image acquisition.",
@@ -429,7 +429,7 @@
"stage.generate.template.layout"
],
"files": [],
- "max_tokens": 99900
+ "max_tokens": 101200
},
"route.generate.topic-only-flat-no-image": {
"description": "Topic research followed by the default flat no-image Generate-PPTX path.",
@@ -439,7 +439,7 @@
"route.generate.flat-no-image"
],
"files": [],
- "max_tokens": 83900
+ "max_tokens": 85200
},
"stage.generate.executor.flat": {
"description": "Incremental flat Executor core with representative multi-source custom mode/style execution.",
@@ -549,7 +549,7 @@
"stage.generate.executor.image"
],
"files": [],
- "max_tokens": 59100
+ "max_tokens": 59550
},
"stage.generate.topic-research": {
"description": "Gap-targeted factual intake stage.",
@@ -619,7 +619,7 @@
"skills/ppt-master/scripts/docs/pptx-transitions.md",
"skills/ppt-master/scripts/docs/svg-pipeline.md"
],
- "max_tokens": 22375
+ "max_tokens": 22875
},
"stage.generate.video-motion-plan": {
"description": "Conditional resolved animation-to-video handoff contract.",
@@ -685,7 +685,7 @@
"stage.generate.strategist.template"
],
"files": [],
- "max_tokens": 60250
+ "max_tokens": 61100
},
"route.generate.planning-template-ai": {
"description": "Explicit template workspace plus confirmed AI-image planning.",
@@ -695,7 +695,7 @@
"route.generate.planning-ai"
],
"files": [],
- "max_tokens": 72700
+ "max_tokens": 73575
},
"stage.generate.executor.chart": {
"description": "Conditional chart/table page execution rules.",
@@ -711,7 +711,7 @@
"files": [
"skills/ppt-master/references/strategist-image.md"
],
- "max_tokens": 2250
+ "max_tokens": 2300
},
"stage.generate.strategist.image-layout": {
"description": "Non-formula image planning plus the image-layout pattern catalog required for Section VIII rows.",
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 33238396..058a9b42 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -166,7 +166,7 @@ Use the §VII table only when at least one real catalog reference is selected. A
For every independent data chart or pure text-grid table, add `- **Native-ready**: yes|no` to its §IX Slide block. Choose `yes` only when the confirmed requirement or artifact afterlife benefits from an editable native data object; otherwise use `no`. Conceptual visualizations and incidental sparklines, KPI trends, or insets omit this field and remain ordinary SVG.
-In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Copy the selected `Layout pattern` id/name and modifiers verbatim; set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them.
+In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Copy the recommended `Layout pattern` id/name and modifiers verbatim as a preferred composition; set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them.
### 2.4 Complete page roster and notes
@@ -194,7 +194,15 @@ Write one ordered Slide block per page. Slide count and order must equal §I `Pa
- **Presentation purpose**: <inform, persuade, inspire, instruct, report, or resolved combination>
```
-Add `Visualization` and `Images` to a Slide block when it consumes §VII/§VIII rows or uses a page-local visualization. State whether `Visualization` is data-driven when source values determine geometry; this page-level declaration remains authoritative even when no catalog reference fits. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables. Add `Fact IDs` for sourced claims and `Data class: scenario` for invented demo values. Add `Cover impact` to P01 except on preservation paths; add `Closing impact` only when the final page genuinely resolves the deck. Roster ids/count/order and final content are authoritative. Image patterns preserve their selected semantic composition; chart rows only offer page-local references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
+Append either or both optional lines only when the capability earns a place;
+never write an empty or `none` placeholder:
+
+```markdown
+- **Native shape suggestion**: <semantic object/result plus candidate preset family or Boolean operation/operand roles>
+- **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order>
+```
+
+Add `Visualization` and `Images` to a Slide block when it consumes §VII/§VIII rows or uses a page-local visualization. State whether `Visualization` is data-driven when source values determine geometry; this page-level declaration remains authoritative even when no catalog reference fits. Add `Native shape suggestion` only when a literal PowerPoint preset or a compound silhouette/cutout/intersection/fragment may strengthen the page; describe the semantic object/result and candidate family or Boolean operation/operands, not coordinates, paths, or commands. Executor chooses the actual preset, Boolean construction, or ordinary SVG. Add `Motion suggestion` only when a page transition or progressive reveal would strengthen communication; describe its purpose and semantic order/relationship in natural language, not registry keys, Effect Options, durations, group ids, or coverage. It remains a recommendation: Executor owns the exact native behavior and may simplify it or choose no motion unless that would violate an explicit user requirement. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables. Add `Fact IDs` for sourced claims and `Data class: scenario` for invented demo values. Add `Cover impact` to P01 except on preservation paths; add `Closing impact` only when the final page genuinely resolves the deck. Roster ids/count/order and final content are authoritative. §VIII image patterns are preferred composition references; chart rows only offer page-local references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
For free-design pages, describe `Layout` through relationships, hierarchy, regions, and column spans; do not prescribe element-level `x`, `y`, `width`, or `height` or duplicate the global geometry in §II/§V. Exact coordinates belong to Executor SVG authoring. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it.
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index c7c068a9..d94abd91 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -92,7 +92,7 @@ New locks always write `title_family` and `body_family`, even when their values
- `icons.library` records the primary stylistic library selected from `chunk-filled`, `tabler-filled`, `tabler-outline`, or `phosphor-duotone`, or `none` when no generic bundled icons are selected. Selected `simple-icons/*` brand marks may appear alone or alongside it in `inventory` without becoming a stylistic library. The inventory records planned bundled choices, while every SVG already under `<project_path>/icons/` remains valid prepared execution material.
- `objective` grammar: one concise sentence preserving the deck goal and audience success condition.
- `image_rendering` grammar: one catalog id, or `custom` with `image_rendering_behavior`.
-- `images`: `- <key>: <path> | source=<via> | pattern=<layout> | crop=<adaptive|no-crop>`; e.g. `- p04: images/a.png | source=user | pattern=#2 Left image | crop=no-crop`. Omit unplaced sheets.
+- `images`: `- <key>: <path> | source=<via> | pattern=<layout> | crop=<adaptive|no-crop>`; e.g. `- p04: images/a.png | source=user | pattern=#2 Left image | crop=no-crop`. `pattern` preserves the Strategist's preferred catalog composition for Executor recall; it is not a geometry or realization lock. Omit unplaced sheets.
- Custom reference grammar: comma-separated exact catalog ids with no duplicates. Reference fields are valid only for `custom`; omit them for a genuinely novel direction.
- `stroke_width` grammar: `1.5`, `2`, or `3`; present only for `tabler-outline`.
- `page_rhythm` grammar: `P` + at least two digits (`P01`, `P100`) followed by `anchor|dense|breathing`.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index a637fdbd..8d96866b 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -549,7 +549,11 @@ expresses one complete object, they use the compact canonical
paint comes from the confirmed brief and template `design_spec.md`. After
inserting the complete helper group, add only the registered structural
attributes required by its Master/Layout or object-slot role; geometry and
-paint changes require a new helper render. `mirror` preserves the expanded
+paint changes require a new helper render. When actual `standard` / `fidelity`
+construction needs a Boolean result over closed shapes, Template_Designer
+decides whether to use `shape_boolean_svg.py` under
+[`native-shape-authoring.md`](../references/native-shape-authoring.md) §6; a
+brief/reference suggestion does not lock the operation. `mirror` preserves the expanded
lossless source contract in a new workspace and may only normalize transport details required by
the current compiler. Mirror never performs commonality
extraction, semantic synthesis, merge/split, promotion/demotion, renaming, or
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index b51bb856..e028f7e6 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -228,7 +228,7 @@ If the user opted out of the page but did not delegate confirmation, skip launch
With `refine_spec: true`, run [`refine-spec`](stages/refine-spec.md) after Gate 1: review that same file in chat, accept arbitrary revisions, touch no lock, and stop until explicit approval. Revisions supersede only affected decisions. Otherwise skip the stop.
-After the review closes, author `spec_lock.md` from the approved Design Spec and context. Preserve identity/refinements, every recurring typography role, reusable routing anchors, and each placed image's source/pattern/crop policy; omit page-local garnish and never write a separate image palette. Apply `strategist-template.md` §3 when active. Unhonorable requirements follow [`failure-recovery.md`](governance/failure-recovery.md).
+After the review closes, author `spec_lock.md` from the approved Design Spec and context. Preserve identity/refinements, every recurring typography role, reusable routing anchors, and each placed image's source/preferred-pattern reference/crop policy; omit page-local garnish and never write a separate image palette. Apply `strategist-template.md` §3 when active. Unhonorable requirements follow [`failure-recovery.md`](governance/failure-recovery.md).
**Conditional — split-mode note** (not a separate confirmation): after listing the Strategist confirmation stage details, append one short line (rendered in the user's language, prefixed with 💡) only when the confirmed mode is `split` or upstream-load signals make a fresh execution context materially useful. Judge those signals from recommended page count, source-material bulk, and substantial `topic-research` web-fetch accumulation:
@@ -357,7 +357,7 @@ Read references/visual-styles/<resolved-id>.md # one preset id, or each `visu
| `spec_lock.md images` or §VIII contains at least one image/formula row, or an active template carries bundled images | `executor-image.md` + `image-layout-patterns.md` + `image-layout-spec.md` + `svg-image-embedding.md` |
| At least one placed image has `Status: Sourced` | `executor-web-image.md` after the image branch |
| The locked style/current page calls for noncanonical or alpha paint, dash/cap/join, tracking/decoration/outline, gradient/filter/glow/shadow, path/transform/clipping, or another constructed effect | `svg-effects.md` before authoring that value or effect |
-| A page calls for a literal PowerPoint stock shape, an explicit Merge Shapes operation, or shape-built dimensional form (cylinder/pedestal, layered diagram, reflection, ground plane) | `native-shape-authoring.md` before selecting or materializing that geometry. This trigger is image-independent: a text-only, data-only, or icon-only page reaches it the same way |
+| §IX contains `Native shape suggestion`, or a page calls for a literal PowerPoint stock shape, an explicit Merge Shapes operation, or shape-built dimensional form (cylinder/pedestal, layered diagram, reflection, ground plane) | `native-shape-authoring.md` before selecting or materializing that geometry. This trigger is image-independent: a text-only, data-only, or icon-only page reaches it the same way |
| All SVG pages and SVG quality gates are complete | `executor-notes.md` before generating speaker notes |
No branch is loaded by analogy. Evaluate these triggers from `spec_lock.md`, §VII/§VIII, the selected style, and the current page plan.
@@ -386,7 +386,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`
-Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. When a page actually needs a literal stock shape or an explicit Merge Shapes operation, load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before drawing or materializing it. Diagram relationships remain Shape-first; do not infer a preset from contour similarity.
+Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Treat §IX `Native shape suggestion` as a candidate, not a command: inspect the actual page construction, then choose the precise preset/Boolean result or ordinary SVG. Load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before materializing an adopted native treatment. Diagram relationships remain Shape-first; do not infer a preset from contour similarity.
`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, validate and read back the affected fragments, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.
@@ -437,6 +437,20 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final
> **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the [`visual-review`](stages/visual-review.md) quality-gate stage before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.
+> **Motion capability (conditional)?** After `notes/total.md` exists, inspect §IX
+> `Motion suggestion` rows, explicit user motion requirements, and an existing
+> `<project_path>/animations.json`. With none of the three, keep the exporter
+> defaults (`fade` page transition, per-element animation `none`) and load no
+> motion reference. An existing sidecar always runs
+> [`customize-animations`](stages/customize-animations.md) to validate and
+> resolve preserve/adjust/replace intent before export. With no sidecar, a
+> deck-wide request loads [`animations.md`](../references/animations.md) and
+> resolves Step 7.3 flags; any `Motion suggestion` or per-slide/per-object
+> request runs the custom stage. Strategist owns the communication purpose;
+> Executor owns exact native effects, options, order, timing, and whether a
+> non-literal suggestion should simplify to `none`. Never add motion for
+> coverage or variation.
+
---
### Step 7: Post-processing & Export
@@ -471,6 +485,15 @@ python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
```
+For deck-wide motion settings, append the resolved flags from
+[`animations.md`](../references/animations.md). When the conditional custom
+stage preserves or produces `<project_path>/animations.json`, keep the base command above:
+the exporter reads the sidecar automatically. Explicit motion flags override
+the corresponding sidecar default/slide fields, while group overrides remain
+unless `-a none` hard-disables all object motion; do not mix deck-wide flags
+with a custom sidecar in the normal workflow. With no adopted motion input or
+existing sidecar, preserve the normal `fade` / `none` defaults.
+
**Success criterion**: The command exits successfully and produces:
- `exports/<project_name>_<timestamp>.pptx`
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index eeff3437..e3439f4f 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -52,8 +52,8 @@ route selection. After selection, the route authority owns execution.
| Data charts exist | Run [`verify-charts`](./stages/verify-charts.md) before export |
| User explicitly requests visual review | Run [`visual-review`](./stages/visual-review.md) before post-processing |
| User requests preview, selection, or annotation application | Run [`live-preview`](./stages/live-preview.md) at the stage defined there |
-| User requests page transitions, auto-advance, or deck-wide animation settings | Load [`animations`](../references/animations.md) and apply its export-level contract |
-| User requests per-slide or object-level animation control | Run [`customize-animations`](./stages/customize-animations.md) during post-processing |
+| User requests page transitions, auto-advance, or deck-wide animation settings without page-specific motion planning or an existing `animations.json` | Load [`animations`](../references/animations.md) and apply its export-level contract |
+| Generate `design_spec.md §IX` contains `Motion suggestion`, `<project_path>/animations.json` already exists, or the user requests per-slide or object-level animation control | Run [`customize-animations`](./stages/customize-animations.md) after notes readiness and before Generate Step 7 |
| Generated project needs narration audio | Run [`generate-audio`](./stages/generate-audio.md) after notes/export readiness |
**Hard rule — profile, not fifth route**: The 1:1 beautify behavior uses the same Strategist → Executor → SVG export lifecycle as Generate PPTX. It changes content/page invariants; it does not define a separate artifact lifecycle.
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index b07828da..c0a2abff 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -5,9 +5,11 @@ description: Optional post-processing stage for per-slide and per-object animati
# Customize Animations Stage
> Optional Generate-PPTX post-processing stage for per-slide or per-object
-> animation control. Run when the user asks to customize slide-specific motion,
-> object order, effects, timing, or reveals. Deck-wide transitions,
-> auto-advance, and deck-wide per-element object settings use
+> animation control. Run when Design Spec §IX contains at least one
+> `Motion suggestion`, when `<project_path>/animations.json` already exists, or
+> when the user asks to customize slide-specific motion, object order, effects,
+> timing, or reveals. Deck-wide transitions, auto-advance, and deck-wide
+> per-element settings without page-specific motion or an existing sidecar use
> [`animations.md`](../../references/animations.md) directly and do not activate
> this stage.
@@ -15,11 +17,12 @@ description: Optional post-processing stage for per-slide and per-object animati
| Condition | Action |
|---|---|
+| Design Spec §IX contains at least one `Motion suggestion` | Run this stage after notes exist and before Generate Step 7 |
| User asks for per-slide or per-object animation, reveal order, timing, or effect changes | Run this stage |
-| User only wants the default deck (page transitions, no element builds) | Do not run; normal `svg_to_pptx.py` export is enough |
-| User only wants deck-wide page transitions, auto-advance, or one per-element object animation policy | Do not run; apply [`animations.md`](../../references/animations.md) with exporter flags such as `-a auto` or `-a emphasis_spin` |
+| `<project_path>/animations.json` already exists | Run this stage to validate it and resolve preserve/adjust/replace intent before export |
+| No suggestion, motion request, or existing sidecar; user only wants the default deck | Do not run; normal export keeps page transitions and no element builds |
+| No existing sidecar; user only wants deck-wide page transitions, auto-advance, or one per-element object animation policy | Do not run; apply [`animations.md`](../../references/animations.md) with exporter flags such as `-a auto` or `-a emphasis_spin` |
| `svg_output/*.svg` is missing | Complete the main Executor phase first |
-| `animations.json` exists | Resolve regeneration versus modification through the §1 intent gate before changing it |
---
@@ -39,9 +42,12 @@ description: Optional post-processing stage for per-slide and per-object animati
|---|---|
| Explicit regeneration / rewrite / replacement | Rebuild the semantic grouping plan and replace `animations.json`; the previous choreography is not a constraint |
| Explicit adjustment / tuning / repair | Validate first, preserve the existing choreography where its semantic units remain valid, and migrate affected group references after any required regrouping |
+| Stage activated by new §IX suggestions without a user replacement request | Validate first; preserve valid existing choreography and adjust only the affected semantic units |
+| Existing sidecar with no new motion instruction | Validate and preserve it unchanged; if invalid, repair the owning sidecar/group reference before export |
| Ambiguous generation request | Ask whether to regenerate from scratch or modify the current animation; do not choose on the user's behalf |
-When the existing sidecar will be modified:
+Whenever an existing sidecar is present, validate it before deciding to
+preserve or modify it:
```bash
python3 skills/ppt-master/scripts/animation_config.py validate <project_path>
@@ -54,15 +60,30 @@ the animation plan merely because it already exists.
**Optional-context fallback**: these semantic files inform this supporting stage but are not its gate artifacts. If any are absent, state what is missing and proceed with every remaining file plus visible SVG content. If all three context inputs are absent, use only explicit user instructions, visible SVG content, and the resolution rules in [`animations.md`](../../references/animations.md); do not infer detailed choreography beyond what the page itself expresses.
+**Decision ownership — advice versus requirement**: A §IX
+`Motion suggestion` expresses the Strategist's recommended communication job or
+reveal relationship; it does not lock an effect, Effect Options, timing,
+trigger, group id, or coverage. Explicit user motion requirements remain
+mandatory. Executor maps an adopted suggestion to the native registry, may
+adjust its effect/order/timing or choose `none` when motion would reduce
+clarity, and never changes page content merely to justify animation.
+
+**No-op is complete**: Evaluate suggestions before regrouping SVG content. If
+no `animations.json` exists, every page should retain the normal `fade`
+transition and no object builds, and no explicit user requirement remains
+unmet, change no SVG, create no sidecar, and return to Generate Step 7. Never
+author motion merely to expose a capability.
+
---
-## 2. Rebuild Semantic Animation Groups, Then List IDs
+## 2. Rebuild Semantic Animation Groups When Needed, Then List IDs
-**Mandatory — content-first grouping audit**: inspect every slide's visible
-content against its communication job and speaker flow before treating any
-top-level `<g>` as an animation anchor. Existing groups are implementation
-evidence only. Keep a current group unchanged only after confirming that it
-already represents exactly one audience-facing reveal unit.
+**Mandatory when object animation is in scope — content-first grouping audit**:
+inspect every slide's visible content against its communication job and speaker
+flow before treating any top-level `<g>` as an animation anchor. Existing
+groups are implementation evidence only. Keep a current group unchanged only
+after confirming that it already represents exactly one audience-facing reveal
+unit. A transition-only plan skips regrouping and group listing.
| Content condition | Required grouping action |
|---|---|
@@ -226,8 +247,9 @@ one.
## 4. Edit `animations.json`
-**Hard rule — write every slide explicitly; let groups inherit**. Each
-slide under `slides.<slide>` MUST carry its own complete `transition` and
+**Hard rule — when this stage writes `animations.json`, write every slide
+explicitly; let groups inherit**. Each slide under `slides.<slide>` MUST carry
+its own complete `transition` and
`animation` block (effect + duration + stagger + trigger where applicable),
even when the values match `defaults`. This makes per-page rhythm visible
at a glance without mentally merging the inheritance chain. Group-level
@@ -322,27 +344,32 @@ omitted unless a marker-free legacy name needs an explicitly reviewed override.
---
-## 5. Validate, Refresh Derived SVGs, and Export
+## 5. Validate and Return to Generate Export
-Run sequentially:
+When `animations.json` was newly created or changed after the §1 validation,
+run:
```bash
python3 skills/ppt-master/scripts/animation_config.py validate <project_path>
-python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>
```
-**Validation**: the exported native PPTX must reflect the per-slide and
-per-object overrides, and `svg_final/` must reflect any semantic regrouping
-performed in §2. `--animation none` still disables all per-element animation
-and overrides `animations.json`. Unknown animation
+After validation succeeds, return to
+[`generate-pptx.md`](../generate-pptx.md) Step 7.1. Generate owns note
+splitting, `finalize_svg.py`, native export, and the published postflight
+receipt; Step 7.3 reads `<project_path>/animations.json` automatically. If §2
+changed `svg_output/`, complete its required final SVG quality rerun before
+returning. Do not finalize or export independently from this stage.
+
+**Validation**: The later native export must reflect the per-slide and
+per-object overrides. `--animation none` still disables all per-element
+animation and overrides `animations.json`. Unknown animation
effects/modes/triggers; unsupported effect options; incompatible, boolean,
non-finite, or out-of-range timing parameters; non-positive durations; negative
delay/stagger; invalid order; missing slides/groups; and structural-layer
targets fail validation. Transition validation remains strict. None of these
failures substitutes a fallback effect or silently drops a requested target.
-Generated export reads back row order, trigger, target, resolved effect,
+Generate Step 7 export reads back row order, trigger, target, resolved effect,
duration, offset, timing placement, IDs, and shape references. Narration
preserves these rows. Direct-PPTX routes fingerprint and preserve source object
animation; they never author it. See
@@ -350,8 +377,9 @@ animation; they never author it. See
### 5.1 Optional Video Motion Handoff
-When a downstream video renderer will enhance the deck, export with
-`--conversion-trace` and derive its motion plan from that resolved trace:
+When a downstream video renderer will enhance the deck, have Generate Step 7.3
+append `--conversion-trace`. After that final export succeeds, derive the motion
+plan from its resolved trace:
```bash
python3 skills/ppt-master/scripts/video_motion_plan.py \
@@ -370,10 +398,9 @@ renderer parameters but cannot replace the source effect. See
## ✅ Customize Animations Complete
-- [x] Semantic context and every slide's visible content were reviewed
-- [x] Each target is one post-regroup semantic unit with a real SVG id
-- [x] Regrouped SVG passed the final quality gate and refreshed `svg_final/`
-- [x] Every slide has explicit motion blocks; only divergent groups are listed
-- [x] Page and object motion were planned together with intentional timing
-- [x] Sidecar validation, re-export, semantic read-back, and package validation passed
-- [x] Any video plan came from the final resolved conversion trace
+- [x] Applicable semantic context and motion intent were resolved
+- [x] Adopted object targets use real post-regroup SVG ids when object motion is in scope
+- [x] `animations.json` is complete and validated when present; a no-op path creates none
+- [x] Any regrouped SVG passed the final quality gate
+- [x] Control returned to Generate Step 7 for preview, export, read-back, and package validation
+- [x] Any requested video plan waits for the final resolved conversion trace