Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(workflows): separate creative guidance from hard contracts

hugohe3af582e1925d3
diff --git a/docs/animations.md b/docs/animations.md
index e84850b9..66a7be67 100644
--- a/docs/animations.md
+++ b/docs/animations.md
@@ -103,10 +103,14 @@ audio/video workflows because they require media or bookmark targets.
## Customize Specific Objects
-Use `animations.json` only when deck-wide settings are not enough—for example, title first, chart second, conclusion last. The easiest path is to generate a complete scaffold from the actual slide groups, edit it, validate it, and export:
+Use `animations.json` only when deck-wide settings are not enough—for example,
+title first, chart second, conclusion last. List the real groups, write sparse
+overrides for only the affected slides and objects, validate, and export.
+`scaffold` remains an optional complete editing starter; delete untouched
+entries before using it as the final sidecar.
```bash
-python3 skills/ppt-master/scripts/animation_config.py scaffold <project>
+python3 skills/ppt-master/scripts/animation_config.py list-groups <project>
python3 skills/ppt-master/scripts/animation_config.py validate <project>
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
```
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 5e18e6d5..fcd209e9 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -437,7 +437,7 @@ Several architectural decisions shape this phase:
**The Design Spec owns the image-execution path.** Final confirmation from either the UI or chat is first persisted as `AI Image Acquisition Path` in `design_spec.md §I`; Image_Generator selects API, host-native, or manual from that value and may not reopen the decision during execution. `image_gen.py --manifest` belongs only to API Path A. The current CLI still contains a defensive guard that reads UI `result.json` and blocks an accidental Path A call when that file explicitly records `host-native` or `manual`. That guard is not an authority source, does not cover chat-only confirmation, and cannot replace Design Spec routing. It is a remaining implementation mismatch in the upstream authority chain, not a normal consumer path.
-**One coherent sheet for related spot illustrations.** When a deck needs three or more same-family small illustrations, the plan uses one AI illustration sheet row plus `slice` rows rather than separate generations. `slice_images.py` cuts the sheet into named transparent elements, those derived files join `images/`, and `analyze_images.py` is rerun so Executor sees their real dimensions. This is a style-cohesion rule as much as a cost rule: one sheet forces the small elements to share a visual hand.
+**One coherent sheet when related spot illustrations fit it.** Several same-family spots may share one AI illustration sheet plus `slice` rows when their cell shapes, detail, quality, and semantic needs are compatible; otherwise they may be generated independently. When the sheet path is chosen, `slice_images.py` cuts it into named transparent elements, those derived files join `images/`, and `analyze_images.py` is rerun so Executor sees their real dimensions.
**Terminal status before Executor.** Rows that require acquisition must end in `Generated`, `Sourced`, or `Needs-Manual`; `Pending` and `Failed` are not allowed to leak into Executor. A `Needs-Manual` row can continue through SVG generation only as a known placeholder/dependency, and Step 7 re-checks required files before final export.
@@ -449,16 +449,16 @@ Several architectural decisions shape this phase:
## Image-Text Layout: Primary Structures + Modifier Layers
-The catalog of *how an image is placed on a slide* (full vocabulary in [`references/image-layout-patterns.md`](../skills/ppt-master/references/image-layout-patterns.md)) splits 99 stable-id techniques into two layers that compose freely:
+The optional library of *how an image can be placed on a slide* (full vocabulary in [`references/image-layout-patterns.md`](../skills/ppt-master/references/image-layout-patterns.md)) offers 99 stable-id techniques in two freely composable layers:
- **Primary Structures** (container layouts / image-as-canvas + native overlay / multi-image compositions) — the page's bones. One or more per page; cross-Primary combinations like *side-by-side comparison + image-as-canvas annotation* are legitimate.
- **Modifier Layers** (non-rectangular clips / overlays & masks / texture / special techniques) — finish. Any number per page, stacked on top of the Primary.
-**Why allow explicit composition instead of imposing a "one Primary per page" quota.** The catalog expands compositional choice; it is not a layer-count metric. A page may use one or several Primary structures and any number of Modifiers when each layer contributes to the current narrative or hierarchy. The failure mode is a whole deck repeatedly collapsing into bare `#2` / `#3` / `#5` / `#6` with no Modifier use, not a requirement that every page be composite.
+**Why the library does not impose a catalog or layer quota.** It expands compositional choice rather than defining legal output. A page may use one or several Primary structures and any useful Modifiers, cite no id at all, or use a free-form composition when that better serves the narrative and hierarchy.
-**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 the layers are physically separated, not just tagged.** Patterns are organized with Primary structures first and Modifiers second so a reader who opens the optional library can navigate by construction role. Numbers remain 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 keep resolving.
-**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 composition intent flows through Strategist's resource list.** The `Layout pattern` column in `§VIII Image Resource List` carries one non-empty free-form suggestion and may optionally cite stable ids from the library; `Crop Policy` separately records `adaptive` or `no-crop`. This preserves a useful starting point across session re-entry without making the library or its numbering mandatory. Executor may resize, reflow, reposition, rebalance, replace the suggestion, or use another 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/animations.md b/docs/zh/animations.md
index 158cefc5..ba60ceeb 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -95,10 +95,12 @@ OOXML,而不是嵌入视频。对象动画包括进入、强调、动作路径
## 自定义具体对象
-只有当整份 deck 的统一设置不够用时才需要 `animations.json`,例如标题先出现、图表第二个出现、结论最后出现。最简单的方式是从真实页面分组生成完整 scaffold,修改后校验并导出:
+只有当整份 deck 的统一设置不够用时才需要 `animations.json`,例如标题先出现、
+图表第二个出现、结论最后出现。先列出真实分组,只为受影响页面和对象写稀疏覆盖,
+然后校验并导出。`scaffold` 仍可作为完整编辑起点,但最终 sidecar 应删除未改动项。
```bash
-python3 skills/ppt-master/scripts/animation_config.py scaffold <project>
+python3 skills/ppt-master/scripts/animation_config.py list-groups <project>
python3 skills/ppt-master/scripts/animation_config.py validate <project>
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
```
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index e3826b04..e7ebb088 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -431,7 +431,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
**图片执行路径以 Design Spec 为权威。** UI 或聊天中的最终确认都先固化为 `design_spec.md §I` 的 `AI Image Acquisition Path`;Image_Generator 根据该值选择 API、host-native 或 manual,不能在执行阶段重新决定。`image_gen.py --manifest` 只属于 API Path A。当前 CLI 仍保留一个读取 UI `result.json` 的防误调用 guard,用于在该文件明确记录 `host-native` / `manual` 时阻止误跑 Path A;它不是权威来源,不覆盖 chat-only,也不能替代 Design Spec 的路线判断。这是当前代码与上游权威链尚未闭合的实现差异,不能当作正常消费路径。
-**相关小插画用一张统一 sheet。** 当 deck 需要三个或更多同风格小插画时,资源计划使用一个 AI illustration sheet 行,再用若干 `slice` 行派生元素,而不是分别生成多张小图。`slice_images.py` 把 sheet 切成具名透明元素,这些派生文件进入 `images/`,随后重跑 `analyze_images.py`,让 Executor 看到真实尺寸。这既是成本规则,也是风格一致性规则:一张 sheet 会强迫这些小元素来自同一种视觉手法。
+**相关小插画适合时共用一张 sheet。** 多个同风格小插画在 cell 形状、细节、质量和语义需求兼容时,可以使用一个 AI illustration sheet 行再通过 `slice` 行派生元素;不兼容时可独立生成。选择 sheet 路径后,`slice_images.py` 把它切成具名透明元素,这些派生文件进入 `images/`,随后重跑 `analyze_images.py`,让 Executor 看到真实尺寸。
**Executor 前必须进入终态。** 需要获取的资源行必须落到 `Generated`、`Sourced` 或 `Needs-Manual`;`Pending` 和 `Failed` 不能漏进 Executor。`Needs-Manual` 可以作为已知占位 / 依赖继续进入 SVG 生成,但 Step 7 会在最终导出前重新检查必需文件是否已经存在。
@@ -443,16 +443,16 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
## 图文版式:Primary 主结构 + Modifier 修饰层
-「图片**怎么放上幻灯片**」的词表(完整词汇在 [`references/image-layout-patterns.md`](../../skills/ppt-master/references/image-layout-patterns.md))把 99 条稳定编号技法拆成两层、自由组合:
+「图片**可以怎么放上幻灯片**」的可选灵感库(完整词汇在 [`references/image-layout-patterns.md`](../../skills/ppt-master/references/image-layout-patterns.md))提供 99 条稳定编号技法,分成两层并可自由组合:
- **Primary 主结构**(容器布局 / 图作画布 + 原生覆盖 / 多图组合)—— 页面的骨架。一页可一个也可多个;跨 Primary 的组合,如「侧边对比 + 图作画布的注解卡」,是合规的。
- **Modifier 修饰层**(非矩形裁剪 / 遮罩与叠加 / 纹理 / 特殊技法)—— 装饰层。一页可叠任意多个,附着在 Primary 之上。
-**为什么显式允许复合,而不设「一页一个 Primary」配额。** 这份词表用于扩展构图选择,不是层数指标。一页可以由一个或多个 Primary 构成,并按需要叠加任意数量的 Modifier;每一层都必须对当前叙事或视觉层级有贡献。需要警惕的是整套 deck 反复退化为裸的 `#2` / `#3` / `#5` / `#6` 且完全不使用 Modifier,而不是要求每一页都必须复合。
+**为什么灵感库不设置目录或层数配额。** 它用于扩展构图选择,不定义合法输出。一页可以由一个或多个 Primary 构成,按需叠加 Modifier,也可以完全不引用编号,直接使用更适合叙事和层级的自由构图。
-**为什么物理拆分两层,而不是只打标签。** 词表被重排成「Primary 全部在前,Modifier 全部在后」——Strategist 或 Executor 读一次目录,就能从结构上内化「两层」心智模型。编号是稳定 id(`#38` 永远是「图作画布 + 注解卡」,不论它在文件里的物理位置),所以 `spec_lock.md`、`design_spec.md §VIII`、历史 executor 输出、过往示例里所有 `#<id>` 引用照样解析。
+**为什么物理拆分两层,而不是只打标签。** 灵感库按 Primary 在前、Modifier 在后组织,便于按构造角色查找。编号仍是稳定 id(`#38` 永远是「图作画布 + 注解卡」,不论它在文件里的物理位置),因此 `spec_lock.md`、`design_spec.md §VIII`、历史 executor 输出和过往示例里的既有 `#<id>` 引用照样解析。
-**为什么组合走 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。
+**为什么构图意图走 Strategist 资源列表。** `§VIII 图片资源列表` 的 `Layout pattern` 列承载一句非空自由格式建议,也可以按需引用灵感库的稳定编号;`Crop Policy` 独立记录 `adaptive` 或 `no-crop`。这让可用的构图起点通过 lock 投影在 session 重入后继续存在,但不要求完整读取灵感库或使用编号。Executor 可以调整尺寸、位置、流向与权重,也可以替换建议或使用其他构图。资源身份、必用 / 内容义务、`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 783315b1..74ac3f10 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -15,7 +15,7 @@ before the page plan is frozen, not only when a deck is already exported.
|---|---|---|
| Reveal content in step with the narration | Per-element object animation — `-a auto` deck-wide, or an `animations.json` sidecar for specific order, effects, timing, and triggers | Post-processing; §2, §4, [`customize-animations`](../workflows/stages/customize-animations.md) |
| A continuous action — slide-in, flip, camera push-in, progressive reveal, camera pan | **Morph: author the action as two static pages, then select Morph and add explicit pairs when identity must be deterministic.** There is no keyframe timeline anywhere in this pipeline; the difference between two ordinary editable slides *is* the animation | **Page authoring (Step 6), then motion post-processing** — §2.1, §3.1 |
-| A static full-bleed page that should stop looking frozen | One slow `path_*` motion on the background group only, `with-previous`, 4–10 s | Post-processing; §4.1, one sidecar entry |
+| A static full-bleed page that should stop looking frozen | Consider slow `path_*` motion on a visually subordinate image or atmospheric layer; §4.1 gives one starting recipe | Post-processing; §4.1 |
| Carousel, counting numerals, parallax depth, click-to-reveal flip card | Four recurring recipes assembled from the mechanisms above | §4.2 — the carousel and odometer both need paired pages |
| Kiosk or unattended playback | `--auto-advance <seconds>`, optionally with `-t none` | Export; §3 |
| Nothing should move | `-t none`, and leave per-element animation at its default `none` | Export; §1 |
@@ -73,19 +73,13 @@ python3 skills/ppt-master/scripts/animation_config.py validate <project>
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
```
-Single-slide sidecar excerpt (repeat the complete slide block for every SVG in `svg_output/`):
+Sparse sidecar excerpt (unlisted slides inherit resolved defaults):
```json
{
"version": 1,
- "defaults": {
- "transition": { "effect": "fade", "duration": 0.4 },
- "animation": { "effect": "auto", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" }
- },
"slides": {
"03_market": {
- "transition": { "effect": "fade", "duration": 0.4 },
- "animation": { "effect": "auto", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" },
"groups": {
"title": { "effect": "entrance_fade", "order": 1 },
"chart": { "effect": "entrance_wipe", "effect_options": { "direction": "left" }, "order": 2, "duration": 0.6 },
@@ -143,14 +137,14 @@ Rules:
- An explicit sidecar group may override the legacy chrome-name heuristic, but it cannot override `data-pptx-layer` or an explicit static role/placeholder marker.
- 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 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.
+**Inheritance**: the sidecar and its `defaults` block are optional. Unlisted
+slides and omitted slide fields inherit `defaults.transition` /
+`defaults.animation`, then CLI/exporter 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.
### 2.1 Deterministic Morph Object Pairing
@@ -163,22 +157,13 @@ The generated names follow Microsoft's
```json
{
"version": 1,
- "defaults": {
- "transition": { "effect": "fade", "duration": 0.4 },
- "animation": { "effect": "none", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" }
- },
"slides": {
- "01_overview": {
- "transition": { "effect": "fade", "duration": 0.4 },
- "animation": { "effect": "none", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" }
- },
"02_detail": {
"transition": {
"effect": "morph",
"effect_options": { "morph_by": "object" },
"duration": 0.8
},
- "animation": { "effect": "none", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" },
"morph": {
"from": "01_overview",
"pairs": {
@@ -374,13 +359,22 @@ motion but preserves narration audio and recorded advance timing.
### 4.1 Slow ambient motion — the page that breathes
-Most object animation exists to reveal content on click. There is a second, quieter use: **one long, slow motion on the background that never waits for a click**, so a static page stops looking frozen. It is the highest-impact-per-effort motion available and it costs one sidecar entry.
+**Reference — not a constraint**: ambient motion can keep a static page from
+feeling frozen when it remains visually subordinate to the message. A common
+starting recipe is `path_left` or `path_right` on a background image, started
+`with-previous` and paced much more slowly than a content reveal. The same
+principle may suit another atmospheric or non-information-bearing layer. Choose
+duration, distance, and moving-object count from the composition and delivery
+context.
-The recipe: a `path_left` (or `path_right`) motion on the **background image group only**, `with-previous` so it starts unprompted, and a duration of **4–10 s** — an order of magnitude longer than the reveal default. Set the travel distance so the image is still fully covering the canvas at both ends; a background that drifts past its own edge exposes the slide beneath it.
+Keep a full-bleed moving image covering the canvas at both endpoints; exposing
+the slide beneath it is a visible failure.
It pairs naturally with a fixed foreground: with image-layout-patterns `#90`, the scrim and its cut contour stay locked while the world moves behind the cuts, which reads as looking through windows rather than as a sliding photo. The same logic applies to `#82` and `#12`.
-**Restraint is the whole technique**: one moving object per page, background only, never body copy or data. Two ambient motions on one page cancel each other out and the page reads as unstable.
+Motion remains subordinate: avoid competing ambient paths or movement that
+reduces the readability of body copy or data. Multiple coordinated layers are
+valid when they express one intentional depth or atmosphere relationship.
### 4.2 Recurring recipes
@@ -389,7 +383,7 @@ mechanisms already defined above — none needs a new capability.
**Carousel** (Morph, §2.1 and §3.1) — hold a fixed row of card frames and rotate the *content* through them: on each page every image advances one position, so the card at centre changes while the frames stay put. Explicitly pair each moving content unit across adjacent pages; the fixed frames stay static and need no pair. Scales to any number of images with one page each.
-**Odometer / counting numerals** (morph or motion path) — build a vertical strip of digits 0–9 and show one through a fixed window formed by background-filled rectangles above and below ([`image-layout-patterns.md`](./image-layout-patterns.md) `#95`). Shift the strip so the target digit lands in the window, then either morph between two pages or run a `path_up` motion on the strip. Give each digit column a 0.1 s stagger so they settle in sequence rather than in lockstep.
+**Odometer / counting numerals** (morph or motion path) — build a vertical strip of digits 0–9 and show one through a fixed window formed by background-filled rectangles above and below ([`image-layout-patterns.md`](./image-layout-patterns.md) `#95`). Shift the strip so the target digit lands in the window, then either morph between two pages or run a `path_up` motion on the strip. A small stagger, such as `0.1s`, can make digit columns settle in sequence; synchronized motion is also valid when it fits the intended rhythm.
**Parallax depth** (morph) — move a background layer a *short* distance and a foreground layer a longer one between two pages. The differing travel is read as depth. Keep both layers' z-order identical on both pages; a layer that changes stacking between pages breaks the tween and the transition jumps.
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 840b00f6..1f1081b6 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -9,7 +9,7 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
| `pptx_structure.mode: structured` | [`executor-structured.md`](./executor-structured.md) |
| Any data chart, chart catalog selection, or text-grid table | [`executor-chart.md`](./executor-chart.md) |
| A page will use a preset pattern fill or evaluate native chart/table replacement | [`native-data-interface.md`](./native-data-interface.md) before deciding eligibility or emitting metadata |
-| Any image or formula resource, including template-bundled images | [`executor-image.md`](./executor-image.md) + [`image-layout-patterns.md`](./image-layout-patterns.md) |
+| Any image/formula; a cited `#<id>` or optional composition recall also triggers the library | [`executor-image.md`](./executor-image.md); conditionally [`image-layout-patterns.md`](./image-layout-patterns.md) |
| Any `Status: Sourced` web image | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` |
| Speaker notes generation after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |
@@ -119,7 +119,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
| Tag | Layout discipline |
|-----|-------------------|
-| `anchor` | Structural page (cover / chapter / TOC / ending). With `template_reuse_scope: mirror`, follow the selected prototype verbatim except visible text values. With `layout`, retain the selected structure system while realizing the page's §IX intent. With `style` or free design, realize §IX directly — for the cover deliver its `Cover impact` and for a closing page its `Closing impact`, never a default centered title + subtitle or generic "Thank you" sign-off. |
+| `anchor` | Structural page (cover / chapter / TOC / ending). `mirror` follows its prototype; `layout` retains its structure system. `style` / free design preserves the §IX cover hook or closing takeaway but may adapt the recommended composition. Avoid an information-empty generic cover/sign-off unless content, user direction, or template requires it. |
| `dense` | Information-heavy. Card grids, multi-column layouts, KPI dashboards, tables, and charts are all permitted. This is the baseline behavior. |
| `breathing` | Low-density impact page. Avoid **multi-card grid layouts** — do not organize content as multiple parallel rounded containers (3-card row, 4-card KPI grid, 2×2 matrix rendered as cards). Use naked text blocks, dividers, whitespace, or full-bleed imagery as the content structure. Single rounded visual elements (hero image corners, callouts, tags, one emphasis block) are fine — the rule is about grid structure, not about the `rx` attribute. Proportions follow information weight (not a preset ratio). Typical forms: hero quote, single large number with one-line interpretation, full-bleed image with floating caption, section transition. |
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.md
index 064fa7db..381526a3 100644
--- a/skills/ppt-master/references/executor-image.md
+++ b/skills/ppt-master/references/executor-image.md
@@ -23,21 +23,23 @@ 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/`.
-**Reference — preferred pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once and resolve every active §VIII/lock pattern id. Adapt its geometry or composition when the page communicates better, while preserving resource role, source, must-use status, crop policy, content, and explicit user/template constraints. Pattern-only changes need no upstream rewrite. Avoid generic left/right repetition.
+**Reference — layout catalog is optional recall**: Load [`image-layout-patterns.md`](./image-layout-patterns.md) only when an active suggestion cites `#<id>` or inspiration is useful; resolve only cited ids. Free-form suggestions need no catalog lookup. Adapt or decline the suggestion when the page communicates better, while preserving resource role/source, must-use, crop/content, and explicit user/template constraints. Expression-only changes need no upstream rewrite.
**Reference — motion-ready image layering, not a constraint**: For adopted §IX or an explicit focus, comparison, evidence, reveal-order, or cross-page requirement, decide during SVG authoring whether the final composition needs separate visible units. Keep ordinary stable framing/background static and wrap each independently revealed or continuing Slide-local unit in a descriptive direct-root `<g id>`; structured atoms/slots retain their boundaries. Existing units or a page transition may suffice. The motion stage owns effects, pairing, order, and timing.
**Hard rule — visible-layer timing**: Any crop, lens, scrim, comparison, evidence, or annotation layer required by an adopted motion plan MUST already exist in the final SVG without violating structural contracts. The later stage may regroup ordinary Slide-local content visual-equivalently, but cannot invent or modify missing visible content. If no legal existing unit can serve a non-binding suggestion, simplify it to available units, a page transition, or `none`; an explicit requirement that cannot be represented follows failure recovery.
-**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.
+**Hard rule — narrow visual-inspection scope**: Start with §VIII `Reference` plus dimensions. If one `Existing`/`Sourced` asset still leaves focal-safe crop, overlay contrast, or a quiet region ambiguous, inspect only that asset/review copy for placement. This cannot reopen selection, change identity/must-use, infer provenance, substitute the asset, or invent focus; never routinely read back `Generated` images. If `adaptive` focus stays uncertain, use `meet`; conflicting binding constraints return upstream.
**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text
**Crop policy**: read the §VIII row and matching lock projection. On every slide that uses a `crop=no-crop` source (or a legacy trailing `| no-crop`), retain one visible complete instance using one of the nine legal anchors with `meet`, never `none`, and no `clip-path`, `mask`, clipping overflow, or nested `<svg>` crop viewport. An auxiliary same-slide detail or lens may crop the same source only while that complete instance remains visible. `crop=adaptive` permits but never requires cropping; choose `meet` or focal-safe `slice` from purpose, ratio, focus, and container. A missing or conflicting `source` / `pattern` / `crop` projection returns upstream instead of being inferred during execution; the accurately projected `pattern` remains a preferred expression that may be adapted without rewriting the lock.
-**Hard rule — same-source addressable crops**: for binding use or pattern
-`#100`, reuse one exact `href` without slice assets. Give every
-independent/Morph object a stable
+**Hard rule — same-source addressable crops, only when adopted**: A layout
+suggestion, including pattern `#100`, never activates this transport. Apply it
+only when the chosen composition uses independent same-source crops or an
+explicit editable/Morph requirement needs them. Once active, reuse one exact
+`href` without slice assets. Give every independent/Morph object a stable
page-unique id and a distinct nested crop wrapper under
[`svg-effects.md`](./svg-effects.md) §6.5. Plain rectangles need no crop marker;
shaped frames put `data-pptx-crop="1"` on the wrapper and a matching
diff --git a/skills/ppt-master/references/executor-web-image.md b/skills/ppt-master/references/executor-web-image.md
index 97ad9d67..38650626 100644
--- a/skills/ppt-master/references/executor-web-image.md
+++ b/skills/ppt-master/references/executor-web-image.md
@@ -13,12 +13,12 @@ Whenever the slide uses an image with `Status: Sourced`, look up the correspondi
| `license_tier` | Action on this slide |
|---|---|
| `no-attribution` | Embed the `<image>` element only. **No credit element needed.** |
-| `attribution-required` | Embed the `<image>` element **plus** a small inline `<text>` credit element per the visual spec in [image-searcher.md §7](./image-searcher.md). |
+| `attribution-required` | Embed the `<image>` element **plus** a visible inline credit that preserves the asset-specific legal content in [image-searcher.md §7](./image-searcher.md). |
| `manual` | Embed the `<image>` element only. **No credit element** — a user-supplied `--from-url` replacement; verifying usage rights / any required credit is the user's responsibility. |
-The credit text is **not** rendered by post-processing or export — it must be present in the SVG you produce. The shape of the credit element (size, position, color, multi-image source line, hero gradient overlay) is specified in [image-searcher.md §7](./image-searcher.md). Do not invent a different style.
+The credit is **not** rendered by post-processing or export — it must be present in the SVG you produce. Preserve that asset's author, source/provider, and CC BY / CC BY-SA license facts. Size, position, color, per-image versus combined treatment, labels, and any contrast scrim/gradient are Executor-owned as long as the credit stays readable and unambiguously bound to the correct image.
-Use `attribution_text` from the manifest entry as the **starting point**, then compress for the small-text constraint: drop URL and filename, but retain that image's author and CC BY / CC BY-SA license so the quality checker can bind the credit to the referenced asset. For CC0/PD images that landed in the `attribution-required` tier only because of upstream metadata quirks (rare), credits are still safe to render.
+Use `attribution_text` from the manifest entry as the **starting point**. You may omit the filename and full URL when the visible source/provider remains clear, but retain that image's author and CC BY / CC BY-SA license so the quality checker can bind the credit to the referenced asset. For CC0/PD images that landed in the `attribution-required` tier only because of upstream metadata quirks (rare), credits are still safe to render.
`svg_quality_checker.py` treats a missing image-specific author + license credit as an **error**; one generic CC token does not cover multiple files. An unreadable/missing manifest or missing per-file provenance is also blocking. Fix the manifest or SVG before post-processing.
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
index c673f8ee..b73cb49c 100644
--- a/skills/ppt-master/references/image-base.md
+++ b/skills/ppt-master/references/image-base.md
@@ -74,9 +74,9 @@ After all rows reach terminal status:
**Hard rule**: acquisition failures MUST NOT halt the pipeline.
-1. Try once
-2. On recoverable failure (network, no candidates, license rejection, rate limit), retry once with broadened parameters
-3. On second failure, set `Status: Needs-Manual`, log the reason in conversation, continue
+1. Run the selected path's initial strategy
+2. On recoverable failure (network, no candidates, license rejection, rate limit), continue through materially different strategies that remain inside that path's confirmed permissions; never loop an already exhausted strategy
+3. When the path-specific query/provider/license-stage or backend/retry strategy is exhausted, set `Status: Needs-Manual`, log the reason in conversation, and continue
4. After the phase completes, summarize all `Needs-Manual` rows for the user — list filenames, where prompts live (`images/image_prompts.md` paste-ready blocks for ai rows; refresh via `image_gen.py --render-md` if stale), and where to place generated files (`project/images/<filename>`). For `slice` rows, list the parent sheet filename and target element names; the user places the sheet, then the agent reruns `slice_images.py`.
`Needs-Manual` is also the entry status for **Offline Manual Mode** (no `IMAGE_BACKEND` configured, no host-native image tool in use). Affected ai rows are marked `Needs-Manual` from the start without a failed attempt — see [`image-generator.md`](./image-generator.md) §7 Offline Manual Mode.
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index af7d7f3f..6762c30f 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -46,7 +46,7 @@ Every AI image uses one deck-wide rendering, the deck's stable color anchors/sem
|---|---|---|
| **Rendering** | Visual style family (vector / sketch-notes / 3d-isometric / corporate-photo / …) | Once per deck — every AI image in the deck shares one rendering |
| **Deck colors** | Core background / primary / accent / secondary-accent / text anchors from `spec_lock.md colors`, interpreted with the Design Spec and per-image context; these are not reconfirmed | Anchored after Stage 2 |
-| **Type** | What a local structural infographic's internal skeleton looks like (infographic / flowchart / framework / matrix / cycle / funnel / pyramid / comparison / timeline / map / scene). A local single-subject or portrait image may omit type and use §4.1 A/B prose; `hero_page` always omits type. | Per image |
+| **Type** | Optional recall for a local structural infographic's internal skeleton (infographic / flowchart / framework / matrix / cycle / funnel / pyramid / comparison / timeline / map / scene). Use it when one template fits; otherwise omit type and write the composition directly in §4.1 E prose. Local single-subject/portrait and `hero_page` images also omit type. | Per image |
> Rendering decides *how the image is drawn* (line quality, texture, depth). Color instructions begin from the deck roles: background / secondary background usually dominate, primary carries main forms, and accents stay scarce. Adjust proportions and derive coherent lighting/material/tint transitions for the image context; do not replace the deck's identity with an unrelated image-only palette.
@@ -122,15 +122,15 @@ For each `Acquire Via: ai` row in `design_spec.md §VIII`:
1. **Determine `page_role`** — Strategist's explicit value wins; a blank or omitted value resolves to `local`. `hero_page` must be explicit.
2. **Determine `text_policy`** — Strategist's value wins when set. **Declared-inference fallback for a blank or omitted value**: pick `none` or `embedded` from the row's `Purpose`, `Reference`, and page intent based on whether in-image text serves the page. Long body / data / lists stay in SVG.
-3. **Determine type or free composition** — an Illustration Sheet omits manifest `type` and follows §4.3's grid composition. For another local structural infographic, match `Purpose` against the `_index.md` table and choose one of the 11 types. For a local single-subject / portrait image, omit type and describe §4.1 A/B inside its actual region. For `hero_page`, omit type and use §4.1 A/B/C/D/E.
+3. **Determine type or free composition** — an Illustration Sheet omits manifest `type` and follows §4.3's grid composition. For another local structural infographic, use one of the 11 types only when the `_index.md` offers a real match; otherwise omit type and author the intended structure directly with §4.1 E. A local single-subject/portrait image omits type and uses §4.1 A/B inside its actual region. A `hero_page` omits type and uses §4.1 A/B/C/D/E.
4. `read_file references/image-type-templates/<type>.md` only when a type was selected (and only if not already read).
5. **Assemble the prompt** by combining:
- The rendering's style paragraph (from Step 2)
- Color-role instructions anchored by the deck HEX values and refined for the image context (from Step 2)
- The selected type's structural layout, or the no-type composition prose (from Step 3)
- The image's specific `Reference` intent (from `design_spec.md §VIII`)
- - The container sizing guidance from the type file (so the model knows it's painting a local block, not a full canvas)
- - The hard rules from §5 below (HEX-not-as-text, simplified figures, text policy)
+ - Container sizing from the selected type file, or the row's Dimensions for no-type prose
+ - The hard rules from §5 below (HEX-not-as-text, rendering-aligned human depiction and likeness authorization, text policy)
The assembled prompt is **one cohesive paragraph**, not a bulleted list of tags. See §4 for the assembly template.
@@ -165,7 +165,7 @@ This produces generic, model-average output. The model is not weighting your tag
### 4.1 No-type composition primitives
-Use these when no structural type applies. A/B can describe either a hero image or a local single-subject / portrait region; scale their framing to the actual container. C/D are hero-page compositions, and E is the explicit escape hatch. Local structural infographics still use the 11 type templates.
+Use these when no structural type applies. A/B can describe either a hero image or a local single-subject/portrait region; scale their framing to the actual container. C/D are hero-page compositions. E authors any custom hero or local composition, including a structural infographic that does not genuinely match one of the 11 type templates.
**Primitive A — single dominant subject (product / object / concept hero)**
@@ -177,7 +177,7 @@ Use for: product reveal, concept introduction, chapter-opener visual, brand stat
> One person, frontal or three-quarter turn, head + upper body. Start with the face as the clear focal point, centered or rule-of-thirds offset, with eyes near the upper-third horizontal line. Background neutral, minimal, or softly blurred. Keep comfortable headroom and no competing foreground objects; adjust framing to the container rather than enforcing fixed padding.
-Use for: founder profile, speaker bio, testimonial page, or executive intro, including a local bio region. Pair with `rendering: corporate-photo` for photographic realism; otherwise the §5.2 simplified-figures rule applies.
+Use for: founder profile, speaker bio, testimonial page, or executive intro, including a local bio region. Let the chosen rendering and Reference determine photographic, editorial, painterly, graphic, or other figure treatment; see §5.2.
**Primitive C — typographic hero (the text *is* the image)**
@@ -189,7 +189,7 @@ Use with `text_policy: embedded`. Must obey the §5.3 rule — text that is part
> Atmospheric field with no dominant subject — gradients, subtle patterns, or restrained color blocks. A small geometric anchor may sit in a corner or along an edge. Arrange visual activity around the SVG overlay region named by the page plan so that region stays calm enough for its title or text; its position and extent follow the composition rather than a fixed percentage.
-**Applies to `page_role: hero_page` only.** The "calm center for SVG overlay" contract defines this primitive. A `local` image uses §3 type templates or §4.1 A/B instead; when §VIII / §IX explicitly plans native overlays inside that region, its prompt may reserve only the named focal/quiet area without turning the whole asset into Primitive D.
+**Applies to `page_role: hero_page` only.** The "calm center for SVG overlay" contract defines this primitive. A `local` image uses §3 type templates or §4.1 A/B/E instead; when §VIII / §IX explicitly plans native overlays inside that region, its prompt may reserve only the named focal/quiet area without turning the whole asset into Primitive D.
Use for: cover background, chapter divider background, breathing-page background, any page where the SVG layer carries the words and the image only sets tone.
@@ -197,13 +197,13 @@ Use for: cover background, chapter divider background, breathing-page background
When none of A/B/C/D describe the page's intended layout (triptych, asymmetric multi-focal, narrative diorama, etc.), write the composition description directly into the prompt's composition sentence — same paragraph slot A/B/C/D occupy, but in your own words. No new field; the freedom is in the prose.
-**Hard rule — custom composition prose**:
+**Default — concise custom composition prose (may override for subject accuracy)**:
| Rule | Value |
|---|---|
| Length | One paragraph, 2-5 sentences, replacing A/B/C/D's opening paragraph |
-| Required content | subject count, layout structure, where breathing room sits, where SVG overlay can claim canvas |
-| Forbidden | Naming a competing primitive ("like A but two subjects") |
+| Content | State enough subject count and layout structure to make the composition executable; include breathing room or an SVG-overlay region only when the page composition actually needs it |
+| Clarity | Describe the actual geometry; a primitive name alone is not a substitute |
Example opening for a triptych hero:
@@ -246,9 +246,9 @@ Example opening for a triptych hero:
### 4.3 Illustration sheets — one generation, many spot elements
-When a deck wants several small **spot illustrations** scattered as decorative accessories across pages, do **not** generate them one image per slot. Generate one sheet and slice it. One call buys identical rendering, deck-color treatment, and line quality—the same consistency protected by `deck_rendering` + `color_scheme`.
+An illustration sheet can produce several small **spot illustrations** in one generation and preserve closely matched rendering, deck-color treatment, and line quality before slicing.
-**When to use**: the §VIII image resource plan needs ≥3 small spot illustrations from the same family across the deck. For a single hero/local image, stay with the normal one-row-per-image flow (§4.1). Use sheets only where decorative illustration genuinely lifts the page; an unused element costs nothing, but a deck papered in decoration reads cheap.
+**Default — one sheet for a compatible spot family (may override when separate generation serves the assets better)**: Prefer a sheet when several elements share similar proportions, detail, quality, and semantic precision. Generate elements separately when those needs differ materially; quantity alone neither requires nor forbids a sheet. A single hero/local image stays with the normal one-row-per-image flow (§4.1).
**Hard rule**: a spot sheet is a generation source, not a slide asset. The sheet row is never listed in `spec_lock.md images` and never referenced from SVG. Only the sliced element rows are placed.
@@ -279,11 +279,11 @@ 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-recommended decorative-cutout Layout pattern rather than a boxed-container recommendation; Executor owns the actual placement — 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 carries a Strategist layout recommendation; Executor may realize it as a direct cutout or inside an appropriate container while preserving the resource and crop/content constraints.
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` validates, preserves, and displays these metadata fields; it does not run the separate slicing command.
-**Slice** with [`slice_images.py`](../scripts/slice_images.py) — cells are cut row-major into individual files in `images/`. With `--alpha` they are **transparent cutout stickers** (image-layout-patterns `#63`), not rectangular content images. Recommended flags: `--names` (semantic per-cell filenames matching the element rows; the count **must** equal `rows*cols`), `--trim` (tight-crop each cell so imprecise placement inside a cell doesn't leave lopsided margins), `--alpha` (knock the flat background out to transparency so an element drops onto any slide color):
+**Slice** with [`slice_images.py`](../scripts/slice_images.py) — cells are cut row-major into individual files in `images/`. With `--alpha` they become transparent elements suitable for direct cutout placement or for composition inside a card, evidence frame, label, or other container. Recommended flags: `--names` (semantic per-cell filenames matching the element rows; the count **must** equal `rows*cols`), `--trim` (tight-crop each cell so imprecise placement inside a cell doesn't leave lopsided margins), `--alpha` (knock the flat background out to transparency so an element can sit on any slide color or container):
```bash
python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \
@@ -293,10 +293,10 @@ python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \
**Three constraints that decide whether it looks good**:
1. **Flat background, matched to the slide.** `image_gen.py` has no transparent-background mode, so the cut element carries whatever was behind it. A flat sheet background (= deck background HEX) is what `--alpha` keys out and what makes non-keyed pieces blend.
-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.
+2. **Clean grid, or it cuts ugly.** State the exact row/column structure and cell shape so the model does not invent a square matrix; `--trim` absorbs smaller placement variance. Do not generate several sheets or read them back merely to choose a favorite; re-roll only when user/live-preview feedback exposes an unusable slice.
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 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)).
+**Reference — sliced-asset placement is not a constraint**: A transparent slice may remain an unboxed cutout or enter a card, evidence frame, label, panel, or other suitable container. Strategist's layout text is an expression recommendation; Executor owns the actual geometry and treatment while preserving the resource role and crop/content constraints.
**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.
@@ -314,13 +314,13 @@ Image generation models occasionally paint color names and HEX values as **visib
> Color values (HEX codes like #1E3A5F) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
-### 5.2 Simplified human figures, no realistic faces
+### 5.2 Human depiction follows the selected rendering
When the image contains people:
-> Human figures appear as simplified stylized silhouettes or symbolic representations — no photorealistic faces, no detailed anatomy, no celebrity likeness. Express role/emotion through posture, attire, and simple gestures.
+> Match facial detail, anatomy, texture, and realism to the selected rendering and the row's Reference. A silhouette, detailed illustration, painterly figure, editorial photograph, or another treatment is valid when it belongs to that rendering.
-Exception: when the chosen rendering is `corporate-photo`, photorealism is intentional — replace the above with: `Diverse, professionally attired subjects. Editorial photography style, natural composition`.
+**Hard rule — likeness authorization**: Do not request an identifiable real-person or celebrity likeness unless the Reference explicitly names a user-authorized subject/source. Generic or fictional people remain free to follow the selected rendering.
### 5.3 Text policy — two-layer ownership
@@ -449,7 +449,7 @@ Write `project/images/image_prompts.json` with this shape:
| `deck_rendering` | yes | Step 2 lock | Single rendering name shared by all items in this deck |
| `color_scheme` | yes | `spec_lock.md colors` | Core deck color anchors shared by every item; prompts may add contextual tonal behavior, but no separate image palette |
| `items[].filename` | yes | `§VIII` resource list | Output filename with extension |
-| `items[].type` | conditional | Step 3 per-image | One of 11 internal-composition types for a local structural infographic. Omit it for `hero_page`, an Illustration Sheet, and a local single-subject / portrait composition authored with §4.1 A/B prose. |
+| `items[].type` | no | Step 3 per-image | Optional one-of-11 internal-composition type for a local structural infographic when a template genuinely fits. Omit it for custom §4.1 E prose, `hero_page`, an Illustration Sheet, and local single-subject/portrait prose. |
| `items[].page_role` | yes | Step 3 per-image | `local` (default — region block on SVG page) or `hero_page` (image is page's main voice; SVG overlay minimal or empty) |
| `items[].text_policy` | yes | Step 3 per-image | `none` (image carries no text — explicit visual rule) or `embedded` (image contains stable artistic lettering, hand-lettered keywords, or visual identifiers like axis labels / subplot letters / unit symbols). AI judges per image; no global default bias — see §5.3. |
| `items[].aspect_ratio` | yes | Container sizing | Passed to `image_gen.py --aspect_ratio` |
@@ -461,12 +461,12 @@ Write `project/images/image_prompts.json` with this shape:
| `items[].slice_names` | paired optional | §4.3 sheet geometry | Illustration sheet only; comma-separated safe PNG basenames to pass to `slice_images.py --names`; requires exactly `rows*cols` unique outputs |
| `items[].status` | yes | CLI manages | `Pending` initially; CLI updates to `Generated` / `Failed` / `Needs-Manual` |
-> **Back-compat for legacy `type` values**: existing manifests using `background` / `hero` / `portrait` / `typography` (the four removed pseudo-types) remain readable. Read them as: `background` → `page_role: hero_page` + no type; `hero` → `page_role: hero_page` + no type (use §4.1 Primitive A in prompt); `portrait` → `page_role: local` + no type (use §4.1 Primitive B); `typography` → `page_role: hero_page` + `text_policy: embedded` + no type (use §4.1 Primitive C). New manifests omit `type` for hero pages and local single-subject / portrait prose.
+> **Back-compat for legacy `type` values**: existing manifests using `background` / `hero` / `portrait` / `typography` (the four removed pseudo-types) remain readable. Read them as: `background` → `page_role: hero_page` + no type; `hero` → `page_role: hero_page` + no type (use §4.1 Primitive A in prompt); `portrait` → `page_role: local` + no type (use §4.1 Primitive B); `typography` → `page_role: hero_page` + `text_policy: embedded` + no type (use §4.1 Primitive C). New manifests also omit `type` for custom §4.1 E prose, hero pages, and local single-subject/portrait prose.
>
> **Existing manifest compatibility**:
>
> - **Fixed compatibility defaults**: a missing `page_role` resolves to `local`; a missing `text_policy` resolves to `none`. Emit one aggregate legacy-compatibility warning per manifest.
-> - **Declared replay procedure**: an existing manifest may lack `deck_rendering`, or an existing local item may lack `type`, because `items[].prompt` is already assembled. Leave that metadata absent, execute the existing prompt verbatim, and do not reconstruct either value. New manifests follow the field table; hero pages and local single-subject / portrait prose omit `type` intentionally.
+> - **Declared replay procedure**: an existing manifest may lack `deck_rendering`, or an existing local item may lack `type`, because `items[].prompt` is already assembled. Leave that metadata absent, execute the existing prompt verbatim, and do not reconstruct either value. New manifests follow the field table; custom §4.1 E prose, hero pages, and local single-subject/portrait prose omit `type` intentionally.
> - A legacy non-empty `deck_style_anchor` string or object remains readable for replay and sidecar display but never overrides a current `deck_rendering`.
> - A legacy `deck_palette` field may remain but cannot override `color_scheme`. Read legacy `page_role: full_page` as `hero_page`.
@@ -645,7 +645,7 @@ Diagnose the failure category, adjust the **one specific dimension** responsible
| Garbled letters in supposedly text-free image | `text_policy: none` rule too weak | Strengthen with explicit list: "no letters, no numbers, no words, no signs, no labels, no captions, no watermarks" |
| SVG text overlay clashes with busy image area | Page design needs negative space the prompt didn't request | Add a composition cue like "leave the {center / left third / lower band} relatively calm for text overlay" — only when the page actually overlays text on top of the image |
| Subject vague | Reference field too abstract | Rewrite reference with concrete nouns (verbs + objects) |
-| Faces too realistic / uncanny | §5.2 rule omitted, or rendering is photo-incompatible | Either append §5.2, or switch rendering to a non-photo family |
+| Human depiction conflicts with the selected style or intent | §5.2 rendering/Reference cues were diluted | Restate the selected rendering's facial detail, anatomy, texture, and realism cues without changing the locked rendering |
**Variant workflow**:
diff --git a/skills/ppt-master/references/image-layout-patterns.md b/skills/ppt-master/references/image-layout-patterns.md
index 511bf7e4..ea72dd62 100644
--- a/skills/ppt-master/references/image-layout-patterns.md
+++ b/skills/ppt-master/references/image-layout-patterns.md
@@ -1,10 +1,10 @@
-# Image-Text Layout Patterns
+# Image-Text Layout Pattern Library
-A vocabulary registry of ways images can be placed on a slide. The point of this file is to **expand the mental list of options** so that when you reach for an image layout, you do not default to the same three patterns (left/right, top/bottom, full-bleed cover). Start at **High-Yield Patterns** below: it routes the common page situations to the constructions that most visibly raise a deck's quality, at no asset cost.
+An optional vocabulary library for ways images can be placed on a slide. Open it when a page would benefit from more composition ideas; ordinary natural-language layout suggestions remain valid without consulting or citing the library. When using it, start at **High-Yield Patterns** below.
-Every entry has a name plus a short technical hint. Common techniques get a single line. Less obvious or easily forgotten techniques get a short paragraph — not a full tutorial, but enough that a model unfamiliar with the project can implement it without guessing. This is a registry, not a teaching document; no use-case prescriptions, no decision tables.
+Every entry has a name plus a short technical hint. Common techniques get a single line. Less obvious or easily forgotten techniques get a short paragraph — not a full tutorial, but enough that a model unfamiliar with the project can implement it without guessing. This is an inspiration library, not a legality boundary or teaching document; it sets no usage, id, family, or coverage quota.
-> **Numbers are stable identifiers, not sequence.** The file is split into **Part 1 — Primary Structures** (#1–#19, #38–#56, #73–#81, #88, #92–#94) and **Part 2 — Modifier Layers** (#20–#37, #57–#72, #82–#87, #89–#91, #95–#100). Numbers jump within each Part because Primary structures were grouped first; existing references to `#38`, `#48`, etc. anywhere in the project still resolve correctly. **High-Yield Patterns** below is a router over those same numbers, not a third part — read it first, then jump to the entry it names.
+> **Numbers are stable optional identifiers, not sequence.** The file is split into **Part 1 — Primary Structures** (#1–#19, #38–#56, #73–#81, #88, #92–#94) and **Part 2 — Modifier Layers** (#20–#37, #57–#72, #82–#87, #89–#91, #95–#100). Numbers jump within each Part because Primary structures were grouped first; existing references to `#38`, `#48`, etc. anywhere in the project still resolve correctly. **High-Yield Patterns** is a router over those same numbers; use it when entering by page situation.
---
@@ -20,11 +20,11 @@ Anything that must remain editable, numerically or semantically exact, or styled
---
-## High-Yield Patterns — Open Here
+## High-Yield Patterns — Optional Starting Points
-The patterns below are what separate a deck that looks designed from a deck that looks assembled. Nearly all of them are **one `<image>` plus geometry** — no extra asset, no generation cost, no second render — and they are the SVG equivalents of what PowerPoint users reach for under Merge Shapes. They sit late in the file only because the numbering is historical; they are the first place to look, not the last.
+The patterns below are efficient ways to expand a page beyond familiar splits. Nearly all of them are **one `<image>` plus geometry** — no extra asset, no generation cost, no second render — and they are the SVG equivalents of what PowerPoint users reach for under Merge Shapes.
-**Default — resolve each page against this table before falling back to the plain structures in Part 1 (may override when the content genuinely wants a plain split, an equal grid, or bare whitespace):**
+**Reference — not a constraint**: use this router when it adds a useful composition option. A plain split, equal grid, bare whitespace, or an unlisted free-form construction remains valid when it serves the content.
| Page situation | Reach for | Produces |
|---|---|---|
@@ -42,13 +42,13 @@ The patterns below are what separate a deck that looks designed from a deck that
| A subject should escape its container | `#85` subject breaking out + `#96` | Depth with no shadow at all |
| One place should be recognized across consecutive pages | `#87` one image panned across pages | The deck reads as one continuous scene; `-t morph` uses heuristic matching, while explicit `morph.pairs` makes the camera pan deterministic |
-**Mandatory**: Pair a modifier-only router result with a content-appropriate Part 1 Primary as the page bones before §VIII. The pairing makes the recommendation complete; it does not lock Executor geometry or create a usage quota.
+**Reference — not a constraint**: when citing a modifier-only result, also name the content-appropriate Primary that supplies the page bones. Free-form suggestions may describe the complete relationship without catalog ids.
**Hard rule — registration is what makes this family work**: in `#82`, `#85`, `#87`, `#89`, `#96`, `#97`, and `#100`, the image stays anchored to the *union* of its containers, or the copies share one source coordinate system. A few pixels of drift reads as a printing error. `#84` alone breaks registration on purpose.
**Prepared-asset gate**: select `#96` only when a registered cutout PNG already exists, `#97` only when its blurred crop exists, and `#99` only when its desaturated copy exists. If not, keep the original asset and fall back to a native-shape treatment such as `#30` / `#29`; do not invent an image-processing step during execution.
-**Skip-detection signal** — if every page's `Layout pattern` resolves to a bare `#2` / `#3` / `#5` / `#6` with no Modifier id, this table was not consulted. Re-open it before finalizing `design_spec.md §VIII`.
+**Reference — not a constraint**: repeated plain splits may be a reason to consult this library, but are not evidence of failure. Neither §VIII nor the final deck must cite an id or cover a pattern family.
Each entry above is specified in full at its own number below; the table routes, it does not restate.
@@ -262,7 +262,7 @@ names the intended appearance only. Realize it with crop/clip geometry,
scrim/overlay shapes, a real cutout path, or a baked-alpha asset; never emit
`<mask>` or `mask="url(...)"`.
-> **Crop displacement (HARD rule for text over images).** `preserveAspectRatio="xMidYMid slice"` center-crops whatever the source aspect ratio does not cover — when source and display aspects differ, the subject can land under the text column even if the prompt asked for it on the "focal side". Before layering text on a slice-cropped image: estimate the crop from the aspect-ratio difference, and keep the **entire text column on the scrim's opaque plateau** — text must never start inside a gradient's transition zone. When the subject position is unverified, fall back to an opaque treatment (`#30` at high opacity, or a solid panel) instead of a two-stop scrim (`#29`).
+> **Default — focal-safe text contrast (may override when the image and treatment demonstrably remain legible).** `preserveAspectRatio="xMidYMid slice"` center-crops whatever the source aspect ratio does not cover, so estimate the crop before placing text. Keep copy clear of the focal subject and maintain readable contrast across its full area. A gradient transition is valid when those conditions hold; use an opaque plateau or solid panel only when the image and softer treatment cannot guarantee them. When subject position is unresolved, prefer the opaque treatment rather than guessing.
27. **Linear gradient scrim for text legibility** — `<linearGradient>` in `<defs>` (set `x1/y1/x2/y2` for direction) + overlay `<rect fill="url(#grad)">`. Most common is top-to-bottom darkening on full-bleed cover images.
@@ -419,7 +419,7 @@ Combine freely. The "AI-default" failure mode is the opposite: defaulting to bar
| Benefits with one dominant proof image | `#80` |
| Light promotional page without photos | `#81` |
-**Reach for the boolean-geometry family (#82–#100) before adding another photo to the page.** Routing, the registration invariant, and the skip-detection signal are in **High-Yield Patterns** at the top of this file.
+**Reference — not a constraint**: before adding another photo, consider whether one prepared image plus #82–#100 can express the idea more clearly. Registration and prepared-asset boundaries remain mandatory when the chosen technique depends on them.
**Cross-page through-line (recurring motif).** The patterns above are per-page, but a deck reads as *designed* when one illustration motif family recurs across pages—a cover anchor, section dividers repeating the motif (`#75`), and small `#63` spots threaded through the body. Keep one family (shared rendering / locked deck colors / subject world), vary scale and placement, and never turn recurrence into a quota.
diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.md
index 7750d180..46366fe7 100644
--- a/skills/ppt-master/references/image-layout-spec.md
+++ b/skills/ppt-master/references/image-layout-spec.md
@@ -188,10 +188,10 @@ This spec only defines layout calculation. Write computed fields into the Image
| Field | Meaning |
|-------|---------|
| `Ratio` | Original image width / height |
-| `Layout pattern` | Strategist-recommended catalog pattern; preferred composition, Executor-owned realization |
+| `Layout pattern` | Non-empty Strategist layout suggestion in free-form prose, optionally citing catalog ids; Executor-owned realization |
| `Crop Policy` | `no-crop` requires one complete instance; `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>`; source/crop exactly project §VIII, while pattern preserves its ordered catalog ids (or normalized custom prose) as a recommendation, not a geometry/realization lock |
+| `spec_lock.md images` value | `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>`; source/crop exactly project §VIII, while pattern preserves the normalized free-form suggestion and any optional catalog ids as a recommendation, not a geometry/realization lock |
For SVG `<image>` syntax, path rules, `preserveAspectRatio`, external refs, and Base64 embedding: see [`svg-image-embedding.md`](svg-image-embedding.md).
diff --git a/skills/ppt-master/references/image-renderings/corporate-photo.md b/skills/ppt-master/references/image-renderings/corporate-photo.md
index a3652f0e..cab1917b 100644
--- a/skills/ppt-master/references/image-renderings/corporate-photo.md
+++ b/skills/ppt-master/references/image-renderings/corporate-photo.md
@@ -1,6 +1,6 @@
# Rendering: corporate-photo
-Editorial photography style — real subjects, natural composition, professional grading. The only rendering where photorealism is intentional. Used for team photos, lifestyle shots, product photography, real-world scenarios.
+Editorial photography style — real subjects, natural composition, professional grading. Used for team photos, lifestyle shots, product photography, and real-world scenarios.
## 1. Style paragraph (paste-ready, 100 words)
@@ -20,13 +20,13 @@ Editorial photography style — real subjects, natural composition, professional
---
-## 3. Exception to global hard rule §5.2
+## 3. Human treatment
-corporate-photo **overrides** the global "simplified silhouettes / no realistic faces" rule (image-generator.md §5.2). For this rendering, append instead:
+Apply [`image-generator.md`](../image-generator.md) §5.2 through this rendering's photographic grammar:
> Diverse, professionally attired subjects rendered photorealistically. Editorial photography composition, natural light or soft studio lighting. Subjects appear authentic and contemporary — no posed stock-photo stiffness, no exaggerated expressions, no fashion-shoot artificiality.
-All other renderings keep the simplified-figure rule.
+This rendering does not create a photorealism whitelist; other renderings choose their own anatomy, facial detail, texture, and realism under the same global rule.
## 4. Using the deck's HEX values
@@ -43,4 +43,4 @@ corporate-photo's relationship to HEX is **color grading**, not color fills:
**Snippet A — team workplace photo, text_policy: none**
-> Editorial photography of a small modern team collaborating around a laptop in a contemporary office. Three to four diverse, professionally attired adults — varied ethnicities, varied ages — engaged in genuine conversation, no posed stock-photo stiffness. Natural window light from the side, soft shadows. Color grading is cool-corporate — image is subtly graded toward deep blue tones echoing the deck's primary `#1E3A5F`, with the background carrying soft light gray `#F8F9FA` walls and a single accent of warm wood or amber from a desk lamp echoing the accent `#D4AF37`. Shallow depth of field — subjects sharp, background gently blurred. Composed as a 1200×600 hero band with 8% inner padding. Diverse, professionally attired subjects rendered photorealistically. Editorial photography composition. Authentic, not stock-photo artificial. Color values are rendering guidance — HEX codes themselves do not appear in the image as text.
\ No newline at end of file
+> Editorial photography of a small modern team collaborating around a laptop in a contemporary office. Three to four diverse, professionally attired adults — varied ethnicities, varied ages — engaged in genuine conversation, no posed stock-photo stiffness. Natural window light from the side, soft shadows. Color grading is cool-corporate — image is subtly graded toward deep blue tones echoing the deck's primary `#1E3A5F`, with the background carrying soft light gray `#F8F9FA` walls and a single accent of warm wood or amber from a desk lamp echoing the accent `#D4AF37`. Shallow depth of field — subjects sharp, background gently blurred. Composed as a 1200×600 hero band with 8% inner padding. Diverse, professionally attired subjects rendered photorealistically. Editorial photography composition. Authentic, not stock-photo artificial. Color values are rendering guidance — HEX codes themselves do not appear in the image as text.
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 728a13de..ee439265 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -59,7 +59,7 @@ Default chain (when `--provider` is unset):
Keyed providers without an API key are silently skipped — not an error.
-**Validation**: For polished visual decks, configure at least one keyed provider before using `Acquire Via: web`.
+**Default — keyed providers for broader stock coverage (may override when zero-config sources fit)**: Configure Pexels or Pixabay when their stock-photo coverage serves the brief. Their absence is not a validation failure; Openverse and Wikimedia remain valid zero-config acquisition paths.
---
@@ -70,11 +70,11 @@ Keep two layers distinct:
| Layer | Owner and grammar |
|---|---|
| Design Spec §VIII `Reference` | Strategist's complete visual intent: exact subject, desired view/mood, focal or quiet region, and crop-safety constraints. Positive quality cues are valid here. |
-| `image_queries.json.items[].query` / positional query | Image_Searcher's provider keyword string: 1–4 concrete entity or identity words only; omit mood, quality, composition, HEX, and negative wording. |
+| `image_queries.json.items[].query` / positional query | Image_Searcher's concrete entity/identity keyword string. Start with the shortest phrase that preserves identity; keep exact multi-word names and necessary disambiguators even when they exceed four words. Omit mood, quality, composition, HEX, and negative wording. |
-Web APIs match metadata, not semantic intent. For ad-hoc long positional input, `simplify_query` strips noise and caps the fallback at four words, but a pipeline manifest should already contain the short provider query. For Chinese landmarks, use the precise Chinese name with Wikimedia; for stock providers, use short English identity terms.
+Web APIs match metadata, not semantic intent. Providers try the original query first, then progressively simplified four/three/two/one-word variants. A pipeline manifest should therefore use a concise query without pre-truncating exact names. For Chinese landmarks, use the precise Chinese name with Wikimedia; for stock providers, use compact English identity terms when they retain the subject.
-Image_Searcher consumes the locked Reference and never rewrites `design_spec.md` or `spec_lock.md`. A candidate either satisfies that existing subject/focal/crop intent, or the role re-queries once and then marks `Needs-Manual`.
+Image_Searcher consumes the locked Reference and never rewrites `design_spec.md` or `spec_lock.md`. A candidate either satisfies that existing subject/focal/crop intent, or the role tries materially different query/provider/permitted-license strategies until no untried strategy remains, then marks `Needs-Manual`. Never loosen `required_terms`, the license policy, or the locked intent to manufacture a match.
When the subject is an exact entity (landmark / person / company / product / venue), write `required_terms` at the same time you write the row's `query`. Use one required group per identity anchor and `|` for aliases / translations, e.g. `["Chongqing|重庆", "Jiefangbei|解放碑|Liberation Monument"]`. This keeps the query short for provider search while preventing metadata-ranked wrong entities from being accepted.
@@ -183,14 +183,14 @@ Never treat a generic `required_terms` pass as acceptance. For example, matching
**Replacement ladder when a best match is not right** (any reviewer):
-1. refine the query and re-run that row once;
+1. refine the query and re-run that row while each revision tests a materially different identity phrase or disambiguator; do not repeat a semantically exhausted query;
2. **manual URL replace (universal, model-agnostic)** — the user finds a better image anywhere and gives its URL; download and swap it in:
```bash
python3 scripts/image_search.py --from-url <image-url> --filename <name>.jpg -o <project_path>/images
```
Recorded with `license_tier: manual` — verifying usage rights is the user's call. Human replacement is a legitimate outcome, not a failure. It updates the image and `image_sources.json` but does **not** rewrite `image_queries.json`, so a row fixed this way may still read `Needs-Manual` in the batch manifest — harmless: the file is present, so export proceeds ([`executor-web-image.md`](./executor-web-image.md) §1);
3. (opt-in) `--save-candidates` to pull auto-alternatives with their own `source_page_url`s, then `--promote` the best (below);
-4. if nothing fits, mark the row `Needs-Manual`.
+4. when the query variants, configured provider chain, and permitted license stages are exhausted and no user-confirmed manual URL is available, mark the row `Needs-Manual`.
Web search is far cheaper than AI generation, so this review pass is well worth it.
@@ -265,40 +265,23 @@ Every successful download appends or replaces one entry keyed on `filename`:
---
-## 7. On-Slide Attribution — Visual Specification
+## 7. On-Slide Attribution Contract
-Applied by Executor when an image's `license_tier == "attribution-required"`. Three layouts depending on the page.
+Applied by Executor when an image's `license_tier == "attribution-required"`.
-### 7.1 Single-image page
+**Hard rule — legal content and binding**: Every slide that uses the asset carries a visible, readable credit bound unambiguously to that asset. Preserve its author, source/provider, and CC BY / CC BY-SA license facts from `attribution_text`; do not invent, merge away, or drop identity.
-- **Position**: bottom-right of the image's container, hugging the image edge (within ~8 px)
-- **Font size**: 6–8pt equivalent (≈ 0.7–1 % of canvas short edge)
-- **Color**: `fill="#999999"` on light/photo backgrounds; `fill="#FFFFFF" fill-opacity="0.6"` on dark/photo
-- **Content**: `© {author} / {provider_short} / {license_short}`
- - `provider_short`: `Openverse` / `Wikimedia` / `Pexels` / `Pixabay`
- - `license_short`: `CC BY 4.0` / `CC BY-SA 4.0` / `Public Domain`
- - Drop empty fields (CC0 with no author → `via Openverse`)
+**Reference — visual treatment is not a constraint**: Position, size, color, line structure, per-image versus combined credits, labels, and contrast treatment belong to the page composition. Use any treatment that stays readable and preserves the asset-to-credit binding; a scrim or gradient is optional, not required.
-**Forbidden — fields that break the visual line**: full URLs, `attribution_text` verbatim, "License:" prefix.
+**Reference — attribution treatments, not constraints**:
-### 7.2 Multi-image page (≥ 2 attribution-required)
-
-Combine into one source line at the page bottom rather than scattering credits:
-
-```
-Sources: a, b via Wikimedia (CC BY); c via Openverse (CC BY-SA)
-```
-
-Use single-letter labels (a/b/c) only when needed for disambiguation.
-
-### 7.3 Hero / full-bleed image
-
-- Bottom 1.5 cm gradient overlay: `stop-color="#000000" stop-opacity="0"` → `stop-color="#000000" stop-opacity="0.5"`
-- 7pt text with `fill="#FFFFFF" fill-opacity="0.6"` inside the overlay band, right-aligned ~24 px from edge
-
-### 7.4 Source for the credit text
+| Page situation | Possible treatment |
+|---|---|
+| One credited image | Place a compact credit near the image edge or in a page footnote area |
+| Several credited images | Use per-image credits or one combined source line with labels when needed for unambiguous mapping |
+| Hero / full-bleed image | Place the credit in an available quiet region; add a scrim or gradient only when contrast otherwise fails |
-Use `attribution_text` from the manifest as the **starting point**. Compress for the small-text constraint:
+Use `attribution_text` from the manifest as the **starting point**. Compress when the chosen page treatment needs a shorter line, without dropping the required facts:
| Manifest | Slide credit |
|---|---|
@@ -313,7 +296,7 @@ Extends [`image-base.md`](./image-base.md) §6.
| Situation | Behavior |
|---|---|
-| No candidates from any provider in either stage | Mark row `Needs-Manual`. Suggest: shorter query, drop `--strict-no-attribution`, or set keyed provider's API key. |
+| No candidates from any provider in either stage | Mark row `Needs-Manual`. Suggest a more precise query or another configured provider; rerun without `--strict-no-attribution` only when the confirmed page may carry visible credit. |
| Single candidate fails to download (HTTP 403/404) | Dispatcher auto-falls through to the next ranked candidate. No user action. |
| All candidates from one provider fail | Dispatcher moves to the next provider in the chain. |
| Provider/network failure remains after dispatch | Mark row `Failed`; a later batch run retries it. |
@@ -327,7 +310,7 @@ CLI exit: `0` when all attempted rows resolve; `1` while any row remains `Failed
Reference field is **intent description**, not a query. See [`image-base.md`](./image-base.md) §8 for the rule.
-Keep it intact as the acceptance contract. Derive a separate 1–4 word provider query; do not pass the Reference verbatim or rewrite it after search.
+Keep it intact as the acceptance contract. Derive a separate concise provider query that preserves exact names and necessary disambiguation; do not pass the Reference verbatim or rewrite it after search.
---
diff --git a/skills/ppt-master/references/image-type-templates/_index.md b/skills/ppt-master/references/image-type-templates/_index.md
index 9b160500..f3656233 100644
--- a/skills/ppt-master/references/image-type-templates/_index.md
+++ b/skills/ppt-master/references/image-type-templates/_index.md
@@ -1,6 +1,6 @@
# Type Templates — Index
-A **type** describes the **internal geometric composition skeleton** of a local infographic image block — what the layout looks like *inside the rectangle the model paints*. Type is decided **per image**, not per deck (one deck typically uses 2-4 different types).
+A **type** optionally describes the **internal geometric composition skeleton** of a local infographic image block — what the layout looks like *inside the rectangle the model paints*. Type is decided **per image**, not per deck.
## What Type *is* and *is not*
@@ -12,7 +12,7 @@ A **type** describes the **internal geometric composition skeleton** of a local
- *not* "what subject occupies the image" — single subject, single person, big number, no subject: these are all expressible through §4.1 no-type primitives or natural-language prompt description, not through types
- *not* a high-level asset category — the row's `Purpose` + `Reference` columns in `design_spec.md §VIII` already carry that, no separate vocabulary needed
-**When to skip type entirely** — every `hero_page` omits type and uses the prose primitives in [`image-generator.md`](../image-generator.md) §4.1. A local single-subject or single-person region also omits type and uses Primitive A/B sized to that region. The 11 types below are for local structural infographic blocks only.
+**Reference — when to skip type**: Every `hero_page` omits type and uses the prose primitives in [`image-generator.md`](../image-generator.md) §4.1. A local single-subject or single-person region also omits type and uses Primitive A/B sized to that region. A local structural infographic with no genuine catalog match omits type and uses custom Primitive E prose. The 11 types below are recall tools, not a closed set.
---
@@ -38,7 +38,7 @@ Each type has its own file with: composition skeleton (LAYOUT / ELEMENTS / NEGAT
## 2. Auto-selection — per-image `Purpose` → type
-For each row in `design_spec.md §VIII Image Resource List` where `page_role: local`, match `Purpose` against this table.
+**Reference — not a constraint**: For a `page_role: local` row in `design_spec.md §VIII Image Resource List`, use this table when `Purpose` genuinely matches. Otherwise omit `type` and write the intended composition directly.
| `Purpose` keyword | Type |
|---|---|
diff --git a/skills/ppt-master/references/image-type-templates/scene.md b/skills/ppt-master/references/image-type-templates/scene.md
index 7107a23c..382b8bc5 100644
--- a/skills/ppt-master/references/image-type-templates/scene.md
+++ b/skills/ppt-master/references/image-type-templates/scene.md
@@ -21,7 +21,7 @@ Atmospheric environment with narrative — a moment, a place, a situation render
```
| LAYOUT | Three-layer composition: foreground (subject + immediate context), middle ground (supporting environment), background (atmospheric depth). The viewer reads the scene like a small story |
-| ELEMENTS | One or more figures (simplified silhouettes unless `corporate-photo`) in an environment. Environmental elements (sun, lamp, tree, desk) support the narrative |
+| ELEMENTS | One or more figures treated according to the selected rendering and Reference, inside an environment. Environmental elements (sun, lamp, tree, desk) support the narrative |
| NEGATIVE SPACE | Atmospheric perspective creates breathing room — background paler than foreground |
| ATMOSPHERE | Lighting direction, color temperature, and mood are deliberate (golden-hour, evening light, morning haze, etc.) |
@@ -43,4 +43,4 @@ Two valid cases:
**Snippet A — warm-scene + warm-earth personal story, text_policy: none, 1200×600**
-> Atmospheric scene illustration with golden-hour cinematic lighting. The composition is a three-layer narrative: foreground left — a softly rendered simplified figure silhouette walking along a path with warm long shadows cast toward the right; middle ground — the warm path winds into a stylized hillside with a few suggested trees; background — atmospheric perspective creates pale warm distance, sky transitioning from amber `#D97706` at the horizon to soft cream `#FEF3C7` at the top. Lighting is warm golden-hour from the upper right. Foreground in deeper warm primary `#9A3412`; small accent gold `#D4AF37` highlights on sunlit surfaces. No hard outlines — forms emerge from light and shadow. Subtle film grain at 8% opacity. Composed as a 1200×600 hero scene with 10% inner padding. Simplified silhouette figure only — no realistic face. NO text or labels. Color values are rendering guidance only.
\ No newline at end of file
+> Atmospheric scene illustration with golden-hour cinematic lighting. The composition is a three-layer narrative: foreground left — a softly rendered simplified figure silhouette walking along a path with warm long shadows cast toward the right; middle ground — the warm path winds into a stylized hillside with a few suggested trees; background — atmospheric perspective creates pale warm distance, sky transitioning from amber `#D97706` at the horizon to soft cream `#FEF3C7` at the top. Lighting is warm golden-hour from the upper right. Foreground in deeper warm primary `#9A3412`; small accent gold `#D4AF37` highlights on sunlit surfaces. No hard outlines — forms emerge from light and shadow. Subtle film grain at 8% opacity. Composed as a 1200×600 hero scene with 10% inner padding. Simplified silhouette figure only — no realistic face. NO text or labels. Color values are rendering guidance only.
diff --git a/skills/ppt-master/references/modes/_index.md b/skills/ppt-master/references/modes/_index.md
index 02587f33..e119ad6d 100644
--- a/skills/ppt-master/references/modes/_index.md
+++ b/skills/ppt-master/references/modes/_index.md
@@ -12,7 +12,7 @@ Each mode has its own file with: narrative skeleton, page-structure tendencies,
| Mode | Narrative skeleton | Best for |
|---|---|---|
-| [`pyramid`](./pyramid.md) | Conclusion first; MECE arguments; every datum carries a comparison | Decision support, analysis, strategy, board / exec reports |
+| [`pyramid`](./pyramid.md) | Conclusion first; structured arguments; data contextualized with supported comparisons where useful | Decision support, analysis, strategy, board / exec reports |
| [`narrative`](./narrative.md) | Story arc — situation → tension → resolution; suspense and turns | Pitches, case studies, brand journeys, fundraising |
| [`instructional`](./instructional.md) | Concept decomposition; step-by-step; parallel exposition | Training, tutorials, explainers, knowledge sharing |
| [`showcase`](./showcase.md) | Visual-led impact; big imagery / numbers; emotional rhythm | Launches, brand reveals, event / promo decks |
@@ -40,12 +40,12 @@ Each mode has its own file with: narrative skeleton, page-structure tendencies,
| Torn between | …the first when | …the second when |
|---|---|---|
-| `pyramid` / `briefing` | it must land a recommendation — conclusion-first, every number compared | it must inform completely without arguing — topic titles, even weight |
+| `pyramid` / `briefing` | it must land a recommendation — conclusion-first, figures contextualized toward a decision | it must inform completely without arguing — topic titles, even weight |
| `narrative` / `pyramid` | the point lands through a story arc, tension → resolution | the point lands as a conclusion stated up front, then supported |
-| `narrative` / `showcase` | an argument travels through the story | presence leads — minimal copy, one big visual per page |
+| `narrative` / `showcase` | an argument travels through the story | presence leads — concise copy and a clear visual focus |
| `instructional` / `briefing` | the goal is to build understanding step by step | the goal is to lay out a complete reference to scan |
-> "Keynote-style" is a *mode* request, not a visual style — it means showcase pacing (one big idea per page, full-bleed hero, reveal rhythm), skinned by whatever visual style fits the brand (`swiss-minimal` clean, `dark-tech` dramatic, `glassmorphism` premium). Don't reach for a "keynote" visual style — there isn't one, by design.
+> "Keynote-style" is a *mode* request, not a visual style — it means showcase pacing (a clear primary idea, hero-scale visual treatment, reveal rhythm), skinned by whatever visual style fits the brand (`swiss-minimal` clean, `dark-tech` dramatic, `glassmorphism` premium). Don't reach for a "keynote" visual style — there isn't one, by design.
---
diff --git a/skills/ppt-master/references/modes/instructional.md b/skills/ppt-master/references/modes/instructional.md
index d0feaefe..48b18e70 100644
--- a/skills/ppt-master/references/modes/instructional.md
+++ b/skills/ppt-master/references/modes/instructional.md
@@ -8,11 +8,11 @@ Teaching-led exposition. Decompose a concept into ordered, digestible parts and
**Decompose, then sequence**: break the subject into parts and present them in a deliberate order (simple → complex, prerequisite → dependent, overview → detail).
-**One concept per page**: each page teaches a single idea well; do not stack unrelated concepts.
+**Focused learning unit**: center each page on a coherent teaching step; related concepts may share a page when their relationship is what the learner needs to understand.
**Parallel exposition**: sibling concepts get parallel structure — same shape, same depth — so the audience can compare and map them.
-**Show, then tell**: lead with a concrete example or analogy, then state the principle. A worked example beats an abstract definition.
+**Ground abstraction**: use a concrete example or analogy when it clarifies the principle; sequence example and explanation according to the learner's prerequisite needs.
**Signpost**: orient the learner — what we covered, what comes next.
@@ -24,7 +24,7 @@ Titles state what the page teaches ("How attention weights are computed") — cl
- Numbered steps / ordered flows for processes; parallel cards for sibling concepts.
- Diagrams that build incrementally; annotate the part currently being explained.
-- A concrete example anchors each abstract point.
+- Concrete examples anchor abstract points when they improve transfer or comprehension.
> Step / flow / diagram geometry lives in [`templates/charts/`](../../templates/charts/); this mode decides *the learning order and granularity*.
diff --git a/skills/ppt-master/references/modes/narrative.md b/skills/ppt-master/references/modes/narrative.md
index a8276e82..94f2207a 100644
--- a/skills/ppt-master/references/modes/narrative.md
+++ b/skills/ppt-master/references/modes/narrative.md
@@ -6,13 +6,13 @@ Story-arc persuasion. Carry the audience through situation → tension → resol
## 1. Narrative skeleton
-**Arc, per deck and per page**: scenario → conflict → resolution. Set a stake, raise a tension, resolve it — then bridge to the next beat.
+**Arc across the deck and within suitable beats**: scenario → conflict → resolution. Set a stake, raise tension, resolve it, and bridge to the next beat without forcing the complete arc onto every page.
-**Suspense and payoff**: pose a question at the right moment, answer it on the next page. Let curiosity pull the audience forward.
+**Suspense and payoff**: pose a question at the right moment and answer it at the beat where the evidence lands. Let curiosity pull the audience forward.
**Human framing**: anchor abstract points in a protagonist, a moment, a concrete stake ("a team that shipped in two weeks instead of three months").
-**At least one turn**: a reframe, a reveal, a "but here's what changed". Flat exposition is not narrative.
+**Narrative movement**: use a reframe, reveal, or change in stakes where the material supports it. The sequence should move rather than merely relabel flat exposition.
Titles read as beats that advance the arc ("Then the numbers stopped adding up"), not as labels.
@@ -20,7 +20,7 @@ Titles read as beats that advance the arc ("Then the numbers stopped adding up")
## 2. Page-structure tendencies
-- Pages alternate rhythm: a dense beat followed by a breathing page (single image / quote / turn) to prevent fatigue.
+- Vary dense and breathing beats according to tension, payoff, and audience fatigue; do not enforce a mechanical alternation.
- Visual weight guides the eye through each beat (hero image, one focal number, a pull quote).
- Continuity within a chapter, variation between chapters.
@@ -30,7 +30,7 @@ Titles read as beats that advance the arc ("Then the numbers stopped adding up")
## 3. Speaker-notes register
-Conversational narration — like talking with the audience, not reading a report. Scenario-conflict-resolution per page. Metaphors make the abstract tangible ("like adding a turbocharger"). Plain rhetorical questions create suspense; bridge each page from the prior one. Conversational data ("nearly a third", "more than doubled"). (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)
+Conversational narration — like talking with the audience, not reading a report. Use scenario-conflict-resolution within a page when that beat benefits from it. Metaphors make the abstract tangible ("like adding a turbocharger"). Plain rhetorical questions create suspense; bridge each page from the prior one. Conversational data ("nearly a third", "more than doubled"). (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)
---
diff --git a/skills/ppt-master/references/modes/pyramid.md b/skills/ppt-master/references/modes/pyramid.md
index 5dc50cee..33e50f10 100644
--- a/skills/ppt-master/references/modes/pyramid.md
+++ b/skills/ppt-master/references/modes/pyramid.md
@@ -1,6 +1,6 @@
# Mode: pyramid
-Conclusion-first argumentation. State the answer, then support it with mutually-exclusive, collectively-exhaustive evidence — every claim earns its place, every number carries a comparison. For audiences who want the result before the process: executives, boards, investors, decision-makers.
+Conclusion-first argumentation. State the answer, then support it with structured evidence — every claim earns its place and data is contextualized without inventing comparisons. For audiences who want the result before the process: executives, boards, investors, decision-makers.
---
@@ -12,10 +12,10 @@ SCQA opening, pyramid body:
| Stage | Role | Where |
|---|---|---|
-| Situation | establish shared context | cover / first 1-2 pages |
+| Situation | establish shared context | opening pages |
| Complication | the tension / problem | early pages |
| Question | the implicit question to resolve | transition |
-| Answer | the recommendation, developed MECE | all body pages |
+| Answer | the recommendation, developed through structured evidence; use MECE when the source supports it | body pages |
**Assertion titles** — write the finding, not the topic:
@@ -25,16 +25,16 @@ SCQA opening, pyramid body:
| "Challenges" | "Three structural contradictions block scaled deployment" |
| "Our Solution" | "Three-phase path: Focus, Expand, Scale" |
-**Data never stands alone** — every figure pairs with a comparison (prior period / benchmark / competitor / target / rank) and a "so what". A bare number is an incomplete thought in this mode.
+**Contextualize data** — pair a figure with a supported comparison when that comparison changes the decision; otherwise state its direct relevance or implication. Never invent a prior period, benchmark, competitor, target, or rank to satisfy the mode.
-**MECE** — when decomposing (drivers, segments, options), branches are mutually exclusive and collectively exhaustive; parts sum to the whole (or label "Other").
+**Structured decomposition** — when decomposing drivers, segments, or options, make branches meaningfully distinct and cover what the decision needs. Preserve real overlap or an acknowledged gap instead of fabricating a perfect MECE partition.
---
## 2. Page-structure tendencies
-- Title (the conclusion) → one-line takeaway → supporting evidence beneath.
-- Each body page answers one question and states its own one-sentence conclusion.
+- Title (the conclusion) → concise takeaway → supporting evidence beneath.
+- Each body page centers on a decision-relevant question and states a clear conclusion; supporting subquestions may share the page when their relationship matters.
- Decomposition pages (driver tree / MECE breakdown / 2×2 matrix) carry the analytical load.
- Source attribution on every data page.
@@ -44,7 +44,7 @@ SCQA opening, pyramid body:
## 3. Speaker-notes register
-Conclusion-driven: the first sentence of each page's notes is the takeaway, then 2-3 supporting facts in flowing prose. Composed, authoritative. Every number paired with its comparison in the same sentence ("23% — nearly double the industry's 12%"). Spell percentages as words where the spoken form reads more naturally. (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)
+Conclusion-driven: open each page's notes with the takeaway, then support it with a compact set of facts in flowing prose. Composed, authoritative. Pair a number with a supported comparison when it materially clarifies the takeaway ("23% — nearly double the industry's 12%"); otherwise explain its implication directly. Spell percentages as words where the spoken form reads more naturally. (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)
---
@@ -53,6 +53,6 @@ Conclusion-driven: the first sentence of each page's notes is the takeaway, then
```
Title: "Retention, not acquisition, now drives growth" ← the conclusion
Takeaway: one line — "CAC up 40% YoY, yet repurchase lifted 60% of revenue growth"
-Body: 3 MECE arguments, each with one contextualized datum
+Body: supporting arguments with contextualized data
Footer: Source: … | page #
```
diff --git a/skills/ppt-master/references/modes/showcase.md b/skills/ppt-master/references/modes/showcase.md
index 301330b7..138e5107 100644
--- a/skills/ppt-master/references/modes/showcase.md
+++ b/skills/ppt-master/references/modes/showcase.md
@@ -6,11 +6,11 @@ Visual-led impact. Let imagery, scale, and rhythm carry the message; minimize co
## 1. Narrative skeleton
-**Image / number leads, words support**: each page has one dominant visual element — a hero image, a single huge number, a short phrase — not a paragraph.
+**Image / number leads, words support**: establish a dominant visual hierarchy through a hero image, large number, or short phrase; supporting elements may share the page without competing for focus.
**Emotional rhythm**: build and release — a run of bold pages punctuated by a quiet one. Pace for feeling, not density.
-**One idea per page, stated big**: reduce each page to a single takeaway expressed at scale.
+**Primary idea stated big**: center each page on a clear takeaway expressed at scale; retain supporting context when the audience needs it to understand or trust that takeaway.
**Reveal structure**: hold back, then reveal (the product, the result, the tagline) for maximum effect.
@@ -20,11 +20,11 @@ Titles are short and evocative — a phrase, not a sentence.
## 2. Page-structure tendencies
-- Full-bleed imagery with overlay text; a single focal hero number / phrase.
-- Generous negative space; the page breathes around one element.
+- Full-bleed imagery with overlay text; a focal hero number or phrase.
+- Generous negative space around the primary visual relationship.
- Bold use of the deck's theme color for atmosphere (cover / chapter pages).
-> Hero / full-bleed / breathing-page geometry lives in [`executor-base.md`](../executor-base.md) and [`image-layout-patterns.md`](../image-layout-patterns.md); this mode decides *what single thing each page presents*.
+> Hero / full-bleed / breathing-page geometry lives in [`executor-base.md`](../executor-base.md) and the optional [`image-layout-patterns.md`](../image-layout-patterns.md) library; this mode decides *what each page makes primary*.
---
diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.md
index a527a1f9..8a7de821 100644
--- a/skills/ppt-master/references/strategist-image.md
+++ b/skills/ppt-master/references/strategist-image.md
@@ -16,7 +16,7 @@ For illustration, apply this precedence: confirmed `none` → explicit user inte
**Context-first understanding for provided assets**: Do not visually scan `images/`. First infer identity, role, and crop / focus needs from source position and surrounding prose, captions / alt / titles, filename, user notes / confirmed `image_notes`, existing resource records, and CSV geometry. Inspect only one specific image when a remaining ambiguity would change selection, factual identity, page role, crop safety, or focal placement. Never inspect for inspiration, bulk-open the folder, or infer external facts / provenance from pixels. Record the result in §VIII. Leave an optional unresolved asset unused; route an unresolved must-use asset through failure recovery.
-For ≥3 AI-generated same-family spots, plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element; only slice rows enter `spec_lock.md images`. State the intended placement shape family in the sheet reference and use separate sheets for incompatible shapes. [`image-generator.md`](./image-generator.md) §4.3 owns grid, ratio, slicing, and execution details. Stage 3 chooses the AI execution path under `image-generator.md` §7; do not pre-empt or re-pick it here.
+**Default — one coherent sheet for compatible same-family spots (may override when aspect, detail, quality, or semantic needs differ)**: prefer one Illustration Sheet when several AI-generated spots can share a useful cell shape and production treatment; generate them independently when forcing one sheet would weaken a planned element. When a sheet is chosen, plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element; only slice rows enter `spec_lock.md images`. State the intended placement shape family in the sheet reference and use separate sheets for incompatible shapes. [`image-generator.md`](./image-generator.md) §4.3 owns grid, ratio, slicing, and execution details. Stage 3 chooses the AI execution path under `image-generator.md` §7; do not pre-empt or re-pick it here.
## 2. AI Image Strategy — propose before Stage 2; lock only for confirmed `ai`
@@ -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, 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. `source` and `crop` preserve the exact confirmed §VIII text; `pattern` preserves its ordered catalog ids or normalized custom prose while remaining preferred expression, not locked geometry. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web records exact subject, view/mood, focal/quiet region, and crop safety with positive quality cues; Image_Searcher later derives a separate 1–4 word query without rewriting this locked intent; formula preserves 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 suggestion, 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. `source` and `crop` preserve the exact confirmed §VIII text; `pattern` preserves the non-empty free-form suggestion, including any optional catalog ids, while remaining preferred expression rather than locked geometry. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web records exact subject, view/mood, focal/quiet region, and crop safety with positive quality cues; Image_Searcher later derives a separate short, specific provider query without rewriting this locked intent, while complete entity names or necessary disambiguation may use more words; formula preserves 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 EXIF-corrected `Width` / `Height` / native `AspectRatio` in the latest `analysis/image_analysis.csv`; `SourceDisplayRatio` is source-context metadata, not the bitmap crop ratio. 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**: start at `High-Yield Patterns` and read [`image-layout-patterns.md`](./image-layout-patterns.md) completely. Each row copies a Part 1 Primary `#<id> <name>` plus any Modifiers verbatim; modifier-only routes add fitting Primary page bones. No blanks, paraphrases, or invented ids.
+**Mandatory**: write one concise, non-empty, executable `Layout pattern` value per non-formula row in ordinary language. It may cite stable ids from [`image-layout-patterns.md`](./image-layout-patterns.md), but reading the library or using ids is not required. Preserve any cited id accurately; otherwise describe the composition without inventing one.
-**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 native boolean-geometry family is the largest single lever on how designed the exported deck looks. Patterns requiring a cutout, blurred crop, or desaturated copy are selectable only when that derived asset is already prepared; otherwise choose a one-asset/native-shape fallback. 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.
+**Reference — not a constraint**: open [`image-layout-patterns.md`](./image-layout-patterns.md) only when its vocabulary would expand the current options. Techniques needing a cutout, blurred crop, or desaturated copy require that prepared asset. Executor may adapt, replace, or decline the suggestion while preserving resource role, file/source, must-use status, crop boundary, content, and explicit user/template constraints; layout-only changes need no upstream rewrite.
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 4060fc28..255cd2ce 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -280,7 +280,7 @@ user/template requirements bind.
| Capability | Opportunity signal | Design Spec handoff |
|---|---|---|
-| Image composition | Image-as-canvas, editorial crop, collage, cutout, or meaningful focus / comparison / evidence units carry the page better than an adjacent rectangle | Propose a permitted source; when selected, load [`strategist-image.md`](./strategist-image.md), record exact §VIII `Layout pattern`, and describe page-level image/overlay relationships in §IX `Layout` / `Images` |
+| Image composition | Image-as-canvas, editorial crop, collage, cutout, or meaningful focus / comparison / evidence units carry the page better than an adjacent rectangle | Propose a permitted source; when selected, load [`strategist-image.md`](./strategist-image.md), record a concise §VIII `Layout pattern` suggestion, and describe page-level image/overlay relationships in §IX `Layout` / `Images` |
| Native paint / overlay | Gradient, translucency, scrim, vignette, or wash supports focus, hierarchy, depth, legibility, or image integration | Record purpose/layering in §IX `Layout`, plus `Images` when imagery participates; no new field or type/stops/opacity/coordinates—Executor chooses realization |
| Native shape / Merge Shapes | A literal Office symbol, a stock bent/curved relationship contour, 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/Connector family or Boolean operation/operands |
| Page transition | A section/state change, spatial continuity, recorded/self-running flow, or the same semantic object changing position, scale, crop, or state across adjacent pages benefits from motion | Add an optional §IX `Motion suggestion` describing the communication job and any continuing object's start/end semantic states; leave effect, ids, pairing names, and timing to Executor |
@@ -293,7 +293,7 @@ Review planned pages through two lenses:
| Numeric / data | comparisons, trends, proportions, KPIs, financials, rankings, distributions, funnels |
| Structural information | rosters, agendas, principles, phases, journeys, capability maps, OKR cascades, roadmaps, strategic frameworks |
-**Per-page recall**: For every page whose information structure may benefit from a visualization, restate the content shape as 3–8 concise English semantic tags. Translate source-language and industry terms into structure before recall. Run:
+**Reference — not a constraint**: use catalog recall when it would help. Its CLI accepts 3–8 distinct English content-shape tags; a page already planned as a custom visualization or table needs no recall. Run:
```bash
python3 skills/ppt-master/scripts/chart_recall.py recall \
@@ -309,7 +309,7 @@ The command returns a bounded shortlist plus `no-template-match`. Read it unfilt
**Selection**:
1. Choose the most relevant candidate as a reference for that page. It does not lock the final visualization type or geometry and never applies to another page without its own row.
-2. After the fallback gate above, retain `no-template-match` when no reference fits: data content falls back to a table, permitted conceptual content to an AI image, and structural content to a custom layout. Record the fallback only in the page's §IX `Visualization` / `Layout`; never serialize it into §VII.
+2. Retain `no-template-match` when no reference fits. Choose a custom visualization, table, diagram/layout, or permitted image from the content semantics, communication job, and editability need. Record the choice only in §IX; never serialize `no-template-match` into §VII.
3. Validate all selected keys before writing the lock:
```bash
@@ -437,7 +437,7 @@ 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, 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.
+**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, layout suggestion, 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 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.
@@ -446,9 +446,9 @@ Generate Step 4 owns this sequence. `design_spec.md` is the complete human-reada
- **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing`. This is what breaks the uniform "every page is a card grid" feel. New locks may not omit the section; consumer omission behavior is owned by [`executor-base.md`](executor-base.md) §2.1.
- **Fact IDs and scenario labels are mandatory when applicable**: Read any `sources/*.facts.json`. For each §IX page, list the stable IDs actually used; never cite an ID whose claim is absent from the page. Mark invented KPIs/targets/internal ratios as `Data class: scenario` and state which values are scenario data. Executor carries external sources into notes/footnotes and renders a visible scenario label for scenario figures.
- **Rhythm follows narrative, not quota**: `breathing` pages mark natural pauses — chapter transitions, standalone emphasis (hero quote / big number), SCQA bridges. Dense decks may legitimately be all `dense`. **Do NOT invent filler pages** ("Thank you", empty dividers) to pad rhythm — every `breathing` page must say something independent. Consumption mode biases the overall lean (`presentation` toward more `anchor` / `breathing`, `text` toward `dense`; see §6.1) — a bias, never a quota.
- - **Cover impact is mandatory**: Page `P01` is the deck's first visual contract, not a generic title slide. In `design_spec.md §IX`, add a `Cover impact` line for `P01` that names one concrete hook and one concrete composition strategy. Use the source's strongest available signal: a provocative core claim, object / scene metaphor, hero number, founder / product / audience moment, or a distilled conflict. Pair it with one concrete composition strategy — such as `full-bleed image + floating title`, `typographic poster`, `hero object`, `data hook`, `editorial scene`, `high-contrast abstract geometry`, or a fresh composition the deck's subject suggests (these are starting points, not the allowed set). If no external or AI image is available, still specify a native-SVG visual hook; do not fall back to "title + subtitle + decorative background". (Beautify / template-fill keep the source cover verbatim — this rule does not apply on those preservation paths.)
- - **Cover rhythm lock**: `P01` remains `anchor` in `spec_lock.md page_rhythm`, but its §IX `Cover impact` must prevent content-page patterns. Do not plan multi-card grids, agenda-like bullets, or equal-weight columns on the cover unless a template explicitly requires that structure, or a preservation path (beautify / template-fill) is transcribing the source cover verbatim.
- - **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.
+ - **Cover impact is mandatory**: In `design_spec.md §IX`, give `P01` one concrete hook from the source's strongest claim, metaphor, number, moment, or conflict plus a recommended composition. The hook binds; Executor may adapt the composition to prepared assets and explicit constraints. With no suitable image, recommend a native-SVG hook instead of a generic title treatment. Beautify / template-fill preservation paths are exempt.
+ - **Cover rhythm lock**: `P01` remains `anchor`. Default away from generic content-page templates; a card grid, agenda, or equal-weight columns remains valid when content, user direction, or the template makes it the clearest cover.
+ - **Closing impact (only when the deck closes)**: For a genuine conclusion / CTA / final takeaway, name the binding takeaway plus a recommended composition; Executor may adapt the latter. Do not default to an information-empty "Thank you", contact-only slide, or cover reprise; an explicit contact/event CTA may serve the purpose. **Do NOT invent a closing page to satisfy this**. Preservation paths are exempt.
- **pptx_structure is mandatory**: Free-design, brand-only, and `template_reuse_scope: style` routes write `mode: flat`; a style-reference route may also record `template_reuse_scope: style` but omits every structure mapping and `template_adherence`. `template_reuse_scope: mirror|layout` writes `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.
- **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.
- **Structured template route**: When [`strategist-template.md`](./strategist-template.md) is active and reuse is `mirror|layout`, follow its complete Master/Layout/slot/prototype mapping rules.
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index 45cd1a18..ed5e85ee 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -24,7 +24,7 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac
| **Pending** | Acquisition needed (`Acquire Via: ai` / `web`) or derivation needed (`Acquire Via: slice`); not yet attempted | Image Acquisition Phase (Step 5) consumes this; must not remain after Step 5 |
| **Failed** | The latest automatic acquisition attempt failed; this is retryable and non-terminal | Step 5 reruns the owning manifest or explicitly resolves the row to `Needs-Manual`; Executor must never treat `Failed` as usable content |
| **Generated** | AI-generated file exists at expected path, or sliced element file exists at expected path | Reference from `../images/`; no on-slide credit needed. **Exception**: an `Illustration Sheet` row is only a slice source — it lives in §VIII but never in `spec_lock.md images`, so the Executor never places it |
-| **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [`executor-web-image.md`](./executor-web-image.md) §1 and [`image-searcher.md`](./image-searcher.md) §7 for the visual spec) |
+| **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [`executor-web-image.md`](./executor-web-image.md) §1 and [`image-searcher.md`](./image-searcher.md) §7 for the attribution contract) |
| **Rendered** | Deterministic formula PNG exists at expected path (`Acquire Via: formula`) | Reference from `../images/`; use a legal anchor with `meet` for the complete placement (centered default: `xMidYMid meet`) and do not crop |
| **Needs-Manual** | Automatic acquisition is unavailable/exhausted or the confirmed path requires manual fulfillment; for `slice`, the parent sheet is unavailable | Dashed placeholder unless the user has supplied the expected file. For `slice` rows, supply the parent sheet and rerun `slice_images.py`; do not hand-place individual element files |
| **Existing** | User already has image (`Acquire Via: user`) | Place in `images/`, reference with `<image>` |
diff --git a/skills/ppt-master/references/visual-styles/brutalist.md b/skills/ppt-master/references/visual-styles/brutalist.md
index 369705d9..2c94793a 100644
--- a/skills/ppt-master/references/visual-styles/brutalist.md
+++ b/skills/ppt-master/references/visual-styles/brutalist.md
@@ -9,19 +9,19 @@ Brutalist editorial newspaper. Wall-to-wall small type, irregular column widths,
- Shape language: hard rectangles and ruled boxes; thick black borders / cell frames; visible column dividers. Corner radius `rx="0"` — never rounded.
- Composition geometry: a masthead numeral or headline set so large it crosses column rules; one grid cell inverted to solid ink (light type on dark) as the focal cell; full-bleed rule bars slicing sections; a single rotated stamp-box breaking the grid at one deliberate point.
- Decoration: the grid itself is the decoration — masthead bars, rule lines, boxed pull-quotes, halftone fills. No gradients, no soft cards, no shadows.
-- Whitespace: tight and deliberate — narrow margins, dense columns, a newspaper's packed rhythm. Density is the point; one or two breathing zones per page keep it readable, not airy.
+- Whitespace: tight and deliberate — narrow margins, dense columns, a newspaper's packed rhythm. Density is the point; retain enough breathing room for hierarchy and readability without imposing a per-page count.
- Irregular multi-column layout (mixed column widths) over a uniform grid; asymmetry is intentional.
## 2. Typography character
-- Three-family hard contrast: a heavy display sans for headlines (poster-black weight), a serif for column body, monospace for figures / data — the collision is the look.
+- Strong role contrast: a heavy display sans for headlines (poster-black weight), a serif character for column body, and monospace for figures / data can create the collision this style needs without imposing a family count.
- Small body size, high density; strong size jump between masthead headline and body. Flush-left columns, tight leading.
> Families are chosen at confirmation `g`; this style asks for a display-black × serif-body × monospace-data *character*.
## 3. Using the deck's colors
-- Near-monochrome: ink-dark structure and type on a paper-light field; a single spot accent appears rarely (a masthead rule, one key figure, a stamp) — a few percent of canvas at most.
+- Near-monochrome: ink-dark structure and type on a paper-light field; use a localized spot accent as punctuation, such as a masthead rule, key figure, or stamp.
- Color as punctuation, not fill. No color blocking, no gradients — the accent earns attention by scarcity.
> HEX values come from confirmation `e`; this style only governs how sparingly the accent is used — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/dark-tech.md b/skills/ppt-master/references/visual-styles/dark-tech.md
index 29567d11..94338977 100644
--- a/skills/ppt-master/references/visual-styles/dark-tech.md
+++ b/skills/ppt-master/references/visual-styles/dark-tech.md
@@ -6,7 +6,7 @@ Dark canvas, luminous accents, geometric precision. For tech, AI, dev tools, dat
## 1. Shape & decoration
-- Shape language: crisp geometry; thin glowing rules; hexagon / circuit / grid motifs used sparingly. Slight rounding (`rx` 4-8) or sharp.
+- Shape language: crisp geometry; thin glowing rules; hexagon / circuit / grid motifs used sparingly. Corners may be sharp or only slightly rounded.
- Composition geometry: a glowing diagonal circuit trace splitting the field; concentric orbit rings staging a central metric; a hexagon node cluster mapping components; an oversized low-opacity numeral or glyph floating behind the content layer; thin bracket frames zoning the page.
- Decoration: glow accents, fine grid backgrounds, monospace labels, node / connector lines. Restrained — precision over clutter.
- Whitespace: dark negative space reads as depth; let elements float on it.
@@ -20,8 +20,8 @@ Dark canvas, luminous accents, geometric precision. For tech, AI, dev tools, dat
## 3. Using the deck's colors
-- Dark background; one or two luminous accents carry focus (glowing figures, active nodes); everything else low-key.
-- The accent does the work of attention — few points, high contrast.
+- Dark background; a restrained set of luminous accents carries focus through glowing figures or active nodes while everything else stays low-key.
+- The accent does the work of attention through localized, high-contrast use rather than a fixed point count.
> HEX values come from confirmation `e`; this style only governs the dark-field, luminous-accent discipline — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/editorial.md b/skills/ppt-master/references/visual-styles/editorial.md
index c3edb5f9..4f46e2c3 100644
--- a/skills/ppt-master/references/visual-styles/editorial.md
+++ b/skills/ppt-master/references/visual-styles/editorial.md
@@ -6,8 +6,8 @@ Magazine-grade hierarchy. Columns, hairline rules, a serif / sans interplay, str
## 1. Shape & decoration
-- Shape language: rectilinear; thin rules and column dividers instead of cards. Minimal rounding (`rx` 0-4).
-- Composition geometry: an oversized drop cap or numeral anchoring the page; a pull quote breaking across two columns; a full-height vertical rule the content hangs from; an asymmetric 2:1 column split instead of even columns; one figure deliberately crossing a column edge.
+- Shape language: rectilinear; thin rules and column dividers instead of cards. Rounding, when used, stays visually minimal.
+- Composition geometry: an oversized drop cap or numeral anchoring the page; a pull quote breaking across columns; a full-height vertical rule the content hangs from; an asymmetric column split instead of mechanically even columns; a figure deliberately crossing a column edge.
- Decoration: hairline rules, kickers / eyebrows, pull quotes, drop-style emphasis — typographic, not graphic. Sparing.
- Whitespace: structured by columns and baseline rhythm; comfortable but information-rich.
- Multi-column text flow where content suits.
@@ -21,7 +21,7 @@ Magazine-grade hierarchy. Columns, hairline rules, a serif / sans interplay, str
## 3. Using the deck's colors
-- Mostly monochrome text on a light field; one accent for emphasis (a rule, a highlighted figure, a kicker).
+- Mostly monochrome text on a light field; a restrained accent may emphasize a rule, highlighted figure, or kicker.
- Restraint — color marks structure and emphasis, not decoration.
> HEX values come from confirmation `e`; this style only governs the monochrome-with-structural-accent discipline — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/glassmorphism.md b/skills/ppt-master/references/visual-styles/glassmorphism.md
index b1f8a030..88b65314 100644
--- a/skills/ppt-master/references/visual-styles/glassmorphism.md
+++ b/skills/ppt-master/references/visual-styles/glassmorphism.md
@@ -6,7 +6,7 @@ Frosted-glass SaaS — translucent layered panels, flowing gradient light, float
## 1. Shape & decoration
-- Shape language: rounded translucent glass panels (low fill-opacity over the dark field) with bright hairline edges; layered, floating cards that imply blur and frost; rounded corners (`rx` 12-20).
+- Shape language: visibly rounded translucent glass panels (low fill-opacity over the dark field) with bright hairline edges; layered, floating cards that imply blur and frost.
- Composition geometry: one hero glass panel set off-axis over a radial bloom; overlapping translucent discs building the focal cluster; a large glass ring encircling the key metric; panels stepped in depth to imply sequence; a diagonal light beam crossing the dark field.
- Decoration: soft radial light blooms in the background; thin luminous edge highlights along panels; restrained — the glass material is the decoration, not added ornament. Realize the radial bloom / glow halo as a `<circle>` / `<ellipse>` with a `<radialGradient>` fill, never a `rect rx=w/2` standing in for it.
- Whitespace: dark negative space reads as depth; let panels float on it with room to breathe.
@@ -19,7 +19,7 @@ Frosted-glass SaaS — translucent layered panels, flowing gradient light, float
## 3. Using the deck's colors
-- Dark field; the deck's colors read as luminous gradients flowing across panels and titles, low-opacity glass tints, and a neon accent at ~10%. Color behaves like light through glass, not flat fill.
+- Dark field; the deck's colors read as luminous gradients flowing across panels and titles, low-opacity glass tints, and a subordinate neon accent. Color behaves like light through glass, not flat fill.
- Depth and hierarchy come from how brightly the glass glows, not from heavy saturation.
> HEX values come from confirmation `e`; this style only governs the translucent-glass, luminous-gradient discipline — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/ink-notes.md b/skills/ppt-master/references/visual-styles/ink-notes.md
index 8b3a2b19..60043e81 100644
--- a/skills/ppt-master/references/visual-styles/ink-notes.md
+++ b/skills/ppt-master/references/visual-styles/ink-notes.md
@@ -20,8 +20,8 @@ Whiteboard-ink minimalism — a pale field, confident black hand-ink line work,
## 3. Using the deck's colors
-- Near-monochrome: ink-dark line work on a pale field does ~85% of the work; the deck's accent appears only as a semantic mark (risk / positive / highlight) under ~10% of canvas.
-- Color carries meaning, not decoration — one or two accents, used where they signify.
+- Near-monochrome: ink-dark line work on a pale field carries the composition; the deck's accent remains a sparse semantic mark for risk, positive state, or emphasis.
+- Color carries meaning, not decoration; use only the accents that signify something on the current page.
> HEX values come from confirmation `e`; this style only governs the monochrome-with-semantic-accent discipline — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/memphis.md b/skills/ppt-master/references/visual-styles/memphis.md
index 3a66789e..3cbafaf3 100644
--- a/skills/ppt-master/references/visual-styles/memphis.md
+++ b/skills/ppt-master/references/visual-styles/memphis.md
@@ -6,7 +6,7 @@ Memphis / Pop — clashing color blocks, geometric confetti, bold outlines, 80s-
## 1. Shape & decoration
-- Shape language: bold geometric primitives — circles, triangles, zigzags, squiggles, blobs — with thick dark outlines (2-4px). Mixed corner radii allowed; playful inconsistency is on-brand.
+- Shape language: bold geometric primitives — circles, triangles, zigzags, squiggles, blobs — with thick dark outlines. Mixed corner radii allowed; playful inconsistency is on-brand.
- Composition geometry: a giant primitive bleeding off one edge as the backdrop; a diagonal two-color field split; a zigzag or squiggle band as the section divider; props scattered at angles around one dominant rotated frame or badge at the focal point.
- Decoration: scattered geometric confetti, color-block backings, pattern fills (dots / stripes), oversized punctuation. Generous decoration — but composed, not chaotic.
- Whitespace: energetic asymmetry; props float at angles. Still leave the focal content room to read against the noise.
@@ -20,7 +20,7 @@ Memphis / Pop — clashing color blocks, geometric confetti, bold outlines, 80s-
## 3. Using the deck's colors
-- Multi-accent clash is the signature — but bounded: the clashing colors stay a minority of canvas (≈40% cap), and any one page fronts only two or three of them, not the whole set.
+- Multi-accent clash is the signature, but the light field and dark outlines remain visually dominant. Front a curated subset of the deck accents on each page instead of displaying the whole set by quota.
- A light field carries the noise; dark outlines anchor every shape so the clash reads as composed, not muddy. Disciplined exuberance, never rainbow soup.
> HEX values come from confirmation `e`; this style governs how many accents appear and how boldly — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/paper-cut.md b/skills/ppt-master/references/visual-styles/paper-cut.md
index cdf51582..d4f0d84e 100644
--- a/skills/ppt-master/references/visual-styles/paper-cut.md
+++ b/skills/ppt-master/references/visual-styles/paper-cut.md
@@ -26,7 +26,7 @@ Layered paper-craft — scissor-cut shapes stacked in tactile layers, soft shado
## 4. Texture / elevation
-- Real layered depth — a soft 8-12% drop shadow under each cut layer is core here (the one style where layered shadow is the point, not a violation). Matte paper grain on each sheet.
+- Real layered depth — a soft, low-opacity drop shadow under cut layers is core here (the style where layered shadow is the point, not a violation). Matte paper grain on each sheet.
## 5. Paired image-rendering
diff --git a/skills/ppt-master/references/visual-styles/soft-rounded.md b/skills/ppt-master/references/visual-styles/soft-rounded.md
index 1caf771b..b566e695 100644
--- a/skills/ppt-master/references/visual-styles/soft-rounded.md
+++ b/skills/ppt-master/references/visual-styles/soft-rounded.md
@@ -6,7 +6,7 @@ Approachable and modern. Rounded cards, gentle elevation, friendly rhythm. For p
## 1. Shape & decoration
-- Shape language: rounded rectangles (`rx` 12-16), pill tags, soft containers. Consistent radius deck-wide.
+- Shape language: visibly rounded rectangles, pill tags, and soft containers. Keep the radius family coherent deck-wide.
- Composition geometry: a large soft disc or blob bleeding off one edge as the color field; a pill chain or exact native `arc` / `blockArc` preset replacing the boxed step row; one hero panel overlapping a full-width tinted band; an oversized rounded numeral behind the point. Use a custom arc path only when the presets cannot faithfully express the intended contour. Cards are the container language, not the composition — vary the stage they sit on.
- Decoration: cards as the primary container; icon accents; numbered circles; gentle dividers. Moderate, in service of clarity.
- Whitespace: comfortable padding inside cards; even gutters; balanced rather than austere.
@@ -27,7 +27,7 @@ Approachable and modern. Rounded cards, gentle elevation, friendly rhythm. For p
## 4. Texture / elevation
-- Gentle elevation: soft shadows on floating cards (resting tier), subtle tints, optional same-hue gradients. Two-tier elevation max; keep peer-grid cards flat.
+- Gentle elevation: soft shadows on floating cards, subtle tints, and optional same-hue gradients. Keep the elevation hierarchy shallow and coherent; peer-grid cards stay flat.
## 5. Paired image-rendering
diff --git a/skills/ppt-master/references/visual-styles/swiss-minimal.md b/skills/ppt-master/references/visual-styles/swiss-minimal.md
index 0d133640..c637ea8c 100644
--- a/skills/ppt-master/references/visual-styles/swiss-minimal.md
+++ b/skills/ppt-master/references/visual-styles/swiss-minimal.md
@@ -6,7 +6,7 @@ Strict Swiss-grid discipline. Modular grid, sharp geometry, aggressive whitespac
## 1. Shape & decoration
-- Shape language: sharp rectangles, true circles, single-weight rules. Corner radius `rx="0"` by default; if rounding at all, ≤4.
+- Shape language: sharp rectangles, true circles, single-weight rules. Use square corners by default; any rounding stays barely perceptible.
- Composition geometry: one oversized geometric plane — a full-height color column, a giant disc, a heavy bar — zoning the page; an asymmetric split with content flush to one axis; a hero numeral at architectural scale; a single diagonal rule or type line as the deliberate grid break. Few, large, exact — geometry at poster scale is Swiss, clutter is not.
- Decoration: none. No gradient fills, no decorative blocks, no badges — structure carries the page.
- Whitespace: vast and deliberate; negative space carries as much weight as content. Wide margins, generous gutters.
@@ -21,7 +21,7 @@ Strict Swiss-grid discipline. Modular grid, sharp geometry, aggressive whitespac
## 3. Using the deck's colors
-- One color dominates a deliberate grid zone; the field stays near-white; the accent appears at a single point — never more than a few percent of canvas.
+- A dominant color may define a deliberate grid zone while the field stays near-white; keep accent color localized enough that it reads as punctuation rather than decoration.
- Color as conceptual zone, not decoration. No gradients.
> HEX values come from confirmation `e`; this style only governs how sparingly they are applied — it names no colors.
diff --git a/skills/ppt-master/references/visual-styles/zine.md b/skills/ppt-master/references/visual-styles/zine.md
index c5e4874f..eda1b17e 100644
--- a/skills/ppt-master/references/visual-styles/zine.md
+++ b/skills/ppt-master/references/visual-styles/zine.md
@@ -8,7 +8,7 @@ Risograph zine / DIY poster — misregistered color layers, halftone dots, a tig
- Shape language: cut-and-paste blocks, offset color shapes, rough frames; outlines in a near-black ink tone. Corner radius low or zero — print-flat, not soft-digital.
- Composition geometry: rotated pasted-on blocks (slight skew) building the collage stage; a torn-strip band as the section divider; an oversized halftone shape bleeding behind the content; a photocopy frame or taped corner anchoring the focal block; column scraps at mixed widths.
-- Decoration: the riso print artifacts — 1-3px color-layer misregistration, halftone-dot `<pattern>` texture, overlapping color blocks that imply a third color where they cross. Texture is the decoration.
+- Decoration: the riso print artifacts — subtle visible color-layer misregistration, halftone-dot `<pattern>` texture, overlapping color blocks that imply another color where they cross. Texture is the decoration.
- Whitespace: poster-like — bold focal blocks with raw margins; deliberate roughness over clean alignment.
## 2. Typography character
@@ -20,8 +20,8 @@ Risograph zine / DIY poster — misregistered color layers, halftone dots, a tig
## 3. Using the deck's colors
-- A strictly limited spot palette (riso logic) on a warm paper field; two ink layers do most of the work and a third spot color appears rarely (<5%).
-- Color is laid as flat spot fills, not gradients; overlap and offset of the same few inks create depth and the third-color illusion. Scarcity and overlap, not variety.
+- A tightly limited spot palette (riso logic) sits on a warm paper field; a dominant ink pairing does most of the work and any additional spot color appears selectively.
+- Color is laid as flat spot fills, not gradients; overlap and offset of the same small ink set create depth and extra-color illusions. Scarcity and overlap, not variety.
> HEX values come from confirmation `e`; this style governs the flat-spot, misregistered-overlay discipline — it names no colors.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 7b243b7e..294ad1e2 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -174,7 +174,7 @@ python3 scripts/template_fill_pptx.py apply <project_path>/sources/<source.pptx>
python3 scripts/template_fill_pptx.py validate <project_path>
```
-`apply` requires `fill_plan.json` to have top-level `"status": "confirmed"` unless `--force` is passed. It automatically writes `filled_YYYYMMDD_HHMMSS.pptx` unless the output stem already ends with a timestamp. It applies a `fade` page transition by default; `--transition <effect>` accepts a canonical effect in the shared native gallery registry documented by [`docs/pptx-transitions.md`](docs/pptx-transitions.md), while old names remain accepted only as compatibility inputs, and `--transition-duration <seconds>` changes its duration. `--transition none` removes the visual effect, `--transition keep` preserves the source transitions, and a per-slide `transition` field in the plan overrides whatever the CLI selects. The object form accepts effect-specific native `effect_options`.
+`apply` requires `fill_plan.json` to have top-level `"status": "confirmed"` unless `--force` is passed. It automatically writes `filled_YYYYMMDD_HHMMSS.pptx` unless the output stem already ends with a timestamp. It preserves source page transitions by default; `--transition <effect>` accepts a canonical effect in the shared native gallery registry documented by [`docs/pptx-transitions.md`](docs/pptx-transitions.md), while old names remain accepted only as compatibility inputs, and `--transition-duration <seconds>` changes a replacement effect's duration. `--transition none` removes the visual effect, `--transition keep` states the preservation policy explicitly, and a per-slide `transition` field in the plan overrides whatever the CLI selects. The object form accepts effect-specific native `effect_options`.
Native existing-PPTX enhancement (direct PPTX, no SVG conversion):
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index f62fc6e3..ae6020a8 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -167,7 +167,7 @@ python3 scripts/analyze_images.py <project_path>/images --canvas ppt43
Without `--canvas`, the tool resolves the project format and falls back to `ppt169`; the flag is an explicit override. The atomic CSV records EXIF-corrected native dimensions/`AspectRatio`, optional source `SourceDisplayRatio`, format, and actual transparent-pixel presence. Native ratio—not source display metadata—drives bitmap layout/crop. An empty folder rewrites a header-only report; unreadable supported files still refresh the report and produce a non-zero exit.
-Use this as the default inventory and geometry source; it does not perform semantic image understanding. Generate planning follows the Strategist's context-first boundary: source context, captions / alt text / titles, filenames, user notes, and existing resource records come first. Only a specific asset whose meaning or safe placement remains materially ambiguous may be inspected, and the workflow never bulk-opens the image folder.
+Use this as the default inventory and geometry source; it does not perform semantic image understanding. Generate planning follows the Strategist's context-first boundary: source context, captions / alt text / titles, filenames, user notes, and existing resource records come first. Only an already-selected provided/web asset whose focal-safe crop, overlay contrast, or quiet region remains materially ambiguous may be inspected for that placement; this never reopens selection or provenance, never bulk-opens the image folder, and never restores routine readback of AI-generated images.
## `image_search.py`
@@ -190,18 +190,18 @@ Providers (Pexels / Pixabay are tried first when keyed; Openverse and Wikimedia
| `openverse` | zero-config | fallback aggregator: Wikimedia + Flickr + museums + rawpixel |
| `wikimedia` | zero-config | educational, scientific, geographic, historical |
-Default search chain (when `--provider` is unset): configured Pexels, configured Pixabay, Openverse, then Wikimedia. Missing keyed credentials are silently skipped. For polished visual decks, configure at least one keyed provider.
+Default search chain (when `--provider` is unset): configured Pexels, configured Pixabay, Openverse, then Wikimedia. Missing keyed credentials are silently skipped. Keyed providers broaden stock-photo coverage but are optional; zero-config providers remain valid.
`image_search.py` uses the same `.env` lookup order as `image_gen.py`, so skill installs can keep `PEXELS_API_KEY` / `PIXABAY_API_KEY` in `~/.ppt-master/.env`.
Query guidance:
-Keep the Design Spec §VIII `Reference` as the full visual/crop intent; write a separate 1–4 word concrete provider query for this CLI.
+Keep the Design Spec §VIII `Reference` as the full visual/crop intent; write a separate concise provider query for this CLI. Start with the shortest phrase that preserves identity, but retain exact multi-word names and necessary disambiguators beyond four words.
| Case | Pattern |
|---|---|
| Generic stock concept | `boardroom meeting` |
-| China-specific landmark | 1–4 official place/identity words |
+| China-specific landmark | Precise official place/identity name plus necessary geography |
| Avoid | Negative prompt wording such as `not tourist snapshot` |
License filter:
@@ -240,7 +240,7 @@ Output:
Allowed licenses (default): CC0, Public Domain, Pexels License, Pixabay Content License, CC BY, CC BY-SA. Auto-rejected: CC BY-NC, CC BY-ND, CC BY-NC-SA, CC BY-NC-ND, all rights reserved, unknown.
-The full role-level reference (intent → query translation, on-slide attribution visual specification) is in [`references/image-searcher.md`](../../references/image-searcher.md).
+The full role-level reference (intent → query translation, on-slide attribution contract) is in [`references/image-searcher.md`](../../references/image-searcher.md).
## `gemini_watermark_remover.py`
diff --git a/skills/ppt-master/scripts/docs/pptx-transitions.md b/skills/ppt-master/scripts/docs/pptx-transitions.md
index b846e6e1..a907d202 100644
--- a/skills/ppt-master/scripts/docs/pptx-transitions.md
+++ b/skills/ppt-master/scripts/docs/pptx-transitions.md
@@ -234,13 +234,13 @@ continue to preserve existing object names and transition XML.
|---|---|---|---|
| Generated PPTX CLI | fade, 0.4s | click | auto-advance maps to both |
| Recorded narration | Preserve resolved enter | narration | none remains visually none |
-| Template Fill v1 | fade, 0.5s | click | keep preserves source; legacy advance_after maps to both |
-| Native Enhance | Confirmed global/per-slide plan effect | Confirmed timing module | Explicit page entries override scope; disabled global transitions preserve unless the plan selected none |
+| Template Fill | preserve source | preserve source | explicit effects replace; legacy advance_after maps to both |
+| Native Enhance | Confirmed global/per-slide plan effect | Confirmed timing module | With audio off, enabled global transitions apply to all pages; with audio on, the scope flag controls non-narrated pages |
-Template Fill and Native Enhance keep their established route defaults.
-The public `create_pptx_with_native_svg` Python API also retains its legacy
-0.5s default; the CLI explicitly passes 0.4s. Changing a default policy is a
-separate migration decision.
+Template Fill changes source transitions only when its CLI or per-slide plan
+selects a replacement, removal, or timed advance. Native Enhance uses its
+confirmed plan. The public `create_pptx_with_native_svg` Python API retains its
+legacy 0.5s default; the generated-deck CLI explicitly passes 0.4s.
---
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index a5403dc9..de842b7d 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -20,7 +20,7 @@
"skills/ppt-master/references/executor-base.md": 8125,
"skills/ppt-master/references/executor-structured.md": 5300,
"skills/ppt-master/references/executor-chart.md": 3100,
- "skills/ppt-master/references/executor-image.md": 1275,
+ "skills/ppt-master/references/executor-image.md": 1500,
"skills/ppt-master/references/executor-web-image.md": 500,
"skills/ppt-master/references/executor-notes.md": 900,
"skills/ppt-master/references/shared-standards.md": 250,
@@ -186,11 +186,11 @@
"max_tokens": 30825
},
"route.generate.planning-image": {
- "description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed.",
+ "description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed; layout-catalog recall remains optional.",
"scope": "cumulative",
"include": [
"route.generate.planning",
- "stage.generate.strategist.image-layout"
+ "stage.generate.strategist.image"
],
"files": [],
"max_tokens": 74850
@@ -727,7 +727,7 @@
"max_tokens": 2500
},
"stage.generate.strategist.image-layout": {
- "description": "Non-formula image planning plus the image-layout pattern catalog required for Section VIII rows.",
+ "description": "Optional image-layout catalog recall layered on image planning when the Strategist wants additional composition vocabulary.",
"scope": "incremental",
"include": [
"stage.generate.strategist.image"
@@ -754,11 +754,10 @@
"max_tokens": 6200
},
"stage.generate.executor.image": {
- "description": "Conditional image embedding and layout execution rules.",
+ "description": "Conditional image embedding and layout execution rules; the optional layout catalog is not part of the required bundle.",
"scope": "incremental",
"files": [
"skills/ppt-master/references/executor-image.md",
- "skills/ppt-master/references/image-layout-patterns.md",
"skills/ppt-master/references/image-layout-spec.md",
"skills/ppt-master/references/svg-image-embedding.md"
],
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index c762e89b..81d2ad3d 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 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.
+In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Write one concise, non-empty `Layout pattern` suggestion in ordinary language; optionally cite stable ids from the layout library when they help recall a technique. 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.
§VIII `Layout pattern` is a per-resource preference. When a page uses several images, repeats one image in multiple views, or combines an image with native overlays, describe the page-level relationship and participating resources in §IX `Layout` / `Images`; do not duplicate an unchanged resource row merely to encode animation sequencing.
@@ -206,7 +206,7 @@ never write an empty or `none` placeholder:
- **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, a stock bent/curved Connector contour, 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, exact preset keys, endpoint/site metadata, or attachment promises. Executor chooses the actual basic primitive, preset, Boolean construction, or necessary freeform. 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. When it depends on visible image states, describe those fully revealed units in the same page's `Layout` / `Images`; the suggestion does not create missing visual content. 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.
+Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visualization; mark it data-driven when source values determine geometry. §IX stays authoritative without a catalog match and may choose a custom visualization or table. Add `Native shape suggestion` only when a preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name the semantic result plus candidate family or Boolean operands, never implementation geometry or keys. Executor chooses the primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` only when transition/reveal strengthens communication; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. Describe any required visible image states in `Layout` / `Images`; the suggestion creates no content and Executor may simplify or omit it unless the user explicitly requires motion. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; chart rows are 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 0142c32b..82bfdaac 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`. Use the canonical `images/<filename>` path; `source` and `crop` exactly project §VIII, while `pattern` preserves its ordered catalog ids or normalized custom prose. The pattern remains a recommendation for Executor recall, not a geometry or realization lock. Omit unplaced sheets.
+- `images`: `- <key>: <path> | source=<via> | pattern=<layout> | crop=<adaptive|no-crop>`; e.g. `- p04: images/a.png | source=user | pattern=full-height image beside the evidence | crop=no-crop`. Use the canonical `images/<filename>` path; `source` and `crop` exactly project §VIII, while `pattern` preserves its non-empty normalized free-form suggestion and any optional catalog ids. The pattern remains a recommendation for Executor recall, 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/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 40333710..d6983717 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -230,7 +230,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/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).
+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/layout suggestion/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:
@@ -252,7 +252,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
> 🔁 **Image facts are regenerated on change, never maintained as a second store.** `images/` is the live working folder and single source of truth; `analysis/image_analysis.csv` is its regenerated view. Run `analyze_images.py` before the first inventory read, then reuse that CSV while `images/` is unchanged. Re-run after import/acquisition or any user addition, removal, or replacement; an empty folder produces a fresh header-only CSV rather than leaving stale facts.
-> ⚠️ **Image understanding**: Do not bulk-open images. Strategist uses source context, captions / alt / titles, filenames, user notes, existing resource records, and `image_analysis.csv` first; only a specifically ambiguous asset may be inspected under [`strategist-image.md`](../references/strategist-image.md). Record the result in §VIII. Executor never reopens source images for semantic discovery or reselection.
+> ⚠️ **Image understanding**: Do not bulk-open images. Strategist starts from context, filenames, records, and `image_analysis.csv`; inspect only a specifically ambiguous asset under [`strategist-image.md`](../references/strategist-image.md), then record the result in §VIII. Under [`executor-image.md`](../references/executor-image.md), Executor may inspect one selected `Existing` / `Sourced` asset only to resolve crop, focal placement, or text contrast—never to reselect, replace, or infer provenance.
**Output**:
- `<project_path>/design_spec.md` — complete human-readable design narrative and durable confirmed production state
@@ -301,9 +301,9 @@ A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `we
> ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](../references/image-searcher.md) §5.
-> Web query boundary: keep §VIII `Reference` as the locked full subject/focal/crop intent; each `image_queries.json.query` is a separate 1–4 word concrete provider query. Search/review never rewrites the Design Spec or lock to fit a returned candidate.
+> **Default — short provider query (may override for a complete entity name or necessary disambiguation)**: keep §VIII `Reference` as the locked subject/focal/crop intent and author a separate concrete `image_queries.json.query`. Search/review never rewrites the Design Spec or lock to fit a candidate.
-> 💡 **ai path — spot illustrations as one sheet**: when the §VIII image resource plan needs ≥3 same-family spot illustrations as decorative accessories, generate **one grid sheet** (a single `ai` sheet row) instead of one row per element, then slice it (workflow step 2.5 below). Choose sheet geometry from intended placement: `1xN` / `Nx1` are useful for extreme portrait / landscape cells, and a designed `MxN` grid is valid when its cell ratio fits the planned elements. The sheet row is generated but not placed; each cut **element row** (`Acquire Via: slice`) is placed and must appear in `spec_lock.md images`. One generation = one coherent style across all pieces. Resource contract + the geometry rules: [image-generator.md](../references/image-generator.md) §4.3.
+> **Default — one sheet for compatible AI spots (may override for different cell shape, detail, quality, or semantics)**: prefer one grid sheet for a same-family set; independent `ai` rows remain valid. When selected, choose a grid matching the planned cells, keep the sheet unplaced, and place/project each `slice` row. Contract: [image-generator.md](../references/image-generator.md) §4.3.
> ⚠️ **Honor the Design Spec's confirmed image source before running any generation command**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — the production value recorded in `design_spec.md §I` wins. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. Never reopen `result.json` here, and never run `image_gen.py --manifest` when the recorded value is `host-native` or `manual`. Full selection rule: [image-generator.md](../references/image-generator.md) §7 Path Selection.
@@ -326,7 +326,7 @@ Workflow:
- [ ] **Next**: open a fresh chat window and input `继续生成 projects/<project_name>` to enter the execution session via the [`resume-execute`](stages/resume-execute.md) stage.
```
-> On acquisition failure, do NOT halt — follow the Failure Handling rule in [image-base.md](../references/image-base.md) §5: retry once, then mark the row `Needs-Manual`, report to user, and continue to the checkpoint above.
+> On acquisition failure, follow [image-base.md](../references/image-base.md) §5 without halting. Web rows continue through materially different query/provider/license/URL strategies; after exhaustion, mark `Needs-Manual`, report, and continue.
---
@@ -358,7 +358,7 @@ Read references/visual-styles/<resolved-id>.md # one preset id, or each `visu
| `pptx_structure.mode: structured` | `executor-structured.md` + `pptx-structure-interface.md` |
| Any data chart/table, including mini or inset charts and sparklines | `executor-chart.md` |
| Preset pattern or supported native chart/table | `native-data-interface.md` before drawing |
-| `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` |
+| `spec_lock.md images` / §VIII has an image/formula row, or the template has bundled images | `executor-image.md` + `image-layout-spec.md` + `svg-image-embedding.md`; add `image-layout-patterns.md` only for a cited `#<id>` or optional composition recall |
| 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 |
| §IX contains `Native shape suggestion`, or current page construction calls for a literal PowerPoint stock shape, a stock Connector contour, an explicit Merge Shapes operation or result, or a shape-built dimensional form (cylinder/pedestal, layered diagram, reflection, ground plane), or Executor is about to hand-author a freeform not already required by data geometry or the locked organic / hand-drawn style | `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 |
diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.md
index 7ab5dc50..8d438069 100644
--- a/skills/ppt-master/workflows/native-enhance-pptx.md
+++ b/skills/ppt-master/workflows/native-enhance-pptx.md
@@ -188,11 +188,12 @@ the 1-based `index` in `analysis/slide_index.json`:
| `effect: none` | Remove the visual transition; timings remain independently owned |
| `effect: preserve` | Preserve the source visual transition; narration timing may still update advance |
-An explicit `slides` entry selects a page even when it has no audio and
-`apply_without_audio` is false. With `transitions.enabled: false`, only listed
-pages opt in; unlisted pages preserve their source transition. Morph uses
-PowerPoint's automatic matching only—this route does not rename native objects
-to create deterministic pairs.
+An explicit `slides` entry always selects that page. With audio disabled,
+enabled transitions apply to every page; `apply_without_audio` is ignored. With
+audio enabled, that flag extends the global policy from narrated pages to all
+pages. If global transitions are disabled, only listed pages opt in; others
+preserve source transitions. Morph uses PowerPoint automatic
+matching; this route does not rename native objects for deterministic pairs.
**Hard rule — no silent downgrade**: a requested native effect must be written with its complete validated Effect Options. Unknown effects or inapplicable options fail; unknown source effects are preserved when the transition module is disabled.
@@ -305,10 +306,9 @@ python3 skills/ppt-master/scripts/native_enhance_pptx.py apply "<project>" \
--overwrite
```
-Without `--apply-transition-without-audio` (or the matching confirmed-plan
-field), the resolved enter policy is applied while processing slides with
-audio; slides without audio keep their source transition unless explicitly
-listed in `modules.transitions.slides`.
+`--apply-transition-without-audio` matters only with audio enabled: it extends
+the global enter policy from narrated slides to all slides. Explicit slide
+entries always opt in. Without audio, enabled transitions apply to every slide.
`apply` reruns the same source/readiness/plan checks as `validate`. Enabling
audio always requires every selected file to be decodable by ffprobe; enabling
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index 0a22ac22..ecb66443 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -80,13 +80,16 @@ author motion merely to expose a capability.
## 2. Rebuild Semantic Motion Groups When Needed, Then List IDs
-**Mandatory when object-targeted motion 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 or one continuing Morph object. Only a page-transition plan without
-explicit Morph pairs skips regrouping and group listing.
+**Mandatory when object-targeted motion is in scope — content-first grouping
+audit**: inspect each affected slide's visible content against its communication
+job and speaker flow before treating any top-level `<g>` as an animation
+anchor. The affected set is the page named by an adopted suggestion or explicit
+object-motion request, plus both endpoints of each deterministic Morph pair.
+Untouched pages need no animation audit. Existing groups are implementation
+evidence only. Keep a current group unchanged only after confirming that it
+already represents exactly one audience-facing reveal unit or one continuing
+Morph object. A page-transition-only plan without explicit Morph pairs skips
+regrouping and group listing.
| Content condition | Required grouping action |
|---|---|
@@ -159,7 +162,9 @@ Do not read the full scaffold unless it is needed as an editing starting point.
## 3. Plan Slide and Object Motion
-**Mandatory**: plan both page-level transitions and in-slide object animations before editing `animations.json`.
+**Mandatory**: plan the requested motion layers for each affected slide before
+editing `animations.json`. A local object-animation request does not require a
+deck-wide transition review.
| Layer | Config path | Use |
|---|---|---|
@@ -168,15 +173,23 @@ Do not read the full scaffold unless it is needed as an editing starting point.
| Page animation defaults | `defaults.animation` or `slides.<slide>.animation` | Control the default object-animation behavior for animated groups on a slide |
| Object overrides | `slides.<slide>.groups.<group_id>` | Control order, effect, delay, or duration for a real SVG group |
-**Per-page motion brief**: for each slide, first decide what communication job motion should perform—or that it should perform none—then decide transition effect, transition duration, object reveal sequence, object effects, and timing. Use `design_spec.md` for slide role, `spec_lock.md` for rhythm and visual style, speaker notes for narration order, and SVG group ids for target validity.
+**Per-affected-page motion brief**: decide what communication job the requested
+motion should perform—or that it should perform none—then choose only the
+relevant transition, reveal sequence, object effects, and timing. Use
+`design_spec.md` for slide role, `spec_lock.md` for rhythm and visual style,
+speaker notes for narration order, and SVG group ids for target validity.
-**Title reveal decision**: treat each real title as a first-class plan item.
-Choose static, immediate, delayed, synchronized, post-hero, or narration-cued
-behavior from slide intent. Use the sidecar override for a marker-free legacy
-chrome-like id; repair an incorrect explicit structural/static marker before
-animating it.
+**Title reveal decision**: when a title participates in the affected page's
+motion job, choose static, immediate, delayed, synchronized, post-hero, or
+narration-cued behavior from slide intent. Use the sidecar override for a
+marker-free legacy chrome-like id; repair an incorrect explicit
+structural/static marker before animating it.
-**Hard rule**: a custom animation pass must not only edit group effects. It must also decide whether each slide should inherit the default transition or need a slide-specific `transition` override. Inheritance is a complete decision; do not create slide-specific transitions to satisfy a variation quota.
+**Default — inherit unaffected motion layers (may override when the page's
+communication job requires it)**: a custom object-animation pass may leave the
+page transition and every untouched page on exporter or sidecar defaults. Add a
+slide-specific `transition` only when the affected page needs one; never add
+variation for coverage.
**Timing guidance**: use shorter motion for dense/repeated scan content and
longer motion for conceptual pivots, hero diagrams, section boundaries, and
@@ -261,30 +274,20 @@ one.
## 4. Edit `animations.json`
-**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
-overrides remain opt-in — list only the groups that genuinely diverge from
-the slide's `animation` block. Chrome groups stay out (the exporter pins
-them to `none` by default). Name a legacy chrome-like id only when the user
-explicitly wants that content animated and the SVG has no explicit structural
-layer, role, or placeholder marker.
-
-> Note: version-1 legacy sidecars may omit fields inside a listed slide under
-> the declared inheritance in [`animations.md`](../../references/animations.md) §2. This
-> workflow writes complete new slide blocks, and validation still requires
-> every current SVG stem to be present under `slides`.
-
-`defaults` is still required: it supplies the legacy inheritance baseline and
-the deck-wide values copied into every complete new slide block.
+**Hard rule — sparse overrides reference real targets**: write only affected
+slides and only fields that differ from exporter or sidecar defaults. An
+unlisted SVG inherits the resolved deck-wide settings; a listed slide may
+contain only `transition`, `animation`, `groups`, or `morph` fields that it
+actually overrides. `defaults` is optional and belongs only to intentional
+deck-wide settings. Group-level overrides remain opt-in. Chrome groups stay out
+(the exporter pins them to `none` by default). Name a legacy chrome-like id only
+when the user explicitly wants that content animated and the SVG has no
+explicit structural layer, role, or placeholder marker.
**Forbidden**:
-- Omitting a slide that exists in `svg_output/` — every produced slide must appear under `slides`
-- Writing a slide block with only `groups` and no `transition`/`animation`
+- Referencing a slide that does not exist in `svg_output/`
+- Referencing a missing, ambiguous, or structural group
- Enumerating every content group in a slide just to restate the slide-level default effect
- Listing a group with `data-pptx-layer` or an explicit static role/placeholder marker
- Listing a legacy chrome-like id without an explicit, reviewed intent to override the name heuristic
@@ -322,28 +325,19 @@ PowerPoint Speed; `accelerate`/`decelerate` own smooth start/end, so do not
invent duplicate fields. Change Font's `font_name` is one concrete
target-installed PowerPoint face, never a CSS font stack.
-**Canonical example — every slide carries explicit transition + animation;
-groups appear only when they diverge**:
+**Canonical sparse example — only the affected slide and divergent fields
+appear**:
```json
{
"version": 1,
- "defaults": {
- "transition": { "effect": "fade", "duration": 0.4 },
- "animation": { "effect": "entrance_fade", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" }
- },
"slides": {
- "01_cover": {
- "transition": { "effect": "fade", "duration": 0.5 },
- "animation": { "effect": "entrance_fade", "duration": 0.5, "stagger": 0.4, "trigger": "after-previous" }
- },
"03_market": {
"transition": {
"effect": "wipe",
"effect_options": { "direction": "left" },
"duration": 0.35
},
- "animation": { "effect": "entrance_fade", "duration": 0.4, "stagger": 0.25, "trigger": "after-previous" },
"groups": {
"chart": { "effect": "entrance_wipe", "effect_options": { "direction": "left" }, "order": 2, "duration": 0.6 },
"insight": { "effect": "entrance_fly", "effect_options": { "direction": "up_right" }, "order": 3, "delay": 0.2, "trigger_shape": "chart" }
@@ -353,9 +347,10 @@ groups appear only when they diverge**:
}
```
-`01_cover` shows a complete per-slide block even when values closely match
-the defaults. `03_market` lists only divergent groups. Structural chrome stays
-omitted unless a marker-free legacy name needs an explicitly reviewed override.
+Every unlisted page inherits the resolved defaults. `03_market` changes its
+transition and two real groups without restating a page animation block.
+Structural chrome stays omitted unless a marker-free legacy name needs an
+explicitly reviewed override.
Use the complete two-slide deterministic Morph example in
[`animations.md`](../../references/animations.md) §2.1; do not copy the source
@@ -425,7 +420,7 @@ renderer parameters but cannot replace the source effect. See
- [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] Sparse `animations.json` overrides are valid 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
diff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.md
index a33c22ec..5686ec3e 100644
--- a/skills/ppt-master/workflows/template-fill-pptx.md
+++ b/skills/ppt-master/workflows/template-fill-pptx.md
@@ -272,7 +272,17 @@ Run:
python3 skills/ppt-master/scripts/template_fill_pptx.py apply "<project_dir>/sources/<source.pptx>" "<project_dir>/analysis/fill_plan.json" -o "<project_dir>/exports/<output.pptx>"
```
-By default `apply` gives every cloned slide a `fade` transition (`0.5s`), preserving the v1 route contract. Override it with `--transition <effect>` using a canonical gallery effect from [`animations.md`](../references/animations.md) §3 and `--transition-duration <seconds>`; old names remain accepted only as compatibility CLI inputs. Pass `--transition none` for no visual motion, or `--transition keep` to preserve each source slide's existing transition unchanged. A per-slide `transition` field overrides the CLI and may include native `effect_options`; these require an explicit effect and are validated effect-by-effect. `advance_after` keeps click advance enabled and adds timed advance; it also works with `none` (timing-only transition) and `keep` (source effect preserved, Choice/Fallback timing updated together).
+By default `apply` preserves every cloned slide's existing transition. Select
+`--transition <effect>` to replace it with a canonical gallery effect from
+[`animations.md`](../references/animations.md) §3, and use
+`--transition-duration <seconds>` for the replacement duration; old names
+remain accepted only as compatibility CLI inputs. Pass `--transition none` for
+no visual motion. `--transition keep` states the default preservation policy
+explicitly. A per-slide `transition` field overrides the CLI and may include
+native `effect_options`; these require an explicit effect and are validated
+effect-by-effect. `advance_after` keeps click advance enabled and adds timed
+advance; it also works with `none` (timing-only transition) and `keep` (source
+effect preserved, Choice/Fallback timing updated together).
`apply` appends a timestamp automatically. For example, `-o "<project_dir>/exports/demo.pptx"` writes `demo_YYYYMMDD_HHMMSS.pptx`. If the filename already ends with `_YYYYMMDD_HHMMSS`, it is left unchanged.
@@ -288,7 +298,15 @@ The script:
| Adds timestamp to PPTX filename | Matches the main SVG-to-PPTX export convention |
| Drops orphaned source parts | Output carries only the selected pages and the layouts / media / charts they still reference (reachability prune) |
-**Animation policy**: Template-fill preserves each cloned slide's existing object animation XML (the SVG pipeline's generated object animation defaults are not applied here). Page transitions are the one motion layer this route writes directly, and `apply` adds a `fade` transition by default; change it with `apply --transition` / a per-slide `transition` field, or opt out with `--transition keep` (preserve source) or `--transition none`. `keep` preserves direct and `mc:AlternateContent` transition effects without converting unknown effects to `fade`; explicit replacement removes the old logical carrier before writing one new carrier. If the user asks to change object-level animation order / timing / effects, treat that as a separate direct-PPTX animation customization task.
+**Animation policy**: Template-fill preserves each cloned slide's existing
+object animation XML (the SVG pipeline's generated object animation defaults
+are not applied here). It also preserves source page transitions by default.
+Use `apply --transition` or a per-slide `transition` field only when the user
+requests a replacement or removal. `keep` preserves direct and
+`mc:AlternateContent` transition effects without converting unknown effects to
+`fade`; explicit replacement removes the old logical carrier before writing one
+new carrier. If the user asks to change object-level animation order / timing /
+effects, treat that as a separate direct-PPTX animation customization task.
---