skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/converters/skills/mermaid-render/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mermaid-render
+description: Check Mermaid diagrams for the mistakes that stop them rendering (unknown diagram type, unbalanced brackets or quotes, unquoted parentheses in labels, the word end as a node id, missing arrows, unclosed subgraphs or alt blocks) with line numbers and a fix for each, then render them to SVG, PNG or PDF with mermaid-cli, or to a standalone HTML page when it is not installed. Works on a .mmd file or every mermaid fence in a Markdown doc. Use when a diagram "won't render", the user says "check my mermaid", "export this diagram as SVG/PNG", or needs the diagrams in a doc as image files.
+---
+
+# mermaid-render
+
+You make Mermaid diagrams render, then turn them into files. Most Mermaid failures are a
+handful of syntax mistakes that the live editor reports as "Parse error on line 2" with no
+hint. The lint here names the mistake, the line, and the fix. Then the script renders: with
+`mmdc` (mermaid-cli) when it is installed, otherwise to an HTML page that draws the diagrams
+in a browser. Diagrams usually come from `architecture-diagrams`; the rendered SVGs go into
+`md-to-html` or `md-to-docx` as images.
+
+## How to respond
+
+1. **Ask once for what is missing.** Usually only the input:
+
+   > Send the diagram (a `.mmd` file, or the Markdown doc it lives in). Optional:
+   > 1. **Output:** `svg` (sharp at any size, best for docs) · `png` (for slides and chat) ·
+   >    `pdf` · `html`. *Default: lint only, or `svg` if the user asked for a file.*
+   > 2. **Where to write it.** *Default: next to the input.*
+
+2. **Lint first, always.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/render_mermaid.py" diagram.mmd
+   # Other IDEs (from the skill folder)
+   python3 scripts/render_mermaid.py diagram.mmd
+   ```
+
+   For a `.md` file the script finds every ```` ```mermaid ```` fence, and line numbers refer to
+   the `.md` file. Exit code 1 means at least one error.
+
+3. **Fix each error without changing what the diagram says.** Apply the fix the lint names:
+
+   | Lint says | Fix |
+   |---|---|
+   | unquoted `(` `)` in a label | ✅ `api["Orders API (v2)"]` · ❌ `api[Orders API (v2)]` |
+   | arrow label has unquoted brackets | ✅ `-->|"HTTPS (443)"|` · ❌ `-->|HTTPS (443)|` |
+   | `end` is reserved | ✅ `done([Done])` or `End` · ❌ `queue --> end` |
+   | `->` is not a flowchart arrow | ✅ `a --> b` · ❌ `a -> b` |
+   | no arrow between `a` and `b` | Add the arrow the author meant, or put the two nodes on separate lines |
+   | subgraph / `alt` has no `end` | Add `end` where the block should close, judged from the indentation |
+   | unknown diagram type | Use the suggested keyword (`flowchart`, `sequenceDiagram`, `stateDiagram-v2` …) |
+
+   Show the user a before/after of each changed line. When the intent is unclear (which node
+   did `worker cache` mean to connect?), ask rather than guess.
+
+4. **Render once lint is clean.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/render_mermaid.py" design.md -o figures/design.svg
+   # Other IDEs (from the skill folder)
+   python3 scripts/render_mermaid.py design.md -o figures/design.svg
+   ```
+
+   - One diagram writes `design.svg`; a doc with several writes `design-1.svg`, `design-2.svg`
+     … in document order.
+   - `.png` renders on white at 2× scale for slides.
+   - Without `mmdc` the script writes `design.html` instead, which draws every diagram with
+     Mermaid 11.4.1 (pinned) from jsDelivr, and says so. Tell the user that page needs network
+     when opened, and that `npm install -g @mermaid-js/mermaid-cli` gets real SVG/PNG files.
+   - `--force` renders despite lint errors. Use it only to show the user Mermaid's own error.
+
+5. **Report:** files written, any `mmdc` failure verbatim, and the fixes made.
+
+**Non-interactive runs** (subagent, CI, headless): lint, apply only the fixes the table above
+makes unambiguous, mark each with `[assumption]`, and render. If a fix needs the author's
+intent (a missing arrow, where a block ends), emit `BLOCKED: need the intended <connection |
+block end> at <file>:<line>` and do not render that diagram.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): every lint rule, what it catches and why Mermaid fails on it, how it was checked against Mermaid 11.4.1, and what lint does not cover
+- [`scripts/render_mermaid.py`](scripts/render_mermaid.py): lint and render (stdlib; `mmdc` optional)
+- [`examples/broken-diagrams.md`](examples/broken-diagrams.md): real lint output on broken and clean diagrams, a fix, and the no-`mmdc` fallback
+
+## Quality bar
+
+- **Every error has a line number and a fix,** in the user's file, not in a temporary copy.
+- **Fixes keep the meaning.** Same nodes, same edges, same labels; only syntax changes.
+- **Clean diagrams pass.** The `architecture-diagrams` examples and templates lint clean, and lint never blocks a diagram Mermaid itself accepts.
+- **The output format matches the use:** SVG for documents, PNG for slides and chat.
+- **Network dependence is stated.** The HTML fallback is named as needing network, with the install line for real files.
+
+## When to use this skill
+
+- ✅ A Mermaid diagram shows "Syntax error" or "Parse error" and the user can't see why
+- ✅ Exporting diagrams from a design doc as SVG or PNG for slides, Word or Confluence
+- ✅ Checking every diagram in a doc before it is shared or merged
+- ✅ Embedding diagrams in an HTML or Word export that must work offline
+
+## When NOT to use this skill
+
+- ❌ Drawing a new diagram from a description; use `architecture-diagrams`
+- ❌ Converting the whole Markdown doc to a web page; use `md-to-html` (render the diagrams here first if readers are offline)
+- ❌ Converting the whole doc to Word; use `md-to-docx`
+
+## Anti-patterns to avoid
+
+- ❌ **"Fixing" a label by deleting the parenthesised part.** Quote the label; keep the words.
+- ❌ **Renaming `end` to `End` in a subgraph closer.** Only a node called `end` is the problem; the lone `end` line that closes a subgraph is correct.
+- ❌ **Rendering with `--force` and shipping the result.** Mermaid draws an error graphic, not the diagram.
+- ❌ **Sending the HTML fallback as if it were an SVG.** It is a web page that needs network.
+- ❌ **Linting a copy and reporting line numbers from it.** Run the script on the user's own `.md` so the numbers match their editor.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.

skilldrop_cli/data/packs/converters/skills/mermaid-render/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "My mermaid diagram says syntax error, can you find what's wrong?",
+    "should_trigger": true
+  },
+  {
+    "query": "Export the diagrams in design.md as PNGs for my slides",
+    "should_trigger": true
+  },
+  {
+    "query": "Check every mermaid block in this doc renders before I open the PR",
+    "should_trigger": true
+  },
+  {
+    "query": "Convert arch.mmd to an SVG",
+    "should_trigger": true
+  },
+  {
+    "query": "Draw an architecture diagram of our three-tier AWS app",
+    "should_trigger": false
+  },
+  {
+    "query": "Turn design.md into an HTML page I can email",
+    "should_trigger": false
+  },
+  {
+    "query": "Make design.md a Word document with the diagrams in it",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/converters/skills/mermaid-render/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "mermaid-render",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "My diagram in docs/contoso-orders.md won't render on GitHub, it just says parse error. It's the second mermaid block. Can you fix it and export both diagrams as SVG for the design review deck?",
+      "assertions": [
+        "Runs render_mermaid.py on docs/contoso-orders.md (the user's file, not a copy) and reports errors with line numbers from that file",
+        "Each fix quotes labels or corrects syntax without removing or renaming nodes, edges or label text",
+        "Shows a before/after for every changed line",
+        "Asks the user, rather than guessing, when a fix depends on intent (a missing arrow, where a block ends)",
+        "Renders only after lint is clean, writing contoso-orders-1.svg and contoso-orders-2.svg, or, without mmdc, says it wrote an HTML page that needs network and gives the mermaid-cli install line",
+        "Does not invent nodes or connections that are not in the original diagram"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/converters/skills/mermaid-render/evals/files/1/docs/contoso-orders.md

@@ -0,0 +1,23 @@
+# Contoso orders
+
+## Order states
+
+```mermaid
+stateDiagram-v2
+    [*] --> Placed
+    Placed --> Paid
+    Paid --> Shipped
+    Shipped --> [*]
+```
+
+## Order flow
+
+```mermaid
+flowchart TD
+    A[Customer places order] --> B{In stock?}
+    B -->|Yes| C[Reserve stock (warehouse)]
+    B -->|No| D[Back-order]
+    C -> E[Take payment]
+    E --> F[Ship]
+    D --> F
+```

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/broken-diagrams.md

@@ -0,0 +1,147 @@
+# Example: linting broken diagrams, fixing one, and rendering
+
+Inputs are in [`inputs/`](inputs/). Every output block is what the script printed.
+
+## 1. A flowchart with seven mistakes
+
+[`inputs/broken-flowchart.mmd`](inputs/broken-flowchart.mmd):
+
+```text
+     1	flowchart LR
+     2	    start([Customer]) --> api[Orders API (v2)]
+     3	    api -> db[(Orders DB)]
+     4	    api --> queue{{Events}
+     5	    queue --> end
+     6	    worker[Worker] cache[(Cache)]
+     7	    subgraph Billing["Billing zone"]
+     8	        inv[Invoicer] -->|"monthly| api
+```
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/broken-flowchart.mmd
+broken-flowchart.mmd:2: error: label of `api` has unquoted `(` `)`; wrap the label in quotes: api["Orders API (v2)"]
+broken-flowchart.mmd:3: error: `->` is not a flowchart arrow; use `-->` (or `==>`)
+broken-flowchart.mmd:4: error: unbalanced brackets: `queue{{` is never closed with `}}`
+broken-flowchart.mmd:5: error: `end` is reserved in flowcharts and breaks the diagram; use `End`, `END` or `done` as the node id
+broken-flowchart.mmd:6: error: no arrow between `worker` and `cache`; join them with `-->`
+broken-flowchart.mmd:7: error: subgraph opened here has no matching `end`
+broken-flowchart.mmd:8: error: unbalanced double quote
+lint: 1 diagram(s), 7 error(s), 0 warning(s)
+```
+
+Mermaid 11.4.1 itself stops at the first one, reporting `Parse error on line 2` and a list of expected tokens, and says nothing about the other six.
+
+## 2. The fix
+
+Each change is the one the lint named; the nodes, edges and labels are the same.
+
+| Line | Before | After |
+|---|---|---|
+| 2 | `api[Orders API (v2)]` | `api["Orders API (v2)"]` |
+| 3 | `api -> db[(Orders DB)]` | `api --> db[(Orders DB)]` |
+| 4 | `queue{{Events}` | `queue{{Events}}` |
+| 5 | `queue --> end` | `queue --> done([Done])` *(asked the author: "end" meant the flow finishes)* |
+| 6 | `worker[Worker] cache[(Cache)]` | `worker[Worker] --> cache[(Cache)]` *(asked the author which way it points)* |
+| 8 | `-->\|"monthly\| api` | `-->\|"monthly"\| api` |
+| 9 | *(missing)* | `end` closing the Billing subgraph |
+
+[`inputs/fixed-flowchart.mmd`](inputs/fixed-flowchart.mmd):
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/fixed-flowchart.mmd
+fixed-flowchart.mmd: flowchart: ok
+lint: 1 diagram(s), 0 error(s), 0 warning(s)
+```
+
+## 3. Other diagram types
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/broken-sequence.mmd
+broken-sequence.mmd:5: error: `alt` block opened here has no matching `end`
+lint: 1 diagram(s), 1 error(s), 0 warning(s)
+```
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/typo.mmd
+typo.mmd:1: error: unknown diagram type `flowchar` on the first line. Did you mean `flowchart`?
+lint: 1 diagram(s), 1 error(s), 0 warning(s)
+```
+
+## 4. Every diagram in a Markdown doc
+
+[`inputs/design-notes.md`](inputs/design-notes.md) has three fences. Line numbers point into the `.md` file:
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/design-notes.md
+design-notes.md: diagram 1 (flowchart): ok
+design-notes.md: diagram 2 (sequenceDiagram): ok
+design-notes.md:31: error: `{` opened here is never closed
+lint: 3 diagram(s), 1 error(s), 0 warning(s)
+```
+
+## 5. The architecture-diagrams examples lint clean
+
+```text
+$ python3 scripts/render_mermaid.py ../../../solution-architect/skills/architecture-diagrams/examples/aws-three-tier.md
+aws-three-tier.md: flowchart: ok
+lint: 1 diagram(s), 0 error(s), 0 warning(s)
+```
+
+```text
+$ python3 scripts/render_mermaid.py ../../../solution-architect/skills/architecture-diagrams/examples/microservices-sequence.md
+microservices-sequence.md: sequenceDiagram: ok
+lint: 1 diagram(s), 0 error(s), 0 warning(s)
+```
+
+## 6. Rendering without mermaid-cli
+
+On a machine without `mmdc`, asking for an SVG writes an HTML page instead and says so:
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/checkout-flow.mmd -o checkout.svg
+checkout-flow.mmd: flowchart: ok
+lint: 1 diagram(s), 0 error(s), 0 warning(s)
+mmdc (mermaid-cli) is not on PATH, so no .svg was written. Wrote checkout.html instead: it draws the diagram(s) with Mermaid 11.4.1 from cdn.jsdelivr.net and needs network when opened. For .svg output: npm install -g @mermaid-js/mermaid-cli, then rerun.
+```
+
+Opened in headless Chrome with network, that page drew the flowchart as an SVG. With `mmdc`
+installed, the same command writes `checkout.svg`; for `design-notes.md` it would write
+`design-notes-1.svg`, `design-notes-2.svg` and `design-notes-3.svg` (after the state diagram's
+missing `}` is fixed).
+
+## Rendering with mermaid-cli installed
+
+With `mmdc` (mermaid-cli 12.0.0) on `PATH`, the same script writes real images. Run on
+2026-10-01:
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/checkout-flow.mmd -o checkout-flow.png
+checkout-flow.mmd: flowchart: ok
+lint: 1 diagram(s), 0 error(s), 0 warning(s)
+wrote checkout-flow.png
+```
+
+The PNG is 1268 × 1442 pixels: `-s 2` doubles the scale so it stays sharp in a document.
+
+A Markdown file with three diagrams, the third one broken, rendered with `--force`:
+
+```text
+$ python3 scripts/render_mermaid.py examples/inputs/design-notes.md -o notes.svg --force
+mmdc failed on design-notes.md, diagram 3 (line 29):
+Error: Parse error on line 6:
+...  [*] --> Cancelled
+----------------------^
+Expecting 'SPACE', 'NL', 'HIDE_EMPTY', 'scale', 'COMPOSIT_STATE', 'STRUCT_STOP', 'STATE_DESCR', 'ID', 'FORK', 'JOIN', 'CHOICE', 'CONCURRENT', 'note', 'acc_title', 'acc_descr', 'acc_descr_multiline_value', 'CLICK', 'classDef', 'style', 'class', 'direction_tb', 'direction_bt', 'direction_rl', 'direction_lr', 'EDGE_STATE', got '1'
+design-notes.md: diagram 1 (flowchart): ok
+design-notes.md: diagram 2 (sequenceDiagram): ok
+design-notes.md:31: error: `{` opened here is never closed
+lint: 3 diagram(s), 1 error(s), 0 warning(s)
+wrote notes-1.svg
+wrote notes-2.svg
+```
+
+`--force` still writes every diagram that renders (`notes-1.svg`, `notes-2.svg`), prints
+Mermaid's own parse error for the one that doesn't, and exits 1, so a CI step still fails.
+Here Mermaid stopped at line 6 of that diagram, a few lines after the lint's line 31 (the
+diagram starts at line 29 of the file). The lint found the cause first.
+

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/inputs/broken-flowchart.mmd

@@ -0,0 +1,8 @@
+flowchart LR
+    start([Customer]) --> api[Orders API (v2)]
+    api -> db[(Orders DB)]
+    api --> queue{{Events}
+    queue --> end
+    worker[Worker] cache[(Cache)]
+    subgraph Billing["Billing zone"]
+        inv[Invoicer] -->|"monthly| api

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/inputs/broken-sequence.mmd

@@ -0,0 +1,11 @@
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    C->>S: GET /report
+    alt cached
+        S-->>C: 200 from cache
+    else stale
+        S-->>C: 200 rebuilt
+    loop every 5 min
+        S->>S: refresh
+    end

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/inputs/checkout-flow.mmd

@@ -0,0 +1,9 @@
+flowchart TD
+    Cart([Shopper cart]) --> Pay{"Payment OK? (3-D Secure)"}
+    Pay -->|yes| Confirm[Order confirmed]
+    Pay -->|no| Retry[Ask for another card]
+    Retry -.-> Pay
+    Confirm --> Done([End])
+    subgraph Ops["Back office"]
+        Confirm --> Pick[Pick and pack] & Mail[Send receipt]
+    end

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/inputs/design-notes.md

@@ -0,0 +1,35 @@
+# Contoso order service: design notes
+
+The request path:
+
+```mermaid
+flowchart LR
+    Web([Web app]) -->|HTTPS| API[Order API]
+    API --> DB[(Orders DB)]
+    API -.publishes.-> Bus{{Event bus}}
+```
+
+What happens on checkout:
+
+```mermaid
+sequenceDiagram
+    participant W as Web
+    participant A as Order API
+    W->>A: POST /orders
+    alt stock reserved
+        A-->>W: 201 Created
+    else out of stock
+        A-->>W: 409 Conflict
+    end
+```
+
+The order lifecycle (has a mistake):
+
+```mermaid
+stateDiagram-v2
+    [*] --> Placed
+    state Fulfilment {
+        Placed --> Packed
+        Packed --> Shipped
+    [*] --> Cancelled
+```

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/inputs/fixed-flowchart.mmd

@@ -0,0 +1,9 @@
+flowchart LR
+    start([Customer]) --> api["Orders API (v2)"]
+    api --> db[(Orders DB)]
+    api --> queue{{Events}}
+    queue --> done([Done])
+    worker[Worker] --> cache[(Cache)]
+    subgraph Billing["Billing zone"]
+        inv[Invoicer] -->|"monthly"| api
+    end

skilldrop_cli/data/packs/converters/skills/mermaid-render/examples/inputs/typo.mmd

@@ -0,0 +1,2 @@
+flowchar TD
+    A --> B

skilldrop_cli/data/packs/converters/skills/mermaid-render/manifest.json

@@ -0,0 +1,40 @@
+{
+  "name": "mermaid-render",
+  "version": "0.1.2",
+  "description": "Check Mermaid diagrams for the mistakes that stop them rendering (unknown diagram type, unbalanced brackets or quotes, unquoted parentheses in labels, the word end as a node id, missing arrows, unclosed subgraphs or alt blocks) with line numbers and a fix for each, then render them to SVG, PNG or PDF with mermaid-cli, or to a standalone HTML page when it is not installed. Works on a .mmd file or every mermaid fence in a Markdown doc. Use when a diagram \"won't render\", the user says \"check my mermaid\", \"export this diagram as SVG/PNG\", or needs the diagrams in a doc as image files.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "architecture-diagrams",
+    "md-to-docx",
+    "md-to-html"
+  ],
+  "handoff": [
+    {
+      "to": "md-to-html",
+      "when": "the diagrams are rendered and the doc around them needs sharing",
+      "purpose": "Embed the SVGs in a self-contained HTML file that works offline.",
+      "fallback": "If md-to-html is absent, give the user the SVG paths and the Markdown image lines (![…](figures/x-1.svg)) to paste in place of each fence."
+    }
+  ],
+  "tags": [
+    "mermaid",
+    "diagram",
+    "lint",
+    "svg",
+    "png",
+    "render"
+  ],
+  "permissions": {"network": [], "commands": ["mmdc"], "files": "named-paths", "notes": "mmdc (mermaid-cli) renders SVG, PNG and PDF if it is installed. Without it the script writes an HTML page that loads Mermaid from cdn.jsdelivr.net when opened; the script itself makes no network calls."},
+  "model": {
+    "tier": "standard",
+    "rationale": "The script lints and renders deterministically, but fixing a broken diagram means reading the author's intent and rewriting syntax without changing nodes, edges or labels, and knowing when to ask instead."
+  }
+}

skilldrop_cli/data/packs/converters/skills/mermaid-render/reference.md

@@ -0,0 +1,70 @@
+# mermaid-render reference
+
+## Lint rules
+
+Each rule exists because Mermaid 11.4.1's parser rejects the pattern. The script reports
+`<file>:<line>: error: …`; warnings do not stop rendering.
+
+| Rule | Applies to | Fails in Mermaid | Passes |
+|---|---|---|---|
+| Unknown diagram type on the first line (after front matter and `%%` lines), with a closest-match suggestion | all | `flowchar TD` | `flowchart TD` |
+| Unknown flowchart direction | flowchart, graph | `flowchart LTR` | `flowchart LR`, `graph` (no direction) |
+| Unquoted `(` `)` `[` `]` `{` `}` or `"` inside a node label | flowchart | `api[Orders API (v2)]`, `a{Is it (x)?}`, `A[{agent}]`, `A([Foo (x)])` | `api["Orders API (v2)"]` |
+| Unquoted brackets inside a `\|pipe\|` arrow label | flowchart | `a -->\|HTTPS (443)\| b`, `a -->\|{x}\| b` | `a -->\|"HTTPS (443)"\| b`, `a -.reads (cached).-> b` |
+| A shape opened and never closed | flowchart | `q{{Events} --> b` | `q{{Events}} --> b` |
+| Unbalanced double quote | flowchart | `a -->\|"monthly\| b` | `a -->\|"monthly"\| b` |
+| `end` as a node id | flowchart | `q --> end` | `q --> End`, `A[end]` (as a label), `endpoint` |
+| Single-dash arrow `->` or `=>` | flowchart | `a -> b` | `a --> b`, `a ==> b` |
+| Two nodes with no arrow between them | flowchart | `worker[Worker] cache[(Cache)]` | `worker --> cache`, `LB --> Web1 & Web2` |
+| Arrow with no node on one side | flowchart | `A -->` | |
+| Subgraph title with unquoted brackets | flowchart | `subgraph Billing zone (EU)` | `subgraph "Billing (EU)"`, `subgraph B["Billing (EU)"]` |
+| `subgraph` with no `end`, or `end` with no subgraph | flowchart | | |
+| `loop` `alt` `opt` `par` `critical` `break` `rect` `box` with no `end`; `else`/`and`/`option` outside their block | sequenceDiagram | `alt` … (no `end`) | |
+| Message with no `: text` | sequenceDiagram | `A->>B` | `A->>B: call(x)` |
+| Unbalanced `{` `}` across lines (ER cardinality like `\|\|--o{` is ignored) | classDiagram, stateDiagram, erDiagram | `class Foo {` (no `}`) | |
+| Warning: `---oB` is read as a circle arrowhead to `B` | flowchart | | `A --- ops` (with a space) |
+
+Labels that are fine unquoted: `&`, `:`, `/`, `%`, `<`, `>`, emoji, and the shape pairs
+themselves (`[(cylinder)]`, `([stadium])`, `{{hexagon}}`, `>flag]`).
+
+## How the rules were checked
+
+Every rule above was run against Mermaid 11.4.1's own parser (`mermaid.parse`) in headless
+Chrome, together with every Mermaid block in this repo: the `architecture-diagrams` examples
+and templates, `docs/loops/*.mmd`, and the other skills' templates. The lint result (error or
+clean) matched Mermaid's on all 86 cases. Two existing templates fail in Mermaid as well as in
+lint, because their placeholders (`A[{agent}]`, `-->|{causal sentence}|`) are unquoted braces.
+That is expected for a template with blanks still in it.
+
+## What lint does not cover
+
+Lint checks syntax that stops rendering, not everything Mermaid validates. Not checked:
+
+- Diagram types other than flowchart, sequence, class, state and ER beyond the first line
+  (gantt dates, pie values, gitGraph commands, C4 macros, mindmap indentation).
+- Style statements (`classDef`, `style`, `linkStyle`): their CSS is not validated.
+- Layout problems: a diagram that renders but is unreadable (30+ nodes, crossing edges).
+
+When lint is clean but Mermaid still fails, run with `-o out.html --force` and open the page:
+Mermaid shows its own parse error in place of the diagram.
+
+## Rendering
+
+| Output | With `mmdc` on PATH | Without it |
+|---|---|---|
+| `.svg` | Vector file, transparent background | `.html` page instead, which says so |
+| `.png` | White background, 2× scale | `.html` page instead |
+| `.pdf` | One PDF per diagram | `.html` page instead |
+| `.html` | Always the HTML page: every diagram in order, captioned with its source line | same |
+
+The HTML page loads Mermaid 11.4.1 from `cdn.jsdelivr.net`, pinned so the drawing does not
+change under the reader, and carries a Content-Security-Policy that allows only that loader.
+It needs network when opened. Install mermaid-cli for offline files:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+Installing mermaid-cli also downloads a headless Chrome for Puppeteer, which `mmdc` drives. In a
+locked-down environment where that download is blocked, use the HTML page and print it to PDF
+from a browser.