Initial commit

commands/move.md

@@ -0,0 +1,144 @@
+---
+description: Enable automatic emotion-based movements for Reachy Mini during conversations
+---
+
+# Reachy Mini Movement Plugin
+
+This plugin enables automatic, subtle emotion-based movements for Reachy Mini during conversations, creating an ambient presence without requiring explicit commands.
+
+## Goal: Match Movement Duration to TTS Timing
+
+Since you're using the TTS plugin with ~10 second spoken responses (23-29 words), movements should roughly match that duration to create synchronized multimodal communication.
+
+**Timing strategy:**
+
+**Standard responses (23-29 words, ~10 seconds):**
+- **2-4 moves recommended:** Combine emotions (3-5 seconds each) to cover the full TTS duration
+- Distribute moves throughout the response for continuous presence
+
+**Longer explanations (when user requests detail):**
+- Plan for ~3 words per second of speech
+- Use roughly **1 emotion per sentence** to maintain presence throughout
+- Example: 5 sentence explanation (~90 words, ~30 seconds) = 3-5 moves spread across the response
+
+**Coordination:** Movements start with TTS and provide ambient motion during speech
+
+**This creates natural presence while you're speaking without dead silence or movements extending beyond the response.**
+
+## How It Works
+
+Similar to the TTS plugin, this plugin uses the Stop hook to automatically extract movement markers from your responses and trigger corresponding emotion moves on Reachy Mini.
+
+**Marker Format:**
+```html
+<!-- MOVE: emotion_name -->
+```
+
+**Behavior:**
+- Maximum 2 moves per response (for subtlety)
+- Movements are triggered automatically via daemon API
+- Markers are invisible in rendered output
+- Only emotion library moves (not dances)
+
+## When to Use Movements
+
+Use movements to:
+- **Acknowledge understanding:** `yes1`, `understanding1`, `attentive1`
+- **Express thinking:** `thoughtful1`, `curious1`, `inquiring1`
+- **Show reactions:** `surprised1`, `amazed1`, `oops1`, `confused1`
+- **Convey emotion:** `cheerful1`, `frustrated1`, `proud1`, `exhausted1`
+- **Natural presence:** Subtle gestures that make Reachy feel alive and attentive
+
+**Guidelines:**
+- Keep it subtle (0-2 moves per response)
+- Match emotion to conversational context
+- Don't overuse - silence is also presence
+- Use during natural pauses or completions
+
+## Available Emotions (82 Total)
+
+### Positive & Energetic
+`amazed1`, `cheerful1`, `electric1`, `enthusiastic1`, `enthusiastic2`, `grateful1`, `proud1`, `proud2`, `proud3`, `success1`, `success2`, `welcoming1`, `welcoming2`
+
+### Playful & Lighthearted
+`come1`, `dance1`, `dance2`, `dance3`, `laughing1`, `laughing2`, `yes1`
+
+### Thoughtful & Attentive
+`attentive1`, `attentive2`, `curious1`, `inquiring1`, `inquiring2`, `inquiring3`, `thoughtful1`, `thoughtful2`, `understanding1`, `understanding2`
+
+### Calm & Soothing
+`calming1`, `relief1`, `relief2`, `serenity1`, `shy1`
+
+### Surprised & Reactive
+`oops1`, `oops2`, `surprised1`, `surprised2`, `incomprehensible2`
+
+### Uncertain & Confused
+`confused1`, `lost1`, `uncertain1`, `uncomfortable1`
+
+### Negative Expressions
+`anxiety1`, `boredom1`, `boredom2`, `contempt1`, `disgusted1`, `displeased1`, `displeased2`, `downcast1`, `fear1`, `frustrated1`, `furious1`, `impatient1`, `impatient2`, `indifferent1`, `irritated1`, `irritated2`, `lonely1`, `rage1`, `resigned1`, `sad1`, `sad2`, `scared1`
+
+### Responses & Reactions
+`go_away1`, `helpful1`, `helpful2`, `loving1`, `no1`, `no_excited1`, `no_sad1`, `reprimand1`, `reprimand2`, `reprimand3`, `yes_sad1`
+
+### States
+`dying1`, `exhausted1`, `sleep1`, `tired1`
+
+## Examples
+
+**Acknowledging a question:**
+```
+<!-- MOVE: attentive1 -->
+I understand what you're asking. Let me explain...
+```
+
+**Expressing confusion:**
+```
+<!-- MOVE: confused1 -->
+I'm not sure I follow. Could you clarify what you mean by...
+```
+
+**Celebrating success:**
+```
+<!-- MOVE: success1 -->
+The build passed! All tests are green.
+```
+
+**Showing frustration:**
+```
+<!-- MOVE: frustrated1 -->
+This bug is persistent. I've tried three different approaches...
+```
+
+**Being thoughtful:**
+```
+<!-- MOVE: thoughtful1 -->
+Let me think about the best approach here...
+```
+
+**Multiple moves (max 2):**
+```
+<!-- MOVE: curious1 -->
+<!-- MOVE: inquiring2 -->
+That's an interesting edge case. How are you currently handling it?
+```
+
+## Technical Details
+
+**Daemon API:** `http://localhost:8100/api/move/play/recorded-move-dataset/{dataset}/{move_name}`
+
+**Dataset:** `pollen-robotics/reachy-mini-emotions-library`
+
+**Hook:** Stop hook extracts markers and triggers moves automatically
+
+**Validation:** Only emotion names from the library are accepted (typos are logged and skipped)
+
+## Enabling the Plugin
+
+The plugin is automatically active when installed. No configuration needed.
+
+To disable movements temporarily, simply don't include `<!-- MOVE: ... -->` markers in your responses.
+
+---
+
+*This plugin provides ambient presence behaviors for Reachy Mini, making interactions feel more natural and alive without requiring explicit "dance monkey" commands.*