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(template-creation): align authored and mirror contracts

hugohe333d80a59520e
diff --git a/docs/faq.md b/docs/faq.md
index 247d8a92..3aa80a9b 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -240,7 +240,9 @@ Want to turn a PPT you love into a reusable template for PPT Master? Here's how:
**Step 1 — Prepare Reference Material**
-The recommended input is the original `.pptx`. PPT Master extracts theme identity, the complete Master/Layout topology, placeholder metadata, and reusable assets, then reconstructs every source Master and Layout as complete structured SVG pages. Source Master/Layout groups are flattened object by object into direct atomic layer elements; supported appearance, parent relationships, picker names, placeholder type/index/bounds, and stacking order are retained, but the source group-editing hierarchy is not. When that template is used, `adaptive` may create a new explicit Layout under the retained Master; `strict` preserves the selected Master/Layout/slot contract.
+The recommended input is the original `.pptx`. PPT Master extracts theme identity, declared Master/Layout topology, placeholder metadata, native-shape evidence, and reusable assets. `standard` and `fidelity` use the source as visual reference and author a new SVG roster plus a new Master/Layout/slot system; they neither preserve nor distill source topology. `mirror` instead restores source slide order, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`.
+
+Large imported SVGs may contain native-shape metadata, hidden carriers, and preview fingerprints. That lossless representation stays in the temporary analysis workspace, while the model reads a lightweight inspection projection. The projection is never an export source. `standard` / `fidelity` use compact canonical metadata. Mirror materializes from the lossless source, reuses only metadata already supported by the converter on unchanged Slide-local/slot objects, and keeps an SVG fallback for unsupported or edited objects.
If no source PPTX exists, screenshots of the key page types still work — cover, TOC, chapter, content, and closing — but geometry, fonts, and inheritance must then be inferred visually.
@@ -252,13 +254,13 @@ Use an AI coding agent (Claude Code, Codex, etc.) and ask it to use the **PPT Ma
- Desired tone and color palette (e.g., "modern and restrained, dark blue primary")
- Category preference (`brand` / `general` / `scenario` / `government` / `special`)
- Canvas format, if not the default 16:9
-- Output scope: indexed `library` (default) or one already initialized `project`; both use the same complete workspace shape
+- Output scope: indexed `library` (default) or one already initialized `project`; both use the same workspace routing and omit empty optional asset directories
You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (output scope, template ID, theme mode, etc.).
**Step 3 — Wait for the Result**
-The AI agent will handle the rest — analyzing your screenshots, building the layout definitions, validating the template, and exporting `exports/<id>_template_preview.pptx` for visual review in PowerPoint. Both scopes contain the same `templates/`, `images/`, `icons/`, and `exports/` core: library scope writes `skills/ppt-master/templates/<kind>/<id>/` and registers it; project scope writes `projects/<name>/` and skips registration. Give that workspace root to Step 3. Older flat packages with `design_spec.md` at the root remain compatible, and flat placement alone is not a reason to run structure restoration. Because the new workspace shapes match, a complete result can be migrated or reused between the two locations without restructuring it.
+The AI agent will handle the rest — analyzing your references, building the layout definitions, and validating the template. If you request PowerPoint review, it also generates `exports/<id>_template_preview.pptx` on demand. Both scopes require `templates/` and use optional `images/`, `icons/`, and `exports/`: library scope writes `skills/ppt-master/templates/<kind>/<id>/` and registers it; project scope writes `projects/<name>/` and skips registration. Empty optional directories are omitted. Give that workspace root to Step 3; it never copies `exports/`, and library review exports are Git-ignored. Older flat packages with `design_spec.md` at the root remain compatible, and flat placement alone is not a reason to run structure restoration.
> **Tip**: The more specific you are about the style and use case, the better the generated template will match your expectations.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 51f64603..77bf1c4d 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -31,16 +31,16 @@ For the first, give the AI your `.pptx` plus your material (or a topic) and ask
You: Replicate this as a template via /create-template: projects/brand/our_deck.pptx
```
-That runs `pptx_template_import.py` and rebuilds the file into a reusable workspace — layout SVGs + `design_spec.md` + extracted theme colors, fonts, and images. It also exports `exports/<id>_template_preview.pptx`, so you can open the reconstructed template in PowerPoint and judge it before generation. The workspace root is what you point to at generation time.
+That runs `pptx_template_import.py` and rebuilds the file into a reusable workspace — layout SVGs + `design_spec.md` + extracted theme colors, fonts, and images. If you want a PowerPoint review file, run the optional preview export; it creates `exports/<id>_template_preview.pptx` on demand. The workspace root is what you point to at generation time.
-During the create-template brief, choose `library` (the existing default) or `project`. Both create the same complete `templates/`, `images/`, `icons/`, and `exports/` workspace. Project scope requires an initialized target project; library scope alone adds global registration.
+During the create-template brief, choose `library` (the existing default) or `project`. Both require `templates/` and use optional `images/`, `icons/`, and on-demand `exports/`; empty optional directories are omitted. Project scope requires an initialized target project; library scope alone adds global registration.
A created template lives in one of two places:
| Location | Path | Notes |
|---|---|---|
-| **Registered in the skill library** | `skills/ppt-master/templates/<kind>/<id>/` | Complete workspace plus global registration, so it appears when you ask "what templates are available?" |
-| **Under projects** | `projects/<name>/` | The same complete workspace without global registration |
+| **Registered in the skill library** | `skills/ppt-master/templates/<kind>/<id>/` | Portable workspace plus global registration, so it appears when you ask "what templates are available?" |
+| **Under projects** | `projects/<name>/` | The same portable workspace without global registration |
Invoke either result by giving its **workspace-root path** in chat. Step 3 resolves `templates/design_spec.md`; for compatibility it also accepts older flat packages whose `design_spec.md` is directly at the supplied root. A create-template run may hand its exact validated workspace root directly to Step 3 in the same conversation. Both cases stay path-based; a bare template name never triggers. The complete workspace can be copied or migrated between the library and `projects/` without restructuring it; only library registration changes.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 450d9183..35ccbc4a 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -51,7 +51,7 @@ The past two months' structural capability growth. Single flags / incremental po
- **Prompt constraint-strength decoupling** ([`docs/rules/prompt-style.md`](rules/prompt-style.md) §4) — three explicit strength tiers — rule (`Hard rule` / `Forbidden`) / default (`Default — … may override`) / reference (`Reference — not a constraint`) — plus an "objective failure vs taste" test and a checker boundary, so the model can tell "must keep vs may deviate" at a glance; the visual-style catalog is Reference-strength throughout
- **visual-style catalog grows to 18, aligned with image-renderings + examples reclaimed** — first four distilled from the [examples library](../examples/) (`brutalist` / `blueprint` / `memphis` / `zine`), then six filling in the hand-drawn / textured renderings that have a layout twin (`sketch-notes` / `ink-notes` / `chalkboard` / `paper-cut` / `vintage-poster` / `pixel-art`), then four more reclaimed from still-uncovered example aesthetics: `ink-wash` (rice-paper whitespace, from Cangzhuo / Li Ziqi) · `glassmorphism` (dark frosted-glass + gradient light, from glassmorphism_demo, split out of soft-rounded) · `photo-editorial` (full-bleed photography dominates, text captions, from Pritzker / fashion_weekly) · `data-journalism` (Bloomberg/Economist multi-column micro-charts + sidebars, from global_ai_capital). The catalog is regrouped into five families (corporate-product / editorial-publication / expressive-print / hand-drawn-brush / specialty). **The test**: a rendering earns a visual-style twin only when it defines a whole-page layout language, not merely how an inserted image looks — so photo-*led composition* gets `photo-editorial` (paired with corporate-photo), while purely atmospheric renderings (nature / warm-scene / fantasy-animation) stay imagery-only and just pair with a layout style. Zero HEX, Reference strength throughout
- **mode catalog grows to 5: add `briefing`** — fills the "neutral information delivery" cell: no thesis, no story, no teaching, no spectacle — topic titles, even weight, complete and scannable, for status updates / reference decks / catalogs / meeting packs / FAQs that inform without arguing. The five now partition presentation *intent* more nearly MECE: persuade (pyramid) · tell a story (narrative) · teach (instructional) · impress (showcase) · simply inform (briefing). `_index` gains a `briefing` vs `pyramid` tie-breaker ("if you'd have to invent a thesis to fit pyramid, it's briefing"). Five presets plus a `custom` escape hatch for a bespoke direction none of them captures (a special cadence, a multi-mode fusion, a particular posture) — either user-requested or Strategist-recommended, confirmed like every lock; a deck always locks one value, and a fusion is one `custom` describing the acts. The only thing to avoid is defaulting to `custom` when a preset genuinely fits. Mirrors the truth-precedence rule that a user-authored outline or direction overrides the mode
-- **mode / visual-style system validated on real decks + four calibration tightenings landed** — the 5 modes + 18 visual-styles + the `custom` escape hatch were exercised on five covering decks (briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine, with the narrative deck going through the AI-image branch): **zero selection misses** (all four Close-calls tie-breakers fired and held against the real grey-zone pulls), **discipline fully honored** (zero HEX / Reference strength / whole-page layout language), **the `custom` mechanism works** (a `mode_behavior` prose paragraph carried a 10-page generation and reads as plain language at confirmation, not a bare token), **mode ⟂ visual_style holds** (any combination without bleed, including a positive check of the "keynote/launch = mode not style" route), export 5/5 decks × every page with 0 failures. Tightened four spots from the real signal: `strategist §e` now locks the full neutral tier set the visual_style implies up front (killing the mid-deck color top-ups seen in three consecutive decks), `executor-base §1` re-skins chart/layout template gradients-shadows-fills to the deck's visual_style (templates supply structure, not skin; mirror templates stay verbatim per §1.1), `briefing §1` makes `core_message` state coverage rather than a claim (briefing-only; global §IX assertion semantics stay for narrative/instructional/pyramid), and `svg_quality_checker` fixes font-family drift false positives (delimiter-matched capture + stack normalization) and drops the font-size ceiling for showcase mode and poster visual-styles
+- **mode / visual-style system validated on real decks + four calibration tightenings landed** — the 5 modes + 18 visual-styles + the `custom` escape hatch were exercised on five covering decks (briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine, with the narrative deck going through the AI-image branch): **zero selection misses** (all four Close-calls tie-breakers fired and held against the real grey-zone pulls), **discipline fully honored** (zero HEX / Reference strength / whole-page layout language), **the `custom` mechanism works** (a `mode_behavior` prose paragraph carried a 10-page generation and reads as plain language at confirmation, not a bare token), **mode ⟂ visual_style holds** (any combination without bleed, including a positive check of the "keynote/launch = mode not style" route), export 5/5 decks × every page with 0 failures. Tightened four spots from the real signal: `strategist §e` now locks the full neutral tier set the visual_style implies up front (killing the mid-deck color top-ups seen in three consecutive decks), `executor-base §1` re-skins chart/layout template gradients-shadows-fills to the deck's visual_style (templates supply structure, not skin; mirror templates retain their declared prototype paint per §1.1), `briefing §1` makes `core_message` state coverage rather than a claim (briefing-only; global §IX assertion semantics stay for narrative/instructional/pyramid), and `svg_quality_checker` fixes font-family drift false positives (delimiter-matched capture + stack normalization) and drops the font-size ceiling for showcase mode and poster visual-styles
- **Optional spec-review checkpoint shipped** ([`workflows/refine-spec.md`](../skills/ppt-master/workflows/refine-spec.md)) — an opt-in pause after the Strategist confirmation stage: when the user explicitly asks (default OFF), the Strategist produces the full `design_spec.md` + `spec_lock.md`, then stops so the user can revise any part of the spec (outline / color / typography / layout / image strategy / page rhythm) before generation, keeping both files in sync. Same shape as the split-mode note — it never fires on its own, the default pipeline is unchanged, and it surfaces as one opt-in line inside the Strategist confirmation stage. Review lenses (logical clarity / information density / focus / register / emotional resonance / chapter balance + the design dimensions) give a direction only, never a numeric threshold (`Reference` strength). Prompted by [@cuberoocp](https://github.com/cuberoocp) in [issue #173](https://github.com/hugohe3/ppt-master/issues/173)
- **Interactive visual Strategist confirmation stage page (Step 4)** ([`scripts/confirm_ui/server.py`](../skills/ppt-master/scripts/confirm_ui/server.py), field schema [`scripts/docs/confirm_ui.md`](../skills/ppt-master/scripts/docs/confirm_ui.md)) — the Strategist confirmation stage moves from chat-only to a browser page that auto-launches by default at Step 4. Template adherence appears only for deck/layout templates and defaults to `adaptive`: every page still maps to the template architecture, while unmatched compositions may create a new explicit Layout under the same Master. `strict` keeps the selected Layout contracts unchanged. The page shares port `5050` with Live Preview and writes authoritative choices to `result.json`.
- **A batch of source-conversion fidelity gains** — less information dropped as source material enters the pipeline: `doc_to_md` converts Word OMML / Office Math equations to inline LaTeX, `pdf_to_md` recognizes `Figure N |` pipe-delimited captions, and `ppt_to_md` preserves hyperlinks already in the source deck (run-level external `[text](url)` / slide-internal jumps `[text](#slide-N)` / shape-level clicks, with dangerous-scheme filtering and anchor-text Markdown escaping) and transcribes native chart data into Markdown tables (values survive the conversion instead of collapsing to a single picture). Caption recognition is based on [@suay1113](https://github.com/suay1113)'s [PR #191](https://github.com/hugohe3/ppt-master/pull/191); hyperlink preservation is distilled from [@ZhaoZuohong](https://github.com/ZhaoZuohong)'s [PR #155](https://github.com/hugohe3/ppt-master/pull/155)
@@ -84,7 +84,7 @@ The past two months' structural capability growth. Single flags / incremental po
- **`--native-objects` hardened from dormant marker to usable opt-in** — the narrow native-object exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts.pptx` to tell it apart from the default flattened-shape export. **The default route is unchanged** — charts/tables still export as SVG-derived DrawingML shapes for cross-renderer fidelity; native objects stay the deliberate opt-in trade documented under Non-goals below
-- **Native package structure + conservative PPTX object round-trip** — every new SVG page declares its final Master/Layout identity while it is authored. Fixed Master/Layout visuals are root-level atoms, reusable slots are bounded top-level groups with real carriers or an explicit composite proxy, and zero-slot Layouts remain valid. Export deterministically compiles only that contract, writes locked title/body sizes into Master `p:txStyles`, and performs final package read-back; it never promotes repeated chrome or infers placeholders. `create-template` restores the source Master/Layout topology into the same explicit SVG model; strict keeps a selected Layout, while adaptive may add a new Layout under the same Master. Library and project outputs now share one complete `templates/` + `images/` + `icons/` + `exports/<id>_template_preview.pptx` workspace shape; only library registration differs. Legacy baseline/template/preserve SVG packages first run `restore-pptx-structure`. Raw one-off PPTX filling remains `template-fill-pptx`.
+- **Native package structure + mode-specific template creation** — every new SVG page declares its final Master/Layout identity while it is authored. Fixed Master/Layout visuals are root-level atoms, reusable slots are bounded top-level groups with real carriers or an explicit composite proxy, and zero-slot Layouts remain valid. Export deterministically compiles only that contract, writes locked title/body sizes into Master `p:txStyles`, and performs final package read-back; it never promotes repeated chrome or infers placeholders. `standard` / `fidelity` author new SVG rosters and new Master/Layout systems without preserving or distilling source topology. `mirror` restores source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Lossless imports stay in analysis and lightweight projections stay inspection-only. Library and project outputs share required `templates/`, optional `images/` / `icons/`, and optional on-demand review output in `exports/`; only library registration differs. Legacy baseline/template/preserve SVG packages first run `restore-pptx-structure`. Raw one-off PPTX filling remains `template-fill-pptx`.
---
@@ -114,11 +114,11 @@ The directions below come up repeatedly and have been evaluated as **not on the
**Issues**: [#53](https://github.com/hugohe3/ppt-master/issues/53), [#118](https://github.com/hugohe3/ppt-master/issues/118)
-PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. A structured PPTX can now be converted into a reviewed reusable package whose master/layout/theme are preserved, but generic "open any PPTX and blindly refill every placeholder" remains a different product shape.
+PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. A structured PPTX can now become a reviewed reusable package in two explicit ways: `standard` / `fidelity` author a new SVG and Master/Layout system from visual evidence, while `mirror` restores the reachable supported source graph. Generic "open any PPTX and blindly refill every placeholder" remains a different product shape.
**The basic need is actually simple**: if you just need "replace Excel data into fixed positions in a PPT template", have the AI write a few lines of `python-pptx`. You don't need this pipeline.
-> **Supported boundaries**: `template-fill-pptx` directly refills selected source slides. `create-template` turns source Master/Layout facts into reviewed, complete, explicitly layered SVG templates. Strict and adaptive downstream use both to reconstruct native structure from those SVG contracts. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.
+> **Supported boundaries**: `template-fill-pptx` directly refills selected source slides. `create-template` either authors a new explicit SVG contract (`standard` / `fidelity`) or restores a supported source contract without semantic synthesis (`mirror`). Strict and adaptive downstream use the resulting declared contract to reconstruct native structure. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.
### Switch to native PowerPoint charts (Excel-native chart)
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 4466d3ee..0a6ac85f 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -97,8 +97,8 @@ Use this table before reasoning about implementation details. Most failed runs s
| Raw PPTX template plus new material/topic | `template-fill-pptx` | clone/fill native slides; no SVG generation |
| Existing PPTX, preserve page count/order/wording 1:1, improve layout | `beautify-pptx` | regenerate through SVG; content and pagination are locked |
| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | `native-enhance-pptx` | direct OOXML patch; no design regeneration |
-| User wants a reusable template workspace from a PPTX or design reference | `create-template` or `create-brand` | outputs a workspace root that later triggers Step 3; create-template also exports a review PPTX |
-| User supplies an explicit template path | main SVG pipeline Step 3 | current Layout/Deck workspaces resolve `templates/design_spec.md`; Brand packages and legacy-flat roots resolve direct `design_spec.md`; restore only legacy SVG semantics |
+| User wants a reusable template workspace from a PPTX or design reference | `create-template` or `create-brand` | outputs a workspace root that later triggers Step 3; create-template can export an on-demand review PPTX |
+| User supplies an explicit template path | main SVG pipeline Step 3 | current Brand/Layout/Deck workspaces resolve `templates/design_spec.md`; compatible legacy-flat roots resolve direct `design_spec.md`; restore only legacy SVG semantics |
| User asks to tune object-level animation order/effect/timing | `customize-animations` | optional export policy via `animations.json` |
| User asks to preview, select, annotate, or re-export browser edits | `live-preview` | browser workflow; annotations apply only at defined handoff points |
@@ -263,19 +263,21 @@ Templates are **opt-in, not default**. The default Strategist flow is free desig
**Why default to free design.** Templates are floors that easily become ceilings: they lock the deck into the template's visual idioms regardless of how the content actually wants to be presented. Free-design layouts derive structure from the source content rather than imposing it from a fixed grammar, so the visual rhythm tracks the content rather than fighting it. Constrained mode is genuinely better in narrow cases (brand-locked decks, strongly-typed scenarios like academic defense or government report), so it stays available — but the AI doesn't proactively reach for it; the user does.
-**Mechanical trigger, not semantic matching.** A bare name like `academic_defense`, a brand mention, or a style phrase such as "McKinsey style" does not trigger Step 3 even if a matching library directory exists. Step 3 consumes an explicit path. Current Layout/Deck workspaces resolve `templates/design_spec.md`; Brand packages keep their direct root `design_spec.md`, as do compatible legacy-flat Layout/Deck packages. Flat placement is not a reason to restore structure; only legacy Master/Layout/placeholder semantics trigger `restore-pptx-structure`. Discoverability is handled by template indexes and explicit Q&A ("what templates are available?"), not by runtime fuzzy matching.
+**Mechanical trigger, not semantic matching.** A bare name like `academic_defense`, a brand mention, or a style phrase such as "McKinsey style" does not trigger Step 3 even if a matching library directory exists. Step 3 consumes an explicit path. Current Brand/Layout/Deck workspaces resolve `templates/design_spec.md`; compatible legacy-flat packages resolve direct `design_spec.md`. Flat placement is not a reason to restore structure; only legacy Master/Layout/placeholder semantics trigger `restore-pptx-structure`. Discoverability is handled by template indexes and explicit Q&A ("what templates are available?"), not by runtime fuzzy matching.
-New `create-template` Layout/Deck outputs use one physical contract in both locations:
+All current Brand/Layout/Deck packages use one workspace routing contract. Brand workspaces omit the SVG roster; empty optional directories are omitted:
```text
<template_workspace>/
├── templates/ # design_spec.md, SVG prototypes, templates/icons/ when used
-├── images/ # bitmap assets referenced as ../images/<name>
-├── icons/ # runtime copy of extracted vector assets
-└── exports/ # <id>_template_preview.pptx
+├── images/ # optional; bitmap assets referenced as ../images/<name>
+├── icons/ # optional; runtime copy of extracted vector assets
+└── exports/ # optional, on-demand review files; Git-ignored in the library
```
-`<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or `projects/<name>/`. Step 3 receives that root. The workspace is portable between locations without reshaping; global index registration is the only scope-specific behavior, and `exports/` is review evidence rather than a template input.
+`<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or `projects/<name>/`. Step 3 receives that root. The workspace is portable between locations without reshaping; global index registration is the only scope-specific behavior. Empty optional directories are absent, and template application never copies `exports/`.
+
+`standard` and `fidelity` write new SVG documents and a new Master/Layout/slot system; source topology is visual evidence only and is neither preserved nor distilled. `mirror` restores source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis. Because structural layers cannot be `<g>`, fixed-layer source group wrappers are mechanically expanded into direct atoms while preserving ownership, paint order, and appearance.
The three template kinds own different segments of the design contract:
@@ -283,7 +285,7 @@ The three template kinds own different segments of the design contract:
|---|---|---|---|
| `brand` | identity | colors, typography, logo, voice, icon style | locks identity; structure remains free |
| `layout` | structure | canvas, page structure, page types, SVG roster | locks structure; identity is confirmed in the Strategist confirmation stage |
-| `deck` | identity + structure + template overview | full replica-style package | locks the full template grammar, with only content-specific choices left |
+| `deck` | identity + structure + template overview | complete identity + structure package | locks the full template grammar, with only content-specific choices left |
When several paths are supplied, fusion is segment-level, not field-level. A brand overrides the identity segment, a layout overrides the structure segment, and a deck supplies the middle/template-overview segment. Same-kind conflicts are surfaced as conflicts rather than resolved by implicit ordering. This keeps template composition debuggable: a fused spec can say exactly which bundle owns each segment.
@@ -462,7 +464,9 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why per-element dispatch, not whole-file translation.** SVG's hierarchical model maps cleanly onto DrawingML's group / shape / picture types — there's no need for a holistic optimizer that re-plans the slide. Each shape kind gets its own narrow translator, which keeps each translator simple enough to debug and unit-test in isolation. The output quality of a slide is the sum of independent local conversions; that property is fragile under whole-file translation but robust under element dispatch.
-**Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is a self-contained visual-preview artifact rather than a PPTX source; users may insert it as an SVG picture, while PowerPoint's manual Convert to Shape command remains outside the supported contract.
+**Why imported and authored shape metadata are separate.** A lossless imported SVG may need native-shape metadata, hidden carriers, and preview fingerprints to recover an advanced PowerPoint shape. That representation stays in the temporary analysis workspace. `svg_authoring_view.py` creates a lightweight inspection projection without opaque payload or duplicate hidden carriers; the projection is never an export source. `standard` / `fidelity` use compact canonical metadata. Mirror materializes from the lossless source and may reuse converter-supported metadata on unchanged Slide-local/slot objects; fixed structural layers remain direct atoms, and unsupported or edited objects keep their current SVG fallback.
+
+**Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; when requested, create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is a self-contained visual-preview artifact rather than a PPTX source; users may insert it as an SVG picture, while PowerPoint's manual Convert to Shape command remains outside the supported contract.
**Why structure is authored before visual generation.** Master and Layout are not post-processing discoveries. Strategist writes the Master roster and complete page mapping before SVG generation; Executor writes those identities, fixed atoms, and slots while composing each page. This keeps free design unconstrained at the visual level while making PowerPoint ownership explicit. Export only compiles declared structure. Legacy or unmapped projects enter `restore-pptx-structure`; they never trigger an exporter heuristic.
@@ -472,15 +476,15 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why reusable bounds are design zones, not measured text boxes.** Slot bounds come from the intended safe area, column, panel inset, or picture frame—not glyph width, line count, or the current content's tight box. The current Slide retains its own authored carrier geometry, so 4:6, 3:7, and 5:5 instances may share one Layout when they express the same semantic composition. Text length therefore cannot accidentally split or mutate the reusable Layout contract.
-**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete input prototype, while `pptx_masters` and `pptx_layouts` record output ownership from planning onward. Strict preserves the prototype contract. Adaptive retains its Master and assigns a new Layout key only when fixed Layout atoms or slot topology/bounds change; that mapping is updated during page authoring rather than inferred later. Non-mirror skin remains project-controlled, while mirror keeps reused visual identities except for the intentional flattening of source Master/Layout groups.
+**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete input prototype, while `pptx_masters` and `pptx_layouts` record output ownership from planning onward. Strict preserves the declared prototype contract. Adaptive retains its Master and assigns a new Layout key only when fixed Layout atoms or slot topology/bounds change; that mapping is updated during page authoring rather than inferred later. Non-mirror skin remains project-controlled, while mirror keeps restored output visual identities.
**Why explicit-Layout text defaults are split between Master and Layout.** Structured export writes locked title/body sizes into Master text defaults. Each generated Layout text slot also copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged.
**Why structured output is read back before publication.** Metadata preflight cannot prove package serialization preserved every relationship and registration. Export therefore reopens the temporary PPTX and validates Presentation → Master → Layout → Slide registration, physical part/content-type rosters, picker identities, exact static-object order, placeholder type/effective index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts before publishing the file.
-**Why reusable templates reconstruct the source topology.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `create-template` reconstructs every source Master and Layout, including unused Layouts, as complete annotated SVG prototypes. Source Master/Layout groups are flattened into atoms; parent relationships, picker names, placeholder identities, and bounds remain auditable in the template specification. The original PPTX remains an analysis input, not a packaged export dependency.
+**Why template creation has authored and restoration modes.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `standard` / `fidelity` use those assets and visuals as references, then author a new topology from the confirmed reusable behavior. Mirror instead restores the source roster and topology one-to-one, allowing only mechanical normalization required by the explicit structured contract. The original PPTX remains analysis evidence, not a packaged export dependency.
-**Why create-template uses one workspace shape in both scopes.** `create-template` keeps `library` as its default indexed output and may instead write under an initialized project. Both roots contain the same `templates/`, `images/`, `icons/`, and `exports/` core, including `<id>_template_preview.pptx`; SVG asset references are identical. This makes the complete workspace migratable and reusable without a library-only package branch or a reduced project branch. The sole scope difference is global index registration, and both use the same `structured` contract.
+**Why create-template uses one workspace routing contract in both scopes.** `create-template` keeps `library` as its default indexed output and may instead write under an initialized project. Both roots require `templates/`; `images/`, `icons/`, and on-demand `exports/` appear only when they contain real files, and SVG asset references are identical. This makes the workspace migratable and reusable without a library-only package branch or a reduced project branch. The sole scope difference is global index registration, and both use the same `structured` contract.
**Why each template SVG stays complete while still compiling to native structure.** A template SVG repeats the inherited Master/Layout visuals together with sample Slide content so it opens as a complete standalone page. During generation, `page_layouts` selects that prototype and the output SVG remains complete. Export removes repeated inherited atoms, emits real Master/Layout parts, and leaves actual slot carriers and Slide-local content on the Slide.
@@ -539,7 +543,7 @@ Standalone workflows are route definitions, not optional decorations. They exist
| `topic-research` | user provides only a topic and no source material | gather web materials before Step 1 |
| `template-fill-pptx` | raw PPTX template + new material/topic | direct native slide clone/fill; no SVG pipeline |
| `beautify-pptx` | existing PPTX, preserve page count/order/wording 1:1, improve layout | regenerate through SVG pipeline with source identity/content locked |
-| `create-template` | build a reusable layout/deck template workspace | output a portable workspace root plus `exports/<id>_template_preview.pptx`; only library scope registers it |
+| `create-template` | build a reusable layout/deck template workspace | output a portable workspace root; optionally generate `exports/<id>_template_preview.pptx`; only library scope registers it |
| `create-brand` | extract or define a reusable brand identity | output `templates/brands/<id>/` |
| `resume-execute` | fresh chat after the planning session; user says to continue a project | enter the execution session without rerunning Strategist |
| `refine-spec` | user explicitly wants to review/refine the spec before generation | stop after full spec/lock for revision, then resume |
diff --git a/docs/templates-architecture.md b/docs/templates-architecture.md
index f1bed606..53f357f5 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -14,12 +14,12 @@
| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template.md` (layout branch) |
| **Deck** | `templates/decks/<id>/` | All segments: identity + structure + middle (template overview) | — | `workflows/create-template.md` (deck branch, default) |
-Every newly created or restored Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. Strict keeps the selected Layout contract; adaptive retains the Master and may create a new Layout identity while authoring. Both export through `pptx_structure.mode: structured`. Packages with legacy Master/Layout semantics first run `restore-pptx-structure`; a legacy flat directory with `design_spec.md` at its root remains a supported compatibility shape and flat placement alone does not trigger restoration.
+Every newly created or restored Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express. `standard` / `fidelity` author new SVGs and new structure without preserving or distilling source topology. Mirror restores the source roster, identities, parentage, placeholder facts, and supported visuals without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Strict keeps the selected declared Layout contract; adaptive retains the Master and may create a new Layout identity while authoring. Both export through `pptx_structure.mode: structured`. Packages with legacy Master/Layout semantics first run `restore-pptx-structure`; a legacy flat directory with `design_spec.md` at its root remains a supported compatibility shape and flat placement alone does not trigger restoration.
The three are **parallel reference bundles**. In library scope, the physical directory and the frontmatter `kind` field correspond one-to-one:
```yaml
-# templates/brands/anthropic/design_spec.md
+# templates/brands/anthropic/templates/design_spec.md
---
kind: brand
...
@@ -46,8 +46,8 @@ native_structure_mode: structured
| Scope | Workspace root | Core workspace | Discovery |
|---|---|---|---|
-| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | `templates/` + `images/` + `icons/` + `exports/` | Register in the matching global index |
-| `project` | `projects/<name>/` | The same `templates/` + `images/` + `icons/` + `exports/` contract | No global index update |
+| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Required `templates/`; optional `images/`, `icons/`, and on-demand `exports/` | Register in the matching global index |
+| `project` | `projects/<name>/` | The same routing contract | No global index update |
Both roots have the same core shape:
@@ -57,17 +57,19 @@ Both roots have the same core shape:
│ ├── design_spec.md
│ ├── *.svg
│ └── icons/ # package/validation copy when used
-├── images/ # every bitmap; SVG href uses ../images/<name>
-├── icons/ # runtime copy of extracted vector assets
-└── exports/
+├── images/ # optional; SVG href uses ../images/<name>
+├── icons/ # optional; runtime vector assets
+└── exports/ # optional; created only for on-demand review
└── <id>_template_preview.pptx
```
-The preview PPTX is derived review evidence, not a source template asset. Step 3 reads the workspace root and consumes `templates/`, `images/`, and `icons/`; it ignores `exports/`.
+Empty optional directories are omitted; do not add placeholder files. An on-demand preview PPTX is derived review evidence, not a source template asset. Step 3 reads the workspace root and consumes `templates/` plus any existing `images/` and `icons/`; it ignores `exports/`. Library `exports/` directories are Git-ignored.
+
+PPTX import uses a two-level metadata model. The temporary lossless SVG keeps native-shape metadata, hidden carriers, and preview evidence; `svg_authoring_view.py` creates a lightweight model-facing projection without opaque payload or duplicate hidden carriers. The projection is never an export source. Authored modes use compact canonical metadata. Mirror may reuse converter-supported metadata on unchanged Slide-local/slot objects; fixed structural layers remain direct atoms, and unsupported or edited objects keep their SVG fallback. Export compiles only the declared SVG structure and never infers ownership.
Both scopes retain `kind: layout` or `kind: deck` in portable frontmatter. `output_scope` and `target_project` stay in the workflow brief and are not persisted into `design_spec.md`.
-Before any final write, resolve the selected workspace root, require an empty `templates/` root, and check all planned image, icon, and preview-PPTX destination filenames for conflicts. Project scope additionally requires an initialized target project. Fail before writing anything; never merge or overwrite.
+Before any final write, resolve the selected workspace root, require an empty `templates/` root, and check all planned image and icon destination filenames for conflicts. Check a preview-PPTX destination only when review export was requested. Project scope additionally requires an initialized target project. Fail before writing anything; never merge or overwrite.
### Segment partition
@@ -81,9 +83,9 @@ To make multi-path fusion override cleanly, every field belongs to a named segme
### Why Deck is its own kind
-A deck is the **full replica** of an existing PPT — the SVG geometry was drawn for that color palette and those typefaces, and identity + structure have been combat-tested together in the source deck. Its value is "validated cohesion", which a free layout + brand combo can't always reach.
+A deck is the **full identity + structure reference** derived from an existing PPT or confirmed design direction — its geometry, color palette, and typefaces form one coherent system. Its value is "validated cohesion", which a free layout + brand combo can't always reach.
-But a deck is **not "an immutable replica"** — it's "a replica that serves as the default base, overridable by explicitly-supplied brand / layout". This gives users maximum freedom: by default you get a complete solution; when needed, swap identity or structure explicitly.
+Its construction depends on replication mode. `standard` / `fidelity` author a new system from visual reference; mirror restores source identities and parentage one-to-one. Once packaged, either form is a complete reference solution that can be overridden by an explicitly supplied brand or layout.
---
@@ -301,10 +303,10 @@ This lets both AI and humans trace which segment came from where.
| User path's `kind` | Step 3 action (per-kind branch) |
|---|---|
-| `kind: brand` | Spec/non-bitmap assets → `<project>/templates/`; logo/illustration/icon bitmaps → `<project>/images/` |
-| `kind: layout` | Spec/SVG roster → `<project>/templates/`; bitmaps → `<project>/images/` |
-| `kind: deck` | Spec/template SVGs/non-bitmap assets → `<project>/templates/`; logo/background/other bitmaps → `<project>/images/` |
-| Multi-path | Fuse one `design_spec.md` per the table above; merge SVG/non-bitmap assets into `templates/` and bitmaps into `images/` |
+| `kind: brand` | Map workspace `templates/` plus existing `images/` and `icons/` to the matching project peers; ignore `exports/` |
+| `kind: layout` | Map workspace `templates/` plus existing `images/` and `icons/` to the matching project peers; ignore `exports/` |
+| `kind: deck` | Map workspace `templates/` plus existing `images/` and `icons/` to the matching project peers; ignore `exports/` |
+| Multi-path | Fuse one `design_spec.md` per the table above, then merge the existing portable roots after resolving collisions |
| Same-kind multiple | Run the "git-style conflict resolution" prompt above to determine the merge |
Bitmaps share the workspace `images/` pool and template SVGs reference them through `../images/`. If the explicit input root is already the target project's root, Step 3 consumes the workspace in place: do not copy it onto itself and do not move its assets again. Otherwise, the complete core workspace is portable: it may be copied from a project root to a library root, from the library to a project, or reused from another workspace without changing its internal structure. Registration is the only scope-specific step.
@@ -319,8 +321,8 @@ When a deck path is supplied, the user already has a complete solution; the Stra
| Workflow | Produces |
|---|---|
-| `workflows/create-brand.md` | brand directory (identity-only), reverse-engineered from brand assets |
-| `workflows/create-template.md` | complete layout or deck workspace. Output scope is `library` by default (`templates/<kind>/<id>/` + registration) or `project` when confirmed (`projects/<name>/`, no registration). Both contain the same core directories and preview PPTX. The internal kind branch still defaults to deck; explicit "structure only / drop the brand color" selects layout |
+| `workflows/create-brand.md` | identity-only brand workspace using the common routes; empty optional directories are omitted |
+| `workflows/create-template.md` | complete layout or deck workspace. `standard` / `fidelity` author new semantic SVGs; mirror restores the source contract. Output scope is `library` by default (`templates/<kind>/<id>/` + registration) or `project` when confirmed (`projects/<name>/`, no registration). Both use the same optional-directory routing; preview PPTX is on demand. The internal kind branch still defaults to deck; explicit "structure only / drop the brand color" selects layout |
In library scope, the frontmatter `kind` field determines which workspace parent is used under `templates/brands/` / `templates/layouts/` / `templates/decks/`. Project scope keeps the same kind semantics at the project workspace root. A complete workspace may migrate between scopes without reshaping; add or remove only the library index registration.
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index 6423d1c3..f309da66 100644
--- a/docs/templates-guide.md
+++ b/docs/templates-guide.md
@@ -18,13 +18,13 @@ The workflow **defaults to free design** — it will not ask whether you want a
### How to enter the template flow
-Send the Layout/Deck workspace root or direct Brand package path in your initial message. Anywhere in the sentence is fine; the path just has to be unambiguous:
+Send the Brand/Layout/Deck workspace root in your initial message. Anywhere in the sentence is fine; the path just has to be unambiguous:
> "use this template: `skills/ppt-master/templates/layouts/academic_defense/`" ✅
> "use last deck's template: `projects/last_deck/`" ✅
> "make a product introduction with `/Users/me/Desktop/our_brand_v3/`" ✅
-For a current Layout/Deck, the path is the **template workspace root**. Step 3 resolves `templates/design_spec.md`, validates the structured SVG contract, then installs `templates/`, `images/`, and `icons/` into the target project or consumes them in place when the workspace is already that project. The path may point to a built-in library workspace under `skills/ppt-master/templates/<kind>/<id>/`, a project workspace under `projects/<name>/`, or another workspace with the same shape. Brand packages keep their direct root `design_spec.md` contract. A create-template run may hand its exact validated workspace root directly to Step 3 in the same conversation; this is the only exception to the initial-message rule.
+For every current template kind, the path is the **template workspace root**. Step 3 resolves `templates/design_spec.md`, then installs `templates/` plus any existing `images/` and `icons/` into the target project or consumes them in place when the workspace is already that project. It never copies `exports/`. Deck/Layout workspaces additionally validate the structured SVG contract. The path may point to a built-in library workspace under `skills/ppt-master/templates/<kind>/<id>/`, a project workspace under `projects/<name>/`, or another workspace with the same routing. A create-template run may hand its exact validated workspace root directly to Step 3 in the same conversation; this is the only exception to the initial-message rule.
> **Compatibility preflight:** Step 3 also accepts an older flat package with `design_spec.md` and SVGs directly at the supplied root. Flat placement by itself does not require restoration. Run [`restore-pptx-structure`](../skills/ppt-master/workflows/restore-pptx-structure.md) only when the SVGs use the former atomic-placeholder/unmapped Master/Layout semantics; Step 3 does not copy such a semantic-legacy package and defer migration.
@@ -44,7 +44,7 @@ Templates are organized into three kinds, each in its own directory:
- [`templates/brands/README.md`](../skills/ppt-master/templates/brands/README.md) — identity-only presets (color / typography / logo / voice / icon style), no SVG pages; Anthropic, Google
- [`templates/layouts/README.md`](../skills/ppt-master/templates/layouts/README.md) — structure-only patterns (canvas / page structure / page types / SVG roster), no identity; academic_defense, government_blue/red, ai_ops, medical_university, pixel_retro, psychology_attachment
-- [`templates/decks/README.md`](../skills/ppt-master/templates/decks/README.md) — full-PPT replicas (identity + structure + middle segments); China Merchants Bank, Power Construction Corporation of China, Chongqing University, China Telecom
+- [`templates/decks/README.md`](../skills/ppt-master/templates/decks/README.md) — full identity + structure references (including the middle segment); China Merchants Bank, Power Construction Corporation of China, Chongqing University, China Telecom
Full data model + fusion / conflict-resolution rules: [`docs/zh/templates-architecture.md`](./zh/templates-architecture.md) (Chinese only for now).
@@ -123,7 +123,7 @@ The workflow will then **mandatorily** confirm a template brief with you before
### Step 1 — Prepare reference material
-**Strongly recommended: hand over the original `.pptx` file.** The importer reads OOXML directly and extracts every Master, Layout, placeholder, theme, and reusable asset into layered analysis references. Template_Designer reconstructs the source Master roster, Layout parent graph, picker names, and placeholder identities as complete annotated SVG pages. Source Master/Layout groups are flattened object by object into direct atomic layer elements. The original PPTX remains analysis input and is not packaged into the new template.
+**Strongly recommended: hand over the original `.pptx` file.** The importer reads OOXML directly and extracts every Master, Layout, placeholder, theme, native-shape fact, and reusable asset into layered analysis references. In `standard` / `fidelity`, Template_Designer uses them as visual reference and authors a new SVG roster plus a new Master/Layout/slot system. In mirror, it restores source identities, parentage, placeholder facts, and supported visuals one-to-one. The original PPTX remains analysis evidence and is not packaged into the new template.
You can also design from scratch from a brand guideline: provide a logo, primary color HEX, fonts, tone description, and a few mood references — the AI will design the page skeletons on the spot. This suits brands that don't yet have a finished PPT, only a VI manual.
@@ -135,7 +135,7 @@ The workflow does not silently infer values — before generation it lists these
| Field | Notes |
|-------|-------|
-| **Output scope** | `library` (default) or `project`; both write the same complete workspace, while only library scope registers it globally |
+| **Output scope** | `library` (default) or `project`; both use the same portable workspace routing, while only library scope registers it globally |
| **Target project** | Required only for `project`; give the exact initialized project path |
| **Template ID** | Portable template identity; in library scope it is also the directory / index key. Prefer ASCII slug like `acme_consulting`; non-ASCII names work but must be filesystem-safe |
| **Display name** | Human-readable name for documentation |
@@ -144,15 +144,15 @@ The workflow does not silently infer values — before generation it lists these
| **Tone summary** | One line, e.g. "modern, restrained, data-driven" |
| **Theme mode** | Light / dark / gradient / ... |
| **Canvas format** | Default `ppt169` (16:9); specify other formats up front |
-| **Replication mode** | `standard` (default 5-page roster) / `fidelity` (one variant per visually distinct cluster) / `mirror` (literal visual copy of every source slide plus explicit layer ownership) |
-| **Native structure facts** | The brief reports source Master/Layout counts, parent relationships, placeholder identities, and multi-master status. Output uses the current `structured` SVG contract and preserves that topology. |
-| **Visual fidelity** | (required for `standard` / `fidelity` when a reference exists) `literal` (reproduce original geometry / decoration / sprite crops as-is) or `adapted` (use reference for tone and structure but allow design evolution). Cover / chapter / ending are usually `literal`. **Not asked for `mirror`** — mirror is implicitly literal |
+| **Replication mode** | `standard` (default compact roster) / `fidelity` (one variant per reusable semantic family) / `mirror` (one restored prototype per source slide). `standard` / `fidelity` author new SVG semantics; mirror restores source structure without synthesis. |
+| **Native structure facts** | The brief reports source Master/Layout counts, parent relationships, placeholder identities, and multi-master status. `standard` / `fidelity` treat them as reference only; mirror restores them one-to-one through the current `structured` contract. |
+| **Visual fidelity** | (required for `standard` / `fidelity` when a reference exists) `literal` (closely reproduce original geometry / decoration / sprite crops inside a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Cover / chapter / ending are usually `literal`. **Not asked for `mirror`** — mirror restores the source visual. |
| **Keywords** | 3–5 tags for index lookup |
| Theme color / design notes / asset list | Optional — can be auto-extracted from the source |
After confirmation the workflow echoes the finalized brief and emits the marker `[TEMPLATE_BRIEF_CONFIRMED]`. Subsequent steps only run after that marker. **This is a hard gate — no brief, no generation.**
-Before either scope writes final files, one hard preflight resolves all four destinations, requires an empty `templates/` root, and rejects bitmap, icon, or preview-PPTX filename collisions in `images/`, `icons/`, `templates/icons/`, and `exports/`. Project scope additionally requires an initialized target project. A failed check stops before partial output; the workflow does not merge or overwrite.
+Before either scope writes final files, one hard preflight resolves the required `templates/` destination and any optional asset destinations, requires an empty `templates/` root, and rejects bitmap or icon filename collisions in `images/`, `icons/`, and `templates/icons/`. It checks `exports/` only when a review PPTX was requested. Project scope additionally requires an initialized target project. A failed check stops before partial output; the workflow does not merge or overwrite.
> Why so strict? A template is a structural contract, whether it is reused globally or only inside the current project. Confirming ownership and geometry first avoids partial or misplaced output.
@@ -162,26 +162,30 @@ This is the most easily confused decision when deriving a template.
| | **standard** | **fidelity** | **mirror** |
|---|---|---|---|
-| Output pages | 5 (cover / chapter / TOC / content / ending) | one variant per visually distinct cluster — count driven by the source | one page per source slide (1:1) |
-| Abstraction | High — clean, reusable skeleton | Medium — source variants retained with cleanup | Visual copy — source Master/Layout groups are still flattened into atoms |
+| Output pages | 4–5 (cover / chapter / content / ending, with optional TOC) | one variant per reusable semantic family — count driven by the source | one restored prototype per source slide (1:1 roster) |
+| Abstraction | High — clean, reusable skeleton | Medium — semantic source families redesigned with cleanup | None at the topology level; only mechanical structured-contract normalization |
| Authoring placeholders | Yes (`{{TITLE}}`, `{{CONTENT_AREA}}`, …) | Yes | Literal text may remain, but imported native content slots still carry semantic metadata |
| Best for | You want "tone + basic skeleton" to generate brand-new decks later | The source PPTX itself is a customized layout library and every variant matters | Someone else's polished deck is great as-is, you want every page available as a reference |
-| Typical use | Building a base brand template | Replicating a 20-variant government briefing layout set | Reusing a 50-page McKinsey-style deck verbatim |
-| Requires PPTX source? | No | **Yes** | **Yes** |
+| Typical use | Building a base brand template | Replicating a 20-variant government briefing layout set | Keeping all 50 source compositions available as faithful prototypes |
+| Source requirement | None | PPTX or SVG visual reference | PPTX, or SVGs with a complete explicit structure contract |
| Decoration complexity | Usually simpler | Must preserve sprite-sheet crop structure | Preserves literal geometry while adding explicit layer ownership |
**About sprite sheets**: PPTX-exported assets are often a single large image referenced from multiple slides, each cropping a different region via nested `<svg viewBox=...>` wrappers. In `fidelity` and `mirror` modes this nesting must be preserved — you cannot flatten it to a bare `<image>`, or the crop is lost and the page misaligns. The workflow validates this automatically.
+**About native PowerPoint shapes**: the lossless import SVG stays in the temporary analysis workspace, while the model works from a lightweight projection that omits opaque payload and duplicate hidden carriers. The projection is never an export source. Authored modes use compact canonical metadata. Mirror may reuse converter-supported metadata on unchanged Slide-local/slot objects; fixed Master/Layout layers remain direct atoms, and unsupported or edited objects keep the current SVG fallback.
+
+**Current mirror boundary**: every source Layout must be used by at least one source slide, and every source Master must be reachable through those Layouts. The structured template roster cannot yet materialize an unused picker-only identity without inventing an extra page, so preflight reports the exact unused identities and stops instead of silently dropping them.
+
**How mirror is consumed**: the Strategist picks one mirror page per project page, and the Executor copies that complete SVG and edits visible text in place while preserving decoration, sprite crops, geometry, and the normalized structured declarations. Mirror preserves supported appearance, not the source PPTX group-editing hierarchy.
### Step 4 — Validation, review export, registration, and discovery
-After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) as a hard gate and export `exports/<id>_template_preview.pptx`. Open that PPTX to inspect every template page as PowerPoint will present it before relying on the workspace downstream. The only scope-specific action is library registration:
+After generation, both scopes run [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) as a hard gate. If you want a PowerPoint review file, run the optional preview export; it creates `exports/<id>_template_preview.pptx` on demand. The only scope-specific action is library registration:
| Scope | Workspace root | Preview | Discovery behavior |
|---|---|---|---|
-| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | `exports/<id>_template_preview.pptx` | Register in the matching `layouts_index.json` or `decks_index.json` after validation and preview export |
-| `project` | `projects/<name>/` | `exports/<id>_template_preview.pptx` | Skip global index registration |
+| `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Optional `exports/<id>_template_preview.pptx` | Register in the matching `layouts_index.json` or `decks_index.json` after validation |
+| `project` | `projects/<name>/` | Optional `exports/<id>_template_preview.pptx` | Skip global index registration |
Library registration makes the template **discoverable** — when someone asks "what templates are available?", the AI lists it from the index. To use either scope, follow the SKILL.md Step 3 rule: name the workspace root in your first message, for example `use this template: skills/ppt-master/templates/layouts/<your_template_id>/` or `use this template: projects/<name>/`. A project workspace can also be migrated or reused elsewhere because its core shape is identical; register it only if it is placed in the library and should appear in discovery.
@@ -205,11 +209,11 @@ Library and project scopes use the same core structure; substitute either `skill
│ ├── 03a_content_two_col.svg # fidelity variant
│ ├── 04_ending.svg
│ └── icons/ # package/validation copy when used
-├── images/
+├── images/ # optional
│ └── *.png / *.jpg # SVG references use ../images/<name>
-├── icons/
+├── icons/ # optional
│ └── *.svg # runtime copy of extracted vectors
-└── exports/
+└── exports/ # optional; on-demand review output
└── <id>_template_preview.pptx
```
@@ -220,9 +224,9 @@ A `mirror` workspace uses the same tree but places its source-ordered `001_cover
### Library registration vs project placement
- **Library scope (`library`, default)** writes the workspace under `skills/ppt-master/templates/<kind>/<id>/` and registers it globally.
-- **Project scope (`project`)** writes the same complete workspace at `projects/<name>/` and skips registration.
+- **Project scope (`project`)** writes the same portable workspace at `projects/<name>/` and skips registration.
-The result is not a private or reduced project-only format. You can point Step 3 at either workspace root, copy the complete core workspace between roots, or migrate a project result into the library without restructuring it. If it moves into the library, run registration so discovery reflects its new location.
+The result is not a private or reduced project-only format. You can point Step 3 at either workspace root, copy `templates/` plus any existing `images/` and `icons/` between roots, or migrate a project result into the library without restructuring it. If it moves into the library, run registration so discovery reflects its new location.
---
@@ -230,11 +234,11 @@ The result is not a private or reduced project-only format. You can point Step 3
Common misconceptions to avoid:
-- **A reusable template is a complete SVG reconstruction contract, not a preserved source package.** Every page previews independently, while explicit metadata lets export restore Master/Layout/Slide structure
+- **A reusable template is an explicit SVG contract, not a packaged source PPTX.** Authored modes create that contract; mirror restores source ownership through it. Every page previews independently, and export compiles only declared Master/Layout/Slide structure
- **A template is not a "style skin".** It bundles structure (which blocks per page, how information is hierarchized) with style (colors, fonts, decoration). Trying to swap "skin" without structure tends to put the information architecture and the visuals at odds
- **A template does not make content decisions for you.** The Strategist still decides per-page which layout to use and whether to extend a variant. Templates offer candidates, not predetermined results
- **`fidelity` mode is not pixel-perfect copying.** Even with `literal` fidelity, the AI still strips noise and unnecessary repetition — geometry stays, redundancy goes
-- **`mirror` targets literal supported appearance, not byte-identical OOXML.** It inherits the source import limitations, and Master/Layout groups are normalized into atoms. Charts, SmartArt, OLE objects, and EMF / WMF media that do not round-trip through `pptx_template_import.py` fail the same way in mirror. The flat SVG is the visual source of truth
+- **`mirror` targets literal supported appearance and source topology, not byte-identical OOXML.** It inherits source import limitations and permits only mechanical normalization such as fixed-layer group expansion. Unsupported native objects keep their available SVG fallback or are reported; mirror never synthesizes replacement ownership.
---
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 4f82408d..8765ce64 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -244,7 +244,9 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息
**第一步 — 准备参考材料**
-**最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取主题色、字体、全部 Master/Layout、placeholder type/idx 和可复用图片资源,再重建一个干净 Master 与语义 Layout,输出完整且显式分层的 SVG。使用该模板生成新 deck 时,`adaptive` 可在同一 Master 下创建新 Layout,`strict` 保持所选 Layout 契约不变;两者都从 SVG 确定性还原原生结构。
+**最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取主题色、字体、Master/Layout、placeholder type/idx、原生形状信息和可复用图片资源。`standard` 与 `fidelity` 把来源当作视觉参考,重新设计 SVG roster 和新的 Master/Layout/slot 系统,不保留、也不蒸馏来源拓扑。`mirror` 则按来源页序恢复 Master/Layout 身份与父子关系、placeholder 事实和受支持的视觉对象,不做语义归纳。由于结构层禁止 `<g>`,来源 Master/Layout 的 group wrapper 只允许机械展开成直接原子。
+
+完整导入 SVG 可以保留高级 PowerPoint 形状所需的 metadata、隐藏 carrier 和预览指纹,但模型只读取轻量 inspection projection;projection 永远不是导出源。`standard` / `fidelity` 使用紧凑 canonical metadata。Mirror 从无损来源物化,只在未改的 Slide-local/slot 对象上复用转换器已经支持的 metadata;不支持或已修改的对象保留当前 SVG fallback。
没有源 PPTX 时,截图集也能跑(`cover.png` / `toc.png` / `chapter.png` / `content.png` / `closing.png`),但保真度会明显下降。建议优先找原始 PPTX。
@@ -256,13 +258,13 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息
- 期望的风格基调和配色(如"现代克制、深蓝主色调")
- 类别偏好(`brand` 品牌 / `general` 通用 / `scenario` 场景 / `government` 政务 / `special` 特殊)
- 画布格式(默认 16:9,如需其他格式请注明)
-- 输出范围:进入索引的 `library`(默认)或一个已经初始化的 `project`;两者使用相同的完整工作区结构
+- 输出范围:进入索引的 `library`(默认)或一个已经初始化的 `project`;两者使用相同路由并省略空的可选目录
不需要一次提供所有细节——AI 代理会通过对话追问补齐缺失信息(输出范围、模板 ID、主题模式等)。
**第三步 — 等待完成**
-AI 代理会自动完成后续工作——分析截图、构建布局定义、验证模板,并导出 `exports/<id>_template_preview.pptx`,方便在 PowerPoint 中直观看模板效果。两种范围都包含相同的 `templates/`、`images/`、`icons/` 与 `exports/` 核心结构:`library` 写入 `skills/ppt-master/templates/<kind>/<id>/` 并完成全局注册;`project` 写入 `projects/<name>/` 并跳过注册。把这个工作区根目录交给 Step 3 即可。旧式平铺包仍可把 `design_spec.md` 放在根目录,目录平铺本身不要求恢复结构。由于新工作区形态一致,完整结果可在两个位置之间迁移或复用,无需重新组织目录。
+AI 代理会自动完成后续工作——分析参考、构建布局定义并验证模板。如果你明确需要 PowerPoint 审阅文件,它还会按需生成 `exports/<id>_template_preview.pptx`。两种范围都要求 `templates/`,并使用可选的 `images/`、`icons/` 与 `exports/`:`library` 写入 `skills/ppt-master/templates/<kind>/<id>/` 并完成全局注册;`project` 写入 `projects/<name>/` 并跳过注册;空的可选目录直接省略。把这个工作区根目录交给 Step 3 即可,Step 3 不会复制 `exports/`,全局库的预览导出也由 Git 忽略。旧式平铺包仍可把 `design_spec.md` 放在根目录,目录平铺本身不要求恢复结构。
> **提示**:对风格和使用场景描述得越具体,生成的模板就越符合你的预期。
diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.md
index cd7de47a..1c98acd4 100644
--- a/docs/zh/getting-started.md
+++ b/docs/zh/getting-started.md
@@ -31,16 +31,16 @@
你:用 /create-template 把这个复刻成模板:projects/brand/our_deck.pptx
```
-这会跑 `pptx_template_import.py`,把文件重建成可复用工作区——版式 SVG + `design_spec.md` + 抽取出的主题色、字体、图片。它还会导出 `exports/<id>_template_preview.pptx`,方便先在 PowerPoint 里判断模板还原效果。生成时引用的是工作区根目录。
+这会跑 `pptx_template_import.py`,把文件重建成可复用工作区——版式 SVG + `design_spec.md` + 抽取出的主题色、字体、图片。如果需要 PowerPoint 评审文件,再显式运行可选预览导出;它会按需创建 `exports/<id>_template_preview.pptx`。生成时引用的是工作区根目录。
-在 create-template 简报中选择 `library`(沿用原默认)或 `project`。两种范围都会创建完整且相同的 `templates/`、`images/`、`icons/` 与 `exports/` 工作区。项目范围要求给出已初始化的目标项目;只有全局库范围会执行注册。
+在 create-template 简报中选择 `library`(沿用原默认)或 `project`。两种范围都要求 `templates/`,并使用可选的 `images/`、`icons/` 和按需生成的 `exports/`;空的可选目录直接省略。项目范围要求给出已初始化的目标项目;只有全局库范围会执行注册。
复刻出的模板可以放在两个位置之一:
| 位置 | 路径 | 说明 |
|---|---|---|
-| **注册进 skill 库** | `skills/ppt-master/templates/<kind>/<id>/` | 完整工作区并执行全局注册;问“有哪些模板”时会被列出来 |
-| **放在 projects 下** | `projects/<name>/` | 相同的完整工作区,不执行全局注册 |
+| **注册进 skill 库** | `skills/ppt-master/templates/<kind>/<id>/` | 可移植工作区并执行全局注册;问“有哪些模板”时会被列出来 |
+| **放在 projects 下** | `projects/<name>/` | 相同的可移植工作区,不执行全局注册 |
两种结果都通过对话里给出**工作区根目录路径**来引用。Step 3 会解析 `templates/design_spec.md`;为兼容旧包,也接受 `design_spec.md` 直接位于所给根目录的平铺形态。create-template 可在同一对话里把已验证的精确工作区根目录直接交给 Step 3。两种情况都以路径为准,绝不认裸模板名。完整工作区可以在全局库与 `projects/` 之间复制或迁移,无需调整目录结构;只有全局库注册不同。
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index 4f9b6d7e..3009a58a 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -51,7 +51,7 @@
- **提示词约束强度三档解耦**([`docs/rules/prompt-style.md`](../rules/prompt-style.md) §4) — 规则(`Hard rule` / `Forbidden`)/ 默认(`Default — … may override`)/ 参考(`Reference — not a constraint`)三档显式化 + 「客观失败 vs 品味」判据 + checker 边界,让模型对「该守 vs 可破」一目了然;visual-style catalog 全程用 Reference 强度
- **visual-style catalog 扩充至 18 个,与 image-renderings 对齐 + 示例库回收** — 先从[示例库](../../examples/)提炼 4 个(`brutalist` / `blueprint` / `memphis` / `zine`),再补齐 [`image-renderings`](../../skills/ppt-master/references/image-renderings/) 里有排版对应物的手绘 / 纹理风格 6 个(`sketch-notes` / `ink-notes` / `chalkboard` / `paper-cut` / `vintage-poster` / `pixel-art`),再回收示例库里仍未覆盖的独立气质:`ink-wash`(新中式水墨留白,源 藏拙 / 李子柒)· `glassmorphism`(深底磨砂玻璃 + 流光,源 glassmorphism_demo,从 soft-rounded 独立)· `photo-editorial`(满版摄影主导、文字点题,源 Pritzker / fashion_weekly)· `data-journalism`(Bloomberg/Economist 新闻信息图,多栏微图表 + 数据侧栏,源 global_ai_capital)。catalog 重组为 5 组(企业产品 / 编辑出版 / 表现印刷 / 手绘笔触 / 特殊)。**关键判据**:一个 rendering 升 visual-style 的前提是它定义「整页版面语言」而非「插入图的样子」——故 corporate-photo「摄影主导版面」该建(photo-editorial),而 nature / warm-scene / fantasy-animation 等纯氛围 rendering 仍只配对、不单建。全程零 HEX、Reference 强度
- **mode catalog 扩档至 5 个:加 `briefing`** — 补上「中性信息平铺」这一格:无论点 / 无故事 / 不教学 / 不冲击,topic 标题、等权铺事实、完整可扫读,服务周报 / 参考册 / 目录 / 会议材料 / FAQ 这类「只告知不论证」的 deck。五个 mode 自此更接近 MECE 地切分**表达意图**:说服(pyramid)· 讲故事(narrative)· 教会(instructional)· 震住(showcase)· 只告知(briefing)。`_index` 加了 `briefing` vs `pyramid` 的灰区判据(「要不要造个 thesis 才塞得进 pyramid → 那就是 briefing」)。五个预设之外加一个 `custom` 兜底,承接预设盖不住的 bespoke 方向(特殊节奏 / 多 mode 融合 / 特定姿态)——用户点名**或策略师推荐**皆可,与所有锁一样由用户确认;一份 deck 永远只锁一个值,融合=一个 custom 描述多幕。唯一要避免的是「预设明明贴合却图省事甩 custom」。这与「用户自带大纲 / 方向覆盖 mode」是同一条真值优先原则
-- **mode / visual-style 体系真实 deck 验证完成 + 四项校准收紧落地** — 5 mode + 18 visual-style + `custom` 逃生舱在 5 份覆盖性 deck 上跑过验证(briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine,其中 narrative 一份走 AI 图生成分支):**选型零误判**(四对 Close-calls 灰区引力全被触发且全抗住)、**纪律全落实**(零 HEX / Reference 强度 / 整页版面语言)、**custom 机制可用**(`mode_behavior` 散文段落撑过 10 页生成、能讲成大白话让用户确认)、**mode ⟂ visual_style 正交成立**(任意组合无串味,含「keynote/发布会=mode 不是 style」路由正面验证)、导出 5/5 deck × 全页 0 失败。据真实信号收紧四处:`strategist §e` 按 visual_style 预判中性档位一次锁全(消除连续三份的 Executor 中途补色)、`executor-base §1` 套模板页重皮到当前 visual_style(模板供结构不供皮,镜像模板仍按 §1.1 逐字保留)、`briefing §1` 的 `core_message` = 本页覆盖什么而非证明什么(briefing 专属例外,全局 §IX 论断语义保留给 narrative/instructional/pyramid)、`svg_quality_checker` 修字体 drift 误报(按定界符匹配 + font-stack 归一化)+ 放宽 showcase mode 与 poster 类 visual-style 的字号上限
+- **mode / visual-style 体系真实 deck 验证完成 + 四项校准收紧落地** — 5 mode + 18 visual-style + `custom` 逃生舱在 5 份覆盖性 deck 上跑过验证(briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine,其中 narrative 一份走 AI 图生成分支):**选型零误判**(四对 Close-calls 灰区引力全被触发且全抗住)、**纪律全落实**(零 HEX / Reference 强度 / 整页版面语言)、**custom 机制可用**(`mode_behavior` 散文段落撑过 10 页生成、能讲成大白话让用户确认)、**mode ⟂ visual_style 正交成立**(任意组合无串味,含「keynote/发布会=mode 不是 style」路由正面验证)、导出 5/5 deck × 全页 0 失败。据真实信号收紧四处:`strategist §e` 按 visual_style 预判中性档位一次锁全(消除连续三份的 Executor 中途补色)、`executor-base §1` 套模板页重皮到当前 visual_style(模板供结构不供皮,mirror 模板保持恢复后的视觉身份)、`briefing §1` 的 `core_message` = 本页覆盖什么而非证明什么(briefing 专属例外,全局 §IX 论断语义保留给 narrative/instructional/pyramid)、`svg_quality_checker` 修字体 drift 误报(按定界符匹配 + font-stack 归一化)+ 放宽 showcase mode 与 poster 类 visual-style 的字号上限
- **可选 spec 复核环节上线**([`workflows/refine-spec.md`](../../skills/ppt-master/workflows/refine-spec.md)) — 策略师确认阶段后新增一个 opt-in 停顿点:用户明确要求时(默认 OFF),Strategist 先产出完整 `design_spec.md` + `spec_lock.md`,停下来让用户对 spec 任意部分(大纲 / 配色 / 排版 / 版式 / 图片策略 / page rhythm)深入讨论修改,改完同步两个文件再进生成。与 split-mode 同构——不主动触发、默认管线零变化,仅在策略师确认阶段里多一行 opt-in 提示。复核视角(逻辑清晰度 / 信息密度 / 焦点 / 口语化 / 感染力 / 章节配比 + 各设计维度)只给方向、不落任何数字阈值(`Reference` 强度)。启发自 [@cuberoocp](https://github.com/cuberoocp) [issue #173](https://github.com/hugohe3/ppt-master/issues/173)
- **交互式可视化策略师确认页(Step 4)**([`scripts/confirm_ui/server.py`](../../skills/ppt-master/scripts/confirm_ui/server.py),字段 schema [`scripts/docs/confirm_ui.md`](../../skills/ppt-master/scripts/docs/confirm_ui.md)) — 模板遵循方式只在加载 Deck/Layout 模板时显示,默认推荐 `adaptive`:每页仍映射模板架构,无匹配构图时可在同一 Master 下创建新 Layout;`strict` 保持所选 Layout 契约不变。确认页与 Live Preview 共用端口,最终 `result.json` 对下游权威。
- **源文档转换保真度提升一批** — 源材料进管线时更少丢信息:`doc_to_md` 把 Word 里的 OMML / Office Math 公式转成内联 LaTeX、`pdf_to_md` 识别 `Figure N |` 竖线分隔的图注、`ppt_to_md` 保留源 deck 已有的超链接(run 级外链 `[text](url)` / slide 内部跳转 `[text](#slide-N)` / shape 级点击,含危险 scheme 过滤与锚文本 Markdown 转义)并把原生图表数据转写成 Markdown 表格(数值随转换存活,不再只剩一张图)。图注识别基于 [@suay1113](https://github.com/suay1113) [PR #191](https://github.com/hugohe3/ppt-master/pull/191),超链接保留提炼自 [@ZhaoZuohong](https://github.com/ZhaoZuohong) [PR #155](https://github.com/hugohe3/ppt-master/pull/155)
@@ -84,7 +84,7 @@
- **`--native-objects` 从休眠 marker 硬化为可用级 opt-in** — 那条窄「原生对象」例外(见下文 Non-goals)现在导出的图表与纯文本表格会**保留 deck 自己的设计**,不再塌回 PowerPoint 的白底默认主题。classic 原生图表显式写入 chart-area / plot-area / 轴线 / 网格线 / 标签文字颜色——从可见的 SVG fallback 推断(最大面板型 `<rect>` → 背景、fallback 文字 → 标签、fallback 描边 → 轴线/网格),或用 `style` 显式覆盖(`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`,`"none"` 表透明);颜色解析把命名色、`#RGB` 简写、`rgb()` / `rgba()` 归一为 OOXML hex;bar/column 系列关掉负值反色,负值柱保持系列色。激活导出命名为 `<name>_<ts>_native_charts.pptx` 以与默认压平形状导出区分。**默认路线不变**——图表/表格仍以 SVG 派生的 DrawingML 形状导出以保跨渲染器保真;原生对象仍是下文 Non-goals 里那条刻意的 opt-in 取舍
-- **原生 package 结构 + 保守 PPTX 对象回转** — 每个新 SVG 页面在创作时就声明最终 Master/Layout 身份。固定 Master/Layout 视觉是根级原子,可复用槽位是带真实 carrier 或显式 composite proxy 的有界顶层 group,零槽位 Layout 也合法。导出只确定性编译该合同,把锁定 title/body 字号写入母版 `p:txStyles`,并执行最终 package 回读;不提升重复 chrome,也不推断 placeholder。`create-template` 只把源结构当分析输入并统一重建显式 SVG;`strict` 保持所选 Layout,`adaptive` 可在同一 Master 下新建 Layout。`library` 与 `project` 输出统一采用完整的 `templates/` + `images/` + `icons/` + `exports/<id>_template_preview.pptx` 工作区结构,仅全局注册不同。旧 baseline/template/preserve SVG 包先运行 `restore-pptx-structure`;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。
+- **原生 package 结构 + 按模式创建模板** — 每个新 SVG 页面在创作时就声明最终 Master/Layout 身份。固定 Master/Layout 视觉是根级原子,可复用槽位是带真实 carrier 或显式 composite proxy 的有界顶层 group,零槽位 Layout 也合法。导出只确定性编译该合同,把锁定 title/body 字号写入母版 `p:txStyles`,并执行最终 package 回读;不提升重复 chrome,也不推断 placeholder。`standard` / `fidelity` 重新创作 SVG roster 和新的 Master/Layout 系统,不保留、也不蒸馏来源拓扑。`mirror` 按来源页序恢复 Master/Layout 身份与父子关系、placeholder 事实和受支持视觉,不做语义归纳;固定结构层的来源 group 只允许机械展开成直接原子。无损导入保留在分析区,轻量 projection 仅供检查。`library` 与 `project` 都要求 `templates/`,`images/` / `icons/` 可选,`exports/` 仅在按需生成评审文件时出现;只有全局注册不同。旧 baseline/template/preserve SVG 包先运行 `restore-pptx-structure`;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。
---
@@ -114,11 +114,11 @@
**对应 Issue**:[#53](https://github.com/hugohe3/ppt-master/issues/53)、[#118](https://github.com/hugohe3/ppt-master/issues/118)
-PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。结构完整的 PPTX 现在可以先转成经过确认的可复用模板包,并保留其 master/layout/theme;但「打开任意 PPTX 后不经规范化就盲填所有占位框」仍是另一种产品形态。
+PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。结构完整的 PPTX 现在可以通过两种显式方式形成经过确认的可复用模板包:`standard` / `fidelity` 以视觉证据为参考,创作新的 SVG 与 Master/Layout 系统;`mirror` 恢复当前可达且受支持的来源结构。但「打开任意 PPTX 后不经规范化就盲填所有占位框」仍是另一种产品形态。
**基础诉求其实很简单**:如果只是「固定位置替换 Excel 数据到 PPT 模板」,直接让 AI 写一段 `python-pptx` 脚本即可,几行代码搞定,不需要本项目这套管线。
-> **已支持边界**:`template-fill-pptx` 直接回填选中的源页面;`create-template` 把源 Master/Layout 事实收敛成经过确认、完整且显式分层的 SVG 模板。下游严格与适应性使用都从 SVG 契约还原原生结构。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。
+> **已支持边界**:`template-fill-pptx` 直接回填选中的源页面;`create-template` 或者创作新的显式 SVG 契约(`standard` / `fidelity`),或者在不做语义归纳的前提下恢复受支持的来源契约(`mirror`)。下游 `strict` / `adaptive` 都从这份已声明契约还原原生结构。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。
### 改用原生 PowerPoint 图表(Excel-native chart)
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 77f93640..3c72218c 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -98,8 +98,8 @@
| 原生 PPTX 模板 + 新材料 / 新主题 | `template-fill-pptx` | 克隆并填充原生页面;不生成 SVG |
| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | `beautify-pptx` | 通过 SVG 重新生成;内容和分页锁定 |
| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | `native-enhance-pptx` | 直接 OOXML patch;不重新设计 |
-| 用户想从 PPTX 或设计参考构建可复用模板工作区 | `create-template` 或 `create-brand` | 输出后续能触发 Step 3 的工作区根目录;create-template 还会导出审阅 PPTX |
-| 用户提供明确模板路径 | 主 SVG 流水线 Step 3 | 当前 Layout/Deck 工作区解析 `templates/design_spec.md`;Brand 与旧式平铺包解析根目录 `design_spec.md`;只有旧 SVG 语义才恢复结构 |
+| 用户想从 PPTX 或设计参考构建可复用模板工作区 | `create-template` 或 `create-brand` | 输出后续能触发 Step 3 的工作区根目录;create-template 可按需导出审阅 PPTX |
+| 用户提供明确模板路径 | 主 SVG 流水线 Step 3 | 当前 Brand/Layout/Deck 工作区均解析 `templates/design_spec.md`;兼容的旧式平铺包解析根目录 `design_spec.md`;只有旧 SVG 语义才恢复结构 |
| 用户要求调整对象级动画顺序 / 效果 / 计时 | `customize-animations` | 通过 `animations.json` 控制可选导出策略 |
| 用户要求预览、选择、注解或重导出浏览器编辑 | `live-preview` | 浏览器工作流;注解只在规定交接点应用 |
@@ -263,19 +263,21 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
**为什么默认自由设计。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),所以它一直在;但 AI 不主动去抓,是用户去抓。
-**机械触发,不做语义匹配。** 像 `academic_defense` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,即使库里存在相似目录,也不会触发 Step 3。Step 3 只消费显式路径。当前 Layout/Deck 工作区解析 `templates/design_spec.md`;Brand 包维持根目录 `design_spec.md` 合同,兼容的旧式平铺 Layout/Deck 包也从根目录读取。目录平铺本身不是恢复理由;只有旧 Master/Layout/placeholder 语义才触发 `restore-pptx-structure`。发现性交给模板索引和显式问答(“有哪些模板可以用?”),不交给运行时 fuzzy matching。
+**机械触发,不做语义匹配。** 像 `academic_defense` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,即使库里存在相似目录,也不会触发 Step 3。Step 3 只消费显式路径。当前 Brand/Layout/Deck 工作区均解析 `templates/design_spec.md`;兼容的旧式平铺包从根目录读取 `design_spec.md`。目录平铺本身不是恢复理由;只有旧 Master/Layout/placeholder 语义才触发 `restore-pptx-structure`。发现性交给模板索引和显式问答(“有哪些模板可以用?”),不交给运行时 fuzzy matching。
-新建 Layout/Deck 在两种位置都采用同一物理合同:
+当前 Brand/Layout/Deck 都采用同一工作区路由合同;Brand 不含 SVG roster,空的可选目录直接省略:
```text
<template_workspace>/
├── templates/ # design_spec.md、SVG 原型,以及使用时的 templates/icons/
-├── images/ # 位图素材,SVG 统一引用 ../images/<name>
-├── icons/ # 提取向量素材的运行期副本
-└── exports/ # <id>_template_preview.pptx
+├── images/ # 可选;位图素材,SVG 统一引用 ../images/<name>
+├── icons/ # 可选;提取向量素材的运行期副本
+└── exports/ # 可选、按需生成的审阅文件;全局库下由 Git 忽略
```
-`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/`。Step 3 接收这个根目录。工作区可在两个位置之间迁移而不改形;唯一的范围差异是全局索引注册,`exports/` 只作为审阅证据,不参与模板输入。
+`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/`。Step 3 接收这个根目录。工作区可在两个位置之间迁移而不改形;唯一的范围差异是全局索引注册。空的可选目录不创建,`exports/` 也不会复制进新项目。
+
+`standard` 与 `fidelity` 会重新创作 SVG 和新的 Master/Layout/slot 系统;来源拓扑只作为视觉证据,不保留、也不蒸馏。`mirror` 按来源页序恢复 Master/Layout 身份与父子关系、placeholder 事实和受支持视觉,不做语义归纳。由于结构层不能是 `<g>`,固定结构层的来源 group wrapper 只允许机械展开成直接原子,同时保持归属、paint order 和视觉一致。
三类模板拥有不同的设计契约片段:
@@ -283,7 +285,7 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
|---|---|---|---|
| `brand` | 身份片段 | 配色、字体、logo、语气、图标风格 | 锁定身份;结构保持自由 |
| `layout` | 结构片段 | 画布、页面结构、页面类型、SVG roster | 锁定结构;身份仍在策略师确认阶段里确定 |
-| `deck` | 身份 + 结构 + 模板总览 | 完整复刻型包 | 锁定完整模板语法,只剩内容相关选择 |
+| `deck` | 身份 + 结构 + 模板总览 | 完整身份 + 结构包 | 锁定完整模板语法,只剩内容相关选择 |
当用户提供多个路径时,融合是**片段级**而不是字段级:brand 覆盖身份片段,layout 覆盖结构片段,deck 提供中间的 template overview 片段。同类冲突会被显式列为冲突,而不是按输入顺序默默决定。这样融合后的 spec 能明确说明每个片段来自哪里,便于审计和复现。
@@ -462,7 +464,9 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器,简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和;这个性质在整体翻译下脆弱,在元素派发下稳健。
-**为什么只有一条 PPTX 编译路线。** Native 导出把作者 SVG 中受支持的元素逐个翻译成 DrawingML 形状。常规 deck 路线读取 `svg_output/`;create-template 对通过校验的模板原型调用同一 structured 编译器,生成 `exports/<id>_template_preview.pptx` 作为审阅证据。项目不会把整页 SVG 媒体或另一套位图渲染打包成第二类 PPTX。`svg_final/` 仍由常规 deck 的强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不为 PowerPoint 手工“转换为形状”提供兼容兜底。
+**为什么导入型与生成型 metadata 分层。** 导入 PPTX 时,完整 SVG 可以携带高级形状所需的 metadata、隐藏 carrier 和预览指纹,但这类载荷不适合直接进入模型上下文。authoring projection 会非破坏性地移除大体积载荷,只保留可见几何和紧凑意图,而且永远不是导出源。`standard` / `fidelity` 使用 compact canonical metadata。Mirror 从无损来源物化,可在未改的 Slide-local/slot 对象上复用转换器已经支持的 metadata;固定结构层保持直接原子,不支持或已修改的对象保留当前 SVG fallback。
+
+**为什么只有一条 PPTX 编译路线。** Native 导出把作者 SVG 中受支持的元素逐个翻译成 DrawingML 形状。常规 deck 路线读取 `svg_output/`;用户需要时,create-template 对通过校验的模板原型调用同一 structured 编译器,生成 `exports/<id>_template_preview.pptx` 作为审阅证据。项目不会把整页 SVG 媒体或另一套位图渲染打包成第二类 PPTX。`svg_final/` 仍由常规 deck 的强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不为 PowerPoint 手工“转换为形状”提供兼容兜底。
**为什么结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。Strategist 在 SVG 生成前写出 Master roster 和完整页面 mapping;Executor 在构图时同步写入这些身份、固定原子元素和槽位。这样,自由设计在视觉层面仍然开放,PowerPoint 归属却从一开始就是显式合同。导出器只编译声明;旧项目或 unmapped 项目进入 `restore-pptx-structure`,不会触发导出期启发式推断。
@@ -472,15 +476,15 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。
-**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整输入原型,`pptx_masters` 与 `pptx_layouts` 从规划阶段起记录输出归属。strict 保持原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才使用新 Layout key,并在页面创作时立即更新 mapping,而不是事后推断。非 mirror 的皮肤由项目控制;mirror 保持复用视觉身份,但来源 Master/Layout group 仍会按合同原子化。
+**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整输入原型,`pptx_masters` 与 `pptx_layouts` 从规划阶段起记录输出归属。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才使用新 Layout key,并在页面创作时立即更新 mapping,而不是事后推断。非 mirror 的皮肤由项目控制;mirror 保持已恢复的输出视觉身份。
**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Structured 导出把锁定的 title/body 字号写入 Master 文本默认值;每个 Layout 文字槽位也把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。
**为什么 structured 输出要在发布前回读。** 元数据预检不能证明 package 序列化保留了所有 relationship 与注册信息。导出器会重新打开临时 PPTX,校验 Presentation → Master → Layout → Slide 注册链、物理 part/content-type roster、选择器身份、固定对象顺序、placeholder 类型/有效索引/bounds、carrier 绑定、隐藏 proxy 与零槽 Layout,只有通过后才发布。
-**为什么可复用模板要重建来源拓扑。** `pptx_template_import.py` 输出分层 Master/Layout/Slide 参考和 native 结构事实;`create-template` 重建每一个来源 Master 和 Layout,包括未使用 Layout,并生成完整注释 SVG 原型。来源 Master/Layout group 被原子化;父子关系、选择器名称、placeholder 身份和 bounds 在模板规格中保持可审计。原 PPTX 只是分析输入,不再成为打包依赖。
+**为什么模板创建分为创作模式和恢复模式。** `pptx_template_import.py` 输出分层 Master/Layout/Slide 参考和 native 结构事实。`standard` / `fidelity` 把这些素材和视觉当参考,再按照确认后的可复用行为创作新拓扑。Mirror 则一对一恢复来源 roster 与拓扑,只允许显式 structured 合同要求的机械归一化。原始 PPTX 保留为分析证据,不成为最终模板依赖。
-**为什么 create-template 在两种范围都使用同一工作区形态。** `create-template` 仍以写入索引的 `library` 为默认,也可写入已初始化项目。两种根目录都包含相同的 `templates/`、`images/`、`icons/` 与 `exports/` 核心结构,包括 `<id>_template_preview.pptx`;SVG 素材引用也完全一致。因此完整工作区可直接迁移和复用,不需要全局库专用 package 分支或缩减的项目分支。唯一范围差异是全局索引注册,两种范围都使用同一 `structured` 合同。
+**为什么 create-template 在两种范围都使用同一工作区路由。** `create-template` 仍以写入索引的 `library` 为默认,也可写入已初始化项目。两种根目录都要求 `templates/`;`images/`、`icons/` 和按需生成的 `exports/` 只有存在真实内容时才出现,SVG 素材引用完全一致。因此工作区可直接迁移和复用,不需要全局库专用 package 分支或缩减的项目分支。唯一范围差异是全局索引注册,两种范围都使用同一 `structured` 合同。
**为什么模板 SVG 保持完整却仍能编译成原生结构。** 模板 SVG 会重复携带继承的 Master/Layout 视觉和示例 Slide 内容,因此可独立打开。生成时由 `page_layouts` 选择该原型,输出 SVG 仍保持视觉闭包。导出器移除重复继承原子、生成真实 Master/Layout part,并把槽位 carrier 与 Slide-local 内容留在 Slide。
@@ -539,7 +543,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu
| `topic-research` | 用户只有主题、没有源材料 | 在 Step 1 前收集网络材料 |
| `template-fill-pptx` | 原生 PPTX 模板 + 新材料 / 新主题 | 直接克隆并填充原生页面;不进入 SVG 流水线 |
| `beautify-pptx` | 现有 PPTX,页数/页序/措辞必须 1:1 保留,只改善排版 | 锁定源身份与内容后,通过 SVG 流水线重新生成 |
-| `create-template` | 构建可复用 layout/deck 模板工作区 | 输出可移植工作区根目录与 `exports/<id>_template_preview.pptx`;只有全局库范围执行注册 |
+| `create-template` | 构建可复用 layout/deck 模板工作区 | 输出可移植工作区根目录;可按需生成 `exports/<id>_template_preview.pptx`;只有全局库范围执行注册 |
| `create-brand` | 提取或定义可复用品牌身份 | 输出 `templates/brands/<id>/` |
| `resume-execute` | 规划会话后新开聊天,用户要求继续某项目 | 不重跑 Strategist,直接进入执行会话 |
| `refine-spec` | 用户明确要求生成前先审阅 / 修改 spec | 写出完整 spec/lock 后停下,用户修改后再恢复 |
diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.md
index b24c97df..2673c619 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -14,14 +14,14 @@
| **Layout** | `templates/layouts/<id>/` | 仅结构段:canvas / page structure / page types / SVG roster | 不写品牌身份(无 logo、无品牌色硬约束) | `workflows/create-template.md`(layout 分支)|
| **Deck** | `templates/decks/<id>/` | 全段:身份段 + 结构段 + 中间段(template overview) | —— | `workflows/create-template.md`(deck 分支,默认)|
-每张新建或已恢复的 Layout/Deck SVG 都是完整预览,并在根节点声明 Master/Layout key 与选择器名称;固定 Master/Layout 视觉是直接原子元素;语义槽位是顶层 group。普通槽位必须有正数设计区域 bounds 和恰好一个兼容 carrier;复合 `object` 区域走显式 proxy 绑定,零槽 Layout 也合法。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为。PPTX 导入产物只用于分析,不进入新模板包。下游 `strict` 保持所选 Layout 契约,`adaptive` 保持 Master 并可在创作时建立新 Layout 身份;两者都使用 `pptx_structure.mode: structured`。只有使用旧 Master/Layout 语义的包才必须先运行 `restore-pptx-structure`;旧包把 `design_spec.md` 平铺在根目录仍属于受支持的兼容目录形态,目录平铺本身不触发恢复。
+每张新建或已恢复的 Layout/Deck SVG 都是完整预览,并在根节点声明 Master/Layout key 与选择器名称;固定 Master/Layout 视觉是直接原子元素;语义槽位是顶层 group。普通槽位必须有正数设计区域 bounds 和恰好一个兼容 carrier;复合 `object` 区域走显式 proxy 绑定,零槽 Layout 也合法。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为。`standard` / `fidelity` 重新创作 SVG 和新的结构,不保留、也不蒸馏来源拓扑。Mirror 按来源恢复 roster、身份、父子关系、placeholder 事实和受支持视觉,不做语义归纳;固定结构层的来源 group 只允许机械展开成直接原子。下游 `strict` 保持所选声明合同,`adaptive` 保持 Master 并可在创作时建立新 Layout 身份;两者都使用 `pptx_structure.mode: structured`。只有使用旧 Master/Layout 语义的包才必须先运行 `restore-pptx-structure`;旧包把 `design_spec.md` 平铺在根目录仍属于受支持的兼容目录形态,目录平铺本身不触发恢复。
三者是**三种并列的 reference bundle**。在全局库范围内,物理目录与 frontmatter `kind` 字段双向对齐:
多路径合成后的项目级 `design_spec.md` 也必须保留准确的 `kind`:同时具备身份段和结构段时为 `deck`,只有结构段时为 `layout`,只有身份段时为 `brand`。Strategist 确认页据此只对真正包含页面结构的 Deck/Layout 显示 `adaptive / strict`。
```yaml
-# templates/brands/anthropic/design_spec.md
+# templates/brands/anthropic/templates/design_spec.md
---
kind: brand
...
@@ -48,8 +48,8 @@ native_structure_mode: structured
| 范围 | 工作区根目录 | 核心结构 | 发现行为 |
|---|---|---|---|
-| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | `templates/` + `images/` + `icons/` + `exports/` | 写入对应全局索引 |
-| `project` | `projects/<name>/` | 完全相同的 `templates/` + `images/` + `icons/` + `exports/` 契约 | 不更新全局索引 |
+| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | 必需 `templates/`;可选 `images/`、`icons/` 与按需 `exports/` | 写入对应全局索引 |
+| `project` | `projects/<name>/` | 完全相同的路由合同 | 不更新全局索引 |
两种根目录都保持相同的核心形态:
@@ -59,17 +59,19 @@ native_structure_mode: structured
│ ├── design_spec.md
│ ├── *.svg
│ └── icons/ # 使用时保留 package / 校验副本
-├── images/ # 所有位图;SVG 统一引用 ../images/<name>
-├── icons/ # 提取向量素材的运行期副本
-└── exports/
+├── images/ # 可选;SVG 统一引用 ../images/<name>
+├── icons/ # 可选;提取向量素材的运行期副本
+└── exports/ # 可选;仅在按需生成审阅文件时创建
└── <id>_template_preview.pptx
```
-预览 PPTX 是派生的审阅证据,不是模板源资产。Step 3 读取工作区根目录,只消费 `templates/`、`images/` 与 `icons/`,不会复制或使用 `exports/`。
+空的可选目录直接省略,不添加占位文件。按需生成的预览 PPTX 是派生审阅证据,不是模板源资产。Step 3 读取工作区根目录,只消费 `templates/` 及实际存在的 `images/`、`icons/`,不会复制或使用 `exports/`;全局库下的 `exports/` 统一由 Git 忽略。
+
+原生形状 metadata 采用两级模型。完整导入 SVG 保存 native metadata、隐藏 carrier 和预览证据;轻量 authoring projection 移除大体积载荷与重复 carrier,只供模型检查,永远不是导出源。创作模式使用紧凑 canonical metadata。Mirror 可在未改的 Slide-local/slot 对象上复用转换器已经支持的 metadata;固定结构层保持直接原子,不支持或已修改的对象保留 SVG fallback。导出只编译声明的结构,不推断归属。
两种范围都在可移植 frontmatter 中保留 `kind: layout` 或 `kind: deck`。`output_scope` 与 `target_project` 只属于工作流简报,不写入 `design_spec.md`。
-任何范围第一次写最终文件前,都必须解析工作区根目录、确认 `templates/` 为空,并检查全部计划写入的图片、图标与预览 PPTX 文件名无冲突。项目范围还必须确认目标项目已初始化。任一失败都在写入前停止,不合并、不覆盖。
+任何范围第一次写最终文件前,都必须解析工作区根目录、确认 `templates/` 为空,并检查全部计划写入的图片与图标文件名无冲突;只有明确要求预览导出时才检查预览 PPTX 目标。项目范围还必须确认目标项目已初始化。任一失败都在写入前停止,不合并、不覆盖。
### 三段的字段切分
@@ -83,9 +85,9 @@ native_structure_mode: structured
### 为什么需要 Deck 这一类
-Deck 是一份现存 PPT 的"复刻全息"——SVG 几何为该套配色和字体画的,身份与结构在原 PPT 里已经实战搭配。它的价值是「已验证的整体感」,是 layout + brand 自由拼合未必能达到的成品。
+Deck 是从一份现存 PPT 或明确设计方向形成的完整身份与结构参考——配色、字体、视觉节奏与页面类型共同组成一个整体。它的价值是「已验证的整体感」,是 layout + brand 自由拼合未必能达到的成品。
-但 Deck **不是"不可篡改的复刻"**——它是"作为默认底图的复刻,可被显式 brand / layout 覆盖"。这给了用户最大自由度:默认拿到一份完整方案,需要时显式换身份或换结构。
+它的构建方式由 replication mode 决定:`standard` / `fidelity` 根据视觉参考创作新系统;mirror 一对一恢复来源身份与父子关系。打包完成后,两者都作为可被显式 brand / layout 覆盖的完整参考方案使用。
---
@@ -301,10 +303,10 @@ AI: 你给了两个 brand,检测到段级冲突:
| 用户路径指向 | Step 3 行为(按 kind 分支)|
|---|---|
-| `kind: brand` | design_spec + 非图片资产 → `<project>/templates/`;logo / 插画 / 图标**位图** → `<project>/images/` |
-| `kind: layout` | design_spec + SVG roster → `<project>/templates/`;**位图**资产 → `<project>/images/` |
-| `kind: deck` | design_spec + 模板 SVG → `<project>/templates/`;logo / 背景 / 其它**位图** → `<project>/images/` |
-| 多路径 | 按上表合成单份 `design_spec.md`;SVG 进 `templates/`、位图进 `images/` 合并复制 |
+| `kind: brand` | 把工作区 `templates/` 及实际存在的 `images/`、`icons/` 映射到项目同名目录;忽略 `exports/` |
+| `kind: layout` | 把工作区 `templates/` 及实际存在的 `images/`、`icons/` 映射到项目同名目录;忽略 `exports/` |
+| `kind: deck` | 把工作区 `templates/` 及实际存在的 `images/`、`icons/` 映射到项目同名目录;忽略 `exports/` |
+| 多路径 | 按上表合成单份 `design_spec.md`,解决冲突后再合并实际存在的可移植目录 |
| 同类多份 | 按上节"git 冲突解决"问答,得到合成结果 |
位图统一进入工作区 `images/`,模板 SVG 通过 `../images/` 引用。如果显式输入根目录本来就是目标项目根目录,Step 3 原地消费:不得复制到自身,也不得再次移动素材。除此之外,完整核心工作区是可移植的:可以从项目根复制到全局库根、从全局库复制到项目,或从另一个工作区直接复用,而不改变内部结构。注册是唯一与范围相关的步骤。
@@ -319,8 +321,8 @@ Deck 路径下用户已经拿到完整方案,策略师确认阶段收窄到"
| 工作流 | 产出 |
|---|---|
-| `workflows/create-brand.md` | brand 目录(identity-only),从品牌资产逆向提取 |
-| `workflows/create-template.md` | 完整 layout 或 deck 工作区。输出范围默认 `library`(`templates/<kind>/<id>/` + 注册),确认 `project` 时写 `projects/<name>/`(不注册)。两者具有相同核心目录与预览 PPTX。内部 kind 分支仍默认 deck;用户明说"只要结构 / 丢掉品牌色"时走 layout |
+| `workflows/create-brand.md` | 使用统一路由的 identity-only brand 工作区;空的可选目录省略 |
+| `workflows/create-template.md` | 完整 layout 或 deck 工作区。`standard` / `fidelity` 创作新语义 SVG,mirror 恢复来源合同。输出范围默认 `library`(`templates/<kind>/<id>/` + 注册),确认 `project` 时写 `projects/<name>/`(不注册)。两者使用相同的可选目录路由,预览 PPTX 按需生成;内部 kind 分支仍默认 deck,用户明说"只要结构 / 丢掉品牌色"时走 layout |
在全局库范围,frontmatter `kind` 字段决定工作区父目录位于 `templates/brands/` / `templates/layouts/` / `templates/decks/`。项目范围在项目工作区根目录保留同一 kind 语义。完整工作区可在两种范围之间迁移而不改形,只需增加或移除全局索引注册。
diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.md
index 95fb6aac..2a3b3ed3 100644
--- a/docs/zh/templates-guide.md
+++ b/docs/zh/templates-guide.md
@@ -18,13 +18,13 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
### 怎么触发模板流程
-在对话里写出 Layout/Deck 工作区根目录,或直接 Brand 包路径(位置不重要,只要明确即可):
+在对话里写出 Brand/Layout/Deck 工作区根目录(位置不重要,只要明确即可):
> "用这个模板做:`skills/ppt-master/templates/layouts/academic_defense/`" ✅
> "用上次那个模板:`projects/last_deck/`" ✅
> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
-对于当前 Layout/Deck,这里给的是**模板工作区根目录**。Step 3 会解析其中的 `templates/design_spec.md`,校验 structured SVG 合同,然后把 `templates/`、`images/` 与 `icons/` 安装进目标项目;如果工作区本来就是该项目根目录,则原地消费。路径可以指向 `skills/ppt-master/templates/<kind>/<id>/` 下的内置库工作区、`projects/<name>/` 下的项目工作区,或其他保持同样结构的工作区。Brand 包继续使用根目录 `design_spec.md` 合同。当前对话刚完成 create-template 时,可把精确的已验证工作区根目录直接交给 Step 3;这是“首条消息显式路径”规则的唯一例外。
+对于当前所有模板类型,这里给的都是**模板工作区根目录**。Step 3 会解析其中的 `templates/design_spec.md`,然后把 `templates/` 及实际存在的 `images/`、`icons/` 安装进目标项目;如果工作区本来就是该项目根目录,则原地消费,并且始终不复制 `exports/`。Deck/Layout 还会校验 structured SVG 合同。路径可以指向 `skills/ppt-master/templates/<kind>/<id>/` 下的内置库工作区、`projects/<name>/` 下的项目工作区,或其他保持同样路由的工作区。当前对话刚完成 create-template 时,可把精确的已验证工作区根目录直接交给 Step 3;这是“首条消息显式路径”规则的唯一例外。
> **兼容性预检:** Step 3 也接受旧式平铺包,即 `design_spec.md` 与 SVG 直接位于所给根目录。目录平铺本身不需要恢复;只有 SVG 仍使用旧的原子 placeholder / 未映射 Master/Layout 语义时,才先运行 [`restore-pptx-structure`](../../skills/ppt-master/workflows/restore-pptx-structure.md)。Step 3 不会先复制语义旧包、再延后恢复。
@@ -123,7 +123,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
### 第一步:准备参考材料
-**强烈推荐:直接给原始 `.pptx` 文件。** 导入器会读取 OOXML,提取全部 Master、Layout、placeholder、主题与可复用素材,并生成分层分析参考。Template_Designer 据此重建一个干净 Master 与语义 Layout,输出完整且显式分层的 SVG;原 PPTX 只作分析输入,不进入新模板包。
+**强烈推荐:直接给原始 `.pptx` 文件。** 导入器会读取 OOXML,提取全部 Master、Layout、placeholder、主题、原生形状事实与可复用素材,并生成分层分析参考。`standard` / `fidelity` 把它们当视觉参考,创作新的 SVG roster 与 Master/Layout/slot 系统;mirror 则一对一恢复来源身份、父子关系、placeholder 事实和受支持视觉。原 PPTX 只作分析证据,不进入新模板包。
也可以基于品牌指南从零设计:提供 logo、主色 HEX、字体、调性描述、几张氛围参考图,AI 会现场设计页面骨架。适合品牌方还没有成型 PPT、只有 VI 手册的场景。
@@ -135,7 +135,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
| 字段 | 说明 |
|------|------|
-| **输出范围** | `library`(默认)或 `project`;两者都写完整且相同的工作区,只有 library 会进入全局索引 |
+| **输出范围** | `library`(默认)或 `project`;两者使用相同的可移植工作区路由,只有 library 会进入全局索引 |
| **目标项目** | 仅 `project` 必填;必须给出已初始化项目的精确路径 |
| **模板 ID** | 模板的可移植身份;在 `library` 下同时也是目录名 / 索引键。优先 ASCII slug,如 `acme_consulting`;中文品牌名也行,但要文件系统安全 |
| **显示名称** | 文档中的人类可读名 |
@@ -144,15 +144,15 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
| **调性概要** | 一句话,如"现代克制、数据驱动" |
| **主题模式** | 浅色 / 深色 / 渐变…… |
| **画布格式** | 默认 `ppt169`(16:9),其他格式需提前指定 |
-| **复刻模式** | `standard`(默认 5 页基本套)/ `fidelity`(按视觉版式簇生成变体)/ `mirror`(逐页保持原视觉,同时补齐显式层级归属) |
-| **原生结构事实** | 简报会列出源 Master/Layout 数量、placeholder 身份和多母版情况;最终一律重建显式 SVG 结构(`template`)。 |
-| **保真级别** | (`standard` / `fidelity` 有源时必填)`literal`(按原样复刻几何/装饰/精灵图裁剪)/ `adapted`(借结构和调性、允许设计演化)。封面 / 章节 / 结尾通常用 `literal`。**`mirror` 模式不询问**——隐含 literal |
+| **复刻模式** | `standard`(默认精简基本套)/ `fidelity`(每个可复用语义家族一个变体)/ `mirror`(每张源页一个恢复原型)。`standard` / `fidelity` 创作新 SVG 语义;mirror 恢复来源结构,不做归纳。 |
+| **原生结构事实** | 简报会列出源 Master/Layout 数量、父子关系、placeholder 身份和多母版情况。`standard` / `fidelity` 只把它们当参考;mirror 通过当前 `structured` 合同一对一恢复。 |
+| **保真级别** | (`standard` / `fidelity` 有源时必填)`literal`(在新创作结构内尽量复现原几何、装饰和精灵图裁剪)/ `adapted`(借调性与构图、允许设计演化)。封面 / 章节 / 结尾通常用 `literal`。**`mirror` 模式不询问**——它恢复来源视觉。 |
| **关键词** | 3–5 个标签,用于索引检索 |
| 主题色 / 设计风格 / 素材清单 | 可选,可让 AI 从源里自动提取 |
确认后,工作流会回显一份完整简报并写入标记 `[TEMPLATE_BRIEF_CONFIRMED]`,从这一刻起后续步骤才会启动。**这是一个硬门——简报没确认,不会开始生成**。
-无论选择哪种范围,第一次写最终文件前都会做一次完整预检:解析四个目标目录,要求 `templates/` 为空,并检查 `images/`、`icons/`、`templates/icons/` 与 `exports/` 中计划写入的位图、图标和预览 PPTX 文件名没有冲突。项目范围还要求目标项目已经初始化。任一检查失败都会在写入前停止,不合并、不覆盖,也不会留下半套输出。
+无论选择哪种范围,第一次写最终文件前都会做一次完整预检:解析必需的 `templates/` 和实际需要的可选素材目录,要求 `templates/` 为空,并检查 `images/`、`icons/` 与 `templates/icons/` 中计划写入的位图和图标文件名没有冲突;只有明确要求审阅 PPTX 时才检查 `exports/`。项目范围还要求目标项目已经初始化。任一检查失败都会在写入前停止,不合并、不覆盖,也不会留下半套输出。
> 为什么这么严?无论模板进入全局库,还是只服务当前项目,它都是结构契约。先确认归属和几何,可避免半成品或资产落错目录。
@@ -162,26 +162,30 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
| | **standard** | **fidelity** | **mirror** |
|---|---|---|---|
-| 输出页数 | 5 页(封面/章节/目录/内容/结尾) | 视觉上真正不同的版式簇各一个变体——数量由源决定 | 每张源页 1:1 一页 |
-| 抽象程度 | 高 —— 干净可复用骨架 | 中 —— 聚类后清理 | **零** —— 原样复制 |
+| 输出页数 | 4–5 页(封面/章节/内容/结尾,可选目录) | 每个可复用语义家族一个变体——数量由源决定 | 每张源页一个恢复原型(1:1 页面集合) |
+| 抽象程度 | 高 —— 干净可复用骨架 | 中 —— 语义家族重新设计 | 拓扑层面不抽象,只做 structured 合同要求的机械归一化 |
| 作者占位符 | 是(`{{TITLE}}`、`{{CONTENT_AREA}}` 等) | 是 | 可保留原文字,但导入识别出的原生内容槽仍带语义 metadata |
| 适合场景 | 你只需要"调性 + 基本骨架",未来用模板生成全新 deck | 源 PPTX 本身就是高度定制的版式库 | 别人的精装 deck 直接好用、想把每页都当参考页 |
-| 典型例子 | 给品牌做基础模板 | 复刻一套政府汇报的 20 种章节版式 | 把一份 50 页的麦肯锡风格 deck 整套用作模板 |
-| 必须有 PPTX 源吗 | 否 | **是** | **是** |
+| 典型例子 | 给品牌做基础模板 | 复刻一套政府汇报的 20 种章节版式 | 把 50 张源构图都保留为视觉忠实的模板原型 |
+| 来源要求 | 无 | PPTX 或 SVG 视觉参考 | PPTX,或带完整显式结构合同的 SVG |
| 装饰复杂度 | 通常较简洁 | 需要保留精灵图裁剪等结构 | 保留原几何,并补齐显式层级归属 |
**关于精灵图**:PPTX 导出的素材常常是**一张大图 + 多页通过 viewBox 裁剪不同区域**。`fidelity` 和 `mirror` 模式下必须保留这层嵌套 `<svg viewBox=...>` 包装,不能扁平化为单张 `<image>`——否则裁剪信息丢失,画面会错位。工作流会自动校验这一点。
+**关于 PowerPoint 原生形状**:完整导入 SVG 保留在临时分析工作区,模型读取的是移除 opaque payload 和重复 carrier 的轻量 projection;projection 永远不是导出源。创作模式使用紧凑 canonical metadata。Mirror 可在未改的 Slide-local/slot 对象上复用转换器已支持的 metadata;固定 Master/Layout 层保持直接原子,不支持或已修改的对象保留当前 SVG fallback。
+
+**当前 mirror 边界**:每个来源 Layout 都必须至少被一张来源 Slide 使用,每个来源 Master 也必须能通过这些 Layout 到达。当前 structured 模板 roster 还不能在不虚构额外页面的情况下物化只存在于选择器里的未使用身份,因此预检会列出具体未使用身份并停止,而不是静默丢弃。
+
**`mirror` 模板怎么消费**:Strategist 为每个项目页选择一张 mirror 参考,Executor 复制完整 SVG 并原位修改可见文字,同时保留装饰、精灵图裁剪、几何坐标和全部 `data-pptx-*` 结构声明。
### 第四步:验证、预览导出、注册与发现
-模板生成完,两种范围都会先跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 作为硬门,并导出 `exports/<id>_template_preview.pptx`。先打开这份 PPTX,逐页判断模板在 PowerPoint 中的实际样子,再交给后续生成。唯一按范围分流的动作是全局注册:
+模板生成完,两种范围都会先跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 作为硬门。如果需要 PowerPoint 审阅文件,再运行可选预览导出;它会按需创建 `exports/<id>_template_preview.pptx`。唯一按范围分流的动作是全局注册:
| 范围 | 工作区根目录 | 预览 | 发现行为 |
|---|---|---|---|
-| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | `exports/<id>_template_preview.pptx` | 校验与预览导出后注册到对应 `layouts_index.json` 或 `decks_index.json` |
-| `project` | `projects/<name>/` | `exports/<id>_template_preview.pptx` | 跳过全局索引注册 |
+| `library`(默认) | `skills/ppt-master/templates/<kind>/<id>/` | 可选 `exports/<id>_template_preview.pptx` | 校验后注册到对应 `layouts_index.json` 或 `decks_index.json` |
+| `project` | `projects/<name>/` | 可选 `exports/<id>_template_preview.pptx` | 跳过全局索引注册 |
全局注册让模板**可被发现**——下次有人问“有哪些模板可用?”时,AI 会从索引里把它列出来。两种范围的用法相同:按 SKILL.md Step 3 的规则,在第一条消息里给出工作区根目录,例如 `用这个模板:skills/ppt-master/templates/layouts/<your_template_id>/` 或 `用这个模板:projects/<name>/`。项目工作区也可以迁移或被其他工作区复用,因为核心结构完全一致;只有放进全局库并需要被发现时才执行注册。
@@ -205,11 +209,11 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
│ ├── 03a_content_two_col.svg # fidelity 变体
│ ├── 04_ending.svg
│ └── icons/ # 使用时的 package / 校验副本
-├── images/
+├── images/ # 可选
│ └── *.png / *.jpg # SVG 统一引用 ../images/<name>
-├── icons/
+├── icons/ # 可选
│ └── *.svg # 提取向量素材的运行期副本
-└── exports/
+└── exports/ # 可选;按需生成审阅文件
└── <id>_template_preview.pptx
```
@@ -220,9 +224,9 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
### 全局注册与项目放置
- **全局库范围(`library`,默认)**把工作区写入 `skills/ppt-master/templates/<kind>/<id>/`,并完成全局注册。
-- **项目范围(`project`)**把同一份完整工作区写入 `projects/<name>/`,并跳过注册。
+- **项目范围(`project`)**把同一份可移植工作区写入 `projects/<name>/`,并跳过注册。
-项目范围不是私有或缩减格式。Step 3 可以直接接收任一工作区根目录;完整核心工作区也可以在两类根目录之间复制或迁移,无需改形。如果迁入全局库,再执行注册,让发现索引反映新位置。
+项目范围不是私有或缩减格式。Step 3 可以直接接收任一工作区根目录;`templates/` 及实际存在的 `images/`、`icons/` 可以在两类根目录之间复制或迁移,无需改形。如果迁入全局库,再执行注册,让发现索引反映新位置。
---
@@ -230,11 +234,11 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
避免常见误解:
-- **可复用模板是一份完整 SVG 重建契约,不是源 PPTX package**。每页可独立预览,显式 metadata 负责在导出时还原 Master/Layout/Slide
+- **可复用模板是一份显式 SVG 契约,不是打包后的源 PPTX**。创作模式新建该合同,mirror 通过该合同恢复来源归属;每页都能独立预览,导出只编译已声明的 Master/Layout/Slide 结构
- **模板不是"风格皮肤"**。它包含结构(页面有几块、信息层级如何分布)+ 风格(配色、字体、装饰),两者不可分割。试图只换"皮肤"不换结构,往往会让信息架构和视觉打架
- **模板不会替你做内容决策**。策略师仍然会按内容判断每页用哪个版式、要不要扩展为变体,模板提供候选,不预设结果
- **`fidelity` 模式不等于像素级搬运**。即便是 `literal` 保真,AI 仍会把杂质和不必要的重复结构清理掉——载体保留几何,但不照抄冗余
-- **`mirror` 模式确实是像素级搬运——但它继承源 PPT 的导入限制**。图表、SmartArt、OLE 对象、EMF / WMF 媒体如果在 `pptx_template_import.py` 里 round-trip 失败,mirror 也会同样失败。flat SVG 是事实源——`<workspace>/svg-flat/` 里看着断了,mirror 模板也会断
+- **`mirror` 的目标是受支持范围内的视觉与来源拓扑忠实,不是字节级 OOXML**。它继承源 PPT 的导入限制,只允许固定结构层 group 展开等机械归一化。不支持的原生对象保留可用 SVG fallback 或明确报告;mirror 不归纳替代 ownership。
---
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 8c0ec9e7..09ed3652 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -90,6 +90,7 @@ description: >
| `${SKILL_DIR}/scripts/latex_render.py` | LaTeX formula rendering (manifest-driven PNG assets) |
| `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) |
| `${SKILL_DIR}/scripts/slice_images.py` | Slice one AI illustration sheet into individual spot-illustration elements |
+| `${SKILL_DIR}/scripts/svg_authoring_view.py` | Create a lightweight non-destructive inspection projection of PPTX-imported SVGs; never a release source |
| `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check |
| `${SKILL_DIR}/scripts/preset_shape_svg.py` | Print one registry-backed native PowerPoint preset fragment to stdout for hand-authored SVG insertion |
| `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting |
@@ -132,6 +133,24 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
**MUST**: Beautify is strictly 1:1. Any split, merge, drop, reorder, or page-count change routes to the main pipeline.
+**MUST — reusable template mode boundary**: `create-template` has two distinct
+contracts. `standard` and `fidelity` author new SVG prototypes and their own
+Master/Layout/slot system; source visuals and assets are references, and source
+Master/Layout topology is neither preserved nor distilled. `mirror` is a
+restoration path: preserve the source slide roster/order, visual appearance,
+Master/Layout parentage and identities, placeholder type/index/bounds, native
+object ownership, and supported native-shape metadata. The lossless import is
+the restoration authority; the lightweight authoring projection exists only to
+keep model context small. Mechanical normalization may express the source facts
+in the current explicit SVG contract and expand fixed-layer group wrappers into
+direct atoms, but it MUST NOT merge, split, promote, demote, rename, or
+re-parent source structure. Export compiles the selected contract and never
+infers a different one. Because the current structured roster materializes only
+identities referenced by emitted page prototypes, `mirror` is available only
+when every source Layout is used by a source Slide and every source Master is
+reachable through those Layouts. Otherwise stop and report the exact
+unreachable identities; never drop them or invent a carrier page.
+
**FALLBACK**: Ambiguous requests such as "make this PPT more professional" require exactly one discriminator question: preserve original page count/order and slide wording, or treat the deck as source material and restructure it?
---
@@ -251,7 +270,7 @@ The architecture has three independent reference bundles. Full schema in [`docs/
|---|---|---|---|
| **brand** | `templates/brands/<id>/templates/` inside a complete workspace | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` |
| **layout** | `templates/layouts/<id>/templates/` inside a complete workspace | structure-only segment: canvas / page structure / page types / SVG roster | `kind: layout` |
-| **deck** | `templates/decks/<id>/templates/` inside a complete workspace | full replica: identity + structure + middle (template overview) segments | `kind: deck` |
+| **deck** | `templates/decks/<id>/templates/` inside a complete workspace | full identity + structure reference with the middle (template overview) segment | `kind: deck` |
**Segment ownership** (governs fusion override priority):
@@ -280,7 +299,7 @@ Normalize every explicit path before any write:
Never infer that a flat directory has legacy Master/Layout semantics solely from packaging.
-The same current-workspace routing applies to all three kinds: source/spec in `templates/`, visual assets in `images/`, runtime icons in `icons/`, and review artifacts in `exports/`. Empty optional roots are omitted rather than retained with placeholder files. Brand workspaces normally have no `exports/` because they have no SVG roster. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.
+The same current-workspace routing applies to all three kinds: source/spec in `templates/`, visual assets in `images/`, runtime icons in `icons/`, and on-demand review artifacts in `exports/`. Empty optional roots are omitted rather than retained with placeholder files, so a normal workspace has no `exports/` until a review file is explicitly generated. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.
When `create-template` used project output scope, its workspace root is the target project itself and all core directories are already final. Resolve both roots before copying: equality means **in-place consumption**, so skip the installation. An in-place workspace cannot participate in multi-path fusion; use external workspaces for fusion. Never place the local source under a nested `templates/local_master/` directory because the confirmation and quality gates read the project `templates/` root.
@@ -288,7 +307,7 @@ A project-scoped workspace has the same portable routing as a library workspace.
Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy or consume those semantic contracts through Step 3. Run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) on the package first, then return with the migrated workspace path. Old flat packaging remains readable when its SVG structure is already current.
-The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. New projects use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, and write complete `pptx_masters` / `pptx_layouts` output mappings before SVG generation. Strict preserves the referenced Master/Layout/slot contract. Adaptive keeps the template Master and may assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.
+The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. New projects use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, and write complete `pptx_masters` / `pptx_layouts` output mappings before SVG generation. Strict preserves the template's declared Master/Layout/slot contract. Adaptive keeps the template Master and may assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.
#### Multi-path fusion
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index c0fc934a..b905cf9a 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -28,7 +28,7 @@ Other files link here instead of restating its contracts.
| Text treatments | Mixed runs, tracking, underline, strikethrough, gradient fill, outline, transparency, watermark text, and text glow | §4.2, §6.7 |
| Transforms and composition | Translate, scale, rotate, mirror, supported matrix composition, layering, and static local reuse | §1.3, §6.8 |
| Freeform geometry | Full SVG path vocabulary, curves, organic containers, multi-subpaths, and asymmetric rounded rectangles | §6.9 |
-| Imported PowerPoint shapes | All 187 preset geometries, adjustments, logical frames, custom geometry, connectors, and unchanged native text bodies | §1.4 |
+| Imported PowerPoint shapes | Lossless import payload, lightweight inspection projection, and selective restoration of preset/custom geometry, connectors, and unchanged native text bodies | §1.4 |
| Authored PowerPoint preset shapes | Registry-generated visible fragments that export as one native preset shape or connector | §1.5; [`native-shape-authoring.md`](./native-shape-authoring.md) |
| Radial/chart geometry | Pie/donut arcs, dashed-circle ring segments, gauges, progress rings, sunbursts, and diagonal polygon arrowheads | §6.10 |
| Constructed visual styles | Faux glass, hand-drawn marks, ink wash, Riso offset, pixel grid, halftone, isometric facets, paper cut, and line-plus-area data treatment | §6.11 |
@@ -214,8 +214,10 @@ the original `<use>` / `<symbol>` structure.
### 1.4 Imported Native PowerPoint Shapes (Conditional Contract)
`pptx_to_svg.py` emits rendering-neutral metadata when a visible SVG object
-originates from `p:sp`, `p:cxnSp`, or `p:grpSp`. This contract is for imported
-round-trip SVG; ordinary authored SVG does not need these attributes.
+originates from `p:sp`, `p:cxnSp`, or `p:grpSp`. This contract is for lossless
+import SVGs and unchanged imported objects that remain Slide-local or inside a
+slot during mirror restoration. Ordinary authored SVG does not need these
+attributes, and no separate source-payload opt-in marker exists.
| Metadata | Placement | Required behavior |
|---|---|---|
@@ -232,6 +234,29 @@ round-trip SVG; ordinary authored SVG does not need these attributes.
| `data-pptx-shape-style` | Native carrier | Preserve a relationship-free `p:style` independently of text, including shapes with no visible text. |
| `metadata[data-pptx-part="txbody"]` | Logical shape `<g>` | Preserve unchanged `p:txBody`, including an empty text body. Content, whitespace, positioning, or visible typography edits invalidate the payload and use the normal SVG text fallback. |
+**Import/authoring representation split**:
+
+| Representation | Contract |
+|---|---|
+| Lossless import SVG | Keep complete native payload, hidden carriers, and preview evidence in the temporary analysis workspace. This is the round-trip source, not the model-facing authored page. |
+| Lightweight authoring projection | Exclude opaque payload and duplicate hidden carriers from model context while retaining visible shape intent and logical ids needed to locate an adopted object in the lossless import. It is not an export source. |
+| `standard` / `fidelity` output | Use compact canonical metadata for newly authored shapes; do not transplant opaque import payload or source topology. |
+| `mirror` output | Keep supported imported metadata only on unchanged Slide-local/slot objects. Expand fixed Master/Layout group wrappers into direct atoms while preserving source ownership, paint order, and visible appearance. |
+
+**Hard rule — structural-layer boundary**: An unchanged imported logical object
+may keep currently supported metadata while it remains Slide-local or inside a
+slot. A logical `<g>` cannot be assigned to Master/Layout because those layers
+require direct atoms. Mechanically expand a fixed-layer source group into direct
+atoms, rebuilding a preset when supported and otherwise retaining the visible
+SVG fallback. Do not use this normalization to change ownership or appearance.
+
+**Hard rule — selective payload**: Do not copy every imported metadata block into
+an authored template. Keep the full lossless import SVG separately as the
+audit/fallback source. Mirror may reuse only metadata already supported by the
+converter on unchanged Slide-local/slot objects; unsupported or edited objects
+use the current SVG fallback. `data-pptx-native` remains reserved for native
+chart/table markers.
+
**Registry and rendering rules**:
- The hash-locked shared registry must equal the independent 187-value shape
@@ -270,7 +295,9 @@ reconstruction are also normalized rather than byte-identical OOXML.
New SVG pages may opt one complete geometric object into a native DrawingML
preset through the deterministic fragment helper. Selection behavior lives in
[`native-shape-authoring.md`](./native-shape-authoring.md); this section owns
-the machine contract.
+the machine contract. This is compact canonical authoring metadata: it describes
+the intended preset, frame, adjustments, paint, and preview fingerprint without
+embedding source OOXML or relying on an imported-payload marker.
| Metadata / structure | Required behavior |
|---|---|
@@ -1350,7 +1377,7 @@ defaults to `bottom` and accepts `top`, `left`, or `right`.
### Structured Layout Routing
-Every new SVG project has one deterministic route: `pptx_structure.mode: structured`. `spec_lock.md` contains a complete Master roster and one page-to-Master/Layout row before the first page is drawn. Free design defaults to one Master; templates preserve their restored Master topology.
+Every new SVG project has one deterministic route: `pptx_structure.mode: structured`. `spec_lock.md` contains a complete Master roster and one page-to-Master/Layout row before the first page is drawn. Free design defaults to one Master. `standard` / `fidelity` templates use their newly authored contract; mirror templates use the restored source identities and parentage expressed through the same explicit interface.
**Hard rule — no structure inference**: Export does not assign Layout families, promote repeated chrome, cluster pages, infer placeholders, or repair missing metadata. It compiles only the declared root identities, atomic fixed layers, and slot groups. Legacy or unmapped projects must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.
@@ -1366,7 +1393,7 @@ Every new SVG project has one deterministic route: `pptx_structure.mode: structu
**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A page row is `P<NN>: <master_key> | <layout_key> | <PowerPoint layout name>`. The SVG root values MUST match those rows. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when pages share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.
-**Template behavior**: Strict preserves the selected prototype's Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror additionally preserves literal paint, typography, effects, atomic geometry, and referenced assets for every reused identity. The source PPTX group hierarchy may still be flattened because Master/Layout groups are outside the current SVG contract.
+**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve restored source identity, literal paint, typography, effects, atomic geometry, and referenced assets. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology.
**Master text-style contract**: Structured export maps the
locked `title` size to every `a:defRPr` in Master `p:titleStyle`, and map the
@@ -1489,7 +1516,7 @@ video or audio media from a decorative SVG group.
Existing projects or packages that carry `native_structure.json` / `source_template.pptx`, `pptx_structure.mode: baseline|template|preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled` / `utility`, direct atomic placeholders, or no root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation or export.
-When original PPTX/native facts exist, migration preserves the source Master roster, Layout parent relationships and picker names, placeholder type/index/bounds, and visible supported geometry. Source Master/Layout groups are recursively flattened into atomic SVG elements. When no native facts exist, the main Agent explicitly derives a structured contract from the complete SVG pages; the exporter never performs that derivation.
+When original PPTX/native facts exist, migration preserves the reachable source Master roster, Layout parent relationships and picker names, placeholder type/index/bounds, and visible supported geometry while normalizing the package into the explicit contract. Source Master/Layout groups are recursively flattened into atomic SVG elements. The current structured roster cannot materialize a source Layout that no output page references, or a Master reachable only through such Layouts; stop and report those identities instead of silently dropping them or inventing a carrier page. A subsequent `create-template` run treats the result according to its selected mode: `standard` / `fidelity` author a new topology, while mirror keeps the restored source topology only when the source graph satisfies that reachability boundary. When no native facts exist, the main Agent explicitly derives a structured contract from the complete SVG pages; the exporter never performs that derivation.
---
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index 81a1ab18..d0f0c2e6 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -17,20 +17,21 @@ Generate reusable page templates inside the complete workspace selected by `crea
**Hard rule — scope is execution metadata**: Use `output_scope` and `target_project` to route files, but do not write either field into portable `design_spec.md` frontmatter. Do not create a new PPTX structure mode; deck/layout output declares `native_structure_mode: structured`.
-**Workspace precondition**: The workflow has already resolved the selected root, confirmed an empty `<template_workspace>/templates/`, and checked collision-free destination filenames in `images/`, `icons/`, `templates/icons/`, and `exports/`. Project scope additionally requires an initialized target project. Do not begin final writes before that all-at-once preflight passes.
+**Workspace precondition**: The workflow has already resolved the selected root, confirmed an empty `<template_workspace>/templates/`, and checked collision-free destination filenames in `images/`, `icons/`, and `templates/icons/`. Check `exports/` only when an on-demand review PPTX was requested. Optional directories may be absent until their first real file is written. Project scope additionally requires an initialized target project. Do not begin final writes before that all-at-once preflight passes.
When the workflow provides a PPTX reference source, the effective input package comes from the unified `pptx_template_import.py` preparation workspace and becomes:
- finalized template brief
-- `manifest.json` — single source of truth (slide size, theme, per-master themes, assets, asset map, placeholders, layouts, masters, slides, SVG file paths, page-type candidates)
+- `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
- exported `assets/`
-- `svg/master_*.svg` / `svg/layout_*.svg` — every master / layout in the deck rendered once as standalone SVG, including ones no sample slide references (template packages often ship more design surfaces than the embedded samples exercise)
-- `svg/slide_NN.svg` — each slide's own shapes and slide-local background only; master / layout decoration and backgrounds are **not** inlined here
+- `svg/master_*.svg` / `svg/layout_*.svg` — lossless layered import evidence; every master / layout in the deck rendered once, including ones no sample slide references
+- `svg/slide_NN.svg` — lossless slide-local import evidence; do not bulk-read because opaque native payload is retained
- `svg/inheritance.json` — which layout / master each slide consumes
-- `svg-flat/slide_NN.svg` — companion view; each slide is self-contained so you can preview or screenshot a single page without losing the surrounding chrome. Use it as a sanity check for "what would PowerPoint actually show", not as an authoring source — the master/layout chrome will be duplicated across every flat slide.
+- `svg-flat/slide_NN.svg` — lossless complete-page import evidence; use it as mirror restoration authority, not as model-facing context
+- `authoring-svg/` / `authoring-svg-flat/` — lightweight non-destructive projections created by `svg_authoring_view.py`; these are the model-facing layered and complete-page views
- optional screenshots for visual cross-checking
PPTX import interpretation:
@@ -39,22 +40,38 @@ PPTX import interpretation:
- Charts, SmartArt, diagrams, and OLE objects may appear as typed placeholders in layered SVGs. In flat SVGs they may show preview images. Treat them as source intent markers, not reusable decorative assets.
- The asset filenames referenced by SVGs are governed by the manifest asset map. Prefer those references over inventing duplicate asset names.
-Input priority for PPTX-backed template creation:
+Input priority for PPTX-backed template creation depends on replication mode:
-1. `manifest.json` for all factual metadata (theme, assets, unique layout/master structure, slide reuse, page-type guidance)
-2. `native_structure.json` for source PowerPoint identities, placeholder indices, relationship completeness, and reconstruction facts
-3. `svg/master_*.svg` + `svg/layout_*.svg` — the **primary source for the deck's shared visual language**: backgrounds, page chrome, decorative bars, recurring brand motifs. These are what the new template's fixed structure should adopt or reinterpret. Read these before any slide SVG.
-4. `svg/inheritance.json` for confirming which slide uses which layout / master
-5. exported `assets/` for reusable visual resources
-6. `svg/slide_NN.svg` — each slide's unique content, useful for judging composition rhythm and content density (not for fixed structure)
-7. `summary.md` only as a fast scan; never as the canonical fact source
-8. screenshots / original PPTX only for style verification
+| Mode | Authoritative inputs | Model-facing inputs |
+|---|---|---|
+| `standard` / `fidelity` | Finalized brief for the newly designed output; `manifest.json` for factual canvas/theme/assets | Lightweight `authoring-svg-flat/` pages and 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`, lossless layered `svg/`, lossless complete-page `svg-flat/`, and `svg/inheritance.json` | Matching lightweight `authoring-svg/` and `authoring-svg-flat/` projections for inspection. The projections never replace the lossless restoration source. |
-**Native structure output**: Always set `native_structure_mode: structured`. Do not ship `native_structure.json` or `source_template.pptx`. Reconstruct the source Master roster and Layout graph through explicit SVG metadata. Recursively flatten source Master/Layout groups into direct atomic elements while pushing supported transforms, styles, opacity, and paint order into each atom. Every page remains a complete standalone SVG preview, and every source Layout is represented by at least one complete template page even when no source Slide used it. Mirror is the page-count exception: report unused source Layouts that cannot be represented and use fidelity when the full picker roster must be materialized.
+Use `summary.md` only for orientation. Open screenshots or the original PPTX only for visual cross-checking.
+
+**Native structure output**: Always set `native_structure_mode: structured`.
+
+| Mode | Output structure contract |
+|---|---|
+| `standard` / `fidelity` | Author new SVG prototypes and an intentional new Master/Layout/slot system. Source visual language and assets may guide the design, but source ownership, keys, picker names, parent relationships, placeholders, and repeated Slide-local elements do not define or seed the output topology. Use compact canonical metadata for authored objects. |
+| `mirror` | Restore the source graph one-to-one: keep source Master/Layout identities and parentage, slide assignments, placeholder type/index/bounds, and supported visual/native-object facts. Mechanical normalization maps fixed-layer source groups into the direct atoms required by the current explicit SVG contract while preserving ownership, paint order, and appearance; it must not semantically redesign the graph. |
+
+Every page remains a complete standalone SVG preview.
+
+**Hard rule — mirror graph reachability**: The current structured template
+compiler materializes only Master/Layout identities referenced by emitted SVG
+prototypes. Before accepting `mirror`, verify that every source Layout has a
+non-empty `usedBySlides` set and that every source Master owns at least one such
+Layout. If the source package contains an unused Layout or an otherwise
+unreachable Master, stop and report that full-graph mirror is not representable
+by the current template roster. Never silently drop it, merge it, or invent a
+carrier page.
+
+**Hard rule — no duplicate authored Layout contracts**: In `standard` / `fidelity`, distinct output Layout keys must differ in fixed Layout atoms or slot topology/type/index/bounds/binding. Topic, sample wording, or Slide-local content alone never justifies another authored key. Mirror keeps source Layout identities even when two source contracts are visibly equivalent.
**Downstream boundary**: The Strategist confirmation stage selects `strict` or `adaptive` when a project consumes this package. Both export through `pptx_structure.mode: structured`. Strict keeps the referenced Layout contract; adaptive may create a new Layout identity while retaining the template Master. Template_Designer does not preselect that project-level choice.
-When the source has a native Layout graph, `design_spec.md §V` must be followed by a `Source Structure Reconstruction` table. Record every source Master/Layout key/name, parent relationship, output SVG, and rebuilt key/picker name; if mirror cannot materialize an unused source Layout, record the explicit unsupported reason. Never silently merge, drop, or re-parent source structure.
+For `mirror`, `design_spec.md §V` must be followed by a `Source Restoration Map` that records each source slide's Master/Layout assignment and output file. The map is evidence of one-to-one preservation, not a design-decision log. `standard` and `fidelity` record only their newly authored output roster and structure; do not add a source-topology disposition table.
---
@@ -65,8 +82,10 @@ The output page set is determined by **replication mode**, declared in the final
| Mode | When to use | Roster |
|------|-------------|--------|
| `standard` (default) | Most templates — clean, reusable, balanced coverage | `01_cover`, `02_chapter`, `03_content`, `04_ending`, optional `02_toc` |
-| `fidelity` | User explicitly wants strict replication of a source PPTX, but still wants the AI to clean / cluster / cap variants | Standard roster + one variant per distinct layout cluster found in `manifest.json` |
-| `mirror` | Creation-time harvesting mode: every source slide keeps literal visual geometry while gaining explicit Master/Layout metadata | One SVG per source slide, named `<NNN>_<page_type>.svg` by source order |
+| `fidelity` | User wants a broader, source-aligned but newly designed template | Standard roster + intentionally designed variants that cover useful reference compositions |
+| `mirror` | User wants the source template restored | One SVG prototype restored from the lossless source per source slide, named `<NNN>_<page_type>.svg` by source order |
+
+**Hard rule — mode controls authorship**: `standard` and `fidelity` create new SVG documents and their own Master/Layout system. `mirror` restores the imported source contract and must not reauthor, distill, or reinterpret its structure.
### Standard mode
@@ -84,7 +103,7 @@ The output page set is determined by **replication mode**, declared in the final
### Fidelity mode
-When the brief sets `Replication mode: fidelity`, derive the page roster from `manifest.json` page-type clusters and emit one SVG per distinct visual cluster.
+When the brief sets `Replication mode: fidelity`, design a broader reusable roster that stays close to the source's visual language and useful composition examples. The output Master/Layout system is authored independently from source topology.
**Variant naming**: append a lowercase letter suffix to the parent type's index, preserving sort order:
@@ -98,27 +117,28 @@ Extension page types beyond the canonical four (transition / appendix / disclaim
**Roster decision**:
-- Cluster slides from `manifest.json` by `pageType` + visual structure (column count, hero-image vs. icon-grid vs. quote, etc.)
-- One SVG per cluster — do **not** emit a variant for a cluster represented by a single source slide unless that slide is structurally distinct from existing variants
-- One variant per visually distinct cluster — let the source's structural diversity drive the count. Collapse only **near-duplicates** (same column count, same hero element, same content density); do not collapse genuine structural differences just to keep the variant count down. If you find yourself wanting one variant per source slide, that is the signal the user should be in `mirror` mode, not `fidelity`
+- Choose variants from useful visual composition types such as two-column content, hero image, icon grid, data card, and quote
+- Keep only variants that add a genuinely useful authored composition; source Layout keys and repeated source chrome are not clustering inputs
+- Design each variant's Master/Layout/slot contract directly from its intended reusable behavior
- Record every emitted page in `design_spec.md §V Page Roster`; in library scope, `register_template.py` generates the corresponding index entry from `<template_workspace>/templates/*.svg`. Project scope skips registration
> Variants reuse the parent type's placeholder set — see §4 (Placeholder Reference) below.
### Mirror mode
-When the brief sets `Replication mode: mirror`, preserve literal page appearance while reconstructing layer ownership:
+When the brief sets `Replication mode: mirror`, restore the imported template rather than designing a new one:
-- Visual source: `<import_workspace>/svg-flat/slide_NN.svg` (the self-contained "what PowerPoint shows" view). Structural source: `svg/master_*.svg`, `svg/layout_*.svg`, and `svg/inheritance.json`.
+- Restoration source: lossless `svg/master_*.svg`, `svg/layout_*.svg`, `svg/slide_NN.svg`, `svg-flat/slide_NN.svg`, `svg/inheritance.json`, and `native_structure.json`. Use matching lightweight projections only to inspect the result without loading opaque payload into model context.
+- Precondition: every source Layout is referenced by at least one source slide, and every source Master is reachable through those referenced Layouts. Otherwise report that full-graph mirror is currently unsupported and stop before writing output.
- Output: `<template_workspace>/templates/<NNN>_<page_type>.svg` in both scopes. `<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.
-- Required metadata rewrite: declare the output Master/Layout key and picker names on the root, mark inherited Master/Layout visuals as direct atomic elements, and map source content slots to top-level semantic slot groups where the imported contract exposes them. Add `data-pptx-role` only to structural page-frame objects whose behavior is not already expressed by specialized markers.
-- Other allowed modifications: rewrite `<image href="...">` paths to local assets and rename assets semantically. Keep geometry, decoration, sprite-sheet wrappers, original example text, chart previews, and fonts visually unchanged.
-- Forbidden: simplifying decorative complexity, merging similar slides, or dropping inherited preview chrome.
-- `design_spec.md` §V Page Roster lists every emitted file with a one-line content-fit description; SVG metadata owns native reconstruction.
+- 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.
+- Allowed normalization: add or normalize explicit root declarations and asset paths, and recursively expand fixed Master/Layout group wrappers into direct atoms. The mapping must remain one-to-one at the ownership level and must not change paint order or appearance.
+- Forbidden: commonality extraction, semantic synthesis, merging, splitting, promotion, demotion, renaming, re-parenting, decorative simplification, placeholder invention, or replacement of supported source-native metadata / SVG fallback with a model-authored approximation.
+- `design_spec.md` §V Page Roster lists every emitted file, and `Source Restoration Map` records the preserved source Master/Layout assignment.
**Mirror consumption boundary**: `mirror` applies only while creating the template package from the source deck. Once created, the package is consumed as an ordinary deck / layout template roster: downstream generation may select, repeat, skip, reorder, or adapt pages according to the new content. The `replication_mode: mirror` field must not force the generated deck to preserve the source page count, source order, or one-output-slide-per-template-slide mapping.
-**What mirror is not**: a pixel-perfect re-rendering pipeline test. Charts, SmartArt, OLE objects, and EMF / WMF media that fail to round-trip in `pptx_template_import.py` will fail the same way in mirror. If the import workspace has missing media or unsupported objects, mirror inherits those gaps — the user should be told before generation begins.
+**What mirror is not**: a redesign or topology-cleanup mode. It may mechanically transcode the imported representation into the current explicit SVG/package contract, so byte identity is not promised. Charts, SmartArt, OLE objects, and EMF / WMF media that fail to round-trip in `pptx_template_import.py` will fail the same way in mirror. If the import workspace has missing media or unsupported objects, mirror inherits those gaps — report them before restoration begins.
---
@@ -187,9 +207,9 @@ native_structure_mode: structured
- Optional XML snippet for any reusable component unique to this template
## V. Page Roster
-One row per emitted SVG describing what this template's version of cover / chapter / content / ending looks like (background treatment, decorative anchors, layout rhythm, image behavior, content density, intended content slot). Record the rebuilt Layout key and PowerPoint picker name. For `fidelity` mode, note the cluster source and visual differentiator. For `mirror` mode the roster is the load-bearing content-fit index, so each row must distinguish siblings by column count, hero element, density, and suitable content. Roster entries must match the actual SVG files on disk.
+One row per emitted SVG describing what this template's version of cover / chapter / content / ending looks like (background treatment, decorative anchors, layout rhythm, image behavior, content density, intended content slot). For `standard` / `fidelity`, record the newly authored Layout key and PowerPoint picker name. For `mirror`, record the restored source Master/Layout keys and picker names without redesigning them. Roster entries must match the actual SVG files on disk.
-For a source-derived native template, add `### Source Structure Reconstruction` immediately after the roster with columns `Source Master/Layout key/name`, `Parent Master`, `Output SVG`, `Rebuilt key/picker name`, and `Disposition`. Include one row for every source Master/Layout, including explicitly unsupported mirror Layouts.
+For `mirror`, add `### Source Restoration Map` immediately after the roster with columns `Source slide`, `Source Master`, `Source Layout`, `Output SVG`, and `Restoration status`. This is a one-to-one mapping record. Do not add synthesis rationale or source-structure disposition rows to `standard` / `fidelity` templates.
## VI. Assets (omit when none)
Logos, cover backgrounds, brand textures bundled with the template package — file name, dimensions, intended usage.
@@ -203,11 +223,11 @@ Sections to **omit** from template `design_spec.md` (sourced elsewhere — listi
| Don't write | Source |
|---|---|
| General SVG technical / compatibility rules | `shared-standards.md` |
-| Generic layout pattern library (centered card / 三栏 / timeline / …) | `design_spec_reference.md` §V |
+| Generic layout pattern library (centered card / three-column / timeline / …) | `design_spec_reference.md` §V |
| Generic spacing bands (margin 40-60px, card gap 20-32px, etc.) | `design_spec_reference.md` §V |
| Generic font-size hierarchy (cover 2.5-5x body, page title 1.5-2x, …) | `design_spec_reference.md` §IV |
| Canonical placeholder table (`{{TITLE}}`, `{{PAGE_NUM}}`, …) | §4 below |
-| Content methodology (pyramid / SCQA / MECE / 金字塔) | `strategist.md` |
+| Content methodology (pyramid / SCQA / MECE) | `strategist.md` |
| "Usage Instructions" boilerplate (copy template / select page / …) | `create-template.md` |
| Created Date / Page Count rows | not a library-level field |
@@ -233,56 +253,74 @@ If PPTX import output exists:
**Precondition**:
-- When PPTX import output is provided, do not generate any template SVG or `design_spec.md` until every file under `<import_workspace>/svg/` has been read — including `master_*.svg`, `layout_*.svg`, and every `slide_*.svg`
-- Before template generation begins, explicitly report the read slide indexes
+- For `standard`, inspect enough lightweight complete-page projections to understand the requested visual direction and reusable assets; do not analyze source topology.
+- For `fidelity`, inspect every lightweight complete-page projection so the newly designed roster covers the useful source composition range; do not derive output ownership from source Master/Layout recurrence.
+- For `mirror`, verify every projected Master, Layout, and Slide against `native_structure.json` and `svg/inheritance.json`, then restore from the matching lossless files. Before restoration begins, report the verified source slide indexes.
-### 2.1 PPTX Import Simplification Rule
+### 2.1 PPTX Import Mode Rule
-The imported PPTX is a **reference source**, not a direct conversion target.
+The imported PPTX has a different authority level in each replication mode.
-Do:
-- preserve brand assets, recurring backgrounds, and stable structural motifs
-- rebuild the layout into a clean SVG structure aligned with PPT Master constraints
-- simplify repeated decorative fragments into a smaller number of maintainable SVG elements
-- use a background image asset when the original decorative layer is too complex to recreate cleanly
-- use cleaned slide SVG references to inspect composition, spacing, text hierarchy, and fixed decorative structure only after factual metadata has been anchored
-- read every reference SVG under `svg/` — `master_*.svg`, `layout_*.svg`, and every `slide_*.svg` regardless of slide count. Master / layout files describe the deck's shared visual language (read first); slide files describe per-page content (read after). Partial coverage drops template fidelity.
-- materialize every source Layout into at least one complete template page by composing its parent Master atoms, Layout atoms, slot contract, and an appropriate Slide sample; never silently merge, drop, or re-parent source structure.
-- rename adopted assets to semantic names (`cover_bg.png`, `brand_emblem.png`) rather than carrying raw `image3.png` into the final template
-
-Do not:
-- attempt 1:1 translation of every PowerPoint shape, group, shadow, or decorative fragment
-- mirror PPT-specific complexity when it makes the resulting SVG brittle or hard to edit
-- introduce dense low-value vector detail that does not materially improve template reuse
+| Mode | Required behavior |
+|---|---|
+| `standard` | Use source visuals/assets as references, then author the compact canonical roster and its Master/Layout/slot structure from the confirmed brief. Do not preserve or distill source topology. |
+| `fidelity` | Use the complete visual roster as design reference, then author a broader canonical roster and its own Master/Layout/slot structure. Match the source visual language closely, but do not cluster, merge, or split source Layouts into output families. |
+| `mirror` | Restore source pages, inheritance, placeholders, native objects, and visuals from the lossless import. Do not simplify, redesign, rename structure, or infer new common structure. |
+
+**Hard rule — restoration is mechanical**: Mirror may normalize namespaces,
+portable asset paths, explicit root declarations, and fixed-layer group wrappers
+required by the current compiler. Expanding a source Master/Layout group must
+produce direct atoms with the same ownership, transforms, paint order, and
+appearance. A maintainability preference is not authority to alter the source
+template.
+
+### 2.2 Native Shape Payload and Authoring Projection
+
+| Representation | Purpose | Payload rule |
+|---|---|---|
+| Lossless import SVG | Round-trip and mirror-restoration source | Retain complete imported metadata, native object boundaries, hidden carriers, and source-scope identity. It is authoritative for mirror restoration. |
+| Lightweight authoring projection | Model-readable inspection surface | Omit opaque native payload and duplicate hidden carriers from model context; retain visible shape intent and logical ids needed to locate an adopted object in the lossless import |
+| `standard` / `fidelity` output | Newly authored contract | Use compact canonical metadata for new shapes. Reuse exported image/vector assets, not opaque source shape payload or source topology. |
+| `mirror` output | Restored contract | Keep currently supported imported metadata on unchanged Slide-local/slot objects. Normalize fixed structural layers into direct atoms from the lossless source. The projection never becomes the restoration source. |
+
+**Validation**: Mirror does not silently use stale metadata or a lightweight
+projection. If an imported object cannot use the converter's supported native
+metadata after normalization, keep its current SVG fallback and report the
+limitation. `standard` / `fidelity` regenerate compact canonical shapes instead
+of transplanting opaque source payload. `data-pptx-native` remains reserved for
+native chart/table markers.
**Explicit template SVG contract**:
-| Rebuilt fact | Template SVG declaration |
+| Authored/restored fact | Template SVG declaration |
|---|---|
-| Output semantic Master/Layout | Root `data-pptx-master` / `data-pptx-master-name` plus `data-pptx-layout` / `data-pptx-layout-name` |
-| Rebuilt Master/Layout visual | Direct atomic child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"`; `<g>` is forbidden for either layer |
-| Semantic content slot | Direct `<g id>` with `data-pptx-placeholder` and explicit `data-pptx-placeholder-bounds`; exactly one compatible direct child carries `data-pptx-placeholder-carrier="true"` |
+| Master/Layout identity | Root `data-pptx-master` / `data-pptx-master-name` plus `data-pptx-layout` / `data-pptx-layout-name`; authored keys for `standard` / `fidelity`, source keys for `mirror` |
+| Authored Master/Layout visual | In `standard` / `fidelity`, use a direct atomic child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"`; `<g>` is forbidden for a structural layer |
+| Restored Master/Layout visual | In `mirror`, recursively expand each fixed-layer source group into direct atoms with the same Master/Layout ownership, transforms, styles, paint order, and appearance; semantic regrouping is forbidden |
+| Content slot | Direct `<g id>` with `data-pptx-placeholder` and explicit `data-pptx-placeholder-bounds`; `standard` / `fidelity` author the slot, while `mirror` preserves source type/index/bounds and carrier identity |
| Page-only background | Direct full-canvas solid rect with `data-pptx-layer="slide"` |
| Structural page-frame hint | Optional `data-pptx-role` only when background/decoration/header/footer/logo/watermark/chrome/page-number behavior is not already expressed by layer/placeholder metadata; stable unique `id` required |
-Repeat inherited visuals in every standalone SVG so browser preview remains complete. Template export validates their equality, moves one copy into the generated Master/Layout parts, and removes the repeated Slide copies. Do not flatten inherited visuals into unmarked slide content.
+Repeat inherited visuals in every standalone SVG so browser preview remains complete. Template export validates their equality and restores or creates the declared Master/Layout parts. It does not infer ownership.
**Forbidden — legacy structure contract**: Do not carry `data-pptx-layout-kind`, `distilled`, `utility`, unmapped `baseline`, `preserve`, or direct atomic placeholders into a reusable template package. Route that source through [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.
**Composite slot boundary**: A normal slot group has exactly one compatible direct carrier. Only a genuinely composite region may declare `data-pptx-placeholder="object"` with `data-pptx-placeholder-binding="proxy"`; the visible group stays Slide-local and export creates a hidden transparent binding proxy. Do not use proxy binding as the default template slot form.
-Use the imported placeholder types verbatim: `title`, `subtitle`, `body`,
-`picture`, `chart`, `table`, `object`, `media`, `date`, `footer`, and
-`slide-number`. In particular, do not collapse source `subTitle`, `obj`,
-`media`, or `dt` placeholders into a generic body marker. A reconstructed
-title normally has no index. Assign stable indices only when repeated roles need
-disambiguation inside the rebuilt Layout.
+In `mirror`, preserve imported placeholder types, indices, bounds, and carrier
+identity exactly when the importer supports them. Do not replace source
+`subTitle`, `obj`, `media`, or `dt` roles with generic body content. In
+`standard` / `fidelity`, assign the canonical authored types deliberately:
+`title`, `subtitle`, `body`, `picture`, `chart`, `table`, `object`, `media`,
+`date`, `footer`, and `slide-number`. An authored title normally has no index;
+assign stable indices only when repeated roles need disambiguation inside the
+new Layout.
-**Hard rule — explicit design-zone bounds**: Every slot in a newly created template carries `data-pptx-placeholder-bounds="x y width height"`. For imported slots, use the source Layout geometry from `manifest.json` / `native_structure.json`. For new slots, use the intended safe area, column, panel inset, or media frame. Do not use character count, glyph width, current wrapping, or the tight sample-content box. A Layout may intentionally have zero slots.
+**Hard rule — explicit design-zone bounds**: Every slot carries `data-pptx-placeholder-bounds="x y width height"`. Mirror uses the source Layout placeholder frame. `standard` / `fidelity` author bounds from the intended safe area, column, panel inset, or media frame. Do not use character count, glyph width, current wrapping, or the tight sample-content box. An authored Layout may intentionally have zero slots.
### 3. Placeholder Markers
-> Mirror may retain literal example text instead of `{{...}}` authoring markers, but imported semantic content slots still receive native `data-pptx-placeholder` metadata. The rest of this section defines the preferred authoring vocabulary for standard and fidelity modes.
+> Mirror retains literal source example text and source placeholder metadata. It does not insert `{{...}}` markers. The rest of this section defines the preferred authoring vocabulary for standard and fidelity modes.
Use clear placeholder markers for replaceable content:
@@ -351,7 +389,7 @@ Do **not** create new TOC placeholder families such as `{{CHAPTER_01_TITLE}}` fo
Variants reuse their parent type's placeholder set by default: every `03*_content*.svg` shares the content placeholder list above, unless the spec frontmatter declares an override for that specific stem.
-When rebuilding from imported PPTX references, placeholder insertion takes priority over visual mimicry. If the original layout leaves insufficient room for canonical placeholders, adjust the layout instead of inventing one-off placeholder families — or, if the deviation is intentional and meaningful, declare it in frontmatter.
+For `standard` / `fidelity`, canonical placeholder insertion takes priority over visual mimicry; adjust the newly designed layout or declare an intentional vocabulary override. Mirror preserves the source placeholders and literal text instead of inserting canonical authoring markers.
---
@@ -378,11 +416,11 @@ Standard mode (default):
│ ├── 03_content.svg
│ ├── 04_ending.svg
│ └── icons/ # Package/validation copy, when used
-├── images/
+├── images/ # Optional; omit when unused
│ └── *.png / *.jpg # SVG href is ../images/<name>
-├── icons/
+├── icons/ # Optional; omit when unused
│ └── *.svg # Runtime copy, when used
-└── exports/
+└── exports/ # Optional; created only for on-demand review
└── <template_id>_template_preview.pptx
```
@@ -418,21 +456,21 @@ Mirror mode emits one SVG per source slide, named by source order:
└── 050_ending.svg
```
-Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. Literal source text may remain, but every page still carries explicit native structure metadata.
+Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. Literal source text and the source native structure are restored; the lightweight projection is not copied into the output.
-**Hard rule — common routing**: Keep `design_spec.md`, template SVGs, and non-bitmap template-source assets in `templates/`; place every bitmap in `images/`; duplicate each extracted icon into `templates/icons/` and runtime `icons/`; write the review deck to `exports/`. Do not branch asset placement by output scope.
+**Hard rule — common routing**: Keep `design_spec.md`, template SVGs, and non-bitmap template-source assets in `templates/`; place every bitmap in `images/`; duplicate each extracted icon into `templates/icons/` and runtime `icons/`. Write a review deck to `exports/` only when explicitly requested. Create optional directories only when they contain real files; never add placeholders for empty directories. Do not branch asset placement by output scope.
### Template Preview
-After SVG validation, run `template_preview_pptx.py <template_workspace>`. The template is incomplete until `exports/<template_id>_template_preview.pptx` reopens with one slide per SVG prototype and the expected Master/Layout counts. The first export refuses a collision; an intentional post-fix replacement uses `--force`. The review PPTX is derived evidence and never a template-application input.
+When the user requests a PowerPoint review file, run `template_preview_pptx.py <template_workspace>` after SVG validation. The command creates `exports/` on demand and verifies one slide per SVG prototype plus the expected Master/Layout counts. The first export refuses a collision; an intentional post-fix replacement uses `--force`. The review PPTX is derived evidence and never a template-application input.
-Provide a brief summary table listing each template's status and the review PPTX path.
+When a review deck was generated, include its path in the completion summary. Otherwise omit `exports/` from the workspace inventory.
If the template is based on PPTX import output, briefly note:
- which extracted assets were reused directly
-- which complex original decorations were intentionally simplified
-- whether any page-type mapping required judgment beyond the import heuristic
-- how the source Master/Layout graph was reconstructed, including group flattening and any explicitly unsupported source structures
+- for `standard` / `fidelity`, which visual references influenced the newly authored roster
+- for `mirror`, whether any source feature could not be restored and the exact affected source object/page
+- whether any page-type filename mapping required judgment beyond the import heuristic
---
@@ -440,13 +478,13 @@ If the template is based on PPTX import output, briefly note:
If suitable template resources already exist, use them directly instead of generating new ones:
-1. **Copy template workspace**: copy or stage `templates/`, `images/`, and `icons/` together; exclude `exports/` from template application.
+1. **Copy template workspace**: copy or stage `templates/` plus any existing `images/` and `icons/`; exclude `exports/` from template application.
2. **Adjust colors**: Modify colors per the project design spec
3. **Customize**: Make project-specific adjustments
This section describes downstream reuse of an existing workspace. Library and project scopes carry the same portable template contract.
-**Example library structure** (query the appropriate kind's index — `templates/layouts/layouts_index.json` for structure-only templates, `templates/decks/decks_index.json` for full-PPT replicas, `templates/brands/brands_index.json` for identity-only presets):
+**Example library structure** (query the appropriate kind's index — `templates/layouts/layouts_index.json` for structure-only templates, `templates/decks/decks_index.json` for complete identity + structure templates, `templates/brands/brands_index.json` for identity-only presets):
```
templates/
@@ -457,8 +495,8 @@ templates/
│ ├── academic_defense/ # Academic-defense structure (no identity)
│ └── pixel_retro/ # Pixel retro / cyberpunk structure (no identity)
└── decks/
- ├── 招商银行/ # China Merchants Bank full PPT replica
- └── 中国电建/ # PowerChina full PPT replica
+ ├── <bank_deck>/ # Example banking deck
+ └── <engineering_deck>/ # Example engineering deck
```
---
@@ -474,8 +512,11 @@ templates/
- [x] Every page listed in `design_spec.md §V Page Roster` saved to `<template_workspace>/templates/`
- [x] Naming convention applied (standard / fidelity: letter-suffix variants; mirror: `<NNN>_<page_type>.svg`)
- [x] Templates follow design spec (colors, fonts, layout)
-- [x] Placeholder markers are clear and standardized; every slot has explicit design-zone bounds; mirror may keep literal text but still maps imported semantic slots
-- [x] Every SVG is a complete preview with explicit root Master/Layout identity, atomic Master/Layout elements, grouped slot/carrier metadata, and `native_structure_mode: structured`; source Layouts are materialized, or mirror reports unsupported Layouts explicitly
+- [x] `standard` / `fidelity` SVGs and Master/Layout contracts were newly authored; `mirror` SVGs restore the lossless source graph without semantic redesign
+- [x] Placeholder markers are clear and standardized for `standard` / `fidelity`; mirror preserves literal source text plus source placeholder type/index/bounds
+- [x] Every SVG is a complete preview with explicit root Master/Layout identity and `native_structure_mode: structured`; authored modes use canonical fixed layers/slots, while mirror preserves source ownership and mechanically expands fixed-layer groups into direct atoms
+- [x] Authored `standard` / `fidelity` Layout keys are non-duplicative; mirror keeps distinct source Layout identities even when their current visible contracts are equivalent
+- [x] Model context used lightweight projections; lossless imports remained authoritative for mirror restoration, while `standard` / `fidelity` used compact canonical authored metadata
- [x] Both scopes route bitmaps to `images/` and copy extracted icons to both `templates/icons/` and runtime `icons/`
-- [ ] **Next step**: Validate assets, export and verify `exports/<template_id>_template_preview.pptx`, then register only library scope
+- [ ] **Next step**: Validate assets, optionally export a review PPTX, then register only library scope
```
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 865e0c59..bdd219be 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -45,7 +45,7 @@ python3 scripts/update_repo.py
|------|-----------------|---------------|
| Conversion | `source_to_md.py`, `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py`, `pptx_to_svg.py` | [docs/conversion.md](./docs/conversion.md) |
| Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py` | [docs/project.md](./docs/project.md) |
-| SVG pipeline | `preset_shape_svg.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) |
+| SVG pipeline | `preset_shape_svg.py`, `svg_authoring_view.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) |
| PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) |
| PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) |
| Spec maintenance | `update_spec.py` | [docs/update_spec.md](./docs/update_spec.md) |
@@ -81,10 +81,23 @@ Template source import:
python3 scripts/pptx_template_import.py <template.pptx>
python3 scripts/pptx_template_import.py <template.pptx> --manifest-only
python3 scripts/pptx_template_import.py <template.pptx> --inheritance-mode both
+python3 scripts/svg_authoring_view.py <imported-svg-or-dir> -o <output-dir>
python3 scripts/template_preview_pptx.py <template_workspace>
+python3 scripts/template_preview_pptx.py <legacy_template_workspace> --visual-only
```
-`template_preview_pptx.py` reads a complete create-template workspace (`templates/`, `images/`, `icons/`, `exports/`), exports every `templates/*.svg` prototype as one structured review slide, and verifies the resulting Master/Layout package. Its default output is `exports/<template_id>_template_preview.pptx`. It refuses an existing output unless an intentional re-export passes `--force`. Legacy flat template packages remain readable; new template creation uses the workspace structure.
+`svg_authoring_view.py` creates a lightweight, non-destructive inspection copy
+of PPTX-imported SVGs. It removes embedded `txbody` / `text-carrier` payloads,
+duplicate hidden geometry carriers, and import-identity attributes from the
+copy while retaining visible fallback geometry, text, images, stable element
+ids, root Master/Layout markers, and supported compact native-shape intent.
+Relative local image references are rewritten so the projected copy still
+renders from its new location. The full imported SVG remains unchanged and is
+the evidence source for mirror restoration; the projection is inspection-only.
+The exporter never reads the import workspace or the projection. A projected
+view is not a final template or release export source.
+
+`template_preview_pptx.py` reads a template workspace, exports every `templates/*.svg` prototype as one structured review slide, and verifies the resulting Master/Layout package. This is an on-demand review action: its default output is `exports/<template_id>_template_preview.pptx`, and that directory need not exist before the command runs. It refuses an existing output unless an intentional re-export passes `--force`. `--visual-only` is an explicit migration aid for legacy SVG rosters: it creates a slide-local visual review deck without validating or claiming a reusable Master/Layout contract. New structured templates use the default mode when a review deck is requested.
Template fill (direct PPTX, no SVG conversion):
@@ -139,7 +152,7 @@ Native `svg_to_pptx.py` release export uses the project's `structured` lock. Eve
The exporter compiles only this declared structure, maps locked typography/colors into PowerPoint defaults, creates the named Master/Layout parts, and reads the package back before publication. It never clusters pages, promotes repeated chrome heuristically, or invents placeholders. Use `--pptx-structure flat` only for diagnostics.
-Template `page_layouts` records input provenance. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. Current `create-template` reconstructs source Master/Layout topology and flattens source structural groups into atoms; the original PPTX remains analysis input.
+Template `page_layouts` records input provenance. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. `standard` / `fidelity` author new SVGs and a new Master/Layout/slot contract. `mirror` restores the source identities and parentage without semantic synthesis, while mechanically expanding fixed-layer group wrappers into the direct atoms required by the structured contract.
Legacy `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, and missing root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before release export.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index afa042e5..85ba4a2e 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -6,6 +6,37 @@ These tools cover post-processing, SVG validation, speaker notes, recorded narra
The supported delivery contract has one PPTX path: `svg_output/` → the project SVG-to-DrawingML converter → native PPTX. The mandatory `finalize_svg.py` step separately creates self-contained `svg_final/` visual previews, which may be opened directly or inserted into PowerPoint as SVG pictures. There is no SVG-image PPTX output, and PowerPoint's manual Convert-to-Shape operation is unsupported.
+## `svg_authoring_view.py`
+
+Create a lightweight inspection/authoring projection of one PPTX-imported SVG
+or a directory of imported SVGs:
+
+```bash
+python3 scripts/svg_authoring_view.py <svg-file-or-directory> -o <output-dir>
+```
+
+The operation is non-destructive and refuses existing output files unless
+`--force` is explicit. It never writes back to the source SVG. The JSON report
+on stdout records original/projected byte counts and removals by category.
+
+The projected copy:
+
+- removes embedded `txbody` and `text-carrier` metadata;
+- removes hidden native geometry carriers while retaining and unwrapping their
+ visible preview geometry;
+- removes source-object identity/style/hash attributes that are only useful to
+ an exact import round trip;
+- keeps visible paths, text, images, stable ids, Master/Layout root markers,
+ and supported compact `data-pptx-object` / `data-pptx-prst` /
+ `data-pptx-frame` intent; and
+- rewrites relative local asset references for the projection's new location.
+
+The complete imported SVG remains the evidence source for mirror restoration.
+The exporter does not read the import workspace or the projection. The
+projection is deliberately not a template generator, not a replacement for
+the explicit Master/Layout restoration workflow, and not a supported release
+input to `svg_to_pptx.py`.
+
## Recommended Pipeline
Run these steps in order:
@@ -145,12 +176,19 @@ python3 scripts/svg_quality_checker.py examples/project
python3 scripts/svg_quality_checker.py examples/project --format ppt169
python3 scripts/svg_quality_checker.py --all examples
python3 scripts/svg_quality_checker.py examples/project --export
+python3 scripts/svg_quality_checker.py path/to/template/templates --template-mode
```
Checks include:
- `viewBox`
- banned elements
- line-break structure
+- explicit Master/Layout/slot structure for reusable templates
+- duplicate empty Layout contracts under different keys
+
+Template mode accepts compact canonical preset shapes marked with
+`data-pptx-authoring="preset"`. It validates the explicit structured SVG
+contract; it does not implement a separate source-payload opt-in marker.
## `svg_position_calculator.py`
diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.md
index 0f6eabaf..e6f91d9f 100644
--- a/skills/ppt-master/templates/README.md
+++ b/skills/ppt-master/templates/README.md
@@ -21,11 +21,11 @@ The `layouts/` directory contains pre-built page layout templates organized by d
- **Human browsing**: [layouts/README.md](./layouts/README.md)
- **Slim lookup (discovery only)**: [layouts/layouts_index.json](./layouts/layouts_index.json) — used to answer "what templates exist?". Step 3 triggers on an explicit directory path supplied by the user, not on names from this index.
-New layout/deck packages are complete workspaces. Whether created under this library or under `projects/`, they use the same `templates/`, `images/`, `icons/`, and `exports/<id>_template_preview.pptx` structure. Step 3 receives the workspace root. Existing flat library packages remain readable; flat placement alone does not imply legacy Master/Layout metadata.
+Every brand/layout/deck package uses one workspace routing contract. Whether created under this library or under `projects/`, source files live in `templates/`, bitmaps in `images/`, runtime icons in `icons/`, and on-demand review files in `exports/`. Empty optional directories are omitted, so a normal checked-in workspace has no `exports/`. Library `exports/` directories are Git-ignored, and Step 3 never copies them. Existing flat packages remain readable; flat placement alone does not imply legacy Master/Layout metadata.
## Brand Identity Presets
-The `brands/` directory holds brand-only templates: identity bundles (color / typography / logo / voice / icon style) without an SVG page roster. Brands follow the **same explicit-path trigger rule as layout templates** — at SKILL.md Step 3 the user supplies the brand directory path to apply it; bare brand names never trigger. Both layout and brand inputs land in the same project directory (`<project_path>/templates/`). When supplied together, Step 3 fuses them into a single `design_spec.md` (brand wins on identity tokens, layout wins on page structure) — see `SKILL.md` Step 3 for the precedence table.
+The `brands/` directory holds brand-only templates: identity bundles (color / typography / logo / voice / icon style) without an SVG page roster. Brands follow the **same explicit-path trigger and workspace routing as layout templates** — at SKILL.md Step 3 the user supplies the workspace root; bare brand names never trigger. `templates/`, `images/`, and `icons/` map to their matching project peers. When supplied together, Step 3 fuses them into one `design_spec.md` (brand wins on identity tokens, layout wins on page structure) — see `SKILL.md` Step 3 for the precedence table.
A brand is structurally a layout template minus its page roster. Use a brand when the user wants identity locking with free page layout; use a layout template when fixed page structures are also required.
diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.md
index bdb37f28..ec696647 100644
--- a/skills/ppt-master/templates/brands/README.md
+++ b/skills/ppt-master/templates/brands/README.md
@@ -2,7 +2,7 @@
This directory holds **brand-only templates**: identity bundles (color / typography / logo / voice / icon style) without an SVG page roster. Strategist locks the brand's identity segment as truth; Executor designs pages freely under those constraints.
-Brand is one of three template kinds in the library — alongside [`layouts/`](../layouts/) (structure-only) and [`decks/`](../decks/) (full-PPT replica). Full data model: [`docs/zh/templates-architecture.md`](../../../../docs/zh/templates-architecture.md).
+Brand is one of three template kinds in the library — alongside [`layouts/`](../layouts/) (structure-only) and [`decks/`](../decks/) (complete identity + structure). Full data model: [`docs/zh/templates-architecture.md`](../../../../docs/zh/templates-architecture.md).
## How brands are consumed
@@ -10,7 +10,7 @@ Brand application follows the **same explicit-path rule and workspace routing as
| User input at SKILL.md Step 3 | Behavior |
|---|---|
-| An explicit brand workspace path (e.g. `templates/brands/anthropic/`) | Resolve `templates/design_spec.md`; stage `templates/`, `images/`, and `icons/` into the matching project directories; Strategist locks the identity segment |
+| An explicit brand workspace path (e.g. `templates/brands/anthropic/`) | Resolve `templates/design_spec.md`; stage `templates/` plus any existing `images/` and `icons/` into the matching project directories; Strategist locks the identity segment |
| Bare brand name only ("use anthropic brand"), brand mention without path, or silence | Skip — same mechanical rule as all template kinds: bare names never trigger |
| Brand path + layout path | Fuse into one `design_spec.md` — brand owns identity segment (color / typography / logo / voice / icon style); layout owns structure segment (canvas / page roster). See `SKILL.md` Step 3. |
| Brand path + deck path | Fuse — brand identity overrides deck identity; structure + middle segments come from deck |
@@ -41,7 +41,7 @@ templates/brands/<brand_id>/
│ ├── logo.<ext> # optional — primary logo
│ └── <brand>_wordmark.svg # optional — alternate lockups and visual assets
├── icons/ # optional — branded icon overrides
-└── exports/ # optional local derived artifacts; Git-ignored
+└── exports/ # normally absent; real local derived artifacts only; Git-ignored
```
Logo filenames are descriptive, not contractual — `templates/design_spec.md` §IV lists exact `../images/...` paths and usage contexts. Single-lockup brands typically ship one logo; dual-lockup brands ship separately named files.
diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.md
index 0bf2043c..83f369f2 100644
--- a/skills/ppt-master/templates/decks/README.md
+++ b/skills/ppt-master/templates/decks/README.md
@@ -1,6 +1,6 @@
# Deck Templates
-**Deck = full-PPT replica.** Each deck reverse-engineers a specific organization's branded presentation and bundles its **identity + structure + middle** segments into one atomic asset. Use a deck when you want the complete look of a particular institution (color, typography, logo, page structure, voice) preserved as a whole.
+**Deck = full identity + structure reference.** Each deck reverse-engineers a specific organization's branded presentation and bundles its **identity + structure + middle** segments into one atomic asset. Use a deck when you want the complete look of a particular institution (color, typography, logo, page structure, voice) preserved as a coherent authored system.
Single source of truth for what decks exist: [`decks_index.json`](./decks_index.json) (`deck_id → { summary, canvas_format, page_count, primary_color }`). This README explains the kind; it does **not** enumerate decks.
@@ -56,7 +56,7 @@ When the user gives a deck path **with** a brand path or layout path, identity /
## Standard workspace contract
-New deck creation uses the same complete workspace shape in both output scopes:
+New deck creation uses the same portable workspace routing in both output scopes:
```text
<template_workspace>/
@@ -66,9 +66,9 @@ New deck creation uses the same complete workspace shape in both output scopes:
│ ├── 02_chapter.svg
│ ├── 03_content.svg
│ └── 04_ending.svg
-├── images/
-├── icons/
-└── exports/
+├── images/ # Optional; omit when unused
+├── icons/ # Optional; omit when unused
+└── exports/ # Optional, on-demand review output; Git-ignored
└── <deck_id>_template_preview.pptx
```
@@ -77,7 +77,9 @@ New deck creation uses the same complete workspace shape in both output scopes:
| Library | `skills/ppt-master/templates/decks/<deck_id>/` | Register in `decks_index.json` |
| Project | `projects/<project_name>/` | Do not register globally |
-Bitmaps belong in `images/`; extracted runtime icons belong in `icons/`; template sources and any validation icon copy belong in `templates/`. The preview PPTX is a required review artifact, not a template input. Template application consumes `templates/`, `images/`, and `icons/` from the explicit workspace root and does not copy `exports/`.
+Bitmaps belong in `images/`; extracted runtime icons belong in `icons/`; template sources and any validation icon copy belong in `templates/`. Omit empty optional directories instead of adding placeholder files. Generate a preview PPTX only when local PowerPoint review is requested; it is derived output, library `exports/` is Git-ignored, and template application never copies it.
+
+`standard` and `fidelity` author new SVG documents and a new Master/Layout/slot contract. `mirror` restores the source roster, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`; this normalization must preserve ownership, paint order, and appearance.
**Legacy compatibility**: Existing flat packages with `design_spec.md` and SVGs at their root remain readable. Flat placement alone does not trigger [`restore-pptx-structure`](../../workflows/restore-pptx-structure.md); restoration is required only when SVG Master/Layout/slot metadata is absent or legacy. New `create-template` outputs always use the workspace contract above.
@@ -88,7 +90,7 @@ Bitmaps belong in `images/`; extracted runtime icons belong in `icons/`; templat
1. Run [`workflows/create-template.md`](../../workflows/create-template.md) (default kind is `deck`)
2. Choose the workspace root: library `skills/ppt-master/templates/decks/<id>/` or project `projects/<name>/`
3. Validate: `python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/templates" --template-mode --format ppt169`
-4. Export the review deck: `python3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>"`
+4. Optional — when PowerPoint review is requested, export the review deck: `python3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>"`
5. For library scope only, register: `python3 skills/ppt-master/scripts/register_template.py <id> --kind deck`
The register step updates [`decks_index.json`](./decks_index.json) — the single source of truth for deck discovery.
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index 7681f6b9..6471286c 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -45,7 +45,7 @@ Layouts may include additional supporting sections (Layout Patterns, Spacing Gui
## Standard workspace contract
-New layout creation uses the same complete workspace shape in both output scopes:
+New layout creation uses the same portable workspace routing in both output scopes:
```text
<template_workspace>/
@@ -55,9 +55,9 @@ New layout creation uses the same complete workspace shape in both output scopes
│ ├── 02_chapter.svg
│ ├── 03_content.svg
│ └── 04_ending.svg
-├── images/
-├── icons/
-└── exports/
+├── images/ # Optional; omit when unused
+├── icons/ # Optional; omit when unused
+└── exports/ # Optional, on-demand review output; Git-ignored
└── <layout_id>_template_preview.pptx
```
@@ -68,7 +68,9 @@ New layout creation uses the same complete workspace shape in both output scopes
`02_toc.svg` and other roster variants remain optional. All SVGs use `viewBox="0 0 1280 720"` for ppt169. Bitmaps belong in `images/`; extracted runtime icons belong in `icons/`; template sources and any validation icon copy belong in `templates/`.
-The preview PPTX is a required review artifact and is not a template input. Template application consumes the workspace root's `templates/`, `images/`, and `icons/`; it does not copy `exports/`.
+Omit empty optional directories instead of adding placeholder files. Generate a preview PPTX only when local PowerPoint review is requested; it is derived output, library `exports/` is Git-ignored, and template application never copies it.
+
+`standard` and `fidelity` author new SVG documents and a new Master/Layout/slot contract. `mirror` restores the source roster, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`; this normalization must preserve ownership, paint order, and appearance.
**Legacy compatibility**: Existing flat packages with `design_spec.md` and SVGs at their root remain readable. Flat placement alone does not trigger [`restore-pptx-structure`](../../workflows/restore-pptx-structure.md); restoration is required only when SVG Master/Layout/slot metadata is absent or legacy. New `create-template` outputs always use the workspace contract above.
@@ -85,7 +87,7 @@ Templates use `{{PLACEHOLDER}}` to mark replaceable content. New layouts should
1. Run [`workflows/create-template.md`](../../workflows/create-template.md) (default produces a deck; explicit "structure only / no identity" option produces a layout)
2. Choose the workspace root: library `skills/ppt-master/templates/layouts/<id>/` or project `projects/<name>/`
3. Validate: `python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/templates" --template-mode --format ppt169`
-4. Export the review deck: `python3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>"`
+4. Optional — when PowerPoint review is requested, export the review deck: `python3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>"`
5. For library scope only, register: `python3 skills/ppt-master/scripts/register_template.py <id> --kind layout`
The register step updates [`layouts_index.json`](./layouts_index.json) — the single source of truth for layout discovery.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 1437eeda..b97213ef 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -10,11 +10,11 @@ Generate one complete layout/deck template workspace under either the **global t
**Default — library scope**: Write `skills/ppt-master/templates/<kind>/<id>/` and register it in the matching discovery index.
-**Project scope**: Write the same complete workspace contract at `<project>/` and do not register any global index.
+**Project scope**: Write the same portable workspace routing at `<project>/` and do not register any global index.
-**Hard rule — one workspace shape**: Output scope changes only the workspace parent and index registration. Both scopes use the same `templates/`, `images/`, `icons/`, and `exports/` placement, the same relative asset references, the same validation command, and the same preview-export command. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.
+**Hard rule — one workspace routing contract**: Output scope changes only the workspace parent and index registration. Both scopes use required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/`, with the same relative asset references and validation command. Never add placeholder files only to retain an empty directory. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.
-> **Boundary against template-fill**: this workflow does not fill content into a PPTX and does not directly output the user's final generated deck. It creates a reusable template contract plus a review-only PPTX at the selected scope. To generate a deck from the workspace, return its root path to the main SKILL.md pipeline. A project-scoped workspace is already installed at that project's Step 3 path and is consumed in place.
+> **Boundary against template-fill**: this workflow does not fill content into a PPTX and does not directly output the user's final generated deck. It creates a reusable template contract; an optional PPTX may be generated later for local review. To generate a deck from the workspace, return its root path to the main SKILL.md pipeline. A project-scoped workspace is already installed at that project's Step 3 path and is consumed in place.
> **Companion workflow**: identity-only locking (colors / typography / logo / voice without SVG pages) is handled by [`create-brand.md`](./create-brand.md). Use that when the user wants brand identity but free page layout; use this when fixed page structures are required.
@@ -43,25 +43,25 @@ Both scopes write this contract:
```text
<template_workspace>/
├── templates/ # design_spec.md, template SVGs, templates/icons/ when used
-├── images/ # every bitmap; SVG href is always ../images/<name>
-├── icons/ # runtime copy of extracted vector assets
-└── exports/ # <template_id>_template_preview.pptx
+├── images/ # optional; every bitmap; SVG href is ../images/<name>
+├── icons/ # optional; runtime copy of extracted vector assets
+└── exports/ # optional; on-demand <template_id>_template_preview.pptx
```
-The review PPTX is derived evidence, not a source template asset. Template application reads `templates/`, `images/`, and `icons/`; it never copies or consumes `exports/`.
+The review PPTX is derived evidence, not a source template asset. Do not create `exports/` unless a review deck is requested. Template application reads `templates/` plus any existing `images/` and `icons/`; it never copies or consumes `exports/`. Library `exports/` directories are Git-ignored.
For `project`, `target_project` is required and must be an existing project initialized by `project_manager.py init`. Before the first final-output write, run one complete preflight. Apply the same collision checks to a library workspace; the only difference is that its root is under the global kind directory:
-1. Resolve `<template_workspace>` from the confirmed scope and confirm its `templates/`, `images/`, `icons/`, and `exports/` destinations.
+1. Resolve `<template_workspace>` from the confirmed scope and confirm its required `templates/` destination plus any needed `images/` / `icons/` destinations.
2. Confirm `<template_workspace>/templates/` is empty.
-3. Resolve every final bitmap, extracted-icon, and review-PPTX filename, then confirm none would overwrite an existing file in `images/`, `icons/`, `templates/icons/`, or `exports/`.
+3. Resolve every final bitmap and extracted-icon filename, then confirm none would overwrite an existing file in `images/`, `icons/`, or `templates/icons/`. Check the review-PPTX destination only when preview export was requested.
Any failed check aborts before writing `design_spec.md`, SVGs, images, icons, or the review PPTX. Do not merge into a non-empty template source and do not overwrite a name conflict. Temporary Step 1 analysis workspaces remain allowed because they are not final outputs.
## Process Overview
```
-Reference Intake & Analysis -> Basic Norm Extraction -> Fact-Based Brief Proposal -> User Confirmation Gate -> Preflight + Invoke Template_Designer -> Validate Assets -> Export Review PPTX -> [Register Library Index] -> Output
+Reference Intake & Analysis -> Basic Norm Extraction -> Fact-Based Brief Proposal -> User Confirmation Gate -> Preflight + Invoke Template_Designer -> Validate Assets -> [Optional Review PPTX] -> [Register Library Index] -> Output
```
The first three steps derive the brief from facts, not guesses. **No final template directory may be created and no template SVG / `design_spec.md` may be written until `[TEMPLATE_BRIEF_CONFIRMED]` is emitted in Step 3.** Reference-analysis intermediates produced by `pptx_template_import.py` (typically under `/tmp/pptx_template_import/`) are explicitly **not** subject to this gate — they are temporary workspaces feeding Step 2.
@@ -77,22 +77,22 @@ 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` |
-| **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 SVG source directory, then `ls` + `Read` each `*.svg`; also read companion `design_spec.md` / `spec_lock.md` when present | `standard` / `fidelity` (explicit structure first; visual clustering only when unstructured) / `mirror` (direct 1:1 copy) |
+| **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 a lightweight projection with `svg_authoring_view.py`, then read projected 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 path: `manifest.json` page-type candidates and the layered `svg/` workspace anchor cluster detection (fidelity) and verbatim copy (mirror) with factual data.
+`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.
**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.
Type B is supported with caveats:
-- **mirror on type B** — direct 1:1 copy. B's SVGs are already self-contained (one file per page, equivalent to `svg-flat/slide_*.svg`). Page-type for the `<NNN>_<page_type>.svg` filename is read from the source filename when it follows the PPT Master naming convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); fall back to `content` otherwise. Particularly natural when the source is a current or legacy template workspace and the user wants to fork it.
-- **fidelity on type B** — inspect root Master/Layout identities, direct atomic Master/Layout elements, top-level slot groups, and companion `spec_lock.md` first. When a complete current contract exists, its Master roster and `pptx_layouts` families are authoritative; preserve them instead of visual re-clustering. If the input is an existing template, use its metadata and variant filenames.
+- **mirror on type B** — require a complete explicit source contract. Preserve page count/order, literal visuals, root Master/Layout identities, slot metadata, supported native-object metadata, and source ownership. Page type for `<NNN>_<page_type>.svg` is read from the source filename when it follows the PPT Master naming convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); fall back to `content` otherwise. A loose visual-only SVG folder has no native structure to restore and cannot use mirror.
+- **fidelity on type B** — inspect the complete page roster as visual reference, then design a broader new roster and its own Master/Layout/slot system. Existing keys, families, and repeated source chrome are not output-topology inputs.
- **legacy or unstructured type B** — old `baseline` / `preserve` / `layout_strategy: distill` / `data-pptx-layout-kind` / direct-atomic-placeholder inputs, and SVGs with no root Master identity, first run [`restore-pptx-structure`](./restore-pptx-structure.md). The restored contract is then the Type B input. Do not keep a second compatibility branch inside template creation.
- **selected free-design subset on type B** — restore the named source pages into the current structured contract, then ingest only that explicit subset. Do not scan or copy the whole `svg_output/` directory and silently turn unselected pages into template variants.
-**Replication mode boundary**: `standard` / `fidelity` / `mirror` are construction choices for this workflow only. They decide how the template package is created from the reference source; they do not create a downstream generation route, and `mirror` must not force future decks to preserve the source page count or page order.
+**Replication mode boundary**: `standard` and `fidelity` are authored modes: source visuals/assets guide a new SVG roster and a newly designed Master/Layout/slot system, without preserving or distilling source topology. `mirror` is a restoration mode: source page order, visuals, Master/Layout graph, placeholders, ownership, and supported native-object metadata are authoritative. Mirror may mechanically normalize the transport representation for the current compiler, including fixed-layer group expansion, but it never performs semantic synthesis. The modes do not create a downstream generation route, and a completed mirror workspace does not force future decks to preserve the source page count or page order.
### 1A. `.pptx` reference
@@ -126,44 +126,60 @@ Import fidelity rules:
It is a reconstruction aid, not a final direct template conversion.
+**Lossless source + lightweight authoring view**:
+
+Keep `<import_workspace>/svg/` and `<import_workspace>/svg-flat/` unchanged as the lossless import evidence. Before the Template_Designer reads any imported page SVG, create non-destructive model-facing projections:
+
+```bash
+python3 skills/ppt-master/scripts/svg_authoring_view.py "<import_workspace>/svg" -o "<import_workspace>/authoring-svg"
+python3 skills/ppt-master/scripts/svg_authoring_view.py "<import_workspace>/svg-flat" -o "<import_workspace>/authoring-svg-flat"
+```
+
+The projection removes opaque text payload, duplicate hidden geometry carriers, and import-only identity attributes while keeping visible shape intent, compact preset/frame metadata, structure markers, logical ids, and valid asset references. It is an inspection surface only. Never export it as a finished template and never overwrite the lossless source.
+
**Vector illustration readability pass**:
-Before the Template_Designer reads imported SVGs, factor large decorative vector groups into project icon assets so the working SVGs stay readable while export remains native shapes. Run this on the SVG view that will feed the selected replication path:
+Factor large decorative vector groups out of the lightweight projections so the model-facing SVGs stay readable while export remains native shapes. Never run this in place on the lossless import SVGs:
```bash
# standard / fidelity analysis path
-python3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/svg" --icons-dir "<import_workspace>/icons" --inplace --id-prefix layered --min-decoration-bytes 3000 --clean-stale
+python3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authoring-svg" --icons-dir "<import_workspace>/icons" --inplace --id-prefix layered --min-decoration-bytes 3000 --clean-stale
-# mirror visual-copy path; also run the layered command above because Master/Layout
-# ownership remains required for the rebuilt explicit structure
-python3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/svg-flat" --icons-dir "<import_workspace>/icons" --inplace --id-prefix flat --min-decoration-bytes 3000 --clean-stale
+# mirror inspection path; the lossless layered/flat sources remain authoritative
+python3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authoring-svg-flat" --icons-dir "<import_workspace>/icons" --inplace --id-prefix flat --min-decoration-bytes 3000 --clean-stale
```
-The source SVGs in `<import_workspace>/svg/` / `<import_workspace>/svg-flat/` are rewritten in place with compact `<use data-icon="..."/>` placeholders. Extracted assets live directly under `<import_workspace>/icons/`; `icons/` must contain only icon/vector assets, not rewritten page SVGs or inventories. The inventory is written beside the processed SVG directory (for example `<import_workspace>/svg_vector_asset_inventory.json`). 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 directory, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.
+The projected SVGs in `<import_workspace>/authoring-svg/` / `<import_workspace>/authoring-svg-flat/` are rewritten in place with compact `<use data-icon="..."/>` placeholders. Extracted assets live directly under `<import_workspace>/icons/`; `icons/` must contain only icon/vector assets, not rewritten page SVGs or inventories. The inventory is written beside the processed projection directory. 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 directory, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.
-**Read order during analysis** (read everything below before composing Step 2):
+**Read order during analysis**:
+
+| Mode | Required read set |
+|---|---|
+| `standard` | `manifest.json`, exported assets, and enough cleaned `authoring-svg-flat/slide_NN.svg` pages to ground the confirmed visual direction. Source Master/Layout files are not needed for output design. |
+| `fidelity` | `manifest.json`, exported assets, and every cleaned `authoring-svg-flat/slide_NN.svg` page so the newly designed roster covers the useful visual range. Source topology remains non-binding. |
+| `mirror` | `manifest.json`, `native_structure.json`, `svg/inheritance.json`, every cleaned layered Master/Layout/Slide projection, and every cleaned flat slide projection. Verify the projection against the lossless file inventory; restoration itself reads the matching lossless files by identity rather than placing their opaque payload in model context. |
-1. `manifest.json` (factual metadata: slide size, theme, assets, layouts, masters, slide page-types)
-2. `native_structure.json` (stable native keys, source layout names/placeholders, relationship completeness, recommended structure strategy)
-3. cleaned `svg/master_*.svg` and `svg/layout_*.svg` — read these **before** any slide SVG; they show the deck's shared visual language (background, headers, footers, decorative bars). This is what the new template's fixed structure should adapt from.
-4. `svg/inheritance.json` — confirms which slide uses which layout/master
-5. exported `assets/`
-6. cleaned slide SVG references from `svg/` — content unique to each slide; consult after the master/layout language is understood
-7. `summary.md` only as a quick orientation aid
-8. user-provided screenshots or the original PPTX only for visual cross-checking
+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.
Interpretation rule (carries forward into Steps 2 and 4):
-- `manifest.json` is the source of truth for slide size, theme colors, fonts, background inheritance, reusable asset inventory, unique layout/master structure, and slide reuse relationships
-- `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. Use those facts to rebuild the explicit SVG contract; never retain the source package as the new template architecture.
+- `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
- exported `assets/` are the canonical reusable image pool — `<image>` references in `svg/` already point at these files directly
- exported `icons/*.svg` 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 icon 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 `svg/master_*.svg` / `svg/layout_*.svg` are the **primary source for fixed structural design** — recurring backgrounds, page chrome, decorative motifs that the template should preserve. The new template's `01_cover` / `02_chapter` / `03_content` / `04_ending` typically inherit elements from these layers.
-- cleaned `svg/slide_NN.svg` shows page-specific content — useful for judging composition rhythm and content density, not for fixed structure. Read every slide regardless of count.
-- cleaned `svg-flat/slide_NN.svg` is for human preview and screenshot comparison; do not treat duplicated master/layout chrome inside flat slides as separate reusable template structure.
+- cleaned layered projections are mirror verification views; they expose source ownership without requiring the model to read opaque payload. Do not use them to promote, demote, merge, or split source structure.
+- cleaned complete-page projections are visual references for authored modes and verification views for mirror. They are never the lossless restoration source.
- screenshots remain useful for judging composition and style, but should not override extracted factual metadata unless the import result is clearly incomplete
+**Mirror reachability gate**: compare every `native_structure.json.layouts[*].usedBySlides`
+entry with the source Master roster before offering `mirror`. The current
+structured template compiler materializes only identities referenced by emitted
+SVG prototypes. If any source Layout is unused, or any source Master is not
+reachable through a referenced Layout, full-graph mirror is currently
+unsupported. Report the exact keys and stop; do not silently omit them or create
+a synthetic carrier page.
+
### Basic norm extraction (mandatory when reference content exists)
Before composing Step 2, extract the template's reusable norms from the previous content. These norms are not generic design advice; they are the source deck's observable operating rules, and they must flow into `design_spec.md`.
@@ -177,28 +193,30 @@ Before composing Step 2, extract the template's reusable norms from the previous
| Density rhythm | title scale, content block count, whitespace balance, dense vs. breathing pages | Page-type guidance for Strategist / Executor |
| Page roster semantics | cover / TOC / chapter / content / ending variants and their intended content slots | `design_spec.md §V Page Roster` rows |
| Asset policy | source images / icons / textures that are part of the template vs. sample-only content | `design_spec.md §VI Assets` or omit sample-only assets |
-| Native PowerPoint structure | `native_structure.json` source facts, masters/layouts, picker names, placeholder type/index, source slide mapping | Reconstruct the source Master roster and Layout graph in complete, explicitly annotated SVG pages; flatten source groups into atomic Master/Layout objects. |
+| Native PowerPoint structure | `native_structure.json` plus inheritance facts | Mirror restores the source graph one-to-one. Standard/fidelity author an independent output graph and do not distill source common structure. |
Distinguish observed facts from template rules: "`slide_07` uses a left photo crop" is a fact; "content pages may use a left photo rail for location / product / case-study pages" is the reusable rule.
-**Hard read gate** (all replication modes):
+**Read gate**:
-- The agent MUST finish reading every cleaned `master_*.svg`, `layout_*.svg`, and `slide_*.svg` file from the layered `svg/` view before moving on to Step 2
-- The agent MUST list the read master / layout / slide filenames inside the Step 2 brief proposal as proof of the gate
+- `standard`: report the projected reference pages inspected
+- `fidelity`: read and report every projected complete-page SVG
+- `mirror`: verify and report every projected Master, Layout, and Slide plus the inheritance map, while keeping opaque payload out of model context
-Do **not** treat the imported PPTX or exported slide SVGs as direct final template assets — Step 4 reconstructs them as a clean, maintainable PPT Master template package, not a 1:1 shape translation.
+Do not treat lightweight projections as final template assets. `standard` / `fidelity` author new SVGs. Mirror restores from the lossless import and uses projections only for inspection.
-> **Mirror-mode visual path** — when the user selects mirror replication, use cleaned `svg-flat/slide_*.svg` for literal page appearance, but still read cleaned `svg/master_*.svg`, `svg/layout_*.svg`, and `svg/inheritance.json` to recover layer ownership. Mirror preserves page visuals; it does not bypass the explicit Master/Layout reconstruction contract.
+> **Mirror-mode restoration path** — use lossless layered SVGs, flat SVGs, `native_structure.json`, and `svg/inheritance.json` as authority. The cleaned projections are the literal inspection target, not a replacement data source. Preserve roster, appearance, ownership, placeholders, converter-supported native metadata, and available SVG fallbacks; do not synthesize a different graph.
### 1B. Existing SVG assets
-First resolve the Type B source directory using the rule above. If that normalized SVG directory contains complex vector blobs, copy the SVG files into a throwaway analysis workspace and run the same readability pass there. Do **not** rewrite the user's original source directory in place.
+First resolve the Type B source directory using the rule above. Create a non-destructive authoring projection in a throwaway analysis workspace, then run the same vector readability pass only on that projection. Do **not** rewrite the user's original source directory in place.
```bash
-python3 skills/ppt-master/scripts/extract_svg_assets.py "<svg_analysis_workspace>/svg" --icons-dir "<svg_analysis_workspace>/icons" --inplace --id-prefix source --min-decoration-bytes 3000 --clean-stale
+python3 skills/ppt-master/scripts/svg_authoring_view.py "<normalized_svg_source>" -o "<svg_analysis_workspace>/authoring-svg"
+python3 skills/ppt-master/scripts/extract_svg_assets.py "<svg_analysis_workspace>/authoring-svg" --icons-dir "<svg_analysis_workspace>/icons" --inplace --id-prefix source --min-decoration-bytes 3000 --clean-stale
```
-Then `ls` the analysis workspace and `Read` every cleaned `*.svg` to extract:
+Then `ls` the analysis workspace and `Read` every cleaned `authoring-svg/*.svg` to extract:
- canvas size (`viewBox` on the root `<svg>`)
- recurring colors (`fill` / `stroke` values; identify the dominant 2–4 hex codes as candidate theme colors)
@@ -208,7 +226,7 @@ Then `ls` the analysis workspace and `Read` every cleaned `*.svg` to extract:
Read the generated `*_vector_asset_inventory.json` before opening individual `<svg_analysis_workspace>/icons/*.svg`; do not bulk-read extracted icons unless a specific asset affects a design decision or is selected for mirror preservation.
-If a `design_spec.md` or `spec_lock.md` accompanies the SVGs, `Read` it too — it is a higher-confidence source than re-deriving from the SVG alone. Record the equivalent of a `manifest.json`'s factual fields in your own analysis notes (no actual file written) so Step 2 can label them `[fact]`.
+If a `design_spec.md` or `spec_lock.md` accompanies the SVGs, read it too. In mirror it is part of the source contract and must agree with the SVG identities; in `standard` / `fidelity` it is visual/contextual reference only. Record the equivalent of a `manifest.json`'s factual fields in analysis notes so Step 2 can label them `[fact]`.
### 1C. Image / visual references
@@ -235,20 +253,20 @@ Compose a single message that surfaces every Required brief item to the user, **
- **`[suggested]`** — AI-inferred from analysis or context (e.g. tone summary, applicable scenarios; visually estimated values from type C)
- **`[decision]`** — pure user choice, no analysis substitute (e.g. `template_id`, `replication mode`, `category`)
-**Language adaptation rule**: write the Step 2 brief in the user's language. For technical enum values, show the localized label first and keep the English ID in parentheses only when needed for precision, e.g. `完整套版(deck)`, `结构版式(layout)`, `逐页采样(mirror)`. Do not assume users know what each English word means.
+**Language adaptation rule**: write the Step 2 brief in the user's language. For technical enum values, show the localized label first and keep the English ID in parentheses only when needed for precision, for example `<localized deck label> (deck)`, `<localized layout label> (layout)`, or `<localized mirror label> (mirror)`. Do not assume users know what each English word means.
**Option visibility rule**: for every field with a finite option set, show both the recommended value and the other valid options. Do not present a single recommended value as if no alternatives exist. If an option is unavailable for the current input type, list it under `Unavailable` with the reason.
| Field | Must show |
|---|---|
-| Output scope | Recommended `library` (default) plus `project`; explain that both create the same complete workspace and only the parent path / global registration differ |
+| Output scope | Recommended `library` (default) plus `project`; explain that both use the same portable workspace routing and only the parent path / global registration differ |
| Target project | Required only for `project`; show the exact initialized project workspace path, not a project nickname |
| Template kind | Recommended localized label with English ID, plus both options and the rule for choosing |
| Category | Recommended localized category with English ID, plus `brand` / `general` / `scenario` / `government` / `special` with localized explanations |
| Theme mode | Recommended localized mode with English ID, plus available modes such as `light` / `dark` / `mixed` with localized explanations |
| Canvas format | Recommended canvas, plus other supported formats from [`canvas-formats.md`](../references/canvas-formats.md) that fit the source aspect ratio or user intent. Always show the concrete pixel size and `viewBox`; do not treat two same-ratio formats such as `ppt169` (`1280x720`) and `banner` (`1920x1080`) as interchangeable. |
-| Replication mode | Recommended localized mode with English ID, plus all modes available for the current input type; list forbidden modes for type C / D as unavailable with localized reasons |
-| Native structure reconstruction | For type A, summarize the source master/layout graph from `native_structure.json`, then state the fixed output policy: reconstruct every retained source Master/Layout identity through the current structured SVG contract. The source package is analysis input only. |
+| Replication mode | Recommended localized mode with English ID, plus all modes available for the current input type; state that `standard` / `fidelity` design a new structure while `mirror` restores the source structure; list unavailable modes with reasons |
+| Native structure policy | For `standard` / `fidelity`, state that the designer will author a new Master/Layout/slot system without preserving or distilling source topology. For `mirror`, summarize the exact source Master/Layout/placeholder graph that will be restored one-to-one. |
| Visual fidelity for fixed pages | Recommended localized choice with English ID, plus both `literal` / `adapted` options when applicable |
| Asset bundling | Recommended included assets, plus excluded candidate assets with a one-line reason when reference assets exist |
@@ -256,7 +274,7 @@ Items to surface:
| Item | Required | Provenance by input type |
|------|----------|--------------------------|
-| Output scope | Yes | `[decision]` — `library` (default, globally reusable and indexed) or `project` (same complete workspace under one initialized project) |
+| 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) |
@@ -265,9 +283,10 @@ Items to surface:
| Tone summary | Yes | `[suggested]` from analysis (e.g. `Modern, restrained, data-driven`) |
| Theme mode | Yes | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[decision]` |
| Canvas format and dimensions | Yes | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`) |
-| Replication mode | Yes | `[decision]` — `standard` always available; `fidelity` and `mirror` available for type A (canonical, manifest-anchored) and type B (explicit-structure grouping or unstructured visual clustering / direct 1:1 copy — see Step 1 caveats); reject `fidelity` / `mirror` upfront for type C / D |
-| Native structure facts | Type A only | `[fact]` from `native_structure.json.strategy`: master/layout counts, source placeholder identities, multi-master status, and reason codes. Output remains rebuilt explicit SVG structure (`template`) for every replication mode. |
-| Visual fidelity for fixed pages | Yes for `standard` / `fidelity` when reference exists; **N/A for `mirror`** (mirror is implicitly literal) | `[decision]` — `literal` (preserve original geometry / decoration / sprite crops as-is; for cover / chapter / ending especially) or `adapted` (use the reference for tone/structure but allow design evolution). Different page types may take different settings |
+| Replication mode | Yes | `[decision]` — `standard` always available; `fidelity` is available for A/B; `mirror` is available for A only when every source Master/Layout is reachable from a source slide, and only for B sources with a complete explicit structure contract whose declared identities are all page-referenced. `standard` / `fidelity` author new SVG semantics, while mirror retains one restored prototype per source slide in source order. Reject `fidelity` / `mirror` for C/D. |
+| Native structure facts | Type A and structured Type B | `[fact]` from `native_structure.json` / source SVG contract: master/layout counts, parentage, page assignments, placeholder identities, and multi-master status. Mirror restores these facts; authored modes do not use them as output topology. |
+| Mode-specific ownership | Yes | `standard` / `fidelity`: `[decision]` newly authored Master/Layout ownership. `mirror`: `[fact]` source ownership restored without synthesis. Export never infers either contract. |
+| Visual fidelity for fixed pages | Yes for `standard` / `fidelity` when reference exists; **N/A for `mirror`** (mirror restores the source visual) | `[decision]` — `literal` (closely reproduce reference geometry / decoration / sprite crops within a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Different page types may take different settings. |
| Basic template norms | Yes when reference exists | `[fact]` / `[suggested]` — layout grammar, image system, density rhythm, page roster semantics, and asset policy extracted in Step 1 |
| Reference source | Optional | already known if Step 1 ran |
| Theme color | Optional | A: `[fact]` from theme XML. B: `[fact]` from dominant SVG `fill`. C: `[suggested]` from visual estimate (HEX is approximate). D: `[decision]` |
@@ -278,9 +297,9 @@ Items to surface:
For type A, also include in this message:
-- the exact cleaned `master_*.svg`, `layout_*.svg`, `slide_*.svg` filenames you read from the layered `svg/` view (proof of the hard read gate)
-- a one-line summary of the master / layout structure you extracted
-- the source structure facts, including master/layout counts, multi-master status, and reason codes; state that the final package will reconstruct that topology through atomic Master/Layout objects and grouped slots
+- the exact projected files required by the selected mode and verified during Step 1
+- a one-line summary of the source Master/Layout structure
+- the source structure facts, including master/layout counts, multi-master status, and reason codes; state whether they will be restored (`mirror`) or ignored as output topology (`standard` / `fidelity`)
The user replies with corrections, additions, or "all good".
@@ -295,7 +314,7 @@ The user replies with corrections, additions, or "all good".
1. Echo back the finalized brief (post-corrections) in a single message
2. Emit the marker `[TEMPLATE_BRIEF_CONFIRMED]` on its own line
-Skipping this gate — including silently inferring values from the reference source, opened IDE file, or prior conversation — is a workflow violation. Even if the user said "用这个 .pptx 做模板" upfront, you MUST still surface Step 2 with provenance labels and obtain explicit confirmation here. The reference source informs the brief; it does not substitute for it.
+Skipping this gate — including silently inferring values from the reference source, opened IDE file, or prior conversation — is a workflow violation. Even if the user said "use this .pptx as a template" upfront, you MUST still surface Step 2 with provenance labels and obtain explicit confirmation here. The reference source informs the brief; it does not substitute for it.
**Required outcome of Step 3** (all must be true before emitting `[TEMPLATE_BRIEF_CONFIRMED]`):
@@ -305,8 +324,10 @@ Skipping this gate — including silently inferring values from the reference so
- [ ] User has replied with values or explicit acceptance of suggested defaults
- [ ] Output scope is confirmed; both scopes use the same workspace shape, while `project` includes an explicit initialized target-project path
- [ ] The canvas format is fixed before SVG generation
-- [ ] Replication mode is consistent with the input type (`fidelity` / `mirror` allowed for A and B with B's caveats noted; forbidden for C / D)
+- [ ] Replication mode is consistent with the input type (`fidelity` allowed for A/B; `mirror` allowed for A and structured B only; both forbidden for C/D)
+- [ ] Before offering `mirror`, every source Layout has at least one source-slide reference and every source Master is reachable through those Layouts; otherwise the exact unsupported identities were reported and mirror was not selected
- [ ] Basic template norms from prior content have been surfaced and accepted, or explicitly marked N/A when no reference exists
+- [ ] Mode-specific ownership policy is explicit: `standard` / `fidelity` author a new structure without source-topology distillation; `mirror` restores source ownership one-to-one
- [ ] For `library`, metadata is complete enough to register into the relevant index; for `project`, the same portable template metadata is complete and no global registration is planned
- [ ] Marker `[TEMPLATE_BRIEF_CONFIRMED]` emitted on its own line after the echoed brief
@@ -327,9 +348,8 @@ template_workspace="skills/ppt-master/templates/<kind_dir>/<template_id>"
# project scope
template_workspace="<target_project>"
-# identical in both scopes
-mkdir -p "$template_workspace/templates" "$template_workspace/images"
-mkdir -p "$template_workspace/icons" "$template_workspace/exports"
+# identical in both scopes; create optional roots only when writing an asset
+mkdir -p "$template_workspace/templates"
```
| Scope | Workspace target | Required action before generation |
@@ -345,43 +365,55 @@ 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` as read-only analysis inputs
+- `native_structure.json` and `source_template.pptx`
- `summary.md` (orientation only)
- exported `assets/`
- `*_vector_asset_inventory.json`, when the vector readability pass extracted assets; do not bulk-read `icons/*.svg`
-- cleaned SVG references from `svg/`
+- lightweight references from `authoring-svg/` and `authoring-svg-flat/`
+- for `mirror` only, matching lossless `svg/`, `svg-flat/`, and `svg/inheritance.json` restoration sources
- optional screenshots, if available
For type B, pass the cleaned SVG file list from the analysis workspace, `*_vector_asset_inventory.json` if extraction ran, any companion `design_spec.md` / `spec_lock.md`, and the analysis notes. Do not bulk-read extracted icons; open individual `icons/*.svg` only when needed.
For type C, pass the image file list and the visual analysis notes.
For type D, pass only the finalized brief.
-The role uses the analysis bundle to anchor objective facts such as theme colors, fonts, reusable backgrounds, common branding assets, layout grammar, image-placement rules, density rhythm, and page-slot semantics, then rebuilds the final SVG templates in a simplified, maintainable form.
+The role interprets the package according to replication mode:
+
+| Mode | Final SVG authority | Structure behavior |
+|---|---|---|
+| `standard` / `fidelity` | Newly authored SVGs based on the confirmed brief and visual references | Design an intentional new Master/Layout/slot system. Source topology is neither preserved nor distilled into the output. |
+| `mirror` | Lossless imported SVG/native-structure evidence | Restore source pages, Master/Layout identities and parentage, placeholder identity/bounds, ownership, and supported native-object metadata one-to-one. Lightweight projections are inspection views only. |
+
+**Hard rule — mode-specific authorship**: `standard` and `fidelity` author new SVG documents and compact canonical metadata. `mirror` restores the lossless source contract and may only normalize transport details required by the current compiler. Mirror never performs commonality extraction, semantic synthesis, merge/split, promotion/demotion, renaming, or re-parenting.
-**Native structure reconstruction**: Do not copy `native_structure.json` or `source_template.pptx` into `<template_workspace>/templates/`. Use their Master/Layout/placeholder facts to reconstruct the full source topology through the current SVG contract. Preserve every source Master, every retained Layout and its parent Master, picker name, placeholder type/index/bounds, and unused Layout roster. Same-named Layouts under different Masters receive globally unique keys. Recursively flatten source Master/Layout groups: push supported transforms, styles, opacity, and paint order into direct atomic elements; do not emit a Master/Layout `<g>`. Materialize at least one complete template page for every retained source Layout, including unused Layouts. Immediately below `design_spec.md §V Page Roster`, write a `Source Structure Reconstruction` table with one row per source Master/Layout and its output key/page or explicit unsupported reason. Never silently drop, merge, or re-parent source structure. Mirror keeps its exact source-slide count, so report any unused source Layout that cannot be materialized and use fidelity instead when the full Layout picker roster is required. Every emitted SVG repeats the identical atomic Master contract, selected atomic Layout contract, and top-level semantic slot groups so it remains a complete standalone preview.
+Do not package `native_structure.json` or `source_template.pptx` as template inputs. In `standard` / `fidelity`, author Master/Layout direct atoms and bounded slot groups deliberately from the intended reusable behavior. In `mirror`, use the lossless layered and flat SVGs plus inheritance/native facts to preserve source ownership. Recursively expand fixed Master/Layout group wrappers only because the structured contract requires direct atoms; preserve transforms, styles, paint order, and appearance, and never flatten or regroup by semantic judgment.
-Downstream, both template-adherence choices use `pptx_structure.mode: structured`. `page_layouts` selects one complete input prototype per page, while `pptx_masters` and `pptx_layouts` declare the output mapping before the first SVG. Strict preserves the prototype contract. Adaptive keeps the prototype Master and may explicitly create a new Layout key/name while authoring the page that needs it. For mirror packages, reused Master/Layout identities retain literal visual styling in addition to structure; only visible text content may change.
+`design_spec.md §V` records the newly authored roster for `standard` / `fidelity`. For `mirror`, add the `Source Restoration Map` required by [template-designer.md](../references/template-designer.md), with one row per source slide and its preserved Master/Layout assignment. Do not add a synthesis-decision table.
-**Apply the visual-fidelity decision from Step 3**: pages marked `literal` (typically cover / chapter / ending) must reproduce the reference's geometry, decoration, and sprite-sheet crops as-is — "simplified, maintainable form" applies only to genuinely redundant structure, not to load-bearing layout. Pages marked `adapted` may use the reference for tone and structural rhythm but evolve the design.
+**Native-shape metadata boundary**: The lightweight authoring projection removes opaque payload only from model context; it never becomes the restoration source. `standard` / `fidelity` use compact canonical shapes and assets rather than copied source payload. `mirror` reuses only native metadata already supported by the converter on unchanged Slide-local/slot objects. Fixed layers are normalized to direct atoms; unsupported or edited objects keep the current SVG fallback and are reported rather than silently replaced by stale metadata.
+
+Downstream, both template-adherence choices use `pptx_structure.mode: structured`. `page_layouts` selects one complete input prototype per page, while `pptx_masters` and `pptx_layouts` declare the output mapping before the first SVG. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create a new Layout key/name while authoring the page that needs it. A mirror-created package does not force a future generated deck to keep the source page count or order.
+
+**Apply the visual-fidelity decision from Step 3 to authored modes**: in `standard` / `fidelity`, pages marked `literal` reproduce the selected reference geometry and decoration while still using a newly designed structure; pages marked `adapted` may evolve the composition. Mirror restores every supported source visual and does not use this authored-page distinction.
**Sprite-sheet preservation (do NOT simplify away)**: PPTX-exported assets are often sprite sheets — a single tall/large image referenced from multiple slides, each cropping a different region via nested `<svg ... viewBox="...">` wrappers around `<image width="1" height="1">`. This nesting is **load-bearing geometry**, not redundant structure. When rebuilding, preserve the exact `viewBox` crop and the outer `<svg>` placement for every image; do not flatten to a single `<image>` with direct `x/y/width/height`. Verify by sampling: if any asset's pixel dimensions don't match the on-page display aspect, it is a sprite and the wrapper must stay.
-**Mirror-mode override** (type A or B): when `Replication mode: mirror`, this step is a **verbatim copy** rather than a reconstruction. The Template_Designer role:
+**Mirror-mode restoration contract** (type A or B): when `Replication mode: mirror`, the Template_Designer role:
-1. **Copies the cleaned source pages** into `<template_workspace>/templates/` with literal visual fidelity — no content rewriting or decorative simplification. Then annotate the complete page with root Master/Layout identity, direct atomic Master/Layout elements, and top-level slot groups derived from the layered source. Recursively flatten source Master/Layout groups while preserving supported appearance and paint order. The SVG remains visually identical when opened alone, while export can deterministically reconstruct native structure.
- - Type A: source is the cleaned flat `<import_workspace>/svg-flat/slide_NN.svg`
- - Type B: source is each cleaned `*.svg` in the analysis workspace when extraction ran; otherwise each `*.svg` in the normalized Type B source directory (already self-contained)
+1. **Restores one output SVG per source page** in `<template_workspace>/templates/`. Use lightweight projections for inspection, but materialize from the matching lossless source and native structure facts. Preserve source Master/Layout keys and picker names, Layout parentage, slide assignment, placeholder type/index/bounds, 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 restoration source: `<import_workspace>/svg/`, `<import_workspace>/svg-flat/`, `svg/inheritance.json`, and `native_structure.json`
+ - Type B restoration source: the complete explicit source SVG contract; `authoring-svg/` remains inspection-only
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`.
- Type A: derive `<page_type>` from `manifest.json.pageTypeCandidates`
- Type B: derive `<page_type>` from the source filename when it follows the PPT Master convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); otherwise infer from page content or fall back to `content`
-3. **Routes bundled assets through the common workspace contract** and rewrites every `<image href="...">` consistently. Asset filenames may be renamed to semantic names (`brand_emblem.png` instead of `image3.png`) when it improves readability.
+3. **Routes bundled assets through the common workspace contract** and rewrites every `<image href="...">` consistently. Keep stable source asset identity in mirror; do not rename, merge, or replace assets by semantic judgment.
- Type A: assets come from `<import_workspace>/assets/`
- Type B: resolve relative paths in source `<image href="...">` against the source SVG location and copy each unique asset; if the source already follows PPT Master conventions (assets co-located with SVGs in the same directory), copy the whole asset set and then rewrite paths
- Both scopes: write bitmaps to `<template_workspace>/images/`, point SVG references at `../images/<name>`, and keep non-bitmap template-source assets under `<template_workspace>/templates/`.
-4. **Copies `icons/` when present** and preserves every extracted `<use data-icon="..."/>` reference. Both scopes write the package/validation copy to `<template_workspace>/templates/icons/` and an identical runtime copy to `<template_workspace>/icons/`. Do not inline these assets manually in the template working SVGs; the shared icon embedding path owns re-inlining before export.
+4. **Copies `icons/` when present** and preserves every adopted `<use data-icon="..."/>` reference. Both scopes write the package/validation copy to `<template_workspace>/templates/icons/` and an identical runtime copy to `<template_workspace>/icons/`. Do not inline these assets manually in the template working SVGs; the shared icon embedding path owns re-inlining before export.
5. Writes `design_spec.md` per [template-designer.md](../references/template-designer.md) §1. The §V Page Roster remains the content-fit index; explicit SVG metadata is the native Master/Layout contract. Mirror is only the template-creation replication mode; downstream generation still treats the finished package as a selectable / reusable roster, not as a forced 1:1 slide sequence.
-Mirror mode does not simplify the visual page, but it still reconstructs layer ownership. The sprite-sheet preservation rule applies because flat SVGs already contain the original crop wrappers; do not flatten them when annotating the page.
+Mirror mode does not simplify the visual target or synthesize layer ownership. The sprite-sheet preservation rule applies because crop wrappers carry visible geometry; preserve those wrappers and their source scope faithfully.
**Expected outputs from this step** (full spec → [template-designer.md](../references/template-designer.md)):
@@ -417,6 +449,7 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/t
- require every SVG root to declare one output Master and Layout; zero-slot Layouts are valid
- reject Master/Layout `<g>` elements, nested structure markers, missing slot bounds, and carrier-bound slots without exactly one compatible carrier
- validate cross-page Master equality plus same-key Layout atom/slot equality
+- warn when distinct Layout keys have identical static framing/slot contracts. Resolve this for `standard` / `fidelity`; mirror may retain the distinct source identities and records that fact in its Source Restoration Map
**Checklist**:
@@ -431,16 +464,22 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_workspace>/t
- [ ] `design_spec.md` frontmatter declares `native_structure_mode: structured`; no `native_structure.json` or `source_template.pptx` is packaged
- [ ] Every SVG root declares Master/Layout key and picker names; Master/Layout visuals are direct atoms, never `<g>`, and obey the explicit paint-order contract. Structural `data-pptx-role` is used only when specialized metadata cannot express required package/page-number/animation behavior
- [ ] Every slot is a direct `<g id>` with explicit design-zone bounds and exactly one compatible direct carrier, or an explicit composite `object` proxy; zero-slot Layouts remain valid
-- [ ] Every source Layout is represented by a complete template page, or `design_spec.md` records an explicit unsupported reason in `Source Structure Reconstruction`; no silent merge, drop, or re-parenting
+- [ ] `standard` / `fidelity` output SVGs and their Master/Layout/slot contracts were newly authored without preserving or distilling source topology
+- [ ] Mirror output preserves source slide order, Master/Layout identity and parentage, placeholder facts, and ownership; fixed-layer group expansion is mechanical and pixel-equivalent, and the Source Restoration Map lists every source slide
+- [ ] Mirror preflight proved that the source graph has no unused Layout or unreachable Master that the one-prototype-per-source-slide roster would silently omit
+- [ ] For `standard` / `fidelity`, no duplicate-Layout-contract warning remains; mirror may keep equivalent source Layout identities when the restoration map explains them
+- [ ] Lightweight projections were used only for inspection. Mirror materialized from lossless sources, reused only converter-supported metadata on unchanged Slide-local/slot objects, and kept fixed Master/Layout visuals as direct atoms
- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists under `<template_workspace>/templates/icons/` and the identical runtime copy exists under `<template_workspace>/icons/`; do not add a separate illustration embedding script
- [ ] For `fidelity` mode: every sprite-sheet asset retains its nested `<svg viewBox=...>` crop wrapper; no image whose file aspect differs from its on-page aspect was flattened to a bare `<image>`
-- [ ] For `mirror` mode: file count equals source page count (type A: `<template_source>/*_*.svg` matches the cleaned flat `<import_workspace>/svg-flat/slide_*.svg` count; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no `{{...}}` placeholder strings appear in any copied SVG** (`grep -l "{{" "<template_source>"/*.svg` should return nothing — if the type B source itself contains placeholders, the user should be in `standard` mode, not `mirror`); §V Page Roster in `design_spec.md` lists every emitted file with a one-line description of what the page contains and what content slot it suits
+- [ ] For `mirror` mode: file count equals source page count (type A: `<template_source>/*_*.svg` matches the lossless `<import_workspace>/svg-flat/slide_*.svg` count; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no new `{{...}}` authoring placeholders were inserted into restored SVGs**; §V Page Roster in `design_spec.md` lists every emitted file with a one-line description of what the page contains and what content slot it suits
-This step is a **hard gate**. Do not export the review PPTX, register, or hand the workspace to the main pipeline until validation passes.
+This step is a **hard gate**. Do not generate an optional review PPTX, register, or hand the workspace to the main pipeline until validation passes.
---
-## Step 6: Export and Verify the Template Review PPTX
+## Step 6: Optional Template Review PPTX
+
+**Trigger**: Run only when the user requests a PowerPoint review file. Otherwise skip directly to Step 7 and do not create `exports/`.
Export the complete SVG roster, one prototype per slide, from the workspace root:
@@ -448,7 +487,7 @@ Export the complete SVG roster, one prototype per slide, from the workspace root
python3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>"
```
-The default output is `<template_workspace>/exports/<template_id>_template_preview.pptx`. The script consumes `templates/*.svg` directly, compiles the declared structured Master/Layout contract, and reopens the result. It does not require a project `spec_lock.md`, does not create an intermediate project, and does not infer or distill structure.
+The default output is `<template_workspace>/exports/<template_id>_template_preview.pptx`; the command creates `exports/` on demand. The script consumes `templates/*.svg` directly, compiles the declared structured Master/Layout contract, and reopens the result. It does not require a project `spec_lock.md`, does not create an intermediate project, and does not infer or distill structure.
The first export refuses an existing output. After intentionally fixing the template and replacing its prior review deck, rerun with `--force`; never rely on a silent overwrite:
@@ -463,7 +502,7 @@ python3 skills/ppt-master/scripts/template_preview_pptx.py "<template_workspace>
- [ ] Package read-back reports the expected Master and Layout counts
- [ ] The user can open one file and review every template page in deterministic filename order
-This step is a **hard gate**. A template that cannot produce its review PPTX is incomplete; fix the owning SVG/spec/asset and rerun Steps 5–6 before registration or handoff.
+If this optional step is run, every validation item becomes a hard gate for the review artifact. Fix the owning SVG/spec/asset before reporting the preview as verified. Failure of an unrequested preview does not block a workspace that already passed Step 5.
---
@@ -473,7 +512,7 @@ Branch on the confirmed output scope:
| Scope | Action |
|---|---|
-| `library` | Run the registrar below after Steps 5–6 pass |
+| `library` | Run the registrar below after Step 5 passes and, when requested, Step 6 also passes |
| `project` | Skip the registrar entirely. Do not edit `decks_index.json`, `layouts_index.json`, or any library README; continue to Step 8 with index status `Not registered (project workspace)` |
Run the unified registrar with the kind flag; it derives the corresponding index entry from `templates/design_spec.md` (frontmatter when present, prose fallback otherwise) plus the actual `templates/*.svg` file list. The registrar retains read compatibility with old flat library packages; new creation never writes that shape:
@@ -560,9 +599,9 @@ Produce one scope-aware, evidence-driven completion card for either location:
**Output Scope**: library | project
**Workspace Path**: `<template_workspace>/`
**Template Source**: `<template_workspace>/templates/`
-**Bitmap Path**: `<template_workspace>/images/`
-**Runtime Icon Path**: `<template_workspace>/icons/`
-**Review PPTX**: `<template_workspace>/exports/<template_id>_template_preview.pptx`
+**Bitmap Path**: `<template_workspace>/images/` ← omit when absent
+**Runtime Icon Path**: `<template_workspace>/icons/` ← omit when absent
+**Review PPTX**: `<template_workspace>/exports/<template_id>_template_preview.pptx` ← omit when not requested
**Primary Color**: <hex> ← deck only; omit for layout
**Index Registration**: Done | Not registered (project workspace)
@@ -575,10 +614,10 @@ Produce one scope-aware, evidence-driven completion card for either location:
| `templates/02_toc.svg` | Done |
| `templates/03_content.svg` | Done |
| `templates/04_ending.svg` | Done |
-| `exports/<template_id>_template_preview.pptx` | Verified |
+| `exports/<template_id>_template_preview.pptx` | Verified, when requested |
```
-The next main-pipeline Step 3 input is the exact `<template_workspace>/` root in either scope. Step 3 resolves its `templates/design_spec.md`, ignores `exports/`, and copies or consumes `templates/`, `images/`, and `icons/` as one unit. A legacy flat package root remains readable, but directory flatness alone is not a legacy Master/Layout condition and does not trigger `restore-pptx-structure`.
+The next main-pipeline Step 3 input is the exact `<template_workspace>/` root in either scope. Step 3 resolves its `templates/design_spec.md`, ignores `exports/`, and copies or consumes `templates/` plus any existing `images/` and `icons/` as one unit. A legacy flat package root remains readable, but directory flatness alone is not a legacy Master/Layout condition and does not trigger `restore-pptx-structure`.
---
@@ -599,6 +638,6 @@ The next main-pipeline Step 3 input is the exact `<template_workspace>/` root in
2. **Color consistency**: All SVG files must use the same color scheme as `design_spec.md §II Color Scheme`
3. **Placeholder convention**: `{{}}` format only; default names listed in [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). Override per template via `placeholders:` frontmatter when needed.
4. **Discovery requirement**: A library template is discoverable only after `register_template.py` has been run against it (Step 7). A project-scoped workspace intentionally stays out of global discovery and is consumed by its explicit workspace-root path.
-5. **Review requirement**: Every completed deck/layout template has a verified `exports/<template_id>_template_preview.pptx`; it is never a source input during template application.
+5. **Review output**: Generate `exports/<template_id>_template_preview.pptx` only on request. It is derived local evidence, never a source input during template application, and library exports stay Git-ignored.
> **Full role specification**: [template-designer.md](../references/template-designer.md)
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
index 34c0e90b..2dfee775 100644
--- a/skills/ppt-master/workflows/index.md
+++ b/skills/ppt-master/workflows/index.md
@@ -17,8 +17,8 @@ Registry for standalone workflows referenced by `SKILL.md` and [`routing.md`](./
| `topic-research` | [`topic-research.md`](./topic-research.md) | Topic-only request with no substantive source material | Topic or requirements exist | Do not invent facts in the main pipeline | Before `SKILL.md` Step 1 | Source material suitable for Step 1 | Stops if usable source facts cannot be gathered |
| `template-fill-pptx` | [`template-fill-pptx.md`](./template-fill-pptx.md) | Raw PPTX template plus new material/topic; clone/fill native slides | Source PPTX plus content material or topic brief | No SVG generation; no `create-template` unless reusable package is requested | Workflow Step 1 | Native PPTX in project `exports/` | Stops if no PPTX or no fill material |
| `beautify-pptx` | [`beautify-pptx.md`](./beautify-pptx.md) | Existing PPTX should be re-laid out while preserving slide count/order and wording 1:1 | Single source PPTX | Not for merge/split/drop/reorder or re-outline | Workflow Step 1 | Regenerated 1:1 deck through SVG pipeline | Blocks on source-slide mapping and final confirmation gates defined in the workflow |
-| `create-template` | [`create-template.md`](./create-template.md) | Build a reusable layout/deck template from a PPTX or design reference, globally or for one initialized project | Design source or explicit template-creation request; project scope also requires an initialized target project | Does not fill final content; its PPTX is a review of the template roster, not a generated content deck | Workflow Step 1 | Both scopes produce a complete workspace containing `templates/`, `images/`, `icons/`, and `exports/<id>_template_preview.pptx`; library root is `skills/ppt-master/templates/<kind>/<id>/`, project root is `projects/<name>/`; only library scope is registered | Return the exact workspace root to main Step 3; the target project's own root may continue in place after validation and preview export |
-| `create-brand` | [`create-brand.md`](./create-brand.md) | Build/extract a reusable brand identity preset | Logo/site/branded deck/PDF or explicit brand setup request | Not a layout/deck template roster | Workflow Step 1 | Brand directory under `templates/brands/<id>/` | Blocks on brand evidence and validation defined in the workflow |
+| `create-template` | [`create-template.md`](./create-template.md) | Build a reusable layout/deck template from a PPTX or design reference, globally or for one initialized project | Design source or explicit template-creation request; project scope also requires an initialized target project | Does not fill final content; an optional PPTX is only an on-demand review artifact | Workflow Step 1 | Both scopes produce one workspace with required `templates/`, optional `images/` / `icons/`, and optional `exports/<id>_template_preview.pptx`; library root is `skills/ppt-master/templates/<kind>/<id>/`, project root is `projects/<name>/`; only library scope is registered | Return the exact workspace root to main Step 3; the target project's own root may continue in place after validation |
+| `create-brand` | [`create-brand.md`](./create-brand.md) | Build/extract a reusable brand identity preset | Logo/site/branded deck/PDF or explicit brand setup request | Not a layout/deck template roster | Workflow Step 1 | Complete identity-only workspace under `templates/brands/<id>/` | Blocks on brand evidence and validation defined in the workflow |
| `resume-execute` | [`resume-execute.md`](./resume-execute.md) | Continue an existing split-mode project | Planning-session artifacts exist | Do not re-run planning | Execution-session entry | SVG generation, post-processing, export | Stops if `design_spec.md` or `spec_lock.md` is missing |
| `refine-spec` | [`refine-spec.md`](./refine-spec.md) | User explicitly opts into spec refinement before generation | Strategist confirmation stage completed | Do not enter by default | After Step 4, before Step 5/6 | Revised `design_spec.md` and `spec_lock.md` | Blocks for user review/approval before generation |
| `restore-pptx-structure` | [`restore-pptx-structure.md`](./restore-pptx-structure.md) | Existing project or template uses a legacy/unmapped PowerPoint structure contract | Legacy SVG project/package exists; original PPTX/native facts are preferred when available; legacy-flat packaging alone is not a trigger | Not part of normal new-project generation; exporter never migrates implicitly | Before Step 3 template use, SVG generation, or export | Current structured SVGs plus complete Master/Layout lock mapping | Blocks only when restoration requires an unresolved design decision |
diff --git a/skills/ppt-master/workflows/restore-pptx-structure.md b/skills/ppt-master/workflows/restore-pptx-structure.md
index b04fc94f..b5ae3e78 100644
--- a/skills/ppt-master/workflows/restore-pptx-structure.md
+++ b/skills/ppt-master/workflows/restore-pptx-structure.md
@@ -10,6 +10,8 @@ Restore an existing SVG-authored project or template before quality checking or
**Hard rule — structure, not packaging**: Directory shape is not PowerPoint structure evidence. A current template workspace uses `templates/design_spec.md`; a compatible legacy-flat package uses `design_spec.md` at its root. Do not run this workflow merely to move a flat package into the current workspace shape.
+**Boundary against template creation**: This workflow normalizes one existing project's/package's structure without visual redesign. It does not choose a reusable-template replication mode. When its result becomes type-B input to [`create-template`](./create-template.md), `standard` / `fidelity` treat it as visual reference and author new structure; `mirror` restores its explicit source ownership one-to-one.
+
---
## 1. Route Boundary
@@ -21,7 +23,7 @@ Restore an existing SVG-authored project or template before quality checking or
| Legacy `preserve` plus `native_structure.json` / `source_template.pptx` | Use the native facts as restoration evidence; rebuild the SVG contract instead of preserving package parts |
| Existing `mode: structured` project | Validate and repair only the reported mismatch; do not re-infer the deck |
| Legacy-flat template package whose SVG roots and slots already satisfy the current structured contract | Consume it through the compatibility reader; do not restore or relocate it solely because `design_spec.md` and SVGs are flat |
-| Current template workspace with `templates/`, `images/`, `icons/`, and `exports/` | Inspect SVG metadata to decide whether restoration is needed; the workspace folders themselves do not prove or disprove structure |
+| Current template workspace with `templates/` and optional `images/`, `icons/`, or `exports/` | Inspect SVG metadata to decide whether restoration is needed; the workspace folders themselves do not prove or disprove structure |
| Raw PPTX intended as a reusable template | Run [`create-template`](./create-template.md), not this workflow |
| Existing PPTX receiving notes/audio/timing/transitions | Keep the direct [`native-enhance-pptx`](./native-enhance-pptx.md) route; do not create SVGs |
| Raw PPTX template receiving new content | Keep the direct [`template-fill-pptx`](./template-fill-pptx.md) route |
@@ -44,7 +46,7 @@ Record the source evidence used for restoration in a short `README.md` inside th
**Hard rule**: Never delete the legacy sources during restoration. If the requested migration would rewrite several existing files and the user has not already authorized that operation, obtain the repository-required bulk-modification confirmation first.
-**Hard rule — no packaging migration**: Keep the input workspace/package placement unchanged. This workflow edits the semantic SVG/lock contract only; it does not normalize a legacy-flat package into `templates/`, `images/`, `icons/`, and `exports/`.
+**Hard rule — no packaging migration**: Keep the input workspace/package placement unchanged. This workflow edits the semantic SVG/lock contract only; it does not normalize a legacy-flat package into the current `templates/` plus optional `images/`, `icons/`, and `exports/` routing.
---
@@ -54,10 +56,16 @@ Use this evidence priority:
| Priority | Evidence | Contract |
|---:|---|---|
-| 1 | Original PPTX plus verified native structure facts | Preserve Master/Layout names, ownership, placeholder type/index/bounds, and page assignment |
+| 1 | Original PPTX plus verified native structure facts | Use the source contract as compatibility evidence for this no-redesign restoration; record any required normalization |
| 2 | Legacy template SVGs or explicit legacy structure metadata | Preserve stable identities and reusable geometry after removing legacy-only fields |
| 3 | Completed SVG pages only | Classify deliberately across the full deck; do not let the exporter infer structure |
+**Hard rule — reachable native graph only**: The current structured contract
+materializes Master/Layout identities through output-page references. If native
+evidence contains a Layout unused by every output page, or a Master reachable
+only through such Layouts, stop and list the exact identities. Do not silently
+drop them, synthesize a carrier page, or claim full source-graph restoration.
+
**Hard rule**: Decide from SVG/lock semantics, never from whether `design_spec.md` is at the workspace root or under `templates/`.
Classify each visible object:
@@ -73,6 +81,8 @@ Classify each visible object:
**Hard rule — no visual redesign**: Do not change wording, geometry, paint, assets, or z-order except for the normalization required to flatten a fixed Master/Layout group. Render before and after any transform-flattening edit and require pixel equivalence.
+**Hard rule — native metadata below structural layers**: Keep the complete lossless import artifact in the backup/evidence set. An unchanged imported shape may keep the source metadata already supported by the converter when it remains Slide-local or inside a slot; no additional opt-in marker exists. A logical `<g>` cannot become Master/Layout because those layers require direct atoms. Normalize fixed-layer objects into direct atom(s), rebuilding a preset when supported and otherwise keeping the current SVG fallback. Any geometry, paint, text, or fingerprint change invalidates stale source metadata. `data-pptx-native` remains reserved for chart/table markers.
+
---
## 4. Write the Structured SVG Contract
@@ -187,5 +197,6 @@ After the checker reports zero errors, return to `SKILL.md` Step 7.2 and Step 7.
- [x] Every slot has explicit bounds and a valid carrier or proxy contract
- [x] `spec_lock.md` contains complete `structured` Master and page mappings
- [x] Group-flattening edits are pixel-equivalent and the quality gate reports zero errors
+- [x] Imported native metadata is used only through supported existing attributes on unchanged Slide-local/slot objects; Master/Layout objects remain direct atoms
- [ ] **Next**: Resume the canonical post-processing and release export steps
```
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index 4acd4609..146ddd1c 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -27,7 +27,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Route family | SVG contract |
|---|---|
| Main SVG pipeline and `beautify-pptx` | Every visible output-page object is authored in the completed page SVG; templates and locks guide authoring but are not export-time visual overlays. |
-| `create-template` | Each reusable template SVG is a complete visual reference plus explicit PowerPoint structure metadata. Library and project outputs use the same complete workspace shape: `templates/`, `images/`, `icons/`, and `exports/<id>_template_preview.pptx`. |
+| `create-template` | Each reusable template SVG is a complete visual reference plus explicit PowerPoint structure metadata. Library and project outputs use the same routing: required `templates/`, optional `images/` / `icons/`, and optional on-demand review output under `exports/`. |
| `template-fill-pptx` and `native-enhance-pptx` | Native PPTX editing routes. They retain their OOXML contracts and are not forced through SVG. |
| Animation, transition, speaker-note, and narration workflows | Presentation behavior/content outside the visible page-design layer; keep their dedicated sidecars and package post-processing. |
@@ -42,7 +42,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Topic only, no source facts | User supplies only a topic name or requirement and no substantive source material | [`topic-research`](./topic-research.md), then main `SKILL.md` pipeline | Direct main pipeline with invented facts | Web/source gathering is allowed or user supplies facts | Research material becomes source input for Step 1 | Stop if facts cannot be gathered and the user supplies no source |
| Source material can be reworked into a new story | PDF/DOCX/URL/Markdown/text/conversation content, or PPTX treated as content | Main `SKILL.md` pipeline | Direct PPTX edit workflows | Source content exists or is available in conversation | `design_spec.md`, `spec_lock.md`, `svg_output/`, exported PPTX | Stop at Step gates when required artifacts are missing |
| PPTX as re-architectable source | User allows page count/order/outline to change, or asks to split/merge/drop/reorder slides | Main `SKILL.md` pipeline with `ppt_to_md.py` plus PPTX intake | [`beautify-pptx`](./beautify-pptx.md) | PPTX source exists | Markdown content plus `analysis/source_profile.json`; Strategist may re-outline | Stop if user requires exact 1:1 page preservation |
-| Explicit template workspace path | User provides a current layout/deck workspace root containing `templates/design_spec.md`, a compatible legacy-flat layout/deck root containing `design_spec.md`, or an existing brand directory under its unchanged direct-spec contract | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name; passing a current workspace's inner `templates/` directory instead of its root | Path resolves, frontmatter kind is valid, and every deck/layout SVG satisfies the current structured Master/Layout/slot contract | Stage `templates/`, `images/`, and `icons/` from the explicit workspace root into the target project peers; consume the target project's own root in place; never consume the review-only `exports/` directory | Route only a structurally legacy SVG contract to [`restore-pptx-structure`](./restore-pptx-structure.md) before Step 3; a legacy-flat directory shape alone remains compatible and does not trigger restoration |
+| Explicit template workspace path | User provides a current brand/layout/deck workspace root containing `templates/design_spec.md`, or a compatible legacy-flat root containing `design_spec.md` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name; passing a current workspace's inner `templates/` directory instead of its root | Path resolves, frontmatter kind is valid, and every deck/layout SVG satisfies the current structured Master/Layout/slot contract | Stage `templates/` plus any existing `images/` and `icons/` into the target project peers; consume the target project's own root in place; never consume the review-only `exports/` directory | Route only a structurally legacy SVG contract to [`restore-pptx-structure`](./restore-pptx-structure.md) before Step 3; a legacy-flat directory shape alone remains compatible and does not trigger restoration |
---
@@ -53,7 +53,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Raw PPTX template plus new material/topic | "Use this PPT template to generate a PPTX", "fill this deck", "replace copy", native slide shell reuse | [`template-fill-pptx`](./template-fill-pptx.md) | Main SVG pipeline directly from raw PPTX template | Source PPTX plus content material or topic brief | New native PPTX in `exports/`, cloned/patched by OOXML | Stop if user instead wants a reusable template package |
| Existing PPTX, preserve page split and wording | "Beautify", "re-layout", "make more professional" with same slide count/order and verbatim text | [`beautify-pptx`](./beautify-pptx.md) | Main pipeline if page count/order changes | Single source PPTX | Regenerated deck through SVG pipeline, one source slide to one output slide | Stop if user asks to split/merge/drop/reorder |
| Finished PPTX, native enhancement only | Add notes, recorded narration, auto-advance, transitions, or stable-layout metadata | [`native-enhance-pptx`](./native-enhance-pptx.md) | SVG regeneration | Finished PPTX exists; content/layout should stay stable | Patched PPTX through direct OOXML | Stop if user asks for visual redesign |
-| PPTX/reference design should become a reusable template | "Create a template", "make reusable", "build template from this deck/design", including a template for one named initialized project | [`create-template`](./create-template.md) | `template-fill-pptx` one-off fill | PPTX/design reference exists, or the user gives an explicit template-creation brief; project output additionally requires an initialized target project | Both scopes produce one complete workspace with `templates/`, `images/`, `icons/`, and `exports/<id>_template_preview.pptx`; library root is `skills/ppt-master/templates/<kind>/<id>/`, project root is `projects/<name>/`; only library scope is registered | Return the exact workspace root for main Step 3; the target project's own root may resume in place after validation and preview export |
+| PPTX/reference design should become a reusable template | "Create a template", "make reusable", "build template from this deck/design", including a template for one named initialized project | [`create-template`](./create-template.md) | `template-fill-pptx` one-off fill | PPTX/design reference exists, or the user gives an explicit template-creation brief; project output additionally requires an initialized target project | Both scopes produce one workspace with required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/<id>_template_preview.pptx`; library root is `skills/ppt-master/templates/<kind>/<id>/`, project root is `projects/<name>/`; only library scope is registered | Return the exact workspace root for main Step 3; the target project's own root may resume in place after validation |
**Hard rule**: Raw PPTX template plus "generate PPTX" routes to `template-fill-pptx` by default. A raw PPTX is not a Step 3 template until `create-template` has produced a reusable template directory.
@@ -65,7 +65,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Request shape | Trigger | Route | Preconditions | Output contract | Stop condition |
|---|---|---|---|---|---|
-| Brand identity setup | Brand asset, brand site URL, branded PPTX/PDF, or explicit brand setup request | [`create-brand`](./create-brand.md) | Brand source exists or can be inspected | Brand preset under `templates/brands/<id>/` | Stop if no brand source or brand intent exists |
+| Brand identity setup | Brand asset, brand site URL, branded PPTX/PDF, or explicit brand setup request | [`create-brand`](./create-brand.md) | Brand source exists or can be inspected | Complete identity-only workspace under `templates/brands/<id>/` | Stop if no brand source or brand intent exists |
| Continue a split-mode project | "Continue generating `projects/<name>`" after the planning session | [`resume-execute`](./resume-execute.md) | Project has planning-session artifacts | Execution-session SVG generation and export | Stop if required planning artifacts are missing |
| Refine spec before generation | User explicitly asks to refine/review/revise the spec before SVG work, or confirms `refine_spec: true` | [`refine-spec`](./refine-spec.md) | Strategist confirmation stage completed | Revised `design_spec.md` and `spec_lock.md` before Step 5/6 | Stop until user approves the refined spec |
| Restore legacy PowerPoint structure | Existing project/template SVGs use unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or lack root Master identity | [`restore-pptx-structure`](./restore-pptx-structure.md) before generation/export or before Step 3 template consumption | Legacy SVG project/package exists; original PPTX/native facts are used when available; a flat package directory by itself is not a trigger | Current structured SVG contract plus complete `pptx_masters`/`pptx_layouts` mapping | Stop if structure cannot be restored without an explicit design decision |
@@ -81,11 +81,10 @@ Route selection authority for PPT Master. Use this file before entering the main
| User input | Route behavior |
|---|---|
-| Explicit current layout/deck workspace root containing `templates/design_spec.md` | Enter main Step 3 template option; use the workspace root, not its inner `templates/` directory |
-| Explicit legacy-flat layout/deck root containing `design_spec.md` | Enter main Step 3 through the compatibility reader; flat packaging alone does not require structure restoration |
-| Explicit brand directory containing `design_spec.md` | Enter main Step 3 under the existing `create-brand` contract; brand packaging is unchanged by `create-template` workspace rules |
+| Explicit current brand/layout/deck workspace root containing `templates/design_spec.md` | Enter main Step 3 template option; use the workspace root, not its inner `templates/` directory |
+| Explicit legacy-flat root containing `design_spec.md` | Enter main Step 3 through the compatibility reader; flat packaging alone does not require structure restoration |
| Bare template name, brand name, style label, or vague "use a template" | Do not trigger Step 3; treat as style input for Strategist confirmation stage |
| User asks "what templates exist?" | Answer as Q&A by listing indexed paths; do not advance the pipeline |
| Raw `.pptx` called a template | Route by §3, usually `template-fill-pptx`; never treat it as a Step 3 template path |
-**Forbidden - fuzzy resolution**: Do not resolve bare names to local template directories on the user's behalf. The user must provide the path that enters Step 3. For a current layout/deck package, that path is the workspace root.
+**Forbidden - fuzzy resolution**: Do not resolve bare names to local template directories on the user's behalf. The user must provide the path that enters Step 3. For every current template kind, that path is the workspace root.