[Turnstile] Add Spin docs page#31195
Open
juleslemee wants to merge 5 commits into
Open
Conversation
Adds /turnstile/spin/ documenting the Turnstile Spin agent skill: how to invoke it, what it does end-to-end (widget create, Worker deploy, frontend snippets, validation), the full inlined SKILL.md prompt for paste-into-agent flows, recovery flow, edge cases, and migration from reCAPTCHA/hCaptcha. Companion to the skill PR at cloudflare/skills#58. Internal PRD: https://jira.cfdata.org/browse/NC-8209
juleslemee
requested review from
a team,
elithrar,
migueldemoura and
punkeel
as code owners
Review⏸️ Automatic reviews for this PR are paused. This PR has already received 2 automatic reviews. To run another review, a codeowner can comment
|
added 4 commits
June 3, 2026 11:23
Sync to the refactored skill bundle. The MDX page's inlined paste-into-agent prompt now consists of the (much shorter) SKILL.md orchestration + a bootstrap section that writes the 6 helper scripts under /tmp/turnstile-spin-scripts/. Total prompt length is comparable to before; the architecture is cleaner because the agent now branches on structured JSON output from deterministic scripts instead of inline bash interpretation. Companion to cloudflare/skills#58.
Per Marina's review feedback, add the Beta badge to the Spin landing page (matching the multi-cloud-networking pattern): - title gets the "(beta)" suffix - sidebar.badge.text set to "Beta"
Move spin/index.mdx to spin.mdx so the page is a flat sidebar sibling of Plans, Concepts, etc., instead of a collapsible group with a single child. Shorten sidebar.label from "Spin (one-shot setup)" to "Spin".
Addresses 5 findings from Miguel's review: 1. Resolved wrangler login contradiction. The skill prose said "don't use wrangler login because OAuth lacks Account.Turnstile:Edit" but the human walkthrough, the troubleshooting table, and the 403 recovery section all instructed the agent to run wrangler login. Replaced with token-creation guidance everywhere. 2. Fixed multi-account handling in auth-probe.sh. The script hardcoded .accounts[0].id and treated any user-set CLOUDFLARE_ACCOUNT_ID pointing at a non-first account as a mismatch. It now checks membership in the accounts array, emits a new multiple_accounts status when the token covers >1 accounts and the env var is unset, and only uses [0] when there is exactly one account. 3. Added a Workers scope probe. The script docstring claimed status:ok meant both Turnstile and Workers scope were present, but the code only hit GET /challenges/widgets. Added a second probe against /workers/scripts that emits missing_workers_scope when the token lacks Account.Workers Scripts:Edit, preventing widget creation followed by Worker deploy failure. 4. Fixed wrangler secret put without --name in the human walkthrough. The script uses --name correctly; the docs prose did not, so the secret would land on wrangler.toml's default worker name. Also reordered: deploy first (so the named Worker exists), then put the secret on it. Made set_secret failure fatal in worker-deploy.sh (was previously swallowed; the script could emit status:ok with no secret on the Worker). 5. Fixed jq shape mismatch in curl fallback. Was '.account.id' (singular, wrong); now '.accounts[0].id' (matches wrangler whoami --json output and the helper script).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the canonical docs page for Turnstile Spin at
/turnstile/spin/.What's on the page
Also adds the matching plain-markdown copy at
public/turnstile/spin/index.mdso the agent's Step 8 (persist skill) can fetch it viacurl.Companion PRs
Internal context
Tier 3 launch tracked in NC-8209. PRD: https://jira.cfdata.org/browse/NC-8209
Validation: `pnpm run check` passes on the spin MDX. No type errors or broken internal links specific to this page.