# AGENTS.md — WatchOsm

Application Wear OS 5 qui suit la navigation initiée par OsmAnd+ (Android).
Documentation d'architecture : `documentation/architecture.md` + diagrammes
PlantUML dans `documentation/puml/`.

## Langues

- Commentaires, messages de commit, documentation : **français**.
- Identifiants de code en anglais (conventions Kotlin/Android classiques).

## Build et vérification — chaîne validée le 07/10/2026

Toutes les commandes suivantes sont **vertes** sur cette machine :

```bash
./gradlew :wear:assembleDebug        # APK debug
./gradlew :wear:testDebugUnitTest    # 11 tests unitaires (parseur)
./gradlew :wear:lint                 # lint Android
java -jar /tmp/opencode/plantuml.jar -checkonly documentation/puml/*.puml
```

- **Toolchain** : Gradle wrapper **8.11.1**, AGP **8.9.2**, Kotlin **2.1.20**
  (+ plugin `org.jetbrains.kotlin.plugin.compose` ; ne PAS ajouter
  `composeOptions.kotlinCompilerExtensionVersion`, compilateur Compose intégré
  au plugin Kotlin 2.x).
- **Android SDK** : installé dans `~/Android/Sdk` (cmdline-tools,
  `platforms;android-35`, `build-tools;35.0.0`). `local.properties` (non
  versionné) pointe dessus. Si le SDK manque : voir l'historique git, les
  étapes sdkmanager sont dans le commit d'initialisation.
- **JDK complet requis** : le JDK système est une JRE sans `javac`, ce qui
  fait échouer Gradle 8.11 sur les tâches Java. `~/.gradle/gradle.properties`
  (hors dépôt) définit
  `org.gradle.java.home=/home/aston/tools/jdk-21.0.12.1+1`. Si ce chemin
  disparaît, télécharger Temurin 21 via
  `https://api.adoptium.net/v3/binary/latest/21/ga/linux/x64/jdk/hotspot/normal/eclipse`.
- **Épinglages à ne pas bouger sans raisons** :
  - AGP < 8.9.2 → son lint plante (UAST vs Kotlin 2.1,
    `KaCallableMemberCall`). Ne pas revenir à 8.7.x.
  - **Compose BOM = `2025.08.00`** (Compose 1.9.0) : c'est la version attendue
    par Wear Compose 1.6.2 (qui dépend de `compose.ui:1.9.0`). Avec une BOM
    plus ancienne (1.8.x) les versions Compose deviennent mixtes et le rendu
    casse. Ne pas redescendre.
  - Wear Compose **1.6.2** : la 1.7.x exige AGP 9.1 + compileSdk 37.
  - core-ktx / lifecycle : versions inférieures aux dernières car les suivantes
    demandent compileSdk ≥ 36. Monter compileSdk/AGP est un chantier à part.

## Pièges de rendu Wear Compose (déjà rencontrés)

- Dans `SwipeDismissableNavHost`, utiliser **impérativement**
  `androidx.wear.compose.navigation.composable` — et NON
  `androidx.navigation.compose.composable`. Avec le mauvais import les
  destinations ne s'affichent jamais : l'app démarre sur un **écran noir**
  (aucune exception, surface dessinée mais vide). C'était la cause du bug
  d'écran noir d'octobre 2026.
- Toujours passer `modifier = Modifier.fillMaxSize()` à
  `SwipeDismissableNavHost` : sans contrainte de taille explicite il peut
  mesurer 0.
- Pour déboguer un écran noir sur montre : `adb exec-out screencap -p` +
  analyse des pixels (voir `scripts/`), puis comparer avec le `NavHost`
  standard `androidx.navigation.compose.NavHost` qui, lui, rend correctement.

## Diagrammes UML

- Sources **uniquement** en PlantUML (`.puml`) dans `documentation/puml/`.
- PlantUML n'est pas installé ; pour valider la syntaxe localement :
  `java -jar /tmp/opencode/plantuml.jar -checkonly documentation/puml/*.puml`
  (le jar, téléchargé dans `/tmp/opencode/`, n'est pas versionné ; le retirer
  si absent, il se re-télécharge depuis
  `https://github.com/plantuml/plantuml/releases`).
- Toute évolution d'architecture met à jour les diagrammes dans le même commit.

## Structure

- Module unique `wear/` (application montre autonome). Le module `phone/`
  (compagnon Android : listener renforcé + API AIDL OsmAnd + Data Layer) est
  prévu en phase 2, pas encore créé.
- Package : `fr.barteam.watchosm`.
- Le pont vers OsmAnd repose sur le **bridging des notifications** vers la
  montre ; le parseur de texte (`OsmAndNotificationParser`) est le seul point
  fragile face aux mises à jour d'OsmAnd — toute régression de format se
  corrige là, avec un test dans `OsmAndNotificationParserTest`.