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
fix(checker): default a missing pptx_structure.mode to flat and relax non-export gates
hugohe3cc535363b8cf
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex e1324e45..16d7d52d 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -86,7 +86,7 @@ history, or resumable planning state. Context loss restarts the Quick run.| SVG source | `svg_output/` is the only author source for generated pages. || Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. || Package-behavior separation | Speaker notes, animations, transitions, narration, and direct native-PPTX workflows keep their owning artifacts; do not force them into SVG metadata. |-| Post-processed SVG | In Default Generate, `svg_final/` is disposable, must be rebuilt in Step 7.2, and serves only as a self-contained visual preview / manually insertable SVG picture. Quick omits it. |+| Post-processed SVG | In Default Generate, `svg_final/` is an optional disposable preview rebuilt by Step 7.2; it serves only as a self-contained visual preview / manually insertable SVG picture. Quick omits it. || Workflow audit log | `validation/workflow.log` automatically records each project-scoped Python command envelope, all explicit error/failure and receipt/report lines, bounded warning/OK/stderr samples, summary context, and omission counts, plus explicitly selected manual audit entries. It does not retain the full console stream or automatically capture direct file-authoring actions, host-native tools, pre-project conversion, binary-buffer writes, hidden child output, or detached-service activity; absence of a detail line proves nothing about those stages. Automatic recording failure is advisory and never changes the owning tool's outcome; a failed explicit manual append reports failure because no entry was recorded. || Export source | The only supported generated-PPTX route reads `svg_output/` through the project SVG-to-DrawingML converter. A diagnostic `-s final` override does not change ownership or create a supported release route. || Shape-conversion boundary | PowerPoint's manual Convert-to-Shape operation on `svg_final/` is outside the project compatibility contract. |diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex fb141989..eb3209de 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -25,7 +25,7 @@ Evaluate branches from each object's actual information model, not only from a C**Hard rule — flat PowerPoint structure**: Free-design, brand-only, Style-only, and every `template_reuse_scope: style` project use `pptx_structure.mode: flat`: write no root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder`; every visible object remains Slide-local, and the root declares exactly one canonical `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`). A Style workspace supplies reusable communication/design direction, composition rhythm, and information-expression defaults without page prototypes. Its identity-adjacent color, typography, icon, and image defaults yield to the final Brand/Deck identity and confirmed project lock. When a Style is installed alongside Layout/Deck, it changes only Direction / method and follows the resolved non-Style structure route. Export materializes one clean project-owned Master plus one Blank Layout from the current lock. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by specialized metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md).-**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.+**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 generates `svg_final/` as an optional self-contained visual preview that may be inserted as an SVG picture; its absence never blocks export. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.mdindex 22ed7edc..ed31bcd3 100644--- a/skills/ppt-master/references/shared-standards-core.md+++ b/skills/ppt-master/references/shared-standards-core.md@@ -332,7 +332,7 @@ one. This array is still diagnostic metadata, not an authoring surface.| `standard` / `fidelity` output | Use §1.5 compact presets; never transplant opaque payload or source topology. || `mirror` output | Template_Designer reviews/authors the compact parsed IR; materialization validates refs/graph and publishes that tree without restoring visible lossless subtrees. Recover only supported non-visible semantics; expand fixed Master/Layout wrappers without changing ownership or intended presentation. |-**Hard rule — model-facing page-coordinate precision**:+**Default — model-facing page-coordinate precision (the canonical checker reports over-precision as an advisory warning)**:| Surface | Precision contract ||---|---|diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 48e6a2ec..ccfa0d05 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -706,7 +706,7 @@ It aggregates:- `align_embed_images.py` (`crop-images` / `fix-aspect` / `embed-images` aliases route here)- `flatten_tspan.py`-`svg_final/` remains a required Step 7.2 artifact even though the native exporter reads `svg_output/`. It is the self-contained visual reference and may be manually inserted as an SVG picture.+`svg_final/` is an optional Step 7.2 preview artifact; the native exporter reads `svg_output/` and never requires it. It is the self-contained visual reference and may be manually inserted as an SVG picture.## `svg_to_pptx.py`diff --git a/skills/ppt-master/scripts/project_utils.py b/skills/ppt-master/scripts/project_utils.pyindex 4a3295e1..20fd7438 100644--- a/skills/ppt-master/scripts/project_utils.py+++ b/skills/ppt-master/scripts/project_utils.py@@ -407,11 +407,11 @@ def validate_project_structure(# Check required filesif not (project_path / 'README.md').exists():- msg = "Missing required file: README.md"+ msg = "Missing README.md (optional project notes; nothing reads it)"if use_helper and verbose:msg += "\n" + ErrorHelper.format_error_message('missing_readme',{'project_path': str(project_path)})- errors.append(msg)+ warnings.append(msg)# Check design specification filehas_spec = any((project_path / name).exists() for name in _DESIGN_SPEC_NAMES)diff --git a/skills/ppt-master/scripts/svg_quality/checker.py b/skills/ppt-master/scripts/svg_quality/checker.pyindex 090edec7..79d1ec8f 100644--- a/skills/ppt-master/scripts/svg_quality/checker.py+++ b/skills/ppt-master/scripts/svg_quality/checker.py@@ -5893,6 +5893,16 @@ class SVGQualityChecker:if standard_projectelse None)+ implicit_flat = bool(standard_project) and not declared_mode+ if implicit_flat:+ self._pptx_structure_issues.append((+ 'warning',+ 'spec_lock.md declares no pptx_structure.mode; the project is '+ 'treated as mode: flat, matching the exporter default. Declare '+ 'mode: flat explicitly, or mode: structured for a deck/layout '+ 'template.',+ ))+ declared_mode = 'flat'if standard_project and declared_mode in {'flat', 'structured'}:self._pptx_structure_issues.extend(('error', message)@@ -5914,6 +5924,8 @@ class SVGQualityChecker:except _TemplateStructureError as exc:self._pptx_structure_issues.append(('error', str(exc)))return+ if structure_lock is None and implicit_flat:+ returnif structure_lock is None or structure_lock.mode != 'flat':self._pptx_structure_issues.append(('error',@@ -5969,18 +5981,14 @@ class SVGQualityChecker:returnif standard_project and declared_mode != 'structured':- label = repr(declared_mode) if declared_mode else (- 'missing (legacy implicit baseline)'- )self._pptx_structure_issues.append(('error',- 'release SVG projects require an explicit spec_lock.md '- 'pptx_structure.mode: flat (free design / brand-only) or '- f'structured (deck/layout template); found {label}. New '- 'free-design projects use mode: flat; create a new template '- 'workspace through skills/ppt-master/workflows/create-template.md, '- 'then generate new structured SVG pages before export. Existing '- 'PPTX/SVG files are not upgraded in place.',+ 'release SVG projects require spec_lock.md pptx_structure.mode: '+ 'flat (free design / brand-only) or structured (deck/layout '+ f'template); found {declared_mode!r}. Create a template '+ 'workspace through skills/ppt-master/workflows/create-template.md '+ 'before generating structured SVG pages. Existing PPTX/SVG files '+ 'are not upgraded in place.',))returndiff --git a/skills/ppt-master/templates/schemas/spec_lock.schema.json b/skills/ppt-master/templates/schemas/spec_lock.schema.jsonindex 7108563d..c025f47c 100644--- a/skills/ppt-master/templates/schemas/spec_lock.schema.json+++ b/skills/ppt-master/templates/schemas/spec_lock.schema.json@@ -13,7 +13,6 @@"typography","icons","page_rhythm",- "pptx_structure","forbidden"],"properties": {@@ -183,7 +182,7 @@{"id": "pptx_structure","pattern": "^pptx_structure$",- "required": true,+ "required": false,"required_fields": ["mode"],"allowed_fields": ["mode", "template_reuse_scope", "template_adherence"],"field_enums": {diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 5122667a..a30516c8 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -32,7 +32,7 @@ request does not explicitly select Quick.| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, block/inline native-formula preview, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. || Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. || Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. Chart/table markers preserve their visible SVG fallback; block and inline formula markers carry exact LaTeX and replace only their registered ordinary SVG preview with editable Office Math during PPTX export. |-| `svg_final/` | Mandatory derived, self-contained SVG visual preview in the default pipeline. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. Quick-generate skips it. |+| `svg_final/` | Optional derived, self-contained SVG visual preview in the default pipeline; release export never reads it. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. Quick-generate skips it. || SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It compiles only the selected route's explicit structure contract: `flat` keeps represented content Slide-local, while `structured` may place explicitly scoped content in Master/Layout/Slide parts. It MUST NOT infer structure, upgrade `flat`, or invent new visible page content. || Native PPTX routes and presentation-behavior stages | Remain outside SVG page-design closure. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |@@ -835,7 +835,7 @@ command and proceed directly to Step 7.2.python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>```-**Success criterion**: `<project_path>/svg_final/` contains one self-contained preview SVG for every published slide. This mandatory derived preview does not replace `svg_output/` as the native-export source.+**Success criterion**: `<project_path>/svg_final/` contains one self-contained preview SVG for every published slide. This optional derived preview does not replace `svg_output/` as the native-export source, and its absence never blocks Step 7.3.#### Step 7.3 — Export the Native PPTX