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(rules): contract before craft, both short; reorder shared-standards-core
hugohe39fd8a47c684e
diff --git a/docs/rules/prompt-layers.md b/docs/rules/prompt-layers.mdindex c1fbf78c..8cd51a89 100644--- a/docs/rules/prompt-layers.md+++ b/docs/rules/prompt-layers.md@@ -28,6 +28,21 @@ The prompt files are read by a model before it plans a deck and hand-writes SVG| `scripts/docs/<topic>.md` | Tool documentation. A contract reference that mirrors a prompt file keeps that file's section numbers (`svg-contract.md` §1.1–§2.2 mirror `shared-standards-core.md`, Part II §6.2–§6.10 mirror `svg-effects.md`) so a pointer resolves in either direction | Nobody during generation; `coverage.exempt` in the manifest with a reason || `templates/*_reference.md`, `templates/schemas/*.json` | Artifact grammar the model authors against (`design_spec.md`, `spec_lock.md`) | Read at authoring time by the owning Step |+**Hard rule — contract before craft, both short**: inside a file, and inside+each section, state the contract first — the routing/menu rows and the one+canonical form — then the craft that uses it. A recall index (a routing table,+the Visual Job Router, the everyday device menu) counts as contract: it is the+list of what exists, and it stays at the top because a capability the model+has not seen is a capability it will not use. Anything that is plain SVG or+XML behavior — what `<use>` does, what a path command means, that a transform+composes — gets one line or nothing; the model knows SVG, and the prompt only+records where this pipeline departs from it. Craft is written as the decision+and its test, not as an essay: one labelled paragraph or one table per+decision, examples only where a form is easier shown than told. A long+passage is justified only when the decision genuinely has that many moving+parts; length that comes from restating context, hedging, or listing every+case is what makes a rule hard to recall at authoring time.+**Hard rule — one owner, pointers elsewhere**: a rule is stated in full in exactly one file. Every other file that needs it carries a pointer naming the file and section, not a paraphrase. A paraphrase is a second owner: it drifts, contradicts the original after the next edit, and doubles the tokens. The cross-file duplicate check in `prompt_audit.py` catches verbatim copies only; paraphrases are caught by reading.**Hard rule — everyday capabilities stay in the core**: effects, native shapes and their preset vocabulary, relationship grammar, and topology assembly are read before the first page by both Default and Quick. Only a capability most decks never touch (formula, hyperlink, chart/table branches, structured templates, video, animation, web-image attribution) loads on its own observable trigger, and the always-read core still names it in one routing row. Demoting an everyday capability to a trigger does not shrink the run — nearly every deck fires the trigger — and it reintroduces the failure where a capability not in context is never used.diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.mdindex a61a9c40..3559aa84 100644--- a/skills/ppt-master/references/shared-standards-core.md+++ b/skills/ppt-master/references/shared-standards-core.md@@ -10,25 +10,7 @@ Mandatory reference for every route that authors or regenerates slide visuals th| 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 || Default structured lock, or Quick installed Layout/Deck structured authoring | [`pptx-structure-interface.md`](./pptx-structure-interface.md) |-**Default — shared aesthetic baseline (may be overridden by explicit user, installed template / brand, or locked / Quick-resolved visual-style requirements)**: Required / Forbidden technical contracts remain absolute. When a higher authority is silent, build clear hierarchy through typography and leading, alignment, negative space, purposeful imagery / icons, shapes, and repetition. Deliberate tightness, imbalance, off-axis placement, or container-heavy structure remains valid when that authority calls for it.--| Concern | Shared default |-|---|---|-| Text-block rhythm | Use §4.2 leading. Make the baseline step into a new paragraph visibly larger than the intra-paragraph line step; keep the extra gap between list items smaller than paragraph separation but large enough to scan each item. Repeated peer blocks share one rhythm unless their hierarchy differs. |-| Typography roles | Use the fewest semantic text roles that preserve hierarchy, and make their differences legible at slide-thumbnail scale. Consolidate near-neighbor sizes that serve the same role; otherwise distinguish roles through a deliberate combination of size, weight, color, position, and surrounding space. |-| Viewing-distance legibility | Resolve delivery context and viewing distance before fixing density and type scale. Preserve necessary text at a readable scale by applying only actions the active route's content and page invariants permit: restructure, shorten, split, or reflow. If none is permitted, surface the unresolved fit instead of silently miniaturizing it. Do not turn this into one universal font-size floor: captions and metadata may be smaller when their role and context remain legible. |-| Contrast and semantic encoding | Within the active profile's fidelity boundary, keep meaning-bearing text distinguishable from its actual background. For newly authored distinctions, combine luminance, weight, scale, shape, position, or explicit labeling; color may reinforce meaning but never carry a required distinction alone. When fidelity requires preserving source-only color encoding, reproduce it rather than inventing a cue. Reserve lower-contrast treatment for genuinely secondary metadata that remains legible. |-| Natural wrapping | Break at semantic phrase or punctuation boundaries where possible. Reflow the text frame or adjust neighboring geometry before using any permitted local size reduction. Let the final line run naturally shorter; avoid mechanically equal lines or a stranded single-character / single-word line when an earlier natural break preserves meaning. |-| Content field | Establish the usable body frame before placing modules. Divide it into one or a small set of macro-regions from information weight and reading order: use unequal weight when the information differs, while true peers may share equal weight. Give each region its own local axes / micro-grid while retaining only the cross-region anchors the composition needs. On a dense page, let the planned content system organize that frame; create breathing room through gutters, module spacing, and intentional voids between semantic clusters. Unorganized residual space that leaves content stranded in one part of the frame is leftover blank, not negative space. |-| Alignment and proximity | Establish shared axes from the current composition. Align related titles, copy, labels, images, and diagram nodes to those edges, centers, or baselines; group related elements more tightly than unrelated groups so spacing carries hierarchy. Break an axis only when the offset performs hierarchy, direction, or tension. |-| Visual weight | Judge weight from area, darkness, saturation, density, stroke, image detail, and elevation together. Distribute it to support the focal path; symmetry is optional, and deliberate imbalance may create direction. |-| Boundary strength | Boundaries range from spacing / alignment, rule / bracket, and tint field through outline, filled panel, and true floating layer; choose the strength from the relationship. Peer relationships use comparable strength while focus, hierarchy, or material difference may use a different one. |-| Containers | A card or panel expresses grouping, hierarchy, boundary, capacity, or a distinct material plane; peer containers share treatment unless a semantic difference justifies contrast. An unplanned repeated web-card grid is a carrier / topology problem, not a reason to suppress meaningful borders, shapes, or containers. |-| Titles and page chrome | Treat the semantic page title as part of the current composition rather than an automatic fixed header band; its position, scale, and relationship may change with page role while preserving the active route's content invariants. Add or retain running headers, footers, and page numbers only when they carry navigation, identity, attribution, or another explicit page job. Fidelity profiles preserve required source chrome. |--**Reference — effects vocabulary**: Default and Quick Generate load [`svg-effects.md`](./svg-effects.md); its §6.1 Visual Job Router lists the visual jobs an effect can serve. Whether any compatible technique is added is the author's call.--**Reference — where expression lives**: §4.2 owns editable text form, including per-run inline emphasis and leading; §4.3 owns grouping. §1.4's imported-PowerPoint metadata applies only to import, mirror, and round-trip routes.+Design defaults that apply when no higher authority speaks are collected in §6.**Fidelity labels**:@@ -102,7 +84,7 @@ One offending character invalidates the file and aborts export.### 1.3 Static Same-Document `<use>` (Conditional Contract)-Local reuse is compile-time shorthand: `finalize_svg.py` and native export clone the referenced primitive content into each instance, and PPTX import never reconstructs the `<use>` / `<symbol>` structure. Author `href="#id"` to one `<symbol>` (finite positive `viewBox`, artwork inside it, instance `width` / `height` positive unitless) or to a primitive, `<g>`, `<text>`, or `<image>`; nested local `<use>` expands recursively. The reused subtree carries no layer, placeholder, or chart/table replacement metadata, and duplicate IDs anywhere in the chain fail. Limits and forbidden forms: [`svg-contract.md`](../scripts/docs/svg-contract.md) §1.3.+Author `href="#id"` to a `<symbol>` (finite positive `viewBox`, artwork inside it, instance `width` / `height` positive unitless) or to a primitive, `<g>`, `<text>`, or `<image>`. This pipeline departs from browser SVG in two ways: finalization and native export clone the referenced primitives into each instance (PowerPoint keeps no symbol graph, and PPTX import never reconstructs `<use>`), and the reused subtree may carry no layer, placeholder, or chart/table replacement metadata. Limits and forbidden forms: [`svg-contract.md`](../scripts/docs/svg-contract.md) §1.3.```xml<svg xmlns="http://www.w3.org/2000/svg">@@ -250,3 +232,27 @@ An authored native preset fragment (§1.5) is already an atomic `<g id>` and cou## 5. Workflow AuthoritySerial post-processing and export belong to [`generate-pptx.md`](../workflows/generate-pptx.md) Step 7 and, for the direct-generation exception, [`quick-generate.md`](../workflows/profiles/quick-generate.md). This file defines SVG authoring boundaries only; project structure, commands, quality-gate order, and export products are intentionally outside it.++---++## 6. Shared Aesthetic Baseline++**Default — shared aesthetic baseline (may be overridden by explicit user, installed template / brand, or locked / Quick-resolved visual-style requirements)**: Required / Forbidden technical contracts remain absolute. When a higher authority is silent, build clear hierarchy through typography and leading, alignment, negative space, purposeful imagery / icons, shapes, and repetition. Deliberate tightness, imbalance, off-axis placement, or container-heavy structure remains valid when that authority calls for it.++| Concern | Shared default |+|---|---|+| Text-block rhythm | Use §4.2 leading. Make the baseline step into a new paragraph visibly larger than the intra-paragraph line step; keep the extra gap between list items smaller than paragraph separation but large enough to scan each item. Repeated peer blocks share one rhythm unless their hierarchy differs. |+| Typography roles | Use the fewest semantic text roles that preserve hierarchy, and make their differences legible at slide-thumbnail scale. Consolidate near-neighbor sizes that serve the same role; otherwise distinguish roles through a deliberate combination of size, weight, color, position, and surrounding space. |+| Viewing-distance legibility | Resolve delivery context and viewing distance before fixing density and type scale. Preserve necessary text at a readable scale by applying only actions the active route's content and page invariants permit: restructure, shorten, split, or reflow. If none is permitted, surface the unresolved fit instead of silently miniaturizing it. Do not turn this into one universal font-size floor: captions and metadata may be smaller when their role and context remain legible. |+| Contrast and semantic encoding | Within the active profile's fidelity boundary, keep meaning-bearing text distinguishable from its actual background. For newly authored distinctions, combine luminance, weight, scale, shape, position, or explicit labeling; color may reinforce meaning but never carry a required distinction alone. When fidelity requires preserving source-only color encoding, reproduce it rather than inventing a cue. Reserve lower-contrast treatment for genuinely secondary metadata that remains legible. |+| Natural wrapping | Break at semantic phrase or punctuation boundaries where possible. Reflow the text frame or adjust neighboring geometry before using any permitted local size reduction. Let the final line run naturally shorter; avoid mechanically equal lines or a stranded single-character / single-word line when an earlier natural break preserves meaning. |+| Content field | Establish the usable body frame before placing modules. Divide it into one or a small set of macro-regions from information weight and reading order: use unequal weight when the information differs, while true peers may share equal weight. Give each region its own local axes / micro-grid while retaining only the cross-region anchors the composition needs. On a dense page, let the planned content system organize that frame; create breathing room through gutters, module spacing, and intentional voids between semantic clusters. Unorganized residual space that leaves content stranded in one part of the frame is leftover blank, not negative space. |+| Alignment and proximity | Establish shared axes from the current composition. Align related titles, copy, labels, images, and diagram nodes to those edges, centers, or baselines; group related elements more tightly than unrelated groups so spacing carries hierarchy. Break an axis only when the offset performs hierarchy, direction, or tension. |+| Visual weight | Judge weight from area, darkness, saturation, density, stroke, image detail, and elevation together. Distribute it to support the focal path; symmetry is optional, and deliberate imbalance may create direction. |+| Boundary strength | Boundaries range from spacing / alignment, rule / bracket, and tint field through outline, filled panel, and true floating layer; choose the strength from the relationship. Peer relationships use comparable strength while focus, hierarchy, or material difference may use a different one. |+| Containers | A card or panel expresses grouping, hierarchy, boundary, capacity, or a distinct material plane; peer containers share treatment unless a semantic difference justifies contrast. An unplanned repeated web-card grid is a carrier / topology problem, not a reason to suppress meaningful borders, shapes, or containers. |+| Titles and page chrome | Treat the semantic page title as part of the current composition rather than an automatic fixed header band; its position, scale, and relationship may change with page role while preserving the active route's content invariants. Add or retain running headers, footers, and page numbers only when they carry navigation, identity, attribution, or another explicit page job. Fidelity profiles preserve required source chrome. |++**Reference — effects vocabulary**: Default and Quick Generate load [`svg-effects.md`](./svg-effects.md); its §6.1 Visual Job Router lists the visual jobs an effect can serve. Whether any compatible technique is added is the author's call.++**Reference — where expression lives**: §4.2 owns editable text form, including per-run inline emphasis and leading; §4.3 owns grouping. §1.4's imported-PowerPoint metadata applies only to import, mirror, and round-trip routes.diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.mdindex 37931e7b..653045bb 100644--- a/skills/ppt-master/references/svg-effects.md+++ b/skills/ppt-master/references/svg-effects.md@@ -401,21 +401,12 @@ descendant alpha (§2.2).### 6.9 Freeform Shapes and Curves-| Input | Native normalization | Fidelity |-|---|---|---|-| `M/L/H/V`, absolute or relative | Absolute `M/L` | `Native-normalized` |-| `C` | Cubic Bézier | `Native-normalized` |-| `S/Q/T` | Explicit cubic controls | `Native-normalized` |-| `A` | Cubic segments of at most 90° | `Approximate` |-| `Z`; polygon/polyline | Closed/open freeform | `Native-normalized` |--Write `path@d` and `points` with finite unitless ordinary decimals and only-these commands; a path starts with `M`, arc flags are `0`/`1`, a polygon has-≥3 pairs and a polyline ≥2. Command identity, relative coordinates, shorthand,-arc parameters, and original handles are not retained; geometry needs non-zero-bounds. Do not depend on `fill-rule="evenodd"` — build explicit visible-geometry, bake an essential knockout, or on a fixed background use a-background-colored overlay.+Every SVG path command, `<polygon>`, and `<polyline>` is accepted; export+normalizes to absolute `M/L` and cubic Béziers, and arcs become ≤90° cubic+segments (`Approximate`). Write `d` and `points` as finite unitless ordinary+decimals; geometry needs non-zero bounds; do not depend on+`fill-rule="evenodd"` — build explicit visible geometry, bake an essential+knockout, or on a fixed background use a background-colored overlay.**Reference — not a constraint**: use the fewest curve segments and controlpoints that preserve the intended silhouette. Set endpoints and tangent