@idosgames/mcp 0.1.2 → 0.1.3

package/registry/skills/idosgames-agent-debug-surface.json

@@ -0,0 +1,6 @@
+{
+  "name": "idosgames-agent-debug-surface",
+  "description": "Make a module observable and controllable by the AI Coder's agent through ctx.exposeToAgent — the ModuleAgentApi contract (state, actions, describeActions) that backs the GetGameState and GameAction tools. Read it BEFORE writing any module that renders into a canvas (three.js, Phaser, Pixi, raw WebGL/2d) — publishing the surface and avoiding Pointer Lock are part of building one. Also use it whenever a rendered game has to be debugged or verified in the live preview, when the agent reports \"the DOM shows nothing about this game\", or when a developer adds player/world state or agent-drivable actions to a module.",
+  "content": "---\nname: idosgames-agent-debug-surface\ndescription: >-\n  Make a module observable and controllable by the AI Coder's agent through ctx.exposeToAgent — the\n  ModuleAgentApi contract (state, actions, describeActions) that backs the GetGameState and\n  GameAction tools. Read it BEFORE writing any module that renders into a canvas (three.js, Phaser,\n  Pixi, raw WebGL/2d) — publishing the surface and avoiding Pointer Lock are part of building one.\n  Also use it whenever a rendered game has to be debugged or verified in the live preview, when the\n  agent reports \"the DOM shows nothing about this game\", or when a developer adds player/world\n  state or agent-drivable actions to a module.\n---\n\n# Making a module visible to the agent (`ctx.exposeToAgent`)\n\nThe agent inspects a running app by reading its DOM. A rendered game has no DOM to read — it is one\n`<canvas>` — so what the game _is doing_ is invisible unless the module says so itself.\n\n`ctx.exposeToAgent` closes that gap. The module publishes a small debug surface; the preview probe\npicks it up and the agent reaches it with two tools:\n\n- **GetGameState** — reads `state()` of every module that opted in, plus the list of its actions.\n- **GameAction** — calls one action and returns the state after it.\n\n## What the agent already sees without you\n\n`GetGameState` always returns an **automatic layer** first, measured by the preview probe with no\ncooperation from the game: which canvas and graphics context exist, fps, frames and draw calls,\na sparse grid of pixels read back from the frame, and the host's own state (login screen vs game).\n\nWhere the engine can be identified, its own numbers come too:\n\n| Engine   | How it is found                                                                 | What you get                                                                                                      |\n| -------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| three.js | `__THREE_DEVTOOLS__` — three announces itself                                   | renderer info (draw calls, triangles, textures), scene object/mesh/light counts, camera position + look direction |\n| PixiJS 8 | `__PIXI_APP_INIT__` / `__PIXI_RENDERER_INIT__` — Pixi announces itself          | stage display objects, hidden count, tree depth, ticker fps, renderer backend and resolution                      |\n| Phaser   | looked up in the page globals — Phaser has no such channel in its release build | scenes with active/visible flags, per-scene object counts, main camera scroll and zoom, loop fps                  |\n\n**Phaser needs one line from you.** Phaser assigns `window.PHASER_GAME` itself, but only in its\ndebug build — the release build shipped by npm has that branch stripped, so a Phaser game is\ninvisible to any observer until it hands itself over. Verified live: without the line the preview\nreports no engine at all; with it, scenes, object counts, camera and loop fps all come through.\n\n```ts\nthis.game = new Phaser.Game({/* … */});\n// Makes the game observable in the live preview, which reads this exact global.\n(globalThis as unknown as Record<string, unknown>).PHASER_GAME = this.game;\n```\n\nDelete it again in `destroy()` (`if (globals.PHASER_GAME === this.game) delete globals.PHASER_GAME`)\n— the Mode Router destroys a suspended mode, and a stale reference would show a game that no longer\nexists. `modules/idle-rpg` does exactly this; copy it.\n\nNote that the engine layer never replaces the surface below: it reports _scenes and objects_, never\n_what the game means_ — which hero is selected, what the score is, whose turn it is.\n\nThat layer answers \"does it render at all\" — a dead loop, a blank one-colour frame, a player stuck\non the login screen. It cannot answer anything about _gameplay_: where the player is, what the score\nis, why the character fell through the floor. That is what the surface below is for, and why a\ncanvas module is not finished without it.\n\nThe same goes for driving the game. `SendInput` dispatches synthetic keys/clicks and works for\ngames that read plain DOM events, but an engine that gates input on Pointer Lock ignores it —\nPointer Lock is unavailable inside the preview's cross-origin iframe. **Do not gate controls on\nPointer Lock**: support a soft-lock fallback (click the canvas to take control, Escape to release,\nclamp mouse deltas), or the preview is unplayable for the human too. Actions published here always\nwork, because they go through the module's own input path.\n\n## Adding the surface\n\n```ts\nsetup(ctx) {\n  const { scene, agent } = createMyGame();\n  ctx.registerScene(scene);\n  ctx.exposeToAgent(agent);\n}\n```\n\n```ts\nimport type { ModuleAgentApi } from \"@idosgames/module-sdk\";\n\nexport function createMyGameAgentApi(\n  getGame: () => Game | null,\n): ModuleAgentApi {\n  return {\n    state() {\n      const game = getGame();\n      if (!game) return { mounted: false };\n      return {\n        mounted: true,\n        playing: game.running, // на паузе персонаж не двигается — это не баг\n        player: { pos: game.player.pos, health: game.player.health },\n        world: { loadedChunks: game.world.chunks.size },\n      };\n    },\n    actions: {\n      move: async (args) => hold(dirKey(args?.dir), clampMs(args?.ms)),\n      jump: async () => hold(\"Space\", 120),\n    },\n    describeActions: {\n      move: \"Walk: { dir: forward|back|left|right, ms?: number }.\",\n      jump: \"Jump.\",\n    },\n  };\n}\n```\n\nPass a **getter**, not the game object: the scene creates the game in `mount()` and drops it in\n`destroy()`, while the surface is registered once in `setup()`.\n\n## Rules that matter\n\n1. **Actions go through the module's real input path** — intents, command queue, the same key set\n   the player's keyboard fills. A second movement implementation drifts from the real one, and then\n   the agent verifies a game nobody plays.\n2. **`state()` must be cheap, JSON-serializable and free of secrets.** It is called per request and\n   pasted verbatim into an LLM prompt.\n3. **Bound every action.** Clamp durations (a few seconds at most) so the agent cannot \"hold W\" for\n   a minute; reject unknown argument values with a clear error naming the valid ones.\n4. **Nothing destructive.** Deleting a save, spending real currency or resetting progress does not\n   belong here — this surface exists to observe and reproduce, not to administer.\n5. **`describeActions` is the only documentation the agent gets.** One line per action: what it does\n   and which arguments it takes, with units.\n6. **Include the \"am I even running\" flags** (`mounted`, `playing`). Most \"the character does not\n   move\" reports are a paused game, and without those flags the agent goes looking for a physics bug.\n\n## When the module's UI is DOM\n\nA module whose interface is React/DOM (panels, HUD, buttons) needs only a thin surface — the agent\nalready reads that tree and clicks it like a human. Expose what the canvas hides (scene state) and\nleave `actions` empty rather than mirroring buttons the agent can already press.\n\n## Verifying it works\n\nIn the preview, ask the agent something it can only answer by looking: \"where is the player right\nnow?\", \"walk forward for a second and tell me if the position changed\", \"jump and check that the\nplayer lands\". If `GetGameState` answers with the automatic layer but an empty `exposedByGame`, the\nsurface is not wired — check that `exposeToAgent` runs inside `setup()` and that the host is\n`@idosgames/app-shell` (the bridge publishes the registry).\n",
+  "references": []
+}

package/registry/skills/idosgames-getting-started.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-getting-started",
   "description": "Start a new game or app on the iDosGames composable-module architecture: scaffold the host shell and plug in feature modules (board-game, idle-rpg, voxelcraft, …). Use this whenever a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and idosgames-compose-modules (merging several). If pulling modules over MCP, use the @idosgames/mcp tools get_host_scaffold / get_module / get_manifest.",
-  "content": "---\nname: idosgames-getting-started\ndescription: >-\n  Start a new game or app on the iDosGames composable-module architecture: scaffold the host shell\n  and plug in feature modules (board-game, idle-rpg, voxelcraft, …). Use this whenever\n  a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a\n  project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or\n  src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and\n  idosgames-compose-modules (merging several). If pulling modules over MCP, use the @idosgames/mcp\n  tools get_host_scaffold / get_module / get_manifest.\n---\n\n# Getting started (iDosGames composable modules)\n\nAn iDosGames project is **one host shell + N feature modules**. The host owns everything that exists\nonce — the SDK client, login, the React root, the screen, a module registry, and a Mode Router that\nswitches between modules. A module is a library (a game or app) that plugs into the host; it never\ncreates the client, logs in, or owns the root.\n\n## Runtime packages (npm)\n\n- `@idosgames/core` — the SDK client (`createIDosGamesClient`): auth, currency, store, characters,\n  blockchain, ~28 services. See the per-service skills (currency-system, store-system, …).\n- `@idosgames/module-sdk` — the module contract types (`Module`, `ModuleContext`, `EngineScene`,\n  `UiPanel`). See idosgames-module-contract.\n- `@idosgames/react` — shared React glue (`IDosGamesProvider`, `useIDosGamesClient`, `useUserState`,\n  `StatusProvider`, `createControllerContext`).\n- `@idosgames/app-shell` — the host runtime (`mountHost`, the Mode Router, the module registry).\n- `@idosgames/wallet` — optional wallet bridge (EVM/Solana) for on-chain deposits/withdrawals.\n\nInstall the exact versions from `get_manifest` (MCP) or the registry `index.json` `runtimePackages`.\n\n## Project shape\n\n```\nindex.html                 # mounts #app\nsrc/main.tsx               # creates ONE client and calls mountHost({container, client, modules})\nsrc/modules.ts             # the registry: export const modules: Module[] = [ … ]\nsrc/modules/{id}/          # each module's source (from get_module)\n```\n\n`src/main.tsx` (host-owned) is the only place that creates the client — but it does **not** sign in.\n`mountHost` owns sign-in: it replays a previous session (`autoLogin`) and renders the login screen\nwhen there is nothing to replay. Calling a `login*` method here skips that screen for good, taking\n\"switch account\" and wallet sign-in with it:\n\n```ts\nconst client = createIDosGamesClient({ titleID, buildKey, throttleMs: 0 });\n// Do NOT log in here — the host does it.\nmountHost({\n  container: app,\n  client,\n  modules, // from ./modules\n  renderLogin, // optional: your own screen; omitted = a plain guest-only default\n});\n```\n\nWhether a returning player is signed back in silently is the login screen's business, not the\nhost's: it calls `client.auth.setRememberSession(remember)` before a `login*` method. See the\nauthentication skill.\n\n`src/modules.ts` registers what the project composes:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nexport const modules: Module[] = [boardGameModule];\n```\n\n## Steps to scaffold\n\n1. **Host** — write the host scaffold to the project root (`get_host_scaffold`, or copy\n   `templates/host-starter`). Its `src/modules.ts` starts empty → the host shows a \"no modules\" state.\n2. **Bind the Title** — open `src/idos.title.ts` and set `IDOS_TITLE_ID` to the game's canonical\n   Title id (and `IDOS_BUILD_KEY` if the title enforces one). This file is the project's single\n   centralized identity — it is the highest-priority source and the only channel a packaged mobile\n   build, iframe embed, or shared link has. On platform-created projects the platform generates it;\n   on a manually scaffolded project **you fill it yourself**. Do NOT bind the title via `.env.local`\n   (`VITE_IDOS_TITLE_ID`) — that is a local-dev fallback for the raw template only, and it does not\n   travel with the code.\n3. **Pick modules** — `list_modules` / `search`, then `get_module {id}` for each. Write its files\n   into `src/modules/{id}/`.\n4. **Register** — for each module add `import { {camelCase(id)}Module } from \"./modules/{id}\"` and\n   push it into the `modules` array (e.g. `board-game` → `boardGameModule`).\n5. **Install deps** — the union of `runtimePackages` + each module's `dependencies`. Modules bring\n   their own engine (three, phaser); the host brings react/react-dom/app-shell.\n6. **Run** — the host renders a nav-bar when ≥2 modules register a route, and mode-switches between\n   them; a shared HUD panel (`activeOnly:false`) stays visible across all modes.\n\nTo combine multiple genres into one game, see **idosgames-compose-modules**. To write or edit a\nmodule, see **idosgames-module-contract**.\n\n## Two MCP surfaces: game CODE vs. a Title's live DATA\n\nThe platform exposes **two independent MCP servers** — don't confuse them:\n\n- **`@idosgames/mcp`** (this one) serves the **CODE registry**. Use it to WRITE a game's source:\n  `get_host_scaffold`, `list_modules` / `search` / `get_module`, `get_manifest`, `list_skills` /\n  `get_skill`. Transport: stdio (`npx -y @idosgames/mcp`). Its registry is bundled offline; to use the\n  hosted copy set `IDOSGAMES_REGISTRY_URL=https://cloud.idosgames.com/drive/registry/latest` — a **base**\n  the loader appends `/index.json`, `/modules/{id}.json`, etc. to (the base itself is not fetchable on\n  R2; open `.../latest/index.json` to browse the catalog). Read-only, no auth. It never reads or changes\n  a live Title's data.\n- **The Title-configuration MCP** (a separate backend server) owns a **live Title's DATA**. Use it to\n  read/write the Title's `TitlePublicConfiguration` (`get_<field>` / `save_<field>`, or the whole\n  model) and to generate assets (`generate_image` / `generate_audio` / `generate_text` /\n  `generate_three_d` / `generate_video`). Transport: HTTP JSON-RPC at\n  `POST https://site.idosgames.com/api/v2/mcp`, authenticated with an `X-MCP-API-Key` header (the\n  publisher issues the key per Title on platform.idosgames.com); every tool call takes a `title_id`\n  argument. Connect it as an HTTP MCP server — and keep the key out of committed config via env\n  expansion:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"idosgames-title\": {\n        \"type\": \"http\",\n        \"url\": \"https://site.idosgames.com/api/v2/mcp\",\n        \"headers\": { \"X-MCP-API-Key\": \"${IDOS_MCP_API_KEY}\" }\n      }\n    }\n  }\n  ```\n\n  Configuring a **fresh (empty) Title** so a game can actually run against it (currencies → game\n  loop → bots) is its own checklist: see **idosgames-title-bootstrap**.\n\nRule of thumb: **game CODE → `@idosgames/mcp`; a Title's live config DATA and generated ASSETS → the\nbackend `v2/mcp` server.** Scaffolding a project and configuring/populating the Title it runs as are\ntwo different jobs on two different servers — connect the one that matches the task (or both).\n",
+  "content": "---\nname: idosgames-getting-started\ndescription: >-\n  Start a new game or app on the iDosGames composable-module architecture: scaffold the host shell\n  and plug in feature modules (board-game, idle-rpg, voxelcraft, …). Use this whenever\n  a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a\n  project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or\n  src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and\n  idosgames-compose-modules (merging several). If pulling modules over MCP, use the @idosgames/mcp\n  tools get_host_scaffold / get_module / get_manifest.\n---\n\n# Getting started (iDosGames composable modules)\n\nAn iDosGames project is **one host shell + N feature modules**. The host owns everything that exists\nonce — the SDK client, login, the React root, the screen, a module registry, and a Mode Router that\nswitches between modules. A module is a library (a game or app) that plugs into the host; it never\ncreates the client, logs in, or owns the root.\n\n## Runtime packages (npm)\n\n- `@idosgames/core` — the SDK client (`createIDosGamesClient`): auth, currency, store, characters,\n  blockchain, ~28 services. See the per-service skills (currency-system, store-system, …).\n- `@idosgames/module-sdk` — the module contract types (`Module`, `ModuleContext`, `EngineScene`,\n  `UiPanel`). See idosgames-module-contract.\n- `@idosgames/react` — shared React glue (`IDosGamesProvider`, `useIDosGamesClient`, `useUserState`,\n  `StatusProvider`, `createControllerContext`).\n- `@idosgames/app-shell` — the host runtime (`mountHost`, the Mode Router, the module registry).\n- `@idosgames/wallet` — optional wallet bridge (EVM/Solana) for on-chain deposits/withdrawals.\n\nInstall the exact versions from `get_manifest` (MCP) or the registry `index.json` `runtimePackages`.\n\n## Project shape\n\n```\nindex.html                 # mounts #app\nsrc/main.tsx               # creates ONE client and calls mountHost({container, client, modules})\nsrc/modules.ts             # the registry: export const modules: Module[] = [ … ]\nsrc/modules/{id}/          # each module's source (from get_module)\n```\n\n`src/main.tsx` (host-owned) is the only place that creates the client — but it does **not** sign in.\n`mountHost` owns sign-in: it replays a previous session (`autoLogin`) and renders the login screen\nwhen there is nothing to replay. Calling a `login*` method here skips that screen for good, taking\n\"switch account\" and wallet sign-in with it:\n\n```ts\nconst client = createIDosGamesClient({ titleID, buildKey, throttleMs: 0 });\n// Do NOT log in here — the host does it.\nmountHost({\n  container: app,\n  client,\n  modules, // from ./modules\n  renderLogin, // optional: your own screen; omitted = a plain guest-only default\n});\n```\n\nWhether a returning player is signed back in silently is the login screen's business, not the\nhost's: it calls `client.auth.setRememberSession(remember)` before a `login*` method. See the\nauthentication skill.\n\n`src/modules.ts` registers what the project composes:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nexport const modules: Module[] = [boardGameModule];\n```\n\n## Steps to scaffold\n\n1. **Host** — write the host scaffold to the project root (`get_host_scaffold`, or copy\n   `templates/host-starter`). Its `src/modules.ts` starts empty → the host shows a \"no modules\" state.\n2. **Bind the Title** — open `src/idos.title.ts` and set `IDOS_TITLE_ID` to the game's canonical\n   Title id (and `IDOS_BUILD_KEY` if the title enforces one). This file is the project's single\n   centralized identity — it is the highest-priority source and the only channel a packaged mobile\n   build, iframe embed, or shared link has. On platform-created projects the platform generates it;\n   on a manually scaffolded project **you fill it yourself**. Do NOT bind the title via `.env.local`\n   (`VITE_IDOS_TITLE_ID`) — that is a local-dev fallback for the raw template only, and it does not\n   travel with the code.\n3. **Pick modules** — `list_modules` / `search`, then `get_module {id}` for each. Write its files\n   into `src/modules/{id}/`.\n4. **Register** — for each module add `import { {camelCase(id)}Module } from \"./modules/{id}\"` and\n   push it into the `modules` array (e.g. `board-game` → `boardGameModule`).\n5. **Install deps** — the union of `runtimePackages` + each module's `dependencies`. Modules bring\n   their own engine (three, phaser); the host brings react/react-dom/app-shell.\n6. **Run** — the host renders a nav-bar when ≥2 modules register a route, and mode-switches between\n   them; a shared HUD panel (`activeOnly:false`) stays visible across all modes.\n\nTo combine multiple genres into one game, see **idosgames-compose-modules**. To write or edit a\nmodule, see **idosgames-module-contract**.\n\n## Where state lives (decide this before writing the first save)\n\nThe project is client-side code in the player's browser. `localStorage`, module fields, and React\nstate are **not storage** — nothing there survives a device change, and nothing there is trusted.\n\n1. **A dedicated module owns it?** Use that module. Currencies, inventory, quests, characters,\n   leaderboards, store purchases each have a service that enforces the rules server-side.\n2. **Otherwise, per-player data → `client.userCustomData`** — buckets `Private`/`Public` are\n   client-writable (settings, cosmetics), `ReadOnly`/`Internal` are server-only. Anything a player\n   could cheat by editing goes in the server-only buckets. See **user-custom-data**.\n3. **Shared by all players → `client.titleCustomData`** (event state, global counters, server\n   thresholds, feature toggles). Read-only for clients. See **title-custom-data**.\n4. **Writing any of the server-only data, or any rule the player must not be able to fake** →\n   a CloudCode handler, called with `client.cloudCode.execute(...)`. See **cloud-code**.\n\n## Two MCP surfaces: game CODE vs. a Title's live DATA\n\nThe platform exposes **two independent MCP servers** — don't confuse them:\n\n- **`@idosgames/mcp`** (this one) serves the **CODE registry**. Use it to WRITE a game's source:\n  `get_host_scaffold`, `list_modules` / `search` / `get_module`, `get_manifest`, `list_skills` /\n  `get_skill`. Transport: stdio (`npx -y @idosgames/mcp`). Its registry is bundled offline; to use the\n  hosted copy set `IDOSGAMES_REGISTRY_URL=https://cloud.idosgames.com/drive/registry/latest` — a **base**\n  the loader appends `/index.json`, `/modules/{id}.json`, etc. to (the base itself is not fetchable on\n  R2; open `.../latest/index.json` to browse the catalog). Read-only, no auth. It never reads or changes\n  a live Title's data.\n- **The Title-configuration MCP** (a separate backend server) owns a **live Title's DATA**. Use it to\n  read/write the Title's `TitlePublicConfiguration` (`get_<field>` / `save_<field>`, or the whole\n  model) and to generate assets (`generate_image` / `generate_audio` / `generate_text` /\n  `generate_three_d` / `generate_video`). Transport: HTTP JSON-RPC at\n  `POST https://site.idosgames.com/api/v2/mcp`, authenticated with an `X-MCP-API-Key` header (the\n  publisher issues the key per Title on platform.idosgames.com); every tool call takes a `title_id`\n  argument. Connect it as an HTTP MCP server — and keep the key out of committed config via env\n  expansion:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"idosgames-title\": {\n        \"type\": \"http\",\n        \"url\": \"https://site.idosgames.com/api/v2/mcp\",\n        \"headers\": { \"X-MCP-API-Key\": \"${IDOS_MCP_API_KEY}\" }\n      }\n    }\n  }\n  ```\n\n  Configuring a **fresh (empty) Title** so a game can actually run against it (currencies → game\n  loop → bots) is its own checklist: see **idosgames-title-bootstrap**.\n\nRule of thumb: **game CODE → `@idosgames/mcp`; a Title's live config DATA and generated ASSETS → the\nbackend `v2/mcp` server.** Scaffolding a project and configuring/populating the Title it runs as are\ntwo different jobs on two different servers — connect the one that matches the task (or both).\n",
   "references": []
 }

package/registry/skills/idosgames-module-contract.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-module-contract",
   "description": "Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk: the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route registration, and the shared controller-box bridge between an imperative scene and React panels. Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg, voxelcraft), or asks about defineModule, registerScene/registerPanel/registerRoute, activate/suspend, SceneMountContext, or the {camelCase(id)}Module export convention.",
-  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft), or asks about defineModule, registerScene/registerPanel/registerRoute,\n  activate/suspend, SceneMountContext, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (cross-module bus) · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // nav/mode entry\n  },\n});\n```\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
+  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft), or asks about defineModule, registerScene/registerPanel/registerRoute,\n  activate/suspend, SceneMountContext, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (cross-module bus) · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // nav/mode entry\n  },\n});\n```\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\nA module that registers a scene MUST also publish its debug surface — `ctx.exposeToAgent({ state,\nactions, describeActions })` — and must NOT gate controls on Pointer Lock (unavailable in the\npreview's cross-origin iframe). Nothing inside a `<canvas>` is observable from the DOM, so without\nthe surface neither the AI Coder nor a human reviewer can tell what the game is doing. See the\n`idosgames-agent-debug-surface` skill.\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
   "references": []
 }

package/registry/skills/quest-system.json

@@ -1,11 +1,11 @@
 {
   "name": "quest-system",
-  "description": "Build a quest / daily-task system in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.quest (QuestService): load quest and cycle definitions, load the player's quest progress state, add progress toward a metric, claim a completed quest's reward, claim a points-track milestone reward, claim a group-completion (grand) reward, and refresh cycles (dailies/ weeklies) forward. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants daily/weekly quest screens, task lists, objective/progress trackers, battle-pass-style points tracks, milestone reward ladders, quest-group completion bonuses, or otherwise touches client.quest, QuestService, QuestDefinitions, UserQuestState, QuestPointsTrackView, or MilestoneDefinition — even if they don't name the module explicitly.",
-  "content": "---\nname: quest-system\ndescription: >-\n  Build a quest / daily-task system in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.quest (QuestService): load quest and cycle\n  definitions, load the player's quest progress state, add progress toward a\n  metric, claim a completed quest's reward, claim a points-track milestone\n  reward, claim a group-completion (grand) reward, and refresh cycles (dailies/\n  weeklies) forward. Use this whenever the user is working in the iDosGames TS\n  SDK or its game templates (board-game, idle-rpg) and wants daily/weekly quest\n  screens, task lists, objective/progress trackers, battle-pass-style points\n  tracks, milestone reward ladders, quest-group completion bonuses, or\n  otherwise touches client.quest, QuestService, QuestDefinitions,\n  UserQuestState, QuestPointsTrackView, or MilestoneDefinition — even if they\n  don't name the module explicitly.\n---\n\n# Quest system (iDosGames TS SDK)\n\nThe Quest module runs a title's task/quest board: dailies, weeklies, permanent\nquests, and one-off event quests, each made of objectives that accrue progress\ntoward a metric. Everything is **server-authoritative**: the backend tracks\nprogress, decides when a quest is `Completed`, and validates every claim. The\nclient asks the backend to report progress or claim a reward, and the SDK\nmirrors the confirmed result into a local cache your UI reads. You never\ncompute quest status yourself — you call a method, check the result, and\nrender from the cache.\n\nThis skill is for **using** the production `QuestService`, not for porting or\nextending it. If a call is rejected, that's the backend enforcing a rule\n(objective not met, already claimed, prerequisite quest incomplete) — surface\nthe error, don't try to reproduce the check client-side.\n\n## The two data shapes\n\nKeep these straight; every recipe below is just moving between them.\n\n1. **Definitions** (config, same for every player) — the title's catalog of\n   quest cycles (dailies/weeklies/permanent), the quests inside each cycle,\n   their objectives/rewards/prerequisites, and the cycle's milestone points\n   track and group-completion grand rewards. Fetched with\n   `getQuestDefinitions()`.\n2. **User quest state** (state, per player) — this player's live progress:\n   which cycle instances are active, each quest's `Status` and per-objective\n   `CurrentValue`, and the points-track balance/claimed-milestone ids for each\n   cycle. Fetched with `getUserQuestState()`.\n\nA quest lives either **inside a cycle** (`CycleID` set — dailies, weeklies,\nseasonal) or as a **permanent quest** (no `CycleID` — a one-time or\nalways-available quest, e.g. onboarding). Most methods take an optional/blank\n`CycleID` to address either; the cache keeps them in separate buckets\n(`Quest.Cycles[cycleID]` vs `Quest.PermanentQuests`).\n\nThree distinct reward mechanisms — don't conflate them:\n\n- **Quest reward** — the `Reward` on one `QuestDefinition`, claimed once that\n  quest's objectives are all met (`Status: \"Completed\"`), via\n  `claimQuestReward`. Moves the quest to `\"Claimed\"`.\n- **Milestone reward** — a rung on a cycle's **points track** (backend/config\n  comments call this \"Achievements\"): claiming a quest with `PointsReward > 0`\n  also grants that many points into a per-cycle point balance — a dedicated\n  `EventTokenType.Quest` token, tracked separately from any single quest's own\n  claim status — in the same atomic transaction as the quest claim. Each\n  `MilestoneDefinition` in `Cycle.Milestones` pays out once that balance's\n  lifetime total crosses its `RequiredProgress`. Claimed via\n  `claimMilestoneReward`. This is the battle-pass-style ladder — a player can\n  hit a milestone from points earned across many different quest claims, and\n  milestone eligibility never re-checks any individual quest's status.\n- **Group-completion reward** — a grand bonus in `Cycle.GroupCompletions` that\n  pays out once at least `RequiredCompletedQuests` quests sharing a `GroupID`\n  have reached `\"Completed\"` (not necessarily claimed). Claimed via\n  `claimGroupCompletionReward`.\n\nAll three can be in flight simultaneously for the same cycle — completing one\nquest can push its points into the milestone track, count toward its group's\ncompletion total, _and_ be individually claimable, all at once.\n\n**Progress** is reported with `addQuestProgress(metricID, progressValue)` — a\ngeneric counter keyed by `MetricID`, not by quest id. The backend fans one\nmetric update out to every objective across every active quest that listens to\nthat `MetricID` (per each objective's own `AggregationMethod`/filters), and\nreturns the list of quests/objectives that changed. You call this from your\ngame-loop code wherever the underlying action happens (e.g. \"enemy defeated\" →\n`addQuestProgress(\"EnemiesDefeated\", 1)`), not once per quest.\n\n**Cycles** (dailies/weeklies) roll forward on a schedule. `getUserQuestState`\ndefaults to auto-refreshing stale cycles for you (`autoRefreshCycles = true`);\ncall `refreshQuestCycles()` directly when you want to force-check for a new\ncycle boundary (e.g. app resumed from background) without re-fetching the\nwhole state.\n\nFor the full field-by-field shape of Definitions and state (objective sources,\nprerequisite modes, schedule/limit/gate blocks, the points-track/milestone\nplumbing), read [references/data-model.md](references/data-model.md). You do\n**not** need it to call the methods — only to drive richer UI off the config.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst quest = client.quest; // the QuestService\n```\n\nEvery quest method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args), `\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again\ninside the throttle window), `\"connection\"` (transient, offer Retry),\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\n`error` carries the human-readable reason, e.g. \"Quest is not completed\",\n\"Already claimed\", \"Prerequisite quest not completed\").\n\n| Method                                                   | Purpose                                                              | `data` on success                                                          |\n| -------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| `getQuestDefinitions()`                                  | Load the title's quest/cycle catalog (config).                       | `QuestDefinitions`                                                         |\n| `getUserQuestState(autoRefreshCycles?)`                  | Load this player's quest progress (state). Defaults to auto-refresh. | `GetUserQuestStateResponse` (`State`, `PointsTracks`)                      |\n| `refreshQuestCycles()`                                   | Force-check cycle boundaries and roll any stale cycle forward.       | `SuccessResponse`                                                          |\n| `addQuestProgress(metricID, progressValue)`              | Report progress on a metric; fans out to every listening objective.  | `AddQuestProgressResponse` (`Updates`)                                     |\n| `claimQuestReward(questID, cycleID?)`                    | Claim a single completed quest's reward.                             | `ClaimQuestRewardResponse` (`NewStatus`, `Resources`)                      |\n| `claimQuestRewardsBatch(quests)`                         | Claim several quests' rewards in one atomic call.                    | `BatchItemResult<ClaimQuestRewardResponse>[]`                              |\n| `claimMilestoneReward(cycleID, milestoneID)`             | Claim one points-track milestone reward for a cycle.                 | `ClaimMilestoneRewardResponse` (`PointsTotalEarned`, `Resources`)          |\n| `claimMilestoneRewardsBatch(milestones)`                 | Claim several milestone rewards in one atomic call.                  | `BatchItemResult<ClaimMilestoneRewardResponse>[]`                          |\n| `claimGroupCompletionReward(cycleID, groupCompletionID)` | Claim a cycle's group-completion grand reward.                       | `ClaimGroupCompletionRewardResponse` (`CompletedGroupQuests`, `Resources`) |\n\n`claimQuestReward` / `claimMilestoneReward` / `claimGroupCompletionReward` all\naccept a blank/absent `CycleID` to mean a permanent quest (quest claim only —\nmilestones and group-completions always belong to a cycle). Each mints its own\n`RelatedEntityID` internally for idempotency; you don't supply one.\n\n`claimQuestRewardsBatch(quests)` takes `QuestClaimRef[]` (`{ CycleID?,\nQuestID? }`, deduped by `CycleID`+`QuestID`); `claimMilestoneRewardsBatch(milestones)`\ntakes `MilestoneClaimRef[]` (`{ CycleID?, MilestoneID? }`, deduped by\n`CycleID`+`MilestoneID`).\n\nOn success, each method also **mirrors the confirmed change into the cache and\nemits an event** — you don't apply anything by hand. Granted resources\n(currencies, items) ride along in `data.Resources` (a `ResourceOperation`, see\n[ResourceModels](../../../packages/core/src/models/_shared/ResourceModels.ts))\nand are already applied to the cached balances, so read updated balances\nstraight from the cache.\n\n## Reading state and reacting to changes\n\nDrive the UI off the cache, not off one-off return values — that way every\nscreen stays consistent no matter which code path changed things.\n\n```ts\n// Quest progress (only present after getUserQuestState()):\nconst cycleA = client.data.user.state?.Quest?.Cycles?.[\"cycleA\"];\ncycleA?.Quests?.[\"q1\"]?.Status; // \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\"\ncycleA?.Quests?.[\"q1\"]?.Objectives?.[\"obj1\"]?.CurrentValue;\ncycleA?.ClaimedGroupCompletionIDs; // string[]\n\nconst permanentQuest =\n  client.data.user.state?.Quest?.PermanentQuests?.[\"intro\"];\n\n// Points track (balance + claimed milestone ids), keyed by cycleID (or\n// \"cycleID:instanceKey\" for recurring cycles) — read with the helper so you\n// don't have to know the exact composite key:\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\npoints?.Balance?.Current; // current points balance this cycle\npoints?.Balance?.TotalEarned;\npoints?.Milestone?.ClaimedIDs; // milestone ids already claimed\n\n// Definitions (cached after getQuestDefinitions()):\nimport type { QuestDefinitions } from \"@idosgames/core\";\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `quest:definitionsLoaded` → `QuestDefinitions`\n- `quest:userStateLoaded` → `UserQuestState`\n- `quest:cyclesRefreshed` → `void`\n- `quest:progressAdded` → `AddQuestProgressResponse`\n- `quest:rewardClaimed` → `ClaimQuestRewardResponse`\n- `quest:rewardsClaimedBatch` → `ClaimQuestRewardsBatchResponse`\n- `quest:milestoneClaimed` → `ClaimMilestoneRewardResponse`\n- `quest:milestonesClaimedBatch` → `ClaimMilestoneRewardsBatchResponse`\n- `quest:groupCompletionClaimed` → `ClaimGroupCompletionRewardResponse`\n\nThe coarse `user:questUpdated` (and `user:anyUpdated`) also fire on any quest\ncache write — handy for a \"re-render everything\" hook.\n\n```ts\nconst off = client.on(\"quest:progressAdded\", (r) => {\n  for (const u of r.Updates ?? []) {\n    console.log(`${u.QuestID} objective ${u.ObjectiveID} -> ${u.NewValue}`);\n  }\n});\n// later: off();\n```\n\n## Recipes\n\n### Load the board and render quest cards\n\n```ts\nawait client.quest.getQuestDefinitions();\nawait client.quest.getUserQuestState();\n\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\nconst cycles = client.data.user.state?.Quest?.Cycles ?? {};\n\nfor (const [cycleID, cycleDef] of Object.entries(defs?.Cycles ?? {})) {\n  const userCycle = cycles[cycleID];\n  for (const [questID, questDef] of Object.entries(defs?.Quests ?? {})) {\n    if (!questDef.CycleIDs?.includes(cycleID)) continue;\n    const progress = userCycle?.Quests?.[questID];\n    // progress?.Status drives the card state: not-started/Active/Completed/Claimed.\n    // questDef.Objectives + progress?.Objectives drives the progress bar(s).\n  }\n}\n```\n\nA quest's `CycleIDs` lists every cycle it can appear in; cross-reference\nagainst `defs.Cycles` to know which are currently relevant. A quest absent from\n`userCycle.Quests` simply hasn't accrued any progress yet — treat it as\n`\"Active\"` with zero progress, not as an error. The backend creates a quest's\nprogress record (and each objective's) lazily, the first time it accrues\nsomething — it never pre-populates the catalog with zeros.\n\n### Report progress, then claim\n\n```ts\n// Wherever the underlying game action happens:\nconst prog = await client.quest.addQuestProgress(\"EnemiesDefeated\", 1);\nif (!prog.ok) return showError(prog.error);\n\nfor (const u of prog.data.Updates ?? []) {\n  if (u.Status === \"Completed\") {\n    // Surface a \"claim\" button for u.QuestID / u.CycleID now.\n  }\n}\n```\n\n```ts\n// Later, when the player taps Claim:\nconst claim = await client.quest.claimQuestReward(\"q1\", \"cycleA\");\nif (!claim.ok) return showError(claim.error); // e.g. \"Quest is not completed\", \"Already claimed\"\n// cache now shows q1 as \"Claimed\"; balances already credited.\n```\n\nClaiming before every objective is met, or claiming twice, both fail with\n`reason: \"server\"` — the quest must be `\"Completed\"` and not already\n`\"Claimed\"`. There's no client-side shortcut to check this ahead of time beyond\nreading the cached `Status` you already have.\n\nOnly objectives configured with `Source: \"ClientApi\"` can be advanced this way;\nan unrecognized `MetricID` fails with `\"MetricID not allowed for ClientApi\"`.\nNever send an inflated `ProgressValue` \"to be safe\" — if a matching objective\ndeclares `MaxProgressPerCall`, the backend compares your raw value against it\nand **bans the account** on a violation (`\"User banned: Value exceeds\nMaxValuePerCall\"`); it does not just clamp and continue.\n\n### Claim a milestone once the points track crosses a rung\n\n```ts\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\nconst claimedAlready = points?.Milestone?.ClaimedIDs?.includes(\"m1\") ?? false;\n\nif (\n  !claimedAlready &&\n  (points?.Balance?.Current ?? 0) >= /* milestone.RequiredProgress */ 100\n) {\n  const res = await client.quest.claimMilestoneReward(\"cycleA\", \"m1\");\n  if (!res.ok) return showError(res.error);\n  res.data.PointsTotalEarned; // lifetime points earned this cycle, for display\n}\n```\n\nMilestone eligibility is judged against the points token's **lifetime total**\n(`Balance.TotalEarned`, mirrored into `PointsCurrent`/`PointsTotalEarned` on\n`QuestPointsTrackView` — for this token they're always equal, since points are\nonly ever granted, never spent). Points land in that balance when a quest with\n`PointsReward > 0` is **claimed** (`claimQuestReward`/batch) — completing a\nquest alone does not add points, claiming it does, in the same atomic\ntransaction as the quest's own reward. So a player reaches milestone `m1` by\nclaiming enough individual quest rewards across the cycle — milestone claiming\nis independent of any _single_ quest's claim, but not of claiming in general.\n\n### Claim a group-completion grand reward\n\n```ts\nconst res = await client.quest.claimGroupCompletionReward(\n  \"cycleA\",\n  \"dailyGroupBonus\",\n);\nif (!res.ok) return showError(res.error); // e.g. \"not enough quests completed in group\"\nres.data.CompletedGroupQuests; // e.g. 3\nres.data.RequiredGroupQuests; // e.g. 3\n```\n\nEligibility counts quests in the group that reached `\"Completed\"` **or**\n`\"Claimed\"` — you don't need to claim every quest's own reward first, just\nfinish them. The required count is `RequiredCompletedQuests` if set, otherwise\n**every** quest currently in that group/cycle (0 means \"all\"). This is\nrecomputed live against the current catalog at claim time (not a snapshot from\nwhenever the player finished the quests), so a group whose quest list changed\nafter the player completed them can shift the totals. Once claimed, the id is\nrecorded in `cycle.ClaimedGroupCompletionIDs` — check that list to hide an\nalready-claimed banner.\n\n### Batch claim several quests/milestones at once\n\n```ts\nconst res = await client.quest.claimQuestRewardsBatch([\n  { CycleID: \"cycleA\", QuestID: \"q1\" },\n  { CycleID: \"cycleA\", QuestID: \"q2\" },\n  { QuestID: \"intro\" }, // permanent quest: CycleID omitted\n]);\nif (!res.ok) return showError(res.error);\nfor (const item of res.data) {\n  if (item.Success) applyOk(item.Id);\n  else showItemError(item.Id, item.Error); // this one was rejected\n}\n```\n\nBatch results are **partial-aware**: the outer `res.ok` tells you the call ran;\neach element's `Success`/`Error` tells you whether that item applied — one\nalready-claimed quest in the batch doesn't sink the others. `claimMilestoneRewardsBatch`\nworks the same way with `MilestoneClaimRef[]`.\n\n### Force a cycle refresh (e.g. on app resume)\n\n```ts\nconst res = await client.quest.refreshQuestCycles();\nif (res.ok) {\n  await client.quest.getUserQuestState(); // reload to pick up the new cycle instance\n}\n```\n\n`getUserQuestState()` already auto-refreshes cycles by default\n(`autoRefreshCycles: true`), so most apps never need to call this directly —\nreach for it when you want to roll cycles forward (e.g. after detecting a\nday/week boundary while the app was backgrounded) without waiting on a full\nstate reload, or want the two steps as separate UI beats (spinner → \"New\nquests!\" toast).\n\n## Gotchas\n\n- **Progress is reported by metric, not by quest.** `addQuestProgress` doesn't\n  target a quest id — it fans one `MetricID` update out to every objective\n  across every active quest (and cycle) that listens to it. Call it once per\n  underlying game action, not once per quest you think might care.\n- **Claiming has three independent tracks.** A quest's own `Reward`, its\n  cycle's points-track `Milestones`, and its group's `GroupCompletions` are\n  claimed through three different methods and three different cache locations\n  (`Quest.Cycles[...].Quests`, `EventToken.Quest`, `Quest.Cycles[...]\n.ClaimedGroupCompletionIDs`). Completing a quest can make all three\n  claimable at once — don't assume claiming one auto-claims the others.\n- **Milestone/points state lives in the event-token cache, not `Quest`.**\n  `client.data.user.state?.Quest` holds quest/objective progress; the points\n  balance and claimed-milestone ids live at\n  `client.data.user.state?.EventToken?.Quest`, keyed by `cycleID` or\n  `\"cycleID:instanceKey\"` for recurring cycles. Use the\n  `client.data.user.getQuestPointsProgress(cycleID)` helper instead of\n  indexing the bucket yourself — it normalizes the composite key for you.\n- **Guard against double-submit.** Each call mints a fresh idempotency key\n  (`RelatedEntityID`), so two separate calls are two real operations — a\n  double-clicked \"Claim\" can attempt to claim twice (the second simply fails\n  as already-claimed, but don't rely on that for UX). Disable the control\n  while a call is in flight. Firing the same endpoint again within the\n  throttle window (default 600 ms) is rejected with `reason: \"throttled\"`\n  rather than duplicated.\n- **`RequiredQuestIDs` can gate progress, not just claiming.** A quest's\n  `PrerequisiteMode` decides whether unmet prerequisites block progress from\n  accruing at all (`BlockProgressAndClaim`) or only block the final claim\n  (`BlockClaimOnly`) — check which mode a quest uses before assuming progress\n  bars will move.\n- **Batch charges/prereqs are evaluated per item, independently.** Unlike some\n  other modules' batch upgrades, quest/milestone batch claims aren't chained —\n  each item is judged against state at the start of the call, so claiming\n  `q1` and `q2` in the same batch where `q2` requires `q1` completed (not\n  claimed) still works, but don't expect claim-order effects within one batch\n  call.\n- **Cycles roll forward wholesale, not incrementally.** When a cycle's schedule\n  window rotates (e.g. midnight UTC for a daily), the server replaces that\n  cycle's entire `Quests` map and `ClaimedGroupCompletionIDs` with a fresh,\n  empty state — there is no partial carry-over of yesterday's progress. Always\n  call `getUserQuestState()` (or `refreshQuestCycles()` + a reload) after\n  detecting a boundary rather than trusting a stale cached cycle.\n- **Cache patches for an unknown cycle silently no-op.** `claimQuestReward` and\n  `claimGroupCompletionReward` only patch the local cache if that `CycleID`\n  already exists in `client.data.user.state.Quest.Cycles` — if you call them\n  for a cycle the client hasn't loaded yet (e.g. right after a cold start with\n  a stale cache), the call still succeeds server-side but the UI won't reflect\n  it until you `getUserQuestState()` again. Load state before wiring up claim\n  buttons.\n- **Render from the cache, handle the error from the result.** The happy path\n  updates the cache + emits an event; the failure path gives you `reason` +\n  `error`. Use `reason` to decide behavior (retry on `\"connection\"`, re-auth on\n  `\"unauthorized\"`, toast the `error` on `\"server\"`).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and state\nfield, the objective/prerequisite/schedule/limit/gate blocks, and how the\npoints-track and milestone plumbing ties into the shared event-token cache.\nRead it when building config-driven UI (objective progress bars, milestone\nladders, cycle countdowns) or when an error message points at a config rule you\nneed to understand.\n",
+  "description": "",
+  "content": "---\r\nname: quest-system\r\ndescription: >-\r\n  Build a quest / daily-task system in a game on the iDosGames TypeScript SDK\r\n  (@idosgames/core) via client.quest (QuestService): load quest and cycle\r\n  definitions, load the player's quest progress state, add progress toward a\r\n  metric, claim a completed quest's reward, claim a points-track milestone\r\n  reward, claim a group-completion (grand) reward, and refresh cycles (dailies/\r\n  weeklies) forward. Use this whenever the user is working in the iDosGames TS\r\n  SDK or its game templates (board-game, idle-rpg) and wants daily/weekly quest\r\n  screens, task lists, objective/progress trackers, battle-pass-style points\r\n  tracks, milestone reward ladders, quest-group completion bonuses, or\r\n  otherwise touches client.quest, QuestService, QuestDefinitions,\r\n  UserQuestState, QuestPointsTrackView, or MilestoneDefinition — even if they\r\n  don't name the module explicitly.\r\n---\r\n\r\n# Quest system (iDosGames TS SDK)\r\n\r\nThe Quest module runs a title's task/quest board: dailies, weeklies, permanent\r\nquests, and one-off event quests, each made of objectives that accrue progress\r\ntoward a metric. Everything is **server-authoritative**: the backend tracks\r\nprogress, decides when a quest is `Completed`, and validates every claim. The\r\nclient asks the backend to report progress or claim a reward, and the SDK\r\nmirrors the confirmed result into a local cache your UI reads. You never\r\ncompute quest status yourself — you call a method, check the result, and\r\nrender from the cache.\r\n\r\nThis skill is for **using** the production `QuestService`, not for porting or\r\nextending it. If a call is rejected, that's the backend enforcing a rule\r\n(objective not met, already claimed, prerequisite quest incomplete) — surface\r\nthe error, don't try to reproduce the check client-side.\r\n\r\n## The two data shapes\r\n\r\nKeep these straight; every recipe below is just moving between them.\r\n\r\n1. **Definitions** (config, same for every player) — the title's catalog of\r\n   quest cycles (dailies/weeklies/permanent), the quests inside each cycle,\r\n   their objectives/rewards/prerequisites, and the cycle's milestone points\r\n   track and group-completion grand rewards. Fetched with\r\n   `getQuestDefinitions()`.\r\n2. **User quest state** (state, per player) — this player's live progress:\r\n   which cycle instances are active, each quest's `Status` and per-objective\r\n   `CurrentValue`, and the points-track balance/claimed-milestone ids for each\r\n   cycle. Fetched with `getUserQuestState()`.\r\n\r\nA quest lives either **inside a cycle** (`CycleID` set — dailies, weeklies,\r\nseasonal) or as a **permanent quest** (no `CycleID` — a one-time or\r\nalways-available quest, e.g. onboarding). Most methods take an optional/blank\r\n`CycleID` to address either; the cache keeps them in separate buckets\r\n(`Quest.Cycles[cycleID]` vs `Quest.PermanentQuests`).\r\n\r\nThree distinct reward mechanisms — don't conflate them:\r\n\r\n- **Quest reward** — the `Reward` on one `QuestDefinition`, claimed once that\r\n  quest's objectives are all met (`Status: \"Completed\"`), via\r\n  `claimQuestReward`. Moves the quest to `\"Claimed\"`.\r\n- **Chain phase** — a cycle whose `Schedule.Mode` is `\"Chained\"` plays its `Phases` one after\r\n  another and then repeats. Each phase is a separate window with its **own** points track and its\r\n  **own** claimed milestones, so a \"season\" of eight weeks is one cycle, not eight. Quests bind to\r\n  phases with `PhaseIDs`. The live phase arrives in `PointsTracks[cycleID].PhaseID`.\r\n- **Milestone reward** — a rung on a cycle's **points track** (backend/config\r\n  comments call this \"Achievements\"): claiming a quest with `PointsReward > 0`\r\n  also grants that many points into a per-cycle point balance — a dedicated\r\n  `EventTokenType.Quest` token, tracked separately from any single quest's own\r\n  claim status — in the same atomic transaction as the quest claim. Each\r\n  `MilestoneDefinition` in `Cycle.Milestones` pays out once that balance's\r\n  lifetime total crosses its `RequiredProgress`. Claimed via\r\n  `claimMilestoneReward`. This is the battle-pass-style ladder — a player can\r\n  hit a milestone from points earned across many different quest claims, and\r\n  milestone eligibility never re-checks any individual quest's status.\r\n- **Group-completion reward** — a grand bonus in `Cycle.GroupCompletions` that\r\n  pays out once at least `RequiredCompletedQuests` quests sharing a `GroupID`\r\n  have reached `\"Completed\"` (not necessarily claimed). Claimed via\r\n  `claimGroupCompletionReward`.\r\n\r\nAll three can be in flight simultaneously for the same cycle — completing one\r\nquest can push its points into the milestone track, count toward its group's\r\ncompletion total, _and_ be individually claimable, all at once.\r\n\r\n**Progress** is reported with `addQuestProgress(metricID, progressValue)` — a\r\ngeneric counter keyed by `MetricID`, not by quest id. The backend fans one\r\nmetric update out to every objective across every active quest that listens to\r\nthat `MetricID` (per each objective's own `AggregationMethod`/filters), and\r\nreturns the list of quests/objectives that changed. You call this from your\r\ngame-loop code wherever the underlying action happens (e.g. \"enemy defeated\" →\r\n`addQuestProgress(\"EnemiesDefeated\", 1)`), not once per quest.\r\n\r\n**Cycles** (dailies/weeklies) roll forward on a schedule. `getUserQuestState`\r\ndefaults to auto-refreshing stale cycles for you (`autoRefreshCycles = true`);\r\ncall `refreshQuestCycles()` directly when you want to force-check for a new\r\ncycle boundary (e.g. app resumed from background) without re-fetching the\r\nwhole state.\r\n\r\nFor the full field-by-field shape of Definitions and state (objective sources,\r\nprerequisite modes, schedule/limit/gate blocks, the points-track/milestone\r\nplumbing), read [references/data-model.md](references/data-model.md). You do\r\n**not** need it to call the methods — only to drive richer UI off the config.\r\n\r\n## Setup\r\n\r\n```ts\r\nimport { createIDosGamesClient } from \"@idosgames/core\";\r\n\r\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\r\nawait client.auth.loginWithDeviceID(); // or any auth.* method\r\n\r\nconst quest = client.quest; // the QuestService\r\n```\r\n\r\nEvery quest method requires an authenticated session. Without one they return\r\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\r\n`client` per player; don't share it across sessions.\r\n\r\n## Methods\r\n\r\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\r\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\r\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\r\nlocal args), `\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again\r\ninside the throttle window), `\"connection\"` (transient, offer Retry),\r\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\r\n`error` carries the human-readable reason, e.g. \"Quest is not completed\",\r\n\"Already claimed\", \"Prerequisite quest not completed\").\r\n\r\n| Method                                                   | Purpose                                                              | `data` on success                                                          |\r\n| -------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |\r\n| `getQuestDefinitions()`                                  | Load the title's quest/cycle catalog (config).                       | `QuestDefinitions`                                                         |\r\n| `getUserQuestState(autoRefreshCycles?)`                  | Load this player's quest progress (state). Defaults to auto-refresh. | `GetUserQuestStateResponse` (`State`, `PointsTracks`)                      |\r\n| `refreshQuestCycles()`                                   | Force-check cycle boundaries and roll any stale cycle forward.       | `SuccessResponse`                                                          |\r\n| `addQuestProgress(metricID, progressValue)`              | Report progress on a metric; fans out to every listening objective.  | `AddQuestProgressResponse` (`Updates`)                                     |\r\n| `claimQuestReward(questID, cycleID?)`                    | Claim a single completed quest's reward.                             | `ClaimQuestRewardResponse` (`NewStatus`, `Resources`)                      |\r\n| `claimQuestRewardsBatch(quests)`                         | Claim several quests' rewards in one atomic call.                    | `BatchItemResult<ClaimQuestRewardResponse>[]`                              |\r\n| `claimMilestoneReward(cycleID, milestoneID)`             | Claim one points-track milestone reward for a cycle.                 | `ClaimMilestoneRewardResponse` (`PointsTotalEarned`, `Resources`)          |\r\n| `claimMilestoneRewardsBatch(milestones)`                 | Claim several milestone rewards in one atomic call.                  | `BatchItemResult<ClaimMilestoneRewardResponse>[]`                          |\r\n| `claimGroupCompletionReward(cycleID, groupCompletionID)` | Claim a cycle's group-completion grand reward.                       | `ClaimGroupCompletionRewardResponse` (`CompletedGroupQuests`, `Resources`) |\r\n\r\n`claimQuestReward` / `claimMilestoneReward` / `claimGroupCompletionReward` all\r\naccept a blank/absent `CycleID` to mean a permanent quest (quest claim only —\r\nmilestones and group-completions always belong to a cycle). Each mints its own\r\n`RelatedEntityID` internally for idempotency; you don't supply one.\r\n\r\n`claimQuestRewardsBatch(quests)` takes `QuestClaimRef[]` (`{ CycleID?,\r\nQuestID? }`, deduped by `CycleID`+`QuestID`); `claimMilestoneRewardsBatch(milestones)`\r\ntakes `MilestoneClaimRef[]` (`{ CycleID?, MilestoneID? }`, deduped by\r\n`CycleID`+`MilestoneID`).\r\n\r\nOn success, each method also **mirrors the confirmed change into the cache and\r\nemits an event** — you don't apply anything by hand. Granted resources\r\n(currencies, items) ride along in `data.Resources` (a `ResourceOperation`, see\r\n[ResourceModels](../../../packages/core/src/models/_shared/ResourceModels.ts))\r\nand are already applied to the cached balances, so read updated balances\r\nstraight from the cache.\r\n\r\n## Reading state and reacting to changes\r\n\r\nDrive the UI off the cache, not off one-off return values — that way every\r\nscreen stays consistent no matter which code path changed things.\r\n\r\n```ts\r\n// Quest progress (only present after getUserQuestState()):\r\nconst cycleA = client.data.user.state?.Quest?.Cycles?.[\"cycleA\"];\r\ncycleA?.Quests?.[\"q1\"]?.Status; // \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\"\r\ncycleA?.Quests?.[\"q1\"]?.Objectives?.[\"obj1\"]?.CurrentValue;\r\ncycleA?.ClaimedGroupCompletionIDs; // string[]\r\n\r\nconst permanentQuest =\r\n  client.data.user.state?.Quest?.PermanentQuests?.[\"intro\"];\r\n\r\n// Points track (balance + claimed milestone ids), keyed by cycleID (or\r\n// \"cycleID:instanceKey\" for recurring cycles) — read with the helper so you\r\n// don't have to know the exact composite key:\r\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\r\npoints?.Balance?.Current; // current points balance this cycle\r\npoints?.Balance?.TotalEarned;\r\npoints?.Milestone?.ClaimedIDs; // milestone ids already claimed\r\n\r\n// Definitions (cached after getQuestDefinitions()):\r\nimport type { QuestDefinitions } from \"@idosgames/core\";\r\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\r\n```\r\n\r\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\r\n\r\n- `quest:definitionsLoaded` → `QuestDefinitions`\r\n- `quest:userStateLoaded` → `UserQuestState`\r\n- `quest:cyclesRefreshed` → `void`\r\n- `quest:progressAdded` → `AddQuestProgressResponse`\r\n- `quest:rewardClaimed` → `ClaimQuestRewardResponse`\r\n- `quest:rewardsClaimedBatch` → `ClaimQuestRewardsBatchResponse`\r\n- `quest:milestoneClaimed` → `ClaimMilestoneRewardResponse`\r\n- `quest:milestonesClaimedBatch` → `ClaimMilestoneRewardsBatchResponse`\r\n- `quest:groupCompletionClaimed` → `ClaimGroupCompletionRewardResponse`\r\n\r\nThe coarse `user:questUpdated` (and `user:anyUpdated`) also fire on any quest\r\ncache write — handy for a \"re-render everything\" hook.\r\n\r\n```ts\r\nconst off = client.on(\"quest:progressAdded\", (r) => {\r\n  for (const u of r.Updates ?? []) {\r\n    console.log(`${u.QuestID} objective ${u.ObjectiveID} -> ${u.NewValue}`);\r\n  }\r\n});\r\n// later: off();\r\n```\r\n\r\n## Recipes\r\n\r\n### Load the board and render quest cards\r\n\r\n```ts\r\nawait client.quest.getQuestDefinitions();\r\nawait client.quest.getUserQuestState();\r\n\r\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\r\nconst cycles = client.data.user.state?.Quest?.Cycles ?? {};\r\n\r\nfor (const [cycleID, cycleDef] of Object.entries(defs?.Cycles ?? {})) {\r\n  const userCycle = cycles[cycleID];\r\n  for (const [questID, questDef] of Object.entries(defs?.Quests ?? {})) {\r\n    if (!questDef.CycleIDs?.includes(cycleID)) continue;\r\n    const progress = userCycle?.Quests?.[questID];\r\n    // progress?.Status drives the card state: not-started/Active/Completed/Claimed.\r\n    // questDef.Objectives + progress?.Objectives drives the progress bar(s).\r\n  }\r\n}\r\n```\r\n\r\nA quest's `CycleIDs` lists every cycle it can appear in; cross-reference\r\nagainst `defs.Cycles` to know which are currently relevant. A quest absent from\r\n`userCycle.Quests` simply hasn't accrued any progress yet — treat it as\r\n`\"Active\"` with zero progress, not as an error. The backend creates a quest's\r\nprogress record (and each objective's) lazily, the first time it accrues\r\nsomething — it never pre-populates the catalog with zeros.\r\n\r\n### Report progress, then claim\r\n\r\n```ts\r\n// Wherever the underlying game action happens:\r\nconst prog = await client.quest.addQuestProgress(\"EnemiesDefeated\", 1);\r\nif (!prog.ok) return showError(prog.error);\r\n\r\nfor (const u of prog.data.Updates ?? []) {\r\n  if (u.Status === \"Completed\") {\r\n    // Surface a \"claim\" button for u.QuestID / u.CycleID now.\r\n  }\r\n}\r\n```\r\n\r\n```ts\r\n// Later, when the player taps Claim:\r\nconst claim = await client.quest.claimQuestReward(\"q1\", \"cycleA\");\r\nif (!claim.ok) return showError(claim.error); // e.g. \"Quest is not completed\", \"Already claimed\"\r\n// cache now shows q1 as \"Claimed\"; balances already credited.\r\n```\r\n\r\nClaiming before every objective is met, or claiming twice, both fail with\r\n`reason: \"server\"` — the quest must be `\"Completed\"` and not already\r\n`\"Claimed\"`. There's no client-side shortcut to check this ahead of time beyond\r\nreading the cached `Status` you already have.\r\n\r\nOnly objectives configured with `Source: \"ClientApi\"` can be advanced this way;\r\nan unrecognized `MetricID` fails with `\"MetricID not allowed for ClientApi\"`.\r\nNever send an inflated `ProgressValue` \"to be safe\" — if a matching objective\r\ndeclares `MaxProgressPerCall`, the backend compares your raw value against it\r\nand **bans the account** on a violation (`\"User banned: Value exceeds\r\nMaxValuePerCall\"`); it does not just clamp and continue.\r\n\r\n### Objectives you must NOT report progress for\r\n\r\nObjectives with `Source: \"SystemEvent\"` are advanced by the backend itself from\r\ntheir `Triggers` list — board rolls, store purchases, marketplace settlements,\r\nclaiming another quest. There is no call to make: `addQuestProgress` rejects\r\nthem, and adding a client-side counter for them double-counts nothing but wastes\r\na request.\r\n\r\nWhen such an objective moves, the progress rides back on the envelope of\r\nwhatever call caused it (a roll, a purchase, a claim) as\r\n`QuestProgress: QuestProgressUpdate[]`. The client applies it to the cached user\r\nstate automatically, so quest UI just needs to re-read the cache — do not poll\r\n`getUserQuestState` for it.\r\n\r\n`Source: \"ServerApi\"` objectives are moved only by a CloudCode script calling\r\n`server.AddQuestProgress(metricID, value)`. Same rule: nothing for the game to\r\ncall.\r\n\r\n### Claim a milestone once the points track crosses a rung\r\n\r\n```ts\r\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\r\nconst claimedAlready = points?.Milestone?.ClaimedIDs?.includes(\"m1\") ?? false;\r\n\r\nif (\r\n  !claimedAlready &&\r\n  (points?.Balance?.Current ?? 0) >= /* milestone.RequiredProgress */ 100\r\n) {\r\n  const res = await client.quest.claimMilestoneReward(\"cycleA\", \"m1\");\r\n  if (!res.ok) return showError(res.error);\r\n  res.data.PointsTotalEarned; // lifetime points earned this cycle, for display\r\n}\r\n```\r\n\r\nMilestone eligibility is judged against the points token's **lifetime total**\r\n(`Balance.TotalEarned`, mirrored into `PointsCurrent`/`PointsTotalEarned` on\r\n`QuestPointsTrackView` — for this token they're always equal, since points are\r\nonly ever granted, never spent). Points land in that balance when a quest with\r\n`PointsReward > 0` is **claimed** (`claimQuestReward`/batch) — completing a\r\nquest alone does not add points, claiming it does, in the same atomic\r\ntransaction as the quest's own reward. So a player reaches milestone `m1` by\r\nclaiming enough individual quest rewards across the cycle — milestone claiming\r\nis independent of any _single_ quest's claim, but not of claiming in general.\r\n\r\n### Claim a group-completion grand reward\r\n\r\n```ts\r\nconst res = await client.quest.claimGroupCompletionReward(\r\n  \"cycleA\",\r\n  \"dailyGroupBonus\",\r\n);\r\nif (!res.ok) return showError(res.error); // e.g. \"not enough quests completed in group\"\r\nres.data.CompletedGroupQuests; // e.g. 3\r\nres.data.RequiredGroupQuests; // e.g. 3\r\n```\r\n\r\nEligibility counts quests in the group that reached `\"Completed\"` **or**\r\n`\"Claimed\"` — you don't need to claim every quest's own reward first, just\r\nfinish them. The required count is `RequiredCompletedQuests` if set, otherwise\r\n**every** quest currently in that group/cycle (0 means \"all\"). This is\r\nrecomputed live against the current catalog at claim time (not a snapshot from\r\nwhenever the player finished the quests), so a group whose quest list changed\r\nafter the player completed them can shift the totals. Once claimed, the id is\r\nrecorded in `cycle.ClaimedGroupCompletionIDs` — check that list to hide an\r\nalready-claimed banner.\r\n\r\n### Batch claim several quests/milestones at once\r\n\r\n```ts\r\nconst res = await client.quest.claimQuestRewardsBatch([\r\n  { CycleID: \"cycleA\", QuestID: \"q1\" },\r\n  { CycleID: \"cycleA\", QuestID: \"q2\" },\r\n  { QuestID: \"intro\" }, // permanent quest: CycleID omitted\r\n]);\r\nif (!res.ok) return showError(res.error);\r\nfor (const item of res.data) {\r\n  if (item.Success) applyOk(item.Id);\r\n  else showItemError(item.Id, item.Error); // this one was rejected\r\n}\r\n```\r\n\r\nBatch results are **partial-aware**: the outer `res.ok` tells you the call ran;\r\neach element's `Success`/`Error` tells you whether that item applied — one\r\nalready-claimed quest in the batch doesn't sink the others. `claimMilestoneRewardsBatch`\r\nworks the same way with `MilestoneClaimRef[]`.\r\n\r\n### Force a cycle refresh (e.g. on app resume)\r\n\r\n```ts\r\nconst res = await client.quest.refreshQuestCycles();\r\nif (res.ok) {\r\n  await client.quest.getUserQuestState(); // reload to pick up the new cycle instance\r\n}\r\n```\r\n\r\n`getUserQuestState()` already auto-refreshes cycles by default\r\n(`autoRefreshCycles: true`), so most apps never need to call this directly —\r\nreach for it when you want to roll cycles forward (e.g. after detecting a\r\nday/week boundary while the app was backgrounded) without waiting on a full\r\nstate reload, or want the two steps as separate UI beats (spinner → \"New\r\nquests!\" toast).\r\n\r\n## Gotchas\r\n\r\n- **Progress is reported by metric, not by quest.** `addQuestProgress` doesn't\r\n  target a quest id — it fans one `MetricID` update out to every objective\r\n  across every active quest (and cycle) that listens to it. Call it once per\r\n  underlying game action, not once per quest you think might care.\r\n- **Claiming has three independent tracks.** A quest's own `Reward`, its\r\n  cycle's points-track `Milestones`, and its group's `GroupCompletions` are\r\n  claimed through three different methods and three different cache locations\r\n  (`Quest.Cycles[...].Quests`, `EventToken.Quest`, `Quest.Cycles[...]\r\n.ClaimedGroupCompletionIDs`). Completing a quest can make all three\r\n  claimable at once — don't assume claiming one auto-claims the others.\r\n- **Milestone/points state lives in the event-token cache, not `Quest`.**\r\n  `client.data.user.state?.Quest` holds quest/objective progress; the points\r\n  balance and claimed-milestone ids live at\r\n  `client.data.user.state?.EventToken?.Quest`, keyed by `cycleID` or\r\n  `\"cycleID:instanceKey\"` for recurring cycles. Use the\r\n  `client.data.user.getQuestPointsProgress(cycleID)` helper instead of\r\n  indexing the bucket yourself — it normalizes the composite key for you.\r\n- **Guard against double-submit.** Each call mints a fresh idempotency key\r\n  (`RelatedEntityID`), so two separate calls are two real operations — a\r\n  double-clicked \"Claim\" can attempt to claim twice (the second simply fails\r\n  as already-claimed, but don't rely on that for UX). Disable the control\r\n  while a call is in flight. Firing the same endpoint again within the\r\n  throttle window (default 600 ms) is rejected with `reason: \"throttled\"`\r\n  rather than duplicated.\r\n- **`RequiredQuestIDs` can gate progress, not just claiming.** A quest's\r\n  `PrerequisiteMode` decides whether unmet prerequisites block progress from\r\n  accruing at all (`BlockProgressAndClaim`) or only block the final claim\r\n  (`BlockClaimOnly`) — check which mode a quest uses before assuming progress\r\n  bars will move.\r\n- **Batch charges/prereqs are evaluated per item, independently.** Unlike some\r\n  other modules' batch upgrades, quest/milestone batch claims aren't chained —\r\n  each item is judged against state at the start of the call, so claiming\r\n  `q1` and `q2` in the same batch where `q2` requires `q1` completed (not\r\n  claimed) still works, but don't expect claim-order effects within one batch\r\n  call.\r\n- **Cycles roll forward wholesale, not incrementally.** When a cycle's schedule\r\n  window rotates (e.g. midnight UTC for a daily), the server replaces that\r\n  cycle's entire `Quests` map and `ClaimedGroupCompletionIDs` with a fresh,\r\n  empty state — there is no partial carry-over of yesterday's progress. Always\r\n  call `getUserQuestState()` (or `refreshQuestCycles()` + a reload) after\r\n  detecting a boundary rather than trusting a stale cached cycle.\r\n- **Cache patches for an unknown cycle silently no-op.** `claimQuestReward` and\r\n  `claimGroupCompletionReward` only patch the local cache if that `CycleID`\r\n  already exists in `client.data.user.state.Quest.Cycles` — if you call them\r\n  for a cycle the client hasn't loaded yet (e.g. right after a cold start with\r\n  a stale cache), the call still succeeds server-side but the UI won't reflect\r\n  it until you `getUserQuestState()` again. Load state before wiring up claim\r\n  buttons.\r\n- **Render from the cache, handle the error from the result.** The happy path\r\n  updates the cache + emits an event; the failure path gives you `reason` +\r\n  `error`. Use `reason` to decide behavior (retry on `\"connection\"`, re-auth on\r\n  `\"unauthorized\"`, toast the `error` on `\"server\"`).\r\n\r\n## Full reference\r\n\r\n[references/data-model.md](references/data-model.md) — every config and state\r\nfield, the objective/prerequisite/schedule/limit/gate blocks, and how the\r\npoints-track and milestone plumbing ties into the shared event-token cache.\r\nRead it when building config-driven UI (objective progress bars, milestone\r\nladders, cycle countdowns) or when an error message points at a config rule you\r\nneed to understand.\r\n",
   "references": [
     {
       "path": "data-model.md",
-      "content": "# Quest data model — reference\n\nFull shape of the config (Definitions) and player state, the cycle/schedule\nresolution rules, the points-track (\"Achievements\") plumbing, group-completion\nmath, and the server-side limits/idempotency rules. All of these are **strictly\ntyped in the SDK** — `QuestDefinitions` and every nested block (`QuestDefinition`,\n`QuestCycleDefinition`, `QuestObjectiveDefinition`, `QuestGroupCompletionDefinition`,\nthe shared `ScheduleSpec`/`SegmentGate`/`LimitSpec`/`MilestoneDefinition`/\n`EventTokenDefinition` blocks, …) are exported from `@idosgames/core`, so\n`getQuestDefinitions()` and `getSection<QuestDefinitions>(\"Quest\")` give you\nconcrete types, not `unknown`. The schemas keep `.passthrough()`, so a field the\nbackend adds later still round-trips. Field names are PascalCase (straight from\nthe backend JSON).\n\nBackend source of truth for everything below:\n`IDosGamesSDK/API/Client/v2/Quest/Quest.cs`,\n`IDosGamesSDK/API/Client/v2/Quest/Models/QuestDefinitions.cs`,\n`IDosGamesSDK/API/Client/v2/Quest/Models/UserQuestState.cs`,\n`IDosGamesSDK/API/Core/Scheduling/Services/ScheduleResolver.cs`,\n`IDosGamesSDK/API/Core/Event/Services/EventTokenService.cs`.\n\n## Contents\n\n- [Player state](#player-state) — what `getUserQuestState()` returns\n- [Config: QuestDefinitions](#config-questdefinitions) — what `getQuestDefinitions()` returns\n- [QuestCycleDefinition](#questcycledefinition)\n- [QuestDefinition](#questdefinition)\n- [QuestObjectiveDefinition + progress aggregation](#questobjectivedefinition--progress-aggregation)\n- [Prerequisites (`RequiredQuestIDs`)](#prerequisites-requiredquestids)\n- [Cycle schedule resolution](#cycle-schedule-resolution)\n- [Per-quest schedule (\"staged unlock\" / Achievements)](#per-quest-schedule-staged-unlock--achievements)\n- [Points track (\"Achievements\") — the Quest event-token](#points-track-achievements--the-quest-event-token)\n- [Group-completion (grand reward) math](#group-completion-grand-reward-math)\n- [`AddQuestProgress` server-side rules](#addquestprogress-server-side-rules)\n- [Idempotency, atomicity, batch limits](#idempotency-atomicity-batch-limits)\n\n---\n\n## Player state\n\nReturned by `getUserQuestState()` as `{ State, PointsTracks }` and cached at\n`client.data.user.state?.Quest` (progress) + `client.data.user.state?.EventToken?.Quest`\n(points track — see below). Hand-written interfaces (not `z.infer`) because the\ncache-patch methods mutate these objects in place.\n\n```ts\ninterface UserQuestState {\n  Cycles?: Record<string, UserQuestCycleState>; // key = CycleID\n  PermanentQuests?: Record<string, UserQuestProgress>; // key = QuestID\n  LastUpdatedUtc?: string;\n}\n\ninterface UserQuestCycleState {\n  CycleID?: string;\n  CycleStartUtc?: string; // current window start, UTC\n  CycleEndUtc?: string; // current window end, UTC\n  Quests?: Record<string, UserQuestProgress>; // key = QuestID, THIS window only\n  ClaimedGroupCompletionIDs?: string[]; // CompletionIDs already claimed this window\n}\n\ninterface UserQuestProgress {\n  QuestID: string;\n  Status: \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\";\n  ActivatedAtUtc?: string | null;\n  CompletedAtUtc?: string | null;\n  ClaimedAtUtc?: string | null;\n  Objectives?: Record<string, UserQuestObjectiveProgress>; // key = ObjectiveID\n}\n\ninterface UserQuestObjectiveProgress {\n  ObjectiveID: string;\n  CurrentValue: number;\n  Completed: boolean;\n  CompletedAtUtc?: string | null;\n}\n```\n\n**Lazy initialization** (`Quest.cs` `RefreshQuestCycles` / `CreateQuestProgressFromDefinition`):\na quest's `UserQuestProgress` (and each objective's `UserQuestObjectiveProgress`)\nis created only the first time progress is reported for it — the server does\n**not** pre-populate every configured quest/objective with zeros. A quest absent\nfrom `Cycles[cycleID].Quests` (or `PermanentQuests`) simply has zero progress on\nevery objective; render it as `\"Active\"`, not as an error or \"unknown\" state.\n`Expired` is only ever set for cyclic quests (never for permanent quests) and\nonly via the same lazy path — in practice you will see `Active` → `Completed` →\n`Claimed` for anything you've touched; a truly stale quest from a rolled-over\ncycle is simply absent (the whole cycle bucket gets replaced on rollover, see\nbelow), not flagged `Expired` in current code paths.\n\n---\n\n## Config: QuestDefinitions\n\nReturned by `getQuestDefinitions()`; cached via\n`client.data.config.getSection<QuestDefinitions>(\"Quest\")`.\n\n```ts\ninterface QuestDefinitions {\n  Cycles?: Record<string, QuestCycleDefinition>; // key = CycleID\n  Quests?: Record<string, QuestDefinition>; // key = QuestID\n}\n```\n\nA quest is **permanent** iff its `CycleIDs` is null/empty; otherwise it is\n**cyclic** and belongs to every cycle listed in `CycleIDs` (a quest can appear\nin more than one cycle definition, each with independent progress/claim state).\nCycle IDs and quest/objective IDs must all be Mongo-safe (no `.` or `$`) —\nthe server rejects unsafe keys outright (`\"Invalid CycleID (mongo-unsafe): …\"`,\n`\"QuestID is mongo-unsafe\"`, etc.); this only matters if you let players or\nremote config drive raw ids into these fields.\n\n---\n\n## QuestCycleDefinition\n\n`Quest.cs` / `QuestDefinitions.cs`. One recurring or one-off \"board\" (dailies,\nweeklies, a scheduled event window, …). Quests do **not** get listed here —\neach `QuestDefinition` points back at the cycle via `CycleIDs`.\n\n```ts\ninterface QuestCycleDefinition {\n  CycleID?: string;\n  DisplayName?: string;\n  Schedule?: ScheduleSpec; // cycle window/reset — see below\n  Milestones?: Record<string, MilestoneDefinition>; // points-track rungs, key = MilestoneID\n  Gate?: SegmentGate; // audience gate for the whole cycle; ANDed with each quest's own Gate\n  PointsToken?: EventTokenDefinition; // global caps/burn for the points track (see below)\n  GroupCompletions?: Record<string, QuestGroupCompletionDefinition>; // key = CompletionID\n}\n```\n\nBackend default when a cycle is authored without an explicit `Schedule`:\n`Mode: \"Cyclic\"`, `Cyclic: {}` (i.e. daily calendar reset) —\n`QuestCycleDefinition.Schedule` in `QuestDefinitions.cs`.\n\n---\n\n## QuestDefinition\n\n```ts\ninterface QuestDefinition {\n  QuestID?: string;\n  CycleIDs?: string[]; // null/empty => permanent; else cyclic, one entry per cycle it appears in\n  DisplayName?: string;\n  Description?: string;\n  SortOrder?: number; // lower = earlier in UI\n\n  RequiredQuestIDs?: string[]; // prerequisite QuestIDs — see below\n  PrerequisiteMode?: \"BlockProgressAndClaim\" | \"BlockClaimOnly\"; // default BlockProgressAndClaim\n\n  PointsReward?: number; // points into the cycle's points track on claim; ignored for permanent quests\n  Schedule?: ScheduleSpec; // per-quest unlock window; null = inherit the cycle's window (see below)\n  AccrueProgressWhenLocked?: boolean; // default false — see per-quest schedule section\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\n  Limits?: LimitSpec; // per-quest per-source caps on POINTS grants only (not on objective progress)\n  GroupID?: string; // for UI grouping + QuestGroupCompletionDefinition.GroupID matching\n\n  Objectives?: Record<string, QuestObjectiveDefinition>; // key = ObjectiveID; ALL must complete\n  Reward?: ResourceGrant; // claimed via claimQuestReward\n}\n```\n\n`PrerequisiteMode` (`QuestDefinition.cs` comment, verbatim intent):\n\n| Mode                              | Effect on `RequiredQuestIDs`                                                                                                                            |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `BlockProgressAndClaim` (default) | The quest does not start accruing progress at all until every listed prerequisite reaches `Completed`/`Claimed`; consequently it also can't be claimed. |\n| `BlockClaimOnly`                  | Progress accrues immediately; only the final reward claim is blocked until prerequisites are met.                                                       |\n\nA prerequisite is looked up \"where its own progress lives\": permanent →\n`PermanentQuests`; cyclic → the same `cycleID` if the prerequisite also belongs\nto it, otherwise the prerequisite's own first `CycleIDs` entry\n(`ArePrerequisitesMet`, `Quest.cs`). Empty/null `RequiredQuestIDs` = no gating.\n\n---\n\n## QuestObjectiveDefinition + progress aggregation\n\n```ts\ninterface QuestObjectiveDefinition {\n  ObjectiveID?: string;\n  Source?: \"ClientApi\" | \"ServerApi\" | \"SystemEvent\"; // who may report progress; default SystemEvent\n  MaxProgressPerCall?: number; // per-call delta cap (ClientApi abuse guard); 0/absent = no cap\n  MetricID?: string; // the metric key addQuestProgress reports against\n  TargetValue?: number; // default 1; required value to complete\n  AggregationMethod?: string; // \"Sum\" | \"Maximum\" | \"Minimum\" | \"Last\"; default \"Sum\"\n  Filters?: Record<string, string>; // optional metric refinement (not enforced client-side)\n}\n```\n\nOnly objectives with `Source: \"ClientApi\"` are reachable from `addQuestProgress`\n— `Source: \"ServerApi\"` / `\"SystemEvent\"` objectives are advanced by other\nbackend systems, never by the client, and a `MetricID` with no matching\n`ClientApi` objective anywhere in the catalog is rejected outright\n(`\"MetricID not allowed for ClientApi\"`).\n\nAggregation (`ApplyAggregation`, `Quest.cs`), given the objective's current\n`CurrentValue` and the incoming call value:\n\n| Method                   | New value                                                                                |\n| ------------------------ | ---------------------------------------------------------------------------------------- |\n| `Sum` (default)          | `current + incoming`, clamped to `long.MaxValue` on overflow; `incoming <= 0` is a no-op |\n| `Maximum`                | `max(current, incoming)`                                                                 |\n| `Minimum`                | `incoming` if `current == 0`, else `min(current, incoming)`                              |\n| `Last` (or unrecognized) | `incoming` (last-write-wins)                                                             |\n\nAfter aggregation, if `TargetValue > 0` the new value is clamped to\n`TargetValue` (progress bars never overshoot 100%); if `TargetValue <= 0` there\nis no cap. An objective is marked `Completed` once\n`(TargetValue <= 0 && newValue > 0) || newValue >= TargetValue`. A quest becomes\n`\"Completed\"` once **every** objective the player has a progress record for is\n`Completed` **and** every objective in the definition has a progress record —\ni.e. an objective with zero recorded progress blocks completion (it's absent\nfrom the player's `Objectives` map, so the `All(...)` check in\n`EnsureQuestObjectivesAndCompletion` fails for it).\n\n`MaxProgressPerCall` guards two different things depending on\n`AggregationMethod`:\n\n- If **any** matching `ClientApi` objective for the `MetricID` has\n  `MaxProgressPerCall > 0`, the server compares the **raw** `ProgressValue` you\n  sent against the (minimum across matches) cap **before** any clamping. If the\n  raw value exceeds it, the call is rejected **and the player is banned**\n  (`service.BanUser(...)`, fire-and-forget) with error `\"User banned: Value\nexceeds MaxValuePerCall\"`. This is a hard anti-abuse trip-wire, not a soft\n  clamp — never let client code send inflated values \"to be safe.\"\n- Only for objectives using `Sum` aggregation is the value additionally\n  clamped to `MaxProgressPerCall` before summing (defense in depth; irrelevant\n  once the ban-check above has already passed, since raw ⇐ cap by that point).\n\n---\n\n## Prerequisites (`RequiredQuestIDs`)\n\nSee the `PrerequisiteMode` table above. Enforcement points in `Quest.cs`:\n\n- **Progress accrual** (`AddQuestProgress` internal helper): for permanent\n  quests and for each cycle a cyclic quest belongs to, prerequisites are\n  checked (only in `BlockProgressAndClaim` mode) before the quest's\n  `UserQuestProgress` is even created/updated for that call.\n- **Claim** (`ClaimQuestReward` / batch): `ArePrerequisitesMet(...)` is checked\n  unconditionally (both modes gate the claim) — error\n  `\"Prerequisite quests are not completed\"`.\n\n---\n\n## Cycle schedule resolution\n\n`QuestCycleDefinition.Schedule` is a `ScheduleSpec` (`_shared/ScheduleModels.ts`\n/ `Core/Scheduling`), the same primitive every other module uses. For Quest,\n`RefreshQuestCycles` resolves it via `ScheduleResolver.ResolveActive(...)`\ninto a `[CycleStartUtc, CycleEndUtc)` window per the active `Mode`:\n\n- **`Cyclic`** (the practical default for dailies/weeklies): `Cyclic.Reset` picks\n  the calendar cadence — `Hourly`/`Daily`/`Weekly` (always **Monday** start)/`Monthly`\n  (always the **1st**)/`Yearly` are calendar-aligned in **UTC**, reset time is\n  **always 00:00:00 UTC** and is not configurable. `FixedInterval` instead repeats\n  every `Cyclic.IntervalSeconds` seconds from `Cyclic.AnchorUtc` (default anchor\n  `2026-01-01T00:00:00Z`, default interval 86400s if unset/≤0); an optional\n  `PauseBetweenCyclesSec` inserts a dead gap after each active window during\n  which `CanEarn` is `false` (`IsInPause = true`) but the window has still\n  technically \"ended\" — new progress does not accrue during the pause, though\n  already-completed quests remain claimable (claims are never earn-gated).\n- **`Scheduled`**: one fixed `[StartUtc, EndUtc]` window; `ClaimGraceHours`\n  extends claimability past `EndUtc` without extending earning (unless\n  `AllowEarningAfterEnd` is set).\n- **`AlwaysOn`**: always active, no end.\n- Any other/inactive resolution (e.g. `Triggered`, or `spec.IsActive === false`)\n  makes `ComputeCycleWindowUtc` **degrade to a plain UTC calendar day**\n  `[today 00:00, tomorrow 00:00)` as a fallback — don't configure `Triggered` on\n  a quest cycle expecting anything else.\n\n**Rollover behavior** (`RefreshQuestCycles`, called automatically by\n`getUserQuestState({autoRefreshCycles: true})` — the default — and before every\nmutating Quest action): when the resolved `[start, end)` no longer matches the\nstored `CycleStartUtc`/`CycleEndUtc`, the entire `UserQuestCycleState` for that\ncycle is **replaced with a brand-new, empty one** (`Quests: {}`,\n`ClaimedGroupCompletionIDs` reset) — there is no partial carry-over of\nin-progress quests into the new window. Cycles removed from config entirely are\ndeleted from the player's state on the next refresh. If the window has **not**\nrolled over, the refresh instead walks the player's **existing** quest progress\nrecords (only ones already started) and re-evaluates `Completed` status against\ncurrent config — it does not add new objectives to already-tracked quests.\n\n---\n\n## Per-quest schedule (\"staged unlock\" / Achievements)\n\n`QuestDefinition.Schedule` is an **independent, optional** `ScheduleSpec` layered\non top of the cycle's own schedule — this is how \"Day 2 unlocks 24h after Day 1\"\nor an \"Achievements\" track with a `ScheduleSpec`-driven unlock (rather than a\nliteral day-count) is built, with any number of stages at any interval, not just\nliteral days:\n\n- `Schedule` absent → the quest simply inherits its cycle's window; earning and\n  claiming follow the cycle's own `CanEarn`/`CanClaim`.\n- `Schedule` present → resolved via `ResolveQuestInstance`, which passes the\n  **cycle's** resolved instance as the `parent` for `Relative`-mode windows —\n  so a per-quest `Relative` schedule with `OffsetSecondsFromParentStart` is\n  \"N seconds after this cycle instance started,\" letting one `Cyclic` cycle\n  auto-repeat a whole staged sequence without hardcoded absolute dates.\n- `AccrueProgressWhenLocked` (default `false`) decides what happens **while**\n  the cycle's window is open but the quest's own window is not: `false` means a\n  locked stage accrues **zero** progress (a true lock — progress reported for\n  its metric while locked is simply dropped for that quest); `true` means\n  progress accrues the whole time the cycle is active, but the **reward claim**\n  is still gated on the quest's own `CanClaim` — so you can pre-accrue \"Day 3\"\n  progress while day 3 is still locked, and only the payout waits.\n\nEarning gate precedence for a cyclic quest, all of which must pass\n(`AddQuestProgress` internal helper): cycle `earningCycles` membership (cycle\nitself must be `CanEarn`, i.e. not `IsInPause`) → quest's own\n`IsQuestEarnable` (`AccrueProgressWhenLocked` bypasses this specific check) →\n`QuestGatesPass` (cycle `Gate` AND quest `Gate`) → prerequisites (only in\n`BlockProgressAndClaim` mode).\n\n---\n\n## Points track (\"Achievements\") — the Quest event-token\n\nThis is the mechanism the \"Achievements\" hint in the prompt refers to — it is\nreal and it is exactly the cycle's points track, not a separate module. Russian\ncomments in `Quest.cs` literally label it «Достижения» (Achievements).\n\n**How points get earned.** Each cyclic `QuestDefinition.PointsReward` (points,\nnot currency) is granted **only on claim** of that quest's own reward — via\n`ClaimQuestReward` / `ClaimQuestRewardsBatch`, in the **same atomic transaction**\nas the quest's `Reward` grant. It's `long`, defaults to `0`, and is ignored for\npermanent quests (`isPermanent` quests never touch the points track). A group\ncompletion (below) can **also** add points via its own `PointsReward`, on top of\nwhatever its member quests already contributed individually.\n\n**Where it's addressed.** The points track is backed by a standard\n`EventTokenType.Quest` event token (the same primitive TimedEvent/Leaderboard/\nCoopEvent/Season points tracks use), addressed at\n`EntityID = \"{cycleID}:{instanceKey}\"` where `instanceKey` comes from\n`ScheduleResolver`'s resolution of the **cycle's** schedule (`\"all\"` if the\ncycle has no resolvable instance). Because the instance key changes when the\ncycle's schedule rotates to a new window, **the points balance and claimed-milestone\nlist reset automatically on cycle rollover** — there is no explicit\n\"reset points\" step; it's a natural consequence of the address changing.\n\n**Where it lives in state.** `UserQuestState` does **not** carry the points\nbalance — it lives in `UserDataDocument.EventToken.Quest[entityID]`\n(`UserEventTokenProgress`: `Balance.Current`/`Balance.TotalEarned`,\n`Milestone.ClaimedIDs`). `GetUserQuestState` additionally projects a **read-only\nsnapshot** per cycle into `GetUserQuestStateResponse.PointsTracks[cycleID]`\n(`QuestPointsTrackView`) so the client doesn't have to know the composite key —\nthe TS SDK's `patchQuestPointsTracks` writes this into\n`client.data.user.state.EventToken.Quest[\"{cycleID}:{instanceKey}\"]` for you,\nand `client.data.user.getQuestPointsProgress(cycleID)` resolves the composite\nkey back out (`matchesBase`, `util/eventTokenIds.ts`) so you can look it up by\nplain `cycleID`.\n\n```ts\ninterface QuestPointsTrackView {\n  CycleID: string;\n  InstanceKey?: string | null;\n  CycleStartUtc?: string | null;\n  CycleEndUtc?: string | null; // source for a \"resets in\" timer\n  PointsTotalEarned?: number | null; // lifetime points earned this cycle instance\n  PointsCurrent?: number | null; // current balance (== TotalEarned; points are never spent)\n  ClaimedPointMilestoneIDs?: string[] | null;\n}\n```\n\n**Milestones** (`QuestCycleDefinition.Milestones`, keyed by `MilestoneID`) are\nthe shared Core `MilestoneDefinition` primitive\n(`RequiredProgress`, `Rewards`, `BonusRewards`, `SeasonTierRewards`,\n`SortOrder`, `IsFeatured`) — see `_shared/MilestoneModels.ts`. Eligibility is\njudged **only** against `Balance.TotalEarned` on the points token (never\n`Current`, though for Quest the two happen to always be equal since points are\nonly ever granted, never spent) — `EventTokenService.ComputeMilestoneClaim`:\nfails with `\"Not enough earned. Have: X, need: Y.\"` if under threshold, or\n`\"Milestone already claimed.\"` if `MilestoneID` is already in `ClaimedIDs`.\nClaiming pushes the id into `ClaimedIDs` via a Mongo `$push` guarded by a\n`$nin` filter (OCC — a concurrent duplicate claim loses the race cleanly). The\nmilestone's reward itself runs through the shared `MilestoneRewardResolver`\n(same resolver Leaderboard/TimedEvent/CommunityChest/Referral use), which\napplies the title's progression-multiplier overlay\n(`cfg.Reward.MilestoneRewardMultiplier`) if configured — so the actual payout\ncan exceed the base `Rewards` grant; read it from the response, don't assume\nface value.\n\n**Caps** on points grants (`BuildPointsGrantContext`): **global** caps come from\n`QuestCycleDefinition.PointsToken` (an `EventTokenDefinition` — `DailyEarnCap`,\n`MaxBalance`, `MaxPerGrant`); **per-quest-source** caps/cooldown come from\n`QuestDefinition.Limits` (a `LimitSpec`, mapped as `DailyWeightCap` →\nper-source daily cap, `DailyCap` → per-source daily trigger count,\n`CooldownSeconds` → per-source cooldown). Per-source limits only apply in the\n**single** `ClaimQuestReward` path — the batch claim path\n(`ClaimQuestRewardsBatch`) only enforces the cycle's **global** `PointsToken`\ncaps against the **summed** batch amount per address, since per-source limits\ndon't make sense once amounts from multiple quests are merged into one token\noperation. If a cap fully exhausts the grant, `EventTokenService.ComputeGrant`\ncan reduce the amount to `0`, which surfaces as a failed points portion inside\nthe resource operation — always read granted amounts from the response, never\nassume the full `PointsReward` landed.\n\n---\n\n## Group-completion (grand reward) math\n\n`QuestCycleDefinition.GroupCompletions[completionID]` (`QuestGroupCompletionDefinition`):\n\n```ts\ninterface QuestGroupCompletionDefinition {\n  CompletionID?: string;\n  GroupID?: string; // must match QuestDefinition.GroupID on member quests\n  RequiredCompletedQuests?: number; // 0 = \"ALL quests in this group, per current config\"\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\n  Reward?: ResourceGrant;\n  PointsReward?: number; // additional points into the SAME cycle points track; 0 = none\n}\n```\n\n`ClaimGroupCompletionReward` computes eligibility **live**, at claim time, by\nscanning the **current** `QuestDefinitions.Quests` for every quest that (a)\nlists this `cycleID` in its `CycleIDs` and (b) has `GroupID` equal to the\ncompletion's `GroupID` — that's `totalGroupQuests`. Of those, it counts how many\nhave reached `Status === \"Completed\"` **or** `\"Claimed\"` in the player's current\ncycle state — that's `completedGroupQuests`. The required threshold is\n`RequiredCompletedQuests` if `> 0`, otherwise `totalGroupQuests` (i.e. every\ngroup quest currently in config). Failure modes:\n\n- `RequiredCompletedQuests` unset and the group is empty/misconfigured (no\n  quests currently reference that `GroupID` in that cycle) →\n  `\"No quests configured for this group\"` (required resolves to `0`, which is\n  rejected outright — you can never claim an empty group).\n- `completedGroupQuests < required` → `\"Not enough completed quests for this\ngroup\"`.\n- Already in `cycle.ClaimedGroupCompletionIDs` → `\"Group completion already\nclaimed\"` (checked in-memory before the DB round-trip, then re-enforced by an\n  `AnyEq`-negated Mongo filter for the actual OCC guard).\n- `completion.GroupID` blank/whitespace on the definition itself →\n  `\"Group completion has no GroupID\"` (a config error, not a player error).\n\nBecause the scan is **live against current config**, removing a quest from the\ngroup (or from the cycle) between when a player completed it and when they\nclaim the group reward can change `totalGroupQuests`/`completedGroupQuests` —\nthere's no snapshot of \"the group as it was.\" The response echoes\n`CompletedGroupQuests` and `RequiredGroupQuests` (the resolved threshold, not\nthe raw config field) so the client can show \"3 / 3\" without recomputing\nanything.\n\n---\n\n## `AddQuestProgress` server-side rules\n\nFull request-to-mutation path (`QuestV2.AddQuestProgress` public entry point +\nthe internal shared helper), summarized because several rules only make sense\ntogether:\n\n1. `MetricID` required; must match at least one `ClientApi`-sourced objective\n   in the **entire** quest catalog, or the call fails with `\"MetricID not\nallowed for ClientApi\"` before touching the database.\n2. `ProgressValue` (`long`) must be `>= 0`.\n3. If any matching objective declares `MaxProgressPerCall > 0`, the **raw**\n   value is checked against the smallest such cap across all matches; exceeding\n   it **bans the account** (see the objective section above) rather than\n   clamping — this is a hard security control, not UX guidance.\n4. The (possibly `Sum`-clamped) value then fans out to **every** quest/objective\n   pair across **every currently-earning cycle and every permanent quest**\n   whose objective's `Source === \"ClientApi\"` and `MetricID` matches — one\n   `addQuestProgress` call can move several quests (even across different\n   cycles) simultaneously if they all listen to the same metric.\n5. Each matched quest only advances if it isn't already `Completed`/`Claimed`\n   (`ApplyToQuestInstance` early-returns `false` otherwise) — so calling\n   `addQuestProgress` for an action a player keeps performing after a quest is\n   done is safe and a no-op for that quest.\n6. The response's `Updates[]` (`QuestProgressUpdate`) lists **only the\n   quest/objective pairs that actually changed** this call — an objective whose\n   `Sum` increment was clamped to `0` (already at `TargetValue`) or a locked\n   quest that accrued nothing produces no entry.\n7. This whole path calls `RefreshQuestCycles` first (unless the internal helper\n   is invoked with `ensureCyclesUpToDate: false`, which the public\n   `AddQuestProgress` action does to avoid double-refreshing) — so cycle\n   windows are always current before progress is evaluated.\n\n---\n\n## Idempotency, atomicity, batch limits\n\n- **Idempotency keys** (`ResourceService.ResolveRelatedEntityID`, stable ID\n  patterns from `Quest.cs`): single quest claim →\n  `\"{questID}\"` (permanent) or `\"{questID}_{cycleStartUtc:yyyyMMddHHmmss}\"`\n  (cyclic — so the **same** quest claimed again after the cycle rolls to a new\n  window is a distinct idempotency key, not a duplicate); milestone claim →\n  `\"{cycleID}_{milestoneID}_{instanceKey}\"`; group completion →\n  `\"{cycleID}_{completionID}_{cycleStartUtc:yyyyMMddHHmmss}\"`. You never\n  construct these yourself — the TS SDK mints its own client-side\n  `RelatedEntityID` (`quest_claim_…`, `milestone_claim_…`, `group_completion_…`,\n  each suffixed with a fresh UUID) purely for its own request-level tracking;\n  the **server-side** idempotency guarantee comes from the stable IDs above\n  plus the OCC filter on each claim, not from the client's `RelatedEntityID`.\n- **Atomicity.** Every claim path (`ClaimQuestReward`, `ClaimMilestoneReward`,\n  `ClaimGroupCompletionReward`, and both batch variants) runs the reward grant\n  and the state-mutating patches (status → `Claimed`, milestone `$push`, group\n  `$addToSet`) inside **one** `ResourceService.ApplyResourceOperationAtomicAsync`\n  call with an `extraFilter` re-asserting the pre-claim condition (e.g. quest\n  `Status == Completed`) — if the grant fails for any reason (insufficient\n  server-side room, a concurrent claim already flipped the filter condition,\n  etc.) the whole transaction rolls back; there is no partially-applied claim.\n- **Resources in batch responses.** For both `ClaimQuestRewardsBatch` and\n  `ClaimMilestoneRewardsBatch`, all included items' rewards are merged into a\n  **single** `ResourceBundle` (`BatchSupport.MergeBundles`) and charged/granted\n  in one call — the merged `ResourceOperation` is attached to only the **first\n  successful** `BatchItemResult.Data.Resources` in the returned array; every\n  other successful item's `Data.Resources` is an **empty** `ResourceOperation`\n  (`new ResourceOperation()`), not a duplicate of the shared one. Don't sum\n  resources across batch items — read them once from wherever they landed (the\n  TS SDK's `applyResourceOperation` is only ever called once, on the first\n  `Resources` it finds, matching this).\n- **Batch size.** `BatchSupport.MaxBatchSize = 50`. Both\n  `claimQuestRewardsBatch` and `claimMilestoneRewardsBatch` accumulate refs from\n  your array only up to 50 (after deduping by `CycleID+QuestID` /\n  `CycleID+MilestoneID`); anything past the 50th valid, deduped entry is\n  **silently dropped** — it never appears in the result array at all, so a\n  `results.length` shorter than your input isn't necessarily an error. Chunk\n  larger sets yourself.\n- **Batch validity filtering happens before charging.** Each item is\n  independently checked (mongo-safety, config existence, gates, schedule\n  window, prerequisites, current `Status`) and rejected into a preset\n  `BatchItemResult` **before** the shared resource operation runs; only\n  surviving items contribute to the merged grant and the combined Mongo filter\n  (`AND` of each item's own OCC filter). That combined filter means: if even\n  one surviving item's condition is no longer true by the time the transaction\n  actually commits (e.g. a race with another request), **the entire merged\n  operation fails** and every surviving item in that batch call reports the\n  same `apply.Error` — \"partial-aware\" describes the **pre-filtering** stage,\n  not protection against a mid-flight race on the shared charge.\n- **Rate limit / lock.** The whole `QuestV2` function uses\n  `RateLimitMilliseconds = 500` (per-IP endpoint throttle) and\n  `LockDurationMilliseconds = 10000` (per-user-action Mongo transaction lock)\n  inside `ClientRun.Execute` — both are backend-side controls independent of\n  the TS SDK's own 600ms client-side throttle guard.\n"
+      "content": "# Quest data model — reference\r\n\r\nFull shape of the config (Definitions) and player state, the cycle/schedule\r\nresolution rules, the points-track (\"Achievements\") plumbing, group-completion\r\nmath, and the server-side limits/idempotency rules. All of these are **strictly\r\ntyped in the SDK** — `QuestDefinitions` and every nested block (`QuestDefinition`,\r\n`QuestCycleDefinition`, `QuestObjectiveDefinition`, `QuestGroupCompletionDefinition`,\r\nthe shared `ScheduleSpec`/`SegmentGate`/`LimitSpec`/`MilestoneDefinition`/\r\n`EventTokenDefinition` blocks, …) are exported from `@idosgames/core`, so\r\n`getQuestDefinitions()` and `getSection<QuestDefinitions>(\"Quest\")` give you\r\nconcrete types, not `unknown`. The schemas keep `.passthrough()`, so a field the\r\nbackend adds later still round-trips. Field names are PascalCase (straight from\r\nthe backend JSON).\r\n\r\nBackend source of truth for everything below:\r\n`IDosGamesSDK/API/Client/v2/Quest/Quest.cs`,\r\n`IDosGamesSDK/API/Client/v2/Quest/Models/QuestDefinitions.cs`,\r\n`IDosGamesSDK/API/Client/v2/Quest/Models/UserQuestState.cs`,\r\n`IDosGamesSDK/API/Core/Scheduling/Services/ScheduleResolver.cs`,\r\n`IDosGamesSDK/API/Core/Event/Services/EventTokenService.cs`.\r\n\r\n## Contents\r\n\r\n- [Player state](#player-state) — what `getUserQuestState()` returns\r\n- [Config: QuestDefinitions](#config-questdefinitions) — what `getQuestDefinitions()` returns\r\n- [QuestCycleDefinition](#questcycledefinition)\r\n- [QuestDefinition](#questdefinition)\r\n- [QuestObjectiveDefinition + progress aggregation](#questobjectivedefinition--progress-aggregation)\r\n- [Prerequisites (`RequiredQuestIDs`)](#prerequisites-requiredquestids)\r\n- [Cycle schedule resolution](#cycle-schedule-resolution)\r\n- [Per-quest schedule (\"staged unlock\" / Achievements)](#per-quest-schedule-staged-unlock--achievements)\r\n- [Points track (\"Achievements\") — the Quest event-token](#points-track-achievements--the-quest-event-token)\r\n- [Group-completion (grand reward) math](#group-completion-grand-reward-math)\r\n- [`AddQuestProgress` server-side rules](#addquestprogress-server-side-rules)\r\n- [Idempotency, atomicity, batch limits](#idempotency-atomicity-batch-limits)\r\n\r\n---\r\n\r\n## Player state\r\n\r\nReturned by `getUserQuestState()` as `{ State, PointsTracks }` and cached at\r\n`client.data.user.state?.Quest` (progress) + `client.data.user.state?.EventToken?.Quest`\r\n(points track — see below). Hand-written interfaces (not `z.infer`) because the\r\ncache-patch methods mutate these objects in place.\r\n\r\n```ts\r\ninterface UserQuestState {\r\n  Cycles?: Record<string, UserQuestCycleState>; // key = CycleID\r\n  PermanentQuests?: Record<string, UserQuestProgress>; // key = QuestID\r\n  LastUpdatedUtc?: string;\r\n}\r\n\r\ninterface UserQuestCycleState {\r\n  CycleID?: string;\r\n  CycleStartUtc?: string; // current window start, UTC\r\n  CycleEndUtc?: string; // current window end, UTC\r\n  Quests?: Record<string, UserQuestProgress>; // key = QuestID, THIS window only\r\n  ClaimedGroupCompletionIDs?: string[]; // CompletionIDs already claimed this window\r\n}\r\n\r\ninterface UserQuestProgress {\r\n  QuestID: string;\r\n  Status: \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\";\r\n  ActivatedAtUtc?: string | null;\r\n  CompletedAtUtc?: string | null;\r\n  ClaimedAtUtc?: string | null;\r\n  Objectives?: Record<string, UserQuestObjectiveProgress>; // key = ObjectiveID\r\n}\r\n\r\ninterface UserQuestObjectiveProgress {\r\n  ObjectiveID: string;\r\n  CurrentValue: number;\r\n  Completed: boolean;\r\n  CompletedAtUtc?: string | null;\r\n}\r\n```\r\n\r\n**Lazy initialization** (`Quest.cs` `RefreshQuestCycles` / `CreateQuestProgressFromDefinition`):\r\na quest's `UserQuestProgress` (and each objective's `UserQuestObjectiveProgress`)\r\nis created only the first time progress is reported for it — the server does\r\n**not** pre-populate every configured quest/objective with zeros. A quest absent\r\nfrom `Cycles[cycleID].Quests` (or `PermanentQuests`) simply has zero progress on\r\nevery objective; render it as `\"Active\"`, not as an error or \"unknown\" state.\r\n`Expired` is only ever set for cyclic quests (never for permanent quests) and\r\nonly via the same lazy path — in practice you will see `Active` → `Completed` →\r\n`Claimed` for anything you've touched; a truly stale quest from a rolled-over\r\ncycle is simply absent (the whole cycle bucket gets replaced on rollover, see\r\nbelow), not flagged `Expired` in current code paths.\r\n\r\n---\r\n\r\n## Config: QuestDefinitions\r\n\r\nReturned by `getQuestDefinitions()`; cached via\r\n`client.data.config.getSection<QuestDefinitions>(\"Quest\")`.\r\n\r\n```ts\r\ninterface QuestDefinitions {\r\n  Cycles?: Record<string, QuestCycleDefinition>; // key = CycleID\r\n  Quests?: Record<string, QuestDefinition>; // key = QuestID\r\n}\r\n```\r\n\r\nA quest is **permanent** iff its `CycleIDs` is null/empty; otherwise it is\r\n**cyclic** and belongs to every cycle listed in `CycleIDs` (a quest can appear\r\nin more than one cycle definition, each with independent progress/claim state).\r\nCycle IDs and quest/objective IDs must all be Mongo-safe (no `.` or `$`) —\r\nthe server rejects unsafe keys outright (`\"Invalid CycleID (mongo-unsafe): …\"`,\r\n`\"QuestID is mongo-unsafe\"`, etc.); this only matters if you let players or\r\nremote config drive raw ids into these fields.\r\n\r\n---\r\n\r\n## QuestCycleDefinition\r\n\r\n`Quest.cs` / `QuestDefinitions.cs`. One recurring or one-off \"board\" (dailies,\r\nweeklies, a scheduled event window, …). Quests do **not** get listed here —\r\neach `QuestDefinition` points back at the cycle via `CycleIDs`.\r\n\r\n```ts\r\ninterface QuestCycleDefinition {\r\n  CycleID?: string;\r\n  DisplayName?: string;\r\n  Schedule?: ScheduleSpec; // cycle window/reset — see below\r\n  Milestones?: Record<string, MilestoneDefinition>; // points-track rungs, key = MilestoneID\r\n  Phases?: Record<string, QuestPhaseDefinition>;    // chain phases, only for Schedule.Mode = \"Chained\"\r\n  Presets?: { Milestones?: PresetBinding };         // cycle-level preset wiring (Core/Presets)\r\n  AssetPaths?: Record<string, string>;\r\n  CustomParams?: Record<string, string>;\r\n  Gate?: SegmentGate; // audience gate for the whole cycle; ANDed with each quest's own Gate\r\n  PointsToken?: EventTokenDefinition; // global caps/burn for the points track (see below)\r\n  GroupCompletions?: Record<string, QuestGroupCompletionDefinition>; // key = CompletionID\r\n}\r\n```\r\n\r\nBackend default when a cycle is authored without an explicit `Schedule`:\r\n`Mode: \"Cyclic\"`, `Cyclic: {}` (i.e. daily calendar reset) —\r\n`QuestCycleDefinition.Schedule` in `QuestDefinitions.cs`.\r\n\r\n---\r\n\r\n## QuestDefinition\r\n\r\n```ts\r\ninterface QuestDefinition {\r\n  QuestID?: string;\r\n  CycleIDs?: string[]; // null/empty => permanent; else cyclic, one entry per cycle it appears in\r\n  DisplayName?: string;\r\n  Description?: string;\r\n  SortOrder?: number; // lower = earlier in UI\r\n\r\n  RequiredQuestIDs?: string[]; // prerequisite QuestIDs — see below\r\n  PrerequisiteMode?: \"BlockProgressAndClaim\" | \"BlockClaimOnly\"; // default BlockProgressAndClaim\r\n\r\n  PointsReward?: number; // points into the cycle's points track on claim; ignored for permanent quests\r\n  Schedule?: ScheduleSpec; // per-quest unlock window; null = inherit the cycle's window (see below)\r\n  AccrueProgressWhenLocked?: boolean; // default false — see per-quest schedule section\r\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\r\n  Limits?: LimitSpec; // per-quest per-source caps on POINTS grants only (not on objective progress)\r\n  GroupID?: string; // for UI grouping + QuestGroupCompletionDefinition.GroupID matching\r\n\r\n  PhaseIDs?: string[];                 // chain phases this quest lives in; empty = all\r\n  AssetPaths?: Record<string, string>; // task icon\r\n  CustomParams?: Record<string, string>;\r\n  Objectives?: Record<string, QuestObjectiveDefinition>; // key = ObjectiveID; ALL must complete\r\n  Reward?: ResourceGrant; // claimed via claimQuestReward\r\n}\r\n```\r\n\r\n`PrerequisiteMode` (`QuestDefinition.cs` comment, verbatim intent):\r\n\r\n| Mode                              | Effect on `RequiredQuestIDs`                                                                                                                            |\r\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| `BlockProgressAndClaim` (default) | The quest does not start accruing progress at all until every listed prerequisite reaches `Completed`/`Claimed`; consequently it also can't be claimed. |\r\n| `BlockClaimOnly`                  | Progress accrues immediately; only the final reward claim is blocked until prerequisites are met.                                                       |\r\n\r\nA prerequisite is looked up \"where its own progress lives\": permanent →\r\n`PermanentQuests`; cyclic → the same `cycleID` if the prerequisite also belongs\r\nto it, otherwise the prerequisite's own first `CycleIDs` entry\r\n(`ArePrerequisitesMet`, `Quest.cs`). Empty/null `RequiredQuestIDs` = no gating.\r\n\r\n---\r\n\r\n## Chains — a cycle that runs phases one after another\r\n\r\nSet the cycle's `Schedule.Mode` to `\"Chained\"` and fill `Phases`. The chain starts at\r\n`Schedule.Chain.AnchorUtc`, plays its phases in `Order`, then repeats (`MaxCycles`, pauses).\r\n\r\n```ts\r\ninterface QuestPhaseDefinition {\r\n  PhaseID?: string;        // unique within the chain; referenced by QuestDefinition.PhaseIDs\r\n  Order?: number;          // position within one full pass (0, 1, 2...)\r\n  DurationSec?: number;    // how long the phase stays open\r\n  ClaimGraceHours?: number;// extra claim window after it ends\r\n  DisplayName?: string;\r\n  AssetPaths?: Record<string, string>;\r\n  CustomParams?: Record<string, string>;\r\n  Gate?: SegmentGate;                                 // AND-ed with cycle gate and quest gate\r\n  Milestones?: Record<string, MilestoneDefinition>;   // null = the cycle's ladder is used\r\n  Presets?: { Milestones?: PresetBinding };\r\n  PointsToken?: EventTokenDefinition;                 // null = the cycle's token\r\n}\r\n```\r\n\r\nThree rules worth knowing before designing one:\r\n\r\n- **Every phase owns its progress.** The points-track address includes the instance key, and for\r\n  a phase that key is `chain:{cycleIndex}:{phaseID}`. So week 2 starts from zero points with its\r\n  own claimed-milestone list — it never inherits week 1. The cycle's quest state resets at a phase\r\n  boundary exactly like it resets at midnight for a `Daily` cycle.\r\n- **Unset phase content falls back to the cycle.** Eight identical weeks are eight phases with\r\n  only `Order`/`DurationSec` filled — not eight copies of the milestone ladder. The exception is an\r\n  *empty* (not absent) `Milestones` object: that explicitly means \"no milestones in this phase\".\r\n- **A `Chained` cycle with no phases never activates.** There is nothing to resolve, so the whole\r\n  cycle stays closed and its quests never progress.\r\n\r\nBind a quest to specific phases with `QuestDefinition.PhaseIDs` (empty = every phase). It gates\r\nboth progress and claiming — a week-2 quest cannot be claimed during week 1, in single and batch\r\nclaims alike. `PhaseIDs` is the direct way to say \"this quest belongs to week two\"; the quest's own\r\n`Schedule` with a `Relative` window stays for staged unlocking *within* one phase (\"Day N\").\r\n\r\n`GetUserQuestState` reports the live phase on each track: `PointsTracks[cycleID].PhaseID` and\r\n`.CycleIndex` (both absent/0 for a plain cycle) alongside `CycleStartUtc`/`CycleEndUtc` of that\r\nphase — enough to render \"Week 2 of 8\" and a countdown.\r\n\r\n### Milestone presets (Core/Presets)\r\n\r\n`QuestDefinitions.Presets.Milestones` is a registry of reusable `MilestoneSet`s keyed by PresetID.\r\nA cycle or a phase references one through `Presets.Milestones` (`PresetBinding`): the preset is the\r\nbase, the inline `Milestones` dictionary overrides or adds by MilestoneID, and `Remove` drops keys.\r\nNo PresetID ⇒ inline only. An unknown PresetID silently falls back to inline — it never wipes the\r\nentity's own ladder.\r\n\r\n---\r\n\r\n## QuestObjectiveDefinition + progress aggregation\r\n\r\n```ts\r\ninterface QuestObjectiveDefinition {\r\n  ObjectiveID?: string;\r\n  Source?: \"ClientApi\" | \"ServerApi\" | \"SystemEvent\"; // what advances it; default ClientApi\r\n  MaxProgressPerCall?: number; // ClientApi BAN threshold (not a clamp); 0/absent = no check\r\n  MetricID?: string; // ClientApi/ServerApi only: the metric key reported against\r\n  Triggers?: TriggerSource[]; // SystemEvent only: in-game events that advance it\r\n  TargetValue?: number; // default 1; required value to complete\r\n  AggregationMethod?: string; // \"Sum\" | \"Maximum\" | \"Minimum\" | \"Last\"; default \"Sum\"\r\n}\r\n```\r\n\r\n`Source` selects **which field is read** — they are mutually exclusive:\r\n\r\n| Source        | Advanced by                                     | Field read   |\r\n| ------------- | ----------------------------------------------- | ------------ |\r\n| `ClientApi`   | the game calling `addQuestProgress(MetricID, v)` | `MetricID`   |\r\n| `ServerApi`   | a CloudCode script calling `server.AddQuestProgress(MetricID, v)` | `MetricID` |\r\n| `SystemEvent` | the backend itself, on in-game events           | `Triggers`   |\r\n\r\n`addQuestProgress` reaches **only** `ClientApi` objectives; a `MetricID` with no\r\nmatching `ClientApi` objective anywhere in the catalog is rejected outright\r\n(`\"MetricID not allowed for ClientApi\"`).\r\n\r\n### `Triggers` — SystemEvent objectives\r\n\r\n`Triggers` is the shared `TriggerSource` used by `EventContent.TokenSources`\r\n(TimedEvent) and `LeaderboardDefinition.ScoreSources`: an event type plus\r\nfilters, with `BaseWeight` as the progress step per fire. The list is OR-ed\r\n(first match wins). Empty/absent ⇒ the objective never advances.\r\n\r\nThe backend emits these event types into quests — anything else in\r\n`EventTokenSourceType` never reaches a quest (use `ClientApi` for\r\nclient-observed actions like watching an ad):\r\n\r\n`BoardTileLanding`, `BoardPassStart`, `BoardAttack`, `BoardRaid`, `BoardBuild`,\r\n`BoardStageComplete`, `BoardSpecialComplete` (GameLoop) · `StorePurchase`\r\n(`Store.Purchase` / `PurchaseBatch`, multiplier = purchase count) ·\r\n`MarketplaceSell` / `MarketplaceBuy` (settlement, **acting player only**) ·\r\n`QuestComplete` (`ClaimQuestReward`, for meta-quests).\r\n\r\n`Params` filters the matcher actually checks: `StorePurchase` → `OfferID`;\r\n`QuestComplete` → `QuestID`, `CycleID`; `Marketplace*` → `CatalogID`, `ItemID`,\r\n`OfferType`; `CustomAction` → `ActionName`. Any other key is stored but ignored.\r\n\r\nSet `ScaleWithRollMultiplier: false` on a quest trigger unless you *want* the\r\nboard's roll multiplier to inflate the step — otherwise \"win 3 raids\" closes on\r\na single x3 raid.\r\n\r\n`SystemEvent` progress is applied **after** the handler succeeds and returns on\r\nthat response's envelope as `QuestProgress: QuestProgressUpdate[]` (absent when\r\nnothing moved). The guarantee is at-most-once: the game action is already\r\ncommitted, so a failure here loses the event rather than rolling the action back.\r\n\r\nAggregation (`ApplyAggregation`, `Quest.cs`), given the objective's current\r\n`CurrentValue` and the incoming call value:\r\n\r\n| Method                   | New value                                                                                |\r\n| ------------------------ | ---------------------------------------------------------------------------------------- |\r\n| `Sum` (default)          | `current + incoming`, clamped to `long.MaxValue` on overflow; `incoming <= 0` is a no-op |\r\n| `Maximum`                | `max(current, incoming)`                                                                 |\r\n| `Minimum`                | `incoming` if `current == 0`, else `min(current, incoming)`                              |\r\n| `Last` (or unrecognized) | `incoming` (last-write-wins)                                                             |\r\n\r\nAfter aggregation, if `TargetValue > 0` the new value is clamped to\r\n`TargetValue` (progress bars never overshoot 100%); if `TargetValue <= 0` there\r\nis no cap. An objective is marked `Completed` once\r\n`(TargetValue <= 0 && newValue > 0) || newValue >= TargetValue`. A quest becomes\r\n`\"Completed\"` once **every** objective the player has a progress record for is\r\n`Completed` **and** every objective in the definition has a progress record —\r\ni.e. an objective with zero recorded progress blocks completion (it's absent\r\nfrom the player's `Objectives` map, so the `All(...)` check in\r\n`EnsureQuestObjectivesAndCompletion` fails for it).\r\n\r\n`MaxProgressPerCall` guards two different things depending on\r\n`AggregationMethod`:\r\n\r\n- If **any** matching `ClientApi` objective for the `MetricID` has\r\n  `MaxProgressPerCall > 0`, the server compares the **raw** `ProgressValue` you\r\n  sent against the (minimum across matches) cap **before** any clamping. If the\r\n  raw value exceeds it, the call is rejected **and the player is banned**\r\n  (`service.BanUser(...)`, fire-and-forget) with error `\"User banned: Value\r\nexceeds MaxValuePerCall\"`. This is a hard anti-abuse trip-wire, not a soft\r\n  clamp — never let client code send inflated values \"to be safe.\"\r\n- Only for objectives using `Sum` aggregation is the value additionally\r\n  clamped to `MaxProgressPerCall` before summing (defense in depth; irrelevant\r\n  once the ban-check above has already passed, since raw ⇐ cap by that point).\r\n\r\n---\r\n\r\n## Prerequisites (`RequiredQuestIDs`)\r\n\r\nSee the `PrerequisiteMode` table above. Enforcement points in `Quest.cs`:\r\n\r\n- **Progress accrual** (`AddQuestProgress` internal helper): for permanent\r\n  quests and for each cycle a cyclic quest belongs to, prerequisites are\r\n  checked (only in `BlockProgressAndClaim` mode) before the quest's\r\n  `UserQuestProgress` is even created/updated for that call.\r\n- **Claim** (`ClaimQuestReward` / batch): `ArePrerequisitesMet(...)` is checked\r\n  unconditionally (both modes gate the claim) — error\r\n  `\"Prerequisite quests are not completed\"`.\r\n\r\n---\r\n\r\n## Cycle schedule resolution\r\n\r\n`QuestCycleDefinition.Schedule` is a `ScheduleSpec` (`_shared/ScheduleModels.ts`\r\n/ `Core/Scheduling`), the same primitive every other module uses. For Quest,\r\n`RefreshQuestCycles` resolves it via `ScheduleResolver.ResolveActive(...)`\r\ninto a `[CycleStartUtc, CycleEndUtc)` window per the active `Mode`:\r\n\r\n- **`Cyclic`** (the practical default for dailies/weeklies): `Cyclic.Reset` picks\r\n  the calendar cadence — `Hourly`/`Daily`/`Weekly` (always **Monday** start)/`Monthly`\r\n  (always the **1st**)/`Yearly` are calendar-aligned in **UTC**, reset time is\r\n  **always 00:00:00 UTC** and is not configurable. `FixedInterval` instead repeats\r\n  every `Cyclic.IntervalSeconds` seconds from `Cyclic.AnchorUtc` (default anchor\r\n  `2026-01-01T00:00:00Z`, default interval 86400s if unset/≤0); an optional\r\n  `PauseBetweenCyclesSec` inserts a dead gap after each active window during\r\n  which `CanEarn` is `false` (`IsInPause = true`) but the window has still\r\n  technically \"ended\" — new progress does not accrue during the pause, though\r\n  already-completed quests remain claimable (claims are never earn-gated).\r\n- **`Scheduled`**: one fixed `[StartUtc, EndUtc]` window; `ClaimGraceHours`\r\n  extends claimability past `EndUtc` without extending earning (unless\r\n  `AllowEarningAfterEnd` is set).\r\n- **`AlwaysOn`**: always active, no end.\r\n- Any other/inactive resolution (e.g. `Triggered`, or `spec.IsActive === false`)\r\n  makes `ComputeCycleWindowUtc` **degrade to a plain UTC calendar day**\r\n  `[today 00:00, tomorrow 00:00)` as a fallback — don't configure `Triggered` on\r\n  a quest cycle expecting anything else.\r\n\r\n**Rollover behavior** (`RefreshQuestCycles`, called automatically by\r\n`getUserQuestState({autoRefreshCycles: true})` — the default — and before every\r\nmutating Quest action): when the resolved `[start, end)` no longer matches the\r\nstored `CycleStartUtc`/`CycleEndUtc`, the entire `UserQuestCycleState` for that\r\ncycle is **replaced with a brand-new, empty one** (`Quests: {}`,\r\n`ClaimedGroupCompletionIDs` reset) — there is no partial carry-over of\r\nin-progress quests into the new window. Cycles removed from config entirely are\r\ndeleted from the player's state on the next refresh. If the window has **not**\r\nrolled over, the refresh instead walks the player's **existing** quest progress\r\nrecords (only ones already started) and re-evaluates `Completed` status against\r\ncurrent config — it does not add new objectives to already-tracked quests.\r\n\r\n---\r\n\r\n## Per-quest schedule (\"staged unlock\" / Achievements)\r\n\r\n`QuestDefinition.Schedule` is an **independent, optional** `ScheduleSpec` layered\r\non top of the cycle's own schedule — this is how \"Day 2 unlocks 24h after Day 1\"\r\nor an \"Achievements\" track with a `ScheduleSpec`-driven unlock (rather than a\r\nliteral day-count) is built, with any number of stages at any interval, not just\r\nliteral days:\r\n\r\n- `Schedule` absent → the quest simply inherits its cycle's window; earning and\r\n  claiming follow the cycle's own `CanEarn`/`CanClaim`.\r\n- `Schedule` present → resolved via `ResolveQuestInstance`, which passes the\r\n  **cycle's** resolved instance as the `parent` for `Relative`-mode windows —\r\n  so a per-quest `Relative` schedule with `OffsetSecondsFromParentStart` is\r\n  \"N seconds after this cycle instance started,\" letting one `Cyclic` cycle\r\n  auto-repeat a whole staged sequence without hardcoded absolute dates.\r\n- `AccrueProgressWhenLocked` (default `false`) decides what happens **while**\r\n  the cycle's window is open but the quest's own window is not: `false` means a\r\n  locked stage accrues **zero** progress (a true lock — progress reported for\r\n  its metric while locked is simply dropped for that quest); `true` means\r\n  progress accrues the whole time the cycle is active, but the **reward claim**\r\n  is still gated on the quest's own `CanClaim` — so you can pre-accrue \"Day 3\"\r\n  progress while day 3 is still locked, and only the payout waits.\r\n\r\nEarning gate precedence for a cyclic quest, all of which must pass\r\n(`AddQuestProgress` internal helper): cycle `earningCycles` membership (cycle\r\nitself must be `CanEarn`, i.e. not `IsInPause`) → quest's own\r\n`IsQuestEarnable` (`AccrueProgressWhenLocked` bypasses this specific check) →\r\n`QuestGatesPass` (cycle `Gate` AND quest `Gate`) → prerequisites (only in\r\n`BlockProgressAndClaim` mode).\r\n\r\n---\r\n\r\n## Points track (\"Achievements\") — the Quest event-token\r\n\r\nThis is the mechanism the \"Achievements\" hint in the prompt refers to — it is\r\nreal and it is exactly the cycle's points track, not a separate module. Russian\r\ncomments in `Quest.cs` literally label it «Достижения» (Achievements).\r\n\r\n**How points get earned.** Each cyclic `QuestDefinition.PointsReward` (points,\r\nnot currency) is granted **only on claim** of that quest's own reward — via\r\n`ClaimQuestReward` / `ClaimQuestRewardsBatch`, in the **same atomic transaction**\r\nas the quest's `Reward` grant. It's `long`, defaults to `0`, and is ignored for\r\npermanent quests (`isPermanent` quests never touch the points track). A group\r\ncompletion (below) can **also** add points via its own `PointsReward`, on top of\r\nwhatever its member quests already contributed individually.\r\n\r\n**Where it's addressed.** The points track is backed by a standard\r\n`EventTokenType.Quest` event token (the same primitive TimedEvent/Leaderboard/\r\nCoopEvent/Season points tracks use), addressed at\r\n`EntityID = \"{cycleID}:{instanceKey}\"` where `instanceKey` comes from\r\n`ScheduleResolver`'s resolution of the **cycle's** schedule (`\"all\"` if the\r\ncycle has no resolvable instance). Because the instance key changes when the\r\ncycle's schedule rotates to a new window, **the points balance and claimed-milestone\r\nlist reset automatically on cycle rollover** — there is no explicit\r\n\"reset points\" step; it's a natural consequence of the address changing.\r\n\r\n**Where it lives in state.** `UserQuestState` does **not** carry the points\r\nbalance — it lives in `UserDataDocument.EventToken.Quest[entityID]`\r\n(`UserEventTokenProgress`: `Balance.Current`/`Balance.TotalEarned`,\r\n`Milestone.ClaimedIDs`). `GetUserQuestState` additionally projects a **read-only\r\nsnapshot** per cycle into `GetUserQuestStateResponse.PointsTracks[cycleID]`\r\n(`QuestPointsTrackView`) so the client doesn't have to know the composite key —\r\nthe TS SDK's `patchQuestPointsTracks` writes this into\r\n`client.data.user.state.EventToken.Quest[\"{cycleID}:{instanceKey}\"]` for you,\r\nand `client.data.user.getQuestPointsProgress(cycleID)` resolves the composite\r\nkey back out (`matchesBase`, `util/eventTokenIds.ts`) so you can look it up by\r\nplain `cycleID`.\r\n\r\n```ts\r\ninterface QuestPointsTrackView {\r\n  CycleID: string;\r\n  InstanceKey?: string | null;\r\n  CycleStartUtc?: string | null;\r\n  CycleEndUtc?: string | null; // source for a \"resets in\" timer\r\n  PointsTotalEarned?: number | null; // lifetime points earned this cycle instance\r\n  PointsCurrent?: number | null; // current balance (== TotalEarned; points are never spent)\r\n  ClaimedPointMilestoneIDs?: string[] | null;\r\n}\r\n```\r\n\r\n**Milestones** (`QuestCycleDefinition.Milestones`, keyed by `MilestoneID`) are\r\nthe shared Core `MilestoneDefinition` primitive\r\n(`RequiredProgress`, `Rewards`, `BonusRewards`, `SeasonTierRewards`,\r\n`SortOrder`, `IsFeatured`) — see `_shared/MilestoneModels.ts`. Eligibility is\r\njudged **only** against `Balance.TotalEarned` on the points token (never\r\n`Current`, though for Quest the two happen to always be equal since points are\r\nonly ever granted, never spent) — `EventTokenService.ComputeMilestoneClaim`:\r\nfails with `\"Not enough earned. Have: X, need: Y.\"` if under threshold, or\r\n`\"Milestone already claimed.\"` if `MilestoneID` is already in `ClaimedIDs`.\r\nClaiming pushes the id into `ClaimedIDs` via a Mongo `$push` guarded by a\r\n`$nin` filter (OCC — a concurrent duplicate claim loses the race cleanly). The\r\nmilestone's reward itself runs through the shared `MilestoneRewardResolver`\r\n(same resolver Leaderboard/TimedEvent/CommunityChest/Referral use), which\r\napplies the title's progression-multiplier overlay\r\n(`cfg.Reward.MilestoneRewardMultiplier`) if configured — so the actual payout\r\ncan exceed the base `Rewards` grant; read it from the response, don't assume\r\nface value.\r\n\r\n**Caps** on points grants (`BuildPointsGrantContext`): **global** caps come from\r\n`QuestCycleDefinition.PointsToken` (an `EventTokenDefinition` — `DailyEarnCap`,\r\n`MaxBalance`, `MaxPerGrant`); **per-quest-source** caps/cooldown come from\r\n`QuestDefinition.Limits` (a `LimitSpec`, mapped as `DailyWeightCap` →\r\nper-source daily cap, `DailyCap` → per-source daily trigger count,\r\n`CooldownSeconds` → per-source cooldown). Per-source limits only apply in the\r\n**single** `ClaimQuestReward` path — the batch claim path\r\n(`ClaimQuestRewardsBatch`) only enforces the cycle's **global** `PointsToken`\r\ncaps against the **summed** batch amount per address, since per-source limits\r\ndon't make sense once amounts from multiple quests are merged into one token\r\noperation. If a cap fully exhausts the grant, `EventTokenService.ComputeGrant`\r\ncan reduce the amount to `0`, which surfaces as a failed points portion inside\r\nthe resource operation — always read granted amounts from the response, never\r\nassume the full `PointsReward` landed.\r\n\r\n---\r\n\r\n## Group-completion (grand reward) math\r\n\r\n`QuestCycleDefinition.GroupCompletions[completionID]` (`QuestGroupCompletionDefinition`):\r\n\r\n```ts\r\ninterface QuestGroupCompletionDefinition {\r\n  CompletionID?: string;\r\n  GroupID?: string; // must match QuestDefinition.GroupID on member quests\r\n  RequiredCompletedQuests?: number; // 0 = \"ALL quests in this group, per current config\"\r\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\r\n  Reward?: ResourceGrant;\r\n  PointsReward?: number; // additional points into the SAME cycle points track; 0 = none\r\n}\r\n```\r\n\r\n`ClaimGroupCompletionReward` computes eligibility **live**, at claim time, by\r\nscanning the **current** `QuestDefinitions.Quests` for every quest that (a)\r\nlists this `cycleID` in its `CycleIDs` and (b) has `GroupID` equal to the\r\ncompletion's `GroupID` — that's `totalGroupQuests`. Of those, it counts how many\r\nhave reached `Status === \"Completed\"` **or** `\"Claimed\"` in the player's current\r\ncycle state — that's `completedGroupQuests`. The required threshold is\r\n`RequiredCompletedQuests` if `> 0`, otherwise `totalGroupQuests` (i.e. every\r\ngroup quest currently in config). Failure modes:\r\n\r\n- `RequiredCompletedQuests` unset and the group is empty/misconfigured (no\r\n  quests currently reference that `GroupID` in that cycle) →\r\n  `\"No quests configured for this group\"` (required resolves to `0`, which is\r\n  rejected outright — you can never claim an empty group).\r\n- `completedGroupQuests < required` → `\"Not enough completed quests for this\r\ngroup\"`.\r\n- Already in `cycle.ClaimedGroupCompletionIDs` → `\"Group completion already\r\nclaimed\"` (checked in-memory before the DB round-trip, then re-enforced by an\r\n  `AnyEq`-negated Mongo filter for the actual OCC guard).\r\n- `completion.GroupID` blank/whitespace on the definition itself →\r\n  `\"Group completion has no GroupID\"` (a config error, not a player error).\r\n\r\nBecause the scan is **live against current config**, removing a quest from the\r\ngroup (or from the cycle) between when a player completed it and when they\r\nclaim the group reward can change `totalGroupQuests`/`completedGroupQuests` —\r\nthere's no snapshot of \"the group as it was.\" The response echoes\r\n`CompletedGroupQuests` and `RequiredGroupQuests` (the resolved threshold, not\r\nthe raw config field) so the client can show \"3 / 3\" without recomputing\r\nanything.\r\n\r\n---\r\n\r\n## `AddQuestProgress` server-side rules\r\n\r\nFull request-to-mutation path (`QuestV2.AddQuestProgress` public entry point +\r\nthe internal shared helper), summarized because several rules only make sense\r\ntogether:\r\n\r\n1. `MetricID` required; must match at least one `ClientApi`-sourced objective\r\n   in the **entire** quest catalog, or the call fails with `\"MetricID not\r\nallowed for ClientApi\"` before touching the database.\r\n2. `ProgressValue` (`long`) must be `>= 0`.\r\n3. If any matching objective declares `MaxProgressPerCall > 0`, the **raw**\r\n   value is checked against the smallest such cap across all matches; exceeding\r\n   it **bans the account** (see the objective section above) rather than\r\n   clamping — this is a hard security control, not UX guidance.\r\n4. The (possibly `Sum`-clamped) value then fans out to **every** quest/objective\r\n   pair across **every currently-earning cycle and every permanent quest**\r\n   whose objective's `Source === \"ClientApi\"` and `MetricID` matches — one\r\n   `addQuestProgress` call can move several quests (even across different\r\n   cycles) simultaneously if they all listen to the same metric.\r\n5. Each matched quest only advances if it isn't already `Completed`/`Claimed`\r\n   (`ApplyToQuestInstance` early-returns `false` otherwise) — so calling\r\n   `addQuestProgress` for an action a player keeps performing after a quest is\r\n   done is safe and a no-op for that quest.\r\n6. The response's `Updates[]` (`QuestProgressUpdate`) lists **only the\r\n   quest/objective pairs that actually changed** this call — an objective whose\r\n   `Sum` increment was clamped to `0` (already at `TargetValue`) or a locked\r\n   quest that accrued nothing produces no entry.\r\n7. This whole path calls `RefreshQuestCycles` first (unless the internal helper\r\n   is invoked with `ensureCyclesUpToDate: false`, which the public\r\n   `AddQuestProgress` action does to avoid double-refreshing) — so cycle\r\n   windows are always current before progress is evaluated.\r\n\r\n---\r\n\r\n## Idempotency, atomicity, batch limits\r\n\r\n- **Idempotency keys** (`ResourceService.ResolveRelatedEntityID`, stable ID\r\n  patterns from `Quest.cs`): single quest claim →\r\n  `\"{questID}\"` (permanent) or `\"{questID}_{cycleStartUtc:yyyyMMddHHmmss}\"`\r\n  (cyclic — so the **same** quest claimed again after the cycle rolls to a new\r\n  window is a distinct idempotency key, not a duplicate); milestone claim →\r\n  `\"{cycleID}_{milestoneID}_{instanceKey}\"`; group completion →\r\n  `\"{cycleID}_{completionID}_{cycleStartUtc:yyyyMMddHHmmss}\"`. You never\r\n  construct these yourself — the TS SDK mints its own client-side\r\n  `RelatedEntityID` (`quest_claim_…`, `milestone_claim_…`, `group_completion_…`,\r\n  each suffixed with a fresh UUID) purely for its own request-level tracking;\r\n  the **server-side** idempotency guarantee comes from the stable IDs above\r\n  plus the OCC filter on each claim, not from the client's `RelatedEntityID`.\r\n- **Atomicity.** Every claim path (`ClaimQuestReward`, `ClaimMilestoneReward`,\r\n  `ClaimGroupCompletionReward`, and both batch variants) runs the reward grant\r\n  and the state-mutating patches (status → `Claimed`, milestone `$push`, group\r\n  `$addToSet`) inside **one** `ResourceService.ApplyResourceOperationAtomicAsync`\r\n  call with an `extraFilter` re-asserting the pre-claim condition (e.g. quest\r\n  `Status == Completed`) — if the grant fails for any reason (insufficient\r\n  server-side room, a concurrent claim already flipped the filter condition,\r\n  etc.) the whole transaction rolls back; there is no partially-applied claim.\r\n- **Resources in batch responses.** For both `ClaimQuestRewardsBatch` and\r\n  `ClaimMilestoneRewardsBatch`, all included items' rewards are merged into a\r\n  **single** `ResourceBundle` (`BatchSupport.MergeBundles`) and charged/granted\r\n  in one call — the merged `ResourceOperation` is attached to only the **first\r\n  successful** `BatchItemResult.Data.Resources` in the returned array; every\r\n  other successful item's `Data.Resources` is an **empty** `ResourceOperation`\r\n  (`new ResourceOperation()`), not a duplicate of the shared one. Don't sum\r\n  resources across batch items — read them once from wherever they landed (the\r\n  TS SDK's `applyResourceOperation` is only ever called once, on the first\r\n  `Resources` it finds, matching this).\r\n- **Batch size.** `BatchSupport.MaxBatchSize = 50`. Both\r\n  `claimQuestRewardsBatch` and `claimMilestoneRewardsBatch` accumulate refs from\r\n  your array only up to 50 (after deduping by `CycleID+QuestID` /\r\n  `CycleID+MilestoneID`); anything past the 50th valid, deduped entry is\r\n  **silently dropped** — it never appears in the result array at all, so a\r\n  `results.length` shorter than your input isn't necessarily an error. Chunk\r\n  larger sets yourself.\r\n- **Batch validity filtering happens before charging.** Each item is\r\n  independently checked (mongo-safety, config existence, gates, schedule\r\n  window, prerequisites, current `Status`) and rejected into a preset\r\n  `BatchItemResult` **before** the shared resource operation runs; only\r\n  surviving items contribute to the merged grant and the combined Mongo filter\r\n  (`AND` of each item's own OCC filter). That combined filter means: if even\r\n  one surviving item's condition is no longer true by the time the transaction\r\n  actually commits (e.g. a race with another request), **the entire merged\r\n  operation fails** and every surviving item in that batch call reports the\r\n  same `apply.Error` — \"partial-aware\" describes the **pre-filtering** stage,\r\n  not protection against a mid-flight race on the shared charge.\r\n- **Rate limit / lock.** The whole `QuestV2` function uses\r\n  `RateLimitMilliseconds = 500` (per-IP endpoint throttle) and\r\n  `LockDurationMilliseconds = 10000` (per-user-action Mongo transaction lock)\r\n  inside `ClientRun.Execute` — both are backend-side controls independent of\r\n  the TS SDK's own 600ms client-side throttle guard.\r\n"
     }
   ]
 }

package/registry/skills/title-custom-data.json

@@ -0,0 +1,6 @@
+{
+  "name": "title-custom-data",
+  "description": "Read title-wide shared data in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.titleCustomData (TitleCustomDataService): the key-value store every player of a title sees — live event state, global counters and progress bars, server-side thresholds, feature flags, remote config. Use this whenever the user wants a value that is the SAME for all players (a server-wide event, a global goal, a kill switch, a balancing knob changed without a rebuild), or touches client.titleCustomData, TitleCustomDataService, GetPublicTitleDataResponse, TitleDataScope or TitleDataBucket — even if they don't name the module. For per-player values use user-custom-data; to WRITE title data at runtime use cloud-code.",
+  "content": "---\nname: title-custom-data\ndescription: >-\n  Read title-wide shared data in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.titleCustomData (TitleCustomDataService): the\n  key-value store every player of a title sees — live event state, global\n  counters and progress bars, server-side thresholds, feature flags, remote\n  config. Use this whenever the user wants a value that is the SAME for all\n  players (a server-wide event, a global goal, a kill switch, a balancing knob\n  changed without a rebuild), or touches client.titleCustomData,\n  TitleCustomDataService, GetPublicTitleDataResponse, TitleDataScope or\n  TitleDataBucket — even if they don't name the module. For per-player values\n  use user-custom-data; to WRITE title data at runtime use cloud-code.\n---\n\n# Title custom data (iDosGames TS SDK)\n\n`TitleCustomDataService` is the title-wide key-value store: one set of values\nshared by **every player** of the title. Use it for anything global — the state\nof a live event, a server-wide progress bar, thresholds the server enforces, a\nfeature flag you want to flip without shipping a build.\n\nFor per-player values use **user-custom-data**. Putting a global value in each\nplayer's data means N copies that immediately disagree.\n\n## Mental model: two scopes, two buckets, zero client writes\n\nEvery record has a **scope** (who may write it) and a **bucket** (who may read\nit).\n\n| Scope     | Written by                                    | Cached | Typical content                                    |\n| --------- | --------------------------------------------- | ------ | -------------------------------------------------- |\n| `Static`  | publisher / AI Coder (title-data admin tools) | yes    | authored config: schedules, texts, balancing knobs |\n| `Runtime` | **CloudCode scripts only**                    | no     | live state: counters, current event phase, winners |\n\n| Bucket    | Readable by                       |\n| --------- | --------------------------------- |\n| `Public`  | game clients (this service)       |\n| `Private` | server code and CloudCode scripts |\n\n**The client has no write path at all** — not a restricted one, none. That is\nthe point: a value every player reads must not be settable by any player. To\nchange title data at runtime, write a CloudCode handler\n(`server.SetTitleCustomData` / `server.IncrementTitleCustomData`) and call it —\nsee **cloud-code**.\n\n`Static` is cached server-side alongside the title config, so an authored change\npropagates within roughly a minute. `Runtime` is never cached: a counter read\nright after a script incremented it is already correct.\n\nValues are always **strings** — JSON-encode structured data yourself.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst titleData = client.titleCustomData;\n```\n\nEvery method needs an authenticated session; without one they return\n`{ ok: false, reason: \"unauthorized\" }` rather than throwing.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>` — branch on `result.ok` before\ntouching `result.data`. `reason` is one of `\"client\"` (bad local args),\n`\"unauthorized\"`, `\"throttled\"`, `\"connection\"`, `\"validation\"`, or `\"server\"`.\n\n| Method                                 | Purpose                                              | `data` on success            |\n| -------------------------------------- | ---------------------------------------------------- | ---------------------------- |\n| `getPublicTitleData(useKnownVersion?)` | Read all public title data (both scopes).            | `GetPublicTitleDataResponse` |\n| `getPublicTitleDataKeys(keyIDs)`       | Read only the listed keys (max 50 per call).         | `GetPublicTitleDataResponse` |\n| `getTitleCustomDataDefinitions()`      | Load the schema of public keys + the title's limits. | `TitleCustomDataDefinitions` |\n\n`GetPublicTitleDataResponse`:\n\n| Field            | Meaning                                                                                   |\n| ---------------- | ----------------------------------------------------------------------------------------- |\n| `Static`         | `Record<string, TitleCustomDataRecord>` — authored values.                                |\n| `Runtime`        | `Record<string, TitleCustomDataRecord>` — live values written by scripts.                 |\n| `StaticVersion`  | Change counter of the authored part.                                                      |\n| `RuntimeVersion` | Change counter of the live part — the cheap way to detect \"did anything change\".          |\n| `NotModified`    | `true` when the server skipped the Runtime payload because nothing changed (see polling). |\n\nEach record carries `Value`, `UpdatedAt`, `Version` (per-key write counter),\n`LastWriter` and `ExpiresAt`.\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn.\n\n- `titleCustomData:definitionsLoaded` → `TitleCustomDataDefinitions`\n- `titleCustomData:publicDataLoaded` → `GetPublicTitleDataResponse`\n\n## Recipes\n\n### Read the current event state at startup\n\n```ts\nconst res = await client.titleCustomData.getPublicTitleData();\nif (!res.ok) return showError(res.error);\n\nconst phase = res.data.Runtime?.[\"event_phase\"]?.Value ?? \"idle\";\nconst endsAt = res.data.Static?.[\"event_ends_at\"]?.Value; // ISO string you authored\n```\n\n### Poll a global progress bar cheaply\n\n```ts\n// The service remembers the last RuntimeVersion and sends it along; when nothing\n// changed the server answers NotModified and skips the payload. The service still\n// fills `Runtime` from its own cache, so this branch needs no special handling.\nsetInterval(async () => {\n  const res = await client.titleCustomData.getPublicTitleData();\n  if (!res.ok) return;\n  const done = Number(res.data.Runtime?.[\"global_kills\"]?.Value ?? 0);\n  renderProgress(done, GOAL);\n}, 15_000);\n```\n\n### Fetch just the two keys a screen needs\n\n```ts\nconst res = await client.titleCustomData.getPublicTitleDataKeys([\n  \"event_phase\",\n  \"event_multiplier\",\n]);\n```\n\n### Contribute to a global counter (needs a script)\n\nThe client cannot write, so contribution goes through CloudCode:\n\n```ts\n// server side (published with the CloudCode tooling):\n// handlers.contributeKills = function (args, context) {\n//   var res = server.IncrementTitleCustomData(\"Public\", \"global_kills\", args.count | 0);\n//   if (!res.Success) throw new Error(res.Error);\n//   return { total: res.Data.Value };\n// };\n\nconst res = await client.cloudCode.execute(\"contributeKills\", { count: 3 });\nif (res.ok && !res.data.Error) {\n  const total = (res.data.FunctionResult as { total: string }).total;\n}\n```\n\n## Gotchas\n\n- **There is no `set…` here, and that is deliberate.** If you find yourself\n  wanting one, the value either belongs to the player (`user-custom-data`) or\n  must be written by a CloudCode handler.\n- **`Runtime` values change under you.** They are live, shared, and written by\n  scripts while the player is looking at them — render from the last read and\n  re-read on a cadence; don't cache one at login and treat it as stable.\n- **`NotModified` is a success, not an error.** The service refills `Runtime`\n  from its cache, so `res.data.Runtime` is always populated. Pass\n  `getPublicTitleData(false)` to force a full payload.\n- **`Private` never reaches the client.** Not filtered out — never read from the\n  database on this path. If a value you expect is missing, it is probably in the\n  private bucket and only a script can see it.\n- **Registered keys behave better.** A key registered in the title's\n  `TitleCustomData` config section gets its scope/bucket pinned, its value type\n  validated, a size limit, an optional TTL, and a `DefaultValue` that the server\n  materializes on read while the record does not exist yet. Unregistered keys\n  work but nothing protects them.\n- **`getPublicTitleDataKeys` caps at 50 keys** and rejects the whole call past\n  that — chunk larger reads yourself.\n- **Expired records simply stop appearing.** A key with a TTL is filtered on\n  read once `ExpiresAt` passes; the record is purged on the next write.\n- **`config.TitleCustomData` is the schema, not the data.** The title config\n  bundle carries the key definitions (scope, bucket, type, limits); the values\n  only come from this service.\n",
+  "references": []
+}

package/registry/skills/title-system.json

@@ -1,6 +1,6 @@
 {
   "name": "title-system",
-  "description": "Fetch the iDosGames TypeScript SDK (@idosgames/core) title-level bootstrap config via client.title (TitleService): the full title public configuration bundle, title-wide public custom data, server time, and the standalone currency/item definitions endpoints. Also documents the config-section registry (`client.data.config.getSection<T>(\"Section\")`) that every other module's skill depends on. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants app boot/init sequences, server time sync, title-wide custom data, or otherwise touches client.title, TitleService, TitlePublicConfigurationModel, getTitlePublicConfiguration, or the title-level GetCurrencyDefinitions / GetItemDefinitions calls — even if they don't name the module explicitly.",
-  "content": "---\nname: title-system\ndescription: >-\n  Fetch the iDosGames TypeScript SDK (@idosgames/core) title-level bootstrap\n  config via client.title (TitleService): the full title public configuration\n  bundle, title-wide public custom data, server time, and the standalone\n  currency/item definitions endpoints. Also documents the config-section\n  registry (`client.data.config.getSection<T>(\"Section\")`) that every other\n  module's skill depends on. Use this whenever the user is working in the\n  iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants app\n  boot/init sequences, server time sync, title-wide custom data, or otherwise\n  touches client.title, TitleService, TitlePublicConfigurationModel,\n  getTitlePublicConfiguration, or the title-level GetCurrencyDefinitions /\n  GetItemDefinitions calls — even if they don't name the module explicitly.\n---\n\n# Title system (iDosGames TS SDK)\n\nThe Title module is **not a gameplay feature** — it's title-level bootstrap\nconfig, config only, no per-player state. It's the place you'd fetch server\ntime, title-wide custom data, and a bundled snapshot of most other modules'\n_config_ (`Currency`, `Item`, `Store`, `Quest`, …) in one call. Most screens\ndon't call `client.title` directly for gameplay data; they call the owning\nmodule's own definitions method instead (e.g.\n`client.character.getCharacterDefinitions()`).\n\nDon't confuse this with the real login bootstrap: `client.auth.loginWithDeviceID()`\n(and every other login method) already calls `UserService.getClientStateExcept(...)`\ninternally, which fetches **both** the title config bundle **and** every\nmodule's per-player `User.*` state in one shot — see the user-profile skill.\n`client.title.getTitlePublicConfiguration()` only gets you the config half of\nthat (no `User.*` state), so you rarely need to call it yourself right after\nlogin; it's more useful for an explicit \"refresh config only\" action, or for\nthe couple of things no other module owns (server time, title custom data).\n\nThis skill is for **using** the production `TitleService`, not for porting or\nextending it.\n\n## The config-section registry (read this even if you're here for another module)\n\nEvery module's `Definitions` (config) getter — `getCharacterDefinitions()`,\n`getStoreDefinitions()` inside StoreService, etc. — follows the same pattern:\non a successful fetch, the owning service calls\n`client.data.config.patchSection(\"<SectionKey>\", result.data)`, storing the\nblob in a single `Map<string, unknown>` keyed by a plain string\n(`TitleConfig.sections`). Your UI code reads it back with a type parameter:\n\n```ts\nconst defs = client.data.config.getSection<CharacterDefinitions>(\"Character\");\n```\n\n`getSection<T>(key)` is just `sections.get(key) as T | undefined` — **the cast\nis not runtime-validated**, it only recovers the compile-time type; if a\nmodule hasn't fetched its definitions yet, you get `undefined`, not a runtime\nerror. Each module's own skill documents its section key and payload type —\nthis skill only documents the mechanism itself, not any section's contents.\n\nTwo things live outside that generic map, with their own dedicated getters:\n\n- `client.data.config.titlePublicConfiguration` — the full bundle fetched by\n  `getTitlePublicConfiguration()` here in Title (see caveat below on which\n  fields it actually contains).\n- `client.data.config.currencyDefinitions` / `client.data.config.itemDefinitions`\n  — dedicated getters (not `getSection`) that fall back from a standalone\n  fetch to the bundled value; see below.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst title = client.title; // the TitleService\n```\n\nEvery method requires an authenticated session — confirmed server-side, not\njust a client-side gate: the backend's shared `ClientRun.Execute` pipeline\nrequires a Bearer `ClientSessionTicket` and runs `ValidateUserSession` for\nevery Title action with no per-action exception, including `GetServerTime`.\nWithout a session, SDK methods return `{ ok: false, reason: \"unauthorized\" }`\nlocally before any network call — they do not throw.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: either `{ ok: true, data }`\nor `{ ok: false, reason, error }`. Always branch on `result.ok`. `reason` is\none of `\"client\"`, `\"unauthorized\"`, `\"throttled\"` (600 ms default client-side\nwindow), `\"connection\"` (transient, offer Retry), `\"validation\"`, or\n`\"server\"`.\n\n| Method                          | Purpose                                                                                      | `data` on success                               |\n| ------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------- |\n| `getTitlePublicConfiguration()` | Fetch the title config bundle (see field-subset caveat below).                               | `TitlePublicConfigurationModel`                 |\n| `getPublicTitleCustomData()`    | Fetch title-wide public custom data (arbitrary tenant data, not tied to any feature module). | `TitleCustomDataResponse` (`PublicData`)        |\n| `getCurrencyDefinitions()`      | Fetch just the currency catalog, standalone.                                                 | `CurrencyDefinitions`                           |\n| `getItemDefinitions()`          | Fetch just the item catalog, standalone.                                                     | `ItemDefinitions`                               |\n| `getServerTime()`               | Fetch authoritative server time.                                                             | `SuccessResponse` (`ServerTime`, `IsCompleted`) |\n\nNone of these take parameters — every one builds its request from\n`buildAuthedBaseRequest()` only (`TitleService.ts`'s private `baseRequest()`\nnever fills in any extra field). On success, each method mirrors its result\ninto the cache and emits an event — you don't apply anything by hand.\n\n### `getTitlePublicConfiguration()` returns a fixed field subset, not everything\n\nThe backend's `TitleRequest` supports `Fields`/`ExcludeFields` (and a second\naction, `GetTitlePublicConfigurationExcept`, for the exclude-list variant),\nbut the TS `TitleService.getTitlePublicConfiguration()` never populates\neither — it always calls the plain `GetTitlePublicConfiguration` action with\nan empty field list, which the backend then defaults to its own hard-coded\nsubset (`_defaultFields` in `Title.cs`). As of this writing that subset is:\n`ImageData`, `AssetBundle`, `Currency`, `Item`, `Premium`, `Reward`,\n`TimedEvent`, `CoopEvent`, `Leaderboard`, `Season`, `Collection`, `Craft`,\n`Lootbox`, `Store`, `DealOffer`, `Quest`, `Referral`, `Blockchain`,\n`Multiplayer`.\n\n**`UserCustomData`, `GameLoop`, and `Character` are deliberately left out** of\nthat default list (commented out in the backend source) — calling\n`getTitlePublicConfiguration()` will **not** populate\n`titlePublicConfiguration.Character` or `.GameLoop`, even though those fields\nexist on the `TitlePublicConfigurationModel` TypeScript type. For those three,\ncall the owning module's own `getXDefinitions()` instead (e.g.\n`client.character.getCharacterDefinitions()`), which patches its own section\nindependently of this bundle. `Match` is absent from the backend's field\nlist entirely — it is never returned by this endpoint under any field\nselection, standalone or bundled; use `client.match`'s own definitions call.\nThere is currently no TS-level way to request a different field subset or the\n\"except\" variant; if you need that, it would require extending\n`TitleService`/`TitleApi` to pass `Fields`/`ExcludeFields` through.\n\n## Currency/Item definitions: this module overlaps with currency-system and item-system\n\n`getCurrencyDefinitions()` and `getItemDefinitions()` live on `TitleService`,\nnot on `CurrencyService` or `ItemService` — as of this writing neither of\nthose modules exposes its own definitions-fetch method. If you need the\ncurrency or item catalog, this is currently the only place to get it\nstandalone (or via the full `getTitlePublicConfiguration()` bundle, which\nembeds both under `.Currency` / `.Item` — these two, unlike Character/GameLoop,\n_are_ in the default field subset). For everything else about currencies and\nitems (balances, granting, converting, upgrading item instances, equipping),\nsee the currency-system and item-system skills — this skill only covers\n_fetching the catalog_, not consuming it.\n\nCaching nuance: `getTitlePublicConfiguration()` stores the full bundle\nseparately from the standalone fetches. Reading order:\n\n- `client.data.config.currencyDefinitions` / `client.data.config.itemDefinitions`\n  return the standalone-fetched value if you've called\n  `getCurrencyDefinitions()` / `getItemDefinitions()`, falling back to the\n  value embedded in the full bundle (`titlePublicConfiguration.Currency` /\n  `.Item`) otherwise. A standalone fetch **overrides** the bundled value in\n  this getter, it doesn't merge with it.\n- The full bundle itself is read via\n  `client.data.config.titlePublicConfiguration` (not `getSection`).\n\n## Reading state and reacting to changes\n\n```ts\n// Full bundle (only present after getTitlePublicConfiguration()):\nconst cfg = client.data.config.titlePublicConfiguration;\ncfg?.Currency; // CurrencyDefinitions — in the default field subset\ncfg?.TitleCustomData; // { PublicData, PrivateData }\n// cfg?.Character / cfg?.GameLoop are NOT populated by this call — see above.\n\n// Title-wide custom data (only present after getPublicTitleCustomData()):\nconst customData =\n  client.data.config.getSection<TitleCustomDataResponse>(\"TitleCustomData\");\n\n// Standalone currency/item catalogs (prefer these getters over reading the bundle directly):\nconst currencyDefs = client.data.config.currencyDefinitions;\nconst itemDefs = client.data.config.itemDefinitions;\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `title:publicConfigurationReceived` → `TitlePublicConfigurationModel`\n- `title:publicCustomDataReceived` → `TitleCustomDataResponse`\n- `title:currencyDefinitionsReceived` → `CurrencyDefinitions`\n- `title:itemDefinitionsReceived` → `ItemDefinitions`\n- `title:serverTimeReceived` → `SuccessResponse`\n\nThere is no coarse `title:*Updated` / `user:anyUpdated`-style event for this\nmodule — Title carries no per-player state, so none of the `user:*Updated`\nevents fire from it either.\n\n```ts\nconst off = client.on(\"title:serverTimeReceived\", (r) => {\n  console.log(\"server time:\", r.ServerTime);\n});\n// later: off();\n```\n\n## Recipes\n\n### App boot: load config alongside login\n\n```ts\nawait client.auth.loginWithDeviceID();\n// Login already fetched Title + User state via getClientStateExcept internally.\n// Call this again only when you explicitly want a config-only refresh:\nconst res = await client.title.getTitlePublicConfiguration();\nif (!res.ok) return showError(res.error);\n\nconst cfg = client.data.config.titlePublicConfiguration;\n// cfg.Currency, cfg.Item, cfg.Store, cfg.Quest, ... are populated.\n// cfg.Character / cfg.GameLoop are NOT — fetch those from their own modules.\n```\n\nUse this when you want a fresh, config-only round-trip after boot (e.g. a\n\"refresh config\" debug action, or recovering from a stale cache) — not as\nyour primary boot path, since login already populated the same cache slot.\n\n### Fetch just the currency/item catalog\n\n```ts\nconst currencies = await client.title.getCurrencyDefinitions();\nconst items = await client.title.getItemDefinitions();\nif (!currencies.ok || !items.ok) return; // handle each independently\n\n// Prefer these getters — they resolve standalone-fetch-overrides-bundle for you:\nconst currencyDefs = client.data.config.currencyDefinitions;\nconst itemDefs = client.data.config.itemDefinitions;\n```\n\nUse this when you only need currencies/items and don't want the full bundle\n— e.g. a store screen that boots faster by skipping Quest/Reward/etc.\n\n### Title-wide custom data\n\n```ts\nconst res = await client.title.getPublicTitleCustomData();\nif (!res.ok) return showError(res.error);\nres.data.PublicData; // Record<string, TitlePublicData>, each { Data, SchemaVersion, UpdatedAt }\n```\n\nThis is free-form tenant-level data (announcements, feature flags, remote\nconfig-style values) — not tied to any single gameplay module. `Data` is a\nraw string; parse it yourself (e.g. JSON) per your title's convention.\n\n### Sync server time\n\n```ts\nconst res = await client.title.getServerTime();\nif (!res.ok) return showError(res.error);\nconst offsetMs = new Date(res.data.ServerTime).getTime() - Date.now();\n// Apply offsetMs when rendering countdowns driven by server-stamped\n// ExpiresAtUtc/StartUtc fields (timed boosts, timed events, offers, etc.),\n// so a skewed device clock doesn't show a wrong countdown.\n```\n\n`res.data.ServerTime` is the backend's UTC clock read at the moment the\nrequest was handled — it is not cached or memoized server-side, each call\nreflects \"now.\"\n\n### Reading any other module's config once it's loaded\n\n```ts\nimport type { CharacterDefinitions } from \"@idosgames/core\";\n\nawait client.character.getCharacterDefinitions(); // fetch + patchSection(\"Character\", ...)\nconst defs = client.data.config.getSection<CharacterDefinitions>(\"Character\");\n```\n\nThis is the pattern every other module's skill in this repo uses without\nre-explaining it: fetch via that module's own service method, then read back\nthrough `getSection<T>(\"<ThatModule'sSectionKey>\")`. The section key string is\ndocumented per-module (usually the module's own PascalCase name, e.g.\n`\"Character\"`, `\"Quest\"`, `\"Store\"`) — check that module's skill for the exact\nkey and payload shape.\n\n## Gotchas\n\n- **This is config, not gameplay state.** Nothing here is per-player\n  progression — there's no \"upgrade\" or \"grant\" method in this module.\n  Render from the cache; there's no user-state mirror to reconcile, and no\n  `user:*Updated` event fires from Title.\n- **`getTitlePublicConfiguration()` silently omits `Character`, `GameLoop`,\n  and `UserCustomData`**, and can never return `Match` at all — see the\n  dedicated section above. Don't assume the bundle is a complete snapshot of\n  every module; check the field list before relying on a section being\n  present in `titlePublicConfiguration`.\n- **Two ways to get currency/item definitions, one source of truth.** The\n  standalone `getCurrencyDefinitions()`/`getItemDefinitions()` calls and the\n  bundled `getTitlePublicConfiguration()` both hit the same backend catalog —\n  don't treat them as independently-versioned. Calling both is harmless but\n  redundant; the standalone fetch simply overrides the getter's fallback.\n- **`getPublicTitleCustomData()` is cached under its own section key**\n  (`\"TitleCustomData\"`), separate from `TitleCustomData` embedded in the full\n  bundle — read it via `getSection`, not off `titlePublicConfiguration`, to\n  get the freshest standalone fetch.\n- **Config can be up to ~60 seconds stale.** The backend serves this bundle\n  from a process-wide in-memory cache, invalidated by a Redis version counter\n  that's itself re-checked at most once every 60 seconds per title. A config\n  change made in a title's admin panel isn't guaranteed to be visible to a\n  running client instantly — don't build a \"config just changed, refresh now\"\n  UX that assumes sub-second propagation.\n- **`getServerTime()` isn't a lightweight unauthenticated ping.** It goes\n  through the same full pipeline as every other v2 endpoint: Bearer session\n  validation and the title-active/BuildKey check both run before the handler\n  executes. A banned/inactive title or an expired session rejects it exactly\n  like any other Title call — it will not quietly succeed as a health check\n  when the title itself is down.\n- **No batch methods, no write methods.** Every method here is a read; there\n  is nothing to guard against double-submit charges for.\n",
+  "description": "Fetch the iDosGames TypeScript SDK (@idosgames/core) title-level bootstrap config via client.title (TitleService): the full title public configuration bundle, server time, and the standalone currency/item definitions endpoints. Also documents the config-section registry (`client.data.config.getSection<T>(\"Section\")`) that every other module's skill depends on. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants app boot/init sequences or server time sync, or otherwise touches client.title, TitleService, TitlePublicConfigurationModel, getTitlePublicConfiguration, or the title-level GetCurrencyDefinitions / GetItemDefinitions calls — even if they don't name the module explicitly.",
+  "content": "---\nname: title-system\ndescription: >-\n  Fetch the iDosGames TypeScript SDK (@idosgames/core) title-level bootstrap\n  config via client.title (TitleService): the full title public configuration\n  bundle, server time, and the standalone currency/item definitions endpoints.\n  Also documents the config-section registry (`client.data.config.getSection<T>(\"Section\")`) that every other\n  module's skill depends on. Use this whenever the user is working in the\n  iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants app\n  boot/init sequences or server time sync, or otherwise touches client.title,\n  TitleService, TitlePublicConfigurationModel, getTitlePublicConfiguration, or the title-level GetCurrencyDefinitions /\n  GetItemDefinitions calls — even if they don't name the module explicitly.\n---\n\n# Title system (iDosGames TS SDK)\n\nThe Title module is **not a gameplay feature** — it's title-level bootstrap\nconfig, config only, no per-player state. It's the place you'd fetch server\ntime and a bundled snapshot of most other modules'\n_config_ (`Currency`, `Item`, `Store`, `Quest`, …) in one call. Most screens\ndon't call `client.title` directly for gameplay data; they call the owning\nmodule's own definitions method instead (e.g.\n`client.character.getCharacterDefinitions()`).\n\nDon't confuse this with the real login bootstrap: `client.auth.loginWithDeviceID()`\n(and every other login method) already calls `UserService.getClientStateExcept(...)`\ninternally, which fetches **both** the title config bundle **and** every\nmodule's per-player `User.*` state in one shot — see the user-profile skill.\n`client.title.getTitlePublicConfiguration()` only gets you the config half of\nthat (no `User.*` state), so you rarely need to call it yourself right after\nlogin; it's more useful for an explicit \"refresh config only\" action, or for\nthe couple of things no other module owns (server time, the config bundle).\n\nThis skill is for **using** the production `TitleService`, not for porting or\nextending it.\n\n## The config-section registry (read this even if you're here for another module)\n\nEvery module's `Definitions` (config) getter — `getCharacterDefinitions()`,\n`getStoreDefinitions()` inside StoreService, etc. — follows the same pattern:\non a successful fetch, the owning service calls\n`client.data.config.patchSection(\"<SectionKey>\", result.data)`, storing the\nblob in a single `Map<string, unknown>` keyed by a plain string\n(`TitleConfig.sections`). Your UI code reads it back with a type parameter:\n\n```ts\nconst defs = client.data.config.getSection<CharacterDefinitions>(\"Character\");\n```\n\n`getSection<T>(key)` is just `sections.get(key) as T | undefined` — **the cast\nis not runtime-validated**, it only recovers the compile-time type; if a\nmodule hasn't fetched its definitions yet, you get `undefined`, not a runtime\nerror. Each module's own skill documents its section key and payload type —\nthis skill only documents the mechanism itself, not any section's contents.\n\nTwo things live outside that generic map, with their own dedicated getters:\n\n- `client.data.config.titlePublicConfiguration` — the full bundle fetched by\n  `getTitlePublicConfiguration()` here in Title (see caveat below on which\n  fields it actually contains).\n- `client.data.config.currencyDefinitions` / `client.data.config.itemDefinitions`\n  — dedicated getters (not `getSection`) that fall back from a standalone\n  fetch to the bundled value; see below.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst title = client.title; // the TitleService\n```\n\nEvery method requires an authenticated session — confirmed server-side, not\njust a client-side gate: the backend's shared `ClientRun.Execute` pipeline\nrequires a Bearer `ClientSessionTicket` and runs `ValidateUserSession` for\nevery Title action with no per-action exception, including `GetServerTime`.\nWithout a session, SDK methods return `{ ok: false, reason: \"unauthorized\" }`\nlocally before any network call — they do not throw.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: either `{ ok: true, data }`\nor `{ ok: false, reason, error }`. Always branch on `result.ok`. `reason` is\none of `\"client\"`, `\"unauthorized\"`, `\"throttled\"` (600 ms default client-side\nwindow), `\"connection\"` (transient, offer Retry), `\"validation\"`, or\n`\"server\"`.\n\n| Method                          | Purpose                                                        | `data` on success                               |\n| ------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |\n| `getTitlePublicConfiguration()` | Fetch the title config bundle (see field-subset caveat below). | `TitlePublicConfigurationModel`                 |\n| `getCurrencyDefinitions()`      | Fetch just the currency catalog, standalone.                   | `CurrencyDefinitions`                           |\n| `getItemDefinitions()`          | Fetch just the item catalog, standalone.                       | `ItemDefinitions`                               |\n| `getServerTime()`               | Fetch authoritative server time.                               | `SuccessResponse` (`ServerTime`, `IsCompleted`) |\n\nNone of these take parameters — every one builds its request from\n`buildAuthedBaseRequest()` only (`TitleService.ts`'s private `baseRequest()`\nnever fills in any extra field). On success, each method mirrors its result\ninto the cache and emits an event — you don't apply anything by hand.\n\n### `getTitlePublicConfiguration()` returns a fixed field subset, not everything\n\nThe backend's `TitleRequest` supports `Fields`/`ExcludeFields` (and a second\naction, `GetTitlePublicConfigurationExcept`, for the exclude-list variant),\nbut the TS `TitleService.getTitlePublicConfiguration()` never populates\neither — it always calls the plain `GetTitlePublicConfiguration` action with\nan empty field list, which the backend then defaults to its own hard-coded\nsubset (`_defaultFields` in `Title.cs`). As of this writing that subset is:\n`ImageData`, `AssetBundle`, `Currency`, `Item`, `Premium`, `Reward`,\n`TimedEvent`, `CoopEvent`, `Leaderboard`, `Season`, `Collection`, `Craft`,\n`Lootbox`, `Store`, `DealOffer`, `Quest`, `Referral`, `Blockchain`,\n`Multiplayer`.\n\n**`UserCustomData`, `GameLoop`, and `Character` are deliberately left out** of\nthat default list (commented out in the backend source) — calling\n`getTitlePublicConfiguration()` will **not** populate\n`titlePublicConfiguration.Character` or `.GameLoop`, even though those fields\nexist on the `TitlePublicConfigurationModel` TypeScript type. For those three,\ncall the owning module's own `getXDefinitions()` instead (e.g.\n`client.character.getCharacterDefinitions()`), which patches its own section\nindependently of this bundle. `Match` is absent from the backend's field\nlist entirely — it is never returned by this endpoint under any field\nselection, standalone or bundled; use `client.match`'s own definitions call.\nThere is currently no TS-level way to request a different field subset or the\n\"except\" variant; if you need that, it would require extending\n`TitleService`/`TitleApi` to pass `Fields`/`ExcludeFields` through.\n\n## Currency/Item definitions: this module overlaps with currency-system and item-system\n\n`getCurrencyDefinitions()` and `getItemDefinitions()` live on `TitleService`,\nnot on `CurrencyService` or `ItemService` — as of this writing neither of\nthose modules exposes its own definitions-fetch method. If you need the\ncurrency or item catalog, this is currently the only place to get it\nstandalone (or via the full `getTitlePublicConfiguration()` bundle, which\nembeds both under `.Currency` / `.Item` — these two, unlike Character/GameLoop,\n_are_ in the default field subset). For everything else about currencies and\nitems (balances, granting, converting, upgrading item instances, equipping),\nsee the currency-system and item-system skills — this skill only covers\n_fetching the catalog_, not consuming it.\n\nCaching nuance: `getTitlePublicConfiguration()` stores the full bundle\nseparately from the standalone fetches. Reading order:\n\n- `client.data.config.currencyDefinitions` / `client.data.config.itemDefinitions`\n  return the standalone-fetched value if you've called\n  `getCurrencyDefinitions()` / `getItemDefinitions()`, falling back to the\n  value embedded in the full bundle (`titlePublicConfiguration.Currency` /\n  `.Item`) otherwise. A standalone fetch **overrides** the bundled value in\n  this getter, it doesn't merge with it.\n- The full bundle itself is read via\n  `client.data.config.titlePublicConfiguration` (not `getSection`).\n\n## Reading state and reacting to changes\n\n```ts\n// Full bundle (only present after getTitlePublicConfiguration()):\nconst cfg = client.data.config.titlePublicConfiguration;\ncfg?.Currency; // CurrencyDefinitions — in the default field subset\ncfg?.TitleCustomData; // TitleCustomDataDefinitions — the title-data key SCHEMA, not its values\n// cfg?.Character / cfg?.GameLoop are NOT populated by this call — see above.\n\n// Standalone currency/item catalogs (prefer these getters over reading the bundle directly):\nconst currencyDefs = client.data.config.currencyDefinitions;\nconst itemDefs = client.data.config.itemDefinitions;\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `title:publicConfigurationReceived` → `TitlePublicConfigurationModel`\n- `title:currencyDefinitionsReceived` → `CurrencyDefinitions`\n- `title:itemDefinitionsReceived` → `ItemDefinitions`\n- `title:serverTimeReceived` → `SuccessResponse`\n\nThere is no coarse `title:*Updated` / `user:anyUpdated`-style event for this\nmodule — Title carries no per-player state, so none of the `user:*Updated`\nevents fire from it either.\n\n```ts\nconst off = client.on(\"title:serverTimeReceived\", (r) => {\n  console.log(\"server time:\", r.ServerTime);\n});\n// later: off();\n```\n\n## Recipes\n\n### App boot: load config alongside login\n\n```ts\nawait client.auth.loginWithDeviceID();\n// Login already fetched Title + User state via getClientStateExcept internally.\n// Call this again only when you explicitly want a config-only refresh:\nconst res = await client.title.getTitlePublicConfiguration();\nif (!res.ok) return showError(res.error);\n\nconst cfg = client.data.config.titlePublicConfiguration;\n// cfg.Currency, cfg.Item, cfg.Store, cfg.Quest, ... are populated.\n// cfg.Character / cfg.GameLoop are NOT — fetch those from their own modules.\n```\n\nUse this when you want a fresh, config-only round-trip after boot (e.g. a\n\"refresh config\" debug action, or recovering from a stale cache) — not as\nyour primary boot path, since login already populated the same cache slot.\n\n### Fetch just the currency/item catalog\n\n```ts\nconst currencies = await client.title.getCurrencyDefinitions();\nconst items = await client.title.getItemDefinitions();\nif (!currencies.ok || !items.ok) return; // handle each independently\n\n// Prefer these getters — they resolve standalone-fetch-overrides-bundle for you:\nconst currencyDefs = client.data.config.currencyDefinitions;\nconst itemDefs = client.data.config.itemDefinitions;\n```\n\nUse this when you only need currencies/items and don't want the full bundle\n— e.g. a store screen that boots faster by skipping Quest/Reward/etc.\n\n### Title-wide custom data lives in its own module\n\nValues shared by all players (announcements, feature flags, event state, global\ncounters) are **not** part of this bundle: `cfg.TitleCustomData` is only the key\nschema. Read the values with `client.titleCustomData` — see **title-custom-data**.\n\n### Sync server time\n\n```ts\nconst res = await client.title.getServerTime();\nif (!res.ok) return showError(res.error);\nconst offsetMs = new Date(res.data.ServerTime).getTime() - Date.now();\n// Apply offsetMs when rendering countdowns driven by server-stamped\n// ExpiresAtUtc/StartUtc fields (timed boosts, timed events, offers, etc.),\n// so a skewed device clock doesn't show a wrong countdown.\n```\n\n`res.data.ServerTime` is the backend's UTC clock read at the moment the\nrequest was handled — it is not cached or memoized server-side, each call\nreflects \"now.\"\n\n### Reading any other module's config once it's loaded\n\n```ts\nimport type { CharacterDefinitions } from \"@idosgames/core\";\n\nawait client.character.getCharacterDefinitions(); // fetch + patchSection(\"Character\", ...)\nconst defs = client.data.config.getSection<CharacterDefinitions>(\"Character\");\n```\n\nThis is the pattern every other module's skill in this repo uses without\nre-explaining it: fetch via that module's own service method, then read back\nthrough `getSection<T>(\"<ThatModule'sSectionKey>\")`. The section key string is\ndocumented per-module (usually the module's own PascalCase name, e.g.\n`\"Character\"`, `\"Quest\"`, `\"Store\"`) — check that module's skill for the exact\nkey and payload shape.\n\n## Gotchas\n\n- **This is config, not gameplay state.** Nothing here is per-player\n  progression — there's no \"upgrade\" or \"grant\" method in this module.\n  Render from the cache; there's no user-state mirror to reconcile, and no\n  `user:*Updated` event fires from Title.\n- **`getTitlePublicConfiguration()` silently omits `Character`, `GameLoop`,\n  and `UserCustomData`**, and can never return `Match` at all — see the\n  dedicated section above. Don't assume the bundle is a complete snapshot of\n  every module; check the field list before relying on a section being\n  present in `titlePublicConfiguration`.\n- **Two ways to get currency/item definitions, one source of truth.** The\n  standalone `getCurrencyDefinitions()`/`getItemDefinitions()` calls and the\n  bundled `getTitlePublicConfiguration()` both hit the same backend catalog —\n  don't treat them as independently-versioned. Calling both is harmless but\n  redundant; the standalone fetch simply overrides the getter's fallback.\n- **Config can be up to ~60 seconds stale.** The backend serves this bundle\n  from a process-wide in-memory cache, invalidated by a Redis version counter\n  that's itself re-checked at most once every 60 seconds per title. A config\n  change made in a title's admin panel isn't guaranteed to be visible to a\n  running client instantly — don't build a \"config just changed, refresh now\"\n  UX that assumes sub-second propagation.\n- **`getServerTime()` isn't a lightweight unauthenticated ping.** It goes\n  through the same full pipeline as every other v2 endpoint: Bearer session\n  validation and the title-active/BuildKey check both run before the handler\n  executes. A banned/inactive title or an expired session rejects it exactly\n  like any other Title call — it will not quietly succeed as a health check\n  when the title itself is down.\n- **No batch methods, no write methods.** Every method here is a read; there\n  is nothing to guard against double-submit charges for.\n",
   "references": []
 }