From 3cbe65442f623b828ded3f86f2218e2a10ca5f10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zo=C3=AB?= <zoe@guido-it.nl>
Date: Sat, 8 Aug 2026 12:55:07 +0200
Subject: [PATCH] docs: add WearOS target documentation to AGENTS.md

---
 AGENTS.md | 49 ++++++++++++++++++++++++++++++++++---------------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f94f916..8f983e9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # SwimBuddy
 
-Swimming workout tracker with Apple Watch companion app. Expo 57 + React Native 0.86 + NativeWind v5 + Drizzle ORM + Swift Watch target.
+Swimming workout tracker with Apple Watch and WearOS companion apps. Expo 57 + React Native 0.86 + NativeWind v5 + Drizzle ORM + Swift Watch target + Kotlin WearOS target.
 
 ## Commands
 
@@ -11,25 +11,34 @@ npx expo prebuild -p ios    # Regenerate ios/ dir (safe — targets/ persists)
 npx drizzle-kit generate    # Regenerate SQL migrations after schema changes
 ```
 
+**WearOS:**
+```bash
+./scripts/build-wearos.sh debug    # Build debug APK
+./scripts/build-wearos.sh release  # Build release APK
+./scripts/generate-wearos-icon.sh assets/icon.png  # Generate launcher icons
+```
+
 No `npm test` or lint scripts exist yet. No `babel.config.js` — NativeWind v5 uses CSS-first config.
 
 ## Project Structure
 
 ```
 src/
-  features/<name>/screens/   # Screen components (registered in navigators)
-  features/<name>/components/# Feature-specific UI
-  features/<name>/hooks/     # Feature-specific hooks
-  components/                # Shared UI primitives (flat)
-  hooks/                     # Shared hooks
-  navigation/                # React Navigation (RootNav, TabNav, feature stacks)
-  db/                        # Drizzle schema, client, relations, operations
-  providers/                 # DatabaseProvider, SettingsProvider (MMKV)
-  utils/                     # formatTime, calculateSwolf, uuid, etc.
-  constants/                 # strokes, poolLengths, colors
-  types/                     # workout.ts, common.ts
-  modules/watch-connectivity/# Expo native module bridging WCSession
-targets/watch/               # Apple Watch app (Swift/SwiftUI) — survives prebuild
+  features/<name>/screens/    # Screen components (registered in navigators)
+  features/<name>/components/ # Feature-specific UI
+  features/<name>/hooks/      # Feature-specific hooks
+  components/                 # Shared UI primitives (flat)
+  hooks/                      # Shared hooks
+  navigation/                 # React Navigation (RootNav, TabNav, feature stacks)
+  db/                         # Drizzle schema, client, relations, operations
+  providers/                  # DatabaseProvider, SettingsProvider (MMKV)
+  utils/                      # formatTime, calculateSwolf, uuid, etc.
+  constants/                  # strokes, poolLengths, colors
+  types/                      # workout.ts, common.ts
+  modules/watch-connectivity/ # Expo native module bridging WCSession (Apple Watch)
+  modules/wear-connectivity/  # Expo native module bridging Wear Data Layer (WearOS)
+targets/watch/                # Apple Watch app (Swift/SwiftUI) — survives prebuild
+targets/wearos/               # WearOS app (Kotlin/Compose) — survives prebuild
 ```
 
 ## Key Conventions
@@ -40,7 +49,7 @@ targets/watch/               # Apple Watch app (Swift/SwiftUI) — survives preb
 - **`className` types**: `nativewind-env.d.ts` at root — don't delete
 - **lightningcss pinned** to 1.30.1 in package.json overrides — required by NativeWind v5
 
-## Watch Target
+## Watch Target (Apple Watch)
 
 - Lives in `targets/watch/`, NOT in `ios/` — survives `expo prebuild --clean`
 - Config: `targets/watch/expo-target.config.js`
@@ -50,6 +59,15 @@ targets/watch/               # Apple Watch app (Swift/SwiftUI) — survives preb
 - HealthKit for swim workout tracking (indoor swimming)
 - Swift types `StoredWorkout`, `StoredSet`, `CompletedLap` in `WorkoutManager.swift`
 
+## WearOS Target
+
+- Lives in `targets/wearos/` — survives `expo prebuild --clean`
+- Kotlin + Jetpack Compose with Wear OS Compose libraries
+- Build: `./scripts/build-wearos.sh` or open `targets/wearos/` in Android Studio
+- Uses Wear Data Layer API for phone↔watch communication
+- Health Services Client for swim workout tracking
+- Namespace: `nl.guidoit.swimbuddy`
+
 ## Database
 
 - **expo-sqlite** + **Drizzle ORM** (SQLite dialect, expo driver)
@@ -94,6 +112,7 @@ These are hard-won bugs that will waste hours if rediscovered:
 - Watch target compiles as separate Xcode target — not a RN module
 - `react-native-css` is a NativeWind v5 peer dependency — don't remove
 - `@bacons/apple-targets` plugin must be in app.json plugins array
+- WearOS uses same `applicationId` as iOS bundle identifier — don't change without updating both
 
 ## Expo Docs