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

package/dist/templates/package/README.md.liquid

@@ -0,0 +1,143 @@
+# {{ name }}
+
+A Serious Gaming game package created with the Serious Gaming SDK.
+
+It starts as a complete, playable simulation rather than a blank page: 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. The whole game is the balance between making too
+much and too little.
+
+Keep it, change the numbers, or replace the model entirely. What is worth
+keeping either way is the shape around it: state keyed so two people on one team
+cannot overwrite each other, a validator on the one thing they share (the
+stall's capacity), every write awaited so a refusal reaches the person who made
+it, and teams that each open their stall when they are ready.
+
+If the package was created with `--empty`, none of the game is here, only the
+package files: `pnpm run sdk docs view recipes/start-from-an-empty-package.md`
+picks up from there.
+
+## Getting started
+
+Dependencies are installed and types generated when the package is created. If
+the install failed, run `pnpm install` once the cause is fixed.
+
+### Play it
+
+Start the development server:
+
+```bash
+pnpm start
+```
+
+It opens the facilitator console at `http://localhost:3000`. Open
+`http://localhost:3000/team/1/player/1` in another tab for the first
+participant on team 1, then switch off **Waiting room** in the console to let
+them in. Press the backtick key on any page for the dev drawer: tick, undo, and
+reset controls, and the state as JSON.
+
+Edits to logic, UIs, `*.sdk.json` bundles and `seriousgaming.sdk.json` reach
+the running game without a restart. A settings change, which reaches the game
+through `Init`, waits for you to re-initialise once a round has been played:
+the console says so and offers a button.
+
+### Drive it from the CLI
+
+```bash
+pnpm run sdk tick --patch '[{"op":"replace","path":"/plan/Make/lemonade","value":70}]'
+pnpm run sdk view
+```
+
+Session commands act on the running dev server's session. With none running,
+they start one in the background; `pnpm run sdk dev status` and
+`pnpm run sdk dev stop` check on it and stop it. Add `--no-server` to run a
+command in-process against a fresh session instead.
+
+### Build your package
+
+Validate, generate types, and bundle the game into `dist/`:
+
+```bash
+pnpm run build
+```
+
+## Project structure
+
+```
+.
+├── seriousgaming.sdk.json  # The package identifier, locales, maxTicks and teams
+├── engine/                 # THE engine: one day at the stall
+├── ui/                     # THE participant interface: plan, open, review
+├── session/                # THE session interface: the facilitator's screen
+├── waiting_room/           # THE holding screen, shown before and between
+├── guide/                  # THE facilitator guide, as markdown chapters
+├── presentation/           # THE slide deck the facilitator projects (add with `new presentation`)
+├── setup/                  # THE form a facilitator fills in at session creation (`new setup`)
+├── scenario_editor/        # THE editor for authoring lasting scenarios (`new scenario_editor`)
+├── capabilities/           # The shape of the game's state
+├── settings/               # Read-only parameters, each with a default
+├── validators/             # Reject-only gates on what a surface may write
+├── hooks/                  # Lifecycle handlers, outside the tick
+├── endpoints/              # Server-side functions a surface calls by name (`new endpoint`)
+├── scenarios/              # Settings overrides (an ordinary week, a heatwave)
+├── testing/                # Whole-game tests and Playwright specs
+├── dist/                   # Built output (generated)
+├── package.json            # Package manifest
+└── tsconfig.json           # TypeScript configuration
+```
+
+## Running the tests
+
+```bash
+pnpm test:run      # the engine's arithmetic, and every surface
+pnpm test:engine   # the whole game, day by day, in-process
+pnpm test:e2e      # the surfaces in a browser, against a dev server of its own
+```
+
+`test:e2e` starts an isolated dev server of its own on free ports, so it runs
+beside the one you are working in and leaves that session alone.
+
+## Adding resources
+
+### Create a capability
+
+Capabilities define the data the engine and interfaces work with:
+
+```bash
+pnpm run sdk new capability
+```
+
+### Change the engine or an interface
+
+A game holds one engine, one participant interface, one session interface, and
+one waiting room, and the starter game already has each. Edit their code
+directly, and change their bundles with `update`:
+
+```bash
+pnpm run sdk update engine --help
+pnpm run sdk update ui --help
+```
+
+### The rest
+
+`pnpm run sdk new --help` lists every resource type, including validators,
+hooks, endpoints, scenarios, tick controllers, setup, and the scenario editor.
+
+A package is a game, so there is no `new game`: the game's locales, ticks and
+teams live in `seriousgaming.sdk.json` beside the package identifier, its
+parameters live in `settings/`, and every resource is discovered from the
+directory it sits in.
+
+## Learn more
+
+```bash
+pnpm run sdk docs view getting-started.md
+pnpm run sdk docs view guides/starter-game.md
+pnpm run sdk docs view recipes/index.md
+```
+
+The same documents are on disk in
+`node_modules/@seriousgaming/sdk-tools/dist/docs/`, and
+describe the SDK version you have installed.

package/dist/templates/package/claude/rules/workflow-create-capability.md

@@ -0,0 +1,26 @@
+---
+paths:
+    - '**/capabilities/**'
+---
+
+# Workflow: Create a capability
+
+Capabilities are the data definitions the engine and UIs read from and write to. Use the SDK CLI rather than hand-editing `capability.sdk.json`.
+
+## Order of operations
+
+1. **Read the full recipe** before you start:
+    ```bash
+    pnpm run --silent sdk docs view recipes/create-capability.md
+    ```
+2. **Create the capability** with `pnpm run sdk new capability '{ ... }'`. `definition.identifier` is a short lowercase name (`sales`), which becomes the directory `capabilities/sales/` and the key `context.sales`. The `variablesSchema` must be a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`), not a properties-only object. Set `scope` (`team` by default, or `team-readable`, `shared`, `private`) if the capability is not private to each team.
+3. **Declare it** in the `reads` or `writes` of every resource that uses it (`pnpm run sdk update engine --patch '[...]'`, and so on). A resource is handed only the capabilities it declares.
+4. **Verify**: `pnpm run build` should pass without type errors. `new` and `update` regenerate types; run `pnpm run generate` yourself only after editing a bundle by hand.
+
+## Things that almost always go wrong
+
+- Forgetting to add the capability to a resource's `reads` or `writes`: it is absent from that resource's `context` and generated `Context`
+- Using a properties-only schema: the CLI assumes the full Draft 7 object shape everywhere
+- Putting JSON in a `string`-typed field. Use `object` or `array` types so the generated types stay precise
+- Using an array for something several participants add to at once: the last write wins. Key it by id instead (see `pnpm run --silent sdk docs view recipes/design-state-for-concurrent-writes.md`)
+- A `default` that does not satisfy its own schema: `pnpm run sdk build --validate-only` fails it

package/dist/templates/package/claude/rules/workflow-create-endpoint.md

@@ -0,0 +1,35 @@
+---
+paths:
+    - '**/endpoints/**'
+---
+
+# Workflow: Create an endpoint
+
+Endpoints are named, server-side handlers that user interfaces (and, when its `visibility` is `external`, callers outside the game such as a facilitator's AI agent) invoke by identifier. The author owns the request and response schemas; the runtime validates both, builds a scoped context snapshot from the declared `reads` and `writes`, builds guarded callbacks for the declared `uses`, runs `Handle` (or `Plan` then `Respond`), and returns the response to the caller. An endpoint changes game state only if it declares `writes` or `actions`. Use the SDK CLI to scaffold it rather than hand-editing `endpoint.sdk.json`.
+
+## Order of operations
+
+1. **Read the full recipe** before you start:
+    ```bash
+    pnpm run --silent sdk docs view recipes/create-endpoint.md
+    ```
+2. **Decide the request and response shapes.** Each is a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`).
+3. **Decide what it touches**: which capabilities it `reads`, which it `writes` (if any), which settings resources it reads (`settings`), which runtime callbacks it `uses` (`generateText`, `extractText`, `generateSpeech`, `writeBlob`), which session `actions` it may return (such as advancing a tick or closing the waiting room), whether its `session` argument needs each team's participants (`roster: true`), and its `scope`: `team` (the default: it acts on the calling team's board) or `session` (for a session UI, setup screen, or scenario editor, which has no team of its own).
+4. **Create the endpoint** with `pnpm run sdk new endpoint '{ ... }'`, declaring `identifier`, `requestSchema`, `responseSchema`, and whichever of `reads`, `writes`, `settings`, `uses`, `actions`, `roster`, `scope`, `visibility`, and `description` apply. An outside caller, such as an AI agent, reads `description` to decide whether to call an external endpoint, so write it for that reader. An external endpoint's `requestSchema` must be `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`); one taking no input declares an object with no properties.
+5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
+6. **Allow the UI to call it.** Add the endpoint identifier to the `endpoints` array in the bundle of every UI that should be permitted to call it (`pnpm run sdk update ui --patch '[...]'`). Without this, the host rejects the call and TypeScript flags it. The UI then calls `callbacks.endpoints['<name>'](request)`.
+7. **Add a unit test** in the scaffolded `endpoints/<name>/logic/logic.test.ts` covering the happy path and any branch in `Handle`.
+8. **Verify**: `pnpm run sdk endpoint list` shows its scope and whether it writes; `pnpm run --silent sdk endpoint call <name> --no-server --team 1 --request '{...}'` runs it without a UI; then `pnpm run build` and `pnpm test:run`.
+
+## Things that almost always go wrong
+
+- Returning a value that does not match `responseSchema`: the runtime rejects it before delivery, and the UI's call rejects with an `EndpointError` of kind `invalid-response`
+- Treating a failed call as one that changed nothing: an `EndpointError` whose `applied` is non-empty means the write and earlier actions landed before a later action failed. Tell the person so, and never retry the call automatically
+- Using a capability not listed in `reads` or `writes`: it is not in `context`
+- Calling a callback not listed in `uses`: the runtime throws
+- Forgetting to add the endpoint identifier to the UI's `endpoints` array: the host rejects every call from that UI
+- Returning a capability outside `writes` in `capabilities`: the whole call fails and none of the change is applied
+- Returning a bare value from an endpoint that declares `writes` or `actions`, or `{ response, capabilities }` from one that declares neither
+- Calling a team-scoped endpoint from a session UI, setup screen, or scenario editor: the build fails. Set `"scope": "session"`
+- Listing an endpoint with `reads`, `writes` or `actions` in the scenario editor: the build fails (`EDITOR_ENDPOINT_STATEFUL`). The editor has no session, so its endpoints read their `settings`, resolved from the scenario being edited, and nothing else
+- Returning binary data inline: declare `'writeBlob'` in `uses`, call `callbacks.writeBlob(bytes, { name, mimeType })`, and return the resulting `blob:<id>` reference in the JSON response

package/dist/templates/package/claude/rules/workflow-create-engine.md

@@ -0,0 +1,35 @@
+---
+paths:
+    - '**/engine/**'
+---
+
+# Workflow: Create or change the engine
+
+The engine runs each tick. It reads from capabilities and returns the ones it writes under `capabilities`. A game holds one engine, in the `engine/` slot, so its commands take no identifier. Use the SDK CLI to change its bundle rather than hand-editing `engine.sdk.json`.
+
+## Order of operations
+
+1. **Read the full recipe** before you start:
+    ```bash
+    pnpm run --silent sdk docs view recipes/create-engine.md
+    ```
+2. **Confirm the capabilities exist.** An engine reads and writes capabilities by their short names (`plan`, `results`). Create any that are missing first (see the create-capability workflow).
+3. **Change or create the bundle.** The starter game already has an engine, so change it with `pnpm run sdk update engine --patch '[...]'` (or a full `update engine '{ ... }'`); `new engine` refuses while `engine/` exists. In an empty package, `pnpm run sdk new engine '{ ... }'`. Declare every capability the engine reads or writes in `reads` / `writes`, and every settings resource it reads in `settings`. A tunable value belongs in a settings resource (`pnpm run sdk new settings`): a full JSON Schema 7 object, with a `default` on every property.
+4. **Implement `Init` and `Run`** in `engine/logic.ts`. Both are async, both take `{ context, settings, callbacks, meta }`, and both return `{ capabilities: Context }`. Never mutate `context`: always spread. Optionally, return `state` beside `capabilities` for memory only the engine needs between ticks (it comes back as `state`; type it with `RunFunction`'s fourth parameter), and return `complete: true` from `Run` to end the game for that team. A simulation with several steps calls them as plain functions from its one `Run`: type each as `StepFunction<Context, Settings>`, pass the context along flat, and wrap only the final one.
+5. **Check the types.** `new` and `update` regenerate `engine/types.ts`; run `pnpm run generate` yourself only after editing the bundle by hand.
+6. **Test it.** Unit tests go in `engine/logic.test.ts`, covering at least the happy path and every branch in `Run`. Whole-game behaviour across several ticks goes in `testing/engine/` and runs with `pnpm test:engine`.
+7. **Verify**: `pnpm run build`, `pnpm test:run`, `pnpm test:engine`, and `pnpm run --silent sdk tick --no-server`, which runs the logic in the restricted production runtime. A running dev server picks up the edit from its next tick, without a reset.
+
+## Things that almost always go wrong
+
+- Using a capability that is not declared in `reads` / `writes`: it is absent from `context` and from the generated `Context`
+- Mutating `context` directly instead of returning a fresh object via spread
+- Returning the capabilities flat (`{ ...context }`) instead of under `capabilities`: the runtime fails the call
+- Trying to remove a map entry by leaving it out of `capabilities`: a key you leave out keeps its value. Return its path in `deletes` beside `capabilities` instead (`deletes: [['orders', 'Open', id]]`), under a capability in `writes`
+- Using a host global (`structuredClone`, `setTimeout`, `fetch`, `crypto`): production logic runs in a bare V8 isolate. `pnpm run lint` catches most of them
+- Importing a Node built-in (`node:fs`, `path`, `os`, and so on), directly or through a library: the build, `dev` and `tick` refuse it with `LOGIC_NODE_BUILTIN`
+- Using `Math.random()` for anything you keep: derive it from `meta.seed` with `deriveSeed` and `seededRandom`, since a tick may run more than once
+- Calling `Date.now()` or `new Date()`: read `meta.now`, the instant the operation started, which every team's `Run` in one tick and a re-run of it share
+- Keeping a roster in context from `participantJoin` hooks: `Init`, `Run` and the tick controller receive `participants`, the team's roster as the tick started
+- Expecting an edit to replay the ticks already played: a logic edit changes the next tick only. Undo and tick again, or reset to re-run `Init`
+- Using `any` in engine signatures instead of the generated `Context` and `Settings` types

package/dist/templates/package/claude/rules/workflow-create-guide.md

@@ -0,0 +1,40 @@
+---
+paths:
+    - '**/guide/**'
+---
+
+# Workflow: Create a facilitator guide
+
+Facilitator guides are content, not code: per-locale markdown chapters plus shared images, rendered natively on the facilitator's page. A game holds one guide, in the `guide/` slot, so its commands take no identifier. Scaffold it with the SDK CLI rather than hand-creating the bundle file.
+
+## Order of operations
+
+1. **Read the full recipe** before you start:
+    ```bash
+    pnpm run --silent sdk docs view recipes/create-guide.md
+    ```
+2. **Create or change the guide.** The starter game already has one, so edit its chapters directly and change its bundle with `pnpm run sdk update guide`; `new guide` refuses while `guide/` exists. In an empty package, `pnpm run sdk new guide '{ ... }'`. Declare every locale up front: the scaffold creates a chapter skeleton per declared locale, and the per-locale `name` is the title the host renders.
+3. **Write the chapters** in `guide/content/<locale>/`. Chapters are ordered by file name (number them `01-`, `02-`, …) and file names must be identical across locales.
+4. **Validate**: `pnpm run sdk build --validate-only`. This warns on missing translations and fails on malformed video blocks or image references that do not resolve. There is nothing to wire: a `guide/` directory beside `seriousgaming.sdk.json` is served.
+
+## Content format
+
+- Admonitions are container directives: `:::note`, `:::warning`, `:::tip`, plus the facilitation-specific `:::say`, `:::do`, and `:::timing`. Unknown types render as error blocks
+- Headings build the table of contents (chapter H1 plus H2 to H3); end a heading with `{-}` to omit it
+- Images go in the shared `assets/` directory, referenced relatively (`../../assets/diagram.png` from a chapter)
+- Video embeds are fenced `video` blocks validated against a closed registry (YouTube only):
+    ````markdown
+    ```video
+    provider: youtube
+    id: dQw4w9WgXcQ
+    ```
+    ````
+- Raw HTML never renders: it is escaped to visible text. Use markdown, admonitions, and video blocks only
+
+## Things that almost always go wrong
+
+- Chapter file names differing between locales: the runtime matches chapters by file name, so a renamed translation is treated as missing and falls back
+- Invalid YouTube ids: the id must match the 11-character format exactly; anything else renders an inert error block
+- Writing HTML for layout: it will appear as escaped text. Tables, admonitions, and images cover the supported layouts
+- Breaking the structure `guide/guide.test.ts` checks (in the starter game): run `pnpm test:run` after editing chapters
+- A guide a new facilitator could not run the session from alone: if a step lives only in the designer's head, write it down

package/dist/templates/package/claude/rules/workflow-create-presentation.md

@@ -0,0 +1,37 @@
+---
+paths:
+    - '**/presentation/**'
+---
+
+# Workflow: Create or change the presentation
+
+The presentation is the facilitator's slide deck, shown on their screen and projected to the room. A game holds one, in the `presentation/` slot, so its commands take no identifier. It is read-only: it declares `reads` and `settings`, never `writes`, `uses` or `endpoints`. It is built with `@seriousgaming/deck` (`Deck`, `Slide`, `Step`, and the building blocks `Heading`, `Text`, `Bullets`, `Table`, `Image` and `Chart`).
+
+## Order of operations
+
+1. **Read the full recipe** before you start:
+    ```bash
+    pnpm run --silent sdk docs view recipes/create-presentation.md
+    ```
+2. **Check the deck library is installed.** `package.json` must list `@seriousgaming/deck` at the same version as `@seriousgaming/sdk`. If it does not, add it at that version before anything else
+3. **Create or change the bundle.** In a package without one, `pnpm run sdk new presentation '{ ... }'`. Otherwise change its `reads` and `settings` with `pnpm run sdk update presentation --patch '[...]'`, then `pnpm run sdk generate`
+4. **Write the slides** in `presentation/src/`. Every element of the slides array is one slide; give each a stable `key`
+5. **Check both ways it is shown**: `/presentation` during a session and `/presentation?preview` with none, once the user has started `pnpm run sdk dev`. Then `pnpm run build`
+
+## Habits that keep an export faithful
+
+A facilitator exports the deck and edits the PowerPoint, where words are editable and visuals are pictures. `pnpm run --silent sdk docs view guides/presentation.md` explains each habit; hold to them:
+
+- **Use the building blocks** (`Heading`, `Text`, `Bullets`, `Table`) for anything a facilitator might edit
+- **Render with `session === null`**, showing labelled sample figures where results would go
+- **Branch on settings, not the scenario name**
+- **Draw a custom animation's end state** when `useSlide().mode` is `'static'`
+- **Route every word through i18n**, and keep one element per slide
+
+## Things that almost always go wrong
+
+- Reading `session.data` without checking `session` first: the no-session preview breaks
+- A slide that comes and goes with a setting but has no `key`: the remembered position lands on the wrong slide
+- Branching on `game.scenarioName`: the deck shows the wrong slides for a facilitator's saved scenario
+- A chart or diagram drawn as text the facilitator expects to edit: it exports as a picture, so put the words they will change in a `Text` or `Table` beside it
+- A word written straight into a slide rather than added to `src/i18n.ts`: it stays in English whatever the session's language

package/dist/templates/package/claude/rules/workflow-create-user-interface.md

@@ -0,0 +1,31 @@
+---
+paths:
+    - '**/ui/**'
+---
+
+# Workflow: Create or change a user interface
+
+A user interface is a React app that reads game state and (optionally) sends decisions back via `setData`. A game holds one participant interface, in the `ui/` slot, so its commands take no identifier; `session/` and `waiting_room/` are the facilitator's screen and the holding screen, and work the same way. Use the SDK CLI to change a bundle rather than hand-editing `ui.sdk.json`.
+
+## Order of operations
+
+1. **Read the full recipe** before you start:
+    ```bash
+    pnpm run --silent sdk docs view recipes/create-user-interface.md
+    ```
+2. **Confirm the capabilities exist.** A UI reads (and optionally writes) capabilities by their short names. Create any that are missing first.
+3. **Change or create the bundle.** The starter game already has a `ui/`, so change it with `pnpm run sdk update ui --patch '[...]'`; `new ui` refuses while `ui/` exists. In an empty package, `pnpm run sdk new ui '{ ... }'`. Declare every capability the UI shows in `reads`, and add `writes` only for the ones it sends back via `setData`. A UI receives exactly what it declares.
+4. **Implement the components** under `ui/src/` (the entry component is `App.tsx`), with `useUserInterfaceData()` for `data`, `settings`, `setData` and `completedTicks`. Default to MUI; another library must integrate with `useUserInterfaceTheme` so dark mode and colour palettes work, and text on a theme colour uses that colour's `contrastText`. Remember a viewer's own choices with `useViewerStorage`, never `localStorage`. Put every string in `src/i18n.ts`. `pnpm run --silent sdk docs view guides/ui.md` is the reference for every hook.
+5. **Await every write.** `setData` returns a promise that rejects when the host refuses the write. Route writes through `useMutationReporter`, as the starter game's `ui/src/writes.ts` does, so the participant sees the refusal. Never retry a write automatically: on a `conflict` the host has already retried and given up, so offer `failure.retry` behind a 'Try again' button instead.
+6. **Add a test** beside the component (`App.test.tsx`), rendered with `renderUserInterface()` (or `renderSessionUserInterface<SessionData>()`, `renderSettingsEditor()`) from `@seriousgaming/sdk/ui/testing`, as the starter game's tests do. `pnpm run --silent sdk docs view guides/testing.md` has the harness.
+7. **Verify**: `pnpm run build` and `pnpm test:run`. A running dev server hot-reloads the UI. The user starts the dev server (`pnpm run sdk dev`) when they want to see it; never start it yourself.
+
+## Things that almost always go wrong
+
+- Mocking the SDK contexts with `vi.mock`, or wiring a few providers by hand: the hand-wired version throws once the component uses callbacks or participants. Use `renderUserInterface()` instead, so the component renders as it does in production
+- Forgetting `useUserInterfaceTheme` integration when using a non-MUI styling solution: the UI renders in the wrong colour scheme
+- Writing a capability that is not declared in `writes`: `setData` for it is refused
+- Calling `setData` without awaiting it: a refused write leaves the participant looking at a decision the game never received
+- Expecting the engine's settings to reach the UI: a UI's `settings` holds only the settings resources the UI itself lists in `settings`, never those the engine lists, even for an engine whose capability it reads. List the settings resource in the UI's `settings` too, or write the value into context from the engine and read it via `data`
+- Calling an LLM from the UI: a UI reaches external services only through an endpoint it lists in its `endpoints` array
+- Using `userEvent.type` on controlled inputs in tests: the mock `setData` does not propagate, so the input value never updates between keystrokes. Use `fireEvent.change`

package/dist/templates/package/claude/rules/workflow-publish-package.md

@@ -0,0 +1,54 @@
+---
+paths:
+    - 'seriousgaming.sdk.json'
+---
+
+# Workflow: Publish this package
+
+`pnpm run sdk package publish` builds (if needed), bundles, and uploads this package to the Serious Gaming platform. Uploads are scoped to a publisher, so the command needs both an API key and a publisher slug.
+
+## Before you publish
+
+You need:
+
+- An API key (`sg_<lookupId>_<secret>`), issued from your organisation's settings page by an account with publishing access. Business Simulations grants that access; if the user's account lacks it, `publish` fails with a 403 and only they can ask for it
+- The slug of the publisher you upload under
+- A bumped version: the platform rejects re-uploads of a version that already exists
+
+## Order of operations
+
+1. **Configure the key and publisher once.** Either put them in `.env` in this directory (and keep `.env` git-ignored):
+    ```bash
+    SERIOUSGAMING_API_KEY=sg_your_lookup_id_your_secret
+    SERIOUSGAMING_PUBLISHER=your-publisher-slug
+    ```
+    Or have the user store them in the global settings file, so every project picks them up (this writes to their home directory, so leave it to them):
+    ```bash
+    pnpm run sdk config set platform.apiKey sg_your_lookup_id_your_secret
+    pnpm run sdk config set platform.defaultPublisher your-publisher-slug
+    ```
+2. **Bump the version** (the platform rejects a duplicate):
+    ```bash
+    pnpm run sdk package version patch
+    ```
+3. **Build and publish**:
+    ```bash
+    pnpm run sdk build
+    pnpm run sdk package publish
+    ```
+    The command runs `package bundle` itself when the zip is missing. On success it prints the hosted `PackageVersionResponse`.
+4. **Capture the result in CI** with `--json`. The envelope's `data` is the `PackageVersionResponse`, and a failure carries a code: `PLATFORM_UNAUTHORISED` (exit 5), `VERSION_EXISTS` or `PLATFORM_REJECTED` (exit 3):
+    ```bash
+    pnpm run --silent sdk package publish --json > publish.json
+    ```
+
+## Resolution and overrides
+
+The publisher slug resolves from (highest priority first): `--publisher <slug>`, the `SERIOUSGAMING_PUBLISHER` env var, then `platform.defaultPublisher` in global settings. The API key and the host follow the same order: the flag (`--api-key`, `--host`), then the environment (`SERIOUSGAMING_API_KEY`, `SERIOUSGAMING_API_HOST`, from the shell or `.env`), then global settings (`platform.apiKey`, `platform.apiHost`). The default host is `https://app.businesssimulations.com`; override it with `--host` or `SERIOUSGAMING_API_HOST` for a staging target.
+
+## Things that almost always go wrong
+
+- **No publisher configured.** The command fails rather than guessing. Set `SERIOUSGAMING_PUBLISHER`, pass `--publisher`, or set `platform.defaultPublisher`
+- **Uploading under the wrong publisher.** The first upload binds this package to a publisher; later versions must use the same one or you get a 400 naming the registered publisher. Do not switch publishers to dodge the error
+- **Version already exists (409).** Bump with `pnpm run sdk package version patch` and retry
+- **Committing the API key.** Keep it in `.env` (git-ignored) or the global settings file, never in tracked source or shell history

package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md

@@ -0,0 +1,30 @@
+---
+paths:
+    - '**/*.test.ts'
+    - '**/*.test.tsx'
+---
+
+# Workflow: Test an engine or user interface
+
+Unit and component tests live next to the source they cover: the engine's `engine/logic.test.ts` beside `engine/logic.ts`, a hook's, validator's, or endpoint's `logic/logic.test.ts` beside its `logic.ts`, and a UI's `*.test.tsx` beside its components. `pnpm test:run` runs them all. Whole-game tests live in `testing/engine/` and run with `pnpm test:engine`; Playwright specs live in `testing/e2e/` and run with `pnpm test:e2e`.
+
+## Order of operations
+
+1. **Read the full recipe** that matches what you're testing:
+    ```bash
+    pnpm run --silent sdk docs view recipes/test-user-interface.md   # for UI components
+    pnpm run --silent sdk docs view recipes/test-with-engine.md   # for whole games across several ticks
+    ```
+2. **For logic**, call `Init`, `Run`, a hook, an endpoint or a validator directly with arguments built by `logicArgs` from `@seriousgaming/sdk/testing` (`logicArgs.run({ context, settings: defaultSettings })`), and assert on the returned `capabilities`. For behaviour across several ticks, hooks, validators, endpoints, participants, undo or automatic ticks, use `createTestSession<Context, SharedContext>` in `testing/engine/`: it runs the session the dev server runs, in-process, with offline stubs for `generateText`, `generateSpeech` and `extractText`. The references are `pnpm run --silent sdk docs view guides/testing.md` and `guides/engine-testing.md`.
+3. **For UI components**, render with `renderUserInterface()` (or `renderSessionUserInterface()`, or `renderSettingsEditor()` for setup and the scenario editor) from `@seriousgaming/sdk/ui/testing`, which supplies every provider the host does. Never `vi.mock` the SDK contexts, and never wire the providers by hand. For a session UI, pass the generated types: `renderSessionUserInterface<SessionData>()`, with fixtures from `createMockTeamState<TeamContext>()` and `createMockSharedState<SharedContext>()`, so a shared capability left on a team fixture fails to compile.
+4. **Cover the branches.** One test per code path: the happy path plus each failure mode, each option flag, each conditional in `Run`.
+5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server of its own on free ports (`testing/e2e/global-setup.ts`), beside any the user has running.
+
+## Things that almost always go wrong
+
+- Mocking the SDK contexts with `vi.mock` instead of wrapping with the real providers: the test now exercises the mock, not the component
+- Using `userEvent.type` on controlled inputs: the mock `setData` does not propagate, so subsequent keystrokes see the original value. Use `fireEvent.change`
+- Asserting on internal implementation (props, state) instead of observable output (rendered text, `setData` arguments)
+- Taking a green unit test as proof the logic runs in production: tests run in Node, where host globals exist. `pnpm run --silent sdk tick --no-server` runs a tick in the restricted runtime
+- Casting arguments (`as never`, `{} as Callbacks`) or a session's context: `logicArgs` and the typed session make every cast unnecessary, and a cast hides the shape error the test exists to catch
+- Skipping a test for a new resource: the scaffold creates the test file for a reason

package/dist/templates/package/claude/rules/workflow-update-sdk-version.md

@@ -0,0 +1,43 @@
+---
+paths:
+    - 'package.json'
+---
+
+# Workflow: Update the SDK version
+
+The SDK ships as three npm packages: `@seriousgaming/sdk` (runtime), `@seriousgaming/sdk-tools` (CLI and dev server), and `@seriousgaming/deck` (the presentation's deck library). Update them in lockstep and read the changelog before rebuilding.
+
+## Order of operations
+
+1. **Check the installed version**:
+    ```bash
+    pnpm run --silent sdk version
+    ```
+2. **Read the changelog** for everything released since that version:
+    ```bash
+    pnpm run sdk docs view changelog.md
+    ```
+    Pay particular attention to any **Breaking Changes** section. If there are breaking changes, plan how to address them before bumping, and read `pnpm run sdk docs view guides/upgrading.md` too. The docs describe the installed version, so read the new changelog again after step 3.
+3. **Bump all three packages** together. The SDK and its tools are dev dependencies, so keep `-D`; the deck library is a runtime dependency of the presentation and must stay at the same version as the SDK:
+    ```bash
+    pnpm add -D @seriousgaming/sdk@latest @seriousgaming/sdk-tools@latest
+    pnpm add @seriousgaming/deck@latest
+    ```
+    The package also lists `@seriousgaming/sdk` under `peerDependencies`; move that range to match.
+4. **Regenerate types**: `pnpm run generate`. New schema fields, renames, or removed fields all surface through the generated `types.ts` files.
+5. **Build and address breakages**: `pnpm run build`. Work through type errors and address each Breaking Changes entry from step 2.
+6. **Run the test suites**: `pnpm test:run` and `pnpm test:engine`.
+7. **Adopt updated scaffold guidance**. New packages are scaffolded with the latest `CLAUDE.md` and `.claude/rules/`, but this package keeps whatever it was scaffolded with. The new version ships its templates inside the installed package, so both sides of the diff are on disk. Check three places and fold in anything relevant:
+    1. The changelog entries between the old and new version (from step 2): anything mentioning scaffold, guidance, rules, or `CLAUDE.md` is a candidate to adopt.
+    2. The shipped rules in `node_modules/@seriousgaming/sdk-tools/dist/templates/package/claude/rules/` against the local `.claude/rules/`: copy rule files that don't exist locally; for rules that do exist, diff the two and incorporate new guidance while keeping local edits.
+    3. The shipped `node_modules/@seriousgaming/sdk-tools/dist/templates/package/CLAUDE.md.template` against the local `CLAUDE.md`: incorporate new advice carefully.
+
+    The templates are the source of new guidance; the local files are the source of local truth. Propose the merge as a normal reviewable change, skip anything that isn't relevant to this package, and never overwrite local content wholesale. The goal is adoption, not a reset.
+
+## Things that almost always go wrong
+
+- Bumping only some of the three packages: the runtime and the CLI must agree on the schema, and the deck must match the SDK
+- Skipping the changelog read: breaking changes silently corrupt resources or fail validation later
+- Forgetting `pnpm run generate` after the upgrade: types stay stale and downstream code compiles against the old shape
+- Leaving `package.json` scripts, `pnpm-workspace.yaml`, or the config files behind: the new version's `dist/templates/package/` holds the current copies to compare against
+- Skipping the scaffold guidance check: the package quietly stays on outdated advice and never gains rules added after it was scaffolded

package/dist/templates/package/claude/settings.json.template

@@ -0,0 +1,16 @@
+{
+    "permissions": {
+        "allow": [
+            "Bash(pnpm run generate)",
+            "Bash(pnpm run --silent sdk build --validate-only:*)",
+            "Bash(pnpm run --silent sdk view:*)",
+            "Bash(pnpm run --silent sdk tick:*)",
+            "Bash(pnpm run --silent sdk init:*)",
+            "Bash(pnpm run --silent sdk docs view:*)",
+            "Bash(pnpm test:run:*)",
+            "Bash(pnpm test:engine:*)",
+            "Bash(pnpm run typecheck)",
+            "Bash(pnpm run lint)"
+        ]
+    }
+}

package/dist/templates/package/gitignore.template

@@ -0,0 +1,15 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# The dev server's local state: settings overrides, session state and uploaded files
+.seriousgaming-sdk/
+
+# Playwright results and reports
+test-results/
+playwright-report/
+
+# Local environment
+.env

package/dist/templates/package/global-setup.ts.template

@@ -0,0 +1,21 @@
+import { dirname } from 'path';
+
+import type { FullConfig } from '@playwright/test';
+import { startDevServer } from '@seriousgaming/sdk-tools/client';
+
+/**
+ * Start the dev server the browser tests run against, and stop it after them.
+ *
+ * It is the server `sdk dev --isolated --port auto` runs: on free ports, with
+ * no lock file, and configured from the package alone, so it starts beside
+ * your own dev server and every run begins from the same place. Running it in
+ * this process rather than spawning `sdk dev` means stopping it is a call,
+ * which a run cannot hang on.
+ */
+export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
+    const server = await startDevServer({
+        packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
+    });
+    process.env.SERIOUSGAMING_DEV_URL = server.url;
+    return () => server.stop();
+}

package/dist/templates/package/globals.d.ts.template

@@ -0,0 +1,2 @@
+// Ambient module declarations for CSS-only packages that ship no types.
+declare module '@fontsource-variable/*';

package/dist/templates/package/oxfmtrc.json.template

@@ -0,0 +1,14 @@
+{
+    "$schema": "./node_modules/oxfmt/configuration_schema.json",
+    "ignorePatterns": ["**/*.sdk.json", "seriousgaming.sdk.json", "**/types.ts"],
+    "semi": true,
+    "trailingComma": "es5",
+    "singleQuote": true,
+    "printWidth": 100,
+    "tabWidth": 4,
+    "useTabs": false,
+    "experimentalSortImports": {
+        "ignoreCase": true
+    },
+    "experimentalSortPackageJson": true
+}