docs: migrate to Starlight + merge authoring into sourcebans-pp (#1333)

.github/dependabot.yml

@@ -17,3 +17,17 @@ updates:
       prefix: "Composer"
       include: "scope"
     rebase-strategy: "auto"
+
+  # Astro + Starlight + Pagefind + mermaid for the docs/ site (#1333).
+  # Same monthly cadence to stay in lock-step with composer's noise floor.
+  - package-ecosystem: "npm"
+    directory: "/docs"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "docs"
+    commit-message:
+      prefix: "docs(deps)"
+      include: "scope"
+    rebase-strategy: "auto"

.github/workflows/docs-build.yml

@@ -0,0 +1,62 @@
+# docs-build — validate the Astro + Starlight build on PRs that touch docs/.
+#
+# Cadence: per-PR + per-merge-to-main, gated on `docs/**` paths so it
+# stays out of the way of PRs that don't touch the docs site.
+#
+# Why it exists: catches `npm run build` failures (broken Markdown,
+# missing assets, busted Starlight config) BEFORE the deploy trigger
+# fires on main. Pair gate with docs-deploy-trigger.yml.
+
+name: docs-build
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-build.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-build.yml'
+
+jobs:
+  build:
+    name: Build Astro + Starlight
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      # docs/package-lock.json is committed; npm ci is the deterministic
+      # path and will fail loudly if anyone lands a package.json bump
+      # without regenerating the lockfile (which is exactly the gate
+      # we want).
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund
+
+      - name: Build site
+        run: npm run build
+
+      # Surface the built site as an artifact so reviewers can poke at
+      # the chrome locally without rebuilding. Retention is short
+      # because docs-deploy-trigger.yml is the production path.
+      - name: Upload build artifact
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-dist
+          path: docs/dist/
+          retention-days: 7
+          if-no-files-found: error

.github/workflows/docs-deploy-trigger.yml

@@ -0,0 +1,69 @@
+# docs-deploy-trigger — fire a repository_dispatch into sbpp.github.io
+# whenever main moves under docs/, kicking the Pages deploy in the
+# sibling repo.
+#
+# Cadence: only on push to main with a docs/** path filter. PRs use
+# docs-build.yml to validate; this workflow is the production trigger.
+#
+# Required repo configuration BEFORE this workflow can succeed (one-time
+# cutover steps documented in #1333 cutover steps 1-2):
+#
+#   - Create the `sbpp-docs-deploy` GitHub App (org-owned), scope
+#     `Actions: write` on `sbpp.github.io` only, install on
+#     `sbpp/sbpp.github.io`.
+#   - Repo VARIABLE  `DOCS_DEPLOY_APP_ID`   = the App's numeric ID.
+#   - Repo SECRET    `DOCS_DEPLOY_APP_KEY`  = the App's PEM private key.
+#
+# Until those land, this workflow will fail on the first run with an
+# auth error. That's expected; the deploy shell in sbpp.github.io
+# also has a workflow_dispatch trigger as a manual fallback.
+
+name: docs-deploy-trigger
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-deploy-trigger.yml'
+
+# Allow at most one in-flight trigger at a time; if a second push lands
+# while the first is still running, queue the second and skip any
+# intermediate runs. The dispatched workflow in sbpp.github.io is
+# itself idempotent (it always builds from sourcebans-pp@main), so
+# coalescing here is safe.
+concurrency:
+  group: docs-deploy-trigger
+  cancel-in-progress: false
+
+jobs:
+  trigger:
+    name: Dispatch docs-changed event
+    runs-on: ubuntu-24.04
+    permissions: {}
+
+    steps:
+      - name: Mint installation token via GitHub App
+        id: mint-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.DOCS_DEPLOY_APP_ID }}
+          private-key: ${{ secrets.DOCS_DEPLOY_APP_KEY }}
+          owner: sbpp
+          repositories: sbpp.github.io
+
+      # The dispatched workflow in sbpp.github.io listens for
+      # `event_type: docs-changed`. The client_payload carries the
+      # commit SHA and ref so the deploy job can stamp it into the
+      # site footer / build manifest if it wants.
+      - name: Dispatch repository_dispatch into sbpp.github.io
+        env:
+          GH_TOKEN: ${{ steps.mint-token.outputs.token }}
+        run: |
+          gh api repos/sbpp/sbpp.github.io/dispatches \
+            --method POST \
+            --field event_type=docs-changed \
+            --field 'client_payload[source_repo]=${{ github.repository }}' \
+            --field 'client_payload[source_sha]=${{ github.sha }}' \
+            --field 'client_payload[source_ref]=${{ github.ref }}'

.github/workflows/docs-screenshots-build.yml

@@ -0,0 +1,58 @@
+# docs-screenshots-build — sandboxed verification job for the screenshot
+# capture script.
+#
+# Cadence: every PR that touches the capture script, its package.json
+# manifest, or this workflow.
+#
+# Why split: the matching capture workflow (docs-screenshots-capture.yml)
+# runs `pull_request_target` with `contents: write` so it can boot the
+# dev stack and commit screenshots back to the PR branch. That workflow
+# is gated behind a maintainer-applied `safe-to-screenshot` label and
+# refuses fork PRs because anything else would let a contributor exfil
+# the GITHUB_TOKEN through a postinstall hook or a tweaked capture.mjs.
+# This job covers the routine "does the script still parse / install"
+# loop on every PR, in the standard `pull_request` sandbox (no secrets,
+# no write permissions, no privileged token).
+#
+# Pair with: .github/workflows/docs-screenshots-capture.yml.
+
+name: docs-screenshots-build
+
+on:
+  pull_request:
+    paths:
+      - 'docs/scripts/capture.mjs'
+      - 'docs/package.json'
+      - 'docs/package-lock.json'
+      - '.github/workflows/docs-screenshots-build.yml'
+      - '.github/workflows/docs-screenshots-capture.yml'
+
+jobs:
+  build:
+    name: Verify capture script
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund
+
+      # `node --check` parses the script without executing it. The
+      # capture script imports @playwright/test at module scope, which
+      # is installed by `npm ci` above, so the parse + import-resolution
+      # walk is the cheap end-to-end gate.
+      - name: Parse capture script
+        run: node --check scripts/capture.mjs