docs(watchos): plan technique + handoff Claude Code Mac mini

Préparation du chantier watchOS Live Workout (live FC/calories/distance
sur l'iPhone pendant que Sylvain fait du sport sur l'Apple Watch).

Décision archi : la phase native Swift/watchOS nécessite Xcode + Apple
Watch device, indispo dans la session Linux où ces docs ont été écrites.
D'où le handoff vers Claude Code lancé sur le Mac mini Sylvain.

Fichiers ajoutés :

- `docs/watchos-live-workout-plan.md` (444 lignes)
  Plan technique complet en 5 phases :
  1. Création target watchOS Xcode + entitlements
  2. Code Swift watchOS (4 fichiers : CoachWatchApp, WorkoutManager,
     ConnectivityManager, ContentView)
  3. Plugin Capacitor iOS (CoachLiveBridge.swift) qui reçoit les samples
     WCSession et les publie au JS via notifyListeners
  4. Route web /live + template (squelette prêt à coller dans
     coach_sportif/web/)
  5. Tests device + TestFlight internal
  Inclut décisions d'archi (HKLiveWorkoutBuilder, sendMessage avec
  fallback transferUserInfo, pas de Live Activity V1), pseudocode Swift,
  estimation effort 12-20h sur 3-5 jours, et risques + mitigations.

- `HANDOFF-WATCHOS.md` (181 lignes)
  Instructions étape par étape pour Claude Code Mac. Liste les memories
  à charger (project_coach_watchos_live, project_coach_ios,
  project_coach_app_commercial, user_sante_cardio,
  feedback_inline_display_none_toggle), workflow Step 1..6 (setup env,
  création target, lecture docs Apple, implémentation Swift, route web,
  tests device), garde-fous et règle "qui possède quoi" pendant le
  chantier (Mac = Swift natif, Linux = backend Python).

- `CLAUDE.md` (1ère commit, fichier existait en local non-tracked)
  Pointeur ajouté dans la section Backlog vers les 2 nouveaux fichiers.

Aucun fichier Swift n'a été écrit ici (décision conjointe avec Sylvain
pour ne pas risquer du code à l'aveugle sans Xcode pour valider les
APIs HealthKit/WCSession à jour).

HANDOFF-WATCHOS.md

@@ -0,0 +1,181 @@
+# Handoff — Chantier watchOS Live Workout
+
+**Pour** : Claude Code lancé sur le Mac mini Sylvain (`cd ~/coach-ios && claude`).
+**De** : Claude Code session Linux du 2026-05-24 (sandbox sans Xcode).
+**Pourquoi le handoff** : la phase native Swift/watchOS nécessite Xcode +
+Apple Watch device, indispo sur le sandbox Linux.
+
+## Première chose à faire avant de coder
+
+1. **Lis** `coach-ios/CLAUDE.md` (règles projet).
+2. **Lis** `coach-ios/docs/watchos-live-workout-plan.md` (plan technique complet).
+3. **Vérifie** que tu es bien sur le Mac mini avec Xcode 16+ : `xcodebuild -version`.
+4. **Vérifie** que `coach-ios` est à jour : `git pull` (les commits préparatoires
+   sont déjà poussés sur `main`).
+
+## Contexte session Linux (2026-05-24)
+
+Sylvain a confirmé vouloir attaquer le chantier watchOS Live Workout
+(memory `project_coach_watchos_live.md`). On a estimé ensemble qu'écrire
+du Swift à l'aveugle depuis le sandbox Linux était risqué (training data
+peut diverger des dernières APIs Apple, pas de compile Xcode pour valider).
+
+D'où ce handoff : toute la phase native (Phases 1-3 du plan) doit être
+exécutée par toi sur le Mac avec lecture des docs Apple en direct.
+
+Memories à charger pour contexte complet (probablement déjà dans `~/.claude/projects/-home-coder/memory/` synchronisé via Gitea ou autre, sinon
+demande à Sylvain de te briefer) :
+
+- `project_coach_watchos_live.md` — chantier original
+- `project_coach_ios.md` — état wrapper Capacitor
+- `project_coach_app_commercial.md` — pivot commercial (le watchOS live est un
+  différenciateur clé pour vendre à 39 ou 99 CHF/mois)
+- `user_sante_cardio.md` — FCmax Sylvain 145-155 bpm (à respecter dans tests)
+- `feedback_inline_display_none_toggle.md` — règle apprise hier : grep JS avant
+  de migrer du `style="display:none"` initial vers du CSS
+
+## État actuel à ton arrivée
+
+```
+coach-ios/
+├── CLAUDE.md ............. Règles projet (à jour)
+├── HANDOFF-WATCHOS.md .... Ce fichier
+├── docs/
+│   └── watchos-live-workout-plan.md ... Plan technique complet
+├── ios/App/App/
+│   ├── AppDelegate.swift .......... Bootstrap + cookie inject (NE PAS CASSER)
+│   ├── MainViewController.swift ... WKWebView config
+│   ├── CoachHealthRoute.swift ..... HealthKit web bridge existant
+│   ├── CoachWorkoutKit.swift ...... HKWorkoutPlan push (iOS 17+)
+│   └── CoachWorkoutObserver.swift . Observer fin de séance
+└── ios/App/App.xcodeproj ......... Projet Xcode (PAS de target watchOS encore)
+```
+
+**Aucun fichier Swift watchOS écrit pour l'instant** — décision conjointe :
+tu écris depuis zéro après avoir lu les docs Apple à jour.
+
+## Workflow recommandé sur ton Mac
+
+### Step 1 — Setup environnement (30 min)
+
+```bash
+cd ~/coach-ios
+git pull origin main
+xcodebuild -version          # Xcode 16+ requis (watchOS 11+ SDK)
+xcrun simctl list devicetypes | grep Watch  # voir simulateurs watchOS dispo
+```
+
+Vérifie aussi que ton Apple Watch est jumelée à l'iPhone et tournée vers
+watchOS 11+ (cf. About sur la Watch).
+
+### Step 2 — Création de la target watchOS (1-2h)
+
+**2 voies possibles** :
+
+**Voie A — Manuelle dans Xcode UI** (recommandée pour la 1ère fois) :
+1. Ouvre `ios/App/App.xcworkspace`
+2. `File > New > Target...` → watchOS → App
+3. Suis le plan section "Phase 1.1" du fichier `docs/watchos-live-workout-plan.md`
+4. Commit le diff sur `project.pbxproj`
+
+**Voie B — Édition pbxproj directe** (si tu veux être 100% reproducible) :
+- Édite `ios/App/App.xcodeproj/project.pbxproj` à la main
+- Risque : format propriétaire Xcode, fragile. À éviter sauf si Voie A
+  bloquée.
+
+### Step 3 — Lecture des docs Apple à jour (45 min)
+
+Avant de coder, lis ces 4 pages doc Apple **dans ton browser** ou via
+`mcp__claude_ai_*` si tu as un MCP fetch dispo :
+
+1. `developer.apple.com/documentation/healthkit/hkliveworkoutbuilder`
+2. `developer.apple.com/documentation/watchconnectivity/wcsession`
+3. `developer.apple.com/documentation/healthkit/hkworkoutsession`
+4. `capacitorjs.com/docs/plugins/creating-plugins/ios-guide`
+
+Note les **signatures exactes** qui peuvent avoir changé. Le plan technique
+du fichier `docs/watchos-live-workout-plan.md` contient du pseudocode qui
+peut être périmé sur des détails (par exemple async/await sur certaines
+méthodes en watchOS 11+).
+
+### Step 4 — Implémentation Swift (6-8h sur 1-2 jours)
+
+Suis les Phases 2 et 3 du plan technique. Commit petit par petit :
+
+- Commit 1 : `CoachWatchApp.swift` + `ContentView.swift` minimal
+  (juste affichage statique, vérifie que la target builde sur simulator).
+- Commit 2 : `WorkoutManager.swift` (HKLiveWorkoutBuilder seul, sans
+  Connectivity). Vérifie sur Apple Watch device que les samples HR arrivent.
+- Commit 3 : `ConnectivityManager.swift` (WCSession). Test envoi simple.
+- Commit 4 : `CoachLiveBridge.swift` côté iPhone (Capacitor plugin).
+- Commit 5 : Tests + fixes itératifs.
+
+Règle clé : **chaque commit doit compiler** (Watch + iPhone targets).
+
+### Step 5 — Route web `/live` + template
+
+Cette partie peut être faite par toi OU déléguée à une session Claude Code
+sur le repo `coach_sportif/` (Linux Linux sandbox d'origine). Le code FastAPI
++ Jinja est trivial une fois le plugin Capacitor publie l'event JS
+`liveSample`.
+
+Si tu veux le faire toi-même sur Mac : Phase 4 du plan technique a le
+squelette prêt à coller.
+
+### Step 6 — Tests device + TestFlight internal (4-8h)
+
+- Test E2E : lance app CoachWatch sur Apple Watch → choisis activité
+  Course → vérifie /live sur iPhone affiche le BPM en moins de 10 sec.
+- Test fallback : Bluetooth off pendant 30 sec, vérifie que les samples
+  arrivent quand BLE revient.
+- Test batterie : 1h de workout, vérifier % drop sur Watch (cible <15%).
+- Upload TestFlight internal (juste pour Sylvain) avant la 1ère review
+  publique.
+
+## Garde-fous communs à respecter (depuis les memories)
+
+1. **Pas d'extrapolation** : si une API Apple n'est pas vérifiée dans la doc
+   live, **ne pas l'inventer**. Préfère commenter "TODO: vérifier signature"
+   et demander à Sylvain.
+2. **Default yes** : décide et exécute sauf actions destructives (push force,
+   delete entitlements, etc.).
+3. **Git push après chaque commit** atomique qui compile.
+4. **descriptions Info.plist en FR** (App Store FR).
+5. **`raise X from e`** ou `from None` côté Python (B904 fixé ce matin,
+   préserver la norme).
+6. **Tests à chaque feature** ; pas de merge sans test minimum.
+7. **CLAUDE.md à jour** : si tu décides quelque chose qui change l'archi
+   (ex : passer à Live Activity au lieu de webview /live), document-le.
+
+## Quand revenir vers la session Linux
+
+Le repo `coach_sportif/` (Linux sandbox source) reste mon terrain :
+
+- Backend FastAPI (route `/live`, helpers)
+- Template Jinja (`live_workout.html`)
+- Tests pytest backend
+- Refactor CSS / scope global
+
+Quand tu finis le plugin Capacitor `CoachLiveBridge` et que tu as besoin
+de la route `/live` côté serveur, soit tu la code toi-même (Phase 4), soit
+tu demandes à Sylvain de relancer la session Linux pour que je l'écrive.
+
+## Référence "qui possède quoi" pendant le chantier
+
+| Composant | Owner | Notes |
+|---|---|---|
+| `coach-ios/ios/App/App/Coach*Watch.swift` | Toi (Mac) | Swift natif iOS |
+| `coach-ios/watch/CoachWatch/*.swift` | Toi (Mac) | Swift natif watchOS |
+| `coach-ios/ios/App/App/CoachLiveBridge.swift` | Toi (Mac) | Plugin Capacitor iOS |
+| `coach-ios/project.pbxproj` | Toi (Mac) | Édition prudente |
+| `coach_sportif/web/routers/misc.py` route /live | Moi (Linux) ou toi | Trivial |
+| `coach_sportif/web/templates/live_workout.html` | Moi (Linux) ou toi | Squelette dans plan |
+| `coach_sportif/web/static/style.css` ajouts .live-* | Moi (Linux) | Si je fais le template |
+| Tests pytest backend | Moi (Linux) | |
+| Tests Xcode XCTest | Toi (Mac) | |
+
+## Bon courage
+
+Quand tu auras fini : commit final qui résume l'état + ferme ce chantier
+dans la memory (`project_coach_watchos_live.md` à update). Et appelle
+Sylvain pour test device. 🚀