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: settle remaining contract drift and add missing authority edges

hugohe34f5041901c28
diff --git a/AGENTS.md b/AGENTS.md
index 11fe26ae..e03ab8fa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate
- Default Generate prepares template candidates internally in Step 3, then confirms the communication contract and free-design/template choice together in Stage 1. Template content stays unread until that confirmation; selected roots are installed before template-aware Stage 2. Quick skips this interaction.
- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.
- Raw PPTX cannot be consumed as a Generate template workspace; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated workspace root as a Stage-1 candidate. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.
-- Explicit quick/fast or skip-strategy generation may use [`quick-generate`](skills/ppt-master/workflows/profiles/quick-generate.md): prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author `svg_output/`, pass its lockless final checker, and export.
+- Explicit quick/fast or skip-strategy generation uses [`quick-generate`](skills/ppt-master/workflows/profiles/quick-generate.md): prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author `svg_output/`, pass its lockless final checker, and export.
- Recorded, self-running, or video-directed Generate work conditionally loads [`video-design`](skills/ppt-master/references/video-design.md) inside the selected Default or explicit Quick runtime before page planning. It changes scene, script, and motion design—not the runtime/profile or artifact route.
- PPTX beautify is a strict 1:1 Generate [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), not a separate route. Explicit Quick intent uses the Quick runtime; otherwise it uses Default. Any split/merge/drop/reorder disables Beautify and returns to ordinary Generate in the selected runtime.
- Page-image reconstruction uses the Codex-supported, Quick-only [`image-to-pptx`](skills/ppt-master/workflows/profiles/image-to-pptx.md) profile. Normalize input page frames; one frame becomes one slide. Restore text natively, reconstruct low-resolution graphics without changing identity, and derive registered clean-base/scene layers. Padded-bbox-disjoint objects may share a generated plate and become independent crops. Never use a full-slide screenshot skin. Other hosts are unsupported.
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 0fc293af..6281688a 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -654,7 +654,8 @@ playback instead and does not consume the trace for sound mixing.
## 9. Implementation References
-See [`svg-pipeline.md`](../scripts/docs/svg-pipeline.md),
+See [`pptx_transitions.py`](../scripts/pptx_transitions.py),
+[`svg-pipeline.md`](../scripts/docs/svg-pipeline.md),
[`pptx-transitions.md`](../scripts/docs/pptx-transitions.md),
[`pptx-animations.md`](../scripts/docs/pptx-animations.md), and
[`video-motion-plan.md`](../scripts/docs/video-motion-plan.md).
diff --git a/skills/ppt-master/references/native-formula.md b/skills/ppt-master/references/native-formula.md
index 1771c4d1..e10986c5 100644
--- a/skills/ppt-master/references/native-formula.md
+++ b/skills/ppt-master/references/native-formula.md
@@ -117,6 +117,13 @@ gate live in `scripts/svg_to_pptx/native_objects/formula_compiler.py` and
names; only explicitly named commands and retained project aliases are
contractual.
+Implementations:
+[`formula.py`](../scripts/svg_to_pptx/native_objects/formula.py),
+[`formula_ast.py`](../scripts/svg_to_pptx/native_objects/formula_ast.py),
+[`formula_parser.py`](../scripts/svg_to_pptx/native_objects/formula_parser.py),
+[`formula_run_properties.py`](../scripts/svg_to_pptx/native_objects/formula_run_properties.py),
+[`inline_formula.py`](../scripts/svg_to_pptx/native_objects/inline_formula.py).
+
**Native normalization**: `\dfrac` / `\tfrac`, `\dbinom` / `\tbinom`, and
continued-fraction alignment normalize to the corresponding OMML structure;
explicit big-delimiter grades become auto-sizing delimiters; `\mathscr`
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index 4def8381..5637c1fb 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -543,6 +543,8 @@ external stylesheets, and imported styles remain forbidden. This contract is
only for literal declarations in an element's own `style` attribute; PPT Master
does not compute CSS cascade or custom properties. Root canvas authority remains
the `viewBox`, regardless of root `<svg>` compatibility width/height values.
+The shared coordinate and geometry implementation is
+[`utils.py`](../scripts/svg_to_pptx/drawingml/utils.py).
### 2.2 Group Opacity Compatibility
diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.md
index 33f07917..7b3ac4de 100644
--- a/skills/ppt-master/references/svg-effects.md
+++ b/skills/ppt-master/references/svg-effects.md
@@ -103,7 +103,9 @@ when the effect carries material meaning.
Compatible paint grammar includes recognized named colors, `rgb()` / `rgba()`,
`hsl()` / `hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`. The
-converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens.
+converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens. The
+shared converter implementation for §§6.2–6.8 is
+[`utils.py`](../scripts/svg_to_pptx/drawingml/utils.py).
**Default — canonical generated paint tokens (may preserve compatible
alternatives)**: New `svg_output/` and reusable template SVGs write solid paint
diff --git a/skills/ppt-master/scripts/attribution_guard.py b/skills/ppt-master/scripts/attribution_guard.py
index 023199aa..0680f2ea 100644
--- a/skills/ppt-master/scripts/attribution_guard.py
+++ b/skills/ppt-master/scripts/attribution_guard.py
@@ -17,6 +17,7 @@ Dependencies:
from __future__ import annotations
+import argparse
import ast
import hashlib
import re
@@ -208,8 +209,16 @@ def require_skill_integrity() -> None:
raise SystemExit(78)
-def main() -> int:
+def build_parser() -> argparse.ArgumentParser:
+ """Build the zero-argument integrity-check CLI parser."""
+ return argparse.ArgumentParser(
+ description="Validate the PPT Master Skill attribution and execution gates.",
+ )
+
+
+def main(argv: list[str] | None = None) -> int:
"""Run the fail-closed Skill integrity gate."""
+ build_parser().parse_args(argv)
require_skill_integrity()
return 0
diff --git a/skills/ppt-master/scripts/generate_examples_index.py b/skills/ppt-master/scripts/generate_examples_index.py
index 8d57ea91..9a41ab84 100644
--- a/skills/ppt-master/scripts/generate_examples_index.py
+++ b/skills/ppt-master/scripts/generate_examples_index.py
@@ -9,6 +9,7 @@ Usage:
python3 scripts/generate_examples_index.py examples
"""
+import argparse
import os
import sys
from collections import defaultdict
@@ -17,8 +18,6 @@ from pathlib import Path
from console_encoding import configure_utf8_stdio
-configure_utf8_stdio()
-
try:
from project_utils import find_all_projects, get_project_info, CANVAS_FORMATS
except ImportError:
@@ -214,16 +213,30 @@ def generate_examples_index(examples_dir: str = 'examples') -> str:
return "\n".join(content)
-def main() -> None:
- """Run the CLI entry point."""
- examples_dir = 'examples'
+def build_parser() -> argparse.ArgumentParser:
+ """Build the examples-index CLI parser."""
+ parser = argparse.ArgumentParser(
+ description="Generate the PPT Master examples README index.",
+ )
+ parser.add_argument(
+ "examples_dir",
+ nargs="?",
+ default="examples",
+ help="Examples directory (default: examples)",
+ )
+ return parser
- if len(sys.argv) > 1:
- if sys.argv[1] in {'-h', '--help', 'help'}:
- print(__doc__)
- sys.exit(0)
- examples_dir = sys.argv[1]
+def main(argv: list[str] | None = None) -> int:
+ """Run the CLI entry point."""
+ parser = build_parser()
+ raw_argv = list(sys.argv[1:] if argv is None else argv)
+ if raw_argv == ["help"]:
+ parser.print_help()
+ return 0
+ args = parser.parse_args(raw_argv)
+ configure_utf8_stdio()
+ examples_dir = args.examples_dir
print("=" * 80)
print("PPT Master - Examples Index Generator")
@@ -234,7 +247,7 @@ def main() -> None:
if not content:
print("\n[ERROR] Generation failed")
- sys.exit(1)
+ return 1
# Write to file
output_file = Path(examples_dir) / 'README.md'
@@ -252,8 +265,10 @@ def main() -> None:
except Exception as e:
print(f"\n[ERROR] Failed to write file: {e}")
- sys.exit(1)
+ return 1
+
+ return 0
if __name__ == '__main__':
- main()
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/visualization_catalog.py b/skills/ppt-master/scripts/visualization_catalog.py
index a76e11f9..e50e8296 100644
--- a/skills/ppt-master/scripts/visualization_catalog.py
+++ b/skills/ppt-master/scripts/visualization_catalog.py
@@ -352,6 +352,13 @@ def resolve_visualization_reference(
return _require_svg(resolved)
+if __name__ == "__main__" and any(
+ arg in {"-h", "--help", "help"} for arg in sys.argv[1:]
+):
+ print(__doc__)
+ raise SystemExit(0)
+
+
if __name__ == "__main__":
from console_encoding import configure_utf8_stdio