ci(docs-truth): fail fast when the org read token is missing or unscoped

.github/workflows/docs-truth-public.yml

@@ -57,6 +57,31 @@ jobs:
           echo "repo=$repo" >> "$GITHUB_OUTPUT"
           echo "local_name=$local_name" >> "$GITHUB_OUTPUT"
 
+      # A reusable workflow's `secrets: required: true` only checks that the
+      # caller declared the key, not that the value is non-empty or usable. So
+      # a deleted secret surfaces as actions/checkout's "Input required and not
+      # supplied: token", and an under-scoped one as a bare 403 — both read as
+      # checkout bugs. The 2026-07-16 sweep cost days to that ambiguity
+      # (HELM-311). Fail here instead, naming the actual cause.
+      - name: Verify org read token
+        shell: bash
+        env:
+          TOKEN: ${{ secrets.MINDBURN_ORG_READ_TOKEN }}
+          SUBJECT_REPO: ${{ steps.subject.outputs.repo }}
+        run: |
+          if [ -z "$TOKEN" ]; then
+            echo "::error::MINDBURN_ORG_READ_TOKEN resolved empty. The caller declared the secret but no value reached this run — it was deleted, or an org secret's visibility does not cover this repo."
+            exit 1
+          fi
+          code=$(curl -sS -o /dev/null -w '%{http_code}' \
+            -H "Authorization: Bearer $TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/Mindburn-Labs/$SUBJECT_REPO")
+          if [ "$code" != "200" ]; then
+            echo "::error::MINDBURN_ORG_READ_TOKEN cannot read Mindburn-Labs/$SUBJECT_REPO (HTTP $code). 401=invalid or expired; 403=valid but insufficient scope; 404=token has no access to this repo. Checkout would fail next with a misleading git error."
+            exit 1
+          fi
+
       - name: Checkout subject repo
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with: