chore: migrate GitHub Pages deployment from gh-pages branch to GitHub Actions artifact

[planetf1]

Background

Currently the docs CI builds the site then force-pushes to a gh-pages branch, which GitHub Pages serves. The modern approach uses actions/upload-pages-artifact + actions/deploy-pages, deploying directly from the workflow without a branch.

Benefits

• Atomic deployments — branch push has a window where Pages serves partially-updated content; Actions deployment is a single swap
• Deployment environments — shows up in the repo's Environments tab with timestamps, triggering run link, and rollback visibility
• No orphan branch — gh-pages accumulates history forever and requires periodic pruning
• Cleaner concurrency — GitHub's Pages infrastructure handles races at the infrastructure level

Work required

1. Update .github/workflows/docs-publish.yml to use actions/upload-pages-artifact + actions/deploy-pages
2. Add the pages: write and id-token: write permissions to the deploy job
3. Requires repo admin action: change the Pages source in Settings → Pages from "Deploy from a branch" to "GitHub Actions" — this must be coordinated with the workflow change to avoid a gap in availability

References

• GitHub Pages — publishing with a custom workflow
  🤖 Generated with Claude Code