docs: register TR-ops-001/002/003 and fix story-002 GDD traceability

.claude/docs/technical-preferences.md

@@ -5,44 +5,44 @@
 
 ## Engine & Language
 
-- **Engine**: [TO BE CONFIGURED — run /setup-engine]
-- **Language**: [TO BE CONFIGURED]
-- **Rendering**: [TO BE CONFIGURED]
-- **Physics**: [TO BE CONFIGURED]
+- **Engine**: React Native (Expo SDK) + Node.js game server
+- **Language**: TypeScript (client + server)
+- **Rendering**: React Native renderer (Skia / Canvas TBD per graphics needs)
+- **Physics**: Custom server-authoritative game logic (no engine physics)
 
 ## Input & Platform
 
 <!-- Written by /setup-engine. Read by /ux-design, /ux-review, /test-setup, /team-ui, and /dev-story -->
 <!-- to scope interaction specs, test helpers, and implementation to the correct input methods. -->
 
-- **Target Platforms**: [TO BE CONFIGURED — e.g., PC, Console, Mobile, Web]
-- **Input Methods**: [TO BE CONFIGURED — e.g., Keyboard/Mouse, Gamepad, Touch, Mixed]
-- **Primary Input**: [TO BE CONFIGURED — the dominant input for this game]
-- **Gamepad Support**: [TO BE CONFIGURED — Full / Partial / None]
-- **Touch Support**: [TO BE CONFIGURED — Full / Partial / None]
-- **Platform Notes**: [TO BE CONFIGURED — any platform-specific UX constraints]
+- **Target Platforms**: iOS + Android
+- **Input Methods**: Touch
+- **Primary Input**: Touch
+- **Gamepad Support**: None
+- **Touch Support**: Full
+- **Platform Notes**: All UI must handle safe area insets (notch, home indicator). No hover-only interactions. Test on both iOS and Android physical devices before marking UI stories done.
 
 ## Naming Conventions
 
-- **Classes**: [TO BE CONFIGURED]
-- **Variables**: [TO BE CONFIGURED]
-- **Signals/Events**: [TO BE CONFIGURED]
-- **Files**: [TO BE CONFIGURED]
-- **Scenes/Prefabs**: [TO BE CONFIGURED]
-- **Constants**: [TO BE CONFIGURED]
+- **Classes/Components**: PascalCase (e.g., `PlayerCard`, `MatchScreen`)
+- **Variables**: camelCase (e.g., `moveSpeed`, `currentHealth`)
+- **Events/Callbacks**: camelCase with `on` prefix (e.g., `onMatchEnd`, `onPlayerJoin`)
+- **Files**: PascalCase for React components (`MatchScreen.tsx`), camelCase for utilities (`matchUtils.ts`)
+- **Scenes/Prefabs**: N/A — React Native screens use PascalCase component directories
+- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_HEALTH`, `TICK_RATE_MS`)
 
 ## Performance Budgets
 
-- **Target Framerate**: [TO BE CONFIGURED]
-- **Frame Budget**: [TO BE CONFIGURED]
-- **Draw Calls**: [TO BE CONFIGURED]
-- **Memory Ceiling**: [TO BE CONFIGURED]
+- **Target Framerate**: 60fps
+- **Frame Budget**: 16.6ms (JS thread; monitor with Flipper or React Native Perf Monitor)
+- **Draw Calls**: N/A — React Native renderer; monitor JS thread frame time instead
+- **Memory Ceiling**: 200MB (mid-range mobile device target)
 
 ## Testing
 
-- **Framework**: [TO BE CONFIGURED]
-- **Minimum Coverage**: [TO BE CONFIGURED]
-- **Required Tests**: Balance formulas, gameplay systems, networking (if applicable)
+- **Framework**: Jest + React Native Testing Library
+- **Minimum Coverage**: 70% for game logic (matchmaking, MMR, reward calculation); advisory for UI components
+- **Required Tests**: Balance formulas, matchmaking logic, MMR calculation, reward distribution, game state transitions
 
 ## Forbidden Patterns
 
@@ -51,7 +51,7 @@
 
 ## Allowed Libraries / Addons
 
-<!-- Add approved third-party dependencies here -->
+<!-- Add approved third-party dependencies here when actively integrating, not speculatively -->
 - [None configured yet — add as dependencies are approved]
 
 ## Architecture Decisions Log
@@ -63,25 +63,24 @@
 
 <!-- Written by /setup-engine when engine is configured. -->
 <!-- Read by /code-review, /architecture-decision, /architecture-review, and team skills -->
-<!-- to know which specialist to spawn for engine-specific validation. -->
+<!-- to know which specialist to spawn for code-area-specific validation. -->
 
-- **Primary**: [TO BE CONFIGURED — run /setup-engine]
-- **Language/Code Specialist**: [TO BE CONFIGURED]
-- **Shader Specialist**: [TO BE CONFIGURED]
-- **UI Specialist**: [TO BE CONFIGURED]
-- **Additional Specialists**: [TO BE CONFIGURED]
-- **Routing Notes**: [TO BE CONFIGURED]
+- **Primary**: lead-programmer
+- **Game Logic Specialist**: gameplay-programmer (match mechanics, character abilities, game state)
+- **Networking Specialist**: network-programmer (Socket.io real-time sync, matchmaking, lag compensation)
+- **UI Specialist**: ui-programmer (React Native screens, HUD, menus, animations)
+- **Security Specialist**: security-engineer (Supabase auth, RevenueCat IAP validation, anti-cheat)
+- **Routing Notes**: This is a React Native / Node.js project — game engine specialists (Godot, Unity, Unreal) do not apply. Route by functional area using the table below.
 
 ### File Extension Routing
 
 <!-- Skills use this table to select the right specialist per file type. -->
-<!-- If a row says [TO BE CONFIGURED], fall back to Primary for that file type. -->
 
 | File Extension / Type | Specialist to Spawn |
 |-----------------------|---------------------|
-| Game code (primary language) | [TO BE CONFIGURED] |
-| Shader / material files | [TO BE CONFIGURED] |
-| UI / screen files | [TO BE CONFIGURED] |
-| Scene / prefab / level files | [TO BE CONFIGURED] |
-| Native extension / plugin files | [TO BE CONFIGURED] |
-| General architecture review | Primary |
+| Game mechanics (.ts in game logic modules) | gameplay-programmer |
+| React Native UI screens (.tsx) | ui-programmer |
+| Real-time server code (.ts in server/) | network-programmer |
+| Auth / IAP / security code | security-engineer |
+| Native modules (.m, .java, .kt) | lead-programmer |
+| General architecture review | lead-programmer |

.gitignore

@@ -91,6 +91,20 @@ Saved/
 *.cso
 *.dxbc
 
+# === React Native / Expo ===
+.expo/
+ios/
+android/
+*.jks
+*.keystore
+mobile/.expo/
+mobile/ios/
+mobile/android/
+
+# === Node.js / Server ===
+server/dist/
+*.tsbuildinfo
+
 # === Temporary and Cache ===
 *.tmp
 *.temp
@@ -111,11 +125,19 @@ node_modules/
 .env
 .env.local
 .env.*.local
+.env.production
+.env.staging
 *.pem
 *.key
 credentials.json
 secrets.json
 
+# === IDE: Obsidian ===
+.obsidian/
+
+# === Scratch / Unnamed files ===
+Unbenannt*
+
 # === Large Binary Assets (use Git LFS instead) ===
 # Uncomment and configure with Git LFS for your project:
 # *.png

CLAUDE.md

@@ -5,22 +5,22 @@ Each agent owns a specific domain, enforcing separation of concerns and quality.
 
 ## Technology Stack
 
-- **Engine**: [CHOOSE: Godot 4 / Unity / Unreal Engine 5]
-- **Language**: [CHOOSE: GDScript / C# / C++ / Blueprint]
+- **Engine**: React Native (Expo SDK) + Node.js game server
+- **Language**: TypeScript (client + server)
 - **Version Control**: Git with trunk-based development
-- **Build System**: [SPECIFY after choosing engine]
-- **Asset Pipeline**: [SPECIFY after choosing engine]
+- **Build System**: Expo EAS Build (mobile), npm/Node.js (server)
+- **Asset Pipeline**: Expo asset system + manual optimization pipeline
 
-> **Note**: Engine-specialist agents exist for Godot, Unity, and Unreal with
-> dedicated sub-specialists. Use the set matching your engine.
+> **Note**: This project uses React Native/Expo, not a traditional game engine.
+> Route code review by functional area — see Engine Specialists in technical-preferences.md.
 
 ## Project Structure
 
 @.claude/docs/directory-structure.md
 
 ## Engine Version Reference
 
-@docs/engine-reference/godot/VERSION.md
+@docs/engine-reference/react-native/VERSION.md
 
 ## Technical Preferences
 

DEPLOY.md

@@ -0,0 +1,169 @@
+# BRAWLZONE — Deployment Guide
+
+## Stack
+- **Server**: Node.js 22 on Railway
+- **Database**: PostgreSQL via Supabase
+- **Cache**: Redis (Railway add-on)
+- **Auth**: Supabase Auth (JWT RS256)
+- **Mobile**: React Native + Expo EAS Build (iOS + Android)
+
+---
+
+## 1. Supabase Setup
+
+### Create project
+1. Go to https://supabase.com → New Project
+2. Note your **Project URL** and **anon key** (for mobile) and **service key** (for server)
+3. Note your **JWT Secret** (Settings → API → JWT Settings)
+
+### Apply schema
+1. Open Supabase Dashboard → SQL Editor
+2. Run `server/src/db/schema.sql` — this creates all tables and the auto-profile trigger
+
+### Enable Auth providers
+- Email/Password: enabled by default
+- Google OAuth: Authentication → Providers → Google → enable + add OAuth credentials
+- Apple OAuth: Authentication → Providers → Apple → enable + add Apple credentials
+
+---
+
+## 2. Server Deployment (Railway)
+
+### Environment variables
+```
+PORT=3001
+NODE_ENV=production
+CLIENT_ORIGIN=exp://your-expo-app-url   # or your production app URL
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=eyJ...             # service role key (never expose to client)
+SUPABASE_JWT_SECRET=your-jwt-secret
+DATABASE_URL=postgresql://...           # from Supabase: Settings → Database → Connection string
+REDIS_URL=redis://...                   # from Railway Redis add-on
+```
+
+### Deploy
+```bash
+# Push to main — Railway auto-deploys
+git push origin main
+
+# Or manually via CLI
+railway up
+```
+
+### Verify
+```
+curl https://your-railway-url.railway.app/health
+# → { "status": "ok", "ts": 1234567890 }
+```
+
+---
+
+## 3. Mobile App (Expo EAS)
+
+### Environment variables
+Create `mobile/.env` (gitignored):
+```
+EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+EXPO_PUBLIC_SUPABASE_ANON_KEY=eyJ...    # anon/public key (safe to expose)
+EXPO_PUBLIC_SERVER_URL=https://your-railway-url.railway.app
+```
+
+### Build
+```bash
+cd mobile
+npm install
+
+# Development build (runs on Expo Go or dev client)
+npx expo start
+
+# Production build via EAS
+eas build --platform ios
+eas build --platform android
+
+# Submit to stores
+eas submit --platform ios
+eas submit --platform android
+```
+
+### OTA updates
+```bash
+eas update --branch production --message "Bug fix"
+```
+
+---
+
+## 4. Local Development
+
+### Prerequisites
+- Node.js 22+
+- Redis running locally (`redis-server`)
+- Supabase local OR use cloud Supabase with development project
+
+### Start server
+```bash
+cd server
+cp .env.example .env   # fill in your values
+npm install
+npm run dev            # starts on :3001 with hot reload
+```
+
+### Start mobile
+```bash
+cd mobile
+npm install
+npx expo start         # opens Expo Go QR code
+```
+
+### Run all server tests
+```bash
+cd server
+npm test               # 276 tests, ~10s
+```
+
+---
+
+## 5. Architecture Overview
+
+```
+Mobile App (React Native/Expo)
+  ↕ Supabase Auth (JWT)
+  ↕ REST API: /v1/profile, /v1/catalog
+  ↕ Socket.io: matchmaking, game state, profile:refresh
+         ↕
+Server (Node.js / Railway)
+  - 20Hz authoritative game loop (GameRoom.ts)
+  - Matchmaking with bot backfill (MatchmakingQueue.ts, BracketMatcher)
+  - Session state machine (forming → char_select → active → ended)
+  - Economy systems (Currency, Inventory, XP, MMR, Rewards)
+  - Content Catalog (35 records: 8 chars, 18 abilities, 3 modes, 6 maps)
+         ↕
+Supabase (PostgreSQL + Auth)
+  - player_profiles, entitlements, economy_transactions
+  - character_xp, xp_grants, match_records
+```
+
+---
+
+## 6. Game Features
+
+| Feature | Status |
+|---|---|
+| Email/password auth | ✅ |
+| Google OAuth | ✅ |
+| Matchmaking: 1v1 Duel, 3v3 Squad, FFA 8-player | ✅ |
+| Bot backfill (45s timeout) | ✅ |
+| 20Hz authoritative server game loop | ✅ |
+| 8 characters (Vex, Zook, Sera, Fen, Grim, Dash, Colt, Nyx) | ✅ |
+| 18 abilities with cooldowns, status effects | ✅ |
+| 3 game modes with win conditions | ✅ |
+| BURNING bypasses SHIELDED | ✅ |
+| Joystick + attack/skill/dodge controls | ✅ |
+| HP bars, match timer | ✅ |
+| Match results with XP + diamond rewards | ✅ |
+| Player profile with MMR (Elo) | ✅ |
+| Economy (coins, diamonds, inventory) | ✅ |
+| Session persistence (disconnect → reconnect grace) | ✅ |
+| Structured JSON logging (pino) | ✅ |
+| Analytics event system | ✅ |
+| Remote config / live tuning | ✅ |
+| Content catalog with overlay | ✅ |