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

package/dist/templates/guide/03-running-the-session.md.liquid

@@ -0,0 +1,37 @@
+# Running the session
+
+One section per phase. Use the say, do, and timing admonitions so the script is easy to follow live.
+
+## Briefing
+
+:::say
+Welcome everyone. Today you are running {{ name }}. You will make decisions as a team, see the consequences, and compete with the other teams.
+:::
+
+:::do
+Form the teams and hand each team its device.
+:::
+
+:::timing
+Keep the briefing under 15 minutes. Energy matters more than completeness; the first tick will teach the mechanics.
+:::
+
+## Play
+
+:::do
+Run the first tick once every team has submitted its decisions. Walk the room between ticks and coach teams that are stuck.
+:::
+
+:::warning
+Avoid revealing how the underlying model works during play. Save it for the debrief.
+:::
+
+## Debrief
+
+:::say
+What surprised you? Where did the result differ from what you expected when you made the decision?
+:::
+
+:::tip
+Tie at least one concrete in-game moment back to each learning objective.
+:::

package/dist/templates/hook/logic.test.ts.liquid

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { Run } from './logic';
+import type { Context, Settings, Callbacks } from '../types';
+import type { LogicMeta } from '@seriousgaming/sdk';
+
+// The run-wide facts the host supplies: the session locale, its random seed,
+// whether this is the game being played or a walkthrough beside it, and when
+// the operation started.
+const meta: LogicMeta = { locale: 'en', seed: 'test-seed', runKind: 'session', now: Date.UTC(2026, 0, 1) };
+
+const callbacks = {} as Callbacks;
+
+// The participant the signal concerns, and the roster the hook receives.
+const participant = {
+    id: '1',
+    teamId: 'team-1',
+    name: 'Participant 1',
+    index: 0,
+    connected: true,
+};
+
+describe('{{ identifier }}', () => {
+  describe('Run', () => {
+    it('should update context in response to the signal', async () => {
+      const context: Context = {
+        // TODO: Add context values based on required/provided capabilities
+      } as Context;
+      const settings: Settings = {
+        // TODO: Add values for the settings resources this reads
+      } as Settings;
+
+      // TODO: replace with the payload fields the hook's signal supplies
+      const { capabilities } = await Run({
+        context,
+        settings,
+        callbacks,
+        meta,
+        participant,
+        participants: [participant],
+      } as Parameters<typeof Run>[0]);
+
+      // TODO: Add assertions for updated values
+      expect(capabilities).toBeDefined();
+    });
+  });
+});

package/dist/templates/hook/logic.ts.liquid

@@ -0,0 +1,12 @@
+import type { HookFunction } from '../types';
+
+export const Run: HookFunction = async ({ context, settings, callbacks }) => {
+  // Hooks fire after the runtime applies the lifecycle change.
+  // Return the capabilities it writes under `capabilities`; the runtime merges
+  // and persists them.
+  return {
+    capabilities: {
+      ...context
+    }
+  };
+};

package/dist/templates/package/CLAUDE.md.template

@@ -0,0 +1,338 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this Serious Gaming SDK package. A package is a game.
+
+## Non-negotiables
+
+- **Logic returns what it writes under `capabilities`**, and removes keys with `deletes` beside it. Never mutate `context`: spread
+- **Declare `reads`, `writes`, `settings` and `uses`.** A resource receives exactly what it declares; a write or a service outside them is refused
+- **Await every `setData`**, through `useMutationReporter`, so a refusal reaches the person. Never retry a write automatically
+- **Never start `pnpm start`, `pnpm run sdk dev` or watch-mode `pnpm test`.** The user starts long-running processes
+- **No host globals in logic.** `meta.now`, not `Date.now()`; `meta.seed` with `deriveSeed` and `seededRandom`, not `Math.random()`; no `fetch`, timers or Node built-ins
+- **Use `update`, not `new`, for a slot that is already filled** (`engine`, `ui`, `session`, …). Change bundles through the CLI, not by hand
+- **Never edit a generated `types.ts`, and never use `any`**
+- **Never publish, and never `pnpm add`, unless the user asks**
+
+## Workflows
+
+Before touching a resource, read its rule. A tool that loads only this file still finds them here:
+
+- `capabilities/`: `.claude/rules/workflow-create-capability.md`
+- `engine/`: `.claude/rules/workflow-create-engine.md`
+- `ui/`, `session/`, `waiting_room/`, `setup/`, `scenario_editor/`: `.claude/rules/workflow-create-user-interface.md`
+- `endpoints/`: `.claude/rules/workflow-create-endpoint.md`
+- `guide/`: `.claude/rules/workflow-create-guide.md`
+- `presentation/`: `.claude/rules/workflow-create-presentation.md`
+- Any `*.test.ts` or `*.test.tsx`: `.claude/rules/workflow-test-engine-or-ui.md`
+- `package.json` and an SDK upgrade: `.claude/rules/workflow-update-sdk-version.md`
+- Publishing: `.claude/rules/workflow-publish-package.md`
+
+## Documentation
+
+The SDK's documentation ships inside it, so it describes the version installed here. **Read the recipe before you start a task; do not guess.**
+
+```bash
+pnpm run --silent sdk docs view                                # the documentation tree
+pnpm run --silent sdk docs view recipes/index.md               # every recipe, one line each
+pnpm run --silent sdk docs view recipes/create-hook.md         # one document
+pnpm run --silent sdk docs view cli-reference.md               # every command and flag
+```
+
+The same files are on disk in `node_modules/@seriousgaming/sdk-tools/dist/docs/`, so you can search them with `grep -rn`. Start from `recipes/` for a task, `guides/` for a whole subject, and `concepts/` for the model.
+
+## This package
+
+Unless it was created with `--empty`, this package holds a complete, playable starter game: a lemonade stand, run for 10 days. Each morning a team decides how many lemonades, iced teas, and cookies to make. Whatever they make they pay for, whatever is left at closing is poured away, and anyone who wanted something that ran out simply leaves.
+
+Read it before you change it. It is the reference for four things that are easy to get wrong and expensive to retrofit:
+
+- **State keyed so participants cannot overwrite each other.** `plan.Make` is keyed by menu item, and `hooks/assignproducts/` puts each participant in charge of one item, so two people changing two numbers write two different keys
+- **A validator on the one thing they share.** Two changes can each fit while the merged plan exceeds the stall's capacity, so `validators/capacity/` checks the merged result and refuses it out loud
+- **Awaited writes.** Every `setData` in `ui/` goes through the one mutation reporter in `ui/src/writes.ts`
+- **Teams run their own days.** The game is in independent mode; the facilitator watches from `session/` and can undo
+
+Replace the model freely. Keep the shape. `pnpm run --silent sdk docs view guides/starter-game.md` walks through every file, and `recipes/start-from-an-empty-package.md` picks up an empty package.
+
+### Mental model
+
+A game works like a **reactive spreadsheet**:
+
+- **Capabilities**: column headers (named groups of variables, schema only)
+- **Settings**: read-only parameters, each property with a default, overridden by scenarios
+- **The engine**: the formulas (`Init` sets up, `Run` computes one tick)
+- **User interfaces**: charts and input cells (`ui/` for participants, `session/` for the facilitator, `waiting_room/` before play, `setup/` and `scenario_editor/` for settings)
+- **Validators**: data validation on input cells (reject a write, never change it)
+- **Hooks**: handlers that run outside the tick on a signal such as `participantJoin`
+- **Endpoints**: server-side functions a surface, or with `visibility: "external"` a caller outside the game, calls by identifier
+- **Guide and presentation**: the facilitator's run-sheet and slide deck
+
+Data flows: surfaces write decisions with `setData`, a tick runs the engine, and surfaces show the results.
+
+### Layout
+
+```
+.
+├── seriousgaming.sdk.json   # The package identifier, locales, maxTicks and teams
+├── engine/                  # THE engine: Init and Run
+├── ui/                      # THE participant interface
+├── session/                 # THE facilitator's screen
+├── waiting_room/            # THE holding screen
+├── setup/                   # THE settings form at session creation (sdk new setup)
+├── scenario_editor/         # THE scenario authoring screen (sdk new scenario_editor)
+├── presentation/            # THE slide deck (sdk new presentation)
+├── tick_controller/         # THE timer, for timed rounds (sdk new tick_controller)
+├── guide/                   # THE facilitator guide (markdown per locale, plus assets)
+├── capabilities/<name>/     # Data definitions
+├── settings/<name>/         # Read-only parameters
+├── endpoints/<name>/        # Server-side functions
+├── hooks/<name>/            # Lifecycle handlers
+├── validators/<name>/       # Reject-only gates on writes and tick requests
+├── scenarios/<name>/        # Settings overrides, plus assets
+├── testing/engine/          # Whole-game tests (createTestSession)
+└── testing/e2e/             # Playwright specs, and the global setup that starts their server
+```
+
+A game holds one of each slot resource, so it lives in its slot and carries no name. Everything else sits at `<plural>/<name>/` and is named by its directory: `"identifier": "sales"` makes `capabilities/sales/`, `context.sales`, and `"sales"` in `reads`. A name is lowercase letters, digits, and underscores, starting with a letter. Only the package carries a dotted reverse-DNS identifier, and its game is that identifier with `.game` appended. There is no list to keep in step: a package declares whatever is on disk.
+
+## The loop: edit, validate, test
+
+Pass `--json` to any command (or set `SERIOUSGAMING_JSON=1`) and it prints exactly one JSON document on stdout, success or failure, with progress on stderr. Always invoke it as `pnpm run --silent sdk …`, so no pnpm banner precedes the JSON.
+
+```json
+{ "ok": true, "command": "tick", "data": { "completedTicks": 1 }, "diagnostics": [], "warnings": [] }
+{ "ok": false, "command": "build", "error": { "code": "PACKAGE_INVALID", "message": "…", "hint": "…" }, "diagnostics": [{ "severity": "error", "code": "SETTINGS_UNKNOWN_KEY", "file": "scenarios/hard/scenario.sdk.json", "pointer": "/definition/settings/engine/BaseDemnd", "hint": "Did you mean 'BaseDemand'?", "message": "…" }], "warnings": [] }
+```
+
+After every change, run these in order and stop at the first that fails:
+
+```bash
+pnpm run --silent sdk build --validate-only --json   # the package: bundles, references, settings
+pnpm run typecheck                                   # tsc over the whole package
+pnpm run lint                                        # oxlint, warnings included
+pnpm test:run                                        # unit and component tests beside each resource
+pnpm test:engine                                     # whole games, in-process
+pnpm run --silent sdk tick --no-server --json        # one tick in the restricted production runtime
+```
+
+Branch on `ok`, the exit code and `error.code`, never on the message:
+
+| Exit | Meaning             | What to do                                                                 |
+| ---- | ------------------- | -------------------------------------------------------------------------- |
+| 0    | Success             |                                                                            |
+| 1    | A bug in the CLI    | Report it; do not retry blindly                                            |
+| 2    | Usage error         | Fix the command: a flag, an argument, or input you did not pass            |
+| 3    | Invalid package     | Fix the package: `diagnostics` says which file and where                   |
+| 4    | Refused by the game | The game said no (`REFUSED_VALIDATION`, `TICK_FAILED`, …): read the reason |
+| 5    | Environment         | No session, a port in use, the platform unreachable: fix the environment   |
+
+**On a failure, read `diagnostics[]` first.** `file` is relative to the package root; `pointer` is an RFC 6901 pointer into that JSON file (`/definition/reads/0` is the bundle's first read), and `line` and `column` locate a TypeScript file instead. Open it there, apply the `hint`, and rerun the same command. Branch on each diagnostic's `code` (`SCHEMA_INVALID`, `REFERENCE_UNKNOWN`, `SETTINGS_UNKNOWN_KEY`, `REMOVED_FIELD`, `LOGIC_ERROR`, …). Logic that throws during `init`, `tick` or `endpoint call` exits 4 with a `LOGIC_ERROR` naming the source line, `tick` and `team`. Warnings do not fail a command, but are usually worth fixing.
+
+The CLI never prompts without a terminal: a command that would ask fails with `PROMPT_REQUIRED` (exit 2). Pass definitions as an argument, with `--file`, or on stdin, and pass `--yes` to `delete`. `pnpm run --silent sdk docs view recipes/check-a-package-from-a-script.md` has the whole contract.
+
+## Commands
+
+### Resources
+
+```bash
+pnpm run sdk new capability --help        # every type prints its JSON format with --help
+pnpm run sdk new capability '{...}'       # likewise hook, validator, endpoint, settings, scenario
+pnpm run sdk new setup '{...}'            # an empty slot: setup, scenario_editor, presentation, tick_controller
+pnpm run sdk update engine --patch '[{"op":"add","path":"/definition/writes/-","value":"results"}]'
+pnpm run sdk update capability plan '{...}'                     # full replacement
+pnpm run sdk update package --patch '[{"op":"replace","path":"/ticks","value":12}]'
+pnpm run sdk delete capability plan --yes
+pnpm run generate                         # regenerate types after a hand edit (new and update already do)
+pnpm run build                            # validate, generate and bundle into dist/
+```
+
+A slot command takes no identifier. The starter game fills every slot but `setup`, `scenario_editor`, `presentation` and `tick_controller`, and `new` refuses a filled slot. `update package` changes the manifest, which takes no identifier either.
+
+### Playing the game from the CLI
+
+```bash
+pnpm run --silent sdk init                     # start the session, or rebuild it at tick 0
+pnpm run --silent sdk tick --patch '[{"op":"replace","path":"/plan/Make/lemonade","value":70}]'
+pnpm run --silent sdk patch '[{"op":"replace","path":"/plan/Make/cookies","value":0}]'
+pnpm run --silent sdk view                     # the current state (--full for the whole projection)
+pnpm run --silent sdk undo                     # undo the last tick
+pnpm run --silent sdk reset                    # back to tick 0
+```
+
+Patch paths start at the capability. `--team N` picks the team in a game with several. `pnpm run sdk configure '{"menu":{"Capacity":60}}'` overrides settings for the session, keyed by settings identifier, and restarts a running session on the new values.
+
+**Know which session a command touches:**
+
+- **If a dev server is running**, session commands act on its session, which is what the user is watching
+- **If none is running**, they start one in the background and say so on stderr
+- **With `--no-server`**, they run in-process against a fresh session and leave nothing behind; each starts again at tick 0
+
+Edits to logic and bundles reach a running dev server from its next tick, without a reset. Prefer `--no-server` and `pnpm test:engine` for your own checks. Use the shared session only when the user wants to watch. `pnpm run sdk dev status` says whether a server is running; never stop one you did not start. `pnpm test:e2e` starts an isolated server of its own on free ports, beside the user's.
+
+## How things work
+
+### Reads, writes and what the runtime owns
+
+Every resource declares its data flow as arrays of capability identifiers: `reads` for what it consumes, `writes` for what it produces (a capability may appear in both). A capability you forgot to declare is absent from `context` (or a surface's `data`), and the generated `Context` says so. A game holds one engine; a simulation with several steps calls them as plain functions from its `Run`.
+
+Do not rebuild runtime concerns in context:
+
+- **Ticks**: no `CurrentRound` variable; read `meta.tick`, the tick being run
+- **Time**: `meta.now`, the instant the operation started, which a re-run sees again
+- **Who is on a team**: the read-only `participants` argument, not a roster kept from hooks
+- **Lifecycle**: set `maxTicks` in `seriousgaming.sdk.json`, or return `complete: true` from `Run`. A tick controller is for timed rounds, or ending on a participant's write between ticks
+- **Undo and reset**: built in
+- **Parameters**: a settings resource (`settings/<name>/settings.sdk.json`, a default on every property), read by each resource that lists it in `settings`
+
+`setData` updates context immediately, and other surfaces see it at once; the engine's `Run` sees it on the next tick.
+
+### Logic
+
+Every logic function is async, takes one args object, and returns what it writes under `capabilities`, always by spreading:
+
+```typescript
+import type { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Init: InitializationFunction<Context, Settings> = async ({ context, settings }) => ({
+    capabilities: { ...context },
+});
+
+export const Run: RunFunction<Context, Settings> = async ({ context, meta }) => ({
+    capabilities: {
+        ...context,
+        results: { ...context.results, Day: meta.tick }, // never context.results.Day = …
+    },
+});
+```
+
+- The args are `{ context, settings, callbacks, meta, participants }`, plus `state` for an engine. `settings` is keyed by settings identifier and already resolved for the session; `guides/settings.md` has the order
+- Hooks, aggregate engines (`{ shared: { capabilities }, teams: [{ capabilities }] }`) and writing endpoints (`{ response, capabilities }`) return the same way. A flat return fails the call
+- **To remove a key**, return its path in `deletes` beside `capabilities` (`deletes: [['orders', 'Open', id]]`), under a capability in `writes`. Leaving a key out never removes it
+- `Init` is optional: without it each team starts from the capabilities' defaults
+- `Run` may return `complete: true` to end the game, and an engine may return `state` beside `capabilities` for private memory between ticks (type it with `RunFunction`'s fourth parameter)
+- A step of a split engine is a `StepFunction<Context, Settings>`: steps pass the context flat, and only the exported function wraps the result
+
+### The logic runtime: ECMAScript intrinsics only
+
+Engine, hook, validator, endpoint, and tick controller logic runs in a **bare V8 isolate** in production. `process`, `require`, `fetch`, timers, `structuredClone`, `Buffer`, `TextEncoder`, `URL`, `crypto`, `atob`, `window`, `document` and `localStorage` are absent and throw at tick time. `console.log` is fine.
+
+| Instead of                    | Use                                                            |
+| ----------------------------- | -------------------------------------------------------------- |
+| `structuredClone(v)`          | `JSON.parse(JSON.stringify(v))`                                |
+| `TextEncoder`, `TextDecoder`  | `encodeUtf8`, `decodeUtf8` from `@seriousgaming/sdk`           |
+| `fetch(...)`                  | The injected `callbacks`, or an endpoint                       |
+| `setTimeout(...)`             | Nothing: ticks are the scheduling primitive                    |
+| `process.env.X`               | The `settings` argument                                        |
+| `Math.random()` for kept data | `deriveSeed` and `seededRandom` from the SDK, from `meta.seed` |
+| `Date.now()`, `new Date()`    | `meta.now`                                                     |
+
+Importing a Node built-in (`node:fs`, `path`, `os`, …), directly or through a library, fails `build`, `dev` and `tick` with `LOGIC_NODE_BUILTIN`. `pnpm run lint` refuses the globals above as errors in every logic file, and fails on any warning, so run it before you call logic done. It cannot see `globalThis.fetch`, and it is off for tests, which run in Node: **a green unit test does not prove logic is portable**, so finish with `tick --no-server`.
+
+### Type safety
+
+`variablesSchema` and `settingsSchema` are full JSON Schema 7 objects, and the generated types are only as precise as they are:
+
+- **Wrap every schema**: `type: 'object'`, `properties`, `additionalProperties: false` (and `required` in a `variablesSchema`)
+- **Type every field.** Never a string holding JSON; give an object its `properties` and an array its `items`
+- **Key collections by id** where several people write at once (`additionalProperties` with a schema): two writes to two keys cannot collide, and an entry leaves through `deletes`. See `recipes/design-state-for-concurrent-writes.md`
+- **A `default` must satisfy its own schema**: `build --validate-only` fails one that does not
+
+```json
+{
+    "definition": {
+        "identifier": "market",
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Competitors": {
+                    "type": "object",
+                    "properties": {
+                        "count": { "type": "number", "minimum": 1 },
+                        "priceList": {
+                            "type": "array",
+                            "items": { "type": "number", "minimum": 0 }
+                        }
+                    },
+                    "required": ["count", "priceList"],
+                    "additionalProperties": false,
+                    "default": { "count": 5, "priceList": [10, 15, 20] }
+                }
+            },
+            "required": ["Competitors"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+Every resource with logic or a surface has a generated `types.ts` beside it: `Context` holds exactly the capabilities it declares, `Settings` the settings resources it lists, and `Callbacks` the services in its `uses`. Import from `./types` (or `../types` from a `logic/` directory), never edit it or `defaults.ts`, and never write your own. `pnpm run --silent sdk docs view guides/type-safety.md` has the rest.
+
+### Testing logic
+
+Call a logic function with `logicArgs` from `@seriousgaming/sdk/testing`, which fills `meta`, the roster and offline stub callbacks around what you name; pass the generated `defaultSettings`. A whole game runs in `createTestSession<Context, SharedContext>` (`testing/engine/`), whose `setData` and `requestTick` act as a participant, so validators judge them. Never cast an argument or a context:
+
+```ts
+const result = await Run(
+    logicArgs.run({ context: defaultContext, settings: defaultSettings, meta: { tick: 3 } })
+);
+
+const session = await createTestSession<Context, SharedContext>({ packagePath });
+await session.setData(0, { plan: { Make: { lemonade: 28 } } });
+await session.tick();
+expect(session.team(0).context.results.Day).toBe(1);
+```
+
+## User interfaces
+
+- **Default to MUI** (`@mui/material`), as the starter game does. Another library must integrate with `useUserInterfaceTheme` so colours and dark mode work, and text on a theme colour uses that colour's `contrastText` (`colors.contrastText.primary`)
+- **Await writes.** `setData` rejects when the host refuses the write. Route writes through `useMutationReporter`, as `ui/src/writes.ts` does; on a `conflict`, offer `failure.retry` behind a 'Try again' button
+- **Endpoint calls fail typed.** `callbacks.endpoints['<name>'](request)` rejects with an `EndpointError` whose `kind` says why; a non-empty `applied` means some effects landed. Never retry one automatically
+- **A viewer's own choices** (a tab, a collapsed panel) go in `useViewerStorage(key, initial)`, never `localStorage`, which collides across sessions
+- **Assets and history through the hooks.** `useAssetUrl(ref)` for a `src`, `useAsset(ref, { as })` to read a file (it finds the locale's copy in `<dir>/<locale>/<file>`), and `usePastState(query)` for past rounds, rather than hand-rolled effects. The wrapper already sets `lang`, `dir` and `color-scheme` on the document
+- **Every string** goes through `src/i18n.ts`
+- **The facilitator's screen** is `session/`: rendered full-bleed beneath a thin band of host chrome, it owns teams, participants and game controls (`guides/session.md`)
+
+### Testing a surface
+
+Every surface but the presentation scaffolds an `App.test.tsx`; the starter game's own tests are worked examples, and `pnpm run --silent sdk docs view guides/testing.md` is the reference.
+
+- **Render through the helper**: `renderUserInterface()` from `@seriousgaming/sdk/ui/testing` (or `renderSessionUserInterface<SessionData>()`, or `renderSettingsEditor()` for setup and the scenario editor). It supplies every provider the host does; pass `data`, `settings`, `callbacks` and the rest as options
+- **Never `vi.mock` the SDK, and never wire its providers by hand**
+- **Use `fireEvent.change` on controlled inputs**: the mock `setData` does not update the value between `userEvent.type` keystrokes
+
+## Presentations
+
+The `presentation/` slot holds the facilitator's slide deck, built with `@seriousgaming/deck` at the SDK's version. It reads every team's state and writes nothing. A facilitator exports it to PDF or PowerPoint and edits the copy, so:
+
+- **Use the building blocks** (`Heading`, `Text`, `Bullets`, `Table`) for anything a facilitator might edit; anything else exports as a picture
+- **Render with `session === null`**, showing labelled sample figures where results would go
+- **Branch on settings, not the scenario name**, and draw a custom animation's end state when `useSlide().mode` is `'static'`
+- **Route every word through i18n**, and keep one element per slide
+
+## LLM integration
+
+Logic calls `callbacks.generateText()` only if its bundle lists `generateText` in `uses`; once listed it is always present on the generated `Callbacks`, so call it without `?.`. A surface reaches an LLM only through an endpoint. The dev server needs `SERIOUSGAMING_API_KEY` in the environment or `.env`, and `createTestSession` stubs it offline. See `guides/llm-integration.md`.
+
+## Keeping the SDK up to date
+
+```bash
+pnpm run --silent sdk version              # the installed version
+pnpm run sdk docs view changelog.md        # newest first: read every entry above your version
+pnpm run sdk docs view guides/upgrading.md # a step for each breaking change
+```
+
+Upgrade only when the user asks, or when the changelog has a fix the task needs, and then follow `.claude/rules/workflow-update-sdk-version.md`: it bumps the SDK, its tools and the deck together, and adopts the newer scaffold guidance without overwriting yours.
+
+## Troubleshooting
+
+| Problem                               | Solution                                                                                   |
+| ------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Types not updating                    | `pnpm run generate`                                                                        |
+| A capability is missing in code       | Add it to the resource's `reads` or `writes`; `update` regenerates the types               |
+| A surface's write is refused          | Add the capability to that surface's `writes`                                              |
+| Build failing                         | `pnpm run --silent sdk build --validate-only --json`, then read `diagnostics`              |
+| Edit not showing, or `SETTINGS_STALE` | A setting, `teams` or a capability's scope applies only at init: `sdk init`                |
+| A hook reads empty data in a surface  | Two copies of a package with React context: add it to `resolve.dedupe` in `vite.config.ts` |
+| Anything else                         | `pnpm run --silent sdk docs view troubleshooting.md`                                       |
+
+Keep `DESIGN.md` up to date as the game changes.

package/dist/templates/package/DESIGN.md.liquid

@@ -0,0 +1,144 @@
+# DESIGN.md
+
+This document describes the design of the **{{ name }}** game. Keep it up to date as you build.
+
+Unless it was created with `--empty`, the package was scaffolded with a working game already in it: a lemonade stand, where each team decides every morning how many lemonades, iced teas, and cookies to make, pays for all of it, and pours away what does not sell. The prompts below are written for the game you are going to build instead. Answer them as you replace the model, and delete the examples as you go.
+
+## Overview
+
+**Package identifier:** `{{ identifier }}`
+
+A package is a game. The package keeps its dotted reverse-DNS identifier, set in `seriousgaming.sdk.json`; the game's is that with `.game` appended, and is never authored.
+
+### Purpose
+
+What does this game model, and what decisions does it help players make? Who plays it, and what real-world situation does it stand in for?
+
+**Example:** 'Models a retail inventory system, so store managers feel the trade-off between carrying costs and stocking out.'
+
+### Key concepts
+
+The business concepts the game is made of.
+
+**Example:**
+
+- **Demand**: customers wanting to buy, per day
+- **Inventory**: stock on hand
+- **Reorder point**: the level that triggers an order
+- **Lead time**: days between ordering and delivery
+
+### Assumptions and constraints
+
+What the model simplifies, and what it deliberately leaves out.
+
+**Example:**
+
+- Demand is predictable, with no seasonality
+- Lead times are constant
+- Orders arrive whole rather than split across shipments
+
+---
+
+## Session shape
+
+- **Ticks:** how many rounds, and what one round represents
+- **Teams:** `independent` (each team on its own clock, and the default when `teams.mode` is omitted) or `shared-state` (every team advances together and can interact through shared capabilities)
+- **Participants per team:** and whether several people write the same context at once, which is the thing that decides how state below has to be shaped
+- **Locales:** which, and which is first (the game's name comes from the first)
+
+---
+
+## Capabilities
+
+`capabilities/<name>/`: the game's state, one named group of variables each. A capability is named by its directory, so the identifier is a short name and the bundle authors none.
+
+### `<name>`
+
+**Purpose:** why this data exists.
+
+**Variables:**
+
+- `VariableName` (type): what it means and its units. Default: value
+
+**Example:**
+
+```
+- `DailyDemand` (number): customers per day. Default: 50
+- `LeadTime` (number): days to receive an order. Default: 3
+```
+
+**Scope:** `team` (default), `team-readable` (other teams' surfaces may observe it live), `shared` (one value for the whole session, written by an aggregate engine in a shared-state game or by the session interface), or `private` (engine bookkeeping, never delivered to any surface).
+
+**Written by:** the engine, a user interface, or both. If several participants on one team write it at the same time, say how it is shaped to survive that: a collection keyed by id rather than an array, and deletion rather than a sentinel.
+
+---
+
+## Engine
+
+`engine/`: the code that computes the game. A game holds exactly one.
+
+**Reads:** the capabilities it consumes, and why each is needed.
+
+**Writes:** the capabilities it produces, and what it computes into them.
+
+**Settings:** the settings resources it lists in `settings`: each property, its type, its default, and what it changes.
+
+**What `Run` does**, in order. A simulation with several steps calls them as plain functions from its one `Run`:
+
+```
+1. Read the decisions the team submitted
+2. Work out demand from settings and the round
+3. Update inventory
+4. Compute revenue, costs and profit
+```
+
+**Aggregate?** If a shared-state game's engine needs every team's context at once (a market price, a ranking, anything cross-team), export `InitAggregate` and `RunAggregate` beside `Init`. There is no flag to set: the build reads the exports. A per-team `Run` is optional and runs for every team before `RunAggregate` is called once, so a step that must follow the aggregate is called from inside `RunAggregate` rather than from `Run`. The aggregate functions receive shared capabilities once, as `shared.context`, and each team's own capabilities in `teams`, and write shared ones under `shared` only.
+
+**Edge cases:** what happens at the boundaries, and anything that must hold true whatever the input.
+
+---
+
+## User interfaces
+
+**`ui/`**: the participant surface. A game holds one, so several views are components inside it rather than separate resources.
+
+- **Reads / writes:** the capabilities it renders and the ones players change through it
+- **Views:** the tabs or panels, and what each is for
+- **How a player submits:** what they change, and what tells them a write did not land
+
+**`session/`**: the facilitator surface. What the facilitator watches, and what they can change mid-session.
+
+**`waiting_room/`**: what players see before the session opens, if the game has one.
+
+**`setup/`** and **`scenario_editor/`**: the form a facilitator fills in at session creation, and the screen for authoring lasting scenarios, if the game has them, and which settings resources each `configures`.
+
+---
+
+## The rest
+
+Only the ones this game uses.
+
+- **`hooks/<name>/`**: one lifecycle signal each (a player joining, for example), run outside the tick. Numbered directories where order matters
+- **`validators/<name>/`**: a read-only gate that rejects a UI write. Reach for one where a contested write cannot be fixed by the shape of the state
+- **`endpoints/<name>/`**: server-side work a UI, or with `visibility: "external"` a caller outside the game, calls by identifier. It is how a surface reaches an LLM or a document parser, and, with `writes`, how it changes state outside the tick
+- **`tick_controller/`**: when a round ends on its own rather than on the facilitator's say-so, or when the game must end on a participant's write between ticks. A game ends by setting `maxTicks`, or by returning `complete: true` from the engine's `Run`
+- **`scenarios/<name>/`**: settings overrides, keyed by settings identifier, plus any assets that change with them
+- **`guide/`**: the facilitator's guide, as numbered markdown chapters under `content/<locale>/`
+
+---
+
+## Design decisions
+
+### Why the state is shaped this way
+
+Why these capabilities, and why the boundaries fall where they do.
+
+**Example:** 'Pricing and sales are separate capabilities because a later scenario changes how price is set without touching how sales are computed.'
+
+### Decisions taken and not revisited
+
+Choices someone will otherwise reopen, with the reason they were made.
+
+### Not built yet
+
+What is deliberately out of scope, and what might come later.