diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 28ab949..157986e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,6 +2,10 @@ name: CI
 
 on:
   pull_request:
+  # Lets a bot-pushed commit be verified on demand: GITHUB_TOKEN pushes do not
+  # trigger workflows, so the nightly refresh otherwise leaves main's CI status
+  # reflecting the last human push.
+  workflow_dispatch:
   push:
     branches: [main]
     paths:
diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml
index 4203d91..4ca7b87 100644
--- a/.github/workflows/update.yml
+++ b/.github/workflows/update.yml
@@ -46,6 +46,14 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: go run .
 
+      # Bot commits are pushed with GITHUB_TOKEN, which by design does not
+      # re-trigger workflows — so CI never runs on them. Without this step a
+      # refresh that broke the build would be discovered by Cloudflare at deploy
+      # time. Running the build before the commit means unbuildable data is
+      # never committed in the first place.
+      - name: Verify the committed data builds
+        run: go run . -build
+
       - name: Commit changes
         run: |
           git config user.name  "github-actions[bot]"
diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md
index dfb98c8..6ebf5c4 100644
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -29,11 +29,18 @@ Cloudflare's build webhook, which redeploys with the new numbers.
 
 ## One-time setup
 
-### 1. Bootstrap `data/metadata.json`
+### 1. Check `data/metadata.json` is committed
 
-The build fails without it, so generate it before connecting Cloudflare. Either
-trigger the **Update rankings** workflow manually (Actions tab →
-*Update rankings* → *Run workflow*), or run the updater locally and commit:
+The build reads it and fails without it. It is committed on `main`, kept fresh
+by the nightly **Update rankings** workflow — so this is normally just a
+sanity check:
+
+```bash
+go run . -build   # should print "built dist: N entries, data fetched ..."
+```
+
+If it is ever missing (a fresh fork, say), regenerate it by triggering
+**Update rankings** manually from the Actions tab, or locally:
 
 ```bash
 export GITHUB_TOKEN=ghp_your_token_here
@@ -85,8 +92,8 @@ are copied into `dist/` as-is and use Cloudflare's defaults.
 
 ## Troubleshooting
 
-**Build fails with "data/metadata.json not found"** — the bootstrap in step 1
-has not been committed yet.
+**Build fails with "data/metadata.json not found"** — step 1 has not been
+committed yet. Trigger *Update rankings* to produce it.
 
 **A newly added tool is missing from the site** — expected between merging the
 `agents.yml` entry and the next update run. The build logs a warning and omits