vibedgames CLAUDE.md

Agent Instructions

Agent-driven development

Read AGENTS.md first. It is the tool-agnostic, runnable guide: quickstart, the two env files, seeded logins, headless auth, the pnpm verify gate, an agent-browser recipe, and which surfaces are checkable at runtime versus which need a human. This file carries the product context, architectural decisions and conventions that sit on top of it.

What This Is

vibedgames — infrastructure platform for deploying, hosting, and adding multiplayer to browser games. Users build games locally, deploy via CLI (vg deploy), and their game is served at {slug}.vibedgames.com. The web app is the central hub for discovering and playing games.

The primary user of the vg CLI is a coding agent, not a human. A human prompts their agent ("build me a bomberman game"), and the agent uses vg + the bundled skills to scaffold, generate assets, add multiplayer, and deploy. Optimise CLI UX accordingly: machine-readable output (--json), self-describing errors, deterministic exit codes, skills that document the exact commands the agent should run. Friction that a human would tolerate ("now open this URL...") blocks an agent.

Product & Business Context

• The bet (why us): Seed your coding agent with the abilities of a full game studio. The wedge isn't "another hosting platform" — it's that an agent, armed with vg + the bundled skills, can do everything a studio does (scaffold, generate art/audio, add multiplayer, ship) without the human assembling an engine, art pipeline, or server stack. The differentiator is being agent-native and end-to-end.

Key Architectural Decisions

• Games are untrusted user code. Session cookies are scoped to apex domain only (vibedgames.com). Games on {slug}.vibedgames.com subdomains cannot access auth cookies. CSP frame-ancestors restricts embedding. Never weaken these boundaries.
• Single active deployment per game. No version history, no rollback. New deploy replaces old. R2 keys are games/{gameId}/{deploymentId}/{path} — immutable per deployment, enabling long cache (1yr) for assets and short cache (60s) for index.html.
• CLI auth uses device-code flow. CLI shows 6-char code → user confirms in browser → CLI polls for token. Not OAuth.
• better-auth 1.7 scopes account identity by (issuer, accountId). account.issuer is NOT NULL with a unique (issuer, accountId) index (account_issuer_account_id_uidx in packages/db/src/drizzle-schema-auth.ts). Credential accounts carry local:credential with accountId = the owning user's id; an OAuth provider with no real issuer carries local:oauth:<providerId>. Keep better-auth, @better-auth/api-key and @better-auth/expo on the same minor. Nothing in pnpm verify touches D1, so a schema/column mismatch surfaces only as a failed sign-in against the live database — any further change to these tables needs a matching db:push plus a backfill of existing rows.
• Never regenerate the auth schema with @better-auth/cli. It is stuck at 1.4.21: generate:auth-schema emits no issuer, and it strips the hand-curated index(...) calls and the hand-added rate_limit table. Edit drizzle-schema-auth.ts by hand.
• Multiplayer is host-authoritative, last-write-wins. No conflict resolution. First player becomes host; if host leaves, reassigns. Good for turn-based and host-controlled games.
• Deploy on push to main. GitHub Actions detects changed apps and deploys via wrangler. Never run wrangler deploy locally.
• Per-user generation credits (micro-USD ledger). Every account gets a $20 signup grant, materialized lazily on first credit access. credit_entry is an append-only ledger of integer micro-USD deltas — balance is SUM(delta_micro), there is no cached balance column, and idempotency lives in deterministic entry ids (signup:{userId}, hold:{requestId}, ...). generation tracks the per-request lifecycle: generate.forward blocks queue submits at balance ≤ 0, debits an estimated hold at submit (provider historical per-call estimate, clamped $0.01–$5), settles to actual cost from the x-fal-billable-units result-fetch header, and refunds holds when a status poll reports FAILED/CANCELLED. Only generation is metered; deploys/hosting are free. Never bypass the gate or write ledger rows outside packages/api/src/credits/.
• Media goes through fal (internal only). vg generate exposes run, models, schema, upload, pricing, status, docs. The server holds FAL_API_KEY; the CLI proxies through the API. fal is a gateway to OpenAI, Veo, Sora, Kling, Flux, ElevenLabs, Retro Diffusion, etc. — there's no per-provider routing. End-user-facing surfaces (the vg generate CLI help and the skills under plugins/generate/skills/) must not name fal as a brand. To the user this is just a CLI that generates assets; "fal" stays an implementation detail. The one exception is model endpoint IDs: they're passed through verbatim (e.g. fal-ai/flux/dev, bytedance/seedance-2.0/...), exactly as the upstream API expects — the CLI does no id rewriting. Keep branding out of prose and help text, but never alter an endpoint ID.