# AGENTS.md — building an AikaHub game

Guide for AI coding agents (Claude, ChatGPT, Copilot, Cursor, …) that help someone build a game for AikaHub
(https://aikahub.com). Copy it into the game's folder. Every AikaHub starter game already has its own AGENTS.md that knows that
game's files — prefer that one inside a starter project; this file is the general version.

The owner is probably a beginner. Keep changes small, explain in plain words what you changed and why, keep the game
runnable after every step, and keep comments in the language the project already uses.

## What AikaHub gives a game

Through **@aikahub/sdk 1.5.0** (ESM, no dependencies): "Log in with AikaHub" (OAuth 2.0 + PKCE S256, handled by the
SDK), the member's profile (`me()`: sub, nickname, avatarUrl, level — never an email), their 3D VRM character
(`character()`), achievements (`unlock(key)`), entitlements, cloud saves (`cloudSave()`), leaderboards (`scores`),
visits with preset gifts (`visits`) and "playing now" presence (`presence`). Full reference: https://aikahub.dev/docs/sdk/ —
everything as one text file: https://aikahub.dev/llms-full.txt

## Loading the SDK

Pin the exact version and check integrity with an import map (hashes: https://aikahub.com/sdk/1.5.0/manifest.json), or copy the
file into the game (`vendor/`), which is what the starter games do:

```html
<script type="importmap">
{ "imports": { "@aikahub/sdk/browser": "./vendor/aikahub-sdk/1.5.0/browser.js" } }
</script>
<script type="module" src="./src/main.js"></script>
```

```js
import { createClient } from '@aikahub/sdk/browser';

const hub = createClient({ clientId: 'x-my-game', redirectUri: location.origin + '/', scopes: ['profile', 'achievements'] });
loginButton.addEventListener('click', () => hub.login({ returnTo: '/' }));
await hub.handleCallback();            // on the redirect page: checks state, exchanges the code
const me = await hub.me();
await hub.unlock('first-win');         // idempotent: a repeat gives { new: false, xp: 0 }
```

Never use `/sdk/v1/…` with an `integrity` hash (v1 moves); never load the SDK or any library from a URL without an exact
version.

## Rules — do not break these

1. **No secrets in browser code.** The server key (`ahk_…`) lives only on the game's own server (secret store or a
   git-ignored `.env.local`). Only its SHA-256 is uploaded in the Developer console. Never import `@aikahub/sdk/server`
   from browser code.
2. **Tokens stay in memory** (the SDK default). Do not write tokens to localStorage, cookies or logs; do not pass
   `storage: 'session'` unless the owner asks and understands the XSS trade-off. Never log `sub`.
3. **Achievements:** keys are 2–40 chars of `a-z 0-9 -`, each one must be declared (console or `aikahub.config.json`).
   `client` trust (unlocked from the browser): at most 50 XP each, never legendary, at most 50 achievements and 450 client
   XP per game. Valuable ones (`server` trust, up to 250 XP, legendary) only from the game's server with the key.
4. **Ask only for the scopes the game uses** — the member sees every scope on the consent page. Presence is sent only from
   the member's own client while they are actually playing.
5. **Handle errors**: every SDK error is an `AikaHubError` (`code`, `status`, `final`). `final: true` → do not retry.
   Use the server retry queue (`hub.queue()`) for server unlocks.

## If the game is published from AikaHub Studio (g-<slug>.aikahub.dev)

The game is served as static files with exactly this Content-Security-Policy (the Studio preview uses the same one):

```
default-src 'self'; script-src 'self' 'wasm-unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://aikahub.com; media-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' https://aikahub.com; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; form-action 'self' https://aikahub.com; frame-ancestors 'self' https://aikahub.com
```

So:

- **No inline `<script>…</script>`** — put code into `.js` files. The only allowed inline script is the import map
  (allowed by its exact SHA-256, computed at upload). `<script type="application/json">` data blocks are fine.
- **No inline event handlers** (`onclick="…"`, `onload="…"`): they silently do not run. Use `addEventListener`.
- **No remote scripts, styles, fonts or images**: copy libraries into the game with a pinned version. `connect-src` allows
  only the game itself and https://aikahub.com. No `eval` / `new Function` (WebAssembly is allowed).
- **No service worker and no cookies** (the SW script request is refused). Save locally in `localStorage`, or use cloud saves.
- Limits: 25 MB per release, 600 files, 16 MB per file, 100 HTML files.
  Allowed file types: html, js, css, json, png, webp, jpg, svg, mp3, ogg, wav, glb, vrm, txt, md, woff2, woff, ttf, otf, wasm, ktx2, hdr, bin.
  Folders that are never uploaded: server/, tools/, mock-hub/, node_modules/, __aikahub/, __studio/. No dotfiles.
- Only the AikaHub may frame the game (`frame-ancestors 'self' https://aikahub.com`).

## If the game is hosted elsewhere

The owner registers it in the Developer console (https://aikahub.com/developers/console): accept the Developer Agreement, create a
client (`x-` id), add exact redirect URIs (`http://127.0.0.1/` works for local development, any port), add up to 5
testers by nickname, optionally upload the server key's hash, fill in the Playground page (name, short description,
cover 16:9, operator name and country, privacy notice URL) and submit. Until approved only the owner and testers can log
in, and achievements / scores are sandbox-only (no XP).

## Local development without an account

The starter games include a **Mock Hub** (`npm run dev`, test players, the same endpoints, JSON shapes and error codes as
the real Hub). `"hub": "mock"` in `aikahub.config.json` → Mock Hub; `"hub": "https://aikahub.com"` → the real Hub. Nothing else
changes. Run `npm run check` after every change.

## Contact

info@aika.hu — Developer Agreement: https://aikahub.com/developers/agreement — SDK License: https://aikahub.com/developers/sdk-license
