@taloswork/ose-shared 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taloswork/ose-shared",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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-JzD-VeYh0UJfwZYHueL8DpxlsjlDOEJGiSdOaX70yIg",
-  "_talosPublishedAt": "2026-09-28T08:42:12.912Z"
+  "_talosPublishHash": "sha256-HbLb5fXPsWxwD1td2ljod1H_UVd555EmCpblxk4GZ2g",
+  "_talosPublishedAt": "2026-10-10T06:45:49.079Z"
 }

package/skills/document/SKILL.md

@@ -1,231 +1,147 @@
 ---
 name: document
-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."
+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), doc-convert (Office files and final decks 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
 ---
 
 # Document Handling
 
-Local-first, progressive-disclosure document processing. Prefer local text
-extraction (cheap, cross-vendor, avoids gateway size/timeout limits); escalate
-to page rendering only when the content is genuinely visual, and to native
-document delivery only when the user explicitly opts in (PDF only).
+Local-first, progressive disclosure: read the extracted text first, render pages only
+when the content is genuinely visual, and write files only through this skill's scripts.
 
 ## Route (read only what you need)
 
-This skill is for work the submit-time delivery does NOT do: PDF page rendering,
-spreadsheet computation, and document generation. **Attachments arrive as file
-pointers** — a `<document … delivery="file">` block gives you the on-disk path
-(PDF/Office point at a pre-extracted `<file>.txt` sidecar). **Read that file
-FIRST** (ordinary file/read tool — no script needed) before answering anything
-about the document's content; never guess from the filename. Then reach for a
-script only when:
-
-- **Spreadsheet** (.xlsx) computation — "sum/average/pivot/how many/总数/统计"
-  → read **xlsx.md**, use `bin/xlsx-query`. **Compute, do not dump** — and it is
-  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
-  re-theme, re-typeset or "优化排版" unless the user asks. **Never** hand-roll a
-  textutil / LibreOffice / python / headless-browser pipeline for this. xlsx/xls/
-  ods render ONLY through a real LibreOffice (local `soffice` or the
-  `TALOS_OFFICE_URL` sidecar) — there is no HTML/text-only fallback for
-  spreadsheets, so if neither is available the command errors instead of
-  degrading.
-- **Create or edit** a .docx/.pptx/.xlsx/.pdf (generate from scratch or fill a
-  template) → read **rewrite.md**, use `doc-gen` / `doc-fill`. **Always** produce
-  document files via these scripts — never hand-write a python / ReportLab /
+**Attachments arrive as file pointers** — a `<document … delivery="file">` block gives
+the on-disk path (PDF/Office point at a pre-extracted `<file>.txt` sidecar). **Read that
+file FIRST** (ordinary read tool, no script) before answering anything about the
+document's content; never guess from the filename. Then:
+
+- **Read a docx/pptx** → the sidecar is the content; don't re-extract (**office.md**).
+- **Read a PDF** whose text is garbled/missing where the answer should be, or that needs
+  formulas, tables, figures or a scan read → **pdf.md** (scan → text or render; looking
+  at a page and the OCR fallback → **vision.md**).
+- **Spreadsheet** computation ("sum/average/how many/总数/统计") → **xlsx.md**,
+  `bin/xlsx-query`. **Compute, do not dump** — it is exact; don't do the arithmetic yourself.
+- **Create, fill or edit** a .docx/.xlsx/.pdf (or edit an existing .pptx: template fill,
+  slide surgery, comments/tracked changes) → **rewrite.md** — its index names the one
+  section your task needs. PDF forms, merge/split, stamp, encrypt → **pdf.md**. **Always**
+  produce document files via the 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** (提供材料 / 联网调研 / 自由创作);
-  **(2) scenario** (pitch / 内审 / 销售 / 讲座 / 发布会 / 培训 / 大会 — sets tone,
-  density, required sections); **(3) slide count.** Ask only for fields the user did
-  not already supply, in **ONE AskUserQuestion call with at most THREE questions**, and
-  wait for the answers. If all three are already known, do not ask them again.
-
-  **STYLE PICKER — ONE RESULT PER IMAGE, SCENARIO-RANKED.** After the scenario is
-  known, read the skill directory's **current `catalog.json` from disk immediately
-  before building the picker**. Never reuse a catalog listing from earlier conversation
-  context and never infer pack availability by scanning `packs/`. If the current catalog
-  cannot be read or parsed, stop and report that exact error instead of presenting stale
-  options.
-
-  Unless the user already named an entry id/name, supplied a template file, or explicitly
-  said **"无需展示模板，直接替我选定风格"**, send one single-question image-card picker:
-
-  - Rank **entries**, not groups, against the confirmed scenario and the user's requested
-    tone. Show at most 8 recommended entries. A scenario-matching `kind === "pack"` ranks
-    before matching skins; include at least one matching pack whenever one exists.
-  - Every image card maps to exactly one final entry and uses
-    `{ label: entry.kind === "pack" ? "PACK · " + entry.name_cn :
-    (entry 属于 renderMode === "classic-v1" 的 collection ? "经典 · " + entry.name_cn : entry.name_cn),
-    description: entry.oneliner, imagePath: <skill目录下entry.sample的绝对路径> }`.
-    Copy `entry.oneliner` verbatim. Never use `group.sample` in this default picker.
-  - Append `{ label: "查看全部风格", description: "一次查看全部模板" }`, then
-    `{ label: "使用我的模板文件", description: "复用现成 PPT 的版式/风格",
-    filePick: "file" }` as the final option.
-
-  **"按场景推荐/你推荐" means rank the cards and still ask.** It does NOT waive the
-  picker. Only the explicit no-picker wording above authorizes automatic selection.
-  Do not waive this gate because the deck is small or quick.
-
-  If the user chooses **查看全部风格**, immediately show **every current
-  `catalog.entries` item in one single-question image-card picker** using the same label,
-  description, and imagePath rule above. Preserve catalog order, keep `PACK ·` visible,
-  and append the custom-template file card. Do not ask for a group, paginate, or return to
-  any category/second-level picker; the browse-all action must expose final selectable
-  templates directly.
-
-  Samples are pre-rendered WebP files shipped with the skill: pass their absolute paths
-  directly and do not render anything during the question. The selected `entry.id` is the
-  stable `style` id. Resolve the selected entry against `catalog.collections` before writing
-  the spec. Entries in a `renderMode:"classic-v1"` collection are frozen: omit
-  `themeVersion`, `mediaStyle`, `decorRhythm`, per-slide scene controls, and every layout in
-  `layouts/profiles.json.themeV2Layouts`; render them with `--style <id>` and never add
-  `--theme-v2`. All other newly authored decks use Theme V2 (`"themeVersion":2`), which
-  composes that family with its component profile, media treatment and art direction. Read
-  **theme-system.md** before authoring. The CLIs reject Theme V2 for frozen classic entries.
-
-  **Keep both calls LEAN.** The content/scenario/count questions use bare label strings,
-  no per-option descriptions; every question stem is one short sentence. Skip chat
-  preambles or keep one short line. Every question has the panel's implicit custom-text
-  escape. If the user responds with a correction or question, handle it and re-ask.
-
-  **Automatic choice, only when explicitly authorized:** rank by a remembered preference,
-  an exact user-named style, scenario match, a matching pack before a matching skin, then
-  `entry.mode` when the user asked for clean/formal/light/dark. Never hardcode a family id:
-  `catalog.json` is the only roster; `styles/README.md` is explanatory only. Never render
-  unstyled. After the user confirms, save the preference to memory.
-
-  **Custom style (user picked 其他/自定义 in the style picker)** — clarify which route, **prefer B
-  (derive a bespoke look)**:
-  - **B — derive a bespoke look (PREFERRED).** From an **existing deck**: `pptx-tokenize`
-    it to reuse its EXACT layouts/master/brand as a fillable template (rewrite.md B2),
-    OR `pptx-theme` to extract just its palette → paint OUR `layouts/`. From a
-    **reference image / brand color**: build a new `styles/<name>/skin.css` (sample the
-    palette → fill the class contract; see deck-design "build a skin from a reference
-    image"). *(A deck given here is for its STYLE — distinct from a deck given as
-    content, which is text-only; see content-pipeline's content-source choice.)*
-  - **A — map to the nearest of catalog 里的族** (they only described a vibe): pick the
-    closest, render its sample, confirm.
-  - **C — tweak an existing skin** ("刚才那个族但换绿色"): clone it, swap accent/palette or
-    flip light↔dark.
-  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.
-
-  **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 →
-  **pdf.md**: `bin/doc-text <file.pdf>` to re-extract, or render + look.
-- Just reading a docx/pptx/text → read the pointed-at file/sidecar directly;
-  don't re-extract with scripts (see **office.md**).
-
-## Fidelity decision (default text, escalate on evidence)
-
-1. `bin/doc-scan <file>` → cheap per-page signals (`textChars`, `imageCoverage`,
-   `mathHint`, `tableHint`, `scanned`). Costs nothing to the context beyond the
-   small JSON.
-2. Read intent: summarize/translate → text; formulas/tables/figures/layout →
-   visual; unsure → start with text.
-3. Per page: `scanned` OR high `imageCoverage` OR (visual intent AND
-   math/table hint) → render + look (vision.md); else `doc-text`.
-4. **Self-correct (important):** if the extracted text is garbled or missing
-   where the answer should be (symbols shredded for a formula, a table collapsed
-   into one line, a page with almost no characters) → render THAT page and look.
-5. **Vision unavailable** (text-only model): text/OCR only, and state the
-   limitation plainly — never silently return empty for a scanned/visual page.
-
-## Verify generated output (render-and-look — MANDATORY for delivery)
-
-Structural validation (`doc-validate`) proves the file is well-formed; it does
-NOT prove it *looks* right. Before delivering ANY document you generated or
-converted (doc-gen / doc-fill / doc-convert / doc-run / raw-XML / template fill),
-do a visual self-check — the same "assume there are problems" ethos as the
-Fidelity-decision self-correct, but pointed at your OWN output:
-
-1. **Render the final artifact to images** and LOOK at every page (not "glance"):
-   PDF → `bin/pdf-render.cjs <file.pdf> all`; docx/pptx → `bin/doc-convert.cjs
-   <file> /tmp/preview.pdf` then `pdf-render` the PDF. Decks follow the fuller
-   loop in **deck-design.md** ("Verify before delivering") — do that instead.
-2. **Hunt for render-level bugs** structural checks can't see: text overflowing
-   its box / cut off at the page edge; tables broken or collapsed; bad page
-   breaks (heading orphaned from its body, a row split mid-cell); **tofu / □ /
-   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. Fix what is broken — clipped, overlapping, unreadable, tofu —
-   not how full a page looks: unless the user asked for a page count, never
+- **Convert** a .docx/.pptx/.xlsx to PDF(转成/导出 PDF)→ `bin/doc-convert.cjs <in> <out.pdf>`.
+  Preserve the source; do not re-theme or "优化排版" unless asked, and never hand-roll a textutil /
+  LibreOffice / headless-browser pipeline. PPTX and spreadsheets render ONLY through a real
+  LibreOffice (local `soffice` or `TALOS_OFFICE_URL`); without one the command errors.
+  DOCX may fall back to HTML reconstruction; report that its layout can change.
+- **A deck you built here, as PDF**(PPT 要 PDF)→ `bin/doc-convert.cjs deck.pptx out.pdf`.
+  The final PPTX is the source of truth for content, fonts and layout. Reuse its final
+  QA Office PDF only if the PPTX has not changed. Never print `deck.html` or assemble
+  preview PNGs as the delivered PDF. No Office engine → report that PDF export is unavailable.
+- **Any deck/presentation(路演/汇报/评审/宣讲/pitch/roadshow/介绍 PPT)** → the deck route below.
+
+## Decks
+
+**CLARIFY FIRST — HARD GATE (applies to EVERY deck).** Before authoring, collect three
+brief fields: **(1) content source** (提供材料 / 联网调研 / 自由创作); **(2) scenario**
+(pitch / 内审 / 销售 / 讲座 / 发布会 / 培训 / 大会 — sets tone, density, required sections);
+**(3) slide count.** Ask only for fields the user did not already supply, in **ONE
+AskUserQuestion call with at most THREE questions**, and wait for the answers. If all
+three are already known, do not ask them again.
+
+**STYLE PICKER — ONE RESULT PER IMAGE, SCENARIO-RANKED.** After the scenario is
+known, run `node <skill>/bin/deck-styles.cjs --scenario "<the confirmed scenario>"`: it
+reads the current `catalog.json` from disk immediately and ranks the entries (a
+scenario-matching pack first, at least six cards). Never rank from memory, reuse a listing
+from earlier context or scan `packs/`. If it exits non-zero, stop and report that exact
+error instead of presenting stale options.
+
+Unless the user already named an entry id/name, supplied a template file, or explicitly
+said **"无需展示模板，直接替我选定风格"**, send one single-question image-card picker whose
+`options` are deck-styles' `options` **as printed** — never rewrite, reorder or add a card.
+
+**"按场景推荐/你推荐" means rank the cards and still ask.** It does NOT waive the
+picker. Only the explicit no-picker wording above authorizes automatic selection.
+Do not waive this gate because the deck is small or quick.
+
+**查看全部风格** opens the full gallery in the app itself — you receive the final pick, not
+the click. Only if 查看全部风格 comes back as the answer, show **every current
+  `catalog.entries` item in one single-question image-card picker** in catalog order:
+`{ label: "PACK · " + entry.name_cn` for a pack, `"经典 · " + entry.name_cn` in a
+`classic-v1` collection, else `entry.name_cn`; `description: entry.oneliner, imagePath:
+"document:" + entry.sample }`, then the template card. Do not ask for a group, paginate, or return to
+  any category/second-level picker.
+
+The selected `entry.id` is the stable
+`style` id. An entry in a `renderMode:"classic-v1"` collection of `catalog.collections`
+renders V1 (no `themeVersion`, never `--theme-v2`); every other new deck uses Theme V2 —
+read **theme-system.md** before authoring.
+
+**Keep both calls LEAN:** bare label strings for the content/scenario/count questions,
+one short sentence per stem, no chat preamble beyond one line. If the user answers with
+a correction or question, handle it and re-ask.
+
+**Automatic choice, only when explicitly authorized:** rank by a remembered preference,
+an exact user-named style, scenario match, a matching pack before a matching skin, then
+`entry.mode` when the user asked for clean/formal/light/dark. Never hardcode a family id:
+`catalog.json` is the only roster. Never render unstyled. After the user confirms, save
+the preference to memory.
+
+**Custom style** (其他/自定义, 使用我的模板文件, "我之前那个风格"): routes and naming are in
+**deck-design.md "Custom skins"** — prefer deriving a bespoke skin, saved as a user style
+under `$TALOS_DOC_STYLES_DIR/styles/<name>/`; a 使用我的模板文件 deck is learned as a style
+(`template-skin`); refilling its original pages (opt-in) → rewrite.md "Reuse an
+uploaded deck". Never write inside the skill directory.
+
+**Then build it.** Read **content-pipeline.md** for a substantive deck, then
+**deck-design.md** and **`layouts/README.md`**. Assess whether generated visuals help;
+if so, read **generated-visuals.md**. In short:
+**plan before you fill** — `bin/deck-plan.cjs plan.json spec.json` picks layouts by
+MEASURED capacity and drafts the spec, `deck-build` fills it, charts are drawn from data
+(never hand-write chart SVG), and `bin/html2pptx.cjs deck.html out.pptx --style <id>`
+(+ `--theme-v2` unless the entry is classic-v1) renders it. `doc-gen` and doc-run
+PptxGenJS make no decks; html2pptx needs a browser — without one, say so and stop, never
+fall back to a lesser deck.
+
+## After writing a file (MANDATORY before delivery)
+
+1. **Valid.** `doc-gen` and `html2pptx` check their own output in the step that wrote
+   it — `valid: false` exits 1, fix before delivering;
+   never re-run `doc-validate` on their output. `doc-gen pdf` prints `{valid, pages, textChars, cjkChars, previews}`
+   (≈72dpi PNGs — read those, do not re-render). Counts describe input, not visible glyphs.
+   `doc-gen docx` prints `{valid, textChars, cjkChars}`, `xlsx` `{valid}`. After any
+   other write (doc-fill, docx-annotate, pptx-*, pdf-form / pdf-ops, doc-xml pack, a
+   doc-run script) run `bin/doc-validate.cjs <file>` yourself — exit 1 means fix it.
+2. **Looks right — render and LOOK at every page** (valid is not good-looking): a
+   doc-gen PDF → its `previews`; another PDF → `bin/pdf-render.cjs <file.pdf> all 1`;
+   docx/pptx/xlsx → `bin/doc-convert.cjs <file> preview.pdf` (working folder), then
+   `pdf-render` it. Decks follow deck-design.md "Verify before delivering" instead. Hunt
+   for text overflowing or cut off at the page edge, collapsed tables, a row split
+   mid-cell, **tofu / □ / blank CJK** (a missing font, not a content bug), colliding
+   headers/footers, leftover `{{tokens}}` / "lorem" / "undefined".
+3. **Fix → re-render the affected pages** and look at only those — never re-read a
+   page you already looked at. 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)
-
-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 —
-report that to the user, do not fabricate content.
+   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 taste gets at most
+   TWO fix rounds; then deliver and name what is still imperfect. A one-page memo = one
+   look; a long report = every page.
+4. **Vision unavailable**: say so, rely on `doc-validate` + a `doc-text` re-extract as a
+   weaker proxy, and never claim the layout is verified.
+
+## Scripts
+
+Run them with bash; **read a bin's entry in `bin-reference.md` before its first use** —
+its index at the top points at the one section your task needs (flags, output, exit
+codes). Never read or grep `bin/*.cjs` themselves: they are bundled builds.
+
+- Read: `bin/doc-scan.cjs` · `bin/doc-text.cjs` · `bin/pdf-render.cjs` · `bin/pdf-images.cjs` ·
+  `bin/pdf-tables.cjs` · `bin/ocr.cjs` · `bin/xlsx-query.cjs`
+- Generate: `bin/doc-gen.cjs` · `bin/doc-run.cjs` · `bin/xlsx-recalc.cjs`
+- Fill / edit: `bin/doc-fill.cjs` · `bin/doc-xml.cjs` · `bin/docx-annotate.cjs` · `bin/docx-defaults.cjs` · `bin/pptx-clone.cjs` ·
+  `bin/pptx-slide.cjs` · `bin/pptx-tokenize.cjs` · `bin/pptx-set-image.cjs` · `bin/pptx-notes.cjs` · `bin/pptx-theme.cjs` ·
+  `bin/pptx-embed-fonts.cjs` · `bin/pdf-form.cjs` · `bin/pdf-ops.cjs`
+- Decks: `bin/deck-scenario.cjs` · `bin/deck-styles.cjs` · `bin/deck-plan.cjs` · `bin/deck-build.cjs` · `bin/deck-chart.cjs` · `bin/html2pptx.cjs` · `bin/deck-qa.cjs` · `bin/template-skin.cjs`
+- Validate / convert: `bin/doc-validate.cjs <file.docx|pptx|xlsx|pdf> [--strict]` · `bin/doc-convert.cjs`
+
+Every script prints a machine-readable result. On a missing dependency or unreadable
+file it exits non-zero with a clear message — report that, never fabricate content.

package/skills/document/art-directions/base.css

@@ -1,7 +1,11 @@
 /* Theme V2 art-direction canvas. The renderer injects this decoration-only layer
-   into .slide-backdrop; V1 never receives the markup or these rules. */
-.theme-art-layer,.theme-art-layer>*{position:absolute;pointer-events:none}
+   into .slide-backdrop; V1 never receives the markup or these rules.
+   Markup: .theme-art-layer > .art-slot.art-slot-{a,b,c,pattern} > .art-{a,b,c,pattern}.
+   Each slot is a full-bleed, untransformed box, so a canvas-space mask on it stays
+   put while the shape inside it is rotated, scaled or moved. */
+.theme-art-layer,.theme-art-layer *{position:absolute;pointer-events:none}
 .theme-art-layer{inset:0;overflow:hidden}
+.theme-art-layer .art-slot{inset:0;display:block}
 .theme-art-layer .art-shape{display:block}
 
 /* Scene controls composition; density controls intensity. These selectors only
@@ -21,3 +25,24 @@
 [data-scene-variant="b"] .theme-art-layer .art-b{opacity:.82}
 [data-scene-variant="c"] .theme-art-layer .art-a{opacity:.18}
 [data-scene-variant="c"] .theme-art-layer .art-c{opacity:.86}
+
+/* Content safe zone. Every motif is composed for the open hero/cover canvas; on a
+   content layout the type, cards and charts fill x≈94–1196 · y≈128–655, so a corner
+   block at hero size lands on them. Each art direction therefore restates its hard
+   shapes for content layouts — shrunk back toward the canvas corner/edge they lean on
+   (`scale`/`translate` compose with a motif's own `transform`), never clipped.
+   The content selector is the same in every art-direction file (and in gen-skin's
+   signature rules); tests/unit/deck-decor-overlap.test.ts holds them to it:
+
+     .slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"])
+
+   Slides without data-layout (hand-written HTML) keep the hero composition.
+
+   Safety net: a slot listed by its art direction under the same selector gets
+   --decor-safe-mask, which clears the content box (x 94–1196 · y 128–654; matrix axis labels reach x≈1195) with a short feather outside it. Where
+   the retreat already keeps a shape out of the box the mask changes no pixel; it only
+   bites where a shape still reaches in. */
+.theme-art-layer,.sig-layer{
+  --decor-safe-mask:linear-gradient(90deg,black 80px,transparent 94px,transparent calc(100% - 84px),black calc(100% - 74px)),
+    linear-gradient(180deg,black 112px,transparent 128px,transparent calc(100% - 66px),black calc(100% - 58px));
+}

package/skills/document/art-directions/cinematic-depth.css

@@ -3,4 +3,6 @@
 .theme-art-layer .art-b{left:18%;top:-230px;width:260px;height:1120px;background:linear-gradient(180deg,color-mix(in srgb,var(--c3) 36%,transparent),transparent 78%);transform:rotate(-28deg);filter:blur(18px);opacity:.52}
 .theme-art-layer .art-c{right:84px;top:62px;width:210px;height:210px;border:1px solid var(--c1);border-radius:50%;box-shadow:0 0 0 28px color-mix(in srgb,var(--c1) 8%,transparent),0 0 70px color-mix(in srgb,var(--c2) 30%,transparent);opacity:.62}
 .theme-art-layer .art-pattern{inset:0;background:linear-gradient(180deg,transparent 64%,color-mix(in srgb,var(--title) 7%,transparent));opacity:.8}
-
+/* Content layouts — the floating ring shrinks into the top-right corner; the lights and beams stay. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:calc(100% + 84px) -62px;scale:.36}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-c){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/collage-paper.css

@@ -5,4 +5,8 @@
 .theme-art-layer .art-pattern{right:54px;bottom:44px;width:170px;height:120px;background:conic-gradient(from 90deg,color-mix(in srgb,var(--c1) 32%,transparent) 25%,transparent 0 50%,color-mix(in srgb,var(--c2) 28%,transparent) 0 75%,transparent 0);background-size:24px 24px;transform:rotate(3deg);opacity:.68}
 .component-grid>.component-card:nth-child(odd),.component-grid>.team-card:nth-child(odd){transform:rotate(-.45deg)}
 .component-grid>.component-card:nth-child(even),.component-grid>.team-card:nth-child(even){transform:rotate(.45deg)}
-
+/* Content layouts — the paper scraps and the checker swatch shrink into their corners; the tape strip already sits in the top margin. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-a{transform-origin:calc(100% - 40px) 52px;scale:.52}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:64px calc(100% - 52px);scale:.4}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-pattern{transform-origin:calc(100% + 54px) calc(100% + 44px);scale:.45}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-a,.art-slot-b,.art-slot-pattern){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/editorial-cut.css

@@ -5,4 +5,8 @@
 .theme-art-layer .art-pattern{right:44px;bottom:34px;width:220px;height:164px;border:1px solid var(--c1);background:repeating-linear-gradient(-45deg,transparent 0 11px,color-mix(in srgb,var(--c1) 14%,transparent) 11px 13px);opacity:.58}
 [data-layout="cover"] .theme-art-layer .art-a,[data-layout="section"] .theme-art-layer .art-a{width:40%;background:var(--c1);opacity:.9}
 .component-grid>.component-card:nth-child(even),.component-grid>.proof-card:nth-child(even){background:color-mix(in srgb,var(--c2) 9%,var(--cmp-surface))}
-
+/* Content layouts — the colour column narrows to the right margin (its gradient cap follows); the hatched plate shrinks into the bottom-right corner. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-a{width:74px}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{width:74px}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-pattern{transform-origin:calc(100% + 44px) calc(100% + 34px);scale:.4}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-a,.art-slot-b,.art-slot-pattern){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/geometric-pop.css

@@ -7,3 +7,9 @@
 .component-grid>.component-card:nth-child(4n+1),.component-grid>.feature-card:nth-child(4n+1){border-top:7px solid var(--c1)}
 .component-grid>.component-card:nth-child(4n+2),.component-grid>.feature-card:nth-child(4n+2){border-top:7px solid var(--c2)}
 .component-grid>.component-card:nth-child(4n+3),.component-grid>.feature-card:nth-child(4n+3){border-top:7px solid var(--c3)}
+/* Content layouts — the colour fields and the square ring shrink into the corners they are cropped by. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-a{transform-origin:calc(100% - 80px) calc(100% - 110px);scale:.28}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:70px calc(100% - 92px);scale:.45}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:calc(100% + 260px) calc(100% + 44px);scale:.22}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-a,.art-slot-b,.art-slot-c){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"])[data-layout="pitch-problem"] .theme-art-layer .art-a{transform-origin:calc(100% - 80px) 90px}

package/skills/document/art-directions/gradient-mesh.css

@@ -3,4 +3,8 @@
 .theme-art-layer .art-b{right:-110px;top:90px;width:380px;height:520px;border-radius:52% 0 0 52%;background:linear-gradient(150deg,color-mix(in srgb,var(--c2) 78%,transparent),color-mix(in srgb,var(--c4) 58%,transparent));opacity:.18;transform:rotate(8deg)}
 .theme-art-layer .art-c{left:58%;top:-160px;width:320px;height:320px;border:1px solid var(--c1);border-radius:50%;box-shadow:0 0 0 38px color-mix(in srgb,var(--c1) 8%,transparent),0 0 0 76px color-mix(in srgb,var(--c2) 6%,transparent);opacity:.45}
 .theme-art-layer .art-pattern{inset:0;background:linear-gradient(115deg,transparent 48%,color-mix(in srgb,var(--c1) 12%,transparent) 49%,transparent 51%);opacity:.6}
-
+/* Content layouts — the side blob retreats to the right edge; the rings shrink onto their centre on the top edge
+   (outer shadow ring ends at y≈106, above pitch eyebrows/headlines at x 600–1180 · y≥123); the mesh and the light stay. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:calc(100% - 110px) 50%;scale:.28}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:50% 50%;scale:.45}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-b,.art-slot-c){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/illustrated-doodle.css

@@ -6,3 +6,8 @@
 .component-grid>.component-card:nth-child(3n+1),.component-grid>.feature-card:nth-child(3n+1){background:color-mix(in srgb,var(--c1) 9%,var(--cmp-surface))}
 .component-grid>.component-card:nth-child(3n+2),.component-grid>.feature-card:nth-child(3n+2){background:color-mix(in srgb,var(--c2) 9%,var(--cmp-surface))}
 .component-grid>.component-card:nth-child(3n),.component-grid>.feature-card:nth-child(3n){background:color-mix(in srgb,var(--c3) 9%,var(--cmp-surface))}
+/* Content layouts — the blobs and the loop shrink into their corners. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-a{transform-origin:calc(100% - 95px) 76px;scale:.55}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:90px calc(100% - 90px);scale:.44}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:calc(100% + 210px) calc(100% + 58px);scale:.3}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-a,.art-slot-b,.art-slot-c){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/luxury-ornament.css

@@ -3,4 +3,7 @@
 .theme-art-layer .art-b{right:-150px;top:-150px;width:420px;height:420px;border:1px solid var(--c2);border-radius:50%;box-shadow:0 0 0 34px color-mix(in srgb,var(--c2) 7%,transparent),0 0 0 68px color-mix(in srgb,var(--c3) 5%,transparent);opacity:.46}
 .theme-art-layer .art-c{left:-120px;bottom:-120px;width:320px;height:320px;background:radial-gradient(circle,var(--c1) 0 2px,transparent 3px),conic-gradient(from 0deg,transparent 0 8deg,color-mix(in srgb,var(--c1) 18%,transparent) 8deg 10deg,transparent 10deg 20deg);border-radius:50%;opacity:.4}
 .theme-art-layer .art-pattern{right:50px;bottom:50px;width:180px;height:1px;background:linear-gradient(90deg,transparent,var(--c1),transparent);box-shadow:0 -8px 0 color-mix(in srgb,var(--c1) 22%,transparent),0 8px 0 color-mix(in srgb,var(--c1) 22%,transparent)}
-
+/* Content layouts — the corner rings and the ray ornament shrink into their corners; the frame stays. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:calc(100% - 150px) 150px;scale:.55}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:120px calc(100% - 120px);scale:.55}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-b,.art-slot-c){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/maximalist-blocks.css

@@ -7,3 +7,9 @@
 .component-grid>.component-card:nth-child(4n+2),.component-grid>.price-card:nth-child(4n+2){background:var(--c2)}
 .component-grid>.component-card:nth-child(4n+3),.component-grid>.price-card:nth-child(4n+3){background:var(--c3)}
 .component-grid>.component-card:nth-child(4n+4),.component-grid>.price-card:nth-child(4n+4){background:var(--c4)}
+/* Content layouts — the top slab already lives above the title; the floor slab, the shadowed card and the stripe swatch shrink into their corners.
+   The swatch stops above y≈56: pitch layouts put their eyebrow at x 80 · y 64. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:80px calc(100% - 78px);scale:.38}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:calc(100% + 36px) calc(100% + 48px);scale:.34}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-pattern{transform-origin:0 0;scale:.36}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-b,.art-slot-c,.art-slot-pattern){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}

package/skills/document/art-directions/technical-grid.css

@@ -4,3 +4,7 @@
 .theme-art-layer .art-c{right:76px;top:64px;width:122px;height:122px;border:1px solid var(--c1);box-shadow:26px 26px 0 color-mix(in srgb,var(--c2) 16%,transparent);opacity:.58}
 .theme-art-layer .art-pattern{left:36px;bottom:32px;width:300px;height:26px;background:repeating-linear-gradient(90deg,var(--c1) 0 2px,transparent 2px 18px);opacity:.32}
 .component-grid>.component-card,.component-grid>.metric-card{background:color-mix(in srgb,var(--slide-bg) 82%,transparent);backdrop-filter:blur(8px)}
+/* Content layouts — the modular zone and the node square shrink into their corners; grid and tick rail stay. */
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-b{transform-origin:100% 100%;scale:.2}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer .art-c{transform-origin:calc(100% + 76px) -64px;scale:.5}
+.slide[data-layout]:not([data-layout^="cover"],[data-layout^="section"],[data-layout^="title"],[data-layout^="ending"],[data-layout="hero"],[data-layout="transition"]) .theme-art-layer :is(.art-slot-b,.art-slot-c){-webkit-mask-image:var(--decor-safe-mask);mask-image:var(--decor-safe-mask)}