# Reflect ← Fitbit / Google Health setup

This connects your **Google Fitbit Air** to **Reflect** so it knows how you slept,
your HRV, resting heart rate and SpO2, and can open a session like *"you slept
rough and your HRV's down — how are you doing?"*

It uses the **Google Health API** (the Fitbit Web API retires Sept 2026). The
code is already wired in (`src/health.py` → injected into `build_instructions()`
in `therapist.py`). What's left is the one-time Google authorisation, which only
you can do because it needs your Google login.

## 1. Migrate your Fitbit login to a Google Account
In the Fitbit app: Account → migrate to a Google Account (if you haven't already).
The Health API only works with Google-account-linked devices.

## 2. Create a Google Cloud project (~10 min, free)
1. https://console.cloud.google.com → new project.
2. **APIs & Services → Library** → enable the **Google Health API**.
3. **OAuth consent screen** → User type *External* → add yourself as a **Test
   user** (your own Google email). Add the **Restricted** `googlehealth.*.read`
   scopes for sleep, heart rate, oxygen saturation. **Copy the exact scope
   strings it shows** — paste them into the `GOOGLE_HEALTH_SCOPES` Fly secret if
   they differ from the defaults in `health.py`.
4. **Credentials → Create credentials → OAuth client ID → Web application.**
   Add redirect URI: `http://localhost:8765/callback`. Copy the **client ID**
   and **client secret**.

> ⚠️ **Two honest caveats.** (a) `googlehealth.*` scopes are *Restricted*: to run
> beyond a personal test you'd need Google's security review (no published SLA).
> For just your own data, "Test user" mode is fine. (b) In test mode the
> **refresh token expires after 7 days**, so you'd re-run step 3 weekly. To make
> it permanent, publish the app and pass verification.

## 3. Authorise once (on your laptop)
```bash
cd ~/r1-voice-agent/agent
GOOGLE_HEALTH_CLIENT_ID="<id>" GOOGLE_HEALTH_CLIENT_SECRET="<secret>" \
  uv run python -m src.oauth_setup
```
A browser opens; click **Allow**. It prints a `flyctl secrets set …` command.

## 4. Store the secrets on Fly
Run the printed command, e.g.:
```bash
flyctl secrets set \
  GOOGLE_HEALTH_CLIENT_ID="..." \
  GOOGLE_HEALTH_CLIENT_SECRET="..." \
  GOOGLE_HEALTH_REFRESH_TOKEN="..."
```

## 5. Confirm the data (locks in field names)
With the same env exported locally:
```bash
uv run python -m src.health --probe
```
This prints raw API responses + the formatted block. If a metric is blank, the
real field/datatype name differs from the default — tell Claude the probe output
and it'll tighten the parsing in `health.py` (the constants near the top:
`GH_DT_*` and the `_deep_find_number` hints).

## How it behaves
- Reflect reads a cached `health_snapshot.json`; building the prompt never blocks
  on the network.
- Each session start refreshes the snapshot in the background for next time.
- Anything older than ~18h is ignored (so an unsynced watch = silence, not stale
  data).
- Not configured / any error → the health block is simply empty. Reflect is
  unaffected. No R1/Android changes were needed.
```