From 926bead412bebdf1a5f8bbd42fd02dbdca2857f2 Mon Sep 17 00:00:00 2001
From: Jason Vranek <jasonvranek@gmail.com>
Date: Tue, 11 Aug 2026 13:55:15 -0700
Subject: [PATCH] ci(docs): manual, main-only docs deploy on demand
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the abandoned `stable`-branch deploy (frozen at v0.9.3) with a
manual (`workflow_dispatch`) GitHub Pages deploy.

Publishing is restricted to `main` by two independent layers: the
`github-pages` environment's deployment-branch policy (set to `main` only),
and a guard step that fails the run if dispatched from any other ref. So
"only what's reviewed and merged to main is published" holds even though
workflow_dispatch's branch picker technically offers other branches.

Manual (not push-triggered) so publishing is a deliberate act and a failed
run can be re-fired without a new commit if the runner is unavailable.

test-docs runs the build on any PR touching docs or their linked inputs
(filter covers `config.example.toml`, drops `api/**` — the API spec is
fetched client-side at runtime, not built in).
---
 .github/workflows/docs.yml      | 37 +++++++++++++++++++++++++--------
 .github/workflows/test-docs.yml | 21 +++++++++++++------
 2 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a23cbd7e..6429f477 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,27 +1,46 @@
 name: Docs
 
+# Manual only: click "Run workflow" to publish the docs currently on the
+# selected branch (defaults to the repo default branch). Publishing is a
+# deliberate act, not a side effect of a merge, and a failed run can simply be
+# re-run without pushing a new commit.
 on:
-  push:
-    branches:
-      - stable
-    # Review gh actions docs if you want to further define triggers, paths, etc
-    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
   build:
     name: Build Docusaurus
     runs-on: ubuntu-latest
     steps:
+      # Publishing is main-only. The github-pages environment enforces this at
+      # deploy time, but fail loud here too so a mistaken dispatch from another
+      # branch stops before building instead of silently producing no deploy.
+      - name: Refuse to publish from a non-main branch
+        if: github.ref != 'refs/heads/main'
+        env:
+          DISPATCHED_REF: ${{ github.ref }}
+        run: |
+          echo "::error::Docs publish only from main (dispatched ref: $DISPATCHED_REF)."
+          exit 1
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
       - name: Install dependencies
-        run: npm install
+        # npm ci = reproducible install from package-lock.json (npm install
+        # re-resolves ranges at run time and can drift between runs)
+        run: npm ci
         working-directory: ./docs
 
       - name: Build website
diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml
index 6cb3e4d9..e3211761 100644
--- a/.github/workflows/test-docs.yml
+++ b/.github/workflows/test-docs.yml
@@ -4,8 +4,16 @@ on:
   pull_request:
     branches:
       - main
-    # Review gh actions docs if you want to further define triggers, paths, etc
-    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+    paths:
+      # config.example.toml is linked from docs/ and bundled into the build, so
+      # a PR that changes or removes it must run the build check
+      - 'docs/**'
+      - 'config.example.toml'
+      - '.github/workflows/test-docs.yml'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
 
 jobs:
   test-deploy:
@@ -13,15 +21,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
       - name: Install dependencies
-        run: npm install
+        # npm ci = reproducible install from package-lock.json
+        run: npm ci
         working-directory: ./docs
 
       - name: Test build website