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(prompts): dogfood follow-ups — downscale as a derivative, role-family fallback, CJK lettering check

hugohe3895166c52cf9
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 504de0c2..691f70f3 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -202,7 +202,7 @@ The result stays information-equivalent: the `Core message`, `Audience move`, an
- **Icons**: any SVG prepared under `<project_path>/icons/` is usable. `icons.library` records the primary bundled style; `icons.inventory` indexes the synced pool without assigning icons to pages or limiting other project-local assets; `simple-icons` entries are real brand marks, not a library. Illustrated icons are transparent slices under `images/` and follow [`executor-image.md`](./executor-image.md) — never moved into `icons/`, added to the inventory, or rendered through `<use data-icon>`.
- **Colors**: core roles keep their meaning. Derive tints, shades, alpha, gradients, and effects; preserve natural asset colors; use sparse page-local accents that never become a competing or recurring palette.
- **Spacing**: §V anchors (page margin, block gap, column gutter, corner radius, body leading) are deck-wide identity. Depart only for a page job, never to make content fit.
-- **Families**: resolve by role — exact `<role>_family`, then `title_family` / `body_family`, then legacy `font_family`; never flatten a declared override. A sparse export-safe accent family may style short non-structural display or ornament only; recurrence needs upstream selection.
+- **Families**: resolve by role — exact `<role>_family`, then `title_family` / `body_family`, then legacy `font_family`; never flatten a declared override. A role with no `<role>_family` of its own uses `body_family`; `title`, `subtitle`, and chapter-numeral roles use `title_family`. A sparse export-safe accent family may style short non-structural display or ornament only; recurrence needs upstream selection.
- **Sizes**: map every structural text item to a declared `typography` role and write its anchor or a value within `±2` px, as unitless px with at most two decimals. Peers on one page stay consistent, and bounded adjustment creates no new role. Never inherit a template placeholder size. `lead` / `subtitle` carry the page's primary claim; `footnote` / `annotation` carry footnotes, page numbers, and credits.
- **Sparse display-size exception**: a short non-structural Hero/Display element may use one undeclared size at most twice across the deck without a lock row. The third occurrence makes it recurring: stop, return to Strategist to name the role in the Design Spec and lock, then read back and validate before reuse. Never for titles, body, subtitles, annotations, footnotes, captions, data labels, or card copy, and never imitated with nearby sizes.
- **Outside-band recovery**: structural text reflows geometry and uses the declared band; a sparse display occurrence keeps its value while its deck-wide count stays ≤2. Never flatten a justified distinction or add a role to silence the checker. Mirror pages keep exact source typography.
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
index a9c0d20f..985c3513 100644
--- a/skills/ppt-master/references/image-base.md
+++ b/skills/ppt-master/references/image-base.md
@@ -27,7 +27,7 @@ Classify `Reference: Derived from <canonical bare filename>; treatment=<operatio
An all-`web` deck never reads `image-generator.md`, and vice versa.
-**Mandatory — consume the resolved treatment path**: this phase never adds or reselects a treatment. `none` uses the canonical bitmap; `native` creates no file (SVG owns crop/clip, transform, opacity, frame/shadow/scrim/vignette, overlap); `prepared derivative` is a separate file only for pixel blur, desaturation/grayscale, duotone, brightness/contrast, or existing cutout/registered-layer preparation. Never bake a native treatment into a derivative.
+**Mandatory — consume the resolved treatment path**: this phase never adds or reselects a treatment. `none` uses the canonical bitmap; `native` creates no file (SVG owns crop/clip, transform, opacity, frame/shadow/scrim/vignette, overlap); `prepared derivative` is a separate file only for pixel blur, desaturation/grayscale, duotone, brightness/contrast, downscaling to the planned on-slide size (`image_treat.py --fit WxH`, never upscaling), or existing cutout/registered-layer preparation. Never bake a native treatment into a derivative.
**Reference — pattern → preparation (an adopted id creates nothing by itself)**: `P*` / `M*` / `C*` use existing assets with native composition; `A1-02` / `A1-03` → `image_treat.py` blur / duotone; `A1-01` / `A1-04` → an existing composite or the host/AI path (`image_treat.py` does not blend); `A2-01` → an existing RGBA or flat-key AI/slice asset (with `A2-02` / `A2-03` + §4.4 when scene registration is required); `A2-02` / `A2-03` → §4.4 registered layers; `A2-04` → an existing transparent frame/device asset plus a content picture registered beneath it; `A3-01` → original/subject plus a registered `image_treat.py` derivative; `A3-02` → a registered full-canvas blur derivative with native crop panels; `A3-03` → a desaturated base plus an existing/§4.4 color subject layer.
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index b5da1fa7..6f821bbf 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -237,7 +237,7 @@ Match facial detail, anatomy, texture, and realism to the rendering and the row'
**Hard rule — decide by editability, not model capability**: Layer 1 text can never be edited, corrected, searched, restyled, or reflowed. Text that is part of the artwork and stable — decorative lettering, a wordmark, a hand-lettered phrase, figure-internal identifiers — may be Layer 1. Anything that must stay exact, searchable, editable, or may be reworded is Layer 2, whatever `text_policy` says: authoritative titles, chrome, navigation, footer, bullets, captions, data values. Bake title-like wording only when the approved plan treats those exact characters as stable artwork. When the headline must stay editable, use Primitive D and overlay it.
-**Hard rule — never pre-judge by script or length**: never push text to SVG, shorten a headline, or downgrade `embedded` to `none` on the assumption that a script or long string "won't render"; a multi-word phrase or two-line lockup qualifies exactly as one word does. Name the exact characters literally; do not re-read the generated image to verify them.
+**Hard rule — never pre-judge by script or length**: never push text to SVG, shorten a headline, or downgrade `embedded` to `none` on the assumption that a script or long string "won't render"; a multi-word phrase or two-line lockup qualifies exactly as one word does. Name the exact characters literally; do not re-read the generated image to verify them. Exception — CJK lettering: when `text_policy: embedded` and the string contains CJK characters, one look at the generated file is allowed, answering only whether the characters match the approved string exactly; a mismatch regenerates that item, and the look never reopens selection or taste.
**Reference — controlled, deck-aligned artistic authorship** (high expression on user request or a confirmed direction): give the model the exact string, communication role, placement/background relationship, deck identity, relative weight, and desired energy; the rendering, semantic colors, mood, and page hierarchy define the envelope. Glyph-native expression carries identity through silhouette, stroke construction, internal material/texture, contour-bound depth and light, and composition. Literal topic illustrations or detached decoration compete with the glyph; a lettering-plus-illustration lockup needs an explicit request or confirmed direction. Within the treatment let the model combine or omit gesture, material, dimensionality, texture, lighting, and hierarchy — possibility space, not a recipe. Never flatten the art to ease extraction (§4.3's gates protect delivery); when fit is uncertain use the lower density; keep a multi-line lockup as one element when its hierarchy is part of the art.
@@ -307,7 +307,7 @@ Write `project/images/image_prompts.json`:
| `items[].type` | no | One of the 11 internal-composition types for a local structural infographic when a template genuinely fits; omitted for §4.1 E prose, `hero_page`, sheets, and single-subject/portrait |
| `items[].page_role` | yes | `local` (default) or `hero_page` |
| `items[].text_policy` | yes | `none` or `embedded`, judged per image (§5.3) |
-| `items[].aspect_ratio` | yes | Passed to `image_gen.py --aspect_ratio` |
+| `items[].aspect_ratio` | yes | Passed to `image_gen.py --aspect_ratio`; every backend accepts a subset of the CLI union (e.g. gemini has no `3:1`), and `--manifest` fails the item before any request when the resolved backend rejects its ratio |
| `items[].prompt` | yes | The assembled paragraph |
| `items[].image_size` | no | `512px` / `1K` / `2K` / `4K` |
| `items[].model` | no | Per-item backend model override |
@@ -349,7 +349,7 @@ Prerequisite: §3 complete and `images/image_prompts.json` validates. The manife
python3 scripts/image_gen.py --manifest project/images/image_prompts.json --output project/images
```
-Validates the file behind every `Generated` row before skipping it, iterates retryable rows with bounded concurrency, and writes each status atomically. Interrupting is safe (completed items stay `Generated`), and `--render-md` refreshes the Markdown sidecar after an interruption. Backend selection, `.env` lookup order, provider keys, and the OpenAI-compatible knobs: [`image.md`](../scripts/docs/image.md). The single-image form `image_gen.py "prompt" --filename …` remains for ad-hoc re-rolls.
+Validates the file behind every `Generated` row before skipping it, iterates retryable rows with bounded concurrency, and writes each status atomically. Interrupting is safe (completed items stay `Generated`), and `--render-md` refreshes the Markdown sidecar after an interruption. Backend selection, `.env` lookup order, provider keys, and the OpenAI-compatible knobs: [`image.md`](../scripts/docs/image.md). The single-image form `image_gen.py "prompt" --filename …` remains for ad-hoc re-rolls. Backends return their own native resolutions: backfill the actual pixels into `Dimensions`, and when a file is far larger than its planned on-slide size, downscale it to that size as a prepared derivative (`image_treat.py --fit WxH`); never upscale.
### Path B — host-native image tool
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index 1dbf66ef..e37d5449 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -21,7 +21,7 @@ python3 ${SKILL_DIR}/scripts/shape_boolean_svg.py render <svg-file> \
- `render` prints one compact atomic `<g data-pptx-authoring="preset">` with preset, frame, adjustments, and base paint written once and registry-generated visible paths as children; **Hard rule — batch after selection**: after selecting two or more objects for one page or template, use `render-batch --input -` so their independent fragments are validated and emitted in one stdout round. `--frame x y w h` is in the coordinate space where the fragment is inserted (group-local inside a `<g transform>`). Insert the fragment unchanged through the normal page edit; never redirect helper output into `svg_output/`.
- Paint accepted: `none` or six-digit solid HEX fill/stroke, optional channel opacity, stroke width, cap, join, and one shape-only filter id. Gradient or pattern paint stays ordinary SVG. Connector-family presets require `--object-kind connector`, `--fill none`, and a visible stroke, and export as unconnected `p:cxnSp`.
-- **Hard rule — atomic and helper-owned**: never write `data-pptx-prst`, frame, adjustment, or registry paths by hand, never edit a direct path, and rerun the helper when preset, frame, adjustment, paint, or filter changes. Keep the fragment top-level without `data-pptx-bounds` when standalone (its `data-pptx-frame` owns geometry); put labels or decorations beside it in a separate bounded parent group, never inside. Moving, scaling, rotating, or flipping the whole group is fine; zero-scale and shear are not, the transformed frame stays inside DrawingML's coordinate range, and stroke width stays inside its line-width range. Keep the helper's exact space-separated ordinary-decimal `data-pptx-frame` spelling; compact authoring accepts no alternate numeric spelling. Keep paint and opacity off ancestor groups (the checker warns).
+- **Hard rule — atomic and helper-owned**: never write `data-pptx-prst`, frame, adjustment, or registry paths by hand, never edit a direct path, and rerun the helper when preset, frame, adjustment, paint, or filter changes. Keep the fragment top-level without `data-pptx-bounds` when standalone (its `data-pptx-frame` owns geometry); put labels or decorations beside it in a separate bounded parent group, never inside. Moving, scaling, rotating, or flipping the whole group is fine; zero-scale and shear are not, the transformed frame stays inside DrawingML's coordinate range, and stroke width stays inside its line-width range. Keep the helper's exact space-separated ordinary-decimal `data-pptx-frame` spelling; compact authoring accepts no alternate numeric spelling. Keep paint and opacity off ancestor groups (the checker warns). Helper output may contain consecutive duplicate vertices (`L 440 449.33 L 440 449.33`); they are the registry path as printed and stay untouched — cleaning them up is an edit to a direct path and fails the check.
- `shape_boolean_svg.py` consumes closed `path` / `polygon` / `rect` / `circle` / `ellipse`, one unfiltered compact preset, or supported horizontal direct `<text>` with a resolvable OpenType face (`--font-dir` adds roots; text becomes glyph geometry). The first `--source` supplies result paint and explicit paint flags override only their named channels; for `subtract` every later operand is removed from it. Coordinates are baked into root space: insert the stdout paths at the primary operand's z-order with no extra transform. `union` / `combine` / `intersect` / `subtract` emit one `<path>`; `fragment` emits `<id>-1`, `<id>-2`, … in top/left/bottom/right/area order, each a separate shape. Results use nonzero winding and never `fill-rule`, `clip-rule`, `clip-path`, `mask`, or Merge Shapes metadata; operands that depend on even-odd fill, clipping, or masking fail closed. Never use it on mirror/preserve source structure.
**Mandatory — complete vocabulary before contour selection**: [`preset-shape-vocabulary.md`](./preset-shape-vocabulary.md) is read completely before contour work (Generate: with the executor core before the first page; Create Template: as soon as `replication_mode` resolves to `standard` or `fidelity`; never for `mirror`); a filtered lookup cannot replace it. Reread only after context invalidation or a known file change.
diff --git a/skills/ppt-master/references/plan-core.md b/skills/ppt-master/references/plan-core.md
index 457bb5d3..3bbe7314 100644
--- a/skills/ppt-master/references/plan-core.md
+++ b/skills/ppt-master/references/plan-core.md
@@ -180,7 +180,7 @@ python3 skills/ppt-master/scripts/visualization_recall.py validate \
| Annotation | 0.7–0.85× |
| Footnote / page number | 0.5–0.65× |
-Scan the roster before fixing anchors and declare every recurring role (`lead` at least body size; `footnote`; chart annotations when used), one deck-wide anchor each, snapped to clean even px (body 24 → title 42, subtitle 32, lead 30, annotation 18, footnote 16). Executor's ±2 px band and its two-occurrence display exception are [`executor-base.md`](./executor-base.md) §2.1; declare every recurring role so no structural text depends on that exception.
+Scan the roster before fixing anchors and declare every recurring role (`lead` at least body size; `footnote`; chart annotations when used; and the display roles the `anchor` page count makes recurring — chapter numerals, hero numbers), one deck-wide anchor each, snapped to clean even px (body 24 → title 42, subtitle 32, lead 30, annotation 18, footnote 16). Executor's ±2 px band and its two-occurrence display exception are [`executor-base.md`](./executor-base.md) §2.1; declare every recurring role so no structural text depends on that exception.
### 6.3 Icons
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index e186c72f..c6f41466 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -63,6 +63,9 @@ Useful options:
- Unknown backend-specific flags are passed through to each selected converter.
- `-o/--output` selects one Markdown file for one input, or an output directory
for multiple inputs / directory inputs.
+ A path that names an existing directory, or ends in `/`, is always treated as
+ a directory, even for a single input: the file keeps its default `<stem>.md`
+ name inside it.
For multi-source project intake, use `project_manager.py import-sources` with
all source paths / URLs. For local files, the default is to keep generated
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index c248c4ab..c75bd235 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -170,11 +170,15 @@ python3 scripts/image_treat.py projects/demo hero.jpg \
python3 scripts/image_treat.py projects/demo hero.jpg \
--output hero_duotone.png --duotone "#14213D" "#FCA311"
+
+python3 scripts/image_treat.py projects/demo title_art.png \
+ --output title_art_fit.png --fit 920x228
```
Supported operations are brightness, contrast, desaturation/grayscale,
-duotone, and Gaussian blur. They compose in a fixed order: brightness →
-contrast → tone treatment → blur. Desaturation, grayscale, and duotone are
+duotone, Gaussian blur, and `--fit WxH` (downscale to fit inside a pixel
+box, aspect ratio and alpha preserved; never upscales). They compose in a
+fixed order: brightness → contrast → tone treatment → blur → fit. Desaturation, grayscale, and duotone are
mutually exclusive. At least one option must produce a real change; animated
or multi-frame sources are rejected rather than reduced to one frame.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index a826927f..73393922 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -1947,7 +1947,7 @@
{
"path": "skills/ppt-master/references/executor-base.md",
"role": "consumer",
- "fingerprint": "3c3185729190",
+ "fingerprint": "7e5a0d00892e",
"reason": "This consumer needs the field contract for deterministic execution."
},
{
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 15533d58..ec1902fe 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -195,7 +195,7 @@ Read ${SKILL_DIR}/references/image-base.md # always
| Row | Additional reference | Run |
|---|---|---|
-| Prepared derivative | `image-generator.md` §4.4 only for registered layers | after its canonical source is terminal: `python3 ${SKILL_DIR}/scripts/image_treat.py ...` for blur, desaturation/grayscale, duotone, brightness, or contrast, or the §4.4 preparation path |
+| Prepared derivative | `image-generator.md` §4.4 only for registered layers | after its canonical source is terminal: `python3 ${SKILL_DIR}/scripts/image_treat.py ...` for blur, desaturation/grayscale, duotone, brightness, contrast, or `--fit WxH` downscaling to the planned size, or the §4.4 preparation path |
| `ai` | `image-generator.md` | write `images/image_prompts.json`, render `image_prompts.md` with `image_gen.py --render-md`, then follow §7 Path Selection — `image_gen.py --manifest` is Path A only, `host-native` is Path B and skips `--manifest`, `manual` writes prompts and stops; the recorded `design_spec.md §I` path wins over `IMAGE_BACKEND` |
| `web` | `image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...`; with ≥2 rows write `images/image_queries.json` and run `--batch` once |
| `slice` | `image-generator.md` §4.3 | after the parent sheet is `Generated`: `python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha --bg KEY_HEX_FROM_PROMPT --strict-alpha` |
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index 98ec7cf1..b7daf70b 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -238,7 +238,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --quick-generate --no
- [x] The frozen Template Application paragraph was applied, every installed Layout/Deck SVG was read, and structure matches the installed capability (flat vs explicit all-page structured)
- [x] The early gate ran once after P05 on a roster of seven or more pages (or a shorter roster skipped it), and every checker invocation followed a gate point or one consolidated repair pass
- [x] The carrier receipt was compared with the retained page jobs and contradictions repaired; the lockless final report passes and matches the current SVGs
-- [x] Enabled notes were validated/generated and split; enabled custom motion ran through its owning stage
+- [x] The §1 motion gate was evaluated before P01 (the row hit, or none); enabled notes were validated/generated and split; enabled custom motion ran through its owning stage
- [x] One native PPTX exists under `exports/` or the explicit output path; no Strategist, confirmation, root Design Spec, or lock artifact was created
- [ ] **Next**: report the base PPTX and any narrated PPTX, MP4, or capture-ready handoff, plus the resolved mode, visual style, and image sources actually used; for every no-AI replan, report the affected job, attempted path, concrete error, replacement carrier, and that retaining AI imagery requires repairing generation capability and a new Quick run
```