Setup guide

Lets `wrangler whoami` and /user/tokens/verify resolve and confirm the account ID before anything is provisioned.

↳ Optional if CLOUDFLARE_ACCOUNT_ID is always supplied explicitly, but without it wrangler cannot list accounts and fails in non-interactive mode.

Uploads the Worker bundle and its bindings (`wrangler deploy`, `wrangler versions upload`, `wrangler versions deploy`, `wrangler rollback`) and stores secrets via `wrangler secret put`.

↳ Workers Scripts:Read is enough for a review-only or cost-modelling engagement that never deploys.

Creates buckets, sets lifecycle rules, and enables/inspects Sippy for the incremental object-storage migration.

↳ Workers R2 Storage:Read covers auditing existing buckets; note this permission governs the bucket control plane, while data-plane reads/writes use the separate R2 S3 access key pair.

Creates the CONFIG namespace and writes/reads keys for feature flags and routing tables.

↳ Workers KV Storage:Read suffices once namespaces exist and the Worker only reads at runtime.

Creates the D1 database, applies migrations with `wrangler d1 migrations apply --remote`, and runs EXPLAIN QUERY PLAN / DDL through `wrangler d1 execute`.

↳ D1:Read allows querying and plan inspection without schema changes; use it once the schema is frozen.

Creates the queue used for async fan-out, retries and dead-lettering (`wrangler queues create`).

↳ Drop this permission entirely if step 2 of the procedure does not select Queues as a primitive.

Streams live logs during cutover with `wrangler tail --status=error` to catch 1101/1102 before shifting more traffic.

↳ Omit for offline design work; it is only needed while observing a running deployment.

Resolves the zone by name to its Zone ID and reads the zone plan, which caps Cache Rules and WAF custom rule counts.

↳ No narrower option; this is already read-only.

Attaches `app.example.com/*` to the Worker so the route in wrangler.jsonc actually binds on deploy.

↳ Not needed if the Worker is invoked only on a workers.dev subdomain or via Service bindings.

Toggles the cache settings this skill PATCHes: tiered_cache_smart_topology_enable and cache_reserve.

↳ Zone Settings:Read is enough for an audit that only reports current cache posture.

PUTs the entrypoint rulesets for the http_request_cache_settings, http_ratelimit and http_request_firewall_managed phases (Cache Rules, rate limiting, managed-ruleset Log-then-Block rollout).

↳ Zone WAF:Read allows reviewing existing rulesets before you overwrite a phase entrypoint - do that first, because each PUT replaces the whole phase.

Purges by URL or prefix after a cache-key or TTL change so the new Cache Rule is what you are actually measuring.

↳ There is no narrower purge scope; restrict blast radius by scoping the token to a single zone rather than All zones.

Cause: wrangler found no OAuth session from `wrangler login` and no token in the environment (a token exported only as CF_API_TOKEN does not count).

Fix: Export CLOUDFLARE_API_TOKEN with the scoped token, or run `npx wrangler login` for interactive use. Export CF_API_TOKEN as well so the curl snippets in this skill authenticate too.

Cause: The token can see multiple accounts and wrangler cannot prompt in CI.

Fix: Set CLOUDFLARE_ACCOUNT_ID (or `account_id` in wrangler.jsonc) to the 32-hex account ID printed by `wrangler whoami`.

Cause: The token is missing the permission group for the resource, is scoped to the wrong account or zone, has expired, or is blocked by its IP filter. Cloudflare returns the same generic code for insufficient scope as for a bad token.

Fix: Re-open the token at https://dash.cloudflare.com/profile/api-tokens, add the missing group (for example Zone WAF:Edit for ruleset PUTs, D1:Edit for migrations), confirm Zone Resources includes the zone, then re-verify with /user/tokens/verify.

Cause: ZONE_ID is empty or wrong, so the path contains a blank or malformed identifier - usually the shell variable was never exported into the subshell running the curl.

Fix: echo "$ZONE_ID" to confirm 32 hex characters, re-copy it from the domain Overview page, and re-run the request.

Cause: No Cache Rule matched the request, so Cloudflare treated the response as uncacheable by default.

Fix: Check the rule expression really matches the path, confirm the hostname is Proxied, and re-issue the PUT to the http_request_cache_settings phase entrypoint. If the status is BYPASS instead, the origin is sending Set-Cookie or Cache-Control: private/no-store - override edge TTL and normalize the cache key.

Cause: An uncaught exception inside the Worker, most often an unhandled rejection or a null binding because the binding name in wrangler.jsonc does not match the code.

Fix: Run `npx wrangler tail --format=pretty --status=error` to see the stack, wrap the handler in try/catch, and confirm every binding name (ASSETS, DB, CONFIG, ROOM) exists in the deployed version.

Cause: CPU time exceeded - commonly buffering a large R2 object with arrayBuffer(), or heavy synchronous work per request.

Fix: Stream R2 bodies with `new Response(obj.body)`, move non-blocking work into ctx.waitUntil(), and raise `limits.cpu_ms` only after profiling.

Cause: Module-scope initialization (large parsing, client construction, WASM instantiation) runs during the deploy-time startup check.

Fix: Initialize lazily inside the fetch handler behind a cached promise instead of at module scope, then redeploy.

Cause: Migrations were applied with --local only, or to a different database than the one bound by database_id in wrangler.jsonc.

Fix: Run `npx wrangler d1 migrations apply <db> --remote` and confirm the database_id in wrangler.jsonc matches the ID printed by `wrangler d1 create`.

Cause: A rate-limiting rule you deployed is matching real traffic - frequently because the characteristics are too coarse (ip.src alone behind a corporate NAT or a mobile carrier).

Fix: Widen requests_per_period, add a narrower expression, or add characteristics such as a session identifier. Remember non-Enterprise rules must still include cf.colo.id, which makes the effective limit per data centre.