ci: build and deploy docs site to Cloudflare Pages

Builds on PRs touching docs/**; deploys dist/ to the claudius-docs Pages
project on pushes to main. Needs CLOUDFLARE_API_TOKEN and
CLOUDFLARE_ACCOUNT_ID repo secrets plus a one-time pages project create
(documented in docs/README.md). Also keeps docs/package.json version in
sync via release-please.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Paul Mulligan

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build (includes Pagefind index)
+        run: pnpm build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-dist
+          path: docs/dist
+
+  deploy:
+    name: Deploy to Cloudflare Pages
+    # Deploys need the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID repo
+    # secrets, and a one-time `wrangler pages project create claudius-docs`.
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-dist
+          path: docs/dist
+
+      - name: Deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: docs
+          command: pages deploy dist --project-name=claudius-docs

docs/README.md

@@ -0,0 +1,51 @@
+# Claudius documentation site
+
+Astro Starlight site published at
+[claudius-docs.pages.dev](https://claudius-docs.pages.dev). Content lives in
+`src/content/docs/`; `plans/` holds internal design/implementation notes and
+is not part of the site.
+
+## Develop
+
+```bash
+pnpm install
+pnpm dev        # http://localhost:4321
+pnpm build      # static build into dist/ (includes the Pagefind search index)
+```
+
+## Deployment
+
+`.github/workflows/docs.yml` builds on every PR touching `docs/**` and
+deploys `dist/` to the Cloudflare Pages project `claudius-docs` on pushes to
+`main`.
+
+One-time setup (already done if the site is live):
+
+1. Create the Pages project:
+   ```bash
+   cd docs && pnpm build
+   npx wrangler login
+   npx wrangler pages project create claudius-docs --production-branch main
+   npx wrangler pages deploy dist --project-name=claudius-docs
+   ```
+2. Add the `CLOUDFLARE_API_TOKEN` (Pages:Edit permission) and
+   `CLOUDFLARE_ACCOUNT_ID` secrets to the GitHub repo so CI can deploy.
+3. Optional custom domain (e.g. `docs.claudius.dev`): Cloudflare dashboard →
+   Pages → claudius-docs → Custom domains. Then update `site` in
+   `astro.config.mjs` and the docs links in the root README.
+4. Add the docs origin to the production worker's `ALLOWED_ORIGIN`
+   (comma-separated) so the live demo widget on the home page can chat:
+   `ALLOWED_ORIGIN = https://pmds.info,https://claudius-docs.pages.dev`
+
+## Versioned docs
+
+[starlight-versions](https://github.com/HiDeoo/starlight-versions) archives a
+copy of the docs per major release line (currently `1.x`, browsable via the
+version switcher in the header). When a new major ships, add an entry to
+`versions` in `astro.config.mjs`; the next build snapshots the then-current
+docs under that slug.
+
+Two authoring constraints the archiver imposes (it converts pages to MDX):
+
+- No autolinks (`<https://example.com>`) — use `[text](url)` links
+- Raw `<`/`>` outside code spans must be valid JSX

release-please-config.json

@@ -20,7 +20,8 @@
       "changelog-path": "CHANGELOG.md",
       "extra-files": [
         { "type": "json", "path": "widget/package.json", "jsonpath": "$.version" },
-        { "type": "json", "path": "worker/package.json", "jsonpath": "$.version" }
+        { "type": "json", "path": "worker/package.json", "jsonpath": "$.version" },
+        { "type": "json", "path": "docs/package.json", "jsonpath": "$.version" }
       ]
     }
   }