@taloswork/ose-shared 0.1.9 → 0.1.11

package/mcp/gen/mcp.json

@@ -12,9 +12,9 @@
         "TALOS_API_KEY": "${TALOS_GATEWAY_API_KEY}",
         "TALOS_GATEWAY_BASE_URL": "${TALOS_GATEWAY_BASE_URL}"
       },
-      "timeoutMs": 600000,
+      "timeoutMs": 720000,
       "connectTimeoutMs": 30000,
-      "supportsParallelToolCalls": false,
+      "supportsParallelToolCalls": true,
       "metadata": {
         "provides": "talos/gen",
         "title": "文生图/视频 · Talos 计费",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taloswork/ose-shared",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Talos cross-OSE shared library — skills + MCP servers auto-loaded into every OSE (P93 2026-07-27).",
   "type": "module",
   "files": [
@@ -10,6 +10,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "_talosPublishHash": "sha256-G225GKl7MFuGzmHVNTAmkcBmcOohJvs3RLcQOy4ffEo",
-  "_talosPublishedAt": "2026-09-21T07:29:20.819Z"
+  "_talosPublishHash": "sha256-JzD-VeYh0UJfwZYHueL8DpxlsjlDOEJGiSdOaX70yIg",
+  "_talosPublishedAt": "2026-09-28T08:42:12.912Z"
 }

package/skills/diagram-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: diagram-design
-description: Create branded architecture, IT current-state, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, radar/spider, loop/flywheel, nested, tree, org chart, layer stack, Venn, pyramid/funnel, bar, line, Gantt and scatter charts, high-level, process, medallion, data flow, DP integration, or DP security matrix diagrams as standalone HTML/SVG/PNG. Redraw .drawio/.drawio.png/.drawio.svg or Mermaid .mmd sources at a chosen size/detail; onboard brand tokens from a website; add semantic patterns, callouts, accessible motion, or sketchy/hand-drawn styling.
+description: Create branded architecture, data flow, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, radar, flywheel, tree, org chart, layer stack, Venn, pyramid/funnel, and bar/line/Gantt/scatter diagrams as standalone HTML/SVG/PNG. Also redraws .drawio or Mermaid sources, onboards brand tokens from a website, and adds callouts, motion or hand-drawn styling.
 license: MIT
 metadata:
   version: "2.3"

package/skills/document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document
-description: "Use this skill whenever a document attachment (PDF, .docx, .pptx, or .xlsx) is the input and the user wants it read, summarized, translated, searched, or its tables/formulas/figures interpreted — OR whenever the user asks to CREATE/GENERATE a document FILE (PDF, Word, PowerPoint, Excel) from scratch, edit an existing one, or CONVERT a document to another format (转成/转换/导出 PDF, .docx/.pptx → PDF, convert/export to PDF). For generating any document file ALWAYS use this skill's doc-gen script, and for docx/pptx→PDF conversion ALWAYS use its doc-convert script — never hand-write a python / ReportLab / LibreOffice / textutil / headless-browser pipeline for document output. Talos routes most inbound documents to local text extraction by default; reach for this skill's scripts for page rendering (formulas/scanned/figures), spreadsheet computation, document generation, or format conversion. Do NOT trigger for images (handled natively) or plain .txt/.md/.csv already inlined as text."
+description: "Use for document FILES. Reading: a PDF, .docx, .pptx or .xlsx attachment to read, summarize, translate or search when its pages must be rendered (formulas, scans, figures) or a sheet computed — others arrive as extracted text. Writing: any request to create or edit a Word, PowerPoint, Excel or PDF file, or convert one (转成/导出 PDF, .docx/.pptx → PDF). ALWAYS use its scripts — doc-gen (docs), html2pptx (decks, and a deck made here to PDF), doc-convert (an existing file to PDF); never hand-write a python/ReportLab/LibreOffice/browser pipeline. Do NOT trigger for images or plain .txt/.md/.csv."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
@@ -26,6 +26,14 @@ script only when:
   exact (don't do the arithmetic yourself).
 - **Formula / figure / scanned / exact layout matters** AND you can see images
   → read **vision.md**; `bin/pdf-render` a page, then look.
+- **A deck you built here, as PDF**(PPT 要 PDF / 导出 PDF / deck as PDF)→ print
+  its `deck.html` with the same STYLE flags you rendered the .pptx with (leave out
+  `--editable` / `--rasterize` / `--notes-doc`, which are .pptx-only):
+  `bin/html2pptx.cjs deck.html out.pdf --style <id> [--theme-v2 …] [--backdrop …]`.
+  One 16:9 page per slide, vector text (selectable, searchable), links clickable.
+  Do not route it through `doc-convert` (that re-lays out the .pptx) and never
+  assemble slide PNGs into a PDF (image pages: no text, no links). If the result
+  reports `pages` ≠ `slides`, a slide overflows its canvas — fix it and print again.
 - **Convert** a .docx/.pptx/.xlsx to PDF(转成/转换/导出 PDF / convert to PDF)→
   `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf>`. This is FAITHFUL conversion —
   the source's content, structure and images with neutral print styling; do not
@@ -39,6 +47,10 @@ script only when:
   template) → read **rewrite.md**, use `doc-gen` / `doc-fill`. **Always** produce
   document files via these scripts — never hand-write a python / ReportLab /
   LibreOffice script for document output.
+  **A length limit** (正文 1000 字以内 / under 800 words) is kept in the spec,
+  before generating: after a PDF, `doc-gen` prints `textChars` (spaces and URLs
+  not counted) — over the limit, shorten the spec and generate once more. Do not
+  extract text from the output to count it.
   **Any deck/presentation(路演/汇报/评审/宣讲/pitch/roadshow/介绍 PPT)**:
   **CLARIFY FIRST — HARD GATE (applies to EVERY deck).** Before authoring, collect
   three brief fields: **(1) content source** (提供材料 / 联网调研 / 自由创作);
@@ -117,53 +129,28 @@ script only when:
   Then render a cover+content sample of the result and confirm (same image-card step as
   a normal pick) before authoring; save the resulting preference to memory.
 
-  **THE deck method — html2pptx HYBRID with catalog-governed V1/V2 composition.**
-  Modern entries compose **Theme + component profile + media style + art direction +
-  content-selected layouts**; frozen `classic-v1` entries keep family paint only:
-  1. **Read deck-design.md** (⭐ PREFERRED workflow) + **`layouts/README.md`**
-     (every layout tagged role · structure · density · has-image; that index is
-     the source of truth for which layouts exist).
-  2. **Plan pages, pick layouts** from `layouts/profiles.json` by intent, then by
-     **P1/P2/P3** (structure → density → **≤2 dedup**;
-     `html2pptx` warns on repeats). Paste each `layouts/<id>.tpl` into `deck.html`
-     (they carry `data-layout`), fill REAL content — **never hardcode a brand hex**
-     (leave color to the skin; `html2pptx` warns on hardcoded colors). 8 roles:
-     cover/title/toc/section/transition/content/ending + special charts
-     (gantt/radar/funnel/ring/org-tree/map/data-table/stats-chart).
-     **A layout with a `{{#rows}}` block (gantt · radar · ring-progress ·
-     map-distribution · team-row · brand-values · color-palette · steps-vertical ·
-     toc-panel) must go through `deck-build`** — it repeats the block per row AND
-     computes the geometry (bar spans, ring arcs, pin positions, the radar chart)
-     from your numbers. Hand-pasting one leaves `{{#…}}` markers in the deck, or a
-     drawing that contradicts its own labels.
-     For Theme V2, keep each slide's semantic `intent`: `deck-build` uses it to derive
-     the `hero/content/data/media/closing` art scene and balance low/medium/high decoration
-     across the deck. Do not hand-assign every scene; override `scene` or `decorDensity`
-     only for a deliberate exception. `decorRhythm:"steady"` disables auto balancing.
-     For `classic-v1`, choose only pre-V2 layouts and omit scene/decor controls.
-  3. **Render:** modern entry → `bin/html2pptx.cjs deck.html out.pptx --style <id>
-     --theme-v2 [--media-style <id>] [--backdrop <variant>]`; frozen classic entry →
-     `bin/html2pptx.cjs deck.html out.pptx --style <id> [--backdrop <variant>]`.
-     DEFAULT hybrid (no `--editable`/`--rasterize`): pixel-perfect
-     visuals baked into a backdrop + native EDITABLE text and native `data-chart`
-     on top. Theme V2 injects the compatible V1 family paint plus semantic component,
-     media and art-direction layers; it never chooses a layout. Chromium gives the full CSS toolbox (Tailwind
-     + a `size="1".."7"` scale, gradients, shadows, per-element SVG, `<img>`
-     auto-inline, speaker notes) → NATIVE editable pptx.
-  **For a substantive deck, first read content-pipeline.md** (premium-deck method:
-  clarify + persist brief → research → narrative structure → one outline gate → author from
-  `layouts/` → fast HTML preview → final PPTX QA; premium density = rich VISUAL + sparse TEXT, details to
-  speaker notes). **Do NOT build a deck with `doc-gen pptx` archetypes or `doc-run`
-  PptxGenJS — those deck paths are OFF.** (html2pptx needs a browser: the app's
-  Chromium service or bundled Playwright; if neither, say so and stop — never
-  silently fall back to a lesser deck.) End with the mandatory hostile-review loop
-  (deck-design.md). *(The legacy `themes/*.json` + `--theme` recolor path is for
-  doc-gen DOCUMENTS; for decks use `--style` + `layouts/`.)*
-- **After ANY generated/edited file** (doc-gen / doc-fill / docx-annotate /
-  pptx-clone / doc-xml pack / hand-written scripts): run
-  `bin/doc-validate.cjs <file>` — exit 1 means fix it before delivering. Then
-  **render-and-look** at the output before delivery (see "Verify generated
-  output" below) — `doc-validate` proves well-formed, not good-looking.
+  **Then build it — the method lives in deck-design.md.** For a substantive deck read
+  **content-pipeline.md** first (brief → research → narrative → one outline gate), then
+  **deck-design.md** (workflow and delivery sign-off) and **`layouts/README.md`** (the
+  layout index and fill rules). In short: pick layouts from `layouts/profiles.json` by
+  slide intent; fill them with `deck-build` (required for any layout with a `{{#rows}}`
+  block — it computes the geometry; put the confirmed scenario in its spec as
+  `"scenario"` — read decks such as 内审/报告/培训 then get no animation); render with `bin/html2pptx.cjs deck.html out.pptx
+  --style <id>` (+ `--theme-v2` for modern entries, never for `classic-v1`) — DEFAULT
+  hybrid: baked visuals, native editable text. `doc-gen` makes no decks and the doc-run
+  PptxGenJS deck path is OFF. html2pptx needs a browser (the app's Chromium or bundled
+  Playwright); without one, say so and stop — never fall back to a lesser deck.
+- **Generators check their own output.** `doc-gen` and `html2pptx` report
+  validity in the step that wrote the file — `valid: false` exits 1, fix before
+  delivering; never re-run `doc-validate` on their output. `doc-gen pdf` prints
+  `{valid, pages, textChars, cjkChars, previews}` (a ≈72dpi PNG per page — read
+  those, do not re-render or count characters yourself); `doc-gen docx` prints
+  `{valid, textChars, cjkChars}`, `xlsx` `{valid}`; `html2pptx` adds `valid` and
+  `qa` (deck-qa's findings) to its result. **After any other edit** (doc-fill /
+  docx-annotate / pptx-clone / pptx-slide / doc-xml pack / hand-written scripts)
+  run `bin/doc-validate.cjs <file>` yourself — exit 1 means fix it. Valid is not
+  good-looking: **render-and-look** before delivery (see "Verify generated
+  output" below; decks sign off with `deck-qa --final`).
 - **Raw XML edit** (when no targeted tool fits): `doc-xml unpack` → edit →
   `doc-xml pack` → `doc-validate` (see rewrite.md "Raw XML editing").
 - **PDF** whose inlined text is garbled/missing where the answer should be →
@@ -204,39 +191,40 @@ Fidelity-decision self-correct, but pointed at your OWN output:
    blank CJK** (a missing-font symptom, not a content bug); colliding
    headers/footers; leftover `{{tokens}}` / "lorem" / "undefined".
 3. **Fix → re-render the affected pages.** One fix often creates another; repeat
-   until a clean pass. Scale rigor to the artifact: a one-page memo = one look; a
+   until a clean pass. Fix what is broken — clipped, overlapping, unreadable, tofu —
+   not how full a page looks: unless the user asked for a page count, never
+   resize fonts, line height or margins to fill a short last page or squeeze onto
+   fewer pages. Page breaks already keep a heading with its text and never strand
+   a single line, so a heading near a page edge is not something to fix. Layout and styling taste gets at most
+   TWO fix rounds: after the second, deliver and name what is still imperfect instead
+   of regenerating again. Scale rigor to the artifact: a one-page memo = one look; a
    multi-page report/deck = every page, ideally a sub-agent for fresh eyes.
 4. **Vision unavailable**: say so and rely on `doc-validate` + a text re-extract
    (`doc-text`) as a weaker proxy — never claim the layout is verified.
 
 ## Scripts (run via bash; output returns to context, the script itself does not)
 
-- `bin/doc-scan.cjs <file.pdf>` — per-page signals as JSON.
-- `bin/doc-text.cjs <file.pdf>` — extract a PDF's text layer.
-- `bin/pdf-render.cjs <file.pdf> <pages|all> [scale]` — render pages to PNG for vision (`pages` = `3` | `2-5` | `all`). `scale` (default `2` ≈ 144dpi) trades resolution for vision tokens: pass `1` (≈72dpi, ¼ the pixels ≈ ¼ the tokens) for slide-composition/layout QA; keep `2` when fine print must stay legible (formulas/tables). Reading previews is the priciest step in the deck loop — render cheap + read only what changed.
-- `bin/pdf-images.cjs <file.pdf> [pages]` — extract EMBEDDED images at native resolution with page placement (`pages` = `N` | `N-M` | `all`, default all). Prints a JSON manifest (page/index/bbox/size/path). Use this — not a full-page `pdf-render` — when you need the original figures/photos as their own files (e.g. rebuilding a deck). Vector/text-only pages yield nothing → fall back to `pdf-render`.
-- `bin/pdf-tables.cjs <file.pdf> [page] [minCols]` — recover text-layer tables as rows (ruled/scanned tables need render + vision instead).
-- `bin/ocr.cjs <image.png|jpg> [lang]` — read text off a scanned image (tesseract.js). For a scanned PDF, `pdf-render` a page first, then OCR the PNG. Language data downloads on first use / set `$TALOS_TESSDATA` for offline. **Prefer vision** when a vision model is available; OCR is the text-only fallback.
-- `bin/xlsx-query.cjs <file> [--summary | --agg <sheet> <col> <op> | --sample <sheet> [n]]` — spreadsheet compute.
-- `bin/doc-gen.cjs <docx|xlsx|pptx|pdf> <out> <spec.json> [--theme <theme.json>] [--topic <subject> | --palette <id>] [--design native|html]` — generate documents from scratch. DOCX/PDF body fields are exactly `paragraphs` and/or `blocks` (never `sections`); unknown fields and empty bodies fail with `DOC_SPEC_INVALID` before any output is written (`allowCoverOnly:true` is the explicit title-only opt-in). Correct the reported JSON path and rerun. `--theme` applies a presentation theme (colors/fonts/cover/header/footer/pptx master — see rewrite.md "Themes"; built-ins in `themes/`). **`--topic <subject>` (pptx, when no `--theme`) picks a topic-adaptive palette** so the deck is designed-for-subject instead of template-flat, and turns on richness (motif + gradient wash + depth). `--palette <id>` forces a specific palette (`doc-gen --list-palettes` prints them). **`--accent <#hex>` / `--style <skin>` (docx/pdf)**: white-paper-black-text base with ONE brand color on H1/H2 + a faint table-header tint — the practical doc shape (a document is read/printed/edited, not projected, so body text stays near-black). `--accent` takes a literal hex; `--style <skin>` pulls just the `--accent` from `styles/<skin>/skin.css` (the deck skin's full palette is NOT carried onto paper). Precedence: `--theme` > spec `"theme"` > `--accent`/`--style` > `--palette`/`--topic` > default. `--design html` (pptx only, in-app) renders eligible slides through designed HTML templates for a magazine look — richer but a flat collage (no master structure); auto-falls back to native when headless or a slide has no template. Default `native` (structured, editable, charts, headless-safe).
-- `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf> [--cache-dir <dir>]` — faithful docx/pptx/xlsx → PDF conversion. Engine precedence (best fidelity first, each downgrade tagged on stdout `[pdf (…)]` + warned on stderr): (1) **LibreOffice** if a system `soffice` is found — true layout render (page geometry, headers/footers, text-box positions, native charts), offline; (2) **LibreOffice sidecar** if `TALOS_OFFICE_URL` is set — same true-layout fidelity via a remote converter (e.g. Gotenberg), needs network; (3) **Chromium** (in-app) — reconstructed HTML, content/structure/images preserved but in-document layout is not (pptx = one page per slide); (4) **pdf-lib text-only** headless last resort — images/tables flatten. `--cache-dir` (or `TALOS_OFFICE_CACHE_DIR`) reuses a content-hashed local LibreOffice result for the exact same immutable artifact; caching is opt-in so document bytes are not retained by default. Surface the resulting `[pdf (engine)]` caveat to the user. NOTE: spreadsheets (xlsx/xls/ods) render ONLY via tiers 1–2 (real LibreOffice); tiers 3–4 do not rebuild spreadsheets, so with no LibreOffice available the command errors (never a degraded text-only sheet).
-- `bin/doc-validate.cjs <file.docx|pptx|xlsx> [--strict] [--design-lint]` — structural OOXML validation gate (zip/parts/rels/Content_Types/XML well-formedness); run after every generation or edit; exit 1 = broken, fix before delivering. `--strict` adds full ECMA-376 schema (XSD) validation of every recognised part — REQUIRED after custom-code (doc-run/html2pptx) or raw-XML output; a strict failure means the file is non-standard even if Office opens it. `--design-lint` (pptx only) adds an ADVISORY design pass — flags `text-only-slide` (a wall of text with no visual anchor), `low-contrast-text`, `placeholder-text` (a layout pasted but never filled — 替换为…/占位/Lorem still in the slide), `font-mismatch` (CJK text set in a Latin-only font → 豆腐; expected language defaults to the system locale, override with `TALOS_DECK_LANG`), `off-canvas`, `tiny-font`, `shape-overlap`; findings are warnings (never change the exit code) but are real design bugs — fix them. See deck-design.md "Design principles".
-- `bin/deck-qa.cjs <file.pptx> [--json]` — MECHANICAL design QA (deterministic, token-free): reads slide XML and flags `off-canvas` (content clipped past the edge), `tiny-font` (<10pt), `shape-overlap` (colliding text), plus `text-only-slide` / `low-contrast-text` / `placeholder-text` / `font-mismatch` (CJK text in a Latin-only font → 豆腐). Advisory (exit 0 even with findings). `--json` → `{ok,findings:[{slide,code,message}]}` for the visual-QA loop. It is the CHEAP GATE before spending vision tokens — run it every QA round and fix all findings first; then do the vision critic + per-slide regeneration (deck-design.md "Verify before delivering").
-- `bin/doc-xml.cjs unpack <file> <dir>` / `pack <dir> <out>` — raw-XML escape hatch (pretty-printed unpack → edit → repack); always doc-validate afterwards. `replace <in.docx> <out.docx> <find> <replacement>` — cross-run character-offset replace (finds text even when Word split it over runs, preserves formatting; covers body + headers/footers) — try this FIRST for plain text edits before unpacking. `merge-runs <in.docx> <out.docx>` repairs run fragmentation when you do need manual XML edits.
-- `bin/pptx-clone.cjs <template.pptx> <slideNo> <out.pptx> [replacements.json]` — clone a styled template slide once per data item, replacing `{{tokens}}` in the clone only (tokens split across runs are still found); `pptx-clone remove <in> <slideNo> <out>` drops a slide (e.g. the leftover token template). CAPACITY warnings on stderr mean the text likely overflows its slot — shorten the wording, never shrink the font. See rewrite.md.
-- `bin/pptx-slide.cjs add <in.pptx> <out.pptx> [--layout N]` / `dup <in> <slideNo> <out>` / `remove <in> <slideNo> <out>` / `reorder <in> <order> <out>` — slide-lifecycle surgery on an EXISTING deck WITHOUT a `{{token}}` template: append a blank slide bound to a layout (inherits the deck's master/theme), duplicate or drop a slide, or permute deck order (`pptx-slide reorder in.pptx 3,1,2 out.pptx` — comma-list of current 1-based positions in the new sequence). Lossless & structural — parts/rels/Content_Types are bookkept for you, but in-slide TEXT/content edits still go through doc-xml. Always doc-validate.
-- `bin/pptx-embed-fonts.cjs <in.pptx> <out.pptx> --font "<Typeface>=<path.ttf>" [--bold …] [--italic …]` — EMBED fonts into a deck (OOXML font embedding) so it looks identical on a machine lacking the font. Full-font embed → use for SMALL custom/brand fonts; NOT big CJK fonts (openers have system CJK, and the file would balloon). `<Typeface>` must match the deck's text-run font name. doc-validate after.
-- `bin/pptx-theme.cjs <ref.pptx> [out.json]` — extract a theme.json (palette/fonts/sizes) from an existing deck, then `doc-gen --theme` it: new content in that deck's look. Palette only — reusing actual layouts is pptx-clone/doc-fill territory.
-- `bin/doc-fill.cjs <template.docx|pptx|xlsx> <values.json> <out>` — fill `{{placeholders}}` in an existing template, preserving its styling (see rewrite.md).
-- `bin/pptx-tokenize.cjs <user.pptx> <template.pptx> [schema.json]` — turn a user's UPLOADED deck into a reusable `{{token}}` template: keeps its exact layouts/master/brand, replaces each content slot's text with a clean single-run token, and emits a `schema.json` cataloging every token (slide/role/type/multiline/original/capacity). Plain text boxes (no `<p:ph>`) are tokenized too. Then `doc-fill` it — fill EVERY token (pass `original` for slots you keep, else they blank). The B2 "reuse their layout" path; see rewrite.md.
-- `bin/pptx-set-image.cjs <in.pptx> <slideNo> <rId> <image> <out.pptx>` — swap the picture behind a slide's `rId` (from pptx-tokenize's image tokens) with a new image, keeping the frame (position/size) put. add-and-repoint (old media orphaned). Aspect-mismatch STRETCHES — pre-crop to the slot ratio. Always doc-validate.
-- `bin/docx-annotate.cjs comment <in.docx> <out.docx> <comments.json>` / `suggest <in.docx> <out.docx> <author> <text>` / `accept <in.docx> <out.docx>` / `redline-check <original.docx> <edited.docx>` — add Word comments (paragraph-anchored, threaded replies via `replyTo`), a tracked insertion (reviewer suggestion), accept ALL tracked changes, or PROVE an edited file changed nothing outside tracked changes (run after every redline edit; non-zero exit = an untracked content change slipped in).
-- `bin/pdf-form.cjs list <in.pdf>` / `fill <in.pdf> <values.json> <out.pdf> [--flatten]` / `overlay <filled.pdf> <out.pdf>` — inspect/fill PDF forms; `overlay` boxes every field in red for a render-and-look fill check (see pdf.md).
-- `bin/pdf-ops.cjs merge <out> <in…>` / `split <in> <from-to> <out>` / `rotate <in> <deg> <out> [pages]` / `watermark <in> <text> <out>` / `encrypt <in> <out> <user-pw> [owner-pw]` / `decrypt <in> <pw> <out>` — PDF page ops + AES-256 password protection.
-- `bin/xlsx-recalc.cjs <in.xlsx> <out.xlsx>` — re-evaluate all formulas (HyperFormula) and cache the results, keeping the formulas. Use when a spreadsheet's formula cells show stale/blank values.
-- `bin/doc-run.cjs <script.js> [args…]` — run a custom Node script with the engine's libraries bundled in (`require("pptxgenjs"|"docx"|"xlsx"|"pdf-lib"|"jszip"|"pizzip"|"hyperformula")` guaranteed on any machine; `--list` prints the registry). The long-tail escape hatch when no verb fits — see rewrite.md "Custom scripts"; ALWAYS doc-validate the output.
-- `bin/html2pptx.cjs <deck.html|snapshot.layout.json> [out.pptx] [--style <id>] [--theme-v2] [--media-style <id>] [--backdrop <variant>] [--editable] [--rasterize] [--preview-dir <dir>] [--preview-pages <all|N,N-M>]` — **THE deck path**: write slide HTML (`<section class="slide" data-layout="…">` on a 1280×720 canvas), Chromium lays it out → NATIVE editable pptx. `--preview-dir` is a preview-only fast path that writes slide PNGs directly from the styled HTML and skips PPTX/LibreOffice; use all pages once, then `--preview-pages` for changed pages. `--theme-v2` composes the selected family's existing paint with its semantic component profile, default media style and bound art direction; `--media-style` overrides only the media treatment. Entries in a `classic-v1` catalog collection reject both flags; omit them for the frozen V1 path. `--backdrop <variant>` picks a signature backdrop. **DEFAULT = hybrid**: each slide's visuals bake into a full-fidelity raster backdrop with native EDITABLE text on top; auto-falls back to plain native if backdrop capture is unavailable. `--editable` = plain native only (effects flatten). `--rasterize` = full image slides (ZERO editability — tell the user). Advisory warnings on hardcoded brand colors + repeated layouts (P3). Runs in the app's Chromium OR bundled headless Chromium (Playwright) — works off-app (CI/cloud); layout JSON works anywhere. **Tailwind + `size="1".."7"` scale available** (vendored offline). See theme-system.md + deck-design.md + layouts/README.md. `[--theme <theme.json>]` is a separate legacy document recolor path.
-- `bin/deck-build.cjs <spec.json> <deck.html>` — **THE FAST deck path** for catalog slides: emit a COMPACT spec with `style`, independent `layoutPack`, and per-slide `intent` + `layout` + content. Modern entries add `themeVersion:2` plus optional `mediaStyle`/`decorRhythm`; frozen `classic-v1` entries must omit those fields and use only pre-V2 layouts. Use `layouts/profiles.json` to match content intent before selecting geometry; under V2 the same intent derives the art scene and deck-level decoration rhythm. The CLI warns on an intent/layout mismatch and errors on an unknown intent. `layoutPack:"none"` forces shared layouts; omitting `layoutPack` preserves the old behavior where a `kind:"pack"` style implicitly uses its same-name layouts. `slots`, `rows`, and `chart` are still validated against `layouts/slots.json`; any unknown layout/slot/field or missing figure input exits 1 and writes nothing. See theme-system.md for the full schema and compatibility contract.
+One line each — **read a bin's entry in `bin-reference.md` before its first use**
+(flags, output shape, exit codes, gotchas). Do not read, grep or open `bin/*.cjs`
+themselves — they are bundled builds; the answer is in `bin-reference.md`.
+
+- Read: `bin/doc-scan.cjs <file.pdf>` page signals · `bin/doc-text.cjs <file.pdf>` text layer ·
+  `bin/pdf-render.cjs <file.pdf> <N|N-M|3,7-8|all> [scale]` pages → PNG (scale `1` ≈72dpi for layout) ·
+  `bin/pdf-images.cjs` embedded images · `bin/pdf-tables.cjs` text-layer tables ·
+  `bin/ocr.cjs <image> [lang]` · `bin/xlsx-query.cjs <file> --summary|--agg|--sample` exact spreadsheet compute.
+- Generate: `bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json>` (self-checks) ·
+  `bin/doc-run.cjs <script.js>` custom script with the bundled libraries ·
+  `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf>` faithful → PDF.
+- Decks: `bin/deck-build.cjs <spec.json> <deck.html>` catalog slides from a compact spec ·
+  `bin/html2pptx.cjs <deck.html> <out.pptx> --style <id> …` THE deck path (self-checks; `--preview-dir` for fast previews) ·
+  `bin/deck-qa.cjs <deck.pptx> [--json | --final]` lint, and the one-call delivery sign-off.
+- Edit: `bin/doc-fill.cjs` fill `{{tokens}}` · `bin/doc-xml.cjs unpack|pack|replace|merge-runs` raw XML ·
+  `bin/pptx-slide.cjs add|dup|remove|reorder` · `bin/pptx-clone.cjs` clone a template slide per item ·
+  `bin/pptx-tokenize.cjs` uploaded deck → template · `bin/pptx-set-image.cjs` · `bin/pptx-theme.cjs` palette from a deck ·
+  `bin/pptx-embed-fonts.cjs` · `bin/docx-annotate.cjs comment|suggest|accept|redline-check` ·
+  `bin/xlsx-recalc.cjs` recompute formulas.
+- Validate: `bin/doc-validate.cjs <file.docx|pptx|xlsx|pdf> [--strict]` — for anything a generator did not already check.
+- PDF: `bin/pdf-form.cjs list|fill|overlay` · `bin/pdf-ops.cjs merge|split|rotate|watermark|stamp|encrypt|decrypt`.
 
 All scripts are Node and print a machine-readable result plus a human note. On a
 missing dependency or unreadable file they exit non-zero with a clear message —

package/skills/document/bin/deck-build.cjs

@@ -686,6 +686,52 @@ function applyMotion(html, layoutId, preset) {
   }
   return out;
 }
+var STAGE_SCENARIOS = [
+  "pitch",
+  "\u8DEF\u6F14",
+  "\u53D1\u5E03\u4F1A",
+  "launch",
+  "keynote",
+  "\u4E3B\u9898\u6F14\u8BB2",
+  "\u5927\u4F1A",
+  "conference",
+  "\u8BB2\u5EA7",
+  "lecture",
+  "talk",
+  "\u9500\u552E",
+  "sales"
+];
+var READ_SCENARIOS = [
+  "\u5185\u5BA1",
+  "\u8BC4\u5BA1",
+  "review",
+  "\u62A5\u544A",
+  "\u6C47\u62A5",
+  "report",
+  "\u8BB2\u4E49",
+  "handout",
+  "\u57F9\u8BAD",
+  "training",
+  "\u8FF0\u804C",
+  "\u5468\u62A5",
+  "\u6708\u62A5"
+];
+function motionForDeck(spec) {
+  if (typeof spec.motion === "boolean") {
+    return { on: spec.motion, reason: `motion: ${spec.motion} in the spec` };
+  }
+  const scenario = typeof spec.scenario === "string" ? spec.scenario.trim() : "";
+  if (!scenario)
+    return { on: true, reason: "no scenario in the spec \u2014 the family preset applies" };
+  const s = scenario.toLowerCase();
+  const read = READ_SCENARIOS.find((k) => s.includes(k));
+  if (read)
+    return { on: false, reason: `scenario "${scenario}" is read, not watched \u2014 the family preset is off` };
+  const stage = STAGE_SCENARIOS.find((k) => s.includes(k));
+  if (stage)
+    return { on: true, reason: `scenario "${scenario}" is presented \u2014 the family preset applies` };
+  return { on: true, reason: `scenario "${scenario}" is not one motion knows \u2014 the family preset applies; set motion:false to drop it` };
+}
 
 // apps/admin/data/skills.lib/document/bin-src/deck-build.mjs
 function die(msg, code = 1) {
@@ -711,6 +757,8 @@ async function main() {
     die("mediaStyle must be a string and requires themeVersion: 2", 64);
   }
   if (spec?.layoutPack !== void 0 && typeof spec.layoutPack !== "string") die('layoutPack must be a pack id or "none"', 64);
+  if (spec?.scenario !== void 0 && typeof spec.scenario !== "string") die('scenario must be a string (the confirmed scenario, e.g. "\u5185\u5BA1" or "\u53D1\u5E03\u4F1A")', 64);
+  if (spec?.motion !== void 0 && typeof spec.motion !== "boolean") die("motion must be true or false", 64);
   if (spec?.decorRhythm !== void 0 && (spec.themeVersion !== 2 || !["auto", "steady"].includes(spec.decorRhythm))) {
     die("decorRhythm must be auto|steady and requires themeVersion: 2", 64);
   }
@@ -816,8 +864,9 @@ async function main() {
       );
     }
   }
+  const motion = motionForDeck(spec);
   let motionPreset = null;
-  if (catalogEntry?.motion) {
+  if (catalogEntry?.motion && motion.on) {
     const mp = (0, import_node_path.join)(skillDir, catalogEntry.motion);
     if (!(0, import_node_fs.existsSync)(mp)) die(`motion preset not found: ${catalogEntry.motion}`, 66);
     let raw;
@@ -848,6 +897,7 @@ async function main() {
     out: outPath,
     slides: Array.isArray(spec?.slides) ? spec.slides.length : 0,
     warnings,
+    motion: catalogEntry?.motion ? motion : { on: false, reason: "the family has no motion preset" },
     next: `html2pptx ${outPath} out.pptx${styleId ? ` --style ${styleId}` : " --style <skin>"}${spec?.themeVersion === 2 ? " --theme-v2" : ""}${spec?.mediaStyle ? ` --media-style ${spec.mediaStyle}` : ""}`
   }, null, 1) + "\n");
 }