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(pptx-structure): establish SVG page-design boundary
hugohe3d9633ba47de7
diff --git a/docs/faq.md b/docs/faq.mdindex 4be28538..15bcff64 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -238,7 +238,7 @@ 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, every master/layout, placeholder type/index metadata, and reusable assets. When that native structure is reusable, the template package retains the source package as an optional strict-use capability; when the structure is minimal, the workflow rebuilds a clean master plus semantic layouts from layered SVG references. When the resulting template is used, Strategist asks whether adherence is `adaptive` (SVG references plus free pages, baseline export) or `strict` (every page follows the roster and compatible source layouts are preserved).+The recommended input is the original `.pptx`. PPT Master extracts theme identity, every Master/Layout, placeholder metadata, and reusable assets, then rebuilds one clean Master plus semantic Layouts as complete, explicitly annotated SVG pages. When that template is used, `adaptive` may create a new explicit Layout under the same Master; `strict` keeps the selected Layout contract unchanged. Both routes reconstruct native structure from the SVGs.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.diff --git a/docs/roadmap.md b/docs/roadmap.mdindex b93d79a9..1ff0358a 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -53,7 +53,7 @@ The past two months' structural capability growth. Single flags / incremental po- **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- **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: enumerable fields (canvas / mode / visual_style / conditional template adherence / icons / image usage / formula & generation policy) list common options from `catalogs.json`, while generative fields present candidates — color swatches, live font previews (CJK / Latin previewed independently), and AI-image rendering × palette picks; plus live swatch feedback on custom HEX, a live combined color × typography preview, and a body-size range hinted from the chosen canvas. Template adherence appears only when Step 3 actually loaded a deck/layout template and defaults to `adaptive`; `strict` is the explicit path to all-page roster mapping and compatible native preservation. It **shares port `5050`** with the Step 6 Live Preview (they never run at once — the page auto-`--shutdown`s at the end of Step 4 to free the port; if the port is busy the launcher auto-advances to the next free one). On principle **chat stays the canonical channel and the page is a convenience layer**: the page's `result.json` is authoritative over the recommendations and is consumed in place downstream (image plan / `image_strategy` / fonts / the split and refine-spec toggles all read from it), and any failure to open / timeout / headless host degrades losslessly to the chat-summary fallback+- **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)- **Content-faithful PPT beautification / re-layout shipped** ([`workflows/beautify-pptx.md`](../skills/ppt-master/workflows/beautify-pptx.md)) — mirror of `template-fill`: template-fill reuses a deck's design with new content, beautify keeps the content and redoes the layout. Given an existing PPTX, **every text string is preserved verbatim (nothing added / removed / reworded)**; it **extracts and inherits the source deck's visual identity (palette / fonts, `theme` or `observed` offered as two confirm-page candidates)** and redoes only layout / hierarchy / whitespace, strict 1:1 page count and order, with charts / tables regenerated natively from extracted data (values frozen) and source pictures re-laid-out. Technically still "generate a native, editable PPTX from scratch" (`ppt_to_md` extracts content → main pipeline → a brand-new deck), not a patch over the original, so it stays clear of Non-goals #53. Adds `beautify_identity.py` / `beautify_inventory.py`; the confirm page is seeded from the source for the user to review. Honest v1 ceiling: it does not relieve information overload (a crowded page improves within itself; true re-pagination is the main pipeline), does not guarantee coordinate-level paste-back, and combo / dual-axis / waterfall charts lose the un-captured plots@@ -82,7 +82,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** — native export keeps a real master/layout relationship and defaults to a baseline master that promotes only safe shared backgrounds/chrome. After SVG generation, baseline assigns filename-backed Cover/Agenda/Section/Closing/Content layouts and lifts only exact family-wide backgrounds; actual content remains slide-local and no placeholders are inferred. A locked `template` mode compiles declared SVG master/layout layers and typed placeholders without visual inference; a reusable PPTX imported through `create-template` retains its native pair as optional capability. Strategist now confirms template adherence: `strict` can lock `preserve`, retain the original master/layout/theme roster (including multiple masters), bind every page to an exact source layout, and restore source placeholder indices; `adaptive` keeps the created SVG roster optional and exports through baseline. Raw one-off PPTX filling remains the `template-fill-pptx` route. The standalone importer also emits fallback SVG plus native metadata for supported unmerged tables and classic-chart caches; unsupported semantics remain explicit fallback-only markers+- **Native package structure + conservative PPTX object round-trip** — free-design baseline export promotes only safe shared backgrounds/chrome, assigns filename-backed Layout families, and may lift exact family-wide leading chrome without inferring placeholders. Template export deterministically compiles complete SVG pages whose Master/Layout/placeholder ownership is explicit. `create-template` uses imported source structure as analysis input and always rebuilds explicit SVG structure; strict keeps a selected Layout, adaptive may add a new Layout under the same Master. Legacy `preserve` remains compatibility-only. Raw one-off PPTX filling remains `template-fill-pptx`.---@@ -116,7 +116,7 @@ PPT Master's main route is "AI generates SVG from scratch → DrawingML", with t**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` first turns a structured source into a reviewed reusable SVG template and may retain its native contract; strict downstream use activates `preserve` against exact source layouts, while adaptive use stays on baseline. What remains out of scope is unreviewed, schema-free text-only substitution against every arbitrary third-party placeholder system.+> **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 reconstruct native structure from those SVG contracts. 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.mdindex d0b114c4..7d6b0387 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -55,7 +55,20 @@ Output:└── svg_output/ ← Archived Executor SVG source (rerun finalize_svg → svg_to_pptx to rebuild)```-Direct PPTX workflows intentionally bypass this SVG route:+### SVG as the Page-Design Language++For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.++| Domain | Authority |+|---|---|+| Visible page content and layout on SVG-authoring routes | Final page SVG in `svg_output/` |+| Master/Layout/Slide packaging and native-object mapping | SVG-to-PPTX translation; it may reorganize represented content but does not invent visible content |+| Animations, transitions, speaker notes, and narration | Dedicated sidecars/assets and PPTX package post-processing |+| Direct native-PPTX editing | The selected native workflow's PPTX/OOXML contract |++This is a page-design closure rule, not a claim that SVG describes the entire PPTX package. Rebuilding the visible slide from its completed SVG is the relevant invariant; reconstructing notes, audio, timing, relationships, or direct native edits from SVG alone is not.++Direct PPTX workflows intentionally bypass the SVG authoring route and remain separate by design:| Workflow | Input role | Output mechanics | Why it is separate ||---|---|---|---|@@ -267,7 +280,7 @@ PPT Master uses **role switching within one main agent** rather than parallel su**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode (no improvisation, no missing attributes). Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.-**Strategist confirmation stage as the only blocking gate.** Strategist ends with a single confirmation gate delivered in three stages: Stage 1 confirms direction anchors (canvas, audience, divergence, delivery purpose, mode, visual style, plus template adherence only when Step 3 loaded a deck/layout template); Stage 2 is re-derived from those anchors and confirms the design system (page count, palette, typography, icons, formula policy); Stage 3 is re-derived from the confirmed design system and confirms images / execution (image usage, generated-image style, AI image path, generation mode, refine-spec). Template adherence defaults to `adaptive`; `strict` is the explicit all-page roster/native-preservation path. The final `confirm_ui/result.json` is authoritative — if the user changes a field, the generated `design_spec.md` and `spec_lock.md` must use that value, not the AI's original recommendation.+**Strategist confirmation stage as the only blocking gate.** Strategist ends with a single confirmation gate delivered in three stages: Stage 1 confirms direction anchors (canvas, audience, divergence, delivery purpose, mode, visual style, plus template adherence only when Step 3 loaded a deck/layout template); Stage 2 is re-derived from those anchors and confirms the design system (page count, palette, typography, icons, formula policy); Stage 3 is re-derived from the confirmed design system and confirms images / execution (image usage, generated-image style, AI image path, generation mode, refine-spec). Template adherence defaults to `adaptive`: every page still references the template architecture, but unmatched compositions may create a new explicit Layout under the same Master. `strict` keeps every selected Layout contract unchanged. The final `confirm_ui/result.json` is authoritative.**Image analysis goes through regenerated metadata, not pixels.** When images exist, Strategist and Executor use `analyze_images.py` output (`analysis/image_analysis.csv`) rather than directly opening image files. The CSV is a regenerated view over the live `images/` folder, not a durable cache. Re-running it before image-sensitive decisions is the staleness strategy: user images, extracted images, web images, AI outputs, formulas, and sliced elements all converge into the same measured fact table.@@ -427,13 +440,13 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why compatibility fallback belongs to the SVG snapshot path, not native shapes.** Native PPTX export translates supported SVG elements into DrawingML shapes and explicitly disables PNG+SVG compatibility mode in native-shapes mode. The PNG fallback is used only by the legacy SVG-image path (`--svg-snapshot` / `--only legacy`) when a renderer is available, because that path embeds SVG media that older Office builds may not display. Legacy compatibility is therefore an optional snapshot deliverable, not a fallback bundled inside the primary editable native deck.-**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` starts from the actual blank slide layout relationship in the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: the strict-majority identical slide background (every slide must carry an explicit background, and minority slides keep their own overriding fill), plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Chrome promotion also requires identical generated OOXML, no slide-timing reference, and the same leading z-order across a strict majority of slides sharing the master; overlay chrome stays slide-local. Minority slides — covers and section pages — keep every shape slide-local and are rebound to a generated `Cover` layout with `showMasterSp="0"`, following the PowerPoint convention that page-type differences live in layouts under one master rather than in extra masters, so promoted chrome never leaks onto them. After all pages are generated, an export-only pass assigns `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` from exact filename role tokens. It preserves the current master-shape visibility, never compares page visuals or infers placeholders, and moves a family background to its Layout only when every family member carries the exact same explicit `p:bg`; actual page content remains on the Slide. Image relationships for promoted chrome are copied to the slide master, base-template slide layouts no generated slide references are pruned from the package, and `pageNumber`/`slideNumber` chrome whose text exactly equals the slide's display number (honoring `firstSlideNum`) becomes an auto-updating slide-number field so reordering slides in PowerPoint renumbers pages. This gives ordinary decks a useful master/layout roster without constraining SVG authoring or spending model context on layout planning.+**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` starts from the actual blank slide layout relationship in the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: the strict-majority identical slide background plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Promotion requires identical generated OOXML, no timing reference, and z-order safety; minority pages keep their shapes slide-local and use a `Cover` layout with `showMasterSp="0"`. A later export-only pass assigns `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content`. It moves an exact family-wide background and an exact leading family-wide chrome prefix into that Layout, but never compares visual similarity or infers placeholders. Actual content remains on the Slide. This gives free-design decks useful Master/Layout structure without constraining SVG authoring.**Why reusable layouts require explicit SVG metadata.** `--pptx-structure template` is the opt-in path for a generated deck that must remain reusable as a PowerPoint template. The final slide SVGs declare a layout key at the root, mark only direct root children as master/layout layers, and attach typed placeholder semantics to the slide-local prototypes that should become layout placeholders. Export validates that shared master and same-key layout declarations are structurally and visually identical, then emits real layout parts and `p:ph` references while leaving every unmarked object slide-local. This is deterministic structure compilation, not visual-template inference.-**Why imported reusable templates retain native structure without forcing it.** `pptx_template_import.py` emits a paired `native_structure.json` and `source_template.pptx`. `create-template` may retain that pair when the source master/layout graph is reusable, while still building the ordinary SVG template roster. A later Strategist confirmation chooses template adherence: `strict` may set `pptx_structure.mode: preserve`, use the source package as the base, bind every generated page to an exact source layout, remove SVG-only previews of inherited layers, and restore source placeholder type/index identities; `adaptive` keeps template SVGs as optional references and exports through baseline. Existing multiple masters and unused template layouts remain available in PowerPoint's layout picker only on the strict preserve path. Raw PPTX plus one-off generated content still routes to `template-fill-pptx`; preserve mode begins only from a reusable template package.+**Why reusable templates rebuild explicit SVG structure.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus source structure facts. `create-template` uses those inputs to rebuild one clean Master and semantic Layouts as complete, explicitly annotated SVG pages; it does not package the original PPTX. Strict use keeps the selected Layout contract, while adaptive use may create a new Layout under the same Master. Both export through deterministic `template` mode. Legacy `preserve` remains readable for existing projects only. Raw PPTX plus one-off generated content still routes to `template-fill-pptx`.-**Why each SVG references a layout instead of becoming one.** A generated SVG is a complete slide instance: its actual title, body, pictures, tables, and charts must remain selectable in Normal View. `spec_lock.md` therefore separates `pptx_layouts` (the output PowerPoint layout key/name for every structured page) from `page_layouts` (an input SVG design reference). Confirmed `template_adherence: strict` requires a template SVG for every page and may activate preserved native layouts; `adaptive` permits missing `page_layouts` rows and keeps native export on baseline. Pages reuse one output key only when their static layout layer and placeholder contract match. The exporter reads `pptx_structure.mode` from the lock when no CLI override is present. Within that hierarchy, ownership follows scope rather than paint type: a direct full-canvas solid rect becomes Master `p:bg` when deck-wide, Layout `p:bg` when page-type-specific, and Slide `p:bg` when explicitly marked for that scope or left unmarked in the background plane. This keeps new slides inheriting the right background without putting content or selectable full-canvas rectangles into layouts.+**Why each template SVG stays complete while still compiling to a Layout.** A generated SVG is a complete standalone preview, so it repeats inherited Master/Layout visuals together with its selectable Slide content. `page_layouts` names the input reference and `pptx_layouts` names the output Layout; both exist for every template page. Strict keeps the selected contract, while adaptive may lock a new Layout key under the same Master. Export removes repeated inherited copies and emits real Master/Layout parts, leaving actual content on the Slide.**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer can emit SVG fallback content plus `data-pptx-native` metadata for supported unmerged tables and conservative classic-chart caches. It retains source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts when the current schema can represent them. Exporter-canonical classic charts also recover canonical solid series/slice colors and exact one- or two-paragraph title metadata. The default export still consumes fallback children as regular DrawingML shapes; only `--native-objects` activates editable PowerPoint tables/charts. Unsupported table cases — including merged cells, direct borders, non-solid fills, and mixed rich text — keep the rendered SVG table. Unsupported chart cases — including ChartEx, rotated/flipped/3D/combo charts, unsupported data-label scopes/types, custom axis semantics, trendlines/error bars, unsupported subtype options, sparse or non-finite caches, and date/formatted category axes — keep a baked preview when one exists, otherwise an explicit placeholder. Both carry `data-pptx-native-status`; the quality checker and native-object export report them as fallback-only warnings. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.diff --git a/docs/templates-architecture.md b/docs/templates-architecture.mdindex aa097681..38e8fe5f 100644--- a/docs/templates-architecture.md+++ b/docs/templates-architecture.md@@ -14,6 +14,8 @@| **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 Layout/Deck SVG is a complete preview with explicit `data-pptx-layout`, Master/Layout layers, and semantic placeholders. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. The template guides authoring of a complete generated page SVG; export never reaches back into the template to overlay visible content missing from that generated SVG. Strict use keeps the selected Layout contract; adaptive use may create a new Layout under the same Master. Both export through `pptx_structure.mode: template`; legacy `preserve` remains compatibility-only.+The three are **parallel reference bundles**. The physical directory and the frontmatter `kind` field correspond one-to-one:```yaml@@ -26,12 +28,14 @@ kind: brand# templates/layouts/academic_defense/design_spec.md---kind: layout+native_structure_mode: template...---# templates/decks/招商银行/design_spec.md---kind: deck+native_structure_mode: template...---```@@ -92,6 +96,7 @@ primary_color: "<HEX>"---layout_id: <slug>kind: layout+native_structure_mode: templatesummary: <one-line use cases>canvas_format: <ppt169 | ppt43 | a4 | ...>page_count: <N>@@ -119,6 +124,7 @@ page_types: [<cover, toc, chapter, content, ending, ...>]---deck_id: <slug>kind: deck+native_structure_mode: templatesummary: <one-line use cases>canvas_format: <ppt169 | ...>page_count: <N>diff --git a/docs/templates-guide.md b/docs/templates-guide.mdindex 467b81dc..2e94c97b 100644--- a/docs/templates-guide.md+++ b/docs/templates-guide.md@@ -1,6 +1,6 @@# Templates Guide: Use, Derive, and Boundaries-A PPT Master "template" is a **structure + style** preset bundle: a set of page layout SVGs (cover / chapter / TOC / content / ending and their variants), a `design_spec.md` design specification, and matching assets (logos, backgrounds, decorative imagery). When derived from a structured PPTX it may also carry a native master/layout contract and preserved source package; without that pair it remains a reusable SVG page-skeleton bundle.+A PPT Master "template" is a **structure + style** preset bundle: complete standalone SVG pages whose metadata explicitly identifies Master, Layout, Slide, and placeholders, plus `design_spec.md` and matching assets. Export deterministically reconstructs native PowerPoint structure from those SVGs.This guide answers three questions:@@ -121,7 +121,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, extracts every master/layout and placeholder, and emits both layered SVG references and a paired `native_structure.json` + byte-preserved `source_template.pptx`. When the source structure is reusable, the template package retains the option to bind generated pages to its original layouts; when it is minimal, Template_Designer rebuilds a clean master plus semantic layouts from the layered references. Retention does not force later decks to use the native structure.+**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 uses those facts to rebuild one clean Master plus semantic Layouts as complete, explicitly annotated SVG pages. The original PPTX remains analysis input 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.@@ -140,8 +140,8 @@ 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 from a `.pptx` source — count is driven by the source) / `mirror` (1:1 verbatim copy of every source slide, no abstraction, no placeholders) — `fidelity` and `mirror` both require a `.pptx` reference |-| **Native structure packaging** | `preserve` when the source master/layout graph is reusable; `template` to rebuild one master plus semantic layouts when it is minimal. This decides what capability the library package retains, not how every future deck must use it. `mirror` uses the rebuilt/baseline path because its inherited layers are flattened. |+| **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, placeholder identities, and multi-master status. Output is always rebuilt explicit SVG structure (`template`). || **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 || **Keywords** | 3–5 tags for index lookup || Theme color / design notes / asset list | Optional — can be auto-extracted from the source |@@ -158,15 +158,15 @@ This is the most easily confused decision when deriving a template.|---|---|---|---|| 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 — clusters preserved with cleanup | **Zero** — verbatim copy |-| Placeholders inserted? | Yes (`{{TITLE}}`, `{{CONTENT_AREA}}`, …) | Yes | **No** — Executor edits text in place against the project content |+| 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** |-| Decoration complexity | Usually simpler | Must preserve sprite-sheet (cropped image) structure | Inherits whatever the source had, byte-for-byte |+| 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.-**How mirror is consumed**: a mirror template carries no `{{}}` placeholders, so the Strategist picks one mirror page per project page (using `design_spec.md §V Page Roster` descriptions to match content), and the Executor copies that mirror SVG and edits the text in place against the project content — preserving all decoration, sprite crops, and geometry. The library asset stays 100% verbatim; per-project edits live in `projects/<project>/svg_output/`.+**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 every `data-pptx-*` structure declaration.### Step 4 — Registration and discovery@@ -180,8 +180,8 @@ Registration makes the template **discoverable** — when someone asks "what temWhen a deck/layout template is selected, the Strategist confirmation stage asks how it should be used:-- **adaptive** — use suitable SVG template pages, allow unmatched pages to be designed freely, and keep native export on the normal baseline path-- **strict** — map every generated page to the template roster; when the package carries a compatible native pair, reuse its original Master/Layout/Placeholder structure+- **adaptive** — choose one template SVG per page; when no Layout fits, keep the same Master and create a new explicit Layout+- **strict** — choose one template SVG per page and keep its Master/Layout/Placeholder contract unchanged### What a derived template looks like@@ -200,7 +200,7 @@ skills/ppt-master/templates/layouts/<your_template_id>/`standard` and `fidelity` SVGs use a unified placeholder convention (`{{TITLE}}`, `{{CHAPTER_TITLE}}`, `{{PAGE_TITLE}}`, `{{CONTENT_AREA}}`, ...) that the Strategist phase fills with content.-A `mirror` template emits one SVG per source slide, named by source order, with **no** placeholders inside:+A `mirror` template emits one SVG per source slide, named by source order. It may keep literal example text instead of `{{...}}` markers, but imported native slots still carry semantic metadata:```skills/ppt-master/templates/layouts/<your_template_id>/@@ -230,7 +230,7 @@ Don't confuse the two:Common misconceptions to avoid:-- **A template is not always a Slide Master, but it may carry one.** Ordinary templates remain SVG skeletons. An imported template with `native_structure.json` + `source_template.pptx` retains the original master/layout/theme package as an optional strict-use capability; adaptive use still follows the ordinary SVG + baseline path+- **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 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 goesdiff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 22a2cd20..b7804b30 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -242,7 +242,7 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息**第一步 — 准备参考材料**-**最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取主题色、字体、全部 master/layout、placeholder type/idx 和可复用图片资源。源结构完整时,模板包会把原 package 保留为严格套用时的可选能力;源结构薄弱时,再用 layered SVG 重建一个干净的 master + 语义版式体系。使用该模板生成新 deck 时,Strategist 会确认是 `adaptive`(SVG 模板参考 + 自由页面,baseline 导出)还是 `strict`(每页套用模板 roster,并在兼容时保留原生版式)。+**最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取主题色、字体、全部 Master/Layout、placeholder type/idx 和可复用图片资源,再重建一个干净 Master 与语义 Layout,输出完整且显式分层的 SVG。使用该模板生成新 deck 时,`adaptive` 可在同一 Master 下创建新 Layout,`strict` 保持所选 Layout 契约不变;两者都从 SVG 确定性还原原生结构。没有源 PPTX 时,截图集也能跑(`cover.png` / `toc.png` / `chapter.png` / `content.png` / `closing.png`),但保真度会明显下降。建议优先找原始 PPTX。diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex 015081b4..4c427142 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -53,7 +53,7 @@- **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 的字号上限- **可选 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)) — 策略师确认阶段从纯聊天升级为浏览器可视化页面,Step 4 默认自动拉起:可枚举字段(canvas / mode / visual_style / 条件式模板遵循方式 / 图标 / 图片用法 / 公式与生成策略)从 `catalogs.json` 出常用项、生成型字段摆候选——配色 swatch、字体实时预览(CJK / Latin 各自独立)、AI 图 rendering × palette 候选;并支持自定义 HEX 即时 swatch 反馈、配色 × 字体组合的实时合成预览、canvas 尺寸联动建议正文字号区间。模板遵循方式只在 Step 3 实际加载 Deck/Layout 模板时显示,默认推荐 `adaptive`;`strict` 才进入全页 roster 映射和兼容原生结构保留。与 Step 6 Live Preview **共用 `5050` 端口**(永不同时跑,确认页在 Step 4 末尾自动 `--shutdown` 让出端口;端口被占则自动顺延到下一个空闲口)。原则上**聊天始终是 canonical 通道、确认页只是便利层**:页面写出的 `result.json` 对推荐值具权威性、由下游就地消费(图片计划 / `image_strategy` / 字体 / split 与 refine-spec 开关都从中读取),任何打不开 / 超时 / 无 GUI 的情况都无损回退到聊天总结路径+- **交互式可视化策略师确认页(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)- **内容保真的 PPT 美化 / 重排版上线**([`workflows/beautify-pptx.md`](../../skills/ppt-master/workflows/beautify-pptx.md)) — 与 `template-fill` 互为镜像:template-fill 复用某份 deck 的设计换新内容,beautify 反过来保留内容、重做版面。给一份现成 PPTX,**全部文字逐字保留(不增 / 不删 / 不改写)**,从源 deck 提取并**继承其视觉身份(配色 / 字体,`theme` 或 `observed` 两套候选过确认页)**,只重做版面 / 层级 / 留白;严格 1:1 页数页序,图表 / 表格从抽取数据原生重绘(数据冻结)、源配图重新排布。技术上仍走从零生成原生 PPTX 管线(`ppt_to_md` 抽内容 → 主管线 → 全新 deck),不补丁原文件,因此不碰 Non-goals #53。新增 `beautify_identity.py` / `beautify_inventory.py`,confirm 页全字段按源 seed 后用户复核。v1 天花板(诚实标注):不缓解信息过载(挤页只在页内改,真要重排分页属主管线)、不保证坐标级 paste-back、combo / dual-axis / waterfall 图丢未捕获的绘图层@@ -82,7 +82,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 对象回转** — 原生导出保留真实 master/layout 关系,默认 baseline 只提升安全的共享背景/chrome。SVG 生成完成后,baseline 根据文件名中的明确角色分配 Cover/Agenda/Section/Closing/Content 版式,并且只提升家族内完全一致的背景;实际内容继续留在 Slide,不推断占位符。锁定的 `template` 模式把显式 SVG master/layout layer 与有类型的 placeholder 编译成可复用版式,不做视觉推断;通过 `create-template` 导入的可复用 PPTX 会把原生结构对保留为可选能力。Strategist 进一步确认模板遵循方式:`strict` 可锁定 `preserve`,保留原 master/layout/theme 清单(包括多母版)、把每页绑定到精确源版式并恢复源 placeholder idx;`adaptive` 则把 SVG roster 作为可选参考并继续走 baseline。原始 PPTX 的一次性直接填充继续走 `template-fill-pptx`。导入器也会为受支持的未合并表格与 classic-chart cache 输出 fallback SVG 加原生元数据;无法等价表达的语义保持明确的 fallback-only marker+- **原生 package 结构 + 保守 PPTX 对象回转** — 自由设计的 baseline 只提升安全共享背景/chrome,分配文件名页型 Layout,并可进一步提升家族内完全一致的前置 chrome,不推断 placeholder。模板路线则确定性编译完整 SVG 中显式声明的 Master/Layout/placeholder。`create-template` 只把源结构当分析输入并统一重建显式 SVG;`strict` 保持所选 Layout,`adaptive` 可在同一 Master 下新建 Layout。旧 `preserve` 仅保留兼容读取。---@@ -116,7 +116,7 @@ PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围**基础诉求其实很简单**:如果只是「固定位置替换 Excel 数据到 PPT 模板」,直接让 AI 写一段 `python-pptx` 脚本即可,几行代码搞定,不需要本项目这套管线。-> **已支持边界**:`template-fill-pptx` 直接回填选中的源页面;`create-template` 先把结构完整的源文件收敛成经过确认的 SVG 模板,并可保留原生契约。下游严格套用时才激活 `preserve` 引用精确源版式,适应性使用仍走 baseline。仍不做的是未经审查、没有契约的任意第三方 placeholder 全自动文字替换。+> **已支持边界**:`template-fill-pptx` 直接回填选中的源页面;`create-template` 把源 Master/Layout 事实收敛成经过确认、完整且显式分层的 SVG 模板。下游严格与适应性使用都从 SVG 契约还原原生结构。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。### 改用原生 PowerPoint 图表(Excel-native chart)diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex e4745fc5..89322cd3 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -55,7 +55,20 @@└── svg_output/ ← Executor 原始 SVG 备份(重跑 finalize_svg → svg_to_pptx 即可重建 pptx)```-以下直接 PPTX 工作流会有意绕过这条 SVG 路线:+### SVG 是页面设计语言++凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。++| 领域 | 权威来源 |+|---|---|+| SVG 创作路线中的可见页面内容与布局 | `svg_output/` 中的最终页面 SVG |+| Master/Layout/Slide 打包与原生对象映射 | SVG 到 PPTX 的翻译;可以重组 SVG 已表达的内容,但不能创造新的可见内容 |+| 动画、转场、讲稿和旁白 | 各自的 sidecar / 资源与 PPTX package 后处理 |+| 直接原生 PPTX 编辑 | 所选原生工作流自己的 PPTX / OOXML 契约 |++这是一条“页面设计闭包”规则,不代表 SVG 要描述完整 PPTX package。相关验收是:完成的页面 SVG 能重建对应幻灯片的可见设计;不要求仅凭 SVG 重建讲稿、音频、计时、relationships 或直接原生编辑结果。++以下直接 PPTX 工作流会有意绕过 SVG 创作路线,并继续保持独立:| 工作流 | 输入角色 | 输出机制 | 为什么独立 ||---|---|---|---|@@ -267,7 +280,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式(不准即兴、不准漏属性)。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。-**策略师确认阶段是唯一的阻塞 gate。** Strategist 阶段以一个三阶段确认 gate 作为核心阻塞决策点:第一阶段确认方向锚点(画布、受众、改写幅度、交付目的、mode、visual style,以及只在 Step 3 加载 Deck/Layout 模板时出现的模板遵循方式);第二阶段基于已确认锚点重新推导并确认设计系统(页数、调色板、字体、图标、公式策略);第三阶段基于已确认设计系统重新推导并确认图片与执行方式(图片来源、生成图风格、AI 图片路径、生成模式、refine-spec)。模板遵循默认推荐 `adaptive`,`strict` 是全页 roster 映射与兼容原生结构保留的显式路径。最终的 `confirm_ui/result.json` 是权威输入——用户改过的字段必须进入 `design_spec.md` 和 `spec_lock.md`,不能回退到 AI 的原始推荐。+**策略师确认阶段是唯一的阻塞 gate。** Strategist 阶段以一个三阶段确认 gate 作为核心阻塞决策点:第一阶段确认方向锚点(画布、受众、改写幅度、交付目的、mode、visual style,以及只在 Step 3 加载 Deck/Layout 模板时出现的模板遵循方式);第二阶段基于已确认锚点重新推导并确认设计系统(页数、调色板、字体、图标、公式策略);第三阶段基于已确认设计系统重新推导并确认图片与执行方式(图片来源、生成图风格、AI 图片路径、生成模式、refine-spec)。模板遵循默认推荐 `adaptive`:每页仍引用模板架构,但无匹配构图时可在同一 Master 下创建新 Layout;`strict` 则保持所选 Layout 契约不变。最终的 `confirm_ui/result.json` 是权威输入。**图片分析走重算元数据,不读像素。** 当项目里存在图片时,Strategist 和 Executor 使用 `analyze_images.py` 的输出(`analysis/image_analysis.csv`),而不是直接打开图片文件。这个 CSV 是基于当前 `images/` 目录重算出来的视图,不是持久缓存。每次做图片敏感决策前重跑分析,就是它的防陈旧策略:用户图、抽取图、网络图、AI 图、公式图和切片图最终都会汇入同一张可度量事实表。@@ -427,13 +440,13 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份**为什么兼容 fallback 属于 SVG snapshot 路径,而不是 native shapes。** Native PPTX 导出会把受支持的 SVG 元素翻译成 DrawingML 形状,并在 native-shapes 模式下显式关闭 PNG+SVG 兼容模式。PNG fallback 只在 legacy SVG-image 路径(`--svg-snapshot` / `--only legacy`)且本地 renderer 可用时使用,因为那条路径嵌入的是旧版 Office 可能无法显示的 SVG media。因此,旧版兼容是一份可选 snapshot 交付物,不是捆在主 editable native deck 里的兜底层。-**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 会从基础 package 中空白版式的真实关系开始构建,并默认使用 `--pptx-structure baseline`。Baseline 只提升低风险共享结构:严格多数页面完全一致的页面背景(每页都必须携带显式背景,少数派页面保留自己的背景并覆盖母版填充),以及位于 shape 序列开头(视觉后层)、且 id 精确 token 为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的重复 SVG chrome。Chrome 还必须在共享同一母版的严格多数页面上生成完全一致的 OOXML、没有被页面动画引用,并保持相同的前置 z-order;覆盖在正文之上的 chrome 继续留在 slide 本地。少数派页面(封面、章节页)的全部元素保持 slide-local,并被改绑到生成的 `Cover` 版式(`showMasterSp="0"`)——遵循 PowerPoint 的惯例:页型差异用同一母版下的版式表达而不是增加母版,因此被提升的母版 chrome 绝不会泄漏到这些页面上。全部页面生成完成后,导出器只根据文件名中的明确角色 token 分配 `Cover`、`Agenda`、`Section`、`Closing` 或兜底 `Content`;它保留当前版式的母版图形可见性,不比较页面视觉、不猜占位符,只有某一家族的每页都携带完全相同的显式 `p:bg` 时才把该背景提升到 Layout,实际页面内容始终留在 Slide。被提升 chrome 的图片关系会复制到 slide master,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉;`pageNumber`/`slideNumber` chrome 的文本若恰好等于该页应显示的页码(尊重 `firstSlideNum`),会转换为自动更新的 PowerPoint 页码字段,此后在 PowerPoint 中调整页序页码自动重算,其他编号方案保持字面文本不动。这样普通 deck 能获得实用的 master/layout 清单,同时不限制 SVG 创作,也不消耗模型上下文预先规划版式。+**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 默认使用 `--pptx-structure baseline`。它只提升低风险共享结构:严格多数页面完全一致的背景,以及 id 明确标记为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的共同前置 chrome。提升还要求 OOXML 完全一致、无动画引用且 z-order 安全;少数派页面继续使用隐藏母版图形的 `Cover` 版式。导出后处理再按文件名分配 `Cover`、`Agenda`、`Section`、`Closing` 或 `Content`,并把一家族所有页面完全一致的背景与前置 chrome 提升到该 Layout。它不做视觉相似度比较、不猜占位符,实际内容始终留在 Slide。**为什么可复用版式必须依赖显式 SVG 元数据。** `--pptx-structure template` 是生成型 deck 需要继续作为 PowerPoint 模板复用时的 opt-in 路径。最终 slide SVG 在根节点声明 layout key,只允许根节点的直接子元素标记 master/layout layer,并在应成为版式占位框的 slide-local 原型上附加类型语义。导出器会验证共享 master 与同 key layout 的声明在结构和视觉上完全一致,再生成真实 layout part 与 `p:ph` 引用;所有未标记对象仍保持 slide-local。这是确定性的结构编译,不是根据视觉相似度猜模板。-**为什么导入的可复用模板应保留原生结构但不强制使用。** `pptx_template_import.py` 会配对输出 `native_structure.json` 与 `source_template.pptx`。当源 master/layout 图谱可复用时,`create-template` 可以在照常创建 SVG 模板 roster 的同时保留这对文件。后续 Strategist 确认模板遵循方式:`strict` 可以启用 `pptx_structure.mode: preserve`,以源 package 为底包,把每个生成页绑定到精确的源 layout part,移除 SVG 中仅用于预览的继承层副本,并恢复源 placeholder 的 type/idx 身份;`adaptive` 则把模板 SVG 当作可选参考,原生导出仍走 baseline。只有严格 preserve 路径会把源文件已有的多母版和未被示例页引用的版式继续保留在 PowerPoint 的版式选择器中。原始 PPTX 加一次性新内容仍走 `template-fill-pptx`;preserve 模式只从完成封装的可复用模板包开始。+**为什么可复用模板统一重建显式 SVG 结构。** `pptx_template_import.py` 输出分层的 Master/Layout/Slide 参考和源结构事实;`create-template` 据此重建一个干净 Master 与语义 Layout,并把它们重复标注在可独立预览的完整 SVG 中,不再封装原 PPTX。严格套用保持所选 Layout 契约,自适应使用可在同一 Master 下新建显式 Layout;两者都走确定性的 `template` 导出。`preserve` 只为旧项目保留兼容读取。-**为什么每个 SVG 应引用版式,而不是直接变成版式。** 生成 SVG 是完整的 slide 实例;其中真实标题、正文、图片、表格和图表必须继续能在普通视图中选择。`spec_lock.md` 因而把 `pptx_layouts`(结构化页面最终引用的 PowerPoint layout key/name)与 `page_layouts`(输入 SVG 设计参考)分开。确认 `template_adherence: strict` 时,每页都必须选择一个模板 SVG,并可进一步启用原生版式保留;确认 `adaptive` 时,允许省略 `page_layouts` 让页面自由设计,原生导出继续走 baseline。只有静态 layout layer 与 placeholder contract 相同的页面才复用同一个输出 key。没有 CLI 覆盖时,导出器会读取 lock 中的 `pptx_structure.mode`。在这个继承层级里,归属由复用范围而不是填充类型决定:全画布纯色矩形在全 deck 共享时成为 Master `p:bg`,页型共享时成为 Layout `p:bg`,显式标记为 slide 或位于背景层但未标记时成为 Slide `p:bg`。这样新增页面能继承正确背景,同时不会把实际内容或可选中的全屏矩形塞进版式。+**为什么模板 SVG 保持完整却仍能编译成版式。** 每张生成 SVG 都是可独立预览的完整 slide,因此会重复携带继承的 Master/Layout 视觉和可选择的 Slide 内容。`page_layouts` 指定输入参考,`pptx_layouts` 指定输出版式,两者在模板路线中逐页齐全。严格模式保持所选契约;自适应模式可在同一 Master 下锁定新 Layout。导出器移除重复继承层并生成真实 Master/Layout,实际内容仍留在 Slide。**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据;当现有 schema 能表达时,还会保留源表格样式继承、受支持的单元格纯色填充 / 基础文字格式,以及图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关。由本 exporter 生成的规范 classic chart 还会回读规范纯色系列 / 切片,以及精确的单段或双段标题元数据。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留实际渲染的 SVG table。ChartEx、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持的图表场景,则在有 baked preview 时保留预览,否则给出明确占位符。两类对象都会写入 `data-pptx-native-status`;质量检查器和 native-object 导出将其报告为 fallback-only warning。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.mdindex a86e27fa..c1044d76 100644--- a/docs/zh/templates-architecture.md+++ b/docs/zh/templates-architecture.md@@ -14,7 +14,7 @@| **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 分支,默认)|-从结构完整的 PPTX 导入的 Layout/Deck 可以额外携带一对原生结构文件:`native_structure.json` 记录稳定 master/layout key、版式显示名称、父母版和 placeholder type/idx;`source_template.pptx` 保存原 package。两者必须同时存在且 SHA-256 匹配。这是一项模板包能力,不是自动路由:下游 Strategist 确认 `strict` 时可用 `pptx_structure.mode: preserve` 复用源 master/layout/theme;确认 `adaptive` 时仍按 SVG 模板参考 + `baseline` 自由生成。没有这对文件时继续使用现有 `baseline` 或显式 `template` 重建。+Layout/Deck 的每张 SVG 都是完整预览,同时显式声明 `data-pptx-layout`、Master/Layout 层和语义 placeholder。PPTX 导入产生的 `native_structure.json` 与 `source_template.pptx` 只用于分析源结构,不进入新模板包。模板负责指导生成完整的页面 SVG;导出时不得再回读模板,向生成 SVG 叠加其中缺失的可见内容。下游 `strict` 保持所选 Layout 契约,`adaptive` 可在同一 Master 下创建新 Layout;两者都使用 `pptx_structure.mode: template`。旧 `preserve` 契约仅保留兼容读取。三者是**三种并列的 reference bundle**,物理目录与 frontmatter `kind` 字段双向对齐:@@ -30,12 +30,14 @@ kind: brand# templates/layouts/academic_defense/design_spec.md---kind: layout+native_structure_mode: template...---# templates/decks/招商银行/design_spec.md---kind: deck+native_structure_mode: template...---```@@ -96,6 +98,7 @@ primary_color: "<HEX>"---layout_id: <slug>kind: layout+native_structure_mode: templatesummary: <一句话描述用途>canvas_format: <ppt169 | ppt43 | a4 | ...>page_count: <N>@@ -123,6 +126,7 @@ page_types: [<cover, toc, chapter, content, ending, ...>]---deck_id: <slug>kind: deck+native_structure_mode: templatesummary: <一句话描述用途>canvas_format: <ppt169 | ...>page_count: <N>diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex 9314670d..60bc71f9 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -1,6 +1,6 @@# 模板指南:选用、派生与边界-PPT Master 的"模板"是一份**结构 + 风格**的预设包:包含若干页面布局 SVG(封面/章节/目录/内容/结尾及其变体)、`design_spec.md` 设计规范,以及配套素材(logo、背景、装饰图)。从结构完整的 PPTX 导入时,它还可以携带原生 master/layout 契约和源模板 package;没有这对文件时,它仍是由工作流复用的 SVG 页面骨架。+PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG 都能独立完整预览,并用 metadata 显式标出 Master、Layout、Slide 与 placeholder;同时包含 `design_spec.md` 和配套素材。导出器据此确定性还原 PowerPoint 原生结构。本文回答三个问题:@@ -121,7 +121,7 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目### 第一步:准备参考材料-**强烈推荐:直接给原始 `.pptx` 文件。** 当前的 PPTX 导入管线会用 [`pptx_template_import.py`](../../skills/ppt-master/scripts/pptx_template_import.py) 直接读取 OOXML,提取主题色、字体、全部 master/layout、placeholder 元数据和可复用图片资源,同时输出 `native_structure.json` 与字节保留的 `source_template.pptx`。结构完整时,模板包会保留后续生成页直接引用原版式的能力;结构薄弱时,Template_Designer 才会基于 layered `svg/` 重建干净的 master/layout 规范。保留原生结构不等于强制未来每份 deck 都使用它。+**强烈推荐:直接给原始 `.pptx` 文件。** 导入器会读取 OOXML,提取全部 Master、Layout、placeholder、主题与可复用素材,并生成分层分析参考。Template_Designer 据此重建一个干净 Master 与语义 Layout,输出完整且显式分层的 SVG;原 PPTX 只作分析输入,不进入新模板包。也可以基于品牌指南从零设计:提供 logo、主色 HEX、字体、调性描述、几张氛围参考图,AI 会现场设计页面骨架。适合品牌方还没有成型 PPT、只有 VI 手册的场景。@@ -140,8 +140,8 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目| **调性概要** | 一句话,如"现代克制、数据驱动" || **主题模式** | 浅色 / 深色 / 渐变…… || **画布格式** | 默认 `ppt169`(16:9),其他格式需提前指定 |-| **复刻模式** | `standard`(默认 5 页基本套)/ `fidelity`(按 PPTX 源里"视觉上真正不同"的版式簇各开一个变体——数量由源决定)/ `mirror`(每张源页 1:1 原样复制,零抽象、不插占位符)—— `fidelity` 和 `mirror` 都必须有 `.pptx` 源 |-| **原生结构封装策略** | 有完整 master/layout 时推荐 `preserve`(保留原 package);结构薄弱时用 `template`(重建一个 master + 语义版式)。它决定模板库资产保留什么能力,不决定未来每份 deck 必须怎样使用。`mirror` 因为继承层已展平,只走重建/基线路线。 |+| **复刻模式** | `standard`(默认 5 页基本套)/ `fidelity`(按视觉版式簇生成变体)/ `mirror`(逐页保持原视觉,同时补齐显式层级归属) |+| **原生结构事实** | 简报会列出源 Master/Layout 数量、placeholder 身份和多母版情况;最终一律重建显式 SVG 结构(`template`)。 || **保真级别** | (`standard` / `fidelity` 有源时必填)`literal`(按原样复刻几何/装饰/精灵图裁剪)/ `adapted`(借结构和调性、允许设计演化)。封面 / 章节 / 结尾通常用 `literal`。**`mirror` 模式不询问**——隐含 literal || **关键词** | 3–5 个标签,用于索引检索 || 主题色 / 设计风格 / 素材清单 | 可选,可让 AI 从源里自动提取 |@@ -158,15 +158,15 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目|---|---|---|---|| 输出页数 | 5 页(封面/章节/目录/内容/结尾) | 视觉上真正不同的版式簇各一个变体——数量由源决定 | 每张源页 1:1 一页 || 抽象程度 | 高 —— 干净可复用骨架 | 中 —— 聚类后清理 | **零** —— 原样复制 |-| 是否插占位符 | 是(`{{TITLE}}`、`{{CONTENT_AREA}}` 等) | 是 | **否** —— Executor 直接在 SVG 里就地编辑文字 |+| 作者占位符 | 是(`{{TITLE}}`、`{{CONTENT_AREA}}` 等) | 是 | 可保留原文字,但导入识别出的原生内容槽仍带语义 metadata || 适合场景 | 你只需要"调性 + 基本骨架",未来用模板生成全新 deck | 源 PPTX 本身就是高度定制的版式库 | 别人的精装 deck 直接好用、想把每页都当参考页 || 典型例子 | 给品牌做基础模板 | 复刻一套政府汇报的 20 种章节版式 | 把一份 50 页的麦肯锡风格 deck 整套用作模板 || 必须有 PPTX 源吗 | 否 | **是** | **是** |-| 装饰复杂度 | 通常较简洁 | 需要保留精灵图(sprite sheet)裁剪等结构 | 源页啥样就啥样,逐字节继承 |+| 装饰复杂度 | 通常较简洁 | 需要保留精灵图裁剪等结构 | 保留原几何,并补齐显式层级归属 |**关于精灵图**:PPTX 导出的素材常常是**一张大图 + 多页通过 viewBox 裁剪不同区域**。`fidelity` 和 `mirror` 模式下必须保留这层嵌套 `<svg viewBox=...>` 包装,不能扁平化为单张 `<image>`——否则裁剪信息丢失,画面会错位。工作流会自动校验这一点。-**`mirror` 模板怎么消费**:mirror 模板里没有 `{{}}` 占位符——Strategist 根据 `design_spec.md §V Page Roster` 的逐页描述为每个项目页选一张参考页,Executor 把那张参考 SVG 拷过去,**仅在原位修改文字内容**,所有装饰、精灵图裁剪、几何坐标全部保留。库资产保持 100% 原样;针对项目的修改只存在于 `projects/<project>/svg_output/`。+**`mirror` 模板怎么消费**:Strategist 为每个项目页选择一张 mirror 参考,Executor 复制完整 SVG 并原位修改可见文字,同时保留装饰、精灵图裁剪、几何坐标和全部 `data-pptx-*` 结构声明。### 第四步:注册与发现@@ -180,8 +180,8 @@ AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目选择 Deck/Layout 模板后,Strategist 确认阶段会进一步询问模板的使用方式:-- **适应性使用(adaptive)**——只使用适合的 SVG 模板页,不适配的页面允许自由设计,原生导出继续走普通 baseline-- **严格套用(strict)**——每一页都映射到模板 roster;模板携带兼容原生结构时,复用原始 Master/Layout/Placeholder+- **适应性使用(adaptive)**——每页都选择一张模板 SVG;没有合适 Layout 时沿用同一 Master 创建新的显式 Layout+- **严格套用(strict)**——每页都选择一张模板 SVG,并保持其 Master/Layout/Placeholder 契约不变### 派生后的目录长什么样@@ -200,7 +200,7 @@ skills/ppt-master/templates/layouts/<your_template_id>/`standard` 和 `fidelity` 模式下的页面 SVG 里使用统一的占位符约定(`{{TITLE}}`、`{{CHAPTER_TITLE}}`、`{{PAGE_TITLE}}`、`{{CONTENT_AREA}}` 等),策略师阶段会按内容填充。-`mirror` 模板按源页序号每页一张 SVG,**SVG 内部没有占位符**:+`mirror` 模板按源页序号每页一张 SVG。它可以保留原示例文字而不写 `{{...}}`,但导入识别出的原生内容槽仍带语义 metadata:```skills/ppt-master/templates/layouts/<your_template_id>/@@ -230,7 +230,7 @@ skills/ppt-master/templates/layouts/<your_template_id>/避免常见误解:-- **模板不一定等于母版,但可以携带母版**。普通模板仍以 SVG 骨架为主;带 `native_structure.json` + `source_template.pptx` 的导入模板会把原 master/layout/theme 保留为严格套用时的可选能力,适应性使用仍走普通 SVG + baseline 路径+- **可复用模板是一份完整 SVG 重建契约,不是源 PPTX package**。每页可独立预览,显式 metadata 负责在导出时还原 Master/Layout/Slide- **模板不是"风格皮肤"**。它包含结构(页面有几块、信息层级如何分布)+ 风格(配色、字体、装饰),两者不可分割。试图只换"皮肤"不换结构,往往会让信息架构和视觉打架- **模板不会替你做内容决策**。策略师仍然会按内容判断每页用哪个版式、要不要扩展为变体,模板提供候选,不预设结果- **`fidelity` 模式不等于像素级搬运**。即便是 `literal` 保真,AI 仍会把杂质和不必要的重复结构清理掉——载体保留几何,但不照抄冗余diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex f4480fd5..9a8a3af1 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -13,6 +13,17 @@ description: >**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export`+### SVG Page-Design Boundary++| Scope | Contract |+|---|---|+| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. |+| Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. |+| SVG-to-PPTX export | Translation only: map SVG content to DrawingML/native objects and reorganize represented content into Master/Layout/Slide structure without inventing new visible page content. |+| Direct PPTX and presentation-behavior workflows | Remain separate. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |++**MUST — page-design closure**: For an SVG-authoring route, inspect the final page SVG to determine what the exported slide looks like. Do not reinterpret “SVG is the page-design language” as “SVG is the complete PPTX package description language.”+> [!CAUTION]> ## 🚨 Global Execution Discipline (MANDATORY)>@@ -25,7 +36,7 @@ description: >> 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)> 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN> 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN-> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the confirmed `pptx_structure.template_adherence` when present, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (which template SVG to inherit, if any), `page_charts` (which chart template to adapt, if any), and — when `pptx_structure.mode` is `template` or `preserve` — `pptx_layouts` (which native PowerPoint layout the page references). Empty / absent `page_layouts` rows are intentional only for adaptive/free design; strict template use requires one per page — see executor-base.md §2.1. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default+> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the confirmed `pptx_structure.template_adherence` when present, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (which template SVG to inherit), `page_charts` (which chart template to adapt, if any), and — when `pptx_structure.mode` is `template` or `preserve` — `pptx_layouts` (which native PowerPoint layout the page references). Deck/layout template routes require both mappings for every page: `strict` reuses the selected layout contract; `adaptive` may create a new explicit layout contract from the selected reference. Empty / absent `page_layouts` rows are reserved for free design and brand-only routes — see executor-base.md §2.1. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default> 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce> 10. **FOLLOW DETERMINISTIC ROUTING RULES** — Do not add blocking routing questions when this skill defines a route. If the user request violates a route precondition, state the required prerequisite and stop that route instead of asking the user to choose around the rule. Ordinary finite options, stylistic preferences, and recoverable details are surfaced with a recommended value plus alternatives at the next existing confirmation gate.@@ -263,9 +274,9 @@ find <project_path>/templates -type f \( -iname '*.png' -o -iname '*.jpg' -o -inThe same split applies to all three kinds — bitmaps always land in `images/`, the rest in `templates/`. The spec's `kind` field tells Strategist how to read the `templates/` side; downstream code doesn't distinguish. (Template SVGs in `templates/` are reference material only — the rendered pages live in `svg_output/` and reference images via `../images/`.)-If the selected structure owner ships `native_structure.json` + `source_template.pptx`, keep the pair together in `<project>/templates/`. During fusion, only the winning **structure segment** may contribute this pair: a layout override without a native pair removes a deck's pair, while a brand-only identity override leaves it intact. Never mix one template's contract with another template's source package.+Legacy template packages may ship `native_structure.json` + `source_template.pptx`; keep the pair together in `<project>/templates/` for backward-compatible `preserve` export. Current `create-template` output does not package this pair: it rebuilds complete, explicitly layered SVG templates instead. During fusion, never mix one legacy contract with another template's source package.-The pair is retained capability, not an automatic generation route. The Strategist confirmation stage decides whether the selected template is used `strict` (every page follows the SVG roster; compatible native structure may use `preserve`) or `adaptive` (template SVGs are optional page references; native export stays `baseline`). Its mere presence must never force `preserve`.+The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. Both use `pptx_structure.mode: template` for current templates and map every page to one reference SVG plus one output PowerPoint layout. `strict` keeps the referenced layout contract unchanged; `adaptive` may create a new layout key while keeping the template Master contract. Legacy `preserve` remains strict-only compatibility behavior.#### Multi-path fusion@@ -582,13 +593,15 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).-**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups and the optional `pptx_structure` / `pptx_layouts` native-layout contract. Resists context-compression drift on long decks. See executor-base.md §2.1.+**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups and the route-specific `pptx_structure` / `pptx_layouts` native-layout contract. The contract is absent only on legacy/free inputs that have not yet been normalized; it is mandatory for every current template page. Resists context-compression drift on long decks. See executor-base.md §2.1.> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`+Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities.+**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE annotation handling and speaker notes:```bashpython3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>@@ -703,7 +716,10 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> Master chrome. It does not inspect visual similarity or infer placeholders,> and all actual page content remains slide-local. When every slide in one> family carries the exact same explicit background, that background moves to-> the family layout. This is+> the family layout. The same family may also promote an identical leading+> prefix of explicitly named chrome when every family member carries the same+> generated OOXML, relationships are safe, no timing targets it, and z-order is+> preserved. This is> an export-only package pass: SVG authoring, live preview, and model context are> unchanged. Baseline also prunes base-template slide layouts no generated slide> references, so the PowerPoint new-slide picker only offers layouts that belong@@ -723,7 +739,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> `--pptx-structure flat` only for debugging/comparison when all generated> backgrounds and chrome must remain slide-local and fonts must stay concrete.-> **Preserved source-template export** — a reusable template package created+> **Legacy preserved source-template export** — an existing template package> from a structured PPTX may ship `native_structure.json` plus> `source_template.pptx`. This pair records a reusable capability; it does not> select the downstream route by itself. Only a confirmed@@ -737,16 +753,13 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> original placeholder type/index. Preserve mode keeps the source layout picker> roster; it does not prune unused source layouts.>-> A confirmed `template_adherence: adaptive` deck continues to use the created-> template SVG roster as optional visual/layout references and exports through-> `baseline`, even when the template directory contains the native pair. Pages-> without a `page_layouts` row remain free design; the baseline post-pass owns-> conservative Master/background/chrome extraction plus filename-backed Layout-> family assignment exactly as it does without a template.--> **Explicit reusable template export** — set `spec_lock.md`-> `pptx_structure.mode: template` (or pass `--pptx-structure template`-> explicitly) only when every SVG root declares `data-pptx-layout` and direct children+> Current template creation no longer emits this pair. `preserve` is retained+> only so existing template packages and projects remain exportable; do not+> select it for newly created templates.++> **Explicit reusable template export** — deck/layout template routes set+> `spec_lock.md` `pptx_structure.mode: template`. Every SVG root declares+> `data-pptx-layout`, and direct children> explicitly declare master/layout layers, an optional Slide background, or> PowerPoint placeholders. This> mode builds named reusable layouts and placeholder mappings; it does not@@ -756,8 +769,10 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> example live in> [`references/shared-standards.md`](references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).> Raw PPTX templates still route to `template-fill-pptx`; `template` structure-> mode is for explicitly annotated SVG authoring. Source-package preservation is-> available only after `create-template` has produced the reusable native pair.+> mode is for explicitly annotated SVG authoring. Both `strict` and `adaptive`+> template use stay on this deterministic route. Adaptive pages may define new+> layout keys, but they repeat the same Master layer and one internally+> consistent Layout/placeholder contract.> In template mode, `pptx_layouts` contains exactly one locked> layout key/name per page; reuse a key for a shared structure instead of> creating one key per content instance.diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex f3d7e84e..c7d31820 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -24,7 +24,7 @@ Global artifact ownership rules for PPT Master projects.| `templates/` | Project template reference | Step 3 imported specs, template SVGs, and non-image assets | Strategist/Executor read only when Step 3 is triggered || `confirm_ui/recommendations.json` | Confirmation proposal | Strategist-authored confirmation payload | Confirm UI reads; rewritten between Stage 1, Stage 2, and Stage 3 || `confirm_ui/result.json` | Confirmation result | User-confirmed values | Strategist treats final result as authoritative over recommendations |-| `svg_output/` | Author source | Main-agent handwritten SVG pages | Quality checker and native PPTX export read this as canonical page source |+| `svg_output/` | Page-design author source | Main-agent handwritten SVG pages containing the complete visible design | Quality checker and native PPTX export read this as the canonical visual/page-layout source; templates and locks do not add missing visible objects at export || `notes/total.md` | Speaker-note source | Complete notes before splitting | Step 6 writes; Step 7.1 splits || `notes/slide_*.md` | Split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` || `svg_final/` | Derived preview/export SVGs | Self-contained post-processed SVGs | Rebuild from `svg_output/` with `finalize_svg.py` |@@ -44,6 +44,8 @@ Global artifact ownership rules for PPT Master projects.| Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. || Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. || SVG source | `svg_output/` is the only author source for generated pages. |+| Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. |+| Package-behavior separation | Speaker notes, animations, transitions, narration, and direct native-PPTX workflows keep their owning artifacts; do not force them into SVG metadata. || Post-processed SVG | `svg_final/` is disposable and must be rebuildable from `svg_output/`. || Export source | Native PPTX export reads `svg_output/` by default. SVG snapshot export reads `svg_final/` only when requested. || Confirmation | Final `confirm_ui/result.json` or chat confirmation overrides recommendations. |diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 94fedae1..53a48ea6 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -2,6 +2,10 @@> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). Technical constraints are in shared-standards.md.+**Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content.++> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.+---## 1. Template Adherence Rules@@ -13,7 +17,7 @@| Source list | Read path ||---|---|| Chosen template's `design_spec.md` (read frontmatter to detect `replication_mode`) | `templates/design_spec.md` |-| Preserve-mode native layout/placeholder contract | `templates/native_structure.json` |+| Legacy preserve-mode native layout/placeholder contract, when present | `templates/native_structure.json` || Every distinct `<basename>` in `spec_lock.md page_layouts` | `templates/<basename>.svg` || Every distinct chart name in `spec_lock.md page_charts` | `templates/charts/<chart_name>.svg` || Chart types in `design_spec.md §VII` not covered above | `templates/charts/<chart_name>.svg` |@@ -34,9 +38,9 @@ Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative1. **Mirror-mode template** (template's `design_spec.md` frontmatter has `replication_mode: mirror`) → see §1.1 below. The page is consumed as a **visual reference**, not as a placeholder shell.2. `spec_lock.md page_layouts` has `P<NN>: <basename>` for this page → inherit the structure of `templates/<basename>.svg` (already in context from §1.0).-3. `page_layouts` exists but **no entry** for this page → **free design**, no template inheritance.-4. `page_layouts` section absent (legacy deck) **and** `templates/` directory exists → fall back to the page-type table below, matching by SVG filename keyword (cover/chapter/content/ending/toc). Read the matched file at first use if §1.0 batch did not cover it.-5. No template at all → free design.+3. `pptx_structure.mode: template` but this page has no `page_layouts` entry → stop; the template contract is incomplete. Adaptive mode must still select a reference SVG.+4. `page_layouts` section absent in a legacy project and `templates/` exists → fall back to the page-type table below, matching by SVG filename keyword. Read the matched file at first use if §1.0 did not cover it.+5. No deck/layout template at all → free design.> Note: `page_layouts` disambiguates the multiple content variants modern templates ship (e.g., `graduation_defense` has 8); the legacy table cannot.@@ -59,14 +63,14 @@ Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritativeWhen the project's chosen template is a `mirror` template (`design_spec.md` frontmatter declares `replication_mode: mirror`), Executor switches to a **reference-style** consumption path that bypasses placeholder substitution:1. **Per-page reference selection** — Strategist selects one mirror page per project page via `spec_lock.md page_layouts` (e.g., `P04: 015_content`). The basename is the mirror filename without extension; Strategist made this choice by reading `design_spec.md §V Page Roster` descriptions, not by guessing.-2. **Copy, don't fill** — open the referenced mirror SVG (already in context from §1.0). **Copy it as the starting point for the project page**, then edit text elements in place to express the project's content for `P<NN>`. Preserve every non-text element verbatim: backgrounds, decorative shapes, sprite-cropped images, charts, icon usage, color values, font families, geometry, sprite `<svg viewBox>` wrappers, and **which image** each `<image>` points at.+2. **Copy, don't fill** — open the referenced mirror SVG (already in context from §1.0). Copy it as the starting point, then edit slide-specific text in place. Preserve every non-text element and every `data-pptx-*` structure attribute verbatim unless adaptive mode intentionally assigns a new Layout contract.3. **What you may edit** — the visible text content of `<text>` / `<tspan>` elements that express slide-specific content (title, body, captions, KPI labels, dates, page numbers). Replace the source deck's example text with the project's text for this page from `design_spec.md §IX` and `notes/<NN>_*.md`.4. **What you must not touch** — element positions, sizes, fonts, colors, fills, strokes, gradients, **which image each `<image>` points at**, `<g>` grouping, sprite-sheet `<svg viewBox>` wrappers, decorative `<rect>` / `<path>` / `<circle>` / `<polygon>` shapes, `<use data-icon="...">` markers, embedded chart data structures. Mirror's value is preserving the source deck's visual identity — any geometric / decorative drift defeats the purpose. **The `href` path is not the image**: normalizing a bare `href="cover_bg.png"` to `href="../images/<name>"` (when Step 3 relocated the asset to `images/`) points at the *same* image and changes nothing visual — that is an allowed path fix, not a fidelity edit. Leaving the bare href as-is is also fine; the exporter and live preview resolve bare hrefs against `images/` either way.5. **Content fit** — the mirror page was chosen by Strategist because its layout matches the content slot. If the project's content for `P<NN>` legitimately needs more / fewer items than the mirror page provides (e.g. mirror shows 3 KPI cards, project has 4 metrics), keep the mirror page's visual rhythm and either drop one metric to fit or split across two pages — do **not** restructure the mirror page's grid. If neither works, surface a `warning: P<NN> content does not fit mirror reference <basename>; suggest different reference page` and proceed with the closest-fit edit.-6. **No `{{}}` substitution** — mirror SVGs do not contain placeholder markers. Do not search for `{{TITLE}}` / `{{CONTENT_AREA}}` etc.; do not invent placeholders. The whole mirror contract is "verbatim source + in-place text edit".+6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit visible text in place, but retain any imported semantic `data-pptx-placeholder` identity.7. **Output filename** — follow the standard project SVG naming convention (`<NN>_<page_name>.svg` where `<NN>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.-**Detecting mirror mode**: read the chosen template's `design_spec.md` frontmatter once during §1.0 batch read. If `replication_mode: mirror`, every page that hits `page_layouts` follows §1.1 above; pages without a `page_layouts` entry still fall through to free design (resolution rule 3 above).+**Detecting mirror mode**: read the chosen template's `design_spec.md` frontmatter once during §1.0 batch read. If `replication_mode: mirror`, every page follows §1.1 through its mandatory `page_layouts` reference.**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.@@ -85,32 +89,34 @@ When the project's chosen template is a `mirror` template (`design_spec.md` fronBefore generating each page, output which template is used:```-📝 **Template mapping**: `templates/03a_content_image_text.svg` (or "None (free design)")+📝 **Template mapping**: `templates/03a_content_image_text.svg` (free-design routes may use "None")🎯 **Adherence rules / layout strategy**: [specific description]```- **Content pages**: template defines only header/footer; content area is free-- **No template**: generate entirely per the Design Spec+- **No template**: allowed only on free-design or brand-only routes### 1.2 PowerPoint Master / Layout Mapping`page_layouts` selects an SVG design reference; `pptx_layouts` declares the native PowerPoint layout produced at export. They are independent contracts.-`pptx_structure.template_adherence` records the Strategist's confirmed template-use policy. `strict` requires one real `page_layouts` roster entry for every page; `adaptive` permits missing rows and keeps native export on `baseline` even when the template directory contains `native_structure.json` + `source_template.pptx`.+`pptx_structure.template_adherence` records the Strategist's confirmed template-use policy. Both `strict` and `adaptive` require one real `page_layouts` reference and one `pptx_layouts` output mapping per page. Strict keeps the referenced Layout contract; adaptive may create a new explicit Layout while retaining the template Master.| `pptx_structure.mode` | Executor behavior ||---|---|-| `baseline` or missing | Author ordinary SVG pages. Do not add explicit PPTX structure metadata merely because a page uses a visual template or its directory carries a native structure pair; export assigns conservative filename-backed Layout families after generation. |+| `baseline` or missing | Free design or brand-only route. Author ordinary standalone SVG pages; export assigns conservative filename-backed Layout families after generation. || `template` | Every generated SVG MUST implement the matching `pptx_layouts` row and the explicit structure contract below. |-| `preserve` | Every generated SVG MUST use the locked source layout key/name. Keep inherited master/layout visuals as marked preview layers; export removes the previews and reuses the original source package parts. |+| `preserve` | Legacy strict-only compatibility. Use the locked source layout key/name and retain marked preview layers for source-package reuse. |-**Hard rule — every structured page references one layout**: In `template` or `preserve` mode, read `P<NN>: <layout_key> | <layout name>` from `pptx_layouts`, then put both values on the root SVG as `data-pptx-layout` and `data-pptx-layout-name`. Do not invent, rename, or omit a key.+**Hard rule — every structured page references one layout**: In `template` or `preserve` mode, read `P<NN>: <layout_key> | <layout name>` from `pptx_layouts`, then put both values on the root SVG as `data-pptx-layout` and `data-pptx-layout-name`. Strict copies the selected template key/name. Adaptive may use the new key/name already locked by Strategist; Executor must not improvise another.**Hard rule — PowerPoint paint order**: Direct visual children appear in this order: Master background, Layout background, optional Slide background, shared Master shapes, same-key Layout shapes, then slide-local content/placeholders. Backgrounds are the special plane beneath all inherited shapes. Repeat the same Master contract on every page and the same Layout contract on every page sharing a key.**Placeholder ownership**: Keep actual title/subtitle/body/picture/chart/table/object/media/date/footer/slide-number content on the Slide and add the matching `data-pptx-placeholder`. Do not move actual content into a Layout. A reconstructed `title` normally omits `data-pptx-placeholder-idx`; preserve an explicit imported title index when present. Every indexed placeholder on one layout uses a unique index. Chart/table placeholders require native markers and a later `--native-objects` export; object/media placeholders must each resolve to one top-level DrawingML object.-**Preserve-mode source identity**: Copy `data-pptx-placeholder-idx` from the chosen template SVG/native contract whenever the source placeholder has an index. Preserve the source placeholder type/idx pairing; do not assign a convenient new index. Master/layout elements in the SVG are preview copies only and MUST retain `data-pptx-layer` + `data-pptx-editable="false"`; never flatten them into unmarked slide-local content.+**Adaptive Layout creation**: Start from the selected template SVG, keep every Master element identical, and change only the Layout layer/placeholder contract needed for the new composition. Pages sharing the new key repeat the same static Layout elements and placeholder ids/types in the same order.++**Legacy preserve identity**: In `preserve` mode only, copy source `data-pptx-placeholder-idx` values and retain the source placeholder type/index pairing. Master/Layout preview elements keep `data-pptx-layer` plus `data-pptx-editable="false"`.**Background ownership**:@@ -177,12 +183,12 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`Before drawing each page, look up its entry in `page_layouts` to decide which basename to inherit (the SVG itself was loaded in §1.0):-- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding SVG already in context. The basename **must match** an actual file in the chosen template directory. If it does not, `adaptive` emits `warning: page_layouts P<NN> references missing file <basename>.svg — falling back to free design`; `strict` stops and reports the invalid mapping.-- No entry for this page with `template_adherence: adaptive` (or no adherence row) → free design, no inheritance. **Not an error** — Strategist intentionally left this page free.-- No entry for this page with `template_adherence: strict` → stop before drawing and report the missing Strategist mapping; strict template use cannot silently fall back to free design.-- Whole section absent → see §1 fallback (legacy page-type matching).+- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding SVG already in context. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a template deck.+- No entry for this page with `template_adherence: strict|adaptive` → stop before drawing and report the missing Strategist mapping. Adaptive mode still selects the closest template SVG as its visual/structural reference; flexibility applies to the new output Layout, not to whether a template reference exists.+- Whole section absent with `pptx_structure.mode: template` → stop before drawing; the current template contract is incomplete.+- Whole section absent only in a legacy project without the current template contract → see §1 fallback (legacy page-type matching).-Do **not** invent a layout entry, and do **not** assume a template just because `templates/` exists. In `adaptive` mode, a silent `page_layouts` row is the instruction to design freely; in `strict` mode, silence is an upstream contract error.+Do **not** invent a layout entry, and do **not** assume a template just because `templates/` exists. For either template-adherence value, a missing or invalid `page_layouts` row is an upstream contract error. Free design is a separate deck route, never a per-page fallback inside template mode.**Per-page PowerPoint layout lookup — `pptx_layouts` section**:diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex 91e4894a..924a0bf0 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -169,6 +169,17 @@ One offending character invalidates the file and aborts export. Numeric refs (`&## 4. Basic SVG Rules+### 4.0 Complete Page-Design Contract++| Concern | Requirement |+|---|---|+| Visible slide result | The completed `svg_output/<slide>.svg` MUST contain every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element intended for that slide. External visual assets are valid when the SVG references them explicitly. |+| Template/control inputs | Templates, `design_spec.md`, and `spec_lock.md` guide authoring. Do not depend on them to add visible elements after the page SVG is complete. |+| PPTX translation | The exporter may map represented SVG content to DrawingML/native objects and deduplicate represented elements into Master/Layout/Slide parts. It MUST NOT invent visible slide content absent from the SVG. |+| Excluded package behavior | Speaker notes, animations, transitions, narration audio, PPTX relationships, and direct native-PPTX workflows remain separately owned. They are not part of the SVG page-design contract. |++**Hard rule — page-design closure**: A final page SVG is the sole visual/design authority for that page on every SVG-authoring route. SVG is not the authority for the entire PPTX package.+- **viewBox** MUST match the canvas dimensions; it is the single source of truth for canvas size. Root `width`/`height` are optional compatibility attributes and are not used as PPT Master canvas authority.- **Background**: Use `<rect>` to define the page background color- **`<tspan>`** has two purposes: (1) manual line breaks (use `dy` or explicit `y`); (2) inline run formatting on the same line (color/weight/size). `<foreignObject>` is FORBIDDEN. See "Single logical line" rule below.@@ -950,6 +961,13 @@ slide in that family carries exactly the same explicit background. Otherwise,keep each background on its Slide. Preserve whether each family shows or hidesthe parent Master shape tree.+**Layout chrome rule**: After family assignment, move only the identical+leading prefix of explicitly named chrome (`logo`, `footer`, `header`,+`watermark`, `chrome`) carried by every family member. Generated OOXML and+image relationships must match exactly, no animation may target the shapes,+and moving them behind Slide content must preserve z-order. Keep page numbers+and every non-identical object Slide-local.+### Theme Font Inheritance (Baseline and Template Export)New projects derive PowerPoint theme fonts from `spec_lock.md` typography when@@ -1010,18 +1028,19 @@ colors.### Explicit PPTX Master / Layout / Placeholder Metadata (Template Export)-**Trigger**: Set `spec_lock.md` `pptx_structure.mode` to `template`, or pass-`--pptx-structure template` explicitly. The CLI value overrides the lock;-without either trigger, metadata stays visually dormant and the SVG exports-through the normal baseline / flat path.+**Trigger**: Deck/layout template routes set `spec_lock.md`+`pptx_structure.mode` to `template`; direct diagnostics may pass+`--pptx-structure template`. Both strict and adaptive template adherence use+this mode. Without either trigger, metadata stays visually dormant.**Project lock**: In the standard project pipeline, template mode requires one`pptx_layouts` row per page using`P<NN>: <layout_key> | <PowerPoint layout name>`. The SVG root values MUST-match that row. Reuse one layout key only when pages share the same static-layout layer and placeholder contract; different content is not a reason to-create a new layout. Direct diagnostic exports may pass the CLI flag without a-spec lock; the SVG metadata remains the exporter source of truth.+match that row. Strict uses the selected template key/name. Adaptive may create+a new key/name while repeating the same Master contract. Reuse one layout key+only when pages share the same static Layout layer and placeholder contract;+different content is not a reason to create a new layout. Direct diagnostic+exports may pass the CLI flag without a spec lock.| Metadata | Placement | Behavior ||---|---|---|@@ -1096,9 +1115,9 @@ must still resolve to one top-level DrawingML object. `media` currently bindsan authored image/crop to a native `media` placeholder; it does not synthesizevideo or audio media from a decorative SVG group.-### Preserved Source Master / Layout Contract+### Legacy Preserved Source Master / Layout Contract-**Trigger**: A reusable template package ships `native_structure.json` and `source_template.pptx`, the Strategist-confirmed `template_adherence` is `strict`, and `spec_lock.md` sets `pptx_structure.mode: preserve` with project-relative paths to both files. The pair's presence alone is not a trigger; `adaptive` template use stays on `baseline`.+**Trigger**: An existing project already ships `native_structure.json` and `source_template.pptx`, has strict template adherence, and sets `pptx_structure.mode: preserve`. Current `create-template` output does not emit this pair; retain this contract only for backward compatibility.| Artifact | Authority ||---|---|diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 815ab6b2..a22f8f81 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -100,14 +100,14 @@ Write the locked value to `spec_lock.md` `- visual_style:` and the rationale to> **Template vs preset**: a style mention may sound like a template name ("academic style" vs the `academic_defense/` template directory). Step 3 only triggers on an explicit template directory path supplied by the user — bare names and style words never copy templates; they map to a visual-style preset here. If a template was triggered upstream, its files are already in `<project_path>/templates/` and its fused design_spec governs.-**Native template contract**: When `<project_path>/templates/native_structure.json` exists, read it before assigning page layouts. It is the factual source for PowerPoint layout keys/names, parent masters, and placeholder identities; the template SVG roster remains the visual/content-fit source.+**Legacy native contract**: When `<project_path>/templates/native_structure.json` exists, treat it as backward-compatible `preserve` input only. Current templates declare their PowerPoint structure directly in the SVG roster.**Template adherence confirmation**: Surface this closed Stage-1 choice only when Step 3 loaded a `kind: deck` or `kind: layout` template. Omit it for free design and brand-only templates.| Value | Planning and export behavior ||---|---|-| `strict` | Map every generated page to one actual template SVG in `page_layouts`. When the selected structure segment also ships a validated native pair, use `pptx_structure.mode: preserve` and map every page to that SVG's exact source layout key/name. |-| `adaptive` | Treat the template roster as optional visual/layout references. Write `page_layouts` only where a roster page fits; leave other pages free. Keep `pptx_structure.mode: baseline` even when the native pair exists. |+| `strict` | Map every page to one template SVG. Keep its explicit Master/Layout/placeholder contract and output layout key unchanged. |+| `adaptive` | Map every page to the closest template SVG. Keep the template Master contract, but allow a new explicit Layout key when the selected composition must adapt to the content. |**Default — adaptive (may override when the user requests exact template use)**: Recommend `adaptive` when the user supplied only a template path with no stricter instruction. Preselect `strict` when the user explicitly asks to follow or preserve the template closely; the Stage-1 confirmation still records the final choice. Record the confirmed value in `design_spec.md §I` and as `template_adherence` under `spec_lock.md pptx_structure`.@@ -852,11 +852,11 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck- **Cover impact is mandatory**: Page `P01` is the deck's first visual contract, not a generic title slide. In `design_spec.md §IX`, add a `Cover impact` line for `P01` that names one concrete hook and one concrete composition strategy. Use the source's strongest available signal: a provocative core claim, object / scene metaphor, hero number, founder / product / audience moment, or a distilled conflict. Pair it with one concrete composition strategy — such as `full-bleed image + floating title`, `typographic poster`, `hero object`, `data hook`, `editorial scene`, `high-contrast abstract geometry`, or a fresh composition the deck's subject suggests (these are starting points, not the allowed set). If no external or AI image is available, still specify a native-SVG visual hook; do not fall back to "title + subtitle + decorative background". (Beautify / template-fill keep the source cover verbatim — this rule does not apply on those preservation paths.)- **Cover rhythm lock**: `P01` remains `anchor` in `spec_lock.md page_rhythm`, but its §IX `Cover impact` must prevent content-page patterns. Do not plan multi-card grids, agenda-like bullets, or equal-weight columns on the cover unless a template explicitly requires that structure, or a preservation path (beautify / template-fill) is transcribing the source cover verbatim.- **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.- - **pptx_structure is mandatory**: Write `mode: baseline` by default. When a deck/layout template was confirmed, also write `template_adherence: strict|adaptive`. Use `mode: preserve` only when adherence is `strict` and the selected template structure segment ships both `templates/native_structure.json` and `templates/source_template.pptx`; add project-relative `source_template` and `native_structure` rows exactly as shown in `spec_lock_reference.md`. `adaptive` always stays on `baseline`, regardless of whether the pair exists. Use `mode: template` only when the user explicitly requests a reusable PowerPoint Master/Layout/Placeholder deliverable and no preserved native pair owns the structure. Do not choose `flat`; it is a CLI-only diagnostic override.- - **pptx_layouts (template/preserve structure)**: When `pptx_structure.mode` is `template` or `preserve`, write one `P<NN>: <layout_key> | <PowerPoint layout name>` row for every page. In preserve mode, take the exact key/name from the chosen template SVG root and verify it exists in `native_structure.json`; never rename source layouts. In template mode, reuse a layout key when pages share the same static layout layer and placeholder contract; page content differences do not justify new keys. One-off cover/section layouts are valid. Omit the whole section in baseline mode.- - **page_layouts (write only when a template is in use)**: For each page that inherits a template SVG, add `P<NN>: <svg_basename>` (e.g., `P04: 03a_content_image_text`). With `template_adherence: strict`, every generated page requires a row and the basename must exist in the selected roster. With `adaptive`, pages designed freely get **no entry** — Executor reads the absence as "free design, no inheritance". If zero pages use a template, omit the section entirely.+ - **pptx_structure is mandatory**: Write `mode: baseline` for free design and brand-only routes. When a deck/layout template is confirmed, write `mode: template` plus `template_adherence: strict|adaptive`. Both adherence values stay on explicit template export. Use `mode: preserve` only when reopening a legacy strict project that already carries a validated `native_structure.json` + `source_template.pptx` pair. Do not choose `flat`; it is a CLI-only diagnostic override.+ - **pptx_layouts (template/preserve structure)**: In template mode, write one `P<NN>: <layout_key> | <PowerPoint layout name>` row for every page. Strict uses the selected template SVG's exact key/name. Adaptive may introduce a new stable key/name, but pages reuse a key only when their static Layout layer and placeholder contract match. In legacy preserve mode, use the exact source key/name. Omit the whole section in baseline mode.+ - **page_layouts (deck/layout templates only)**: Add one `P<NN>: <svg_basename>` row for every page. Strict inherits that SVG contract unchanged. Adaptive uses it as the architecture reference and may evolve the Layout layer under a new `pptx_layouts` key; it must not drop into free design. Omit the section only for free design and brand-only routes.- **page_charts (write only for chart pages that match a catalog template)**: For each page in `design_spec.md §VII` whose `reference template path` points to `templates/charts/<name>.svg`, add `P<NN>: <chart_name>`. Pages with `no-template-match` in §VII MUST NOT appear here (Executor would look for a non-existent reference). If the deck has no data-visualization pages, omit the section.- - **Hard rule**: Use both `page_layouts` and `page_charts` for the same page only when the layout template is a compatible shell for the chart. Do not pair chart pages with conflicting page layouts (e.g., `waterfall_chart` + timeline layout, KPI cards + circle-diagram layout). If no compatible layout exists, omit the page from `page_layouts`.+ - **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible template shell. For a chart page without an exact roster match, adaptive mode selects the closest neutral content template and assigns a new explicit Layout key; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` inside a deck/layout template route.---diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex 4a497f96..a87e477b 100644--- a/skills/ppt-master/references/template-designer.md+++ b/skills/ppt-master/references/template-designer.md@@ -18,8 +18,8 @@ When the workflow provides a PPTX reference source, the effective input package- 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)-- `native_structure.json` — stable source master/layout keys, picker names, parent-master relationships, placeholder type/index/geometry, source hash, and template-packaging preserve-vs-rebuild recommendation-- `source_template.pptx` — byte-preserved source package paired with `native_structure.json`+- `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)@@ -37,7 +37,7 @@ PPTX import interpretation:Input priority for PPTX-backed template creation:1. `manifest.json` for all factual metadata (theme, assets, unique layout/master structure, slide reuse, page-type guidance)-2. `native_structure.json` for native PowerPoint identities, source placeholder indices, relationship completeness, and the confirmed template-packaging strategy+2. `native_structure.json` for source PowerPoint identities, placeholder indices, relationship completeness, and reconstruction facts3. `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 / master5. exported `assets/` for reusable visual resources@@ -45,16 +45,9 @@ Input priority for PPTX-backed template creation:7. `summary.md` only as a fast scan; never as the canonical fact source8. screenshots / original PPTX only for style verification-**Native structure packaging strategy**:+**Native structure output**: Always set `native_structure_mode: template`. Do not ship `native_structure.json` or `source_template.pptx`. Reconstruct one clean Master plus semantic Layouts through explicit SVG structure metadata. Every page remains a complete standalone SVG preview.-| Confirmed value | Output behavior |-|---|---|-| `preserve` | Copy `native_structure.json` and `source_template.pptx` unchanged. Bind every template SVG to one source layout key/name and source placeholder identities. This retains a downstream strict-use capability; it does not force every project to activate it. |-| `template` | Do not ship the source pair. Reconstruct one master plus semantic layouts through explicit SVG structure metadata. |--Mirror replication cannot use `preserve`: flat SVGs no longer identify which pixels belong to the source master/layout.--**Downstream boundary**: The Strategist confirmation stage selects `strict` or `adaptive` when a project consumes this package. `strict` may activate the preserved pair; `adaptive` uses selected template SVGs as references and exports through baseline. Template_Designer does not preselect that project-level choice.+**Downstream boundary**: The Strategist confirmation stage selects `strict` or `adaptive` when a project consumes this package. Both export through explicit template mode. Strict keeps the referenced Layout contract; adaptive may create a new Layout while retaining the template Master. Template_Designer does not preselect that project-level choice.---@@ -66,7 +59,7 @@ The output page set is determined by **replication mode**, declared in the final|------|-------------|--------|| `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 is preserved 1:1 as a reference page for the template package. Verbatim copy, no abstraction, no placeholders | One SVG per source slide, named `<NNN>_<page_type>.svg` by source order |+| `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 |### Standard mode@@ -107,13 +100,14 @@ Extension page types beyond the canonical four (transition / appendix / disclaim### Mirror mode-When the brief sets `Replication mode: mirror`, the role does **not** abstract or reconstruct. Each source slide becomes one template page **byte-for-byte**:+When the brief sets `Replication mode: mirror`, preserve literal page appearance while reconstructing layer ownership:-- Source: `<import_workspace>/svg-flat/slide_NN.svg` (the self-contained "what PowerPoint shows" view). Do **not** read or use `svg/master_*.svg`, `svg/layout_*.svg`, or `svg/inheritance.json` — chrome / content separation is irrelevant because mirror does not insert placeholders.+- 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`.- Output: `templates/<kind_dir>/<template_id>/<NNN>_<page_type>.svg`, where `<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.-- Modifications allowed: **only** rewriting `<image href="...">` paths to point at the local `assets/` copy, and renaming asset files to semantic names. Everything else — geometry, decoration, sprite-sheet wrappers, original example text, chart placeholders, embedded fonts — is copied as-is.-- Modifications forbidden: inserting `{{TITLE}}` / `{{CONTENT_AREA}}` / any other placeholder; "cleaning up" decorative complexity; merging similar slides; dropping master/layout chrome (it's already baked into the flat SVG, leave it).-- `design_spec.md` §V Page Roster lists every emitted file with **a one-line description** of what the page contains and what content slot it suits — Strategist selects pages from these descriptions, since the SVG itself carries no placeholder contract.+- Required metadata rewrite: declare the output Layout on the root, mark inherited Master/Layout visuals as direct preview layers, and map source content slots to semantic `data-pptx-placeholder` markers where the imported contract exposes them.+- 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.**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.@@ -152,13 +146,10 @@ source_canvas_width: 1280source_canvas_height: 720source_viewbox: "0 0 1280 720"replication_mode: standard | fidelity | mirror-# Type-A native retention capability only; omit these rows for rebuilt templates.-# Downstream strict/adaptive use is confirmed by Strategist.-# native_structure_mode: preserve-# native_structure: native_structure.json-# source_template: source_template.pptx+# Required for every deck/layout template. Source packages remain analysis-only.+native_structure_mode: template# Optional — only when this template overrides canonical placeholder vocabulary.-# Omit entirely for `mirror` mode (mirror has no placeholders).+# Omit only when the page truly exposes no replaceable content slots.# placeholders:# 01_cover: ["{{TITLE}}", "{{SUBTITLE}}", "{{BRAND_LOGO}}"]# 03_content: ["{{KEY_MESSAGE}}", "{{CONTENT_AREA}}"]@@ -185,7 +176,7 @@ replication_mode: standard | fidelity | mirror- 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). For a preserved template, also record the source native 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 artifact** — Strategist picks pages from these descriptions, so each row must include enough detail to distinguish it from siblings (column count, hero element, content density, what kind of content slot it fits — "three-column KPI grid with large numbers, suits quarterly summary"). 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). 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.## VI. Assets (omit when none)Logos, cover backgrounds, brand textures bundled with the template package — file name, dimensions, intended usage.@@ -234,8 +225,6 @@ If PPTX import output exists:The imported PPTX is a **reference source**, not a direct conversion target.-> Preserve exception: `source_template.pptx` is the native package retention target. Keep it byte-identical; only the companion SVG authoring references are simplified.-Do:- preserve brand assets, recurring backgrounds, and stable structural motifs- rebuild the layout into a clean SVG structure aligned with PPT Master constraints@@ -250,27 +239,27 @@ Do not:- 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-**Preserve-mode SVG contract**:+**Explicit template SVG contract**:-| Source fact | Template SVG declaration |+| Rebuilt fact | Template SVG declaration ||---|---|-| Chosen source layout | Root `data-pptx-layout` + exact `data-pptx-layout-name` |-| Source master/layout visual | Direct preview child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"` |-| Source placeholder | Direct content child with `data-pptx-placeholder`; add exact `data-pptx-placeholder-idx` when the source placeholder has an index |+| Output semantic layout | Root `data-pptx-layout` + stable `data-pptx-layout-name` |+| Rebuilt master/layout visual | Direct preview child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"` |+| Semantic content slot | Direct content child with `data-pptx-placeholder`; add `data-pptx-placeholder-idx` when same-role slots require stable disambiguation || Page-only background | Direct full-canvas solid rect with `data-pptx-layer="slide"` |-Repeat inherited visuals in the standalone SVG so browser preview remains complete. Preserve export removes those preview copies and renders the original source master/layout parts instead. 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, moves one copy into the generated Master/Layout parts, and removes the repeated Slide copies. Do not flatten inherited visuals into unmarked slide content.Use the imported semantic roles 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; if the imported source title has one, retain it.-All indexed source placeholders keep their exact indices.+title normally has no index. Assign stable indices only when repeated roles need+disambiguation inside the rebuilt Layout.### 3. Placeholder Markers-> **Mirror mode skips this section entirely.** Mirror SVGs are verbatim copies of the source flat slides — they carry no `{{}}` markers. Mirror is only a template-creation mode; downstream generation treats the finished files as normal template roster candidates. The rest of this section applies to `standard` and `fidelity` only.+> 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.Use clear placeholder markers for replaceable content:@@ -369,20 +358,6 @@ templates/<kind_dir>/<template_name>/└── *.png / *.jpg```-Preserve-mode standard/fidelity packages add the native pair:--```-templates/<kind_dir>/<template_name>/-├── design_spec.md-├── native_structure.json-├── source_template.pptx-├── 01_cover.svg-├── 03a_content_two_col.svg-└── ...-```--Do not add the pair to mirror packages or rebuilt templates.-Mirror mode emits one SVG per source slide, named by source order:```@@ -400,7 +375,7 @@ templates/<kind_dir>/<template_name>/└── *.png / *.jpg```-Filenames preserve the source slide order via the 3-digit prefix; `<page_type>` is derived from `manifest.json` `pageTypeCandidates`. No `{{}}` placeholders appear in any mirror 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.### Template Preview@@ -410,7 +385,7 @@ 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-- whether native structure was preserved or rebuilt; for preserve, list the retained master/layout counts+- how the source Master/Layout graph was consolidated into the rebuilt Master and semantic Layout roster---@@ -418,7 +393,7 @@ 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**: copy the spec + template SVGs and optional native structure pair into the project's `templates/`, and any bundled bitmaps into the project's `images/` (the runtime image pool, referenced as `../images/`). The pair remains optional capability until Strategist confirms strict template adherence.+1. **Copy template**: copy the spec + explicitly layered template SVGs into the project's `templates/`, and any bundled bitmaps into the project's `images/` (the runtime image pool, referenced as `../images/`).2. **Adjust colors**: Modify colors per the project design spec3. **Customize**: Make project-specific adjustments@@ -451,7 +426,7 @@ templates/- [x] Every page listed in `design_spec.md §V Page Roster` saved to `templates/<layouts|decks>/<template_name>/` (decks for full-PPT replicas, layouts for structure-only)- [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 (standard / fidelity); mirror SVGs contain **no** `{{}}` markers-- [x] Native structure packaging strategy applied: preserve pair + source bindings, or explicit rebuilt structure; downstream strict/adaptive choice remains unforced+- [x] Placeholder markers are clear and standardized; mirror may keep literal text but still maps imported semantic slots+- [x] Every SVG is a complete preview with explicit Master/Layout/Slide/placeholder metadata and `native_structure_mode: template`- [ ] **Next step**: Validate assets and register the template via `register_template.py <id> --kind <deck|layout>````diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 3f9dca22..07805b14 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -116,11 +116,13 @@ python3 scripts/svg_to_pptx.py <project_path>`finalize_svg.py` optimizes raster images by default using `2x` display pixels and max `2560px`. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: only oversized full source images are reduced to max `2560px`, so later PowerPoint resizing keeps more image detail. Use `svg_to_pptx.py --image-sizing display --image-scale 2` only for aggressive size reduction, or `--no-image-optimize` when the native PPTX must embed original image bytes.-When `spec_lock.md` has no `pptx_structure` section, native `svg_to_pptx.py` falls back to `baseline`: the generated deck keeps a standard master/layout relationship and promotes the strict-majority identical native slide background into the slide master (minority slides keep their own overriding background). A shared leading prefix of top-level SVG elements with exact chrome id tokens such as `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber` may also be promoted when its generated OOXML is identical on a strict majority of slides, it is not referenced by slide timing, and moving it behind slide-local content preserves z-order; image relationships are copied to the master. Minority slides such as covers keep every shape slide-local and are bound to a generated `Cover` layout (`showMasterSp="0"`) that hides the promoted master chrome. After all SVG pages are complete, baseline assigns filename-backed `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` layouts while preserving that master-shape visibility. It moves a family background to Layout only when every member carries the exact same explicit `p:bg`; actual titles, body content, pictures, charts, tables, and page-specific shapes remain on Slide, with no visual-similarity or placeholder inference. Baseline additionally prunes base-template slide layouts that no generated slide references, and swaps `pageNumber`/`slideNumber` chrome text for an auto-updating slide-number field when the text exactly equals the slide's display number. For projects with locked typography and colors, baseline/template export also maps the title/body families and canonical palette roles into the PowerPoint theme while preserving the initial SVG rendering. Use `--pptx-structure flat` when all generated structure and theme tokens must remain slide-local/concrete for debugging or comparison.+For SVG-authoring routes, `svg_output/` is the complete visible page-design source: every exported text, image, shape, background, and template-derived layout element is present in the page SVG or explicitly referenced by it. Export may translate represented content into Master/Layout/Slide parts or native objects, but it does not retrieve missing visible content from templates or planning files. Speaker notes, animation, narration, transitions, `template-fill-pptx`, and `native-enhance-pptx` remain separately owned capabilities.-Use template structure only when the final slide SVGs explicitly declare reusable PowerPoint structure. The CLI reads `spec_lock.md` `pptx_structure.mode` when `--pptx-structure` is omitted, so a locked `template` project exports structurally through the standard command; an explicit CLI value still overrides the lock. Each SVG names its layout with `data-pptx-layout`; direct root children may opt into master/layout layers with `data-pptx-layer`, and supported text, picture, chart, table, footer, or slide-number elements may declare `data-pptx-placeholder`. The exporter validates the project-level `pptx_layouts` mapping and cross-slide consistency, creates one reusable layout per layout key, and keeps actual content slide-local. A direct full-canvas solid rect becomes a real Master/Layout/Slide `p:bg` according to its declared scope; an unmarked full-canvas solid rect is a Slide override. It never infers placeholders from visual similarity. The complete metadata contract lives in [`references/shared-standards.md`](../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).+When `spec_lock.md` has no `pptx_structure` section, native `svg_to_pptx.py` falls back to `baseline`: the generated deck keeps a standard Master/Layout relationship and promotes only exact, z-order-safe shared backgrounds/chrome. It then assigns filename-backed `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` layouts. A family-wide exact background and an exact leading chrome prefix may move into that Layout; actual titles, body content, pictures, charts, tables, page numbers, and page-specific shapes remain on Slide. No visual-similarity or placeholder inference is performed. Baseline also prunes unused layouts and maps locked typography/colors into the PowerPoint theme. Use `--pptx-structure flat` for slide-local diagnostics.-`create-template` may retain `native_structure.json` plus `source_template.pptx` as an optional native capability. Their presence does not select the export route. When Strategist confirms `template_adherence: strict`, lock `pptx_structure.mode: preserve`, point the lock at both project-relative files, and map every page to an exact imported layout key/name. The exporter verifies the source hash and package parts, keeps the source master/layout/theme roster (including multiple source masters), removes SVG preview copies of inherited layers, and binds generated slide content back to source placeholder indices. Preserve mode does not prune unused source layouts. With `template_adherence: adaptive`, keep `pptx_structure.mode: baseline`; template SVGs remain optional page references and free pages remain slide-local.+Deck/layout template routes use explicit template structure. Each complete SVG names its output Layout, repeats inherited Master/Layout preview layers, and marks supported content placeholders. Strict keeps the selected Layout contract; adaptive may create a new Layout while retaining the Master. The exporter validates cross-slide equality, creates one reusable Layout per key, removes repeated inherited copies, and keeps actual content Slide-local. The complete contract lives in [`references/shared-standards.md`](../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).++Current `create-template` output always rebuilds explicit SVG structure and does not package `native_structure.json` or `source_template.pptx`. `preserve` remains available only for existing projects that already carry the legacy pair.`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. Source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts are retained when the current schema can represent them. Tables with direct borders, non-solid fills, or mixed rich-text formatting remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Unsupported tables keep their rendered SVG table; unsupported charts keep a baked preview or explicit placeholder. Both carry `data-pptx-native-status`, which `svg_quality_checker.py` and `svg_to_pptx.py --native-objects` report as a warning.diff --git a/skills/ppt-master/scripts/confirm_ui/static/catalogs.json b/skills/ppt-master/scripts/confirm_ui/static/catalogs.jsonindex 639ebe38..3acbb5ab 100644--- a/skills/ppt-master/scripts/confirm_ui/static/catalogs.json+++ b/skills/ppt-master/scripts/confirm_ui/static/catalogs.json@@ -562,9 +562,9 @@"label_zh": "适应性使用","label_en": "adaptive","label_ja": "適応的に使用",- "desc_zh": "沿用模板的视觉语言和合适版式,允许不适配的页面自由设计;原生结构文件不会强制整份演示使用 preserve。",- "desc_en": "Reuse the template's visual language and suitable layouts while allowing unmatched pages to be designed freely; native structure files do not force preserve mode for the whole deck.",- "desc_ja": "テンプレートのビジュアル言語と適合するレイアウトを再利用し、合わないページは自由に設計する。ネイティブ構造ファイルがあっても、デッキ全体に preserve を強制しない。"+ "desc_zh": "每页选择一个模板 SVG 作为架构参考;没有合适版式时沿用同一 Master 创建新的显式 Layout。",+ "desc_en": "Choose a template SVG as the architecture reference for every page; when no layout fits, create a new explicit Layout under the same Master.",+ "desc_ja": "各ページでテンプレートSVGを構造参照として選び、適合する版式がない場合は同じMaster配下に新しい明示的Layoutを作成する。"},{"id": "strict",@@ -572,9 +572,9 @@"label_zh": "严格套用","label_en": "strict","label_ja": "厳密に適用",- "desc_zh": "每一页都从模板 SVG roster 选择版式;模板携带兼容的原生结构时,复用其 Master/Layout/Placeholder。",- "desc_en": "Map every page to the template SVG roster; when the package carries compatible native structure, reuse its Master, Layout, and Placeholder contracts.",- "desc_ja": "すべてのページをテンプレートSVG一覧へ割り当て、互換性のあるネイティブ構造が含まれる場合はMaster/Layout/Placeholderを再利用する。"+ "desc_zh": "每一页都从模板 SVG roster 选择版式,并保持其显式 Master、Layout 与 Placeholder 契约不变。",+ "desc_en": "Map every page to the template SVG roster and keep its explicit Master, Layout, and Placeholder contract unchanged.",+ "desc_ja": "すべてのページをテンプレートSVG一覧へ割り当て、明示されたMaster/Layout/Placeholder契約を変更せずに維持する。"}],"delivery_purpose": [diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex e99d3084..8a79e758 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -153,7 +153,7 @@ The AI launches Stage 1 (`--daemon --wait`), reads the stage-1 result, **re-deri> Each `candidates` array above shows **one** entry for brevity — `color` and `typography` must each carry **≥3** in a real file, while `image_strategy.candidates` should carry **exactly 3 non-custom recommendation** entries when AI image generation is offered. The UI adds the fourth **Custom** card itself; `selected` indexes the recommended default among the recommendation entries.- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids.-- `recommend.template_adherence` is conditional. Write `adaptive` or `strict` only when Step 3 loaded a `kind: deck` or `kind: layout` template. The server independently checks the copied template spec and enables the field only for those two kinds; free design and brand-only templates cannot display or return it. If the template is active but the recommendation key is missing, the server supplies `adaptive`. `adaptive` keeps native export on `baseline` and permits pages without `page_layouts`; `strict` requires every page to use the template roster and may activate a compatible preserved native pair.+- `recommend.template_adherence` is conditional. Write `adaptive` or `strict` only when Step 3 loaded a `kind: deck` or `kind: layout` template. The server independently checks the copied template spec and enables the field only for those two kinds; free design and brand-only templates cannot display or return it. If the template is active but the recommendation key is missing, the server supplies `adaptive`. Both values use explicit template export and require a reference SVG for every page: `strict` keeps the selected Layout contract; `adaptive` may create a new Layout under the same Master.- `recommend.image_usage` should be an array of source ids when more than one source applies, e.g. `["ai", "provided"]`. A single string is still accepted for backward compatibility. Do not write bare `"custom"` and do not encode a mixed-source plan as prose here; write the prose to top-level `image_notes.value`.- `image_notes` is the initial strategy note shown under the image source chips. Use it for page-role guidance and constraints: which source applies where, what to avoid, which user assets are authoritative, how realistic / abstract the imagery should be, and what can remain as placeholders. It is intent guidance, not a separate finite option.- When `recommend.image_usage` includes `ai`, also set `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`; the page presents these as explicit choices.diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 9b30c5c4..64975f6f 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -60,13 +60,18 @@ Behavior:- Mergeable detection is conservative: only fires when the children form a clean paragraph block; mixed-layout `<text>` falls through to the default per-line path- Native export reads `svg_output/`; `--svg-snapshot` and legacy export read`svg_final/`. Use `-s` only as an explicit diagnostic override.+- On every SVG-authoring route, each file in `svg_output/` is the complete visible+ page-design source. Templates and locks may guide authoring, but finalize/export+ never use them to overlay visible content missing from the SVG. Notes, animation,+ narration, transitions, and direct native-PPTX workflows keep their separate+ inputs and package-level processing.- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.-- Omitting `--pptx-structure` reads `spec_lock.md` `pptx_structure.mode`, then falls back to `baseline`; an explicit CLI value overrides the lock. After SVG conversion, baseline assigns filename-backed `Cover` / `Agenda` / `Section` / `Closing` / `Content` layout families (while retaining an existing chrome-safety `Cover` assignment), keeps real page content slide-local, and moves a family background to Layout only when every member has the exact same explicit `p:bg`; it never infers placeholders or visual similarity. Template mode builds reusable PowerPoint layouts only from explicit SVG metadata: root `data-pptx-layout`, direct-child `data-pptx-layer="master|layout"`, optional `data-pptx-layer="slide"` on a full-canvas solid background, and direct-child `data-pptx-placeholder`. It validates the per-page `pptx_layouts` lock plus cross-slide structure consistency and never infers layouts from visual similarity. Direct full-canvas solid rects compile to Master/Layout/Slide `p:bg` by scope; an unmarked one is a Slide override. Chart/table placeholders also require `--native-objects`. Full contracts: [`shared-standards.md`](../../references/shared-standards.md#baseline-layout-family-extraction) and [`shared-standards.md`](../../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).+- Omitting `--pptx-structure` reads `spec_lock.md` and falls back to `baseline`. Baseline assigns filename-backed layout families, keeps content Slide-local, and promotes only exact family-wide backgrounds plus exact leading named chrome; it never infers placeholders or visual similarity. Template mode builds reusable PowerPoint structure only from explicit SVG metadata and validates every `pptx_layouts` row plus cross-slide equality. Both strict and adaptive template adherence use this mode; adaptive may introduce a new Layout key under the same Master.- Template/preserve placeholder semantics distinguish title, subtitle, body, picture, chart, table, generic object, media, date, footer, and slide number. Reconstructed titles are normally type-matched without an index; explicit imported title indices and all other source indices are retained. Imported `subTitle`, `obj`, `media`, and `dt` identities remain distinct through `manifest.json`, `native_structure.json`, Layout XML, and Slide XML.- Baseline/template native export reads `spec_lock.md` typography into the PowerPoint theme: `title_family` becomes the major font and `body_family` / `font_family` becomes the minor font. Matching SVG text emits `+mj-*` / `+mn-*` tokens, while unrelated emphasis/code/brand families stay concrete. Preserve mode keeps the imported source theme; flat mode keeps fixed-font diagnostic output.- Baseline/template native export also maps canonical `spec_lock.md` color roles into the PowerPoint color scheme and emits context-safe `schemeClr` tokens for exact matches in SVG fills/text/strokes, gradients/patterns/bullets, native tables, and native-chart accent series. Local colors, inverse white/black, and effects stay concrete. Preserve mode keeps the imported source color scheme; flat mode keeps fixed-color diagnostic output.-- Preserve mode requires both a Strategist-confirmed `template_adherence: strict` and a `create-template` native pair (`native_structure.json` + `source_template.pptx`) declared in `spec_lock.md`. It verifies the source digest, binds each generated page to an imported layout part, retains the source master/layout/theme roster, removes preview-only inherited SVG layers, and restores source placeholder type/index identities. The SVG root still declares `data-pptx-layout`; repeated semantic placeholders may disambiguate with `data-pptx-placeholder-idx`. `template_adherence: adaptive` keeps export on baseline even when the pair is present.+- Preserve mode is legacy strict-only compatibility for existing projects that already carry `native_structure.json` + `source_template.pptx`. Current template creation does not emit the pair.- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.mdindex cb26a3b9..b93d6bbb 100644--- a/skills/ppt-master/templates/spec_lock_reference.md+++ b/skills/ppt-master/templates/spec_lock_reference.md@@ -132,11 +132,11 @@> - template_adherence: adaptive> - template_adherence: strict> ```-> Omit the row for free design and brand-only templates. `adaptive` treats template SVGs as optional page references and always exports through `baseline`; `strict` requires one `page_layouts` row per page and may use `preserve` when the template carries a compatible native pair.+> Omit the row for free design and brand-only templates. Both values require one `page_layouts` and one `pptx_layouts` row per page. `strict` keeps the selected Layout contract; `adaptive` may create a new explicit Layout under the same template Master.>-> - `baseline` — default. Preserve conservative shared Master/background/chrome behavior, then assign filename-backed Cover/Agenda/Section/Closing/Content layouts after SVG generation. Actual content stays slide-local; no reusable placeholders or visual-similarity inference are authored.-> - `template` — use only when the user explicitly requests a reusable PowerPoint template/master/layout deliverable. Requires a complete `pptx_layouts` section and explicit SVG structure metadata on every generated page.-> - `preserve` — use only with `template_adherence: strict` when the selected reusable template ships `native_structure.json` + `source_template.pptx`. Add both project-relative rows below and map every page under `pptx_layouts`. `adaptive + preserve` is invalid.+> - `baseline` — default for free design and brand-only routes. Preserve conservative shared Master/background/chrome behavior, then assign filename-backed Cover/Agenda/Section/Closing/Content layouts. It may also promote exact family-wide leading chrome into a Layout. Actual content stays slide-local; no placeholders or visual-similarity inference are authored.+> - `template` — required whenever Step 3 loaded a deck/layout template. Requires complete `page_layouts` and `pptx_layouts` sections plus explicit SVG structure metadata on every generated page.+> - `preserve` — legacy strict-only compatibility for an existing project that already ships `native_structure.json` + `source_template.pptx`. Do not select it for newly created templates.> - `flat` — diagnostic escape hatch. Do not lock this in a normal project; pass it on the CLI when comparing slide-local output.>> Preserve example:@@ -149,7 +149,7 @@## pptx_layouts-> Emit this section only when `pptx_structure.mode` is `template` or `preserve`. Include exactly one row per generated page. Value format: `<layout_key> | <PowerPoint layout name>`. Preserve mode uses exact keys/names from `native_structure.json` and the selected template SVG root.+> Emit this section only when `pptx_structure.mode` is `template` or legacy `preserve`. Include exactly one row per generated page. Value format: `<layout_key> | <PowerPoint layout name>`. Strict template use copies the selected SVG key/name; adaptive use may declare a new stable key/name. Preserve uses the legacy native contract.>> Example:> ```@@ -166,13 +166,13 @@- P03: 02a_chapter- P04: 03a_content_abstract-> One entry per page **that uses a template SVG**. Key: `P<NN>` matching §IX. Value: the template's SVG basename without extension (e.g., `01_cover`, `03a_content_image_text`) — Executor resolves it to `templates/<value>.svg`. Modern templates ship many content-page variants (`03a_content_abstract`, `03b_content_image_text`, `03c_content_three_items` …); the page-type → single-file mapping in `executor-base.md §1` no longer covers them, so this section is the per-page truth.+> For a deck/layout template route, include one entry per page. Key: `P<NN>` matching §IX. Value: the template SVG basename without extension. Strict inherits it unchanged; adaptive uses it as the architecture reference and may output a new `pptx_layouts` key.>-> **No entry for a page** → that page is free design (no template inheritance). Mixed decks are supported: e.g., cover/chapter pages inherit a template while content pages are free.+> **No entry for a page** is valid only when the entire route is free design or brand-only. It is an error in template mode.>-> **Hard rule**: Use both `page_layouts` and `page_charts` for the same page only when the layout template is a compatible shell for the chart. Do not assign a conflicting layout just to fill every page: a waterfall chart should not inherit a timeline layout, and KPI cards should not inherit a circle-diagram layout unless that is the intended visual structure. When no compatible layout exists, omit the page from `page_layouts`.+> **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible shell. Adaptive mode may start from a neutral content template and create a new explicit Layout; strict mode must choose an existing compatible Layout or revise the outline.>-> **Whole section omitted** → entire deck is free design. Equivalent to no rows but cleaner; do this when zero pages reference a template.+> **Whole section omitted** → free design or brand-only route.>> **Strategist source**: copy the per-page SVG choices from `design_spec.md §VI Page Roster` (or §IX outline if Roster is absent). Names must match files in `templates/` exactly — typos cause silent fallback to free design.diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 44850c9f..18b79dc1 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -66,8 +66,8 @@ python3 skills/ppt-master/scripts/pptx_template_import.py "<reference_template.pThis produces, in one workspace:- `manifest.json` — single source of truth: slide size, theme colors, fonts, per-master theme summaries, asset inventory, placeholder metadata, SVG file paths, per-slide / per-layout / per-master metadata, page-type candidates-- `native_structure.json` — portable machine contract: stable master/layout keys, source package parts, layout picker names, placeholder type/index/geometry, source hash, and a template-packaging preserve-vs-rebuild recommendation-- `source_template.pptx` — byte-preserved source package paired with `native_structure.json`; required for downstream `pptx_structure.mode: preserve`+- `native_structure.json` — analysis contract: stable master/layout keys, layout picker names, placeholder type/index/geometry, source hash, and source-graph quality facts+- `source_template.pptx` — byte-preserved analysis copy for visual/package cross-checking; it is not copied into the final template package- `summary.md` — short human-readable digest derived from manifest.json (for quick scanning only)- `assets/` — extracted reusable image assets; `manifest.json` owns the asset-name mapping and SVG `href` values reuse that mapping- `svg/` — **primary view** (layered template view):@@ -95,7 +95,8 @@ Before the Template_Designer reads imported SVGs, factor large decorative vector# standard / fidelity analysis pathpython3 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-# mirror creation path+# mirror visual-copy path; also run the layered command above because Master/Layout+# ownership remains required for the rebuilt explicit structurepython3 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```@@ -115,7 +116,7 @@ The source SVGs in `<import_workspace>/svg/` / `<import_workspace>/svg-flat/` arInterpretation 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 native PowerPoint identity: stable layout keys, picker names, parent masters, placeholder types/indices, and the source-package hash. Its `recommendedMode` guides this template-creation workflow only; downstream deck generation confirms `strict` vs `adaptive` separately in the Strategist stage.+- `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.- `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.@@ -137,21 +138,18 @@ 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` strategy, masters/layouts, picker names, placeholder type/index, source slide mapping | Package the preserved contract when reusable; otherwise rebuild one master plus semantic layouts. Do not decide downstream strict/adaptive use here. |+| Native PowerPoint structure | `native_structure.json` source facts, masters/layouts, picker names, placeholder type/index, source slide mapping | Rebuild one clean Master plus semantic Layouts in complete, explicitly annotated SVG pages. |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** (`standard` / `fidelity` modes — `mirror` differs, see below):+**Hard read gate** (all replication modes):- 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 gateDo **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.-> **Mirror-mode fast path** — when the user has indicated mirror replication (verbatim copy of every source slide):-> - Run the vector illustration readability pass on `svg-flat/`, then read **only** the cleaned flat `slide_*.svg` files (the self-contained, what-PowerPoint-shows view) and `manifest.json` (for theme colors, fonts, asset inventory).-> - Skip `svg/master_*.svg` / `svg/layout_*.svg` / `svg/inheritance.json` — chrome / content separation is irrelevant in mirror mode (no placeholder insertion happens).-> - Mirror is explicitly a visual-verbatim copy flow: every slide becomes a template page as-is, except that large vector illustrations may be factored into `icons/` placeholders for maintainability. The "reconstruct, don't translate" rule applies to `standard` / `fidelity` only.+> **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.### 1B. Existing SVG assets@@ -209,7 +207,7 @@ Compose a single message that surfaces every Required brief item to the user, **| 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 packaging | For type A, show the `native_structure.json` recommendation and both choices: retain the source package (`preserve`) or rebuild explicit layouts (`template`). This is a library-package capability choice, not downstream strict/adaptive adherence. `mirror` cannot retain the native pair because its flat SVGs do not identify inherited layers. |+| Native structure reconstruction | For type A, summarize the source master/layout graph from `native_structure.json`, then state the fixed output policy: rebuild one clean Master plus explicit semantic Layouts (`template`). The source package is analysis input only. || 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 |@@ -225,7 +223,7 @@ Items to surface:| 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 (AI visual clustering / direct 1:1 copy — see Step 1 caveats); reject `fidelity` / `mirror` upfront for type C / D |-| Native structure strategy | Type A only | `[fact]` recommendation from `native_structure.json.strategy`; preserve (`preserve`) when the source graph is complete/reusable, rebuild (`template`) when minimal/incomplete. Force rebuild for `mirror`. |+| 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 || 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 |@@ -239,7 +237,7 @@ 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 native structure recommendation, including master/layout counts, multi-master status, and reason codes+- the source structure facts, including master/layout counts, multi-master status, and reason codes; state that the final package will rebuild one clean Master plus semantic LayoutsThe user replies with corrections, additions, or "all good".@@ -291,7 +289,7 @@ If the input source is type A, pass the following internal package to the role:- finalized brief from Step 3- `manifest.json`-- `native_structure.json` and `source_template.pptx`+- `native_structure.json` and `source_template.pptx` as read-only analysis inputs- `summary.md` (orientation only)- exported `assets/`- `*_vector_asset_inventory.json`, when the vector readability pass extracted assets; do not bulk-read `icons/*.svg`@@ -304,9 +302,9 @@ 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.-**Native structure packaging strategy**: When the confirmed strategy is `preserve`, copy `native_structure.json` and `source_template.pptx` unchanged into the final template directory. Author every template SVG with the source layout key/name on the root, source master/layout visuals as preview layers, and slide content as source-compatible placeholder markers. Preserve the importer's distinct `subtitle` / `object` / `media` / `date` roles and exact source indices instead of reducing them to body/other. This retains a future strict-use capability; it does not force every downstream deck to use it. When the strategy is `template`, do not copy the native pair; reconstruct one master plus semantic layouts through the explicit metadata contract. Mirror mode always takes this rebuild/baseline path because flat slides do not retain layer ownership.+**Native structure reconstruction**: Do not copy `native_structure.json` or `source_template.pptx` into the final template directory. Use their master/layout/placeholder facts to reconstruct one clean Master plus semantic Layouts through the explicit SVG metadata contract. Every emitted SVG is a complete standalone preview: repeat the identical Master layer, repeat the selected Layout layer for pages sharing a key, and keep actual content on the Slide with semantic placeholder markers.-Downstream, the Strategist confirmation stage owns template adherence. `strict` maps every generated page to this SVG roster and may activate `pptx_structure.mode: preserve`; `adaptive` may use only selected SVGs and always keeps native export on `baseline`, even though the pair remains available in the template directory.+Downstream, both template-adherence choices stay on `pptx_structure.mode: template`. `strict` preserves the selected template Layout contract. `adaptive` still references one template SVG per page, keeps the same Master contract, and may author a new explicit Layout key when the source roster has no suitable composition. It never falls back to baseline inside a template deck.**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.@@ -314,7 +312,7 @@ Downstream, the Strategist confirmation stage owns template adherence. `strict`**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:-1. **Copies the cleaned source pages** into the template directory **without reconstruction** — no content placeholder insertion, no decorative simplification, no chrome/content reorganization. The SVG that ships in the template is the cleaned source page, modulo filename changes, asset path rewrites, and the vector illustration placeholders created by the readability pass.+1. **Copies the cleaned source pages** into the template directory with literal visual fidelity — no content rewriting or decorative simplification. Then annotate the complete page with root Layout identity plus direct Master/Layout/placeholder metadata derived from the layered source. 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 input directory (already self-contained)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`.@@ -324,16 +322,16 @@ Downstream, the Strategist confirmation stage owns template adherence. `strict`- 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 paths4. **Copies `icons/` when present** and preserves every extracted `<use data-icon="..."/>` reference. 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 description per page is the load-bearing artifact** because mirror has no placeholders to advertise the per-page contract. Mirror is only the template-creation replication mode; downstream generation still treats the finished template package as a selectable / reusable roster, not as a forced 1:1 slide sequence.+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** invoke the "reconstruct into clean SVG" pathway. The sprite-sheet preservation rule still applies (because the flat SVGs already contain the original sprite wrappers — do not flatten them when copying). Vector illustration placeholders are the only allowed maintainability rewrite.+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.**Expected outputs from this step** (full spec → [template-designer.md](../references/template-designer.md)):1. `design_spec.md` — **personality only**. Required sections: Template Overview, Color Scheme, Signature Design Elements, Page Roster (matching the actual SVG files on disk). Skip Typography / Assets / Placeholder Overrides when they would just restate defaults. Declare brief frontmatter for `register_template.py`. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` / `fidelity` / `mirror` mode rosters, variant naming, and TOC handling3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.- - `{{...}}` placeholders are the authoring contract used to generate final slide content; they are not PowerPoint `p:ph` objects. For an explicitly requested reusable PowerPoint structure, use `pptx_structure.mode: template`. A package carrying `native_structure.json` + `source_template.pptx` may use `mode: preserve` only when downstream template adherence is confirmed as `strict`. `adaptive` use keeps `baseline`. Template/preserve modes require `pptx_layouts` and explicit root/layer/placeholder metadata; preserve-mode placeholders retain the source `data-pptx-placeholder-idx`.+ - `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native reconstruction contract: root `data-pptx-layout` / `data-pptx-layout-name`, direct Master/Layout layers, and direct semantic `data-pptx-placeholder` markers. Both strict and adaptive downstream use set `mode: template` and require `page_layouts` plus `pptx_layouts` for every page.4. Template assets (optional) — Logos / PNG / JPG / reference SVG bundled with the template package---@@ -357,7 +355,8 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/temp- skip `spec_lock.md` drift checks (templates do not ship a spec_lock)- enforce roster ↔ `design_spec.md` consistency as **errors** (orphan files / missing files break the target kind's index)- emit advisory **warnings** when a page lacks a conventional placeholder — these are hints, not failures. Declare a `placeholders:` block in `design_spec.md` frontmatter to silence them when your template intentionally uses a different vocabulary-- validate `native_structure.json` and `source_template.pptx` as an inseparable pair, including source hash, package layout parts, SVG layout keys/names, and placeholder compatibility+- require every SVG root to declare an output Layout and every SVG to contain at least one direct Master/Layout/placeholder declaration+- validate cross-page Master equality plus same-key Layout/placeholder equality**Checklist**:@@ -369,7 +368,8 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/temp- [ ] SVG `viewBox` matches the declared canvas dimensions, not just the aspect ratio (for `ppt169`: `0 0 1280 720`; for `banner`: `0 0 1920 1080`); `width` / `height`, if written, equal it- [ ] Placeholder names follow the canonical convention where applicable; templates with intentionally different vocabularies (e.g. `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`) should declare a `placeholders:` frontmatter block to silence advisory warnings- [ ] Asset files referenced by SVGs actually exist in the template package-- [ ] When native strategy is `preserve`, both `native_structure.json` and `source_template.pptx` exist; every SVG root references a contract layout key/name and every placeholder uses a compatible source type/index+- [ ] `design_spec.md` frontmatter declares `native_structure_mode: template`; no `native_structure.json` or `source_template.pptx` is packaged+- [ ] Every SVG root declares `data-pptx-layout` and `data-pptx-layout-name`; direct Master/Layout elements and semantic placeholders obey the explicit paint-order contract- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists directly under the package's `icons/` directory; 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: `ls templates/<kind_dir>/<id>/*_*.svg | wc -l` matches the cleaned flat `<import_workspace>/svg-flat/slide_*.svg | wc -l`; 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 "{{" templates/<kind_dir>/<id>/*.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@@ -417,11 +417,9 @@ The index file is a **discovery index** — it lets the AI answer "what template> source_canvas_width: 1280> source_canvas_height: 720> source_viewbox: "0 0 1280 720"-> # Type-A native retention capability only; omit all three rows for rebuilt templates.+> # All current deck/layout templates rebuild an explicit SVG structure.> # Downstream strict/adaptive use is confirmed by Strategist and is not stored here.-> native_structure_mode: preserve-> native_structure: native_structure.json-> source_template: source_template.pptx+> native_structure_mode: template> page_count: 5> primary_color: "#005587"> ---diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.mdindex ca5eab8f..738e2553 100644--- a/skills/ppt-master/workflows/routing.md+++ b/skills/ppt-master/workflows/routing.md@@ -22,6 +22,17 @@ Route selection authority for PPT Master. Use this file before entering the main**Forbidden - route-choice prompts**: Do not present multiple implementation paths when this file already defines the route. Ordinary style choices and finite options belong at the next existing confirmation gate.+### 1.1 SVG Page-Design Scope++| 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. |+| `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. |++**Hard rule**: Apply SVG page-design closure only after selecting an SVG-authoring route. Do not reroute a native PPTX operation merely to make every package-level capability pass through SVG.+---## 2. Main Route Matrix