@taloswork/ose-shared 0.1.8 → 0.1.10

package/skills/diagram-design/scripts/self_check.py

@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""Self-check a generated diagram HTML file, with no third-party deps.
+
+Ships inside the skill so an installed agent can verify its own output:
+
+    python3 <skill-dir>/scripts/self_check.py my-diagram.html
+
+Checks the accessible-SVG contract, the single-file safety rules (no remote
+assets beyond the approved Google Fonts stylesheet, no executable attributes,
+no scripts other than the one canonical motion controller), and — when motion
+markup is present — the structural motion contract. This is a distilled
+subset of the repository gates (`lint-skin.py`, `verify-motion.py`), which
+remain the authority for contributions to the repository itself.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections import Counter
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urlparse
+
+SKILL_DIR = Path(__file__).resolve().parent.parent
+MOTION_TEMPLATE = SKILL_DIR / "assets" / "template-motion.html"
+MODES = {"none", "reveal", "step", "loop"}
+ACTIONS = {"play", "pause", "replay", "prev", "next"}
+ASCII_DECIMAL_RE = re.compile(r"^[0-9]+$")
+REFERENCE_ATTRS = {"src", "href", "xlink:href", "poster", "srcset", "action", "formaction"}
+
+
+class DiagramParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.roots: list[dict[str, str]] = []
+        self.items: list[dict[str, str]] = []
+        self.actions: set[str] = set()
+        self.controls = 0
+        self.statuses: list[dict[str, str]] = []
+        self.statuses_in_controls = 0
+        self.scripts: list[dict[str, object]] = []
+        self.styles: list[str] = []
+        self.svgs: list[dict[str, object]] = []
+        self.unsafe: list[str] = []
+        self.references: list[tuple[str, str, str]] = []
+        self._svg_depth = 0
+        self._current_svg: dict[str, object] | None = None
+        self._capture: str | None = None
+        self._current_script: dict[str, object] | None = None
+        self._in_style = False
+        self._element_stack: list[str] = []
+        self._motion_root_depth: int | None = None
+        self._controls_depth: int | None = None
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.casefold()
+        normalized_attrs = [(key.casefold(), value or "") for key, value in attrs]
+        data = {key: value for key, value in normalized_attrs}
+        if tag in {"base", "embed", "object", "iframe"}:
+            self.unsafe.append(f"<{tag}> is not allowed in a diagram file")
+        for key, value in normalized_attrs:
+            if key.startswith("on"):
+                self.unsafe.append(f"executable attribute {key} on <{tag}>")
+            if key == "srcdoc":
+                self.unsafe.append(f"srcdoc attribute on <{tag}>")
+            if key in REFERENCE_ATTRS:
+                self.references.append((tag, data.get("rel", ""), value))
+        if "data-motion-root" in data:
+            self.roots.append(data)
+            if self._motion_root_depth is None:
+                self._motion_root_depth = len(self._element_stack)
+        if self._motion_root_depth is not None:
+            if "data-motion-item" in data:
+                self.items.append(data)
+            if "data-motion-action" in data:
+                self.actions.add(data["data-motion-action"])
+            if "data-motion-controls" in data:
+                self.controls += 1
+                if self._controls_depth is None:
+                    self._controls_depth = len(self._element_stack)
+            if "data-motion-status" in data:
+                self.statuses.append(data)
+                if self._controls_depth is not None:
+                    self.statuses_in_controls += 1
+        if tag == "script":
+            self._current_script = {
+                "attrs": data,
+                "attr_names": [name for name, _value in normalized_attrs],
+                "body": [],
+                "closed": False,
+            }
+            self.scripts.append(self._current_script)
+        if tag == "style":
+            self._in_style = True
+        self._element_stack.append(tag)
+        if tag == "svg" and self._svg_depth == 0:
+            self._svg_depth = 1
+            self._current_svg = {"attrs": data, "first": None, "title": {}, "desc": {}}
+            self.svgs.append(self._current_svg)
+            return
+        if self._svg_depth:
+            self._svg_depth += 1
+            assert self._current_svg is not None
+            if self._svg_depth == 2 and self._current_svg["first"] is None:
+                self._current_svg["first"] = tag
+            if self._svg_depth == 2 and tag in {"title", "desc"}:
+                self._current_svg[tag] = {"attrs": data, "text": ""}
+                self._capture = tag
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.casefold()
+        if tag == "script" and self._current_script is not None:
+            self._current_script["closed"] = True
+            self._current_script = None
+        if tag == "style":
+            self._in_style = False
+        if self._svg_depth:
+            if tag in {"title", "desc"}:
+                self._capture = None
+            self._svg_depth -= 1
+            if self._svg_depth == 0:
+                self._current_svg = None
+        for index in range(len(self._element_stack) - 1, -1, -1):
+            if self._element_stack[index] == tag:
+                del self._element_stack[index:]
+                break
+        if (
+            self._motion_root_depth is not None
+            and len(self._element_stack) <= self._motion_root_depth
+        ):
+            self._motion_root_depth = None
+        if (
+            self._controls_depth is not None
+            and len(self._element_stack) <= self._controls_depth
+        ):
+            self._controls_depth = None
+
+    def handle_data(self, data: str) -> None:
+        if self._current_script is not None:
+            body = self._current_script["body"]
+            assert isinstance(body, list)
+            body.append(data)
+        if self._in_style:
+            self.styles.append(data)
+        if self._capture and self._current_svg:
+            node = self._current_svg[self._capture]
+            assert isinstance(node, dict)
+            node["text"] = str(node.get("text", "")) + data
+
+
+def normalized_controller(body: str) -> str:
+    return body.replace("\r\n", "\n").replace("\r", "\n").strip()
+
+
+def parsed_document(source: str) -> DiagramParser:
+    parser = DiagramParser()
+    parser.feed(source)
+    parser.close()
+    return parser
+
+
+def is_approved_google_fonts_stylesheet(value: str) -> bool:
+    try:
+        parsed = urlparse(value)
+    except ValueError:
+        return False
+    return (
+        parsed.scheme == "https"
+        and parsed.hostname is not None
+        and parsed.hostname.casefold() == "fonts.googleapis.com"
+        and parsed.port is None
+        and parsed.path == "/css2"
+        and not parsed.fragment
+    )
+
+
+def reference_error(tag: str, rel: str, value: str) -> str | None:
+    stripped = value.strip()
+    lowered = stripped.casefold()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if lowered.startswith("javascript:") or lowered.startswith("data:text/html"):
+        return f"executable URL on <{tag}>: {stripped[:80]}"
+    remote = lowered.startswith(("http://", "https://", "//")) or (
+        ":" in stripped.split("/", 1)[0] and not lowered.startswith("data:")
+    )
+    if not remote:
+        if lowered.startswith("data:") and not lowered.startswith("data:image/"):
+            return f"non-image data URL on <{tag}>: {stripped[:80]}"
+        return None
+    if tag == "link" and "stylesheet" in rel.casefold().split():
+        if is_approved_google_fonts_stylesheet(stripped):
+            return None
+        return f"remote stylesheet is not the approved Google Fonts /css2 URL: {stripped[:80]}"
+    return f"remote reference on <{tag}>: {stripped[:80]}"
+
+
+def canonical_controller() -> str:
+    if not MOTION_TEMPLATE.is_file():
+        raise RuntimeError(
+            f"cannot find the canonical controller at {MOTION_TEMPLATE}; "
+            "run self_check.py from its shipped location inside the skill"
+        )
+    parser = parsed_document(MOTION_TEMPLATE.read_text(encoding="utf-8"))
+    if len(parser.scripts) != 1 or not parser.scripts[0]["closed"]:
+        raise RuntimeError("template-motion.html must contain one closed controller")
+    body = parser.scripts[0]["body"]
+    assert isinstance(body, list)
+    return normalized_controller("".join(body))
+
+
+def check_svgs(parser: DiagramParser, errors: list[str]) -> None:
+    checkable = [
+        svg
+        for svg in parser.svgs
+        if isinstance(svg["attrs"], dict)
+        and str(svg["attrs"].get("aria-hidden", "")).casefold() != "true"
+    ]
+    if not checkable:
+        errors.append("diagram file needs at least one accessible (non-aria-hidden) SVG")
+    for number, svg in enumerate(checkable, 1):
+        attrs = svg["attrs"]
+        assert isinstance(attrs, dict)
+        if attrs.get("role") != "img":
+            errors.append(f"svg {number} needs role=img")
+        labelled = attrs.get("aria-labelledby", "").split()
+        title = svg["title"]
+        desc = svg["desc"]
+        assert isinstance(title, dict) and isinstance(desc, dict)
+        title_attrs = title.get("attrs", {})
+        desc_attrs = desc.get("attrs", {})
+        assert isinstance(title_attrs, dict) and isinstance(desc_attrs, dict)
+        if svg["first"] != "title":
+            errors.append(f"svg {number} title must be its first child")
+        if not str(title.get("text", "")).strip() or not str(desc.get("text", "")).strip():
+            errors.append(f"svg {number} needs non-empty title and desc")
+        title_id = title_attrs.get("id", "")
+        desc_id = desc_attrs.get("id", "")
+        if title_id in {"", "title"} or desc_id in {"", "desc"}:
+            errors.append(f"svg {number} title/desc IDs must be diagram-prefixed, never bare")
+        if labelled != [title_id, desc_id]:
+            errors.append(f"svg {number} aria-labelledby must name title then desc")
+
+
+def check_scripts(parser: DiagramParser, errors: list[str]) -> None:
+    if not parser.scripts:
+        return
+    if len(parser.scripts) > 1:
+        errors.append(f"at most one script is allowed; found {len(parser.scripts)}")
+    for number, script in enumerate(parser.scripts, 1):
+        attrs = script["attrs"]
+        attr_names = script["attr_names"]
+        body = script["body"]
+        assert isinstance(attrs, dict) and isinstance(attr_names, list) and isinstance(body, list)
+        if not script["closed"]:
+            errors.append(f"script {number} must have a closing script tag")
+        if attr_names != ["data-diagram-controls"] or attrs.get("data-diagram-controls") != "":
+            errors.append(f"script {number} must carry only the canonical data-diagram-controls attribute")
+            continue
+        try:
+            if normalized_controller("".join(body)) != canonical_controller():
+                errors.append(f"script {number} must exactly match the controller in template-motion.html")
+        except RuntimeError as exc:
+            errors.append(str(exc))
+
+
+def check_motion(parser: DiagramParser, source: str, errors: list[str]) -> None:
+    has_motion_markup = bool(parser.roots or parser.items or parser.scripts)
+    if not has_motion_markup:
+        return
+    if len(parser.roots) != 1:
+        errors.append(f"expected exactly one data-motion-root; found {len(parser.roots)}")
+        return
+    root = parser.roots[0]
+    mode = root.get("data-motion-mode", "")
+    if mode not in MODES:
+        errors.append(f"data-motion-mode must be one of {sorted(MODES)}; got {mode!r}")
+    raw_count = root.get("data-step-count", "")
+    if not ASCII_DECIMAL_RE.fullmatch(raw_count):
+        count = -1
+        errors.append("data-step-count must be an ASCII decimal integer")
+    else:
+        count = int(raw_count)
+    minimum_count = 0 if mode == "none" else 1
+    if count < minimum_count or count > 8:
+        errors.append(f"semantic step count must be {minimum_count}..8; got {count}")
+
+    if len(parser.items) > 12:
+        errors.append(f"motion item budget is 12; found {len(parser.items)}")
+    semantic_steps: list[int] = []
+    for index, item in enumerate(parser.items, 1):
+        raw_step = item.get("data-step", "")
+        if not ASCII_DECIMAL_RE.fullmatch(raw_step):
+            errors.append(f"motion item {index} has a non-ASCII-decimal data-step")
+            continue
+        step = int(raw_step)
+        decorative = "data-motion-decorative" in item
+        if not decorative:
+            semantic_steps.append(step)
+            if not item.get("aria-label", "").strip():
+                errors.append(f"semantic motion item {index} needs a non-color aria-label")
+        elif item.get("aria-hidden") != "true" or item.get("focusable") != "false":
+            errors.append(f"decorative motion item {index} needs aria-hidden=true and focusable=false")
+        inline = item.get("style", "").replace(" ", "").lower()
+        if any(token in inline for token in ("display:none", "visibility:hidden", "opacity:0")):
+            errors.append(f"motion item {index} is hidden in source; the fallback must be visible")
+
+    expected = set(range(1, count + 1)) if count > 0 else set()
+    if set(semantic_steps) != expected:
+        errors.append(f"semantic steps must be contiguous 1..{count}; found {sorted(set(semantic_steps))}")
+    crowded = {step: n for step, n in Counter(semantic_steps).items() if n > 2}
+    if crowded:
+        errors.append(f"no more than two semantic items may share a step; found {crowded}")
+
+    if mode in {"none", "loop"} and parser.scripts:
+        errors.append(f"{mode} mode must be script-free")
+    if mode in {"none", "loop"} and (parser.controls or parser.actions or parser.statuses):
+        errors.append(f"{mode} mode must not expose playback controls or live status")
+    controlled = mode == "step" or (mode == "reveal" and bool(parser.scripts))
+    if controlled:
+        if parser.controls != 1:
+            errors.append(f"controlled mode needs one in-root control group; found {parser.controls}")
+        missing = ACTIONS - parser.actions
+        if missing:
+            errors.append(f"controlled mode is missing actions: {', '.join(sorted(missing))}")
+        if not parser.statuses:
+            errors.append("controlled mode needs data-motion-status")
+        else:
+            status = parser.statuses[0]
+            if (
+                status.get("role") != "status"
+                or status.get("aria-live") != "polite"
+                or status.get("aria-atomic") != "true"
+            ):
+                errors.append("motion status needs role=status, aria-live=polite, aria-atomic=true")
+            if parser.statuses_in_controls:
+                errors.append("motion status must sit outside data-motion-controls")
+        if not parser.scripts:
+            errors.append("controlled mode needs the scoped control script")
+
+    style_source = "".join(parser.styles)
+    if parser.scripts:
+        if re.search(r"prefers-reduced-motion\s*:\s*reduce", style_source, re.IGNORECASE) is None:
+            errors.append("missing reduced-motion CSS fallback (prefers-reduced-motion)")
+        if re.search(r"@media\s+print\b", style_source, re.IGNORECASE) is None:
+            errors.append("missing print CSS fallback (@media print)")
+        if "<noscript" not in source.casefold():
+            errors.append("motion file needs a <noscript> explanation of the complete static frame")
+
+
+def verify(path: Path) -> list[str]:
+    source = path.read_text(encoding="utf-8")
+    parser = parsed_document(source)
+    errors: list[str] = []
+    errors.extend(parser.unsafe)
+    for tag, rel, value in parser.references:
+        finding = reference_error(tag, rel, value)
+        if finding:
+            errors.append(finding)
+    check_svgs(parser, errors)
+    check_scripts(parser, errors)
+    check_motion(parser, source, errors)
+    return errors
+
+
+def main() -> int:
+    argument_parser = argparse.ArgumentParser(description=__doc__)
+    argument_parser.add_argument("files", nargs="+", type=Path)
+    args = argument_parser.parse_args()
+    failed = False
+    for path in args.files:
+        try:
+            errors = verify(path)
+        except (OSError, UnicodeError) as exc:
+            errors = [str(exc)]
+        if errors:
+            failed = True
+            print(f"FAIL {path}")
+            for error in errors:
+                print(f"  - {error}")
+        else:
+            print(f"OK {path}")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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 —