Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(charts): keep concise usage in design spec references

hugohe398ff0e88177f
diff --git a/skills/ppt-master/references/executor-chart.md b/skills/ppt-master/references/executor-chart.md
index 2e20329e..c86e0ae5 100644
--- a/skills/ppt-master/references/executor-chart.md
+++ b/skills/ppt-master/references/executor-chart.md
@@ -14,7 +14,7 @@ For each selected `templates/charts/<key>.svg`, use its Skill-relative `referenc
Before drawing each page, look up whether `page_charts` supplies a page-local reference:
-- Entry present (e.g., `P09: timeline_horizontal`) → read `templates/charts/<key>.svg` for that page only, then realize §IX with or without its exact chart type; do not copy it verbatim or load the catalog.
+- Entry present (e.g., `P09: timeline_horizontal`) → read its §VII Usage and SVG for that page only; realize §IX without copying it or loading the catalog.
- No entry for this page → no catalog reference was selected. Follow the current §IX `Visualization` / `Layout`; design any declared custom visualization from scratch without inventing a §VII reference.
- Whole section absent → no catalog references were selected; §IX may still contain custom data charts or tables.
@@ -108,7 +108,7 @@ rg -n 'data-pptx-replace-with="(chart|table)"|<metadata type="application/json">
## 3. Visualization Reference
-§1 loads the SVG selected by `page_charts`; this section governs adaptation. For legacy wider §VII tables, bind by `Page | Template` and ignore extra fields.
+§1 loads the `page_charts` SVG. Usage gives page-local intent; §IX remains authoritative. Legacy wider rows keep Usage and ignore path/summary fields.
**Hard rule**: treat the loaded SVG as a page-local reference, not a required base. §IX and source data own the final information structure; never replicate the preview verbatim.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 4b8e7cbd..9285544a 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -302,14 +302,14 @@ python3 skills/ppt-master/scripts/chart_recall.py validate <key> [<key> ...]
A failed validation must be corrected with a recalled key. `no-template-match` is not a key and never appears in `page_charts`.
-**Section VII selection list**: §VII is an optional inventory of page-local catalog references. Include it only when at least one candidate is selected, and record only the page plus the exact returned template key. The path is deterministically `templates/charts/<key>.svg`; §IX remains authoritative for the page's intent and information structure. Do not copy summaries, paths, usage prose, runners-up, `no-template-match`, `n/a`, or no-reference explanations into §VII.
+**Section VII selection list**: when a reference is selected, write `Page | Template | Usage`; Usage is one short page-local purpose, not geometry. Omit §VII when none is selected, and never add path, summary, runners-up, `no-template-match`, or `n/a`. §IX remains authoritative.
**Native-ready boundary**: For every independent data chart or pure text-grid table, add `Native-ready: yes|no` to its §IX page block. Choose `yes` only when the confirmed requirement or artifact afterlife benefits from an editable native data object; otherwise keep the designed SVG with `no`. Conceptual rows and incidental sparklines, KPI trends, or insets omit the field; Executor never promotes them.
```markdown
-| Page | Template |
-| --- | --- |
-| P03 | line_chart |
+| Page | Template | Usage |
+| --- | --- | --- |
+| P03 | line_chart | Compare the source metrics over time |
```
**Flag native-preset candidates**: In the affected page's §IX `Layout` / `Visualization`, note when the content calls for a literal stock PowerPoint chevron, block arrow, standard flowchart node, callout, banner, or star. Executor still decides the exact preset under its native-shape branch; this note never creates a §VII row by itself.
@@ -425,7 +425,7 @@ Generate Step 4 owns this reference-first sequence. `design_spec.md` is the Stra
- **pptx_structure is mandatory**: Free-design, brand-only, and `template_reuse_scope: style` routes write `mode: flat`; a style-reference route may also record `template_reuse_scope: style` but omits every structure mapping and `template_adherence`. `template_reuse_scope: mirror|layout` writes `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.
- **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.
- **Structured template route**: When [`strategist-template.md`](./strategist-template.md) is active and reuse is `mirror|layout`, follow its complete Master/Layout/slot/prototype mapping rules.
- - **page_charts (write only for pages with a selected catalog reference)**: Project every `Page | Template` row in `design_spec.md §VII` one-to-one as `P<NN>: <template_key>`. This is a page-local reference lookup, not a type or geometry lock. No-match pages never appear here; if no reference is selected, omit the section even when §IX contains custom visualizations.
+ - **page_charts**: project each §VII row's `Page` and `Template` as `P<NN>: <template_key>`; Usage stays in the Design Spec. This is a page-local reference, not a type/geometry lock. Omit no-match pages and the empty section.
---
diff --git a/skills/ppt-master/scripts/docs/chart-recall.md b/skills/ppt-master/scripts/docs/chart-recall.md
index 287c6494..5f1352a7 100644
--- a/skills/ppt-master/scripts/docs/chart-recall.md
+++ b/skills/ppt-master/scripts/docs/chart-recall.md
@@ -43,8 +43,8 @@ The command is read-only. It exits `0` when every key exists and `1` when any ke
## Selection boundary
- Preserve the two-lens review: numeric/data pages and structural-information pages.
-- Keep §VII as a positive selection list: record only `Page | Template` for each selected returned key, and omit the whole section when no candidate is selected.
-- Derive `templates/charts/<key>.svg` from the selected key; keep page-specific use and adaptation in §IX rather than duplicating them in §VII.
+- Keep §VII as a positive selection list: record `Page | Template | Usage` for each selected key, and omit the whole section when no candidate is selected.
+- Make `Usage` one concise page-local purpose, not geometry or execution instructions; derive `templates/charts/<key>.svg` from the key and keep detailed adaptation in §IX.
- Never serialize `no-template-match`, an empty table, or a no-reference explanation into §VII.
-- Do not serialize returned summaries, paths, usage prose, or runners-up into new §VII tables. Legacy wider tables remain readable.
+- Do not serialize returned summaries, paths, or runners-up into new §VII tables. Legacy wider tables remain readable.
- Open the selected `<key>.svg` only as a reference for its mapped page; it does not lock type or geometry. Do not load unrelated catalog SVGs.
diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.md
index 259e3953..521b8cad 100644
--- a/skills/ppt-master/templates/charts/README.md
+++ b/skills/ppt-master/templates/charts/README.md
@@ -6,7 +6,7 @@ This directory contains the standardized SVG visualization templates used by PPT
[`charts_index.json`](./charts_index.json) is the single source of truth for the library: total count + one selection-rule `summary` per template (format: `"Pick for X. Skip if Y (use other_key)."`). [`chart_recall.py`](../../scripts/chart_recall.py) can recall a bounded candidate set from this live registry without maintaining a second category or keyword index.
-For one planned page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring summaries plus the explicit `no-template-match` option. The requested limit is a cap, not a padding target, and lexical confidence never expands the output automatically. At `high` / `medium`, the Strategist may keep `no-template-match` when no bounded candidate fits. At `low` / `none`, a fitting candidate needs no expansion, but the Strategist must rerun the same query once with `--semantic-fallback` before keeping `no-template-match`. A selected result creates one `Page | Template` row in §VII and one matching `page_charts` entry; its path is derived from the key and its page-specific use remains in §IX. The negative result stays inside planning: it creates no §VII row or `page_charts` entry, and the chosen fallback is described in the page's §IX block. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when Strategist uses this helper; maintainers may still open the registry directly when editing or auditing the catalog.
+For one planned page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring summaries plus the explicit `no-template-match` option. The requested limit is a cap, not a padding target, and lexical confidence never expands the output automatically. At `high` / `medium`, the Strategist may keep `no-template-match` when no bounded candidate fits. At `low` / `none`, a fitting candidate needs no expansion, but the Strategist must rerun the same query once with `--semantic-fallback` before keeping `no-template-match`. A selected result creates one `Page | Template | Usage` row in §VII and one matching `page_charts` entry; its path is derived from the key, while Usage is concise page-local intent and detailed adaptation remains in §IX. The negative result stays inside planning: it creates no §VII row or `page_charts` entry, and the chosen fallback is described in the page's §IX block. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when Strategist uses this helper; maintainers may still open the registry directly when editing or auditing the catalog.
## Authoring contract
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 75034743..f2ba1e5c 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -154,8 +154,8 @@ Use the §VII table only when at least one real catalog reference is selected. A
```markdown
## VII. Visualization Reference List
-| Page | Template |
-| --- | --- |
+| Page | Template | Usage |
+| --- | --- | --- |
## VIII. Image Resource List
@@ -163,7 +163,7 @@ Use the §VII table only when at least one real catalog reference is selected. A
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
```
-§VII records one optional reference for a specific page, not an execution instruction or deck-wide style. Every row contains one page and one returned catalog key. The Executor derives `templates/charts/<key>.svg`; §IX remains authoritative and may be realized without preserving the preview's type or geometry. Never emit an empty §VII, extra path / summary / usage / runners-up fields, a `no-template-match` / `n/a` row, or no-reference prose. When recall finds no fit, omit that page from §VII and describe the fallback in §IX. Legacy wider rows remain readable; new specs use this two-column form.
+§VII is an optional page-local reference list. Each row records the page, catalog key, and a short semantic Usage—not geometry. The key derives `templates/charts/<key>.svg`; §IX remains authoritative over final type and realization. Omit an empty §VII and never add path, summary, runners-up, `no-template-match`, or `n/a`. Put unmatched fallbacks in §IX. Legacy wider rows remain readable; new specs use these three columns.
For every independent data chart or pure text-grid table, add `- **Native-ready**: yes|no` to its §IX Slide block. Choose `yes` only when the confirmed requirement or artifact afterlife benefits from an editable native data object; otherwise use `no`. Conceptual visualizations and incidental sparklines, KPI trends, or insets omit this field and remain ordinary SVG.
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 303d6ec1..c7c068a9 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -70,7 +70,7 @@ Structured section value shapes:
- P01: 03_content
```
-Each new Design Spec §VII `Page | Template` row projects one-to-one into `page_charts` as a page-local reference lookup, not a type or geometry lock. Values must exist as keys in `charts/charts_index.json`; `no-template-match` stays out of both sections while its fallback remains in §IX.
+Project each §VII `Page | Template | Usage` row's first two fields into `page_charts`; Usage stays in the Design Spec. This is a page-local reference, not a type/geometry lock. Keys must exist in `charts/charts_index.json`; no-match stays in §IX.
Typography projection is role-for-role, not a lossy summary:
diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.md
index ccb6b6f3..d957b857 100644
--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md
+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md
@@ -208,7 +208,7 @@ python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait
After the final wait returns, read `<project_path>/confirm_ui/result.json` exactly once and retain the complete confirmed object through Design Spec authoring. Chat is the canonical fallback when the page cannot open (remote / headless) — present the same fields in chat and retain the reply identically. Always run `--shutdown` on exit (page-confirm or chat-fallback) so port 5050 is free for Step 6 live preview.
-On confirmation, enter [`generate-pptx`](../generate-pptx.md) Step 4 as Strategist with the plan pre-resolved. The two beautify invariants always hold: the content-faithful clause ([`strategist.md`](../../references/strategist.md) §d Layer 1) and page count = source slide count (strict 1:1). Write the retained confirmed object completely into `design_spec.md` — `mode` (recommended `briefing`), canvas, `visual_style`, color (e) + typography (g) incl. `body_size` (the reviewed values; skip both recommendation flows) — honoring whatever the user kept or overrode. Do not reopen `result.json` afterward. §VII contains only `Page | Template` rows for selected catalog references; unmatched chart/table plans stay in their §IX page blocks. §VIII contains source pictures for re-layout.
+On confirmation, enter [`generate-pptx`](../generate-pptx.md) Step 4 as Strategist with the plan pre-resolved. The two beautify invariants always hold: the content-faithful clause ([`strategist.md`](../../references/strategist.md) §d Layer 1) and page count = source slide count (strict 1:1). Write the retained confirmed object completely into `design_spec.md` — `mode` (recommended `briefing`), canvas, `visual_style`, color (e) + typography (g) incl. `body_size` (the reviewed values; skip both recommendation flows) — honoring whatever the user kept or overrode. Do not reopen `result.json` afterward. §VII contains only `Page | Template | Usage` rows for selected catalog references; unmatched chart/table plans stay in their §IX page blocks. §VIII contains source pictures for re-layout.
**Hard rule — §IX is verbatim and 1:1**: each source slide becomes exactly one page, in source order, its text transcribed word-for-word from `sources/<stem>.md`. Do not merge, split, drop, or rewrite. Complete and audit `design_spec.md` first, then author `spec_lock.md` from that Design Spec plus the source/page/template context per `strategist.md` §6 before handing off to the Executor.