Deploy documentation with GitHub Pages

[wmeddie]

Summary

• replace the SSH/rsync documentation deployment with GitHub Pages
• build and upload the existing MkDocs site/ output without changing documentation content or mkdocs.yml
• validate documentation builds on pull requests while deploying only pushes to main
• scope pages: write and id-token: write permissions to the deployment job
• use the checked-in uv.lock and skip installing/building the Xaibo package and UI, which the docs build does not require

Why

The previous workflow copied the generated site to a self-managed server over SSH. That server was compromised, so the documentation should no longer depend on a persistent host or SSH deployment credentials.

GitHub Pages can host the same static MkDocs output at the existing xaibo.ai apex domain.

Impact

Documentation sources and site configuration are unchanged. Once the one-time repository and DNS setup below is complete, merges affecting docs or their dependencies will publish automatically through GitHub Pages.

Validation

• actionlint .github/workflows/docs.yml
• clean Python 3.11 container:
  • uv sync --frozen --no-install-project
  • uv run --no-sync mkdocs build --strict
• build completed successfully with 212 generated files (14 MB)

The build retains one existing informational message: tutorial/advanced-orchestration.md links to an anchor that is not present in how-to/index.md. It does not fail strict mode and is unrelated to this deployment change.

One-time cutover after merge

1. In Settings → Pages, select GitHub Actions as the publishing source.
2. Verify xaibo.ai for the XpressAI organization, then set it as this repository's Pages custom domain.
3. Replace the current apex DNS record with GitHub Pages' four A records:
   • 185.199.108.153
   • 185.199.109.153
   • 185.199.110.153
   • 185.199.111.153
4. Point www via CNAME to xpressai.github.io.
5. Enable Enforce HTTPS once GitHub provisions the certificate.
6. Remove the obsolete SSH deployment secrets and revoke the old deployment key after cutover.