Add an agent-setup prompt for cli.mapbox.com

[zmofei]

What

Adds site/agent-setup/prompt.md, a page meant to be served at https://cli.mapbox.com/agent-setup/prompt.md, modeled on Cloudflare's agent-setup prompt. A user hands the URL to any coding agent, and the agent installs the Mapbox CLI, the Mapbox Agent Skills and the hosted MCP servers (mapbox, mapbox-devkit, mapbox-docs).

The CLI is the first step, not optional: the page lives on the CLI's domain, the CLI is the skills fallback where npm isn't available, and it still works where an MCP client can't sign in (see AGI-1166). It installs via Homebrew, or by downloading the script and then running it, because agent sandboxes deny curl | sh outright (AGI-1135). The script runs with MAPBOX_CLI_NO_AGENT_SETUP=1, since its skills and MCP questions would wait on an agent that can't answer them, and the prompt sets those up itself. If the install is denied, the agent hands the commands to the user instead of skipping the step.

The page never asks for a token. Every server and the CLI sign in with OAuth in the browser.

Checks

• tests/docs_contract.rs: every mapbox … command and flag in the prompt must exist in mapbox --schema. The README check doesn't look at flags; this one does, because agents run the prompt verbatim. I confirmed it fails when a flag or command name is broken.
• prose_is_american_english now also reads site/.

Not verified

• I haven't run any of the per-agent commands or config snippets end to end (Claude Code plugin, Codex, Cursor, VS Code, OpenCode, Windsurf). They come from the skills repo, the hosted MCP guide, Cloudflare's prompt and each tool's --help.
• Codex OAuth currently fails against mcp.mapbox.com and mcp-devkit.mapbox.com (AGI-1166). A fix for the issuer mismatch is in review upstream and works in staging, so the Codex section describes the flow as it will be once that ships.
• I haven't checked that downloading the script and then running it gets through Claude Code's default sandbox.
• The Windows command (-ExecutionPolicy Bypass -File) hasn't been tested.
• I haven't run the installer with MAPBOX_CLI_NO_AGENT_SETUP=1 from an agent with a real terminal; that it skips the questions is from reading install.sh and install.ps1.

Before merging

• The private release pipeline has to publish site/agent-setup/prompt.md at /agent-setup/prompt.md with text/markdown. Today that path returns 403.
• The maintainers of mapbox-agent-skills and hosted-mcp-server should review the parts that describe their projects. Nothing in this repo can check those.
• Follow-ups: once a release ships mapbox mcp (Add mapbox mcp: register a Mapbox MCP server with a coding agent #69, after 0.3.0), decide whether to point the MCP sections at mapbox mcp install --global. It isn't a drop-in: for Cursor and VS Code it writes the app's own global profile, not ~/.cursor/mcp.json or a project .vscode/mcp.json, so it means choosing between that and the hand-edit path documented here. After Make the install scripts read like a finished product #71 merges, point a failed install at ~/.local/state/mapbox-cli/install.log.

[mattpodwysocki]

On the Cursor bullet in "Not verified": checked this against Cursor's own current docs, and ~/.cursor/mcp.json with "mcpServers" is still the documented, current format, so this isn't stale. What #69 found (Cursor 3.x keeping servers in settings.json under "mcp") is a different thing: that's specifically where the cursor --add-mcp CLI flag writes, not the file Cursor's docs tell a person to hand-edit. Both are real and coexist.

One thing this does sharpen for the "Follow-ups" note: once #69 lands, mapbox mcp install for Cursor/VS Code only ever touches the app's own global profile, never ~/.cursor/mcp.json or a project-level .vscode/mcp.json. So swapping the snippets here for mapbox mcp install isn't a clean drop-in, it's a choice between pointing this page at the CLI's file or keeping the hand-edit path documented here.

On the Codex OAuth bullet: a fix is in review upstream for the issuer/authorization-endpoint mismatch Codex was rejecting, and it's already tested working in staging for Codex, Claude Code, MCP Inspector and ChatGPT. Worth noting here that it's in progress rather than leaving it as open-ended.

Everything else in "Not verified" (the other per-agent snippets, the Windows command, sandbox download-then-run behavior) is still genuinely unverified.

[zmofei]

Thanks @mattpodwysocki, updated the description:

• Dropped the Cursor "may be stale" bullet; the prompt keeps ~/.cursor/mcp.json.
• The follow-up now says moving to mapbox mcp install is a choice between the app's global profile and the hand-edit path, not a drop-in.
• The Codex bullet notes the upstream fix is in review and working in staging.

[mattpodwysocki]

Re-reviewed after the latest commit. Good catch making the install scripts skip their interactive questions when run from the prompt, an agent with a real pty could otherwise hang waiting for an answer nobody will give.

Full suite, clippy -D warnings, fmt, and the new every_command_the_agent_setup_prompt_spells_exists contract test all pass, confirmed on the actual branch, not just the diff. CI green. Thanks for folding in the Cursor/Codex updates from the earlier pass.