chore(docs): install mkdocs deps with uv and enable mermaid2 plugin

Switch the docs toolchain from pip to uv, in CI (docs.yaml) and locally
via mise.toml (aligned with the worktree-docs-contributing-tools branch).
Declare the mermaid2 plugin (with search) in mkdocs.yml so the state
machine diagrams actually render.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: nlevee

.github/workflows/docs.yaml

@@ -25,6 +25,9 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: 3.x
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.11.19"
       - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
         with:
           key: mkdocs-material-${{ github.ref }}
@@ -33,7 +36,7 @@ jobs:
             mkdocs-material-
 
       - name: Install dependencies
-        run: pip install -r requirements.txt
+        run: uv pip install --system -r requirements.txt
 
       - name: Lint Markdown files
         uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23

mise.toml

@@ -0,0 +1,34 @@
+[tools]
+# Language runtimes — matched to the Dockerfile build images so dev == build
+go = "1.26.3"      # Dockerfile golang builder (>= go.mod 1.26.0)
+node = "24.16.0"   # Dockerfile node builder / ci-frontend NODE_VERSION
+yarn = "1.22.22"   # classic, matches ui/yarn.lock
+
+# Kubernetes & dev CLIs — pinned for a reproducible environment
+kubectl = "1.36.2"      # aligns with ENVTEST_K8S_VERSION (1.36.0)
+helm = "4.2.0"
+kind = "0.32.0"
+yq = "4.53.3"           # mikefarah
+golangci-lint = "2.12.2"
+
+# Docs toolchain
+uv = "0.11.19"
+
+# Not managed here (system-level): docker + buildx/compose, make, git.
+
+[env]
+# Automatic virtualenv activation for the docs toolchain
+_.python.venv = { path = ".venv", create = true }
+
+[tasks.install]
+description = "Install documentation dependencies"
+run = "uv pip install -r requirements.txt"
+
+[tasks.mkdocs-serve]
+depends = "install"
+description = "Serve MkDocs documentation locally"
+run = "uv run mkdocs serve"
+
+[tasks.lint]
+description = "Run golangci-lint (no make target exists for it)"
+run = "golangci-lint run ./..."

mkdocs.yml

@@ -9,6 +9,9 @@ theme:
 extra:
   version:
     provider: mike
+plugins:
+  - search
+  - mermaid2
 markdown_extensions:
   - codehilite
   - admonition