# Voice Command Shortcuts - User Guide

## 🚀 **What Are Voice Shortcuts?**

Voice shortcuts are quick, instant commands  that bypass the AI and give you immediate responses for common requests. No waiting for Gemini API - just speak and get instant results!

---

## ⚡ Available Commands

### ⏰ **Timer & Break Commands**

| Say This | What Happens |
|----------|--------------|
| "Quick break" or "Short break" | Instant 5-minute break timer |
| "Long break" or "Longer break" | Instant 15-minute break timer |
| "Pomodoro" or "Work timer" | Instant 25-minute focus timer |

**Examples**:
- "Quick break" → ⏱️ 5min timer starts
- "Pomodoro" → ⏱️ 25min focus session

---

### 🍽️ **Food Commands**

| Say This | What Happens |
|----------|--------------|
| "Lunch" or "Lunch ideas" | Quick lunch suggestions |
| "Snack" or "Hungry" | Healthy snack ideas |
| "Food" | Meal suggestions |

**Examples**:
- "Lunch" → 🥗 "Try a protein bowl with grains, veggies, and lean protein"
- "Snack" → 🍎 "Try nuts, fruit, yogurt, or a protein bar"

---

### ⚡ **Energy Level Commands**

| Say This | What Happens |
|----------|--------------|
| "Energy low" or "I'm tired" | Sets energy to Low |
| "Energy high" or "I'm energized" | Sets energy to High |

**Examples**:
- "I'm tired" → Energy set to Low ⬇️  
- "Energy high" → Energy set to High ⬆️

--- ###🧘 **Self-Care Commands**

| Say This | What Happens |
|----------|--------------|
| "Need break" or "Overwhelmed" | Self-care suggestions |
| "Stressed" | Calming activity ideas |
| "Stretch" or "Move" | Movement suggestions |

**Examples**:
- "Overwhelmed" → 🧘 "Try deep breathing for 2 minutes, a short walk, or step away from screens"
- "Stretch" → 🤸 "Try neck rolls, shoulder shrugs, standing and reaching"

---

### ❓ **Help Command**

| Say This | What Happens |
|----------|--------------|
| "Help" or "Commands" | Shows all available shortcuts |

**Example**:
- "Help" → 📋 List of all voice commands

---

## 🎯 How It Works

### 1. **Instant Response**
```
You say: "Quick break"
    ↓
⚡ Command detected (< 300ms)
    ↓
✅ "Starting a 5-minute break timer for you."
```

**No AI call needed!** = Instant response

### 2. **Fallback to AI**
```
You say: "Should I work on project A or B?"
    ↓
❌ No command match
    ↓
🤖 Gemini AI analyzes your question
    ↓
💡 Personalized suggestion
```

If your question doesn't match a shortcut, it goes to Gemini for a full AI response.

---

## ✨ Benefits

### ⚡ **Speed**
- **Shortcuts**: < 300ms response  
- **AI calls**: 1-3 seconds

### 🎯 **Reliability**
- Works offline (shortcuts only)
- No API rate limits for shortcuts
- Consistent responses

### 😊 **Convenience**
- Common actions in 1-2 words
- Natural command variations ("break", "quick break", "short break" all work)
- No need to remember exact phrasing

---

## 📝 Examples in Action

### Scenario 1: Need a Quick Break
```
🗣️ User: "Break"
⚡ System: Quick command detected!
💬 Ayuel: "Starting a 5-minute break timer for you."
⏱️ Timer: 5:00 starts counting down
```

### Scenario 2: Lunch Time
```
🗣️ User: "Lunch"
⚡ System: Quick command detected!
💬 Ayuel: "For a balanced lunch, try a protein bowl with grains, veggies, and lean protein."
📝 Actions: [More ideas] [Done]
```

### Scenario 3: Feeling Overwhelmed
```
🗣️ User: "Stressed"
⚡ System: Quick command detected!
💬 Ayuel: "Try: deep breathing for 2 minutes, a short walk, or step away from screens."
⏱️ Action: [Start 5m break] [Other ideas]
```

### Scenario 4: Complex Question (Uses AI)
```
🗣️ User: "Should I go to the gym or work late?"
❌ No shortcut match
🤖 Gemini AI thinking...
💬 Ayuel: "Given your Low energy, prioritize rest. Maybe a light walk instead of gym?"
```

---

## 🔍 Pattern Matching

Commands are flexible! They match variations:

### Timer Commands
- ✅ "quick break" → 5min
- ✅ "short break" → 5min
- ✅ "break 5" → 5min
- ✅ "5 minute break" → 5min
- ✅ "5 min break" → 5min

### Food Commands
- ✅ "lunch" → suggestions
- ✅ "lunch ideas" → suggestions
- ✅ "what should i eat" → suggestions
- ✅ "food" → suggestions

### Energy Commands
- ✅ "energy low" → set to Low
- ✅ "I'm tired" → set to Low
- ✅ "Im tired" → set to Low
- ✅ "feeling low energy" → set to Low

---

## 📊 Command Priority

The system checks commands in this order:

1. **Quick Break** (most specific timers)
2. **Long Break**
3. **Pomodoro**
4. **Lunch/Snack** (food)
5. **Energy Settings**
6. **Self-care**
7. **Help**
8. **Movement**

If no match → **Gemini AI** processes the request

---

## 💡 Pro Tips

### 1. **Be Concise for Shortcuts**
- ✅ "Quick break" → Instant
- ❌ "I think I need a quick break maybe" → Goes to AI

### 2. **Learn the Commands**
Say **"Help"** to see the full list anytime!

### 3. **Combine with AI**
- Use shortcuts for common tasks (faster)
- Use natural language for complex decisions (smarter)

### 4. **Check the Console**
In browser DevTools, you'll see:
```
🚀 Quick command detected: quick_break
```

---

## 🎨 Visual Indicators

### Shortcut Detected
```
🎤 Listening → "Quick break"
    ↓
💭 Thinking (< 300ms)
    ↓
🔊 Speaking + Response Card
    ↓
⏱️ Timer starts
```

### AI Processing
```
🎤 Listening → "Should I work out?"
    ↓
💭 Thinking (1-3s with spinner)
    ↓
🔊 Speaking + Response Card
```

**Notice**: Shortcuts show "Thinking" briefly, AI takes longer

---

## 🛠️ Technical Details

### Command Detection
```dart
// Check transcript against patterns
final command = commandsService.detectCommand(transcript);

if (command != null) {
  // Execute instantly
  final response = command.execute(transcript);
  // Show response
} else {
  // Call Gemini API
  final response = await gemini.getSuggestion(...);
}
```

### Pattern Matching
```dart
RegExp(r'^quick\s*break$')  // Matches "quick break", "quick  break"
RegExp(r'^lunch(\\s*ideas?)?$')  // Matches "lunch", "lunch idea", "lunch ideas"
```

---

## 📈 Performance Comparison

| Type | Response Time | API Cost | Offline? |
|------|--------------|----------|----------|
| **Voice Shortcut** | < 300ms | Free | ✅ Yes |
| **Gemini AI** | 1-3 seconds | Paid | ❌ No |

Use shortcuts whenever possible for:
- ⚡ Faster interactions
- 💰 Lower costs
- 📶 Offline capability

---

## 🚀 Future Enhancements

Coming soon to voice shortcuts:

1. **Custom Shortcuts** - Add your own commands
2. **Smart Learning** - System learns your common phrases
3. **Context Awareness** - "Another break" → Knows you just took one
4. **Voice Parameters** - "15 minute break" → Dynamic timer
5. **Chaining** - "Quick break then lunch ideas"

---

## 🆘 Troubleshooting

### Command Not Working?

**Problem**: Said "quick break" but got AI response instead

**Solutions**:
1. Speak clearly and concisely
2. Check for exact matches (case-insensitive)
3. Try alternative phrasing: "break", "short break"
4. Say "help" to see available commands

### Want to See All Commands?

Just say: **"Help"** or **"Commands"**

### Command Too Slow?

Shortcuts should be < 300ms. If slow:
- Check internet connection (for AI fallback detection)
- Check browser console for errors
- Restart the app

---

## 📝 Command Cheat Sheet (Print This!)

```
TIMERS:
  quick break → 5min
  long break → 15min
  pomodoro → 25min

FOOD:
  lunch → meal ideas
  snack → quick snack ideas

ENERGY:
  energy low → set to Low
  energy high → set to High
  I'm tired → set to Low

SELF-CARE:
  need break → self-care tips
  stressed → calming activities
  stretch → movement ideas

HELP:
  help → show all commands
```

---

## 🎉 Summary

Voice shortcuts make Hey Ayuel **10x faster** for common tasks!

**Remember**:
- 🗣️ Speak concisely for shortcuts
- 💬 Speak naturally for AI help
- ❓ Say "help" to see all commands
- ⚡ Shortcuts = instant, AI = personalized

**Try it now!** Say "Quick break" and experience the speed! 🚀
