workouts/README.md

# Workouts

A workout tracking app for iPhone, Apple Watch, and Mac. Build workout splits, run
sessions, and track your progress — with your data stored as plain JSON files in
your own iCloud Drive.

## Key Features

- **Workout splits** — organize exercises into reusable routines with custom
  colors, icons, and an activity type (strength, HIIT, cardio, …). Each split can
  set its own rest time (overriding the app-wide default) and turn on **Auto-Advance**
  to flow hands-free from one exercise to the next, resting automatically between them
  (the **Morning Wake-Up** starter split ships this way). Built-in starter splits
  (Upper Body / Core / Lower Body machine routines, plus an equipment-free
  **Bodyweight Core** circuit with its own warm-up) appear automatically on first
  launch and wear a **Starter** badge; editing one makes it your own copy. Any
  exercise can be duplicated and renamed for this routine only
  (its figure and guide still come from the original) — build an interval routine
  like a treadmill's Warmup / Brisk Walk / Cooldown from one library exercise.
- **Library tab** — a dedicated tab for managing it all: drag routines into your
  own order (the Today board and pickers follow it), duplicate any routine with a
  swipe, see each routine's usage at a glance (last trained, workouts completed,
  scheduled days — with a warning if you delete a routine that schedules still
  reference), and browse a **starter gallery** that previews every built-in
  routine — including deleted ones — and re-adds them individually or all at
  once. The exercise library and the add-exercise picker are grouped by category
  and searchable by name, category, or muscle.
- **Exercise library** — a bundled library of 67 exercises to populate your
  splits, authored in `Exercise Library/` with per-exercise setup, cues,
  mistakes, progressions, and an anatomically-rigged 3D stick-figure visual
  system — covering every common movement pattern and gym station (see the
  library's `COVERAGE.md`): the full machine circuit, the barbell and dumbbell
  free-weight canon (deadlifts, squats, benches, rows, curls, raises), the
  cable staples, and the bodyweight staples (push-ups, pull-ups, dips,
  lunges, and the floor core set).
- **Cardio** — a generic **Cardio** exercise and matching starter split for
  aerobic work. Tag a split's activity type Cardio and your Apple Watch records
  the real effort (heart rate, calories, duration) as a `.mixedCardio` workout,
  while the phone logs a simple timed block — no per-machine tracking needed.
- **Run a workout** — start a session from a split, then tap an exercise to run it
  as a paged flow: a **Ready?** lead-in, count-up work phases, count-down rests, and
  a **Finish** page — mirroring the Apple Watch. Swipe a row to mark it complete, or
  swipe to edit its plan (sets/reps/weight or duration) and notes. End a workout early
  from the **⋯** menu — **Save** keeps your progress (remaining exercises are marked
  skipped) or **Discard** removes it. Mid-workout, add any exercise from the full
  library — its plan is seeded from your most recent session with it, or from the
  library's authored defaults.
- **Live Activity** — the running workout lives on the Lock Screen and in the
  Dynamic Island: current exercise, set count, phase, and a live rest countdown,
  updating through every transition without unlocking the phone.
- **Animated form guide** — every library exercise shows a looping stick-figure
  demonstration on the run screen's bottom half, posed by real joint angles on an
  anatomical 3D skeleton (complete with feet) and rendered live from the Exercise
  Library's rig data with the working limbs highlighted — the camera slowly
  orbits every exercise while it moves, machine equipment (seats, bars, cables,
  roller pads) has world-space 3D form that turns with the figure, and face-on
  machines show true hip abduction and torso rotation. While you rest between
  exercises in an auto-advancing split, the figure previews the next exercise under
  a **Coming up** label, so you see what's next before it starts.
- **Spoken instructions** — tap the speaker in any library exercise to hear its
  full reference read aloud, and turn on **Speak Exercise Cues** in Settings to
  narrate a running workout hands-free. A **Narration** setting chooses the style:
  *Coming Up & Countdown* announces the next exercise during a rest and counts you
  into every set (the upcoming exercise, then "in 1, 2, 3, GO!", one word per beat),
  *Setup & Form Read* speaks each exercise's cues as it starts, or *Both*. On-device
  speech that ducks — never stops — your music, holding the duck across the count so
  it doesn't pulse between words. A **Voice** section in Settings picks the voice
  (preferring any enhanced or premium voices you've installed) and tunes its speed,
  pitch, and volume, with a live preview.
- **Machine comfort settings** — machine-based exercises remember your setup
  (seat height, back-rest position, pin position, …), shown on the workout
  screen and editable mid-workout; changes save back to the split for next time.
- **Per-set actuals** — every completed set is recorded automatically with its
  planned reps and weight, and the rest and finish pages offer a small adjust
  pill to correct what you actually did (in 2.5 lb / 1.25 kg steps) without
  breaking the flow; the completed-exercise page shows the recorded sets.
- **Progress tab** — per-goal adherence tracks (a 12-week strip per goal with
  weekly streaks and per-schedule this-week dots), this-week totals with
  vs-last-week deltas, trend charts (workouts, volume, active time, energy over
  7D–All ranges), weight-progression charts per exercise plotting the top-set
  weight you actually lifted, a derived achievements gallery, and full workout
  history — everything recomputed from your workout files, nothing separately
  stored.
- **Apple Watch companion** — starting a workout on the iPhone launches the watch
  app straight into it. The watch lists your in-progress workouts; pick one, pick an
  exercise, and run it as a paged flow: a **Ready?** lead-in, count-up work phases,
  count-down rests with final-three-second haptics and auto-advance, and a **Finish**
  page with **One More** and a **Done** that auto-completes after a countdown. A
  phase-dot row (purple work, teal rest) tracks progress. Rest time and the
  auto-finish countdown are configurable; changes sync back to the phone.
- **Two-way live run** — prop your iPhone up during an Apple Watch workout and it runs
  the same Ready → work/rest → Finish flow with live timers, in step with the watch. It's
  bidirectional: drive from either device — swipe ahead, finish a set, add one — and the
  other follows. Only *human* transitions are sent; automatic ones (a rest timer ending)
  advance both devices independently off shared start times, so they never fight.
- **Live status panel** — between the run screen's timer and figure (a band in
  portrait, a column in landscape) sits a big-digit readout of watch-streamed heart
  rate, HR zone (1–5), active calories, and the workout stopwatch, glanceable from
  across the room.
- **Target heart rate** — give a cardio routine (HIIT, cardio, cycling) a target bpm
  and the live heart-rate readout — on the watch and in the iPhone's status panel —
  tints green in range, with an arrow cue to push harder or ease off. Perfect for
  dialing in a treadmill incline and holding a steady effort.
- **Watch face complication** — a launcher complication you can place on any Apple
  Watch face; tap it to open the app. Available in the circular, corner, inline, and
  rectangular accessory slots.
- **Apple Health & Activity rings** — workouts recorded on the Apple Watch (heart
  rate + active energy) are saved to Apple Health and credit your Move and Exercise
  rings. See live heart rate and calories on the watch, and a post-workout summary
  (duration, calories, avg/max heart rate, heart-rate zones with a legend, total
  volume) you can revisit on any past workout. Weights display in your choice of
  pounds or kilograms.
- **Mac app** — a native macOS companion for managing your library: create, edit,
  reorder, and duplicate routines in a sidebar-driven window, manage schedules
  (recurrence, weekdays, reminder times — your iPhone sends the notifications),
  browse the starter gallery, and explore the exercise library with the same
  animated figures and reference guides. Library management only — workouts still
  run on iPhone and Apple Watch. Same iCloud data, no extra setup.
- **iCloud Drive sync** — your data lives as human-readable JSON in your iCloud
  Drive, synced across devices and visible in the Files app. iCloud is required.
- **Backups** — create point-in-time snapshots of all your data from Settings,
  keep several with retention controls, and restore one with a tap (backup files
  open straight into the app).
- **Diagnostics** — a Settings screen that shows iCloud account and container
  status, per-document download/eviction state, schema compatibility, and network
  readiness — with a one-tap copyable report.

## Architecture

iCloud Drive JSON documents are the **sole source of truth**; a local SwiftData
store is a rebuildable read-through cache populated exclusively by an
`NSMetadataQuery` observer (one-way flow: files → observer → cache). The phone
and the Mac write iCloud Drive directly (the Mac only routines and schedules —
whole-document last-writer-wins); the Apple Watch is a thin remote that
round-trips workout changes through the phone via WatchConnectivity.

See `REQUIREMENTS.md` for the data model and `CLAUDE.md` for project guidance.

## Building

The Xcode project is generated with [XcodeGen](https://github.com/yonaskolb/XcodeGen):

```sh
xcodegen generate
open Workouts.xcodeproj
```

Requires Xcode 26 (iOS 26 / watchOS 26 / macOS 26, Swift 6).