# Workout Planner — User Journey Walkthrough

> **Homepage Card Description:** *"Personalized training programs and tracking."*

This document walks through the complete visitor experience of the Workout Planner feature on Marich Wellness — from the moment they land on the homepage to exploring their personalized fitness dashboard and beyond.

---

## 1. Entry Point — Homepage Card

The visitor arrives on the Marich Wellness homepage. Scrolling down, they encounter the **Personalized Fitness Planner** section — a large banner card featuring:

- A hero image of a fitness/wellness scene
- **Headline:** "Personalized Fitness Planner"
- **Description:** "Answer a few quick questions and unlock a personalized workout and meal plan tailored to your goals."
- **CTA Button:** "Start Journey"

Clicking **"Start Journey"** takes the visitor to `/fitness-planner`.

---

## 2. Onboarding — Step 1: Focus Selection

**Screen Title:** *"How can we help you today?"*

The visitor sees two large option cards:

| Option | Icon | Description | Status |
|--------|------|-------------|--------|
| **Workout Planner** | `fitness_center` | Personalized training programs and tracking. | ✅ Active |
| Calorie Tracker / Meal Planner | `restaurant` | Custom nutrition plans and macro tracking. | ⏳ Coming Soon |

A progress bar at the top shows **0%** — "Step 1 of 6".

The visitor clicks **Workout Planner** and is automatically advanced to the next step.

---

## 3. Onboarding — Step 2: Fitness Goals

**Screen Title:** *"What are your primary fitness goals?"*
**Subtitle:** *"Select all that apply. We'll tailor your workout and meal plans to these objectives."*

The visitor can select **multiple** goals from these cards:

| Goal | Icon | Description |
|------|------|-------------|
| Weight Loss | `fitness_center` | Focus on calorie deficit and fat burning. |
| Muscle Gain | `exercise` | Hypertrophy-focused training and surplus. |
| Strength | `weight` | Maximize your absolute power output. |
| Endurance | `shutter_speed` | Improve stamina and cardiovascular health. |
| General Health | `health_and_safety` | Balanced approach for longevity. |

Each card has a checkbox. Selected cards highlight with a green border and checkmark.

**Progress:** ~17% — "Step 2 of 6"

The visitor selects their goal(s) and clicks **"Continue Journey"**.

---

## 4. Onboarding — Step 3: Physical Profile

**Screen Title:** *"Your Physical Profile"*
**Subtitle:** *"These metrics help us calculate your BMR and TDEE."*

Three input fields appear:

| Field | Type | Placeholder |
|-------|------|-------------|
| Age | Number | e.g. 28 |
| Height (ft) | Number | e.g. 5.9 |
| Weight (kg) | Number | e.g. 72 |

**Progress:** ~33% — "Step 3 of 6"

The visitor fills in their details and clicks **"Continue Journey"**.

---

## 5. Onboarding — Step 4: Fitness Level

**Screen Title:** *"What's your fitness level?"*
**Subtitle:** *"We'll adjust the intensity of your starting program."*

Three single-select options:

| Level | Icon | Description |
|-------|------|-------------|
| Beginner | `stairs` | New to training or returning after a long break. |
| Intermediate | `trending_up` | Consistent training for 6-12 months. |
| Advanced | `military_tech` | Years of structured training experience. |

**Progress:** ~50% — "Step 4 of 6"

The visitor selects their level and is advanced automatically.

---

## 6. Onboarding — Step 5: Equipment Selection

**Screen Title:** *"What equipment do you have?"*
**Subtitle:** *"Select all that apply. We'll generate workouts you can actually do."*

Multi-select options:

| Option | Icon | Description |
|--------|------|-------------|
| None / Home | `home` | Bodyweight only exercises. |
| Home Gym | `fitness_center` | Select your available tools (sub-checkboxes appear): Dumbbells, Kettlebells, Elastic Bands, Pull-up Bar, Stationary Bike, Ab Roller |
| Full Gym | `apartment` | Access to machines, racks, and weights. |

**Progress:** ~67% — "Step 5 of 6"

The visitor selects their equipment and clicks **"Continue Journey"**.

---

## 7. Onboarding — Step 5.5: Choose Your Training Path

**Screen Title:** *"How would you like to train?"*
**Subtitle:** *"Choose how we build your program."*

Two large option cards appear:

### Option A: AI Generated Plan
- **Icon:** Sparkle/AI icon
- **Title:** "AI Generated Plan"
- **Description:** "Let our AI analyze your profile and create a fully personalized program just for you."
- **CTA:** "Generate My Plan"

### Option B: Browse Pre-Built Programs
- **Icon:** Grid/Library icon
- **Title:** "Browse Pre-Built Programs"
- **Description:** "Explore expert-designed programs filtered by your fitness level and goals."
- **CTA:** "Browse Programs"

**If the visitor selects Option A (AI Generated Plan):** They continue to the Medical Disclaimer step, then the existing AI generation flow.

**If the visitor selects Option B (Browse Pre-Built Programs):** They are taken to the **Program Library** at `/fitness-planner/library` (see Section 12).

---

## 8. Onboarding — Step 6: Medical Disclaimer

**Screen Title:** *"One last thing..."*
**Subtitle:** *"We highly recommend consulting with a healthcare professional before starting any new exercise program to ensure it is safe for your individual health status."*

**Progress:** ~83% — "Step 6 of 6"

The visitor clicks **"Generate Strategy"** to proceed.

---

## 9. Loading Screen — "Crafting Your Plan..."

A full-screen loading state appears with:

- An animated spinning circle
- **Headline:** "Crafting Your Plan..."
- **Message:** "Our AI is analyzing your profile to generate the perfect workout and nutrition strategy."
- **Progress bar** animating from 0% to 100%
- **Status text:** "Step 4/4: Finalizing Macros"

This lasts a few seconds while the AI generates the personalized plan.

---

## 10. Registration Screen — "Your Custom Roadmap is Ready!"

After generation completes, a registration screen appears:

- **Badge:** "Quiz Status — 100% Complete"
- **Headline:** "Your Custom Roadmap is Ready!"
- **Subheadline:** "Create your free account to instantly unlock your fitness report and activate your personalized wellness suite:"

Three benefits are listed with icons:

| Icon | Benefit |
|------|---------|
| `monitoring` | **Personalized Fitness Dashboard** — Track your daily habits and fitness progress in one place. |
| `notifications_active` | **Custom Product Alerts** — Be the first to know when your favorite gear and items are back in stock. |
| `local_offer` | **Exclusive App Discounts** — Get member-only deals on top supportive wellness apps. |

A form asks for the visitor's **email address**, with the CTA button: **"Unlock My Report & Dashboard"**

Upon submitting their email, the visitor is redirected to their personalized dashboard at `/fitness-planner/dashboard`.

---

## 11. Dashboard — "Welcome back, [Name]"

**Route:** `/fitness-planner/dashboard`

The visitor arrives at their personalized fitness dashboard. The layout includes:

### Sidebar Navigation (Desktop)
- `spa` — Marich Wellness home
- `dashboard` — Dashboard (active, highlighted)
- `fitness_center` — Workouts
- `restaurant` — Meals
- `analytics` — Analytics

### Header
- **Greeting:** "Welcome back, [Name]" (large serif heading)
- **Subtitle:** Shows the goal title (e.g. "Weight Loss Journey • Week 1, Day 1")
- **CTA Button:** "Log Activity"

### Stats Grid (4 cards)
| Stat | Value | Subtext |
|------|-------|---------|
| Daily Calories | 1,840 | of 2,200 goal |
| Water Intake | 2.4L | of 3.0L goal |
| Training Streak | 4 Days | Personal Best |
| Active Time | 45m | Today |

### Active Training Plan Widget
When the visitor has an active program set (from pre-built programs), a prominent card appears between the stats grid and the main content sections:

- **"Active Program" badge** with pulsing green dot
- **Program Name** (large serif heading)
- **Stats Row:** Week [X] of [Y] • [X] days/week • [Level]
- **CTA Buttons:**
  - "View Plan" (white, links to `/fitness-planner/my-plans`)
  - "Today's Workout" (outline, links to `/fitness-planner/day/[nextDayId]`)
- **Background:** Gradient from emerald-900 to emerald-800 with ambient light effect
- **Data Source:** Fetched from `GET /api/fitness/programs?status=active`
- **Conditional:** Only renders when `activeProgram` state is populated; hidden when no active program exists

### Meal Strategy Section
- **Upcoming meal** displayed prominently (e.g. "Grilled Lemon Herb Salmon with Quinoa and Steamed Greens")
- **Macros breakdown:** Protein (45g), Carbs (60g), Fats (12g)
- **Buttons:** "Log Meal" and "Swap Options"
- **Today's Menu:** Breakfast (with calories), Dinner (pending)

### Today's Routine Section
- **Workout name:** "Dynamic Performance"
- **Focus:** Shows the visitor's selected goals
- **Play button** to start the workout
- **Exercise list:** Each exercise shows:
  - Icon
  - Exercise name
  - Sets • Reps
  - Check circle to mark complete

### Affiliate Product Recommendations
- **Headline:** "Optimize Your Results"
- **Description:** "Based on your [goal] profile, we recommend these high-performance additions."
- **Category cards:** Supplements and Equipment (large image cards linking to shop)
- **Curated product grid:** 3 product cards showing:
  - Product image
  - Category badge
  - Product name
  - Price
  - "Shop Now" button

### Mobile Navigation (Bottom Bar)
- Dashboard, Workouts, Add (+), Meals, Profile

---

## 12. Program Library — `/fitness-planner/library`

*Accessed by selecting "Browse Pre-Built Programs" during onboarding, or by navigating directly.*

### Page Header
- **Title:** "Workout Plans"
- **Subtitle:** "Browse and save pre-built programs for every level"
- **Counter:** "[book icon] 9 programs"

### Filter Tabs (Horizontal, scrollable on mobile)
| Tab | Count |
|-----|-------|
| All | 9 |
| Beginner | 3 |
| Intermediate | 3 |
| Advanced | 3 |
| My Saved Plans | (dynamic) |
| My Custom Plans | (dynamic) |

Filtering is instant — no page reload needed.

### Program Grid
- **Desktop:** 3 columns
- **Tablet:** 2 columns
- **Mobile:** 1 column

### Program Card (each card shows)
- **Level Badge** (color-coded: Beginner = green, Intermediate = blue, Advanced = orange)
- **Save icon** (bookmark to save to My Plans)
- **Program Name** (heading)
- **Short Description** (2 lines max)
- **Stats Row:** [X]x/week • [X] weeks • [X] days
- **Tag Pills:** Goal tags as small rounded pills
- **Footer Buttons:**
  - "View Plan" (outline style)
  - "Save Plan" / "Set Active" / "Active ✓" (filled style, changes based on state)

### The 9 Pre-Built Programs

| # | Program | Level | Goal | Days/Week | Weeks |
|---|---------|-------|------|-----------|-------|
| 1 | Full Body Starter | Beginner | General Fitness | 3 | 8 |
| 2 | Beginner Fat Burn | Beginner | Weight Loss | 4 | 6 |
| 3 | Beginner Muscle Builder | Beginner | Muscle Gain | 3 | 8 |
| 4 | Push Pull Legs | Intermediate | Hypertrophy | 6 | 10 |
| 5 | Upper Lower Split | Intermediate | Strength + Muscle | 4 | 8 |
| 6 | Endurance & Conditioning | Intermediate | Cardio | 5 | 8 |
| 7 | 5/3/1 Powerbuilding | Advanced | Strength | 4 | 12 |
| 8 | Advanced Bodybuilding | Advanced | Hypertrophy | 6 | 12 |
| 9 | Athletic Performance | Advanced | Explosive Strength | 5 | 10 |

---

## 13. Program Detail Page — `/fitness-planner/library/[templateId]`

*Accessed by clicking "View Plan" on a program card.*

### Navigation
- **"← Back to Programs"** link at top

### Program Hero Section
- **Program Name** (large heading)
- **Level Badge** (color-coded)
- **Short Description**
- **Stats Row:** [X] weeks • [X]x/week • [X] total days
- **Goals Card:** Icon + goal description
- **Equipment Card:** Icon + equipment needed
- **Who Is For Card:** Icon + target audience
- **Long Description** (if available)
- **Action Buttons:**
  - "Start This Program" (if not saved)
  - "Set as Active Program" (if saved but not active)
  - "Active — Go to Dashboard" (if active)

### Program Structure Section
- **Week Navigation:** Horizontal tabs for each week (Week 1, Week 2, etc.)
- **Active week highlighted** with filled style

### Day Cards (within selected week)
Each day shows:
- **Day Number** (circle badge)
- **Day Name** (heading)
- **Exercise Count** or "Rest Day" badge
- **"View Workout"** button (links to `/fitness-planner/day/[dayId]`)

### Exercise Preview (non-rest days)
- Up to 4 exercises shown inline with:
  - Order number
  - Exercise name
  - Sets × Reps • Muscle group
  - Rest seconds
- "+ [N] more exercises" link if more than 4

### Rest Days
- Recovery icon
- "Recovery day — focus on mobility and nutrition" message

---

## 14. Daily Workout View — `/fitness-planner/day/[dayId]`

*Accessed by clicking "View Workout" from the Program Detail page.*

### Navigation
- **"← Back"** link to return to library

### Day Header
- **Day Number** (circle badge)
- **Day Name** (large heading)
- **Exercise count** and instruction text

### Start Workout Button
- **"Start Workout"** — prominent, full width, appears at top and bottom
- Links to `/fitness-planner/session/[dayId]`

### Exercise List (accordion style)
Each exercise is a collapsible card showing:

**Collapsed:**
- Order number
- Exercise name
- Sets × Reps • Muscle group
- Rest seconds
- Expand arrow

**Expanded:**
- **Tags:** Equipment, Difficulty, Bodyweight (if applicable), Cardio (if applicable)
- **Instructions:** Numbered steps
- **Pro Tips:** Green highlighted box
- **Common Mistakes:** Orange highlighted box
- **Set Details Grid:** Sets | Reps | Rest (3-column display)

### Rest Day Handling
If the day is a rest day, a full-screen rest day view is shown with:
- Large self-care icon
- "Rest Day" heading
- Day name
- Recovery message
- "Back to Programs" button

---

## 15. Active Session Mode — `/fitness-planner/session/[dayId]`

*Entered by clicking "Start Workout" on the Daily Workout View.*

### Pre-Session Start View
Before the session begins, a summary screen shows:
- **Play icon** (large)
- **Day Name** (heading)
- **Summary:** "[N] exercises · [N] total sets"
- **Exercise list** with order numbers, names, sets × reps, muscle groups
- **"Start Workout"** button

### Active Session View (after starting)

**Top Bar (sticky):**
- Day name
- Elapsed timer (MM:SS format, counting up)
- Progress: "[completed]/[total] exercises"
- Progress bar (percentage)

**Current Exercise Display:**
- Exercise number (e.g. "Exercise 2 of 8")
- Exercise name (large heading)
- Muscle group · Equipment (subtitle)

**Set Progress:**
- "Set [N] of [N]" label
- Visual set indicators (circles: completed = filled, current = highlighted + scaled, remaining = muted)
- Reps displayed prominently

**Instructions:**
- Numbered steps for the current exercise

**Pro Tip:**
- Green highlighted box with form advice

**Rest Timer (appears after completing a set):**
- Timer icon
- "Rest" label
- Countdown timer (large display)
- "Skip Rest" button

**Action Buttons:**
- "Complete Set [N]" / "Complete Exercise" / "Finish Workout" (context-aware label)
- "End Workout Early" (secondary, muted)

### Session Complete View
When all exercises are completed or the visitor ends early:

- **Celebration icon** (large)
- **"Workout Complete!"** heading
- **Day name** acknowledgment
- **Stats Grid:**
  - Duration (MM:SS)
  - Exercises completed
  - Sets completed
- **CTA Buttons:**
  - "View Dashboard" (primary, links to `/fitness-planner/dashboard`)
  - "Back to Programs" (secondary, links to `/fitness-planner/library`)

### Progress Logging
On session completion, progress is automatically logged via the API:
- User ID (from profile)
- Week number, day number
- Completion status
- Exercises and sets completed
- Duration in minutes
- Notes (optional)

---

## 16. My Plans Page — `/fitness-planner/my-plans`

*Accessed from the library filter tabs or navigation.*

### Page Header
- **Title:** "My Plans"
- **Subtitle:** "Manage your saved and active workout programs"
- **Counter:** "[bookmark icon] [N] plans"

### Section: Active Plan
- If an active plan exists: A highlighted card with green border and pulsing "ACTIVE" badge
  - Shows: Program name, description, Week X, Day Y, Source
  - Buttons: "Mark Complete" | "Go to Dashboard"
- If no active plan: Empty state with "Browse Programs" CTA

### Section: Saved Programs
- Grid of saved program cards (3 columns desktop, 2 tablet, 1 mobile)
- Each card shows:
  - Program name
  - Description (2 lines max)
  - Week X, Day Y stats
  - "Set Active" button
  - Delete button (with confirmation dialog)

### Section: Completed Programs
- Muted cards with strikethrough names
- Checkmark icon
- Completion date

### API Integration
- Fetches programs via `GET /api/fitness/programs?userId=[email]`
- Set active via `PUT /api/fitness/programs/[id]`
- Delete via `DELETE /api/fitness/programs/[id]`
- Mark complete via `PUT /api/fitness/programs/[id]` with `{ completed: true }`

---

## 17. Plan Editor — `/fitness-planner/edit`

*Accessed by clicking "Create Custom Plan" from My Plans or navigation.*

### Step 1: Plan Details
- **Plan Name** input
- **Description** textarea (optional)
- **Total Weeks** dropdown (2, 4, 6, 8, 12)
- **Days Per Week** dropdown (2, 3, 4, 5, 6)
- **"Next: Build Program"** button

### Step 2: Build Program

**Exercise Library Sidebar:**
- Search input
- Muscle Group filter dropdown
- Scrollable exercise list (fetched from all templates)
- Click an exercise to add it to the first available workout day

**Week/Day Structure:**
- Each week shown as a card
- Each day within a week shows:
  - Day name (Monday-Sunday)
  - "Make Rest" / "Make Active" toggle button
  - Exercise list with editable fields:
    - Sets (number input)
    - Reps (text input)
    - Rest seconds (number input)
  - Remove exercise button
  - "+ Add Exercise" link

### Step 3: Review & Save
- Plan name and description
- Duration, frequency, total workouts stats
- Week overview grid showing:
  - Each week as a row
  - 7 day columns showing "R" (rest), number of exercises, or orange (empty)
- **"Back to Edit"** and **"Save Plan"** buttons

### Saving
- Saves as a custom program via `POST /api/fitness/programs`
- Redirects to `/fitness-planner/my-plans` on success
- Requires completed fitness questionnaire first

---

## 18. API Routes Summary

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/api/fitness/templates` | List all workout templates |
| GET | `/api/fitness/templates/[id]` | Get template with weeks, days, exercises |
| GET | `/api/fitness/programs?userId=` | List user's saved programs |
| POST | `/api/fitness/programs` | Save a program for a user |
| PUT | `/api/fitness/programs/[id]` | Update program (active, completed, progress) |
| DELETE | `/api/fitness/programs/[id]` | Delete a saved program |
| POST | `/api/fitness/progress` | Log workout session progress |
| GET | `/api/user/profile` | Get user profile (for email/user ID) |

---

## 19. Database Schema (Workout Planner Tables)

### `workout_exercises`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| name | TEXT | Exercise name |
| muscle_group | TEXT | Primary muscle targeted |
| equipment | TEXT | Required equipment |
| difficulty | TEXT | beginner/intermediate/advanced |
| instructions | TEXT | Step-by-step instructions |
| pro_tips | TEXT | Form tips |
| common_mistakes | TEXT | Common errors |
| is_bodyweight | INTEGER | 0 or 1 |
| is_cardio | INTEGER | 0 or 1 |
| image_url | TEXT | Optional image |
| video_url | TEXT | Optional video |

### `workout_templates`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| name | TEXT | Template name |
| description | TEXT | Short description |
| long_description | TEXT | Detailed description |
| level | TEXT | beginner/intermediate/advanced |
| goal | TEXT | Fitness goal |
| days_per_week | INTEGER | Training frequency |
| total_weeks | INTEGER | Program duration |
| estimated_calories_per_week | INTEGER | Calorie estimate |
| equipment_needed | TEXT | Equipment summary |
| who_is_for | TEXT | Target audience |

### `workout_template_weeks`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| template_id | TEXT | FK to workout_templates |
| week_number | INTEGER | Week number |
| name | TEXT | Week name |

### `workout_template_days`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| week_id | TEXT | FK to workout_template_weeks |
| day_number | INTEGER | Day number |
| name | TEXT | Day name |
| is_rest_day | INTEGER | 0 or 1 |

### `workout_template_exercises`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| day_id | TEXT | FK to workout_template_days |
| exercise_id | TEXT | FK to workout_exercises |
| sets | INTEGER | Number of sets |
| reps | TEXT | Rep range |
| rest_seconds | INTEGER | Rest between sets |
| order_index | INTEGER | Display order |

### `user_programs`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| user_id | TEXT | User email/ID |
| template_id | TEXT | FK to workout_templates (nullable) |
| name | TEXT | Program name |
| description | TEXT | Program description |
| is_active | INTEGER | 0 or 1 |
| is_custom | INTEGER | 0 or 1 |
| source | TEXT | 'template', 'ai', or 'custom' |
| current_week | INTEGER | Current progress week |
| current_day | INTEGER | Current progress day |
| completed_at | TEXT | ISO date when completed |
| created_at | TEXT | ISO date created |
| updated_at | TEXT | ISO date updated |

### `workout_progress`
| Column | Type | Description |
|--------|------|-------------|
| id | TEXT (UUID) | Primary key |
| user_id | TEXT | User email/ID |
| week_number | INTEGER | Week logged |
| day_number | INTEGER | Day logged |
| completed | INTEGER | 0 or 1 |
| exercises_done | INTEGER | Count |
| sets_done | INTEGER | Count |
| duration_minutes | INTEGER | Session duration |
| notes | TEXT | User notes |
| logged_at | TEXT | ISO timestamp |

---

## Summary: Complete Visitor Flow

```
Homepage Card ("Start Journey")
  → /fitness-planner
    → Step 1: Focus Selection (Workout Planner)
    → Step 2: Fitness Goals (multi-select)
    → Step 3: Physical Profile (age, height, weight)
    → Step 4: Fitness Level
    → Step 5: Equipment Selection
    → Step 5.5: Training Path Choice
      ├── Option A: AI Generated Plan
      │     → Medical Disclaimer
      │     → Loading Screen ("Crafting Your Plan...")
      │     → Registration Screen (email capture)
      │     → Dashboard
      │
      └── Option B: Browse Pre-Built Programs
            → /fitness-planner/library (Program Library)
              → /fitness-planner/library/[templateId] (Program Detail)
                → /fitness-planner/day/[dayId] (Daily Workout View)
                  → /fitness-planner/session/[dayId] (Active Session Mode)
                    → Session Complete → Dashboard
              → Save Program → /fitness-planner/my-plans (My Plans)
              → Set Active Plan → /fitness-planner/dashboard (Dashboard)
              → /fitness-planner/edit (Plan Editor)
```

---

## Page Route Map

| Route | Page | Description |
|-------|------|-------------|
| `/fitness-planner` | Onboarding | Multi-step questionnaire (focus, goals, profile, level, equipment, path choice) |
| `/fitness-planner/dashboard` | Dashboard | Personalized fitness dashboard with stats, workout, meals, products |
| `/fitness-planner/library` | Program Library | Browse 9 pre-built programs with filters |
| `/fitness-planner/library/[templateId]` | Program Detail | Full program view with week/day structure |
| `/fitness-planner/day/[dayId]` | Daily Workout | Exercise list with expandable details |
| `/fitness-planner/session/[dayId]` | Active Session | Live workout mode with timer, sets, rest tracking |
| `/fitness-planner/my-plans` | My Plans | Manage saved, active, and completed programs |
| `/fitness-planner/edit` | Plan Editor | Create custom workout programs (3-step wizard) |

---

*This document describes the user-facing journey only. For technical implementation details, database schema, and API specifications, refer to the implementation roadmap.*

---

## Hardcoded Rules (DO NOT BREAK)

### Card Visibility & Layout
1. **Card borders must use `border-zinc-400` or stronger** — Never use `border-zinc-300` or lighter for card borders as they are too subtle against the background.
2. **Card description text must use `text-zinc-800`** — Never use `text-zinc-700` or lighter for card descriptions as they are not legible enough.
3. **Card stats must use `text-zinc-700`** — Never use `text-zinc-600` or lighter for stats text.
4. **Goal tags must use `bg-emerald-100 text-emerald-800` with `border-emerald-300`** — Never use `bg-emerald-50` or `text-emerald-700` as they lack contrast.
5. **Card padding must be `p-5` with `space-y-3`** — Never use `p-8` or `space-y-6` as they make cards too tall to fit all 9 in the viewport.
6. **Grid gap must be `gap-5`** — Never use `gap-8` as it wastes horizontal space.
7. **GSAP animation must use `useRef` + `querySelectorAll`** — Never use `gsap.from(".program-card", ...)` as it may miss cards below the fold. Always use `gridRef.current.querySelectorAll(".program-card")`.

### API Routes
8. **API routes must use shared `getDb()` from `@/lib/workout-planner/db`** — Never import raw `sqlite3` directly in fitness API routes.
9. **Dashboard must use `/api/fitness/programs?userId=...&status=active`** — Never use `/api/fitness/programs/active` as this endpoint does not exist.
10. **Dashboard must NOT import from `next-auth/react`** — The dashboard uses sessionStorage-based auth, not NextAuth.