@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/pdf/scripts/render/overlay_preview.py

@@ -0,0 +1,86 @@
+"""Draw bounding-box previews on top of a rasterised page.
+
+Reads the new-style ``fields.json`` config (see docs/forms-guide.md
+for the schema) and overlays each entry/tag rectangle onto a single
+page image so the operator can eyeball the geometry before running
+``scripts.fill.overlay_apply``.
+
+Run from the skill root::
+
+    python -m scripts.render.overlay_preview \\
+        1 fields.json out_dir/page_1.png out_dir/page_1_overlay.png
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from PIL import Image, ImageDraw
+
+from scripts.lib.cli_utils import emit, fail, make_parser
+
+
+def render_overlay_preview(
+    page_no: int,
+    cfg_path: str,
+    base_img: str,
+    out_img: str,
+    *,
+    quiet: bool = False,
+) -> int:
+    with open(cfg_path, "r") as handle:
+        cfg = json.load(handle)
+
+    canvas = Image.open(base_img)
+    painter = ImageDraw.Draw(canvas)
+    drawn_boxes = 0
+
+    for slot in cfg.get("slots", []):
+        if slot.get("page_no") != page_no:
+            continue
+        slot_box = slot.get("slot_box")
+        tag_box = slot.get("tag_box")
+        if slot_box:
+            painter.rectangle(slot_box, outline="red", width=2)
+            drawn_boxes += 1
+        if tag_box:
+            painter.rectangle(tag_box, outline="blue", width=2)
+            drawn_boxes += 1
+
+    canvas.save(out_img)
+    emit(
+        f"Rendered overlay preview to {out_img} ({drawn_boxes} boxes drawn)",
+        quiet=quiet,
+    )
+    return drawn_boxes
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = make_parser(
+        "overlay_preview",
+        "Draw slot/tag bounding boxes on top of a rasterised page image.",
+    )
+    parser.add_argument("page_no", type=int, help="1-based page number.")
+    parser.add_argument("cfg_path", help="Path to fields.json (new schema).")
+    parser.add_argument("base_img", help="Input page PNG.")
+    parser.add_argument("out_img", help="Output PNG with overlay drawn.")
+    args = parser.parse_args(argv)
+
+    try:
+        render_overlay_preview(
+            args.page_no,
+            args.cfg_path,
+            args.base_img,
+            args.out_img,
+            quiet=args.quiet,
+        )
+    except FileNotFoundError as exc:
+        fail(f"File not found: {exc.filename}", code=2)
+    except Exception as exc:  # noqa: BLE001
+        fail(f"Overlay preview failed: {exc}", code=2)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/server/assets/skills/pdf/scripts/render/page_rasterize.py

@@ -0,0 +1,85 @@
+"""Rasterise PDF pages to PNG images.
+
+Each page becomes ``page_<N>.png`` inside the destination directory.
+Pages larger than ``--max-edge`` (in pixels along the longer side)
+are downsampled with PIL before being written, which keeps the output
+manageable for visual inspection.
+
+Run from the skill root::
+
+    python -m scripts.render.page_rasterize input.pdf out_dir/ \\
+        --max-edge 1200 --dpi 200
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from pdf2image import convert_from_path
+
+from scripts.lib.cli_utils import emit, fail, make_parser
+
+
+def rasterize(
+    src_pdf: str,
+    dst_dir: str,
+    *,
+    max_edge: int = 1000,
+    dpi: int = 200,
+    quiet: bool = False,
+) -> int:
+    os.makedirs(dst_dir, exist_ok=True)
+    page_imgs = convert_from_path(src_pdf, dpi=dpi)
+
+    for idx, img in enumerate(page_imgs):
+        w, h = img.size
+        if w > max_edge or h > max_edge:
+            shrink = min(max_edge / w, max_edge / h)
+            img = img.resize((int(w * shrink), int(h * shrink)))
+        out_png = os.path.join(dst_dir, f"page_{idx + 1}.png")
+        img.save(out_png)
+        emit(f"  page {idx + 1} -> {out_png} ({img.size[0]}x{img.size[1]})", quiet=quiet)
+
+    emit(f"Rasterised {len(page_imgs)} page(s) into {dst_dir}", quiet=quiet)
+    return len(page_imgs)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = make_parser(
+        "page_rasterize",
+        "Convert each PDF page into a PNG file under the output directory.",
+    )
+    parser.add_argument("src_pdf", help="Input PDF path.")
+    parser.add_argument("dst_dir", help="Output directory for PNGs.")
+    parser.add_argument(
+        "--max-edge",
+        type=int,
+        default=1000,
+        help="Cap the longer side (pixels). Set 0 to disable resizing.",
+    )
+    parser.add_argument(
+        "--dpi",
+        type=int,
+        default=200,
+        help="Initial render resolution before optional resizing.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        rasterize(
+            args.src_pdf,
+            args.dst_dir,
+            max_edge=args.max_edge if args.max_edge > 0 else 10**9,
+            dpi=args.dpi,
+            quiet=args.quiet,
+        )
+    except FileNotFoundError:
+        fail(f"PDF not found: {args.src_pdf}", code=2)
+    except Exception as exc:  # noqa: BLE001
+        fail(f"Rasterisation failed: {exc}", code=2)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/server/assets/skills/pdf/scripts/render_html.cjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * render_html.cjs — Render any HTML (file or URL) → PDF via Playwright.
+ *
+ * Usage:
+ *   node render_html.cjs --in page.html --out report.pdf
+ *   node render_html.cjs --in page.html --out report.pdf --wait 15000
+ *   node render_html.cjs --in https://example.com --out site.pdf --landscape
+ *
+ * Options:
+ *   --in <file|url>          HTML file path or http(s):// URL (required)
+ *   --out <file>             Output PDF path (required)
+ *   --wait <ms>              Extra settle time after networkidle (default 800).
+ *                            Bump to 15000+ for Chart.js / heavy JS pages.
+ *   --format <A4|Letter>     Page format (default A4)
+ *   --margin <css>           CSS margin shorthand, e.g. "14mm 12mm" (default "14mm 12mm")
+ *   --landscape              Landscape orientation
+ *   --scale <n>              Print scale 0.1–2 (default 1)
+ *   --no-print-background    Disable -webkit-print-color-adjust:exact rendering
+ *   --header <html>          Optional header HTML template
+ *   --footer <html>          Optional footer HTML template
+ *
+ * Exit codes: 0 success, 1 bad args, 2 dependency missing, 3 render error
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+function usage(msg) {
+  if (msg) console.error(msg);
+  console.error(
+    'Usage: node render_html.cjs --in <file.html|url> --out <file.pdf>\n' +
+      '       [--wait <ms>] [--format A4|Letter] [--margin "14mm 12mm"]\n' +
+      '       [--landscape] [--scale 1] [--no-print-background]\n' +
+      '       [--header <html>] [--footer <html>]',
+  );
+  process.exit(1);
+}
+
+// ── Arg parsing ────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+let input = null;
+let outFile = null;
+let waitMs = 800;
+let format = 'A4';
+let margin = '14mm 12mm';
+let landscape = false;
+let scale = 1;
+let printBackground = true;
+let headerHtml = null;
+let footerHtml = null;
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if ((a === '--in' || a === '--input') && args[i + 1]) input = args[++i];
+  else if (a === '--out' && args[i + 1]) outFile = args[++i];
+  else if (a === '--wait' && args[i + 1]) waitMs = parseInt(args[++i], 10);
+  else if (a === '--format' && args[i + 1]) format = args[++i];
+  else if (a === '--margin' && args[i + 1]) margin = args[++i];
+  else if (a === '--scale' && args[i + 1]) scale = parseFloat(args[++i]);
+  else if (a === '--landscape') landscape = true;
+  else if (a === '--no-print-background') printBackground = false;
+  else if (a === '--header' && args[i + 1]) headerHtml = args[++i];
+  else if (a === '--footer' && args[i + 1]) footerHtml = args[++i];
+  else if (a === '-h' || a === '--help') usage();
+}
+
+if (!input || !outFile) usage('error: --in and --out are required');
+
+// Resolve --in to file:// URL or pass through if already http(s)://
+let pageUrl;
+if (/^https?:\/\//i.test(input)) {
+  pageUrl = input;
+} else {
+  if (!fs.existsSync(input)) {
+    console.error(JSON.stringify({ status: 'error', error: `File not found: ${input}` }));
+    process.exit(1);
+  }
+  pageUrl = 'file://' + path.resolve(input);
+}
+
+// Parse CSS margin shorthand → Playwright margin object
+function parseMargin(css) {
+  const parts = css.trim().split(/\s+/);
+  const [t, r, b, l] = (() => {
+    if (parts.length === 1) return [parts[0], parts[0], parts[0], parts[0]];
+    if (parts.length === 2) return [parts[0], parts[1], parts[0], parts[1]];
+    if (parts.length === 3) return [parts[0], parts[1], parts[2], parts[1]];
+    return [parts[0], parts[1], parts[2], parts[3]];
+  })();
+  return { top: t, right: r, bottom: b, left: l };
+}
+
+// ── Playwright loader (tolerates global npm installs) ─────────────────────────
+function loadPlaywright() {
+  const { execSync } = require('child_process');
+  try {
+    return require('playwright');
+  } catch (_) {}
+  try {
+    const root = execSync('npm root -g', { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+    return require(path.join(root, 'playwright'));
+  } catch (_) {}
+  console.error(
+    JSON.stringify({
+      status: 'error',
+      error: 'playwright not found',
+      hint: 'Run: bash scripts/make.sh fix  (or: npm install -g playwright && npx playwright install chromium)',
+    }),
+  );
+  process.exit(2);
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+(async () => {
+  const { chromium } = loadPlaywright();
+
+  let browser;
+  try {
+    browser = await chromium.launch();
+  } catch (_) {
+    // Chromium binary missing — try installing once
+    const { spawnSync } = require('child_process');
+    const r = spawnSync('npx', ['playwright', 'install', 'chromium'], {
+      stdio: 'inherit',
+      shell: true,
+    });
+    if (r.status !== 0) {
+      console.error(
+        JSON.stringify({
+          status: 'error',
+          error: 'Chromium not installed and auto-install failed',
+          hint: 'Run: npx playwright install chromium',
+        }),
+      );
+      process.exit(2);
+    }
+    browser = await chromium.launch();
+  }
+
+  try {
+    const page = await browser.newPage();
+    page.setDefaultTimeout(60_000);
+    page.setDefaultNavigationTimeout(60_000);
+
+    await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 60_000 });
+
+    // Wait for web fonts to actually load (otherwise body text falls back to
+    // a generic sans-serif while the snapshot is taken).
+    try {
+      await page.waitForFunction(() => document.fonts && document.fonts.ready, { timeout: 15_000 });
+      await page.evaluate(() => document.fonts.ready);
+    } catch (_) {
+      // Best effort — some pages have no @font-face; ignore.
+    }
+
+    // Extra settle window for Chart.js / lazy images / late JS.
+    if (waitMs > 0) await page.waitForTimeout(waitMs);
+
+    const pdfOpts = {
+      path: outFile,
+      format,
+      printBackground,
+      landscape,
+      scale,
+      margin: parseMargin(margin),
+    };
+    if (headerHtml || footerHtml) {
+      pdfOpts.displayHeaderFooter = true;
+      if (headerHtml) pdfOpts.headerTemplate = headerHtml;
+      if (footerHtml) pdfOpts.footerTemplate = footerHtml;
+    }
+
+    await page.pdf(pdfOpts);
+    await browser.close();
+
+    const stat = fs.statSync(outFile);
+    if (stat.size < 5000) {
+      console.error(
+        JSON.stringify({
+          status: 'error',
+          error: 'Output PDF is suspiciously small — page may be blank',
+          hint: 'Open the source HTML in a browser and check for render errors',
+        }),
+      );
+      process.exit(3);
+    }
+
+    console.log(
+      JSON.stringify({
+        status: 'ok',
+        out: outFile,
+        size_kb: Math.round(stat.size / 1024),
+        format,
+        landscape,
+      }),
+    );
+  } catch (e) {
+    if (browser) await browser.close().catch(() => {});
+    console.error(JSON.stringify({ status: 'error', error: String(e) }));
+    process.exit(3);
+  }
+})();

package/server/assets/skills/pdf/scripts/validate/geometry_lint.py

@@ -0,0 +1,124 @@
+"""Lint bounding-box geometry inside a fields.json config.
+
+Catches the two mistakes operators make most often when hand-editing
+``fields.json``:
+
+1. **Overlapping rectangles** (slot vs. slot, slot vs. tag, tag vs.
+   tag), which cause text to land on top of other text.
+2. **Slot boxes that are too short** for the configured font size,
+   which clips glyphs.
+
+The script returns exit code 0 only if no findings are produced.
+
+Run from the skill root::
+
+    python -m scripts.validate.geometry_lint fields.json --max-findings 20
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+
+from scripts.lib.cli_utils import make_parser
+from scripts.lib.geometry import boxes_overlap
+
+
+@dataclass
+class BoxRecord:
+    bbox: list[float]
+    kind: str            # "slot" or "tag"
+    owner: dict          # the original slot dict
+
+
+def _label_for(slot: dict) -> str:
+    return slot.get("description") or slot.get("tag_text") or "<unnamed>"
+
+
+def lint(cfg_path: str, max_findings: int = 20) -> tuple[bool, list[str]]:
+    with open(cfg_path) as handle:
+        cfg = json.load(handle)
+
+    findings: list[str] = []
+    findings.append(f"Read {len(cfg['slots'])} slots from {cfg_path}")
+
+    boxes: list[BoxRecord] = []
+    for slot in cfg["slots"]:
+        if "tag_box" in slot:
+            boxes.append(BoxRecord(slot["tag_box"], "tag", slot))
+        if "slot_box" in slot:
+            boxes.append(BoxRecord(slot["slot_box"], "slot", slot))
+
+    failed = False
+
+    # --- intersection scan ---
+    for i, left in enumerate(boxes):
+        for right in boxes[i + 1 :]:
+            if left.owner["page_no"] != right.owner["page_no"]:
+                continue
+            if not boxes_overlap(left.bbox, right.bbox):
+                continue
+            failed = True
+            if left.owner is right.owner:
+                findings.append(
+                    f"FAILURE: slot/tag overlap inside `{_label_for(left.owner)}`: "
+                    f"{left.bbox} vs {right.bbox}"
+                )
+            else:
+                findings.append(
+                    f"FAILURE: {left.kind} of `{_label_for(left.owner)}` "
+                    f"({left.bbox}) overlaps {right.kind} of "
+                    f"`{_label_for(right.owner)}` ({right.bbox})"
+                )
+            if len(findings) >= max_findings:
+                findings.append("Too many findings; aborting further checks.")
+                return True, findings
+
+    # --- height check ---
+    for record in boxes:
+        if record.kind != "slot":
+            continue
+        glyph_spec = record.owner.get("value")
+        if not glyph_spec:
+            continue
+        glyph_pt = glyph_spec.get("size", 14)
+        slot_h = record.bbox[3] - record.bbox[1]
+        if slot_h < glyph_pt:
+            failed = True
+            findings.append(
+                f"FAILURE: slot height {slot_h} for `{_label_for(record.owner)}` "
+                f"is shorter than glyph size {glyph_pt}; either grow the box or "
+                "shrink value.size."
+            )
+            if len(findings) >= max_findings:
+                findings.append("Too many findings; aborting further checks.")
+                return True, findings
+
+    if not failed:
+        findings.append("SUCCESS: all bounding boxes look sane.")
+    return failed, findings
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = make_parser(
+        "geometry_lint",
+        "Validate bounding-box geometry inside a fields.json file.",
+    )
+    parser.add_argument("cfg_path", help="Path to fields.json.")
+    parser.add_argument(
+        "--max-findings",
+        type=int,
+        default=20,
+        help="Stop reporting after this many findings (default 20).",
+    )
+    args = parser.parse_args(argv)
+
+    failed, findings = lint(args.cfg_path, max_findings=args.max_findings)
+    for line in findings:
+        print(line)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/server/assets/skills/pdf/templates/INDEX.md

@@ -0,0 +1,97 @@
+# Templates Index
+
+Eight production-grade PDF templates — every CREATE / REFORMAT skeleton renders via Playwright
+HTML+CSS → PDF (no token pipeline, no LaTeX). Use them as starting points; copy, re-skin, and
+render.
+
+> **Diversity reminder.** Each skeleton ships with a baseline palette, fonts, and section ordering
+> so the layout demo works out-of-the-box. **Adapt these to the user's brand, topic, mood, or
+> audience every time** — do not return three different documents using the same bronze/gold (menu)
+> or navy (research report) palette. Each README §7 lists the **structural invariants** you must
+> keep and the **swappables** you should vary.
+
+| Slug                      | Route                | Use case                                         | Trigger keywords                                          |
+| ------------------------- | -------------------- | ------------------------------------------------ | --------------------------------------------------------- |
+| bilingual-menu-premium    | CREATE               | Premium bilingual menus                          | "menu", "bilingual menu", "餐厅菜单"                      |
+| brand-guide-2page         | CREATE               | 2-page brand guide                               | "brand guide", "design system"                            |
+| data-viz-report           | CREATE               | Chart-rich data analysis brief                   | "data report", "可视化", "benchmark", "图文报告"          |
+| multi-article-aggregator  | CREATE               | Article digest / anthology                       | "article digest", "newsletter"                            |
+| multilang-research-report | CREATE               | Multi-country research report                    | "research report", "regulatory survey"                    |
+| reformat-default          | REFORMAT             | Default markdown / text / pdf reformat           | "reformat", "markdown to PDF", "重排版"                   |
+| translate-preserve-layout | REFORMAT             | Translate while preserving layout                | "translate PDF", "翻译保版"                               |
+| form-fill-acroform        | FILL                 | Government / official form fill                  | "fill form", "visa form", "签证表"                        |
+| latex-technical-book      | LATEX_TECHNICAL_BOOK | Chinese technical books / engineering monographs | "技术书", "源码解析书", "LaTeX 技术出版", "O'Reilly 风格" |
+
+## Usage
+
+### CREATE — copy a skeleton, fill placeholders, render
+
+```bash
+# 1. Pick a template
+cat templates/INDEX.md            # the file you are reading
+cat templates/<slug>/README.md    # 7-section recipe (when-to-use → generalization)
+
+# 2. Copy the skeleton + edit
+cp templates/<slug>/skeleton.html /tmp/work/page.html
+$EDITOR /tmp/work/page.html       # replace <!-- PLACEHOLDER --> tokens
+
+# 3. Render (15s settle if Chart.js is on the page)
+bash scripts/make.sh render --in /tmp/work/page.html --out /tmp/work/out.pdf --wait 15000
+
+# 4. Verify
+pdfinfo /tmp/work/out.pdf | grep Pages
+open /tmp/work/out.pdf
+```
+
+### REFORMAT — single-command markdown → PDF
+
+```bash
+bash scripts/make.sh reformat \
+  --input doc.md --out report.pdf \
+  --title "My Report" --author "Jane" --accent "#0a7488"
+```
+
+The `reformat-default` template is auto-applied. Pass `--template <slug>` to use a different
+`templates/reformat-*/` skeleton.
+
+### FILL — see [form-fill-acroform/README.md](form-fill-acroform/README.md)
+
+```bash
+bash scripts/make.sh fill probe form.pdf
+```
+
+## Per-template files
+
+Each `templates/<slug>/` contains:
+
+- `README.md` — the full seven-section recipe (when-to-use / pipeline / shape / visual / skeleton /
+  pitfalls / generalization).
+- `skeleton.html` (or `skeleton.json` / `pipeline.md`) — a copy-and-edit starting point with
+  placeholders marked `<!-- PLACEHOLDER -->`.
+- A small helper file when relevant (`terminology.template.json`, `field_values.template.json`).
+
+## Case exemplars
+
+| Case                                           | Source                                                                         | Use when                                                                                                                                                                                                                                                             | Files                                                                                                                                                                                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Goldman China Two Sessions email translation   | EML research report with cid charts                                            | Rich HTML email report must be translated to Chinese PDF while preserving charts/images and links; read `../docs/email-translation-goldman-two-sessions-case.md` first                                                                                               | `translate-preserve-layout/cases/goldman-china-two-sessions-cn.html`                                                                                                                                                                                     |
+| Apple M-series AI static academic data-viz     | Markdown report with Chinese prose + numeric tables                            | Data-heavy Markdown must become an A4 print-academic PDF with source hierarchy preserved and static charts only; read `../docs/markdown-static-academic-data-viz-case.md` first                                                                                      | `data-viz-report/cases/apple-m-ai-static-academic/source.html`                                                                                                                                                                                           |
+| AI voice cloning regulatory survey             | Five-jurisdiction legal/regulatory research prompt                             | Multi-country regulatory survey must become a Chinese A4 print-academic PDF with bilingual research, fact-checking, comparison table, and source ratings; read `../docs/ai-voice-cloning-regulatory-report-case.md` first                                            | `multilang-research-report/cases/ai-voice-cloning-regulatory/source.html`                                                                                                                                                                                |
+| MiniMax web brand guide two-pager              | Live brand website + current MiniMax assets                                    | Website-to-brand-guide PDF where real logo, palette, concise voice rules, and exact two-page A4 pagination matter; read the case README first                                                                                                                        | `brand-guide-2page/cases/minimax-web-brand-guide/README.md`; `brand-guide-2page/cases/minimax-web-brand-guide/source.html`                                                                                                                               |
+| Italian Schengen visa AcroForm fill            | Chinese employment certificate PDF + DOCX travel itinerary + official visa PDF | Fill official visa/Schengen AcroForm from source materials, transform Chinese facts to Latin form values, leave unknowns blank, and report missing fields; read `../docs/italy-schengen-visa-acroform-case.md` first                                                 | `form-fill-acroform/cases/italy-schengen-visa-example/field_values.case.json`; `form-fill-acroform/cases/italy-schengen-visa-example/extract_pdfs_key_info.py`; `form-fill-acroform/cases/italy-schengen-visa-example/USER-FINAL-SUMMARY.template.md` |
+| Annual-report compact financial digest (LaTeX) | 200+ page listed-company annual report PDF                                     | Extract financial highlights and segment revenue, generate static charts, then compile a dense Chinese table-first LaTeX digest when user wants broker-research/academic style without whitespace; read `../docs/annual-report-financial-digest-latex-case.md` first | `data-viz-report/cases/annual-report-financial-digest-latex/source.tex`; `data-viz-report/cases/annual-report-financial-digest-latex/build_charts.py`                                                                                                    |
+| Chinese technical book (LaTeX)                 | Structured HTML / Markdown chapters for a technical book                       | Long-form source-code reading or engineering book needs B5 book typography, O'Reilly-like cover, clickable TOC, code blocks, callouts, and diagrams; read `../docs/latex-technical-book-guide.md` first                                                              | `latex-technical-book/source.tex`; `latex-technical-book/README.md`                                                                                                                                                                                      |
+| Legal contract round-trip professional PDF     | Legacy Word/DOCX Chinese contract template                                     | Convert DOC/DOCX contract to professional A4 PDF + Markdown + HTML + round-trip DOCX with fidelity-loss report; read `../docs/docx-contract-roundtrip-professional-case.md` first                                                                                    | `reformat-default/cases/pku-contract-roundtrip/source.html`; `reformat-default/cases/pku-contract-roundtrip/source.md`; `reformat-default/cases/pku-contract-roundtrip/docx_engine.py`                                                                   |
+
+## When nothing matches
+
+- Document is structurally close to a template → **adapt the closest one** and re-skin (palette +
+  cover archetype). Faster than from-zero authoring.
+- Completely different shape → hand-author HTML following
+  [`../docs/html-pdf-spec.md`](../docs/html-pdf-spec.md) (the mechanical contract) and
+  [`../docs/design-guide.md`](../docs/design-guide.md) (the aesthetic contract). Copy individual
+  primitives (KPI grid, chart card, pill table, conclusion block) from
+  `data-viz-report/skeleton.html`.
+- Still unsure → read a reference PDF first via the READ route:
+  `python3 -m scripts.read_pdf_vision --input <reference.pdf> --pages 1`, understand the structure,
+  then choose.