AGENTS.md: the context an agent starts from (#379)

ddiff --git a/AGENTS.md b/AGENTS.md
nnew file mode 100644
iindex 0000000..fe032d3
---- /dev/null
++++ b/AGENTS.md
@@@ -0,0 +1,169 @@
++# AGENTS.md — OpenVibe.Games
++
++## Project Overview
++
++OpenVibe.Games hosts the browser games at `openvibe.games` and `play.openvibe.games`: **Scraplandia** (a persistent
++multiplayer physics sandbox with the scored "Haul" mode), **Salvage Rush** (on-foot timed collection),
++**creator worlds** (map editor + `/worlds`, sandboxed), the casual line (plan T22, starting with **Vibe Heroes**),
++server-run AI draft matches/Bench scoring, and the moved **OpenVibe.Play player pages** (`/achievements`,
++`/leaderboards`, `/developers`) which read Play's public API server-side.
++
++- **Domain:** `openvibe.games`, `play.openvibe.games` · **Port:** 8000 (server; Vite dev client 5173) ·
++  **Service id:** `games` · **Env prefix:** `GAMES`/`OV_`
++- **Stack:** TypeScript everywhere, pnpm 10 monorepo, Babylon.js (WebGPU/WebGL) client, Rapier
++  `@dimforge/rapier3d-deterministic-compat` (one pinned build headless on server and in client prediction), WS
++  protocol, PostgreSQL 18 + Valkey through `openvibe-sdk`, QuickJS for script mods.
++- **Read first:** [README.md](README.md), [ARCHITECTURE.md](ARCHITECTURE.md), [ROADMAP.md](ROADMAP.md),
++  [docs/games.md](docs/games.md), [docs/casual.md](docs/casual.md), [docs/mods.md](docs/mods.md),
++  [docs/instances.md](docs/instances.md), [docs/ai-matches.md](docs/ai-matches.md), [ADR-0007](docs/adr/), [ADR-0013](docs/adr/).
++
++**Network context:** players are keyed by Network `subject_id` (`usr_…`/`gst_…`); SSO/JWKS/identity/mod grants are
++OpenVibe.Network. Events are OpenVibe.Events (transactional outbox). Achievements/scores go to OpenVibe.Play's API;
++six built-in achievements grant Live items through OpenVibe.Inventory. Map-editor assets are also copied to
++OpenVibe.Media objects. Mod grants' authority is Network (`mods.grant.manage`); Games runs its own bounded
++`games-quickjs@1` scripts. The platform boundary is `apps/server/src/platform` and `apps/server/src/mods`; the
++simulation packages do not know the platform exists.
++
++## Commands
++
++```bash
++corepack enable && pnpm install          # Node ≥22, pnpm 10.6.5
++pnpm dev                                 # server + client dev in parallel
++pnpm dev:server                          # authoritative server on :8000 (tsx watch)
++pnpm dev:client                          # client hot reload on :5173 (proxies /ws to :8000)
++pnpm test                                # all vitest files through test/run.js
++pnpm typecheck                           # strict TypeScript across every package
++pnpm lint                                # ESLint (no-explicit-any)
++pnpm format                              # Prettier write (format:check in CI)
++pnpm build                               # all packages + client bundle
++node test/run.js --index                 # regenerate the flat test/*.test.js pointers after adding/moving a test
++tsx apps/server/scripts/sliceTest.ts     # end-to-end vertical slice: real server, protocol clients, restart
++pnpm test:editor | test:collab | test:console   # e2e Playwright checks (editor, collaboration, console)
++pnpm audit:editor                        # editor architecture audit (vitest config)
++```
++
++Production: `pnpm build`, then `DATABASE_URL=… DATABASE_DIRECT_URL=… STATIC_DIR=apps/client/dist PORT=8000 pnpm
++--filter @openvibe/server start`. `DATABASE_URL` serves through PgBouncer; migrations run at boot on
++`DATABASE_DIRECT_URL` (owner, direct); without both and outside production, PGlite under `DATABASE_DIR`.
++
++## Architecture at a Glance
++
++- **Server entry:** `apps/server/src/main.ts`; authoritative simulation, networking, persistence, platform boundary
++  ([apps/server/src/platform](apps/server/src/platform)), mods ([apps/server/src/mods](apps/server/src/mods)),
++  maps, worlds, casual, AI matches, Steam lists, observability.
++- **Client:** [apps/client/](apps/client/) — rendering, prediction, input, HUD, the map editor (`src/editor/`), e2e
++  scripts; Babylon is imported **only** here.
++- **Packages:** [packages/shared/](packages/shared/) (math, ids, events, logging, fixed timestep),
++  [packages/protocol/](packages/protocol/) (versioned wire messages, zod-validated inbound),
++  [packages/content/](packages/content/) (data-driven items/recipes/worlds + validation registry),
++  [packages/gameplay/](packages/gameplay/) (pure inventory/crafting/movement/zones/entities),
++  [packages/physics/](packages/physics/) (abstraction + Rapier adapter),
++  [packages/persistence/](packages/persistence/) (DTOs, repositories, PostgreSQL, migrations),
++  [packages/casual/](packages/casual/) (casual rules/auto-battle/Vibe Heroes, engine-free).
++- **Dependency graph (ARCHITECTURE.md):** shared → protocol/content/physics → gameplay → persistence → apps; only
++  `apps/server` and `packages/persistence` know PostgreSQL; `packages/*` never import browser-only APIs.
++- **Simulation:** 30 Hz fixed tick, 15 Hz snapshots; kinematic Source/Quake controller, client prediction + rewind +
++  interpolation; physics sleep is first-class (settled props cost nothing on the wire).
++- **Data:** [packages/persistence/migrations/](packages/persistence/migrations/) (23 migrations: characters, world,
++  props, instances/leases, progress, hauls, inventory rewards, casual, Play sync, telemetry, creator worlds/scripts/
++  teams/assets, surf, AI matches, sharing, outbox). A write-behind flusher means the tick never awaits I/O; SIGTERM
++  drains it.
++- **Pages:** `/` (portal; on play.openvibe.games `/` is the game), `/play`, `/editor`, `/worlds`,
++  `/achievements`, `/leaderboards`, `/developers`, `/play/vibe-heroes`, `/healthz`, `/api/ready`, `/metrics`.
++- **Deploy:** [deploy/openvibe-games.service](deploy/openvibe-games.service) (PORT 8000, HOST 127.0.0.1,
++  `/etc/openvibe/games.env`, `GAMES_MIGRATIONS_DIR`, `MAP_PATH`, `STATIC_DIR`, `TRUST_PROXY=127.0.0.1`,
++  `TimeoutStopSec=30`), [deploy/nginx-openvibe-games.conf](deploy/nginx-openvibe-games.conf),
++  [deploy/scripts/deploy.sh](deploy/scripts/deploy.sh) wrapping `ovhost deploy games` (strategy `pnpm-build`:
++  `pnpm install --frozen-lockfile`, `pnpm build`, restore tracked `dist-types/`, restart). `--wait-idle` holds the
++  restart until nobody plays; `DRY_RUN=1` prints `ovhost plan games`; rollback `sudo deploy/scripts/deploy.sh
++  --rollback` (rebuilds the previous commit).
++
++## Ownership and Boundaries
++
++Games owns the authoritative simulation (world, characters, inventories, skills, blueprints, props), the
++write-behind persistence schema, the map editor and its assets, the mod registry/content/script sandbox and its audit,
++the `games.*` events, the WS protocol and the portal/play/editor pages, the casual kit and its server economy, creator
++worlds, AI draft matches, and the moved Play player pages. It does **not** own identity (Network subjects), files
++beyond the local copy (Media mirrors), event delivery (Events), Play's service/API (Play), Inventory items (Inventory),
++or general-purpose executable mods (Host Stage C; Games' QuickJS scripts are bounded and approved per install).
++
++## Platform Integration (the boundary)
++
++- **Identity:** a signed-in player is the token's `subject_id`; a token without one cannot name an account, and a
++  guest token that looks like `usr_…` is refused. Never key a row on a display name.
++- **Service principal:** calls to Events/Media/Network identity/Inventory/Play carry a client-credentials token for
++  the `games` client, one per audience. No shared keys. SSO calls for a player use the player's own token.
++- **Events:** `games.player.joined|left`, `games.skill.leveled`, `games.blueprint.unlocked`, `games.world.saved`
++  (≤1 per `WORLD_SAVED_EVENT_MINUTES`, plus shutdown), `games.mod.installed|enabled|disabled|grants_changed|revoked`.
++  Achievements are **not** events: an unlock is stored in Games and sent to Play; the six inventory-bearing
++  achievements grant through Inventory and retry on failure.
++- **Play:** `GAMES_PLAY_URL` (unset = scores/unlocks stay local); Play is the network-wide read surface.
++- **Media:** only map-editor assets (textures, paint masks, glb) are uploaded; a restart-safe `media_mirrors` queue
++  copies them to the `games` tenant. There is no screenshot/blueprint upload.
++- **Mods:** manifests follow `[email protected]` validated against the installed Contracts (pin drift is a
++  defect); `games-content@2` packs merge definitions at boot, the client sends its definition digest in `hello` and the
++  server rejects a mismatch; each install stores the approved subset of requested capabilities, every runtime binding
++  checks it, revocation stops affecting the world on the next tick, and install/grant/use/deny/revoke are audited.
++  `games-quickjs@1` runs only with `GAMES_SCRIPT_MODS=1` in a per-mod QuickJS sandbox (defaults `cpuMs` 2/tick,
++  `memoryMb` 8, `stackKb` 128; over budget disables the mod for the instance).
++- **Frame:** the portal/play/editor load the OpenVibe Frame from this server's own `/shared/` copy, so it keeps its
++  frame while Network is down. `GET /api/v1/platform` reports events/Media-mirror state and backlog without secrets.
++
++## Capabilities and Grants
++
++Implemented: `games.mod.manage`, `games.mod.read` (mods API), `games.world.announce`, `games.prop.place`,
++`games.def.define` (declarative packs), and for script packs `games.script.run`, `games.players.read`,
++`games.player.message`, `games.world.emit`, `games.storage.kv`. Script bindings are absent unless approved for that
++install. The `games` principal needs `inventory.item.grant`, `events.event.publish|subscription.manage`,
++`media.object.upload` (namespace `games`), `identity.subject.resolve`, `network.modules.write` on
++`games.progress.summary`, and Network's `mods.grant.manage`.
++
++## Conventions and Pitfalls
++
++- **The server is the game.** Every gameplay-relevant decision is server-simulated/validated; no client field is
++  trusted; inbound messages are zod-validated and flood-controlled.
++- **Do not import Babylon into `apps/server`** (the architecture audit fails) or platform modules into `packages/*`;
++  keep gameplay engine-free and deterministic (same Rapier build on both sides).
++- **Data-driven content:** add definitions in `@openvibe/content`, validate at startup; stable ids, display names are
++  cosmetic. A new built-in pack must not bypass the capability check.
++- **Migrations** are `packages/persistence/migrations/NNNN_*.sql`, applied at boot with the owner URL; never edit one
++  that has run. The tick never awaits I/O — write-behind, then drain on SIGTERM (30 s stop timeout).
++- **Instances/leases:** PostgreSQL records each room and a renewable fenced lease; `GAMES_INSTANCES_PER_PLACE` only
++  within one process, `GAMES_CREATOR_WORLDS_MAX` caps creator worlds, empty ones stop after the idle timeout. A lease
++  that is lost must stop the place (old failure: five places lost leases in one night).
++- **`TRUST_PROXY`:** unset means the TCP peer is the client and all forwarded headers are ignored (otherwise a caller
++  mints fresh rate-limit buckets); behind nginx it is `127.0.0.1`, and nginx overwrites the headers from
++  `$remote_addr`. Never read `X-Forwarded-For` directly.
++- **Static serving:** an unknown path is a 404 (HTML page, `{"error":"not_found"}` under `/api`, plain text for a
++  missing asset), never the portal with 200. `/api/ready` is 200 only while the database answers a real round trip.
++- **Test pointers:** after adding/moving a `*.test.ts`, run `node test/run.js --index`; a missing/stale flat pointer
++  fails the suite. Vitest reads the real colocated file.
++- **Build:** pnpm's `onlyBuiltDependencies` is `esbuild`; Corepack downloads pnpm with Node's fetch in CI (the image
++  bakes it). `pnpm install --frozen-lockfile` and a clean `pnpm build` are the deploy gate.
++- **nginx** keeps `/api/ready` off the public vhosts; `/metrics` answers loopback only. Secrets
++  (`OV_OAUTH_CLIENT_SECRET`, `GAMES_EVENTS_SECRET`, `OV_NETWORK_AUTH_URL`) live in `/etc/openvibe/games.env` by name
++  only.
++- **Play's old pages 301 here:** do not re-add `apps/server` player pages under play.openvibe.network; the service and
++  API stay there.
++- Phone first for casual/portal pages; no Font Awesome; "Calm reduces, only Off removes".
++
++## Testing
++
++`pnpm test` runs every vitest file through [test/run.js](test/run.js) (package and server units incl.
++`apps/server/src/game/platformIntegration.test.ts`, which boots the real server twice on one database, and the
++architecture audit). `pnpm typecheck`/`pnpm lint` keep strict TS and no `any`; `tsx apps/server/scripts/sliceTest.ts`
++drives protocol clients across a restart; `pnpm test:editor|test:collab|test:console` are Playwright e2e checks. Run
++the narrowest file first, then the suite.
++
++## Documentation
++
++- [README.md](README.md) — purpose, owns, does-not-own, depends on, layout, development, commands, production,
++  platform integration, capabilities, tests, security.
++- [ARCHITECTURE.md](ARCHITECTURE.md) — principles, package graph, simulation, networking, server systems, persistence,
++  platform boundary, zones, entities, observability, security posture.
++- [ROADMAP.md](ROADMAP.md), [docs/games.md](docs/games.md), [docs/casual.md](docs/casual.md),
++  [docs/MAP_EDITOR.md](docs/MAP_EDITOR.md), [docs/EDITOR_COMPLETION_STATUS.md](docs/EDITOR_COMPLETION_STATUS.md),
++  [docs/instances.md](docs/instances.md), [docs/mods.md](docs/mods.md), [docs/ai-matches.md](docs/ai-matches.md),
++  [docs/platform-direction.md](docs/platform-direction.md), [docs/adr/](docs/adr/),
++  [docs/capabilities-proposal/](docs/capabilities-proposal/), [docs/service-manifest-proposal.json](docs/service-manifest-proposal.json).
++- [SECURITY.md](SECURITY.md), [.env.example](.env.example), [CHANGELOG.md](CHANGELOG.md).
ddiff --git a/CLAUDE.md b/CLAUDE.md
nnew file mode 100644
iindex 0000000..43c994c
---- /dev/null
++++ b/CLAUDE.md
@@@ -0,0 +1 @@
+[email protected]