All of these currently return HTTP 404, so an agent following them gets
nothing back and typically retries variations of the guess.
- argo/ -> argo-smart-routing/
- artifacts/api/artifactfs/ -> artifacts/guides/artifact-fs/ (page moved)
- cni-locations-2026-01.pdf -> cni-locations-05-may-2026.pdf (2 files;
current filename per network-interconnect/llms-full.txt)
- workers-ai/realtimekit/ -> realtime/realtimekit/
- workers/tutorials/connect-to-postgres/ -> workers/tutorials/postgres/
- workers-sdk/tree/main/templates -> cloudflare/templates (repo moved)
- workers-sdk fixtures/vitest-pool-workers-examples -> the Vitest
integration docs page (the fixtures path no longer exists)
- cloudflare/pages-example-projects -> Pages framework guides (repo
deleted, no successor repo)
Every replacement URL was verified to return HTTP 200.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* Add Sandbox 1.0 migration skills
Refresh sandbox-sdk for @next and add sandbox-v1-migration plus
sandbox-2026-deprecation so agents install migrate paths from
cloudflare/skills instead of docs-only markdown.
* Split Sandbox skills by package line
Agents need separate build paths for stable and @next so they do
not mix incompatible exec models. Keep migration as its own
performable upgrade skill.
* Rename sandbox-sdk skill to sandbox-next
Pair build skills as sandbox-next and sandbox-stable so the
package line is obvious from the skill name.
* Restructure Sandbox skills as retrieval maps
Build skills gate the package line, state the contract, and
route to docs by task. Keep migrate as a stepwise port runbook.
* Clarify @next API file is a cheatsheet only
Point exhaustive reading at types and docs so agents do not
treat the process/terminal stub as the full Sandbox surface.
* turnstile-spin: guide token reset after submit to fix V2 double-redemption
Turnstile tokens are single-use. When siteverify returns success:false and
the user retries, the browser resubmits the same cf-turnstile-response and
Cloudflare's edge rejects it with timeout-or-duplicate. V2 telemetry since
the 2026-07-14 launch shows 4.86% sv_fail rate, of which 99% (123/124) are
double redemptions — 5x the V1 baseline of 0.9%.
Add reset-on-submit guidance to the canonical frontend snippet in SKILL.md
and to each framework reference so the widget re-solves before the retry.
Also add a 'Token lifecycle' paragraph explaining the single-use contract.
- SKILL.md: id=cf-form + reset script; Token lifecycle paragraph
- vanilla-html: main HTML + AJAX variant get reset calls
- nextjs-app: handleSubmit resets on !data.ok; Server Action variant
covers useActionState error branch
- nextjs-pages: reset script wrapped in <Script> for hydration ordering
- sveltekit: use:enhance callback resets on non-redirect + client-fetch
variant
- astro: main form script + Astro Actions variant reset
- hugo: partial gets reset script
* [Turnstile] Spin skill: address code review warnings from docs PR
Mirrors the fixes applied in cloudflare/cloudflare-docs#32147:
* Siteverify snippet in Step 9 now wraps fetch+json in try/catch,
checks r.ok, and replaces the non-existent reject(403, ...) helper
with res.status(403).send('forbidden') plus a comment about
adapting to the target framework.
* Recovery flow step 3 no longer offers 'ask user or exit' for
non-no_clearance widgets, which contradicted the scope boundary.
Always exits per the boundary now.
Keeps this file byte-for-byte in sync with the docs prompt.md and
stratus spinSkillContent.ts (the three-surface parity that the
Spin machinery depends on).
* [Turnstile] Spin skill: broaden scope beyond forms per review
Marina flagged on cloudflare/cloudflare-docs#32147 that the skill's
scope reads too form-centric, when Turnstile actually applies to any
user-triggered request the customer wants to gate: form submissions,
SPA button-triggered API calls, download links, comment or vote
submissions, and any other explicit user action that hits a backend
the customer controls.
Broadened six spots to match how Turnstile is actually used in the
wild (per the product docs at developers.cloudflare.com/turnstile),
while keeping the canonical form example in the frontend-edit
contract section as the primary illustration:
* Description: 'embed it on the right forms' -> 'embed it where user
requests need bot verification (form submissions, SPA actions, API
endpoints, download links, comment or vote submissions, etc.)'.
* When-to-load triggers: added 'protect this endpoint', 'protect this
button', 'block bots on <target>'; the 'specific request' example
bullet now lists downloads / comments / API endpoints alongside
signup / login / contact form.
* Brief-acknowledge line the agent says on Step 1.
* Wire-the-integration statement the agent says on Step 9.
* Hard-scope-boundary sentence: dropped 'form' qualifier on handler.
* Frontend-edit-contract opener: covers form or user-triggered
endpoint; dropped 'submit' from handler.
Kept in sync across all three surfaces (this canonical SKILL.md,
prompt.md docs, stratus spinSkillContent.ts).
* Harden Turnstile Spin helper scripts (safety + portability)
Replaces hand-escaped JSON with python3 json.dumps for both request
bodies and response outputs, adds argument-value validation before
each shift, structures HTTP error handling, and switches auth-probe
from a GET-based read probe to a POST-invalid-payload probe so it
tests Turnstile:Edit specifically.
widget-create.sh:
- python3 json.dumps for request body + success/error output
(replaces `echo "{\"name\":\"$NAME\",...}"` which broke
on names containing quotes, backslashes, or control characters)
- Argument value validation before shift
- Remove `2>/dev/null` on the API curl so network errors reach stderr
- URL-encode account_id
validate.sh:
- Argument value validation
- mktemp + -o + %{http_code} pattern for the widget-domains lookup
- python3 with structured error handling for JSON parse failures
- URL-encode account_id and sitekey
auth-probe.sh:
- `command -v wrangler` guard before invocation (avoids npx
install-prompt hang in non-interactive envs); fall back to
$CLOUDFLARE_ACCOUNT_ID when wrangler is not on PATH
- Replace GET-based scope probe with POST-invalid-payload probe:
a GET would authorize a Read-only token and let the agent proceed
to widget-create where it would fail. POST-invalid tests Edit
specifically: 401/403/err-10000 -> missing_scope, 400/422 -> scope OK.
- mktemp with explicit template for macOS/BSD portability
- Argument value validation
fetch-secret.sh:
- Argument value validation
- mktemp with explicit template + trap-based cleanup on early exit
- Python fallbacks use .get() with structured error output on
missing keys or non-JSON responses
- URL-encode account_id and sitekey
persist-skill.sh:
- Argument value validation
- Build scripts JSON list via python3 os.listdir + json.dumps
(replaces ls | sed | paste which mishandled filenames with quotes,
backslashes, or newlines)
Flagged by cloudflare-docs-bot on
https://github.com/cloudflare/cloudflare-docs/pull/32147: 1 critical
(CR-22ef8f6771b1) + 15 warnings + 1 suggestion. All 19 addressed.
Companion: cloudflare-docs #32147, stratus MR !40817.
* Harden Turnstile Spin helper scripts (second pass on docs-bot findings)
Second round of docs-bot findings: 6 real issues + 3 secrets-in-argv
warnings addressed. The bot's critical (EXIT trap fires in $() subshell)
is a false positive verified with a bash test: subshells reset their
parent's traps per the bash manual, so $tmp survives curl $() calls
and the trap only fires on outer-script exit.
- All scripts: 'command -v python3' guard at top; emit structured JSON
error on missing prerequisite instead of raw shell error.
- All scripts: header comments now document exit 2 (invalid usage) in
addition to exit 0 (success) and exit 1 (failure).
- widget-create.sh, validate.sh, fetch-secret.sh, auth-probe.sh:
Authorization header written to mode-600 tempfile, curl reads it via
'-H @file'. Bearer token never appears in argv.
- validate.sh: Turnstile secret written to mode-600 tempfile, curl reads
it via --data-urlencode 'secret@file'. Secret never appears in argv.
- validate.sh: strip whitespace from each expected-domains token so
'--expected-domains "a.com, b.com"' matches correctly.
- fetch-secret.sh, auth-probe.sh: guard 'errors[0]' with '(errors[0] or {})'
before .get() to survive non-dict error entries.
- All parse blocks: 'isinstance(data, dict)' check after json.loads;
emit structured error output when response is not a JSON object.
- persist-skill.sh: catch OSError (not just FileNotFoundError) so
NotADirectoryError/PermissionError on the scripts dir emit
'scripts: []' instead of a traceback.
Skipped:
- CR-04913c72363f (critical, false positive; bash test in the docs PR
triage comment)
- CR-14b4e5e6a596 (suggestion; --path is user-supplied by design so
agents can persist to .claude/skills, .opencode/skills, etc.)
Companion: cloudflare-docs #32147, stratus MR !40817.
* Guard mktemp, malformed errors list, and npx prerequisite
Docs-bot third-round review flagged four items:
- Unchecked mktemp in widget-create.sh (two calls). Applied
inline mktemp guards across all mktemp calls in
widget-create.sh, validate.sh, fetch-secret.sh, and
auth-probe.sh. On failure the scripts emit structured error
JSON matching the existing contract and clean up any earlier
tempfiles before exit.
- fetch-secret.sh accessed errors[0] without first checking
that errors is a list. Added isinstance(errors, list) guard
and applied the same fix to widget-create.sh, validate.sh,
and auth-probe.sh which have the same pattern.
- persist-skill.sh had a python3 command -v guard but not one
for npx (needed for the degit call). Added the npx guard
next to it, returning a structured error JSON on absence.
* Add cleanup safety net to auth-probe Edit-scope probe
Docs-bot and gsa_claude flagged that the Edit-scope probe POSTs a
widget-create request with intentionally-invalid empty name/domains
to distinguish Read scope (401/403) from Edit scope (400/422). The
API rejects the payload today, so no widget is created, but there
was no safety net if validation ever loosened.
Parse result.sitekey from the probe response and, if a widget was
unexpectedly created (success:true with a sitekey), fire a DELETE
against it so the probe stays side-effect-free regardless of future
API validation changes. Verdict logic and existing 400/422/200/401/
403 branches are unchanged.
* Correct Step 2 + Troubleshooting prose to match auth-probe behavior
gsa_claude flagged that Step 2's CLI-check paragraph still said Spin's
helper scripts use `npx wrangler whoami` for account enumeration and
that no persistent CLI install is required. Neither is accurate after
the auth-probe.sh rewrite: the probe uses PATH-resident `wrangler`
(not npx, so a non-interactive shell won't hang on auto-install) and
falls back to requiring `$CLOUDFLARE_ACCOUNT_ID` when wrangler is
missing.
Rewrite line 38 (Step 2) and line 195 (`wrangler whoami` troubleshooting
row) to reflect the actual behavior: PATH check first, otherwise
require the account ID be exported. Also drop the misleading suggestion
to curl `/accounts` as a fallback \x2D the Account.Turnstile:Edit token
can't list accounts (`/accounts` is Account.Read-scoped), so that
fallback would 403.
* Harden Turnstile Spin skill after independent semantic review
Independent review of the Turnstile Spin skill surfaced a critical
Python module-shadowing risk, several correctness gaps in the recovery
flow and reference examples, and drift in the README install path.
Fixes applied to SKILL.md, all six framework references, the four
helper scripts, the test doc, and the README:
- Run every embedded python3 invocation with -I to prevent cwd-relative
module shadowing of stdlib (urllib, json, hashlib, os, re, sys).
Covers -c inline, - stdin heredoc, and the bootstrap loop.
- auth-probe.sh: distinguish network_failure and upstream_failure from
missing_scope; SKILL.md Step 3 documents branches for both.
- SKILL.md Step 3: post-auth recovery resumes at Step 4 (the numbered
wizard) instead of jumping over Steps 4-7.
- SKILL.md Step 9: require git check-ignore before writing to any
.env-style file, with fallback to the platform's secret manager.
- Framework references (vanilla-html, nextjs-app, nextjs-pages, astro,
sveltekit, hugo): inline a TURNSTILE_HOSTNAMES allowlist and compare
result.hostname against it in every server-side snippet. Includes
Node, Ruby, and Python variants in vanilla-html.
- README: recommend the git-clone/symlink install path; keep the
single-file curl bootstrap only as a read-only fallback with a note
that persist-skill.sh needs the cloned bundle.
- Remove fetch-secret.sh (superseded by the in-flow existing-widget
recovery in SKILL.md, no callers remain).
Scripts still pass shellcheck and safe smoke tests (missing_token,
file_target_not_supported, empty-array rejection, unsupported-mode
rejection). Isolation is confirmed by poisoning urllib.py/json.py/
hashlib.py in the working directory and re-running each script.
---------
Co-authored-by: Jules Lemee <jules@cloudflare.com>
Limit the final diff to correcting broken REST paths, SDK namespaces, and route request shapes.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: faf22a37-1023-405e-afc5-3871e8f1dab0
Restore the existing reference structure and limit the change to broken REST endpoints and SDK calls.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: faf22a37-1023-405e-afc5-3871e8f1dab0
Brendan Irvine-Broque