Move sleep scoring doc to features section

Added new 'Features' section in docs. Renamed 'sleep-scoring.md' from 'getting-started' to 'features' and updated mkdocs.yml navigation to reflect this change.

docs/features/sleep-scoring.md

@@ -0,0 +1,288 @@
+# Sleep Scoring Guide
+
+Endurain uses a sleep scoring system to help you understand the quality of your sleep. This guide explains how your sleep is evaluated and what the scores mean.
+
+## What is Sleep Scoring?
+
+Sleep scoring is like a report card for your sleep. The system analyzes your sleep data and gives you:
+
+- **An overall sleep score** (0-100 points)
+- **Individual component scores** with quality labels
+- **Easy-to-understand ratings**: Excellent, Good, Fair, or Poor
+
+## How Are Scores Calculated?
+
+### Overall Sleep Score (0-100)
+
+Your overall sleep score combines several important factors:
+
+- **30%** - How long you slept (Duration)
+- **40%** - How well you slept (Quality)
+- **10%** - How many times you woke up
+- **20%** - Your stress levels during sleep
+
+**What the scores mean:**
+
+- **90-100**: Excellent sleep! You're well-rested and recharged
+- **70-89**: Good sleep. You got decent rest with room for improvement
+- **50-69**: Fair sleep. You might feel somewhat rested but could do better
+- **0-49**: Poor sleep. You likely feel tired and need better rest
+
+---
+
+## Understanding Each Score Component
+
+### 1. Sleep Duration Score
+
+**What it measures:** How many hours you slept
+
+**Why it matters:** Your body needs enough time to go through all sleep stages and recover properly.
+
+**Scoring guidelines:**
+
+| Hours of Sleep | Score | Rating |
+|----------------|-------|--------|
+| 7-9 hours | 90-100 | **EXCELLENT** - Perfect amount! |
+| 6-7 hours | 70-89 | **GOOD** - A bit short but okay |
+| 9-10 hours | 70-89 | **GOOD** - A bit long but okay |
+| 5-6 hours | 50-69 | **FAIR** - Not enough rest |
+| 10-11 hours | 50-69 | **FAIR** - Possibly oversleeping |
+| Less than 5 hours | 0-49 | **POOR** - Seriously insufficient |
+| More than 11 hours | 0-49 | **POOR** - Too much sleep |
+
+**The sweet spot:** 7-9 hours, with 8 hours being ideal for most adults.
+
+---
+
+### 2. Sleep Quality Score
+
+**What it measures:** How your sleep was distributed across different sleep stages
+
+**Why it matters:** Quality sleep isn't just about quantity - your brain and body need the right mix of sleep stages to fully recover.
+
+**The four sleep stages:**
+
+1. **Light Sleep** - Transition period, your body starts to relax
+2. **Deep Sleep** - Body repairs muscles and tissues, strengthens immune system
+3. **REM Sleep** - Brain processes memories and emotions, vivid dreams occur
+4. **Awake** - Brief wakeful moments (some are normal!)
+
+**Optimal percentages:**
+
+| Sleep Stage | Ideal Range | Why It Matters |
+|-------------|-------------|----------------|
+| **Deep Sleep** | 13-23% (peak: 18%) | Physical recovery and healing |
+| **REM Sleep** | 20-25% (peak: 22.5%) | Memory and emotional processing |
+| **Light Sleep** | 45-55% (peak: 50%) | Transition between stages |
+| **Awake Time** | Less than 5% | Normal brief awakenings |
+
+**How it's scored:**
+
+- Each sleep stage gets its own score based on how close you are to the optimal percentage
+- The scores are combined with these weights:
+  - Deep sleep: 25%
+  - REM sleep: 30% (most important for mental recovery!)
+  - Light sleep: 25%
+  - Awake time: 20% (penalty applied)
+
+---
+
+### 3. Awake Count Score
+
+**What it measures:** How many times you woke up during the night
+
+**Why it matters:** Frequent awakenings disrupt your sleep cycles and prevent deep, restorative sleep.
+
+**Scoring:**
+
+| Awakenings | Score | Rating | What It Means |
+|------------|-------|--------|---------------|
+| 0-1 times | 90-100 | **EXCELLENT** | Uninterrupted, restorative sleep |
+| 2-3 times | 70-89 | **GOOD** | Some interruptions but still decent |
+| 4-5 times | 50-69 | **FAIR** | Sleep continuity affected |
+| 6+ times | 0-49 | **POOR** | Very fragmented sleep |
+
+**Note:** It's normal to wake up briefly 1-2 times per night. You might not even remember them!
+
+---
+
+### 4. REM Sleep Percentage Score
+
+**What it measures:** What percentage of your sleep was REM (Rapid Eye Movement) sleep
+
+**Why it matters:** REM sleep is when your brain consolidates memories, processes emotions, and boosts creativity. It's essential for mental health and learning.
+
+**Optimal range:** 20-25% of total sleep time (about 1.5-2 hours for 8 hours of sleep)
+
+**What different levels mean:**
+
+- **Too low (<20%)**: May affect memory, mood, and cognitive function
+- **Optimal (20-25%)**: Brain is fully processing and recovering
+- **Too high (>25%)**: Unusual and may indicate sleep disorders
+
+---
+
+### 5. Deep Sleep Percentage Score
+
+**What it measures:** What percentage of your sleep was deep sleep
+
+**Why it matters:** Deep sleep is when your body does most of its physical repair - healing muscles, strengthening bones, and boosting your immune system.
+
+**Optimal range:** 13-23% of total sleep time (about 1-2 hours for 8 hours of sleep)
+
+**What different levels mean:**
+
+- **Too low (<13%)**: Less physical recovery, may feel physically tired
+- **Optimal (13-23%)**: Body is fully recovering and strengthening
+- **Too high (>23%)**: Rare, but may indicate sleep debt recovery
+
+**Did you know?** Deep sleep decreases naturally as you age, which is normal!
+
+---
+
+### 6. Light Sleep Percentage Score
+
+**What it measures:** What percentage of your sleep was light sleep
+
+**Why it matters:** Light sleep serves as a transition between sleep stages and makes up the largest portion of your sleep.
+
+**Optimal range:** 45-55% of total sleep time (about 3.5-4.5 hours for 8 hours of sleep)
+
+**What different levels mean:**
+
+- **Too low (<45%)**: You may be spending too much time in other stages
+- **Optimal (45-55%)**: Healthy balance of sleep stages
+- **Too high (>55%)**: May not be getting enough deep or REM sleep
+
+---
+
+### 7. Sleep Stress Score
+
+**What it measures:** Your average stress level during sleep and how restless you were
+
+**Why it matters:** High stress during sleep indicates your body isn't fully relaxing, which affects recovery quality.
+
+**Stress levels explained** (based on Garmin scale):
+
+- **0-25**: Rest state - fully relaxed
+- **26-50**: Low stress - mostly relaxed
+- **51-75**: Medium stress - moderately elevated
+- **76-100**: High stress - not relaxing properly
+
+**Scoring:**
+
+| Stress Level | Base Score | Rating |
+|--------------|-----------|--------|
+| 0-25 (Rest) | 100 | **EXCELLENT** |
+| 26-50 (Low) | 70-90 | **GOOD** |
+| 51-75 (Medium) | 50-70 | **FAIR** |
+| 76-100 (High) | 0-50 | **POOR** |
+
+**Restless moments penalty:** Each restless moment during sleep reduces your score by 2-3 points.
+
+---
+
+## Tips for Better Sleep Scores
+
+### To Improve Duration Score:
+- Aim for 7-9 hours of sleep per night
+- Keep a consistent sleep schedule, even on weekends. Be consistent on the time you go to bed and awake not only the sleep hours
+- Go to bed when you're tired, not too early or late
+
+### To Improve Quality Score:
+- Create a dark, quiet, cool sleeping environment
+- Avoid screens and high intensity brain tasks 1 hour before bedtime (blue light disrupts sleep)
+- Avoid caffeine 6 hours before bed
+- Exercise regularly, but not right before bed
+
+### To Reduce Awakenings:
+- Limit fluid intake 2 hours before bedtime
+- Keep your bedroom cool (60-67°F / 15-19°C is ideal)
+- Use white noise or earplugs if needed
+- Address any underlying sleep disorders with a doctor
+
+### To Reduce Sleep Stress:
+- Practice relaxation techniques before bed (meditation, deep breathing)
+- Keep a regular exercise routine during the day
+- Avoid stressful activities or conversations before bedtime
+- Consider journaling to clear your mind before sleep
+
+---
+
+## Frequently Asked Questions
+
+### Q: Why is my score low even though I slept 8 hours?
+
+**A:** Duration is only 30% of your overall score. You might have had poor quality sleep, many awakenings, or high stress levels. Check your individual component scores to see what needs improvement.
+
+### Q: Is it bad if my scores vary day to day?
+
+**A:** Some variation is normal! Factors like stress, exercise, diet, and life events affect your sleep. Look for trends over weeks rather than individual nights.
+
+### Q: What's more important - duration or quality?
+
+**A:** Both matter! Quality is weighted slightly higher (40% vs 30%) because you can sleep for 10 hours but still feel tired if the quality is poor. Aim for both good duration AND quality.
+
+### Q: My REM/Deep sleep percentage seems low. Is that bad?
+
+**A:** Not necessarily. These percentages are averages based on research. Individual needs vary by age, genetics, and lifestyle. If you feel rested and energetic, your sleep is probably fine!
+
+### Q: Can I compare my scores with friends?
+
+**A:** While you can, remember that everyone's sleep needs are different. Focus on improving YOUR scores over time rather than comparing with others.
+
+### Q: What if I have a sleep disorder?
+
+**A:** These scores are educational tools, not medical diagnoses. If you consistently get poor scores or feel tired despite good scores, consult a healthcare professional or sleep specialist.
+
+---
+
+## Understanding Your Data
+
+### When are scores calculated?
+
+Scores are automatically calculated when you:
+
+- Create a new sleep record
+- Update an existing sleep record
+- Important: If sleep data is imported from Garmin Connect, no calculations are made. Garmin Connect data is used
+
+The system recalculates all scores to ensure they reflect your current data.
+
+### What data is needed?
+
+For the most accurate scores, provide:
+
+- ✅ Sleep start and end times
+- ✅ Total sleep duration
+- ✅ Sleep stage breakdowns (deep, light, REM, awake)
+- ✅ Number of awakenings
+- ✅ Stress levels (optional but recommended)
+
+**Partial data:** Even with incomplete data, the system will calculate scores for the metrics you provide. Missing metrics won't break the scoring system.
+
+---
+
+## Technical Details
+
+For developers and technically-minded users:
+
+- **Algorithm**: Based on sleep research (provided by Claude Sonnet 4.5 and double checked by me)
+- **Scoring method**: Weighted average of normalized component scores
+- **Data source**: Compatible with Garmin Connect and manual entry
+- **Score range**: All scores normalized to 0-100 scale
+- **Labels**: Threshold-based categorization (90+=Excellent, 70+=Good, 50+=Fair, <50=Poor)
+
+---
+
+## Summary
+
+Your sleep scores provide valuable insights into your rest quality. By understanding what each score means and following the improvement tips, you can work towards better, more restorative sleep.
+
+**Remember:**
+- 🎯 Focus on trends, not single nights
+- 💪 Small improvements add up over time
+- 😴 Consistency is key to good sleep
+- 🩺 Consult a doctor for persistent sleep issues
+
+Sweet dreams and happy tracking! 🌙✨