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(native-shapes): move preset selection to authoring

hugohe3e792af0fd9a0
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.md
index 5503e8a0..a1cda2ee 100644
--- a/docs/rules/prompt-style.md
+++ b/docs/rules/prompt-style.md
@@ -102,8 +102,17 @@ Constraint strength and decision ownership are independent. Preserve this chain
| Layer | Owns |
|---|---|
| User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative |
-| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its research/provenance pair without expanding adopted webpage URLs; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages |
-| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring |
+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its research/provenance pair without expanding adopted webpage URLs; decide the approved content, resources, keys, identity anchors, and exact page roster; record only recommendations that affect content, resource preparation, sequencing, or explicit user/template constraints; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages |
+| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Discover and invoke local deterministic authoring capabilities without an upstream capability suggestion. Fields explicitly labeled `suggestion` or Reference remain preferred expression rather than binding selections when their owning contract permits adaptation. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring |
+
+**Hard rule — native shapes are authoring capabilities, not prepared
+resources**: a prepared resource needs a stable project-local file/path before
+realization because page authoring cannot acquire or generate it in place.
+Office presets, SVG primitives, Connectors, Boolean helpers, and necessary
+freeform geometry are locally callable construction capabilities. Strategist
+never selects, inventories, or suggests them, and the Design Spec / lock create
+no native-shape field. Executor discovers the complete current preset registry
+and chooses the page-fit construction during realization.
**Preparation timing**: In the default pipeline, topic research and import of
its two-artifact research pair may run before final confirmation. Facts JSON
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index e99841f1..e610fcdd 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -186,11 +186,10 @@ materialize that contour with Boolean semantics, and use freeform last. Block
arrows, chevrons, banners / ribbons, callouts, flowchart nodes, stars, and other
Office symbols use `preset_shape_svg.py`, not plain paths or fake rectangles.
-§IX `Native shape suggestion` records a semantic opportunity, not a literal
-tool command. Decide from the actual page construction which page-fit native
-contour and simplest exact authoring form, independent compound construction,
-Boolean result, or necessary freeform best realizes it; a different
-implementation is valid when it preserves the intended object and content.
+Before the first page, complete [`native-shape-authoring.md`](./native-shape-authoring.md)'s
+unfiltered full-registry discovery. Decide every page-fit contour and its
+simplest exact authoring form directly from the page content and visual system;
+no Design Spec capability suggestion or material inventory gates this choice.
**Mandatory — independent per-page compound-shape decision**: after the
Structure result and any applicable topology resolve, decide whether two or more
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index 1d24657b..c648f848 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -12,6 +12,20 @@ only when those constructions fail. Neither helper writes a page. The preset
helper does not create the shape's own `p:txBody`; keep visible text outside the
atomic fragment.
+**Mandatory — complete registry discovery at authoring entry**: before the
+first newly authored page or template contour in each valid context, run the
+following command unfiltered and retain its complete output (currently 187
+names). This is authoring-time capability discovery, never a Strategist task or
+Design Spec field. Rerun only after context invalidation or a registry change.
+
+```bash
+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list
+```
+
+Choose from that full inventory by page job. Use `list --search` only to narrow
+the already-read inventory and `describe <name>` only after identifying a
+candidate; neither replaces the complete initial read.
+
## 1. Contour Selection and Materialization Gate
**Hard rule — contour before encoding**: choose the page-fit contour from the
@@ -45,10 +59,10 @@ rerun the helper whenever its geometry, paint, or filter reference changes.
## 2. Semantic Preset Candidate Guide
-Use the table below as a high-frequency entry, not a whitelist: match the
-page's visual intent to a candidate contour before settling on a neutral
-rectangle / ellipse or a freeform path. Search the registry when the job calls
-for a more specific contour rather than letting authoring convenience decide.
+Use the table below as semantic navigation, not a shortlist: match the page's
+visual intent against the complete inventory already loaded above before
+settling on a neutral rectangle / ellipse or a freeform path. Do not let the
+examples or authoring convenience hide a more specific registered contour.
"Automatic" means the Executor independently applies this semantic decision
gate before drawing a new object. It does not scan existing SVG, classify
@@ -65,7 +79,7 @@ paths or contours, or upgrade ordinary SVG during export.
| Standalone math symbol | `mathPlus`, `mathMinus`, `mathMultiply`, `mathDivide`, `mathEqual`, `mathNotEqual` | Use only when the symbol itself is a diagram shape; simple notation remains text, while non-trivial inline or block mathematics follows [`native-formula.md`](./native-formula.md). |
| Literal Office symbol | `heart`, `sun`, `moon`, `lightningBolt`, `gear6`, `gear9` | Never replace an icon required by `spec_lock.icons`. |
-Use registry search for a less common literal shape:
+Narrow and inspect candidates from the already-loaded inventory:
```bash
python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list --search arrow
@@ -278,9 +292,9 @@ freshness contract.
**Trigger**: Current page construction has two or more supported shape/text operands
whose faithful result calls for PowerPoint-style Union, Combine, Fragment,
-Intersect, or Subtract. A §IX `Native shape suggestion` is a semantic candidate,
-not a prerequisite or tool command; Executor may adopt, adapt, or decline it
-from the actual content and explicit user/template constraints.
+Intersect, or Subtract. Executor decides this directly from the actual content,
+complete native inventory, and explicit user/template constraints; no upstream
+suggestion or planning field is required.
```bash
python3 ${SKILL_DIR}/scripts/shape_boolean_svg.py render <svg-file> \
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 33001a74..0da37af4 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -58,7 +58,7 @@ Do not force communication intent into one catalog label; Stage 1 records compos
| Reference | Preserve the selected direction or role; adapt its realization to context. |
| Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. |
-**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, page-local visualization/Layout references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Topic research and import of its two-artifact research pair may precede confirmation; facts URLs are not auto-expanded. Only after normal image search fails may one adopted webpage become a reviewable Markdown + companion-image source package, with accepted files promoted individually. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
+**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, semantic relationships, prepared resources/paths, Chart/Table and structured-template routing references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Topic research and import of its two-artifact research pair may precede confirmation; facts URLs are not auto-expanded. Only after normal image search fails may one adopted webpage become a reviewable Markdown + companion-image source package, with accepted files promoted individually. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Locally callable native construction is an Executor capability—not a resource or planning output. Executor owns its discovery and selection plus geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement.
@@ -348,18 +348,19 @@ The module owns AI rendering alternatives, acquisition paths, resource rows, pro
**Per-page capability recall**: Before §IX, consider this menu without a usage
quota. Use existing fields for semantic intent; omit unused lines and
-implementation parameters. Executor may adapt/decline the
-two non-literal suggestions while preserving content and intent; explicit
-user/template requirements bind.
+implementation parameters. Executor may adapt/decline a `Motion suggestion`
+while preserving content and intent; explicit user/template requirements bind.
-**Reference — carriers compose, not compete**: Any page may combine a suitable subset of background paint, native shapes, editable text, photos/scenes, transparent illustration elements, decorative lettering, icons, and visualizations. Select only what improves communication and composition; outside explicit requirements, no carrier is mandatory or mutually exclusive.
+**Hard rule — native construction stays downstream**: record the page's
+semantic relationships and any prepared resource roles; add no native-
+construction recommendation. Executor independently discovers and selects local
+construction from the actual page content and visual system.
| 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, apply the already-loaded [`strategist-image.md`](./strategist-image.md) resource contract plus the conditional image-layout references, record a concise §VIII `Layout pattern` suggestion, and describe page-level image/overlay relationships in §IX `Layout` / `Images` |
| Composable illustration family | One or more pages benefit from coherent reusable title/corner ornaments, dominant anchors, supporting figures, compact illustrated-icon cues, or accents that can mix with text, shapes, photos, or lettering | Apply [`strategist-image.md`](./strategist-image.md): plan transparent elements by compatible family, record fixed reuse or adaptive variation in §VIII `Reference`, and describe each used page's carrier 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 system / Merge Shapes | A page field, outline carrier, visual nesting, literal Office symbol, stock bent/curved contour, or compound silhouette/cutout/overlap region strengthens the visual idea | Add an optional §IX `Native shape suggestion` with the semantic geometry jobs and relationship; identify independent atom roles, a candidate preset/Connector family, or Boolean operation/operands only where useful |
| AI decorative lettering asset | Any stable display string in the deck — including a complete long or multi-line title, cover hook, chapter word, place or product name, dish or exhibit name, year, hero number, pull quote, or motif word — reads better with a material, dimensional, hand-rendered, or otherwise illustrative treatment than as ordinary text | Apply [`strategist-image.md`](./strategist-image.md): preserve every complete exact string, group compatible marks when useful, and keep chrome/body as native text. The lettering asset may carry the complete long or multi-line title as its display layer; keep an ordinary native title/subtitle in a separate text frame wherever the page needs a searchable, selectable, or outline-visible heading. Never shorten copy to make it look more like a wordmark |
| 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 initial state → action → end state; leave effect, ids, pairing names, and timing to Executor |
| Object animation | Progressive reveal, emphasis, movement, removal, or deliberate stillness clarifies sequence, causality, comparison, hierarchy, narration order, full-view → detail, atmosphere → evidence, or hotspot/annotation order | Add an optional §IX `Motion suggestion` naming each relevant semantic unit's lifecycle duty and initial state → communication action → end state, plus any meaningful order/relationship; leave group ids, effects, options, and timing to Executor |
@@ -427,19 +428,6 @@ Correct failed selections by recall; `no-template-match` never enters `page_visu
| P03 | chart | line_chart | Compare the source metrics over time |
```
-**Native-geometry candidate detail**: Add `Native shape suggestion` when a
-page-level field, boundary, direction, reveal, visual nesting, literal stock
-shape, or stock bent/curved Connector contour may strengthen the page. Describe
-the semantic jobs and whether atoms should remain independent, not coordinates,
-an exact preset key, endpoint/site metadata, or attachment promises. Only when
-one contour, cutout, common region, or meaningful fragmentation is intended,
-name the candidate Union / Combine / Fragment / Intersect / Subtract operation,
-semantic operands, and result.
-Executor still decides the exact page-fit native contour and authoring form,
-independent compound construction, Boolean result, or necessary freeform under
-its native-shape branch; the recommendation never creates a §VII row or lock
-field.
-
### Speaker Notes Requirements
Resolve the effective Speaker Notes outcome from the latest explicit user
diff --git a/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md b/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md
index 7884115d..1c610eaf 100644
--- a/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md
+++ b/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md
@@ -10,13 +10,14 @@ a test file or public example deck.
The fixture deliberately closes the full planning and execution chain:
-- `design_spec.md` carries `Motion suggestion`, `Native shape suggestion`, one
- current §VIII image row, and `Crop Policy`;
+- `design_spec.md` carries `Motion suggestion`, one current §VIII image row,
+ and `Crop Policy`, with no native-shape planning field;
- `spec_lock.md` projects that row with optional layout pattern `#M1-11`;
- both pages reuse one raster through ordinary, ellipse-preset, and custom-path
independent nested crops;
- `animations.json` pairs the main crop across adjacent Morph pages;
-- one helper-authored `rightArrow` verifies native preset discovery and export.
+- one complete registry read plus a helper-authored `rightArrow` verifies
+ Executor-local native preset discovery and export.
```bash
python3 - <<'PY'
@@ -68,6 +69,10 @@ draw.rectangle((860, 0, 1280, 720), fill="#0F172A")
draw.ellipse((460, 150, 820, 510), fill="#F8FAFC")
scene.save(images / "scene.png")
+preset_inventory = run_tool("preset_shape_svg.py", "list").splitlines()
+assert len(preset_inventory) == 187
+assert "rightArrow" in preset_inventory
+
preset = run_tool(
"preset_shape_svg.py",
"render",
@@ -139,12 +144,11 @@ preset = (
#### Slide 01 - Overview
- **Audience move**: See separate source views as one editable image system.
-- **Layout**: Ordinary crop, shaped crop, and one native directional preset.
+- **Layout**: Ordinary crop and shaped detail establish the first visual state.
- **Title**: Overview crop state
- **Core message**: One source can support independent native picture objects.
- **Content**: Show the wide crop and shaped detail together.
- **Images**: Use `scene.png` for both visible crop objects.
-- **Native shape suggestion**: Use the PowerPoint `rightArrow` preset to indicate continuation.
- **Motion suggestion**: Continue the primary crop into Slide 02 as one deterministic Morph object.
#### Slide 02 - Detail
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 5bc82d2e..eb05d069 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -220,15 +220,14 @@ When an explicit final/literal narration script will become notes or generated
audio, make §X `Content` name that source and say `preserve verbatim`; keep the
full segmented script in `notes/total.md`, not in §IX or this Design Spec.
-Append either or both optional lines only when the capability earns a place;
-never write an empty or `none` placeholder:
+Append the optional line only when the capability earns a place; never write an
+empty or `none` placeholder:
```markdown
-- **Native shape suggestion**: <semantic page/object geometry jobs plus independent atom roles, candidate preset/Connector family, or Boolean operation/operand roles as applicable>
- **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order>
```
-Add `Mathematical content` whenever a Slide needs a mathematical expression preserved exactly. Store the expression body as valid LaTeX without `$...$`, `$$...$$`, `\(...\)`, or `\[...\]` source delimiters; the field does not classify inline versus structural use. This is content authority for [`native-formula.md`](../references/native-formula.md), not a formula policy, marker, or implementation request; Executor chooses ordinary text, inline native math, or block native math. Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visual model. Name every value-driven geometry, qualitative relationship, cell grid, and child visual here; only independent Chart/Table entries use object keys. Describe qualitative order, linkage, hierarchy, grouping, contrast, overlap, and reading path freely—not as a model name or grammar enum. §IX may choose a custom Chart/Table fallback. Add `Native shape suggestion` only when a page-level shape system, preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name semantic geometry jobs and relationships plus independent atom roles, a candidate family, or Boolean operands as applicable, never implementation geometry or keys. Executor chooses the page-fit native contour and exact authoring form, independent compound construction, Boolean result, or necessary freeform. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add keyed `Native-ready` 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; §VII Chart/Table rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
+Add `Mathematical content` whenever a Slide needs a mathematical expression preserved exactly. Store the expression body as valid LaTeX without `$...$`, `$$...$$`, `\(...\)`, or `\[...\]` source delimiters; the field does not classify inline versus structural use. This is content authority for [`native-formula.md`](../references/native-formula.md), not a formula policy, marker, or implementation request; Executor chooses ordinary text, inline native math, or block native math. Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visual model. Name every value-driven geometry, qualitative relationship, cell grid, and child visual here; only independent Chart/Table entries use object keys. Describe qualitative order, linkage, hierarchy, grouping, contrast, overlap, and reading path freely—not as a model name or grammar enum. §IX may choose a custom Chart/Table fallback. Native construction creates no Design Spec field; Executor discovers and selects it independently during realization. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add keyed `Native-ready` 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; §VII Chart/Table 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/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 7dc74d52..d965028e 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -652,7 +652,7 @@ sidecars, or guessed family paths.
**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`
-Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Treat §IX `Native shape suggestion` as a candidate, not a command: inspect the actual page construction, then follow [`native-shape-authoring.md`](../references/native-shape-authoring.md) — choose page-fit contours from the full native vocabulary before their authoring forms, keep exact native atoms independent when possible, materialize a Merge Shapes Boolean result only where contour semantics require it, and use necessary freeform last. Diagram relationships follow the same Shape-first gate; do not infer a preset from contour similarity.
+Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Native shapes are Executor-local authoring capabilities, not planned resources: follow [`native-shape-authoring.md`](../references/native-shape-authoring.md), load its complete current preset inventory before the first page, choose page-fit contours before their authoring forms, keep exact native atoms independent when possible, materialize a Merge Shapes Boolean result only where contour semantics require it, and use necessary freeform last. Diagram relationships follow the same Shape-first gate; do not infer a preset from contour similarity.
**Motion-ready image composition**: Only when an explicit user motion
instruction, the effective Custom Animations outcome in `design_spec.md §I` is