working companion prototype

docs/TECH.md

@@ -123,10 +123,19 @@ Two candidates meet accessibility and performance requirements:
 - **Rationale:** Cross-platform desktop framework (Windows, macOS, Linux). Native OS integration (system tray, notifications, auto-start).
 - **Security:** Isolated renderer processes, context bridge for IPC
 
-### Nut.js
-- **Purpose:** Keyboard/mouse control for browser automation
-- **Rationale:** Simulates human interaction with iRacing web UI when official API unavailable. Not gameplay automation—assistant for data entry tasks.
-- **Constraints:** Windows-only initially (iRacing primary platform)
+### Playwright (Browser Automation)
+- **Purpose:** Automate the iRacing website (members.iracing.com) via DOM manipulation
+- **Rationale:** Standard browser automation for the iRacing web interface. The iRacing website is a standard HTML/DOM application that can be automated with Playwright. This is 100% legal and the only approach GridPilot uses.
+- **Key Features:**
+  - Cross-browser support (Chromium, Firefox, WebKit)
+  - Auto-wait for elements (eliminates flaky tests)
+  - Network interception for testing
+  - Screenshot/video capture for debugging
+
+### Important: iRacing Automation Rules
+- **✅ Allowed:** Browser automation of members.iracing.com (standard web application)
+- **❌ Forbidden:** DOM automation inside the iRacing Electron desktop app (TOS violation)
+- **❌ Forbidden:** Script injection or client modification (like iRefined)
 
 ### Electron IPC
 - **Main ↔ Renderer:** Type-safe message passing via preload scripts
@@ -140,6 +149,7 @@ Two candidates meet accessibility and performance requirements:
 - Assistant-style automation (user-initiated), not gameplay bots
 - Complements web app (handles tasks iRacing API doesn't expose)
 - Desktop integration (notifications for upcoming races, quick access via system tray)
+- Browser automation is reliable and testable
 
 ## 7. Testing Tools
 
@@ -243,7 +253,7 @@ Two candidates meet accessibility and performance requirements:
 - Runtime: Node.js 20+
 - Database: PostgreSQL 15+
 - Auth: iRacing OAuth + JWT
-- Companion: Electron + Nut.js
+- Companion: Electron + Playwright (browser automation only)
 - Testing: Vitest + Playwright + Test Containers
 - Infra: Docker + Redis + S3/MinIO
 - Monorepo: npm workspaces
@@ -271,4 +281,4 @@ Two candidates meet accessibility and performance requirements:
 
 ---
 
-*Last Updated: 2025-11-21*
+*Last Updated: 2025-11-23*