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

package/server/assets/skills/pdf/docs/create-guide.md

@@ -0,0 +1,438 @@
+# CREATE — Generate a New PDF
+
+> **Prerequisites.** Read [`html-pdf-spec.md`](html-pdf-spec.md) for the
+> mechanical contract (page geometry, page-break rules, Chart.js settle, CJK
+> cascade). Read [`design-guide.md`](design-guide.md) for the aesthetic
+> contract (palette mood, typography, anti-patterns). This file is the
+> end-to-end recipe that ties them together.
+
+The CREATE pipeline has one shape:
+
+```
+HTML file (templates/<slug>/skeleton.html or hand-written)
+  └─► render_html.cjs (Playwright Chromium)
+       └─► report.pdf
+```
+
+There is no token system, no ReportLab, no LaTeX. If a primitive cannot be
+expressed in HTML+CSS+JS, it does not belong in CREATE.
+
+---
+
+## 1. The 4 steps
+
+```bash
+# Step 1 — verify deps once per machine
+bash scripts/make.sh check
+
+# Step 2 — pick a starting point (DO NOT skip this scan)
+cat templates/INDEX.md
+cat templates/<chosen-slug>/README.md      # 7-section recipe
+
+# Step 3 — copy the skeleton, fill the placeholders, re-skin to your topic
+cp templates/<chosen-slug>/skeleton.html /tmp/work/page.html
+$EDITOR /tmp/work/page.html
+
+# Step 4 — render & verify
+bash scripts/make.sh render --in /tmp/work/page.html --out /tmp/work/out.pdf --wait 15000
+pdfinfo /tmp/work/out.pdf | grep Pages
+pdftotext -layout /tmp/work/out.pdf - | head -40
+open /tmp/work/out.pdf       # eyeball it
+```
+
+The `--wait 15000` flag is critical when the page contains Chart.js or any
+late-loading JS. Static prose can use the default `--wait 800`. See
+[html-pdf-spec.md §6](html-pdf-spec.md#6-charts-chartjs).
+
+---
+
+## 2. Picking a template
+
+[`templates/INDEX.md`](../templates/INDEX.md) lists every skeleton with intent
+keywords. Match by user intent first, then by document shape:
+
+| Intent | Template |
+|---|---|
+| Restaurant menu, bilingual omakase | `bilingual-menu-premium` |
+| Brand guide / style guide / 2-page identity | `brand-guide-2page` |
+| Data report / benchmark / 数据可视化 / 评测 | `data-viz-report` |
+| Article digest / blog anthology / newsletter | `multi-article-aggregator` |
+| Multi-country research / regulatory survey | `multilang-research-report` (for AI voice cloning / legal-regulatory surveys, read `docs/ai-voice-cloning-regulatory-report-case.md`) |
+| Plain markdown report (REFORMAT path) | `reformat-default` |
+
+If nothing fits, **adapt the closest** rather than starting from scratch — the
+skeletons encode page-break math and CJK cascades that take real time to get
+right.
+
+If the user's content is genuinely unique (not just "reskin needed"),
+hand-author the HTML following [`html-pdf-spec.md`](html-pdf-spec.md) and
+copy individual primitives (KPI cards, chart cards, pill table) from
+`templates/data-viz-report/skeleton.html`.
+
+---
+
+## 2. JSON-driven CREATE workflow (data reports)
+
+Use this when the PDF is a data/report deliverable and the content should be
+separated from layout. The contract is still **HTML → Playwright → PDF**;
+JSON is only an intermediate content manifest consumed by your build script.
+
+### 2.1 Minimal `content.json` shape
+
+Always write JSON with `json.dumps(..., ensure_ascii=False, indent=2)` — never
+hand-concatenate strings.
+
+```json
+{
+  "meta": {
+    "title": "2024 Annual Report Digest",
+    "subtitle": "Financial highlights and segment revenue",
+    "author": "Mavis",
+    "date": "2026-04-26",
+    "locale": "zh-CN",
+    "page_format": "A4",
+    "style": "print-academic"
+  },
+  "theme": {
+    "accent": "#8A1E1E",
+    "ink": "#1F2A25",
+    "muted": "#66706A",
+    "paper": "#FBFAF7"
+  },
+  "kpis": [
+    {"label": "营业收入", "value": "2.94万亿", "delta": "同比 -2.5%", "tone": "neutral"},
+    {"label": "归母净利润", "value": "1,646.84亿", "delta": "同比 +2.0%", "tone": "good"}
+  ],
+  "sections": [
+    {
+      "id": "financials",
+      "title": "主要财务指标",
+      "lead": "单位除特别注明外为人民币百万元。",
+      "tables": [
+        {
+          "caption": "近五年主要财务指标",
+          "columns": ["项目", "2024", "2023", "2022"],
+          "rows": [
+            ["营业收入", "2,937,981", "3,012,812", "3,240,951"],
+            ["净利润", "183,755", "180,563", "163,493"]
+          ],
+          "source": "年报第5页"
+        }
+      ],
+      "charts": [
+        {"id": "trend", "title": "财务趋势", "image": "trend.png", "alt": "五年收入与利润趋势"}
+      ],
+      "takeaways": ["收入同比回落，但利润端保持韧性。"]
+    }
+  ],
+  "footnotes": [
+    "本摘要不替代经审计年度报告全文。"
+  ]
+}
+```
+
+Recommended fields:
+
+| Field | Required | Meaning |
+|---|---:|---|
+| `meta.title` | yes | Cover/title-bar title; must match user language. |
+| `meta.page_format` | yes | Usually `A4`; renderer must also pass `--format A4`. |
+| `theme.*` | no | Palette tokens copied into CSS variables. |
+| `kpis[]` | no | Small KPI cards; values are strings so units are explicit. |
+| `sections[].tables[]` | no | Dense source tables; keep `source` for auditability. |
+| `sections[].charts[]` | no | Static image paths or data-URI strings; runtime chart libraries are optional but static PNGs are preferred for strict deliverables. |
+| `sections[].takeaways[]` | no | Short bullets; do not let prose crowd out tables. |
+| `footnotes[]` | no | Method, caveats, and source notes. |
+
+### 2.2 Build script skeleton
+
+This script turns `content.json` into `page.html`. Keep HTML escaping explicit;
+never paste JSON directly into JavaScript unless you serialized it yourself.
+
+```python
+import html, json
+from pathlib import Path
+
+work = Path("/tmp/pdf-create")
+payload = json.loads((work / "content.json").read_text(encoding="utf-8"))
+
+def esc(x):
+    return html.escape(str(x), quote=True)
+
+def render_table(table):
+    head = "".join(f"<th>{esc(c)}</th>" for c in table["columns"])
+    rows = []
+    for row in table["rows"]:
+        rows.append("<tr>" + "".join(f"<td>{esc(c)}</td>" for c in row) + "</tr>")
+    source = f"<div class='source'>{esc(table.get('source',''))}</div>" if table.get("source") else ""
+    return f"<figure class='table-card'><figcaption>{esc(table['caption'])}</figcaption><table><thead><tr>{head}</tr></thead><tbody>{''.join(rows)}</tbody></table>{source}</figure>"
+
+sections = []
+for sec in payload["sections"]:
+    body = [f"<section class='page' id='{esc(sec['id'])}'>", f"<h2>{esc(sec['title'])}</h2>"]
+    if sec.get("lead"):
+        body.append(f"<p class='lead'>{esc(sec['lead'])}</p>")
+    for table in sec.get("tables", []):
+        body.append(render_table(table))
+    for chart in sec.get("charts", []):
+        body.append(f"<figure class='chart'><img src='{esc(chart['image'])}' alt='{esc(chart.get('alt',''))}'><figcaption>{esc(chart['title'])}</figcaption></figure>")
+    for item in sec.get("takeaways", []):
+        body.append(f"<p class='takeaway'>{esc(item)}</p>")
+    body.append("</section>")
+    sections.append("\n".join(body))
+
+html_doc = f"""<!doctype html>
+<meta charset="utf-8">
+<title>{esc(payload['meta']['title'])}</title>
+<style>
+@page {{ size: A4 portrait; margin: 14mm 12mm; }}
+* {{ box-sizing: border-box; -webkit-print-color-adjust: exact; print-color-adjust: exact; }}
+body {{ font-family: -apple-system, 'PingFang SC', sans-serif; color: {payload.get('theme',{}).get('ink','#1F2A25')}; }}
+.page {{ page-break-after: always; }}
+.page:last-child {{ page-break-after: auto; }}
+table {{ width: 100%; border-collapse: collapse; font-size: 8.8pt; }}
+th, td {{ border: .5pt solid #d8d0c4; padding: 5px 7px; }}
+th {{ background: #efe7da; }}
+.chart img {{ max-width: 100%; height: auto; }}
+</style>
+<body>
+{''.join(sections)}
+</body>"""
+(work / "page.html").write_text(html_doc, encoding="utf-8")
+```
+
+### 2.3 End-to-end commands
+
+```bash
+SKILL=/path/to/pdf
+WORK=/tmp/pdf-create
+mkdir -p "$WORK"
+
+bash "$SKILL/scripts/make.sh" check
+python3 "$WORK/build_content.py"              # writes content.json and any chart PNGs
+python3 "$WORK/build_html.py"                 # content.json -> page.html
+bash "$SKILL/scripts/make.sh" render \
+  --in "$WORK/page.html" \
+  --out "$WORK/report.pdf" \
+  --format A4 \
+  --wait 15000
+
+pdfinfo "$WORK/report.pdf" | grep -E "Pages|Page size"
+pdfimages -list "$WORK/report.pdf" | tail -n +3 | wc -l
+pdftotext -layout "$WORK/report.pdf" - | head -40
+```
+
+Expected evidence:
+
+- `Page size` is A4.
+- `Pages` matches the requested cap.
+- image count is at least the number of embedded chart PNGs/logos.
+- `pdftotext` shows readable body text and key figures.
+- Source HTML and `content.json` have no placeholder tokens.
+
+---
+
+## 3. The component primitive cookbook
+
+Every primitive below ships in `templates/data-viz-report/skeleton.html`
+(self-contained). Copy the markup + CSS for the ones you need.
+
+### Cover (full-bleed gradient)
+
+```html
+<section class="cover">
+  <span class="cover-tag">DEEP RESEARCH · 2026</span>
+  <h1>Report title</h1>
+  <p class="subtitle">One-sentence positioning, ≤ 3 lines.</p>
+
+  <div class="cover-meta">
+    <div class="meta-stats">
+      <div class="meta-stat"><div class="num">14</div><div class="lbl">CHIPS</div></div>
+      ...
+    </div>
+    <div class="cover-info">RESEARCH REPORT<br/>v1.0 · 2026/04</div>
+  </div>
+</section>
+```
+
+### Section header (eyebrow + H2 + accent rule)
+
+```html
+<span class="section-num">PART 01 · 硬件分析</span>
+<h2 class="section">Apple M-series Hardware Analysis</h2>
+<div class="section-line"></div>
+```
+
+### KPI 4-grid (4 color variants)
+
+```html
+<div class="kpis">
+  <div class="kpi blue"><div class="label">Q3</div><div class="value">$4.2M</div><div class="desc">vs $3.1M Q2</div></div>
+  <div class="kpi green">…</div>
+  <div class="kpi orange">…</div>
+  <div class="kpi purple">…</div>
+</div>
+```
+
+### Chart card (always wrap with `.avoid-break`)
+
+```html
+<div class="chart-card avoid-break">
+  <div class="chart-title">Figure 1.1 · Memory bandwidth & TOPS evolution</div>
+  <div class="chart-sub">Max series M1 → M4 representative comparison</div>
+  <div class="chart-wrap"><canvas id="evolution"></canvas></div>
+</div>
+```
+
+### Reference table with status pills
+
+```html
+<table class="data">
+  <thead><tr><th>Chip</th><th>Memory</th><th>Verdict</th></tr></thead>
+  <tbody>
+    <tr><td class="bold">M3 Pro</td><td>36 GB</td><td><span class="pill pill-ok">✓ Feasible</span></td></tr>
+    <tr><td class="bold">M4 Max</td><td>128 GB</td><td><span class="pill pill-best">★★ Excellent</span></td></tr>
+  </tbody>
+</table>
+```
+
+5 pill semantics are fixed: `bad / warn / ok / good / best`. Do not invent
+new colors.
+
+### Versus comparison
+
+```html
+<div class="versus">
+  <div class="vs-card apple">
+    <span class="tag">APPLE M4 MAX</span>
+    <h4>Unified memory · End-of-line</h4>
+    <ul><li>...</li></ul>
+  </div>
+  <div class="vs-divider">VS</div>
+  <div class="vs-card nvidia">
+    <span class="tag">NVIDIA RTX 5090</span>
+    <h4>CUDA empire · Compute beast</h4>
+    <ul><li>...</li></ul>
+  </div>
+</div>
+```
+
+### Recommend triple (entry / recommended / premium)
+
+```html
+<div class="recommend-grid">
+  <div class="rec-card entry"><span class="level">Entry</span>...</div>
+  <div class="rec-card recommend"><span class="level">★ Recommended</span>...</div>
+  <div class="rec-card premium"><span class="level">Premium</span>...</div>
+</div>
+```
+
+### Insight callout (yellow, one paragraph)
+
+```html
+<div class="insight">
+  <span class="label">⚡ Key insight</span>
+  Body text — one paragraph, ideally a single takeaway. Don't stack 3 of these on a page.
+</div>
+```
+
+### Dark conclusion block
+
+```html
+<div class="conclusion">
+  <h3><span class="num">01.</span>Title of the conclusion</h3>
+  <p style="opacity: 0.92;">Body text on dark background. Keep it short.</p>
+</div>
+```
+
+### Chart.js initialization (8 baseline types)
+
+See `templates/data-viz-report/skeleton.html` `<script>` at the bottom of the
+file. Copy the chart you need (dual-axis, horizontal bar, grouped bar,
+scatter, stacked, log-axis, radar, dual-axis 2-bar) and edit the `labels` /
+`data` arrays — keep the `options` block intact.
+
+**Always** set `Chart.defaults.animation = false` once at the top.
+
+---
+
+## 4. Cover archetype palette
+
+If your topic doesn't fit the navy + Apple-blue feel of `data-viz-report`,
+re-skin the cover gradient + accent. Examples (also in
+[design-guide.md](design-guide.md)):
+
+| Subject | Cover gradient | Accent |
+|---|---|---|
+| Healthcare / pharma | teal → ivory | `#0a7488` |
+| Finance / market data | charcoal → emerald | `#0c8a5d` |
+| Energy / industrial | graphite → ember | `#d4621a` |
+| AI research lab | violet → midnight | `#7c3aed` |
+| Sustainability / ESG | forest → khaki | `#3f7d3f` |
+
+Two reports on different subjects must read as two different publications.
+Reusing the same blue defeats the whole point of using HTML.
+
+---
+
+## 5. Hand-authoring an HTML from zero
+
+When no template fits, follow this order:
+
+1. Start from a minimal `@page` + `*` reset:
+   ```css
+   @page { size: A4 portrait; margin: 14mm 12mm; }
+   * { box-sizing: border-box;
+       -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+   ```
+2. Define `:root` CSS variables for palette (`--accent`, `--ink`, `--mute`,
+   `--rule`, `--hairline`).
+3. Build the cover, then the visible clickable TOC/index. Use real internal
+   anchors (`<a href="#section-id">`) and give every target section a stable,
+   unique `id`; see [html-pdf-spec.md §3.4](html-pdf-spec.md#34-clickable-toc--index-links).
+4. Build one body section, render, eyeball, iterate.
+5. Add primitives (KPI cards, chart card, pill table) by copying from
+   `data-viz-report/skeleton.html`.
+6. Run the **quality gate** in
+   [html-pdf-spec.md §11](html-pdf-spec.md#11-quality-gate-agent-self-check-before-declaring-done)
+   before declaring "done".
+
+---
+
+## 6. Verification checklist
+
+Run before committing the source HTML or reporting "PDF ready":
+
+- [ ] `bash scripts/make.sh render --in page.html --out out.pdf --wait 15000` exits 0
+- [ ] `pdfinfo out.pdf | grep Pages` matches expected page count (within ±1)
+- [ ] `pdftotext -layout out.pdf - | head -40` shows readable body text
+- [ ] PDF has a visible TOC/index for every multi-page output; TOC rows are
+      clickable internal links or the PDF has equivalent outline/bookmark
+      navigation for the same section targets
+- [ ] Spot-click at least 3 TOC/index entries (or all entries when fewer than 3)
+      and confirm they jump to the intended pages; for assembled PDFs, also
+      inspect link annotations/outlines with `pdfinfo` or `pypdf`
+- [ ] `open out.pdf` — eyeball: charts drew, no blank canvases, fonts correct,
+      no `⊃2;` artifacts
+- [ ] Last page is ≥ 1/3 full (not an orphan)
+- [ ] Source HTML has no remaining `<!-- PLACEHOLDER -->` tokens
+- [ ] Accent re-skinned away from default blue (unless subject is consumer
+      hardware)
+- [ ] At most 3 data colors + 1 accent in any single page
+
+---
+
+## 7. Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Blank chart canvases | Chromium snapshotted before Chart.js painted | Add `--wait 15000`; set `Chart.defaults.animation = false` |
+| Body text in default sans | Webfont didn't load before snapshot | Use system stack from spec §4, or `@font-face` from local file |
+| Color desaturated in print | Missing `print-color-adjust: exact` | Apply to universal selector `*`, not `body` |
+| Charts split across pages | Missing `.avoid-break` wrapper | Wrap each `.chart-card` |
+| Tables eat too much space | Full-width CJK punctuation | Use half-width `()`、`:`、`/` inside cells |
+| `3nm⊃2;` artifacts | HTML entity typo for `²` | Paste real unicode `²` `⁺` `™` etc |
+| Output PDF is 1 KB | Source HTML had a JS error (404 on Chart.js, etc) | Open the source in a browser, check Console |
+| Cover takes 2 pages | Cover height > 268 mm | Reduce padding or content; do not change `@page` margin |
+
+For deeper debugging see [`troubleshooting.md`](troubleshooting.md).

package/server/assets/skills/pdf/docs/design-guide.md

@@ -0,0 +1,204 @@
+# Design System
+
+The aesthetic layer. Read this before authoring any HTML report.
+This file answers "what should it look like and why." For *how* to wire the
+HTML so it survives Chromium's print snapshot, see
+[`html-pdf-spec.md`](html-pdf-spec.md).
+
+---
+
+## The one rule
+
+Every design decision must be **rooted in the document's content and purpose**.
+Dark teal + cream is not "professional". Serif + beige is not "elegant".
+A color chosen because it fits the content will always outperform a color chosen
+because it seems safe.
+
+---
+
+## Palette logic
+
+Pick a base palette by reading the content's mood, then declare the resulting
+hex values as CSS variables on `:root`. **Don't** keep a default blue because
+"blue is safe" — every report should look distinct from the last.
+
+### Mood → base palette
+
+| Content signal | Mood | Background | Accent | Text |
+|---|---|---|---|---|
+| Research, science, analysis | Authoritative | `#0F1F2E` deep ink | `#00B4A6` teal | `#F0EDE6` warm white |
+| Business, strategy, finance | Confident | `#1C1C2B` near-black | `#E8A020` amber | `#F5F2EC` cream |
+| Creative, portfolio, design | Expressive | `#1A0A2E` deep violet | `#FF6B6B` coral | `#FAF5FF` lavender white |
+| Education, academic paper | Scholarly | `#FAFAF7` warm white | `#2C4A7C` navy | `#1A1A2E` dark |
+| Healthcare, wellness | Calm | `#F5F9F8` pale mint | `#2D8B72` forest | `#1E3830` deep green |
+| Resume / personal | Clean | `#FFFFFF` white | pick from content | `#111111` near-black |
+| Formal publications, annual reports | Magazine | `#F2F0EC` warm linen | `#1C3557` deep navy | `#0D1A2B` near-black |
+| Premium / dark reports, tech reviews | Darkroom | `#151C27` deep navy | `#4A6FA5` steel blue | `#F0EDE6` warm white |
+| Technical docs, developer reports | Terminal | `#0D1117` near-black | `#39D353` neon green | `#E6EDF3` cool white |
+| Portfolios, creative, photography | Poster | `#FFFFFF` white | `#0A0A0A` near-black | `#0A0A0A` near-black |
+| General / unknown | Neutral | `#F8F6F1` warm off-white | `#3D3D3D` dark gray | `#1A1A1A` black |
+
+### Accent selection rules
+
+- **One accent color only.** Two accents split visual energy.
+- Accent appears on: cover geometric elements, section rules, callout left
+  borders, table header background, page header rule, chart primary series.
+  Nowhere else.
+- Accent must contrast with the cover background by at least **4.5:1** (WCAG
+  AA). Verify with any contrast checker before shipping.
+- **Do not default to blue.** Blue is the most overused accent in
+  AI-generated documents.
+
+### Color pairing anti-patterns
+
+| Avoid | Why |
+|---|---|
+| Purple gradient on white | The default AI aesthetic — immediately signals "generated" |
+| Navy + gold | Overused corporate cliche |
+| All-black background | Prints aggressive, ink-heavy |
+| More than 3 data colors + 1 accent | Visual noise |
+| Accent on body text | Destroys readability |
+
+---
+
+## Typography
+
+Two typefaces maximum. Always.
+
+| Role | Criteria | System-safe choices |
+|---|---|---|
+| Display (cover title, H1) | Distinctive, strong contrast, high weight | Times New Roman, Georgia, Cambria (serif) · SF Pro Display, Helvetica Neue (sans) |
+| Text (body, captions, UI) | Highly readable at 10–11 pt | Helvetica, Arial, SF Pro Text · Georgia, Cambria for serif body |
+
+Cover hero pairings by mood (load CDN webfonts via `@font-face` + a local
+fallback file under `assets/fonts/` — do not rely on a live CDN at render
+time):
+
+- Authoritative: Playfair Display / IBM Plex Sans
+- Confident: Syne / Nunito Sans
+- Expressive: Fraunces / Inter
+- Scholarly: EB Garamond / Source Sans 3
+- Clean: DM Serif Display / DM Sans
+- Restrained: Cormorant Garamond / Jost
+- Bold: Barlow Condensed / Barlow
+- Editorial: Bebas Neue / Libre Franklin
+- Classical: Cormorant / Crimson Pro
+- System fallback (always include last): `-apple-system, "PingFang SC",
+  "Helvetica Neue", Arial, sans-serif`
+
+### Type scale (suggested baseline)
+
+All sizes in `pt` (Chromium converts; never use `px` for body text in print).
+
+| Token | Size | Leading | Usage |
+|---|---|---|---|
+| display | 38–54 pt | 1.10–1.20 | Cover title |
+| h1 | 20–22 pt | 1.30 | Section headings |
+| h2 | 13–15 pt | 1.40 | Subsection headings |
+| h3 | 11.5–12 pt | 1.50 | Sub-subsection |
+| body | 10–11 pt | 1.55–1.65 | Main prose |
+| caption | 8.5–9 pt | 1.40 | Figure / table captions |
+| meta | 8 pt | 1.30 | Header / footer text |
+
+CJK font cascade rule: order is **SC → JP → KR → Latin → generic**. Putting
+JP before SC renders simplified-Chinese characters in JP forms. Apple SD
+Gothic Neo (or Noto Sans CJK KR) is required for Korean — Hiragino does not
+cover hangul.
+
+---
+
+## Cover design
+
+The cover is the most important page. It determines whether a reader trusts the
+document. The cover should occupy exactly one A4 page (~268 mm content height
+at 14 mm margin), end with `page-break-after: always`, and use full-bleed
+`-webkit-print-color-adjust: exact`.
+
+Pick a cover archetype that fits the mood. None of these are "the right one";
+pick the one that matches the content energy.
+
+| Archetype | Best for | Visual signature |
+|---|---|---|
+| **Full-bleed gradient hero** | Tech / data reports | Deep gradient + radial halo blobs + hero title + bottom meta strip |
+| **Split panel** | Proposals | Colored left 42% panel + right white panel + accent vertical rule |
+| **Typographic** | Resumes, academic papers | Off-white bg + oversized type + first word in accent + thin rule |
+| **Atmospheric** | Portfolios | Near-black bg + soft accent radial + low-opacity dot grid |
+| **Minimal bar** | Editorial summaries | White bg + 8 px accent left bar + huge light-weight title |
+| **Stripe** | Newspaper / brand poster | Three horizontal bands (accent / dark / light), hard edges |
+| **Diagonal** | Bold reports | SVG polygon diagonal cut, accent edge line traces it |
+| **Frame** | Annual reports, legal | Inset rectangular border + accent corner squares |
+| **Editorial** | Magazines | Ghost first-letter at low opacity + accent top bar + uppercase title |
+| **Magazine** | Centered formal | Cream/linen bg, vertical stack, optional hero image |
+| **Darkroom** | Premium tech reviews | Same as magazine but deep navy + grayscale hero filter |
+| **Terminal** | Developer / system reports | Near-black + neon green + monospace + grid overlay + bracket frame |
+| **Poster** | Creative, photography | White bg + thick accent left sidebar + 96 px condensed all-caps title |
+
+### What always kills a cover
+
+- Centered title on white background with a thin horizontal line beneath
+- Gradient from one color to another that reads as PowerPoint, not print
+- Drop shadows on text
+- More than one accent color
+- Emoji or icon fonts (fail silently in headless Chromium)
+
+---
+
+## Inner page restraint
+
+Every design decision should remove something, not add something. The page is
+done when there is nothing left to remove.
+
+- Accent appears on section rules / chart bars / pill backgrounds — **not**
+  on body headings, **not** on bullet markers.
+- No bordered card components inside body prose. Cards are reserved for
+  call-out roles: KPI grids, recommend cards, versus comparisons,
+  conclusion blocks, insight callouts.
+- No rounded corners on anything except callout boxes / KPI cards (≤ 12 px).
+- No shadows beyond `0 1px 3px rgba(0,0,0,0.04)` on chart cards (very subtle).
+- Tables: header row in accent (or dark gradient), zebra rows, no internal
+  grid lines except the outer box and a hairline between rows.
+- Callout boxes: left border in accent (3–4 px), very light tint background,
+  no icon decoration unless it's a single semantic emoji (⚡ insight, 🛠
+  pitfall).
+
+### Page header / footer
+
+Header (when used): document title left-aligned 7.5 pt muted + accent rule
+1.5 pt full width below. Footer: author left, page number right, light rule
+above. Both at 7.5 pt, color = `#86868b` or similar muted.
+
+---
+
+## Quality bar
+
+A PDF passes if a designer would not be embarrassed to hand it to a client.
+Concretely:
+
+- Cover has a clear visual identity that is not "generic AI output".
+- Body text is readable at arm's length without squinting.
+- Every page looks like it belongs to the same document.
+- No element bleeds off the edge or overlaps another.
+- Page numbers are present (when ≥ 5 pages) and correct.
+- The accent color appears fewer than 8 times per page on average.
+- Last page is ≥ 1/3 full — if not, expand content, do **not** shrink margins.
+- Two reports on different subjects don't look like reskins of each other —
+  the palette, typography, and cover archetype have all been adapted.
+
+---
+
+## Anti-patterns specific to AI-generated documents
+
+These are the tells that a reader spots in 2 seconds:
+
+| Tell | Fix |
+|---|---|
+| Apple-blue (`#007AFF`) on every report | Re-skin per subject (see palette table) |
+| Identical KPI 4-grid on every cover | Mix layouts: timeline, hero stat, single big number |
+| Stock emoji icons everywhere | One semantic emoji per callout, max 3 per page |
+| Tables with the default Chrome look (gray rows, blue header) | Use the accent header + zebra body + outer-box-only style |
+| Generic "Q3 2024 Strategy Review" cover with stock subtitle | Pull a real signal from the content for the subtitle |
+| All charts in the same orientation | Mix horizontal / vertical / radar / scatter to match data shape |
+
+When in doubt, look at the [`templates/`](../templates/) catalogue — every
+skeleton there has been tuned for a real bench-trace; copy the closest one
+and re-skin rather than starting from the generic blueprint.