openup: EA model preparation (COD) - checklist, scripts, realizations intermediate

Per design-wi-2-architecture-cleanup.md §11.b/c: keyfob-station pipeline
studied (add-wi19-uc11.ps1, export-model-json.ps1). Platform gap: EA COM
pipeline is Windows-only; this session ran on Linux (no EABase.eapx found,
no pwsh) - .eapx skeleton NOT committed, documented in model/README.md
with the two path options. Landed:
- docs/openup/model/BUILD-CHECKLIST.md: full EA-session checklist
  (packages, 3 actors, 12 UCs with scenarios, 13 associations, 12
  realization packages / 36 elements) derived from use-case-model.md +
  uc-realization-mapping.md
- docs/openup/model/README.md: platform note, status, drift rule
- docs/openup/model/exports/uc-realizations.json: generated from mapping
  §2 via scripts/openup/markdown-to-json.py (tested locally)
- scripts/openup/build-model.ps1, export-model.ps1: adapted from keyfob
  patterns, Windows-gated (human gate per design §11.d)
- scripts/openup/markdown-to-json.py: local markdown -> JSON transform

docs/openup/model/BUILD-CHECKLIST.md

@@ -0,0 +1,203 @@
+# Skara Brae — EA Model Build Checklist (WI-2)
+
+Version 1.0 (2026-10-03) · Prepared by COD per `design-wi-2-architecture-cleanup.md` §11.b.4.
+Sources (authoritative, do not deviate): `docs/openup/requirements/use-case-model.md`,
+`docs/openup/analysis-design/uc-realization-mapping.md` (§1 tree, §2 realization table),
+`docs/openup/requirements/supplementary-specifications.md`, design note §3 (boundary rules).
+Drift rule: markdown and model must agree; a mismatch is a defect fixed in the same cycle.
+
+This checklist is written to be clicked through in EA **or** executed via
+`scripts/openup/build-model.ps1` (then verified below). The per-discipline element lists
+are complete: nothing outside them belongs in the WI-2 model.
+
+---
+
+## 0. Prerequisites (Windows machine — see model/README.md for why not Linux)
+
+1. skara-brae-common checked out (branch `wi-2-openup-docs` or later).
+2. EA installed and licensed. Copy the EA installation's empty-model template to the
+   model home:
+   `C:\Program Files\Sparx Systems\EA\EABase.eapx` → `docs/openup/model/skara-brae.eapx`
+   (exact install path may differ; the file is the standard empty `.eapx` template.
+   Do **not** derive the skeleton from keyfob-station's model — it carries keyfob content).
+3. PowerShell 5.1+ (built into Windows) for the script path.
+
+## 1. Model root
+
+- Rename the default model root to **`Skara Brae`** (keyfob equivalent: single model root).
+
+---
+
+## 2. Requirements discipline
+
+### 2.1 Package `Requirements`
+
+Create package **`Requirements`** directly under the model root.
+
+### 2.2 Package `Requirements / Vision`
+
+- Notes: purpose statement source = `docs/openup/requirements/vision.md` (the markdown is
+  the human-facing source; the model carries the product purpose in the package notes and
+  links, not a full copy).
+
+### 2.3 Package `Requirements / Use Case Model`
+
+**Actors (exactly 3)** — type `Actor`, notes verbatim from the Actors table:
+
+| Actor | Notes |
+|---|---|
+| `Player` | Authenticated user owning one or more characters (JWT role `player`). |
+| `Administrator` | Player with elevated rights (`role = admin`); may view any user's and any character's resources read-only. |
+| `Guest` | Unauthenticated caller; only register/login are open. |
+
+**Use cases (exactly 12)** — type `UseCase`, names verbatim:
+
+`UC-01 Register Account`, `UC-02 Authenticate`, `UC-03 Manage Characters`,
+`UC-04 Browse Game Catalogue`, `UC-05 Train Stat`, `UC-06 Manage Equipment`,
+`UC-07 Trade at Shop`, `UC-08 Run Adventure`, `UC-09 Heal at Temple`,
+`UC-10 Practice Bard Song`, `UC-11 Study Magic`, `UC-12 Level Up at Review Board`.
+
+Element notes: the UC's precondition line(s) verbatim from `use-case-model.md`; plus:
+- UC-05 note appends: *includes Regenerate Resources.*
+- UC-08 note appends: *includes Regenerate Resources, Resolve Combat. Exception: encounter
+  references an unknown enemy → 500 (post WI-2; previously a panic). WI-2 design driver
+  (`sb_core::adventure` extraction).*
+- Include targets are **sub-flows, not use case elements** (only 12 UCs exist) — model the
+  includes in the notes, **not** as `«include»` connectors.
+
+**Associations (exactly 13)** — type `Association`, Actor → UseCase:
+
+| Actor | Use cases |
+|---|---|
+| `Guest` | UC-01, UC-02 |
+| `Player` | UC-03, UC-04, UC-05, UC-06, UC-07, UC-08, UC-09, UC-10, UC-11, UC-12 |
+| `Administrator` | UC-03 (read-only) |
+
+**Scenarios** — stored on each use case (`Scenarios` collection), types are EA's
+`Basic Path` / `Alternate` / `Exception`. Naming and structuring rules used below
+(also implemented in `build-model.ps1`):
+- Markdown "Main success scenario" → scenario **Main Success Scenario** (`Basic Path`);
+  its numbered list items become ordered **steps**, each step's **Actor** = the leading
+  grammatical subject of the step text (`Player`/`Guest` → that actor; otherwise `System`).
+- Markdown "**Scenario (x):**" block → scenario named **x** (`Alternate`); prose text goes
+  into the scenario notes verbatim.
+- Markdown "**Alternate flows:**" prose → one scenario **Alternate flows** (`Alternate`),
+  prose verbatim in notes.
+- Markdown "**Exception:**" prose → scenario **Exception** (`Exception`), prose verbatim.
+- Precondition text rides on the scenario notes of the Main Success Scenario.
+- UC-11 has no labeled main scenario in the markdown; its first listed scenario
+  (view spellbook) serves as the Basic Path, the remaining "Scenario (x)" blocks as
+  `Alternate`.
+- Parenthetical actor remarks on a step text (e.g. UC-03 step 1 "(Admin may act for any
+  user)") move to the scenario notes to keep the step actionable; the wording is kept.
+
+| UC | Scenario (type) | Steps (Actor: text) / Notes |
+|---|---|---|
+| UC-01 | Main Success Scenario (Basic Path) | Guest: Guest submits name (3–32 chars) and password (≥ 6 chars). · System: System verifies the name is unused → 409 CONFLICT if taken. · System: System hashes the password (argon2), assigns the `player` role and the next id, persists the user. · System: System issues a JWT (HS256, `player` role) and returns `{token, user_id, name, role}`. |
+| UC-01 | Alternate flows (Alternate) | Notes: name length invalid → 400; password too short → 400; name taken → 409; hashing/token failure → 500. |
+| UC-02 | Main Success Scenario (Basic Path) | Guest: Guest submits name and password. · System: System finds the user (401 if unknown) and verifies the password hash (401 on mismatch). · System: System issues a JWT carrying the user's real role (`admin`/`player`) and returns `{token, user_id, name, role}`. |
+| UC-02 | Alternate flows (Alternate) | Notes: unknown name or wrong password → 401 UNAUTHORIZED; token creation failure → 500. |
+| UC-03 | Main Success Scenario (create) (Basic Path) | Notes: Admin may act for any user. · Player: Player submits character name, race, class for their user id. · System: System validates the target user exists (404) and the trimmed name is 1–32 chars (400). · System: System rolls stats (d6+5 base 6–16 per stat ± race modifiers), computes max HP/energy/nerve from class, grants starting gold (50) and level-1 class spells to casters. · System: System assigns the next character id, stores and persists the character; returns it fully. |
+| UC-03 | list/view (Alternate) | Notes: Player lists their characters (Admin: any user's); the system applies Regenerate Resources to each returned character and returns them. Viewing one character applies regen then returns it. |
+| UC-03 | Alternate flows (Alternate) | Notes: foreign user/character without admin role → 403 FORBIDDEN; user/character not found → 404; invalid name → 400. |
+| UC-04 | Main Success Scenario (Basic Path) | Player: Player requests the catalogue: races, classes, items (optional type/quality/slot filters), enemies, or adventure zones. · System: System returns static game data loaded from `skara-brae-common` JSON (class info is enriched with `is_caster`). |
+| UC-04 | Alternate flows (Alternate) | Notes: single item by unknown id → 404; filters may return an empty list (not an error). |
+| UC-05 | Main Success Scenario (Basic Path) | Notes: Precondition: character exists and caller may act on it. · Player: Player selects a training ground (strength / dexterity / constitution / intelligence / luck) and submits the stat name. · System: System applies Regenerate Resources. · System: System checks energy ≥ 1 and gold ≥ training cost (cost grows ~1.3× per 10 stat points). · System: System deducts 1 energy and the gold cost, increments the stat; constitution training recomputes max HP (current HP clamped). · System: System persists and returns `{success, message, character}`. |
+| UC-05 | Alternate flows (Alternate) | Notes: foreign character → 403; character not found → 404; not enough energy → 422; not enough gold → 422; unknown stat name → 400. |
+| UC-06 | Main Success Scenario (equip) (Basic Path) | Player: Player submits an item id from their inventory. · System: System moves the item from inventory to its slot; a previously equipped item in that slot returns to inventory. · System: System persists and returns the updated character. |
+| UC-06 | unequip (Alternate) | Notes: Player submits a slot name; the system moves the equipped item back to inventory. |
+| UC-06 | Alternate flows (Alternate) | Notes: foreign character → 403; character/item not found → 404; item not in inventory → 400; nothing equipped in slot → 400. |
+| UC-07 | Main Success Scenario (buy) (Basic Path) | Player: Player views the shop: always-stocked items plus rotating stock (with quantities) alongside their inventory. · Player: Player submits `buy` + item id. · System: System checks gold ≥ price (422), and for non-always-in-stock items decrements the limited stock (410 GONE if 0). · System: System deducts gold, adds the item to inventory, persists character and stock; returns `{success, message, gold}`. |
+| UC-07 | sell (Alternate) | Notes: Player submits `sell` + item id; system removes the first matching inventory item, pays half the item value, increments shop stock for non-permanent items. |
+| UC-07 | Alternate flows (Alternate) | Notes: unknown action or item not owned (sell) → 400; item not found → 404; insufficient gold → 422; stock exhausted → 410. |
+| UC-08 | Main Success Scenario (Basic Path) | Notes: Precondition: character exists and caller may act on it. · Player: Player requests an adventure for a zone (default `skara_brae_streets`). · System: System validates the zone (404) and applies Regenerate Resources. · System: System refuses incapacitated characters (HP ≤ 0 → 400) and characters with nerve below the zone cost (422); otherwise deducts the nerve cost. · System: System draws one enemy from the zone's weighted encounter table. · System: System resolves turn-based combat: open-ended d100 attack rolls, OB vs DB, RoleMaster crit tables with level-gap damage caps, active bard song effects, active spell damage/heal per round. · System: On player victory: XP and gold per the enemy definition, character HP set to the last round's defender HP, and loot dropped per-item chance rolls (only items existing in the catalogue). · System: On defeat: character HP set to 0; no rewards. · System: Spell-point upkeep is charged whenever a spell was active, win or lose. · System: System persists the character and returns `{zone, enemy, combat_log, loot}` (loot = item display names). |
+| UC-08 | Alternate flows (Alternate) | Notes: foreign character → 403; character/zone not found → 404; incapacitated → 400; insufficient nerve → 422. |
+| UC-08 | Exception (Exception) | Notes: encounter references an unknown enemy (data error) → 500 (post WI-2; previously a panic). |
+| UC-09 | Main Success Scenario (Basic Path) | Player: Player requests healing, optionally `partial`. · System: System computes missing HP; full heals all, partial heals half (rounded up); cost = amount healed, minimum 1 gold. · System: System checks gold (422), deducts it, restores HP, persists; returns `{hp, max_hp, gold, healed: true}`. |
+| UC-09 | Alternate flows (Alternate) | Notes: foreign character → 403; not found → 404; already at full HP → 400; insufficient gold → 422. |
+| UC-10 | Main Success Scenario (Basic Path) | Notes: Precondition: character class is Bard. · Player: Player views available songs (level-gated, with combat effect descriptions) and the active song. · Player: Player submits a song id; system validates level requirement (422) and sets it active; returns `{success, message, active_song}`. |
+| UC-10 | clear (Alternate) | Notes: submitting no song id clears the active song. |
+| UC-10 | Alternate flows (Alternate) | Notes: non-Bard → 403; unknown song → 404; level too low → 422; foreign character → 403; not found → 404. |
+| UC-11 | Main Success Scenario (view spellbook) (Basic Path) | Notes: Precondition: character belongs to a caster class (Mage→magician, Wizard, Conjurer, Sorcerer). Spell level = (character level / 3) + 1 — uncapped by code (level 100 → spell level 34); learn requests are validated to 1–7. · Player: Player requests their spellbook: caster class, current spell level, spell points, spells up to the achievable level (each marked known), and the learn-cost table for levels 2–7. |
+| UC-11 | learn spell level (Alternate) | Player: Player submits a spell level (1–7). · System: System validates caster class (403), level range (400), level not above the character's current spell level (422), gold ≥ learn cost (422), and that new spells exist (400). · System: System deducts gold, adds all unknown spell ids of that level, recomputes and refills max spell points; returns `{learned_count, spell_points, max_spell_points, gold}`. |
+| UC-11 | activate/clear active spell (Alternate) | Player: Player submits a spell id (or empty to clear). · System: System validates the spell is known (403), exists (404), and spell points suffice (422); deducts the spell's points and sets it active; returns `{active_spell, spell_points}`. |
+| UC-12 | Main Success Scenario (Basic Path) | Player: Player requests a level-up. · System: System validates: below max level 100, XP ≥ 18·100·(level)² for the next level (i.e. `xp_for_level(next)`), gold ≥ 500·next level. · System: System deducts the gold cost, increments the level, recomputes and fully restores HP/energy/nerve and max spell points; persists; returns `{success, message, character}`. |
+| UC-12 | Alternate flows (Alternate) | Notes: all of already at max level; not enough XP; not enough gold → 422. Foreign character → 403; not found → 404. |
+
+**Diagram** `Skara Brae Use Case Overview` (type `UseCase`): place all 3 actors (left
+column) and all 12 use cases (right grid).
+
+### 2.4 Package `Requirements / Supplementary Specifications`
+
+- One child element per top-level section of `requirements/supplementary-specifications.md`,
+  type `Requirement`, name = `SS-<n> <section title>` with the section's content in notes:
+  `1. Performance / Scalability`, `2. Reliability / Correctness`,
+  `3. Quality Gates (per-commit acceptance)`, `4. Data`, `5. Security`,
+  `6. Constraints`, `7. Usability / API`.
+- `Trace` connectors from each `SS-n` element to the use cases the section names
+  (the spec text cites the UCs; when it names none, leave untraced rather than guessing).
+
+---
+
+## 3. Analysis-Design discipline
+
+### 3.1 Package `Analysis-Design`
+
+Create package **`Analysis-Design`** under the model root (mapping §1 name — note:
+keyfob uses `Analysis & Design`; here the mapping document says `Analysis-Design` —
+follow the mapping).
+
+### 3.2 Package `Analysis-Design / Architecture Overview`
+
+- Notes: the dependency rule verbatim from `uc-realization-mapping.md` §2
+  ("all controllers/entities above live in `sb-core`/`sb-shared` …; the single current
+  violations (ShopService, HealingService, parts of MagicService in sb-api) are recorded
+  as debt … stale docs are defects") + design note §3 boundary rules.
+- Three cross-cutting elements (type `Class`, notes from the mapping's cross-cutting
+  paragraph):
+  1. `DomainError` — notes: `sb-core::error::DomainError` + `sb-api::routes::domain_status`
+     (status mapping table, design note §4.1) realize the error paths of UC-05/06/08/12.
+  2. `Constants` — notes: `sb-core::constants` realizes NFR "no magic numbers".
+  3. `Responses` — notes: `sb-api::routes::responses` realizes NFR-19 (wire-format freeze).
+
+### 3.3 Twelve realization packages
+
+For **each** entry in `docs/openup/model/exports/uc-realizations.json`
+(generated from mapping §2 — 12 packages, 36 elements):
+
+1. Package `UC-<NN> Realization` under `Analysis-Design`.
+2. Inside it, one `Collaboration` element named like the package, with a `Realization`
+   connector (Collaboration → the use case element in `Requirements / Use Case Model`).
+3. Inside it, one `Class` element per mapping row:
+   - Name = analysis class (e.g. `AdventureService`).
+   - Stereotype = `controller` / `entity` / `boundary` (mapping §2 column).
+   - Notes = the mapping's *Design element* cell verbatim, plus the *Notes* cell
+     (e.g. `` `sb-core::adventure::run_adventure` (**new, WI-2**) + `services::pick_enemy`
+     → `Result` (WI-2) — takes injected rng; `DomainError` (WI-2)``).
+4. One class diagram per realization package (name = package name), all its classes placed.
+
+Element counts for verification: UC-01:3, UC-02:2, UC-03:4, UC-04:2, UC-05:3, UC-06:3,
+UC-07:3, UC-08:5, UC-09:2, UC-10:3, UC-11:3, UC-12:3 — total 36.
+
+---
+
+## 4. Verification (design §11.d)
+
+1. Model opens clean (no missing-package errors).
+2. `Requirements → Use Case Model` shows exactly 3 actors + 12 use cases; every UC carries
+   its Main Success Scenario plus the alternates/exceptions from the table above, with
+   per-step actors.
+3. Spot-check two scenarios against `requirements/use-case-model.md` (recommended: UC-08
+   MSS — 9 steps, and UC-11 learn spell level — 3 steps).
+4. 12 `UC-N Realization` packages exist under `Analysis-Design` with the element counts
+   above; spot-check the UC-08 realization table against `uc-realization-mapping.md` §2.
+5. Association count is 13; there are no `«include»` connectors (includes live in UC notes).
+
+## 5. Export + commit (design §11.d.4–5)
+
+1. Run `scripts/openup/export-model.ps1` → regenerates
+   `docs/openup/model/exports/use-case-model.json`, `uc-realizations.json` and an XMI
+   backup; confirm the diff is expected (`uc-realizations.json` must be unchanged in
+   content — it was generated from the mapping markdown).
+2. Save the model; commit `.eapx` + `exports/` + `scripts/openup/` together as one commit
+   `openup: EA model WI-2 baseline` in **skara-brae-common**.

docs/openup/model/README.md

@@ -0,0 +1,37 @@
+# docs/openup/model/ — EA Model Home (WI-2 status)
+
+Per `design-wi-2-architecture-cleanup.md` §11 (decision reversal 2026-10-03): the binary
+EA model lives here at `skara-brae.eapx` with generated exports under `exports/`; generator
+scripts live in `scripts/openup/` (repo root). Markdown stays the content source of truth;
+exports are generated, never hand-edited.
+
+## Status after COD session 2 (2026-10-03, Linux agent)
+
+| Design item (§11.b/c) | Status |
+|---|---|
+| §11.b.1 clone keyfob-station read-only | done — studied `add-wi19-uc11.ps1` (scenario embedding: `Name/Type/Notes/Steps` arrays with per-step `Actor`) and `export-model-json.ps1` (COM walk → JSON); patterns reused in the scripts below |
+| §11.b.3 `.eapx` skeleton from EA's `EABase.eapx` | **not done — platform gap.** No `EABase.eapx` exists on this Linux machine (searched `~`, `~/.wine`, `/mnt`, `/media`, `/opt`, `/usr/local`); EA is a Win32 application. The binary is deliberately NOT committed and NOT derived from keyfob's model (it carries keyfob content). Copy it during the Windows session (see BUILD-CHECKLIST §0). |
+| §11.b.4 build checklist | done — `BUILD-CHECKLIST.md` (packages, actors, use cases, scenarios, associations, realization packages — complete and clickable) |
+| §11.c `build-model.ps1` / `export-model.ps1` | committed, adapted from the keyfob patterns; **Windows-gated** — this machine has no EA COM automation (and no `pwsh`), so they could not be executed here. They are prepared, not proven. |
+| §11.c machine-readable intermediates | `exports/uc-realizations.json` generated (by `scripts/openup/markdown-to-json.py`, tested locally) from mapping §2 — 12 realizations, 36 elements. `exports/use-case-model.json` is **not** generated here: the markdown carries no per-step actor tags, so a faithful JSON intermediate cannot be produced mechanically. Per §11.c's recorded fallback, `build-model.ps1` embeds the scenario content as PowerShell arrays (keyfob pattern); the human gate verifies it against `use-case-model.md` via the checklist. |
+
+## Linux constraint and the two options
+
+The EA pipeline is PowerShell + COM automation (`New-Object -ComObject EA.App`) against a
+`.eapx` (MS Access/Jet) file — Windows-only. This session ran on Linux. Options:
+
+1. **Run the pipeline on the Windows/EA machine (planned path).** `BUILD-CHECKLIST.md`
+   §0–§5 is the session script: copy `EABase.eapx` → `skara-brae.eapx`, run
+   `build-model.ps1`, verify per checklist §4, run `export-model.ps1`, commit
+   `.eapx` + `exports/` + `scripts/openup/` as `openup: EA model WI-2 baseline`.
+2. **EA manual XML export → agent-side transform.** If the COM scripts hit friction in EA,
+   export the package manually from the EA UI (`Publish → XML / XMI`), drop the file into
+   `exports/`, and the agent side can transform/validate it into the JSON intermediates
+   with a small local script (same role as `markdown-to-json.py`). The committed scripts
+   remain the reproducible path of record.
+
+## Drift rule
+
+Markdown (`use-case-model.md`, `uc-realization-mapping.md`) and the model must agree;
+exports are generated; a mismatch is a defect fixed in the same cycle (stale docs are
+defects). The human gate (design §11.d) owns `.eapx` editing/verification — never the agent.

docs/openup/model/exports/uc-realizations.json

@@ -0,0 +1,295 @@
+{
+  "exportedFrom": "docs/openup/analysis-design/uc-realization-mapping.md §2, generated by scripts/openup/markdown-to-json.py — generated file, never hand-edit",
+  "realizations": [
+    {
+      "id": "UC-01 Realization",
+      "elements": [
+        {
+          "name": "AccountRegistry",
+          "stereotype": "controller",
+          "designElement": "`sb-api::routes::{register, seed_users}`",
+          "notes": "argon2 hash via `sb-auth::hash`; JWT via `sb-auth::jwt`"
+        },
+        {
+          "name": "UserAccount",
+          "stereotype": "entity",
+          "designElement": "`sb-shared::user::User`, `Role`",
+          "notes": "persisted via `sb-db::Database`"
+        },
+        {
+          "name": "AuthBoundary",
+          "stereotype": "boundary",
+          "designElement": "`POST /api/auth/register`, `AuthResponse`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Register Account"
+    },
+    {
+      "id": "UC-02 Realization",
+      "elements": [
+        {
+          "name": "Authenticator",
+          "stereotype": "controller",
+          "designElement": "`sb-api::routes::login`, `sb-auth::{hash::verify_password, jwt::create_token}`",
+          "notes": ""
+        },
+        {
+          "name": "TokenService",
+          "stereotype": "boundary",
+          "designElement": "`POST /api/auth/login`, `AuthResponse`, `middleware::auth::auth_middleware`",
+          "notes": "middleware guards all UC-03…12"
+        }
+      ],
+      "useCase": "Authenticate"
+    },
+    {
+      "id": "UC-03 Realization",
+      "elements": [
+        {
+          "name": "CharacterFactory",
+          "stereotype": "controller",
+          "designElement": "`sb-core::character::create_character`",
+          "notes": "takes injected rng (WI-1)"
+        },
+        {
+          "name": "Character",
+          "stereotype": "entity",
+          "designElement": "`sb-shared::character::Character` (+ `Race`, `Class`, `CharacterStats`)",
+          "notes": ""
+        },
+        {
+          "name": "CharacterCatalog",
+          "stereotype": "boundary",
+          "designElement": "`GET/POST /api/users/{id}/characters`, `GET /api/characters/{id}`",
+          "notes": "store: `AppState.characters`"
+        },
+        {
+          "name": "ResourceRegenerator",
+          "stereotype": "entity",
+          "designElement": "`sb-core::character::apply_regen` (+ regen constants — WI-2 names them)",
+          "notes": "included sub-flow"
+        }
+      ],
+      "useCase": "Manage Characters"
+    },
+    {
+      "id": "UC-04 Realization",
+      "elements": [
+        {
+          "name": "CatalogueBrowser",
+          "stereotype": "boundary",
+          "designElement": "`GET /api/{races,classes,items,enemies,adventures}`; response types `sb-shared::responses`",
+          "notes": "data from `sb-common` JSON via `sb-core::{character::RACES/CLASSES, data, items}`"
+        },
+        {
+          "name": "GameData",
+          "stereotype": "entity",
+          "designElement": "`sb-core::data::{EnemyDef, ZoneDef, EncounterEntry, LootDrop}`, `items::load_all_items`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Browse Game Catalogue"
+    },
+    {
+      "id": "UC-05 Realization",
+      "elements": [
+        {
+          "name": "TrainingService",
+          "stereotype": "controller",
+          "designElement": "`sb-core::services::train_stat`",
+          "notes": "error type `DomainError` (WI-2)"
+        },
+        {
+          "name": "TrainingGrounds",
+          "stereotype": "entity",
+          "designElement": "`sb-core::character::TRAINING_GROUNDS`, `training_cost` (+ cost constants WI-2)",
+          "notes": ""
+        },
+        {
+          "name": "GymBoundary",
+          "stereotype": "boundary",
+          "designElement": "`GET/POST /api/characters/{id}/gym`, `GymResponse`, `TrainStatResponse`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Train Stat"
+    },
+    {
+      "id": "UC-06 Realization",
+      "elements": [
+        {
+          "name": "EquipmentService",
+          "stereotype": "controller",
+          "designElement": "`sb-core::services::{equip_item, unequip_item}`",
+          "notes": "`DomainError` (WI-2)"
+        },
+        {
+          "name": "Equipment/Inventory",
+          "stereotype": "entity",
+          "designElement": "`Character.equipment` / `.inventory`, `sb-shared::item::Item`",
+          "notes": ""
+        },
+        {
+          "name": "EquipmentBoundary",
+          "stereotype": "boundary",
+          "designElement": "`POST /api/characters/{id}/{equip,unequip}`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Manage Equipment"
+    },
+    {
+      "id": "UC-07 Realization",
+      "elements": [
+        {
+          "name": "ShopService",
+          "stereotype": "controller",
+          "designElement": "`sb-api::routes::{shop_action, buy_item, sell_item}` (handler-side; extraction candidate, design note Q3)",
+          "notes": "prices: `sb-core::items::{item_price, item_sell_price}`"
+        },
+        {
+          "name": "ShopStock",
+          "stereotype": "entity",
+          "designElement": "`AppState.shop_stock`",
+          "notes": "persisted via `sb-db`"
+        },
+        {
+          "name": "ShopBoundary",
+          "stereotype": "boundary",
+          "designElement": "`GET/POST /api/characters/{id}/shop`, `ShopResponse`, `ShopActionResponse`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Trade at Shop"
+    },
+    {
+      "id": "UC-08 Realization",
+      "elements": [
+        {
+          "name": "AdventureService",
+          "stereotype": "controller",
+          "designElement": "`sb-core::adventure::run_adventure` (**new, WI-2**) + `services::pick_enemy` → `Result` (WI-2)",
+          "notes": "takes injected rng; `DomainError` (WI-2)"
+        },
+        {
+          "name": "CombatEngine",
+          "stereotype": "entity",
+          "designElement": "`sb-core::combat::{resolve_combat_full, resolve_attack, crit tables, open_ended_roll}` + combat constants (WI-2)",
+          "notes": ""
+        },
+        {
+          "name": "Combatant",
+          "stereotype": "entity",
+          "designElement": "`sb-core::combat::CombatStats`",
+          "notes": "built from Character/EnemyDef"
+        },
+        {
+          "name": "SpellEffect / BardSong",
+          "stereotype": "entity",
+          "designElement": "`sb-core::combat::SpellEffect`, `sb-core::spells`, `sb-core::songs`",
+          "notes": ""
+        },
+        {
+          "name": "AdventureBoundary",
+          "stereotype": "boundary",
+          "designElement": "`GET /api/characters/{id}/adventure`; `AdventureRunResponse` (**new, WI-2**), `sb-shared::responses::CombatLog`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Run Adventure"
+    },
+    {
+      "id": "UC-09 Realization",
+      "elements": [
+        {
+          "name": "HealingService",
+          "stereotype": "controller",
+          "designElement": "`sb-api::routes::heal_character` (handler-side; extraction candidate, Q3)",
+          "notes": ""
+        },
+        {
+          "name": "TempleBoundary",
+          "stereotype": "boundary",
+          "designElement": "`POST /api/characters/{id}/heal`; `HealResponse` (**new, WI-2**)",
+          "notes": ""
+        }
+      ],
+      "useCase": "Heal at Temple"
+    },
+    {
+      "id": "UC-10 Realization",
+      "elements": [
+        {
+          "name": "SongService",
+          "stereotype": "controller",
+          "designElement": "`sb-api::routes::set_song`; `sb-core::songs::available_songs`",
+          "notes": ""
+        },
+        {
+          "name": "BardSong",
+          "stereotype": "entity",
+          "designElement": "`sb-core::songs::BARD_SONGS`, `Character.active_song`",
+          "notes": ""
+        },
+        {
+          "name": "SongBoundary",
+          "stereotype": "boundary",
+          "designElement": "`GET/POST /api/characters/{id}/songs`, `SongsResponse`, `SetSongResponse`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Practice Bard Song"
+    },
+    {
+      "id": "UC-11 Realization",
+      "elements": [
+        {
+          "name": "MagicService",
+          "stereotype": "controller",
+          "designElement": "`sb-api::routes::{get_spells, learn_spell_level}`; `sb-core::spells::{spells_for_class, spell_learn_cost, max_spell_points, caster_spell_level (WI-2)}`",
+          "notes": ""
+        },
+        {
+          "name": "Spell",
+          "stereotype": "entity",
+          "designElement": "`sb-core::spells::SpellDef`, `Character.{known_spells, active_spell, spell_points}`",
+          "notes": ""
+        },
+        {
+          "name": "MagicBoundary",
+          "stereotype": "boundary",
+          "designElement": "`GET/POST /api/characters/{id}/spells`; `SpellbookResponse`, `LearnSpellResponse` (**new, WI-2**)",
+          "notes": ""
+        }
+      ],
+      "useCase": "Study Magic"
+    },
+    {
+      "id": "UC-12 Realization",
+      "elements": [
+        {
+          "name": "ReviewBoard",
+          "stereotype": "controller",
+          "designElement": "`sb-core::character::level_up`",
+          "notes": "`DomainError` (WI-2)"
+        },
+        {
+          "name": "Progression",
+          "stereotype": "entity",
+          "designElement": "`sb-core::character::{xp_for_level, level_up_cost, MAX_LEVEL}` (+ curve constants WI-2)",
+          "notes": ""
+        },
+        {
+          "name": "ReviewBoundary",
+          "stereotype": "boundary",
+          "designElement": "`POST /api/characters/{id}/level-up`, `LevelUpResponse`",
+          "notes": ""
+        }
+      ],
+      "useCase": "Level Up at Review Board"
+    }
+  ],
+  "crossCutting": "Cross-cutting design elements (WI-2): `sb-core::error::DomainError` + `sb-api::routes::domain_status` (status mapping table, design note §4.1) realize the error paths of UC-05/06/08/12; `sb-core::constants` realizes NFR \"no magic numbers\"; `sb-api::routes::responses` realizes NFR-19 (wire-format freeze).",
+  "dependencyRule": "Dependency rule check (Clean Architecture): all controllers/entities above live in `sb-core`/`sb-shared` (domain side, no HTTP imports); all boundaries live in `sb-api`; the single current violations (ShopService, HealingService, parts of MagicService in sb-api) are recorded as debt with a follow-up question — the model must not paper over them (stale docs are defects)."
+}