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

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

@@ -0,0 +1,111 @@
+# Create an engine
+
+Write the engine that moves the game on each tick: here, one that reads a price and writes the day's revenue.
+
+**Keywords:** create engine, new engine, engine example, add engine, simple engine, update engine, Init, Run
+
+## Prerequisites
+
+- A capability to read (here `pricing`, with `BasePrice`) and one to write (here `sales`, with `Revenue` and `DailySales`); see [Create a capability](create-capability.md)
+- A settings resource for the engine's parameters (here `demand`, with `DailyUnitsSold`); see [Create settings](create-settings.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Declare what the engine reads, writes, and takes as settings. A game holds one engine, in the `engine/` slot, and the starter game already has it, so in a package made with `new package` update it:
+
+    ```bash
+    pnpm run sdk update engine --patch '[
+      { "op": "replace", "path": "/definition/reads", "value": ["pricing"] },
+      { "op": "replace", "path": "/definition/writes", "value": ["sales"] },
+      { "op": "replace", "path": "/definition/settings", "value": ["demand"] }
+    ]'
+    ```
+
+    In a package made with `new package --empty`, create it:
+
+    ```bash
+    pnpm run sdk new engine '{
+      "definition": {
+        "reads": ["pricing"],
+        "writes": ["sales"],
+        "settings": ["demand"]
+      },
+      "logic": { "directory": ".", "entrypoint": "logic.ts" },
+      "rootDirectory": "."
+    }'
+    ```
+
+    Either command regenerates `engine/types.ts`. `update engine` leaves `engine/logic.ts` alone.
+
+2. Write `Init` and `Run` in `engine/logic.ts`. Each returns what it writes under `capabilities`, spreading rather than mutating:
+
+    ```typescript
+    import { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
+
+    import type { Callbacks, Context, Settings } from './types';
+
+    export const Init: InitializationFunction<Context, Settings, Callbacks> = async ({
+        context,
+        settings,
+    }) => ({
+        capabilities: {
+            ...context,
+            sales: { ...context.sales, Revenue: 0, DailySales: settings.demand.DailyUnitsSold },
+        },
+    });
+
+    export const Run: RunFunction<Context, Settings, Callbacks> = async ({
+        context,
+        settings,
+    }) => ({
+        capabilities: {
+            ...context,
+            sales: {
+                ...context.sales,
+                Revenue: context.pricing.BasePrice * context.sales.DailySales,
+                DailySales: settings.demand.DailyUnitsSold,
+            },
+        },
+    });
+    ```
+
+3. If you replaced the starter game's engine, replace or delete `engine/logic.test.ts` and the starter's other engine files, which test the old logic.
+
+4. In a package made with `--empty`, set how long the game runs (the starter already sets `maxTicks`):
+
+    ```bash
+    pnpm run sdk update package --patch '[{ "op": "add", "path": "/maxTicks", "value": 10 }]'
+    ```
+
+5. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk init
+pnpm run sdk tick
+pnpm run sdk view
+```
+
+`sales.Revenue` is `BasePrice` times the previous day's `DailySales`, and `sales.DailySales` is the `demand` setting.
+
+## Troubleshooting
+
+| Problem                                 | Solution                                                        |
+| --------------------------------------- | --------------------------------------------------------------- |
+| `new engine` refuses: the game has one  | Use `update engine` (step 1)                                    |
+| `context.pricing` is a type error       | Add `pricing` to `reads`; the command regenerates `types.ts`    |
+| `settings.demand` is undefined          | List `demand` in the engine's `settings`                        |
+| The tick fails with a flat-result error | Return the new state under `capabilities`, not at the top level |
+| The engine's write is refused           | The engine returned a capability outside its `writes`           |
+
+## Related
+
+- [Engine guide](../guides/engine.md): the model, results, memory between ticks, aggregate engines, and the language environment
+- [Test a whole game in-process](test-with-engine.md)
+- [Create a user interface](create-user-interface.md)

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

@@ -0,0 +1,70 @@
+# Shape your game
+
+Set what your package's game is: its name in each locale, how long it runs, and its teams.
+
+**Keywords:** create game, new game, game definition, game setup, game manifest, seriousgaming.sdk.json, ticks, teams, locales, update package
+
+## Prerequisites
+
+- A package (see [Getting started](../getting-started.md)). A package is a game: there is no `new game`, and the game runs whatever resources sit beside its manifest
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Name the game in each locale it supports. Patch the field rather than replacing the manifest, so the fields you do not name stay as they are:
+
+    ```bash
+    pnpm run sdk update package --patch '[
+      { "op": "replace", "path": "/locales/en/name", "value": "Retail Simulation" }
+    ]'
+    ```
+
+2. Set how many ticks the game runs, one per meaningful period or phase:
+
+    ```bash
+    pnpm run sdk update package --patch '[{ "op": "add", "path": "/maxTicks", "value": 12 }]'
+    ```
+
+    For a game that ends on a goal rather than a count, see [End a game when a condition is met](end-game-on-condition.md). Do not set a large `maxTicks` 'just in case', and do not keep a tick number, a status, or a phase in context: the SDK tracks them.
+
+3. Set the teams: the interaction mode and how many teams a session may have:
+
+    ```bash
+    pnpm run sdk update package --patch '[
+      { "op": "add", "path": "/teams", "value": { "mode": "independent", "min": 1, "max": 8 } }
+    ]'
+    ```
+
+    See [Play modes](../guides/multi-team-games.md#play-modes) for `independent` and `shared-state`.
+
+4. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk init
+pnpm run sdk tick
+pnpm run sdk view
+```
+
+`init` runs the engine's `Init`, and `view` shows `completedTicks: 1` after one tick. To play with different settings without changing their defaults, see [Overriding settings from the CLI](../guides/settings.md#from-the-cli).
+
+## Troubleshooting
+
+| Problem                                               | Solution                                                                       |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------ |
+| The build reports no engine                           | Check `engine/engine.sdk.json` exists                                          |
+| The build warns that only the engine can end the game | There is no `maxTicks`; expected for a goal-based game                         |
+| A patch fails on a missing path                       | Use `add` for a field the manifest does not have yet, `replace` for one it has |
+| Detailed errors                                       | Run `pnpm run sdk build --validate-only --json`                                |
+
+## Related
+
+- [Games guide](../guides/games.md): the manifest, host controls, and goal-based games
+- [Create settings](create-settings.md)
+- [Create a setup screen](create-setup.md)
+- [Drive a game from the CLI](../cli-simulation-testing.md)

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

@@ -0,0 +1,75 @@
+# Create a facilitator guide
+
+Bundle a facilitator guide with your game: markdown chapters shown on the facilitator's page.
+
+**Keywords:** create facilitator guide, new facilitator guide, cheat sheet, run sheet, facilitation notes, session script, markdown guide, say do timing
+
+## Prerequisites
+
+- A package with `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Declare the guide's locales and titles. A game holds at most one guide, in the `guide/` slot, and the starter game already fills it, so in a package made with `new package` update it:
+
+    ```bash
+    pnpm run sdk update guide --patch '[
+      { "op": "add", "path": "/definition/locales/de", "value": { "name": "Moderationsleitfaden" } }
+    ]'
+    ```
+
+    In a package without one, create it, which scaffolds a chapter skeleton for every locale:
+
+    ```bash
+    pnpm run sdk new guide '{
+      "definition": {
+        "locales": {
+          "en": { "name": "Facilitator guide" },
+          "de": { "name": "Moderationsleitfaden" }
+        }
+      },
+      "rootDirectory": "."
+    }'
+    ```
+
+2. Write the chapters as markdown files in `guide/content/<locale>/`, ordered by file name, with the same file names in every locale (`01-at-a-glance.md`, `02-preparation.md`, and so on).
+
+3. Mark the live script with admonitions:
+
+    ```markdown
+    :::say
+    Welcome everyone. Today you are running a company for three simulated years.
+    :::
+
+    :::do
+    Form the teams and hand each team its device.
+    :::
+    ```
+
+    `timing`, `note`, `warning`, and `tip` work the same way. See [Content rules](../guides/guide.md#content-rules) for headings, images, and video blocks.
+
+4. Put images in `guide/assets/` and reference them relatively from a chapter: `![Market diagram](../../assets/market-diagram.png)`.
+
+## Verify
+
+```bash
+pnpm run sdk build --validate-only
+```
+
+Validation warns when a locale is missing a chapter the reference locale has, and fails on a malformed video block or an image that does not resolve. Then open `/guide` in the dev server: the page has its own locale picker and a print button.
+
+## Troubleshooting
+
+| Problem                                     | Solution                                                                                                       |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `new guide` fails with `RESOURCE_EXISTS`    | The slot is filled: use `update guide` and edit the chapters, or `pnpm run sdk delete guide --yes` first       |
+| A chapter shows a 'not yet translated' note | That file is missing from the selected locale's directory; content falls back per file to the reference locale |
+| A video renders an error block              | The provider must be `youtube` and the id an 11-character YouTube id                                           |
+| An image does not display                   | The path must resolve inside `guide/`, for example `../../assets/diagram.png` from a chapter                   |
+| Raw HTML appears as text                    | By design: the renderer escapes HTML. Use markdown, admonitions, and video blocks                              |
+
+## Related
+
+- [Facilitator guides](../guides/guide.md): writing guidance and the full content format
+- [Create a presentation](create-presentation.md)
+- [Internationalisation](../guides/internationalization.md)

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

@@ -0,0 +1,80 @@
+# Create a hook
+
+React to a lifecycle signal, such as a participant joining a team, outside the tick loop.
+
+**Keywords:** create hook, new hook, lifecycle hook, participant join, participant move, out-of-tick
+
+## Prerequisites
+
+- A capability for the hook to write (here `roles`, with an `Assignments` map keyed by participant id); see [Create a capability](create-capability.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Create the hook, naming its signal and what it reads and writes:
+
+    ```bash
+    pnpm run sdk new hook '{
+      "definition": {
+        "identifier": "assignroles",
+        "signal": "participantJoin",
+        "reads": ["roles"],
+        "writes": ["roles"]
+      },
+      "logic": { "directory": "logic", "entrypoint": "logic.ts" },
+      "rootDirectory": "."
+    }'
+    ```
+
+    This writes `hooks/assignroles/` with `hook.sdk.json`, `logic/logic.ts`, and a generated `types.ts` that pins the signal and its payload. The directory is the whole of the wiring.
+
+2. Write `Run` in `hooks/assignroles/logic/logic.ts`, returning what it writes under `capabilities`:
+
+    ```typescript
+    import type { HookFunction } from '../types';
+
+    export const Run: HookFunction = async ({ context, participant }) => ({
+        capabilities: {
+            ...context,
+            roles: {
+                ...context.roles,
+                Assignments: {
+                    ...context.roles.Assignments,
+                    [participant.id]: context.roles.Assignments[participant.id] ?? 'observer',
+                },
+            },
+        },
+    });
+    ```
+
+3. If several hooks subscribe to the same signal and order matters, number their directories: they run in directory-name order.
+
+4. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk participant add Alice --team 1
+pnpm run sdk view
+```
+
+Adding a participant fires `participantJoin`, and the team's `roles.Assignments` holds an entry for the new participant.
+
+## Troubleshooting
+
+| Problem                         | Solution                                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| The hook never fires            | Check `hooks/<identifier>/hook.sdk.json` exists and `signal` is spelled as a signal name |
+| `context.roles` is a type error | Add `roles` to the hook's `reads`; a hook is handed only what it declares                |
+| The write is refused            | The hook returned a capability outside its `writes`                                      |
+| `participant` is undefined      | The hook is bound to a signal whose payload has no `participant`; check `signal`         |
+
+## Related
+
+- [Hooks guide](../guides/hooks.md): signals and payloads, ordering, settings, and testing
+- [Create a validator](create-validator.md)
+- [Test a whole game in-process](test-with-engine.md)

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

@@ -0,0 +1,142 @@
+# Create a presentation
+
+Ship the facilitator's slide deck with the game, so the briefing, the round dividers, the debriefs and the results travel with the package rather than in an email after train the trainer.
+
+**Keywords:** presentation, slides, slide deck, deck, briefing, debrief, results slide, PowerPoint, PDF export, facilitator slides, usePresentation, @seriousgaming/deck
+
+## What you'll build
+
+A presentation in the `presentation/` slot that:
+
+- Opens with a title slide, an agenda revealed one point per click, and a results slide
+- Renders with no session at all, showing labelled sample figures in place of results
+- Shows every team's results once a session is running
+- Exports to PDF, editable PowerPoint and PNG from its own controls
+
+A game holds at most one presentation. It is read-only: it reads every team's state, but writes nothing and calls no endpoint. Only the facilitator sees it, and the room sees it because the facilitator shares or projects their screen. See the [presentation guide](../guides/presentation.md) for the full picture.
+
+## Prerequisites
+
+- A game to attach the deck to; see [Shape your game](create-game.md)
+- `@seriousgaming/deck` in your `package.json`, at the same version as the SDK. A newly scaffolded package already has it; an older one adds it:
+    ```bash
+    pnpm add @seriousgaming/deck@<your SDK version>
+    ```
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+### 1. Create the presentation
+
+```bash
+pnpm run sdk new presentation '{
+  "definition": {
+    "reads": ["results"],
+    "settings": ["engine"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+`reads` names the capabilities the deck shows, from every team. `settings` names the settings resources it varies on. Neither `writes`, `uses` nor `endpoints` is accepted. This creates:
+
+```
+presentation/
+├── presentation.sdk.json
+├── index.html
+├── types.ts
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    ├── Slides.tsx
+    └── i18n.ts
+```
+
+### 2. Write the slides
+
+`presentation/src/Slides.tsx` returns an array, and every element of it is one slide. Use the deck's building blocks for anything a facilitator might want to edit after exporting (see [Habits that keep an export faithful](../guides/presentation.md#habits-that-keep-an-export-faithful)):
+
+```tsx
+import { Bullets, Heading, Slide, Table, Text } from '@seriousgaming/deck';
+
+import type { PresentationSession } from '../types';
+
+export function slides({ session }: { session: PresentationSession | null }) {
+    return [
+        <Slide key="agenda" transition="slide" notes="Reveal each point in turn.">
+            <div style={{ padding: '120px 140px' }}>
+                <Heading>Today</Heading>
+                <Bullets stepped items={['Meet your team', 'Play the rounds', 'Review together']} />
+            </div>
+        </Slide>,
+
+        <Slide key="results" transition="rise">
+            <div style={{ padding: '120px 140px' }}>
+                <Heading>Results</Heading>
+                {session ? (
+                    <Table
+                        columns={['Team', 'Round']}
+                        align={['start', 'end']}
+                        rows={session.teams.map((team) => [
+                            team.name,
+                            session.data.teams[team.teamId]?.completedTicks ?? 0,
+                        ])}
+                    />
+                ) : (
+                    <Text>Sample data: results appear here once the session has started</Text>
+                )}
+            </div>
+        </Slide>,
+    ];
+}
+```
+
+- Give every slide a `key`. The deck remembers the slide a facilitator was on by that name, so a slide that comes and goes with a setting does not shift them onto the wrong one
+- `stepped` on `Bullets` reveals one item per click. Wrap anything else in `<Step at={n}>` to do the same
+- `notes` go to nobody on screen and into PowerPoint's notes pane on export
+
+### 3. Make it work with no session
+
+`session` is `null` whenever the deck is shown outside a session: in a game's library, while a facilitator rehearses, or to export it before the day. Every slide must still make sense then. Where a slide would show results, show sample or placeholder figures and say so on the slide.
+
+### 4. Route every word through i18n
+
+The scaffold keeps every word in `src/i18n.ts`, in English, Italian and Arabic, and sets the deck's language and direction from `usePresentation().locale`. Add a key there for each new word, and a translation for each locale the game supports, rather than writing words into a slide.
+
+### 5. Build
+
+```bash
+pnpm run build
+```
+
+## Verify
+
+```bash
+pnpm run sdk dev
+```
+
+Open http://localhost:3000/presentation for the deck during the session, or http://localhost:3000/presentation?preview for the deck as it looks with no session. Then:
+
+- Press the right arrow, space or page down to advance, O for the overview, and F for fullscreen
+- Move the pointer to show the controls, and use **Export** to download a PDF, a PowerPoint file and a PNG of the current slide
+- Open the PowerPoint file and check that headings, bullets and tables are editable text
+
+## Troubleshooting
+
+| Problem                                        | Solution                                                                                                              |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@seriousgaming/deck'`     | Add the deck package at the SDK's version (see prerequisites), then `pnpm install`                                    |
+| The whole deck is one slide                    | The slides are wrapped in a component of your own. Return them as an array, or make each component render one `Slide` |
+| The deck shows blank or broken with `?preview` | A slide reads `session` without checking for `null`                                                                   |
+| `data` is empty for a team                     | Add the capability to the presentation's `reads`, then run `pnpm run sdk generate`                                    |
+| An export differs from the screen              | See [Habits that keep an export faithful](../guides/presentation.md#habits-that-keep-an-export-faithful)              |
+| The deck shows the wrong slides for a scenario | Branch on settings and scenario assets, never on `game.scenarioName`                                                  |
+
+## Related
+
+- [Presentation guide](../guides/presentation.md): the slot, the deck library, resume and export
+- [Create a facilitator guide](create-guide.md): the run sheet beside the deck
+- [Create a scenario](create-scenario.md): vary the deck through settings and assets

package/dist/docs/recipes/create-scenario-editor.md

@@ -0,0 +1,102 @@
+# Create a scenario editor
+
+Give people a screen for building new scenarios for your released game, without rebuilding it.
+
+**Keywords:** scenario editor, scenario builder, custom scenarios, author scenario, save as scenario, customScenarios, settings editor, configures
+
+## What you'll build
+
+A scenario editor at `scenario_editor/` that edits the `engine` and `ui` settings. The host offers save-as-scenario from it, never from setup. See the [scenario editor guide](../guides/scenario-editor.md) for when a game needs one.
+
+## Prerequisites
+
+- Settings resources for the editor to edit; see [Create a settings resource](create-settings.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+### 1. Switch custom scenarios on
+
+The editor is optional; this declaration is what lets a hosted runtime save scenarios for the game:
+
+```bash
+pnpm run sdk update package --patch '[
+  { "op": "add", "path": "/customScenarios", "value": { "supported": true } }
+]'
+```
+
+### 2. Create the slot
+
+```bash
+pnpm run sdk new scenario_editor '{
+  "definition": {
+    "configures": ["engine", "ui"]
+  },
+  "rootDirectory": ".",
+  "ui": { "entrypoint": "index.html" }
+}'
+```
+
+This creates `scenario_editor/` with `scenario_editor.sdk.json`, `index.html`, `src/{main,App,i18n,theme}`, and the generated `types.ts` and `defaults.ts`.
+
+### 3. Build the editor
+
+Open `scenario_editor/src/App.tsx`. It uses the same hooks as setup:
+
+```tsx
+import { useSettingsEditor } from '@seriousgaming/sdk/ui';
+import { Stack, TextField } from '@mui/material';
+import type { Settings } from '../types';
+
+function App() {
+    const { settings, updateSettings } = useSettingsEditor<Settings>();
+
+    return (
+        <Stack spacing={2}>
+            <TextField
+                label="Maximum price"
+                type="number"
+                value={settings.ui.MaxPrice}
+                onChange={(e) =>
+                    void updateSettings({
+                        ui: { ...settings.ui, MaxPrice: Number(e.target.value) },
+                    })
+                }
+            />
+        </Stack>
+    );
+}
+
+export default App;
+```
+
+Do not add a save button or call `requestPlay`: the host owns saving, and ignores `requestPlay` from the editor.
+
+### 4. Edit a scenario in the dev server
+
+```bash
+pnpm run sdk dev
+```
+
+Open the dev drawer, then **Scenario**, then **Edit** on a scenario (or **Add scenario**). The editor opens on `/scenario-editor`. Change a value and click **Save**.
+
+## Verify
+
+- [ ] `scenarios/<identifier>/scenario.sdk.json` holds the value you changed, under its settings identifier
+- [ ] Selecting that scenario starts a session with the value
+
+## Troubleshooting
+
+**Edit opens nothing to edit**
+
+The package has no `scenario_editor/scenario_editor.sdk.json`. Without an editor, set values with `pnpm run sdk configure` and add a scenario from the current settings.
+
+**An agent cannot tell what a setting means**
+
+Describe every property in the settings schema: `title`, `description` with units, `minimum` and `maximum`, and `enum` where the choices are closed. An agent edits a game with no editor UI from those alone.
+
+## Related
+
+- [Create a setup screen](create-setup.md)
+- [Create a scenario](create-scenario.md)
+- [Scenarios guide](../guides/scenarios.md)

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

@@ -0,0 +1,98 @@
+# Create a scenario
+
+Bundle a game flavour with settings overrides and static assets.
+
+**Keywords:** create scenario, new scenario, game variant, game flavour, difficulty preset, storyline, scenario assets
+
+## What you'll build
+
+A scenario called `hard_mode` that overrides the engine's `demand` settings and includes a briefing PDF.
+
+## Prerequisites
+
+- A package with a `demand` settings resource that declares `BaseDemand` and `InflationRate` (see [Create a settings resource](create-settings.md))
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+### 1. Create the scenario
+
+```bash
+pnpm run sdk new scenario '{
+  "definition": {
+    "identifier": "hard_mode",
+    "locales": {
+      "en": {
+        "name": "Hard Mode",
+        "description": "Higher costs, lower demand"
+      }
+    },
+    "settings": {
+      "demand": { "BaseDemand": 30, "InflationRate": 0.15 }
+    }
+  },
+  "rootDirectory": "."
+}'
+```
+
+Overrides are keyed by settings identifier and are partial: a key you leave out falls through to its default. Every resource that lists `demand` in its `settings` receives the overridden values.
+
+### 2. Add assets
+
+```bash
+cp briefing.pdf scenarios/hard_mode/assets/shared/
+```
+
+### 3. Mark it as the default
+
+```bash
+pnpm run sdk update scenario hard_mode --patch '[
+  { "op": "add", "path": "/definition/default", "value": true }
+]'
+```
+
+### 4. Load assets in a UI
+
+Scenario assets are referenced under the `asset:` URI scheme (see [Asset references](../guides/file-handling.md#asset-references)):
+
+```typescript
+const { getAssetUrl } = useUserInterfaceCallbacks();
+return <a href={getAssetUrl('asset:shared/briefing.pdf')}>Download briefing</a>;
+```
+
+## Verify
+
+```bash
+# Check the overrides against each settings resource's settingsSchema
+pnpm run sdk build --validate-only
+
+# CLI
+pnpm run sdk init --scenario hard_mode
+pnpm run sdk tick
+
+# Dev server
+pnpm run sdk dev --scenario hard_mode
+```
+
+The game should initialise with `BaseDemand: 30` and `InflationRate: 0.15`. A facilitator can still override these values through the game's setup screen: the scenario is a starting point, not a lock.
+
+You should now have:
+
+- `scenarios/hard_mode/scenario.sdk.json`, the scenario definition
+- `scenarios/hard_mode/assets/shared/briefing.pdf`, the static asset
+
+## Troubleshooting
+
+| Problem                                  | Solution                                                                            |
+| ---------------------------------------- | ----------------------------------------------------------------------------------- |
+| Build rejects an override key            | The settings resource's `settingsSchema` does not declare it, usually a misspelling |
+| Build rejects a settings identifier      | The package holds no settings resource by that name                                 |
+| Override has no effect in the UI         | The UI does not list those settings in its `settings` array                         |
+| Build refuses a default scenario         | A restricted scenario cannot also be the default                                    |
+| Facilitator value wins over the scenario | By design: the session overrides a facilitator sets win over scenario values        |
+
+## Related
+
+- [Scenarios guide](../guides/scenarios.md): the model, validation, resolution order, team names and restricted scenarios
+- [Share assets across scenarios](./share-assets-across-scenarios.md)
+- [Create a settings resource](create-settings.md)