diff --git a/CLAUDE.md b/CLAUDE.md
index 9796cf1..7968236 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -116,10 +116,12 @@ Each action (or group) must have a `README.md` covering:
 
 1. **What it does** — one paragraph per action
 2. **Prerequisites** — external resources that must exist (CF project, etc.)
-3. **Caller requirements** — `permissions:`, fork-PR guards, concurrency,
-   required secrets
-4. **Usage** — a minimal but complete caller workflow example
-5. **Inputs/outputs** — tables with name, required, default, description
+3. **Required secrets** — dedicated section listing every secret the caller
+   must configure: what it is, minimum permission scope, and which action
+   input it maps to. If no secrets are needed, state that explicitly.
+4. **Caller requirements** — `permissions:`, fork-PR guards, concurrency
+5. **Usage** — a minimal but complete caller workflow example
+6. **Inputs/outputs** — tables with name, required, default, description
 
 ## Registering the action
 
diff --git a/cloudflare-pages-preview/README.md b/cloudflare-pages-preview/README.md
index 03d7d02..7a40394 100644
--- a/cloudflare-pages-preview/README.md
+++ b/cloudflare-pages-preview/README.md
@@ -21,9 +21,23 @@ and cleaning them up when the PR closes.
 
 - A **Cloudflare Pages project** must be created in the Cloudflare dashboard
   first. Pass its name as `project-name`.
-- A **Cloudflare API token** with `Pages:Edit` permission scoped to that
-  project. Do not reuse a general-purpose token.
-- GitHub Actions secrets for the token and account ID.
+- Two GitHub Actions secrets (see below).
+
+## Required secrets
+
+Configure these in the caller repo (**Settings → Secrets and variables →
+Actions**) and pass them to the action via `with:`:
+
+| Secret | Passed as | What it is |
+|---|---|---|
+| Cloudflare API token | `api-token` | Token with **`Pages:Edit`** permission scoped **only** to the target Pages project. Do not reuse a general-purpose or account-wide Cloudflare token — create a dedicated token per project. |
+| Cloudflare account ID | `account-id` | Found in the Cloudflare dashboard sidebar. Not actually secret, but stored as one to co-locate with the token. |
+
+Both actions require the same two secrets.
+
+The default `github-token` (`${{ github.token }}`) is sufficient for PR
+commenting with the standard `pull-requests: write` permission — no additional
+secret is needed there unless you want to comment as a different identity.
 
 ## Caller workflow requirements