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

refactor(visualizations): align planning and execution families

hugohe3047129422ff3
diff --git a/docs/roadmap.md b/docs/roadmap.md
index c0c7415b..eb9333fc 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -70,7 +70,7 @@ The Generate PPTX route is built around full control of newly authored shapes, t
Pixel-fidelity across the four renderers (PowerPoint / Keynote / LibreOffice / WPS) is the project's spine. Switching the default route to native PowerPoint charts breaks that — the same PPTX renders different chart layouts across renderers. Charts as SVG is **by design**, not a capability gap.
-The narrow exception is the `data-pptx-replace-with` marker: independently planned supported data charts and pure text-grid tables can carry a PowerPoint-native Chart/Table replacement payload when their Design Spec §IX page block says `Native-ready: yes`; `no` and incidental microvisuals remain ordinary shapes. §VII only records selected reusable references. Exporting with `--native-charts-and-tables` activates prepared markers for users who deliberately trade cross-renderer fidelity for a data-backed object and its chart/table-specific editing model — the activated objects preserve the deck's chart-area / plot / axis / gridline / label colors and native table formatting rather than snapping to PowerPoint's default theme (see the [v4.0.0 release notes](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0)). The default export path and editable SVG-derived shape system are unchanged.
+The narrow exception is the `data-pptx-replace-with` marker: independently planned supported data charts and pure text-grid tables can carry a PowerPoint-native Chart/Table replacement payload when their semantic object key is recorded as `<object-key>=yes` in the Design Spec §IX `Native-ready` map; `no` and incidental microvisuals remain ordinary shapes. §VII only records selected reusable references. Exporting with `--native-charts-and-tables` activates prepared markers for users who deliberately trade cross-renderer fidelity for a data-backed object and its chart/table-specific editing model — the activated objects preserve the deck's chart-area / plot / axis / gridline / label colors and native table formatting rather than snapping to PowerPoint's default theme (see the [v4.0.0 release notes](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0)). The default export path and editable SVG-derived shape system are unchanged.
### uv as default / required dependency
diff --git a/docs/technical-design.md b/docs/technical-design.md
index ae42bab1..dba804b4 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -460,7 +460,7 @@ When several workspaces are selected, each installs as its own spec file and own
**Raw PPTX files cannot be Step 3 workspaces.** Normal Generate may use a PPTX as source material, and `beautify-pptx` may redesign it while preserving page count, order, and per-page wording 1:1; neither treats the source PPTX as a Step 3 template. When a raw PPTX is used as a template or native slide shell and filled with new material, the default route is Fill Native PPTX. If the request permits splitting, merging, dropping, reordering, or narrative restructuring, it remains Generate. Only a request to create a reusable template workspace and reuse that design system in SVG-route Step 3 first runs Create Template and then supplies the generated workspace root.
-**Template contracts are opt-in; charts and icons are not.** The asymmetry is intentional: Layout locks reusable structure, Style locks direction/method defaults, Brand locks identity, and Deck combines a recurring application with identity and structure. Charts and icons are reusable primitives that do not by themselves impose a deck-wide contract. Same `templates/` directory, different ownership.
+**Template contracts are opt-in; Visualization references and icons are not.** The asymmetry is intentional: Layout locks reusable structure, Style locks direction/method defaults, Brand locks identity, and Deck combines a recurring application with identity and structure. Page-local Chart, Structure, and Table references plus icons are reusable primitives that do not by themselves impose a deck-wide contract. Same `templates/` directory, different ownership.
---
@@ -513,9 +513,9 @@ Why both? `design_spec.md` preserves the complete confirmed solution and rationa
The view omits universal SVG/icon prohibitions already owned by the always-loaded Executor core and retains only project-specific forbidden rows. It selects images from the current page brief, explicit image-resource page assignments, and mirror prototype references. Images assigned elsewhere are excluded; any unresolved legacy image remains in a compatibility subset, and `confirmed-none` appears only when every locked image has a deterministic assignment elsewhere.
-The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (the selected page-local chart-catalog reference, which triggers reading the corresponding SVG and §VII Usage but does not lock the final chart type or geometry), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values that decide which execution rule files are loaded. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. When it actually combines or borrows catalog entries, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`, and execution reads every listed file before synthesis; a genuinely novel custom omits the corresponding reference field. `template_reuse_scope: mirror|layout` locks additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
+The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_visualizations` (the selected page-local `chart|structure|table/<key>` reference, which triggers reading the corresponding family SVG and §VII Usage but does not lock the final information model, type, or geometry), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values that decide which execution rule files are loaded. Legacy `page_charts` remains readable but is not written by new planning. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. When it actually combines or borrows catalog entries, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`, and execution reads every listed file before synthesis; a genuinely novel custom omits the corresponding reference field. `template_reuse_scope: mirror|layout` locks additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no visualization or no image is often a design decision rather than missing data.
-`page-context v2` remains an on-demand projector. Each invocation emits a compact global anchor set bound to `lock_source.sha256`, the current §IX/resource/routing delta, and scoped path/SHA fingerprints for large references; the projection is not a color/font allowlist or a replacement authority. It is used only for explicit diagnostics/telemetry or an unresolved page/template/chart path-SHA question. A bounded exact repair in a valid uncompacted context may use targeted fragment readback plus validation; fresh, compacted, external, unknown, structural, or mismatched changes require one complete Design Spec and lock read. Flat pages have no prototype reference; structured pages use the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.
+`page-context v2` remains an on-demand projector. Each invocation emits a compact global anchor set bound to `lock_source.sha256`, the current §IX/resource/routing delta, and scoped path/SHA fingerprints for large references; the projection is not a color/font allowlist or a replacement authority. It is used only for explicit diagnostics/telemetry or an unresolved page/template/visualization path-SHA question. A bounded exact repair in a valid uncompacted context may use targeted fragment readback plus validation; fresh, compacted, external, unknown, structural, or mismatched changes require one complete Design Spec and lock read. Flat pages have no prototype reference; structured pages use the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.
`--record-usage` writes a derived, input-hashed compact-output snapshot for an invoked page under `analysis/page-context/`. Token counting lazily uses `o200k_base`; a missing `tiktoken` installation records `tokens: null` without blocking execution. `page-context-report` excludes stale snapshots, reports existing snapshots, and lists unique reference fingerprints; telemetry may be partial. The once-loaded reference payloads and other session context remain intentionally unmeasured.
@@ -759,7 +759,7 @@ These direct routes share some analysis primitives with the main pipeline, but a
**Why each template SVG stays complete while still compiling to native structure.** A template SVG repeats the inherited Master/Layout visuals together with sample Slide content so it opens as a complete standalone page. During generation, `page_layouts` selects that prototype and the output SVG remains complete. Export removes repeated inherited atoms, emits real Master/Layout parts, and leaves actual slot carriers and Slide-local content on the Slide.
-**Why PowerPoint-native Chart/Table reconstruction uses explicit replacement markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer emits a visible SVG fallback plus `data-pptx-replace-with` and `<metadata type="application/json">` only for validated table/chart subsets. Generated decks prepare that pair only when Strategist marks the §IX page block `Native-ready: yes`; §VII remains a positive catalog-reference inventory, and a catalog marker is a capability example rather than an execution decision. The parent marker determines the payload schema; ordinary shapes and connectors never use this contract. Table import covers exact physical row/grid topology, canonical rectangular merges with empty slaves, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph form. A rich paragraph contains non-empty `runs`; every run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. Unknown source presentation-only run XML without a non-empty `effectLst` / `effectDag` normalizes into that schema; a table-cell run effect instead disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, malformed text topology, noncanonical merges, unsafe borders, and non-solid fills remain fallback-only. The normalized fallback for table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct overrides; this is not a full built-in/custom style registry.
+**Why PowerPoint-native Chart/Table reconstruction uses explicit replacement markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer emits a visible SVG fallback plus `data-pptx-replace-with` and `<metadata type="application/json">` only for validated table/chart subsets. Generated decks prepare that pair only for semantic object keys recorded as `<object-key>=yes` in the §IX `Native-ready` map; §VII remains a positive catalog-reference inventory, and a catalog marker is a capability example rather than an execution decision. The parent marker determines the payload schema; ordinary shapes and connectors never use this contract. Table import covers exact physical row/grid topology, canonical rectangular merges with empty slaves, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph form. A rich paragraph contains non-empty `runs`; every run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. Unknown source presentation-only run XML without a non-empty `effectLst` / `effectDag` normalizes into that schema; a table-cell run effect instead disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, malformed text topology, noncanonical merges, unsafe borders, and non-solid fills remain fallback-only. The normalized fallback for table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct overrides; this is not a full built-in/custom style registry.
For supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts, a missing baked preview is replaced by a deterministic readable SVG fallback marked `data-pptx-fallback-kind="normalized"`. The importer also covers the verified column/line/area combo subset, canonical four-series OHLC stock, area charts with numeric date axes, verified scatter/bubble charts with the closed `axes.x` / `axes.y` contract, radar, safe `of_pie` `serLines`, axis/title/legend normalization, and bounded bar/column gap/overlap cases. `gapWidth` is accepted only as one integer in `0..500`, and `overlap` only as one integer in `-100..100`; these presentation values intentionally normalize in native output, while malformed, duplicate, or out-of-range input fails closed. Combo plots may retain independent primary/secondary category caches and workbook ranges. XY import derives `scatter_style` from uniform effective series line/marker/smooth state. The closed category/value and XY axis contracts retain kind, position, visibility, label position, number format, min/max/major unit, reversal, and major gridlines for native read-back; the normalized XY fallback consumes only the two `major_gridlines` flags.
diff --git a/docs/templates-architecture.md b/docs/templates-architecture.md
index fa208dff..3b1e3069 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -312,7 +312,7 @@ kind owns this segment”.
## 3. The four index files
-Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick, following the compact "meta + summary" pattern used by [`charts_index.json`](../skills/ppt-master/templates/charts/charts_index.json) while preserving structured metadata that helps selection.
+Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick, following the compact "meta + summary" pattern used by the Visualization family indexes ([Chart](../skills/ppt-master/templates/charts/charts_index.json), [Structure](../skills/ppt-master/templates/structures/structures_index.json), and [Table](../skills/ppt-master/templates/tables/tables_index.json)) while preserving structured metadata that helps selection.
These indexes cover library scope only. A project-root workspace is intentionally absent from all four indexes and remains usable through its explicit `projects/<name>/` path. Because both scopes use the same workspace shape, moving or copying the complete core workspace between them does not require asset-path rewriting; only library registration changes.
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index da8a69c5..425c304d 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -70,7 +70,7 @@ Generate PPTX 路线围绕完全可控的新形状、文字与版式创作。结
跨四渲染器(PowerPoint / Keynote / LibreOffice / WPS)的位置保真是项目主轴。把默认路线改成 PowerPoint 原生图表会让「像素级一致性」破功——同一个 PPTX 在不同渲染器里图表会显示不同布局。图表默认用 SVG 是 **by design**,不是能力缺失。
-窄例外是 `data-pptx-replace-with` marker:Design Spec §IX 页面块中独立规划、且写明 `Native-ready: yes` 的受支持数据图表与纯文本网格表格可以携带 PowerPoint 原生 Chart/Table 替换 payload;`no` 与零星微型图形保持普通 shape。§VII 只记录真正选中的可复用参考。导出加 `--native-charts-and-tables` 才激活已准备的 marker——供主动用跨渲染器保真换取带数据源对象及图表/表格专属编辑模型的用户使用;激活后的对象会保留 deck 的 chart-area / plot / 轴线 / 网格线 / 标签颜色与原生表格格式,不再塌回 PowerPoint 默认主题(见 [v4.0.0 发布说明](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0))。默认导出路径与可编辑的 SVG 派生形状系统不变。
+窄例外是 `data-pptx-replace-with` marker:Design Spec §IX `Native-ready` 映射中以 `<object-key>=yes` 点名的受支持独立数据图表与纯文本网格表格可以携带 PowerPoint 原生 Chart/Table 替换 payload;`no` 与零星微型图形保持普通 shape。§VII 只记录真正选中的可复用参考。导出加 `--native-charts-and-tables` 才激活已准备的 marker——供主动用跨渲染器保真换取带数据源对象及图表/表格专属编辑模型的用户使用;激活后的对象会保留 deck 的 chart-area / plot / 轴线 / 网格线 / 标签颜色与原生表格格式,不再塌回 PowerPoint 默认主题(见 [v4.0.0 发布说明](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0))。默认导出路径与可编辑的 SVG 派生形状系统不变。
### uv 作为默认 / 必需依赖
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 944c94ca..19984067 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -402,7 +402,7 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是编译生成的 PowerPoin
**原生 PPTX 不能直接作为 Step 3 工作区。** 普通 Generate 可以把 PPTX 作为源材料使用,`beautify-pptx` 也可以在页数、页序和逐页措辞 1:1 的边界下重新设计;这两种情况都不会把原始 PPTX 当作 Step 3 模板。把原生 PPTX 作为模板或页面壳、再用新材料填充时,默认进入 Fill Native PPTX;若请求允许拆分、合并、删页、重排或叙事重构,则仍属于 Generate。只有当目标是创建可复用模板工作区、并在 SVG 路线的 Step 3 中重复使用其设计系统时,才先运行 Create Template,再传入生成的工作区根目录。
-**模板合同是 opt-in,图表和图标不是。** 这种不对称是有意的:Layout 锁定可复用结构,Style 锁定方向/方法默认值,Brand 锁定身份,Deck 则把重复应用与身份、结构组合起来;图表和图标只是不会单独施加 deck 级合同的复用原语。同一个 `templates/` 目录,但 ownership 不同。
+**模板合同是 opt-in,Visualization 参考和图标不是。** 这种不对称是有意的:Layout 锁定可复用结构,Style 锁定方向/方法默认值,Brand 锁定身份,Deck 则把重复应用与身份、结构组合起来;页面级 Chart、Structure、Table 参考和图标只是不会单独施加 deck 级合同的复用原语。同一个 `templates/` 目录,但 ownership 不同。
---
@@ -452,9 +452,9 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge
该视图省略 Executor core 已经恒定加载的通用 SVG/图标禁令,只保留项目专属 forbidden 行。图片从当前页 brief、图片资源表中的显式页分配和 mirror 原型引用中选择;已分配给其他页面的图片会被排除,仍无法归属的 legacy 图片保留在兼容子集中,只有所有锁定图片都能确定归属到其他页面时才记录 `confirmed-none`。
-这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页选中的图表目录参考;它只触发读取对应 SVG 与 §VII Usage,不锁定最终图表类型或几何)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_visualizations`(某页选中的 `chart|structure|table/<key>` 页面级参考;它只触发读取对应 family SVG 与 §VII Usage,不锁定最终信息模型、类型或几何)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。旧 `page_charts` 仍可读取,但新规划不再写入。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有可视化参考、没有图片,很多时候是设计选择,而不是漏填。
-`page-context v2` 保留为按需投影器。每次调用都会输出绑定 `lock_source.sha256` 的紧凑全局锚点、当前 §IX/资源/路由 delta,以及大型引用的带 scope 路径/SHA 指纹;该投影既不是颜色/字体白名单,也不是替代权威。只有明确的诊断/统计需求,或页面/模板/图表的路径-SHA 问题仍未解决时才调用。有效且未压缩的上下文中做有界精确回修,可以只回读修改片段并校验;fresh、已压缩、外部、来源不明、结构性或投影不符的修改必须完整读取 Design Spec 与 lock。flat 页面没有原型引用;structured 页面使用权威完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。
+`page-context v2` 保留为按需投影器。每次调用都会输出绑定 `lock_source.sha256` 的紧凑全局锚点、当前 §IX/资源/路由 delta,以及大型引用的带 scope 路径/SHA 指纹;该投影既不是颜色/字体白名单,也不是替代权威。只有明确的诊断/统计需求,或页面/模板/可视化参考的路径-SHA 问题仍未解决时才调用。有效且未压缩的上下文中做有界精确回修,可以只回读修改片段并校验;fresh、已压缩、外部、来源不明、结构性或投影不符的修改必须完整读取 Design Spec 与 lock。flat 页面没有原型引用;structured 页面使用权威完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。
`--record-usage` 在 `analysis/page-context/` 下为实际调用的页面写入派生快照,记录输入 hash 和紧凑 stdout 的实测大小。token 计数按需加载 `o200k_base`;没有安装 `tiktoken` 时写入 `tokens: null`,但不阻塞执行。`page-context-report` 排除过期快照,汇总已有快照并列出唯一引用指纹;统计可以只覆盖部分页面。一次加载的大型引用 payload 与其他会话上下文有意不纳入统计。
@@ -671,7 +671,7 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“
**为什么模板 SVG 保持完整却仍能编译成原生结构。** 模板 SVG 会重复携带继承的 Master/Layout 视觉和示例 Slide 内容,因此可独立打开。生成时由 `page_layouts` 选择该原型,输出 SVG 仍保持视觉闭包。导出器移除重复继承原子、生成真实 Master/Layout part,并把槽位 carrier 与 Slide-local 内容留在 Slide。
-**为什么 PowerPoint 原生 Chart/Table 重建使用显式替换 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器只为已验证的表格 / 图表子集输出可见 SVG fallback、`data-pptx-replace-with` 与 `<metadata type="application/json">`。生成型 deck 只在 Strategist 将 §IX 页面块标为 `Native-ready: yes` 时准备这组内容;§VII 只保存正向 catalog reference,catalog marker 只是能力示例,不替项目做决策。父组 marker 决定 payload schema;普通 shape 与 connector 不使用该合同。表格导入覆盖精确的物理行列 topology、slave 为空的规范矩形 merge、安全的 solid/no-fill 逐边 border、纯文本多段落,以及封闭的 run 级富文本段落。富文本段落包含非空 `runs`;每个 run 必须有 `text`,并且只能使用 `bold`、`italic`、`underline`、`strike`、`color`、`font_size`、单一 `font_family`、`lang` 和 `alt_lang`。不含非空 `effectLst` / `effectDag` 的来源展示型 run XML 会归一化到该 schema;表格单元格 run 效果则会禁用原生替换,并添加阻塞效果诊断。带 relationship 的文本、扩展节点、换行、字段、tab、项目符号、破损文本 topology、非规范 merge、不安全 border 与非纯色填充仍保持 fallback-only。表格样式 `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` 的规范化 fallback 会解析 `wholeTbl`、`firstRow`、横向带状行、主题颜色 / 字体和直接格式覆盖;这不代表完整 built-in/custom style registry。
+**为什么 PowerPoint 原生 Chart/Table 重建使用显式替换 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器只为已验证的表格 / 图表子集输出可见 SVG fallback、`data-pptx-replace-with` 与 `<metadata type="application/json">`。生成型 deck 只为 §IX `Native-ready` 映射中以 `<object-key>=yes` 点名的语义对象准备这组内容;§VII 只保存正向 catalog reference,catalog marker 只是能力示例,不替项目做决策。父组 marker 决定 payload schema;普通 shape 与 connector 不使用该合同。表格导入覆盖精确的物理行列 topology、slave 为空的规范矩形 merge、安全的 solid/no-fill 逐边 border、纯文本多段落,以及封闭的 run 级富文本段落。富文本段落包含非空 `runs`;每个 run 必须有 `text`,并且只能使用 `bold`、`italic`、`underline`、`strike`、`color`、`font_size`、单一 `font_family`、`lang` 和 `alt_lang`。不含非空 `effectLst` / `effectDag` 的来源展示型 run XML 会归一化到该 schema;表格单元格 run 效果则会禁用原生替换,并添加阻塞效果诊断。带 relationship 的文本、扩展节点、换行、字段、tab、项目符号、破损文本 topology、非规范 merge、不安全 border 与非纯色填充仍保持 fallback-only。表格样式 `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` 的规范化 fallback 会解析 `wholeTbl`、`firstRow`、横向带状行、主题颜色 / 字体和直接格式覆盖;这不代表完整 built-in/custom style registry。
受支持的柱 / 条 / 折线 / 面积、饼 / 圆环、散点 / 气泡图在没有 baked preview 时会生成确定性、可读的 SVG fallback,并标记 `data-pptx-fallback-kind="normalized"`。导入器还覆盖已验证的柱 / 折线 / 面积组合图、规范四系列 OHLC stock、数值日期轴面积图、采用封闭 `axes.x` / `axes.y` 合同的散点 / 气泡图、radar、安全的 `of_pie` `serLines`、坐标轴 / 标题 / 图例归一化,以及有界的柱 / 条图 gap/overlap 场景。`gapWidth` 只接受 `0..500` 内的单个整数,`overlap` 只接受 `-100..100` 内的单个整数;这两个表现字段在 native 输出中有意归一化,非法、重复或越界输入 fail closed。组合图可保留主 / 次 plot 各自的 category cache 与 workbook range。XY 导入根据各系列一致的有效 line/marker/smooth 状态推导 `scatter_style`。封闭的 category/value 与 XY 轴合同为 native read-back 保留 kind、position、visibility、label position、number format、min/max/major unit、reverse 和 major gridlines;规范化 XY fallback 只消费两个 `major_gridlines` 开关。
diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.md
index a2f95b12..f793dd8e 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -269,7 +269,7 @@ Template Overview 写明可重复演示类型、目标受众与结果、交付/
## 三、四套 index 文件
-每个 index 跟物理目录一一对应,字段按需精简,沿用 [`charts_index.json`](../../skills/ppt-master/templates/charts/charts_index.json) 的紧凑“meta + summary”模式,同时保留对 Strategist 选型有用的结构化元数据。
+每个 index 跟物理目录一一对应,字段按需精简,沿用 Visualization family 索引([Chart](../../skills/ppt-master/templates/charts/charts_index.json)、[Structure](../../skills/ppt-master/templates/structures/structures_index.json)、[Table](../../skills/ppt-master/templates/tables/tables_index.json))的紧凑“meta + summary”模式,同时保留对 Strategist 选型有用的结构化元数据。
四套索引只覆盖全局库范围。项目根工作区有意不进入任何索引,仍可通过显式 `projects/<name>/` 路径使用。因为两种范围采用相同工作区形态,完整核心工作区可在两者之间移动或复制,不需要重写素材路径;只有全局库注册不同。
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index c60fd7b3..ea2920cf 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -7,15 +7,20 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
| Trigger | Load |
|---|---|
| `pptx_structure.mode: structured` | [`executor-structured.md`](./executor-structured.md) |
-| Any data chart, chart catalog selection, or text-grid table | [`executor-chart.md`](./executor-chart.md) |
-| A page will use a preset pattern fill or evaluate native chart/table replacement | [`native-data-interface.md`](./native-data-interface.md) before deciding eligibility or emitting metadata |
+| Any selected `family/key` visualization reference, or a current-page legacy `page_charts` row | [`executor-visualization.md`](./executor-visualization.md), then the resolver-returned family branch below |
+| Any value-driven geometry, including a chart-family reference, mini chart, sparkline, inset, or small multiple | [`executor-chart.md`](./executor-chart.md) |
+| Any page-local qualitative topology, including a structure-family reference | [`executor-structure.md`](./executor-structure.md) |
+| Any semantic cell grid, including a table-family reference | [`executor-table.md`](./executor-table.md) |
+| A page will use a preset pattern fill or an independent object is explicitly selected as native-ready | [`native-data-interface.md`](./native-data-interface.md) before emitting the pattern or replacement metadata |
| Any image/formula | [`executor-image.md`](./executor-image.md) + [`image-layout-spec.md`](./image-layout-spec.md) + [`image-layout-patterns.md`](./image-layout-patterns.md) + [`svg-image-embedding.md`](./svg-image-embedding.md) |
| Any `Status: Sourced` web image | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` |
| Effective Speaker Notes outcome is enabled after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |
+Evaluate family branches from each object's actual information model, not only from the primary reference. A family selects construction guidance but never native readiness; `Native-ready` is an independent object-level decision. Page-local `structure` also never implies package-level `pptx_structure.mode: structured`.
+
> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). [`shared-standards-core.md`](./shared-standards-core.md) supplies the technical boundary plus the fallback visual-quality and leading defaults when those authorities are silent.
-**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.
+**Hard rule — Shape-first page authority**: 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. Optional native Chart/Table metadata belongs to an independently selected object and never replaces this visible fallback during authoring; [`native-data-interface.md`](./native-data-interface.md) alone defines that metadata and its export activation.
**Hard rule — flat PowerPoint structure**: Free-design, brand-only, Style-only, and every `template_reuse_scope: style` project use `pptx_structure.mode: flat`: write no root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder`; every visible object remains Slide-local, and the root declares exactly one canonical `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`). A Style workspace supplies reusable communication/design direction, composition rhythm, and information-expression defaults without page prototypes. Its identity-adjacent color, typography, icon, and image defaults yield to the final Brand/Deck identity and confirmed project lock. When a Style is installed alongside Layout/Deck, it changes only Direction / method and follows the resolved non-Style structure route. Export materializes one clean project-owned Master plus one Blank Layout from the current lock. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by specialized metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md).
@@ -53,7 +58,7 @@ Before the first SVG page, output a confirmation listing: the compact communicat
- **Invalid**: fresh/resumed/restarted execution, compaction/summary-only recovery, or an external/unknown change requires one complete read of `design_spec.md`, then `spec_lock.md`, plus triggered references/template inputs. Mid-deck recovery also reads the latest completed SVG and, when images are used, current image metadata.
- **Uncertain**: consult the retained lock first, then only the owning Design Spec fragment; use sources only for facts. Design Spec remains upstream on conflict.
-**On-demand page-context diagnostic**: only for explicit telemetry/debugging or an unresolved page/template/chart path-SHA question; never as a pre-page gate:
+**On-demand page-context diagnostic**: only for explicit telemetry/debugging or an unresolved page/template/visualization path-SHA question; never as a pre-page gate:
```bash
python3 ${SKILL_DIR}/scripts/project_manager.py page-context <project_path> P<NN> [--record-usage]
@@ -65,7 +70,7 @@ Consume stdout directly; stop on non-zero exit. The projection is derived, not a
**Hard rule — exact page roster**: `design_spec.md §IX` is the ordered queue: one final slide per entry, with the same id/order. The UI range no longer applies. Never add, drop, merge, split, or reorder; repair/reconfirm the Design Spec first.
-**Hard rule — binding selection vs realization**: use Strategist-selected semantic content, resources/paths, chart keys, template/layout routing keys, core fonts, palette anchors, icon-library/stroke anchors, and crop boundaries. Adapt realization—including which prepared project-local icon, if any, best serves each page—without changing those binding selections, except sparse local font/color garnish allowed below. A §VIII preferred image pattern is not a template/layout routing key; [`executor-image.md`](./executor-image.md) owns its realization freedom. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Binding selection changes require upstream repair.
+**Hard rule — binding selection vs realization**: use Strategist-selected semantic content, resources/paths, visualization `family/key` references, template/layout routing keys, core fonts, palette anchors, icon-library/stroke anchors, and crop boundaries. Adapt realization—including which prepared project-local icon, if any, best serves each page—without changing those binding selections, except sparse local font/color garnish allowed below. A §VIII preferred image pattern is not a template/layout routing key; [`executor-image.md`](./executor-image.md) owns its realization freedom. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Binding selection changes require upstream repair.
**Hard rule — content vs expression**: `design_spec.md §IX` owns each page's semantic content and supplies complete preferred wording and block texture; those expression choices are not verbatim requirements unless explicitly literal. Executor may paraphrase, condense repetition, regroup or reorder material within the same page, and switch among prose, bullets, keywords, labels, or visual annotation when fit or readability benefits. The result must remain information-equivalent: preserve the `Core message`, `Audience move`, and every substantive claim, fact, data value, proper name, qualifier or caveat, relationship, key argument or evidence, and literal requirement. Never add a claim, move content across pages, or drop information to make the layout fit; return an unfit or underspecified block for Design Spec repair.
@@ -143,11 +148,11 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
- **Fact provenance**: when a §IX page lists `Fact IDs`, resolve each ID from `sources/*.facts.json` and keep the claim/value unchanged. Render a compact source footnote using the source name and a short URL/domain when space permits; when speaker notes are enabled, state the attribution naturally there too. When §IX says `Data class: scenario`, place a visible localized `Scenario data` / `情景数据` label adjacent to the affected KPI/chart and, when notes are enabled, state naturally there that the number is illustrative. Never attach an external fact ID to scenario data or let an unlabeled invented KPI look factual.
- **Default — stage each page with the style's composition geometry (may override when the content genuinely calls for a plain grid)**: an SVG page is a canvas, not a DOM. Before defaulting to stacked rounded-rect cards or uniform equal columns, pick one page-scale move from the locked visual style's §1 `Composition geometry` (a bleed shape, diagonal split, oversized numeral, orbit rings, …) to stage the page's primary zone. Card grids are one option among many, not the house layout.
- **Default — vary a planned deck motif instead of cloning it (may omit where it has no page job)**: when §III `Theme` names a cross-page motif, use the current §IX `Layout` to preserve its recognizable contour, direction, material, or relationship while varying scale, crop, density, position, and content interaction by page role. Apply it only where it supports hierarchy or continuity; do not paste identical ornament or invent a second recurring identity.
-- **Inherited containers**: preserve meaningful template frames; restyle radius, fill, stroke, and depth from the active Design Spec and `spec_lock.md`. Chart-catalog adaptation is owned by [`executor-chart.md`](./executor-chart.md); preview effects never override project styling or structural roles.
+- **Inherited containers**: preserve meaningful template frames; restyle radius, fill, stroke, and depth from the active Design Spec and `spec_lock.md`. Selected catalog-reference adaptation is owned by [`executor-visualization.md`](./executor-visualization.md); preview effects never override project styling or structural roles.
- **Reference — prefer semantic geometry over preset stacks**: for relationships such as ascending, converging, breaking through, or stacking, first seek a basic primitive, one exact preset, or a clear Boolean result. Only when none can faithfully express the relationship should one page-specific polygon/path replace a stack of generic arrows.
- **Reference — create depth with restraint**: use rhythm, spacing, typography, accent bars, and subtle tints before shadows. Reserve lift for a few genuinely floating elements; keep peer grids, dividers, and body containers flat.
- **Phased generation** (recommended):
- 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every §IX-planned data-chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every planned native-ready object. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page --json` directly without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.
+ 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Apply every triggered information-model branch while drawing. **MUST embed one object-scoped plot-area marker** per §IX-named or Quick-promoted value-driven chart object under [`executor-chart.md`](./executor-chart.md) §2; coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)). Write every `<object-key>=yes` native marker plus JSON metadata atomically under [`native-data-interface.md`](./native-data-interface.md) §2. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page --json` directly without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.
2. **Quality Check Gate**: only after every planned SVG exists, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json` directly on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
3. **Logic Construction Phase (conditional)**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity only when the effective Speaker Notes outcome is enabled.
diff --git a/skills/ppt-master/references/executor-chart.md b/skills/ppt-master/references/executor-chart.md
index 5c4769d6..c5394de9 100644
--- a/skills/ppt-master/references/executor-chart.md
+++ b/skills/ppt-master/references/executor-chart.md
@@ -1,176 +1,115 @@
-> Default Generate also loads [`executor-base.md`](./executor-base.md); Default and Quick load [`native-data-interface.md`](./native-data-interface.md) when native chart/table metadata is selected.
+> Default Generate also loads [`executor-base.md`](./executor-base.md); a selected chart-family SVG is adapted through [`executor-visualization.md`](./executor-visualization.md), while independent native readiness and metadata remain exclusively in [`native-data-interface.md`](./native-data-interface.md).
-# Executor Chart and Table Branch
+# Executor Chart Branch
-Conditional Executor authority for data charts, chart-catalog adaptations, chart verification markers, and eligible native chart/table replacement metadata.
+Conditional Executor authority for value-driven SVG geometry, plot-area markers, and the [`verify-charts`](../workflows/stages/verify-charts.md) handoff.
-**Trigger**: load when `design_spec.md §VII` contains a selected chart/table reference, `spec_lock.md page_charts` contains any row, the current §IX page block carries any data-encoded chart or text-grid table, or Quick Generate resolves such an object in active context. Mini charts, sparklines, inset charts, and small multiples count even when they are absent from `page_charts` or the chart catalog.
+**Trigger**: load whenever source values determine visible geometry, including bar length/height, point position, arc angle, polygon vertex, connector or flow width/path, bubble center/radius, duration position, area, or another quantitative visual variable. Mini charts, sparklines, insets, and small multiples count even without a catalog reference.
-**Profile authority**: Default follows the Design Spec/lock and returns missing or conflicting planning decisions upstream. Quick has no plan artifact: the current main agent resolves the data object, optional catalog key, fallback design, and native-readiness immediately in active context, writes the selected semantics into the SVG itself, and does not create a substitute roster or mapping file.
+**Boundary**:
-## 1. Reference Loading and Per-page Selection
+| Information model | Route |
+|---|---|
+| Values determine geometry or another visual variable | This branch |
+| Qualitative order, grouping, containment, causality, or named zones determine topology | [`executor-structure.md`](./executor-structure.md) |
+| Row/column intersections define a semantic cell grid | [`executor-table.md`](./executor-table.md) |
-For each selected `templates/charts/<key>.svg`, use its Skill-relative path and
-read once before first use or after a known change, otherwise reuse it. Never
-load the full catalog.
+---
-**Per-page chart reference**:
+## 1. Value-driven Geometry
-| Active profile | Selection authority |
-|---|---|
-| Default Generate | Look up whether `spec_lock.md page_charts` supplies a page-local key, then read its §VII Usage and SVG for that page only |
-| Quick Generate | Use bounded `chart_recall.py` only when a reusable visualization reference would help; keep the selected key and purpose in active context for that page only, or retain `no-template-match` and design from scratch |
+**Hard rule — data owns the marks**: derive every quantitative mark from the authoritative values and one explicit scale/encoding. Do not eyeball positions, preserve sample values from a catalog preview, or alter data to improve composition.
+
+Construct the chart in this order:
+
+1. Resolve the data domain, categories, units, baseline, scale, and any radius/color/bin mapping.
+2. Establish the plot frame, axes/grid or radial frame, and legend needed to decode those mappings.
+3. Calculate marks from the values, including cumulative, derived, or hierarchical geometry where the chosen chart requires it.
+4. Add data labels, axis/category labels, annotations, units, source notes, and visible exceptions from the active page contract.
+5. Apply project typography, palette, effects, and container treatment without changing the encoding.
+
+**Per-object completeness**: preserve every authoritative series, category, point, label, unit, qualifier, source, and scale cue needed to read the chart. When the source cannot determine a required scale or derived value, return the ambiguity upstream in Default or resolve it from explicit source facts in Quick; never fabricate it at draw time.
-Before drawing each page, apply the matching branch:
+**Selected reference**: when the page has a `chart/<key>` primary reference, [`executor-visualization.md`](./executor-visualization.md) owns its resolution and flexible adaptation. This branch still owns the actual value-to-geometry calculation. A chart authored from scratch follows the same geometry contract without loading a catalog SVG.
-- Selected key present (e.g., `timeline_horizontal`) → read that SVG for the current page only and realize the active page intent without copying it or loading the catalog.
-- No selected key → design the declared visualization/table from scratch; do not invent a catalog reference after drawing begins.
-- Quick never persists its selection into §VII, `page_charts`, or another mapping artifact.
+**Incidental microvisual**: draw a small value-driven trend or indicator accurately. It enters §2 and the verification handoff only when Default §IX or the Quick active-context decision promotes it to a coordinate-verified data object; do not infer that promotion from its appearance after drawing.
---
-## 2. Chart and Native-data Authoring
+## 2. Plot-area Marker
-### 2.1 Chart Plot-Area Marker (MANDATORY on active data-chart pages)
+### 2.1 Chart Plot-Area Marker (Mandatory per verified chart object)
-> The [`verify-charts`](../workflows/stages/verify-charts.md) stage enumerates Default data-driven chart pages from `design_spec.md §IX`; Quick runs it from the still-active page decisions and cross-checks those decisions against plot-area markers. A missing marker invokes that stage's declared fallback and adds avoidable derivation work.
+> [`verify-charts`](../workflows/stages/verify-charts.md) enumerates Default pages from Design Spec §IX and Quick pages from the still-active authoring decisions. A missing marker invokes that stage's declared fallback and adds avoidable derivation work.
-**Hard rule**: every Default page whose §IX `Visualization` declares
-data-driven chart geometry, and every Quick page the current agent resolves as
-data-driven, includes a plot-area marker inside `<g id="chartArea">`, placed
-**after axis lines** and **before the first data element** (bar, line, area,
-point). A legacy §VII data-chart row counts when its page block lacks that
-declaration. An incidental microvisual needs no marker unless the current
-profile promotes it to a coordinate-verified data object; Default repairs §IX,
-while Quick resolves that decision immediately before drawing.
+**Hard rule — object-scoped marker**: every Default chart object given a
+semantic key in §IX `Visualization`, and every Quick chart object promoted for
+coordinate verification, has one page-local `kebab-case` object key. Wrap that
+object in `<g id="<object-key>">`; put exactly one marker inside its plot-area
+group after the axes and before the first data mark. Use
+`id="<object-key>-chartArea"` so several charts can coexist without duplicate
+IDs. New pages prefix the marker payload with `object=<object-key> |`. A legacy
+unscoped marker and `<g id="chartArea">` are accepted only when the page has
+exactly one verified chart object.
-**Rectangular plot area** (bar / horizontal_bar / grouped_bar / stacked_bar / line / area / stacked_area / scatter / waterfall / pareto / butterfly):
+**Rectangular plot area**:
```xml
-<!-- chart-plot-area: x_min,y_min,x_max,y_max -->
+<g id="revenue-trend">
+ <g id="revenue-trend-chartArea">
+ <!-- axes -->
+ <!-- chart-plot-area: object=revenue-trend | x_min,y_min,x_max,y_max -->
+ <!-- data marks -->
+ </g>
+</g>
```
-**Radial charts** (pie / donut / radar):
+**Radial plot area**:
```xml
-<!-- chart-plot-area: pie | center: cx,cy | radius: r -->
-<!-- chart-plot-area: donut | center: cx,cy | outer-radius: r1 | inner-radius: r2 -->
-<!-- chart-plot-area: radar | center: cx,cy | radius: r -->
+<!-- chart-plot-area: object=share-pie | pie | center: cx,cy | radius: r -->
+<!-- chart-plot-area: object=share-donut | donut | center: cx,cy | outer-radius: r1 | inner-radius: r2 -->
+<!-- chart-plot-area: object=capability-radar | radar | center: cx,cy | radius: r -->
```
-**How to determine coordinate values**:
-
| Value | Derivation |
-|-------|------------|
-| `x_min` | X coordinate of the Y-axis line (leftmost data boundary) |
-| `y_min` | Y coordinate of the topmost grid line (highest data boundary) |
-| `x_max` | X coordinate of the rightmost axis endpoint or grid line |
-| `y_max` | Y coordinate of the X-axis baseline |
-| `cx, cy` | Center point of pie/donut/radar (accounting for `transform="translate()"`) |
-| `r` | Outer radius of the chart |
-
-**Per-page verification** — after writing each active data-chart SVG, confirm the marker exists:
+|---|---|
+| `x_min` | X coordinate of the Y-axis line or leftmost data boundary |
+| `y_min` | Y coordinate of the topmost grid line or data boundary |
+| `x_max` | X coordinate of the rightmost axis endpoint or data boundary |
+| `y_max` | Y coordinate of the X-axis baseline or bottom data boundary |
+| `cx, cy` | Absolute center after accounting for containing translate transforms |
+| `r`, `r1`, `r2` | Visible outer/inner radii used by the authored radial geometry |
-```bash
-rg -n "chart-plot-area" <project_path>/svg_output/<current_page>.svg
-```
+Calculator-supported SVGs in `templates/charts/` carry the same comment, and
+single-object previews may retain the legacy unscoped payload and
+`id="chartArea"`. A qualitative structure or cell-grid table does not gain a
+marker merely because it contains numbers.
-> Calculator-supported data-chart templates in `templates/charts/` include this
-> marker as a reference. If a data chart covered by §2.1 lacks it, that is a
-> bug. Conceptual diagrams, frameworks, and other non-data visualizations in
-> the same library do not use a plot-area marker.
-Technical SVG/PPT constraints remain in [`shared-standards-core.md`](./shared-standards-core.md).
+### 2.2 Authoring-time Check
-### 2.2 PowerPoint-Native Chart/Table Replacement Marker (MANDATORY on selected native-ready objects)
-
-> `svg_to_pptx.py --native-charts-and-tables` replaces marked groups with PowerPoint-native Chart/Table objects (charts get an embedded Excel workbook). Markers stay dormant in the default export, whose SVG children become independently editable DrawingML shapes. Prepare this optional capability for selected independent data objects, not every numeric embellishment.
-
-**Hard rule**: load [`native-data-interface.md`](./native-data-interface.md) for
-each independent data chart or pure text-grid table selected as native-ready.
-Default reads that decision from the current §IX page block (`yes`/`no`; legacy
-§VII fallback only). Quick decides in active context before drawing based on
-whether the PowerPoint Chart/Table object model is useful enough to accept its
-normalization risk. A supported selected chart gets
-`data-pptx-replace-with="chart"` plus one JSON `<metadata>` child; a selected
-pure text-grid table gets the table form, transcribing all plotted data or
-visible cells. An object not selected stays ordinary SVG even when a catalog
-reference contains a marker. The parent marker selects the schema.
-
-**MUST — atomic authoring**: For each native-ready object, treat the visible SVG fallback, the parent `data-pptx-replace-with` marker, and its JSON `<metadata>` child as one object. Write all three in the same SVG edit while the data is in context. Do not defer the marker or metadata to `verify-charts`, the final quality gate, or export.
-
-**Hard rule — eligibility follows the active profile authority**: In Default, a
-two-point line or small multiple gets metadata only when its §IX page block
-plans it as an independent object with `Native-ready: yes`; changing eligibility
-requires upstream repair. In Quick, the current agent makes that independent-
-object decision before drawing and expresses it atomically through the marker,
-metadata, and fallback. A sparkline, inset, KPI-card trend, or other incidental
-microvisual stays ordinary SVG unless Quick deliberately promotes it before
-authoring.
-
-Generated authoring MUST omit `data-pptx-import-source` and
-`data-pptx-fallback-sha256`: those attributes record imported-PPTX provenance
-and its sealed fallback baseline. Never copy a static baseline from a chart
-catalog or reusable template; normal content edits would make it stale.
-
-`data-pptx-replace-with` is a **data-backed replacement claim**, not a generic label for a group that contains numbers and not a marker for ordinary PowerPoint shapes or connectors. Add it only when the matching JSON payload can be written in the same edit; if the object is meant to remain SVG geometry, do not add the marker.
-
-- Chart types absent from that list and conceptual/diagrammatic graphics (process flows, cycles, quadrant cards, timelines, or a KPI card container) get **no marker** — `svg_quality_checker.py` rejects unsupported marker types. A supported data chart nested inside one of those compositions gets its own marker only when Default §IX or the Quick active-context decision selects that object as native-ready.
-- Canonical rectangular merged text cells may carry a table marker by putting anchor-only `row_span` / `col_span` in metadata and leaving covered cells blank. Nonrectangular/overlapping merges, nonblank covered cells, and graphical cells (icons, harvey balls, rating dots) get **no table marker** and stay on the SVG fallback route.
-- Transcribe, don't restyle: `categories` / `series[].values` are the numbers just plotted; `style.colors` copies the series HEX values already rendered on the page, whether they use a recurring Default `spec_lock.colors` anchor or a Quick/contextual page-local color.
-- Data-point color: when a single column/bar series uses data-point colors in the fallback, copy those fills into `series[].point_colors` in category order.
-- Data labels: when visible point values are part of the fallback chart, write `data_labels` instead of companion text; use `data_labels.points` for selected labels, and use `number_format`, `font_size`, `font_family`, and per-point `colors` / `color` when the fallback labels carry suffixes or color-coded text.
-- Line markers: when the fallback line chart draws visible point nodes, set `line_style: "lineMarker"`; leave the default `line` only for line charts without nodes.
-- Area-under-line: when a combo plot is drawn as a filled area under a line, keep `type: "line"`, add `area_fill: true`, and copy the area transparency into `series[].fill_opacity`; copy visible line `stroke-width` into `series[].line_width` for line/area series.
-- Native chrome: write `title`, `subtitle`, axis titles, or `show_legend: true` only when the fallback visibly renders the same chrome inside the native chart's replacement scope. `title` is the PowerPoint chart title, not an object name; use `name` for page-semantic object naming (e.g. `p03-revenue-chart`). Write explicit `x`/`y`/`width`/`height` read from the drawn plot area; omission is the fallback — the exporter then infers the frame from the drawn fallback geometry.
-- Value-axis labels: when the fallback keeps category labels but intentionally omits numeric value-axis tick labels, set `show_value_axis_labels: false`.
-- Freeform chart text: transcribe center labels, source notes, and other in-chart annotations as companion `caption` / `note` / `notes` entries with explicit slide-coordinate bounds; do not rely on fallback `<text>` children to survive native export.
-- Native chart typography mirrors the SVG fallback. Copy the fallback's shared chart font into `style.font_family` and visible chart text sizes into the matching metadata fields (`title_font_size`, `subtitle_font_size`, `axis_font_size`, `note_font_size`, etc.) only when role sizes differ; otherwise let the exporter infer them from visible fallback text. When a visible chart title, subtitle, or axis title needs its own size/color/font, write that field as an object with `text`, `font_size`, `font_family`, and `color`. Use `axis_title_font_size`, `legend_font_size`, or companion per-entry `font_size` only when the fallback visibly uses a separate size.
-- Native table typography mirrors the SVG fallback. Write `style.font_family` and `style.font_size` from the visible table text; use `header_font_size` or per-cell `font_size` only when the fallback visibly does so. If the fallback has no explicit table font, Default uses the deck body family and declared `spec_lock.md` body anchor; Quick uses the concrete body family/size already resolved in active context.
-- The marker group's transform stays translate/scale only (no rotate / matrix / skew).
-- Visual parity is not a goal: the SVG drawing remains the designed visual and exports as editable DrawingML shapes; the native object is the data-backed counterpart with PowerPoint's chart/table-specific model. Never simplify the SVG design to match what a native object could show.
-
-**Per-page verification** — after writing a page with selected native-ready objects, enumerate those objects and confirm a one-to-one match: every object has one parent marker and exactly one JSON metadata child. Finding one marker somewhere on a page is insufficient when the page contains multiple selected objects.
+After writing each page containing verified charts, confirm marker count and
+object ownership before continuing:
```bash
-rg -n 'data-pptx-replace-with="(chart|table)"|<metadata type="application/json">' <project_path>/svg_output/<current_page>.svg
+rg -n "chart-plot-area" <project_path>/svg_output/<current_page>.svg
```
+The number of markers must equal the number of promoted chart objects, and each
+marker must sit under its matching object wrapper. One marker somewhere on a
+multi-chart page is insufficient.
----
-
-## 3. Visualization Reference
-
-§1 loads only a selected page-local SVG. Default takes Usage/semantics from
-§VII/§IX; Quick takes them from the current active-context page decision.
-
-**Hard rule**: treat the loaded SVG as a page-local reference, not a required base. Default §IX or the Quick active-context page decision plus source data own the final information structure; never replicate the preview verbatim.
-
-**Adaptation rules**:
-- **Preserve**: Default-planned or Quick-resolved information relationships, data encoding, and every active content obligation
-- **Page-local only**: a reference row applies only to its mapped page; never spread it across the deck
-- **Flexible realization**: borrow, recombine, or depart from the preview's type and geometry when the current page is better served another way
-- **Carry forward**: every authoritative label, value, unit, status, source, and explanatory block; never shorten or drop content to imitate a lighter catalog preview
-- **Adapt**: project data and labels, dimensions, axes, legend, and spacing as the authored content requires
-- **Project-owned**: palette, typography, container treatment, effects, background, and page chrome; catalog preview values are fallbacks, never defaults
-- **Bound final body modules**: add or revise root-coordinate `data-pptx-bounds` on every visible direct root `<g>` copied into the final page; nested groups need none, chart geometry and local references are not content-boundary inputs, and catalog reference warnings never waive the final-page contract
-- **Adjust with fidelity**: composition, axis ranges, grouping, and grid may change when the actual content, relationships, hierarchy, and data encoding remain complete
-- **Forbidden**: treating preview structure as the page specification; omitting authoritative data points, labels, relationships, or explanatory content to fit it
+Technical SVG/PPT constraints remain in [`shared-standards-core.md`](./shared-standards-core.md).
-> Templates: `templates/charts/`. `page_charts` maps one optional reference to one page; execution opens only that SVG.
+---
-### 3.1 Chart Coordinate Calibration
+## 3. Verification Handoff
-Coordinate calibration runs as a **conditional post-generation stage**, not
-inside the SVG authoring loop. After SVG generation completes, if the deck
-contains data-driven charts, run
-[`verify-charts`](../workflows/stages/verify-charts.md). Default follows its
-declared gate order; Quick runs calibration before its one lockless final
-checker.
+Coordinate calibration is a conditional post-generation stage, not part of the page-authoring loop. After all SVG pages exist, run [`verify-charts`](../workflows/stages/verify-charts.md) whenever the active profile declares at least one page with value-driven chart geometry.
-The authoring obligation is upstream: embed the
-`<!-- chart-plot-area ... -->` marker on every active data-chart page during the
-initial draft (§2.1). Verify-charts enumerates Default pages from the Design
-Spec; Quick enumerates them from the still-active page decisions and cross-checks
-the markers before feeding `svg_position_calculator.py`.
+| Active profile | Verification page list |
+|---|---|
+| Default Generate | Design Spec §IX, with the stage's explicit legacy §VII fallback |
+| Quick Generate | Still-active page decisions cross-checked one-for-one against plot-area markers |
-> Do NOT run `svg_position_calculator.py` during the initial draft. The calculator calibrates already-generated SVGs against their declared plot areas; running it before the SVG exists has nothing to compare against.
+Do not run `svg_position_calculator.py` during the initial draft. The stage calibrates completed SVG geometry against the declared plot area, handles direct/decomposable/formula/manual modes, repairs genuine coordinate mismatches, and then returns to the active profile's checker order.
diff --git a/skills/ppt-master/references/executor-structure.md b/skills/ppt-master/references/executor-structure.md
new file mode 100644
index 00000000..f91c664d
--- /dev/null
+++ b/skills/ppt-master/references/executor-structure.md
@@ -0,0 +1,51 @@
+> See [`executor-base.md`](./executor-base.md) for page authoring and [`executor-visualization.md`](./executor-visualization.md) when a structure-family SVG is selected.
+
+# Executor Structure Branch
+
+Conditional Executor authority for page-local qualitative topology: relationships expressed through spatial order, grouping, containment, direction, hierarchy, or named zones rather than value-mapped geometry.
+
+**Trigger**: load when the page's actual information model is qualitative topology or its primary reference uses `structure/<key>`.
+
+**Hard rule — not structured PPTX**: this branch constructs Slide-local information geometry. [`executor-structured.md`](./executor-structured.md) separately owns PowerPoint Master/Layout/placeholder reuse under `pptx_structure.mode: structured`. Either, both, or neither branch may be active on a page; their names do not imply each other.
+
+---
+
+## 1. Information-model Boundary
+
+| Content relationship | Route |
+|---|---|
+| Sequence, flow, hierarchy, hub/spoke, layers, comparison zones, grouping, containment, roster, roadmap, or qualitative matrix | This branch |
+| Position, length, angle, area, radius, flow width, or color bin derives from values | [`executor-chart.md`](./executor-chart.md) |
+| Row/column intersections form a semantic cell grid | [`executor-table.md`](./executor-table.md) |
+
+A structure may contain numbers as labels without becoming a chart. A named quadrant may use axes as qualitative boundaries without becoming value-driven. Conversely, actual `x`, `y`, or radius mapping remains chart geometry even when the result resembles a framework.
+
+When a `structure/<key>` primary reference exists, [`executor-visualization.md`](./executor-visualization.md) owns resolution and flexible adaptation. No reference is required for a page-specific topology.
+
+---
+
+## 2. Topology Construction Order
+
+**Mandatory — spine → nodes → connectors → labels → garnish**: complete each layer in this order so the semantic topology remains legible without decorative support.
+
+| Layer | Construction job | Completion evidence |
+|---|---|---|
+| `spine` | Establish the dominant reading path or organizing frame: baseline, axis pair, hierarchy trunk, ring, hub, container, layer stack, or another explicit/implicit scaffold | The intended entry point and reading direction are unambiguous before content boxes are styled |
+| `nodes` | Place every semantic unit with hierarchy and information weight reflected in size, position, repetition, or containment | Every required item has one identifiable home and peers remain visually comparable |
+| `connectors` | Add only relationships the topology cannot express by adjacency, alignment, order, or containment alone | Direction, dependency, exchange, branching, or convergence is explicit without decorative arrows |
+| `labels` | Attach titles, node copy, edge labels, stage names, legends, and qualifiers to the geometry they explain | No label floats ambiguously between nodes; all authoritative relationships and caveats remain readable |
+| `garnish` | Add non-semantic accents, depth, icons, or motifs after the structure already communicates | Removing garnish leaves the complete topology and reading order intact |
+
+**Hard rule — topology before styling**: do not start from a row of decorated cards and infer relationships afterward. First encode the actual information relationship; then apply project-owned palette, typography, effects, and container treatment.
+
+**Connector economy**: use containment, alignment, shared baselines, or proximity when they already communicate the relationship. When a connector is necessary, give it a clear source/target or shared route and follow [`executor-base.md`](./executor-base.md) §3.0 for line, preset Connector, Boolean, or necessary freeform construction. Never add arrows solely to make a page look process-like.
+
+**Label fidelity**: keep every required node, stage, branch, qualifier, status, and relationship from the active page contract. Reflow geometry around the copy; do not delete nodes, merge distinct relationships, or shorten away a caveat to preserve a preview's spacing.
+
+---
+
+## 3. Page-level Integration
+
+Use one dominant topology per primary structure. Secondary annotations, KPIs, or a small data object may attach to it when their semantic ownership is clear; load the corresponding family branch for any actual chart or cell grid rather than forcing that object into the structure grammar.
+
+Keep garnish subordinate to the page's communication move. Icons, fills, bands, shadows, and decorative paths may reinforce grouping or direction, but they never create a relationship that is absent from the spine, nodes, connectors, or labels.
diff --git a/skills/ppt-master/references/executor-structured.md b/skills/ppt-master/references/executor-structured.md
index 312b6748..3f958019 100644
--- a/skills/ppt-master/references/executor-structured.md
+++ b/skills/ppt-master/references/executor-structured.md
@@ -6,6 +6,8 @@ Conditional Executor authority for `template_reuse_scope: mirror|layout` with `p
**Trigger**: load only when the lock selects structured template reuse.
+**Hard rule — package structure, not information structure**: this branch owns reusable PowerPoint Master/Layout atoms, placeholders, slots, and prototype topology. [`executor-structure.md`](./executor-structure.md) independently owns page-local qualitative diagrams and layouts. A structure-family reference never activates `pptx_structure.mode: structured`, and structured template reuse never implies a structure-family reference.
+
## 1. Template Reuse Rules
### 1.0 Template Context Load
@@ -60,7 +62,7 @@ When `spec_lock.md` records the AI-derived `template_reuse_scope: mirror`, Execu
**Detecting mirror mode**: read `template_reuse_scope` from the retained lock. `replication_mode: mirror` in the installed template only determines whether that scope is legal; it must never force mirror behavior when the lock records `layout` or `style`.
-**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.
+**Mirror + visualization pages**: chart, table, and qualitative topology inside a mirror SVG are already drawn. Replace only the permitted visible text values while preserving the prototype geometry and topology; do not redraw any object from a `family/key` catalog SVG. A mirror template's `page_visualizations` entries are normally absent for this reason, and a legacy `page_charts` row does not override mirror fidelity.
**Legacy template boundary**: A template with missing root Master identity, direct atomic placeholders, `data-pptx-layout-kind`, unmapped `baseline`, `preserve`, or `layout_strategy: distill` is not a fallback input. Stop and create a new current workspace through [`create-template`](../workflows/create-template.md) before generation.
diff --git a/skills/ppt-master/references/executor-table.md b/skills/ppt-master/references/executor-table.md
new file mode 100644
index 00000000..cb971a31
--- /dev/null
+++ b/skills/ppt-master/references/executor-table.md
@@ -0,0 +1,51 @@
+> See [`executor-base.md`](./executor-base.md) for page authoring and [`executor-visualization.md`](./executor-visualization.md) when a table-family SVG is selected.
+
+# Executor Table Branch
+
+Conditional Executor authority for semantic cell grids whose row/column intersections carry the information.
+
+**Trigger**: load when the page contains an actual cell-grid table or its primary reference uses `table/<key>`.
+
+---
+
+## 1. Cell-grid Boundary
+
+| Information model | Route |
+|---|---|
+| Row headers, column headers, body cells, summaries, and optional rectangular spans define meaning by intersection | This branch |
+| Independent visual zones compare categories without a shared row/column grid | [`executor-structure.md`](./executor-structure.md) |
+| Values determine marks, positions, lengths, areas, angles, radii, or color bins | [`executor-chart.md`](./executor-chart.md) |
+
+Graphical indicators may appear inside cells without changing the table family, provided the row/column grid still carries their meaning. A row of metric cards or two prose columns is a qualitative structure, not a table.
+
+When a `table/<key>` primary reference exists, [`executor-visualization.md`](./executor-visualization.md) owns resolution and flexible adaptation. A custom cell grid follows this branch without loading a catalog SVG.
+
+---
+
+## 2. Grid Construction
+
+**Hard rule — grid before decoration**: establish the complete logical grid before drawing fills, borders, badges, or other cell treatment.
+
+1. Resolve column count, row count, header rows, row labels, summaries, and any rectangular visual spans from the authoritative content.
+2. Allocate column widths and row heights from semantic weight and real text/data fit; do not default to equal columns when labels or values differ materially.
+3. Place every cell value, unit, qualifier, status, and source-bearing note in its correct intersection.
+4. Apply alignment consistently by content role, including comparable numeric alignment and stable header/body hierarchy.
+5. Add rules, fills, banding, highlights, and in-cell indicators only after the grid reads correctly in plain form.
+
+**Per-cell completeness**: never drop a row, column, summary, footnote, unit, or qualifier to imitate a lighter catalog preview. Reflow text, widen the affected column, rebalance adjacent columns, or increase row height while preserving the active page's information contract and [`executor-base.md`](./executor-base.md) typography bounds.
+
+**Visual span discipline**: merge only rectangular regions whose repeated boundaries would obscure an intended shared heading or group. Covered areas must not carry competing visible content. This branch owns the visible SVG geometry only; any native merge fields or payload topology belong exclusively to [`native-data-interface.md`](./native-data-interface.md).
+
+**Table chrome**: make header/body/summary roles distinguishable with the lightest sufficient combination of weight, fill, rule, and whitespace. Keep comparison scanning stable across the grid; decorative card treatment must not break row or column continuity.
+
+---
+
+## 3. Object Boundary
+
+Treat each semantic table as one independently bounded page object even when it contains nested cell groups. Captions, source notes, and explanatory callouts may sit outside the grid when their ownership is visually explicit.
+
+Native readiness is decided per independent table object, not by the `table`
+family or numeric cells. Reuse its §IX/Quick semantic object key in the
+`Native-ready` map; only `<object-key>=yes` loads and follows
+[`native-data-interface.md`](./native-data-interface.md). All others remain
+ordinary Shape-first SVG geometry under [`executor-base.md`](./executor-base.md).
diff --git a/skills/ppt-master/references/executor-visualization.md b/skills/ppt-master/references/executor-visualization.md
new file mode 100644
index 00000000..99d30da3
--- /dev/null
+++ b/skills/ppt-master/references/executor-visualization.md
@@ -0,0 +1,58 @@
+> See [`executor-base.md`](./executor-base.md) for page authoring and the family branches for actual information-model construction.
+
+# Executor Visualization Reference Branch
+
+Conditional Executor authority for resolving one page-local `family/key` SVG reference and adapting it without turning the catalog preview into a page specification.
+
+**Trigger**: load only when Default `spec_lock.md page_visualizations` maps the current page to a canonical reference, a legacy project supplies a current-page `page_charts` row, or Quick already selected one canonical reference in active context.
+
+---
+
+## 1. Canonical Reference Resolution
+
+| Family | Canonical reference | SVG root | Construction authority |
+|---|---|---|---|
+| `chart` | `chart/<key>` | `templates/charts/<key>.svg` | [`executor-chart.md`](./executor-chart.md) |
+| `structure` | `structure/<key>` | `templates/structures/<key>.svg` | [`executor-structure.md`](./executor-structure.md) |
+| `table` | `table/<key>` | `templates/tables/<key>.svg` | [`executor-table.md`](./executor-table.md) |
+
+**Per-page selection authority**:
+
+| Active profile | Resolve from |
+|---|---|
+| Default Generate | Prefer the current `P<NN>: family/key` row from retained `spec_lock.md page_visualizations`, then read that page's `Page | Family | Template | Usage` row in Design Spec §VII; use a legacy `page_charts` row and its legacy §VII Usage only when the canonical row is absent |
+| Quick Generate | Use the canonical `family/key` and page-local purpose already selected in active context before SVG authoring |
+
+**Hard rule — one primary reference per page**: one page resolves at most one catalog SVG. The reference guides the page's dominant reusable information structure; secondary objects are authored from their actual content through the applicable family branch without loading another catalog SVG. Independent Chart/Table children retain their §IX or Quick semantic object keys for scoped native/verification contracts. A page may still activate several family branches when it genuinely contains several information models.
+
+**Mandatory — shared resolution**: resolve the selected value through `visualization_recall.py validate`; consume its canonical `reference` and `path` instead of guessing a family or constructing a path from the input string. Add `--legacy-bare` only for a value read from legacy `page_charts`.
+
+```bash
+python3 ${SKILL_DIR}/scripts/visualization_recall.py validate <family/key>
+python3 ${SKILL_DIR}/scripts/visualization_recall.py validate \
+ --legacy-bare <legacy-key>
+```
+
+New `page_visualizations` and Quick selections accept only canonical `chart/<key>`, `structure/<key>`, or `table/<key>`. A bare key is read-compatible only from legacy `page_charts`: the shared resolver must produce exactly one canonical entry, otherwise stop for upstream correction. Never write the normalized result back into the legacy lock or silently choose among ambiguous families. If canonical and legacy rows both exist for one page, stop on the duplicate contract even when both values resolve to the same SVG.
+
+Read the resolver-returned SVG once before its first use in the valid active context and reuse that reading until a known file change or context invalidation. Do not manually open indexes or scan family directories during Executor realization; the shared resolver owns live-catalog reads. Selection and bounded recall belong before this branch; this branch only resolves the already-selected reference.
+
+---
+
+## 2. Flexible Page-local Adaptation
+
+**Hard rule — reference, not lock**: the selected SVG is a page-local construction reference. The current §IX page block or Quick page decision plus authoritative source content owns the final information structure; the preview does not lock visualization type, geometry, styling, or native replacement.
+
+| Preserve | Adapt freely |
+|---|---|
+| Authoritative labels, values, units, statuses, sources, relationships, hierarchy, and explanatory content | Dimensions, spacing, axes, grouping, orientation, density, and exact primitive/preset composition |
+| The selected page-local Usage and any information encoding that remains valid for the actual content | Borrow, recombine, simplify, extend, or depart from the preview when another realization preserves the same information more faithfully |
+| The active page's complete content obligations | Palette, typography, container treatment, effects, background, and page chrome from the project authorities |
+
+**Forbidden — preview substitution**:
+
+- Do not copy the preview verbatim or treat its sample labels/data as content.
+- Do not omit authoritative content to fit the preview's lighter density.
+- Do not spread one page's reference to another page without that page's own selected mapping.
+
+The `family` namespace selects a reference registry and its construction authority only. It does not assert that an object is native-ready; native eligibility is an independent per-object decision owned exclusively by [`native-data-interface.md`](./native-data-interface.md).
diff --git a/skills/ppt-master/references/modes/briefing.md b/skills/ppt-master/references/modes/briefing.md
index 04c2252c..96eb1a6b 100644
--- a/skills/ppt-master/references/modes/briefing.md
+++ b/skills/ppt-master/references/modes/briefing.md
@@ -26,7 +26,7 @@ Neutral information delivery. Lay the facts out plainly and completely, organize
- Even hierarchy within a section; consistent layout across sibling pages so the eye always knows where to look.
- Where one figure genuinely matters (a total, a status flag, an exception), surface it — but don't invent a punchline the content doesn't have.
-> Table / list / dashboard / status-card geometry lives in [`templates/charts/`](../../templates/charts/); this mode decides *that the page informs completely and neutrally*, not pixel positions.
+> Cell-grid tables live in [`templates/tables/`](../../templates/tables/); list and KPI/status-card topology lives in [`templates/structures/`](../../templates/structures/); value-driven marks live in [`templates/charts/`](../../templates/charts/). A dashboard may combine those object types. This mode decides *that the page informs completely and neutrally*, not pixel positions.
## 3. Speaker-notes register
diff --git a/skills/ppt-master/references/modes/instructional.md b/skills/ppt-master/references/modes/instructional.md
index 48b18e70..1c0b49f8 100644
--- a/skills/ppt-master/references/modes/instructional.md
+++ b/skills/ppt-master/references/modes/instructional.md
@@ -26,7 +26,7 @@ Titles state what the page teaches ("How attention weights are computed") — cl
- Diagrams that build incrementally; annotate the part currently being explained.
- Concrete examples anchor abstract points when they improve transfer or comprehension.
-> Step / flow / diagram geometry lives in [`templates/charts/`](../../templates/charts/); this mode decides *the learning order and granularity*.
+> Step / flow / diagram topology lives in [`templates/structures/`](../../templates/structures/); value-driven teaching charts remain in [`templates/charts/`](../../templates/charts/). This mode decides *the learning order and granularity*.
---
diff --git a/skills/ppt-master/references/modes/narrative.md b/skills/ppt-master/references/modes/narrative.md
index 94f2207a..83ea7ab7 100644
--- a/skills/ppt-master/references/modes/narrative.md
+++ b/skills/ppt-master/references/modes/narrative.md
@@ -24,7 +24,7 @@ Titles read as beats that advance the arc ("Then the numbers stopped adding up")
- Visual weight guides the eye through each beat (hero image, one focal number, a pull quote).
- Continuity within a chapter, variation between chapters.
-> Structure serves the arc, not a grid. Layout / chart geometry lives in [`templates/charts/`](../../templates/charts/) and [`executor-base.md`](../executor-base.md); this mode decides *the emotional beat of each page*.
+> Structure serves the arc, not a grid. Qualitative page topology lives in [`templates/structures/`](../../templates/structures/), value-driven marks in [`templates/charts/`](../../templates/charts/), cell grids in [`templates/tables/`](../../templates/tables/), and general composition in [`executor-base.md`](../executor-base.md). This mode decides *the emotional beat of each page*.
---
diff --git a/skills/ppt-master/references/modes/pyramid.md b/skills/ppt-master/references/modes/pyramid.md
index 33e50f10..5f0a53cc 100644
--- a/skills/ppt-master/references/modes/pyramid.md
+++ b/skills/ppt-master/references/modes/pyramid.md
@@ -38,7 +38,7 @@ SCQA opening, pyramid body:
- Decomposition pages (driver tree / MECE breakdown / 2×2 matrix) carry the analytical load.
- Source attribution on every data page.
-> Page structure is a tendency, not a coordinate template. Card / tree / chart / KPI geometry lives in [`templates/charts/`](../../templates/charts/) — adapt those skeletons, do not reinvent. This mode decides *what argument each page makes*, not pixel positions.
+> Page structure is a tendency, not a coordinate template. Card / tree / KPI and qualitative 2×2 topology lives in [`templates/structures/`](../../templates/structures/); value-driven charts, including plotted 2×2 matrices, live in [`templates/charts/`](../../templates/charts/); cell grids live in [`templates/tables/`](../../templates/tables/). Adapt the selected reference without treating it as fixed geometry. This mode decides *what argument each page makes*, not pixel positions.
---
diff --git a/skills/ppt-master/references/native-data-interface.md b/skills/ppt-master/references/native-data-interface.md
index 53982ac0..5ffdecbd 100644
--- a/skills/ppt-master/references/native-data-interface.md
+++ b/skills/ppt-master/references/native-data-interface.md
@@ -1,8 +1,8 @@
-> See [`shared-standards-core.md`](./shared-standards-core.md) for the mandatory SVG foundation.
+> See [`executor-base.md`](./executor-base.md) for the Shape-first page authority and [`shared-standards-core.md`](./shared-standards-core.md) for the mandatory SVG foundation.
# Native Data Interface
-Conditional interface for preset pattern fills and PowerPoint-native chart/table replacement metadata. Load when either feature appears in the authored SVG.
+Sole conditional interface for preset pattern fills and PowerPoint-native chart/table replacement eligibility, markers, metadata schemas, and export activation. Load only when either feature is selected for the authored SVG.
## 1. Pattern Fill — `<pattern>` with PPTX preset annotation
@@ -40,18 +40,30 @@ this enum.
## 2. PowerPoint-Native Chart / Table Replacement Markers (Opt-in)
-Native PowerPoint tables and Excel-backed charts activate at export time only. Generated pages prepare dormant replacement metadata for independently selected native-ready objects while keeping hand-authored SVG geometry pixel-stable across PowerPoint / Keynote / LibreOffice / WPS.
+[`executor-base.md`](./executor-base.md) remains the single Shape-first authoring authority: the complete visible SVG fallback is required regardless of native eligibility. This section only adds dormant replacement metadata to independently selected objects and defines how export may activate it.
**Hard rule — selected-object authoring**: write the marker and JSON metadata in
-the same edit only for a supported chart or pure text-grid table selected as
-native-ready under [`executor-chart.md`](./executor-chart.md) §2.2. Default reads
-`Native-ready: yes` from §IX (legacy §VII fallback only); Quick makes the
-decision in active context before drawing. Default `no`, a Quick decision not to
-use the native object model, and incidental microvisuals stay on the SVG
-fallback route. Canonical rectangular merged text cells may use the narrow
+the same edit only for a supported chart or pure text-grid table independently
+selected as native-ready. Default reads the exact semantic object key from §IX
+`Native-ready: <object-key>=yes|no; ...`; Quick assigns the same page-local
+`kebab-case` key in active context before drawing. Use that key as the marker
+group `id` and metadata `name`. A catalog `family/key`, family name, §VII row,
+numeric content, or another ready object on the page never implies eligibility.
+Default `<object-key>=no`, Quick `no`, and unlisted incidental microvisuals stay
+on the SVG fallback route. Canonical rectangular merged text cells may use the narrow
`row_span` / `col_span` contract below; graphical cells stay unmarked. The
-marker group supplies visible SVG fallback children for browser rendering and
-JSON metadata for `svg_to_pptx` native export.
+marker group supplies visible fallback children for browser rendering and JSON
+metadata for `svg_to_pptx` native export.
+
+A legacy bare `Native-ready: yes|no` maps only to the page's sole eligible
+object. Zero or multiple eligible objects make it ambiguous and require
+upstream repair.
+
+**MUST — atomic authoring**: treat one object's visible SVG fallback, parent
+`data-pptx-replace-with` marker, and single JSON `<metadata>` child as one
+authoring unit. Write all three while that object's data is in context. Do not
+defer the marker or metadata to `verify-charts`, the final quality gate, or
+export.
**Hard rule — activation is the opt-in, dormant unless exported with `--native-charts-and-tables`**: A marker only declares that a group is eligible for PowerPoint-native Chart/Table replacement. Normal `svg_to_pptx.py` runs keep the fallback SVG children and convert them into independently editable DrawingML shapes. Pass `--native-charts-and-tables` only when the data source and chart/table-specific object model matter more than cross-renderer layout fidelity: it emits the PowerPoint Chart/Table object and skips the fallback children to avoid duplicates. Native styling preserves the core palette, text, axis, grid, and background colors where possible, but it is still a PowerPoint Chart/Table object rather than a pixel-identical SVG drawing.
@@ -94,6 +106,7 @@ free of those attributes; use the exact behavior and field index in
<metadata type="application/json">
{
"x": 120, "y": 150, "width": 520, "height": 320,
+ "name": "p03-revenue-chart",
"type": "column",
"title": "Revenue by Segment",
"categories": ["Q1", "Q2", "Q3"],
@@ -107,6 +120,31 @@ free of those attributes; use the exact behavior and field index in
</g>
```
+**Hard rule — transcribe the authored object**: metadata is the native object's
+source of truth and must describe the same data and visible chart/table chrome
+as the fallback drawn in that marker group.
+
+| Object | Required projection from the visible fallback |
+|---|---|
+| Chart | Every category/point and series value, the actual x/y/size data where applicable, visible point colors and labels, line/area treatment needed by the schema, visible title/axis/legend chrome, companion text, bounds, and fallback typography/style values that native export cannot infer unambiguously |
+| Table | Every resolved row/column cell, header/summary line, rectangular span, required cell style, alignment, bounds, and visible typography |
+
+Do not simplify the SVG artwork to match the native object model. When the
+closed payload cannot represent an object without losing required data or cell
+topology, Default returns the native-ready decision upstream and Quick revises
+that per-object decision before drawing; only the resolved non-native object
+stays unmarked on its complete SVG fallback. Never silently ignore an explicit
+`<object-key>=yes` declaration.
+
+**Per-page verification**: enumerate every `<object-key>=yes` on the current
+page and confirm a one-to-one key match. Each key identifies one parent marker
+and exactly one JSON metadata child; `<object-key>=no` and unlisted incidental
+objects have no marker. Finding one marker somewhere on a page is insufficient.
+
+```bash
+rg -n 'data-pptx-replace-with="(chart|table)"|<metadata type="application/json">' <project_path>/svg_output/<current_page>.svg
+```
+
**Table schema**: Native tables are rectangular DrawingML grids. Use `columns`
for the optional header row and `rows` for body rows; shorter rows are padded
with blank cells unless `strict_grid: true` is set. Tables may contain at most
diff --git a/skills/ppt-master/references/strategist-template.md b/skills/ppt-master/references/strategist-template.md
index 91ad0e87..24e4ec2e 100644
--- a/skills/ppt-master/references/strategist-template.md
+++ b/skills/ppt-master/references/strategist-template.md
@@ -85,4 +85,13 @@ For `mirror` / `layout`, write `pptx_structure.mode: structured` plus `template_
- **Adaptive refinement**: Initial definitions are complete. If construction shows that reusable framing or slot topology/bounds must change, return to Strategist to add a definition sourced from that page and update its assignment before execution resumes. Executor never mutates or extends the contract; export only compiles declared structure and never discovers or clusters Layouts.
- **Input prototypes**: Add one `page_layouts` row per page. Strict preserves that SVG's contract; adaptive keeps its Master and may declare a new output Layout; mirror also preserves literal visuals and text-node topology.
-**Chart compatibility**: Use `page_layouts` together with `page_charts` only when the selected prototype shell is compatible. For a chart page without an exact roster match, adaptive mode starts from the closest neutral prototype and declares an output Layout; strict mode selects an existing compatible Layout or revises the outline. Never omit `page_layouts` on a structured route.
+**Visualization compatibility**: Use `page_layouts` together with optional
+`page_visualizations` only when the selected prototype shell can carry the
+actual §IX information model. The primary `family/key` is a flexible
+page-local reference and does not change Layout identity, slot topology, or the
+final visualization type. A `structure` family reference remains Slide-local;
+it never becomes a reusable Layout or supplies Master/Layout/placeholder
+ownership. Without an exact prototype match, adaptive mode starts from the
+closest neutral prototype and declares an output Layout; strict mode selects an
+existing compatible Layout or revises the outline. Never omit `page_layouts`
+on a structured route, and never write legacy `page_charts` in a new lock.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index a95bb3cf..103a32c4 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -56,7 +56,7 @@ Do not force communication intent into one catalog label; Stage 1 records compos
| Reference | Preserve the selected direction or role; adapt its realization to context. |
| Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. |
-**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, chart/layout keys, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Fact research may precede confirmation; AI/web/slice follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
+**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, page-local visualization/Layout references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Fact research may precede confirmation; AI/web/slice follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement.
@@ -309,17 +309,18 @@ the effective outcome. Suggestions remain non-binding and never activate the
custom stage; only an explicit motion requirement or an enabled outcome may
require visible lifecycle-state preparation.
-Review planned pages through two lenses:
+Review planned pages through the three visualization information models:
-| Lens | Content shapes |
+| Family | Information model |
|---|---|
-| Numeric / data | comparisons, trends, proportions, KPIs, financials, rankings, distributions, funnels |
-| Structural information | rosters, agendas, principles, phases, journeys, capability maps, OKR cascades, roadmaps, strategic frameworks |
+| `chart` | Values, categories, time, weights, or duration determine mark geometry |
+| `structure` | Qualitative sequence, hierarchy, role, region, or relationship determines page-local topology |
+| `table` | Rows, columns, cells, headers, merges, alignment, and cell content form a grid |
-**Reference — not a constraint**: use catalog recall when it would help. Its CLI accepts 3–8 distinct English content-shape tags; a page already planned as a custom visualization or table needs no recall. Run:
+**Reference — not a constraint**: use unified recall when helpful. Supply 3–8 English content-shape tags; use `--family` only when the information model is certain. Skip recall for an already-planned custom visualization/table.
```bash
-python3 skills/ppt-master/scripts/chart_recall.py recall \
+python3 skills/ppt-master/scripts/visualization_recall.py recall \
--page P03 \
--tag "time series" \
--tag "three metrics" \
@@ -327,28 +328,29 @@ python3 skills/ppt-master/scripts/chart_recall.py recall \
--limit 6
```
-The command returns a bounded shortlist plus `no-template-match`. Read it unfiltered; `tail` / `head` / `grep` can hide ranked candidates. `confidence` is lexical only. At `high` / `medium`, keep no-match after candidate review. At `low` / `none`, use a fitting candidate directly; otherwise rerun once with `--semantic-fallback` before no-match. Do not open a second index.
+The command returns a bounded shortlist plus `no-template-match`. Read it unfiltered; `tail` / `head` / `grep` can hide ranked candidates. `confidence` is lexical only. At `high` / `medium`, keep no-match after candidate review. At `low` / `none`, use a fitting candidate directly; otherwise rerun once with `--semantic-fallback` before no-match. Do not open any family index separately.
**Selection**:
-1. Choose the most relevant candidate as a reference for that page. It does not lock the final visualization type or geometry and never applies to another page without its own row.
-2. Retain `no-template-match` when no reference fits. Choose a custom visualization, table, diagram/layout, or permitted image from the content semantics, communication job, and editability need. Record the choice only in §IX; never serialize `no-template-match` into §VII.
-3. Validate all selected keys before writing the lock:
+1. Choose at most one primary `family/key` per page. It is a flexible page-local reference, not a type/geometry/style/native lock. Keep embedded child visuals in §IX `Visualization`, not a second §VII row.
+2. If none fits, keep `no-template-match` and plan the fallback only in §IX; never serialize no-match.
+3. Validate every selected canonical reference before the lock:
```bash
-python3 skills/ppt-master/scripts/chart_recall.py validate <key> [<key> ...]
+python3 skills/ppt-master/scripts/visualization_recall.py validate \
+ <family>/<key> [<family>/<key> ...]
```
-A failed validation must be corrected with a recalled key. `no-template-match` is not a key and never appears in `page_charts`.
+Correct failed selections by recall; `no-template-match` never enters `page_visualizations`.
-**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.
+**Section VII selection list**: write `Page | Family | Template | Usage` for each primary reference; Family is `chart`, `structure`, or `table`, while Usage is semantic purpose, not geometry. Omit an empty §VII and path/summary/runners-up/no-match placeholders; §IX remains authoritative. Structure references stay Slide-local—only an installed Layout/Deck workspace owns reusable structure.
-**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.
+**Native-ready boundary**: Give every independent data chart and pure text-grid table in §IX `Visualization` a unique page-local semantic `kebab-case` key, then write one `Native-ready` map: `<key>=yes|no; ...`. Use `yes` only when an editable native object benefits the confirmed requirement/afterlife. Conceptual structures and incidental microvisuals stay unlisted.
```markdown
-| Page | Template | Usage |
-| --- | --- | --- |
-| P03 | line_chart | Compare the source metrics over time |
+| Page | Family | Template | Usage |
+| --- | --- | --- | --- |
+| P03 | chart | line_chart | Compare the source metrics over time |
```
**Native-geometry candidate detail**: Add `Native shape suggestion` to the
@@ -469,7 +471,7 @@ final Stage 2 `false`, explicit objects-off, or explicit all-motion-off; only th
includes transitions.
1. With Generate Step 4's retained complete final-confirmation state, read `${SKILL_DIR}/templates/design_spec_reference.md`.
-2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I, including one effective outcome plus provenance for Speaker Notes, Custom Animations, and Narration Audio. Resolve them from latest explicit user instruction → matching final Stage 2 proactive value → workflow default `enabled` / `disabled` / `disabled`; Narration Audio enabled requires Speaker Notes enabled without rewriting the raw proactive evidence, and a dependency-driven notes outcome records that provenance. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/chart patterns remain References unless promoted.
+2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I, including one effective outcome plus provenance for Speaker Notes, Custom Animations, and Narration Audio. Resolve them from latest explicit user instruction → matching final Stage 2 proactive value → workflow default `enabled` / `disabled` / `disabled`; Narration Audio enabled requires Speaker Notes enabled without rewriting the raw proactive evidence, and a dependency-driven notes outcome records that provenance. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, applicable capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/visualization patterns remain References unless promoted.
3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before entering an enabled refine-spec review or authoring `spec_lock.md`.
4. If enabled, run [`refine-spec`](../workflows/stages/refine-spec.md) after Gate 1; edit only that Design Spec and create no lock before explicit approval.
5. Read `${SKILL_DIR}/templates/spec_lock_reference.md`; create the lock once or resynchronize stale derived state from the approved Design Spec and context. Retain identity/refinements and stable roles/routing; omit unnamed page-local values, do not reopen evidence, and make no new recommendation.
@@ -492,7 +494,7 @@ includes transitions.
⛔ **GATE 2 — lock context fidelity.** After Gate 1 closes, author machine-relevant anchors/routing into `spec_lock.md`. The lock may normalize syntax and add justified recurring roles, but must not change identity, discard a refinement, introduce a direction, or become a field copy/allowlist. On contradiction, return to Gate 1 using retained confirmation by default or the approved revised Design Spec after refinement; fresh recovery reads persisted final evidence once only when active state is absent.
-**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, layout suggestion, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor context policy lives in [executor-base.md](executor-base.md) §2.1. Repair from Gate 2's active decision authority, then re-author affected lock rows.
+**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, visualization references, and route-specific PowerPoint structure. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, layout suggestion, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor context policy lives in [executor-base.md](executor-base.md) §2.1. Repair from Gate 2's active decision authority, then re-author affected lock rows.
**Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or recurring cross-page identity patterns require upstream repair; a page-local §VIII preferred image pattern follows [`executor-image.md`](./executor-image.md) and may change during realization. Executor never reverse-projects a local choice as planning fact. Promote recurring garnish upstream before reuse, read back and validate the affected planning fragments, and never add values to silence a comparison.
@@ -507,7 +509,7 @@ includes transitions.
- **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**: 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.
+ - **page_visualizations**: project §VII Page/Family/Template as `P<NN>: <family>/<template_key>`, at most once per page. Usage and child visuals stay in the Design Spec; omit no-match/empty sections. The reference does not lock type/geometry/native output. New locks never write legacy `page_charts`; it is read-only compatibility.
---
diff --git a/skills/ppt-master/scripts/docs/visualization-recall.md b/skills/ppt-master/scripts/docs/visualization-recall.md
index ef2894c8..f7af8bc9 100644
--- a/skills/ppt-master/scripts/docs/visualization-recall.md
+++ b/skills/ppt-master/scripts/docs/visualization-recall.md
@@ -62,9 +62,18 @@ python3 skills/ppt-master/scripts/visualization_recall.py validate \
chart/line_chart structure/quadrant_text_bullets table/basic_table
```
-The command is read-only. It exits `0` when every canonical `family/key` exists
-with its SVG and `1` otherwise. A Default `no-template-match` page appears in
-neither §VII nor `page_visualizations`; record its custom fallback in §IX.
+The command is read-only. It exits `0` when every supplied reference resolves
+to a registered SVG and `1` otherwise. New planning supplies canonical
+`family/key`. When validating an existing legacy mapping, opt into bare-key
+resolution explicitly; every key must resolve uniquely:
+
+```bash
+python3 skills/ppt-master/scripts/visualization_recall.py validate \
+ --legacy-bare pros_cons_chart
+```
+
+A Default `no-template-match` page appears in neither §VII nor
+`page_visualizations`; record its custom fallback in §IX.
## Selection boundary
diff --git a/skills/ppt-master/scripts/generate_examples_index.py b/skills/ppt-master/scripts/generate_examples_index.py
index 388421d4..8d57ea91 100644
--- a/skills/ppt-master/scripts/generate_examples_index.py
+++ b/skills/ppt-master/scripts/generate_examples_index.py
@@ -204,7 +204,7 @@ def generate_examples_index(examples_dir: str = 'examples') -> str:
content.append(
f"- [Role Definitions]({skill_link(skill_dir / 'references')})")
content.append(
- f"- [Chart Templates]({skill_link(skill_dir / 'templates' / 'charts' / 'README.md')})\n")
+ f"- [Visualization Templates]({skill_link(skill_dir / 'templates' / 'README.md')})\n")
# Footer
content.append("---\n")
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 337e0da0..1040863f 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -22,6 +22,9 @@
"skills/ppt-master/references/executor-base.md": 9250,
"skills/ppt-master/references/executor-structured.md": 5500,
"skills/ppt-master/references/executor-chart.md": 3500,
+ "skills/ppt-master/references/executor-visualization.md": 1250,
+ "skills/ppt-master/references/executor-structure.md": 1250,
+ "skills/ppt-master/references/executor-table.md": 1000,
"skills/ppt-master/references/executor-image.md": 2000,
"skills/ppt-master/references/executor-web-image.md": 750,
"skills/ppt-master/references/executor-notes.md": 1000,
@@ -309,14 +312,16 @@
"files": [],
"max_tokens": 92000
},
- "route.generate.quick-generate.chart": {
- "description": "Quick Generate with bounded chart recall, chart/table authoring, optional native-data metadata, and in-context coordinate verification before the final checker.",
+ "route.generate.quick-generate.visualization": {
+ "description": "Quick Generate with bounded visualization recall, all three information-model branches, optional native-data metadata, and chart-coordinate verification before the final checker.",
"scope": "cumulative",
"include": [
"route.generate.quick-generate",
+ "stage.generate.executor.visualization",
"stage.generate.executor.chart",
+ "stage.generate.executor.structure",
+ "stage.generate.executor.table",
"stage.generate.executor.native-data",
- "stage.generate.visualization-authoring",
"stage.generate.verify-charts"
],
"files": [
@@ -556,14 +561,16 @@
"files": [],
"max_tokens": 130000
},
- "route.generate.flat-no-image-chart": {
- "description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",
+ "route.generate.flat-no-image-visualization": {
+ "description": "Default flat Generate-PPTX path with visualization-reference consumption, all three information-model branches, optional native-data replacement, and chart verification.",
"scope": "cumulative",
"include": [
"route.generate.flat-no-image",
+ "stage.generate.executor.visualization",
"stage.generate.executor.chart",
+ "stage.generate.executor.structure",
+ "stage.generate.executor.table",
"stage.generate.executor.native-data",
- "stage.generate.visualization-authoring",
"stage.generate.verify-charts"
],
"files": [],
@@ -771,8 +778,8 @@
],
"max_tokens": 7000
},
- "stage.generate.visualization-authoring": {
- "description": "Conditional shared chart, structure, and table template authoring guidance.",
+ "maintenance.visualization-authoring": {
+ "description": "Shared chart, structure, and table catalog-template authoring guidance; not a Generate runtime load.",
"scope": "incremental",
"files": [
"skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md",
@@ -888,13 +895,37 @@
"max_tokens": 88000
},
"stage.generate.executor.chart": {
- "description": "Conditional chart/table page execution rules.",
+ "description": "Conditional value-driven chart execution rules.",
"scope": "incremental",
"files": [
"skills/ppt-master/references/executor-chart.md"
],
"max_tokens": 3500
},
+ "stage.generate.executor.visualization": {
+ "description": "Conditional selected visualization-reference resolution and flexible page-local adaptation rules.",
+ "scope": "incremental",
+ "files": [
+ "skills/ppt-master/references/executor-visualization.md"
+ ],
+ "max_tokens": 1250
+ },
+ "stage.generate.executor.structure": {
+ "description": "Conditional page-local qualitative-topology construction rules.",
+ "scope": "incremental",
+ "files": [
+ "skills/ppt-master/references/executor-structure.md"
+ ],
+ "max_tokens": 1250
+ },
+ "stage.generate.executor.table": {
+ "description": "Conditional semantic cell-grid construction rules.",
+ "scope": "incremental",
+ "files": [
+ "skills/ppt-master/references/executor-table.md"
+ ],
+ "max_tokens": 1000
+ },
"stage.generate.strategist.image": {
"description": "Conditional Strategist image/formula policy with the always-read layout math and compact composition vocabulary.",
"scope": "incremental",
@@ -1094,6 +1125,51 @@
"from": "skills/ppt-master/references/executor-base.md",
"to": "skills/ppt-master/references/shared-standards-core.md"
},
+ {
+ "concern": "visualization-reference-routing",
+ "from": "skills/ppt-master/references/executor-base.md",
+ "to": "skills/ppt-master/references/executor-visualization.md"
+ },
+ {
+ "concern": "structured-executor-routing",
+ "from": "skills/ppt-master/references/executor-base.md",
+ "to": "skills/ppt-master/references/executor-structured.md"
+ },
+ {
+ "concern": "chart-executor-routing",
+ "from": "skills/ppt-master/references/executor-base.md",
+ "to": "skills/ppt-master/references/executor-chart.md"
+ },
+ {
+ "concern": "structure-executor-routing",
+ "from": "skills/ppt-master/references/executor-base.md",
+ "to": "skills/ppt-master/references/executor-structure.md"
+ },
+ {
+ "concern": "table-executor-routing",
+ "from": "skills/ppt-master/references/executor-base.md",
+ "to": "skills/ppt-master/references/executor-table.md"
+ },
+ {
+ "concern": "native-data-routing",
+ "from": "skills/ppt-master/references/executor-base.md",
+ "to": "skills/ppt-master/references/native-data-interface.md"
+ },
+ {
+ "concern": "visualization-chart-routing",
+ "from": "skills/ppt-master/references/executor-visualization.md",
+ "to": "skills/ppt-master/references/executor-chart.md"
+ },
+ {
+ "concern": "visualization-structure-routing",
+ "from": "skills/ppt-master/references/executor-visualization.md",
+ "to": "skills/ppt-master/references/executor-structure.md"
+ },
+ {
+ "concern": "visualization-table-routing",
+ "from": "skills/ppt-master/references/executor-visualization.md",
+ "to": "skills/ppt-master/references/executor-table.md"
+ },
{
"concern": "structured-execution-contract",
"from": "skills/ppt-master/references/executor-structured.md",
@@ -1104,6 +1180,16 @@
"from": "skills/ppt-master/references/executor-chart.md",
"to": "skills/ppt-master/references/native-data-interface.md"
},
+ {
+ "concern": "chart-verification-handoff",
+ "from": "skills/ppt-master/references/executor-chart.md",
+ "to": "skills/ppt-master/workflows/stages/verify-charts.md"
+ },
+ {
+ "concern": "native-table-contract",
+ "from": "skills/ppt-master/references/executor-table.md",
+ "to": "skills/ppt-master/references/native-data-interface.md"
+ },
{
"concern": "strategist-image-routing",
"from": "skills/ppt-master/references/strategist.md",
diff --git a/skills/ppt-master/scripts/visualization_recall.py b/skills/ppt-master/scripts/visualization_recall.py
index 8e5a5848..19367ebf 100644
--- a/skills/ppt-master/scripts/visualization_recall.py
+++ b/skills/ppt-master/scripts/visualization_recall.py
@@ -312,12 +312,20 @@ def _run_recall(args: argparse.Namespace) -> int:
return 0
-def _resolve_validation_value(raw: str, family: str) -> VisualizationEntry:
+def _resolve_validation_value(
+ raw: str,
+ family: str,
+ *,
+ allow_legacy_bare: bool,
+) -> VisualizationEntry:
if "/" in raw:
return resolve_visualization_reference(raw)
if family != "all":
return resolve_visualization_reference(f"{family}/{raw}")
- return resolve_visualization_reference(raw, allow_legacy_bare=True)
+ return resolve_visualization_reference(
+ raw,
+ allow_legacy_bare=allow_legacy_bare,
+ )
def _run_validate(args: argparse.Namespace) -> int:
@@ -326,7 +334,16 @@ def _run_validate(args: argparse.Namespace) -> int:
valid_entries: list[tuple[str, VisualizationEntry]] = []
for value in selected:
try:
- valid_entries.append((value, _resolve_validation_value(value, args.family)))
+ valid_entries.append(
+ (
+ value,
+ _resolve_validation_value(
+ value,
+ args.family,
+ allow_legacy_bare=args.legacy_bare,
+ ),
+ )
+ )
except VisualizationCatalogError:
invalid.append(value)
@@ -348,7 +365,11 @@ def _run_validate(args: argparse.Namespace) -> int:
result = {"invalid": sorted(invalid), "valid": valid}
print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True))
if invalid:
- mapping_name = "page_charts" if args.legacy_output else "page_visualizations"
+ mapping_name = (
+ "page_charts"
+ if args.legacy_output or args.legacy_bare
+ else "page_visualizations"
+ )
print(
"Error: replace each invalid reference with one returned by recall, or "
f"keep no-template-match out of Section VII and {mapping_name} while "
@@ -407,6 +428,16 @@ def build_parser(*, legacy_output: bool = False) -> argparse.ArgumentParser:
validate = subparsers.add_parser("validate", help="Validate selected references.")
validate.add_argument("keys", nargs="+", help="One or more keys or family/key references.")
+ validate.add_argument(
+ "--legacy-bare",
+ action="store_true",
+ default=legacy_output,
+ help=(
+ argparse.SUPPRESS
+ if legacy_output
+ else "Allow unqualified keys from an existing legacy page_charts mapping."
+ ),
+ )
_add_family_argument(validate)
validate.set_defaults(handler=_run_validate)
return parser
diff --git a/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md b/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md
index 48ae6c10..510fa682 100644
--- a/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md
+++ b/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md
@@ -259,6 +259,11 @@ placeholder 所有权标记。即使 Structure 预览占满整个 `1280×720`
Pie、Donut、Radar 使用对应中心和半径格式。该注释是工具输入,不得作为“清理注释”删除。
+Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与
+`id="chartArea"`。Executor 在项目页面组合多个已验证 Chart 对象时,改用
+[`executor-chart.md`](../references/executor-chart.md) 定义的 semantic object key
+和 scoped marker;不能在同一 SVG 中复制多个 `chartArea` id。
+
### 6.2 Native Chart/Table
**Hard rule**: 只有 [`native-data-interface.md`](../references/native-data-interface.md) 支持的真实 Chart 或纯文本 Table 使用 replacement marker。JSON metadata 与可见 fallback 必须表达同一份数据。Structure 永远不使用 Chart/Table replacement marker。
diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.md
index 75b26081..af16248e 100644
--- a/skills/ppt-master/templates/charts/README.md
+++ b/skills/ppt-master/templates/charts/README.md
@@ -47,5 +47,6 @@ One selected SVG is a flexible reference for one mapped page. Design Spec §IX
or the Quick active-context decision plus source data owns final semantics.
Project palette, typography, chrome, grouping, capacity, and geometry remain
adaptable. Selecting a chart reference does not itself select native output;
-`Native-ready` and explicit `--native-charts-and-tables` export remain separate
-decisions.
+§IX/Quick names independent objects separately and decides
+`<object-key>=yes|no`, while explicit `--native-charts-and-tables` export is a
+second opt-in.
diff --git a/skills/ppt-master/templates/charts/line_chart.svg b/skills/ppt-master/templates/charts/line_chart.svg
index 2f396280..d06152de 100644
--- a/skills/ppt-master/templates/charts/line_chart.svg
+++ b/skills/ppt-master/templates/charts/line_chart.svg
@@ -14,7 +14,7 @@
data-pptx-replace-with="chart">
<metadata type="application/json">
{
- "name": "line_chart",
+ "name": "line-chart",
"x": 120,
"y": 141,
"width": 1063.1,
diff --git a/skills/ppt-master/templates/charts/matrix_2x2.svg b/skills/ppt-master/templates/charts/matrix_2x2.svg
index 2f89eb1f..abf02f72 100644
--- a/skills/ppt-master/templates/charts/matrix_2x2.svg
+++ b/skills/ppt-master/templates/charts/matrix_2x2.svg
@@ -3,7 +3,7 @@
font-size="12">
<!--
Matrix 2x2 Chart Template
- Usage: Four-quadrant analysis
+ Usage: Value-driven 2x2 bubble matrix (X, Y, bubble size)
Scenarios: BCG Matrix, risk assessment, priority analysis, strategic evaluation
-->
<defs>
@@ -31,7 +31,7 @@
font-size="14" font-weight="500" fill="#94A3B8">Business Impact vs Implementation Effort · Bubble size represents resource cost</text>
</g>
<!-- Matrix Main Area -->
- <g id="matrixArea" data-pptx-bounds="0 128 1137 592">
+ <g id="chartArea" data-pptx-bounds="0 128 1137 592">
<!-- Quadrants -->
<!-- Q1: Top Right (Stars) -->
<rect x="565" y="170" width="480" height="240" fill="#ECFDF5" stroke="#FFFFFF" stroke-width="4" rx="4"/>
@@ -44,6 +44,7 @@
<!-- Axes -->
<line x1="85" y1="410" x2="1055" y2="410" stroke="#0F172A" stroke-width="3" marker-end="url(#arrowX)"/>
<line x1="565" y1="160" x2="565" y2="650" stroke="#0F172A" stroke-width="3" marker-start="url(#arrowY)"/>
+ <!-- chart-plot-area: 85,170,1045,650 -->
<!-- X-Axis Labels -->
<text x="565" y="685"
font-size="15" font-weight="700" fill="#0F172A" text-anchor="middle">Implementation Effort</text>
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 2f975997..ca7bb3e3 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -158,8 +158,8 @@ Use the §VII table only when at least one real catalog reference is selected. A
```markdown
## VII. Visualization Reference List
-| Page | Template | Usage |
-| --- | --- | --- |
+| Page | Family | Template | Usage |
+| --- | --- | --- | --- |
## VIII. Image Resource List
@@ -167,9 +167,20 @@ Use the §VII table only when at least one real catalog reference is selected. A
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
```
-§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.
+§VII lists at most one primary page-local reference per page: Family is
+`chart|structure|table`, Template is its canonical key, and Usage is semantic
+purpose—not geometry. Resolve `family/key` through the shared catalog; never
+derive a charts path from a bare key. §IX owns final information models and
+embedded child visuals, so the reference stays flexible. Structure references
+are Slide-local; Layout/Deck workspaces alone own reusable structure. Omit an
+empty §VII and path/summary/runners-up/no-match placeholders; put unmatched
+fallbacks in §IX. Legacy rows remain readable; new specs use four columns.
+
+In §IX `Visualization`, give every independent data chart and pure text-grid
+table a unique page-local `kebab-case` key. Add one `Native-ready` map:
+`<key>=yes|no; ...`. Use `yes` only when an editable native object benefits the
+confirmed requirement/afterlife. Conceptual structures and incidental
+microvisuals stay unlisted as ordinary SVG.
In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Write one concise, non-empty `Layout pattern` suggestion in ordinary language; optionally cite hierarchical ids from the layout library when they help recall a technique. Set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them.
@@ -216,7 +227,7 @@ never write an empty or `none` placeholder:
- **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order>
```
-Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visualization; mark it data-driven when source values determine geometry. §IX stays authoritative without a catalog match and may choose a custom visualization or table. Add `Native shape suggestion` only when a preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name the semantic result plus candidate family or Boolean operands, never implementation geometry or keys. Executor chooses the primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; chart rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
+Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visualization. Name every actual model—value-driven geometry, qualitative topology, or cell grid—and any child visual here, not in another §VII row; independent Chart/Table entries use the semantic object keys defined above. §IX may choose a custom fallback. Add `Native shape suggestion` only when a preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name the semantic result plus candidate family or Boolean operands, never implementation geometry or keys. Executor chooses the primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add keyed `Native-ready` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; visualization rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.
For free-design pages, describe `Layout` through relationships, hierarchy, regions, and column spans; do not prescribe element-level `x`, `y`, `width`, or `height` or duplicate the global geometry in §II/§V. Exact coordinates belong to Executor SVG authoring. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it.
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 0e2cc8a7..f3d03585 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -29,8 +29,9 @@ After Generate Step 4 Gate 1, read the completed Design Spec and current page/re
| `pptx_structure` | `mode` | Values: `flat`, `structured` |
| `forbidden` | Literal list items | General standards stay in their owning reference |
-Optional data sections: `images`, `page_visualizations`. Existing locks may
-retain legacy `page_charts`; never write both sections for the same page.
+Optional data sections: `images`, `page_visualizations`. New locks never write
+legacy `page_charts`; existing locks may retain it for read-only compatibility.
+Never declare the same page in both sections.
The required universal block is:
@@ -74,8 +75,10 @@ Structured section value shapes:
Project each §VII `Page | Family | Template | Usage` row's Page, Family, and
Template fields into `page_visualizations` as `<family>/<key>`; Usage stays in
the Design Spec. The families are `chart`, `structure`, and `table`. This is a
-page-local reference, not a type/geometry lock. The family/key must resolve
-through its live family registry to one SVG; no-match stays in §IX.
+single primary page-local reference, not a type/geometry/native lock. Write at
+most one per page; child visuals stay in §IX. Resolve it through the shared live
+catalog to one SVG; no-match stays in §IX. Structure references remain
+Slide-local and never create Master/Layout/placeholder ownership.
```markdown
## page_visualizations
diff --git a/skills/ppt-master/templates/tables/README.md b/skills/ppt-master/templates/tables/README.md
index 852a5f56..7317c0c8 100644
--- a/skills/ppt-master/templates/tables/README.md
+++ b/skills/ppt-master/templates/tables/README.md
@@ -37,5 +37,6 @@ family, and catalog rules. Table-specific requirements are:
contract explicitly supports them.
Selecting a table reference does not itself select native output. Design Spec
-§IX `Native-ready` and explicit `--native-charts-and-tables` export remain
-separate decisions.
+§IX/Quick names independent objects separately and decides
+`<object-key>=yes|no`; explicit `--native-charts-and-tables` export is a second
+opt-in.
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index cc412d82..7ac78991 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -533,13 +533,19 @@ Keep the core's shared visual-quality defaults and `svg-effects.md` §6.1 Visual
| Deterministic trigger | Additional references |
|---|---|
| `pptx_structure.mode: structured` | `executor-structured.md` + `pptx-structure-interface.md` |
-| Any data chart/table, including mini or inset charts and sparklines | `executor-chart.md` |
-| Preset pattern or supported native chart/table | `native-data-interface.md` before drawing |
+| Selected §VII / `page_visualizations` `family/key`, or legacy `page_charts` row | `executor-visualization.md` + the selected family branch |
+| Actual value-driven geometry, including mini/inset charts and sparklines | `executor-chart.md` |
+| Actual page-local qualitative topology | `executor-structure.md` |
+| Actual cell grid | `executor-table.md` |
+| Used preset pattern fill, or independent Chart/Table with §IX `<object-key>=yes` | `native-data-interface.md` before that object |
| `spec_lock.md images` / §VIII has an image/formula row, or the template has bundled images | `executor-image.md` + `image-layout-spec.md` + `image-layout-patterns.md` + `svg-image-embedding.md` |
| At least one placed image has `Status: Sourced` | `executor-web-image.md` after the image branch |
| All SVG pages and SVG quality gates are complete, and the effective Speaker Notes outcome in `design_spec.md §I` is enabled | `executor-notes.md` before generating speaker notes |
-No branch is loaded by analogy. Evaluate these triggers from `spec_lock.md`, §VII/§VIII, the selected style, and the current page plan.
+No branch is loaded by analogy. Evaluate `spec_lock.md`, §VII/§VIII, style, and
+the current page plan. Triggers are additive: a selected family loads its
+reference branch, while each actual information model loads its owner
+independently. Family never locks final type/geometry or implies `Native-ready`.
**Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.
@@ -554,7 +560,12 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/stages/live-preview.md`](stages/live-preview.md).
- The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/stages/live-preview.md`](stages/live-preview.md) Notes.
-**Conditional reference reads**: Follow `executor-structured.md` for template Design Spec/prototypes and `executor-chart.md` for chart SVGs. Read each selected full reference once per valid context; reread only after a known change or context invalidation. Flat routes skip template reads. Summaries and sidecars never replace full SVGs.
+**Conditional reference reads**: `executor-structured.md` owns template specs
+and prototypes. `executor-visualization.md` resolves a selected canonical or
+legacy value; read only its returned SVG plus applicable family branches. Read
+each full reference once per valid context and reread only after change/context
+invalidation. Flat routes skip template reads; never substitute summaries,
+sidecars, or guessed family paths.
> Image facts: trust the latest `analysis/image_analysis.csv` from the Step 4 inventory read or the Step 5 post-acquisition refresh. If `images/` changed since, re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before layout; if the folder is empty, use no image inventory and ignore a stale CSV.
@@ -616,7 +627,7 @@ gate-signal: method=<rule resolved, or none> | page-local=<count> | not-exercise
```bash
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json
```
-- **MUST**: Before this gate, every chart/table whose Design Spec §IX page block says `Native-ready: yes` already has its own draw-time marker plus JSON metadata. Rows marked `no` and incidental microvisuals remain ordinary SVG. For legacy specs only, a matching §VII value may supply the decision when §IX has no field.
+- **MUST**: Before this gate, every §IX `Native-ready` entry `<object-key>=yes` already has one matching draw-time marker group and JSON metadata child; `=no` and incidental microvisuals remain ordinary SVG. A legacy bare `yes|no` is readable only when that page has exactly one eligible object; it never derives from §VII.
- Run the command unfiltered—do not pipe it through `tail`, `head`, `grep`, or another output truncator. One invocation already scans every page and reports the complete issue set.
- On failure, review all `blocking` errors and all advisory warnings from that run before editing. Choose which warnings merit work, fix every blocking error and the selected warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never run the checker between individual fixes or use repeated invocations to discover one next issue at a time. If terminal output is truncated, extract only `categories.blocking.issues` and, when needed, `categories.introduced.issues` from the report written by that same run.
- Every `warning` is advisory and non-blocking: do not return the page for mandatory modification, do not auto-normalize user-authored compatible syntax, and do not require an acknowledgement/disposition line. Recommendation warnings identify the generated-SVG default; fidelity/quality warnings may be reported when material, but the existing input may ship unchanged. If a condition must be corrected before release, the checker must classify it as an `error`, not a `warning`.
diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.md
index ef652a43..ba0d8477 100644
--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md
+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md
@@ -251,7 +251,7 @@ In the UI branch, after the final wait returns, read
branch, retain the visible final summary instead and require no UI result. After
any launched UI path, run `--shutdown` before Step 6; do not assume `5050`.
-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 final confirmation state 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 UI evidence 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.
+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 final confirmation state 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 UI evidence afterward. §VII contains only `Page | Family | Template | Usage` rows for selected `chart`, `structure`, or `table` catalog references; project their family-qualified keys into `spec_lock.md` `page_visualizations`. Unmatched visualization 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.
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index b12996bd..2e970eb7 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -234,10 +234,41 @@ because Quick is expected to be faster is not.
| Real subject, place, product, evidence, atmosphere, or scene benefits from visual grounding | Supplied/extracted, web, AI, or sliced image |
| A compact semantic cue clarifies a category, process, KPI, state, navigation item, or real brand | Prepared project-local icon |
| Editable geometry can express a relationship, flow, emphasis, callout, symbol, or diagram | Basic SVG primitive, exact Office preset, Boolean result, then necessary freeform |
-| Values encode comparison, trend, distribution, composition, relationship, or a text grid | Data chart or table, with optional native Chart/Table metadata when its object model is useful |
+| Values, categories, time, weights, or duration determine mark geometry | Value-driven chart |
+| Sequence, hierarchy, role, region, or relationship determines page-local topology | Qualitative structure |
+| Rows, columns, cells, headers, merges, and alignment form the information model | Cell-grid table |
| Mathematical notation is clearer as typeset math than ordinary text | Rendered formula asset |
| Typography, spacing, and simple geometry already carry the message | Use no additional visual carrier |
+**Visualization recall — optional page-local reference**: When a reusable
+reference would help, run the unified recall with 3–8 English semantic tags.
+Use its default all-family search; add `--family chart|structure|table` only
+when the page's information model is already certain.
+
+```bash
+python3 skills/ppt-master/scripts/visualization_recall.py recall \
+ --page P03 \
+ --tag "time series" \
+ --tag "three metrics" \
+ --tag "direction over time" \
+ --limit 6
+```
+
+Read the result unfiltered and apply
+[`visualization-recall.md`](../../scripts/docs/visualization-recall.md)'s
+low-confidence semantic fallback before retaining `no-template-match`. Choose at most one primary
+`family/key` for a page, validate it with `visualization_recall.py validate`,
+and keep its short purpose only in active context. The reference remains
+flexible: it does not lock final type, geometry, style, or native output.
+Describe an embedded child chart, structure, or table in the page's active
+decision rather than selecting a second primary reference. Actual information
+models determine the loaded execution branches. Give every independent
+Chart/Table a page-local semantic `kebab-case` object key; keep its
+`<object-key>=yes|no` native-ready decision and any promoted chart-verification
+status in active context. A structure-family reference is always Slide-local
+and never becomes a Layout workspace or reusable Master/Layout/placeholder
+contract.
+
Prepare only the resource paths needed by the decided pages:
| Resource | Required preparation |
@@ -248,7 +279,7 @@ Prepare only the resource paths needed by the decided pages:
| AI image | Follow `image-base.md` + `image-generator.md`; keep `image_prompts.json` and its human-readable sidecar |
| Web image | Follow `image-base.md` + `image-searcher.md`; keep query/status data and `image_sources.json`, including any required on-slide attribution |
| Illustration slice | Generate or obtain the parent sheet, run `slice_images.py`, and place only the resulting element files |
-| Data chart/table | Keep source values and the chosen page treatment in active context; load the chart/table authorities in §3 before drawing and write native replacement metadata only when selected |
+| Visualization | Keep source values, qualitative relationships, cell topology, and the chosen page treatment in active context; load every applicable family authority in §3 before drawing and write native replacement metadata only for an independently selected native-ready Chart/Table object |
**Image inspection boundary**: acquisition-time suitability review follows the
owning AI/web/slice reference. Once resources reach terminal status, SVG
@@ -299,10 +330,17 @@ for a non-default canvas.
| Deterministic trigger | Additional authority |
|---|---|
-| Any data chart or text-grid table, including mini/inset charts and sparklines | [`executor-chart.md`](../../references/executor-chart.md); use bounded [`chart_recall.py`](../../scripts/docs/chart-recall.md) only when a reusable visualization reference would help |
-| Preset pattern or selected PowerPoint-native Chart/Table replacement | [`native-data-interface.md`](../../references/native-data-interface.md) before drawing the object |
+| A selected primary `family/key` | [`executor-visualization.md`](../../references/executor-visualization.md), then the matching chart, structure, or table family authority for interpreting that reference |
+| Any actual value-driven geometry, including mini/inset charts and sparklines | [`executor-chart.md`](../../references/executor-chart.md) |
+| Any actual page-local qualitative topology | [`executor-structure.md`](../../references/executor-structure.md) |
+| Any actual cell grid | [`executor-table.md`](../../references/executor-table.md) |
+| A used preset pattern fill, or one independent Chart/Table object selected as native-ready in active context | [`native-data-interface.md`](../../references/native-data-interface.md) before drawing that object |
| Any data-driven chart geometry | [`verify-charts.md`](../stages/verify-charts.md) after the complete roster and before the one final checker |
+Selected-reference family and final information model are independent loading
+signals: load both applicable authorities when they differ. Family selection
+never makes an object native-ready.
+
Keep the core's shared visual-quality / leading defaults and `svg-effects.md` §6.1 Visual Job Router active while authoring. Explicit user/template requirements and the resolved style override compatible aesthetic defaults, never technical Required / Forbidden boundaries.
**Per-page execution anchors**: apply the transient core-message, typography-role, body-frame, density, and composition anchors resolved in §2 while authoring; they guide the current run without creating a persisted planning artifact.
diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.md
index 0a237d58..83342796 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -39,7 +39,23 @@ Verify the project's planning-session artifacts before doing anything else:
| `<project_path>/design_spec.md` | Always | Complete approved design narrative and Section IX page outline; read it completely once in this fresh execution context |
| `<project_path>/images/` plus files whose row status requires existence | `spec_lock images` references any image | `Existing` / `Generated` / `Sourced` / `Rendered` files must exist; an absent `Needs-Manual` file remains allowed until the Step 7 readiness gate |
| `<project_path>/templates/` | `spec_lock page_layouts` references any | Layout / mirror prototypes required by execution |
-| `skills/ppt-master/templates/charts/` | `spec_lock page_charts` references any | Shared chart SVGs selected by key |
+| Resolver-returned visualization SVG | `spec_lock page_visualizations` or legacy `page_charts` references any | Shared page-local SVG selected through the live family catalogs |
+
+Resolve every visualization value through the shared catalog resolver before
+Step 6. The CLI below delegates to that resolver and returns each real family
+path. Validate canonical `family/key` from `page_visualizations` directly; opt
+into bare-key resolution only for values read from legacy `page_charts`:
+
+```bash
+python3 skills/ppt-master/scripts/visualization_recall.py validate \
+ <family/key> [<family/key> ...]
+python3 skills/ppt-master/scripts/visualization_recall.py validate \
+ --legacy-bare <legacy-key> [<legacy-key> ...]
+```
+
+Require every returned SVG to exist. Never construct a path from the key,
+guess a family directory, or prefer one registry. Failed, missing, or ambiguous
+resolution is a missing planning dependency and stops this stage.
If any required artifact is missing, report it and stop this stage. Do not enter Step 6 or invent a replacement artifact. Recover by artifact owner:
diff --git a/skills/ppt-master/workflows/stages/verify-charts.md b/skills/ppt-master/workflows/stages/verify-charts.md
index 09ec600c..1a55d59f 100644
--- a/skills/ppt-master/workflows/stages/verify-charts.md
+++ b/skills/ppt-master/workflows/stages/verify-charts.md
@@ -1,10 +1,10 @@
---
-description: Conditional quality-gate stage for chart coordinate verification.
+description: Conditional quality-gate stage for data-chart geometry and encoding verification.
---
# Verify Charts Stage
-> Conditional Generate-PPTX quality stage. Run after a deck containing data charts has finished SVG generation, before post-processing & export. Catches the 10–50 px coordinate errors AI models routinely introduce when mapping data to pixel positions.
+> Conditional Generate-PPTX quality stage. Run after a deck containing data charts has finished SVG generation, before post-processing & export. Catches coordinate and visual-encoding errors introduced while mapping source values into SVG marks.
In Default Generate this stage is **context-independent**: it reads
`design_spec.md` and the generated SVGs, then runs the calculator script. The
@@ -14,7 +14,7 @@ restart Quick rather than inventing a page plan from finished files.
## When to Run
-- The deck contains one or more data visualization charts where source values determine SVG geometry: bar lengths/heights, point positions, arc angles, polygon vertices, connector endpoints, bubble centers/radii, or flow widths/paths.
+- The deck contains one or more data visualization charts where source values determine SVG geometry or visual encoding: bar lengths/heights, point positions, arc angles, polygon vertices, connector endpoints, bubble centers/radii, flow widths/paths, cell colors, or word sizes.
- SVGs are generated to `<project_path>/svg_output/`. Default enters from its declared quality-gate order; Quick runs this stage before its one lockless final checker.
- Post-processing (`finalize_svg.py`, `svg_to_pptx.py`) has **not yet** run.
@@ -22,80 +22,85 @@ The calculator has direct CLI models for simple bars, lines/scatter, pie/donut,
---
-## Step 1: Build the page list from the active profile authority
+## Step 1: Build the chart-object list from the active profile authority
-| Active profile | Page-list authority |
+| Active profile | Object-list authority |
|---|---|
| Default Generate | `design_spec.md §IX` plus the legacy §VII fallback below |
-| Quick Generate | The still-active page decisions that produced the SVGs, cross-checked against every `chart-plot-area` marker; no Design Spec, lock, or substitute planning artifact is created |
+| Quick Generate | The still-active semantic object keys and page decisions that produced the SVGs, cross-checked against every `chart-plot-area` marker; no Design Spec, lock, or substitute planning artifact is created |
For Default, read `<project_path>/design_spec.md` §IX Content Outline as the
-authoritative page roster and include every page whose `Visualization`
-explicitly declares SVG geometry driven by data values. Cross-check §VII when
-present to resolve a selected catalog key; absence from §VII means only that no
-reusable reference was selected. For legacy specs, a real §VII data-chart row
-may enumerate the page when its §IX block predates the explicit data-driven
-declaration.
+authoritative roster and include every semantic object key whose
+`Visualization` entry declares SVG geometry driven by data values. Cross-check
+§VII only to resolve a selected catalog reference; absence means no reusable
+reference was selected. For a legacy spec whose §IX predates object keys, one
+real §VII data-chart row may supply one legacy chart object for that page.
-For Quick, enumerate every page the current agent just authored with
-value-driven geometry, then search `svg_output/` once for `chart-plot-area` and
-compare the marker pages one-for-one with that active list. Add a missing marker
-before continuing; investigate an unexpected marker instead of silently adding
-or dropping a page. Keep the list in active context only.
+For Quick, enumerate every promoted chart object's semantic key and page, then
+search `svg_output/` once for `chart-plot-area`. Compare objects and marker
+wrappers one-for-one. Add a missing scoped marker before continuing;
+investigate an unexpected marker instead of silently adding or dropping an
+object. Keep the list in active context only.
-Classify each included page into exactly one mode:
+Classify each included chart object into exactly one mode:
Incidental microvisuals not promoted under the active profile authority are not
-inferred into this list. Default repairs that page's §IX `Visualization` first;
+inferred into this list. Default repairs that object's §IX `Visualization` first;
Quick makes the promotion decision immediately in active context and updates
the SVG marker before verification.
| Mode | `charts_index.json` keys | Notes |
|------|--------------------------|-------|
-| `direct-calc` | `column_chart`, `horizontal_bar_chart` | Use `calc bar`; add `--horizontal` for horizontal bars. |
+| `direct-calc` | `column_chart`, `horizontal_bar_chart`, `histogram_chart` | Use `calc bar`; add `--horizontal` for horizontal bars. Histogram bins use contiguous bars on the numeric x-axis. |
| `direct-calc` | `line_chart`, `area_chart`, `scatter_chart` | Use `calc line`; area uses line output as the top boundary, then closes to `y_max`. |
| `direct-calc` | `pie_chart`, `donut_chart` | Use `calc pie`; donut passes `--inner-radius`. |
| `direct-calc` | `radar_chart` | Use `calc radar`; separate subcommand, not under `calc pie`. |
-| `decomposable-calc` | `stacked_bar_chart`, `stacked_area_chart`, `grouped_bar_chart`, `dumbbell_chart`, `pareto_chart`, `dual_axis_line_chart`, `bullet_chart`, `butterfly_chart`, `waterfall_chart`, `box_plot_chart`, `gantt_chart` | Verify by repeated direct calculations; see recipes below. |
-| `partial-calc` | `bubble_chart` | Use `calc line` for `cx/cy`; verify radius only when a size scale is explicit. |
-| `formula-verify` | `progress_bar_chart`, `gauge_chart`, `funnel_chart` | One-line math; record the formula and resulting length/angle/width in the receipt, no calculator call needed. |
-| `manual-verify` | `sankey_chart`, `heatmap_chart`, `treemap_chart` | Data-driven geometry exists, but the current calculator has no complete layout model. Inspect and report; do not silently skip. |
-
-**Out of scope** (do not include in the receipt unless the page uses a data-driven sub-chart inside the layout):
-
-- Pure text/number dashboards: `kpi_cards`.
-- Tables: `comparison_table`, `basic_table`, `consulting_table`, `project_schedule_table`, `financial_statement_table`, `feature_matrix_table`, `harvey_balls_table`.
-- Information graphics / frameworks / diagrams whose positions are layout-driven rather than value-driven: e.g. `hub_spoke`, `hub_inward_arrows`, `quadrant_text_bullets`, `quadrant_bubble_scatter` (BCG-style four-quadrant text grid — the visual bubbles are decoration, not value-mapped points), `matrix_2x2` (fixed quadrant cells with text cards), `mind_map`, `process_flow`, `numbered_steps`, `timeline`, `roadmap_vertical`, `layered_architecture`, `module_composition`, `pipeline_with_stages`, `client_server_flow`, `top_down_tree`, `journey_map`, `agenda_list`. If a deck genuinely uses these as data-driven scatter (rare — values mapped to actual `cx/cy`), promote to `partial-calc` and explain in the receipt.
+| `decomposable-calc` | `stacked_bar_chart`, `stacked_area_chart`, `grouped_bar_chart`, `dumbbell_chart`, `pareto_chart`, `dual_axis_line_chart`, `bullet_chart`, `butterfly_chart`, `waterfall_chart`, `box_plot_chart`, `gantt_chart`, `bar_of_pie_chart`, `pie_of_pie_chart`, `stock_chart` | Verify by repeated direct calculations; see recipes below. |
+| `partial-calc` | `bubble_chart`, `matrix_2x2` | Use `calc line` for x/y-driven `cx/cy`; verify radius only when a size scale is explicit. |
+| `formula-verify` | `progress_bar_chart`, `gauge_chart`, `funnel_chart`, `sunburst_chart` | Record the formula and resulting length/angle/width in the receipt; sunburst verifies each ring's value-derived arc lengths and offsets. |
+| `manual-verify` | `sankey_chart`, `heatmap_chart`, `treemap_chart`, `word_cloud` | Data-driven geometry or encoding exists, but the current calculator has no complete layout model. Inspect and report; do not silently skip. |
+
+**Family boundary**: this table covers every canonical key in
+`templates/charts/charts_index.json` exactly once. Do not put a Structure or
+Table reference in the chart receipt merely because it contains shapes or
+numbers. A fixed named-quadrant page uses
+`structure/quadrant_text_cards`; `chart/matrix_2x2` is reserved for plotted
+items whose x position, y position, and optional radius encode data. Every
+embedded data chart inside a Structure or Table page is its own object when the
+active §IX `Visualization` decision declares and keys that child chart.
Resulting list:
```
-P03 03_market_share.svg type=bar mode=direct-calc
-P07 07_growth.svg type=line mode=direct-calc
-P11 11_share_split.svg type=pie mode=direct-calc
-P15 15_pareto.svg type=pareto mode=decomposable-calc
+P03 market-share 03_market_share.svg type=bar mode=direct-calc
+P03 margin-trend 03_market_share.svg type=line mode=direct-calc
+P11 share-split 11_share_split.svg type=pie mode=direct-calc
+P15 pareto-causes 15_pareto.svg type=pareto mode=decomposable-calc
```
In Default, if §VII is absent, continue from §IX; this is the normal state when
-all chart pages use custom structures. Do not guess from SVG content when §IX
-declares no data-driven page. In Quick, do not treat marker search as a
-replacement for the still-active authoring decisions; use it as the required
-cross-check.
+all chart objects use custom structures. Do not guess from SVG content when §IX
+declares no data-driven object. In Quick, marker search is only the required
+cross-check, never a replacement for active authoring decisions.
-If the filtered list is empty, output `verify-charts: active profile declares no data-driven chart geometry, nothing to verify` and stop.
+If the filtered list is empty, output `verify-charts: active profile declares no data-driven chart objects, nothing to verify` and stop.
---
-## Step 2: Per page — read SVG, run calculator, compare, update
+## Step 2: Per object — read its SVG scope, calculate, compare, update
-For each page in the Step 1 list:
+For each object in the Step 1 list:
1. Read `<project_path>/svg_output/<page>.svg`.
-2. Locate the plot-area definition:
- - Preferred: `<!-- chart-plot-area: ... -->` marker placed by Executor (see [executor-chart.md §2.1](../../references/executor-chart.md)). Read coordinates directly.
- - If missing: derive the plot area from the SVG's axis lines (rectangular charts) or center/radius elements (radial charts). Then **add the marker back to the SVG** so future runs are not paying this cost again.
-3. Read the data series from the SVG's `<text>` label/value elements.
-4. **Read axis tick labels for every axis-based chart.** Locate the `<text>` elements along the value axis — X-axis labels for horizontal bars, Y-axis labels for vertical bars, and Y-axis labels for line-like charts. Extract the first and last tick values to determine the axis range (e.g. `0%` to `120%` → range `0,120`). Pass this range as `--value-range`, `--y-range`, or `--x-range` as appropriate. Use the attached `--*-range=min,max` form, which also keeps a negative minimum from being parsed as another option. Radar uses `--max-value` instead of a range: read the outermost ring's tick value and pass it as `--max-value`. If the SVG has no explicit tick labels (data labels only, no grid), omit the range and let the calculator auto-normalize — but flag the receipt as `scale=auto (no ticks)`.
+2. Locate `<g id="<object-key>">` and its one plot-area marker. The marker
+ payload starts `chart-plot-area: object=<object-key> |` and belongs inside
+ `<g id="<object-key>-chartArea">`. Accept a legacy unscoped marker and
+ `id="chartArea"` only when the page has exactly one verified chart. A
+ multi-chart page may not mix scoped and unscoped markers. If a marker is
+ missing, derive it from that object's axes or center/radius and add the
+ scoped marker before continuing.
+3. Read only that object's data series and label/value elements.
+4. **Read axis tick labels for every axis-based chart inside the same object scope.** Locate the `<text>` elements along the value axis — X-axis labels for horizontal bars, Y-axis labels for vertical bars, and Y-axis labels for line-like charts. Extract the first and last tick values to determine the axis range (e.g. `0%` to `120%` → range `0,120`). Pass this range as `--value-range`, `--y-range`, or `--x-range` as appropriate. Use the attached `--*-range=min,max` form, which also keeps a negative minimum from being parsed as another option. Radar uses `--max-value` instead of a range: read the outermost ring's tick value and pass it as `--max-value`. If the SVG has no explicit tick labels (data labels only, no grid), omit the range and let the calculator auto-normalize — but flag the receipt as `scale=auto (no ticks)`.
**Local vs absolute coordinates.** Many chart templates wrap chart content in `<g transform="translate(cx, cy)">` or similar, so child `<circle>`/`<polygon>`/`<rect>` coords are relative to that origin (e.g. radar polygon at `0,-198`, donut paths starting from `0,0` inside a translated `<g>`, dumbbell circles at `cy="0"` inside a per-row translated `<g>`). The calculator outputs **absolute** SVG coordinates. Before comparing, either add the wrapping translate's offset to the SVG coords or subtract it from the calculator's output — pick one direction and apply it consistently.
5. Run the matching calculator command:
@@ -243,52 +248,57 @@ python3 skills/ppt-master/scripts/svg_position_calculator.py calc line \
3. Compare each waterfall rect's `(x, y, width, height)` against the calculated pair. Connector lines should run from `(x + width, top_or_bot[i].Y)` to `(x_next, top_or_bot[i+1].Y)` at the matching shared cumulative value.
4. Total bars (full-height start/end) use `bot = 0` and the calc reduces to the standard `calc bar` recipe.
-**Bubble chart / quadrant bubble scatter** — partial calculator support:
+**Bubble chart / plotted 2×2 matrix** — partial calculator support:
1. Use `calc line` to verify bubble centers (`cx/cy`) from the X/Y values and axis ticks.
-2. Verify radius only if `design_spec.md`, `spec_lock.md`, the Quick active-context decision, or SVG comments declare a size scale such as `radius = sqrt(value) * k` or explicit min/max radius mapping.
-3. If the size scale is missing, record `radius=manual (scale missing)` and inspect relative ordering by hand.
+2. For `matrix_2x2`, verify that the axis midpoint matches the quadrant split. If the visible axes say only Low/High, read the explicit numeric mapping from the active §IX decision or SVG comment; without one, record `xy=manual (scale missing)` instead of inventing a range.
+3. Verify radius only if `design_spec.md`, the Quick active-context decision, or SVG comments declare a size scale such as `radius = sqrt(value) * k` or explicit min/max radius mapping. `spec_lock.md` carries only the primary family/key reference and is not a size-scale authority.
+4. If the size scale is missing, record `radius=manual (scale missing)` and inspect relative ordering by hand.
+
+**Bar-of-pie / pie-of-pie** — decompose the primary and expanded views:
+
+1. Replace the expanded tail in the primary data with one aggregate tail value, then run `calc pie` for the main pie.
+2. For `pie_of_pie_chart`, run `calc pie` again on the tail values at the secondary center/radius. For `bar_of_pie_chart`, verify each stacked detail height as `tail_value / sum(tail_values) × detail_height` and confirm the segments fill the declared detail bar without gaps or overlap.
+3. Verify that the aggregate tail slice equals the sum of the expanded values and that connector endpoints touch the two declared plot regions.
+
+**Stock chart** — decompose each OHLC observation into four y-values:
+
+1. Read the shared price-axis range and ordered date positions.
+2. Run `calc line` for open, high, low, and close using the same plot area and ranges. For each date, the wick spans `high_y` to `low_y`; the body spans `min(open_y, close_y)` to `max(open_y, close_y)`.
+3. Verify the body color/direction against `close >= open`, and verify that every body stays within its wick.
-**Progress bar / gauge / funnel — formula-verify** (no calc call needed):
+**Progress bar / gauge / funnel / sunburst — formula-verify** (no calc call needed):
- Progress bar: `fill_width = value / max × track_width`. Read `value`, `max`, and `track_width` from the SVG; compute and compare against the fill rect's `width`.
- Gauge: `needle_angle = start_angle + value / max × sweep_angle`. Read `start_angle` and `sweep_angle` from the SVG's arc path (e.g. half-circle `start_angle=-180`, `sweep_angle=180`). Compare against the needle's `transform="rotate(α ...)"` value (the most common form), or against endpoint `(cx + L·cos α, cy + L·sin α)` when the needle is drawn as an explicit line/path.
- Funnel: each trapezoid's `top_width = prev.bottom_width`, `bottom_width = top_width × next_value / curr_value`. Verify by walking the segments: for segment `i`, `(top_left_x, top_right_x) → bottom_x_inset = (top_width - bottom_width) / 2`. The first segment's top width comes from the design's outer frame.
+- Sunburst: for each ring, `circumference = 2πr` and each node's arc length is `node_value / root_total × circumference`; offsets follow cumulative sibling values plus any explicitly declared separator gap. Verify that child arcs remain inside their parent span and that sibling values sum to the parent.
- Receipt should quote the formula and resulting value (e.g. `formula=value/max×track_width=0.92×700=644px`, or `formula=600×850/1000=510 bottom width`).
-**Sankey / heatmap / treemap — manual verification:**
+**Sankey / heatmap / treemap / word cloud — manual verification:**
- Sankey: no layout model for node stacking, link routing, or flow-width normalization. Verify that link widths are proportional to flow values and that node-side totals match (in = out).
- Heatmap: cell positions are a fixed grid (not value-driven); the value-to-color binning is what's data-driven. Verify that the color of each cell falls in the bin matching the cell's number, and that high/low extremes use the legend's high/low colors.
- Treemap: rectangle areas reflect value proportions but the recursive squarify layout has no calculator equivalent. Verify each rect's `width × height ≈ total_area × value / sum(values)` for top-level cells, and that nested cells sum to their parent.
+- Word cloud: verify that keyword font sizes are monotonic with their declared weights (or match the declared weight bins), then inspect the final text bounds for overlap and clipping. Position is layout-driven; do not invent a coordinate formula.
---
-## Step 3: Per-page receipt
+## Step 3: Per-object receipt
-Output one line per page from the Step 1 list. Receipt count MUST equal Step 1
+Output one line per chart object from the Step 1 list. Include its semantic key;
+receipt count MUST equal Step 1
list length — that is the gate-closing evidence. Quick does not persist these
lines as a generation plan or resume record.
```
-verify-charts: 03_market_share.svg | type=bar | mode=direct-calc | scale=0-100 (from ticks) | calc=ran | svg=updated
-verify-charts: 07_growth.svg | type=line | mode=direct-calc | scale=0-120 (from ticks) | calc=ran | svg=unchanged (already accurate)
-verify-charts: 11_share_split.svg | type=pie | mode=direct-calc | scale=N/A | calc=ran | svg=updated | marker=added (was missing)
-verify-charts: 14_revenue_mix.svg | type=stacked-bar | mode=decomposable-calc | scale=0-200 (from ticks) | calc=ran×3 | svg=updated (per stacked recipe)
-verify-charts: 15_unit_economics.svg | type=stacked-area | mode=manual-verify | scale=N/A | reason=percent-stacked, recipe does not apply
-verify-charts: 16_before_after.svg | type=dumbbell | mode=decomposable-calc | scale=0-100 (from ticks) | calc=ran×2 | svg=unchanged
-verify-charts: 17_drivers_pareto.svg | type=pareto | mode=decomposable-calc | scale=left 0-80 / right 0-100 | calc=ran×2 | svg=updated
-verify-charts: 18_market_bubbles.svg | type=bubble | mode=partial-calc | xy=ran | radius=manual (scale missing) | svg=unchanged
-verify-charts: 20_quota_attainment.svg | type=bullet | mode=decomposable-calc | scale=0-120 (from ticks) | calc=ran×3 (bands+actual+target) | svg=updated
-verify-charts: 21_inflow_outflow.svg | type=butterfly | mode=decomposable-calc | scale=0-500 (from ticks) | calc=ran×2 + mirror | svg=unchanged
-verify-charts: 22_profit_bridge.svg | type=waterfall | mode=decomposable-calc | scale=0-500 (from ticks) | calc=ran×2 (top/bot) | svg=updated
-verify-charts: 23_quarterly_progress.svg | type=progress | mode=formula-verify | formula=68/100×800=544px | svg=unchanged
-verify-charts: 24_capacity_gauge.svg | type=gauge | mode=formula-verify | formula=-180+72/100×180=-50.4° | svg=updated
-verify-charts: 25_conversion_funnel.svg | type=funnel | mode=formula-verify | formula=600×850/1000=510 (seg2 bottom width) | svg=unchanged
-verify-charts: 26_regional_compare.svg | type=grouped-bar | mode=decomposable-calc | scale=0-500 (from ticks) | calc=ran×3 | svg=updated
-verify-charts: 27_release_plan.svg | type=gantt | mode=decomposable-calc | scale=Week1-Week24 (24 ticks, 40px/unit) | calc=ran×2 (start/end) | svg=unchanged
-verify-charts: 28_score_distribution.svg | type=boxplot | mode=decomposable-calc | scale=0-100 (from ticks) | calc=ran×4 (Q1/Q3/whiskers) | svg=updated
-verify-charts: 19_flow.svg | type=sankey | mode=manual-verify | link widths consistent with values | svg=unchanged
+verify-charts: 03_market_share.svg | object=market-share | type=bar | mode=direct-calc | scale=0-100 (from ticks) | calc=ran | svg=updated
+verify-charts: 03_market_share.svg | object=margin-trend | type=line | mode=direct-calc | scale=0-120 (from ticks) | calc=ran | svg=unchanged
+verify-charts: 11_share_split.svg | object=share-split | type=pie | mode=direct-calc | scale=N/A | calc=ran | svg=updated | marker=added
+verify-charts: 14_revenue_mix.svg | object=revenue-mix | type=stacked-bar | mode=decomposable-calc | scale=0-200 (from ticks) | calc=ran×3 | svg=updated
+verify-charts: 18_market_bubbles.svg | object=market-bubbles | type=bubble | mode=partial-calc | xy=ran | radius=manual (scale missing) | svg=unchanged
+verify-charts: 23_quarterly_progress.svg | object=quarterly-progress | type=progress | mode=formula-verify | formula=68/100×800=544px | svg=unchanged
+verify-charts: 19_flow.svg | object=flow | type=sankey | mode=manual-verify | link widths consistent with values | svg=unchanged
```
---