From 176eea76dc387eed76035d35d781437e6bec1077 Mon Sep 17 00:00:00 2001
From: Sisyphus <clio-agent@sisyphuslabs.ai>
Date: Thu, 23 Jul 2026 21:13:18 +0900
Subject: [PATCH] ci(docs): add mermaid render lint to catch diagram syntax
 regressions

Add a PR-triggered workflow that renders every ```mermaid block in
README*.md and docs/ with mermaid-cli (mmdc), failing fast when a
diagram has invalid syntax. Runs only on PRs that touch README*/docs,
keeping the chromium-based dependency isolated from the main test CI.

Closes #214
---
 .github/workflows/mermaid-lint.yml | 63 ++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 .github/workflows/mermaid-lint.yml

diff --git a/.github/workflows/mermaid-lint.yml b/.github/workflows/mermaid-lint.yml
new file mode 100644
index 0000000..d026cb3
--- /dev/null
+++ b/.github/workflows/mermaid-lint.yml
@@ -0,0 +1,63 @@
+name: Mermaid Render Lint
+
+# Renders every Mermaid diagram in the docs/README so that invalid syntax
+# fails fast in CI. See issue #214 (follow-up from the diagram PR #209).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "README*.md"
+      - "docs/**"
+      - ".github/workflows/mermaid-lint.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  mermaid-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "20"
+
+      - name: Install mermaid-cli
+        run: npm install -g @mermaid-js/mermaid-cli@11
+
+      - name: Configure Puppeteer (headless Chromium, no sandbox)
+        run: |
+          echo '{ "args": ["--no-sandbox"] }' > "$RUNNER_TEMP/puppeteer-config.json"
+
+      - name: Render all Mermaid diagrams (fails on invalid syntax)
+        run: |
+          set -euo pipefail
+          # Collect markdown files that contain a ```mermaid fenced block.
+          mapfile -t files < <(grep -rlZ '```mermaid' README*.md docs 2>/dev/null | tr '\0' '\n' | sort -u)
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No Mermaid diagrams found — nothing to lint."
+            exit 0
+          fi
+          status=0
+          for f in "${files[@]}"; do
+            echo "::group::Rendering $f"
+            # mmdc processes every ```mermaid block in the markdown file and
+            # exits non-zero if any diagram has invalid syntax. Output is
+            # discarded (we only care about the render succeeding).
+            if mmdc \
+              --puppeteerConfigFile "$RUNNER_TEMP/puppeteer-config.json" \
+              --input "$f" \
+              --output "$RUNNER_TEMP/$(basename "$f" .md)-rendered.md"; then
+              echo "OK: $f"
+            else
+              echo "::error file=$f::Mermaid render failed — check diagram syntax."
+              status=1
+            fi
+            echo "::endgroup::"
+          done
+          exit "$status"