fix: correct PNG resolution regression and inaccurate skill docs

Fixes found in a critical review of the previous commit:

- embed.ts: fix PNG resolution degradation on large diagrams. Export mode
  was reusing the interactive fitToContainer() scaling, which silently
  shrinks diagrams to fit an arbitrary viewport — a 21-node flowchart at
  default settings rendered at 444x1736px instead of its natural 2024x7936px.
  Export mode now always renders at true 1:1 scale.
- render.mjs: grow the PNG viewport to the diagram's natural size as a
  defensive fallback; drop the fragile global-puppeteer createRequire hack
  in favor of one consistent local-install story.
- SKILL.md/README: fix contradictory puppeteer install instructions
  (SKILL.md said -g, README said local — only local works with this
  script's ESM resolution). Remove the false "auto-installed via npx"
  compatibility claim. Remove allowed-tools (Claude-specific syntax,
  risky to pre-authorize Bash access across untested agents). Document
  that --width/--height only bound PNG output and never affect SVG.

Also split the single diagram-guide.md into two verified reference docs,
researched via web search and fact-checked against MermZen's actual
renderer (not just recalled from training data):
- references/style-guide.md: diagram types, node-count thresholds,
  direction/subgraph/shape conventions, hand-drawn-specific complexity
  limits, gantt/ER/sequence-diagram tips
- references/syntax-guide.md: LLM-common Mermaid syntax mistakes (reserved
  words, keyword collisions, quoting rules, classDef support by diagram
  type). Several claims from initial research were verified or corrected
  by actually rendering test cases: confirmed `end` as a bare node ID and
  sequence participants named `Loop` break rendering; confirmed classDef
  is a hard parse error in sequenceDiagram but a silent no-op in
  classDiagram/erDiagram; disproved and removed an unverified claim about
  underscores triggering markdown italics (doesn't reproduce on this
  Mermaid version/config).

Author: caoergou

README.md

@@ -259,7 +259,12 @@ node skills/mermzen-render/scripts/render.mjs \
 | `--font` | `kalam` | `kalam` or `caveat` (CJK auto-uses Xiaolai SC) |
 | `--bg` | `transparent` | CSS color, `transparent`, or `grid` |
 | `--scale` | `2` | Device scale factor for PNG |
-| `--width` | `1400` | Viewport width (px) |
-| `--height` | `900` | Viewport height (px) |
-
-Run `node skills/mermzen-render/scripts/render.mjs --help` for more details.
+| `--width` | `1400` | Minimum PNG canvas width (px); grows to fit large diagrams |
+| `--height` | `900` | Minimum PNG canvas height (px); grows to fit large diagrams |
+
+Diagrams always render at their true 1:1 size (never shrunk to fit), so PNG
+resolution reflects the diagram's real size regardless of `--width`/`--height`.
+SVG output is always the natural vector size — `--width`/`--height`/`--scale`
+don't apply to it. Run `node skills/mermzen-render/scripts/render.mjs --help`
+for more details. For diagram styling tips and common syntax pitfalls, see
+[skills/mermzen-render/references/](skills/mermzen-render/references/).

README.zh.md

@@ -252,8 +252,8 @@ node skills/mermzen-render/scripts/render.mjs \
 | `--font` | `kalam` | `kalam` 或 `caveat`（中文自动使用小赖字体） |
 | `--bg` | `transparent` | CSS 颜色、`transparent`、`grid` |
 | `--scale` | `2` | PNG 设备缩放系数 |
-| `--width` | `1400` | 视口宽度（px） |
-| `--height` | `900` | 视口高度（px） |
+| `--width` | `1400` | PNG 画布最小宽度（px）；大图会自动撑大 |
+| `--height` | `900` | PNG 画布最小高度（px）；大图会自动撑大 |
 
-运行 `node skills/mermzen-render/scripts/render.mjs --help` 查看完整用法。
+图表始终按真实 1:1 尺寸渲染（不会为适配小画布而被压缩），所以 PNG 分辨率取决于图表本身大小，与 `--width`/`--height` 无关；这两个参数只是设置最小画布尺寸。SVG 输出始终是矢量自然尺寸，不受 `--width`/`--height`/`--scale` 影响。运行 `node skills/mermzen-render/scripts/render.mjs --help` 查看完整用法。图表美化技巧和常见语法陷阱见 [skills/mermzen-render/references/](skills/mermzen-render/references/)。
 

skills/mermzen-render/SKILL.md

@@ -5,8 +5,7 @@ description: >
   and multiple themes. Use when asked to generate, render, or export a Mermaid diagram as
   an image file. Triggers: "render diagram", "mermaid to svg", "mermaid to png",
   "generate diagram", "draw flowchart", "draw sequence diagram", "export diagram".
-compatibility: Requires Node.js 18+ and Puppeteer (auto-installed on first run via npx)
-allowed-tools: Bash(node *) Bash(npx *)
+compatibility: Requires Node.js 18+ and a local Puppeteer install (npm install puppeteer)
 ---
 
 # MermZen Render
@@ -17,13 +16,19 @@ No need to clone any repository — the script uses the deployed MermZen instanc
 
 ## Prerequisites
 
-The render script requires **Node.js 18+** and **Puppeteer**. Install Puppeteer if not
-already available:
+The render script requires **Node.js 18+** and **Puppeteer**, installed locally
+(not globally — a global install won't be found by this script's module
+resolution):
 
 ```bash
-npm install -g puppeteer
+npm install puppeteer
 ```
 
+Run this from your project directory (or anywhere that's an ancestor
+directory of wherever this skill is installed) — Node resolves `puppeteer`
+by walking up from the script's location, so a local install anywhere above
+it in the directory tree works.
+
 ## Usage
 
 ```bash
@@ -36,6 +41,15 @@ node scripts/render.mjs --code "graph TD; A-->B-->C" --output diagram.svg
 node scripts/render.mjs --file diagram.mmd --output output.png --format png
 ```
 
+### Workflow: render, then look at the result
+
+Syntax-valid Mermaid can still render into something visually broken —
+clipped labels, a cramped layout, or the wrong orientation. After rendering,
+view the output image before reporting success. If rendering fails outright,
+check [references/syntax-guide.md](references/syntax-guide.md) for the likely
+cause, apply one targeted fix, and retry once before reporting the error to
+the user.
+
 ### Parameters
 
 | Parameter    | Default               | Description                                            |
@@ -50,10 +64,16 @@ node scripts/render.mjs --file diagram.mmd --output output.png --format png
 | `--font-size`| `16`                  | Font size in pixels                                    |
 | `--bg`       | `transparent`         | CSS color, `transparent`, or `grid`                    |
 | `--scale`    | `2`                   | Device scale factor for PNG (higher = sharper)         |
-| `--width`    | `1400`                | Viewport width (px)                                    |
-| `--height`   | `900`                 | Viewport height (px)                                   |
+| `--width`    | `1400`                | Minimum PNG canvas width (px); grows to fit large diagrams |
+| `--height`   | `900`                 | Minimum PNG canvas height (px); grows to fit large diagrams |
 | `--base-url` | `https://eric.run.place/MermZen` | Override the MermZen instance URL         |
 
+`--width`/`--height`/`--scale` only affect PNG output — SVG always exports at
+its natural vector size. Diagrams always render at their true 1:1 size (never
+shrunk to fit a small canvas), so PNG resolution reflects the diagram's real
+size regardless of `--width`/`--height`; they only set a *minimum* canvas,
+useful for adding extra padding around a small diagram.
+
 Run `node scripts/render.mjs --help` for the full usage info.
 
 ### Themes, fonts, and styles
@@ -109,15 +129,20 @@ node scripts/render.mjs \
 4. Extracts the SVG from the DOM or takes a PNG screenshot
 5. Writes the result to the output file
 
-## Diagram guide
+## References
 
-For supported diagram types, styling tips, and best practices for creating
-beautiful diagrams, see [references/diagram-guide.md](references/diagram-guide.md).
+- [references/style-guide.md](references/style-guide.md) — supported diagram
+  types, node-count thresholds, direction/layout choices, and styling tips
+  for making diagrams look good
+- [references/syntax-guide.md](references/syntax-guide.md) — reserved words,
+  quoting rules, and other syntax pitfalls that break rendering; read this
+  first if a render fails
 
 ## Troubleshooting
 
 | Symptom | Fix |
 |---------|-----|
-| `Cannot find module 'puppeteer'` | Run `npm install -g puppeteer` |
+| `Cannot find module 'puppeteer'` | Run `npm install puppeteer` (local, not global — see Prerequisites) |
+| Render hangs / times out with no error | Usually a Mermaid syntax error (e.g. a reserved word, unquoted special character) — check [references/syntax-guide.md](references/syntax-guide.md) |
 | Timeout / blank output | Check network connectivity (the script fetches from eric.run.place) |
 | CJK text clipped | Re-run — font CDN may have been slow on first load |