fix(docs): pin the toolchain in a requirements file so pip caching works

actions/setup-python's pip cache needs a requirements.txt or
pyproject.toml to hash, and failed the whole job without one. Putting
the pin in a file rather than inline also puts it somewhere a person
would look for it.

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

.github/workflows/docs.yml

@@ -31,12 +31,9 @@ jobs:
         with:
           python-version: '3.12'
           cache: pip
+          cache-dependency-path: docs/requirements.txt
 
-      # Pinned deliberately. The Material maintainers have announced that MkDocs
+      - run: pip install -r docs/requirements.txt
-      # 2.0 removes the plugin system and breaks every theme override with no
-      # migration path — an unpinned install would break this build on the day it
-      # lands, for a docs site nobody was editing.
-      - run: pip install 'mkdocs-material==9.7.7'
 
       - run: mkdocs build --strict
 

docs/requirements.txt

@@ -0,0 +1,5 @@
+# Pinned deliberately. The Material maintainers have announced that MkDocs 2.0
+# removes the plugin system and breaks every theme override with no migration
+# path, so an unpinned install would break this build on the day it lands — for a
+# docs site nobody was editing.
+mkdocs-material==9.7.7

mkdocs.yml

@@ -75,3 +75,8 @@ markdown_extensions:
 
 plugins:
   - search
+
+# The pinned toolchain lives in docs/ so the Pages workflow can cache on it; it is
+# not a page.
+exclude_docs: |
+  requirements.txt