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

package/dist/docs/guides/file-handling.md

@@ -0,0 +1,405 @@
+# File handling (assets and blobs)
+
+The SDK reads every file, whether it ships in the package or arrives at runtime, through one reference scheme. This guide explains the scheme, then covers uploading files at runtime, displaying them in UIs, and reading their bytes in logic.
+
+Common uses include uploading a market research PDF in a decisions UI, displaying it in a results UI, and summarising it with an LLM inside an engine.
+
+## Asset references
+
+Every file a game can read is named by a self-describing string:
+
+```
+asset:<path>   // a file inside the active scenario's assets/ directory
+shared:<path>  // a file inside the package-level shared-assets/ directory
+blob:<id>      // a file uploaded at runtime, in the blob store
+```
+
+Any string that begins with `asset:`, `shared:`, or `blob:` is an asset reference, and no other string is. So settings and context can mix scenario files, package files, and uploads freely: the prefix tells the resolver which store to read, and the code that uses a reference never needs to know which kind it holds.
+
+- **`asset:`** is scenario-scoped. It resolves against the active scenario's `assets/` directory, and resolves to nothing when no scenario is active
+- **`shared:`** is package-level. It resolves against `shared-assets/` at the package root, whatever scenario is active, or none (see [Sharing assets across scenarios](./scenarios.md#sharing-assets-across-scenarios))
+- **`blob:`** names an upload. `uploadBlob` in a UI and `writeBlob` in logic both return one, so store it directly in context: there is no separate id to track
+
+`asset:` and `shared:` are disjoint: there is no shadowing or precedence between them.
+
+### The callbacks
+
+Every callback that works on a file takes a reference:
+
+- **`getAssetUrl(reference)`** returns a URL the browser can fetch, for `<img>`, `<embed>`, `<video>` and the like. Synchronous, and in a UI only. In a hosted runtime the URL is on the runtime's asset host, cross-origin to the surface's iframe. `useAssetUrl` is the hook form
+- **`readAsset(reference)`** returns the bytes, MIME type, and display name. Asynchronous. In logic the runtime resolves the reference server-side; in a UI the SDK fetches the URL with `credentials: 'include'`. `useAsset` is the hook form that reads text, JSON, or a `Blob`
+- **`extractText(reference)`** returns plain text from a PDF. It is offered to the engine, hooks, tick controllers, and endpoints that declare it in `uses`; a UI reaches it through an endpoint
+
+In a UI, `getAssetUrl` strips the prefix and appends the rest to an absolute prefix the host supplies for each scheme. Under `sdk dev` those prefixes are on the asset origin (`--asset-port`), so `asset:shared/hero.jpg` becomes `http://localhost:<asset-port>/assets/scenario/shared/hero.jpg`; a hosted runtime points them at its own asset host. With no scenario active an `asset:` reference still produces a URL, which answers 404. A string with none of the three prefixes throws.
+
+### Writing references in a scenario
+
+A scenario writes references with the prefix in place, usually as values of settings the engine and UIs read:
+
+```json
+{
+    "definition": {
+        "settings": {
+            "briefing": {
+                "Logo": "asset:shared/logo.svg",
+                "ScenarioBrief": "asset:en/intro.pdf"
+            }
+        }
+    }
+}
+```
+
+Here `briefing` is a settings resource (`settings/briefing/`) declaring `Logo` and `ScenarioBrief` as strings with an empty default, which the engine and UI examples below list in their `settings`. The runtime takes these strings as they are: nothing checks at scenario load that the file exists, and a reference that does not resolve fails when something calls `getAssetUrl`, `readAsset`, or `extractText` with it. See [Scenarios](./scenarios.md#2-add-assets-optional) for where the files go.
+
+### How a file moves through a game
+
+```
+User uploads file in decisions UI
+        ↓
+uploadBlob(file) → returns 'blob:<id>'
+        ↓
+setData({ 'upload': { DocumentRef: reference } })
+        ↓
+Next tick: engine reads bytes via readAsset(reference)
+Results UI displays via getAssetUrl(reference)
+```
+
+## Uploading a file in a UI
+
+Use the `uploadBlob` callback from `useUserInterfaceCallbacks`. It returns a `blob:`-prefixed reference; store it directly:
+
+```typescript
+import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function DocumentUpload() {
+    const callbacks = useUserInterfaceCallbacks();
+    const { setData } = useUserInterfaceData<Context, Settings>();
+    const [isUploading, setIsUploading] = useState(false);
+
+    const handleFileUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+        const file = e.target.files?.[0];
+        if (!file) return;
+
+        try {
+            setIsUploading(true);
+            const reference = await callbacks.uploadBlob(file);
+
+            setData({
+                upload: { DocumentRef: reference },
+            });
+        } finally {
+            setIsUploading(false);
+            e.target.value = '';
+        }
+    };
+
+    return (
+        <div>
+            <input
+                type="file"
+                accept=".pdf,.csv,.txt"
+                onChange={handleFileUpload}
+                disabled={isUploading}
+            />
+            {isUploading && <p>Uploading...</p>}
+        </div>
+    );
+}
+```
+
+**Notes:**
+
+- You do not choose the blob's lifetime: the host assigns it from the UI type (see [Blob scopes](#blob-scopes) below)
+- The maximum file size is **20 MB**
+- The returned string starts with `blob:`. Persist it in context via `setData` so the engine and other UIs can resolve it
+
+## Displaying a file in a UI
+
+Use `useAssetUrl` to resolve any reference to a URL suitable for `<img>`, `<embed>`, `<video>`, or any HTML element that takes a `src`. It returns `undefined` for an absent reference. Whether the reference came from an uploader (`blob:abc123`) or a scenario (`asset:shared/intro.pdf`), the component is the same:
+
+```typescript
+import { useAssetUrl, useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function DocumentViewer() {
+    const { data, settings } = useUserInterfaceData<Context, Settings>();
+    const src = useAssetUrl(data.upload?.DocumentRef || settings.briefing.ScenarioBrief);
+
+    if (!src) {
+        return <p>No document uploaded.</p>;
+    }
+
+    return (
+        <embed
+            src={src}
+            type="application/pdf"
+            style={{ width: '100%', height: '500px', border: 'none' }}
+        />
+    );
+}
+```
+
+For images, including a logo bundled in a scenario:
+
+```tsx
+const logo = useAssetUrl('asset:shared/logo.svg');
+return <img src={logo} alt="Logo" />;
+```
+
+Outside a component, the surface's `getAssetUrl` callback does the same. To render a file's contents rather than link to it, such as a localised briefing, use `useAsset(reference, { as: 'text' })`, which fetches and reads it (see [Reading an asset's contents](./ui.md#reading-an-assets-contents)).
+
+## Reading an asset in an engine
+
+The engine receives `readAsset` in its callbacks. It accepts an `asset:`, `shared:`, or `blob:` reference and returns the bytes plus metadata:
+
+```typescript
+import { decodeUtf8, getText, type RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }) => {
+    const reference = context.upload?.DocumentRef;
+
+    if (reference) {
+        const { data, mimeType, name } = await callbacks.readAsset(reference);
+
+        const text = decodeUtf8(data);
+
+        const summary = await callbacks.generateText({
+            prompt: `Summarise this document:\n\n${text}`,
+            tier: 'standard',
+        });
+
+        return {
+            capabilities: {
+                ...context,
+                summary: {
+                    ...context.summary,
+                    Summary: getText(summary),
+                },
+            },
+        };
+    }
+
+    return { capabilities: context };
+};
+```
+
+**Notes:**
+
+- `readAsset` needs no `uses` entry: every engine, hook, tick controller, and endpoint has it
+- `data` is a `Uint8Array`. Use `decodeUtf8` for text formats; pass binary directly to downstream APIs
+- The same callback resolves `asset:shared/brief.pdf` and `blob:abc123`: there is no separate API for bundled and uploaded files
+
+## Extracting text from a document
+
+Use the `extractText` callback to convert a document into plain text suitable for passing to an LLM. Available in the engine, hooks, tick controllers, and endpoints that declare `"extractText"` in `uses`. UIs reach it through an endpoint. Currently supports **PDF** files.
+
+### In an engine
+
+Declare `"uses": ["extractText", "generateText"]` on the engine, and pass the generated `Callbacks` as `RunFunction`'s third type argument so both are typed as present:
+
+```typescript
+import { getText, type RunFunction } from '@seriousgaming/sdk';
+import type { Callbacks, Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings, Callbacks> = async ({
+    context,
+    settings,
+    callbacks,
+}) => {
+    // An upload if there is one, else the brief the scenario supplies
+    const reference = context.upload?.DocumentRef || settings.briefing.ScenarioBrief;
+
+    if (reference) {
+        const { content } = await callbacks.extractText(reference);
+
+        const summary = await callbacks.generateText({
+            prompt: `Summarise this document:\n\n${content}`,
+            tier: 'standard',
+        });
+
+        return {
+            capabilities: {
+                ...context,
+                summary: {
+                    ...context.summary,
+                    Summary: getText(summary),
+                },
+            },
+        };
+    }
+
+    return { capabilities: context };
+};
+```
+
+### From a UI, through an endpoint
+
+UIs cannot call `extractText` directly. Upload the document with `uploadBlob`, then pass the returned reference to an endpoint that wraps `extractText`:
+
+```typescript
+// endpoints/extract/logic/logic.ts
+import type { Handler } from '../types';
+
+export const Handle: Handler = async ({ request, callbacks }) => {
+    // Declared in `uses`, so always present: no check needed.
+    const { content } = await callbacks.extractText(request.reference);
+    return { text: content };
+};
+```
+
+The endpoint bundle declares `"uses": ["extractText"]`; the UI declares the endpoint in its `endpoints` array and calls it:
+
+```tsx
+import { useState } from 'react';
+import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+import type { Callbacks } from '../types';
+
+function DocumentProcessor() {
+    const callbacks = useUserInterfaceCallbacks() as Callbacks;
+    const [extractedText, setExtractedText] = useState<string | null>(null);
+
+    const handleExtract = async (reference: string) => {
+        const { text } = await callbacks.endpoints['extract']({ reference });
+        setExtractedText(text);
+    };
+
+    return extractedText ? <pre>{extractedText}</pre> : <p>No text extracted.</p>;
+}
+```
+
+See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md).
+
+**Notes:**
+
+- Without the generated `Callbacks` type argument, `extractText` is typed as optional, and a resource that calls it without declaring it in `uses` throws at run time
+- The extracted text is plain text. For PDFs, the quality depends on the source document (text-based PDFs extract well; scanned documents may not)
+
+## Sending a file to an endpoint
+
+An endpoint that takes a file declares it in its request schema with `blob`, so the runtime checks the file before the handler runs:
+
+```json
+"reference": {
+    "type": "string",
+    "blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
+}
+```
+
+The field accepts two kinds of string, so the same endpoint serves every caller:
+
+- **A `blob:` reference** to a file already stored. A UI passes the reference `uploadBlob` returned, as in the example above; a script or an agent uploads first (locally, `POST /api/blobs` or `pnpm run sdk blob upload`)
+- **A `data:` URI** carrying the file inline, for a caller with no upload of its own: `data:application/pdf;name=brief.pdf;base64,...`. Up to 5 MB
+
+Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
+
+See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
+
+## Blob scopes
+
+Every blob is stored with a retention that controls its lifetime:
+
+| Retention    | Lifetime                                             | When to use                                                                                                     |
+| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `"game"`     | Cleared on a session reset or a re-initialise        | Participant-uploaded content for a specific game session                                                        |
+| `"settings"` | Survives a session reset, cleared on a re-initialise | Documents set up before the game starts (e.g. a scenario brief uploaded from a setup screen or scenario editor) |
+
+Retention is a deletion-lifecycle bucket only: it is not an access or visibility control. It is set at upload time, and who sets it depends on the surface:
+
+- **UIs** never choose the retention. The host assigns it from the UI type: uploads from setup or the scenario editor are `"settings"`, every other UI's uploads are `"game"`. The `uploadBlob` callback takes no retention option
+- **Engine / endpoint `writeBlob`** has no UI to derive from, so it takes an explicit `retention` option (default `"game"`)
+- **CLI uploads** default to `"game"` retention but accept `--settings` to use `"settings"` retention
+
+A deleted blob's reference answers 404, as an unknown one does. In the dev server, `sdk init`, the console's Re-initialise and Reconfigure, and selecting a scenario clear both retentions. The automatic re-initialise after a package edit clears `"game"` blobs only, so the scenario editor's uploads survive an edit. A per-team reset clears nothing, since blobs are not held per team, and neither does resetting the walkthrough.
+
+## Uploading a blob via CLI
+
+You can pre-load a file into a game session from the command line:
+
+```bash
+pnpm run sdk blob upload <file-path>
+```
+
+**Options:**
+
+- `--settings`: store with `'settings'` retention (survives a session reset). Default is `'game'` retention
+- `--json`: print one JSON document for scripts, with the result as its `data`
+
+**Output (default):**
+
+```
+Uploaded blob: blob:a3f7c2d1-84b0-4e12-9f1a-0c7e8a3b1d5e
+  File:  market-research.pdf
+  Type:  application/pdf
+  Retention: game
+```
+
+**Output (`--json`):** one JSON document (see [JSON output](../cli-reference.md#json-output)), whose `data` is:
+
+```json
+{
+    "reference": "blob:a3f7c2d1-84b0-4e12-9f1a-0c7e8a3b1d5e",
+    "name": "market-research.pdf",
+    "mimeType": "application/pdf",
+    "retention": "game"
+}
+```
+
+After uploading, patch the reference into the game context so the engine can find it:
+
+```bash
+REFERENCE=$(pnpm run --silent sdk blob upload market-research.pdf --json | jq -r '.data.reference')
+pnpm run sdk patch \
+  "[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
+```
+
+## Supported file types
+
+MIME types are detected from the file extension:
+
+| Extension       | MIME type                  |
+| --------------- | -------------------------- |
+| `.pdf`          | `application/pdf`          |
+| `.png`          | `image/png`                |
+| `.jpg`, `.jpeg` | `image/jpeg`               |
+| `.gif`          | `image/gif`                |
+| `.webp`         | `image/webp`               |
+| `.svg`          | `image/svg+xml`            |
+| `.mp4`          | `video/mp4`                |
+| `.webm`         | `video/webm`               |
+| `.mp3`          | `audio/mpeg`               |
+| `.wav`          | `audio/wav`                |
+| `.json`         | `application/json`         |
+| `.csv`          | `text/csv`                 |
+| `.txt`          | `text/plain`               |
+| Other           | `application/octet-stream` |
+
+## Capability design
+
+Define a capability to hold asset references:
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "upload",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "DocumentRef": { "type": "string", "default": "" }
+      },
+      "required": ["DocumentRef"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+The directory is the declaration: there is no list in `seriousgaming.sdk.json` to register it in. Then reference it from the resources that need it:
+
+- The **game UI** (`ui/`) lists `upload` in both its `writes` and its `reads`: the decisions and results panels are both components inside it
+- Any **engine** that processes the document lists `upload` in its `reads`
+
+## Example
+
+Put together, the pieces above make an upload round trip. One component inside the game UI uploads a PDF with the code in [Uploading a file in a UI](#uploading-a-file-in-a-ui) and writes the returned reference to `upload.DocumentRef`; another reads `upload.DocumentRef` and embeds the file with the code in [Displaying a file in a UI](#displaying-a-file-in-a-ui). The engine reads the same reference when it needs the document's contents, as [Reading an asset in an engine](#reading-an-asset-in-an-engine) shows.

package/dist/docs/guides/games.md

@@ -0,0 +1,176 @@
+# Shaping games
+
+A package is a game. This guide shows you how to shape the one you have.
+
+## What you'll learn
+
+- Where a game is authored
+- How to configure the engine and game UI it runs
+- How to add a setup screen and a scenario editor
+- How to set up multi-language support
+- Where to read about goal-based games with dynamic end conditions
+
+## Where the game lives
+
+The game is `seriousgaming.sdk.json`: the manifest is the package, and the package is the game.
+
+```json
+{
+    "identifier": "com.example.mygame",
+    "supportedLocales": ["en"],
+    "locales": { "en": { "name": "My Game" } },
+    "maxTicks": 10
+}
+```
+
+The game's own identifier is `com.example.mygame.game`, the package identifier with `.game` appended, so it is never authored. The version is `package.json`'s. What the game wires is whatever the package declares, and what the package declares is whatever sits in the conventional directories beside this file:
+
+```
+com.example.mygame/
+├── seriousgaming.sdk.json
+├── capabilities/stock/capability.sdk.json
+├── engine/engine.sdk.json
+└── ui/ui.sdk.json
+```
+
+Edit the file by hand, or through the CLI:
+
+```bash
+pnpm run sdk update package --patch '[{ "op": "replace", "path": "/maxTicks", "value": 20 }]'
+```
+
+## Engines and UIs
+
+A game holds one engine and one game UI: whichever ones the package declares. There is nothing to list. Order the simulation's steps by the order you call them inside the engine's `Run`.
+
+## Configuring them
+
+A game's parameters live in settings resources, `settings/<name>/settings.sdk.json`, not in the manifest. Each property declares a default, and the default is the game's own value: to change it, edit the settings resource. A resource reads the settings it lists in its `settings`:
+
+```json
+{
+    "definition": {
+        "reads": ["stock"],
+        "writes": ["stock"],
+        "settings": ["engine"]
+    }
+}
+```
+
+A scenario or the facilitator's setup screen overrides settings by identifier, and nothing else does. The manifest has no `configuration` block, and the build refuses one. See [Settings](./settings.md).
+
+The manifest's `maxTicks`, `teams` and `waitingRoom` are the exception, because every game has them: they are the game's own values for the built-in `game` settings, which a scenario or setup overrides under `game` like any other. Only `teams.mode` is fixed, since nothing can change a game's interaction mode. `gameSettingsConstraints` narrows or locks the rest, for example to four to ten rounds (see [Narrow or lock the game settings](./settings.md#narrow-or-lock-the-game-settings)). See [The game settings](./settings.md#the-game-settings).
+
+## Adding setup and a scenario editor
+
+Two optional slots edit a game's settings. Each is a slot, so nothing in the manifest names it:
+
+- `setup/`: a short form at session creation, writing that session's overrides only. Every session of a game with a setup slot starts at its configuration step, with the setup screen open and participants waiting, until the facilitator presses **Play**; switching scenario returns it there. A session of a game without one starts at tick 0
+- `scenario_editor/`: a screen for building lasting scenarios, at any time and with no session. The host offers save-as-scenario from it, never from setup
+
+Each lists the settings resources it edits in `configures`. A game may have either, both, or neither. Custom scenarios in a hosted runtime are switched on by `customScenarios: { "supported": true }`, not by the editor: an agent can author a scenario from well-described settings schemas alone.
+
+See [Building a setup screen](./setup.md) and [Building a scenario editor](./scenario-editor.md).
+
+## Multi-language support
+
+Add localisation to your game:
+
+```json
+{
+    "identifier": "com.example.production",
+    "supportedLocales": ["en", "es", "fr"],
+    "locales": {
+        "en": { "name": "Production Game" },
+        "es": { "name": "Simulación de Producción" },
+        "fr": { "name": "Game de Production" }
+    },
+    "maxTicks": 10
+}
+```
+
+The facilitator switches the session language with the locale select in the console's dev drawer; the choice applies to every participant.
+
+## Goal-based games
+
+A game can end when a condition is met rather than after a fixed count: leave out `maxTicks` and return `complete: true` from the engine's `Run` (or from a tick controller). See [Game completion](./tick-controller.md#game-completion) for the reference, and [End a game when a condition is met](../recipes/end-game-on-condition.md) for the steps.
+
+## Host controls
+
+**The Play control is the host's.** It is always rendered on the configuration
+step and a game cannot hide it. A setup screen may add a finish control of
+its own with the [`requestPlay` callback](./setup.md#starting-play-from-your-own-control),
+which does the same thing, but it is an addition, never a replacement, so a bug
+in a game's own control cannot leave a facilitator with no way out of
+configuration.
+
+**Tick controls are the game's own.** There is no built-in next tick button: use the [`requestTick` callback](./ui.md#requesting-a-tick) in a game or session UI to advance the game. The console's dev drawer keeps a developer-only **Tick** button for testing.
+
+**Tip**: To finish configuration from inside your own form, call `requestPlay` from your [setup screen](./setup.md). The host's Play control stays alongside it.
+
+## Full example game
+
+Here's a complete game example:
+
+```json
+{
+    "identifier": "com.example.retail",
+    "supportedLocales": ["en", "es"],
+    "locales": {
+        "en": { "name": "Retail Business Game" },
+        "es": { "name": "Simulación de Negocio Minorista" }
+    },
+    "maxTicks": 52,
+    "teams": { "mode": "independent", "min": 2, "max": 6 }
+}
+```
+
+## Testing games
+
+Start the dev server to test your game:
+
+```bash
+pnpm run sdk dev
+```
+
+Open http://localhost:3000 to view your game. You can:
+
+- Step through ticks
+- Inspect context state
+- Undo/redo changes
+- Switch languages
+
+## Updating games
+
+`update package` takes no identifier of its own, and a patch's paths start at the manifest:
+
+```bash
+pnpm run sdk update package --patch '[{ "op": "replace", "path": "/maxTicks", "value": 20 }]'
+```
+
+## Best practices
+
+1. **Name clearly**: use descriptive package identifiers, since the game takes its name from the package
+    - ✅ `com.example.retailbusinessgame`
+    - ❌ `com.example.sim1`
+
+2. **Reasonable tick count**: balance educational value and execution time
+    - ✅ 10-52 ticks for most games
+    - ❌ 1000+ ticks
+
+3. **Organise resources**: group related variables into one capability
+    - ✅ Call the engine's steps in the order their data flows
+    - ❌ Reading a value a later step writes
+
+4. **Test before deploying**: use the dev server to validate everything works
+    - ✅ Run through all ticks, check engine behaviour
+    - ❌ Deploy without testing
+
+5. **Support languages**: add localisation from the start
+    - ✅ Include English, Spanish, French
+    - ❌ Only English
+
+## Next steps
+
+- [Getting started](../getting-started.md): test your game
+- [Building user interfaces](./ui.md): build custom UIs

package/dist/docs/guides/global-settings.md

@@ -0,0 +1,94 @@
+# Global settings
+
+The global settings file lets you store API keys and defaults once, in a single user-owned file, so every project picks them up. It is the convenient default for the credentials the SDK needs: ElevenLabs and the Serious Gaming platform.
+
+Without it, each new shell needs the keys re-exported, and project-level `.env` files are easy to leak into git. The global file lives outside any project, so it is shared across every game you work on.
+
+## Location
+
+The file lives at:
+
+```
+~/.seriousgaming-sdk/config.json
+```
+
+This resolves correctly on every platform via the home directory, with no platform branching:
+
+- macOS: `~/.seriousgaming-sdk/config.json`
+- Linux: `~/.seriousgaming-sdk/config.json`
+- Windows: `C:\Users\<user>\.seriousgaming-sdk\config.json`
+
+To use a different location, set `SERIOUSGAMING_SDK_CONFIG` to an absolute path:
+
+```bash
+export SERIOUSGAMING_SDK_CONFIG=/path/to/my-settings.json
+```
+
+Run `pnpm run sdk config path` to print the resolved location.
+
+## File shape
+
+```json
+{
+    "elevenLabs": { "apiKey": "..." },
+    "platform": {
+        "apiHost": "https://app.businesssimulations.com",
+        "apiKey": "sg_...",
+        "defaultPublisher": "..."
+    }
+}
+```
+
+Every field is optional. Set only what you need.
+
+## Managing settings from the CLI
+
+You do not have to edit the file by hand. The `config` commands manage it for you:
+
+```bash
+# Set a value (creates the file if needed)
+pnpm run sdk config set platform.apiKey sg_...
+
+# Read a value
+pnpm run sdk config get platform.apiKey
+
+# Print the resolved file path
+pnpm run sdk config path
+```
+
+The available keys are:
+
+- `elevenLabs.apiKey`
+- `platform.apiHost`, `platform.apiKey`, `platform.defaultPublisher`
+
+`config set` replaces whatever the key held before, and says so when it does. Check with `config get` before you set a key you are only trying to confirm, and be wary of pasting an example value from these docs over a real one.
+
+Only `config set` writes to the file. `config get` and `config path` never change it.
+
+If the file exists but is not valid JSON, `config set` refuses to write rather than replacing it with just the key you asked for. Fix or remove the file, then run the command again.
+
+## Precedence
+
+The global settings file is the lowest-priority source. From lowest to highest, the SDK merges:
+
+1. Global settings file (`~/.seriousgaming-sdk/config.json`)
+2. Project `.env` file
+3. Environment variables
+4. CLI flags
+
+So a value in your shell environment, a project `.env`, or a `--flag` always wins over the global file. This keeps CI and one-off shells in control: the file is a convenience default, never an override.
+
+For example, with `platform.apiKey` set in the global file, running a command in a shell that also exports `SERIOUSGAMING_API_KEY` uses the environment value, not the file.
+
+## Security
+
+The file is stored in plaintext and is not encrypted. Treat it like any other secrets file:
+
+- On macOS and Linux, the SDK creates it with owner-only permissions. You can confirm or re-apply this with `chmod 600 ~/.seriousgaming-sdk/config.json`
+- On Windows, restrict access with a restrictive ACL so only your user account can read it
+- Never commit the file to git. It lives outside your project directory by default, so it is not picked up by a project's version control unless you move it
+
+## Related
+
+- [LLM integration](llm-integration.md)
+- [Speech generation](speech-generation.md)