# Apple Health Dashboard / Health Auto Export Debugging

Use when Sir reports that Health Dashboard Apple Health charts stop before the newest uploaded Health Auto Export files.

## Canonical paths
- Health asset root: `/home/agent/.hermes/assets/Gesundheit`
- Active DB used by dashboard: `/home/agent/.hermes/assets/Gesundheit/health_data.db`
- Dashboard HTML served by static server: `/home/agent/.hermes/assets/Gesundheit/reports/health_dashboard.html`
- Dashboard server script: `/home/agent/projects/Jarvis/scripts/health-dashboard-static-server.py`
- Apple Health sync script: `/home/agent/.hermes/assets/Gesundheit/scripts/apple_health_drive_sync.py`
- Dashboard generator: `/home/agent/.hermes/assets/Gesundheit/scripts/health_pipeline.py dashboard`
- Canonical Apple aggregation: `/home/agent/.hermes/assets/Gesundheit/scripts/apple_health_analytics.py`
- Cron wrapper: `/home/agent/.hermes/scripts/apple_health_daily_sync.py`

## Debug workflow
1. Check the served dashboard file timestamp and generation text:
   - `stat /home/agent/.hermes/assets/Gesundheit/reports/health_dashboard.html`
   - search the HTML for `Generiert:` and the Apple Health table ranges.
2. Run the sync manually from the Health asset root when the user has just uploaded/exported files:
   - `cd /home/agent/.hermes/assets/Gesundheit && GOG_KEYRING_PASSWORD=... /usr/bin/python3 scripts/apple_health_drive_sync.py`
   - Do not print the key value.
3. Inspect the sync JSON:
   - `downloaded` shows files newly fetched from Drive.
   - `import.results[*].inserted` shows genuinely new records.
   - files can be `imported` with `inserted: 0` if their records are already present / duplicate hashes.
4. Regenerate the dashboard after any inserted records:
   - `cd /home/agent/.hermes/assets/Gesundheit && /usr/bin/python3 scripts/health_pipeline.py dashboard`
5. Verify at DB level whether the missing days actually contain the metric:
   - query `apple_health_records` grouped by `metric` and `substr(start_date,1,10)` for the dates in question.
   - Missing chart points are often because the uploaded JSON for that day contains only a subset of metrics.
6. Verify canonical chart output, not only raw rows:
   - import `daily_series(metric, mode)` from `apple_health_analytics.py` and check the last labels per metric.

## Important aggregation behavior
- `apple_health_analytics.daily_series(..., stable_only=True)` excludes the current local date because Health Auto Export intraday values are provisional/incomplete. This is intentional; today’s raw records can be present while the dashboard hides them.
- Current-day data will normally appear the next day if the export contains those metrics and the dashboard is regenerated.
- Yearly/weekly aggregate rows for SUM metrics may be normalized to daily-equivalent values to avoid impossible one-day spikes.

## Common root causes
- Dashboard HTML not regenerated after manual upload/sync.
- The Drive folder contains files for new dates, but those files only include some metrics (e.g. `physical_effort`, HRV, SpO₂) and not steps/distance/sleep/resting HR.
- Current-day data exists in `apple_health_records` but is deliberately suppressed by `stable_only=True`.

## User-facing explanation pattern
Keep it concise and separate:
1. "Dashboard stale or not regenerated" vs.
2. "raw files do not contain this metric for those days" vs.
3. "today is hidden as provisional".

Report which metrics now extend to the later date and which still stop earlier because raw data is absent. Avoid implying import failure when the import succeeded but the metric is missing from the export file.