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

package/dist/docs/guides/multi-team-games.md

@@ -0,0 +1,586 @@
+# Multi-team games
+
+This guide explains how to build and test games where multiple teams compete, cooperate, or operate independently. It covers play modes, shared capabilities, an aggregate engine, team composition, and how to run multi-team simulations via the dev server and CLI.
+
+## What you'll learn
+
+- The two interaction modes: **independent** and **shared-state**
+- How to declare your game's interaction mode and set team composition constraints
+- How to use shared capabilities and an aggregate engine for cross-team interaction
+- How to test multi-team games with `--teams N` in the dev server and CLI
+
+## Play modes
+
+Every multi-team game operates in one of two **interaction modes**. The mode is a fixed property of the game definition: the author chooses it once, and facilitators and participants never select it. This keeps a structural, technical concern out of the hands of everyone downstream of authoring.
+
+### Independent mode
+
+Teams are fully isolated: each team has its own context, makes its own decisions, and **ticks on its own schedule**. No cross-team data flows between teams. This is the right mode for games where teams solve the same challenge in parallel without affecting each other (e.g. training exercises, individual assessments).
+
+An aggregate engine still executes in independent mode, but each call receives a single-element `teams` array containing only that team's context. This means the same engine code works in both modes without branching.
+
+### Shared-state mode
+
+Teams interact through **shared capabilities** computed by **an aggregate engine**. All teams **tick together** (synchronised) because an aggregate engine needs every team's state at the same point in time. This is the right mode for competitive markets, cooperative scenarios, or any game where one team's decisions affect another.
+
+**Example**: In a market simulation, each team sets their own `Price`, and the resulting `MarketShare` depends on all teams' prices. `Price` and `MarketShare` are both per-team; a session-wide figure computed from every team's decisions, such as `AverageMarketPrice`, is what comes from a shared capability.
+
+### Declaring the interaction mode
+
+In your `seriousgaming.sdk.json`:
+
+```json
+{
+    "identifier": "com.example.marketsim",
+    "teams": {
+        "mode": "shared-state"
+    }
+}
+```
+
+- A game runs in exactly one interaction mode.
+- If `teams.mode` is omitted, it defaults to `independent`.
+- The mode is fixed at authoring time. If a single game genuinely needs both topologies, ship two game definitions.
+
+### Team composition
+
+Games can declare advisory metadata about team and participant counts:
+
+```json
+{
+    "identifier": "com.example.marketsim",
+    "teams": {
+        "mode": "shared-state",
+        "min": 2,
+        "max": 6,
+        "perTeam": {
+            "minParticipants": 3,
+            "maxParticipants": 8
+        }
+    }
+}
+```
+
+| Field                     | Meaning                                           |
+| ------------------------- | ------------------------------------------------- |
+| `min`                     | Minimum number of teams this game is designed for |
+| `max`                     | Maximum number of teams this game is designed for |
+| `perTeam.minParticipants` | Minimum participants per team                     |
+| `perTeam.maxParticipants` | Maximum participants per team                     |
+
+All fields are optional, and each is enforced differently. Every field but `mode` is a [game setting](./settings.md#the-game-settings), so a scenario or a setup screen can change it; what follows applies to the value it resolves to. `max` is hard at every point: no session holds more teams, and a runtime may cap it further with its own platform ceiling (40 teams on the reference platform), so the effective maximum is the lower of the two. `min` applies when a session is created and again when play starts: a team count outside `min` and `max` is refused rather than adjusted, and once the session is running a team can be removed down to one. The `perTeam` fields are advisory. The dev server uses `min` as the default team count when `--teams` is not passed.
+
+### Naming teams
+
+Every team carries a platform-assigned, session-stable, zero-based `index`. Team ids are `team-${index + 1}`, so the team with index 0 is `team-1`. The index never renumbers: removing a team leaves a gap in the `team-N` sequence, and a later-added team takes the lowest unused index. That team is a new one with the default name: nothing of the removed team comes back with it. Only an empty team in an independent-mode session can be removed (see [Deleting a team](./session.md#deleting-a-team)).
+
+By default teams are shown as 'Team 1', 'Team 2', and so on. To give them meaningful default names (for example a game where each team is a predefined brand), declare `teams.defaultNames`: an ordered, localised list applied by index, so entry N names the team with index N.
+
+```json
+{
+    "identifier": "com.example.marketsim",
+    "teams": {
+        "mode": "shared-state",
+        "defaultNames": [
+            { "en": { "name": "Acme" }, "fr": { "name": "Acmé" } },
+            { "en": { "name": "Globex" } },
+            { "en": { "name": "Initech" } }
+        ]
+    }
+}
+```
+
+Each entry is a locale-keyed map, the same shape used for other localised fields. Resolution works as follows:
+
+- A name is shown in the session's locale, falling back to another locale the entry declares, then to the positional default ('Team N')
+- Indexes beyond the end of the list fall back to the positional default ('Team N')
+- Because names are applied by index, display names and game-logic identity cannot diverge: a re-added team recovers its `defaultNames` entry along with its index
+- A scenario can replace these names with its own list, under `settings.game.teams.defaultNames`, so one game can present different brands per scenario (see [Scenarios](./scenarios.md#overriding-team-names)). A setup screen can too, for one session
+- Names are advisory defaults: operators can still rename teams at session setup
+
+## Core concepts
+
+### Per-team vs. shared state
+
+In independent mode (or a single-team game), each team has its own isolated context: decisions made by one team have no effect on another. Shared-state mode adds two cross-team tools, both declared through the capability's `scope`:
+
+- **Shared capabilities** (`scope: 'shared'`): one value for all teams, computed from every team's data by an aggregate engine and distributed back to every team
+- **Team-readable capabilities** (`scope: 'team-readable'`): each team still writes only its own copy, but other teams' user interfaces can observe every team's value live, without waiting for a tick
+
+A capability with no `scope` (or `scope: 'team'`) stays private to each team.
+
+### Shared capabilities
+
+Mark a capability as shared in `capability.sdk.json`:
+
+```json
+{
+    "definition": {
+        "scope": "shared",
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "AverageMarketPrice": { "type": "number", "default": 0 },
+                "PriceChange": { "type": "number", "default": 0 }
+            },
+            "required": ["AverageMarketPrice", "PriceChange"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+Earlier SDK versions used a boolean `"shared": true` flag; it has been removed. A capability that still declares it fails the build with a message pointing at `"scope": "shared"`.
+
+**Only put genuinely session-wide values in a shared capability.** A shared capability holds exactly one value for the whole session, so a per-team figure cannot live in one, even when an aggregate engine computes it from every team's data. `AverageMarketPrice` is session-wide, so it belongs here; each team's `MarketShare` is not, so it belongs in a separate default-scope capability the aggregate engine writes per team (see [Aggregate engines](#aggregate-engines) below). Splitting a capability along its actual scope is the fix whenever you find yourself wanting to write different values per team to the same shared identifier.
+
+**Rules:**
+
+- Shared capabilities have exactly two writers: **an aggregate engine** and **session UIs** that declare the capability in `writes` (see below)
+- Regular `Run` functions may read shared capabilities but must not change them
+- The SDK enforces this at runtime: a regular engine that modifies a shared capability throws an error
+- The build also validates this statically: a non-aggregate engine with `writes` to a shared capability fails `pnpm run sdk build`, as does a game UI declaring such a write
+- A team-addressed context update (a game UI's `setData`, `patch --team N`) that would change a shared capability is rejected by the dev server in multi-team games, because a per-team value for shared scope cannot be represented. Echoing the current shared value back (as full-context senders do) is fine
+
+### Facilitator-writable shared capabilities
+
+Games with live facilitator dials (prices, thresholds, toggles) need session-wide values that can change at runtime. Settings cannot hold them, because they are fixed when play starts. Instead, declare a capability (here `dials`) with `scope: 'shared'` and add it to the session UI's `writes`:
+
+```json
+{
+    "definition": {
+        "writes": ["dials"]
+    }
+}
+```
+
+The session UI then writes it with the one-argument form of `setData`: no team id, one call, and every team observes the same value:
+
+```typescript
+import type { Settings, SessionData, SharedWrites } from '../types';
+
+const { sessionData, setData } = useSessionUserInterfaceData<SessionData, Settings, SharedWrites>();
+
+setData({ dials: { BasePrice: 12 } }); // session-wide, atomic
+sessionData.shared.context.dials.BasePrice; // read it back once, not off a team
+```
+
+Generated types include `SharedWrites`, covering exactly the shared capabilities the UI declares in `writes`; pass it as the third generic to type the call. `TeamWrites`, the rest of `writes`, is the fourth, and types the per-team `setData(teamId, update)` so that naming a shared capability there fails to compile. `SharedContext` covers every shared capability the UI declares, reads as well as writes, and is what `sessionData.shared.context` holds.
+
+Ordering is well defined: a facilitator write that lands while a tick is executing is queued and applied after the tick, so the engine never silently reverts it. The next tick consumes the new value as input. If an aggregate engine recomputes the capability each tick (for example a scripted per-tick pre-load), the engine's value reasserts at the next tick boundary. That is expected: the facilitator's edit holds until then.
+
+In independent-mode games the same write reaches every team in one call, because a shared capability holds one value for the whole session. An engine cannot write a shared capability in a multi-team independent game (the build refuses it), so the facilitator's value stands until they change it.
+
+For headless testing, a [test session](./engine-testing.md#injecting-decisions) makes the same facilitator write with `{ type: 'updateSharedContext', payload }`.
+
+### Team-readable capabilities
+
+Shared capabilities only update at tick time, because an aggregate engine computes them. When teams need to see one another's **pending** decisions live (for example, watching a shared resource pool settle while everyone negotiates), mark the decision capability as team-readable:
+
+```json
+{
+    "definition": {
+        "scope": "team-readable",
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Price": { "type": "number", "default": 10 }
+            },
+            "required": ["Price"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+Then declare the cross-team read on the user interface that wants to observe it, in `ui.sdk.json`:
+
+```json
+{
+    "definition": {
+        "reads": ["decisions"],
+        "crossTeamReads": ["decisions"],
+        "writes": ["decisions"]
+    }
+}
+```
+
+In the UI, read every team's live value with the `useUserInterfaceCrossTeamData` hook:
+
+```typescript
+import { useUserInterfaceCrossTeamData } from '@seriousgaming/sdk/ui';
+
+import type { CrossTeamContext } from '../types';
+
+function PoolGauge() {
+    const teams = useUserInterfaceCrossTeamData<CrossTeamContext>();
+    // [{ teamId: 'team-1', index: 0, name: 'Acme', context: { decisions: { Price: 12 } } }, ...]
+    const total = teams.reduce((sum, team) => sum + team.context.decisions.Price, 0);
+    return <div>Combined: {total}</div>;
+}
+```
+
+The hook takes no capability identifier: each entry's `context` carries exactly the capabilities this surface listed in `crossTeamReads`. `CrossTeamContext` is generated beside `Context` from those declarations, so pass it as the type argument and read fields off it: naming a capability left out of `crossTeamReads` is then a compile error rather than a result carrying your own team and nobody else. The array contains every team including your own (identifiable by `teamId`), and updates within about a second of any team calling `setData`, without a tick.
+
+**Rules:**
+
+- Cross-team observation is read-only: each team still writes only its own copy, so there is no write contention
+- Cross-team reads are only valid on user interfaces, and only against capabilities with `scope: 'team-readable'`; anything else fails the build
+- Team-readable capabilities require `teams.mode: 'shared-state'`; using one in an independent-mode game fails the build
+- Observed values are pending state: they can change again before the tick consumes them, so treat them as live negotiation data, not committed results
+- Keep private data private by splitting capabilities: put publicly observable decisions in a team-readable capability and everything else in a default-scope one
+- To review the cross-team picture of an earlier tick, `getPastState({ fromTick: tick, teams: 'all' })` returns the same per-team entries as they stood at a committed past tick, each carrying the tick it came from. It is the historical counterpart of `useUserInterfaceCrossTeamData` (see [Review a past day](../recipes/review-a-past-day.md))
+- For teams that transact with each other rather than merely observe, see [Negotiate across teams](../recipes/negotiate-across-teams.md). A game UI cannot write another team's state, so a mutual exchange is published as intent by each side and settled authoritatively by an aggregate engine
+
+#### Choosing between team-readable and shared
+
+The two scopes look like alternative ways to show one team something about the others, and they cost very different amounts as a session grows.
+
+A cross-team read is delivered as one entry per team, to every participant's screen, every time any team writes it. So its cost rises with team count, with participant count, and with how often people are typing, all at the same time. Six teams in a workshop will never notice. A hundred teams will.
+
+A `shared` capability is one value for the whole session, however many teams there are. Its cost does not change with cohort size at all.
+
+Most cross-team screens want a summary rather than a roll call: a ranking, a market price, an average, a distribution, or a count of who has submitted. Every one of those an aggregate engine can compute into a shared capability, and a game written that way runs the same in a hall as in a room.
+
+Reach for `team-readable` when the screen genuinely needs each team's own value attributed to that team, live, before the tick consumes it. That is the thing no aggregate can reconstruct, and it is worth paying for. Where either would work, prefer `shared`.
+
+### Aggregate engines
+
+An aggregate engine runs once across all teams at both init and tick time, receiving every team's context simultaneously. It computes shared outputs and updates each team's individual context.
+
+**An engine is aggregate because of what its logic exports.** Export `InitAggregate` and `RunAggregate` and it is one; there is no flag to set, and nothing to keep in step with the code. The build reads the exports and records what it found in the package it produces. A per-team `Init` and `Run` are both optional: `Init` runs per team before `InitAggregate`, and `Run` per team before `RunAggregate`.
+
+Exporting one of `InitAggregate` / `RunAggregate` without the other fails the build, naming the one that is missing: an aggregate engine runs across every team at both initialisation and tick time, so it needs both.
+
+The bundle itself carries only the capabilities it reads and writes, and the settings it reads:
+
+```json
+{
+    "definition": {
+        "reads": ["decisions"],
+        "writes": ["market", "marketshare"]
+    },
+    "logic": {
+        "directory": ".",
+        "entrypoint": "logic.ts"
+    },
+    "rootDirectory": "."
+}
+```
+
+Note the two `writes`, one per scope: the shared `market` for the session-wide average, and the default-scope `marketshare` for each team's own share. One aggregate engine routinely writes both.
+
+`sdk new engine --aggregate` scaffolds logic with the three exports already in place, so a freshly created aggregate engine builds without changes.
+
+## The aggregate functions
+
+Implement all required functions in your engine's `logic.ts`:
+
+```typescript
+import {
+    InitializationFunction,
+    InitAggregateFunction,
+    RunAggregateFunction,
+} from '@seriousgaming/sdk';
+import type { Context, Settings, SharedContext, TeamContext } from './types';
+
+// Per-team init: set this team's own default values
+export const Init: InitializationFunction<Context, Settings> = async ({ context }) => {
+    return {
+        capabilities: {
+            ...context,
+            marketshare: {
+                ...context.marketshare,
+                MarketShare: 0,
+            },
+        },
+    };
+};
+
+// Aggregate init: runs once with all teams' initial contexts
+export const InitAggregate: InitAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    teams,
+}) => {
+    const equalShare = 1 / teams.length;
+    return {
+        // The session-wide value goes in the shared slice...
+        shared: { capabilities: { market: { AverageMarketPrice: 0, PriceChange: 0 } } },
+        // ...and the per-team value in each team's own context
+        teams: teams.map((t) => ({
+            capabilities: {
+                ...t.context,
+                marketshare: {
+                    ...t.context.marketshare,
+                    MarketShare: equalShare,
+                },
+            },
+        })),
+    };
+};
+
+// Aggregate tick: runs once with all teams' data
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    shared,
+    teams,
+}) => {
+    // teams is an array, sorted by index: [{ teamId, index, context }, ...]
+    // Each team's context carries team scope only; the shared store arrives once, in shared
+    const prices = teams.map((t) => t.context.decisions.Price);
+    const avgPrice = prices.reduce((sum, p) => sum + p, 0) / prices.length;
+    const previousAverage = shared.context.market.AverageMarketPrice;
+
+    return {
+        // shared: one value for the session, written to the shared store
+        shared: {
+            capabilities: {
+                market: {
+                    AverageMarketPrice: avgPrice,
+                    PriceChange: avgPrice - previousAverage,
+                },
+            },
+        },
+        // teams: updated capabilities per team (same order as input)
+        teams: teams.map((t) => {
+            const myPrice = t.context.decisions.Price;
+            const marketShare =
+                avgPrice > 0 ? (avgPrice - myPrice + 1) / avgPrice : 1 / teams.length;
+
+            return {
+                capabilities: {
+                    ...t.context,
+                    marketshare: {
+                        ...t.context.marketshare,
+                        MarketShare: Math.max(0, marketShare),
+                    },
+                },
+            };
+        }),
+    };
+};
+```
+
+### Arguments
+
+Both `InitAggregate` and `RunAggregate` receive `{ shared, teams, settings, meta, participants, callbacks }`:
+
+| Field          | Type                                                        | Description                                                                                                                 |
+| -------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `shared`       | `{ context: SharedContext }`                                | The session's shared store, once: only the shared capabilities the engine declares in `reads` or `writes`                   |
+| `teams`        | `{ teamId: string; index: number; context: TeamContext }[]` | Every team, sorted by index. Each `context` carries that team's own capabilities only, never the shared ones                |
+| `participants` | `readonly Participant[]`                                    | The participants of every team in `teams`, by team and then join order, taken when the operation started. Group by `teamId` |
+
+The generated `types.ts` exports `TeamContext` and `SharedContext` beside `Context`: each is a `Pick` of `Context` by scope (`SharedContext` is `Record<string, never>` when the engine declares no shared capability). `Context` is still the composed view `Init` and a per-team `Run` receive, with shared values included.
+
+Read a shared value from `shared.context`, never off a team. Reading it off `teams[0]` has nothing to read in a session with no teams, and at a hundred teams hands you a hundred copies of one value.
+
+### Return value
+
+Both `InitAggregate` and `RunAggregate` return the same shape:
+
+| Field    | Type                                                 | Description                                                                                                             |
+| -------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `shared` | `{ capabilities: Partial<SharedContext>, deletes? }` | Shared capability values, field-merged over the shared store, so every team observes them                               |
+| `teams`  | `{ capabilities: TeamContext, deletes? }[]`          | Updated capabilities for each team, in the same order as the input `teams` array, shaped like `Run` but team scope only |
+
+Either level may carry `deletes`, paths removed after its `capabilities` fold (see [Removing a key](./engine.md#removing-a-key)). `shared.deletes` may name only shared capabilities, and a `teams` entry's only team ones.
+
+Every key in `shared.capabilities` must be a `scope: 'shared'` capability identifier: anything else fails the init or tick with an error naming the engine and the capability. Shared capabilities live in one session-wide store, and the `shared` slice is the only way an aggregate engine writes it; every team's composed view re-reads the store, so all teams observe the new value.
+
+**A shared capability inside a `teams` entry fails the init or tick**, even when every team carries the same value:
+
+```
+Engine "engine" returned shared capability "market" in teams[0] of RunAggregate. Return shared capabilities once, under "shared": { capabilities: { market: ... } }.
+```
+
+A `teams` entry is a per-team patch, and a capability with one value per session has no per-team value to patch. Earlier SDK versions adopted a value every team carried identically; that channel is gone. Spreading `...t.context` into a `teams` entry is safe, because `t.context` no longer carries shared capabilities. If you want a different figure per team, give it its own default-scope capability.
+
+In independent-mode games, the engine cannot write shared capabilities at all (it fails game validation): with teams ticking on their own clocks there is no coherent writer order. Shared capabilities are facilitator-only there, written session-wide from a session UI, and survive per-team undo and reset.
+
+### Execution order
+
+**Initialisation**: when the executor processes an aggregate engine during `init`:
+
+1. **Per-team `Init`** (optional): runs once per team, as on a regular engine. Without one, each team starts from the capability defaults
+2. **`InitAggregate`**: runs once with all teams' post-init contexts (team scope only) and the shared store, as `shared`. May write to shared capabilities
+3. **Result applied**: the `capabilities` of each entry in `result.teams` merge into the corresponding team's context, then the result's shared values land on the session-wide store and every team's view re-composes from it
+
+**Tick**: when the game's engine is aggregate:
+
+1. **Per-team `Run`** (optional): runs once per team. May read shared capabilities but must not write to them
+2. **`RunAggregate`**: runs once with all teams' contexts (team scope only) and the shared store, as `shared`. May write to shared capabilities
+3. **Result applied**: the `capabilities` of each entry in `result.teams` merge into the corresponding team's context, then the result's shared values land on the session-wide store and every team's view re-composes from it
+
+### Keying off the team index
+
+Each entry in the `teams` array is `{ teamId, index, context }`, and the array is always sorted by `index`. The `index` is the team's session-stable, zero-based identity (see [Naming teams](#naming-teams)), so it is the right key for roster-style logic: per-team economics, targeted documents, or any configuration that must follow a team across its life. Reaching for the array position instead breaks the moment a team is removed and the array shortens, whereas the index does not move.
+
+```typescript
+import { RunAggregateFunction } from '@seriousgaming/sdk';
+import type { Settings, SharedContext, TeamContext } from './types';
+
+// Per-team starting capital, indexed by the stable team index
+const ROSTER = [
+    { startingCapital: 100_000 },
+    { startingCapital: 80_000 },
+    { startingCapital: 120_000 },
+];
+
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    teams,
+}) => {
+    return {
+        shared: { capabilities: {} },
+        teams: teams.map((t) => {
+            const slot = ROSTER[t.index] ?? { startingCapital: 100_000 };
+            return {
+                capabilities: {
+                    ...t.context,
+                    finance: {
+                        ...t.context.finance,
+                        StartingCapital: slot.startingCapital,
+                    },
+                },
+            };
+        }),
+    };
+};
+```
+
+In a single-team game the index is 0. In independent mode the single-element `teams` array still carries that team's real index, so the same lookup works in every mode.
+
+## Testing in the dev server
+
+Start the dev server with multiple teams:
+
+```bash
+pnpm run sdk dev --teams 3
+```
+
+**Auto-derived team count**: If you don't pass `--teams`, the dev server reads `teams.min` from your game. For example, if your game declares `"teams": { "min": 3 }`, running `pnpm run sdk dev` will automatically start with 3 teams. The `--teams` flag always overrides this, but it must sit within the game's bounds: a count below `min` or above `max` is refused, not adjusted.
+
+Each team gets its own game UI URL, and the console at `/` is the session UI:
+
+| View        | URL                                   |
+| ----------- | ------------------------------------- |
+| Team 1 game | http://localhost:3000/team/1/player/1 |
+| Team 2 game | http://localhost:3000/team/2/player/1 |
+| Team 3 game | http://localhost:3000/team/3/player/1 |
+| Console     | http://localhost:3000/                |
+
+**Participants per team**: Every team starts with one participant, or the game's `perTeam.minParticipants`, so each player URL has somebody behind it. Pass `--participants` to `sdk dev` or `sdk init` to choose: `--participants 4` for a full table everywhere, `--participants 0` to see what your game does before anybody joins, or one count per team such as `--participants 2,0,1`. A player URL for a seat nobody holds is refused rather than mounted, and a team's join page says it is empty. `sdk team add --participants N` seeds a team added later.
+
+**Teams in the dev drawer**: The console's dev drawer (press the backtick key) lists every team on its Session tab with its current tick, per-team Tick, Undo and Reset, and 'Add participant'. 'Add team' adds a team at runtime, up to the game's `teams.max`. A team can be removed down to a single team: `teams.min` applies only when the session is created and when play starts.
+
+Runtime team changes preserve the stable team index:
+
+- Removing a team does not renumber the others. Their ids, URLs, and participants stay put, and the `team-N` sequence keeps a gap where the removed team was. The next added team refills the lowest unused index as a new team with the default name, not the removed one back
+- In shared-state games, adding a team is only allowed before the first tick. Adding one then re-initialises the session so `InitAggregate` sees every team. After the first tick the request is rejected, because the aggregate state has already been computed without the new team
+- In shared-state games, a team cannot be removed at all, before the first tick or after, and in independent mode only an empty team can be
+
+**The session UI**: The console (`/`) renders the game's session UI, which receives the state of **all** teams simultaneously, making it the right place to test leaderboards, cross-team views, or facilitator overviews.
+
+**Per-team ticks in independent mode**: When the game declares `"mode": "independent"`, each team ticks independently. A tick requested from a team's game UI (via the game's own `requestTick` control, or that team's Tick in the dev drawer) advances only that team, and the dev drawer shows each team's tick. Use each team's game UI to advance teams on their own schedule.
+
+**Synced ticks in shared-state mode**: When the game declares `"shared-state"` mode, all teams advance on the same tick.
+
+**Context updates**: When a game UI writes a decision (via `setData`), it updates only that team's context.
+
+## Testing with CLI game commands
+
+> **Multi-team is set once, at init.** You pass `--teams N` to `init` and nothing else. `tick` and `view` read the team count from the running session, so they advance and display every team automatically, with no per-command flag. `tick` accepts `--teams N` only on the first run (when it initialises the game for you), and `view` has no `--teams` at all; `--team N` only narrows an existing multi-team game to one team, and is refused on a session with one team. This is the headless path for verifying shared-state aggregate behaviour without the dev server.
+
+### Initialise with multiple teams
+
+```bash
+pnpm run sdk init --teams 3
+```
+
+This starts the session with three teams, and every later command detects it automatically. Without `--teams`, the game starts with its `teams.min` teams (one when it declares no minimum). Re-run `init` to change the count (this resets to tick 0).
+
+### Set decisions per-team
+
+Use `patch` to set each team's decisions before ticking. In multi-team mode, `--team` is required:
+
+```bash
+pnpm run sdk patch \
+  '[{"op":"replace","path":"/decisions/Price","value":8}]' -- --team 1
+pnpm run sdk patch \
+  '[{"op":"replace","path":"/decisions/Price","value":6}]' -- --team 2
+pnpm run sdk patch \
+  '[{"op":"replace","path":"/decisions/Price","value":4}]' -- --team 3
+```
+
+### Advance all teams (tick)
+
+```bash
+pnpm run sdk tick
+```
+
+Without `--team`, every team advances. With `--team N` (1-based), what ticks depends on the mode: in independent mode only team N advances, as its per-team Tick in the dev drawer does; in shared-state mode every team still advances together, because they share one tick.
+
+`--team N` also scopes a `--patch` to that team before the tick fires:
+
+```bash
+# Team 2 changes price, then team 2 ticks (independent) or every team ticks (shared-state)
+pnpm run sdk tick \
+  -- --team 2 --patch '[{"op":"replace","path":"/decisions/Price","value":5}]'
+```
+
+### View state
+
+```bash
+# All teams
+pnpm run sdk view
+
+# Single team
+pnpm run sdk view --team 2
+```
+
+## Full workflow example
+
+Put together, the pieces on this page make a complete multi-team game: a per-team `decisions` capability holding each team's `Price`, a shared `market` capability, a per-team `marketshare`, and the aggregate engine above. From the package root, run it end to end:
+
+```bash
+# Initialise 3 teams
+pnpm run sdk init --teams 3
+
+# Each team sets a different price
+pnpm run sdk patch \
+  '[{"op":"replace","path":"/decisions/Price","value":8}]' -- --team 1
+pnpm run sdk patch \
+  '[{"op":"replace","path":"/decisions/Price","value":6}]' -- --team 2
+pnpm run sdk patch \
+  '[{"op":"replace","path":"/decisions/Price","value":4}]' -- --team 3
+
+# Run tick: market engine aggregates all prices, computes MarketShare per team
+pnpm run sdk tick
+
+# View results: AverageMarketPrice is shared, MarketShare differs per team
+pnpm run sdk view
+```
+
+To play it in the browser with five teams:
+
+```bash
+pnpm run sdk dev --teams 5
+```
+
+## Single-team and independent-mode compatibility
+
+Without `--teams` (or `--teams 1`), everything works exactly as before. An aggregate engine receives a single-element `teams` array with `teamId: 'team-1'`, so it works correctly without any code changes. `shared` is passed on every call, in either mode and with any number of teams.
+
+The same principle applies in **independent mode** with multiple teams: an aggregate engine receives a single-element `teams` array for each team, containing only that team. The engine code is identical: the only difference is whether the `teams` array contains one team or all teams:
+
+```
+Independent mode:  RunAggregate({ shared, teams: [{ teamId: "team-1", index: 0, context: ctx1 }] })   // one team
+                   RunAggregate({ shared, teams: [{ teamId: "team-2", index: 1, context: ctx2 }] })   // separate call
+
+Shared-state mode: RunAggregate({ shared, teams: [{ teamId: "team-1", index: 0, context: ctx1 },
+                                                  { teamId: "team-2", index: 1, context: ctx2 }] })   // single call
+```
+
+## Next steps
+
+- [Creating engines](./engine.md) - Implement engine logic
+- [Creating capabilities](./capabilities.md) - Define shared and per-team variables
+- [Drive a game from the CLI](../cli-simulation-testing.md) - Play a multi-team session from the terminal with `--team` and `--teams`