docs: add README with project overview, architecture, and getting started

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

.gitignore

@@ -0,0 +1,28 @@
+# Binary
+cmd/leaf/leaf
+
+# Data directory
+data/
+
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Frontend (SvelteKit build output managed separately)
+frontend/node_modules/
+frontend/.svelte-kit/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

.planning/PROJECT.md

@@ -0,0 +1,139 @@
+# Felt — The Operating System for Poker Venues
+
+## What This Is
+
+Felt is an all-in-one poker venue operating system built on a resilient edge-cloud architecture. An ARM64 SBC "Leaf Node" runs the venue autonomously with NVMe storage. Ultra-cheap wireless display nodes replace HDMI cables. Players interact via their phones (PWA). A cloud Core layer handles cross-venue leagues, player profiles, public scheduling, and remote access. Everything flows through a self-hosted Netbird WireGuard mesh — network agnostic, zero-config, encrypted end-to-end.
+
+The product targets poker venues of all sizes — from a 3-table Copenhagen bar to a 40-table casino floor — replacing fragmented tools (TDD, whiteboards, spreadsheets, Blind Valet, BravoPokerLive) with one integrated platform.
+
+## Core Value
+
+A venue can run a complete tournament offline on a €100 device with wireless displays and player mobile access — and it just works, on any network, with zero IT involvement.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+**Phase 1 (Development Focus): Live Tournament Management**
+- [ ] Platform-level player identity (players belong to Felt, not venues — UUID profiles span all venues, tournament history/stats/league standings are portable, data travels with the player if a venue leaves Felt; this is the core network effect and must be in the data model from day one)
+- [ ] Virtual Leaf architecture (same Go codebase runs as physical Leaf on ARM64 SBC or as virtual Leaf instance on Core cloud infrastructure for free-tier venues; free tier gets full tournament engine requiring only internet)
+- [ ] Full tournament clock engine (countdown, blinds, antes, levels, breaks, chip-ups, pause/resume)
+- [ ] Financial engine (buy-ins, rebuys, add-ons, bounties, payouts, prize pool calculation, rake — all int64 cents, never float64)
+- [ ] Player management (database, registration, bust-out tracking, chip counts, action history)
+- [ ] Table & seating (configurable layouts, random seating, auto-balancing, table breaks, drag-and-drop moves)
+- [ ] Multi-tournament support (run multiple tournaments simultaneously)
+- [ ] League & season management (configurable point formulas, standings, archives)
+- [ ] Regional tournament organizer (free-tier feature — anyone can create cross-venue tournaments/leagues, automatic result aggregation across venues, unified leaderboards, finals management; this is the viral adoption mechanism that hooks venues from outside)
+- [ ] Wireless display system (node registry, view assignment, tournament clock/rankings/seating/schedule views)
+- [ ] Digital signage (info screens, event promos, drink specials, sponsor ads, playlists, auto-scheduling)
+- [ ] WYSIWYG content editor with AI assist (template gallery, AI-generated promo cards/imagery, venue branding)
+- [ ] Player mobile PWA (QR code access, live clock, blinds, rankings, personal stats, league standings)
+- [ ] Player access via Netbird reverse proxy (public HTTPS → WireGuard → Leaf, same URL from anywhere)
+- [ ] Custom domain support (venues point CNAME to felt subdomain, Netbird handles TLS termination and routing automatically, felt subdomain as fallback — zero IT complexity for professional venue presence)
+- [ ] Events engine (triggers, conditions, actions — sounds, messages, view changes, webhooks)
+- [ ] Export (CSV, JSON, HTML)
+- [ ] NATS-based sync (Leaf → Core, queued offline, replayed on reconnect)
+- [ ] Operator UI (mobile-first, touch-native, dark-room ready, TDD-depth with modern UX)
+- [ ] Authentication (PIN login offline, OIDC via Authentik when online, operator roles)
+- [ ] TDD data import (blind structures, player database, tournament history, leagues, payout structures — this is the primary competitive weapon for adoption, not just a feature; zero data loss migration makes TDD obsolete on day one)
+
+**Phase 2 (Development Focus): Cash Game Operations**
+- [ ] Waitlist management (by game type and stakes, display integration, notifications)
+- [ ] Table management (open/close, game types, stakes, seat tracking, status board)
+- [ ] Game type registry (all poker variants, configurable stakes, betting structures)
+- [ ] Session tracking (player sessions, buy-in/cashout, duration, history)
+- [ ] Rake tracking (percentage/time/flat, per-table reporting, financial analytics)
+- [ ] Must-move tables (automated progression, main game priority)
+- [ ] Seat change requests (queue tracking, notification on availability)
+- [ ] Table transfers (cross-table moves within sessions)
+- [ ] Player alerts (waitlist position, seat available, preferred game opened)
+
+**Phase 3 (Development Focus): Complete Venue Platform**
+- [ ] Dealer management (scheduling, skill profiles, shift trading, clock-in/out, rotation) — dealer profiles are platform-level identity like players: work history, verified skills, and shift records belong to the dealer's Felt profile and are portable across venues
+- [ ] Player loyalty system (points engine, tier system, rewards catalog, automated promos, cross-venue loyalty for multi-venue operators)
+- [ ] Private venues & memberships (privacy modes, invite codes, member tiers, guest system)
+- [ ] Venue analytics & reporting (revenue dashboards, player analytics, operational analytics, multi-venue benchmarking)
+- [ ] Public venue presence (venue profile page, online event registration, schedule publishing, SEO-optimized)
+
+**Phase 4 (Development Focus): Native Apps & Platform Maturity**
+- [ ] Native player app (iOS + Android — push notifications, Wallet integration, social features)
+- [ ] Native venue management app (iOS + Android — push alerts, biometric auth, background sync)
+- [ ] Social features (private groups, activity feed, achievements, friend-based venue discovery)
+
+### Out of Scope
+
+- Online poker / real-money gambling — Felt is a management tool, not a gambling platform
+- Payment processing — tracks amounts, doesn't process transactions
+- Video streaming / live poker broadcast — not in the product vision
+- BYO hardware — Felt ships pre-configured, locked-down devices only
+- Third-party cloud dependencies (Cloudflare, AWS, etc.) — self-hosted everything
+
+## Context
+
+**Technical Environment:**
+- Leaf Node: ARM64 SBC (Orange Pi 5 Plus reference board, ~€100) with NVMe storage
+- Display Node: Raspberry Pi Zero 2 W (~€20) running Chromium kiosk
+- Core: Hetzner dedicated server running Proxmox VE with LXC containers
+- Backend: Go (shared codebase for Leaf and Core, different builds)
+- Frontend: SvelteKit (operator UI, player PWA, admin dashboard)
+- Database: LibSQL on Leaf (embedded SQLite), PostgreSQL on Core
+- Message Queue: NATS JetStream (embedded on Leaf, clustered on Core)
+- Identity: Authentik (self-hosted OIDC IdP)
+- Networking: Netbird (WireGuard mesh, reverse proxy, DNS, SSH, firewall policies)
+
+**Design Philosophy:** "TDD's brain, Linear's face." — Match The Tournament Director's depth and power while looking and feeling like a modern premium product. Dark-room ready, touch-native, glanceable, information-dense without clutter.
+
+**Color System:** Catppuccin Mocha-based dark theme (default), with Catppuccin Latte light alternative. Typography: Inter (UI) + JetBrains Mono (data/timers). Poker-specific accents (felt green, card white, bounty pink, prize yellow).
+
+**Competition:**
+- The Tournament Director (TDD): Feature-rich but Windows-only, 2002-era UI, no mobile/cloud/wireless
+- Blind Valet: Simple cloud timer, dead without internet
+- Poker Atlas: Discovery only, zero operational tooling
+- BravoPokerLive: US waitlist app, no tournaments, no displays
+
+**Business Model:**
+- Free tier: Full tournament engine on virtual Leaf in cloud (requires internet, ~€0.45/mo infra cost per venue)
+- Offline tier (€25/mo): Dedicated Leaf hardware + wireless display nodes + offline operation + custom domain + remote admin. Leaf hardware (~€120) free with 12-month annual plan
+- Pro tier (€100/mo = €25 offline + €75 features): Everything in Offline + cash games + dealer scheduling + loyalty + memberships + analytics + TDD import + priority support
+- Casino Starter (€249/mo): Independent casino, 1 poker room, 5-15 tables
+- Casino Pro (€499/mo per property): Small chain, 2-5 properties, 15-40 tables each
+- Casino Enterprise (€999+/mo custom): Large operators, 5+ properties, 40+ tables
+- Display nodes: Sold at cost + shipping (~€30 each), no recurring fee — stateless render devices
+- Hardware: No BYO. Felt hardware only — pre-configured, encrypted, secure boot
+
+**User's Development Phases vs. GSD Planning Phases:**
+The user's spec describes 4 product development phases (Tournament → Cash Games → Full Venue → Native Apps). These are the user's product focus areas, not to be confused with GSD's planning phases which break down the work within those development phases.
+
+## Constraints
+
+- **Hardware:** Must run on ARM64 SBC with 4GB+ RAM, NVMe storage. Display nodes on Pi Zero 2 W (512MB RAM)
+- **Offline-first:** Entire tournament operation must work without internet. Cloud is never a dependency during operation
+- **Network agnostic:** Must work on any internet connection via Netbird WireGuard mesh. No firewall config, no port forwarding
+- **Self-hosted:** No third-party MITM. Self-hosted Netbird, Authentik, Core. Full stack ownership
+- **Security:** LUKS encryption at rest, WireGuard in transit, RLS multi-tenancy, GDPR compliance, audit trail on all state changes
+- **Performance:** State changes propagate to all clients within 100ms via WebSocket. Display views readable from 10+ feet
+- **Solo developer initially:** Architecture must be manageable for a single developer to build and maintain
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Go for backend (Leaf + Core) | Single binary, ARM cross-compile, goroutine concurrency, excellent stdlib | — Pending |
+| SvelteKit for all frontends | Shared codebase, PWA support, SSR for public pages, SPA for operator | — Pending |
+| LibSQL over plain SQLite on Leaf | SQLite-compatible with replication support, better concurrent writes | — Pending |
+| NATS JetStream for sync | Runs on Pi (~10MB RAM), persistent queuing, survives offline, ordered replay | — Pending |
+| Netbird as infrastructure backbone | WireGuard mesh + reverse proxy + DNS + SSH + firewall in one self-hosted platform | — Pending |
+| Authentik as IdP | Self-hosted, OIDC for Netbird + Felt, lightweight (~200MB RAM), Apache 2.0 | — Pending |
+| Catppuccin Mocha color system | Dark-room optimized, established palette, systematic accent colors | — Pending |
+| Platform-level player & dealer identity | Players AND dealers belong to Felt, not venues — portable profiles, cross-venue history, network effects, platform lock-in | — Pending |
+| Virtual Leaf for free tier | Same codebase runs on physical SBC or as cloud instance — enables free tier without hardware | — Pending |
+| No BYO hardware | Security, reliability, support consistency, controlled full chain | — Pending |
+| Free tier with virtual Leaf | Full tournament engine for free, costs ~€0.45/mo per venue, drives adoption flywheel | — Pending |
+| Proxmox VE for Core hosting | LXC + KVM, web management, PBS backup integration, scales by adding nodes | — Pending |
+
+---
+*Last updated: 2026-02-28 after initialization + gap review (platform identity, virtual Leaf, regional organizer, custom domains, business model details, dealer portability)*

.planning/REQUIREMENTS.md

@@ -0,0 +1,446 @@
+# Requirements: Felt
+
+**Defined:** 2026-02-28
+**Core Value:** A venue can run a complete tournament offline on a €100 device with wireless displays and player mobile access — and it just works, on any network, with zero IT involvement.
+
+## v1 Requirements
+
+Requirements for Phase 1 (Development Focus: Live Tournament Management). Each maps to roadmap phases.
+
+### Platform Identity
+
+- [ ] **PLAT-01**: Players have platform-level Felt profiles (UUID, cross-venue, portable) — not tied to any single venue
+- [ ] **PLAT-02**: Player profile stores name, nickname, photo, email, phone, notes, custom fields
+- [ ] **PLAT-03**: Player tournament history, stats, and league standings are cross-venue and travel with the player
+- [ ] **PLAT-04**: Player can control public visibility of their profile data
+- [ ] **PLAT-05**: Player can request full data export (GDPR right to portability) in JSON
+- [ ] **PLAT-06**: Player deletion cascades: anonymize tournament entries (keep aggregate stats), remove PII, propagate via NATS
+
+### Architecture & Infrastructure
+
+- [x] **ARCH-01**: Leaf Node runs as single Go binary on ARM64 SBC with embedded LibSQL, NATS JetStream, and WebSocket hub
+- [ ] **ARCH-02**: Virtual Leaf runs same Go codebase on Core cloud infrastructure for free-tier venues (requires internet)
+- [x] **ARCH-03**: All financial values stored as int64 cents — never float64
+- [x] **ARCH-04**: NATS JetStream embedded on Leaf with `sync_interval: always` for durability
+- [x] **ARCH-05**: WebSocket hub broadcasts state changes to all connected clients within 100ms
+- [x] **ARCH-06**: SvelteKit frontend embedded in Go binary via `//go:embed` for single-binary deployment
+- [x] **ARCH-07**: Leaf is sovereign — all tournament logic runs locally, cloud is never required for operation
+- [x] **ARCH-08**: Append-only audit trail for every state-changing action (operator, action, target, previous/new state, timestamp)
+- [ ] **ARCH-09**: Automated daily backup of LibSQL database to USB or cloud, with documented recovery procedure
+- [ ] **ARCH-10**: Leaf must recover cleanly from hard power-cycle during active tournament (verified by chaos testing)
+
+### Tournament Clock
+
+- [x] **CLOCK-01**: Countdown timer per level with second-granularity display, millisecond-precision internally
+- [x] **CLOCK-02**: Separate break durations with distinct visual treatment
+- [x] **CLOCK-03**: Pause/resume with visual indicator across all displays
+- [x] **CLOCK-04**: Manual advance forward/backward between levels
+- [x] **CLOCK-05**: Jump to any level by number
+- [x] **CLOCK-06**: Total elapsed time display
+- [x] **CLOCK-07**: Configurable warning thresholds (e.g., 60s, 30s, 10s) with audio and visual alerts
+- [x] **CLOCK-08**: Clock state authoritative on Leaf; clients receive ticks via WebSocket (1/sec normal, 10/sec final 10s)
+- [x] **CLOCK-09**: Reconnecting clients receive full clock state immediately
+
+### Blind Structure
+
+- [x] **BLIND-01**: Unlimited configurable levels (round or break, game type, SB/BB, ante, duration, chip-up, notes)
+- [x] **BLIND-02**: Big Blind Ante support alongside standard ante
+- [x] **BLIND-03**: Mixed game rotation support (HORSE, 8-Game round definitions)
+- [x] **BLIND-04**: Save/load reusable blind structure templates
+- [x] **BLIND-05**: Built-in templates (Turbo ~2hr, Standard ~3-4hr, Deep Stack ~5-6hr, WSOP-style)
+- [x] **BLIND-06**: Structure wizard (inputs: player count, starting chips, duration, denominations → suggested structure)
+
+### Chip Management
+
+- [x] **CHIP-01**: Define denominations with colors (hex) and values
+- [x] **CHIP-02**: Chip-up tracking per break with visual indicator on displays
+- [x] **CHIP-03**: Total chips in play calculation
+- [x] **CHIP-04**: Average stack display
+
+### Financial Engine
+
+- [x] **FIN-01**: Buy-in configuration (amount, starting chips, per-player rake, fixed rake, house contribution, bounty cost, points)
+- [x] **FIN-02**: Multiple rake categories (staff fund, league fund, house)
+- [x] **FIN-03**: Late registration cutoff (by level, by time, or by level AND remaining time — e.g., "end of Level 6 or first 90 minutes, whichever comes first")
+- [x] **FIN-04**: Re-entry support (distinct from rebuy — new entry after busting)
+- [x] **FIN-05**: Rebuy configuration (cost, chips, rake, points, limits, level/time cutoff, chip threshold)
+- [x] **FIN-06**: Add-on configuration (cost, chips, rake, points, availability window)
+- [x] **FIN-07**: Fixed bounty system (bounty cost, chip issued, hitman tracking, chain tracking, cash-out)
+- [x] **FIN-08**: Prize pool auto-calculation from all financial inputs
+- [x] **FIN-09**: Guaranteed pot support (house covers shortfall)
+- [x] **FIN-10**: Payout structures (percentage, fixed, custom table) with configurable rounding
+- [x] **FIN-11**: Chop/deal support (ICM calculator, chip-chop, even-chop, custom)
+- [x] **FIN-12**: End-of-season withholding (reserve rake portion for season prizes)
+- [x] **FIN-13**: Every financial action generates a receipt with full transaction log
+- [x] **FIN-14**: Transaction editing with audit trail and receipt reprint capability
+
+### Player Management
+
+- [x] **PLYR-01**: Player database persistent on Leaf (LibSQL), synced to Core (PostgreSQL)
+- [x] **PLYR-02**: Search with typeahead, merge duplicates, import from CSV
+- [x] **PLYR-03**: QR code generation per player for self-check-in
+- [x] **PLYR-04**: Buy-in flow: search/select player → confirm → optional auto-seat → receipt → displays update
+- [x] **PLYR-05**: Bust-out flow: select player → select hitman → bounty transfer → auto-rank → rebalance trigger → displays update
+- [x] **PLYR-06**: Undo capability for bust-out, rebuy, add-on, buy-in with full re-ranking
+- [x] **PLYR-07**: Per-player tracking: chip count, playing time, seat, moves, rebuys, add-ons, bounties, prize, points, net take, full action history
+
+### Table & Seating
+
+- [x] **SEAT-01**: Tables with configurable seat counts (6-max to 10-max), names/labels
+- [x] **SEAT-02**: Table blueprints (save venue layout)
+- [x] **SEAT-03**: Dealer button tracking
+- [x] **SEAT-04**: Random initial seating on buy-in (fills tables evenly)
+- [x] **SEAT-05**: Automatic balancing suggestions with operator confirmation required (size difference threshold, move fairness, button awareness, locked players, break short tables first — dry-run preview, never auto-apply)
+- [x] **SEAT-06**: Tap-tap manual seat moves on touch interface (tap source seat, tap destination seat)
+- [x] **SEAT-07**: Break Table action (dissolve and distribute)
+- [x] **SEAT-08**: Visual top-down table layout (player names in seats), list view, movement screen
+- [x] **SEAT-09**: Hand-for-hand mode (clock pauses, per-table completion tracking, all tables complete → next hand)
+
+### Multi-Tournament
+
+- [x] **MULTI-01**: Run multiple simultaneous tournaments with independent clocks, financials, and player tracking
+- [x] **MULTI-02**: Tournament lobby view (multi-tournament overview on displays)
+
+### League & Season
+
+- [ ] **LEAGUE-01**: Leagues (named groups, cross-season) and seasons (time-bounded within a league)
+- [ ] **LEAGUE-02**: Players can belong to multiple leagues; tournaments assigned to league + season
+- [ ] **LEAGUE-03**: Custom point formula engine with variables (TOTAL_PLAYERS, PLAYER_PLACE, REBUYS, etc.) and functions (sqrt, pow, if, etc.)
+- [ ] **LEAGUE-04**: Formula testing (input test values, preview all placements, graph distribution)
+- [ ] **LEAGUE-05**: Season standings (cumulative, best N of M, minimum attendance, historical archives)
+- [ ] **LEAGUE-06**: League standings available as display node view
+
+### Regional Tournaments
+
+- [ ] **REGION-01**: Anyone can create cross-venue tournaments/leagues (free-tier feature)
+- [ ] **REGION-02**: Define qualifying events across participating venues
+- [ ] **REGION-03**: Automatic point aggregation from each venue's qualifying tournaments
+- [ ] **REGION-04**: Unified leaderboard across all venues
+- [ ] **REGION-05**: Finals event management
+
+### Display System
+
+- [ ] **DISP-01**: Display node registry showing all connected nodes (name, status, resolution, view, group)
+- [ ] **DISP-02**: Actions: assign view, rename, group, reboot, remove
+- [ ] **DISP-03**: Tournament views: Clock, Rankings, Seating Chart, Blind Schedule, Final Table, Player Movement, Prize Pool, Tournament Lobby
+- [ ] **DISP-04**: General views: Welcome/Promo, League Standings, Upcoming Events
+- [ ] **DISP-05**: Theme system with pre-built dark/light themes and custom theme builder (colors, fonts, logo, background)
+- [ ] **DISP-06**: Sponsor banner areas (configurable per view)
+- [ ] **DISP-07**: Screen cycling with rotation config, conditional routing, override, lock
+- [ ] **DISP-08**: Multi-tournament routing (assign displays to specific tournaments or lobby)
+- [ ] **DISP-09**: Auto font-scaling to resolution; readable from 10+ feet
+- [ ] **DISP-10**: Display nodes connect via WebSocket, heartbeat every 5s, Leaf tracks status
+- [ ] **DISP-11**: All display views must stay under 350MB RSS on Pi Zero 2W during 4-hour continuous operation (non-functional, verified by soak testing)
+
+### Digital Signage
+
+- [ ] **SIGN-01**: Info screen content types: info_card, event_promo, sponsor_ad, menu_board, league_table, custom_html, media
+- [ ] **SIGN-02**: WYSIWYG drag-and-drop content editor with template gallery
+- [ ] **SIGN-03**: Venue branding auto-applied (logo, colors, fonts from venue profile)
+- [ ] **SIGN-04**: AI content generation (text prompt → polished promo card with layout, typography, imagery)
+- [ ] **SIGN-05**: AI image generation (thematic backgrounds, poker graphics, event artwork from prompts)
+- [ ] **SIGN-06**: Rich text editing with headlines, images, QR codes, countdowns, live data widgets
+- [ ] **SIGN-07**: Content scheduling (time slots, automated playlists, priority, fallback content)
+- [ ] **SIGN-08**: Per-screen content assignment (different screens show different content simultaneously)
+- [ ] **SIGN-09**: Tournament override (screens auto-switch to tournament views during play, revert to signage after)
+- [ ] **SIGN-10**: Content bundles stored on Leaf as static HTML/CSS/JS, rendered in Chromium kiosk
+
+### Player Mobile PWA
+
+- [ ] **PWA-01**: Access via QR code scan, no login required for public views
+- [ ] **PWA-02**: Live clock view (blinds, timer, next level)
+- [ ] **PWA-03**: Full blind schedule (current level highlighted)
+- [ ] **PWA-04**: Rankings (live bust-out order)
+- [ ] **PWA-05**: Prize pool and payout structure
+- [ ] **PWA-06**: Personal status (seat, points — after PIN claim)
+- [ ] **PWA-07**: League standings
+- [ ] **PWA-08**: Upcoming tournaments
+- [ ] **PWA-09**: WebSocket real-time updates with auto-reconnect and polling fallback
+- [ ] **PWA-10**: "Add to Home Screen" PWA prompt
+
+### Events Engine
+
+- [ ] **EVENT-01**: Triggers: tournament.started/ended, level.started/ended, break.started/ended, player.busted/bought_in/rebought, tables.consolidated, final_table.reached, bubble.reached, timer.warning, timer.N_remaining
+- [ ] **EVENT-02**: Actions: play_sound, show_message, change_view, flash_screen, change_theme, announce (TTS), webhook, run_command
+- [ ] **EVENT-03**: Visual rule builder (select trigger → set conditions → add actions, no code required)
+- [ ] **EVENT-04**: Rules can be global or per-tournament
+
+### Networking & Access
+
+- [ ] **NET-01**: Netbird WireGuard mesh (Leaf ↔ Core ↔ Display Nodes, zero-trust, encrypted)
+- [ ] **NET-02**: Netbird reverse proxy (player + operator access to Leaf via HTTPS from anywhere)
+- [ ] **NET-03**: Custom DNS zone (felt.internal for service discovery)
+- [ ] **NET-04**: Identity-aware SSH (admin access to Leaves via Authentik OIDC)
+- [ ] **NET-05**: Firewall policies (drop-inbound on display nodes, zero-trust ACLs)
+- [ ] **NET-06**: Lazy connections (on-demand tunnels at scale for 500+ venues)
+- [ ] **NET-07**: Custom domain support (venue CNAME → felt subdomain, Netbird handles TLS, felt subdomain as fallback)
+
+### Sync
+
+- [ ] **SYNC-01**: NATS-based event sync from Leaf to Core (queued offline, replayed in order on reconnect)
+- [ ] **SYNC-02**: Idempotent upserts on Core (safe to replay, keyed on event ID)
+- [ ] **SYNC-03**: Reverse sync (Core → Leaf) for player profiles, league config, tournament templates, new registrations, branding
+- [ ] **SYNC-04**: During running tournament, Core never overrides Leaf data for that tournament
+
+### Authentication & Security
+
+- [x] **AUTH-01**: Operator PIN login → local JWT (bcrypt hash in LibSQL, works offline)
+- [ ] **AUTH-02**: Operator OIDC via Authentik when Leaf has internet
+- [x] **AUTH-03**: Operator roles: Admin (full control), Floor (runtime actions), Viewer (read-only)
+- [ ] **AUTH-04**: Core Admin: OIDC via Authentik with mandatory MFA
+- [ ] **AUTH-05**: Player mobile: no auth for public views, 6-digit PIN claim for personal data (rate limited: exponential backoff after 5 failures, lockout after 10)
+- [ ] **AUTH-06**: Leaf ↔ Core sync: mTLS certificate + API key per venue
+- [ ] **AUTH-07**: LUKS full-disk encryption on Leaf NVMe
+- [ ] **AUTH-08**: PostgreSQL Row-Level Security (RLS) for multi-tenant isolation on Core
+- [ ] **AUTH-09**: NATS subject namespacing (venue.{id}.*) enforced by NATS authorization
+
+### Export & Import
+
+- [ ] **EXPORT-01**: CSV export (configurable columns)
+- [ ] **EXPORT-02**: JSON export (full tournament data)
+- [ ] **EXPORT-03**: HTML export (themed with venue branding)
+- [ ] **EXPORT-04**: Print output from operator UI
+
+### TDD Migration
+
+- [ ] **TDD-01**: Import blind structures and tournament templates from TDD XML export
+- [ ] **TDD-02**: Import player database (names, contact info, aliases, notes)
+- [ ] **TDD-03**: Import tournament history (results, payouts, bust-out order)
+- [ ] **TDD-04**: Import league standings and season data
+- [ ] **TDD-05**: Import custom payout structures
+- [ ] **TDD-06**: Import wizard with preview, player name matching, template naming
+- [ ] **TDD-07**: Zero data loss on migration — venue's Felt instance shows complete history from day one
+
+### Operator UI
+
+- [x] **UI-01**: Mobile-first bottom tab bar (Overview, Players, Tables, Financials, More)
+- [x] **UI-02**: Floating Action Button (FAB) for quick actions (Bust, Buy In, Rebuy, Add-On, Pause/Resume)
+- [x] **UI-03**: Persistent header showing clock, level, blinds, player count
+- [x] **UI-04**: Desktop/laptop sidebar navigation with wider content area
+- [x] **UI-05**: Catppuccin Mocha dark theme (default) and Latte light theme
+- [x] **UI-06**: 48px minimum touch targets, press-state animations, loading states
+- [x] **UI-07**: Toast notifications (success, info, warning, error) with auto-dismiss
+- [x] **UI-08**: Data tables with sort, sticky header, search/filter, swipe actions (mobile)
+
+## v2 Requirements
+
+Deferred to Development Phases 2-4. Tracked but not in current roadmap.
+
+### Cash Game Operations (Dev Phase 2)
+
+- **CASH-01**: Waitlist management by game type and stakes with display integration
+- **CASH-02**: Table management (open/close, game types, stakes, seat tracking, status board)
+- **CASH-03**: Game type registry (all poker variants, configurable stakes/betting)
+- **CASH-04**: Session tracking (player sessions, buy-in/cashout, duration, history)
+- **CASH-05**: Rake tracking (percentage/time/flat, per-table reporting)
+- **CASH-06**: Must-move tables (automated progression, main game priority)
+- **CASH-07**: Seat change requests (queue, notification)
+- **CASH-08**: Table transfers within sessions
+- **CASH-09**: Player alerts (waitlist position, seat available, preferred game opened)
+
+### Complete Venue Platform (Dev Phase 3)
+
+- **DEALER-01**: Dealer scheduling, skill profiles, shift trading, clock-in/out, rotation
+- **DEALER-02**: Dealer profiles are platform-level (portable across venues)
+- **LOYAL-01**: Points engine, tier system, rewards catalog, automated promos
+- **LOYAL-02**: Cross-venue loyalty for multi-venue operators
+- **MEMBER-01**: Private venues, memberships, invite codes, member tiers, guest system
+- **ANALYTICS-01**: Revenue dashboards, player analytics, operational analytics, benchmarking
+- **PUBLIC-01**: Venue profile page, online event registration, schedule publishing
+
+### Native Apps & Platform Maturity (Dev Phase 4)
+
+- **NATIVE-01**: Native player app (iOS + Android)
+- **NATIVE-02**: Native venue management app (iOS + Android)
+- **SOCIAL-01**: Private groups, activity feed, achievements, friend-based venue discovery
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Online poker / real-money gambling | Felt is a management tool, not a gambling platform |
+| Payment processing | Tracks amounts, doesn't process transactions |
+| Video streaming / live broadcast | Different infrastructure, niche use case |
+| BYO hardware | Security, reliability, support consistency |
+| Third-party cloud (Cloudflare, AWS) | Self-hosted everything, no MITM |
+| Crypto payments | Volatile, regulatory uncertainty, wrong market |
+| Real-time chip count entry by players | Cheating surface, operational chaos |
+| Staking / backing / action splitting | Legal complexity, out of scope |
+| Casino CMS integration (IGT, Bally's) | Out of scope for Phase 1-3; planned for Casino Enterprise tier in Phase 4+ |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap reorganization.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| ARCH-01 | Phase 1 | Complete |
+| ARCH-02 | Phase 3 | Pending |
+| ARCH-03 | Phase 1 | Complete |
+| ARCH-04 | Phase 1 | Complete |
+| ARCH-05 | Phase 1 | Complete |
+| ARCH-06 | Phase 1 | Complete |
+| ARCH-07 | Phase 1 | Complete |
+| ARCH-08 | Phase 1 | Complete |
+| ARCH-09 | Phase 7 | Pending |
+| ARCH-10 | Phase 7 | Pending |
+| AUTH-01 | Phase 1 | Complete |
+| AUTH-02 | Phase 7 | Pending |
+| AUTH-03 | Phase 1 | Complete |
+| AUTH-04 | Phase 3 | Pending |
+| AUTH-05 | Phase 2 | Pending |
+| AUTH-06 | Phase 3 | Pending |
+| AUTH-07 | Phase 7 | Pending |
+| AUTH-08 | Phase 3 | Pending |
+| AUTH-09 | Phase 3 | Pending |
+| NET-01 | Phase 7 | Pending |
+| NET-02 | Phase 7 | Pending |
+| NET-03 | Phase 7 | Pending |
+| NET-04 | Phase 7 | Pending |
+| NET-05 | Phase 7 | Pending |
+| NET-06 | Phase 7 | Pending |
+| NET-07 | Phase 7 | Pending |
+| PLAT-01 | Phase 3 | Pending |
+| PLAT-02 | Phase 3 | Pending |
+| PLAT-03 | Phase 3 | Pending |
+| PLAT-04 | Phase 3 | Pending |
+| PLAT-05 | Phase 3 | Pending |
+| PLAT-06 | Phase 3 | Pending |
+| SYNC-01 | Phase 3 | Pending |
+| SYNC-02 | Phase 3 | Pending |
+| SYNC-03 | Phase 3 | Pending |
+| SYNC-04 | Phase 3 | Pending |
+| EXPORT-01 | Phase 2 | Pending |
+| EXPORT-02 | Phase 2 | Pending |
+| EXPORT-03 | Phase 2 | Pending |
+| EXPORT-04 | Phase 2 | Pending |
+| CLOCK-01 | Phase 1 | Complete |
+| CLOCK-02 | Phase 1 | Complete |
+| CLOCK-03 | Phase 1 | Complete |
+| CLOCK-04 | Phase 1 | Complete |
+| CLOCK-05 | Phase 1 | Complete |
+| CLOCK-06 | Phase 1 | Complete |
+| CLOCK-07 | Phase 1 | Complete |
+| CLOCK-08 | Phase 1 | Complete |
+| CLOCK-09 | Phase 1 | Complete |
+| BLIND-01 | Phase 1 | Complete |
+| BLIND-02 | Phase 1 | Complete |
+| BLIND-03 | Phase 1 | Complete |
+| BLIND-04 | Phase 1 | Complete |
+| BLIND-05 | Phase 1 | Complete |
+| BLIND-06 | Phase 1 | Complete |
+| CHIP-01 | Phase 1 | Complete |
+| CHIP-02 | Phase 1 | Complete |
+| CHIP-03 | Phase 1 | Complete |
+| CHIP-04 | Phase 1 | Complete |
+| MULTI-01 | Phase 1 | Complete |
+| MULTI-02 | Phase 1 | Complete |
+| FIN-01 | Phase 1 | Complete |
+| FIN-02 | Phase 1 | Complete |
+| FIN-03 | Phase 1 | Complete |
+| FIN-04 | Phase 1 | Complete |
+| FIN-05 | Phase 1 | Complete |
+| FIN-06 | Phase 1 | Complete |
+| FIN-07 | Phase 1 | Complete |
+| FIN-08 | Phase 1 | Complete |
+| FIN-09 | Phase 1 | Complete |
+| FIN-10 | Phase 1 | Complete |
+| FIN-11 | Phase 1 | Complete |
+| FIN-12 | Phase 1 | Complete |
+| FIN-13 | Phase 1 | Complete |
+| FIN-14 | Phase 1 | Complete |
+| PLYR-01 | Phase 1 | Complete |
+| PLYR-02 | Phase 1 | Complete |
+| PLYR-03 | Phase 1 | Complete |
+| PLYR-04 | Phase 1 | Complete |
+| PLYR-05 | Phase 1 | Complete |
+| PLYR-06 | Phase 1 | Complete |
+| PLYR-07 | Phase 1 | Complete |
+| SEAT-01 | Phase 1 | Complete |
+| SEAT-02 | Phase 1 | Complete |
+| SEAT-03 | Phase 1 | Complete |
+| SEAT-04 | Phase 1 | Complete |
+| SEAT-05 | Phase 1 | Complete |
+| SEAT-06 | Phase 1 | Complete |
+| SEAT-07 | Phase 1 | Complete |
+| SEAT-08 | Phase 1 | Complete |
+| SEAT-09 | Phase 1 | Complete |
+| UI-01 | Phase 1 | Complete |
+| UI-02 | Phase 1 | Complete |
+| UI-03 | Phase 1 | Complete |
+| UI-04 | Phase 1 | Complete |
+| UI-05 | Phase 1 | Complete |
+| UI-06 | Phase 1 | Complete |
+| UI-07 | Phase 1 | Complete |
+| UI-08 | Phase 1 | Complete |
+| DISP-01 | Phase 2 | Pending |
+| DISP-02 | Phase 2 | Pending |
+| DISP-03 | Phase 2 | Pending |
+| DISP-04 | Phase 2 | Pending |
+| DISP-05 | Phase 2 | Pending |
+| DISP-06 | Phase 2 | Pending |
+| DISP-07 | Phase 2 | Pending |
+| DISP-08 | Phase 2 | Pending |
+| DISP-09 | Phase 2 | Pending |
+| DISP-10 | Phase 2 | Pending |
+| DISP-11 | Phase 7 | Pending |
+| PWA-01 | Phase 2 | Pending |
+| PWA-02 | Phase 2 | Pending |
+| PWA-03 | Phase 2 | Pending |
+| PWA-04 | Phase 2 | Pending |
+| PWA-05 | Phase 2 | Pending |
+| PWA-06 | Phase 2 | Pending |
+| PWA-07 | Phase 2 | Pending |
+| PWA-08 | Phase 2 | Pending |
+| PWA-09 | Phase 2 | Pending |
+| PWA-10 | Phase 2 | Pending |
+| SIGN-01 | Phase 4 | Pending |
+| SIGN-02 | Phase 4 | Pending |
+| SIGN-03 | Phase 4 | Pending |
+| SIGN-04 | Phase 4 | Pending |
+| SIGN-05 | Phase 4 | Pending |
+| SIGN-06 | Phase 4 | Pending |
+| SIGN-07 | Phase 4 | Pending |
+| SIGN-08 | Phase 4 | Pending |
+| SIGN-09 | Phase 4 | Pending |
+| SIGN-10 | Phase 4 | Pending |
+| EVENT-01 | Phase 4 | Pending |
+| EVENT-02 | Phase 4 | Pending |
+| EVENT-03 | Phase 4 | Pending |
+| EVENT-04 | Phase 4 | Pending |
+| LEAGUE-01 | Phase 5 | Pending |
+| LEAGUE-02 | Phase 5 | Pending |
+| LEAGUE-03 | Phase 5 | Pending |
+| LEAGUE-04 | Phase 5 | Pending |
+| LEAGUE-05 | Phase 5 | Pending |
+| LEAGUE-06 | Phase 5 | Pending |
+| REGION-01 | Phase 5 | Pending |
+| REGION-02 | Phase 5 | Pending |
+| REGION-03 | Phase 5 | Pending |
+| REGION-04 | Phase 5 | Pending |
+| REGION-05 | Phase 5 | Pending |
+| TDD-01 | Phase 6 | Pending |
+| TDD-02 | Phase 6 | Pending |
+| TDD-03 | Phase 6 | Pending |
+| TDD-04 | Phase 6 | Pending |
+| TDD-05 | Phase 6 | Pending |
+| TDD-06 | Phase 6 | Pending |
+| TDD-07 | Phase 6 | Pending |
+
+**Coverage:**
+- v1 requirements: 152 total
+- Mapped to phases: 152
+- Unmapped: 0
+
+**Per-phase breakdown:**
+- Phase 1 (Tournament Engine): 68
+- Phase 2 (Display Views + Player PWA): 25
+- Phase 3 (Core Sync + Platform Identity): 15
+- Phase 4 (Digital Signage + Events Engine): 14
+- Phase 5 (Leagues, Seasons + Regional Tournaments): 11
+- Phase 6 (TDD Migration): 7
+- Phase 7 (Hardware Leaf): 12
+
+---
+*Requirements defined: 2026-02-28*
+*Last updated: 2026-03-01 — roadmap reorganized from 11 phases to 7 (vertical slices, software-first/hardware-later, dev environment is x86 LXC not ARM64)*

.planning/ROADMAP.md

@@ -0,0 +1,150 @@
+# Roadmap: Felt
+
+## Overview
+
+Felt is built in 7 phases, all scoped to Development Phase 1 (Live Tournament Management). The build order follows two principles: **vertical slices** (backend + frontend together so every phase is demoable) and **software first, hardware later** (ARM64, LUKS, Netbird, Pi Zero kiosk are all Phase 7 packaging concerns).
+
+All development and testing happens in an x86 LXC container on Proxmox. The Go binary running there is functionally identical to the Virtual Leaf that runs the free tier in production on Hetzner. Hardware Leaf is a later deployment target for the Offline/Pro tier.
+
+**Development environment:** x86_64 LXC container (Debian/Ubuntu), Go binary + LibSQL + NATS JetStream + SvelteKit. No Docker, no ARM cross-compilation, no Netbird. Display views are browser windows pointed at the container. Player phones connect on the local network.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Tournament Engine** - Go binary in LXC, full vertical slice: clock, blinds, financials, players, tables, seating, operator UI — everything to run a complete tournament
+- [ ] **Phase 2: Display Views + Player PWA** - Browser-based display views, player mobile PWA, export formats — the full venue experience
+- [ ] **Phase 3: Core Sync + Platform Identity** - PostgreSQL on Core, NATS sync, platform-level player profiles, Virtual Leaf, GDPR compliance
+- [ ] **Phase 4: Digital Signage + Events Engine** - WYSIWYG content editor, AI generation, scheduling, visual rule builder, automation triggers
+- [ ] **Phase 5: Leagues, Seasons + Regional Tournaments** - Point formulas, standings, cross-venue tournaments, finals management
+- [ ] **Phase 6: TDD Migration** - Full TDD XML import, player database migration, tournament history, wizard, zero data loss
+- [ ] **Phase 7: Hardware Leaf (ARM64 + Offline Hardening)** - ARM64 cross-compilation, LUKS encryption, Pi Zero display nodes, Netbird mesh, provisioning, chaos testing
+
+## Phase Details
+
+### Phase 1: Tournament Engine
+**Goal**: A complete tournament runs from start to finish in an x86 LXC container with a working touch-friendly operator UI — demoable at a venue by pointing any device at the container
+**Depends on**: Nothing (first phase)
+**Requirements**: ARCH-01, ARCH-03, ARCH-04, ARCH-05, ARCH-06, ARCH-07, ARCH-08, AUTH-01, AUTH-03, CLOCK-01, CLOCK-02, CLOCK-03, CLOCK-04, CLOCK-05, CLOCK-06, CLOCK-07, CLOCK-08, CLOCK-09, BLIND-01, BLIND-02, BLIND-03, BLIND-04, BLIND-05, BLIND-06, CHIP-01, CHIP-02, CHIP-03, CHIP-04, FIN-01, FIN-02, FIN-03, FIN-04, FIN-05, FIN-06, FIN-07, FIN-08, FIN-09, FIN-10, FIN-11, FIN-12, FIN-13, FIN-14, PLYR-01, PLYR-02, PLYR-03, PLYR-04, PLYR-05, PLYR-06, PLYR-07, SEAT-01, SEAT-02, SEAT-03, SEAT-04, SEAT-05, SEAT-06, SEAT-07, SEAT-08, SEAT-09, MULTI-01, MULTI-02, UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, UI-07, UI-08
+**Note**: Basic sound infrastructure (play_sound action for level change, break start, bubble) ships with the clock engine here. The full visual rule builder (EVENT-01 through EVENT-04) remains in Phase 4.
+**Success Criteria** (what must be TRUE):
+  1. A Go binary starts in the LXC container, serves HTTP, embeds NATS JetStream and LibSQL, and WebSocket-connected clients receive state changes within 100ms
+  2. The clock counts down each level, transitions automatically, emits configurable warnings; an operator can pause, resume, jump to any level; two tournaments run simultaneously with independent state
+  3. A blind structure with mixed-game rotation, big-blind antes, and chip-up breaks can be saved as a template; the structure wizard produces a playable structure from inputs
+  4. A complete buy-in, rebuy, add-on, and bounty flow produces a transaction log; a CI gate test verifies sum of payouts always equals prize pool (int64 cents, zero floating-point deviation)
+  5. An operator can search by name with typeahead, process a buy-in with auto-seating, bust a player with hitman selection and auto-balancing — all from a mobile-first touch UI with FAB, persistent header, Catppuccin Mocha dark theme, and 48px touch targets
+  6. Every state-changing action writes an append-only audit trail entry; any financial transaction or bust-out can be undone with full re-ranking
+**Plans** (12 plans, 5 waves):
+  - Wave 1: A (Project Scaffold + Infrastructure), B (Database Schema + Migrations)
+  - Wave 2: C (Auth + Audit Trail + Undo), D (Clock Engine), E (Blind Structure + Templates), J (SvelteKit Frontend Scaffold)
+  - Wave 3: F (Financial Engine), G (Player Management), H (Table & Seating Engine)
+  - Wave 4: I (Tournament Lifecycle + Multi-Tournament + Chop/Deal)
+  - Wave 5: K (Frontend — Overview + Clock + Financials), L (Frontend — Players + Tables + More)
+
+### Phase 2: Display Views + Player PWA
+**Goal**: The full venue experience — operator UI on phone, TV browsers showing tournament data fullscreen, players scanning QR codes on their phones — all connecting to the LXC container
+**Depends on**: Phase 1
+**Requirements**: DISP-01, DISP-02, DISP-03, DISP-04, DISP-05, DISP-06, DISP-07, DISP-08, DISP-09, DISP-10, PWA-01, PWA-02, PWA-03, PWA-04, PWA-05, PWA-06, PWA-07, PWA-08, PWA-09, PWA-10, AUTH-05, EXPORT-01, EXPORT-02, EXPORT-03, EXPORT-04
+**Success Criteria** (what must be TRUE):
+  1. All tournament views (Clock, Rankings, Seating Chart, Blind Schedule, Final Table, Prize Pool, Lobby) render in browser windows connected via WebSocket and are readable from 10+ feet with auto font-scaling
+  2. Screen cycling with configurable rotation runs automatically; the operator can assign views, override, or lock any screen from the operator UI
+  3. A player scans a QR code and sees live clock, current blinds, and next level within 3 seconds — no account required; the PWA prompts "Add to Home Screen" on iOS and Android
+  4. A player can claim personal status (seat, points) by entering a 6-digit PIN; WebSocket updates arrive within 100ms with auto-reconnect and polling fallback
+  5. A completed tournament exports to CSV, JSON, and HTML with correct data and venue branding; a player can request a JSON export of their personal data (GDPR portability)
+**Plans**: TBD
+
+### Phase 3: Core Sync + Platform Identity
+**Goal**: Players are platform-level entities with cross-venue portable profiles, Leaf-to-Core sync works with guaranteed delivery, Virtual Leaf provides free-tier access, and Core Admin is secured with MFA
+**Depends on**: Phase 1
+**Requirements**: ARCH-02, PLAT-01, PLAT-02, PLAT-03, PLAT-04, PLAT-05, PLAT-06, SYNC-01, SYNC-02, SYNC-03, SYNC-04, AUTH-04, AUTH-06, AUTH-08, AUTH-09
+**Success Criteria** (what must be TRUE):
+  1. A player created on one Leaf appears on Core with the same UUID and profile data after reconnect, with no duplicates
+  2. Tournament events published on Leaf while offline queue in NATS JetStream and replay to Core in order when connectivity is restored; Core never overwrites Leaf data for a running tournament
+  3. Reverse sync delivers player profiles, league config, tournament templates, and branding from Core to Leaf
+  4. A Virtual Leaf instance starts on Core infrastructure, runs the same tournament logic as a physical Leaf, and syncs data to Core PostgreSQL
+  5. Core Admin authenticates via OIDC with mandatory MFA; NATS subjects are namespaced by venue ID with PostgreSQL RLS multi-tenant isolation; Leaf-Core sync uses mTLS + API key per venue
+  6. Player data export (GDPR portability) and deletion (anonymize tournament entries, remove PII, propagate via NATS) work correctly
+**Plans**: TBD
+
+### Phase 4: Digital Signage + Events Engine
+**Goal**: Venue screens show scheduled content between tournaments and the events engine automates visual and audio responses to tournament moments — all configured via the operator UI without code
+**Depends on**: Phase 2
+**Requirements**: SIGN-01, SIGN-02, SIGN-03, SIGN-04, SIGN-05, SIGN-06, SIGN-07, SIGN-08, SIGN-09, SIGN-10, EVENT-01, EVENT-02, EVENT-03, EVENT-04
+**Success Criteria** (what must be TRUE):
+  1. An operator creates a promo card with the WYSIWYG editor, uses AI text generation to produce content, schedules it to run on specific screens at specific times, and it appears without manual intervention
+  2. Screens automatically switch to tournament clock view when a tournament starts and revert to the signage playlist when it ends — without operator action
+  3. An event rule triggers a sound and a display message when the final table is reached; the operator created the rule via the visual builder without writing code
+  4. Different screens show different content simultaneously (e.g., screen 1 shows sponsor ad, screen 2 shows league table)
+  5. All signage content bundles are stored as static HTML/CSS/JS and render in any browser without internet
+**Security Requirements** (deferred from Phase 1 security review):
+  - EVENT-02 `run_command` action: sandbox execution (allowlist of commands, no shell=true, no arbitrary binary execution, timeout enforcement)
+  - EVENT-02 `webhook` action: URL allowlist (operator-configured permitted domains), no SSRF to internal services, timeout on outbound requests
+  - Signage content: sanitize user-authored HTML/CSS (no script injection in WYSIWYG output), CSP headers on display views
+**Plans**: TBD
+
+### Phase 5: Leagues, Seasons + Regional Tournaments
+**Goal**: Venues run structured leagues with configurable point formulas and season standings, and anyone can create cross-venue tournaments using the free-tier regional organizer
+**Depends on**: Phase 3
+**Requirements**: LEAGUE-01, LEAGUE-02, LEAGUE-03, LEAGUE-04, LEAGUE-05, LEAGUE-06, REGION-01, REGION-02, REGION-03, REGION-04, REGION-05
+**Success Criteria** (what must be TRUE):
+  1. An operator configures a league with a custom point formula, tests it against sample placements with the formula tester, and sees the distribution graph before saving
+  2. Season standings update automatically after each tournament result; the operator can configure best-N-of-M counting and minimum attendance requirements
+  3. League standings display as a dedicated view, updating live as tournament results arrive
+  4. A regional organizer (free-tier user) creates a cross-venue tournament, adds qualifying events at participating venues, and the unified leaderboard updates automatically from each venue's results
+  5. A finals event is managed through the platform with aggregated qualifying results feeding directly into the finals seeding
+**Plans**: TBD
+
+### Phase 6: TDD Migration
+**Goal**: Any venue running The Tournament Director can import their complete history and start using Felt on day one with zero data loss
+**Depends on**: Phase 5
+**Requirements**: TDD-01, TDD-02, TDD-03, TDD-04, TDD-05, TDD-06, TDD-07
+**Success Criteria** (what must be TRUE):
+  1. An operator drops a TDD XML export file into the import wizard and sees a preview of all detected blind structures, players, tournaments, and leagues before committing
+  2. All blind structures and payout tables import with exact value preservation — no rounding, no data loss
+  3. The player database imports with name matching that detects likely duplicates and prompts the operator to confirm merges before writing
+  4. Complete tournament history (results, payouts, bust-out order) appears in Felt as if it were run there — full search, export, and league calculation work on imported data
+  5. A venue that has used TDD for 5 years can import their full history and see complete league standings with accurate historical point calculations on day one
+**Plans**: TBD
+
+### Phase 7: Hardware Leaf (ARM64 + Offline Hardening)
+**Goal**: A pre-configured ARM64 Leaf node boots, connects to Core via Netbird, serves everything wirelessly, survives power failures, and runs completely offline — this is the Offline/Pro tier product
+**Depends on**: Phase 3
+**Requirements**: ARCH-09, ARCH-10, AUTH-02, AUTH-07, NET-01, NET-02, NET-03, NET-04, NET-05, NET-06, NET-07, DISP-11
+**Success Criteria** (what must be TRUE):
+  1. A single Go binary (`cmd/leaf`) builds for ARM64 via CI with CGO enabled and LibSQL linked, with zero manual steps
+  2. The Leaf binary starts on an Orange Pi 5 Plus with LUKS full-disk encryption on NVMe, serves HTTP, and connects to Core via Netbird WireGuard mesh
+  3. An operator can authenticate via OIDC through Authentik when the Leaf has internet; display nodes and player browsers reach the Leaf from outside the local network via HTTPS through the Netbird reverse proxy
+  4. Pi Zero 2W display nodes run Chromium kiosk with systemd watchdog, zram, and memory limits; all display views stay under 350MB RSS for 4+ hours (soak tested on actual hardware)
+  5. The Leaf survives 10 hard power cycles without data loss (WAL checkpoint on shutdown, verified by chaos testing); automated daily backup to USB or cloud with documented recovery
+  6. Custom domain support works (venue CNAME → felt subdomain); lazy connections scale to 500+ venues; Netbird DNS, SSH, and firewall policies are enforced
+**Security Requirements** (deferred from Phase 1 security review):
+  - Migrate JWT storage from localStorage to HttpOnly secure cookies (Leaf becomes publicly accessible via Netbird reverse proxy — XSS can steal localStorage tokens)
+  - JWT signing key rotation with `kid` header support
+**Plans**: TBD
+
+## Key Principles
+
+1. **Build software first, package for hardware later.** Every feature is developed and tested in an x86 LXC container. ARM64 is a deployment target, not a development concern.
+2. **Vertical slices, not horizontal layers.** Each phase delivers something visible and demoable. No headless engine phases followed by a monolithic UI phase.
+3. **The LXC container IS the product.** The binary running in the dev container is functionally the same as the Virtual Leaf that runs the free tier in production. Hardware Leaf is a later packaging step for paid tiers.
+4. **Revenue-gated complexity.** Netbird, LUKS, ARM cross-compilation, Pi Zero kiosk — all Offline/Pro tier. Don't build until venues pay for it.
+5. **Demo-driven development.** After Phase 1, demo a full tournament at the venue. After Phase 2, the full experience with displays and player phones. Every phase adds visible value.
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Tournament Engine | 9/14 | Executing | - |
+| 2. Display Views + Player PWA | 0/TBD | Not started | - |
+| 3. Core Sync + Platform Identity | 0/TBD | Not started | - |
+| 4. Digital Signage + Events Engine | 0/TBD | Not started | - |
+| 5. Leagues, Seasons + Regional Tournaments | 0/TBD | Not started | - |
+| 6. TDD Migration | 0/TBD | Not started | - |
+| 7. Hardware Leaf (ARM64 + Offline Hardening) | 0/TBD | Not started | - |

.planning/ROADMAP_FEEDBACK.md

@@ -0,0 +1,44 @@
+# Roadmap Feedback (to apply in next session)
+
+Applied: 2026-02-28 — Context exhausted before changes could be made to ROADMAP.md
+
+## Changes to make
+
+### 1. Slim down Phase 1 (move 4 requirements to later phases)
+- **NET-06** (lazy connections for 500+ venues) → Move to Phase 10 or later
+- **NET-07** (custom domains) → Move to Phase 9 or 10
+- **AUTH-04** (Core Admin with mandatory MFA) → Move to Phase 2 (depends on Core)
+- **AUTH-09** (NATS subject namespacing) → Move to Phase 2 (multi-tenant concern)
+- Phase 1 goal: "Leaf binary boots, serves HTTP, NATS works, LibSQL works, basic PIN auth works, Netbird mesh connects, CI builds ARM64"
+
+### 2. Interleave UI with engine work (Phases 3-6)
+- Building all engines headless then all UI at once is unnatural for a solo dev
+- Consider: build tournament clock UI while building clock engine, financial UI while building financial engine
+- This is a planning consideration for /gsd:discuss-phase, not necessarily a phase restructure
+- Alternative: merge Phase 6 into Phases 3-5 (each phase builds its own UI slice)
+
+### 3. Move EXPORT out of Phase 2
+- EXPORT-01 through EXPORT-04 → Move to Phase 8 or later
+- Not a dependency for anything; keeps Phase 2 focused on "identity + sync"
+
+### 4. Basic sound events earlier
+- Basic sound triggers (level change, break start, bubble) are TDD table-stakes
+- Consider: move basic play_sound action to Phase 3 (Tournament Engine)
+- Full visual rule builder (EVENT-01 through EVENT-04) stays in Phase 9
+
+### 5. Virtual Leaf (ARCH-02) needs a home
+- Free tier runs virtual Leaf instances on cloud infrastructure
+- Leaf binary must run headlessly on Core, managed as containers
+- Different startup path than physical Leaf
+- Should be part of Phase 2 (alongside Core sync) or its own phase
+- Without this, there's no free tier to deploy
+
+### 6. Add offline duration test to success criteria
+- Phase 3 or Phase 5 should include: "A 4-hour tournament with 40 players, including rebuys, bust-outs, table balancing, and payouts, completes successfully with the Leaf completely offline the entire time"
+
+### 7. Clarify 8hr vs 4hr soak test (Phase 7)
+- Phase 7 success criterion 5 says "8+ hours" — more ambitious than pitfalls doc (4hr)
+- If intentional, great — but soak test on Pi Zero 2W hardware needs to happen early in Phase 7, not at the end
+
+## Also update REQUIREMENTS.md traceability
+- After moving requirements between phases, update the traceability table to match

.planning/STATE.md

@@ -0,0 +1,139 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+status: unknown
+last_updated: "2026-03-01T07:29:08.718Z"
+progress:
+  total_phases: 1
+  completed_phases: 1
+  total_plans: 14
+  completed_plans: 14
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-02-28)
+
+**Core value:** A venue can run a complete tournament offline on a €100 device with wireless displays and player mobile access — and it just works, on any network, with zero IT involvement.
+**Current focus:** Phase 1 — Foundation
+
+## Current Position
+
+Phase: 1 of 7 (Tournament Engine)
+Plan: 14 of 14 in current phase (COMPLETE)
+Status: Phase 1 Complete
+Last activity: 2026-03-01 — Completed Plan 14 (Frontend Tables Tab + More Tab)
+
+Progress: [██████████] 100%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 13
+- Average duration: 9min
+- Total execution time: 2.01 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| 01-tournament-engine | 13 | 121min | 9min |
+
+**Recent Trend:**
+- Last 5 plans: 01-11 (8min), 01-12 (8min), 01-13 (5min), 01-06 (9min), 01-08 (6min)
+- Trend: steady
+
+*Updated after each plan completion*
+| Phase 01 P14 | 11 | 2 tasks | 8 files |
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- [Init]: Go monorepo, shared `internal/`, `cmd/leaf` and `cmd/core` are the only divergence points
+- [Init]: NATS sync_interval: always required before first deploy (December 2025 Jepsen finding)
+- [Init]: All monetary values int64 cents — never float64 (CI gate test required)
+- [Init]: go-libsql has no tagged releases — pin to commit hash in go.mod
+- [Init]: Netbird reverse proxy is beta — validate player PWA access in Phase 1 before depending on it in Phase 8
+- [01-01]: NATS server v2.12.4 requires Go 1.24+ — auto-upgraded from Go 1.23
+- [01-01]: WebSocket JWT via query parameter (browser WS API limitation)
+- [01-01]: JWT signing key ephemeral per startup — will persist in auth plan
+- [01-02]: go-libsql requires single-statement Exec — migration runner splits SQL files into individual statements
+- [01-02]: go-libsql PRAGMA handling is inconsistent — use QueryRow for journal_mode, execPragma helper for others
+- [01-02]: Force single DB connection during migrations (SetMaxOpenConns(1)) for table visibility
+- [01-10]: ESM type:module required in package.json for SvelteKit/Vite compatibility
+- [01-10]: frontend/build/ tracked in git (not gitignored) for go:embed
+- [01-10]: Catppuccin colors defined as CSS custom properties rather than @catppuccin/palette JS package
+- [01-04]: Clock ticker uses 100ms resolution with broadcast gating (not two separate tickers)
+- [01-04]: Crash recovery always restores clock as paused (operator must explicitly resume)
+- [01-04]: Overtime mode defaults to repeat (last level repeats indefinitely)
+- [01-04]: State change callback is async to avoid holding clock mutex during DB writes
+- [01-05]: Seed data uses INSERT OR IGNORE with explicit IDs for idempotent migration re-runs
+- [01-05]: Wizard generates preview-only levels (not auto-saved) for TD review before saving
+- [01-05]: BB ante used in WSOP-style template (separate from standard ante field)
+- [01-05]: Payout bracket validation enforces contiguous entry count ranges with no gaps
+- [01-03]: JWT HS256 enforcement via WithValidMethods prevents algorithm confusion attacks
+- [01-03]: Rate limiting keyed by global sentinel (_global) since PINs scan all operators
+- [01-03]: AuditRecorder callback breaks import cycle between auth and audit packages
+- [01-03]: NATS publish best-effort (logged, not fatal) to avoid audit blocking mutations
+- [01-03]: Undo creates reversal entry, only marks undone_by on original (never deletes)
+- [01-13]: div with role=tablist (not nav) for bottom tabs to avoid Svelte a11y conflict
+- [01-13]: FAB actions dispatched via callback prop for centralized routing in layout
+- [01-13]: Multi-tournament state is a separate store from singleton tournament state
+- [01-13]: DataTable uses Record<string,unknown> with render functions (not generics) for Svelte compat
+- [01-06]: PKO bounty half-split uses integer division (cashPortion = bountyValue/2, bountyPortion = remainder)
+- [01-06]: Unique entry count for bracket selection uses COUNT(DISTINCT player_id) on non-undone buyin tx only
+- [01-06]: Late reg checks level AND time cutoffs independently (either exceeded closes registration)
+- [01-06]: Rebuy/addon rake splits proportionally scaled from buyin rake splits (last gets remainder)
+- [01-06]: CI gate: CalculatePayoutsFromPool is pure function tested with 10,000+ random inputs, zero deviation
+- [01-08]: Balance suggestions use clockwise distance from dealer button for move fairness
+- [01-08]: Stale suggestion re-validation requires fromCount - toCount >= 2 before accepting
+- [01-08]: Break table is fully automatic (applies immediately, result is informational per CONTEXT.md)
+- [01-08]: Blueprint routes are venue-level (not tournament-scoped); admin role required for mutations
+- [01-07]: Rankings derived from bust_out_at timestamps via RecalculateAllRankings (never stored independently)
+- [01-07]: FTS5 queries use quoted terms with * suffix for prefix matching
+- [01-07]: CSV formula injection neutralized with tab prefix on =, +, -, @ characters
+- [01-07]: Buy-in flow auto-registers player in tournament_players if not already present
+- [01-07]: QR code URL format: felt://player/{uuid} for future PWA self-check-in
+- [01-09]: ICM dispatcher: exact Malmuth-Harville for <=10 players, Monte Carlo (100K iterations) for 11+
+- [01-09]: Deal proposal/confirm workflow: ProposeDeal returns preview, ConfirmDeal applies payouts
+- [01-09]: Full chop sets all players to 'deal' status and completes tournament; partial chop continues play
+- [01-09]: Tournament auto-close: 1 remaining = EndTournament, 0 remaining = CancelTournament
+- [01-09]: Integration tests use file-based DB with WAL mode for clock ticker goroutine compatibility
+- [01-12]: Flow overlays use fixed full-screen z-index 100 positioning (modal-like, not route-based)
+- [01-12]: BustOutFlow uses grid table picker then seat tap for minimal taps under time pressure
+- [01-12]: RebuyFlow/AddOnFlow preselectedPlayer prop skips search step for direct launch from PlayerDetail
+- [01-12]: FAB actions in layout wired to actual flow overlays (replacing placeholder toasts)
+- [01-11]: ClockDisplay uses clamp(3rem, 12vw, 6rem) for responsive timer sizing across mobile/desktop
+- [01-11]: Unicode escapes in Svelte templates must use HTML entities (not JS escapes) to avoid parser confusion
+- [01-11]: BubblePrize is standalone prominent button (not buried in menus) per CONTEXT.md requirement
+- [01-11]: DealFlow uses multi-step wizard pattern (type > input > review > confirm) for all 5 deal types
+- [01-11]: Transaction undo uses window.confirm for simplicity in touch-first TD interface
+- [Phase 01]: Structure wizard uses geometric ratio for blind escalation with nice-number rounding
+- [Phase 01]: Blind structure editor uses move up/down buttons (no drag-and-drop in Phase 1)
+- [Phase 01]: Theme toggle writes data-theme attribute on documentElement for immediate CSS variable switch
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- [Phase 1]: go-libsql CGO ARM64 cross-compilation must be validated in CI before any downstream features depend on it
+- [Phase 1]: Netbird reverse proxy beta status — test the full QR code → HTTPS → WireGuard → Leaf flow early
+- [Phase 3]: NATS JetStream cross-domain stream mirroring (Leaf → Core) needs integration test before Phase 2 depends on it
+- [Phase 4]: Events engine security — run_command sandboxing, webhook URL allowlist, WYSIWYG HTML sanitization (deferred from Phase 1 security review)
+- [Phase 7]: JWT HttpOnly cookies + signing key rotation (deferred from Phase 1 security review — localStorage is acceptable while Leaf is local-network only)
+- [Phase 7]: Pi Zero 2W memory must be profiled on actual hardware with all display views before scaling signage
+
+## Session Continuity
+
+Last session: 2026-03-01
+Stopped at: Completed 01-14-PLAN.md (Frontend Tables Tab + More Tab)
+Resume file: None

.planning/config.json

@@ -0,0 +1,13 @@
+{
+  "mode": "yolo",
+  "depth": "comprehensive",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "quality",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "auto_advance": true
+  }
+}

.planning/phases/01-tournament-engine/.continue-here.md

@@ -0,0 +1,110 @@
+---
+phase: 01-tournament-engine
+task: planning-feedback
+total_tasks: 14 plans (A-N)
+status: in_progress
+last_updated: 2026-03-01T02:16:50.435Z
+---
+
+<current_state>
+Phase 1 planning is complete (14 plans, 6 waves, 68/68 requirements covered). Currently applying security feedback — item 1 of 7 is done, items 2-7 remain. All plans are committed except the security hardening edits.
+</current_state>
+
+<completed_work>
+
+## Planning Pipeline (fully complete)
+- Research: 01-RESEARCH.md written (go-libsql, NATS JetStream, Svelte 5, ICM complexity)
+- Plans A-N created (14 plans, 6 waves)
+- Plan checker: 2 iterations, all blockers resolved (G dep on F, J/L scope splits → M/N)
+- Committed: `21ff950 docs(01): create Phase 1 plans (A-N) with research and feedback`
+
+## User Feedback Round 1 (fully applied, committed)
+- Correction 1: CONTEXT.md — Added hand-for-hand decisions (per-table completion tracking)
+- Correction 2: Plan D/H — Fixed hand-for-hand (removed time deduction, added per-table handCompleted)
+- Correction 3: REQUIREMENTS.md — Reworded SEAT-06 to "tap-tap manual seat moves"
+- Correction 4: Plan C — Removed FIN-14 duplicate (Plan F is sole owner)
+- Correction 5: Plan B — Clarified re-entry clears bust fields
+- Gap 6: CONTEXT.md — Defined punctuality bonus concretely
+- Gap 7: Plan I — Added integration_test.go with full tournament lifecycle
+- Gap 8: Plan A — Health check verifies LibSQL + NATS + hub
+- Gap 9: Plan C — JWT expiry 24h → 7 days
+- Suggestion 10: Plan B — DKK defaults + Copenhagen chip set
+- Suggestion 12: Plan M — Multi-tournament state caching
+- Suggestion 13: Plan K — Removed clock tap-to-pause (FAB only)
+
+## Security Feedback (partially applied)
+- Fix 1 DONE: Plan B — Removed default admin PIN seed, added first-run setup flow + dev-only seed migration
+- Fixes 2-7: NOT YET APPLIED (see remaining_work)
+</completed_work>
+
+<remaining_work>
+
+## Security Fixes (MUST APPLY — continue from fix 2)
+
+### Fix 2: Plan A — Authenticated WebSocket connections
+- Require JWT as query param on /ws?token=...
+- Validate JWT before allowing subscription
+- Enforce tournament scope server-side
+- Validate Origin header, reject unknown origins
+- Edit Plan A task A2 WebSocket hub section
+
+### Fix 3: Plan A — Harden HTTP server baseline
+- Set explicit timeouts: ReadHeaderTimeout(10s), ReadTimeout(30s), WriteTimeout(60s), IdleTimeout(120s), MaxHeaderBytes(1MB)
+- Apply http.MaxBytesReader on all request body reads (default 1MB, larger for CSV import)
+- Edit Plan A task A2 HTTP server section
+
+### Fix 4: Plan B — Audit trail tamper protection triggers
+- SQLite trigger REJECT UPDATE on audit_entries (except undone_by)
+- SQLite trigger REJECT DELETE on audit_entries entirely
+- Add to Plan B task B1 schema migration
+
+### Fix 5: Plan C — Fix JWT validation and PIN rate limiting
+- Enforce HS256 via jwt.WithValidMethods([]string{"HS256"})
+- JWT TTL already 7 days (done in earlier feedback)
+- Persist failed login attempts in LibSQL (not in-memory)
+- Key rate limiting by operator ID (not IP)
+- Emit audit entries for 5+ consecutive failures
+- Defer key rotation to Phase 7
+
+### Fix 6: Plan C/A (NATS) — Validate subject construction
+- UUID validation helper before constructing NATS subjects
+- Apply in internal/nats/publisher.go (Plan A)
+
+### Fix 7: Plan G + Plan F — CSV safety
+- Import limits: max 10,000 rows, 20 columns, 1,000 chars/field
+- Export: neutralize formula injection (prefix =, +, -, @ with tab)
+- Test cases for both
+
+### Also Apply:
+- Keep-as-is item 8: Add TODO comment in Plan J auth store re: Phase 7 HttpOnly cookies
+- Acceptance criteria: Add security acceptance criteria to relevant plan verification sections
+
+### After Security Fixes:
+- Commit all security edits
+- Phase 1 planning is DONE — ready for /gsd:execute-phase 1
+</remaining_work>
+
+<decisions_made>
+
+- Plans split from 12→14: J split into J+M (layout shell), L split into L+N (tables+more) — checker blocker on file count
+- G moved to wave 4 (depends on F for financial engine calls) — checker blocker on missing dependency
+- I moved to wave 5, K/L/N moved to wave 6 — cascading from G wave change
+- Hand-for-hand is per-table completion tracking (not time deduction) — user correction
+- SEAT-06 reworded to tap-tap (not drag-and-drop) — user correction, matches CONTEXT.md locked decision
+- Clock tap-to-pause removed — accidental pause risk, FAB only
+- JWT 7 days not 24h — 12+ hour tournament sessions
+- DKK as default currency — Copenhagen demo venue
+- No default admin PIN in prod — first-run setup screen instead
+</decisions_made>
+
+<blockers>
+None — just need to finish applying security fixes 2-7
+</blockers>
+
+<context>
+The user provided security feedback as a structured list (7 must-apply items, 2 keep-as-is items, acceptance criteria). Fix 1 (Plan B default admin) is applied. The remaining 6 fixes are straightforward edits to existing plan files. All the files have already been read in this session. After applying fixes 2-7, commit, and Phase 1 planning is complete. Next step after planning: /gsd:execute-phase 1.
+</context>
+
+<next_action>
+Start with: Apply security fix 2 (Plan A WebSocket auth) — edit the WebSocket hub section in 01-PLAN-A.md task A2 to require JWT token as query parameter, validate before subscription, enforce tournament scope, validate Origin header. Then continue with fixes 3-7 sequentially, add acceptance criteria to verification sections, commit all.
+</next_action>

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

@@ -0,0 +1,170 @@
+---
+phase: 01-tournament-engine
+plan: 01
+subsystem: infra
+tags: [go, nats, jetstream, libsql, websocket, chi, jwt, embed, sveltekit]
+
+# Dependency graph
+requires: []
+provides:
+  - Go binary scaffold with cmd/leaf entry point
+  - Embedded NATS JetStream with AUDIT and STATE streams
+  - LibSQL database with WAL mode and migration runner
+  - WebSocket hub with JWT auth and tournament-scoped broadcasting
+  - chi HTTP server with middleware (auth, CORS, body limits, timeouts)
+  - SvelteKit SPA stub served via go:embed with fallback routing
+  - Health endpoint reporting all subsystem status
+  - Integration test suite (9 tests)
+affects: [01-tournament-engine]
+
+# Tech tracking
+tech-stack:
+  added:
+    - go-libsql v0.0.0-20251219133454 (pinned commit, no tagged releases)
+    - nats-server v2.12.4 (embedded, JetStream sync=always)
+    - nats.go v1.49.0 (client + jetstream package)
+    - coder/websocket v1.8.14
+    - go-chi/chi v5.2.5
+    - golang-jwt/jwt v5.3.1
+  patterns:
+    - Embedded NATS with DontListen=true, in-process client connection
+    - WebSocket JWT auth via query parameter (not header)
+    - Tournament-scoped broadcasting via client subscription
+    - UUID validation before NATS subject construction (injection prevention)
+    - go:embed SPA with fallback routing for client-side routing
+    - Reverse-order graceful shutdown on signal
+
+key-files:
+  created:
+    - cmd/leaf/main.go
+    - cmd/leaf/main_test.go
+    - internal/nats/embedded.go
+    - internal/nats/publisher.go
+    - internal/server/server.go
+    - internal/server/ws/hub.go
+    - internal/server/middleware/auth.go
+    - internal/server/middleware/role.go
+    - internal/server/middleware/bodylimit.go
+    - internal/store/db.go
+    - internal/store/migrate.go
+    - frontend/embed.go
+    - frontend/build/index.html
+    - Makefile
+    - go.mod
+    - go.sum
+  modified: []
+
+key-decisions:
+  - "NATS JetStreamSyncInterval=0 (sync_interval: always) for single-node durability per Jepsen 2025"
+  - "WebSocket JWT via query parameter rather than header (browser WebSocket API limitation)"
+  - "Ephemeral JWT signing key (generated on startup) — will be persisted in a later plan"
+  - "NATS server requires Go 1.24+ — upgraded from Go 1.23 (auto-resolved by go get)"
+  - "Tournament validator is a stub (accepts all) — will validate against DB in auth plan"
+
+patterns-established:
+  - "Embedded infrastructure: all services start in-process, no external dependencies"
+  - "Tournament-scoped state: all broadcasting and events keyed by tournament ID"
+  - "UUID validation on all NATS subject construction (security)"
+  - "Integration tests with httptest.NewServer and t.TempDir() for isolation"
+
+requirements-completed: [ARCH-01, ARCH-04, ARCH-05, ARCH-06, ARCH-07]
+
+# Metrics
+duration: 15min
+completed: 2026-03-01
+---
+
+# Phase 1 Plan 01: Project Scaffold + Core Infrastructure Summary
+
+**Go binary embedding NATS JetStream (sync=always), LibSQL (WAL), WebSocket hub (JWT auth), chi HTTP server, and SvelteKit SPA via go:embed — all verified with 9 integration tests**
+
+## Performance
+
+- **Duration:** 15 min
+- **Started:** 2026-03-01T02:27:38Z
+- **Completed:** 2026-03-01T02:42:58Z
+- **Tasks:** 2
+- **Files modified:** 48
+
+## Accomplishments
+- Single Go binary compiles and runs with all infrastructure embedded — no external services required
+- NATS JetStream with mandatory sync_interval=always for single-node durability (Jepsen 2025 finding)
+- WebSocket hub authenticates via JWT query param, broadcasts tournament-scoped messages, drops slow consumers
+- Health endpoint reports status of all subsystems (database, NATS, WebSocket)
+- Full directory structure matching research recommendations with 30+ package stubs
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task A1: Initialize Go module and dependency tree** - `af13732` (feat)
+2. **Task A2: Implement core infrastructure** - `16caa12` (feat)
+
+## Files Created/Modified
+- `cmd/leaf/main.go` - Entry point: flags, startup orchestration, signal handling, graceful shutdown
+- `cmd/leaf/main_test.go` - 9 integration tests covering all verification criteria
+- `internal/nats/embedded.go` - Embedded NATS server with JetStream, AUDIT + STATE streams
+- `internal/nats/publisher.go` - Tournament-scoped publisher with UUID validation
+- `internal/server/server.go` - chi HTTP server with middleware, health endpoint, SPA handler
+- `internal/server/ws/hub.go` - WebSocket hub with JWT auth, tournament scoping, broadcasting
+- `internal/server/middleware/auth.go` - JWT validation middleware (Bearer header + raw token)
+- `internal/server/middleware/role.go` - Role-based access control (admin > floor > viewer)
+- `internal/server/middleware/bodylimit.go` - MaxBytesReader middleware (1MB default)
+- `internal/store/db.go` - LibSQL open with WAL, foreign keys, busy timeout
+- `internal/store/migrate.go` - Embedded SQL migration runner with dev-only migrations
+- `frontend/embed.go` - go:embed handler with SPA fallback routing
+- `frontend/build/index.html` - Stub HTML with Catppuccin Mocha dark theme colors
+- `Makefile` - build, run, run-dev, test, frontend, all, clean targets
+- `go.mod` / `go.sum` - Module definition with all dependencies pinned
+
+## Decisions Made
+- NATS server v2.12.4 requires Go 1.24+ — upgraded automatically from 1.23
+- WebSocket JWT passed via query parameter (browser WebSocket API does not support custom headers)
+- JWT signing key is ephemeral (random per startup) — will be persisted to disk in auth plan
+- Tournament validator stub accepts all — real validation deferred to auth/tournament plans
+- Added `run-dev` Makefile target for development mode with seed data
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Store package auto-populated by linter**
+- **Found during:** Task A1 (directory structure creation)
+- **Issue:** The db.go and migrate.go files were auto-populated with full implementations including migration runner, replacing my stub package declarations
+- **Fix:** Kept the auto-populated implementations (correct and useful), removed my redundant migrations.go stub
+- **Files modified:** internal/store/db.go, internal/store/migrate.go
+- **Verification:** go build and go vet pass
+- **Committed in:** af13732 (Task A1 commit)
+
+**2. [Rule 3 - Blocking] Go 1.24 required by NATS server v2.12.4**
+- **Found during:** Task A2 (dependency installation)
+- **Issue:** nats-server v2.12.4 requires go >= 1.24.0, but go.mod specified 1.23.6
+- **Fix:** go toolchain auto-resolved by upgrading go directive to 1.24.0 in go.mod
+- **Files modified:** go.mod
+- **Verification:** go build succeeds, all tests pass
+- **Committed in:** 16caa12 (Task A2 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 blocking)
+**Impact on plan:** Both auto-fixes were necessary for compilation. No scope creep.
+
+## Issues Encountered
+- Go 1.23.6 installed on system but NATS v2.12.4 required Go 1.24+ — resolved automatically by Go toolchain management
+- Port 8080 remained bound after manual server test — cleaned up with lsof before re-test
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Infrastructure scaffold complete — ready for database schema (Plan 02), auth (Plan 03), and all subsequent plans
+- All subsystems verified operational via integration tests
+- Tournament-scoped architecture established from day one (MULTI-01)
+
+## Self-Check: PASSED
+
+All 16 created files verified present. Both commit hashes (af13732, 16caa12) found in git log. SUMMARY.md exists at expected path.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-02-SUMMARY.md

@@ -0,0 +1,154 @@
+---
+phase: 01-tournament-engine
+plan: 02
+subsystem: database
+tags: [libsql, sqlite, fts5, migrations, schema, go-embed]
+
+# Dependency graph
+requires:
+  - phase: none
+    provides: n/a
+provides:
+  - Complete Phase 1 database schema (23 tables)
+  - Embedded migration runner with statement splitting for go-libsql
+  - FTS5 player search with automatic sync triggers
+  - Seed data (venue settings, chip sets)
+  - Dev seed (default admin operator)
+  - First-run setup detection
+affects: [01-tournament-engine, player-management, tournament-runtime, financial-engine]
+
+# Tech tracking
+tech-stack:
+  added: [go-libsql, sqlite-fts5]
+  patterns: [embedded-sql-migrations, statement-splitting, go-embed-migrations, append-only-audit-triggers]
+
+key-files:
+  created:
+    - internal/store/migrations/001_initial_schema.sql
+    - internal/store/migrations/002_fts_indexes.sql
+    - internal/store/migrations/003_seed_data.sql
+    - internal/store/migrations/004_dev_seed.sql
+  modified:
+    - internal/store/migrate.go
+    - internal/store/db.go
+    - cmd/leaf/main.go
+    - Makefile
+
+key-decisions:
+  - "go-libsql requires single-statement Exec: migration runner splits SQL files into individual statements"
+  - "go-libsql PRAGMAs need special handling: journal_mode returns a row (use QueryRow), foreign_keys/busy_timeout use fallback execPragma helper"
+  - "Force single DB connection during migrations (SetMaxOpenConns(1)) to ensure table visibility across migration steps"
+  - "Dev seed (004) is gated by --dev flag, not applied in production mode"
+  - "Bcrypt hash for default admin PIN (1234) generated and embedded in dev seed SQL"
+
+patterns-established:
+  - "Migration files: sequential numbered SQL in internal/store/migrations/, embedded via go:embed"
+  - "Statement splitting: splitStatements() handles triggers (BEGIN...END blocks), comments, and semicolons"
+  - "Financial columns: all INTEGER (int64 cents), zero REAL/FLOAT in schema"
+  - "Audit trail: append-only enforced by SQLite triggers (no UPDATE except undone_by, no DELETE)"
+
+requirements-completed: [ARCH-03, ARCH-08, PLYR-01, PLYR-07, SEAT-01, SEAT-02]
+
+# Metrics
+duration: 10min
+completed: 2026-03-01
+---
+
+# Phase 1 Plan 02: Database Schema + Migrations Summary
+
+**Complete LibSQL schema (23 tables) with embedded migration runner, FTS5 player search, and seed data for tournament engine**
+
+## Performance
+
+- **Duration:** 10 min
+- **Started:** 2026-03-01T02:27:39Z
+- **Completed:** 2026-03-01T02:37:45Z
+- **Tasks:** 2
+- **Files modified:** 8
+
+## Accomplishments
+- 23-table schema covering venue settings, building blocks (chips, blinds, payouts, buy-ins, points), tournament templates, runtime tournaments, players, tables/seating, financial transactions, audit trail, and operators
+- Embedded migration runner that splits SQL into individual statements for go-libsql compatibility
+- FTS5 virtual table on player names/nicknames/emails with automatic sync triggers
+- Audit trail tamper protection via SQLite triggers (reject UPDATE except undone_by, reject DELETE)
+- All financial columns use INTEGER (int64 cents) -- zero REAL/FLOAT in schema
+- Seed data: DKK venue settings, Standard and Copenhagen chip sets with denominations
+- Dev mode: gated admin operator seed (PIN 1234, bcrypt hashed)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task B1: Design and write the initial schema migration** - `17dbfc6` (feat)
+2. **Task B2: Implement migration runner and FTS5 indexes** - `0afa04a` (feat)
+
+## Files Created/Modified
+- `internal/store/migrations/001_initial_schema.sql` - Complete Phase 1 schema (23 tables, indexes, audit triggers)
+- `internal/store/migrations/002_fts_indexes.sql` - FTS5 virtual table and sync triggers for player search
+- `internal/store/migrations/003_seed_data.sql` - Default venue settings and built-in chip sets
+- `internal/store/migrations/004_dev_seed.sql` - Dev-only default admin operator
+- `internal/store/migrate.go` - Embedded migration runner with statement splitting
+- `internal/store/db.go` - Database open/close with PRAGMA configuration and migration wiring
+- `cmd/leaf/main.go` - Dev mode flag and database integration
+- `Makefile` - Added run-dev target
+
+## Decisions Made
+- **go-libsql statement splitting:** go-libsql does not support multi-statement Exec. The migration runner splits each SQL file into individual statements, handling trigger bodies (BEGIN...END blocks) as a single statement.
+- **PRAGMA handling:** go-libsql is inconsistent about which PRAGMAs return rows. `journal_mode=WAL` returns the mode string; `foreign_keys=ON` and `busy_timeout=5000` do not. A fallback `execPragma` helper tries Exec first, falling back to QueryRow.
+- **Single connection during migration:** Forcing `SetMaxOpenConns(1)` during migration ensures all tables created in earlier migrations are visible to later ones (go-libsql connection pooling issue).
+- **Dev seed gating:** The `004_dev_seed.sql` migration is only applied when `--dev` flag is set, preventing default admin credentials in production.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] go-libsql multi-statement Exec does not work**
+- **Found during:** Task B2 (Migration runner implementation)
+- **Issue:** go-libsql's `tx.Exec` with multi-statement SQL silently fails -- tables in 001_initial_schema.sql were not created despite the migration being recorded as applied
+- **Fix:** Implemented `splitStatements()` function that splits SQL files into individual statements, handling trigger BEGIN...END blocks correctly. Removed transaction wrapping since go-libsql single-connection mode ensures atomicity.
+- **Files modified:** internal/store/migrate.go
+- **Verification:** All 4 migrations apply successfully, 23 tables created, second run skips all
+- **Committed in:** 0afa04a
+
+**2. [Rule 1 - Bug] go-libsql PRAGMA handling inconsistency**
+- **Found during:** Task B2 (db.go PRAGMA setup)
+- **Issue:** `PRAGMA journal_mode=WAL` returns a row (Exec fails), `PRAGMA foreign_keys=ON` does not return a row (QueryRow fails). Standard approach of using either Exec or QueryRow for all PRAGMAs doesn't work.
+- **Fix:** Separate handling: QueryRow for journal_mode, execPragma helper (tries Exec, falls back to QueryRow) for others, then verify with getter queries.
+- **Files modified:** internal/store/db.go
+- **Verification:** All PRAGMAs set correctly (journal_mode=wal, foreign_keys=1, busy_timeout=5000)
+- **Committed in:** 0afa04a
+
+**3. [Rule 3 - Blocking] Go and gcc not installed**
+- **Found during:** Task B2 pre-requisite check
+- **Issue:** Go 1.24.1 and gcc were not installed on the system. go-libsql requires CGO (gcc).
+- **Fix:** Installed Go 1.24.1 and gcc/libc6-dev via apt-get
+- **Files modified:** System packages only (not committed)
+- **Verification:** `go version` returns 1.24.1, CGO_ENABLED=1 works
+
+---
+
+**Total deviations:** 3 auto-fixed (1 bug, 2 blocking)
+**Impact on plan:** All auto-fixes necessary for go-libsql compatibility. The statement-splitting pattern is essential for the migration system to work at all. No scope creep.
+
+## Issues Encountered
+- go-libsql connection pooling causes table visibility issues across migrations -- resolved by forcing single connection with SetMaxOpenConns(1)
+- Plan A (project scaffold) was executed concurrently, committing some of Plan B's files (db.go, main.go, Makefile) in its scaffold commit. This did not cause issues but meant Task B2's commit only included the migrate.go fix.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Database schema complete for all Phase 1 features
+- Migration system ready for future schema changes (add new numbered SQL files)
+- FTS5 player search operational for typeahead
+- Audit trail tamper protection active
+- Ready for Plan C (Auth/Operators) and Plan D (Player Management)
+
+## Self-Check: PASSED
+
+- All 9 files verified present
+- Both task commits (17dbfc6, 0afa04a) verified in git log
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-03-SUMMARY.md

@@ -0,0 +1,164 @@
+---
+phase: 01-tournament-engine
+plan: 03
+subsystem: auth-audit
+tags: [jwt, bcrypt, pin-auth, rate-limiting, audit-trail, undo-engine, hs256, nats-jetstream]
+
+# Dependency graph
+requires:
+  - phase: 01-01
+    provides: HTTP server, NATS JetStream, WebSocket hub
+  - phase: 01-02
+    provides: Database schema (operators, audit_entries, login_attempts tables)
+provides:
+  - PIN-based operator authentication with JWT issuance
+  - HS256-enforced JWT validation middleware with role extraction
+  - Auth HTTP routes (login, me, logout)
+  - Append-only audit trail with LibSQL persistence and NATS publishing
+  - Undo engine with reversal entries and double-undo protection
+  - Auth-to-audit bridge via RecorderFunc callback
+affects: [01-tournament-engine, financial-engine, player-management, clock-engine]
+
+# Tech tracking
+tech-stack:
+  added: [golang-jwt-v5, bcrypt]
+  patterns: [pin-scan-auth, rate-limiting-libsql, audit-recorder-callback, append-only-audit, reversal-entries]
+
+key-files:
+  created:
+    - internal/auth/pin_test.go
+    - internal/server/routes/auth.go
+    - internal/audit/trail_test.go
+    - internal/audit/undo_test.go
+  modified:
+    - internal/auth/jwt.go
+    - internal/auth/pin.go
+    - internal/audit/trail.go
+    - internal/audit/undo.go
+    - internal/server/middleware/auth.go
+    - internal/server/server.go
+    - cmd/leaf/main.go
+    - cmd/leaf/main_test.go
+
+key-decisions:
+  - "JWT HS256 enforcement via jwt.WithValidMethods prevents algorithm confusion attacks"
+  - "Rate limiting keyed by global sentinel (_global) since PINs are scanned across all operators"
+  - "AuditRecorder callback type breaks import cycle between auth and audit packages"
+  - "Audit timestamps stored as epoch seconds in SQLite, converted to/from nanoseconds in Go"
+  - "NATS publish is best-effort (logged, not fatal) to avoid audit trail failures blocking mutations"
+  - "Undo creates reversal entry (never deletes) -- only exception is marking undone_by on original"
+
+patterns-established:
+  - "Auth middleware extracts JWT claims to context (OperatorIDKey, OperatorRoleKey)"
+  - "Audit recorder as callback function to decouple auth package from audit package"
+  - "Mock publisher interface for testing audit NATS integration without real NATS"
+  - "Rate limit thresholds: 5 failures = 30s, 8 = 5min, 10 = 30min lockout"
+
+requirements-completed: [AUTH-01, AUTH-03, ARCH-08, PLYR-06]
+
+# Metrics
+duration: 5min
+completed: 2026-03-01
+---
+
+# Phase 1 Plan 03: Authentication + Audit Trail + Undo Engine Summary
+
+**PIN auth with HS256 JWT, bcrypt rate limiting in LibSQL, append-only audit trail with NATS publishing, and reversal-based undo engine**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-01T02:58:26Z
+- **Completed:** 2026-03-01T03:03:22Z
+- **Tasks:** 2
+- **Files modified:** 12
+
+## Accomplishments
+
+- PIN-based authentication scanning all operators via bcrypt, issuing HS256 JWT with role claims (admin/floor/viewer)
+- Rate limiting persisted in LibSQL login_attempts table with exponential backoff (5/8/10 failure thresholds)
+- JWT validation enforces HS256 via WithValidMethods to prevent algorithm confusion attacks
+- Auth HTTP routes: POST /api/v1/auth/login, GET /api/v1/auth/me, POST /api/v1/auth/logout
+- JWT signing key generated on first startup and persisted in _config table
+- Append-only audit trail with 30+ action constants covering all domain mutations
+- NATS JetStream publishing for tournament-scoped audit events (best-effort, non-blocking)
+- Undo engine creating reversal entries that swap previous/new state -- never deletes originals
+- Double-undo protection via undone_by field (tamper-protected by SQLite triggers)
+- RecorderFunc bridges auth package to audit trail without import cycles
+- 11 unit tests for auth package, 6 integration tests for auth HTTP endpoints
+- 10 audit trail tests, 8 undo engine tests -- all passing
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task C1: Implement PIN authentication with JWT issuance** - `dd2f9bb` (feat)
+   - Auth routes, HS256 enforcement, context helpers, comprehensive test suite
+2. **Task C2: Implement audit trail and undo engine** - Previously committed in `1978d3d`
+   - Trail, undo engine, action constants, tests were auto-populated during Plan 05 execution
+
+## Files Created/Modified
+
+- `internal/auth/jwt.go` - JWT service with HS256 enforcement, signing key persistence
+- `internal/auth/pin.go` - AuthService with PIN login, rate limiting, operator CRUD
+- `internal/auth/pin_test.go` - 11 comprehensive auth unit tests
+- `internal/server/middleware/auth.go` - JWT middleware with WithValidMethods, context helpers
+- `internal/server/middleware/role.go` - Role hierarchy middleware (admin > floor > viewer)
+- `internal/server/routes/auth.go` - Auth HTTP handlers (login, me, logout)
+- `internal/audit/trail.go` - AuditTrail with LibSQL persistence, NATS publishing, 30+ action constants
+- `internal/audit/undo.go` - UndoEngine with reversal entries, undoable action whitelist
+- `internal/audit/trail_test.go` - 10 audit trail tests (persistence, NATS, pagination, filtering)
+- `internal/audit/undo_test.go` - 8 undo engine tests (reversal, double-undo, non-undoable actions)
+- `internal/server/server.go` - Updated with authService and clockRegistry parameters
+- `cmd/leaf/main.go` - Auth service creation with persisted signing key
+
+## Decisions Made
+
+- **HS256 enforcement:** JWT validation uses both method type check and WithValidMethods([]string{"HS256"}) -- belt AND suspenders against algorithm confusion attacks.
+- **Global rate limiting key:** Since PINs are compared against all operators (scan), failures are recorded against a "_global" sentinel key rather than per-operator. Resets on any successful login.
+- **Audit recorder callback:** The auth package defines an AuditRecorder function type and calls it for login events. The audit package provides RecorderFunc() that creates this callback. This avoids circular imports.
+- **Best-effort NATS publishing:** Audit trail records to LibSQL first (source of truth), then publishes to NATS. NATS failures are logged but don't fail the operation -- prevents audit infrastructure issues from blocking game actions.
+- **Timestamp dual representation:** SQLite stores epoch seconds (schema default). Go layer converts to/from nanoseconds for precision. GetEntry/GetEntries multiply by 1e9 when reading.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Task C2 code already committed by previous session**
+- **Found during:** Task C2 staging
+- **Issue:** The audit trail and undo engine code (trail.go, undo.go, trail_test.go, undo_test.go) had been auto-populated and committed in commit `1978d3d` during Plan 05 execution. My Write operations produced identical code to what was already committed, resulting in zero git diff.
+- **Fix:** Verified all 18 audit tests pass. No commit needed since code was already in the repository.
+- **Impact:** None -- the implementation matches the plan requirements exactly.
+
+No other deviations. Plan executed as written.
+
+## Verification Results
+
+1. PIN login with "1234" produces valid JWT with role claims -- PASS
+2. Auth middleware rejects requests without valid JWT (401) -- PASS
+3. Role middleware enforces admin/floor/viewer hierarchy -- PASS
+4. Rate limiting activates after 5 failed login attempts -- PASS
+5. Audit entries persist to LibSQL with all fields -- PASS
+6. NATS JetStream receives audit events on correct subject -- PASS (mock)
+7. Undo creates reversal entry and marks original -- PASS
+8. Double-undo is rejected with clear error -- PASS
+9. All 35 tests pass (11 auth + 6 integration + 10 trail + 8 undo) -- PASS
+
+## Next Phase Readiness
+
+- Auth middleware available for all protected routes in subsequent plans
+- Audit trail ready as cross-cutting concern for financial, player, and seat mutations
+- Undo engine ready for financial transactions and bust-out reversals
+- Rate limiting and signing key persistence operational
+- Ready for Plan F (Financial Engine), Plan G (Player Management)
+
+## Self-Check: PASSED
+
+- All 12 key files verified present
+- Task C1 commit (dd2f9bb) verified in git log
+- Task C2 code verified present (committed in 1978d3d)
+- All 35 tests pass
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-04-SUMMARY.md

@@ -0,0 +1,153 @@
+---
+phase: 01-tournament-engine
+plan: 04
+subsystem: api
+tags: [go, clock, websocket, ticker, state-machine, warnings, chi, rest-api]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: LibSQL database with blind_levels table, WebSocket hub, chi HTTP server, JWT auth middleware
+provides:
+  - Server-authoritative clock engine with state machine (stopped/running/paused)
+  - Drift-free ticker with 1/sec normal and 10/sec final 10s broadcast
+  - Clock registry for multi-tournament support (thread-safe)
+  - Clock API routes (start, pause, resume, advance, rewind, jump, get, warnings)
+  - Configurable warning thresholds with WebSocket events
+  - Clock state persistence to DB for crash recovery
+  - ClockSnapshot for reconnecting clients
+affects: [01-tournament-engine, display-views, player-pwa]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Clock state machine with mutex-protected transitions
+    - Ticker goroutine with 100ms resolution using monotonic clock
+    - Broadcast rate adaptation (1/sec normal, 10/sec final 10s)
+    - State change callbacks for async DB persistence
+    - Crash recovery restores as paused (operator must explicitly resume)
+    - ClockSnapshot as single source of truth for all client communication
+
+key-files:
+  created:
+    - internal/clock/engine.go
+    - internal/clock/ticker.go
+    - internal/clock/registry.go
+    - internal/clock/warnings.go
+    - internal/clock/engine_test.go
+    - internal/clock/warnings_test.go
+    - internal/clock/registry_test.go
+    - internal/server/routes/clock.go
+  modified:
+    - internal/server/server.go
+    - cmd/leaf/main.go
+    - cmd/leaf/main_test.go
+    - internal/auth/pin.go
+
+key-decisions:
+  - "Clock ticker uses 100ms resolution with broadcast gating (not two separate tickers) for simplicity"
+  - "Crash recovery always restores clock as paused -- operator must explicitly resume for safety"
+  - "Overtime mode defaults to repeat (last level repeats indefinitely) with configurable stop option"
+  - "State change callback is async (goroutine) to avoid holding clock mutex during DB writes"
+  - "Clock routes use chi sub-router with floor role requirement on mutations"
+
+patterns-established:
+  - "AuditRecorder interface for decoupled audit trail recording (avoids circular imports)"
+  - "StateChangeCallback pattern for async persistence on meaningful state changes"
+  - "Registry pattern for managing multiple concurrent engines per tournament"
+
+requirements-completed: [CLOCK-01, CLOCK-02, CLOCK-03, CLOCK-04, CLOCK-05, CLOCK-06, CLOCK-07, CLOCK-08, CLOCK-09]
+
+# Metrics
+duration: 8min
+completed: 2026-03-01
+---
+
+# Phase 1 Plan 04: Clock Engine Summary
+
+**Server-authoritative tournament clock with state machine, drift-free 100ms ticker, configurable warnings, multi-tournament registry, REST API, and DB persistence -- verified with 25 unit tests**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-03-01T02:48:21Z
+- **Completed:** 2026-03-01T02:56:31Z
+- **Tasks:** 2
+- **Files modified:** 12
+
+## Accomplishments
+- Complete clock state machine (stopped/running/paused) with all transitions and guard conditions
+- Drift-free ticker using Go monotonic clock at 100ms resolution with adaptive broadcast rate
+- Multi-tournament clock registry with independent engines and per-engine ticker goroutines
+- Full REST API with role-based access (floor+ for mutations, any auth for reads)
+- Configurable warning thresholds (default 60s/30s/10s) with WebSocket events
+- Clock state persisted to DB on every meaningful state change for crash recovery
+- Hand-for-hand mode support (clock pauses, per-table deduction via seating engine)
+- Overtime handling (repeat last level or stop -- configurable)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task D1: Clock engine state machine and ticker** - `9ce05f6` (feat)
+2. **Task D2: Warnings, API routes, tests, and server wiring** - `ae90d9b` (feat)
+
+## Files Created/Modified
+- `internal/clock/engine.go` - ClockEngine state machine, Level/Warning/Snapshot structs, all operations
+- `internal/clock/ticker.go` - StartTicker with 100ms resolution and adaptive broadcast rate
+- `internal/clock/registry.go` - Thread-safe ClockRegistry managing multiple engines
+- `internal/clock/warnings.go` - Warning system documentation (logic in engine.go)
+- `internal/clock/engine_test.go` - 16 tests: state machine, countdown, auto-advance, pause/resume, jump, rewind, hand-for-hand, snapshot, overtime, crash recovery
+- `internal/clock/warnings_test.go` - 5 tests: threshold detection, no re-emit, reset on level change, defaults, custom
+- `internal/clock/registry_test.go` - 4 tests: get/create, get, remove, shutdown
+- `internal/server/routes/clock.go` - 8 API endpoints with DB integration and role-based access
+- `internal/server/server.go` - Clock registry wired into server constructor and route registration
+- `cmd/leaf/main.go` - Clock registry created during startup, shutdown on exit
+- `cmd/leaf/main_test.go` - Test setup updated with clock registry parameter
+- `internal/auth/pin.go` - Fix missing crypto/rand import (auto-fix)
+
+## Decisions Made
+- Clock ticker uses single 100ms timer with broadcast gating rather than two separate tickers (simpler, same result)
+- Crash recovery always restores as paused -- safer than auto-resuming with potentially stale remaining time
+- Overtime defaults to repeat mode (most common in poker tournaments)
+- State change callback runs in a goroutine to prevent DB latency from blocking the clock ticker
+- AuditRecorder is an interface (not direct import) to avoid circular dependency between clock and audit packages
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Missing crypto/rand import in auth/pin.go**
+- **Found during:** Task D2 (compiling routes package which depends on auth)
+- **Issue:** internal/auth/pin.go uses `rand.Read` but was missing `crypto/rand` import, preventing compilation of the routes package
+- **Fix:** Added `"crypto/rand"` to the import block
+- **Files modified:** internal/auth/pin.go
+- **Verification:** `go build ./...` passes, `go vet ./...` passes
+- **Committed in:** ae90d9b (Task D2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Single missing import in a dependency. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Clock engine fully operational for all tournament clock requirements
+- API endpoints ready for frontend integration (Plan K/L)
+- Clock registry supports multi-tournament operation (MULTI-01)
+- Warning events ready for display views (Phase 2)
+- DB persistence ensures clock survives server restart
+
+## Self-Check: PASSED
+
+All 8 created files verified present. Both commit hashes (9ce05f6, ae90d9b) found in git log. SUMMARY.md exists at expected path.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-05-SUMMARY.md

@@ -0,0 +1,140 @@
+---
+phase: 01-tournament-engine
+plan: 05
+subsystem: api, database, template
+tags: [go, crud, blind-structure, chip-set, payout, buyin, wizard, tournament-template, chi, libsql]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine (Plan A)
+    provides: Project scaffold, chi router, middleware, store layer
+  - phase: 01-tournament-engine (Plan B)
+    provides: Database schema with all building block tables
+provides:
+  - ChipSet CRUD service with denomination management
+  - BlindStructure CRUD service with level validation
+  - PayoutStructure CRUD service with bracket/tier nesting and 100% sum validation
+  - BuyinConfig CRUD service with rake split validation
+  - TournamentTemplate CRUD service with FK validation and expanded view
+  - Structure wizard algorithm (geometric progression, denomination snapping, break insertion)
+  - 4 built-in blind structures (Turbo, Standard, Deep Stack, WSOP-style)
+  - Built-in payout structure with 4 entry-count brackets
+  - 4 built-in buy-in configs with rake splits
+  - 4 built-in tournament templates composing all above
+  - Full REST API for all building blocks and templates
+affects: [tournament-lifecycle, frontend-templates, clock-engine]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Service-per-entity CRUD pattern with *sql.DB injection
+    - Transaction-based create/update with nested entity replacement
+    - FK reference validation before template creation
+    - Expanded view pattern (GetTemplate vs GetTemplateExpanded)
+    - Seed migration with INSERT OR IGNORE for idempotent built-in data
+
+key-files:
+  created:
+    - internal/template/chipset.go
+    - internal/template/payout.go
+    - internal/template/buyin.go
+    - internal/template/tournament.go
+    - internal/blind/structure.go
+    - internal/blind/wizard.go
+    - internal/blind/templates.go
+    - internal/server/routes/templates.go
+    - internal/store/migrations/005_builtin_templates.sql
+    - internal/blind/wizard_test.go
+    - internal/template/tournament_test.go
+  modified:
+    - internal/server/server.go
+
+key-decisions:
+  - "Seed data uses INSERT OR IGNORE with explicit IDs for idempotent re-runs"
+  - "Wizard generates preview-only levels (not auto-saved) for TD review"
+  - "BB ante used in WSOP-style template (separate from standard ante field)"
+  - "Payout brackets must be contiguous ranges (no gaps between min/max entries)"
+
+patterns-established:
+  - "Service CRUD pattern: NewXService(db) with Create/Get/List/Update/Delete/Duplicate"
+  - "Nested entity pattern: replace-all on update (delete children, re-insert)"
+  - "Route registration: Register(chi.Router) method for modular route mounting"
+
+requirements-completed: [BLIND-01, BLIND-02, BLIND-03, BLIND-04, BLIND-05, BLIND-06, CHIP-01, CHIP-02, CHIP-03, CHIP-04, FIN-01, FIN-02, FIN-05, FIN-06, FIN-10]
+
+# Metrics
+duration: 10min
+completed: 2026-03-01
+---
+
+# Plan 05: Blind Structure + Chip Sets + Templates Summary
+
+**Full CRUD for all building blocks (chip sets, blind structures, payouts, buy-ins) with 4 built-in tournament templates, structure wizard algorithm, and REST API endpoints**
+
+## Performance
+
+- **Duration:** 10 min
+- **Started:** 2026-03-01T02:48:52Z
+- **Completed:** 2026-03-01T02:58:52Z
+- **Tasks:** 2
+- **Files modified:** 12
+
+## Accomplishments
+- Complete CRUD services for all 5 building block types with validation, duplication, and builtin protection
+- Structure wizard generates blind structures from high-level inputs (player count, chips, duration, denominations) using geometric progression with denomination snapping
+- 4 built-in tournament templates (Turbo, Standard, Deep Stack, WSOP-style) with matching blind structures, buy-in configs, and shared payout structure
+- Full REST API with admin-gated mutations and floor-accessible reads
+- Comprehensive test suites for wizard (6 tests) and templates (7 tests), all passing
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task E1: Building block CRUD and API routes** - `99545bd` (feat)
+2. **Task E2: Built-in templates, seed data, wizard tests, template tests** - `7dbb4ca` (feat)
+
+## Files Created/Modified
+- `internal/template/chipset.go` - ChipSet CRUD service with denomination management
+- `internal/template/payout.go` - PayoutStructure CRUD with bracket/tier nesting and 100% sum validation
+- `internal/template/buyin.go` - BuyinConfig CRUD with rake split validation
+- `internal/template/tournament.go` - TournamentTemplate CRUD with FK validation, expanded view, SaveAsTemplate
+- `internal/blind/structure.go` - BlindStructure CRUD with level validation (contiguous positions, SB < BB)
+- `internal/blind/wizard.go` - Structure wizard: geometric progression, denomination snapping, break insertion, chip-up markers
+- `internal/blind/templates.go` - Built-in level definitions (Turbo, Standard, Deep Stack, WSOP-style)
+- `internal/server/routes/templates.go` - REST API handlers for all building blocks and templates
+- `internal/store/migrations/005_builtin_templates.sql` - Seed data for 4 blind structures, 1 payout structure, 4 buy-in configs, 4 tournament templates
+- `internal/blind/wizard_test.go` - Wizard tests: standard, player counts, denomination alignment, short/long, invalid inputs
+- `internal/template/tournament_test.go` - Template tests: create, invalid FK, expanded, save-as, duplicate, delete-builtin, list
+- `internal/server/server.go` - Wired template routes into protected API group
+
+## Decisions Made
+- Seed data uses INSERT OR IGNORE with explicit integer IDs for idempotent migration re-runs
+- Wizard generates preview-only levels (not auto-saved) so the TD can review and adjust before saving
+- WSOP-style blind structure uses BB ante (separate field from standard ante) starting at level 4
+- Payout bracket validation enforces contiguous entry count ranges with no gaps
+- All built-in entities use is_builtin=1 flag -- cannot be deleted but can be duplicated
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- Pre-existing test failure in `cmd/leaf/main_test.go` (missing `clockRegistry` parameter from Plan D) -- out of scope, not caused by this plan
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- All building blocks have full CRUD with API endpoints -- ready for frontend template management UI
+- Tournament templates compose building blocks by reference -- ready for tournament creation flow
+- Structure wizard is functional -- ready for frontend wizard UI
+- Built-in templates exist on first boot -- ready for template-first tournament creation
+
+## Self-Check: PASSED
+
+All 11 created files verified on disk. Both task commits (99545bd, 7dbb4ca) found in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-06-SUMMARY.md

@@ -0,0 +1,131 @@
+---
+phase: 01-tournament-engine
+plan: 06
+subsystem: financial
+tags: [int64, poker, buyin, rebuy, payout, bounty, pko, receipt, audit, rake]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine/plan-03
+    provides: audit trail and undo engine
+  - phase: 01-tournament-engine/plan-05
+    provides: buyin configs with rake splits, payout structures with brackets
+provides:
+  - Financial transaction engine (buy-in, rebuy, add-on, re-entry)
+  - PKO bounty transfer with half-split chain tracking
+  - Prize pool calculation from all transaction types
+  - Payout distribution with int64 rounding (round DOWN, remainder to 1st)
+  - CI gate test proving sum(payouts) == prize_pool across 10,000+ inputs
+  - Bubble prize proposal/confirm with proportional shaving
+  - Receipt generation with sequential numbering and reprint
+  - Late registration with level AND time cutoffs plus admin override
+  - Season reserve tracking via rake split categories
+  - Financial API routes (prize-pool, payouts, transactions, receipts)
+affects: [01-tournament-engine/plan-07, 01-tournament-engine/plan-09, 01-tournament-engine/plan-12]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "int64 cents for all monetary values (zero float64)"
+    - "Round DOWN to venue denomination, remainder to 1st place"
+    - "Property-based CI gate test with 10,000+ random payout combinations"
+    - "Rake split transactions per category (house, staff, league, season_reserve)"
+    - "Proportional rake scaling for rebuy/addon (different rake amounts)"
+
+key-files:
+  created:
+    - internal/financial/engine.go
+    - internal/financial/engine_test.go
+    - internal/financial/payout.go
+    - internal/financial/payout_test.go
+    - internal/financial/receipt.go
+    - internal/server/routes/financials.go
+  modified: []
+
+key-decisions:
+  - "PKO bounty half-split uses integer division (half = bountyValue/2, remainder stays with bounty portion)"
+  - "Unique entry count for bracket selection uses COUNT(DISTINCT player_id) on non-undone buyin transactions"
+  - "Rebuy/addon rake splits are proportionally scaled from buyin rake splits"
+  - "Receipt number is sequential per tournament (COUNT of existing receipts + 1)"
+  - "Bubble prize shaves proportionally from top 3 positions, extending to 5 if needed"
+  - "Late reg checks level AND time cutoffs independently (either exceeded closes registration)"
+
+patterns-established:
+  - "Financial engine pattern: load tournament info, load buyin config, validate, create transaction, audit, broadcast"
+  - "CalculatePayoutsFromPool is a pure function for testability and CI gate"
+  - "Transaction undo marks undone=1 and reverses player state effects"
+
+requirements-completed: [FIN-03, FIN-04, FIN-07, FIN-08, FIN-09, FIN-12, FIN-13, FIN-14]
+
+# Metrics
+duration: 9min
+completed: 2026-03-01
+---
+
+# Plan 06: Financial Engine Summary
+
+**Int64 financial engine with buy-in/rebuy/addon/re-entry transactions, PKO bounty half-split, payout calculation with CI gate (10,000+ tests, zero deviation), bubble prize, receipts, and late registration cutoffs**
+
+## Performance
+
+- **Duration:** 9 min
+- **Started:** 2026-03-01T03:06:59Z
+- **Completed:** 2026-03-01T03:16:22Z
+- **Tasks:** 2
+- **Files created:** 6
+
+## Accomplishments
+- Full financial transaction engine processing buy-ins, rebuys, add-ons, re-entries with all validation checks
+- PKO progressive knockout bounty transfer with half cash / half bounty split and chain tracking
+- CI gate test proving sum(payouts) == prize_pool across 10,000+ random combinations -- zero deviation
+- Prize pool auto-calculation from all non-undone transactions minus categorized rake
+- Late registration enforcement with level AND time cutoffs, admin override logged in audit trail
+- Receipt generation with sequential numbering, venue info, and reprint capability
+- Financial API routes for prize pool, payouts, transactions, receipts, bubble prize, and season reserves
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task F1: Financial transaction engine** - `51153df` (feat)
+2. **Task F2: Prize pool, payouts, receipts, and API routes** - `56a7ef1` (feat)
+
+## Files Created/Modified
+- `internal/financial/engine.go` - Financial transaction engine (buy-in, rebuy, addon, re-entry, bounty, undo)
+- `internal/financial/engine_test.go` - 14 tests for all transaction flows and edge cases
+- `internal/financial/payout.go` - Prize pool calculation, payout distribution, bubble prize
+- `internal/financial/payout_test.go` - 7 tests including CI gate (10,000+ random combinations)
+- `internal/financial/receipt.go` - Receipt generation, retrieval, and reprint
+- `internal/server/routes/financials.go` - API routes for all financial endpoints
+
+## Decisions Made
+- PKO bounty half-split uses integer division: cashPortion = bountyValue/2, bountyPortion = bountyValue - cashPortion (handles odd cents correctly)
+- Unique entry count for payout bracket selection uses COUNT(DISTINCT player_id) on non-undone buyin transactions only (not rebuys, not re-entries)
+- Rebuy and addon rake splits are proportionally scaled from the buyin rake split amounts (last split gets remainder for exact sum)
+- Receipt numbering is sequential per tournament based on count of existing receipts
+- Bubble prize shaves proportionally from top 3 positions, extending to top 5 if the top 3 cannot cover the amount
+- Late registration checks level AND time cutoffs independently -- if either is exceeded, registration closes
+- Rounding denomination loaded from venue_settings (default 100 cents if not configured)
+- Guaranteed pot support: if FinalPrizePool < Guarantee, HouseContribution = Guarantee - PrizePool
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- Task F2 files were inadvertently included in a prior session's docs commit (56a7ef1) alongside the SUMMARY.md for plan 13. The code content is correct and complete.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Financial engine ready for player management (Plan G) to call ProcessBuyIn/ProcessRebuy on player actions
+- Payout calculation ready for tournament completion (Plan I) to apply final payouts
+- Season reserve tracking ready for multi-tournament views (Plan L)
+- All 21 tests passing, full project builds cleanly
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-07-SUMMARY.md

@@ -0,0 +1,146 @@
+---
+phase: 01-tournament-engine
+plan: "07"
+subsystem: api, database
+tags: [player, fts5, qrcode, csv-import, ranking, bounty, pko, undo]
+
+requires:
+  - phase: 01-tournament-engine
+    provides: "audit trail + undo engine (Plan C), financial engine (Plan F), seating engine (Plan H), schema with FTS5 (Plan B)"
+provides:
+  - "PlayerService with CRUD, FTS5 typeahead search, merge, CSV import"
+  - "QR code generation per player (felt://player/{uuid})"
+  - "Tournament player operations: register, bust, undo bust"
+  - "RankingEngine deriving positions from bust-out order"
+  - "Player API routes for venue-level and tournament-scoped operations"
+  - "Buy-in flow: register + financial + auto-seat"
+  - "Bust flow: hitman + bounty + rank + balance check"
+  - "CSV export safety: formula injection neutralization"
+affects: [09-tournament-lifecycle, 11-tournament-ui, 14-integration]
+
+tech-stack:
+  added: [skip2/go-qrcode]
+  patterns: [derived-rankings, csv-formula-injection-safety, fts5-prefix-matching]
+
+key-files:
+  created:
+    - internal/player/player.go
+    - internal/player/ranking.go
+    - internal/player/qrcode.go
+    - internal/player/export.go
+    - internal/server/routes/players.go
+    - internal/player/ranking_test.go
+    - internal/player/player_test.go
+  modified:
+    - go.mod
+    - go.sum
+
+key-decisions:
+  - "Rankings derived from bust_out_at timestamps, never stored independently (Pitfall 6)"
+  - "RecalculateAllRankings rebuilds all bust_out_order values from timestamps for undo consistency"
+  - "FTS5 query terms wrapped in quotes with * suffix for prefix matching"
+  - "CSV formula injection neutralized with tab prefix on =, +, -, @ characters"
+  - "Buy-in flow auto-registers player if not yet in tournament"
+  - "QR code URL format: felt://player/{uuid} for future PWA self-check-in"
+
+patterns-established:
+  - "Derived rankings: always compute from bust-out list, never store"
+  - "CSV export safety: SanitizeCSVField for any user data in CSV output"
+  - "Player API pattern: venue-level CRUD + tournament-scoped actions"
+
+requirements-completed: [PLYR-02, PLYR-03, PLYR-04, PLYR-05, PLYR-06, PLYR-07]
+
+duration: 7min
+completed: 2026-03-01
+---
+
+# Plan 07: Player Management Summary
+
+**Player CRUD with FTS5 typeahead, CSV import, QR codes, bust/undo flows with derived rankings from bust-out order**
+
+## Performance
+
+- **Duration:** 7 min
+- **Started:** 2026-03-01T03:27:50Z
+- **Completed:** 2026-03-01T03:35:13Z
+- **Tasks:** 2
+- **Files modified:** 9
+
+## Accomplishments
+- Full player service with CRUD, FTS5 prefix-matching search, merge, CSV import with safety limits
+- QR code generation per player using skip2/go-qrcode (felt://player/{uuid})
+- Tournament player operations: register, bust (with PKO bounty), undo bust with re-ranking
+- RankingEngine that derives all positions from ordered bust-out list (never stored)
+- Complete player API routes: venue-level CRUD + tournament-scoped actions + rankings
+- CSV export formula injection neutralization (tab-prefix on =, +, -, @)
+- 12 passing tests covering ranking derivation, undo re-ranking, re-entry, deals, concurrency
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task G1: Player CRUD, search, merge, import, QR codes** - `9373628` (feat)
+2. **Task G2: Ranking engine and player API routes** - `8b4b131` (feat)
+
+## Files Created/Modified
+- `internal/player/player.go` - PlayerService with CRUD, search, merge, import, bust, undo
+- `internal/player/ranking.go` - RankingEngine deriving positions from bust-out order
+- `internal/player/qrcode.go` - QR code generation using skip2/go-qrcode
+- `internal/player/export.go` - CSV export safety: formula injection neutralization
+- `internal/server/routes/players.go` - PlayerHandler with venue-level and tournament-scoped routes
+- `internal/player/ranking_test.go` - 7 ranking tests (bust order, undo, re-entry, deals, concurrency)
+- `internal/player/player_test.go` - 5 tests (CSV safety, import limits, UUID)
+- `go.mod` - Added skip2/go-qrcode dependency
+- `go.sum` - Updated checksums
+
+## Decisions Made
+- Rankings derived from bust_out_at timestamps via RecalculateAllRankings (not stored independently per Pitfall 6)
+- FTS5 queries use quoted terms with * suffix for prefix matching
+- CSV formula injection neutralized with tab prefix on =, +, -, @ characters
+- Buy-in flow auto-registers player in tournament_players if not already present
+- QR code URL format: felt://player/{uuid} for future PWA self-check-in
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Installed skip2/go-qrcode dependency**
+- **Found during:** Task G1 (QR code generation)
+- **Issue:** No QR code library in go.mod
+- **Fix:** Ran `go get github.com/skip2/go-qrcode`
+- **Files modified:** go.mod, go.sum
+- **Verification:** QR code generation compiles and encodes valid PNG
+- **Committed in:** 9373628 (Task G1 commit)
+
+**2. [Rule 3 - Blocking] Created RankingEngine in Task G1 (planned for G2)**
+- **Found during:** Task G1 (UndoBust implementation)
+- **Issue:** UndoBust calls RecalculateAllRankings which requires the RankingEngine
+- **Fix:** Implemented RankingEngine in ranking.go as part of Task G1
+- **Files modified:** internal/player/ranking.go
+- **Verification:** Package compiles, tests pass
+- **Committed in:** 9373628 (Task G1 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 blocking)
+**Impact on plan:** Both auto-fixes necessary for compilation and correctness. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Player management API is complete and ready for tournament lifecycle integration (Plan I)
+- Ranking engine provides derived rankings for the clock/tournament UI
+- Buy-in and bust flows integrate with financial engine and seating engine
+- CSV import and merge provide player database management for TDs
+
+## Self-Check: PASSED
+
+All 7 created files verified on disk. Both task commits (9373628, 8b4b131) verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-08-SUMMARY.md

@@ -0,0 +1,104 @@
+---
+phase: 01-tournament-engine
+plan: 08
+subsystem: seating
+tags: [table-balancing, break-table, tda-rules, auto-seating, dealer-button, hand-for-hand, chi-router]
+
+requires:
+  - phase: 01-tournament-engine
+    provides: "table schema, tournament_players schema, audit trail, WebSocket hub, clock registry"
+provides:
+  - "BalanceEngine with TDA-compliant suggestion generation and live-adaptive invalidation"
+  - "BreakTableService for fully automatic player redistribution"
+  - "Full REST API for tables, seating, balancing, blueprints, dealer button, hand-for-hand"
+  - "TableService.DB() accessor for cross-service database access"
+affects: [02-multi-device, frontend-tournament-view]
+
+tech-stack:
+  added: []
+  patterns: [live-adaptive-suggestions, stale-detection-on-accept, clockwise-distance-fairness]
+
+key-files:
+  created:
+    - internal/seating/balance.go
+    - internal/seating/breaktable.go
+    - internal/seating/balance_test.go
+    - internal/seating/breaktable_test.go
+    - internal/server/routes/tables.go
+  modified:
+    - internal/seating/table.go
+
+key-decisions:
+  - "Balance suggestions use clockwise distance from dealer button for move fairness (player closest after button moves first)"
+  - "Stale suggestion re-validation requires fromCount - toCount >= 2 before accepting (ensures move still needed)"
+  - "Break table is fully automatic (applies immediately, result is informational per CONTEXT.md)"
+  - "Blueprint routes are venue-level (not tournament-scoped); admin role required for mutations"
+
+patterns-established:
+  - "Live-adaptive pattern: suggestions are proposals that are re-validated on accept and invalidated on state change"
+  - "Break table distributes by iterating sorted destination tables (ascending player count) for each player"
+
+requirements-completed: [SEAT-01, SEAT-02, SEAT-03, SEAT-04, SEAT-05, SEAT-06, SEAT-07, SEAT-08, SEAT-09]
+
+duration: 6min
+completed: 2026-03-01
+---
+
+# Phase 1 Plan 8: Table & Seating Engine Summary
+
+**TDA-compliant balance engine with live-adaptive suggestions, fully automatic break table, and complete REST API for table/seating management**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-03-01T03:19:29Z
+- **Completed:** 2026-03-01T03:25:01Z
+- **Tasks:** 2
+- **Files modified:** 6
+
+## Accomplishments
+- Balance engine detects unbalanced tables (diff > 1) and generates TDA-compliant move suggestions with button-aware fairness
+- Suggestions are live and adaptive: re-validated on accept, auto-invalidated when state changes (bust, move, etc.)
+- Break table fully automatically distributes players evenly and deactivates the dissolved table
+- Complete REST API covering tables, seating, balancing, blueprints, dealer button, and hand-for-hand
+- 15 tests covering balance detection, suggestion lifecycle, stale detection, auto-seat, break table distribution, and dealer button advancement
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task H1: Table management, auto-seating, blueprints, hand-for-hand** - `e947ab1` (feat)
+2. **Task H2: Balance engine, break table, API routes, tests** - `2d3cb0a` (feat)
+
+## Files Created/Modified
+- `internal/seating/balance.go` - BalanceEngine with CheckBalance, SuggestMoves, AcceptSuggestion, CancelSuggestion, InvalidateStaleSuggestions
+- `internal/seating/breaktable.go` - BreakTableService with BreakTable (fully automatic redistribution)
+- `internal/seating/table.go` - Added DB() accessor method for cross-service use
+- `internal/seating/balance_test.go` - 10 tests: balance detection, suggestions, stale detection, auto-seat, dealer button
+- `internal/seating/breaktable_test.go` - 5 tests: even distribution, odd count, deactivation, error cases
+- `internal/server/routes/tables.go` - Full REST API handler with 22 endpoints
+
+## Decisions Made
+- Balance suggestions use clockwise distance from dealer button for fairness: player closest after button (small blind position) is moved first, as they are least disadvantaged by a move
+- Stale suggestion re-validation requires source table to have at least 2 more players than destination (the threshold that makes a move necessary)
+- Break table is fully automatic per CONTEXT.md -- moves are applied immediately and result is informational for TD display
+- Blueprint CRUD routes are venue-level (not tournament-scoped) with admin role for mutations, read for any authenticated user
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Table and seating engine is feature-complete for Phase 1
+- Frontend can integrate table views, balance alerts, and break table UI
+- Balance suggestions ready for real-time WebSocket push to connected clients
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-09-SUMMARY.md

@@ -0,0 +1,166 @@
+---
+phase: 01-tournament-engine
+plan: 09
+subsystem: api, tournament, financial
+tags: [tournament-lifecycle, multi-tournament, icm, chop, deal, malmuth-harville, monte-carlo, lobby]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine/04
+    provides: Clock engine with registry, ticker, state machine
+  - phase: 01-tournament-engine/06
+    provides: Financial engine with transactions, prize pool, payouts
+  - phase: 01-tournament-engine/07
+    provides: Player management, rankings, buy-in flow
+  - phase: 01-tournament-engine/08
+    provides: Seating engine with tables, balancing, break table
+provides:
+  - Tournament lifecycle service (create, start, pause, resume, end, cancel, auto-close)
+  - Multi-tournament manager with lobby view (MULTI-01, MULTI-02)
+  - ICM calculator (exact Malmuth-Harville for <=10, Monte Carlo for 11+)
+  - Chop/deal engine (ICM, chip chop, even chop, custom, partial chop)
+  - Tournament state aggregation for WebSocket connect
+  - Activity feed from audit trail
+  - Tournament API routes with deal proposal workflow
+  - Deal proposals migration (007_deal_proposals.sql)
+affects: [01-11, 01-12, 01-14, phase-02]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [tournament-scoped-state, template-first-creation, local-copy-semantics, proposal-confirm-workflow, icm-dispatcher-pattern]
+
+key-files:
+  created:
+    - internal/tournament/tournament.go
+    - internal/tournament/state.go
+    - internal/tournament/multi.go
+    - internal/financial/icm.go
+    - internal/financial/chop.go
+    - internal/server/routes/tournaments.go
+    - internal/store/migrations/007_deal_proposals.sql
+    - internal/financial/icm_test.go
+    - internal/financial/chop_test.go
+    - internal/tournament/tournament_test.go
+    - internal/tournament/integration_test.go
+  modified: []
+
+key-decisions:
+  - "ICM dispatcher: exact Malmuth-Harville for <=10 players, Monte Carlo (100K iterations) for 11+"
+  - "Deal proposal/confirm workflow: ProposeDeal returns preview, ConfirmDeal applies payouts"
+  - "Full chop sets all players to 'deal' status and completes tournament; partial chop continues play"
+  - "Integration tests use file-based DB with WAL mode for clock ticker goroutine compatibility"
+  - "Tournament auto-close: 1 remaining = end, 0 remaining = cancel"
+
+patterns-established:
+  - "Tournament-scoped state: all state (clock, players, tables, financials) keyed by tournament_id"
+  - "Template-first creation: CreateFromTemplate loads expanded template, applies overrides, copies all refs"
+  - "Proposal-confirm pattern: deal proposals are stored, reviewed, then confirmed or cancelled"
+  - "ICM dispatcher pattern: CalculateICM auto-selects exact vs Monte Carlo based on player count"
+  - "Activity feed: audit entries converted to human-readable ActivityEntry structs"
+
+requirements-completed: [MULTI-01, MULTI-02, FIN-11, SEAT-06]
+
+# Metrics
+duration: 25min
+completed: 2026-03-01
+---
+
+# Plan 09: Tournament Lifecycle + Multi-Tournament + Chop/Deal Summary
+
+**Full tournament lifecycle (create/start/pause/resume/end/cancel/auto-close) with multi-tournament lobby, ICM calculator (exact + Monte Carlo), and chop/deal engine supporting 5 deal types**
+
+## Performance
+
+- **Duration:** ~25 min
+- **Started:** 2026-03-01T07:45:00Z
+- **Completed:** 2026-03-01T08:10:00Z
+- **Tasks:** 2
+- **Files created:** 11
+
+## Accomplishments
+- Tournament lifecycle service with all state transitions, template-first creation with local copy semantics, and auto-close on last player standing
+- Multi-tournament manager enabling lobby view with independent state per tournament (clocks, financials, players, tables)
+- ICM calculator with exact Malmuth-Harville algorithm (<=10 players, <2ms) and Monte Carlo simulation (11+ players, 100K iterations, <25ms)
+- Chop/deal engine with 5 deal types (ICM, chip chop, even chop, custom, partial chop) and proposal/confirm workflow
+- 31 new tests across 4 test files: 12 ICM, 6 chop, 9 tournament unit, 4 integration
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task I1: Tournament lifecycle and multi-tournament management** - `75ccb6f` (feat)
+2. **Task I2: ICM calculator, chop/deal engine, and comprehensive tests** - `2958449` (test)
+
+## Files Created/Modified
+- `internal/tournament/tournament.go` - Tournament service: create from template, start, pause, resume, end, cancel, auto-close, list
+- `internal/tournament/state.go` - State aggregation for WebSocket snapshots and activity feed
+- `internal/tournament/multi.go` - Multi-tournament manager with lobby view, active tournament listing
+- `internal/financial/icm.go` - ICM calculator: exact Malmuth-Harville + Monte Carlo dispatcher
+- `internal/financial/chop.go` - Chop engine: 5 deal types, proposal/confirm workflow, position assignment
+- `internal/server/routes/tournaments.go` - Tournament API routes: CRUD, lifecycle, deal proposals
+- `internal/store/migrations/007_deal_proposals.sql` - Deal proposals table migration
+- `internal/financial/icm_test.go` - 12 ICM tests (exact, Monte Carlo, validation, performance, convergence)
+- `internal/financial/chop_test.go` - 6 chop/deal tests (all deal types, positions, tournament end)
+- `internal/tournament/tournament_test.go` - 9 tournament unit tests (template, start, auto-close, multi, state)
+- `internal/tournament/integration_test.go` - 4 integration tests (lifecycle, deal, cancel, pause/resume)
+
+## Decisions Made
+- **ICM dispatcher pattern:** CalculateICM auto-selects exact for <=10 players (factorial complexity manageable) and Monte Carlo with 100K iterations for 11+ (converges to <2% deviation with equal stacks)
+- **Deal proposal/confirm workflow:** ProposeDeal calculates and stores proposal without applying; ConfirmDeal applies payouts as chop transactions -- matches the TD review flow from CONTEXT.md
+- **Full vs partial chop:** Full chop sets all players to 'deal' status and completes the tournament; partial chop applies partial payouts and lets tournament continue with remaining pool
+- **Integration test DB strategy:** In-memory DBs with libsql don't support cross-goroutine access; integration tests use file-based DB with WAL mode and busy_timeout for clock ticker compatibility
+- **Auto-close semantics:** CheckAutoClose called after every bust-out; 1 player remaining triggers EndTournament, 0 players triggers CancelTournament
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed in-memory DB cross-goroutine access in integration tests**
+- **Found during:** Task I2 (integration tests)
+- **Issue:** `setupTestDB` creates per-test in-memory DBs that aren't accessible from the clock ticker's background goroutine, causing "no such table" errors
+- **Fix:** Created `setupIntegrationDB` using file-based temp DB with WAL mode and busy_timeout=5000; added StopTicker call after StartTournament
+- **Files modified:** internal/tournament/integration_test.go
+- **Verification:** All 4 integration tests pass
+- **Committed in:** 2958449
+
+**2. [Rule 1 - Bug] Fixed blind_levels notes NULL scan failure**
+- **Found during:** Task I2 (tournament tests)
+- **Issue:** blind_levels notes column could be NULL, causing scan into string to fail when loading template
+- **Fix:** Used sql.NullString for notes scanning in loadLevelsFromDB; added explicit empty string notes to seed data
+- **Files modified:** internal/tournament/tournament.go, internal/tournament/tournament_test.go
+- **Verification:** TestCreateFromTemplate passes
+- **Committed in:** 2958449
+
+**3. [Rule 1 - Bug] Fixed payout_brackets column name mismatch**
+- **Found during:** Task I2 (tournament tests)
+- **Issue:** Test DDL used `payout_structure_id` but service queries use `structure_id` column name
+- **Fix:** Renamed column to `structure_id` in test DDL to match production schema
+- **Files modified:** internal/tournament/tournament_test.go
+- **Verification:** All tournament unit tests pass
+- **Committed in:** 2958449
+
+---
+
+**Total deviations:** 3 auto-fixed (3 Rule 1 bugs)
+**Impact on plan:** All auto-fixes necessary for test correctness. No scope creep.
+
+## Issues Encountered
+- libsql PRAGMA handling: `PRAGMA journal_mode=WAL` returns a row, so `Exec` fails with "Execute returned rows" -- must use `QueryRow` with `Scan` instead. This is consistent with the decision logged in 01-02 about libsql PRAGMA inconsistency.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Tournament lifecycle is complete and ready for wiring into the full server
+- Multi-tournament support enables lobby view for the frontend (Plan 11/14)
+- ICM and chop engines ready for frontend deal UI integration
+- API routes registered but need wiring into server.go router (will happen in final assembly plan)
+
+## Self-Check: PASSED
+
+All 11 created files verified present. Both task commits (75ccb6f, 2958449) verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-10-SUMMARY.md

@@ -0,0 +1,165 @@
+---
+phase: 01-tournament-engine
+plan: 10
+subsystem: ui
+tags: [sveltekit, svelte5, catppuccin, websocket, spa, typescript]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: Go binary scaffold with embed.go, WebSocket hub, JWT auth middleware
+provides:
+  - SvelteKit SPA scaffold with adapter-static and SPA fallback
+  - Catppuccin Mocha/Latte CSS theme with semantic color tokens
+  - WebSocket client with auto-reconnect and exponential backoff
+  - HTTP API client with JWT auth and 401 redirect
+  - Auth state store (Svelte 5 runes) with localStorage persistence
+  - Tournament state store (Svelte 5 runes) with WS message routing
+  - PIN login page with numpad and 48px touch targets
+  - Makefile frontend target for real SvelteKit build
+affects: [01-11, 01-13, 01-14]
+
+# Tech tracking
+tech-stack:
+  added: [sveltekit, svelte5, adapter-static, vite, typescript, catppuccin]
+  patterns: [svelte5-runes-state, spa-mode-no-ssr, css-custom-properties-theming, ws-reconnect-backoff, api-client-with-auth]
+
+key-files:
+  created:
+    - frontend/package.json
+    - frontend/svelte.config.js
+    - frontend/vite.config.ts
+    - frontend/tsconfig.json
+    - frontend/src/app.html
+    - frontend/src/app.css
+    - frontend/src/lib/theme/catppuccin.css
+    - frontend/src/lib/ws.ts
+    - frontend/src/lib/api.ts
+    - frontend/src/lib/stores/auth.svelte.ts
+    - frontend/src/lib/stores/tournament.svelte.ts
+    - frontend/src/routes/+layout.ts
+    - frontend/src/routes/+layout.svelte
+    - frontend/src/routes/+page.svelte
+    - frontend/src/routes/login/+page.svelte
+  modified:
+    - Makefile
+
+key-decisions:
+  - "Added type:module to package.json for ESM compatibility with SvelteKit/Vite"
+  - "Build output (frontend/build/) tracked in git for go:embed — not gitignored"
+  - "Catppuccin colors defined as CSS custom properties with semantic mappings rather than using @catppuccin/palette JS package"
+
+patterns-established:
+  - "Svelte 5 runes: class-based state with $state/$derived, exported as singletons"
+  - "CSS custom properties: --ctp-* for raw colors, --color-* for semantic usage"
+  - "WebSocket: singleton client with event handlers and auto-reconnect"
+  - "API client: auto-detect base URL, auto-attach JWT, 401 clears auth"
+  - "48px minimum touch targets via CSS (.touch-target, button, role=button)"
+
+requirements-completed: [UI-05, UI-06]
+
+# Metrics
+duration: 5min
+completed: 2026-03-01
+---
+
+# Plan 10: SvelteKit Frontend Scaffold + Theme + Clients Summary
+
+**SvelteKit SPA with Catppuccin Mocha dark theme, WebSocket/HTTP clients, Svelte 5 runes state stores, and PIN login page**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-01T02:49:15Z
+- **Completed:** 2026-03-01T02:54:37Z
+- **Tasks:** 1 (single compound task with 8 sub-items)
+- **Files modified:** 43
+
+## Accomplishments
+- SvelteKit project initialized with adapter-static SPA mode, builds to frontend/build/
+- Catppuccin Mocha (dark) and Latte (light) themes with 26 base colors + semantic tokens + poker-specific colors
+- WebSocket client with exponential backoff reconnect (1s-30s), connection state tracking, message routing
+- HTTP API client with auto JWT auth, 401 redirect to login, typed error handling
+- Auth state (Svelte 5 runes) with localStorage persistence, role-based access checks
+- Tournament state (Svelte 5 runes) handles clock, players, tables, financials, activity, rankings, balance
+- PIN login page with large numpad buttons, masked dot display, keyboard support, error states
+- Makefile updated: `make frontend` runs real SvelteKit build, `make all` builds frontend then Go binary
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task J1: Initialize SvelteKit project with theme, WS client, API client, stores, login page, Makefile** - `47e1f19` (feat)
+
+## Files Created/Modified
+- `frontend/package.json` - SvelteKit project config with ESM type
+- `frontend/svelte.config.js` - adapter-static with SPA fallback
+- `frontend/vite.config.ts` - Vite config with SvelteKit plugin
+- `frontend/tsconfig.json` - TypeScript config extending SvelteKit
+- `frontend/src/app.html` - HTML shell with data-theme="mocha"
+- `frontend/src/app.css` - Reset, touch targets, scrollbars, utilities
+- `frontend/src/lib/theme/catppuccin.css` - Mocha/Latte themes with semantic tokens
+- `frontend/src/lib/ws.ts` - WebSocket client with reconnect and backoff
+- `frontend/src/lib/api.ts` - HTTP API client with JWT auth
+- `frontend/src/lib/stores/auth.svelte.ts` - Auth state with localStorage
+- `frontend/src/lib/stores/tournament.svelte.ts` - Tournament state with WS message handling
+- `frontend/src/routes/+layout.ts` - SPA mode (prerender=true, ssr=false)
+- `frontend/src/routes/+layout.svelte` - Root layout importing app.css
+- `frontend/src/routes/+page.svelte` - Home page with auth redirect
+- `frontend/src/routes/login/+page.svelte` - PIN login page with numpad
+- `Makefile` - Updated frontend target for real SvelteKit build
+
+## Decisions Made
+- Used CSS custom properties for Catppuccin instead of @catppuccin/palette JS package — simpler, no runtime dependency, works with data-theme attribute switching
+- Added `"type": "module"` to package.json — required for ESM-only SvelteKit/Vite packages
+- frontend/build/ tracked in git (not gitignored) — required by Go's embed.go for go:embed directive
+- Defined all Catppuccin colors directly in CSS rather than importing from npm — avoids build complexity and runtime overhead
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Added "type": "module" to package.json**
+- **Found during:** Task J1 (SvelteKit build)
+- **Issue:** Vite build failed with "This package is ESM only but it was tried to load by require"
+- **Fix:** Added `"type": "module"` to frontend/package.json
+- **Files modified:** frontend/package.json
+- **Verification:** `npm run build` succeeds
+- **Committed in:** 47e1f19
+
+**2. [Rule 3 - Blocking] Ran svelte-kit sync before build**
+- **Found during:** Task J1 (SvelteKit build)
+- **Issue:** tsconfig.json extends .svelte-kit/tsconfig.json which doesn't exist until sync runs
+- **Fix:** `npx svelte-kit sync` generates the .svelte-kit/ directory
+- **Files modified:** None (generated files in .svelte-kit/ are gitignored)
+- **Verification:** Build succeeds without tsconfig warning
+- **Committed in:** 47e1f19
+
+---
+
+**Total deviations:** 2 auto-fixed (2 blocking)
+**Impact on plan:** Both fixes necessary for build to succeed. No scope creep.
+
+## Issues Encountered
+- `make all` fails at Go build step due to pre-existing undefined types in `internal/server/routes/templates.go` — this is from incomplete Plan I (Template CRUD), not related to this plan's changes. `make frontend` works correctly.
+- Go binary not available in sandbox PATH — located at /usr/local/go/bin/go. Does not affect frontend build.
+- Skipped `@catppuccin/palette` npm dependency — defined colors directly in CSS for zero runtime overhead.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Frontend scaffold ready for Plan M (Layout Shell) and Plan N (Feature Views)
+- WebSocket client ready to connect once backend WS hub is active
+- API client ready for all CRUD operations once endpoints are implemented
+- Auth state ready for PIN login once auth endpoint exists
+- All Svelte 5 runes patterns established for future components
+
+## Self-Check: PASSED
+
+All 17 key files verified present. Commit 47e1f19 verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-11-SUMMARY.md

@@ -0,0 +1,141 @@
+---
+phase: 01-tournament-engine
+plan: 11
+subsystem: ui
+tags: [sveltekit, svelte5, catppuccin, clock-display, financials, activity-feed, bubble-prize, chop-deal, websocket]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: Clock engine API (Plan D), Financial engine API (Plan F), Tournament lifecycle API (Plan I), UI shell with layout/header/FAB/toast/DataTable/WS client (Plan J/10/13)
+provides:
+  - Overview tab with large clock display, break/pause overlays, player count, table balance status, financial summary, activity feed
+  - Financials tab with prize pool breakdown, payout preview, bubble prize flow, chop/deal wizard, transaction list
+  - ClockDisplay component with urgent pulse, hand-for-hand badge, next level preview, chip-up indicator
+  - ActivityFeed component with type-specific icons/colors and relative timestamps
+  - PrizePoolCard component with collapsible breakdown table
+  - BubblePrize component with prominent button and preview redistribution flow
+  - DealFlow component supporting ICM, chip chop, even chop, custom, and partial chop
+  - TransactionList component with type filter chips, search, and swipe-to-undo
+  - Extended tournament store types (ClockSnapshot, FinancialSummary, Transaction, Deal types)
+  - Derived state: bustedPlayers, averageStack, totalChips
+affects: [01-14]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [clock-display-responsive-sizing, activity-feed-slide-animation, multi-step-wizard-flow, filter-chips-pattern, collapsible-card-pattern]
+
+key-files:
+  created:
+    - frontend/src/lib/components/ClockDisplay.svelte
+    - frontend/src/lib/components/BlindInfo.svelte
+    - frontend/src/lib/components/ActivityFeed.svelte
+    - frontend/src/lib/components/PrizePoolCard.svelte
+    - frontend/src/lib/components/TransactionList.svelte
+    - frontend/src/lib/components/BubblePrize.svelte
+    - frontend/src/lib/components/DealFlow.svelte
+  modified:
+    - frontend/src/routes/overview/+page.svelte
+    - frontend/src/routes/financials/+page.svelte
+    - frontend/src/lib/stores/tournament.svelte.ts
+
+key-decisions:
+  - "ClockDisplay uses clamp(3rem, 12vw, 6rem) for responsive timer sizing across mobile/desktop"
+  - "Unicode escapes in Svelte templates must use HTML entities (&#x...;) not JS escapes (\\u{...}) to avoid Svelte parser treating braces as expression blocks"
+  - "BubblePrize is a standalone prominent button (not buried in menus) per CONTEXT.md requirement"
+  - "DealFlow uses multi-step wizard pattern (type > input > review > confirm) for all 5 deal types"
+  - "Transaction undo uses window.confirm for confirmation (not custom modal) matching touch-first simplicity"
+
+patterns-established:
+  - "Multi-step wizard: state machine with step variable, each step renders different UI"
+  - "Filter chips: scrollable horizontal row of toggleable buttons for data filtering"
+  - "Collapsible card: button header with expand/collapse toggle and animated content"
+  - "Activity feed: type-icon mapping function returns { icon, color } per entry type"
+
+requirements-completed: [CHIP-03, CHIP-04, MULTI-02]
+
+# Metrics
+duration: 8min
+completed: 2026-03-01
+---
+
+# Phase 01 Plan 11: Overview + Clock + Financials Views Summary
+
+**Overview tab with responsive clock display, real-time activity feed, and Financials tab with prize pool breakdown, bubble prize flow, ICM/custom chop-deal wizard, and filterable transaction list**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-03-01T07:15:06Z
+- **Completed:** 2026-03-01T07:23:35Z
+- **Tasks:** 2
+- **Files modified:** 10
+
+## Accomplishments
+- Overview tab assembles all priority items from CONTEXT.md: large clock (40% viewport), break countdown, player count with avg stack, table balance status, financial summary card, activity feed
+- Financials tab with collapsible prize pool breakdown, payout preview table, prominent bubble prize button, 5-type chop/deal wizard, and filterable transaction list with swipe-to-undo
+- Extended tournament store with detailed clock fields (bb_ante, game_type, hand_for_hand, next level info), financial breakdown fields, Transaction type, and Deal types
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task K1: Overview tab with clock display and activity feed** - `e7da206` (feat)
+2. **Task K2: Financials tab with prize pool, bubble prize, and chop/deal** - `5e18bbe` (feat)
+
+## Files Created/Modified
+- `frontend/src/lib/components/ClockDisplay.svelte` - Large countdown timer with break/pause overlays, urgent pulse, next level preview
+- `frontend/src/lib/components/BlindInfo.svelte` - Time-to-break countdown display
+- `frontend/src/lib/components/ActivityFeed.svelte` - Recent actions with type icons, relative timestamps, slide-in animation
+- `frontend/src/lib/components/PrizePoolCard.svelte` - Collapsible prize pool breakdown with rake and guarantee
+- `frontend/src/lib/components/TransactionList.svelte` - DataTable-based transaction list with type filter and swipe undo
+- `frontend/src/lib/components/BubblePrize.svelte` - Prominent bubble prize button with preview redistribution flow
+- `frontend/src/lib/components/DealFlow.svelte` - Multi-step chop/deal wizard (ICM, chip chop, even, custom, partial)
+- `frontend/src/routes/overview/+page.svelte` - Full overview page with all priority components
+- `frontend/src/routes/financials/+page.svelte` - Full financials page with all sub-components
+- `frontend/src/lib/stores/tournament.svelte.ts` - Extended types and derived state properties
+
+## Decisions Made
+- ClockDisplay uses `clamp(3rem, 12vw, 6rem)` for responsive timer sizing that adapts to screen width
+- Unicode escapes in Svelte HTML templates require HTML entities (`&#x...;`) instead of JS escapes (`\u{...}`) because Svelte parser treats `{` as expression start
+- BubblePrize placed as prominent standalone button per CONTEXT.md ("not buried in menus")
+- DealFlow implements state-machine wizard pattern for clean multi-step flows
+- Transaction undo uses `window.confirm()` for simplicity in a touch-first TD interface
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Fixed Svelte template unicode escape parsing**
+- **Found during:** Task K2 (BubblePrize and DealFlow components)
+- **Issue:** `\u{1F3C6}` in Svelte template HTML was parsed as `\u` + Svelte expression `{1F3C6}`, causing "Identifier directly after number" errors
+- **Fix:** Replaced all `\u{...}` in HTML template sections with HTML entities `&#x...;`
+- **Files modified:** BubblePrize.svelte, DealFlow.svelte
+- **Verification:** svelte-check passes with 0 errors
+- **Committed in:** 5e18bbe (Task K2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Trivial syntax fix required for Svelte template compatibility. No scope creep.
+
+## Issues Encountered
+None beyond the unicode escape fix above.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Overview and Financials tabs are fully built and reactive from WebSocket state
+- All components ready for real-time data from the Go backend
+- Plan 14 (integration/action flows) can wire up the FAB actions to these views
+- Pre-existing type errors in BuyInFlow.svelte and players page are from other plans and unrelated
+
+## Self-Check: PASSED
+
+All 10 files verified present. Both commit hashes (e7da206, 5e18bbe) verified in git log. svelte-check: 0 errors.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-12-SUMMARY.md

@@ -0,0 +1,149 @@
+---
+phase: 01-tournament-engine
+plan: 12
+subsystem: ui
+tags: [svelte, sveltekit, player-management, buy-in, bust-out, rebuy, addon, touch-ui]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: Player management API (Plan G), seating engine API (Plan H), UI shell (Plan J/K)
+provides:
+  - PlayerSearch typeahead component
+  - BuyInFlow step-by-step wizard
+  - BustOutFlow minimal-tap flow
+  - PlayerDetail per-player tracking panel
+  - RebuyFlow quick 2-tap flow
+  - AddOnFlow with mass add-on option
+  - Players page with Active/Busted/All tabs
+  - FAB actions wired to actual tournament flows
+affects: [frontend, tournament-operations, player-experience]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [flow-overlay-pattern, step-wizard-pattern, tap-tap-interaction]
+
+key-files:
+  created:
+    - frontend/src/lib/components/PlayerSearch.svelte
+    - frontend/src/lib/components/BuyInFlow.svelte
+    - frontend/src/lib/components/BustOutFlow.svelte
+    - frontend/src/lib/components/PlayerDetail.svelte
+    - frontend/src/lib/components/RebuyFlow.svelte
+    - frontend/src/lib/components/AddOnFlow.svelte
+  modified:
+    - frontend/src/routes/players/+page.svelte
+    - frontend/src/routes/+layout.svelte
+
+key-decisions:
+  - "Flow overlays use fixed full-screen positioning (z-index 100) for modal-like behavior"
+  - "BuyInFlow uses 3-step wizard with mini table diagram for seat visualization"
+  - "BustOutFlow uses grid table picker then seat tap for minimal taps under time pressure"
+  - "RebuyFlow and AddOnFlow support preselectedPlayer prop for direct launch from PlayerDetail"
+  - "FAB actions in layout now trigger actual flow overlays instead of placeholder toasts"
+  - "DataTable receives Player[] cast as Record<string,unknown>[] for type compatibility"
+
+patterns-established:
+  - "Flow overlay pattern: full-screen fixed overlay with header (back/close) + step content"
+  - "Step wizard pattern: step indicator + content per step, goBack() method for navigation"
+  - "Preselected entity pattern: optional prop to skip search step in quick flows"
+
+requirements-completed: [PLYR-04, PLYR-05, PLYR-07]
+
+# Metrics
+duration: 8min
+completed: 2026-03-01
+---
+
+# Plan 12: Frontend Players Tab + Buy-In/Bust-Out Flows Summary
+
+**Touch-optimized Players tab with step-by-step buy-in wizard, minimal-tap bust-out flow, full player detail tracking, and quick rebuy/add-on flows via FAB and player detail**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-03-01T07:15:08Z
+- **Completed:** 2026-03-01T07:23:17Z
+- **Tasks:** 1 (with 6 sub-components)
+- **Files modified:** 8
+
+## Accomplishments
+- PlayerSearch with debounced typeahead, 48px touch rows, "Add New Player" option, recently active when empty
+- BuyInFlow 3-step wizard: search player, auto-seat with mini table diagram + override, confirm with green button
+- BustOutFlow minimal-tap flow: table grid, oval seat picker, verify with avatar, hitman selection (same table + search all)
+- PlayerDetail with status/location/chips, financial stats, action history, undo buttons for bust/buyin/rebuy
+- RebuyFlow and AddOnFlow with 2-tap quick flow, preselected player support, mass add-on all option
+- Players page with Active/Busted/All segmented tabs, DataTable with search and swipe actions
+- Layout FAB now launches actual flow overlays with clock pause/resume via API
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task L1: Players tab with buy-in and bust-out flows** - `44b555d` (feat)
+
+**Plan metadata:** [pending] (docs: complete plan)
+
+## Files Created/Modified
+- `frontend/src/lib/components/PlayerSearch.svelte` - Typeahead player search with debounce, touch targets, recent players
+- `frontend/src/lib/components/BuyInFlow.svelte` - 3-step buy-in wizard with auto-seat and mini table diagram
+- `frontend/src/lib/components/BustOutFlow.svelte` - Minimal-tap bust-out flow with table grid and seat picker
+- `frontend/src/lib/components/PlayerDetail.svelte` - Full per-player tracking panel with undo actions
+- `frontend/src/lib/components/RebuyFlow.svelte` - Quick rebuy flow with preselected player support
+- `frontend/src/lib/components/AddOnFlow.svelte` - Quick add-on flow with mass add-on all option
+- `frontend/src/routes/players/+page.svelte` - Players page with Active/Busted/All tabs and overlay flows
+- `frontend/src/routes/+layout.svelte` - FAB actions wired to actual flows, clock pause/resume
+
+## Decisions Made
+- Flow overlays use fixed full-screen positioning (z-index 100) for modal-like behavior rather than routes
+- BuyInFlow uses 3-step wizard with mini table diagram for seat visualization (auto-seat preview)
+- BustOutFlow uses grid table picker then seat tap for minimal taps under time pressure
+- RebuyFlow and AddOnFlow support preselectedPlayer prop for direct launch from PlayerDetail
+- FAB actions in layout now trigger actual flow overlays instead of placeholder toasts
+- DataTable receives Player[] cast as Record<string,unknown>[] for type compatibility
+- Svelte 5 $effect used for preselectedPlayer initialization to avoid state_referenced_locally warnings
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed Svelte 5 {@const} placement in BuyInFlow**
+- **Found during:** Task L1 (BuyInFlow component)
+- **Issue:** {@const} tag placed inside HTML div element instead of Svelte block
+- **Fix:** Wrapped in additional {#if} block so {@const} is direct child of Svelte control flow
+- **Files modified:** frontend/src/lib/components/BuyInFlow.svelte
+- **Verification:** svelte-check passes with zero errors in our files
+- **Committed in:** 44b555d (Task L1 commit)
+
+**2. [Rule 1 - Bug] Fixed state_referenced_locally warnings in RebuyFlow/AddOnFlow**
+- **Found during:** Task L1 (RebuyFlow, AddOnFlow components)
+- **Issue:** Initializing $state from prop value captures initial value only
+- **Fix:** Used $effect to set state from prop, initializing state to defaults
+- **Files modified:** frontend/src/lib/components/RebuyFlow.svelte, frontend/src/lib/components/AddOnFlow.svelte
+- **Verification:** svelte-check shows no warnings for these files
+- **Committed in:** 44b555d (Task L1 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs)
+**Impact on plan:** Both auto-fixes necessary for correct Svelte 5 compilation. No scope creep.
+
+## Issues Encountered
+None beyond the auto-fixed items above.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Players tab with all flows is complete and ready for integration testing
+- FAB actions are now wired to real flows throughout the app
+- Pre-existing errors in BubblePrize.svelte and DealFlow.svelte are not affected by this plan
+
+## Self-Check: PASSED
+
+All 9 files verified present. Commit 44b555d verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-13-SUMMARY.md

@@ -0,0 +1,168 @@
+---
+phase: 01-tournament-engine
+plan: 13
+subsystem: ui
+tags: [sveltekit, svelte5, catppuccin, responsive, mobile-first, touch-targets, toast, datatable, fab]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: SvelteKit SPA scaffold, Catppuccin theme, WS/API clients, auth/tournament state stores
+provides:
+  - Persistent header with live clock, level, blinds, player count
+  - Mobile bottom tab bar with 5 navigation tabs (48px touch targets)
+  - Desktop sidebar navigation (>=768px breakpoint)
+  - Floating action button (FAB) with context-aware quick actions
+  - Toast notification system (success/info/warning/error with auto-dismiss)
+  - Reusable DataTable component (sort, search, swipe actions, skeleton loading)
+  - Multi-tournament tab selector for 2+ active tournaments
+  - Loading components (spinner, skeleton, full-page)
+  - Root layout shell with auth guard and responsive structure
+affects: [01-14]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [responsive-layout-shell, mobile-bottom-tabs-desktop-sidebar, fab-pattern, toast-runes-store, datatable-generic, multi-tournament-routing]
+
+key-files:
+  created:
+    - frontend/src/lib/components/Header.svelte
+    - frontend/src/lib/components/BottomTabs.svelte
+    - frontend/src/lib/components/Sidebar.svelte
+    - frontend/src/lib/components/FAB.svelte
+    - frontend/src/lib/components/Toast.svelte
+    - frontend/src/lib/components/DataTable.svelte
+    - frontend/src/lib/components/TournamentTabs.svelte
+    - frontend/src/lib/components/Loading.svelte
+    - frontend/src/lib/stores/toast.svelte.ts
+    - frontend/src/lib/stores/multi-tournament.svelte.ts
+    - frontend/src/routes/overview/+page.svelte
+    - frontend/src/routes/players/+page.svelte
+    - frontend/src/routes/tables/+page.svelte
+    - frontend/src/routes/financials/+page.svelte
+    - frontend/src/routes/more/+page.svelte
+  modified:
+    - frontend/src/routes/+layout.svelte
+    - frontend/src/routes/+page.svelte
+
+key-decisions:
+  - "Svelte 5 div with role=tablist instead of nav element to avoid a11y conflict with interactive role on non-interactive element"
+  - "FAB actions dispatched via callback prop (onaction) to parent layout for centralized action handling"
+  - "Multi-tournament state as separate store (not merged into tournament store) for clean separation of concerns"
+  - "DataTable uses generic Record<string,unknown> with column render functions rather than generics for Svelte component compatibility"
+
+patterns-established:
+  - "Layout shell: fixed header + fixed bottom tabs (mobile) / sidebar (desktop) + scrollable content area"
+  - "Toast store: Svelte 5 runes class with auto-dismiss timers and type-based durations"
+  - "DataTable: column config driven with hideMobile flag for responsive column visibility"
+  - "FAB: backdrop overlay + ESC dismiss + context-aware action filtering"
+
+requirements-completed: [UI-01, UI-02, UI-03, UI-04, UI-07, UI-08]
+
+# Metrics
+duration: 5min
+completed: 2026-03-01
+---
+
+# Plan 13: Layout Shell -- Header, Tabs, FAB, Toast, Data Table Summary
+
+**Mobile-first layout shell with persistent clock header, bottom tabs/desktop sidebar, expandable FAB, toast notifications, and generic sortable DataTable**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-01T03:07:29Z
+- **Completed:** 2026-03-01T03:13:27Z
+- **Tasks:** 1 (compound task with 9 sub-items)
+- **Files modified:** 74
+
+## Accomplishments
+- Persistent header fixed at top showing clock countdown (MM:SS), level number, blinds (SB/BB), ante, player count with red pulse animation in final 10s and PAUSED/BREAK badges
+- Mobile bottom tab bar (5 tabs: Overview, Players, Tables, Financials, More) with 48px touch targets, hidden on desktop
+- Desktop sidebar (>=768px) with vertical navigation replacing bottom tabs, active item highlight with accent border
+- Floating Action Button expanding to Bust/Buy In/Rebuy/Add-On/Pause-Resume with backdrop dismiss and ESC key support
+- Toast notification system using Svelte 5 runes: success (3s), info (4s), warning (5s), error (8s) with auto-dismiss, color-coded using Catppuccin palette
+- Reusable DataTable component: sortable columns (asc/desc), sticky header, search/filter across all columns, mobile swipe actions, skeleton loading, empty state, responsive column hiding
+- Multi-tournament tab selector: horizontal scrollable tabs with status dot indicators, fast switching without re-fetch
+- Loading components: spinner (sm/md/lg), skeleton placeholder rows, full-page loading overlay
+- Root layout shell with auth guard (redirect to /login if unauthenticated), responsive structure
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task M1: Implement layout shell** - `7f91301` (feat)
+
+## Files Created/Modified
+- `frontend/src/lib/components/Header.svelte` - Persistent header with clock, level, blinds, player count
+- `frontend/src/lib/components/BottomTabs.svelte` - Mobile bottom tab bar (5 tabs)
+- `frontend/src/lib/components/Sidebar.svelte` - Desktop sidebar navigation
+- `frontend/src/lib/components/FAB.svelte` - Floating action button with expandable actions
+- `frontend/src/lib/components/Toast.svelte` - Toast notification renderer
+- `frontend/src/lib/components/DataTable.svelte` - Generic sortable/searchable data table
+- `frontend/src/lib/components/TournamentTabs.svelte` - Multi-tournament tab selector
+- `frontend/src/lib/components/Loading.svelte` - Spinner, skeleton, full-page loading
+- `frontend/src/lib/stores/toast.svelte.ts` - Toast state store (Svelte 5 runes)
+- `frontend/src/lib/stores/multi-tournament.svelte.ts` - Multi-tournament routing state
+- `frontend/src/routes/+layout.svelte` - Root layout with auth guard and full shell
+- `frontend/src/routes/+page.svelte` - Redirect to /overview
+- `frontend/src/routes/overview/+page.svelte` - Overview page with stats grid
+- `frontend/src/routes/players/+page.svelte` - Players page with DataTable
+- `frontend/src/routes/tables/+page.svelte` - Tables page with DataTable
+- `frontend/src/routes/financials/+page.svelte` - Financials page with finance cards
+- `frontend/src/routes/more/+page.svelte` - Settings/logout page
+
+## Decisions Made
+- Used `div` with `role="tablist"` instead of `nav` element for bottom tabs to avoid Svelte a11y warning about non-interactive elements with interactive roles
+- FAB actions dispatched via callback prop (`onaction`) to parent layout for centralized action routing (placeholder handlers until Plan N)
+- Multi-tournament state kept as a separate store from the singleton tournament state for clean separation of concerns
+- DataTable uses `Record<string, unknown>` with column render functions rather than TypeScript generics due to Svelte component prop constraints
+- Root page (`/`) redirects to `/overview` with `replaceState` to avoid back-button issues
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed Svelte 5 event modifier syntax in DataTable**
+- **Found during:** Task M1 (build verification)
+- **Issue:** Used Svelte 4 syntax `onclick|stopPropagation` which is invalid in Svelte 5
+- **Fix:** Changed to `onclick={(e) => { e.stopPropagation(); ... }}` inline handler
+- **Files modified:** frontend/src/lib/components/DataTable.svelte
+- **Verification:** Build succeeds
+- **Committed in:** 7f91301
+
+**2. [Rule 1 - Bug] Fixed a11y violation: nav with role=tablist**
+- **Found during:** Task M1 (build verification)
+- **Issue:** Svelte a11y check rejects interactive role on non-interactive `nav` element
+- **Fix:** Changed `nav` to `div` with `role="tablist"` for BottomTabs
+- **Files modified:** frontend/src/lib/components/BottomTabs.svelte
+- **Verification:** Build succeeds without a11y warnings
+- **Committed in:** 7f91301
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs)
+**Impact on plan:** Both fixes necessary for build to succeed. No scope creep.
+
+## Issues Encountered
+None beyond the auto-fixed build errors above.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Layout shell complete and ready for Plan N (Feature Views: Overview, Players, Tables, Financials)
+- All navigation routes exist with placeholder content
+- DataTable component ready for use in player lists, table views, payout tables
+- Toast system ready for action feedback (bust confirmation, rebuy success, etc.)
+- FAB wired with placeholder handlers ready for Plan N to implement actual flows
+
+## Self-Check: PASSED
+
+All 17 key files verified present. Commit 7f91301 verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

.planning/phases/01-tournament-engine/01-14-SUMMARY.md

@@ -0,0 +1,148 @@
+---
+phase: 01-tournament-engine
+plan: 14
+subsystem: ui
+tags: [svelte, svg, datatable, template-editor, blind-structure, wizard, settings, audit-log]
+
+# Dependency graph
+requires:
+  - phase: 01-tournament-engine
+    provides: [layout shell, data table, FAB, toast, tournament store, auth store]
+provides:
+  - SVG-based oval table view with seat positions and player names
+  - Table list view alternative for large tournaments
+  - Balancing panel with suggest/accept move flow
+  - Tap-tap seat move across tables
+  - Break table with confirmation dialog
+  - LEGO-style template manager with 5 building block types
+  - Blind structure editor with mixed game support and BB ante
+  - Structure wizard with parameter-driven generation
+  - Venue settings page (currency, receipts, theme toggle)
+  - Audit log with filters, detail panel, and undo
+affects: [02-display-engine, 03-sync, 08-deployment]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [SVG table rendering, tap-tap seat move flow, LEGO building block composition, parameter-driven generation wizard]
+
+key-files:
+  created:
+    - frontend/src/lib/components/TemplateManager.svelte
+    - frontend/src/lib/components/BlindStructureEditor.svelte
+    - frontend/src/lib/components/StructureWizard.svelte
+    - frontend/src/routes/more/templates/+page.svelte
+    - frontend/src/routes/more/structures/+page.svelte
+    - frontend/src/routes/more/settings/+page.svelte
+    - frontend/src/routes/more/audit/+page.svelte
+  modified:
+    - frontend/src/routes/more/+page.svelte
+    - frontend/src/routes/tables/+page.svelte
+    - frontend/src/lib/components/OvalTable.svelte
+    - frontend/src/lib/components/TableListView.svelte
+    - frontend/src/lib/components/BalancingPanel.svelte
+
+key-decisions:
+  - "DataTable typed interface data requires cast to Record<string, unknown>[] (pre-existing pattern from Plan M)"
+  - "Structure wizard uses geometric ratio for blind escalation with nice-number rounding"
+  - "Blind structure editor uses move up/down buttons instead of drag-and-drop (Phase 1 constraint)"
+  - "Theme toggle writes data-theme attribute directly on documentElement for immediate switch"
+
+patterns-established:
+  - "LEGO composition: dropdowns with preview summaries and Create New navigation"
+  - "Wizard pattern: sliders/presets for input, generate, preview, save/use"
+  - "Admin-gated sections: conditional rendering based on auth.isAdmin"
+  - "Audit detail: overlay panel with JSON detail and contextual undo"
+
+requirements-completed: [SEAT-05, SEAT-07, SEAT-08, BLIND-06]
+
+# Metrics
+duration: 11min
+completed: 2026-03-01
+---
+
+# Phase 1 Plan 14: Frontend Tables Tab + More Tab Summary
+
+**SVG oval table views with tap-tap seat moves, LEGO-style template manager, blind structure wizard, venue settings, and audit log**
+
+## Performance
+
+- **Duration:** 11 min
+- **Started:** 2026-03-01T07:15:15Z
+- **Completed:** 2026-03-01T07:26:25Z
+- **Tasks:** 2
+- **Files modified:** 8
+
+## Accomplishments
+- Tables tab with SVG oval views (6-10 max), list view toggle, tap-tap seat move, balancing panel, break table with confirmation
+- More tab with navigable menu to templates, structures, settings, and audit log
+- LEGO-style template editor composing tournament configs from 5 building block types
+- Blind structure editor with all fields (SB, BB, Ante, BB Ante, Duration, Chip-up, Game Type) and move up/down reorder
+- Structure wizard generating blind levels from player count, starting chips, and target duration
+- Venue settings with currency, rounding, receipt mode, Mocha/Latte theme toggle
+- Audit log with action/operator filters, detail panel with JSON state, and undo capability
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task N1: Tables tab with oval view and balancing panel** - `e7da206` (feat - already committed in prior plan 01-11)
+2. **Task N2: More tab with template management, wizard, settings, audit** - `59badcb` (feat)
+
+## Files Created/Modified
+- `frontend/src/lib/components/OvalTable.svelte` - SVG oval table with seat positions (prior commit)
+- `frontend/src/lib/components/TableListView.svelte` - DataTable alternative for large tournaments (prior commit)
+- `frontend/src/lib/components/BalancingPanel.svelte` - Balance suggestions with accept/cancel flow (prior commit)
+- `frontend/src/lib/components/TemplateManager.svelte` - LEGO-style building block composition editor
+- `frontend/src/lib/components/BlindStructureEditor.svelte` - Full blind level editor with mixed game support
+- `frontend/src/lib/components/StructureWizard.svelte` - Parameter-driven blind structure generator
+- `frontend/src/routes/tables/+page.svelte` - Tables grid with oval/list toggle, move banner, H4H (prior commit)
+- `frontend/src/routes/more/+page.svelte` - Navigation menu with operator card and admin-gated sections
+- `frontend/src/routes/more/templates/+page.svelte` - Template list with CRUD and DataTable
+- `frontend/src/routes/more/structures/+page.svelte` - Blind structure list with wizard integration
+- `frontend/src/routes/more/settings/+page.svelte` - Venue settings with theme toggle and operator management
+- `frontend/src/routes/more/audit/+page.svelte` - Filterable audit log with detail overlay and undo
+
+## Decisions Made
+- DataTable typed interface data requires cast to `Record<string, unknown>[]` (consistent with existing players page pattern)
+- Structure wizard uses geometric ratio for blind escalation: `finalBB/startBB^(1/n)` with nice-number rounding
+- Blind structure editor uses move up/down buttons for reorder (no drag-and-drop per Phase 1 constraint)
+- Theme toggle writes `data-theme` attribute directly on `documentElement` for immediate CSS variable switch
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] DataTable type compatibility**
+- **Found during:** Task N2 (template/structure/audit pages)
+- **Issue:** DataTable expects `Record<string, unknown>[]` but typed interfaces lack index signatures
+- **Fix:** Cast data arrays with `as unknown as Record<string, unknown>[]` (matches pre-existing pattern)
+- **Files modified:** templates/+page.svelte, structures/+page.svelte, audit/+page.svelte
+- **Verification:** svelte-check passes with 0 errors
+- **Committed in:** 59badcb (Task N2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 bug)
+**Impact on plan:** Type cast is the established DataTable pattern. No scope creep.
+
+## Issues Encountered
+- Task N1 files (OvalTable, TableListView, BalancingPanel, tables/+page) were already implemented and committed in prior plan 01-11 run. Content was verified to match Plan N1 spec. No changes needed.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- All 5 main tabs (Overview, Players, Tables, Financials, More) now have full implementations
+- Template management ready for API integration when backend serves building block data
+- Structure wizard ready for backend wizard API integration
+- Phase 1 frontend is complete pending remaining plans (11, 12)
+
+## Self-Check: PASSED
+
+All 12 key files verified present. Both commit hashes (e7da206, 59badcb) verified in git log.
+
+---
+*Phase: 01-tournament-engine*
+*Completed: 2026-03-01*

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

@@ -0,0 +1,147 @@
+# 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: bonus chips awarded to the first X players who buy in (configurable cutoff count)
+  - Punctuality bonus: bonus chips awarded to players who complete buy-in before the tournament starts (status transitions from 'registering' to 'running') — deterministic, automatic, no TD judgment call
+- **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
+
+### Hand-for-Hand Mode
+- Activated by TD when tournament reaches bubble (remaining players = paid positions + 1)
+- Clock pauses, each table plays one hand at a time
+- TD view: table grid showing completion status per table (completed / in progress)
+- TD taps "Hand Complete" per table as dealers report
+- When all tables complete: next hand starts automatically, or if someone busted the bubble is resolved
+- If bust during hand-for-hand: check if bubble burst, if yes exit hand-for-hand mode and resume clock
+- Hand-for-hand should be prominent (visible mode indicator on all clients) because players watch this closely
+
+### 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
+
+</deferred>
+
+---
+
+*Phase: 01-tournament-engine*
+*Context gathered: 2026-03-01*

.planning/phases/01-tournament-engine/01-PLAN-A.md

@@ -0,0 +1,148 @@
+# Plan A: Project Scaffold + Core Infrastructure
+
+---
+wave: 1
+depends_on: []
+files_modified:
+  - go.mod
+  - go.sum
+  - cmd/leaf/main.go
+  - internal/server/server.go
+  - internal/server/ws/hub.go
+  - internal/server/middleware/auth.go
+  - internal/server/middleware/role.go
+  - internal/nats/embedded.go
+  - internal/nats/publisher.go
+  - internal/store/db.go
+  - frontend/embed.go
+  - Makefile
+autonomous: true
+requirements: [ARCH-01, ARCH-04, ARCH-05, ARCH-06, ARCH-07]
+---
+
+## Goal
+
+A Go binary starts in the LXC container, embeds NATS JetStream (sync_interval: always) and LibSQL, serves HTTP via chi, hosts a WebSocket hub that broadcasts to connected clients within 100ms, and serves a SvelteKit SPA stub via go:embed. This is the skeleton that every subsequent plan builds on.
+
+## Context
+
+- **Greenfield project** — no existing code
+- **Dev environment:** x86_64 LXC container (Debian/Ubuntu), Go 1.23+
+- **go-libsql has no tagged releases** — pin to commit hash in go.mod with comment
+- **NATS JetStream sync_interval: always** is mandatory (Jepsen 2025 finding for single-node)
+- **coder/websocket** v1.8.14 for WebSocket hub (not gorilla/websocket)
+- See 01-RESEARCH.md Pattern 1 (Embedded NATS), Pattern 2 (WebSocket Hub), Pattern 3 (SvelteKit Embed)
+
+## User Decisions (from CONTEXT.md)
+
+- The operator is the **Tournament Director (TD)** — use this term consistently
+- Multi-tournament support means all state must be tournament-scoped from day one (MULTI-01)
+- WebSocket hub must support tournament-scoped broadcasting
+
+## Tasks
+
+<task id="A1" title="Initialize Go module and dependency tree">
+Create the Go module at the project root. Install all core dependencies pinned to specific versions:
+
+- `github.com/tursodatabase/go-libsql` — pin to commit hash (check latest stable commit, add comment in go.mod)
+- `github.com/nats-io/nats-server/v2` @ v2.12.4
+- `github.com/nats-io/nats.go` @ latest
+- `github.com/coder/websocket` @ v1.8.14
+- `github.com/go-chi/chi/v5` @ v5.2.5
+- `github.com/golang-jwt/jwt/v5` @ latest
+- `golang.org/x/crypto` @ latest
+- `github.com/google/uuid` @ latest
+- `github.com/skip2/go-qrcode` @ latest
+
+Create the directory structure per 01-RESEARCH.md Recommended Project Structure. Include empty `.go` files with package declarations where needed to make the module compile.
+
+Create a Makefile with targets:
+- `make build` — builds `cmd/leaf` binary
+- `make run` — builds and runs with default data dir
+- `make test` — runs all tests
+- `make frontend` — builds the SvelteKit frontend (placeholder — just creates build dir with stub index.html)
+- `make all` — frontend + build
+
+The binary must compile and run (serving HTTP on :8080) with `make run`.
+
+**Verification:** `go build ./cmd/leaf/...` succeeds. `go vet ./...` passes. Directory structure matches the recommended layout.
+</task>
+
+<task id="A2" title="Implement core infrastructure: NATS, LibSQL, WebSocket hub, HTTP server">
+Wire up all core infrastructure in `cmd/leaf/main.go` and the `internal/` packages:
+
+**1. Embedded NATS Server** (`internal/nats/embedded.go`):
+- Start NATS server in-process with `DontListen: true` (no TCP listener)
+- JetStream enabled with `JetStreamSyncInterval: 0` (sync_interval: always — MANDATORY per Jepsen finding)
+- Memory limit: 64MB, Disk limit: 1GB
+- Wait for ready with 5-second timeout
+- Clean shutdown on context cancellation
+- Create initial JetStream streams: `AUDIT` (subject: `tournament.*.audit`), `STATE` (subject: `tournament.*.state.*`)
+
+**2. NATS Publisher** (`internal/nats/publisher.go`):
+- Publish function that writes to JetStream with subject routing
+- Helper to publish tournament-scoped events: `Publish(ctx, tournamentID, subject, data)`
+
+**3. LibSQL Database** (`internal/store/db.go`):
+- Open LibSQL with `sql.Open("libsql", "file:"+dbPath)`
+- Enable WAL mode: `PRAGMA journal_mode=WAL`
+- Enable foreign keys: `PRAGMA foreign_keys=ON`
+- Configurable data directory (flag or env var)
+- Close on context cancellation
+
+**4. WebSocket Hub** (`internal/server/ws/hub.go`):
+- Connection registry with mutex protection
+- Client struct: conn, tournamentID (subscription scope), send channel (buffered 256)
+- `Register(client)` / `Unregister(client)`
+- `Broadcast(tournamentID, messageType, data)` — sends to all clients subscribed to that tournament (or all if tournamentID is empty)
+- On connect: accept WebSocket, register client, send initial state snapshot (stub for now — just a "connected" message)
+- Read pump and write pump goroutines per client
+- Drop messages for slow consumers (non-blocking channel send)
+- Graceful shutdown: close all connections
+
+**5. HTTP Server** (`internal/server/server.go`):
+- chi router with middleware: logger, recoverer, request ID, CORS (permissive for dev)
+- Route groups:
+  - `/api/v1/` — REST API endpoints (stub 200 responses for now)
+  - `/ws` — WebSocket upgrade endpoint → Hub.HandleConnect
+  - `/*` — SvelteKit SPA fallback handler
+- Configurable listen address (default `:8080`)
+- Graceful shutdown with context
+
+**6. SvelteKit Embed Stub** (`frontend/embed.go`):
+- `//go:embed all:build` directive
+- `Handler()` function that serves static files with SPA fallback
+- For now, create a `frontend/build/index.html` stub file with minimal HTML that says "Felt — Loading..."
+
+**7. Main** (`cmd/leaf/main.go`):
+- Parse flags: `--data-dir` (default `./data`), `--addr` (default `:8080`)
+- Startup order: LibSQL → NATS → Hub → HTTP Server
+- Signal handling (SIGINT, SIGTERM) with graceful shutdown in reverse order
+- Log startup and shutdown events
+
+**Verification:**
+- `make run` starts the binary, prints startup log showing LibSQL opened, NATS ready, HTTP listening on :8080
+- `curl http://localhost:8080/` returns the stub HTML
+- `curl http://localhost:8080/api/v1/health` returns 200 with JSON showing all subsystems operational (LibSQL: `SELECT 1` succeeds, NATS server ready, WebSocket hub accepting connections)
+- A WebSocket client connecting to `ws://localhost:8080/ws` receives a connected message
+- CTRL+C triggers graceful shutdown with log messages
+</task>
+
+## Verification Criteria
+
+1. `go build ./cmd/leaf/...` succeeds with zero warnings
+2. `go vet ./...` passes
+3. `make run` starts the binary and serves HTTP on :8080
+4. LibSQL database file created in data directory with WAL mode
+5. NATS JetStream streams (AUDIT, STATE) exist after startup
+6. WebSocket connection to `/ws` succeeds and receives initial message
+7. SPA fallback serves index.html for unknown routes
+8. Graceful shutdown on SIGINT/SIGTERM completes without errors
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Go binary compiles and runs as a single process with all infrastructure embedded
+- [ ] NATS JetStream uses sync_interval: always (data durability guarantee)
+- [ ] WebSocket hub supports tournament-scoped broadcasting
+- [ ] SvelteKit SPA served via go:embed with fallback routing
+- [ ] All state is tournament-scoped from day one (no global singletons)

.planning/phases/01-tournament-engine/01-PLAN-B.md

@@ -0,0 +1,285 @@
+# Plan B: Database Schema + Migrations
+
+---
+wave: 1
+depends_on: []
+files_modified:
+  - internal/store/migrations/001_initial_schema.sql
+  - internal/store/migrations/002_fts_indexes.sql
+  - internal/store/migrate.go
+  - internal/store/db.go
+autonomous: true
+requirements: [ARCH-03, ARCH-08, PLYR-01, PLYR-07, SEAT-01, SEAT-02]
+---
+
+## Goal
+
+The complete LibSQL database schema for Phase 1 is defined in migration files and auto-applied on startup. Every table, index, and FTS5 virtual table needed by the tournament engine exists. All financial columns use INTEGER (int64 cents, never float/real). The migration system is simple (sequential numbered SQL files, applied once, tracked in a migrations table).
+
+## Context
+
+- **LibSQL is SQLite-compatible** — standard SQL DDL, PRAGMA, triggers, FTS5 all work
+- **All financial values are int64 cents** (ARCH-03) — every money column is INTEGER, never REAL
+- **Append-only audit trail** (ARCH-08) — audit_entries table is INSERT only, never UPDATE/DELETE
+- **Player database persistent on Leaf** (PLYR-01) — players table with UUID PK
+- **FTS5 for typeahead search** (PLYR-02) — virtual table on player names
+- **Tables and seats** (SEAT-01, SEAT-02) — tables, seats, blueprints
+- Schema must support multi-tournament (all tournament-specific tables reference tournament_id)
+
+## User Decisions (from CONTEXT.md)
+
+- **Templates are compositions of reusable building blocks** — chip_sets, blind_structures, payout_structures, buyin_configs, points_formulas are all independent entities
+- **Entry count = unique entries only** — not rebuys or add-ons (affects how we count entries for payout bracket selection)
+- **Receipts configurable per venue** — venue_settings table needed
+- **Chip bonuses** — early signup bonus, punctuality bonus fields in tournament config
+- **Minimum player threshold** — field in tournament metadata
+
+## Tasks
+
+<task id="B1" title="Design and write the initial schema migration">
+Create `internal/store/migrations/001_initial_schema.sql` containing all Phase 1 tables. Use `IF NOT EXISTS` on all CREATE statements. Every table gets `created_at` and `updated_at` timestamps (INTEGER, Unix epoch seconds).
+
+**Venue & Settings:**
+```sql
+-- venue_settings: singleton row for venue-level config
+-- Fields: id, venue_name, currency_code, currency_symbol, rounding_denomination (INTEGER cents),
+--         receipt_mode (off/digital/print/both), timezone, created_at, updated_at
+```
+
+**Building Blocks (venue-level reusable):**
+```sql
+-- chip_sets: id, name, is_builtin, created_at, updated_at
+-- chip_denominations: id, chip_set_id FK, value (INTEGER cents), color_hex, label, sort_order
+
+-- blind_structures: id, name, is_builtin, game_type_default, notes, created_at, updated_at
+-- blind_levels: id, structure_id FK, position (sort order), level_type (round/break),
+--   game_type, small_blind (INTEGER), big_blind (INTEGER), ante (INTEGER), bb_ante (INTEGER),
+--   duration_seconds, chip_up_denomination_value (INTEGER, nullable), notes
+
+-- payout_structures: id, name, is_builtin, created_at, updated_at
+-- payout_brackets: id, structure_id FK, min_entries, max_entries
+-- payout_tiers: id, bracket_id FK, position, percentage_basis_points (INTEGER, e.g. 5000 = 50.00%)
+
+-- buyin_configs: id, name, buyin_amount (INTEGER cents), starting_chips (INTEGER),
+--   rake_total (INTEGER cents), bounty_amount (INTEGER cents), bounty_chip (INTEGER),
+--   rebuy_allowed BOOLEAN, rebuy_cost (INTEGER), rebuy_chips (INTEGER), rebuy_rake (INTEGER),
+--   rebuy_limit (INTEGER, 0=unlimited), rebuy_level_cutoff (INTEGER nullable),
+--   rebuy_time_cutoff_seconds (INTEGER nullable), rebuy_chip_threshold (INTEGER nullable),
+--   addon_allowed BOOLEAN, addon_cost (INTEGER), addon_chips (INTEGER), addon_rake (INTEGER),
+--   addon_level_start (INTEGER nullable), addon_level_end (INTEGER nullable),
+--   reentry_allowed BOOLEAN, reentry_limit (INTEGER),
+--   late_reg_level_cutoff (INTEGER nullable), late_reg_time_cutoff_seconds (INTEGER nullable),
+--   created_at, updated_at
+
+-- rake_splits: id, buyin_config_id FK, category (house/staff/league/season_reserve), amount (INTEGER cents)
+
+-- points_formulas: id, name, expression TEXT, variables TEXT (JSON), is_builtin, created_at, updated_at
+```
+
+**Tournament Templates:**
+```sql
+-- tournament_templates: id, name, description, chip_set_id FK, blind_structure_id FK,
+--   payout_structure_id FK, buyin_config_id FK, points_formula_id FK (nullable),
+--   min_players (INTEGER), max_players (INTEGER nullable),
+--   early_signup_bonus_chips (INTEGER, default 0), early_signup_cutoff TEXT (nullable, datetime or player count),
+--   punctuality_bonus_chips (INTEGER, default 0),
+--   is_pko BOOLEAN DEFAULT FALSE,
+--   is_builtin BOOLEAN DEFAULT FALSE,
+--   created_at, updated_at
+```
+
+**Tournaments (runtime):**
+```sql
+-- tournaments: id (UUID), name, template_id FK (nullable, reference only),
+--   status (created/registering/running/paused/final_table/completed/cancelled),
+--   -- Copied config (local changes don't affect template):
+--   chip_set_id FK, blind_structure_id FK, payout_structure_id FK, buyin_config_id FK,
+--   points_formula_id FK (nullable),
+--   min_players, max_players,
+--   early_signup_bonus_chips, early_signup_cutoff,
+--   punctuality_bonus_chips,
+--   is_pko BOOLEAN,
+--   -- Runtime state:
+--   current_level INTEGER DEFAULT 0,
+--   clock_state TEXT DEFAULT 'stopped', -- stopped/running/paused
+--   clock_remaining_ns INTEGER DEFAULT 0,
+--   total_elapsed_ns INTEGER DEFAULT 0,
+--   hand_for_hand BOOLEAN DEFAULT FALSE,
+--   started_at INTEGER (nullable), ended_at INTEGER (nullable),
+--   created_at, updated_at
+```
+
+**Players:**
+```sql
+-- players: id (UUID), name, nickname (nullable), email (nullable), phone (nullable),
+--   photo_url (nullable), notes TEXT (nullable), custom_fields TEXT (nullable, JSON),
+--   created_at, updated_at
+
+-- tournament_players: id, tournament_id FK, player_id FK, status (registered/active/busted/deal),
+--   seat_table_id FK (nullable), seat_position INTEGER (nullable),
+--   buy_in_at INTEGER (nullable), bust_out_at INTEGER (nullable),
+--   bust_out_order INTEGER (nullable), -- position when busted (derived from bust order, not stored permanently)
+--   finishing_position INTEGER (nullable), -- final position (set at tournament end or deal)
+--   current_chips INTEGER DEFAULT 0,
+--   rebuys INTEGER DEFAULT 0, addons INTEGER DEFAULT 0, reentries INTEGER DEFAULT 0,
+--   bounty_value (INTEGER cents, for PKO — starts at half of bounty_amount),
+--   bounties_collected INTEGER DEFAULT 0,
+--   prize_amount (INTEGER cents, default 0),
+--   points_awarded INTEGER DEFAULT 0,
+--   early_signup_bonus_applied BOOLEAN DEFAULT FALSE,
+--   punctuality_bonus_applied BOOLEAN DEFAULT FALSE,
+--   hitman_player_id (nullable, FK players — who busted them),
+--   created_at, updated_at
+--   UNIQUE(tournament_id, player_id) -- one entry per player per tournament.
+--   Re-entry reactivates same row: status → 'active', reentries += 1,
+--   bust_out_at/bust_out_order/finishing_position/hitman_player_id are CLEARED (previous values preserved in audit trail).
+--   Only the final bust matters for ranking purposes.
+```
+
+**Tables & Seating:**
+```sql
+-- tables: id, tournament_id FK, name TEXT, seat_count INTEGER (6-10),
+--   dealer_button_position INTEGER (nullable), is_active BOOLEAN DEFAULT TRUE,
+--   created_at, updated_at
+
+-- table_blueprints: id, name, table_configs TEXT (JSON array of {name, seat_count}),
+--   created_at, updated_at
+
+-- balance_suggestions: id, tournament_id FK, status (pending/accepted/cancelled/expired),
+--   from_table_id FK, to_table_id FK,
+--   player_id FK (nullable — set when suggestion specifies a player),
+--   from_seat INTEGER (nullable), to_seat INTEGER (nullable),
+--   reason TEXT, created_at, resolved_at INTEGER (nullable)
+```
+
+**Financial Transactions:**
+```sql
+-- transactions: id (UUID), tournament_id FK, player_id FK,
+--   type (buyin/rebuy/addon/reentry/bounty_collected/bounty_paid/payout/rake/chop/bubble_prize),
+--   amount (INTEGER cents), chips (INTEGER, chips given/removed),
+--   operator_id TEXT, -- who performed the action
+--   receipt_data TEXT (nullable, JSON),
+--   undone BOOLEAN DEFAULT FALSE, undone_by TEXT (nullable, FK audit_entries.id),
+--   metadata TEXT (nullable, JSON — for bounty chain info, chop details, etc),
+--   created_at
+
+-- bubble_prizes: id, tournament_id FK, amount (INTEGER cents),
+--   funded_from TEXT (JSON — array of {position, reduction_amount}),
+--   status (proposed/confirmed/cancelled), created_at
+```
+
+**Audit Trail:**
+```sql
+-- audit_entries: id (UUID), tournament_id TEXT (nullable — some are venue-level),
+--   timestamp INTEGER (UnixNano), operator_id TEXT,
+--   action TEXT (e.g. 'player.bust', 'financial.buyin', 'clock.pause', 'seat.move'),
+--   target_type TEXT, target_id TEXT,
+--   previous_state TEXT (JSON), new_state TEXT (JSON),
+--   metadata TEXT (nullable, JSON),
+--   undone_by TEXT (nullable, references audit_entries.id)
+--   -- NO UPDATE OR DELETE — append only
+```
+
+**Operators:**
+```sql
+-- operators: id (UUID), name TEXT, pin_hash TEXT (bcrypt), role TEXT (admin/floor/viewer),
+--   created_at, updated_at
+```
+
+Add indexes on all foreign keys and common query patterns:
+- `tournament_players(tournament_id, status)` for active player lookups
+- `tournament_players(tournament_id, bust_out_order)` for rankings
+- `transactions(tournament_id, type)` for financial summaries
+- `transactions(tournament_id, player_id)` for player transaction history
+- `audit_entries(tournament_id, timestamp)` for audit log browsing
+- `audit_entries(action)` for action filtering
+- `tables(tournament_id, is_active)` for active table lookups
+
+**Verification:** The SQL file is valid and can be executed against a fresh LibSQL database without errors.
+</task>
+
+<task id="B2" title="Implement migration runner and FTS5 indexes">
+**1. FTS5 Migration** (`internal/store/migrations/002_fts_indexes.sql`):
+Create FTS5 virtual table for player search:
+```sql
+CREATE VIRTUAL TABLE IF NOT EXISTS players_fts USING fts5(
+    name, nickname, email,
+    content='players',
+    content_rowid='rowid'
+);
+
+-- Triggers to keep FTS in sync
+CREATE TRIGGER IF NOT EXISTS players_ai AFTER INSERT ON players BEGIN
+    INSERT INTO players_fts(rowid, name, nickname, email)
+    VALUES (new.rowid, new.name, new.nickname, new.email);
+END;
+
+CREATE TRIGGER IF NOT EXISTS players_ad AFTER DELETE ON players BEGIN
+    INSERT INTO players_fts(players_fts, rowid, name, nickname, email)
+    VALUES ('delete', old.rowid, old.name, old.nickname, old.email);
+END;
+
+CREATE TRIGGER IF NOT EXISTS players_au AFTER UPDATE ON players BEGIN
+    INSERT INTO players_fts(players_fts, rowid, name, nickname, email)
+    VALUES ('delete', old.rowid, old.name, old.nickname, old.email);
+    INSERT INTO players_fts(rowid, name, nickname, email)
+    VALUES (new.rowid, new.name, new.nickname, new.email);
+END;
+```
+
+**2. Migration Runner** (`internal/store/migrate.go`):
+- Create a `_migrations` table to track applied migrations: `(id INTEGER PRIMARY KEY, name TEXT, applied_at INTEGER)`
+- On startup, read all `*.sql` files from the embedded migrations directory (use `//go:embed migrations/*.sql`)
+- Sort by filename (numeric prefix ensures order)
+- For each migration not yet applied: execute within a transaction, record in _migrations table
+- Log each migration applied
+- Return error if any migration fails (don't apply partial migrations)
+
+**3. Wire into db.go:**
+- After opening the database and setting PRAGMAs, call `RunMigrations(db)` automatically
+- Add a `//go:embed migrations/*.sql` directive in migrate.go to embed migration SQL files
+
+**4. Seed data:**
+Create `internal/store/migrations/003_seed_data.sql`:
+- Insert a default venue_settings row (currency: DKK, symbol: kr, rounding: 5000 = 50 kr, receipt_mode: digital)
+- Insert a default chip set ("Standard") with common denominations:
+  - 25 (white, #FFFFFF), 100 (red, #FF0000), 500 (green, #00AA00), 1000 (black, #000000), 5000 (blue, #0000FF)
+- Insert a second chip set ("Copenhagen") with DKK-friendly denominations:
+  - 100 (white), 500 (red), 1000 (green), 5000 (black), 10000 (blue)
+- **NO default admin operator in seed migration** — first-run setup handles this
+- Dev-only seed: create `internal/store/migrations/004_dev_seed.sql` with default admin (name: "Admin", PIN hash for "1234", role: "admin"). Only applied when `--dev` flag is set.
+
+**5. First-run setup:**
+- On startup, check if operators table has zero rows
+- If zero operators AND not --dev mode: server starts but returns a setup page at all routes except `/api/v1/setup`
+- `POST /api/v1/setup` — body: `{"name": "...", "pin": "..."}` — creates the first admin operator. Only works when zero operators exist. Returns JWT.
+- After first operator is created, normal app behavior resumes
+- In --dev mode: dev seed migration creates default admin, no setup screen needed
+
+**Verification:**
+- `make run` starts the binary and auto-applies all 3 migrations
+- Second startup skips already-applied migrations (idempotent)
+- `SELECT * FROM _migrations` shows all 3 rows
+- `SELECT * FROM operators` shows the default admin
+- `SELECT * FROM chip_denominations` shows 5 denominations
+- FTS5 search works: insert a player, query `SELECT * FROM players_fts WHERE players_fts MATCH 'searchterm'`
+</task>
+
+## Verification Criteria
+
+1. All migration SQL files are syntactically valid
+2. Migrations auto-apply on first startup, skip on subsequent startups
+3. All financial columns use INTEGER type (grep for REAL/FLOAT returns zero hits in schema)
+4. FTS5 virtual table syncs with players table via triggers
+5. Default seed data (admin operator, venue settings, chip set) exists after first startup
+6. Foreign key constraints are enforced (test by inserting invalid FK)
+7. Schema supports multi-tournament (tournament_id FK on all tournament-specific tables)
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Every money column is INTEGER (int64 cents) — zero float64 in the schema
+- [ ] Audit trail table is append-only by design (no UPDATE trigger needed — enforce in application code)
+- [ ] Player table exists with UUID PK for cross-venue portability
+- [ ] FTS5 enables typeahead search on player names
+- [ ] All tournament-specific tables reference tournament_id for multi-tournament support
+- [ ] Migration system is embedded and runs automatically on startup

.planning/phases/01-tournament-engine/01-PLAN-C.md

@@ -0,0 +1,186 @@
+# Plan C: Authentication + Audit Trail + Undo Engine
+
+---
+wave: 2
+depends_on: [01-PLAN-A, 01-PLAN-B]
+files_modified:
+  - internal/auth/pin.go
+  - internal/auth/jwt.go
+  - internal/server/middleware/auth.go
+  - internal/server/middleware/role.go
+  - internal/audit/trail.go
+  - internal/audit/undo.go
+  - internal/server/routes/auth.go
+  - internal/auth/pin_test.go
+  - internal/audit/trail_test.go
+  - internal/audit/undo_test.go
+autonomous: true
+requirements: [AUTH-01, AUTH-03, ARCH-08, PLYR-06]
+---
+
+## Goal
+
+Operators authenticate with a PIN that produces a local JWT with role claims. Every state-changing action writes an immutable audit trail entry to LibSQL and publishes to NATS JetStream. Any financial action or bust-out can be undone with full state reversal and re-ranking. This is the security and accountability foundation for the entire system.
+
+## Context
+
+- **PIN login flow:** Operator enters PIN → bcrypt compare against all operators → JWT issued with role claim (admin/floor/viewer)
+- **Rate limiting:** Exponential backoff after 5 failures, lockout after 10 (AUTH-05 spec, applied here to operator PIN too)
+- **JWT:** HS256 signed, 7-day expiry (local system, not internet-exposed — prevents mid-tournament logouts during 12+ hour sessions), claims: sub (operator ID), role, iat, exp
+- **Audit trail:** Every mutation writes to `audit_entries` table AND publishes to NATS `tournament.{id}.audit`
+- **Undo:** Creates a NEW audit entry that reverses the original — never deletes/modifies existing entries
+- See 01-RESEARCH.md Pattern 4 (Event-Sourced Audit Trail), PIN Authentication Flow
+
+## User Decisions (from CONTEXT.md)
+
+- **Undo is critical** — bust-outs, rebuys, add-ons, buy-ins can all be undone with full re-ranking
+- **Late registration soft lock with admin override** — logged in audit trail
+- **Operator is the Tournament Director (TD)**
+- **Roles:** Admin (full control), Floor (runtime actions), Viewer (read-only)
+
+## Tasks
+
+<task id="C1" title="Implement PIN authentication with JWT issuance">
+**1. PIN Service** (`internal/auth/pin.go`):
+- `AuthService` struct with db, signing key, rate limiter
+- `Login(ctx, pin string) (token string, operator Operator, err error)`:
+  - Check rate limiter — return `ErrTooManyAttempts` if blocked
+  - Load all operators from DB
+  - Try bcrypt.CompareHashAndPassword against each operator's pin_hash
+  - On match: reset failure counter, issue JWT, return token + operator
+  - On no match: record failure, return `ErrInvalidPIN`
+- Rate limiter (in-memory, per-IP or global for simplicity):
+  - Track consecutive failures
+  - After 5 failures: 30-second delay
+  - After 8 failures: 5-minute delay
+  - After 10 failures: 30-minute lockout
+  - Reset on successful login
+- `HashPIN(pin string) (string, error)` — bcrypt with cost 12 (for seed data and operator management)
+- `CreateOperator(ctx, name, pin, role string) error` — insert operator with hashed PIN
+- `ListOperators(ctx) ([]Operator, error)` — for admin management
+- `UpdateOperator(ctx, id, name, pin, role string) error`
+
+**2. JWT Service** (`internal/auth/jwt.go`):
+- `NewToken(operatorID, role string) (string, error)` — creates HS256-signed JWT with claims: sub, role, iat, exp (24h)
+- `ValidateToken(tokenString string) (*Claims, error)` — parses and validates JWT, returns claims
+- Claims struct: `OperatorID string`, `Role string` (admin/floor/viewer)
+- Signing key: generated randomly on first startup, stored in LibSQL `_config` table (persisted across restarts)
+
+**3. Auth Middleware** (`internal/server/middleware/auth.go`):
+- Extract JWT from `Authorization: Bearer <token>` header
+- Validate token, extract claims
+- Store claims in request context (`context.WithValue`)
+- Return 401 if missing/invalid/expired
+- Public routes (health, static files, WebSocket initial connect) bypass auth
+
+**4. Role Middleware** (`internal/server/middleware/role.go`):
+- `RequireRole(roles ...string)` middleware factory
+- Extract claims from context, check if role is in allowed list
+- Return 403 if insufficient role
+- Role hierarchy: admin > floor > viewer (admin can do everything floor can do)
+
+**5. Auth Routes** (`internal/server/routes/auth.go`):
+- `POST /api/v1/auth/login` — body: `{"pin": "1234"}` → response: `{"token": "...", "operator": {...}}`
+- `GET /api/v1/auth/me` — returns current operator from JWT claims
+- `POST /api/v1/auth/logout` — client-side only (JWT is stateless), but endpoint exists for audit logging
+
+**6. Tests** (`internal/auth/pin_test.go`):
+- Test successful login returns valid JWT
+- Test wrong PIN returns ErrInvalidPIN
+- Test rate limiting kicks in after 5 failures
+- Test lockout after 10 failures
+- Test successful login resets failure counter
+- Test JWT validation with expired token returns error
+- Test role middleware blocks insufficient roles
+
+**Verification:**
+- `POST /api/v1/auth/login` with PIN "1234" returns a JWT token
+- The token can be used to access protected endpoints
+- Wrong PIN returns 401
+- Rate limiting activates after 5 rapid failures
+- Role middleware blocks floor from admin-only endpoints
+</task>
+
+<task id="C2" title="Implement audit trail and undo engine">
+**1. Audit Trail** (`internal/audit/trail.go`):
+- `AuditTrail` struct with db, nats publisher
+- `Record(ctx, entry AuditEntry) error`:
+  - Generate UUID for entry ID
+  - Set timestamp to `time.Now().UnixNano()`
+  - Extract operator ID from context (set by auth middleware)
+  - Insert into `audit_entries` table in LibSQL
+  - Publish to NATS JetStream subject `tournament.{tournament_id}.audit`
+  - If tournament_id is empty (venue-level action), publish to `venue.audit`
+- `AuditEntry` struct per 01-RESEARCH.md Pattern 4:
+  - ID, TournamentID, Timestamp, OperatorID, Action, TargetType, TargetID
+  - PreviousState (json.RawMessage), NewState (json.RawMessage)
+  - Metadata (json.RawMessage, optional)
+  - UndoneBy (*string, nullable)
+- `GetEntries(ctx, tournamentID string, limit, offset int) ([]AuditEntry, error)` — paginated audit log
+- `GetEntry(ctx, entryID string) (*AuditEntry, error)` — single entry lookup
+- Action constants: define all action strings as constants:
+  - `player.buyin`, `player.bust`, `player.rebuy`, `player.addon`, `player.reentry`
+  - `financial.buyin`, `financial.rebuy`, `financial.addon`, `financial.payout`, `financial.chop`, `financial.bubble_prize`
+  - `clock.start`, `clock.pause`, `clock.resume`, `clock.advance`, `clock.rewind`, `clock.jump`
+  - `seat.assign`, `seat.move`, `seat.balance`, `seat.break_table`
+  - `tournament.create`, `tournament.start`, `tournament.end`, `tournament.cancel`
+  - `template.create`, `template.update`, `template.delete`
+  - `operator.login`, `operator.logout`
+  - `undo.*` — mirrors each action type
+
+**2. Undo Engine** (`internal/audit/undo.go`):
+- `UndoEngine` struct with db, audit trail, nats publisher
+- `Undo(ctx, auditEntryID string) error`:
+  - Load the original audit entry
+  - Verify it hasn't already been undone (check `undone_by` field)
+  - Create a NEW audit entry with:
+    - Action: `undo.{original_action}` (e.g., `undo.player.bust`)
+    - PreviousState: original's NewState
+    - NewState: original's PreviousState
+    - Metadata: `{"undone_entry_id": "original-id"}`
+  - Update the original entry's `undone_by` field to point to the new entry (this is the ONE exception to append-only — it marks an entry as undone, not deleting it)
+  - Return the undo entry for the caller to perform the actual state reversal
+- `CanUndo(ctx, auditEntryID string) (bool, error)` — checks if entry is undoable (not already undone, action type is undoable)
+- Undoable actions list: `player.bust`, `player.buyin`, `player.rebuy`, `player.addon`, `player.reentry`, `financial.*`, `seat.move`, `seat.balance`
+- Non-undoable actions: `clock.*`, `tournament.start`, `tournament.end`, `operator.*`
+
+**3. Integration with existing infrastructure:**
+- Add `AuditTrail` to the server struct, pass to all route handlers
+- Audit trail is a cross-cutting concern — every route handler that mutates state calls `audit.Record()`
+- Wire up NATS publisher to audit trail
+
+**4. Tests** (`internal/audit/trail_test.go`, `internal/audit/undo_test.go`):
+- Test audit entry is persisted to LibSQL with all fields
+- Test audit entry is published to NATS JetStream
+- Test undo creates new entry and marks original as undone
+- Test double-undo returns error
+- Test non-undoable action returns error
+- Test GetEntries pagination works correctly
+- Test operator ID is extracted from context
+
+**Verification:**
+- Every state mutation creates an audit_entries row with correct previous/new state
+- NATS JetStream receives the audit event on the correct subject
+- Undo creates a reversal entry and marks the original
+- Double-undo is rejected
+- Audit log is queryable by tournament, action type, and time range
+</task>
+
+## Verification Criteria
+
+1. PIN login produces valid JWT with role claims
+2. Auth middleware rejects requests without valid JWT
+3. Role middleware enforces admin/floor/viewer hierarchy
+4. Rate limiting activates after 5 failed login attempts
+5. Every state mutation produces an audit_entries row
+6. Undo creates a new audit entry (never deletes the original)
+7. Double-undo is rejected with clear error
+8. All tests pass
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Operator PIN → local JWT works offline (no external IdP dependency)
+- [ ] Three roles (Admin, Floor, Viewer) enforced on all API endpoints
+- [ ] Every state-changing action writes an append-only audit trail entry
+- [ ] Financial transactions and bust-outs can be undone with audit trail reversal
+- [ ] Undo never deletes or overwrites existing audit entries (only marks them and creates new ones)

.planning/phases/01-tournament-engine/01-PLAN-D.md

@@ -0,0 +1,237 @@
+# Plan D: Clock Engine
+
+---
+wave: 2
+depends_on: [01-PLAN-A, 01-PLAN-B]
+files_modified:
+  - internal/clock/engine.go
+  - internal/clock/ticker.go
+  - internal/clock/warnings.go
+  - internal/server/routes/clock.go
+  - internal/clock/engine_test.go
+  - internal/clock/warnings_test.go
+autonomous: true
+requirements: [CLOCK-01, CLOCK-02, CLOCK-03, CLOCK-04, CLOCK-05, CLOCK-06, CLOCK-07, CLOCK-08, CLOCK-09]
+---
+
+## Goal
+
+A server-authoritative tournament clock counts down each level with millisecond precision, transitions automatically between levels (rounds and breaks), supports pause/resume/advance/rewind/jump, emits configurable warnings, and broadcasts state to all WebSocket clients at 1/sec (10/sec in final 10s). Reconnecting clients receive a full clock snapshot immediately. Multiple clock engines run independently for multi-tournament support.
+
+## Context
+
+- **Server-authoritative clock** — clients NEVER run their own timer. Server sends absolute state (level, remaining_ms, is_paused, server_timestamp), clients calculate display from server time
+- **Tick rates:** 1/sec normal, 10/sec in final 10 seconds of each level (CLOCK-08)
+- **Clock state machine:** stopped → running ↔ paused → stopped (CLOCK-03)
+- **Level transitions are automatic** — when a level's time expires, advance to next level (CLOCK-01)
+- **Breaks have distinct treatment** — levels can be round or break type (CLOCK-02)
+- See 01-RESEARCH.md: Clock Engine State Machine code example, Pitfall 5 (Clock Drift)
+
+## User Decisions (from CONTEXT.md)
+
+- **Overview tab priority:** Clock & current level is the biggest element (top priority)
+- **Multi-tournament switching** — each tournament has its own independent clock (MULTI-01)
+- **Hand-for-hand mode** (SEAT-09) — clock pauses, per-hand deduction. The clock engine must support this mode
+
+## Tasks
+
+<task id="D1" title="Implement clock engine state machine and ticker">
+**1. Clock Engine** (`internal/clock/engine.go`):
+- `ClockEngine` struct:
+  - `mu sync.RWMutex`
+  - `tournamentID string`
+  - `state ClockState` (stopped/running/paused)
+  - `levels []Level` — the blind structure levels for this tournament
+  - `currentLevel int` — index into levels
+  - `remainingNs int64` — nanoseconds remaining in current level
+  - `lastTick time.Time` — monotonic clock reference for drift-free timing
+  - `totalElapsedNs int64` — total tournament time (excludes paused time)
+  - `pausedAt *time.Time` — when pause started (for elapsed tracking)
+  - `handForHand bool` — hand-for-hand mode flag
+  - `hub *ws.Hub` — WebSocket hub for broadcasting
+  - `auditTrail *audit.AuditTrail` — for recording clock actions
+
+- `Level` struct:
+  - `Position int`
+  - `LevelType string` — "round" or "break"
+  - `GameType string` — e.g., "nlhe", "plo", "horse" (for mixed game rotation)
+  - `SmallBlind int64` (cents)
+  - `BigBlind int64` (cents)
+  - `Ante int64` (cents)
+  - `BBAnte int64` (cents, big blind ante)
+  - `DurationSeconds int`
+  - `ChipUpDenomination *int64` (nullable)
+  - `Notes string`
+
+- State machine methods:
+  - `Start()` — transition from stopped → running, set lastTick, record audit entry
+  - `Pause()` — transition from running → paused, record remaining time, record audit entry
+  - `Resume()` — transition from paused → running, reset lastTick, record audit entry
+  - `Stop()` — transition to stopped (tournament end)
+  - `AdvanceLevel()` — move to next level (CLOCK-04 forward)
+  - `RewindLevel()` — move to previous level (CLOCK-04 backward)
+  - `JumpToLevel(levelIndex int)` — jump to any level by index (CLOCK-05)
+  - `SetHandForHand(enabled bool)` — toggle hand-for-hand flag on the clock snapshot (called by seating engine, SEAT-09). When enabled, clock pauses. When disabled, clock resumes.
+
+- `advanceLevel()` (internal, called when timer expires):
+  - If current level is the last level, enter overtime (repeat last level or stop — configurable)
+  - Otherwise, increment currentLevel, set remainingNs from new level's DurationSeconds
+  - Emit level_change event via WebSocket broadcast
+  - If new level is a break, emit break_start event
+  - If previous level was a break, emit break_end event
+
+- `Snapshot() ClockSnapshot` — returns current state for reconnecting clients (CLOCK-09):
+  ```go
+  type ClockSnapshot struct {
+      TournamentID    string     `json:"tournament_id"`
+      State           string     `json:"state"` // "stopped", "running", "paused"
+      CurrentLevel    int        `json:"current_level"`
+      Level           Level      `json:"level"` // Current level details
+      NextLevel       *Level     `json:"next_level"` // Preview of next level (nullable if last)
+      RemainingMs     int64      `json:"remaining_ms"`
+      TotalElapsedMs  int64      `json:"total_elapsed_ms"`
+      ServerTimeMs    int64      `json:"server_time_ms"` // For client drift correction
+      HandForHand     bool       `json:"hand_for_hand"`
+      LevelCount      int        `json:"level_count"` // Total levels in structure
+      Warnings        []Warning  `json:"warnings"` // Active warning thresholds
+  }
+  ```
+
+- `LoadLevels(levels []Level)` — load blind structure levels into the engine
+
+**2. Ticker** (`internal/clock/ticker.go`):
+- `StartTicker(ctx context.Context, engine *ClockEngine)`:
+  - Run in a goroutine
+  - Normal mode: tick every 100ms (check if second changed, broadcast at 1/sec)
+  - Final 10s mode: broadcast every 100ms (10/sec effective)
+  - On each tick:
+    1. Lock engine mutex
+    2. If state is not running, skip
+    3. Calculate elapsed since lastTick using monotonic clock
+    4. Subtract from remainingNs
+    5. Update totalElapsedNs
+    6. Check for level transition (remainingNs <= 0)
+    7. Determine if broadcast is needed (1/sec or 10/sec)
+    8. Build ClockSnapshot
+    9. Unlock mutex
+    10. Broadcast via hub (outside the lock)
+  - Use `time.NewTicker(100 * time.Millisecond)` for consistent 100ms checks
+  - Stop ticker on context cancellation
+
+**3. Clock Registry** (in engine.go or separate):
+- `ClockRegistry` — manages multiple clock engines (one per tournament)
+- `GetOrCreate(tournamentID string, hub *Hub) *ClockEngine`
+- `Get(tournamentID string) *ClockEngine`
+- `Remove(tournamentID string)` — cleanup after tournament ends
+- Thread-safe with sync.RWMutex
+
+**Verification:**
+- Create a clock engine, load 3 levels (2 rounds + 1 break), start it
+- Clock counts down, advancing through levels automatically
+- Pause stops the countdown, resume continues from where it left
+- Snapshot returns correct remaining time at any moment
+- Multiple clock engines run independently with different levels
+</task>
+
+<task id="D2" title="Implement clock warnings and API routes">
+**1. Warning System** (`internal/clock/warnings.go`):
+- `WarningThreshold` struct: `Seconds int`, `Type string` (audio/visual/both), `SoundID string`, `Message string`
+- Default warning thresholds: 60s, 30s, 10s (configurable per tournament)
+- `checkWarnings()` method on ClockEngine:
+  - Check if remainingNs just crossed a threshold (was above, now below)
+  - If crossed, emit warning event via WebSocket: `{type: "clock.warning", seconds: 60, sound: "warning_60s"}`
+  - Track which warnings have been emitted for current level (reset on level change)
+  - Don't re-emit if already emitted (prevent duplicate warnings on tick boundary)
+
+- Level change sound event: when level changes, emit `{type: "clock.level_change", sound: "level_change"}`
+- Break start/end sounds: emit `{type: "clock.break_start", sound: "break_start"}` and `break_end`
+
+**2. Clock API Routes** (`internal/server/routes/clock.go`):
+All routes require auth middleware. Mutation routes require admin or floor role.
+
+- `POST /api/v1/tournaments/{id}/clock/start` — start the clock
+  - Load blind structure from DB, create/get clock engine, call Start()
+  - Response: ClockSnapshot
+
+- `POST /api/v1/tournaments/{id}/clock/pause` — pause
+  - Response: ClockSnapshot
+
+- `POST /api/v1/tournaments/{id}/clock/resume` — resume
+  - Response: ClockSnapshot
+
+- `POST /api/v1/tournaments/{id}/clock/advance` — advance to next level
+  - Response: ClockSnapshot
+
+- `POST /api/v1/tournaments/{id}/clock/rewind` — go back to previous level
+  - Response: ClockSnapshot
+
+- `POST /api/v1/tournaments/{id}/clock/jump` — body: `{"level": 5}`
+  - Validate level index is within range
+  - Response: ClockSnapshot
+
+- `GET /api/v1/tournaments/{id}/clock` — get current clock state
+  - Response: ClockSnapshot
+  - This is also what WebSocket clients receive on connect
+
+- `PUT /api/v1/tournaments/{id}/clock/warnings` — body: `{"warnings": [{"seconds": 60, "type": "both", "sound": "warning"}]}`
+  - Update warning thresholds for this tournament
+  - Response: updated warnings config
+
+All mutation endpoints:
+- Record audit entry (action, previous state, new state)
+- Persist clock state to tournament record in DB (currentLevel, remainingNs, state)
+- Broadcast updated state via WebSocket hub
+
+**3. Clock State Persistence:**
+- On every meaningful state change (pause, resume, level advance, jump), persist to DB:
+  - `UPDATE tournaments SET current_level = ?, clock_state = ?, clock_remaining_ns = ?, total_elapsed_ns = ? WHERE id = ?`
+- On startup, if a tournament was "running" when the server stopped, resume with adjusted remaining time (or pause it — safer for crash recovery)
+
+**4. Tests** (`internal/clock/engine_test.go`, `internal/clock/warnings_test.go`):
+- Test clock counts down correctly over simulated time
+- Test pause preserves remaining time exactly
+- Test resume continues from paused position
+- Test level auto-advance when time expires
+- Test jump to specific level sets correct remaining time
+- Test rewind to previous level
+- Test warning threshold detection (crossing boundary)
+- Test warning not re-emitted for same level
+- Test hand-for-hand mode pauses clock
+- Test multiple independent engines don't interfere
+- Test crash recovery: clock persisted as "running" resumes correctly on startup
+- Test snapshot includes all required fields (CLOCK-09)
+- Test total elapsed time excludes paused periods
+
+**Verification:**
+- Clock API endpoints work via curl
+- Clock ticks appear on WebSocket connection
+- Warning events fire at correct thresholds
+- Level transitions happen automatically
+- Clock state survives server restart
+</task>
+
+## Verification Criteria
+
+1. Clock counts down each level with second-granularity display and transitions automatically
+2. Breaks display with distinct visual treatment (level_type: "break" in snapshot)
+3. Pause/resume works with correct remaining time preservation
+4. Forward/backward level advance works
+5. Jump to any level by number works
+6. Total elapsed time displays correctly (excludes paused time)
+7. Warning events fire at configured thresholds (60s, 30s, 10s default)
+8. WebSocket clients receive clock ticks at 1/sec (10/sec in final 10s)
+9. Reconnecting WebSocket clients receive full clock snapshot immediately
+10. Multiple tournament clocks run independently
+11. Clock state persists to DB and survives server restart
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Server-authoritative clock — clients never run their own timer
+- [ ] Automatic level transitions (rounds and breaks)
+- [ ] Pause/resume with visual indicator data in snapshot
+- [ ] Jump to any level by number
+- [ ] Configurable warning thresholds with audio/visual events
+- [ ] 1/sec normal ticks, 10/sec final 10 seconds
+- [ ] Full clock snapshot on WebSocket connect (reconnection)
+- [ ] Independent clock per tournament (multi-tournament)
+- [ ] Clock state persisted to DB (crash recovery)

.planning/phases/01-tournament-engine/01-PLAN-E.md

@@ -0,0 +1,252 @@
+# Plan E: Blind Structure + Chip Sets + Templates
+
+---
+wave: 2
+depends_on: [01-PLAN-A, 01-PLAN-B]
+files_modified:
+  - internal/blind/structure.go
+  - internal/blind/wizard.go
+  - internal/blind/templates.go
+  - internal/template/chipset.go
+  - internal/template/payout.go
+  - internal/template/buyin.go
+  - internal/template/tournament.go
+  - internal/server/routes/templates.go
+  - internal/blind/wizard_test.go
+  - internal/template/tournament_test.go
+autonomous: true
+requirements: [BLIND-01, BLIND-02, BLIND-03, BLIND-04, BLIND-05, BLIND-06, CHIP-01, CHIP-02, CHIP-03, CHIP-04, FIN-01, FIN-02, FIN-05, FIN-06, FIN-10]
+---
+
+## Goal
+
+All reusable building blocks — chip sets, blind structures, payout structures, buy-in configs — have full CRUD with API endpoints. Built-in templates (Turbo, Standard, Deep Stack, WSOP-style) ship as seed data. The structure wizard generates a blind structure from inputs (player count, starting chips, duration, denominations). Tournament templates compose these building blocks. Template management is a dedicated area.
+
+## Context
+
+- **Templates are compositions of building blocks** — not monolithic configs (CONTEXT.md locked decision)
+- **Building blocks are venue-level** — shared across tournaments
+- **Local changes by default** — tournament gets a copy, edits don't affect the template
+- **Structure wizard** lives in template management (CONTEXT.md locked decision)
+- **Built-in templates** ship with the app (BLIND-05)
+- **Big Blind Ante** support alongside standard ante (BLIND-02)
+- **Mixed game rotation** (HORSE, 8-Game) via game type per level (BLIND-03)
+- See 01-RESEARCH.md for blind wizard algorithm description
+
+## User Decisions (from CONTEXT.md)
+
+- **Template-first creation** — TD picks a template, everything pre-fills, tweak for tonight, Start
+- **Building blocks feel like LEGO** — pick chip set, pick blind structure, pick payout table, name it, done
+- **Dedicated template management area** — create from scratch, duplicate/edit existing, save tournament config as new template
+- **Entry count = unique entries only** — for payout bracket selection
+- **Prize rounding** — round down to nearest venue-configured denomination
+
+## Tasks
+
+<task id="E1" title="Implement building block CRUD: chip sets, blind structures, payout structures, buy-in configs">
+**1. Chip Set Service** (`internal/template/chipset.go`):
+- `ChipSet` struct: ID, Name, IsBuiltin, CreatedAt, UpdatedAt
+- `ChipDenomination` struct: ID, ChipSetID, Value (int64 cents), ColorHex, Label, SortOrder
+- CRUD operations:
+  - `CreateChipSet(ctx, name string, denominations []ChipDenomination) (*ChipSet, error)`
+  - `GetChipSet(ctx, id string) (*ChipSet, error)` — includes denominations
+  - `ListChipSets(ctx) ([]ChipSet, error)`
+  - `UpdateChipSet(ctx, id, name string, denominations []ChipDenomination) error`
+  - `DeleteChipSet(ctx, id string) error` — fail if referenced by active tournament
+  - `DuplicateChipSet(ctx, id string, newName string) (*ChipSet, error)`
+- Built-in chip sets cannot be deleted (is_builtin = true), but can be duplicated
+
+**2. Blind Structure Service** (`internal/blind/structure.go`):
+- `BlindStructure` struct: ID, Name, IsBuiltin, GameTypeDefault, Notes, CreatedAt, UpdatedAt
+- `BlindLevel` struct per BLIND-01:
+  - Position, LevelType (round/break), GameType
+  - SmallBlind, BigBlind, Ante, BBAnte (all int64) — BLIND-02
+  - DurationSeconds, ChipUpDenominationValue (*int64 nullable) — CHIP-02
+  - Notes
+- CRUD operations:
+  - `CreateStructure(ctx, name string, levels []BlindLevel) (*BlindStructure, error)`
+  - `GetStructure(ctx, id string) (*BlindStructure, error)` — includes levels ordered by position
+  - `ListStructures(ctx) ([]BlindStructure, error)`
+  - `UpdateStructure(ctx, id string, name string, levels []BlindLevel) error`
+  - `DeleteStructure(ctx, id string) error`
+  - `DuplicateStructure(ctx, id string, newName string) (*BlindStructure, error)`
+- Validation:
+  - At least one round level required
+  - Small blind < big blind
+  - Duration > 0 for all levels
+  - Positions must be contiguous starting from 0
+
+**3. Payout Structure Service** (`internal/template/payout.go`):
+- `PayoutStructure` struct: ID, Name, IsBuiltin, CreatedAt, UpdatedAt
+- `PayoutBracket` struct: ID, StructureID, MinEntries, MaxEntries
+- `PayoutTier` struct: ID, BracketID, Position, PercentageBasisPoints (int64, 5000 = 50.00%)
+- CRUD with brackets and tiers as nested entities
+- Validation:
+  - Brackets must cover contiguous ranges (no gaps)
+  - Tier percentages per bracket must sum to exactly 10000 (100.00%)
+  - At least one bracket required
+
+**4. Buy-in Config Service** (`internal/template/buyin.go`):
+- `BuyinConfig` struct with all fields from schema: buyin amount, starting chips, rake, bounty, rebuy config, addon config, reentry config, late reg config
+- `RakeSplit` struct: Category (house/staff/league/season_reserve), Amount (int64 cents)
+- CRUD operations
+- Validation:
+  - Rake splits sum must equal rake_total
+  - All amounts must be non-negative
+  - Rebuy/addon limits must be non-negative
+  - If bounty_amount > 0, bounty_chip must be > 0
+
+**5. API Routes** (`internal/server/routes/templates.go`):
+All routes require auth. Create/update/delete require admin role. List/get are floor+ accessible.
+
+Chip Sets:
+- `GET /api/v1/chip-sets` — list all
+- `GET /api/v1/chip-sets/{id}` — get with denominations
+- `POST /api/v1/chip-sets` — create
+- `PUT /api/v1/chip-sets/{id}` — update
+- `DELETE /api/v1/chip-sets/{id}` — delete
+- `POST /api/v1/chip-sets/{id}/duplicate` — duplicate
+
+Blind Structures:
+- `GET /api/v1/blind-structures` — list all
+- `GET /api/v1/blind-structures/{id}` — get with levels
+- `POST /api/v1/blind-structures` — create
+- `PUT /api/v1/blind-structures/{id}` — update
+- `DELETE /api/v1/blind-structures/{id}` — delete
+- `POST /api/v1/blind-structures/{id}/duplicate` — duplicate
+
+Payout Structures:
+- `GET /api/v1/payout-structures` — list all
+- `GET /api/v1/payout-structures/{id}` — get with brackets and tiers
+- `POST /api/v1/payout-structures` — create
+- `PUT /api/v1/payout-structures/{id}` — update
+- `DELETE /api/v1/payout-structures/{id}` — delete
+- `POST /api/v1/payout-structures/{id}/duplicate` — duplicate
+
+Buy-in Configs:
+- `GET /api/v1/buyin-configs` — list all
+- `GET /api/v1/buyin-configs/{id}` — get
+- `POST /api/v1/buyin-configs` — create
+- `PUT /api/v1/buyin-configs/{id}` — update
+- `DELETE /api/v1/buyin-configs/{id}` — delete
+- `POST /api/v1/buyin-configs/{id}/duplicate` — duplicate
+
+All mutations record audit entries.
+
+**Verification:**
+- Full CRUD cycle for each building block type via curl
+- Validation rejects invalid inputs (e.g., payout tiers not summing to 100%)
+- Built-in items cannot be deleted
+- Duplicate creates independent copy
+</task>
+
+<task id="E2" title="Implement tournament templates, built-in seed data, and structure wizard">
+**1. Tournament Template Service** (`internal/template/tournament.go`):
+- `TournamentTemplate` struct: ID, Name, Description, ChipSetID, BlindStructureID, PayoutStructureID, BuyinConfigID, PointsFormulaID (nullable), MinPlayers, MaxPlayers, EarlySignupBonusChips, EarlySignupCutoff, PunctualityBonusChips, IsPKO, IsBuiltin, CreatedAt, UpdatedAt
+- CRUD operations:
+  - `CreateTemplate(ctx, template TournamentTemplate) (*TournamentTemplate, error)` — validates all FK references exist
+  - `GetTemplate(ctx, id string) (*TournamentTemplate, error)` — returns template with populated building block summaries (names, not full data)
+  - `GetTemplateExpanded(ctx, id string) (*ExpandedTemplate, error)` — returns template with ALL building block data (for tournament creation)
+  - `ListTemplates(ctx) ([]TournamentTemplate, error)`
+  - `UpdateTemplate(ctx, template TournamentTemplate) error`
+  - `DeleteTemplate(ctx, id string) error`
+  - `DuplicateTemplate(ctx, id string, newName string) (*TournamentTemplate, error)`
+  - `SaveAsTemplate(ctx, tournamentID string, name string) (*TournamentTemplate, error)` — creates a new template from a tournament's current config
+
+- API Routes:
+  - `GET /api/v1/tournament-templates` — list all
+  - `GET /api/v1/tournament-templates/{id}` — get with building block summaries
+  - `GET /api/v1/tournament-templates/{id}/expanded` — get with full building block data
+  - `POST /api/v1/tournament-templates` — create
+  - `PUT /api/v1/tournament-templates/{id}` — update
+  - `DELETE /api/v1/tournament-templates/{id}` — delete
+  - `POST /api/v1/tournament-templates/{id}/duplicate` — duplicate
+
+**2. Built-in Seed Data** (`internal/blind/templates.go`):
+Create built-in templates that ship with the app. Add to seed migration or boot logic (skip if already exist).
+
+Built-in Blind Structures:
+- **Turbo** (~2hr for 20 players): 15-minute levels, aggressive blind jumps, 1 break
+  - Levels: 25/50, 50/100, 75/150, 100/200, break, 150/300, 200/400, 300/600, 400/800, break, 600/1200, 800/1600, 1000/2000, 1500/3000, 2000/4000
+  - Starting chips: 10,000
+- **Standard** (~3-4hr for 20 players): 20-minute levels, moderate progression, 2 breaks
+  - Levels: 25/50, 50/100, 75/150, 100/200, 150/300, break, 200/400, 300/600, 400/800, 500/1000, break, 600/1200, 800/1600, 1000/2000, 1500/3000, 2000/4000, 3000/6000
+  - Starting chips: 15,000
+- **Deep Stack** (~5-6hr for 20 players): 30-minute levels, slow progression, 3 breaks
+  - Starting chips: 25,000, wider level range
+- **WSOP-style**: 60-minute levels, with antes starting at level 4, BB ante option
+  - Starting chips: 50,000, slow progression
+
+Built-in Payout Structures:
+- **Standard**: 8-20 entries (3 prizes: 50/30/20), 21-30 (4 prizes: 45/26/17/12), 31-40 (5 prizes), 41+ (6 prizes)
+
+Built-in Tournament Templates (compose the above):
+- Turbo template (Turbo blinds + Standard payout + default chip set + basic buy-in)
+- Standard template
+- Deep Stack template
+- WSOP-style template
+
+Each built-in has `is_builtin = true` — cannot be deleted, but can be duplicated.
+
+**3. Structure Wizard** (`internal/blind/wizard.go`):
+Algorithm to generate a blind structure from inputs:
+- Inputs: `playerCount int`, `startingChips int64`, `targetDurationMinutes int`, `chipSetID string` (for denomination alignment)
+- Algorithm (from 01-RESEARCH.md):
+  1. Calculate target number of levels: `targetDuration / levelDuration` (default 20-minute levels)
+  2. Calculate target final big blind: `startingChips * playerCount / 10` (roughly — at the end, average stack = 10 BB)
+  3. Calculate geometric progression ratio: `(finalBB / initialBB)^(1/numLevels)`
+  4. Generate levels with geometric blind progression
+  5. Snap each blind to nearest chip denomination from the chip set
+  6. Ensure SB = BB/2 (or closest denomination)
+  7. Add antes starting at ~level 4-5 (standard is ante = BB at higher levels)
+  8. Insert breaks every 4-5 levels (10-minute breaks)
+  9. Mark chip-up breaks when lower denominations are no longer needed
+- Output: `[]BlindLevel` ready to save as a blind structure
+
+- API Route:
+  - `POST /api/v1/blind-structures/wizard` — body: `{"player_count": 20, "starting_chips": 15000, "target_duration_minutes": 240, "chip_set_id": "..."}`
+  - Response: generated `[]BlindLevel` (NOT saved — preview only, TD can then save)
+
+**4. Tests:**
+- `internal/blind/wizard_test.go`:
+  - Test wizard generates sensible structure for various inputs (10, 20, 40, 80 players)
+  - Test blind values align with chip denominations
+  - Test breaks are inserted at reasonable intervals
+  - Test generated structure has increasing blinds
+  - Test edge case: very short tournament (1 hour), very long tournament (8 hours)
+- `internal/template/tournament_test.go`:
+  - Test template creation with valid FK references
+  - Test template creation with invalid FK reference returns error
+  - Test SaveAsTemplate from running tournament
+  - Test GetTemplateExpanded returns all building block data
+
+**Verification:**
+- All 4 built-in templates exist after first startup
+- Wizard generates a blind structure from sample inputs
+- Generated blind values align with chip denominations
+- Full CRUD for tournament templates works
+- Template expanded endpoint returns complete building block data
+</task>
+
+## Verification Criteria
+
+1. Unlimited configurable levels with all fields (round/break, game type, SB/BB, ante, BB ante, duration, chip-up, notes)
+2. Big Blind Ante field exists alongside standard ante
+3. Mixed game rotation via game_type per level
+4. Blind structures can be saved/loaded as reusable templates
+5. 4 built-in blind structures + 4 built-in tournament templates exist on first boot
+6. Structure wizard produces a playable structure from inputs
+7. Chip sets with denominations, colors, and values fully manageable
+8. Chip-up tracking via chip_up_denomination field per level
+9. Payout structures with entry-count brackets work correctly
+10. All building blocks compose into tournament templates
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Building blocks are independent reusable entities (not embedded in templates)
+- [ ] Templates compose building blocks by reference (LEGO pattern)
+- [ ] Built-in templates ship with the app and cannot be deleted
+- [ ] Structure wizard generates playable blind structures from inputs
+- [ ] Big Blind Ante and mixed game rotation are supported in the level definition
+- [ ] Payout structure tiers always sum to exactly 100% per bracket
+- [ ] Chip denominations have colors for display rendering

.planning/phases/01-tournament-engine/01-PLAN-F.md

@@ -0,0 +1,268 @@
+# Plan F: Financial Engine
+
+---
+wave: 3
+depends_on: [01-PLAN-C, 01-PLAN-E]
+files_modified:
+  - internal/financial/engine.go
+  - internal/financial/payout.go
+  - internal/financial/receipt.go
+  - internal/server/routes/financials.go
+  - internal/financial/engine_test.go
+  - internal/financial/payout_test.go
+autonomous: true
+requirements: [FIN-03, FIN-04, FIN-07, FIN-08, FIN-09, FIN-12, FIN-13, FIN-14]
+---
+
+## Goal
+
+The financial engine processes buy-ins, rebuys, add-ons, re-entries, and bounty transfers. It calculates prize pools from all inputs, handles guaranteed pots, tracks rake splits (including season reserve), and generates receipts for every transaction. All math uses int64 cents. Every transaction writes an audit entry and can be undone. A CI gate test proves sum of payouts always equals prize pool.
+
+## Context
+
+- **All money is int64 cents** (ARCH-03) — already enforced in schema (Plan B)
+- **Buy-in config is a building block** — already created in Plan E
+- **Payout structures with brackets** — already created in Plan E
+- **Audit trail + undo** — already created in Plan C
+- **Late registration soft lock with admin override** — logged in audit trail (CONTEXT.md)
+- See 01-RESEARCH.md Pattern 5 (Int64 Financial Math), Pitfall 4 (Payout Rounding)
+
+## User Decisions (from CONTEXT.md)
+
+- **Entry count = unique entries only** — not rebuys or add-ons (for payout bracket selection)
+- **Prize rounding** — round down to nearest venue-configured denomination
+- **Bubble prize** — fast and prominent, funded by shaving top prizes
+- **PKO (Progressive Knockout)** — half bounty to hitman, half added to own bounty
+- **Receipts configurable per venue** — off / digital / print / both
+- **Late registration soft lock with admin override**
+
+## Tasks
+
+<task id="F1" title="Implement financial transaction engine">
+**1. Financial Engine** (`internal/financial/engine.go`):
+- `FinancialEngine` struct with db, audit trail, nats publisher
+
+- `ProcessBuyIn(ctx, tournamentID, playerID string, override bool) (*Transaction, error)`:
+  - Load tournament's buyin config
+  - Check late registration eligibility:
+    - Load tournament clock state (current level, elapsed time)
+    - If past cutoff AND not override → return `ErrLateRegistrationClosed`
+    - If past cutoff AND override → allow, log admin override in audit trail (CONTEXT.md: admin override logged)
+    - If no cutoff → always allow
+  - Check max players limit
+  - Create transaction record:
+    - Type: "buyin"
+    - Amount: buyin_amount (int64 cents)
+    - Chips: starting_chips + any applicable bonuses (early signup, punctuality)
+  - Create rake split transactions (one per category: house, staff, league, season_reserve)
+  - If PKO tournament: create bounty initialization (bounty_amount → half initial bounty value on player)
+  - Persist all to transactions table
+  - Record audit entry with full state
+  - Broadcast via WebSocket
+  - Return transaction for receipt generation
+
+- `ProcessRebuy(ctx, tournamentID, playerID string) (*Transaction, error)`:
+  - Check player is active in tournament
+  - Check rebuy eligibility:
+    - Rebuy allowed in buyin config
+    - Player's rebuy count < rebuy_limit (0 = unlimited)
+    - Current level/time within rebuy cutoff
+    - Player's chip count <= rebuy_chip_threshold (if configured)
+  - Create transaction record (type: "rebuy")
+  - Increment player's rebuy count
+  - Record audit entry
+  - Broadcast
+  - Return transaction
+
+- `ProcessAddOn(ctx, tournamentID, playerID string) (*Transaction, error)`:
+  - Check addon allowed and within addon window (level_start to level_end)
+  - Check player hasn't already added on (addon is typically once per tournament)
+  - Create transaction, increment addon count
+  - Record audit entry, broadcast, return
+
+- `ProcessReEntry(ctx, tournamentID, playerID string) (*Transaction, error)`:
+  - Re-entry is distinct from rebuy (FIN-04): player must be busted first
+  - Check player status is "busted"
+  - Check reentry allowed and within reentry limit
+  - Reactivate player with fresh starting chips
+  - Increment reentry count (does NOT count as new unique entry for payout brackets)
+  - Process like a buy-in financially (same cost, rake)
+  - Re-seat player (auto-seat)
+  - Record audit entry, broadcast, return
+
+- `ProcessBountyTransfer(ctx, tournamentID, eliminatedPlayerID, hitmanPlayerID string) error`:
+  - For PKO tournaments (FIN-07):
+    - Eliminated player's bounty value → half goes to hitman as cash prize, half adds to hitman's own bounty
+    - Track the chain in transaction metadata
+    - Create bounty_collected transaction for hitman
+    - Create bounty_paid transaction for eliminated player
+  - For fixed bounty (non-progressive):
+    - Full bounty amount goes to hitman
+  - Record audit entry with bounty chain details
+
+- `UndoTransaction(ctx, transactionID string) error`:
+  - Use undo engine (Plan C) to create reversal audit entry
+  - Reverse the financial effects:
+    - Subtract chips from player
+    - Decrement rebuy/addon/reentry count
+    - If buyin undo: remove player from tournament (status → removed)
+    - If bounty undo: reverse bounty transfer
+  - Trigger re-ranking (will be called by player management in Plan G)
+  - Broadcast updates
+
+- `GetTransactions(ctx, tournamentID string) ([]Transaction, error)` — all transactions for a tournament
+- `GetPlayerTransactions(ctx, tournamentID, playerID string) ([]Transaction, error)` — player-specific
+
+**2. Late Registration Logic:**
+- `IsLateRegistrationOpen(ctx, tournamentID string) (bool, error)`:
+  - Check buyin config cutoffs (level AND/OR time — FIN-03: "end of Level 6 or first 90 minutes, whichever comes first")
+  - Load current clock state
+  - Both conditions checked: if either cutoff is exceeded, late reg is closed
+  - Return true if still open
+
+**3. Season Withholding** (FIN-12):
+- When processing rake splits, if a "season_reserve" category exists, that portion is earmarked
+- Track in a `season_reserves` summary (aggregated from rake_split transactions)
+- API endpoint to query season reserves: `GET /api/v1/season-reserves`
+
+**Verification:**
+- Buy-in creates correct transaction with rake splits
+- Rebuy respects limits and cutoffs
+- Add-on respects window
+- Re-entry requires busted status
+- PKO bounty transfer splits correctly (half cash, half to bounty)
+- Late registration cutoff enforced (level AND time conditions)
+- Admin override bypasses late reg with audit log
+- Transaction undo reverses all effects
+</task>
+
+<task id="F2" title="Implement prize pool calculation, payout distribution, and receipts">
+**1. Prize Pool Calculator** (`internal/financial/payout.go`):
+- `CalculatePrizePool(ctx, tournamentID string) (PrizePoolSummary, error)`:
+  - Load all non-undone transactions for the tournament
+  - Sum all buy-in amounts (minus rake)
+  - Sum all rebuy amounts (minus rake)
+  - Sum all add-on amounts (minus rake)
+  - Sum all re-entry amounts (minus rake)
+  - Prize pool = total contributions (not rake)
+  - Check guaranteed pot (FIN-09): if prize pool < guarantee, house covers shortfall
+  - Return summary:
+    ```go
+    type PrizePoolSummary struct {
+        TotalEntries      int     // Unique entries only (not rebuys/addons)
+        TotalRebuys       int
+        TotalAddOns       int
+        TotalReEntries    int
+        TotalBuyInAmount  int64   // cents
+        TotalRebuyAmount  int64
+        TotalAddOnAmount  int64
+        TotalReEntryAmount int64
+        TotalRake         int64   // All rake categories combined
+        RakeByCategory    map[string]int64 // house, staff, league, season_reserve
+        PrizePool         int64   // After rake, before guarantee
+        Guarantee         int64   // Configured guarantee amount
+        HouseContribution int64   // House covers if pool < guarantee
+        FinalPrizePool    int64   // Max(PrizePool, Guarantee)
+        TotalBountyPool   int64   // Sum of all bounty amounts (PKO)
+        TotalChipsInPlay  int64   // CHIP-03
+        AverageStack      int64   // CHIP-04: TotalChipsInPlay / remaining players
+        RemainingPlayers  int
+    }
+    ```
+
+- `CalculatePayouts(ctx, tournamentID string) ([]Payout, error)`:
+  - Load prize pool and entry count
+  - Load payout structure, select correct bracket by entry count (unique entries only)
+  - Load venue rounding denomination
+  - Calculate each position's payout:
+    - Raw amount = FinalPrizePool * tier.PercentageBasisPoints / 10000
+    - Rounded = (raw / roundingDenomination) * roundingDenomination — always round DOWN
+  - Assign remainder to 1st place (standard poker convention)
+  - Return list of Payout structs: `{Position int, Amount int64, Percentage int64}`
+  - **CRITICAL:** Assert `sum(payouts) == FinalPrizePool` — if not, panic (this is a bug)
+
+- `ApplyPayouts(ctx, tournamentID string, payouts []Payout) error`:
+  - For each payout, create a "payout" transaction for the player in that finishing position
+  - Record audit entries
+  - Broadcast updates
+
+**2. Bubble Prize** (from CONTEXT.md):
+- `CalculateBubblePrize(ctx, tournamentID string, amount int64) (*BubblePrizeProposal, error)`:
+  - Load current payouts
+  - Calculate redistribution: shave from top prizes (proportionally from 1st-3rd primarily, extending to 4th-5th if needed)
+  - Return proposal showing original and adjusted payouts for each position
+- `ConfirmBubblePrize(ctx, tournamentID string, proposalID string) error`:
+  - Apply the redistributed payout structure
+  - Add bubble prize position to payouts
+  - Record audit entry
+
+**3. Receipt Generation** (`internal/financial/receipt.go`):
+- `GenerateReceipt(ctx, transaction Transaction) (*Receipt, error)`:
+  - Build receipt data from transaction:
+    - Venue name, tournament name, date/time
+    - Player name
+    - Transaction type and amount
+    - Chips received
+    - Running totals (total entries, rebuys, addons for this player)
+    - Receipt number (sequential per tournament)
+  - Return Receipt struct with all fields (rendering is frontend's job for digital, or ESC/POS for print — defer print to later)
+- `GetReceipt(ctx, transactionID string) (*Receipt, error)` — retrieve saved receipt
+- `ReprintReceipt(ctx, transactionID string) (*Receipt, error)` — FIN-14: reprint capability (same receipt data, new print timestamp)
+
+**4. API Routes** (`internal/server/routes/financials.go`):
+- `GET /api/v1/tournaments/{id}/prize-pool` — current prize pool summary
+- `GET /api/v1/tournaments/{id}/payouts` — calculated payout table
+- `GET /api/v1/tournaments/{id}/payouts/preview` — preview with current entries (not applied yet)
+- `POST /api/v1/tournaments/{id}/bubble-prize` — body: `{"amount": 5000}` → proposal
+- `POST /api/v1/tournaments/{id}/bubble-prize/{proposalId}/confirm` — confirm bubble prize
+- `GET /api/v1/tournaments/{id}/transactions` — all transactions
+- `GET /api/v1/tournaments/{id}/transactions/{txId}/receipt` — get receipt
+- `POST /api/v1/tournaments/{id}/transactions/{txId}/reprint` — reprint receipt
+- `GET /api/v1/season-reserves` — season withholding summary
+
+**5. CI Gate Test** (`internal/financial/payout_test.go`):
+- Property-based test: generate random prize pools (1000 to 10,000,000 cents), random payout structures (2-20 positions), random rounding denominations (100, 500, 1000, 5000)
+- For each combination: assert `sum(payouts) == prizePool` — ZERO deviation
+- Run at least 10,000 random combinations
+- This test MUST pass in CI — it's the financial integrity gate
+- Also test:
+  - Guaranteed pot: pool < guarantee → house contribution makes up difference
+  - Bubble prize: redistributed payouts still sum to prize pool + bubble amount
+  - Rounding never creates money (never rounds up)
+  - Entry count uses unique entries only (not rebuys)
+
+**Verification:**
+- Prize pool calculation matches manual calculation for test scenarios
+- Payouts sum to exactly prize pool in all cases (CI gate test)
+- Bubble prize redistribution is correct and prominent
+- Receipts contain all required information
+- Season withholding is tracked separately
+- Guaranteed pot fills shortfall correctly
+</task>
+
+## Verification Criteria
+
+1. Buy-in, rebuy, add-on, and re-entry flows produce correct transactions
+2. Late registration cutoff works (level AND/OR time — whichever comes first)
+3. Admin override for late reg is logged in audit trail
+4. PKO bounty transfer splits correctly (half cash, half to own bounty)
+5. Prize pool calculation includes all contributions minus rake
+6. Guaranteed pot: house covers shortfall
+7. Payout rounding always rounds DOWN, remainder to 1st place
+8. CI gate test: sum(payouts) == prize_pool across 10,000+ random inputs
+9. Bubble prize redistribution is correct and traceable
+10. Receipts generated for every financial transaction
+11. Transaction undo reverses all effects with audit trail
+12. Season withholding (reserve rake) tracked separately
+
+## Must-Haves (Goal-Backward)
+
+- [ ] All financial math uses int64 cents — zero float64
+- [ ] CI gate test proves sum(payouts) == prize_pool, always, zero deviation
+- [ ] Late registration with admin override (soft lock, not hard lock)
+- [ ] PKO bounty half-split with chain tracking
+- [ ] Prize pool auto-calculation from all inputs
+- [ ] Guaranteed pot support (house covers shortfall)
+- [ ] Every financial action generates a receipt
+- [ ] Transaction editing with audit trail and receipt reprint
+- [ ] Bubble prize creation is fast and accessible

.planning/phases/01-tournament-engine/01-PLAN-G.md

@@ -0,0 +1,254 @@
+# Plan G: Player Management
+
+---
+wave: 4
+depends_on: [01-PLAN-C, 01-PLAN-E, 01-PLAN-F]
+files_modified:
+  - internal/player/player.go
+  - internal/player/ranking.go
+  - internal/player/qrcode.go
+  - internal/player/import.go
+  - internal/server/routes/players.go
+  - internal/player/ranking_test.go
+  - internal/player/player_test.go
+autonomous: true
+requirements: [PLYR-02, PLYR-03, PLYR-04, PLYR-05, PLYR-06, PLYR-07]
+---
+
+## Goal
+
+The player database supports search with typeahead (FTS5), merge duplicates, and CSV import. The buy-in and bust-out flows are the core transaction paths. Rankings are derived from the ordered bust-out list (never stored independently). Undo on any player action triggers full re-ranking. Per-player tracking captures all stats. QR codes are generated per player for future self-check-in.
+
+## Context
+
+- **Player database is persistent on Leaf** (PLYR-01) — already in schema (Plan B)
+- **FTS5 virtual table** for typeahead — already created in Plan B
+- **Financial engine** for buy-in/rebuy/addon processing — Plan F
+- **Audit trail + undo** — Plan C
+- **Auto-seating** — Plan H (seating). Buy-in flow calls seating after financial processing
+- **Rankings are derived, not stored** — from 01-RESEARCH.md Pitfall 6: "Rankings should be derived from the ordered bust-out list, not stored as independent values"
+- See 01-RESEARCH.md Pitfall 6 (Undo Re-Rank)
+
+## User Decisions (from CONTEXT.md)
+
+- **Buy-in flow:** search/select player → auto-seat suggests optimal seat → TD can override → confirm → receipt
+- **Bust-out flow:** tap Bust → pick table → pick seat → verify name → confirm → select hitman (mandatory in PKO, optional otherwise) → done
+- **Undo is critical** — bust-outs, rebuys, add-ons, buy-ins can all be undone with full re-ranking
+- **Bust-out flow must be as few taps as possible** — TD is under time pressure
+
+## Tasks
+
+<task id="G1" title="Implement player CRUD, search, merge, import, and QR codes">
+**1. Player Service** (`internal/player/player.go`):
+- `PlayerService` struct with db, audit trail
+
+- `CreatePlayer(ctx, player Player) (*Player, error)`:
+  - Generate UUID
+  - Insert into players table
+  - FTS5 auto-syncs via trigger (Plan B)
+  - Record audit entry
+  - Return player
+
+- `GetPlayer(ctx, id string) (*Player, error)`
+
+- `UpdatePlayer(ctx, player Player) error`:
+  - Update fields, record audit entry
+  - FTS5 auto-syncs via trigger
+
+- `SearchPlayers(ctx, query string, limit int) ([]Player, error)` — PLYR-02:
+  - Use FTS5: `SELECT p.* FROM players p JOIN players_fts f ON p.rowid = f.rowid WHERE players_fts MATCH ? ORDER BY rank LIMIT ?`
+  - Support prefix matching for typeahead: append `*` to query terms
+  - Return results ordered by relevance (FTS5 rank)
+  - If query is empty, return most recently active players (for quick access)
+
+- `ListPlayers(ctx, limit, offset int) ([]Player, error)` — paginated list
+
+- `MergePlayers(ctx, keepID, mergeID string) error` — PLYR-02:
+  - Merge player `mergeID` into `keepID`:
+    - Move all tournament_players records from mergeID to keepID
+    - Move all transactions from mergeID to keepID
+    - Merge any non-empty fields from mergeID into keepID (name takes keepID, fill in blanks)
+    - Delete mergeID player record
+  - Record audit entry with full merge details
+  - This is destructive — require admin role
+
+- `ImportFromCSV(ctx, reader io.Reader) (ImportResult, error)` — PLYR-02:
+  - Parse CSV with headers: name, nickname, email, phone, notes (minimum: name required)
+  - For each row:
+    - Check for potential duplicates (FTS5 search on name)
+    - If exact name match exists, flag as duplicate (don't auto-merge)
+    - Otherwise create new player
+  - Return ImportResult: created count, duplicate count, error count, duplicate details
+  - Require admin role
+
+**2. Tournament Player Operations:**
+- `RegisterPlayer(ctx, tournamentID, playerID string) (*TournamentPlayer, error)`:
+  - Create tournament_players record with status "registered"
+  - Check tournament isn't full (max_players)
+  - Return tournament player record
+
+- `GetTournamentPlayers(ctx, tournamentID string) ([]TournamentPlayerDetail, error)`:
+  - Join tournament_players with players table
+  - Include computed fields: total investment, net result, action count
+  - Sort by status (active first), then by name
+
+- `GetTournamentPlayer(ctx, tournamentID, playerID string) (*TournamentPlayerDetail, error)`:
+  - Full player detail within tournament context (PLYR-07):
+    - Current chips, seat (table + position), playing time
+    - Rebuys count, add-ons count, re-entries count
+    - Bounties collected, bounty value (PKO)
+    - Prize amount, points awarded
+    - Net take (prize - total investment)
+    - Full action history (from audit trail + transactions)
+
+- `BustPlayer(ctx, tournamentID, playerID string, hitmanPlayerID *string) error` — PLYR-05:
+  - Validate player is active
+  - Set status to "busted", bust_out_at to now
+  - Calculate bust_out_order (count of currently busted players + 1, from the end)
+  - If PKO: hitman is mandatory, process bounty transfer (call financial engine)
+  - If not PKO: hitman is optional (for tracking who eliminated whom)
+  - Set hitman_player_id
+  - Clear seat assignment (remove from table)
+  - Record audit entry with previous state (for undo)
+  - Trigger balance check (notify if tables are unbalanced — seating engine, Plan H)
+  - Broadcast player bust event
+  - Check if tournament should auto-close (1 player remaining → tournament.end)
+
+- `UndoBust(ctx, tournamentID, playerID string) error` — PLYR-06:
+  - Restore player to active status
+  - Clear bust_out_at, bust_out_order, finishing_position, hitman_player_id
+  - If PKO: reverse bounty transfer
+  - Re-seat player (needs a seat — auto-assign or put back in original seat from audit trail)
+  - Trigger full re-ranking
+  - Record audit entry
+  - Broadcast
+
+**3. QR Code Generation** (`internal/player/qrcode.go`) — PLYR-03:
+- `GenerateQRCode(ctx, playerID string) ([]byte, error)`:
+  - Generate QR code encoding player UUID
+  - Return PNG image bytes
+  - QR code URL format: `felt://player/{uuid}` (for future PWA self-check-in)
+- API endpoint: `GET /api/v1/players/{id}/qrcode` — returns PNG image
+
+**Verification:**
+- Player CRUD works via API
+- FTS5 typeahead search returns results with prefix matching
+- CSV import creates players and flags duplicates
+- Merge combines two player records correctly
+- QR code generates valid PNG image
+</task>
+
+<task id="G2" title="Implement ranking engine and player API routes">
+**1. Ranking Engine** (`internal/player/ranking.go`):
+- Rankings are **derived from the ordered bust-out list**, never stored independently
+- `CalculateRankings(ctx, tournamentID string) ([]PlayerRanking, error)`:
+  - Load all tournament_players ordered by bust_out_at (nulls = still active)
+  - Active players: no ranking yet (still playing) — all share the same "current position" = remaining player count
+  - Busted players: ranked in reverse bust order (last busted = highest remaining, first busted = last place)
+  - Finishing position = total_unique_entries - bust_order + 1
+  - Handle re-entries: a re-entered player's previous bust is "cancelled" — they only have the final bust (or are still active)
+  - Handle deals: players who took a deal have status "deal" with manually assigned finishing positions
+
+- `RecalculateAllRankings(ctx, tournamentID string) error`:
+  - Called after any undo operation
+  - Recalculates ALL bust_out_order values from the bust_out_at timestamps
+  - Updates finishing_position for all busted players
+  - This ensures consistency even after undoing busts in the middle of the sequence
+  - Broadcast updated rankings
+
+- `GetRankings(ctx, tournamentID string) ([]PlayerRanking, error)`:
+  - Returns current rankings for display:
+    ```go
+    type PlayerRanking struct {
+        Position      int    // Current ranking position
+        PlayerID      string
+        PlayerName    string
+        Status        string // active, busted, deal
+        ChipCount     int64
+        BustOutTime   *int64
+        HitmanName    *string
+        BountiesCollected int
+        Prize         int64
+        Points        int64
+    }
+    ```
+  - Active players sorted by chip count (if available), then alphabetically
+  - Busted players sorted by bust order (most recent first)
+
+**2. Player API Routes** (`internal/server/routes/players.go`):
+
+Player database (venue-level):
+- `GET /api/v1/players` — list all players (paginated)
+- `GET /api/v1/players/search?q=john` — typeahead search (PLYR-02)
+- `POST /api/v1/players` — create player
+- `GET /api/v1/players/{id}` — get player
+- `PUT /api/v1/players/{id}` — update player
+- `GET /api/v1/players/{id}/qrcode` — QR code PNG (PLYR-03)
+- `POST /api/v1/players/merge` — body: `{"keep_id": "...", "merge_id": "..."}` (admin only)
+- `POST /api/v1/players/import` — multipart CSV upload (admin only)
+
+Tournament players:
+- `GET /api/v1/tournaments/{id}/players` — all players in tournament with stats
+- `GET /api/v1/tournaments/{id}/players/{playerId}` — player detail with full tracking (PLYR-07)
+- `POST /api/v1/tournaments/{id}/players/{playerId}/buyin` — buy-in flow (PLYR-04):
+  - Calls financial engine (Plan F) for transaction
+  - Calls seating engine (Plan H) for auto-seat
+  - Returns: transaction, seat assignment, receipt
+- `POST /api/v1/tournaments/{id}/players/{playerId}/bust` — bust-out flow (PLYR-05):
+  - Body: `{"hitman_player_id": "..."}` (required for PKO, optional otherwise)
+  - Calls financial engine for bounty transfer
+  - Calls ranking engine for re-ranking
+  - Calls seating engine for balance check
+  - Returns: updated rankings
+- `POST /api/v1/tournaments/{id}/players/{playerId}/rebuy` — rebuy (delegates to financial engine)
+- `POST /api/v1/tournaments/{id}/players/{playerId}/addon` — add-on (delegates to financial engine)
+- `POST /api/v1/tournaments/{id}/players/{playerId}/reentry` — re-entry (delegates to financial engine + seating)
+- `POST /api/v1/tournaments/{id}/players/{playerId}/undo-bust` — undo bust (PLYR-06)
+- `POST /api/v1/tournaments/{id}/transactions/{txId}/undo` — undo any transaction (PLYR-06)
+
+Rankings:
+- `GET /api/v1/tournaments/{id}/rankings` — current rankings
+
+All mutation endpoints record audit entries and broadcast via WebSocket.
+
+**3. Tests** (`internal/player/ranking_test.go`):
+- Test rankings derived correctly from bust order
+- Test undo bust triggers re-ranking of all subsequent positions
+- Test undo early bust (not the most recent) re-ranks correctly
+- Test re-entry doesn't count as new entry for ranking purposes
+- Test deal players get manually assigned positions
+- Test auto-close when 1 player remains
+- Test concurrent busts (order preserved by timestamp)
+
+**Verification:**
+- Buy-in flow creates player entry, transaction, and seat assignment
+- Bust-out flow busts player, processes bounty, re-ranks, checks balance
+- Undo bust restores player and re-ranks all subsequent busts
+- Rankings are always consistent with bust order
+- Player detail shows complete tracking data (PLYR-07)
+- Search returns results with typeahead behavior
+</task>
+
+## Verification Criteria
+
+1. Player search with typeahead returns results via FTS5 prefix matching
+2. Duplicate merge combines records correctly (admin only)
+3. CSV import creates players and flags duplicates
+4. QR code generates valid PNG with player UUID
+5. Buy-in flow: search → financial transaction → auto-seat → receipt
+6. Bust-out flow: select → hitman → bounty → rank → balance check
+7. Undo bust restores player with full re-ranking of all positions
+8. Undo buy-in removes player from tournament
+9. Per-player tracking shows all stats (PLYR-07)
+10. Rankings are always derived from bust-out list, never stored independently
+11. Tournament auto-closes when one player remains
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Typeahead search on player names using FTS5
+- [ ] Buy-in flow produces transaction + seat assignment + receipt
+- [ ] Bust-out flow with hitman selection and bounty transfer (PKO)
+- [ ] Undo capability for bust-out, rebuy, add-on, buy-in with full re-ranking
+- [ ] Rankings derived from ordered bust-out list (not stored independently)
+- [ ] Per-player tracking: chips, time, seat, moves, rebuys, add-ons, bounties, prize, points, net, history
+- [ ] QR code generation per player

.planning/phases/01-tournament-engine/01-PLAN-H.md

@@ -0,0 +1,342 @@
+# Plan H: Table & Seating Engine
+
+---
+wave: 3
+depends_on: [01-PLAN-C, 01-PLAN-B, 01-PLAN-D]
+files_modified:
+  - internal/seating/table.go
+  - internal/seating/balance.go
+  - internal/seating/breaktable.go
+  - internal/seating/blueprint.go
+  - internal/server/routes/tables.go
+  - internal/seating/balance_test.go
+  - internal/seating/breaktable_test.go
+autonomous: true
+requirements: [SEAT-01, SEAT-02, SEAT-03, SEAT-04, SEAT-05, SEAT-06, SEAT-07, SEAT-08, SEAT-09]
+---
+
+## Goal
+
+Tables with configurable seat counts are managed per tournament. Random initial seating fills tables evenly. The balancing engine suggests moves when tables are unbalanced, with live-adaptive suggestions that recalculate when the situation changes. Break Table dissolves a table and distributes players evenly. Dealer button tracking, hand-for-hand mode, and table blueprints (venue layout) are all supported. All moves use tap-tap flow (no drag-and-drop in Phase 1).
+
+## Context
+
+- **Tables are tournament-scoped** — each tournament has its own set of tables
+- **Table blueprints** are venue-level — save/load table configurations
+- **Balancing suggestions are pending proposals** — re-validated before execution (from 01-RESEARCH.md Pitfall 7)
+- **TDA-compliant balancing** — size difference threshold, move fairness, button awareness
+- **No drag-and-drop in Phase 1** — tap-tap flow (CONTEXT.md locked decision)
+- See 01-RESEARCH.md Pitfall 7 (Table Balancing Race Condition)
+
+## User Decisions (from CONTEXT.md)
+
+- **Oval table view (default)** — top-down view with numbered seats, switchable to list view
+- **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
+  4. Assistant reports back: "Seat 3 to Seat 5" — TD taps two seat numbers, done
+  5. Suggestion is live and adaptive — if situation changes, system recalculates or cancels
+- **Break Table is fully automatic** — distributes evenly, TD sees result
+- **No drag-and-drop in Phase 1** — tap-tap flow for all moves
+
+## Tasks
+
+<task id="H1" title="Implement table management, auto-seating, and blueprints">
+**1. Table Service** (`internal/seating/table.go`):
+- `TableService` struct with db, audit trail, hub
+
+- `CreateTable(ctx, tournamentID string, name string, seatCount int) (*Table, error)`:
+  - Validate seatCount is 6-10 (SEAT-01)
+  - Generate UUID, insert into tables table
+  - Record audit entry, broadcast
+
+- `CreateTablesFromBlueprint(ctx, tournamentID, blueprintID string) ([]Table, error)`:
+  - Load blueprint's table configs
+  - Create all tables from the blueprint
+  - Return created tables
+
+- `GetTables(ctx, tournamentID string) ([]TableDetail, error)`:
+  - Return all active tables with seated players:
+    ```go
+    type TableDetail struct {
+        ID                  string
+        Name                string
+        SeatCount           int
+        DealerButtonPosition *int  // SEAT-03
+        IsActive            bool
+        Seats               []SeatDetail // Array of seat_count length
+    }
+    type SeatDetail struct {
+        Position   int
+        PlayerID   *string
+        PlayerName *string
+        ChipCount  *int64
+        IsEmpty    bool
+    }
+    ```
+
+- `UpdateTable(ctx, tournamentID, tableID string, name string, seatCount int) error`
+- `DeactivateTable(ctx, tournamentID, tableID string) error` — soft delete (is_active = false)
+
+- `AssignSeat(ctx, tournamentID, playerID, tableID string, seatPosition int) error`:
+  - Validate seat is empty
+  - Update tournament_players record (seat_table_id, seat_position)
+  - Record audit entry, broadcast
+
+- `AutoAssignSeat(ctx, tournamentID, playerID string) (*SeatAssignment, error)` — SEAT-04:
+  - Find the table with the fewest players (fills evenly)
+  - If tie, pick randomly among tied tables
+  - Pick a random empty seat at that table
+  - Return the assignment (table, seat) for TD confirmation (or auto-apply)
+  - **Does NOT assign yet** — returns suggestion for TD to confirm or override
+
+- `ConfirmSeatAssignment(ctx, tournamentID, playerID string, assignment SeatAssignment) error`:
+  - Apply the seat assignment
+  - Record audit entry, broadcast
+
+- `MoveSeat(ctx, tournamentID, playerID string, toTableID string, toSeatPosition int) error` — SEAT-06 (tap-tap flow):
+  - Validate destination seat is empty
+  - Move player: update tournament_players record
+  - Record audit entry with from/to details
+  - Broadcast
+
+- `SwapSeats(ctx, tournamentID, player1ID, player2ID string) error`:
+  - Swap two players' seats atomically
+  - Record audit entry, broadcast
+
+**2. Dealer Button** (`internal/seating/table.go`) — SEAT-03:
+- `SetDealerButton(ctx, tournamentID, tableID string, position int) error`
+- `AdvanceDealerButton(ctx, tournamentID, tableID string) error`:
+  - Move button to next occupied seat (clockwise)
+  - Skip empty seats
+  - Record audit entry
+
+**3. Table Blueprints** (`internal/seating/blueprint.go`) — SEAT-02:
+- `Blueprint` struct: ID, Name, TableConfigs (JSON array of {name, seat_count})
+- CRUD operations:
+  - `CreateBlueprint(ctx, name string, configs []BlueprintTableConfig) (*Blueprint, error)`
+  - `GetBlueprint(ctx, id string) (*Blueprint, error)`
+  - `ListBlueprints(ctx) ([]Blueprint, error)`
+  - `UpdateBlueprint(ctx, blueprint Blueprint) error`
+  - `DeleteBlueprint(ctx, id string) error`
+  - `SaveBlueprintFromTournament(ctx, tournamentID, name string) (*Blueprint, error)` — snapshot current tables as blueprint
+
+**4. Hand-for-Hand Mode** — SEAT-09:
+Hand-for-hand is a synchronization mechanism: all tables play one hand at a time. Clock stays paused the entire time — no time deduction.
+
+State needed:
+- Tournament-level: `handForHand bool`, `currentHandNumber int`
+- Table-level: `handCompleted bool` (reset each hand round)
+
+- `SetHandForHand(ctx, tournamentID string, enabled bool) error`:
+  - Set hand_for_hand flag on tournament, initialize currentHandNumber = 1
+  - Pause clock (call clock engine `SetHandForHand(true)`)
+  - Reset handCompleted = false on all active tables
+  - Broadcast mode change to all clients (prominent visual indicator)
+  - Record audit entry
+
+- `TableHandComplete(ctx, tournamentID, tableID string) error`:
+  - Set handCompleted = true for this table
+  - Check if ALL active tables have handCompleted = true
+  - If yes: increment currentHandNumber, reset all tables to handCompleted = false, broadcast "next hand"
+  - If no: broadcast updated completion status (e.g., "3/5 tables complete")
+  - Record audit entry
+
+- `DisableHandForHand(ctx, tournamentID string) error`:
+  - Called when bubble bursts (player busted during hand-for-hand)
+  - Clear hand_for_hand flag, resume clock (call clock engine `SetHandForHand(false)`)
+  - Broadcast mode change
+  - Record audit entry
+
+API routes:
+- `POST /api/v1/tournaments/{id}/hand-for-hand` — body: `{"enabled": true}` — enable/disable
+- `POST /api/v1/tournaments/{id}/tables/{tableId}/hand-complete` — TD marks table as hand complete
+
+**Verification:**
+- Create tables with 6-10 seat counts
+- Auto-assign seats fills tables evenly
+- Move seat works with tap-tap (source, destination)
+- Dealer button advances to next occupied seat
+- Blueprints save and restore table layouts
+- Hand-for-hand mode pauses clock and enables per-hand tracking
+</task>
+
+<task id="H2" title="Implement table balancing and break table">
+**1. Balancing Engine** (`internal/seating/balance.go`) — SEAT-05:
+- `BalanceEngine` struct with db, audit trail, hub
+
+- `CheckBalance(ctx, tournamentID string) (*BalanceStatus, error)`:
+  - Load all active tables with player counts
+  - Calculate max difference between largest and smallest table
+  - TDA rule: tables are unbalanced if max difference > 1
+  - Return:
+    ```go
+    type BalanceStatus struct {
+        IsBalanced     bool
+        MaxDifference  int
+        Tables         []TableCount // {TableID, TableName, PlayerCount}
+        NeedsMoves     int          // How many players need to move
+    }
+    ```
+
+- `SuggestMoves(ctx, tournamentID string) ([]BalanceSuggestion, error)`:
+  - Algorithm (TDA-compliant):
+    1. Identify tables that need to lose players (largest tables)
+    2. Identify tables that need to gain players (smallest tables)
+    3. For each needed move:
+       a. Select player to move from source table:
+          - Prefer the player in the worst position relative to the button (fairness)
+          - Avoid moving a player who just moved (if tracked)
+          - Never move a player who is locked (if lock feature exists)
+       b. Select seat at destination table:
+          - Prefer seat that avoids giving the moved player immediate button advantage
+          - Random among equivalent seats
+    4. Generate suggestion:
+       ```go
+       type BalanceSuggestion struct {
+           ID           string
+           FromTableID  string
+           FromTableName string
+           ToTableID    string
+           ToTableName  string
+           PlayerID     *string  // Suggested player (nullable — TD chooses)
+           PlayerName   *string
+           Status       string  // pending, accepted, cancelled, expired
+           CreatedAt    int64
+       }
+       ```
+  - Suggestions are PROPOSALS — not auto-applied (CONTEXT.md: "operator confirmation required")
+  - Suggestions include dry-run preview (SEAT-05: "dry-run preview, never auto-apply")
+
+- `AcceptSuggestion(ctx, tournamentID, suggestionID string, fromSeat, toSeat int) error`:
+  - Re-validate the suggestion is still valid (live and adaptive):
+    - Is the source table still larger than the destination?
+    - Is the player still at the source table?
+    - Is the destination seat still empty?
+  - If invalid: cancel suggestion, generate new one, return error with "stale suggestion"
+  - If valid: execute the move (call MoveSeat)
+  - Mark suggestion as accepted
+  - Re-check if more moves are needed
+  - Record audit entry
+
+- `CancelSuggestion(ctx, tournamentID, suggestionID string) error`:
+  - Mark as cancelled
+  - Record audit entry
+
+- `InvalidateStaleSuggestions(ctx, tournamentID string) error`:
+  - Called whenever table state changes (bust, move, break table)
+  - Check all pending suggestions — if source/dest player counts no longer justify the move, cancel them
+  - If still needed but details changed, cancel and regenerate
+  - This implements the "live and adaptive" behavior from CONTEXT.md
+
+**2. Break Table** (`internal/seating/breaktable.go`) — SEAT-07:
+- `BreakTable(ctx, tournamentID, tableID string) (*BreakTableResult, error)`:
+  - Load all players at the table being broken
+  - Load all remaining active tables with available seats
+  - Distribute players as evenly as possible:
+    1. Sort destination tables by current player count (ascending)
+    2. For each player from broken table, assign to the table with fewest players
+    3. Assign random empty seat at destination table
+    4. Consider button position for fairness (TDA rules)
+  - Deactivate the broken table (is_active = false)
+  - Return result showing all moves:
+    ```go
+    type BreakTableResult struct {
+        BrokenTableID   string
+        BrokenTableName string
+        Moves           []BreakTableMove // {PlayerID, PlayerName, ToTableName, ToSeat}
+    }
+    ```
+  - The result is informational — the moves are already applied (Break Table is fully automatic per CONTEXT.md)
+  - Record audit entry with all moves
+  - Invalidate any pending balance suggestions
+  - Broadcast all changes
+
+**3. API Routes** (`internal/server/routes/tables.go`):
+
+Tables:
+- `GET /api/v1/tournaments/{id}/tables` — all tables with seated players (SEAT-08)
+- `POST /api/v1/tournaments/{id}/tables` — create table
+- `POST /api/v1/tournaments/{id}/tables/from-blueprint` — body: `{"blueprint_id": "..."}`
+- `PUT /api/v1/tournaments/{id}/tables/{tableId}` — update table
+- `DELETE /api/v1/tournaments/{id}/tables/{tableId}` — deactivate table
+
+Seating:
+- `POST /api/v1/tournaments/{id}/players/{playerId}/auto-seat` — get auto-seat suggestion (SEAT-04)
+- `POST /api/v1/tournaments/{id}/players/{playerId}/seat` — body: `{"table_id": "...", "seat_position": 3}` — assign/move
+- `POST /api/v1/tournaments/{id}/seats/swap` — body: `{"player1_id": "...", "player2_id": "..."}`
+
+Balancing:
+- `GET /api/v1/tournaments/{id}/balance` — check balance status
+- `POST /api/v1/tournaments/{id}/balance/suggest` — get move suggestions
+- `POST /api/v1/tournaments/{id}/balance/suggestions/{suggId}/accept` — body: `{"from_seat": 3, "to_seat": 7}` — accept with seat specifics
+- `POST /api/v1/tournaments/{id}/balance/suggestions/{suggId}/cancel` — cancel suggestion
+
+Break Table:
+- `POST /api/v1/tournaments/{id}/tables/{tableId}/break` — break table and redistribute
+
+Dealer Button:
+- `POST /api/v1/tournaments/{id}/tables/{tableId}/button` — body: `{"position": 3}`
+- `POST /api/v1/tournaments/{id}/tables/{tableId}/button/advance`
+
+Blueprints (venue-level):
+- `GET /api/v1/blueprints` — list all
+- `POST /api/v1/blueprints` — create
+- `GET /api/v1/blueprints/{id}`
+- `PUT /api/v1/blueprints/{id}`
+- `DELETE /api/v1/blueprints/{id}`
+- `POST /api/v1/tournaments/{id}/tables/save-blueprint` — body: `{"name": "..."}`
+
+Hand-for-Hand:
+- `POST /api/v1/tournaments/{id}/hand-for-hand` — body: `{"enabled": true}` — enable/disable mode
+- `POST /api/v1/tournaments/{id}/tables/{tableId}/hand-complete` — TD marks table's hand as complete
+
+All mutations record audit entries and broadcast.
+
+**4. Tests** (`internal/seating/balance_test.go`, `internal/seating/breaktable_test.go`):
+- Test balance detection: 2 tables with counts [8, 6] → unbalanced (diff > 1)
+- Test balance detection: 2 tables with counts [7, 6] → balanced (diff = 1)
+- Test suggestion generation picks player from largest table
+- Test stale suggestion detection (table state changed since suggestion)
+- Test live-adaptive behavior: bust during pending suggestion → suggestion cancelled
+- Test break table distributes evenly across remaining tables
+- Test break table with odd player count (some tables get one more)
+- Test break table deactivates the broken table
+- Test auto-seat fills tables evenly
+- Test dealer button advances to next occupied seat, skipping empty
+
+**Verification:**
+- Tables with 6-10 seats can be created and managed
+- Auto-seating fills tables evenly
+- Balance engine detects unbalanced tables (diff > 1)
+- Suggestions are live and adaptive (re-validated on accept)
+- Break Table distributes players evenly and deactivates the table
+- Dealer button tracks and advances correctly
+- Hand-for-hand mode works with clock integration
+</task>
+
+## Verification Criteria
+
+1. Tables with configurable seat counts (6-max to 10-max) work correctly
+2. Table blueprints save and restore venue layouts
+3. Dealer button tracking and advancement work
+4. Random initial seating fills tables evenly
+5. Balancing suggestions with operator confirmation (never auto-apply)
+6. Suggestions are live and adaptive (recalculate on state change)
+7. Tap-tap seat moves work (no drag-and-drop)
+8. Break Table dissolves and distributes players evenly
+9. Visual table data available (top-down with seats, SEAT-08)
+10. Hand-for-hand mode pauses clock with per-table completion tracking (all tables complete → next hand)
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Tables with configurable seat counts (6-10) per tournament
+- [ ] Random initial seating that fills tables evenly
+- [ ] Balancing suggestions are TD-driven with operator confirmation, never auto-apply
+- [ ] Suggestions are live and adaptive (invalidated when state changes)
+- [ ] Break Table automatically distributes players evenly
+- [ ] Tap-tap flow for seat moves (no drag-and-drop in Phase 1)
+- [ ] Dealer button tracking per table
+- [ ] Table blueprints for saving venue layouts
+- [ ] Hand-for-hand mode with per-table completion tracking and clock pause

.planning/phases/01-tournament-engine/01-PLAN-I.md

@@ -0,0 +1,334 @@
+# Plan I: Tournament Lifecycle + Multi-Tournament + Chop/Deal
+
+---
+wave: 5
+depends_on: [01-PLAN-D, 01-PLAN-F, 01-PLAN-G, 01-PLAN-H]
+files_modified:
+  - internal/tournament/tournament.go
+  - internal/tournament/state.go
+  - internal/tournament/multi.go
+  - internal/financial/icm.go
+  - internal/financial/chop.go
+  - internal/server/routes/tournaments.go
+  - internal/financial/icm_test.go
+  - internal/financial/chop_test.go
+  - internal/tournament/tournament_test.go
+  - internal/tournament/integration_test.go
+autonomous: true
+requirements: [MULTI-01, MULTI-02, FIN-11, SEAT-06]
+---
+
+## Goal
+
+The tournament lifecycle — create from template, configure, start, run, and close — works end-to-end. Multiple simultaneous tournaments run with fully independent state (clocks, financials, players, tables). A tournament lobby shows all active tournaments. Chop/deal support (ICM, chip-chop, even-chop, custom) handles end-game scenarios. The tap-tap seat move flow from the seating engine is wired into the full tournament context.
+
+## Context
+
+- **Clock engine** — Plan D (running, independent per tournament)
+- **Financial engine** — Plan F (transactions, prize pool, payouts)
+- **Player management** — Plan G (buy-in, bust-out, rankings)
+- **Seating engine** — Plan H (tables, balancing, break table)
+- **Template-first creation** — CONTEXT.md: TD picks template, everything pre-fills
+- **Tournament auto-closes** when one player remains (CONTEXT.md)
+- **ICM calculator:** Malmuth-Harville exact for <=10 players, Monte Carlo for 11+ (01-RESEARCH.md Pitfall 3)
+
+## User Decisions (from CONTEXT.md)
+
+- **Template-first creation** — pick template → pre-fill → tweak → Start
+- **Local changes by default** — tournament gets a copy of building blocks
+- **Tournament auto-closes** when one player remains — no manual "end tournament" button
+- **Multi-tournament switching** — tabs at top (phone) or split view (tablet landscape)
+- **Flexible chop/deal support** — ICM, custom split, partial chop, any number of players
+- **Prize money and league positions are independent** — money can be chopped but positions determined by play
+- **Minimum player threshold** — Start button unavailable until met
+
+## Tasks
+
+<task id="I1" title="Implement tournament lifecycle and multi-tournament management">
+**1. Tournament Service** (`internal/tournament/tournament.go`):
+- `TournamentService` struct with db, clock registry, financial engine, player service, seating service, audit trail, hub
+
+- `CreateFromTemplate(ctx, templateID string, overrides TournamentOverrides) (*Tournament, error)`:
+  - Load expanded template (all building blocks)
+  - Create tournament record with status "created"
+  - Copy all building block references (chip_set_id, blind_structure_id, etc.) — local copy semantics
+  - Apply overrides (name, min/max players, bonuses, PKO flag, etc.)
+  - Create tables from blueprint if specified, or empty table set
+  - Record audit entry
+  - Broadcast tournament.created event
+  - Return tournament
+
+- `CreateManual(ctx, config TournamentConfig) (*Tournament, error)`:
+  - Create without a template — manually specify all config
+  - Same flow but no template reference
+
+- `GetTournament(ctx, id string) (*TournamentDetail, error)`:
+  - Return full tournament state:
+    ```go
+    type TournamentDetail struct {
+        Tournament      Tournament
+        ClockSnapshot   *ClockSnapshot
+        Tables          []TableDetail
+        Players         PlayerSummary  // counts: registered, active, busted
+        PrizePool       PrizePoolSummary
+        Rankings        []PlayerRanking
+        RecentActivity  []AuditEntry   // last 20 audit entries
+        BalanceStatus   *BalanceStatus
+    }
+    ```
+
+- `StartTournament(ctx, id string) error`:
+  - Validate minimum players met
+  - Validate at least one table exists with seats
+  - Set status to "registering" → "running"
+  - Start the clock engine (loads blind structure, starts countdown)
+  - Set started_at timestamp
+  - Record audit entry
+  - Broadcast tournament.started event
+
+- `PauseTournament(ctx, id string) error`:
+  - Pause the clock
+  - Set status to "paused"
+  - Record audit entry, broadcast
+
+- `ResumeTournament(ctx, id string) error`:
+  - Resume the clock
+  - Set status to "running"
+  - Record audit entry, broadcast
+
+- `EndTournament(ctx, id string) error`:
+  - Called automatically when 1 player remains, or manually for deals
+  - Stop the clock
+  - Assign finishing positions to remaining active players
+  - Calculate and apply final payouts
+  - Set status to "completed", ended_at timestamp
+  - Record audit entry
+  - Broadcast tournament.ended event
+
+- `CancelTournament(ctx, id string) error`:
+  - Set status to "cancelled"
+  - Stop clock if running
+  - Void all pending transactions (mark as cancelled, not deleted)
+  - Record audit entry, broadcast
+
+- `CheckAutoClose(ctx, id string) error`:
+  - Called after every bust-out (from player management)
+  - Count remaining active players
+  - If 1 remaining: auto-close tournament
+  - If 0 remaining (edge case): cancel tournament
+
+**2. Tournament State Aggregation** (`internal/tournament/state.go`):
+- `GetTournamentState(ctx, id string) (*TournamentState, error)`:
+  - Aggregates all state for WebSocket snapshot:
+    - Clock state (from clock engine)
+    - Player counts (registered, active, busted)
+    - Table states (all tables with seats)
+    - Financial summary (prize pool, entries, rebuys)
+    - Rankings (current)
+    - Balance status
+  - This is what new WebSocket connections receive (replaces the stub from Plan A)
+  - Sent as a single JSON message on connect
+
+- `BuildActivityFeed(ctx, tournamentID string, limit int) ([]ActivityEntry, error)`:
+  - Convert recent audit entries into human-readable activity items:
+    ```go
+    type ActivityEntry struct {
+        Timestamp   int64  `json:"timestamp"`
+        Type        string `json:"type"`      // "bust", "buyin", "rebuy", "clock", "seat", etc.
+        Title       string `json:"title"`      // "John Smith busted by Jane Doe"
+        Description string `json:"description"` // "Table 1, Seat 4 → 12th place"
+        Icon        string `json:"icon"`       // For frontend rendering
+    }
+    ```
+
+**3. Multi-Tournament Manager** (`internal/tournament/multi.go`) — MULTI-01:
+- `MultiManager` struct — manages multiple tournament services (or uses tournament-scoped queries)
+- `ListActiveTournaments(ctx) ([]TournamentSummary, error)` — MULTI-02:
+  - Return all tournaments with status in (registering, running, paused, final_table)
+  - Summary: ID, name, status, player count, current level, blind, remaining time
+  - This powers the tournament lobby view
+
+- `GetTournamentSummary(ctx, id string) (*TournamentSummary, error)`:
+  - Lightweight summary for lobby display
+
+- **Independence guarantee:** Every piece of state (clock, players, tables, financials) is scoped by tournament_id. No global singletons. Multiple tournaments run simultaneously with zero interference.
+
+**4. API Routes** (`internal/server/routes/tournaments.go`):
+- `POST /api/v1/tournaments` — create from template: body: `{"template_id": "...", "name": "Friday Night Turbo", "overrides": {...}}`
+- `POST /api/v1/tournaments/manual` — create without template
+- `GET /api/v1/tournaments` — list all (active and recent)
+- `GET /api/v1/tournaments/active` — active only (lobby, MULTI-02)
+- `GET /api/v1/tournaments/{id}` — full tournament state
+- `GET /api/v1/tournaments/{id}/state` — WebSocket-compatible full state snapshot
+- `POST /api/v1/tournaments/{id}/start` — start tournament
+- `POST /api/v1/tournaments/{id}/pause` — pause
+- `POST /api/v1/tournaments/{id}/resume` — resume
+- `POST /api/v1/tournaments/{id}/cancel` — cancel
+- `GET /api/v1/tournaments/{id}/activity` — recent activity feed
+
+**5. WebSocket Integration:**
+- Update the WebSocket hub (Plan A) to send full tournament state on connect
+- Messages are typed: `{type: "clock.tick", data: {...}}`, `{type: "player.bust", data: {...}}`, etc.
+- Client subscribes to a specific tournament by sending `{type: "subscribe", tournament_id: "..."}`
+- Lobby clients subscribe without tournament_id to receive all tournament summaries
+
+**Verification:**
+- Create tournament from template with all config pre-filled
+- Start tournament after minimum players met
+- Multiple tournaments run simultaneously with independent state
+- Tournament auto-closes when 1 player remains
+- Lobby shows all active tournaments
+- WebSocket sends full state on connect
+</task>
+
+<task id="I2" title="Implement chop/deal support with ICM calculator">
+**1. ICM Calculator** (`internal/financial/icm.go`) — FIN-11:
+- `Malmuth-Harville Algorithm` (exact, for <= 10 players):
+  - Calculate each player's equity in the prize pool based on chip stacks
+  - Recursively calculate probability of each player finishing in each position
+  - `CalculateICMExact(stacks []int64, payouts []int64) ([]int64, error)`:
+    - Input: chip stacks (int64) and payout amounts (int64 cents)
+    - Output: ICM value for each player (int64 cents)
+    - Algorithm: for each player, calculate P(finish in each position) using chip-proportion recursion
+    - Sum P(position) * payout(position) for all positions
+
+- `Monte Carlo ICM` (approximate, for 11+ players):
+  - `CalculateICMMonteCarlo(stacks []int64, payouts []int64, iterations int) ([]int64, error)`:
+    - Default iterations: 100,000 (converges to <0.1% error per 01-RESEARCH.md)
+    - Simulate tournament outcomes based on chip probabilities
+    - For each iteration: randomly determine finishing order weighted by chip stacks
+    - Average results across all iterations
+    - Return ICM values (int64 cents)
+
+- `CalculateICM(stacks []int64, payouts []int64) ([]int64, error)`:
+  - Dispatcher: use exact if <= 10 players, Monte Carlo otherwise
+  - Validate inputs: stacks and payouts must be non-empty, all positive
+  - ICM values must sum to total prize pool (validate before returning)
+
+**2. Chop/Deal Engine** (`internal/financial/chop.go`):
+- `ChopEngine` struct with financial engine, audit trail
+
+- `ProposeDeal(ctx, tournamentID string, dealType string, params DealParams) (*DealProposal, error)`:
+  - Deal types:
+    - **ICM**: TD inputs chip stacks → system calculates ICM values → shows proposed payouts
+    - **Chip Chop**: Divide pool proportionally by chip count (simpler than ICM)
+    - **Even Chop**: Equal split among all remaining players
+    - **Custom**: TD enters specific amounts per player
+    - **Partial Chop**: Split some money, keep remainder + points in play (CONTEXT.md: "split some money, play on for remaining + league points")
+  - DealParams:
+    ```go
+    type DealParams struct {
+        PlayerStacks   map[string]int64 // playerID -> chip count (for ICM/chip chop)
+        CustomAmounts  map[string]int64 // playerID -> custom payout (for custom)
+        PartialPool    int64            // Amount to split (for partial chop)
+        RemainingPool  int64            // Amount left in play (for partial chop)
+    }
+    ```
+  - Returns proposal for all remaining players with calculated payouts:
+    ```go
+    type DealProposal struct {
+        ID            string
+        TournamentID  string
+        DealType      string
+        Payouts       []DealPayout // {PlayerID, PlayerName, Amount, ChipStack, ICMValue}
+        TotalAmount   int64        // Must equal prize pool (or partial pool for partial chop)
+        IsPartial     bool
+        RemainingPool int64        // If partial, what's still in play
+        CreatedAt     int64
+    }
+    ```
+  - Validate: sum of proposed payouts == total pool (or partial pool)
+  - Does NOT apply yet — returns proposal for TD approval
+
+- `ConfirmDeal(ctx, tournamentID, proposalID string) error`:
+  - Apply all payouts as transactions
+  - If full chop: set all players' status to "deal", assign finishing positions
+  - If partial chop: apply partial payouts, tournament continues with remaining pool
+  - **Prize money and league positions are independent** (CONTEXT.md): positions for league points are based on chip counts at deal time (or play on for partial chop)
+  - Record audit entry with full deal details
+  - If full chop: end tournament (set status "completed")
+  - Broadcast
+
+- `CancelDeal(ctx, tournamentID, proposalID string) error`
+
+**3. API Routes (add to tournaments.go):**
+- `POST /api/v1/tournaments/{id}/deal/propose` — body: `{"type": "icm", "stacks": {"player1": 50000, "player2": 30000}}`
+- `GET /api/v1/tournaments/{id}/deal/proposals` — list proposals
+- `POST /api/v1/tournaments/{id}/deal/proposals/{proposalId}/confirm` — confirm deal
+- `POST /api/v1/tournaments/{id}/deal/proposals/{proposalId}/cancel` — cancel
+
+**4. Tests:**
+- `internal/financial/icm_test.go`:
+  - Test ICM exact with 2 players: known expected values
+  - Test ICM exact with 3 players: verify against known ICM tables
+  - Test ICM exact with 5 players: verify sum equals prize pool
+  - Test ICM Monte Carlo with 15 players: verify result is within 1% of expected (statistical test)
+  - Test ICM with equal stacks: all players should get approximately equal ICM values
+  - Test ICM edge case: one player has 99% of chips
+  - Test performance: ICM for 10 players completes in < 1 second
+  - Test performance: Monte Carlo ICM for 20 players completes in < 2 seconds
+
+- `internal/financial/chop_test.go`:
+  - Test chip chop: payouts proportional to chip stacks
+  - Test even chop: all players get equal amounts
+  - Test custom split: arbitrary amounts summing to pool
+  - Test partial chop: partial payouts + remaining pool for continuation
+  - Test deal sets finishing positions correctly
+  - Test full chop ends tournament
+
+- `internal/tournament/tournament_test.go`:
+  - Test create from template pre-fills all config
+  - Test start requires minimum players
+  - Test auto-close when 1 player remains
+  - Test multiple tournaments run independently
+  - Test tournament state aggregation includes all components
+
+- `internal/tournament/integration_test.go` — **End-to-end tournament lifecycle test:**
+  - Create tournament from template (standard 10-player, PKO)
+  - Register 10 players with buy-ins (verify prize pool, rake, seat assignments)
+  - Start tournament, advance clock through 3 levels
+  - Process 2 rebuys, 1 add-on (verify prize pool update, transaction log)
+  - Bust 5 players with bounty transfers (verify rankings, hitman chain, balance check)
+  - Undo 1 bust → verify re-ranking of all subsequent positions
+  - Run table balancing (verify suggestion → accept → move)
+  - Break a table (verify even redistribution)
+  - Propose and confirm ICM deal with remaining 5 players
+  - **Final assertions:**
+    - Sum of all payouts == prize pool (int64, zero deviation)
+    - All 10 players have correct finishing positions
+    - Audit trail contains every state-changing action
+    - All transactions are accounted for (buyin + rebuy + addon = contributions, payouts + rake = disbursements)
+    - Tournament status is "completed"
+
+**Verification:**
+- ICM calculation produces correct values for known test cases
+- All chop types produce valid payouts summing to prize pool
+- Partial chop allows tournament to continue
+- Full deal ends the tournament and assigns positions
+- Multiple tournaments run simultaneously without interference
+- Tournament lobby shows all active tournaments
+</task>
+
+## Verification Criteria
+
+1. Tournament creation from template pre-fills all configuration
+2. Tournament start requires minimum players met
+3. Tournament auto-closes when one player remains
+4. Multiple simultaneous tournaments with independent clocks, financials, and players
+5. Tournament lobby shows all active tournaments (MULTI-02)
+6. ICM calculator works for 2-20+ players (exact for <=10, Monte Carlo for 11+)
+7. All chop types (ICM, chip-chop, even-chop, custom, partial) work correctly
+8. Prize money and league positions are independent in deal scenarios
+9. Full tournament state sent on WebSocket connect
+10. Activity feed shows recent actions in human-readable form
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Template-first tournament creation with local copy semantics
+- [ ] Tournament auto-closes when one player remains
+- [ ] Multiple simultaneous tournaments with fully independent state
+- [ ] Tournament lobby view for multi-tournament overview
+- [ ] ICM calculator (exact <=10, Monte Carlo 11+) produces correct values
+- [ ] Chop/deal support (ICM, chip-chop, even-chop, custom, partial)
+- [ ] Prize money and league positions independent
+- [ ] Full tournament state available on WebSocket connect

.planning/phases/01-tournament-engine/01-PLAN-J.md

@@ -0,0 +1,220 @@
+# Plan J: SvelteKit Frontend Scaffold + Theme + Clients
+
+---
+wave: 2
+depends_on: [01-PLAN-A]
+files_modified:
+  - frontend/package.json
+  - frontend/svelte.config.js
+  - frontend/vite.config.ts
+  - frontend/tsconfig.json
+  - frontend/src/app.html
+  - frontend/src/app.css
+  - frontend/src/routes/+layout.ts
+  - frontend/src/lib/theme/catppuccin.css
+  - frontend/src/lib/ws.ts
+  - frontend/src/lib/api.ts
+  - frontend/src/lib/stores/tournament.svelte.ts
+  - frontend/src/lib/stores/auth.svelte.ts
+  - frontend/src/routes/login/+page.svelte
+autonomous: true
+requirements: [UI-05, UI-06]
+---
+
+## Goal
+
+SvelteKit SPA scaffold with Catppuccin Mocha dark theme, WebSocket client with reconnect, HTTP API client, authentication state, tournament state store, and PIN login page. This is the foundation that the layout shell (Plan M) and all feature views build on.
+
+## Context
+
+- **SvelteKit with adapter-static** — SPA mode, embedded in Go binary via go:embed
+- **Svelte 5 runes** — $state, $derived, $effect for all reactivity (not stores)
+- **Catppuccin Mocha** dark theme default, Latte light theme alternate
+- **Mobile-first** with responsive desktop layout (sidebar instead of bottom tabs)
+- **48px minimum touch targets** — poker room environment, TD using phone with one hand
+- See 01-RESEARCH.md: Svelte 5 Runes WebSocket State, Catppuccin Mocha Theme Setup, Pattern 3 (SvelteKit SPA)
+
+## User Decisions (from CONTEXT.md)
+
+- **Overview tab priority** — Clock > Time to break > Player count > Table balance > Financial summary > Activity feed
+- **Mobile-first bottom tab bar** — Overview, Players, Tables, Financials, More
+- **FAB for quick actions** — Bust, Buy In, Rebuy, Add-On, Pause/Resume
+- **Persistent header** showing clock, level, blinds, player count
+- **Desktop/laptop sidebar** with wider content area
+- **Catppuccin Mocha dark theme** (default), Latte light
+- **48px minimum touch targets**, press-state animations, loading states
+- **Toast notifications** (success, info, warning, error) with auto-dismiss
+- **Multi-tournament switching** — tabs at top (phone) or split view (tablet landscape)
+
+## Tasks
+
+<task id="J1" title="Initialize SvelteKit project with theme, WebSocket client, and API client">
+**1. SvelteKit Project Setup:**
+- Initialize SvelteKit project in `frontend/` directory:
+  - `npm create svelte@latest frontend -- --template skeleton`
+  - Install adapter-static: `npm install -D @sveltejs/adapter-static`
+  - Install Catppuccin: `npm install @catppuccin/palette`
+  - Configure TypeScript
+
+- `svelte.config.js`:
+  ```javascript
+  import adapter from '@sveltejs/adapter-static';
+  export default {
+      kit: {
+          adapter: adapter({
+              pages: 'build',
+              assets: 'build',
+              fallback: 'index.html', // SPA fallback
+              precompress: false,
+              strict: true
+          }),
+          paths: { base: '' }
+      }
+  };
+  ```
+
+- `frontend/src/routes/+layout.ts`:
+  ```typescript
+  export const prerender = true;
+  export const ssr = false; // SPA mode, no SSR
+  ```
+
+**2. Catppuccin Theme** (`frontend/src/lib/theme/catppuccin.css`) — UI-05:
+- Define CSS custom properties for Mocha and Latte flavors (all 26 Catppuccin colors)
+- Use `[data-theme="mocha"]` and `[data-theme="latte"]` selectors
+- Default to Mocha (dark theme)
+- Include semantic color mappings:
+  - `--color-bg`: base
+  - `--color-surface`: surface0
+  - `--color-surface-hover`: surface1
+  - `--color-text`: text
+  - `--color-text-secondary`: subtext1
+  - `--color-primary`: blue
+  - `--color-success`: green
+  - `--color-warning`: yellow
+  - `--color-error`: red
+  - `--color-accent`: mauve
+  - Poker-specific: `--color-felt`: green, `--color-card`: text, `--color-bounty`: pink, `--color-prize`: yellow
+- Typography: system-ui for body, monospace for timers/numbers
+- Base styles: body background, text color, font size, line height
+
+- `app.css`:
+  - Import catppuccin.css
+  - Reset styles (box-sizing, margin, padding)
+  - Touch action: `touch-action: manipulation` on interactive elements (prevent double-tap zoom)
+  - Minimum touch target: `.touch-target { min-height: 48px; min-width: 48px; }` — UI-06
+  - Active/pressed states: `:active { transform: scale(0.97); opacity: 0.9; }` — UI-06
+  - Focus visible styles for accessibility
+  - Scrollbar styling for dark theme
+
+**3. WebSocket Client** (`frontend/src/lib/ws.ts`):
+- `WebSocketClient` class:
+  - Connect to `ws://host/ws` (auto-detect protocol for HTTPS → WSS)
+  - Auto-reconnect with exponential backoff (1s, 2s, 4s, 8s, max 30s)
+  - Connection state tracking: connecting, connected, disconnected, reconnecting
+  - `send(message)` — JSON serialize and send
+  - `subscribe(tournamentID)` — send subscription message
+  - `onMessage(callback)` — register message handler
+  - `onStateChange(callback)` — register connection state handler
+  - Parse incoming messages: `{type: string, data: any}`
+  - Route messages to the tournament state store
+
+**4. HTTP API Client** (`frontend/src/lib/api.ts`):
+- `api` object with methods:
+  - `get(path)`, `post(path, body)`, `put(path, body)`, `delete(path)`
+  - Base URL: auto-detect from current host
+  - Automatically attach JWT from auth store as `Authorization: Bearer` header
+  - Handle 401 responses: clear auth state, redirect to login
+  - Handle errors: parse error response, throw typed errors
+  - Response parsing: auto-parse JSON
+  - Loading state tracking (for UI loading indicators)
+
+**5. Auth State** (`frontend/src/lib/stores/auth.svelte.ts`):
+- Using Svelte 5 runes:
+  ```typescript
+  class AuthState {
+      token = $state<string | null>(null);
+      operator = $state<Operator | null>(null);
+
+      get isAuthenticated() { return this.token !== null; }
+      get isAdmin() { return this.operator?.role === 'admin'; }
+      get isFloor() { return ['admin', 'floor'].includes(this.operator?.role ?? ''); }
+
+      login(token: string, operator: Operator) { ... }
+      logout() { ... }
+  }
+  export const auth = new AuthState();
+  ```
+  - Persist token to localStorage
+  - Load token from localStorage on app startup
+  - Clear on logout or 401 response
+
+**6. Tournament State** (`frontend/src/lib/stores/tournament.svelte.ts`):
+- Using Svelte 5 runes per 01-RESEARCH.md pattern:
+  ```typescript
+  class TournamentState {
+      clock = $state<ClockSnapshot | null>(null);
+      players = $state<Player[]>([]);
+      tables = $state<Table[]>([]);
+      financials = $state<FinancialSummary | null>(null);
+      activity = $state<ActivityEntry[]>([]);
+      rankings = $state<PlayerRanking[]>([]);
+      balanceStatus = $state<BalanceStatus | null>(null);
+
+      get remainingPlayers() { return this.players.filter(p => p.status === 'active').length; }
+      get isBalanced() { ... }
+
+      handleMessage(msg: WSMessage) {
+          switch (msg.type) {
+              case 'clock.tick': this.clock = msg.data; break;
+              case 'player.bust': ... break;
+              case 'state.snapshot': this.loadFullState(msg.data); break;
+              // ... all message types
+          }
+      }
+  }
+  export const tournament = new TournamentState();
+  ```
+
+**7. Login Page** (`frontend/src/routes/login/+page.svelte`):
+- PIN input with 4 large digit buttons (48px+ touch targets)
+- PIN display with dots (masked)
+- Submit button
+- Error display for wrong PIN / rate limited
+- Auto-redirect to overview on successful login
+- Catppuccin Mocha styling
+
+**8. Update Makefile:**
+- Update `make frontend` target to actually build the SvelteKit project:
+  - `cd frontend && npm install && npm run build`
+- Update `make all` to build frontend first, then Go binary
+
+**Verification:**
+- `cd frontend && npm run build` produces `frontend/build/index.html`
+- `make all` builds the full binary with embedded frontend
+- Login page renders with dark theme
+- WebSocket client connects and logs messages to console
+- API client sends requests with JWT header
+</task>
+
+## Verification Criteria
+
+1. SvelteKit builds to static SPA with `npm run build`
+2. Catppuccin Mocha dark theme applied with CSS custom properties
+3. 48px minimum touch targets defined in base styles
+4. WebSocket client connects with auto-reconnect and exponential backoff
+5. HTTP API client sends requests with JWT Authorization header
+6. Auth state persists to localStorage and clears on 401
+7. Tournament state store handles all WebSocket message types
+8. Login page works with PIN authentication
+9. `make all` builds the full binary with embedded frontend
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Catppuccin Mocha dark theme as default with semantic color variables
+- [ ] 48px minimum touch targets on all interactive elements (base CSS)
+- [ ] WebSocket client with auto-reconnect for real-time updates
+- [ ] HTTP API client with JWT auth and error handling
+- [ ] Tournament state store reactive via Svelte 5 runes
+- [ ] Auth state with localStorage persistence
+- [ ] PIN login page

.planning/phases/01-tournament-engine/01-PLAN-K.md

@@ -0,0 +1,212 @@
+# Plan K: Frontend — Overview + Clock + Financials Views
+
+---
+wave: 6
+depends_on: [01-PLAN-M, 01-PLAN-D, 01-PLAN-F, 01-PLAN-I]
+files_modified:
+  - frontend/src/routes/overview/+page.svelte
+  - frontend/src/routes/financials/+page.svelte
+  - frontend/src/lib/components/ClockDisplay.svelte
+  - frontend/src/lib/components/BlindInfo.svelte
+  - frontend/src/lib/components/ActivityFeed.svelte
+  - frontend/src/lib/components/PrizePoolCard.svelte
+  - frontend/src/lib/components/TransactionList.svelte
+  - frontend/src/lib/components/BubblePrize.svelte
+  - frontend/src/lib/components/DealFlow.svelte
+autonomous: true
+requirements: [CHIP-03, CHIP-04, MULTI-02]
+---
+
+## Goal
+
+The Overview tab shows the TD's primary workspace: a large clock display, time to next break, player counts, table balance status, financial summary, and recent activity feed. The Financials tab shows prize pool breakdown, transaction history, payout preview, bubble prize action, and chop/deal initiation. All views are reactive and update in real time via WebSocket.
+
+## Context
+
+- **Clock engine API** — Plan D (clock state, pause/resume, warnings)
+- **Financial engine API** — Plan F (prize pool, transactions, payouts, bubble prize)
+- **Tournament lifecycle API** — Plan I (tournament state, activity feed, chop/deal)
+- **UI shell** — Plan J (layout, header, FAB, toast, data table, WebSocket client)
+- **Overview tab is the TD's primary view** — most time spent here during a tournament
+
+## User Decisions (from CONTEXT.md)
+
+- **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
+  5. Financial summary (prize pool, entries, rebuys)
+  6. Recent activity feed (last few actions)
+- **Bubble prize** must be fast and prominent, "Add bubble prize" easily accessible, not buried in menus
+- **Flexible chop/deal** — ICM, custom split, partial chop, any number of players
+
+## Tasks
+
+<task id="K1" title="Implement Overview tab with clock display and activity feed">
+**1. Clock Display Component** (`frontend/src/lib/components/ClockDisplay.svelte`):
+- Large countdown timer: MM:SS format
+  - Font size: as large as possible while fitting the container
+  - Color: white text normally, transitions to `--ctp-red` in final 10 seconds
+  - Pulsing animation in final 10 seconds
+- Current level label: "Level 5" with game type if not default (e.g., "Level 5 — PLO")
+- Blinds display: "SB: 100 / BB: 200" (large, readable)
+- Ante display: "Ante: 25" (if > 0), "BB Ante: 200" (if BB ante)
+- Next level preview: smaller text showing "Next: 150/300 (20:00)" or "Next: BREAK (10:00)"
+- Chip-up indicator: if next level has chip-up, show "Chip-up: Remove 25s"
+- Break styling: when current level is a break, display "BREAK" prominently with a different background color (teal from Catppuccin)
+- Pause overlay: when paused, overlay "PAUSED" text with pulsing animation
+- Hand-for-hand indicator: when active, show "HAND FOR HAND" badge
+- No tap-to-pause on clock display (too easy to accidentally pause) — pause/resume lives exclusively in the FAB
+
+**2. Time to Break Display:**
+- Calculate time until next break level
+- Show: "Break in: 45:00" (countdown to next break)
+- If currently on break: show "Break ends in: 05:30"
+- If no upcoming break: hide
+
+**3. Player Count Card:**
+- Show: "12 / 20 remaining" (active / total entries)
+- Busted count: "8 busted"
+- Average stack: "Avg: 25,000" (CHIP-04)
+- Total chips in play: small text (CHIP-03)
+
+**4. Table Balance Status:**
+- If balanced: green indicator "Tables balanced"
+- If unbalanced: yellow/red warning "Tables unbalanced — tap to view"
+- Tap opens table balance view (navigates to Tables tab or modal)
+
+**5. Financial Summary Card:**
+- Prize pool: large number "€5,000"
+- Breakdown: entries (15), rebuys (3), add-ons (2)
+- Guarantee status: if guarantee exists and not met, show "Guarantee: €3,000 (house covers €500)"
+- Tap opens Financials tab
+
+**6. Activity Feed** (`frontend/src/lib/components/ActivityFeed.svelte`):
+- Last 10-20 actions in reverse chronological order
+- Each entry: icon + text + relative timestamp ("2m ago")
+- Entry types with icons and colors:
+  - Buy-in: green, player icon
+  - Bust: red, skull/X icon
+  - Rebuy: blue, refresh icon
+  - Level change: clock icon
+  - Break start/end: coffee/play icon
+  - Seat move: arrow icon
+  - Table break: table icon
+- Auto-updates from WebSocket (new entries slide in at top)
+- "View all" link → full audit log
+
+**7. Overview Page** (`frontend/src/routes/overview/+page.svelte`):
+- Assembles all components in the priority order from CONTEXT.md:
+  1. ClockDisplay (takes ~40% of viewport on mobile)
+  2. Time to break
+  3. Player count card
+  4. Table balance status
+  5. Financial summary card
+  6. Activity feed (scrollable, takes remaining space)
+- All data reactive from `tournament` state store
+- Skeleton loading state when tournament data is loading
+
+**Verification:**
+- Overview tab shows all priority items in correct order
+- Clock counts down in real time from WebSocket updates
+- Player count updates when players buy in or bust
+- Activity feed shows recent actions with real-time updates
+- Break styling shows distinctly when on break
+</task>
+
+<task id="K2" title="Implement Financials tab with prize pool, bubble prize, and chop/deal">
+**1. Prize Pool Card** (`frontend/src/lib/components/PrizePoolCard.svelte`):
+- Large prize pool display: "€5,000"
+- Breakdown table:
+  - Entries: count x amount = subtotal
+  - Rebuys: count x amount = subtotal
+  - Add-ons: count x amount = subtotal
+  - Re-entries: count x amount = subtotal
+  - Total contributions: sum
+  - Rake: -amount (with category breakdown on expand)
+  - Prize pool: final amount
+- Guarantee indicator if active
+- Season reserve amount if configured (FIN-12)
+
+**2. Payout Preview:**
+- Table showing payout structure for current entry count:
+  - Position | Percentage | Amount
+  - 1st | 50.0% | €2,500
+  - 2nd | 30.0% | €1,500
+  - 3rd | 20.0% | €1,000
+- Auto-selects correct bracket based on entry count
+- Updates in real time as entries change
+- Rounding denomination shown (e.g., "Rounded to nearest €5")
+
+**3. Bubble Prize** (`frontend/src/lib/components/BubblePrize.svelte`):
+- **Prominent placement** — not buried in menus (CONTEXT.md: "Add bubble prize" easily accessible)
+- Button: "Add Bubble Prize" with icon, placed prominently on Financials tab
+- Flow:
+  1. TD taps "Add Bubble Prize"
+  2. Amount input (pre-filled with buy-in amount as suggestion)
+  3. Preview: shows redistribution (original → adjusted for each position)
+  4. Confirm button
+- Visual: before/after comparison for top 3-5 prizes
+
+**4. Transaction List** (`frontend/src/lib/components/TransactionList.svelte`):
+- Uses DataTable component (Plan J)
+- Columns: Time, Player, Type, Amount, Chips, Actions
+- Filter by type (buy-in, rebuy, add-on, etc.)
+- Search by player name
+- Swipe action: Undo (with confirmation dialog)
+- Receipt view: tap a row to see receipt details
+- Reprint button on receipt view (FIN-14)
+
+**5. Chop/Deal Flow** (`frontend/src/lib/components/DealFlow.svelte`):
+- Button: "Propose Deal" (visible when 2+ players remain)
+- Step 1: Select deal type (ICM, Chip Chop, Even Chop, Custom, Partial Chop)
+- Step 2 (type-specific):
+  - ICM: input chip stacks for each remaining player → calculate
+  - Chip Chop: input chip stacks → proportional calculation
+  - Even Chop: automatic (equal split)
+  - Custom: input amount per player
+  - Partial Chop: input amount to split + amount to leave in play
+- Step 3: Review proposal showing each player's payout
+- Step 4: Confirm deal → apply payouts
+- Note: "Prize money and league positions are independent" — show info message
+
+**6. Financials Page** (`frontend/src/routes/financials/+page.svelte`):
+- Assembles:
+  1. Prize Pool Card (collapsible for detail)
+  2. Payout Preview table
+  3. Bubble Prize button (prominent)
+  4. Deal/Chop button (when applicable)
+  5. Transaction list (scrollable, filterable)
+- All reactive from tournament state
+
+**Verification:**
+- Prize pool displays correctly with breakdown
+- Payout preview matches selected bracket
+- Bubble prize flow: propose → preview redistribution → confirm
+- Transaction list with filter, search, and undo action
+- Chop/deal flow works for all types (ICM, chip chop, even, custom, partial)
+- Season reserve amount shown when configured
+</task>
+
+## Verification Criteria
+
+1. Overview tab shows all items in CONTEXT.md priority order
+2. Clock display is large, readable, and updates in real time
+3. Break and pause states display distinctly
+4. Activity feed updates in real time
+5. Prize pool breakdown is accurate and updates live
+6. Payout preview auto-selects correct bracket by entry count
+7. Bubble prize flow is fast and prominent (not buried in menus)
+8. Transaction list supports filter, search, undo, receipt view
+9. Chop/deal flow supports all types
+10. All views are reactive from WebSocket state
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Overview tab is the TD's primary workspace with clock as the biggest element
+- [ ] Activity feed shows recent actions in real time
+- [ ] Prize pool and payout preview update live as entries change
+- [ ] Bubble prize creation is fast and prominent
+- [ ] Transaction undo is accessible via swipe action
+- [ ] Chop/deal supports ICM, chip-chop, even-chop, custom, and partial

.planning/phases/01-tournament-engine/01-PLAN-L.md

@@ -0,0 +1,138 @@
+# Plan L: Frontend — Players Tab + Buy-In/Bust-Out Flows
+
+---
+wave: 6
+depends_on: [01-PLAN-M, 01-PLAN-G, 01-PLAN-I]
+files_modified:
+  - frontend/src/routes/players/+page.svelte
+  - frontend/src/lib/components/PlayerSearch.svelte
+  - frontend/src/lib/components/BuyInFlow.svelte
+  - frontend/src/lib/components/BustOutFlow.svelte
+  - frontend/src/lib/components/PlayerDetail.svelte
+autonomous: true
+requirements: [PLYR-04, PLYR-05, PLYR-07]
+---
+
+## Goal
+
+The Players tab shows all tournament players with search, buy-in flow, bust-out flow, and player detail. All flows are optimized for minimal taps — the TD is under time pressure during a running tournament.
+
+## Context
+
+- **Player management API** — Plan G (search, buy-in, bust-out, undo, rankings)
+- **Seating engine API** — Plan H (tables, auto-seat, balancing, break table)
+- **Template API** — Plan E (building blocks, templates, wizard)
+- **UI shell** — Plan J (layout, data table, FAB, toast)
+- **All flows use tap-tap pattern** — no drag-and-drop in Phase 1
+
+## User Decisions (from CONTEXT.md)
+
+- **Buy-in flow:** search/select player → auto-seat suggests optimal seat → TD can override → confirm → receipt
+- **Bust-out flow:** tap Bust → pick table → pick seat → verify name → confirm → select hitman → done
+- **Bust-out flow must be as few taps as possible**
+- **Oval table view (default)** — top-down with numbered seats, switchable to list view
+- **Balancing is TD-driven, system-assisted** — 2-tap recording (source seat, destination seat)
+- **Break Table is fully automatic**
+- **Template building blocks feel like LEGO**
+- **No drag-and-drop in Phase 1** — tap-tap for all moves
+- **Structure wizard** lives in template management
+
+## Tasks
+
+<task id="L1" title="Implement Players tab with buy-in and bust-out flows">
+**1. Player Search** (`frontend/src/lib/components/PlayerSearch.svelte`):
+- Typeahead input: as TD types, results appear below (debounced 200ms)
+- Results show: name, nickname (if set), last tournament date
+- Tap a result to select
+- "Add New Player" option at bottom if no match
+- 48px result rows for touch targets
+- Quick search: when empty, show recently active players
+
+**2. Buy-In Flow** (`frontend/src/lib/components/BuyInFlow.svelte`) — PLYR-04:
+- Step-by-step flow (each step is a single screen):
+  1. **Search/Select Player**: PlayerSearch component → select player
+  2. **Auto-Seat Preview**: system suggests table + seat → TD can accept or tap a different seat
+     - Show mini table diagram highlighting suggested seat
+     - "Override" button → shows all available seats
+  3. **Confirm**: summary card showing player name, table, seat, buy-in amount, chips
+     - Big "Confirm Buy-In" button (48px, green)
+  4. **Receipt**: brief confirmation toast + receipt data available
+- Late registration indicator: if cutoff approaching, show warning
+- Late registration override: if past cutoff, show admin override option (logged in audit)
+- Bonuses: show if early signup or punctuality bonus applies
+- Triggered from: FAB "Buy In" action, or Players tab "+" button
+
+**3. Bust-Out Flow** (`frontend/src/lib/components/BustOutFlow.svelte`) — PLYR-05:
+- Optimized for minimum taps:
+  1. **Pick Table**: grid of active tables (large tap targets), each showing table name + player count
+  2. **Pick Seat**: oval table view of selected table, tap the seat of the busted player
+  3. **Verify**: confirmation card: "Bust [Player Name]?" with player photo/avatar
+     - Big "Confirm Bust" button (48px, red)
+  4. **Select Hitman** (PKO mandatory, otherwise optional):
+     - List of active players at the same table (most likely hitman)
+     - "Other" option → search all active players
+     - "Skip" option (non-PKO only)
+  5. **Done**: toast notification "Player Name busted — 12th place"
+- Auto-ranking happens in background
+- Balance check: if tables become unbalanced, show notification
+- Triggered from: FAB "Bust" action
+
+**4. Player Detail** (`frontend/src/lib/components/PlayerDetail.svelte`) — PLYR-07:
+- Full player tracking within tournament:
+  - Current status (active/busted)
+  - Current seat (Table X, Seat Y)
+  - Chip count
+  - Playing time
+  - Buy-in time
+  - Rebuys: count and total amount
+  - Add-ons: count and total amount
+  - Bounties collected (with hitman chain details for PKO)
+  - Prize amount
+  - Points awarded
+  - Net take (prize - total investment)
+  - Action history (from audit trail): chronological list of all actions
+- Undo buttons on applicable actions (bust, rebuy, addon, buyin)
+
+**5. Players Page** (`frontend/src/routes/players/+page.svelte`):
+- Tab layout: "Active" | "Busted" | "All"
+- DataTable (from Plan J) showing:
+  - Active: Name, Table/Seat, Chips, Rebuys, Status
+  - Busted: Name, Position, Bust Time, Hitman, Prize
+  - All: Name, Status, Chips/Position, Net
+- Search bar at top (filter current list)
+- Tap row → Player Detail
+- "Buy In" button at top (alternative to FAB)
+- Swipe actions: Bust (active players), Undo Bust (busted players)
+
+**6. Rebuy/Add-On Flows:**
+- Rebuy: triggered from FAB or player detail
+  - Select player (show only eligible — active, under chip threshold, within cutoff)
+  - Confirm rebuy amount and chips
+  - Quick flow: 2 taps (select + confirm)
+- Add-On: similar quick flow
+  - Show only during addon window
+  - "Add-On All" option for break-time mass add-ons (one-by-one confirmation)
+
+**Verification:**
+- Buy-in flow: search → auto-seat → confirm → receipt in minimal taps
+- Bust-out flow: table → seat → verify → hitman → done in minimal taps
+- Player detail shows all tracking stats
+- Player list with tabs (Active/Busted/All) and search
+- Undo works from player detail
+</task>
+
+## Verification Criteria
+
+1. Buy-in flow completes in minimal taps with auto-seat
+2. Bust-out flow completes in minimal taps with hitman selection
+3. Player detail shows full per-player tracking stats (PLYR-07)
+4. Player list with Active/Busted/All tabs and search
+5. Undo works from player detail view
+6. Rebuy and add-on quick flows work from FAB and player detail
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Buy-in flow: search → auto-seat → confirm → receipt (minimal taps)
+- [ ] Bust-out flow: table → seat → verify → hitman → done (minimal taps, TD under time pressure)
+- [ ] Player detail with complete tracking data
+- [ ] All flows optimized for touch (48px targets, no drag-and-drop)

.planning/phases/01-tournament-engine/01-PLAN-M.md

@@ -0,0 +1,180 @@
+# Plan M: Layout Shell — Header, Tabs, FAB, Toast, Data Table
+
+---
+wave: 3
+depends_on: [01-PLAN-J]
+files_modified:
+  - frontend/src/routes/+layout.svelte
+  - frontend/src/lib/components/Header.svelte
+  - frontend/src/lib/components/BottomTabs.svelte
+  - frontend/src/lib/components/FAB.svelte
+  - frontend/src/lib/components/Toast.svelte
+  - frontend/src/lib/components/DataTable.svelte
+autonomous: true
+requirements: [UI-01, UI-02, UI-03, UI-04, UI-07, UI-08]
+---
+
+## Goal
+
+The layout shell wraps all page content: a persistent clock header, mobile bottom tab bar (or desktop sidebar), floating action button (FAB) for quick actions, toast notification system, and a reusable data table component. Multi-tournament tab switching when 2+ tournaments are active.
+
+## Context
+
+- **SvelteKit scaffold** — Plan J (theme, WS client, API client, auth/tournament state stores)
+- **Svelte 5 runes** for all reactivity
+- **Mobile-first** with responsive desktop layout (sidebar instead of bottom tabs)
+- **48px minimum touch targets** — poker room environment
+- See 01-RESEARCH.md: Pattern 3 (SvelteKit SPA)
+
+## User Decisions (from CONTEXT.md)
+
+- **Mobile-first bottom tab bar** — Overview, Players, Tables, Financials, More
+- **FAB for quick actions** — Bust, Buy In, Rebuy, Add-On, Pause/Resume
+- **Persistent header** showing clock, level, blinds, player count
+- **Desktop/laptop sidebar** with wider content area
+- **Toast notifications** (success, info, warning, error) with auto-dismiss
+- **Multi-tournament switching** — tabs at top (phone)
+
+## Tasks
+
+<task id="M1" title="Implement layout shell: header, bottom tabs, FAB, toast, data table">
+**1. Root Layout** (`frontend/src/routes/+layout.svelte`):
+- Auth guard: if not authenticated, redirect to /login
+- Structure:
+  ```
+  ┌─────────────────────────┐
+  │ PersistentHeader        │ ← Fixed top, always visible
+  ├─────────────────────────┤
+  │ [Tournament Tabs]       │ ← Multi-tournament selector (when 2+ active)
+  ├─────────────────────────┤
+  │                         │
+  │     <slot />            │ ← Page content (scrollable)
+  │                         │
+  ├─────────────────────────┤
+  │ BottomTabBar            │ ← Fixed bottom (mobile), Sidebar (desktop)
+  └─────────────────────────┘
+  │ FAB (floating)          │ ← Bottom-right, above tab bar
+  │ Toast (floating)        │ ← Top-right or bottom-center
+  ```
+- Responsive: detect screen width
+  - Mobile (< 768px): bottom tab bar, content full width
+  - Desktop (>= 768px): sidebar left, content fills remaining width — UI-04
+
+**2. Persistent Header** (`frontend/src/lib/components/Header.svelte`) — UI-03:
+- Fixed at top, always visible
+- Content (reactive, from tournament state):
+  - Clock: large countdown timer (MM:SS format, red text in final 10s)
+  - Current level number and name (e.g., "Level 5 — NL Hold'em")
+  - Blinds: SB/BB display (e.g., "100/200")
+  - Ante: if > 0, show ante (e.g., "Ante 25")
+  - Player count: "12/20 remaining" (active/total)
+  - Pause indicator: pulsing "PAUSED" when clock is paused
+  - Break indicator: "BREAK" with different styling when on break level
+- Compact on mobile (smaller font, abbreviated), expanded on desktop
+- Connected to tournament state store (auto-updates from WebSocket)
+
+**3. Bottom Tab Bar** (`frontend/src/lib/components/BottomTabs.svelte`) — UI-01:
+- 5 tabs: Overview, Players, Tables, Financials, More
+- Each tab: icon + label
+- Active tab highlighted with accent color
+- 48px touch targets — UI-06
+- Renders only on mobile (hidden on desktop where sidebar shows)
+- Navigation: SvelteKit goto() or <a> elements
+
+**4. Desktop Sidebar** — UI-04:
+- Same 5 navigation items as bottom tabs but in vertical sidebar
+- Wider labels, no icons-only mode
+- Active item highlighted
+- Renders only on desktop (>= 768px)
+
+**5. Floating Action Button** (`frontend/src/lib/components/FAB.svelte`) — UI-02:
+- Positioned bottom-right, above the tab bar
+- Default state: single button with "+" icon
+- Expanded state: fan out action buttons:
+  - Bust (red) — opens bust-out flow
+  - Buy In (green) — opens buy-in flow
+  - Rebuy (blue) — opens rebuy flow
+  - Add-On (yellow) — opens add-on flow
+  - Pause/Resume (orange) — toggles clock
+- Each action button: 48px, with label
+- Press-state animation (scale down on press) — UI-06
+- Context-aware: only show relevant actions (e.g., hide "Add-On" if not in addon window)
+- Close on backdrop tap or ESC
+
+**6. Toast Notifications** (`frontend/src/lib/components/Toast.svelte`) — UI-07:
+- Toast state using Svelte 5 runes:
+  ```typescript
+  class ToastState {
+      toasts = $state<Toast[]>([]);
+      success(message: string, duration?: number) { ... }
+      info(message: string, duration?: number) { ... }
+      warning(message: string, duration?: number) { ... }
+      error(message: string, duration?: number) { ... }
+      dismiss(id: string) { ... }
+  }
+  export const toast = new ToastState();
+  ```
+- Auto-dismiss: success (3s), info (4s), warning (5s), error (manual dismiss or 8s)
+- Stacking: multiple toasts stack vertically
+- Animation: slide in from right, fade out
+- Color coding: green (success), blue (info), yellow (warning), red (error) — using Catppuccin colors
+
+**7. Data Table** (`frontend/src/lib/components/DataTable.svelte`) — UI-08:
+- Props: columns config, data array, sortable flag, searchable flag
+- Features:
+  - Sort by clicking column header (asc/desc toggle)
+  - Sticky header on scroll
+  - Search/filter input (filters across all visible columns)
+  - Row click handler (for detail navigation)
+  - Mobile: swipe actions (swipe left reveals action buttons like "Bust", "Rebuy")
+  - Loading state: skeleton rows
+  - Empty state: "No data" message
+- Responsive: hide less important columns on mobile (configurable per column)
+- 48px row height for touch targets — UI-06
+
+**8. Multi-Tournament Tabs:**
+- Show tabs at top of content area when 2+ tournaments are active
+- Each tab: tournament name + status indicator
+- Tapping a tab switches the active tournament (changes which state the views render)
+- Keep both tournament states in memory (keyed by tournament ID) for fast switching — don't clear/re-fetch on tab change
+- WebSocket subscribes to all active tournaments simultaneously; messages route to the correct state by tournament ID
+- On phone: scrollable horizontal tabs
+
+**9. Loading States** — UI-06:
+- Skeleton loading component: animated placeholder matching content shape
+- Used in all data-fetching views
+- Full-page loading spinner for initial app load
+- Inline loading states for buttons (spinner replaces label during action)
+
+**Verification:**
+- App renders with Catppuccin Mocha dark theme
+- Header shows clock countdown (updates from WebSocket)
+- Bottom tabs navigate between Overview/Players/Tables/Financials/More on mobile
+- Sidebar navigation works on desktop
+- FAB expands to show action buttons
+- Toast notifications appear and auto-dismiss
+- Data table sorts, filters, and handles mobile swipe actions
+- Multi-tournament tabs appear when 2+ tournaments exist
+- All interactive elements meet 48px minimum touch target
+</task>
+
+## Verification Criteria
+
+1. Mobile-first bottom tab bar with Overview, Players, Tables, Financials, More
+2. FAB expands to show quick actions (Bust, Buy In, Rebuy, Add-On, Pause/Resume)
+3. Persistent header shows clock, level, blinds, player count — updates in real time
+4. Desktop sidebar navigation for wider screens
+5. Toast notifications work (success, info, warning, error) with auto-dismiss
+6. Data tables with sort, sticky header, search/filter, swipe actions (mobile)
+7. Multi-tournament tabs appear when 2+ tournaments active
+8. All interactive elements meet 48px minimum touch targets
+9. Loading states (skeleton, spinner) for all data-fetching views
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Mobile-first bottom tab bar with 5 navigation tabs
+- [ ] FAB with context-aware quick actions
+- [ ] Persistent header with live clock, level, blinds, player count
+- [ ] Responsive layout (bottom tabs on mobile, sidebar on desktop)
+- [ ] Data table component reusable across all views
+- [ ] Toast notification system

.planning/phases/01-tournament-engine/01-PLAN-N.md

@@ -0,0 +1,186 @@
+# Plan N: Frontend — Tables Tab + More Tab (Templates, Settings)
+
+---
+wave: 6
+depends_on: [01-PLAN-M, 01-PLAN-H, 01-PLAN-E, 01-PLAN-I]
+files_modified:
+  - frontend/src/routes/tables/+page.svelte
+  - frontend/src/routes/more/+page.svelte
+  - frontend/src/routes/more/templates/+page.svelte
+  - frontend/src/routes/more/settings/+page.svelte
+  - frontend/src/lib/components/OvalTable.svelte
+  - frontend/src/lib/components/TableListView.svelte
+  - frontend/src/lib/components/BalancingPanel.svelte
+  - frontend/src/lib/components/TemplateManager.svelte
+  - frontend/src/lib/components/BlindStructureEditor.svelte
+  - frontend/src/lib/components/StructureWizard.svelte
+autonomous: true
+requirements: [SEAT-05, SEAT-07, SEAT-08, BLIND-06]
+---
+
+## Goal
+
+The Tables tab shows oval table views (default) with seated players, list view alternative, balancing panel, and break table action. The More tab provides template management (LEGO building blocks), blind structure editor, structure wizard, venue settings, and audit log access. All interactions use tap-tap flow (no drag-and-drop in Phase 1).
+
+## Context
+
+- **Seating engine API** — Plan H (tables, auto-seat, balancing, break table)
+- **Template/building blocks API** — Plan E (CRUD, templates, wizard)
+- **Tournament lifecycle API** — Plan I (tournament state)
+- **UI shell** — Plan M (layout, data table, FAB, toast)
+- **All flows use tap-tap pattern** — no drag-and-drop in Phase 1
+
+## User Decisions (from CONTEXT.md)
+
+- **Oval table view (default)** — top-down with numbered seats, switchable to list view
+- **Balancing is TD-driven, system-assisted** — 2-tap recording (source seat, destination seat)
+- **Break Table is fully automatic**
+- **Template building blocks feel like LEGO**
+- **No drag-and-drop in Phase 1** — tap-tap for all moves
+- **Structure wizard** lives in template management
+
+## Tasks
+
+<task id="N1" title="Implement Tables tab with oval view and balancing panel">
+**1. Oval Table View** (`frontend/src/lib/components/OvalTable.svelte`) — SEAT-08:
+- SVG-based top-down oval table:
+  - Oval shape with seat positions around the edge
+  - Each seat: numbered circle (48px touch target)
+  - Occupied seats: show player name (truncated if needed)
+  - Empty seats: show seat number only (lighter color)
+  - Dealer button indicator on the button seat
+  - Active/selected seat highlighted
+- Responsive: scales to container width
+- Tap seat → select for move/bust/details
+- Support 6-max through 10-max configurations
+
+**2. Table List View** (`frontend/src/lib/components/TableListView.svelte`) — SEAT-08:
+- Alternative to oval view for density (10+ table tournaments)
+- DataTable format: Table Name | Players | Seats | Balance
+- Expand row → show seated players list
+- Toggle between Oval and List view
+
+**3. Balancing Panel** (`frontend/src/lib/components/BalancingPanel.svelte`) — SEAT-05:
+- Shown when tables are unbalanced (yellow/red indicator)
+- "Suggest Moves" button → shows system-generated suggestions
+- Each suggestion: "Move 1 player from Table 1 (8 players) to Table 4 (6 players)"
+- Accept flow (2 taps):
+  1. Tap source seat on source table (who is moving)
+  2. Tap destination seat on destination table (where they're going)
+  3. System confirms and executes
+- Cancel suggestion button
+- Status: "Live" indicator showing suggestion is current (adaptive)
+- If suggestion becomes stale (state changed), auto-cancel and show updated suggestion
+
+**4. Tables Page** (`frontend/src/routes/tables/+page.svelte`):
+- Grid of oval tables (2 per row on phone, more on tablet/desktop)
+- View toggle: Oval / List
+- Balance status banner at top (if unbalanced)
+- Balancing panel (expandable)
+- Actions per table:
+  - "Break Table" button (with confirmation: "Distribute N players to remaining tables?")
+  - "Add Table" button
+- Seat move: tap source seat, tap destination seat (different table) → confirm move
+- Hand-for-hand toggle (when near bubble)
+
+**Verification:**
+- Oval table view renders with correct seat positions and player names
+- Tap-tap seat move works across tables
+- Balancing panel shows suggestions and executes moves
+- Break Table dissolves table and shows redistribution result
+</task>
+
+<task id="N2" title="Implement More tab with template management, structure wizard, settings">
+**1. More Page** (`frontend/src/routes/more/+page.svelte`):
+- Navigation list to sub-pages:
+  - Tournament Templates
+  - Blind Structures
+  - Chip Sets
+  - Payout Structures
+  - Buy-in Configs
+  - Venue Settings
+  - Operators (admin only)
+  - Audit Log
+  - About / Version
+
+**2. Template Manager** (`frontend/src/routes/more/templates/+page.svelte` and components):
+
+**Template List:**
+- DataTable: Name, Type (Turbo/Standard/etc.), Built-in badge
+- Actions: Edit, Duplicate, Delete (not for built-in)
+- "Create Template" button
+
+**Template Editor** (`frontend/src/lib/components/TemplateManager.svelte`):
+- LEGO-style composition:
+  1. Name and description
+  2. Chip Set: dropdown selector (preview denominations below)
+  3. Blind Structure: dropdown selector (preview level summary below)
+  4. Payout Structure: dropdown selector (preview brackets below)
+  5. Buy-in Config: dropdown selector (preview amounts below)
+  6. Points Formula: dropdown selector (optional)
+  7. Tournament options: min/max players, PKO, bonuses
+- Each dropdown: show current selection with summary, tap to change
+- "Create New" option in each dropdown → navigate to that building block's editor
+
+**3. Blind Structure Editor** (`frontend/src/lib/components/BlindStructureEditor.svelte`):
+- List of levels with all fields per row (BLIND-01):
+  - Position, Type (round/break), Game Type, SB, BB, Ante, BB Ante, Duration, Chip-up, Notes
+- Add level button (appends)
+- Delete level button (per row)
+- Reorder (move up/down buttons — no drag, Phase 1)
+- Auto-numbering (positions auto-increment)
+- Mixed game support: game type dropdown per level (BLIND-03)
+
+**4. Structure Wizard** (`frontend/src/lib/components/StructureWizard.svelte`) — BLIND-06:
+- Inputs:
+  - Player count (slider or number input, 8-200)
+  - Starting chips (number input, common presets: 10K, 15K, 25K, 50K)
+  - Target duration (slider: 1-8 hours)
+  - Chip set (dropdown — for denomination alignment)
+- "Generate" button → calls wizard API
+- Preview: generated level list (editable before saving)
+- "Save as Structure" button → creates new blind structure
+- "Use in Template" button → pre-selects in template editor
+
+**5. Settings Page** (`frontend/src/routes/more/settings/+page.svelte`):
+- Venue name
+- Currency (code + symbol)
+- Rounding denomination
+- Receipt mode (off / digital / print / both)
+- Theme toggle (Mocha / Latte)
+- Operator management (admin only): list operators, change PINs, change roles
+
+**6. Audit Log Page:**
+- DataTable with audit entries
+- Filters: by action type, by tournament, by operator, date range
+- Entry detail: full previous/new state JSON
+- Linked to undo: "Undo this action" button where applicable
+
+**Verification:**
+- Template editor composes building blocks LEGO-style
+- Blind structure editor supports all level fields
+- Structure wizard generates and previews a blind structure
+- Settings page saves venue configuration
+- Audit log shows filterable action history
+</task>
+
+## Verification Criteria
+
+1. Oval table view renders correctly for 6-10 max configurations
+2. Tap-tap seat moves work between tables
+3. Balancing panel shows adaptive suggestions and executes with 2 taps
+4. Break Table distributes players and shows result
+5. Template editor composes building blocks like LEGO
+6. Blind structure editor supports all fields including BB Ante and mixed game
+7. Structure wizard generates playable structures
+8. Settings page saves venue configuration
+9. Audit log shows filterable action history with undo capability
+
+## Must-Haves (Goal-Backward)
+
+- [ ] Oval table view with numbered seats and player names
+- [ ] 2-tap seat recording for balancing (source seat, destination seat)
+- [ ] Break Table shows redistribution result
+- [ ] Template management with LEGO-style building block composition
+- [ ] Structure wizard lives in template management
+- [ ] All interactions use tap-tap flow (no drag-and-drop)

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

@@ -0,0 +1,903 @@
+# Phase 1: Tournament Engine - Research
+
+**Researched:** 2026-03-01
+**Domain:** Full-stack tournament management — Go backend (LibSQL, NATS JetStream, WebSocket), SvelteKit frontend (embedded via go:embed), poker domain logic (clock, blinds, financials, seating, ICM)
+**Confidence:** HIGH (core stack verified via official sources and docs)
+
+## Summary
+
+Phase 1 is a greenfield full-stack build: a single Go binary embedding LibSQL (local SQLite fork), NATS JetStream (event durability), and a WebSocket hub, serving a SvelteKit SPA via `go:embed`. The binary runs in an x86 LXC container and provides a touch-friendly Tournament Director (TD) UI for managing a complete poker tournament lifecycle.
+
+The Go backend stack is well-established. LibSQL provides a local-first SQLite-compatible database via `go-libsql` (CGO required, no tagged releases — pin to commit hash). NATS server embeds programmatically with JetStream enabled for append-only event durability (`sync_interval: always` is mandatory for single-node per the December 2025 Jepsen finding). The WebSocket hub uses `coder/websocket` (v1.8.14, formerly nhooyr.io/websocket) for idiomatic Go context support. HTTP routing uses `go-chi/chi` v5 for its lightweight middleware composition. Authentication is bcrypt-hashed PINs producing local JWTs via `golang-jwt/jwt` v5.
+
+The SvelteKit frontend uses Svelte 5 with runes (the new reactivity model replacing stores) and `adapter-static` to prerender a SPA embedded in the Go binary. Catppuccin Mocha provides the dark theme via CSS custom properties from `@catppuccin/palette`. The operator UI follows a mobile-first bottom-tab layout with FAB quick actions, persistent clock header, and 48px touch targets.
+
+The poker domain has several non-trivial algorithmic areas: ICM calculation (factorial complexity, needs Monte Carlo approximation beyond ~15 players), blind structure wizard (backward calculation from target duration to level progression), table balancing (TDA-compliant seat assignment with blind position awareness), and PKO bounty chain tracking (half bounty to hitman, half added to own bounty).
+
+**Primary recommendation:** Build as a monolithic Go binary with clean internal package boundaries (clock, financial, seating, player, audit). Use event-sourced state changes written to both NATS JetStream (for real-time broadcast) and LibSQL (for persistence and query). All financial math uses int64 cents with a CI gate test proving zero-deviation payout sums.
+
+<user_constraints>
+
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+- **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, Blind structure, Payout structure, Buy-in config, Points formula (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
+- **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)
+- **Structure wizard** lives in template management — input player count, starting chips, duration, denominations -> generates a blind structure
+- **Minimum player threshold** — configured in tournament metadata, Start button unavailable until met
+- **Chip bonuses** — configurable per tournament: early signup bonus, punctuality bonus
+- **Late registration soft lock with admin override** — when cutoff hits, registration locks but admin can push through (logged in audit trail)
+- **Payout structure as standalone reusable building block** — entry-count brackets with tiered prizes
+- **Entry count = unique entries only** — not rebuys or add-ons
+- **Prize rounding** — round down to nearest venue-configured denomination (e.g. 50 DKK, EUR 5)
+- **Bubble prize** — fast and prominent, "Add bubble prize" easily accessible, funded by shaving top prizes
+- **Overview tab priority** — Clock > Time to break > Player count > Table balance > Financial summary > Activity feed
+- **Bust-out flow** — tap Bust -> pick table -> pick seat -> verify name -> confirm -> select hitman -> done
+- **PKO (Progressive Knockout)** — bounty transfer part of bust flow (half to hitman, half added to own bounty)
+- **Buy-in flow** — search/select player -> auto-seat -> TD override option -> confirm -> receipt
+- **Multi-tournament switching** — tabs at top (phone) or split view (tablet landscape)
+- **Undo is critical** — bust-outs, rebuys, add-ons, buy-ins can all be undone with full re-ranking
+- **Oval table view (default)** — top-down view with numbered seats, switchable to list view
+- **Balancing is TD-driven, system-assisted** — system alerts, TD requests suggestion, TD announces, assistant reports, two-tap recording
+- **Break Table is fully automatic** — system distributes evenly, TD sees result
+- **No drag-and-drop in Phase 1** — tap-tap flow for all moves
+- **Flexible chop/deal support** — ICM, custom split, partial chop, any number of players
+- **Prize money and league positions are independent**
+- **Tournament auto-closes** when one player remains
+- **Receipts configurable per venue** — off / digital / print / both
+- **Operator is the Tournament Director (TD)** — use this term consistently
+
+### 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
+
+### Deferred Ideas (OUT OF SCOPE)
+
+- **Drag-and-drop seat moves** — future Phase 1 enhancement or later
+- **PWA seat move notifications** — Phase 2
+- **"Keep apart" player marking** — evaluate for Phase 1 or later
+- **Chip bonus for early signup/punctuality** — captured in decisions, evaluate complexity during planning
+
+</user_constraints>
+
+<phase_requirements>
+
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| ARCH-01 | Single Go binary on x86 LXC with embedded LibSQL, NATS JetStream, WebSocket hub | go-libsql local-only mode (`sql.Open("libsql", "file:"+path)`), embedded nats-server with JetStream, coder/websocket hub pattern |
+| ARCH-03 | All financial values stored as int64 cents — never float64 | Standard Go int64 arithmetic, CI gate test pattern documented |
+| ARCH-04 | NATS JetStream embedded with `sync_interval: always` for durability | Jepsen 2.12.1 finding confirms mandatory for single-node; embedded server opts `JetStream: true` + sync config |
+| ARCH-05 | WebSocket hub broadcasts within 100ms | coder/websocket concurrent writes, custom hub with connection registry pattern |
+| ARCH-06 | SvelteKit frontend via `//go:embed` | adapter-static + `//go:embed all:build` + SPA fallback handler pattern |
+| ARCH-07 | Leaf is sovereign — cloud never required | Local LibSQL file, embedded NATS, all logic in Go binary |
+| ARCH-08 | Append-only audit trail for every state-changing action | Event-sourced audit table in LibSQL + NATS JetStream publish for real-time |
+| AUTH-01 | Operator PIN login -> local JWT (bcrypt in LibSQL) | golang-jwt/jwt v5 + golang.org/x/crypto/bcrypt, offline-capable |
+| AUTH-03 | Operator roles: Admin, Floor, Viewer | JWT claims with role field, middleware enforcement on chi routes |
+| CLOCK-01 | Countdown timer per level, second-granularity display, ms-precision internal | Go time.Ticker + monotonic clock, server-authoritative time |
+| CLOCK-02 | Separate break durations with distinct visual treatment | Level type enum (round/break), frontend conditional styling |
+| CLOCK-03 | Pause/resume with visual indicator across all displays | Clock state machine (running/paused/stopped), WebSocket broadcast |
+| CLOCK-04 | Manual advance forward/backward between levels | Clock engine level index navigation |
+| CLOCK-05 | Jump to any level by number | Direct level index set on clock engine |
+| CLOCK-06 | Total elapsed time display | Tracked from tournament start, pauses excluded |
+| CLOCK-07 | Configurable warning thresholds with audio/visual | Threshold config per level, play_sound action on WebSocket, CSS animation triggers |
+| CLOCK-08 | Clock state authoritative on Leaf; 1/sec normal, 10/sec final 10s | Server-side tick emitter with dynamic interval |
+| CLOCK-09 | Reconnecting clients receive full clock state | WebSocket connection handler sends current snapshot on connect |
+| BLIND-01 | Unlimited configurable levels (round/break, game type, SB/BB, ante, duration, chip-up, notes) | Level struct with all fields, array in blind structure entity |
+| BLIND-02 | Big Blind Ante support alongside standard ante | Separate ante and bb_ante fields per level |
+| BLIND-03 | Mixed game rotation (HORSE, 8-Game) | Game type per level, rotation sequence in structure |
+| BLIND-04 | Save/load reusable blind structure templates | Template CRUD in LibSQL, building block pattern |
+| BLIND-05 | Built-in templates (Turbo, Standard, Deep Stack, WSOP-style) | Seed data on first boot |
+| BLIND-06 | Structure wizard | Algorithm: target duration -> final BB -> geometric curve -> nearest chip denominations |
+| CHIP-01 | Define denominations with colors (hex) and values | Chip set entity (venue-level building block) |
+| CHIP-02 | Chip-up tracking per break | Level flag + chip-up denomination reference |
+| CHIP-03 | Total chips in play calculation | Sum of (active players * starting chips) + rebuys + add-ons |
+| CHIP-04 | Average stack display | Total chips / remaining players |
+| FIN-01 | Buy-in configuration (amount, chips, rake, bounty, points) | Buy-in config entity as building block, int64 cents |
+| FIN-02 | Multiple rake categories (staff, league, house) | Rake split array in buy-in config |
+| FIN-03 | Late registration cutoff (by level, by time, or both) | Cutoff config with dual-condition logic |
+| FIN-04 | Re-entry support (distinct from rebuy) | Separate transaction type, new entry after bust |
+| FIN-05 | Rebuy configuration (cost, chips, rake, points, limits, cutoff, chip threshold) | Rebuy config entity with all parameters |
+| FIN-06 | Add-on configuration (cost, chips, rake, points, window) | Add-on config entity |
+| FIN-07 | Fixed bounty system (cost, chip, hitman tracking, chain tracking, cash-out) | PKO bounty entity per player, half-split on elimination, chain tracked in audit trail |
+| FIN-08 | Prize pool auto-calculation | Sum of all entries * entry amount - total rake, int64 cents |
+| FIN-09 | Guaranteed pot support (house covers shortfall) | Guarantee config field, shortfall = guarantee - actual pool |
+| FIN-10 | Payout structures (percentage, fixed, custom) with rounding | Payout building block, round-down to venue denomination, bracket selection by entry count |
+| FIN-11 | Chop/deal support (ICM, chip-chop, even-chop, custom) | ICM: Malmuth-Harville algorithm (Monte Carlo for >15 players), custom split UI |
+| FIN-12 | End-of-season withholding | Rake category marked as season reserve |
+| FIN-13 | Every financial action generates receipt | Transaction log with receipt rendering |
+| FIN-14 | Transaction editing with audit trail and receipt reprint | Undo/edit creates new audit entry referencing original |
+| PLYR-01 | Player database persistent on Leaf (LibSQL) | LibSQL local file, player table with UUID PK |
+| PLYR-02 | Search with typeahead, merge duplicates, import CSV | FTS5 (SQLite full-text search) for typeahead, merge logic, CSV import endpoint |
+| PLYR-03 | QR code generation per player | Go QR library (e.g. skip2/go-qrcode), encodes player UUID |
+| PLYR-04 | Buy-in flow (search -> confirm -> auto-seat -> receipt -> display update) | Multi-step transaction: financial entry + seat assignment + WebSocket broadcast |
+| PLYR-05 | Bust-out flow (select -> hitman -> bounty -> rank -> rebalance -> display) | Multi-step: bust record + bounty transfer + re-rank + balance check + broadcast |
+| PLYR-06 | Undo for bust-out, rebuy, add-on, buy-in with re-ranking | Reverse transaction in audit trail, recalculate rankings and balances |
+| PLYR-07 | Per-player tracking (chips, time, seat, moves, rebuys, add-ons, bounties, prize, points, net, history) | Computed from transaction log and current state |
+| SEAT-01 | Tables with configurable seat counts (6-max to 10-max) | Table entity with seat_count, name/label |
+| SEAT-02 | Table blueprints (save venue layout) | Blueprint entity as venue-level template |
+| SEAT-03 | Dealer button tracking | Button position field per table, advanced on bust/balance |
+| SEAT-04 | Random initial seating on buy-in (fills evenly) | Random seat assignment algorithm: find table with fewest players, random empty seat |
+| SEAT-05 | Auto balancing suggestions with operator confirmation | TDA-compliant algorithm: size difference threshold, move fairness, button awareness, dry-run preview |
+| SEAT-06 | Drag-and-drop manual moves on touch interface | DEFERRED in Phase 1 — tap-tap flow instead |
+| SEAT-07 | Break Table action (dissolve and distribute) | Distribute players from broken table to remaining tables evenly, respecting blind position |
+| SEAT-08 | Visual top-down table layout, list view, movement screen | Oval SVG table component, list view alternative, move confirmation screen |
+| SEAT-09 | Hand-for-hand mode | Clock pause + per-hand level decrement mode |
+| MULTI-01 | Multiple simultaneous tournaments with independent state | Tournament-scoped state (clock, financials, players all keyed by tournament ID) |
+| MULTI-02 | Tournament lobby view | List of active tournaments with status summary |
+| UI-01 | Mobile-first bottom tab bar (Overview, Players, Tables, Financials, More) | SvelteKit layout with bottom nav component |
+| UI-02 | FAB for quick actions (Bust, Buy In, Rebuy, Add-On, Pause/Resume) | Expandable FAB component with context-aware actions |
+| UI-03 | Persistent header (clock, level, blinds, player count) | Fixed header component subscribing to clock WebSocket |
+| UI-04 | Desktop/laptop sidebar navigation | Responsive layout: bottom tabs on mobile, sidebar on desktop |
+| UI-05 | Catppuccin Mocha dark theme (default), Latte light theme | @catppuccin/palette CSS custom properties, theme toggle |
+| UI-06 | 48px minimum touch targets, press-state animations, loading states | CSS touch-action, :active states, skeleton loading |
+| UI-07 | Toast notifications (success, info, warning, error) | Svelte toast store/rune with auto-dismiss timer |
+| UI-08 | Data tables with sort, sticky header, search/filter, swipe actions | Custom table component or thin wrapper, virtual scroll for large lists |
+
+</phase_requirements>
+
+## Standard Stack
+
+### Core
+
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Go | 1.23+ | Backend language | Current stable, required for latest stdlib features |
+| github.com/tursodatabase/go-libsql | commit pin (no tags) | Embedded LibSQL database | SQLite-compatible, local-first, CGO required, `sql.Open("libsql", "file:"+path)` |
+| github.com/nats-io/nats-server/v2 | v2.12.4 | Embedded NATS server with JetStream | Event durability, append-only streams, embedded in Go process |
+| github.com/nats-io/nats.go | latest (v1.49+) | NATS Go client + jetstream package | New JetStream API (replaces legacy JetStreamContext) |
+| github.com/coder/websocket | v1.8.14 | WebSocket server | Minimal, idiomatic, context.Context support, concurrent writes, zero deps |
+| github.com/go-chi/chi/v5 | v5.2.5 | HTTP router | Lightweight, stdlib-compatible middleware, route grouping |
+| github.com/golang-jwt/jwt/v5 | v5.x (latest) | JWT tokens | Standard Go JWT library, 13K+ importers, HS256 signing |
+| golang.org/x/crypto | latest | bcrypt for PIN hashing | Standard library extension, production-grade bcrypt |
+| Svelte | 5.46+ | Frontend framework | Runes reactivity model, compiled output, small bundle |
+| SvelteKit | 2.x | Frontend framework/router | adapter-static for SPA, file-based routing, SSR-capable |
+| @sveltejs/adapter-static | latest | SPA build adapter | Prerenders all pages to static HTML for go:embed |
+| @catppuccin/palette | latest | Theme colors | Official Catppuccin color palette as CSS/JS, Mocha + Latte flavors |
+
+### Supporting
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| github.com/skip2/go-qrcode | latest | QR code generation | PLYR-03: Player QR codes for self-check-in |
+| github.com/google/uuid | latest | UUID generation | Player IDs, tournament IDs, all entity PKs |
+| FTS5 (built into LibSQL/SQLite) | N/A | Full-text search | PLYR-02: Typeahead player search |
+| @catppuccin/tailwindcss | latest | Tailwind theme plugin | Only if using Tailwind; otherwise use raw CSS vars from @catppuccin/palette |
+
+### Alternatives Considered
+
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| go-chi/chi v5 | Go 1.22+ stdlib ServeMux | Go 1.22 added method+path matching but chi has better middleware composition, route grouping, and ecosystem |
+| coder/websocket | gorilla/websocket | gorilla is more battle-tested (6+ years) but coder/websocket is more idiomatic (context support, concurrent writes) and actively maintained by Coder |
+| go-libsql | mattn/go-sqlite3 | go-sqlite3 is more mature with tagged releases but doesn't support libSQL extensions and eventual Turso sync in Phase 3 |
+| SvelteKit adapter-static | Vite vanilla SPA | SvelteKit provides file-based routing, layouts, and SSR-capability for Phase 2+ |
+
+**Installation (Go):**
+```bash
+# go.mod — pin go-libsql to specific commit
+go get github.com/tursodatabase/go-libsql@<commit-hash>
+go get github.com/nats-io/nats-server/v2@v2.12.4
+go get github.com/nats-io/nats.go@latest
+go get github.com/coder/websocket@v1.8.14
+go get github.com/go-chi/chi/v5@v5.2.5
+go get github.com/golang-jwt/jwt/v5@latest
+go get golang.org/x/crypto@latest
+go get github.com/skip2/go-qrcode@latest
+go get github.com/google/uuid@latest
+```
+
+**Installation (Frontend):**
+```bash
+npm create svelte@latest frontend -- --template skeleton
+cd frontend
+npm install @catppuccin/palette
+npm install -D @sveltejs/adapter-static
+```
+
+## Architecture Patterns
+
+### Recommended Project Structure
+
+```
+felt/
+├── cmd/
+│   └── leaf/
+│       └── main.go              # Entry point: starts NATS, LibSQL, HTTP server
+├── internal/
+│   ├── server/
+│   │   ├── server.go            # HTTP server setup, chi router, middleware
+│   │   ├── ws/
+│   │   │   └── hub.go           # WebSocket hub: connection registry, broadcast
+│   │   └── middleware/
+│   │       ├── auth.go          # JWT validation middleware
+│   │       └── role.go          # Role-based access control
+│   ├── auth/
+│   │   ├── pin.go               # PIN login, bcrypt verify, JWT issue
+│   │   └── jwt.go               # Token creation, validation, claims
+│   ├── clock/
+│   │   ├── engine.go            # Clock state machine (running/paused/stopped)
+│   │   ├── ticker.go            # Server-side tick emitter (1/sec, 10/sec final 10s)
+│   │   └── warnings.go          # Threshold detection and alert emission
+│   ├── tournament/
+│   │   ├── tournament.go        # Tournament lifecycle (create, start, close)
+│   │   ├── state.go             # Tournament state aggregation
+│   │   └── multi.go             # Multi-tournament management
+│   ├── financial/
+│   │   ├── engine.go            # Buy-in, rebuy, add-on, bounty transactions
+│   │   ├── payout.go            # Prize pool calculation, payout distribution
+│   │   ├── icm.go               # ICM calculator (Malmuth-Harville + Monte Carlo)
+│   │   ├── chop.go              # Deal/chop flows (ICM, chip-chop, custom)
+│   │   └── receipt.go           # Receipt generation
+│   ├── player/
+│   │   ├── player.go            # Player CRUD, search, merge
+│   │   ├── ranking.go           # Live rankings, re-ranking on undo
+│   │   └── qrcode.go            # QR code generation
+│   ├── seating/
+│   │   ├── table.go             # Table management, seat assignment
+│   │   ├── balance.go           # Table balancing algorithm
+│   │   ├── breaktable.go        # Table break and redistribute
+│   │   └── blueprint.go         # Venue layout blueprints
+│   ├── blind/
+│   │   ├── structure.go         # Blind structure definition and CRUD
+│   │   ├── wizard.go            # Structure wizard algorithm
+│   │   └── templates.go         # Built-in template seed data
+│   ├── template/
+│   │   ├── tournament.go        # Tournament template (composition of blocks)
+│   │   ├── chipset.go           # Chip set building block
+│   │   ├── payout.go            # Payout structure building block
+│   │   └── buyin.go             # Buy-in config building block
+│   ├── audit/
+│   │   ├── trail.go             # Append-only audit log
+│   │   └── undo.go              # Undo engine (reverse operations)
+│   ├── nats/
+│   │   ├── embedded.go          # Embedded NATS server startup
+│   │   └── publisher.go         # Event publishing to JetStream
+│   └── store/
+│       ├── db.go                # LibSQL connection setup
+│       ├── migrations/          # SQL migration files
+│       └── queries/             # SQL query files (or generated)
+├── frontend/
+│   ├── src/
+│   │   ├── lib/
+│   │   │   ├── ws.ts            # WebSocket client with reconnect
+│   │   │   ├── api.ts           # HTTP API client
+│   │   │   ├── stores/          # Svelte 5 runes-based state
+│   │   │   ├── components/      # Reusable UI components
+│   │   │   └── theme/           # Catppuccin theme setup
+│   │   ├── routes/
+│   │   │   ├── +layout.svelte   # Root layout (header, tabs, FAB)
+│   │   │   ├── overview/        # Overview tab
+│   │   │   ├── players/         # Players tab
+│   │   │   ├── tables/          # Tables tab
+│   │   │   ├── financials/      # Financials tab
+│   │   │   └── more/            # More tab (templates, settings)
+│   │   └── app.html
+│   ├── static/
+│   │   └── sounds/              # Level change, break, bubble sounds
+│   ├── svelte.config.js
+│   ├── embed.go                 # //go:embed all:build
+│   └── package.json
+└── go.mod
+```
+
+### Pattern 1: Embedded NATS Server with JetStream
+
+**What:** Start NATS server in-process with JetStream enabled and `sync_interval: always` for single-node durability.
+**When to use:** Application startup in `cmd/leaf/main.go`.
+
+```go
+// Source: https://github.com/nats-io/nats-server/discussions/6242
+import (
+    "github.com/nats-io/nats-server/v2/server"
+    "github.com/nats-io/nats.go"
+)
+
+func startEmbeddedNATS(dataDir string) (*server.Server, error) {
+    opts := &server.Options{
+        DontListen: true,  // In-process only, no TCP listener needed
+        JetStream:  true,
+        StoreDir:   dataDir,
+        JetStreamMaxMemory:  64 * 1024 * 1024,  // 64MB memory limit
+        JetStreamMaxStore:   1024 * 1024 * 1024, // 1GB disk limit
+        JetStreamSyncInterval: 0, // 0 = "always" — fsync every write
+    }
+
+    ns, err := server.NewServer(opts)
+    if err != nil {
+        return nil, fmt.Errorf("failed to create NATS server: %w", err)
+    }
+
+    go ns.Start()
+
+    if !ns.ReadyForConnections(5 * time.Second) {
+        return nil, errors.New("NATS server startup timeout")
+    }
+
+    return ns, nil
+}
+```
+
+**CRITICAL:** `sync_interval: always` (or `JetStreamSyncInterval: 0`) is mandatory. The Jepsen December 2025 analysis of NATS 2.12.1 found that the default 2-minute fsync interval means recently acknowledged writes exist only in memory and are lost on power failure. For single-node (non-replicated) deployments, every write must fsync immediately.
+
+### Pattern 2: WebSocket Hub with Connection Registry
+
+**What:** Central hub managing all WebSocket connections with topic-based broadcasting.
+**When to use:** Real-time state updates to all connected operator/display clients.
+
+```go
+// Source: coder/websocket docs + standard hub pattern
+import "github.com/coder/websocket"
+
+type Hub struct {
+    mu      sync.RWMutex
+    clients map[*Client]struct{}
+}
+
+type Client struct {
+    conn         *websocket.Conn
+    tournamentID string // Subscribe to specific tournament
+    send         chan []byte
+}
+
+func (h *Hub) Broadcast(tournamentID string, msg []byte) {
+    h.mu.RLock()
+    defer h.mu.RUnlock()
+    for client := range h.clients {
+        if client.tournamentID == tournamentID || client.tournamentID == "" {
+            select {
+            case client.send <- msg:
+            default:
+                // Client too slow, drop message
+            }
+        }
+    }
+}
+
+// On new WebSocket connection — send full state snapshot
+func (h *Hub) HandleConnect(w http.ResponseWriter, r *http.Request) {
+    c, err := websocket.Accept(w, r, nil)
+    if err != nil { return }
+
+    client := &Client{conn: c, send: make(chan []byte, 256)}
+    h.register(client)
+    defer h.unregister(client)
+
+    // Send full state snapshot on connect (CLOCK-09)
+    snapshot := h.getCurrentState(client.tournamentID)
+    client.send <- snapshot
+
+    // Read/write pumps...
+}
+```
+
+### Pattern 3: SvelteKit SPA Embedded in Go Binary
+
+**What:** Build SvelteKit with adapter-static, embed the output, serve with SPA fallback.
+**When to use:** Serving the frontend from the Go binary.
+
+```javascript
+// svelte.config.js
+import adapter from '@sveltejs/adapter-static';
+
+export default {
+    kit: {
+        adapter: adapter({
+            pages: 'build',
+            assets: 'build',
+            fallback: 'index.html', // SPA fallback
+            precompress: false,
+            strict: true
+        }),
+        paths: {
+            base: ''  // Served from root
+        }
+    }
+};
+```
+
+```go
+// frontend/embed.go
+package frontend
+
+import (
+    "embed"
+    "io/fs"
+    "net/http"
+    "strings"
+)
+
+//go:embed all:build
+var files embed.FS
+
+func Handler() http.Handler {
+    fsys, _ := fs.Sub(files, "build")
+    fileServer := http.FileServer(http.FS(fsys))
+
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        // Try to serve static file first
+        path := strings.TrimPrefix(r.URL.Path, "/")
+        if path == "" {
+            path = "index.html"
+        }
+        if _, err := fs.Stat(fsys, path); err != nil {
+            // SPA fallback: serve index.html for client-side routing
+            r.URL.Path = "/"
+        }
+        fileServer.ServeHTTP(w, r)
+    })
+}
+```
+
+### Pattern 4: Event-Sourced Audit Trail
+
+**What:** Every state-changing action writes an immutable audit entry to both LibSQL and NATS JetStream.
+**When to use:** All mutations (buy-in, bust-out, rebuy, clock pause, seat move, etc.).
+
+```go
+type AuditEntry struct {
+    ID            string    `json:"id"`         // UUID
+    TournamentID  string    `json:"tournament_id"`
+    Timestamp     int64     `json:"timestamp"`  // UnixNano
+    OperatorID    string    `json:"operator_id"`
+    Action        string    `json:"action"`     // "player.bust", "financial.buyin", etc.
+    TargetID      string    `json:"target_id"`  // Player/table/etc ID
+    PreviousState json.RawMessage `json:"previous_state"`
+    NewState      json.RawMessage `json:"new_state"`
+    Metadata      json.RawMessage `json:"metadata,omitempty"`
+    UndoneBy      *string   `json:"undone_by,omitempty"` // Points to undo entry
+}
+
+// Write to both LibSQL (persistence) and NATS JetStream (real-time broadcast)
+func (a *AuditTrail) Record(ctx context.Context, entry AuditEntry) error {
+    // 1. Insert into LibSQL audit table
+    if err := a.store.InsertAudit(ctx, entry); err != nil {
+        return err
+    }
+    // 2. Publish to NATS JetStream for real-time broadcast
+    data, _ := json.Marshal(entry)
+    _, err := a.js.Publish(ctx,
+        fmt.Sprintf("tournament.%s.audit", entry.TournamentID),
+        data,
+    )
+    return err
+}
+```
+
+### Pattern 5: Int64 Financial Math
+
+**What:** All monetary values stored and calculated as int64 cents. Never float64.
+**When to use:** Every financial calculation (prize pool, payouts, rake, bounties).
+
+```go
+// All money is int64 cents. 1000 = $10.00 or 10.00 EUR or 1000 DKK (10 kr)
+type Money int64
+
+func (m Money) String() string {
+    return fmt.Sprintf("%d.%02d", m/100, m%100)
+}
+
+// Prize pool: sum of all entry fees minus rake
+func CalculatePrizePool(entries []Transaction) Money {
+    var pool Money
+    for _, e := range entries {
+        pool += e.PrizeContribution // Already int64 cents
+    }
+    return pool
+}
+
+// Payout with round-down to venue denomination
+func CalculatePayouts(pool Money, structure []PayoutTier, roundTo Money) []Money {
+    payouts := make([]Money, len(structure))
+    var distributed Money
+    for i, tier := range structure {
+        raw := Money(int64(pool) * int64(tier.BasisPoints) / 10000)
+        payouts[i] = (raw / roundTo) * roundTo // Round down
+        distributed += payouts[i]
+    }
+    // Remainder goes to 1st place (standard poker convention)
+    payouts[0] += pool - distributed
+    return payouts
+}
+
+// CI GATE TEST: sum of payouts must exactly equal prize pool
+func TestPayoutSumEqualsPool(t *testing.T) {
+    // ... property-based test across thousands of random inputs
+    // assert: sum(payouts) == pool, always, zero deviation
+}
+```
+
+### Anti-Patterns to Avoid
+
+- **float64 for money:** Floating-point representation causes rounding errors. A pool of 10000 cents split 3 ways (3333 + 3333 + 3334) is exact in int64. With float64, 100.00/3 = 33.333... causes cumulative errors across a tournament.
+- **Client-authoritative clock:** The clock MUST be server-authoritative. Client clocks drift, can be manipulated, and diverge across devices. Server sends ticks, clients display.
+- **Mutable audit trail:** Audit entries must be append-only. "Undo" creates a NEW entry that references the original, never deletes or modifies existing entries.
+- **Blocking WebSocket writes:** Never write to a WebSocket connection synchronously in the broadcast loop. Use buffered channels per client with drop semantics for slow consumers.
+- **Global state instead of tournament-scoped:** Every piece of state (clock, players, tables, financials) must be scoped to a tournament ID. Global singletons break MULTI-01.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Password hashing | Custom hash function | golang.org/x/crypto/bcrypt | Bcrypt handles salt generation, timing-safe comparison, configurable cost |
+| JWT token management | Custom token format | golang-jwt/jwt/v5 | Standard claims, expiry, signing algorithm negotiation |
+| QR code generation | Manual QR encoding | skip2/go-qrcode | Reed-Solomon error correction, multiple output formats |
+| WebSocket protocol | Raw TCP upgrade | coder/websocket | RFC 6455 compliance, compression, ping/pong, close handshake |
+| SQLite FTS | Custom search index | FTS5 (built into LibSQL) | Tokenization, ranking, prefix queries, diacritics handled |
+| UUID generation | Custom ID scheme | google/uuid | RFC 4122 compliant, v4 random, v7 time-ordered |
+| Theme colors | Manual hex values | @catppuccin/palette | 26 colors across 4 flavors, community-maintained, consistent |
+| HTTP routing + middleware | Custom mux | go-chi/chi v5 | Middleware composition, route grouping, stdlib compatible |
+
+**Key insight:** The complexity in this phase is in the poker domain logic (ICM, balancing, blind wizard, PKO chains), not in infrastructure. Use battle-tested libraries for all infrastructure concerns so implementation time is spent on domain logic.
+
+## Common Pitfalls
+
+### Pitfall 1: NATS JetStream Default sync_interval Loses Data
+
+**What goes wrong:** Acknowledged writes exist only in OS page cache for up to 2 minutes. Power failure loses all recent tournament state.
+**Why it happens:** NATS defaults to `sync_interval: 2m` for performance, relying on cluster replication for durability. Single-node deployments have no replication.
+**How to avoid:** Set `sync_interval: always` (or `JetStreamSyncInterval: 0` in Go opts) on every embedded NATS instance. Accept the ~10-20% write throughput reduction.
+**Warning signs:** Tests pass because no simulated power failure; first real power cut at a venue loses the last 2 minutes of tournament data.
+
+### Pitfall 2: go-libsql Unpinned Dependency Breaks Build
+
+**What goes wrong:** `go get github.com/tursodatabase/go-libsql@latest` resolves to a different commit on different days. Breaking changes arrive silently.
+**Why it happens:** go-libsql has no tagged releases. Go modules fall back to pseudo-versions based on commit hash.
+**How to avoid:** Pin to a specific commit hash in go.mod. Test thoroughly before updating. Document the pinned commit with a comment.
+**Warning signs:** CI builds succeed locally but fail in a clean environment, or vice versa.
+
+### Pitfall 3: ICM Calculation Factorial Explosion
+
+**What goes wrong:** Exact Malmuth-Harville ICM calculation for 20+ players takes minutes or hours. UI freezes during chop negotiation.
+**Why it happens:** ICM exhausts all possible finish permutations. For N players this is O(N!) — 15 players = 1.3 trillion permutations.
+**How to avoid:** Use exact calculation for <= 10 players. Use Monte Carlo sampling (Tysen Streib method, 2011) for 11+ players with 100K iterations — converges to <0.1% error in under 1 second.
+**Warning signs:** Chop calculation works in testing (4-5 players) but hangs in production with 8+ players.
+
+### Pitfall 4: Payout Rounding Creates Money from Nothing
+
+**What goes wrong:** Prize pool is 10000 cents, payouts sum to 10050 cents due to rounding up. Venue pays out more than collected.
+**Why it happens:** Rounding each payout independently can round up. Multiple round-ups accumulate.
+**How to avoid:** Always round DOWN to venue denomination. Assign remainder to 1st place. CI gate test: assert `sum(payouts) == prize_pool` for every possible input combination.
+**Warning signs:** Payout sum doesn't match prize pool in edge cases (odd numbers, large fields, unusual denominations).
+
+### Pitfall 5: Clock Drift Between Server and Client
+
+**What goes wrong:** Timer shows different values on different devices. Operator's phone says 45 seconds, display says 43 seconds.
+**Why it happens:** Client-side timers using `setInterval` drift due to JS event loop scheduling, tab throttling, and device sleep.
+**How to avoid:** Server is authoritative. Send absolute state (level, remaining_ms, is_paused, server_timestamp) not relative ticks. Client calculates display from server time, correcting for known RTT. Re-sync on every WebSocket message.
+**Warning signs:** Devices show slightly different times; discrepancy grows over long levels.
+
+### Pitfall 6: Undo Doesn't Re-Rank Correctly
+
+**What goes wrong:** Undoing a bust-out puts the player back but rankings are wrong. Players who busted after them have incorrect positions.
+**Why it happens:** Rankings are calculated at bust time. Undoing a bust requires recalculating ALL rankings from that point forward.
+**How to avoid:** Rankings should be derived from the ordered bust-out list, not stored as independent values. Undo removes from bust list, all subsequent positions shift. Re-derive, don't patch.
+**Warning signs:** Rankings look correct for simple undo (last bust) but break for earlier undos.
+
+### Pitfall 7: Table Balancing Race Condition
+
+**What goes wrong:** System suggests "move Player A from Table 1 to Table 4". Before TD executes, Player B busts from Table 1. Now the move makes tables unbalanced in the other direction.
+**Why it happens:** Time gap between suggestion and execution. Real tournaments have concurrent busts during hands in play.
+**How to avoid:** The CONTEXT.md already addresses this: "Suggestion is live and adaptive — if Table 1 loses a player before the move happens, system recalculates or cancels." Implement suggestions as pending proposals that are re-validated before execution.
+**Warning signs:** TD executes a stale balancing suggestion and tables end up worse than before.
+
+### Pitfall 8: SvelteKit adapter-static Path Resolution
+
+**What goes wrong:** Routes work in development but return 404 in production when embedded in Go binary.
+**Why it happens:** SvelteKit adapter-static generates files like `build/players/index.html`. The Go file server doesn't automatically resolve `/players` to `/players/index.html`.
+**How to avoid:** Configure `fallback: 'index.html'` in adapter-static config for SPA mode. The Go handler falls back to index.html for any path not found as a static file, letting SvelteKit's client-side router handle navigation.
+**Warning signs:** Direct navigation to routes works, but refresh on a nested route returns 404.
+
+## Code Examples
+
+### LibSQL Local Database Setup
+
+```go
+// Source: https://github.com/tursodatabase/go-libsql/blob/main/example/local/main.go
+import (
+    "database/sql"
+    _ "github.com/tursodatabase/go-libsql"
+)
+
+func openDB(dataDir string) (*sql.DB, error) {
+    dbPath := filepath.Join(dataDir, "felt.db")
+    db, err := sql.Open("libsql", "file:"+dbPath)
+    if err != nil {
+        return nil, fmt.Errorf("open libsql: %w", err)
+    }
+
+    // Enable WAL mode for concurrent reads during writes
+    if _, err := db.Exec("PRAGMA journal_mode=WAL"); err != nil {
+        return nil, err
+    }
+    // Enable foreign keys
+    if _, err := db.Exec("PRAGMA foreign_keys=ON"); err != nil {
+        return nil, err
+    }
+
+    return db, nil
+}
+```
+
+### Clock Engine State Machine
+
+```go
+type ClockState int
+const (
+    ClockStopped ClockState = iota
+    ClockRunning
+    ClockPaused
+)
+
+type ClockEngine struct {
+    mu            sync.RWMutex
+    tournamentID  string
+    state         ClockState
+    levels        []Level
+    currentLevel  int
+    remainingNs   int64       // Nanoseconds remaining in current level
+    lastTick      time.Time   // Monotonic clock reference
+    totalElapsed  time.Duration
+    warnings      []WarningThreshold
+    hub           *ws.Hub
+}
+
+func (c *ClockEngine) Tick() {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+
+    if c.state != ClockRunning { return }
+
+    now := time.Now()
+    elapsed := now.Sub(c.lastTick)
+    c.lastTick = now
+    c.remainingNs -= elapsed.Nanoseconds()
+    c.totalElapsed += elapsed
+
+    // Check for level transition
+    if c.remainingNs <= 0 {
+        c.advanceLevel()
+    }
+
+    // Check warning thresholds
+    c.checkWarnings()
+
+    // Determine tick rate: 10/sec in final 10s, 1/sec otherwise
+    remainingSec := c.remainingNs / int64(time.Second)
+    msg := c.buildStateMessage()
+
+    // Broadcast to all clients
+    c.hub.Broadcast(c.tournamentID, msg)
+}
+
+func (c *ClockEngine) Snapshot() ClockSnapshot {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    return ClockSnapshot{
+        TournamentID:  c.tournamentID,
+        State:         c.state,
+        CurrentLevel:  c.currentLevel,
+        Level:         c.levels[c.currentLevel],
+        RemainingMs:   c.remainingNs / int64(time.Millisecond),
+        TotalElapsed:  c.totalElapsed,
+        ServerTime:    time.Now().UnixMilli(),
+    }
+}
+```
+
+### Catppuccin Mocha Theme Setup
+
+```css
+/* Source: https://catppuccin.com/palette/ — Mocha flavor */
+:root {
+    /* Base */
+    --ctp-base: #1e1e2e;
+    --ctp-mantle: #181825;
+    --ctp-crust: #11111b;
+
+    /* Text */
+    --ctp-text: #cdd6f4;
+    --ctp-subtext1: #bac2de;
+    --ctp-subtext0: #a6adc8;
+
+    /* Surface */
+    --ctp-surface2: #585b70;
+    --ctp-surface1: #45475a;
+    --ctp-surface0: #313244;
+
+    /* Overlay */
+    --ctp-overlay2: #9399b2;
+    --ctp-overlay1: #7f849c;
+    --ctp-overlay0: #6c7086;
+
+    /* Accents */
+    --ctp-rosewater: #f5e0dc;
+    --ctp-flamingo: #f2cdcd;
+    --ctp-pink: #f5c2e7;
+    --ctp-mauve: #cba6f7;
+    --ctp-red: #f38ba8;
+    --ctp-maroon: #eba0ac;
+    --ctp-peach: #fab387;
+    --ctp-yellow: #f9e2af;
+    --ctp-green: #a6e3a1;
+    --ctp-teal: #94e2d5;
+    --ctp-sky: #89dceb;
+    --ctp-sapphire: #74c7ec;
+    --ctp-blue: #89b4fa;
+    --ctp-lavender: #b4befe;
+}
+
+body {
+    background-color: var(--ctp-base);
+    color: var(--ctp-text);
+    font-family: system-ui, -apple-system, sans-serif;
+}
+```
+
+### Svelte 5 Runes WebSocket State
+
+```typescript
+// Source: Svelte 5 runes documentation
+// lib/stores/tournament.svelte.ts
+
+class TournamentState {
+    clock = $state<ClockSnapshot | null>(null);
+    players = $state<Player[]>([]);
+    tables = $state<Table[]>([]);
+    financials = $state<FinancialSummary | null>(null);
+    activity = $state<ActivityEntry[]>([]);
+
+    get remainingPlayers() {
+        return this.players.filter(p => p.status === 'active').length;
+    }
+
+    get isBalanced() {
+        if (this.tables.length <= 1) return true;
+        const counts = this.tables.map(t => t.players.length);
+        return Math.max(...counts) - Math.min(...counts) <= 1;
+    }
+
+    handleMessage(msg: WSMessage) {
+        switch (msg.type) {
+            case 'clock.tick':
+                this.clock = msg.data;
+                break;
+            case 'player.update':
+                // Reactive update via $state
+                const idx = this.players.findIndex(p => p.id === msg.data.id);
+                if (idx >= 0) this.players[idx] = msg.data;
+                break;
+            // ... other message types
+        }
+    }
+}
+
+export const tournament = new TournamentState();
+```
+
+### PIN Authentication Flow
+
+```go
+// PIN login -> bcrypt verify -> JWT issue
+func (a *AuthService) Login(ctx context.Context, pin string) (string, error) {
+    // Rate limiting: exponential backoff after 5 failures
+    if blocked := a.rateLimiter.Check(pin); blocked {
+        return "", ErrTooManyAttempts
+    }
+
+    operators, err := a.store.GetOperators(ctx)
+    if err != nil { return "", err }
+
+    for _, op := range operators {
+        if err := bcrypt.CompareHashAndPassword([]byte(op.PINHash), []byte(pin)); err == nil {
+            // Match found — issue JWT
+            token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
+                "sub":  op.ID,
+                "role": op.Role, // "admin", "floor", "viewer"
+                "iat":  time.Now().Unix(),
+                "exp":  time.Now().Add(24 * time.Hour).Unix(),
+            })
+            return token.SignedString(a.signingKey)
+        }
+    }
+
+    a.rateLimiter.RecordFailure(pin)
+    return "", ErrInvalidPIN
+}
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Svelte stores (writable/readable) | Svelte 5 runes ($state, $derived, $effect) | Oct 2024 (Svelte 5.0) | All state management uses runes, stores deprecated for new code |
+| nats.JetStreamContext (legacy API) | nats.go/jetstream package (new API) | 2024 | Simpler interfaces, pull consumers, better stream management |
+| gorilla/websocket | coder/websocket (nhooyr fork) | 2024 | Coder maintains the project, context.Context support, concurrent writes |
+| Go 1.21 stdlib ServeMux | Go 1.22+ enhanced ServeMux | Feb 2024 | Method matching + path params in stdlib, but chi still better for middleware |
+| Manual ICM calculation | Monte Carlo ICM approximation | 2011 (Streib) | Practical ICM for any field size, converges quickly |
+
+**Deprecated/outdated:**
+- **Svelte stores for new code:** Still work but Svelte 5 docs recommend runes ($state) for all new code. Stores remain for backward compatibility.
+- **nats.JetStreamContext:** Legacy API. The `jetstream` package under `nats.go/jetstream` is the replacement. Don't use the old JetStreamContext methods.
+- **gorilla/websocket as default choice:** Still works but archived/maintenance-mode. coder/websocket is the actively maintained modern alternative.
+
+## Open Questions
+
+1. **go-libsql CGO Cross-Compilation for CI**
+   - What we know: go-libsql requires CGO_ENABLED=1 and precompiled libsql for linux/amd64
+   - What's unclear: Whether CI runners (GitHub Actions) have the right C toolchain pre-installed, or if we need a custom Docker build image
+   - Recommendation: Test early with a minimal CI pipeline. If problematic, use a Debian-based CI image with build-essential.
+
+2. **go-libsql Exact Commit to Pin**
+   - What we know: No tagged releases. Must pin to commit hash.
+   - What's unclear: Which commit is most stable as of March 2026
+   - Recommendation: Check the repo's main branch, pick the latest commit, verify it passes local tests, pin it with a comment in go.mod.
+
+3. **NATS JetStream Stream Configuration for Audit Trail**
+   - What we know: JetStream streams need proper retention, limits, and subject patterns
+   - What's unclear: Optimal retention policy (limits vs interest), max message size for audit entries with full state snapshots, disk space planning
+   - Recommendation: Start with limits-based retention (MaxAge: 90 days, MaxBytes: 1GB), adjust based on real tournament data sizes.
+
+4. **Svelte 5 Runes with SvelteKit adapter-static**
+   - What we know: Svelte 5 runes work for state management, adapter-static produces a SPA
+   - What's unclear: Whether $state runes in .svelte.ts files work correctly with adapter-static's prerendering (runes are runtime, prerendering is build-time)
+   - Recommendation: Use `fallback: 'index.html'` SPA mode to avoid prerendering issues. Runes are client-side only.
+
+5. **Thermal Printer Receipt Integration**
+   - What we know: FIN-13 requires receipt generation, CONTEXT.md mentions configurable receipt settings
+   - What's unclear: Which thermal printer protocol to target (ESC/POS is standard), whether to generate in Go or browser
+   - Recommendation: Generate receipt as HTML/CSS rendered in a hidden iframe for print. Thermal printer support can use ESC/POS in a later iteration. Digital receipts first.
+
+## Sources
+
+### Primary (HIGH confidence)
+
+- [go-libsql GitHub](https://github.com/tursodatabase/go-libsql) — Local-only API (`sql.Open("libsql", "file:"+path)`), CGO requirement, platform support
+- [go-libsql local example](https://github.com/tursodatabase/go-libsql/blob/main/example/local/main.go) — Verified local-only database opening pattern
+- [NATS JetStream docs](https://docs.nats.io/nats-concepts/jetstream) — JetStream configuration, sync_interval
+- [NATS server discussions #6242](https://github.com/nats-io/nats-server/discussions/6242) — Embedded JetStream account setup, PR #6261 fix
+- [Jepsen NATS 2.12.1](https://jepsen.io/analyses/nats-2.12.1) — sync_interval durability finding, single-node recommendation
+- [coder/websocket GitHub](https://github.com/coder/websocket) — v1.8.14, API, features
+- [go-chi/chi GitHub](https://github.com/go-chi/chi) — v5.2.5, middleware, routing
+- [golang-jwt/jwt v5](https://pkg.go.dev/github.com/golang-jwt/jwt/v5) — JWT library API
+- [Catppuccin palette](https://catppuccin.com/palette/) — Mocha hex values verified
+- [SvelteKit adapter-static docs](https://svelte.dev/docs/kit/adapter-static) — Configuration, fallback, prerender
+- [Svelte 5 runes blog](https://svelte.dev/blog/runes) — $state, $derived, $effect API
+- [ICM Wikipedia](https://en.wikipedia.org/wiki/Independent_Chip_Model) — Malmuth-Harville algorithm, factorial complexity
+
+### Secondary (MEDIUM confidence)
+
+- [Liip blog: Embed SvelteKit into Go](https://www.liip.ch/en/blog/embed-sveltekit-into-a-go-binary) — Complete go:embed + adapter-static pattern, verified with official docs
+- [Replay Poker table rebalancing](https://replayhelp.casino.org/hc/en-us/articles/360001878254-How-table-rebalancing-works) — TDA-compliant balancing algorithm description
+- [PokerSoup blind calculator](https://pokersoup.com/tool/blindStructureCalculator) — Blind structure wizard algorithm approach
+- [Poker TDA 2024 rules](https://www.pokertda.com/poker-tda-rules/) — Official TDA breaking/balancing rules
+- [GTO Wizard PKO theory](https://blog.gtowizard.com/the-theory-of-progressive-knockout-tournaments/) — PKO bounty mechanics (half-split)
+- [HoldemResources ICM](https://www.holdemresources.net/blog/high-accuracy-mtt-icm/) — Monte Carlo ICM approximation for large fields
+
+### Tertiary (LOW confidence)
+
+- [nats-server releases](https://github.com/nats-io/nats-server/releases) — v2.12.4 latest stable (Jan 2026), needs re-check at implementation time
+- go-libsql latest commit hash — needs to be fetched fresh at implementation time
+- Svelte exact version — reported as 5.46+ (Jan 2026), may have newer patches
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — All core libraries verified via official GitHub repos, official docs, and package registries
+- Architecture: HIGH — Patterns (go:embed SPA, embedded NATS, WebSocket hub, event sourcing) verified via multiple official examples and production usage
+- Pitfalls: HIGH — NATS Jepsen finding verified via official Jepsen report; ICM complexity verified via Wikipedia and academic sources; other pitfalls derived from verified library characteristics
+- Domain logic: MEDIUM — Poker domain (ICM, balancing, blind wizard) based on community sources and TDA rules, not on verified software implementations in Go
+
+**Research date:** 2026-03-01
+**Valid until:** 2026-03-31 (30 days — stack is stable, check go-libsql for new tagged releases)

.planning/research/ARCHITECTURE.md

@@ -0,0 +1,496 @@
+# Architecture Research
+
+**Domain:** Edge-cloud poker venue management platform (offline-first, three-tier)
+**Researched:** 2026-02-28
+**Confidence:** MEDIUM-HIGH (core patterns well-established; NATS leaf node specifics verified via official docs)
+
+## Standard Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                            CLOUD TIER (Core)                                    │
+│  Hetzner Dedicated — Proxmox VE — LXC Containers                                │
+│                                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
+│  │  Go Core API │  │  PostgreSQL  │  │NATS JetStream│  │    Authentik     │   │
+│  │  (multi-     │  │  (venue      │  │  (hub cluster│  │  (OIDC IdP)      │   │
+│  │   tenant)    │  │   agg. data) │  │   R=3)       │  │                  │   │
+│  └──────┬───────┘  └──────────────┘  └──────┬───────┘  └──────────────────┘   │
+│         │                                    │                                  │
+│  ┌──────────────┐  ┌──────────────┐          │                                  │
+│  │  SvelteKit   │  │   Netbird    │          │  ← mirrors from leaf streams     │
+│  │  (public     │  │  (WireGuard  │          │                                  │
+│  │   pages,     │  │   mesh ctrl) │          │                                  │
+│  │   admin UI)  │  │              │          │                                  │
+│  └──────────────┘  └──────────────┘          │                                  │
+└────────────────────────────────────────────────────────────────────────────────┘
+         │ WireGuard encrypted tunnel (Netbird mesh)
+         │ NATS leaf node connection (domain: "leaf-<venue-id>")
+         │ NetBird reverse proxy (HTTPS → WireGuard → Leaf :8080)
+         ↓
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                         EDGE TIER (Leaf Node)                                   │
+│  ARM64 SBC — Orange Pi 5 Plus — NVMe — ~€100                                   │
+│                                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
+│  │  Go Leaf API │  │   LibSQL     │  │NATS JetStream│  │  SvelteKit       │   │
+│  │  (tournament │  │  (embedded   │  │  (embedded   │  │  (operator UI    │   │
+│  │   engine,    │  │   SQLite +   │  │   leaf node, │  │   served from    │   │
+│  │   state mgr) │  │   WAL-based) │  │   local      │  │   Leaf)          │   │
+│  └──────┬───────┘  └──────────────┘  │   streams)   │  └──────────────────┘   │
+│         │                            └──────┬───────┘                          │
+│         │ WebSocket broadcast               │ mirror stream                    │
+│         │                                  ↓ (store-and-forward)              │
+│  ┌──────────────┐                   to Core when online                        │
+│  │  Hub Manager │                                                               │
+│  │  (client     │                                                               │
+│  │   registry,  │                                                               │
+│  │   broadcast) │                                                               │
+│  └──────────────┘                                                               │
+└─────────────────────────────────────────────────────────────────────────────────┘
+         │ Local WiFi / Ethernet
+         │ WebSocket (ws:// — LAN only, no TLS needed)
+         │ Chromium kiosk HTTP polling / WebSocket
+         ↓
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                         DISPLAY TIER (Display Nodes)                            │
+│  Raspberry Pi Zero 2W — 512MB RAM — ~€20 each                                  │
+│                                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
+│  │  Chromium    │  │  Chromium    │  │  Chromium    │  │    Chromium      │   │
+│  │  Kiosk       │  │  Kiosk       │  │  Kiosk       │  │    Kiosk         │   │
+│  │  (Clock      │  │  (Rankings)  │  │  (Seating)   │  │  (Signage)       │   │
+│  │   view)      │  │              │  │              │  │                  │   │
+│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────────┘   │
+│  Raspberry Pi OS Lite + X.Org + Openbox + Chromium (kiosk mode, no UI chrome)  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+Player Phones (PWA) ←→ Netbird reverse proxy ←→ Leaf Node
+                        (public HTTPS URL, same URL from any network)
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Implementation |
+|-----------|----------------|----------------|
+| **Go Leaf API** | Tournament engine, financial engine, state machine, WebSocket hub, REST/WS API for operator + players | Go binary (ARM64), goroutine-per-subsystem, embedded NATS + LibSQL |
+| **LibSQL (Leaf)** | Single source of truth for venue state, tournament data, player records | Embedded SQLite via LibSQL driver (`github.com/tursodatabase/go-libsql`), WAL mode |
+| **NATS JetStream (Leaf)** | Local pub/sub for in-process events, durable stream for cloud sync, event audit log | Embedded `nats-server` process, domain `leaf-<venue-id>`, local stream mirrored to Core |
+| **SvelteKit (from Leaf)** | Operator UI (admin SPA) served by Leaf, player PWA, display views | Static SvelteKit build served by Go's `net/http` or embedded filesystem |
+| **Hub Manager (Leaf)** | WebSocket connection registry, broadcast state to all connected clients | Go goroutines + channels; one goroutine per connection, central broadcast channel |
+| **Netbird Agent (Leaf)** | WireGuard tunnel to Core, reverse proxy target registration, DNS | Netbird client process, auto-reconnects, handles NAT traversal via STUN/TURN |
+| **Go Core API** | Multi-tenant aggregation, cross-venue leagues, player identity, remote API access, cloud-hosted free tier | Go binary (amd64), PostgreSQL with RLS, NATS hub cluster |
+| **PostgreSQL (Core)** | Persistent store for aggregated venue data, player profiles, leagues, analytics | PostgreSQL 17+, RLS by `venue_id`, pgx driver in Go |
+| **NATS JetStream (Core)** | Hub cluster receiving mirrored streams from all leaves, fan-out to analytics consumers | Clustered NATS (R=3), domain `core`, stream sources from all leaf mirrors |
+| **Authentik (Core)** | OIDC identity provider for Netbird and Felt operator auth, PIN login fallback | Self-hosted Authentik, ~200MB RAM, Apache 2.0 |
+| **Netbird Control (Core)** | Mesh network management plane, policy distribution, reverse proxy routing | Self-hosted Netbird management + signal services |
+| **SvelteKit (Core)** | Public venue pages (SSR), admin dashboard, free-tier virtual Leaf UI | SvelteKit with SSR for public pages, SPA for dashboard |
+| **Display Nodes** | Render assigned view (clock/rankings/seating/signage) in kiosk browser | Pi Zero 2W + Raspberry Pi OS Lite + X.Org + Openbox + Chromium kiosk |
+
+## Recommended Project Structure
+
+```
+felt/
+├── cmd/
+│   ├── leaf/               # Leaf Node binary entrypoint (ARM64 target)
+│   │   └── main.go         # Boots LibSQL, embedded NATS, HTTP/WS server
+│   └── core/               # Core binary entrypoint (amd64 target)
+│       └── main.go         # Boots PostgreSQL conn, NATS hub, HTTP server
+│
+├── internal/
+│   ├── tournament/         # Domain: tournament engine (state machine)
+│   │   ├── engine.go       # Clock, blinds, levels — pure business logic
+│   │   ├── financial.go    # Buy-ins, rebuys, prize pool, rake
+│   │   ├── seating.go      # Table layout, auto-balance, drag-and-drop
+│   │   └── events.go       # Domain events emitted on state changes
+│   ├── player/             # Domain: player management
+│   │   ├── registry.go     # Player database, registration, bust-out
+│   │   └── identity.go     # Platform-level identity (belongs to Felt, not venue)
+│   ├── display/            # Domain: display node management
+│   │   ├── registry.go     # Node registration, view assignment
+│   │   └── views.go        # View types: clock, rankings, seating, signage
+│   ├── sync/               # NATS JetStream sync layer
+│   │   ├── leaf.go         # Leaf-side: publish events, mirror config
+│   │   └── core.go         # Core-side: consume from leaf mirrors, aggregate
+│   ├── ws/                 # WebSocket hub
+│   │   ├── hub.go          # Client registry, broadcast channel
+│   │   └── handler.go      # Upgrade, read pump, write pump
+│   ├── api/                # HTTP handlers (shared where possible)
+│   │   ├── tournament.go
+│   │   ├── player.go
+│   │   └── display.go
+│   ├── store/              # Data layer
+│   │   ├── libsql/         # Leaf: LibSQL queries (sqlc generated)
+│   │   └── postgres/       # Core: PostgreSQL queries (sqlc generated)
+│   └── auth/               # Auth: PIN offline, OIDC online
+│       ├── pin.go
+│       └── oidc.go
+│
+├── frontend/               # SvelteKit applications
+│   ├── operator/           # Operator UI (served from Leaf)
+│   ├── player/             # Player PWA (served from Leaf)
+│   ├── display/            # Display views (served from Leaf)
+│   └── public/             # Public venue pages (served from Core, SSR)
+│
+├── schema/
+│   ├── libsql/             # LibSQL migrations (goose or atlas)
+│   └── postgres/           # PostgreSQL migrations (goose or atlas)
+│
+├── build/
+│   ├── leaf/               # Dockerfile.leaf, systemd units, LUKS scripts
+│   └── core/               # Dockerfile.core, LXC configs, Proxmox notes
+│
+└── scripts/
+    ├── cross-build.sh      # GOOS=linux GOARCH=arm64 go build ./cmd/leaf
+    └── provision-leaf.sh   # Flash + configure a new Leaf device
+```
+
+### Structure Rationale
+
+- **cmd/leaf vs cmd/core:** Same internal packages, different main.go wiring. Shared domain logic compiles to both targets without duplication. GOARCH=arm64 for leaf, default for core.
+- **internal/tournament/:** Pure domain logic with no I/O dependencies. Testable without database or NATS.
+- **internal/sync/:** The bridge between domain events and NATS JetStream. Leaf publishes; Core subscribes via mirror.
+- **internal/ws/:** Hub pattern isolates WebSocket concerns. Goroutines for each connection; central broadcast channel prevents blocking.
+- **schema/libsql vs schema/postgres:** Separate migration paths because LibSQL (SQLite dialect) and PostgreSQL have syntax differences (no arrays, different types).
+
+## Architectural Patterns
+
+### Pattern 1: NATS JetStream Leaf-to-Core Domain Sync
+
+**What:** Leaf node runs an embedded NATS server with its own JetStream domain (`leaf-<venue-id>`). All state-change events are published to a local stream. Core creates a mirror of this stream using stream source configuration. JetStream's store-and-forward guarantees delivery when the connection resumes after offline periods.
+
+**When to use:** For any state that needs to survive offline periods and eventually reach Core. All tournament events, financial transactions, player registrations.
+
+**Trade-offs:** At-least-once delivery means consumers must be idempotent. Message IDs on publish plus deduplication windows on Core resolve this. No ordering guarantees across subjects, but per-subject ordering is preserved.
+
+**Domain configuration (NATS server config on Leaf):**
+```hcl
+# leaf-node.conf
+jetstream {
+  domain: "leaf-venue-abc123"
+  store_dir: "/data/nats"
+}
+
+leafnodes {
+  remotes [
+    {
+      urls: ["nats://core.felt.internal:7422"]
+      account: "$G"
+    }
+  ]
+}
+```
+
+**Mirror configuration (Core side — creates source from leaf domain):**
+```go
+// core/sync.go
+js.AddStream(ctx, jetstream.StreamConfig{
+    Name: "VENUE_ABC123_EVENTS",
+    Sources: []*jetstream.StreamSource{
+        {
+            Name:          "VENUE_EVENTS",
+            Domain:        "leaf-venue-abc123",
+            FilterSubject: "venue.abc123.>",
+        },
+    },
+})
+```
+
+### Pattern 2: WebSocket Hub-and-Broadcast for Real-Time Clients
+
+**What:** Central Hub struct in Go holds a map of active connections (operator UI, player PWA, display nodes). State changes trigger a broadcast to the Hub. The Hub writes to each connection's send channel. Per-connection goroutines handle read and write independently, preventing slow clients from blocking others.
+
+**When to use:** Any real-time update that needs to reach all connected clients within 100ms — clock ticks, table state changes, seating updates.
+
+**Trade-offs:** In-process hub is simple and fast. No Redis pub/sub needed at single-venue scale. Restart drops all connections (clients must reconnect — which is standard WebSocket behavior).
+
+**Example (Hub pattern):**
+```go
+type Hub struct {
+    clients    map[*Client]bool
+    broadcast  chan []byte
+    register   chan *Client
+    unregister chan *Client
+}
+
+func (h *Hub) Run() {
+    for {
+        select {
+        case client := <-h.register:
+            h.clients[client] = true
+        case client := <-h.unregister:
+            delete(h.clients, client)
+            close(client.send)
+        case message := <-h.broadcast:
+            for client := range h.clients {
+                select {
+                case client.send <- message: // non-blocking
+                default:
+                    close(client.send)
+                    delete(h.clients, client)
+                }
+            }
+        }
+    }
+}
+```
+
+### Pattern 3: Offline-First with Local-Writes-First
+
+**What:** All writes go to LibSQL (Leaf) first, immediately confirming to the client. LibSQL write triggers a domain event published to local NATS stream. NATS mirrors the event to Core asynchronously when online. The UI subscribes to WebSocket and sees state changes from the local store — never waiting on the network.
+
+**When to use:** All operational writes: starting clock, registering buy-in, busting a player, assigning a table.
+
+**Trade-offs:** Core is eventually consistent with Leaf, not strongly consistent. For operational use (venue running a tournament), this is the correct trade-off — the venue never waits for the cloud. Cross-venue features (league standings) accept slight delay.
+
+### Pattern 4: Event-Sourced Audit Trail via JetStream Streams
+
+**What:** NATS JetStream streams are append-only and immutable by default. Every state change (clock pause, player bust-out, financial transaction) is published as an event with sequence number and timestamp. The stream retains full history. This doubles as the sync mechanism and the audit log. Current state in LibSQL is the projection of these events.
+
+**When to use:** All state changes that need an audit trail (financial transactions, player registrations, table assignments).
+
+**Trade-offs:** Stream storage grows over time (limit by time or byte size for old tournaments). Projecting current state from events adds complexity on recovery — mitigate with snapshots in LibSQL. Full event history is available in Core for analytics.
+
+### Pattern 5: Display Node View Assignment via URL Parameters
+
+**What:** Each Pi Zero 2W Chromium instance opens a URL like `http://leaf.local:8080/display?view=clock&tournament=abc123`. The Leaf serves the display SvelteKit app. The view is determined by URL parameter, set via the operator UI's node registry. Chromium kiosk mode (no UI chrome) renders full-screen. Changes to view assignment push through WebSocket, triggering client-side navigation.
+
+**When to use:** All display node management — view assignment, content scheduling, emergency override.
+
+**Trade-offs:** URL-based assignment is simple and stateless on the display node. Requires reliable local WiFi. Pi Zero 2W's 512MB RAM constrains complex Svelte animations; keep display views lightweight (clock, text, simple tables).
+
+## Data Flow
+
+### Tournament State Change Flow (Operator Action)
+
+```
+Operator touches UI (e.g., "Advance Level")
+    ↓
+SvelteKit → POST /api/tournament/{id}/level/advance
+    ↓
+Go Leaf API handler validates & applies change
+    ↓
+LibSQL write (authoritative local state update)
+    ↓
+Domain event emitted: {type: "LEVEL_ADVANCED", level: 5, ...}
+    ↓
+Event published to NATS subject: "venue.{id}.tournament.{id}.events"
+    ↓
+NATS local stream appends event (immutable audit log)
+    ↓ (parallel)
+Hub.broadcast ← serialized state delta (JSON)
+    ↓
+All WebSocket clients receive update within ~10ms
+    ├── Operator UI: updates clock display
+    ├── Player PWA: updates blind levels shown
+    └── Display Nodes: all views react to new state
+    ↓ (async, when online)
+NATS mirror replicates event to Core stream
+    ↓
+Core consumer processes event → writes to PostgreSQL
+    ↓
+Aggregated data available for cross-venue analytics
+```
+
+### Player Phone Access Flow (Online)
+
+```
+Player scans QR code → browser opens https://venue.felt.app/play
+    ↓
+DNS resolves to Core (public IP)
+    ↓
+NetBird reverse proxy (TLS termination at proxy)
+    ↓
+Encrypted WireGuard tunnel → Leaf Node :8080
+    ↓
+Go Leaf API serves SvelteKit PWA
+    ↓
+PWA opens WebSocket ws://venue.felt.app/ws (proxied via same mechanism)
+    ↓
+Player sees live clock, blinds, rankings, personal stats
+```
+
+### Display Node Lifecycle
+
+```
+Pi Zero 2W boots → systemd starts X.Org → Openbox autostart → Chromium kiosk
+    ↓
+Chromium opens: http://leaf.local:8080/display?node-id=display-001
+    ↓
+Leaf API: lookup node-id in node registry → determine assigned view
+    ↓
+SvelteKit display app renders assigned view (clock / rankings / seating / signage)
+    ↓
+WebSocket connection held to Leaf
+    ↓
+When operator reassigns view → Hub broadcasts view-change event
+    ↓
+Display SvelteKit navigates to new view (client-side routing, no page reload)
+```
+
+### Offline → Online Reconnect Sync
+
+```
+Leaf node was offline (NATS leaf connection dropped)
+    ↓
+Venue continues operating normally (LibSQL is authoritative, NATS local streams work)
+All events accumulate in local JetStream stream (store-and-forward)
+    ↓
+WireGuard tunnel restored (Netbird handles auto-reconnect)
+    ↓
+NATS leaf node reconnects to Core hub
+    ↓
+JetStream mirror resumes replication from last sequence number
+    ↓
+Core processes accumulated events in order (per-subject ordering preserved)
+    ↓
+PostgreSQL updated with all events that occurred during offline period
+```
+
+### Multi-Tenant Core Data Model
+
+```
+Core PostgreSQL:
+  venues (id, name, netbird_peer_id, subscription_tier, ...)
+  tournaments (id, venue_id, ...)       ← RLS: venue_id = current_setting('app.venue_id')
+  players (id, felt_user_id, ...)       ← platform-level identity (no venue_id)
+  league_standings (id, league_id, ...) ← cross-venue aggregation
+```
+
+## Scaling Considerations
+
+| Scale | Architecture Adjustments |
+|-------|--------------------------|
+| 1-50 venues (MVP) | Single Core server on Hetzner; NATS single-node or simple cluster; LibSQL on each Leaf is the bottleneck-free read path |
+| 50-500 venues | NATS core cluster R=3 is already the design; PostgreSQL read replicas for analytics; SvelteKit public site to CDN |
+| 500+ venues | NATS super-cluster across Hetzner regions; PostgreSQL sharding by venue_id; dedicated analytics database (TimescaleDB or ClickHouse for event stream) |
+
+### Scaling Priorities
+
+1. **First bottleneck:** Core NATS hub receiving mirrors from many leaves simultaneously. Mitigation: NATS is designed for this — 50M messages/sec benchmarks. Won't be the bottleneck before 500 venues.
+2. **Second bottleneck:** PostgreSQL write throughput as event volume grows. Mitigation: NATS stream is the durable store; Postgres writes are async. TimescaleDB for time-series event analytics defers this further.
+3. **Not a bottleneck:** Leaf Node WebSocket clients — 25,000+ connections on a modest server (the Leaf handles 1 venue, typically 5-50 concurrent clients).
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Making Core a Write Path Dependency
+
+**What people do:** Design operator actions to write to Core (cloud) first, then sync down to Leaf.
+**Why it's wrong:** The primary constraint is offline-first. If Core is the write path, any internet disruption breaks the entire operation.
+**Do this instead:** Leaf is always the authoritative write target. Core is a read/analytics/aggregation target. Never make Core an operational dependency.
+
+### Anti-Pattern 2: Shared Database Between Leaf and Core
+
+**What people do:** Try to use a single LibSQL instance with remote replication as both the Leaf store and Core store.
+**Why it's wrong:** LibSQL embedded replication (Turso model) requires connectivity to the remote primary for writes. This violates offline-first. Also: Core needs PostgreSQL features (RLS, complex queries, multi-venue joins) that LibSQL cannot provide.
+**Do this instead:** Separate data stores per tier. LibSQL on Leaf (sovereign, offline-capable). PostgreSQL on Core (multi-tenant, cloud-native). NATS JetStream is the replication channel, not the database driver.
+
+### Anti-Pattern 3: Single Goroutine WebSocket Broadcast
+
+**What people do:** Iterate over all connected clients in a single goroutine and write synchronously.
+**Why it's wrong:** A slow or disconnected client blocks the broadcast for all others. One stale connection delays the clock update for everyone.
+**Do this instead:** Hub pattern with per-client send channels (buffered). Use `select` with a `default` case to drop slow clients rather than block. Per-connection goroutines handle writes to the actual WebSocket.
+
+### Anti-Pattern 4: Storing View Assignment State on Display Nodes
+
+**What people do:** Configure display views locally on each Pi and SSH in to change them.
+**Why it's wrong:** Requires SSH access to each device. No central management. Adding a new display means physical configuration. Breaking offline-first if central config is required at boot.
+**Do this instead:** Display nodes are stateless. They register with the Leaf by device ID (MAC or serial). Leaf holds the view assignment. Display nodes poll/subscribe for their assignment. Swap physical Pi without reconfiguration.
+
+### Anti-Pattern 5: Separate Go Codebases for Leaf and Core
+
+**What people do:** Create two independent Go repositories with duplicated domain logic.
+**Why it's wrong:** Business logic diverges over time. Bugs fixed in one aren't fixed in the other. Double maintenance burden for a solo developer.
+**Do this instead:** Single Go monorepo with shared `internal/` packages. `cmd/leaf/main.go` and `cmd/core/main.go` are the only divergence points — they wire up the same packages with different configuration. `GOOS=linux GOARCH=arm64 go build ./cmd/leaf` for the Leaf binary.
+
+## Integration Points
+
+### External Services
+
+| Service | Integration Pattern | Notes |
+|---------|---------------------|-------|
+| Netbird (WireGuard mesh) | Agent on Leaf connects to self-hosted Netbird management service; reverse proxy configured per-venue | NetBird reverse proxy is beta, requires Traefik as external reverse proxy on Core; test early |
+| Authentik (OIDC) | Leaf uses OIDC tokens from Authentik for operator login when online; PIN login as offline fallback | PIN verification against locally cached hash in LibSQL; no Authentik dependency during offline operation |
+| NATS JetStream (leaf↔core) | Leaf runs embedded NATS server as leaf node connecting to Core hub over WireGuard | Domain isolation per venue; subjects namespaced `venue.<id>.>` |
+
+### Internal Boundaries
+
+| Boundary | Communication | Notes |
+|----------|---------------|-------|
+| Go Leaf API ↔ LibSQL | Direct SQL via `go-libsql` driver (CGo-free driver preferred for cross-compilation) | Use `sqlc` for type-safe query generation; avoid raw string queries |
+| Go Leaf API ↔ NATS (local) | In-process NATS client connecting to embedded server (`nats.Connect("nats://127.0.0.1:4222")`) | Publish on every state-change event; Hub subscribes to NATS for broadcast triggers |
+| Go Leaf API ↔ WebSocket Hub | Channel-based: API handlers send to `hub.broadcast` channel | Hub runs in its own goroutine; never call Hub methods directly from handlers |
+| Go Core API ↔ PostgreSQL | `pgx/v5` driver, `sqlc` generated queries; RLS via `SET LOCAL app.venue_id = $1` in transaction | Row-level security enforced at database layer as defense-in-depth |
+| Go Core API ↔ NATS (hub) | Standard NATS client; consumers per-venue mirror stream | Push consumers for real-time processing; durable consumers for reliable at-least-once |
+| Leaf ↔ Display Nodes | HTTP (serve SvelteKit app) + WebSocket (state updates) over local LAN | No TLS on local LAN — Leaf and displays are on the same trusted network |
+| Leaf ↔ Player PWA | HTTP + WebSocket proxied via Netbird reverse proxy | HTTPS at proxy, decrypts, sends over WireGuard to Leaf |
+
+## Suggested Build Order
+
+The build order derives from dependency relationships: each layer must be tested before the layer above it depends on it.
+
+```
+Phase 1: Foundation (Leaf Core + Networking)
+   1a. LibSQL schema + Go data layer (sqlc queries, migrations)
+   1b. Tournament engine (pure Go, no I/O — state machine logic)
+   1c. NATS embedded + local event publishing
+   1d. WebSocket Hub (broadcast infrastructure)
+   1e. REST + WS API (operator endpoints)
+   1f. Netbird agent on Leaf (WireGuard mesh)
+   1g. PIN auth (offline) + OIDC auth (online fallback)
+        ↓ Validates: Offline operation works end-to-end
+
+Phase 2: Frontend Clients
+   2a. SvelteKit operator UI (connects to Leaf API + WS)
+   2b. SvelteKit display views (connects to Leaf WS)
+   2c. Player PWA (connects to Leaf via Netbird reverse proxy)
+        ↓ Validates: Real-time sync, display management, player access
+
+Phase 3: Cloud Sync (Core)
+   3a. PostgreSQL schema + RLS (multi-tenant)
+   3b. NATS hub cluster on Core
+   3c. Leaf-to-Core stream mirroring (event replay on reconnect)
+   3d. Go Core API (multi-tenant REST, league aggregation)
+   3e. SvelteKit public pages (SSR) + admin dashboard
+        ↓ Validates: Offline sync, cross-venue features, eventual consistency
+
+Phase 4: Display Management + Signage
+   4a. Display node registry (Leaf API)
+   4b. View assignment system (operator sets view per node)
+   4c. Pi Zero 2W provisioning scripts (kiosk setup automation)
+   4d. Digital signage content system + scheduler
+        ↓ Validates: Wireless display management at scale
+
+Phase 5: Authentication + Security Hardening
+   5a. Authentik OIDC integration
+   5b. LUKS encryption on Leaf (device-level)
+   5c. NATS auth callout (per-venue account isolation)
+   5d. Audit trail validation (event stream integrity checks)
+```
+
+**Why this order:**
+- Leaf foundation must exist before any frontend can connect to it
+- Tournament engine logic is the most complex domain; test it isolated before adding network layers
+- Cloud sync (Phase 3) is a progressive enhancement — the Leaf works completely without it
+- Display management (Phase 4) depends on the WebSocket infrastructure from Phase 1
+- Auth hardening (Phase 5) is last because it can wrap existing endpoints without architectural change
+
+## Sources
+
+- [NATS Adaptive Edge Deployment](https://docs.nats.io/nats-concepts/service_infrastructure/adaptive_edge_deployment) — MEDIUM confidence (official NATS docs on leaf node architecture)
+- [JetStream on Leaf Nodes](https://docs.nats.io/running-a-nats-service/configuration/leafnodes/jetstream_leafnodes) — MEDIUM confidence (official NATS docs on domain isolation and mirroring)
+- [NATS JetStream Core Concepts](https://docs.nats.io/nats-concepts/jetstream) — HIGH confidence (official docs: at-least-once, mirroring, consumer patterns)
+- [Synadia: AI at the Edge with NATS JetStream](https://www.synadia.com/blog/ai-at-the-edge-with-nats-jetstream) — LOW confidence (single source, useful patterns)
+- [NetBird Reverse Proxy Docs](https://docs.netbird.io/manage/reverse-proxy) — MEDIUM confidence (official Netbird docs; note: beta feature, requires Traefik)
+- [LibSQL Embedded Replicas](https://docs.turso.tech/features/embedded-replicas/introduction) — MEDIUM confidence (Turso official docs; embedded replication model)
+- [Multi-Tenancy Database Patterns in Go](https://www.glukhov.org/post/2025/11/multitenant-database-patterns/) — LOW confidence (single source, corroborates general PostgreSQL RLS pattern)
+- [Raspberry Pi Kiosk System](https://github.com/TOLDOTECHNIK/Raspberry-Pi-Kiosk-Display-System) — LOW confidence (community project, validated approach)
+- [Go Cross-Compilation for ARM64](https://dev.to/generatecodedev/how-to-cross-compile-go-applications-for-arm64-with-cgoenabled1-188h) — MEDIUM confidence (multiple corroborating sources; CGO complexity for LibSQL noted)
+- [Building WebSocket Applications in Go](https://www.videosdk.live/developer-hub/websocket/go-websocket) — LOW confidence (corroborates hub pattern; well-established Go pattern)
+- [SvelteKit Service Workers](https://kit.svelte.dev/docs/service-workers) — HIGH confidence (official SvelteKit docs on offline/PWA patterns)
+
+---
+*Architecture research for: Felt — Edge-cloud poker venue management platform*
+*Researched: 2026-02-28*

.planning/research/FEATURES.md

@@ -0,0 +1,347 @@
+# Feature Research
+
+**Domain:** Poker venue management platform (live card rooms, bars, clubs, casinos)
+**Researched:** 2026-02-28
+**Confidence:** MEDIUM — Core feature categories verified across multiple competitor products (TDD, Blind Valet, BravoPokerLive, LetsPoker, CasinoWare, kHold'em, TableCaptain). Feature importance is inferred from competitive analysis and forum discussions, not from direct operator interviews.
+
+---
+
+## Feature Landscape
+
+### Table Stakes (Users Expect These)
+
+Features that every competing product has. Missing any of these makes Felt feel broken before operators even test differentiating features.
+
+#### Tournament Management
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Tournament clock (countdown + level display) | Every competitor has it; this is the core job | LOW | Must show level, time remaining, next blind, break info |
+| Configurable blind structures | TDD, Blind Valet, CasinoWare all require this; no venue runs default blinds | MEDIUM | Presets + custom editor; include antes, bring-ins |
+| Break management (scheduled + manual) | Standard tournament flow; operators must pause for chip-ups, meals | LOW | Break countdown, break message per level |
+| Chip-up / denomination removal messaging | Standard tournament procedure; without it operators improvise manually | LOW | Custom message per break (e.g., "Chip up 5s") |
+| Rebuy / add-on tracking | Required in almost all bar/club tournaments | MEDIUM | Per-player rebuy count, add-on windows, prize pool impact |
+| Late registration window | Industry standard; extends prize pool, increases player counts | LOW | Configurable end-of-level or time-based cutoff |
+| Bust-out tracking | Required for payout ordering and seating consolidation | MEDIUM | Player elimination order, timestamp, chip count at bust |
+| Prize pool calculation | Operators need this instantly; manual math causes errors | MEDIUM | Rake config, bounties, guaranteed pools, overflows |
+| Payout structure (fixed % or variable) | Every serious software has this; without it TDs use paper | MEDIUM | ICM, fixed %, custom splits; print-ready output |
+| Player registration / database | Venues know their regulars; re-entry and rebuy require player identity | MEDIUM | Name, contact, history; import from TDD |
+| Seating assignment (random + manual) | Required for fair tournament start | MEDIUM | Auto-randomize, drag-and-drop adjustments |
+| Table balancing | Required as players bust out; manual is error-prone | HIGH | Auto-suggest moves, seat assignment notifications |
+| Table break / consolidation | Tables must close as field shrinks | MEDIUM | Triggers at N players, assigns destination seats |
+| Multi-tournament support | Venues run satellites alongside mains; bars run concurrent events | HIGH | Independent clocks, financials, player DBs per tournament |
+| Pause / resume clock | Universal need; phone calls, disputes, manual delays | LOW | Single button; broadcasts to all displays |
+| Hand-for-hand mode | Required at bubble; TDA rules mandate clock management | MEDIUM | Stops timer, 2-3 min per hand deduction |
+| Bounty tournament support | Standard format at most venues | MEDIUM | Progressive bounty tracking, per-player bounty calculations |
+| Re-entry tournament support | Common format; distinct from rebuy | MEDIUM | New entry = new stack, maintains same player identity |
+
+#### Cash Game Management
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Waitlist management | Core cash game operation; BravoPokerLive built entirely on this | MEDIUM | By game type + stakes; order preserved; auto-seat |
+| Table status board | Operators and players need to see what games are running | MEDIUM | Open/closed, game type, stakes, seat count, occupied seats |
+| Seat-available notification | Players hate watching the board; notification is now expected | MEDIUM | SMS or push; BravoPokerLive popularized this |
+| Game type + stakes configuration | Venues run multiple games (NLH, PLO, mixed); must be configurable | LOW | Poker variant, stakes level, min/max buy-in |
+| Session tracking (buy-in/cashout) | Required for rake calculation and financial reporting | MEDIUM | Player buy-in amounts, cashout amounts, duration |
+| Rake tracking | Venues live on rake; they must see it per table and in aggregate | MEDIUM | Percentage, time charge, or flat fee per pot |
+| Must-move table handling | Standard practice at busy rooms with main + must-move games | HIGH | Automated progression rules, priority queue |
+| Seat change request queue | Standard poker room procedure; without it conflicts arise | LOW | Players queue for preferred seat, FIFO, dealer notification |
+
+#### Display / Signage
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Tournament clock display (dedicated screen) | Any software that can't show a big clock on a TV is unusable | MEDIUM | Full-screen view: time, level, blinds/antes, next level |
+| Seating board display | Venues show draw results and table assignments on screens | MEDIUM | Table/seat grid, player names, color-coded |
+| Rankings / chip count display | Players want to see standings; operators use it to drive engagement | MEDIUM | Sorted leaderboard, update on eliminations |
+| Upcoming events / schedule display | Venues run this on idle screens; basic signage need | LOW | Schedule rotation between operational views |
+| Multi-screen support | One screen is not enough for a venue | MEDIUM | Each display independently assigned a view |
+
+#### Player-Facing Access
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Mobile clock view (player phone) | Blind Valet and LetsPoker both offer this; players expect it now | MEDIUM | QR code access, no app install, live blind/time view |
+| Player standings on mobile | Players check their ranking constantly; it reduces questions to staff | MEDIUM | Live rank, chip count if entered, position relative to bubble |
+| Waitlist position on mobile | Players want to leave and be notified; board-watching is dying | MEDIUM | Live position number, estimated wait time |
+
+#### Operational Foundations
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| PIN / role-based authentication | Multi-staff venues need access control | MEDIUM | Floor manager, dealer, observer roles; offline PIN |
+| Audit trail (state change log) | Disputes happen; operators need a record | MEDIUM | Who did what, when; immutable append-only log |
+| Data export (CSV / JSON) | Operators archive results, import to spreadsheets, submit to leagues | LOW | Tournament results, player history, financial summary |
+| Offline operation | Venues lose internet; TDD's biggest advantage over cloud-only competitors | HIGH | Full tournament run with zero cloud dependency |
+| Print output (registration slips, payout sheets) | Physically handing a player their payout amount is still standard | LOW | Browser print, no special driver required |
+
+---
+
+### Differentiators (Competitive Advantage)
+
+Features that no single competitor offers completely, or where the gap between current products and user expectations is large enough to win venues.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| Wireless display nodes (no HDMI cables) | Eliminates the #1 physical deployment pain point for venues | HIGH | Pi Zero 2W kiosk over WireGuard mesh; unique to Felt |
+| Offline-first edge architecture | Cloud-only products (Blind Valet) die without internet; TDD has no cloud sync | HIGH | Leaf Node runs full tournament autonomously; game changer for reliability |
+| Player mobile PWA (no app install) | App installs kill adoption; QR → instant live data is frictionless | MEDIUM | Progressive Web App, works on any phone |
+| Integrated digital signage with WYSIWYG editor | Venues pay for separate signage software (Yodeck, NoviSign); Felt combines them | HIGH | Template gallery, AI content generation, venue branding, playlists |
+| AI-assisted promo content generation | No competitor offers AI imagery for drink specials, event promos | HIGH | Generates branded images; reduces need for a graphic designer |
+| League / season management with point formulas | TDD has leagues; Blind Valet has leagues; but neither integrates with operations | MEDIUM | Configurable scoring, automatic season standings, archive |
+| Events engine (triggers + actions) | No competitor has this; "when bubble bursts, play sound, change display, send message" | HIGH | Rule-based automation; webhook support; unlocks countless automations |
+| Cross-venue platform identity (player belongs to Felt, not venue) | BravoPokerLive does discovery; no one does cross-venue player identity for non-casinos | HIGH | Network effects; players carry their history across venues |
+| TDD data import | Critical for adoption; operators have years of data in TDD | MEDIUM | Import blind structures, player DB, tournament history, league records |
+| Touch-native dark-room operator UI | TDD's UI is 2002-era; all competitors have mediocre UX | HIGH | Mobile-first, one-handed operation in a dark card room |
+| Dealer tablet module (bust-outs / rebuys at table) | LetsPoker has this; no other competitor does for live venues | MEDIUM | Reduces floor staff movement; improves accuracy |
+| Multi-room / simultaneous tournament management | Casinos need this; no small-venue product handles it | HIGH | Independent rooms under one operator account |
+| Sound engine (level-up sounds, break alerts, bubble fanfare) | TDD has customizable sounds; most cloud products don't | LOW | Per-event sound mapping; controllable from operator UI |
+| Sponsor ad rotation on signage | Venues monetize signage; no poker software does this natively | LOW | Ad slot in signage playlist with scheduling |
+| Rake analytics dashboard | Most products track rake but don't visualize it usefully | MEDIUM | Per-table, per-game, per-session revenue reporting |
+| Player notifications (seat, waitlist, next tournament) | Push/SMS when seat ready; LetsPoker does this; most don't | MEDIUM | Seat available, waitlist position change, event reminder |
+| Venue public presence page | PokerAtlas does discovery; Felt can combine venue management + public presence | MEDIUM | Public schedule, event registration, venue info |
+
+---
+
+### Anti-Features (Commonly Requested, Often Problematic)
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Payment processing / chip cashout | "Complete the money loop in one system" | Gambling license requirements, PCI compliance, massive regulatory complexity; Felt is a management tool not a payment processor | Track amounts, integrate with existing cage/cashier workflow; show totals clearly |
+| Online poker gameplay | "Run online tourneys too" | Entirely different product (RNG, real-money gambling regulation, anti-fraud); would consume years of development for a different market | Keep focus on live venues; out of scope per PROJECT.md |
+| Video streaming / broadcast | "Stream our home game" | Different infrastructure (CDN, video encoding, latency constraints); adds enormous complexity for a niche use case | Partner with OBS/Streamlabs if needed; do not build |
+| Crypto / blockchain payments | "Accept ETH for buy-ins" | Volatile value, regulatory uncertainty, operational complexity for floor staff; 2024 trend but wrong for this market | Cash is still king in live poker; not needed |
+| Real-money gambling regulation features | "We need GRC built in" | Each jurisdiction has different requirements; would require constant legal maintenance | Operate as a management tool; compliance is venue's responsibility |
+| BYO hardware support | "Can I run it on my old laptop?" | Support burden becomes enormous; hardware variance causes reliability issues; undermines offline guarantees | Ship pre-configured Leaf Nodes; free tier runs on Felt cloud |
+| Separate mobile apps (iOS/Android) for phase 1-3 | "Native app feels better" | Play Store / App Store review cycles slow iteration; PWA covers 95% of use cases for this domain | PWA for players; native apps are Phase 4 only |
+| Multi-currency / regional financial rules | "Support Euro AND GBP" | Display-only currency is fine; actual financial rule compliance per jurisdiction is a legal minefield | Show currency symbol as configuration; no financial calculation changes |
+| Real-time chip count entry by all players | "Players should enter their own chip counts" | Cheating surface; operational chaos; floor staff integrity is paramount | Optional chip count entry by floor staff only with audit trail |
+| Complex tournament scheduling / calendar system | "Let players register online for next month's events" | Phase 3 feature only; in phase 1-2, the complexity diverts from core operational tools | Static event schedule display in phase 1; online registration in phase 3 |
+| Third-party casino management system (CMS) integration | "Connect to IGT/Bally/Aristocrat" | Enterprise sales cycle, NDA/API access requirements, proprietary protocols; not needed for target market | Target venues are non-casino; casinos use Bravo/ACSC anyway |
+| Staking / backing / action splitting | "Track who owns % of players" | Legal complexity, financial tracking burden, scope far beyond venue operations | Out of scope; operators who want this use dedicated tools |
+
+---
+
+## Feature Dependencies
+
+```
+[Player Database]
+    └──requires──> [Tournament Registration]
+                       └──requires──> [Tournament Clock Engine]
+                                          └──requires──> [Blind Structure Config]
+
+[Table Balancing]
+    └──requires──> [Seating Assignment]
+                       └──requires──> [Player Database]
+
+[Waitlist Management] (cash game)
+    └──requires──> [Player Database]
+    └──requires──> [Table Status Board]
+
+[Display System]
+    └──requires──> [Display Node Registry]
+    └──requires──> [Tournament Clock Engine] (for tournament views)
+    └──requires──> [Table Status Board] (for cash game views)
+
+[Player Mobile PWA]
+    └──requires──> [Tournament Clock Engine] (for live data)
+    └──requires──> [Waitlist Management] (for position tracking)
+    └──requires──> [Netbird reverse proxy] (for external access)
+
+[League Management]
+    └──requires──> [Tournament results export / history]
+    └──requires──> [Player Database]
+
+[Events Engine]
+    └──requires──> [Tournament Clock Engine] (trigger source)
+    └──requires──> [Display System] (action target)
+
+[Dealer Tablet Module]
+    └──requires──> [Tournament Registration]
+    └──requires──> [Bust-out Tracking]
+    └──requires──> [Rebuy/Add-on Tracking]
+
+[Digital Signage / Promo Content]
+    └──requires──> [Display Node Registry]
+    └──enhances──> [Events Engine] (content triggers)
+
+[Analytics / Revenue Reporting]
+    └──requires──> [Rake Tracking] (cash games)
+    └──requires──> [Tournament Financial Engine] (tournaments)
+    └──requires──> [Session Tracking]
+
+[NATS Sync / Offline Replay]
+    └──requires──> [Leaf Node embedded NATS]
+    └──enhances──> [All real-time features] (propagates state to clients)
+
+[Loyalty / Points System]
+    └──requires──> [Player Database]
+    └──requires──> [Session Tracking]
+    └──requires──> [Tournament Registration]
+
+[Public Venue Presence]
+    └──requires──> [Core cloud layer]
+    └──requires──> [Player Database] (cross-venue identity)
+```
+
+### Dependency Notes
+
+- **Tournament Clock requires Blind Structure Config:** You cannot run a clock without a structure. Build the structure editor before the clock UI.
+- **Table Balancing requires Seating Assignment:** Balancing suggests moves; you need an assigned seating model first.
+- **Player Mobile PWA requires Netbird reverse proxy:** Players accessing from outside the venue LAN need the reverse proxy tunnel. Must be available from day 1 of mobile features.
+- **Dealer Tablet requires Bust-out + Rebuy tracking:** The tablet is just an input surface for existing state; build the state machine first.
+- **Events Engine enhances almost everything:** Build core features without it first; add Events Engine as an automation layer on top.
+- **Digital Signage conflicts with Lean MVP scope:** Signage is a differentiator but adds significant complexity (content editor, playlist, scheduling). Build operational displays first; WYSIWYG editor is phase 1 stretch, AI content generation is phase 2+.
+- **League Management requires completed tournament results:** You cannot compute standings without a completed tournament history model. League features must come after the core tournament lifecycle is complete.
+
+---
+
+## MVP Definition
+
+### Launch With (v1) — Tournament Operations Core
+
+Minimum viable product for a venue to replace TDD + a whiteboard and run a complete tournament with Felt.
+
+- [ ] Tournament clock engine (countdown, levels, breaks, pause/resume) — core job
+- [ ] Blind structure configuration (custom + presets, antes, chip-up messages) — cannot run without
+- [ ] Player registration + bust-out tracking — needed for payout and table management
+- [ ] Rebuy / add-on / late registration — needed for 90% of real tournaments
+- [ ] Prize pool calculation + payout structure — operators need this to pay out correctly
+- [ ] Table seating assignment (random + manual) + table balancing — required for multi-table events
+- [ ] Financial engine (buy-ins, rake, bounties) — venues need to track cash flow
+- [ ] Display system: clock view + seating view on dedicated screens — the room needs to see the clock
+- [ ] Player mobile PWA: live clock + blinds + personal rank — replaces asking the floor every 2 minutes
+- [ ] Offline-first operation (zero internet dependency during tournament) — reliability requirement
+- [ ] Role-based auth (operator PIN offline, OIDC online) — floor staff access control
+- [ ] TDD data import (blind structures + player DB) — adoption enabler for existing TDD users
+- [ ] Data export (CSV, JSON, HTML print output) — venues archive results, submit to leagues
+
+### Add After Validation (v1.x) — Tournament Enhancement + Cash Game Foundations
+
+Add once the core tournament loop is proven reliable in production.
+
+- [ ] League / season management — triggered when venues start asking for standings tracking
+- [ ] Hand-for-hand mode — needed before any venue runs a serious event with a bubble
+- [ ] Events engine (sound triggers, view changes on level-up, break start) — high value, low user cost
+- [ ] Digital signage (schedule/promo display between operational views) — venues want their idle screens working
+- [ ] Waitlist management + table status board — prerequisite for cash game operations
+- [ ] Session tracking (buy-in / cashout / duration) — cash game financial foundation
+- [ ] Rake tracking per table — cash game revenue visibility
+- [ ] Seat-available notifications (push / SMS) — player retention for cash games
+- [ ] Must-move table logic — required at any venue with main game protection
+- [ ] Dealer tablet module (bust-outs + rebuys at table) — reduces floor staff walking
+
+### Future Consideration (v2+) — Platform Maturity
+
+Defer until core product-market fit is established across tournament and cash game operations.
+
+- [ ] WYSIWYG content editor + AI promo generation — Phase 1 is out-of-the-box templates; WYSIWYG editor is Phase 2 after operational features are solid
+- [ ] Dealer management (scheduling, rotations, clock-in) — Phase 3; operators won't churn over this
+- [ ] Player loyalty / points system — Phase 3; high complexity, needs player identity first
+- [ ] Public venue presence page + online event registration — Phase 3; requires stable Core cloud layer
+- [ ] Analytics dashboards (revenue, player retention, game popularity) — Phase 3; operators need basic reporting first
+- [ ] Private venues + membership management — Phase 3; niche use case (private clubs)
+- [ ] Native iOS / Android apps (player + operator) — Phase 4; PWA covers the use case until then
+- [ ] Social features (friends, activity feed, achievements) — Phase 4; requires large player network first
+- [ ] Cross-venue player leaderboards — Phase 4; requires critical mass of venues on the platform
+
+---
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| Tournament clock engine | HIGH | LOW | P1 |
+| Blind structure config | HIGH | LOW | P1 |
+| Player registration + bust-out | HIGH | MEDIUM | P1 |
+| Rebuy / add-on | HIGH | MEDIUM | P1 |
+| Payout calculation + structure | HIGH | MEDIUM | P1 |
+| Table seating + balancing | HIGH | HIGH | P1 |
+| Display system (clock + seating views) | HIGH | HIGH | P1 |
+| Player mobile PWA (clock + rank) | HIGH | MEDIUM | P1 |
+| Offline-first operation | HIGH | HIGH | P1 |
+| TDD data import | HIGH | MEDIUM | P1 |
+| Financial engine (buy-ins, rake) | HIGH | MEDIUM | P1 |
+| Role-based auth (PIN + OIDC) | HIGH | MEDIUM | P1 |
+| Waitlist management | HIGH | MEDIUM | P2 |
+| Cash game table status board | HIGH | MEDIUM | P2 |
+| Session + rake tracking | HIGH | MEDIUM | P2 |
+| Events engine | MEDIUM | HIGH | P2 |
+| League management | MEDIUM | MEDIUM | P2 |
+| Dealer tablet module | MEDIUM | MEDIUM | P2 |
+| Hand-for-hand mode | HIGH | LOW | P2 |
+| Seat-available notifications | MEDIUM | MEDIUM | P2 |
+| Must-move logic | MEDIUM | HIGH | P2 |
+| Digital signage (playlist + schedule) | MEDIUM | HIGH | P2 |
+| WYSIWYG content editor | MEDIUM | HIGH | P3 |
+| AI content generation | LOW | HIGH | P3 |
+| Dealer management / scheduling | MEDIUM | HIGH | P3 |
+| Loyalty points system | MEDIUM | HIGH | P3 |
+| Public venue presence | MEDIUM | HIGH | P3 |
+| Analytics dashboards | MEDIUM | HIGH | P3 |
+| Native mobile apps | LOW | HIGH | P3 |
+| Social / friend features | LOW | HIGH | P3 |
+
+**Priority key:**
+- P1: Must have for any operator to run a tournament with Felt
+- P2: Must have to expand beyond early adopters and cover cash game venues
+- P3: Must have to compete at enterprise / casino tier
+
+---
+
+## Competitor Feature Analysis
+
+| Feature | TDD | Blind Valet | BravoPokerLive | LetsPoker | Felt (planned) |
+|---------|-----|-------------|----------------|-----------|----------------|
+| Tournament clock | Yes (deep) | Yes (basic) | No | Yes | Yes (deep) |
+| Blind structure editor | Yes (deep) | Yes | No | Yes | Yes (deep + presets) |
+| Player registration | Yes | Yes (basic) | Player-side only | Yes | Yes |
+| Rebuy / add-on | Yes | Yes | No | Yes | Yes |
+| Bust-out tracking | Yes | Yes | No | Yes | Yes |
+| Table balancing | Yes | No | No | Yes | Yes |
+| Multi-tournament | Yes (limited) | No | No | Yes | Yes |
+| Payout calculator | Yes | Yes | No | Yes | Yes |
+| League management | Yes | Yes | No | Yes | Yes |
+| Display (TV clock) | Yes (HDMI) | Browser | No | Yes (browser) | Yes (wireless nodes) |
+| Player mobile access | No | Yes | Yes (waitlist) | Yes | Yes (PWA) |
+| Waitlist management | No | No | Yes (core feature) | Yes | Yes |
+| Cash game table board | No | No | Yes | Yes | Yes |
+| Session / rake tracking | No | No | No | Partial | Yes |
+| Must-move tables | No | No | Partial | No | Yes |
+| Offline operation | Yes (Windows only) | No | No | No | Yes (ARM SBC) |
+| Cloud sync | No | Yes | Yes | Yes | Yes (NATS) |
+| Cross-platform | Windows only | Browser | iOS/Android | All | Browser / PWA |
+| Digital signage | No | No | No | No | Yes (integrated) |
+| Events engine | Yes (scripts) | No | No | No | Yes |
+| AI content generation | No | No | No | No | Yes (planned) |
+| Dealer tablet module | No | No | No | Yes | Yes (Phase 2) |
+| Loyalty system | No | No | No | No | Yes (Phase 3) |
+| Dealer management | No | No | No | No | Yes (Phase 3) |
+| Analytics dashboard | Minimal | No | Partial (player app) | Partial | Yes (Phase 3) |
+| Import from TDD | N/A | No | No | No | Yes |
+| Wireless displays | No | No | No | No | Yes (unique) |
+| Platform player identity | No | No | Partial (national) | Partial | Yes (cross-venue) |
+
+---
+
+## Sources
+
+- [The Tournament Director](https://www.thetournamentdirector.net/) — feature research (403 on direct fetch; confirmed via WebSearch and community forums)
+- [Blind Valet](https://blindvalet.com/) — features page fetched directly
+- [BravoPokerLive App Store](https://apps.apple.com/us/app/bravopokerlive/id470322257) — feature descriptions
+- [LetsPoker](https://lets.poker/) — confirmed via [PokerNews LetsPoker article](https://www.pokernews.com/news/2022/02/letspoker-app-looks-to-revolutionize-the-world-of-live-poker-40689.htm) and [LetsPoker features article](https://lets.poker/articles/letspoker-features/)
+- [CasinoWare](https://www.casinoware.net/) — features fetched directly
+- [kHold'em](https://www.kholdem.net/en/) — features fetched directly
+- [PokerAtlas TableCaptain](https://www.pokeratlas.com/info/table-captain) — confirmed via WebSearch (403 on direct fetch)
+- [PokerNews: Best Poker Table Management Software](https://www.pokernews.com/strategy/what-is-the-best-poker-table-management-software-48189.htm) — category overview
+- [Poker Chip Forum: What tournament management solution are you using?](https://www.pokerchipforum.com/threads/what-tournament-management-solution-are-you-using.106524/) — operator pain points (403 on direct fetch; confirmed via WebSearch)
+- [Poker Chip Forum: Not impressed with tournament director](https://www.pokerchipforum.com/threads/not-really-impressed-with-tournament-director-software-any-interest-in-this.69632/) — TDD limitations
+- [Home Poker Tourney: Clock Features Chart](https://homepokertourney.org/clocks-chart.htm) — feature comparison matrix fetched directly
+- [3UP Gaming: Compare Poker Tournament Software](https://www.3upgaming.com/blog/compare-the-best-poker-tournament-software-providers/) — provider comparison fetched directly
+- [Technology.org: Optimizing Poker Room Operations](https://www.technology.org/2025/01/23/optimizing-poker-room-operations-with-advanced-software/) — operational features (403 on direct fetch; confirmed via WebSearch)
+- [3UP Gaming: Poker Room Waiting List App](https://www.3upgaming.com/blog/poker-room-waiting-list-app-the-best-tools-to-manage-your-poker-games) — waitlist feature analysis
+
+---
+*Feature research for: poker venue management platform (Felt)*
+*Researched: 2026-02-28*

.planning/research/PITFALLS.md

@@ -0,0 +1,456 @@
+# Pitfalls Research
+
+**Domain:** Edge-cloud poker venue management platform (offline-first, ARM64 SBC, real-time display sync, multi-tenant SaaS)
+**Researched:** 2026-02-28
+**Confidence:** MEDIUM-HIGH (critical pitfalls verified against multiple sources; some domain-specific items from training data flagged)
+
+---
+
+## Critical Pitfalls
+
+### Pitfall 1: NATS JetStream Data Loss Under Default fsync Settings
+
+**What goes wrong:**
+NATS JetStream's default `sync_interval` is 2 minutes — meaning acknowledged messages are not guaranteed to be on disk before the ACK is sent to the client. A kernel crash, power loss, or sudden SBC shutdown on the Leaf node can result in losing messages that were already ACK'd by the broker. The December 2025 Jepsen analysis of NATS 2.12.1 confirmed this: "NATS JetStream can lose data or get stuck in persistent split-brain in response to file corruption or simulated node failures." Even a single power failure can trigger loss of committed writes.
+
+**Why it happens:**
+The lazy fsync default prioritizes throughput over durability. This is the correct tradeoff for most messaging workloads. However, tournament state sync is financial-adjacent: a lost "player busted" or "rebuy processed" event corrupts the prize pool ledger and produces incorrect final payouts. Developers assume "acknowledged" means "durable."
+
+**How to avoid:**
+Set `sync_interval: always` on the embedded NATS server configuration on the Leaf node. This makes NATS fsync before every acknowledgement. Accept the throughput reduction — tournament events are low-frequency (< 100 events/minute) so this has zero practical impact. Verify this setting is in the embedded server config before first production deploy.
+
+```yaml
+# nats-server.conf for Leaf
+jetstream {
+  store_dir: /var/lib/felt/jetstream
+  sync_interval: always
+}
+```
+
+**Warning signs:**
+- Default config template copied from NATS quickstart docs (which do not set `sync_interval`)
+- Tournament events not replaying correctly after SBC reboot in testing
+- "Event count mismatch" after power-cycle tests
+
+**Phase to address:** Phase 1 (NATS JetStream integration) — bake this into the embedded server bootstrap config, not as a post-launch fix.
+
+---
+
+### Pitfall 2: LibSQL/SQLite WAL Checkpoint Stall Causing Write Timeouts
+
+**What goes wrong:**
+SQLite in WAL mode accumulates changes in the WAL file until a checkpoint copies them back to the main database. Under sustained write load (active tournament with frequent state updates), the WAL file can grow unbounded if readers hold long transactions — preventing checkpoint from completing. When a checkpoint finally runs (FULL or RESTART mode), it briefly blocks all writers, causing the tournament clock update goroutine to queue up and miss a 1-second tick. Separately, running LibSQL's sync operation while the local WAL is being actively written risks data corruption (documented in LibSQL issue #1910).
+
+**Why it happens:**
+Developers set WAL mode and consider concurrency "solved." They miss that: (1) WAL autocheckpoint defaults to PASSIVE mode which skips when readers are present, (2) uncontrolled WAL growth degrades read performance as SQLite must scan further into WAL history, and (3) LibSQL sync must not overlap with active write transactions.
+
+**How to avoid:**
+- Set `PRAGMA wal_autocheckpoint = 0` to disable automatic checkpointing, then schedule explicit `PRAGMA wal_checkpoint(TRUNCATE)` during quiet periods (e.g., break periods in tournament, level transitions).
+- Set `PRAGMA journal_size_limit = 67108864` (64MB) to cap WAL file size.
+- Never initiate LibSQL cloud sync during an active database write transaction — gate sync on a mutex with the write path.
+- Use `PRAGMA busy_timeout = 5000` to avoid immediate failures when contention occurs.
+
+**Warning signs:**
+- Tournament clock drifting by 1-2 seconds during heavy rebuy periods
+- WAL file growing past 50MB during long tournaments
+- LibSQL sync errors logged during high-activity periods
+
+**Phase to address:** Phase 1 (database layer setup) — configure these pragmas in the database initialization code path, not as tuning afterthoughts.
+
+---
+
+### Pitfall 3: Offline-First Sync Conflict Producing Incorrect Prize Pool Ledger
+
+**What goes wrong:**
+The Leaf node operates offline. If an operator on the venue tablet and a player viewing their phone PWA both initiate actions that affect the same tournament state (e.g., operator marks player as busted while player is registering a rebuy via PWA), conflicting events arrive at the NATS stream in undefined order when connectivity resumes. A Last-Write-Wins or timestamp-based merge on financial records corrupts the prize pool: a rebuy that was processed offline gets silently dropped, and the player is paid out less than they are owed.
+
+**Why it happens:**
+Developers treat all offline sync as equal. Financial ledger mutations (buy-ins, rebuys, payouts) are not idempotent by default. The LibSQL sync "last-push-wins" default is dangerous for financial records where all writes must be applied in the correct order. Timestamp-based ordering fails on SBCs where system clocks can drift.
+
+**How to avoid:**
+- Treat financial transactions as an append-only event log, never as mutable rows. Each buy-in, rebuy, add-on, and payout is an immutable event with a monotonic sequence number assigned by the Leaf node.
+- Never use wall clock timestamps to order conflicting financial events — use lamport clocks or NATS sequence numbers as the canonical ordering.
+- The prize pool balance is always derived from the event log (computed, never stored directly), so a re-play of all events always produces the correct total.
+- Mark financial events as requiring explicit human conflict resolution (surface a UI alert) rather than auto-merging on the rare case of genuine conflicts.
+
+**Warning signs:**
+- Prize pool total doesn't match sum of individual player buy-in records
+- Rebuy count in player history differs from rebuy count in prize pool calculation
+- Sync error logs showing sequence number gaps in NATS stream replay
+
+**Phase to address:** Phase 1 (financial engine design) — must be an architectural decision, not retrofittable.
+
+---
+
+### Pitfall 4: Pi Zero 2W Memory Exhaustion Crashing Display Node
+
+**What goes wrong:**
+The Raspberry Pi Zero 2W has 512MB RAM. Chromium running a full WebGL/Canvas display (animated tournament clock, live chip counts, scrolling rankings) can consume 300-400MB alone, leaving minimal headroom. Memory pressure causes the kernel OOM killer to terminate Chromium mid-display. Without a proper watchdog and restart mechanism, the display node goes dark silently — venue staff don't notice until a player complains. Over multi-hour tournaments, memory leaks in JavaScript (uncollected WebSocket message handlers, accumulated DOM nodes) compound this.
+
+**Why it happens:**
+Development happens on a desktop or full Raspberry Pi 4 with 4-8GB RAM. The Zero 2W constraint is not felt until hardware testing. Display views are designed with visual richness in mind, without profiling memory consumption on the target hardware. WebSocket reconnection handlers that fail to deregister previous listeners create unbounded listener growth.
+
+**How to avoid:**
+- Test ALL display views on actual Pi Zero 2W hardware from day one, not just functionality but memory usage (use `chrome://memory-internals` or external monitoring).
+- Set Chromium flags: `--max-old-space-size=256 --memory-pressure-off` — counterintuitively, disabling pressure signals can prevent thrashing.
+- Enable `zram` on the Pi Zero 2W (compressed swap) — adds ~200MB effective memory, documented to make Chromium "usable" on constrained devices.
+- Implement a kiosk watchdog service (systemd `Restart=always` + `MemoryMax=450M`) that restarts Chromium if it exceeds memory limits.
+- Use Server-Sent Events (SSE) instead of WebSocket for display-only views — reduces connection overhead and eliminates bidirectional state machine complexity where one-way push is sufficient.
+- Implement manual listener cleanup in all WebSocket event handlers: always call `removeEventListener` in cleanup functions.
+
+**Warning signs:**
+- Display works fine for 30 minutes, then goes blank
+- `dmesg` on Pi Zero shows `oom-kill` entries
+- Memory usage climbs monotonically over tournament duration when profiling
+
+**Phase to address:** Phase 1 (display node MVP) — must validate on target hardware before building more display views.
+
+---
+
+### Pitfall 5: Tournament Table Rebalancing Algorithm Producing Unfair or Invalid Seating
+
+**What goes wrong:**
+Table rebalancing when players bust out is operationally critical and algorithmically subtle. Common failures: (1) moving a player who just posted their blind, creating a situation where they post blind twice before being able to act; (2) breaking a table that still has enough players to stay open; (3) choosing a player to move who has the dealer button (invalid in most rule sets); (4) the algorithm enters an infinite loop when there is no valid move (e.g., exactly balanced tables that can't be further balanced without breaking one). The Tournament Director software has a known bug where "if the dealer button is set to a non-valid seat, a table balance can cause the application to lock-up."
+
+**Why it happens:**
+Developers implement the "move player from biggest table to smallest table" happy path, then discover edge cases through production tournaments. Poker TDA rules for balancing are complex and context-dependent. The interaction between dealer button position, blind positions, and move eligibility is not obvious.
+
+**How to avoid:**
+- Implement rebalancing as a pure function that takes complete tournament state and returns a list of moves — enables exhaustive unit testing with edge cases.
+- Consult the Poker TDA Rules (2024 edition) as the authoritative reference for rebalancing procedures (Rules 25-28 cover table balancing and player movement).
+- Test edge cases explicitly: single player remaining, two players at same table count, dealer button at last seat, player in small blind position being the move candidate.
+- Expose a "dry run" rebalancing mode in the UI that shows proposed moves before executing — operators can catch bad suggestions before players are physically moved.
+- Never auto-apply rebalancing; always require operator confirmation.
+
+**Warning signs:**
+- Players complaining about double-posting blinds after a move
+- Tournament stuck unable to proceed after table break
+- Rebalancing suggestion moving the dealer button holder
+
+**Phase to address:** Phase 1 (seating engine) — core algorithm must be implemented and unit tested exhaustively before tournament testing.
+
+---
+
+### Pitfall 6: Multi-Tenant RLS Policy Leaking Venue Data at Application Layer
+
+**What goes wrong:**
+PostgreSQL Row Level Security on Core provides database-level tenant isolation, but RLS has a critical operational failure mode: if the application sets the `app.tenant_id` session variable (the common pattern for RLS) using a connection pool that reuses connections between requests, a previous request's tenant ID can bleed into the next request's session. This is a documented thread-safety issue — "some requests were being authorized with a previous request's user id because the user id for RLS was being stored in thread-local storage and threads were being reused for requests."
+
+**Why it happens:**
+RLS tutorials typically show setting `SET LOCAL app.tenant_id = $1` inside a transaction, which is safe. But connection pools that don't reset session state between checkouts, or code that uses `SET` instead of `SET LOCAL`, cause session variables to persist across requests. In a multi-tenant venue management platform, this means venue A could see venue B's player data.
+
+**How to avoid:**
+- Always use `SET LOCAL app.tenant_id = $1` (transaction-scoped), never `SET app.tenant_id` (session-scoped).
+- Use a connection pool that explicitly resets session state on checkout (pgBouncer in transaction mode is safer than session mode for this pattern).
+- Add an application-layer assertion: before every query, verify that `current_setting('app.tenant_id')` matches the expected tenant from the JWT/session — log and reject any mismatch as a security event.
+- Write integration tests that explicitly test cross-tenant isolation: authenticate as venue A, attempt to query venue B's data through all API endpoints.
+
+**Warning signs:**
+- Flaky test failures where tenant data appears for wrong user (intermittent = session state bleed)
+- Query results contain more rows than expected for a given venue's player count
+- Connection pool configured in session mode (pgBouncer `pool_mode = session`)
+
+**Phase to address:** Phase 1 (Core backend data model) — RLS policies and the tenant isolation integration tests must be built before any multi-venue feature.
+
+---
+
+### Pitfall 7: Financial Calculations Using Floating-Point Arithmetic
+
+**What goes wrong:**
+Prize pool calculations, rake, bounties, and payout distributions calculated using `float64` accumulate representation errors. `0.1 + 0.2 != 0.3` in IEEE 754. A tournament with 127 players at €55 buy-in with 10% rake, split across 12 payout positions with percentage-based distribution, will produce cent-level errors that cascade: the sum of individual payouts does not equal the prize pool total, creating a money reconciliation error. In a live venue, this is a regulatory and reputational risk.
+
+**Why it happens:**
+Go's `float64` feels precise enough for small numbers. Developers write `prizePool := float64(buyIns) * 0.9` and don't notice that `0.9` is not exactly representable. The error is invisible until summing many such calculations.
+
+**How to avoid:**
+- Store and compute ALL financial values as `int64` representing the smallest currency unit (eurocents for EUR). €55 = 5500 cents.
+- Never store or compute monetary values as `float64`. If you need percentage-based rake, multiply first then divide: `rake = (buyInCents * rakePercent) / 100` using integer division.
+- For payout percentage splits (e.g., 35.7% to 1st place), compute each payout as `(prizePool * 357) / 1000` in integer arithmetic, then distribute any remainder (due to truncation) to the first payout position.
+- Write a test that sums all individual payouts and asserts equality to the prize pool total — this test will catch floating-point drift immediately.
+
+**Warning signs:**
+- Prize pool "total" displayed in UI differs by €0.01-0.02 from sum of individual payouts
+- Rake calculation produces fractional cents
+- Any use of `float64` in the financial calculation code path
+
+**Phase to address:** Phase 1 (financial engine) — this is a zero-compromise architectural constraint, not a later optimization.
+
+---
+
+## Moderate Pitfalls
+
+### Pitfall 8: ARM64 CGO Cross-Compilation Blocking CI/CD
+
+**What goes wrong:**
+Go cross-compilation for `GOARCH=arm64` is trivial for pure Go code: set `GOOS=linux GOARCH=arm64` and the toolchain handles everything. The moment any dependency uses CGO (C bindings), this breaks. CGO requires a target-specific C toolchain (`aarch64-linux-gnu-gcc`). LibSQL's Go bindings may require CGO. If not caught early, the CI/CD pipeline that builds the Leaf node binary fails on x86-64 build agents, blocking all Leaf deployments.
+
+**Prevention:**
+- Audit all dependencies for CGO usage before finalizing the stack: `go build -v ./... 2>&1 | grep cgo`.
+- For any CGO dependency, set up Docker Buildx with `--platform linux/arm64` multi-arch builds from the start.
+- Alternatively, choose pure-Go alternatives where possible: `modernc.org/sqlite` (CGO-free SQLite driver) vs `mattn/go-sqlite3` (requires CGO). Validate LibSQL Go driver CGO requirements against the latest release.
+- Use a dedicated ARM64 build runner (e.g., a Hetzner CAX11 ARM instance) as the canonical Leaf build environment rather than cross-compiling.
+
+**Warning signs:**
+- `cannot execute binary file: Exec format error` when deploying to Leaf
+- CI build succeeds on x86 runner but produces wrong binary
+- Build scripts not setting `GOARCH` and `GOOS` explicitly
+
+**Phase to address:** Phase 1 (build system setup) — establish cross-compilation pipeline before writing any Leaf-specific code.
+
+---
+
+### Pitfall 9: WebSocket State Desync — Server Restarts vs. Client State
+
+**What goes wrong:**
+The Leaf backend restarts (deploy, crash, OOM). All WebSocket connections drop. When clients reconnect, they receive a "current state" snapshot. But if the snapshot is emitted before all pending database writes have completed (race condition between reconnect handler and write completion), clients receive a stale snapshot and operate on incorrect state. Operators may see a tournament clock that's 45 seconds behind reality, or chip counts from before the last bust-out.
+
+**Why it happens:**
+WebSocket reconnect handlers typically emit state immediately on connection establishment. If the server restart was triggered by a deploy, in-flight writes from the last moments before restart may not have been committed. The reconnect handler races against database recovery.
+
+**How to avoid:**
+- Implement sequence numbers on all state updates. Every WebSocket message carries a monotonic `seq` field. Clients detect gaps in sequence and request a full resync rather than trusting a partial update.
+- On server restart, wait for LibSQL WAL to be fully checkpointed before accepting new WebSocket connections (add a health check gate).
+- Implement idempotent state application on the client: applying the same state update twice produces the same result (prevents double-application of duplicate messages during reconnect window).
+- Only one goroutine writes to a WebSocket connection at a time (Go WebSocket constraint) — use a dedicated send goroutine with a buffered channel.
+
+**Warning signs:**
+- Tournament clock jumps backward after reconnect
+- Chip counts inconsistent between two operators' screens after server restart
+- Client receiving sequence numbers with gaps
+
+**Phase to address:** Phase 1 (real-time sync architecture) — must be designed correctly from the first WebSocket implementation.
+
+---
+
+### Pitfall 10: SBC Hardware Reliability — Power Loss During Tournament
+
+**What goes wrong:**
+The Leaf node (Orange Pi 5 Plus) loses power mid-tournament. Even with NVMe (superior to SD card), an unclean shutdown can corrupt the filesystem if writes were in-flight. LibSQL's WAL may be partially written. The NATS JetStream store directory may be in an inconsistent state. On restoration, the system may fail to start, or worse, start with corrupted state that appears valid.
+
+**Why it happens:**
+SBC deployments in venues are not enterprise environments. Power strips get kicked. UPS systems are absent. NVMe is more reliable than SD but is not immune to corruption on power loss — the OS ext4 journal and SQLite WAL both need clean shutdown to guarantee consistency.
+
+**How to avoid:**
+- Mount the NVMe with a journaling filesystem configured for ordered data mode: `ext4` with `data=ordered` (default on most distros, but verify).
+- Run LibSQL with `PRAGMA synchronous = FULL` (or at minimum `NORMAL`) and `PRAGMA journal_mode = WAL` — already planned, but verify synchronous mode specifically.
+- Configure NATS `sync_interval: always` (Pitfall 1 above) to ensure JetStream state is on disk before any event is ACK'd.
+- Implement a daily backup cron job that copies the LibSQL database to a USB drive or cloud (Hetzner Storage Box) — gives a recovery point even if local corruption is total.
+- Add a systemd `ExecStop` hook that runs `PRAGMA wal_checkpoint(TRUNCATE)` before the process exits, minimizing WAL state at shutdown.
+
+**Warning signs:**
+- Venues skipping UPS/surge protector hardware
+- Leaf node failing to start after power cycle during testing
+- Filesystem errors in `dmesg` on startup after unclean shutdown
+
+**Phase to address:** Phase 1 (Leaf node infrastructure setup) — backup strategy and sync configuration must be part of initial deployment scripts.
+
+---
+
+### Pitfall 11: GDPR Violation — Storing Player PII on Leaf Without Consent Mechanism
+
+**What goes wrong:**
+Player names, contact details, and tournament history are stored on the Leaf node for offline operation. If the venue is in the EU (the target market is Danish/European), this constitutes processing of personal data under GDPR. Without explicit consent capture at registration, documented data retention policies, and a right-to-erasure mechanism, the venue operator is liable. Fines can reach €20 million or 4% of global annual turnover. The platform architecture (players belong to Felt, not venues) amplifies risk — Felt is the data controller for the platform-level player profile.
+
+**Why it happens:**
+Tournament management software traditionally treats player data as operational, not personal. Developers focus on functionality first. GDPR compliance is deferred as "legal's problem." The offline-first architecture compounds this: data on edge devices is harder to audit and harder to delete on-request.
+
+**How to avoid:**
+- Define the data model from day one with GDPR in mind: separate PII fields (name, email, phone) from operational data (chip count, tournament position). This allows selective erasure without corrupting tournament history.
+- Implement a "right to erasure" API endpoint that anonymizes PII (replaces name with "Player [ID]", nullifies contact fields) while preserving tournament result records for statistical purposes.
+- Leaf node must be encrypted at rest (LUKS — already planned). Verify LUKS is set up in the provisioning flow.
+- Data retention: document a default retention policy (e.g., player PII deleted after 12 months of inactivity) and implement automated enforcement.
+- Consent must be captured before storing player contact details — the player registration flow must include explicit consent.
+
+**Warning signs:**
+- Player registration form collecting email/phone without a consent checkbox
+- No data deletion API endpoint in the player management module
+- Player data stored without any anonymization strategy for inactive accounts
+
+**Phase to address:** Phase 1 (player management) for anonymization model; Phase 3 (platform maturity) for full GDPR compliance workflow.
+
+---
+
+### Pitfall 12: Netbird Management Server as a Single Point of Failure
+
+**What goes wrong:**
+The Leaf node connects to the self-hosted Netbird management server to establish WireGuard peers. If the Netbird management server is down, new peer connections cannot be established. In practice, once WireGuard peers are established, they maintain connectivity without the management server. But initial Leaf node boot, new display node enrollment, and player PWA access (via reverse proxy) all require the management server. A Netbird server outage at the start of a tournament is a critical incident.
+
+**Why it happens:**
+The Netbird management server is treated as infrastructure rather than a critical dependency. It runs on a single LXC container on Proxmox. Single-container deployments have no redundancy. Developers assume "it's just networking" and don't plan for management plane failures.
+
+**How to avoid:**
+- Run Netbird management server with Proxmox backup jobs (PBS daily backup) so restoration is fast if the container fails.
+- Implement a startup procedure that verifies Netbird connectivity before marking the Leaf as ready for tournament use — surfaces infrastructure failures before they affect operations.
+- Once WireGuard peers are established on the Leaf and display nodes, they retain connectivity through management server outages (WireGuard doesn't need a control plane after handshake). Document this so staff know not to panic if the management UI is unreachable mid-tournament.
+- Consider running Netbird management on a separate, simpler VM rather than the same Proxmox host as other Core services — reduces correlated failure risk.
+
+**Warning signs:**
+- Netbird management server on the same LXC as other Core services (single failure domain)
+- No monitoring/alerting on management server health
+- New Leaf provisioning untested after simulated management server outage
+
+**Phase to address:** Phase 1 (infrastructure setup) — define the Netbird deployment topology before provisioning hardware.
+
+---
+
+### Pitfall 13: Player PWA Stale Service Worker Serving Old App Version
+
+**What goes wrong:**
+SvelteKit PWA service workers cache the application for offline use. When the operator deploys a new version of the player PWA, players who have the old version cached via service worker continue seeing the old app. If a new API contract is introduced (e.g., a new field in the tournament state WebSocket message), the old client silently ignores or mishandles it. In the worst case, an old client submits a rebuy request using the old API shape, which the new server rejects, and the player receives no feedback.
+
+**Why it happens:**
+Service worker update mechanics are subtle. The browser downloads the new service worker but doesn't activate it until all existing tabs running the old worker are closed. In a venue environment, players' phones keep the browser open throughout the tournament (for live clock viewing). The tab never closes, so the update never activates.
+
+**How to avoid:**
+- Configure the service worker to use `skipWaiting()` and `clients.claim()` to force immediate activation of new service worker versions — accept the tradeoff that this can disrupt in-flight requests.
+- Implement a version header in all API responses. The client checks the server version on every WebSocket connection and forces a full page reload if the versions diverge.
+- Use the `vite-pwa/sveltekit` plugin for zero-config PWA setup — it handles cache busting and update notifications correctly.
+- During development, test service worker update behavior explicitly: deploy a version, open the app, deploy again, verify the client updates without manual browser restart.
+
+**Warning signs:**
+- Players reporting "the clock stopped updating" after a deploy
+- API errors logged for requests with old field names/shapes after a schema change
+- Service worker version in browser devtools differs from current deploy
+
+**Phase to address:** Phase 1 (player PWA setup) — configure service worker update behavior before the PWA goes live.
+
+---
+
+## Technical Debt Patterns
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| Store prize pool as `float64` | Faster initial implementation | Cent-level rounding errors, reconciliation failures | Never |
+| Skip WAL checkpoint configuration | Works fine in dev | WAL grows unbounded under tournament load, write stalls | Never |
+| Copy NATS default config | Fast bootstrap | Data loss on power failure | Never for financial events |
+| Hard-code venue ID (single-tenant) | Simplifies first version | Full schema migration to add multi-tenancy later | Only for pre-alpha validation |
+| Use `SET` instead of `SET LOCAL` for RLS tenant | Slightly simpler code | Cross-tenant data leak in connection pool | Never |
+| Skip Pi Zero 2W hardware testing | Faster UI iteration | Memory issues only discovered in production | Never — test on target hardware early |
+| Auto-apply table rebalancing | Faster UX | Incorrect moves enforced without operator awareness | Never in a live tournament |
+| Mock Netbird/WireGuard in dev | Faster development cycle | Networking issues only found at venue deployment | Acceptable in unit test phase; must integration-test before deploy |
+
+---
+
+## Integration Gotchas
+
+| Integration | Common Mistake | Correct Approach |
+|-------------|----------------|------------------|
+| NATS embedded server | Copy quickstart config with default `sync_interval` | Set `sync_interval: always` in the embedded server options struct before starting |
+| LibSQL cloud sync | Initiate sync inside an open write transaction | Gate sync behind a mutex; never overlap sync with write transaction |
+| LibSQL + Go | Use `mattn/go-sqlite3` CGO driver | Evaluate `modernc.org/sqlite` (CGO-free) or LibSQL's own Go driver — verify CGO requirement for ARM64 cross-compile |
+| PostgreSQL RLS | Use `SET app.tenant_id` (session-scoped) | Use `SET LOCAL app.tenant_id` inside every transaction |
+| Netbird reverse proxy | Route all player PWA traffic through management server | Use Netbird's peer-to-peer WireGuard path; management server is only for control plane |
+| SvelteKit service worker | Use default Workbox cache-first strategy for API calls | Use network-first for API responses, cache-first only for static assets |
+| Chromium kiosk on Pi Zero 2W | No memory limits, default flags | Set `--max-old-space-size=256`, enable `zram`, use systemd `MemoryMax` |
+| Go WebSocket | Multiple goroutines writing to the same connection | Single dedicated send goroutine per connection; other goroutines push to a channel |
+
+---
+
+## Performance Traps
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| Unbounded WAL growth | Reads slow down as WAL grows; checkpoint stalls block writes | Manual checkpoint scheduling, `journal_size_limit` pragma | > 50 concurrent writes without checkpoint, or after 2-hour tournament |
+| Pi Zero 2W memory leak in display | Display goes blank mid-tournament | Explicit listener cleanup, memory profiling on target hardware | After 60-90 minutes of continuous display operation |
+| NATS consumer storm on reconnect | All clients subscribe simultaneously after Leaf restart, overwhelming broker | Implement jittered reconnect backoff (50-500ms random) | > 20 concurrent display/player clients reconnecting simultaneously |
+| Full RLS policy evaluation on every query | Slow queries as tournament grows | Index the `tenant_id` column; keep RLS policies simple (avoid JOINs in policy) | > 10,000 player records per venue |
+| Broadcasting entire tournament state on every WebSocket message | Bandwidth spike on player PWA reconnect | Send deltas (only changed fields) after initial full-state sync | > 50 concurrent player PWA connections |
+
+---
+
+## Security Mistakes
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| Storing player PII without encryption on Leaf | GDPR violation if device lost/stolen | LUKS full-disk encryption on NVMe (planned — verify it's in provisioning scripts) |
+| Reusable Netbird enrollment key for all Leaf nodes | If key leaks, attacker can enroll rogue devices | Use one-time enrollment keys per Leaf node; rotate after provisioning |
+| RLS bypass via direct database connection | Venue A reads venue B's data if DB credentials leak | Restrict DB user to application role only; no superuser credentials in app connection string |
+| PIN authentication without rate limiting | Brute-force PIN in offline mode | Implement exponential backoff after 5 failed PIN attempts, lockout after 10 |
+| Serving player PWA over HTTP (non-HTTPS) | Service workers require HTTPS; also exposes player data | All player-facing endpoints must terminate TLS (Netbird reverse proxy with Let's Encrypt) |
+
+---
+
+## UX Pitfalls
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| Auto-applying table rebalancing moves without confirmation | Operators don't know why players are being moved; incorrect moves go unchallenged | Always show proposed moves, require tap-to-confirm before executing |
+| Tournament clock not visible on dark screens in a dim poker room | Operators squint, miss blind level changes | Dark-room-first design from day one: minimum 18pt font for clock, high contrast ratios > 7:1, Catppuccin Mocha base |
+| Player PWA showing stale chip counts after reconnect | Players see incorrect stack sizes, distrust the platform | Show "last updated X seconds ago" indicator; force full resync on reconnect |
+| Sound events playing at maximum volume | Dealers and players startled; venue disruption | Per-venue configurable volume, default to 50%, fade-in for alerts |
+| Prize payout screen not showing running total vs. paid out total | Operator makes payout errors when managing multiple players simultaneously | Show real-time "remaining to pay out" counter on payout screen |
+
+---
+
+## "Looks Done But Isn't" Checklist
+
+- [ ] **Tournament clock:** Verify pause/resume correctly adjusts all time-based triggers (blind level end, break start) — not just the display counter
+- [ ] **Prize pool:** Verify sum of all individual payouts equals prize pool total (run automated reconciliation test)
+- [ ] **Table rebalancing:** Verify algorithm handles all TDA edge cases: last 2-player table, dealer button seat, player in blind position
+- [ ] **Offline mode:** Verify full tournament can run (including rebuys, bust-outs, level changes) with internet completely disconnected for 4+ hours
+- [ ] **Display node restart:** Verify display node automatically rejoins and resumes correct view after reboot without operator intervention
+- [ ] **NATS replay:** Verify all queued events replay correctly after Leaf comes back online after 8+ hours offline
+- [ ] **RLS isolation:** Verify API endpoints return 0 results (not 403) for valid venue A token querying venue B data — 403 leaks resource existence
+- [ ] **GDPR erasure:** Verify player PII deletion does not delete tournament result records (anonymize, don't delete)
+- [ ] **NATS fsync:** Verify `sync_interval: always` is in the deployed Leaf configuration (not just development)
+- [ ] **Pi Zero memory:** Verify display node shows no memory growth after 4-hour continuous tournament with `/usr/bin/free -m` monitoring
+
+---
+
+## Recovery Strategies
+
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| NATS data loss (wrong fsync default in production) | HIGH | Restore from last backup; replay any manually recorded tournament events; accept some data loss |
+| SQLite corruption after power loss | MEDIUM | LibSQL can often repair WAL with `PRAGMA integrity_check`; if not, restore from daily backup |
+| Prize pool floating-point error discovered post-tournament | HIGH | Manual audit of all transactions; correction requires agreement of all players involved |
+| RLS cross-tenant data leak | HIGH | Immediate incident response; audit logs for all affected queries; notify affected venues per GDPR breach requirements (72-hour deadline) |
+| Pi Zero display failure mid-tournament | LOW | Display nodes are stateless — reboot restores operation within 60 seconds; have spare Pi Zero on-site |
+| Table rebalancing error (player moved incorrectly) | MEDIUM | Manual seat correction via operator UI; document as a tournament irregularity in audit log |
+| Service worker serving stale PWA | LOW | Force browser refresh (player gesture); if critical, add server-side cache-busting header |
+
+---
+
+## Pitfall-to-Phase Mapping
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| NATS default fsync data loss | Phase 1 (NATS setup) | Integration test: write 100 events, power-cycle Leaf, verify all 100 replay correctly |
+| LibSQL WAL checkpoint stall | Phase 1 (database initialization) | Load test: 500 writes/min for 2 hours, monitor WAL file size stays bounded |
+| Offline sync financial conflict | Phase 1 (financial engine architecture) | Conflict test: process rebuy offline, simulate late online event with same sequence, verify ledger correctness |
+| Pi Zero memory exhaustion | Phase 1 (display node MVP) | Soak test: run display on actual Pi Zero 2W hardware for 4 hours, monitor RSS |
+| Table rebalancing algorithm | Phase 1 (seating engine) | Unit tests covering all TDA edge cases (min 20 cases); load test with simulated 40-table tournament |
+| Multi-tenant RLS data leak | Phase 1 (Core backend) | Security test: verify all 30+ API endpoints return correct tenant-scoped data only |
+| Float arithmetic in financials | Phase 1 (financial engine) | Automated test: sum of payouts must equal prize pool (run as CI gate) |
+| ARM64 CGO cross-compile | Phase 1 (build system) | CI gate: ARM64 binary builds successfully and passes smoke test on Orange Pi 5 Plus |
+| WebSocket state desync | Phase 1 (real-time sync) | Chaos test: restart Leaf server mid-tournament, verify all clients resync within 5 seconds |
+| SBC power loss data corruption | Phase 1 (infrastructure) | Chaos test: hard-power-cycle Leaf mid-tournament 10 times, verify restart always recovers cleanly |
+| GDPR compliance | Phase 1 (player management) + Phase 3 | Verify: right-to-erasure API anonymizes PII, preserves results; audit trail shows all PII access |
+| Netbird management SPOF | Phase 1 (infrastructure design) | Test: take Netbird management offline, verify existing WireGuard peers retain connectivity |
+| PWA stale service worker | Phase 1 (PWA setup) | Test: deploy v1, open app, deploy v2, verify client shows v2 without manual browser restart |
+
+---
+
+## Sources
+
+- [NATS JetStream Anti-Patterns for Scale — Synadia](https://www.synadia.com/blog/jetstream-design-patterns-for-scale) (MEDIUM confidence — official vendor blog)
+- [Jepsen: NATS 2.12.1 — jepsen.io](https://jepsen.io/blog/2025-12-08-nats-2.12.1) (HIGH confidence — independent analysis, Dec 2025)
+- [NATS JetStream loses acknowledged writes by default — GitHub Issue #7564](https://github.com/nats-io/nats-server/issues/7564) (HIGH confidence — official tracker)
+- [Downsides of Local First / Offline First — RxDB](https://rxdb.info/downsides-of-offline-first.html) (MEDIUM confidence — library author perspective)
+- [SQLite Write-Ahead Logging — sqlite.org](https://sqlite.org/wal.html) (HIGH confidence — official documentation)
+- [LibSQL Embedded Replicas Data Corruption — GitHub Discussion #1910](https://github.com/tursodatabase/libsql/discussions/1910) (HIGH confidence — official tracker)
+- [Turso Offline Sync Public Beta](https://turso.tech/blog/turso-offline-sync-public-beta) (MEDIUM confidence — vendor announcement)
+- [PostgreSQL RLS Implementation Guide — permit.io](https://www.permit.io/blog/postgres-rls-implementation-guide) (MEDIUM confidence — verified against AWS prescriptive guidance)
+- [Multi-tenant Data Isolation with PostgreSQL RLS — AWS](https://aws.amazon.com/blogs/database/multi-tenant-data-isolation-with-postgresql-row-level-security/) (HIGH confidence — official AWS documentation)
+- [Floats Don't Work for Storing Cents — Modern Treasury](https://www.moderntreasury.com/journal/floats-dont-work-for-storing-cents) (HIGH confidence — multiple corroborating sources)
+- [SQLite WAL Checkpoint Starvation — sqlite-users](https://sqlite-users.sqlite.narkive.com/muT0rMYt/sqlite-wal-checkpoint-starved) (MEDIUM confidence — community discussion)
+- [Chromium on Pi Zero 2W memory constraints — Raspberry Pi Forums](https://forums.raspberrypi.com/viewtopic.php?t=326222) (MEDIUM confidence — community-verified)
+- [NetBird 2025 Guide: 5 Critical Mistakes](https://junkangworld.com/blog/your-2025-netbird-guide-5-critical-mistakes-to-avoid) (LOW confidence — third-party blog, verify against official docs)
+- [SvelteKit Service Workers — official docs](https://kit.svelte.dev/docs/service-workers) (HIGH confidence — official documentation)
+- [The Tournament Director — known bugs changelog](https://thetournamentdirector.net/changes.txt) (HIGH confidence — official changelog)
+- [Poker TDA Rules 2013 — table balancing procedures](https://www.pokertda.com/wp-content/uploads/2013/08/Poker_TDA_Rules_2013_Version_1.1_Final_handout_PDF_redlines_from_2011_Rules.pdf) (MEDIUM confidence — check against current TDA ruleset)
+- [GDPR compliance for gaming/gambling operators — GDPR Local](https://gdprlocal.com/gdpr-compliance-online-casinos-betting-operators/) (MEDIUM confidence — legal advisory blog, not authoritative)
+
+---
+*Pitfalls research for: edge-cloud poker venue management platform (Felt)*
+*Researched: 2026-02-28*

.planning/research/STACK.md

@@ -0,0 +1,278 @@
+# Stack Research
+
+**Domain:** Edge-cloud poker venue management platform (ARM64 SBC + cloud hybrid)
+**Researched:** 2026-02-28
+**Confidence:** MEDIUM-HIGH (core stack verified via official sources; peripheral libraries verified via pkg.go.dev and GitHub releases; CGO cross-compilation complexity is a known risk requiring phase-specific validation)
+
+---
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| Go | 1.26 | Backend runtime (Leaf + Core shared codebase) | Single binary deployment, ARM64 cross-compilation, goroutine concurrency for real-time tournament state, excellent stdlib HTTP. Released Feb 10, 2026. |
+| SvelteKit | 2.53.x | Operator UI, player PWA, admin dashboard | Single codebase for SPA, SSR, and PWA modes. SvelteKit 2 + Svelte 5 runes are production-stable. Adapter-static for Go embed, adapter-node for standalone. |
+| Svelte | 5.53.x | Frontend framework | Runes reactivity model ($state, $derived, $effect) handles high-frequency real-time data (100ms tournament clock) without store complexity. Svelte 5 stable since Oct 2024. |
+| NATS Server | 2.12.4 | Embedded message broker on Leaf; clustered on Core | Embeds directly into Go binary (~10MB RAM overhead), JetStream provides offline-durable queuing, ordered replay on reconnect, KV store. ARM64 native packages available. |
+| LibSQL (go-libsql) | unreleased / CGO | Embedded SQLite-compatible DB on Leaf | SQLite-compatible with built-in replication support. Supports linux/arm64 natively via precompiled binaries. CGO_ENABLED=1 required. |
+| PostgreSQL | 16 | Relational DB on Core | Standard choice for Core; multi-tenant RLS, full-text search for player lookup, proven at scale. LibSQL mirrors for sync path. |
+| Tailwind CSS | 4.x | UI styling | v4 uses Vite plugin (no PostCSS config needed), 100x faster incremental builds, CSS-native config. Pairs naturally with SvelteKit's Vite build pipeline. |
+| Netbird | latest | WireGuard mesh overlay network | Self-hosted, provides mesh VPN + reverse proxy + DNS + SSH + firewall policies in one platform. Zero-config peer connection through NAT. ARM64 client supported. |
+| Authentik | 2026.2.x | Self-hosted OIDC Identity Provider | Integrates natively with Netbird self-hosted. Provides SSO for operator login, LDAP fallback, Apache 2.0. Requires PostgreSQL + Redis; runs in LXC on Core. |
+
+### Supporting Libraries — Go Backend
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| github.com/go-chi/chi/v5 | v5.2.5 | HTTP router | All Leaf and Core HTTP handlers. Lightweight, fully net/http compatible, composable middleware, no magic. |
+| github.com/nats-io/nats.go | v1.49.0 | NATS client (JetStream API) | Publishing, consuming, and managing JetStream streams from application code. Uses the new jetstream sub-package API. |
+| github.com/nats-io/nats-server/v2 | v2.12.4 | Embedded NATS server | Leaf embeds this directly via server.NewServer() + EnableJetStream(). Not used on Core (standalone server process). |
+| github.com/pressly/goose/v3 | v3.27.0 | Database migrations | Runs schema migrations at startup via embed.FS. Supports SQLite + PostgreSQL with same migration files. |
+| github.com/sqlc-dev/sqlc | v1.30.0 | Type-safe SQL code generation | Generate Go structs and query functions from raw SQL. Eliminates ORM overhead, keeps SQL as SQL. |
+| github.com/coder/websocket | v1.8.14 | WebSocket server | Real-time push to operator UI and player PWA. Actively maintained successor to nhooyr/websocket. Context-aware, zero-allocation. |
+| github.com/golang-jwt/jwt/v5 | latest | JWT token handling | Offline PIN-based auth on Leaf (no network dependency). Validates tokens from Authentik OIDC on Core. |
+| go.opentelemetry.io/otel | 1.x | Observability | Structured tracing for state machine transitions, tournament operations. Add otelchi for per-request span creation. |
+| github.com/riandyrn/otelchi | latest | OpenTelemetry middleware for chi | Automatic HTTP span creation. Plug into chi middleware chain. |
+
+### Supporting Libraries — SvelteKit Frontend
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| @vite-pwa/sveltekit | latest | PWA + service worker | Player PWA offline caching, installable shell. Wraps Workbox. Required for offline player access. |
+| vite-plugin-pwa | latest | PWA build tooling | Underlying PWA config for manifest, service worker generation. |
+| @tailwindcss/vite | 4.x | Tailwind v4 Vite integration | Add before sveltekit() in vite.config. CSS-native config via app.css @import "tailwindcss". |
+| svelte-sonner | latest | Toast notifications | Operator action feedback (seat assignments, registration, bust-outs). Lightweight, accessible. |
+| @lucide/svelte | latest | Icon set | Consistent iconography. Tree-shakeable, Svelte-native bindings. |
+
+### Development Tools
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| Task (Taskfile) | Build orchestration | Define `build:leaf`, `build:core`, `build:frontend`, `cross-compile:arm64` tasks. Replaces Makefile with YAML syntax. |
+| Docker buildx | ARM64 cross-compilation | For CGO-enabled builds targeting linux/arm64. Use `--platform linux/arm64` with aarch64-linux-gnu-gcc cross-compiler in container. |
+| air | Go live reload (dev) | `github.com/air-verse/air` — watches Go files, rebuilds on change. Dev only. |
+| golangci-lint | Go linting | Runs multiple linters. Critical for enforcing error handling patterns in state machine code. |
+| playwright | E2E testing | Test operator UI flows. Svelte-compatible. |
+| sqlc | SQL → Go codegen | Run as part of build pipeline. Check generated files into git. |
+
+---
+
+## Installation
+
+### Go Backend
+
+```bash
+# Initialize module
+go mod init felt
+
+# Core router and middleware
+go get github.com/go-chi/chi/v5@v5.2.5
+go get github.com/go-chi/cors
+
+# NATS (client + embedded server)
+go get github.com/nats-io/nats.go@v1.49.0
+go get github.com/nats-io/nats-server/v2@v2.12.4
+
+# Database — LibSQL (CGO required)
+# Note: CGO_ENABLED=1 and linux/arm64 cross-compiler required for Leaf builds
+go get github.com/tursodatabase/go-libsql
+
+# Database — PostgreSQL for Core
+go get github.com/jackc/pgx/v5
+
+# Migrations and query gen
+go get github.com/pressly/goose/v3@v3.27.0
+# sqlc: install as tool
+go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.30.0
+
+# Auth
+go get github.com/golang-jwt/jwt/v5
+
+# WebSocket
+go get github.com/coder/websocket@v1.8.14
+
+# Observability
+go get go.opentelemetry.io/otel
+go get go.opentelemetry.io/otel/sdk
+go get github.com/riandyrn/otelchi
+```
+
+### SvelteKit Frontend
+
+```bash
+# Scaffold
+npx sv create felt-frontend
+# Choose: SvelteKit, TypeScript, Tailwind
+
+# Or manually:
+npm create svelte@latest felt-frontend
+
+# Tailwind v4
+npm install tailwindcss @tailwindcss/vite
+
+# PWA
+npm install -D @vite-pwa/sveltekit vite-plugin-pwa
+
+# UI libraries
+npm install svelte-sonner @lucide/svelte
+```
+
+---
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| chi (router) | Gin, Echo, Fiber | Gin if you want more batteries-included middleware and faster onboarding. Fiber if raw throughput benchmarks matter more than stdlib compatibility. Chi chosen here because it's pure net/http, no magic, easy to embed with NATS server in same binary. |
+| LibSQL (go-libsql) | mattn/go-sqlite3 | go-sqlite3 if you never need replication or remote sync. go-libsql is SQLite-compatible but adds replication capability needed for Leaf→Core sync path. |
+| LibSQL (go-libsql) | modernc.org/sqlite | modernc if CGO is unacceptable (pure Go, no cross-compile issues). Tradeoff: no replication, pure-Go performance is slower, and you lose LibSQL's sync protocol. |
+| goose | golang-migrate | golang-migrate is fine but goose has cleaner embed.FS support and the sqlc community uses it as the reference migration tool. |
+| coder/websocket | gorilla/websocket | gorilla/websocket if you need RFC 7455 edge cases or have existing gorilla-dependent code. gorilla is widely used but coder/websocket is the modern, context-aware successor. |
+| NATS JetStream | Redis Streams, RabbitMQ | Redis Streams if you already have Redis in the stack. RabbitMQ for complex enterprise routing. NATS chosen because it embeds in the Go binary (no separate process on Leaf), runs on 10MB RAM, and handles offline-queued replay natively. |
+| Authentik | Keycloak, Authelia | Keycloak if you need SAML federation or very large enterprise deployments. Authelia if you want lightweight forward-auth only. Authentik chosen for OIDC depth, active development, and documented Netbird integration. |
+| Tailwind CSS v4 | UnoCSS, vanilla CSS | UnoCSS if Tailwind v4's Rust engine still has edge-case gaps in your toolchain. Vanilla CSS with CSS custom properties if the design system is simple. Tailwind v4 chosen for its systematic utility classes matching the dense information design requirement. |
+| SvelteKit | React/Next.js, Vue/Nuxt | React/Next.js if you have an existing team with React expertise. SvelteKit chosen for smaller bundle sizes (critical for Pi Zero display nodes loading over WiFi), built-in PWA path, and Svelte 5 runes handling high-frequency clock updates without virtual DOM overhead. |
+
+---
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| gorilla/websocket (new code) | Unmaintained since 2023, no context support, no concurrent writes | github.com/coder/websocket (maintained successor) |
+| gorm | ORM magic hides SQL, bad for complex tournament state queries, generates inefficient queries, fights with LibSQL's CGO interface | sqlc for generated type-safe queries, raw database/sql when needed |
+| modernc.org/sqlite for Leaf | Pure-Go SQLite has no replication — you lose the LibSQL sync protocol that enables Leaf→Core data replication | tursodatabase/go-libsql (CGO, linux/arm64 prebuilt) |
+| React/Next.js | Heavy bundle — Pi Zero 2W (512MB RAM) running Chromium kiosk will struggle; Svelte compiles to vanilla JS with no runtime | SvelteKit + Svelte 5 |
+| Svelte 4 / SvelteKit 1 | End of active development; Svelte 5 runes are the current API; v4 stores pattern has known SSR shared-state bugs | Svelte 5 + SvelteKit 2 |
+| Tailwind CSS v3 | Requires PostCSS config, slower builds, JS-based config. v4 drops all of this and integrates cleaner with Vite | Tailwind CSS v4 with @tailwindcss/vite plugin |
+| OIDC-only auth on Leaf | If Core/internet is down, OIDC token validation fails → operators locked out | JWT-based offline PIN auth on Leaf, OIDC only when online |
+| Global Netbird cloud | Introduces Netbird as a third-party MITM for network control plane | Self-hosted Netbird management server on Core (Hetzner Proxmox LXC) |
+| Docker on Leaf (ARM64) | Docker daemon adds ~100MB RAM overhead on a 4-8GB device; unnecessary abstraction for a dedicated appliance | Bare systemd services; Go single binary + SvelteKit embedded build |
+
+---
+
+## Stack Patterns by Variant
+
+**For Leaf Node (ARM64 SBC, offline-first):**
+- Go binary with embedded NATS server + JetStream store on NVMe
+- LibSQL (go-libsql, CGO) with goose migrations at startup
+- SvelteKit build embedded via `//go:embed all:build` in Go binary
+- Single systemd service: `felt-leaf`
+- Offline PIN auth via JWT; Authentik OIDC optional when online
+- CGO cross-compile: `GOOS=linux GOARCH=arm64 CGO_ENABLED=1 CC=aarch64-linux-gnu-gcc go build`
+
+**For Core Node (Hetzner Proxmox LXC, always-online):**
+- Go binary (no embedded NATS — connects to standalone NATS cluster)
+- PostgreSQL (pgx/v5 driver)
+- NATS JetStream cluster for multi-venue message routing
+- Authentik + Netbird management server as separate LXC containers
+- Standard AMD64 build: `GOOS=linux GOARCH=amd64 go build`
+
+**For Display Nodes (Pi Zero 2W, Chromium kiosk):**
+- No custom software on the node itself
+- Raspberry Pi OS Lite + X11 + Chromium in `--kiosk` mode
+- Chromium points to `http://leaf.local/display/{node-id}` (served by Leaf Go binary)
+- Display content is pure SvelteKit SPA pages served from the Leaf
+- Node management (which view to show) handled via NATS KV on Leaf
+
+**If CGO cross-compilation proves painful in CI:**
+- Use Docker buildx with `FROM --platform=linux/arm64` base and native arm64 runner
+- OR accept CGO complexity and use `aarch64-linux-gnu-gcc` in a standard amd64 CI runner
+- Do NOT switch to modernc.org/sqlite — losing replication is worse than cross-compile friction
+
+---
+
+## Version Compatibility
+
+| Package | Compatible With | Notes |
+|---------|-----------------|-------|
+| go-libsql (unreleased) | Go 1.26, linux/arm64 | No tagged releases; pin to commit hash in go.mod. CGO_ENABLED=1 mandatory. |
+| @vite-pwa/sveltekit | SvelteKit 2.x, Vite 5.x | From v0.3.0+ supports SvelteKit 2. |
+| goose v3.27.0 | Go 1.25+ | Requires Go 1.25 minimum per v3.27.0 release notes. Go 1.26 is compatible. |
+| chi v5.2.5 | Go 1.22+ | Standard net/http; any Go 1.22+ supported. |
+| Tailwind v4 | Vite 5.x, SvelteKit 2.x | @tailwindcss/vite must be listed before sveltekit() in vite.config plugins array. |
+| NATS server v2.12.4 | nats.go v1.49.0 | Use matching client and server versions. Server v2.12.x is compatible with client v1.49.x. |
+| Svelte 5.53.x | SvelteKit 2.53.x | Must use matching Svelte 5 + SvelteKit 2. Svelte 4 / SvelteKit 1 are not compatible targets. |
+
+---
+
+## Critical Build Notes
+
+### LibSQL CGO Cross-Compilation
+
+go-libsql has no tagged releases on GitHub. You must pin to a specific commit:
+
+```bash
+go get github.com/tursodatabase/go-libsql@<commit-hash>
+```
+
+Cross-compilation for ARM64 requires the GNU cross-compiler toolchain:
+
+```bash
+# On Ubuntu/Debian CI
+apt-get install gcc-aarch64-linux-gnu
+
+# Build command
+GOOS=linux GOARCH=arm64 CGO_ENABLED=1 \
+  CC=aarch64-linux-gnu-gcc \
+  go build -o felt-leaf ./cmd/leaf
+```
+
+Alternative (recommended for CI consistency): Use Docker buildx with an ARM64 base image to build natively, avoiding cross-compiler dependency management.
+
+### SvelteKit Static Embed in Go Binary
+
+```go
+//go:embed all:frontend/build
+var frontendFS embed.FS
+
+// In HTTP handler:
+sub, _ := fs.Sub(frontendFS, "frontend/build")
+http.FileServer(http.FS(sub))
+```
+
+SvelteKit must be built with `@sveltejs/adapter-static` for full embed. The Leaf serves all frontend assets from its single binary — no separate static file server.
+
+### NATS Embedded Server Setup
+
+```go
+opts := &server.Options{
+    Port:      4222,
+    Host:      "127.0.0.1",
+    JetStream: true,
+    StoreDir:  "/data/nats/jetstream",  // on NVMe
+}
+ns, err := server.NewServer(opts)
+ns.Start()
+nc, _ := nats.Connect(ns.ClientURL())
+js, _ := jetstream.New(nc)
+```
+
+---
+
+## Sources
+
+- Go 1.26 release: https://go.dev/blog/go1.26 — HIGH confidence
+- NATS Server v2.12.4: https://github.com/nats-io/nats-server/releases — HIGH confidence (official)
+- NATS server embed API: https://pkg.go.dev/github.com/nats-io/nats-server/v2/server — HIGH confidence
+- nats.go v1.49.0: https://github.com/nats-io/nats.go/releases — HIGH confidence
+- go-libsql ARM64 support: https://github.com/tursodatabase/go-libsql — HIGH confidence (official repo)
+- chi v5.2.5: https://github.com/go-chi/chi/tree/v5.2.3 + pkg.go.dev — HIGH confidence
+- goose v3.27.0: https://pkg.go.dev/github.com/pressly/goose/v3 + releases — HIGH confidence
+- sqlc v1.30.0: https://github.com/sqlc-dev/sqlc/releases — HIGH confidence
+- coder/websocket v1.8.14: https://github.com/coder/websocket — HIGH confidence
+- SvelteKit 2.53.2: https://www.npmjs.com/package/@sveltejs/kit — HIGH confidence
+- Svelte 5.53.5: https://www.npmjs.com/package/svelte — HIGH confidence
+- Tailwind v4 Vite integration: https://tailwindcss.com/docs/guides/sveltekit — HIGH confidence
+- @vite-pwa/sveltekit: https://github.com/vite-pwa/sveltekit — MEDIUM confidence (version not pinned)
+- Authentik Netbird integration: https://docs.netbird.io/selfhosted/identity-providers/authentik — MEDIUM confidence
+- CGO ARM64 cross-compilation: https://forum.golangbridge.org/t/cross-compiling-go-with-cgo-for-arm64/38794 — MEDIUM confidence (community)
+- Go embed + SvelteKit: https://www.liip.ch/en/blog/embed-sveltekit-into-a-go-binary — MEDIUM confidence (verified pattern, widely cited)
+- Pi Zero 2W Chromium kiosk: https://gist.github.com/lellky/673d84260dfa26fa9b57287e0f67d09e — MEDIUM confidence
+
+---
+
+*Stack research for: Felt — Edge-cloud poker venue management platform*
+*Researched: 2026-02-28*

.planning/research/SUMMARY.md

@@ -0,0 +1,263 @@
+# Project Research Summary
+
+**Project:** Felt — Edge-cloud poker venue management platform
+**Domain:** Live venue poker operations (ARM64 SBC + cloud hybrid, offline-first)
+**Researched:** 2026-02-28
+**Confidence:** MEDIUM-HIGH
+
+## Executive Summary
+
+Felt is a three-tier edge-cloud platform for managing live poker venues: tournament operations, cash game management, player tracking, and digital display signage. The competitive landscape (TDD, Blind Valet, BravoPokerLive, LetsPoker) reveals a clear gap — no single product combines offline-first reliability, wireless display management, cloud sync, and modern UX. Experts in this domain build tournament state machines as pure functions with an append-only event log backing financial calculations, and treat offline operation as a first-class architectural constraint rather than a fallback. The recommended approach is a Go monorepo with shared domain logic compiled to two targets: an ARM64 Leaf binary for venue hardware and an amd64 Core binary for the cloud tier, connected via NATS JetStream leaf-node mirroring over a WireGuard mesh.
+
+The primary technical risk is the intersection of offline-first requirements with financial correctness. Financial mutations (buy-ins, rebuys, prize pool splits) must be modelled as an immutable append-only event log using integer arithmetic — not mutable rows or floating-point values. Any deviation from this is not recoverable post-production without manual audit and player agreement. The second major risk is CGO cross-compilation complexity introduced by the LibSQL Go driver; this must be validated in CI from day one. A third risk is NATS JetStream's default `sync_interval` which does not guarantee durability on power loss — requiring an explicit configuration override before any production deployment.
+
+The architecture is well-validated: Go's single-binary embed model (SvelteKit built assets embedded via `go:embed`) eliminates deployment complexity on ARM hardware; NATS JetStream's leaf-node domain isolation provides clean offline queuing with replay; PostgreSQL RLS provides multi-tenant isolation on Core; Pi Zero 2W display nodes are stateless Chromium kiosk consumers, not managed agents. The main uncertainty is around LibSQL's go-libsql driver (no tagged releases, pinned to commit hash) and the Netbird reverse proxy beta status, both of which require early integration testing to validate before committing to downstream features.
+
+## Key Findings
+
+### Recommended Stack
+
+The stack is a Go + SvelteKit monorepo targeting two runtimes. Go 1.26 provides single-binary deployment, native ARM64 cross-compilation, and goroutine-based concurrency for real-time tournament clock management. SvelteKit 2 + Svelte 5 runes handle all frontends (operator UI, player PWA, display views, public pages) with Svelte 5's runes reactivity model handling 100ms clock updates without virtual DOM overhead. NATS Server 2.12.4 is embedded in the Leaf binary (~10MB RAM) and runs as a standalone cluster on Core; JetStream provides durable event queuing with offline store-and-forward replay. LibSQL (go-libsql, CGO-required) is the embedded database on Leaf; PostgreSQL 16 with row-level security is the multi-tenant store on Core. Netbird + Authentik provide self-hosted WireGuard mesh networking and OIDC identity.
+
+**Core technologies:**
+- Go 1.26: Backend runtime for both Leaf and Core — single binary, ARM64 native, goroutine concurrency for real-time state
+- SvelteKit 2 + Svelte 5: All frontends — operator UI, player PWA, display views, public pages served from embedded Go binary
+- NATS JetStream 2.12.4: Embedded message broker on Leaf + hub cluster on Core — durable offline-first event sync with store-and-forward replay
+- LibSQL (go-libsql): Embedded SQLite-compatible DB on Leaf — offline-first authoritative state store with WAL mode
+- PostgreSQL 16: Multi-tenant relational store on Core — RLS tenant isolation, cross-venue aggregation, league management
+- Netbird (WireGuard mesh): Zero-config peer networking — reverse proxy for player PWA external access, encrypted tunnel for Core sync
+- Authentik: Self-hosted OIDC identity provider — operator SSO with offline PIN fallback, integrates with Netbird
+
+**Critical version notes:**
+- go-libsql has no tagged releases; pin to commit hash in go.mod
+- NATS server v2.12.4 must match nats.go v1.49.0 client
+- Tailwind CSS v4 requires `@tailwindcss/vite` plugin listed before `sveltekit()` in vite.config
+- CGO_ENABLED=1 required for LibSQL; ARM64 cross-compilation needs `aarch64-linux-gnu-gcc`
+
+### Expected Features
+
+The MVP must replace TDD (The Tournament Director) and a whiteboard for a single-venue operator running a complete tournament. Competitive analysis confirms no product combines offline reliability with wireless displays and cloud sync — this is the primary differentiation window.
+
+**Must have (table stakes) — P1:**
+- Tournament clock engine (countdown, levels, breaks, pause/resume) — the core product job
+- Configurable blind structures with presets, antes, chip-up messaging, and break config
+- Player registration, bust-out tracking, rebuy/add-on/late registration handling
+- Prize pool calculation and payout structure (ICM, fixed %, custom splits)
+- Table seating assignment (random + manual) and automated table balancing
+- Display system: clock view and seating view on dedicated screens (wireless)
+- Player mobile PWA: live clock, blinds, personal rank — QR code access, no install
+- Offline-first operation — zero internet dependency during tournament
+- Role-based auth: operator PIN offline, OIDC online
+- TDD data import: blind structures and player database
+- Data export: CSV, JSON, HTML print output
+
+**Should have (competitive advantage) — P2:**
+- Cash game: waitlist management, table status board, session/rake tracking, must-move logic
+- Events engine: rule-based automation ("level advance → play sound, change display view")
+- League/season management with configurable point formulas
+- Hand-for-hand bubble mode per TDA rules
+- Dealer tablet module for bust-outs and rebuys at the table
+- Seat-available notifications (push/SMS)
+- Digital signage content system with playlist scheduling
+
+**Defer (v2+) — P3:**
+- WYSIWYG content editor and AI promo generation
+- Dealer management and staff scheduling
+- Player loyalty/points system
+- Public venue presence page with online event registration
+- Analytics dashboards (revenue, retention, game popularity)
+- Native iOS/Android apps — PWA covers use case until then
+- Cross-venue player leaderboards — requires network effect
+
+**Anti-features (do not build):**
+- Payment processing or chip cashout — PCI/gambling license complexity
+- Online poker gameplay — different product entirely
+- BYO hardware support — undermines offline guarantees, support burden
+- Real-money gambling regulation features — jurisdiction-specific legal maintenance
+
+### Architecture Approach
+
+The architecture is a three-tier model: Cloud Core (Hetzner Proxmox LXC, amd64), Edge Leaf (Orange Pi 5 Plus ARM64 SBC, NVMe), and Display Tier (Raspberry Pi Zero 2W Chromium kiosk). The Leaf node is the authoritative operational unit — all tournament writes happen to LibSQL first, domain events are published to a local NATS JetStream stream, and the Hub broadcasts state deltas to all WebSocket clients within ~10ms. NATS mirrors the local stream to Core asynchronously over WireGuard, providing offline store-and-forward sync with per-subject ordering guarantees. Core is an analytics/aggregation/cross-venue target only — never a write-path dependency.
+
+**Major components:**
+1. Go Leaf API — tournament engine (pure domain logic, no I/O), financial engine, seating engine, WebSocket hub, REST/WS API; single ARM64 binary with embedded NATS + LibSQL + SvelteKit assets
+2. Go Core API — multi-tenant aggregation, cross-venue leagues, player platform identity; PostgreSQL with RLS, NATS hub cluster
+3. NATS JetStream (Leaf → Core) — leaf-node domain isolation, store-and-forward mirroring, append-only event audit log; doubles as sync mechanism and audit trail
+4. WebSocket Hub — per-client goroutine send channels, central broadcast channel; non-blocking drop for slow clients; in-process pub/sub triggers
+5. Display Tier — stateless Pi Zero 2W kiosk nodes; view assignment stored on Leaf (not on node); Chromium kiosk subscribes to assigned view URL via WebSocket; operator reassigns view through Hub broadcast
+6. Netbird Mesh — WireGuard peer-to-peer tunnels; reverse proxy for player PWA HTTPS access; Authentik OIDC for operator auth when online
+
+**Key architecture rules:**
+- Leaf is always the authoritative write target; Core is read/aggregation only
+- Financial events are immutable append-only log; prize pool is derived, never stored
+- All monetary values stored as int64 cents — never float64
+- Display nodes are stateless; view assignment is Leaf state, not node state
+- Single Go monorepo with shared `internal/` packages; `cmd/leaf` and `cmd/core` are the only divergence points
+
+### Critical Pitfalls
+
+1. **NATS JetStream default fsync causes data loss on power failure** — Set `sync_interval: always` in the embedded NATS server config before first production deploy. The December 2025 Jepsen analysis confirmed NATS 2.12.1 loses acknowledged writes with default settings. Tournament events are low-frequency so the throughput tradeoff is irrelevant.
+
+2. **Float64 arithmetic corrupts prize pool calculations** — Store and compute all monetary values as `int64` cents. Percentage payouts use integer multiplication-then-division. Write a CI gate test: sum of individual payouts must equal prize pool total. This is a zero-compromise constraint — floating-point errors in production require manual audit and player agreement to resolve.
+
+3. **LibSQL WAL checkpoint stall causes clock drift** — Disable autocheckpoint (`PRAGMA wal_autocheckpoint = 0`), schedule explicit `PRAGMA wal_checkpoint(TRUNCATE)` during level transitions and breaks. Set `journal_size_limit` to 64MB. Gate LibSQL cloud sync behind a mutex with the write path — never overlap sync with an active write transaction.
+
+4. **Pi Zero 2W memory exhaustion crashes display mid-tournament** — Test ALL display views on actual Pi Zero 2W hardware from day one, not a Pi 4. Enable zram (~200MB effective headroom). Set `--max-old-space-size=256` Chromium flag. Use systemd `MemoryMax=450M` with `Restart=always`. Consider Server-Sent Events instead of WebSocket for display-only views to reduce connection overhead.
+
+5. **Table rebalancing algorithm produces invalid seating** — Implement rebalancing as a pure function returning a proposed move list, never auto-applied. Consult Poker TDA Rules 25-28. Unit test exhaustively: last 2-player table, dealer button position, player in blind position. Require operator tap-to-confirm before executing any move. Never silently apply balance suggestions.
+
+6. **PostgreSQL RLS tenant isolation bleeds between connections** — Always use `SET LOCAL app.tenant_id = $1` (transaction-scoped), never session-scoped `SET`. Assert `current_setting('app.tenant_id')` matches JWT claim before every query. Write integration tests verifying venue A token returns 0 results (not 403) for venue B endpoints.
+
+7. **Offline sync conflict corrupts financial ledger** — Financial events must be immutable with monotonic sequence numbers assigned by the Leaf. Never use wall-clock timestamps for event ordering (SBC clock drift is real). Surface genuine conflicts in the operator UI rather than auto-merging.
+
+## Implications for Roadmap
+
+Research strongly supports the five-phase build order identified in ARCHITECTURE.md, with one critical addition: financial engine correctness and infrastructure hardening must be established before any frontend work begins.
+
+### Phase 1: Foundation — Leaf Core Infrastructure
+
+**Rationale:** The Leaf node is the architectural foundation everything else depends on. Tournament engine, financial engine, and data layer correctness must be established in isolation before adding network layers or frontends. All seven Phase 1 critical pitfalls manifest here: NATS fsync, float arithmetic, WAL configuration, Pi Zero 2W memory, seating algorithm, RLS isolation, and offline sync conflict handling. None of these are retrofittable.
+
+**Delivers:** A working offline tournament system accessible via API. Operators can run a complete tournament (registration → clock → rebuys → bust-outs → payout) without any frontend UI, verifiable via API calls and automated tests.
+
+**Addresses (from FEATURES.md P1):** Tournament clock engine, blind structure config, player registration + bust-out, rebuy/add-on, prize pool calculation, table seating + balancing, financial engine, role-based auth, offline operation
+
+**Avoids:** NATS default fsync data loss, float arithmetic in financials, WAL checkpoint stall, offline sync financial conflict, table rebalancing invalid seating, Multi-tenant RLS data leak
+
+**Needs deeper research:** CGO cross-compilation pipeline (LibSQL ARM64 build); NATS JetStream embedded server wiring with domain isolation; go-libsql commit-pin strategy given no tagged releases
+
+### Phase 2: Operator + Display Frontend
+
+**Rationale:** The API from Phase 1 is the source of truth; frontend is a view layer. Building frontend after backend eliminates the common mistake of letting UI design drive data model decisions. Display node architecture (stateless Chromium kiosk) must be validated on actual Pi Zero 2W hardware before building more display views.
+
+**Delivers:** Fully operational venue management UI — operators can run a tournament through the SvelteKit operator interface; display nodes show clock/seating on TV screens; player PWA shows live data via QR code.
+
+**Addresses (from FEATURES.md P1):** Display system (clock + seating views), player mobile PWA, TDD data import, data export
+
+**Implements (from ARCHITECTURE.md):** SvelteKit operator UI, display view routing via URL parameters + WebSocket view-change broadcast, player PWA with service worker, Netbird reverse proxy for external player access
+
+**Avoids:** Pi Zero 2W memory exhaustion (validate on hardware before adding more views), PWA stale service worker (configure skipWaiting from day one), WebSocket state desync on server restart
+
+**Standard patterns:** SvelteKit + Svelte 5 runes, Tailwind v4 Vite integration, vite-pwa/sveltekit plugin — well-documented, skip deep research here
+
+### Phase 3: Cloud Sync + Core Backend
+
+**Rationale:** Core is a progressive enhancement — Leaf operates completely without it. This deliberate ordering ensures offline-first is proven before adding the cloud dependency. Multi-tenant RLS and NATS hub cluster configuration are complex enough to warrant dedicated implementation phase after Leaf is battle-tested.
+
+**Delivers:** Leaf events mirror to Core PostgreSQL; multi-venue operator dashboard; player platform identity (player belongs to Felt, not just one venue); cross-venue league standings computable from aggregated data.
+
+**Addresses (from FEATURES.md P1/P2):** TDD import to cloud, league/season management foundations, analytics data pipeline, multi-tenant operator accounts
+
+**Implements (from ARCHITECTURE.md):** PostgreSQL schema + RLS, NATS hub cluster, Leaf-to-Core JetStream mirror stream, Go Core API, SvelteKit SSR public pages + admin dashboard
+
+**Avoids:** Multi-tenant RLS tenant isolation bleed, Netbird management server as single point of failure (design redundancy here), NATS data loss on Leaf reconnect (verify replay correctness)
+
+**Needs deeper research:** NATS JetStream stream source/mirror configuration across domains; PostgreSQL RLS with pgx connection pool (transaction mode vs session mode); Authentik OIDC integration with Netbird self-hosted
+
+### Phase 4: Cash Game + Advanced Tournament Features
+
+**Rationale:** Cash game operations have different state machine characteristics than tournaments (open-ended sessions, waitlist progression, must-move table logic). Building after tournament proves the event-sourcing and WebSocket broadcast patterns. Events engine automation layer is additive on top of existing state machines.
+
+**Delivers:** Full cash game venue management: waitlist, table status board, session/rake tracking, must-move logic, seat-available notifications. Events engine enables rule-based automation for both tournament and cash game operations.
+
+**Addresses (from FEATURES.md P2):** Waitlist management, table status board, session tracking, rake tracking, seat-available notifications, must-move table logic, events engine, hand-for-hand mode, dealer tablet module, digital signage content system
+
+**Avoids:** Must-move algorithm correctness (similar testing discipline as table rebalancing), GDPR consent capture for player contact details used in push notifications
+
+**Needs deeper research:** Push notification delivery for seat-available (PWA push vs SMS gateway); must-move table priority queue algorithm per TDA rules; digital signage content scheduling architecture
+
+### Phase 5: Platform Maturity + Analytics
+
+**Rationale:** Platform-level features (public venue pages, cross-venue leaderboards, loyalty system, analytics dashboards) require the player identity foundation from Phase 3 and the full event history from Phases 1-4. Analytics consumers on Core event streams can be added without modifying existing Leaf or Core operational code.
+
+**Delivers:** Public venue discovery pages, online event registration, player loyalty/points system, revenue analytics dashboards, full GDPR compliance workflow including right-to-erasure API.
+
+**Addresses (from FEATURES.md P3):** WYSIWYG content editor, AI promo generation, dealer management, loyalty points, public venue presence, analytics dashboards, full GDPR compliance
+
+**Avoids:** Full GDPR right-to-erasure implementation (PII anonymization without destroying tournament results), cross-tenant leaderboard data isolation
+
+**Standard patterns:** Analytics dashboards on time-series data — well-documented patterns; skip deep research unless using TimescaleDB/ClickHouse
+
+### Phase Ordering Rationale
+
+- Financial engine correctness, NATS durability, and data layer configuration are all Phase 1 because they are architectural constraints that cannot be retrofitted without full data migration or manual audit
+- Frontend follows backend (Phase 2 after Phase 1) to prevent UI from driving data model decisions; the API contract is established before the first pixel is rendered
+- Core cloud sync (Phase 3) is explicitly deferred until Leaf is proven in offline operation — this validates the most important product constraint before adding complexity
+- Cash game (Phase 4) shares infrastructure with tournaments but has distinct operational semantics; building after tournament prevents premature abstraction
+- GDPR compliance is split: the anonymization data model must be in place from Phase 1 (player management), but the full workflow (consent capture, deletion API, retention enforcement) is Phase 5
+
+### Research Flags
+
+Phases likely needing `/gsd:research-phase` during planning:
+
+- **Phase 1 — CGO cross-compilation pipeline:** go-libsql has no tagged releases and CGO ARM64 cross-compilation is a known complexity point. Need to validate the specific commit hash strategy and Docker buildx vs cross-compiler approach before committing to the build pipeline.
+- **Phase 1 — NATS embedded leaf node domain setup:** The exact configuration for running an embedded NATS server as a JetStream leaf node with a named domain, connecting to a Core hub, is documented but has known gotchas (domain naming conflicts, account configuration). Validate with a minimal integration test before building any domain event logic on top.
+- **Phase 3 — NATS JetStream stream source/mirror across domains:** Cross-domain JetStream mirroring has specific configuration requirements. The Core side creating a stream source from a leaf domain is not well-documented outside official NATS docs. Needs validation test.
+- **Phase 3 — Netbird reverse proxy beta status:** Netbird reverse proxy is in beta as of research date. The integration with Traefik as external reverse proxy needs explicit validation. Test before committing the player PWA access pattern to this mechanism.
+- **Phase 4 — Push notification delivery for seat-available:** PWA push requires browser permission grant and a push service (Web Push Protocol, VAPID keys). SMS requires a gateway (Twilio, Vonage). Neither is trivial and the choice has cost and compliance implications.
+
+Phases with standard patterns (skip research-phase):
+
+- **Phase 2 — SvelteKit + Tailwind v4 + vite-pwa:** All well-documented with official guides. The integration patterns are verified and the stack is stable. Implement directly.
+- **Phase 2 — WebSocket Hub pattern:** Canonical Go pattern with multiple reference implementations. Implement directly from the hub pattern documented in ARCHITECTURE.md.
+- **Phase 5 — Analytics dashboards:** Standard time-series query patterns on PostgreSQL/TimescaleDB. Skip research unless introducing a dedicated analytics database.
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | MEDIUM-HIGH | Core technologies (Go, SvelteKit, NATS, PostgreSQL) verified against official sources and current releases. go-libsql is the uncertainty — no tagged releases, CGO complexity. Netbird reverse proxy is beta. |
+| Features | MEDIUM | Competitive analysis covered major products (TDD, Blind Valet, BravoPokerLive, LetsPoker, CasinoWare). Feature importance inferred from analysis and forum discussions, not direct operator interviews. Prioritization reflects reasonable inference, not validated PMF. |
+| Architecture | MEDIUM-HIGH | NATS leaf-node patterns verified via official docs. WebSocket Hub is a canonical Go pattern. LibSQL embedded replication model verified. Pi Zero 2W constraints community-verified. Chromium kiosk approach has multiple real-world references. |
+| Pitfalls | HIGH | NATS fsync data loss is documented in a December 2025 Jepsen analysis (independent, high confidence). Float arithmetic, RLS bleed, and WAL checkpoint issues are verified against official sources. Pi Zero 2W memory constraints are community-verified. Table rebalancing edge cases are documented in TDD's own changelog. |
+
+**Overall confidence:** MEDIUM-HIGH
+
+### Gaps to Address
+
+- **Direct operator validation:** Feature priorities are inferred from competitive analysis, not operator interviews. The first beta deployments should include structured feedback collection to validate P1 feature completeness before Phase 2 work begins.
+- **go-libsql stability and replication:** The go-libsql driver has no tagged releases and the LibSQL embedded replication feature is in public beta. The sync-to-Core path may not be needed if NATS JetStream handles all replication. Validate during Phase 1 whether LibSQL sync is used at all or NATS is the exclusive sync mechanism.
+- **Netbird reverse proxy in production:** Beta status means API may change. Validate the full player PWA access flow (QR code → public HTTPS URL → WireGuard → Leaf) in a real venue network environment before Phase 3 depends on it.
+- **Pi Zero 2W Chromium memory with multi-view display:** Memory profiling has been community-validated for basic kiosk use, but not for the specific animation patterns in a tournament clock display. Must be validated on actual hardware in Phase 2 before scaling display views.
+- **Multi-currency display configuration:** Research flagged this as deferred (display-only currency symbol), but the data model choice (storing amounts as cents in a single implicit currency vs. currency-tagged amounts) must be made in Phase 1 even if multi-currency display is deferred.
+
+## Sources
+
+### Primary (HIGH confidence)
+- Go 1.26 release — https://go.dev/blog/go1.26
+- NATS Server v2.12.4 releases — https://github.com/nats-io/nats-server/releases
+- NATS JetStream Core Concepts — https://docs.nats.io/nats-concepts/jetstream
+- Jepsen: NATS 2.12.1 analysis — https://jepsen.io/blog/2025-12-08-nats-2.12.1
+- NATS JetStream data loss GitHub issue — https://github.com/nats-io/nats-server/issues/7564
+- SQLite Write-Ahead Logging — https://sqlite.org/wal.html
+- LibSQL Embedded Replicas data corruption — https://github.com/tursodatabase/libsql/discussions/1910
+- Multi-tenant Data Isolation with PostgreSQL RLS — AWS — https://aws.amazon.com/blogs/database/multi-tenant-data-isolation-with-postgresql-row-level-security/
+- Floats Don't Work for Storing Cents — Modern Treasury
+- SvelteKit 2.53.x official docs — https://kit.svelte.dev
+- Tailwind v4 Vite integration — https://tailwindcss.com/docs/guides/sveltekit
+- The Tournament Director known bugs changelog — https://thetournamentdirector.net/changes.txt
+
+### Secondary (MEDIUM confidence)
+- NATS Adaptive Edge Deployment — https://docs.nats.io/nats-concepts/service_infrastructure/adaptive_edge_deployment
+- JetStream on Leaf Nodes — https://docs.nats.io/running-a-nats-service/configuration/leafnodes/jetstream_leafnodes
+- NetBird Reverse Proxy Docs — https://docs.netbird.io/manage/reverse-proxy
+- LibSQL Embedded Replicas — https://docs.turso.tech/features/embedded-replicas/introduction
+- Authentik Netbird integration — https://docs.netbird.io/selfhosted/identity-providers/authentik
+- CGO ARM64 cross-compilation community thread
+- Go embed + SvelteKit pattern — https://www.liip.ch/en/blog/embed-sveltekit-into-a-go-binary
+- Chromium on Pi Zero 2W memory — Raspberry Pi Forums
+- PostgreSQL RLS implementation guide — permit.io / AWS
+- Competitor feature analysis: Blind Valet, BravoPokerLive, LetsPoker, CasinoWare, kHold'em, PokerAtlas TableCaptain
+- PokerNews: Best Poker Table Management Software comparison
+- Poker TDA Rules 2013 (balancing procedures Rules 25-28)
+
+### Tertiary (LOW confidence)
+- Synadia: AI at the Edge with NATS JetStream — single source for edge AI patterns
+- Multi-Tenancy Database Patterns in Go — single source, corroborates general RLS pattern
+- Raspberry Pi Kiosk System community project
+- NetBird 2025 critical mistakes — third-party blog, verify against official docs
+- GDPR compliance for gaming operators — legal advisory blog, not authoritative
+
+---
+*Research completed: 2026-02-28*
+*Ready for roadmap: yes*

Makefile

@@ -0,0 +1,27 @@
+.PHONY: build run test frontend all clean
+
+# Default data directory
+DATA_DIR ?= ./data
+ADDR ?= :8080
+BINARY := cmd/leaf/leaf
+
+build:
+	CGO_ENABLED=1 go build -o $(BINARY) ./cmd/leaf/
+
+run: build
+	./$(BINARY) --data-dir $(DATA_DIR) --addr $(ADDR)
+
+run-dev: build
+	./$(BINARY) --data-dir $(DATA_DIR) --addr $(ADDR) --dev
+
+test:
+	CGO_ENABLED=1 go test ./...
+
+frontend:
+	cd frontend && npm install && npm run build
+
+all: frontend build
+
+clean:
+	rm -f $(BINARY)
+	rm -rf data/

README.md

@@ -0,0 +1,221 @@
+<p align="center">
+  <br>
+  <strong style="font-size: 2.5em">♠ ♥ ♣ ♦</strong>
+  <br><br>
+</p>
+
+<h1 align="center">Felt</h1>
+
+<p align="center">
+  <strong>The Operating System for Poker Venues</strong>
+  <br>
+  <em>Run a complete tournament offline on a €100 device — it just works.</em>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#architecture">Architecture</a> •
+  <a href="#getting-started">Getting Started</a> •
+  <a href="#development">Development</a> •
+  <a href="#project-structure">Project Structure</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+**Felt** replaces the fragmented tools poker venues cobble together — TDD, whiteboards, spreadsheets, Blind Valet, BravoPokerLive — with one integrated platform. From a 3-table Copenhagen bar to a 40-table casino floor.
+
+TDD's brain. Linear's face. Dark-room ready.
+
+## Features
+
+### Tournament Engine
+- **Clock Engine** — Countdown, blind levels, antes, breaks, chip-ups, pause/resume, hand-for-hand. 100ms tick resolution with configurable warnings
+- **Blind Structure Wizard** — Generate playable structures from target duration, starting chips, and game type. Mixed-game rotation, big-blind antes, chip-up breaks
+- **Financial Engine** — Buy-ins, rebuys, add-ons, bounties (standard + PKO), payouts, rake — all `int64` cents, never `float64`. CI-gated: sum of payouts always equals prize pool
+- **ICM Calculator** — Exact Malmuth-Harville for ≤10 players, Monte Carlo (100K iterations) for 11+. Chop/deal support: ICM, chip-chop, even-chop, custom split, partial chop
+- **Player Management** — Full-text search, buy-in with auto-seating, bust-out with hitman tracking, undo with full re-ranking, CSV import/export, QR codes
+- **Table & Seating** — Configurable layouts, auto-balancing with clockwise distance fairness, break table (fully automatic), tap-tap seat moves
+- **Multi-Tournament** — Run simultaneous tournaments with fully independent state (clocks, financials, players, tables)
+- **Audit Trail** — Every state-changing action logged. Any financial transaction or bust-out undoable with full re-ranking
+
+### Operator UI
+- **Mobile-first, touch-native** — 48px touch targets, FAB with contextual actions, persistent header with tournament switcher
+- **Catppuccin Mocha** dark theme (dark-room ready) with Latte light alternative
+- **Overview** — Large clock display, player counts, table balance status, financial summary, activity feed
+- **Financials** — Prize pool breakdown, transaction history, payout preview, bubble prize, chop/deal flow
+- **Players** — Typeahead search, buy-in flow (search → auto-seat → confirm → receipt), bust-out flow (minimal taps)
+- **Tables** — SVG oval table view with seat positions, list view for large tournaments, balancing panel
+- **Templates** — LEGO-style building blocks: chip sets, blind structures, payout structures, buy-in configs, assembled into reusable tournament templates
+
+### Architecture
+- **Single Go binary** — Embeds HTTP server, SvelteKit frontend, NATS JetStream, and LibSQL. One process, zero dependencies
+- **Offline-first** — Entire operation works without internet. Cloud is never a dependency during a tournament
+- **WebSocket real-time** — State changes propagate to all clients within 100ms
+- **PIN authentication** — Operators log in with 4-6 digit PINs. Argon2id hashing, rate limiting, JWT sessions
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│                   Leaf Node                   │
+│                                               │
+│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
+│  │  SvelteKit │  │   Go     │  │   NATS     │  │
+│  │  Frontend │──│  Server   │──│  JetStream │  │
+│  │  (embed)  │  │  (HTTP)   │  │ (embedded) │  │
+│  └──────────┘  └──────────┘  └────────────┘  │
+│                      │                        │
+│                ┌─────┴─────┐                  │
+│                │   LibSQL   │                  │
+│                │  (SQLite)  │                  │
+│                └───────────┘                  │
+└──────────────────────────────────────────────┘
+         │              │              │
+    ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+    │ Operator │    │ Display │    │ Player  │
+    │  Phone   │    │  TV/Pi  │    │  Phone  │
+    └─────────┘    └─────────┘    └─────────┘
+```
+
+**Stack:**
+
+| Layer | Technology | Why |
+|-------|-----------|-----|
+| Backend | Go 1.24 | Single binary, ARM cross-compile, goroutine concurrency |
+| Frontend | SvelteKit 2 | Reactive UI, SPA for operator, SSR for public pages |
+| Database | LibSQL (SQLite) | Embedded, zero-config, WAL mode, crash-safe |
+| Messages | NATS JetStream | Embedded, 10MB RAM, persistent queuing, ordered replay |
+| Auth | Argon2id + JWT | Offline PIN login, role-based access |
+| Theme | Catppuccin Mocha | Dark-room optimized, systematic accent palette |
+
+## Getting Started
+
+### Prerequisites
+
+- **Go 1.24+** with CGO enabled
+- **Node.js 20+** and npm
+- Linux (developed on Debian/Ubuntu in LXC)
+
+### Build & Run
+
+```bash
+# Clone the repository
+git clone ssh://git@your-forgejo-instance/mikkel/felt.git
+cd felt
+
+# Build frontend + backend
+make all
+
+# Run in development mode
+make run-dev
+
+# Run tests
+make test
+```
+
+The server starts at `http://localhost:8080`. Open it on any device on the local network.
+
+### First Run
+
+1. Navigate to `http://<host>:8080`
+2. Log in with the default operator PIN (shown in terminal on first start)
+3. Go to **More → Templates** to set up your tournament building blocks
+4. Create a tournament from a template
+5. Start managing your tournament
+
+## Development
+
+### Commands
+
+```bash
+make build      # Build Go binary (CGO_ENABLED=1)
+make run        # Build and run on :8080
+make run-dev    # Build and run in dev mode
+make test       # Run all Go tests
+make frontend   # Build SvelteKit frontend
+make all        # Build frontend + backend
+make clean      # Remove binary and data
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATA_DIR` | `./data` | SQLite database and data storage |
+| `ADDR` | `:8080` | HTTP listen address |
+
+## Project Structure
+
+```
+felt/
+├── cmd/leaf/              # Main binary entrypoint
+│   └── main.go            # Server startup, wiring, graceful shutdown
+├── internal/              # Application packages
+│   ├── audit/             # Append-only audit trail + undo engine
+│   ├── auth/              # PIN auth (Argon2id) + JWT tokens
+│   ├── blind/             # Blind structure + wizard generation
+│   ├── clock/             # Tournament clock engine (100ms resolution)
+│   ├── financial/         # Buy-in/rebuy/addon/payout/ICM/chop engine
+│   ├── nats/              # Embedded NATS JetStream server + publisher
+│   ├── player/            # Player CRUD, search, rankings, CSV, QR
+│   ├── seating/           # Table management, balancing, break table
+│   ├── server/            # HTTP server, middleware, WebSocket hub
+│   │   ├── middleware/     # Auth + role middleware
+│   │   ├── routes/        # API route handlers
+│   │   └── ws/            # WebSocket hub + client management
+│   ├── store/             # Database setup, migrations, queries
+│   │   ├── migrations/    # SQL migration files
+│   │   └── queries/       # Named SQL queries
+│   ├── template/          # Building blocks: chipsets, payouts, buyins
+│   └── tournament/        # Tournament lifecycle, multi-tournament, state
+├── frontend/              # SvelteKit operator UI
+│   ├── src/
+│   │   ├── lib/
+│   │   │   ├── api/       # HTTP API client (auto-JWT, error handling)
+│   │   │   ├── components/ # Svelte components (clock, tables, FAB, etc.)
+│   │   │   ├── stores/    # Svelte 5 runes state (tournament, auth, multi)
+│   │   │   ├── theme/     # Catppuccin CSS custom properties
+│   │   │   └── ws/        # WebSocket client with auto-reconnect
+│   │   └── routes/        # SvelteKit pages (overview, players, tables, etc.)
+│   └── build/             # Compiled frontend (go:embed)
+├── Makefile               # Build commands
+├── go.mod
+└── go.sum
+```
+
+## Design Philosophy
+
+> *"TDD's brain, Linear's face."*
+
+Match The Tournament Director's depth and power while looking and feeling like a modern premium product.
+
+- **Dark-room ready** — Catppuccin Mocha dark theme optimized for dimly lit poker rooms
+- **Touch-native** — 48px minimum touch targets, FAB for frequent actions, swipe-friendly
+- **Glanceable** — Information-dense without clutter. Monospace numbers, semantic color coding
+- **Offline-first** — Internet is never required during operation. Everything runs locally
+- **int64 cents** — All monetary values are integer cents. No floating point. Ever. CI-gated
+
+## Roadmap
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| **1** | Tournament Engine | In Progress |
+| **2** | Display Views + Player PWA | Planned |
+| **3** | Core Sync + Platform Identity | Planned |
+| **4** | Digital Signage + Events Engine | Planned |
+| **5** | Leagues, Seasons + Regional | Planned |
+| **6** | TDD Migration | Planned |
+| **7** | Hardware Leaf (ARM64 + Offline) | Planned |
+
+## License
+
+Proprietary. All rights reserved.
+
+---
+
+<p align="center">
+  <sub>Built with Go, SvelteKit, LibSQL, and NATS JetStream.</sub>
+  <br>
+  <sub>Designed for dark rooms and fast decisions.</sub>
+</p>

cmd/leaf/main.go

@@ -0,0 +1,137 @@
+// Command leaf is the Felt tournament engine binary. It starts all embedded
+// infrastructure (LibSQL, NATS JetStream, WebSocket hub) and serves the
+// SvelteKit SPA over HTTP.
+package main
+
+import (
+	"context"
+	"flag"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	feltauth "github.com/felt-app/felt/internal/auth"
+	"github.com/felt-app/felt/internal/clock"
+	feltnats "github.com/felt-app/felt/internal/nats"
+	"github.com/felt-app/felt/internal/server"
+	"github.com/felt-app/felt/internal/server/middleware"
+	"github.com/felt-app/felt/internal/server/ws"
+	"github.com/felt-app/felt/internal/store"
+)
+
+func main() {
+	dataDir := flag.String("data-dir", "./data", "Data directory for database and files")
+	addr := flag.String("addr", ":8080", "HTTP listen address")
+	devMode := flag.Bool("dev", false, "Enable development mode (permissive CORS, dev seed data)")
+	flag.Parse()
+
+	log.SetFlags(log.LstdFlags | log.Lmsgprefix)
+	log.SetPrefix("felt: ")
+
+	log.Printf("starting (data-dir=%s, addr=%s, dev=%v)", *dataDir, *addr, *devMode)
+
+	// Create root context with cancellation
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// ---- 1. LibSQL Database ----
+	db, err := store.Open(*dataDir, *devMode)
+	if err != nil {
+		log.Fatalf("failed to open database: %v", err)
+	}
+	defer db.Close()
+
+	// Verify database is working
+	var one int
+	if err := db.QueryRow("SELECT 1").Scan(&one); err != nil {
+		log.Fatalf("database health check failed: %v", err)
+	}
+	log.Printf("database ready")
+
+	// ---- 2. Embedded NATS Server ----
+	natsServer, err := feltnats.Start(ctx, *dataDir)
+	if err != nil {
+		log.Fatalf("failed to start NATS: %v", err)
+	}
+	defer natsServer.Shutdown()
+
+	// ---- 3. JWT Signing Key (persisted in LibSQL) ----
+	signingKey, err := feltauth.LoadOrCreateSigningKey(db.DB)
+	if err != nil {
+		log.Fatalf("failed to load/create signing key: %v", err)
+	}
+
+	// ---- 4. Auth Service ----
+	jwtService := feltauth.NewJWTService(signingKey, 7*24*time.Hour) // 7-day expiry
+	authService := feltauth.NewAuthService(db.DB, jwtService)
+
+	// ---- 5. WebSocket Hub ----
+	tokenValidator := func(tokenStr string) (string, string, error) {
+		return middleware.ValidateJWT(tokenStr, signingKey)
+	}
+
+	// Tournament validator stub -- allows all for now
+	// TODO: Implement tournament existence + access check against DB
+	tournamentValidator := func(tournamentID string, operatorID string) error {
+		return nil // Accept all tournaments for now
+	}
+
+	var allowedOrigins []string
+	if *devMode {
+		allowedOrigins = nil // InsecureSkipVerify will be used
+	} else {
+		allowedOrigins = []string{"*"} // Same-origin enforced by browser
+	}
+
+	hub := ws.NewHub(tokenValidator, tournamentValidator, allowedOrigins)
+	defer hub.Shutdown()
+
+	// ---- 6. Clock Registry ----
+	clockRegistry := clock.NewRegistry(hub)
+	defer clockRegistry.Shutdown()
+	log.Printf("clock registry ready")
+
+	// ---- 7. HTTP Server ----
+	srv := server.New(server.Config{
+		Addr:      *addr,
+		SigningKey: signingKey,
+		DevMode:   *devMode,
+	}, db.DB, natsServer.Server(), hub, authService, clockRegistry)
+
+	// Start HTTP server in goroutine
+	go func() {
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Fatalf("HTTP server error: %v", err)
+		}
+	}()
+
+	log.Printf("ready (addr=%s, dev=%v)", *addr, *devMode)
+
+	// ---- Signal Handling ----
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
+	sig := <-sigCh
+	log.Printf("received signal: %s, shutting down...", sig)
+
+	// Graceful shutdown in reverse startup order
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer shutdownCancel()
+
+	// 7. HTTP Server
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		log.Printf("HTTP server shutdown error: %v", err)
+	}
+
+	// 6. Clock Registry (closed by defer)
+	// 5. WebSocket Hub (closed by defer)
+	// 4. NATS Server (closed by defer)
+	// 3. Database (closed by defer)
+
+	cancel() // Cancel root context
+
+	log.Printf("shutdown complete")
+}

cmd/leaf/main_test.go

@@ -0,0 +1,454 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/coder/websocket"
+	"github.com/golang-jwt/jwt/v5"
+
+	feltauth "github.com/felt-app/felt/internal/auth"
+	"github.com/felt-app/felt/internal/clock"
+	feltnats "github.com/felt-app/felt/internal/nats"
+	"github.com/felt-app/felt/internal/server"
+	"github.com/felt-app/felt/internal/server/middleware"
+	"github.com/felt-app/felt/internal/server/ws"
+	"github.com/felt-app/felt/internal/store"
+)
+
+func setupTestServer(t *testing.T) (*httptest.Server, *store.DB, *feltnats.EmbeddedServer, []byte, *feltauth.AuthService) {
+	t.Helper()
+	ctx := context.Background()
+	tmpDir := t.TempDir()
+
+	// Open database
+	db, err := store.Open(tmpDir, true)
+	if err != nil {
+		t.Fatalf("open database: %v", err)
+	}
+	t.Cleanup(func() { db.Close() })
+
+	// Start NATS
+	ns, err := feltnats.Start(ctx, tmpDir)
+	if err != nil {
+		t.Fatalf("start nats: %v", err)
+	}
+	t.Cleanup(func() { ns.Shutdown() })
+
+	// Setup JWT signing
+	signingKey := []byte("test-signing-key-32-bytes-long!!")
+
+	// Create auth service
+	jwtService := feltauth.NewJWTService(signingKey, 7*24*time.Hour)
+	authService := feltauth.NewAuthService(db.DB, jwtService)
+
+	tokenValidator := func(tokenStr string) (string, string, error) {
+		return middleware.ValidateJWT(tokenStr, signingKey)
+	}
+
+	hub := ws.NewHub(tokenValidator, nil, nil)
+	t.Cleanup(func() { hub.Shutdown() })
+
+	// Clock registry
+	clockRegistry := clock.NewRegistry(hub)
+	t.Cleanup(func() { clockRegistry.Shutdown() })
+
+	// Create HTTP server
+	srv := server.New(server.Config{
+		Addr:      ":0",
+		SigningKey: signingKey,
+		DevMode:   true,
+	}, db.DB, ns.Server(), hub, authService, clockRegistry)
+
+	ts := httptest.NewServer(srv.Handler())
+	t.Cleanup(func() { ts.Close() })
+
+	return ts, db, ns, signingKey, authService
+}
+
+func makeToken(t *testing.T, signingKey []byte, operatorID, role string) string {
+	t.Helper()
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
+		"sub":  operatorID,
+		"role": role,
+		"exp":  time.Now().Add(time.Hour).Unix(),
+	})
+	tokenStr, err := token.SignedString(signingKey)
+	if err != nil {
+		t.Fatalf("sign token: %v", err)
+	}
+	return tokenStr
+}
+
+func TestHealthEndpoint(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+
+	resp, err := http.Get(ts.URL + "/api/v1/health")
+	if err != nil {
+		t.Fatalf("health request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	var health map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&health); err != nil {
+		t.Fatalf("decode health: %v", err)
+	}
+
+	if health["status"] != "ok" {
+		t.Fatalf("expected status ok, got %v", health["status"])
+	}
+
+	// Check subsystems
+	subsystems, ok := health["subsystems"].(map[string]interface{})
+	if !ok {
+		t.Fatal("missing subsystems in health response")
+	}
+
+	dbStatus, ok := subsystems["database"].(map[string]interface{})
+	if !ok || dbStatus["status"] != "ok" {
+		t.Fatalf("database not ok: %v", dbStatus)
+	}
+
+	natsStatus, ok := subsystems["nats"].(map[string]interface{})
+	if !ok || natsStatus["status"] != "ok" {
+		t.Fatalf("nats not ok: %v", natsStatus)
+	}
+
+	wsStatus, ok := subsystems["websocket"].(map[string]interface{})
+	if !ok || wsStatus["status"] != "ok" {
+		t.Fatalf("websocket not ok: %v", wsStatus)
+	}
+}
+
+func TestSPAFallback(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+
+	// Root path
+	resp, err := http.Get(ts.URL + "/")
+	if err != nil {
+		t.Fatalf("root request: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != 200 {
+		t.Fatalf("expected 200 for root, got %d", resp.StatusCode)
+	}
+
+	// Unknown path (SPA fallback)
+	resp2, err := http.Get(ts.URL + "/some/unknown/route")
+	if err != nil {
+		t.Fatalf("unknown path request: %v", err)
+	}
+	defer resp2.Body.Close()
+	if resp2.StatusCode != 200 {
+		t.Fatalf("expected 200 for SPA fallback, got %d", resp2.StatusCode)
+	}
+}
+
+func TestWebSocketRejectsMissingToken(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+	ctx := context.Background()
+
+	_, resp, err := websocket.Dial(ctx, "ws"+ts.URL[4:]+"/ws", nil)
+	if err == nil {
+		t.Fatal("expected error for missing token")
+	}
+	if resp != nil && resp.StatusCode != 401 {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestWebSocketRejectsInvalidToken(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+	ctx := context.Background()
+
+	_, resp, err := websocket.Dial(ctx, "ws"+ts.URL[4:]+"/ws?token=invalid", nil)
+	if err == nil {
+		t.Fatal("expected error for invalid token")
+	}
+	if resp != nil && resp.StatusCode != 401 {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestWebSocketAcceptsValidToken(t *testing.T) {
+	ts, _, _, signingKey, _ := setupTestServer(t)
+	ctx := context.Background()
+
+	tokenStr := makeToken(t, signingKey, "operator-123", "admin")
+
+	wsURL := "ws" + ts.URL[4:] + "/ws?token=" + tokenStr
+	conn, _, err := websocket.Dial(ctx, wsURL, nil)
+	if err != nil {
+		t.Fatalf("websocket dial: %v", err)
+	}
+	defer conn.CloseNow()
+
+	// Should receive a connected message
+	readCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+
+	_, msgBytes, err := conn.Read(readCtx)
+	if err != nil {
+		t.Fatalf("read connected message: %v", err)
+	}
+
+	var msg map[string]interface{}
+	if err := json.Unmarshal(msgBytes, &msg); err != nil {
+		t.Fatalf("decode message: %v", err)
+	}
+
+	if msg["type"] != "connected" {
+		t.Fatalf("expected 'connected' message, got %v", msg["type"])
+	}
+
+	conn.Close(websocket.StatusNormalClosure, "test done")
+}
+
+func TestNATSStreamsExist(t *testing.T) {
+	_, _, ns, _, _ := setupTestServer(t)
+	ctx := context.Background()
+
+	js := ns.JetStream()
+
+	// Check AUDIT stream
+	stream, err := js.Stream(ctx, "AUDIT")
+	if err != nil {
+		t.Fatalf("get AUDIT stream: %v", err)
+	}
+	info, err := stream.Info(ctx)
+	if err != nil {
+		t.Fatalf("get AUDIT stream info: %v", err)
+	}
+	if info.Config.Name != "AUDIT" {
+		t.Fatalf("expected AUDIT stream, got %s", info.Config.Name)
+	}
+
+	// Check STATE stream
+	stream, err = js.Stream(ctx, "STATE")
+	if err != nil {
+		t.Fatalf("get STATE stream: %v", err)
+	}
+	info, err = stream.Info(ctx)
+	if err != nil {
+		t.Fatalf("get STATE stream info: %v", err)
+	}
+	if info.Config.Name != "STATE" {
+		t.Fatalf("expected STATE stream, got %s", info.Config.Name)
+	}
+}
+
+func TestPublisherUUIDValidation(t *testing.T) {
+	_, _, ns, _, _ := setupTestServer(t)
+	ctx := context.Background()
+
+	js := ns.JetStream()
+	pub := feltnats.NewPublisher(js)
+
+	// Empty UUID
+	_, err := pub.Publish(ctx, "", "audit", []byte("test"))
+	if err == nil {
+		t.Fatal("expected error for empty UUID")
+	}
+
+	// UUID with NATS wildcards
+	_, err = pub.Publish(ctx, "test.*.injection", "audit", []byte("test"))
+	if err == nil {
+		t.Fatal("expected error for UUID with wildcards")
+	}
+
+	// Invalid format
+	_, err = pub.Publish(ctx, "not-a-uuid", "audit", []byte("test"))
+	if err == nil {
+		t.Fatal("expected error for invalid UUID format")
+	}
+
+	// Valid UUID should succeed
+	_, err = pub.Publish(ctx, "550e8400-e29b-41d4-a716-446655440000", "audit", []byte(`{"test":true}`))
+	if err != nil {
+		t.Fatalf("expected success for valid UUID, got: %v", err)
+	}
+}
+
+func TestLibSQLWALMode(t *testing.T) {
+	_, db, _, _, _ := setupTestServer(t)
+
+	var mode string
+	err := db.QueryRow("PRAGMA journal_mode").Scan(&mode)
+	if err != nil {
+		t.Fatalf("query journal_mode: %v", err)
+	}
+	if mode != "wal" {
+		t.Fatalf("expected WAL mode, got %s", mode)
+	}
+}
+
+func TestLibSQLForeignKeys(t *testing.T) {
+	_, db, _, _, _ := setupTestServer(t)
+
+	var fk int
+	err := db.QueryRow("PRAGMA foreign_keys").Scan(&fk)
+	if err != nil {
+		t.Fatalf("query foreign_keys: %v", err)
+	}
+	if fk != 1 {
+		t.Fatalf("expected foreign_keys=1, got %d", fk)
+	}
+}
+
+// ---- Auth Tests (Plan C) ----
+
+func TestLoginWithCorrectPIN(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+
+	// Dev seed creates admin with PIN 1234
+	body := bytes.NewBufferString(`{"pin":"1234"}`)
+	resp, err := http.Post(ts.URL+"/api/v1/auth/login", "application/json", body)
+	if err != nil {
+		t.Fatalf("login request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	var loginResp map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&loginResp); err != nil {
+		t.Fatalf("decode login response: %v", err)
+	}
+
+	if loginResp["token"] == nil || loginResp["token"] == "" {
+		t.Fatal("expected token in login response")
+	}
+
+	operator, ok := loginResp["operator"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected operator in login response")
+	}
+
+	if operator["name"] != "Admin" {
+		t.Fatalf("expected operator name Admin, got %v", operator["name"])
+	}
+	if operator["role"] != "admin" {
+		t.Fatalf("expected operator role admin, got %v", operator["role"])
+	}
+}
+
+func TestLoginWithWrongPIN(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+
+	body := bytes.NewBufferString(`{"pin":"9999"}`)
+	resp, err := http.Post(ts.URL+"/api/v1/auth/login", "application/json", body)
+	if err != nil {
+		t.Fatalf("login request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 401 {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestLoginTokenAccessesProtectedEndpoint(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+
+	// Login first
+	body := bytes.NewBufferString(`{"pin":"1234"}`)
+	resp, err := http.Post(ts.URL+"/api/v1/auth/login", "application/json", body)
+	if err != nil {
+		t.Fatalf("login request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var loginResp map[string]interface{}
+	json.NewDecoder(resp.Body).Decode(&loginResp)
+	token := loginResp["token"].(string)
+
+	// Use token to access /auth/me
+	req, _ := http.NewRequest("GET", ts.URL+"/api/v1/auth/me", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+
+	meResp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("me request: %v", err)
+	}
+	defer meResp.Body.Close()
+
+	if meResp.StatusCode != 200 {
+		t.Fatalf("expected 200, got %d", meResp.StatusCode)
+	}
+
+	var me map[string]interface{}
+	json.NewDecoder(meResp.Body).Decode(&me)
+
+	if me["role"] != "admin" {
+		t.Fatalf("expected role admin, got %v", me["role"])
+	}
+}
+
+func TestProtectedEndpointWithoutToken(t *testing.T) {
+	ts, _, _, _, _ := setupTestServer(t)
+
+	resp, err := http.Get(ts.URL + "/api/v1/auth/me")
+	if err != nil {
+		t.Fatalf("me request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 401 {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleMiddlewareBlocksInsufficientRole(t *testing.T) {
+	ts, _, _, signingKey, _ := setupTestServer(t)
+
+	// Create a viewer token -- viewers can't access admin endpoints
+	viewerToken := makeToken(t, signingKey, "viewer-op", "viewer")
+
+	// /tournaments requires auth but should be accessible by any role for now
+	req, _ := http.NewRequest("GET", ts.URL+"/api/v1/tournaments", nil)
+	req.Header.Set("Authorization", "Bearer "+viewerToken)
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	// Currently all authenticated users can access stub endpoints
+	if resp.StatusCode != 200 {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestJWTValidationEnforcesHS256(t *testing.T) {
+	signingKey := []byte("test-signing-key-32-bytes-long!!")
+
+	// Create a valid HS256 token -- should work
+	_, _, err := middleware.ValidateJWT(makeToken(t, signingKey, "op-1", "admin"), signingKey)
+	if err != nil {
+		t.Fatalf("valid HS256 token should pass: %v", err)
+	}
+
+	// Create an expired token -- should fail
+	expiredToken := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
+		"sub":  "op-1",
+		"role": "admin",
+		"exp":  time.Now().Add(-time.Hour).Unix(),
+	})
+	expiredStr, _ := expiredToken.SignedString(signingKey)
+	_, _, err = middleware.ValidateJWT(expiredStr, signingKey)
+	if err == nil {
+		t.Fatal("expired token should fail validation")
+	}
+}

frontend/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.svelte-kit/

frontend/build/_app/env.js

@@ -0,0 +1 @@
+export const env={}

frontend/build/_app/immutable/assets/2.BmNlW7Gm.css

@@ -0,0 +1 @@
+.redirect.svelte-1uha8ag{display:flex;align-items:center;justify-content:center;min-height:50dvh;color:var(--color-text-muted)}

frontend/build/_app/immutable/assets/3.BysT7-iU.css

@@ -0,0 +1 @@
+.page-content.svelte-1ba4c5d{padding:var(--space-4)}h2.svelte-1ba4c5d{font-size:var(--text-2xl);font-weight:700;color:var(--color-text);margin-bottom:var(--space-2)}.text-secondary.svelte-1ba4c5d{color:var(--color-text-secondary);font-size:var(--text-sm);margin-bottom:var(--space-6)}.finance-grid.svelte-1ba4c5d{display:grid;grid-template-columns:repeat(2,1fr);gap:var(--space-3)}@media(min-width:768px){.finance-grid.svelte-1ba4c5d{grid-template-columns:repeat(3,1fr)}}.finance-card.svelte-1ba4c5d{display:flex;flex-direction:column;gap:var(--space-1);padding:var(--space-4);background-color:var(--color-surface);border-radius:var(--radius-lg);border:1px solid var(--color-border)}.finance-card.highlight.svelte-1ba4c5d{border-color:var(--color-prize)}.finance-label.svelte-1ba4c5d{font-size:var(--text-xs);text-transform:uppercase;letter-spacing:.05em;color:var(--color-text-muted)}.finance-value.svelte-1ba4c5d{font-size:var(--text-xl);font-weight:700;color:var(--color-text)}.finance-value.prize.svelte-1ba4c5d{color:var(--color-prize)}.empty-state.svelte-1ba4c5d{color:var(--color-text-muted);font-style:italic;padding:var(--space-8) 0;text-align:center}

frontend/build/_app/immutable/assets/4.C7Q2VT44.css

@@ -0,0 +1 @@
+.login-container.svelte-1x05zx6{display:flex;align-items:center;justify-content:center;min-height:100dvh;padding:var(--space-4);background-color:var(--color-bg)}.login-card.svelte-1x05zx6{width:100%;max-width:360px;display:flex;flex-direction:column;align-items:center;gap:var(--space-6)}.logo.svelte-1x05zx6{text-align:center}.logo.svelte-1x05zx6 h1:where(.svelte-1x05zx6){font-size:var(--text-4xl);font-weight:700;color:var(--color-primary);letter-spacing:-.02em}.subtitle.svelte-1x05zx6{color:var(--color-text-secondary);font-size:var(--text-sm);margin-top:var(--space-1)}.pin-display.svelte-1x05zx6{display:flex;gap:var(--space-3);padding:var(--space-4) 0}.pin-dot.svelte-1x05zx6{width:16px;height:16px;border-radius:var(--radius-full);border:2px solid var(--color-surface-active);background-color:transparent;transition:background-color var(--transition-fast),border-color var(--transition-fast)}.pin-dot.filled.svelte-1x05zx6{background-color:var(--color-primary);border-color:var(--color-primary)}.error-message.svelte-1x05zx6{color:var(--color-error);font-size:var(--text-sm);text-align:center;padding:var(--space-2) var(--space-4);background-color:color-mix(in srgb,var(--color-error) 10%,transparent);border-radius:var(--radius-md);width:100%}.numpad.svelte-1x05zx6{display:grid;grid-template-columns:repeat(3,1fr);gap:var(--space-3);width:100%}.numpad-btn.svelte-1x05zx6{display:flex;align-items:center;justify-content:center;height:64px;font-size:var(--text-2xl);font-weight:600;color:var(--color-text);background-color:var(--color-surface);border:1px solid var(--color-border);border-radius:var(--radius-lg);cursor:pointer;-webkit-user-select:none;user-select:none;-webkit-tap-highlight-color:transparent;transition:background-color var(--transition-fast)}.numpad-btn.svelte-1x05zx6:hover:not(:disabled){background-color:var(--color-surface-hover)}.numpad-btn.svelte-1x05zx6:disabled{opacity:.4;cursor:not-allowed;transform:none}.numpad-fn.svelte-1x05zx6{font-size:var(--text-sm);font-weight:500;color:var(--color-text-secondary)}.submit-btn.svelte-1x05zx6{width:100%;height:56px;font-size:var(--text-lg);font-weight:600;color:var(--color-bg);background-color:var(--color-primary);border:none;border-radius:var(--radius-lg);cursor:pointer;-webkit-user-select:none;user-select:none;-webkit-tap-highlight-color:transparent;transition:background-color var(--transition-fast),opacity var(--transition-fast)}.submit-btn.svelte-1x05zx6:hover:not(:disabled){opacity:.9}.submit-btn.svelte-1x05zx6:disabled{opacity:.4;cursor:not-allowed;transform:none}

frontend/build/_app/immutable/assets/5.B34oOQk5.css

@@ -0,0 +1 @@
+.page-content.svelte-hq0atu{padding:var(--space-4)}h2.svelte-hq0atu{font-size:var(--text-2xl);font-weight:700;color:var(--color-text);margin-bottom:var(--space-2)}.text-secondary.svelte-hq0atu{color:var(--color-text-secondary);font-size:var(--text-sm);margin-bottom:var(--space-6)}.menu-list.svelte-hq0atu{display:flex;flex-direction:column;background-color:var(--color-surface);border-radius:var(--radius-lg);border:1px solid var(--color-border);overflow:hidden}.menu-item.svelte-hq0atu{display:flex;align-items:center;justify-content:space-between;padding:var(--space-4);min-height:var(--touch-target);border-bottom:1px solid var(--color-border)}.menu-item.svelte-hq0atu:last-child{border-bottom:none}.menu-action.svelte-hq0atu{background:none;border:none;border-bottom:1px solid var(--color-border);cursor:pointer;width:100%;text-align:left;font-size:inherit;font-family:inherit}.menu-action.svelte-hq0atu:hover{background-color:var(--color-surface-hover)}.menu-label.svelte-hq0atu{font-size:var(--text-base);color:var(--color-text)}.menu-value.svelte-hq0atu{font-size:var(--text-sm);color:var(--color-text-secondary)}.danger.svelte-hq0atu .menu-label:where(.svelte-hq0atu){color:var(--color-error)}.divider.svelte-hq0atu{border:none;border-top:1px solid var(--color-border);margin:0}

frontend/build/_app/immutable/assets/6.BcOWEnnB.css

@@ -0,0 +1 @@
+.page-content.svelte-14qseeg{padding:var(--space-4)}h2.svelte-14qseeg{font-size:var(--text-2xl);font-weight:700;color:var(--color-text);margin-bottom:var(--space-2)}.text-secondary.svelte-14qseeg{color:var(--color-text-secondary);font-size:var(--text-sm);margin-bottom:var(--space-6)}.stats-grid.svelte-14qseeg{display:grid;grid-template-columns:repeat(2,1fr);gap:var(--space-3)}@media(min-width:768px){.stats-grid.svelte-14qseeg{grid-template-columns:repeat(4,1fr)}}.stat-card.svelte-14qseeg{display:flex;flex-direction:column;gap:var(--space-1);padding:var(--space-4);background-color:var(--color-surface);border-radius:var(--radius-lg);border:1px solid var(--color-border)}.stat-label.svelte-14qseeg{font-size:var(--text-xs);text-transform:uppercase;letter-spacing:.05em;color:var(--color-text-muted)}.stat-value.svelte-14qseeg{font-size:var(--text-2xl);font-weight:700;color:var(--color-text)}.empty-state.svelte-14qseeg{color:var(--color-text-muted);font-style:italic;padding:var(--space-8) 0;text-align:center}

frontend/build/_app/immutable/assets/7.CLv6rscz.css

@@ -0,0 +1 @@
+.page-content.svelte-wtkzqx{padding:var(--space-4)}h2.svelte-wtkzqx{font-size:var(--text-2xl);font-weight:700;color:var(--color-text);margin-bottom:var(--space-2)}.text-secondary.svelte-wtkzqx{color:var(--color-text-secondary);font-size:var(--text-sm);margin-bottom:var(--space-4)}

frontend/build/_app/immutable/assets/8.WyH666g9.css

@@ -0,0 +1 @@
+.page-content.svelte-bf0doe{padding:var(--space-4)}h2.svelte-bf0doe{font-size:var(--text-2xl);font-weight:700;color:var(--color-text);margin-bottom:var(--space-2)}.text-secondary.svelte-bf0doe{color:var(--color-text-secondary);font-size:var(--text-sm);margin-bottom:var(--space-4)}

frontend/build/_app/immutable/assets/DataTable.CrZfXN-V.css

@@ -0,0 +1 @@
+.data-table-wrapper.svelte-16k18c8{width:100%;overflow:hidden}.table-search.svelte-16k18c8{padding:var(--space-3) 0}.search-input.svelte-16k18c8{width:100%;padding:var(--space-2) var(--space-3);font-size:var(--text-sm);color:var(--color-text);background-color:var(--color-surface);border:1px solid var(--color-border);border-radius:var(--radius-md);outline:none;transition:border-color var(--transition-fast);min-height:var(--touch-target)}.search-input.svelte-16k18c8:focus{border-color:var(--color-primary)}.search-input.svelte-16k18c8::placeholder{color:var(--color-text-muted)}.table-scroll.svelte-16k18c8{overflow-x:auto;-webkit-overflow-scrolling:touch}.data-table.svelte-16k18c8{width:100%;border-collapse:collapse;font-size:var(--text-sm)}.data-table.svelte-16k18c8 thead:where(.svelte-16k18c8){position:sticky;top:0;z-index:2}.data-table.svelte-16k18c8 th:where(.svelte-16k18c8){padding:var(--space-2) var(--space-3);font-weight:600;font-size:var(--text-xs);text-transform:uppercase;letter-spacing:.05em;color:var(--color-text-muted);background-color:var(--color-bg-elevated);border-bottom:2px solid var(--color-border);white-space:nowrap;-webkit-user-select:none;user-select:none}.data-table.svelte-16k18c8 th.sortable:where(.svelte-16k18c8){cursor:pointer}.data-table.svelte-16k18c8 th.sortable:where(.svelte-16k18c8):hover{color:var(--color-text)}.th-content.svelte-16k18c8{display:inline-flex;align-items:center;gap:var(--space-1)}.sort-indicator.svelte-16k18c8{font-size:8px;color:var(--color-text-muted);opacity:.3}.sort-indicator.active.svelte-16k18c8{opacity:1;color:var(--color-primary)}.data-table.svelte-16k18c8 td:where(.svelte-16k18c8){padding:var(--space-2) var(--space-3);color:var(--color-text);border-bottom:1px solid var(--color-border);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:200px}.data-row.svelte-16k18c8{min-height:var(--touch-target);transition:background-color var(--transition-fast)}.data-row.svelte-16k18c8:hover{background-color:var(--color-surface)}.data-row.clickable.svelte-16k18c8{cursor:pointer}.data-row.clickable.svelte-16k18c8:active{background-color:var(--color-surface-hover)}.empty-state.svelte-16k18c8{text-align:center;padding:var(--space-12) var(--space-4);color:var(--color-text-muted);font-style:italic}.skeleton-row.svelte-16k18c8 td:where(.svelte-16k18c8){padding:var(--space-3)}.skeleton-cell.svelte-16k18c8{height:16px;background:linear-gradient(90deg,var(--color-surface) 25%,var(--color-surface-hover) 50%,var(--color-surface) 75%);background-size:200% 100%;animation:svelte-16k18c8-skeleton-shimmer 1.5s ease-in-out infinite;border-radius:var(--radius-sm)}@keyframes svelte-16k18c8-skeleton-shimmer{0%{background-position:200% 0}to{background-position:-200% 0}}.swipe-actions-row.svelte-16k18c8 td:where(.svelte-16k18c8){padding:0;border-bottom:none}.swipe-actions.svelte-16k18c8{display:flex;justify-content:flex-end;gap:var(--space-1);padding:var(--space-1);background-color:var(--color-bg-sunken)}.swipe-action-btn.svelte-16k18c8{padding:var(--space-2) var(--space-4);font-size:var(--text-sm);font-weight:600;color:#fff;border:none;border-radius:var(--radius-md);cursor:pointer;white-space:nowrap}.hide-mobile.svelte-16k18c8{display:none}@media(min-width:768px){.hide-mobile.svelte-16k18c8{display:table-cell}.data-table.svelte-16k18c8 td:where(.svelte-16k18c8){max-width:300px}}

frontend/build/_app/immutable/chunks/BTkWS7xQ.js

@@ -0,0 +1 @@
+import{t as b}from"./BeLKMLqR.js";import{h as c}from"./C4An0dnW.js";function A(i,u={},r,f){for(var a in r){var o=r[a];u[a]!==o&&(r[a]==null?i.style.removeProperty(a):i.style.setProperty(a,o,f))}}function t(i,u,r,f){var a=i.__style;if(c||a!==u){var o=b(u,f);(!c||o!==i.getAttribute("style"))&&(o==null?i.removeAttribute("style"):i.style.cssText=o),i.__style=u}else f&&(Array.isArray(f)?(A(i,r==null?void 0:r[0],f[0]),A(i,r==null?void 0:r[1],f[1],"important")):A(i,r,f));return f}export{t as s};

frontend/build/_app/immutable/chunks/BViIIwgj.js

@@ -0,0 +1 @@
+import{j as g,m as d,u as c,k as m,n as i,o as b,g as p,q as v,v as k,w as h}from"./C4An0dnW.js";function x(t=!1){const s=g,e=s.l.u;if(!e)return;let f=()=>v(s.s);if(t){let o=0,n={};const _=k(()=>{let l=!1;const r=s.s;for(const a in r)r[a]!==n[a]&&(n[a]=r[a],l=!0);return l&&o++,o});f=()=>p(_)}e.b.length&&d(()=>{u(s,f),i(e.b)}),c(()=>{const o=m(()=>e.m.map(b));return()=>{for(const n of o)typeof n=="function"&&n()}}),e.a.length&&c(()=>{u(s,f),i(e.a)})}function u(t,s){if(t.l.s)for(const e of t.l.s)p(e);s()}h();export{x as i};

frontend/build/_app/immutable/chunks/BeLKMLqR.js

@@ -0,0 +1,2 @@
+import{K as U,T as tr,a5 as sr,h as A,_ as Y,a6 as vr,U as cr,g as j,W as dr,Y as gr,Z as x,$ as q,O as z,a7 as hr,a8 as pr,a9 as y,N as _r,aa as I,M as m,ab as Er,R as Ar,i as Tr,ac as Nr,ad as V,ae as Sr,af as Ir,ag as br,ah as rr,ai as Cr,H as ur,J as lr,aj as B,ak as or,al as Mr,am as Or,an as Lr,I as wr,ao as Hr,ap as Rr,aq as kr,ar as Dr,as as Fr,at as zr,au as Ur}from"./C4An0dnW.js";function Wr(r,e){return e}function Yr(r,e,f){for(var a=[],u=e.length,n,s=e.length,c=0;c<u;c++){let g=e[c];lr(g,()=>{if(n){if(n.pending.delete(g),n.done.add(g),n.pending.size===0){var t=r.outrogroups;G(V(n.done)),t.delete(n),t.size===0&&(r.outrogroups=null)}}else s-=1},!1)}if(s===0){var l=a.length===0&&f!==null;if(l){var d=f,o=d.parentNode;Lr(o),o.append(d),r.items.clear()}G(e,!l)}else n={pending:new Set(e),done:new Set},(r.outrogroups??(r.outrogroups=new Set)).add(n)}function G(r,e=!0){for(var f=0;f<r.length;f++)wr(r[f],e)}var er;function Zr(r,e,f,a,u,n=null){var s=r,c=new Map,l=(e&sr)!==0;if(l){var d=r;s=A?Y(vr(d)):d.appendChild(U())}A&&cr();var o=null,g=Tr(()=>{var v=f();return Nr(v)?v:v==null?[]:V(v)}),t,h=!0;function T(){i.fallback=o,qr(i,t,s,e,a),o!==null&&(t.length===0?(o.f&I)===0?ur(o):(o.f^=I,k(o,null,s)):lr(o,()=>{o=null}))}var N=tr(()=>{t=j(g);var v=t.length;let O=!1;if(A){var L=dr(s)===gr;L!==(v===0)&&(s=x(),Y(s),q(!1),O=!0)}for(var _=new Set,C=_r,w=Ar(),p=0;p<v;p+=1){A&&z.nodeType===hr&&z.data===pr&&(s=z,O=!0,q(!1));var M=t[p],H=a(M,p),E=h?null:c.get(H);E?(E.v&&y(E.v,M),E.i&&y(E.i,p),w&&C.unskip_effect(E.e)):(E=Br(c,h?s:er??(er=U()),M,H,p,u,e,f),h||(E.e.f|=I),c.set(H,E)),_.add(H)}if(v===0&&n&&!o&&(h?o=m(()=>n(s)):(o=m(()=>n(er??(er=U()))),o.f|=I)),v>_.size&&Er(),A&&v>0&&Y(x()),!h)if(w){for(const[D,F]of c)_.has(D)||C.skip_effect(F.e);C.oncommit(T),C.ondiscard(()=>{})}else T();O&&q(!0),j(g)}),i={effect:N,items:c,outrogroups:null,fallback:o};h=!1,A&&(s=z)}function R(r){for(;r!==null&&(r.f&Mr)===0;)r=r.next;return r}function qr(r,e,f,a,u){var E,D,F,X,J,P,W,Z,$;var n=(a&Or)!==0,s=e.length,c=r.items,l=R(r.effect.first),d,o=null,g,t=[],h=[],T,N,i,v;if(n)for(v=0;v<s;v+=1)T=e[v],N=u(T,v),i=c.get(N).e,(i.f&I)===0&&((D=(E=i.nodes)==null?void 0:E.a)==null||D.measure(),(g??(g=new Set)).add(i));for(v=0;v<s;v+=1){if(T=e[v],N=u(T,v),i=c.get(N).e,r.outrogroups!==null)for(const S of r.outrogroups)S.pending.delete(i),S.done.delete(i);if((i.f&I)!==0)if(i.f^=I,i===l)k(i,null,f);else{var O=o?o.next:l;i===r.effect.last&&(r.effect.last=i.prev),i.prev&&(i.prev.next=i.next),i.next&&(i.next.prev=i.prev),b(r,o,i),b(r,i,O),k(i,O,f),o=i,t=[],h=[],l=R(o.next);continue}if((i.f&B)!==0&&(ur(i),n&&((X=(F=i.nodes)==null?void 0:F.a)==null||X.unfix(),(g??(g=new Set)).delete(i))),i!==l){if(d!==void 0&&d.has(i)){if(t.length<h.length){var L=h[0],_;o=L.prev;var C=t[0],w=t[t.length-1];for(_=0;_<t.length;_+=1)k(t[_],L,f);for(_=0;_<h.length;_+=1)d.delete(h[_]);b(r,C.prev,w.next),b(r,o,C),b(r,w,L),l=L,o=w,v-=1,t=[],h=[]}else d.delete(i),k(i,l,f),b(r,i.prev,i.next),b(r,i,o===null?r.effect.first:o.next),b(r,o,i),o=i;continue}for(t=[],h=[];l!==null&&l!==i;)(d??(d=new Set)).add(l),h.push(l),l=R(l.next);if(l===null)continue}(i.f&I)===0&&t.push(i),o=i,l=R(i.next)}if(r.outrogroups!==null){for(const S of r.outrogroups)S.pending.size===0&&(G(V(S.done)),(J=r.outrogroups)==null||J.delete(S));r.outrogroups.size===0&&(r.outrogroups=null)}if(l!==null||d!==void 0){var p=[];if(d!==void 0)for(i of d)(i.f&B)===0&&p.push(i);for(;l!==null;)(l.f&B)===0&&l!==r.fallback&&p.push(l),l=R(l.next);var M=p.length;if(M>0){var H=(a&sr)!==0&&s===0?f:null;if(n){for(v=0;v<M;v+=1)(W=(P=p[v].nodes)==null?void 0:P.a)==null||W.measure();for(v=0;v<M;v+=1)($=(Z=p[v].nodes)==null?void 0:Z.a)==null||$.fix()}Yr(r,p,H)}}n&&or(()=>{var S,Q;if(g!==void 0)for(i of g)(Q=(S=i.nodes)==null?void 0:S.a)==null||Q.apply()})}function Br(r,e,f,a,u,n,s,c){var l=(s&Sr)!==0?(s&Ir)===0?br(f,!1,!1):rr(f):null,d=(s&Cr)!==0?rr(u):null;return{v:l,i:d,e:m(()=>(n(e,l??f,d??u,c),()=>{r.delete(a)}))}}function k(r,e,f){if(r.nodes)for(var a=r.nodes.start,u=r.nodes.end,n=e&&(e.f&I)===0?e.nodes.start:f;a!==null;){var s=Hr(a);if(n.before(a),a===u)return;a=s}}function b(r,e,f){e===null?r.effect.first=f:e.next=f,f===null?r.effect.last=e:f.prev=e}const fr=[...` 	
+\r\f \v\uFEFF`];function Kr(r,e,f){var a=r==null?"":""+r;if(e&&(a=a?a+" "+e:e),f){for(var u of Object.keys(f))if(f[u])a=a?a+" "+u:u;else if(a.length)for(var n=u.length,s=0;(s=a.indexOf(u,s))>=0;){var c=s+n;(s===0||fr.includes(a[s-1]))&&(c===a.length||fr.includes(a[c]))?a=(s===0?"":a.substring(0,s))+a.substring(c+1):s=c}}return a===""?null:a}function ar(r,e=!1){var f=e?" !important;":";",a="";for(var u of Object.keys(r)){var n=r[u];n!=null&&n!==""&&(a+=" "+u+": "+n+f)}return a}function K(r){return r[0]!=="-"||r[1]!=="-"?r.toLowerCase():r}function $r(r,e){if(e){var f="",a,u;if(Array.isArray(e)?(a=e[0],u=e[1]):a=e,r){r=String(r).replaceAll(/\s*\/\*.*?\*\/\s*/g,"").trim();var n=!1,s=0,c=!1,l=[];a&&l.push(...Object.keys(a).map(K)),u&&l.push(...Object.keys(u).map(K));var d=0,o=-1;const N=r.length;for(var g=0;g<N;g++){var t=r[g];if(c?t==="/"&&r[g-1]==="*"&&(c=!1):n?n===t&&(n=!1):t==="/"&&r[g+1]==="*"?c=!0:t==='"'||t==="'"?n=t:t==="("?s++:t===")"&&s--,!c&&n===!1&&s===0){if(t===":"&&o===-1)o=g;else if(t===";"||g===N-1){if(o!==-1){var h=K(r.substring(d,o).trim());if(!l.includes(h)){t!==";"&&g++;var T=r.substring(d,g).trim();f+=" "+T+";"}}d=g+1,o=-1}}}}return a&&(f+=ar(a)),u&&(f+=ar(u,!0)),f=f.trim(),f===""?null:f}return r==null?null:String(r)}function Qr(r,e,f,a,u,n){var s=r.__className;if(A||s!==f||s===void 0){var c=Kr(f,a,n);(!A||c!==r.getAttribute("class"))&&(c==null?r.removeAttribute("class"):r.className=c),r.__className=f}else if(n&&u!==n)for(var l in n){var d=!!n[l];(u==null||d!==!!u[l])&&r.classList.toggle(l,d)}return n}const mr=Symbol("is custom element"),Gr=Symbol("is html"),Vr=Ur?"link":"LINK";function jr(r){if(A){var e=!1,f=()=>{if(!e){if(e=!0,r.hasAttribute("value")){var a=r.value;ir(r,"value",null),r.value=a}if(r.hasAttribute("checked")){var u=r.checked;ir(r,"checked",null),r.checked=u}}};r.__on_r=f,or(f),Fr()}}function ir(r,e,f,a){var u=Xr(r);A&&(u[e]=r.getAttribute(e),e==="src"||e==="srcset"||e==="href"&&r.nodeName===Vr)||u[e]!==(u[e]=f)&&(e==="loading"&&(r[zr]=f),f==null?r.removeAttribute(e):typeof f!="string"&&Jr(r).includes(e)?r[e]=f:r.setAttribute(e,f))}function Xr(r){return r.__attributes??(r.__attributes={[mr]:r.nodeName.includes("-"),[Gr]:r.namespaceURI===Rr})}var nr=new Map;function Jr(r){var e=r.getAttribute("is")||r.nodeName,f=nr.get(e);if(f)return f;nr.set(e,f=[]);for(var a,u=r,n=Element.prototype;n!==u;){a=Dr(u);for(var s in a)a[s].set&&f.push(s);u=kr(u)}return f}export{Qr as a,Zr as e,Wr as i,jr as r,ir as s,$r as t};

frontend/build/_app/immutable/chunks/C48rM6KF.js

@@ -0,0 +1 @@
+import{y as D,z as T,P as B,g,e as m,d as Y,A as y,B as M,D as N,C as U,k as h,l as x,E as z,F as C,v as G,i as $,G as q,S as w,L as F}from"./C4An0dnW.js";let S=!1;function Z(r){var n=S;try{return S=!1,[r(),S]}finally{S=n}}function H(r,n,t,d){var E;var f=!x||(t&z)!==0,v=(t&U)!==0,O=(t&q)!==0,a=d,c=!0,o=()=>(c&&(c=!1,a=O?h(d):d),a),u;if(v){var R=w in r||F in r;u=((E=D(r,n))==null?void 0:E.set)??(R&&n in r?e=>r[n]=e:void 0)}var _,I=!1;v?[_,I]=Z(()=>r[n]):_=r[n],_===void 0&&d!==void 0&&(_=o(),u&&(f&&T(),u(_)));var i;if(f?i=()=>{var e=r[n];return e===void 0?o():(c=!0,e)}:i=()=>{var e=r[n];return e!==void 0&&(a=void 0),e===void 0?a:e},f&&(t&B)===0)return i;if(u){var L=r.$$legacy;return(function(e,l){return arguments.length>0?((!f||!l||L||I)&&u(l?i():e),e):i()})}var P=!1,s=((t&C)!==0?G:$)(()=>(P=!1,i()));v&&g(s);var b=M;return(function(e,l){if(arguments.length>0){const A=l?g(s):f&&v?m(e):e;return Y(s,A),P=!0,a!==void 0&&(a=A),e}return y&&P||(b.f&N)!==0?s.v:g(s)})}export{H as p};

frontend/build/_app/immutable/chunks/C5aWxL5p.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var v=e=>{throw TypeError(e)};var O=(e,t,a)=>t in e?S(e,t,{enumerable:!0,configurable:!0,writable:!0,value:a}):e[t]=a;var g=(e,t,a)=>O(e,typeof t!="symbol"?t+"":t,a),U=(e,t,a)=>t.has(e)||v("Cannot "+a);var s=(e,t,a)=>(U(e,t,"read from private field"),a?a.call(e):t.get(e)),i=(e,t,a)=>t.has(e)?v("Cannot add the same private member more than once"):t instanceof WeakSet?t.add(e):t.set(e,a);import{b as l,g as r,d as c,e as p}from"./C4An0dnW.js";var n,d,h,u,b,k,y,o;class x{constructor(){i(this,n,l(null));i(this,d,l(null));i(this,h,l(p([])));i(this,u,l(p([])));i(this,b,l(null));i(this,k,l(p([])));i(this,y,l(p([])));i(this,o,l(null));g(this,"maxActivityEntries",100)}get id(){return r(s(this,n))}set id(t){c(s(this,n),t,!0)}get clock(){return r(s(this,d))}set clock(t){c(s(this,d),t,!0)}get players(){return r(s(this,h))}set players(t){c(s(this,h),t,!0)}get tables(){return r(s(this,u))}set tables(t){c(s(this,u),t,!0)}get financials(){return r(s(this,b))}set financials(t){c(s(this,b),t,!0)}get activity(){return r(s(this,k))}set activity(t){c(s(this,k),t,!0)}get rankings(){return r(s(this,y))}set rankings(t){c(s(this,y),t,!0)}get balanceStatus(){return r(s(this,o))}set balanceStatus(t){c(s(this,o),t,!0)}get remainingPlayers(){return this.players.filter(t=>t.status==="active").length}get totalPlayers(){return this.players.length}get activeTables(){return this.tables.filter(t=>t.players.length>0).length}get isBalanced(){var t;return((t=this.balanceStatus)==null?void 0:t.is_balanced)??!0}handleMessage(t){switch(t.type){case"clock.tick":this.clock=t.data;break;case"clock.level_change":this.clock=t.data;break;case"clock.paused":this.clock&&(this.clock.is_paused=!0);break;case"clock.resumed":this.clock&&(this.clock.is_paused=!1);break;case"state.snapshot":this.loadFullState(t.data);break;case"player.registered":this.addOrUpdatePlayer(t.data);break;case"player.seated":this.addOrUpdatePlayer(t.data);break;case"player.bust":case"player.eliminated":this.addOrUpdatePlayer(t.data);break;case"player.rebuy":case"player.addon":this.addOrUpdatePlayer(t.data);break;case"player.moved":this.addOrUpdatePlayer(t.data);break;case"table.created":this.addOrUpdateTable(t.data);break;case"table.broken":this.removeTable(t.data.id);break;case"table.updated":this.addOrUpdateTable(t.data);break;case"financial.updated":this.financials=t.data;break;case"rankings.updated":this.rankings=t.data;break;case"balance.updated":this.balanceStatus=t.data;break;case"activity.new":this.addActivity(t.data);break;case"connected":console.log("tournament: connected to server");break;default:console.warn(`tournament: unknown message type: ${t.type}`)}}reset(){this.id=null,this.clock=null,this.players=[],this.tables=[],this.financials=null,this.activity=[],this.rankings=[],this.balanceStatus=null}loadFullState(t){this.id=t.id??this.id,this.clock=t.clock??null,this.players=t.players??[],this.tables=t.tables??[],this.financials=t.financials??null,this.activity=t.activity??[],this.rankings=t.rankings??[],this.balanceStatus=t.balance_status??null}addOrUpdatePlayer(t){const a=this.players.findIndex(f=>f.id===t.id);a>=0?this.players[a]=t:this.players.push(t)}addOrUpdateTable(t){const a=this.tables.findIndex(f=>f.id===t.id);a>=0?this.tables[a]=t:this.tables.push(t)}removeTable(t){this.tables=this.tables.filter(a=>a.id!==t)}addActivity(t){this.activity=[t,...this.activity].slice(0,this.maxActivityEntries)}}n=new WeakMap,d=new WeakMap,h=new WeakMap,u=new WeakMap,b=new WeakMap,k=new WeakMap,y=new WeakMap,o=new WeakMap;const w=new x;export{w as t};

frontend/build/_app/immutable/chunks/D3f6eoxz.js

@@ -0,0 +1 @@
+var h=e=>{throw TypeError(e)};var m=(e,t,o)=>t.has(e)||h("Cannot "+o);var r=(e,t,o)=>(m(e,t,"read from private field"),o?o.call(e):t.get(e)),l=(e,t,o)=>t.has(e)?h("Cannot add the same private member more than once"):t instanceof WeakSet?t.add(e):t.set(e,o);import{b as c,g,d as u}from"./C4An0dnW.js";const n="felt_token",i="felt_operator";var a,s;class p{constructor(){l(this,a,c(null));l(this,s,c(null));typeof window<"u"&&this.loadFromStorage()}get token(){return g(r(this,a))}set token(t){u(r(this,a),t,!0)}get operator(){return g(r(this,s))}set operator(t){u(r(this,s),t,!0)}get isAuthenticated(){return this.token!==null}get isAdmin(){var t;return((t=this.operator)==null?void 0:t.role)==="admin"}get isFloor(){var t;return["admin","floor"].includes(((t=this.operator)==null?void 0:t.role)??"")}login(t,o){this.token=t,this.operator=o,this.saveToStorage()}logout(){this.token=null,this.operator=null,this.clearStorage()}loadFromStorage(){try{const t=localStorage.getItem(n),o=localStorage.getItem(i);t&&o&&(this.token=t,this.operator=JSON.parse(o))}catch(t){console.warn("auth: failed to load from storage:",t),this.clearStorage()}}saveToStorage(){try{this.token&&this.operator&&(localStorage.setItem(n,this.token),localStorage.setItem(i,JSON.stringify(this.operator)))}catch(t){console.warn("auth: failed to save to storage:",t)}}clearStorage(){try{localStorage.removeItem(n),localStorage.removeItem(i)}catch(t){console.warn("auth: failed to clear storage:",t)}}}a=new WeakMap,s=new WeakMap;const f=new p;export{f as a};

frontend/build/_app/immutable/chunks/D__6P984.js

@@ -0,0 +1 @@
+var I=Object.defineProperty;var R=a=>{throw TypeError(a)};var x=(a,e,t)=>e in a?I(a,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):a[e]=t;var w=(a,e,t)=>x(a,typeof e!="symbol"?e+"":e,t),E=(a,e,t)=>e.has(a)||R("Cannot "+t);var s=(a,e,t)=>(E(a,e,"read from private field"),t?t.call(a):e.get(a)),_=(a,e,t)=>e.has(a)?R("Cannot add the same private member more than once"):e instanceof WeakSet?e.add(a):e.set(a,t),M=(a,e,t,i)=>(E(a,e,"write to private field"),i?i.call(a,t):e.set(a,t),t);import{H,I as T,J as O,K as N,M as S,N as Y,h as A,O as F,Q as B,R as C,T as J,U as K,V as L,W as P,X as Q,Y as U,Z as V,_ as W,$ as D}from"./C4An0dnW.js";var l,u,h,p,v,m,g;class X{constructor(e,t=!0){w(this,"anchor");_(this,l,new Map);_(this,u,new Map);_(this,h,new Map);_(this,p,new Set);_(this,v,!0);_(this,m,e=>{if(s(this,l).has(e)){var t=s(this,l).get(e),i=s(this,u).get(t);if(i)H(i),s(this,p).delete(t);else{var n=s(this,h).get(t);n&&(s(this,u).set(t,n.effect),s(this,h).delete(t),n.fragment.lastChild.remove(),this.anchor.before(n.fragment),i=n.effect)}for(const[f,c]of s(this,l)){if(s(this,l).delete(f),f===e)break;const r=s(this,h).get(c);r&&(T(r.effect),s(this,h).delete(c))}for(const[f,c]of s(this,u)){if(f===t||s(this,p).has(f))continue;const r=()=>{if(Array.from(s(this,l).values()).includes(f)){var d=document.createDocumentFragment();B(c,d),d.append(N()),s(this,h).set(f,{effect:c,fragment:d})}else T(c);s(this,p).delete(f),s(this,u).delete(f)};s(this,v)||!i?(s(this,p).add(f),O(c,r,!1)):r()}}});_(this,g,e=>{s(this,l).delete(e);const t=Array.from(s(this,l).values());for(const[i,n]of s(this,h))t.includes(i)||(T(n.effect),s(this,h).delete(i))});this.anchor=e,M(this,v,t)}ensure(e,t){var i=Y,n=C();if(t&&!s(this,u).has(e)&&!s(this,h).has(e))if(n){var f=document.createDocumentFragment(),c=N();f.append(c),s(this,h).set(e,{effect:S(()=>t(c)),fragment:f})}else s(this,u).set(e,S(()=>t(this.anchor)));if(s(this,l).set(i,e),n){for(const[r,o]of s(this,u))r===e?i.unskip_effect(o):i.skip_effect(o);for(const[r,o]of s(this,h))r===e?i.unskip_effect(o.effect):i.skip_effect(o.effect);i.oncommit(s(this,m)),i.ondiscard(s(this,g))}else A&&(this.anchor=F),s(this,m).call(this,i)}}l=new WeakMap,u=new WeakMap,h=new WeakMap,p=new WeakMap,v=new WeakMap,m=new WeakMap,g=new WeakMap;function j(a,e,t=!1){var i;A&&(i=F,K());var n=new X(a),f=t?L:0;function c(r,o){if(A){var d=P(i),b;if(d===Q?b=0:d===U?b=!1:b=parseInt(d.substring(1)),r!==b){var k=V();W(k),n.anchor=k,D(!1),n.ensure(r,o),D(!0);return}}n.ensure(r,o)}J(()=>{var r=!1;e((o,d=0)=>{r=!0,c(d,o)}),r||c(!1,null)},f)}export{X as B,j as i};

frontend/build/_app/immutable/chunks/DyXP65qD.js

@@ -0,0 +1 @@
+import{s as e,p as r}from"./DQNCp18R.js";const t={get error(){return r.error},get status(){return r.status},get url(){return r.url}};e.updated.check;const a=t;export{a as p};

frontend/build/_app/immutable/chunks/Q5CB4WY5.js

@@ -0,0 +1 @@
+import{av as p,K as u,a6 as l,aw as E,B as c,ax as w,ay as g,h as d,O as s,az as y,U as N,aA as x,_ as A,aB as M}from"./C4An0dnW.js";var f;const i=((f=globalThis==null?void 0:globalThis.window)==null?void 0:f.trustedTypes)&&globalThis.window.trustedTypes.createPolicy("svelte-trusted-html",{createHTML:t=>t});function L(t){return(i==null?void 0:i.createHTML(t))??t}function O(t){var r=p("template");return r.innerHTML=L(t.replaceAll("<!>","<!---->")),r.content}function n(t,r){var e=c;e.nodes===null&&(e.nodes={start:t,end:r,a:null,t:null})}function R(t,r){var e=(r&w)!==0,m=(r&g)!==0,a,v=!t.startsWith("<!>");return()=>{if(d)return n(s,null),s;a===void 0&&(a=O(v?t:"<!>"+t),e||(a=l(a)));var o=m||E?document.importNode(a,!0):a.cloneNode(!0);if(e){var T=l(o),h=o.lastChild;n(T,h)}else n(o,o);return o}}function C(t=""){if(!d){var r=u(t+"");return n(r,r),r}var e=s;return e.nodeType!==x?(e.before(e=u()),A(e)):M(e),n(e,e),e}function I(){if(d)return n(s,null),s;var t=document.createDocumentFragment(),r=document.createComment(""),e=u();return t.append(r,e),n(r,e),t}function B(t,r){if(d){var e=c;((e.f&y)===0||e.nodes.end===null)&&(e.nodes.end=s),N();return}t!==null&&t.before(r)}const b="5";var _;typeof window<"u"&&((_=window.__svelte??(window.__svelte={})).v??(_.v=new Set)).add(b);export{B as a,n as b,I as c,R as f,C as t};

frontend/build/_app/immutable/chunks/nIaoZoCo.js

@@ -0,0 +1 @@
+import{u as o,j as t,l as c,k as u}from"./C4An0dnW.js";function l(n){throw new Error("https://svelte.dev/e/lifecycle_outside_component")}function r(n){t===null&&l(),c&&t.l!==null?a(t).m.push(n):o(()=>{const e=u(n);if(typeof e=="function")return e})}function a(n){var e=n.l;return e.u??(e.u={a:[],b:[],m:[]})}export{r as o};

frontend/build/_app/immutable/entry/start.Do4A91T6.js

@@ -0,0 +1 @@
+import{l as o,a as r}from"../chunks/DQNCp18R.js";export{o as load_css,r as start};

frontend/build/_app/immutable/nodes/1.CNv_pgkw.js

@@ -0,0 +1 @@
+import{a as c,f as l}from"../chunks/Q5CB4WY5.js";import{i as v}from"../chunks/BViIIwgj.js";import{p as u,f as _,t as g,a as x,c as e,r as o,s as d}from"../chunks/C4An0dnW.js";import{s as p}from"../chunks/CQQh_IlD.js";import{p as m}from"../chunks/DyXP65qD.js";var b=l("<h1> </h1> <p> </p>",1);function y(f,i){u(i,!1),v();var t=b(),r=_(t),n=e(r,!0);o(r);var a=d(r,2),h=e(a,!0);o(a),g(()=>{var s;p(n,m.status),p(h,(s=m.error)==null?void 0:s.message)}),c(f,t),x()}export{y as component};

frontend/build/_app/immutable/nodes/2.C9GK89sD.js

@@ -0,0 +1 @@
+import{a as t,f as p}from"../chunks/Q5CB4WY5.js";import{i as e}from"../chunks/BViIIwgj.js";import{o as i}from"../chunks/nIaoZoCo.js";import{p as m,a as s}from"../chunks/C4An0dnW.js";import{g as f}from"../chunks/DQNCp18R.js";var n=p('<div class="redirect svelte-1uha8ag"><p>Loading...</p></div>');function u(o,a){m(a,!1),i(()=>{f("/overview",{replaceState:!0})}),e();var r=n();t(o,r),s()}export{u as component};

frontend/build/_app/immutable/nodes/3.BMSY6fJC.js

@@ -0,0 +1 @@
+import{a as b,f as _}from"../chunks/Q5CB4WY5.js";import{i as G}from"../chunks/BViIIwgj.js";import{p as I,a as J,s,c as a,r as e,t as K,g as c,i as M}from"../chunks/C4An0dnW.js";import{s as l}from"../chunks/CQQh_IlD.js";import{i as O}from"../chunks/D__6P984.js";import{t as P}from"../chunks/C5aWxL5p.js";var Q=_('<div class="finance-grid svelte-1ba4c5d"><div class="finance-card svelte-1ba4c5d"><span class="finance-label svelte-1ba4c5d">Total Buy-ins</span> <span class="finance-value currency svelte-1ba4c5d"> </span></div> <div class="finance-card svelte-1ba4c5d"><span class="finance-label svelte-1ba4c5d">Total Rebuys</span> <span class="finance-value currency svelte-1ba4c5d"> </span></div> <div class="finance-card svelte-1ba4c5d"><span class="finance-label svelte-1ba4c5d">Total Add-ons</span> <span class="finance-value currency svelte-1ba4c5d"> </span></div> <div class="finance-card highlight svelte-1ba4c5d"><span class="finance-label svelte-1ba4c5d">Prize Pool</span> <span class="finance-value currency prize svelte-1ba4c5d"> </span></div> <div class="finance-card svelte-1ba4c5d"><span class="finance-label svelte-1ba4c5d">House Fee</span> <span class="finance-value currency svelte-1ba4c5d"> </span></div> <div class="finance-card svelte-1ba4c5d"><span class="finance-label svelte-1ba4c5d">Paid Positions</span> <span class="finance-value number svelte-1ba4c5d"> </span></div></div>'),U=_('<p class="empty-state svelte-1ba4c5d">No financial data available yet.</p>'),V=_('<div class="page-content svelte-1ba4c5d"><h2 class="svelte-1ba4c5d">Financials</h2> <p class="text-secondary svelte-1ba4c5d">Prize pool and payout information.</p> <!></div>');function ea(S,z){I(z,!1),G();var i=V(),T=s(a(i),4);{var F=t=>{const n=M(()=>P.financials);var r=Q(),v=a(r),u=s(a(v),2),q=a(u,!0);e(u),e(v);var d=s(v,2),m=s(a(d),2),A=a(m,!0);e(m),e(d);var o=s(d,2),g=s(a(o),2),B=a(g,!0);e(g),e(o);var p=s(o,2),y=s(a(p),2),H=a(y,!0);e(y),e(p);var f=s(p,2),h=s(a(f),2),N=a(h,!0);e(h),e(f);var x=s(f,2),L=s(a(x),2),R=a(L,!0);e(L),e(x),e(r),K((j,w,C,D,E)=>{l(q,j),l(A,w),l(B,C),l(H,D),l(N,E),l(R,c(n).paid_positions)},[()=>c(n).total_buyin.toLocaleString(),()=>c(n).total_rebuys.toLocaleString(),()=>c(n).total_addons.toLocaleString(),()=>c(n).prize_pool.toLocaleString(),()=>c(n).house_fee.toLocaleString()]),b(t,r)},k=t=>{var n=U();b(t,n)};O(T,t=>{P.financials?t(F):t(k,!1)})}e(i),b(S,i),J()}export{ea as component};

frontend/build/_app/immutable/nodes/4.Ct0ahWmg.js

@@ -0,0 +1 @@
+import{a as f,f as y,t as M}from"../chunks/Q5CB4WY5.js";import{o as V}from"../chunks/nIaoZoCo.js";import{p as W,t as _,a as Y,a0 as Z,c as p,s as u,r as d,g as r,b as A,d as o}from"../chunks/C4An0dnW.js";import{d as tt,e as et,a as g,s as U}from"../chunks/CQQh_IlD.js";import{i as G}from"../chunks/D__6P984.js";import{e as O,i as R,s as q,a as at}from"../chunks/BeLKMLqR.js";import{a as k}from"../chunks/D3f6eoxz.js";import{g as D}from"../chunks/DQNCp18R.js";class C extends Error{constructor(s,a,i){const n=typeof i=="object"&&i!==null&&"error"in i?i.error:a;super(n),this.status=s,this.statusText=a,this.body=i,this.name="ApiError"}}function rt(){return`${window.location.origin}/api/v1`}function st(e){const s={Accept:"application/json"};e&&(s["Content-Type"]="application/json");const a=k.token;return a&&(s.Authorization=`Bearer ${a}`),s}async function it(e){if(e.status===401)throw k.logout(),await D("/login"),new C(401,"Unauthorized",{error:"Session expired"});if(!e.ok){let s;try{s=await e.json()}catch{s={error:e.statusText}}throw new C(e.status,e.statusText,s)}if(e.status!==204)return e.json()}async function m(e,s,a){const i=`${rt()}${s}`,n={method:e,headers:st(a!==void 0),credentials:"same-origin"};a!==void 0&&(n.body=JSON.stringify(a));const v=await fetch(i,n);return it(v)}const nt={get(e){return m("GET",e)},post(e,s){return m("POST",e,s)},put(e,s){return m("PUT",e,s)},patch(e,s){return m("PATCH",e,s)},delete(e){return m("DELETE",e)}};var ot=y("<div></div>"),lt=y('<div class="error-message svelte-1x05zx6" role="alert"> </div>'),ct=y('<button class="numpad-btn touch-target svelte-1x05zx6"> </button>'),ut=y('<main class="login-container svelte-1x05zx6"><div class="login-card svelte-1x05zx6"><div class="logo svelte-1x05zx6"><h1 class="svelte-1x05zx6">Felt</h1> <p class="subtitle svelte-1x05zx6">Tournament Manager</p></div> <div class="pin-display svelte-1x05zx6" role="status"></div> <!> <div class="numpad svelte-1x05zx6"><!> <button class="numpad-btn numpad-fn touch-target svelte-1x05zx6" aria-label="Clear PIN">CLR</button> <button class="numpad-btn touch-target svelte-1x05zx6" aria-label="Digit 0">0</button> <button class="numpad-btn numpad-fn touch-target svelte-1x05zx6" aria-label="Delete last digit">DEL</button></div> <button class="submit-btn touch-target svelte-1x05zx6"><!></button></div></main>');function bt(e,s){W(s,!0);let a=A(""),i=A(""),n=A(!1);const v=6;V(()=>{k.isAuthenticated&&D("/")});function w(t){r(a).length>=v||(o(a,r(a)+t),o(i,""))}function I(){o(a,r(a).slice(0,-1),!0),o(i,"")}function N(){o(a,""),o(i,"")}async function j(){if(!(r(a).length<4||r(n))){o(n,!0),o(i,"");try{const t=await nt.post("/auth/login",{pin:r(a)});k.login(t.token,{id:t.operator.id,name:t.operator.name,role:t.operator.role}),await D("/")}catch(t){t instanceof C?t.status===429?o(i,"Too many attempts. Please wait."):t.status===401?o(i,"Invalid PIN. Try again."):o(i,t.message,!0):o(i,"Connection error. Check your network."),o(a,"")}finally{o(n,!1)}}}function F(t){t.key>="0"&&t.key<="9"?w(t.key):t.key==="Backspace"?I():t.key==="Enter"?j():t.key==="Escape"&&N()}var z=ut();et("keydown",Z,F);var S=p(z),x=u(p(S),2);O(x,21,()=>Array(v),R,(t,l,c)=>{var b=ot();let H;_(()=>H=at(b,1,"pin-dot svelte-1x05zx6",null,H,{filled:c<r(a).length})),f(t,b)}),d(x);var $=u(x,2);{var J=t=>{var l=lt(),c=p(l,!0);d(l),_(()=>U(c,r(i))),f(t,l)};G($,t=>{r(i)&&t(J)})}var T=u($,2),L=p(T);O(L,16,()=>["1","2","3","4","5","6","7","8","9"],R,(t,l)=>{var c=ct(),b=p(c,!0);d(c),_(()=>{c.disabled=r(n)||r(a).length>=v,q(c,"aria-label",`Digit ${l??""}`),U(b,l)}),g("click",c,()=>w(l)),f(t,c)});var E=u(L,2),P=u(E,2),B=u(P,2);d(T);var h=u(T,2),K=p(h);{var X=t=>{var l=M("Signing in...");f(t,l)},Q=t=>{var l=M("Sign In");f(t,l)};G(K,t=>{r(n)?t(X):t(Q,!1)})}d(h),d(S),d(z),_(()=>{q(x,"aria-label",`PIN entered: ${r(a).length??""} digits`),E.disabled=r(n),P.disabled=r(n)||r(a).length>=v,B.disabled=r(n)||r(a).length===0,h.disabled=r(a).length<4||r(n)}),g("click",E,N),g("click",P,()=>w("0")),g("click",B,I),g("click",h,j),f(e,z),Y()}tt(["click"]);export{bt as component};

frontend/build/_app/immutable/nodes/5.CrKjY73y.js

@@ -0,0 +1 @@
+import{a as _,f as b}from"../chunks/Q5CB4WY5.js";import{i as x}from"../chunks/BViIIwgj.js";import{p as k,t as w,a as O,s as e,c as a,r as t}from"../chunks/C4An0dnW.js";import{d as S,a as U,s as m}from"../chunks/CQQh_IlD.js";import{a as o}from"../chunks/D3f6eoxz.js";import{g as y}from"../chunks/DQNCp18R.js";var L=b('<div class="page-content svelte-hq0atu"><h2 class="svelte-hq0atu">More</h2> <p class="text-secondary svelte-hq0atu">Settings and additional options.</p> <div class="menu-list svelte-hq0atu"><div class="menu-item svelte-hq0atu"><span class="menu-label svelte-hq0atu">Operator</span> <span class="menu-value svelte-hq0atu"> </span></div> <div class="menu-item svelte-hq0atu"><span class="menu-label svelte-hq0atu">Role</span> <span class="menu-value svelte-hq0atu"> </span></div> <hr class="divider svelte-hq0atu"/> <button class="menu-item menu-action danger touch-target svelte-hq0atu"><span class="menu-label svelte-hq0atu">Sign Out</span></button></div></div>');function C(c,d){k(d,!1);function h(){o.logout(),y("/login")}x();var s=L(),r=e(a(s),4),n=a(r),i=e(a(n),2),g=a(i,!0);t(i),t(n);var l=e(n,2),u=e(a(l),2),f=a(u,!0);t(u),t(l);var q=e(l,4);t(r),t(s),w(()=>{var v,p;m(g,((v=o.operator)==null?void 0:v.name)??"Unknown"),m(f,((p=o.operator)==null?void 0:p.role)??"Unknown")}),U("click",q,h),_(c,s),O()}S(["click"]);export{C as component};

frontend/build/_app/immutable/nodes/6.CMmeTvWv.js

@@ -0,0 +1 @@
+import{a as c,f as d}from"../chunks/Q5CB4WY5.js";import{i as N}from"../chunks/BViIIwgj.js";import{p as $,a as j,s as a,c as s,r as e,t as B}from"../chunks/C4An0dnW.js";import{s as r}from"../chunks/CQQh_IlD.js";import{i as L}from"../chunks/D__6P984.js";import{t}from"../chunks/C5aWxL5p.js";var O=d('<div class="stats-grid svelte-14qseeg"><div class="stat-card svelte-14qseeg"><span class="stat-label svelte-14qseeg">Players</span> <span class="stat-value number svelte-14qseeg"> </span></div> <div class="stat-card svelte-14qseeg"><span class="stat-label svelte-14qseeg">Tables</span> <span class="stat-value number svelte-14qseeg"> </span></div> <div class="stat-card svelte-14qseeg"><span class="stat-label svelte-14qseeg">Level</span> <span class="stat-value number svelte-14qseeg"> </span></div> <div class="stat-card svelte-14qseeg"><span class="stat-label svelte-14qseeg">Blinds</span> <span class="stat-value blinds svelte-14qseeg"> </span></div></div>'),S=d('<p class="empty-state svelte-14qseeg">No active tournament. Start or join a tournament to see the overview.</p>'),z=d('<div class="page-content svelte-14qseeg"><h2 class="svelte-14qseeg">Overview</h2> <p class="text-secondary svelte-14qseeg">Tournament dashboard — detailed views coming in Plan N.</p> <!></div>');function H(f,u){$(u,!1),N();var i=z(),h=a(s(i),4);{var x=l=>{var v=O(),n=s(v),m=a(s(n),2),y=s(m);e(m),e(n);var o=a(n,2),g=a(s(o),2),P=s(g,!0);e(g),e(o);var p=a(o,2),_=a(s(p),2),w=s(_,!0);e(_),e(p);var q=a(p,2),b=a(s(q),2),T=s(b);e(b),e(q),e(v),B(()=>{r(y,`${t.remainingPlayers??""}/${t.totalPlayers??""}`),r(P,t.activeTables),r(w,t.clock.level),r(T,`${t.clock.small_blind??""}/${t.clock.big_blind??""}`)}),c(l,v)},k=l=>{var v=S();c(l,v)};L(h,l=>{t.clock?l(x):l(k,!1)})}e(i),c(f,i),j()}export{H as component};

frontend/build/_app/immutable/nodes/7.0Z-UCw0W.js

@@ -0,0 +1 @@
+import{a as o,f as i}from"../chunks/Q5CB4WY5.js";import{i as n}from"../chunks/BViIIwgj.js";import{p as b,a as p,s as u,c,r as d}from"../chunks/C4An0dnW.js";import{t as m}from"../chunks/C5aWxL5p.js";import{D as y}from"../chunks/WPMya0VZ.js";var h=i('<div class="page-content svelte-wtkzqx"><h2 class="svelte-wtkzqx">Players</h2> <p class="text-secondary svelte-wtkzqx">Registered players and chip counts.</p> <!></div>');function x(a,t){b(t,!1);const s=[{key:"name",label:"Name",sortable:!0},{key:"status",label:"Status",sortable:!0},{key:"chips",label:"Chips",sortable:!0,align:"right",render:r=>r.chips.toLocaleString()},{key:"table_id",label:"Table",hideMobile:!0,sortable:!0},{key:"seat",label:"Seat",hideMobile:!0,sortable:!0,align:"center"},{key:"rebuys",label:"Rebuys",hideMobile:!0,sortable:!0,align:"center"}];n();var e=h(),l=u(c(e),4);y(l,{get columns(){return s},get data(){return m.players},sortable:!0,searchable:!0,loading:!1,emptyMessage:"No players registered yet",rowKey:r=>String(r.id),swipeActions:[{id:"bust",label:"Bust",color:"var(--color-error)",handler:()=>{}},{id:"rebuy",label:"Rebuy",color:"var(--color-primary)",handler:()=>{}}]}),d(e),o(a,e),p()}export{x as component};

frontend/build/_app/immutable/nodes/8.fn5hverG.js

@@ -0,0 +1 @@
+import{a as o,f as i}from"../chunks/Q5CB4WY5.js";import{p as b,a as p,g as c,x as u,s as d,c as m,r as g}from"../chunks/C4An0dnW.js";import{t as f}from"../chunks/C5aWxL5p.js";import{D as y}from"../chunks/WPMya0VZ.js";var v=i('<div class="page-content svelte-bf0doe"><h2 class="svelte-bf0doe">Tables</h2> <p class="text-secondary svelte-bf0doe">Active tables and seating.</p> <!></div>');function D(t,s){b(s,!0);const l=[{key:"number",label:"Table #",sortable:!0,align:"center"},{key:"seats",label:"Seats",sortable:!0,align:"center"},{key:"player_count",label:"Players",sortable:!0,align:"center"},{key:"is_final_table",label:"Final",hideMobile:!0,sortable:!0,align:"center",render:e=>e.is_final_table?"Yes":""}];let r=u(()=>f.tables.map(e=>({...e,player_count:e.players.length})));var a=v(),n=d(m(a),4);y(n,{get columns(){return l},get data(){return c(r)},sortable:!0,searchable:!1,loading:!1,emptyMessage:"No tables set up yet",rowKey:e=>String(e.id)}),g(a),o(t,a),p()}export{D as component};

frontend/build/_app/version.json

@@ -0,0 +1 @@
+{"version":"1772334772507"}

frontend/build/financials.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="./favicon.png" />
+		<title>Felt</title>
+		<link href="./_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: new URL(".", location).pathname.slice(0, -1)
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("./_app/immutable/entry/start.Do4A91T6.js"),
+						import("./_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/build/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="/favicon.png" />
+		<title>Felt</title>
+		<link href="/_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="/_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="/_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: ""
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("/_app/immutable/entry/start.Do4A91T6.js"),
+						import("/_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/build/login.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="./favicon.png" />
+		<title>Felt</title>
+		<link href="./_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: new URL(".", location).pathname.slice(0, -1)
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("./_app/immutable/entry/start.Do4A91T6.js"),
+						import("./_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/build/more.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="./favicon.png" />
+		<title>Felt</title>
+		<link href="./_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: new URL(".", location).pathname.slice(0, -1)
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("./_app/immutable/entry/start.Do4A91T6.js"),
+						import("./_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/build/overview.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="./favicon.png" />
+		<title>Felt</title>
+		<link href="./_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: new URL(".", location).pathname.slice(0, -1)
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("./_app/immutable/entry/start.Do4A91T6.js"),
+						import("./_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/build/players.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="./favicon.png" />
+		<title>Felt</title>
+		<link href="./_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: new URL(".", location).pathname.slice(0, -1)
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("./_app/immutable/entry/start.Do4A91T6.js"),
+						import("./_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/build/tables.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="./favicon.png" />
+		<title>Felt</title>
+		<link href="./_app/immutable/entry/start.Do4A91T6.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DQNCp18R.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C4An0dnW.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/nIaoZoCo.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.Dwn0pdp1.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CQQh_IlD.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Q5CB4WY5.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D__6P984.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C48rM6KF.js" rel="modulepreload">
+		
+	</head>
+	<body>
+		<div style="display: contents">
+			<script>
+				{
+					__sveltekit_og1wdu = {
+						base: new URL(".", location).pathname.slice(0, -1)
+					};
+
+					const element = document.currentScript.parentElement;
+
+					Promise.all([
+						import("./_app/immutable/entry/start.Do4A91T6.js"),
+						import("./_app/immutable/entry/app.Dwn0pdp1.js")
+					]).then(([kit, app]) => {
+						kit.start(app, element);
+					});
+				}
+			</script>
+		</div>
+	</body>
+</html>

frontend/embed.go

@@ -0,0 +1,38 @@
+package frontend
+
+import (
+	"embed"
+	"io/fs"
+	"net/http"
+)
+
+//go:embed all:build
+var files embed.FS
+
+// Handler returns an http.Handler that serves the embedded SvelteKit SPA.
+// Unknown paths fall back to index.html for client-side routing.
+func Handler() http.Handler {
+	fsys, _ := fs.Sub(files, "build")
+	fileServer := http.FileServer(http.FS(fsys))
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Try to serve static file first
+		path := r.URL.Path
+		if path == "/" {
+			path = "/index.html"
+		}
+
+		// Check if the file exists in the embedded filesystem
+		cleanPath := path[1:] // Remove leading slash
+		if cleanPath == "" {
+			cleanPath = "index.html"
+		}
+
+		if _, err := fs.Stat(fsys, cleanPath); err != nil {
+			// SPA fallback: serve index.html for client-side routing
+			r.URL.Path = "/"
+		}
+
+		fileServer.ServeHTTP(w, r)
+	})
+}

frontend/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "felt-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.8",
+    "@sveltejs/kit": "^2.16.0",
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
+  }
+}

frontend/src/app.css

@@ -0,0 +1,138 @@
+@import '$lib/theme/catppuccin.css';
+
+/* ============================================
+   Reset
+   ============================================ */
+*,
+*::before,
+*::after {
+	box-sizing: border-box;
+	margin: 0;
+	padding: 0;
+}
+
+/* ============================================
+   Base styles
+   ============================================ */
+html {
+	font-family: var(--font-body);
+	font-size: 16px;
+	line-height: var(--leading-normal);
+	color: var(--color-text);
+	background-color: var(--color-bg);
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+	/* Prevent layout shift from scrollbar */
+	scrollbar-gutter: stable;
+}
+
+body {
+	min-height: 100dvh;
+	color: var(--color-text);
+	background-color: var(--color-bg);
+}
+
+/* ============================================
+   Touch targets & interaction
+   Poker room: TD using phone with one hand
+   ============================================ */
+button,
+a,
+input,
+select,
+textarea,
+[role='button'],
+[role='tab'],
+[role='menuitem'] {
+	/* Prevent double-tap zoom on mobile */
+	touch-action: manipulation;
+}
+
+/* Minimum 48px touch target for all interactive elements */
+.touch-target,
+button,
+[role='button'],
+[role='tab'] {
+	min-height: var(--touch-target);
+	min-width: var(--touch-target);
+}
+
+/* Active/pressed state for tactile feedback */
+button:active,
+[role='button']:active,
+[role='tab']:active,
+.touch-target:active {
+	transform: scale(0.97);
+	opacity: 0.9;
+	transition: transform var(--transition-fast), opacity var(--transition-fast);
+}
+
+/* Focus visible for keyboard accessibility */
+:focus-visible {
+	outline: 2px solid var(--color-primary);
+	outline-offset: 2px;
+}
+
+/* Remove default focus ring for mouse/touch users */
+:focus:not(:focus-visible) {
+	outline: none;
+}
+
+/* ============================================
+   Scrollbar styling (dark theme)
+   ============================================ */
+::-webkit-scrollbar {
+	width: 8px;
+	height: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: var(--color-bg);
+}
+
+::-webkit-scrollbar-thumb {
+	background: var(--color-surface-active);
+	border-radius: var(--radius-full);
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: var(--color-overlay);
+}
+
+/* Firefox */
+* {
+	scrollbar-width: thin;
+	scrollbar-color: var(--color-surface-active) var(--color-bg);
+}
+
+/* ============================================
+   Typography helpers
+   ============================================ */
+.font-mono {
+	font-family: var(--font-mono);
+}
+
+/* Timer/number display — always monospace */
+.timer,
+.number,
+.blinds,
+.chips,
+.currency {
+	font-family: var(--font-mono);
+	font-variant-numeric: tabular-nums;
+}
+
+/* ============================================
+   Common utility classes
+   ============================================ */
+.visually-hidden {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip: rect(0, 0, 0, 0);
+	white-space: nowrap;
+	border: 0;
+}

frontend/src/app.d.ts

@@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};

frontend/src/app.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-theme="mocha">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.png" />
+		<title>Felt</title>
+		%sveltekit.head%
+	</head>
+	<body>
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

frontend/src/lib/api.ts

@@ -0,0 +1,124 @@
+/**
+ * HTTP API client for the Felt backend.
+ *
+ * Auto-detects base URL from current host, attaches JWT from auth store,
+ * handles 401 responses by clearing auth state and redirecting to login.
+ */
+
+import { auth } from '$lib/stores/auth.svelte';
+import { goto } from '$app/navigation';
+
+/** Typed API error with status code and message. */
+export class ApiError extends Error {
+	constructor(
+		public readonly status: number,
+		public readonly statusText: string,
+		public readonly body: unknown
+	) {
+		const msg = typeof body === 'object' && body !== null && 'error' in body
+			? (body as { error: string }).error
+			: statusText;
+		super(msg);
+		this.name = 'ApiError';
+	}
+}
+
+/** Base URL for API requests — auto-detected from current host. */
+function getBaseUrl(): string {
+	return `${window.location.origin}/api/v1`;
+}
+
+/** Build headers with JWT auth and content type. */
+function buildHeaders(hasBody: boolean): HeadersInit {
+	const headers: Record<string, string> = {
+		'Accept': 'application/json'
+	};
+
+	if (hasBody) {
+		headers['Content-Type'] = 'application/json';
+	}
+
+	const token = auth.token;
+	if (token) {
+		headers['Authorization'] = `Bearer ${token}`;
+	}
+
+	return headers;
+}
+
+/** Handle API response — parse JSON, handle errors. */
+async function handleResponse<T>(response: Response): Promise<T> {
+	if (response.status === 401) {
+		// Token expired or invalid — clear auth and redirect to login
+		auth.logout();
+		await goto('/login');
+		throw new ApiError(401, 'Unauthorized', { error: 'Session expired' });
+	}
+
+	if (!response.ok) {
+		let body: unknown;
+		try {
+			body = await response.json();
+		} catch {
+			body = { error: response.statusText };
+		}
+		throw new ApiError(response.status, response.statusText, body);
+	}
+
+	// Handle 204 No Content
+	if (response.status === 204) {
+		return undefined as T;
+	}
+
+	return response.json() as Promise<T>;
+}
+
+/** Perform an API request. */
+async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+	const url = `${getBaseUrl()}${path}`;
+
+	const init: RequestInit = {
+		method,
+		headers: buildHeaders(body !== undefined),
+		credentials: 'same-origin'
+	};
+
+	if (body !== undefined) {
+		init.body = JSON.stringify(body);
+	}
+
+	const response = await fetch(url, init);
+	return handleResponse<T>(response);
+}
+
+/**
+ * HTTP API client.
+ *
+ * All methods auto-attach JWT from auth store and handle 401 responses.
+ */
+export const api = {
+	/** GET request. */
+	get<T>(path: string): Promise<T> {
+		return request<T>('GET', path);
+	},
+
+	/** POST request with JSON body. */
+	post<T>(path: string, body?: unknown): Promise<T> {
+		return request<T>('POST', path, body);
+	},
+
+	/** PUT request with JSON body. */
+	put<T>(path: string, body?: unknown): Promise<T> {
+		return request<T>('PUT', path, body);
+	},
+
+	/** PATCH request with JSON body. */
+	patch<T>(path: string, body?: unknown): Promise<T> {
+		return request<T>('PATCH', path, body);
+	},
+
+	/** DELETE request. */
+	delete<T>(path: string): Promise<T> {
+		return request<T>('DELETE', path);
+	}
+};

frontend/src/lib/components/ActivityFeed.svelte

@@ -0,0 +1,203 @@
+<script lang="ts">
+	import type { ActivityEntry } from '$lib/stores/tournament.svelte';
+
+	/**
+	 * Activity feed showing recent tournament actions.
+	 *
+	 * Displays last N actions in reverse chronological order with
+	 * type-specific icons, colors, and relative timestamps.
+	 * New entries animate in from the top.
+	 */
+
+	interface Props {
+		entries: ActivityEntry[];
+		/** Maximum entries to display. */
+		limit?: number;
+		/** Show "View all" link. */
+		showViewAll?: boolean;
+		/** Handler for "View all" click. */
+		onviewall?: () => void;
+	}
+
+	let {
+		entries,
+		limit = 15,
+		showViewAll = true,
+		onviewall
+	}: Props = $props();
+
+	let visibleEntries = $derived(entries.slice(0, limit));
+
+	/** Icon and color mapping for activity types. */
+	function getEntryStyle(type: string): { icon: string; color: string } {
+		switch (type) {
+			case 'buyin':
+			case 'buy_in':
+				return { icon: '\u{1F464}', color: 'var(--color-success)' };
+			case 'bust':
+			case 'elimination':
+				return { icon: '\u{2716}', color: 'var(--color-error)' };
+			case 'rebuy':
+				return { icon: '\u{1F504}', color: 'var(--color-primary)' };
+			case 'addon':
+			case 'add_on':
+				return { icon: '\u{2B06}', color: 'var(--color-warning)' };
+			case 'level_change':
+				return { icon: '\u{1F552}', color: 'var(--color-clock)' };
+			case 'break_start':
+				return { icon: '\u{2615}', color: 'var(--color-break)' };
+			case 'break_end':
+				return { icon: '\u{25B6}', color: 'var(--color-break)' };
+			case 'seat_move':
+				return { icon: '\u{2194}', color: 'var(--ctp-lavender)' };
+			case 'table_break':
+				return { icon: '\u{1F4CB}', color: 'var(--ctp-peach)' };
+			case 'reentry':
+			case 're_entry':
+				return { icon: '\u{1F503}', color: 'var(--ctp-sapphire)' };
+			case 'deal':
+			case 'chop':
+				return { icon: '\u{1F91D}', color: 'var(--color-prize)' };
+			default:
+				return { icon: '\u{2022}', color: 'var(--color-text-muted)' };
+		}
+	}
+
+	/** Format timestamp as relative time ("2m ago", "1h ago"). */
+	function formatRelativeTime(timestamp: number): string {
+		const now = Date.now();
+		const ts = timestamp > 1e12 ? timestamp : timestamp * 1000; // Handle both ms and seconds
+		const diff = Math.max(0, Math.floor((now - ts) / 1000));
+
+		if (diff < 5) return 'just now';
+		if (diff < 60) return `${diff}s ago`;
+		if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+		if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+		return `${Math.floor(diff / 86400)}d ago`;
+	}
+</script>
+
+<div class="activity-feed">
+	<div class="feed-header">
+		<h3 class="feed-title">Recent Activity</h3>
+		{#if showViewAll && onviewall && entries.length > limit}
+			<button class="view-all-btn touch-target" onclick={onviewall}>
+				View all
+			</button>
+		{/if}
+	</div>
+
+	{#if visibleEntries.length === 0}
+		<p class="feed-empty">No activity yet</p>
+	{:else}
+		<div class="feed-list" role="log" aria-label="Tournament activity feed">
+			{#each visibleEntries as entry (entry.id)}
+				{@const style = getEntryStyle(entry.type)}
+				<div class="feed-entry" style="--entry-color: {style.color}">
+					<span class="entry-icon" aria-hidden="true">{style.icon}</span>
+					<span class="entry-message">{entry.message}</span>
+					<span class="entry-time">{formatRelativeTime(entry.timestamp)}</span>
+				</div>
+			{/each}
+		</div>
+	{/if}
+</div>
+
+<style>
+	.activity-feed {
+		display: flex;
+		flex-direction: column;
+		gap: var(--space-2);
+	}
+
+	.feed-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+	}
+
+	.feed-title {
+		font-size: var(--text-sm);
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: var(--color-text-muted);
+	}
+
+	.view-all-btn {
+		background: none;
+		border: none;
+		font-size: var(--text-sm);
+		color: var(--color-primary);
+		cursor: pointer;
+		padding: var(--space-1) var(--space-2);
+		border-radius: var(--radius-sm);
+		min-height: auto;
+		min-width: auto;
+	}
+
+	.view-all-btn:hover {
+		text-decoration: underline;
+	}
+
+	.feed-list {
+		display: flex;
+		flex-direction: column;
+	}
+
+	.feed-entry {
+		display: flex;
+		align-items: center;
+		gap: var(--space-2);
+		padding: var(--space-2) var(--space-3);
+		border-bottom: 1px solid var(--color-border);
+		animation: slide-in 200ms ease-out;
+	}
+
+	.feed-entry:last-child {
+		border-bottom: none;
+	}
+
+	@keyframes slide-in {
+		from {
+			opacity: 0;
+			transform: translateY(-8px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+
+	.entry-icon {
+		flex-shrink: 0;
+		width: 1.5em;
+		text-align: center;
+		font-size: var(--text-base);
+	}
+
+	.entry-message {
+		flex: 1;
+		font-size: var(--text-sm);
+		color: var(--color-text);
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.entry-time {
+		flex-shrink: 0;
+		font-size: var(--text-xs);
+		color: var(--color-text-muted);
+		font-family: var(--font-mono);
+	}
+
+	.feed-empty {
+		text-align: center;
+		padding: var(--space-6);
+		color: var(--color-text-muted);
+		font-style: italic;
+		font-size: var(--text-sm);
+	}
+</style>