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

package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md

@@ -0,0 +1,133 @@
+# Adapt a game for walkthroughs
+
+**Keywords:** walkthrough, runKind, meta.runKind, useRunKind, demonstrate the game, demo run, rehearse, facilitator walkthrough, show the room, spoiler, solo run, resetWalkthrough, walkthrough link
+
+A walkthrough is a disposable second run of your game beside the session, for demonstrating it: one team, one participant, always from tick 0, and isolated from the session in both directions. It is what a facilitator puts on a projector while talking a room through the game before they play it.
+
+Most games need no changes. Reach for this when a solo run is missing something a group has, or when a tick reaches outside for something you would rather not pay for or wait on in front of a room.
+
+## Prerequisites
+
+- A game with an engine (see [Create an engine](create-engine.md))
+- The dev server running (`pnpm run sdk dev`)
+
+## Steps
+
+1. Open the walkthrough and see what your game looks like in it. It is at `/walkthrough`, and in the dev drawer's Surfaces tab:
+
+    ```bash
+    pnpm run sdk dev
+    # then open http://localhost:3000/walkthrough
+    ```
+
+    The run is built the first time you open it. Nothing to create, nothing to clean up.
+
+2. Read the run kind in logic. `meta.runKind` is `'session'` or `'walkthrough'`:
+
+    ```typescript
+    export const Run: RunFunction<Context, Settings> = async ({ context, meta, callbacks }) => {
+        if (meta.runKind === 'walkthrough') {
+            // ...
+        }
+    };
+    ```
+
+    Hooks, endpoints and validators read it the same way, from their own `meta`.
+
+3. Read it in a surface with `useRunKind()`:
+
+    ```tsx
+    import { useRunKind } from '@seriousgaming/sdk/ui';
+
+    const runKind = useRunKind();
+    ```
+
+    It is the same value your engine reads, and neither changes for the life of the run, so a decision taken here cannot disagree with one taken in logic.
+
+4. Fill in what a solo run genuinely lacks. A walkthrough has one team, so anything that compares teams has nobody to compare against:
+
+    ```tsx
+    function Leaderboard() {
+        const runKind = useRunKind();
+        const data = useUserInterfaceData();
+
+        // One row is worse than no board: it teaches the room the wrong shape.
+        const rows = runKind === 'walkthrough' ? demonstrationRows : data.market.Standings;
+
+        return <Board rows={rows} />;
+    }
+    ```
+
+5. Suppress what reaches outside. A model call is real spend, real latency, and a different answer every time, none of which you want on a projector:
+
+    ```typescript
+    const commentary =
+        meta.runKind === 'walkthrough'
+            ? writtenCommentary(context)
+            : getText(await callbacks.generateText(prompt(context)));
+    ```
+
+    Prefer a path your game already has. If it falls back to written text when the model is unavailable, route the walkthrough through that same fallback, so the demonstration is not a third behaviour nobody tests.
+
+6. Offer the walkthrough from your session UI, if you have one. Gate the control on the link, so it never appears on a host that has no walkthrough to open:
+
+    ```tsx
+    function WalkthroughControls() {
+        const walkthrough = useSessionUserInterfaceWalkthroughLink();
+        const { resetWalkthrough } = useSessionUserInterfaceCallbacks();
+
+        if (!walkthrough) return null;
+
+        return (
+            <>
+                <Button href={walkthrough.url} target="_blank" rel="noreferrer">
+                    Walkthrough
+                </Button>
+                <Button onClick={() => void resetWalkthrough()}>Start it again</Button>
+            </>
+        );
+    }
+    ```
+
+7. Test both paths. `runKind` is an ordinary field on `meta`, so build the arguments with `logicArgs`, and the render helpers take it as an option:
+
+    ```typescript
+    import { logicArgs } from '@seriousgaming/sdk/testing';
+
+    import { defaultContext, defaultSettings } from './defaults';
+
+    const result = await Run(
+        logicArgs.run({
+            context: defaultContext,
+            settings: defaultSettings,
+            meta: { runKind: 'walkthrough' },
+        })
+    );
+    ```
+
+    ```tsx
+    renderUserInterface(<Leaderboard />, { runKind: 'walkthrough' });
+    ```
+
+Hold one line throughout: fill in the social context a solo run lacks, and suppress spoilers and outside calls, but never change how the game plays. If the walkthrough invents a figure the game would not produce, it has gone too far.
+
+## Verify
+
+- `pnpm run sdk view --walkthrough` reports `"runKind": "walkthrough"`, one team, and tick 0
+- `pnpm run sdk tick --walkthrough` advances the walkthrough and leaves `pnpm run sdk view` on the session unchanged
+- The walkthrough never shows the waiting room, even for a game with `waitingRoom.openOnStart`
+- `pnpm run sdk reset --walkthrough` returns it to tick 0
+- A game that reads `runKind` nowhere behaves exactly as it did before
+
+## Troubleshooting
+
+- **`meta.runKind` is always `'session'`**: you are looking at the session, not the walkthrough. In `sdk dev`, open `/walkthrough` or pass `--walkthrough`
+- **The walkthrough asks for configuration**: it should not. It resolves settings exactly as its session does. If your game has a `setup` slot, commit the session's configuration first, then open the walkthrough
+- **A shared-state game runs the walkthrough with one team**: that is deliberate. `teams.min` says what the game needs to be _played_, and a walkthrough is not play. Use `runKind` to fill in the teams that are not there
+- **The walkthrough's generated content differs from the session's**: the two runs draw separate seeds, so anything derived from `meta.seed` differs between them. Rely on the shape of the screen rather than on a specific generated value when rehearsing
+
+## Related
+
+- [Engines guide, walkthroughs](../guides/engine.md#walkthroughs)
+- [Building user interfaces guide, walkthroughs](../guides/ui.md#walkthroughs)
+- [Adapt a UI for observers](adapt-ui-for-observers.md)

package/dist/docs/recipes/adapt-ui-for-observers.md

@@ -0,0 +1,74 @@
+# Adapt a UI for observers
+
+**Keywords:** observer, observe team, viewer role, useUserInterfaceViewerRole, facilitator peek, debrief, null participant, own team, useUserInterfaceOwnTeam, which team am I
+
+An observer is a facilitator watching one team's live game UI without joining as a team member. It is useful for seeing how a team is playing, troubleshooting, or running a debrief. Your game UI is rendered for observers as well as participants; most UIs work unchanged, and you reach for this only when you want the game UI to behave differently under observation.
+
+## Prerequisites
+
+- A game UI (see [Create a user interface](create-user-interface.md))
+- The dev server running (`pnpm run sdk dev`) with at least one team
+
+## Steps
+
+1. Read the viewer role with `useUserInterfaceViewerRole()`. It returns `'participant'` or `'observer'` and is always present:
+
+    ```tsx
+    import { useUserInterfaceViewerRole } from '@seriousgaming/sdk/ui';
+
+    const isObserver = useUserInterfaceViewerRole() === 'observer';
+    ```
+
+2. Guard reads of the participant. An observer has no caller identity, so `useUserInterfaceParticipant()` returns `null`:
+
+    ```tsx
+    import { useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
+
+    const participant = useUserInterfaceParticipant(); // null when observing
+    ```
+
+3. Do **not** reach for the participant to find out which team you are rendering. Use `useUserInterfaceOwnTeam()`, which is populated for observers and participants alike:
+
+    ```tsx
+    import { useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
+
+    const ownTeam = useUserInterfaceOwnTeam(); // { teamId, index, name }, not null under observation
+    ```
+
+    This is the read most often missed. `participant.teamId` is the obvious route and it silently becomes `null` when observed, so anything keyed off it (splitting a `useUserInterfaceCrossTeamData()` result into 'mine' and 'theirs', labelling a board, picking a row to highlight) breaks only in the observer view. Note that `useUserInterfaceTeams()` is the plural hook: it lists every team in the session and does not mark which is yours.
+
+4. Adapt the game UI. Hide participant-only controls (anything keyed by participant id has no id to write under), reveal state you keep hidden during play, or present a read-only debrief view:
+
+    ```tsx
+    function Decisions() {
+        const isObserver = useUserInterfaceViewerRole() === 'observer';
+
+        return (
+            <>
+                {isObserver && <Banner>Observing: watching this team, not playing</Banner>}
+                <PriceInput readOnly={isObserver} />
+                {!isObserver && <SubmitNoteForm />}
+            </>
+        );
+    }
+    ```
+
+5. Open the observer view at `/team/<n>/observe`. It renders the same game UI with no participant identity and no presence.
+
+## Verify
+
+- The observer view shows the same live state as the participant view, and updates as the game ticks
+- `useUserInterfaceViewerRole()` reads `'observer'` and `useUserInterfaceParticipant()` is `null` in the observer view
+- `useUserInterfaceOwnTeam()` still returns the observed team, so anything labelled 'yours' stays correct
+- The observer does not appear in the team roster (`useUserInterfaceParticipants()`) and no presence indicator lights up for them
+
+## Troubleshooting
+
+- **The UI crashes reading `participant.name` when observing**: `useUserInterfaceParticipant()` is `null` for an observer. Guard for `null` before reading its fields
+- **Cross-team lists stop marking which team is yours when observing**: you are deriving own-team from `participant.teamId`, which is `null` under observation. Switch to `useUserInterfaceOwnTeam()`
+- **`useUserInterfaceOwnTeam()` returns `null`**: the host is not sending an own team and there is no participant to fall back on. Against the dev server this should not happen on a game UI; on a hosted runtime that does not send the own team, an observer reads `null`
+
+## Related
+
+- [User interfaces guide: observers](../guides/ui.md#observers)
+- [Observe other teams' state](observe-other-teams-state.md)

package/dist/docs/recipes/call-endpoint-from-ui.md

@@ -0,0 +1,109 @@
+# Call an endpoint from a UI
+
+**Keywords:** call endpoint, invoke endpoint, callbacks.endpoints, UI endpoint, request response, EndpointError, endpoint failure
+
+## Prerequisites
+
+- An [endpoint](create-endpoint.md) already scaffolded in the same package (or installed via another package)
+- A user interface, session UI, setup screen, or scenario editor to call it from
+
+## Steps
+
+1. Declare the endpoint on the UI bundle. Edit the UI's bundle (`ui/ui.sdk.json`, `session/session.sdk.json`, `waiting_room/waiting_room.sdk.json`, `setup/setup.sdk.json`, or `scenario_editor/scenario_editor.sdk.json`) and add the endpoint identifier to the `endpoints` array:
+
+    ```json
+    {
+        "definition": {
+            "endpoints": ["summarise"]
+        }
+    }
+    ```
+
+    Run `pnpm run sdk generate` (or any `new`/`update` resource command) to regenerate the UI's `types.ts`. The generator merges a typed `Endpoints` interface into the UI's `Callbacks` type.
+
+2. Use the endpoint from the UI. Access it on the callbacks context exposed by the wrapper:
+
+    ```tsx
+    import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+    import type { Callbacks } from '../types';
+
+    function ReportButton({ reportText }: { reportText: string }) {
+        // The generated Callbacks narrows `endpoints` to the ones this UI declares
+        const { endpoints } = useUserInterfaceCallbacks() as unknown as Callbacks;
+
+        return (
+            <button
+                onClick={async () => {
+                    const { summary } = await endpoints['summarise']({
+                        text: reportText,
+                    });
+                    console.log(summary);
+                }}
+            >
+                Summarise
+            </button>
+        );
+    }
+    ```
+
+    `request` is typed from the endpoint's `requestSchema`. The returned promise resolves with the value validated against `responseSchema`.
+
+3. Handle errors. A failed call rejects with an `EndpointError`. Its `kind` says why, and its `applied` lists the effects that had already landed before it stopped:
+
+    | `kind`                                    | What happened                                                                                                       |
+    | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+    | `denied`                                  | The UI does not list the endpoint, or the call was refused before the request was read. Nothing changed             |
+    | `invalid-request`                         | The request does not match `requestSchema`. The handler did not run                                                 |
+    | `handler-error`                           | The handler threw, or ran past its time limit                                                                       |
+    | `invalid-response`                        | The handler returned something its declaration forbids, such as a response that does not match `responseSchema`     |
+    | `conflict`                                | A round started while the handler ran, so nothing was applied. A person may try again                               |
+    | `tick-failed`, or another step's own kind | One of the endpoint's actions failed once applied. `applied` lists what landed before it, and `failedStep` names it |
+    | `error`                                   | Anything else                                                                                                       |
+
+    ```tsx
+    import { EndpointError } from '@seriousgaming/sdk/ui';
+
+    try {
+        const { summary } = await endpoints['summarise']({ text: reportText });
+        setSummary(summary);
+    } catch (error) {
+        if (error instanceof EndpointError && error.applied.length > 0) {
+            // Part of the endpoint's work landed before it stopped
+            setNotice(`Some changes were saved, then: ${error.message}`);
+        } else {
+            setNotice(error instanceof Error ? error.message : String(error));
+        }
+    }
+    ```
+
+    An empty `applied` means nothing changed. A non-empty one means the session moved, so do not tell the person their action had no effect.
+
+4. (Optional) Return binary data. If the endpoint produces audio, images, or files, it returns a `blob:<id>` reference in the JSON response. Resolve it the same way as any blob reference:
+
+    ```typescript
+    const { getAssetUrl } = useUserInterfaceCallbacks();
+    const { endpoints } = useUserInterfaceCallbacks() as unknown as Callbacks;
+
+    const { audioRef } = await endpoints['narrate']({ text });
+    const src = getAssetUrl?.(audioRef);
+    <audio src={src} controls autoPlay />
+    ```
+
+    `getAssetUrl` comes from the untyped callbacks, since the generated `Callbacks` carries `endpoints` alone.
+
+## Verify
+
+- TypeScript: removing the endpoint identifier from the UI's `endpoints` array makes `callbacks.endpoints['summarise']` a type error
+- Runtime: removing the endpoint identifier from the UI's `endpoints` array makes the call reject with an `EndpointError` of kind `denied` and the message _'"ui" does not list endpoint "summarise" in its endpoints'_
+
+## Troubleshooting
+
+- _'"ui" does not list endpoint "X" in its endpoints'_: add the endpoint identifier to the UI's `endpoints` array, then regenerate types
+- _'Endpoint "X" rejected the request: ...'_ (`invalid-request`): your payload does not match `requestSchema`. Compare your call against the endpoint's request schema
+- _'Endpoint "X" returned a response its schema forbids: ...'_ (`invalid-response`): the endpoint handler is returning a value that does not match `responseSchema`. Fix the handler or widen the schema
+- _'Endpoint "X" stopped at action 1 ("tick"): ...'_: the endpoint's write and earlier actions landed, then an action failed. `error.applied` and `error.failedStep` say which
+
+## Related
+
+- [Create an endpoint](create-endpoint.md)
+- [Endpoints (concept)](../guides/endpoints.md)

package/dist/docs/recipes/check-a-package-from-a-script.md

@@ -0,0 +1,117 @@
+# Check a package from a script
+
+Validate a package and play a few ticks from CI or an AI agent, and turn each failure into the file and line to fix.
+
+**Keywords:** ci, agent, script, json, exit code, diagnostics, validate, automation, error code, pointer, source map
+
+## What you'll build
+
+A check that runs `build --validate-only` and a couple of ticks, branches on the exit code, and reads `diagnostics[]` to report each problem where it is: a JSON pointer into a bundle, or a line and column in your TypeScript.
+
+## Prerequisites
+
+- A package with `seriousgaming.sdk.json` in the working directory
+- `jq`, or any language that parses JSON
+
+## Steps
+
+### 1. Ask for one JSON document
+
+Pass `--json`, or set `SERIOUSGAMING_JSON=1` once for the whole job, and every command writes exactly one envelope to stdout. Run it through `pnpm run --silent` so pnpm's banner does not land on stdout before it.
+
+```bash
+export SERIOUSGAMING_JSON=1
+pnpm run --silent sdk build --validate-only > validate.json
+status=$?
+```
+
+Setting `SERIOUSGAMING_JSON` (or `CI`) also turns prompts off: a command that would have to ask fails with exit code 2 and `PROMPT_REQUIRED` instead of waiting.
+
+### 2. Branch on the exit code
+
+0 is success and 3 an invalid package; the others are in [Exit codes](../cli-reference.md#exit-codes).
+
+```bash
+case $status in
+    0) echo "Package is valid" ;;
+    3) echo "Package is invalid" ;;
+    *) jq -r '.error.code + ": " + .error.message' validate.json; exit $status ;;
+esac
+```
+
+### 3. Read the diagnostics
+
+Each diagnostic names a `file` relative to the package root, and either a `pointer` (RFC 6901, into a JSON file) or a `line` and `column` (in a source file). Branch on `code`; the `message` is for people.
+
+```bash
+jq -r '.diagnostics[]
+  | "\(.severity) \(.code) \(.file // "-")\(if .pointer then "#" + .pointer elif .line then ":\(.line):\(.column)" else "" end)\n  \(.message)\(if .hint then "\n  hint: " + .hint else "" end)"' validate.json
+```
+
+```
+error SETTINGS_UNKNOWN_KEY scenarios/hard/scenario.sdk.json#/definition/settings/engine/BaseDemnd
+  Overrides "BaseDemnd", which settings "engine" does not declare
+  hint: Did you mean 'BaseDemand'?
+```
+
+A passing build can still have warnings. They are in the success envelope's `diagnostics`, with `"severity": "warning"`.
+
+### 4. Play a tick and catch a logic error
+
+```bash
+pnpm run --silent sdk tick --no-server > tick.json || jq '.diagnostics[] | select(.code == "LOGIC_ERROR")' tick.json
+```
+
+When the engine throws, `tick` exits 4 with `error.code` `TICK_FAILED`, and the first diagnostic says where, read back through the bundle's source map, with the tick and team:
+
+```json
+{
+    "severity": "error",
+    "code": "LOGIC_ERROR",
+    "message": "the first round has no stock",
+    "file": "engine/logic.ts",
+    "line": 13,
+    "column": 15,
+    "resource": { "type": "engine", "identifier": "engine" },
+    "tick": 1,
+    "team": { "teamId": "team-1", "index": 0 }
+}
+```
+
+`--no-server` runs the session in the command's own process and leaves nothing behind, so each command starts from tick 0, and `tick` initialises the session before it plays. To play several ticks in a row, leave it off: the first command starts a background dev server, and `pnpm run sdk dev stop` stops it at the end of the job.
+
+### 5. Do the same from Node
+
+```typescript
+import { execFile } from 'node:child_process';
+
+execFile(
+    'pnpm',
+    ['run', '--silent', 'sdk', 'build', '--validate-only', '--json'],
+    (error, stdout) => {
+        const envelope = JSON.parse(stdout);
+        if (envelope.ok) return;
+        for (const diagnostic of envelope.diagnostics) {
+            const where = diagnostic.pointer ?? `${diagnostic.line}:${diagnostic.column}`;
+            console.log(`${diagnostic.code} ${diagnostic.file} ${where}: ${diagnostic.message}`);
+        }
+        process.exitCode = error?.code ?? 1;
+    }
+);
+```
+
+## Verify
+
+- Misspell a key in a scenario's `settings` and run step 1: the exit code is 3 and a `SETTINGS_UNKNOWN_KEY` diagnostic points at the key
+- Fix it and run step 1 again: the exit code is 0
+
+## Troubleshooting
+
+- **`JSON.parse` fails on the first line**: pnpm printed its banner on stdout. Add `--silent` to `pnpm run`
+- **A diagnostic has no `file`**: the check could not tie the finding to one file. Its `resource` and `message` still say what it is about
+- **`LOGIC_ERROR` has no `line`**: the throw came from somewhere other than your bundle's own frames, such as a timeout. The `resource` says which logic it was
+
+## Related
+
+- [CLI reference: exit codes, JSON output and diagnostics](../cli-reference.md#exit-codes)
+- [Publish a package to the Serious Gaming platform](publish-a-package.md)

package/dist/docs/recipes/create-capability.md

@@ -0,0 +1,66 @@
+# Create a capability
+
+Define a named slice of the game's state that the engine and screens read and write.
+
+**Keywords:** create capability, new capability, capability variables, data structure, capability schema, variablesSchema, scope
+
+## Prerequisites
+
+- A package with `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Create the capability. Its identifier is its directory name, and every variable declares a `type` and a `default`:
+
+    ```bash
+    pnpm run sdk new capability '{
+      "definition": {
+        "identifier": "pricing",
+        "variablesSchema": {
+          "type": "object",
+          "properties": {
+            "BasePrice": { "type": "number", "default": 100, "minimum": 0, "description": "Price before adjustments" },
+            "CurrentPrice": { "type": "number", "default": 100, "minimum": 0, "description": "Price after adjustments" }
+          },
+          "required": ["BasePrice", "CurrentPrice"],
+          "additionalProperties": false
+        }
+      }
+    }'
+    ```
+
+    This writes `capabilities/pricing/capability.sdk.json`. For nested objects, arrays, and keyed collections, see [Variable types](../guides/capabilities.md#variable-types).
+
+2. Optional: give it a `scope` other than the default `team`, by adding `"scope"` to the `definition` above: `shared` for one value across all teams, `team-readable` for a per-team value other teams may watch, or `private` for engine bookkeeping no screen receives. See [Scope](../guides/capabilities.md#scope).
+
+3. Declare it on each resource that uses it, in `reads` or `writes`. For the engine:
+
+    ```bash
+    pnpm run sdk update engine --patch '[
+      { "op": "add", "path": "/definition/writes/-", "value": "pricing" }
+    ]'
+    ```
+
+    The command regenerates that resource's `types.ts`, so `context.pricing` is typed.
+
+## Verify
+
+```bash
+pnpm run sdk init
+pnpm run sdk view
+```
+
+The team's context holds `pricing` with its defaults.
+
+## Troubleshooting
+
+| Problem                              | Solution                                                                    |
+| ------------------------------------ | --------------------------------------------------------------------------- |
+| A resource cannot see the capability | Declare it in that resource's `reads` or `writes`; it receives nothing else |
+| The build rejects a default          | The default does not match the variable's `type`                            |
+
+## Related
+
+- [Capabilities guide](../guides/capabilities.md): the state model, scope, lifetime, and variable types
+- [Create an engine](create-engine.md)
+- [Design state for concurrent writes](design-state-for-concurrent-writes.md)

package/dist/docs/recipes/create-endpoint.md

@@ -0,0 +1,127 @@
+# Create an endpoint
+
+**Keywords:** create endpoint, new endpoint, server handler, callable handler, scaffold endpoint
+
+## Prerequisites
+
+- A package with a valid `seriousgaming.sdk.json`
+- A UI that will call the endpoint (or plan to add one)
+- Optional: capabilities the endpoint will read
+
+## Steps
+
+1. Scaffold the endpoint:
+
+    ```bash
+    pnpm run sdk new endpoint
+    ```
+
+    Interactive mode prompts for a short identifier and the request and response properties. Alternatively pass a JSON definition:
+
+    ```bash
+    pnpm run sdk new endpoint '{
+      "definition": {
+        "identifier": "summarise",
+        "requestSchema": {
+          "type": "object",
+          "properties": { "text": { "type": "string" } },
+          "required": ["text"],
+          "additionalProperties": false
+        },
+        "responseSchema": {
+          "type": "object",
+          "properties": { "summary": { "type": "string" } },
+          "required": ["summary"],
+          "additionalProperties": false
+        },
+        "uses": ["generateText"]
+      },
+      "logic": { "directory": "logic", "entrypoint": "logic.ts" },
+      "rootDirectory": "."
+    }'
+    ```
+
+2. Fill in the handler at `endpoints/<identifier>/logic/logic.ts`:
+
+    ```typescript
+    import { getText } from '@seriousgaming/sdk';
+
+    import type { Handler } from '../types';
+
+    export const Handle: Handler = async ({ request, callbacks, caller }) => {
+        const response = await callbacks.generateText({
+            prompt: `Summarise this text in one sentence: ${request.text}`,
+        });
+        return { summary: getText(response) };
+    };
+    ```
+
+    The signature is `({ request, context, callbacks, caller, team, meta }) => Promise<Response>`, where `team` is the team a team-scoped call runs for. A session-scoped handler has no `team`. An endpoint that declares no `writes` cannot change state: return only what fits the declared `responseSchema`.
+
+    To change state, declare the capabilities you may write and return the change alongside the response. `scope`, `writes`, and `visibility` can go straight into the `definition` you pass to `new endpoint`, which then scaffolds a handler of the writing shape:
+
+    ```json
+    { "scope": "team", "writes": ["price"] }
+    ```
+
+    ```typescript
+    export const Handle: Handler = async ({ request, context }) => ({
+        response: { previous: context.price.Price, current: request.price },
+        capabilities: { price: { ...context.price, Price: request.price } },
+    });
+    ```
+
+    The generated `Handler` type switches shape when `writes` is present, so the compiler tells you which one you owe, and a writing endpoint that returns a bare value is refused at run time. Writes are held to the declaration, and are not put to the game's validators: see [Endpoints (concept)](../guides/endpoints.md#endpoints-and-validators) for why.
+
+3. Set the scope if the endpoint is not called against a single team:
+
+    ```json
+    { "scope": "session" }
+    ```
+
+    `scope` defaults to `'team'`, which gives the handler that team's board and a `team` naming it: `team.teamId`, `team.index` and `team.name`. Use `team`, not `caller`, to find the team's own row in anything keyed by team: `caller` says who is calling, and a facilitator's agent or the CLI calls on a team's behalf without being on it, so its `caller.teamId` is absent. `caller.teamId` is set only for a participant or an observer, and names their own team. A session UI, a setup screen, or a scenario editor has no team of its own, so calling a team-scoped endpoint from one fails the build.
+
+4. Declare the endpoint on every UI that should be allowed to call it:
+
+    ```json
+    {
+        "definition": {
+            "endpoints": ["summarise"]
+        }
+    }
+    ```
+
+    UIs that don't list the endpoint cannot call it. Add the identifier to each consuming UI's `endpoints` array.
+
+5. Use the endpoint from the UI. The generated `types.ts` makes `callbacks.endpoints` strongly typed:
+
+    ```typescript
+    const { summary } = await callbacks.endpoints['summarise']({
+        text: 'lots of text here',
+    });
+    ```
+
+## Verify
+
+- `pnpm run sdk endpoint list` shows the endpoint with its scope and whether it writes
+- `pnpm run sdk endpoint call <identifier> --team 1 --request '{...}'` runs it without a UI
+- `pnpm run sdk generate` (or any `new`/`update` command) produces `endpoints/<identifier>/types.ts` with `Request`, `Response`, `Context`, and `Handler` exports (plus `Writes`, where the endpoint declares any)
+- Calling an undeclared endpoint from a UI is a TypeScript error
+- The dev server rejects calls when the UI did not declare the endpoint or when the request shape does not match `requestSchema`
+
+## Troubleshooting
+
+- _'Endpoint X not found in configuration'_: re-run `pnpm run sdk generate`; the endpoint's bundle must sit at `endpoints/<identifier>/endpoint.sdk.json`
+- _'Endpoint "X" rejected the request: \<path\> must have required property ...'_: the iframe sent a payload that does not match `requestSchema`. Check that the UI's call matches the declared request shape
+- _'"ui" does not list endpoint "X" in its endpoints'_: add the endpoint identifier to the UI's `endpoints` array
+- _'Resource "X" attempted to call callback "Y" but did not declare it in its bundle's "uses" array'_: add the `ApiUse` value to the endpoint bundle's `uses` array
+- _'which is team-scoped, but this surface has no team of its own'_: a session UI, setup screen, or scenario editor is calling it; set `"scope": "session"` on the endpoint
+- _'wrote X, which it does not declare in writes'_: the handler returned a capability outside its `writes`; add it, or stop returning it
+- _'The game moved on while the endpoint was running'_: a tick committed mid-call, so the patch was computed against a board that no longer exists. Make the handler faster, or move the work into the engine
+
+## Related
+
+- [Make an endpoint callable from outside the game](make-an-endpoint-external.md)
+- [Call an endpoint from a UI](call-endpoint-from-ui.md)
+- [Declare API uses](declare-api-uses.md)
+- [Endpoints (concept)](../guides/endpoints.md)