docs: replace MkDocs with Zensical

Migrate the v2 docs build from MkDocs Material to Zensical, the Material
team's successor (as Starlette and uvicorn have done). Zensical natively
re-implements search, glightbox and mkdocstrings, but — unlike MkDocs — runs
no arbitrary plugins or hooks. This SDK's docs relied on three of those, so
they are reimplemented as standalone build steps around `zensical build`:

- API reference: `mkdocs-gen-files` + `mkdocs-literate-nav` become
  `scripts/docs/gen_ref_pages.py` (writes the `docs/api/` mkdocstrings stubs)
  and `scripts/docs/build_config.py` (splices the nested API nav into a
  generated `mkdocs.gen.yml`, since Zensical has no literate-nav).
- llms.txt: the former MkDocs hook becomes `scripts/docs/llms_txt.py`, a
  post-build step over the source tree, with no dependency on build internals.

`mkdocs.yml` stays the source config, with the MkDocs-only YAML tags
(`!relative`, `!ENV`, `!!python/name:`) translated to the string forms
Zensical understands and the emoji functions pointed at
`zensical.extensions.emoji`. The generators moved out of `docs/` (Zensical
publishes everything under docs_dir) into `scripts/docs/`, and
`scripts/build-docs.sh` now picks the toolchain per worktree so the combined
v1 (MkDocs) + v2 (Zensical) build stays correct. Adds `scripts/serve-docs.sh`
for local preview.

The docs dependency group drops mkdocs, mkdocs-material[imaging] and the
gen-files/glightbox/literate-nav plugins for `zensical`. mkdocstrings is
floored at 1.0.4 / mkdocstrings-python 2.0.5: Zensical's compatibility layer
targets that API, and the older line renders API pages with an
unregistered-autorefs error.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CTkPwxyKkLTnqZdeiCMCzK

Author: claude

.github/workflows/deploy-docs.yml

@@ -14,6 +14,7 @@ on:
       - src/mcp/**
       - src/mcp-types/**
       - scripts/build-docs.sh
+      - scripts/docs/**
       - pyproject.toml
       - uv.lock
       - .github/workflows/deploy-docs.yml

.github/workflows/docs-preview.yml

@@ -1,13 +1,13 @@
 name: Docs Preview
 
-# Builds the mkdocs site for a PR and deploys it to Cloudflare Pages.
+# Builds the Zensical site for a PR and deploys it to Cloudflare Pages.
 #
-# Security: mkdocs executes Python from the PR (mkdocstrings imports src/mcp,
-# `!!python/name:` directives). The build is gated by `authorize` (admin sender
-# for auto-preview, admin/maintainer commenter for /preview-docs) and isolated
-# from Cloudflare secrets — `build` runs PR code with no secrets and hands the
-# static site to `deploy` via an artifact, so PR code never shares a runner
-# with the Cloudflare token.
+# Security: the build executes Python from the PR (mkdocstrings imports src/mcp,
+# the scripts/docs/ generators run). The build is gated by `authorize` (admin
+# sender for auto-preview, admin/maintainer commenter for /preview-docs) and
+# isolated from Cloudflare secrets — `build` runs PR code with no secrets and
+# hands the static site to `deploy` via an artifact, so PR code never shares a
+# runner with the Cloudflare token.
 #
 # Required configuration:
 #   - secrets.CLOUDFLARE_API_TOKEN   (scope: Account → Cloudflare Pages → Edit)
@@ -21,6 +21,7 @@ on:
       - docs/**
       - docs_src/**
       - mkdocs.yml
+      - scripts/docs/**
       - pyproject.toml
   issue_comment:
     types: [created]
@@ -129,7 +130,11 @@ jobs:
           version: 0.9.5
 
       - run: uv sync --frozen --group docs
-      - run: uv run --frozen --no-sync mkdocs build
+      # Zensical runs no MkDocs plugins/hooks: generate the API reference and the
+      # concrete config, build, then generate llms.txt (see scripts/docs/).
+      - run: uv run --frozen --no-sync python scripts/docs/build_config.py
+      - run: uv run --frozen --no-sync zensical build -f mkdocs.gen.yml --strict
+      - run: uv run --frozen --no-sync python scripts/docs/llms_txt.py --site-dir site
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

.github/workflows/shared.yml

@@ -103,11 +103,13 @@ jobs:
       - name: Check README snippets are up to date
         run: uv run --frozen scripts/update_readme_snippets.py --check
 
-  # `mkdocs.yml` sets `strict: true` and `pymdownx.snippets: check_paths: true`,
-  # but until this job existed the docs were only ever built post-merge by
-  # `deploy-docs.yml`, so a broken link, a missing nav target, or a deleted
-  # `docs_src/` include went green on the PR and broke the next deploy of main.
-  # This is the check path; `deploy-docs.yml` stays the deploy path.
+  # `zensical build --strict` fails on broken links / missing nav targets and
+  # `pymdownx.snippets: check_paths: true` fails on a deleted `docs_src/`
+  # include; the llms_txt step additionally re-resolves every snippet and link.
+  # Until this job existed the docs were only ever built post-merge by
+  # `deploy-docs.yml`, so those failures went green on the PR and broke the next
+  # deploy of main. This is the check path; `deploy-docs.yml` stays the deploy
+  # path.
   docs:
     runs-on: ubuntu-latest
     steps:
@@ -123,5 +125,10 @@ jobs:
       - name: Install dependencies
         run: uv sync --frozen --all-extras --python 3.10
 
+      # Zensical runs no MkDocs plugins/hooks: generate the API reference and
+      # the concrete config, build strictly, then generate llms.txt.
       - name: Build the docs in strict mode
-        run: uv run --frozen --no-sync mkdocs build --strict
+        run: |
+          uv run --frozen --no-sync python scripts/docs/build_config.py
+          uv run --frozen --no-sync zensical build -f mkdocs.gen.yml --strict
+          uv run --frozen --no-sync python scripts/docs/llms_txt.py --site-dir site

.gitignore

@@ -141,9 +141,13 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# documentation
 /site
 /.worktrees/
+# Generated at build time by docs/hooks/ (the API reference tree and the
+# concrete Zensical config spliced from mkdocs.yml).
+/docs/api/
+/mkdocs.gen.yml
 
 # mypy
 .mypy_cache/