mindmap-render

## When to use this skill

Use this skill when the user asks to:
- Create a mindmap from a topic or data.
- Convert a Markdown outline into a visual mindmap image or PDF.
- Generate a colorful, presentation-quality mindmap with auto-export to PNG/PDF.
- Build a structured outline (unordered list) and then render it as a mindmap.

## Prerequisites

Assume the runtime environment already has Python 3.10+, Playwright, and Chromium installed (they are provisioned in the container). **Do not proactively run `pip install` or `playwright install`** — just run the render script directly. Only if the first run fails with a clear missing-dependency error (ImportError, missing-browser error, etc.), then repair the environment:

```bash
pip install -r scripts/requirements.txt
playwright install chromium
```

and retry. Never install speculatively before a failure is observed.

## Workflow

### Step 1 — Determine input source

Ask the user (or infer from context):
- **Topic**: What is the central theme?
- **Data source**: Do they already have a Markdown file, or should you research and write one?
- **Source fidelity vs synthesis** — a spectrum, not a binary. The more specifically the request points to a **named existing artifact** (a particular book's table of contents (ToC), a particular course's syllabus, a specific spec or documentation structure, a numbered chapter list), the more you should **reproduce the source's real structure verbatim** — preserve original labels and numbering, follow the source's natural depth, and add NO fabricated descriptions. The more the request is a **broad topic** with no single canonical source, the more the structural targets below apply. Most requests sit somewhere on this spectrum; judge and lean accordingly.
- **Theme**: `air` (light blue glow + white cards, default), `editorial` (warm paper + jewel-tone branches), `midnight` (deep black + neon accents), or `zen` (soft misty background + muted pastels).
- **Language**: 
  - If the user explicitly specifies a language (e.g. "in English", "in Japanese"), use that language for all node text (labels + layer-5 descriptions).
  - Otherwise, match the language of the user's request; default to English when the request language is unclear.
  - Do not translate proper nouns, model names, or established technical terms — preserve them inline.

**Default structural targets — for synthesis work only.** These do NOT apply when you are faithfully reproducing a named source (in that case, follow the source's actual shape). They also yield to any numbers the user gives explicitly.
- **1 root** + **6–10 top-level branches** (default aim: ~9).
- **Maximum depth = 5 layers** (root → branch → subtopic → item → leaf-with-description). Layer 5 is reserved for the **important, information-dense** nodes — it is **not** a mandatory floor for every path.
- **Layer-5 leaves (when present) MUST carry a substantive description** — around **200 Chinese characters** (or ~150 English words if the mindmap is in English), roughly 2–4 sentences — that explains mechanism, why it matters, quantitative detail, or a concrete example. A one-line label is not enough at layer 5; if you cannot write ~200 Chinese characters of real content, the node does not belong at layer 5.
- Intermediate nodes (layers 2–4) stay concise (1–10 words) and may themselves be terminal leaves when that is the right level of detail.
- **Asymmetry is required, not a flaw.** Branches should be weighted by importance and information value, *not* padded for visual symmetry:
  - Pillar branches (where the real substance lives) should go deep and wide, with many children and rich layer-5 descriptions.
  - Supporting / well-known branches can stop at layer 2 or 3. Do not expand common knowledge the target reader already owns, and do not invent filler children just to match sibling counts.
  - When deciding "expand or stop," ask: *Would a knowledgeable reader learn something here?* If no, prune.
- The hierarchy is intentionally irregular. In Step 2c, report the shape honestly rather than forcing every branch to layer 5.

If the user gives different numbers, use theirs; otherwise treat the defaults above as **guidance with judgment** — breadth/depth targets are firm, but per-branch expansion is deliberately uneven.

### Step 2a — User provided a Markdown file

If the user already has a `.md` file, note its path and proceed to Step 3.

### Step 2b — Generate the Markdown outline yourself

**CRITICAL: If the user has NOT provided a `.md` file, you MUST perform web research BEFORE writing the outline.** Do not rely solely on internal knowledge.

1. **Research** (mandatory): Use `WebSearch` to find authoritative, high-quality sources:
   - Official book table of contents (publisher's catalog, Douban Books listing).
   - Wikipedia structured sections.
   - Academic course syllabi or reputable blog series.
   - Official documentation / white-paper outlines.
   - Recent industry reports, survey papers, or conference proceedings (e.g. NeurIPS, ICML, JPMorgan Quantitative Research).

   **Fail loudly if the authoritative source cannot be found.** When the user names a specific artifact (a particular book, edition, course, spec) and repeated searches do not surface its real ToC / syllabus / structure, **STOP** and tell the user: *"I couldn't find the authoritative structure of [X]. Please paste the ToC, confirm the edition/title, or allow me to produce a synthesized overview instead."* **Never invent chapter/section structure to fill the gap.** This is the single most important rule of this step.

2. **Write the outline** — choose the mode based on Step 1's fidelity-vs-synthesis judgment:

   **a) Faithful reproduction** (user pointed to a specific named artifact and you located its real structure): copy the ToC/outline verbatim into a single-root bullet list. Preserve original labels, chapter numbering, and natural depth. Do **not** add layer-5 descriptions, do **not** force 6–10 top-level br