# Garmin Coach to Calendar Sync

This tool clones Garmin Coach/adaptive cycling workouts into normal Garmin Connect cycling workouts and schedules the generated clone on your Garmin calendar. The target use case is an original Garmin Edge 1030: the Edge can sync and run the generated structured workout like a normal workout while still using normal Edge navigation.

It uses unofficial Garmin Connect APIs. Run it locally or on a private network unless you harden it yourself.

## Current Status

Implemented:

- Feasibility research in [docs/feasibility.md](/home/yannik/repos/garmin-coach-to-cal-sync/docs/feasibility.md).
- CLI probe scripts for Garmin login, discovery, Coach extraction, dummy upload/schedule, and clone dry-run.
- Dockerized FastAPI web app with first-launch local login setup, Garmin login/MFA, manual sync, scheduled change detection, logs, traces, search, and schedule editing.
- SQLite state under `/data/app.db`.
- Persistent Garmin tokens under `/data/garmin-tokens`.
- Coolify-compatible `Dockerfile` and `docker-compose.yml`.

Still fragile:

- Garmin can change private API endpoints or authentication behavior.
- Garmin Coach completion may not be marked when you complete the generated clone.
- Edge 1030 acceptance must be verified on your device after upload/schedule.
- FIT export fallback is not implemented because Garmin Connect scheduling is the primary path.

## Quick Start

```sh
cp .env.example .env
docker compose up --build
```

Open [http://localhost:8080](http://localhost:8080).

First launch:

1. Create the local app username/password.
2. Open `Garmin`.
3. Enter Garmin credentials.
4. Enter MFA if Garmin asks for it.
5. Use `Search` to inspect Coach/calendar/workout visibility.
6. Use `Dashboard > Dry-run today` first, then `Check today` or `Check tomorrow`.

## Coolify Deployment

Deploy from the repository link.

Set:

- Container port: `8000`
- Persistent storage mount: `/data`
- `APP_SECRET_KEY`: a long random secret
- `TZ`: `Europe/Berlin`
- Optional bootstrap `APP_USERNAME` / `APP_PASSWORD`

The compose file uses a named volume for local Docker. In Coolify, configure persistent storage for `/data` instead of a repo bind mount. Runtime state, Garmin tokens, SQLite, logs, and traces all live under `/data`.

## Environment

Important defaults are in [.env.example](/home/yannik/repos/garmin-coach-to-cal-sync/.env.example):

```text
TZ=Europe/Berlin
DATA_DIR=/data
APP_USERNAME=admin
APP_PASSWORD=change-me
APP_SECRET_KEY=replace-with-a-long-random-secret
SYNC_ENABLED=true
SYNC_DAYS_AHEAD=1
CLONE_PREFIX=GCClone
OVERWRITE_EXISTING=true
DELETE_OLD_CLONES=false
CHANGE_DETECTION_INTERVAL_MINUTES=30
CHANGE_DETECTION_ACTIVE_WINDOW=05:00-22:00
CHANGE_DETECTION_FIXED_TIMES=05:15,06:15,07:15,08:15,09:15,10:15,11:15,12:15,13:15
```

Scheduled runs are change-detection runs. They create a missing clone, skip an unchanged clone, and replace only when the Coach source hash changes. If a Coach day becomes rest/empty while a generated clone exists, scheduled sync records a warning and leaves the clone alone.

## Web UI

- `Dashboard`: Garmin status, last run, next run, clone state, manual sync actions.
- `Garmin`: store encrypted Garmin credentials and complete MFA.
- `Search`: list calendar entries, normal workouts, plans, Coach tasks, and generated clones.
- `Schedule`: edit sync enabled, interval window, fixed `:15` checks, days ahead, or restore defaults.
- `Traces`: inspect source Coach task/detail, generated payload, source hash, and upload/schedule result.
- `Logs`: sync events and warnings.

Passwords, MFA codes, cookies, headers, and tokens are not logged. Trace JSON is redacted before storage.

## CLI Probe Commands

The CLI remains useful for low-level debugging:

```sh
uv run python scripts/probe_garmin.py login
uv run python scripts/probe_garmin.py report --dump-json
uv run python scripts/probe_garmin.py coach --date today --dump-json
uv run python scripts/clone_today_workout.py --date today --dry-run --dump-json
uv run python scripts/clone_today_workout.py --date today --schedule
```

Run local verification:

```sh
uv run ruff check .
uv run ty check
uv run pytest
```

## Edge 1030 Testing

After a web or CLI sync creates a clone:

1. Sync the Edge 1030.
2. Check `Training > Workouts`.
3. Check `Training > Training Plan > calendar icon > scheduled date`.
4. Start a route/course.
5. Start the generated workout and verify prompts run while navigation remains active.

More detail is in [docs/edge1030-testing.md](/home/yannik/repos/garmin-coach-to-cal-sync/docs/edge1030-testing.md).

## Cleanup

Generated workouts use the `GCClone YYYY-MM-DD ...` prefix by default. Scheduled automation never deletes a current clone just because a check ran. Replacement only happens when the source hash changes and the stored mapping points to a generated clone.

Use the CLI guarded cleanup helpers if you need manual cleanup:

```sh
uv run python scripts/probe_garmin.py generated --prefix GCClone
uv run python scripts/probe_garmin.py generated-calendar --date today --prefix GCClone
```

Delete or unschedule only IDs shown by those generated-prefix listings.