docs(01): capture phase context

.planning/phases/01-tournament-engine/01-CONTEXT.md

@@ -0,0 +1,137 @@
+# Phase 1: Tournament Engine - Context
+
+**Gathered:** 2026-03-01
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+A complete tournament runs from start to finish in an x86 LXC container with a working touch-friendly operator (TD) UI — demoable at a venue by pointing any device at the container. Go backend with embedded LibSQL, NATS JetStream, WebSocket hub. SvelteKit frontend embedded via go:embed. Covers: clock, blinds, financials, players, tables, seating, multi-tournament, and the full TD interface.
+
+Note: The operator throughout this system is the **Tournament Director (TD)** — use this term consistently.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Tournament Setup Flow
+- **Template-first creation** — TD picks from saved tournament templates, everything pre-fills, tweak what's needed for tonight, hit Start
+- **Templates are compositions of reusable building blocks** — a template is NOT a monolithic config. It references:
+  - Chip set (denominations, colors, values — venue-level)
+  - Blind structure (level progression, antes, breaks)
+  - Payout structure (tiered by entry count — see Payout Structure below)
+  - Buy-in config (entry cost, rake splits, rebuy/add-on rules)
+  - Points formula (league scoring — venue-level, reused across seasons)
+- **Local changes by default** — when creating a tournament from a template, the TD gets a copy. Edits only affect that tournament. To change the actual reusable block, go to template management
+- **Dedicated template management area** — create from scratch, duplicate/edit existing, save tournament config as new template
+- **Built-in starter templates** ship with the app (Turbo, Standard, Deep Stack, WSOP-style) so day one has something to pick from
+- **Structure wizard** lives in template management — input player count, starting chips, desired duration, denominations → generates a blind structure to save as a block
+- **Minimum player threshold** — configured in tournament metadata (typically 8-9), Start button unavailable until met
+- **Chip bonuses** — configurable per tournament: early signup bonus (before a date/time or first X players) and punctuality bonus (showed up on time)
+- **Late registration soft lock with admin override** — when cutoff hits, registration locks but admin can push through a late entry (logged in audit trail). Some tournaments have no late reg at all (registration closes at start)
+
+### Payout Structure
+- **Entry-count brackets with tiered prizes** — standalone reusable building block, example:
+  - 8–20 entries → 3 prizes (50% / 30% / 20%)
+  - 21–30 entries → 4 prizes (45% / 26% / 17% / 12%)
+  - 31–40 entries → 5 prizes (42% / 26% / 16% / 11% / 5%)
+  - 41–50 entries → 6 prizes (40% / 24% / 14% / 10% / 7% / 5%)
+- **Entry count = unique entries only** — not rebuys or add-ons
+- **Prize rounding** — all prizes round down to nearest venue-configured denomination (e.g. 50 DKK in Denmark, €5 elsewhere). No coins, no awkward change
+- **Bubble prize** — happens in ~70% of tournaments. When remaining players exceed paid positions (e.g. 8 left, 7 paid), all remaining players can unanimously agree to create a bubble prize:
+  - Typically around the buy-in amount
+  - Funded by shaving from top prizes (mostly 1st–3rd, sometimes 4th–5th)
+  - TD flow: "Add bubble prize" → set amount → system shows redistribution across top prizes → confirm
+  - Must be fast and intuitive — not buried in menus, this happens constantly
+
+### TD Workflow During Play
+- **Overview tab priority** (top to bottom):
+  1. Clock & current level (biggest element)
+  2. Time to next break
+  3. Player count (registered / remaining / busted)
+  4. Table balance status (are tables even or needs attention)
+  5. Financial summary (prize pool, entries, rebuys)
+  6. Recent activity feed (last few actions)
+- **Bust-out flow**: tap Bust → pick table → pick seat → system shows player name for verification → confirm → select hitman (mandatory in PKO tournaments, optional otherwise) → done
+- **PKO (Progressive Knockout)**: when template defines PKO, bounty transfer is part of the bust flow (half to hitman, half added to their own bounty, chain tracked)
+- **Buy-in flow**: search/select player → auto-seat suggests optimal seat → TD can override (accessibility needs, keep-apart situations like couples) → confirm → receipt
+- **Multi-tournament switching**: TD chooses tabs at top OR split view — phone likely tabs, tablet landscape could do split view
+- **Undo is critical** — bust-outs, rebuys, add-ons, buy-ins can all be undone with full re-ranking. Miscommunication between TD and dealers happens often
+
+### Seating & Balancing
+- **Oval table view (default)** — top-down view with numbered seats, player names in seats, empty seats visible. Switchable to list view for density (10+ table tournaments)
+- **Balancing is TD-driven, system-assisted**:
+  1. System alerts: tables are unbalanced
+  2. TD requests suggestion: system says "move 1 from Table 1 to Table 4"
+  3. TD announces to the floor, assistant facilitates
+  4. Assistant reports back: "Seat 3 to Seat 5" — TD taps two seat numbers, done (minimal touches)
+  5. Suggestion is **live and adaptive** — if Table 1 loses a player before the move happens (e.g. bust during ongoing hand), system recalculates or cancels
+- **Break Table is fully automatic** — system knows all open seats, distributes players evenly, TD just sees the result ("Player X → Table 1 Seat 4")
+- **No drag-and-drop in Phase 1** — tap-tap flow for all moves
+
+### End-Game & Payouts
+- **Flexible chop/deal support** — all remaining players participate in a deal, nobody leaves while others play on. Supported scenarios:
+  - ICM calculation (TD inputs chip stacks, system calculates each player's share)
+  - Custom split (players agree on % or fixed amount)
+  - Partial chop (split some money, play on for remaining + league points)
+  - Any number of players (not just heads-up — 4-way deals after 12 hours are real)
+- **Prize money and league positions are independent** — money can be chopped but positions still determined by play for points
+- **Tournament auto-closes** when one player remains — no manual "end tournament" button
+- **Receipts configurable per venue**: off / digital / print / both. Player and venue can always see tournament participation in the system regardless of receipt setting
+
+### Claude's Discretion
+- Loading skeleton and animation design
+- Exact spacing, typography, and component sizing
+- Error state handling and messaging
+- Toast notification behavior and timing
+- Activity feed formatting
+- Thermal printer receipt layout
+- Internal data structures and state management patterns
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- The bust-out flow must be as few taps as possible — TD is under time pressure during a running tournament
+- Balancing recording should be two taps (source seat, destination seat) after the system suggests table-to-table
+- Bubble prize creation needs to be fast and prominent — it happens in 70% of tournaments
+- "Add bubble prize" should be easily accessible, not buried in settings
+- Template building blocks should feel like LEGO — pick chip set, pick blind structure, pick payout table, name it, done
+- The system should adapt to the chaos of live poker — hands in progress during balancing, players busting mid-move, deals negotiated at 2am after 12 hours of play
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- No existing code — greenfield project
+
+### Established Patterns
+- No established patterns yet — Phase 1 sets the foundation
+
+### Integration Points
+- Go binary serves SvelteKit via go:embed
+- WebSocket hub for real-time state to all connected clients
+- LibSQL for local persistence
+- NATS JetStream for event durability
+- Catppuccin Mocha dark theme (UI-05)
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+- **Drag-and-drop seat moves** — UI polish, add after core tap-tap flow works (future Phase 1 enhancement or later)
+- **PWA seat move notifications** — when a player is moved (balancing or table break), notify them in the PWA with new table/seat — Phase 2
+- **"Keep apart" player marking** — TD marks players who shouldn't be at the same table (couples, etc.), auto-seating respects it — evaluate for Phase 1 or later
+- **Chip bonus for early signup/punctuality** — captured in decisions, evaluate complexity during planning
+
+</deferred>
+
+---
+
+*Phase: 01-tournament-engine*
+*Context gathered: 2026-03-01*