AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs(template-workspaces): align portable template routing
hugohe37c90b47b8ce7
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex eb253165..8c0ec9e7 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -219,7 +219,7 @@ Multi-deck: several PPTX files may be imported into one main-pipeline project**Default — free design.** Proceed directly to Step 4. Do NOT query any `*_index.json` unless triggered. Do NOT ask the user. Do NOT proactively suggest, hint at, or fuzzy-match any template based on content, slug-like words, or vague style descriptions.-**Hard boundary — raw PPTX template references are not Step 3 templates.** PPTX-as-source remains valid in Step 1 / Step 2, and raw PPTX template + generated PPTX routes to `template-fill`. But if the user wants the SVG/template-based generation route from that PPTX, stop before Step 3. The user must first run [`workflows/create-template.md`](workflows/create-template.md), then return with the generated template workspace path. Step 3 consumes an explicit workspace whose `templates/design_spec.md` declares `kind: layout` / `kind: deck`, a direct brand package, or a legacy flat package whose root `design_spec.md` declares one of those kinds.+**Hard boundary — raw PPTX template references are not Step 3 templates.** PPTX-as-source remains valid in Step 1 / Step 2, and raw PPTX template + generated PPTX routes to `template-fill`. But if the user wants the SVG/template-based generation route from that PPTX, stop before Step 3. The user must first run [`workflows/create-template.md`](workflows/create-template.md), then return with the generated template workspace path. Step 3 consumes an explicit workspace whose `templates/design_spec.md` declares `kind: brand` / `kind: layout` / `kind: deck`, or a compatible legacy-flat package whose root `design_spec.md` declares one of those kinds.Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use `template-fill` for raw PPTX template + generated PPTX requests; use `beautify` only when the source deck's page count, order, and wording are preserved.@@ -227,7 +227,7 @@ Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use| User input contains | Step 3 action ||---|---|-| One or more explicit template workspace paths (each resolves to `templates/design_spec.md`, or to a legacy/direct root `design_spec.md`, with `kind: brand` / `kind: layout` / `kind: deck` in YAML frontmatter) | Normalize each source directory, read its `kind`, dispatch per the kind matrix below, fuse if multiple |+| One or more explicit template workspace paths (each resolves to `templates/design_spec.md`, or to a compatible legacy-flat root `design_spec.md`, with `kind: brand` / `kind: layout` / `kind: deck` in YAML frontmatter) | Normalize each source directory, read its `kind`, dispatch per the kind matrix below, fuse if multiple || Current `create-template` workflow just completed project scope and validated its exact `<project>/` workspace | Consume that single workspace in place; it cannot join multi-path fusion || Anything else — bare template names ("用 academic_defense"), style descriptions ("麦肯锡风格"), brand mentions ("招商银行风格"), vague intent ("想用个模板"), or silence | Skip Step 3, free design |@@ -249,7 +249,7 @@ The architecture has three independent reference bundles. Full schema in [`docs/| Kind | Physical dir | Contains | Frontmatter ||---|---|---|---|-| **brand** | `templates/brands/<id>/` (direct package; `create-brand` contract) | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` |+| **brand** | `templates/brands/<id>/templates/` inside a complete workspace | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` || **layout** | `templates/layouts/<id>/templates/` inside a complete workspace | structure-only segment: canvas / page structure / page types / SVG roster | `kind: layout` || **deck** | `templates/decks/<id>/templates/` inside a complete workspace | full replica: identity + structure + middle (template overview) segments | `kind: deck` |@@ -265,27 +265,26 @@ The architecture has three independent reference bundles. Full schema in [`docs/| User path's `kind` | Step 3 action ||---|---|-| `kind: brand` | Install the direct package's spec/non-image assets in `<project>/templates/` and bitmaps in `<project>/images/`. Strategist locks identity; structure stays free. |-| `kind: layout` | Install the workspace's `templates/`, `images/`, and `icons/` into the matching project roots; ignore `exports/`. Strategist locks structure; identity is decided in confirmation fields e–g. |-| `kind: deck` | Install the workspace's `templates/`, `images/`, and `icons/` into the matching project roots; ignore `exports/`. Strategist locks all segments; confirmation narrows to deck-content fields. |+| `kind: brand` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Strategist locks identity; structure stays free. |+| `kind: layout` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Strategist locks structure; identity is decided in confirmation fields e–g. |+| `kind: deck` | Install `templates/` plus any existing `images/` and `icons/` into the matching project roots; ignore `exports/`. Strategist locks all segments; confirmation narrows to deck-content fields. |Normalize every explicit path before any write:| Input shape | Spec / SVG source | Asset source | Install rule ||---|---|---|---|-| Current Layout/Deck workspace: `<root>/templates/design_spec.md` | `<root>/templates/` | `<root>/images/`, `<root>/icons/` | Map those three roots to the target project's matching roots; ignore `<root>/exports/` |-| Direct Brand package: `<root>/design_spec.md`, `kind: brand` | `<root>/` | Package-local files | Spec/non-bitmap assets → project `templates/`; bitmaps → project `images/` |-| Compatible legacy-flat Layout/Deck: `<root>/design_spec.md` | `<root>/` | Package-local files | Preserve the existing flat-package routing: SVG/spec/non-bitmaps → project `templates/`; bitmaps → project `images/`; route declared icons to project `icons/` |+| Current workspace: `<root>/templates/design_spec.md` | `<root>/templates/` | Any existing `<root>/images/`, `<root>/icons/` | Map the existing portable roots to the target project's matching roots; ignore `<root>/exports/` |+| Compatible legacy-flat package: `<root>/design_spec.md` | `<root>/` | Package-local files | SVG/spec/non-bitmaps → project `templates/`; bitmaps → project `images/`; route declared icons to project `icons/` |**Atomic install preflight (mandatory)**: Resolve source and destination paths, enumerate the complete file mapping, and reject every destination collision before copying any file. Equality between a current project workspace root and the target project root means in-place consumption and no copy. For an external single path, a collision stops Step 3 rather than overwriting. For multi-path fusion, do not copy packages sequentially: resolve segment conflicts and asset-name conflicts first, construct one final mapping, then write it once. Never use recursive copy as an implicit conflict policy.Never infer that a flat directory has legacy Master/Layout semantics solely from packaging.-The same current-workspace split applies to layout and deck: source/spec in `templates/`, bitmaps in `images/`, runtime vectors in `icons/`, review artifacts in `exports/`. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.+The same current-workspace routing applies to all three kinds: source/spec in `templates/`, visual assets in `images/`, runtime icons in `icons/`, and review artifacts in `exports/`. Empty optional roots are omitted rather than retained with placeholder files. Brand workspaces normally have no `exports/` because they have no SVG roster. The spec's `kind` tells Strategist how to read the installed source. Template SVGs are not export-time overlays: visible output still lives completely in `svg_output/`. Their complete visuals and explicit Master/Layout/placeholder metadata are nevertheless the authoring prototypes selected by `page_layouts`.When `create-template` used project output scope, its workspace root is the target project itself and all core directories are already final. Resolve both roots before copying: equality means **in-place consumption**, so skip the installation. An in-place workspace cannot participate in multi-path fusion; use external workspaces for fusion. Never place the local source under a nested `templates/local_master/` directory because the confirmation and quality gates read the project `templates/` root.-A project-scoped workspace has the same portable core structure as a library workspace. It may be copied or promoted across roots as one unit (`templates/`, `images/`, `icons/`); `exports/` stays review-only. Do not pass only another project's `templates/` subdirectory because that would omit sibling assets.+A project-scoped workspace has the same portable routing as a library workspace. It may be copied or promoted across roots as one unit (`templates/` plus any existing `images/` and `icons/`); `exports/` stays review-only. Do not pass only another project's `templates/` subdirectory because that would omit sibling assets.Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy or consume those semantic contracts through Step 3. Run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) on the package first, then return with the migrated workspace path. Old flat packaging remains readable when its SVG structure is already current.diff --git a/skills/ppt-master/templates/brands/README.md b/skills/ppt-master/templates/brands/README.mdindex fc2acc4d..bdb37f28 100644--- a/skills/ppt-master/templates/brands/README.md+++ b/skills/ppt-master/templates/brands/README.md@@ -6,11 +6,11 @@ Brand is one of three template kinds in the library — alongside [`layouts/`](.## How brands are consumed-Brand application follows the **same explicit-path rule as all template kinds** at SKILL.md Step 3, and lands in the **same project directory** (`<project_path>/templates/`):+Brand application follows the **same explicit-path rule and workspace routing as all template kinds** at SKILL.md Step 3:| User input at SKILL.md Step 3 | Behavior ||---|---|-| An explicit brand directory path (e.g. `templates/brands/anthropic/`) | Copy `design_spec.md` + logo files + asset subdirectories into `<project_path>/templates/`; Strategist locks identity segment |+| An explicit brand workspace path (e.g. `templates/brands/anthropic/`) | Resolve `templates/design_spec.md`; stage `templates/`, `images/`, and `icons/` into the matching project directories; Strategist locks the identity segment || Bare brand name only ("use anthropic brand"), brand mention without path, or silence | Skip — same mechanical rule as all template kinds: bare names never trigger || Brand path + layout path | Fuse into one `design_spec.md` — brand owns identity segment (color / typography / logo / voice / icon style); layout owns structure segment (canvas / page roster). See `SKILL.md` Step 3. || Brand path + deck path | Fuse — brand identity overrides deck identity; structure + middle segments come from deck |@@ -29,25 +29,24 @@ Read skills/ppt-master/workflows/create-brand.mdThree input paths are supported: brand asset (logo / brand site URL / branded PPTX / brand PDF), verbal spec dictated in chat, or empty skeleton for the user to fill in later.-## Package structure+## Workspace structure-Every brand directory is self-contained:+Every brand uses the same workspace routing as layout and deck templates. Brand identity remains roster-free; omit empty optional directories instead of adding placeholder files.```templates/brands/<brand_id>/-├── design_spec.md # required — brand identity spec (7 sections)-├── logo.<ext> # optional — primary brand logo (single-lockup brands)-│ …or…-├── <brand>_wordmark.<ext> # optional — wordmark variant (dual-lockup brands)-├── <brand>_mark.<ext> # optional — symbol / icon variant (dual-lockup brands)-├── images/ # optional — branded photos-├── illustrations/ # optional — branded illustrations-└── icons/ # optional — branded icon overrides+├── templates/+│ └── design_spec.md # required — brand identity spec+├── images/ # optional — logos and visual assets+│ ├── logo.<ext> # optional — primary logo+│ └── <brand>_wordmark.svg # optional — alternate lockups and visual assets+├── icons/ # optional — branded icon overrides+└── exports/ # optional local derived artifacts; Git-ignored```-Logo filenames are descriptive, not contractual — `design_spec.md` §IV lists the exact files and the contexts in which each is used. Single-lockup brands typically ship one `logo.<ext>`; dual-lockup brands (e.g. Google's wordmark + G mark) ship separately named files.+Logo filenames are descriptive, not contractual — `templates/design_spec.md` §IV lists exact `../images/...` paths and usage contexts. Single-lockup brands typically ship one logo; dual-lockup brands ship separately named files.-`design_spec.md` carries a YAML frontmatter block with `kind: brand` and is the single source of truth for the brand identity. The six required sections are: I Brand Overview / II Color Scheme / III Typography / IV Logo / V Voice & Tone / VI Icon Style.+`templates/design_spec.md` carries a YAML frontmatter block with `kind: brand` and is the single source of truth for the brand identity. The six required sections are: I Brand Overview / II Color Scheme / III Typography / IV Logo / V Voice & Tone / VI Icon Style.## Discovery indexdiff --git a/skills/ppt-master/workflows/create-brand.md b/skills/ppt-master/workflows/create-brand.mdindex 8d86b90c..7e92864d 100644--- a/skills/ppt-master/workflows/create-brand.md+++ b/skills/ppt-master/workflows/create-brand.md@@ -1,10 +1,10 @@----description: Generate a brand-only template under `templates/brands/<id>/` — a design_spec.md that captures the user's colors / typography / logo / voice / icon style without an SVG page roster, so subsequent PPT projects inherit brand identity while keeping page layout free.+description: Generate a brand-only workspace under `templates/brands/<id>/` that captures colors, typography, logos, voice, and icon style without an SVG page roster.---# Create Brand Workflow-> Standalone preset-creation workflow. Output is a brand template package at `skills/ppt-master/templates/brands/<brand_id>/`. Structurally a brand is a template minus the SVG page roster — Strategist locks the brand's color / typography / logo / voice as truth; Executor designs pages freely under those constraints.+> Standalone preset-creation workflow. Output is a complete brand workspace at `skills/ppt-master/templates/brands/<brand_id>/`. A brand keeps the common workspace shape but omits the SVG page roster: Strategist locks identity while Executor designs pages freely.This workflow edits the global brand library, not any specific `projects/<x>/`. Consumption follows the same explicit-path rule as layout templates (see [Downstream consumption](#downstream-consumption-informational) at the end).@@ -14,7 +14,7 @@ This workflow edits the global brand library, not any specific `projects/<x>/`.| User signal | Action ||---|---|-| "set up brand" / "extract brand from this logo" / 建立品牌 / 做品牌规范 | Run this workflow |+| "set up brand" / "extract brand from this logo" | Run this workflow || User provides a brand asset (logo / brand site URL / branded PPTX / brand PDF) and wants it locked across future projects | Run this workflow || User mentions brand color or font once for a single deck only | Skip — handle inline via Strategist h.5 || `templates/brands/<requested_id>/` already exists | Ask: update / replace / use a new id — never silently overwrite |@@ -66,7 +66,7 @@ Whatever the user gives is `[user]`-labelled. Skip Step 3 unless the user explic## Step 2C: Empty skeleton-Write `templates/brands/<brand_id>/design_spec.md` with the full schema, every value as a TODO comment. Tell the user where the file is. No further prompting — the user owns it from here.+Write `templates/brands/<brand_id>/templates/design_spec.md` with the full schema, every value as a TODO comment. Tell the user where the file is. No further prompting — the user owns it from here.---@@ -85,15 +85,15 @@ For fields not covered by the asset, ask the user in a single bundled message. S----## Step 4: Materialize the brand package+## Step 4: Materialize the brand workspace-Create the package directory:+Create the required template source directory. Create `images/`, `icons/`, or `exports/` only when writing a real asset or derived artifact; never add placeholder files for empty directories.```bash-mkdir -p "skills/ppt-master/templates/brands/<brand_id>"+mkdir -p "skills/ppt-master/templates/brands/<brand_id>/templates"```-### Mandatory: `design_spec.md`+### Mandatory: `templates/design_spec.md````markdown---@@ -132,7 +132,7 @@ primary_color: "#XXXXXX"| mono | <family> | optional |## IV. Logo-- File: `./logo.<ext>` (relative to this design_spec.md)+- File: `../images/logo.<ext>` (relative to this design_spec.md)- Usage: cover-only \| every-page \| never## V. Voice & Tone@@ -145,28 +145,27 @@ primary_color: "#XXXXXX"- Preference: linear \| filled \| duotone # optional, drives icon library search## VII. Visual Assets (optional)-- Images: `./images/` # branded photos, prioritised before AI image generation-- Illustrations: `./illustrations/` # branded illustrations, prioritised before AI generation-- Icons: `./icons/` # branded icon overrides; falls back to `templates/icons/`+- Images and illustrations: `../images/` # brand visual assets+- Icons: `../icons/` # branded icon overrides```**Section scope rules**:-- Layout / canvas / spacing / radius / shadow / page roster / signature design elements are OUT of brand scope. Those live in layout / deck templates (`templates/layouts/<id>/design_spec.md` or `templates/decks/<id>/design_spec.md`) or `shared-standards.md`. Do NOT add those sections here.+- Layout / canvas / spacing / radius / shadow / page roster / signature design elements are OUT of brand scope. Those live in layout / deck workspaces (`templates/layouts/<id>/templates/design_spec.md` or `templates/decks/<id>/templates/design_spec.md`) or `shared-standards.md`. Do NOT add those sections here.- HEX must be `#RRGGBB`- Font names are free strings; not validated against locally installed fonts- §VII is fully optional — list only directories that actually exist### Optional: logo file-If the user provided a logo, copy it to `templates/brands/<brand_id>/logo.<ext>` (preserve source extension).+If the user provided a logo, copy it to `templates/brands/<brand_id>/images/logo.<ext>` and preserve its source extension. Use descriptive filenames when several lockups exist.### Optional: visual asset directories-If the user provided brand photo / illustration / icon folders, copy them as `images/` / `illustrations/` / `icons/` under `templates/brands/<brand_id>/`. Reference each in §VII of `design_spec.md`. Skip the entire section if none exist.+Copy brand photos and illustrations into the workspace `images/` directory. Copy branded icon overrides into `icons/`. Reference only directories and assets that actually exist in §VII of `templates/design_spec.md`.### NOT created here-No SVG page roster. No canvas spec. No signature design elements. If the user later wants brand-anchored page templates, run `create-template.md` with this brand as a style reference.+No SVG page roster, canvas spec, signature design elements, or preview PPTX. Do not create an empty `exports/` directory. If the user later wants brand-anchored page templates, run `create-template.md` with this brand as a style reference.---@@ -189,16 +188,16 @@ Emit the confirmation card:```markdown## ✅ Brand Saved- Path: `skills/ppt-master/templates/brands/<brand_id>/`-- Files: design_spec.md{, logo.<ext>}{, images/}{, illustrations/}{, icons/}+- Files: templates/design_spec.md{, images/logo.<ext>}{, images/*}{, icons/*}- Fields locked: <list>- Provenance: <fact / approx / user counts>How to use in a project:-- Include the brand directory path in your initial Step 3 input — e.g. "做一个 Q4 总结 PPT, 用 skills/ppt-master/templates/brands/<brand_id>/ 这个品牌"+- Include the brand workspace path in the initial Step 3 input, for example: "Create a Q4 summary using skills/ppt-master/templates/brands/<brand_id>/"- Same explicit-path rule as layout templates: bare brand names never trigger- May be supplied together with a layout template path; Step 3 fuses both into a single `design_spec.md` (brand wins on identity tokens, layout wins on page structure) — see `SKILL.md` Step 3- To list available brands: open `templates/brands/brands_index.json`-- To edit: modify `templates/brands/<brand_id>/design_spec.md` directly, then re-run `python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id>`+- To edit: modify `templates/brands/<brand_id>/templates/design_spec.md`, then re-run `python3 skills/ppt-master/scripts/register_template.py --kind brand <brand_id>````---@@ -209,7 +208,7 @@ Brand application happens in [`SKILL.md` Step 3](../SKILL.md) under the **same e| User input at SKILL.md Step 3 | Behavior ||---|---|-| Explicit brand directory path supplied | Step 3 copies the brand into `<project_path>/templates/` (same target as a layout template); Strategist locks color / typography / logo / voice as truth at Step 4 |+| Explicit brand workspace path supplied | Step 3 resolves `templates/design_spec.md`, stages `templates/`, `images/`, and `icons/` into their project peers, and locks color / typography / logo / voice as truth at Step 4 || Bare brand name, brand mention without path, or silence | Skip — no auto-application based on directory count or any other implicit signal || Both a brand path and a layout template path supplied in the same message | Step 3 fuses both into a single `design_spec.md` inside `<project_path>/templates/` (brand wins on identity tokens, layout wins on page structure). See `SKILL.md` Step 3 for the field-precedence table and the two conflict gates that may surface a clarifying question |@@ -220,7 +219,7 @@ Brand application happens in [`SKILL.md` Step 3](../SKILL.md) under the **same e## Notes1. **Brand is identity, not layout** — colors / typography / logo / voice / icon style only. Page roster, canvas spec, and signature design elements belong to layout templates; do not duplicate them here.-2. **Self-contained package** — all brand assets (logo, images, illustrations, icons) live inside `templates/brands/<brand_id>/`. Nothing leaks to workspace root or `projects/`.+2. **Common workspace routing** — brand assets use the same `templates/`, `images/`, `icons/`, and `exports/` routes as other template kinds; empty optional directories are omitted.3. **No script dependency** — Step 2A reuses existing converters plus AI inline reading. A dedicated `brand_extract.py` is not introduced unless future user feedback demands batch processing or precise color picking from raster logos.4. **Multi-brand support** — `templates/brands/` accepts any number of brands; agency / freelancer / multi-client workflows are natural.5. **Precedence rule** — when a brand and a layout template both apply, Step 3 fuses them into one `design_spec.md`: brand wins on color / typography / logo / voice / icon style; layout wins on canvas / page roster / spacing / font-size hierarchy / signature visual elements. See `SKILL.md` Step 3 for the full precedence table.