WS-G1: agent-first docs funnel — /agent-setup paste-prompt + publish docs aligned to the live release API

[mathias-heide]

WS-G1: the agent-first Summer SDK docs funnel. A person points any coding agent at these docs; the agent builds a multiplayer Godot game and publishes it to Summercraft. Builds on the 2026-07-28 Summer SDK rename (PR #1); product copy says Summercraft / Summer SDK, frozen wire identifiers untouched.

What changed

New pages

• /agent-setup — funnel landing page: the copy-paste bootstrap block, human token-extraction steps (agents never touch passwords), and a live-vs-coming capability table.
• /agent-setup/prompt — the canonical agent instruction set, fetchable raw at /agent-setup/prompt.md (Cloudflare prompt.md pattern). Contains a complete multiplayer-native template — project files, local SDK stubs, export preset — plus local validation, the exact four-call publish flow, per-error recovery, and an honest post-submission section. Every file and command in it was executed with Godot 4.5.1 before being written down.

Rewritten against the live publish API (shapes derived from the deployed route sources in summercraft src/app/api/games/engine/* and src/app/api/games/[gameId]/releases/**, cross-checked with docs/API.md and live expected-401 probes):

• exporting-and-uploading-your-game — now documents the real pipeline: POST /api/games/engine → POST …/releases/upload-url (presigned, content-type pinned, if-none-match: * write-once) → PUT → POST …/releases/finalize (server-streamed sha256, nothing client-claimed trusted) → manual review → GET …/releases/{version}/download-url. Exact request/response bodies, limits (1024 B–512 MiB, 1/hour per step per account, 1 h presign TTL, 5 min download TTL, version regex), full error tables. The old page documented only the Railway multipart flow.
• submission-guide — the two live paths side by side (release API; browser /submit multipart with its 2 GB cap and upload-time static scanner — Railway hostname kept verbatim as the deployed identity), unified review lifecycle, immutable-release update flow.
• build-your-first-summer-game — multiplayer-native by default (host-authoritative, min_players: 1 / max_players: 8), honest transport note: ENet today, SummerMultiplayerPeer per the transport contract is engine-fork work in progress.
• testing-your-game-locally — new standalone agent/CLI section (stubs, headless smoke run, banned-API grep, pack-content check), honest about what it does and does not validate.
• manifest-json-reference — runtime resolution rules verified from the desktop repo's core/game_loader.gd (paths relative to the manifest, entry root must extends SummerGame), release-version constraints.
• ai-agent-playbook — now points to /agent-setup/prompt.md as canonical; publish step updated.
• docs.json / index / SDK overview — "Agent Setup" nav group in the Summer SDK tab; funnel cards on the docs landing page and the SDK overview.

llms.txt / llms-full.txt / .md suffix — all three are Mintlify built-ins and already live on this site (verified: docs.summerengine.com/llms.txt 200, llms-full.txt 200, .md suffix 200 on existing pages). No config change needed; nothing added that could go stale. Note: the .md suffix is served by Mintlify's production infra — mint dev does not serve it locally.

Honesty rule applied throughout: upload/publish/review/download are described as live; browser play, desktop shell play, hosted Fly game servers, the automated runtime sandbox, and SummerMultiplayerPeer are labeled precisely as not yet available. No page promises undeployed capability.

Validation

• node scripts/check-docs.mjs — PASS, 0 errors (3 pre-existing orphan warnings, untouched).
• npx mint broken-links — no broken links.
• mint dev — /agent-setup, /agent-setup/prompt, and the rewritten reference all render 200.

Walkthrough report — following the prompt as a naive fresh agent

Method: extracted every fenced code block out of agent-setup/prompt.mdx mechanically (what a copying agent does), reconstructed the project from those blocks alone in a clean directory, and ran the prompt's own commands in order. Live API contact restricted to a handful of unauthenticated expected-401 probes; no credentials, no accounts, no sign-ins.

Breaks found and fixed (docs iterated until only the credential wall remained):

1. super._process(delta) parse failure (template verification round). The documented SummerGame pattern calls super._process(); a stub without _process makes Godot refuse the script — the whole template dies at step 5b. Fixed: the shipped stub defines _process. This would have killed every naive follower.
2. Clean banned-API grep exits non-zero (walkthrough round). Step 5c's pass state is empty output, but grep exits 1 on no matches — an exit-code-checking agent reads success as failure. Fixed: the prompt now states the pass condition explicitly.
3. Unbound $SHA256 / $SIZE_BYTES (walkthrough round). Step 6 referenced variables step 5 never set. Fixed: step 5 now captures both.
4. Misleading 401 hint on POST /api/games/engine (probe round). Its 401 detail says only "Sign in and retry with the session cookie" — no mention of the Bearer token the endpoint accepts, which is the only option an agent has. Docs-side mitigation shipped (the prompt pre-arms agents); API-side fix reported below.

Verified working, from prompt-extracted files alone, Godot 4.5.1 stable:

• 5a import: exit 0 · 5b headless smoke run: exit 0, hooks fire, no SCRIPT ERROR · 5c self-check: clean · 5d --export-pack: exit 0 without export templates installed — game.pck = 10 536 bytes, only game files + manifest.json inside, sdk/* stubs excluded, GDScript shipped as readable text.
• Runtime-contract cross-check against summercraft-desktop core/game_loader.gd: pack loaded with load_resource_pack(path, false) (runtime files win, so the pck's stub class-cache is inert), manifest found at pack root, entry_scene resolved relative to the manifest, entry root must be SummerGame — all consistent with what the prompt produces.

The credential wall (expected, documented, stopped there):

• POST /api/games/engine with no auth, with an empty Bearer header, and with a present-but-invalid Bearer token → all 401 {"error":"sign_in_required", …}. The invalid-token case confirms the documented hard-401 (no cookie fallthrough). upload-url and download-url unauthenticated → 401 with hints that do name the access-token option.
• What the naive follower needs at the wall, exactly: a Supabase access token extracted by their signed-in human (dev tools → sb-…-auth-token cookie → access_token; documented on /agent-setup), passed as SUMMERCRAFT_ACCESS_TOKEN, valid ~1 h.

Not verifiable without credentials (stated, not assumed): the 2xx response bodies of engine/upload-url/finalize/download-url as deployed (documented from route source + docs/API.md), R2's 412/403 SignatureDoesNotMatch behavior on the presigned PUT, and the end-to-end review round-trip. One structural note: docs.summerengine.com/agent-setup/prompt.md goes live when this merges — the paste block tells agents to stop and report if the URL is unreachable.

API-side defects found (API repo not in scope this session)

1. POST /api/games/engine 401 hint omits Bearer. src/app/api/games/engine/route.ts returns "Sign in and retry with the session cookie." while the release endpoints' shared HINTS.sign_in_required says "…or a Supabase access token." The endpoint accepts Bearer (defaultGetUserId). For an agent-first funnel the error text is the documentation — suggest reusing the shared hint.
2. No first-class token surface for agents/CI. The only way a creator can hand an agent a token is scraping the Supabase auth cookie from dev tools (now documented, ugly). The funnel's conversion bottleneck is exactly here — a /creator "API token" panel (or CLI device-code flow) would remove the one manual step left in the loop.
3. Product gap, not a bug: approved engine releases are downloadable but not playable on any live surface; the docs label this precisely, but the funnel's payoff ("publish → people play") lands only when a play surface ships.

Could not verify

• Authenticated-path response bodies as deployed (above).
• Whether the /submit browser page's Railway backend enforces shapes beyond what its client code and the existing docs state (kept existing documented behavior; no unauthenticated probing beyond one expected-401).
• Mintlify production rendering of the two new URLs (site deploys from main; local mint dev render verified).

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.