| 1 | --- |
| 2 | description: Generate-PPTX runbook for validating, installing, or fusing selected Brand, Style, Layout, and Deck workspaces. |
| 3 | --- |
| 4 | |
| 5 | # Apply Template Workspace Stage |
| 6 | |
| 7 | > Run from [`generate-pptx.md`](../generate-pptx.md) Step 4 only after Stage 1 confirms at least one exact template workspace. [`quick-generate`](../profiles/quick-generate.md) enters only for exact roots or a current Create Template handoff. Never load for free design, bare names, or style descriptions. This stage applies the completed Stage-1 selection; it never chooses a workspace or changes the communication contract. |
| 8 | |
| 9 | ## 1. Gate and Normalize Inputs |
| 10 | |
| 11 | 🚧 **GATE**: Either Default Stage 1 confirmed a non-free template selection, or |
| 12 | Quick received exact roots directly from the |
| 13 | user/current Create Template handoff. In Quick, that explicit input is the complete selection authority: do |
| 14 | not launch Confirm UI or create `template_options.json`, |
| 15 | `template_selection.json`, or `template_handoff.json`. Every selected input must |
| 16 | resolve to one of these current contracts: |
| 17 | |
| 18 | | Input shape | Spec and SVG source | Asset source | |
| 19 | |---|---|---| |
| 20 | | Current workspace root | `<root>/templates/design_spec.md` and `<root>/templates/` | Existing `<root>/images/` and `<root>/icons/` | |
| 21 | | Compatible legacy-flat Brand/Layout/Deck root | `<root>/design_spec.md`; Layout/Deck also require current-contract SVGs under `<root>/` | Package-local files | |
| 22 | | Current Create Template handoff | Its exact validated library or project workspace root | Existing portable sibling `images/` and `icons/`; already installed only when the root is the target project | |
| 23 | |
| 24 | The spec frontmatter MUST declare `kind: brand`, `kind: style`, `kind: layout`, or `kind: deck`. Do not accept only another project's inner `templates/` directory because that omits sibling assets. |
| 25 | |
| 26 | **Selection-source classification**: |
| 27 | |
| 28 | | Source label | Resolution rule | |
| 29 | |---|---| |
| 30 | | `library` | The normalized root exactly equals `templates/<kind_dir>/<id>/` derived from an entry in that kind's `*_index.json` | |
| 31 | | `explicit` | The user or Create Template supplied an exact workspace root that is not registered at that canonical index-derived root | |
| 32 | |
| 33 | Read library choices only from `brands_index.json`, `styles_index.json`, |
| 34 | `layouts_index.json`, and `decks_index.json`. Never scan kind directories or |
| 35 | promote an unregistered directory into the UI catalog. An explicit root remains |
| 36 | valid without index membership; exact equality with a registered root may be |
| 37 | reported as `library`. The label changes discovery provenance only, never schema |
| 38 | validation, fusion precedence, or installation behavior. |
| 39 | |
| 40 | **Selection cardinality**: Default Stage 1 permits one registered root per kind plus one explicit root; its explicit root may pair with a same-kind library root under §5.2. Quick has no page or catalog selection and accepts at most one supplied exact root per declared kind (four roots total). Kinds compose freely in both profiles. Reject larger default receipts server-side; require an oversized or duplicate-kind Quick input to converge in chat before installation, never through Confirm UI. |
| 41 | |
| 42 | **Hard rule — raw source boundary**: A raw PPTX is not a template workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first; its validated workspace-root handoff becomes a Stage-1 candidate and is preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project. |
| 43 | |
| 44 | **Compatibility gate**: Reject semantic-legacy or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved. A legacy-flat Brand/Layout/Deck directory is readable only when it satisfies its current kind contract; Layout/Deck also require a current structured SVG contract. Style has no legacy-flat form and always requires `<root>/templates/design_spec.md`. |
| 45 | |
| 46 | ## 2. Read the Matching Schema |
| 47 | |
| 48 | Read [`templates/README.md`](../../templates/README.md), then only the README for each supplied kind: |
| 49 | |
| 50 | | Kind | Schema | Owned segment | |
| 51 | |---|---|---| |
| 52 | | `brand` | [`templates/brands/README.md`](../../templates/brands/README.md) | Identity: color, typography, logo, voice/tone, icon style | |
| 53 | | `style` | [`templates/styles/README.md`](../../templates/styles/README.md) | Direction/method: reusable communication method, visual language, composition, and information-expression defaults | |
| 54 | | `layout` | [`templates/layouts/README.md`](../../templates/layouts/README.md) | Structure: canvas, page structure, semantic text roles, page types, SVG roster | |
| 55 | | `deck` | [`templates/decks/README.md`](../../templates/decks/README.md) | Application plus integrated identity and structure | |
| 56 | |
| 57 | A Layout created with `mirror` remains eligible only when its source contract is brand-neutral and application-neutral. Keep a branded or application-bearing source as a Deck, or re-author it as Layout through `standard` / `fidelity`; do not remove those semantics through mirror. |
| 58 | |
| 59 | Before mapping any current workspace, run its shared package validator from the |
| 60 | workspace root. This is the same schema authority used during creation and |
| 61 | library registration; Brand/Style pass without SVG, while Layout/Deck validate |
| 62 | their roster and structure: |
| 63 | |
| 64 | ```bash |
| 65 | python3 skills/ppt-master/scripts/svg_quality_checker.py "<workspace_root>/templates" --template-mode |
| 66 | ``` |
| 67 | |
| 68 | Any error blocks installation. A compatible legacy-flat root uses its own root |
| 69 | as the checker target. |
| 70 | |
| 71 | ## 3. Structured Preflight |
| 72 | |
| 73 | Before copying a Deck or Layout workspace, inspect every SVG root and slot. Brand and Style workspaces are roster-free and skip this structured preflight: |
| 74 | |
| 75 | - Every page declares root Master/Layout keys and PowerPoint picker names. |
| 76 | - Master/Layout visuals are direct atoms, not generic layer `<g>` wrappers. |
| 77 | - Every non-composite slot is a top-level `<g>` with positive bounds and exactly one compatible carrier. |
| 78 | - A composite region uses an explicit `object` proxy; a zero-slot Layout is valid. |
| 79 | - The complete SVG contract is current. Reject a legacy semantic contract instead of repairing it in the target project. |
| 80 | |
| 81 | ## 4. Install a Single Workspace |
| 82 | |
| 83 | | Kind | Install behavior | |
| 84 | |---|---| |
| 85 | | `brand` | Install `templates/` plus existing `images/` and `icons/`; ignore `exports/`. Identity is constrained; structure remains free. | |
| 86 | | `style` | Install `templates/design_spec.md` only. Ignore sibling project scaffolding and reject a library Style carrying asset/review payloads. Expose reusable direction/method without identity truth, page prototypes, or native structure. Default Style-only and Style + Brand derive `template_reuse_scope: style` and stay flat; Style + Layout/Deck follows the selected structure plan. Quick always realizes the resolved combination as flat pages. A Style workspace never activates visual review. | |
| 87 | | `layout` | Install the same portable roots. Expose the actual reusable structure; Default Strategist later inspects the prototypes, while Quick's current agent uses them for immediate flat authoring decisions in active context. | |
| 88 | | `deck` | Install the same portable roots. Expose descriptive application context, identity, structure, and the actual prototype roster; Default Strategist or Quick's current agent compares them with the current communication contract and content, then derives the applicable plan. | |
| 89 | |
| 90 | For a compatible legacy-flat package, route SVG/spec/non-bitmaps to project `templates/`, bitmaps to project `images/`, and declared icons to project `icons/`. Do not infer legacy Master/Layout semantics from the flat directory shape. |
| 91 | |
| 92 | **Atomic install preflight**: |
| 93 | |
| 94 | 1. Resolve every source and destination path. |
| 95 | 2. Enumerate the complete mapping across `templates/`, `images/`, and `icons/`. |
| 96 | 3. Reject every destination collision before writing. |
| 97 | 4. Write the accepted mapping once; never use recursive copy as an implicit conflict policy. |
| 98 | |
| 99 | If the normalized source root equals the target project root, consume it in place and copy nothing. An in-place workspace cannot participate in multi-path fusion. Ignore source `exports/`; it contains review artifacts, not portable template inputs. Empty optional roots remain absent. |
| 100 | |
| 101 | **Hard rule — project-local consumer boundary**: After installation/fusion, |
| 102 | Default template-aware Strategist work in final Stage 2, Quick's current |
| 103 | agent before direct authoring, and every later role read only |
| 104 | `<project_path>/templates/` and the project-local `images/` / `icons/` pools. The original library or external root |
| 105 | is installation input, not a later prompt source. If source and target are the |
| 106 | same project root, that in-place root already satisfies this boundary. |
| 107 | |
| 108 | Template SVGs are authoring prototypes, not export-time overlays. The generated page remains complete in `svg_output/`; `page_layouts` selects the complete prototype and its explicit structure contract for authoring. |
| 109 | Quick instead realizes the selected prototypes into complete flat, Slide-local |
| 110 | SVGs and never writes `page_layouts` or Master/Layout/placeholder metadata. |
| 111 | |
| 112 | |
| 113 | ## 5. Fuse Multiple Workspace Paths |
| 114 | |
| 115 | Fuse different kinds or, in Default only, at most two same-kind roots. Resolve template segment/asset conflicts before writing. Never reinterpret, predict, or revise the confirmed Stage-1 communication contract here. Default obtains any additional material conflict decision through the active chat channel after Stage 1; this conditional resolution does not reopen template selection. Quick follows explicit conflict instructions; an unresolved material compatibility conflict is a hard prerequisite handled in chat, never by launching Confirm UI or by using path order. |
| 116 | |
| 117 | ### 5.1 Different Kinds |
| 118 | |
| 119 | Resolve four whole template segments. This table selects the installed starting owner; current user instructions and the caller's later consuming plan still govern project use: |
| 120 | |
| 121 | | Segment | Starting owner | |
| 122 | |---|---| |
| 123 | | Identity | Brand, otherwise Deck, otherwise unresolved until the consuming plan (Default final Stage 2 or Quick active context). Style color/type/icon/image values are direction candidates, never identity truth. | |
| 124 | | Structure | A compatible Layout, otherwise Deck, otherwise unresolved/free design until the consuming plan. Style owns no canvas, prototype, Master/Layout, slot, or page mapping. | |
| 125 | | Reusable application context | Deck only when present. Preserve it for the consuming comparison; it never becomes the current project's application contract. | |
| 126 | | Direction / method | Style when present, otherwise unresolved until the consuming plan. Actual Deck prototypes and Signature facts may inform compatibility, but Deck does not own the Style-only method segment. | |
| 127 | |
| 128 | Replace each selected segment wholesale; do not mix its fields implicitly. Brand or Deck identity replaces any identity-adjacent defaults carried by Style. A Style direction may adapt to that resolved identity, but cannot relabel its candidates as official brand facts. |
| 129 | |
| 130 | Before Layout overrides Deck structure, compare Deck's reusable roles with Layout roles, slots, and capacity. On mismatch, offer exactly three remedies: retain Deck structure, select another Layout, or omit Deck. Default resolves only this template-to-template conflict and must not reinterpret the confirmed Stage-1 communication contract; Quick compares against the current request/content and treats any unresolved material mismatch as a chat hard prerequisite. |
| 131 | |
| 132 | Before Style overlays Deck guidance, verify that its method serves Deck's reusable context and fits the selected structure. On mismatch, require omitting Style or choosing a compatible Style/structure; never silently weaken a segment. Default final Stage 2 separately checks the result against the confirmed project contract; Quick checks it against the current request/content before authoring. |
| 133 | |
| 134 | Field-level micro-adjustments such as a primary-color override are not workspace fusion. Default carries them into the normal final Stage-2 confirmation fields; Quick treats explicit adjustments as direct active-context authoring constraints. |
| 135 | |
| 136 | ### 5.2 Same Kind |
| 137 | |
| 138 | Default only: do not use path order as priority. Report every segment-level difference and ask the user to choose workspace A, workspace B, or select per segment. Only the per-segment choice opens a segment-by-segment resolution. Two Style workspaces conflict over the complete Direction / method segment. Do not resolve field-level conflicts here. Three or more same-kind paths require the user to converge to at most two. Quick accepts one root per kind and therefore never enters this subsection. |
| 139 | |
| 140 | ### 5.3 Fused Provenance |
| 141 | |
| 142 | Write one final `<project>/templates/design_spec.md`. Immediately under its H1, record every source kind/path, base or override role, and resolved segment conflict with its explicit authority: |
| 143 | |
| 144 | ```markdown |
| 145 | > **Fused from:** |
| 146 | > - deck: `templates/decks/example/` (base) |
| 147 | > - brand: `templates/brands/example/` (identity override) |
| 148 | > - style: `templates/styles/example/` (direction/method override) |
| 149 | > - layout: `templates/layouts/example/` (structure override) |
| 150 | > - conflicts resolved: Color Scheme from brand (user selected A) |
| 151 | ``` |
| 152 | |
| 153 | Single-path installs do not add provenance. Set fused frontmatter `kind` from the non-Style capability: `deck` when identity and structure are both present, `layout` for structure only, or `brand` for identity only. Use `kind: style` only for Style-only input. Adding Style to Brand, Layout, Deck, or Brand + Layout does not change that existing capability label; its Direction / method ownership stays explicit in the fused provenance and body. A project-local Brand + Layout fusion uses `kind: deck` for routing but is not automatically a reusable library Deck; its application remains current-project context. |
| 154 | |
| 155 | **Completion receipt**: Report `roots=<normalized roots>; sources=<library|explicit per root>; kinds=<kind per root>; segments=identity:<owner>,structure:<owner>,application_context:<owner>,direction:<owner>; install=<in-place|copied>; final_spec=<project_path>/templates/design_spec.md`. |
| 156 | |
| 157 | ## ✅ Template Workspace Applied |
| 158 | |
| 159 | - [x] Every selected input was an index-derived library root or an exact explicit/Create Template root satisfying a listed workspace contract |
| 160 | - [x] Every kind schema passed preflight; structured SVG checks ran only for Layout/Deck inputs |
| 161 | - [x] All collisions and fusion conflicts were resolved before one atomic install |
| 162 | - [x] `<project_path>/templates/` and any portable sibling assets are complete and are the only downstream template source |
| 163 | - [ ] **Next**: Default completes the template-selection handoff and continues [`generate-pptx.md`](../generate-pptx.md) Step 4 Stage 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2 |
| 164 |