@taloswork/ose-shared 0.1.9 → 0.1.11

package/skills/document/deck-design.md

@@ -1,16 +1,16 @@
 # Deck design — html2pptx (hybrid) is THE deck engine
 
 **Every deck is built ONE way:** author slide HTML and render with `html2pptx` in
-its default **HYBRID** mode — `bin/html2pptx.cjs deck.html out.pptx --theme <t>`
+its default **HYBRID** mode — `bin/html2pptx.cjs deck.html out.pptx --style <id>`
 (no `--editable`/`--rasterize`). Chromium gives you the full power of HTML/CSS
 (flexbox/grid, layering, per-element SVG) and converts to NATIVE editable pptx
 text boxes/shapes, with the decorative visual layer baked into one pixel-perfect
 backdrop — designed look **AND** editable words + editable `data-chart`. This is
 the path for every deck: pitch / keynote / report / design-y / plain alike.
 
-`doc-gen pptx` archetypes and `doc-run` PptxGenJS are **NOT deck-building paths** —
-do not use them to build a deck. (They remain for NON-deck jobs only: structured
-data tables, batch/deterministic document generation, shape-level one-offs.)
+`doc-gen` makes no decks, and `doc-run` PptxGenJS is **NOT a deck-building path** —
+do not use it to build a deck. (It remains for NON-deck jobs only: structured
+data tables, batch/deterministic generation, shape-level one-offs.)
 
 html2pptx needs a browser — the app's Chromium service or the bundled Playwright.
 If neither is available, **say so and stop; never silently downgrade** to a lesser
@@ -33,11 +33,11 @@ every slide from zero is the #1 "AI-generated" tell; compose from the catalog fi
 ## html2pptx — HTML/CSS is the layout engine
 
 ```
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --theme <theme.json>       # DEFAULT = hybrid (visuals + editable text)
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <name>             # structure/skin split: paint layouts/ with styles/<name>/
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --theme <t> --editable     # plain native (effects flatten)
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --theme <t> --rasterize    # pixel-perfect, NOT editable
-node <skill>/bin/html2pptx.cjs snapshot.layout.json out.pptx                 # headless-safe input (always plain native)
+node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <id> [--theme-v2]  # DEFAULT = hybrid: paint layouts/ with the catalog entry
+node <skill>/bin/html2pptx.cjs deck.html --preview-dir <dir> --style <id>     # authoring preview: PNG per slide, no pptx
+node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <id> --editable     # plain native (effects flatten)
+node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <id> --rasterize    # pixel-perfect, NOT editable
+node <skill>/bin/html2pptx.cjs snapshot.layout.json out.pptx                  # headless-safe input (always plain native)
 ```
 
 ### ⭐ PREFERRED workflow — structure/skin split (`--style`)
@@ -128,12 +128,15 @@ needs) so it becomes reusable: bespoke first, then graduate the winners into the
 Contract (violations fail loudly, nothing degrades silently):
 
 - One `<section class="slide">` per slide, laid out on a **1280×720 px** canvas
-  (= 13.33×7.5 in). The bin injects a reset + the theme's CSS variables — style
-  with `var(--primary|--accent|--secondary|--text|--muted|--card-bg|--border|
-  --slide-bg|--title-color|--body-color|--font-heading|--font-body)`, never
-  hardcode brand colors. html2pptx **warns** (`N hardcoded brand color(s) bypass
-  theme vars`) when a slide writes a hex instead of a `var(--…)` — that deck won't
-  re-theme, so fix it before shipping. (SVG diagram semantic colors are exempt.)
+  (= 13.33×7.5 in). Color comes from the skin (`--style`), whose tokens every skin
+  defines: `var(--accent|--title|--body|--muted|--hair|--slide-bg|--title-color|
+  --body-color|--font-heading|--font-body)` plus the ramp `var(--c1..--c4)` — never
+  hardcode brand colors, and never use a name outside this set (`--primary`,
+  `--text`, `--card-bg`, `--border` are NOT defined by skins: they only exist under
+  the legacy `--theme` path, so on a `--style` deck they silently stick on their
+  fallback). html2pptx **warns** (`N hardcoded brand color(s) bypass theme vars`)
+  when a slide writes a hex instead of a `var(--…)` — that deck won't re-skin, so
+  fix it before shipping. (SVG diagram semantic colors are exempt.)
 - **Tailwind utility classes are available** (vendored offline — no CDN needed):
   author like a modern web deck — `grid grid-cols-2 gap-16`, `flex items-center
   justify-center`, `p-16`, `text-6xl font-bold`, `rounded-3xl`, `bg-blue-600`,
@@ -176,8 +179,8 @@ Contract (violations fail loudly, nothing degrades silently):
 - Fonts are measured by Chromium but re-laid-out by PowerPoint — keep ~10%
   slack in text boxes; don't butt text against box edges.
 
-After generating: `doc-validate --strict --design-lint`, then render-and-look
-(doc-convert → PDF → view) like any deck.
+After generating: the build reports `valid` and `qa` itself; sign off with
+`deck-qa --final` like any deck ("Verify before delivering").
 
 ## HTML slide authoring — the design-first route
 
@@ -281,12 +284,17 @@ The shipped `layouts/*.tpl` are this recipe applied as structure-only slides —
 paste the nearest one and paint it with a skin (`--style`) rather than rebuilding
 the stack by hand; each already carries the 8 layers correctly wired.
 
-**动画优先由族的 motion 预设派发**（`motion/<id>.json`，`catalog.json` 里该 entry 的
-`motion` 字段指到它；`deck-build` 填槽时按每页 layout 的 role 自动注入
-`data-anim*`/`data-transition*`）。手写 `data-anim`/`data-transition` 仍然优先 ——
-`deck-build` 只在元素还没有该属性时才注入，用于特例覆盖派发结果。没有 motion 预设
-的族（当前 13 个 skin 在 P0 都没有）保持这一段以下描述的默认行为：不写
-`data-anim` 就没有任何动画。
+**Every catalog entry ships a motion preset; the scenario decides whether
+`deck-build` applies it.** (`motion/<id>.json`, named by the entry's `motion` field.)
+Put the confirmed scenario in the spec as `"scenario"`: a **presented** deck (pitch /
+路演 / 发布会 / keynote / 大会 / 讲座 / 销售) gets the preset — `data-anim*` /
+`data-transition*` injected per slide by the layout's role; a **read** deck (内审 /
+评审 / 报告 / 汇报 / 讲义 / 培训 / 述职) gets none; no or an unknown scenario keeps the
+preset. `"motion": true|false` overrides the scenario. The build's JSON says which
+applied and why (`motion: {on, reason}`). Hand-written `data-anim` /
+`data-transition` always wins — `deck-build` only adds an attribute an element does
+not already have, and a deck authored straight into `deck.html` animates only
+where you write `data-anim`.
 
 ## Motion — entrance animation + slide transitions
 
@@ -297,10 +305,10 @@ build sequence — not a video, not a GIF). Mark an element with `data-anim` and
 becomes one build step; the deck then plays like a keynote instead of appearing
 all at once.
 
-**Off unless you ask for it.** No `data-anim` anywhere → no `<p:timing>` → byte-
-identical output to before. Reach for it when the scenario is a **stage** —
-发布会 / 路演 / pitch / 主题演讲 — and skip it for 内审 / 报告 / 讲义 decks that
-people read rather than watch.
+**The attribute itself is opt-in.** No `data-anim` on the page → no `<p:timing>`.
+Write your own when the scenario is a **stage** — 发布会 / 路演 / pitch / 主题演讲;
+for 内审 / 报告 / 讲义 decks that people read rather than watch, add none beyond
+what the preset already injects.
 
 #### The attribute contract
 
@@ -472,56 +480,11 @@ A face that is bundled but neither baked nor embedded is *still worth bundling*
 backdrop and the picker previews come out right), just don't assume the native text
 followed. `hand-drawn`'s Gochi Hand heading is exactly that case today.
 
-## Running a script (PptxGenJS via doc-run — NOT for decks)
-
-> **This section is reference for NON-deck freeform PptxGenJS only** (bespoke
-> one-off shapes, non-deck pptx). **Do not build a deck this way** — every deck
-> goes through html2pptx hybrid (see the top of this file). Kept here so the
-> capability is documented, not as a deck path.
-
-Write `deck.js`, run it with **`node <skill>/bin/doc-run.cjs deck.js`** —
-`pptxgenjs` (and `jszip`, `pdf-lib`, `docx`, `xlsx`, `hyperformula`) are bundled
-inside doc-run, so `require("pptxgenjs")` works on any machine with no install
-step (packaged app included; `doc-run --list` prints the registry). Bare
-`node deck.js` only resolves those libs on a dev checkout — always use doc-run.
-
-## Canvas & grid
-
-- Layout: 16:9 wide = **13.33 × 7.5 inches**, origin top-left, units in inches.
-- Safe margins: 0.6 left/right, 0.3 top, 0.45 bottom (footer/page number zone).
-- Use a 12-column mental grid: column width ≈ 1.0", gutters 0.1".
-- Vertical rhythm: title zone y 0.3–1.05; content y 1.25–7.0.
-
-```js
-const pptxgen = require("pptxgenjs");
-const p = new pptxgen();
-p.defineLayout({ name: "WIDE", width: 13.33, height: 7.5 });
-p.layout = "WIDE";
-```
-
-## Theme first — never hardcode colors
-
-Load the active theme (the user's template skill ships one, or use the document
-skill's `themes/mckinsey-consulting.json`). PptxGenJS colors are bare hex (no `#`).
-
-```js
-const { readFileSync } = require("node:fs");
-const t = JSON.parse(readFileSync(process.env.TALOS_DOC_THEME ?? "<skill>/themes/mckinsey-consulting.json", "utf8"));
-const C = {
-  primary: (t.colors?.primary ?? "#1a3c6e").replace("#", ""),
-  text:    (t.colors?.text ?? "#1f2328").replace("#", ""),
-  muted:   (t.colors?.muted ?? "#5b6570").replace("#", ""),
-  cardBg:  (t.colors?.tableHeaderBg ?? "#eef2f8").replace("#", ""),
-  border:  (t.colors?.tableBorder ?? "#c6d0dd").replace("#", ""),
-};
-const FONT = t.fonts?.body || undefined; // undefined → platform default (CJK-safe)
-```
-
 ## Design principles (the constraint EVERY deck honors)
 
-This is the "design ideas" bar for a freeform deck. The archetype path already
-bakes most of it into the engine (dominant accent, contrast-picked text, motif,
-no under-title lines); when you hand-build slides YOU are responsible for it.
+This is the "design ideas" bar for a freeform deck. The catalog layouts
+(`layouts/*.tpl`) already bake most of it in (dominant accent, contrast-picked
+text, motif, no under-title lines); when you hand-build slides YOU are responsible for it.
 Not a menu — treat it as a checklist the deck must pass.
 
 **Color — commit, don't sprinkle.**
@@ -537,7 +500,7 @@ Not a menu — treat it as a checklist the deck must pass.
 - No slide is a wall of text. Each one gets a structural element: a colored band,
   a big number, an icon row, a 2×2, a chart, or a supporting image. A title +
   bullets on white is the classic AI tell — restructure it (this is exactly what
-  `--design-lint` flags as `text-only-slide`).
+  the build's `qa` flags as `text-only-slide`).
 - Reach for the strong composition patterns: two-column split, icon+label rows,
   a 2×2 grid, a half-bleed image with text on the other half, one hero figure.
 - Vary the layout slide-to-slide. Ten identical bullet slides is the single
@@ -563,7 +526,7 @@ Not a menu — treat it as a checklist the deck must pass.
 **Contrast — readability is non-negotiable.**
 - Text on fills must clear ~4.5:1 (large/bold ~3:1). Dark fills → light text
   (`F1FAEE`/`FFFFFF`); light fills → the `text` color. When unsure compute
-  luminance. `--design-lint` flags the worst offenders as `low-contrast-text`.
+  luminance. The build's `qa` flags the worst offenders as `low-contrast-text`.
 
 **The AI tells to avoid** (these scream "template"):
 - A thin accent LINE under the title. Never. It's the #1 giveaway; use space,
@@ -612,17 +575,17 @@ per page; add them as the deck needs. Catalogs in `assets/snippets/`:
 
 All snippets are hybrid-native: chips, rules, frames, gradients, SVG **bake into the
 backdrop**; labels, page numbers, chart data stay **native/editable**. Route every
-color through theme vars (`var(--accent, …)`) so one `--theme` reskins them — the same
+color through the skin tokens (`var(--accent, …)`) so one skin reskins them — the same
 `footer-pageno` fragment becomes tech-cyan or 国风-朱红 by swapping `--accent`.
 
 **Pairing a snippet with the theme** — two independent dimensions:
-- **Color = automatic.** Snippets read only the **12 injected vars** (`--primary
-  --accent --secondary --text --muted --card-bg --border --slide-bg --title-color
-  --body-color --font-heading --font-body`). Set the deck `--theme` and every snippet
-  recolors for free; the value after the comma is just the no-theme fallback. Any
-  OTHER var name (e.g. `--accent2`) is never injected → it silently sticks on its
-  fallback, so **only use those 12 names**. Need one snippet in an off-theme color?
-  Override on its `<section>`: `style="--accent:#b8292e;--muted:#9a8b76"`.
+- **Color = automatic.** Snippets read only the skin tokens listed in the slide
+  contract above (`--accent --title --body --muted --hair --slide-bg --title-color
+  --body-color --font-heading --font-body --c1..--c4`). Pick the skin and every
+  snippet recolors for free; the value after the comma is just the fallback. Any
+  OTHER var name (e.g. `--accent2`, `--primary`) is not defined → it silently sticks
+  on its fallback, so **only use those names**. Need one snippet in an off-skin
+  color? Override on its `<section>`: `style="--accent:#b8292e;--muted:#9a8b76"`.
 - **Form = your choice.** The theme supplies the palette, NOT the shape. A `neon-dot`
   on a 侘寂 light theme reads wrong even recolored — pick the motif/functional family
   that matches the style's aesthetic (seal→chinese, gold-flourish→black-gold,
@@ -632,139 +595,75 @@ color through theme vars (`var(--accent, …)`) so one `--theme` reskins them
   are intentionally hardcoded; the theme reskins their title/bg/accent but the ramp
   stays so the hierarchy reads.
 
-## Shape vocabulary (the pieces everything is built from)
-
-```js
-// Card
-s.addShape("roundRect", { x, y, w, h, rectRadius: 0.07, fill: { color: C.cardBg }, line: { color: C.border, width: 1 } });
-// Accent bar (left edge of a card, or under a heading)
-s.addShape("rect", { x, y, w: 0.07, h, fill: { color: C.primary } });
-// Divider / timeline spine
-s.addShape("line", { x, y, w, h: 0, line: { color: C.primary, width: 2 } });
-// Node / dot
-s.addShape("ellipse", { x, y, w: 0.18, h: 0.18, fill: { color: C.primary } });
-// Chevron / arrow for flows
-s.addShape("chevron", { x, y, w: 1.2, h: 0.5, fill: { color: C.primary } });
-// Layered stack (architecture): repeat roundRects with y += h + 0.15, widths shrinking
-```
-
-Text goes ON shapes as separate `addText` (easier to position than shape text):
-
-```js
-s.addText("标题", { x, y, w, h, fontSize: 14, bold: true, color: C.text, fontFace: FONT, align: "left", valign: "top" });
-```
-
-## Complete skeleton (title + custom quadrant slide)
-
-```js
-const pptxgen = require("pptxgenjs"); const { readFileSync } = require("node:fs");
-const t = JSON.parse(readFileSync("<theme.json path>", "utf8"));
-const hex = (c, d) => (c ?? d).replace("#", "");
-const C = { primary: hex(t.colors?.primary, "#1a3c6e"), text: hex(t.colors?.text, "#1f2328"),
-            muted: hex(t.colors?.muted, "#5b6570"), cardBg: hex(t.colors?.tableHeaderBg, "#eef2f8") };
-const p = new pptxgen();
-p.defineLayout({ name: "W", width: 13.33, height: 7.5 }); p.layout = "W";
-
-// ── cover
-let s = p.addSlide();
-s.background = { color: C.primary };
-s.addShape("rect", { x: 0.6, y: 3.0, w: 1.1, h: 0.06, fill: { color: "FFFFFF" } });
-s.addText("WorkBuddy 产品路演", { x: 0.6, y: 3.15, w: 12, h: 1, fontSize: 38, bold: true, color: "FFFFFF" });
-s.addText("AI Agent 数字员工 · 2026 Q3", { x: 0.6, y: 4.2, w: 12, h: 0.5, fontSize: 15, color: "E8EEF6" });
-
-// ── custom: 2×2 quadrant (no archetype for this — the freeform case)
-s = p.addSlide();
-s.addText("市场象限", { x: 0.6, y: 0.3, w: 12, h: 0.7, fontSize: 26, bold: true, color: C.primary });
-const qx = 0.9, qy = 1.4, qw = 11.5, qh = 5.4;
-s.addShape("line", { x: qx + qw / 2, y: qy, w: 0, h: qh, line: { color: C.muted, width: 1 } });
-s.addShape("line", { x: qx, y: qy + qh / 2, w: qw, h: 0, line: { color: C.muted, width: 1 } });
-const cell = (cx, cy, title, body, hot) => {
-  s.addShape("roundRect", { x: cx, y: cy, w: qw / 2 - 0.3, h: qh / 2 - 0.3, rectRadius: 0.08,
-    fill: { color: hot ? C.primary : C.cardBg }, line: { color: C.muted, width: 1 } });
-  s.addText(title, { x: cx + 0.2, y: cy + 0.15, w: qw / 2 - 0.7, h: 0.4, fontSize: 14, bold: true, color: hot ? "FFFFFF" : C.text });
-  s.addText(body,  { x: cx + 0.2, y: cy + 0.6,  w: qw / 2 - 0.7, h: qh / 2 - 1.0, fontSize: 11.5, color: hot ? "E8EEF6" : C.text, valign: "top" });
-};
-cell(qx + 0.15, qy + 0.15, "高频 × 高价值", "跨境电商对账 —— 切入点", true);
-cell(qx + qw / 2 + 0.15, qy + 0.15, "低频 × 高价值", "合同合规勾稽", false);
-cell(qx + 0.15, qy + qh / 2 + 0.15, "高频 × 低价值", "日报汇总", false);
-cell(qx + qw / 2 + 0.15, qy + qh / 2 + 0.15, "低频 × 低价值", "暂不投入", false);
-
-p.writeFile({ fileName: "deck.pptx" }).then(() => console.log("ok"));
-```
-
 ## Verify before delivering (MANDATORY automated visual-QA loop)
 
 **Assume there are problems — your job is to find them.** Treat QA as a bug hunt,
-not a confirmation step. Use the cheapest faithful surface for each stage: direct
-HTML screenshots while authoring, then PPTX checks and one Office-rendered final pass.
-Do not launch LibreOffice after every CSS/content edit.
-
-**Gate 1 — structural + schema** (blocking): `doc-validate.cjs deck.pptx
---strict` — exit 1 = fix the reported part, never deliver (`--strict` = full
-ECMA-376 XSD).
-
-**Gate 2 — mechanical QA** (cheap, token-free, run EVERY round):
-`deck-qa.cjs deck.pptx --json` → `{ ok, findings:[{slide,code,message}] }`.
-It deterministically catches **off-canvas** (content clipped past the edge),
-**tiny-font** (<10pt), **shape-overlap** (colliding text), **text-only-slide**,
-**low-contrast-text**, **placeholder-text** (a layout pasted but never filled —
-替换为…/占位/在这里写/Lorem still in a slide), and **font-mismatch** (CJK text set
-in a Latin-only font → 豆腐; expected language defaults to the system locale,
-override with `TALOS_DECK_LANG`). **Fix every finding first** — these
-are objective bugs and free to detect, so they must never reach the vision pass or
-delivery. (This is the same lint as `doc-validate --design-lint`, JSON-shaped for
-the loop.)
+not a confirmation step. Use the cheapest faithful surface for each stage: HTML
+screenshots while authoring, the build's own checks on every build, and one
+Office-rendered sign-off at the end. Do not launch LibreOffice after every edit.
+
+**Machine checks come with the build.** Every `html2pptx … out.pptx` run prints,
+next to the build result, `valid` (does the file open — `false` exits 1: never
+deliver) and `qa: { ok, findings:[{slide,code,message}] }` — deck-qa's lint:
+**off-canvas**, **tiny-font** (<10pt), **shape-overlap**, **text-only-slide**,
+**low-contrast-text**, **placeholder-text** (替换为…/占位/在这里写/Lorem left in a
+slide) and **font-mismatch** (CJK in a Latin-only font → 豆腐; language defaults to
+the system locale, override with `TALOS_DECK_LANG`). **Fix every finding before
+anything else** — they are objective and free, so they must never reach the
+vision pass or delivery. No separate `doc-validate` / `deck-qa` call is needed
+after a build.
 
 **The loop** (≤2 delivery rounds, then report residuals — never silently ship):
 
-1. **Fast authoring preview:** before generating the delivery PPTX, run
-   `html2pptx.cjs deck.html --preview-dir /tmp/deck-preview --style <id> ...`.
-   The first pass renders every slide; after a fix add `--preview-pages 3,7-8` to
-   capture only changed slides. Inspect and iterate on these HTML-faithful images.
-2. **Build + machine gates:** generate `deck.pptx`, then run Gate 1 and Gate 2 above.
-   Fix every objective finding before the expensive final render.
-3. **Final Office render:** once HTML preview and machine gates are clean, run
-   `doc-convert.cjs deck.pptx /tmp/deck.pdf --cache-dir /tmp/talos-office-cache` then
-   `pdf-render.cjs /tmp/deck.pdf all 1` → one PNG per slide. This happens once in
-   the normal path and verifies PPTX/Office-only drift; rerun it only after fixing
-   drift found in this final pass.
-   **Reading the previews is the single most token-expensive step in the whole
-   deck flow** (an image costs ≈ w×h∕750 tokens; a full-res 1280×720 slide ≈ 1.2k
-   each, ~15k for a 12-page deck — and you re-read every round). The trailing `1`
-   renders at ≈72dpi (¼ the pixels of the default `2`) — **≈¼ the vision tokens**,
-   and slide composition/color/hierarchy read fine at that size. Two ways to spend
-   even less: (a) Gates 1–2 are token-FREE — never send a slide to vision that a
-   machine already flagged; (b) use `--preview-pages` during HTML iteration and
-   read only changed slides. `pdf-render 3-3` saves PNG work but does **not** avoid
-   the whole-deck Office conversion, so reserve it for a genuine final-PPTX rerun.
-   Bump scale back to `2` only when fine print genuinely needs it.
-4. **Vision critic — the part only a model can do.** LOOK at every slide image
-   (not "glance"); **if sub-agent dispatch is available, critique slides in
-   parallel — one fresh-eyes agent per slide** (they catch what you, having
-   authored it, will not). Pass each critic the slide's `deck-qa` findings so it
-   does NOT re-report mechanical issues — it judges only what the machine can't:
-   visual balance / whitespace, hierarchy & focal point, a real visual anchor
-   (not a text wall), palette/motif consistency with the theme, image quality,
-   crowding/uneven gaps, misaligned sibling columns, decorative lines sized for
-   one-line text when the title wrapped, and any leftover placeholders Gate 2
-   can't phrase-match — unfilled `{{tokens}}`, "undefined", stray "xxx" (the
-   替换为/占位/在这里写/Lorem class is already caught mechanically in Gate 2, so
-   don't re-report those). Each critic returns **{slide, verdict: pass|fail,
+1. **Author against the HTML preview.** `html2pptx.cjs deck.html --preview-dir
+   <dir> --style <id> …` renders every slide the first time; after a fix,
+   `--preview-pages 3,7-8` renders only the changed ones. Read these images and
+   iterate until the composition is clean.
+2. **Build and fix the build's findings** (`html2pptx … deck.pptx`, see above).
+3. **Sign off once: `deck-qa.cjs deck.pptx --final`.** One call runs strict XSD
+   validation (a failure exits 1), the lint, an Office render (LibreOffice via
+   `doc-convert`, cached), and the render check: `render-overflow` (text Office
+   re-wrapped onto more lines than its box holds, or past its side) and
+   `render-collision` (text that grew out of its box onto another). It returns
+   `review` — the slides with such a finding or a native chart (Office draws
+   charts; the preview never showed them) — and `previews`, a ≈72dpi image of
+   each. **Read only `previews`.** Every other slide already passed your eyes in
+   the HTML preview, and in the default hybrid mode its visuals are baked from
+   that same render; Office only re-lays the native text, which was just
+   measured. Re-wrapping at a different word, spacing CJK and Latin apart or a
+   substituted Latin face is normal, not a defect.
+   - **Read every slide instead** (`pdf-render.cjs <deck>.office.pdf all 1`) when
+     `html2pptx` reported a `layout (fallback)` engine (no baked visuals, so the
+     preview no longer matches) or you changed the PPTX after building it
+     (`doc-xml`, `pptx-slide`, a script).
+   - `office.faithful: false` (no LibreOffice, only a Chromium reconstruction) or
+     `office.error`: there is no Office layout to check. The HTML preview stands;
+     say so when delivering.
+4. **Vision critic — the part only a model can do.** It judges the HTML preview
+   images (step 1) and the `previews` of step 3 — never a second full pass over
+   slides already judged. LOOK at every image you critique (not "glance").
+   **Either you critique a slide or a sub-agent does, not both:** with sub-agent
+   dispatch, hand slides to fresh-eyes critics in parallel and read their verdicts
+   instead of opening the images yourself. Give each critic the slide's findings
+   so it does NOT re-report them — it judges only what a machine can't: balance
+   and whitespace, hierarchy and focal point, a real visual anchor (not a text
+   wall), palette/motif consistency, image quality, crowding and uneven gaps,
+   misaligned sibling columns, decorative lines sized for one-line text when the
+   title wrapped, and leftovers the lint can't phrase-match (`{{tokens}}`,
+   "undefined", stray "xxx"). Each critic returns **{slide, verdict: pass|fail,
    defects:[…]}**.
-3. **Regenerate ONLY the failing slides** (targeted, not the whole deck):
-   - **doc-gen route** — edit that slide's spec object (swap archetype/variant,
-     move detail to notes, split overloaded content), re-run `doc-gen`.
-   - **html2pptx route** — re-author just that `<section>`'s HTML (author decks
-     one section per file so a slide regenerates in isolation), re-run
-     `html2pptx`; reassemble.
-   - **structural** — `pptx-slide` (dup/remove/reorder) or `pptx-clone` for
-     template-driven slides.
-4. **Re-run Gate 2 + render + critic on the regenerated slides only** — one fix
-   often creates another. Repeat until a full pass finds nothing new **or** 2
-   rounds elapse. If defects remain after round 2, **deliver with an explicit
-   note listing the residual issues** — do not present a flawed deck as finished.
-
-**Do not declare done before at least one complete gate→critic→fix cycle.**
+5. **Regenerate only the failing slides.** Re-author that `<section>` (one section
+   per file lets a slide rebuild in isolation) and rebuild, or use `pptx-slide`
+   (dup/remove/reorder) / `pptx-clone` for template-driven slides. Then preview
+   the changed slides, rebuild and run `--final` again — one fix often creates
+   another. Stop when a pass finds nothing new **or** after 2 rounds; if defects
+   remain, **deliver with an explicit note listing them**.
+
+**Reading images is the most token-expensive step of the deck flow** (≈ w×h∕750
+tokens each; a 1280×720 slide ≈ 1.2k). Preview and `--final` images are ≈72dpi,
+¼ of the default render; `pdf-render … 2` only when fine print must be legible.
+
+**Do not declare done before at least one complete build→sign-off→critic cycle.**
 
 ## CJK notes
 

package/skills/document/layouts/README.md

@@ -66,8 +66,10 @@ after touching a `.tpl`.
 让高度由内容决定：网格用 `grid-auto-rows:min-content`（下限必须显式写 `min-content` ——
 `1fr`/`auto` 的自动下限对 `overflow` 非 visible 的网格项一律归零），余量交给外层
 `justify-content:space-between`。这样内容超量时会把后续元素顶出页面，被 `deck-qa` 的
-`off-canvas`/`overlap` 抓到，而不是变成一排缺了下半截的字。`deck-qa` 的第三条硬失败
-`clipped` 专门守这件事，并且对**整册版式库**逐个版式扫，不只是 `sweep-spec.json` 里那几个。
+`off-canvas`/`overlap` 抓到，而不是变成一排缺了下半截的字。被祖先 `overflow:hidden`
+裁掉的文字不会出现在 pptx 的几何里，运行时的 `deck-qa` 看不到——它只在版式生产线的
+`scripts/deck/deck-qa-sweep.mjs`（`clipped` 硬失败，逐个版式扫整册库）里被拦截；写 bespoke
+页时请直接避免定高容器。
 
 ## Catalog
 
@@ -186,34 +188,3 @@ styles change their visual grammar without changing layout HTML.
 
 Adding a **Theme binding** = one entry in `theme-system.json`; adding a **layout** = one
 `layouts/<id>.tpl` plus a candidate role in `profiles.json`. Regenerate `slots.json`.
-
-## 反向通道 —— 包内版式如何进入共享库
-
-一个 `packs/<id>/` 可以带自己的专属版式（`packs/<id>/layouts/<id>.tpl`，与共享同名
-即遮蔽）。当包里做出来的某一页被证明**不是**包专属的装饰、而是别的族/包也会用得上
-的结构时，把它提升进这个共享库，而不是让每个包各自重复发明。
-
-**准入判据**（spec §7.3）：**剥掉所有颜色与 `font-family` 之后，它仍表达一个共享库
-没有的结构。** 是 → 提升；否（结构其实通用，专属感全靠色彩/字体/图形语汇撑）→ 留在
-包内，不要提升。
-
-跑 `node scripts/ppt-tpl/promote-layout.mjs <packId> <layoutId>`。它只机械校验"可
-提升"的必要条件（零硬编码色、不带私有 `font-family`、只用契约内 class、规范的
-1280×720 单 `section` + `data-layout`、至少一个可填槽位、`layouts/README.md` 表头
-格式没变）——**是不是结构性创新仍需人来判**，脚本不代劳。任一条不满足就拒绝写入
-（不移动文件），并逐条报出缺什么。
-
-校验通过后脚本会：把 `.tpl` 移到 `layouts/`、重跑 `scripts/deck/gen-slots.mjs` 重生成
-`slots.json`、在本文件的 Catalog 表格里插入一行占位（`role`/`structure`/`density`/
-`has-image`/`pick when` 均为 `TODO`，附 `promoted from packs/<packId>`）。写入中途
-任何一步失败都会整体回滚（删掉刚写的 `.tpl`，`slots.json`/本文件复原），不会留下
-半成品。
-
-提升不是终点，脚本打印的四步收尾都要做：补全本文件里那一行的全部 `TODO`、从
-`packs/<packId>/layouts/` 删掉原文件（否则同名遮蔽会让包永远看不到共享版本、也
-永远吃不到后续对共享版式的修复）、`node scripts/deck/deck-skin-samples.mjs && node
-scripts/deck/deck-fidelity.mjs` 确认它在所有皮肤下都成立、再跑
-`TALOS_TEST_SCOPE=unit npx vitest run tests/unit/deck-layouts.test.ts`。
-
-新版式若用到契约外的 class，先扩 `styles/_contract-defaults.css`（本脚本不代劳）——
-但只有 **≥3 个族/包各自独立地需要同一个新原语**时才扩，避免契约被单个包的口味撑肥。

package/skills/document/motion/README.md

@@ -4,8 +4,10 @@
 `deck-build` 填槽时按 role 注入 `data-anim*` / `data-transition*`；deck.html 里已有的
 同名属性优先，不被覆盖。
 
-**motion 是可选的** —— 没有预设文件的族不注入任何动画，与 `data-anim` 默认全关一致。
-23 个 entry 现在都配了（P0 有意留空以保证行为零变化，P2 补齐）。
+**`catalog.json` 的每个 entry 都配了预设**（33/33）。用不用由 spec 的 `scenario` 决定
+（`packages/core/src/document/deck-motion.ts::motionForDeck`）：演示型场景（pitch/路演/发布会/
+大会/讲座/销售）注入，阅读型场景（内审/评审/报告/汇报/讲义/培训/述职）不注入，未写或认不出
+的场景保持注入；`"motion": true|false` 显式覆盖。没有预设的族不注入任何动画。
 
 效果集必须与 `packages/core/src/document/pptx-anim.ts` 一致：
 fade · fade-up · float · appear · fly-up · fly-down · fly-left · fly-right

package/skills/document/office.md

@@ -10,7 +10,11 @@ prompt carries a `delivery="file"` pointer at that sidecar. So:
 
 ## What this skill IS for (Office)
 
-- **Generate / edit** .docx / .pptx → read **rewrite.md**, use `doc-gen`.
+- **Generate** a .docx → `doc-gen` (read **rewrite.md**); a deck → the deck path
+  (SKILL.md → deck-design.md; `doc-gen` makes no decks).
+- **Edit** an existing .docx / .pptx → **rewrite.md**: `doc-xml replace` for text,
+  `doc-fill` for `{{tokens}}`, `pptx-slide` / `pptx-clone` for slides,
+  `docx-annotate` for comments and tracked changes.
 - Everything visual (a diagram/chart that matters) → if you can see images, look
   at the original (see vision.md).