Documentation Site, AGENTS.md improvements and CI

.github/workflows/ci.yaml

@@ -2,6 +2,7 @@ name: CI
 
 on:
   push:
+    branches: [main, dev]
   pull_request:
 
 # Builds and tests only — no deploy (ADR 0003: local single-user scope).
@@ -13,7 +14,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.12"
           enable-cache: true
@@ -32,3 +33,23 @@ jobs:
 
       - name: Pytest
         run: uv run pytest
+
+  docs:
+    name: Docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync workspace
+        run: uv sync
+
+      # Build-only (no deploy) so every push/PR is checked the same way as lint/mypy/pytest.
+      # -W turns Sphinx warnings into errors. Deployment to Pages stays in docs-deploy.yaml.
+      - name: Build docs
+        run: uv run sphinx-build -b html docs site -W

.github/workflows/docs-deploy.yaml

@@ -0,0 +1,54 @@
+name: Deploy docs
+
+# Build the Sphinx site and publish it to GitHub Pages on push to main or dev. Kept as its own
+# workflow (not a job in ci.yaml) so CI stays build-and-test only, with no deploy.
+on:
+  push:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Never cancel an in-flight Pages deploy; let queued runs finish in order.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build and upload the Pages artifact in its own job so it is produced exactly once. If the deploy
+  # job below fails transiently and is re-run, it does not re-upload — which would otherwise leave two
+  # "github-pages" artifacts in the run and make actions/deploy-pages error.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync workspace
+        run: uv sync
+
+      - name: Build site
+        run: uv run sphinx-build -b html docs site -W
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  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@v5