diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a66c8d6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+**Full smoke suite** (token scan + SharedCore tests + all platform builds):
+```bash
+./scripts/smoke/smoke_all.sh
+```
+
+**SharedCore unit tests only:**
+```bash
+cd SharedCore && swift test --disable-sandbox
+```
+
+**Individual platform builds** (no code signing):
+```bash
+./scripts/smoke/build_ios.sh
+./scripts/smoke/build_watch.sh
+./scripts/smoke/build_tvos.sh
+```
+
+**Build iOS via xcodebuild directly:**
+```bash
+xcodebuild -project iphone/Werkout_ios.xcodeproj \
+  -scheme 'Werkout_ios' -configuration Debug \
+  -destination 'generic/platform=iOS' \
+  CODE_SIGNING_ALLOWED=NO build
+```
+
+**Schemes:** `Werkout_ios` (iOS), `Werkout_watch Watch App` (watchOS), `WekoutThotViewer` (tvOS)
+
+**Workspace:** `Werkout.xcworkspace` contains the iOS/watchOS project and tvOS project.
+
+## Architecture
+
+### Multi-Platform Structure
+
+- **`iphone/`** — Main iOS app and watchOS companion app (same Xcode project: `Werkout_ios.xcodeproj`)
+- **`SharedCore/`** — Swift Package (v5.9) with cross-platform code: data models, validation, token security, runtime reporting, utilities. Has per-platform test targets (`SharedCoreiOSTests`, `SharedCoreWatchOSTests`, `SharedCoreTVOSTests`).
+- **`WekoutThotViewer/`** — Standalone tvOS app (separate Xcode project)
+
+Platform minimums: iOS 16+, watchOS 9+, tvOS 16+, macOS 13+.
+
+### iOS App (`iphone/Werkout_ios/`)
+
+SwiftUI app with MVVM pattern. Three-tab navigation: All Workouts, Create Workout, Account.
+
+**Core singletons:**
+- `UserStore` — Auth state, token lifecycle (Keychain storage with legacy migration), login/logout, planned workouts
+- `DataStore` — Cached workouts/exercises/muscles/equipment, parallel fetching via DispatchGroup
+- `BridgeModule` — iPhone↔Watch communication via WCSession, workout timers, external display (AirPlay) support
+
+**Networking layer** (`Network/`):
+- Protocol-based: `Fetchable` (GET) and `Postable` (POST) protocols in `Network.swift`
+- Concrete implementations in `Fetchables.swift` (e.g. `AllWorkoutFetchable`, `LoginFetchable`, `CreateWorkoutFetchable`)
+- Auto-attaches auth token; 30-second timeout; error handling via `FetchableError` enum
+
+**Data persistence:**
+- CoreData (`Werkout_ios.xcdatamodeld`, managed by `Persistence.swift`)
+- Keychain for token storage (`Keychain.swift`)
+- UserDefaults for preferences and token metadata
+
+**Key integrations:** HealthKit (calories, heart rate, workout sessions), AVFoundation (audio/video playback), WatchConnectivity
+
+### watchOS App (`iphone/Werkout_watch Watch App/`)
+
+Companion app with HealthKit workout session management (`WatchWorkout`), timer display, exercise controls. Communicates with iPhone via `BridgeModule` using action-based message passing (`WatchActions`, `PhoneToWatchActions`).
+
+### View Organization
+
+Views live in `iphone/Werkout_ios/Views/` grouped by feature (AllWorkouts, CreateWorkout, Login, WorkoutDetail, etc.). Shared subviews are in `iphone/Werkout_ios/subview/`.
+
+### Data Flow Patterns
+
+- Workout creation: `WorkoutViewModel` validates → `CreateWorkoutFetchable` POSTs → `AppNotifications.createdNewWorkout` triggers refresh
+- Auth: `LoginFetchable` → `UserStore` stores token in Keychain → all requests auto-attach token → 401/403 triggers logout → proactive refresh 30min before expiry
+- Watch sync: `BridgeModule` queues messages via `BoundedFIFOQueue` (max 100) over WCSession
+
+## CI
+
+GitHub Actions (`.github/workflows/apple-platform-ci.yml`) runs on macOS 15 for all pushes/PRs. Executes `smoke_all.sh` which runs token security scan, SharedCore tests, and builds all three platforms. Build scripts fail on any warnings or errors.