[v1.x] ci: pick the docs toolchain per worktree in build-docs.sh

[maxisbey]

Backports main's toolchain-detecting scripts/build-docs.sh (from #3073) verbatim.

Motivation and Context

The combined Pages deploy builds both branches — v1.x at the site root and main under /v2/ — from whichever branch triggered the push. Once #3073 lands, main's half builds with Zensical, and this branch's hardcoded mkdocs build would fail every v1.x-triggered deploy. With the detection, each worktree is built with the toolchain its own files declare; v1.x keeps building with MkDocs via the fallback arm (which also owns its dependency sync).

Safe to merge before or after #3073: when main has no scripts/docs/build.sh yet, the detection falls back to the current MkDocs path for both halves.

How Has This Been Tested?

Both arms of this exact file were exercised on real builds for #3073: the Zensical arm in that PR's CI docs job and validation runs, the MkDocs fallback arm as the v1.x half of the combined-build verification.

Breaking Changes

None.

Types of changes

• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}

[claude]

LGTM — self-contained docs-build script change; the fallback arm preserves current v1.x MkDocs behavior and the detection only activates once main ships scripts/docs/build.sh.

Extended reasoning...

Overview

This PR touches a single file, scripts/build-docs.sh — the CI script that assembles the combined v1 + v2 GitHub Pages site. It replaces the hardcoded mkdocs build per worktree with a build_site helper that picks the toolchain from the worktree's own files: if scripts/docs/build.sh exists (main's Zensical recipe from #3073), it runs that; otherwise it falls back to the existing MkDocs path. Both arms build into the worktree-local site/ and copy to the destination, since Zensical requires site_dir inside the project root.

Correctness

I verified the logic directly: build_site is invoked inside the subshell after cd "$worktree", so the file-presence check and build run against each worktree's own tree — v1.x has no scripts/docs/, so it takes the MkDocs fallback, matching the mkdocs>=1.6.1,<2 pin in this branch's pyproject.toml. The rm -rf "${OUTPUT_DIR:?}"/* guard is retained (just moved below the function definitions with identical semantics), mkdir -p "$dest" handles the /v2 subdirectory, and set -euo pipefail ensures any build failure aborts the deploy rather than publishing a partial site. NO_MKDOCS_2_WARNING=1 is a harmless env var for the mkdocs 1.x deprecation notice.

Security risks

None. This is a CI-only shell script with no runtime surface. It does execute scripts/docs/build.sh from the fetched branch's worktree, but CI already runs each branch's own build tooling by design, so this introduces no new trust boundary.

Level of scrutiny

Low-to-moderate: a build-infrastructure shell script whose worst failure mode is a loud, recoverable broken docs deploy — not production code, auth, or crypto. The change is small, well-commented, and explicitly order-independent with #3073 (the fallback keeps both halves on MkDocS until main ships the Zensical recipe).

Other factors

The bug hunting system found no issues, there are no prior reviewer comments on the timeline, and the PR description states both arms were exercised on real CI builds for #3073. The change is a verbatim sync of main's version of this script, keeping the two branches' copies consistent.