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

package/server/assets/skills/pdf/docs/pitfalls-index.md

@@ -0,0 +1,798 @@
+# Pitfalls Index — Canonical Query Templates
+
+> **Match-and-fuse, don't read-and-think.** Each entry below is a
+> production-ready prompt template. When the user's incoming query
+> matches a `Match signatures` block, **copy the matching canonical
+> query**, substitute the `Slots` with the user's actual values,
+> and execute it verbatim. Each canonical query already encodes every
+> known pitfall, every verification gate, and every fall-back path
+> for that scenario — there is no extra "trace" to look up.
+>
+> If no signature matches, fall back to [`../SKILL.md`](../SKILL.md) routing.
+> If a partial match (one of two slots fits), prefer **fusing** the
+> matching template's verifications into your own plan rather than
+> writing a new one from scratch.
+>
+> **Universal slot placeholders below** — these are referenced inside
+> every canonical query and resolve at execution time:
+>
+> - `<SKILL>` → `{{DATA_DIR}}/.builtin-skills/pdf`
+> - `<SKILL_XLSX>` → `{{DATA_DIR}}/.builtin-skills/xlsx`
+> - `<TMP>` → a writable scratch dir (e.g. `/tmp/pdf-task-<ts>`)
+
+---
+
+## Quick lookup — match user query to a case
+
+| # | Match keywords | Slots | Canonical §|
+|---|---|---|---|
+| **P1** | brand guide / cover / poster / 品牌指南 / 设计规范 from a website | `BRAND_URL`, `OUTPUT_PATH`, `BRAND_NAME`, `PAGE_COUNT(default 2)`, `AUDIENCE(intl/US)` | §P1 |
+| **P2** | bilingual menu / 双语菜单 / formal printed deliverable / certificate / two-pager | `LANG_A`, `LANG_B`, `RESTAURANT_TYPE`, `ITEMS_JSON`, `OUTPUT_PATH`, `AUDIENCE` | §P2 |
+| **P3** | markdown→PDF / convert structured text to chart-rich PDF / 可视化报告 / data brief | `INPUT_PATH(.md/.csv)`, `OUTPUT_PATH`, `CHART_COUNT`, `THEME(default light)` | §P3 |
+| **P4** | research report across N jurisdictions / multi-region regulatory survey / 多国监管 | `TOPIC`, `JURISDICTIONS[]`, `OUTPUT_PDF`, `DEADLINE_MIN(default 30)` | §P4 |
+| **P5** | translate this <EML/PDF> to <lang> preserving layout / 翻译保版 | `INPUT_PATH(.eml/.pdf)`, `TARGET_LANG`, `OUTPUT_PATH` | §P5 |
+| **P6** | find <X> in this <100+ page PDF> / 长 PDF 定向提取 / extract specific data from annual report | `PDF_PATH`, `TARGET_QUERY`, `MAX_OUTPUT_PAGES(optional)` | §P6 |
+| **P7** | convert <240-page financial PDF> to Excel/Word/Markdown / 复杂金融排版 PDF 转格式 | `PDF_PATH`, `OUTPUT_FORMAT`, `OUTPUT_PATH`, `STATEMENTS[]` | §P7 |
+| **P8** | fill out this PDF form / AcroForm / visa / tax / contract / 表单填写 | `FORM_PDF`, `MATERIALS[]`, `OUTPUT_PDF`, `MISSING_FIELDS_REPORT(true)` | §P8 |
+| **P9** | export 10k+ row spreadsheet as PDF / 大表打印 / tabular → PDF | `INPUT_XLSX`, `OUTPUT_PDF`, `ORIENTATION`, `REPEAT_HEADER`, `FULL_OR_PREVIEW` | §P9 |
+| **P10** | convert <DOCX/PDF/MD/HTML> to <formats> with fidelity loss report / 双向转换 | `INPUT_PATH`, `TARGET_FORMATS[]`, `OUTPUT_DIR` | §P10 |
+
+---
+
+## P1 — Branded paged PDF from web content
+
+### Match signatures
+
+- "做一份 {BRAND_NAME}（{BRAND_URL}）的 brand guide / 品牌指南 PDF"
+- "make a brand-guide / cover / poster PDF from {BRAND_URL}"
+- "把 {site} 抓取的品牌元素整理成双页 PDF"
+- "create a 2-page design system overview for {company}"
+
+### Canonical query
+
+```
+TASK: Generate a {PAGE_COUNT}-page brand guide PDF for {BRAND_NAME} from
+      {BRAND_URL}, output to {OUTPUT_PATH}.
+
+STEP 1 — Environment preflight (mandatory)
+  bash <SKILL>/scripts/make.sh check 2><TMP>/check.log
+  # WARN/FAIL → bash <SKILL>/scripts/make.sh fix && re-run check
+
+STEP 2 — Brand asset extraction (precise, not inferred)
+  curl -sL "{BRAND_URL}" > <TMP>/brand.html 2><TMP>/curl.log
+  # Palette — exact hex from CSS/SVG (NEVER infer from prose)
+  grep -oE '#[0-9a-fA-F]{6}' <TMP>/brand.html | sort -u > <TMP>/palette.txt
+  grep -oP 'fill="\K#[0-9a-fA-F]{6}' <TMP>/brand.html | sort -u >> <TMP>/palette.txt
+  # Fonts
+  grep -oiE 'font-family[: ][^;}"]+' <TMP>/brand.html | sort -u
+  # Logo — download SVG / PNG separately
+  # If <link rel="stylesheet"> points off-domain, fetch each one and grep colors there too.
+
+STEP 3 — Template + fill placeholders
+  cp <SKILL>/templates/brand-guide-2page/skeleton.html <TMP>/page.html
+  # Replace <!-- PLACEHOLDER --> tokens with:
+  #   - {BRAND_NAME}, tagline (LLM-extracted from site if user didn't supply)
+  #   - 6-color palette from <TMP>/palette.txt (top 6 unique hex)
+  #   - Font stack from grep above
+  #   - Logo as <img src="data:image/...;base64,..."> or file:// reference
+
+STEP 4 — Render (mandatory --format)
+  bash <SKILL>/scripts/make.sh render \
+    --in <TMP>/page.html --out {OUTPUT_PATH} \
+    --format <A4 if AUDIENCE=intl|CJK else Letter> --wait 15000
+  # Never rely on the renderer default; Chromium overrides CSS @page.
+
+STEP 5 — Verification (BOTH gates mandatory)
+  pdfinfo {OUTPUT_PATH} | grep "Page size"
+  # Must print:  595.276 x 841.89 pts (A4)   OR   612 x 792 pts (Letter)
+  # Mismatch → go back to STEP 4, do not ship.
+  pdfimages -list {OUTPUT_PATH} | tail -n +3 | wc -l
+  # Must be ≥ 1 (logo); typically ≥ 6 (logo + palette swatches + samples).
+  # If 0 → Chart.js / fonts didn't settle. Bump --wait 30000, set
+  # Chart.defaults.animation = false, wrap canvases in .avoid-break.
+
+STEP 6 — Deliver with evidence
+  Report: pdfinfo "Page size" line + pdfimages count + screenshot of page 1.
+
+CONSTRAINTS (universal — do not violate):
+  - NEVER `2>/dev/null` — redirect to <TMP>/*.log and grep on demand.
+  - Palette MUST come from CSS/SVG hex, never from rendered prose ("looks blue-ish").
+  - Always pass --format explicitly to make.sh render.
+```
+
+---
+
+## P2 — Bilingual menu / formal printed two-pager
+
+### Match signatures
+
+- "做一份 {LANG_A}-{LANG_B} 双语 {RESTAURANT_TYPE} 菜单 PDF"
+- "make a {LANG_A}/{LANG_B} bilingual menu / wine list / certificate"
+- "design a 2-page formal printed PDF for {use_case}"
+
+### Canonical query
+
+```
+TASK: Render a 2-page bilingual ({LANG_A} + {LANG_B}) {RESTAURANT_TYPE}
+      menu PDF from items in {ITEMS_JSON}, output to {OUTPUT_PATH}.
+
+STEP 1 — Preflight
+  bash <SKILL>/scripts/make.sh check 2><TMP>/check.log
+
+STEP 2 — Use the canonical template (do not author from scratch)
+  cp <SKILL>/templates/bilingual-menu-premium/skeleton.html <TMP>/menu.html
+  # Inject ITEMS_JSON: each item has {LANG_A_name, LANG_B_name, price, category}
+  # Categories ≥ 3 (e.g. 前菜/Sushi/甘味). Pricing follows pricing_model.
+
+STEP 3 — CJK font cascade verification
+  # If LANG_A or LANG_B ∈ {zh, ja, ko}, the HTML MUST declare:
+  #   font-family: -apple-system, "PingFang SC", "Hiragino Sans",
+  #                "Apple SD Gothic Neo", "Helvetica Neue", sans-serif;
+  # Cascade ORDER MATTERS — wrong order renders SC chars in JP forms.
+
+STEP 4 — Render (canonical CLI shape)
+  bash <SKILL>/scripts/make.sh render \
+    --in <TMP>/menu.html --out {OUTPUT_PATH} \
+    --format A4 --wait 15000
+  # The flag is `--in` (not --input), `--out` (not --output).
+  # A4 by default for CJK / international audiences.
+
+STEP 5 — Verification (CJK-aware)
+  pdfinfo {OUTPUT_PATH} | grep "Page size"   # 595x841 pts (A4)
+  pdfimages -list {OUTPUT_PATH} | tail -n +3 | wc -l
+  pdftotext -layout {OUTPUT_PATH} - | head -40
+  # Look for [ ] [ ] tofu boxes in the CJK output. If any → install
+  # missing CJK font (`brew install font-noto-sans-cjk-sc`), re-render.
+
+STEP 6 — Spot-check first page visually (optional but recommended)
+  pdftoppm -r 150 -png -f 1 -l 1 {OUTPUT_PATH} <TMP>/preview
+  # Open <TMP>/preview-1.png to confirm typography & balance.
+
+CONSTRAINTS:
+  - Memorize the canonical render CLI shape: --in / --out (NOT --input / --output).
+  - For CJK languages, verify font cascade ORDER, not just presence.
+  - --format defaults to A4 here because menus are international/CJK; for
+    US-only steakhouses pass --format Letter explicitly.
+```
+
+---
+
+## P3 — Markdown / structured text → chart-rich PDF
+
+### Match signatures
+
+- "把 {INPUT_PATH} (markdown/csv) 转成含图表的 PDF 报告"
+- "convert this benchmark / dataset / md into a visualized PDF"
+- "make a data brief from {INPUT_PATH}"
+- "可视化报告 / 图文报告 / 评测报告 / data report"
+
+### Canonical query
+
+```
+TASK: Build a chart-rich PDF report from {INPUT_PATH}, with approximately
+      {CHART_COUNT} charts (auto-estimate if unspecified), output to {OUTPUT_PATH}.
+
+STEP 1 — Preflight
+  bash <SKILL>/scripts/make.sh check 2><TMP>/check.log
+  # Includes Playwright Chromium check; fix if WARN.
+
+STEP 2 — Choose template
+  cp -r <SKILL>/templates/data-viz-report/* <TMP>/
+  # The skeleton.html has KPI grid, chart-card, takeaway-row, conclusion primitives.
+  # If acceptance criteria require source hierarchy preservation, print-academic style,
+  # and static charts only (no Chart.js/ECharts/D3/Plotly), load:
+  #   <SKILL>/docs/markdown-static-academic-data-viz-case.md
+  # and follow that case instead of the Chart.js skeleton path.
+
+STEP 3 — Build content.json (mandatory ensure_ascii=False)
+  python3 <<EOF
+  import json, pathlib
+  payload = {
+      "title": "...",
+      "kpis": [...],
+      "charts": [{"id": "ch1", "type": "bar", "data": {...}}, ...],
+      "tables": [...],
+      "conclusion": "...",
+  }
+  pathlib.Path("<TMP>/content.json").write_text(
+      json.dumps(payload, ensure_ascii=False, indent=2),
+      encoding="utf-8",
+  )
+  EOF
+  # NEVER hand-concatenate JSON strings. CJK quotes / em-dashes break json.load.
+
+STEP 4 — Render (mandatory --format + long --wait for charts)
+  bash <SKILL>/scripts/make.sh render \
+    --in <TMP>/page.html --out {OUTPUT_PATH} \
+    --format A4 --wait 15000
+  # 15s baseline; if charts are non-trivial (>30 series, animated), use 25000.
+
+STEP 5 — Verification (both gates mandatory; pdftotext alone is NOT enough)
+  pdfinfo {OUTPUT_PATH} | grep "Page size"
+  IMG_COUNT=$(pdfimages -list {OUTPUT_PATH} | tail -n +3 | wc -l)
+  echo "Image count: $IMG_COUNT (expected ≥ {CHART_COUNT})"
+  # IMG_COUNT < CHART_COUNT → at least one chart is a blank canvas.
+  pdftotext -layout {OUTPUT_PATH} - | head -40   # body text sanity
+
+STEP 6 — Chart-rendering recovery (when STEP 5 image count is low)
+  # 1. In the source HTML's <script>: Chart.defaults.animation = false;
+  # 2. Wrap every <canvas> parent: <div class="chart-card avoid-break">
+  # 3. Increase --wait to 30000
+  # 4. Re-render and re-verify.
+  # See <SKILL>/docs/troubleshooting.md "Chart.js render-timing checklist".
+
+STEP 7 — For matplotlib pipelines (PNG → embedded into HTML)
+  ls -lh <TMP>/build/*.png   # the intermediate PNGs MUST exist and be > 5 KB each.
+
+CONSTRAINTS:
+  - JSON config files: json.dumps(payload, ensure_ascii=False, indent=2). Always.
+  - `pdftotext` cannot see images and silently passes a chart-less PDF.
+    pdfimages count is the ONLY reliable chart-presence check.
+  - Don't 2>/dev/null any of the verification commands.
+```
+
+---
+
+## P4 — Multi-jurisdiction research with parallel sub-agents
+
+### Match signatures
+
+- "研究 {TOPIC} 在 {JURISDICTIONS} 的 {regulatory|market|enforcement} 情况"
+- "deep research on {topic} across {N} regions, output a synthesised PDF"
+- "multi-country survey of {policy area}, parallel workers"
+
+### Canonical query
+
+```
+TASK: Produce a synthesised PDF report on {TOPIC} covering jurisdictions
+      {JURISDICTIONS[]}, output to {OUTPUT_PDF} within {DEADLINE_MIN} minutes.
+
+STEP 0 — Load progressive case when applicable
+  If TOPIC is AI voice cloning / synthetic voice / deepfake audio, or the
+  acceptance criteria require laws + regulators + cases + self-regulation +
+  source reliability ratings, read:
+    <SKILL>/docs/ai-voice-cloning-regulatory-report-case.md
+  Reuse its bounded worker prompts, terminology rules, fact-check table,
+  and optimized source HTML.
+
+STEP 1 — Plan the fan-out (timeout-with-degrade is mandatory)
+  N background research sub-agents (task tool with
+  run_in_background: true, one per jurisdiction) + a synthesis step
+  after collecting their outputs. CRITICAL rules:
+  - Launch every research sub-agent with run_in_background: true.
+    Foreground task calls run sequentially and block — they cannot
+    honor the deadline rule below.
+  - Poll with task_query; collect finished reports with task_output.
+    At T+{DEADLINE_MIN}, task_stop the stragglers and proceed.
+  - Each sub-agent writes its report to <TMP>/report-<jurisdiction>.md
+    and returns only a short summary.
+  - The synthesis step explicitly allows partial input: "If at deadline
+    T+{DEADLINE_MIN}, fewer than N jurisdictions have delivered, ship a
+    partial PDF labelled 'Region X: data not yet available' for the
+    missing ones."
+
+STEP 2 — Per-sub-agent prompt SHAPE (specific, not open-ended)
+  GOOD:  "Find the 5 enacted statutes most-cited by {jurisdiction}'s
+          enforcement agencies on {topic} since 2020. For each: cite,
+          1-line summary, primary agency, last enforcement action date."
+  BAD:   "Research {jurisdiction}'s regulatory framework for {topic}."
+  # Open-ended prompts run for hours and stall the whole batch.
+
+STEP 3 — Synthesis (yourself, after the sub-agents return)
+  Cross-reference all received jurisdiction reports. Build a comparison
+  table (rows=jurisdictions, cols=key dimensions). Highlight 3 themes
+  that appear in ≥3 jurisdictions and 3 unique-to-one-region findings.
+  Then render via <SKILL>/scripts/make.sh render with the
+  templates/multilang-research-report skeleton, --format A4 --wait 15000.
+
+STEP 4 — Failure handling
+  A sub-agent errors or returns garbage → relaunch it ONCE with the same
+    bounded prompt.
+  Still failing → proceed with the remaining N-1 reports; the partial-ship
+    rule from STEP 1 covers the gap.
+
+STEP 5 — Final verify (after synthesis renders)
+  pdfinfo {OUTPUT_PDF} | grep Pages       # expected ≥ N+2 (intro + per-region + comparison)
+  pdfinfo {OUTPUT_PDF} | grep "Page size" # match A4
+  pdfimages -list {OUTPUT_PDF} | tail -n +3 | wc -l
+
+CONSTRAINTS:
+  - NEVER launch the fan-out without an explicit timeout-with-degrade rule.
+  - Sub-agent prompts MUST be specific. "全面研究" / "全面分析" = guaranteed stall.
+  - Don't suppress stderr in any sub-agent prompt — log to <TMP>/<worker>.log.
+```
+
+---
+
+## P5 — Translate EML / PDF to {lang} preserving layout
+
+### Match signatures
+
+- "把这份 {INPUT_PATH} (.eml/.pdf) 翻译成 {TARGET_LANG}，保留排版"
+- "translate this {Goldman Sachs / formal} report to {lang}, output PDF"
+- "翻译保版 / preserve-layout translation"
+
+### Canonical query
+
+```
+TASK: Translate {INPUT_PATH} into {TARGET_LANG} while preserving the
+      original page geometry, figures, and tables. Output to {OUTPUT_PATH}.
+
+STEP 1 — Source parsing
+  Case A — INPUT_PATH ends with .eml:
+    # Progressive case for rich research-email HTML with optimized translation prompt:
+    #   <SKILL>/docs/email-translation-goldman-two-sessions-case.md
+    python3 <<EOF
+    import email, re
+    msg = email.message_from_file(open("{INPUT_PATH}"))
+    # Walk parts: extract text/html, extract attachments, replace cid: refs
+    # with data: URIs so the rendered HTML is self-contained.
+    EOF
+
+  Case B — INPUT_PATH ends with .pdf:
+    # Use pdfplumber for prose pages; vision per-page for chart/table pages
+    # (see §P7 if the input is a financial doc).
+
+STEP 2 — Translation (call LLM, never hand-write for long inputs)
+  Use the llm-call skill, batched per page or per logical block.
+  For rich EML research reports, copy the optimized prompt from the Goldman case;
+  it enforces JSON id parity, terminology freeze, numeric preservation, and QA.
+  STRICTLY PRESERVE verbatim:
+  - Numbers, dates, currency symbols, percentages
+  - Proper nouns (people, companies, fund codes, ticker symbols)
+  - Already-target-lang words (don't double-translate)
+  Only translate prose.
+
+STEP 3 — Use the layout-preserving template
+  cp -r <SKILL>/templates/translate-preserve-layout/* <TMP>/
+  # The skeleton mirrors the source's page grid; substitute translated
+  # blocks into the page-grid slots. Don't author HTML from scratch.
+  # For rich EML HTML, prefer mutating the original HTML in place to preserve
+  # table grid, hrefs, and img src (see Goldman case).
+
+STEP 4 — Render
+  bash <SKILL>/scripts/make.sh render \
+    --in <TMP>/translated.html --out {OUTPUT_PATH} \
+    --format <match source page size; default A4> --wait 15000
+
+STEP 5 — Verification
+  pdfinfo {OUTPUT_PATH} | grep "Page size"
+  # Must MATCH the source PDF/EML's page size.
+  pdfimages -list {OUTPUT_PATH} | tail -n +3 | wc -l
+  # Must equal the source's image count (figures preserved).
+  pdftotext -layout {OUTPUT_PATH} - | head -60   # confirm target lang text
+
+STEP 6 — Cross-check verbatim items
+  Spot-check 5 numeric values + 3 proper nouns: must appear unchanged
+  in the translated PDF.
+
+CONSTRAINTS:
+  - Don't hand-translate long financial / legal text — call LLM via llm-call.
+  - Use the translate-preserve-layout template; don't re-author the grid.
+  - Number / date / proper-noun preservation is non-negotiable.
+```
+
+---
+
+## P6 — Targeted extraction from a 100+ page PDF
+
+### Match signatures
+
+- "在这份 {PDF_PATH}（{N}页年报/招股书）里找 {TARGET_QUERY}"
+- "extract {metric/section} from this annual report / prospectus / white paper"
+- "what does {long PDF} say about {topic}"
+
+### Canonical query
+
+```
+TASK: Locate and extract {TARGET_QUERY} from {PDF_PATH}, returning at most
+      {MAX_OUTPUT_PAGES or 5} pages of relevant content.
+
+STEP 1 — Probe page count + structure (cheap, mandatory)
+  pdfinfo "{PDF_PATH}" | grep -E "Pages|Encrypted"
+  # Three thresholds determine path:
+  #   ≤20 pages → skip locate, pdfplumber the whole thing.
+  #   21-200 pages → locate-first mandatory.
+  #   >200 pages → ALWAYS build heading index FIRST (skip blind grep entirely).
+
+STEP 2 — Build heading index (paths in cheapest-first order)
+
+  Path A — pypdf outline (cheapest):
+    python3 - <<EOF
+    from pypdf import PdfReader
+    doc = PdfReader("{PDF_PATH}")
+    def walk(items, depth=0):
+        for it in items:
+            if isinstance(it, list):
+                walk(it, depth + 1)
+            else:
+                p = doc.get_destination_page_number(it) + 1
+                print(f"{'  '*depth}{it.title}  -> p{p}")
+    walk(doc.outline)
+    EOF
+
+  Path B — printed TOC (when outline empty):
+    pdftotext -layout -f 1 -l 5 "{PDF_PATH}" - | head -120
+    # Note: printed page numbers may have a front-matter offset (cover,
+    # copyright, preface = 2-10 unnumbered pages). Add the offset before
+    # slicing.
+
+  Path C — full-text grep (last resort, BUDGET = 2 attempts max):
+    pdftotext -layout "{PDF_PATH}" - | grep -in "{KEYWORD}"
+    # If 2 different keywords don't land on the target, STOP and use Path A/B.
+
+STEP 3 — Once target pages identified
+  Determine page nature:
+  - Pure prose / simple table → pdfplumber recipe (§3.1 in read-guide)
+  - Chart / diagram / financial table → vision PER PAGE (mandatory, see §P7)
+    python3 -m scripts.read_pdf_vision --input "{PDF_PATH}" --pages N
+
+STEP 4 — JSON config (if writing intermediate file)
+  json.dumps(payload, ensure_ascii=False, indent=2)
+  # Mandatory for any file passed to a downstream tool.
+
+STEP 5 — Deliver
+  Quote the relevant pages, cite page numbers, and if the user asked for
+  a number, also cite the line / row context surrounding it.
+
+CONSTRAINTS:
+  - >200 pages + targeted query → BUILD INDEX FIRST. No blind greps.
+  - 2 blind grep limit applies regardless of page count.
+  - NEVER 2>/dev/null any extraction step. Use <TMP>/grep.log.
+```
+
+---
+
+## P7 — Complex financial PDF → structured format
+
+### Match signatures
+
+- "把这份 {PDF_PATH}（240页 financial report / 10-K / 招股书）转成 {Excel/Word/Markdown}"
+- "convert balance sheet / income statement / cash-flow from {PDF} to {format}"
+- "extract financial tables from {annual report}"
+
+### Canonical query
+
+```
+TASK: Convert {STATEMENTS[]} (e.g. balance sheet, income statement,
+      cash-flow, debt schedule) from {PDF_PATH} into {OUTPUT_FORMAT},
+      output to {OUTPUT_PATH}, preserving every cell.
+
+STEP 1 — Locate financial-table pages (run §P6 first)
+  Use §P6's heading-index path to list pages containing each statement.
+  Output: PAGES = [p_balance, p_income, p_cashflow, ...].
+
+STEP 2 — Vision per page (MANDATORY — pdfplumber FORBIDDEN here)
+  # Reason: complex financial layout uses multi-level headers, merged
+  # cells, dotted leader lines, footnoted sub-totals. pdfplumber's
+  # extract_text returns scrambled fragments (`9,19109,190` for two
+  # adjacent numbers); extract_tables needs a clean grid these layouts
+  # never have.
+
+  for p in $PAGES; do
+    python3 -m scripts.read_pdf_vision \
+      --input "{PDF_PATH}" --pages $p \
+      --prompt "For every table on this page output one row per cell:
+                header_l1 | header_l2 | row_label | value | footnote_ref.
+                Preserve every sub-total and footnote marker. Use - for
+                empty cells. Output as TSV." \
+      --json 2><TMP>/vision-p$p.log > <TMP>/vision-p$p.json
+  done
+
+STEP 3 — Parse vision output
+  python3 <<EOF
+  import json, pathlib
+  rows = []
+  for p in PAGES:
+      data = json.loads(pathlib.Path(f"<TMP>/vision-p{p}.json").read_text())
+      # Vision output is in chunks[0].text; parse the TSV.
+      for line in data["chunks"][0]["text"].splitlines():
+          parts = line.split("\t")
+          if len(parts) == 5:
+              rows.append({"page": p, "l1": parts[0], "l2": parts[1],
+                           "label": parts[2], "value": parts[3],
+                           "footnote": parts[4]})
+  EOF
+
+STEP 4 — Write to OUTPUT_FORMAT
+
+  Case A — OUTPUT_FORMAT = xlsx:
+    # See [xlsx] §X4. One sheet per statement. Column A = label,
+    # data = pure dump (this leg has no derived values; if you compute
+    # totals/margins, switch to formula-first per [xlsx] §X5).
+
+  Case B — OUTPUT_FORMAT = docx:
+    # Use docx; render each statement as a Word table with
+    # multi-level headers preserved.
+
+  Case C — OUTPUT_FORMAT = md:
+    # Use Markdown tables; multi-level headers expand to a flat header row.
+
+STEP 5 — Verification
+  Spot-check 3 sub-totals across statements: read them off the source PDF
+  visually, compare to the converted output. Mismatch → re-run vision
+  with a more explicit prompt for that page, never patch by hand.
+
+CONSTRAINTS:
+  - pdfplumber.extract_tables on financial layouts is FORBIDDEN even when
+    the PDF is text-native. Visual structure complexity > text-native check.
+  - Vision MUST be per-page (`--pages N`). A range like `--pages 1-30`
+    stitches pages together and mis-attributes values.
+  - Don't 2>/dev/null vision calls — the daemon log on stderr is the only
+    debugging signal.
+```
+
+---
+
+## P8 — AcroForm / PDF form filling
+
+### Match signatures
+
+- "填这份 {FORM_PDF} (visa / tax / contract)，材料是 {MATERIALS[]}"
+- "fill out PDF form / AcroForm with the supplied values"
+- "把 {employment_letter / itinerary} 里的信息填到 {visa_form}"
+
+### Canonical query
+
+```
+TASK: Fill {FORM_PDF} using values extracted from {MATERIALS[]},
+      output to {OUTPUT_PDF}. Report missing fields = {MISSING_FIELDS_REPORT}.
+
+STEP 1 — Probe form type
+  bash <SKILL>/scripts/make.sh fill probe "{FORM_PDF}"
+  # Output: acroform=true → §B path; acroform=false → §C overlay path.
+
+STEP 2 — Inspect fields (§B path only)
+  bash <SKILL>/scripts/make.sh fill inspect "{FORM_PDF}" <TMP>/meta.json
+  # Each record: {qname, page_no, type, box, on_value/off_value/choice_options}.
+
+  # Progressive case: if FORM_PDF is an Italian / Schengen visa application and
+  # MATERIALS include Chinese employment certificate + travel itinerary, read:
+  #   <SKILL>/docs/italy-schengen-visa-acroform-case.md
+  # It includes extract_pdfs_key_info, uppercase pinyin/date transforms,
+  # missing-fields report, and exact verification evidence.
+
+STEP 3 — Extract values from MATERIALS[]
+  For each material:
+  - Simple PDF (passport scan with text layer) → pdfplumber
+  - Complex PDF (employment letter with letterhead, stamps, multi-column)
+    → vision per page per §P7
+  - DOCX itinerary → docx read
+  Build the qname → value mapping.
+
+STEP 4 — Build values.json (NEW array schema)
+  python3 <<EOF
+  import json, pathlib
+  values = [
+      {"qname": "person.last_name", "page_no": 1, "set_to": "Park"},
+      {"qname": "person.first_name", "page_no": 1, "set_to": "Joon"},
+      # Checkbox: use the field's literal on_value, NOT "true"/"false"
+      {"qname": "is_adult", "page_no": 1, "set_to": "/On"},
+  ]
+  pathlib.Path("<TMP>/values.json").write_text(
+      json.dumps(values, ensure_ascii=False, indent=2),
+      encoding="utf-8",
+  )
+  EOF
+
+STEP 5 — Apply
+  bash <SKILL>/scripts/make.sh fill apply \
+    "{FORM_PDF}" <TMP>/values.json "{OUTPUT_PDF}"
+
+  # If you must skip the wrapper (custom validation / batch driver),
+  # USE EXACTLY THIS pypdf snippet — see <SKILL>/docs/forms-guide.md §B.4.1:
+  python3 <<EOF
+  from pypdf import PdfReader, PdfWriter
+  src = PdfReader("{FORM_PDF}")
+  out = PdfWriter(clone_from=src)             # ← THE constructor
+  for page_no, vals in values_by_page.items():
+      out.update_page_form_field_values(
+          out.pages[page_no - 1], vals,
+          auto_regenerate=False,
+      )
+  out.set_need_appearances_writer(True)        # ← MANDATORY
+  with open("{OUTPUT_PDF}", "wb") as fh:
+      out.write(fh)
+  EOF
+  # NEVER use any of these — they "succeed silently" (no error, no values):
+  #   - PdfWriter() + clone_reader_document_root(src)
+  #   - patching page["/Annots"] /V directly
+  #   - PdfWriter() + append_pages_from_reader(src)
+  #   - pypdf 1.x camelCase updatePageFormFieldValues (removed)
+
+STEP 6 — Verify
+  bash <SKILL>/scripts/make.sh fill rasterize "{OUTPUT_PDF}" <TMP>/verify/
+  # Open <TMP>/verify/page_*.png and visually confirm each filled field.
+
+STEP 7 — Missing-fields report (if MISSING_FIELDS_REPORT)
+  Print: "Filled X of Y fields. Missing: <qname>, <qname>, …"
+  For each missing: state which MATERIALS[] would have provided it.
+
+CONSTRAINTS:
+  - The pypdf snippet in STEP 5 is THE only working pattern. Don't try variants.
+  - Checkboxes: write the literal on_value (`/On`, `/Yes`, `/Choice2`),
+    never `"true"`/`"false"`/`true`/`1`.
+  - Don't 2>/dev/null the apply step — silent-failure is the dominant mode.
+```
+
+---
+
+## P9 — Tabular data → printable PDF
+
+### Match signatures
+
+- "把这份 {INPUT_XLSX}（{N} 行）导出成 PDF / 打印"
+- "export 10k+ rows as PDF, landscape, repeat header"
+- "{xlsx} 转 PDF 可打印"
+
+### Canonical query
+
+```
+TASK: Convert {INPUT_XLSX} (N rows) to PDF at {OUTPUT_PDF} with
+      orientation={ORIENTATION}, repeat_header={REPEAT_HEADER},
+      mode={FULL_OR_PREVIEW}.
+
+STEP 0 — Strict wide-table / Superstore route check
+  If the request is a multi-format Excel conversion package (CSV + JSON +
+  PDF + CSV→Excel reverse validation), and the PDF must be HTML→PDF with
+  A4 landscape, repeated headers, all columns visible, no truncation, and
+  no CSS counters, load:
+    <SKILL_XLSX>/docs/superstore-multiformat-conversion-case.md
+  Follow its HTML-source workflow instead of the LibreOffice path below.
+
+STEP 1 — Sanity probe
+  python3 -c "import pandas as pd; df = pd.read_excel('{INPUT_XLSX}'); print(len(df))"
+  # If row_count > 500 AND user didn't state mode → STOP and ASK:
+  #   "This dataset has N rows. Full export will produce a ~XX MB PDF
+  #    (estimated YY pages). Do you want full or first-N preview?"
+
+STEP 2 — Configure print settings (openpyxl)
+  python3 <<EOF
+  from openpyxl import load_workbook
+  book = load_workbook("{INPUT_XLSX}")
+  ws = book.active
+  ws.page_setup.orientation = "{ORIENTATION}"   # 'landscape' or 'portrait'
+  ws.page_setup.fitToWidth = 1
+  ws.page_setup.fitToHeight = 0
+  if {REPEAT_HEADER}:
+      ws.print_title_rows = "1:1"               # repeat header on every page
+  ws.print_options.gridLines = True
+  book.save("<TMP>/printable.xlsx")
+  EOF
+
+STEP 3 — Convert via LibreOffice (NOT openpyxl-native; print settings need soffice)
+  python3 <SKILL_XLSX>/scripts/office/soffice.py \
+    --headless --convert-to pdf --outdir <TMP> <TMP>/printable.xlsx \
+    2><TMP>/soffice.log
+  mv <TMP>/printable.pdf "{OUTPUT_PDF}"
+
+STEP 4 — VERIFY (mandatory because soffice may ignore print settings)
+  pdfinfo "{OUTPUT_PDF}" | grep -E "Pages|Page size"
+  ls -lh "{OUTPUT_PDF}"
+  # If size > 50 MB and user wanted preview → mode mismatch; rerun.
+
+  # Open page 1 + last page visually:
+  PAGES=$(pdfinfo "{OUTPUT_PDF}" | awk '/^Pages/{print $2}')
+  pdftoppm -r 100 -png -f 1 -l 1 "{OUTPUT_PDF}" <TMP>/p1
+  pdftoppm -r 100 -png -f $PAGES -l $PAGES "{OUTPUT_PDF}" <TMP>/last
+  # Check: page 1 has the header; last page rows are not truncated;
+  # orientation looks right.
+
+STEP 5 — Recovery: print settings didn't survive soffice
+  Fall back to rendering via the pdf HTML pipeline:
+  - For Superstore-like wide data, use the ready workflow and editable HTML
+    artifact pattern in <SKILL_XLSX>/docs/superstore-multiformat-conversion-case.md.
+  - Convert xlsx → dense HTML table with @page A4 landscape and
+    thead { display: table-header-group; }.
+  - Use bash <SKILL>/scripts/make.sh render with --format A4 --landscape.
+  - Verify page size, repeated header, all headers present, and no ellipsis.
+
+CONSTRAINTS:
+  - row_count > 500 + no mode → ASK before producing a 50+ MB PDF.
+  - Never trust openpyxl's print settings without re-opening the converted
+    PDF and visually checking page 1 + last page.
+  - Don't 2>/dev/null soffice — its stderr explains why settings failed.
+```
+
+---
+
+## P10 — DOCX ↔ PDF / MD / HTML round-trip with fidelity report
+
+> Progressive case: for legal/contract Word templates where the PDF must look professional (formal cover, fill lines, signature/seal tables), read [`docx-contract-roundtrip-professional-case.md`](docx-contract-roundtrip-professional-case.md) before executing the generic P10 steps. Reuse its editable HTML artifact instead of shipping a raw Pandoc/LibreOffice export.
+
+### Match signatures
+
+- "把这份 {INPUT_PATH} (.docx/.pdf/.md) 转成 {TARGET_FORMATS[]}，并评估 fidelity loss"
+- "convert {contract / report} to PDF + MD + HTML, tell me what's lost"
+- "DOCX 双向转换 / round-trip"
+
+### Canonical query
+
+```
+TASK: Convert {INPUT_PATH} into each format in {TARGET_FORMATS[]} and
+      produce a fidelity-loss inventory. Output to {OUTPUT_DIR}.
+
+STEP 1 — Normalize input
+  Case A — INPUT_PATH ends with .doc (legacy binary):
+    python3 <SKILL_XLSX>/scripts/office/soffice.py \
+      --headless --convert-to docx --outdir <TMP> "{INPUT_PATH}" \
+      2><TMP>/soffice.log
+    INPUT_PATH=<TMP>/<basename>.docx
+
+STEP 2 — Detect structural elements that risk fidelity loss
+  python3 <<EOF
+  from docx import Document
+  d = Document("{INPUT_PATH}")
+  # Inventory:
+  # - Tables with merged cells (rowspan/colspan)
+  # - Headers / footers with content
+  # - Footnotes / endnotes / comments
+  # - Embedded objects (Excel ranges, Visio shapes, OLE)
+  # - Tracked changes / revisions
+  # - Section breaks with different page sizes
+  EOF
+
+STEP 3 — Convert to each TARGET_FORMAT (parallel)
+  For PDF: native DOCX→PDF render/export first (docx docx_to_pdf.py or
+           LibreOffice/soffice export) → verify. Do NOT route DOCX through
+           Markdown/HTML just to make a PDF; that loses Word layout. Use
+           HTML→PDF only if the user asks for redesign/recomposition or direct
+           render is visibly unacceptable, and state that decision.
+  For MD:  pandoc {INPUT_PATH} -o {OUTPUT_DIR}/output.md
+  For HTML: pandoc {INPUT_PATH} -o {OUTPUT_DIR}/output.html --self-contained
+
+STEP 4 — Fidelity-loss inventory (mandatory deliverable)
+  Produce a table:
+  | Element | DOCX | PDF | MD | HTML | Severity |
+  |---|---|---|---|---|---|
+  | Tables (merged cells) | ✓ | ✓ | LOST → flat | LOST → flat | HIGH |
+  | Headers / footers | ✓ | ✓ | LOST | LOST | MED |
+  | Footnotes | ✓ | ✓ | LOST | LOST | MED |
+  | Comments / tracked changes | ✓ | LOST | LOST | LOST | HIGH for legal |
+  | Embedded Excel ranges | ✓ | image | LOST | LOST | HIGH |
+  | Section page sizes | ✓ | ✓ | N/A | N/A | LOW |
+
+STEP 5 — Visual verification on PDF outputs (legal/contract docs critical)
+  pdftoppm -r 150 -png -f 1 -l 1 {OUTPUT_DIR}/output.pdf <TMP>/p1
+  # Open <TMP>/p1-1.png — confirm signature blocks, seals, stamps render.
+  # For multi-page legal docs, also rasterize the signature page:
+  SIG_PAGE=$(pdftotext -layout {OUTPUT_DIR}/output.pdf - | grep -n "^Signature\|签字\|签章" | head -1 | cut -d: -f1)
+  # …then rasterize that page too.
+
+STEP 6 — Round-trip verification (if user wants reverse confirmation)
+  pandoc {OUTPUT_DIR}/output.md -o <TMP>/roundtrip.docx
+  python3 -c "from docx import Document; …"   # diff structures
+  # Report the delta back to user.
+
+CONSTRAINTS:
+  - Fidelity-loss inventory is a MANDATORY deliverable, not optional.
+  - For PDF outputs of legal / contract docs, NEVER trust strings/grep
+    alone — visual verification on signature pages is required.
+  - .doc → .docx must go through soffice first; pandoc on .doc is unreliable.
+  - DOCX→PDF native render/export is the default for preservation; HTML→PDF is a redesign/recomposition route, not the default conversion route.
+  - Don't 2>/dev/null pandoc / soffice — their stderr lists every dropped element.
+```
+
+---
+
+## How to use this index
+
+1. **Read the user's incoming query.** Match it against each `Match signatures` block.
+2. **One match → copy the full Canonical query.** Substitute Slots verbatim
+   from the user's actual values. Execute step-by-step. Do not skip
+   verification steps.
+3. **Multiple partial matches → fuse.** Take the strictest verification
+   from each matched canonical query; never relax a constraint.
+4. **No match → fall back** to [`../SKILL.md`](../SKILL.md) Operational rules and
+   Routes. Don't force-fit a wrong canonical query — it will encode the
+   wrong constraints.
+
+## Universal constraints (apply to every canonical query above)
+
+- **Don't `2>/dev/null`.** Redirect to `<TMP>/<step>.log`, grep on demand.
+- **JSON files via `json.dumps(payload, ensure_ascii=False, indent=2)`.**
+- **Always pass `--format` explicitly** to `make.sh render`.
+- **Always verify with `pdfinfo "Page size"` + `pdfimages -list | wc -l`.**
+- **Vision per page** for charts and complex financial tables (`--pages N`).
+- **Locate-first** for >20 page PDFs with targeted queries; index-first
+  for >200 pages; budget = 2 blind greps max.