docs: Update architecture/UI docs and add new game mode template

- ARCHITECTURE.md: Updated deployment section with dual remotes,
added audio caching and preference persistence to perf table
- CONTEXT_UI.md: Added Discovered Context with actual file structure,
JS audio caching architecture, asset naming conventions, auto-hold
pattern, and sidebar rules documentation
- NEW_GAME_MODE_TEMPLATE.md: Comprehensive template for defining new
game modes — covers rules, scoring, tiers, audio, UI patterns, and
integration checklist with a worked Peasant's Gamble example

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -250,34 +250,40 @@ To reduce perceived latency:
 ## 7. Deployment Architecture
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                  Hugging Face Spaces                         │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │              Streamlit Application                     │  │
-│  │                 (Free Tier)                            │  │
-│  │  - Serves UI                                           │  │
-│  │  - Runs game engine                                    │  │
-│  │  - Connects to Supabase                                │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              │ HTTPS
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                       Supabase                               │
-│                     (Free Tier)                              │
-│  - PostgreSQL database                                       │
-│  - Realtime WebSocket channels                               │
-│  - Row Level Security                                        │
-│  - 500MB storage limit                                       │
-└─────────────────────────────────────────────────────────────┘
+┌──────────────────────────┐       ┌──────────────────────────┐
+│    GitHub (source)       │       │   Hugging Face Spaces    │
+│  origin/master           │       │   hf/main (live app)     │
+└──────────┬───────────────┘       └──────────┬───────────────┘
+           │  git push origin master           │  git push hf master:main
+           └───────────────┬───────────────────┘
+                           │
+              ┌────────────▼────────────────────┐
+              │     Streamlit Application        │
+              │  - Serves UI + game engine       │
+              │  - JS-cached audio system        │
+              │  - Connects to Supabase (HTTPS)  │
+              └────────────┬────────────────────┘
+                           │
+              ┌────────────▼────────────────────┐
+              │          Supabase               │
+              │  - PostgreSQL database           │
+              │  - Realtime WebSocket channels   │
+              │  - Row Level Security            │
+              └─────────────────────────────────┘
 ```
 
-### Environment Variables (Hugging Face Secrets)
+### Remotes
+
+| Remote | URL | Branch |
+|--------|-----|--------|
+| `origin` | `https://github.com/legomaheggoz-source/DevilsDozen.git` | `master` |
+| `hf` | `https://huggingface.co/spaces/legomaheggo/DevilsDozen` | push `master:main` |
+
+### Environment Variables (HF Spaces Secrets / `.env` locally)
 
 ```
 SUPABASE_URL=https://xxx.supabase.co
-SUPABASE_ANON_KEY=eyJxxx...
+SUPABASE_ANON_KEY=sb_publishable_xxx...
 ```
 
 ---
@@ -292,6 +298,8 @@ SUPABASE_ANON_KEY=eyJxxx...
 | Database round-trips | Batch updates where possible |
 | Realtime subscription limits | One channel per lobby |
 | Animation performance | CSS animations over JS |
+| Audio data re-send on rerun | JS Audio caching in `window.parent` — base64 sent once, then tiny control commands |
+| Widget prefs lost on `st.rerun()` | Non-widget session state keys (`_sfx_pref`, `_music_pref`, etc.) |
 
 ### Scaling Limits (Free Tier)
 

docs/CONTEXT_UI.md

@@ -328,6 +328,61 @@ streamlit run src/ui/app.py
 
 ## Discovered Context
 
-> This section is updated during implementation. Check here before starting work.
+> Updated Feb 2026 after full implementation and playtesting.
 
-[Empty until implementation begins]
+### Actual File Structure
+
+Pages live under `src/ui/views/` (not `src/ui/pages/`). Sound system is in `src/ui/themes/sounds.py`.
+
+| File | Purpose |
+|------|---------|
+| `src/ui/app.py` | Entrypoint — routing, sidebar rules, sound system init |
+| `src/ui/themes/sounds.py` | JS-cached audio system (SFX + music) |
+| `src/ui/themes/animations.py` | CSS/HTML animation helpers |
+| `src/ui/themes/medieval.css` | Full medieval theme CSS |
+| `src/ui/components/dice_tray.py` | Dice display with hold/reroll buttons |
+| `src/ui/components/scoreboard.py` | Player scores panel |
+| `src/ui/components/turn_controls.py` | Roll / Bank / End Turn buttons |
+| `src/ui/components/lobby.py` | Create / Join / Waiting room |
+| `src/ui/views/home.py` | Home + lobby waiting page |
+| `src/ui/views/game.py` | Main game loop with polling |
+| `src/ui/views/results.py` | Victory screen + standings |
+
+### Audio System Architecture
+
+The original approach injected base64 `<audio>` elements via `st.markdown` on every rerun, sending 5-8 MB per cycle. This was replaced with a JS-caching strategy:
+
+1. **First load per track**: base64 data sent via `st.components.v1.html(height=0)`, cached as `window.parent._dd_audio` JS Audio objects using **parent window's Audio constructor** (`new p.Audio(...)`) so objects survive iframe replacement.
+2. **Subsequent reruns**: Only tiny control commands (<1 KB) — play, pause, volume.
+3. **SFX**: Lazy-loaded on first trigger, cached as data URI strings in `window.parent._dd_audio.sfx`.
+4. **Preferences**: Stored in non-widget session state keys (`_sfx_pref`, `_music_pref`, `_sfx_volume`, `_music_volume`) that survive Streamlit's widget lifecycle cleanup during `st.rerun()`.
+
+### Audio Asset Naming Convention
+
+| Type | Key | Filename | Size |
+|------|-----|----------|------|
+| SFX | `dice_roll` | `dice_roll.mp3` | 45 KB |
+| SFX | `bust` | `bust.mp3` | 64 KB |
+| SFX | `bank` | `bank.mp3` | 46 KB |
+| SFX | `hot_dice` | `hot_dice.mp3` | 58 KB |
+| SFX | `victory` | `victory.mp3` | 327 KB |
+| SFX | `tier_advance` | `tier_advance.mp3` | 59 KB |
+| Music | `menu` | `menu_theme.mp3` | 4.3 MB |
+| Music | `peasants_gamble` | `d6_theme.mp3` | 6.5 MB |
+| Music | `alchemists_ascent` | `d20_theme.mp3` | 4.9 MB |
+
+To add new audio: add the file to `assets/sounds/`, add to `_SFX_FILES` or `_MUSIC_FILES` dict in `sounds.py`, and update `.gitattributes` LFS tracking if needed.
+
+### Auto-Hold Scoring Dice
+
+After rolling (D6 and D20 Tier 1), all scoring dice default to "Held". Players uncheck to release. This inverts the original opt-in pattern to opt-out. D20 Tier 2 reroll and Tier 3 auto-apply are unchanged. Implementation is in `_handle_roll()` in `game.py`.
+
+### Sidebar Game Rules
+
+When `page == "game"`, rules for the active game mode are rendered below audio controls in the sidebar. Rules text is defined as module-level constants `_D6_RULES` and `_D20_RULES` in `app.py`.
+
+### Run Command
+
+```bash
+python -m streamlit run src/ui/app.py
+```

docs/NEW_GAME_MODE_TEMPLATE.md

@@ -0,0 +1,278 @@
+# New Game Mode Template
+
+Use this template to define a new game mode for Devil's Dozen. Fill out each section, then open Claude Code and say:
+
+> "I want to add a new game mode to Devil's Dozen. Here is the completed template: [paste or reference this file]."
+
+Claude will use this template along with the existing `CONTEXT_*.md` docs to build the engine, wire up the UI, and add audio support.
+
+---
+
+## 1. Mode Identity
+
+| Field | Value |
+|-------|-------|
+| **Display Name** | _(e.g., "Pirate's Plunder")_ |
+| **Internal Key** | _(e.g., `pirates_plunder` — lowercase, underscores, used in code + DB)_ |
+| **Dice Type** | _(e.g., D6 / D10 / D12 / D20 / mixed)_ |
+| **Number of Dice** | _(e.g., 5)_ |
+| **Min Players** | _(e.g., 2)_ |
+| **Max Players** | _(e.g., 4)_ |
+| **Target Score / Win Condition** | _(e.g., "First to 5,000 points" or "Survive 10 rounds")_ |
+| **Configurable Win Conditions?** | _(e.g., "Yes — 3000 / 5000 / 10000" or "No — fixed at 250")_ |
+
+---
+
+## 2. Turn Structure
+
+Describe what happens on a single player's turn from start to finish.
+
+```
+Example (Peasant's Gamble):
+1. Player rolls all 6 D6 dice
+2. Must hold at least one scoring die
+3. Can choose to roll remaining dice or bank
+4. If no scoring dice on a roll → BUST (lose all unbanked turn points)
+5. If all dice score → HOT DICE (roll all 6 fresh, keep accumulated points)
+6. Bank ends the turn and adds turn score to total
+```
+
+**Your turn structure:**
+```
+1. ...
+2. ...
+3. ...
+```
+
+---
+
+## 3. Scoring Rules
+
+### 3.1 Basic Scoring
+
+List every scoring combination, its point value, and which dice participate.
+
+| Combo | Points | Example |
+|-------|--------|---------|
+| _(e.g., Single 1)_ | _(e.g., 100)_ | _(e.g., rolling a 1 among other dice)_ |
+| _(e.g., Three of a kind)_ | _(e.g., face value x 100)_ | _(e.g., three 4s = 400)_ |
+
+### 3.2 Special Combos (if any)
+
+| Combo | Points | Notes |
+|-------|--------|-------|
+| _(e.g., Straight 1-6)_ | _(e.g., 1500)_ | _(e.g., must be all 6 dice)_ |
+
+### 3.3 Bust Condition
+
+When does the player bust? _(e.g., "No scoring dice on a roll" / "Rolling a 1" / "Never busts")_
+
+### 3.4 Hot Dice / Re-roll Condition (if any)
+
+When does the player get to re-roll all dice fresh? _(e.g., "All dice are scoring" / "Not applicable")_
+
+---
+
+## 4. Tiers / Phases (if applicable)
+
+Does the game have tiers, phases, or stages that change the rules as the player progresses?
+
+If **no tiers**: Write "Single phase — rules are constant throughout."
+
+If **yes**:
+
+| Tier | Name | Score Range | Dice Count | Rule Changes |
+|------|------|-------------|------------|-------------|
+| 1 | _(e.g., Red)_ | _(e.g., 0-100)_ | _(e.g., 8)_ | _(e.g., Standard scoring)_ |
+| 2 | _(e.g., Green)_ | _(e.g., 101-200)_ | _(e.g., 3)_ | _(e.g., Score x5, per-die reroll)_ |
+
+---
+
+## 5. Special Mechanics
+
+Describe any unique mechanics not covered above:
+
+- _(e.g., "Kingmaker: Rolling a 20 in Tier 3 gives 20 points to last-place player")_
+- _(e.g., "Steal: Rolling triples lets you steal 50 points from another player")_
+- _(e.g., "Curse: Rolling snake eyes resets your score to zero")_
+
+If none: Write "No special mechanics."
+
+---
+
+## 6. Player-Facing Rules Summary
+
+Write a concise version of the rules as you'd want players to see it in the sidebar during gameplay. Use markdown. Aim for <=20 lines. This will be displayed directly in the app.
+
+```markdown
+**Goal:** ...
+
+**Rolling:**
+- ...
+- ...
+
+**Scoring:**
+| Combo | Points |
+|---|---|
+| ... | ... |
+```
+
+---
+
+## 7. Audio
+
+### 7.1 Background Music
+
+Provide or describe the background music track for this mode.
+
+| Field | Value |
+|-------|-------|
+| **Filename** | _(e.g., `pirates_theme.mp3` — place in `assets/sounds/`)_ |
+| **Music dict key** | _(must match the internal key from Section 1, e.g., `pirates_plunder`)_ |
+| **Vibe / Description** | _(e.g., "Upbeat tavern shanty with fiddle and accordion")_ |
+| **Provided?** | _(Yes — file attached / No — generate or find one)_ |
+
+### 7.2 New Sound Effects (if any)
+
+List any NEW SFX this mode needs beyond the existing set. Existing SFX that can be reused:
+
+| Existing SFX | Trigger |
+|---|---|
+| `dice_roll` | On any dice roll |
+| `bust` | On bust |
+| `bank` | On banking score |
+| `hot_dice` | On hot dice / re-roll all |
+| `victory` | On game win |
+| `tier_advance` | On tier/phase change |
+
+**New SFX needed:**
+
+| SFX Name | Filename | Trigger | Description |
+|----------|----------|---------|-------------|
+| _(e.g., `steal`)_ | _(e.g., `steal.mp3`)_ | _(e.g., "When player steals points")_ | _(e.g., "Coin clinking sound")_ |
+
+If none: Write "No new SFX — reusing existing set."
+
+---
+
+## 8. UI Considerations
+
+### 8.1 Dice Display
+
+How should the dice look? _(e.g., "Same as D6 but with pirate skull on 1" / "Standard D20 with tier colors" / "Custom D10 faces")_
+
+### 8.2 Hold / Interaction Pattern
+
+Which pattern should this mode use?
+
+- [ ] **Auto-hold scoring** (like current D6/D20 Tier 1) — scoring dice default to held, player unchecks to release
+- [ ] **Per-die reroll** (like D20 Tier 2) — each die has a Reroll button
+- [ ] **Auto-apply** (like D20 Tier 3) — roll result is applied automatically, no player choice
+- [ ] **Other** — describe: _____________
+
+### 8.3 Special UI Elements
+
+Any special animations, indicators, or displays needed?
+
+- _(e.g., "Show a 'steal target' selector when triples are rolled")_
+- _(e.g., "Tier indicator like Alchemist's Ascent")_
+- _(e.g., "Round counter at the top")_
+
+If none: Write "Standard UI — no special elements."
+
+---
+
+## 9. Integration Checklist
+
+_Claude will handle these, but this is the work involved for reference:_
+
+### Engine (`src/engine/`)
+- [ ] New engine class (e.g., `pirates_plunder.py`) with `roll_dice()`, `calculate_score()`, bust/hot-dice logic
+- [ ] Scoring result dataclass with `points`, `is_bust`, `scoring_dice_indices`, `breakdown`
+- [ ] Unit tests covering all scoring combos, edge cases, bust, and hot dice
+
+### Database
+- [ ] Add mode key to `game_mode` column allowed values
+- [ ] Any new `game_state` columns? _(e.g., "round_number" / "steal_target")_
+
+### UI
+- [ ] Add to home page mode selector
+- [ ] Wire into `game.py` roll/hold/bank handlers
+- [ ] Add scoring indices helper in `game.py`
+- [ ] Add rules text to `app.py` (`_XX_RULES` constant + sidebar render)
+- [ ] Add background music entry to `_MUSIC_FILES` in `sounds.py`
+- [ ] Add any new SFX entries to `_SFX_FILES` in `sounds.py`
+- [ ] Add win condition options if configurable
+
+### Assets
+- [ ] Background music file in `assets/sounds/`
+- [ ] Any new SFX files in `assets/sounds/`
+- [ ] Update `.gitattributes` for LFS tracking if new MP3s added
+
+---
+
+## 10. Example: Filling This Out for Peasant's Gamble
+
+<details>
+<summary>Click to expand worked example</summary>
+
+### 1. Mode Identity
+
+| Field | Value |
+|-------|-------|
+| **Display Name** | Peasant's Gamble |
+| **Internal Key** | `peasants_gamble` |
+| **Dice Type** | D6 |
+| **Number of Dice** | 6 |
+| **Min/Max Players** | 2–4 |
+| **Target Score** | First to target score |
+| **Configurable?** | Yes — 3,000 / 5,000 / 10,000 |
+
+### 2. Turn Structure
+
+```
+1. Roll all 6 dice
+2. Must hold at least one scoring die
+3. Roll remaining dice or bank turn score
+4. No scoring dice = BUST (lose turn score)
+5. All dice score = HOT DICE (roll all 6 fresh)
+6. Bank adds turn score to total, ends turn
+```
+
+### 3. Scoring Rules
+
+| Combo | Points |
+|---|---|
+| Single 1 | 100 |
+| Single 5 | 50 |
+| Three 1s | 1,000 |
+| Three 2s–6s | Face x 100 |
+| Four+ of a kind | Previous tier x 2 |
+| 1-2-3-4-5 | 500 |
+| 2-3-4-5-6 | 750 |
+| 1-2-3-4-5-6 | 1,500 |
+
+**Bust:** No scoring dice on a roll.
+**Hot Dice:** All 6 dice are scoring.
+
+### 4. Tiers
+
+Single phase — rules are constant throughout.
+
+### 7. Audio
+
+| Field | Value |
+|-------|-------|
+| **Filename** | `d6_theme.mp3` |
+| **Music key** | `peasants_gamble` |
+| **Vibe** | Medieval tavern with lute and drums |
+| **Provided?** | Yes |
+
+No new SFX — reusing existing set.
+
+### 8. UI
+
+- Auto-hold scoring dice
+- No special elements beyond standard dice tray + scoreboard
+
+</details>