README: usage + label-quoting rules

README.md

@@ -1,3 +1,113 @@
 # mermaid-compile
 
-Mermaid syntax validator — runs mmdc in a transient podman container, reports file:line for every parse failure.
+Syntax-check every ` ```mermaid ` block across markdown files. Runs
+[mmdc][1] (the official Mermaid CLI) inside a transient podman
+container — no local Node install, no global package pollution.
+
+[1]: https://github.com/mermaid-js/mermaid-cli
+
+## Prereqs
+
+- Python ≥ 3.9
+- Podman (rootless works fine)
+- Network reachable to Docker Hub for the first `docker.io/minlag/mermaid-cli` pull
+
+## Install
+
+```fish
+git clone https://git.timemachine.center/Timemachine/mermaid-compile.git
+cd mermaid-compile
+chmod +x check-mermaid.py
+```
+
+Optionally symlink onto `$PATH`:
+
+```fish
+ln -s "$PWD/check-mermaid.py" ~/.local/bin/check-mermaid
+```
+
+## Usage
+
+```fish
+# Walk current dir
+./check-mermaid.py
+
+# Specific path(s)
+./check-mermaid.py docs/ README.md
+
+# Skip the upfront podman pull (faster reruns)
+./check-mermaid.py --no-pull docs/
+
+# Override the image
+./check-mermaid.py --image my-mirror.example.com/mermaid-cli:1.2.3 docs/
+```
+
+Exit code:
+
+- `0` — every block parsed
+- `1` — at least one parse failure
+- `2` — environment problem (no podman, etc.)
+
+Suitable for `make check-docs`, pre-commit hooks, CI.
+
+## Output
+
+```
+  ✓ docs/architecture.md:4
+  ✓ docs/architecture.md:111
+  ✗ docs/auth-flow.md:6
+
+1 of 3 block(s) FAILED:
+
+=== docs/auth-flow.md:6 ===
+  Error: Parse error on line 3:
+  ...D    A --> B    A -> C    invalid edge
+  ---------------------^
+  Expecting 'SEMI', 'NEWLINE', 'EOF', 'AMP', ..., got 'MINUS'
+```
+
+The reported line is the line of the offending statement *within the
+Mermaid block* (1 = the first line after the opening ` ```mermaid `).
+The script prints the markdown file's line of the fence + 1 as the
+block start, so jumping with `Ctrl+G` in most editors lands you on the
+diagram body.
+
+## Why mmdc and not a pure parser?
+
+Mermaid's grammar is implemented in JavaScript (Jison). The simplest
+trustworthy way to validate is to invoke the same renderer the docs
+viewer will use. mmdc renders to SVG (which forces a full parse +
+layout); we ignore the SVG and only consume the exit code.
+
+`docker.io/minlag/mermaid-cli` packages Node + Puppeteer + Chromium
+already, so no host-side runtime needed. ~250 MB pull, one-time.
+
+## Common parse errors and fixes
+
+### flowchart node labels
+
+Wrap the label in `"..."` whenever the text contains any of `[`, `]`,
+`(`, `)`, `{`, `}`, `$`, `"`. The parser treats those as
+shape-delimiters mid-token.
+
+| Wrong | Right |
+|---|---|
+| `Box[/portal · waker (waking)/]` | `Box[/"portal · waker (waking)"/]` |
+| `Box[build []liteRoute]` | `Box["build []liteRoute"]` |
+| `Box[Templates ${VAR}]` | `Box["Templates ${VAR}"]` |
+| `Cond{state == "x"?}` | `Cond{"state == 'x' ?"}` |
+
+### sequence-diagram messages
+
+Cannot contain `;` — Mermaid reads `Foo->>Bar: a; b` as a partial
+statement and misidentifies the next line. Replace with `then` or
+`,`, or use the HTML entity `#59;`.
+
+| Wrong | Right |
+|---|---|
+| `A->>A: mu.Lock(); set flag` | `A->>A: mu.Lock then set flag` |
+| `A->>A: x=true; y=false` | `A->>A: x=true, y=false` |
+
+## License
+
+MIT. See LICENSE.