Review fixes: filename-agnostic gather, custom domains, smoother migration, Sphinx support

[coretl]

Fixes from a full repo review, ahead of adopting the workflows in Sphinx-based repos (python-copier-template) and newer mystmd projects.

Workflows

• Gather by artifact name, not workflow filename. publish.yml found branch/PR builds by querying runs of a hardcoded ci.yml; a consumer naming their entry workflow anything else got silent degradation (stale default branch, no PR previews). It now queries the artifacts API for non-expired artifacts named docs (the existing contract), filtered by workflow_run.head_branch/head_sha, with head_repository_id checked on the default-branch gather so a same-named fork branch can't shadow it. Note the success signal shifts from run conclusion to artifact existence — docs.yml only uploads after a successful build, so this is arguably the truer signal.
• Custom Pages domains work. The deploy job resolves PAGES_URL from the Pages API (github.io fallback) and threads it into both the _sources restore and assemble.mjs generate --base-url (replacing --repo), so switcher.json URLs are no longer hardcoded to *.github.io.
• Prerelease detection anchored to a digit (1.0a1/2.0rc1 yes; release-1.0/beta-program no) in assemble.mjs, release.yml, and migrate.sh's new create path — kept in parity, with tests for the negatives.
• docs.yml exports VERSION_NAME alongside BASE_URL, so a Sphinx conf.py can set pydata-sphinx-theme's switcher version_match without parsing it out of a path.

Migration (scripts/migrate.sh)

• Backfill creates a Release when a tag has a gh-pages dir but no Release (created-with-asset, so immutable-safe; prerelease-flagged). This makes the fork rehearsal faithful — forking copies tags but not Releases, so previously every released version dropped on the floor — and covers repos that tag without releasing.
• Will-DROP report: the script now prints exactly which live switcher.json versions the new model won't serve, instead of asking the operator to diff the backfill plan against the probe list by eye.
• --wait (with --delete-gh-pages) polls the guard until _sources/<default>.zip goes live (30 min cap), so finalize can run right after merging the pipeline PR.
• --seed-from <dir> for old sites that published the default branch's docs under another name (e.g. latest/).
• gh-pages is deleted via the API rather than git push --delete (no git credential-helper dependency in the temp clone); the clone is now blobless.

Docs

• New how-to: use with Sphinx — pydata-sphinx-theme reads the same pydata-format switcher.json, so Sphinx repos need no plugin; includes the conf.py/ci.yml wiring and a note that this will be rolled into a later python-copier-template release.
• Docs warnings are now errors: myst build --strict + error_rules (pattern from PandABlocks-server). Verified both ways — clean build passes, an injected broken anchor fails the build. Two pre-existing broken anchors in architecture.md fixed (would have been caught by this).
• Drift swept: package.json files/description, CLAUDE.md paths and PAGES_URL wording, stale fork-warn mentions in docs.yml/reference.

npm test (24 checks), biome, and the strict docs build are all green.

🤖 Generated with Claude Code