@nguyenphp/antigravity-marketing 1.0.18 → 1.0.20

package/templates/.agent/skills/minimax-pdf/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: minimax-pdf
+description: >
+  Use this skill when visual quality and design identity matter for a PDF.
+  CREATE (generate from scratch): "make a PDF", "generate a report", "write a proposal",
+  "create a resume", "beautiful PDF", "professional document", "cover page",
+  "polished PDF", "client-ready document".
+  FILL (complete form fields): "fill in the form", "fill out this PDF",
+  "complete the form fields", "write values into PDF", "what fields does this PDF have".
+  REFORMAT (apply design to an existing doc): "reformat this document", "apply our style",
+  "convert this Markdown/text to PDF", "make this doc look good", "re-style this PDF".
+  This skill uses a token-based design system: color, typography, and spacing are derived
+  from the document type and flow through every page. The output is print-ready.
+  Prefer this skill when appearance matters, not just when any PDF output is needed.
+license: MIT
+metadata:
+  version: "1.0"
+  category: document-generation
+---
+
+# minimax-pdf
+
+Three tasks. One skill.
+
+## Read `design/design.md` before any CREATE or REFORMAT work.
+
+---
+
+## Route table
+
+| User intent | Route | Scripts used |
+|---|---|---|
+| Generate a new PDF from scratch | **CREATE** | `palette.py` → `cover.py` → `render_cover.js` → `render_body.py` → `merge.py` |
+| Fill / complete form fields in an existing PDF | **FILL** | `fill_inspect.py` → `fill_write.py` |
+| Reformat / re-style an existing document | **REFORMAT** | `reformat_parse.py` → then full CREATE pipeline |
+
+**Rule:** when in doubt between CREATE and REFORMAT, ask whether the user has an existing document to start from. If yes → REFORMAT. If no → CREATE.
+
+---
+
+## Route A: CREATE
+
+Full pipeline — content → design tokens → cover → body → merged PDF.
+
+```bash
+bash scripts/make.sh run \
+  --title "Q3 Strategy Review" --type proposal \
+  --author "Strategy Team" --date "October 2025" \
+  --accent "#2D5F8A" \
+  --content content.json --out report.pdf
+```
+
+**Doc types:** `report` · `proposal` · `resume` · `portfolio` · `academic` · `general` · `minimal` · `stripe` · `diagonal` · `frame` · `editorial` · `magazine` · `darkroom` · `terminal` · `poster`
+
+| Type | Cover pattern | Visual identity |
+|---|---|---|
+| `report` | `fullbleed` | Dark bg, dot grid, Playfair Display |
+| `proposal` | `split` | Left panel + right geometric, Syne |
+| `resume` | `typographic` | Oversized first-word, DM Serif Display |
+| `portfolio` | `atmospheric` | Near-black, radial glow, Fraunces |
+| `academic` | `typographic` | Light bg, classical serif, EB Garamond |
+| `general` | `fullbleed` | Dark slate, Outfit |
+| `minimal` | `minimal` | White + single 8px accent bar, Cormorant Garamond |
+| `stripe` | `stripe` | 3 bold horizontal color bands, Barlow Condensed |
+| `diagonal` | `diagonal` | SVG angled cut, dark/light halves, Montserrat |
+| `frame` | `frame` | Inset border, corner ornaments, Cormorant |
+| `editorial` | `editorial` | Ghost letter, all-caps title, Bebas Neue |
+| `magazine` | `magazine` | Warm cream bg, centered stack, hero image, Playfair Display |
+| `darkroom` | `darkroom` | Navy bg, centered stack, grayscale image, Playfair Display |
+| `terminal` | `terminal` | Near-black, grid lines, monospace, neon green |
+| `poster` | `poster` | White bg, thick sidebar, oversized title, Barlow Condensed |
+
+Cover extras (inject into tokens via `--abstract`, `--cover-image`):
+- `--abstract "text"` — abstract text block on the cover (magazine/darkroom)
+- `--cover-image "url"` — hero image URL/path (magazine, darkroom, poster)
+
+**Color overrides — always choose these based on document content:**
+- `--accent "#HEX"` — override the accent color; `accent_lt` is auto-derived by lightening toward white
+- `--cover-bg "#HEX"` — override the cover background color
+
+**Accent color selection guidance:**
+
+You have creative authority over the accent color. Pick it from the document's semantic context — title, industry, purpose, audience — not from generic "safe" choices. The accent appears on section rules, callout bars, table headers, and the cover: it carries the document's visual identity.
+
+| Context | Suggested accent range |
+|---|---|
+| Legal / compliance / finance | Deep navy `#1C3A5E`, charcoal `#2E3440`, slate `#3D4C5E` |
+| Healthcare / medical | Teal-green `#2A6B5A`, cool green `#3A7D6A` |
+| Technology / engineering | Steel blue `#2D5F8A`, indigo `#3D4F8A` |
+| Environmental / sustainability | Forest `#2E5E3A`, olive `#4A5E2A` |
+| Creative / arts / culture | Burgundy `#6B2A35`, plum `#5A2A6B`, terracotta `#8A3A2A` |
+| Academic / research | Deep teal `#2A5A6B`, library blue `#2A4A6B` |
+| Corporate / neutral | Slate `#3D4A5A`, graphite `#444C56` |
+| Luxury / premium | Warm black `#1A1208`, deep bronze `#4A3820` |
+
+**Rule:** choose a color that a thoughtful designer would select for this specific document — not the type's default. Muted, desaturated tones work best; avoid vivid primaries. When in doubt, go darker and more neutral.
+
+**content.json block types:**
+
+| Block | Usage | Key fields |
+|---|---|---|
+| `h1` | Section heading + accent rule | `text` |
+| `h2` | Subsection heading | `text` |
+| `h3` | Sub-subsection (bold) | `text` |
+| `body` | Justified paragraph; supports `<b>` `<i>` markup | `text` |
+| `bullet` | Unordered list item (• prefix) | `text` |
+| `numbered` | Ordered list item — counter auto-resets on non-numbered blocks | `text` |
+| `callout` | Highlighted insight box with accent left bar | `text` |
+| `table` | Data table — accent header, alternating row tints | `headers`, `rows`, `col_widths`?, `caption`? |
+| `image` | Embedded image scaled to column width | `path`/`src`, `caption`? |
+| `figure` | Image with auto-numbered "Figure N:" caption | `path`/`src`, `caption`? |
+| `code` | Monospace code block with accent left border | `text`, `language`? |
+| `math` | Display math — LaTeX syntax via matplotlib mathtext | `text`, `label`?, `caption`? |
+| `chart` | Bar / line / pie chart rendered with matplotlib | `chart_type`, `labels`, `datasets`, `title`?, `x_label`?, `y_label`?, `caption`?, `figure`? |
+| `flowchart` | Process diagram with nodes + edges via matplotlib | `nodes`, `edges`, `caption`?, `figure`? |
+| `bibliography` | Numbered reference list with hanging indent | `items` [{id, text}], `title`? |
+| `divider` | Accent-colored full-width rule | — |
+| `caption` | Small muted label | `text` |
+| `pagebreak` | Force a new page | — |
+| `spacer` | Vertical whitespace | `pt` (default 12) |
+
+**chart / flowchart schemas:**
+```json
+{"type":"chart","chart_type":"bar","labels":["Q1","Q2","Q3","Q4"],
+ "datasets":[{"label":"Revenue","values":[120,145,132,178]}],"caption":"Q results"}
+
+{"type":"flowchart",
+ "nodes":[{"id":"s","label":"Start","shape":"oval"},
+          {"id":"p","label":"Process","shape":"rect"},
+          {"id":"d","label":"Valid?","shape":"diamond"},
+          {"id":"e","label":"End","shape":"oval"}],
+ "edges":[{"from":"s","to":"p"},{"from":"p","to":"d"},
+          {"from":"d","to":"e","label":"Yes"},{"from":"d","to":"p","label":"No"}]}
+
+{"type":"bibliography","items":[
+  {"id":"1","text":"Author (Year). Title. Publisher."}]}
+```
+
+---
+
+## Route B: FILL
+
+Fill form fields in an existing PDF without altering layout or design.
+
+```bash
+# Step 1: inspect
+python3 scripts/fill_inspect.py --input form.pdf
+
+# Step 2: fill
+python3 scripts/fill_write.py --input form.pdf --out filled.pdf \
+  --values '{"FirstName": "Jane", "Agree": "true", "Country": "US"}'
+```
+
+| Field type | Value format |
+|---|---|
+| `text` | Any string |
+| `checkbox` | `"true"` or `"false"` |
+| `dropdown` | Must match a choice value from inspect output |
+| `radio` | Must match a radio value (often starts with `/`) |
+
+Always run `fill_inspect.py` first to get exact field names.
+
+---
+
+## Route C: REFORMAT
+
+Parse an existing document → content.json → CREATE pipeline.
+
+```bash
+bash scripts/make.sh reformat \
+  --input source.md --title "My Report" --type report --out output.pdf
+```
+
+**Supported input formats:** `.md` `.txt` `.pdf` `.json`
+
+---
+
+## Environment
+
+```bash
+bash scripts/make.sh check   # verify all deps
+bash scripts/make.sh fix     # auto-install missing deps
+bash scripts/make.sh demo    # build a sample PDF
+```
+
+| Tool | Used by | Install |
+|---|---|---|
+| Python 3.9+ | all `.py` scripts | system |
+| `reportlab` | `render_body.py` | `pip install reportlab` |
+| `pypdf` | fill, merge, reformat | `pip install pypdf` |
+| Node.js 18+ | `render_cover.js` | system |
+| `playwright` + Chromium | `render_cover.js` | `npm install -g playwright && npx playwright install chromium` |
+
+---
+
+## 🤝 Collaborative Design
+
+This skill is designed to work with **`ui-ux-pro-max`** and **`frontend-design`**.
+
+- **Tokens**: Before running `make.sh`, use `ui-ux-pro-max` to derive the optimal `--accent` and `--type` based on the document's purpose.
+- **Layout**: Use `frontend-design` to structure complex reporting sections (like social proof or feature deep-dives) before mapping them to tệp `content.json`.

package/templates/.agent/skills/minimax-pdf/design/design.md

@@ -0,0 +1,381 @@
+# Design System
+
+The aesthetic layer. Read this before touching any script.
+This file answers "what should it look like and why."
+
+---
+
+## 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
+
+`palette.py` takes a short content description and outputs `tokens.json`.
+Here is the reasoning it applies:
+
+### 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 |
+| General / unknown | Neutral | `#F8F6F1` warm off-white | `#3D3D3D` dark gray | `#1A1A1A` 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 |
+
+### Accent selection rules
+
+- **One accent color only.** Using two accents splits visual energy.
+- Accent appears on: cover geometric elements, section rules, callout left borders,
+  table header background, page header rule. Nowhere else.
+- Accent must contrast with the cover background by at least 4.5:1 (WCAG AA).
+- Do not default to blue. Blue is the most overused accent in AI-generated documents.
+
+### Color pairing anti-patterns (never use these)
+
+| ❌ Avoid | Why |
+|---|---|
+| Purple gradient on white | The default AI aesthetic — immediately signals "generated" |
+| Navy + gold | Overused corporate cliché |
+| All-black background | Prints badly, feels aggressive |
+| More than 3 colors in the system | Visual noise |
+| Accent on body text | Destroys readability |
+
+---
+
+## Typography system
+
+### Font pairing logic
+
+Two typefaces maximum. Always.
+
+| Role | Criteria | Good choices (system-safe) |
+|---|---|---|
+| Display (cover title, H1) | Distinctive, strong contrast, high weight | Times New Roman, Georgia (serif) |
+| Text (body, captions, UI) | Highly readable at 10–11pt | Helvetica, Arial (sans) |
+
+Cover fonts are loaded live via `@import url(...)` in the cover HTML — Playwright
+fetches them at render time, no local caching. Body pages always use system fonts
+(Times-Bold / Helvetica) via ReportLab — consistent and offline-safe.
+
+Pairs by mood (cover HTML only — body always uses system fonts):
+- 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`
+- Dynamic: `Montserrat` / `Montserrat`
+- Classical: `Cormorant` / `Crimson Pro`
+- Editorial: `Bebas Neue` / `Libre Franklin`
+- Body fallback (always): `Times-Bold` / `Helvetica` (ReportLab system fonts)
+
+### Type scale
+
+All sizes in points. This scale is used by `palette.py` to populate `tokens.json`.
+
+| Token | Size | Leading | Usage |
+|---|---|---|---|
+| `display` | 54pt | 1.0 | Cover title |
+| `h1` | 22pt | 1.3 | Section headings |
+| `h2` | 15pt | 1.4 | Subsection headings |
+| `h3` | 11.5pt | 1.5 | Sub-subsection |
+| `body` | 10.5pt | 1.6 | Main prose |
+| `caption` | 8.5pt | 1.4 | Figure/table captions |
+| `meta` | 8pt | 1.3 | Header/footer text |
+
+### Spacing system
+
+Margins and rhythm are what separate "looks designed" from "looks printed".
+
+| Token | Value | Notes |
+|---|---|---|
+| `margin_outer` | 2.8cm | Left/right page margin |
+| `margin_top` | 2.8cm | Top page margin |
+| `margin_bottom` | 2.5cm | Bottom page margin |
+| `section_gap` | 26pt | Space before H1 |
+| `para_gap` | 8pt | Space after paragraph |
+| `line_gap` | 17pt | Leading for body text |
+
+Never use ReportLab's default margins (too tight). Always set explicitly.
+
+---
+
+## Cover design
+
+The cover is the most important page. It determines whether a reader trusts the document.
+
+### Thirteen cover patterns
+
+`cover.py` selects one based on `tokens.json["cover_pattern"]`.
+
+**1. `fullbleed`** — used for: `report`, `general`
+- Deep background fills 100% of page
+- Title: large, left-aligned, upper 60% of page
+- Accent: thin horizontal rule + top-right corner strip
+- Dot-grid background texture (subtle, 8–10% opacity)
+- Footer band: author + date metadata
+- Fonts: Playfair Display / IBM Plex Sans
+
+**2. `split`** — used for: `proposal`
+- Left 42% panel: solid cover color, title + author
+- Right 58%: off-white, dot-grid decoration
+- Hard vertical dividing line in accent color
+- No gradients — pure flat geometry
+- Fonts: Syne / Nunito Sans
+
+**3. `typographic`** — used for: `resume`, `academic`
+- White/off-white background
+- Name or title as oversized display type (60–80pt), left-aligned
+- First word in accent color, remainder in dark
+- Thin rule below title block
+- Fonts: DM Serif Display / DM Sans (resume) · EB Garamond / Source Sans 3 (academic)
+
+**4. `atmospheric`** — used for: `portfolio`
+- Near-black background
+- Soft radial glow in accent color (upper-right quadrant)
+- Title centered-left, 2 lines max
+- Short rule in accent below title
+- Dot-grid texture at low opacity
+- Fonts: Fraunces / Inter
+
+**5. `minimal`** — used for: `minimal`
+- Near-white background, 8px left accent bar is the only color
+- Title in very large, light-weight display type (300 weight)
+- Hairline rule, author + date as single muted line
+- Nothing else — the bar does all the visual work
+- Fonts: Cormorant Garamond / Jost
+
+**6. `stripe`** — used for: `stripe`
+- Page cut into three horizontal bands: accent / dark / light
+- Top band: category label; middle: oversized title in white; bottom: metadata
+- Hard edges, no gradients, no textures — newspaper / brand poster aesthetic
+- Fonts: Barlow Condensed / Barlow
+
+**7. `diagonal`** — used for: `diagonal`
+- SVG polygon cuts page diagonally: dark upper-left, light lower-right
+- Accent-colored edge line traces the diagonal cut
+- Title on dark area, metadata on light area
+- Fonts: Montserrat / Montserrat
+
+**8. `frame`** — used for: `frame`
+- White/cream background with an inset rectangular border (1.2px, 28px from edges)
+- Accent strips inside top + bottom of frame; small accent corner squares
+- Title centered in the frame space, centered alignment, classical weight
+- Formal, timeless — annual reports, legal documents, academic papers
+- Fonts: Cormorant / Crimson Pro
+
+**9. `editorial`** — used for: `editorial`
+- Ghost first-letter of title fills upper-right at 5% opacity — visual texture
+- 5px accent top bar; full-width uppercase title in condensed weight
+- Title all-caps, very large (80px), flush-left
+- Footer rule + author/date metadata
+- Fonts: Bebas Neue / Libre Franklin
+
+**10. `magazine`** — used for: `magazine`
+- Warm cream/linen background; fully centered, vertical stack layout
+- Org/company name in small spaced caps + 2px accent rule beneath (top anchor)
+- Large bold serif title (52px) centered; short accent rule under title
+- Italic subtitle; optional `cover_image` URL renders as centered hero thumbnail
+- Optional `abstract` field: justified text block with bold "Abstract:" label
+- Author name in accent color (large, bold); date beneath
+- Fonts: Playfair Display / EB Garamond
+
+**11. `darkroom`** — used for: `darkroom`
+- Same centered stack layout as `magazine` but deep navy background, white text
+- Org name + rules in semi-transparent white; accent rules desaturated
+- Hero image (if provided) gets `grayscale(20%) brightness(0.9)` filter
+- Fonts: Playfair Display / EB Garamond
+
+**12. `terminal`** — used for: `terminal`
+- Near-black background; neon green accent; Space Mono monospace throughout
+- Grid overlay: faint horizontal + vertical lines at 48px intervals (7% opacity)
+- Status label top-left: green dot + `SYSTEM_REPORT // <date>`
+- Title inside a bracket frame (border-left + border-top + pseudo-element corner)
+- Subtitle prefixed with `>` in accent color
+- Abstract text left; author block right; status bar at bottom (UTF-8 / Ln 1)
+- Fonts: Space Mono / Space Mono
+
+**13. `poster`** — used for: `poster`
+- White background; thick 52px left sidebar in accent (typically near-black)
+- Title: 96px, 900-weight, all-caps, condensed — the dominant visual element
+- Subtitle in typewriter font below title; thin 2px rule as separator
+- Author + meta in Courier Prime monospace beneath rule
+- Optional `cover_image` rendered as 260×340 grayscale thumbnail, right-aligned
+- Accent square icon block (lower-right) with white horizontal lines
+- Fonts: Barlow Condensed / Courier Prime
+
+### Optional token: `cover_image`
+
+Patterns `magazine`, `darkroom`, and `poster` accept an optional `cover_image`
+token containing an absolute URL or `file://` path to an image.
+The image renders via `<img src="...">` — Playwright fetches it at render time.
+If omitted, the image area is simply skipped (layout adjusts gracefully).
+
+### Cover CSS requirements (critical for Playwright rendering)
+
+These three rules must appear in every cover HTML file or the output will have
+white borders / incorrect dimensions:
+
+```css
+body { margin: 0; padding: 0; }
+html, body { width: 794px; height: 1123px; overflow: hidden; }
+```
+
+No `@page` rules needed — Playwright handles page size via the `pdf()` call.
+Do NOT use CSS `background-image` for textures — use inline SVG or `<canvas>`.
+Always use `position: absolute` + `z-index` for layered elements.
+
+### What always kills a cover
+
+- Centered title on white background with a thin horizontal line underneath
+- Gradient from one color to another (reads as PowerPoint, not print design)
+- Drop shadows on text
+- More than one accent color
+- Emoji or icon fonts (fail silently on headless Chromium)
+
+---
+
+## Inner page rules
+
+### What "restraint" means in practice
+
+Every design decision should remove something, not add something.
+The page is done when there is nothing left to remove.
+
+- Accent color appears on section rules only — not on headings, not on bullets
+- No card components (bordered boxes with colored headers)
+- No rounded corners on anything except callout boxes (4px max)
+- No shadows anywhere
+- Tables: header row in accent, alternating row tint, no grid lines except outer box
+- Callout boxes: left border in accent (4px), very light tint background, no icon
+
+### Page header / footer
+
+Header: document title (left, 7.5pt, muted) + accent rule (1.5pt, full width below)
+Footer: author name (left, 7.5pt, muted) + page number (right, 7.5pt, muted) + light rule above
+
+---
+
+## 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 and correct
+- The accent color appears fewer than 8 times per page on average
+
+---
+
+## Block type reference
+
+All body blocks use the same token system — colors and fonts come from `tokens.json`, never hardcoded.
+
+| Block | Rendering | Design notes |
+|---|---|---|
+| `h1` | 22pt heading + full-width accent rule below | KeepTogether with rule — heading never orphaned |
+| `h2` | 15pt heading, dark text | No rule, no accent — visual hierarchy through size only |
+| `h3` | 11.5pt bold, dark text | **No accent color** — accent on body headings violates the one-accent-location rule |
+| `body` | 10.5pt justified, 17pt leading | Supports `<b>` `<i>` `<font>` markup |
+| `bullet` | Body size with `•` prefix, 14pt indent | Use for unordered lists |
+| `numbered` | Body size with `N.` prefix, hanging indent | Counter auto-resets on any non-numbered block — no manual numbering needed |
+| `callout` | Accent left-border (4px) + light tint background | Max one callout per section — overuse kills impact |
+| `table` | Accent header row, alternating row tint, outer box only | Supports `col_widths` (fractions, e.g. `[0.3, 0.5, 0.2]`) for custom column widths |
+| `image` | Scaled to column width, preserving aspect ratio | Use `path` or `src`; always provide a `caption` |
+| `figure` | Same as image, but caption auto-prefixed "Figure N:" | Figure counter increments across all `figure`, `chart`, `flowchart` blocks |
+| `code` | Courier 8.5pt, accent left-border, light tint background | Supports optional `language` label (rendered above block) |
+| `math` | Formula centered, optional right-aligned equation label | LaTeX syntax; matplotlib mathtext renderer |
+| `chart` | Bar / line / pie chart rendered via matplotlib | Color palette derived from document accent; figure auto-numbered |
+| `flowchart` | Process diagram with labeled arrows | Supports 4 node shapes; back-edges drawn as curved arcs |
+| `bibliography` | Numbered reference list with hanging indent | Heading rendered as h2 + accent rule; items as `[N] text` |
+| `divider` | Accent-colored 1.2pt rule with padding | Use sparingly — only for major thematic breaks |
+| `caption` | 8.5pt muted text, centered | Appears below images/tables via field or explicit block |
+| `pagebreak` | Force page break | — |
+| `spacer` | Vertical whitespace | `pt` field (default 12) |
+
+### Math formula guidance
+
+**Input syntax:** standard LaTeX math notation — `\frac{}{}`, `\int`, `\sum`, `\alpha`, `^`, `_`, etc.
+**Rendering engine:** matplotlib mathtext — pure Python, no LaTeX compiler, no browser required.
+
+| Syntax example | Rendered as |
+|---|---|
+| `E = mc^2` | Inline expression |
+| `\frac{\sqrt{\pi}}{2}` | Fraction |
+| `\int_0^\infty e^{-x^2} dx` | Integral |
+| `\sum_{i=1}^{n} x_i` | Summation |
+| `\alpha + \beta = \gamma` | Greek letters |
+
+**Limitations:** matplotlib mathtext covers most common expressions but not advanced LaTeX environments (`align`, `cases`, `matrix`). Split complex multi-line proofs into multiple `math` blocks.
+
+**Fallback:** if matplotlib is not installed, renders as `expression` in code style. Run `make.sh fix` to install.
+
+**Equation labels:** `"label": "(1)"` — rendered right-aligned beside the formula.
+
+### Chart guidance
+
+**Rendered entirely in Python** — no external chart services, image files, or internet required.
+
+| chart_type | Use case | Required fields |
+|---|---|---|
+| `bar` | Comparing discrete categories | `labels`, `datasets` |
+| `line` | Trends over time or ordered categories | `labels`, `datasets` |
+| `pie` | Part-to-whole composition | `labels`, `datasets[0].values` |
+
+- Colors are derived from the document accent for visual consistency — do not set custom colors.
+- Multi-series: add multiple objects to `datasets`, each with a `label` and `values` array.
+- Figure auto-numbering: set `"figure": true` (default) or `"figure": false` to suppress.
+
+### Flowchart guidance
+
+**Node shapes:**
+
+| shape | Use for |
+|---|---|
+| `rect` (default) | Process step |
+| `diamond` | Decision / condition |
+| `oval` or `terminal` | Start / End |
+| `parallelogram` | Input / Output |
+
+- Nodes are placed in input order (top to bottom). This controls the layout.
+- Forward edges draw straight arrows; back-edges (to earlier nodes) draw curved arcs.
+- Keep labels short (3–5 words max) — the diagram is A4-column-width at 78% scale.
+- Figure auto-numbering applies same as chart.
+
+### Bibliography guidance
+
+- `id` field is the reference label — use numbers ("1", "2") or alphanumeric ("Smith23").
+- Text should be in a consistent citation style (APA, Chicago, etc.) — the renderer does not enforce style.
+- The `title` field defaults to "References". Set `"title": ""` to suppress the heading.
+- A `bibliography` block always starts with a new section heading + accent rule.
+
+### Image / figure guidance
+
+- Preferred formats: PNG, JPEG
+- Scaled down if wider than the text column; never scaled up
+- `figure` blocks auto-number; `image` blocks do not — use `figure` for numbered figures
+- If the file does not exist at render time, a `[Image not found]` placeholder is substituted
+
+### Code block guidance
+
+- Preserves whitespace exactly — do not indent code in the JSON value
+- Optional `language` field renders a small language label above the block (e.g., `"language": "python"`)
+- No syntax highlighting (by design) — consistent with restraint principle
+- Keep lines under ~90 characters for A4 column width