feat(ci): add Markdown and Mermaid linting

Introduce `markdown:lint` which chains structural markdown checks
(markdownlint-cli2) and Mermaid diagram validation. Both run as part of
`mise run lint` and as a dedicated GitHub Actions job.

Mermaid diagrams are validated by calling `mermaid.parse()` via a small
Node script with a jsdom shim — no Chromium/Puppeteer required. This
catches real parse errors (e.g. the `exec()s` sequence-diagram bug in
`architecture/sandbox-connect.md`) that browser-free alternatives like
`maid` silently miss.

Tooling:
- `.markdownlint-cli2.jsonc` with `gitignore: true`, sensible rule
  overrides (MD033 allowlist for GitHub-rendered HTML, MD060 padded
  table style, MD013/MD034 off to match project style).
- `docs/.markdownlint-cli2.jsonc` overrides for MDX (no top-level H1,
  JSX components may look like HTML).
- `scripts/lint-mermaid/` hosts the validator with a committed
  `package-lock.json` for reproducible CI installs (`npm ci`).
- `markdownlint-cli2` pinned via mise `npm:` backend.

Existing doc fixes applied to satisfy the new checks: adds `text`
language to bare code fences (via one-shot codemod), corrects list
indentation at the single-digit → double-digit boundary in
`architecture/sandbox.md`, plus minor blank-line and trailing-newline
fixes.

Author: pimlock

.github/workflows/branch-checks.yml

@@ -100,3 +100,20 @@ jobs:
 
       - name: Test
         run: mise run test:python
+
+  markdown:
+    name: Markdown
+    runs-on: build-amd64
+    container:
+      image: ghcr.io/nvidia/openshell/ci:latest
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install tools
+        run: mise install
+
+      - name: Lint
+        run: mise run markdown:lint

.gitignore

@@ -202,3 +202,6 @@ architecture/plans
 rfc.md
 .worktrees
 .z3-trace
+
+# Markdown/mermaid lint tooling deps
+scripts/lint-mermaid/node_modules/

.markdownlint-cli2.jsonc

@@ -0,0 +1,31 @@
+{
+  "globs": [
+    "**/*.md",
+    "**/*.mdx"
+  ],
+  "gitignore": true,
+  "ignores": [
+    ".agents/**",
+    ".claude/**",
+    ".opencode/**",
+    ".github/**",
+    "THIRD-PARTY-NOTICES/**",
+    "CLAUDE.md"
+  ],
+  "config": {
+    "default": true,
+    // Allow long lines — prose paragraphs are single-line per project style.
+    "MD013": false,
+    // Allow GitHub-rendered HTML commonly used in READMEs (centered logos,
+    // collapsible sections, keyboard hints). Regular prose HTML still flagged.
+    "MD033": { "allowed_elements": ["p", "img", "br", "a", "div", "details", "summary", "kbd", "sub", "sup"] },
+    // Allow duplicate headings in different sections.
+    "MD024": { "siblings_only": true },
+    // Bare URLs are fine in changelogs and tables.
+    "MD034": false,
+    // First line does not need to be a heading.
+    "MD002": false,
+    // Repo uses padded table pipes (`| foo | bar |`); rule default is "compact".
+    "MD060": { "style": "padded" }
+  }
+}

CLAUDE.md

@@ -1 +1 @@
-@AGENTS.md
+@AGENTS.md

CONTRIBUTING.md

@@ -258,7 +258,7 @@ See [docs/CONTRIBUTING.mdx](docs/CONTRIBUTING.mdx) for the current docs authorin
 
 This project uses [Conventional Commits](https://www.conventionalcommits.org/). All commit messages must follow the format:
 
-```
+```text
 <type>(<scope>): <description>
 
 [optional body]
@@ -279,7 +279,7 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/).
 
 **Examples:**
 
-```
+```text
 feat(cli): add --verbose flag to openshell run
 fix(sandbox): handle timeout errors gracefully
 docs: update installation instructions

SECURITY.md

@@ -1,4 +1,4 @@
-## Security
+# Security
 
 NVIDIA is dedicated to the security and trust of our software products and services, including all source code repositories managed through our organization.
 

TESTING.md

@@ -10,7 +10,7 @@ mise run ci            # Everything: lint, compile checks, and tests
 
 ## Test Layout
 
-```
+```text
 crates/*/src/          # Inline #[cfg(test)] modules
 crates/*/tests/        # Rust integration tests
 python/openshell/      # Python unit tests (*_test.py suffix)

architecture/README.md

@@ -142,6 +142,7 @@ The connection flow works as follows:
 5. The CLI and sandbox exchange SSH traffic bidirectionally through the tunnel.
 
 This design provides several benefits:
+
 - Sandbox pods are never directly accessible from outside the cluster.
 - All access is authenticated and auditable through the gateway.
 - Session tokens can be revoked to immediately cut off access.
@@ -198,7 +199,6 @@ The inference routing system transparently intercepts AI inference API calls fro
 | Gateway inference service | `crates/openshell-server/src/inference.rs` | Stores cluster inference config, resolves bundles with credentials from provider records |
 | Proto definitions | `proto/inference.proto` | `ClusterInferenceConfig`, `ResolvedRoute`, bundle RPCs |
 
-
 ### Container and Build System
 
 The platform produces three container images:

architecture/custom-vm-runtime.md

@@ -61,7 +61,7 @@ never binds a host-side TCP listener.
 `openshell-driver-vm` embeds the VM runtime libraries and the sandbox rootfs as
 zstd-compressed byte arrays, extracting on demand:
 
-```
+```text
 ~/.local/share/openshell/vm-runtime/<version>/        # libkrun / libkrunfw / gvproxy
 ├── libkrun.{dylib,so}
 ├── libkrunfw.{5.dylib,so.5}

architecture/gateway-deploy-connect.md

@@ -99,7 +99,7 @@ This stores `auth_mode = "plaintext"`, skips mTLS certificate extraction, and by
 
 All connection artifacts are stored under `$XDG_CONFIG_HOME/openshell/` (default `~/.config/openshell/`):
 
-```
+```text
 openshell/
   active_gateway                          # plain text: active gateway name
   gateways/