docs: deploy via GitHub Pages Actions; serve at docs.roboco.dev

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.

.github/workflows/docs.yml

@@ -1,6 +1,9 @@
-# Builds the MkDocs site and publishes it to the `gh-pages` orphan branch.
-# GitHub Pages then serves from that branch (set Settings → Pages → Source:
-# "Deploy from a branch" → gh-pages, and configure the custom domain there).
+# Builds the MkDocs site and deploys it with GitHub's official Pages Actions
+# flow (build once -> upload artifact -> deploy). This avoids the gh-pages
+# branch entirely, so there is no force-push race and the custom domain set in
+# Settings persists across deploys.
+#
+# One-time setup: Settings -> Pages -> Source = "GitHub Actions".
 name: docs
 
 on:
@@ -13,30 +16,38 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 
+# Allow one Pages deployment at a time; queue (don't cancel) overlapping runs.
 concurrency:
-  group: docs-deploy
+  group: pages
   cancel-in-progress: false
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
       - name: Install uv
         uses: astral-sh/setup-uv@v5
-
-      - name: Sync docs toolchain
-        run: uv sync --extra docs
-
-      - name: Configure git identity for gh-pages
+      - name: Build the site (strict)
         run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          uv sync --extra docs
+          uv run mkdocs build --strict
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
 
-      - name: Build and deploy to gh-pages
-        run: uv run mkdocs gh-deploy --force --strict
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CLAUDE.md

@@ -536,4 +536,4 @@ ROBOCO_OLLAMA_BASE_URL=http://roboco-ollama:11434          # Native API
 
 ## Blueprint Reference
 
-The organizational structure, communication matrix, role descriptions, and access-control model are documented inline above and in the user-facing documentation site (MkDocs Material; source under `docs/`, built by `mkdocs.yml`, published to `gh-pages` via `.github/workflows/docs.yml` and served at roboco.dev/docs). `docs/rag/` remains the agent-facing RAG corpus (excluded from the published site); the old root `usage.md` / `deployment.md` are now redirect stubs into the site.
+The organizational structure, communication matrix, role descriptions, and access-control model are documented inline above and in the user-facing documentation site (MkDocs Material; source under `docs/`, built by `mkdocs.yml`, deployed by `.github/workflows/docs.yml` via GitHub Pages Actions and served at docs.roboco.dev). `docs/rag/` remains the agent-facing RAG corpus (excluded from the published site); the old root `usage.md` / `deployment.md` are now redirect stubs into the site.

Makefile

@@ -493,7 +493,7 @@ help:
 	@echo "  make clean                    - Clean cache files"
 	@echo "  make prune                    - Prune docker resources"
 	@echo ""
-	@echo "Full docs: https://roboco.dev/docs  (preview locally: make serve-docs)"
+	@echo "Full docs: https://docs.roboco.dev  (preview locally: make serve-docs)"
 
 # Python versions list
 .PHONY: show-python-versions

README.md

@@ -31,7 +31,7 @@ AI Agents Company - A virtual organization of 25 AI agents + 1 human CEO, design
 > **RoboCo is early-stage, work-in-progress software (v0).** It's under active development, runs in a homelab, and *will* have rough edges, breaking changes, and bugs. It is **not production-ready** and the API/database schema are not stable yet. Treat it as a working prototype to explore and build on — please  don't expose it to the public internet as-is. Issues and PRs very welcome.
 
 > [!TIP]
-> 📚 **Full documentation:** **[roboco.dev/docs](https://roboco.dev/docs)** — install & first run, the company model, a page-by-page panel reference, model providers, the optional subsystems, deployment, and the API.
+> 📚 **Full documentation:** **[docs.roboco.dev](https://docs.roboco.dev)** — install & first run, the company model, a page-by-page panel reference, model providers, the optional subsystems, deployment, and the API.
 
 ## Overview
 

deployment.md

@@ -1,6 +1,6 @@
 # RoboCo Deployment Guide
 
-> **This guide has moved.** Deploying RoboCo is now documented in the full docs site at **[roboco.dev/docs](https://roboco.dev/docs)** (source under [`docs/`](docs/)).
+> **This guide has moved.** Deploying RoboCo is now documented in the full docs site at **[docs.roboco.dev](https://docs.roboco.dev)** (source under [`docs/`](docs/)).
 
 Jump straight to:
 

docs/CNAME

@@ -0,0 +1 @@
+docs.roboco.dev

mkdocs.yml

@@ -3,7 +3,7 @@
 # Preview: uv run mkdocs serve
 # Deploy:  handled in CI by .github/workflows/docs.yml (mkdocs gh-deploy → gh-pages).
 site_name: RoboCo
-site_url: https://roboco.dev/docs/
+site_url: https://docs.roboco.dev/
 site_description: >-
   RoboCo is a self-hosted AI agentic company — 25 AI agents and one human CEO
   that run as a complete software-development workforce, operated from a single

pyproject.toml

@@ -97,7 +97,7 @@ roboco-bootstrap = "roboco.bootstrap:cli"
 
 [project.urls]
 Homepage = "https://github.com/rennf93/roboco"
-Documentation = "https://roboco.dev/docs"
+Documentation = "https://docs.roboco.dev"
 Repository = "https://github.com/rennf93/roboco"
 
 [build-system]

usage.md

@@ -1,6 +1,6 @@
 # RoboCo Usage Guide
 
-> **This guide has moved.** Operating RoboCo is now documented in the full docs site at **[roboco.dev/docs](https://roboco.dev/docs)** (source under [`docs/`](docs/)).
+> **This guide has moved.** Operating RoboCo is now documented in the full docs site at **[docs.roboco.dev](https://docs.roboco.dev)** (source under [`docs/`](docs/)).
 
 Jump straight to: