Organize documentation: Move all .md files to readmes/ directory

readmes/AUTONOMOUS_V2_DEBUG_GUIDE.md

@@ -0,0 +1,284 @@
+# Autonomous V2 Debug Guide
+
+Quick reference for debugging the Autonomous V2 decision system.
+
+---
+
+## 🔧 Enable Debug Mode
+
+### Option 1: Environment Variable (Persistent)
+
+Add to your `.env` file or `docker-compose.yml`:
+
+```bash
+AUTONOMOUS_DEBUG=true
+```
+
+### Option 2: Terminal (Temporary)
+
+```bash
+export AUTONOMOUS_DEBUG=true
+python bot.py
+```
+
+### Option 3: Code (Development)
+
+In `bot/globals.py`:
+```python
+AUTONOMOUS_DEBUG = True  # Force enable
+```
+
+---
+
+## 📊 What You'll See
+
+### Normal Mode (Debug Off)
+```
+🤖 [V2] Autonomous engine decided to: join_conversation for server 123456
+✅ [V2] Autonomous tick queued for server 123456
+```
+
+### Debug Mode (Debug On)
+```
+🔍 [V2 Debug] Decision Check for Guild 123456
+   Mood: bubbly (energy=0.90, sociability=0.95, impulsiveness=0.80)
+   Momentum: 0.75
+   Messages (5min/1hr): 15/42
+   Messages since appearance: 8
+   Time since last action: 450s
+   Active activities: 2
+   
+   [Join Conv] momentum=0.75 > 0.63? True
+   [Join Conv] messages=8 >= 5? True
+   [Join Conv] cooldown=450s > 300s? True
+   [Join Conv] impulsive roll? True | Result: True
+   
+✅ [V2 Debug] DECISION: join_conversation
+
+🤖 [V2] Autonomous engine decided to: join_conversation for server 123456
+✅ [V2] Autonomous tick queued for server 123456
+```
+
+---
+
+## 🎯 Understanding the Output
+
+### Decision Types Checked (in order)
+
+1. **[Join Conv]** - High momentum conversation
+   - Shows: momentum threshold, message count, cooldown, impulsiveness roll
+   
+2. **[Engage]** - User started new activity
+   - Shows: active activities list, cooldown, sociability × impulsiveness threshold
+   
+3. **[FOMO]** - Lots of messages without Miku
+   - Shows: message count vs threshold, momentum, cooldown
+   
+4. **[Silence]** - Break long silence
+   - Shows: messages last hour, time threshold, energy roll
+   
+5. **[Share]** - Share tweet/content
+   - Shows: quiet check, cooldown, energy threshold, mood appropriateness
+
+### Context Signals
+
+```
+Mood: bubbly (energy=0.90, sociability=0.95, impulsiveness=0.80)
+```
+- Current mood and personality profile values
+
+```
+Momentum: 0.75
+```
+- Conversation momentum (0-1 scale)
+- Higher = more active chat
+
+```
+Messages (5min/1hr): 15/42
+```
+- Recent activity levels
+- First number: last 5 minutes
+- Second number: last hour
+
+```
+Messages since appearance: 8
+```
+- How many messages since Miku last spoke
+- Capped at 100 to prevent FOMO spam
+
+```
+Time since last action: 450s
+```
+- Seconds since Miku's last autonomous action
+- Used for cooldown checks
+
+```
+Active activities: 2
+```
+- Number of user activities being tracked
+- Max 5, auto-expire after 1 hour
+
+---
+
+## 🐛 Common Debugging Scenarios
+
+### "Why isn't Miku joining the conversation?"
+
+Enable debug mode and look for:
+```
+[Join Conv] momentum=0.45 > 0.63? False
+```
+- Momentum too low for current mood
+- Try waiting for more messages or changing to more social mood
+
+### "Why is Miku so chatty?"
+
+Check the mood:
+```
+Mood: excited (energy=0.95, sociability=0.90, impulsiveness=0.90)
+```
+- High sociability = lower thresholds = more likely to act
+- Change to "shy" or "serious" for less activity
+
+### "Why isn't Miku reacting to user activities?"
+
+Look for:
+```
+Active activities: 0
+```
+- No activities being tracked
+- Check that presence intents are enabled
+- Verify users are actually starting games/activities
+
+### "Miku isn't breaking silence"
+
+Check:
+```
+[Silence] msgs_last_hour=42 < 5? False
+```
+- Channel isn't quiet enough
+- Energy roll might have failed (random)
+
+### "No actions happening at all"
+
+Check:
+```
+💤 [V2 Debug] Mood is 'asleep' - no action taken
+```
+- Miku is asleep! Change mood to wake her up
+
+---
+
+## 📈 Monitoring Tips
+
+### Watch for Decay Task
+Every 15 minutes you should see:
+```
+🧹 [V2] Decay task completed (iteration #4, uptime: 1.0h)
+   └─ Processed 3 servers
+```
+
+If you don't see this, the decay task might not be running.
+
+### Track Activity Events
+When users do things:
+```
+👤 [V2] Username status changed: online → idle
+🎮 [V2] Username started activity: Genshin Impact
+```
+
+If you never see these, presence tracking isn't working.
+
+### Decision Frequency
+In an active server, you should see decision checks:
+- Every time a message is sent (but most will be "None")
+- Every 10-15 minutes (scheduler tick)
+
+---
+
+## 🔍 Performance Impact
+
+**Debug Mode OFF** (Production):
+- Minimal overhead
+- Only logs when actions are taken
+- ~99% of checks are silent
+
+**Debug Mode ON** (Development):
+- Verbose logging on every decision check
+- Can generate lots of output in active servers
+- Useful for tuning but not for production
+
+**Recommendation**: Only enable debug mode when actively troubleshooting.
+
+---
+
+## 🎛️ Tuning Thresholds
+
+If you want to adjust behavior, edit `bot/utils/autonomous_engine.py`:
+
+### Make Miku More Active
+```python
+# In _should_join_conversation
+base_threshold = 0.5  # Lower from 0.6
+```
+
+### Make Miku Less Active
+```python
+# In _should_join_conversation
+base_threshold = 0.7  # Raise from 0.6
+```
+
+### Change FOMO Sensitivity
+```python
+# In _should_respond_to_fomo
+fomo_threshold = 30 * (2.0 - profile["sociability"])  # Raise from 25
+```
+
+### Adjust Silence Breaking
+```python
+# In _should_break_silence
+min_silence = 2400 * (2.0 - profile["energy"])  # Raise from 1800 (30 min to 40 min)
+```
+
+**Note**: After tuning, monitor with debug mode to verify the changes work as expected.
+
+---
+
+## 📞 Quick Reference Commands
+
+```bash
+# Enable debug for current session
+export AUTONOMOUS_DEBUG=true
+
+# Disable debug
+export AUTONOMOUS_DEBUG=false
+unset AUTONOMOUS_DEBUG
+
+# Check if debug is enabled
+echo $AUTONOMOUS_DEBUG
+
+# Watch logs in real-time
+tail -f bot.log | grep "V2 Debug"
+
+# Count decision checks in last hour
+grep "Decision Check" bot.log | wc -l
+
+# See all actions taken
+grep "DECISION:" bot.log
+```
+
+---
+
+## ✅ Troubleshooting Checklist
+
+- [ ] Is `AUTONOMOUS_DEBUG=true` set?
+- [ ] Did you restart the bot after setting the env var?
+- [ ] Are presence intents enabled in `globals.py`?
+- [ ] Is the bot actually receiving messages?
+- [ ] Is the mood set to something other than "asleep"?
+- [ ] Is the decay task running (check logs every 15 min)?
+- [ ] Are there actually users in the server to track?
+
+---
+
+**Happy debugging! With debug mode enabled, you'll have full visibility into every decision the autonomous system makes.** 🔍✨