The gh-pages branch deploy (mkdocs gh-deploy --force) raced GitHub's built-in branch deployment and got canceled, and each force-push wiped the custom-domain CNAME. Switch to GitHub's official Pages Actions flow (build -> upload-pages-artifact -> deploy-pages) with a single 'pages' concurrency group, so there is one deterministic deployment and no branch to force-push.
- Set the custom domain to docs.roboco.dev (site_url + a docs/CNAME that ships in the build artifact, so the domain persists across deploys).
- Point the advertised docs URL at https://docs.roboco.dev across README, the usage/deployment stubs, the Makefile help, pyproject, and CLAUDE.md.
- Requires a one-time Settings -> Pages -> Source = "GitHub Actions"; the gh-pages branch is no longer used.
Build a complete user-facing documentation site (MkDocs Material) under docs/, served at roboco.dev/docs via a new gh-pages deploy workflow.
- Sections: Get Started, The Company, the Tour, Operating the Panel, Choosing & Running Models, Cost & Observability, Optional Subsystems, Configure & Deploy, API Reference, Troubleshooting & Security (55 pages).
- mkdocs.yml (Material theme; excludes the agent-facing rag/ corpus, internal scratch, and orphaned stub trees) and .github/workflows/docs.yml (mkdocs gh-deploy to gh-pages).
- Retire the stale root usage.md and deployment.md to redirect stubs into the site.
- Fix the docs tooling: add the pymarkdownlnt dependency + .pymarkdown.json, run serve-docs/lint-docs/fix-docs under the docs extra, add a build-docs strict gate.
- Fix the roboco console-script entry point (cli, not the un-awaited async main).
- README: correct the project-structure tree (optimal.py, alembic) and link the docs site.
Renn F