Chore/update docs

.github/workflows/docs.yml

@@ -2,26 +2,39 @@ name: Docs
 
 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
+    branches: [main]
+    paths:
+      # api/signer-api.yml is embedded in the site's API tab (webpack alias in
+      # docusaurus.config.js), so spec-only changes must also redeploy
+      - 'docs/**'
+      - 'api/**'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+
+# Pages deployments race if two docs merges land close together; queue them
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
   build:
     name: Build Docusaurus
     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 (npm install
+        # re-resolves ranges at run time and can drift between runs)
+        run: npm ci
         working-directory: ./docs
 
       - name: Build website

.github/workflows/test-docs.yml

@@ -4,24 +4,32 @@ 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:
+      # Mirror docs.yml: api/signer-api.yml is embedded in the site's API tab
+      - 'docs/**'
+      - 'api/**'
+      - '.github/workflows/test-docs.yml'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
 
 jobs:
   test-deploy:
     name: Test deployment
     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