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(template-import): slim canonical analysis workspace
hugohe36f268339d82b
diff --git a/docs/templates-guide.md b/docs/templates-guide.mdindex 7f2cb00e..c5912b76 100644--- a/docs/templates-guide.md+++ b/docs/templates-guide.md@@ -184,7 +184,8 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \It validates the IR manifest, immutable source hashes, complete native graph,visibility facts, and imported-vector closure before atomically publishing thesource-ordered SVG roster and its `icons/imported/` / `images/` assets. It never-uses `svg-flat/` as the template source and never generates `design_spec.md`;+requires or uses the opt-in `svg-flat/` verification tree as the template source+and never generates `design_spec.md`;the designer writes that brief against the published roster.**Mirror graph boundary**: mirror preserves the complete supported source Master/Layout graph. It emits one complete prototype per source slide and one definition-only `layout_<layout_key>.svg` prototype for every source Layout unused by those slides. The latter registers in PowerPoint through the independent Layout roster without becoming a published page; its parent Master is retained with it. Preflight stops only when required source facts or supported geometry are missing, never merely because a Layout is unused.diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex 493b18b1..079828db 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -183,8 +183,8 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \它会先校验 IR manifest、不可变来源 hash、完整原生图谱、可见性事实和导入向量闭包,再原子发布按源顺序排列的 SVG roster 及-`icons/imported/`、`images/` 素材。它不会把 `svg-flat/` 当成模板来源,-也不会生成 `design_spec.md`;设计角色必须针对物化后的 roster 编写该简报。+`icons/imported/`、`images/` 素材。它不要求、也不会把按需生成的+`svg-flat/` 校验视图当成模板来源,并且不会生成 `design_spec.md`;设计角色必须针对物化后的 roster 编写该简报。**Mirror 图谱边界**:mirror 保留完整且受支持的来源 Master/Layout 图谱。它为每张来源 Slide 输出一个完整原型,并为未被任何来源 Slide 使用的 Layout 额外输出一个定义专用的 `layout_<layout_key>.svg`。后者通过独立 Layout roster 注册进 PowerPoint,不会变成发布页面;其父 Master 也随之保留。预检只在必要来源事实或受支持几何缺失时停止,不会仅因 Layout 未使用而停止。diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex 13f63d09..f274b0e8 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -22,10 +22,11 @@ Global artifact ownership rules for PPT Master projects.| `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Step 5 writes here; `analysis/image_analysis.csv` derives from current contents || `icons/` | Project icon inventory | Icons copied by `icon_sync.py` for this project | Executor uses locked project icons; exporter may fall back to global library only as documented || `templates/` | Project template reference | Step 3 imported specs, template SVGs, and non-image assets | Strategist/Executor read only when Step 3 is triggered |-| `<import_workspace>/svg/`, `<import_workspace>/svg-flat/` | Imported native-payload backing | Complete PPTX-derived metadata, hidden carriers, fallback evidence, and source structure | Keep immutable; create-template materialization may resolve a validated source ref against these files, but models do not edit or bulk-read them |+| `<import_workspace>/svg/` | Imported native-payload backing | Complete PPTX-derived metadata, hidden carriers, fallback evidence, and source structure | Keep immutable; create-template materialization may resolve a validated source ref against these files, but models do not edit or bulk-read them |+| `<import_workspace>/svg-flat/` | Optional complete-page verification backing | Self-contained visual composition generated only by explicit `--inheritance-mode both` | Keep immutable when requested; never use as authoring or materialization input || `<import_workspace>/authoring-svg/` | Template-creation author source | Layered editable SVG IR for imported Master, Layout, and Slide objects | Template_Designer reads and edits this bundle; final template SVGs are materialized from it rather than copied from lossless backing || `<import_workspace>/authoring-svg/authoring_manifest.json` | Authoring provenance contract | Per-document source/authoring hashes and document-local source-ref paths | Generated atomically with the IR; materialization validates it before reusing native payload; never duplicate raw payload here |-| `<import_workspace>/authoring-svg-flat/` | Complete-page verification IR | Self-contained page composition view with its own provenance manifest | Use to verify composition; layered `authoring-svg/` remains the canonical editable source |+| `<import_workspace>/authoring-svg-flat/` | Optional complete-page verification IR | Self-contained page composition view with its own provenance manifest | Generate only from an explicitly requested `svg-flat/`; use to verify composition, while layered `authoring-svg/` remains the canonical editable source || `<import_workspace>/icons/imported/` | Imported vector pool | One canonical copy of every factored vector subtree | Authoring SVGs reference `data-icon="imported/<name>"`; vector inventories retain source refs so expansion restores IR identity || `confirm_ui/recommendations.json` | Confirmation proposal | Strategist-authored confirmation payload | Confirm UI reads; rewritten between Stage 1, Stage 2, and Stage 3 || `confirm_ui/result.json` | Confirmation result | User-confirmed values | Strategist treats final result as authoritative over recommendations |@@ -49,7 +50,7 @@ Global artifact ownership rules for PPT Master projects.| Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. || Free-design / brand-only packaging authority | `spec_lock.md` declares `pptx_structure.mode: flat` and omits `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. || Template structure authority | `page_layouts` owns each page's authoring-input prototype. `pptx_masters` / `pptx_layouts` own the unique reusable output definitions, while `page_pptx_layouts` owns page assignment. Strict keeps the prototype contract; adaptive may create a new Layout definition during page authoring and updates its assignment immediately. Unused definitions may register without a published Slide. Templates validate provenance but never add missing visible page objects during export. |-| Imported-template authoring | `authoring-svg/` plus its `authoring_manifest.json` own edits and source-object identity during create-template. Lossless `svg/` / `svg-flat/` own only immutable native payload and fallback evidence. Materialized `templates/*.svg` own the validated deliverable contract and contain no IR-only source refs. |+| Imported-template authoring | `authoring-svg/` plus its `authoring_manifest.json` own edits and source-object identity during create-template. Lossless `svg/` owns immutable native payload and fallback evidence; optional `svg-flat/` owns only complete-page verification. Materialized `templates/*.svg` own the validated deliverable contract and contain no IR-only source refs. || Legacy structure migration | [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) owns conversion of old unmapped/distilled/preserve structured projects and legacy template packages into the current template contract. An intentional free-design or brand-only `flat` project is not a migration input. The exporter does not migrate or visually cluster legacy template structure. || Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. || SVG source | `svg_output/` is the only author source for generated pages. |diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex e7233c40..74de146c 100644--- a/skills/ppt-master/references/template-designer.md+++ b/skills/ppt-master/references/template-designer.md@@ -25,13 +25,13 @@ When the workflow provides a PPTX reference source, the effective input package- `manifest.json` — single source of truth for source-deck facts (slide size, theme, per-master themes, assets, asset map, placeholders, layouts, masters, slides, SVG file paths, page-type candidates)- `native_structure.json` — stable source master/layout keys, picker names, parent-master relationships, placeholder type/index/geometry, source hash, and source-graph quality facts- `source_template.pptx` — byte-preserved analysis copy for visual/package cross-checking; never a final template asset-- `summary.md` — short orientation digest derived from manifest.json+- `conversion-report.json` — source-recovery and fidelity diagnostics, when present- exported `assets/`- `svg/master_*.svg` / `svg/layout_*.svg` — immutable layered native-payload backing; every master / layout in the deck rendered once, including ones no sample slide references- `svg/slide_NN.svg` — immutable slide-local native-payload backing; do not bulk-read because opaque native payload is retained- `svg/inheritance.json` — which layout / master each slide consumes-- `svg-flat/slide_NN.svg` — immutable complete-page native-payload/visual backing; do not use it as the editable source-- `authoring-svg/` / `authoring-svg-flat/` — lightweight non-destructive IR bundles created by `svg_authoring_view.py`; each contains editable SVGs plus `authoring_manifest.json`+- optional `svg-flat/slide_NN.svg` — immutable complete-page verification backing generated only when explicitly requested; do not use it as the editable source+- `authoring-svg/` and optional `authoring-svg-flat/` — lightweight non-destructive IR bundles created by `svg_authoring_view.py`; each contains editable SVGs plus `authoring_manifest.json`- optional screenshots for visual cross-checkingPPTX import interpretation:@@ -45,9 +45,9 @@ Input priority for PPTX-backed template creation depends on replication mode:| Mode | Authoritative inputs | Model-facing inputs ||---|---|---|| `standard` / `fidelity` | Finalized brief for the newly designed output; `manifest.json` for factual canvas/theme/assets | `authoring-svg/` and optional `authoring-svg-flat/` IR documents plus exported assets as visual references. Source Master/Layout topology is informational only and is not mined into output structure. |-| `mirror` | `manifest.json`, `native_structure.json`, `svg/inheritance.json`, and the authoring manifests | Layered `authoring-svg/` as the editable restoration IR; `authoring-svg-flat/` for complete-page verification; matching lossless `svg/` / `svg-flat/` only as immutable payload backing. |+| `mirror` | `manifest.json`, `native_structure.json`, `svg/inheritance.json`, and the authoring manifests | Layered `authoring-svg/` as the editable restoration IR; optional `authoring-svg-flat/` for complete-page verification; matching lossless `svg/` and optional `svg-flat/` only as immutable backing. |-Use `summary.md` only for orientation. Open screenshots or the original PPTX only for visual cross-checking.+Use the compact facts in `manifest.json` for orientation. Open screenshots or the original PPTX only for visual cross-checking.**Native structure output**: Always set `native_structure_mode: structured`.@@ -143,7 +143,7 @@ Extension page types beyond the canonical four (transition / appendix / disclaimWhen the brief sets `Replication mode: mirror`, restore the imported template rather than designing a new one:-- Authoring source: layered `authoring-svg/*.svg` plus `authoring-svg/authoring_manifest.json`, `svg/inheritance.json`, and `native_structure.json`. Use `authoring-svg-flat/` for full-page verification. Matching lossless `svg/` / `svg-flat/` files are immutable native-payload backing and are resolved only during materialization.+- Authoring source: layered `authoring-svg/*.svg` plus `authoring-svg/authoring_manifest.json`, `svg/inheritance.json`, and `native_structure.json`. When present, use `authoring-svg-flat/` only for full-page verification. Matching lossless `svg/` and optional `svg-flat/` files are immutable backing; materialization resolves only the layered backing.- Precondition: the import evidence identifies every source Master/Layout, parent relationship, picker name, placeholder contract, and fixed visual layer. Stop only when required facts or supported geometry are missing; unused identities are not a stop condition.- Output: `<template_workspace>/templates/<NNN>_<page_type>.svg` for every source slide, plus `layout_<layout_key>.svg` for every source Layout unused by all source slides. `<NNN>` is the zero-padded source slide index (3 digits) and `<page_type>` is derived from `manifest.json` `pageTypeCandidates` — `cover` / `toc` / `chapter` / `content` / `ending`. When the page-type heuristic is ambiguous, fall back to `content`. Preserve source slide order via the numeric prefix; definition-only files are not generated pages.- Required restoration: preserve source Master/Layout keys and picker names, Layout-to-Master parentage, slide assignments, placeholder type/index/bounds, supported native-object metadata, geometry, decoration, sprite-sheet wrappers, original example text, chart previews, fonts, effects, and paint order whenever the importer represents them.diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex ebd79147..c517ae0d 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -87,6 +87,11 @@ python3 scripts/template_preview_pptx.py <template_workspace>python3 scripts/template_preview_pptx.py <legacy_template_workspace> --visual-only```+Template import defaults to the canonical layered `svg/` tree. Use+`--inheritance-mode both` only when a separate self-contained `svg-flat/`+verification tree is required. No derived narrative digest is generated+because `manifest.json` already owns those facts.+`svg_authoring_view.py` creates a lightweight, non-destructive editable IRbundle from PPTX-imported SVGs. It removes embedded `txbody` payloads,duplicate hidden geometry carriers, and import-identity attributes from thediff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex e39af7f8..607b15ec 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -106,15 +106,16 @@ Notes:- Extracts reusable media assets from `ppt/media/`- Summarizes slide size, theme colors, font metadata, and per-master theme metadata- Resolves slide / layout / master relationships from OOXML relationships; every master and layout is included even when no sample slide currently references it-- Generates `manifest.json` (single source of truth for slide size, theme, per-master themes, assets, layouts, masters, placeholders, slides, SVG file paths, and page-type candidates), `summary.md` (short orientation digest), `assets/`, and shape-level SVGs under `svg/`-- **SVG output emits two views by default** (`--inheritance-mode both`):+- Generates `manifest.json` (single source of truth for slide size, theme, per-master themes, assets, layouts, masters, placeholders, slides, SVG file paths, and page-type candidates), `native_structure.json`, `source_template.pptx`, `assets/`, `conversion-report.json`, and shape-level SVGs under `svg/`+- **SVG output defaults to the layered authoring source** (`--inheritance-mode layered`):- `svg/` — layered template view for designers: every master and layout in the deck rendered once as `svg/master_*.svg` / `svg/layout_*.svg` (including ones no sample slide currently references); `svg/slide_NN.svg` contains only that slide's own shapes; `svg/inheritance.json` records parentage plus source-owned `showInheritedShapes` / `showMasterShapes` booleans.- - `svg-flat/` — companion view: each `slide_NN.svg` is self-contained (the effective visible Master/Layout contributions plus Slide-local content painted into one file), so opening any slide in isolation shows the full page like PowerPoint would. Background inheritance remains independent of inherited-shape visibility. Useful for previews, screenshots, and "did this slide actually render correctly" sanity checks.+ - `svg-flat/` — optional verification view emitted only by `--inheritance-mode both`: each `slide_NN.svg` is self-contained (the effective visible Master/Layout contributions plus Slide-local content painted into one file), so opening any slide in isolation shows the full page like PowerPoint would. Background inheritance remains independent of inherited-shape visibility. Useful for previews, screenshots, and "did this slide actually render correctly" sanity checks.- `manifest.json` records `svgFile` for slides / layouts / masters, `flatSvgFile` for slides when `svg-flat/` exists, placeholder type / index / geometry / base style, an asset map used by SVG `href` values, and common assets reused through slide / layout / master inheritance. Placeholder semantics keep `subTitle`, `obj`, `media`, and `dt` distinct as `subtitle`, `object`, `media`, and `date`.+- `conversion-report.json` owns tolerant source-recovery diagnostics; it is not a cache or a duplicate of the structural manifests- Layered slide SVGs keep only the slide's own background; inherited master / layout backgrounds stay in the corresponding master / layout SVGs- Placeholder guides are intentionally lightweight in `svg/` master / layout files; `svg-flat/` hides those guides and is the visual preview source- Charts, SmartArt, diagrams, and OLE objects become typed placeholders in `svg/`; `svg-flat/` shows a preview image with a corner badge when one exists, otherwise a visible placeholder. Tables are converted into real SVG content.-- Pass `--inheritance-mode layered` to skip `svg-flat/`, or `--inheritance-mode flat` for the legacy round-trip view (single self-contained `svg/` tree without master/layout/inheritance files).+- Pass `--inheritance-mode both` to add `svg-flat/`, or `--inheritance-mode flat` for the legacy round-trip view (single self-contained `svg/` tree without master/layout/inheritance files).- SVG export reads OOXML directly via `pptx_to_svg` — no PowerPoint or Keynote dependency, runs on any platform- `<image>` elements in `svg/` reference files in `assets/` directly; pass `--embed-images` to inline as data URIs instead- External linked images and missing media are strict failures. Office vector media such as EMF / WMF are converted to PNG previews when the local toolchain can do so; otherwise the import fails instead of silently dropping content.diff --git a/skills/ppt-master/scripts/pptx_template_import.py b/skills/ppt-master/scripts/pptx_template_import.pyindex 48b32d49..df359572 100644--- a/skills/ppt-master/scripts/pptx_template_import.py+++ b/skills/ppt-master/scripts/pptx_template_import.py@@ -7,15 +7,16 @@ Reads OOXML directly via `pptx_to_svg` and writes a reusable reference workspaceasset inventory, and per-slide / per-layout / per-master metadata- `native_structure.json` + `source_template.pptx` — source-structure facts anda byte-identical analysis copy used to rebuild explicit SVG structure-- `summary.md` — short human-readable digest derived from manifest.json- `assets/` — extracted reusable image assets-- `svg/` — primary view: by default the layered template view (every master+- `conversion-report.json` — source-recovery and fidelity diagnostics emitted+ with SVG conversion+- `svg/` — canonical layered template view (every masterand layout in the deck rendered once each as `master_*.svg` /`layout_*.svg`, slides contain only their own shapes, and an`inheritance.json` describes the reuse graph)-- `svg-flat/` — companion view (default mode "both"): each `slide_NN.svg`- is self-contained — master/layout decoration is inlined — so opening any- one slide shows the full page like PowerPoint would+- `svg-flat/` — optional verification view (`--inheritance-mode both`): each+ `slide_NN.svg` is self-contained, so opening one slide shows the full page+ like PowerPoint would"""from __future__ import annotations@@ -56,8 +57,8 @@ def parse_args() -> argparse.Namespace:"--manifest-only",action="store_true",help=(- "Only extract manifest.json + summary.md + reusable assets + the "- "native structure/source pair, without exporting slides to SVG"+ "Only extract manifest.json + reusable assets + the native "+ "structure/source pair, without exporting slides to SVG"),)parser.add_argument(@@ -68,16 +69,16 @@ def parse_args() -> argparse.Namespace:parser.add_argument("--inheritance-mode",choices=("both", "layered", "flat"),- default="both",+ default="layered",help=("How to render master/layout shapes for slide SVGs. "- "'both' (default): emit both views — svg/ holds the layered "+ "'layered' (default): emit the canonical svg/ tree with master, "+ "layout, and slide-local files plus svg/inheritance.json. "+ "'both': also emit svg-flat/ with self-contained per-slide "+ "verification files. In this mode svg/ still holds the layered ""renderings (template designers see master/layout/slide as "- "separate files plus svg/inheritance.json) and svg-flat/ holds "- "self-contained per-slide SVGs (each one renders correctly when "- "opened on its own). 'layered': only the svg/ tree, useful when "- "you don't need the flat view. 'flat': only self-contained slide "- "SVGs in svg/, the round-trip view used by svg_to_pptx."+ "separate files). 'flat': emit only self-contained slide SVGs "+ "in svg/, the round-trip view used by svg_to_pptx."),)return parser.parse_args()@@ -110,7 +111,13 @@ def main() -> int:manifest_path = output_dir / "manifest.json"if not args.skip_manifest:try:- manifest = build_manifest(pptx_path, output_dir)+ manifest = build_manifest(+ pptx_path,+ output_dir,+ include_flat_svg=(+ not args.manifest_only and args.inheritance_mode == "both"+ ),+ )except (RuntimeError, OSError, ValueError) as exc:print(f"Error: failed to extract PPTX metadata: {exc}")return 1@@ -141,7 +148,6 @@ def main() -> int:f"{native_structure['strategy']['recommendedMode']}")print("Template output mode: explicit SVG structure")- print("Summary: summary.md")print(f"Assets exported: {len(manifest['assets']['allAssets'])}")print(f"Common assets: {len(manifest['assets']['commonAssets'])}")print(f"Slides analyzed: {len(manifest['slides'])}")diff --git a/skills/ppt-master/scripts/template_import/manifest.py b/skills/ppt-master/scripts/template_import/manifest.pyindex efd47bc0..a3310e80 100644--- a/skills/ppt-master/scripts/template_import/manifest.py+++ b/skills/ppt-master/scripts/template_import/manifest.py@@ -11,7 +11,6 @@ It does NOT try to convert arbitrary PPTX shapes into SVG templates.Output contract (single source of truth):<workspace>/manifest.json — all factual metadata (theme, assets, slides, layouts, masters)- <workspace>/summary.md — short human-readable digest derived from manifest.json<workspace>/assets/ — extracted reusable image assetsThis module is a pure library. The CLI entry point lives in@@ -74,7 +73,7 @@ class SlideRecord:placeholders: list[dict[str, Any]]page_type: strsvg_file: str- flat_svg_file: str+ flat_svg_file: str | Nonedef summarize_part_record(@@ -500,68 +499,12 @@ def _effective_inherited_image_assets(return assets-def write_summary(output_path: Path, manifest: dict[str, Any]) -> None:- """Render a short human digest derived from manifest.json.-- This intentionally stays terse: every fact already lives in manifest.json.- The digest exists only so a reviewer can scan the workspace at a glance- without parsing JSON.- """- source_name = manifest["source"]["name"]- slide_size = manifest["slideSize"]- theme = manifest["theme"]- slides = manifest["slides"]- layouts = manifest.get("layouts", [])- masters = manifest.get("masters", [])- common_assets = manifest["assets"]["commonAssets"]- page_type_map = manifest.get("pageTypeCandidates", {})-- lines: list[str] = [- f"# Template Import Summary — {source_name}",- "",- "All facts are stored in `manifest.json`; this digest is for quick scanning only.",- "",- "## Canvas",- f"- Size: {slide_size['width_px']} × {slide_size['height_px']} px",- f"- Theme colors: {', '.join(sorted(theme['colors'].keys())) or 'none detected'}",- f"- Theme fonts: {', '.join(f'{k}={v}' for k, v in theme['fonts'].items()) or 'none detected'}",- "",- "## Inventory",- f"- Slides: {len(slides)}",- f"- Layouts (unique): {len(layouts)}",- f"- Masters (unique): {len(masters)}",- f"- Reusable assets (used by ≥2 parts): {len(common_assets)}",- "",- "## Page-Type Candidates",- ]- if page_type_map:- for ptype, indexes in page_type_map.items():- lines.append(f"- {ptype}: slides {', '.join(str(i) for i in indexes)}")- else:- lines.append("- (none classified)")-- lines.extend(["", "## Layout Reuse"])- if layouts:- for layout in layouts:- users = layout.get("usedBySlides", [])- users_str = ", ".join(str(i) for i in users) if users else "n/a"- lines.append(f"- {layout['name']} → slides {users_str}")- else:- lines.append("- (none)")-- lines.extend(["", "## Master Reuse"])- if masters:- for master in masters:- users = master.get("usedBySlides", [])- users_str = ", ".join(str(i) for i in users) if users else "n/a"- lines.append(f"- {master['name']} → slides {users_str}")- else:- lines.append("- (none)")-- output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")---def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:+def build_manifest(+ pptx_path: Path,+ output_dir: Path,+ *,+ include_flat_svg: bool = False,+) -> dict[str, Any]:with zipfile.ZipFile(pptx_path, "r") as zf:presentation_root = load_xml_from_zip(zf, "ppt/presentation.xml")if presentation_root is None:@@ -755,7 +698,9 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:placeholders=placeholders,page_type=page_type,svg_file=slide_svg_filename(index),- flat_svg_file=slide_svg_filename(index),+ flat_svg_file=(+ slide_svg_filename(index) if include_flat_svg else None+ ),))@@ -875,5 +820,4 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:],}- write_summary(output_dir / "summary.md", manifest)return manifestdiff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 7305befc..805c0653 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -77,12 +77,12 @@ Branch by the type of reference source the user supplied. This step produces ana| Type | What the user supplied | Tool / read path | Replication modes available ||------|-------------------------|------------------|------------------------------|-| **A** `.pptx` reference | A `.pptx` file path | `pptx_template_import.py` → `manifest.json` + `native_structure.json` + `source_template.pptx` + layered/flat SVGs + `assets/` | `standard` / `fidelity` / `mirror` |+| **A** `.pptx` reference | A `.pptx` file path | `pptx_template_import.py` → `manifest.json` + `native_structure.json` + `source_template.pptx` + layered SVGs + `assets/`; flat verification SVGs are opt-in | `standard` / `fidelity` / `mirror` || **B** Existing SVG assets | `projects/<x>/svg_output/`, a current template workspace root, a legacy flat template root, or a loose `.svg` folder | Normalize the source directory, create an editable authoring IR bundle with `svg_authoring_view.py`, then use its page SVGs; also read companion `design_spec.md` / `spec_lock.md` when present | `standard` / `fidelity`; `mirror` only when the source already carries a complete explicit Master/Layout/placeholder/native-object contract || **C** Image / visual references | Screenshot folder, single image, PDF pages | `ls` + `Read` each file (multimodal visual recognition) | `standard` only || **D** No reference source | Verbal description only ("McKinsey style", "tech blue", "dark minimal") | — | `standard` only |-`fidelity` and `mirror` are not available for type C / D — visual references and verbal-only briefs cannot drive page-by-page replication. Type A is the canonical mirror path: `manifest.json`, `native_structure.json`, layered lossless `svg/`, complete-page lossless `svg-flat/`, and inheritance facts are the restoration authority. In `standard` / `fidelity`, those files supply factual canvas/asset/visual references only and do not define output topology.+`fidelity` and `mirror` are not available for type C / D — visual references and verbal-only briefs cannot drive page-by-page replication. Type A is the canonical mirror path: `manifest.json`, `native_structure.json`, layered lossless `svg/`, and inheritance facts are the restoration authority. Optional `svg-flat/` files are complete-page verification views, never restoration input. In `standard` / `fidelity`, the imported facts and visuals do not define output topology.**Type B source normalization**: when the supplied root contains `templates/design_spec.md`, use `<input>/templates/` as the SVG/spec source and resolve its workspace assets from sibling `<input>/images/` and `<input>/icons/`. Otherwise, use the supplied directory itself as the legacy-flat/loose SVG source. Directory flatness is not a semantic-structure signal.@@ -108,16 +108,17 @@ This produces, in one workspace:- `manifest.json` — single source of truth: slide size, theme colors, fonts, per-master theme summaries, asset inventory, placeholder metadata, SVG file paths, per-slide / per-layout / per-master metadata (including source-owned inherited-shape visibility), page-type candidates- `native_structure.json` — analysis contract: stable master/layout keys, layout picker names, placeholder type/index/geometry, inherited-shape visibility, source hash, and source-graph quality facts- `source_template.pptx` — byte-preserved analysis copy for visual/package cross-checking; it is not copied into the final template package-- `summary.md` — short human-readable digest derived from manifest.json (for quick scanning only)- `assets/` — extracted reusable image assets; `manifest.json` owns the asset-name mapping and SVG `href` values reuse that mapping+- `conversion-report.json` — source-recovery and fidelity diagnostics; retain it for audit because these warnings are not duplicated in the structural manifests- `svg/` — **primary view** (layered template view):- `svg/master_*.svg` — every slide master in the deck rendered once, including masters that no sample slide currently uses (template packages routinely ship more masters than the visible samples reference)- `svg/layout_*.svg` — every slide layout in the deck rendered once (its own contribution; master shapes do **not** repeat here)- `svg/slide_NN.svg` — each slide's own shapes and slide-local background; master / layout shapes and backgrounds are **not** inlined here- `svg/inheritance.json` — which Layout/Master each Slide consumes plus source-owned `showInheritedShapes` / `showMasterShapes` booleans; Layout shapes follow the Slide's `showInheritedShapes`, while Master shapes require that value and the referenced Layout's `showMasterShapes`; backgrounds remain independent-- `svg-flat/` — **companion view** (one self-contained SVG per slide):+- `svg-flat/` — **optional verification view** (only with `--inheritance-mode both`; one self-contained SVG per slide):- `svg-flat/slide_NN.svg` — effective Master/Layout contributions permitted by the source visibility flags plus Slide-local content, painted into one SVG so opening any slide on its own shows the full page like PowerPoint would. Background inheritance remains independent. Use this for previews / screenshot pipelines / "what does the slide actually look like" sanity checks.-- The default `--inheritance-mode both` emits both views. Pass `layered` to skip `svg-flat/`, or `flat` for round-trip use cases (legacy: `svg/` becomes self-contained slides without the master/layout/inheritance files).+- The default `--inheritance-mode layered` emits only the canonical layered view. Pass `both` when a separate complete-page verification tree is worth the storage cost, or `flat` for round-trip use cases (legacy: `svg/` becomes self-contained slides without the master/layout/inheritance files).+- The importer does not generate a duplicate narrative summary or persistent SVG-size CSV. Read compact facts from `manifest.json`; run ad hoc size measurements outside the canonical workspace when needed.Import fidelity rules:@@ -129,10 +130,15 @@ It is a reconstruction aid, not a final direct template conversion.**Lossless payload backing + editable authoring IR**:-Keep `<import_workspace>/svg/` and `<import_workspace>/svg-flat/` unchanged as lossless native-payload backing. Before the Template_Designer reads or edits any imported page SVG, create non-destructive authoring IR bundles:+Keep `<import_workspace>/svg/` unchanged as lossless native-payload backing. If the optional `<import_workspace>/svg-flat/` verification tree was requested, keep it unchanged too. Before the Template_Designer reads or edits any imported page SVG, create the canonical non-destructive authoring IR bundle:```bashpython3 skills/ppt-master/scripts/svg_authoring_view.py "<import_workspace>/svg" -o "<import_workspace>/authoring-svg" --projection-kind layered+```++Only when the import explicitly used `--inheritance-mode both`, create the optional complete-page verification IR:++```bashpython3 skills/ppt-master/scripts/svg_authoring_view.py "<import_workspace>/svg-flat" -o "<import_workspace>/authoring-svg-flat" --projection-kind flat```@@ -155,11 +161,12 @@ Factor large decorative vector groups out of the lightweight IR documents so the# layered view — primary read surface and canonical extracted-vector inventorypython3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authoring-svg" --icons-dir "<import_workspace>/icons" --icon-namespace imported --inplace --id-prefix layered --min-decoration-bytes 3000 --clean-stale-# flat view — reuse matching layered assets; only genuinely flat-only vectors create new assets+# optional flat verification view — run only when authoring-svg-flat/ exists;+# reuse matching layered assets so only genuinely flat-only vectors create filespython3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authoring-svg-flat" --icons-dir "<import_workspace>/icons" --icon-namespace imported --reuse-inventory "<import_workspace>/authoring-svg_vector_asset_inventory.json" --inplace --id-prefix flat --min-decoration-bytes 3000 --clean-stale```-The authoring SVGs in `<import_workspace>/authoring-svg/` / `<import_workspace>/authoring-svg-flat/` are rewritten in place with compact `<use data-icon="imported/..."/>` placeholders. Extracted assets have one canonical copy under `<import_workspace>/icons/imported/`; never duplicate them under `templates/icons/`. The root `icons/` directory remains a namespace container and must not contain rewritten page SVGs or inventories. The inventory is written beside the processed IR directory and records every preserved `data-pptx-source-ref`; re-inlining an asset therefore restores the referenced object mapping before materialization. The existing icon embedding path re-inlines the extracted assets before final export, preserving multi-color artwork and non-square viewBox geometry as native SVG shapes. Text-bearing groups are never extracted; text must stay readable/editable in the working SVG. Extraction triggers on either many drawable elements or a large pure-vector XML block, so long single-path illustrations are factored out too. Pure-vector decoration runs inside text-bearing groups use a lower size threshold, allowing card borders and decorative paths to be extracted without hiding text. Referenced defs (`gradient` / `pattern` / `filter` / `clipPath` / `marker`) are copied into each asset and namespaced so the asset is self-contained after re-inline. If both layered and flat views are processed into the same icon namespace, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix inside the selected namespace; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.+The authoring SVGs in `<import_workspace>/authoring-svg/` and, when requested, `<import_workspace>/authoring-svg-flat/` are rewritten in place with compact `<use data-icon="imported/..."/>` placeholders. Extracted assets have one canonical copy under `<import_workspace>/icons/imported/`; never duplicate them under `templates/icons/`. The root `icons/` directory remains a namespace container and must not contain rewritten page SVGs or inventories. The inventory is written beside the processed IR directory and records every preserved `data-pptx-source-ref`; re-inlining an asset therefore restores the referenced object mapping before materialization. The existing icon embedding path re-inlines the extracted assets before final export, preserving multi-color artwork and non-square viewBox geometry as native SVG shapes. Text-bearing groups are never extracted; text must stay readable/editable in the working SVG. Extraction triggers on either many drawable elements or a large pure-vector XML block, so long single-path illustrations are factored out too. Pure-vector decoration runs inside text-bearing groups use a lower size threshold, allowing card borders and decorative paths to be extracted without hiding text. Referenced defs (`gradient` / `pattern` / `filter` / `clipPath` / `marker`) are copied into each asset and namespaced so the asset is self-contained after re-inline. If both layered and flat views are processed into the same icon namespace, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix inside the selected namespace; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.The layered pass owns the canonical extracted-vector pool. Each new asset records a source fingerprint before generated ID namespacing. The flat pass MUST consume the layered inventory through `--reuse-inventory`: an exact fingerprint match writes only a `<use>` reference to the existing layered asset, while an unmatched flat-only subtree may create one new asset under the `flat` prefix. Do not independently extract the two views into parallel asset sets. With `--clean-stale`, a rerun also removes obsolete generated `flat_*` duplicates while retaining every reused layered reference.@@ -196,7 +203,8 @@ Master/Layout ownership. Do not apply it to placeholders, individual importednative shapes, native table/chart fallbacks, icon placeholders, or compactauthored presets. `mirror` must keep the source native group/picture identityand therefore must not use this normalization. The original lossless `svg/`-and `svg-flat/` trees remain unchanged and authoritative.+tree remains unchanged and authoritative. Any optional `svg-flat/` tree remains+unchanged but is verification-only.`extract_svg_assets.py` remains a different operation: it factors vectors outfor model readability and re-inlines them as native shapes before export. It@@ -209,13 +217,13 @@ does not turn those vectors into a picture.| `standard` / `fidelity` | `manifest.json`, exported assets, `svg/inheritance.json`, `authoring-svg/authoring_manifest.json`, and every cleaned layered IR document (`authoring-svg/master_*.svg` / `layout_*.svg` / `slide_NN.svg`). The layered IR is the complete read surface: it covers Layouts unused by any sample slide (invisible in `svg-flat/` yet still template vocabulary), and per-page composition follows from `inheritance.json`. Cleaned flat pages are optional composition spot checks, not a required second pass over the same shapes. Source topology remains non-binding; the two modes differ in output design (`fidelity` designs a broader roster covering the useful visual range), not in read coverage. || `mirror` | `manifest.json`, `native_structure.json`, `svg/inheritance.json`, `authoring-svg/authoring_manifest.json`, and every cleaned layered Master/Layout/Slide IR document. The layered `authoring-svg/` tree is the sole editable and materialization input. Cleaned `authoring-svg-flat/` slides are optional visual composition checks only; never edit or feed them into template materialization. Materialization may resolve unchanged refs against the matching lossless backing without placing opaque payload in model context. |-Use `summary.md` only for orientation. Use screenshots or the original PPTX only for visual cross-checking. Do not bulk-read opaque lossless payload into model context.+Use the compact facts in `manifest.json` for orientation. Use screenshots or the original PPTX only for visual cross-checking. Do not bulk-read opaque lossless payload into model context.Interpretation rule (carries forward into Steps 2 and 4):- `manifest.json` is the source of truth for facts about the source deck: slide size, theme colors, fonts, background inheritance, reusable asset inventory, declared source layout/master structure, and slide reuse relationships. It dictates mirror restoration facts but not `standard` / `fidelity` output topology.- `native_structure.json` is the source of truth for source PowerPoint identity: stable layout keys, picker names, parent masters, placeholder types/indices, and the source-package hash. Mirror preserves those facts one-to-one. `standard` / `fidelity` do not mine them into the new structure.-- `summary.md` is a quick scan; never treat it as the canonical fact source — go back to `manifest.json` if anything is unclear+- `manifest.json`, `native_structure.json`, and `svg/inheritance.json` intentionally overlap only at contract boundaries so materialization can cross-check source identity, graph ownership, and visibility; do not collapse them into a cache or substitute one for another- exported `assets/` are the canonical reusable image pool — `<image>` references in `svg/` already point at these files directly- exported `icons/imported/*.svg` files are the canonical reusable vector illustration pool, but they are **not** part of the default read set. Read the cleaned SVGs and `*_vector_asset_inventory.json` first; open a specific imported SVG only when the cleaned page or inventory shows that the extracted asset is relevant to the current design decision. This is what makes the SVG work surface smaller.- cleaned layered authoring SVGs are the mirror editing and verification surface; they expose source ownership without requiring the model to read opaque payload. Do not use them to promote, demote, merge, or split source structure.@@ -254,7 +262,7 @@ Distinguish observed facts from template rules: "`slide_07` uses a left photo crDo not treat authoring IR documents as final template assets. `standard` / `fidelity` author new SVGs from the confirmed brief and IR references. Mirror edits the IR and materializes it with lossless native-payload backing.-> **Mirror-mode restoration path** — use `native_structure.json`, `svg/inheritance.json`, and the authoring manifest as structural/provenance authority. The cleaned layered IR is the editable source; lossless layered/flat SVGs are immutable payload backing. Preserve roster, appearance, ownership, placeholders, converter-supported native metadata, and available SVG fallbacks; do not synthesize a different graph.+> **Mirror-mode restoration path** — use `native_structure.json`, `svg/inheritance.json`, and the authoring manifest as structural/provenance authority. The cleaned layered IR is the editable source and lossless layered SVGs are immutable payload backing; optional flat SVGs are verification-only. Preserve roster, appearance, ownership, placeholders, converter-supported native metadata, and available SVG fallbacks; do not synthesize a different graph.### 1B. Existing SVG assets@@ -333,7 +341,7 @@ Items to surface:| Output scope | Yes | `[decision]` — `library` (default, globally reusable and indexed) or `project` (same portable workspace routing under one initialized project) || Target project | Yes for `project`; N/A for `library` | `[decision]` — explicit path to the initialized target workspace; validate it during the Step 4 preflight || New template ID | Yes | `[decision]` — user chooses ASCII slug; if Chinese brand name, it must be filesystem-safe. In library scope it also becomes the matching index key |-| Template display name | Yes | `[decision]` (often the source deck title — `[suggested]` from `summary.md` for type A) |+| Template display name | Yes | `[decision]` (often the source deck title — `[suggested]` from `manifest.json.source.name` for type A) || Category | Yes | `[decision]` — one of `brand` / `general` / `scenario` / `government` / `special` || Applicable scenarios | Yes | `[suggested]` from analysis; user confirms || Tone summary | Yes | `[suggested]` from analysis (e.g. `Modern, restrained, data-driven`) |@@ -422,7 +430,7 @@ If the input source is type A, pass the following internal package to the role:- finalized brief from Step 3- `manifest.json`- `native_structure.json` and `source_template.pptx`-- `summary.md` (orientation only)+- `conversion-report.json` when source-recovery diagnostics exist- exported `assets/`- `*_vector_asset_inventory.json`, when the vector readability pass extracted assets; do not bulk-read `icons/imported/*.svg`- editable layered IR documents and manifest from `authoring-svg/`; optional `authoring-svg-flat/` is a visual cross-check only and never a template materialization input@@ -508,7 +516,7 @@ Downstream, both template-adherence choices use `pptx_structure.mode: structured**Mirror-mode restoration contract** (type A or B): when `Replication mode: mirror`, the Template_Designer role:1. **Restores one output SVG per source page** in `<template_workspace>/templates/`. Edit and normalize the matching `authoring-svg/` IR document, then materialize it with the authoring manifest, native structure facts, and immutable payload backing. Type A must use `mirror_template_materialize.py`; do not hand-copy or independently rebuild its graph. Preserve source Master/Layout keys and picker names, Layout parentage, slide assignment, placeholder type/index/bounds, inherited-shape visibility, ownership, paint order, and supported native metadata. Mechanical namespace, root-declaration, asset-path, and fixed-layer group normalization is allowed only when source ownership and appearance remain unchanged.- - Type A authoring source: `<import_workspace>/authoring-svg/` plus its `authoring_manifest.json`; `<import_workspace>/svg/`, `<import_workspace>/svg-flat/`, `svg/inheritance.json`, and `native_structure.json` provide payload and structural backing+ - Type A authoring source: `<import_workspace>/authoring-svg/` plus its `authoring_manifest.json`; `<import_workspace>/svg/`, `svg/inheritance.json`, and `native_structure.json` provide payload and structural backing. Optional `<import_workspace>/svg-flat/` is verification-only.- Type B authoring source: `<svg_analysis_workspace>/authoring-svg/` plus its manifest; the complete explicit source SVG contract is immutable backing- For every source Layout unused by all source slides, additionally materialize one definition-only SVG named `layout_<layout_key>.svg` from its layered authoring IR document and payload backing. It carries the exact root identity, fixed atoms, and placeholder contract but is not a generated page assignment. Use source placeholder prompts/carriers; do not invent business content. This definition SVG lets downstream export register the Layout and any otherwise-unused parent Master without retaining an internal carrier slide.2. **Renames each file** using the source-order-first convention `<NNN>_<page_type>.svg`, where `<NNN>` is the source-order index zero-padded to 3 digits and `<page_type>` is typically `cover` / `toc` / `chapter` / `content` / `ending` (fall back to `content` when the type cannot be confidently classified). Examples: `001_cover.svg`, `002_toc.svg`, `003_content.svg`, ..., `050_ending.svg`.