Add glossary, ADRs and future ideas from design grilling

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

GLOSSARY.md

@@ -0,0 +1,72 @@
+# ZenXercise
+
+An offline Android app for stretching and working out, split into two fully separate Modes. The user
+builds their own Plans from a large built-in Exercise Library and performs them in a guided Player.
+
+## Modes
+
+**Mode**:
+One of the two top-level app states, **Stretching** or **Workout**. Switching Mode changes the whole
+app: design, Exercise Library, Plans and History. The last-used Mode is remembered.
+_Avoid_: Tab, section, category
+
+**Stretching Mode**:
+The calm Mode: light design, sage/teal, rounded shapes, slow transitions.
+
+**Workout Mode**:
+The energetic Mode: dark design, orange/red on near-black, bold type, snappy transitions.
+
+## Exercises
+
+**Exercise**:
+A single movement from the Exercise Library, with name, Instructions, primary and secondary muscles,
+equipment, level and a start and end image. Belongs to exactly one Mode. Users cannot create their own.
+_Avoid_: Move, drill, activity
+
+**Exercise Library**:
+The read-only catalogue of Exercises bundled with the app, sourced from free-exercise-db (876
+Exercises). Category `stretching` belongs to Stretching Mode (123); every other category to Workout
+Mode (753). Browsed with text search and filters for muscle, equipment and level.
+_Avoid_: Catalogue, database
+
+**Flip Animation**:
+Alternating an Exercise's start and end image about once a second, the v1 stand-in for real animation.
+
+## Plans
+
+**Plan**:
+A user-created, ordered list of Steps (and Supersets) belonging to one Mode. The app ships no Plans.
+_Avoid_: Routine, program, workout
+
+**Step**:
+One Exercise inside a Plan, with Mode-specific parameters:
+- *Workout Step*: number of sets; reps **or** duration; optional target weight (kg).
+- *Stretching Step*: hold duration; both-sides flag (left, then right); rounds.
+_Avoid_: Item, entry
+
+**Superset**:
+Two or more Workout Steps grouped so they are performed alternately, one set of each in turn.
+_Avoid_: Circuit, combo
+
+## Sessions
+
+**Session**:
+One run-through of a Plan in the Player. It stores a snapshot of the Plan, so later edits to the Plan
+never change it. A Session is **complete** or **incomplete** (ended early).
+_Avoid_: Workout, run
+
+**Player**:
+The guided, one-Exercise-at-a-time screen used to perform a Session. It shows a large countdown ring,
+pulses the Mode's accent colour in the last three seconds, shows full-screen "next" cards, advances
+automatically when a timer ends, keeps the screen awake, and plays a gentle sound. No vibration.
+
+**Set Log**:
+The reps and weight actually done for one Workout set, prefilled from the Step's targets and confirmed
+with "Set done".
+
+**History**:
+The per-Mode list of Sessions with date, Plan, duration and Set Logs.
+
+**Streak**:
+A single, Duolingo-style daily streak shared by both Modes: consecutive days with at least one complete
+Session in either Mode. Incomplete Sessions do not count.

docs/adr/0001-v1-foundations.md

@@ -0,0 +1,19 @@
+# ADR 0001 — v1 foundations
+
+Status: Accepted (2026-10-28)
+
+## Decisions
+
+1. **Platform**: Flutter, Android only.
+2. **Modes**: A global Stretching / Workout switch that changes design, content and everything else.
+3. **Content**: A large bundled Exercise Library; users create all Plans themselves (no built-in Plans).
+4. **Data**: Offline only, local on-device storage, no accounts.
+5. **Sessions**: Guided Player (timers, rest countdown, cues) rather than a checklist.
+6. **History**: Simple log (date, Plan, duration) + Streak.
+7. **Visuals**: Simple animations are desired, but may be deferred past v1.
+8. **Scheduling / reminders**: Not in v1.
+
+## Consequences
+
+- No backend; all persistence is a local database on the device.
+- The Exercise Library must be bundled in the APK, so its size (incl. images) matters.

docs/adr/0002-library-ui-and-player.md

@@ -0,0 +1,22 @@
+# ADR 0002 — Exercise library, mode design, Player cues
+
+Status: Accepted (2026-10-28)
+
+## Decisions
+
+1. **Library source**: free-exercise-db (Unlicense, 876 exercises). `stretching` → Stretching mode,
+   everything else → Workout mode. No user-created exercises.
+2. **Images**: Bundle both images per exercise, compressed to WebP (~400px, est. 15–20 MB).
+   The start/end "flip" is the v1 animation; real animations are a future step.
+3. **Language**: English only; UI strings centralised for later translation.
+4. **Plan Steps**: Workout = sets, reps-or-duration, optional weight; no rest countdown.
+   Stretching = hold, both-sides flag, rounds. Workout Steps can be grouped into Supersets.
+5. **Library browsing**: search + muscle/equipment/level filters, reused as the Plan exercise picker.
+6. **Structure & design**: Mode switch at top; per-mode tabs Plans · Library · History.
+   Stretching = calm/light (sage/teal, rounded, slow). Workout = dark/energetic (orange/red, bold, snappy).
+   Last-used mode is remembered.
+7. **Player cues**: Visual cues (countdown ring, accent pulse, next cards, auto-advance, screen kept on)
+   plus a gentle, non-annoying sound. No vibration.
+8. **History**: Separate per Mode. The Streak is one shared, Duolingo-style daily Streak across both Modes;
+   only complete Sessions count.
+9. **Units**: kg only.

docs/adr/0003-tech-stack-follows-cookit.md

@@ -0,0 +1,17 @@
+# ADR 0003 — Tech stack follows CookIT
+
+Status: Accepted (2026-10-28)
+
+ZenXercise uses the same stack and conventions as the author's CookIT app (local-first Flutter, Android),
+so both codebases read alike.
+
+- State: `provider` with `ChangeNotifier` controllers, wired in `main.dart` via `MultiProvider`.
+- Persistence: `drift` + `drift_flutter` (SQLite); `shared_preferences` for small settings (last Mode).
+- Navigation: plain `Navigator` with named routes (no go_router).
+- Strings: `flutter gen-l10n` with ARB files in `lib/src/localization` (`app_en.arb` template).
+- Layout: `lib/src/<feature>/` with repositories, controllers and `views/`.
+- Screen-on in the Player: `wakelock_plus`. IDs: `uuid`.
+- Tests: `flutter_test`, `mocktail`, `sqlite3` (in-memory drift in tests).
+- Lints: `flutter_lints`. Docs: `GLOSSARY.md` (term / definition / _Avoid_) and `docs/adr/`.
+
+Supersedes the Riverpod / go_router proposal from the grilling session.

future_ideas.md

@@ -0,0 +1,15 @@
+# Future ideas
+
+Things deliberately left out of v1.
+
+- Real exercise animations or video (v1 uses the start/end Flip Animation)
+- iOS build (and web/desktop)
+- Accounts and cloud sync / backup
+- Scheduling Plans on weekdays, with reminder notifications
+- Built-in starter Plans
+- Custom user-created Exercises
+- Progress charts and personal records from Set Logs
+- lb units (v1 is kg only)
+- Vibration cues and voice guidance in the Player
+- Translations (v1 is English only)
+- Mixed Plans that combine Stretching and Workout (e.g. warm-up, workout, cool-down)