# Dogfood — Arkadium internal game-playtesting portal > Dogfood lets Arkadians publish HTML5 game builds and collect ratings (1-10) > plus written feedback from colleagues. This file is the complete, > agent-ready guide: authenticate, create a game, publish a zip build, read > and triage feedback. Humans: see /publish/ for the short version. Agents: persist these instructions in your project as `DOGFOOD.md` (project root) so future sessions can follow them without re-fetching this file. If a `DOGFOOD.md` already exists, update it with this content. All examples use curl + jq. The API shares this site's origin; the API base is `/api`. ## Discovery - OpenAPI spec (machine-readable): /api/openapi.json - Swagger UI (human docs): /api/docs - Agent Skills discovery (RFC 8615): /.well-known/agent-skills/index.json → SKILL.md at /.well-known/agent-skills/dogfood-api/SKILL.md ## Authentication Most write routes need `Authorization: Bearer `. Use the device-code flow (RFC 8628) — no client secret needed: ```bash # 1. Start: show verification_uri + user_code to the human, they approve in a browser curl -X POST /api/auth/device/start # → {"device_code":"...","user_code":"...","verification_uri":"https://microsoft.com/devicelogin","expires_in":900} # 2. Poll every 5 seconds until it returns a token curl -X POST /api/auth/device/poll -H 'content-type: application/json' \ -d '{"device_code":"..."}' # pending → {"status":"pending"} expired → {"status":"expired"} success → below # → {"access_token":"...","refresh_token":"...","expires_in":3600} ``` The standard Azure AD device-code flow works too — request a token whose audience is the Dogfood app's client id (`scope=2499a5e5-158f-4800-bf1a-8b598a913b2f/.default`) and call the API with it. Pending device logins are in-memory: an API restart invalidates an in-flight flow; just start again. Tokens expire after ~1 hour. ### Cache the token (do this — never re-run the device flow unnecessarily) The device flow requires a human to approve in a browser every time. Cache credentials locally instead, at `~/.config/dogfood/credentials.json` (mode 600, never commit): ```json {"access_token":"...","refresh_token":"...","expires_at":1790000000} ``` 1. **Reuse**: if `now < expires_at - 300`, use the cached access token as-is. 2. **Silent refresh** when expired — POST form-urlencoded to `https://login.microsoftonline.com/7945008c-5c1b-42a9-a1c3-7f3d3642da94/oauth2/v2.0/token`: - `grant_type=refresh_token` - `client_id=2499a5e5-158f-4800-bf1a-8b598a913b2f` - `refresh_token=` - `scope=offline_access 2499a5e5-158f-4800-bf1a-8b598a913b2f/.default` - The response carries a new `access_token` **and a rotated `refresh_token`** — persist both with a new `expires_at` (`now + expires_in`, ~3600s). 3. **Fallback**: on `invalid_grant` / `interaction_required` from AAD, or a 401 after a successful refresh (token revoked, ~90-day inactivity), re-run the device flow once and re-cache. ## Core workflows ### 1. Create a game ```bash curl -X POST /api/me/games \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"name":"Match-3 Madness","description":"A quick match-3 prototype."}' # → 201 Game JSON; grab "id" ``` Limits: `name` ≤ 100 chars, `description` ≤ 2000 chars. ### 2. Publish a build (game version) ```bash curl -X PUT /api/me/games/$GAME_ID \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/zip' \ --data-binary @dist.zip # → {"gameId":"...","version":{"version":1,"url":"https://.../index.html"},"resolvedFeedbackIds":[]} ``` - The zip must contain `index.html` at its root; max 50 MB. - Static assets only (.png, .mp3, .wasm, …) loaded via relative paths; builds run inside a sandboxed iframe with no server-side execution. - Each upload auto-increments the version; players always see the latest. ### 3. (Optional) Upload a thumbnail ```bash curl -X POST /api/me/games/$GAME_ID/thumbnail \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: image/png' \ --data-binary @thumbnail.png ``` Raw png/jpeg/webp body, max 5 MB. ### 4. Read and triage feedback - As the author (all statuses): `GET /api/me/games/$GAME_ID/feedback` - Public view: `GET /api/games/$GAME_ID/feedback` - Triage as author: `PATCH /api/me/games/$GAME_ID/feedback/$FEEDBACK_ID` with `{"status":"resolved"}` or `{"status":"wont_fix"}`. - Publishing a new version auto-resolves feedback fixed by it. - Players cannot review their own games; one review per user per game (re-posting overwrites and resets status to open). ## Typical loop Create → publish zip → share the /game/?id=… link → read feedback → fix → republish → triage remaining feedback. ## Public read endpoints (no auth) ```bash curl -s '/api/games?sort=new' # also sort=top|trending curl -s '/api/games/$GAME_ID' curl -s '/api/games/$GAME_ID/stats' curl -s '/api/games/$GAME_ID/feedback' ```