ui fixes, added youtube recommendations in 2D simulation page

README.md

@@ -1,8 +1,8 @@
-# Lumea Health Platform
+# Lumea Health Platform
 
 A full-stack health companion platform for preventive health management. Upload medical reports, extract health metrics via OCR, track trends, and receive AI-powered health recommendations.
 
-> ⚠️ **Disclaimer**: This platform is a support tool for personal health tracking. It does not provide medical advice, diagnosis, or treatment. Always consult a licensed healthcare professional for medical decisions.
+> **Disclaimer**: This platform is a support tool for personal health tracking. It does not provide medical advice, diagnosis, or treatment. Always consult a licensed healthcare professional for medical decisions.
 
 ---
 
@@ -38,9 +38,9 @@ Lumea is a unified medical companion platform that enables users to:
 - **Receive AI recommendations** based on extracted lab values and health patterns powered by OpenRouter (Claude Sonnet 4.5)
 - **Compare reports over time** with AI-powered summaries and trend analysis
 - **Chat with an AI assistant** grounded in your personal health data
-- **🧠 Memory & Knowledge Graph**: Persistent health memory with Mem0 and interconnected insights via Neo4j/Graphiti for temporal reasoning and contradiction detection
-- **🎙️ Voice Agent**: Speak naturally to an AI health assistant for hands-free access to personalized health insights
-- **🏥 Physics Twin**: Interactive 2D organ simulation with real-time telemetry, condition detection, and evidence-based health recommendations powered by your actual medical data
+- **Memory & Knowledge Graph**: Persistent health memory with Mem0 and interconnected insights via Neo4j/Graphiti for temporal reasoning and contradiction detection
+- **Voice Agent**: Speak naturally to an AI health assistant for hands-free access to personalized health insights
+- **Physics Twin**: Interactive 2D organ simulation with real-time telemetry, condition detection, and evidence-based health recommendations powered by your actual medical data
 
 ---
 
@@ -68,106 +68,106 @@ Lumea is a unified medical companion platform that enables users to:
 
 ```mermaid
 flowchart TB
-    subgraph Client["Frontend (React)"]
-        UI[React UI]
-        WS[WebSocket Client]
-    end
-
-    subgraph API["Backend (FastAPI)"]
-        Auth[Auth Routes]
-        Dashboard[Dashboard Routes]
-        Reports[Reports Routes]
-        Profile[Profile Routes]
-        Recommendations[Recommendations Routes]
-        AISummary[AI Summary Routes]
-        Assistant[Assistant Routes]
-        WSServer[WebSocket Server]
-    end
-
-    subgraph Services["Backend Services"]
-        OCR[PDF/OCR Extractor]
-        Classifier[Document Classifier]
-        MetricExtractor[Metric Extractor]
-        MetricsService[Metrics Service]
-        RecommendationEngine[Recommendation Engine]
-        AISummaryService[AI Summary Service]
-        RAG[RAG Service]
-        LLM[LLM Service]
-    end
-
-    subgraph External["External Services"]
-        GrokAPI[Grok API]
-        Ollama[Ollama / MedGemma]
-        Gemini[Gemini API]
-    end
-
-    subgraph Storage["Data Layer"]
-        DB[(PostgreSQL / Neon)]
-        ChromaDB[(ChromaDB Vector Store)]
-        FileStorage[File Storage]
-    end
-
-    UI --> Auth
-    UI --> Dashboard
-    UI --> Reports
-    UI --> Profile
-    UI --> Recommendations
-    UI --> AISummary
-    UI --> Assistant
-    WS <--> WSServer
-
-    Reports --> OCR
-    OCR --> Classifier
-    Classifier --> MetricExtractor
-    MetricExtractor --> MetricsService
-    MetricsService --> RecommendationEngine
-
-    AISummary --> AISummaryService
-    AISummaryService --> GrokAPI
-    Assistant --> RAG
-    RAG --> ChromaDB
-    RAG --> LLM
-    LLM --> Ollama
-    LLM --> Gemini
-
-    Auth --> DB
-    Dashboard --> DB
-    Reports --> DB
-    Reports --> FileStorage
-    Profile --> DB
-    Recommendations --> DB
-    AISummary --> DB
+ subgraph Client["Frontend (React)"]
+ UI[React UI]
+ WS[WebSocket Client]
+ end
+
+ subgraph API["Backend (FastAPI)"]
+ Auth[Auth Routes]
+ Dashboard[Dashboard Routes]
+ Reports[Reports Routes]
+ Profile[Profile Routes]
+ Recommendations[Recommendations Routes]
+ AISummary[AI Summary Routes]
+ Assistant[Assistant Routes]
+ WSServer[WebSocket Server]
+ end
+
+ subgraph Services["Backend Services"]
+ OCR[PDF/OCR Extractor]
+ Classifier[Document Classifier]
+ MetricExtractor[Metric Extractor]
+ MetricsService[Metrics Service]
+ RecommendationEngine[Recommendation Engine]
+ AISummaryService[AI Summary Service]
+ RAG[RAG Service]
+ LLM[LLM Service]
+ end
+
+ subgraph External["External Services"]
+ GrokAPI[Grok API]
+ Ollama[Ollama / MedGemma]
+ Gemini[Gemini API]
+ end
+
+ subgraph Storage["Data Layer"]
+ DB[(PostgreSQL / Neon)]
+ ChromaDB[(ChromaDB Vector Store)]
+ FileStorage[File Storage]
+ end
+
+ UI --> Auth
+ UI --> Dashboard
+ UI --> Reports
+ UI --> Profile
+ UI --> Recommendations
+ UI --> AISummary
+ UI --> Assistant
+ WS <--> WSServer
+
+ Reports --> OCR
+ OCR --> Classifier
+ Classifier --> MetricExtractor
+ MetricExtractor --> MetricsService
+ MetricsService --> RecommendationEngine
+
+ AISummary --> AISummaryService
+ AISummaryService --> GrokAPI
+ Assistant --> RAG
+ RAG --> ChromaDB
+ RAG --> LLM
+ LLM --> Ollama
+ LLM --> Gemini
+
+ Auth --> DB
+ Dashboard --> DB
+ Reports --> DB
+ Reports --> FileStorage
+ Profile --> DB
+ Recommendations --> DB
+ AISummary --> DB
 ```
 
 ### Data Flow: Report Upload to Health Index
 
 ```mermaid
 sequenceDiagram
-    participant User
-    participant Frontend
-    participant Backend
-    participant OCR
-    participant Classifier
-    participant Extractor
-    participant DB
-    participant WebSocket
-
-    User->>Frontend: Upload PDF/Image
-    Frontend->>Backend: POST /api/reports/upload
-    Backend->>DB: Create report (status: uploaded)
-    Backend-->>Frontend: {id, status: uploaded}
-    
-    Backend->>OCR: Extract text (background)
-    OCR-->>Backend: Raw text
-    Backend->>Classifier: Classify document
-    Classifier-->>Backend: Category + doc_type
-    Backend->>Extractor: Extract metrics
-    Extractor-->>Backend: Observations[]
-    Backend->>DB: Save observations + update report
-    Backend->>DB: Recompute health index
-    Backend->>WebSocket: emit report_parsed
-    WebSocket-->>Frontend: report_parsed event
-    Frontend->>Frontend: Refresh UI
+ participant User
+ participant Frontend
+ participant Backend
+ participant OCR
+ participant Classifier
+ participant Extractor
+ participant DB
+ participant WebSocket
+
+ User->>Frontend: Upload PDF/Image
+ Frontend->>Backend: POST /api/reports/upload
+ Backend->>DB: Create report (status: uploaded)
+ Backend-->>Frontend: {id, status: uploaded}
+ 
+ Backend->>OCR: Extract text (background)
+ OCR-->>Backend: Raw text
+ Backend->>Classifier: Classify document
+ Classifier-->>Backend: Category + doc_type
+ Backend->>Extractor: Extract metrics
+ Extractor-->>Backend: Observations[]
+ Backend->>DB: Save observations + update report
+ Backend->>DB: Recompute health index
+ Backend->>WebSocket: emit report_parsed
+ WebSocket-->>Frontend: report_parsed event
+ Frontend->>Frontend: Refresh UI
 ```
 
 ---
@@ -182,6 +182,8 @@ sequenceDiagram
 - **Condition Detection**: 10 rule-based health conditions auto-detected with severity mapping
 - **Body Impact Overlay**: 2D SVG visualization showing organs affected by detected conditions
 - **Smart Recommendations**: Evidence-based health actions with YouTube educational links per condition
+- **AI Video Recommendations**: OpenRouter-powered personalized health video suggestions for each organ based on abnormal metrics, with per-organ caching
+- **Explainability Cards**: Side-by-side "Improve Your Health" and "Why This Score?" panels showing video recommendations and scoring breakdowns
 - **Time-Series History**: View per-report organ scores and historical trends
 - **Lifestyle Integration**: Incorporates self-reported profile data (sleep hours, stress level)
 
@@ -196,7 +198,7 @@ sequenceDiagram
 - Tracks conditions, symptoms, medications, supplements, allergies
 - Family medical history and genetic test results
 - **Once completed, users are never re-asked** – profile status persists in DB
-- "Profile Complete ✅" indicator with quick-edit access via Settings page
+- "Profile Complete" indicator with quick-edit access via Settings page
 - **Real-time SMS reminders** via Twilio (or mock mode for testing)
 - Background scheduler processes due reminders every 60 seconds
 - Default reminders auto-generated: medication, appointment, checkup, hydration
@@ -224,7 +226,7 @@ sequenceDiagram
 - Citations from reports and observations
 - WebSocket streaming for real-time responses
 
-### 🎙️ Voice Agent (AI Health Assistant)
+### Voice Agent (AI Health Assistant)
 - **Natural voice conversations** with your health data
 - **Speech-to-Text**: Browser Web Speech API for hands-free input
 - **AI Processing**: Google Gemini with personalized health context
@@ -251,47 +253,47 @@ The **Memory & Knowledge Graph** system provides persistent, intelligent health
 
 ```mermaid
 flowchart TB
-    subgraph Input["Health Data Sources"]
-        Profile[Health Profile]
-        Reports[Medical Reports]
-        Questionnaire[User Questionnaires]
-        Assistant[AI Assistant Chats]
-    end
-
-    subgraph Memory["Mem0 Memory Layer"]
-        Extraction[Fact Extraction<br/>via Groq LLM]
-        Storage[ChromaDB<br/>Vector Store]
-        Retrieval[Semantic Search]
-    end
-
-    subgraph Graph["Graphiti Knowledge Graph"]
-        Entities[Entity Nodes<br/>conditions, metrics, meds]
-        Relationships[Temporal Relationships<br/>affects, caused_by, treats]
-        Episodes[Health Episodes<br/>time-stamped events]
-        Insights[AI-Generated Insights<br/>contradictions, patterns]
-    end
-
-    subgraph DB["Neo4j Graph Database"]
-        Nodes[Entity Nodes]
-        Edges[Relationship Edges]
-        Indexes[Vector Indexes<br/>Ollama embeddings]
-    end
-
-    Input --> Extraction
-    Extraction --> Storage
-    Storage --> Retrieval
-    
-    Input --> Entities
-    Entities --> Relationships
-    Relationships --> Episodes
-    Episodes --> Insights
-    
-    Entities --> Nodes
-    Relationships --> Edges
-    Edges --> Indexes
-    
-    Retrieval -.->|Enriches| Recommendations[AI Recommendations]
-    Insights -.->|Powers| Dashboard[Features Dashboard]
+ subgraph Input["Health Data Sources"]
+ Profile[Health Profile]
+ Reports[Medical Reports]
+ Questionnaire[User Questionnaires]
+ Assistant[AI Assistant Chats]
+ end
+
+ subgraph Memory["Mem0 Memory Layer"]
+ Extraction[Fact Extraction<br/>via Groq LLM]
+ Storage[ChromaDB<br/>Vector Store]
+ Retrieval[Semantic Search]
+ end
+
+ subgraph Graph["Graphiti Knowledge Graph"]
+ Entities[Entity Nodes<br/>conditions, metrics, meds]
+ Relationships[Temporal Relationships<br/>affects, caused_by, treats]
+ Episodes[Health Episodes<br/>time-stamped events]
+ Insights[AI-Generated Insights<br/>contradictions, patterns]
+ end
+
+ subgraph DB["Neo4j Graph Database"]
+ Nodes[Entity Nodes]
+ Edges[Relationship Edges]
+ Indexes[Vector Indexes<br/>Ollama embeddings]
+ end
+
+ Input --> Extraction
+ Extraction --> Storage
+ Storage --> Retrieval
+ 
+ Input --> Entities
+ Entities --> Relationships
+ Relationships --> Episodes
+ Episodes --> Insights
+ 
+ Entities --> Nodes
+ Relationships --> Edges
+ Edges --> Indexes
+ 
+ Retrieval -.->|Enriches| Recommendations[AI Recommendations]
+ Insights -.->|Powers| Dashboard[Features Dashboard]
 ```
 
 ### Key Features
@@ -299,9 +301,9 @@ flowchart TB
 #### 1. **Persistent Memory (Mem0)**
 
 - **Automatic Fact Extraction**: Converts natural language health data into structured facts
-  - "Sleep is about 5 hours per night" → Extracted memory fact
-  - "Has condition High Blood Pressure" → Indexed and searchable
-  - "BMI is 25.2 which falls in overweight range" → Computed and stored
+ - "Sleep is about 5 hours per night" → Extracted memory fact
+ - "Has condition High Blood Pressure" → Indexed and searchable
+ - "BMI is 25.2 which falls in overweight range" → Computed and stored
 
 - **User-Scoped Storage**: Each user's memories are isolated and secure
 - **Vector-Based Retrieval**: Semantic search powered by local Ollama embeddings (nomic-embed-text)
@@ -310,46 +312,46 @@ flowchart TB
 #### 2. **Knowledge Graph (Graphiti + Neo4j)**
 
 - **Entity Relationship Mapping**:
-  - Conditions связаны with symptoms, medications, and risk factors
-  - Lab values connected to reference ranges and health implications
-  - Lifestyle factors (sleep, diet, exercise) linked to health outcomes
+ - Conditions linked with symptoms, medications, and risk factors
+ - Lab values connected to reference ranges and health implications
+ - Lifestyle factors (sleep, diet, exercise) linked to health outcomes
 
 - **Temporal Reasoning**:
-  - Track health changes over time (BP trend: 140/90 in Jan → 130/85 in Feb)
-  - Episode creation for significant health events
-  - Valid/expired relationships based on temporal context
+ - Track health changes over time (BP trend: 140/90 in Jan → 130/85 in Feb)
+ - Episode creation for significant health events
+ - Valid/expired relationships based on temporal context
 
 - **Contradiction Detection**:
-  - Identifies conflicting health data (e.g., "no allergies" vs. "allergic to dust")
-  - Highlights diagnostic uncertainties
-  - Flags medication interactions
+ - Identifies conflicting health data (e.g., "no allergies" vs. "allergic to dust")
+ - Highlights diagnostic uncertainties
+ - Flags medication interactions
 
 - **Graph-Powered Insights**:
-  - **Temporal Patterns**: "BP decreased after starting medication X"
-  - **Key Relationships**: "High BMI correlates with elevated cholesterol"
-  - **Contradictions**: "Sleep reported as both 5hrs and 8hrs - needs clarification"
+ - **Temporal Patterns**: "BP decreased after starting medication X"
+ - **Key Relationships**: "High BMI correlates with elevated cholesterol"
+ - **Contradictions**: "Sleep reported as both 5hrs and 8hrs - needs clarification"
 
 #### 3. **Interactive Visualization**
 
 **Features Dashboard** (`/features`) provides:
 
 - **Memory Dashboard**:
-  - View all extracted health facts
-  - Search memories semantically
-  - Add/delete facts manually
-  - Real-time sync status
+ - View all extracted health facts
+ - Search memories semantically
+ - Add/delete facts manually
+ - Real-time sync status
 
 - **Knowledge Graph Viewer**:
-  - Interactive node-edge visualization
-  - Filter by conditions, medications, metrics
-  - Zoom/pan for detailed exploration
-  - Click nodes/edges for metadata
+ - Interactive node-edge visualization
+ - Filter by conditions, medications, metrics
+ - Zoom/pan for detailed exploration
+ - Click nodes/edges for metadata
 
 - **AI Insights Panel**:
-  - Temporal insights (trend analysis)
-  - Relationship insights (correlation patterns)
-  - Contradiction insights (data conflicts)
-  - Each insight includes evidence and confidence score
+ - Temporal insights (trend analysis)
+ - Relationship insights (correlation patterns)
+ - Contradiction insights (data conflicts)
+ - Each insight includes evidence and confidence score
 
 ### Technical Implementation
 
@@ -424,7 +426,7 @@ flowchart TB
 
 Lumea includes a comprehensive medicine management system that helps users find affordable generic alternatives to prescribed medicines and locate nearby pharmacies, including government-sponsored Jan Aushadhi Kendras offering subsidized medications.
 
-> ⚠️ **Medical Disclaimer**: This feature is a support tool for informational purposes only. It does NOT provide medical advice. Always consult your doctor or pharmacist before switching medicines or starting new treatments.
+> **Medical Disclaimer**: This feature is a support tool for informational purposes only. It does NOT provide medical advice. Always consult your doctor or pharmacist before switching medicines or starting new treatments.
 
 ### Overview
 
@@ -440,89 +442,89 @@ The Medicines feature enables users to:
 ### User Flow
 
 1. **Input Medicine Information**
-   - User enters brand name (e.g., "Aspirin 500mg") or uploads prescription image
-   - System extracts text via OCR or Grok AI parsing
+ - User enters brand name (e.g., "Aspirin 500mg") or uploads prescription image
+ - System extracts text via OCR or Grok AI parsing
 
 2. **Normalize Medicine Data**
-   - `MedicineNormalizer` service extracts: salt, strength, form (tablet/capsule/liquid), release type (immediate/sustained)
-   - Queries `GenericCatalog` table to validate and standardize extraction
+ - `MedicineNormalizer` service extracts: salt, strength, form (tablet/capsule/liquid), release type (immediate/sustained)
+ - Queries `GenericCatalog` table to validate and standardize extraction
 
 3. **Find Substitutes**
-   - `SubstituteFinder` queries database for alternatives with 4-tier ranked matching:
-     - **Tier 1** (1.0 score): Exact match on salt + strength + form + release type
-     - **Tier 2** (0.8 score): Same salt + strength + form
-     - **Tier 3** (0.6 score): Same salt + strength
-     - **Tier 4** (0.4 score): Same salt only
-   - Results sorted by price (Jan Aushadhi first for lowest cost)
+ - `SubstituteFinder` queries database for alternatives with 4-tier ranked matching:
+ - **Tier 1** (1.0 score): Exact match on salt + strength + form + release type
+ - **Tier 2** (0.8 score): Same salt + strength + form
+ - **Tier 3** (0.6 score): Same salt + strength
+ - **Tier 4** (0.4 score): Same salt only
+ - Results sorted by price (Jan Aushadhi first for lowest cost)
 
 4. **Locate Pharmacies** (Optional)
-   - User enters location (latitude/longitude) and search radius
-   - `PharmacyLocator` queries Google Places API for pharmacies
-   - Results include Jan Aushadhi Kendras (government pharmacies) and private pharmacies
-   - Results cached for 1 hour to reduce API calls
+ - User enters location (latitude/longitude) and search radius
+ - `PharmacyLocator` queries Google Places API for pharmacies
+ - Results include Jan Aushadhi Kendras (government pharmacies) and private pharmacies
+ - Results cached for 1 hour to reduce API calls
 
 5. **Save & Track**
-   - User can save medicines to personal list with notes
-   - Each save creates `UserSavedMedicine` entry for quick reference
+ - User can save medicines to personal list with notes
+ - Each save creates `UserSavedMedicine` entry for quick reference
 
 ### Architecture Diagram
 
 ```mermaid
 flowchart TB
-    subgraph Frontend["Frontend (React)"]
-        MedicinesPage["Medicines.tsx Page"]
-        SubstitutePanel["Substitute Finder Panel"]
-        PharmacyPanel["Pharmacy Locator Panel"]
-    end
-
-    subgraph API["Backend API (FastAPI)"]
-        NormalizeRoute["POST /normalize<br/>POST /normalize/batch"]
-        SubstituteRoute["POST /substitutes<br/>POST /substitutes/from-text"]
-        PharmacyRoute["GET /pharmacies/nearby<br/>GET /pharmacies/{id}<br/>POST /pharmacies/{id}/click"]
-        SavedRoute["POST /saved<br/>GET /saved<br/>DELETE /saved/{id}"]
-    end
-
-    subgraph Services["Backend Services"]
-        MedicineNormalizer["MedicineNormalizer<br/>- normalize()<br/>- normalize_batch()"]
-        SubstituteFinder["SubstituteFinder<br/>- find_substitutes()<br/>- save_medicine()"]
-        PharmacyLocator["PharmacyLocator<br/>- search_nearby()<br/>- get_place_details()<br/>- 1hr cache"]
-        GrokService["GrokMedicineService<br/>- get_alternatives_for_text()"]
-    end
-
-    subgraph External["External Services"]
-        GooglePlaces["Google Places API<br/>(Pharmacy Search)"]
-        GrokAPI["Grok xAI API<br/>(Medicine Parsing)"]
-    end
-
-    subgraph Storage["Data Layer"]
-        DB[(PostgreSQL)]
-        GenericCatalog["GenericCatalog Table<br/>(600K+ medicines)"]
-        UserSavedMedicine["UserSavedMedicine Table"]
-        SubstituteQuery["SubstituteQuery Table<br/>(Analytics)"]
-        PharmacyClick["PharmacyClick Table<br/>(Analytics)"]
-    end
-
-    MedicinesPage --> SubstitutePanel
-    MedicinesPage --> PharmacyPanel
-    SubstitutePanel --> SubstituteRoute
-    PharmacyPanel --> PharmacyRoute
-    PharmacyPanel --> SavedRoute
-
-    SubstituteRoute --> GrokService
-    SubstituteRoute --> MedicineNormalizer
-    SubstituteRoute --> SubstituteFinder
-    PharmacyRoute --> PharmacyLocator
-
-    MedicineNormalizer --> DB
-    MedicineNormalizer --> GenericCatalog
-    SubstituteFinder --> DB
-    SubstituteFinder --> GenericCatalog
-    SubstituteFinder --> SubstituteQuery
-    PharmacyLocator --> GooglePlaces
-    PharmacyLocator --> PharmacyClick
-
-    GrokService --> GrokAPI
-    GrokAPI -->|Parsed results| SubstituteFinder
+ subgraph Frontend["Frontend (React)"]
+ MedicinesPage["Medicines.tsx Page"]
+ SubstitutePanel["Substitute Finder Panel"]
+ PharmacyPanel["Pharmacy Locator Panel"]
+ end
+
+ subgraph API["Backend API (FastAPI)"]
+ NormalizeRoute["POST /normalize<br/>POST /normalize/batch"]
+ SubstituteRoute["POST /substitutes<br/>POST /substitutes/from-text"]
+ PharmacyRoute["GET /pharmacies/nearby<br/>GET /pharmacies/{id}<br/>POST /pharmacies/{id}/click"]
+ SavedRoute["POST /saved<br/>GET /saved<br/>DELETE /saved/{id}"]
+ end
+
+ subgraph Services["Backend Services"]
+ MedicineNormalizer["MedicineNormalizer<br/>- normalize()<br/>- normalize_batch()"]
+ SubstituteFinder["SubstituteFinder<br/>- find_substitutes()<br/>- save_medicine()"]
+ PharmacyLocator["PharmacyLocator<br/>- search_nearby()<br/>- get_place_details()<br/>- 1hr cache"]
+ GrokService["GrokMedicineService<br/>- get_alternatives_for_text()"]
+ end
+
+ subgraph External["External Services"]
+ GooglePlaces["Google Places API<br/>(Pharmacy Search)"]
+ GrokAPI["Grok xAI API<br/>(Medicine Parsing)"]
+ end
+
+ subgraph Storage["Data Layer"]
+ DB[(PostgreSQL)]
+ GenericCatalog["GenericCatalog Table<br/>(600K+ medicines)"]
+ UserSavedMedicine["UserSavedMedicine Table"]
+ SubstituteQuery["SubstituteQuery Table<br/>(Analytics)"]
+ PharmacyClick["PharmacyClick Table<br/>(Analytics)"]
+ end
+
+ MedicinesPage --> SubstitutePanel
+ MedicinesPage --> PharmacyPanel
+ SubstitutePanel --> SubstituteRoute
+ PharmacyPanel --> PharmacyRoute
+ PharmacyPanel --> SavedRoute
+
+ SubstituteRoute --> GrokService
+ SubstituteRoute --> MedicineNormalizer
+ SubstituteRoute --> SubstituteFinder
+ PharmacyRoute --> PharmacyLocator
+
+ MedicineNormalizer --> DB
+ MedicineNormalizer --> GenericCatalog
+ SubstituteFinder --> DB
+ SubstituteFinder --> GenericCatalog
+ SubstituteFinder --> SubstituteQuery
+ PharmacyLocator --> GooglePlaces
+ PharmacyLocator --> PharmacyClick
+
+ GrokService --> GrokAPI
+ GrokAPI -->|Parsed results| SubstituteFinder
 ```
 
 ### API Endpoints
@@ -547,47 +549,47 @@ flowchart TB
 Request:
 ```json
 {
-  "text": "Aspirin 500mg tablets"
+ "text": "Aspirin 500mg tablets"
 }
 ```
 
 Response:
 ```json
 {
-  "original_text": "Aspirin 500mg tablets",
-  "normalized": {
-    "brand_name": "Aspirin",
-    "salt": "Acetylsalicylic Acid",
-    "strength": "500",
-    "form": "tablet",
-    "release_type": "immediate",
-    "confidence": 0.95
-  },
-  "substitutes": [
-    {
-      "rank": 1,
-      "product_name": "Jan Aushadhi Aspirin 500mg",
-      "salt": "Acetylsalicylic Acid",
-      "strength": "500",
-      "form": "tablet",
-      "mrp": "5.00",
-      "is_jan_aushadhi": true,
-      "match_score": 1.0,
-      "match_reason": "Exact match: Same salt, strength, form, and type"
-    },
-    {
-      "rank": 2,
-      "product_name": "Ecosprin 500mg",
-      "salt": "Acetylsalicylic Acid",
-      "strength": "500",
-      "form": "tablet",
-      "mrp": "8.50",
-      "is_jan_aushadhi": false,
-      "match_score": 1.0,
-      "match_reason": "Exact match: Same salt, strength, form, and type"
-    }
-  ],
-  "disclaimer": "Always confirm with your doctor or pharmacist before switching medicines"
+ "original_text": "Aspirin 500mg tablets",
+ "normalized": {
+ "brand_name": "Aspirin",
+ "salt": "Acetylsalicylic Acid",
+ "strength": "500",
+ "form": "tablet",
+ "release_type": "immediate",
+ "confidence": 0.95
+ },
+ "substitutes": [
+ {
+ "rank": 1,
+ "product_name": "Jan Aushadhi Aspirin 500mg",
+ "salt": "Acetylsalicylic Acid",
+ "strength": "500",
+ "form": "tablet",
+ "mrp": "5.00",
+ "is_jan_aushadhi": true,
+ "match_score": 1.0,
+ "match_reason": "Exact match: Same salt, strength, form, and type"
+ },
+ {
+ "rank": 2,
+ "product_name": "Ecosprin 500mg",
+ "salt": "Acetylsalicylic Acid",
+ "strength": "500",
+ "form": "tablet",
+ "mrp": "8.50",
+ "is_jan_aushadhi": false,
+ "match_score": 1.0,
+ "match_reason": "Exact match: Same salt, strength, form, and type"
+ }
+ ],
+ "disclaimer": "Always confirm with your doctor or pharmacist before switching medicines"
 }
 ```
 
@@ -601,32 +603,32 @@ GET /api/medicines/pharmacies/nearby?lat=40.7128&lng=-74.0060&radius_m=1000&type
 Response:
 ```json
 {
-  "pharmacies": [
-    {
-      "place_id": "ChIJN1blbgBQwokRzKgy6E_B_1Q",
-      "name": "Jan Aushadhi Kendra - Downtown",
-      "address": "123 Main St, New York, NY 10001",
-      "latitude": 40.7128,
-      "longitude": -74.0060,
-      "rating": 4.7,
-      "is_open": true,
-      "is_jan_aushadhi": true,
-      "phone": "+1-212-555-0123"
-    },
-    {
-      "place_id": "ChIJrc_p_1BQwokRzKgy6E_B_2Q",
-      "name": "Metro Pharmacy",
-      "address": "456 Broadway, New York, NY 10002",
-      "latitude": 40.7150,
-      "longitude": -74.0030,
-      "rating": 4.2,
-      "is_open": true,
-      "is_jan_aushadhi": false,
-      "phone": "+1-212-555-0456"
-    }
-  ],
-  "next_page_token": null,
-  "total_results": 2
+ "pharmacies": [
+ {
+ "place_id": "ChIJN1blbgBQwokRzKgy6E_B_1Q",
+ "name": "Jan Aushadhi Kendra - Downtown",
+ "address": "123 Main St, New York, NY 10001",
+ "latitude": 40.7128,
+ "longitude": -74.0060,
+ "rating": 4.7,
+ "is_open": true,
+ "is_jan_aushadhi": true,
+ "phone": "+1-212-555-0123"
+ },
+ {
+ "place_id": "ChIJrc_p_1BQwokRzKgy6E_B_2Q",
+ "name": "Metro Pharmacy",
+ "address": "456 Broadway, New York, NY 10002",
+ "latitude": 40.7150,
+ "longitude": -74.0030,
+ "rating": 4.2,
+ "is_open": true,
+ "is_jan_aushadhi": false,
+ "phone": "+1-212-555-0456"
+ }
+ ],
+ "next_page_token": null,
+ "total_results": 2
 }
 ```
 
@@ -636,36 +638,36 @@ Response:
 
 Lumea includes a fully integrated **Voice Agent** that provides an ElevenLabs-style conversational health assistant experience. Users can speak naturally to the AI agent, which responds with personalized health guidance based on their profile, conditions, medications, allergies, and recent lab reports.
 
-> ⚠️ **Medical Disclaimer**: The Voice Agent is an informational support tool. It does NOT provide medical diagnosis, dosage recommendations, or emergency care. Always consult licensed healthcare professionals for medical decisions.
+> **Medical Disclaimer**: The Voice Agent is an informational support tool. It does NOT provide medical diagnosis, dosage recommendations, or emergency care. Always consult licensed healthcare professionals for medical decisions.
 
 ### Overview
 
-The Voice Agent transforms how users interact with their health data through natural voice conversations powered by cutting-edge AI technologies.
+The Voice Agent enables users to interact with their health data through natural voice conversations powered by AI.
 
 **Key Capabilities**:
 
-- **🎙️ Voice Interaction**: Speak naturally using browser-based speech recognition (Web Speech API)
-- **🧠 Personalized AI Responses**: Powered by Google Gemini with access to your complete health profile
-- **🔊 Natural Speech Output**: Human-like voice responses via ElevenLabs TTS (with browser fallback)
-- **🛡️ Medical Safety Filters**: Detects emergency keywords, dosage inquiries, and provides appropriate safety responses
-- **⚡ Real-time Feedback**: Visual orb animations reflect listening/thinking/speaking states
-- **📝 Transcript View**: Optional chat-mode panel displays conversation history
-- **🎯 Context-Aware**: Accesses your health conditions, medications, allergies, recent reports, and RAG-indexed data
+- **Voice Interaction**: Speak naturally using browser-based speech recognition (Web Speech API)
+- **Personalized AI Responses**: Powered by Google Gemini with access to your complete health profile
+- **Natural Speech Output**: Voice responses via ElevenLabs TTS (with browser fallback)
+- **Medical Safety Filters**: Detects emergency keywords, dosage inquiries, and provides appropriate safety responses
+- **Real-time Feedback**: Visual orb animations reflect listening/thinking/speaking states
+- **Transcript View**: Optional chat-mode panel displays conversation history
+- **Context-Aware**: Accesses your health conditions, medications, allergies, recent reports, and RAG-indexed data
 
 ### How It Works
 
-The Voice Agent uses a sophisticated three-stage pipeline to deliver personalized health conversations:
+The Voice Agent uses a three-stage pipeline to deliver personalized health conversations:
 
 ```mermaid
 graph LR
-    A[👤 User Speaks] --> B[🎤 Browser STT<br/>Web Speech API]
-    B --> C[🧠 LLM Processing<br/>Google Gemini]
-    C --> D[📊 Health Context<br/>Profile + Reports + RAG]
-    D --> C
-    C --> E[🔊 Text-to-Speech<br/>ElevenLabs API]
-    E --> F[🔉 Browser Fallback<br/>Web Speech API]
-    E --> G[👤 User Hears Response]
-    F --> G
+ A[User Speaks] --> B[Browser STT<br/>Web Speech API]
+ B --> C[LLM Processing<br/>Google Gemini]
+ C --> D[Health Context<br/>Profile + Reports + RAG]
+ D --> C
+ C --> E[Text-to-Speech<br/>ElevenLabs API]
+ E --> F[Browser Fallback<br/>Web Speech API]
+ E --> G[User Hears Response]
+ F --> G
 ```
 
 #### Stage 1: Speech-to-Text (STT)
@@ -677,75 +679,75 @@ graph LR
 #### Stage 2: AI Processing & Context Retrieval
 - **LLM Provider**: Google Gemini API (`gemini-flash-latest`)
 - **Health Context Integration**:
-  - User demographics (age, gender, BMI)
-  - Active medical conditions
-  - Current medications (name, dose, frequency)
-  - Known allergies and their severity
-  - Recent lab reports and observations
-  - Lifestyle factors (sleep, exercise, smoking, alcohol)
+ - User demographics (age, gender, BMI)
+ - Active medical conditions
+ - Current medications (name, dose, frequency)
+ - Known allergies and their severity
+ - Recent lab reports and observations
+ - Lifestyle factors (sleep, exercise, smoking, alcohol)
 - **RAG Enhancement**: Queries ChromaDB vector store for relevant historical health data
 - **Safety Layer**: HIPAA-compliant system prompt with strict medical guidelines:
-  - Never diagnose conditions
-  - Never recommend medication dosages
-  - Always suggest professional consultation
-  - Detect emergency situations and direct to 911
+ - Never diagnose conditions
+ - Never recommend medication dosages
+ - Always suggest professional consultation
+ - Detect emergency situations and direct to 911
 
 #### Stage 3: Text-to-Speech (TTS)
 - **Primary**: ElevenLabs TTS API
-  - Model: `eleven_turbo_v2_5` (optimized for speed, free tier compatible)
-  - Voice: Rachel (`21m00Tcm4TlvDq8ikWAM`)
-  - Quality: Studio-grade natural voice synthesis
+ - Model: `eleven_turbo_v2_5` (optimized for speed, free tier compatible)
+ - Voice: Rachel (`21m00Tcm4TlvDq8ikWAM`)
+ - Quality: Natural voice synthesis
 - **Fallback**: Browser Text-to-Speech API
-  - Activates automatically if ElevenLabs unavailable (503 errors)
-  - Uses system voices
-  - Zero latency, no API costs
+ - Activates automatically if ElevenLabs unavailable (503 errors)
+ - Uses system voices
+ - Zero latency, no API costs
 
 ### Real-World Benefits
 
 **For Everyday Users**:
-- 🏃 **Hands-Free Access**: Check health info while cooking, exercising, or commuting
-- 💬 **Natural Conversations**: Ask questions in plain language, no medical jargon required
-- 📱 **Accessibility**: Ideal for users with visual impairments or reading difficulties
-- ⚡ **Quick Insights**: Faster than navigating multiple screens and charts
+- **Hands-Free Access**: Check health info while cooking, exercising, or commuting
+- **Natural Conversations**: Ask questions in plain language, no medical jargon required
+- **Accessibility**: Ideal for users with visual impairments or reading difficulties
+- **Quick Insights**: Faster than navigating multiple screens and charts
 
 **For Health-Conscious Individuals**:
-- 🔍 **Report Interpretation**: "What do my cholesterol levels mean?"
-- 💊 **Medication Context**: "Why am I taking this medication?"
-- 📊 **Trend Analysis**: "How has my blood pressure changed over time?"
-- 🎯 **Personalized Guidance**: Responses tailored to YOUR specific health profile
+- **Report Interpretation**: "What do my cholesterol levels mean?"
+- **Medication Context**: "Why am I taking this medication?"
+- **Trend Analysis**: "How has my blood pressure changed over time?"
+- **Personalized Guidance**: Responses tailored to your specific health profile
 
 **Safety & Reliability**:
-- 🚨 **Emergency Detection**: Recognizes crisis keywords (chest pain, can't breathe, etc.)
-- 💊 **Dosage Protection**: Refuses to recommend medication changes
-- 🔒 **HIPAA Guidelines**: All responses include disclaimers and professional consultation advice
-- 🌐 **Fallback Mechanisms**: Graceful degradation if AI/TTS services unavailable
+- **Emergency Detection**: Recognizes crisis keywords (chest pain, can't breathe, etc.)
+- **Dosage Protection**: Refuses to recommend medication changes
+- **HIPAA Guidelines**: All responses include disclaimers and professional consultation advice
+- **Fallback Mechanisms**: Graceful degradation if AI/TTS services unavailable
 
 ### API Endpoints
 
 | Method | Endpoint | Description | Auth | Response |
 |--------|----------|-------------|------|----------|
-| GET | `/api/voice/context` | Get user health context summary with profile completeness status | ✅ Yes | `{profile_complete: bool, summary: {...}, has_personalization: bool}` |
-| POST | `/api/voice/answer` | Generate personalized AI answer using Gemini + health context | ✅ Yes | `{answer_text: string, flags: [string], used_context: {...}}` |
-| POST | `/api/voice/tts` | Convert text to speech using ElevenLabs API | ✅ Yes | Binary audio stream (MP3) |
-| GET | `/api/voice/tts/status` | Check ElevenLabs TTS configuration status | ✅ Yes | `{configured: bool, voice_id: string, runtime_check: {...}}` |
+| GET | `/api/voice/context` | Get user health context summary with profile completeness status | Yes | `{profile_complete: bool, summary: {...}, has_personalization: bool}` |
+| POST | `/api/voice/answer` | Generate personalized AI answer using Gemini + health context | Yes | `{answer_text: string, flags: [string], used_context: {...}}` |
+| POST | `/api/voice/tts` | Convert text to speech using ElevenLabs API | Yes | Binary audio stream (MP3) |
+| GET | `/api/voice/tts/status` | Check ElevenLabs TTS configuration status | Yes | `{configured: bool, voice_id: string, runtime_check: {...}}` |
 
 **Context Response Details**:
 ```json
 {
-  "profile_complete": true,
-  "has_personalization": true,
-  "summary": {
-    "name": "Darshan Ved",
-    "age": 49,
-    "gender": "Male",
-    "bmi": 21.5,
-    "conditions": ["Hypertension"],
-    "medications": ["Lisinopril 10mg"],
-    "allergies": ["Penicillin"],
-    "reports_count": 5,
-    "sleep_hours": 7,
-    "exercise_frequency": "3-4 times/week"
-  }
+ "profile_complete": true,
+ "has_personalization": true,
+ "summary": {
+ "name": "Darshan Ved",
+ "age": 49,
+ "gender": "Male",
+ "bmi": 21.5,
+ "conditions": ["Hypertension"],
+ "medications": ["Lisinopril 10mg"],
+ "allergies": ["Penicillin"],
+ "reports_count": 5,
+ "sleep_hours": 7,
+ "exercise_frequency": "3-4 times/week"
+ }
 }
 ```
 
@@ -764,12 +766,12 @@ Add to **root `.env`** (for Docker) and **`backend/.env`** (for local developmen
 # ===== AI/LLM Configuration =====
 # Google Gemini API (Primary LLM for Voice Agent)
 USE_GEMINI_FALLBACK=true
-GEMINI_API_KEY=AIzaSy...  # Get from https://aistudio.google.com/apikey
+GEMINI_API_KEY=AIzaSy... # Get from https://aistudio.google.com/apikey
 
 # ===== Text-to-Speech Configuration =====
 # ElevenLabs TTS for Voice Agent (Optional - has browser fallback)
-ELEVENLABS_API_KEY=sk_...  # Get from https://elevenlabs.io/
-ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM  # Rachel voice (recommended)
+ELEVENLABS_API_KEY=sk_... # Get from https://elevenlabs.io/
+ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM # Rachel voice (recommended)
 ```
 
 #### Docker Configuration
@@ -778,13 +780,13 @@ Ensure `docker-compose.yml` includes these environment variables in the backend
 
 ```yaml
 services:
-  backend:
-    environment:
-      # ... other env vars ...
-      - GEMINI_API_KEY=${GEMINI_API_KEY:-}
-      - USE_GEMINI_FALLBACK=${USE_GEMINI_FALLBACK:-true}
-      - ELEVENLABS_API_KEY=${ELEVENLABS_API_KEY:-}
-      - ELEVENLABS_VOICE_ID=${ELEVENLABS_VOICE_ID:-21m00Tcm4TlvDq8ikWAM}
+ backend:
+ environment:
+ # ... other env vars ...
+ - GEMINI_API_KEY=${GEMINI_API_KEY:-}
+ - USE_GEMINI_FALLBACK=${USE_GEMINI_FALLBACK:-true}
+ - ELEVENLABS_API_KEY=${ELEVENLABS_API_KEY:-}
+ - ELEVENLABS_VOICE_ID=${ELEVENLABS_VOICE_ID:-21m00Tcm4TlvDq8ikWAM}
 ```
 
 #### Getting API Keys
@@ -803,13 +805,13 @@ services:
 3. Create new API key (starts with `sk_...`)
 4. Free tier includes: 10,000 characters/month
 5. Recommended voice IDs:
-   - `21m00Tcm4TlvDq8ikWAM` - Rachel (conversational, female)
-   - `ErXwobaYiN019PkySvjV` - Antoni (clear, male)
-   - `EXAVITQu4vr4xnSDxMaL` - Bella (warm, female)
+ - `21m00Tcm4TlvDq8ikWAM` - Rachel (conversational, female)
+ - `ErXwobaYiN019PkySvjV` - Antoni (clear, male)
+ - `EXAVITQu4vr4xnSDxMaL` - Bella (warm, female)
 
 **Free Tier Model Compatibility**:
-- ✅ Works: `gemini-flash-latest`, `gemini-1.5-flash-8b`
-- ❌ Quota exceeded: `gemini-2.0-flash`, `gemini-2.5-flash` (requires paid tier)
+- Works: `gemini-flash-latest`, `gemini-1.5-flash-8b`
+- Quota exceeded: `gemini-2.0-flash`, `gemini-2.5-flash` (requires paid tier)
 
 ### Technology Stack
 
@@ -847,19 +849,19 @@ services:
 
 ```bash
 curl -X GET http://localhost:8000/api/voice/tts/status \
-  -H "Authorization: Bearer <your_jwt_token>"
+ -H "Authorization: Bearer <your_jwt_token>"
 ```
 
 **Expected Response**:
 ```json
 {
-  "configured": true,
-  "voice_id": "21m00Tcm4TlvDq8ikWAM",
-  "runtime_check": {
-    "api_key_loaded": true,
-    "api_key_prefix": "sk_d78...",
-    "voice_id": "21m00Tcm4TlvDq8ikWAM"
-  }
+ "configured": true,
+ "voice_id": "21m00Tcm4TlvDq8ikWAM",
+ "runtime_check": {
+ "api_key_loaded": true,
+ "api_key_prefix": "sk_d78...",
+ "voice_id": "21m00Tcm4TlvDq8ikWAM"
+ }
 }
 ```
 
@@ -867,24 +869,24 @@ curl -X GET http://localhost:8000/api/voice/tts/status \
 
 ```bash
 curl -X GET http://localhost:8000/api/voice/context \
-  -H "Authorization: Bearer <your_jwt_token>"
+ -H "Authorization: Bearer <your_jwt_token>"
 ```
 
 **Expected Response**:
 ```json
 {
-  "profile_complete": true,
-  "has_personalization": true,
-  "summary": {
-    "name": "Darshan Ved",
-    "age": 49,
-    "gender": "Male",
-    "bmi": 21.5,
-    "conditions": ["Hypertension"],
-    "medications": ["Lisinopril"],
-    "allergies": ["Penicillin"],
-    "reports_count": 5
-  }
+ "profile_complete": true,
+ "has_personalization": true,
+ "summary": {
+ "name": "Darshan Ved",
+ "age": 49,
+ "gender": "Male",
+ "bmi": 21.5,
+ "conditions": ["Hypertension"],
+ "medications": ["Lisinopril"],
+ "allergies": ["Penicillin"],
+ "reports_count": 5
+ }
 }
 ```
 
@@ -892,24 +894,24 @@ curl -X GET http://localhost:8000/api/voice/context \
 
 ```bash
 curl -X POST http://localhost:8000/api/voice/answer \
-  -H "Authorization: Bearer <your_jwt_token>" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "text": "What do my cholesterol levels mean?"
-  }'
+ -H "Authorization: Bearer <your_jwt_token>" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "text": "What do my cholesterol levels mean?"
+ }'
 ```
 
 **Expected Response**:
 ```json
 {
-  "answer_text": "Based on your recent lab reports, your total cholesterol is 195 mg/dL, which falls within the desirable range (below 200 mg/dL). Your LDL cholesterol is 110 mg/dL, also in the optimal range. However, I recommend discussing these results with your healthcare provider for personalized guidance based on your hypertension condition.",
-  "flags": [],
-  "used_context": {
-    "has_profile": true,
-    "conditions_count": 1,
-    "medications_count": 1,
-    "has_rag_context": true
-  }
+ "answer_text": "Based on your recent lab reports, your total cholesterol is 195 mg/dL, which falls within the desirable range (below 200 mg/dL). Your LDL cholesterol is 110 mg/dL, also in the optimal range. However, I recommend discussing these results with your healthcare provider for personalized guidance based on your hypertension condition.",
+ "flags": [],
+ "used_context": {
+ "has_profile": true,
+ "conditions_count": 1,
+ "medications_count": 1,
+ "has_rag_context": true
+ }
 }
 ```
 
@@ -917,10 +919,10 @@ curl -X POST http://localhost:8000/api/voice/answer \
 
 ```bash
 curl -X POST http://localhost:8000/api/voice/tts \
-  -H "Authorization: Bearer <your_jwt_token>" \
-  -H "Content-Type: application/json" \
-  -d '{"text": "Hello! Your health data shows positive trends."}' \
-  --output test_voice.mp3
+ -H "Authorization: Bearer <your_jwt_token>" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "Hello! Your health data shows positive trends."}' \
+ --output test_voice.mp3
 
 # Play the audio file
 # Windows: start test_voice.mp3
@@ -933,34 +935,34 @@ curl -X POST http://localhost:8000/api/voice/tts \
 **Emergency Detection Test**:
 ```bash
 curl -X POST http://localhost:8000/api/voice/answer \
-  -H "Authorization: Bearer <your_jwt_token>" \
-  -H "Content-Type: application/json" \
-  -d '{"text": "I am having severe chest pain"}'
+ -H "Authorization: Bearer <your_jwt_token>" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "I am having severe chest pain"}'
 ```
 
 **Expected Response**:
 ```json
 {
-  "answer_text": "I'm detecting words that suggest this might be an emergency situation. Please call emergency services immediately (911) or go to the nearest emergency room...",
-  "flags": ["emergency"],
-  "used_context": {}
+ "answer_text": "I'm detecting words that suggest this might be an emergency situation. Please call emergency services immediately (911) or go to the nearest emergency room...",
+ "flags": ["emergency"],
+ "used_context": {}
 }
 ```
 
 **Dosage Inquiry Test**:
 ```bash
 curl -X POST http://localhost:8000/api/voice/answer \
-  -H "Authorization: Bearer <your_jwt_token>" \
-  -H "Content-Type: application/json" \
-  -d '{"text": "Can I double my medication dosage?"}'
+ -H "Authorization: Bearer <your_jwt_token>" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "Can I double my medication dosage?"}'
 ```
 
 **Expected Response**:
 ```json
 {
-  "answer_text": "I cannot provide specific dosage recommendations. Please consult your doctor or pharmacist before making any changes to your medications...",
-  "flags": ["dosage_inquiry"],
-  "used_context": {...}
+ "answer_text": "I cannot provide specific dosage recommendations. Please consult your doctor or pharmacist before making any changes to your medications...",
+ "flags": ["dosage_inquiry"],
+ "used_context": {...}
 }
 ```
 
@@ -972,20 +974,20 @@ curl -X POST http://localhost:8000/api/voice/answer \
 
 **Solutions**:
 1. **Check API Key Loading**:
-   ```bash
-   docker exec ggw-backend python -c "from app.settings import settings; print(f'API Key: {settings.ELEVENLABS_API_KEY[:20] if settings.ELEVENLABS_API_KEY else None}...')"
-   ```
+ ```bash
+ docker exec ggw-backend python -c "from app.settings import settings; print(f'API Key: {settings.ELEVENLABS_API_KEY[:20] if settings.ELEVENLABS_API_KEY else None}...')"
+ ```
 
 2. **Verify Environment Variables**:
-   - Ensure `ELEVENLABS_API_KEY` is in root `.env` file
-   - Ensure `docker-compose.yml` includes the env var mapping
-   - Restart Docker containers: `docker compose restart backend`
+ - Ensure `ELEVENLABS_API_KEY` is in root `.env` file
+ - Ensure `docker-compose.yml` includes the env var mapping
+ - Restart Docker containers: `docker compose restart backend`
 
 3. **Check API Key Validity**:
-   ```bash
-   curl https://api.elevenlabs.io/v1/voices \
-     -H "xi-api-key: sk_your_key_here"
-   ```
+ ```bash
+ curl https://api.elevenlabs.io/v1/voices \
+ -H "xi-api-key: sk_your_key_here"
+ ```
 
 #### Issue: Gemini API 404 or 429 Errors
 
@@ -993,19 +995,19 @@ curl -X POST http://localhost:8000/api/voice/answer \
 
 **Solutions**:
 1. **Verify Model Compatibility**:
-   ```bash
-   docker exec ggw-backend python -c "import google.generativeai as genai; import os; genai.configure(api_key=os.environ['GEMINI_API_KEY']); models = [m.name for m in genai.list_models() if 'generateContent' in m.supported_generation_methods]; print('\n'.join(models))"
-   ```
+ ```bash
+ docker exec ggw-backend python -c "import google.generativeai as genai; import os; genai.configure(api_key=os.environ['GEMINI_API_KEY']); models = [m.name for m in genai.list_models() if 'generateContent' in m.supported_generation_methods]; print('\n'.join(models))"
+ ```
 
 2. **Check Free Tier Limits**:
-   - Free tier model: `gemini-flash-latest` ✅
-   - Paid tier models: `gemini-2.0-flash`, `gemini-2.5-flash` ❌
-   - Rate limits: 15 requests/minute, 1M tokens/day
+ - Free tier model: `gemini-flash-latest` 
+ - Paid tier models: `gemini-2.0-flash`, `gemini-2.5-flash` 
+ - Rate limits: 15 requests/minute, 1M tokens/day
 
 3. **Update Model Name** (if needed):
-   - Edit `backend/app/services/llm_service.py`
-   - Change model to `gemini-flash-latest`
-   - Restart backend
+ - Edit `backend/app/services/llm_service.py`
+ - Change model to `gemini-flash-latest`
+ - Restart backend
 
 #### Issue: "ProfileMedication object has no attribute 'medication_name'"
 
@@ -1026,16 +1028,16 @@ curl -X POST http://localhost:8000/api/voice/answer \
 ### Example Conversations
 
 **General Health Query**:
-- 👤 User: "What does my health profile show?"
-- 🤖 Assistant: "You're a 49-year-old male with a healthy BMI of 21.5. Your profile shows hypertension, and you're currently taking Lisinopril. You have 5 health reports on file. Is there specific information you'd like me to explain?"
+- User: "What does my health profile show?"
+- Assistant: "You're a 49-year-old male with a healthy BMI of 21.5. Your profile shows hypertension, and you're currently taking Lisinopril. You have 5 health reports on file. Is there specific information you'd like me to explain?"
 
 **Lab Result Interpretation**:
-- 👤 User: "Explain my recent cholesterol test"
-- 🤖 Assistant: "Your recent cholesterol panel shows total cholesterol at 195 mg/dL, which is in the desirable range. Your LDL is 110 mg/dL and HDL is 55 mg/dL. Given your hypertension, maintaining these levels is important. Discuss with your doctor about your diet and medication effectiveness."
+- User: "Explain my recent cholesterol test"
+- Assistant: "Your recent cholesterol panel shows total cholesterol at 195 mg/dL, which is in the desirable range. Your LDL is 110 mg/dL and HDL is 55 mg/dL. Given your hypertension, maintaining these levels is important. Discuss with your doctor about your diet and medication effectiveness."
 
 **Medication Context**:
-- 👤 User: "Why am I taking Lisinopril?"
-- 🤖 Assistant: "Lisinopril is an ACE inhibitor prescribed for managing hypertension, which is noted in your health profile. It helps lower blood pressure by relaxing blood vessels. Always take it as prescribed and discuss any side effects with your healthcare provider."
+- User: "Why am I taking Lisinopril?"
+- Assistant: "Lisinopril is an ACE inhibitor prescribed for managing hypertension, which is noted in your health profile. It helps lower blood pressure by relaxing blood vessels. Always take it as prescribed and discuss any side effects with your healthcare provider."
 
 ---
 
@@ -1043,21 +1045,23 @@ curl -X POST http://localhost:8000/api/voice/answer \
 
 Lumea's **Physics Twin** is a comprehensive digital health analysis engine that transforms raw health metrics from uploaded medical reports into deterministic organ-level health scores and real-time condition detection. It provides an interactive 3D body visualization, time-series telemetry monitoring, and AI-powered health recommendations grounded in your actual medical data.
 
-> ⚠️ **Medical Disclaimer**: The Physics Twin is a visualization and analysis support tool. It does NOT provide medical diagnosis or treatment. Values are computed from extracted lab data and should be verified by healthcare professionals. Use for personal health tracking only—always consult a licensed healthcare professional for medical decisions.
+> **Medical Disclaimer**: The Physics Twin is a visualization and analysis support tool. It does NOT provide medical diagnosis or treatment. Values are computed from extracted lab data and should be verified by healthcare professionals. Use for personal health tracking only—always consult a licensed healthcare professional for medical decisions.
 
 ### Overview
 
 The Physics Twin delivers:
 
-- **🏥 Deterministic Organ Scoring**: Evidence-based scoring for 6 organs (kidney, heart, liver, lungs, brain, blood) based on reference ranges and clinical normalisation
-- **🔬 Real Data Integration**: Pulls metrics directly from your uploaded medical reports (not simulated) via the `Observation` table
-- **📊 Interactive 3D Body**: Clickable organ hotspots with animated scoring visualizations and trend indicators
-- **❤️ Real-Time Telemetry**: Simulated vital signs stream via SSE (Server-Sent Events) with SpO₂, heart rate, blood pressure, stress, and glucose tracking
-- **⚠️ Condition Detection**: 10 rule-based conditions (Hypertension, Tachycardia, Kidney Stress, Liver Stress, Hyperglycemia, Sleep Deprivation, etc.) automatically detected from current metrics
-- **👁️ Body Impact Overlay**: 2D SVG body silhouette highlighting organs affected by detected conditions with severity-based color coding
-- **💊 Smart Recommendations**: Context-aware health recommendations with YouTube educational links for each detected condition
-- **📈 Time-Series History**: View per-report organ scores, historical trends, and scored snapshots over time
-- **🧬 Lifestyle Integration**: Incorporates UserProfile self-reported data (sleep hours, stress level, activity level) into organ scoring
+- **Deterministic Organ Scoring**: Evidence-based scoring for 6 organs (kidney, heart, liver, lungs, brain, blood) based on reference ranges and clinical normalisation
+- **Real Data Integration**: Pulls metrics directly from your uploaded medical reports (not simulated) via the `Observation` table
+- **Interactive 3D Body**: Clickable organ hotspots with animated scoring visualizations and trend indicators
+- **Real-Time Telemetry**: Simulated vital signs stream via SSE (Server-Sent Events) with SpO2, heart rate, blood pressure, stress, and glucose tracking
+- **Condition Detection**: 10 rule-based conditions (Hypertension, Tachycardia, Kidney Stress, Liver Stress, Hyperglycemia, Sleep Deprivation, etc.) automatically detected from current metrics
+- **Body Impact Overlay**: 2D SVG body silhouette highlighting organs affected by detected conditions with severity-based color coding
+- **Smart Recommendations**: Context-aware health recommendations with YouTube educational links for each detected condition
+- **AI Video Recommendations**: OpenRouter-powered personalized health video suggestions for each organ based on abnormal metrics, displayed in a side-by-side "Improve Your Health" card with per-organ caching
+- **Explainability Panel**: Side-by-side "Why This Score?" card showing metric contributions, weights, coverage, and confidence for each organ
+- **Time-Series History**: View per-report organ scores, historical trends, and scored snapshots over time
+- **Lifestyle Integration**: Incorporates UserProfile self-reported data (sleep hours, stress level, activity level) into organ scoring
 
 ### How It Works
 
@@ -1089,50 +1093,50 @@ LAYER 3: Condition Detection & Recommendations
 
 ```mermaid
 graph TB
-    subgraph Database["PostgreSQL"]
-        Observation["Observation Table<br/>(extracted metrics)"]
-        UserProfile["UserProfile Table<br/>(lifestyle data)"]
-        Report["Report Table<br/>(source documents)"]
-    end
-
-    subgraph Backend["Backend Services"]
-        PhysicsConfig["physics_config.py<br/>- Organ specs<br/>- Metric weights<br/>- Reference ranges"]
-        PhysicsRoute["physics.py Routes<br/>- GET /latest (auto-compute)<br/>- GET /history (per-report)<br/>- POST /metrics (manual)<br/>- GET /config"]
-        Scorer["Scoring Engine<br/>- compute_organ_score()<br/>- compute_all_organs()"]
-        ConditionEngine["conditions.py<br/>- detect_conditions()<br/>- 10 rule-based conditions<br/>- Severity mapping<br/>- Organ mapping"]
-        TelemetryRoute["telemetry.py Routes<br/>- GET /stream (SSE)<br/>- GET /latest<br/>- GET /history"]
-    end
-
-    subgraph Frontend["Frontend Components"]
-        PhysicsTwin["PhysicsTwin.tsx<br/>- Main page orchestrator<br/>- Tab navigation (Twin/Metrics/History)"]
-        TwinViewer["TwinViewer.tsx<br/>- 3D body with Three.js<br/>- Organ hotspots<br/>- Auto-rotate"]
-        BodyOverlay["BodyImpactOverlay.tsx<br/>- SVG body silhouette<br/>- Animated organ zones<br/>- Gender toggle"]
-        OrganTelemetry["OrganTelemetryCard.tsx<br/>- Overall score display<br/>- Selected organ detail<br/>- Metric values"]
-        Explainability["ExplainabilityCard.tsx<br/>- Scoring breakdown<br/>- Weight contributions<br/>- Coverage/confidence"]
-        Recommendations["RecommendationsCard.tsx<br/>- Detected conditions<br/>- Evidence-based actions<br/>- YouTube links"]
-        ConditionsEngine["conditionsEngine.ts<br/>- Client-side condition detection<br/>- Rapid re-evaluation<br/>- Trend computation"]
-        TelemetryHook["useTelemetryStream.ts<br/>- SSE connection manager<br/>- Fallback simulation<br/>- History buffer (120 readings)"]
-    end
-
-    Observation -->|Query last 90 days| PhysicsRoute
-    UserProfile -->|Enrich with lifestyle| PhysicsRoute
-    Report -->|Group snapshots by| PhysicsRoute
-
-    PhysicsRoute -->|Load config| PhysicsConfig
-    PhysicsRoute -->|Compute scores| Scorer
-    Scorer -->|Detect conditions| ConditionEngine
-
-    TelemetryRoute -->|Generate readings| TelemetryHook
-    PhysicsRoute -->|Return snapshot| PhysicsTwin
-
-    PhysicsTwin -->|Render organs| TwinViewer
-    PhysicsTwin -->|Show overlay| BodyOverlay
-    PhysicsTwin -->|Display score| OrganTelemetry
-    PhysicsTwin -->|Show breakdown| Explainability
-    PhysicsTwin -->|Detect conditions| ConditionsEngine
-    ConditionsEngine -->|Map to organs| BodyOverlay
-    ConditionsEngine -->|Show recommendations| Recommendations
-    TelemetryHook -->|Stream vitals| PhysicsTwin
+ subgraph Database["PostgreSQL"]
+ Observation["Observation Table<br/>(extracted metrics)"]
+ UserProfile["UserProfile Table<br/>(lifestyle data)"]
+ Report["Report Table<br/>(source documents)"]
+ end
+
+ subgraph Backend["Backend Services"]
+ PhysicsConfig["physics_config.py<br/>- Organ specs<br/>- Metric weights<br/>- Reference ranges"]
+ PhysicsRoute["physics.py Routes<br/>- GET /latest (auto-compute)<br/>- GET /history (per-report)<br/>- POST /metrics (manual)<br/>- GET /config"]
+ Scorer["Scoring Engine<br/>- compute_organ_score()<br/>- compute_all_organs()"]
+ ConditionEngine["conditions.py<br/>- detect_conditions()<br/>- 10 rule-based conditions<br/>- Severity mapping<br/>- Organ mapping"]
+ TelemetryRoute["telemetry.py Routes<br/>- GET /stream (SSE)<br/>- GET /latest<br/>- GET /history"]
+ end
+
+ subgraph Frontend["Frontend Components"]
+ PhysicsTwin["PhysicsTwin.tsx<br/>- Main page orchestrator<br/>- Tab navigation (Twin/Metrics/History)"]
+ TwinViewer["TwinViewer.tsx<br/>- 3D body with Three.js<br/>- Organ hotspots<br/>- Auto-rotate"]
+ BodyOverlay["BodyImpactOverlay.tsx<br/>- SVG body silhouette<br/>- Animated organ zones<br/>- Gender toggle"]
+ OrganTelemetry["OrganTelemetryCard.tsx<br/>- Overall score display<br/>- Selected organ detail<br/>- Metric values"]
+ Explainability["ExplainabilityCard.tsx<br/>- Scoring breakdown<br/>- Weight contributions<br/>- Coverage/confidence"]
+ Recommendations["RecommendationsCard.tsx<br/>- Detected conditions<br/>- Evidence-based actions<br/>- YouTube links"]
+ ConditionsEngine["conditionsEngine.ts<br/>- Client-side condition detection<br/>- Rapid re-evaluation<br/>- Trend computation"]
+ TelemetryHook["useTelemetryStream.ts<br/>- SSE connection manager<br/>- Fallback simulation<br/>- History buffer (120 readings)"]
+ end
+
+ Observation -->|Query last 90 days| PhysicsRoute
+ UserProfile -->|Enrich with lifestyle| PhysicsRoute
+ Report -->|Group snapshots by| PhysicsRoute
+
+ PhysicsRoute -->|Load config| PhysicsConfig
+ PhysicsRoute -->|Compute scores| Scorer
+ Scorer -->|Detect conditions| ConditionEngine
+
+ TelemetryRoute -->|Generate readings| TelemetryHook
+ PhysicsRoute -->|Return snapshot| PhysicsTwin
+
+ PhysicsTwin -->|Render organs| TwinViewer
+ PhysicsTwin -->|Show overlay| BodyOverlay
+ PhysicsTwin -->|Display score| OrganTelemetry
+ PhysicsTwin -->|Show breakdown| Explainability
+ PhysicsTwin -->|Detect conditions| ConditionsEngine
+ ConditionsEngine -->|Map to organs| BodyOverlay
+ ConditionsEngine -->|Show recommendations| Recommendations
+ TelemetryHook -->|Stream vitals| PhysicsTwin
 ```
 
 ### Core Concepts
@@ -1154,15 +1158,15 @@ Each metric is **normalised to 0-1** based on clinical reference ranges:
 
 ```
 If metric_value is in reference_range [ref_min, ref_max]:
-  normalised_score = 1.0  (perfect)
+ normalised_score = 1.0 (perfect)
 
 Else if metric_value < ref_min:
-  normalised_score = (metric_value - abs_min) / (ref_min - abs_min)
-  (linear decay to 0 at absolute minimum)
+ normalised_score = (metric_value - abs_min) / (ref_min - abs_min)
+ (linear decay to 0 at absolute minimum)
 
 Else if metric_value > ref_max:
-  normalised_score = 1.0 - (metric_value - ref_max) / (abs_max - ref_max)
-  (linear decay to 0 at absolute maximum)
+ normalised_score = 1.0 - (metric_value - ref_max) / (abs_max - ref_max)
+ (linear decay to 0 at absolute maximum)
 ```
 
 **Organ Score** = weighted average of present metrics:
@@ -1174,9 +1178,9 @@ score = Σ(weight_i × normalised_i) / Σ(weight_present) × 100
 **Overall Score** = mean of all organ scores with data
 
 **Status Classification**:
-- ✅ **Healthy**: 75-100
-- ⚠️ **Watch**: 50-74
-- 🔴 **Risk**: 0-49
+- **Healthy**: 75-100
+- **Watch**: 50-74
+- **Risk**: 0-49
 
 #### Metric Name Alignment
 
@@ -1213,49 +1217,49 @@ This ensures consistent data flow from OCR extraction → database storage → p
 #### Files Modified/Created
 
 1. **`app/services/physics_config.py`**: Organ & metric specifications
-   - 6 organ definitions with metric weights
-   - Reference ranges & absolute bounds per metric
-   - `compute_organ_score()`: Deterministic scoring function
-   - `compute_all_organs()`: Multi-organ aggregation
+ - 6 organ definitions with metric weights
+ - Reference ranges & absolute bounds per metric
+ - `compute_organ_score()`: Deterministic scoring function
+ - `compute_all_organs()`: Multi-organ aggregation
 
 2. **`app/routes/physics.py`**: Smart API endpoints
-   - `GET /api/physics/latest`: Auto-compute from real DB data (90-day window)
-   - `GET /api/physics/history`: Per-report snapshots
-   - `POST /api/physics/metrics`: Manual submission (fallback)
-   - `GET /api/physics/config`: Frontend config download
+ - `GET /api/physics/latest`: Auto-compute from real DB data (90-day window)
+ - `GET /api/physics/history`: Per-report snapshots
+ - `POST /api/physics/metrics`: Manual submission (fallback)
+ - `GET /api/physics/config`: Frontend config download
 
 3. **`app/services/conditions.py`**: Rule engine
-   - 10 `ConditionRule` definitions
-   - `detect_conditions()`: Main evaluation function
-   - Threshold checking with severity mapping
-   - Organ affection mapping
+ - 10 `ConditionRule` definitions
+ - `detect_conditions()`: Main evaluation function
+ - Threshold checking with severity mapping
+ - Organ affection mapping
 
 4. **`app/routes/telemetry.py`**: Simulated SSE stream
-   - Baseline vital signs (heart_rate, bp, spo2, glucose, etc.)
-   - Per-user simulation state tracking
-   - Realistic jitter + periodic spikes
-   - `GET /stream` SSE endpoint
+ - Baseline vital signs (heart_rate, bp, spo2, glucose, etc.)
+ - Per-user simulation state tracking
+ - Realistic jitter + periodic spikes
+ - `GET /stream` SSE endpoint
 
 #### Data QueryQuery Pattern (physics.py)
 
 ```python
 # Gather last 90 days of metrics for user
 result = await db.execute(
-    select(Observation)
-    .where(
-        and_(
-            Observation.user_id == user_id,
-            Observation.observed_at >= cutoff  # 90 days ago
-        )
-    )
-    .order_by(desc(Observation.observed_at))
+ select(Observation)
+ .where(
+ and_(
+ Observation.user_id == user_id,
+ Observation.observed_at >= cutoff # 90 days ago
+ )
+ )
+ .order_by(desc(Observation.observed_at))
 )
 
 # Deduplicate: keep most recent value per metric_name
 metrics = {}
 for obs in sorted_observations:
-    if obs.metric_name not in seen:
-        metrics[obs.metric_name] = float(obs.value)
+ if obs.metric_name not in seen:
+ metrics[obs.metric_name] = float(obs.value)
 ```
 
 ### Frontend Implementation
@@ -1263,50 +1267,59 @@ for obs in sorted_observations:
 #### Main Components
 
 1. **`PhysicsTwin.tsx`** (616 lines): Page orchestrator
-   - Three tabs: Twin View (3D/overlay), Metrics (vitals grid), History (trends + snapshots)
-   - Auto-loads latest snapshot on mount
-   - Streams real-time telemetry via SSE hook
-   - Auto-detects conditions from current metrics
-   - Handles organ selection state
+ - Three tabs: Twin View (3D/overlay), Metrics (vitals grid), History (trends + snapshots)
+ - Auto-loads latest snapshot on mount
+ - Streams real-time telemetry via SSE hook
+ - Auto-detects conditions from current metrics
+ - Handles organ selection state
 
 2. **`TwinViewer.tsx`** (297 lines): 3D body renderer
-   - Uses `@react-three/fiber` + `@react-three/drei` + Three.js
-   - Stylized torso + head mesh
-   - 6 animated organ orbs with onClick handlers
-   - Auto-rotating when no organ selected
-   - Smooth camera tween to selected organ
-   - Responsive scaling & glow effects
+ - Uses `@react-three/fiber` + `@react-three/drei` + Three.js
+ - Stylized torso + head mesh
+ - 6 animated organ orbs with onClick handlers
+ - Auto-rotating when no organ selected
+ - Smooth camera tween to selected organ
+ - Responsive scaling & glow effects
 
 3. **`BodyImpactOverlay.tsx`** (263 lines): 2D condition visualization
-   - SVG body silhouette (male/female toggle)
-   - 6 organ zones with animated pulsing
-   - Severity-based color coding (mild/moderate/severe)
-   - Condition pill badges at top
-   - Gender-specific body paths
+ - SVG body silhouette (male/female toggle)
+ - 6 organ zones with animated pulsing
+ - Severity-based color coding (mild/moderate/severe)
+ - Condition pill badges at top
+ - Gender-specific body paths
 
 4. **`OrganTelemetryCard.tsx`** (159 lines): Score summary
-   - Large animated overall score display
-   - Selected organ detail (coverage %, status badge)
-   - Per-metric contribution breakdown with visual bars
-   - Last updated timestamp
+ - Large animated overall score display
+ - Selected organ detail (coverage %, status badge)
+ - Per-metric contribution breakdown with visual bars
+ - Last updated timestamp
 
 5. **`ExplainabilityCard.tsx`**: Scoring transparency
-   - Breakdown table: metric name, raw value, normalised score, weight
-   - Contribution % calculation
-   - Coverage metric (% of available metrics present)
-   - Confidence score (weighted average)
-
-6. **`RecommendationsCard.tsx`**: Condition actions
-   - Dynamic pill badges grouped by severity
-   - Evidence-based recommendations for each condition
-   - YouTube search links for educational content
-   - Expandable/collapsible sections
+ - Breakdown table: metric name, raw value, normalised score, weight
+ - Contribution % calculation
+ - Coverage metric (% of available metrics present)
+ - Confidence score (weighted average)
+
+6. **`YouTubeRecommendationsCard.tsx`**: AI-powered video recommendations
+ - Generates organ-specific health video suggestions via OpenRouter (GPT-4o-mini)
+ - Per-organ caching with `useRef<Map>` so recommendations load instantly on re-selection
+ - AbortController + request ID pattern prevents stale API responses
+ - Retry mechanism with cache-clearing for error recovery
+ - Styled with `dash-card` CSS to match the project design system
+ - Side-by-side layout with ExplainabilityCard in a 50/50 CSS grid row
+
+7. **`RecommendationsCard.tsx`**: Condition actions
+ - Dynamic pill badges grouped by severity
+ - Evidence-based recommendations for each condition
+ - YouTube search links for educational content
+ - Expandable/collapsible sections
 
 #### Supporting Files
 
 - **`physicsApi.ts`**: API client with types for snapshots, organs, conditions
 - **`conditionsEngine.ts`**: Client-side condition detection mirroring backend rules (instant feedback on metric changes)
 - **`useTelemetryStream.ts`**: SSE hook with automatic fallback to simulated vitals if SSE unavailable
+- **`openRouterService.ts`**: OpenRouter API client for generating video recommendations (GPT-4o-mini, with local fallback)
 
 ### API Endpoints
 
@@ -1327,69 +1340,69 @@ for obs in sorted_observations:
 Response:
 ```json
 {
-  "id": "550e8400-e29b-41d4-a716-446655440000_2025-02-06T10:30:00",
-  "user_id": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2025-02-06T10:30:00",
-  "overall_score": 72.3,
-  "overall_status": "Watch",
-  "data_source": "reports",
-  "raw_metrics": {
-    "systolic_bp": 145,
-    "diastolic_bp": 88,
-    "heart_rate": 78,
-    "glucose": 115,
-    "alt": 35,
-    "creatinine": 1.1,
-    "spo2": 97,
-    "hemoglobin": 14.2,
-    "stress_level": 5.2,
-    "sleep_hours": 6.5
-  },
-  "organs": {
-    "heart": {
-      "score": 68.5,
-      "status": "Watch",
-      "coverage": 0.83,
-      "contributions": [
-        {
-          "name": "systolic_bp",
-          "value": 145,
-          "normalised": 0.75,
-          "weight": 0.25,
-          "weighted": 0.1875,
-          "unit": "mmHg"
-        }
-      ]
-    },
-    "kidney": {
-      "score": 82.1,
-      "status": "Healthy",
-      "coverage": 1.0,
-      "contributions": []
-    }
-  },
-  "conditions": [
-    {
-      "id": "hypertension",
-      "name": "Hypertension",
-      "severity": "moderate",
-      "affected_organs": ["heart", "kidney", "brain"],
-      "trigger_metrics": { "systolic_bp": 145 },
-      "recommendations": [
-        "Reduce sodium intake to under 2,300 mg/day",
-        "Engage in 30 minutes of moderate exercise daily"
-      ],
-      "youtube_queries": ["how to lower blood pressure naturally"]
-    }
-  ],
-  "organ_conditions": {
-    "heart": ["hypertension"],
-    "kidney": ["hypertension"]
-  },
-  "organ_severities": {
-    "heart": "moderate",
-    "kidney": "mild"
-  }
+ "id": "550e8400-e29b-41d4-a716-446655440000_2025-02-06T10:30:00",
+ "user_id": "550e8400-e29b-41d4-a716-446655440000",
+ "timestamp": "2025-02-06T10:30:00",
+ "overall_score": 72.3,
+ "overall_status": "Watch",
+ "data_source": "reports",
+ "raw_metrics": {
+ "systolic_bp": 145,
+ "diastolic_bp": 88,
+ "heart_rate": 78,
+ "glucose": 115,
+ "alt": 35,
+ "creatinine": 1.1,
+ "spo2": 97,
+ "hemoglobin": 14.2,
+ "stress_level": 5.2,
+ "sleep_hours": 6.5
+ },
+ "organs": {
+ "heart": {
+ "score": 68.5,
+ "status": "Watch",
+ "coverage": 0.83,
+ "contributions": [
+ {
+ "name": "systolic_bp",
+ "value": 145,
+ "normalised": 0.75,
+ "weight": 0.25,
+ "weighted": 0.1875,
+ "unit": "mmHg"
+ }
+ ]
+ },
+ "kidney": {
+ "score": 82.1,
+ "status": "Healthy",
+ "coverage": 1.0,
+ "contributions": []
+ }
+ },
+ "conditions": [
+ {
+ "id": "hypertension",
+ "name": "Hypertension",
+ "severity": "moderate",
+ "affected_organs": ["heart", "kidney", "brain"],
+ "trigger_metrics": { "systolic_bp": 145 },
+ "recommendations": [
+ "Reduce sodium intake to under 2,300 mg/day",
+ "Engage in 30 minutes of moderate exercise daily"
+ ],
+ "youtube_queries": ["how to lower blood pressure naturally"]
+ }
+ ],
+ "organ_conditions": {
+ "heart": ["hypertension"],
+ "kidney": ["hypertension"]
+ },
+ "organ_severities": {
+ "heart": "moderate",
+ "kidney": "mild"
+ }
 }
 ```
 
@@ -1405,75 +1418,84 @@ data: {"timestamp":"2025-02-06T10:30:02Z","metrics":{"heart_rate":76,"systolic_b
 ### User Experience Flow
 
 1. **Page Load**: 
-   - Auto-fetches `/api/physics/latest` → loads real data from user's reports
-   - If user has reports: snapshot shows immediately with organ scores visible
-   - If no reports: Shows "No health data found" overlay with option to load demo data
+ - Auto-fetches `/api/physics/latest` → loads real data from user's reports
+ - If user has reports: snapshot shows immediately with organ scores visible
+ - If no reports: Shows "No health data found" overlay with option to load demo data
 
 2. **3D Viewer Interaction**:
-   - Click any organ → auto-selects, triggers camera tween to that organ
-   - OrganTelemetryCard shows score breakdown (e.g., "Heart: 68.5% — Watch")
-   - ExplainabilityCard shows metric contributions to selected organ score
-   - Each metric bar shows current value vs reference range
+ - Click any organ → auto-selects, triggers camera tween to that organ
+ - OrganTelemetryCard shows score breakdown (e.g., "Heart: 68.5% — Watch")
+ - ExplainabilityCard shows metric contributions to selected organ score
+ - Each metric bar shows current value vs reference range
 
 3. **Body Overlay Mode**:
-   - Click "Impact View" toggle → SVG body appears
-   - Detected conditions pulse with color coding (mild=yellow, moderate=orange, severe=red)
-   - Each organ zone highlights if affected by a condition
-   - Hover shows condition name
+ - Click "Impact View" toggle → SVG body appears
+ - Detected conditions pulse with color coding (mild=yellow, moderate=orange, severe=red)
+ - Each organ zone highlights if affected by a condition
+ - Hover shows condition name
 
 4. **Real-Time Metrics Tab**:
-   - Vital signs grid shows latest values (from telemetry SSE stream)
-   - Trend arrows (↑ up, ↓ down, → stable) based on 10-reading window
-   - "Score Metrics" button submits current readings for manual analysis
+ - Vital signs grid shows latest values (from telemetry SSE stream)
+ - Trend arrows (↑ up, ↓ down, → stable) based on 10-reading window
+ - "Score Metrics" button submits current readings for manual analysis
 
 5. **History Tab**:
-   - Line chart of selected metric over last 60 telemetry readings
-   - Scored snapshots section lists per-report scores with timestamps
-   - Click any snapshot to replay its organ breakdown
+ - Line chart of selected metric over last 60 telemetry readings
+ - Scored snapshots section lists per-report scores with timestamps
+ - Click any snapshot to replay its organ breakdown
 
 6. **Recommendations**:
-   - Dynamically updates as conditions detected/cleared
-   - Each condition shows severity, affected organs, evidence-based actions
-   - YouTube links for patient education (e.g., "DASH diet for hypertension")
+ - Dynamically updates as conditions detected/cleared
+ - Each condition shows severity, affected organs, evidence-based actions
+ - YouTube links for patient education (e.g., "DASH diet for hypertension")
 
 ### Key Features Breakdown
 
 #### Real Data, Not Simulation
 
-- ✅ `/api/physics/latest` queries actual `Observation` table
-- ✅ Uses real extracted metrics from uploaded medical reports
-- ✅ Falls back gracefully if user has zero observations (shows empty state)
-- ✅ Enriches with self-reported profile data (sleep, stress)
+- `/api/physics/latest` queries actual `Observation` table
+- Uses real extracted metrics from uploaded medical reports
+- Falls back gracefully if user has zero observations (shows empty state)
+- Enriches with self-reported profile data (sleep, stress)
 
 #### Deterministic Scoring
 
-- ✅ Reference ranges stored in `physics_config.py`
-- ✅ All calculations deterministic (no AI/ML, pure math)
-- ✅ Explainable: every score component shown in breakdown
-- ✅ Aligned with clinical normalisation standards
+- Reference ranges stored in `physics_config.py`
+- All calculations deterministic (no AI/ML, pure math)
+- Explainable: every score component shown in breakdown
+- Aligned with clinical normalisation standards
 
 #### 3D Interactive Body
 
-- ✅ 6 clickable organ hotspots
-- ✅ Smooth camera animation on selection
-- ✅ Real-time score badges on each organ
-- ✅ Auto-rotating when idle
-- ✅ Works on mobile and desktop
+- 6 clickable organ hotspots
+- Smooth camera animation on selection
+- Real-time score badges on each organ
+- Auto-rotating when idle
+- Works on mobile and desktop
 
 #### Condition Detection
 
-- ✅ 10 rule-based conditions automatically detected
-- ✅ Severity mapping (mild ≤ moderate ≤ severe)
-- ✅ Organ affection mapping (which organs are affected?)
-- ✅ Real-time evaluation as metrics change
-- ✅ Client-side + server-side dual detection for instant feedback
+- 10 rule-based conditions automatically detected
+- Severity mapping (mild ≤ moderate ≤ severe)
+- Organ affection mapping (which organs are affected?)
+- Real-time evaluation as metrics change
+- Client-side + server-side dual detection for instant feedback
 
 #### Educational Context
 
-- ✅ Recommendations tailored per condition
-- ✅ YouTube search links for each condition
-- ✅ Evidence citations (reference ranges explained)
-- ✅ Safety disclaimers on all pages
+- Recommendations tailored per condition
+- YouTube search links for each condition
+- Evidence citations (reference ranges explained)
+- Safety disclaimers on all pages
+
+#### AI Video Recommendations (OpenRouter)
+
+- Personalized health video suggestions generated via OpenRouter (GPT-4o-mini) for each organ
+- Video recommendations based on organ-specific abnormal metrics, not generic searches
+- Per-organ caching with `useRef<Map>` for instant retrieval on organ re-selection
+- AbortController + request ID guards prevent stale responses from overwriting current data
+- Fallback recommendations generated locally if API is unavailable
+- Displayed in a side-by-side "Improve Your Health" card alongside the "Why This Score?" explainability panel
 
 ### Performance & Optimization
 
@@ -1676,31 +1698,31 @@ alembic current
 
 ```mermaid
 erDiagram
-    users ||--o{ reports : uploads
-    users ||--o{ observations : has
-    users ||--o{ health_metrics : has
-    users ||--o| user_profiles : has
-    users ||--o{ profile_conditions : has
-    users ||--o{ profile_medications : takes
-    users ||--o{ profile_allergies : has
-    users ||--o{ chat_sessions : owns
-    users ||--o{ report_ai_summaries : generates
-    users ||--o{ report_ai_comparisons : generates
-    users ||--o{ user_saved_medicines : saves
-    users ||--o{ substitute_queries : searches
-    users ||--o{ pharmacy_clicks : clicks
-    users ||--o| user_location_consent : grants
-    
-    user_profiles ||--o{ reminders : has
-    reminders ||--o{ reminder_events : logs
-    
-    reports ||--o{ observations : extracts
-    reports ||--o{ report_ai_summaries : summarized_by
-    
-    chat_sessions ||--o{ chat_messages : contains
-    
-    user_saved_medicines ||--o{ generic_catalog : references
-    substitute_queries ||--o{ generic_catalog : queries
+ users ||--o{ reports : uploads
+ users ||--o{ observations : has
+ users ||--o{ health_metrics : has
+ users ||--o| user_profiles : has
+ users ||--o{ profile_conditions : has
+ users ||--o{ profile_medications : takes
+ users ||--o{ profile_allergies : has
+ users ||--o{ chat_sessions : owns
+ users ||--o{ report_ai_summaries : generates
+ users ||--o{ report_ai_comparisons : generates
+ users ||--o{ user_saved_medicines : saves
+ users ||--o{ substitute_queries : searches
+ users ||--o{ pharmacy_clicks : clicks
+ users ||--o| user_location_consent : grants
+ 
+ user_profiles ||--o{ reminders : has
+ reminders ||--o{ reminder_events : logs
+ 
+ reports ||--o{ observations : extracts
+ reports ||--o{ report_ai_summaries : summarized_by
+ 
+ chat_sessions ||--o{ chat_messages : contains
+ 
+ user_saved_medicines ||--o{ generic_catalog : references
+ substitute_queries ||--o{ generic_catalog : queries
 ```
 
 ### Medicines Database Schema
@@ -1866,21 +1888,21 @@ erDiagram
 Request:
 ```json
 {
-  "email": "user@example.com",
-  "password": "securepassword"
+ "email": "user@example.com",
+ "password": "securepassword"
 }
 ```
 
 Response:
 ```json
 {
-  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "email": "user@example.com",
-    "full_name": "John Doe",
-    "created_at": "2026-01-15T10:30:00Z"
-  }
+ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+ "user": {
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "email": "user@example.com",
+ "full_name": "John Doe",
+ "created_at": "2026-01-15T10:30:00Z"
+ }
 }
 ```
 
@@ -1889,30 +1911,30 @@ Response:
 Request:
 ```json
 {
-  "report_id": "550e8400-e29b-41d4-a716-446655440001",
-  "force_regenerate": false
+ "report_id": "550e8400-e29b-41d4-a716-446655440001",
+ "force_regenerate": false
 }
 ```
 
 Response:
 ```json
 {
-  "summary_json": {
-    "title": "Blood Panel Analysis - January 2026",
-    "highlights": {
-      "positive": ["Hemoglobin within normal range", "Glucose levels stable"],
-      "needs_attention": ["LDL cholesterol slightly elevated"],
-      "next_steps": ["Consider dietary changes", "Retest in 3 months"]
-    },
-    "plain_language_summary": "Your blood panel shows mostly healthy values...",
-    "key_findings": [
-      {"item": "LDL Cholesterol", "evidence": "142 mg/dL (ref: <100)"}
-    ],
-    "confidence": 0.85
-  },
-  "cached": false,
-  "generated_at": "2026-02-02T10:30:00Z",
-  "model_name": "grok-beta"
+ "summary_json": {
+ "title": "Blood Panel Analysis - January 2026",
+ "highlights": {
+ "positive": ["Hemoglobin within normal range", "Glucose levels stable"],
+ "needs_attention": ["LDL cholesterol slightly elevated"],
+ "next_steps": ["Consider dietary changes", "Retest in 3 months"]
+ },
+ "plain_language_summary": "Your blood panel shows mostly healthy values...",
+ "key_findings": [
+ {"item": "LDL Cholesterol", "evidence": "142 mg/dL (ref: <100)"}
+ ],
+ "confidence": 0.85
+ },
+ "cached": false,
+ "generated_at": "2026-02-02T10:30:00Z",
+ "model_name": "grok-beta"
 }
 ```
 
@@ -1978,24 +2000,27 @@ pytest tests/test_routes_auth.py
 
 ### Manual QA Checklist
 
-1. ☐ Register a new account
-2. ☐ Login and verify dashboard loads
-3. ☐ Upload a PDF lab report
-4. ☐ Verify OCR extraction completes (WebSocket notification)
-5. ☐ Check extracted metrics appear in reports list
-6. ☐ Verify health index updates on dashboard
-7. ☐ Complete health profile wizard
-8. ☐ Check recommendations generate
-9. ☐ Open AI Summary page, select a report
-10. ☐ Generate AI summary, verify it displays
-11. ☐ Select 2 reports of same type, generate comparison
-12. ☐ Try selecting mixed types, verify warning appears
-13. ☐ Test Medicines feature: search for a medicine (e.g., "Aspirin 500mg")
-14. ☐ Verify substitutes appear with prices and Jan Aushadhi options highlighted
-15. ☐ Test pharmacy search by entering your location
-16. ☐ Verify nearby pharmacies appear with ratings and distance
-17. ☐ Try filtering pharmacies by type (all/jan_aushadhi/generic)
-18. ☐ Save a medicine and verify it appears in saved list
+1. Register a new account
+2. Login and verify dashboard loads
+3. Upload a PDF lab report
+4. Verify OCR extraction completes (WebSocket notification)
+5. Check extracted metrics appear in reports list
+6. Verify health index updates on dashboard
+7. Complete health profile wizard
+8. Check recommendations generate
+9. Open AI Summary page, select a report
+10. Generate AI summary, verify it displays
+11. Select 2 reports of same type, generate comparison
+12. Try selecting mixed types, verify warning appears
+13. Test Medicines feature: search for a medicine (e.g., "Aspirin 500mg")
+14. Verify substitutes appear with prices and Jan Aushadhi options highlighted
+15. Test pharmacy search by entering your location
+16. Verify nearby pharmacies appear with ratings and distance
+17. Try filtering pharmacies by type (all/jan_aushadhi/generic)
+18. Save a medicine and verify it appears in saved list
+19. Open Physics Twin page, verify organ scores load from reports
+20. Click an organ, verify "Why This Score?" breakdown and "Improve Your Health" video recommendations appear side-by-side
+21. Switch organs, verify video recommendations update and cache correctly
 
 ### Medicines Feature Testing
 
@@ -2018,45 +2043,45 @@ pytest tests/test_routes_medicines.py
 ### Medicines Manual Testing
 
 1. **Test Medicine Normalization**
-   ```bash
-   curl -X POST http://localhost:8000/api/medicines/normalize \
-     -H "Authorization: Bearer <token>" \
-     -H "Content-Type: application/json" \
-     -d '{"text": "Aspirin 500mg tablet"}'
-   ```
-   Expected: `NormalizedMedicine` with extracted salt, strength, form
+ ```bash
+ curl -X POST http://localhost:8000/api/medicines/normalize \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "Aspirin 500mg tablet"}'
+ ```
+ Expected: `NormalizedMedicine` with extracted salt, strength, form
 
 2. **Test Substitute Search (AI-Powered)**
-   ```bash
-   curl -X POST http://localhost:8000/api/medicines/substitutes/from-text \
-     -H "Authorization: Bearer <token>" \
-     -H "Content-Type: application/json" \
-     -d '{"text": "Crocin 650mg for fever"}'
-   ```
-   Expected: Ranked list of alternatives with prices
+ ```bash
+ curl -X POST http://localhost:8000/api/medicines/substitutes/from-text \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "Crocin 650mg for fever"}'
+ ```
+ Expected: Ranked list of alternatives with prices
 
 3. **Test Pharmacy Search**
-   ```bash
-   curl -X GET "http://localhost:8000/api/medicines/pharmacies/nearby?lat=40.7128&lng=-74.0060&radius_m=1000&type=all" \
-     -H "Authorization: Bearer <token>"
-   ```
-   Expected: List of nearby pharmacies with ratings
+ ```bash
+ curl -X GET "http://localhost:8000/api/medicines/pharmacies/nearby?lat=40.7128&lng=-74.0060&radius_m=1000&type=all" \
+ -H "Authorization: Bearer <token>"
+ ```
+ Expected: List of nearby pharmacies with ratings
 
 4. **Test Save Medicine**
-   ```bash
-   curl -X POST http://localhost:8000/api/medicines/saved \
-     -H "Authorization: Bearer <token>" \
-     -H "Content-Type: application/json" \
-     -d '{
-       "brand_name": "Aspirin",
-       "salt": "Acetylsalicylic Acid",
-       "strength": "500",
-       "form": "tablet",
-       "release_type": "immediate",
-       "notes": "Take with food"
-     }'
-   ```
-   Expected: `UserSavedMedicine` object saved to database
+ ```bash
+ curl -X POST http://localhost:8000/api/medicines/saved \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "brand_name": "Aspirin",
+ "salt": "Acetylsalicylic Acid",
+ "strength": "500",
+ "form": "tablet",
+ "release_type": "immediate",
+ "notes": "Take with food"
+ }'
+ ```
+ Expected: `UserSavedMedicine` object saved to database
 
 ### Medicines Troubleshooting
 
@@ -2064,58 +2089,58 @@ pytest tests/test_routes_medicines.py
 
 - **Cause**: Medicine not in `generic_catalog` table
 - **Solution**: 
-  - Verify PMBI/Jan Aushadhi seed data was loaded during migration
-  - Check database: `SELECT COUNT(*) FROM generic_catalog;` should show 600K+ records
-  - Try searching by generic name instead of brand name (e.g., "Acetylsalicylic Acid" instead of "Aspirin")
-  - Check logs for Grok API errors if using free-text search
+ - Verify PMBI/Jan Aushadhi seed data was loaded during migration
+ - Check database: `SELECT COUNT(*) FROM generic_catalog;` should show 600K+ records
+ - Try searching by generic name instead of brand name (e.g., "Acetylsalicylic Acid" instead of "Aspirin")
+ - Check logs for Grok API errors if using free-text search
 
 **Problem: "Google Places API 401" or pharmacy search returns empty**
 
 - **Cause**: `GOOGLE_PLACES_API_KEY` not set or API quota exceeded
 - **Solution**:
-  - Verify `GOOGLE_PLACES_API_KEY` is set in `.env`: `echo $GOOGLE_PLACES_API_KEY`
-  - Check Google Cloud Console for API key validity and quota limits
-  - If quota exceeded, wait 24 hours or upgrade billing
-  - During development, feature falls back to mock pharmacy data when API key is missing
-  - Mock data is useful for frontend testing without API costs
+ - Verify `GOOGLE_PLACES_API_KEY` is set in `.env`: `echo $GOOGLE_PLACES_API_KEY`
+ - Check Google Cloud Console for API key validity and quota limits
+ - If quota exceeded, wait 24 hours or upgrade billing
+ - During development, feature falls back to mock pharmacy data when API key is missing
+ - Mock data is useful for frontend testing without API costs
 
 **Problem: Slow medicine normalization or substitute search**
 
 - **Cause**: Missing database indexes on high-cardinality columns
 - **Solution**:
-  - Verify indexes exist on `generic_catalog`: `SELECT indexname FROM pg_indexes WHERE tablename='generic_catalog';`
-  - Should see indexes on: `product_name`, `salt`, `user_id`
-  - If missing, run: `alembic upgrade head` to apply latest migrations
-  - Check database query performance: Enable `EXPLAIN ANALYZE` in PostgreSQL
-  - Profile with: `SELECT pg_size_pretty(pg_total_relation_size('generic_catalog'));`
+ - Verify indexes exist on `generic_catalog`: `SELECT indexname FROM pg_indexes WHERE tablename='generic_catalog';`
+ - Should see indexes on: `product_name`, `salt`, `user_id`
+ - If missing, run: `alembic upgrade head` to apply latest migrations
+ - Check database query performance: Enable `EXPLAIN ANALYZE` in PostgreSQL
+ - Profile with: `SELECT pg_size_pretty(pg_total_relation_size('generic_catalog'));`
 
 **Problem: Grok API errors when parsing prescription images**
 
 - **Cause**: Invalid image format, API key expired, or API rate limit
 - **Solution**:
-  - Verify image is clear and readable (JPG, PNG, TIFF)
-  - Test API key directly: `curl -H "Authorization: Bearer $GROK_API_KEY" https://api.x.ai/v1/models`
-  - Check Grok API status at https://status.x.ai
-  - Review backend logs: `docker logs <backend-container>` or `tail uvicorn.log`
-  - If rate-limited, implement request throttling in `medicine_normalizer.py`
+ - Verify image is clear and readable (JPG, PNG, TIFF)
+ - Test API key directly: `curl -H "Authorization: Bearer $GROK_API_KEY" https://api.x.ai/v1/models`
+ - Check Grok API status at https://status.x.ai
+ - Review backend logs: `docker logs <backend-container>` or `tail uvicorn.log`
+ - If rate-limited, implement request throttling in `medicine_normalizer.py`
 
 **Problem: Pharmacy search cache not updating**
 
 - **Cause**: In-memory cache TTL (1 hour) not expired
 - **Solution**:
-  - Manually clear cache by restarting backend service
-  - Cache is per-search key (lat/lng/radius): different locations create new cache entries
-  - Check cache size in logs: Search for "pharmacy_cache" debug messages
-  - To disable caching for testing, set `PharmacyLocator.CACHE_TTL_SECONDS = 0`
+ - Manually clear cache by restarting backend service
+ - Cache is per-search key (lat/lng/radius): different locations create new cache entries
+ - Check cache size in logs: Search for "pharmacy_cache" debug messages
+ - To disable caching for testing, set `PharmacyLocator.CACHE_TTL_SECONDS = 0`
 
 **Problem: User saved medicines not persisting**
 
 - **Cause**: Database migration not applied or user_id foreign key constraint
 - **Solution**:
-  - Verify `user_saved_medicines` table exists: `\dt user_saved_medicines` in psql
-  - Run migrations: `cd backend && alembic upgrade head`
-  - Verify user exists and authenticated: Check JWT token contains valid `sub` (user_id)
-  - Check database logs for constraint errors: `docker logs <postgres-container>`
+ - Verify `user_saved_medicines` table exists: `\dt user_saved_medicines` in psql
+ - Run migrations: `cd backend && alembic upgrade head`
+ - Verify user exists and authenticated: Check JWT token contains valid `sub` (user_id)
+ - Check database logs for constraint errors: `docker logs <postgres-container>`
 ---
 
 ## Deployment

backend/app/routes/physics.py

@@ -36,6 +36,13 @@ from app.services.conditions import (
     get_organ_conditions,
     get_organ_worst_severity,
 )
+from app.services.youtube_recommendation_service import YouTubeRecommendationService
+from app.settings import Settings
+from functools import lru_cache
+
+@lru_cache()
+def get_settings():
+    return Settings()
 
 logger = logging.getLogger(__name__)
 
@@ -315,3 +322,52 @@ async def get_config(user=Depends(get_current_user)):
             ],
         }
     return {"organs": organs}
+
+
+class YouTubeRecommendationRequest(BaseModel):
+    """Request body for YouTube recommendations"""
+    organ: str = Field(..., description="Organ name (kidney, heart, liver, etc.)")
+    score: float = Field(..., description="Organ health score 0-100")
+    status: str = Field(..., description="Health status (Healthy, Watch, Risk)")
+    metrics: Dict[str, float] = Field(default_factory=dict, description="Current metric values")
+    conditions: List[dict] = Field(default_factory=list, description="Detected conditions")
+
+
+class YouTubeRecommendationResponse(BaseModel):
+    """Response with YouTube video recommendations"""
+    organ: str
+    recommendations: List[Dict[str, str]]
+
+
+@router.post("/youtube-recommendations", response_model=YouTubeRecommendationResponse)
+async def get_youtube_recommendations(
+    body: YouTubeRecommendationRequest,
+    user=Depends(get_current_user),
+):
+    """
+    Generate YouTube video recommendations based on organ telemetry.
+    Uses OpenRouter AI to generate targeted search queries and returns
+    actual YouTube videos (if API key is available) or search links.
+    """
+    try:
+        settings = get_settings()
+        service = YouTubeRecommendationService(settings)
+        
+        recommendations = await service.generate_recommendations(
+            organ=body.organ,
+            score=body.score,
+            status=body.status,
+            metrics=body.metrics,
+            conditions=body.conditions,
+        )
+        
+        return {
+            "organ": body.organ,
+            "recommendations": recommendations,
+        }
+    except Exception as e:
+        logger.exception(f"Error generating YouTube recommendations: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to generate recommendations: {str(e)}"
+        )

backend/app/services/youtube_recommendation_service.py

@@ -0,0 +1,296 @@
+"""
+YouTube Recommendation Service
+
+Uses OpenRouter API to generate contextual YouTube video recommendations
+based on organ telemetry data and detected health conditions.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Dict, List, Optional
+import httpx
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from app.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class YouTubeRecommendationService:
+    """Generate accurate YouTube video recommendations for health improvement"""
+    
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.openrouter_api_key = settings.OPENROUTER_API_KEY or os.getenv("OPENROUTER_API_KEY")
+        self.youtube_api_key = settings.google_places_api_key or os.getenv("YOUTUBE_API_KEY")
+        
+        if not self.openrouter_api_key:
+            logger.warning("OPENROUTER_API_KEY not configured - YouTube recommendations will use fallback")
+        
+        self.openrouter_base_url = "https://openrouter.ai/api/v1/chat/completions"
+        self.timeout = 30
+
+    async def generate_recommendations(
+        self,
+        organ: str,
+        score: float,
+        status: str,
+        metrics: Dict[str, float],
+        conditions: List[Dict],
+    ) -> List[Dict[str, str]]:
+        """
+        Generate YouTube video recommendations based on organ health data.
+        
+        Args:
+            organ: Organ name (e.g., "kidney", "heart", "liver")
+            score: Organ health score (0-100)
+            status: Health status ("Healthy", "Watch", "Risk")
+            metrics: Current metric values affecting this organ
+            conditions: List of detected conditions affecting this organ
+            
+        Returns:
+            List of video recommendations with title, videoId, thumbnail, and description
+        """
+        try:
+            # Generate search queries using OpenRouter
+            queries = await self._generate_search_queries(organ, score, status, metrics, conditions)
+            
+            # Fetch actual YouTube videos for each query
+            recommendations = []
+            for query in queries[:3]:  # Limit to top 3 queries to save API calls
+                videos = await self._search_youtube(query)
+                if videos:
+                    recommendations.extend(videos[:2])  # Top 2 videos per query
+            
+            # Deduplicate by video ID and limit to 5 total
+            seen_ids = set()
+            unique_recommendations = []
+            for video in recommendations:
+                if video["videoId"] not in seen_ids:
+                    seen_ids.add(video["videoId"])
+                    unique_recommendations.append(video)
+                if len(unique_recommendations) >= 5:
+                    break
+            
+            return unique_recommendations
+        
+        except Exception as e:
+            logger.exception(f"Error generating YouTube recommendations: {e}")
+            return self._get_fallback_recommendations(organ, conditions)
+
+    async def _generate_search_queries(
+        self,
+        organ: str,
+        score: float,
+        status: str,
+        metrics: Dict[str, float],
+        conditions: List[Dict],
+    ) -> List[str]:
+        """Use OpenRouter AI to generate targeted YouTube search queries"""
+        
+        if not self.openrouter_api_key:
+            return self._get_fallback_queries(organ, conditions)
+        
+        # Build context for AI
+        condition_text = ""
+        if conditions:
+            condition_names = [c.get("name", "") for c in conditions]
+            condition_text = f"Detected conditions: {', '.join(condition_names)}. "
+        
+        metric_text = ""
+        if metrics:
+            metric_items = [f"{k.replace('_', ' ')}: {v:.1f}" for k, v in metrics.items()]
+            metric_text = f"Key metrics: {', '.join(metric_items)}. "
+        
+        prompt = f"""You are a medical health educator. Generate 5 specific, actionable YouTube search queries for someone with:
+
+Organ: {organ.upper()}
+Health Score: {score:.1f}/100 ({status})
+{condition_text}{metric_text}
+
+Requirements:
+1. Each query should target EVIDENCE-BASED educational content
+2. Focus on practical improvement strategies, diet, exercise, lifestyle
+3. Include specific terms like "doctor explains", "Mayo Clinic", "medical review"
+4. Avoid clickbait - prioritize credible medical sources
+5. Mix general organ health with specific condition management
+
+Return ONLY the 5 search queries, one per line, no numbering or extra text."""
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    self.openrouter_base_url,
+                    headers={
+                        "Authorization": f"Bearer {self.openrouter_api_key}",
+                        "HTTP-Referer": "https://lumea-health.com",
+                        "X-Title": "Lumea Health YouTube Recommendations",
+                    },
+                    json={
+                        "model": "openai/gpt-4o-mini",  # Fast and accurate
+                        "messages": [{"role": "user", "content": prompt}],
+                        "temperature": 0.7,
+                        "max_tokens": 300,
+                    }
+                )
+                
+                if response.status_code == 200:
+                    data = response.json()
+                    content = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+                    queries = [q.strip() for q in content.strip().split("\n") if q.strip()]
+                    logger.info(f"Generated {len(queries)} queries for {organ}: {queries}")
+                    return queries[:5]
+                else:
+                    logger.warning(f"OpenRouter returned status {response.status_code}")
+                    return self._get_fallback_queries(organ, conditions)
+        
+        except Exception as e:
+            logger.warning(f"Error calling OpenRouter: {e}")
+            return self._get_fallback_queries(organ, conditions)
+
+    async def _search_youtube(self, query: str) -> List[Dict[str, str]]:
+        """Search YouTube Data API v3 for videos matching the query"""
+        
+        # Return search URL fallback if no API key - with generic placeholder
+        if not self.youtube_api_key:
+            logger.info(f"No YouTube API key - returning search link for: {query}")
+            # Generate a more deterministic video ID for better caching
+            video_id = f"srch{abs(hash(query)) % 1000000}"
+            return [{
+                "title": query,
+                "videoId": video_id,
+                "thumbnail": f"https://via.placeholder.com/320x180/6b9175/ffffff?text={query[:30].replace(' ', '+')}",
+                "description": "Click to search YouTube for medical videos on this topic",
+                "url": f"https://www.youtube.com/results?search_query={query.replace(' ', '+')}",
+                "channelTitle": "YouTube Search"
+            }]
+        
+        try:
+            youtube = build("youtube", "v3", developerKey=self.youtube_api_key)
+            
+            search_response = youtube.search().list(
+                q=query,
+                part="id,snippet",
+                maxResults=3,
+                type="video",
+                order="relevance",
+                videoDuration="medium",  # 4-20 minutes
+                videoDefinition="high",
+                relevanceLanguage="en",
+            ).execute()
+            
+            videos = []
+            for item in search_response.get("items", []):
+                video_id = item["id"]["videoId"]
+                snippet = item["snippet"]
+                
+                videos.append({
+                    "title": snippet["title"],
+                    "videoId": video_id,
+                    "thumbnail": snippet["thumbnails"].get("medium", {}).get("url", ""),
+                    "description": snippet["description"][:150] + "..." if len(snippet["description"]) > 150 else snippet["description"],
+                    "url": f"https://www.youtube.com/watch?v={video_id}",
+                    "channelTitle": snippet["channelTitle"]
+                })
+            
+            return videos
+        
+        except HttpError as e:
+            logger.warning(f"YouTube API error for query '{query}': {e}")
+            # Return search URL fallback with generic placeholder
+            video_id = f"srch{abs(hash(query)) % 1000000}"
+            return [{
+                "title": query,
+                "videoId": video_id,
+                "thumbnail": f"https://via.placeholder.com/320x180/6b9175/ffffff?text={query[:30].replace(' ', '+')}",
+                "description": "Click to search YouTube for medical videos on this topic",
+                "url": f"https://www.youtube.com/results?search_query={query.replace(' ', '+')}",
+                "channelTitle": "YouTube Search"
+            }]
+        
+        except Exception as e:
+            logger.exception(f"Error searching YouTube: {e}")
+            return []
+
+    def _get_fallback_queries(self, organ: str, conditions: List[Dict]) -> List[str]:
+        """Fallback queries when AI is unavailable"""
+        
+        base_queries = {
+            "kidney": [
+                "how to improve kidney function naturally doctor explains",
+                "kidney disease prevention Mayo Clinic",
+                "best foods for kidney health medical review",
+                "kidney health exercises and lifestyle changes",
+                "understanding kidney function tests explained",
+            ],
+            "heart": [
+                "heart health improvement doctor guide",
+                "cardiovascular disease prevention explained",
+                "best diet for heart health evidence based",
+                "heart disease risk factors medical review",
+                "improving heart health naturally Cleveland Clinic",
+            ],
+            "liver": [
+                "liver health improvement natural methods",
+                "fatty liver disease treatment explained",
+                "liver detox what actually works doctor",
+                "liver function tests explained medical",
+                "best diet for liver health evidence based",
+            ],
+            "lungs": [
+                "lung health improvement breathing exercises",
+                "respiratory health doctor explains",
+                "lung function improvement natural methods",
+                "breathing techniques for better lung health",
+                "pulmonary health prevention medical review",
+            ],
+            "brain": [
+                "brain health improvement neuroplasticity",
+                "cognitive function optimization doctor",
+                "neurological health prevention methods",
+                "brain health diet and lifestyle medical",
+                "memory improvement techniques evidence based",
+            ],
+            "blood": [
+                "blood health optimization complete guide",
+                "anemia treatment natural methods doctor",
+                "improving blood test results naturally",
+                "hematology basics medical explanation",
+                "blood health diet and supplements",
+            ],
+        }
+        
+        # Get base queries for organ
+        queries = base_queries.get(organ.lower(), [
+            f"{organ} health improvement doctor explains",
+            f"how to improve {organ} function naturally",
+            f"{organ} disease prevention medical review",
+            f"best diet for {organ} health evidence based",
+            f"{organ} health lifestyle changes doctor guide",
+        ])
+        
+        # Add condition-specific queries
+        if conditions:
+            for condition in conditions[:2]:  # Top 2 conditions
+                condition_name = condition.get("name", "")
+                if condition_name:
+                    queries.append(f"{condition_name} treatment explained doctor")
+        
+        return queries[:5]
+
+    def _get_fallback_recommendations(self, organ: str, conditions: List[Dict]) -> List[Dict[str, str]]:
+        """Static fallback when all APIs fail"""
+        
+        queries = self._get_fallback_queries(organ, conditions)
+        
+        return [{
+            "title": query,
+            "videoId": f"fallback_{i}_{abs(hash(query)) % 1000}",
+            "thumbnail": f"https://via.placeholder.com/320x180/6b9175/ffffff?text={query[:30].replace(' ', '+')}",
+            "description": "Click to search YouTube for medical videos on this topic",
+            "url": f"https://www.youtube.com/results?search_query={query.replace(' ', '+')}",
+            "channelTitle": "YouTube Search"
+        } for i, query in enumerate(queries)]

backend/requirements.txt

@@ -40,6 +40,9 @@ ollama>=0.1.0
 google-generativeai>=0.4.0
 openai>=1.0.0  # Used as OpenRouter SDK (OpenAI-compatible API)
 
+# YouTube API for recommendations
+google-api-python-client>=2.100.0
+
 # Local MedGemma via Hugging Face
 # Keep transformers on the 4.x line; 5.x requires newer torch and breaks
 # sentence-transformers import paths used by Mem0 huggingface embeddings.

frontend/.env.example

@@ -0,0 +1,6 @@
+# OpenRouter API Key
+# Used for generating intelligent YouTube video recommendations
+# Get your key from: https://openrouter.ai/keys
+VITE_OPENROUTER_API_KEY=sk-or-v1-your_key_here
+
+# Note: No YouTube Data API key needed - we use YouTube search URLs directly

frontend/src/components/HealthGraph.css

@@ -268,19 +268,20 @@
     transform-origin: center center;
 }
 
-/* SVG Styles */
+/* SVG Styles - Larger, More Readable Nodes */
 .relationship-line {
-    stroke: var(--dash-border, #e5dfd5);
-    stroke-width: 2;
+    stroke: rgba(107, 145, 117, 0.25);
+    stroke-width: 2.5;
     fill: none;
 }
 
 .relationship-label {
-    font-size: 10px;
-    fill: var(--dash-text-muted, #999999);
+    font-size: 11px;
+    fill: var(--dash-text-secondary, #6b6b6b);
     text-anchor: middle;
     pointer-events: none;
     font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
+    font-weight: 500;
 }
 
 .node {
@@ -294,21 +295,23 @@
 
 .node-circle {
     stroke: white;
-    stroke-width: 3;
-    filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
+    stroke-width: 4;
+    filter: drop-shadow(0 3px 6px rgba(0, 0, 0, 0.15));
     transition: all var(--dash-transition-fast, 150ms);
 }
 
 .node:hover .node-circle {
-    filter: drop-shadow(0 4px 8px rgba(0, 0, 0, 0.2));
+    filter: drop-shadow(0 5px 10px rgba(0, 0, 0, 0.25));
+    stroke-width: 5;
 }
 
 .node-label {
-    font-size: 10px;
+    font-size: 12px;
     fill: white;
-    font-weight: 600;
+    font-weight: 700;
     pointer-events: none;
     font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
+    text-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
 }
 
 /* Tooltip */

frontend/src/components/HealthGraph.tsx

@@ -524,7 +524,7 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
                                                         onMouseLeave={() => setHoveredNode(null)}
                                                     >
                                                         <circle
-                                                            r={isHovered ? 28 : 24}
+                                                            r={isHovered ? 38 : 34}
                                                             fill={nodeColors[node.type] || nodeColors.entity}
                                                             className="node-circle"
                                                         />
@@ -533,8 +533,8 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
                                                             textAnchor="middle"
                                                             className="node-label"
                                                         >
-                                                            {node.name.length > 12
-                                                                ? node.name.slice(0, 10) + '...'
+                                                            {node.name.length > 14
+                                                                ? node.name.slice(0, 12) + '...'
                                                                 : node.name}
                                                         </text>
                                                     </g>

frontend/src/components/MemoryDashboard.css

@@ -241,8 +241,9 @@
   justify-content: space-between;
   gap: var(--dash-spacing-md, 1rem);
   padding: var(--dash-spacing-md, 1rem) var(--dash-spacing-lg, 1.5rem);
-  background: white;
+  background: linear-gradient(135deg, #ffffff 0%, #fafafa 100%);
   border: 1px solid var(--dash-border, #e5dfd5);
+  border-left: 3px solid var(--dash-accent-light, #8fb199);
   border-radius: var(--dash-radius-lg, 1rem);
   margin-bottom: var(--dash-spacing-sm, 0.75rem);
   transition: all var(--dash-transition-base, 250ms);
@@ -250,7 +251,9 @@
 
 .memory-item:hover {
   border-color: var(--dash-accent-light, #8fb199);
-  box-shadow: var(--dash-shadow-sm, 0 2px 8px rgba(107, 145, 117, 0.08));
+  border-left-color: var(--dash-accent, #6b9175);
+  background: white;
+  box-shadow: 0 4px 12px rgba(107, 145, 117, 0.12);
   transform: translateY(-1px);
 }
 

frontend/src/components/dashboard/DashboardNavbar.css

@@ -73,18 +73,19 @@
 .dashboard-nav {
   display: flex;
   align-items: center;
-  gap: var(--dash-spacing-md);
+  gap: var(--dash-spacing-sm, 0.75rem);
 }
 
 .dashboard-nav-link {
   padding: var(--dash-spacing-sm) var(--dash-spacing-md);
-  font-size: 0.9375rem;
+  font-size: 0.9rem;
   font-weight: 500;
   color: var(--dash-text-secondary);
   text-decoration: none;
   border-radius: var(--dash-radius-md);
   transition: all var(--dash-transition-fast);
   position: relative;
+  white-space: nowrap;
 }
 
 .dashboard-nav-link:hover {

frontend/src/components/dashboard/DashboardNavbar.tsx

@@ -1,7 +1,7 @@
 import { useState } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import { motion, AnimatePresence } from 'framer-motion';
-import { Settings, LogOut, Home, LayoutDashboard, Bell, FileText, Activity, Sparkles, Pill, PhoneCall, Network } from 'lucide-react';
+import { Settings, LogOut, Home, LayoutDashboard, FileText, Activity, Sparkles, Pill, PhoneCall, Network } from 'lucide-react';
 import { logout } from '../../utils/auth';
 import Logo from '../ui/Logo';
 import './DashboardNavbar.css';
@@ -69,16 +69,6 @@ function DashboardNavbar({ userName = 'User', userStatus = '87% Healthy' }: Dash
 
         {/* Actions */}
         <div className="dashboard-actions">
-          {/* Notifications */}
-          <motion.button
-            className="dash-btn dash-btn-icon dash-focus-ring"
-            whileHover={{ scale: 1.05 }}
-            whileTap={{ scale: 0.95 }}
-            aria-label="Notifications"
-          >
-            <Bell size={20} />
-          </motion.button>
-
           {/* User Menu */}
           <div className="dashboard-user-menu">
             <motion.button

frontend/src/components/physics/ExplainabilityCard.tsx

@@ -1,7 +1,7 @@
 /**
  * ExplainabilityCard – deterministic scoring breakdown.
  * Shows weights, normalised contributions, coverage/confidence.
- * Styled to match the calm Lumea card aesthetic.
+ * Matches clean Tailwind design system.
  */
 
 import React from 'react';
@@ -21,17 +21,17 @@ const ExplainabilityCard: React.FC<ExplainabilityCardProps> = ({
 }) => {
   if (!selectedOrgan || !organResult) {
     return (
-      <div className="dash-card physics-explainability-card">
+      <div className="dash-card h-full flex flex-col">
         <div className="dash-card-header">
-          <h3 className="dash-card-title">
+          <h3 className="dash-card-title flex items-center gap-2">
             <BarChart3 size={18} />
-            Explainability
+            Why this score?
           </h3>
         </div>
-        <div className="dash-card-body">
-          <div className="physics-explain-empty">
-            <Info size={32} />
-            <p>Select an organ to see the scoring breakdown</p>
+        <div className="dash-card-body flex-1 flex items-center justify-center">
+          <div className="text-center" style={{ color: 'var(--dash-text-muted)' }}>
+            <Info size={48} style={{ margin: '0 auto', opacity: 0.3 }} />
+            <p style={{ fontSize: '0.875rem', marginTop: '0.5rem' }}>Select an organ to see details</p>
           </div>
         </div>
       </div>
@@ -41,63 +41,131 @@ const ExplainabilityCard: React.FC<ExplainabilityCardProps> = ({
   const presentMetrics = organResult.contributions.filter((c) => c.value != null);
   const totalWeight = organResult.contributions.reduce((s, c) => s + c.weight, 0);
   const presentWeight = presentMetrics.reduce((s, c) => s + c.weight, 0);
+  const confidence = presentWeight > 0 ? Math.round((presentWeight / totalWeight) * 100) : 0;
 
   return (
-    <div className="dash-card physics-explainability-card">
+    <div className="dash-card h-full flex flex-col">
+      {/* Header */}
       <div className="dash-card-header">
-        <h3 className="dash-card-title">
+        <h3 className="dash-card-title flex items-center gap-2">
           <BarChart3 size={18} />
           Why this score?
         </h3>
-        <span className="physics-explain-organ-badge">{organLabel}</span>
+        <span className={`dash-badge dash-badge-${organResult.status === 'Healthy' ? 'success' : organResult.status === 'Watch' ? 'warning' : 'danger'}`}>
+          {organLabel}
+        </span>
       </div>
 
-      <div className="dash-card-body">
-        {/* Summary row */}
-        <div className="physics-explain-summary">
-          <div className="physics-explain-stat">
-            <span className="physics-explain-stat-value">{Math.round(organResult.score)}</span>
-            <span className="physics-explain-stat-label">Score</span>
+      {/* Content */}
+      <div className="dash-card-body flex-1" style={{ maxHeight: '500px', overflowY: 'auto' }}>
+        {/* Summary Stats */}
+        <div style={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(3, 1fr)',
+          gap: '1rem',
+          marginBottom: '1.5rem',
+          padding: '1rem',
+          background: 'var(--dash-accent-pale)',
+          borderRadius: 'var(--dash-radius-lg)',
+        }}>
+          <div style={{ textAlign: 'center' }}>
+            <div style={{ fontSize: '1.5rem', fontWeight: 'bold', color: 'var(--dash-success)' }}>
+              {Math.round(organResult.score)}
+            </div>
+            <div style={{ fontSize: '0.75rem', color: 'var(--dash-text-muted)', marginTop: '0.25rem' }}>Score</div>
           </div>
-          <div className="physics-explain-stat">
-            <span className="physics-explain-stat-value">{Math.round(organResult.coverage * 100)}%</span>
-            <span className="physics-explain-stat-label">Coverage</span>
+          <div style={{ textAlign: 'center' }}>
+            <div style={{ fontSize: '1.5rem', fontWeight: 'bold', color: 'var(--dash-info)' }}>
+              {Math.round(organResult.coverage * 100)}%
+            </div>
+            <div style={{ fontSize: '0.75rem', color: 'var(--dash-text-muted)', marginTop: '0.25rem' }}>Coverage</div>
           </div>
-          <div className="physics-explain-stat">
-            <span className="physics-explain-stat-value">
-              {presentWeight > 0 ? Math.round((presentWeight / totalWeight) * 100) : 0}%
-            </span>
-            <span className="physics-explain-stat-label">Confidence</span>
+          <div style={{ textAlign: 'center' }}>
+            <div style={{ fontSize: '1.5rem', fontWeight: 'bold', color: 'var(--dash-accent)' }}>
+              {confidence}%
+            </div>
+            <div style={{ fontSize: '0.75rem', color: 'var(--dash-text-muted)', marginTop: '0.25rem' }}>Confidence</div>
           </div>
         </div>
 
-        {/* Contributions table */}
-        <div className="physics-explain-table">
-          <div className="physics-explain-table-header">
+        {/* Metrics Table */}
+        <div style={{ marginTop: '1rem' }}>
+          {/* Header */}
+          <div style={{
+            display: 'grid',
+            gridTemplateColumns: '2fr 1fr 1fr 1fr 1fr',
+            gap: '0.5rem',
+            padding: '0.5rem 0.75rem',
+            fontSize: '0.75rem',
+            fontWeight: 600,
+            color: 'var(--dash-text-muted)',
+            textTransform: 'uppercase',
+            borderBottom: '2px solid var(--dash-border)',
+          }}>
             <span>Metric</span>
-            <span>Value</span>
-            <span>Norm</span>
-            <span>Weight</span>
-            <span>Contrib</span>
+            <span style={{ textAlign: 'right' }}>Value</span>
+            <span style={{ textAlign: 'right' }}>Norm</span>
+            <span style={{ textAlign: 'right' }}>Weight</span>
+            <span style={{ textAlign: 'right' }}>Contrib</span>
           </div>
-          {organResult.contributions.map((c) => (
-            <div key={c.name} className={`physics-explain-table-row ${c.value == null ? 'missing' : ''}`}>
-              <span className="physics-explain-metric-name">{c.name}</span>
-              <span>{c.value != null ? `${c.value}` : '—'}</span>
-              <span>{c.normalised != null ? c.normalised.toFixed(2) : '—'}</span>
-              <span>{(c.weight * 100).toFixed(0)}%</span>
-              <span>{c.weighted != null ? (c.weighted * 100).toFixed(1) : '—'}</span>
+
+          {/* Rows */}
+          {organResult.contributions.map((c, index) => (
+            <div
+              key={c.name}
+              style={{
+                display: 'grid',
+                gridTemplateColumns: '2fr 1fr 1fr 1fr 1fr',
+                gap: '0.5rem',
+                padding: '0.625rem 0.75rem',
+                fontSize: '0.875rem',
+                background: c.value == null ? 'transparent' : (index % 2 === 0 ? 'var(--dash-surface)' : 'var(--dash-surface-hover)'),
+                borderRadius: 'var(--dash-radius-sm)',
+                color: c.value == null ? 'var(--dash-text-muted)' : 'var(--dash-text)',
+                transition: 'background 0.2s',
+              }}
+              onMouseEnter={(e) => {
+                if (c.value != null) e.currentTarget.style.background = 'var(--dash-accent-pale)';
+              }}
+              onMouseLeave={(e) => {
+                if (c.value != null) e.currentTarget.style.background = index % 2 === 0 ? 'var(--dash-surface)' : 'var(--dash-surface-hover)';
+              }}
+            >
+              <span style={{ fontWeight: 500, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                {c.name}
+              </span>
+              <span style={{ textAlign: 'right', fontFamily: 'monospace' }}>
+                {c.value != null ? c.value.toString() : '—'}
+              </span>
+              <span style={{ textAlign: 'right', fontFamily: 'monospace' }}>
+                {c.normalised != null ? c.normalised.toFixed(2) : '—'}
+              </span>
+              <span style={{ textAlign: 'right', fontWeight: 600, color: 'var(--dash-info)' }}>
+                {(c.weight * 100).toFixed(0)}%
+              </span>
+              <span style={{ textAlign: 'right', fontWeight: 600, color: 'var(--dash-success)' }}>
+                {c.weighted != null ? (c.weighted * 100).toFixed(1) : '—'}
+              </span>
             </div>
           ))}
         </div>
 
-        {/* Formula note */}
-        <div className="physics-explain-note">
-          <Info size={14} />
-          <span>
-            Score = Σ (weight<sub>i</sub> × normalised<sub>i</sub>) / Σ weight<sub>present</sub> × 100.
+        {/* Formula Note */}
+        <div style={{
+          marginTop: '1.5rem',
+          padding: '1rem',
+          background: 'var(--dash-accent-pale)',
+          border: '1px solid var(--dash-accent-light)',
+          borderRadius: 'var(--dash-radius-lg)',
+          display: 'flex',
+          alignItems: 'flex-start',
+          gap: '0.75rem',
+        }}>
+          <Info size={16} style={{ color: 'var(--dash-accent)', flexShrink: 0, marginTop: '2px' }} />
+          <p style={{ fontSize: '0.75rem', color: 'var(--dash-text-secondary)', lineHeight: 1.6 }}>
+            <strong>Score Formula:</strong> Σ (weight<sub>i</sub> × normalised<sub>i</sub>) / Σ weight<sub>present</sub> × 100.
             Missing metrics are excluded — coverage reflects data completeness.
-          </span>
+          </p>
         </div>
       </div>
     </div>

frontend/src/components/physics/YouTubeRecommendationsCard.css

@@ -0,0 +1,320 @@
+/**
+ * YouTubeRecommendationsCard styles
+ * Matches Lumea dashboard design tokens
+ */
+
+.youtube-reco-card {
+  /* Card inherits dash-card base styles */
+  display: flex;
+  flex-direction: column;
+}
+
+.youtube-reco-card .dash-card-body {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.youtube-reco-organ-badge {
+  padding: 0.35rem 0.75rem;
+  background: linear-gradient(135deg, var(--sage-green, #6b9175) 0%, var(--sage-dark, #4a7c59) 100%);
+  color: white;
+  border-radius: 6px;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  letter-spacing: 0.025em;
+  box-shadow: 0 2px 4px rgba(107, 145, 117, 0.2);
+}
+
+.youtube-reco-organ-label {
+  font-size: 0.85rem;
+  color: var(--text-secondary, #6b7280);
+  font-style: italic;
+}
+
+/* Empty state */
+.youtube-reco-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 2.5rem 1rem;
+  text-align: center;
+  color: var(--text-muted, #9ca3af);
+}
+
+.youtube-reco-empty svg {
+  color: var(--sage-green, #6b9175);
+  margin-bottom: 1rem;
+  opacity: 0.5;
+}
+
+.youtube-reco-empty p {
+  font-size: 0.9rem;
+  margin: 0;
+}
+
+.youtube-reco-empty-subtitle {
+  font-size: 0.8125rem !important;
+  color: var(--text-muted, #9ca3af) !important;
+  margin-top: 0.5rem !important;
+}
+
+/* Loading state */
+.youtube-reco-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 2.5rem 1rem;
+  text-align: center;
+  color: var(--text-secondary, #6b7280);
+}
+
+.youtube-reco-loading .spinner {
+  color: var(--sage-green, #6b9175);
+  margin-bottom: 1rem;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.youtube-reco-loading p {
+  font-size: 0.9rem;
+  margin: 0;
+}
+
+/* Error state */
+.youtube-reco-error {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem 1rem;
+  text-align: center;
+}
+
+.youtube-reco-error svg {
+  color: var(--danger-color, #ef4444);
+  margin-bottom: 1rem;
+}
+
+.youtube-reco-error p {
+  font-size: 0.9rem;
+  color: var(--text-secondary, #6b7280);
+  margin: 0 0 1rem 0;
+}
+
+.youtube-reco-retry {
+  padding: 0.5rem 1.25rem;
+  background: var(--sage-green, #6b9175);
+  color: white;
+  border: none;
+  border-radius: 6px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.youtube-reco-retry:hover {
+  background: var(--sage-dark, #4a7c59);
+  transform: translateY(-1px);
+}
+
+/* Video list */
+.youtube-reco-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding-right: 0.25rem;
+}
+
+/* Custom scrollbar */
+.youtube-reco-list::-webkit-scrollbar {
+  width: 6px;
+}
+
+.youtube-reco-list::-webkit-scrollbar-track {
+  background: rgba(107, 145, 117, 0.05);
+  border-radius: 3px;
+}
+
+.youtube-reco-list::-webkit-scrollbar-thumb {
+  background: rgba(107, 145, 117, 0.2);
+  border-radius: 3px;
+}
+
+.youtube-reco-list::-webkit-scrollbar-thumb:hover {
+  background: rgba(107, 145, 117, 0.3);
+}
+
+/* Video card */
+.youtube-video-card {
+  display: flex;
+  gap: 0.875rem;
+  padding: 1rem;
+  background: linear-gradient(135deg, #ffffff 0%, #fafafa 100%);
+  border: 1px solid rgba(107, 145, 117, 0.12);
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.25s ease;
+  position: relative;
+  min-height: 110px;
+}
+
+.youtube-video-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(107, 145, 117, 0.15);
+  border-color: var(--sage-green, #6b9175);
+}
+
+/* Video thumbnail */
+.youtube-video-thumbnail {
+  flex-shrink: 0;
+  width: 180px;
+  height: 101px; /* 16:9 aspect ratio */
+  border-radius: 6px;
+  overflow: hidden;
+  background: linear-gradient(135deg, #f0f0f0 0%, #e0e0e0 100%);
+  position: relative;
+}
+
+.youtube-video-thumbnail img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: transform 0.3s ease;
+}
+
+.youtube-video-card:hover .youtube-video-thumbnail img {
+  transform: scale(1.05);
+}
+
+/* Play overlay */
+.youtube-video-play-overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.3);
+  opacity: 0;
+  transition: opacity 0.25s ease;
+}
+
+.youtube-video-card:hover .youtube-video-play-overlay {
+  opacity: 1;
+}
+
+.youtube-video-play-overlay svg {
+  color: white;
+  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.3));
+}
+
+/* Video info */
+.youtube-video-info {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+  min-width: 0; /* Enable text truncation */
+}
+
+.youtube-video-title {
+  font-size: 0.9375rem;
+  font-weight: 600;
+  color: var(--text-primary, #111827);
+  margin: 0;
+  line-height: 1.35;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  transition: color 0.2s ease;
+}
+
+.youtube-video-card:hover .youtube-video-title {
+  color: var(--sage-green, #6b9175);
+}
+
+.youtube-video-channel {
+  font-size: 0.8125rem;
+  color: var(--text-secondary, #6b7280);
+  margin: 0;
+  font-weight: 500;
+}
+
+.youtube-video-description {
+  font-size: 0.8125rem;
+  color: var(--text-muted, #9ca3af);
+  margin: 0;
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* Link icon */
+.youtube-video-link-icon {
+  flex-shrink: 0;
+  align-self: flex-start;
+  margin-top: 0.25rem;
+  color: var(--text-muted, #9ca3af);
+  transition: color 0.2s ease;
+}
+
+.youtube-video-card:hover .youtube-video-link-icon {
+  color: var(--sage-green, #6b9175);
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .youtube-video-card {
+    flex-direction: column;
+    min-height: auto;
+  }
+
+  .youtube-video-thumbnail {
+    width: 100%;
+    height: 200px;
+  }
+
+  .youtube-video-link-icon {
+    position: absolute;
+    top: 1rem;
+    right: 1rem;
+  }
+}
+
+@media (max-width: 1200px) {
+  .youtube-video-thumbnail {
+    width: 140px;
+    height: 79px;
+  }
+}
+
+/* Compact view for smaller cards */
+.youtube-reco-card.compact .youtube-video-thumbnail {
+  width: 120px;
+  height: 68px;
+}
+
+.youtube-reco-card.compact .youtube-video-title {
+  font-size: 0.875rem;
+  -webkit-line-clamp: 1;
+}
+
+.youtube-reco-card.compact .youtube-video-description {
+  display: none;
+}

frontend/src/components/physics/YouTubeRecommendationsCard.tsx

@@ -0,0 +1,392 @@
+/**
+ * YouTubeRecommendationsCard – Smart video recommendations for organ health
+ * 
+ * Uses OpenRouter AI to generate video recommendations (no YouTube API needed)
+ * FIXED: Stable fetch with caching, no infinite loops
+ */
+
+import React, { useState, useEffect, useRef } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+import { Youtube, ExternalLink, Loader2, AlertCircle, PlayCircle, Clock } from 'lucide-react';
+import type { OrganResult } from '../../services/physicsApi';
+import { generateVideoRecommendations, type AbnormalMetric, type VideoRecommendation } from '../../services/openRouterService';
+
+interface YouTubeRecommendationsCardProps {
+  selectedOrgan: string | null;
+  organResult: OrganResult | null;
+  currentMetrics: Record<string, number>;
+}
+
+const ORGAN_LABELS: Record<string, string> = {
+  kidney: 'Kidney',
+  heart: 'Heart',
+  liver: 'Liver',
+  lungs: 'Lungs',
+  brain: 'Brain',
+  blood: 'Blood',
+};
+
+// Reference ranges for metrics
+const METRIC_RANGES: Record<string, { min: number; max: number }> = {
+  creatinine: { min: 0.6, max: 1.2 },
+  urea: { min: 7, max: 20 },
+  alt: { min: 7, max: 56 },
+  ast: { min: 10, max: 40 },
+  bilirubin_total: { min: 0.1, max: 1.2 },
+  systolic_bp: { min: 90, max: 120 },
+  diastolic_bp: { min: 60, max: 80 },
+  heart_rate: { min: 60, max: 100 },
+  glucose: { min: 70, max: 100 },
+  spo2: { min: 95, max: 100 },
+  sodium: { min: 136, max: 145 },
+  potassium: { min: 3.5, max: 5.0 },
+};
+
+const YouTubeRecommendationsCard: React.FC<YouTubeRecommendationsCardProps> = ({
+  selectedOrgan,
+  organResult,
+  currentMetrics,
+}) => {
+  const [videos, setVideos] = useState<VideoRecommendation[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  
+  // Cache videos per organ to avoid refetching
+  const cacheRef = useRef<Map<string, VideoRecommendation[]>>(new Map());
+  
+  // Track current request to ignore stale responses
+  const requestIdRef = useRef(0);
+  
+  // AbortController for cancelling requests
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  // Calculate abnormal metrics
+  const getAbnormalMetrics = (metrics: Record<string, number>): AbnormalMetric[] => {
+    const abnormal: AbnormalMetric[] = [];
+
+    for (const [metricKey, value] of Object.entries(metrics)) {
+      const range = METRIC_RANGES[metricKey];
+      if (!range || typeof value !== 'number') continue;
+
+      if (value < range.min) {
+        abnormal.push({
+          name: metricKey,
+          value,
+          normalRange: `${range.min}-${range.max}`,
+          status: 'low',
+        });
+      } else if (value > range.max) {
+        abnormal.push({
+          name: metricKey,
+          value,
+          normalRange: `${range.min}-${range.max}`,
+          status: 'high',
+        });
+      }
+    }
+
+    return abnormal;
+  };
+
+  useEffect(() => {
+    // Clear state if no organ selected
+    if (!selectedOrgan || !organResult) {
+      setVideos([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Check cache first
+    const cached = cacheRef.current.get(selectedOrgan);
+    if (cached) {
+      setVideos(cached);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Abort previous request if still running
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+    }
+
+    // Start new fetch
+    const abortController = new AbortController();
+    abortControllerRef.current = abortController;
+    
+    const currentRequestId = ++requestIdRef.current;
+    
+    const fetchRecommendations = async () => {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const abnormalMetrics = getAbnormalMetrics(currentMetrics);
+        
+        // Generate video recommendations using OpenRouter AI
+        const recommendations = await generateVideoRecommendations(
+          ORGAN_LABELS[selectedOrgan] || selectedOrgan,
+          abnormalMetrics
+        );
+        
+        // Only update if this is still the latest request
+        if (currentRequestId === requestIdRef.current && !abortController.signal.aborted) {
+          setVideos(recommendations);
+          // Cache the results
+          cacheRef.current.set(selectedOrgan, recommendations);
+          setError(null);
+        }
+      } catch (err: any) {
+        // Only show error if request wasn't aborted
+        if (!abortController.signal.aborted && currentRequestId === requestIdRef.current) {
+          console.error('Error fetching recommendations:', err);
+          setError(err.message || 'Failed to load recommendations');
+          setVideos([]);
+        }
+      } finally {
+        // Only clear loading if this is still the latest request
+        if (currentRequestId === requestIdRef.current && !abortController.signal.aborted) {
+          setLoading(false);
+        }
+      }
+    };
+
+    fetchRecommendations();
+
+    // Cleanup: abort request on unmount or organ change
+    return () => {
+      abortController.abort();
+    };
+  }, [selectedOrgan]); // ONLY depend on selectedOrgan, not currentMetrics!
+
+  const handleRetry = () => {
+    // Clear cache for this organ and refetch
+    if (selectedOrgan) {
+      cacheRef.current.delete(selectedOrgan);
+      // Trigger refetch by incrementing request ID
+      requestIdRef.current++;
+      
+      const fetchRecommendations = async () => {
+        if (!selectedOrgan || !organResult) return;
+        
+        setLoading(true);
+        setError(null);
+
+        try {
+          const abnormalMetrics = getAbnormalMetrics(currentMetrics);
+          const recommendations = await generateVideoRecommendations(
+            ORGAN_LABELS[selectedOrgan] || selectedOrgan,
+            abnormalMetrics
+          );
+          
+          setVideos(recommendations);
+          cacheRef.current.set(selectedOrgan, recommendations);
+          setError(null);
+        } catch (err: any) {
+          console.error('Error fetching recommendations:', err);
+          setError(err.message || 'Failed to load recommendations');
+        } finally {
+          setLoading(false);
+        }
+      };
+
+      fetchRecommendations();
+    }
+  };
+
+  const openVideo = (url: string) => {
+    window.open(url, '_blank', 'noopener,noreferrer');
+  };
+
+  if (!selectedOrgan || !organResult) {
+    return (
+      <div className="rounded-2xl border border-gray-200 bg-white shadow-sm overflow-hidden flex flex-col h-full">
+        <div className="p-6 border-b border-gray-100 bg-gradient-to-r from-emerald-50 to-teal-50">
+          <div className="flex items-center justify-between">
+            <div className="flex items-center gap-3">
+              <Youtube className="text-emerald-600" size={24} />
+              <h3 className="text-lg font-semibold text-gray-900">Improve Your Health</h3>
+            </div>
+          </div>
+        </div>
+        <div className="flex-1 flex items-center justify-center p-8">
+          <div className="text-center text-gray-500 space-y-2">
+            <Youtube size={48} className="mx-auto opacity-30" />
+            <p className="text-sm font-medium">All organs performing well!</p>
+            <p className="text-xs text-gray-400">No specific recommendations needed</p>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="dash-card h-full flex flex-col">
+      {/* Header */}
+      <div className="dash-card-header">
+        <h3 className="dash-card-title flex items-center gap-2">
+          <Youtube size={18} />
+          Improve Your Health
+        </h3>
+        <span className={`dash-badge dash-badge-${organResult.status === 'Healthy' ? 'success' : organResult.status === 'Watch' ? 'warning' : 'danger'}`}>
+          {ORGAN_LABELS[selectedOrgan]}
+        </span>
+      </div>
+
+      {/* Content */}
+      <div className="dash-card-body flex-1" style={{ maxHeight: '500px', overflowY: 'auto' }}>
+        <AnimatePresence mode="wait">
+          {loading && (
+            <motion.div
+              key="loading"
+              style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', padding: '2rem 0' }}
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+            >
+              <Loader2 size={32} className="animate-spin" style={{ color: 'var(--dash-accent)' }} />
+              <p style={{ fontSize: '0.875rem', color: 'var(--dash-text-secondary)', marginTop: '0.75rem' }}>Finding best videos for you...</p>
+            </motion.div>
+          )}
+
+          {error && !loading && (
+            <motion.div
+              key="error"
+              style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', padding: '2rem 0', textAlign: 'center' }}
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+            >
+              <AlertCircle size={32} style={{ color: 'var(--dash-danger)' }} />
+              <p style={{ fontSize: '0.875rem', color: 'var(--dash-text-secondary)', margin: '0.75rem 0' }}>{error}</p>
+              <button
+                onClick={handleRetry}
+                className="dash-btn dash-btn-primary"
+              >
+                Try Again
+              </button>
+            </motion.div>
+          )}
+
+          {!loading && !error && videos.length > 0 && (
+            <motion.div
+              key="videos"
+              className="space-y-4"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+            >
+              {videos.map((video, index) => (
+                <motion.div
+                  key={`${video.title}-${index}`}
+                  style={{
+                    background: 'var(--dash-surface)',
+                    border: '1px solid var(--dash-border-light)',
+                    borderRadius: 'var(--dash-radius-lg)',
+                    padding: '1rem',
+                    marginBottom: '0.75rem',
+                    cursor: 'pointer',
+                    transition: 'all 0.2s ease',
+                    display: 'flex',
+                    gap: '1rem',
+                  }}
+                  initial={{ opacity: 0, y: 10 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ delay: index * 0.1 }}
+                  onClick={() => openVideo(video.url)}
+                  onMouseEnter={(e) => {
+                    e.currentTarget.style.border = '1px solid var(--dash-accent-light)';
+                    e.currentTarget.style.boxShadow = 'var(--dash-shadow-md)';
+                  }}
+                  onMouseLeave={(e) => {
+                    e.currentTarget.style.border = '1px solid var(--dash-border-light)';
+                    e.currentTarget.style.boxShadow = 'none';
+                  }}
+                >
+                  {/* Thumbnail */}
+                  <div style={{
+                    flexShrink: 0,
+                    width: '120px',
+                    height: '80px',
+                    background: 'linear-gradient(135deg, var(--dash-accent-pale), var(--dash-accent-light))',
+                    borderRadius: 'var(--dash-radius-md)',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    position: 'relative',
+                    overflow: 'hidden',
+                  }}>
+                    <Youtube size={32} style={{ color: 'var(--dash-accent)', opacity: 0.5 }} />
+                    <div style={{
+                      position: 'absolute',
+                      inset: 0,
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      transition: 'opacity 0.2s',
+                    }}>
+                      <PlayCircle size={32} style={{ color: 'white', opacity: 0.8 }} />
+                    </div>
+                  </div>
+
+                  {/* Video Info */}
+                  <div style={{ flex: 1, minWidth: 0 }}>
+                    <h4 style={{
+                      fontSize: '0.875rem',
+                      fontWeight: 600,
+                      color: 'var(--dash-text)',
+                      marginBottom: '0.25rem',
+                      lineHeight: 1.3,
+                      display: '-webkit-box',
+                      WebkitLineClamp: 2,
+                      WebkitBoxOrient: 'vertical',
+                      overflow: 'hidden',
+                    }}>
+                      {video.title}
+                    </h4>
+                    <p style={{
+                      fontSize: '0.75rem',
+                      color: 'var(--dash-text-secondary)',
+                      marginBottom: '0.5rem',
+                      display: '-webkit-box',
+                      WebkitLineClamp: 2,
+                      WebkitBoxOrient: 'vertical',
+                      overflow: 'hidden',
+                    }}>
+                      {video.description}
+                    </p>
+                    <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem', fontSize: '0.75rem', color: 'var(--dash-text-muted)' }}>
+                      <Clock size={12} />
+                      <span>{video.duration}</span>
+                    </div>
+                  </div>
+
+                  {/* External Link Icon */}
+                  <div style={{ flexShrink: 0 }}>
+                    <ExternalLink size={16} style={{ color: 'var(--dash-text-muted)' }} />
+                  </div>
+                </motion.div>
+              ))}
+            </motion.div>
+          )}
+
+          {!loading && !error && videos.length === 0 && (
+            <motion.div
+              key="empty"
+              style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', padding: '2rem 0', textAlign: 'center' }}
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+            >
+              <Youtube size={48} style={{ color: 'var(--dash-border)', opacity: 0.5 }} />
+              <p style={{ fontSize: '0.875rem', color: 'var(--dash-text-muted)', marginTop: '0.5rem' }}>No recommendations available</p>
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </div>
+    </div>
+  );
+};
+
+export default YouTubeRecommendationsCard;

frontend/src/components/ui/PdfPreview.css

@@ -2,9 +2,12 @@
   position: relative;
   width: 100%;
   height: 100%;
+  min-height: 0;
   background: #f5f5f5;
   border-radius: 0.5rem;
-  overflow: hidden;
+  overflow: auto;
+  display: flex;
+  flex-direction: column;
 }
 
 .pdf-preview-iframe {

frontend/src/pages/Features.css

@@ -1,74 +1,73 @@
-/* Features Page Styles */
+/* Features Page Styles - Lumea Theme */
 
 .features-page {
     min-height: 100vh;
-    background: var(--dash-bg);
+    background: linear-gradient(135deg, #f8f5f0 0%, #f0ebe3 100%);
     position: relative;
     overflow-x: hidden;
 }
 
-/* Animated Background */
+/* Animated Background with Radial Gradients */
 .features-background {
     position: fixed;
     inset: 0;
     z-index: 0;
     overflow: hidden;
     pointer-events: none;
+    background:
+        radial-gradient(circle at 20% 30%, rgba(107, 145, 117, 0.08) 0%, transparent 50%),
+        radial-gradient(circle at 80% 70%, rgba(217, 169, 98, 0.06) 0%, transparent 50%),
+        radial-gradient(circle at 50% 50%, rgba(122, 156, 198, 0.04) 0%, transparent 60%);
 }
 
 .features-bg-blob {
     position: absolute;
     border-radius: 50%;
-    filter: blur(120px);
-    opacity: 0.4;
-    animation: blobFloat 20s ease-in-out infinite;
+    filter: blur(140px);
+    opacity: 0.15;
+    animation: blobFloat 25s ease-in-out infinite;
 }
 
 .features-bg-blob-1 {
-    width: 600px;
-    height: 600px;
-    background: var(--dash-accent);
-    top: -200px;
-    right: -200px;
+    width: 500px;
+    height: 500px;
+    background: radial-gradient(circle, rgba(107, 145, 117, 0.3), transparent);
+    top: -150px;
+    right: -150px;
     animation-delay: 0s;
 }
 
 .features-bg-blob-2 {
-    width: 500px;
-    height: 500px;
-    background: var(--dash-info);
-    bottom: -150px;
-    left: -150px;
-    animation-delay: -7s;
+    width: 450px;
+    height: 450px;
+    background: radial-gradient(circle, rgba(217, 169, 98, 0.25), transparent);
+    bottom: -100px;
+    left: -100px;
+    animation-delay: -8s;
 }
 
 .features-bg-blob-3 {
-    width: 400px;
-    height: 400px;
-    background: var(--dash-warning);
-    top: 50%;
+    width: 350px;
+    height: 350px;
+    background: radial-gradient(circle, rgba(122, 156, 198, 0.2), transparent);
+    top: 40%;
     left: 50%;
     transform: translate(-50%, -50%);
-    animation-delay: -14s;
+    animation-delay: -16s;
 }
 
 @keyframes blobFloat {
-
-    0%,
-    100% {
+    0%, 100% {
         transform: translate(0, 0) scale(1);
     }
-
     25% {
-        transform: translate(20px, -30px) scale(1.05);
+        transform: translate(30px, -40px) scale(1.08);
     }
-
     50% {
-        transform: translate(-20px, 20px) scale(0.95);
+        transform: translate(-30px, 30px) scale(0.92);
     }
-
     75% {
-        transform: translate(30px, 10px) scale(1.02);
+        transform: translate(40px, 15px) scale(1.04);
     }
 }
 
@@ -76,12 +75,13 @@
 .features-content {
     position: relative;
     z-index: 1;
-    padding: 100px 24px 60px;
+    padding: 110px 24px 80px;
 }
 
 .features-container {
-    max-width: 1200px;
+    max-width: 1300px;
     margin: 0 auto;
+    padding: 0 var(--dash-spacing-lg, 1.5rem);
 }
 
 .features-loading {
@@ -97,109 +97,139 @@
 /* Hero Section */
 .features-hero {
     text-align: center;
-    padding: 60px 0 80px;
+    padding: 40px 0 60px;
+    max-width: 900px;
+    margin: 0 auto;
 }
 
 .hero-badge {
     display: inline-flex;
     align-items: center;
     gap: 8px;
-    padding: 8px 16px;
-    background: rgba(106, 145, 117, 0.15);
-    border: 1px solid rgba(106, 145, 117, 0.3);
-    border-radius: 100px;
-    color: var(--dash-accent);
+    padding: 8px 18px;
+    background: rgba(232, 243, 235, 0.7);
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(107, 145, 117, 0.2);
+    border-radius: var(--dash-radius-full, 9999px);
+    color: var(--dash-accent-dark, #4a7c59);
     font-size: 13px;
-    font-weight: 500;
+    font-weight: 600;
     margin-bottom: 24px;
+    box-shadow: 0 2px 8px rgba(107, 145, 117, 0.1);
 }
 
 .features-hero h1 {
-    font-size: 3.5rem;
+    font-size: 3.25rem;
     font-weight: 700;
-    color: var(--dash-text);
+    color: var(--dash-text, #2d2d2d);
     margin: 0 0 20px;
-    line-height: 1.1;
+    line-height: 1.15;
+    font-family: var(--dash-font-serif, 'Playfair Display', Georgia, serif);
+    letter-spacing: -0.02em;
 }
 
 .gradient-text {
-    background: linear-gradient(135deg, var(--dash-accent), var(--dash-info));
-    -webkit-background-clip: text;
-    -webkit-text-fill-color: transparent;
-    background-clip: text;
+    color: var(--dash-accent, #6b9175);
+    position: relative;
 }
 
 .hero-description {
-    font-size: 1.15rem;
-    color: var(--dash-text-muted);
-    max-width: 640px;
-    margin: 0 auto 48px;
+    font-size: 1.125rem;
+    color: var(--dash-text-secondary, #6b6b6b);
+    max-width: 680px;
+    margin: 0 auto 56px;
     line-height: 1.7;
+    font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
 }
 
-/* Hero Features Grid */
+/* Hero Features Grid - Glassy Cards */
 .hero-features {
     display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
     gap: 24px;
-    max-width: 960px;
-    margin: 0 auto 48px;
+    max-width: 1100px;
+    margin: 0 auto 64px;
     text-align: left;
 }
 
 .hero-feature {
     display: flex;
-    gap: 16px;
-    padding: 20px;
-    background: var(--dash-card-bg);
-    border: 1px solid var(--dash-border);
-    border-radius: 16px;
-    transition: all 0.2s ease;
+    gap: 18px;
+    padding: 24px;
+    background: rgba(255, 255, 255, 0.5);
+    backdrop-filter: blur(12px);
+    border: 1px solid rgba(107, 145, 117, 0.15);
+    border-radius: var(--dash-radius-xl, 1.5rem);
+    box-shadow: 0 8px 24px rgba(107, 145, 117, 0.08);
+    transition: all var(--dash-transition-base, 250ms);
+    position: relative;
+    overflow: hidden;
+}
+
+.hero-feature::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 4px;
+    height: 100%;
+    background: linear-gradient(180deg, var(--dash-accent) 0%, var(--dash-accent-light) 100%);
+    opacity: 0;
+    transition: opacity var(--dash-transition-base, 250ms);
 }
 
 .hero-feature:hover {
-    transform: translateY(-2px);
-    border-color: var(--dash-accent);
-    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
+    transform: translateY(-4px);
+    border-color: rgba(107, 145, 117, 0.3);
+    background: rgba(255, 255, 255, 0.7);
+    box-shadow: 0 12px 32px rgba(107, 145, 117, 0.15);
+}
+
+.hero-feature:hover::before {
+    opacity: 1;
 }
 
 .hero-feature-icon {
-    width: 44px;
-    height: 44px;
-    border-radius: 12px;
+    width: 52px;
+    height: 52px;
+    border-radius: var(--dash-radius-lg, 1rem);
     display: flex;
     align-items: center;
     justify-content: center;
     flex-shrink: 0;
+    position: relative;
+    background: linear-gradient(135deg, rgba(107, 145, 117, 0.15), rgba(107, 145, 117, 0.08));
 }
 
 .hero-feature-icon.memory {
-    background: rgba(156, 136, 255, 0.15);
-    color: #9c88ff;
+    background: linear-gradient(135deg, rgba(107, 145, 117, 0.2), rgba(107, 145, 117, 0.1));
+    color: var(--dash-accent, #6b9175);
 }
 
 .hero-feature-icon.graph {
-    background: rgba(122, 156, 198, 0.15);
-    color: var(--dash-info);
+    background: linear-gradient(135deg, rgba(122, 156, 198, 0.2), rgba(122, 156, 198, 0.1));
+    color: var(--dash-info, #7a9cc6);
 }
 
 .hero-feature-icon.ai {
-    background: rgba(106, 145, 117, 0.15);
-    color: var(--dash-accent);
+    background: linear-gradient(135deg, rgba(74, 124, 89, 0.2), rgba(74, 124, 89, 0.1));
+    color: var(--dash-accent-dark, #4a7c59);
 }
 
 .hero-feature-content h4 {
-    margin: 0 0 6px;
-    font-size: 15px;
+    margin: 0 0 4px;
+    font-size: 16px;
     font-weight: 600;
-    color: var(--dash-text);
+    color: var(--dash-text, #2d2d2d);
+    font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
 }
 
 .hero-feature-content p {
     margin: 0;
-    font-size: 13px;
-    color: var(--dash-text-muted);
-    line-height: 1.5;
+    font-size: 14px;
+    color: var(--dash-text-secondary, #6b6b6b);
+    line-height: 1.6;
+    font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
 }
 
 .scroll-indicator {
@@ -207,23 +237,43 @@
     opacity: 0.5;
 }
 
-/* Flow Diagram */
+/* Flow Diagram - Tinted Container */
 .features-flow {
-    padding: 48px 0 64px;
-    text-align: center;
+    padding: 48px;
+    margin: 0 auto 64px;
+    max-width: 1100px;
+    background: rgba(255, 255, 255, 0.4);
+    backdrop-filter: blur(16px);
+    border: 1px solid rgba(107, 145, 117, 0.12);
+    border-radius: var(--dash-radius-xl, 1.5rem);
+    box-shadow: 0 8px 24px rgba(107, 145, 117, 0.08);
 }
 
 .features-flow h2 {
-    font-size: 1.5rem;
-    color: var(--dash-text);
-    margin: 0 0 32px;
+    font-size: 1.75rem;
+    color: var(--dash-text, #2d2d2d);
+    margin: 0 0 12px;
+    text-align: center;
+    font-family: var(--dash-font-serif, 'Playfair Display', Georgia, serif);
+    font-weight: 600;
+    letter-spacing: -0.01em;
+}
+
+.features-flow > p {
+    text-align: center;
+    color: var(--dash-text-secondary, #6b6b6b);
+    font-size: 14px;
+    margin: 0 0 40px;
+    max-width: 600px;
+    margin-left: auto;
+    margin-right: auto;
 }
 
 .flow-diagram {
     display: flex;
     align-items: center;
     justify-content: center;
-    gap: 16px;
+    gap: 20px;
     flex-wrap: wrap;
 }
 
@@ -231,60 +281,68 @@
     display: flex;
     flex-direction: column;
     align-items: center;
-    gap: 12px;
+    gap: 14px;
 }
 
 .flow-icon {
-    width: 64px;
-    height: 64px;
-    border-radius: 16px;
-    background: var(--dash-card-bg);
-    border: 2px solid var(--dash-border);
+    width: 72px;
+    height: 72px;
+    border-radius: var(--dash-radius-xl, 1.5rem);
+    background: rgba(255, 255, 255, 0.7);
+    backdrop-filter: blur(8px);
+    border: 2px solid rgba(107, 145, 117, 0.2);
     display: flex;
     align-items: center;
     justify-content: center;
-    color: var(--dash-text);
-    transition: all 0.2s ease;
+    color: var(--dash-text, #2d2d2d);
+    transition: all var(--dash-transition-base, 250ms);
+    box-shadow: 0 4px 12px rgba(107, 145, 117, 0.08);
 }
 
 .flow-icon.memory {
-    border-color: #9c88ff;
-    color: #9c88ff;
+    border-color: rgba(107, 145, 117, 0.3);
+    color: var(--dash-accent, #6b9175);
+    background: linear-gradient(135deg, rgba(232, 243, 235, 0.8), rgba(255, 255, 255, 0.7));
 }
 
 .flow-icon.graph {
-    border-color: var(--dash-info);
-    color: var(--dash-info);
+    border-color: rgba(122, 156, 198, 0.3);
+    color: var(--dash-info, #7a9cc6);
+    background: linear-gradient(135deg, rgba(122, 156, 198, 0.15), rgba(255, 255, 255, 0.7));
 }
 
 .flow-icon.ai {
-    border-color: var(--dash-accent);
-    color: var(--dash-accent);
+    border-color: rgba(74, 124, 89, 0.3);
+    color: var(--dash-accent-dark, #4a7c59);
+    background: linear-gradient(135deg, rgba(232, 243, 235, 0.8), rgba(255, 255, 255, 0.7));
 }
 
 .flow-step span {
-    font-size: 13px;
-    color: var(--dash-text-muted);
-    font-weight: 500;
+    font-size: 14px;
+    color: var(--dash-text-secondary, #6b6b6b);
+    font-weight: 600;
+    text-align: center;
 }
 
 .flow-arrow {
-    color: var(--dash-text-muted);
-    opacity: 0.4;
+    color: var(--dash-accent-light, #8fb199);
+    opacity: 0.5;
+    font-size: 20px;
 }
 
 /* Sections */
 .features-section {
-    margin-bottom: 48px;
+    margin-bottom: 56px;
 }
 
 .section-header {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    margin-bottom: 20px;
+    margin-bottom: 24px;
     flex-wrap: wrap;
     gap: 16px;
+    padding: 0 var(--dash-spacing-md, 1rem);
 }
 
 .section-header-left {
@@ -294,53 +352,62 @@
 }
 
 .section-icon {
-    width: 44px;
-    height: 44px;
-    padding: 10px;
-    border-radius: 12px;
+    width: 48px;
+    height: 48px;
+    padding: 12px;
+    border-radius: var(--dash-radius-lg, 1rem);
     flex-shrink: 0;
+    backdrop-filter: blur(8px);
 }
 
 .section-icon.memory {
-    background: rgba(156, 136, 255, 0.15);
-    color: #9c88ff;
+    background: linear-gradient(135deg, rgba(107, 145, 117, 0.15), rgba(107, 145, 117, 0.08));
+    color: var(--dash-accent, #6b9175);
 }
 
 .section-icon.graph {
-    background: rgba(122, 156, 198, 0.15);
-    color: var(--dash-info);
+    background: linear-gradient(135deg, rgba(122, 156, 198, 0.15), rgba(122, 156, 198, 0.08));
+    color: var(--dash-info, #7a9cc6);
 }
 
 .section-header h2 {
     margin: 0;
-    font-size: 1.35rem;
-    color: var(--dash-text);
+    font-size: 1.5rem;
+    color: var(--dash-text, #2d2d2d);
+    font-family: var(--dash-font-serif, 'Playfair Display', Georgia, serif);
+    font-weight: 600;
+    letter-spacing: -0.01em;
 }
 
 .section-header p {
     margin: 4px 0 0;
     font-size: 14px;
-    color: var(--dash-text-muted);
+    color: var(--dash-text-secondary, #6b6b6b);
+    font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
 }
 
 .section-badge {
     display: inline-flex;
     align-items: center;
     gap: 6px;
-    padding: 6px 12px;
-    background: var(--dash-card-bg);
-    border: 1px solid var(--dash-border);
-    border-radius: 100px;
+    padding: 6px 14px;
+    background: rgba(255, 255, 255, 0.6);
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(107, 145, 117, 0.15);
+    border-radius: var(--dash-radius-full, 9999px);
     font-size: 12px;
-    color: var(--dash-text-muted);
+    font-weight: 600;
+    color: var(--dash-accent-dark, #4a7c59);
 }
 
 .section-content {
-    background: var(--dash-card-bg);
-    border: 1px solid var(--dash-border);
-    border-radius: 20px;
-    padding: 4px;
+    background: rgba(255, 255, 255, 0.5);
+    backdrop-filter: blur(12px);
+    border: 1px solid rgba(107, 145, 117, 0.12);
+    border-radius: var(--dash-radius-xl, 1.5rem);
+    padding: 6px;
     overflow: hidden;
+    box-shadow: 0 8px 24px rgba(107, 145, 117, 0.08);
 }
 
 .section-content-large {
@@ -353,56 +420,139 @@
     background: transparent;
     border: none;
     border-radius: 0;
+    box-shadow: none;
 }
 
 .section-content .memory-header,
 .section-content .health-graph-header {
     cursor: default;
-    background: rgba(255, 255, 255, 0.02);
-    border-radius: 16px 16px 0 0;
+    background: rgba(255, 255, 255, 0.4);
+    backdrop-filter: blur(8px);
+    border-radius: var(--dash-radius-lg, 1rem) var(--dash-radius-lg, 1rem) 0 0;
+    padding: 18px 24px;
+    border-bottom: 1px solid rgba(107, 145, 117, 0.1);
+}
+
+/* Memory Dashboard GitHub-style */
+.section-content .memory-list {
+    padding: 20px;
+    background: transparent;
+}
+
+.section-content .memory-item {
+    background: rgba(255, 255, 255, 0.45);
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(107, 145, 117, 0.15);
+    border-left: 3px solid var(--dash-accent, #6b9175);
+    border-radius: var(--dash-radius-lg, 1rem);
     padding: 16px 20px;
+    margin-bottom: 12px;
+    box-shadow: 0 2px 8px rgba(107, 145, 117, 0.06);
+    transition: all var(--dash-transition-base, 250ms);
+}
+
+.section-content .memory-item:hover {
+    background: rgba(255, 255, 255, 0.65);
+    border-left-color: var(--dash-accent-dark, #4a7c59);
+    box-shadow: 0 4px 16px rgba(107, 145, 117, 0.12);
+    transform: translateX(2px);
+}
+
+.section-content .memory-search {
+    background: rgba(255, 255, 255, 0.5);
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(107, 145, 117, 0.15);
+    border-radius: var(--dash-radius-lg, 1rem);
+    padding: 10px 16px;
+}
+
+.section-content .memory-search:focus-within {
+    background: rgba(255, 255, 255, 0.7);
+    border-color: var(--dash-accent, #6b9175);
+    box-shadow: 0 0 0 3px rgba(232, 243, 235, 0.5);
+}
+
+/* Graph Canvas Improvements */
+.section-content .health-graph-canvas-wrapper {
+    position: relative;
+    padding: var(--dash-spacing-xl, 2rem);
+    background: linear-gradient(135deg, rgba(232, 243, 235, 0.2) 0%, rgba(255, 255, 255, 0.3) 100%);
+    backdrop-filter: blur(8px);
+    margin: 16px;
+    border-radius: var(--dash-radius-lg, 1rem);
+    border: 1px solid rgba(107, 145, 117, 0.12);
+    overflow: visible;
+}
+
+.section-content .health-graph-canvas {
+    min-height: 450px;
+}
+
+.section-content .health-graph-toolbar {
+    background: rgba(255, 255, 255, 0.5);
+    backdrop-filter: blur(8px);
+    border-bottom: 1px solid rgba(107, 145, 117, 0.1);
+    padding: 16px 24px;
 }
 
 /* CTA Section */
 .features-cta {
     text-align: center;
-    padding: 60px 0;
-    margin-top: 32px;
+    padding: 80px 32px;
+    margin: 64px auto 0;
+    max-width: 800px;
+    background: rgba(255, 255, 255, 0.4);
+    backdrop-filter: blur(16px);
+    border: 1px solid rgba(107, 145, 117, 0.15);
+    border-radius: var(--dash-radius-xl, 1.5rem);
+    box-shadow: 0 8px 32px rgba(107, 145, 117, 0.1);
 }
 
 .features-cta h3 {
-    font-size: 1.75rem;
-    color: var(--dash-text);
-    margin: 0 0 12px;
+    font-size: 2rem;
+    color: var(--dash-text, #2d2d2d);
+    margin: 0 0 16px;
+    font-family: var(--dash-font-serif, 'Playfair Display', Georgia, serif);
+    font-weight: 600;
+    letter-spacing: -0.01em;
 }
 
 .features-cta p {
-    color: var(--dash-text-muted);
-    margin: 0 0 28px;
+    color: var(--dash-text-secondary, #6b6b6b);
+    margin: 0 0 32px;
+    font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
+    font-size: 1.05rem;
+    line-height: 1.6;
 }
 
 .cta-button {
     display: inline-flex;
     align-items: center;
     gap: 10px;
-    padding: 14px 28px;
-    background: linear-gradient(135deg, var(--dash-accent), var(--dash-accent-dark));
+    padding: 14px 32px;
+    background: linear-gradient(135deg, var(--dash-accent, #6b9175) 0%, var(--dash-accent-dark, #4a7c59) 100%);
     color: white;
     border: none;
-    border-radius: 12px;
-    font-size: 15px;
+    border-radius: var(--dash-radius-lg, 1rem);
+    font-size: 16px;
     font-weight: 600;
     cursor: pointer;
-    transition: all 0.2s ease;
+    transition: all var(--dash-transition-base, 250ms);
+    font-family: var(--dash-font-sans, 'DM Sans', sans-serif);
+    box-shadow: 0 4px 16px rgba(107, 145, 117, 0.25);
 }
 
 .cta-button:hover {
     transform: translateY(-2px);
-    box-shadow: 0 8px 24px rgba(106, 145, 117, 0.3);
+    box-shadow: 0 8px 24px rgba(107, 145, 117, 0.35);
 }
 
 /* Responsive */
 @media (max-width: 768px) {
+    .features-content {
+        padding: 100px 16px 60px;
+    }
+
     .features-hero h1 {
         font-size: 2.25rem;
     }
@@ -411,6 +561,10 @@
         grid-template-columns: 1fr;
     }
 
+    .features-flow {
+        padding: 32px 24px;
+    }
+
     .flow-diagram {
         flex-direction: column;
     }
@@ -422,6 +576,11 @@
     .section-header {
         flex-direction: column;
         align-items: flex-start;
+        padding: 0;
+    }
+
+    .features-cta {
+        padding: 48px 24px;
     }
 }
 

frontend/src/pages/Features.tsx

@@ -320,6 +320,7 @@ function Features() {
                         viewport={{ once: true }}
                     >
                         <h2>How Your Data Flows</h2>
+                        <p>Every piece of health information follows a carefully designed path through our intelligent systems</p>
                         <div className="flow-diagram">
                             <div className="flow-step">
                                 <div className="flow-icon">

frontend/src/pages/PhysicsTwin.css

@@ -49,6 +49,40 @@
   gap: var(--dash-spacing-lg);
 }
 
+/* Two cards side-by-side row: YouTube (left) + Explainability (right) */
+.physics-cards-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--dash-spacing-lg);
+  align-items: stretch;
+  margin-top: var(--dash-spacing-lg);
+}
+
+.physics-cards-row-item {
+  min-width: 0;
+  height: 100%;
+}
+
+.physics-cards-row-item > .dash-card {
+  height: 100%;
+  min-height: 480px;
+  max-height: 700px;
+  display: flex;
+  flex-direction: column;
+}
+
+.physics-cards-row-item > .dash-card .dash-card-body {
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: hidden;
+}
+
+@media (max-width: 768px) {
+  .physics-cards-row {
+    grid-template-columns: 1fr;
+  }
+}
+
 /* ------------------------------------------------------------------ */
 /* Twin card (left column)                                             */
 /* ------------------------------------------------------------------ */
@@ -299,6 +333,20 @@
 /* ------------------------------------------------------------------ */
 /* Explainability card                                                 */
 /* ------------------------------------------------------------------ */
+.physics-explainability-card {
+  display: flex;
+  flex-direction: column;
+}
+
+.physics-explainability-card .dash-card-body {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+}
+
 .physics-explainability-card .dash-card-title {
   display: flex;
   align-items: center;

frontend/src/pages/PhysicsTwin.tsx

@@ -24,7 +24,8 @@ import DashboardNavbar from '../components/dashboard/DashboardNavbar';
 import OrganTelemetryCard from '../components/physics/OrganTelemetryCard';
 import ExplainabilityCard from '../components/physics/ExplainabilityCard';
 import BodyImpactOverlay from '../components/physics/BodyImpactOverlay';
-import RecommendationsCard from '../components/physics/RecommendationsCard';
+import YouTubeRecommendationsCard from '../components/physics/YouTubeRecommendationsCard';
+import '../components/physics/YouTubeRecommendationsCard.css';
 import {
   getLatestSnapshot,
   submitMetrics,
@@ -242,6 +243,31 @@ function PhysicsTwin() {
     ? snapshot.organs[selectedOrgan]
     : null;
 
+  // Find worst performing organ for recommendations
+  const worstOrgan = useMemo(() => {
+    if (!snapshot?.organs) return null;
+    
+    let worst: { organ: string; score: number; result: OrganResult } | null = null;
+    
+    for (const [organKey, organData] of Object.entries(snapshot.organs)) {
+      // Skip if score is 100 (perfect health)
+      if (organData.score >= 100) continue;
+      
+      if (!worst || organData.score < worst.score) {
+        worst = { organ: organKey, score: organData.score, result: organData };
+      }
+    }
+    
+    return worst;
+  }, [snapshot]);
+
+  // Auto-select worst organ if nothing selected
+  useEffect(() => {
+    if (!selectedOrgan && worstOrgan) {
+      setSelectedOrgan(worstOrgan.organ);
+    }
+  }, [worstOrgan, selectedOrgan]);
+
   // Current metric value from telemetry
   const currentMetrics = telemetry.current?.metrics ?? snapshot?.raw_metrics ?? {};
 
@@ -602,15 +628,25 @@ function PhysicsTwin() {
                 organResult={selectedResult}
                 lastUpdated={telemetry.current?.timestamp ?? snapshot?.timestamp ?? null}
               />
+            </motion.div>
+          </div>
 
+          {/* Full-width two-column layout: YouTube (left) + Explainability (right) */}
+          <div className="physics-cards-row">
+            <div className="physics-cards-row-item">
+              <YouTubeRecommendationsCard
+                selectedOrgan={selectedOrgan}
+                organResult={selectedResult}
+                currentMetrics={currentMetrics}
+              />
+            </div>
+            <div className="physics-cards-row-item">
               <ExplainabilityCard
                 selectedOrgan={selectedOrgan}
                 organResult={selectedResult}
                 organLabel={selectedOrgan ? (ORGAN_LABELS[selectedOrgan] || selectedOrgan) : ''}
               />
-
-              <RecommendationsCard conditions={conditions} />
-            </motion.div>
+            </div>
           </div>
 
           {/* Data quality disclaimer */}

frontend/src/pages/ReportSummary.css

@@ -369,7 +369,9 @@
 
 /* Center Panel - Preview */
 .center-panel .panel-card {
-  min-height: 500px;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
 }
 
 .preview-panel {
@@ -409,6 +411,7 @@
 /* Preview Single */
 .preview-single {
   flex: 1;
+  min-height: 0;
   display: flex;
   flex-direction: column;
 }
@@ -435,8 +438,11 @@
 
 .preview-frame {
   flex: 1;
-  min-height: 400px;
+  min-height: 0;
   background: #f8f8f8;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
 }
 
 .preview-iframe {
@@ -444,6 +450,7 @@
   height: 100%;
   min-height: 500px;
   border: none;
+  flex: 1;
 }
 
 .preview-image {
@@ -455,8 +462,10 @@
 /* Preview Multi (Grid) */
 .preview-multi {
   flex: 1;
+  min-height: 0;
   display: flex;
   flex-direction: column;
+  overflow-y: auto;
 }
 
 .preview-multi-header {

frontend/src/services/openRouterService.ts

@@ -0,0 +1,154 @@
+/**
+ * OpenRouter Service
+ * Uses AI to generate YouTube video recommendations based on health metrics.
+ * NO YouTube API needed - generates video titles and search URLs directly.
+ */
+
+const OPENROUTER_API_KEY = import.meta.env.VITE_OPENROUTER_API_KEY || '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';
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1/chat/completions';
+
+export interface AbnormalMetric {
+  name: string;
+  value: number;
+  normalRange: string;
+  status: 'high' | 'low';
+}
+
+export interface VideoRecommendation {
+  title: string;
+  description: string;
+  url: string;
+  duration: string;
+}
+
+export async function generateVideoRecommendations(
+  organ: string,
+  abnormalMetrics: AbnormalMetric[]
+): Promise<VideoRecommendation[]> {
+  // Use fallback if API not configured
+  if (!OPENROUTER_API_KEY || OPENROUTER_API_KEY.includes('your_key')) {
+    console.warn('OpenRouter API key not configured, using fallback recommendations');
+    return generateFallbackRecommendations(organ, abnormalMetrics);
+  }
+
+  try {
+    const prompt = buildPrompt(organ, abnormalMetrics);
+
+    const response = await fetch(OPENROUTER_BASE_URL, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${OPENROUTER_API_KEY}`,
+        'Content-Type': 'application/json',
+        'HTTP-Referer': window.location.origin,
+        'X-Title': 'Lumea Health - Physics Twin',
+      },
+      body: JSON.stringify({
+        model: 'openai/gpt-4o-mini',
+        messages: [
+          {
+            role: 'system',
+            content: 'You are a health education expert. Generate 6 YouTube video recommendations with titles (max 60 chars), descriptions (max 100 chars), and search queries (5-8 words). Return ONLY valid JSON: {"videos":[{"title":"...","description":"...","searchQuery":"..."}]}',
+          },
+          {
+            role: 'user',
+            content: prompt,
+          },
+        ],
+        temperature: 0.8,
+        max_tokens: 1200,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`OpenRouter API error: ${response.status}`);
+    }
+
+    const data = await response.json();
+    const content = data.choices?.[0]?.message?.content?.trim() || '';
+
+    if (content) {
+      // Try to parse JSON response
+      const parsed = JSON.parse(content);
+      const videos = parsed.videos || [];
+      
+      if (Array.isArray(videos) && videos.length > 0) {
+        return videos.slice(0, 6).map((v: any, index: number) => ({
+          title: v.title || `${organ} Health Video ${index + 1}`,
+          description: v.description || 'Learn how to improve your health naturally',
+          url: `https://www.youtube.com/results?search_query=${encodeURIComponent(v.searchQuery || `${organ} health`)}`,
+          duration: estimateDuration(v.searchQuery || ''),
+        }));
+      }
+    }
+
+    return generateFallbackRecommendations(organ, abnormalMetrics);
+  } catch (error) {
+    console.error('OpenRouter recommendation generation failed:', error);
+    return generateFallbackRecommendations(organ, abnormalMetrics);
+  }
+}
+
+function buildPrompt(organ: string, abnormalMetrics: AbnormalMetric[]): string {
+  if (abnormalMetrics.length === 0) {
+    return `Generate 6 YouTube video recommendations for improving ${organ} health. Include titles about: natural remedies, diet tips, exercises, lifestyle changes, supplements, and prevention. Make titles engaging and search queries specific.`;
+  }
+
+  const issues = abnormalMetrics
+    .slice(0, 3)
+    .map(m => `${m.name} is ${m.status} (normal: ${m.normalRange})`)
+    .join(', ');
+
+  return `Generate 6 YouTube video recommendations for ${organ} health when ${issues}. Include: diet changes, exercises, supplements, stress management, sleep tips, and medical advice. Make titles specific and actionable.`;
+}
+
+function generateFallbackRecommendations(organ: string, abnormalMetrics: AbnormalMetric[]): VideoRecommendation[] {
+  const organLower = organ.toLowerCase();
+  const topIssue = abnormalMetrics[0]?.name.toLowerCase() || 'health';
+  
+  return [
+    {
+      title: `How to Improve ${organ} Health Naturally`,
+      description: 'Evidence-based tips for better organ function and overall wellness',
+      url: `https://www.youtube.com/results?search_query=improve+${organLower}+health+naturally`,
+      duration: '10-15 min',
+    },
+    {
+      title: `Best Foods for ${organ} Health`,
+      description: 'Nutritional guide for optimal function and disease prevention',
+      url: `https://www.youtube.com/results?search_query=best+foods+for+${organLower}`,
+      duration: '8-12 min',
+    },
+    {
+      title: `${organ} Function: What You Need to Know`,
+      description: 'Understanding how your organ works and signs of problems',
+      url: `https://www.youtube.com/results?search_query=${organLower}+function+explained`,
+      duration: '12-18 min',
+    },
+    {
+      title: `Exercises for ${organ} Health`,
+      description: 'Physical activities to support and improve organ function',
+      url: `https://www.youtube.com/results?search_query=exercises+for+${organLower}+health`,
+      duration: '15-20 min',
+    },
+    {
+      title: `Managing ${topIssue} for Better ${organ} Health`,
+      description: 'Targeted strategies for your specific health concerns',
+      url: `https://www.youtube.com/results?search_query=${topIssue}+${organLower}+health`,
+      duration: '10-15 min',
+    },
+    {
+      title: `${organ} Health Supplements and Remedies`,
+      description: 'Natural support options and what science says',
+      url: `https://www.youtube.com/results?search_query=${organLower}+supplements+remedies`,
+      duration: '8-12 min',
+    },
+  ];
+}
+
+function estimateDuration(searchQuery: string): string {
+  // Estimate duration based on query complexity
+  const words = searchQuery.split(' ').length;
+  if (words <= 3) return '5-10 min';
+  if (words <= 5) return '8-15 min';
+  return '10-20 min';
+}

frontend/src/services/youtubeService.ts

@@ -0,0 +1,111 @@
+/**
+ * YouTube Data API v3 Service
+ * Fetches real video data with thumbnails
+ */
+
+export interface YouTubeVideo {
+  videoId: string;
+  title: string;
+  channelTitle: string;
+  publishedAt: string;
+  thumbnailUrl: string;
+  url: string;
+  description: string;
+}
+
+interface YouTubeSearchResponse {
+  items: Array<{
+    id: { videoId: string };
+    snippet: {
+      title: string;
+      channelTitle: string;
+      publishedAt: string;
+      thumbnails: {
+        default?: { url: string };
+        medium?: { url: string };
+        high?: { url: string };
+      };
+      description: string;
+    };
+  }>;
+}
+
+const YOUTUBE_API_KEY = import.meta.env.VITE_YOUTUBE_API_KEY;
+const YOUTUBE_API_BASE = 'https://www.googleapis.com/youtube/v3';
+
+export async function searchYouTubeVideos(query: string): Promise<YouTubeVideo[]> {
+  if (!YOUTUBE_API_KEY) {
+    console.warn('YouTube API key not configured');
+    // Return placeholder data that opens YouTube search
+    return [{
+      videoId: 'placeholder',
+      title: query,
+      channelTitle: 'Search YouTube',
+      publishedAt: new Date().toISOString(),
+      thumbnailUrl: '',
+      url: `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`,
+      description: 'Click to search YouTube for this topic',
+    }];
+  }
+
+  try {
+    const params = new URLSearchParams({
+      part: 'snippet',
+      type: 'video',
+      maxResults: '6',
+      videoEmbeddable: 'true',
+      safeSearch: 'strict',
+      relevanceLanguage: 'en',
+      q: query,
+      key: YOUTUBE_API_KEY,
+    });
+
+    const response = await fetch(`${YOUTUBE_API_BASE}/search?${params}`);
+    
+    if (!response.ok) {
+      throw new Error(`YouTube API error: ${response.statusText}`);
+    }
+
+    const data: YouTubeSearchResponse = await response.json();
+
+    return data.items.map(item => {
+      const thumbnails = item.snippet.thumbnails;
+      const thumbnailUrl = 
+        thumbnails.medium?.url || 
+        thumbnails.high?.url || 
+        thumbnails.default?.url || 
+        '';
+
+      return {
+        videoId: item.id.videoId,
+        title: item.snippet.title,
+        channelTitle: item.snippet.channelTitle,
+        publishedAt: item.snippet.publishedAt,
+        thumbnailUrl,
+        url: `https://www.youtube.com/watch?v=${item.id.videoId}`,
+        description: item.snippet.description,
+      };
+    });
+  } catch (error) {
+    console.error('Error fetching YouTube videos:', error);
+    throw error;
+  }
+}
+
+export function formatTimeAgo(dateString: string): string {
+  const date = new Date(dateString);
+  const now = new Date();
+  const seconds = Math.floor((now.getTime() - date.getTime()) / 1000);
+
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months}mo ago`;
+  const years = Math.floor(months / 12);
+  return `${years}y ago`;
+}