chore: pin docs toolchain and modernize CI image

[ClaydeCode]

Why

MkDocs 2.0 is not an upgrade path for this site: it removes the plugin system, switches to TOML, and is incompatible with Material for MkDocs. Material itself has been in maintenance mode since 2025-11-06 (12 months of critical fixes). The likely successor is Zensical, by the same author.

I trial-built this repo with Zensical (uvx --with markdown-include zensical build): it reads our mkdocs.yml unchanged, respects site_dir: public, and builds in 1.7s. glightbox and markdown-include work. The blocker is the blog plugin (zensical/backlog#30, still open) — /blog/ renders with no post listing, and posts land at /blog/posts/<dir>/main/ instead of /blog/YYYY/MM/DD/slug/. So: stay put, but freeze the stack and clear the easy blockers.

Changes

• requirements.txt — pin all four deps to the versions currently in use (mkdocs==1.6.1, mkdocs-material==9.7.6, markdown-include==0.8.1, mkdocs-glightbox==0.5.2). Previously unbounded (mkdocs>=1.1.2, mkdocs-material>=9.2.0b0). MkDocs 2.0 could not have slipped in (Material 9.7.5+ pins mkdocs<2), but there is no reason to float versions on an unmaintained toolchain.
• .github/workflows/ci.yml — python:3.8-buster → python:3.12-slim. 3.8 went EOL in October 2024; Zensical requires >=3.10, so this also unblocks the eventual migration.
• docs/blog/posts/2023-09-16_app_integration_overhaul/main.md — broken anchor. The post linked developer_docs/overview.md#app-format; no such section exists. Retargeted to #the-apps-metadata. Found by the Zensical trial build, which reports missing anchors (MkDocs only logs these at INFO, so --strict never caught it).
• .gitignore — add .claude/worktrees.
• agents.md — deployment section said GitLab Pages; the site actually deploys to GitHub Pages via .github/workflows/ci.yml. Also records that the pins are deliberate, so future agents do not bump MkDocs.

Verification

• uv pip install -r requirements.txt && uv run mkdocs build --strict → exit 0.
• id="the-apps-metadata" present in public/developer_docs/overview/index.html, and the post's rendered link points at it.

Follow-up

Migrate to Zensical once zensical/backlog#30 closes. At that point: re-run the trial build, diff blog URLs against the current /blog/YYYY/MM/DD/slug/ scheme, add redirects if they differ, then swap requirements.txt and the CI build command. mkdocs.yml can stay as-is — Zensical reads it natively.

🤖 Generated with Claude Code