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

package/dist/docs/recipes/index.md

@@ -0,0 +1,86 @@
+# Recipes
+
+Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong. For the full reference on a resource type, see the [guides](../guides/index.md).
+
+## Getting started
+
+- [Start a game from an empty package](start-from-an-empty-package.md): build a game from nothing, with a capability, an engine, and a game UI
+- [Create an engine](create-engine.md): an engine that reads one capability and writes another
+- [Create a capability](create-capability.md): a new slice of the game's state
+- [Create settings](create-settings.md): a read-only parameter logic and screens read, which scenarios and facilitators can change before play
+- [Shape your game](create-game.md): set ticks, teams, and locales
+
+## Scenarios
+
+- [Create a scenario](create-scenario.md): a variant of the game with its own settings and assets
+- [Share assets across scenarios](share-assets-across-scenarios.md): reference one file from several scenarios with a `shared:` reference
+
+## Facilitation
+
+- [Create a facilitator guide](create-guide.md): markdown facilitation content shown on the facilitator's page
+- [Create a presentation](create-presentation.md): the facilitator's slide deck, live with the session's results and exportable to PDF and PowerPoint
+
+## User interfaces
+
+- [Create a user interface](create-user-interface.md): a game UI that shows the game's state
+- [Design state for concurrent writes](design-state-for-concurrent-writes.md): shape capabilities and `setData` calls so participants writing at once never overwrite each other
+- [Share logic between an engine and a UI](share-logic-between-engine-and-ui.md): one calculation in one file, so a live preview cannot drift from the engine's result
+- [Upload and display files](upload-and-display-files.md): let participants upload files and show them in results
+- [Create a session UI](create-session-ui.md): a facilitator screen that shows every team and controls the session
+- [Create a waiting room UI](create-waiting-room-ui.md): replace the host's built-in holding screen with your own
+- [Create a setup screen](create-setup.md): a short form at session creation that sets this session's settings
+- [Create a scenario editor](create-scenario-editor.md): a screen for building new scenarios for a released game
+- [Adapt a UI for observers](adapt-ui-for-observers.md): tell a facilitator observing a team from a participant with `useUserInterfaceViewerRole`
+- [Remember a viewer's choice](remember-a-viewers-choice.md): keep a tab, a collapsed panel or a sort order across a reload with `useViewerStorage`, keyed by session, surface and viewer
+- [Adapt a game for walkthroughs](adapt-a-game-for-walkthroughs.md): use `runKind` to fill in what a solo demonstration lacks and keep outward effects out of it
+
+## Multi-team games
+
+- [Observe other teams' state live](observe-other-teams-state.md): show one team's pending decisions on other teams' screens with team-readable capabilities
+- [Negotiate across teams](negotiate-across-teams.md): let two teams propose, agree, and settle an exchange at tick time
+- [Show all teams' participants in a UI](show-all-teams-participants.md): a directory of who is on each team, with `getAllTeamsParticipants`
+- [Review a past day in a UI](review-a-past-day.md): scrub back through a team's tick history with `getPastState`
+
+The full reference is the [Multi-team games](../guides/multi-team-games.md) guide.
+
+## Progression
+
+- [Use requestTick in a UI](use-request-tick.md): advance the game from a button in your UI
+- [Use requestPlay in a setup screen](use-request-play.md): leave the configuration step from a button in your setup screen
+- [Create a tick controller](create-tick-controller.md): automatic tick timing driven by the game's logic
+- [End a game when a condition is met](end-game-on-condition.md): stop play when a goal is reached rather than after a fixed number of ticks
+
+## Lifecycle hooks
+
+- [Create a hook](create-hook.md): react to a lifecycle signal, such as a participant joining a team
+- [Test a multi-role game in the dev server](test-a-multi-role-game.md): add, name, and open several participants per team to play through a role-based interaction
+
+## Validation
+
+- [Create a validator](create-validator.md): reject UI mutations that break the game's rules
+
+## Runtime callbacks
+
+- [Declare the runtime callbacks a resource uses](declare-api-uses.md): tell the SDK which callbacks, such as `generateText` and `extractText`, a resource may call
+
+## Endpoints
+
+- [Create an endpoint](create-endpoint.md): a server-side handler UIs call by identifier
+- [Call an endpoint from a UI](call-endpoint-from-ui.md): declare an endpoint and call it with a typed callback
+- [Make an endpoint callable from outside the game](make-an-endpoint-external.md): publish an endpoint to a facilitator's AI agent or a platform API
+- [Act on the session from an endpoint](act-on-the-session-from-an-endpoint.md): close the waiting room, advance a tick and more, in one call
+- [Take a file in an endpoint](take-a-file-in-an-endpoint.md): accept an image or PDF from a UI, a script or an AI agent
+
+## Deployment and distribution
+
+- [Distribute a built package](distribute-package.md): bundle `dist/` into an uploadable zip archive
+- [Publish a package to the Serious Gaming platform](publish-a-package.md): build, bundle, and upload in one command
+- [Check a package from a script](check-a-package-from-a-script.md): validate and tick from CI or an AI agent, branching on exit codes and reading each diagnostic's file and pointer
+
+## Testing and verification
+
+- [Drive a game from the CLI](../cli-simulation-testing.md): configure, tick, patch, and read a session from the terminal
+- [Test a user interface](test-user-interface.md): write and run React component tests
+- [Test UIs end to end with Playwright](e2e-testing.md): browser tests against the dev server
+- [Test a whole game in-process](test-with-engine.md): whole games with `createTestSession`, for rules, flow, hooks, validators and completion
+- [Fix duplicate package errors in a UI](fix-duplicate-packages.md): resolve 'Invalid hook call' errors caused by two copies of React

package/dist/docs/recipes/make-an-endpoint-external.md

@@ -0,0 +1,101 @@
+# Make an endpoint callable from outside the game
+
+**Keywords:** external endpoint, visibility, agent callable endpoint, AI agent, facilitator agent, expose endpoint to AI, agent tool, MCP endpoint, platform API, integration
+
+Publish one of your endpoints to callers outside the game, such as a facilitator's AI agent or a platform API, so it can be invoked by asking or by another system rather than by clicking.
+
+## Prerequisites
+
+- An endpoint that already works (see [Create an endpoint](create-endpoint.md))
+- A clear idea of which request from outside the game it answers
+
+## Steps
+
+1. Set `visibility` to `external` and add a description in the endpoint's bundle, `endpoints/setprice/endpoint.sdk.json`:
+
+    ```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"]
+        }
+    }
+    ```
+
+    The description is required once `visibility` is `external`, and the build fails without one. It is what an outside caller, an AI agent most of all, reads to decide whether to call this endpoint rather than another, so say **when to reach for it**, not just what it does.
+
+    An endpoint is `internal` when `visibility` is absent, and a caller outside the game is refused it. Which outside callers may use an external endpoint, and how they sign in, is up to the platform.
+
+2. Set the scope to match what the call acts on:
+
+    - `"scope": "team"` for anything about one team, such as setting its decision. The platform resolves which team the facilitator meant and passes it to your handler on `team`, with its id, index and display name
+    - `"scope": "session"` for anything session-wide
+
+    Do not add a team to your `requestSchema`. A team the model types is a team the model can invent.
+
+3. Put the bounds in the request schema, not only in the description:
+
+    ```json
+    {
+        "requestSchema": {
+            "type": "object",
+            "properties": {
+                "price": { "type": "number", "minimum": 0, "maximum": 50 }
+            },
+            "required": ["price"],
+            "additionalProperties": false
+        }
+    }
+    ```
+
+    The runtime refuses a request outside this before your handler runs. The description stops the model making the call; the schema stops the call landing.
+
+    An external endpoint's request must be an object at the top, because an outside caller passes named arguments. One that takes no input declares `{ "type": "object", "properties": {}, "additionalProperties": false }`.
+
+4. Check the request in the handler for anything the schema cannot express:
+
+    ```typescript
+    export const Handle: Handler = async ({ request, context }) => {
+        if (!Number.isFinite(request.price)) {
+            throw new Error('A price must be a finite number');
+        }
+        return {
+            response: { previous: context.price.Price, current: request.price },
+            capabilities: { price: { ...context.price, Price: request.price } },
+        };
+    };
+    ```
+
+    An endpoint's write is not put to your validators, whoever called it, so the handler is where a rule about the request itself belongs.
+
+5. Read it back as an outside caller will receive it:
+
+    ```bash
+    pnpm run sdk endpoint list --external
+    ```
+
+## Verify
+
+- `pnpm run sdk endpoint list --external` shows the endpoint, its scope, whether it writes, and its description
+- `pnpm run sdk endpoint call setprice --external --team 1 --request '{"price": 3.53}'` returns the expected response, called the way an outside caller calls it
+- `pnpm run sdk view` shows the change on the right team, and no others
+- A request outside the schema is refused, and leaves the board untouched
+
+## Troubleshooting
+
+- _'is external, so it must carry a description'_: Add `description` to the endpoint's definition
+- _'is external, so its requestSchema must declare `"type": "object"`'_ (`EXTERNAL_REQUEST_NOT_OBJECT`): Wrap the request in an object with a named property for each value, such as `{ "price": 3.53 }` rather than `3.53`
+- _'is internal, so a caller outside the game cannot call it'_: Set `"visibility": "external"` on the endpoint
+- _'`agentCallable` has been replaced by `visibility`'_: Replace `"agentCallable": true` with `"visibility": "external"`
+- _'which is team-scoped, but this surface has no team of its own'_: A session UI, setup screen, or scenario editor also lists this endpoint; give it `"scope": "session"` or stop listing it there
+- _Two endpoints get confused for each other_: Run `endpoint list --external` and read the descriptions together. If they do not say when to pick one over the other, the agent has nothing to go on
+- _No user interface requests it_: That warning is suppressed for external endpoints, whose caller no bundle names. If you see it, `visibility` is not `external`
+
+## Related
+
+- [Structuring a game for AI facilitation](../guides/ai-facilitation.md)
+- [Create an endpoint](create-endpoint.md)
+- [Endpoints (concept)](../guides/endpoints.md)

package/dist/docs/recipes/negotiate-across-teams.md

@@ -0,0 +1,164 @@
+# Negotiate across teams
+
+Build a game where two teams propose, agree, and settle an exchange with each other, using a team-readable ledger and authoritative settlement at tick time.
+
+**Keywords:** negotiation, trade, exchange, barter, cross-team transaction, two teams agree, atomic settlement, proposal, offer, accept, counterparty, ledger, transfer resources between teams
+
+## What you'll build
+
+A game UI writes only its own team's state, so no UI can move a resource from one team to another: a UI is untrusted, and a mutual exchange needs one authority. Every negotiation game therefore has the same shape: **teams publish intent, the engine settles it.** Each team publishes proposals and acceptances in a `team-readable` capability, and an aggregate engine pairs them and moves both sides at tick time. For who may write each capability scope, see [Choosing between team-readable and shared](../guides/multi-team-games.md#choosing-between-team-readable-and-shared).
+
+## Prerequisites
+
+- A shared-state game (`teams.mode: 'shared-state'`): see [Multi-team games](../guides/multi-team-games.md)
+- Familiarity with [Observe other teams' state](observe-other-teams-state.md)
+
+## Steps
+
+### 1. Model proposals as a team-readable ledger
+
+Each team writes only its own copy; counterparties read across. Key by proposal id, never an array (see [Design state for concurrent writes](design-state-for-concurrent-writes.md)):
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "trades",
+    "scope": "team-readable",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Proposed": {
+          "type": "object",
+          "description": "Offers this team has made, keyed by proposal id",
+          "default": {},
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "toTeamId": { "type": "string" },
+              "give": { "type": "number" },
+              "take": { "type": "number" }
+            },
+            "required": ["toTeamId", "give", "take"],
+            "additionalProperties": false
+          }
+        },
+        "Accepted": {
+          "type": "object",
+          "description": "Proposal ids from other teams that this team has accepted",
+          "default": {},
+          "additionalProperties": { "type": "boolean" }
+        }
+      },
+      "required": ["Proposed", "Accepted"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+Two one-sided declarations, each written by its own team, are what stands in for a two-party handshake. Agreement is the **conjunction**: a proposal by A that appears in B's `Accepted`.
+
+### 2. Propose and accept from the UI
+
+Each side writes only its own capability, so both calls are ordinary `setData`:
+
+```tsx
+const ownTeam = useUserInterfaceOwnTeam();
+const { setData } = useUserInterfaceData<Context, Settings>();
+const counterparties = useUserInterfaceCrossTeamData<{ trades: Trades }>();
+
+// Team A proposes. The id must be stable and collision-free across teams.
+const propose = (toTeamId: string, give: number, take: number) => {
+    const id = `${ownTeam?.teamId}-${Date.now()}`;
+    void setData({ trades: { Proposed: { [id]: { toTeamId, give, take } } } });
+};
+
+// Team B accepts by id. It never touches team A's state.
+const accept = (proposalId: string) => {
+    void setData({ trades: { Accepted: { [proposalId]: true } } });
+};
+```
+
+`setData` deep-merges, so writing one key under `Proposed` leaves siblings alone and two participants on the same team do not clobber each other.
+
+### 3. Settle authoritatively in an aggregate engine
+
+This is the only place the exchange actually happens. The engine (with `trades` and a `holdings` capability in its `reads` and `writes`) sees every team at once, so it can pair proposals with acceptances and move both sides atomically:
+
+```typescript
+// engine/logic.ts
+import { settle } from '../shared/settlement';
+
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    teams,
+}) => {
+    const agreed = settle(
+        teams.map((t) => ({
+            teamId: t.teamId,
+            trades: t.context.trades,
+            holdings: t.context.holdings,
+        }))
+    );
+
+    return {
+        shared: { capabilities: {} },
+        teams: teams.map((t) => ({
+            capabilities: {
+                ...t.context,
+                holdings: agreed.holdingsByTeam[t.teamId],
+                trades: { Proposed: {}, Accepted: {} },
+            },
+        })),
+    };
+};
+```
+
+Rules worth stating explicitly in your settlement function:
+
+- **Only settle a mutually-agreed pair.** A proposal without a matching acceptance is not a trade
+- **Reject what cannot be paid.** Check both sides' holdings before transferring; a trade that would overdraw either party must be dropped, not applied
+- **Make ordering deterministic.** When two agreed trades compete for the same resource, sort by proposal id (or another stable key) before applying, so the same inputs always produce the same result
+
+### 4. Preview the outcome without duplicating the rules
+
+Participants want to see the effect before the tick. Put the settlement calculation in a shared file and import it from both sides, so the preview cannot drift from the scored result:
+
+```tsx
+import { projectHoldings } from '../../shared/settlement';
+
+const preview = projectHoldings(ownHoldings, pendingTradesForMe);
+```
+
+See [Share logic between an engine and a UI](share-logic-between-engine-and-ui.md) for the mechanics and the two constraints on shared files.
+
+### 5. Review past trades
+
+Clearing `Proposed` and `Accepted` in step 3 costs nothing in review: a tick's snapshot is the board the tick was submitted with, so `getPastState` still shows what each team proposed and accepted (see [Review a past day in a UI](review-a-past-day.md)).
+
+## Verify
+
+- Two teams can propose and accept, and neither write is rejected
+- A proposal with no matching acceptance does not settle
+- A trade neither side can pay for does not settle, and leaves both holdings untouched
+- After the tick, both teams' holdings moved by the same amount in opposite directions, and totals across the session are conserved
+- The UI's preview matches the post-tick holdings for the same inputs
+- `getPastState` on the completed tick shows what each team proposed and accepted
+
+## Troubleshooting
+
+| Problem                                                 | Solution                                                                                                                                                        |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A UI write to another team's capability is rejected     | Expected: teams publish intent about themselves, and only an engine settles. See [What you'll build](#what-youll-build)                                         |
+| Setting `scope: 'shared'` on the ledger fails the build | A game UI cannot write a shared capability. The ledger must be `team-readable`                                                                                  |
+| `useUserInterfaceCrossTeamData` returns an empty array  | The UI must list the capability in `crossTeamReads`, and the game must be `teams.mode: 'shared-state'`                                                          |
+| A trade settles twice                                   | Clear `Proposed` and `Accepted` in the same tick that settles them                                                                                              |
+| Both teams' totals drift                                | You are applying one side of a pair. Transfer as a single operation over both parties, and assert conservation in an [engine test](../guides/engine-testing.md) |
+| The preview disagrees with the result                   | The two are not running the same code. See step 4                                                                                                               |
+
+## Related
+
+- [Share logic between an engine and a UI](share-logic-between-engine-and-ui.md)
+- [Observe other teams' state](observe-other-teams-state.md)
+- [Design state for concurrent writes](design-state-for-concurrent-writes.md)
+- [Review a past day](review-a-past-day.md)
+- [Multi-team games](../guides/multi-team-games.md)

package/dist/docs/recipes/observe-other-teams-state.md

@@ -0,0 +1,119 @@
+# Observe other teams' state live
+
+**Keywords:** cross-team, crossTeamReads, team-readable, observe other teams, live decisions, pending decisions, shared pool, useUserInterfaceCrossTeamData, getPastState, CrossTeamContext, capability scope, useUserInterfaceOwnTeam, own team, which team am I
+
+Let one team's user interface watch another team's pending decisions live, without waiting for a tick. Typical use: a shared resource pool gauge that settles while teams negotiate.
+
+## Prerequisites
+
+- A multi-team game with `teams.mode: 'shared-state'` in `seriousgaming.sdk.json`
+- A capability holding the decisions teams should be able to see
+
+## Steps
+
+1. Set the capability's scope to `team-readable` in `capability.sdk.json`:
+
+    ```json
+    {
+        "definition": {
+            "scope": "team-readable",
+            "variablesSchema": {
+                "type": "object",
+                "properties": {
+                    "DonateToPool": { "type": "number", "default": 0 }
+                },
+                "required": ["DonateToPool"],
+                "additionalProperties": false
+            }
+        }
+    }
+    ```
+
+2. Declare the cross-team read on the observing user interface in `ui.sdk.json`:
+
+    ```json
+    {
+        "definition": {
+            "reads": ["decisions"],
+            "crossTeamReads": ["decisions"],
+            "writes": ["decisions"]
+        }
+    }
+    ```
+
+3. Read every team's live value in the UI with `useUserInterfaceCrossTeamData`:
+
+    ```typescript
+    import { useUserInterfaceCrossTeamData } from '@seriousgaming/sdk/ui';
+
+    // Generated beside Context, and narrower: it carries exactly the
+    // capabilities this surface listed in `crossTeamReads`.
+    import type { CrossTeamContext } from '../types';
+
+    function PoolGauge() {
+        const teams = useUserInterfaceCrossTeamData<CrossTeamContext>();
+        const pool = teams.reduce((sum, team) => sum + team.context.decisions.DonateToPool, 0);
+        return (
+            <ul>
+                {teams.map((team) => (
+                    <li key={team.teamId}>
+                        {team.name}: {team.context.decisions.DonateToPool}
+                    </li>
+                ))}
+                <li>Pool total: {pool}</li>
+            </ul>
+        );
+    }
+    ```
+
+    The array contains one entry per team, **including your own**. Identify yours with `useUserInterfaceOwnTeam()`, which returns the `TeamInfo` of the team whose surface you are rendering:
+
+    ```typescript
+    import { useUserInterfaceCrossTeamData, useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
+
+    const ownTeam = useUserInterfaceOwnTeam();
+    const teams = useUserInterfaceCrossTeamData<CrossTeamContext>();
+    const others = teams.filter((team) => team.teamId !== ownTeam?.teamId);
+    ```
+
+    **Pass `CrossTeamContext`, not `Context`.** `Context` is every capability the surface reads or writes; `CrossTeamContext` is only the ones it declared `crossTeam`. Reading another team's value of a capability left out of `crossTeamReads` returns your own team's value and nobody else's, which looks exactly like an early session where nobody has written yet. Typed against `CrossTeamContext`, that read is a compile error instead.
+
+    Do not use `useUserInterfaceParticipant()?.teamId` for this. It is `null` when a facilitator observes the surface, so the split silently collapses and every team reads as 'theirs' in the observer view. `useUserInterfaceOwnTeam()` is populated for observers too. `useUserInterfaceTeams()` is a different hook: it lists every team in the session and does not mark which is yours.
+
+4. Regenerate types and rebuild:
+
+    ```bash
+    pnpm run sdk generate
+    pnpm run sdk build
+    ```
+
+## Notes
+
+- Observed values are pending state: they can change again before the tick consumes them
+- Other teams' values are read-only; each team still writes only its own copy
+- Keep private data private by splitting capabilities: only the capability marked `team-readable` is observable
+- A cross-team read is the most expensive thing a screen can declare: one entry per team, delivered to every participant, every time anyone writes. That is free in a workshop and heavy in a large cohort. If the screen shows a summary rather than each team's own value (a ranking, a market price, an average, a count of who has submitted), compute it in `RunAggregate` into a `scope: shared` capability instead, which is one value whatever the team count. See [Choosing between team-readable and shared](../guides/multi-team-games.md#choosing-between-team-readable-and-shared)
+- `useUserInterfaceCrossTeamData` is live only. To review other teams' values at a committed past tick, ask its historical counterpart for every team: `getPastState({ fromTick: tick, teams: 'all' })` (see [Review a past day](review-a-past-day.md)). Entries come back in the same shape the hook returns, plus the tick they were captured at, so one renderer serves both. Mind the timing: a past value is the board that tick was _submitted with_, so it carries each team's decisions for the tick as well as the previous tick's outcomes (see [Reviewing past ticks](../guides/ui.md#reviewing-past-ticks)). If the cross-team fact you want is a single settled outcome rather than each team's raw copy, computing it into a `scope: shared` capability at tick time is often simpler: the shared store is included in every team's own board, so it becomes reviewable without any cross-team declaration at all
+
+## Verify
+
+- Start the dev server with at least two teams: `pnpm run sdk dev --teams 2`
+- Open team 1 and team 2 side by side, change the decision on team 1, and confirm team 2's view updates within about a second, without a tick
+
+## Troubleshooting
+
+- **Build fails with 'a crossTeamReads entry requires scope: team-readable'**: the capability is still default-scoped or shared; set `"scope": "team-readable"` on the capability definition
+- **Build fails with 'lists X in crossTeamReads but does not read it'**: add the same identifier to `reads`. `reads` is what says the capability arrives at all; `crossTeamReads` only says every team's value of it does
+- **Build fails with 'interaction mode is not shared-state'**: team-readable capabilities only work in shared-state games; set `"teams": { "mode": "shared-state" }` at the top level of `seriousgaming.sdk.json`
+- **`crossTeamReads` is rejected as an unknown property**: only the game UI and the waiting room UI carry the field. Engines, endpoints, validators, tick controllers, and session UIs receive cross-team data through an aggregate engine instead
+- **The hook returns an empty array**: check the UI lists the capability in `crossTeamReads`. The hook takes no capability identifier: each entry's `context` carries exactly the capabilities the bundle declared that way, so there is nothing to misspell
+- **`CrossTeamContext` is `Record<string, never>`**: the surface lists nothing in `crossTeamReads`, so there is nothing to observe. Add the capability to `crossTeamReads` and regenerate
+- **A property 'x' does not exist on type 'CrossTeamContext' error**: `x` is readable but is not in `crossTeamReads`, so only your own team's copy would ever arrive. Add the flag if the surface should see every team's, or read it from `data` if it should not
+
+## Related
+
+- [Negotiate across teams](negotiate-across-teams.md): when teams need to transact, not just observe
+- [Share logic between an engine and a UI](share-logic-between-engine-and-ui.md): keep a live preview in step with the settled result
+- [Multi-team games](../guides/multi-team-games.md)
+- [Create a capability](create-capability.md)
+- [Create a user interface](create-user-interface.md)

package/dist/docs/recipes/publish-a-package.md

@@ -0,0 +1,139 @@
+# Publish a package to the Serious Gaming platform
+
+Build, bundle, and upload a package to the Serious Gaming platform in a single command.
+
+**Keywords:** publish, upload, deploy, release, publisher, api key, publishing access, permission, ship
+
+## What you'll build
+
+A repeatable pipeline that takes your working tree from source to a hosted package version. The default flow:
+
+1. `seriousgaming-sdk build` produces `dist/`
+2. `seriousgaming-sdk package bundle` (auto-runs if the zip is missing) produces `dist/<identifier>-<version>.zip`
+3. `seriousgaming-sdk package publish` POSTs the zip to `/api/v0/admin/publishers/<slug>/packages` and prints the resulting `PackageVersionResponse`
+
+Designed so an AI agent can drive the whole sequence from a single prompt.
+
+## Prerequisites
+
+- A built package (`seriousgaming-sdk build` has run at least once)
+- A valid semver string in `package.json` (`version`)
+- A platform account with **publishing access**, and an API key issued from it. Business Simulations grants publishing access: ask your contact there to enable it on your account
+- The slug of the publisher you are uploading under
+- Node 24 or newer, the version the SDK supports
+
+## Steps
+
+### 1. Issue an API key
+
+1. Open the platform and go to your organisation's settings page, then the API keys section
+2. Create a key and give it a descriptive name (like 'CI publish' or '<your machine> local')
+3. Copy the key to your clipboard. It will not be shown again
+
+Keys take the form `sg_<lookupId>_<secret>`. A key acts as the account that created it, so create it from the account Business Simulations gave publishing access; the upload endpoint refuses a key whose account does not have it.
+
+Never paste the key into a command line directly. Put it in a `.env` file (and `.gitignore` that file), export it from your shell profile, or store it in the [global settings file](../guides/global-settings.md) so it stays out of shell history. If you lose the key, revoke it on the same page and create a new one.
+
+### 2. Configure the API key and publisher
+
+Add to `.env` in your package's working directory:
+
+```bash
+SERIOUSGAMING_API_KEY=sg_your_lookup_id_your_secret
+SERIOUSGAMING_PUBLISHER=your-publisher-slug
+```
+
+The publisher slug scopes the upload. The CLI resolves it from (highest priority first) the `--publisher` flag, the `SERIOUSGAMING_PUBLISHER` environment variable, then `platform.defaultPublisher` in your global settings. If none resolves, the command fails rather than guessing. The first upload of a package binds it to that publisher, and later versions must use the same one.
+
+If you publish under one publisher most of the time, set it once in the global settings file so every project picks it up:
+
+```bash
+# Replace the slug with your own; `config set` overwrites any value already there
+pnpm run sdk config set platform.defaultPublisher your-publisher-slug
+```
+
+For a non-production target (dev, staging) also set:
+
+```bash
+SERIOUSGAMING_API_HOST=https://staging.example.com
+```
+
+All values can also be set with shell `export`, or overridden per-invocation with `--api-key`, `--publisher`, and `--host`.
+
+### 3. Bump the version
+
+Production runtimes reject re-uploads of the same identifier and version, so bump before each publish:
+
+```bash
+pnpm run sdk package version patch
+```
+
+### 4. Build and publish
+
+```bash
+pnpm run sdk build
+pnpm run sdk package publish
+```
+
+The publish command auto-runs `package bundle` when the zip is missing, so a fresh build can ship in one step. To skip auto-bundling pass `--no-auto-bundle` and run `package bundle` yourself.
+
+### 5. Capture the result in CI
+
+```bash
+pnpm run --silent sdk package publish --json > publish.json
+```
+
+On a 200 response the envelope's `data` is the server's `PackageVersionResponse`:
+
+```json
+{
+    "ok": true,
+    "command": "package publish",
+    "data": {
+        "handle": "pv_abc123",
+        "packageHandle": "pkg_xyz456",
+        "packageIdentifier": "com.example.coffeeshop",
+        "packageName": "Coffee Shop",
+        "version": "1.2.0",
+        "createdAt": "2026-05-15T12:00:00Z",
+        "games": [{ "identifier": "com.example.coffeeshop.game" }]
+    },
+    "warnings": []
+}
+```
+
+On any non-2xx response the CLI exits non-zero, and the envelope is `{ "ok": false, "error": { "code", "message" }, ... }`, so a capture script has one shape to parse and a code to branch on: `PLATFORM_UNAUTHORISED` (exit 5) for a bad key, `VERSION_EXISTS` (exit 3) for a version already uploaded, `PLATFORM_REJECTED` (exit 3) for a package the platform refused. See [Exit codes](../cli-reference.md#exit-codes).
+
+A complete CI sequence:
+
+```bash
+# In CI, after lint/test/typecheck have passed
+pnpm run --silent sdk package version patch --json | tee version.json
+pnpm run sdk build
+pnpm run --silent sdk package publish --json | tee publish.json
+```
+
+`version.json` carries `previous`, `next`, and the files touched in its `data`. `publish.json` carries the hosted version's handle for any downstream step (notification, tagging, audit log).
+
+## Verify
+
+- The CLI exits 0
+- `publish.json` contains a `handle` starting with `pv_`
+- The hosted dashboard lists the new version under your package
+
+## Troubleshooting
+
+- **'No API key configured'**: set `SERIOUSGAMING_API_KEY` in your environment or pass `--api-key`
+- **'No publisher configured'**: set `SERIOUSGAMING_PUBLISHER`, pass `--publisher <slug>`, or run `pnpm run sdk config set platform.defaultPublisher <slug>`
+- **'Invalid API key'** (401): the token is malformed or has been revoked. Issue a new one
+- **'The account that created this API key does not have publishing access'** (403): the key is valid, but its account cannot publish. Ask Business Simulations to grant publishing access to that account, or use a key from an account that has it
+- **An identifier error mentioning a publisher** (400): the package is already bound to a different publisher. Upload later versions under the same publisher it was first published with
+- **'Version X.Y.Z of <identifier> already exists'** (409): bump the version (`pnpm run sdk package version patch`) and retry. The CLI deliberately does not auto-bump, so an agent can decide whether to bump or abort
+- **'Bundle not found at dist/...'**: run `pnpm run sdk build` first, or drop `--no-auto-bundle` and let the command bundle for you
+- **Network errors**: the original message is surfaced verbatim. Check connectivity and the `--host` URL
+
+## Related
+
+- [CLI reference: package publish](../cli-reference.md#publish-a-package-to-the-serious-gaming-platform)
+- [Distribute a built package](distribute-package.md): the underlying bundle step
+- [Set the package version](../cli-reference.md#set-the-package-version): bumping before publish