@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/docs/cli-simulation-testing.md

@@ -0,0 +1,222 @@
+# Drive a game from the CLI
+
+Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON. This is how you check engine behaviour quickly, and how an agent or a script plays a game without a browser.
+
+**Keywords:** cli testing, drive game, tick, patch, view, configure, init, automated testing, json output, simulate decisions
+
+Every flag used here is listed in the [CLI reference](./cli-reference.md#session-commands).
+
+## Prerequisites
+
+- A package with an engine. The commands below use the starter game `new package` scaffolds; for your own game, swap in its settings and capability paths
+- `seriousgaming.sdk.json` in your working directory
+- `jq`, if you want to pick values out of the output
+
+## Steps
+
+### 1. Configure the game (optional)
+
+Skip this step and the game plays with its settings' defaults (or its scenario's values). To try other values, set them keyed by settings identifier, the directory name under `settings/`:
+
+```bash
+pnpm run sdk configure '{"menu":{"Capacity":80},"engine":{"Variation":0}}'
+
+# Or from a file
+pnpm run sdk configure -f config.json
+```
+
+The values are validated against each settings resource's `settingsSchema` and kept in `.seriousgaming-sdk/configuration.json`, so every later session starts from them. A session that is already running is started again on them, at tick 0, keeping its team count, scenario and locale.
+
+### 2. Start a session (optional)
+
+```bash
+pnpm run sdk init
+```
+
+This prints the game at tick 0:
+
+```json
+{
+    "gameId": "com.example.lemonade.game",
+    "completedTicks": 0,
+    "maxTicks": 10,
+    "complete": false,
+    "context": {
+        "plan": { "Make": { "lemonade": 28, "icedtea": 15, "cookies": 10 } },
+        "weather": {
+            "Today": "cloudy",
+            "Expected": { "lemonade": 55, "icedtea": 30, "cookies": 20 }
+        },
+        "results": {
+            "Day": 0,
+            "Weather": "cloudy",
+            "Lines": {},
+            "Takings": 0,
+            "Spent": 0,
+            "Profit": 0,
+            "Purse": 0
+        },
+        "roles": { "LooksAfter": {} }
+    },
+    "sharedContext": { "briefing": { "Message": "" } }
+}
+```
+
+`gameId` is your package identifier with `.game` appended. The weather, and so the forecast in `Expected`, comes from the session's seed, so yours may differ. `sharedContext` appears because the starter game has a shared capability, `briefing`.
+
+You can skip `init` too: any session command starts a session when none is running. Reach for `init` when you want to start over with a different team count, scenario, or locale (`pnpm run sdk init --teams 3`).
+
+A session started this way runs in a background dev server, and the command says so on stderr. The session lives in that server's memory, so it carries across commands until the server stops. See [Where the session lives](./cli-reference.md#where-the-session-lives).
+
+### 3. Advance a tick
+
+```bash
+pnpm run sdk tick
+```
+
+With no decisions, the engine runs on the current context: the game advances as if nobody touched a control.
+
+### 4. Make decisions, then advance
+
+A participant makes a decision by writing to a capability through a UI. From the CLI, `--patch` does the same thing: it applies an RFC 6902 JSON Patch to the context and then runs the engine.
+
+```bash
+pnpm run sdk tick --patch '[{"op":"replace","path":"/plan/Make/lemonade","value":40}]'
+```
+
+Several decisions go in one patch, applied in order:
+
+```bash
+pnpm run sdk tick --patch '[
+  {"op":"replace","path":"/plan/Make/icedtea","value":20},
+  {"op":"replace","path":"/plan/Make/cookies","value":15}
+]'
+```
+
+Paths start at the capability identifier, then the variable, then any key inside it (`/plan/Make/lemonade`). The CLI reference covers [every operation and path rule](./cli-reference.md#partial-update-with-json-patch).
+
+### 5. Change the context without ticking
+
+To set state up, or correct it, without running the engine, use `patch`:
+
+```bash
+pnpm run sdk patch '[{"op":"replace","path":"/plan/Make/cookies","value":0}]'
+```
+
+The game stays on the current tick, and the next tick runs from the patched context.
+
+### 6. Read the state
+
+```bash
+pnpm run sdk view
+```
+
+To parse the output, add `--silent` to `pnpm run` so pnpm's own banner stays out of it (see [Parsing JSON output](./cli-reference.md#parsing-json-through-pnpm)):
+
+```bash
+pnpm run --silent sdk view | jq '.context'
+pnpm run --silent sdk view | jq '.maxTicks'
+```
+
+`view --full` prints the whole state projection: every team's context and roster, the shared store, the resolved settings, and the timer. It is what the console renders from, so what you read is what the browser shows.
+
+```bash
+pnpm run --silent sdk view --full | jq '.teams[] | {team: .index, completedTicks, context}'
+```
+
+### 7. Start again
+
+```bash
+pnpm run sdk reset          # back to tick 0, keeping the scenario and roster
+pnpm run sdk init           # rebuild from the package, re-resolving everything
+```
+
+## Scripting a run
+
+Each command prints JSON, so a script can drive a game and check the result. Always use `pnpm run --silent` so `JSON.parse` sees JSON alone.
+
+Run several ticks and check the end state:
+
+```typescript
+// 1. Initialize game (--silent strips the pnpm banner so JSON.parse succeeds)
+const initResult = await exec('pnpm run --silent sdk init');
+const initialState = JSON.parse(initResult.stdout);
+
+// Verify initial context
+assert(initialState.context.plan.Make.lemonade === 28);
+assert(initialState.completedTicks === 0);
+
+// 2. Execute multiple ticks
+for (let i = 0; i < 5; i++) {
+    const tickResult = await exec('pnpm run --silent sdk tick');
+    const state = JSON.parse(tickResult.stdout);
+
+    // Verify state updates are as expected
+    console.log(`Day ${state.completedTicks}: Profit = ${state.context.results.Profit}`);
+}
+
+// 3. View final state
+const viewResult = await exec('pnpm run --silent sdk view');
+const finalState = JSON.parse(viewResult.stdout);
+
+// Verify end conditions
+assert(finalState.completedTicks === 5);
+assert(finalState.context.results.Day === 5);
+```
+
+Try the engine against several sets of decisions:
+
+```typescript
+// Test how the engine reacts to different input values
+const testCases = [{ lemonade: 20 }, { lemonade: 40 }, { lemonade: 60 }];
+
+for (const testCase of testCases) {
+    // Reset game
+    await exec('pnpm run --silent sdk init');
+
+    // Create patch to set input values
+    const patch = [{ op: 'replace', path: '/plan/Make/lemonade', value: testCase.lemonade }];
+
+    // Tick with modified context
+    const tickResult = await exec(`pnpm run --silent sdk tick --patch '${JSON.stringify(patch)}'`);
+    const state = JSON.parse(tickResult.stdout);
+
+    // Verify the engine played the day on the patched plan
+    const line = state.context.results.Lines.lemonade;
+    assert(line.Made === testCase.lemonade);
+    assert(line.Sold + line.PouredAway === line.Made);
+
+    console.log(`Test case (lemonade=${testCase.lemonade}): passed`);
+}
+```
+
+For a multi-tick run in CI, prefer [`createTestSession`](./guides/engine-testing.md), which plays a whole run in one process with no server and no port. `--no-server` is no substitute: each command is then a fresh session, so two ticks both report `completedTicks: 1`.
+
+For a game with several teams, pass `--team N` to `tick`, `patch`, and `view`; the [multi-team games guide](./guides/multi-team-games.md) explains how shared-state and independent games advance. For letting an agent play while you watch the browser, see [Working alongside an agent](./cli-and-dev-server.md#working-alongside-an-agent).
+
+## Verify
+
+- `pnpm run --silent sdk view | jq '.completedTicks'` reports the tick you expect after each `tick`
+- A value you patched appears in the `context` that `view` prints
+- `pnpm run sdk dev status` shows the background server the commands are talking to
+
+## Troubleshooting
+
+| Problem                                             | Solution                                                                                                                                                                              |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Error: The game is complete`                       | The last tick has run. Raise `maxTicks` in `seriousgaming.sdk.json`, or start again with `pnpm run sdk reset` or `pnpm run sdk init`                                                  |
+| `Team is already complete`                          | A `--team N` tick on a team that has finished. Tick another team, or reset                                                                                                            |
+| `Tick limit reached`                                | The game has played its `maxTicks`. Raise `maxTicks`, or start again with `pnpm run sdk reset`                                                                                        |
+| `JSON.parse` fails or `jq` errors on the first line | Use `pnpm run --silent` so the pnpm banner stays out of stdout                                                                                                                        |
+| `Path does not exist`                               | The patch path does not match the context. Check it with `pnpm run --silent sdk view \| jq '.context'`                                                                                |
+| `--team` errors                                     | See [Team addressing errors](./cli-reference.md#team-addressing-errors)                                                                                                               |
+| The engine cannot be found                          | Build the game with `pnpm run build`                                                                                                                                                  |
+| The context does not change between ticks           | The engine must return a new object built with spreads (`{ capabilities: { ...context, capability: { ...context.capability, Variable: newValue } } }`), not mutate `context` in place |
+| The session is in a state you cannot explain        | Stop the server with `pnpm run sdk dev stop`, then run `pnpm run sdk tick`. The session is the process, so nothing carries the problem forward                                        |
+
+## Related
+
+- [CLI reference](./cli-reference.md): every command and flag
+- [The CLI and the dev server](./cli-and-dev-server.md): how commands reach the session
+- [Engine testing](./guides/engine-testing.md): `createTestSession` for automated playthroughs
+- [Test with the engine](./recipes/test-with-engine.md)

package/dist/docs/concepts/index.md

@@ -0,0 +1,46 @@
+# Core concepts
+
+The model behind the SDK on one page. Each resource kind has one guide that explains it in full and is its reference; this page says how they fit together. For the words these docs use, each with one meaning, see the [terminology](./terminology.md).
+
+## A package is a game
+
+A game is a package: a directory with a `seriousgaming.sdk.json` (the game's identifier, locales, ticks, teams and waiting room) and one directory per resource. The CLI finds resources by scanning the directories beside the manifest, so there is no list to keep in step.
+
+A game holds exactly one of some kinds, each in a fixed **slot** named for it, and any number of the others, each under a plural directory and named by its directory:
+
+| Kind                                                                            | Where                        | What it is                                                            |
+| ------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------- |
+| [Capability](../guides/capabilities.md)                                         | `capabilities/<name>/`       | A named slice of state, with a schema and no logic                    |
+| [Settings](../guides/settings.md)                                               | `settings/<name>/`           | Read-only parameters, each with a default, fixed when play starts     |
+| [Engine](../guides/engine.md)                                                   | `engine/`                    | The tick logic: `Init` and `Run`                                      |
+| [Tick controller](../guides/tick-controller.md)                                 | `tick_controller/`           | Automatic tick timing, and when the game is over                      |
+| [Hook](../guides/hooks.md)                                                      | `hooks/<name>/`              | Logic run on a lifecycle signal, such as a participant joining        |
+| [Validator](../guides/validators.md)                                            | `validators/<name>/`         | A read-only check that can reject what a player surface submits       |
+| [Endpoint](../guides/endpoints.md)                                              | `endpoints/<name>/`          | A server-side handler a surface or an agent calls by identifier       |
+| [Game UI](../guides/ui.md)                                                      | `ui/`                        | What each participant plays                                           |
+| [Waiting room UI](../guides/waiting-room.md)                                    | `waiting_room/`              | What participants see while the session is held                       |
+| [Session UI](../guides/session.md)                                              | `session/`                   | The facilitator's whole-session screen                                |
+| [Setup](../guides/setup.md) and [scenario editor](../guides/scenario-editor.md) | `setup/`, `scenario_editor/` | The screens that edit settings: per session, and as lasting scenarios |
+| [Presentation](../guides/presentation.md)                                       | `presentation/`              | The facilitator's slide deck                                          |
+| [Facilitator guide](../guides/guide.md)                                         | `guide/`                     | Markdown chapters for whoever runs the session                        |
+| [Scenario](../guides/scenarios.md)                                              | `scenarios/<name>/`          | A variant of the game: settings overrides and static assets           |
+
+## How a session runs
+
+1. A facilitator creates a session, choosing a scenario and, if the game has a setup screen, filling it in. The session's settings are resolved and fixed
+2. The engine's `Init` runs once per team, and the teams' surfaces mount
+3. In each round, participants make decisions: each is a write to their team's state, checked by the game's validators
+4. A tick, requested by hand or by the tick controller, runs the engine's `Run` on what the teams submitted and records the round as a snapshot
+5. When the last tick has run, or the tick controller says so, the game is complete
+
+The [CLI and the dev server](../cli-and-dev-server.md) run the same session on your machine.
+
+## Key ideas
+
+1. **Scoped context**: state is organised under capability identifiers, so names cannot collide (`context.sales.Revenue`)
+2. **Immutable updates**: logic returns what it writes under `capabilities`, built with spreads, and removes paths with `deletes`. It never changes the context it was given
+3. **Declared data flow**: every resource declares the capabilities it reads and writes, the settings it reads, and the services it uses, so the SDK can generate exact types and deliver exactly that, and nothing else
+4. **One engine, composed from functions**: a game has one engine, and a simulation with several steps calls them as plain functions from its `Run`, in the order it wants them
+5. **Logic runs anywhere**: logic uses the JavaScript language alone, with no Node.js or browser APIs, and reaches the outside world only through the callbacks it declares, so the same code runs in the dev server and in production
+
+Start with [Capabilities](../guides/capabilities.md) for the data model, then [Engine](../guides/engine.md).

package/dist/docs/concepts/terminology.md

@@ -0,0 +1,322 @@
+# Terminology
+
+Definitions of the terms used across the SDK, the CLI, the dev server, and these docs. Each concept has one preferred name. Where older pages use another, the entry lists it under **Also called**, so you can recognise it, and says which word to use.
+
+**Keywords:** glossary, terminology, definitions, vocabulary, naming conventions, synonyms, preferred terms
+
+## Sessions, teams, and participants
+
+### Session
+
+A single facilitated run of a game. A facilitator starts a session, and it groups one or more **teams**. Every team plays the same game with the same resolved settings, and each has its own context; shared capabilities are the one thing teams hold in common.
+
+In the dev server, the session lives in the server's memory. It starts when the server does, whether you ran `sdk dev` or a session command started one in the background, and it ends when the server stops. `sdk init` puts it back at tick 0.
+
+### Team
+
+The unit of game state. Every participant on a team sees the same context and makes decisions against the same data. A team has a stable `teamId` (`team-1`, `team-2`, and so on) and a stable zero-based index that never changes for the life of the session.
+
+A game that declares `teams.max: 1` and locks it with `gameSettingsConstraints` is single-team. Any other game can run with several teams: the facilitator chooses how many, within `teams.min` and `teams.max`. How teams relate is the game's **interaction mode**.
+
+### Participant
+
+A browser session connected to a team. Each participant has:
+
+| Field       | Meaning                                                 |
+| ----------- | ------------------------------------------------------- |
+| `id`        | Stable within a session; assigned on first visit        |
+| `name`      | Display name (defaults to 'Participant N')              |
+| `index`     | Zero-based join order within the team                   |
+| `connected` | Whether the participant has a live connection right now |
+| `teamId`    | The team this participant belongs to (e.g. `"team-1"`)  |
+
+A participant is **not** the same as a person. Someone who opens two browser tabs against the same team is two participants. Someone who clears their cookies and comes back is a new participant, and the original stays as disconnected.
+
+A game UI reads its own participant with `useUserInterfaceParticipant()` and the team roster with `useUserInterfaceParticipants()`. The session UI reads every team's participants with `useSessionUserInterfaceParticipants()`.
+
+**Also called** 'player' in older pages. Use participant. A game's own copy can call them whatever suits it.
+
+### Facilitator
+
+The person running the session, from the session UI. 'Facilitator' is a human role, not an SDK type: there is no `facilitator` identifier, and anyone with the session UI's address can use it.
+
+### Author
+
+The person creating a scenario, in the scenario editor. On the platform an author may be an end user rather than a facilitator, so an endpoint the editor calls sees `caller.role` as `'author'`, never `'facilitator'`.
+
+### Observer
+
+A facilitator watching one team's game UI without joining as a participant, to see how a team is playing, to help with a problem, or to run a debrief. An observer is a behavioural role, not a record: no participant entry, no presence, and absent from the roster. They see the same game UI a participant sees. A UI tells the two apart with `useUserInterfaceViewerRole()`, and while observing, `useUserInterfaceParticipant()` returns `null`. See [Adapt a UI for observers](../recipes/adapt-ui-for-observers.md).
+
+### Viewer role
+
+Which viewer a game UI is rendered for: `participant` or `observer`. Read it with `useUserInterfaceViewerRole()`.
+
+### Interaction mode
+
+How teams relate within a session, declared as `teams.mode` in `seriousgaming.sdk.json` and fixed by the game:
+
+- **`independent`**: teams are isolated from each other, and each team ticks on its own schedule. A shared capability exists, but only the facilitator writes it. **A game that omits `teams.mode` is independent**
+- **`shared-state`**: teams interact through shared capabilities that an aggregate engine computes from every team's state, so all teams tick together
+
+The facilitator cannot change the mode when creating a session. See [Multi-team games](../guides/multi-team-games.md).
+
+### Walkthrough
+
+A disposable second run of the same game, owned by a session, used to demonstrate the game before it is played for real. It has one team, starts at tick 0, resolves its settings exactly as the session does, and nothing it does reaches the session. It never shows the waiting room, and it is left out of every report.
+
+### Run kind
+
+Which run a call belongs to: `'session'` or `'walkthrough'`. Every call into logic carries it as `meta.runKind`, and every UI is told the same value. A game uses it to fill in what a solo demonstration lacks, such as rival teams on a leaderboard, and to keep outward side effects out of it. See [Adapt a game for walkthroughs](../recipes/adapt-a-game-for-walkthroughs.md).
+
+## Game structure
+
+### Game
+
+The playable simulation a package is: its engine, capabilities, and UIs, plus how long it runs and how it is configured. Authored as `seriousgaming.sdk.json` itself, one flat object. A game is a blueprint, describing what to run rather than the state of any run.
+
+### Resource
+
+One of the things a game is built from: an engine, a capability, a settings resource, a UI (the game UI, the waiting room UI, the session UI, setup, the scenario editor, or the presentation), a hook, a validator, an endpoint, a scenario, a tick controller, or a facilitator guide. Each is a directory holding a `*.sdk.json` bundle. A package declares whatever is on disk; there is no list to keep in step.
+
+### Slot
+
+The fixed directory for a resource a game holds exactly one of: `engine`, `ui` (the game UI), `session` (the session UI), `waiting_room`, `setup`, `scenario_editor`, `presentation` (the facilitator's slide deck), `tick_controller`, and `guide` (the facilitator guide). The slot is the resource's identifier, so it is never renamed. Resources a game can hold several of live under a plural directory instead, such as `capabilities/sales/`.
+
+### Identifier
+
+The name of a resource inside its package, taken from its directory: `sales`, or the slot, such as `session`. Lowercase letters, digits, and underscores, starting with a letter. A resource never authors its own identifier.
+
+A package is named globally, so it keeps a reverse-domain identifier (`com.example.retailgame`), and its game is that identifier with `.game` appended.
+
+### Scenario
+
+A named variant of a game: overrides of its settings, the built-in `game` settings such as `maxTicks` among them, and an `assets/` directory of static files. Scenarios carry no logic. A game's scenarios are whatever sits under `scenarios/`; the facilitator picks one when the session starts (`--scenario` in the dev server), and it stays for the session. See [Scenarios](../guides/scenarios.md).
+
+### Capability
+
+A named slice of the game's state, with a `variablesSchema` (JSON Schema) describing what it holds. A capability is named by its directory (for example `sales`). Capabilities hold no logic.
+
+A capability's **scope** says who else sees it: `team` (the default: each team has its own), `team-readable` (each team writes its own copy, and in a shared-state game a UI that asks can read every team's), `shared` (one value for the whole session), or `private` (hidden from every UI).
+
+### Engine
+
+The game's tick logic, in the `engine` slot. It declares which capabilities it `reads` and `writes`, and exports `Init` (set up tick 0) and `Run` (play one tick). A simulation with several steps calls them as functions from `Run`, in the order it wants them. See [Engines](../guides/engine.md).
+
+### Hook
+
+Logic that runs when the runtime emits a lifecycle **signal**, outside the tick loop: `participantJoin` when a participant joins a team, and `participantMove` when one moves between teams. A hook subscribes to one signal, runs after the runtime has applied the change, and can write the capabilities it declares. It cannot prevent the change. See [Hooks](../guides/hooks.md).
+
+### Validator
+
+A read-only check on every mutation a UI submits, run before the mutation is applied. It sees the state before and after, and either accepts it or rejects it with a message; it never changes state and receives no callbacks. See [Validators](../guides/validators.md).
+
+### Endpoint
+
+A server-side handler, exported as `Handle`, that a UI calls by identifier with `callEndpoint`. It validates its request and response against schemas. An endpoint is **team**-scoped (the default: it acts on the calling team's context) or **session**-scoped (it acts on the session as a whole), and one that declares `writes` can change state. An endpoint is also how a UI reaches callbacks such as `generateText`, and one whose `visibility` is `external` can be called from outside the game, for example by a facilitator's AI agent or a platform API. See [Endpoints](../guides/endpoints.md).
+
+### Context
+
+The whole game state at a point in time, as an object keyed by capability identifier:
+
+```typescript
+{
+    "sales": { Revenue: 100, Units: 50 },
+    "costs": { FixedCosts: 200 }
+}
+```
+
+The engine reads it and returns an updated copy. UIs display it and write back to it with `setData`.
+
+### Scoped context
+
+Nesting each variable under its capability's identifier, so names cannot collide: `context.sales.Revenue` and `context.costs.Revenue` are different values.
+
+### Shared store
+
+The one copy of every `shared` capability in a session. Teams never own shared values: wherever code receives a team's context, the runtime composes a **view** of the team's own capabilities with the store. Only an aggregate engine (in shared-state mode), the facilitator, and session-scoped endpoints write it.
+
+### Board
+
+One team's state as a surface or an endpoint sees it: that team's context at a given tick. A write to a board changes that team only. A shared value is read through a board but lives in the shared store, so a team-addressed write cannot change it.
+
+### Aggregate engine
+
+An engine that runs once per tick across all teams rather than once per team, receiving every team's context. In shared-state mode it is the only engine that may write shared capabilities.
+
+## Ticks
+
+### Tick
+
+One iteration of the game loop: the engine runs on the board the teams submitted, and that board is recorded as a snapshot. Tick N closes round N. The facilitator or a UI triggers a tick by hand (the dev drawer's **Tick**, or `requestTick`), or a tick controller triggers it automatically.
+
+**Also called** 'day' or 'turn' in older pages. Use tick for the runtime concept. A game's own copy calls its ticks whatever fits the story: the starter game calls them days.
+
+### Round
+
+The play between two ticks. Round N opens when tick N - 1 commits (or when the game is initialised, for round 1) and is closed by tick N. Participants enter its decisions on the board their team holds live.
+
+### Engine tick
+
+`meta.tick` on a call into the engine or the tick controller: the tick being run. It is `0` during `Init`, `1` on the first `Run`, and `N` on the `Run` that closes round N. A game with `maxTicks: N` sees `N` on its last `Run`.
+
+### Completed ticks
+
+`completedTicks`, wherever it appears: on a surface (`useUserInterfaceData().completedTicks`), on each team in the session UI, in an endpoint's `session`, and in `sdk view --json`. It is the number of ticks that team has completed: `0` until the first tick commits, and `N - 1` during round N. It is always one behind the engine tick of the tick in progress, so the first `Run` of a session sees `meta.tick` of `1` while every surface still shows `0`. A surface names the round in play as `completedTicks + 1`.
+
+**Also called** the head tick in older pages. Use completed ticks.
+
+### Snapshot N
+
+The record of a closed round, read back with `getPastState` or `usePastState`: the state after tick N (after `Init`, for snapshot 0) together with the decisions made against it. It is captured when tick N + 1 is submitted and recorded once that tick has run, so a team that has completed N ticks holds snapshots 0 to N - 1. The board straight after `Init` is kept as the reset target, not as a snapshot.
+
+The first round of one team, in the order things happen (every later round repeats the last three rows with each number one higher):
+
+| Moment                                                 | Engine tick (`meta.tick`) | Surface `completedTicks`              | Snapshots held                                             |
+| ------------------------------------------------------ | ------------------------- | ------------------------------------- | ---------------------------------------------------------- |
+| `Init` runs                                            | `0`                       | (not yet mounted)                     | None                                                       |
+| Round 1 is played: participants enter decisions        | (no engine call)          | `0`                                   | None                                                       |
+| Tick 1 is requested; the board is captured, `Run` runs | `1`                       | `0`, with a round shown as processing | None yet                                                   |
+| Tick 1 commits; snapshot 0 is recorded                 | (no engine call)          | `1`                                   | Snapshot 0: the post-`Init` state with round 1's decisions |
+| Round 2 is played                                      | (no engine call)          | `1`                                   | Snapshot 0                                                 |
+
+### Decision
+
+A change a participant or the facilitator makes to the context between ticks. A UI makes one with `setData`. From the CLI, `tick --patch` applies a JSON Patch (RFC 6902) to the context and then runs the tick:
+
+```json
+[{ "op": "replace", "path": "/price/Price", "value": 25 }]
+```
+
+### Mutation
+
+Any state-changing request a UI sends: a context write (`setData`), a tick, an undo or a reset, a settings change, a roster change, or opening the waiting room. Every mutation returns a promise that resolves once the change has taken effect and rejects with a `MutationError` when it is refused. The error's `outcome.kind` says why: `validation-rejected` (a validator said no), `denied` (not permitted), `conflict` (lost a race with a tick, worth retrying), `superseded` (someone else already did it), `tick-failed`, or `error`. Await every mutation, so a refusal reaches the person who made it.
+
+### Tick controller
+
+Logic in the `tick_controller` slot that decides automatic tick timing and when the game is over. It exports `GetTickController`, which returns `{ enabled, intervalMs, complete }`: with `enabled` true, the runtime ticks every `intervalMs` milliseconds, and `complete: true` ends the game for good. See [Tick controllers](../guides/tick-controller.md).
+
+## User interfaces
+
+A game has up to six UIs, each in its own slot: the game UI, the waiting room UI, the session UI, setup, the scenario editor, and the presentation. Each is a React app the host mounts in a sandboxed iframe and talks to over a message channel. **Surface** is the umbrella word for any of them as mounted by the host; name a particular one by its UI name below.
+
+### Player surface
+
+The game UI or the waiting room UI: a surface rendered for one team, for a participant or an observer. Everything a player surface submits is put to the game's validators. Where these docs mean the `ui` slot alone, they say game UI.
+
+### Facilitator surface
+
+The session UI, setup, the scenario editor, or the presentation. A facilitator surface is never mounted on a participant's device, and what it submits is never put to validators.
+
+### Game UI
+
+What each participant sees and plays with during the game, in the `ui` slot. It reads and writes its team's context, can request ticks, calls endpoints, and uploads files. It also sees the team roster (`useUserInterfaceParticipants()`) and basic facts about every team (`useUserInterfaceTeams()`). The resource type is `ui`, and the SDK API keeps the `UserInterface` names (`UserInterfaceWrapper`, `useUserInterfaceData`). See [Building user interfaces](../guides/ui.md).
+
+**Also called** 'play surface', 'player UI', 'player user interface', 'participant interface' and 'game user interface' in older pages. Use game UI, or player surface when the waiting room UI is meant too.
+
+### Session UI
+
+The facilitator's whole-session screen, in the `session` slot. It reads and writes every team's context, controls ticks for one team or all of them, manages the roster, writes shared capabilities it declares, and reads the session's join links. Its game-flow callbacks take an optional `teamId` to target one team. In the dev server it is the page at `/`. See [Building session UIs](../guides/session.md).
+
+**Also called** 'session surface', 'facilitator UI' and 'session user interface' in older pages. Use session UI, or facilitator surface when setup, the scenario editor and the presentation are meant too.
+
+### Setup
+
+The short form a facilitator fills in at session creation, in the `setup` slot. It edits the settings it lists in `configures` and writes that session's overrides only, never context. A game with a setup slot opens at its **configuration step**, which closes when the facilitator presses **Play** (or the form sends `requestPlay`). See [Building a setup screen](../guides/setup.md).
+
+**Also called** 'quick config' and 'configuration UI' in older pages. Use setup.
+
+### Scenario editor
+
+The screen for authoring lasting scenarios, in the `scenario_editor` slot. It works at any time, with no session, and its output is a saved scenario; the host offers save-as-scenario from it and never from setup. It is optional: `customScenarios.supported` switches custom scenarios on, and an agent can author one from well-described settings schemas alone. See [Building a scenario editor](../guides/scenario-editor.md).
+
+**Also called** 'scenario builder' and 'configuration UI' in older pages. Use scenario editor.
+
+### Settings editor
+
+Setup and the scenario editor together: the two slots that edit settings rather than context. They share one wrapper, `SettingsEditorWrapper`, and one hook, `useSettingsEditor()`.
+
+### Waiting room UI
+
+The holding screen participants see in place of the game UI while the session's waiting room is open, in the `waiting_room` slot. The facilitator opens and closes the room for every team at once, and `waitingRoom.openOnStart` starts a session with it open. Without one, the host shows its own built-in panel. See [Building waiting room UIs](../guides/waiting-room.md).
+
+**Also called** 'waiting room user interface' in older pages. Use waiting room UI.
+
+### Presentation
+
+The facilitator's slide deck, in the `presentation` slot, shown on a projector during the session. It reads the capabilities it declares, never writes, and is built from `@seriousgaming/deck`. See [Building presentations](../guides/presentation.md).
+
+### Wrapper
+
+The SDK component around each kind of UI (`UserInterfaceWrapper`, which the waiting room UI uses too, `SessionUserInterfaceWrapper`, `SettingsEditorWrapper`, `PresentationWrapper`). A wrapper handles the handshake with the host, provides the data, and exposes the hooks the UI code calls.
+
+## Settings
+
+### Settings resource
+
+A named, read-only set of parameters: a price, a difficulty, a round length, an answer key. Authored at `settings/<name>/settings.sdk.json` as a `settingsSchema` (JSON Schema) whose every property declares a default. A package may hold any number. A resource (the engine, a UI, the session UI, the waiting room UI, the tick controller, a hook, a validator, or an endpoint) lists the ones it reads in its `settings`, exactly as `reads` names capabilities, and receives exactly those, keyed by identifier: `settings.engine.BaseDemand`. No logic or surface writes one, and settings are not part of the context. See [Settings](../guides/settings.md).
+
+**Not to be confused with** the global settings file, `~/.seriousgaming-sdk/config.json`, which holds your API keys (see [Global settings](../guides/global-settings.md)).
+
+### Resolved settings
+
+The values a session's settings take: every settings resource, resolved through the settings layers and keyed by settings identifier. A scenario's `settings`, `sdk configure`, and a settings editor's `configures` all use the same keys. Resolved settings are fixed when play starts: at session creation on the platform, and once the configuration step completes in the dev server.
+
+### Settings layers
+
+The three layers each settings resource is resolved from, each later one winning: the settings defaults, the active scenario's overrides, and the **session overrides**. There is no game-level layer. The full order, and how each layer is set, is in [Overriding settings](../guides/settings.md#overriding-settings).
+
+A running session resolved its settings when it started, so `sdk configure` restarts it on the new values itself, back at tick 0, keeping its team count, scenario, and locale. With no session running, the next one starts on them. Either way, there is no need to run `sdk init` afterwards.
+
+### Session overrides
+
+What was changed for this session and nothing else: the top settings layer. The game's setup screen writes it in production. In the dev server, `sdk configure` writes it to `.seriousgaming-sdk/configuration.json`. The layer is sparse: it holds only the keys somebody supplied, never a resolved copy of the layers beneath, so choosing another scenario still takes effect. See [Settings](../guides/settings.md#overriding-settings).
+
+## LLM integration
+
+### generateText
+
+A callback for generating text through the Serious Gaming platform's LLM API, available to the engine, hooks, tick controllers, and endpoints once the resource declares it in `uses`. A UI reaches it through an endpoint. It takes one of three tiers:
+
+| Tier       | Use case                  |
+| ---------- | ------------------------- |
+| `quick`    | Fast, cheap calls         |
+| `standard` | Balanced quality and cost |
+| `expert`   | Complex reasoning         |
+
+### Tier
+
+The quality and cost level of an LLM call. The platform maps each tier to a model; a raw model name is not accepted.
+
+## File handling
+
+### Asset reference
+
+A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
+
+### Blob
+
+A file (an image, a PDF, a spreadsheet) uploaded during a session and stored by the platform. `callbacks.uploadBlob(file)` returns a `blob:` asset reference, which `callbacks.getAssetUrl(reference)` or `callbacks.readAsset(reference)` resolves.
+
+### Blob scope
+
+How long a blob lasts:
+
+| Scope      | Survives a game reset? | Cleared when?                      |
+| ---------- | ---------------------- | ---------------------------------- |
+| `game`     | No                     | On a game reset or a re-initialise |
+| `settings` | Yes                    | On a re-initialise                 |
+
+## Development
+
+### Dev server
+
+The local runtime started by `sdk dev`, or in the background by any session command. It holds the session in memory and is the only thing that runs the game's logic. Its page at `/` is the console: the session UI, with a dev drawer (press the backtick key) for ticks, undo, reset, the waiting room, the state as JSON, and errors. Every surface has its own address, such as `/team/1/player/1`. It watches the package, so logic and bundle edits reach the next tick without a reset. See [The CLI and the dev server](../cli-and-dev-server.md).
+
+### CLI
+
+The `seriousgaming-sdk` command, run as `pnpm run sdk` in a package. It creates and updates resources, builds and publishes packages, and drives sessions. Session commands print JSON, so a script or an AI agent can play a game. See the [CLI reference](../cli-reference.md).
+
+### Lock file
+
+`.seriousgaming-sdk/session.json`, which names the running dev server (its pid, port and instance id, and the tools that started it), or a directory named by `SERIOUSGAMING_DEV_STATE_DIR`. A CLI command reads it to find the session. It holds no session state: the session is never written to disk, and when the server stops, the session is gone. The same directory holds the session overrides (`configuration.json`) and the scenario they were saved under (`configuration-scenario`).