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

package/dist/docs/guides/guide.md

@@ -0,0 +1,123 @@
+# Facilitator guides
+
+A facilitator guide bundles the run-sheet for a simulation into the package itself: markdown chapters and images that the host renders natively on the facilitator's page. Bundling means guide content can never drift out of sync with the simulation version it ships with, and the facilitator manages everything from one place.
+
+Guides are content as data, not UI bundles: learning designers author markdown, the host renders it. A game holds one guide; a one-page cheat sheet is a chapter of it.
+
+## Resource shape
+
+```
+guide/
+├── guide.sdk.json
+├── content/
+│   ├── en/
+│   │   ├── 01-overview.md
+│   │   └── 02-running-the-game.md
+│   └── de/
+│       ├── 01-overview.md
+│       └── 02-running-the-game.md
+└── assets/
+    └── market-diagram.png
+```
+
+The bundle file declares a `locales` map; the per-locale `name` is the title the host renders:
+
+```json
+{
+    "definition": {
+        "locales": {
+            "en": { "name": "Facilitator guide" },
+            "de": { "name": "Moderationsleitfaden" }
+        }
+    },
+    "rootDirectory": "."
+}
+```
+
+## Content rules
+
+- Markdown files are chapters, ordered by file name. Number them (`01-`, `02-`, …) to control the order
+- File names are identical across locales; only the locale directory differs
+- Headings produce the nested table of contents: chapter titles (H1) plus H2 to H3. End a heading with `{-}` to omit it
+- Images use relative paths into the shared `assets/` directory (for example `../../assets/market-diagram.png` from a chapter). Localised images are simply different files referenced from each locale's markdown
+
+## Admonitions
+
+Six admonition types are available as container directives. The standard three:
+
+```markdown
+:::note
+A setup screen overrides these defaults.
+:::
+
+:::warning
+Do not reveal the demand curve before round two.
+:::
+
+:::tip
+Tie at least one in-game moment back to each learning objective.
+:::
+```
+
+And three facilitation-specific types, following the 'DO/SAY' labelling convention from facilitation practice:
+
+```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
+Keep this briefing under 10 minutes.
+:::
+```
+
+Unknown admonition types render as an inert error block so typos surface immediately.
+
+## Video embeds
+
+A video embed is a fenced code block with language `video`, validated against a closed provider registry (YouTube only in v1):
+
+````markdown
+```video
+provider: youtube
+id: dQw4w9WgXcQ
+```
+````
+
+The id must match YouTube's 11-character format. Unknown providers or malformed blocks render as an inert error block, never a passthrough. The dev server renders the embed from `youtube-nocookie.com` in a sandboxed iframe.
+
+## Rendering and safety
+
+The renderer is default-deny:
+
+- Raw HTML is escaped and shown as text, never executed
+- Link schemes are filtered; `javascript:` and friends are stripped
+- Relative references must stay inside the guide's own content and assets
+
+Stick to markdown, admonitions, and video blocks; anything else is treated as content, not markup.
+
+## Localisation
+
+The guide gets its own locale picker on the facilitator's page, defaulting to the session locale. It is guide-local: changing it never affects what participants see.
+
+Chapters fall back per file: a chapter missing from the selected locale is served from the reference locale ('en' when declared, otherwise the first declared locale) with a visible 'not yet translated' notice. Translate chapter by chapter and the guide stays usable throughout.
+
+`pnpm run sdk build --validate-only` warns when a declared locale is missing chapters present in the reference locale, and fails on malformed video blocks or unresolvable image references.
+
+## Printing
+
+The guide page carries a print stylesheet: the header, table of contents and pickers are hidden and the content fills the page, so cheat sheets can still live on paper next to the laptop. Use the print button on the guide page, or open `/guide` in its own tab and print from there.
+
+## Writing a guide worth shipping
+
+The scaffold (`pnpm run sdk new guide`) generates a recommended skeleton: a front-loaded at-a-glance summary and preparation checklist, then per-phase sections. The test of a good guide: could a facilitator new to this simulation run the session from this guide alone? If a step relies on knowledge that is only in the designer's head, write it down.
+
+## See also
+
+- [Create a Facilitator Guide](../recipes/create-guide.md) - step-by-step recipe
+- [Internationalisation](internationalization.md) - locale rules across the SDK
+- [Scenarios](scenarios.md) - the other data-only resource type

package/dist/docs/guides/hooks.md

@@ -0,0 +1,183 @@
+# Hooks
+
+A hook is logic that runs when the runtime emits a lifecycle signal, such as a participant joining a team. It runs outside the tick loop, after the runtime has applied the change, and can write the capabilities it declares.
+
+## The model
+
+The engine runs inside the tick loop: it takes a context, returns what it writes, and does so only when the loop ticks. That fits everything shaped like 'every tick, do X', but not what happens between ticks, such as a participant joining or a facilitator moving someone to another team. There is no tick boundary to bind engine logic to, so an engine either misses those events or has to poll for them.
+
+The runtime knows exactly when each lifecycle event happens, because it caused it. So it emits a signal, the hooks subscribed to that signal run, and their result is folded back into the game's context. Think of a hook as a reaction to a runtime announcement, the way the engine is a tick-time computation:
+
+- The runtime owns the signals, and decides when to emit them
+- A hook subscribes to exactly one signal, and the signal's payload is part of its type, so there is nothing to check at run time
+- A hook runs after the change has been applied. It can record, react to, or augment the change; it can never veto it
+- Several hooks on one signal run in directory-name order, each receiving the previous one's output, so the chain composes
+
+A hook fires on a signal the runtime emits, never on a condition you define over context. A condition over context is already expressible in the engine: check it at the start of `Run` and return early. What the engine cannot express is 'a participant joined the team', and hooks fill exactly that gap.
+
+### When to use a hook (versus the engine)
+
+- **Engine**: the work belongs in the tick loop. It runs every tick and depends on tick-level orchestration
+- **Hook**: the work is triggered by a lifecycle event with no tick correspondence, and needs to read or write game context. There is no notion of 'every tick' for a hook: it fires only when its signal does
+
+## Available signals
+
+| Signal            | Fires when                                                                                   | Payload                                                   |
+| ----------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `participantJoin` | A new participant record is created                                                          | `{ participant: { id, teamId, name, index, connected } }` |
+| `participantMove` | A facilitator reassigns a participant to another team. Dispatched **once per affected team** | `{ participant, fromTeamId, toTeamId, phase }`            |
+
+The `HookSignal` type lists every signal, and each hook's generated `types.ts` pins its own signal and payload.
+
+## Creating a hook
+
+This creates an `assignroles` hook, which gives each new participant a role. It reads and writes a `roles` capability whose `Assignments` map is keyed by participant id:
+
+```bash
+pnpm run sdk new hook '{
+  "definition": {
+    "identifier": "assignroles",
+    "signal": "participantJoin",
+    "reads": ["roles"],
+    "writes": ["roles"]
+  },
+  "logic": {
+    "directory": "logic",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+`identifier` names the directory the command creates; it is not written into `hook.sdk.json`, because a resource is named by its directory. Declare `reads` and `writes` here (or edit them in later): without them the hook is handed no `roles` at all, its generated `Context` is empty, and the logic below fails to type-check.
+
+This produces:
+
+```
+hooks/assignroles/
+├── hook.sdk.json     # Definition (signal, reads, writes, settings)
+├── logic/
+│   ├── logic.ts      # Run function
+│   └── logic.test.ts
+├── defaults.ts       # Generated: the starting context and settings, for tests
+└── types.ts          # Generated: pins the signal as a literal
+```
+
+### Wiring it to a game
+
+Nothing to do: a package declares whatever is on disk, and a game runs whatever its package declares, so the directory `pnpm run sdk new hook` created is the whole of the wiring.
+
+Where several hooks subscribe to the same signal, they run in directory-name order, so number the directories if the order matters.
+
+## Writing the logic
+
+The hook's logic is a single `Run` function in `logic/logic.ts`:
+
+```typescript
+import type { HookFunction } from '../types';
+
+export const Run: HookFunction = async ({ context, settings, callbacks, participant }) => {
+    const roles = context.roles?.Assignments ?? {};
+    return {
+        capabilities: {
+            ...context,
+            roles: {
+                Assignments: {
+                    ...roles,
+                    [participant.id]: 'observer',
+                },
+            },
+        },
+    };
+};
+```
+
+The signal-specific payload (here `participant`) is spread alongside the standard `context`, `settings`, `meta`, `participants` and `callbacks` fields. Each signal surfaces its own fields the same way.
+
+`participants` is the roster after the change the hook reports, a read-only copy taken when the dispatch started: the team's participants on a `participantJoin`, and every participant in the session on a `participantMove`, so the departure and the arrival read the same list. Read it rather than keeping a roster in context. The `assignroles` hook uses it to hand a newcomer the first role nobody still on the team holds:
+
+```typescript
+export const Run: HookFunction = async ({ context, settings, participant, participants }) => {
+    const existing = context.roles?.Assignments ?? {};
+    const held = new Set(
+        participants.filter((p) => p.id !== participant.id).map((p) => existing[p.id])
+    );
+    const role = settings.assignroles.Roles.find((candidate) => !held.has(candidate));
+    // ...
+};
+```
+
+`meta.now` is when the dispatch started, in milliseconds since the epoch. Use it rather than `Date.now()` to stamp a join.
+
+The generated `types.ts` pins the signal as a literal, so destructuring is type-safe without restating the signal:
+
+```typescript
+// hooks/assignroles/types.ts (auto-generated)
+import type { LogicCallbacks } from '@seriousgaming/sdk';
+export type Callbacks = LogicCallbacks;
+
+import type { HookFunction as SDKHookFunction } from '@seriousgaming/sdk';
+export type HookFunction = SDKHookFunction<'participantJoin', Context, Settings, Callbacks>;
+```
+
+## Reads and writes
+
+Hooks declare `reads` and `writes` exactly like the engine, and the same discipline applies: a hook may only read from capabilities listed under `reads`, and may only write to capabilities listed under `writes`. The generated `Context` type reflects only those capabilities.
+
+A hook removes a key the way the engine does, by naming its path in `deletes` beside `capabilities`. A `participantMove` hook clearing the departing participant's role, for example:
+
+```typescript
+return { capabilities: context, deletes: [['roles', 'Assignments', participant.id]] };
+```
+
+Each path must sit under a capability in the hook's `writes`. See [Removing a key](./engine.md#removing-a-key) for the rules.
+
+A hook that calls `generateText` or another gated callback lists it in `uses`, like any logic resource (see [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses)).
+
+## Order of operations
+
+For every signal, the runtime:
+
+1. Applies the lifecycle change (for example, adds a participant to the registry)
+2. Emits the signal
+3. Looks up the hooks subscribed to that signal in the current game
+4. Runs them in directory-name order, threading context through
+5. Persists the resulting context
+
+So for `participantJoin` the participant is in the registry by the time the hook runs, and it is safe to assume the joiner exists. Hooks can mutate context to record, react to, or augment the change; they cannot prevent it.
+
+### `participantMove` fires twice
+
+A move touches two teams, and a hook writes one team's context, so the signal is dispatched once against each: the source team with `phase: 'departure'`, then the destination with `phase: 'arrival'`. Departure completes and persists before arrival starts.
+
+Read `phase` rather than comparing ids. The change is already applied by the time either invocation runs, so `participant.teamId` reads as the destination on both and cannot tell them apart.
+
+There is no channel between the two invocations: whatever the departure hook returns is not visible to the arrival hook. A shared-state game can carry per-participant state across through the shared store; an independent-mode game re-derives it on arrival from the payload and its own configuration.
+
+The reason to reach for this signal is per-participant state, not the roster. `useUserInterfaceParticipants()` and the session UI's roster are pushed live and are accurate the instant a move lands, so a context-resident roster is a derived cache. What a move genuinely breaks is state your `participantJoin` hook seeded (a role, an allocation, a per-person ledger entry), which is otherwise stranded in the source team with nothing to re-seed it in the destination.
+
+## Settings
+
+A hook reads [settings](./settings.md) the way every other resource does: list the settings resources in the bundle's `settings`, and the hook receives exactly those as `settings`, keyed by identifier. Use them to parameterise hook behaviour without changing logic. They resolve through the same layers as the engine's, so a scenario or the facilitator's setup screen can change them.
+
+The `assignroles` hook can read its role list from a `settings/assignroles/` resource:
+
+```json
+{
+    "definition": {
+        "signal": "participantJoin",
+        "reads": ["roles"],
+        "writes": ["roles"],
+        "settings": ["assignroles"]
+    }
+}
+```
+
+```typescript
+const roles = settings.assignroles.Roles;
+```
+
+## Related
+
+- [Create a hook recipe](../recipes/create-hook.md): step-by-step scaffolding
+- [Engines guide](engine.md): for in-tick logic

package/dist/docs/guides/index.md

@@ -0,0 +1,51 @@
+# Guides
+
+Each guide is the one page for a resource kind or a topic: it explains the model, then serves as the reference, with every field, every option, and the rules behind them. For how the kinds fit together, see the [core concepts](../concepts/index.md); for a single task done step by step, see the [recipes](../recipes/index.md).
+
+## Start here
+
+- **[A tour of the starter game](./starter-game.md)**: every directory and file `new package` gives you, and which guide goes deeper
+- **[Common patterns](./patterns.md)**: inventory, revenue and multi-step engine patterns, with the commands and code for each
+
+## The game and its logic
+
+- **[Shaping games](./games.md)**: ticks, teams, locales, and the rest of `seriousgaming.sdk.json`
+- **[Creating capabilities](./capabilities.md)**: defining the game's state
+- **[Creating engines](./engine.md)**: the tick logic
+- **[Hooks](./hooks.md)**: logic that runs on lifecycle signals, such as a participant joining a team
+- **[Validators](./validators.md)**: server-side checks that reject a UI's mutation before it is applied
+- **[Endpoints](./endpoints.md)**: server-side handlers a surface or an agent calls by identifier, their scope, writes and actions, and how a UI reaches `generateText`
+- **[Tick controllers](./tick-controller.md)**: automatic tick timing and game completion
+- **[Multi-team games](./multi-team-games.md)**: shared capabilities, aggregate engines, and interaction modes
+- **[Scenarios](./scenarios.md)**: variants of a game, with settings overrides and static assets
+- **[Settings](./settings.md)**: read-only parameters, how scenarios and the session override them, and how to set them from the CLI
+- **[Type safety best practices](./type-safety.md)**: generated types, schemas, and avoiding `any`
+
+## User interfaces
+
+- **[Building user interfaces](./ui.md)**: the game UI each participant plays
+- **[Building session UIs](./session.md)**: the facilitator's whole-session screen
+- **[Building a setup screen](./setup.md)**: the short form a facilitator fills in at session creation
+- **[Building a scenario editor](./scenario-editor.md)**: the screen for authoring lasting scenarios, and when a game needs one
+- **[Building waiting room UIs](./waiting-room.md)**: the holding screen participants see while the session is held
+- **[Production security constraints](./production-constraints.md)**: the sandbox and content security policy your UIs run under in production
+- **[Internationalisation (i18n)](./internationalization.md)**: running a game in more than one language
+
+## Content, files, and AI
+
+- **[Facilitator guides](./guide.md)**: markdown facilitation content shown on the facilitator's page
+- **[Building presentations](./presentation.md)**: the facilitator's slide deck, its deck library, resume and export
+- **[File handling (assets and blobs)](./file-handling.md)**: uploading files from UIs, showing them, and reading them in logic
+- **[LLM integration guide](./llm-integration.md)**: generating text through the platform LLM API
+- **[Speech generation guide](./speech-generation.md)**: synthesising audio with `generateSpeech`
+- **[Structuring a game for AI facilitation](./ai-facilitation.md)**: what a facilitator's AI agent can see and do, and what to write down so it behaves
+
+## Testing
+
+- **[Testing](./testing.md)**: unit tests for the engine and component tests for UIs
+- **[Engine testing](./engine-testing.md)**: whole games played in-process with `createTestSession`, with no server
+
+## Set-up and upgrades
+
+- **[Global settings](./global-settings.md)**: API keys and defaults stored once for every project
+- **[Upgrading](./upgrading.md)**: the steps from 0.6 to 1.0

package/dist/docs/guides/internationalization.md

@@ -0,0 +1,288 @@
+# Internationalisation (i18n)
+
+This guide shows you how to add multi-language support to your games.
+
+## What you'll learn
+
+- How to add language support to games
+- How to localise user interfaces
+- How to use i18next in React components
+
+## Game localisation
+
+Add a language to a game by patching its manifest:
+
+```bash
+pnpm run sdk update package --patch '[
+  {"op": "replace", "path": "/supportedLocales", "value": ["en", "es", "fr"]},
+  {"op": "add", "path": "/locales/es", "value": {"name": "Simulación de negocios"}},
+  {"op": "add", "path": "/locales/fr", "value": {"name": "Simulation commerciale"}}
+]'
+```
+
+The `supportedLocales` array defines which languages the game supports. The `locales` object holds the game's name in each of them, and the name in the first supported locale is the package's name.
+
+Use `--patch` rather than a JSON definition here. A definition passed as an argument or with `--file` replaces the whole manifest, so anything it leaves out (`maxTicks`, `teams`, `waitingRoom` and the rest) is dropped. An RFC 6902 patch changes only the paths it names.
+
+## User interface localisation
+
+A user interface declares no localised name of its own: a game holds one, so
+nothing labels it, and `new ui` or `update ui` refuses a `locales` field. Its own
+strings live in `ui/src/i18n.ts` and are resolved against the locale the host
+sends. The same holds for the session, waiting room, setup and scenario editor
+screens.
+
+## React i18next integration
+
+New UIs come with i18next configured. Add translations to your UI:
+
+```typescript
+// src/i18n.ts
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+const resources = {
+    en: {
+        translation: {
+            hello: 'Hello',
+            greeting: 'Welcome to the dashboard',
+            revenue: 'Revenue',
+            sales: 'Sales',
+            stockLevel: 'Stock Level',
+        },
+    },
+    es: {
+        translation: {
+            hello: 'Hola',
+            greeting: 'Bienvenido al panel',
+            revenue: 'Ingresos',
+            sales: 'Ventas',
+            stockLevel: 'Nivel de Stock',
+        },
+    },
+    fr: {
+        translation: {
+            hello: 'Bonjour',
+            greeting: 'Bienvenue au tableau de bord',
+            revenue: 'Revenus',
+            sales: 'Ventes',
+            stockLevel: 'Niveau de Stock',
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en',
+    interpolation: { escapeValue: false },
+});
+
+export default i18n;
+```
+
+## Using translations in components
+
+Import the translation hook and use it:
+
+```typescript
+import { useTranslation } from 'react-i18next';
+import { useUserInterfaceLocale } from '@seriousgaming/sdk/ui';
+
+function Dashboard() {
+  const { t } = useTranslation();
+  const { locale } = useUserInterfaceLocale();
+
+  return (
+    <div>
+      <h1>{t('greeting')}</h1>
+      <p>Current locale: {locale}</p>
+      <table>
+        <tr>
+          <th>{t('revenue')}</th>
+          <th>{t('sales')}</th>
+          <th>{t('stockLevel')}</th>
+        </tr>
+      </table>
+    </div>
+  );
+}
+```
+
+The `useUserInterfaceLocale()` hook provides the current locale from the dev server.
+
+## Locale switching
+
+In the dev server, change the session language with the locale select in the console's dev drawer (press the backtick key), which lists the locales the game supports. It sets the one session-wide locale. When it changes:
+
+1. The dev server broadcasts the change to every open view and UI iframe
+2. The SDK wrapper sets the document root's `lang` and `dir` (`rtl` for Arabic, Hebrew, Persian, Urdu and other right-to-left scripts)
+3. i18next language changes
+4. Components re-render with new translations
+
+The choice holds for the rest of the session. No additional code is needed: just use `t()` in your components.
+
+## Localising scenario content
+
+The i18next setup above localises UI chrome: the buttons, labels, and other text that ships inside the user interface. Scenario-authored content is different. This is the prose a scenario carries but a UI renders: inbox documents, narrative emails, briefings, and transcripts. It needs its own approach.
+
+### Locale is session-wide
+
+A session runs in one locale, shared by every participant. The facilitator chooses it, the runtime broadcasts it to every connected surface, and it can change during a session. There is no per-participant locale, so two participants in the same session always see content in the same language.
+
+### Resolve scenario content in the user interface
+
+Keep the structural, locale-independent parts of your content (identifiers, ordering, triggers, and asset references) in context, where the engine needs them. Move the translatable prose into asset files under your scenario's `assets/` directory (or the package's `shared-assets/`), with each translation in a directory named for its locale beside the untranslated file:
+
+```
+assets/
+  content/
+    documents.json        ← the base language, and the fallback
+    ar/documents.json
+    it/documents.json
+```
+
+Read it with `useAsset`, which tries the surface's locale first (then its language, so `fr-CA` finds `fr/`) and falls back to the file as given:
+
+```typescript
+import { useAsset } from '@seriousgaming/sdk/ui';
+
+type Documents = Record<string, { subject: string; body: string }>;
+
+function useLocalisedDocuments() {
+    const { data } = useAsset<Documents>('asset:content/documents.json', { as: 'json' });
+    return data;
+}
+```
+
+The fallback is per file: a locale with its own copy reads only that copy. A game that wants a partial translation to fall back entry by entry reads both, the localised copy with `locale` set and the base with `locale: false`, and merges them itself.
+
+Because the UI already runs per participant and re-renders when the locale changes, content follows a mid-session locale switch for free.
+
+> Do not resolve scenario content in an engine at `Init` and write it into a capability. That bakes one language into the engine context and every tick snapshot, and it cannot follow a mid-session locale change. Scenario content resolves in the UI.
+
+### Generating localised prose in the engine
+
+The UI pattern works for prose that exists ahead of time. For prose an engine generates at runtime, for example a narrative summary produced by `callbacks.generateText`, there is no pre-written translation to look up. Logic functions can read the session locale and generate in that language:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, meta, callbacks }) => {
+    const summary = await callbacks.generateText(
+        `Write a one-paragraph board update in locale ${meta.locale}: ...`
+    );
+    return {
+        capabilities: {
+            ...context,
+            board: { Update: summary.content },
+        },
+    };
+};
+```
+
+Every logic function reads the locale as `meta.locale`: the engine, aggregate functions, tick controllers, hooks, endpoints, and validators alike.
+
+To test a locale headlessly, pass `--locale` when you initialise and tick a game:
+
+```bash
+pnpm run sdk init --locale ar
+pnpm run sdk tick --locale ar
+```
+
+## Organising translations
+
+For larger UIs, organise translations by feature:
+
+```typescript
+const resources = {
+  en: {
+    translation: {
+      "nav.dashboard": "Dashboard",
+      "nav.reports": "Reports",
+      "form.submit": "Submit",
+      "form.cancel": "Cancel",
+      "table.noData": "No data available"
+    }
+  },
+  es: {
+    translation: {
+      "nav.dashboard": "Panel de Control",
+      "nav.reports": "Informes",
+      "form.submit": "Enviar",
+      "form.cancel": "Cancelar",
+      "table.noData": "No hay datos disponibles"
+    }
+  }
+};
+
+// In components
+<button>{t('form.submit')}</button>
+<span>{t('table.noData')}</span>
+```
+
+## Formatting dates and numbers
+
+Use i18next formatting for locale-specific formatting:
+
+```typescript
+function SalesReport({ revenue, date }) {
+  const { i18n } = useTranslation();
+
+  const formattedRevenue = new Intl.NumberFormat(i18n.language, {
+    style: 'currency',
+    currency: 'USD'
+  }).format(revenue);
+
+  const formattedDate = new Intl.DateTimeFormat(i18n.language).format(date);
+
+  return (
+    <div>
+      <p>Revenue: {formattedRevenue}</p>
+      <p>Date: {formattedDate}</p>
+    </div>
+  );
+}
+```
+
+## Best practices
+
+1. **Complete translations** - Provide all languages for all strings
+    - ✅ Every English string has Spanish and French
+    - ❌ Missing translations in some languages
+
+2. **Consistent naming** - Use dot notation for related strings
+    - ✅ `"form.submit"`, `"form.cancel"`, `"form.error"`
+    - ❌ `"submitButton"`, `"cancelBtn"`, `"errorMessage"`
+
+3. **Use namespaces** - Organise large translation sets
+    - ✅ `"nav.home"`, `"dashboard.title"`, `"reports.nodata"`
+    - ❌ All strings in one flat object
+
+4. **Keep UI in sync** - Update translations when UI changes
+    - ✅ Add new keys to all languages immediately
+    - ❌ Forget to translate new features
+
+5. **Test all languages** - Switch locale in dev server to test
+    - ✅ Verify text displays correctly in each language
+    - ❌ Only test in English
+
+## CLI examples
+
+Make an English game multilingual, keeping every other manifest field:
+
+```bash
+pnpm run sdk update package --patch '[
+  {"op": "replace", "path": "/supportedLocales", "value": ["en", "de", "ja"]},
+  {"op": "add", "path": "/locales/de", "value": {"name": "Geschäftsspiel"}},
+  {"op": "add", "path": "/locales/ja", "value": {"name": "ビジネスゲーム"}}
+]'
+```
+
+Rename the game in one language:
+
+```bash
+pnpm run sdk update package --patch '[{"op": "replace", "path": "/locales/en/name", "value": "Business Game"}]'
+```
+
+## Next steps
+
+- [Building user interfaces](./ui.md) - Build localised UIs
+- [Terminology](../concepts/terminology.md) - The vocabulary these guides use