diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bdf76258..440576fc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,3 +1,16 @@
+# CI Workflow
+#
+# Builds the Zensical docs site and publishes it to GitHub Pages.
+#
+# Triggered on: push to main
+# Requirements: none — deploy-pages authenticates via the job's own Pages/OIDC
+# permissions, no external secrets needed
+#
+# Notes:
+# - No concurrency group, so back-to-back pushes to main can deploy in parallel
+#   with no ordering guarantee — a slower, older run can finish after a newer one
+#   and leave stale content live.
+
 name: ci
 on:
   push:
@@ -14,12 +27,15 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     permissions:
-      contents: read
-      pages: write
-      id-token: write
+      contents: read   # needed for checkout
+      pages: write     # needed by actions/deploy-pages
+      id-token: write  # needed by actions/deploy-pages (OIDC)
+
     steps:
       - uses: actions/configure-pages@v6
       - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
diff --git a/.github/workflows/update-api-docs.yml b/.github/workflows/update-api-docs.yml
index 6e9490f7..e4de2ba1 100644
--- a/.github/workflows/update-api-docs.yml
+++ b/.github/workflows/update-api-docs.yml
@@ -1,3 +1,18 @@
+# Update API Documentation Workflow
+#
+# Regenerates docs/api/ from the OCS OpenAPI schema — fetches the schema files
+# from the OCS repo, runs them through src/ocs_docs/openapi_to_docs.py, and opens
+# a PR with the result if anything changed. docs/api/ is generated; don't hand-edit.
+#
+# Triggered on: repository_dispatch (`ocs_api_update`) from the OCS repo; a daily
+# schedule (02:00 UTC) as a backstop; or workflow_dispatch (manual)
+# Requirements: OCS_AGENT_APP_ID (var) / OCS_AGENT_PRIVATE_KEY (secret) for the
+# ocs-agent GitHub App token used to open the PR
+#
+# Notes:
+# - Labelled `automated`, same as update-changelog.yml's PRs — keeps these PRs
+#   out of the AI review in claude-review.yml (see README-claude-workflows.md).
+
 name: Update API Documentation
 
 on:
@@ -15,14 +30,14 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: write
-      pull-requests: write
+      contents: read  # needed for checkout and the cross-repo `gh api` read; PR creation uses the ocs-agent app token
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -77,7 +92,8 @@ jobs:
         with:
           app-id: ${{ vars.OCS_AGENT_APP_ID }}
           private-key: ${{ secrets.OCS_AGENT_PRIVATE_KEY }}
-
+          permission-contents: write
+          permission-pull-requests: write
       - name: Create Pull Request
         if: steps.check_changes.outputs.has_changes == 'true'
         uses: peter-evans/create-pull-request@v8
diff --git a/.github/workflows/update-confluence.yml b/.github/workflows/update-confluence.yml
index c14b3254..d323820f 100644
--- a/.github/workflows/update-confluence.yml
+++ b/.github/workflows/update-confluence.yml
@@ -1,3 +1,18 @@
+# Update Confluence Release Table Workflow
+#
+# Publishes a row to the Confluence release table for a published GitHub release —
+# runs scripts/update_confluence_release.py with the release's tag, URL, and body
+# pulled from either the triggering release event or a manual re-run.
+#
+# Triggered on: release (published); or workflow_dispatch with a required
+# release_tag input (manual re-run/backfill for an existing release)
+# Requirements: CONFLUENCE_BASE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN secrets
+#
+# Notes:
+# - update_confluence_release.py always inserts a new row — rerunning for a tag
+#   that's already on the page adds a duplicate row rather than updating it in
+#   place, so only backfill tags that aren't there yet.
+
 name: Update Confluence Release Table
 
 on:
@@ -24,6 +39,8 @@ jobs:
     steps:
       - name: Check out repository
         uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -32,15 +49,17 @@ jobs:
         if: github.event_name == 'workflow_dispatch'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG_INPUT: ${{ github.event.inputs.release_tag }}
         run: |
-          TAG="${{ github.event.inputs.release_tag }}"
+          TAG="$RELEASE_TAG_INPUT"
           gh release view "$TAG" --json body,tagName,url > release.json
+          DELIMITER="RELEASE_BODY_EOF_$(openssl rand -hex 16)"
           {
             echo "RELEASE_TAG=$(jq -r .tagName release.json)"
             echo "RELEASE_URL=$(jq -r .url release.json)"
-            echo "RELEASE_BODY<<RELEASE_BODY_EOF"
+            echo "RELEASE_BODY<<$DELIMITER"
             jq -r .body release.json
-            echo "RELEASE_BODY_EOF"
+            echo "$DELIMITER"
           } >> "$GITHUB_ENV"
 
       - name: Resolve release info from release event
@@ -50,12 +69,13 @@ jobs:
           EVENT_URL: ${{ github.event.release.html_url }}
           EVENT_BODY: ${{ github.event.release.body }}
         run: |
+          DELIMITER="RELEASE_BODY_EOF_$(openssl rand -hex 16)"
           {
             echo "RELEASE_TAG=$EVENT_TAG"
             echo "RELEASE_URL=$EVENT_URL"
-            echo "RELEASE_BODY<<RELEASE_BODY_EOF"
+            echo "RELEASE_BODY<<$DELIMITER"
             printf '%s\n' "$EVENT_BODY"
-            echo "RELEASE_BODY_EOF"
+            echo "$DELIMITER"
           } >> "$GITHUB_ENV"
 
       - name: Update Confluence release table