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

package/dist/docs/environment-variables.md

@@ -0,0 +1,102 @@
+# Environment variables
+
+A single reference for every environment variable the dev server and CLI read. Set these in a `.env` file in your project root, export them in your shell, or pass equivalents as CLI flags (flags take priority).
+
+The dev server resolves config in this order, highest priority first: CLI flags → `process.env` → `.env` file → [global settings file](./guides/global-settings.md) → built-in defaults.
+
+## LLM (`generateText`)
+
+Used by the engine, hooks, tick controllers, and endpoints that declare `'generateText'` in `uses` (UIs reach it through an endpoint). Text generation runs through the Serious Gaming platform's LLM pipeline, so the only credential needed is a platform API key. The same variables configure `package publish`. See the [LLM integration guide](./guides/llm-integration.md).
+
+| Variable                 | Required       | Default                               | Purpose                         |
+| ------------------------ | -------------- | ------------------------------------- | ------------------------------- |
+| `SERIOUSGAMING_API_KEY`  | If LLM is used | None                                  | Serious Gaming platform API key |
+| `SERIOUSGAMING_API_HOST` | No             | `https://app.businesssimulations.com` | Platform origin to call         |
+
+Tier-to-model mapping is configured on the platform; there are no per-tier model variables. Equivalent CLI flags on `pnpm run sdk dev`: `--api-key`, `--host`.
+
+## Text-to-speech (`generateSpeech`)
+
+Used by the engine, hooks, tick controllers, and endpoints that declare `'generateSpeech'` in `uses` (UIs reach it through an endpoint). The dev server ships with an ElevenLabs adapter. See the [speech generation guide](./guides/speech-generation.md).
+
+| Variable              | Required       | Default                           | Purpose                             |
+| --------------------- | -------------- | --------------------------------- | ----------------------------------- |
+| `ELEVENLABS_API_KEY`  | If TTS is used | None                              | ElevenLabs API key                  |
+| `TTS_MODEL_QUICK`     | No             | `eleven_flash_v2_5`               | Model for the `quick` tier          |
+| `TTS_MODEL_STANDARD`  | No             | Falls back to quick               | Model for the `standard` tier       |
+| `TTS_MODEL_EXPERT`    | No             | Falls back to standard            | Model for the `expert` tier         |
+| `TTS_VOICE_NEUTRAL`   | No             | ElevenLabs default voice          | Voice ID for the `neutral` preset   |
+| `TTS_VOICE_NARRATOR`  | No             | Falls back to `TTS_VOICE_NEUTRAL` | Voice ID for the `narrator` preset  |
+| `TTS_VOICE_ANNOUNCER` | No             | Falls back to `TTS_VOICE_NEUTRAL` | Voice ID for the `announcer` preset |
+| `TTS_VOICE_EXECUTIVE` | No             | Falls back to `TTS_VOICE_NEUTRAL` | Voice ID for the `executive` preset |
+| `TTS_VOICE_COACH`     | No             | Falls back to `TTS_VOICE_NEUTRAL` | Voice ID for the `coach` preset     |
+
+Any `TTS_VOICE_<NAME>` env var is exposed as the `<name>` preset (lowercased), so authors can define custom presets beyond the recommended five.
+
+Browse voice IDs at <https://elevenlabs.io/voices>.
+
+## Package publishing (`pnpm run sdk package publish`)
+
+`package publish` uses `SERIOUSGAMING_API_KEY` and `SERIOUSGAMING_API_HOST` as above, plus the publisher to upload under. See [Publish a package](./recipes/publish-a-package.md).
+
+| Variable                  | Required               | Default                                        | Purpose                        |
+| ------------------------- | ---------------------- | ---------------------------------------------- | ------------------------------ |
+| `SERIOUSGAMING_PUBLISHER` | Unless set another way | `platform.defaultPublisher` in global settings | Publisher slug to upload under |
+
+Equivalent CLI flag: `--publisher`, which takes priority.
+
+## Global settings file
+
+| Variable                   | Required | Default                            | Purpose                                                  |
+| -------------------------- | -------- | ---------------------------------- | -------------------------------------------------------- |
+| `SERIOUSGAMING_SDK_CONFIG` | No       | `~/.seriousgaming-sdk/config.json` | Absolute path to the global settings file to use instead |
+
+A relative path is an error. See the [global settings guide](./guides/global-settings.md).
+
+## Dev server
+
+A session command starts a dev server when none is running, and has no `--port` of its own to pass it. This is how to tell that server where to start looking. See [The CLI and the dev server](./cli-and-dev-server.md).
+
+| Variable                      | Required | Default                             | Purpose                                                                         |
+| ----------------------------- | -------- | ----------------------------------- | ------------------------------------------------------------------------------- |
+| `SERIOUSGAMING_DEV_PORT`      | No       | `3000`                              | Where the dev server starts looking for a free port, or `auto` for any free one |
+| `SERIOUSGAMING_DEV_URL`       | No       | Unset                               | The server every session command targets, in place of the one the lock names    |
+| `SERIOUSGAMING_DEV_STATE_DIR` | No       | The package's `.seriousgaming-sdk/` | Where the lock file naming the running server is kept                           |
+
+`SERIOUSGAMING_DEV_PORT` is a starting point, not a binding: the server steps up to the first free port from there, and prints the one it lands on. Equivalent CLI flag on `pnpm run sdk dev`: `--port`.
+
+`SERIOUSGAMING_DEV_URL` is for a server no lock names, such as one started with `sdk dev --isolated` beside your own, for a test run or a recording. With it set, a command never starts a server: one that does not answer fails the command with `DEV_SERVER_UNREACHABLE`.
+
+`SERIOUSGAMING_DEV_STATE_DIR` moves the lock out of the project, since it is runtime state rather than project content: a container whose project directory is restored from a snapshot otherwise brings back a lock naming a process from before it. Each package gets its own entry inside it, so one directory can serve several. Saved configuration and uploads stay in the package. See [Where the session lives](./cli-reference.md#where-the-session-lives).
+
+## Output and prompts
+
+| Variable             | Required | Default | Purpose                                                                                   |
+| -------------------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
+| `SERIOUSGAMING_JSON` | No       | Unset   | `1` makes every command print one JSON document on stdout, as if `--json` had been passed |
+| `CI`                 | No       | Unset   | Any value turns interactive prompts off: a command that would ask fails with exit code 2  |
+
+See [Exit codes](./cli-reference.md#exit-codes) and [JSON output](./cli-reference.md#json-output). Prompts are also off whenever stdin or stdout is not a terminal, and under JSON output.
+
+## Example `.env`
+
+```
+# Serious Gaming platform (LLM + package publish)
+SERIOUSGAMING_API_KEY=sg_...
+
+# Dev server
+SERIOUSGAMING_DEV_PORT=3310
+
+# Speech
+ELEVENLABS_API_KEY=...
+TTS_VOICE_NEUTRAL=21m00Tcm4TlvDq8ikWAM
+TTS_VOICE_NARRATOR=ErXwobaYiN019PkySvjV
+TTS_VOICE_ANNOUNCER=VR6AewLTigWG4xSOukaG
+```
+
+Never commit `.env` to version control. The `.gitignore` scaffolded by `new package` already lists it; check a package scaffolded some other way does too.
+
+## Verify
+
+- `pnpm run sdk dev` boots without warnings
+- Calling `callbacks.generateText` and `callbacks.generateSpeech` from a resource with the right `uses` declarations succeeds (no `LLMClientError` / `TtsClientError`)

package/dist/docs/getting-started.md

@@ -0,0 +1,145 @@
+# Getting started
+
+Scaffold the starter game, play it in the dev server, change one thing, and see the change. It takes about 15 minutes, and you finish with a working game you understand well enough to reshape.
+
+**Keywords:** getting started, quick start, first game, starter game, lemonade stand, scaffold, new package, tutorial
+
+## Prerequisites
+
+- Node.js 24 or later
+- pnpm 12
+- A text editor, and some familiarity with TypeScript and React
+
+## 1. Scaffold the starter game
+
+Nothing is installed yet, so run the CLI through `pnpm dlx`, in an empty directory. The packages are on the public npm registry, so there is no token or `.npmrc` to set up first:
+
+```bash
+mkdir my-game
+cd my-game
+pnpm dlx @seriousgaming/sdk-tools new package
+```
+
+The command asks for three things: the package identifier (reverse-domain, such as `com.example.mygame`), the game's name, and a version. It then writes the package, installs its dependencies, and generates each resource's `types.ts`. There is no separate install step. If the install fails, the package is still written and the command tells you so; run `pnpm install` yourself once the cause is fixed.
+
+What you get is a complete game rather than an empty shell. A lemonade stand, 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 game is copied out whole rather than rendered from templates, and it is the same game the SDK's own test suites play, so what you are handed is known to work. Pass `--empty` if you want only the package files and nothing else; [Start a game from an empty package](./recipes/start-from-an-empty-package.md) picks up from there.
+
+## 2. Take the tour
+
+[A tour of the starter game](./guides/starter-game.md) walks through every directory and file you now have, says what each one does, and points at the guide that goes deeper. Skim it now, or keep it open beside the next steps.
+
+## 3. Play it
+
+Start the dev server:
+
+```bash
+pnpm run sdk dev
+```
+
+It opens the facilitator console at `http://localhost:3000`, which is the game's session UI: the screen a facilitator runs the session from. Leave it running in its own terminal, and use a second terminal for everything below.
+
+The starter game begins with its participants held in the waiting room, which is the right start for a live session. To play:
+
+1. Open `http://localhost:3000/team/1/player/1` in a new tab. This is the game UI for the first participant on team 1, and it shows the waiting room
+2. In the console tab, switch off **Waiting room**. The participant's tab moves to the stall
+3. Open `http://localhost:3000/team/1/player/2` as well. Each participant is put in charge of one item on the menu, so the two tabs can change different numbers without overwriting each other
+4. Set how many of each thing to make, then press **Open the stall**. The engine runs one tick, which this game calls a day, and **How yesterday went** shows what sold, what was poured away, and who was turned away
+
+Press the backtick key on any page for the dev drawer: tick, undo, and reset controls, the state as JSON, and the list of surfaces. Every page takes `?bare` to hide the dev chrome.
+
+## 4. Change a setting
+
+A game's numbers live in settings rather than in code, so the first change needs no code at all. The menu's settings are declared in `settings/menu/settings.sdk.json`, and every resource that needs them lists `"menu"` in its own `settings` (the engine's is in `engine/engine.sdk.json`). One of them is how much the stall can make in a day:
+
+```json
+"Capacity": {
+    "type": "number",
+    "description": "How many items the stall can make in a day, across the whole menu",
+    "default": 120,
+    "minimum": 1
+}
+```
+
+Halve it for this session:
+
+```bash
+pnpm run sdk configure '{"menu":{"Capacity":60}}'
+```
+
+The key is the settings identifier, `menu`, the directory name under `settings/`. `configure` validates the value against that schema and writes it to `.seriousgaming-sdk/configuration.json`, the session-override layer, which wins over the others (see [Overriding settings](./guides/settings.md#overriding-settings)). The game's validator and UI read it as `settings.menu.Capacity`. Settings are fixed when play starts, so `configure` puts the running session back at tick 0 on the new value. The stall now says it can make 60 things in a day, and a plan over 60 is refused by the game's validator.
+
+To go back to the defaults, clear the overrides, which restarts the session on them:
+
+```bash
+pnpm run sdk configure '{}'
+```
+
+## 5. Change the engine
+
+The engine is `engine/logic.ts`: an `Init` that sets up each team's first morning, and a `Run` that plays one day. Inside `Run`, this is the line that makes the stall pay for everything it made, including what it poured away:
+
+```typescript
+// You paid to make everything, including what you poured away. That is
+// the whole of the lesson about making too much.
+spent += made * entry.Cost;
+```
+
+Change `made` to `sold`, so the stall pays only for what it sells:
+
+```typescript
+spent += sold * entry.Cost;
+```
+
+Save the file and play another day. You do not need to restart anything or reset the session. The dev server watches the package, and the next tick runs the new code. What it does not do is re-run days already played, so the change shows from the next day onwards: **Spent** no longer counts what was poured away, so making too much stops costing anything.
+
+Edits to a UI hot-reload in the browser, and edits to a `*.sdk.json` bundle or to `seriousgaming.sdk.json` are picked up without a restart too. A change to a setting, which reaches the game through `Init`, waits for you to re-initialise once a day has been played: the console says so and offers a button. The [CLI reference](./cli-reference.md#what-reloads) has the whole table.
+
+## 6. Drive it from the CLI and run its tests
+
+Everything the console does, the CLI does too, against the same session:
+
+```bash
+pnpm run sdk tick --patch '[{"op":"replace","path":"/plan/Make/lemonade","value":70}]'
+pnpm run sdk view
+```
+
+`tick --patch` writes a decision into the context, here 70 lemonades, and then runs a tick; `view` prints the session as JSON. Both reach the dev server you started in step 3, so the browser repaints as they run.
+
+Session commands (`init`, `tick`, `view`, `patch`, `undo`, `reset`, and the rest) always talk to a dev server. If none is running, the command starts one in the background, says so on stderr, and leaves it running for the next command. Check on it or stop it with:
+
+```bash
+pnpm run sdk dev status
+pnpm run sdk dev stop
+```
+
+A background server holds the package's one session, so `sdk dev` refuses to start a second and gives you the address of the first instead. Add `--no-server` to a session command to run it in-process against a fresh session with nothing left behind. [Drive a game from the CLI](./cli-simulation-testing.md) covers the whole workflow.
+
+Now run the tests:
+
+```bash
+pnpm test:run
+pnpm test:engine
+```
+
+`test:run` runs the unit tests beside each resource, and `test:engine` plays whole games in-process with `createTestSession`, with no server and no browser. With the change from step 5 in place, one test in each suite fails: `pours away what it made and did not sell, having paid for it` in the unit tests, and `pours away what nobody wanted, having already paid for it` in the whole-game tests. That is the suite guarding the rule you just changed. Put the line back, or update the tests if the new rule is the one you want. `pnpm test:e2e` runs the browser tests with Playwright. They start a dev server of their own, and a package holds one session, so stop yours first with `sdk dev stop` or Ctrl+C.
+
+## Working with an AI coding agent
+
+A scaffolded package includes a `CLAUDE.md` and `.claude/rules/` written for coding agents. They cover the workflows an agent needs (creating resources, testing, publishing) and tell the agent to leave `sdk dev` for you to start. The points worth knowing:
+
+- Session commands print JSON, so an agent can read state with `view` and make decisions with `tick --patch`
+- Use `pnpm run --silent` when parsing output, so pnpm's banner stays out of the JSON
+- The dev server and the CLI share one session, so you can watch in the browser while an agent plays from the terminal
+
+[The CLI and the dev server](./cli-and-dev-server.md) explains how the two fit together.
+
+## Next steps
+
+- [Design state for concurrent writes](./recipes/design-state-for-concurrent-writes.md): the rule the starter game is built around. Keep its shape when you replace its model
+- [Terminology](./concepts/terminology.md): the words the rest of the docs use, each with one meaning
+- [Core concepts](./concepts/index.md): why the SDK is shaped the way it is
+- [Creating engines](./guides/engine.md) and [Building user interfaces](./guides/ui.md): the full reference for the two resources you will change most
+- [Start a game from an empty package](./recipes/start-from-an-empty-package.md): build your own game from nothing, once you know what the starter game does
+- [CLI reference](./cli-reference.md): every command and flag

package/dist/docs/guides/ai-facilitation.md

@@ -0,0 +1,220 @@
+# Structuring a game for AI facilitation
+
+A facilitator running your game may have an AI agent beside them: something they can ask 'how is Team B doing', 'why has their profit fallen', or 'set their unit price to 3.53'. This guide covers what that agent can see, what it can do, and what you as an author need to write down so it behaves.
+
+Most of it is not new machinery. An agent acting for a facilitator is close to a facilitator's own screen: it sees what a screen declares, and it acts through endpoints. What is new is that the words you write become load-bearing, because a model reads them to decide what to do.
+
+## What the agent can see
+
+A game's data lives in named capabilities. Every screen declares which ones it needs, and receives exactly those. The agent is handed data the same way, so nothing you have not declared reaches it.
+
+Two consequences worth planning around.
+
+**Mark engine internals private.** Simulations accumulate state that exists only to get from one tick to the next: a serialised engine, a smoothing accumulator, a seed, a ledger the next tick consumes. A capability with `scope: 'private'` reaches your logic exactly as before and reaches no screen at all. In `capabilities/engine_state/capability.sdk.json` (the directory names the capability):
+
+```json
+{
+    "definition": {
+        "scope": "private",
+        "variablesSchema": { "…": "…" }
+    }
+}
+```
+
+This matters more for an agent than for a screen. A screen ignores a capability it does not render. A model reads everything it is given, and an opaque blob of serialised simulation state is the single most reliable way to make it say something confidently wrong.
+
+**Keep capabilities a size a model can be handed.** A capability holding a thousand values is fine for a screen that renders a table from it and expensive for an agent asked a one-sentence question. Where a capability has grown that large, either split it or compute a summary into a smaller one. The same aggregate your session UI already renders is usually the right thing.
+
+## Describing your data
+
+This is the highest-value thing on the list and it is not code.
+
+A model handed `Backlog: 153` knows nothing: not the unit, not whether high is good, not what counts as normal in your game. The schema where you define a capability has room for a description per variable, and filling it in is what turns numbers into something an agent can reason about.
+
+```json
+{
+    "Backlog": {
+        "type": "number",
+        "default": 0,
+        "description": "Unfulfilled orders carried into the next round, in units. Lower is better; above about 200 a team is losing customers."
+    }
+}
+```
+
+Three things to include, in roughly this order of value:
+
+- The unit, always. 'Revenue' could be pounds, thousands of pounds, or units sold
+- Which direction is good, where it is not obvious from the name
+- A sense of scale, where you have one. 'Typically 50 to 400' costs you eight words and saves the agent guessing
+
+You do not have to do this everywhere at once. Start with the capabilities a facilitator actually asks about, which are usually the ones already on your session UI.
+
+Two things descriptions cannot fix. The agent has no baseline unless it can also see history, so comparisons come from past ticks rather than from prose. And a snapshot is a board, not a narrative: 'which stakeholder did they engage most' is answerable only if your engine wrote that down.
+
+## Letting the agent do things
+
+An agent performs game-specific actions through endpoints, the same server-side handlers your own screens call. An endpoint becomes available to an agent, and to any other caller outside the game such as a platform API, when its `visibility` is `external`:
+
+```json
+{
+    "definition": {
+        "displayName": "Set the unit price",
+        "description": "Sets a team's unit price, in pounds per unit. Use when a facilitator asks to change what a team charges, for example to unblock a team that has priced itself out of the market. Must be between 0 and 50.",
+        "scope": "team",
+        "visibility": "external",
+        "writes": ["price"],
+        "…": "…"
+    }
+}
+```
+
+An endpoint is `internal` by default, and a caller outside the game is refused it. An endpoint you wrote for your own screens does not become part of an agent's vocabulary until you opt it in, because publishing an operation is a different act from wiring a button to a handler. The agent's handler sees `caller.role` as `'external'`, so it can tell the call from one made by the facilitator's own screens.
+
+### Writing a description a model can act on
+
+Everywhere else in the SDK a description is author-time convenience. Here it is the text a model reads to decide whether to call your endpoint, so the build refuses an external endpoint without one.
+
+What separates a good one from a bad one is not length:
+
+- Say what it does **and when to reach for it**. 'Sets the unit price' tells a model what the name already told it; 'use when a facilitator asks to change what a team charges' tells it when to choose this over the other eleven
+- State the bounds in prose as well as in the schema. The schema refuses a bad call; the description stops the model making it
+- Make it distinguishable from its neighbours. Three endpoints that all say 'updates the team' will be picked between at random
+
+Read yours side by side before you ship:
+
+```bash
+pnpm run sdk endpoint list --external
+```
+
+That is when 'updates the team' three times becomes obvious, and it is the one failure mode in this whole area that no test catches.
+
+### Scope
+
+An endpoint declares whether it acts on one team or on the session. 'Set Team B's price' is team-scoped; 'open the next tick for everyone' is session-scoped.
+
+Do not put a team in your request schema. The platform resolves which team the facilitator meant and hands it to your handler on `team`, as `{ teamId, index, name }`, so a summary can say 'The Daily Grind placed 2nd' and a lookup can find that team's row by `team.teamId`. A team the model typed is a team the model can invent.
+
+Scope decides what the handler can change, and the build holds you to it: see [What each scope may write](./endpoints.md#what-each-scope-may-write). A session-scoped endpoint is how an agent changes something for the whole room, through a shared capability, or for several teams in one call, through per-team patches under `teams` where every team changes or none does. Its own `writes` array is what authorises it: an agent has no screen to borrow permission from.
+
+### Asking about the whole room
+
+A session-scoped endpoint has no team of its own, so its reads arrive split:
+
+- A `shared` capability comes in on `context`, as the single value it is
+- A `team`, `team-readable` or `private` capability comes in on `teams`, one entry per team
+
+```typescript
+export const Handle: Handler = async ({ context, teams }) => ({
+    average: context.market.AveragePrice,
+    behind: (teams ?? [])
+        .filter((team) => team.context.decisions.Price > context.market.AveragePrice)
+        .map((team) => team.name),
+});
+```
+
+This is what lets an agent answer 'which teams haven't submitted yet' or 'who is charging above the market' in one call rather than one call per team.
+
+### Asking about the past
+
+An endpoint can read any tick that has already closed, through `callbacks.getPastState`. It needs no declaration beyond the capabilities it already reads:
+
+```typescript
+export const Handle: Handler = async ({ request, callbacks }) => {
+    const rounds = await callbacks.getPastState<Context>({
+        fromTick: 0,
+        toTick: Number.MAX_SAFE_INTEGER,
+        capabilityIds: ['profit'],
+    });
+    return { trend: rounds.map((round) => round.context.profit.Profit) };
+};
+```
+
+This is what makes 'how has Team B been doing' answerable. An agent has no screen, so it cannot fetch the ticks itself and hand them over the way one of your own surfaces would.
+
+Two things to know. A range running past the last completed tick comes back **short rather than failing**, so treat a short answer as normal. And the same read is available in your engine, which means a capability you were keeping purely to carry last tick's figure forward can go: that value rides every push to every participant for the rest of the session, and the snapshot it was copied from is already recorded.
+
+**Read wide, answer narrow.** The whole point of doing this in an endpoint is that every team's board is assembled server-side and never crosses back to the model. A hundred teams' raw state is both slow to hand to a model and useless once it gets there; a hundred teams reduced to the four names that answer the question is neither. Summarise in the handler, and declare the narrowest `reads` that answer the request.
+
+### What checks the request
+
+Three different things ask three different questions, and you want all three:
+
+- `requestSchema` asks whether the request is well formed. The runtime refuses a bad one before your handler runs
+- Your handler asks whether the request makes sense given what it knows. This is the only place that can
+- A validator asks whether the resulting state is legal, and **does not run for an endpoint's write**
+
+That last point is deliberate and worth understanding, because it is the opposite of what people expect. Validators exist to gate what a participant submits directly, where your game has no code in the path. An endpoint is your code in the path.
+
+It also buys you something. A validator can refuse a change outright while a strict endpoint is the one sanctioned way to make it:
+
+- The validator refuses any direct write to `price` from a participant
+- The endpoint sets `price`, having checked the facilitator's reasons
+
+Now there is exactly one route to that value, and you wrote it.
+
+### Running the session, not only the game
+
+An agent managing a session needs to do what a facilitator does: close the waiting room, start the next round, give a team more time. An endpoint can return those as `actions`, and the runtime carries them out after its write, in one step. So 'start the next round' is one tool call that the game wrote the rules for, rather than three platform calls the agent has to sequence and get right.
+
+```typescript
+export const Handle: Handler = async ({ session }) => {
+    if (session.complete) throw new Error('The game is complete');
+    return {
+        response: { fromRound: session.completedTicks },
+        actions: [
+            ...(session.waitingRoomOpen ? [{ type: 'setWaitingRoom' as const, open: false }] : []),
+            { type: 'tick' },
+        ],
+    };
+};
+```
+
+`session` is what lets the endpoint decide. It says which round it is, whether the waiting room is open, whether the game is over, and where each team stands, which are the first things an agent asks before it acts. Declare `roster: true` to have each team's participants listed too.
+
+The response is computed before the actions run, so it cannot say what they did. When the agent needs to hear the outcome, such as the round now in play, answer in two phases: `Plan` returns the actions, and `Respond` writes the response once they have landed. See [Act on the session from an endpoint](../recipes/act-on-the-session-from-an-endpoint.md).
+
+### Taking and returning files
+
+An agent working with a facilitator often has a file in hand: a research pack, a team photo, a brief. Mark a request property as a file with `blob`, and the agent can send it inline as a `data:` URI, or upload it first and send the reference. Your handler always receives a checked `blob:` reference. See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
+
+Going the other way, an endpoint that writes a report or an export with `writeBlob` returns its reference, and the runtime gives a caller outside the game a URL to fetch it from. How the file reaches the model or the person, inline or as a link, is the platform's choice.
+
+### Who did what
+
+An agent's change looks like anyone else's once it has landed. A platform that knows which agent or API key is calling passes it as `caller.principal`, so an endpoint can answer one caller differently from another, and the runtime keeps an audit of every endpoint call that changed the session: which endpoint, who called it, what it wrote and what it did. Locally, `pnpm run sdk endpoint audit` reads it.
+
+## Testing it without a model
+
+You do not need an agent to develop against this.
+
+```bash
+# What an agent would be offered, with the descriptions it reads
+pnpm run sdk endpoint list --external
+
+# Run one as an outside caller, with no model in the loop
+pnpm run sdk endpoint call setprice --external --team 1 --request '{"price": 3.53}'
+
+# As a particular agent, sending a file, and keeping what comes back
+pnpm run sdk endpoint call attachresearch --external --team 1 \
+    --principal agent:claude-7:Claude --attach document=./research.pdf --save-blobs ./out
+
+# What every endpoint call changed, and who made it (needs a running dev server)
+pnpm run sdk endpoint audit
+```
+
+Exercise the failure paths too, because they are what a model will find: a value outside the schema, a missing property, a team that does not exist.
+
+## What is not in the SDK
+
+The agent itself, and the protocol it speaks, are the platform's. The SDK's job is to make sure the package a platform reads carries everything an agent needs: declared data with descriptions, internals marked private, and operations that say who may call them.
+
+That means you can prepare a game for AI facilitation now, and it will be ready when the platform side arrives.
+
+## Related
+
+- [Endpoints](./endpoints.md)
+- [Make an endpoint callable from outside the game](../recipes/make-an-endpoint-external.md)
+- [Act on the session from an endpoint](../recipes/act-on-the-session-from-an-endpoint.md)
+- [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md)
+- [Capabilities](capabilities.md)
+- [Validators](validators.md)