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

package/dist/docs/cli-reference.md

@@ -0,0 +1,2488 @@
+<!-- Generated by `pnpm docs:generate` from `sdk-tools/cli/program.ts`, the resource registry and `sdk-tools/docs-partials/cli-reference/`. Edit those, not this file. -->
+
+# CLI reference
+
+Every `seriousgaming-sdk` command and flag, in one place. For a worked session that strings these commands together, see [Drive a game from the CLI](./cli-simulation-testing.md).
+
+## Command structure
+
+```
+pnpm run sdk [options] <command> [arguments]
+```
+
+## Global options
+
+The program's own options, which work with every command:
+
+| Option          | Default | Description             |
+| --------------- | ------- | ----------------------- |
+| `-v, --verbose` |         | Enable verbose logging. |
+
+Every command also takes `-j, --json` (see [JSON output](#json-output)). `-j, --json` and `-w, --working-dir` may come before the command as well as after it, so `sdk --json -w ./game view` is `sdk view --json -w ./game`.
+
+### Verbose mode
+
+```bash
+pnpm run sdk --verbose <command>
+```
+
+`-v, --verbose` works on every command. It is a flag only: no configuration file or environment variable turns it on.
+
+By default the CLI prints as little as it can, which suits scripts, CI, and agents that parse its output:
+
+- Errors and warnings always appear
+- Validation reports problems only, not the checks that passed
+- Progress from Vite and the TypeScript compiler is suppressed
+- Type generation and configuration loading run silently
+- The final summary (`✓ Build complete!`) always appears
+
+With `--verbose` you also see:
+
+- Each configuration file as it loads
+- The validation result for every resource, including the ones that passed
+- Type generation for each resource
+- Each build step, with Vite and TypeScript output
+- Asset copying and file generation
+
+```bash
+pnpm run sdk build --verbose
+pnpm run sdk generate --verbose
+pnpm run sdk resolve --verbose
+```
+
+A verbose build looks like this:
+
+```
+Step 1: Loading configuration...
+  Loaded: capabilities/counter/capability.sdk.json
+  Loaded: settings/engine/settings.sdk.json
+  Loaded: engine/engine.sdk.json
+  Loaded: ui/ui.sdk.json
+  ...
+  Found 1 capabilities, an engine, 1 user interfaces, 0 settings editors, 0 tick controllers, 0 hooks, and 0 validators
+
+Step 2: Validating...
+  ...
+    package "com.e2e" is valid
+    capability "counter" is valid
+    engine "engine" is valid
+    ui "ui" is valid
+  ...
+
+Step 3: Generating types...
+    Generating types for module engine
+  Generating types for engine...
+  Generated /path/to/engine/types.ts
+  Generated /path/to/engine/defaults.ts
+  ...
+
+✓ Build complete!
+```
+
+What each kind of output looks like, and when it appears:
+
+| Output                               | Default | `--verbose` | Example                                                                            |
+| ------------------------------------ | ------- | ----------- | ---------------------------------------------------------------------------------- |
+| Errors                               | Shown   | Shown       | `Engine "engine" reads capability "invalid" which is not found in configuration`   |
+| Warnings                             | Shown   | Shown       | `⚠️  Engine "engine" declares a read of capability "forecast", but no engine, ...` |
+| Progress and debug detail            | Hidden  | Shown       | `Loaded: capabilities/price/capability.sdk.json`                                   |
+| Per-resource success lines           | Hidden  | Shown       | `game "com.e2e.game" is valid`                                                     |
+| Vite, TypeScript, and process output | Hidden  | Shown       | `✓ 1176 modules transformed.`                                                      |
+
+To diagnose a failing build, rerun it verbose and keep the log:
+
+```bash
+pnpm run build --verbose 2>&1 | tee build.log
+```
+
+## Exit codes
+
+Every command exits with one of six codes, and the code says what kind of failure it was. Scripts, CI and agents branch on it; the message is for people and may change.
+
+| Code | Meaning                   | Examples                                                                                                  |
+| ---- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| 0    | Success                   |                                                                                                           |
+| 1    | Unexpected internal error | A bug in the CLI. Please report it                                                                        |
+| 2    | Usage error               | An unknown flag, a bad argument, missing input, a prompt needed with no terminal to ask on                |
+| 3    | Invalid package           | A schema or validation failure, a missing `seriousgaming.sdk.json`, a logic file that will not bundle     |
+| 4    | Refused by the game       | A denied command, a validator rejection, a conflict, a failed tick, a superseded write, a failed endpoint |
+| 5    | Environment               | No session running, a port in use, a dev server already running, the platform unreachable or unauthorised |
+
+Each failure also carries a stable error code in `UPPER_SNAKE` case, such as `MANIFEST_NOT_FOUND`, `REFUSED_VALIDATION` or `NO_SESSION`. The codes are the contract, and each belongs to one exit code. Every code, with its exit code and when it is reported, is listed in [CLI error codes](./cli-error-codes.md). The catalogue is also exported from `cli/utils/error-codes.ts` in `@seriousgaming/sdk-tools`.
+
+A session refusal maps one-to-one onto the outcome kinds a UI sees when one of its writes is refused ([`MutationOutcome`](./api/sdk-ui.md#mutationoutcome)): `REFUSED_DENIED`, `REFUSED_VALIDATION`, `REFUSED_CONFLICT`, `REFUSED_SUPERSEDED` and `TICK_FAILED`. A failed endpoint call reports `INVALID_REQUEST`, `HANDLER_ERROR` or `INVALID_RESPONSE`, or the refusal it shares with any other write. All of these exit 4.
+
+Without `--json`, a failure prints `Error: <message>` on stderr, followed by `Hint: <what to do>` when there is one.
+
+## JSON output
+
+Pass `-j, --json` to any command, or set `SERIOUSGAMING_JSON=1` in the environment, and the command writes exactly one JSON document to stdout, whether it succeeds or fails. Progress, logs and notices go to stderr. Every document is indented with two spaces.
+
+On success:
+
+```json
+{
+    "ok": true,
+    "command": "tick",
+    "data": {
+        "gameId": "com.example.factory.game",
+        "completedTicks": 1,
+        "complete": false,
+        "context": {}
+    },
+    "diagnostics": [],
+    "warnings": []
+}
+```
+
+On failure:
+
+```json
+{
+    "ok": false,
+    "command": "build",
+    "error": {
+        "code": "PACKAGE_INVALID",
+        "message": "Validation failed: 1 of 6 resources have errors.",
+        "hint": "Fix the errors listed and run the command again."
+    },
+    "diagnostics": [
+        {
+            "severity": "error",
+            "code": "SETTINGS_UNKNOWN_KEY",
+            "message": "Overrides \"BaseDemnd\", which settings \"engine\" does not declare",
+            "file": "scenarios/hard/scenario.sdk.json",
+            "pointer": "/definition/settings/engine/BaseDemnd",
+            "resource": { "type": "scenario", "identifier": "hard" },
+            "hint": "Did you mean 'BaseDemand'?"
+        }
+    ],
+    "warnings": []
+}
+```
+
+- `ok` says which of the two it is, as the UI protocol's `mutation:response` does
+- `command` is the full command path: `tick`, `new engine`, `timer`, `package publish`
+- `data` is the command's result: the session report for session commands, the change list for `new`, `update` and `delete`, the validation summary for `build --validate-only`. A command with nothing to report has `"data": null`
+- `error.code` is the stable code; `error.hint` says what to do; `error.details` carries structured detail where a failure has it, such as the outcome of a refused write (with a validator's `rejections`) or a failed endpoint call (with the steps it `applied`)
+- `diagnostics` lists findings about the package, errors and warnings both: on failure what failed it, on success the warnings a passing `build` found. See [Diagnostics](#diagnostics)
+- `warnings` lists notices the command printed on the way that point at no file
+
+Session commands (`init`, `tick`, `view`, `patch` and the rest) print their result as JSON even without the flag: the bare report, not the envelope.
+
+### Diagnostics
+
+A diagnostic is one finding, located as precisely as the check that made it can say. Read `file` and `pointer` (or `line` and `column`) to go straight to the problem; branch on `code`, never on `message`.
+
+| Field      | Always | What it holds                                                                                                   |
+| ---------- | ------ | --------------------------------------------------------------------------------------------------------------- |
+| `severity` | Yes    | `error`, which fails the command, or `warning`, which does not                                                  |
+| `code`     | Yes    | A stable code from the list below                                                                               |
+| `message`  | Yes    | What is wrong, for a person. Not part of the contract                                                           |
+| `file`     | No     | The file it is about, relative to the package root, with forward slashes. A directory ends in `/`               |
+| `pointer`  | No     | Where in `file`, when `file` is JSON: an RFC 6901 pointer such as `/definition/reads/0`. `""` is the whole file |
+| `line`     | No     | Where in `file`, when `file` is source code: 1-based                                                            |
+| `column`   | No     | 1-based, with `line`                                                                                            |
+| `resource` | No     | The resource it is about: `{ "type": "scenario", "identifier": "hard" }`                                        |
+| `hint`     | No     | What to do about it, such as `Did you mean 'BaseDemand'?` or what replaced a removed field                      |
+| `tick`     | No     | For `LOGIC_ERROR`: the tick the logic threw in                                                                  |
+| `team`     | No     | For `LOGIC_ERROR`: the team whose logic threw, `{ "teamId": "team-1", "index": 0 }`                             |
+
+When game logic throws during a session command (`init`, `tick`, `endpoint call` and the rest), the command fails with the code for what it was doing (`TICK_FAILED` for a tick, `HANDLER_ERROR` for an endpoint, `SESSION_ERROR` otherwise, all exit 4), and the first diagnostic is `LOGIC_ERROR`, located in your TypeScript through the bundle's source map:
+
+```json
+{
+    "severity": "error",
+    "code": "LOGIC_ERROR",
+    "message": "the second round has no stock",
+    "file": "engine/logic.ts",
+    "line": 13,
+    "column": 15,
+    "resource": { "type": "engine", "identifier": "engine" },
+    "tick": 2,
+    "team": { "teamId": "team-1", "index": 0 }
+}
+```
+
+A failure that is the environment's rather than the game's keeps its own code even when it surfaces through logic: a call to `generateText` with no platform API key configured fails the tick or endpoint call with `LLM_NOT_CONFIGURED` (exit 5), and its hint says how to configure one.
+
+Without `--json`, each diagnostic that names a file is printed under the error as `<code> at <location>`: `LOGIC_ERROR at engine/logic.ts:13:15 (tick 2, team 1)`, or `SETTINGS_UNKNOWN_KEY at scenarios/hard/scenario.sdk.json#/definition/settings/engine/BaseDemnd`.
+
+#### Diagnostic codes
+
+| Code                          | When                                                                                                                                                                                                                                               |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PACKAGE_INVALID`             | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet.                                                                                                                              |
+| `SCHEMA_INVALID`              | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value.                                                                                                                                                |
+| `JSON_INVALID`                | A bundle file is not valid JSON.                                                                                                                                                                                                                   |
+| `BUNDLE_MISSING`              | A resource directory holds no bundle file.                                                                                                                                                                                                         |
+| `REMOVED_FIELD`               | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it.                                                                                                                                                  |
+| `LAYOUT_OUTDATED`             | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now.                                                                                                                                      |
+| `FEATURE_UNSUPPORTED`         | The manifest's `requires` names an optional feature this version of the SDK does not support.                                                                                                                                                      |
+| `REFERENCE_UNKNOWN`           | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare.                                                                                                                                   |
+| `SETTINGS_UNKNOWN`            | A scenario overrides a settings resource the package does not declare.                                                                                                                                                                             |
+| `SETTINGS_UNKNOWN_KEY`        | A scenario overrides a key that its settings resource does not declare.                                                                                                                                                                            |
+| `SETTINGS_INVALID`            | A scenario's override does not match its settings resource's schema.                                                                                                                                                                               |
+| `SETTINGS_RESERVED`           | A settings resource is named `game`, which is reserved for the built-in game settings.                                                                                                                                                             |
+| `SETTINGS_LOCKED`             | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`.                                                                                                                            |
+| `GAME_CONSTRAINT_INVALID`     | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it.                                                                                                                                          |
+| `GAME_CONSTRAINT_VIOLATED`    | The game's own value for a `game` setting breaks its `gameSettingsConstraints`.                                                                                                                                                                    |
+| `LOGIC_EXPORT_MISSING`        | A logic file is missing, or does not export the functions its resource needs.                                                                                                                                                                      |
+| `LOGIC_NODE_BUILTIN`          | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone.                                                                                                                                    |
+| `LOGIC_BUNDLE_FAILED`         | A logic file does not bundle: a syntax error, or an import that does not resolve.                                                                                                                                                                  |
+| `READ_NEVER_WRITTEN`          | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.                                                                                                                                        |
+| `NO_TERMINATION`              | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.                                                                                                                                              |
+| `EDITOR_ENDPOINT_STATEFUL`    | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.                                                                                                                 |
+| `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments.                                                                                              |
+| `ENDPOINT_UNREQUESTED`        | A warning: an internal endpoint no user interface lists in its `endpoints`.                                                                                                                                                                        |
+| `LOGIC_ERROR`                 | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. |
+
+### Non-interactive use
+
+The CLI prompts only when stdin and stdout are both terminals, JSON output is off and `CI` is unset. Anywhere else, a command that would need to ask fails with exit code 2 and `PROMPT_REQUIRED`, naming the question and how to pass the answer instead: as an argument, with `--file`, or on stdin. Input piped on stdin is read to the end, however long it takes.
+
+`delete` asks for confirmation, and so does an interactive `update` before it writes. Pass `-y, --yes` to answer it.
+
+`new package` fails with exit code 5 and `INSTALL_FAILED` when `pnpm install` fails in the new package. The files are written; run `pnpm install` in the package to finish.
+
+### Parsing JSON through pnpm
+
+The catch is `pnpm run`, not the CLI. Before version 12, pnpm prints a banner to stdout ahead of your command:
+
+```
+> com.example.game@0.0.1 sdk /path/to/package
+> seriousgaming-sdk view
+```
+
+That banner is not JSON, so `JSON.parse(stdout)` throws and `jq` stops at the first line. pnpm 12 sends it to stderr instead, but a script cannot count on which pnpm runs it, and the CLI cannot suppress the banner from inside. Add `--silent` to `pnpm run` whenever you parse the output:
+
+```bash
+# Pipe straight into jq
+pnpm run --silent sdk view | jq '.completedTicks'
+
+# The envelope from a command that takes --json
+pnpm run --silent sdk configure -f config.json --json | jq '.data.restarted'
+
+# Branch on the code, not the message
+pnpm run --silent sdk tick --json | jq -r 'if .ok then "ticked" else .error.code end'
+
+# Redirect to a file other tools will parse
+pnpm run --silent sdk package bundle --json > bundle.json
+```
+
+The same flag belongs in any command a Node script runs:
+
+```typescript
+const { stdout } = await execAsync('pnpm run --silent sdk view');
+const state = JSON.parse(stdout);
+```
+
+Calling the CLI binary directly, rather than through a `pnpm run` script, prints no banner, so `--silent` is unnecessary there.
+
+## Resource commands
+
+### Creating resources
+
+#### Create a capability
+
+```text
+pnpm run sdk new capability [definition] [options]
+```
+
+Create a new capability.
+
+| Option                     | Default               | Description                                                                      |
+| -------------------------- | --------------------- | -------------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the capability in.                               |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the capability definition.                        |
+| `--scope <scope>`          |                       | Cross-team visibility: 'team' (default), 'team-readable', 'shared' or 'private'. |
+
+Example:
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "inventory",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Stock": { "type": "number", "default": 100 }
+      },
+      "required": ["Stock"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+The optional `definition.scope` field sets the capability's cross-team visibility, and is written to the created `capability.sdk.json`:
+
+- `'team'` (the default): private to each team
+- `'team-readable'`: each team writes its own copy, but user interfaces on other teams may observe every team's value live in shared-state games
+- `'shared'`: one value for all teams
+- `'private'`: per team like `'team'`, but never delivered to any user interface, so a UI that reads or writes it fails the build
+
+For invocations that do not pass JSON, the `--scope` flag sets any of the four:
+
+```bash
+pnpm run sdk new capability --scope shared
+```
+
+#### Create settings
+
+```text
+pnpm run sdk new settings [definition] [options]
+```
+
+Create a new settings resource.
+
+| Option                     | Default               | Description                                                      |
+| -------------------------- | --------------------- | ---------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the settings resource in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the settings resource definition. |
+
+Example:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "demand",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "BaseDemand": {
+          "type": "number",
+          "description": "Base demand per tick",
+          "default": 100,
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+Creates `settings/<identifier>/settings.sdk.json`: named, read-only parameters that any resource reads by listing its identifier in `settings`. `definition.identifier` names the directory and is stripped from the bundle that is written, so on disk the directory is the name. A package may hold any number, so `update` and `delete` take the identifier.
+
+**Every property declares a `default`.** It is the value the game plays with unless a scenario or the session overrides it, so the command refuses a property without one, and a `settingsSchema` with a top-level `required`. With no JSON, the command prompts for the name and each property interactively.
+
+The identifier `game` is reserved for the built-in game settings, whose values the manifest sets (see [The game settings](./guides/settings.md#the-game-settings)), so `new settings` refuses it with `SETTINGS_RESERVED`.
+
+A settings resource does nothing until something reads it: add its identifier to the `settings` array of each resource that needs it, to the `configures` of the `setup` or `scenario_editor` slot to make it editable, and under a scenario's `settings` to override it. See the [settings guide](./guides/settings.md) and [Create settings](./recipes/create-settings.md).
+
+#### Create the engine
+
+```text
+pnpm run sdk new engine [definition] [options]
+```
+
+Create a new engine.
+
+| Option                     | Default               | Description                                                                                             |
+| -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the engine in.                                                          |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the engine definition.                                                   |
+| `--aggregate`              |                       | Scaffold logic exporting InitAggregate and RunAggregate, for an engine that runs once across all teams. |
+
+Example:
+
+```bash
+pnpm run sdk new engine '{
+  "definition": {
+    "writes": ["inventory"],
+    "uses": ["generateText"],
+    "settings": ["demand"]
+  },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+The optional `definition.uses` field lists the runtime callbacks the engine may invoke: `'generateText'`, `'extractText'`, `'generateSpeech'`, and `'writeBlob'`. It defaults to `[]`. Each one listed is present on the engine's generated `Callbacks`, so logic calls it without a `?.` check, and a call to an undeclared callback throws `UndeclaredApiUseError` at runtime. `new hook`, `new tick_controller`, and `new endpoint` accept the same field, as do the matching `update` commands.
+
+User interfaces have no `uses` field. `new ui`, `new session`, `new waiting_room`, `new presentation`, `new setup`, and `new scenario_editor` refuse one, and so does `pnpm run sdk build`: a user interface reaches an external service through an endpoint instead. See [Declare API uses](./recipes/declare-api-uses.md).
+
+The optional `definition.settings` field lists the settings resources the engine reads, by identifier, exactly as `reads` lists capabilities. Its logic receives exactly those as `settings`, keyed by identifier (`settings.demand.BaseDemand`), and an identifier the package does not declare fails the build. The UIs, the tick controller, hooks, validators, and endpoints accept the same field, as do the matching `update` commands. With no JSON, `new` offers the settings resources already on disk to choose from.
+
+The optional `--aggregate` flag scaffolds an engine that runs once across all teams rather than per team: its logic exports `Init`, `InitAggregate`, and `RunAggregate` instead of `Init` and `Run`. `Init` is optional in either shape: an engine without one starts from its capabilities' defaults, but the scaffold writes one to fill in. Those exports are what make the engine aggregate, so nothing is written into `engine.sdk.json`, and an authored `definition.aggregate` is rejected. See the [multi-team games guide](./guides/multi-team-games.md).
+
+#### Create the game UI
+
+```text
+pnpm run sdk new ui [definition] [options]
+```
+
+Create a new user interface.
+
+| Option                     | Default               | Description                                                   |
+| -------------------------- | --------------------- | ------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the user interface in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the user interface definition. |
+
+Example:
+
+```bash
+pnpm run sdk new ui '{
+  "definition": {
+    "reads": ["revenue"],
+    "writes": ["price"],
+    "settings": ["display"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+`definition.reads` and `definition.writes` are arrays of capability identifiers, and a UI's `data` carries exactly the union of the two. `definition.settings` lists the settings resources it reads, which arrive as `settings` on `useUserInterfaceData()`, keyed by identifier. A value participants must not see, such as an answer key, belongs in a settings resource the UI does not list.
+
+The optional `definition.crossTeamReads` narrows `reads` to the capabilities for which every team's value arrives, live. Each entry must also appear in `reads` and must name a capability with `scope: 'team-readable'`, in a shared-state game. Only `new ui` and `new waiting_room` accept it, and both write it straight into the created bundle. See [Observe other teams' state](./recipes/observe-other-teams-state.md).
+
+#### Create a scenario
+
+```text
+pnpm run sdk new scenario [definition] [options]
+```
+
+Create a new scenario.
+
+| Option                     | Default               | Description                                             |
+| -------------------------- | --------------------- | ------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the scenario in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the scenario definition. |
+
+Example:
+
+```bash
+pnpm run sdk new scenario '{
+  "definition": {
+    "identifier": "ai_influence",
+    "locales": {
+      "en": {
+        "name": "AI Influence",
+        "description": "AI-driven market disruption"
+      }
+    },
+    "settings": {
+      "demand": { "BaseDemand": 50 }
+    }
+  },
+  "rootDirectory": "."
+}'
+```
+
+Creates `scenarios/<identifier>/scenario.sdk.json` and `scenarios/<identifier>/assets/shared/`. The directory is the declaration: nothing registers it. `settings` is keyed by settings identifier, and each entry is a partial override of that settings resource's defaults.
+
+#### Create the facilitator guide
+
+```text
+pnpm run sdk new guide [definition] [options]
+```
+
+Create a new facilitator guide.
+
+| Option                     | Default               | Description                                                      |
+| -------------------------- | --------------------- | ---------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the facilitator guide in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the facilitator guide definition. |
+
+Example:
+
+```bash
+pnpm run sdk new guide '{
+  "definition": {
+    "locales": {
+      "en": { "name": "Facilitator guide" },
+      "de": { "name": "Moderationsleitfaden" }
+    }
+  },
+  "rootDirectory": "."
+}'
+```
+
+Creates `guide/guide.sdk.json`, an `assets/` directory, and a recommended chapter skeleton under `content/<locale>/` for every declared locale. The per-locale `name` is the guide's title. See [Facilitator guides](./guides/guide.md).
+
+#### Create the session UI
+
+```text
+pnpm run sdk new session [definition] [options]
+```
+
+Create a new session user interface.
+
+| Option                     | Default               | Description                                                           |
+| -------------------------- | --------------------- | --------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the session user interface in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the session user interface definition. |
+
+Example:
+
+```bash
+pnpm run sdk new session '{
+  "definition": {
+    "reads": ["price", "workers"],
+    "writes": ["price", "workers"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+The session UI gives the facilitator cross-team, session-level control. See the [session UIs guide](./guides/session.md).
+
+#### Create the waiting room UI
+
+```text
+pnpm run sdk new waiting_room [definition] [options]
+```
+
+Create a new waiting room user interface.
+
+| Option                     | Default               | Description                                                                |
+| -------------------------- | --------------------- | -------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the waiting room user interface in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the waiting room user interface definition. |
+
+Example:
+
+```bash
+pnpm run sdk new waiting_room '{
+  "definition": {
+    "reads": ["briefing"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+The holding screen participants see instead of the game UIs while the facilitator has the session's waiting room open. It is a game UI in a different display context: the same `reads`, `writes`, `endpoints`, hooks, and callbacks are available, and it renders under `UserInterfaceWrapper`. It lives at the `waiting_room/` slot, so nothing references it.
+
+The manifest's `waitingRoom` block carries one setting, `openOnStart`, so `"openOnStart": true` there makes every session begin with the room open. See the [waiting room UIs guide](./guides/waiting-room.md).
+
+#### Create the presentation
+
+```text
+pnpm run sdk new presentation [definition] [options]
+```
+
+Create a new presentation.
+
+| Option                     | Default               | Description                                                 |
+| -------------------------- | --------------------- | ----------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the presentation in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the presentation definition. |
+
+Example:
+
+```bash
+pnpm run sdk new presentation '{
+  "definition": {
+    "reads": ["results"],
+    "settings": ["engine"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+The facilitator's slide deck. It reads every team's state through `reads` and its settings through `settings`, and accepts no `writes`, `uses` or `endpoints`. It renders under `PresentationWrapper`, with or without a session, and the starter deck it scaffolds is built with `@seriousgaming/deck`, which the package must list at the SDK's version. It lives at the `presentation/` slot, so nothing references it. See the [presentations guide](./guides/presentation.md).
+
+#### Create the setup screen
+
+```text
+pnpm run sdk new setup [definition] [options]
+```
+
+Create a new setup user interface.
+
+| Option                     | Default               | Description                                                         |
+| -------------------------- | --------------------- | ------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the setup user interface in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the setup user interface definition. |
+
+Example:
+
+```bash
+pnpm run sdk new setup '{
+  "definition": {
+    "configures": ["demand"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+The short form a facilitator fills in at session creation. `configures` lists the settings resources it edits, by identifier, and what it writes lands in that session's overrides only. A game with a setup screen opens at its configuration step and waits for Play. It renders under `SettingsEditorWrapper` and may send `requestPlay`. It lives at the `setup/` slot, so nothing references it. See the [setup guide](./guides/setup.md).
+
+#### Create the scenario editor
+
+```text
+pnpm run sdk new scenario_editor [definition] [options]
+```
+
+Create a new scenario editor.
+
+| Option                     | Default               | Description                                                    |
+| -------------------------- | --------------------- | -------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the scenario editor in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the scenario editor definition. |
+
+Example:
+
+```bash
+pnpm run sdk new scenario_editor '{
+  "definition": {
+    "configures": ["demand"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+The screen for authoring lasting scenarios, at any time and with no session. `configures` lists the settings resources it edits, by identifier. It renders under `SettingsEditorWrapper`, the host offers save-as-scenario from it (never from setup), and the host ignores `requestPlay` from it. It lives at the `scenario_editor/` slot, so nothing references it. It is optional: `customScenarios.supported` is what switches custom scenarios on. See the [scenario editor guide](./guides/scenario-editor.md).
+
+#### Create the tick controller
+
+```text
+pnpm run sdk new tick_controller [definition] [options]
+```
+
+Create a new tick controller.
+
+| Option                     | Default               | Description                                                    |
+| -------------------------- | --------------------- | -------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the tick controller in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the tick controller definition. |
+
+Minimal example:
+
+```bash
+pnpm run sdk new tick_controller '{
+  "definition": {},
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+With capability reads and settings:
+
+```bash
+pnpm run sdk new tick_controller '{
+  "definition": {
+    "reads": ["progress"],
+    "settings": ["timing"]
+  },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+#### Create a hook
+
+```text
+pnpm run sdk new hook [definition] [options]
+```
+
+Create a new hook.
+
+| Option                     | Default               | Description                                         |
+| -------------------------- | --------------------- | --------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the hook in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the hook definition. |
+
+A hook is a single-signal handler that fires on an out-of-tick lifecycle event. The available signals are `participantJoin` and `participantMove`. See the [hooks guide](./guides/hooks.md).
+
+Minimal example:
+
+```bash
+pnpm run sdk new hook '{
+  "definition": {
+    "identifier": "assignroles",
+    "signal": "participantJoin"
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+With capability writes and settings:
+
+```bash
+pnpm run sdk new hook '{
+  "definition": {
+    "identifier": "assignroles",
+    "signal": "participantJoin",
+    "writes": ["roles"],
+    "settings": ["roles"]
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+#### Create a validator
+
+```text
+pnpm run sdk new validator [definition] [options]
+```
+
+Create a new validator.
+
+| Option                     | Default               | Description                                              |
+| -------------------------- | --------------------- | -------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the validator in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the validator definition. |
+
+A validator is a standalone, read-only check that gates UI-submitted state mutations before they are applied. It can only reject, and never modifies state. See the [validators guide](./guides/validators.md).
+
+Minimal example:
+
+```bash
+pnpm run sdk new validator '{
+  "definition": {
+    "identifier": "decisionlimit"
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+With capability reads and settings:
+
+```bash
+pnpm run sdk new validator '{
+  "definition": {
+    "identifier": "decisionlimit",
+    "reads": ["decisions"],
+    "settings": ["limits"]
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+#### Create an endpoint
+
+```text
+pnpm run sdk new endpoint [definition] [options]
+```
+
+Create a new endpoint.
+
+| Option                     | Default               | Description                                             |
+| -------------------------- | --------------------- | ------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the endpoint in.        |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the endpoint definition. |
+
+Scaffolds `endpoints/<identifier>/endpoint.sdk.json` and `endpoints/<identifier>/logic/logic.ts`, and regenerates types.
+
+```bash
+pnpm run sdk new endpoint                        # interactive
+pnpm run sdk new endpoint '<json definition>'    # from JSON argument
+pnpm run sdk new endpoint --file endpoint.json   # from JSON file
+```
+
+Example:
+
+```bash
+pnpm run sdk new endpoint '{
+  "definition": {
+    "identifier": "summarise",
+    "requestSchema": {
+      "type": "object",
+      "properties": { "text": { "type": "string" } },
+      "required": ["text"],
+      "additionalProperties": false
+    },
+    "responseSchema": {
+      "type": "object",
+      "properties": { "summary": { "type": "string" } },
+      "required": ["summary"],
+      "additionalProperties": false
+    },
+    "uses": ["generateText"],
+    "settings": ["summaries"]
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+An endpoint's `Handle` receives the settings resources it lists in `settings` as `settings`, keyed by identifier, as every other logic function does.
+
+Declare the endpoint on every UI that may call it by adding the identifier to the UI bundle's `endpoints` array:
+
+```json
+{
+    "definition": {
+        "endpoints": ["summarise"]
+    }
+}
+```
+
+### Notes on resource creation
+
+**The `rootDirectory` field.** Most `new` commands require `rootDirectory` in the root object, not inside `definition`, and it is usually `"."`. `new capability` and `new settings` are the exceptions: their bundles carry `definition` alone, and a `rootDirectory` is rejected.
+
+- **Engine and tick controller**: `{ "definition": {...}, "logic": {...}, "rootDirectory": "." }`
+- **User interfaces, including setup and the scenario editor**: `{ "definition": {...}, "rootDirectory": ".", "ui": { "entrypoint": "index.html" } }`
+
+**Identifiers.** For the nine slot kinds (`engine`, `ui`, `session`, `waiting_room`, `presentation`, `setup`, `scenario_editor`, `tick_controller`, and `guide`) any authored identifier is ignored, since the slot names the resource. For the plural kinds (`capability`, `settings`, `endpoint`, `hook`, `validator`, and `scenario`) `definition.identifier` is required: it names the directory to create, and is stripped from the bundle that is written.
+
+**Nothing to wire.** A package declares whatever sits under the conventional directories, and a game uses whatever its package declares, so the directory `new` creates is the whole of the wiring.
+
+### Updating resources
+
+Every resource type has an `update` command, and so does the package:
+
+| Command                                                 | What it does                          | Options                                       |
+| ------------------------------------------------------- | ------------------------------------- | --------------------------------------------- |
+| `update package [definition] [options]`                 | Update a package.                     | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update capability <identifier> [definition] [options]` | Update a capability.                  | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update settings <identifier> [definition] [options]`   | Update a settings resource.           | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update engine [definition] [options]`                  | Update an engine.                     | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update ui [definition] [options]`                      | Update a user interface.              | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update setup [definition] [options]`                   | Update a setup user interface.        | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update scenario_editor [definition] [options]`         | Update a scenario editor.             | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update tick_controller [definition] [options]`         | Update a tick controller.             | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update session [definition] [options]`                 | Update a session user interface.      | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update waiting_room [definition] [options]`            | Update a waiting room user interface. | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update presentation [definition] [options]`            | Update a presentation.                | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update scenario <identifier> [definition] [options]`   | Update a scenario.                    | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update guide [definition] [options]`                   | Update a facilitator guide.           | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update hook <identifier> [definition] [options]`       | Update a hook.                        | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update validator <identifier> [definition] [options]`  | Update a validator.                   | `--working-dir`, `--file`, `--patch`, `--yes` |
+| `update endpoint <identifier> [definition] [options]`   | Update an endpoint.                   | `--working-dir`, `--file`, `--patch`, `--yes` |
+
+Their options, as `update capability` takes them (the table above shows which commands take each):
+
+| Option                     | Default               | Description                                                |
+| -------------------------- | --------------------- | ---------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory containing the package.              |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the update definition.      |
+| `-p, --patch [PATCH]`      |                       | JSON Patch (RFC 6902) array for partial updates.           |
+| `-y, --yes`                |                       | Answer yes to the confirmation an interactive update asks. |
+
+#### Full replacement
+
+Replace a resource's whole definition:
+
+```bash
+pnpm run sdk update <type> <identifier> '<JSON>'
+```
+
+The nine slot kinds take the slot as their identifier, so `update` and `delete` take no identifier for them:
+
+```bash
+pnpm run sdk update engine '<JSON>'
+```
+
+Examples:
+
+```bash
+pnpm run sdk update capability inventory '{...}'
+pnpm run sdk update settings demand '{...}'
+pnpm run sdk update engine '{...}'
+pnpm run sdk update session '{...}'
+pnpm run sdk update waiting_room '{...}'
+pnpm run sdk update presentation '{...}'
+pnpm run sdk update setup '{...}'
+pnpm run sdk update scenario_editor '{...}'
+pnpm run sdk update tick_controller '{...}'
+pnpm run sdk update hook assignroles '{...}'
+pnpm run sdk update validator decisionlimit '{...}'
+pnpm run sdk update scenario ai_influence '{...}'
+pnpm run sdk update guide '{...}'
+pnpm run sdk update endpoint report '{...}'
+```
+
+#### Partial update with JSON Patch
+
+Change part of a resource with an [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902):
+
+```bash
+pnpm run sdk update <type> <identifier> --patch '<JSON-PATCH-ARRAY>'
+```
+
+The CLI loads the existing `.sdk.json` file, applies the patch, validates the result, and writes it back. The supported operations are `add`, `remove`, `replace`, `move`, `copy`, and `test`.
+
+```bash
+# Add a write to an engine
+pnpm run sdk update engine --patch '[
+  {"op": "add", "path": "/definition/writes/-", "value": "forecast"}
+]'
+
+# Change the default value of a capability variable
+pnpm run sdk update capability inventory --patch '[
+  {"op": "replace", "path": "/definition/variablesSchema/properties/Stock/default", "value": 200}
+]'
+
+# Change the default of a setting
+pnpm run sdk update settings demand --patch '[
+  {"op": "replace", "path": "/definition/settingsSchema/properties/BaseDemand/default", "value": 150}
+]'
+
+# Remove a read from an engine (by index)
+pnpm run sdk update engine --patch '[
+  {"op": "remove", "path": "/definition/reads/1"}
+]'
+
+# Update the tick count. A package is a game, so update package takes
+# no identifier, and its patch paths start at the manifest rather than a bundle
+pnpm run sdk update package --patch '[
+  {"op": "replace", "path": "/maxTicks", "value": 20}
+]'
+```
+
+**Renaming settings.** A full replacement of settings whose `definition.identifier` differs from the one named on the command line renames them, and re-keys every reference: each resource's `settings`, the `configures` of the setup and scenario editor slots, and each scenario's `settings`. The interactive `update settings` offers the same rename, and a new, changed, or removed property in the same pass. Every property must still declare a `default`:
+
+```bash
+pnpm run sdk update settings demand '{
+  "definition": {
+    "identifier": "demand",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "BaseDemand": {
+          "type": "number",
+          "description": "Base demand per tick",
+          "default": 150,
+          "minimum": 0
+        },
+        "Elasticity": {
+          "type": "number",
+          "description": "How strongly demand responds to price",
+          "default": 1.2
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+**Patch target.** Paths address the whole `.sdk.json` file as it sits on disk: `/definition/writes/-` for an engine's writes array, or `/logic/entrypoint` for the logic file path. `update package` patches `seriousgaming.sdk.json` itself, so its paths start at the top level.
+
+**Missing parent paths.** RFC 6902 `add` creates only the final path segment, so every parent must already exist. Resource templates may omit empty arrays (an engine created with `reads: []` may have no `reads` key on disk). To add to a field that may not exist, create it first:
+
+```bash
+# Two-op approach: create the array, then append
+pnpm run sdk update engine --patch '[
+  {"op": "add", "path": "/definition/reads", "value": []},
+  {"op": "add", "path": "/definition/reads/-", "value": "x"}
+]'
+
+# Or set the whole array in one operation
+pnpm run sdk update engine --patch '[
+  {"op": "add", "path": "/definition/reads", "value": ["x"]}
+]'
+```
+
+**Input modes.** When `--patch` is present, it takes priority over a positional JSON argument and stdin. `--file` supplies a full definition rather than a patch array, so a patch passed that way fails validation.
+
+#### Update the package
+
+```bash
+pnpm run sdk update package '<JSON>'
+pnpm run sdk update package --patch '<JSON Patch>'
+```
+
+A package is a game, so this one command replaces or patches `seriousgaming.sdk.json`, which carries the package identifier and the game's own fields (locales, `maxTicks`, `teams`, and so on). There is no `new game` and no `delete game`. The game's own identifier is the package identifier with `.game` appended, and it uses whatever the package declares. The command never touches `package.json`, which owns the npm name, description and version.
+
+A full replacement replaces the whole manifest, so any setting the JSON omits (`customScenarios` and `scenarioFormat` included) is dropped. The manifest has no `configuration` block: a game's values are its settings resources' defaults, so change those with `update settings`, and the build refuses a manifest that still carries one. Restate every setting you want to keep, or use `--patch` to change one path at a time.
+
+```bash
+pnpm run sdk update package '{
+  "identifier": "com.example.mygame",
+  "supportedLocales": ["en"],
+  "locales": { "en": { "name": "My Game" } },
+  "maxTicks": 10,
+  "teams": { "mode": "shared-state", "min": 2 }
+}'
+```
+
+`maxTicks` is optional when something else ends the game: the engine returning `complete: true` from `Run`, or a tick controller returning `complete: true`. A game with neither `maxTicks` nor a tick controller still builds, with a warning, because only the engine can end it and the build cannot see whether it ever does. See [Goal-based games](./guides/games.md#goal-based-games).
+
+### Deleting resources
+
+| Command                                    | What it does                          | Options                  |
+| ------------------------------------------ | ------------------------------------- | ------------------------ |
+| `delete capability <identifier> [options]` | Delete a capability.                  | `--working-dir`, `--yes` |
+| `delete settings <identifier> [options]`   | Delete a settings resource.           | `--working-dir`, `--yes` |
+| `delete engine [options]`                  | Delete an engine.                     | `--working-dir`, `--yes` |
+| `delete ui [options]`                      | Delete a user interface.              | `--working-dir`, `--yes` |
+| `delete setup [options]`                   | Delete a setup user interface.        | `--working-dir`, `--yes` |
+| `delete scenario_editor [options]`         | Delete a scenario editor.             | `--working-dir`, `--yes` |
+| `delete tick_controller [options]`         | Delete a tick controller.             | `--working-dir`, `--yes` |
+| `delete session [options]`                 | Delete a session user interface.      | `--working-dir`, `--yes` |
+| `delete waiting_room [options]`            | Delete a waiting room user interface. | `--working-dir`, `--yes` |
+| `delete presentation [options]`            | Delete a presentation.                | `--working-dir`, `--yes` |
+| `delete scenario <identifier> [options]`   | Delete a scenario.                    | `--working-dir`, `--yes` |
+| `delete guide [options]`                   | Delete a facilitator guide.           | `--working-dir`, `--yes` |
+| `delete hook <identifier> [options]`       | Delete a hook.                        | `--working-dir`, `--yes` |
+| `delete validator <identifier> [options]`  | Delete a validator.                   | `--working-dir`, `--yes` |
+| `delete endpoint <identifier> [options]`   | Delete an endpoint.                   | `--working-dir`, `--yes` |
+
+Their options, as `delete capability` takes them:
+
+| Option                     | Default               | Description                                                |
+| -------------------------- | --------------------- | ---------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory containing the package.              |
+| `-y, --yes`                |                       | Answer yes to the confirmation, so it runs without asking. |
+
+A slot resource takes no identifier, since the slot is its identifier:
+
+```bash
+pnpm run sdk delete <type> <identifier>
+pnpm run sdk delete <slot-type>
+```
+
+Examples:
+
+```bash
+pnpm run sdk delete capability inventory
+pnpm run sdk delete settings demand
+pnpm run sdk delete engine
+pnpm run sdk delete session
+pnpm run sdk delete waiting_room
+pnpm run sdk delete presentation
+pnpm run sdk delete setup
+pnpm run sdk delete scenario_editor
+pnpm run sdk delete tick_controller
+pnpm run sdk delete hook assignroles
+pnpm run sdk delete validator decisionlimit
+pnpm run sdk delete endpoint summarise
+pnpm run sdk delete scenario ai_influence
+pnpm run sdk delete guide
+```
+
+Each `delete` asks for confirmation first. Pass `-y, --yes` to answer it, as a script, CI or an agent must: without a terminal to ask on, a `delete` without `--yes` fails with `PROMPT_REQUIRED` (exit 2) rather than waiting.
+
+`delete settings` removes the settings directory and every reference to it: from each resource's `settings`, the `configures` of the setup and scenario editor slots, and each scenario's `settings`. It lists those references before asking you to confirm.
+
+### JSON output
+
+With `--json`, the `data` of `new`, `update`, and `delete` lists what changed, the same shape for every resource type. Paths are relative to the package root, with forward slashes:
+
+```bash
+pnpm run --silent sdk update settings demand -- \
+    --patch '[{"op":"replace","path":"/definition/settingsSchema/properties/BaseDemand/default","value":150}]' \
+    --json
+```
+
+```json
+{
+    "ok": true,
+    "command": "update settings",
+    "data": {
+        "resourceType": "settings",
+        "identifier": "demand",
+        "filesCreated": [],
+        "filesUpdated": ["settings/demand/settings.sdk.json"],
+        "filesDeleted": [],
+        "referencesUpdated": [],
+        "referencesRemoved": [],
+        "directoriesRenamed": []
+    },
+    "warnings": []
+}
+```
+
+A failure is the failure envelope, with a code and exit code 2 for a resource that does not exist:
+
+```json
+{
+    "ok": false,
+    "command": "update capability",
+    "error": { "code": "RESOURCE_NOT_FOUND", "message": "Capability \"missing\" not found" },
+    "diagnostics": [],
+    "warnings": []
+}
+```
+
+Prompts cannot produce JSON, so under `--json`:
+
+- `new` and `update` need a JSON definition (as an argument, via `--file`, or on stdin) or a `--patch`, since without one they would fall through to interactive prompts and fail with `PROMPT_REQUIRED`
+- `delete` needs `--yes`, which answers the confirmation prompt
+
+### Supplying JSON
+
+- **Inline**: wrap the JSON in single quotes and use double quotes inside, as every example on this page does
+- **From a file**: `--file definition.json`, or redirect it on stdin with `pnpm run sdk new capability < definition.json`
+
+### Identifier naming
+
+A package is named globally, so it keeps a reverse-DNS identifier. A resource is named by its directory inside the package, so it is a single short name:
+
+```
+✅ com.mycompany.retailgame     package
+✅ inventory                    resource
+❌ com.mycompany.game.inventory resource, not a short name
+❌ Inventory                    resource, not lowercase
+```
+
+A resource name is lowercase letters, digits, and underscores, starting with a letter. Its game's identifier is the package identifier with `.game` appended.
+
+## Session commands
+
+These commands play the game. None takes a game identifier: a package is a game, so there is nothing to name.
+
+### Where the session lives
+
+The dev server owns the session in memory and is the only thing that runs your game's logic. A session command reaches it rather than keeping a copy of its own: `sdk tick` advances the session a browser is watching, and a tick taken in the browser is what the next `sdk view` reports.
+
+`.seriousgaming-sdk/session.json` is how a command finds it: a lock file, written once at startup and removed at shutdown, carrying the server's pid, port and instance id, the machine it runs on, the version and install path of the tools that started it, and whether a command started it in the background. Session state itself is never written to disk. Set `SERIOUSGAMING_DEV_STATE_DIR` to keep the lock outside the package, one entry per package, for example in a container whose project directory is restored from a snapshot.
+
+With no server running, a session command starts one in the background, says so on stderr, and carries on. That server outlives the command, and `SERIOUSGAMING_DEV_PORT` tells it where to start looking for a port.
+
+Set `SERIOUSGAMING_DEV_URL` to send every session command to a server by its address instead of the one the lock names, such as one started with [`sdk dev --isolated`](#run-a-second-server-beside-your-own). A server that does not answer there fails the command with `DEV_SERVER_UNREACHABLE` (exit 5), and nothing is started in its place.
+
+**A stale lock.** A lock no longer names a running server when its process is gone, its pid is the process reading it, it was written on another machine, or its port refuses the connection or answers as another server. Such a lock is removed and the command carries on as if there were none, so `sdk dev` starts rather than reporting itself as already running.
+
+**A server from other tools.** A server outlives the tools that started it, so after an SDK upgrade, a rebuild of a linked checkout or a switch of branch, it may be running code your CLI no longer is. A command compares the lock's tools version and install path with its own:
+
+- A server a command started in the background is stopped and a fresh one started, with a `SESSION_RESTARTED` warning. Its session does not carry over
+- A server you started with `sdk dev` in a terminal is never stopped for you. The command fails with `SESSION_STALE` (exit 5) and a hint to run `sdk dev stop`
+
+**What the server could not apply.** Whatever the dev server could not apply live is recorded, not only logged, and every session command repeats it on stderr and in the envelope's `warnings`, so it reaches you even from a background server nobody is watching:
+
+| Code                | Meaning                                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `SETTINGS_STALE`    | An edit is pending until `sdk init` (see [What reloads](#what-reloads))                                 |
+| `RELOAD_FAILED`     | The last edited bundle did not load, so the previous one is still in use. Cleared by an edit that loads |
+| `CAPABILITY_SEEDED` | A capability was added with its schema defaults and `Init` has not run for it. Cleared by `sdk init`    |
+
+`GET /api/session` reports the same list as `warnings`, with the pending edits as `pending`.
+
+**What `sdk build` would refuse.** The dev server runs the checks `sdk build --validate-only` runs, when it starts and after every edit. A package that fails them still runs, so an edit that spans several files can be finished with the session in view, but not silently: each error is printed on the server's stderr, shown in a banner on the console, and added to the list above under its own diagnostic code (`REFERENCE_UNKNOWN`, `LOGIC_EXPORT_MISSING` and so on, see [CLI error codes](cli-error-codes.md)) with `build: true`. It is cleared by the edit that fixes it. Run `sdk build --validate-only` for the full report, warnings included.
+
+A game with a `setup` slot starts at its configuration step (see [Building a setup screen](./guides/setup.md)). A session a command starts for itself has no configuration page anybody is looking at, so the command presses Play for you. One you started with `sdk dev`, or sent back with `sdk reconfigure`, waits there: a tick or a context write is refused until somebody presses Play in the console or runs [`sdk play`](#undo-reset-and-reconfigure).
+
+Every session command also takes:
+
+- `-w, --working-dir [PATH]`: the package directory (default: the current directory)
+- `--no-server`: run in this process instead of starting a dev server. Each such command is a fresh session starting at tick 0, with nothing left behind, so a multi-tick run needs a server, or [`createTestSession`](./guides/engine-testing.md)
+
+See [The CLI and the dev server](./cli-and-dev-server.md) for how the two fit together.
+
+### Configure the game
+
+```text
+pnpm run sdk configure [settings] [options]
+```
+
+Override the game's settings for this session, keyed by settings identifier.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+| `-f, --file [PATH]`        |                       | Read the settings from a file.       |
+
+```bash
+pnpm run sdk configure '<JSON>'
+pnpm run sdk configure -f config.json
+```
+
+Sets settings values for CLI and dev server sessions, keyed by settings identifier: the directory name under `settings/`. For an engine whose settings resource is `settings/engine/`:
+
+```json
+{
+    "engine": { "BaseDemand": 200, "CostPerUnit": 2 }
+}
+```
+
+The number of rounds and the team bounds are the built-in `game` settings, set the same way: `{ "game": { "maxTicks": 6 } }` plays six ticks. `game.waitingRoom.openOnStart` is refused, because it takes effect before setup (see [The game settings](./guides/settings.md#the-game-settings)).
+
+The values are validated against each settings resource's `settingsSchema` and written to `.seriousgaming-sdk/configuration.json`, which holds the session overrides. A partial object is fine: keys you omit keep their scenario's value, or their default. An identifier that names no settings resource in the package is an error.
+
+Settings are resolved when a session starts (see [Settings](./guides/settings.md#overriding-settings)), so a running session is started again on the new values, at tick 0, keeping its team count, scenario and locale. A session waiting at its configuration step is started, because saving a configuration is what that step's Play is for. With no session running, the next one starts on it.
+
+With `--json`, the envelope's `data` is `{ "message": "...", "restarted": true|false }`, with the resolved `settings` when a session was restarted.
+
+**Output:** `✓ Settings saved, and the running session restarted on them at tick 0.` With no session running, `✓ Settings saved. The next session starts on them.`
+
+**Errors:** every validation failure is reported together, each labelled by its settings identifier and followed by the JSON Pointer to the offending field:
+
+```
+Error: Settings validation failed:
+Settings "engine": /BaseDemand must be number
+Unknown settings "pricing": expected one of engine, ui
+```
+
+`.seriousgaming-sdk/configuration.json` is authored content, so a value in it that no schema declares any more is an error rather than something to overwrite. Correct the file, or delete it to start again from the schema defaults.
+
+### Start or rebuild a session
+
+```text
+pnpm run sdk init [options]
+```
+
+Start the session, or put a running one back at tick 0.
+
+| Option                     | Default               | Description                                                                                  |
+| -------------------------- | --------------------- | -------------------------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                                                         |
+| `--teams [NUMBER]`         |                       | Number of teams to simulate (enables multi-team mode).                                       |
+| `--participants [COUNT]`   |                       | Participants to seed each team with, zero or more, or one per team as 3,0,2 (defaults to 1). |
+| `--scenario [ID]`          |                       | Scenario identifier to activate (uses default scenario if omitted).                          |
+| `--locale [LOCALE]`        |                       | Session locale to run the game in (defaults to en).                                          |
+| `--no-server`              |                       | Run in this process instead of starting a dev server.                                        |
+| `--walkthrough`            |                       | Drive the walkthrough run rather than the session.                                           |
+
+Starts the session, or rebuilds a running one from the package. Any session command starts a session when none is running, so a fresh package needs no `init` at all. Reach for it to rebuild an existing session with a different team count, scenario, or locale, or after editing settings.
+
+`init` resolves all three afresh, so omitting `--scenario` goes back to the package's default. That is the difference from `reset`, which returns the session to tick 0 with the scenario, team count, and locale it already has.
+
+In more detail:
+
+- `--teams`: a whole number, one or more; anything else is a usage error (exit 2). Each team has its own context. See [Multi-team games](./guides/multi-team-games.md)
+- `--participants`: zero is allowed, for testing a team before anybody has joined it. Without it, each team gets one, or the game's `perTeam.minParticipants`. The count is kept for later `init` runs until you pass a different `--teams`, which drops a per-team list
+- `--scenario`: the scenario's settings overrides sit between the settings defaults and the session overrides (see [Overriding settings](./guides/settings.md#overriding-settings)). If omitted and the game has a default scenario, the default is used. A scenario the package does not hold is `RESOURCE_NOT_FOUND` (exit 2). See [Scenarios](./guides/scenarios.md)
+- `--walkthrough`: see [Walkthrough runs](#walkthrough-runs)
+
+**Output:** JSON with the initial context and tick data, and `scenario`, the scenario the session started on (`null` when it has none). `maxTicks` is omitted for goal-based games whose `game` settings set no `maxTicks`. `sharedContext` is included when the game has shared capabilities, and `teamContexts` when it has several teams.
+
+```json
+{
+    "gameId": "com.example.factory.game",
+    "completedTicks": 0,
+    "maxTicks": 10,
+    "complete": false,
+    "context": {
+        "workers": { "WorkerCount": 5 },
+        "production": { "Production": 250 },
+        "sales": { "Sales": 0 }
+    },
+    "scenario": "standard"
+}
+```
+
+**Examples:**
+
+```bash
+# Single-team (default)
+pnpm run sdk init
+
+# Multi-team with 3 teams
+pnpm run sdk init --teams 3
+
+# Three teams: two participants, nobody, and one
+pnpm run sdk init --teams 3 --participants 2,0,1
+
+# With a specific scenario
+pnpm run sdk init --scenario hard_mode
+```
+
+### Advance a tick
+
+```text
+pnpm run sdk tick [options]
+```
+
+Execute the next tick, initializing the game first if it has not been run yet.
+
+| Option                     | Default               | Description                                                                                   |
+| -------------------------- | --------------------- | --------------------------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                                                          |
+| `-p, --patch [JSON]`       |                       | RFC 6902 JSON Patch to apply to context before tick.                                          |
+| `--team [NUMBER]`          |                       | Team to apply --patch to (multi-team games only, 1-based).                                    |
+| `--teams [NUMBER]`         |                       | Number of teams to simulate (first run only).                                                 |
+| `--participants [COUNT]`   |                       | Participants to seed each team with, zero or more, or one per team as 3,0,2 (first run only). |
+| `--scenario [ID]`          |                       | Scenario identifier to activate (first run only).                                             |
+| `--locale [LOCALE]`        |                       | Change the session locale for this tick onwards.                                              |
+| `--no-server`              |                       | Run in this process instead of starting a dev server.                                         |
+| `--walkthrough`            |                       | Drive the walkthrough run rather than the session.                                            |
+
+Executes one tick, optionally applying decisions first. Against a running `sdk dev` this advances that session, and the person watching the browser sees it immediately. With nothing running it starts a session and then ticks.
+
+How teams advance depends on the game's `teams.mode`:
+
+- **Shared-state**: every team advances together, with or without `--team`
+- **Independent** (the default when `mode` is omitted): with no `--team`, each team advances by one from its own tick, carrying the teams that can move past one that is complete or at its limit. `--team N` advances that team alone
+
+See [Play modes](./guides/multi-team-games.md#play-modes).
+
+In more detail:
+
+- `--patch`: paths start at the capability (`/price/Price`)
+- `--team N`: the stable team id `team-N` to tick, and the team the `--patch` applies to. Required with `--patch` in a multi-team game, and refused in a one-team game
+- `--teams`, `--participants` and `--scenario` apply to the first run, when the tick starts the session. `--locale` changes the session locale from this tick onwards
+- `--walkthrough`: see [Walkthrough runs](#walkthrough-runs)
+
+**Output:** JSON with the updated context for this tick. It includes `complete: true` when a tick controller has signalled that the game is finished. If the game is already complete, the command exits non-zero with the refusal.
+
+**Examples:**
+
+```bash
+# Execute next tick with no changes
+pnpm run sdk tick
+
+# Apply decisions before ticking
+pnpm run sdk tick \
+  -- --patch '[{"op":"replace","path":"/price/Price","value":3}]'
+
+# Multiple decisions
+pnpm run sdk tick \
+  -- --patch '[
+    {"op":"replace","path":"/price/Price","value":5},
+    {"op":"replace","path":"/workers/WorkerCount","value":8}
+  ]'
+```
+
+### Update the context
+
+```text
+pnpm run sdk patch <patch> [options]
+```
+
+Apply an RFC 6902 JSON Patch to the game context without ticking forward.
+
+| Option                     | Default               | Description                                             |
+| -------------------------- | --------------------- | ------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                    |
+| `--team [NUMBER]`          |                       | Team to patch (required for multi-team games, 1-based). |
+| `--shared`                 |                       | Patch the shared store rather than a team.              |
+| `--no-server`              |                       | Run in this process instead of starting a dev server.   |
+| `--walkthrough`            |                       | Drive the walkthrough run rather than the session.      |
+
+Applies an RFC 6902 JSON Patch to the game context without advancing the tick. With no session running, it starts one first, so it patches tick 0 of a fresh session.
+
+| Command        | Effect                                                       | Use it for                                          |
+| -------------- | ------------------------------------------------------------ | --------------------------------------------------- |
+| `patch`        | Modifies the context, stays at the current tick              | Adjusting state without running the engine          |
+| `tick --patch` | Modifies the context, then executes the engine for next tick | Simulating decisions that should drive engine logic |
+
+In more detail:
+
+- `<patch>`: required, in the same format as `tick --patch`
+- `--team N`: the stable team id `team-N` to patch. Required in a multi-team game, unless you pass `--shared`
+- `--shared`: patches the shared store (see [shared capabilities](./guides/multi-team-games.md#shared-capabilities)), as a session UI's shared write does. Paths start at a shared capability (`/market/AveragePrice`), and every team sees the change. A `remove` is refused, because a shared write merges into the store. Use this for a shared capability in a multi-team game, where a team-addressed patch to one is refused
+
+**Output:** JSON with the updated context at the current tick.
+
+**Errors:** a failed operation exits non-zero and leaves the session unchanged. `Path does not exist` means a path does not match the context's structure, and `Array index out of range` means an index is past the end of an array. Other failures are reported as `Patch failed: <reason>`.
+
+**Examples:**
+
+```bash
+# Update a single context value
+pnpm run sdk patch '[{"op":"replace","path":"/price/Price","value":3}]'
+
+# Update multiple values
+pnpm run sdk patch '[
+  {"op":"replace","path":"/price/Price","value":5},
+  {"op":"replace","path":"/workers/WorkerCount","value":8}
+]'
+```
+
+### View the state
+
+```text
+pnpm run sdk view [options]
+```
+
+View the current game state.
+
+| Option                     | Default               | Description                                                       |
+| -------------------------- | --------------------- | ----------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                              |
+| `--team [NUMBER]`          |                       | Show a specific team (multi-team games only, 1-based).            |
+| `--full`                   |                       | Print the whole state projection rather than the reading summary. |
+| `--tick [NUMBER]`          |                       | Print a past committed tick rather than the current one.          |
+| `--to [NUMBER]`            |                       | With --tick, print every tick from --tick to this one.            |
+| `--no-server`              |                       | Run in this process instead of starting a dev server.             |
+| `--walkthrough`            |                       | Drive the walkthrough run rather than the session.                |
+
+Prints the current game state without changing it, or the state at a past tick.
+
+In more detail:
+
+- `--team N`: show only the team with the stable id `team-N`. Omit to show all teams
+- `--full`: the whole state projection is the session, every team's context and roster, the shared store, the resolved `settings`, the timer, and any armed faults. It is the same document the dev server serves at `GET /api/state` and the console renders from
+- `--tick N`: the state as it was at committed tick N, from the session's own snapshots. Returns `{ "entries": [...] }`, one per team per tick, each with `tick`, `teamId`, `index`, `name`, `context`, `recordedAt` and `complete`. The current tick is not in the past, so use `view` on its own for that
+- `--to M`: M is clamped to the last committed tick, so `--tick 0 --to 99` reads everything there is
+
+**Output:** JSON with the latest tick data, the context, and each team's roster. In a multi-team game without `--team`, it returns `{ "teams": [...] }`. Every team carries `participants`, each with its `id`, `name`, `index`, and `connected`, so the plain view already answers who is in the room.
+
+**Examples:**
+
+```bash
+pnpm run sdk view
+
+# The whole state projection, which is what an agent reads
+pnpm run sdk view --full
+
+# What rounds 1 to 3 left behind, for team 2
+pnpm run sdk view --tick 1 --to 3 --team 2
+```
+
+### Undo, reset, and reconfigure
+
+```text
+pnpm run sdk undo [options]
+```
+
+Undo the last committed tick.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--team [NUMBER]`          |                       | Team to undo (multi-team games only, 1-based).        |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+| `--walkthrough`            |                       | Drive the walkthrough run rather than the session.    |
+
+```text
+pnpm run sdk reset [options]
+```
+
+Return the session to tick 0.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--team [NUMBER]`          |                       | Team to reset (multi-team games only, 1-based).       |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+| `--walkthrough`            |                       | Drive the walkthrough run rather than the session.    |
+
+```text
+pnpm run sdk reconfigure [options]
+```
+
+Return the session to its configuration step, and to tick 0.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```text
+pnpm run sdk play [options]
+```
+
+Leave the configuration step and start the session: the console's Play.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```bash
+pnpm run sdk undo [--team N]             # undo the last committed tick
+pnpm run sdk reset [--team N]            # back to tick 0
+pnpm run sdk reconfigure                 # back to the configuration step, and tick 0
+pnpm run sdk play                        # leave the configuration step, as Play does
+```
+
+`reset` keeps the scenario, team count, and locale the session already has; use `init` to resolve them afresh. `undo` and `reset` also take `--walkthrough`. `reset --walkthrough` starts the walkthrough again from the session's current scenario, locale and configuration, as the console's reset does. See [Walkthrough runs](#walkthrough-runs).
+
+`reconfigure` is for a game with a `setup` slot, and is refused for one without. It resets as well, because settings are fixed when play starts: a change that did not restart the session would reach nothing.
+
+`play` starts a session waiting at its configuration step on the configuration it has, and prints the tick report with the resolved `settings` and `started: true`. On a session already playing it changes nothing and reports `started: false`. To set values and start in one go, use [`configure`](#configure-the-game).
+
+### Teams
+
+`<team>` is 1-based, as it reads in a URL.
+
+```text
+pnpm run sdk team add [name] [options]
+```
+
+Add a team to the running session.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--participants [COUNT]`   |                       | Participants to seed the new team with, zero or more. |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```text
+pnpm run sdk team remove <team> [options]
+```
+
+Remove an empty team (1-based, independent mode only).
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```text
+pnpm run sdk team rename <team> <name> [options]
+```
+
+Rename a team (1-based).
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+`team remove` deletes an empty team from an independent-mode session, as a session UI's `deleteTeam` does. It is refused in a shared-state session, for a team that still has participants (move them out with `participant move` first, connected or not), and for the last team. Every team starts with one placeholder participant unless you pass `--participants 0` to `team add` or `init`, so move that one too. The removed team's index is left as a gap and no other team is renumbered; the next `team add` takes the gap back as a new team with the default name. Undo never restores a removed team.
+
+### Participants
+
+```text
+pnpm run sdk participant add [name] [options]
+```
+
+Add a participant to a team.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--team [NUMBER]`          |                       | Team to add them to (1-based, defaults to 1).         |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```text
+pnpm run sdk participant rename <participantId> <name> [options]
+```
+
+Rename a participant.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```text
+pnpm run sdk participant move <participantId> <team> [options]
+```
+
+Move a participant to another team (1-based).
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+`participant add` defaults to team 1 when `--team` is omitted.
+
+### Waiting room, scenario, and locale
+
+```text
+pnpm run sdk waiting-room <action> [options]
+```
+
+Open or close the session waiting room.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+`<action>` is `open` or `close`.
+
+```text
+pnpm run sdk scenario [identifier] [options]
+```
+
+Activate a scenario, or `none` to run on the settings defaults.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+```text
+pnpm run sdk locale <code> [options]
+```
+
+Change the session locale.
+
+| Option                     | Default               | Description                                           |
+| -------------------------- | --------------------- | ----------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                  |
+| `--no-server`              |                       | Run in this process instead of starting a dev server. |
+
+### The tick timer
+
+For a game with a [tick controller](./guides/tick-controller.md). Each command prints the timer afterwards: one `timer` for the session, or one per team in an independent multi-team game, where every team has its own. Each is the timer's `TimerState` (`enabled`, `paused`, `nextTickAt`, `intervalMs`, `pausedAt`, `pausedMs`, `extendedMs`, `scheduleStartedAt`, durations in milliseconds) plus `nextTickIn`, the whole seconds left, for a person reading it.
+
+```text
+pnpm run sdk timer [action] [seconds] [options]
+```
+
+Pause, resume or extend the automatic tick timer, or report it when no action is given. `extend <seconds>` moves the scheduled tick only, and a negative value brings it forward.
+
+| Option                     | Default               | Description                                                               |
+| -------------------------- | --------------------- | ------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                                      |
+| `--team [NUMBER]`          |                       | Team whose timer to address (independent multi-team games only, 1-based). |
+| `--no-server`              |                       | Run in this process instead of starting a dev server.                     |
+
+```bash
+pnpm run sdk timer                       # report it
+pnpm run sdk timer pause [-- --team N]
+pnpm run sdk timer resume [-- --team N]
+pnpm run sdk timer extend <seconds> [-- --team N]
+```
+
+**Moving time.** On a dev server started with `--fake-clock`, time stands still until you move it:
+
+```text
+pnpm run sdk clock advance <seconds> [options]
+```
+
+Move the clock forward, running every automatic tick that comes due.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+
+It runs every automatic tick that falls due on the way, so three minutes on a one-minute timer is three ticks, and prints `advancedBy`, `ticksRun`, the timer and the tick report. It is refused on the real clock, and backwards. See [Testing without waiting](./guides/tick-controller.md#testing-without-waiting).
+
+`extend` takes seconds, moves the currently scheduled tick only, and a negative number brings it forward. The interval the controller returns for later ticks is untouched. It is refused while the timer is paused, because there is no scheduled tick to move. Leaving out `--team` addresses every team, and `--team` is refused where every team shares one timer.
+
+### Fault injection
+
+The dev server serialises every write against every tick, so it never produces the `conflict` outcome a production runtime produces most, which is the 'Try again' path your UI was told to offer. Arming a fault makes that path reachable, deliberately and reproducibly.
+
+```text
+pnpm run sdk fault [kind] [options]
+```
+
+Arm a failure the dev server cannot otherwise produce, so the path a UI was told to handle is reachable in development: conflict, denied, llm-failure, hook-throw, endpoint-timeout, tick-failure.
+
+| Option                     | Default               | Description                                               |
+| -------------------------- | --------------------- | --------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                      |
+| `--times [NUMBER]`         |                       | Fire this many times before disarming (defaults to once). |
+| `--reason [TEXT]`          |                       | Message to carry on the resulting outcome.                |
+| `--disarm`                 |                       | Disarm the fault instead of arming it.                    |
+| `--no-server`              |                       | Run in this process instead of starting a dev server.     |
+
+```bash
+pnpm run sdk fault conflict --reason 'testing the Try again path'
+pnpm run sdk fault llm-failure --times 3
+pnpm run sdk fault conflict --disarm
+```
+
+Available faults: `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`. Each fires once unless `--times` says otherwise, and `--disarm` puts it away. A `--reason` becomes the message on the refusal, failed tick, or failed endpoint call the fault produces, so you can check how your UI shows it; on `hook-throw` it is added to the failure the console reports.
+
+`llm-failure` fails the next call your logic makes to a platform service (`generateText`, `extractText`, or `generateSpeech`) as a platform failure would, with `--reason` in the error. Each failed call uses up one of its `--times`, so `--times 3` fails the next three calls, whichever resources make them. Logic that does not catch the error fails its tick, hook, or endpoint call, exactly as it would in production.
+
+### Walkthrough runs
+
+A walkthrough is a disposable second run of the same game beside the session, for demonstrating it: one team, one participant, always from tick 0, and isolated from the session in both directions, so driving it moves nothing you were about to play. It inherits the session's configuration, scenario, and locale, respects the tick limit its session resolves, and never shows the waiting room.
+
+`--walkthrough` points `init`, `tick`, `view`, `patch`, `undo`, `reset`, and `endpoint call` at it instead of the session.
+
+```bash
+pnpm run sdk view --walkthrough            # where the walkthrough is
+pnpm run sdk tick --walkthrough            # advance it, leaving the session alone
+pnpm run sdk reset --walkthrough           # back to tick 0
+```
+
+The run is built the first time something asks for it, so there is nothing to create. In `sdk dev` it is also a surface, at `/walkthrough`, listed in the drawer's Surfaces tab.
+
+Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui.md#walkthroughs).
+
+### Upload a blob
+
+```text
+pnpm run sdk blob upload <file> [options]
+```
+
+Upload a file as a blob and print its blob ID.
+
+| Option                     | Default               | Description                                               |
+| -------------------------- | --------------------- | --------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                      |
+| `--settings`               |                       | Store with settings retention (survives a session reset). |
+
+Uploads a file and associates it with the game session. It returns the `blob:`-prefixed asset reference that you can patch into the game context for the engine and user interfaces to use (see [Asset references](./guides/file-handling.md#asset-references)).
+
+`--settings` stores the blob with `'settings'` retention, as a setup or scenario editor upload is, which survives a session reset. Without it the blob has `'game'` retention, cleared on reset.
+
+**Output (default):**
+
+```
+Uploaded blob: blob:a3f7c2d1-84b0-4e12-9f1a-0c7e8a3b1d5e
+  File:  market-research.pdf
+  Type:  application/pdf
+  Retention: game
+```
+
+**Output (`--json`):** the [envelope](#json-output), whose `data` is:
+
+```json
+{
+    "reference": "blob:a3f7c2d1-84b0-4e12-9f1a-0c7e8a3b1d5e",
+    "name": "market-research.pdf",
+    "mimeType": "application/pdf",
+    "retention": "game"
+}
+```
+
+Upload and patch into the context:
+
+```bash
+REFERENCE=$(pnpm run --silent sdk blob upload ./market-research.pdf --json | jq -r '.data.reference')
+pnpm run sdk patch \
+  "[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
+```
+
+A blob with settings retention, which survives a session reset:
+
+```bash
+pnpm run sdk blob upload ./scenario-brief.pdf --settings
+```
+
+See [File handling](./guides/file-handling.md) for the full reference.
+
+### Call an endpoint
+
+```text
+pnpm run sdk endpoint call <identifier> [options]
+```
+
+Invoke an endpoint against the running session and print its response.
+
+| Option                         | Default               | Description                                                               |
+| ------------------------------ | --------------------- | ------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]`     | the current directory | The working directory to execute in.                                      |
+| `-r, --request [JSON]`         |                       | The request payload, as JSON.                                             |
+| `-f, --file [PATH]`            |                       | Read the request payload from a file.                                     |
+| `-t, --team [INDEX]`           |                       | The team a team-scoped endpoint acts on (one-based).                      |
+| `--external`                   |                       | Call as a caller outside the game, which reaches only external endpoints. |
+| `--principal [KIND:ID[:NAME]]` |                       | With --external, who the call stands in for, e.g. agent:claude-7:Claude.  |
+| `--attach [FIELD=PATH]`        |                       | Send a local file as a file field, inline as a data: URI (repeatable).    |
+| `--save-blobs [DIR]`           |                       | Save every file the response names into DIR.                              |
+| `--no-server`                  |                       | Run in this process rather than against a dev server.                     |
+| `--walkthrough`                |                       | Drive the walkthrough run rather than the session.                        |
+
+Invokes one of the package's endpoints against the running session and prints its response as JSON.
+
+It exercises an endpoint without its real caller. An external endpoint is reached in production by a caller outside the game, such as a facilitator's AI agent, and a user interface endpoint by a screen you may not have built yet: both are slow and unrepeatable ways to find out that a request schema is wrong.
+
+In more detail:
+
+- `--external`: an internal endpoint is refused, and the handler sees `caller.role` as `'external'` with no `userInterfaceIdentifier`
+- `--principal`: who the call stands in for, as a platform would say after authenticating its caller. The handler sees it as `caller.principal`, and the audit records it
+- `--attach`: a file field is one whose schema carries `blob`. A dotted field reaches into nested objects
+- `--save-blobs`: each `blob:` reference in the response is saved into `DIR` under its stored name
+- `--json`: the [envelope](#json-output) carries the response as `data`, or the failure (see below)
+
+The request may also arrive on stdin, so a payload built by another command can be piped straight in.
+
+A failed call exits non-zero and prints its kind, its message, and the effects that had already landed before it stopped:
+
+```
+Error: Endpoint "startround" failed (tick-failed): Endpoint "startround" stopped at action 1 ("tick"): The game is complete. Its write, action 0 ("tick") had already been applied
+Applied before the failure: its write, action 0 ("tick")
+Failed at: action 1 ("tick")
+```
+
+A failed call exits 4. With `--json`, the failure envelope's code names the kind, and its `error.details` carries the failure itself:
+
+```json
+{
+    "ok": false,
+    "command": "endpoint call",
+    "error": {
+        "code": "INVALID_REQUEST",
+        "message": "Endpoint \"setprice\" failed (invalid-request): ...\nNothing was applied.",
+        "details": {
+            "outcome": {
+                "kind": "invalid-request",
+                "message": "Endpoint \"setprice\" rejected the request: /price must be <= 50"
+            },
+            "applied": []
+        }
+    },
+    "diagnostics": [],
+    "warnings": []
+}
+```
+
+The code is `INVALID_REQUEST`, `HANDLER_ERROR` or `INVALID_RESPONSE` for the three failures only an endpoint has, and the refusal's own code (`REFUSED_DENIED`, `TICK_FAILED` and so on) for the rest. `outcome.kind` is one of `denied`, `invalid-request`, `handler-error`, `invalid-response`, `conflict`, a failed step's own kind such as `tick-failed`, or `error`. `applied` lists the steps that committed, and `failedStep` names the one that failed. See [Endpoints](./guides/endpoints.md#when-a-call-fails).
+
+Against a dev server, an `--external` call also prints each returned `blob:` reference with the URL an outside caller would fetch it from. That goes to stderr, so stdout stays the response alone for a script to parse.
+
+A file sent the way a script without an upload route of its own would, and the export an endpoint returns saved beside it:
+
+```bash
+pnpm run sdk endpoint call attachresearch --external --team 1 --attach document=./research.pdf
+pnpm run sdk endpoint call export --external --save-blobs ./exports
+```
+
+To send a file the other way, upload it first with `sdk blob upload` and put the `blob:` reference it prints in the request.
+
+A team-scoped endpoint that changes state:
+
+```bash
+pnpm run sdk endpoint call setprice --team 1 --request '{"price": 3.53}'
+```
+
+```json
+{
+    "previous": 5,
+    "current": 3.53
+}
+```
+
+A session-scoped endpoint takes no `--team`, because there is no team for the value to mean anything against. An endpoint that declares `writes` applies its change to the board as part of the call, so `sdk view` afterwards shows it.
+
+### List the endpoints
+
+```text
+pnpm run sdk endpoint list [options]
+```
+
+List the package's endpoints and what each one may do.
+
+| Option                     | Default               | Description                                            |
+| -------------------------- | --------------------- | ------------------------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                   |
+| `--external`               |                       | Only the endpoints a caller outside the game may call. |
+
+Prints every endpoint the package declares, with its scope, whether it writes, whether a caller outside the game may call it, and its description. It reads the manifest, so it answers without starting a session.
+
+With `--json`, the [envelope](#json-output)'s `data` lists the endpoints, including each one's request and response schemas.
+
+An endpoint that declares `actions` is marked `acts` and lists them, and one that answers in two phases (`Plan` and `Respond`) is marked `responds after`. `--json` carries both as `actions` and `responds`.
+
+**Output (default):**
+
+```
+setprice  (team, writes, external)
+  Set the unit price
+  Sets a team's unit price, in pounds per unit. Use this when a facilitator asks
+  to change what a team charges.
+  writes: price
+```
+
+The description column is the reason to run it. On an external endpoint, the description is what an outside caller, a model most of all, reads to decide whether to call it. Reading yours side by side is when you notice that three of them say much the same thing, which means a wrong call every session and is the one thing here that no test catches.
+
+### Audit endpoint calls
+
+```text
+pnpm run sdk endpoint audit [options]
+```
+
+List every endpoint call that changed the running session, and who made it.
+
+| Option                     | Default               | Description                                       |
+| -------------------------- | --------------------- | ------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.              |
+| `--walkthrough`            |                       | Read the walkthrough run rather than the session. |
+
+Lists every endpoint call that changed the running session, oldest first: which endpoint, the team it ran for, who called it (with the principal of an external call), what it wrote, and the actions it carried out. A call that stopped partway says where. The dev server holds the log, so this needs one running; a `--no-server` session is new and has nothing to show.
+
+With `--json`, the [envelope](#json-output)'s `data` is the entries.
+
+**Output (default):**
+
+```
+2026-09-30T14:02:11.000Z  startround  by external agent:claude-7 (Claude)
+  wrote noticeboard; did setWaitingRoom, tick
+```
+
+### Team addressing errors
+
+| Error                                                          | Cause                                                         |
+| -------------------------------------------------------------- | ------------------------------------------------------------- |
+| `--team can only be used with multi-team games`                | `--team` passed, but the session has one team                 |
+| `--team <number> is required for multi-team games`             | `patch` in a multi-team game without `--team`                 |
+| `--team is required when using --patch with a multi-team game` | `tick --patch` in a multi-team game without `--team`          |
+| `There is no team N in this session. Teams: 1, 2, 3`           | The team number is out of range, or the team has been removed |
+
+## Development server
+
+### Start the dev server
+
+Run the game with live reloading:
+
+```text
+pnpm run sdk dev [options]
+```
+
+Start the Serious Gaming development server with hot reload.
+
+| Option                      | Default               | Description                                                                                                                                                                                                                           |
+| --------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]`  | the current directory | The working directory to execute in.                                                                                                                                                                                                  |
+| `-p, --port [PORT]`         | `3000`                | Port to run the dev server on, or auto for any free port (can also be set via SERIOUSGAMING_DEV_PORT env var or .env file).                                                                                                           |
+| `--vite-port [VITE_PORT]`   |                       | Port to run the Vite dev server on (defaults to PORT + 1).                                                                                                                                                                            |
+| `--asset-port [ASSET_PORT]` |                       | Port game UI bundles and their assets are served from, which is a separate origin from the console (defaults to the next free port after the Vite port).                                                                              |
+| `--no-open`                 |                       | Do not automatically open browser.                                                                                                                                                                                                    |
+| `--api-key [KEY]`           |                       | Serious Gaming platform API key for LLM calls (can also be set via SERIOUSGAMING_API_KEY env var or .env file).                                                                                                                       |
+| `--host [URL]`              |                       | Serious Gaming platform origin for LLM calls (can also be set via SERIOUSGAMING_API_HOST env var or .env file).                                                                                                                       |
+| `--lan`                     |                       | Listen on every network interface, so phones and tablets on the same network can connect (localhost only by default).                                                                                                                 |
+| `--teams [NUMBER]`          |                       | Number of teams to simulate (each accessible at `/team/<n>);` omit to use the game's teams.min.                                                                                                                                       |
+| `--participants [COUNT]`    |                       | Participants to seed each team with, zero or more, or one per team as 3,0,2 (defaults to 1).                                                                                                                                          |
+| `--scenario [ID]`           |                       | Scenario identifier to activate (uses default scenario if omitted).                                                                                                                                                                   |
+| `--fake-clock`              |                       | Run on a clock that moves only when `sdk clock advance` moves it, to test automatic ticks without waiting.                                                                                                                            |
+| `--reinit-on-change`        |                       | Restart the game at tick 0 whenever an edit applies only at initialisation (a setting, a manifest field such as teams, a capability removed or rescoped), rather than recording it as pending once play is under way.                 |
+| `--isolated`                |                       | Run beside any dev server already running for this package, for tests and recordings: no lock file (CLI commands reach it through SERIOUSGAMING_DEV_URL), configuration from the package alone, and uploads in a temporary directory. |
+
+In more detail:
+
+- `--port`: where to start looking for a port. The default is `SERIOUSGAMING_DEV_PORT` when set, otherwise 3000. The server steps up to the first free port from there and prints the one it lands on. `auto` takes any free port the system offers
+- `--asset-port`: a separate origin from the console, as production's asset host is, so a UI cannot reach the console's API
+- `--lan`: to test on a phone or tablet (see below). Without it, only this machine can reach the server
+- `--api-key` and `--host`: default to `SERIOUSGAMING_API_KEY` and `SERIOUSGAMING_API_HOST`, from the environment or `.env`. The host defaults to `https://app.businesssimulations.com`
+- `--teams` and `--scenario`: see below
+- `--participants`: zero is allowed. Without it, each team gets one, or the game's `perTeam.minParticipants`
+- `--fake-clock`: moved with [`sdk clock advance`](#the-tick-timer)
+- `--reinit-on-change`: however far play has gone, rather than holding the edit as pending (see [What reloads](#what-reloads)). The console shows a short 'Settings changed, game restarted' notice each time. The hosted builder starts the dev server this way
+- `--isolated`: for a test run or a recording (see below)
+
+A package holds one session, so a second `sdk dev` for the same package is refused whatever port it asks for, and names the one already running. Stop that one with `sdk dev stop` to move it elsewhere, or start the second with `--isolated`.
+
+The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated`.
+
+### Run a second server beside your own
+
+```bash
+pnpm run sdk dev --isolated --port auto --no-open
+# ✓ Dev server running at http://localhost:53712
+#   Game surfaces are served from http://localhost:53714
+
+SERIOUSGAMING_DEV_URL=http://localhost:53712 pnpm run sdk tick
+```
+
+`--isolated` starts a server that touches nothing of the one you are working in, so an end-to-end run, a walkthrough recording or a clip capture does not need yours stopped:
+
+- **No lock file.** It neither reads nor writes `.seriousgaming-sdk/session.json`, so it starts whatever is running, and a CLI command reaches it only through `SERIOUSGAMING_DEV_URL`
+- **Configuration from the package alone.** It neither reads nor writes `.seriousgaming-sdk/configuration.json`, so what you last ran `sdk configure` with does not leak into a test
+- **Temporary uploads.** Blobs go to a temporary directory, removed when the server stops
+
+Pair it with `--port auto` so it never collides with yours. To start one from a test runner without spawning the CLI, use [`startDevServer`](./guides/testing.md#a-dev-server-for-browser-tests).
+
+**Several teams.** Start with N teams, each at its own URL:
+
+```bash
+pnpm run sdk dev --teams 3
+# Team 1, first player: http://localhost:3000/team/1/player/1
+# Team 2, first player: http://localhost:3000/team/2/player/1
+# Team 3, first player: http://localhost:3000/team/3/player/1
+# The console, which shows the session UI: http://localhost:3000/
+# A link to hand out, which asks who you are: http://localhost:3000/team/1/join
+```
+
+The setup screen, for a game with a `setup` slot, is at `/setup`: the console opens there while the session is at its configuration step. The scenario editor is at `/scenario-editor`, opened on one scenario from the dev drawer's **Scenario** tab.
+
+Without `--teams`, the dev server starts with `teams.min` teams when the game sets it above one. A `--teams` count below `teams.min` or above `teams.max` is refused rather than adjusted. Once the session is running, teams can be added up to `teams.max` and removed down to one. See [Multi-team games](./guides/multi-team-games.md).
+
+Every surface has its own URL, and `?bare` drops the dev chrome from any of them. [Surfaces and their URLs](./cli-and-dev-server.md#surfaces-and-their-urls) lists them all.
+
+**On a phone or tablet.** The dev server listens on `localhost` only, so nobody else on a shared network, such as an office, an event or a café, can reach it. To open a surface on another device, start it with `--lan`:
+
+```bash
+pnpm run sdk dev --lan
+# ⚠ Listening on your network (--lan). Anyone on the same network can open this
+#   session, use its API and read your package files. Use it only on a network you trust.
+#   On another device, open:
+#     http://192.168.1.157:3000
+```
+
+Every port the server opens, the console's, the asset origin's and Vite's hot-reload socket, then listens on every interface. Add the surface's path to the printed address, for example `http://192.168.1.157:3000/team/1/player/1`. The device must be on the same network, and a firewall on this machine may still need to allow the ports.
+
+**A scenario.** Start with a scenario's settings overrides and assets:
+
+```bash
+pnpm run sdk dev --scenario hard_mode
+```
+
+Without `--scenario`, the game's default scenario is used if it has one. Scenario assets are served at `/api/scenario/assets/*`. See [Scenarios](./guides/scenarios.md).
+
+### Manage the background server
+
+```text
+pnpm run sdk dev status [options]
+```
+
+Report whether a dev server is running for this package, and where.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+
+```text
+pnpm run sdk dev stop [options]
+```
+
+Stop the dev server running for this package.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+
+`dev status` and `dev stop` report through the [envelope](#json-output) with `-j, --json`, like every command.
+
+### Dev server features
+
+- **Hot reloading**: edit logic, bundles, the manifest or UIs and see the change without a restart (see [What reloads](#what-reloads))
+- **The dev drawer**: press the backtick key on any surface for the session, the scenario, the surface list, the state projection, armed faults, and errors (see [The dev drawer](./cli-and-dev-server.md#the-dev-drawer))
+- **One command set**: everything the drawer does, the CLI does, because both send the same commands
+- **Direct addressing**: every surface has a URL, and `?bare` removes the dev chrome
+- **Fault injection**: arm an outcome the dev server cannot otherwise produce, so the path your UI handles is reachable
+- **Several teams**: run N teams at once with `--teams N`, or from `teams.min`
+
+### What reloads
+
+Every edit falls into one of three buckets. Knowing which saves guessing at why an edit appears to do nothing.
+
+**Live: applied straight away, keeping the session where it is.**
+
+| You edit                                                                                                               | What happens                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| A user interface (`ui/src/**`)                                                                                         | Vite hot-replaces the UI                                                                                                                        |
+| Resource logic (`engine/logic.ts`, `tick_controller/logic.ts`, or `logic.ts` in `hooks/`, `validators/`, `endpoints/`) | The next run uses the new code. Ticks already played are not re-run                                                                             |
+| A resource bundle (`*.sdk.json`)                                                                                       | The session uses it from the next operation. A bundle that does not load is reported and the last good one stays in use                         |
+| A new surface, such as a `waiting_room/` or `presentation/` slot                                                       | Served at its URL as soon as its bundle is saved                                                                                                |
+| A new capability, or one a resource starts to read or write                                                            | Every team's board gets it with its schema defaults. `Init` has not run for it, and the dev server says so: run `sdk init` to start from `Init` |
+| `locales` or `supportedLocales` in `seriousgaming.sdk.json`                                                            | The session uses them from the next operation                                                                                                   |
+| Scenario or facilitator-guide markdown, or an asset file                                                               | The new content is served on the next request                                                                                                   |
+| A colocated test (`*.test.ts`, `*.spec.ts`)                                                                            | Nothing. Tests are not part of a logic bundle                                                                                                   |
+
+**Pending until `sdk init`: applied when the session next initialises.** These reach the game through `Init` or session creation, so applying them mid-session would give a state no real session can reach, such as a setting `Init` used keeping its old effect while the next tick reads the new value.
+
+- A settings resource's values, including a default or a scenario's override
+- `maxTicks`, `teams` and `waitingRoom.openOnStart` in `seriousgaming.sdk.json`, which are the game's own values for the built-in `game` settings, and `teams.mode` and `identifier`
+- Adding or removing the `setup` slot, which decides whether there is a configuration step
+- Removing a capability, or changing its `scope`
+
+What happens to a pending change depends on whether anything has been played:
+
+- **At tick 0**, nothing has been played, so the session re-initialises on its own and applies it
+- **Once a tick has been played**, the session keeps running on what it started with and records the change. The console shows 'Settings changed: re-initialise to apply' with a **Re-initialise** button. `sdk tick`, `sdk undo`, a context patch, a writing endpoint call and resuming the tick timer are refused with `SETTINGS_STALE` (exit 4) until you re-initialise, with a hint to run `sdk init`. `sdk view` still answers, with `stale` in its data naming what changed and a warning on stderr. Reads, roster and team changes, and the waiting room are unaffected
+- **Under `sdk dev --reinit-on-change`**, the session always re-initialises, however far play has gone
+
+Re-initialising from the console's button keeps the team count, the scenario and the locale, and returns play to tick 0. So does a session-wide reset. `sdk init` rebuilds the session from the package and takes `--teams`, `--scenario` and `--locale` as usual. Editing the file back to what the session started with clears the pending change.
+
+**Needs a restart.** Only an upgrade of the SDK tools themselves. A command notices one (see [A server from other tools](#where-the-session-lives)): it replaces a server it started in the background, and otherwise asks you to stop yours with `sdk dev stop` and start it again.
+
+A UI that throws while it first loads cannot be hot-replaced, because there is no mounted component left to replace. The dev server reloads its frame on the next edit to any file it uses instead, so fixing the mistake is all it takes, though anything typed into the surface is lost with the reload.
+
+The dev server watches the package directory and nothing outside it, so logic code in a linked workspace dependency is not watched: an edit there reaches the next run once a source file in the package changes. A UI is different, because its files are Vite's to watch, and Vite follows a linked dependency a UI imports and hot-replaces it like an edit under `ui/src/`. A logic edit changes the next run, not the ticks already played or the context `Init` built: undo and tick again to see a change applied from the same starting point, or reset to run the new `Init`.
+
+## Project commands
+
+### Create a package
+
+```text
+pnpm run sdk new package [definition] [options]
+```
+
+Create a new package.
+
+| Option                     | Default               | Description                                              |
+| -------------------------- | --------------------- | -------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to create the package in.          |
+| `-f, --file [PATH]`        |                       | Path to a JSON file containing the package definition.   |
+| `--empty`                  |                       | Skip the starter game: package files and CLAUDE.md only. |
+| `--skip-install`           |                       | Skip running pnpm install after creating the package.    |
+
+```bash
+pnpm dlx @seriousgaming/sdk-tools new package
+```
+
+Scaffolds the package structure and `seriousgaming.sdk.json`. It runs interactively by default, and also accepts a JSON definition as an argument, via `--file`, or on stdin. The `pnpm run sdk` script exists only once a package has been scaffolded, so this first command goes through `pnpm dlx`.
+
+What it writes is a complete, playable game, not an empty shell: an engine, a game UI, a session UI, a waiting room UI, a validator, a `participantJoin` hook, a facilitator guide, five capabilities, four settings resources, two scenarios, and tests at every level. It is the game the SDK's own test suites play, copied out verbatim apart from the game's name. See [A tour of the starter game](./guides/starter-game.md) for what it is and why.
+
+`--empty` writes the package files and the agent guidance (`CLAUDE.md`, `.claude/`) alone: no game resources or tests.
+
+### Resolve configuration
+
+```text
+pnpm run sdk resolve [options]
+```
+
+Resolve the package to its built manifest and print it to stdout.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+
+Prints the complete resolved package: every resource it declares, settings resources included.
+
+### Generate types
+
+```text
+pnpm run sdk generate [options]
+```
+
+Generate code from capabilities and the engine.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+
+Regenerates the typed `types.ts` beside each resource that has logic or a user interface, from the capabilities and bundles the package declares. `new`, `update`, and `build` already run it, so reach for it after editing a `*.sdk.json` file by hand.
+
+### Lint
+
+```bash
+pnpm run lint
+pnpm run lint:fix
+```
+
+`lint` checks code for style and quality issues, and `lint:fix` fixes what it can. Use the `lint:fix` script rather than `pnpm run lint -- --fix`: pnpm passes the `--` through, so `oxlint` reads `--fix` as a path and lints nothing.
+
+## Build and publish commands
+
+### Build the game
+
+```bash
+pnpm run build
+```
+
+```text
+pnpm run sdk build [options]
+```
+
+Build your Serious Gaming package, or just its engine.
+
+| Option                     | Default                  | Description                                                                                           |
+| -------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `-c, --config [PATH]`      | `seriousgaming.sdk.json` | The Serious Gaming SDK config file to load.                                                           |
+| `-w, --working-dir [PATH]` | the current directory    | The working directory to execute in.                                                                  |
+| `-b, --build-dir [PATH]`   | `dist/`                  | The directory to write build artefacts to.                                                            |
+| `--validate-only`          |                          | Run validation checks without building (checks logic files, capability references, game composition). |
+
+Run in the package directory. Validates the package, generates types, and builds the engine and UIs for deployment. A top-level `shared-assets/` directory (if present) is copied verbatim into the build root as `dist/shared-assets/`, so `shared:<path>` references resolve against the built package. See [Share assets across scenarios](./recipes/share-assets-across-scenarios.md).
+
+`--validate-only` is described below. With `--json`, the [envelope](#json-output)'s `data` under `--validate-only` is the validation summary (`success`, `resources`, `summary`); a failure is `PACKAGE_INVALID` (exit 3) with a diagnostic per finding. `--verbose`, the [global option](#global-options), shows detailed build progress.
+
+### Validate the package
+
+```bash
+# Human-readable validation output
+pnpm run sdk build --validate-only
+
+# Structured JSON output for automation
+pnpm run sdk build --validate-only --json
+```
+
+Runs every validation check without building:
+
+- Engine logic files exist and export `Init` and `Run`
+- UI entrypoint files exist
+- Capability references resolve correctly
+- Game composition (settings and locales)
+- Every `settings` entry names a settings resource the package declares, and so does the `configures` of the setup and scenario editor slots
+- Every settings property declares a `default`, and no `settingsSchema` declares a top-level `required`
+- No bundle carries a `configurationSchema`, and the manifest carries no `configuration` block
+- Scenario settings overrides against each settings resource's `settingsSchema` (see [Scenario settings](#scenario-settings))
+- Every schema `default` satisfies the subschema that declares it (see [Schema defaults](#schema-defaults))
+
+It also warns, without failing, when a resource reads a capability that **nothing in the package writes**. Such a read can only ever see the capability's schema defaults, so it is usually a leftover from a deleted writer, or a set of constants that belongs in a [settings resource](./guides/settings.md) instead. The check is package-wide, so a capability written anywhere is never flagged.
+
+#### Scenario settings
+
+A scenario's `settings` block is keyed by settings identifier, and each entry is checked against that settings resource's `settingsSchema`. An entry naming a settings resource the package does not declare fails too. This is the check the dev server and the production runtime make when a scenario is activated, brought forward to build time.
+
+Overrides are **partial**: a scenario that sets only the keys it cares about is fine, and omitted keys fall through to their defaults. What fails the build is a key the schema does not declare (usually a misspelling), or a declared key whose value violates the schema.
+
+```json
+"settings": {
+    "engine": {
+        "BaseDemand": 15000,
+        "DemandPriceModifer": 300
+    }
+}
+```
+
+`DemandPriceModifer` is a typo, so the build fails and names it, rather than the scenario failing at session start.
+
+#### Schema defaults
+
+A `default` must be a valid instance of the subschema that declares it. Defaults seed the initial context (`variablesSchema`) and the resolved settings (`settingsSchema`), so one that violates its own schema puts invalid state into the game before any logic runs. Validation covers `variablesSchema`, `settingsSchema`, and an endpoint's `requestSchema` and `responseSchema`, at any depth.
+
+The common trap is an object default that carries a field the subschema does not declare:
+
+```json
+"Company": {
+    "type": "object",
+    "properties": { "Name": { "type": "string" } },
+    "required": ["Name"],
+    "additionalProperties": false,
+    "default": { "Name": "Acme", "Tagline": "We deliver" }
+}
+```
+
+`Tagline` is not declared and `additionalProperties` is `false`, so the default can never validate. Either declare `Tagline` or drop it from the default.
+
+Also flagged: a default of the wrong type, one outside a declared `enum`, `minimum`, `maximum`, or `pattern`, and one that omits a field its own object marks `required`. A default is used **whole** when its key is absent, not merged with anything, so a partial object default seeds an incomplete value.
+
+> A value that is only legitimate before your logic first writes the capability still has to be in the schema. If a status starts as `'Unknown'` and your engine later sets it to one of four ratings, `'Unknown'` belongs in the `enum` too, otherwise the generated union misrepresents what the capability holds at tick 0.
+
+### Build the engine on its own
+
+```text
+pnpm run sdk build engine [options]
+```
+
+Build the engine and output to stdout.
+
+| Option                     | Default                  | Description                                 |
+| -------------------------- | ------------------------ | ------------------------------------------- |
+| `-c, --config [PATH]`      | `seriousgaming.sdk.json` | The Serious Gaming SDK config file to load. |
+| `-w, --working-dir [PATH]` | the current directory    | The working directory to execute in.        |
+
+Transpiles the engine's TypeScript logic and writes the bundled JavaScript to stdout, without producing a `dist/`. Useful for inspecting what the engine actually runs, or for piping into another tool.
+
+It takes no argument: a game holds one engine, in the `engine` slot. The command fails when the slot is empty.
+
+**Example:**
+
+```bash
+CODE=$(pnpm run --silent sdk build engine)
+```
+
+### Package a built game for distribution
+
+```text
+pnpm run sdk package bundle [options]
+```
+
+Package the built `dist/` directory into a distributable zip archive.
+
+| Option                     | Default               | Description                               |
+| -------------------------- | --------------------- | ----------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.      |
+| `-b, --build-dir [PATH]`   | `dist/`               | The directory containing build artefacts. |
+| `-o, --output-file [PATH]` |                       | Where to write the zip archive.           |
+
+Wraps the contents of a built `dist/` directory into a single zip archive for uploading to a production runtime. Run it after `pnpm run sdk build`; it does not build.
+
+The archive root mirrors the build layout, with `seriousgaming.json` at the top and any `shared-assets/` directory included once at the root. See [Distribute a built package](./recipes/distribute-package.md) for a CI recipe.
+
+`--output-file` defaults to `<build-dir>/<identifier>-<version>.zip`. With `--json`, the [envelope](#json-output)'s `data` is `outputFile`, `size`, `fileCount`, `identifier` and `version`.
+
+**Example:**
+
+```bash
+pnpm run sdk build
+pnpm run sdk package bundle
+# → dist/coffeeshop-1.2.0.zip
+
+pnpm run --silent sdk package bundle --json > bundle.json
+```
+
+### Set the package version
+
+```text
+pnpm run sdk package version <value> [options]
+```
+
+Set the package version in package.json, which owns it.
+
+| Option                     | Default               | Description                          |
+| -------------------------- | --------------------- | ------------------------------------ |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
+
+Sets the package's version in `package.json`, which owns it. The manifest carries no version; the build reads it from here and writes it into the built artefact. Useful in CI to bump the version before `package bundle`, since production runtimes typically reject a re-upload of the same identifier and version.
+
+`<value>` is either a literal semver string (such as `1.2.3` or `1.2.3-rc.1`) or one of the bump keywords `patch`, `minor`, `major`, and `prerelease`. The new version is validated against the same pattern `schema.json` enforces on `PackageDefinition.version`. The command does not run `git tag` or `git commit`; leave tagging to CI.
+
+**Bump keywords:**
+
+- `patch`: `1.2.3` becomes `1.2.4`
+- `minor`: `1.2.3` becomes `1.3.0`
+- `major`: `1.2.3` becomes `2.0.0` (drops any existing pre-release)
+- `prerelease`: on a stable version, bumps patch and appends `-0` (`1.2.3` becomes `1.2.4-0`); on an existing pre-release, increments a trailing numeric identifier (`1.2.3-rc.1` becomes `1.2.3-rc.2`) or appends `.0` when the trailing identifier is alphanumeric (`1.2.3-rc` becomes `1.2.3-rc.0`)
+
+With `--json`, the [envelope](#json-output)'s `data` is `previous`, `next` and `files`.
+
+**Example:**
+
+```bash
+pnpm run sdk package version 1.4.2
+pnpm run sdk package version patch
+pnpm run --silent sdk package version prerelease --json > version.json
+```
+
+### Publish a package to the Serious Gaming platform
+
+```text
+pnpm run sdk package publish [zip] [options]
+```
+
+Upload a built and bundled package to the Serious Gaming platform.
+
+| Option                     | Default               | Description                                                                                                                                                                                                           |
+| -------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in.                                                                                                                                                                                  |
+| `-b, --build-dir [PATH]`   | `dist/`               | The directory containing build artefacts.                                                                                                                                                                             |
+| `--host [URL]`             |                       | Origin to upload to, e.g. https://app.businesssimulations.com (defaults to SERIOUSGAMING_API_HOST env var or https://app.businesssimulations.com). The CLI appends `/api/v0/admin/publishers/<slug>/packages` itself. |
+| `--api-key [KEY]`          |                       | API key (defaults to SERIOUSGAMING_API_KEY env var or .env file).                                                                                                                                                     |
+| `--publisher [SLUG]`       |                       | Publisher slug to upload under (defaults to SERIOUSGAMING_PUBLISHER env var or platform.defaultPublisher in global settings).                                                                                         |
+| `--no-auto-bundle`         |                       | Fail rather than re-bundle when the zip is missing.                                                                                                                                                                   |
+
+Uploads a built and bundled package zip to the Serious Gaming platform through the `/api/v0/admin/publishers/<slug>/packages` endpoint. It reads the identifier from `seriousgaming.sdk.json` and the version from `package.json`, locates `<build-dir>/<identifier>-<version>.zip`, and POSTs it as `multipart/form-data` with field `body` and an `Authorization: Bearer <key>` header. The key must come from an account with publishing access, which Business Simulations grants.
+
+When the bundle is missing, the command runs `package bundle` first. Pass `--no-auto-bundle` to fail instead, or an explicit `[zip]` argument to upload that file without re-bundling.
+
+**Publisher.** The upload is scoped to a publisher, resolved from (highest priority first) the `--publisher` flag, the `SERIOUSGAMING_PUBLISHER` environment variable, then `platform.defaultPublisher` in the [global settings file](./guides/global-settings.md). If none resolves, the command fails with guidance rather than guessing. The first upload of a package binds it to the named publisher; later versions must be uploaded under the same publisher or the platform returns a 400.
+
+**API key.** The CLI looks up `SERIOUSGAMING_API_KEY` in the standard precedence order: global settings file, then `.env` file, then `process.env`, then the `--api-key` flag, each overriding the one before. Keep the key in your `.env`, shell environment, or global settings so it stays out of shell history.
+
+`--host` takes an origin only, not a full path. With `--json`, the [envelope](#json-output)'s `data` is the server's `PackageVersionResponse`.
+
+The environment variables it reads are listed in [Environment variables](./environment-variables.md#package-publishing-pnpm-run-sdk-package-publish).
+
+**Examples:**
+
+```bash
+# Default: bundle if needed, upload to production under the named publisher
+pnpm run sdk package publish --publisher acme
+
+# Upload an explicit zip without re-bundling
+pnpm run sdk package publish artifacts/release.zip --publisher acme
+
+# Target a staging environment
+pnpm run sdk package publish --host https://staging.example.com --publisher acme
+
+# Capture the server response for CI
+pnpm run --silent sdk package publish --json > publish.json
+```
+
+**Errors:**
+
+- `400` (`PLATFORM_REJECTED`, exit 3): each structured validation error (`{field, message}`) in the server's `errors[]` array is rendered as `field: message` on its own line. A version uploaded against the wrong publisher surfaces here
+- `401` and `403` (`PLATFORM_UNAUTHORISED`, exit 5): 'Invalid API key. Check $SERIOUSGAMING_API_KEY and that it has not been revoked.', or 'The account that created this API key does not have publishing access. Ask Business Simulations to grant it.'
+- `409` (`VERSION_EXISTS`, exit 3): 'Version {x.y.z} of {identifier} already exists. Bump it with `seriousgaming-sdk package version patch` and try again.'
+- Any other status (`PLATFORM_ERROR`, exit 5)
+- Network errors (`PLATFORM_UNREACHABLE`, exit 5) are surfaced with the original message
+- No API key (`API_KEY_MISSING`, exit 5), or no publisher (`PUBLISHER_MISSING`, exit 2)
+
+## Global settings
+
+The `config` commands read and write the global settings file at `~/.seriousgaming-sdk/config.json`. It stores API keys and defaults once so every project picks them up, instead of re-exporting environment variables in each shell.
+
+The file is the lowest-priority configuration source: a `.env` file, environment variables, and CLI flags all override it. See the [global settings guide](./guides/global-settings.md) for the full file shape, precedence rules, and security guidance.
+
+The available keys are `elevenLabs.apiKey`, `platform.apiHost`, `platform.apiKey`, and `platform.defaultPublisher`.
+
+### Get a setting
+
+```text
+pnpm run sdk config get <key>
+```
+
+Print the value of a setting.
+
+Prints the value of a single setting, or nothing if the key is valid but unset.
+
+```bash
+pnpm run sdk config get platform.apiKey
+```
+
+### Set a setting
+
+```text
+pnpm run sdk config set <key> <value>
+```
+
+Set a setting in the global settings file.
+
+Writes a single setting, creating the file (with owner-only permissions on macOS and Linux) if it does not exist.
+
+```bash
+pnpm run sdk config set platform.apiKey sg_...
+```
+
+### Print the settings path
+
+```text
+pnpm run sdk config path
+```
+
+Print the resolved path to the global settings file.
+
+Prints the resolved path to the global settings file. Honours the `SERIOUSGAMING_SDK_CONFIG` override.
+
+## Help and documentation
+
+### Command help
+
+```bash
+pnpm run sdk --help
+pnpm run sdk <command> --help
+```
+
+Shows the available commands and their options.
+
+### Print the SDK version
+
+```text
+pnpm run sdk version
+```
+
+Print the SDK version to stdout.
+
+```bash
+pnpm run --silent sdk version
+```
+
+Prints the installed SDK version to stdout.
+
+### Browse the documentation
+
+```text
+pnpm run sdk docs view [file]
+```
+
+View Serious Gaming SDK documentation.
+
+```text
+pnpm run sdk docs export [dir]
+```
+
+Export SDK documentation to your project.
+
+The docs ship inside the package at `node_modules/@seriousgaming/sdk-tools/dist/docs`, so they match the installed version and need no network. Search them with your editor or `grep`.
+
+- `docs view` with no argument prints the tree of documents; with a path (for example `guides/engine.md`) it prints that document
+- `docs export` copies every document to `dir`, or `.seriousgaming-sdk/docs` by default, so an editor or agent can search them locally
+
+## Environment variables
+
+LLM access, speech, publishing, the global settings path, the port a background dev server starts from, the server session commands target (`SERIOUSGAMING_DEV_URL`), where the lock file lives (`SERIOUSGAMING_DEV_STATE_DIR`), and JSON output (`SERIOUSGAMING_JSON=1`) are all set through environment variables. [Environment variables](./environment-variables.md) lists every one. Logging is `--verbose`, a flag only.
+
+## Next steps
+
+- [Drive a game from the CLI](./cli-simulation-testing.md): the session commands as one workflow
+- [Getting started](./getting-started.md): your first game
+- [Guides](./guides/index.md): each resource type and topic in depth
+- [Troubleshooting](./troubleshooting.md): symptoms, causes, and fixes