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

refactor(prompts): state the custom-basis and template-boundary rules once

hugohe307f80c30038f
diff --git a/AGENTS.md b/AGENTS.md
index 888818b2..dfa9be24 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,57 +56,22 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate
Convenience summary only — route selection starts in [`SKILL.md`](skills/ppt-master/SKILL.md). Image to PPTX always uses [`quick-generate.md`](skills/ppt-master/workflows/profiles/quick-generate.md); Beautify uses it only when Quick is explicit, otherwise [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md).
```bash
-# Source content conversion
-python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]
-
-# Project management
-# Add --format <registered_format> only for an exact registered canvas.
-python3 skills/ppt-master/scripts/project_manager.py init <project_name>
-python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...>
-python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path> # optional manual helper
-python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path> # optional manual helper
+python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [...] # source conversion
+python3 skills/ppt-master/scripts/project_manager.py init <project_name> # --format only for an exact registered canvas
+python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <sources...>
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>
-
-# Icon selection — copy chosen library icons into <project>/icons/ (missing names reported + non-zero = re-pick)
-python3 skills/ppt-master/scripts/icon_sync.py <project_path> <lib/name> [<lib/name>...]
-
-# Sounds — after a concrete cue job, read the complete vocabulary:
-# skills/ppt-master/templates/sounds/sound-vocabulary.md
-# list is optional exact filtering
-python3 skills/ppt-master/scripts/sound_sync.py list [--query term]
-python3 skills/ppt-master/scripts/sound_sync.py <project_path> <namespace>/<id>...
-
-python3 skills/ppt-master/scripts/confirm_ui/server.py <project_path> --daemon
-python3 skills/ppt-master/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1
-
-# Image tools and SVG quality check
+python3 skills/ppt-master/scripts/icon_sync.py <project_path> <lib/name> [...] # missing names -> non-zero = re-pick
+python3 skills/ppt-master/scripts/confirm_ui/server.py <project_path> --daemon # then --wait-only --wait-stage stage1
python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images
-# In-pipeline AI image generation — manifest mode (required, even for 1 image):
-python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json
-python3 skills/ppt-master/scripts/image_gen.py --render-md <project_path>/images/image_prompts.json
-# Out-of-pipeline one-off / debug / single-image fixup only (no manifest, no sidecar):
-python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
-# Spot illustrations — slice one AI grid sheet into individual elements (see image-generator.md §4.3):
-python3 skills/ppt-master/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names a,b,c --trim --alpha --bg KEY_HEX_FROM_PROMPT --strict-alpha
+python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json # in-pipeline AI images, even for 1
python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemon
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> --canonical-authoring
-# Canonical compact template validation (read-only)
-python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/templates" --template-mode --canonical-authoring
-# Explicit create-template normalization: selected complex <g> -> one SVG picture asset / <image>
-python3 skills/ppt-master/scripts/extract_svg_pictures.py "<svg_file>" --select "<group_id>" --resource-root "<workspace>" --images-dir "<workspace>/picture-assets" --inplace
-# Type A create-template mirror: validated authoring IR -> deterministic structured template workspace
-python3 skills/ppt-master/scripts/mirror_template_materialize.py "<import_workspace>" "<empty_template_workspace>"
-# create-template review deck (workspace root may be global or project-scoped)
-python3 skills/ppt-master/scripts/template_preview_pptx.py <template_workspace>
-python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animation
-python3 skills/ppt-master/scripts/animation_config.py validate <project_path> # optional, before re-export
-
-# Edit Native PPTX — source-preserving round-trip workspace (fill / edit / enhance an existing deck)
-python3 skills/ppt-master/scripts/pptx_to_svg.py <source.pptx> -o projects/<slug>_<YYYYMMDD> --inheritance-mode both --roundtrip
-python3 skills/ppt-master/scripts/svg_authoring_view.py projects/<slug>_<YYYYMMDD>/authoring-svg-flat --refresh-summary
-python3 skills/ppt-master/scripts/svg_to_pptx.py projects/<slug>_<YYYYMMDD> --roundtrip # optional page_plan.json at the workspace root
+python3 skills/ppt-master/scripts/pptx_to_svg.py <source.pptx> -o projects/<slug>_<YYYYMMDD> --inheritance-mode both --roundtrip # Edit Native PPTX
+python3 skills/ppt-master/scripts/svg_to_pptx.py projects/<slug>_<YYYYMMDD> --roundtrip
```
+Every other command (sound sync, slicing, template materialization and preview, animation config, authoring-view refresh) is listed by the route or stage that owns it and in [`svg-pipeline.md`](skills/ppt-master/scripts/docs/svg-pipeline.md).
+
For Generate PPTX serial post-processing and export, follow [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md) Step 7 exactly; Edit Native PPTX exports through its own §7. See [`svg-pipeline.md`](skills/ppt-master/scripts/docs/svg-pipeline.md) for tool flags and behavior.
## Core Directories
diff --git a/skills/ppt-master/references/image-renderings/_index.md b/skills/ppt-master/references/image-renderings/_index.md
index 25cdaf89..6e5e611e 100644
--- a/skills/ppt-master/references/image-renderings/_index.md
+++ b/skills/ppt-master/references/image-renderings/_index.md
@@ -69,9 +69,7 @@ Every coordinated Stage-2 direction carries one complete `rendering: custom` can
- image_rendering_behavior: "Hand-screened poster aesthetic — slightly misregistered halftone overlays, 3 flat ink colors with visible dot pattern at 12% opacity, no gradients, no anti-aliased edges; reads as silkscreen print."
```
-**Hard rule**: three complete rendering candidates are mandatory in every fresh Stage-2 direction set; AI source recommendation remains independent. See [`strategist-image.md`](../strategist-image.md) for the Stage-2 carrier and downstream lock behavior.
-
-Write `image_rendering_references` only when the confirmed custom direction actually uses catalog material. One rendering may supply the complete treatment unchanged; when several are named, each contributes a distinct executable job across line, texture, depth, material, or mood. Reference count has no fixed cap; count is an outcome, not a target. A four-basis direction may assign `vector-illustration` to silhouette clarity, `minimalist-swiss` to negative-space composition, `screen-print` to restrained halftone texture, and `warm-scene` to light and mood; list all four ids. Omit every rendering whose contribution cannot be stated and never add a second merely to imply synthesis. A custom using no catalog source omits the field and proceeds from its standalone behavior; never invent a reference merely to legitimize `custom`.
+Candidate authoring, the three-per-direction rule, and `image_rendering_references` projection are owned by [`strategist-image.md`](../strategist-image.md) §2.
---
diff --git a/skills/ppt-master/references/modes/_index.md b/skills/ppt-master/references/modes/_index.md
index 79b40f69..ddbdb68d 100644
--- a/skills/ppt-master/references/modes/_index.md
+++ b/skills/ppt-master/references/modes/_index.md
@@ -60,16 +60,4 @@ selecting one for the current deck:
## 4. Editable projection and escape hatch — `custom`
-`custom` is the editable behavior carrier, not a category defined by how it relates to the catalog. Default uses it for each coordinated direction even when one preset supplies the complete cadence unchanged. In Quick or a lower-level manual choice it remains the escape hatch for **a bespoke narrative direction the five don't give as-is**: a nameable cadence (dialectic 正反合, myth-vs-reality, countdown / Top-N, Socratic), a deliberate multi-act fusion, or the user's own posture shifts. Don't try to taxonomize those bespoke cases.
-
-**Default candidates**: All three coordinated Stage-2 directions use literal `custom` plus a visible, non-empty `mode_behavior`. A custom may use catalog material in any way or none, including carrying one preset unchanged; it fits any installed template capacity. The three complete directions are plainly different designs, but no single component is required to carry that difference: mode behaviors and bases may coincide when other components express it, while a different name, note, or reference count alone is never a difference. The fixed five remain lower-level single-select alternatives. Strategist crystallizes the confirmed current value in the Design Spec first, then projects its behavior and actual catalog basis to `spec_lock.md`.
-
-**Quick custom**: do not display a candidate set. Use `custom` only when a project-specific specialization or fusion serves the deck better than one preset; retain the behavior and exact bases in active context and persist nothing.
-
-**Mandatory — select before detail reading**: Use this index to freeze every catalog source actually used, then read only those exact files before writing the behavior. One source may supply the complete cadence unchanged; when several are named, each owns a distinct executable act, posture, title voice, rhythm, or register. Reference count has no fixed cap; count is an outcome, not a target. A three-basis direction may use `pyramid` for a conclusion-first opening, `narrative` for the risk-tension act, and `instructional` for the closing action sequence; it reads those three files and writes all three ids beside `mode_behavior`. Quick retains its bases only in active context. Omit every source whose contribution cannot be stated, never add a second merely to imply synthesis, and do not open candidates for comparison after this gate. A custom using no catalog source names and reads none.
-
-> **One value per deck — fusion is *one* `custom`, not several modes.** A deck always resolves a single `mode`. A multi-mode blend is expressed as **one** custom behavior whose paragraph describes the acts — never as several simultaneous modes.
->
-> **Default custom need not mean fusion or deviation.** It may project one dominant preset unchanged into an editable behavior, or specialize it when the project actually calls for a delta. Quick or a lower-level manual choice still uses the fixed preset directly when no editable projection is needed.
-
-**Forbidden — empty behavior**: Single-preset reuse is valid. When a Default direction carries an index row without changing its logic, name and read that exact basis, then state its executable cadence, posture, title voice, page rhythm, or act sequence in the editable behavior; do not add another mode merely to justify `custom`. A bare label with no executable behavior remains invalid. A user-stated direction remains authoritative the same way a user-supplied outline is — see the lens-not-mandate note in §1.
+`custom` is the editable behavior carrier: one deck resolves a single `mode`, and a multi-mode blend is one custom behavior whose paragraph states the executable cadence, not several modes. A custom may use catalog material in any way or none — carrying one preset unchanged is valid — and names only the bases it actually uses; freeze those ids from this index, then read only their files before writing the behavior. Default authors it for each Stage-2 direction under [`strategist.md`](../strategist.md) §d; Quick uses it only when a project-specific specialization or fusion serves the deck better than one preset and keeps the behavior in active context.
diff --git a/skills/ppt-master/references/visual-styles/_index.md b/skills/ppt-master/references/visual-styles/_index.md
index 5d2a00c2..41c96cd6 100644
--- a/skills/ppt-master/references/visual-styles/_index.md
+++ b/skills/ppt-master/references/visual-styles/_index.md
@@ -107,11 +107,7 @@ an exact authoring preset here.
## 3. Editable `custom` projection
-Each coordinated Default Stage-2 direction authors one visible, non-empty `custom` aesthetic whose paragraph names its executable shape language, composition geometry, decoration density, whitespace, typographic character, and texture — **no HEX, no color names as values**. `custom` is not constrained by its relationship to the catalog: it may use catalog material in any way or none, including carrying one fitting preset unchanged. The three complete directions are plainly different designs; this axis expresses that difference whenever their aesthetics genuinely differ, and catalog bases may coincide. A different name, note, reference count, or palette alone is not another aesthetic. Style behaviors may also coincide when other components carry the direction difference or authoritative user/template truth forbids visual variation; state that boundary in the direction note instead of fabricating difference. Use this index to freeze any catalog bases before reading their detail files. A template-backed direction stays inside the inherited identity and confirmed application plan. Record the confirmed current aesthetic in the Design Spec first, then project `- visual_style: custom` plus `- visual_style_behavior:`. The 18 fixed styles remain lower-level single-select alternatives; do not create a fourth AI-custom proposal.
-
-Quick does not display a candidate spectrum. It reads this index, resolves one preset or custom behavior, then reads only the selected detail files and persists nothing.
-
-**Mandatory — select before detail reading**: Freeze every catalog source actually used from this index, then read only those exact files before writing the behavior. One source may supply the complete aesthetic unchanged; when several are named, each contributes a distinct executable job across shape language, composition, decoration, whitespace, typography, or texture. Reference count has no fixed cap; count is an outcome, not a target. A coherent three-basis direction may assign `swiss-minimal` to grid and whitespace, `soft-rounded` to selective surface contours and elevation, and `editorial` to evidence hierarchy and rules. Default persists every actual id as `visual_style_references`; Quick retains them only in active context. Omit every source whose contribution cannot be stated, never add a second merely to imply synthesis, and do not open candidates for comparison after this gate. A custom using no catalog source names and reads none.
+Each Default Stage-2 direction authors one visible, non-empty `custom` aesthetic under [`strategist.md`](../strategist.md) §d — its executable shape language, composition geometry, decoration density, whitespace, typography character, and texture — naming only the catalog bases it actually uses; freeze those ids from this index, then read only their files before writing the behavior. Quick resolves one preset or custom behavior the same way and persists nothing.
---
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index 0dac0909..a6622c6e 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -85,16 +85,7 @@ Quick activation; Beautify may select either runtime, but never both.
## 4. Template and Master/Layout Boundary
-**Hard rule — no direct structure grafting**: An existing PPTX or SVG is never upgraded in place by adding Master/Layout/placeholder structure. If reusable native structure is required:
-
-1. Run [`create-template`](./create-template.md) to produce a separate validated workspace.
-2. Pass that workspace root to Default as a Stage-1 template candidate, or supply its exact root directly to explicit Quick Generate.
-3. Author new structured SVG pages whose Master/Layout contract exists from their first generated draft.
-4. Export a new PPTX from those pages.
-
-When a PPTX already contains native Master/Layout parts, `create-template` mirror may read and preserve those existing package facts in the new workspace. It does not infer missing historical intent. An incomplete or legacy SVG package may guide `standard` / `fidelity` visually, but it is not mutated into a structured template and cannot claim source-topology recovery.
-
-**Hard rule — no automatic structure upgrade**: Free-design, brand-only, and style-only generation remains `pptx_structure.mode: flat`. Repeated Slide-local objects never trigger `structured`, Master/Layout promotion, placeholder inference, or deduplication. The minimal Master plus Blank Layout emitted by flat export is package scaffolding, not an inferred reusable design master.
+**Hard rule — no direct structure grafting or automatic upgrade**: an existing PPTX or SVG is never upgraded in place by adding Master/Layout/placeholder structure — run [`create-template`](./create-template.md) for a separate validated workspace, then pass its root to Default Stage 1 or explicit Quick and author new structured pages. Free-design, brand-only, and style-only generation stays `pptx_structure.mode: flat`; repeated Slide-local objects never trigger `structured`.
| Input | Route behavior |
|---|---|
@@ -160,14 +151,4 @@ corresponding directories to construct or supplement the catalog:
| Layout | [`layouts_index.json`](../templates/layouts/layouts_index.json) |
| Deck | [`decks_index.json`](../templates/decks/decks_index.json) |
-**Hard rule — one Stage-1 confirmation, delayed template reading**: Author the
-communication recommendation without reading candidate workspaces. Stage 1
-confirms that contract and the template/free-design choice together. Only then
-validate/install selected roots and complete the handoff. Stage 2 waits for that
-handoff, reads only the installed project-local state, and decides how to apply
-it; it never reselects a template.
-
-**Forbidden — fuzzy resolution**: Never resolve a bare name to a local template
-directory on the user's behalf. A library choice comes from an index-derived
-root; an unregistered workspace requires an explicit root, including the exact
-validated workspace handed off by Create Template in the current conversation.
+**Hard rule — index-derived roots only**: never resolve a bare name to a local template directory on the user's behalf; a library choice comes from an index-derived root, and an unregistered workspace requires an explicit root (including the exact workspace handed off by Create Template in the current conversation). Stage-1 ordering and delayed template reading are owned by [`generate-pptx`](./generate-pptx.md) Steps 3–4.