diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2bfbe0e..76561df 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -173,7 +173,8 @@ jobs:
 
   # --------------------------------------------------------------- homebrew
   # Refreshes efij/homebrew-agentdfir. Needs HOMEBREW_TAP_TOKEN (contents:write
-  # on the tap repo). Without it the step prints the manual command and passes.
+  # on the tap repo). Without it the release FAILS visibly: a green release with
+  # a stale `brew upgrade` is worse than a red one.
   homebrew:
     needs: verify
     runs-on: ubuntu-latest
@@ -186,7 +187,17 @@ jobs:
         run: |
           set -euo pipefail
           if [ -z "${TAP_TOKEN:-}" ]; then
-            echo "HOMEBREW_TAP_TOKEN not set. Run locally: scripts/update-tap.sh $RELEASE_TAG"
-            exit 0
+            echo "::error::HOMEBREW_TAP_TOKEN secret is not set — Homebrew users would stay on the previous version."
+            echo "Fix: add a fine-grained PAT with contents:write on efij/homebrew-agentdfir as repo secret HOMEBREW_TAP_TOKEN,"
+            echo "then re-run this job, or publish by hand: scripts/update-tap.sh $RELEASE_TAG"
+            exit 1
           fi
           scripts/update-tap.sh "$RELEASE_TAG"
+      - name: Verify tap serves this version
+        run: |
+          set -euo pipefail
+          got=$(curl -fsSL "https://raw.githubusercontent.com/efij/homebrew-agentdfir/main/Formula/agentdfir.rb" | grep -o 'tags/v[0-9][0-9.]*' | head -1 | sed 's#tags/##')
+          if [ "$got" != "$RELEASE_TAG" ]; then
+            echo "::error::tap formula points at ${got:-nothing}, expected $RELEASE_TAG"; exit 1
+          fi
+          echo "tap formula at $RELEASE_TAG"
diff --git a/docs/install.md b/docs/install.md
index ba92a58..e02f4d4 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -185,3 +185,12 @@ quarantine flag on macOS and the mark-of-the-web on Windows, before the
 release is considered good. The same `verify` job can be re-run at any time
 against an already-published tag from the Actions tab (*Run workflow* →
 enter the tag), which skips the build and checks only what users download.
+
+
+## Release checklist (maintainers)
+
+A tag push builds, signs and publishes assets, then updates the Homebrew tap. The tap step **fails the release**
+if the `HOMEBREW_TAP_TOKEN` repository secret is missing (fine-grained PAT, `contents: write` on
+`efij/homebrew-agentdfir`) and verifies the formula now serves the tag. Manual fallback: `scripts/update-tap.sh vX.Y.Z`.
+After every release check all four paths report the new version: `brew upgrade agentdfir`, `install.sh`,
+`go install github.com/efij/AgentDFIR/cmd/agentdfir@latest`, raw binary from the releases page.