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

package/dist/docs/guides/upgrading.md

@@ -0,0 +1,636 @@
+# Upgrading from 0.6 to 1.0
+
+This guide takes a game package on 0.6 to 1.0, in 13 steps. Each step names what breaks and what to do about it. Step 1 renames the packages, so nothing compiles again until the end.
+
+The steps are grouped by topic, not in the quickest order. Until the package loads, every CLI command reports what later steps have not fixed yet, so most games go fastest like this:
+
+1. Make every edit that gets the package loading, in one pass: step 1, the bundle files and directories in step 2 (2a, 2b, 2c, 2e and 2g), step 3's moves, 7a and step 8
+2. Run `pnpm run sdk generate`
+3. Let `pnpm run typecheck` drive the rest: 2d and steps 4, 5, 6 and 10. One or two runs list everything
+4. Search by hand for the changes no tool sees (below), then verify with step 13
+
+Read your installed version first:
+
+```bash
+cat node_modules/@businesssimulations/seriousgaming-sdk/package.json | grep '"version"'
+```
+
+If it is earlier than 0.6.0, upgrade to 0.6 first with the upgrading guide that ships inside 0.6.0 (`node_modules/@businesssimulations/seriousgaming-sdk-tools/dist/docs/guides/upgrading.md` once 0.6 is installed). The history of every 0.x release is in the [0.x changelog](../changelog-0.x.md).
+
+Most steps are mechanical and the compiler finds what they break. **These changes compile, build and pass unit tests while wrong**, so search for each by hand:
+
+- Timer durations in milliseconds ([step 6c](#6c-timers-in-milliseconds))
+- `caller.teamId` meaning the caller's own team ([step 7d](#7d-read-the-target-team-from-team))
+- `null` no longer standing in for a removed entry ([step 4c](#4c-remove-entries-with-deletes-not-null))
+- A session UI reading shared state through a team, behind a hand-written type or a cast ([step 5b](#5b-session-uis))
+- Logic changing a capability outside its `writes`, and a per-team `Init` or `Run` writing a shared capability: both fail only on the call that changes the value ([step 9](#step-9-meet-what-the-build-and-runtime-now-enforce))
+- A surface retrying a `conflict` on its own ([step 9](#step-9-meet-what-the-build-and-runtime-now-enforce))
+- A test calling an endpoint with `uiIdentifier: ''`, which is now refused ([step 10a](#10a-move-off-gamerunner))
+- Code that reads scenario files itself and still looks for `configuration` ([step 2c](#2c-rename-scenario-configuration-to-settings))
+
+The [changelog](../changelog.md) carries the detail behind every step.
+
+## Step 1: rename the packages
+
+The three public packages move to the `@seriousgaming` scope on the public npm registry, and install without a token. Their subpaths are unchanged, and so is the `seriousgaming-sdk` command, so `pnpm run sdk` keeps working.
+
+| Before                                         | After                      |
+| ---------------------------------------------- | -------------------------- |
+| `@businesssimulations/seriousgaming-sdk-tools` | `@seriousgaming/sdk-tools` |
+| `@businesssimulations/seriousgaming-sdk`       | `@seriousgaming/sdk`       |
+| `@businesssimulations/seriousgaming-deck`      | `@seriousgaming/deck`      |
+
+1. In `package.json`, rename the dependencies and set each to the 1.0 version. Keep the SDK, the tools and the deck at one version. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency at the same version
+2. Replace the names everywhere else, in the order of the table so the SDK's name does not rewrite the start of the tools' name: every import (logic, surfaces, tests), `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`, `oxlintrc.json`, `testing/e2e/global-setup.ts` if you have one, `CLAUDE.md`, `.claude/rules/` and `README.md`. Then run your formatter: the new names sort differently, so every `package.json` and sorted import block changes
+3. Remove the `@businesssimulations:registry=https://npm.pkg.github.com` line, and the token beside it, from `.npmrc` and from CI, unless something else you install still comes from there
+4. In `pnpm-workspace.yaml`, delete the `sharp` and `protobufjs` overrides. They held back dependencies of `@xenova/transformers`, which left with `docs ask` (step 11), so nothing installs either package any more. Delete anything else you added for it too, such as `minimumReleaseAgeExclude` or `allowBuilds` entries for `@xenova/transformers` or `onnxruntime-node`
+5. If you depend on `@seriousgaming/deck`, add `image-size: '>=2.0.3'` under `overrides:` (it clears an advisory reached through the deck's PowerPoint export). A game without the deck does not need it
+6. Run `pnpm install`, then `pnpm update -r` so the dependencies your lockfile already holds reach their patched versions, then `pnpm audit`
+
+```bash
+grep -rn --exclude-dir=node_modules --exclude-dir=dist '@businesssimulations/seriousgaming-' .
+```
+
+The SDK and the deck are now Apache-2.0. The tools are under the Serious Gaming SDK Tools Licence in their `LICENSE` file; what they generate or copy into your project is yours under Apache-2.0.
+
+## Step 2: move configuration into settings resources
+
+A game's parameters now live in settings resources, `settings/<name>/settings.sdk.json`, rather than in a `configurationSchema` on each bundle. A resource lists the settings it reads in `settings`, as `reads` names capabilities, and receives exactly those, keyed by settings identifier. Any resource may read any settings resource. The game-level `configuration` block goes too: a game edits its own defaults. Settings are fixed when play starts. See [Settings](./settings.md) for the model.
+
+### 2a. Move each `configurationSchema` into a settings resource
+
+The build refuses a bundle that still carries one:
+
+```
+`configurationSchema` has been removed. Move these properties into a settings resource (`pnpm run sdk new settings`), and list it in this resource's `settings`.
+```
+
+For each bundle that has one, create `settings/<slot>/settings.sdk.json` holding the same schema under `settingsSchema`, delete the `configurationSchema`, and list the new resource in the bundle's `settings`. Naming each after the slot it came from (`engine`, `ui`, `session`, `waiting_room`, `tick_controller`, or the hook's or validator's own name) keeps every scenario override's key the same.
+
+Before, `engine/engine.sdk.json`:
+
+```json
+{
+    "definition": {
+        "reads": ["stall", "plan"],
+        "writes": ["stall", "plan"],
+        "configurationSchema": {
+            "type": "object",
+            "properties": {
+                "Capacity": { "type": "number", "default": 100, "minimum": 1 }
+            },
+            "required": ["Capacity"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+After, `engine/engine.sdk.json` lists `"settings": ["engine"]` in place of the schema, and `settings/engine/settings.sdk.json` holds it:
+
+```json
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "Capacity": { "type": "number", "default": 100, "minimum": 1 }
+            },
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+Two rules are stricter than before. Every property needs a `default`, and a top-level `required` is refused, since every property always has a value. Delete the `required` array, and give any property without a default one (`"type": ["string", "null"]` with `"default": null` for a value that may be absent).
+
+**An empty `configurationSchema` fails the build too.** A bundle carrying `"configurationSchema": { "type": "object", "properties": {} }` is refused with the same message, though there is nothing to move. Delete the block:
+
+```bash
+grep -rln '"configurationSchema"' --include='*.sdk.json' .
+```
+
+### 2b. Fold the game-level `configuration` block into the defaults
+
+`seriousgaming.sdk.json` may no longer carry a `configuration` block, and the build refuses it. Move each value into the `default` of the matching settings property, then delete the block.
+
+### 2c. Rename scenario `configuration` to `settings`
+
+A scenario's overrides move from `definition.configuration` to `definition.settings`, still keyed by settings identifier, and the build refuses the old field. A configuration UI's `configures`, `sdk configure` overrides and `.seriousgaming-sdk/configuration.json` are keyed by settings identifier as well. If you named each settings resource after its slot in 2a, only the field name changes; otherwise rename each key to the settings resource that now holds the values.
+
+The CLI can move the field, one scenario at a time:
+
+```bash
+pnpm run sdk update scenario short --patch '[{"op":"move","from":"/definition/configuration","path":"/definition/settings"}]'
+```
+
+Code that reads scenario files itself, such as a test that loads one or a script that generates them, still looks for `configuration` and keeps compiling, so a test can pass while checking nothing. Search for it:
+
+```bash
+grep -rn "configuration" testing scripts
+```
+
+### 2d. Read `settings` rather than `config`
+
+| Where                          | Before                                                             | After                                                                  |
+| ------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Engine, hooks, tick controller | `async ({ context, config }) => ...`                               | `async ({ context, settings }) => ...`                                 |
+| A read in logic                | `config.Capacity`                                                  | `settings.engine.Capacity`                                             |
+| Validators                     | `({ previous, next, actor, config, meta })`                        | `({ previous, next, actor, settings, meta })`                          |
+| Endpoints                      | `Handle({ request, context, ... })`                                | `Handle({ request, context, settings, ... })`                          |
+| Type imports                   | `import type { Context, Config } from './types'`                   | `import type { Context, Settings } from './types'`                     |
+| Function types                 | `RunFunction<Context, Config>`, `ModuleFunctionArgs`               | `RunFunction<Context, Settings>`, `LogicFunctionArgs`                  |
+| Game and waiting room UIs      | `const { data, config } = useUserInterfaceData<Context, Config>()` | `const { data, settings } = useUserInterfaceData<Context, Settings>()` |
+| Session UI                     | `useSessionUserInterfaceData<SessionData, Config>()`               | `useSessionUserInterfaceData<SessionData, Settings>()`                 |
+| Test fixtures                  | `import { defaultConfig } from './defaults'`                       | `import { defaultSettings } from './defaults'`                         |
+| Component tests                | `renderUserInterface(<App />, { config: { MaxPrice: 10 } })`       | `renderUserInterface(<App />, { settings: { ui: { MaxPrice: 10 } } })` |
+
+```typescript
+import type { RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    const capacity = settings.engine.Capacity;
+    // ...
+    return { capabilities: { ...context } };
+};
+```
+
+Settings arrive keyed by settings identifier (`settings.ui.MaxPrice`), where `config` was flat (`config.MaxPrice`). The generated types catch every typed read, but two kinds of code escape them:
+
+- **Component tests that pass no settings.** A test that rendered with no `config` now throws on the first `settings.ui.X` read. Pass `defaultSettings`, or the keyed values the test needs
+- **Untyped helpers and props.** A test harness or component that takes settings as a loose object, or a `config` prop passed by shorthand, keeps compiling with the old flat shape. Type each with the generated `Settings`
+
+### 2e. Rename a capability called `settings`
+
+A capability named `settings` now collides with the `settings` argument. Code that destructures both, such as `async ({ context, settings }) => { const { settings } = context; ... }`, or `const { data, settings } = useUserInterfaceData()` beside a read of `data.settings`, fails to compile or silently reads the wrong one. Such a capability usually holds configuration copied into context at `Init`: replace it with a settings resource (2f). If it holds state that changes during play, rename it, which moves its directory and rewrites every reference in the package's bundles, then rename the reads in your code:
+
+```bash
+pnpm run sdk update capability settings --patch '[{"op":"add","path":"/definition/identifier","value":"game_state"}]'
+```
+
+### 2f. Delete the copies of configuration in context
+
+Optional, and worth doing. A game that copied configuration into a capability at `Init`, so that a UI, hook or validator could read it, can list the settings resource on that reader instead, then delete the `Init` step, the capability and the reader's `reads` entry. Keep a capability where the value changes during play. Keep any value participants must not see, such as an answer key, in a settings resource only the engine declares.
+
+### 2g. Rename `ticks` to `maxTicks`, and move a scenario's game fields into `settings.game`
+
+The game-level settings (the number of ticks, the team bounds, the participant guidance, the default team names and whether the waiting room opens on start) are now a built-in settings resource called `game`. A game still declares its own values in `seriousgaming.sdk.json`, where they become that resource's defaults, so a scenario and a session's setup override them like any other setting. The build refuses the old fields, naming what replaced each.
+
+In `seriousgaming.sdk.json`, rename `ticks` to `maxTicks`. `teams` and `waitingRoom` stay as they are, and `teams.min`, `teams.max` and the `perTeam` counts must now be whole numbers.
+
+In each scenario, move `ticks`, `teams` and `waitingRoom` into `settings.game`, renaming `ticks` to `maxTicks`. Before:
+
+```json
+{
+    "definition": {
+        "locales": { "en": { "name": "Short" } },
+        "ticks": 4,
+        "teams": { "max": 4 },
+        "settings": { "engine": { "BaseDemand": 120 } }
+    }
+}
+```
+
+After:
+
+```json
+{
+    "definition": {
+        "locales": { "en": { "name": "Short" } },
+        "settings": {
+            "game": { "maxTicks": 4, "teams": { "max": 4 } },
+            "engine": { "BaseDemand": 120 }
+        }
+    }
+}
+```
+
+Find what needs moving:
+
+```bash
+grep -rln '"ticks"' --include='*.sdk.json' .
+```
+
+Three things behave differently once you have:
+
+- **A scenario's `teams.defaultNames` replaces the game's list whole.** It used to fall back to the game's name for a team past the end of the scenario's list. List every name the scenario needs
+- **A presentation reads `game.maxTicks`**, where it read `game.ticks`
+- **A settings resource called `game` is refused** (`SETTINGS_RESERVED`), since the name is the built-in one's. Rename yours, along with every `settings` and `configures` entry that names it
+- **A single-team game locks `teams.max`.** `teams.max: 1` alone no longer makes a game single-team, because a scenario or setup could raise it. An independent game whose engine writes a shared capability fails the build until it adds `"gameSettingsConstraints": { "teams": { "max": { "readOnly": true } } }` beside `teams.max: 1` (see [Narrow or lock the game settings](./settings.md#narrow-or-lock-the-game-settings))
+
+A setup UI or scenario editor can now set the number of rounds: list `game` in its `configures`, and write `updateSettings({ game: { ...settings.game, maxTicks: 6 } })`. A setup cannot set `waitingRoom.openOnStart`, which takes effect before setup runs. See [The game settings](./settings.md#the-game-settings).
+
+## Step 3: move configuration UIs into the setup and scenario editor slots
+
+A configuration UI used to be one resource wired into one or both surfaces through `configurationSurfaces`. Each surface is now its own slot, and the build refuses the old directory and key, naming the slots. See [Setup](./setup.md) and [The scenario editor](./scenario-editor.md).
+
+| Was wired as       | Move `configuration-user-interfaces/<name>/` to | Bundle file                |
+| ------------------ | ----------------------------------------------- | -------------------------- |
+| `quick-config`     | `setup/`                                        | `setup.sdk.json`           |
+| `scenario-builder` | `scenario_editor/`                              | `scenario_editor.sdk.json` |
+| Both               | Both: copy it, then trim each copy to its job   | Both                       |
+
+Rename `configuration-user-interface.sdk.json` to the slot's bundle file, keep `configures` (keyed by settings identifier, step 2c), and delete `configurationSurfaces` from `seriousgaming.sdk.json`. `sdk new configuration-user-interface <name>` is now `sdk new setup` or `sdk new scenario_editor`, with no name. Then rename the code:
+
+| Before                                                                                    | After                                                                                             |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `ConfigurationUserInterfaceWrapper`                                                       | `SettingsEditorWrapper`                                                                           |
+| `useConfigurationUserInterfaceConfig()`, returning `{ config, setConfig }`                | `useSettingsEditor()`, returning `{ settings, updateSettings, configures }`                       |
+| `useConfigurationUserInterfaceTheme`, `…ThemePreference`, `…Locale`, `…Callbacks`         | `useSettingsEditorTheme`, `…ThemePreference`, `…Locale`, `…Callbacks`                             |
+| `ConfigurationUserInterfaceTheme`, `…ModeColors`, `…Locale`, `…Callbacks`                 | `SettingsEditorTheme`, `…ModeColors`, `…Locale`, `…Callbacks`                                     |
+| `useConfigurationUserInterfaceSurface`, `ConfigurationSurface`                            | Removed: each slot is its own bundle                                                              |
+| `renderConfigurationUserInterface({ config, setConfig })`, `createMockConfigurationTheme` | `renderSettingsEditor({ settings, updateSettings, configures })`, `createMockSettingsEditorTheme` |
+| Generated `Config`, `defaultConfig`                                                       | `Settings`, `defaultSettings`                                                                     |
+| `DEV_SERVER.configureUrl()`, `scenarioBuilderUrl()`                                       | `setupUrl()`, `scenarioEditorUrl()`                                                               |
+
+`renderSettingsEditor`'s `settings` is keyed by settings identifier, like everything else in step 2, and its `configures` defaults to the keys of `settings`. A UI that was wired into both surfaces has tests that render it for both: split them with the code.
+
+The configuration step exists exactly when a game has `setup`. `callbacks.requestPlay` is always present there, and the host refuses it from the scenario editor. A game with custom scenarios should also set `"scenarioFormat": 1` in `seriousgaming.sdk.json` (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it)).
+
+## Step 4: return what logic writes under `capabilities`
+
+The engine, hooks and writing endpoints return what they write under a `capabilities` key, rather than as one flat object. The input `context` is unchanged. A result the runtime does not recognise fails the call, naming the key, so a function you miss fails on its first tick rather than losing its writes.
+
+### 4a. Wrap each return
+
+| Function                                | Before                                 | After                                                                      |
+| --------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
+| Engine `Init` and `Run`, a hook's `Run` | `return { ...context, sales }`         | `return { capabilities: { ...context, sales } }`                           |
+| Engine `InitAggregate` / `RunAggregate` | `{ shared: { market }, teams: [ctx] }` | `{ shared: { capabilities: { market } }, teams: [{ capabilities: ctx }] }` |
+| A writing endpoint's `Handle`           | `{ response, context: { price } }`     | `{ response, capabilities: { price } }`                                    |
+
+An early `return context;` in a hook becomes `return { capabilities: context };`. Validators, tick controllers and endpoints that declare no `writes` return what they did before. An engine with no `Init` now starts every team from its capabilities' defaults, so a no-op `Init` can be deleted.
+
+### 4b. Retype engine steps
+
+An engine that splits `Init` or `Run` into several functions typed as `RunFunction` will not compile, because that type now returns `{ capabilities }`. Type the steps as `StepFunction`, which still takes and returns the context flat, and wrap only in the exported function:
+
+```typescript
+import type { RunFunction, StepFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const runSales: StepFunction<Context, Settings> = async ({ context }) => ({
+    ...context,
+    sales: { ...context.sales, Sales: 10 },
+});
+
+export const Run: RunFunction<Context, Settings> = async (args) => {
+    let context = args.context;
+    context = await runProduction({ ...args, context });
+    context = await runSales({ ...args, context });
+    return { capabilities: context };
+};
+```
+
+An aggregate engine split into steps works the same way. There is no step type for it, so type each step over the team and shared contexts the generated `types.ts` exports, and wrap only in the exported function:
+
+```typescript
+import type { RunAggregateFunction } from '@seriousgaming/sdk';
+import type { Settings, SharedContext, TeamContext } from './types';
+
+type Board = { shared: SharedContext; teams: TeamContext[] };
+
+const settleMarket = (board: Board, settings: Settings): Board => ({
+    ...board,
+    shared: { ...board.shared, market: { ...board.shared.market, Open: false } },
+});
+
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    shared,
+    teams,
+    settings,
+}) => {
+    let board: Board = { shared: shared.context, teams: teams.map((team) => team.context) };
+    board = settleMarket(board, settings);
+    return {
+        shared: { capabilities: board.shared },
+        teams: board.teams.map((context) => ({ capabilities: context })),
+    };
+};
+```
+
+A test that calls `Init`, `Run`, a hook or a writing endpoint directly reads one level deeper: `result.sales` becomes `result.capabilities.sales`, and an endpoint's `result.context` becomes `result.capabilities`. Tests through `createTestSession` read session state, so the result shape does not reach them, but its tick fields are renamed ([step 6a](#6a-tick-numbers)).
+
+### 4c. Remove entries with `deletes`, not `null`
+
+Writing `null` never removed anything, and in 1.0 there is a way that does. A UI's `setData` deep-merges its patch, so `setData({ offers: { Open: { [id]: null } } })` leaves the key in the map holding `null`, carried in every broadcast and every snapshot for the rest of the session. A logic result replaces each variable it returns whole, so a `null` there keeps the key too, or clears the whole variable. Code that wrote `null` as a tombstone, and filtered `null` entries out wherever it read the map, should name the entry in `deletes` instead:
+
+```typescript
+// a UI
+await setData({}, { deletes: [`offers.Open.${id}`] });
+
+// the engine, a hook or a writing endpoint
+return { capabilities: { ...context }, deletes: [`offers.Open.${id}`] };
+```
+
+A path is segments joined by `.`, or an array of segments when a key could contain a dot, and must sit under a capability in the writer's `writes`. Then drop the `null` filters, and `null` from the map's value schema if it was there only for tombstones. See [Removing a key](./engine.md#removing-a-key).
+
+A session saved before the upgrade can still hold `null` entries, since nothing removes them. Keep a reader's `null` filter until no such session is left to resume, and only then drop it and the `null` from the schema. Update the capability's `description` too, and any comment beside the map, where it still says a removed entry is written as `null`. Nothing checks a description against the code, so a stale one stays wrong.
+
+```bash
+grep -rnE ":\s*null\b" engine hooks endpoints ui session waiting_room --include='*.ts' --include='*.tsx'
+```
+
+That search finds a literal `null` only. A tombstone can also be computed (`open ? offer : null`, `reset[id] = null`) or written by a helper outside these directories, so search your capability schemas for maps whose values allow `null`, then read every writer of each.
+
+Three more ways to remove an entry:
+
+- **From a session UI.** Its `setData` takes the same option, for a team's capability or a shared one: `setData(teamId, {}, { deletes: [...] })` or `setData({}, { deletes: [...] })`. Each path must sit under a capability in the session UI's `writes`, in the scope it names
+- **From logic, by leaving it out.** A logic result replaces each variable it returns whole, so returning the map without the key removes it too
+- **From an undo stack.** A UI that keeps inverse patches to undo its own edits now records a `deletes` path as the inverse of an added key, and a write of the old value as the inverse of a removal
+
+Returning `null` to clear a variable whose schema allows it still works: that is a value, not a removal.
+
+## Step 5: read shared state from its own channel
+
+The two places that see every team at once, an aggregate engine and a session UI, receive the shared store once, as `shared`, beside `teams`. Each team's context there carries that team's own capabilities only. `Init`, a per-team `Run`, hooks, team-scoped endpoints, game UIs and waiting rooms are unchanged.
+
+### 5a. Aggregate engines
+
+`InitAggregate` and `RunAggregate` take `{ shared, teams, settings, meta, callbacks, participants }`, and are typed with the team and shared contexts the generated `types.ts` exports:
+
+| Before                                                                  | After                                                         |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `RunAggregateFunction<Context, Config>`                                 | `RunAggregateFunction<TeamContext, SharedContext, Settings>`  |
+| `InitAggregateFunction<Context, Config>`                                | `InitAggregateFunction<TeamContext, SharedContext, Settings>` |
+| `teams[0].context.market.AverageMarketPrice`                            | `shared.context.market.AverageMarketPrice`                    |
+| `teams: teams.map((t) => ({ capabilities: { ...t.context, market } }))` | `shared: { capabilities: { market } }`                        |
+
+**Drop every shared capability from the `teams` entries of the result.** One there now fails the init or tick, even when every team carries the same value; return it once, under `shared`. Spreading `...t.context` into a `teams` entry stays safe, because `t.context` no longer carries shared capabilities. In tests, pass `shared: { context: { ...defaultSharedContext } }` and build teams from `defaultTeamContext` (both from the generated `defaults.ts`), and read shared results from `result.shared.capabilities`.
+
+### 5b. Session UIs
+
+`SessionData` is `{ shared, teams }`: `sessionData.shared.context` holds the shared capabilities the UI declares, once, even with no teams, and each `sessionData.teams[teamId].context` holds that team's own. The generated `types.ts` exports `TeamContext`, `SharedContext`, `SharedWrites`, `TeamWrites` and a ready-made `SessionData`:
+
+| Before                                                                                  | After                                                                            |
+| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `type TypedSessionData = SessionData & { teams: Record<string, { context: Context }> }` | Delete it, and import `SessionData` from `../types`                              |
+| `useSessionUserInterfaceData<TypedSessionData, Config, SharedContext>()`                | `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()` |
+| `Object.values(sessionData.teams)[0]?.context.briefing.Message`                         | `sessionData.shared.context.briefing.Message`                                    |
+
+Move the third generic from `SharedContext` to `SharedWrites`: `SharedContext` now covers shared reads as well, so leaving it there compiles and lets `setData` accept a capability the UI only reads, which the host rejects. The fourth, `TeamWrites`, types the per-team `setData(teamId, update)`, so a team write naming a shared capability fails to compile too.
+
+**A read of shared state through a team returns `undefined`, and only the generated types catch it.** The generated `SessionData` leaves shared capabilities off each team's context, so a read such as `Object.values(sessionData.teams)[0]?.context.briefing` fails to compile with it. It compiles with a hand-written `TypedSessionData`, with a cast such as `team.context as unknown as Context`, and with `useSessionUserInterfaceData()` called with no type arguments, whose contexts are untyped. Left alone, a facilitator sees blank views and gates that never open. Do this in order:
+
+1. Delete every hand-written session data type and every cast of a team's context. Pass the generated `SessionData` to `useSessionUserInterfaceData`, and type every helper that takes session data or a team's context with `SessionData` or `TeamContext`
+2. Run `pnpm run typecheck`, and move each read it reports to `sessionData.shared.context`
+3. As a backstop, search `session/` for each shared capability's name: a read through a string key or a loosely typed helper still escapes the compiler
+
+Watch for the reverse as well: 1.0 delivers shared state with no teams, so a view that waited for a team before it could read shared state now has it at once.
+
+In component tests, put shared fixtures in `sessionData.shared`, built with `createMockSharedState`, and keep team fixtures to each team's own capabilities ([step 10d](#10d-update-ui-component-tests)).
+
+```bash
+grep -rn "TypedSessionData\|SessionData &\|as unknown as\|useSessionUserInterfaceData()\|useSessionUserInterfaceData<.*SharedContext" session
+grep -rn "RunAggregate\|InitAggregate" engine
+```
+
+## Step 6: one name for each thing
+
+The 1.0 vocabulary renames fields, messages and types so each concept has one name. Almost every rename fails to compile, so work through the errors with these tables beside you. 6c holds the changes the compiler cannot catch.
+
+### 6a. Tick numbers
+
+Two numbers shared one name. Nothing is renumbered.
+
+| Before                                                                           | After            | Means                                    |
+| -------------------------------------------------------------------------------- | ---------------- | ---------------------------------------- |
+| `meta.currentTick` (engine, aggregate engine, tick controller)                   | `meta.tick`      | The tick being run: 1 on the first `Run` |
+| `useUserInterfaceData().currentTick`, `renderUserInterface({ currentTick })`     | `completedTicks` | Ticks completed: 0 before the first      |
+| A session UI team's `tick`, a presentation's `session.tick`                      | `completedTicks` |                                          |
+| An endpoint's `session.tick` and each team status's `tick`                       | `completedTicks` |                                          |
+| CLI JSON `currentTick` and per-team `tick` (`sdk view`, `sdk tick` and the rest) | `completedTicks` |                                          |
+| `createTestSession` state's session and per-team `tick`                          | `completedTicks` |                                          |
+
+`getPastState` snapshot numbers are unchanged: snapshot N is the state after tick N.
+
+### 6b. Teams, participants and hooks
+
+| Before                                                                           | After                                                                                          |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `teamName` on cross-team and past-state entries                                  | `name`. Each entry also carries `index`                                                        |
+| `SessionParticipant`, `UserInterfaceTeamParticipant`, `UserInterfaceParticipant` | `Participant`                                                                                  |
+| `EndpointTeam`                                                                   | `TeamInfo`                                                                                     |
+| `EndpointCaller.role` as `string`                                                | `EndpointCallerRole`: `'participant' \| 'observer' \| 'facilitator' \| 'author' \| 'external'` |
+| A tick controller's optional `teams`, of bare contexts                           | `teams`, always present: `{ teamId, index, context }` per team, one in a single-team game      |
+| `useViewerRole`, `useOwnTeam`, `useOwnTeamJoinLink`, `useCrossTeamData`          | `useUserInterfaceViewerRole`, `…OwnTeam`, `…OwnTeamJoinLink`, `…CrossTeamData`                 |
+
+### 6c. Timers, in milliseconds
+
+One `TimerState` type replaces `SurfaceTimer`, `UserInterfaceTimer` and the projection and endpoint timer types.
+
+| Before                                                                    | After                                                  |
+| ------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `timerEnabled`, `isPaused`, `totalPausedMs`                               | `enabled`, `paused`, `pausedMs`                        |
+| `interval` (seconds)                                                      | `intervalMs` (**milliseconds**)                        |
+| Tick controller result `timerEnabled`, `interval` (seconds), `isComplete` | `enabled`, `intervalMs` (**milliseconds**), `complete` |
+| `scheduledTick(at, { isComplete })`                                       | `scheduledTick(at, { complete })`                      |
+| `intervalTick(seconds)`                                                   | `intervalTick(intervalMs)` (**milliseconds**)          |
+| `extendTick(seconds, teamId?)` on a session UI                            | `extendTick(byMs, teamId?)` (**milliseconds**)         |
+| `MIN_EFFECTIVE_TICK_INTERVAL_SECONDS`, `MAX_…`                            | `MIN_EFFECTIVE_TICK_INTERVAL_MS`, `MAX_…`              |
+
+The unit changes compile unchanged, so search for each by hand:
+
+- **`intervalTick(60)` now asks for 60 milliseconds** and is refused as below the 30-second minimum. Write `intervalTick(60_000)`
+- **`extendTick(120)` now extends by 120 milliseconds.** Write `extendTick(120_000)`
+- **A tick controller returning `interval: 60`** must return `intervalMs: 60_000`. `intervalMs` may be left out when the timer is off or you return `nextTickAt`
+- **A settings property the build reads as a default interval** is now `intervalMs`, in milliseconds
+- **`sdk timer --json`** reports a whole `TimerState`, so its interval is `intervalMs`
+
+```bash
+grep -rnE "intervalTick\(|extendTick\(|interval:|timerEnabled|isPaused" tick_controller session settings testing
+```
+
+`sdk timer extend <seconds>` and `sdk clock advance <seconds>` still take seconds, because a person types them.
+
+### 6d. Completion, record times, blob retention and the manifest types
+
+| Before                                                                                        | After                        |
+| --------------------------------------------------------------------------------------------- | ---------------------------- |
+| `isComplete` on an endpoint's `session` and team statuses, and on past-state entries          | `complete`                   |
+| `timestamp` on past-state entries                                                             | `recordedAt`                 |
+| `writeBlob(data, { retention: 'config' })`                                                    | `retention: 'settings'`      |
+| `sdk blob upload --config`                                                                    | `sdk blob upload --settings` |
+| `SDKConfiguration` (the authored `seriousgaming.sdk.json`)                                    | `PackageManifest`            |
+| `Configuration` (the built `seriousgaming.json`)                                              | `ResolvedPackageManifest`    |
+| `LogicConfiguration`                                                                          | `LogicLayout`                |
+| `session.needsConfiguration` on session state (`createTestSession`, `sdk reconfigure --json`) | `session.inSetup`            |
+
+A `writeBlob` call still passing `'config'` is refused, naming the new value. A test fixture that builds past-state entries by hand needs the new names too:
+
+```bash
+grep -rnE "isComplete|timestamp|retention: 'config'|SDKConfiguration|LogicConfiguration" engine endpoints hooks ui session testing
+```
+
+## Step 7: update endpoints
+
+### 7a. Replace `agentCallable` with `visibility`
+
+`visibility` says whether a caller outside the game may call an endpoint: a facilitator's AI agent, as before, or a platform API or other integration. The build refuses `agentCallable`. In each `endpoint.sdk.json`, replace `"agentCallable": true` with `"visibility": "external"`, and delete `"agentCallable": false`. `sdk endpoint list --agent` is now `--external`, and its JSON carries `visibility`. A caller outside the game is now refused an internal endpoint.
+
+The build also refuses an external endpoint whose `requestSchema` is not `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`), since an outside caller passes named arguments. Wrap a bare value in an object, such as `{ "price": 3.53 }` for `3.53`, and read `request.price` in the handler. One that takes no input declares `{ "type": "object", "properties": {}, "additionalProperties": false }`.
+
+### 7b. Handle the new arguments
+
+Every handler receives `session` (where the session stands: `completedTicks`, `maxTicks`, whether the waiting room is open and the game complete, and each team's standing) and `settings`, and a team-scoped one receives `team: { teamId, index, name }`. The generated `Handler` type requires them, so only a unit test that builds the arguments by hand breaks; build them with `logicArgs.endpoint` (step 10b). A session-scoped handler's type has no `team`.
+
+`caller.userInterfaceIdentifier` is optional, because a caller outside the game, and the CLI, has no surface. A handler that passed it on as a `string` needs a fallback, such as `caller.userInterfaceIdentifier ?? 'external'`, and one that checked for `'cli'` checks for the field being absent.
+
+### 7c. Branch on an endpoint failure's kind
+
+`callbacks.endpoints[id]()` rejects with an `EndpointError` rather than a plain `Error`. Code that matched on the message text branches on `error.kind` instead (a `MutationOutcome` kind, or `invalid-request`, `handler-error` or `invalid-response`), and can read `error.applied` to learn which effects landed before a call failed part-way. A failure part-way through reports the failed step's own kind (for example `tick-failed`), and a tick whose logic throws is `tick-failed` everywhere, where it used to be `error`. In tests, `createTestSession().send` answers a failed endpoint call with `{ type: 'endpointFailure', failure }` instead of throwing. See [When a call fails](./endpoints.md#when-a-call-fails).
+
+### 7d. Read the target team from `team`
+
+**`caller.teamId` changes meaning, and the compiler cannot see it.** It is now the caller's own team: present for a participant or an observer, absent for a facilitator or a caller outside the game. The team a team-scoped endpoint acts on is `team`:
+
+```bash
+grep -rn "caller.teamId" endpoints
+```
+
+### 7e. Give the scenario editor endpoints that need no session
+
+The scenario editor edits a scenario, not a session, so the build refuses one that lists an endpoint declaring any `reads`, `writes` or `actions` (`EDITOR_ENDPOINT_STATEFUL`). A 0.6 scenario builder could list one, because the dev server answered it from whatever session was running. For each endpoint the build names, either delete the `reads`, `writes` and `actions` it does not need, or give the editor an endpoint of its own without them. An endpoint the editor calls receives its declared `settings` as the scenario being edited resolves them, the editor's unsaved changes included, so declare `settings` rather than passing the values in the request. Its `context` is empty, `participants` is empty, `session` has played nothing and holds no teams, and `caller` carries `role: 'author'` rather than `'facilitator'` and no `sessionId`, which is now optional: a handler that used it as a `string` needs a fallback, and one that checked for `'facilitator'` to accept the editor's calls checks for `'author'`.
+
+## Step 8: rename each validator's `Run` to `UpdateData`
+
+A validator's logic exports one function per action it gates. Rename `Run` to `UpdateData`, and in tests call `UpdateData({ ... })`. The build refuses a validator that still exports `Run`, or neither gate:
+
+```bash
+grep -rln "export const Run" validators
+```
+
+Optionally, if your game holds teams at a round the facilitator opens and enforces it only by disabling a button, export `RequestTick` too (see [Gating tick requests](./validators.md#gating-tick-requests)).
+
+## Step 9: meet what the build and runtime now enforce
+
+- **Delete `uses` from user interfaces.** A game UI, session UI, waiting room, setup or scenario editor that declares `uses` is refused by the build. It never had an effect: a surface reaches an LLM, text extraction or speech through an endpoint that declares the service
+- **Delete demo mode.** `demo` in `seriousgaming.sdk.json` and in scenarios, the `GameDemo` type and `sdk dev --demo` are removed, and the build refuses the field. To show a game to someone, use a walkthrough run
+- **Write only what you declare.** Logic that changes a capability outside its `writes` now fails the call, where 0.6 kept the change. That covers an engine's `Init` and `Run`, both halves of an aggregate result (`shared` and each `teams` entry), and hooks, whether the capability is one the resource only reads or one it never declared. Returning a capability unchanged, as `{ capabilities: { ...context } }` does, still passes. Add the capability to `writes`, or stop changing it. Code copied between games tends to carry the same undeclared write
+- **Write shared capabilities only from the aggregate functions.** The build refuses a shared write declared by a hook, a surface or an engine without `InitAggregate` and `RunAggregate`. In an aggregate engine, a per-team `Init` or `Run` that writes a shared capability builds and passes unit tests, then stops the session starting or fails the tick. Move the write into `InitAggregate` or `RunAggregate`
+- **Test every path that writes.** The two rules above are checked when the write happens, by comparing the value before and after, so a write that leaves the value as it was passes. An engine that changes a capability it only reads fails on the first tick that moves the value, which may be many ticks in. A per-team `Init` that writes shared state fails when a session starts. `sdk build` checks neither, and a one-tick `tick --no-server` passes every path that tick did not take. Have your engine tests play each round, each branch and each scenario that writes, not one tick (see [Writes are checked when they happen](./testing.md#writes-are-checked-when-they-happen))
+- **Declare every capability a session UI changes in a team.** A session UI's team write that changes a capability outside its `writes`, or names a key that is not a capability, is refused as `denied`; 0.6 applied it. Sending a team's whole context back with one field edited still works, since a capability carried unchanged is not a change. The generated `TeamWrites` type catches most of these (step 5b); add the capability to the session UI's `writes`
+- **Declare every capability a player surface writes.** A game UI or waiting room write (or `deletes` path) naming a capability outside its `writes`, or a key that is not a capability, is refused as `denied`. The generated types already forbid it, so only code that cast around them is affected: add the capability to the surface's `writes`
+- **Keep Node out of logic.** Logic importing a Node built-in such as `fs`, `path` or `node:crypto` fails `sdk build`, `sdk dev` and `sdk tick` with `LOGIC_NODE_BUILTIN`, and the dev server no longer hands logic `require`. Production never had either. Use the callbacks for files, and `encodeUtf8` / `decodeUtf8` and `seededRandom` from the SDK for the rest
+- **Drop the guards on declared services.** A service a resource declares in `uses` is always present on its generated `Callbacks`, so `callbacks.generateText?.(…)` and `callbacks.extractText!` become plain calls. `LogicCallbacks` takes `ApiUse` values as its type parameter
+- **Never retry a conflict automatically.** A `conflict` that reaches a surface means the host already retried and gave up. Delete any automatic retry loop, show the failure, and offer `useMutationReporter`'s `failure.retry()` behind a 'Try again' button. The compiler cannot see a retry loop, so search your surfaces, and any UI library you share between games, for `'conflict'`
+- **Imports that moved out of the SDK.** A game needs none of these, but if you imported them: the host library and its wire types moved from `@seriousgaming/sdk/host` and `./ui` to `@seriousgaming/sdk-tools/host`; the runtime helpers (`createGuardedCallbacks`, `deepMergeContext`, `projectContext`, `validateTickControllerResult`, `MANIFEST_VERSION` and others) moved from the SDK root to `@seriousgaming/sdk-tools/runtime`; `isApiUseDeclared`, `isDeliverableToSurfaces`, `withheldCapabilityIds`, `resolveManifestVersion`, `removedSharedFlagError` and `tickControllerResultSchema` are removed; and `ExecutionHistory`, `JsonPatchOperation`, `LLMGenerateOptions` and `GameContext` are no longer re-exported from `sdk-tools/client` (take `LLMGenerateOptions` from the SDK root). A test harness that merged a `setData` patch with `deepMergeContext` uses `mergingSetData(setLocal)` from `@seriousgaming/sdk/ui/testing`, which applies `deletes` as the host does
+
+## Step 10: update the tests
+
+### 10a. Move off `GameRunner`
+
+`GameRunner` and `MultiTeamGameRunner`, deprecated in 0.6.0, are removed with their option and result types. Move each test to `createTestSession` with the table in [Moving from GameRunner](./engine-testing.md#moving-from-gamerunner):
+
+```bash
+grep -rln "GameRunner" testing
+```
+
+A test that calls an endpoint through `createTestSession` with `uiIdentifier: ''` to mean a system call is now refused as `denied`, and a test that expected a failure may still pass. Leave `uiIdentifier` out instead: a call that names no surface is system-trusted, as the CLI's is.
+
+### 10b. Build logic arguments with `logicArgs`
+
+Every logic call now receives `meta.now` (the operation's time in milliseconds) and a read-only `participants` array, an endpoint also `settings`, `session` and, team-scoped, `team`, and an aggregate `shared`. All are required by the argument types, so a test that builds arguments by hand stops compiling. Rather than adding each field, build them with `logicArgs` from `@seriousgaming/sdk/testing`, which fills `meta`, `participants`, the roster and offline stub callbacks around what the test names:
+
+```typescript
+import { logicArgs } from '@seriousgaming/sdk/testing';
+import { defaultSettings } from '../../engine/defaults';
+
+const result = await Run(logicArgs.run({ context, settings: defaultSettings }));
+expect(result.capabilities.sales.Sales).toBe(10);
+
+const answer = await Handle(logicArgs.endpoint({ request: { price: 3 }, context, settings: {} }));
+```
+
+There are builders for `init`, `run`, `aggregate`, `hook`, `endpoint`, `tickController`, `validator` and `requestTick`. See [Testing the Run function](./testing.md#testing-the-run-function).
+
+**Replace `Date.now()` in logic with `meta.now`.** It is the same for every team in one tick, and a test controls it through the session clock.
+
+Two builders need more than their names suggest:
+
+- **`logicArgs.hook`** takes the signal's payload, so a `participantJoin` hook needs a whole `participant` (a `Participant`), not just an id
+- **`logicArgs.endpoint`** builds a team-scoped call on `team-1` (index 0) from a participant caller. Pass `team`, `caller` or the session-scoped fields when a test needs others
+
+### 10c. Opt in to real services where a test needs them
+
+`createTestSession` no longer reaches the platform by default: `generateText`, `generateSpeech` and `extractText` return deterministic stubs, so a test runs without a network or a key. A test that relied on real responses passes `services: 'platform'`.
+
+### 10d. Update UI component tests
+
+The helpers in `@seriousgaming/sdk/ui/testing` build each piece; see [Testing](./testing.md):
+
+- **`createMockTeamState` and `createMockSharedState`** build a team's and the shared store's state for a session UI test. Pass the generated types, `createMockTeamState<TeamContext>({ context })` and `createMockSharedState<SharedContext>({ context })`, and a shared capability left on a team fixture fails to compile. Render with `renderSessionUserInterface<SessionData>(...)` so the whole fixture is checked. Typing a fixture this way tends to turn up stale test data: fields the game renamed long ago, and tests that were passing while checking nothing. Treat each failure as a find, not a regression, and fix the test
+- **`renderSettingsEditor`** replaces the provider tree a setup or scenario editor test built by hand (step 3)
+- **`mergingSetData(setLocal)`** applies a `setData` call to local state the way the host does, `deletes` included, for a test that keeps state between calls
+- **A hand-built session callbacks object needs `deleteTeam`**, which the session UI's callbacks now require. Build it with the testing helpers rather than by hand where you can
+- **Theme palettes gained `contrastText`.** A hand-built theme object needs it on each colour, and code that loops over a palette's keys, in a test or in the UI, now meets it
+
+## Step 11: update scripts and agents that drive the CLI
+
+A game package does not change here, and a person at a terminal sees the same messages. Scripts, CI jobs and AI agents that parse the CLI's output do:
+
+- **One envelope.** With `--json` (or `SERIOUSGAMING_JSON=1`) every command prints one document: `{ "ok": true, "command", "data", "diagnostics", "warnings" }` on success and `{ "ok": false, "command", "error": { "code", "message", "hint", "details" }, "diagnostics", "warnings" }` on failure. Read `ok` where you read `success`, `data.<field>` where you read a top-level field, and `error.code` where you matched on `error`. A failing `endpoint call` puts its failure in `error.details`
+- **Exit codes by category.** Every failure used to exit 1. Now 1 is a bug in the CLI, 2 a usage error, 3 an invalid package, 4 a refusal by the game (a validator rejection, a failed tick) and 5 the environment (no session, a port in use, the platform unreachable). Replace `[ $? -eq 1 ]` with `[ $? -ne 0 ]`, or test for the category you mean, and branch on `error.code`, never on the message (see [Exit codes](../cli-reference.md#exit-codes))
+- **Diagnostics say where.** A failure about the package lists its findings in `diagnostics`, each with a `code`, the `file`, and a `pointer` into it, or a `line` and `column` for a logic error. Read these rather than searching a message for a file name
+- **`delete --force` is `delete --yes`.** Without a terminal the CLI never prompts: a command that would ask fails with exit 2 and `PROMPT_REQUIRED`. Pass definitions as an argument, with `--file` or on stdin, and confirmations with `--yes`
+- **`new package` fails when its `pnpm install` fails** (exit 5, `INSTALL_FAILED`). The files are written; run `pnpm install` in the package
+- **State readers.** The state projection that `sdk view` and `sdk play` print is version 4: `settings` in place of `configuration`, `completedTicks` in place of `tick`, `complete` in place of `isComplete`, a full `TimerState` and participants with `teamId`. `sdk tick --json` reports `complete`, and `sdk view --tick N` entries carry `complete` and `recordedAt` (were `isComplete` and `timestamp`)
+- **`sdk blob upload --config` is `--settings`**, and its output's `retention` is `settings` where it was `config`
+- **`sdk docs ask` and `sdk docs search` are removed.** Both now fail with `USAGE_REMOVED_COMMAND` (exit 2) and a pointer. Read a document with `pnpm run sdk docs view <path>`, search `node_modules/@seriousgaming/sdk-tools/dist/docs`, or copy the docs into the project with `pnpm run sdk docs export`. Agent guidance often names `docs ask` as its first instruction, so replace it in `CLAUDE.md` and `.claude/rules/` with that wording. Drop `HF_HOME` and `HUGGINGFACE_HUB_CACHE` if you set them only for `docs ask`
+- **`runCommand({ type: 'updateConfig' })` is `updateSettings`**, with its payload keyed by settings identifier, for a walkthrough or script that drives the dev server
+- **The dev server listens on `localhost` only.** To test on a phone or tablet, start it with `pnpm run sdk dev --lan`
+- **A settings edit no longer applies mid-session.** Once a tick is played, `sdk tick`, `sdk undo`, a context patch and a writing endpoint call are refused with `SETTINGS_STALE` (exit 4) until you run `sdk init`; see [What reloads](../cli-reference.md#what-reloads)
+- **`sdk team remove` refuses a team with participants**, and any team in a shared-state session. Move participants out with `sdk participant move` first
+
+## Step 12: refresh the scaffold's furniture
+
+Optional, but each item fixes a trap. A package created by `sdk new package` at 1.0 has all of them; an older one copies them from `node_modules/@seriousgaming/sdk-tools/dist/templates/package/`:
+
+- **Playwright no longer hangs on teardown.** Copy `global-setup.ts.template` to `testing/e2e/global-setup.ts` and replace `playwright.config.ts`. The setup starts an isolated dev server with `startDevServer()` and sets `SERIOUSGAMING_DEV_URL`, which the `@seriousgaming/sdk/e2e` helpers read, so drop `{ port }` from their calls
+- **A shared package can use the SDK's UI hooks.** Add `@seriousgaming/sdk` and `@seriousgaming/deck` to `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`, beside React and Emotion
+- **The agent's pre-approved commands match its guidance.** Replace `.claude/settings.json`: it allows only read and check commands, never `dev`, `publish` or `pnpm add`
+- **Lint fails on a warning.** Set the `lint` script to `oxlint --max-warnings=0`
+- **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
+- **A shorter `CLAUDE.md` and refreshed rules.** Merge in the new `CLAUDE.md.template` and `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
+- **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium`
+
+Nothing breaks if you skip the new features 1.0 adds, but several replace workarounds games carry: the engine's private `state` and `complete: true` (see [Engine](./engine.md#keeping-memory-between-ticks) and [Game completion](./tick-controller.md#game-completion)), capabilities with `"lifetime": "session"` that undo and reset leave alone ([Lifetime](./capabilities.md#lifetime)), a facilitator's slide deck in the `presentation/` slot ([Building presentations](./presentation.md)), endpoints that act on the session or take files ([Endpoints](./endpoints.md)), and the `useAsset`, `usePastState` and `useViewerStorage` hooks ([User interfaces](./ui.md)).
+
+## Step 13: rebuild and verify
+
+From the package root, in this order:
+
+```bash
+pnpm install
+pnpm run sdk generate
+pnpm run typecheck
+pnpm run --silent sdk build --validate-only --json
+pnpm run build
+pnpm run lint
+pnpm run test:run
+pnpm run test:engine
+pnpm run --silent sdk tick --no-server
+pnpm run --silent sdk tick --no-server --scenario <id>   # once for each scenario
+pnpm run test:e2e
+```
+
+- `generate` rewrites every `types.ts` and `defaults.ts` from the new names, so the compiler can point at what is left
+- `typecheck` lists every rename the tables above describe. Work through it until it is clean
+- `build --validate-only --json` checks the package without bundling. On failure, read each entry of `diagnostics`: a `REMOVED_FIELD` names what replaced the field, and any other `SCHEMA_INVALID` carries its `file` and `pointer`
+- `tick --no-server` starts a fresh session and plays one tick, for the default settings and each scenario. It is the only check that runs `Init` and `InitAggregate` against real settings, so it catches what builds and passes unit tests but stops a session starting. Do not skip it, but do not treat it as enough either: it plays one tick, and the write rules in step 9 fail only on a call that changes the value
+- Read each command's exit code rather than its summary line: a test file that fails to load can leave a summary that counts only the tests that ran
+- Then search by hand for the changes no tool sees, listed at the top of this guide
+- Finally, play a round in the dev server and check each surface, the timer and completion
+
+## Before you publish
+
+A 1.0 build is a manifest version 3 package, and the platform must accept version 3 before you publish one. Until it does, the platform refuses the upload, and a version 2 package you published from 0.6 keeps running as it is. Check with Business Simulations that the platform you publish to accepts version 3 packages, and keep publishing from 0.6 until it does.
+
+## Related
+
+- [Changelog](../changelog.md): the detail behind every step
+- [Changelog for 0.x](../changelog-0.x.md): every earlier release
+- [Settings](./settings.md)
+- [Engine testing](./engine-testing.md)
+- [CLI reference](../cli-reference.md)