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

package/dist/docs/recipes/remember-a-viewers-choice.md

@@ -0,0 +1,55 @@
+# Remember a viewer's choice
+
+**Keywords:** useViewerStorage, localStorage, remember tab, collapsed panel, persist across reload, per-browser preference, session key, sessionKey, storage namespace, team-1 collision
+
+A viewer's own choices, such as the tab they had open, a panel they collapsed, or a sort order, should survive a reload. Keying `localStorage` by team id looks like it works and does not: every session's first team is `team-1`, so one session's choice turns up in the next. `useViewerStorage` keys each value by the session, the surface and the viewer for you.
+
+## Prerequisites
+
+- A user interface of any kind (see [Create a user interface](create-user-interface.md))
+
+## Steps
+
+1. Replace the `useState` that holds the choice with `useViewerStorage`, giving it a key and the same initial value:
+
+    ```tsx
+    import { useViewerStorage } from '@seriousgaming/sdk/ui';
+
+    const [tab, setTab] = useViewerStorage('tab', 0);
+    ```
+
+    It returns `[value, setValue]` exactly as `useState` does, updater functions included. Values are stored as JSON, so keep them to plain data.
+
+2. Use the value as before:
+
+    ```tsx
+    <Tabs value={tab} onChange={(_, value: number) => setTab(value)}>
+    ```
+
+3. Keep the key short and specific to the surface: it only has to be unique among the values one surface stores. The hook adds the session key, the surface and the viewer itself.
+
+## What it is keyed by
+
+- **The run.** The host sends every surface an opaque `sessionKey`, the same for every surface of a session and different for every other session. A walkthrough has its own, so a demonstration never touches the real session's values
+- **The surface.** A game UI and its waiting room share values, since both are the player's; the session UI, the settings editors and the presentation each have their own
+- **The viewer.** The participant, or the viewer's role where there is none (an observer, the facilitator), so two participants sharing a device keep their own choices
+
+It is per browser and never shared with anybody. Anything the game or other players need belongs in context, not here.
+
+## Verify
+
+- Choose a tab, reload the page: the same tab opens
+- Open a second participant on the same team: they start from the initial value
+- In a test, `renderUserInterface(<App />, { sessionKey: 'one' })` and a second render with `sessionKey: 'two'` keep their values apart
+
+## Troubleshooting
+
+- **The value does not survive a reload.** The browser is blocking storage (a private window, or a locked-down kiosk). The hook falls back to memory for the life of the page rather than throwing, which is the most it can do
+- **`useViewerStorage must be used inside a surface wrapper`.** The component renders outside the wrapper, or a test renders it without one of the `render*` helpers from `@seriousgaming/sdk/ui/testing`
+- **Another tab shows a stale value.** Tabs follow each other through the browser's `storage` event, which fires only for changes made in a different tab of the same origin
+
+## Related
+
+- [Adapt a UI for observers](adapt-ui-for-observers.md)
+- [Adapt a game for walkthroughs](adapt-a-game-for-walkthroughs.md)
+- [Test a user interface](test-user-interface.md)

package/dist/docs/recipes/review-a-past-day.md

@@ -0,0 +1,73 @@
+# Review a past day in a UI
+
+Let participants scrub back through their team's committed ticks, or chart a value across every tick, with `usePastState` and `getPastState`.
+
+**Keywords:** getPastState, usePastState, PastStateQuery, PastStateEntry, tick snapshot, review past day, history, scrubber, timeline, replay, previous tick, completedTicks, cross-team history, TickSnapshotError, results table, history chart, round_history growing
+
+## Prerequisites
+
+- A user interface (see [Create a user interface](create-user-interface.md)) or a session UI
+- The capabilities you review declared in the surface's `reads` or `writes`
+
+## Steps
+
+1. Bound the scrubber by `completedTicks`. Ticks `0` to `completedTicks - 1` are reviewable; the live board is `data`. Clamp at render, since an undo can lower `completedTicks` under a stored choice:
+
+    ```tsx
+    const { completedTicks } = useUserInterfaceData<Context, Settings>();
+    const [selectedDay, setSelectedDay] = useState(0);
+    const day = Math.max(0, Math.min(selectedDay, completedTicks - 1));
+    ```
+
+2. Read the board for that tick with `usePastState`. It reads again when the query changes, keeps the last board on screen while the next loads, and drops answers a newer read has overtaken:
+
+    ```tsx
+    import { usePastState } from '@seriousgaming/sdk/ui';
+
+    const { entries, error, loading } = usePastState<Context>(
+        completedTicks > 0 ? { fromTick: day } : null
+    );
+    const past = entries[0]; // undefined when that tick is not reviewable
+    ```
+
+    Render `past.context` with the same components as live `data`: it is composed the same way.
+
+3. To chart a value over every tick, read a range in one call and name only the capability you plot:
+
+    ```tsx
+    const { entries: history } = usePastState<Context>(
+        completedTicks > 0
+            ? { fromTick: 0, toTick: completedTicks, capabilityIds: ['profit'] }
+            : null
+    );
+    ```
+
+    This is what lets you drop a `round_history` capability that grows every tick.
+
+4. In a shared-state game, review every team at that tick with `teams: 'all'`, typed by the generated `CrossTeamContext`. Other teams' rows arrive only for capabilities the surface lists in `crossTeamReads` (see [Observe other teams' state](observe-other-teams-state.md)). A session UI calls the same `getPastState` from `useSessionUserInterfaceCallbacks()`, and its default is the whole session.
+
+5. Optional: for a slider dragged quickly, debounce the query, and cache entries by tick. Evict cached ticks at or above `completedTicks` when it drops, so an undo never shows a stale board.
+
+## Verify
+
+- The slider runs from `0` to `completedTicks - 1` and shows each tick's board
+- A decision your engine clears each tick is still visible on that tick's board
+- After an undo, the undone tick is no longer reachable
+- A range over `{ fromTick: 0, toTick: completedTicks }` returns every completed tick and not the live one
+
+## Troubleshooting
+
+| Problem                                              | Solution                                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Every query comes back empty                         | You asked for `completedTicks` or later, or no tick has run yet; only ticks below `completedTicks` are reviewable  |
+| What participants entered in tick 3 is not at tick 3 | A snapshot is the board the next tick was submitted with: decisions entered during tick 3 are at `{ fromTick: 2 }` |
+| An entry is missing where someone did write          | The write landed late and counts for the next tick (`setData` resolves with `late`)                                |
+| A range returns fewer ticks than asked               | A host may page a wide range; read on from the last tick received                                                  |
+| `teams: 'all'` returns only your own team            | The surface lists nothing in `crossTeamReads`                                                                      |
+| Reviewable history vanished                          | A reset deletes it; warn facilitators before they reset a live session                                             |
+
+## Related
+
+- [Reviewing past ticks](../guides/ui.md#reviewing-past-ticks): what a snapshot holds, the query, and its limits
+- [Observe other teams' state](observe-other-teams-state.md)
+- [Use requestTick in a UI](use-request-tick.md)

package/dist/docs/recipes/share-assets-across-scenarios.md

@@ -0,0 +1,120 @@
+# Share assets across scenarios
+
+Reference one file from several scenarios without copying it, using a package-level `shared:` reference.
+
+**Keywords:** shared assets, shared-assets, share media across scenarios, shared: reference, deduplicate scenario assets, storyline assets, avoid asset duplication
+
+## What you'll build
+
+Two scenarios that play the same storyline and reference the same media file from a single source under `shared-assets/`, so editing that one file changes both.
+
+## Prerequisites
+
+- A package with at least two scenarios (see [Create a Scenario](create-scenario.md))
+- The media the scenarios share (images, audio, video, documents)
+
+## When to use this
+
+Use a `shared:` reference when two or more scenarios point at the same file and you do not want to maintain duplicate copies. Asset duplication is the part that drifts: a `shared:` reference keeps a single source of truth.
+
+Keep using a scenario's own `asset:<path>` when a file genuinely belongs to one scenario, or when a scenario needs its own version of a file that another scenario shares. There is no shadowing between the two schemes: `shared:x` and `asset:x` are independent.
+
+## Steps
+
+### 1. Create the shared-assets directory
+
+Place the shared files under a top-level `shared-assets/` directory at the package root (next to `scenarios/`, `engine/`, and `seriousgaming.sdk.json`). Group with folders however you like; there is no schema or declaration:
+
+```
+my-package/
+├── shared-assets/
+│   └── storyline/
+│       ├── avatars/ceo.png
+│       └── video/intro.mp4
+├── scenarios/
+│   ├── agilisco/scenario.sdk.json
+│   └── growth/scenario.sdk.json
+└── seriousgaming.sdk.json
+```
+
+### 2. Declare the setting the scenarios override
+
+A scenario can only override a setting a settings resource declares: an undeclared key fails the build. Create a `storyline` settings resource holding `Avatar`, with a default for games run without a scenario:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "storyline",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "Avatar": { "type": "string", "default": "shared:storyline/avatars/ceo.png" }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+Then add `storyline` to the `settings` array of each resource that shows the avatar, such as the game UI's `ui/ui.sdk.json`. A resource receives only the settings it lists.
+
+### 3. Reference the shared file from each scenario
+
+Use a `shared:<path>` reference anywhere an `asset:` reference is valid; `<path>` is relative to `shared-assets/`. Point both scenarios at the same file. A JSON Patch `add` needs the parent to exist, so if a scenario has no `settings.storyline` block yet, add the block rather than the key (`"path": "/definition/settings/storyline", "value": { "Avatar": "..." }`):
+
+```bash
+pnpm run sdk update scenario agilisco --patch '[
+  { "op": "add",
+    "path": "/definition/settings/storyline/Avatar",
+    "value": "shared:storyline/avatars/ceo.png" }
+]'
+
+pnpm run sdk update scenario growth --patch '[
+  { "op": "add",
+    "path": "/definition/settings/storyline/Avatar",
+    "value": "shared:storyline/avatars/ceo.png" }
+]'
+```
+
+The `growth` preset can still override a setting the two scenarios differ on: duplicated settings values are fine. Only the media is shared.
+
+### 4. Use the reference in a UI or engine
+
+Nothing special is needed: `useAssetUrl`, `useAsset`, `getAssetUrl`, `readAsset`, and `extractText` all handle `shared:` like any other reference.
+
+```tsx
+import { useAssetUrl, useUserInterfaceData } from '@seriousgaming/sdk/ui';
+
+import type { Context, Settings } from '../types';
+
+function Avatar() {
+    const { settings } = useUserInterfaceData<Context, Settings>();
+    return <img src={useAssetUrl(settings.storyline.Avatar)} alt="CEO" />;
+}
+```
+
+## Verify
+
+```bash
+# Build copies shared-assets/ into the bundle root
+pnpm run sdk build
+ls dist/shared-assets/storyline/avatars   # ceo.png is present
+
+# Bundle includes shared-assets/ exactly once
+pnpm run sdk package bundle
+```
+
+Start the dev server and confirm the file is served at `/api/shared/assets/storyline/avatars/ceo.png`, then switch between the two scenarios and confirm both render the same image. A `shared:` reference resolves even before any scenario is selected.
+
+## Troubleshooting
+
+- **404 from the shared asset URL** - the path inside `shared:<path>` is relative to `shared-assets/`, not to a scenario's `assets/`. Check the file exists under `shared-assets/<path>` and that you ran `build` so it was copied into `dist/`
+- **The wrong file resolves** - `shared:` and `asset:` never shadow each other. If you meant the scenario's own copy, use `asset:<path>`; if you meant the shared copy, use `shared:<path>`
+- **`getAssetUrl` or `useAssetUrl` throws** - the reference must start with `asset:`, `shared:`, or `blob:`. A bare path is not a valid reference
+
+## Related
+
+- [Asset references](../guides/file-handling.md#asset-references)
+- [Create a Scenario](create-scenario.md)
+- [Create a settings resource](create-settings.md)
+- [Scenarios guide](../guides/scenarios.md)

package/dist/docs/recipes/share-logic-between-engine-and-ui.md

@@ -0,0 +1,130 @@
+# Share logic between an engine and a UI
+
+**Keywords:** share code, shared logic, duplicate formula, projection, preview, keep in sync, pure helper, import from engine and UI, single source of truth, drift
+
+Put a calculation in one file and use it from both your engine logic and your user interface, so a live preview cannot drift from the result the engine actually computes.
+
+## When you need this
+
+Whenever a UI shows a participant what _would_ happen. An engine settles the real outcome at tick time, but the participant wants to see the effect of a decision before submitting it, so the same formula has to run in two places:
+
+- 'At this price you would win 38% of the market'
+- 'This trade would leave you 12 short'
+- 'Your score after this move would be 340'
+
+Writing the formula twice works right up until someone changes one copy. Then the preview lies, and participants stop trusting the interface.
+
+## Prerequisites
+
+- An engine with logic (see [Create an engine](create-engine.md))
+- A user interface (see [Create a user interface](create-user-interface.md))
+
+## Steps
+
+1. Put the calculation in a plain TypeScript file anywhere in your package. A top-level `shared/` directory keeps it obvious that it is not owned by one resource:
+
+    ```
+    my-package/
+    ├── shared/
+    │   └── market.ts          ← the shared rules
+    ├── engine/
+    │   └── logic.ts
+    └── ui/
+        └── src/App.tsx
+    ```
+
+2. Export pure functions. No callbacks, no context mutation, no I/O: just inputs to outputs:
+
+    ```typescript
+    // shared/market.ts
+
+    /** Share of the market each team wins, given every team's price. */
+    export function marketShares(prices: number[]): number[] {
+        const inverses = prices.map((price) => 1 / price);
+        const total = inverses.reduce((sum, value) => sum + value, 0);
+        return inverses.map((inverse) => inverse / total);
+    }
+
+    /** The share one team would win at `candidatePrice`, rivals unchanged. */
+    export function projectShare(
+        candidatePrice: number,
+        ownIndex: number,
+        currentPrices: number[]
+    ): number {
+        const hypothetical = currentPrices.map((price, index) =>
+            index === ownIndex ? candidatePrice : price
+        );
+        return marketShares(hypothetical)[ownIndex];
+    }
+    ```
+
+3. Import it from your engine's logic. The engine stays the authority: it computes the value that is written to state.
+
+    ```typescript
+    // engine/logic.ts
+    import { marketShares } from '../shared/market';
+
+    export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+        teams,
+    }) => {
+        const prices = teams.map((t) => t.context.price.Price);
+        const shares = marketShares(prices);
+
+        return {
+            shared: { capabilities: {} },
+            teams: teams.map((t, i) => ({
+                capabilities: {
+                    ...t.context,
+                    market: { ...t.context.market, Share: shares[i] },
+                },
+            })),
+        };
+    };
+    ```
+
+4. Import the same file from your UI, and use it only to project. Never to decide:
+
+    ```tsx
+    // ui/src/App.tsx
+    import { projectShare } from '../../shared/market';
+    import { useUserInterfaceCrossTeamData, useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
+
+    import type { CrossTeamContext } from '../types';
+
+    const ownTeam = useUserInterfaceOwnTeam();
+    const teams = useUserInterfaceCrossTeamData<CrossTeamContext>();
+
+    const ownIndex = teams.findIndex((team) => team.teamId === ownTeam?.teamId);
+    const projected =
+        ownIndex === -1
+            ? null
+            : projectShare(
+                  price,
+                  ownIndex,
+                  teams.map((team) => team.context.price.Price)
+              );
+    ```
+
+5. Keep the shared file within two rules. Both sides bundle what they import (esbuild for engine logic, Vite for UIs), so the file's code is inlined into each bundle and nothing resolves it at runtime. That is also why it inherits the constraints of both:
+
+    - **Keep it pure.** Inputs to outputs. A shared function that reaches for `callbacks`, mutates context, or performs I/O cannot be used by both sides, and stops being safe to call from a render
+    - **Stay inside the ECMAScript intrinsics.** The file is compiled into a logic bundle, so it inherits the [bare-V8 restriction](../guides/engine.md#the-language-environment-your-logic-runs-in): no `structuredClone`, `fetch`, timers, `TextEncoder`, and so on. The scaffold's lint rule covers `engine/`, `tick_controller/` and each plural resource's `logic/` directory, so a top-level `shared/` file is **on you**. To have the lint rule cover it, put the file inside `engine/` instead and import it from the UI by relative path
+
+## Verify
+
+- `pnpm run sdk build` completes, and `dist/engine/logic.js` contains the shared function inlined
+- `pnpm run sdk tick` produces the value the engine computes through the shared function
+- The UI's preview and the post-tick value agree for the same inputs
+
+## Troubleshooting
+
+- **`ReferenceError` at tick time naming something from the shared file**: The shared file used a host global. See step 5; the dev server and `tick` both reproduce this, so fix it there
+- **The UI cannot resolve the import**: Check the relative depth. From `ui/src/App.tsx` to `shared/` is two levels up
+- **The preview disagrees with the result**: The engine is passing different inputs, not running different code. Log both sides' arguments; the usual cause is the UI projecting from live cross-team values while the engine settles from the post-validator state
+- **Type errors only in the engine**: The shared file is being type-checked against both the UI's and the engine's tsconfig. Keep its signatures free of DOM and Node types
+
+## Related
+
+- [Negotiate across teams](negotiate-across-teams.md): the pattern this most often serves
+- [Observe other teams' state](observe-other-teams-state.md)
+- [Engines guide: the language environment your logic runs in](../guides/engine.md#the-language-environment-your-logic-runs-in)

package/dist/docs/recipes/show-all-teams-participants.md

@@ -0,0 +1,109 @@
+# Show all teams' participants in a UI
+
+Let a game UI read the participant roster of every team in a shared-state session, so it can render a directory of who is on each competing team.
+
+**Keywords:** getAllTeamsParticipants, crossTeamParticipants, all teams participants, participant directory, who is on each team, cross-team roster, negotiation, useUserInterfaceParticipants, Participant
+
+## What you'll build
+
+A user interface that lists every team and its participants, grouped by team, for a negotiation or trading game where teams deal with each other live.
+
+## Prerequisites
+
+- A shared-state game (`teams.mode` is `shared-state`); the declaration below fails the build in any other mode
+- An existing user interface (see [Create a user interface](create-user-interface.md)) included in that game
+
+## Steps
+
+### 1. Declare cross-team participant access
+
+Add `crossTeamParticipants: true` to the UI's bundle. This authorises the roster read and makes it visible at build time. Without it, `getAllTeamsParticipants()` resolves to an empty array.
+
+```json
+{
+    "definition": {
+        "crossTeamParticipants": true
+    }
+}
+```
+
+It is only meaningful in shared-state games: in any other mode the build fails.
+
+### 2. Read every team's roster
+
+Call `getAllTeamsParticipants` from `useUserInterfaceCallbacks()`. It returns one flat `Participant[]` (`{ id, name, index, connected, teamId }`), one entry per participant across all teams.
+
+```typescript
+import { useUserInterfaceCallbacks, type Participant } from '@seriousgaming/sdk/ui';
+
+const { getAllTeamsParticipants } = useUserInterfaceCallbacks();
+
+const [roster, setRoster] = useState<Participant[]>([]);
+useEffect(() => {
+    let cancelled = false;
+    void getAllTeamsParticipants().then((all) => {
+        if (!cancelled) setRoster(all);
+    });
+    return () => {
+        cancelled = true;
+    };
+}, [getAllTeamsParticipants]);
+```
+
+### 3. Group by team and render
+
+The roster is flat; group it by `teamId` and join against `useUserInterfaceTeams()` for each team's display name and index.
+
+```typescript
+import { useUserInterfaceTeams } from '@seriousgaming/sdk/ui';
+
+const teams = useUserInterfaceTeams();
+const byTeam = useMemo(() => {
+    const grouped = new Map<string, Participant[]>();
+    for (const p of roster) {
+        grouped.set(p.teamId, [...(grouped.get(p.teamId) ?? []), p]);
+    }
+    return grouped;
+}, [roster]);
+
+// teams.map((team) => byTeam.get(team.teamId) ?? []), then render team.name then its members
+```
+
+### 4. Refresh when the roster may have changed
+
+`getAllTeamsParticipants` is a point-in-time snapshot, not a live subscription: it does not update as participants join or leave. Re-call it when you want fresh data, for example on each committed tick by depending on `completedTicks`.
+
+```typescript
+const { completedTicks } = useUserInterfaceData<Context, Settings>();
+useEffect(() => {
+    void getAllTeamsParticipants().then(setRoster);
+}, [completedTicks, getAllTeamsParticipants]);
+```
+
+Your own team's roster stays live through `useUserInterfaceParticipants()`: use that hook for the caller's own team and `getAllTeamsParticipants` for the wider directory.
+
+## Verify
+
+- [ ] The directory lists every team and its participants, grouped by team
+- [ ] A participant that joins another team appears after you refresh (a new tick, or your own refresh trigger)
+- [ ] Removing `crossTeamParticipants` from the bundle makes the directory empty
+- [ ] Declaring `crossTeamParticipants` in a non-shared-state game fails `sdk build`
+
+## Troubleshooting
+
+**`getAllTeamsParticipants()` returns an empty array**
+
+The UI has not declared `crossTeamParticipants: true` in its bundle, or the game is not shared-state. The declaration is the gate; an undeclared UI always receives an empty array.
+
+**The directory does not update when someone joins**
+
+That is expected: the read is point-in-time. Trigger a refresh (step 4). Only the caller's own team updates live, via `useUserInterfaceParticipants()`.
+
+**`useUserInterfaceCallbacks` throws**
+
+The hook must be called inside a component rendered within a `UserInterfaceWrapper`. The SDK template wires this automatically.
+
+## Related
+
+- [Observe other teams' state](observe-other-teams-state.md)
+- [Building user interfaces](../guides/ui.md)

package/dist/docs/recipes/start-from-an-empty-package.md

@@ -0,0 +1,169 @@
+# Start a game from an empty package
+
+Build a game from nothing: a capability for its state, an engine that changes it each tick, and a game UI to show it.
+
+**Keywords:** empty package, from scratch, new game, blank game, new package --empty, first capability, first engine
+
+## What you'll build
+
+A bakery that bakes a number of loaves each day and sells up to the day's demand, with a running count of loaves sold.
+
+## Prerequisites
+
+- Node.js 24 or later and pnpm 12
+- An empty directory
+- [Getting started](../getting-started.md) worked through once. The starter game shows the shape a real game needs, which an empty package does not
+
+## Steps
+
+### 1. Scaffold an empty package
+
+```bash
+mkdir bakery
+cd bakery
+pnpm dlx @seriousgaming/sdk-tools new package --empty
+```
+
+This writes the package files (`seriousgaming.sdk.json`, `package.json`, the TypeScript, lint, and test configuration), the same `CLAUDE.md` and `.claude/` guidance a starter game gets, and installs dependencies. It adds no game resources, so there is nothing to run yet.
+
+### 2. Create a capability
+
+A capability is a named slice of the game's state. This one holds the loaves:
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "bakery",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Loaves": { "type": "number", "default": 20, "minimum": 0 },
+        "Sold": { "type": "number", "default": 0 }
+      },
+      "required": ["Loaves", "Sold"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+The identifier is the directory name, so this writes `capabilities/bakery/capability.sdk.json`.
+
+### 3. Create the engine
+
+A game holds one engine, at `engine/`. It declares what it reads and writes, and the settings it takes. Create the settings first; every property declares a default:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "demand",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "DailyDemand": { "type": "number", "default": 15, "minimum": 0 }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+This writes `settings/demand/settings.sdk.json`. Then create the engine, listing `demand` in its `settings`:
+
+```bash
+pnpm run sdk new engine '{
+  "definition": {
+    "reads": ["bakery"],
+    "writes": ["bakery"],
+    "settings": ["demand"]
+  },
+  "logic": { "directory": ".", "entrypoint": "logic.ts" },
+  "rootDirectory": "."
+}'
+```
+
+This writes `engine/engine.sdk.json`, `engine/logic.ts`, `engine/logic.test.ts`, and a generated `engine/types.ts`.
+
+### 4. Write the logic
+
+Replace the body of `engine/logic.ts`:
+
+```typescript
+import { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
+
+import type { Callbacks, Context, Settings } from './types';
+
+export const Init: InitializationFunction<Context, Settings, Callbacks> = async ({ context }) => {
+    return { capabilities: { ...context, bakery: { ...context.bakery, Sold: 0 } } };
+};
+
+export const Run: RunFunction<Context, Settings, Callbacks> = async ({ context, settings }) => {
+    const sold = Math.min(context.bakery.Loaves, settings.demand.DailyDemand);
+    return {
+        capabilities: {
+            ...context,
+            bakery: { ...context.bakery, Sold: context.bakery.Sold + sold },
+        },
+    };
+};
+```
+
+Always return a new object: spread the context and the capability you change, never assign into them.
+
+### 5. Add a game UI
+
+```bash
+pnpm run sdk new ui '{
+  "definition": {
+    "reads": ["bakery"],
+    "writes": ["bakery"]
+  },
+  "ui": { "entrypoint": "index.html" },
+  "rootDirectory": "."
+}'
+```
+
+This writes `ui/`, the game UI each participant sees. Edit `ui/src/App.tsx` to show `data.bakery` and to write `Loaves` with `setData`; [Building user interfaces](../guides/ui.md) covers both.
+
+### 6. Set how long the game runs
+
+```bash
+pnpm run sdk update package --patch '[{"op":"add","path":"/ticks","value":5}]'
+```
+
+`seriousgaming.sdk.json` now ends the game after five ticks.
+
+## Verify
+
+Play a tick with 10 loaves baked:
+
+```bash
+pnpm run sdk tick --patch '[{"op":"replace","path":"/bakery/Loaves","value":10}]'
+```
+
+The output shows `"completedTicks": 1` and `"Sold": 10`. Then check the package builds and its tests pass:
+
+```bash
+pnpm run sdk build --validate-only
+pnpm typecheck
+pnpm test:run
+```
+
+## Troubleshooting
+
+| Problem                                         | Solution                                                                                                                    |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `new engine` refuses because one already exists | The package was not made with `--empty`. Change the existing engine with `update engine` instead                            |
+| `context.bakery` is a type error                | The engine does not declare `bakery` in `reads` or `writes`. Add it with `update engine`, which regenerates `types.ts`      |
+| `logic.test.ts` fails to typecheck              | Keep the `Callbacks` type argument on `Init` and `Run`: the generated test passes `Callbacks`, not the default callback set |
+| The tick changes nothing                        | Check `Run` returns the new capability object rather than the context it received                                           |
+
+## Related
+
+- [Getting started](../getting-started.md)
+- [Create a capability](./create-capability.md)
+- [Create an engine](./create-engine.md)
+- [Create a settings resource](./create-settings.md)
+- [Create a user interface](./create-user-interface.md)
+- [Shape your game](./create-game.md)
+- [Design state for concurrent writes](./design-state-for-concurrent-writes.md)