docs: replace MkDocs with Zensical

.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/