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

package/dist/docs/guides/validators.md

@@ -0,0 +1,217 @@
+# Validators
+
+A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs. It returns a verdict and never modifies the proposed state. The runtime applies the write, or runs the tick, only when every validator that runs allows it.
+
+## The model
+
+Some rules cannot be written in `variablesSchema`. JSON Schema handles the shape of the data ('Price must be a non-negative number'), but not a rule across fields, such as 'only three of these ten booleans may be true at once' or 'the budget across these fields must not exceed N'. The engine cannot gate such a rule either, because it runs on the tick rather than when a UI submits. That leaves the front end, which is the wrong layer for an integrity rule: devtools bypass it, and so do test scripts and future non-web clients.
+
+A validator sits between a UI's submission and the runtime's apply step, on the server, so no client can get round it. Think of it as a verdict at the moment of submission, the way the engine is a tick-time computation and a [hook](./hooks.md) is a reaction to a runtime announcement:
+
+- The runtime decides when validators run: on a player surface's context writes and tick requests, never inside the tick loop, and never on writes made by the game's own logic
+- A validator subscribes to no signal. Given the previous state, the proposed next state, who is asking, and the settings it lists, it returns `{ ok: true }` or `{ ok: false, message }`
+- A validator never modifies state. The runtime applies the proposed state untouched, and only when every validator allows it
+- A validator runs when a write changes at least one capability in its `reads`, and one that declares no `reads` runs on every write. Every failure is collected and returned, so the experience is form-style rather than short-circuit
+
+```typescript
+type ValidationResult = { ok: true } | { ok: false; message: string };
+```
+
+A validator's logic exports one function per action it gates. `UpdateData` gates a context write; `RequestTick` gates a request for the next tick ([Gating tick requests](#gating-tick-requests)). Export either or both: a validator is run only for the actions it has a gate for, and the build reads which from the exports, so there is nothing to declare in the bundle.
+
+### Why reject rather than modify
+
+A 'clamp' verdict, where a validator rewrites the proposed state, is tempting. Validators do not offer one because:
+
+- It conflates two shapes, gate and transform, which makes composing validators harder to reason about
+- A clamp after the UI has submitted is a silent disagreement: the participant thinks they wrote X and the runtime stored Y. A clear rejection the UI can show is a better experience
+- Anything that needs to transform state can do so in the engine on the next tick, or in the UI before it submits
+
+### When to use a validator (versus an engine or a schema check)
+
+- **`variablesSchema`**: an invariant on the shape of a single capability's data (numeric ranges, required fields, enum values). JSON Schema 7 expresses it natively
+- **Engine**: the rule is part of normal tick-time evolution (clamping, derived state). The engine already changes context every tick
+- **Hook**: the work reacts to a runtime-emitted lifecycle event (a participant joining, for example) after the runtime applies the change
+- **Validator**: the rule is an integrity invariant that must hold whenever a UI submits a write, cannot fit inside `variablesSchema`, and needs to gate the write rather than react to it
+
+Validators are also how a game arbitrates concurrent writes to a genuinely contested slot. When two participants can legitimately race for the same key (claiming a role, taking the last shared resource), no capability shape prevents the race, but a validator comparing `previous` against `next` can enforce 'first claim wins' or 'only write your own entry', so the losing write is refused loudly instead of silently overwriting. See [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md).
+
+## Creating a validator
+
+```bash
+pnpm run sdk new validator '{
+  "definition": {
+    "identifier": "decisionlimit",
+    "reads": ["decisions"]
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+This produces:
+
+```
+validators/decisionlimit/
+├── validator.sdk.json   # Definition (reads, settings)
+├── logic/
+│   ├── logic.ts         # UpdateData, and optionally RequestTick
+│   └── logic.test.ts
+├── defaults.ts          # Generated: the starting context and settings, for tests
+└── types.ts             # Generated: Context, Settings, ValidatorFunction, RequestTickFunction
+```
+
+`identifier` names the directory; it is not written into `validator.sdk.json`. The capabilities in `reads` must already exist (here, a `decisions` capability).
+
+### Wiring it to a game
+
+Nothing to do: a package declares whatever is on disk, and a game runs whatever its package declares, so the directory `pnpm run sdk new validator` created is the whole of the wiring.
+
+Validators run in directory-name order, and every failure is collected rather than short-circuiting, so number the directories if the order matters.
+
+## Writing the logic
+
+```typescript
+import type { ValidatorFunction } from '../types';
+
+export const UpdateData: ValidatorFunction = async ({ previous, next, actor, settings }) => {
+    const decisions = next.decisions;
+    const selected = Object.values(decisions).filter(Boolean).length;
+    if (selected > 3) {
+        return { ok: false, message: 'errors.max-three-decisions' };
+    }
+    return { ok: true };
+};
+```
+
+The validator receives:
+
+- `previous`: the context before the mutation
+- `next`: the proposed context after the mutation
+- `actor`: who made the request (see [The actor](#the-actor))
+- `settings`: the settings resources this validator lists in its bundle's `settings`, keyed by identifier
+
+The `message` string is free-form. The SDK does not prescribe a format, so games encode whatever structure they need (a locale key, a JSON blob) inside it.
+
+### Reads only
+
+Validators declare `reads` but no `writes`. They are pure verdicts and cannot mutate state. The generated `Context` type reflects only the capabilities they read from.
+
+## The actor
+
+Each validator is told who submitted the mutation, as `actor`:
+
+```typescript
+type ValidatorActor =
+    { role: 'participant'; participant: Participant } | { role: 'observer'; teamId: string };
+```
+
+It is a union rather than an optional participant, because these are two callers rather than an identity and the absence of one. `participant` is unreachable until you have narrowed on `role`, so a validator cannot read an identity it has not first decided it has.
+
+A **participant** is playing. An **observer** is a facilitator watching one team on that team's own game UI, with that team's own controls, so the same rules hold for them unless you say otherwise:
+
+```typescript
+export const UpdateData: ValidatorFunction = async ({ next, actor, settings }) => {
+    // This game lets a facilitator past the cap. Deliberate, and worth being
+    // deliberate about: a rule the engine depends on should not be relaxed
+    // here, because that moves the breakage to the next tick.
+    if (actor.role === 'observer') return { ok: true };
+    ...
+};
+```
+
+Whichever it is, `actor` always describes somebody real. A mutation the runtime cannot attribute is refused before any validator runs, so there is no placeholder to guard against (see [When the actor cannot be resolved](#when-the-actor-cannot-be-resolved)).
+
+## Order of operations
+
+For every UI `updateData` mutation, the runtime:
+
+1. Resolves the actor: the participant the mutation is submitted on behalf of. This decides whether the rest of the list happens at all, and is covered below
+2. Computes the proposed `next` state by applying the mutation to the current `previous` state, in memory only
+3. Resolves the package's validators, in directory-name order
+4. Runs each validator's `UpdateData` with `{ previous, next, actor, settings, meta, participants }`, and collects every failure. `participants` is the actor's team, and `meta.now` the instant the run started
+5. If at least one validator returns `{ ok: false }`, it does **not** persist the patch, discards the proposed state, and returns the collected rejections (`{ validatorIdentifier, message }[]`) to the caller through the host ↔ iframe channel as a `validationRejected` port message
+6. Otherwise, it applies and persists the patch as usual and broadcasts the resulting context
+
+The UI decides how to render a rejection: a toast, an inline field error, or a modal.
+
+### When the actor cannot be resolved
+
+Step one has three outcomes, not two, and the third is the one worth knowing about.
+
+- **A participant resolves.** The validators run, as above
+- **There is nobody to resolve, and nobody was expected.** The mutation is system-trusted and skips validation entirely. This is the CLI, a session UI, and the runtime's own writes. An observer is _not_ in this list: it has no participant record, but the runtime knows exactly what it is, so its writes are validated and the validator is told
+- **A participant was expected and none resolved.** The mutation is refused outright, as `denied`, and nothing is applied. No validator runs, because there is no actor to run one against
+
+The third case is what a game UI produces when the runtime cannot bind it to anybody: a link followed after the session moved on, or a URL naming a participant who is not in the session. It is refused rather than skipped, because a runtime that cannot say who is writing cannot run an actor-aware check, and treating it as system-trusted would turn a failure to identify somebody into the widest trust the runtime has.
+
+You will not normally see this. It matters because it must not be confused with the second case. The dev server holds the same line: a surface at `/team/1/player/3` on a team holding two participants is refused, rather than mounted and trusted.
+
+## What bypasses validation
+
+| Source           | Bypasses validators?                        | Why                                                                                       |
+| ---------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| UI `updateData`  | No, validators run                          | UI mutations originate from end-user actions; the rule must hold                          |
+| UI `requestTick` | No, for a validator exporting `RequestTick` | A participant asking for the next tick; see [Gating tick requests](#gating-tick-requests) |
+| Engines          | Yes, system-trusted                         | Engines execute the game's own logic; validators would create infinite recursion          |
+| Hooks            | Yes, system-trusted                         | Hooks react to lifecycle signals, not user input                                          |
+| CLI and tests    | Yes, system-trusted                         | CLI mutations bypass when no participant is supplied (matches test usage)                 |
+| Endpoints        | Yes, system-trusted                         | An endpoint is the game's own code, and checks its own request before it writes           |
+
+### Validators and endpoints
+
+An endpoint's write is not put to validators, whoever called it, including a participant's own game UI: a validator gates the one route where a participant changes state directly, and an endpoint is your code in the path. That lets a validator refuse a change outright while a strict endpoint becomes the one sanctioned way to make it. See [Endpoints and validators](./endpoints.md#endpoints-and-validators).
+
+## Gating tick requests
+
+A validator can also refuse a participant's request for the next tick. That is how a game enforces facilitator pacing: without it, the only thing holding a team at the round the facilitator has opened is a disabled button, and a participant's `requestTick` goes straight through.
+
+Export `RequestTick` from the validator's logic. It receives the requesting team's board as it stands, as `context` (projected onto the validator's `reads`), and `requestedTick`, the tick the request would run: the team's current tick plus one, so a first request asks for tick 1. There is no `previous` and `next`, because a request changes nothing until the tick runs:
+
+```typescript
+import type { RequestTickFunction } from '../types';
+
+export const RequestTick: RequestTickFunction = async ({ requestedTick, context }) => {
+    const { LastOpenRound } = context.pacing;
+    if (requestedTick > LastOpenRound) {
+        return { ok: false, message: `Round ${requestedTick} is not open yet.` };
+    }
+    return { ok: true };
+};
+```
+
+It runs on every request, before the tick starts. The rule that a validator runs only when a write changes its `reads` does not apply, because a request changes nothing.
+
+A refusal stops the tick, and the participant's `requestTick()` rejects with the validator's message, as a refused write does. Only a request from a player surface (a participant's or an observer's) is gated. The facilitator's own tick, from the session surface or the console, and a timer's tick are never gated, which is what lets the facilitator run a round the room is not allowed to yet. Undo and reset are never validated. The `pacing` capability in the example above is a shared one the facilitator raises from the session UI as each round opens.
+
+## Settings
+
+A validator reads [settings](./settings.md) the way every other resource does: list the settings resources in the bundle's `settings`, and it receives exactly those as `settings`, keyed by identifier. They resolve through the same layers as the engine's, so a scenario or the facilitator's setup screen can change a limit without touching the logic.
+
+A `decisionlimit` validator, for instance, can read its cap from `settings/decisionlimit/`:
+
+```json
+{
+    "definition": {
+        "reads": ["addons"],
+        "settings": ["decisionlimit"]
+    }
+}
+```
+
+```typescript
+if (selected > settings.decisionlimit.MaxSelected) {
+    return {
+        ok: false,
+        message: `At most ${settings.decisionlimit.MaxSelected} addons may be selected`,
+    };
+}
+```
+
+## Related
+
+- [Create a validator recipe](../recipes/create-validator.md): step-by-step scaffolding
+- [Hooks guide](hooks.md): for out-of-tick reactions

package/dist/docs/guides/waiting-room.md

@@ -0,0 +1,244 @@
+# Building waiting room UIs
+
+Own the holding screen participants see while a session is parked, instead of accepting the host's stock panel.
+
+**Keywords:** waiting room, holding screen, lobby, waiting to begin, session paused, park a session, break, waitingRoom, setWaitingRoom
+
+## What you'll learn
+
+- What the waiting room is and who controls it
+- Why a waiting room UI is a game UI rather than a new kind of surface
+- How to tell 'not started yet' from 'parked mid-play'
+- How to start every session with the room already open
+- How to stop the tick clock while participants wait
+- How to let your own session UI open and close the room
+
+## What is the waiting room?
+
+The waiting room is a single per-session flag. While it is open, every participant in the session sees a holding screen instead of the game UIs; while it is closed, they see the game. The facilitator toggles it, and the change reaches every team at once.
+
+```
+Waiting room closed          Waiting room open
++---------------------+      +---------------------+
+|                     |      |                     |
+|                     |      |                     |
+|      Game UIs       |      |   Waiting room UI   |
+|                     |      |                     |
+|                     |      |                     |
++---------------------+      +---------------------+
+```
+
+Three properties are worth committing to memory, because each one surprises somebody:
+
+| Property                    | What it means                                                                                                                                                                       |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Game state survives**     | Per-team context, the current tick, and timers are untouched in both directions. Nothing is reset, which is exactly why facilitators use it to park a live session for a discussion |
+| **The clock keeps running** | Automatic ticks still fire while the room is up. Halting play is a separate, opt-in decision (see [stopping the clock](#stopping-the-clock))                                        |
+| **Joining still works**     | Participants can join while the room is open and appear on the roster. `participantJoin` hooks fire as normal                                                                       |
+
+## A game UI in a different place
+
+A waiting room UI is not a reduced surface. It has full parity with a game UI:
+
+| Capability              | Waiting room UI        |
+| ----------------------- | ---------------------- |
+| `reads`                 | Yes                    |
+| `writes`                | Yes                    |
+| `endpoints`             | Yes                    |
+| cross-team reads        | Yes                    |
+| `crossTeamParticipants` | Yes                    |
+| Wrapper                 | `UserInterfaceWrapper` |
+| Hooks                   | `useUserInterface*`    |
+
+There is deliberately no `WaitingRoomUserInterfaceWrapper` and no `useWaitingRoomUserInterfaceData`. A parallel API with identical behaviour would be two things to keep in step for no gain, so the room reuses the game UI's API exactly. Every recipe and guide about game UIs applies unchanged.
+
+What the resource type buys you is the wiring, not a different runtime contract: its own directory, its own generated `types.ts`, a `waitingRoom` settings block on the game, and a mount rule that gives it the whole viewport.
+
+## Creating one
+
+The starter game already fills this slot, and `new` refuses a filled one with `RESOURCE_EXISTS`. In a package made by `new package`, change it with `update waiting_room` instead, or start from `new package --empty`.
+
+```bash
+pnpm run sdk new waiting_room '{
+  "definition": {
+    "reads": ["briefing"]
+  },
+  "rootDirectory": "."
+}'
+```
+
+There is nothing to wire: a package declares whatever is on disk, and a game holds at most one waiting room, in the `waiting_room/` slot. To give the room values a game can vary, list the settings resources it reads in `settings`, as any surface does, and read them from `settings` (see [Settings](./settings.md#reading-settings)):
+
+```json
+{
+    "definition": {
+        "reads": ["briefing"],
+        "settings": ["waiting_room"]
+    }
+}
+```
+
+To hold participants from the moment they join rather than waiting on the facilitator, add `"openOnStart": true` (see [starting held](#starting-held)).
+
+When a game has no `waiting_room/`, the host renders its own built-in holding screen. The SDK dev server does not reimplement that panel. Its **Waiting room** toggle is always in the dev drawer, and with the room open and none authored, a held participant sees a notice that the package has no waiting room UI rather than a holding screen.
+
+## Reading game state
+
+Same as any game UI. Declare the capability in `reads`, regenerate, and read it off `data`:
+
+```typescript
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function App() {
+    const { data, settings, completedTicks } = useUserInterfaceData<Context, Settings>();
+    const briefing = data.briefing?.Headline ?? '';
+    // ...
+}
+```
+
+Because setup completes during session creation, and settings are fixed from then on, a waiting room UI is always mounted against an initialised context. `reads` return real values rather than placeholders, and `writes` always have somewhere to land.
+
+## Not started vs parked mid-play
+
+The room can be opened at any point in a session, so a single fixed message is wrong half the time. `completedTicks` tells the two situations apart:
+
+```typescript
+const { completedTicks } = useUserInterfaceData<Context, Settings>();
+
+return <h1>{completedTicks === 0 ? t('waitingToBegin') : t('sessionPaused')}</h1>;
+```
+
+This is the most common reason authors reach for a custom room: the host's built-in panel says 'waiting to begin' and 'the facilitator will start the session shortly' whatever the tick, which reads as a bug to any participant parked halfway through a game.
+
+## Starting held
+
+By default a session starts with the room closed, so the first participant to follow a join link lands straight in the game at tick 0. For a game whose opening move belongs to the facilitator, that is a race: the room only holds anybody if the facilitator opens it before the join links go out.
+
+`openOnStart` settles it in the manifest:
+
+```json
+{
+    "waitingRoom": {
+        "openOnStart": true
+    }
+}
+```
+
+Every session of that game now begins held, and participants see the room from the moment they join. Pair it with the `completedTicks === 0` branch above and the copy is right on both sides: 'waiting to begin' for the held start, 'session paused' for a mid-play park.
+
+It seeds the session, it does not govern it. Three things follow:
+
+- The facilitator owns the flag from the moment the session exists. Closing the room lets the teams in, and nothing reopens it behind their back
+- A reset does not re-park the session. Reset keeps the roster and is not a new session, so the room stays exactly as the facilitator left it
+- A dev server restart is a new session, so the flag is seeded from the manifest again. What the facilitator did to the last session does not carry over
+
+A held start needs a room to hold people in, so `openOnStart` needs an authored `waiting_room/`. `sdk build` refuses `openOnStart: true` from the game or from any scenario (under `settings.game.waitingRoom`) when the package has none. It is one of the [game settings](./settings.md#the-game-settings), which a scenario can override but a setup screen cannot, because it takes effect as the session is created, before setup. A facilitator can still open the room mid-play in a game without one, which shows the host's built-in panel.
+
+## Showing the roster
+
+The game UI's participant hooks work here, which is what makes a useful holding screen possible:
+
+```typescript
+import {
+    useUserInterfaceOwnTeam,
+    useUserInterfaceParticipant,
+    useUserInterfaceParticipants,
+} from '@seriousgaming/sdk/ui';
+
+const ownTeam = useUserInterfaceOwnTeam();
+const participants = useUserInterfaceParticipants();
+const self = useUserInterfaceParticipant();
+
+const roster = [...participants].sort((a, b) => a.index - b.index);
+```
+
+Sort by `index`, not by name: the index is join order and is stable for the session. `participant.connected` is live, so a member closing their laptop dims in place. `self` is `null` when a facilitator is observing rather than playing, so guard before comparing.
+
+## Showing a join code
+
+The lobby is where a group sits while the facilitator sets up, so it is the natural place for a join code: a latecomer joins the team on the screen in front of them instead of waiting for someone to read a URL out.
+
+```typescript
+import { useUserInterfaceOwnTeamJoinLink } from '@seriousgaming/sdk/ui';
+
+const joinLink = useUserInterfaceOwnTeamJoinLink();
+// `null` until the host delivers it, so render nothing for that first frame
+```
+
+You get this team's link and only this team's. Encode `joinUrl` in the QR code rather than any longer form, and treat `fallbackJoinUrl` as a 'link not working?' affordance for networks that block the shortened one. The session PIN never reaches a game UI, so in a PIN-protected session the code alone does not admit anyone. See [Showing how to join this team](./ui.md) in the user interfaces guide for the full contract, which is identical here: a waiting room UI is a game UI in a different display context.
+
+## Letting the group name itself
+
+The lobby is where a group decides who it is, so it is the natural place for a name field. `renameOwnTeam(name)` sets the team's real name, the one the host's own chrome and print sheets show, so there is no second name to keep in sync:
+
+```typescript
+import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+const { renameOwnTeam } = useUserInterfaceCallbacks();
+await renameOwnTeam('The Cartographers');
+```
+
+It names no team: the host resolves the caller's, so a surface can only rename its own. Render `useUserInterfaceOwnTeam()?.name` rather than what you sent, because a facilitator may rename the same team at the same moment and the last write wins. A blank or over-long name is refused as a terminal `MutationError`. See [Letting a team name itself](./ui.md) for the full contract.
+
+## Stopping the clock
+
+Opening the room pauses nothing. The decision belongs to the game, because only the author knows whether the simulation should keep advancing in the background:
+
+```typescript
+import type { GetTickControllerFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from '../types';
+
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    waitingRoomOpen,
+    context,
+}) => {
+    return {
+        enabled: !waitingRoomOpen,
+        intervalMs: 60_000,
+    };
+};
+```
+
+Without this, a facilitator who parks a session for a ten-minute discussion returns to teams whose game has moved on without them. With it, the countdown stops when the room opens and resumes when it closes.
+
+## Layout
+
+The room owns the viewport. It replaces the game UI. Two consequences:
+
+- Any branding or status you want visible has to live inside the waiting room bundle
+- Set `html, body, #root { margin: 0; height: 100% }` in `index.html` so a full-height layout actually fills the frame
+
+## Opening the room from your own session UI
+
+The host provides a toggle, but a session UI can drive the flag itself, which is useful when your game wants a 'start session' control of its own design:
+
+```typescript
+import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
+
+await setWaitingRoom(true); // park the session
+await setWaitingRoom(false); // resume
+```
+
+Alone among the session controls it takes no `teamId`. The waiting room is one flag for the whole session, so there is no per-team variant to target. It returns a promise that resolves once the host confirms the change and rejects with a `MutationError` if it cannot apply it.
+
+`setWaitingRoom` is not gated by `uses`: it sits with the other session flow controls (`pauseTimer`, `resumeTimer`, `resetGame`, `undoTick`) outside the `ApiUse` enum.
+
+### Letting participants signal readiness
+
+Nothing in a game UI bundle can close the room; that stays a facilitator action. If you want a 'we're ready' affordance, use the parity the room already has: write to a capability from the waiting room UI, and read it in your session UI so the facilitator can see who is waiting on whom.
+
+## Testing
+
+The room renders under the game UI's providers, so `renderUserInterface` tests it with no browser, taking `completedTicks` and `participants` as options: see [Game UIs](./testing.md#game-uis) in the testing guide. Vary `completedTicks` across two tests to cover both headings: that branch is the easiest thing to get wrong and the hardest to notice.
+
+For the full loop, start the dev server, toggle the room, and watch the swap. See [end-to-end testing](../recipes/e2e-testing.md).
+
+## Related
+
+- [Create a waiting room UI](../recipes/create-waiting-room-ui.md): the step-by-step recipe
+- [Building user interfaces](ui.md): the game UI and every hook the room shares with it
+- [Tick controllers](tick-controller.md): where to stop the clock
+- [Building session UIs](session.md): the session UI that can toggle the room

package/dist/docs/index.md

@@ -0,0 +1,41 @@
+# Serious Gaming SDK documentation
+
+The Serious Gaming SDK is for building business simulations: live, in-person learning interventions that a facilitator runs for a room of teams. You write a game as a package of TypeScript logic and React UIs, run it locally in the dev server, and publish it to the Serious Gaming platform.
+
+## How a session runs
+
+1. A facilitator starts a live session of your game and runs it from the session UI
+2. Participants join on their own devices, in teams, and each sees your game UI
+3. Teams make decisions: each change is a write to their team's state, checked by any validators you wrote
+4. Each tick runs your engine on every team's state, and the game UIs show the result
+5. After the last tick the game is complete, and the facilitator leads the debrief
+
+## Start here
+
+- **[Getting started](./getting-started.md)**: scaffold the starter game, play it, and change it
+- **[A tour of the starter game](./guides/starter-game.md)**: every file in the game you are given, and what it does
+- **[Terminology](./concepts/terminology.md)**: the words these docs use, each with one meaning
+
+## The documentation
+
+- **[Core concepts](./concepts/index.md)**: the model on one page, and how the resource kinds fit together
+- **[Guides](./guides/index.md)**: one page per resource kind or topic, explaining it and serving as its reference
+- **[Recipes](./recipes/index.md)**: one task each, step by step
+- **[API reference](./api/index.md)**: every export of the SDK, the deck library and the test client, one page per entry point
+
+## The CLI and the dev server
+
+- **[The CLI and the dev server](./cli-and-dev-server.md)**: how the two share one session
+- **[Drive a game from the CLI](./cli-simulation-testing.md)**: configure, tick, patch, and read a session from the terminal
+- **[CLI reference](./cli-reference.md)**: every command and flag, including logging and output
+- **[CLI error codes](./cli-error-codes.md)**: every code a failed command reports, and its exit code
+- **[Environment variables](./environment-variables.md)**: every variable the dev server and CLI read
+
+## When something changes or goes wrong
+
+- **[Upgrading](./guides/upgrading.md)**: the steps from 0.6 to 1.0
+- **[Changelog](./changelog.md)**: what changed in each release from 1.0, and what to do about it
+- **[Changelog for 0.x](./changelog-0.x.md)**: every release before 1.0
+- **[Troubleshooting](./troubleshooting.md)**: symptoms, causes, and fixes
+
+The docs at sdk.seriousgaming.com describe the newest release. The docs for the version you have installed ship inside it: `pnpm run sdk docs view` lists them and prints any page, and `pnpm run sdk docs export` copies them into your package for an editor or agent to search.

package/dist/docs/recipes/act-on-the-session-from-an-endpoint.md

@@ -0,0 +1,95 @@
+# Act on the session from an endpoint
+
+**Keywords:** endpoint actions, advance tick from endpoint, close waiting room, start round, pause timer, extend tick, move participant, add team, facilitator macro, AI agent start round, Plan, Respond
+
+Let one endpoint call do what a facilitator would otherwise do in several steps, such as posting a notice, closing the waiting room and starting the next round, under your game's own rules.
+
+## Prerequisites
+
+- An endpoint that already works (see [Create an endpoint](create-endpoint.md))
+- The facilitator operations it should perform. Available: `tick`, `pauseTimer`, `resumeTimer`, `extendTick`, `setWaitingRoom`, `renameTeam`, `addTeam`, `moveParticipant` and `setLocale`
+
+## Steps
+
+1. Declare the actions the endpoint may return:
+
+    ```json
+    {
+        "definition": {
+            "scope": "session",
+            "writes": ["noticeboard"],
+            "actions": ["setWaitingRoom", "tick"]
+        }
+    }
+    ```
+
+2. Regenerate the types, which gives you an `Action` type holding just those:
+
+    ```bash
+    pnpm run sdk generate
+    ```
+
+3. Return the actions beside the response, deciding from `session`:
+
+    ```typescript
+    import type { Action, Handler } from '../types';
+
+    export const Handle: Handler = async ({ session, context }) => {
+        if (session.complete) throw new Error('The game is complete');
+
+        const actions: Action[] = [
+            ...(session.waitingRoomOpen ? [{ type: 'setWaitingRoom' as const, open: false }] : []),
+            { type: 'tick' },
+        ];
+        return {
+            response: { fromRound: session.completedTicks },
+            capabilities: { noticeboard: { ...context.noticeboard, Message: 'Round starting' } },
+            actions,
+        };
+    };
+    ```
+
+    The runtime applies the write, then the actions in order, in one step, and holds each action to the same rules as when the session UI performs it. A `teamId` left off an action means the call's own team on a team-scoped endpoint, and the whole session on a session-scoped one.
+
+4. Decide who may call it. Actions are not put to your validators, so a participant whose screen lists this endpoint can trigger them. That is how a game lets a participant end their own turn. For a facilitator-only endpoint, refuse other callers:
+
+    ```typescript
+    export const Handle: Handler = async ({ session, context, caller }) => {
+        if (caller.role === 'participant' || caller.role === 'observer') {
+            throw new Error('Only the facilitator can start a round');
+        }
+        // ...as in step 3
+    };
+    ```
+
+5. Optional: to report what the actions did, such as the round now in play, answer in two phases. Rename `Handle` to `Plan`, return only the effects from it, and export `Respond`, which runs after they have landed:
+
+    ```typescript
+    import type { Planner, Responder } from '../types';
+
+    export const Plan: Planner = async ({ session }) => ({ actions: [{ type: 'tick' }] });
+
+    export const Respond: Responder = async ({ session, outcomes }) => ({
+        round: session.completedTicks, // read after the tick
+    });
+    ```
+
+## Verify
+
+- `pnpm run sdk endpoint call startround` (with `--external` for an external one) returns the response, and `pnpm run sdk view` shows the waiting room closed and the tick advanced
+- `pnpm run sdk endpoint list` marks the endpoint `acts` and lists its actions
+- Against a running dev server, `pnpm run sdk endpoint audit` shows the call and the actions it carried out
+
+## Troubleshooting
+
+- _'action 0 is "setWaitingRoom", which the endpoint does not declare'_: Add it to `actions`
+- _'The game moved on while the endpoint was running'_: A tick landed while the handler ran, so its whole result was refused. Keep endpoints that act quick, and let the caller try again
+- _'stopped at action 1 ("tick"): ... had already been applied'_: A step failed after earlier ones landed; they stay applied. Check the reason, such as the game being complete
+- _'returned "renameTeam" with no teamId'_: A session-scoped endpoint has no team of its own; name one
+- _'exports `Respond` beside `Handle`'_: Rename `Handle` to `Plan`
+
+## Related
+
+- [Endpoints (concept)](../guides/endpoints.md)
+- [Make an endpoint callable from outside the game](make-an-endpoint-external.md)
+- [Take a file in an endpoint](take-a-file-in-an-endpoint.md)