@liustack/pptwise 0.22.0 → 0.24.0

package/skills/pptwise/references/density.md

@@ -1,17 +1,31 @@
-# Density and beat
+# Density and decoration
 
-Read this when pacing budgets, `beat`, capacity, or slide `decor` are in play.
+Read this when writing to pacing budgets, fitting the bound face, or deciding whether a page needs local decoration.
 
-### Capacity
+## Two capacity limits
 
-A slide is a fixed-size canvas. Draft to fit on the first pass: few components per slide, short assertive headings, bullet items within about two lines. Component and bullets budgets scale with the deck's `pacing` axis (tightest for `spacious`, loosest for `dense`) — `validate` reports the exact numbers that applied, not a flat constant. These are warnings, not hard errors — worth fixing for a tighter deck, but they never block `render`. Body text size scales the other way: `spacious` renders the largest body font (32px vs. `balanced`'s 24px and `dense`'s 20px) even though it allows the fewest components, so a `spacious` slide needs fewer and shorter items, not just tighter ones. A bullet item that is long regardless of pacing — long enough to still overflow after shrinking to the render floor — *is* a hard `validate` error, for every bullet style (`default`/`plain`/`divided`/`numbered`/`checklist` alike — it would otherwise lose real text to an ellipsis). Treat "keep bullet items short" as a real constraint regardless of style. When in doubt, split into two slides — writing to fit beats fix-up loops.
+Every content page has two independent limits. Narrative pacing sets an editorial budget. The face selected by the bound theme menu sets a physical body capacity. The effective component limit is the smaller value.
 
-Eight component types own the whole slide instead of sharing it: `swot`, `bmc`, `waterfall`, `gantt`, `pest`, `five_forces`, `heatmap`, `sankey`. Each must be its slide's only component — `validate` hard-errors on a slide that mixes one in with `bullets` or anything else, it never silently drops the sibling.
+| pacing | body baseline | components | bullet items | width units per bullet |
+| --- | ---: | ---: | ---: | ---: |
+| `dense` | 24px | 5 | 6 | 27 |
+| `balanced` | 24px | 4 | 5 | 25 |
+| `spacious` | 32px | 3 | 4 | 22 |
 
-### Beat
+`validate` reports the effective limit for the actual theme and kind. Editorial excess is normally a warning. Render-safety limits and content loss remain hard errors. Shorten or split a page instead of hiding overflow.
 
-A content page's optional `beat` (`anchor`, `dense`, or `breathing`) is more than a `spec validate` rhythm check now — it also nudges which layout `render` auto-picks for that page: `anchor` leans toward a single bold-statement layout, `dense` leans toward a high-density layout with more visible items, `breathing` leans toward the most spacious single-column layout. It is a soft weight, not a pin — an explicit `layout` still overrides it entirely, and an unset `beat` has zero effect. Declare it deliberately, one value per page based on that page's actual role in the argument (the "big reveal" page is `anchor`, a data-heavy comparison page is `dense`, a breather page between two dense sections is `breathing`), not as a rubber stamp on every page — `spec validate`'s own beat-rotation gate already flags a streak of identical declared beats for strategies that expect variation, and stamping the same value everywhere also just cancels out the layout variety this field exists to add.
+`spacious` means fewer elements at a larger body size. It does not mean the same content compressed into a cleaner-looking page. Keep headings assertive and keep bullet items near two lines.
 
-### Decor
+Three consecutive content pages with the same kind produce a spec advisory. Repetition can be correct, but confirm that the story truly calls for the same semantic move three times.
 
-Set slide `decor` only when the user explicitly asks for decorative flourish. Default is none — themes already carry their own motifs.
+Eight components own the whole body: `swot`, `bmc`, `waterfall`, `gantt`, `pest`, `five_forces`, `heatmap`, and `sankey`. Each must be the page's only component.
+
+## Decoration ownership
+
+Decoration resolves in this order:
+
+1. A face with structural `suppressMotif: true` never receives a theme motif.
+2. Otherwise a menu entry may choose `decor.kind: "silent"` or select another motif.
+3. With no menu opinion, the theme's ordinary motif paints.
+
+The face's structural silence cannot be undone by a menu. A page-level `decor` is a controlled local primitive such as a rule, tag, quote mark, dots, or large number. Use it only when the page meaning needs that accent. It does not replace the theme menu and should not be stamped across the deck.

package/skills/pptwise/references/density.zh-CN.md

@@ -3,20 +3,34 @@ summary: 'skills/pptwise/references/density.md 的中文阅读镜像'
 mirror_of: skills/pptwise/references/density.md
 ---
 
-# 密度与 beat
+# 密度与装饰
 
-何时读：处理 pacing 预算、`beat`、容量、或 slide `decor` 时。
+何时读：按 pacing 预算写作，适配已绑定的脸，或判断页面是否需要局部装饰时。
 
-### 容量
+## 两种容量限制
 
-一张 slide 是一块固定尺寸的画布。第一遍起草就要考虑装得下：每张 slide 少放几个 component，标题简短有力，bullet 条目控制在约两行以内。component 数和 bullets 预算随这份 deck 的 `pacing` 轴变化（`spacious` 最紧，`dense` 最松）——`validate` 会报出实际生效的具体数值，不是一个写死的常数。这些是警告，不是硬错误——值得为了让 deck 更紧凑而修，但从不拦住 `render`。正文字号则反过来变化：`spacious` 渲染出的正文字号最大（32px，相对 `balanced` 的 24px 和 `dense` 的 20px），即便它允许的 component 数最少——所以一张 `spacious` 的 slide 需要更少、更短的条目，而不只是更紧凑。不论 pacing 是什么，一条长到在渲染安全字号地板下仍然溢出的 bullet 条目，*就是*一条硬 `validate` 错误，五种 bullet 样式（`default`/`plain`/`divided`/`numbered`/`checklist`）一视同仁——否则它会被省略号真的截掉一段真实文字。把「bullet 条目要短」当成一条不分样式都成立的硬约束。拿不准的时候就拆成两张 slide——一遍写对，好过事后反复修补。
+每张内容页同时受两种独立限制。叙事 pacing 给出编辑预算，主题菜单选中的脸给出正文物理容量。实际组件上限取两者中的较小值。
 
-有八种 component 类型独占整张 slide，而不是与其他组件共享：`swot`、`bmc`、`waterfall`、`gantt`、`pest`、`five_forces`、`heatmap`、`sankey`。各自必须是所在 slide 唯一的 component——`validate` 会在一张 slide 把其中之一和 `bullets` 或其他任何组件混在一起时硬报错，绝不会静默丢弃那个「陪衬」的 component。
+| pacing | 正文基线 | components | bullet 条目 | 每条宽度单位 |
+| --- | ---: | ---: | ---: | ---: |
+| `dense` | 24px | 5 | 6 | 27 |
+| `balanced` | 24px | 4 | 5 | 25 |
+| `spacious` | 32px | 3 | 4 | 22 |
 
-### Beat（节奏标记）
+`validate` 会按实际主题与 kind 报出有效上限。超出编辑预算通常是警告，越过渲染安全线或造成内容丢失仍然是硬错误。应该缩短或拆页，不要隐藏溢出。
 
-一张 content 页面上可选的 `beat`（`anchor`、`dense` 或 `breathing`）现在不只是 `spec validate` 的节奏检查——它还会影响 `render` 给这一页自动选出哪个 layout：`anchor` 偏向单一的强断言式 layout，`dense` 偏向可见条目更多的高密度 layout，`breathing` 偏向最舒展的单栏 layout。它是一个软权重，不是钉死的选择——显式的 `layout` 依然会完全覆盖它，未设置的 `beat` 则毫无影响。要有意识地声明它，按每一页在论证里的实际角色各给一个值（「重磅揭示」的那页是 `anchor`，数据密集的对比页是 `dense`，两个高密度段落之间的换气页是 `breathing`），而不是每一页都盖同一个章——`spec validate` 自己的 beat 轮换门已经会对期望有变化的 strategy 标出一连串相同 beat 的问题，而且到处盖同一个值本来就会抵消这个字段存在的目的：给 layout 增加变化。
+`spacious` 表示元素更少且正文字号更大，不是把同样多的内容压缩进一张看似更干净的页面。标题要短而有判断，bullet 条目尽量控制在两行附近。
 
-### Decor（装饰）
+连续三张内容页使用相同 kind 时，spec 会给出提示。重复可能正确，但应确认故事确实需要连续三次相同的语义动作。
 
-只有当用户明确要求装饰性点缀时，才设置 slide 的 `decor`。默认不设——theme 本身已经带着自己的视觉母题。
+八种组件独占整个正文区：`swot`、`bmc`、`waterfall`、`gantt`、`pest`、`five_forces`、`heatmap` 与 `sankey`。每种都必须是该页唯一的组件。
+
+## 装饰归属
+
+装饰按以下顺序解析：
+
+1. 一张脸若把 `suppressMotif: true` 声明为结构事实，就永远不接收主题 motif。
+2. 其他脸可以由菜单条目选择 `decor.kind: "silent"`，或换用另一个 motif。
+3. 菜单没有表达意见时，绘制主题的普通 motif。
+
+菜单不能推翻脸的结构静默。页面级 `decor` 是受控的局部原语，例如线、标签、引号、圆点或大数字。只有页面含义确实需要这一个强调时才使用。它不能替代主题菜单，也不应整份 deck 到处盖章。

package/skills/pptwise/references/images.md

@@ -1,35 +1,50 @@
 # Images
 
-Read this when declaring image assets, searching stock, or generating art.
+Read this when declaring image assets, choosing `photo` or `evidence`, searching stock, or generating art.
 
-### Image slides
+## Choose the semantic move first
 
-Declare images once in `assets.images` and reference them by `asset_id` — double-check every `asset_id` spelling, a wrong key renders a silent placeholder instead of failing. An explicit `layout` id always wins over pptwise's auto-selection, which otherwise picks from the theme's layout set for that page type (the full registry set by default, unless the theme curates it narrower) — for a slide built around an image, set `layout` to one of the image takeovers: `image-split` (half-page image + side text, `image_side: left|right`), `image-top` (full-bleed top image + text columns below), `image-bottom` (text above, image below), `image-annotate` (center image + radiating callouts taken from the first 4 bullets). **Every image layout needs an `image` component somewhere in `components`** — pptwise uses the first one it finds as the image source regardless of array position, and every other component becomes the layout's text body.
+Use `kind: "photo"` when the image itself is the subject. Use `kind: "evidence"` when one exhibit supports one assertion. The bound theme menu chooses the face for that kind. Authors do not name image geometry.
 
-Before generating art for any `image` component whose `asset_id` still has no real file behind it, run `pptwise asset-brief <target>` — it renders the deck for real and reports each slot's actual frame (not the layout's nominal slot size), crop mode with a safe-zone note, suggested generation pixels, the theme's palette, and a paste-ready prompt. Matching the reported aspect ratio and palette is what makes a generated image look intentional once it's placed instead of stretched, cropped wrong, or off-tone.
+Cover and chapter pages can use an asset background. The renderer applies the dedicated image-cover treatment with a dark readability scrim. Content and ending asset backgrounds retain the theme-toned scrim. Use a background image only when the page truly needs a full-canvas scene.
 
-### Stock photos
+Declare each image once in `assets.images`, then reference it by `asset_id` from `image`, `image_grid`, `image_compare`, or `device_mockup`. Check every key. `validate` reports a dangling reference, and an unresolved source cannot become a real image.
 
-Run `pptwise asset-brief <target>` first so the frame, crop, and palette are known.
+`image_side: "left"` or `"right"` is an optional preference for a face that supports a side image. Other faces ignore no authoring geometry because none is supplied.
 
-Query rules: short concrete nouns, English 2–4 words (`office desk`, `wind farm`). Chinese is a variant, not the only query. No mood or quality words (`beautiful`, `4k`, `cinematic`). No negative keywords (`not office`, `no people`).
+## Brief before sourcing
 
-Search order is Pexels, then Pixabay if a key is set, then Openverse (cc0/pdm, commercial filter).
+Run the real renderer before sourcing any missing asset:
+
+```bash
+pptwise asset-brief <target>
+```
+
+The brief reports the actual frame, crop mode, safe zone, suggested pixel size, theme palette, and a paste-ready prompt. Match the reported aspect ratio and palette.
+
+## Stock photos
+
+Use a short concrete English query of two to four words, such as `office desk` or `wind farm`. Keep mood, quality claims, and negative keywords out of the query. Search Pexels first, Pixabay when configured, then the commercially filtered Openverse sources.
 
 ```bash
 pptwise config set pexels.apiKey
 pptwise images search "office desk" --orientation landscape
 ```
 
-Do not auto-pick the first result. A person or a vision model picks from the ~8 thumbs. Then download:
+Do not take the first result automatically. Have a person or vision model choose from the thumbnails, then fetch the selected asset.
 
 ```bash
 pptwise images fetch pexels:123 --deck <dir> --as hero
 pptwise images list --deck <dir>
+```
+
+## Generated images
+
+```bash
 pptwise images generate --deck <dir> --as <asset_id>
 ```
 
-Local generators stay off until enabled:
+Local generators remain disabled until the user enables one:
 
 ```bash
 pptwise config set images.generators.grok.enabled true
@@ -37,6 +52,4 @@ pptwise config set images.generators.codex.enabled true
 pptwise config set images.generators.antigravity.enabled true
 ```
 
-The file lands in `.pptwise/<deck>/assets/<asset_id>.jpg` with a sidecar next to it. Reference that `asset_id` from the page. Do not delete `.pptwise/` wholesale to "rerun". That drops pinned photos.
-
-No key: leave the slot `missing` (grey frame). Do not invent a photo. Do not scrape. Do not use Unsplash. This is a local client fetching with the user's own key. Commercial use in a presentation is allowed. Do not resell the photo standalone. Print attribution in the terminal, not on the slide by default.
+Fetched and generated files live under `.pptwise/<deck>/assets/` with sidecars. Do not delete that directory to rerun a step because it contains selected assets. Without an available source, leave the asset missing and report it. Do not invent a photo or scrape an unsupported provider. Print required attribution in the terminal unless the license or user asks for on-slide credit.

package/skills/pptwise/references/images.zh-CN.md

@@ -5,36 +5,51 @@ mirror_of: skills/pptwise/references/images.md
 
 # 配图
 
-何时读：声明资产、搜图库、或生图时。
+何时读：声明图片资产，选择 `photo` 或 `evidence`，搜索图库，或生成图片时。
 
-### 图片页
+## 先选择语义动作
 
-在 `assets.images` 里统一声明图片，用 `asset_id` 引用——务必逐个核对 `asset_id` 拼写，写错 key 只会渲染出一个静默的占位符，不会报错。显式的 `layout` id 永远优先于 pptwise 的自动选型，否则自动选型会从该页型对应的 theme layout 集合里挑（默认是全部已注册版式，除非 theme 主动收窄）——对于以图片为核心的 slide，把 `layout` 设成某个 image takeover：`image-split`（半页图片 + 侧边文字，`image_side: left|right`）、`image-top`（顶部通版图片 + 下方文字分栏）、`image-bottom`（上方文字，下方图片）、`image-annotate`（居中图片 + 从前 4 条 bullets 取出的放射状标注）。**每个 image layout 都需要 `components` 里至少有一个 `image` component**——不论它在数组里的位置，pptwise 都会用找到的第一个作为图片来源，其余的 component 全部成为该 layout 的文字正文。
+图像本身就是主角时用 `kind: "photo"`。一件展品支持一个断言时用 `kind: "evidence"`。已绑定主题的菜单为这个 kind 选择脸。作者不点名图片几何。
 
-给任何 `asset_id` 还没有真实文件的 `image` component 生成美术之前，先跑一遍 `pptwise asset-brief <target>`——它会真的渲染一遍 deck，报告每个图片位实际的渲染框（不是版式的名义槽位尺寸）、带安全区说明的裁切模式、建议的生成像素、主题色板，以及一段可直接粘贴的提示词。宽高比和色调对上了，生成的图片摆上去才会显得是设计好的，而不是被拉伸、裁错或跑色。
+封面与章节页可以使用资产背景。渲染器会采用专门的压图处理，并加深色可读性遮罩。内容页与结尾页的资产背景保留主题色调遮罩。只有页面确实需要全画布场景时才使用背景图。
 
-### 图库配图
+每张图片只在 `assets.images` 中声明一次，再由 `image`、`image_grid`、`image_compare` 或 `device_mockup` 通过 `asset_id` 引用。逐个检查 key。`validate` 会报告悬空引用，没有解析到来源的资产不能变成真实图片。
 
-先跑 `pptwise asset-brief <target>`，拿到真实框、裁切和色板。
+`image_side: "left"` 或 `"right"` 是给支持侧图的脸使用的可选偏好。其他脸不需要处理作者几何，因为作者没有提供这类信息。
 
-查询词：短而具体的名词，英文 2 到 4 个词（`office desk`、`wind farm`）。中文只作变体，不要当唯一查询。不要加情绪或画质词（`beautiful`、`4k`、`cinematic`）。不要写负向词（`not office`、`no people`）。
+## 先取简报再找图
 
-搜索顺序是 Pexels，有 key 再 Pixabay，然后 Openverse（cc0/pdm，commercial 过滤）。
+为任何缺失资产找图之前，先运行真实渲染器：
+
+```bash
+pptwise asset-brief <target>
+```
+
+简报会给出实际画框、裁切方式、安全区、建议像素尺寸、主题配色和可直接使用的提示词。素材应匹配它报告的宽高比与色调。
+
+## 图库照片
+
+使用两到四个词的具体英文查询，例如 `office desk` 或 `wind farm`。查询中不要写情绪词、质量描述或否定关键词。搜索顺序是 Pexels，已配置时再查 Pixabay，最后查经过商业用途过滤的 Openverse 来源。
 
 ```bash
 pptwise config set pexels.apiKey
 pptwise images search "office desk" --orientation landscape
 ```
 
-不要自动收第一条。人（或视觉模型）从大约 8 张缩略图里挑。然后下载：
+不要自动选择第一张结果。由人或视觉模型从缩略图中选择，再拉取目标资产。
 
 ```bash
 pptwise images fetch pexels:123 --deck <dir> --as hero
 pptwise images list --deck <dir>
+```
+
+## 生成图片
+
+```bash
 pptwise images generate --deck <dir> --as <asset_id>
 ```
 
-本地生图默认关闭，要显式打开：
+本地生成器默认关闭，只有用户启用后才使用：
 
 ```bash
 pptwise config set images.generators.grok.enabled true
@@ -42,6 +57,4 @@ pptwise config set images.generators.codex.enabled true
 pptwise config set images.generators.antigravity.enabled true
 ```
 
-文件落在 `.pptwise/<deck>/assets/<asset_id>.jpg`，旁边是 sidecar。页面用这个 `asset_id` 引用。不要为了「重跑」整目录删掉 `.pptwise/`，已钉的图会一起没。
-
-没有 key：槽位保持 `missing`（灰框）。不要编一张图。不要刮网页。不要用 Unsplash。这是本机客户端，用用户自己的 key 去拉。幻灯里商用可以。不要把原图单独转卖。署名打在终端，默认不印在画面上。
+拉取与生成的文件存放在 `.pptwise/<deck>/assets/`，旁边带 sidecar。不要为了重跑某一步而删除整个目录，因为其中保存了已经选定的资产。没有可用来源时，保留缺失状态并如实汇报。不要虚构照片，也不要抓取未支持的提供方。除非许可或用户要求在页面署名，归属信息默认打印在终端。

package/skills/pptwise/references/layouts.md

@@ -1,37 +1,41 @@
-# Layouts and pins
+# Kinds and theme menus
 
-Read this when pinning a `layout`, including climax, quote, and evidence sparse pages.
+Read this when deciding what a content page is saying and which `kind` names that move.
 
-### Pin-only layouts
+## The authoring rule
 
-These layouts never appear through auto-selection. Set `layout` explicitly every time you want one. `validate` hard-errors if a pin-only content layout carries more components than its declared capacity (an ordinary layout pinned over capacity only warns).
+Boundary pages use only `cover`, `chapter`, or `ending`. Every content page carries exactly one of the eleven `kind` values below. Authors choose the semantic move. The bound theme menu chooses the visual face.
 
-`quote-stage` is a thesis page on a content slide: one short, powerful heading is the entire visual, with at most one short attribution component (a source, a name, a one-line follow-up). Zero components is legitimate — a pure quote needs no attribution. This one still draws the theme's brand footer and motif.
+Do not encode geometry in the spec or page file. If the requested kind is absent from the theme menu, validation stops with a hard error and lists the kinds that theme offers. Resolve the mismatch by choosing an offered kind that still tells the truth, binding a theme that offers the intended kind, or creating a complete theme whose menu does.
 
-`statement` is a whole-page verse or epigram on a content slide. At most one component, rendered as a small source line (quote / paragraph / citation), never as a card. Optional kicker from the preceding chapter. Brand footer and logo stay off. The theme motif still paints. The face is theme-specific (a boarded theme is not the generic italic 500 lines).
+## Close calls
 
-`pull-quote` is a quotation page on a content slide: heading, source line, optional muted paragraph. Source comes from a quote component's `attribution` when present, otherwise `subheading`. Brand footer and logo stay off. The theme motif still paints.
+- `points` is an argument whose order matters. `list` is a set of peers that can be reordered.
+- `data` is a numeric set with a shape to read. `fact` is one number carrying the page.
+- `photo` makes the image the subject. `evidence` makes an exhibit support one assertion.
+- `statement` is the deck author's proposition. `quote` attributes the words to someone else.
+- `process` expresses direction or time. `hierarchy` expresses containment or levels. `comparison` puts alternatives side by side.
 
-`verse-chapter` is a centered verse as a chapter open (`type: "chapter"`). Tracking chapter-index kicker, 2-line heading, optional italic subheading. No watermark numeral, no body, no footnote — the usual chapter boundary still applies. Logo stays off. The theme motif still paints.
+## Menu consequences
 
-`stat-hero` is a whole-page number on a content slide. The hero value comes from the first `kpi_cards` item when present, otherwise the heading. One caption line, optional source. At most one component. Brand footer and logo stay off. The theme motif still paints.
+A theme menu binds each boundary page and each offered content kind to one face. The same choice also fixes that face's capacity, motif posture, and branding permissions. Write to that physical capacity after binding the theme. A different color fork with the same menu can be rebound without rewriting the story. A theme with a different menu requires a return to the theme step, followed by spec and page-fill revision.
 
-`one-evidence` is an assertion-plus-evidence page on a content slide. Heading is a full-sentence claim. At most one component, rendered as the evidence (a chart, table, or image). Brand footer and logo stay off. The theme motif still paints.
+<!-- generated:begin kinds -->
+### Complete kind vocabulary
 
-`mono-bleed` is a full-bleed brand-color field on a content slide, type as the picture. Capacity 0: write the words in the heading, no body component. Brand footer and logo stay off. The theme motif still paints.
+This section is generated from the IR v5 kind vocabulary and the 24 preset menus. The final column shows how many preset menus offer each kind.
 
-### Sparse-page contract
-
-A deck is for speaking. Extra words that will not fit on the slide go in `slide.notes`. If the file must stand alone as a document, recommend a PDF rather than packing the canvas.
-
-This is not a new `pacing` value. The enum stays `dense` / `balanced` / `spacious`. The contract is pin-only layouts, `notes`, and deck `branding`.
-
-Climax, quote, and evidence pages pin a sparse pin-only layout when the theme offers it. Name it: `statement`, `pull-quote`, `verse-chapter`, `stat-hero`, `one-evidence`, `mono-bleed`. Do not leave those pages to auto-selection. A page that truly is one sentence still gets this pin even when pacing is `dense`. crayon, classroom, enterprise, pulse, runway, and ember do not offer these layouts. If `validate` warns that the pin is not a sparse page this theme offers, drop the pin and write a regular content page.
-
-When the interview or request chose `spacious`: tighten the on-slide budget. Heading is the visual. At most one body component on a pinned sparse page (a source line, a single number, a single chart or table). Zero bullets on those pages. Split instead of stacking.
-
-When `balanced` or `dense`: write to the pacing budget. Still pin a sparse layout when a page is one sentence, one number, one quote, or one piece of evidence.
-
-The spoken script goes in `slide.notes`. `render` exports it as native PowerPoint speaker notes (View → Notes, Presenter View). Never draw the script onto the canvas.
-
-Branding omit/full lives in `references/branding.md`.
+| kind | name | use it when | boundary | preset menus |
+| --- | --- | --- | --- | ---: |
+| `points` | Points | Advance an ordered argument whose sequence matters. | Use list when the items are peers that can be reordered. | 24/24 |
+| `list` | List | Present peer items whose order may change. | Use points when the sequence carries the reasoning. | 24/24 |
+| `comparison` | Comparison | Place alternatives, sides, or dimensions in direct contrast. | Containment belongs to hierarchy and direction belongs to process. | 24/24 |
+| `process` | Process | Show directed steps, a timeline, or a closed cycle. | An ordered argument without motion is points. | 24/24 |
+| `data` | Data | Make a set of numbers, a chart, or a table the subject. | Use fact when one number is the whole message. | 23/24 |
+| `photo` | Photo | Make the image itself the content. | Use evidence when an exhibit exists to support a claim. | 21/24 |
+| `statement` | Statement | Give the deck author's own proposition a full page. | Words attributed to someone else are quote. | 20/24 |
+| `quote` | Quote | Center words attributed to another speaker or source. | The deck author's own proposition is statement. | 8/24 |
+| `fact` | Fact | Build the page around one number. | A numeric set whose structure matters is data. | 18/24 |
+| `evidence` | Evidence | Pair one assertion with one exhibit that supports it. | Use photo when the image stands on its own. | 10/24 |
+| `hierarchy` | Hierarchy | Express containment, levels, or composition. | Sequence belongs to process and side-by-side contrast to comparison. | 22/24 |
+<!-- generated:end kinds -->

package/skills/pptwise/references/layouts.zh-CN.md

@@ -3,40 +3,44 @@ summary: 'skills/pptwise/references/layouts.md 的中文阅读镜像'
 mirror_of: skills/pptwise/references/layouts.md
 ---
 
-# 版式与写死
+# 讲法与主题菜单
 
-何时读：钉 `layout`，包括高潮页、金句页、证据页稀排版式时。
+何时读：判断内容页在说什么，以及该用哪个 `kind` 命名这种表达动作时。
 
-### Pin-only 版式
+## 作者规则
 
-这些版式从不出现在自动选型里。每次要用都得显式设置 `layout`。pin-only 的 content 版式超出声明容量时 `validate` 会硬报错（普通版式钉住超容量只给警告）。
+边界页只使用 `cover`、`chapter` 或 `ending`。每张内容页必须且只能带一个下列十一词中的 `kind`。作者选择语义动作，已绑定主题的菜单负责选择视觉脸。
 
-`quote-stage` 是 content 页上的论断页：一句短而有力的标题是整页主视觉，最多再配一个短附注 component（出处、署名、一句补充）。0 个 component 合法。这一页仍会画主题的品牌页脚和 motif。
+不要在 spec 或页面文件中编码几何。请求的 kind 不在主题菜单里时，验证会硬报错，并列出该主题提供的讲法。解决方式只有三种：改用仍然忠于内容的已提供讲法，绑定一个提供目标讲法的主题，或创建一个菜单包含目标讲法的完整主题。
 
-`statement` 是 content 页上的整页诗行或金句。最多一个 component，渲成出处小字（quote / paragraph / citation），不走卡片。可选 kicker 来自上一章。品牌页脚和 logo 不画。主题 motif 仍画。脸是主题专属的（已定稿的主题不是通用斜体 500 行）。
+## 容易混淆的边界
 
-`pull-quote` 是 content 页上的引言页：标题、出处小字、可选 muted 散文。出处优先 quote 的 `attribution`，否则 `subheading`。品牌页脚和 logo 不画。主题 motif 仍画。
+- `points` 是顺序不可调换的论证。`list` 是可以换序的并列条目。
+- `data` 是要读出结构的一组数字。`fact` 是由一个数字承担整页信息。
+- `photo` 让图像本身成为主角。`evidence` 让一件展品支持一个断言。
+- `statement` 是作者自己的立论。`quote` 把话归给别人。
+- `process` 表达方向或时间。`hierarchy` 表达包含或层级。`comparison` 把多个对象并排对照。
 
-`verse-chapter` 是居中诗行章首（`type: "chapter"`）。tracking 章号眉、两行标题、可选斜体副题。没有水印大数字，没有 body，没有 footnote，chapter 页的既有边界照旧。logo 不画。主题 motif 仍画。
+## 菜单带来的约束
 
-`stat-hero` 是 content 页上的整页数字。英雄位数字优先取自 `kpi_cards` 第一项，否则就是 heading。一行说明，可选出处。最多一个 component。品牌页脚和 logo 不画。主题 motif 仍画。
+主题菜单为每种边界页和每个已提供的内容讲法各绑定一张脸。这次绑定也同时确定了脸的容量、装饰姿态和品牌权限。先绑定主题，再按真实物理容量写作。菜单相同的换色分叉可以直接换绑。菜单不同的主题需要回到主题步骤，再修订 spec 与页面填充。
 
-`one-evidence` 是 content 页上的断言加一条证据。标题是一句完整主张。最多一个 component，渲成那条证据（一张 chart、一张表或一张图）。品牌页脚和 logo 不画。主题 motif 仍画。
+<!-- generated:begin kinds -->
+### 讲法全量表
 
-`mono-bleed` 是 content 页上的满版品牌色底，字当图。容量 0：字写在 heading 里，没有 body component。品牌页脚和 logo 不画。主题 motif 仍画。
+本段由 IR v5 的讲法词表与 24 个预设菜单生成。最后一列表示有多少预设菜单提供该讲法。
 
-### 稀排页合同
-
-一份 deck 是拿来讲的。幻灯片装不下的字写进 `slide.notes`。如果文件必须作为文档独立站住，建议用 PDF，不要把画布塞满。
-
-这不是新的 `pacing` 档。枚举仍是 `dense` / `balanced` / `spacious`。合同靠版式点名、`notes` 和 deck `branding` 实现。
-
-高潮页、金句页、证据页，在主题提供这些版式时显式钉 pinOnly 极简版式。点名：`statement`、`pull-quote`、`verse-chapter`、`stat-hero`、`one-evidence`、`mono-bleed`。不要把这些页交给自动选型。某一页真的只剩一句话时，即使 pacing 是 `dense` 也仍然钉。crayon、classroom、enterprise、pulse、runway、ember 不提供这些版式。如果 `validate` 警告这个钉子不是该主题提供的稀排页，就去掉钉子，改写普通内容页。
-
-访谈或请求选了 `spacious`：收紧页上预算。标题就是主视觉。钉住的极简页最多一个 body component（一行出处、一个数字、一张图或一张表）。这些页零 bullet。装不下就拆页。
-
-`balanced` 或 `dense`：按 pacing 预算写。某一页是一句话、一个数字、一句引语或一条证据时，仍然钉极简版式。
-
-讲稿写进 `slide.notes`。`render` 导出成原生 PowerPoint 演讲者备注（View → Notes，演讲者视图可见）。讲稿从不画到画布上。
-
-品牌框 omit/full 写在 `references/branding.md`。
+| kind | 中文 | 何时使用 | 边界 | 预设菜单 |
+| --- | --- | --- | --- | ---: |
+| `points` | 要点 | 按不可调换的顺序推进一组论点。 | 并列条目可换序时用 list。 | 24/24 |
+| `list` | 清单 | 并列陈列一组可以换序的条目。 | 顺序承载论证时用 points。 | 24/24 |
+| `comparison` | 对比 | 把两边、多个方案或多个维度直接对照。 | 包含关系用 hierarchy，有方向的变化用 process。 | 24/24 |
+| `process` | 流程 | 表达有方向的步骤、时间线或闭环。 | 只有论证递进而没有运动关系时用 points。 | 24/24 |
+| `data` | 数据 | 让一组数字、图表或表格成为页面主角。 | 只有一个数字承担全部信息时用 fact。 | 23/24 |
+| `photo` | 图像 | 让画面本身成为内容。 | 展品是为断言服务时用 evidence。 | 21/24 |
+| `statement` | 宣言 | 让作者自己的一句话立论占据整页。 | 借别人之口时用 quote。 | 20/24 |
+| `quote` | 引用 | 以他人或外部来源的话为中心。 | 作者自己的立论用 statement。 | 8/24 |
+| `fact` | 大数字 | 让一个数字承担整页冲击。 | 要看一组数字的结构时用 data。 | 18/24 |
+| `evidence` | 单证据 | 把一个断言与一件支持它的展品配对。 | 画面自己就是内容时用 photo。 | 10/24 |
+| `hierarchy` | 层级 | 表达包含、层级或组成关系。 | 先后关系用 process，并排对照用 comparison。 | 22/24 |
+<!-- generated:end kinds -->