@taloswork/ose-shared 0.1.11 → 0.1.13

package/skills/document/content-pipeline.md

@@ -1,16 +1,13 @@
 # Content pipeline — premium deck methodology (clarify → research → structure → outline → author → QA)
 
-Follow this for a **substantive, premium-looking deck** (路演/汇报/评审/宣讲/pitch/
-keynote/launch), not a quick 3-slide summary. It is the single source for HOW to
-source, structure, and flesh out deck content; the `layouts/` library × a `styles/`
-skin (deck-design.md) then RENDER it. You run these phases yourself with your own
-tools (web search, reasoning, AskUserQuestion) — there is no research script.
-
-**Design target = a premium presentation, not a document.** On-slide text is
-sparse and punchy; the *substance* lives in visuals, data, and speaker notes (Phase
-4 density). A wall of text is not "substantive" — it is lazy in the other direction.
-Rich VISUAL + sparse TEXT. **Compose from `layouts/` structure-only layouts, not from
-a blank slide** — authoring every slide from zero is the #1 "AI-generated" tell.
+Follow this for a **substantive deck** (路演/汇报/评审/宣讲/pitch/keynote/launch), not a
+quick 3-slide summary. It is the single source for HOW to source, structure and flesh
+out deck content; deck-design.md renders it. You run these phases yourself (web search,
+reasoning, AskUserQuestion) — there is no research script.
+
+**Design target = a premium presentation that explains itself**: a visual + data on every
+slide, and each point says why in one line (Phase 4). A wall of text is not "substantive";
+neither is a board of 2-word labels.
 
 ## Execution discipline (whole pipeline)
 
@@ -23,72 +20,64 @@ a blank slide** — authoring every slide from zero is the #1 "AI-generated" tel
    citation, a palette). Missing → halt and get it.
 4. **No silent skips**: if you skip a step (e.g. Research for "organize my material"),
    say so and why.
+5. **Batch independent reads, searches and checks in ONE turn of parallel calls.**
+   Update the task plan only when a phase changes.
 
-Two entry modes:
-- **Open-ended** ("做一份关于 X 的 PPT") → run every phase from Research.
-- **Organize existing material** (user gave a doc/notes) → SKIP Phase 1; in Phase 4
-  reorganize THEIR content into the slide structures, never invent facts.
+Two entry modes: **open-ended** ("做一份关于 X 的 PPT") → every phase from Research;
+**organize existing material** (user gave a doc/notes) → skip Phase 1 and in Phase 4
+reorganize THEIR content, never invent facts.
 
 ---
 
 ## Phase 0 — Clarify & Brief (MANDATORY gate)
 
-Before any research or generation, confirm requirements and persist a brief. Follow
-the canonical interaction contract in `SKILL.md`: ask only for missing values among
-content source, scenario, and slide count in **ONE AskUserQuestion call with at most
-THREE questions**. Do not re-ask values already supplied. The scenario-ranked style
-picker is a separate single-question image-card call after the scenario is known,
-unless the user already selected a catalog entry, supplied a style template, or
-explicitly authorized automatic selection.
-
-1. **Content source** — 提供材料 / 联网调研 / 自由创作. (Provided → request the materials now.
-   When you ask the user for a FILE — a template/materials .pptx/.docx/.pdf — set
-   `filePick: "file"` on that ask_user_question so they get a native "choose file"
-   button instead of typing a path; the picked path is the answer.)
-   **A material given as CONTENT is for its TEXT/DATA only — extract and re-author it
-   in the chosen skin; NEVER reuse its look.** In particular a **`.pptx` handed in as
-   content** → read its text (the `.txt` sidecar or `bin/doc-text`) and treat it like
-   any other source; do **NOT** `pptx-tokenize`/`pptx-theme` it (those reuse the deck's
-   STYLE — a separate style-picker decision, see below). Reusing an uploaded deck's look is ONLY triggered
-   when the user picks that as their **style** ("复用这份 PPT 的风格"), never merely
-   because the content happened to arrive as a `.pptx`.
-2. **Scenario** — the deck's use case (pitch / 内审 / 销售 / 讲座 / 发布会 / 培训 / 大会 /
-   工作汇报 / 述职 / 项目评审 / 年度总结 / 商业计划书 / 投标 / 政务汇报 / 公司产品介绍 …
-   — the full 15 with their logic live in the **Scenario matrix** below). AskUserQuestion
-   caps at 4 **TEXT** options, so **for THIS scenario question** present the **3–4 best-fit
-   for the topic** + let the user type Other (any scenario, listed or not). This text-option
-   cap does not apply to the separate image-card style picker; follow `SKILL.md` for its
-   current catalog-backed recommendation and browse-all contract. Then look the choice up in the matrix (unlisted →
-   map to the nearest row). Record as a short phrase. Scenario is NOT just wording — it
-   locks **five** things at once (tone · density · **required roles** · narrative shape ·
-   page range). Carry them through: required roles = a checklist Phase 2 MUST satisfy
-   (MECE), density feeds Phase 4 §4.2 P2, narrative picks the Phase 2 pyramid, pages seed the slide-count choice.
-3. **Slide count** — default = the chosen scenario's **默认页数** column in the Scenario
-   matrix (e.g. pitch 10–12 · 内审 6–8 · keynote 15–20 · 工作汇报 5–10 · BP 15–25 · 投标
-   15–30); clamp 3–30, double-check outside.
-
-**Separate style picker — pick ONE current catalog entry after scenario is known.**
-Read `catalog.json` immediately before asking and use the scenario-ranked picker
-contract in `SKILL.md`: show at most eight recommended final entries, then
-“查看全部风格” and the custom-template card. If the user expands, show every current
-`catalog.entries` item in catalog order. Never use a hard-coded skin count or stale
-id list. Samples are pre-rendered WebP assets — use `entry.sample` directly and do
-not render anything during the question. Rank by catalog metadata and the confirmed
-scenario; do not hardcode a default family. After confirmation, save the deck-skin
-preference to memory.
-
-**Custom style (其他/自定义)** — prefer **B (derive a bespoke look)**: from an existing
-deck → `pptx-tokenize` (reuse its layouts/master) or `pptx-theme` (its palette → our
-layouts); from a reference image → build a `styles/<name>/skin.css`. Fallbacks: map
-to the nearest catalog family or tweak one. A deck given here is used for its STYLE —
-distinct from a deck given as **content**, which is text-only. Full routing in `SKILL.md`.
-
-**Scenario matrix** (each row locks tone · density · required roles · narrative ·
-pages). The required roles are a HARD checklist — Phase 2 must include them all:
-
-| 场景 | 语气 | 密度 | 必备章节(required roles — all MUST appear) | 叙事(Phase 2) | 默认页数 |
+The clarify gate and the style picker are defined once, in SKILL.md: ask only for the
+missing values among content source, scenario and slide count, in ONE AskUserQuestion
+call with at most
+THREE questions; the scenario-ranked image-card style picker is a separate call after
+the scenario is known. Run `bin/deck-styles.cjs` and pass its `options` unchanged;
+the app expands the full-gallery option. The manual fallback is defined in SKILL.md.
+What each answer means here:
+
+1. **Content source** — 提供材料 / 联网调研 / 自由创作 (offline / no web tool → say so;
+   only the first and last). Provided → request the materials now; when you ask for a FILE, set
+   `filePick: "file"` on that question (a native file button; the picked path is the
+   answer). **Material given as CONTENT is for its TEXT/DATA only** — extract and
+   re-author it in the chosen style; never reuse its look. A `.pptx` handed in as
+   content → read its text (`.txt` sidecar or `bin/doc-text`); do **NOT**
+   `pptx-tokenize`/`pptx-theme` it. Reusing a deck's look happens only when the user
+   picks it as their **style** ("复用这份 PPT 的风格"), never because the content
+   arrived as a `.pptx`.
+2. **Scenario** — AskUserQuestion caps TEXT options at 4, so offer the 3–4 rows of the
+   matrix below that best fit the topic (the user can type any other); an unlisted
+   answer maps to the nearest row. Record it as a short phrase. It locks **five** things:
+   tone · density (feeds Phase 4) · **required roles** (the default checklist for Phase 2) ·
+   narrative shape (Phase 2) · page range (the slide-count default). Then run
+   `bin/deck-scenario.cjs "<scenario>"` once: it prints that row with each section's
+   `content` — what the section must contain (elements, evidence, a recommended shape).
+3. **Slide count** — default = the row's **默认页数**; clamp 3–30, double-check outside.
+
+**Scenario matrix** — source of truth `scenarios.json`; the tables below are generated
+from it. The required roles (必备章节) are the scenario's **default**: every one appears
+unless the user's own words say otherwise.
+
+**User wins; the matrix is only the base.** When the topic or answers conflict with the
+row — 「别讲团队」, 「按 现状 / 挑战 / 路线图 三段讲」, a chapter order of their own — follow
+the user:
+- **Their structure** → chapter titles follow it. Never splice role names into a title
+  (「挑战｜Solution」, 「融资需求｜团队｜下一步」). Fold each default role into their nearest
+  chapter and name it at the start of a point (「融资需求：…」).
+- **Omit** a role only when the user said so, and only with their verbatim words.
+  「简短一点」 means fewer pages, not dropping Ask — merge roles instead.
+- Record every override in `deck-brief.md` → `Overrides:`
+  `Team/团队 omitted — "别讲团队"` · `Market/市场 merged into S3`.
+  An omission without a verbatim quote is not an override, so restore that role.
+- The format contract and no-fabrication rules are never overridable.
+
+<!-- generated:scenario-matrix · source: scenarios.json · regenerate: node scripts/deck/gen-scenarios.mjs — do not edit by hand -->
+| 场景 | 语气 | 密度 | 必备章节(required roles — default; user overrides win) | 叙事(Phase 2) | 默认页数 |
 |---|---|---|---|---|---|
-| **pitch** 融资/路演 | 自信 · 有张力 · 故事驱动 | 稀疏 · 大数字 | Problem/问题 · Solution/解决方案 · Market/市场 · Product/Traction/产品/进展 · Team/团队 · **Ask/融资需求** | SCQA / 问题-方案 | 10–12 |
+| **pitch** 融资/路演 | 自信 · 有张力 · 故事驱动 | 中 · 大数字+一句解释 | Problem/问题 · Solution/解决方案 · Market/市场 · Product/Traction/产品/进展 · Team/团队 · **Ask/融资需求** | SCQA / 问题-方案 | 10–12 |
 | **内审** | 客观 · 直接 · 结论先行 | 略密(容明细/数据) | 结论/进展 · 关键指标 · 问题与风险 · 下一步/决策项 | 结论先行 | 6–8 |
 | **销售** | 利益驱动 · 客户中心 · 说服 | 中 · 重价值与佐证 | 痛点 · 方案/价值主张 · 差异化 · 客户案例 · ROI/定价 · **CTA/行动号召** | 问题-方案 | 8–12 |
 | **讲座** 学术 | 讲解 · 循序渐进 | 中 · 概念+例子 | 学习目标 · 背景/基础 · 核心概念 · 案例/推导 · 小结 | 由浅入深 | 10–15 |
@@ -106,36 +95,28 @@ pages). The required roles are a HARD checklist — Phase 2 must include them al
 | **产品调研** 竞品分析 市场研究 | 客观 · 有据 · 不替结论下判断 | 中 | 市场规模 · 竞品格局 · 用户需求 · 差距与机会 · 结论建议 | 先摆事实，再给判断 | 10–15 |
 | **会议纪要** 会后同步 | 简洁 · 可执行 · 不复述过程 | 低 | 议题 · 结论 · 待办 · 待决事项 | 结论先行 | 4–8 |
 | **数据分析** 数据解读 指标复盘 | 结论先行 · 可追溯 | 中 | 结论 · 口径与数据源 · 维度拆解 · 归因 · 建议 | 结论先行 | 6–10 |
+<!-- /generated:scenario-matrix -->
+
+<!-- generated:scenario-style-bias · source: scenarios.json · regenerate: node scripts/deck/gen-scenarios.mjs — do not edit by hand -->
+Tone also biases the catalog style ranking: 张力/情绪(pitch·发布会·大会)→ 深色酷炫(cool/apple/black-gold);务实(内审·销售)→ 白底咨询(mckinsey);清晰(讲座·培训)→ 中性/教育风.
+<!-- /generated:scenario-style-bias -->
 
-**必备章节要中英双写（`English/中文`）。** 这张 checklist 的用法是拿每个词去**生成
-出来的大纲标题**里找子串（斜杠分段，命中任意一段就算有）。写成纯英文时，一份写得
-好好的中文稿一个都命中不了 —— 于是每次都判缺、每次都白花一轮模型回喂（10–30 秒
-＋一次调用的钱）。反过来整行换成中文也不对：中文路演稿**真的**会写 Problem / Ask /
-Demo，换掉只是把漏判翻到另一边。中文那半边要挑够窄的词：写「融资」的话，一张叫
-「我们的融资故事」的封面就能把 Ask 顶掉，而那一节缺了正是这张表存在的理由。
-括号写法（`关键成果(STAR)`）同样不行 —— 它一个斜杠都没有，整串当一个词去找，
-大纲里必须原样出现那七个字符才算命中。
-
-还有两个容易漏的：**用单数**（大纲会写 `Module 1`，`Modules` 匹配不上，而 `Module`
-两种都命中）；**本来就是中文的那几段也要补英文**（`练习/示例` 漏了 `Exercise`，
-一份英文培训大纲就在这一项上判缺）。
-
-Tone also biases the catalog style ranking: 张力/情绪(pitch·发布会·大会)→ 深色酷炫(cool/apple/
-black-gold);务实(内审·销售)→ 白底咨询(mckinsey);清晰(讲座·培训)→ 中性/教育风.
-If the user's scenario isn't listed, map it to the nearest row's tone/density/narrative.
-
-**Persist `deck-brief.md`**: Topic · Scenario · Source · Style(name + 2–3 sentence
-palette/type/motif) · Theme file · Template style · Slide Count · (assumptions).
-Persist it and continue. Do not ask the user to approve information they just supplied.
-If the brief adds a material assumption that changes scope, show only that assumption
-and pause for approval before continuing.
-(Offline / no web tool → say so; source can only be 提供材料 or 自由创作.)
+**Persist `deck-brief.md`**: Topic · Scenario · Source · Style (entry id + 2–3 sentences
+on palette/type/motif) · Template style · Slide Count · Overrides (if any) · (assumptions) —
+≤10 lines of DECISIONS. Research findings, numbers, chart data and citations do not go
+here: they are written once, in `plan.json`. Persist it and
+continue — do not ask the user to approve what they just supplied. If the brief adds a
+material assumption that changes scope, show only that assumption and pause.
 
 ---
 
-## Phase 1 — Research (open-ended only — PRESERVED, Talos rigor)
+## Phase 1 — Research (open-ended only)
 
-Search 8–12 queries across layers, then organize into 6 dimensions:
+Run 8–12 queries **in parallel** (many searches at once, or a sub-agent per dimension —
+breadth beats depth-first), then organize into 概述 / 背景 / 关键信息 / 证据(案例·数据) /
+分析 / 展望. Research with search and fetch only — **do not open the browser** for it (it
+pops a panel in the user's app): a page that blocks fetch (403, timeout, paywall) → use
+its search snippet or another source. Open it only when the user asks for that page.
 
 | Layer | Query pattern |
 |---|---|
@@ -145,16 +126,11 @@ Search 8–12 queries across layers, then organize into 6 dimensions:
 | Application | `[主题] 案例/实践` |
 | Trends | `[主题] 趋势/未来` |
 
-Dimensions: 概述 / 背景 / 关键信息 / 证据(案例·数据) / 分析 / 展望.
-
-**层次是兜底，场景才是方向。** 上面那五层是**开放式议题**的默认铺法（用户只给了
-一个主题、没有材料）。一旦 Phase 0 选定了场景，就照下表按**这份稿子真正需要的东西**
-去查 —— 每条焦点出 1–2 条查询词，再从上面五层补 2–4 条防止十条围着一个角度。
-用户在 Phase 0 自己交代的那句话优先级最高，先查他明说要的。
-
-焦点直接对着上面场景矩阵的 `必备章节` —— 查回来的东西要能填进那些章节，
-否则这一轮检索就是白花的（按次计费）。
+**层次是兜底，场景才是方向。** 五层只是只给了主题时的默认铺法。场景选定后按下表查这份
+稿子真正需要的东西：每条焦点 1–2 条查询，再用五层补 2–4 条防止十条围着一个角度；用户
+自己点名要的先查。焦点对着场景的必备章节——查回来填不进去的检索就是白花钱（按次计费）。
 
+<!-- generated:scenario-research-focus · source: scenarios.json · regenerate: node scripts/deck/gen-scenarios.mjs — do not edit by hand -->
 | 场景 | 检索焦点 |
 |---|---|
 | **pitch** 融资/路演 | 市场规模与增速(TAM/SAM) · 可比公司融资与估值 · 同类产品与差异 · 目标客群痛点证据 |
@@ -175,31 +151,28 @@ Dimensions: 概述 / 背景 / 关键信息 / 证据(案例·数据) / 分析 /
 | **产品调研** 竞品分析 市场研究 | 市场规模与增速 · 竞品功能与定价对比 · 用户评价与差评 · 渠道与份额数据 |
 | **会议纪要** 会后同步 | 议题涉及的外部事实 · 相关口径与定义 · 同类决策的公开先例 |
 | **数据分析** 数据解读 指标复盘 | 指标口径定义 · 行业基准值 · 同类归因案例与方法 |
+<!-- /generated:scenario-research-focus -->
 
 内部数据型的几档（内审 · 述职 · 工作汇报 · 年度总结）焦点**刻意收窄到对标与口径**：
-它们的主体材料在用户自己手里，联网能补的只有"外面是什么水位"。照五层去查行业定义
-和历史，查回来的东西一条都填不进它们的必备章节。
-
-**Fan out, then cite:** run layers in PARALLEL (many searches at once, or a
-sub-agent per dimension) — breadth beats depth-first. **Every data point
-(number/percent/year/quote) carries its source** — keep a `{claim → URL}` list; a
-stat without a source is a hallucination risk, drop it. **Quality gate: ≥3
-authoritative sources, ≥5 distinct domains, drop >5-year-old or unverified.** The
-source list goes on a "参考来源" ending slide AND into speaker notes.
-
-**Assets & notes (matters MORE now that slides are text-sparse):** generate
-figures/photos with the media-generation MCP(文生图)into local files, reference by
-path (`<img src="./hero.png">`) — `html2pptx` auto-inlines them as data: URIs. Push
-every detail/caveat/citation that does NOT fit the sparse slide into per-slide
-**speaker notes** (`<div class="talos-notes" style="display:none">…</div>` → pptx
-notesSlide; `--notes-doc` emits a standalone notes doc). Cite → notes → assets, one pass.
+主体材料在用户手里，联网只能补"外面是什么水位"。
+
+**Cite everything:** every data point (number / percent / year / quote) carries its
+source in a `{claim → URL}` list; a stat without one is dropped. **Quality gate: ≥3
+authoritative sources, ≥5 distinct domains; drop anything >5 years old or unverified.**
+The source list goes on a "参考来源" ending slide AND into speaker notes. On the slide
+itself: at most ONE short line, publisher + year — the slide's `source` in the plan
+(「来源：IDC，2026」) — the data period,
+scope caveats and URL go to notes and 参考来源, never a footnote sentence. The user's
+own figures carry no source line. Plan generated visuals in Phase 3; generate after
+the outline and style are confirmed (generated-visuals.md).
 
 ---
 
-## Phase 2 — Narrative structure (PRESERVED — Talos Pyramid/SCQA/MECE)
+## Phase 2 — Narrative structure (Pyramid / SCQA / MECE)
 
-Pick the pyramid shape by deck type, build chapters top-down:
+Take the scenario row's narrative (by deck type below) and build chapters top-down:
 
+<!-- generated:scenario-narratives · source: scenarios.json · regenerate: node scripts/deck/gen-scenarios.mjs — do not edit by hand -->
 | Deck type | Structure | Chapter flow |
 |---|---|---|
 | 报告/总结 | 结论先行 | 结论 → 证据 → 细节 → 下一步 |
@@ -207,153 +180,102 @@ Pick the pyramid shape by deck type, build chapters top-down:
 | 培训/教学 | 由浅入深 | 基础 → 核心 → 进阶 → 练习 |
 | 融资/路演 | SCQA | 情境 → 冲突 → 问题 → 解答 |
 | 活动/宣传 | 情绪线 | 钩子 → 共鸣 → 高潮 → 行动 |
+<!-- /generated:scenario-narratives -->
 
-Default 14–20 pages; 1–5 pages per chapter. **MECE check**: chapters don't overlap
-and together fully support the ONE core message. The scenario's required roles
-(Phase 0) must all appear.
+Page count = the confirmed slide count; 1–5 pages per chapter. **MECE**: chapters don't
+overlap and together support the ONE core message; every required role appears, unless
+it is merged or omitted per the brief's Overrides.
 
 ---
 
-## Phase 3 — Outline artifact (MANDATORY gate — WorkBuddy chapters.md richness + Talos slide/notes split)
-
-Materialize the plan into `slide-outline.md` — the single source of truth for Phase
-4–5; do not re-decide count/roles later. Each slide gets a **full per-page content
-spec block** (the depth of WorkBuddy's `chapters.md`), but the page's substance is
-split into **what appears ON the canvas (sparse)** vs **what moves to speaker notes
-(detail)** — so the outline plans real content without pre-writing a wall of text.
-
-```markdown
-# Slide Outline
-## Meta        — from deck-brief.md (Topic/Scenario/Source/Style/Theme/Template style/Count)
-## Source Materials — provided summary · {claim→URL} list · or "N/A — topic knowledge"
-## Slide-by-Slide   (one BLOCK per slide — a full content spec, not a one-liner)
-
-### S1 — Cover
-- Template: cool/cover
-- Takeaway: <one line — the TITLE stated as a CONCLUSION, not the topic>
-- Content structure: <Data/Trend · Single-impact · Argument · Cards · Comparison · Process · Framework · Case-study · Summary> — core elements: …
-- On-slide (sparse): <only what shows ON the canvas — ≤3–5 key points / numbers, phrase-level>
-- Data points {claim→URL}: <n1 (src) · n2 (src) · …>   (drop any stat with no source)
-- → Notes: <detail / caveat / context / citations that go to SPEAKER NOTES, never the slide>
-- Density: Light(≤3) / Medium(4–6) / Heavy(7+) · Dark: yes/no · Chart: yes/no · Image: yes/no
-- Narrative role: <how this page advances the ONE core message>
-
-### S2 — Agenda
-- Template: cool/toc
-- … (same fields; repeat one block for ALL N slides)
-
-## Visual Rhythm
-- Dark-accent slides at: <e.g. 1, 7, N>   (≥1–2 dark slides)
-- Chart-bearing slides at: <e.g. 4, 6, 9>
-- Template rotation: no template >2 slides in a row, none more than twice total unless unavoidable
+## Phase 3 — Outline artifact (MANDATORY gate)
+
+First see what the chosen style's layouts take — one call, before writing anything:
+
+```
+node <skill>/bin/deck-plan.cjs --layouts --style <style id>
 ```
 
-Each slide BLOCK commits: the **role + template(archetype)** (Phase 4 catalog); a
-**one-line takeaway** (title = conclusion, not topic); the **content structure +
-core elements** (from the §4.1 catalog); an explicit **On-slide (sparse) vs → Notes
-(detail)** split so substance is planned without crowding the canvas; **{claim→URL}**
-for every data point (a sourceless stat is dropped); and the **density / dark /
-chart / image** flags. Then **GATE**: show the outline, AskUserQuestion
-approve/revise, advance only on approval.
+One line per layout this style renders, with the plan fields it takes
+(bin-reference.md). Write each slide's content to the layout you mean it for.
+
+Write the outline ONCE, as `plan.json` — `deck-plan`'s input and the single source of
+truth for Phase 4–5 (do not re-decide count or roles later). Per slide: `role` · `title`
+(the takeaway, stated as a CONCLUSION) · `shape` / `intent` · what goes ON the canvas,
+(`subtitle` · `points` · `stats` · `quote` · `table` · `chart` · `image` · `takeaway`) ·
+`source` (one short line) · `notes` (what to say + the one caveat that matters, 2–3
+sentences, ≲120 字 — never on the slide; cite as "见来源 1": the full citation — title,
+date, URL — is written ONCE, in the 参考来源 slide's notes, never re-quoted per slide or
+in the original language) · `narrative` (how it advances the ONE core message) · `file` for a bespoke slide
+(deck-design.md). Write `plan.json` itself with the file tool and edit it in place on a
+revision — no script that generates or patches it. Render the outline from it;
+never write it by hand:
 
----
+```
+node <skill>/bin/deck-plan.cjs plan.json spec.json --outline slide-outline.md
+```
 
-## Phase 4 — Author & fill (merge: templates + narrative + WorkBuddy density/visual)
+One block per slide (Takeaway · Shape · On-slide · Chart · Source · Notes · Narrative
+role) plus the layout each slide got. A slide that fits no layout says so in its block —
+fix its content before asking. Keep ≥1–2 dark-accent and the chart pages spread through
+the deck (visual rhythm).
 
-Announce the on-canvas language first (default = the user's prompt language; respect
-an explicit "用英文/use English"): one line, e.g. `本次幻灯片内容将使用中文生成`.
+A required section's block covers its `content` (deck-scenario) — the elements on the
+slide or in the data points, the evidence with a source — unless the user's words say
+otherwise. An element with no source → say so in Notes; never invent the number.
 
-**Default route = `layouts/` × a skin + html2pptx.** For each slide: pick the layout
-that matches its content structure (by P1/P2/P3, `layouts/README.md`), **copy the
-`.tpl` `<section>` into the deck HTML, replace the sample text/numbers with real cited
-content** — leave color to the skin (never hardcode a brand hex). Render
-`bin/html2pptx.cjs deck.html out.pptx --style <skin>`. Where the catalog doesn't fit
-(bespoke hero covers, layered architecture, magazine) author bespoke HTML per
-**deck-design.md** (still using the skin's semantic classes). With no browser at
-all, say so and stop — there is no spec-deck fallback.
+A ~9pt footer carries ≤24 characters (deck-plan rejects longer): `source` is the
+publisher and year ("Maximize Market Research，2026"); URL and caveats go in `notes`.
 
-### 4.1 Content structure → layout
+Assess where generated visuals improve the story: typically 2–3 pages, not a quota.
+Count them within the total; mark purpose and image/text mode in `narrative`, reserve
+`file` paths before HTML exists, and follow generated-visuals.md.
 
-| Content structure | Core elements | → `layouts/*` (P1/P2/P3) |
-|---|---|---|
-| **Data / Trend** | 数据标题 + 指标 + 一句数据故事 | `chart-kpi` |
-| **Single impact** | 一个关键数字 + 上下文 | `big-stat` |
-| **Argument / Concept+visual** | 论点/定义 + 3–4 证据/组件 | `split-two-col` |
-| **Cards (并列要点)** | 3 个并列要点 | `cards-3` |
-| **Comparison** | 框架 + 2–3 选项 × 维度 + 推荐 | `comparison` |
-| **Process** | 目标 + 3–5 步骤 | `steps` / `steps-vertical` |
-| **Framework/Matrix** | 两轴 + 四象限 | `matrix-2x2` |
-| **Case Study** | 背景/挑战/方案/前后 | `split-two-col` + `big-stat` |
-
-Role pages: `cover` · `toc` · `section` · `ending` (and their variants in `layouts/README.md`). Anything no layout fits → a bespoke slide (deck-design.md).
-
-### 4.2 Pick the exact template — priority order (P1 → P2 → P3)
-
-The 4.1 table gives the template FAMILY; resolve the exact `.tpl` (and variant) in
-this **priority order** — P1 outranks P2 outranks P3; never trade layout-fit for variety:
-
-- **P1 — Layout match (most important): image presence + position.** No image → a
-  text-only template (`cards-3` / a text-column split). Image present → `split-two-col`
-  with the visual on the side it reads best (mirror the `.tpl` for image-left). Data →
-  `chart-kpi` (chart choice — inline SVG vs native `data-chart` — per deck-design.md "Charts"). Never force text into an image slot or an image
-  into a text slot; delete an unused image slot rather than leaving a placeholder.
-- **P2 — Density match: point count → variant.** 1–2 points / one hero number →
-  spacious·centered (`big-stat`, hero cover); 3–4 points → balanced two-column
-  (`split-two-col` / `cards-3`); 5+ points → grid·dense (`cards-3` grid or bespoke
-  multi-column). Match the template's slot count to the outline's point count — if
-  content > slots, condense to ≤6 items; if content < slots, remove the spare slots.
-- **P3 — Diversity (ENFORCED, hard rule).** ❌ same template twice in a row · ❌ same
-  template >2× total. Vary the variant even when the family repeats. **TOC by chapter
-  count**: 3–4 → centered/large-title · 5–6 → list/grid · 7+ → dense/two-column.
-  **Reuse ONE `section` template for ALL transition pages** (consistency), but rotate
-  content templates. If the catalog can't satisfy P1+P2 without repeating, author a
-  bespoke slide (deck-design.md) rather than force a wrong-fit template.
-
-### 4.3 Premium density (REPLACES the old text-density floor)
-
-- **One message per slide.** The title states the **takeaway** (conclusion), not the topic.
-- **Short phrases > sentences. No paragraphs on the slide.** Every detail, caveat,
-  and citation goes to **speaker notes**, not the canvas.
-- **Substance = VISUAL + DATA, not word count.** Each content slide carries real
-  substance through **≥1 chart/diagram/big-number/decorated visual + 3–5 concrete
-  data points** (numbers/%/years) — the data lives in the visual, its story in one
-  line. A bullets-only slide is a last resort for genuinely list-like content.
-- **Never shrink the font to fit** — doesn't fit at the sizes below → split or remove.
-
-### 4.4 Premium visual contract (adapted from WorkBuddy Rule 1/2/3)
-
-- **Big typography** (`[size=1..7]` = 12/14/16/24/32/48/72px on the 1280×720 canvas):
-  titles `size 6–7`; section headings `size 5–6`; body `size 3–4`, never below
-  `size 3` (16px); hero KPI number huge (`big-stat`). Max 2 font families; use weight,
-  not many sizes.
-- **Rich backgrounds** — never pure white/black; theme gradient + a decorative motif.
-  **≥1–2 dark-accent slides** across the deck (Visual Rhythm).
-- **≥2 decorative/visual elements per content slide**; **charts > text for data**, one
-  insight per chart (SVG or native `data-chart` per deck-design.md "Charts"), highlight the key datapoint, no junk.
-- **Emotional opening & closing** — cover and ending are STATEMENTS (feeling, not
-  facts): strong visual + few powerful words.
-- **Visual diversity** — enforced by P3 (§4.2); a deck of one repeated layout reads as
-  machine-made.
+Then **GATE**, in this order — never ask before the outline exists:
+1. `plan.json` written and `slide-outline.md` rendered by the command above;
+2. `read` `slide-outline.md` — the outline shows in the timeline;
+3. AskUserQuestion, ONE sentence ("是否按这份 12 页大纲制作？"), `confirmation` with
+   `options: ["按此制作", "调整大纲"]` — never the outline in the question.
+
+Advance only on approval. A revision edits `plan.json` and re-runs the same command — the outline and the
+spec move together.
 
 ---
 
-## Phase 5 — Fast preview + final adversarial QA
-
-Use a two-stage loop; do not pay the Office cold-start cost on every visual edit:
-
-1. **Authoring loop (HTML, fast):** render `deck.html` directly with
-   `bin/html2pptx.cjs deck.html --preview-dir <dir> [--preview-pages <spec>]` and inspect every page on
-   the first pass. Fix HTML/CSS, then preview only changed pages. Repeat until the HTML
-   composition is clean.
-2. **Delivery loop (PPTX, once after HTML is clean):** build the PPTX and fix the
-   `qa` findings the build prints. Then sign off with one `deck-qa deck.pptx --final`:
-   strict validation, the Office render and its drift check, and `previews` — the
-   only slides to look at again; every other slide was already judged in the HTML
-   preview (deck-design.md "Verify before delivering", step 3, and its
-   read-everything exceptions). If that pass finds drift, fix and rerun only as
-   required; never use PPTX→PDF as the routine authoring preview.
-
-Assume there are defects and inspect text overflow/clipping, collisions, tofu/blank
-CJK, cramped gaps, low contrast, leftover placeholders, and cross-slide consistency.
-Finish only after the generated PPTX has one clean structural, mechanical, and faithful
-visual pass.
+## Phase 4 — Author
+
+Announce the on-canvas language in one line (default = the user's prompt language;
+respect an explicit "用英文/use English"). Generate the approved visuals, then author
+their `file` slides and follow deck-design.md "Workflow" with the approved plan.
+Layout selection rules (P1/P2/P3) live in layouts/README.md.
+
+Content density — what each slide carries:
+
+- **One message per slide**; the title states the takeaway.
+- **Read deck** (default; `deck-plan` reads it off the scenario — 发布会/大会/年会 are
+  talk decks): each point = a label + ONE explanatory sentence (`body`; stats: `note`),
+  plus `subtitle` (口径 / why it matters) and `takeaway` (启示) — 120–300 字 per slide;
+  `content-thin` flags less. **Talk deck**: phrases only. Either way no paragraphs;
+  citations and long caveats go to the notes.
+- **Substance = visual + data.** Each content slide carries ≥1 chart / diagram / big
+  number / visual plus 3–5 concrete data points, with its story in one line. A
+  bullets-only slide is the last resort for genuinely list-like content.
+- **Cover and ending are statements** — strong visual, few powerful words. On the
+  cover the title is by far the largest text; besides it only the brand/eyebrow once
+  (brand, event or date — never a chapter name like 现状), a subtitle and at most one
+  key line. No running header or chapter nav, no stat row,
+  no source line — the key numbers open slide 2.
+- Doesn't fit → split or cut; never shrink the type (visual rules: deck-design.md
+  "Design principles").
+
+---
+
+## Phase 5 — Preview, build, sign off
+
+deck-design.md "Verify before delivering" is the procedure. In short: iterate on HTML
+previews (`html2pptx.cjs deck.html --preview-dir <dir>`, then `--preview-pages` for the
+changed slides), build the PPTX and fix its `qa` findings, then sign off once with
+`deck-qa deck.pptx --final` and look only at its `previews`. Never use PPTX→PDF as the
+authoring preview. Finish only after one clean structural, mechanical and visual pass.
+For PDF delivery, follow deck-design.md: convert the final PPTX through Office and
+inspect that PDF, reusing final QA output only while the PPTX is unchanged.