@taloswork/ose-shared 0.1.10 → 0.1.12

package/skills/document/rewrite.md

@@ -1,360 +1,293 @@
-# Generate / edit documents (L3)
+# Generate, fill and edit documents (L3)
 
-## Themes — the presentation layer for `doc-gen` DOCUMENTS (docx / pdf)
+**Read only the sections your task needs** (Read with the offset/limit of the line range):
 
-> **Decks use skins, not themes.** For an html2pptx deck (路演/汇报/pitch), pick a
-> **skin** via `--style` (`styles/README.md`, the SKILL deck route) — NOT a
-> `themes/*.json`. The `themes/` + `--theme` system below is for `doc-gen`
-> DOCUMENTS (Word/PDF reports) — a separate, still-valid path. `doc-gen` makes no
-> decks at all; `html2pptx --theme` reads a theme's colors/fonts and its three
-> slide colors (`pptx{background,titleColor,textColor}`).
+- New .docx / .pdf / .xlsx → **Generate** (lines 14–55); a formula in a workbook → also **Formulas** (lines 57–73); a particular look, theme or brand → also **Themes** (lines 75–125)
+- Fill a `{{placeholder}}` .docx / .pptx / .xlsx template → **Fill a template** (lines 127–146)
+- Change an existing .docx — text, structure, comments, tracked changes → **Edit an existing .docx** (lines 148–199)
+- New content in an existing deck's look, or restructure a .pptx → **Template decks** (lines 201–271)
+- Nothing above fits → **Custom scripts** (lines 273–293)
 
-Content (the spec) and presentation (the theme) are separate. A theme is a JSON
-file — template skills ship their own; this skill ships **12 built-ins** in `themes/`
-(theme = colors/fonts for `doc-gen` output; `themes/README.md` lists them with their
-best fit): `cool-tech` · `apple-keynote` · `mckinsey-consulting` · `anthropic-clay` ·
-`black-gold` · `hand-drawn` · `mono` · `warm-editorial` · `ivory-gold` · `cinereel` ·
-`magazine-ink` · `swiss-grid`. For a plain Word/PDF report, `mckinsey-consulting` (white · deep
-navy · structured tables) is a safe default; `mono` for a stark minimal look.
+A PDF's forms, page ops and stamps are in pdf.md; a deck from scratch is the deck route
+(SKILL.md) — `doc-gen` makes no decks. `<skill>` below is this skill's directory.
 
-```
-node <skill>/bin/doc-gen.cjs docx out.docx spec.json --theme <skill>/themes/mckinsey-consulting.json
-```
-
-**Topic-adaptive color (when the user hasn't named a theme/brand)**: pass
-`--topic "<subject>"` (or put `"topic"` in the spec). The engine picks a
-palette that FITS the subject — deterministically, by keyword then stable hash —
-instead of the same default every time (the #1 "AI-generated" tell). `--palette <id>` forces a
-named one; `doc-gen --list-palettes` prints the library. A `--theme` file or a
-saved/brand preference (step 1 below) still wins — use `--topic` for the "just
-make it look designed-for-this" case, not when the user has a look in mind.
-
-**Picking a theme with the user (preference → showcase → confirm → apply)**:
-
-1. **Preference first**: check your memory for a saved deck-theme preference
-   (记忆里的"deck 主题偏好") and `themes/custom/` for the user's own themes —
-   a remembered/custom theme wins over guessing; use it and SAY so ("按你常用的
-   X 主题,要换告诉我").
-2. User named a style → match by 适用场景 in `themes/README.md`, apply directly.
-3. User wants to choose (or nothing fits) → shortlist 2–4 by 适用场景. If they
-   want to SEE them, render a faithful sample per candidate: a 1-page
-   `doc-gen <docx|pdf> … --theme <themes/x.json>` → `doc-convert` to PDF →
-   `pdf-render` the page to a PNG (for a document theme this print render IS the
-   real look). A text shortlist by 适用场景 is fine too — don't over-render. Then
-   ask with the **picker card**: `ask_user_question`
-   type single_choice, one option per theme as
-   `{ label: 主题名, description: 一句适用场景, imagePath: 样片PNG绝对路径 }` —
-   the UI shows a compact thumbnail-card row and the user clicks one. Apply it.
-4. **After an explicit confirmation, remember it**: save the choice to your
-   agent memory as the user's deck-theme preference so the next deck starts
-   from it — and update the memory when they switch.
-
-**User-created themes (`themes/custom/`)**: writing a new theme.json is the
-supported way to make a new "template" — invalid fields fall back with warnings
-on stderr (read them and fix), so iterate freely. When the user tweaks colors
-repeatedly, hands you brand colors/logo, or says "以后都用这个风格", offer to
-save it: write `<skill>/themes/custom/<descriptive-name>.json` (kebab-case,
-with a `bestFor` line). Files there are the USER's — resource updates never
-touch them — and step 1 above picks them up in every later session. A liked
-existing deck can seed one too: `pptx-theme ref.pptx <skill>/themes/custom/x.json`.
-
-**Mimic an EXISTING deck**: extract its palette/fonts into a theme first —
+## Generate — `bin/doc-gen`
 
 ```
-node <skill>/bin/pptx-theme.cjs ref.pptx /tmp/ref-theme.json
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --theme /tmp/ref-theme.json
+node <skill>/bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json> [--topic "<subject>" | --theme <file|name>]
 ```
 
-This captures colors/fonts (heuristic fallbacks print on
-stderr), NOT slide layouts — to reuse the deck's actual LAYOUTS, tokenize it into
-a fillable template instead (see "Reuse a user's UPLOADED deck" below:
-`pptx-tokenize` → `doc-fill`).
-
-Theme fields (all optional; invalid values default + warn on stderr, never fail):
-`bestFor` (one-line 适用场景, for the picker) · `fonts{heading,body}` ·
-`colors{primary,accent,secondary,text,muted,tableHeaderBg,tableBorder}`
-(`accent` defaults to `primary`; `secondary` defaults to `muted`) ·
-`page{size:A4|Letter,margin,header,footer}` (`margin` is a CSS length string such as `margin:"20mm"` — mm/cm/in/pt/px; a bare number is not accepted and falls back to the default margin, which changes the page count; `{title}` `{page}` `{pages}` interpolate;
-**page header/footer: prefer Latin/digits — CJK there renders blank in the PDF path**) ·
-`heading{h1..h4}{size,color,bold,spaceAfter}` (color takes hex or a palette key like `"primary"`) ·
-`body{size,lineHeight,justify}` · `cover{enabled,subtitle,date,logo}` (base64 logo; title moves onto the cover) ·
-`pptx{background,titleColor,textColor}` — read only by `html2pptx --theme`, as the
-slide background / title / body CSS colors (dark deck = dark `background` + light
-`titleColor`/`textColor`; docx/PDF stay white-paper regardless).
-
-Per format the theme becomes: **pdf** CSS + cover page + live page headers/footers;
-**docx** real document styles (Heading1–4, default font/size, table header shading)
-+ header/footer parts + cover page. A spec may embed `"theme": {...}`;
-`--theme <file>` wins.
-
-## Template decks — `bin/pptx-clone` (one styled slide per data item)
-
-When a template `.pptx` carries a styled slide with `{{token}}` text, clone it
-once per item — styling, images and master survive verbatim:
+The spec is validated **strictly before rendering**: an unknown field or an empty body
+exits 65 with `DOC_SPEC_INVALID` and the JSON path — correct that path and rerun rather
+than delivering the previous output.
+
+- **docx / pdf**: `{ "title"?, "paragraphs"?: ["…"], "blocks"?: [ … ] }` — at least one
+  non-empty paragraph or block; never `sections`. A title-only document must set
+  `"allowCoverOnly": true`. `blocks` is an ordered list of
+  - `{ "type": "heading", "text": "…", "level": 1..4 }`
+  - `{ "type": "paragraph", "text": "…", "bold"?, "italic"? }`
+  - `{ "type": "list", "items": ["…"], "ordered"?: true }`
+  - `{ "type": "table", "rows": [["h"],["a"]], "header"?: true, "columnWidths"?: [3000, …] }`
+    (DOCX widths in twips; default: full page width, equal columns)
+  - `{ "type": "image", "data": "<base64>", "imageType"?: "png", "width"?, "height"? }` (px, default 300×200)
+- **xlsx**: `{ "sheets": { "Name": [["h1","h2"], ["a", 1]] } }` (row 1 = bold header), or per
+  sheet `{ "rows": [...], "header"?, "columnWidths"?: [n…], "numFmt"?: ["#,##0.00"…] }`. A
+  cell string starting with `=` is a **live formula** — then run **Formulas** below.
+  Fills, font colours, borders or merges need exceljs via doc-run (**Custom scripts**).
+- The spec may also carry `"topic"`, `"palette"` or `"theme"` (same as the flags).
+
+**A length limit** (正文 1000 字以内 / under 800 words) is kept in the spec, before
+generating: the result's `textChars` (spaces and URLs not counted) and `cjkChars` count it
+— over the limit, shorten the spec and generate once more. Do not extract text from the
+output to count it.
+
+**Look**: with no theme every document gets the same default — pass
+`--topic "<subject>"` (a palette that fits the subject, deterministic) unless the user
+named a look; **Themes** covers the rest.
+
+**PDF** is always printed in Chromium from themed HTML — CJK line-breaking, mixed
+Latin/中文 font fallback, tables, clickable links that wrap inside the page, the theme's
+page size and margin. Inside Talos it uses the app's service (`[pdf (chromium)]`),
+elsewhere a headless Chromium (`[pdf (headless chromium)]`); with neither it exits 69 and
+writes nothing — tell the user (a .docx can be offered; never swap formats silently).
+
+Anything past these shapes — an exotic layout, a styled workbook — is a doc-run script
+(**Custom scripts**), not an edit of the bundled bin.
+
+## Formulas — the xlsx repair loop (mandatory)
+
+Write live formulas (`"=SUM(A2:A9)"`), never precomputed values — the file must
+recalculate when the user edits data. doc-gen and exceljs write formulas without cached
+results, so close the loop:
+
+1. `node <skill>/bin/xlsx-recalc.cjs out.xlsx out.xlsx` — evaluates every formula and
+   caches the results.
+2. Its `errors` array must be **empty** — it exits 0 either way, so read it. A
+   `#DIV/0!`, `#REF!` or `#N/A` → fix the formula (guard divisors with IF, correct the
+   range) and recalc again. **Never deliver a spreadsheet with formula errors**, and never
+   "fix" one by replacing the formula with a hardcoded value.
+
+`xlsx-recalc` (HyperFormula) covers ~400 functions — all common math/stat/text/date/lookup;
+gaps are some exotic financial functions and dynamic-array spilling. `#NAME?` on a function
+you know is valid Excel is that engine limit: say so and compute that value with
+`xlsx-query` or a script instead of guessing.
+
+## Themes — the look of a doc-gen document (docx / pdf)
+
+Decks use **skins** (`--style`, the deck route), not these themes. A theme is a JSON file
+of colours/fonts/page setup; content (the spec) stays separate. This skill ships **12
+built-ins** in `themes/` (`themes/README.md` gives each one's best fit): `cool-tech` ·
+`apple-keynote` · `mckinsey-consulting` · `anthropic-clay` · `black-gold` · `hand-drawn` ·
+`mono` · `warm-editorial` · `ivory-gold` · `cinereel` · `magazine-ink` · `swiss-grid`. For a
+plain Word/PDF report `mckinsey-consulting` (white · deep navy · structured tables) is a
+safe default; `mono` for a stark minimal look. Pass a built-in by path:
 
 ```
-node <skill>/bin/pptx-clone.cjs template.pptx 1 out.pptx replacements.json
-# replacements.json: { "{{region}}": "华东区", "{{owner}}": "Alice" }
+node <skill>/bin/doc-gen.cjs docx out.docx spec.json --theme <skill>/themes/mckinsey-consulting.json
 ```
-The clone is appended at the deck's end; the template slide keeps its tokens for
-the next clone (chain the output for N items). Prints `{ newSlideNumber, replaced,
-missing, warnings }` — surface `missing` tokens instead of pretending they filled. To
-fill a whole deck ONCE (no repetition), use `doc-fill` on the .pptx instead.
-
-**Capacity warnings** (`CAPACITY {{token}}: … likely overflow` on stderr): the
-replacement text is visually wider than its slot (CJK chars count double).
-Fix by REWRITING the value shorter — never by shrinking the font (breaks the
-template's type hierarchy) and never by truncating with an ellipsis (looks
-worse than a slight overflow).
-
-**Slots ≠ item count.** When the template has more slots than you have content
-(e.g. a 4-person team page for a 3-person team), delete the WHOLE leftover
-group — picture + name + title together — via raw XML (`doc-xml unpack`, remove
-the group's `<p:sp>`/`<p:grpSp>` elements, repack). Emptying just the text
-leaves orphaned portraits/decoration. The inverse also holds: more items than
-slots means another cloned slide, not squeezed-in extra lines.
-
-**N data items, no leftover token slide (the standard combo):** clone N-1 times
-(one per item), then `doc-fill` the whole deck with the LAST item's values — that
-fills the original template slide (it becomes item N) plus any global tokens
-(`{{company}}`, `{{quarter}}` on cover/footer) in one pass. Finish with
-`doc-validate`.
-
-Alternatively clone N times and drop the template slide afterwards:
+
+`--palette <id>` forces one palette (`doc-gen --list-palettes`); `--accent <#rrggbb>` or
+`--style <deck style id>` keeps white paper with one brand colour (bin-reference.md
+"Generate" has the precedence).
+
+**Choosing with the user:** (1) a remembered document-theme preference or a theme the
+user saved (`ls "$TALOS_DOC_STYLES_DIR/themes"`) wins — use it and say so ("按你常用的 X
+主题,要换告诉我"); (2) a named style → match by 适用场景 in `themes/README.md` and apply;
+(3) they want to choose → shortlist 2–4 by 适用场景 (a text shortlist is fine). To show
+them, render a 1-page sample per candidate (`doc-gen pdf … --theme <path>` — its preview
+PNG is the real look) and ask with `ask_user_question` type `single_choice`, one option
+per theme `{ label: 主题名, description: 一句适用场景, imagePath: 样片PNG绝对路径 }`;
+(4) after an explicit confirmation, save the choice to memory as their document-theme
+preference, and update it when they switch.
+
+**User-created themes** are the supported way to make a new template: write a theme.json
+in the working folder and iterate (invalid fields fall back with warnings on stderr —
+read and fix them). When the user hands you brand colours/logo or says "以后都用这个风格",
+offer to keep it: save it as `$TALOS_DOC_STYLES_DIR/themes/<descriptive-name>.json`
+(kebab-case, with a `bestFor` line) — their own styles, kept across sessions and shared
+by every expert — and apply it by name, `--theme <descriptive-name>`. Never write inside
+the skill directory: it is an integrity-checked install, reinstalled (your file lost)
+once it changes. **An existing deck's colours** seed one:
+`pptx-theme.cjs ref.pptx ref-theme.json` → `--theme ref-theme.json` (palette/fonts only).
+
+Theme fields (all optional; an invalid value falls back to the default and warns on
+stderr, never fails): `bestFor` (one-line 适用场景) · `fonts{heading,body}` ·
+`colors{primary,accent,secondary,text,muted,tableHeaderBg,tableBorder}` (`accent`
+defaults to `primary`, `secondary` to `muted`) · `page{size:A4|Letter,margin,header,footer}`
+(`margin` is a CSS length string such as `margin:"20mm"` — mm/cm/in/pt/px; a bare number is not accepted and falls back to the default margin, which changes the page count;
+`{title}` `{page}` `{pages}` interpolate in header/footer; **prefer Latin/digits there —
+CJK in a PDF header/footer renders blank**) · `heading{h1..h4}{size,color,bold,spaceAfter}`
+(color: hex or a palette key like `"primary"`) · `body{size,lineHeight,justify}` ·
+`cover{enabled,subtitle,date,logo}` (base64 logo; the title moves onto the cover) ·
+`pptx{…}` (read only by the legacy `html2pptx --theme`; ignore for documents). A spec may
+embed `"theme": {...}`; `--theme` wins. In a **pdf** the theme becomes CSS + cover +
+live page headers/footers; in a **docx**, real styles (Heading1–4, default font, table
+header shading) + header/footer parts + cover.
+
+## Fill a template — `bin/doc-fill` (keeps the template's styling)
+
+When the user has (or wants) a styled **template** with `{{placeholder}}` tokens, this is
+the lossless way to fill it — fonts, tables, headers and layout stay verbatim.
 
 ```
-node <skill>/bin/pptx-clone.cjs remove out.pptx 1 final.pptx
+node <skill>/bin/doc-fill.cjs <template.docx|pptx|xlsx> <values.json> <out>
 ```
 
-Removal keeps every other slide untouched (parts are not renumbered — the
-deck order lives in sldIdLst). Always `doc-validate` the final deck.
+- Values: a JSON object. `{{name}}` ← `name`; nested `{{a.b}}` ← `{"a":{"b":…}}`.
+- Loops (.docx/.pptx): `{{#rows}} … {{col}} … {{/rows}}` over `{"rows":[{...}, ...]}`.
+- Prints `{ ok, out, unfilled }`: `unfilled` lists tokens left blank — surface them, never
+  call the document complete. Tokens Word split across runs are still filled; a malformed
+  or unclosed tag exits 1 and writes nothing.
+- **.xlsx**: tokens are filled cell by cell (`{{a}}`, `{{a.b}}`), each cell keeping its
+  style; a cell that is exactly one token takes the value's type, so pass numbers as
+  numbers. No loops — build repeated rows with `doc-gen xlsx` (or exceljs via doc-run).
+- No template yet → generate a first version with `doc-gen`, then fill that.
 
-## Reuse a user's UPLOADED deck as a template — `pptx-tokenize` → `doc-fill` (B2)
+Then `doc-validate` and render-and-look (SKILL.md "After writing a file").
 
-**Trigger is the STYLE intent, not "a .pptx was uploaded."** Use this ONLY when the
-user explicitly wants their new deck to KEEP an existing deck's look (their exact
-layouts/master/brand) — i.e. they chose it as their **style** (the Q3 "复用这份 PPT
-的风格" custom path). If the `.pptx` was handed in as **content** (they just want its
-text in a NEW deck), do NOT tokenize — extract its text (`.txt` sidecar / `doc-text`)
-and author fresh in the chosen skin. Same file, two intents; the user's answer to the
-style question (Q3), not the file type, decides.
+## Edit an existing .docx
 
-When the STYLE intent holds — new content in the deck's exact look (their layouts,
-master, brand — NOT one of our themes) — turn the deck into a fillable template
-instead of guessing a theme:
+Pick the least lossy path, and tell the user which trade-off you took:
 
-1. **Tokenize** — replace every content slot's text with a clean `{{token}}` (a
-   single run, so docxtemplater never corrupts it), keeping styling/master/layout
-   verbatim, and emit a catalog:
+1. **Change text** → `doc-xml replace` (cross-run, keeps formatting; body incl. tables,
+   headers/footers, footnotes/endnotes — not comments). One call per string, matched within
+   one paragraph; `replaced: 0` means the text is not there as written — copy the exact
+   wording from the sidecar.
+   ```
+   node <skill>/bin/doc-xml.cjs replace in.docx out.docx "旧措辞" "新措辞"
+   ```
+2. **`{{placeholders}}`** → **Fill a template** above.
+3. **Anything structural** (no targeted tool fits) → raw XML. A .docx is a zip of XML
+   parts that reference each other through `_rels/*.rels`, each listed in
+   `[Content_Types].xml` — add or rename a part and update both. Coalesce split runs
+   first so your find hits:
+   ```
+   node <skill>/bin/doc-xml.cjs merge-runs report.docx merged.docx
+   node <skill>/bin/doc-xml.cjs unpack merged.docx unpacked/   # XML pretty-printed
+   # … edit unpacked/word/document.xml …
+   node <skill>/bin/doc-xml.cjs pack unpacked/ report-edited.docx
+   node <skill>/bin/doc-validate.cjs report-edited.docx --strict   # MUST pass before delivering
+   ```
+4. **Content-first rewrite** → regenerate with `doc-gen` from the edited text — the
+   original styling is lost.
+
+### Review: comments and tracked changes — `bin/docx-annotate`
+
+- **Comments**: `docx-annotate.cjs comment in.docx out.docx comments.json` with
+  `[{ "author": "…", "text": "…", "anchor"?: "…", "replyTo"?: 0 }]`. `anchor` is a
+  substring of ONE paragraph (the first paragraph containing it gets the comment; no
+  anchor → the document's first paragraph). An anchor that matches nothing is NOT
+  written: stdout reports `written` and `skipped` (`[{ index, anchor }]`) and stderr warns;
+  add `--strict-anchors` to exit 1 on any skip (all unmatched always exits 1). Copy anchors
+  verbatim from the text. `replyTo` = index of another comment in the same file, shown as
+  a threaded reply (a reply to a skipped comment warns and is written top-level).
+- **Suggest an addition**: `docx-annotate.cjs suggest in.docx out.docx "<author>" "<text>"`
+  appends ONE new paragraph at the end of the body (before the final section properties)
+  as a tracked insertion — it cannot target a position. Rejecting it removes the paragraph.
+- **Tracked change in place** (replace or delete wording): raw XML (path 3 above) — wrap
+  the old run in `<w:del>` (its `<w:t>` becomes `<w:delText>`) and the new one in `<w:ins>`:
+  ```xml
+  <w:del w:id="9101" w:author="Claude" w:date="2026-01-01T00:00:00Z"><w:r><w:delText>旧</w:delText></w:r></w:del><w:ins w:id="9102" w:author="Claude" w:date="2026-01-01T00:00:00Z"><w:r><w:t>新</w:t></w:r></w:ins>
+  ```
+  (`w:id` unique in the document; keep the run's `<w:rPr>` in both to keep its format.)
+- **After ANY redline edit**: `docx-annotate.cjs redline-check original.docx edited.docx`
+  rejects every tracked change and requires the original text back exactly — the proof
+  that nothing changed untracked. Exit 1 prints `firstDivergence`; redo that edit as a
+  tracked change.
+- **Accept all**: `docx-annotate.cjs accept in.docx out.docx` keeps insertions, drops
+  deletions and format-change records, and prints the counts. A deleted paragraph mark
+  keeps both paragraphs (content is never lost).
+
+## Template decks — fill or restructure an existing .pptx
+
+**Which tool**: keep an uploaded deck's LAYOUTS for new content → `pptx-tokenize` →
+`doc-fill`; repeat one styled slide per data item → `pptx-clone`; add, duplicate, drop or
+reorder slides → `pptx-slide`; only its COLOURS → `pptx-theme` into a user skin
+(deck-design.md "Custom skins"). Always `doc-validate` the result, then render-and-look.
+
+### Reuse an uploaded deck — `pptx-tokenize` → `doc-fill`
+
+Only when the user chose the deck as their **style** (the picker's "使用我的模板文件"); a
+deck handed in as **content** is read for its text and authored fresh in the chosen skin.
+
+1. **Tokenize** — every content slot's text (placeholders and plain text boxes) becomes a
+   clean single-run `{{token}}`; styling/master/layouts stay verbatim:
    ```
    node <skill>/bin/pptx-tokenize.cjs user.pptx template.pptx schema.json
    ```
-   `schema.json` lists each token: `{ slide, token, role (title/subtitle/body/
-   text/pic/chart), type, multiline?, original, capacityChars }`. Plain text
-   boxes with NO PowerPoint placeholder are tokenized too (role `text`) — most
-   real decks position text in absolute boxes, not `<p:ph>` placeholders.
-
-2. **Author `values.json` from the schema** — one key per token. **Fill EVERY
-   token**: for slots you're keeping unchanged, pass their `original` back (an
-   unfilled token renders EMPTY and would BLANK that text). `multiline:true`
-   slots take a `\n`-joined string (renders as line breaks). Respect
-   `capacityChars` — rewrite shorter rather than overflow (CJK counts double).
+   `schema.json` = `{ slides: [{ index, tokens: [{ token, role, type, multiline?,
+   original?, capacityChars?, rel? }] }] }` — `role` is title / subtitle / body / text /
+   pic / chart; `type` is `text`, `image` or `chart`.
+2. **Fill** — `values.json` has one key per `text` token (the key is the token name, no
+   braces). **Fill EVERY token**: a slot you keep gets its `original` back (an unfilled
+   token renders EMPTY). `multiline:true` takes a `\n`-joined string. Respect
+   `capacityChars` (CJK-width units; a Latin letter ≈ ½) — rewrite shorter rather than
+   overflow. `unfilled` in the output names tokens you missed — add them and refill.
    ```
    node <skill>/bin/doc-fill.cjs template.pptx values.json out.pptx
    ```
-   `doc-fill` prints `{ unfilled }` — a non-empty `unfilled` means you missed
-   tokens (they blanked); add those keys and refill.
-
-3. **Swap images** — schema `type:"image"` tokens carry the slide + `rel`:
+3. **Images** — an `image` token carries its slide and `rel`:
    ```
    node <skill>/bin/pptx-set-image.cjs out.pptx <slide> <rel> new.png final.pptx
    ```
-   The picture's frame (position/size) stays put — only the pixels change. If the
-   new image's aspect ratio differs it STRETCHES; pre-crop it to the slot's ratio.
-
-4. **Charts** keep their look but hold the SOURCE deck's embedded data (schema
-   marks them `type:"chart"`, not a fill token) — edit the chart part separately,
-   or tell the user the chart numbers are still from their file.
-
-5. **`doc-validate`** the result, then render-and-look (doc-convert → PDF).
+   The frame stays put; a different aspect ratio STRETCHES — pre-crop to the slot's ratio.
+4. **Charts** keep the source deck's embedded data (`type:"chart"`, not a fill token) —
+   edit the chart part separately, or tell the user the numbers are still theirs.
 
-**Repeat one slide per data item?** After tokenizing you have a `{{token}}`
-template slide — the `pptx-clone` workflow above now applies (clone N times, fill
-each, drop the template slide).
-
-**Which path**: reuse their LAYOUTS → this (B2). Reuse only their COLORS in OUR
-layouts → `pptx-theme` (extract palette) + our families. Repeat a styled slide
-per data row → `pptx-clone`.
-
-All-Node generation (no Python): `docx`, `exceljs`, and Chromium for PDF; decks go
-through html2pptx. Same capability tier as the Anthropic docx/pptx/xlsx skills.
-
-## Generate — `bin/doc-gen` (self-contained; no npm install, works offline)
+### One styled slide per data item — `pptx-clone`
 
 ```
-node <skill>/bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json>
+node <skill>/bin/pptx-clone.cjs template.pptx 1 out.pptx replacements.json
+# replacements.json: { "{{region}}": "华东区", "{{owner}}": "Alice" }
 ```
-Simple spec shapes:
-- **docx / pdf**: `{ "title"?: "...", "paragraphs": ["...", ...] }`
-- **xlsx**: `{ "sheets": { "SheetName": [["h1","h2"], ["a", 1], ...] } }` (row 1 = bold header)
-
-`doc-gen pptx` exits 64 and points at html2pptx: decks are laid out as HTML
-(deck-design.md), never generated from a slide spec.
-
-`doc-gen` validates these shapes **strictly before rendering**: unknown fields are
-errors, not ignored. For DOCX/PDF use `paragraphs` and/or `blocks`—never
-`sections`. A title-only artifact also fails unless it is intentional and the
-spec explicitly sets `"allowCoverOnly": true`; on `DOC_SPEC_INVALID`, correct
-the reported JSON path and rerun rather than delivering the previous output.
-
-Rich spec shapes (use these for real documents, not just prose):
-- **docx** `blocks`: ordered list of
-  - `{ "type": "heading", "text": "...", "level": 1..4 }`
-  - `{ "type": "paragraph", "text": "...", "bold"?, "italic"? }`
-  - `{ "type": "list", "items": ["..."], "ordered"?: true }`
-  - `{ "type": "table", "rows": [["h"],["a"]], "header"?: true, "columnWidths"?: [3000, ...] }` (DOCX widths are twips; defaults to full-page equal-width fixed table)`
-  - `{ "type": "image", "data": "<base64>", "imageType"?: "png", "width"?, "height"? }`
-- **xlsx** per sheet, either the row array above OR
-  `{ "rows": [...], "header"?, "columnWidths"?: [n...], "numFmt"?: ["#,##0.00"...] }`.
-  A cell string starting with `=` is written as a **live formula** (e.g. `"=SUM(A2:A3)"`).
-Under the hood it uses `docx` / `exceljs`, and prints PDF in Chromium — the same
-tier as the Anthropic docx/pptx/xlsx skills, but all-Node (no Python /
-LibreOffice) and bundled into the script. For anything past these shapes, write a
-short Node script using those libraries directly (they are on the skill's path).
-
-**PDF rendering (always Chromium, one layout everywhere):** `doc-gen pdf`
-renders your spec as themed HTML and prints it in Chromium — professional CJK
-line-breaking, per-glyph font fallback (Latin + 中文 mixed just works),
-justification, tables, clickable links that wrap inside the page, and the
-theme's page size and margin. Inside Talos it goes through the app's service
-(`[pdf (chromium)]`); elsewhere it uses a headless Chromium
-(`[pdf (headless chromium)]`, needs Playwright). With neither it exits 69 and
-writes nothing — tell the user the PDF could not be produced. The spec's
-`blocks` (headings/lists/tables) are supported, not just `title`/`paragraphs`.
-
-## Fill a template — `bin/doc-fill` (preserves styling; the best "edit" path)
-
-When the user has (or wants) a styled **template** with `{{placeholder}}` tokens,
-this is the lossless way to produce a filled document — the original fonts,
-tables, headers and layout are kept verbatim.
 
-```
-node <skill>/bin/doc-fill.cjs <template.docx|pptx|xlsx> <values.json> <out>
-```
-- Values: a JSON object. `{{name}}` ← `name`; nested `{{a.b}}` ← `{"a":{"b":…}}`.
-- Loops: `{{#rows}} … {{col}} … {{/rows}}` over `{"rows":[{...}, ...]}`.
-- Output prints `{ ok, out, unfilled }`; `unfilled` lists template tokens you left
-  blank — surface them to the user rather than pretending the doc is complete.
-- Works across .docx/.pptx/.xlsx and correctly fills placeholders that Word split
-  across runs (a naive find/replace misses those). Malformed/unclosed tags fail
-  loudly — no half-rendered file.
+The clone is appended at the end; the template slide keeps its tokens for the next clone
+(chain the output for N items). Surface `missing` tokens instead of pretending they
+filled. For N items with no leftover token slide: clone N-1 times, then `doc-fill` the
+whole deck with the LAST item's values — that fills the template slide (it becomes item
+N) plus global tokens (`{{company}}` on cover/footer) in one pass. Or clone N times and
+drop the template: `pptx-clone.cjs remove out.pptx 1 final.pptx`. To fill a deck ONCE (no
+repetition), `doc-fill` the .pptx directly.
 
-If the user has no template, generate a first version with `doc-gen`, then treat
-it as a template on subsequent fills.
+- **CAPACITY warnings** (`CAPACITY {{token}}: … likely overflow` on stderr): rewrite the
+  value shorter — never shrink the font (breaks the type hierarchy), never truncate with
+  an ellipsis.
+- **Slots ≠ item count**: more slots than content (a 4-person team page for 3 people) →
+  delete the WHOLE leftover group — picture + name + title — via raw XML (remove its
+  `<p:sp>`/`<p:grpSp>`); emptying just the text leaves orphaned portraits. More items
+  than slots → another cloned slide, not squeezed-in lines.
 
-## Slide-lifecycle surgery — `bin/pptx-slide` (restructure an existing deck)
-
-Structural changes to an existing `.pptx` that need NO `{{token}}` template and
-preserve every slide's styling/master (the OOXML rels/Content_Types/sldIdLst
-bookkeeping is done for you — lossless):
+### Slide surgery — `pptx-slide`
 
 ```
 node <skill>/bin/pptx-slide.cjs add     in.pptx out.pptx [--layout N]  # append a blank slide (inherits a layout)
 node <skill>/bin/pptx-slide.cjs dup     in.pptx 2 out.pptx             # duplicate slide 2 (copy appended at end)
 node <skill>/bin/pptx-slide.cjs remove  in.pptx 5 out.pptx             # drop slide 5
-node <skill>/bin/pptx-slide.cjs reorder in.pptx 3,1,2 out.pptx         # permute deck order (current 1-based positions)
+node <skill>/bin/pptx-slide.cjs reorder in.pptx 3,1,2 out.pptx         # new order, as current 1-based positions
 ```
 
-`add` binds the new slide to the LAST slide's layout unless `--layout N` picks
-one (so it inherits the deck's master/theme); its body is empty — fill it in
-PowerPoint or with a follow-up `doc-xml` edit. `dup` is `pptx-clone` with no
-replacements. `reorder` rewrites only `<p:sldIdLst>` (no parts move). This is the
-"edit any deck in place" toolkit for STRUCTURE; for in-slide TEXT edits use
-`doc-fill` (templated) or `doc-xml` (raw). Always `doc-validate` the output.
-
-## Other edits (all lossy — pick per goal)
-
-Editing arbitrary content *in place while preserving layout* (no placeholders) is
-an unsolved problem. The realistic paths:
-
-1. **Fill a template** — above; lossless when the doc is (or can be made) a
-   `{{placeholder}}` template. Prefer this.
-2. **Extract → rewrite → regenerate** — `doc-text`, edit the text, regenerate a
-   fresh file. Loses original styling. Best for content-first edits.
-3. **PDF page ops** — `bin/pdf-ops` merges/splits/rotates/watermarks existing PDFs
-   without re-rendering (preserves every page verbatim). Additive/structural only.
-4. **Overlay / annotate** — stamp marks on an existing PDF with `pdf-lib`.
-   Preserves the original; additive only.
-
-State which trade-off you took so the user isn't surprised by lost formatting.
+Lossless; rels/Content_Types/sldIdLst bookkeeping is done for you. `add` binds the last
+slide's layout unless `--layout N`; its body is empty — fill it with `doc-xml`. In-slide
+TEXT goes through `doc-fill` (templated) or `doc-xml` (raw).
 
 ## Custom scripts — `bin/doc-run` (the long-tail escape hatch)
 
-When the built-in verbs and spec blocks can't express what you need (an exotic
-layout, a bulk transformation, a bespoke workbook), **write a Node script and
-run it with `doc-run`** — the engine's pure-JS libraries are bundled inside it,
-so this works on ANY machine (packaged app, clean install, no node_modules):
+When no verb or spec block expresses it (an exotic layout, a bulk transformation, a
+styled workbook), write a CommonJS Node script and run it with `doc-run` — the engine's
+pure-JS libraries are bundled inside it, so it works on any machine:
 
 ```
 node <skill>/bin/doc-run.cjs myscript.js [args…]
 node <skill>/bin/doc-run.cjs --list          # the guaranteed module registry
 ```
 
-Inside the script, plain CommonJS `require()` of these names is guaranteed:
-`pptxgenjs` (non-deck pptx only — data tables, one-off shapes; every deck goes through html2pptx) · `docx` (Word) · `exceljs` (formatted workbooks: fills,
-fonts, borders, merges, formulas) · `xlsx` (SheetJS: reading and plain-data
-workbooks only — it writes no cell styles) · `pdf-lib` (PDF assembly) ·
-`jszip` / `pizzip` (OOXML zip surgery) · `hyperformula` (formula evaluation).
-An exceljs formula is written without a cached result; run
-`bin/xlsx-recalc.cjs` on the file when the values must show before Excel
-recalculates. Nothing else is guaranteed — do not
-`require` other packages, and never run `npm install`.
-
-Rules of the tier ladder (try in this order, don't skip levels). **NOTE — decks
-are the exception: a deck DEFAULTS to html2pptx (SKILL.md routing), not to
-doc-gen; the ladder below is the escalation order for the long-tail / non-deck
-custom case (exotic layouts, bulk transforms, bespoke workbooks).**
-1. **Built-in verbs / spec blocks** (doc-gen, doc-fill, pptx-clone, docx-annotate) — stable, themed, tested.
-2. **html2pptx** (decks — the default deck path; in-app or bundled-headless) — think in HTML/CSS layout, get native editable slides (see deck-design.md).
-3. **`doc-run` custom script** — full library power, themed by reading the theme JSON yourself (see deck-design.md).
-4. **Raw XML** (doc-xml unpack/pack) — when even the libraries can't express it.
-
-And the one unbreakable rule: **every produced file goes through
-`bin/doc-validate.cjs` before delivery — with `--strict` for anything from
-tiers 2–4** (custom code has no safety net except that gate; --strict is the
-full ECMA-376 schema check).
-
-## Raw XML editing (advanced escape hatch)
-
-When no targeted tool (doc-fill / docx-annotate / pptx-clone) covers an edit:
-
-```
-node <skill>/bin/doc-xml.cjs unpack report.docx unpacked/   # XML pretty-printed
-# … edit unpacked/word/document.xml …
-node <skill>/bin/doc-xml.cjs pack unpacked/ report-edited.docx
-node <skill>/bin/doc-validate.cjs report-edited.docx        # MUST pass before delivering
-```
+`require()` of these is guaranteed: `docx` (Word) · `exceljs` (formatted workbooks:
+fills, fonts, borders, merges, formulas — then **Formulas**) · `xlsx` (SheetJS: reading
+and plain-data workbooks only — it writes no cell styles) · `pdf-lib` (PDF assembly) ·
+`jszip` / `pizzip` (OOXML zip surgery) · `hyperformula` (formula evaluation) ·
+`pptxgenjs` (non-deck pptx only — every deck goes through html2pptx). Nothing else: no
+other package, never `npm install`. Theme the output by reading a theme JSON yourself.
 
-A .docx/.pptx/.xlsx is a zip of XML parts; parts reference each other through
-`_rels/*.rels` and every part needs a `[Content_Types].xml` entry — if you add
-or rename parts, update both, then let doc-validate catch what you missed.
-Text is often split across multiple `<w:r>` runs — for a .docx, run
-`doc-xml.cjs merge-runs in.docx merged.docx` FIRST to coalesce same-format
-fragments ("He"+"llo"→"Hello"), then unpack; your find/replace will hit.
-
-## Review workflow (comments + tracked changes)
-
-- Comment threads: give a comment `"replyTo": <index-in-this-batch>` in
-  comments.json and Word shows it as a reply; resolved-state/author-identity
-  parts are written automatically.
-- `docx-annotate.cjs suggest` adds a tracked insertion the user can
-  accept/reject in Word; `docx-annotate.cjs accept in.docx out.docx` accepts
-  ALL tracked changes (insertions kept, deletions dropped, format-change
-  records cleared) and prints the counts. A deleted *paragraph mark* keeps both
-  paragraphs (documented limitation — content is never lost).
-- **After ANY redline edit** (suggest, or hand-written `<w:ins>`/`<w:del>` via
-  doc-xml): run `docx-annotate.cjs redline-check original.docx edited.docx`.
-  It rejects every tracked change and requires the result to equal the
-  original text exactly — the mathematical proof that you changed nothing
-  without tracking it. Non-zero exit prints the first diverging paragraph;
-  redo that edit as a tracked change.
+Order of escalation: built-in verbs → `doc-run` → raw XML (`doc-xml`). Custom code has no
+safety net but the gate: **`doc-validate --strict` every file it produces** (the full
+ECMA-376 schema check).