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

package/server/assets/skills/pdf/docs/latex-academic-thesis-guide.md

@@ -0,0 +1,234 @@
+# Guide: LaTeX Academic Thesis → PDF
+
+Use this route when the user asks to generate, compile, or typeset an academic
+thesis / dissertation / 毕业论文 / 学士论文 / 硕士论文 / 博士论文 using LaTeX,
+especially with a university-provided template or Chinese national standard
+format (GB/T 7714 bibliography, GB/T 7714 title rules, etc.).
+
+This route does **not** write the thesis content for you — it provides the
+toolchain, template scaffold, compilation workflow, and verification gates so
+that a pre-authored `.tex` file (or a user's content) produces a correctly
+formatted PDF.
+
+---
+
+## Trigger signatures
+
+Match any of these; read the guide before doing anything:
+
+- "用 LaTeX 生成/排版学术论文"
+- "毕业论文 LaTeX 模板"
+- "学士论文 PDF 封面合并"
+- "LaTeX 编译 生成 PDF"
+- "参考文献 GB/T 7714 编号"
+- "页眉页脚 奇偶页 不同"
+- "目录含一二三级标题"
+- "三线表 格式"
+- "学校论文格式 A4"
+- "qpdf 合并封面 PDF"
+
+---
+
+## What this route does
+
+1. **Scaffold** a Chinese academic thesis `main.tex` covering all required
+   structural components (cover, abstract, TOC, body, bibliography, appendix).
+2. **Compile** with `tectonic` (preferred, auto-fetches packages) or `xelatex
+   + bibtex` (fallback).
+3. **Verify** page size, page numbering breaks, header/footer, undefined
+   references/citations.
+4. **Merge** a separate cover PDF with the body PDF via `qpdf` when the cover
+   is provided as an external file.
+
+---
+
+## What this route does NOT do
+
+- Do **not** write the thesis body content from scratch. Extract structure and
+  formatting rules from the user's content; do not invent or alter text.
+- Do **not** route DOCX/Word tasks here — use `docx`.
+- Do **not** use HTML→PDF for an academic thesis that requires LaTeX typesetting.
+- Do **not** ignore `undefined reference`, `undefined citation`, or `fatal`
+  warnings in `main.log` — they indicate broken cross-references or bibliography.
+- Do **not** re-number references on every re-citation — use the bibliography
+  style's built-in compression (`sort&compress` with `natbib`).
+
+---
+
+## Input collection checklist
+
+Before writing any LaTeX or running any compile, collect:
+
+| Item | How to get it | Why it matters |
+|---|---|---|
+| University / degree level | Ask user | Determines title formatting, page geometry |
+| Page geometry | A4; top/bottom/left/right mm values | Passed to `geometry` package |
+| Font requirements | e.g. "小四宋体 20pt", "Times New Roman" | Sets `\zihao{}`, `\setCJKmainfont` |
+| Heading hierarchy | e.g. 一级小三加粗, 二级四号, 三级小四 | Sets `\ctexset{section/...}` |
+| Bibliography style | GB/T 7714-2015 numeric; author-date | Sets `\bibliographystyle{gbt7714-numerical}` |
+| Page numbering breaks | Roman (摘要/目录) → Arabic (正文) | Sets `\pagenumbering{roman/arabic}` |
+| Figure/table caption style | e.g. 五号宋体, labelsep=space | Sets `\captionsetup` |
+| Cover page | External PDF or LaTeX built-in? | Determines qpdf merge step |
+| Whether `thebibliography` or BibTeX | Ask user or check source | Changes compile chain |
+| External figure/table dirs | `graphicspath{{../charts/}{../photos/}}` | Resolves `\includegraphics` |
+| Clickable TOC/index | All major sections, appendix, references | `hyperref` + `\tableofcontents` and live destinations |
+
+---
+
+## Implementation flow
+
+### Step 1 — Write the compact template
+
+Use the scaffold in `templates/latex-academic-thesis/source.tex` as the starting
+point. Fill in the structural placeholders (title, author, supervisor, date,
+school name). Keep all formatting commands — only replace content.
+
+Key formatting blocks in the scaffold:
+
+```latex
+% Page geometry (南理工学士论文 spec)
+\usepackage[a4paper, top=30mm, bottom=24mm, left=25mm, right=25mm,
+  headheight=15pt, headsep=10mm, footskip=20mm]{geometry}
+
+% Chinese font: Songti SC + Times New Roman
+\usepackage{fontspec}
+\setmainfont{Times New Roman}
+\setCJKmainfont[AutoFakeBold=2.5]{Songti SC}
+
+% Title formatting (南理工 spec)
+\ctexset{
+  section = { format = \raggedright\songti\bfseries\zihao{-3},
+               beforeskip = 18pt, afterskip = 18pt, break = \clearpage },
+  subsection = { format = \raggedright\songti\bfseries\zihao{4},
+                 beforeskip = 12pt, afterskip = 12pt },
+  subsubsection = { format = \raggedright\songti\bfseries\zihao{-4},
+                    beforeskip = 6pt, afterskip = 6pt },
+}
+
+% Fancy header/footer (different odd/even pages)
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[CO]{...}\fancyhead[CE]{...}
+\fancyfoot[LE,RO]{\thepage}
+```
+
+Clickable navigation is mandatory: keep `hyperref` enabled, keep
+`\tableofcontents`, and use `\phantomsection` before every manual
+`\addcontentsline` entry such as abstract, appendix, or references. Do not
+replace the generated TOC with plain text page numbers.
+
+### Step 2 — Compile
+
+**Preferred — tectonic (no manual package install):**
+```bash
+cd /path/to/thesis-dir
+tectonic main.tex --outdir . 2>&1
+```
+
+**Fallback — xelatex + bibtex:**
+```bash
+cd /path/to/thesis-dir
+xelatex main.tex && bibtex main && xelatex main.tex && xelatex main.tex
+```
+
+> Always run xelatex **twice after bibtex** to resolve cross-references and
+> thebibliography page numbers. Three total runs is the safe minimum.
+
+### Step 3 — Verify
+
+```bash
+# 1. Page size must be A4
+pdfinfo main.pdf | grep "Page size"
+# Expected: A4 = 595 x 842 pts (or 210 x 297 mm)
+
+# 2. For xelatex: check log for fatal / undefined errors
+grep -i "fatal\|undefined" main.log
+# Must be empty (warnings are OK; tectonic does not emit main.log)
+
+# 3. For xelatex: check for undefined references
+grep "undefined reference" main.log
+# Must be empty
+
+# 4. For xelatex: check for undefined citations
+grep "undefined" main.log | grep citation
+# Must be empty
+
+# 5. Page count spot-check
+pdfinfo main.pdf | grep Pages
+# Confirm reasonable page count
+
+# 6. Text extraction spot-check
+pdftotext main.pdf - | head -50
+# Verify Chinese characters render (not CID-glyphs)
+
+# 7. Navigation spot-check
+# Open main.pdf and click several TOC entries; they must jump to the intended
+# section pages. If the PDF was merged with an external cover, repeat this check
+# on the final merged PDF because page offsets may change.
+```
+
+### Step 4 — Merge cover PDF (if external)
+
+```bash
+# 封面 PDF（1页）在前，正文 PDF（1-z）在后
+# 正确顺序：封面 → 正文
+qpdf --empty --pages cover.pdf 1-z body.pdf 1-z -- final.pdf
+
+# 验证合并结果
+pdfinfo final.pdf | grep Pages
+pdftotext final.pdf - | head -20
+# Also open final.pdf and spot-click TOC entries; ensure cover merge did not
+# break internal TOC destinations or page offsets.
+```
+
+---
+
+## Recommended toolchain
+
+| Tool | Purpose | Install |
+|---|---|---|
+| `tectonic` | LaTeX compiler, auto-fetches packages | `brew install tectonic` |
+| `xelatex` + `bibtex` | Fallback compile chain | `brew install basictex` |
+| `qpdf` | PDF merge / split | `brew install qpdf` |
+| `pdfinfo` | Verify page size and page count | `brew install poppler` |
+| `pdftotext` | Extract text to verify rendering | `brew install poppler` |
+| `grep` | Check `main.log` for undefined/fatal | system |
+
+---
+
+## Common pitfalls
+
+1. **Missing `\clearpage` before `\section`** — without `break = \clearpage`,
+   long sections can cause page geometry violations.
+2. **Roman → Arabic page numbering gap** — `\newpage\clearpage\pagestyle{plain}`
+   before `\pagenumbering{arabic}` prevents orphaned headers.
+3. **Caption font size ignored** — `\captionsetup{font=...}` must come **after**
+   `\usepackage{fontspec}` to avoid interference.
+4. **`AutoFakeBold` too heavy or too light** — values between 1.5–3.0 are
+   typical; 2.5 is a good default for "bold" Songti that matches Word output.
+5. **`sort&compress` not working** — must use `natbib` with `numbers` option,
+   not the default `authoryear`.
+6. **qpdf merge creates blank pages** — ensure cover PDF page count is
+   accounted for; use `qpdf --empty --pages` syntax precisely.
+7. **Latin Modern / CM fonts for CJK** — always set `\setCJKmainfont`; never
+   rely on the LaTeX default font for Chinese characters.
+8. **Multiple `hyperref` warnings** — load `hyperref` last (or nearly last) to
+    avoid option conflicts with `caption`, `subcaption`, `booktabs`.
+9. **Overfull `\hbox`** — add `\emergencystretch=0.5em` in the preamble.
+10. **`\ref` vs `\pageref`** — use `\ref` for section/figure numbers; do not
+     mix them in a single document without checking context.
+11. **Plain-text TOC** — never hand-type a static table of contents; use
+    `\tableofcontents` with `hyperref` so entries remain clickable. For manual
+    front-matter entries, add `\phantomsection` immediately before
+    `\addcontentsline` or links jump to the previous page.
+
+---
+
+## Reference
+
+| File | Purpose |
+|---|---|
+| [`templates/latex-academic-thesis/source.tex`](templates/latex-academic-thesis/source.tex) | Compact scaffold — all structural components, minimal content |
+| [`templates/latex-academic-thesis/README.md`](templates/latex-academic-thesis/README.md) | Template usage — fill-in-the-blanks recipe |
+| [`docs/annual-report-financial-digest-latex-case.md`](docs/annual-report-financial-digest-latex-case.md) | Case: long annual-report PDF → compact LaTeX digest (LaTeX compile, tectonic, chart generation) |

package/server/assets/skills/pdf/docs/latex-technical-book-guide.md

@@ -0,0 +1,112 @@
+# Guide: LaTeX Technical Book → PDF
+
+Use this route for polished Chinese technical books, engineering monographs, source-code reading
+books, algorithm books, systems design books, or long-form book-like content that should be typeset
+with LaTeX rather than HTML.
+
+This is distinct from the academic-thesis route. Do not apply university thesis formatting rules
+here unless the user explicitly asks for an academic thesis.
+
+---
+
+## Trigger signatures
+
+- “中文技术书 LaTeX 模板”
+- “把这些 HTML 页面整理成一本书”
+- “源码解析书 / 工程实践书 / 多 Agent 平台书稿”
+- “B5 / 16 开技术出版读物”
+- “O'Reilly 风格封面 / 动物封面 / 技术书封面”
+- “代码块、目录、页眉页脚、引文框、结构图都要像书”
+
+---
+
+## Starting point
+
+Start from:
+
+```text
+templates/latex-technical-book/source.tex
+```
+
+The template uses a TikZ animal-style placeholder by default, so no binary cover illustration is
+required. If the user provides a real cover image, copy it into `figures/` and replace the
+placeholder block in `source.tex` with an `\includegraphics` call. If the source HTML references an
+image that is absent, tell the user instead of pretending the image exists.
+
+---
+
+## Required workflow
+
+1. **Inspect source structure first**
+   - Read cover, TOC, a normal prose page, a code-heavy page, a table-heavy page, and a
+     diagram-heavy page.
+   - Identify semantic classes: `dropcap`, `pullquote`, `timeline`, `arch-diagram`, `dep-flow`,
+     `flow-diagram`, `code`, `table`, etc.
+
+2. **Generate semantic LaTeX, not literal CSS**
+   - Preserve headings/sections through `\chapter`, `\section`, `\subsection`.
+   - Preserve diagrams by rebuilding them with TikZ or `diagramBox`; do not drop structural
+     diagrams.
+   - Preserve callouts as `pullquotebox`/`insightbox`/`warningbox`.
+   - Preserve inline code as breakable `\path|...|` when ASCII-heavy.
+
+3. **Keep navigation clickable**
+   - `hyperref` is mandatory.
+   - Keep `\tableofcontents`.
+   - Use `\phantomsection` before manual TOC entries.
+
+4. **Compile with XeLaTeX**
+   - Use `latexmk -xelatex -interaction=nonstopmode main.tex`.
+   - Run enough passes to resolve TOC and links.
+
+5. **Verify before delivery**
+   - No fatal LaTeX errors / undefined control sequences.
+   - Page size and page count are reasonable.
+   - Open and visually inspect cover, TOC, one prose page, one code page, one table/diagram page.
+
+---
+
+## Mapping rules for HTML sources
+
+Use semantic mappings rather than literal CSS copying:
+
+- `p.dropcap`, `span.dropcap` → `\fancydropcap{首}{剩余文字}` for Chinese prose only; skip
+  ASCII/digit starts.
+- `div.pullquote`, `.pull-quote`, `blockquote` → `pullquotebox`.
+- `ul.timeline` with `.year` → `diagramBox` plus `description`.
+- `.arch-diagram`, `.dep-flow` → TikZ diagram inside `diagramBox`.
+- `.flow-diagram`, `.flow-chain`, `.path-diagram`, `.flow-row` → TikZ or structured `diagramBox`;
+  preserve all nodes/arrows.
+- Inline `<code>` → `\path+...+` (or another delimiter) when ASCII/path/API-like; escaped normal
+  text when CJK-heavy.
+- `<pre><code>` → `lstlisting` with low-saturation highlighting.
+- `<table>` → `tabularx` with ragged `Y` columns; reduce `\tabcolsep`; use `\scriptsize` for many
+  columns.
+- `<ul>` / `<ol>` → `enumitem` lists with restrained red marker/number accents.
+
+---
+
+## Design contract
+
+- Cover can use the O'Reilly-like framed style from `source.tex`.
+- If using an animal cover, align paper/background tone with the image's edge color to avoid visible
+  mismatched rectangles.
+- Avoid overusing accent color. In the template, red is used for rules, TOC numbers, quote bars, and
+  small markers — not for body prose.
+- Keep code highlighting muted, not neon.
+- Page header should be short: current section title + page number, not chapter title and section
+  title concatenated.
+
+---
+
+## Common pitfalls
+
+1. **Forgetting special HTML blocks** — plain text conversion loses the book feel. Always scan
+   classes and map key style semantics.
+2. **Missing cover assets** — if HTML references a cover image but the file is not present, ask for
+   it or use the TikZ placeholder explicitly.
+3. **Drop caps everywhere** — use on opening prose paragraphs; skip ASCII/digit starts and remove
+   when `lettrine` warns near page boundaries.
+4. **Long code paths overflow** — prefer `\path`, `xurl`, `tabularx`, and manual line breaks for
+   extreme cells.
+5. **Static TOC** — never hand-type TOC. Use LaTeX-generated clickable TOC.

package/server/assets/skills/pdf/docs/markdown-static-academic-data-viz-case.md

@@ -0,0 +1,280 @@
+# Case: Markdown tables → print-academic PDF with static charts
+
+## When this case applies
+
+Use this case when a user gives a Markdown report that is mostly Chinese prose + tables and asks for a more visual PDF, especially when the acceptance criteria require:
+
+- preserve the original Markdown section order and heading hierarchy;
+- render all Markdown as rich text, with no Markdown source markers left in the PDF;
+- keep original tables intact while adding charts derived from specific tables;
+- generate charts as static images, not runtime Chart.js/ECharts/D3/Plotly canvases;
+- deliver A4, print-academic styling rather than a magazine/dashboard redesign.
+
+This is a stricter sibling of `templates/data-viz-report/`: the normal `data-viz-report` skeleton is chart-rich and may use Chart.js; this case is for evaluation-style requirements where static chart artifacts and source-structure fidelity matter more than interactive-looking design.
+
+## Original user intent and acceptance criteria
+
+Source: `Apple_M系列芯片AI部署全面分析报告.md`.
+
+Initial ask:
+
+> 这个md以文本和表格为主，我需要你生成一份数据可视化表现更好的图文详情的pdf报告给我，更方便我查看
+
+Strict acceptance criteria added after first attempt:
+
+1. Follow the original Markdown hierarchy; render Markdown as rich text; no raw Markdown syntax remnants.
+2. Include at least two data charts corresponding to original table 1.1 and table 1.2; do not alter source data.
+3. Preserve core content and key conclusions; do not omit important chapters.
+4. Keep source document structure order and hierarchy.
+5. Chinese query → Chinese output.
+6. No overflow, mojibake, text/image overlap.
+7. Use HTML → PDF, not screenshot stitching.
+8. Charts must be embedded as static images; do not use runtime ECharts/Chart.js/D3/Plotly.
+9. Use A4 page size and print-academic visual style.
+10. Chart numbers/titles must be explicit HTML labels, not CSS counters.
+
+## What went wrong in the first attempt
+
+Do **not** repeat the first-attempt pattern when the strict criteria above are present:
+
+- The report was rewritten into a visual executive brief, so it lost strict source order and some section detail.
+- Chart.js was used in the HTML. Although Chromium embedded the final canvases as PDF images, the generation path still violated “no runtime chart library”.
+- The style was a tech visual report rather than print-academic.
+
+Recovery was to rebuild from the original Markdown as the canonical structure, then insert static charts after the relevant source tables.
+
+## End-to-end workflow
+
+### 1. Preflight
+
+```bash
+bash <SKILL>/scripts/make.sh check
+python3 - <<'PY'
+import importlib.util
+for m in ['matplotlib', 'markdown_it', 'bs4']:
+    print(m, bool(importlib.util.find_spec(m)))
+PY
+```
+
+Expected evidence:
+
+- `make.sh check` reports OK for Python, Node, Playwright, pdfinfo.
+- `matplotlib`, `markdown_it`, and `bs4` are available.
+
+If `matplotlib` is missing, install it in the active Python environment or use SVG generated by deterministic Python code. Do not fall back to Chart.js when the acceptance criteria bans runtime chart libraries.
+
+### 2. Inspect source and locate chartable tables
+
+Read the Markdown source and identify:
+
+- title and top-level structure;
+- all `##` / `###` headings;
+- table captions and table bodies;
+- placeholder chart locations in the source;
+- exact user-specified tables that must become charts.
+
+For this case:
+
+- `表1.1：Apple M系列芯片关键硬件规格对比` → static chart `图1.1`.
+- `表1.2：Apple M系列芯片GeekBench 6性能得分` → static chart `图1.2`.
+- Original placeholder `图1.1：Apple M-Max系列芯片性能代际对比` → optional static chart `图1.3` using original table 1.2 values indexed to M1 Max = 100.
+
+Do not infer or “clean up” data silently. Keep values such as `未披露` and `300/400 GB/s` visibly faithful to the source. If a value cannot be plotted, annotate it rather than inventing a number.
+
+### 3. Parsing and transformation strategy
+
+Use Markdown rendering for prose/table fidelity, then manipulate the HTML fragment:
+
+```python
+from markdown_it import MarkdownIt
+from bs4 import BeautifulSoup, NavigableString
+
+md = MarkdownIt('commonmark', {'html': False, 'breaks': False}) \
+    .enable('table') \
+    .enable('strikethrough')
+body_html = md.render(md_text)
+soup = BeautifulSoup(body_html, 'html.parser')
+```
+
+Rules:
+
+- `html=False` unless the source HTML is trusted and required.
+- Keep the original source order. Insert figures after the corresponding rendered tables; do not rebuild the whole document as a new outline.
+- Add CSS classes to headings and tables, but do not renumber headings by script unless the user asked.
+- Remove leftover Markdown emphasis markers caused by malformed source, e.g. orphan `**` around quoted phrases:
+
+```python
+for node in soup.find_all(string=True):
+    if isinstance(node, NavigableString) and '**' in node:
+        node.replace_with(node.replace('**', ''))
+```
+
+### 4. Terminology and language rules
+
+No translation was needed in this run. For Chinese technical Markdown, preserve source terminology unless the user asks for localization changes.
+
+Keep these terms stable:
+
+| Source term | Output rule |
+|---|---|
+| Apple M系列 | keep as `Apple M系列` |
+| Qwen 32B / Qwen3-32B | keep model name unchanged |
+| INT4 / INT8 / BF16 / Q8_0 / Q4_K_M | keep exact technical tokens |
+| 统一内存架构（UMA） | keep Chinese + acronym |
+| 神经网络引擎（NE） / ANE | do not merge unless source does |
+| RTX 5090 / TensorRT-LLM / CUDA | keep exact names |
+| tokens/s / Time To First Token (TTFT) | keep source bilingual form when present |
+
+If a later task involves translation, add a short glossary before rendering and validate that model names, chip names, units, and benchmark labels are untouched.
+
+### 5. Static chart generation
+
+Use Matplotlib or deterministic SVG/PNG generation. Store only editable source HTML and code/pseudocode in the case; do not store generated PDFs.
+
+#### Chart for table 1.1
+
+Recommended chart shape:
+
+- three stacked subplots using original table 1.1:
+  - GPU cores (max);
+  - unified memory bandwidth;
+  - unified memory capacity.
+- For `未披露`, show an annotation instead of a fake zero.
+- For `300/400 GB/s`, draw a range marker or label as `300/400`.
+
+#### Chart for table 1.2
+
+Recommended chart shape:
+
+- two stacked subplots using original table 1.2:
+  - grouped bars for single-core and multi-core scores;
+  - bar chart for GPU Metal scores.
+- Use thousands separators; rotate long chip labels.
+
+#### Optional placeholder chart
+
+For the original placeholder “M-Max系列芯片性能代际对比”, generate a static line chart from table 1.2 values:
+
+- filter `M1 Max`, `M2 Max`, `M3 Max`, `M4 Max`;
+- compute index = value / M1 Max value * 100;
+- title it as an indexed view so the derived transformation is explicit.
+
+### 6. Layout and asset strategy
+
+Use a restrained print-academic shell around the rendered Markdown:
+
+- A4 portrait, normal academic margins (`16mm 14mm 17mm 14mm` worked here).
+- White background, dark text, one restrained accent color.
+- Full original tables remain as HTML tables, not screenshots.
+- Static chart PNGs are embedded with relative paths under `assets/`.
+- Figure captions are literal HTML `<figcaption>` text, e.g. `图1.1：...`, not CSS counters.
+- Avoid decorative prefaces that explain the generation method unless the user asks; those were later removed.
+
+Minimal CSS pattern:
+
+```css
+@page { size: A4 portrait; margin: 16mm 14mm 17mm 14mm; }
+* { box-sizing: border-box; -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+html, body {
+  margin: 0; padding: 0; background: #fff; color: #172033;
+  font-family: "PingFang SC", "Songti SC", "Noto Sans CJK SC", "Microsoft YaHei", Arial, sans-serif;
+  font-size: 10.2pt; line-height: 1.62;
+}
+h1 { font-size: 24pt; text-align: center; margin: 16mm 0 9mm; }
+h2 { font-size: 16pt; margin: 11mm 0 4mm; border-bottom: 1.4pt solid #2f8f83; }
+h3 { font-size: 12.4pt; margin: 7mm 0 3mm; }
+.data-table { width: 100%; border-collapse: collapse; font-size: 7.45pt; table-layout: fixed; }
+.data-table th { background: #eef6f5; border: .55pt solid #b7c9c7; }
+.data-table td { border: .45pt solid #d6dee8; word-break: break-word; }
+.figure-block { margin: 5mm 0 7mm; page-break-inside: avoid; text-align: center; }
+.figure-block img { max-width: 100%; max-height: 205mm; border: .5pt solid #d8e0ea; }
+.figure-block figcaption { margin-top: 2mm; font-size: 8.6pt; color: #526173; }
+```
+
+### 7. Rendering
+
+```bash
+bash <SKILL>/scripts/make.sh render \
+  --in <TMP>/source.html \
+  --out <OUTPUT_PATH> \
+  --format A4 \
+  --wait 15000
+```
+
+Even though static images do not need Chart.js settle time, keep `--wait 15000` when local fonts or large images are involved; it is cheap and avoids racey print snapshots.
+
+### 8. Verification commands and expected evidence
+
+Run all of these; do not suppress stderr.
+
+```bash
+pdfinfo <OUTPUT_PATH>
+pdfimages -list <OUTPUT_PATH>
+pdftotext -layout <OUTPUT_PATH> -
+```
+
+Expected evidence from the successful run:
+
+- `pdfinfo`:
+  - `Pages: 11`
+  - `Page size: 595.92 x 842.88 pts (A4)`
+  - `JavaScript: no`
+- `pdfimages -list`:
+  - at least 2 images for the mandatory static charts;
+  - successful run had 3 image entries for figures 1.1, 1.2, 1.3.
+- `pdftotext -layout`:
+  - starts directly with the report title if no generation note is wanted;
+  - contains `表1.1`, `图1.1`, `表1.2`, `图1.2`;
+  - contains original major sections: `引言`, `第一部分`, `第二部分`, `第三部分`, `结论与最终建议`, `附录：参考资料`;
+  - no raw `**` emphasis markers.
+
+For quick checks:
+
+```bash
+pdftotext -layout <OUTPUT_PATH> - | grep -E '表1\.1|图1\.1|表1\.2|图1\.2|结论与最终建议|附录'
+pdftotext -layout <OUTPUT_PATH> - | grep '\*\*' && echo 'FAIL: raw markdown markers remain'
+```
+
+### 9. Common pitfalls and recovery
+
+| Pitfall | Symptom | Recovery |
+|---|---|---|
+| Rewriting into an executive brief | Structure/order no longer matches source | Render the Markdown first, then insert figures; do not re-outline. |
+| Runtime chart library used despite static requirement | HTML contains Chart.js/ECharts/D3/Plotly script | Regenerate charts with Matplotlib/SVG and embed PNG/SVG files. |
+| Raw Markdown markers remain | `pdftotext` shows `**` or code fences | Use markdown-it; remove orphan markers only after render; inspect text output. |
+| Table too wide | columns wrap awkwardly or overflow | Use `table-layout: fixed`, small table font, `word-break: break-word`; keep A4 portrait unless user accepts landscape. |
+| Chart data “normalized” without disclosure | acceptance says data was changed | Keep source tables intact; if deriving an index chart, label it explicitly as derived. |
+| `未披露` plotted as 0 | chart implies a false value | Annotate as `未披露`; do not include it in numeric axis calculations. |
+| Decorative generation note unwanted | first page begins with process metadata | Remove `.report-meta` / `.toc-note` before final render. |
+| Verification only uses `pdftotext` | chart-less PDF passes text check | Always run `pdfimages -list`; images are the evidence for static chart embedding. |
+
+## Final reusable workflow
+
+1. Load `pdf`; match P3, but if criteria mention static charts / no runtime chart libs / preserve Markdown hierarchy, use this case instead of the default Chart.js data-viz skeleton.
+2. Run dependency preflight.
+3. Read the Markdown and list all headings/tables; identify the exact tables that must be visualized.
+4. Convert Markdown to HTML with `markdown-it-py`; keep original order.
+5. Generate static chart PNG/SVG files from the exact source table values.
+6. Insert `<figure>` blocks immediately after the corresponding source tables.
+7. Wrap the result in print-academic A4 CSS; keep tables as HTML; embed images relatively.
+8. Render with `make.sh render --format A4 --wait 15000`.
+9. Verify A4/page count, static images, extracted text, required section/table/figure labels, and absence of Markdown markers.
+10. If the user asks for cosmetic cleanup, edit the source HTML and rerender the same output PDF; do not patch the PDF binary.
+
+## Reproducible source artifact
+
+Editable source HTML from the successful run is stored at:
+
+- `templates/data-viz-report/cases/apple-m-ai-static-academic/source.html`
+
+It intentionally does **not** include the generated PDF. Recreate the PDF with:
+
+```bash
+bash <SKILL>/scripts/make.sh render \
+  --in <SKILL>/templates/data-viz-report/cases/apple-m-ai-static-academic/source.html \
+  --out /tmp/apple-m-ai-static-academic.pdf \
+  --format A4 \
+  --wait 15000
+```
+
+Note: the source HTML references `assets/fig_*.png` relative to its case directory. If those assets are not present, regenerate them from the source table data using the Matplotlib strategy above, or replace with fresh static figures before rendering.