Bump version to 3.0.5, update ha-garmin to 0.1.18, fix lactate threshold and vo2Max sensors

- Fix lactate threshold sensors: ha-garmin 0.1.18 flattens the response
  into a top-level dict with Garmin's "hearRate" typo; update value_fn
  and mock data accordingly; add preserve_value=True to both sensors
- Simplify vo2Max value_fn to use pre-computed field from ha-garmin;
  add preserve_value=True
- Update polyline card to show activity_name attribute in popup title;
  clear stub entity so users provide their own entity ID
- Fix README: correct polyline sensor entity reference, document 3-file
  install requirement, add entity ID note, fix startTime template example
- Prefer .venv Python in scripts/develop to avoid system Python mismatches

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: cyberjunky

CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Communication style
+
+This user prefers caveman mode: terse, no filler, fragments OK, short synonyms. Drop articles/hedging/pleasantries. Technical terms exact. Code unchanged. Pattern: `[thing] [action] [reason]. [next step].`
+
+## Commands
+
+```bash
+scripts/setup       # Install dependencies and pre-commit hooks
+scripts/test        # Run pytest with coverage (pass extra args after --)
+scripts/lint        # Run pre-commit + vulture dead-code check
+scripts/develop     # Start local Home Assistant instance with the integration loaded
+```
+
+Run a single test file:
+```bash
+pytest tests/test_sensor.py -v
+```
+
+## Architecture
+
+This is a Home Assistant custom integration that polls the Garmin Connect cloud API via the [`ha-garmin`](https://github.com/cyberjunky/ha-garmin) library. The library is the only Garmin API dependency — all data fetching happens there.
+
+### Data flow
+
+Each data domain has its own `DataUpdateCoordinator` subclass in [coordinator.py](custom_components/garmin_connect/coordinator.py). All coordinators share the same `GarminClient` and `GarminAuth` instances, and each calls one `client.fetch_*_data()` method per poll:
+
+| Coordinator | Data |
+|---|---|
+| `CoreCoordinator` | Daily summary, steps, sleep, HR, stress, SpO2, body battery (~50 sensors) |
+| `ActivityCoordinator` | Last activity, last 10 activities, polyline, workouts (~5 sensors) |
+| `TrainingCoordinator` | Readiness, VO2max, HRV, training status, scores (~11 sensors) |
+| `BodyCoordinator` | Weight, BMI, hydration, fitness age, body composition (~17 sensors) |
+| `GoalsCoordinator` | Badges, points, active goals (~6 sensors) |
+| `GearCoordinator` | Gear stats (dynamic sensors per item), alarms |
+| `BloodPressureCoordinator` | Latest BP reading (~3 sensors) |
+| `MenstrualCoordinator` | Menstrual data (~9 sensors, disabled by default) |
+
+### Sensor definitions
+
+All sensors are declared as `GarminConnectSensorEntityDescription` tuples in [sensor.py](custom_components/garmin_connect/sensor.py), grouped by coordinator. Each description has:
+- `coordinator_type` — which coordinator feeds it
+- `value_fn` — lambda to extract the state value from coordinator data (falls back to `key` lookup if omitted)
+- `attributes_fn` — lambda to extract extra state attributes
+- `preserve_value=True` — retains last non-`None` value (used for weight, sleep, HRV which go `None` mid-day)
+
+### Key data facts from `ha-garmin`
+
+- `startTimeLocal` is **dropped** by the library; use `startTime` (UTC datetime) instead. In templates: `(a.startTime | as_datetime | as_local).strftime('%Y-%m-%d')`
+- `activityType` is simplified to a plain string (`"running"`, `"cycling"`, etc.)
+- `polyline` (GPS coordinates as `[{lat, lon}]`) lives on `lastActivityRoute` sensor, **not** `lastActivity`
+
+### Custom Lovelace card
+
+`www/garmin-polyline-card.js` renders activity routes using Leaflet. Users must copy **all three files** from `www/` to `<config>/www/`: the card JS plus `leaflet.js` and `leaflet.css`.
+
+### Entity unique IDs
+
+Format: `{entry_id}_{sensor_key}`. The v1→v2 migration in [\_\_init\_\_.py](custom_components/garmin_connect/__init__.py) rewrites unique IDs from the old `{email}_{key}` format and triggers reauth (tokens are incompatible between versions).

README.md

@@ -291,12 +291,15 @@ Gear sensors are dynamically created for each piece of equipment registered in G
 
 ## Activity Route Map
 
-The `Last Activity` sensor includes a `polyline` attribute with GPS coordinates when the activity has GPS data (`hasPolyline: true`). This can be displayed on a map using the included custom Lovelace card.
+The `Last Activity Route` sensor (`sensor.garmin_connect_last_activity_route`) contains a `polyline` attribute with GPS coordinates when the activity has GPS data. This can be displayed on a map using the included custom Lovelace card.
 
 **Installation:**
 
-1. Copy `www/garmin-polyline-card.js` to your `<config>/www/` folder
-2. Add as a resource: **Settings → Dashboards → ⋮ → Resources → Add Resource**
+1. Copy all three files from the `www/` folder to your `<config>/www/` folder:
+   - `garmin-polyline-card.js`
+   - `leaflet.js`
+   - `leaflet.css`
+2. Add the card as a resource: **Settings → Dashboards → ⋮ → Resources → Add Resource**
    - URL: `/local/garmin-polyline-card.js`
    - Type: JavaScript Module
 3. Hard refresh your browser (Ctrl+Shift+R)
@@ -305,13 +308,15 @@ The `Last Activity` sensor includes a `polyline` attribute with GPS coordinates
 
 ```yaml
 type: custom:garmin-polyline-card
-entity: sensor.garmin_connect_last_activity
+entity: sensor.YOUR_PREFIX_last_activity_route
 attribute: polyline
 title: Last Activity Route
 height: 400px
 color: "#FF5722"
 ```
 
+> **Note:** The entity ID depends on your account name. Find yours in **Settings → Devices & Services → Garmin Connect** or search for `last_activity_route` in Developer Tools → States.
+
 | Option | Default | Description |
 |--------|---------|-------------|
 | `entity` | (required) | Sensor entity with polyline attribute |
@@ -553,7 +558,7 @@ template:
           {% set today = now().strftime('%Y-%m-%d') %}
           {% set activities = state_attr('sensor.garmin_connect_last_activities', 'last_activities') | default([]) %}
           {% set running = namespace(total=0) %}
-          {% for a in activities if a.activityType == 'running' and today in a.startTimeLocal %}
+          {% for a in activities if a.activityType == 'running' and (a.startTime | as_datetime | as_local).strftime('%Y-%m-%d') == today %}
             {% set running.total = running.total + a.distance %}
           {% endfor %}
           {{ (running.total / 1000) | round(2) }}

custom_components/garmin_connect/manifest.json

@@ -9,6 +9,6 @@
   "issue_tracker": "https://github.com/cyberjunky/home-assistant-garmin_connect/issues",
   "loggers": ["ha_garmin"],
   "quality_scale": "gold",
-  "requirements": ["ha-garmin==0.1.15"],
-  "version": "3.0.4"
+  "requirements": ["ha-garmin==0.1.18"],
+  "version": "3.0.5"
 }

custom_components/garmin_connect/sensor.py

@@ -843,20 +843,19 @@ class GarminConnectSensorEntityDescription(SensorEntityDescription):
         translation_key="lactate_threshold_hr",
         coordinator_type=CoordinatorType.TRAINING,
         native_unit_of_measurement="bpm",
-        value_fn=lambda data: (
-            (data.get("lactateThreshold") or {}).get("speed_and_heart_rate") or {}
-        ).get("heartRate"),
+        # Garmin API returns "hearRate" (typo), ha_garmin merges the list into a flat dict
+        value_fn=lambda data: (data.get("lactateThreshold") or {}).get("hearRate"),
         attributes_fn=lambda data: data.get("lactateThreshold") or {},
+        preserve_value=True,
     ),
     GarminConnectSensorEntityDescription(
         key="lactateThresholdSpeed",
         translation_key="lactate_threshold_speed",
         coordinator_type=CoordinatorType.TRAINING,
         native_unit_of_measurement="m/s",
-        value_fn=lambda data: (
-            (data.get("lactateThreshold") or {}).get("speed_and_heart_rate") or {}
-        ).get("speed"),
+        value_fn=lambda data: (data.get("lactateThreshold") or {}).get("speed"),
         attributes_fn=lambda data: data.get("lactateThreshold") or {},
+        preserve_value=True,
     ),
     # HRV — ha_garmin flattens hrvStatus from _get_hrv_data_raw via _add_computed_fields
     GarminConnectSensorEntityDescription(
@@ -907,13 +906,8 @@ class GarminConnectSensorEntityDescription(SensorEntityDescription):
         coordinator_type=CoordinatorType.TRAINING,
         state_class=SensorStateClass.MEASUREMENT,
         native_unit_of_measurement="mL/(kg·min)",
-        value_fn=lambda data: data.get("vo2MaxValue")
-        or (
-            (
-                ((data.get("trainingStatus") or {}).get("mostRecentVO2Max") or {}).get("generic")
-                or {}
-            ).get("vo2MaxValue")
-        ),
+        value_fn=lambda data: data.get("vo2MaxValue"),
+        preserve_value=True,
     ),
 )
 

requirements.txt

@@ -1,4 +1,4 @@
 homeassistant>=2026.2.3
-ha-garmin==0.1.15
+ha-garmin==0.1.18
 colorlog==6.10.1
 setuptools==82.0.1

scripts/develop

@@ -4,8 +4,11 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-# Determine the Home Assistant command to use
-if command -v hass &> /dev/null; then
+# Determine the Home Assistant command to use — prefer the venv to avoid
+# system Python version mismatches (e.g. pycares/aiodns incompatibility).
+if [ -f ".venv/bin/python3" ]; then
+  HASS_CMD=".venv/bin/python3 -m homeassistant"
+elif command -v hass &> /dev/null; then
   HASS_CMD="hass"
 else
   HASS_CMD="python3 -m homeassistant"

tests/conftest.py

@@ -192,7 +192,7 @@ def mock_training_data() -> dict:
         },
         "enduranceScore": {"overallScore": 45, "runningScore": 50},
         "hillScore": {"overallScore": 30, "cyclingScore": 25},
-        "lactateThreshold": {"speed_and_heart_rate": {"heartRate": 162, "speed": 3.2}},
+        "lactateThreshold": {"hearRate": 162, "speed": 3.2},
         "hrvStatusText": "Balanced",
         "hrvWeeklyAvg": 45,
         "hrvLastNightAvg": 42,

www/garmin-polyline-card.js

@@ -101,7 +101,7 @@ class GarminPolylineCard extends HTMLElement {
   }
 
   _renderMap(coordinates, stateObj) {
-    const activityName = stateObj.state || 'Activity';
+    const activityName = stateObj.attributes.activity_name || stateObj.state || 'Activity';
 
     if (this._map) {
       // Update existing map — guard against Leaflet not being ready
@@ -243,7 +243,7 @@ class GarminPolylineCard extends HTMLElement {
 
   static getStubConfig() {
     return {
-      entity: 'sensor.garmin_connect_last_activity',
+      entity: '',
       attribute: 'polyline',
       title: 'Activity Route'
     };