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

package/dist/server/vite-plugin.d.ts

@@ -0,0 +1,46 @@
+import { SDKUserInterface, SDKScenarioEditor, SDKSetup, SDKSessionUserInterface, SDKWaitingRoomUserInterface, SDKPresentation } from '@seriousgaming/sdk';
+import type { Plugin } from 'vite';
+export interface SeriousGamingUiPluginSurfaces {
+    userInterfaces: SDKUserInterface[];
+    setups: SDKSetup[];
+    scenarioEditors: SDKScenarioEditor[];
+    sessionUserInterfaces: SDKSessionUserInterface[];
+    waitingRoomUserInterfaces: SDKWaitingRoomUserInterface[];
+    /** Optional so a caller predating the slot need not name it. */
+    presentations?: SDKPresentation[];
+}
+/**
+ * The surfaces to route, as a fixed set or as a function the plugin calls on
+ * each request. A dev server passes the function, so a surface added while it
+ * runs is routed without a restart (#640).
+ */
+export type SeriousGamingUiPluginOptions = {
+    workingDir: string;
+} & (SeriousGamingUiPluginSurfaces | {
+    surfaces: () => SeriousGamingUiPluginSurfaces;
+});
+/**
+ * Rewrite a document's relative asset references to root-relative ones.
+ *
+ * A surface's HTML is authored beside its sources (`src="./src/main.tsx"`) and
+ * served from under a prefix, so the browser resolves that against the prefixed
+ * document URL while Vite's module graph knows the same file by its
+ * root-relative path. The module was then fetched under both, evaluated twice,
+ * and every surface called `createRoot` on the same container twice.
+ *
+ * Rewriting here makes the document name the module the way Vite names it, so
+ * there is one identity and one evaluation.
+ */
+export declare function toRootRelative(html: string, documentDirectory: string): string;
+/**
+ * Module id of the dev-only recovery guard injected into every served surface.
+ *
+ * Virtual, so it needs no file on disk and no route of its own: Vite resolves
+ * it through the plugin and serves it under `/@id/`, which means it goes
+ * through the transform pipeline and gets an `import.meta.hot` like any other
+ * module.
+ */
+export declare const RECOVERY_MODULE_ID = "virtual:seriousgaming-surface-recovery";
+/** How the injected tag names it. Vite spells a leading NUL `__x00__` in a URL. */
+export declare const RECOVERY_MODULE_URL = "/@id/__x00__virtual:seriousgaming-surface-recovery";
+export declare function seriousgamingUiPlugin(options: SeriousGamingUiPluginOptions): Plugin;

package/dist/services/tts/client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TTS Client - dispatcher that wraps the configured TtsProvider.
+ *
+ * Resolves the provider adapter, the tier-to-model mapping, the preset-to-voice
+ * mapping, clamps `speed` to the provider's supported range, and surfaces a
+ * single `generateSpeech` entry point to the rest of the runtime.
+ *
+ * v1 ships with the ElevenLabs adapter only; additional providers (OpenAI,
+ * Google, Azure, Polly) will land behind a future `TTS_PROVIDER` env var.
+ * Adding them is a non-breaking change for game code.
+ */
+import type { GenerateSpeechRequest, GenerateSpeechResponse } from '@seriousgaming/sdk';
+import type { TtsProvider } from './types';
+export declare class TtsClientError extends Error {
+    constructor(message: string);
+}
+export interface TtsClientConfig {
+    /** ElevenLabs API key. When omitted, the client throws on first call. */
+    elevenLabsApiKey?: string;
+    /** Tier-to-model mapping. Missing tiers fall back toward `quick`. */
+    quickModel?: string;
+    standardModel?: string;
+    expertModel?: string;
+    /** Preset-to-voice mapping. Missing presets fall back to `neutral`, then provider default. */
+    voicePresets?: {
+        neutral?: string;
+        narrator?: string;
+        announcer?: string;
+        executive?: string;
+        coach?: string;
+        [preset: string]: string | undefined;
+    };
+    /** Optional custom provider — used only by tests. */
+    provider?: TtsProvider;
+}
+export declare class TtsClient {
+    private readonly provider;
+    private readonly quickModel;
+    private readonly standardModel?;
+    private readonly expertModel?;
+    private readonly voicePresets;
+    constructor(config: TtsClientConfig);
+    /** Whether the client is configured to make TTS calls. */
+    isConfigured(): boolean;
+    generateSpeech(requestOrText: GenerateSpeechRequest | string): Promise<GenerateSpeechResponse & {
+        audio: Uint8Array;
+    }>;
+    private resolveModel;
+    private resolveVoice;
+    private buildConfigurationError;
+}

package/dist/services/tts/elevenlabs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ElevenLabs adapter for the TTS dispatcher. v1 of `generateSpeech` ships
+ * with this provider only; OpenAI, Google, Azure and Polly adapters will
+ * follow behind a future `TTS_PROVIDER` env var.
+ */
+import type { NormalisedTtsRequest, TtsProvider, TtsSynthesisResult } from './types';
+export declare const ELEVENLABS_DEFAULT_MODELS: {
+    readonly quick: "eleven_flash_v2_5";
+    readonly standard: "eleven_turbo_v2_5";
+    readonly expert: "eleven_multilingual_v2";
+};
+export interface ElevenLabsAdapterConfig {
+    apiKey: string;
+    fetchImpl?: typeof globalThis.fetch;
+}
+export declare class ElevenLabsAdapter implements TtsProvider {
+    readonly name = "elevenlabs";
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(config: ElevenLabsAdapterConfig);
+    defaultVoice(): string;
+    clampSpeed(speed: number): number;
+    synthesize(request: NormalisedTtsRequest): Promise<TtsSynthesisResult>;
+}

package/dist/services/tts/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Provider-agnostic text-to-speech contract used by the TTS dispatcher.
+ *
+ * Adapters (`elevenlabs.ts`, future `openai.ts`, etc.) implement
+ * {@link TtsProvider}. The dispatcher resolves the configured adapter, maps
+ * tier → model and preset → provider voice, clamps `speed` to the supported
+ * range, and calls `synthesize` with a normalised request.
+ */
+import type { GenerateSpeechFormat, LLMTier } from '@seriousgaming/sdk';
+export interface NormalisedTtsRequest {
+    /** Plain-text utterance. */
+    text: string;
+    /** Provider-specific voice ID resolved from the preset. */
+    voice: string;
+    /** Provider-specific model ID resolved from the tier. */
+    model: string;
+    /** Output audio container. */
+    format: GenerateSpeechFormat;
+    /** Optional BCP-47 hint passed through to the provider. */
+    languageHint?: string;
+    /** Speed multiplier already clamped to the provider's supported range. */
+    speed?: number;
+    /** Tier that selected the model — useful for adapters that branch behaviour. */
+    tier: LLMTier;
+}
+export interface TtsSynthesisResult {
+    audio: Uint8Array;
+    mimeType: string;
+    durationMs?: number;
+    charactersBilled?: number;
+}
+export interface TtsProvider {
+    readonly name: string;
+    /**
+     * Synthesise audio for `request`. Throws when the provider cannot service
+     * the call (missing config, transport error, etc.); the dispatcher converts
+     * the error into a callback-level failure for game code.
+     */
+    synthesize(request: NormalisedTtsRequest): Promise<TtsSynthesisResult>;
+    /** Provider-default voice ID, used when no preset (including `neutral`) is configured. */
+    defaultVoice(): string;
+    /** Clamp `speed` to the provider's supported range. */
+    clampSpeed(speed: number): number;
+}

package/dist/storage/asset-resolver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Resolve an asset reference under the unified URI scheme.
+ *
+ *   `asset:<path>`  — package-bundled file, resolved against the active
+ *                     scenario's `assets/` directory.
+ *   `shared:<path>` — package-level file, resolved against the package's
+ *                     top-level `shared-assets/` directory. Resolvable even
+ *                     when no scenario is active.
+ *   `blob:<id>`     — runtime-uploaded file, resolved against the dev
+ *                     server's blob store.
+ *
+ * The dispatch lives here so every engine-side and endpoint-side caller
+ * (`readAsset`, `extractText`) shares a single implementation.
+ */
+export interface ResolvedAsset {
+    data: Buffer;
+    mimeType: string;
+    name: string;
+}
+/**
+ * Returns true when `value` is a string starting with one of the known
+ * asset URI scheme prefixes.
+ */
+export declare function isAssetReference(value: unknown): value is string;
+/**
+ * Resolve an `asset:` reference to a file under the scenario's `assets/`
+ * directory. The path is normalised and validated against directory traversal.
+ */
+export declare function resolveAsset(scenarioRootDirectory: string, path: string): Promise<ResolvedAsset>;
+/**
+ * Resolve a `shared:` reference to a file under the package's top-level
+ * `shared-assets/` directory. Unlike `asset:`, shared assets are package-level
+ * and resolvable with no active scenario. The path is normalised and validated
+ * against directory traversal relative to the `shared-assets/` root.
+ */
+export declare function resolveSharedAsset(packagePath: string, path: string): Promise<ResolvedAsset>;
+/**
+ * Resolve an `asset:<path>`, `shared:<path>`, or `blob:<id>` reference and
+ * return the underlying bytes, MIME type, and display name.
+ * `scenarioRootDirectory` is required for `asset:` references; pass `null` if
+ * no scenario is active and the resolver should throw on `asset:` references.
+ * `shared:` references are package-level and resolve regardless of the active
+ * scenario.
+ *
+ * Relative `scenarioRootDirectory` values resolve against `packagePath`
+ * (rather than the process CWD) so callers don't need to absolutize the
+ * scenario root before passing it in.
+ */
+export declare function readAssetByReference(packagePath: string, scenarioRootDirectory: string | null, reference: string): Promise<ResolvedAsset>;

package/dist/storage/blob-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Blob storage for game assets uploaded during configuration or play.
+ *
+ * Blobs are stored as pairs of files under .seriousgaming-sdk/blobs/:
+ *   <uuid>.bin       — raw binary data
+ *   <uuid>.meta.json — { name, mimeType, retention }
+ *
+ * Retention (§16.2) is a deletion-lifecycle bucket, not an access dimension:
+ *   "settings" — survives a session reset; cleared on a re-initialise
+ *   "game"   — cleared on a session reset or a re-initialise
+ */
+export type BlobRetention = 'settings' | 'game';
+export interface BlobMeta {
+    name: string;
+    mimeType: string;
+    retention: BlobRetention;
+}
+export interface BlobData extends BlobMeta {
+    data: Buffer;
+}
+/**
+ * Keep a package's blobs in `dir` rather than in the package, until the
+ * returned function is called. For an isolated dev server, which must neither
+ * read the developer's uploads nor leave its own beside them (#640).
+ */
+export declare function redirectBlobs(packagePath: string, dir: string): () => void;
+/**
+ * Store a blob on disk. Returns the generated blob ID.
+ * Throws if data exceeds the 20 MB limit.
+ */
+export declare function storeBlob(packagePath: string, data: Buffer, name: string, mimeType: string, retention: BlobRetention): Promise<string>;
+/**
+ * Read a blob from disk by ID.
+ * Throws if the blob does not exist.
+ */
+export declare function readBlob(packagePath: string, id: string): Promise<BlobData>;
+/**
+ * Delete every blob held under one of `retentions` (§16.2). A deleted blob is
+ * read as an unknown one: {@link readBlob} throws, and the asset route 404s.
+ */
+export declare function deleteBlobs(packagePath: string, retentions: readonly BlobRetention[]): Promise<void>;

package/dist/templates/endpoint/logic.test.ts.liquid

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { Handle } from './logic';
+import type { Request, Response, Context, Callbacks } from '../types';
+import type { EndpointCaller, EndpointSession, {% unless sessionScoped %}TeamInfo, {% endunless %}LogicMeta } from '@seriousgaming/sdk';
+
+// The run-wide facts the host supplies: the session locale, its random seed,
+// whether this is the game being played or a walkthrough beside it, and when
+// the operation started.
+const meta: LogicMeta = { locale: 'en', seed: 'test-seed', runKind: 'session', now: Date.UTC(2026, 0, 1) };
+// Where the session stands when the call is made: the ticks it has completed,
+// whether the waiting room is open, and every team's standing.
+const session: EndpointSession = {
+  mode: 'independent',
+  completedTicks: 1,
+  maxTicks: null,
+  waitingRoomOpen: false,
+  complete: false,
+  teams: [],
+};
+const callbacks = {} as Callbacks;
+const caller: EndpointCaller = {
+  sessionId: 'test-session',
+  // A participant's own team; a facilitator's or external call carries none.
+  teamId: 'team-1',
+  role: 'participant',
+  userInterfaceIdentifier: '{{ identifier }}',
+};
+{% unless sessionScoped %}// The team the call runs for, which the runtime always supplies on team scope.
+const team: TeamInfo = { teamId: 'team-1', index: 0, name: 'Team 1' };
+{% endunless %}
+describe('{{ identifier }}', () => {
+  describe('Handle', () => {
+    it('returns a valid response', async () => {
+      const request: Request = {
+        // TODO: populate request fields from requestSchema
+      } as Request;
+      const context: Context = {
+        // TODO: populate context based on declared reads
+      } as Context;
+
+      // The settings resources this endpoint lists in `settings`, keyed by
+      // identifier. Empty until it lists some.
+      const settings = {} as Parameters<typeof Handle>[0]['settings'];
+
+      const result = await Handle({
+        request,
+        context,
+        settings,
+        callbacks,
+        caller,
+{% unless sessionScoped %}        team,
+{% endunless %}        meta,
+        participants: [],
+        session,
+      });
+
+      // TODO: assert result matches responseSchema
+      expect(result).toBeDefined();
+    });
+  });
+});

package/dist/templates/endpoint/logic.ts.liquid

@@ -0,0 +1,25 @@
+import type { Handler } from '../types';
+
+export const Handle: Handler = async ({ request, context, callbacks, caller }) => {
+  // The runtime validates `request` against the requestSchema before this
+  // runs, and the response against the responseSchema before it reaches the
+  // caller.
+{%- if writes %}
+  // This endpoint declares `writes`, so it returns the response and the
+  // capabilities it changed. Only those in `writes` may appear in
+  // `capabilities`.
+  return {
+    response: {
+      // TODO: build the response shape declared in responseSchema
+    },
+    capabilities: {
+      // TODO: the capabilities this call changes
+    },
+  } as Awaited<ReturnType<Handler>>;
+{%- else %}
+  // It declares no `writes`, so it cannot change the game: return the response.
+  return {
+    // TODO: build the response shape declared in responseSchema
+  } as Awaited<ReturnType<Handler>>;
+{%- endif %}
+};

package/dist/templates/engine/init.json.liquid

@@ -0,0 +1,7 @@
+{
+  "blocks": {
+    "languageVersion": 0,
+    "blocks": []
+  },
+  "code": ""
+}

package/dist/templates/engine/logic-aggregate.test.ts.liquid

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import type { Participant, TeamRunMeta } from '@seriousgaming/sdk';
+import { defaultSettings, defaultContext, defaultSharedContext, defaultTeamContext } from './defaults';
+import { Init, InitAggregate, RunAggregate } from './logic';
+import type { Context, Settings, Callbacks, TeamContext } from './types';
+
+// `teamId` and `index` name the team whose context a per-team call receives,
+// `seed` is the session's random seed (a fixed one here keeps an assertion on
+// derived randomness stable), `runKind` says whether this is the game being
+// played or a walkthrough beside it, and `now` is when the operation started
+// (fixed here, as `seed` is, so a test asserting on it is stable). All of them come from the runtime in a
+// real session, so a test has to state them.
+const meta: TeamRunMeta = {
+  tick: 0,
+  locale: 'en',
+  teamId: 'team-1',
+  index: 0,
+  seed: 'test-seed',
+  runKind: 'session',
+  now: Date.UTC(2026, 0, 1),
+};
+// The participants on the team, taken when the operation started. Empty here;
+// add records to test logic that reads the roster.
+const participants: Participant[] = [];
+const callbacks = {} as Callbacks;
+
+// `defaultContext` and `defaultSettings` are generated beside the types, from
+// the very schemas they satisfy: the values a session opens with. Spread
+// them and name only what the case is about, and a capability added later
+// arrives here already populated rather than breaking every fixture. An
+// aggregate function receives them split: the shared store once, and each
+// team's own capabilities, so its fixtures use `defaultSharedContext` and
+// `defaultTeamContext`.
+const shared = { context: { ...defaultSharedContext } };
+
+describe('{{ identifier }}', () => {
+  describe('Init', () => {
+    it('should initialize each team context', async () => {
+      // TODO: override the capabilities this case is about
+      const context: Context = { ...defaultContext };
+      // TODO: override the settings this case is about
+      const settings: Settings = { ...defaultSettings };
+
+      const { capabilities } = await Init({ context, settings, meta, participants, callbacks });
+
+      // TODO: Add assertions for initialized values
+      expect(capabilities).toBeDefined();
+    });
+  });
+
+  describe('InitAggregate', () => {
+    it('should seed shared state across all teams', async () => {
+      const teams = [
+        {
+          teamId: 'team-1',
+          index: 0,
+          // TODO: override the capabilities this case is about
+          context: { ...defaultTeamContext } satisfies TeamContext,
+        },
+      ];
+      // TODO: override the settings this case is about
+      const settings: Settings = { ...defaultSettings };
+
+      const result = await InitAggregate({ shared, teams, settings, meta, participants, callbacks });
+
+      // TODO: Add assertions for shared and per-team values
+      expect(result.teams).toHaveLength(teams.length);
+    });
+  });
+
+  describe('RunAggregate', () => {
+    it('should update shared state on each tick', async () => {
+      const teams = [
+        {
+          teamId: 'team-1',
+          index: 0,
+          // TODO: override the capabilities this case is about
+          context: { ...defaultTeamContext } satisfies TeamContext,
+        },
+      ];
+      // TODO: override the settings this case is about
+      const settings: Settings = { ...defaultSettings };
+
+      const result = await RunAggregate({ shared, teams, settings, meta, participants, callbacks });
+
+      // TODO: Add assertions for shared and per-team values
+      expect(result.teams).toHaveLength(teams.length);
+    });
+  });
+});

package/dist/templates/engine/logic-aggregate.ts.liquid

@@ -0,0 +1,46 @@
+import { InitializationFunction, InitAggregateFunction, RunAggregateFunction } from '@seriousgaming/sdk';
+import type { Context, Settings, Callbacks, SharedContext, TeamContext } from './types';
+
+export const Init: InitializationFunction<Context, Settings, Callbacks> = async ({ context, settings, callbacks }) => {
+  // Initialise each team's context here. Return the capabilities it writes
+  // under `capabilities`: a patch, merged into the team's context. `Init` is
+  // optional: delete it and every team starts from the capabilities' defaults.
+  return {
+    capabilities: {
+      ...context
+    }
+  };
+};
+
+export const InitAggregate: InitAggregateFunction<TeamContext, SharedContext, Settings, Callbacks> = async ({ shared, teams, settings, callbacks }) => {
+  // Seed shared state from all teams' initial contexts here.
+  // `shared.context` is the session's shared store, once; each team's
+  // `context` holds only its own capabilities. Write shared capabilities under
+  // `shared.capabilities`, and each team's under its `teams` entry, in the
+  // same order as the input. A shared capability in a `teams` entry fails.
+  return {
+    shared: { capabilities: {} },
+    teams: teams.map((team) => ({
+      capabilities: {
+        ...team.context
+      }
+    }))
+  };
+};
+
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings, Callbacks> = async ({ shared, teams, settings, callbacks }) => {
+  // Run once across all teams each tick, reading the shared store from
+  // `shared.context` rather than from any one team
+  // Callbacks are narrowed by the engine's `uses` array. To call generateText
+  // or extractText, declare them in engine.sdk.json's `uses` field — the
+  // runtime throws on any callback that isn't declared. A declared one is
+  // always present, so call it directly, without `?.`.
+  return {
+    shared: { capabilities: {} },
+    teams: teams.map((team) => ({
+      capabilities: {
+        ...team.context
+      }
+    }))
+  };
+};

package/dist/templates/engine/logic.test.ts.liquid

@@ -0,0 +1,61 @@
+import type { Participant, TeamRunMeta } from '@seriousgaming/sdk';
+import { describe, it, expect } from 'vitest';
+
+import { defaultSettings, defaultContext } from './defaults';
+import { Init, Run } from './logic';
+import type { Context, Settings, Callbacks } from './types';
+
+// `teamId` and `index` name the team whose context a per-team call receives,
+// `seed` is the session's random seed (a fixed one here keeps an assertion on
+// derived randomness stable), `runKind` says whether this is the game being
+// played or a walkthrough beside it, and `now` is when the operation started
+// (fixed here, as `seed` is, so a test asserting on it is stable). All of them come from the runtime in a
+// real session, so a test has to state them.
+const meta: TeamRunMeta = {
+  tick: 0,
+  locale: 'en',
+  teamId: 'team-1',
+  index: 0,
+  seed: 'test-seed',
+  runKind: 'session',
+  now: Date.UTC(2026, 0, 1),
+};
+// The participants on the team, taken when the operation started. Empty here;
+// add records to test logic that reads the roster.
+const participants: Participant[] = [];
+const callbacks = {} as Callbacks;
+
+// `defaultContext` and `defaultSettings` are generated beside the types, from
+// the very schemas they satisfy: the values a session opens with. Spread
+// them and name only what the case is about, and a capability added later
+// arrives here already populated rather than breaking every fixture.
+
+describe('{{ identifier }}', () => {
+  describe('Init', () => {
+    it('should initialize context variables', async () => {
+      // TODO: override the capabilities this case is about
+      const context: Context = { ...defaultContext };
+      // TODO: override the settings this case is about
+      const settings: Settings = { ...defaultSettings };
+
+      const { capabilities } = await Init({ context, settings, meta, participants, callbacks });
+
+      // TODO: Add assertions for initialized values
+      expect(capabilities).toBeDefined();
+    });
+  });
+
+  describe('Run', () => {
+    it('should update context on each tick', async () => {
+      // TODO: override the capabilities this case is about
+      const context: Context = { ...defaultContext };
+      // TODO: override the settings this case is about
+      const settings: Settings = { ...defaultSettings };
+
+      const { capabilities } = await Run({ context, settings, meta, participants, callbacks });
+
+      // TODO: Add assertions for updated values
+      expect(capabilities).toBeDefined();
+    });
+  });
+});

package/dist/templates/engine/logic.ts.liquid

@@ -0,0 +1,32 @@
+import { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings, Callbacks } from './types';
+
+export const Init: InitializationFunction<Context, Settings, Callbacks> = async ({ context, settings, callbacks }) => {
+  // Initialise your engine here. Return the capabilities it writes under
+  // `capabilities`: a patch, merged into the team's context. `Init` is
+  // optional: delete it and every team starts from the capabilities' defaults.
+  //
+  // Memory only the engine needs between ticks can go under `state` beside
+  // `capabilities` instead of in a capability: no surface ever sees it, and
+  // undo rewinds it. Type it with the fourth parameter, for example
+  // `RunFunction<Context, Settings, Callbacks, EngineState>`, and `Run` receives
+  // it back as `state`.
+  return {
+    capabilities: {
+      ...context
+    }
+  };
+};
+
+export const Run: RunFunction<Context, Settings, Callbacks> = async ({ context, settings, callbacks }) => {
+  // Run your engine logic here
+  // Callbacks are narrowed by the engine's `uses` array. To call generateText
+  // or extractText, declare them in engine.sdk.json's `uses` field — the
+  // runtime throws on any callback that isn't declared. A declared one is
+  // always present, so call it directly, without `?.`.
+  return {
+    capabilities: {
+      ...context
+    }
+  };
+};

package/dist/templates/engine/run.json.liquid

@@ -0,0 +1,7 @@
+{
+  "blocks": {
+    "languageVersion": 0,
+    "blocks": []
+  },
+  "code": ""
+}

package/dist/templates/guide/01-at-a-glance.md.liquid

@@ -0,0 +1,19 @@
+# {{ name }} at a glance
+
+A one-page summary a facilitator can keep next to the laptop. Replace the placeholders with the real shape of your session.
+
+:::timing
+Total session length: about 90 minutes.
+:::
+
+| Phase | Duration | Facilitator focus |
+| --- | --- | --- |
+| Briefing | 15 minutes | Introduce the simulation and form teams |
+| Play | 60 minutes | Run ticks and coach teams between decisions |
+| Debrief | 15 minutes | Connect outcomes to the learning objectives |
+
+## Materials
+
+- One laptop or tablet per team
+- A room layout that lets teams talk without overhearing each other
+- This guide, printed or on a second screen

package/dist/templates/guide/02-preparation.md.liquid

@@ -0,0 +1,18 @@
+# Preparing for the session
+
+Everything to do before participants arrive.
+
+## Before the day
+
+- Read this guide end to end
+- Run the simulation once yourself so the decisions feel familiar
+- Decide team composition and prepare name cards if needed
+
+## On the day
+
+- Start the session and confirm every team device can reach it
+- Check the room layout gives each team space to confer
+
+:::note
+A facilitator new to this simulation should be able to run the session from this guide alone. If a step relies on knowledge that is only in your head, write it down here.
+:::