feat(devshell): add markdownlint-cli2, lychee, vale, cspell; gate Chromium to Linux; add Justfile tasks

- Add `markdownlint-cli2` for fast, configurable Markdown linting.
- Add `lychee` for robust external link checking in Markdown.
- Add `vale` for prose/style linting; `cspell` for spelling.
- Limit `chromium` to Linux in devShell; keep Puppeteer env to use system Chrome/Chromium when present, avoiding issues on aarch64-darwin.
- Add `md-lint`, `md-links`, and `md-spell` Justfile tasks alongside existing Mermaid validator.
- Keeps existing Mermaid validation script; integrates better ergonomics for vault-wide checks.

Author: zah

Justfile

@@ -44,3 +44,19 @@ conf-schema-taplo-check:
 # Serve schema docs locally with Docson (opens http://localhost:3000)
 conf-schema-docs:
     docson -d specs/schemas
+
+# Validate Mermaid diagrams in Markdown with mermaid-cli (mmdc)
+md-mermaid-check:
+    bash scripts/md-mermaid-validate.sh specs/**/*.md
+
+# Lint Markdown structure/style in specs with markdownlint-cli2
+md-lint:
+    markdownlint-cli2 "specs/**/*.md"
+
+# Check external links in Markdown with lychee
+md-links:
+    lychee --offline false --no-progress --require-https true --max-concurrency 8 "specs/**/*.md"
+
+# Spell-check Markdown with cspell (uses default dictionaries unless configured)
+md-spell:
+    cspell "specs/**/*.md"

flake.nix

@@ -71,6 +71,15 @@
           pkgs.fossil
           pkgs.mercurial
           pkgs.nodejs # for npx-based docson helper
+          # Mermaid validation (diagram syntax)
+          (pkgs.nodePackages."@mermaid-js/mermaid-cli")
+          pkgs.noto-fonts
+
+          # Markdown linting & link/prose checking
+          (pkgs.nodePackages.markdownlint-cli2)
+          pkgs.lychee
+          pkgs.vale
+          (pkgs.nodePackages.cspell)
 
           # AI Coding Assistants (latest versions from nixpkgs-unstable)
           pkgs.goose-cli # Goose AI coding assistant
@@ -86,6 +95,8 @@
            then pkgs.nodePackages."ajv-cli" else null)
         ])
         ++ pkgs.lib.optionals isLinux [
+          # Use Chromium on Linux for mermaid-cli's Puppeteer
+          pkgs.chromium
           # Linux-only filesystem utilities for snapshot functionality
           pkgs.zfs # ZFS utilities for copy-on-write snapshots
           pkgs.btrfs-progs # Btrfs utilities for subvolume snapshots
@@ -99,6 +110,15 @@
           # Provide a convenience function to launch Docson without global install
           docson () { npx -y docson "$@"; }
           echo "Tip: run: docson -d ./specs/schemas  # then open http://localhost:3000"
+          # Ensure mermaid-cli (mmdc) uses system Chrome/Chromium when present
+          if command -v chromium >/dev/null 2>&1; then
+            export PUPPETEER_EXECUTABLE_PATH="$(command -v chromium)"
+          elif command -v google-chrome >/dev/null 2>&1; then
+            export PUPPETEER_EXECUTABLE_PATH="$(command -v google-chrome)"
+          elif command -v google-chrome-stable >/dev/null 2>&1; then
+            export PUPPETEER_EXECUTABLE_PATH="$(command -v google-chrome-stable)"
+          fi
+          export PUPPETEER_PRODUCT=chrome
         '';
       };
     });

scripts/md-mermaid-validate.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve Mermaid CLI (mmdc)
+if command -v mmdc >/dev/null 2>&1; then
+  MMDC_CMD="mmdc"
+else
+  # Fallback to npx if available (requires network on first run)
+  if command -v npx >/dev/null 2>&1; then
+    MMDC_CMD="npx -y @mermaid-js/mermaid-cli"
+    # Prefer system Chrome/Chromium if present to avoid downloads
+    for bin in chromium chromium-browser google-chrome google-chrome-stable; do
+      if command -v "$bin" >/dev/null 2>&1; then
+        export PUPPETEER_EXECUTABLE_PATH="$(command -v "$bin")"
+        export PUPPETEER_PRODUCT=chrome
+        export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1
+        break
+      fi
+    done
+    if [[ -z "${PUPPETEER_EXECUTABLE_PATH:-}" ]]; then
+      echo "No system Chrome/Chromium found. Without nix develop this fallback requires network to download a headless browser via npx. If that's not possible here, either install Chrome and re-run, or enter 'nix develop'." >&2
+      exit 127
+    fi
+  else
+    echo "mmdc (mermaid-cli) not found and no npx fallback. Install via Nix dev shell or Node." >&2
+    exit 127
+  fi
+fi
+
+TMPDIR_ROOT="${TMPDIR:-/tmp}"
+FAILED=0
+
+validate_file() {
+  local file="$1"
+  local tmpdir
+  tmpdir="$(mktemp -d "$TMPDIR_ROOT/mmdc.$$.$(basename "$file").XXXX")"
+  trap 'rm -rf "'$tmpdir'"' RETURN
+
+  local in_block=0
+  local block_no=0
+  local line_no=0
+  while IFS= read -r line; do
+    line_no=$((line_no+1))
+    if [[ $in_block -eq 0 && $line =~ ^```mermaid[[:space:]]*$ ]]; then
+      in_block=1
+      block_no=$((block_no+1))
+      : >"$tmpdir/block_${block_no}.mmd"
+      continue
+    fi
+    if [[ $in_block -eq 1 && $line =~ ^```[[:space:]]*$ ]]; then
+      in_block=0
+      # validate the block by attempting render
+      local in_file="$tmpdir/block_${block_no}.mmd"
+      local out_file="$tmpdir/block_${block_no}.svg"
+      if ! $MMDC_CMD -i "$in_file" -o "$out_file" --quiet >/dev/null 2>&1; then
+        echo "Mermaid error: $file: block $block_no (see $in_file)" >&2
+        FAILED=1
+      fi
+      continue
+    fi
+    if [[ $in_block -eq 1 ]]; then
+      printf '%s\n' "$line" >>"$tmpdir/block_${block_no}.mmd"
+    fi
+  done <"$file"
+}
+
+if [[ $# -eq 0 ]]; then
+  set -- specs/Public/*.md specs/Public/**/*.md 2>/dev/null || true
+fi
+
+shopt -s nullglob
+for f in "$@"; do
+  validate_file "$f"
+done
+
+exit $FAILED