@crowdedkingdoms/crowdyjs 13.0.0 → 13.0.1

package/README.md

@@ -1,122 +1,34 @@
 # CrowdyJS
 
-The official browser-first TypeScript SDK for **Crowded Kingdoms**. CrowdyJS gives you typed clients for auth, the world/replication GraphQL API, and the UDP proxy subscription stream. As of **v7** it follows the Overworld two-token model: an identity **session token** for the Management API, and short-lived **app-scoped tokens** for gameplay via `client.portal` (see [Overworld portals & app-scoped tokens (v7)](#overworld-portals--app-scoped-tokens-v7)).
-
-> **CrowdyJS v13 (breaking): unified galaxy API.** The platform merged the
-> Management API and Game API into ONE server on the shared galaxy database
-> (`managementUrl` and `httpUrl` may be the same origin now; the two-token
-> model is unchanged). The schema is resynced from the unified SDL, and the
-> retired surfaces are removed: `client.environments` (dedicated customer
-> environments no longer exist), the per-environment usage rollups and
-> capacity tier catalogs, and everything on `client.operator` except the
-> platform compute ceilings (infra operations moved to the separate
-> infra-control-plane service). See [MIGRATION.md](MIGRATION.md).
+The official browser-first TypeScript SDK for **Crowded Kingdoms**. CrowdyJS
+gives you typed clients for the whole platform: passwordless identity and
+studio administration (the Management surface), world data and the abstract
+game model (the Game surface), and the UDP proxy realtime stream — all over
+one unified GraphQL API.
 
-## Install
-
-```bash
-npm install @crowdedkingdoms/crowdyjs
-```
-
-> **Renamed package, same version line.** This SDK moved to the `@crowdedkingdoms` npm org but **kept its v6 version line**. `@crowdedkingdoms/crowdyjs@6.1.1` continues directly from the former `@crowdedkingdomstudios/crowdyjs@6.1.0` — same code, new package name. (Two interim `1.0.x` publishes during the org move reset the version by mistake; they remain on npm but are superseded by `6.1.1`, which is `latest`.) See [MIGRATION.md](MIGRATION.md).
-
-CrowdyJS v4 targets browsers by default and uses native `fetch`, `WebSocket`, `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must provide browser-compatible globals when opening realtime connections.
-
-> **CrowdyJS v12 (breaking): Agentic Crowdy Studio.** v12 adds the accepted
-> `crowdy.studio-agent/1`, `crowdy.agent-tools/1`, and
-> `crowdy.player-host/1` browser contracts. Import the provider-neutral durable
-> client and immutable tool registry from
-> `@crowdedkingdoms/crowdyjs/agent`, and generic game observations/control from
-> `@crowdedkingdoms/crowdyjs/player-host`. Crowdy Studio can mount the
-> integrated Ask/Build/Play dock when given an injectable agent transport.
-> There is deliberately no OpenRouter key/client, raw GraphQL executor, DOM
-> driver, `fetch`, shell, unrestricted SDK bridge, or client-mod `host_call` in
-> these surfaces. The reconciled Game API SDL, generated operations, and
-> production `CrowdyAgentGraphQLTransport` are included and exposed as
-> `client.crowdyStudioAgent`; tests may still inject
-> `CrowdyStudioAgentTransportV1`. Existing manual Studio mounting remains
-> unchanged when `agent` is omitted.
->
-> **Server compatibility (v8.13):** v8.13 adds the **flow-correlation surface**: `gameModel.flow({ appId, flowId })` stitches one flow correlation id into a single cross-engine timeline (model events + automation runs + compute module runs, each time-ascending), and the default event/run fragments now select the nullable `flowId` field on `GmEvent` / `GmAutomationRun` / `WasmModuleRun`. Both require the 2026-07-19 `cks-game-api` dev line (the `2026-07-19-compute-fleet-hardening` migration for the columns and the `gameModelFlow` query for the timeline); older servers reject the operations with a GraphQL validation error, and everything else keeps working. `gameModel.flow` requires the app-admin `manage_apps` permission (it is a diagnostics surface). v8.13 also extends the kit invoke helpers' gameplay-verdict mapping: the typed invoke-contract violation `computeInvoke` raises (`BAD_REQUEST` with an "Invoke params violate ..." message, game-api 2026-07-19+) now maps onto `{ success: false, errorMessage }` (`kitInvoke`) / `{ success: false, reason }` (engine invokes) instead of throwing — see the exported `isKitVerdictError` predicate.
->
-> **Server compatibility:** v8.12's **container query predicates** (`where`/`limit`/`offset` on `gameModel.containers`), **automation compute actions** (`actionKind: 'compute_invoke'` with `computeModuleName`/`computeExport` on `gameModel.upsertAutomation`; `property_changed` events additionally carry `oldValue`/`newValue` to compute modules), **container-change push** (`gameModel.containerChanged` — metadata-only pull-on-push over graphql-transport-ws; on Node ≤ 21 pass `webSocketImpl`), and **invoke-trigger contracts** (`contractJson` on `compute.upsertTrigger`/`moduleTriggers`, validated server-side pre-sandbox) require the 2026-07 `cks-game-api` dev line with the `2026-07-19-automation-compute-action` migration; older servers reject the new arguments/fields (omit them and everything else keeps working). (npm 8.11.0 is a partial cut of this surface — prefer 8.12.0.) v8.12 also adds the `runOptimisticAction` kit helper (client-only: the packaged optimistic apply → referee invoke → confirm/rollback loop with actionId receipts). v5.2+ targets environments on release **v0.1.19 or later** (`cks-game-api >= v0.10.3`, `cks-management-api >= v0.1.70`). The destructive mutations send an `idempotencyKey` argument that older servers don't define. v6.1's `client.gameApps.deleteGrid` additionally requires release **v0.1.33+** (`cks-game-api >= v0.12.3`). The game-model **permission effects** fields (`permissionEffects` on `gameModel.upsertFunction`/`seed`, `permissionEffectsAppliedJson` on events) require a `cks-game-api` build with the `2026-07-17-model-permission-effects` migration (v0.13.11+); older servers reject queries/mutations that include them (omit the fields and everything else keeps working). The **permission-read** surface (the `has_grid_permission`/`grid_at`/`has_chunk_permission` expression builtins the kit's `chunkPermission` locks compile to, and selector `*PermissionWhere` predicates) additionally requires `cks-game-api` **v0.13.12+**. Older `cks-game-api` builds report game-model **invoke policy denials** as `FORBIDDEN` GraphQL errors instead of resolving with `success: false`; as of this version the kit's invoke helpers map that error onto the documented `{ success: false, errorMessage }` result, so kit callers behave identically against both server generations. v8.6's **`client.compute`** (Compute Modules — server-side Rust/WASM logic) requires a `cks-game-api` build with the compute surface (the `compute*` root fields, v0.13.13+ dev line); older servers reject these operations with a GraphQL validation error, and everything else keeps working. v8.9's **realtime + live-ops surfaces** (`kit.abilities`/`movement`/`territory`/`racing`/`liveops`/`moderation`/`telemetry`, the loot engine path, `client.compute.deployTemplate` + `kit.deploy({engines})`, and the type-94..98 event parsers) complete the 30-abstraction catalog; v8.8's **session-genre engine surfaces** (`kit.instances`/`director`/`matchmaking`/`minigames`, the engine paths on matches/decks/leaderboards, `economy.orderBook`, and the type-91/92/93 event parsers) talk to the Wave 2 engine templates; capability detection keeps model-only deployments on today's behavior. v8.7's **engine kit surfaces** (`kit.mobs`, `kit.pets`, `kit.combat.attackRouted`, `kit.worldsim.forecast`, and the `kit/wire` pose/lane registry) talk to compute-module game engines built on the Wave 0/1 `cks-game-api` dev line (`crowdy-game-kit` crates); capability detection makes them degrade gracefully — model-only deployments keep today's behavior.
->
-> **P1 player runtime compatibility:** `client.playerCompute`,
-> `client.playerModel` (owner/grid-confined flexible data + automations), first-class grid
-> ownership methods on `client.gameApps`, and app code-admission methods on
-> `client.apps` require the 2026-07-20 game-api/management-api player-runtime
-> schemas. Player-authorized one-chunk claims and owner release through
-> `marketplace.claimGridChunk` / `marketplace.releaseClaimedGrid` require the
-> corresponding 2026-07-22 Game API claim schema. Older servers reject only
-> those operations during GraphQL validation.
->
-> **App-scoped player-count compatibility:** `gameModel.activePlayerCount(appId)`
-> and `gameModel.activePlayerCountChanged({ appId }, handlers)` require the
-> matching 2026-07-24 Game API schema and an app token scoped to that exact app;
-> the subscription also requires `wsUrl`. They count active gameplay sessions,
-> not distinct users or actors, and an abandoned session can remain counted for
-> approximately 120 seconds. Only `FRESH` snapshots are complete:
-> `PARTIAL`/`UNAVAILABLE` are not authoritative zeroes. The subscription is
-> best-effort and has no initial event; establish it, query the snapshot,
-> deduplicate by `revision`, and requery after reconnects or revision gaps.
-
-> **v8.21.1 Node realtime routing hotfix:** app-routing responses provide a
-> WebSocket base URL. CrowdyJS now normalizes that base to `/graphql` before
-> constructing the realtime client; previously Node/bot clients connected to
-> the origin root and remained stuck in `connecting` with no notifications.
->
-> **Player-code authoring DX:** `playerCompute.setRequires`,
-> `marketplace.trustGridAuthor`, self-authored `gridClientMods` fields, and
-> version-keyed client artifact fetches require the 2026-07-22 authoring-DX
-> migration. The v11 `mountCrowdyStudio` surface is project-first: cloud project
-> revisions, target-scoped files, atomic autosave, and explicit draft/live/stop
-> orchestration. Its Rust language worker receives source plus the committed
-> platform index only—never a credential and never a server connection.
-> CrowdyJS 11 requires the matching Crowdy Studio Game API schema; the previous
-> package subpath, exports, client property, GraphQL roots, and schema types were
-> removed without aliases.
-
-> **v8.10 inventory authority:** generated craft/barter transactions work on
-> existing Model servers. Compute-refereed durable commits require Compute SDK
-> `0.1.3` / the `model_invoke` host call.
-
-## Standalone builds and schema refresh
-
-CrowdyJS is a standalone public package: a clean clone builds with
-`npm install && npm run build` using the schema artifacts committed to this
-repo — no other repositories and no network access required:
-
-- `schema.gql` — merged Management API + Game API SDL.
-- `src/generated/graphql.ts` — generated TypeScript operation types.
-
-Schema refresh (maintainers) is explicit, from the published SDLs
-([management-api.graphql](https://docs.crowdedkingdoms.com/schema/management-api.graphql),
-[game-api.graphql](https://docs.crowdedkingdoms.com/schema/game-api.graphql)):
+Authentication follows a two-token model: an identity **session token** for
+account and admin operations, and short-lived **app-scoped tokens** for
+gameplay, minted per app through `client.portal`.
 
-```bash
-npm run schema:sync:prod
-npm run codegen
-```
+Start here:
 
-(`npm run schema:sync:paths -- --management <file-or-url> --game <file-or-url>`
-accepts explicit sources.) Commit `schema.gql` and `src/generated/graphql.ts`
-together whenever the public GraphQL surface changes; `npm run check:schema`
-detects drift in CI/release work.
+- [SDK guide](https://docs.crowdedkingdoms.com/crowdyjs/readme) — the canonical
+  walkthrough of everything in this README.
+- [Build a game](https://docs.crowdedkingdoms.com/build-a-game/intro) — a
+  hands-on tutorial from sign-in to a playable voxel game.
+- [Platform overview](https://docs.crowdedkingdoms.com/overview/client-workflow)
+  — how a client session flows through the platform.
 
-The browser authoring index follows the same boundary. `npm run build` validates
-only the committed internal `src/live-coding/assets/browser-authoring-index.json` and its
-generated TypeScript copy; it never discovers or reads a sibling game-api
-checkout. Coordinated maintainers compare an explicitly supplied exporter path:
+## Install
 
 ```bash
-npm run authoring-index:drift -- --source /path/to/browser-authoring-index.json
-# To accept that exact source, then regenerate the committed TypeScript:
-npm run authoring-index:drift -- --source /path/to/browser-authoring-index.json --write
-npm run authoring-index:generate
+npm install @crowdedkingdoms/crowdyjs
 ```
 
-The drift command rejects a missing `--source`; cross-repository orchestration,
-not standalone package build or tests, owns that comparison.
+CrowdyJS targets browsers by default and uses native `fetch`, `WebSocket`,
+`crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must
+provide browser-compatible globals when opening realtime connections (e.g.
+pass `webSocketImpl` on Node ≤ 21 for subscriptions).
 
 ## Quick start
 
@@ -130,7 +42,7 @@ const client = createCrowdyClient({
   // Game API (world data + UDP proxy)
   httpUrl: 'https://game.example.com',
   wsUrl: 'wss://game.example.com',
-  // Management API (passwordless sign-in, profile)
+  // Management API (passwordless sign-in, profile, admin)
   managementUrl: 'https://management.example.com',
   tokenStore: new BrowserLocalStorageTokenStore(),
   realtime: {
@@ -155,390 +67,149 @@ const me = await client.users.me();
 console.log(me.email);
 ```
 
-**Gameplay needs an app-scoped token, not the session token.** Mint one per app and
-drive the Game API world/UDP surface (including `gameClientBootstrap`) from a
-per-game client — see [Overworld portals & app-scoped tokens (v7)](#overworld-portals--app-scoped-tokens-v7).
-
-If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-compat with the single-endpoint deployment.
-
-## Sub-clients at a glance
-
-**Game-client surface** (end-user, browser-safe):
-
-| Sub-client | What it does |
-|---|---|
-| `client.auth` | Passwordless sign-in (magic link, social/OIDC, dev bypass), log out, and linked identities (`myIdentities`, `linkIdentity`/`unlinkIdentity`). |
-| `client.users` | `me`, `updateGamertag`, profile reads. |
-| `client.session` | Token store, `restore()`, `getToken()`, manual `setToken()`. |
-| `client.serverStatus` | `gameClientBootstrap(appId)` — per-app version info, UDP status, spatial limits. |
-| `client.chunks`, `client.voxels`, `client.actors`, `client.avatars`, `client.state` | World data reads + writes. |
-| `client.host` | Game-host election (`get`, `amIHost`) + actor liveness `heartbeat`. `amIHost` is UI convenience only — authoritative host gating uses `gameModelInvoke`'s `is_host` policy. |
-| `client.teleport` | Teleport requests. |
-| `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
-| `client.gameModel` | Abstract game model: containers, properties, functions (incl. model-driven `notify_*` effects), sessions, **app-scoped active-session counts** (`activePlayerCount`, `activePlayerCountChanged`), and **automations / NPCs** (`upsertAutomation`, `runAutomation`, `automationRuns`, `automationStats`, …). |
-| `client.compute` | **Compute Modules** — server-side Rust/WASM logic: author + deploy source (`upsertModule`, `deployVersion`, `waitForCompile`), triggers + policy, synchronous `invoke`, and monitoring (`moduleRuns`, `moduleStats`, `moduleLogs`, `appDiagnostics`). Modules run server-only; see [Compute Modules docs](https://docs.crowdedkingdoms.com/game-api/compute-modules). |
-| `client.playerCompute` | Player-authored SERVER/CLIENT Rust/WASM bound to player-owned grids: deploy source, activate/deactivate, list modules/versions, and delete self-authored modules. |
-| `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, pairing preference, optimistic revisions, copy-by-value imports, and atomic metadata/file saves. Generated operations are pinned to the committed merged SDL. |
-| `client.crowdyStudioAgent` | Generated, app-token Game API transport for durable agent sessions, Relay history/session pages, descriptors/budgets, exact approvals, browser tool results, heartbeat, control mutations, and ordered event subscriptions. |
-| `client.playerModel` | Player-owned flexible model containers and grid-confined automations (`containers`, `createContainer`, `setProperty`, `automations`, `createAutomation`, …). |
-| `client.marketplace` | Player-code store/install/consent flows plus player-authorized grid claims: `claimGridOwnership` preserves the existing-grid policy flow, while `claimGridChunk` atomically creates and owns one chunk under `SELF_CLAIM` and `releaseClaimedGrid` releases an eligible owner-created claim. |
-| `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`). |
-| `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
-| `client.refreshGameplayToken()` | Safely rotates an active game client's app token: disconnects the old-token UDP proxy, refreshes/stores the token, and opens the new-token proxy while existing realtime handlers resubscribe in place. |
-| `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`). |
+The Management and Game APIs may share one origin or be split; if
+`managementUrl` is omitted, the SDK falls back to `httpUrl`.
 
-`PlayerCodeBroker` transfers
-compiled client artifacts to a platform-owned worker, keeps tokens on the page,
-allow-lists host calls, and locally clamps chunk-targeted effects to the owned
-grid before the normal SDK path reaches server authorization. Crowdy Studio
-hot-swaps only the exact version-keyed artifact returned after a successful
-CLIENT compile.
+**Gameplay needs an app-scoped token, not the session token.** Mint one per
+app and drive the Game API world/UDP surface from a per-game client — see
+[Authentication](#authentication-session-token-vs-app-scoped-tokens).
 
-## Crowdy Studio
+## Authentication: session token vs app-scoped tokens
 
-`mountCrowdyStudio` is the project-first SERVER/CLIENT Rust authoring surface. A
-project has one cloud revision, target-scoped files, project metadata, separate
-server/client module names, and a pairing preference. Full-stack edits autosave
-as one optimistic-concurrency write; the UI renders **Saving**, **Saved**,
-**Conflict**, or **Offline**, with retry and conflict-resolution actions.
+Passwordless sign-in returns an **identity session token** that works only
+against the Management API — account, studio admin, and token minting. Each
+game is entered with a short-lived **app-scoped token** confined to that one
+app, so a game stack never receives the player's full session.
 
-The mount fills its host and observes host element resizes, so games can embed
-it in draggable docks or split panes without manually relaying window resize
-events. Give the host an explicit width and height; Crowdy Studio relayouts
-Monaco and collapses secondary panes from its own container width.
+Use two clients: an Overworld/identity client (session token) and a per-game
+client (app token), sharing only the Management URL.
 
 ```ts
-import { mountCrowdyStudio } from '@crowdedkingdoms/crowdyjs/crowdy-studio';
-
-const studio = await mountCrowdyStudio(host, {
-  projectProvider: game.crowdyStudio,
-  playerCompute: game.playerCompute,
-  playerWallet: identity.playerWallet,
-  appId,
-  gridId,
-  grid,
-  workerUrl: playerCodeGlueWorkerUrl,
-  onHostCall,
+// Overworld/identity client
+const overworld = createCrowdyClient({
+  managementUrl,
+  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:session'),
 });
+// Passwordless sign-in (magic link, social/OIDC, or dev bypass) yields the session token.
+await overworld.auth.requestLoginLink({ email, redirectUri });
+await overworld.auth.completeLoginLink(tokenFromLink);
 
-// Stops editor/runtime polling, the Rust worker, and any client broker owned
-// by this mount. It does not implicitly disable a deliberately live server.
-studio.destroy();
+// Native / same-origin: mint directly, then build a game client.
+const t = await overworld.portal.mintAppToken(appId);
+const game = createCrowdyClient({
+  httpUrl: t.gameApiUrl!,
+  wsUrl: t.gameApiWsUrl!,
+  managementUrl,
+  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:app:' + appId),
+});
+game.setToken(t.token);
+game.world(appId).subscribe({ actorUpdate: (n) => { /* ... */ } });
 ```
 
-Use `new CrowdyStudioController(options)` for a custom/headless presentation. Its
-public edits are file operations (`addFile`, `renameFile`, `deleteFile`,
-`updateFile`) and project settings—there is no session-only source blob, fixed
-module name, or template JSON API. The deploy conversion to the Game API's
-legacy `sourceFilesJson` input happens only inside the controller's
-`playerCompute.deploy` call.
-
-The built-in UI provides a project switcher/new-project wizard
-(server/client/full-stack), target explorer, personal library/common files,
-tabs, settings, Problems/Build/Logs/Runs/Invoke panels, and explicit **Test
-draft**, **Deploy live**, and **Stop project** actions. Full-stack deployment is
-ordered: save once → compile CLIENT → compile SERVER → set/clear the pairing
-requirement only after both compiles → enable SERVER → hot-swap the exact
-version-keyed CLIENT artifact. Partial compile failures never write a new
-requirement. Stop always attempts both server disable and client/poll cleanup
-and reports each failure.
-
-Monaco uses target-prefixed model URIs (`.../server/Cargo.toml` and
-`.../client/Cargo.toml`) and opens every loaded project/library/common Rust file
-in one bounded local worker workspace. Completion, hover, symbols, and
-definition therefore work across loaded files; lifecycle snippets and hover
-notes distinguish SERVER platform execution from CLIENT broker host calls.
-Local tree-sitter markers are labeled advisory. Platform rustc output is parsed
-separately into authoritative path/line/column markers and remains visible in
-Build.
-
-The Rust worker receives source files and the strict embedded platform index
-only. It receives no credential, opens no socket/fetch path, and never falls
-back to a server language service. If Monaco, Worker, a WASM asset, or a custom
-platform index fails, the same Crowdy Studio mount keeps project/target tabs and
-uses one file-aware textarea—never a raw JSON blob.
-
-Modern bundlers must preserve module workers and package `.wasm` assets. Custom
-pipelines can pass `languageWorkerFactory` and `editorWorkerFactory`. The
-embedded index remains the byte-identical game export (`schemaVersion: 2`, Rust
-1.97.1, SDK 0.1.5, ABI 0, 725 symbols, content hash
-`3f5f39d4…18ffb`).
-
-### Embed Crowdy Studio in your game (v12.1)
-
-Most games should not hand-roll the window chrome around `mountCrowdyStudio`.
-The embed kit ships the proven Blocks with Friends shell as reusable, game
--agnostic components (exported from `@crowdedkingdoms/crowdyjs/crowdy-studio`):
-
-- **`createCrowdyStudioEmbed(options)` / `CrowdyStudioEmbed`** — a responsive
-  panel that renders a resizable right dock on desktop and a focus-trapped
-  fullscreen modal below 1000 px. It owns Escape/close-key semantics, the
-  compact header (title, grid pill, on-demand Context drawer, Close), loading
-  and retry chrome, and assembles the `mountCrowdyStudio` call — including the
-  agent block when the client exposes `crowdyStudioAgent` and the game passes a
-  `playerHost`.
-- **`CrowdyStudioEmbedDock`** — the accessible game/studio splitter with
-  persisted width (`ck:crowdy-studio:embed:dock-width:v1`), arrow-key/Home/End
-  resize, and ARIA value text.
-- **`CrowdyStudioTextHud`** — the text-only presentation sink for CLIENT-mod
-  `hud_set` payloads plus the drawer HUD preview. Untrusted payloads render as
-  text, never HTML.
-- **`ensureCrowdyStudioEmbedStyles()`** — injected `ck-crowdy-studio-embed-*`
-  styles; games restyle by overriding classes. While docked, the panel sets
-  `--ck-game-right-inset` on `document.body` so game HUDs can keep clear of
-  the dock.
+Browser cross-origin handoff is OAuth2 Authorization Code + PKCE — the
+verifier never leaves the game origin:
 
 ```ts
-import { createCrowdyStudioEmbed } from '@crowdedkingdoms/crowdyjs/crowdy-studio';
-// Self-starting glue worker for CLIENT mods (Vite shown; any bundler that
-// packages module workers works):
-import workerUrl from '@crowdedkingdoms/crowdyjs/player-glue-worker?worker&url';
+// Game origin, on "enter": redirect to the Overworld authorize page.
+location.assign(await game.portal.beginEntry({
+  appId, authorizeUrl: 'https://overworld.example.com/authorize',
+  redirectUri: location.origin + location.pathname,
+}));
 
-const studio = createCrowdyStudioEmbed({
-  client: game, // CrowdyClient: crowdyStudio, playerCompute, playerWallet, crowdyStudioAgent
-  appId,
-  gameName: 'My Game',
-  suppressGameplayInput: () => pauseInput(),
-  onLayoutChange: () => resizeCanvas(),
-});
+// Overworld /authorize page (holds the session token):
+location.assign(await overworld.portal.handleAuthorizeRequest());
 
-// Per open (for example after the player claims a grid):
-studio.toggle({
-  gridId,
-  targetPermissions: {
-    SERVER: { canWrite: true, canRun: true },
-    CLIENT: { canWrite: false, canRun: false }, // SERVER-only embeds omit workerUrl
-  },
-});
+// Game origin, on callback boot: exchange code+verifier -> app token (stored).
+const entered = await game.portal.completeEntry();
 ```
 
-CLIENT-mod embeds additionally pass `grid`, `workerUrl`, `onHostCall`, an
-optional `hud` sink, and a `playerHost` adapter. Note that CLIENT mods outside
-Blocks with Friends remain gated by program decision D13; new games should
-start SERVER-only exactly as above.
+Game-to-game routes through the Overworld for a fresh per-game token.
 
-The visible agent safety chrome is exported from
-`@crowdedkingdoms/crowdyjs/player-host`: **`PlayerControlGate`** (capture-phase
-human preemption seam with offline Stop) and **`AgentControlBanner`** (the
-always-visible-on-control Pause/Stop region, self-injected
-`ck-agent-control-*` styles).
+Notes:
 
-### Game API project contract
+- `portal.mintAppToken(appId)` returns the token plus `gameApiUrl` /
+  `gameApiWsUrl` / `expiresAt`; it does **not** store the token on the identity
+  client — set it on the per-game client.
+- Each client's `AuthState` is observed by both its HTTP client and its
+  realtime socket, so HTTP and WebSocket auth never drift within a client.
+- `client.session.restore()` reads from the configured `tokenStore`.
+  `BrowserLocalStorageTokenStore` is provided; bring your own `TokenStore` for
+  SSR or Node. PKCE state uses `BrowserSessionPkceStore` by default.
+- Use `client.auth.setToken(token)` to seed a token externally (e.g. when
+  restoring auth from a non-default storage).
 
-`CrowdyStudioAPI` implements the transport-neutral
-`CrowdyStudioProjectProvider`; generated GraphQL types remain inside the adapter.
-The committed merged schema and generated operations cover:
+Deeper reading: [Portals & app-scoped tokens](https://docs.crowdedkingdoms.com/management-api/portals-and-app-tokens)
+and [Sign in (passwordless)](https://docs.crowdedkingdoms.com/management-api/authentication).
 
-- `crowdyStudioProjects(appId)` / `crowdyStudioProject(appId, projectId)`
-- `crowdyStudioProjectCreate(input)`
-- `crowdyStudioProjectSave(input)` for one atomic metadata/file delta
-- `crowdyStudioLibraryFiles(appId)` / `crowdyStudioLibrarySave(input)`
-- `crowdyStudioCommonFiles(appId)`
-- `crowdyStudioProjectImportFile(input)` for copy-by-value imports
+### Token refresh during gameplay
 
-The adapter maps the API's `PAIRED | INDEPENDENT | SERVER_ONLY | CLIENT_ONLY`
-presentation enum to Crowdy Studio's runtime-oriented project kind and
-`REQUIRED | OPTIONAL | NONE` setting. A stale expected `revision` arrives as
-`CONFLICT` with `CROWDY_STUDIO_REVISION_CONFLICT` in the message and becomes a
-`CrowdyStudioRevisionConflictError` with the latest cloud project when that
-follow-up read succeeds.
+Before an app token expires, call `game.refreshGameplayToken()` while gameplay
+is active. It closes the old-token UDP proxy, refreshes and stores the token,
+and opens the new-token proxy while existing realtime handlers resubscribe in
+place. It deliberately stops on the first failed stage: if the old proxy cannot
+confirm disconnect, no refresh is attempted; if refresh fails, the old token is
+retained; if the new proxy connect fails, the fresh token remains stored —
+surface the error and retry `game.udp.connect()` instead of rotating again.
 
-### Agent SDK, transport, and integrated dock (v12)
+`game.portal.refresh()` remains available for clients with no active UDP
+lifecycle to preserve.
 
-The v12 agent API remains provider-neutral, while CrowdyJS now ships generated
-operations plus the production `CrowdyAgentGraphQLTransport` exposed as
-`client.crowdyStudioAgent`:
-
-```ts
-import {
-  CROWDY_AGENT_TOOL_REGISTRY_V1,
-  CrowdyStudioAgentController,
-} from '@crowdedkingdoms/crowdyjs/agent';
-
-const agent = new CrowdyStudioAgentController({
-  transport: game.crowdyStudioAgent,
-  createSession: {
-    appId,
-    projectId,
-    gridId,
-    mode: 'BUILD',
-    providerDataConsent: true,
-    idempotencyKey: crypto.randomUUID(),
-  },
-  beforeAgentWork: () => studio.controller.prepareForAgentWork(),
-});
-await agent.initialize(); // attach epoch → durable replay/gap fill → live tail
-```
-
-`CROWDY_AGENT_TOOL_REGISTRY_V1` is an immutable, digest-pinned registry of the
-minimum Studio/project/workspace/library/template/diagnostics/runtime and
-generic game tools. Every descriptor has exact logical and provider wire names,
-semantic version, bounded input/output JSON schemas,
-`additionalProperties:false`, executor, mode, risk/effect/reversibility,
-scope, approval, idempotency, timeout, and redaction metadata. Input schemas
-reject caller-supplied identity, epoch, lease, approval, endpoint, token, and
-other authority fields. `CrowdyAgentToolRegistry.fromWireName` is exact and
-case-sensitive; browser dispatch is execute-once by `toolCallId`, and ambiguous
-effects become `OUTCOME_UNKNOWN` instead of being repeated.
-
-`CrowdyStudioAgentTransportV1` owns no credentials and exposes only typed
-durable orchestration operations: session/history/descriptor/budget queries;
-create/attach/mode/event-ack/message/approval/tool-result/lease/pause/resume/
-cancel/close mutations; and the ordered event subscription. A generated adapter
-maps these methods to the operation names in
-`CROWDY_AGENT_GRAPHQL_OPERATIONS_V1`:
-
-- `crowdyStudioAgentSession`, `crowdyStudioAgentSessions`,
-  `crowdyStudioAgentHistory`, `crowdyStudioAgentToolDescriptors`, and
-  `crowdyStudioAgentBudget`;
-- `crowdyStudioAgentCreateSession`, `AttachClient`, `SetMode`,
-  `AcknowledgeEvents`, `Heartbeat`, `SendMessage`, `ApproveTool`, `RejectTool`,
-  `ToolResult`, `GrantLease`, `RevokeLease`, `Pause`, `Resume`, `CancelRun`,
-  and `CloseSession` (all with the `crowdyStudioAgent` prefix);
-- `crowdyStudioAgentEvents(sessionId, afterSeq, clientEpoch)`.
-
-The controller applies only contiguous decimal-string sequences, deduplicates
-event IDs, fills gaps from durable history, acknowledges the highest
-contiguous cursor, fences old attach epochs, and explicitly reconnects without
-resuming a run or Play lease. Approval methods use the exact displayed argument
-hash. Human edit/game input calls local preemption before best-effort transport
-cleanup. Attach uses a stable `clientInstanceId` and the server
-`replayAfterSeq`; public message input maps to Game API `content`, cancellation
-always sends an explicit run id, and PLAY sends a two-second heartbeat only
-while attached, active, and visible. Heartbeat, kill, and stale-epoch failures
-immediately clear local authority.
-
-Mode changes adopt the complete server-repinned session (registry digest,
-provider/app policy revisions, and context version) before loading its new
-effective descriptors. The Studio mount resolves the selected saved project
-after `CrowdyStudioController.initialize()`, overrides caller guesses when
-creating a BUILD session, and rejects an existing session bound to another
-project. Because v1 has no set-project mutation, switching projects fences the
-agent and requires a new session/remount.
-
-An active BUILD workspace lease is renewed every ten seconds through the same
-authenticated heartbeat; the server returns its renewed 30-second expiry.
-Human edits, project/context changes, lease revocation, disconnect, and destroy
-stop renewal and abort browser handlers. Run events retain their stable
-`code`, `reason`, and typed safe `error`.
-
-The committed descriptor digest fixture is checked on every build against the
-canonical registry. Coordinated refreshes first run
-`npm run agent-descriptors:drift -- --source <game-api-fixture>`; builds then
-recompute the full and canonical 28-tool Game API subset digest (14 mandatory
-game plus 14 Studio/diagnostic/runtime tools) so the fixture cannot silently
-diverge.
-
-Mount the responsive agent dock by adding `agent`; omit it to retain the v11
-manual UI unchanged:
-
-```ts
-const studio = await mountCrowdyStudio(host, {
-  projectProvider: game.crowdyStudio,
-  playerCompute: game.playerCompute,
-  appId,
-  gridId,
-  agent: {
-    transport: game.crowdyStudioAgent,
-    sessionId,
-    playerHost: bwfPlayerHostAdapter,
-  },
-});
-
-studio.agent?.sendMessage('Explain the current diagnostics');
-studio.controlLeaseManager?.preempt('HUMAN_INPUT');
-```
-
-The dock provides human-owned Ask/Build/Play selection, chat streaming,
-plan/tool status, exact approval hashes, diff/checkpoint cards, budget, visible
-lease scope/expiry, Pause/Resume/Stop, and checkpoint-restore requests. It uses
-text nodes for all untrusted content, ARIA status/log/group labels, visible
-focus, keyboard submission, and a container-query layout that moves the agent
-dock below narrow embeds.
-
-The headless `CrowdyStudioController` now also exposes:
+## Game-loop lifecycle
 
-- `prepareForAgentWork()` to flush autosave and fail closed on conflict/offline;
-- `applyAtomicPatch()` and `synchronizeProject()` for all-or-none multi-file
-  updates, human-edit preemption, and Monaco synchronization;
-- `refreshCheckpoints()` / `restoreCheckpoint()` through the optional
-  transport-neutral `CrowdyStudioSynchronizationProvider` (the provider is
-  required for agent writes/restores and must make checkpoint + revision
-  changes durable and atomic);
-- typed draft/live results plus `runtimeSync` (`RUNNING_SAVED`,
-  `RUNNING_STALE`, `STOPPED`, or `NEVER_RUN`).
+1. Sign in (passwordless) on the identity client with `client.auth`, or
+   restore a stored session with `client.session.restore()`. This yields the
+   **session token** (Management API only).
+2. Mint an **app-scoped token** for the app (`identity.portal.mintAppToken(appId)`,
+   or the PKCE portal flow across origins) and build a per-game client holding
+   it (`game.setToken(token)`). The gameplay steps below run on that **game**
+   client.
+3. Subscribe to UDP proxy notifications with `game.udp.subscribe(handlers, appId)`
+   — `appId` is **required** (the SDK opens the realtime socket on demand and
+   scopes it to that app).
+4. Join a chunk by sending an initial actor update.
+5. Send actor, voxel, text, audio, and client-event updates through `game.udp`
+   or the higher-level `game.world(appId)` helpers.
+6. Before the app token expires, call `game.refreshGameplayToken()`.
+7. Call `client.close()` (and `game.close()`) when disposing the SDK instances.
 
-### PlayerHostAdapter and Blocks with Friends integration
+## Sub-clients at a glance
 
-`@crowdedkingdoms/crowdyjs/player-host` exports
-`PlayerHostAdapterV1`, capability/observation/command/result types and schemas,
-`AgentControlLeaseManager`, and `createPlayerHostAgentTools`. A game adapter
-implements only:
+**Game-client surface** (end-user, browser-safe):
 
-```ts
-interface PlayerHostAdapterV1 {
-  readonly contractVersion: 'crowdy.player-host/1';
-  capabilities(): Promise<PlayerHostCapabilitiesV1>;
-  observe(request: ObserveRequestV1): Promise<GameObservationV1>;
-  dispatch(command: GameCommandV1, gate: ValidatedGateV1):
-    Promise<GameCommandResultV1>;
-  clearAgentIntent(reason: CrowdyAgentPreemptionReason): void;
-}
-```
+| Sub-client | What it does |
+|---|---|
+| `client.auth` | Passwordless sign-in (magic link, social/OIDC, dev bypass), log out, and linked identities (`myIdentities`, `linkIdentity`/`unlinkIdentity`). |
+| `client.users` | `me`, `updateGamertag`, profile reads. |
+| `client.session` | Token store, `restore()`, `getToken()`, manual `setToken()`. |
+| `client.portal` | App-scoped token minting (`mintAppToken`) and the cross-origin PKCE entry flow (`beginEntry` / `handleAuthorizeRequest` / `completeEntry` / `refresh`). |
+| `client.platform` | Public platform configuration (`config()`). |
+| `client.serverStatus` | `gameClientBootstrap(appId)` — per-app version info, UDP status, spatial limits. |
+| `client.chunks`, `client.voxels`, `client.actors`, `client.avatars`, `client.state` | World data reads + writes: terrain/LODs, voxel edit + history/rollback, durable actors, avatars, per-user app state blobs. |
+| `client.host` | Game-host election (`get`, `amIHost`) + actor liveness `heartbeat`. `amIHost` is UI convenience only — authoritative host gating uses `gameModelInvoke`'s `is_host` policy. |
+| `client.teleport` | Teleport requests. |
+| `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
+| `client.gameModel` | Abstract game model: containers, properties, functions (incl. model-driven `notify_*` effects), sessions, app-scoped active-session counts (`activePlayerCount`, `activePlayerCountChanged`), container-change push (`containerChanged`), flow-correlation timelines (`flow`), and automations / NPCs (`upsertAutomation`, `runAutomation`, `automationRuns`, `automationStats`, …). |
+| `client.compute` | Compute Modules — server-side Rust/WASM logic: author + deploy source (`upsertModule`, `deployVersion`, `deployTemplate`, `waitForCompile`), triggers + policy, synchronous `invoke`, and monitoring (`moduleRuns`, `moduleStats`, `moduleLogs`, `appDiagnostics`). See [Compute Modules](https://docs.crowdedkingdoms.com/game-api/compute-modules). |
+| `client.playerCompute` | Player-authored SERVER/CLIENT Rust/WASM bound to player-owned grids: deploy source, activate/deactivate, list modules/versions, delete self-authored modules. |
+| `client.playerModel` | Player-owned flexible model containers and grid-confined automations (`containers`, `createContainer`, `setProperty`, `automations`, `createAutomation`, …). |
+| `client.playerWallet` | Player spend: balance, spend caps, card setup, policy, charges. |
+| `client.marketplace` | Player-code store/install/consent flows plus player-authorized grid claims (`claimGridOwnership`, `claimGridChunk`, `releaseClaimedGrid`) and client-mod artifact fetches. |
+| `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, optimistic revisions, copy-by-value imports, atomic saves. |
+| `client.crowdyStudioAgent` | Generated, app-token Game API transport for durable agent sessions: history/session pages, descriptors/budgets, approvals, tool results, heartbeat, control mutations, ordered event subscriptions. |
+| `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`, `sendSingleActorMessage`, `sendChannelMessage`). |
+| `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
+| `client.refreshGameplayToken()` | Safely rotates an active game client's app token (see [Token refresh](#token-refresh-during-gameplay)). |
+| `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`, `actor.sendToActor`). |
+| `client.kit(appId)` | Game Kit: ready-made mappings of game concepts onto the game model — see [Game Kit](#game-kit). |
+| `createWorldSession(client, appId, config)` | World Stores: opt-in, SDK-managed game state from the `@crowdedkingdoms/crowdyjs/stores` subpath — see [World Stores](#world-stores). |
 
-For Blocks with Friends, implement this interface over the same typed intent
-methods used by `PlayerController`, `ActionService`, `InventoryService`,
-`FishingService`, `RideService`, and existing referee/model calls. Construct
-`createPlayerHostAgentTools(adapter)` and pass `adapter` as the mount's
-`playerHost`. The returned lease manager enforces TTL, scopes, client epoch,
-host/controlled-entity revision, observation freshness, modal/death state,
-per-command rate limits, approvals, and tool-call dedup. Call
-`leaseManager.preempt('HUMAN_INPUT')` synchronously on key/mouse/touch input,
-`ESCAPE` on Escape, and the corresponding reason on death, target/context
-change, disconnect, or Stop. `clearAgentIntent` must immediately zero movement,
-look, and pending action intent. BWF does not integrate through raw CrowdyJS,
-DOM input, UDP packets, `PlayerCodeBroker`, or client-mod host calls.
-
-BWF should pass only `game.crowdyStudioAgent` and its
-`BwfPlayerHostAdapter` to the Studio mount; the mount derives the selected
-project id. Its adapter must implement the exact 14 mandatory game surfaces,
-classify combat as conditional approval, return typed failed/denied/unknown
-outcomes, and make `clearAgentIntent` synchronously cancel shared movement and
-action intents when the dispatcher aborts.
-
-The reconciled Game API development pilot advertises the exact 28-tool
-follow-up subset, including all 14 mandatory game descriptors. CrowdyJS routes
-all game tools through
-`PlayerHostAdapterV1`, the scoped lease gate, conditional combat approval,
-safety stop, heartbeat fencing, and typed result continuation. BWF Play now
-remains blocked only on the concrete BWF adapter/shared-intent wiring and its
-host/app policy configuration.
-
-The same browser dispatcher routes backend-advertised `runtime.test_draft`,
-`runtime.deploy_live`, `runtime.invoke`, and `runtime.stop` through the
-headless Studio controller. Draft testing is routine BUILD work; live deploy
-and LIVE invoke require the exact approval grant; stop remains an idempotent
-safety action. Inner game `FAILED`, `DENIED`, or `OUTCOME_UNKNOWN` results are
-promoted to matching outer terminal tool results and are never reported as
-successful.
-
-Runtime execution is plan-bound: requested targets must exactly equal the
-selected project’s authoritative target set, so a full-stack project cannot run
-CLIENT after SERVER-only authorization. Live deploy additionally rechecks the
-saved revision, canonical project content hash (including module names/files),
-and pairing preference after autosave. Invoke checks the exact running
-DRAFT/LIVE environment and export; stop always stops the complete selected
-project as a safety action rather than interpreting a partial target.
-
-| `createWorldSession(client, appId, config)` (from `@crowdedkingdoms/crowdyjs/stores`) | World Stores: opt-in, SDK-managed game state — typed codecs (`structCodec` binary DSL), your own actor with a 5 Hz send loop (`session.self`), a remote-actor registry with lanes/history/staleness (`session.actors`), attributed send errors (`session.errors`), a chunk/voxel cache with realtime merge + worldgen write-back (`session.chunks`), channel/direct-message inboxes + a typed event router, host tracking, typed save/avatar state, and a game-model container mirror. Only configured stores exist (compile-time + runtime); unimported stores tree-shake away. |
-| `client.kit(appId)` | Game Kit: ready-made mappings of game concepts onto the game model — `kit.inventory`, `kit.objects` (lockable doors/chests with custom permissions), `kit.npcs`, `kit.plots` (buy/rent land with transactional, replication-enforced grid grants), and the genre layers `kit.economy` (wallets/shops/trades/market), `kit.progression` (xp/skills/achievements/rating), `kit.loot`, `kit.quests`, `kit.combat`, `kit.matches` (session lobbies/turns/scores with notify-to-pull channels), `kit.decks` (hidden hands), `kit.worldsim` (clock/nodes/crops/waves), `kit.social` (parties/guilds/chat over teams+channels), `kit.leaderboards`, `kit.features` (tier gates), and the engine-aware helpers `kit.mobs` (refereed attacks, defs/slots, contact-damage parsing), `kit.pets` (adopt/summon/dismiss/rename), `kit.instances` (private world slices, seeded runs), `kit.director` (encounter runs), `kit.matchmaking` (queues/proposals/rating), `kit.minigames` (invoke-loop wrapper), `kit.economy.orderBook` (escrowed bid/ask market), engine paths on `kit.matches`/`kit.decks`/`kit.leaderboards`, `kit.quests` tutorial sequencing, `kit.engines` (compute capability detection) with `kit/wire` (the engine pose codec, `engineLanes()`, and the 77/90/91/92/93 event parsers) — plus blueprint builders + `kit.deploy(...)` for the admin "load the rules" step. |
-
-**Studio-admin surface** (privileged; drive with a server-side / studio token, grouped under `client.admin`):
+**Studio-admin surface** (privileged; drive with a server-side / studio token,
+grouped under `client.admin` and mirrored at the top level):
 
 | Sub-client | What it does |
 |---|---|
 | `client.organizations` | Orgs, members, RBAC roles, org API tokens. |
-| `client.apps` | App discovery + routing (`createApp` etc. via the management API directly). |
+| `client.apps` | App registry, discovery + routing (`create`, `routeFor`, `marketplace`), visibility, and player-code admission mode / allow-list administration. |
 | `client.appAccess` | Access tiers + per-user grants. |
 | `client.billing` | Org wallet + per-app spend budgets. |
 | `client.payments` | Payment checkouts (wallet top-ups, plan purchases). |
@@ -546,36 +217,31 @@ project as a safety action rather than interpreting a partial target.
 | `client.usage` | Replication + GraphQL usage reporting. |
 | `client.sharedEnvironment` | Publish to shared, runtime gating, spend caps, auto-billing. |
 | `client.gameApps` | App grids (`createGrid` / `deleteGrid`), first-class grid ownership (`ownership` / `assignOwnership` / `transferOwnership`), and grid runtime-permission administration. |
-| `client.apps` | App registry/routing plus player-code admission mode and code/author/org allow-list administration. |
 
 **Operator surface** (platform operations; requires `is_operator`):
 
 | Sub-client | What it does |
 |---|---|
-| `client.operator` | Platform compute ceilings (v13: infra operations moved to the separate infra-control-plane service). |
+| `client.operator` | Platform compute ceilings (`computePlatformCeilings`, `setComputePlatformCeilings`). Infrastructure operations live in the separate infra-control-plane service, not this SDK. |
 
-Auth, user reads, and the studio-admin / operator surfaces target `managementUrl` and use the **identity session token**; the game-client world/UDP surfaces target `httpUrl` / `wsUrl` and require an **app-scoped token** for that app. Use one identity client plus a per-game client (see [Overworld portals & app-scoped tokens (v7)](#overworld-portals--app-scoped-tokens-v7)); each client's `AuthState` carries its token to its own endpoints, so HTTP and WebSocket auth never drift within a client.
-
-## Game-loop lifecycle
-
-1. Sign in (passwordless) on the identity client with `client.auth` — `requestLoginLink`/`completeLoginLink` (magic link), `socialLoginStart`/`socialLoginComplete` (social/OIDC), or `devLogin` (dev/test only) — or `client.session.restore()`. This yields the **session token** (Management API only).
-2. Mint an **app-scoped token** for the app (`identity.portal.mintAppToken(appId)`, or the PKCE portal flow across origins) and build a per-game client holding it (`game.setToken(token)`). The gameplay steps below run on that **game** client.
-3. Subscribe to UDP proxy notifications with `game.udp.subscribe(handlers, appId)` — `appId` is **required** (the SDK opens the realtime socket on demand and scopes it to that app).
-4. Join a chunk by sending an initial actor update.
-5. Send actor, voxel, text, audio, and client-event updates through `game.udp` or the higher-level `game.world(appId)` helpers.
-6. Before the app token expires, call `game.refreshGameplayToken()` while gameplay is active. It closes the old-token UDP proxy before rotating the token, opens the new-token proxy, and lets the existing realtime subscription restart without adding handlers. Use `game.portal.refresh()` directly only when no UDP proxy lifecycle needs to be preserved.
-7. Call `client.close()` (and `game.close()`) when disposing the SDK instances.
+Auth, user reads, and the studio-admin / operator surfaces target
+`managementUrl` and use the **identity session token**; the game-client
+world/UDP surfaces target `httpUrl` / `wsUrl` and require an **app-scoped
+token** for that app.
 
-`refreshGameplayToken()` deliberately stops on the first failed stage. If the
-old proxy cannot confirm disconnect, no refresh is attempted and the old token
-remains active. If refresh fails, the old token is still retained (although its
-proxy was closed and may be reopened). If the new proxy connect fails, the
-fresh token remains stored; surface the error and retry `game.udp.connect()`
-instead of rotating again.
+CrowdyJS wraps the full public Management + Game API surface — every
+non-deprecated public root field has a typed method, with Relay `*Connection`
+cursor-pagination variants alongside the legacy offset lists. The SDK never
+relaxes server-side authorization: exposing an operation here just gives you a
+typed wrapper; the caller still needs the right token and permission. Drive
+privileged surfaces from a studio backend with an org-scoped or admin token,
+not from an untrusted browser.
 
 ## Per-app routing
 
-When a player is about to join an app, query its routing fields on the management API first:
+`mintAppToken` returns `gameApiUrl` / `gameApiWsUrl`, so you rarely need a
+separate routing query. When you do (e.g. pre-flight discovery), query the
+app's routing fields on the Management API:
 
 ```graphql
 query AppForRouting($appId: BigInt!) {
@@ -588,23 +254,21 @@ query AppForRouting($appId: BigInt!) {
 }
 ```
 
-`gameApiUrl` is populated for **both** dedicated (`splitMode`) and shared
-(`deploymentTarget: "shared"`) apps. When it's set, build a **second**
-`CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) holding that
-app's **app-scoped token** (`identity.portal.mintAppToken(appId)` — do **not**
-reuse the identity client's session token store), then drive gameplay through that
-client. In practice `mintAppToken` already returns `gameApiUrl` / `gameApiWsUrl`,
-so you rarely need this separate routing query. Apps with no `gameApiUrl` keep
-working against the default `httpUrl` you configured.
+`gameApiUrl` is populated for both dedicated (`splitMode`) and shared
+(`deploymentTarget: "shared"`) apps. When it's set, build a second
+`CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) holding
+that app's app-scoped token, then drive gameplay through that client. Apps
+with no `gameApiUrl` keep working against the default `httpUrl` you
+configured. See [Loading an app's Game API](https://docs.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
 
 ## Realtime notifications
 
-`subscribe` takes the handlers **and a required `appId`** (second argument). The
-Game API scopes the realtime session to that app and rejects an app-agnostic
-subscription with a `RealtimeConnectionEvent` (`code: 'APP_ID_REQUIRED'`). It also
-rejects an identity session token (`APP_TOKEN_REQUIRED`) or a token scoped to a
-different app (`APP_SCOPE_MISMATCH`). Run one client per app (each holding that
-app's app-scoped token) when a player is in multiple apps at once.
+`subscribe` takes the handlers **and a required `appId`** (second argument).
+The Game API scopes the realtime session to that app and rejects an
+app-agnostic subscription with a `RealtimeConnectionEvent`
+(`code: 'APP_ID_REQUIRED'`); a missing or invalid gameplay token is rejected
+with `AUTH_REQUIRED`. Run one client per app (each holding that app's
+app-scoped token) when a player is in multiple apps at once.
 
 ```ts
 const appId = '1';
@@ -623,6 +287,10 @@ const unsubscribe = client.udp.subscribe(
       // A direct actor-to-actor message addressed to you.
       console.log(event.uuid, event.payload); // payload is base64
     },
+    channelMessage: (event) => {
+      // A message broadcast on a channel you're subscribed to.
+      console.log(event.channelId, event.payload); // payload is base64
+    },
     genericError: (event) => {
       console.warn(event.sequenceNumber, event.errorCode);
     },
@@ -647,7 +315,13 @@ client.realtime.onStatus((status) => {
 unsubscribe();
 ```
 
-The SDK uses the `graphql-transport-ws` protocol through `graphql-ws`, reconnects with backoff, re-reads the current token before reconnecting, and resubscribes automatically.
+The SDK uses the `graphql-transport-ws` protocol through `graphql-ws`,
+reconnects with backoff, re-reads the current token before reconnecting, and
+resubscribes automatically. `RealtimeConnectionEvent` carries a `retryable`
+flag: `UDP_PROXY_CONNECTION_FAILED` is transient (back off and resubscribe),
+while `AUTH_REQUIRED` / `APP_ID_REQUIRED` must be fixed by the caller first.
+Unsubscribing stops delivery only; call `client.udp.disconnect()` to close the
+UDP proxy session.
 
 ## Spatial sends
 
@@ -664,15 +338,19 @@ const response = await client.udp.sendActorUpdateAndWait({
 console.log(response.__typename, response.sequenceNumber);
 ```
 
-The plain `sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, and `sendClientEvent` methods return the GraphQL mutation result immediately. The `AndWait` variants allocate a `sequenceNumber` when one is missing and wait for either a matching notification or `GenericErrorResponse`.
+The plain `sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`,
+`sendTextPacket`, and `sendClientEvent` methods return the GraphQL mutation
+result immediately. The `AndWait` variants allocate a `sequenceNumber` when
+one is missing and wait for either a matching notification or
+`GenericErrorResponse`. `sendChannelMessage` broadcasts an opaque payload on a
+channel.
 
 ### Actor-to-actor messages
 
 ```ts
 // Delivered only to the actor whose UUID matches `targetUuid`; you must know
-// that actor's current chunk. Fire-and-forget — the sender gets no echo, so
-// there is no `AndWait` variant. The target receives a
-// `SingleActorMessageNotification` on its subscription.
+// that actor's current chunk. Fire-and-forget — the sender gets no echo. The
+// target receives a `SingleActorMessageNotification` on its subscription.
 await client.udp.sendSingleActorMessage({
   appId: '1',
   chunk: { x: '7', y: '1', z: '2' }, // the TARGET actor's chunk
@@ -699,23 +377,24 @@ await actor.sendToActor(
 );
 ```
 
-The world helpers are thin wrappers over `client.udp.*` with the appId pre-bound — convenient for browser games. Advanced callers can always use `client.udp.*` with the generated GraphQL input types directly.
+The world helpers are thin wrappers over `client.udp.*` with the appId
+pre-bound — convenient for browser games. Advanced callers can always use
+`client.udp.*` with the generated GraphQL input types directly.
 
 ## World Stores
 
 The core client is a thin transport; the **World Stores** layer
-(`@crowdedkingdoms/crowdyjs/stores`, 8.4+) adds the source-of-truth data
-structures every game otherwise hand-writes: actor registries, chunk/voxel
-caches, error attribution, message inboxes, host tracking, and typed
-durable-state wrappers — all driven by ONE shared `udpNotifications`
-subscription and ONE scheduler.
+(`@crowdedkingdoms/crowdyjs/stores`) adds the source-of-truth data structures
+every game otherwise hand-writes: actor registries, chunk/voxel caches, error
+attribution, message inboxes, host tracking, and typed durable-state wrappers
+— all driven by ONE shared `udpNotifications` subscription and ONE scheduler.
 
 ```ts
 import {
   createWorldSession, structCodec, f32, u8, jsonCodec, workerTicker,
 } from '@crowdedkingdoms/crowdyjs/stores';
 
-// Describe your replication state ONCE (48-byte binary layouts, declaratively):
+// Describe your replication state ONCE (binary layouts, declaratively):
 const poseCodec = structCodec({
   x: f32(), y: f32(), z: f32(), yaw: f32(),
   flags: u8(), held: u8(),
@@ -750,6 +429,13 @@ session.errors.onError((e) => console.warn(e.errorCode, e.send?.kind));
 session.dispose();
 ```
 
+The available stores are `self` (your actor + send loop), `actors` (remote
+actor registry with lanes/history/staleness), `errors` (attributed send
+errors), `chunks` (chunk/voxel cache with realtime merge + worldgen
+write-back), `channelInbox` / `actorInbox` (message inboxes), `events` (typed
+event router), `host` (host tracking), `save` / `avatar` (typed durable
+state), and `model` (game-model container mirror).
+
 Every store is **opt-in twice over**: only configured stores are constructed
 (and only they exist on the session's TYPE — `session.host` without
 `host: ...` in the config is a compile error), and the layer lives behind the
@@ -795,8 +481,7 @@ const result = await kit.objects.open(doorId, { keyId });
 if (!result.success) console.warn('locked:', result.errorMessage);
 ```
 
-Land sale closes the permission loop end to end (requires game-api v0.13.11+ for
-effects, v0.13.12+ for the chunk-permission reads):
+Land sale closes the permission loop end to end:
 
 ```ts
 // Studio: sell a plot over a grid; doors on it honor the purchase automatically.
@@ -816,28 +501,138 @@ selector has `candidatePermissionWhere: [{ userFrom: { property: 'owner_user_id'
 op: 'lacks', key: 'access', grid: { property: 'grid_id' } }]` reacts only to
 intruders.
 
-As of 8.3.0 the kit covers the common genre staples end to end — every layer
-is a blueprint builder + typed runtime helper:
+The kit covers the common genre staples end to end — each layer is a blueprint
+builder plus a typed runtime helper:
 
 | Layer | Builder → helper | Highlights |
 | --- | --- | --- |
-| Economy | `economyBlueprint` → `kit.economy` | multi-currency wallets, atomic shop buys, escrow trades, player market, restock automation |
+| Inventory | `inventoryBlueprint` → `kit.inventory` | bags/stacks, grant/consume/transfer, craft, barter |
+| Objects | `lockBlueprint` → `kit.objects` | lockable doors/chests with key or permission authority |
+| NPCs | `npcBlueprint` → `kit.npcs` | automation-driven NPC instances (spawn, runNow, enable) |
+| Plots | `plotBlueprint` → `kit.plots` | buy/rent land with transactional, replication-enforced grid grants |
+| Economy | `economyBlueprint` → `kit.economy` | multi-currency wallets, atomic shop buys, escrow trades, player market, escrowed order book (`kit.economy.orderBook`) |
 | Progression | `progressionBlueprint` → `kit.progression` | xp/levels via the `fn:` curve helper, skill prerequisite chains, achievements, host-gated rating |
 | Loot | `lootBlueprint` → `kit.loot` | weighted tables unrolled into seed-driven expressions, atomic single-claim, event-triggered drops |
-| Quests | `questsBlueprint` → `kit.quests` | event-automation progress, atomic claim into stack+wallet, cron daily resets |
-| Combat | `combatBlueprint` → `kit.combat` | server-side damage/death, status-effect tick automation (selector join), `turnBased`/`hostSynced` |
+| Quests | `questsBlueprint` → `kit.quests` | event-automation progress, atomic claim into stack+wallet, cron daily resets, tutorial sequencing |
+| Combat | `combatBlueprint` → `kit.combat` | server-side damage/death, status-effect tick automation, `turnBased`/`hostSynced`, routed attacks |
 | Matches | `matchesBlueprint` → `kit.matches` | session lobbies/rounds/turns/scores, per-match channel + `onMatchChanged` (notify-to-pull) |
 | Decks | `decksBlueprint` → `kit.decks` | hidden hands via owner-visibility `card_id`, shuffle-by-position automation |
-| World sim | `worldsimBlueprint` → `kit.worldsim` | day/night clock with spatial notify, node regen + atomic gather, crops, wave counters |
+| World sim | `worldsimBlueprint` → `kit.worldsim` | day/night clock with spatial notify, node regen + atomic gather, crops, wave counters, forecasts |
 | Social | `guildBlueprint` → `kit.social` | parties/guilds/chat over teams+channels, grid territory grants, guild hall + bank composite |
 | Leaderboards | `leaderboardsBlueprint` → `kit.leaderboards` | trusted keep-best submits, client-side ranking, cron seasons |
+| Live ops | `liveopsBlueprint` → `kit.liveops` | timed event windows and seasons |
+| Moderation | `moderationBlueprint` → `kit.moderation` | reports, queues, mutes |
+| Telemetry | `telemetryBlueprint` → `kit.telemetry` | counters and lightweight event tracking |
 | Monetization | `featureGate` → `kit.features` | feature keys, tier grants, `*policyExtra` gating on builders |
+| Abilities | — → `kit.abilities` | ability definitions, casts, loadouts |
+| Movement | — → `kit.movement` | movement warden configs + violation parsing |
+| Territory | — → `kit.territory` | control points, factions, enrollment |
+| Racing | — → `kit.racing` | courses, entries, possession (claim/pass/shoot) |
+
+Engine-aware layers talk to compute-module game engines when they are
+deployed, and degrade gracefully on model-only apps via capability detection
+(`kit.engines`): `kit.mobs` (refereed attacks, defs/slots, contact-damage
+parsing), `kit.pets` (adopt/summon/dismiss/rename), `kit.instances` (private
+world slices, seeded runs), `kit.director` (encounter runs),
+`kit.matchmaking` (queues/proposals/rating), `kit.minigames` (invoke-loop
+wrapper), plus engine paths on `kit.matches` / `kit.decks` /
+`kit.leaderboards` and the `kit/wire` pose codec + event parsers. Deploy
+engines alongside blueprints with `kit.deploy(blueprints, { engines })`.
 
 See the docs guides [Modeling game concepts](https://docs.crowdedkingdoms.com/game-api/modeling-game-concepts)
 (the underlying model + genre map) and [Game Kit](https://docs.crowdedkingdoms.com/crowdyjs/game-kit)
 (the SDK surface + the simulation-tier / notify-to-pull / timer / hidden-info
 / anti-cheat patterns).
 
+## Crowdy Studio
+
+Crowdy Studio is the in-game SERVER/CLIENT Rust authoring surface for player
+code: cloud projects with target-scoped files, optimistic-concurrency
+autosave, draft/live/stop orchestration, and a Monaco editor backed by a local
+Rust language worker. The worker receives source files and the embedded
+platform index only — never a credential and never a server connection.
+Compiled CLIENT artifacts run through `PlayerCodeBroker`, which keeps tokens
+on the page, allow-lists host calls, and locally clamps chunk-targeted effects
+to the owned grid before the normal SDK path reaches server authorization.
+
+Most games embed the ready-made shell rather than hand-rolling window chrome
+around `mountCrowdyStudio`:
+
+```ts
+import { createCrowdyStudioEmbed } from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+// Self-starting glue worker for CLIENT mods (Vite shown; any bundler that
+// packages module workers works):
+import workerUrl from '@crowdedkingdoms/crowdyjs/player-glue-worker?worker&url';
+
+const studio = createCrowdyStudioEmbed({
+  client: game, // CrowdyClient: crowdyStudio, playerCompute, playerWallet, crowdyStudioAgent
+  appId,
+  gameName: 'My Game',
+  suppressGameplayInput: () => pauseInput(),
+  onLayoutChange: () => resizeCanvas(),
+});
+
+// Per open (for example after the player claims a grid):
+studio.toggle({
+  gridId,
+  targetPermissions: {
+    SERVER: { canWrite: true, canRun: true },
+    CLIENT: { canWrite: false, canRun: false }, // SERVER-only embeds omit workerUrl
+  },
+});
+```
+
+The embed renders a resizable right dock on desktop and a focus-trapped
+fullscreen modal on narrow screens, and mounts the agent dock automatically
+when the client exposes `crowdyStudioAgent` and the game passes a
+`playerHost`. For custom chrome, call `mountCrowdyStudio(host, options)`
+directly; for a headless integration, use `new CrowdyStudioController(options)`.
+New games should start SERVER-only. Untrusted HUD payloads always render as
+text, never HTML.
+
+See [Crowdy Studio & player client mods](https://docs.crowdedkingdoms.com/crowdyjs/player-client-mods)
+and [Embed Crowdy Studio in your game](https://docs.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
+
+### Agentic Crowdy Studio
+
+The agent surface adds an Ask/Build/Play AI dock on top of Crowdy Studio,
+built from three browser contracts (`crowdy.studio-agent/1`,
+`crowdy.agent-tools/1`, `crowdy.player-host/1`):
+
+- `@crowdedkingdoms/crowdyjs/agent` exports `CrowdyStudioAgentController` (the
+  durable session client: contiguous event ordering, replay/gap fill,
+  attach-epoch fencing, exact approval hashes, budgets, pause/resume/stop) and
+  `CROWDY_AGENT_TOOL_REGISTRY_V1`, an immutable digest-pinned registry of
+  bounded, schema-validated tools. There is deliberately no raw GraphQL
+  executor, DOM driver, `fetch`, shell, or unrestricted SDK bridge in these
+  surfaces.
+- `client.crowdyStudioAgent` is the production GraphQL transport for durable
+  agent sessions; pass it (plus a `playerHost` adapter) to the Studio mount's
+  `agent` option to get the integrated dock.
+- `@crowdedkingdoms/crowdyjs/player-host` exports the generic game
+  observation/control contract: implement `PlayerHostAdapterV1` over your
+  game's typed intent methods, and the exported `AgentControlLeaseManager`,
+  `PlayerControlGate`, and `AgentControlBanner` enforce scoped leases, TTLs,
+  synchronous human preemption, and always-visible Pause/Stop chrome.
+
+```ts
+import { CrowdyStudioAgentController } from '@crowdedkingdoms/crowdyjs/agent';
+
+const agent = new CrowdyStudioAgentController({
+  transport: game.crowdyStudioAgent,
+  createSession: {
+    appId, projectId, gridId,
+    mode: 'BUILD',
+    providerDataConsent: true,
+    idempotencyKey: crypto.randomUUID(),
+  },
+});
+await agent.initialize(); // attach epoch → durable replay/gap fill → live tail
+```
+
+See [Agentic Crowdy Studio](https://docs.crowdedkingdoms.com/crowdyjs/agentic-crowdy-studio)
+for the full session, lease, and approval model.
+
 ## Errors
 
 Transport and protocol failures throw structured error classes:
@@ -849,11 +644,18 @@ Transport and protocol failures throw structured error classes:
 - `CrowdyRealtimeError` — realtime subscription couldn't be established or was dropped.
 - `CrowdyProtocolError` — server response failed schema validation.
 
-GraphQL errors carry a stable `extensions.code` (e.g. `UNAUTHENTICATED`, `SCOPE_MISSING`, `FORBIDDEN`, `IDEMPOTENCY_CONFLICT`) plus, where applicable, `extensions.remediation` and `extensions.requiredPermission`. Branch on `error.extensions?.code` rather than parsing messages.
+GraphQL errors carry a stable `extensions.code` (e.g. `UNAUTHENTICATED`,
+`SCOPE_MISSING`, `FORBIDDEN`, `IDEMPOTENCY_CONFLICT`, `RATE_LIMITED`) plus,
+where applicable, `extensions.remediation` and `extensions.requiredPermission`.
+Branch on `error.extensions?.code` rather than parsing messages.
 
 ## Idempotent retries
 
-Destructive game-client mutations accept an optional **idempotency key**. Pass a stable key (e.g. `crypto.randomUUID()`) and a network retry replays the first result instead of applying the side effect twice. Reusing a key with different arguments throws a `CrowdyGraphQLError` with `extensions.code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h.
+Destructive game-client mutations accept an optional **idempotency key**. Pass
+a stable key (e.g. `crypto.randomUUID()`) and a network retry replays the
+first result instead of applying the side effect twice. Reusing a key with
+different arguments throws a `CrowdyGraphQLError` with
+`extensions.code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h.
 
 ```ts
 const key = crypto.randomUUID();
@@ -864,102 +666,56 @@ await client.teams.leave(groupId, key);         // leaveTeam
 await client.voxels.rollback({ ...input, idempotencyKey: key }); // input field
 ```
 
-The key parameter is optional and trailing, so it's safe to omit. Requires a server on release v0.1.19+ (see Server compatibility above).
-
-## Auth notes
+The key parameter is optional and trailing, so it's safe to omit.
 
-- Use `client.auth.setToken(token)` if you need to seed a token externally (e.g. when restoring auth from a non-default storage).
-- `client.session.restore()` reads from the configured `tokenStore`. `BrowserLocalStorageTokenStore` is provided; bring your own for SSR or Node usage.
-- Each client's `AuthState` is observed by both its HTTP client and its realtime socket, so HTTP and WebSocket auth never drift within a client. Hold the **identity session token** on the management/identity client and an **app-scoped token** on each per-game client (`client.portal` — see the [v7 section](#overworld-portals--app-scoped-tokens-v7)).
-
-## Overworld portals & app-scoped tokens (v7)
-
-As of v7 gameplay requires an **app-scoped token**, not the session token.
-Passwordless sign-in returns an **identity session token** (Management API only —
-account, studio admin, and minting); each game is entered with a short-lived token
-confined to that one app, so a game stack never receives the player's full session.
+## Low-level GraphQL access
 
-Use two clients: an Overworld/identity client (session token) and a per-game
-client (app token), sharing only the Management URL.
+Typed sub-client methods are first-class, but generated operation documents
+are also available through a transport escape hatch — `client.graphql` for the
+Game API and `client.management` for the Management API:
 
 ```ts
-// Overworld/identity client
-const overworld = createCrowdyClient({ managementUrl, tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:session') });
-// Passwordless sign-in (magic link, social/OIDC, or dev bypass) yields the session token.
-await overworld.auth.requestLoginLink({ email, redirectUri });
-await overworld.auth.completeLoginLink(tokenFromLink);
+import { VersionInfoDocument } from '@crowdedkingdoms/crowdyjs/generated';
 
-// Native / same-origin: mint directly, then build a game client.
-const t = await overworld.portal.mintAppToken(appId);
-const game = createCrowdyClient({ httpUrl: t.gameApiUrl!, wsUrl: t.gameApiWsUrl!, managementUrl,
-  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:app:' + appId) });
-game.setToken(t.token);
-game.world(appId).subscribe({ actorUpdate: (n) => { /* ... */ } });
+const data = await client.graphql.request(VersionInfoDocument);
 ```
 
-Browser cross-origin handoff is OAuth2 Authorization Code + PKCE — the verifier
-never leaves the game origin:
-
-```ts
-// Game origin, on "enter": redirect to the Overworld authorize page.
-location.assign(await game.portal.beginEntry({
-  appId, authorizeUrl: 'https://overworld.example.com/authorize',
-  redirectUri: location.origin + location.pathname,
-}));
+For any brand-new server field not yet wrapped, `client.graphql.request(...)` /
+`client.management.request(...)` always works.
 
-// Overworld /authorize page (holds the session token):
-location.assign(await overworld.portal.handleAuthorizeRequest());
+## Maintainers: schema artifacts and fixtures
 
-// Game origin, on callback boot: exchange code+verifier -> app token (stored).
-const entered = await game.portal.completeEntry();
-// Keep active UDP gameplay running past expiry without orphaning the old proxy:
-await game.refreshGameplayToken();
-```
+CrowdyJS is a standalone public package: a clean clone builds with
+`npm install && npm run build` using the artifacts committed to this repo —
+no other repositories and no network access required:
 
-`portal.refresh()` remains available for clients with no active UDP lifecycle.
-Once a proxy or realtime gameplay session is active, prefer
-`refreshGameplayToken()` so the old Bearer closes its proxy before the token is
-revoked.
-
-Game-to-game routes through the Overworld for a fresh per-game token. New
-realtime codes: `APP_TOKEN_REQUIRED`, `APP_SCOPE_MISMATCH`; new `UdpErrorCode`:
-`TOKEN_EXPIRED`. See [MIGRATION.md](MIGRATION.md) for the full v7 breaking guide.
-
-## Surface scope & security
-
-As of v6 (completed in v6.1), CrowdyJS wraps the **full** management-api + game-api
-public surface, not just the game-client subset — every non-deprecated public root
-field has a typed method, with Relay `*Connection` cursor-pagination variants
-alongside the legacy offset lists. The surfaces are namespaced by audience:
-
-- **Game-client** (`client.auth`, `client.users`, `client.udp`, `client.world(...)`,
-  `client.chunks`/`voxels`/`actors`/`avatars`/`state`/`teleport`/`channels`/`teams`/
-  `gameModel`/`host`) — safe for untrusted browser clients with an end-user token.
-- **Studio-admin** (`client.admin.*` — also reachable at the top level, e.g.
-  `client.billing`) — privileged organization/app administration. Drive these from a
-  **studio backend** with an org-scoped or admin token, **not** from an untrusted
-  browser; the server still enforces the relevant org/app permission on every call.
-- **Operator** (`client.operator`) — platform-policy operations (compute
-  ceilings) that require `users.is_operator`. For internal operator tooling
-  only. Infrastructure operations live in the separate infra-control-plane
-  service as of v13, not this SDK.
-
-The SDK never relaxes server-side authorization — exposing an operation here just
-gives you a typed wrapper; the caller still needs the right token and permission. For
-any brand-new server field not yet wrapped, the low-level escape hatch
-(`client.graphql.request(...)` / `client.management.request(...)`) always works.
+- `schema.gql` — merged Management API + Game API SDL.
+- `src/generated/graphql.ts` — generated TypeScript operation types.
 
-## Low-level GraphQL access
+Schema refresh is explicit, from the published SDLs
+([management-api.graphql](https://docs.crowdedkingdoms.com/schema/management-api.graphql),
+[game-api.graphql](https://docs.crowdedkingdoms.com/schema/game-api.graphql)):
 
-Game-client methods are first-class, but generated operation documents are also available through a transport escape hatch:
+```bash
+npm run schema:sync:prod
+npm run codegen
+```
 
-```ts
-import { VersionInfoDocument } from '@crowdedkingdoms/crowdyjs/generated';
+(`npm run schema:sync:paths -- --management <file-or-url> --game <file-or-url>`
+accepts explicit sources.) Commit `schema.gql` and `src/generated/graphql.ts`
+together whenever the public GraphQL surface changes; `npm run check:schema`
+detects drift in CI/release work.
 
-const data = await client.graphql.request(VersionInfoDocument);
-```
+Two more committed fixtures follow the same boundary — the build validates
+them locally and never reads a sibling checkout; coordinated maintainers
+refresh them from an explicitly supplied source:
 
-Most consumers should prefer the typed methods on `client.auth`, `client.users`, `client.udp`, `client.serverStatus`, and `client.world()`.
+- The browser Rust authoring index:
+  `npm run authoring-index:drift -- --source <exporter-json> [--write]`, then
+  `npm run authoring-index:generate`.
+- The agent tool-descriptor fixture:
+  `npm run agent-descriptors:drift -- --source <game-api-fixture>`; every
+  build re-checks the digests.
 
 ## Migration