reorganize: consolidate all documentation into readmes/

- Moved 20 root-level markdown files to readmes/ - Includes COMMANDS.md, CONFIG_README.md, all UNO docs, all completion reports - Added new: MEMORY_EDITOR_FEATURE.md, MEMORY_EDITOR_ESCAPING_FIX.md, CONFIG_SOURCES_ANALYSIS.md, MCP_TOOL_CALLING_ANALYSIS.md, and others - Root directory is now clean of documentation clutter
2026-03-04 00:19:49 +02:00
parent fdde12c03d
commit c708770266
22 changed files with 4573 additions and 0 deletions
--- a/readmes/COMMANDS.md
+++ b/readmes/COMMANDS.md
@@ -0,0 +1,660 @@
+# Miku Discord Bot — Commands & Features Reference
+
+> **Last updated:** February 18, 2026
+>
+> Comprehensive documentation of every Discord command, API endpoint, and feature in the Miku bot.
+
+---
+
+## Table of Contents
+
+- [Discord Commands](#discord-commands)
+  - [Voice Commands (`!miku`)](#voice-commands-miku)
+  - [UNO Commands (`!uno`)](#uno-commands-uno)
+  - [Inline / Special Commands](#inline--special-commands)
+- [Conversational Features](#conversational-features)
+  - [Addressing Miku](#addressing-miku)
+  - [Direct Messages (DMs)](#direct-messages-dms)
+  - [Media Analysis](#media-analysis)
+  - [Image Generation](#image-generation)
+  - [Kindness Reactions](#kindness-reactions)
+- [Mood System](#mood-system)
+  - [Available Moods](#available-moods)
+  - [Evil Mode Moods](#evil-mode-moods)
+  - [Mood Auto-Detection](#mood-auto-detection)
+- [Personality Modes](#personality-modes)
+  - [Evil Mode](#evil-mode)
+  - [Bipolar Mode](#bipolar-mode)
+  - [Persona Dialogue](#persona-dialogue)
+- [Voice Chat System](#voice-chat-system)
+  - [Architecture](#voice-architecture)
+  - [STT (Speech-to-Text)](#stt-speech-to-text)
+  - [TTS (Text-to-Speech)](#tts-text-to-speech)
+  - [Resource Locking](#resource-locking)
+- [Autonomous Behavior System](#autonomous-behavior-system)
+- [Memory System (Cheshire Cat)](#memory-system-cheshire-cat)
+- [Profile Picture System](#profile-picture-system)
+- [Language Modes](#language-modes)
+- [Figurine Notifier](#figurine-notifier)
+- [Web UI API Endpoints](#web-ui-api-endpoints)
+  - [General Status](#general-status)
+  - [Mood Management (DM)](#mood-management-dm)
+  - [Mood Management (Per-Server)](#mood-management-per-server)
+  - [Language](#language)
+  - [Evil Mode API](#evil-mode-api)
+  - [Bipolar Mode API](#bipolar-mode-api)
+  - [GPU Selection](#gpu-selection)
+  - [Autonomous Actions](#autonomous-actions)
+  - [Profile Picture & Role Color](#profile-picture--role-color)
+  - [Manual Messaging](#manual-messaging)
+  - [Server Management](#server-management)
+  - [DM Logging & Management](#dm-logging--management)
+  - [DM Interaction Analysis](#dm-interaction-analysis)
+  - [Image Generation API](#image-generation-api)
+  - [Figurine DM Subscriptions](#figurine-dm-subscriptions)
+  - [Chat Interface](#chat-interface)
+  - [Voice Call Management](#voice-call-management)
+  - [Memory (Cheshire Cat) API](#memory-cheshire-cat-api)
+  - [Configuration Management](#configuration-management)
+  - [Logging Configuration](#logging-configuration)
+  - [Message Reactions](#message-reactions)
+  - [Autonomous V2 Endpoints](#autonomous-v2-endpoints)
+  - [Conversation Management](#conversation-management)
+
+---
+
+## Discord Commands
+
+### Voice Commands (`!miku`)
+
+All voice commands are prefixed with `!miku` and must be used in a **server** (not DMs).
+
+| Command | Arguments | Description | File |
+|---------|-----------|-------------|------|
+| `!miku join` | `[#channel]` | Join the user's voice channel (or the mentioned channel). Locks GPU resources for voice. | `bot/commands/voice.py` ~L57 |
+| `!miku leave` | — | Leave the current voice channel and release all resources. | `bot/commands/voice.py` ~L131 |
+| `!miku voice-status` | — | Show current voice session status, resource allocation, and active features. | `bot/commands/voice.py` ~L168 |
+| `!miku test` | `[text]` | Test TTS audio playback with custom or default text. | `bot/commands/voice.py` ~L252 |
+| `!miku say` | `<message>` | Send a message to the LLM, speak the response in voice chat. | `bot/commands/voice.py` ~L284 |
+| `!miku listen` | `[@user]` | Start listening to a user's voice via STT (defaults to command author). | `bot/commands/voice.py` ~L381 |
+| `!miku stop-listening` | `[@user]` | Stop listening to a user's voice (defaults to command author). | `bot/commands/voice.py` ~L431 |
+
+**Permissions required:** Bot needs `Connect` and `Speak` permissions in the target voice channel.
+
+---
+
+### UNO Commands (`!uno`)
+
+Miku can play UNO card games as Player 2, controlled via a Playwright browser automation.
+
+| Command | Arguments | Description | File |
+|---------|-----------|-------------|------|
+| `!uno join` | `<room_code>` | Join an existing UNO game room as Player 2. | `bot/commands/uno.py` ~L25 |
+| `!uno list` | — | List all active UNO games Miku is playing. | `bot/commands/uno.py` ~L82 |
+| `!uno quit` | `[room_code]` | Quit a specific game (or all games if no code provided). | `bot/commands/uno.py` ~L106 |
+| `!uno help` | — | Show UNO command help and how to play. | `bot/commands/uno.py` ~L158 |
+
+**No special permissions required.** Miku uses AI to make strategic moves and trash-talks during games.
+
+---
+
+### Inline / Special Commands
+
+These are handled directly in the `on_message` handler in `bot/bot.py`:
+
+| Command / Trigger | Description | File |
+|-------------------|-------------|------|
+| `!monday` | Manually trigger the Monday video feature. Server messages only. | `bot/bot.py` ~L708 |
+| `miku, rape this nigga balls` | *Must be a reply to another message.* Overlays the replied-to user's name on the `MikuMikuBeam.mp4` video and sends it as a reply. Easter egg command. | `bot/bot.py` ~L196 |
+
+---
+
+## Conversational Features
+
+### Addressing Miku
+
+Miku responds when she detects she is being addressed. The detection logic is in `bot/utils/core.py` (`is_miku_addressed`).
+
+**Miku will respond when:**
+- **In DMs:** Always responds to every message.
+- **@Mentioned** in a server channel.
+- **Replying** to one of Miku's messages.
+- **Her name is mentioned** — supports multiple scripts:
+  - Latin: `miku`
+  - Cyrillic: `мику`
+  - Hiragana: `みく`
+  - Katakana: `ミク`
+  - Kanji: `未来`
+  - Plus any combination with Japanese honorifics (`-chan`, `-san`, `-kun`, `-nyan`, `-senpai`, etc.) in all scripts.
+
+### Direct Messages (DMs)
+
+- Any user can DM Miku directly and get a response.
+- DMs use the global `DM_MOOD` (auto-rotating) instead of per-server moods.
+- All DM conversations are logged for the admin Web UI.
+- Users can be **blocked** from DMs via the API.
+- The bot logs reactions added/removed in DM conversations.
+
+### Media Analysis
+
+When a user sends media while addressing Miku, she analyzes it with the vision model:
+
+| Media Type | Supported Formats | Description |
+|------------|-------------------|-------------|
+| **Images** | `.jpg`, `.jpeg`, `.png`, `.webp` | Analyzed by Qwen vision model, then rephrased as Miku |
+| **Videos** | `.mp4`, `.webm`, `.mov` | Frames extracted, analyzed by vision model |
+| **GIFs** | `.gif` | Converted to MP4, frames extracted, analyzed |
+| **Tenor GIFs** | Discord `/gif` embeds | Extracted from Tenor URLs, processed as GIFs |
+| **Rich embeds** | Articles, images, videos, links | Text extracted and images/videos analyzed |
+
+All media analysis is blocked during active voice sessions.
+
+### Image Generation
+
+Miku can generate images using ComfyUI when users make natural language requests. Detection is pattern-based in `bot/utils/image_generation.py`.
+
+**Trigger phrases include:**
+- "draw me a picture of..."
+- "generate an image of..."
+- "show me yourself swimming"
+- "can you paint..."
+- "I want to see you..."
+- "what do you look like?"
+
+Image generation is blocked during voice sessions.
+
+### Kindness Reactions
+
+Defined in `bot/utils/kindness.py`. When users say kind things to Miku, she reacts with a heart emoji.
+
+**Keyword triggers:** "thank you", "love you", "luv u", "you're the best", "so cute", "adorable", "amazing", "sweet", "kind", "great job", "well done", "precious", "good girl", "cutie", "angel", "my favorite", "so helpful"
+
+**Heart reactions pool:** 💙 💝 💖 💕 💜 ❤️‍🔥 ☺️
+
+Falls back to LLM-based kindness detection if keywords don't match.
+
+---
+
+## Mood System
+
+### Available Moods
+
+Each mood changes Miku's personality, response style, and nickname emoji. Defined in `bot/moods/` (one `.txt` file per mood) and `bot/globals.py`.
+
+| Mood | Emoji | Description File |
+|------|-------|------------------|
+| `neutral` | *(none)* | `moods/neutral.txt` |
+| `bubbly` | ✨ | `moods/bubbly.txt` |
+| `sleepy` | 💤 | `moods/sleepy.txt` |
+| `curious` | 🔍 | `moods/curious.txt` |
+| `shy` | 🥺 | `moods/shy.txt` |
+| `serious` | 😐 | `moods/serious.txt` |
+| `excited` | 🎉 | `moods/excited.txt` |
+| `silly` | 🤪 | `moods/silly.txt` |
+| `melancholy` | 💙 | `moods/melancholy.txt` |
+| `flirty` | 💕 | `moods/flirty.txt` |
+| `romantic` | 💖 | `moods/romantic.txt` |
+| `irritated` | 😤 | `moods/irritated.txt` |
+| `angry` | 😠 | `moods/angry.txt` |
+| `asleep` | 😴 | `moods/asleep.txt` |
+
+**Mood behavior:**
+- **DM moods** rotate automatically on a schedule.
+- **Server moods** are per-server and can be set manually via the API or auto-detected from conversation tone.
+- Mood affects the system prompt, nickname emoji, and profile picture selection.
+- The `asleep` mood can only be reached from `sleepy` (prevents accidental sleep).
+
+### Evil Mode Moods
+
+When Evil Mode is active, a separate mood set is used:
+
+| Evil Mood | Emoji |
+|-----------|-------|
+| `aggressive` | 👿 |
+| `cunning` | 🐍 |
+| `sarcastic` | 😈 |
+| `evil_neutral` | *(none)* |
+
+### Mood Auto-Detection
+
+After Miku responds in a server, the system analyzes her response to detect if a mood shift occurred naturally. Handled by `detect_mood_shift()` in `bot/utils/moods.py`. If detected, the server mood updates automatically and the bot nickname updates.
+
+---
+
+## Personality Modes
+
+### Evil Mode
+
+**File:** `bot/utils/evil_mode.py`
+
+Evil Mode transforms Miku into "Evil Miku" — an uncensored, darker alter ego. When enabled:
+- Uses the `EVIL_TEXT_MODEL` (DarkIdol uncensored model) instead of the standard text model.
+- Loads evil-specific prompts from `bot/evil_miku_prompt.txt`, `bot/evil_miku_lore.txt`, `bot/evil_miku_lyrics.txt`.
+- Changes the bot's username and profile picture across all servers.
+- Changes role color to a dark theme.
+- Uses the evil mood set (`aggressive`, `cunning`, `sarcastic`, `evil_neutral`).
+- State persists across restarts via `memory/evil_mode_state.json`.
+
+### Bipolar Mode
+
+**File:** `bot/utils/bipolar_mode.py`
+
+When enabled, **both** Regular Miku and Evil Miku coexist. After Miku responds to a message, there's a chance (15%) the opposite persona "breaks through" and starts an argument. Arguments happen via Discord webhooks so both personas appear as different users.
+
+**Features:**
+- Minimum 4 exchanges before an argument can end.
+- 2-5 second delay between messages for realism.
+- Scoreboard tracks wins (`memory/bipolar_scoreboard.json`).
+- Webhooks are created per-channel and cached.
+- Paused during voice sessions.
+- Arguments can be manually triggered via the API.
+
+### Persona Dialogue
+
+**File:** `bot/utils/persona_dialogue.py`
+
+After Miku sends a response in bipolar mode, the system checks if the opposite persona wants to "interject" and start a dialogue. This creates multi-turn conversations between the two Miku personas.
+
+---
+
+## Voice Chat System
+
+### Voice Architecture
+
+The voice system uses a dual-GPU setup:
+- **AMD RX 6800 XT:** Text model inference + RVC (voice conversion)
+- **GTX 1660:** Soprano TTS (text-to-speech)
+
+### STT (Speech-to-Text)
+
+**File:** `bot/utils/stt_client.py`, `bot/utils/voice_receiver.py`
+
+- Uses a separate STT server container.
+- Listens to user audio via Discord voice receive.
+- Transcribes speech and sends it to the LLM for a response.
+- Can be enabled per-user with `!miku listen`.
+
+### TTS (Text-to-Speech)
+
+**File:** `bot/utils/voice_audio.py`
+
+- Streams LLM output tokens directly to Soprano TTS.
+- Audio is played back through the Discord voice connection.
+- RVC converts the voice to sound like Miku.
+
+### Resource Locking
+
+When a voice session is active, the following features are **blocked**:
+- ❌ Vision model (images/videos can't be analyzed)
+- ❌ Image generation (ComfyUI)
+- ❌ Bipolar mode arguments
+- ❌ Profile picture changes
+- ⏸️ Autonomous engine (paused)
+- ⏸️ Scheduled events (paused)
+- 📦 Other text channel messages (queued for later)
+
+Resources are fully released when the session ends with `!miku leave`.
+
+---
+
+## Autonomous Behavior System
+
+**Files:** `bot/utils/autonomous.py`, `bot/utils/autonomous_engine.py`, `bot/utils/autonomous_v1_legacy.py`
+
+Miku has an AI-driven autonomous system (V2) that decides when and how to interact without being prompted. The system uses context signals and mood profiles to make decisions.
+
+**Autonomous actions:**
+| Action | Description |
+|--------|-------------|
+| `general` | Say something spontaneous in the autonomous channel |
+| `engage_user` | Engage a random active user (based on activity, status, etc.) |
+| `share_tweet` | Share a Miku-related tweet |
+| `join_conversation` | Detect and join an ongoing conversation |
+| `change_profile_picture` | Autonomously change the bot's profile picture |
+| `reaction` | React to a recent message with an emoji |
+
+**Context signals the engine considers:**
+- Messages in the last 5 minutes / last hour
+- Unique active users
+- Conversation momentum
+- Users who recently joined / changed status / started activities
+- Time since last action / last interaction
+- Hour of day and whether it's a weekend
+- Current mood energy level
+
+**Scheduling:** Each server has its own autonomous tick scheduler. Actions are rate-limited (minimum 30s between actions).
+
+---
+
+## Memory System (Cheshire Cat)
+
+**Files:** `bot/utils/cat_client.py`, `cheshire-cat/` directory
+
+Miku uses the Cheshire Cat AI framework for long-term memory:
+- **Declarative memory:** Learned facts about users and the world.
+- **Episodic memory:** Conversation snippets and experiences.
+- Memories are stored in vector databases (Qdrant).
+- When enabled, all responses are augmented with relevant memories.
+- Falls back to direct LLM queries if Cat is unavailable.
+- Memory consolidation can be triggered manually (like a "sleep" process).
+- Individual memories can be created, edited, and deleted via the API.
+
+Toggle state: `USE_CHESHIRE_CAT` global (default: `true`).
+
+---
+
+## Profile Picture System
+
+**File:** `bot/utils/profile_picture_manager.py`, `bot/utils/danbooru_client.py`, `bot/utils/pfp_context.py`
+
+- Miku's profile picture can change based on mood.
+- Sources images from Danbooru (anime art database).
+- Extracts dominant colors for role color matching.
+- Face detection ensures the selected image has a face.
+- Saves a fallback image for restoration.
+- Can be triggered autonomously or manually via the API.
+- Custom images can be uploaded.
+
+---
+
+## Language Modes
+
+Miku supports switching between English and Japanese:
+- **English mode** (default): Uses the standard `TEXT_MODEL`.
+- **Japanese mode**: Uses `JAPANESE_TEXT_MODEL` (Llama 3.1 Swallow) for Japanese responses.
+- Persisted across restarts via `config_runtime.yaml`.
+
+---
+
+## Figurine Notifier
+
+**File:** `bot/utils/figurine_notifier.py`
+
+DM-based subscription system for Miku figurine notifications:
+- Users can subscribe/unsubscribe to figurine alerts.
+- When new Miku figurines are posted (via tweet URLs), subscribers get DMs.
+- Individual or bulk DM sending supported.
+
+---
+
+## Web UI API Endpoints
+
+The bot runs a FastAPI server on port `3939` for the Web UI dashboard. All endpoints are defined in `bot/api.py`.
+
+### General Status
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/` | Serve the Web UI dashboard |
+| `GET` | `/status` | Bot status, DM mood, server count, per-server moods |
+| `GET` | `/logs` | Last 100 lines of `bot.log` |
+| `GET` | `/prompt` | Last full prompt sent to the LLM |
+
+### Mood Management (DM)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/mood` | Get current DM mood and description |
+| `POST` | `/mood` | Set DM mood (`{ "mood": "bubbly" }`) |
+| `POST` | `/mood/reset` | Reset DM mood to `neutral` |
+| `POST` | `/mood/calm` | Calm DM mood to `neutral` |
+| `GET` | `/moods/available` | List all available mood names |
+
+### Mood Management (Per-Server)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/servers/{guild_id}/mood` | Get current mood for a server |
+| `POST` | `/servers/{guild_id}/mood` | Set mood for a server |
+| `POST` | `/servers/{guild_id}/mood/reset` | Reset server mood to `neutral` |
+| `GET` | `/servers/{guild_id}/mood/state` | Get complete mood state for a server |
+| `POST` | `/test/mood/{guild_id}` | Debug endpoint to test mood changes |
+
+### Language
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/language` | Get current language mode and model |
+| `POST` | `/language/toggle` | Toggle between English and Japanese |
+| `POST` | `/language/set` | Set language (`?language=english` or `japanese`) |
+
+### Evil Mode API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/evil-mode` | Get evil mode status and current mood |
+| `POST` | `/evil-mode/enable` | Enable evil mode |
+| `POST` | `/evil-mode/disable` | Disable evil mode |
+| `POST` | `/evil-mode/toggle` | Toggle evil mode |
+| `GET` | `/evil-mode/mood` | Get current evil mood |
+| `POST` | `/evil-mode/mood` | Set evil mood (`{ "mood": "aggressive" }`) |
+
+### Bipolar Mode API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/bipolar-mode` | Status, active arguments, webhooks count |
+| `POST` | `/bipolar-mode/enable` | Enable bipolar mode |
+| `POST` | `/bipolar-mode/disable` | Disable bipolar mode |
+| `POST` | `/bipolar-mode/toggle` | Toggle bipolar mode |
+| `POST` | `/bipolar-mode/trigger-argument` | Manually trigger an argument in a channel |
+| `POST` | `/bipolar-mode/trigger-dialogue` | Force persona dialogue from a message |
+| `GET` | `/bipolar-mode/scoreboard` | Miku vs Evil Miku win/loss record |
+| `GET` | `/bipolar-mode/arguments` | Get all currently active arguments |
+| `POST` | `/bipolar-mode/cleanup-webhooks` | Clean up all bipolar webhooks |
+
+### GPU Selection
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/gpu-status` | Current GPU selection (`nvidia` or `amd`) |
+| `POST` | `/gpu-select` | Switch GPU (`{ "gpu": "nvidia" }` or `"amd"`) |
+
+### Autonomous Actions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/autonomous/general` | Trigger a general autonomous message (all servers or `?guild_id=`) |
+| `POST` | `/autonomous/engage` | Trigger user engagement (`?guild_id=`, `?user_id=`, `?engagement_type=`) |
+| `POST` | `/autonomous/tweet` | Share a Miku tweet |
+| `POST` | `/autonomous/custom` | Send custom prompt as autonomous message (`{ "prompt": "..." }`) |
+| `POST` | `/autonomous/reaction` | Trigger an emoji reaction to a recent message |
+| `POST` | `/autonomous/join-conversation` | Detect and join an active conversation |
+| `GET` | `/autonomous/stats` | V1 autonomous engine stats for all servers |
+| `POST` | `/servers/{guild_id}/autonomous/general` | Trigger general message for one server |
+| `POST` | `/servers/{guild_id}/autonomous/engage` | Trigger engagement for one server |
+| `POST` | `/servers/{guild_id}/autonomous/custom` | Send custom prompt to one server |
+| `POST` | `/servers/{guild_id}/autonomous/tweet` | Share tweet in one server |
+
+### Profile Picture & Role Color
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/profile-picture/change` | Change PFP (optional `file` upload, optional `?guild_id=`) |
+| `GET` | `/profile-picture/metadata` | Get current PFP metadata (source, tags, etc.) |
+| `POST` | `/profile-picture/restore-fallback` | Restore the original saved PFP |
+| `POST` | `/role-color/custom` | Set custom role color (form field `hex_color`) |
+| `POST` | `/role-color/reset-fallback` | Reset role color to Miku teal (#86cecb) |
+
+### Manual Messaging
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/manual/send` | Send a message to a channel (supports files, replies) |
+| `POST` | `/manual/send-webhook` | Send as Miku or Evil Miku via webhook (`persona=miku|evil`) |
+| `POST` | `/dm/{user_id}/custom` | Send a custom LLM-generated DM to a user |
+| `POST` | `/dm/{user_id}/manual` | Send a manual DM message (supports files, replies) |
+
+### Server Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/servers` | List all configured servers |
+| `POST` | `/servers` | Add a new server configuration |
+| `PUT` | `/servers/{guild_id}` | Update server configuration |
+| `DELETE` | `/servers/{guild_id}` | Remove a server |
+| `POST` | `/servers/{guild_id}/bedtime-range` | Update bedtime reminder schedule |
+| `GET` | `/servers/{guild_id}/memory` | Get server-specific memory |
+| `POST` | `/servers/{guild_id}/memory` | Set server-specific memory |
+| `POST` | `/servers/repair` | Repair corrupted server configuration |
+
+### DM Logging & Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/dms/users` | List all users who have DMed the bot |
+| `GET` | `/dms/users/{user_id}` | Get conversation summary for a user |
+| `GET` | `/dms/users/{user_id}/conversations` | Get recent conversations (`?limit=50`) |
+| `GET` | `/dms/users/{user_id}/search` | Search conversations (`?query=...`) |
+| `GET` | `/dms/users/{user_id}/export` | Export conversations (`?format=json`) |
+| `DELETE` | `/dms/users/{user_id}` | Delete all DM logs for a user |
+| `GET` | `/dms/blocked-users` | List all blocked users |
+| `POST` | `/dms/users/{user_id}/block` | Block a user from DMs |
+| `POST` | `/dms/users/{user_id}/unblock` | Unblock a user |
+| `POST` | `/dms/users/{user_id}/conversations/{id}/delete` | Delete a specific message from Discord + logs |
+| `POST` | `/dms/users/{user_id}/conversations/delete-all` | Delete all conversations (Discord + logs) |
+| `POST` | `/dms/users/{user_id}/delete-completely` | Completely remove all user data |
+
+### DM Interaction Analysis
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/dms/analysis/run` | Manually trigger daily DM analysis |
+| `POST` | `/dms/users/{user_id}/analyze` | Analyze a specific user's interactions |
+| `GET` | `/dms/analysis/reports` | Get recent analysis reports (`?limit=20`) |
+| `GET` | `/dms/analysis/reports/{user_id}` | Get reports for a specific user |
+
+### Image Generation API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/image/generate` | Manually trigger image generation (`{ "prompt": "..." }`) |
+| `GET` | `/image/status` | Check ComfyUI availability |
+| `POST` | `/image/test-detection` | Test natural language image request detection |
+| `GET` | `/image/view/{filename}` | Serve a generated image file |
+
+### Figurine DM Subscriptions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/figurines/subscribers` | List all figurine notification subscribers |
+| `POST` | `/figurines/subscribers` | Add a subscriber (form field `user_id`) |
+| `DELETE` | `/figurines/subscribers/{user_id}` | Remove a subscriber |
+| `POST` | `/figurines/send_now` | Send figurine DMs to all subscribers |
+| `POST` | `/figurines/send_to_user` | Send figurine DM to a specific user |
+
+### Chat Interface
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/chat/stream` | Stream a chat response via SSE (supports text and vision models, conversation history, mood selection) |
+
+### Voice Call Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/voice/call` | Initiate a voice call to a user (starts containers, joins channel, sends DM invite) |
+| `GET` | `/voice/debug-mode` | Get voice debug mode status |
+| `POST` | `/voice/debug-mode` | Set voice debug mode on/off |
+
+### Memory (Cheshire Cat) API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/memory/status` | Cat connection status, circuit breaker state |
+| `POST` | `/memory/toggle` | Enable/disable Cheshire Cat integration |
+| `GET` | `/memory/stats` | Memory collection statistics (point counts) |
+| `GET` | `/memory/facts` | Get all declarative memory facts |
+| `GET` | `/memory/episodic` | Get all episodic memories |
+| `POST` | `/memory/consolidate` | Trigger memory consolidation |
+| `POST` | `/memory/delete` | **Delete ALL memories** (requires exact confirmation string) |
+| `DELETE` | `/memory/point/{collection}/{point_id}` | Delete a single memory point |
+| `PUT` | `/memory/point/{collection}/{point_id}` | Edit a memory point's content/metadata |
+| `POST` | `/memory/create` | Create a new memory (declarative or episodic) |
+
+### Configuration Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/config` | Full config (static + runtime + state) |
+| `GET` | `/config/static` | Static config from `config.yaml` |
+| `GET` | `/config/runtime` | Runtime config (overrides) |
+| `POST` | `/config/set` | Set a runtime config value |
+| `POST` | `/config/reset` | Reset config to defaults |
+| `POST` | `/config/validate` | Validate current configuration |
+| `GET` | `/config/state` | Get current config state |
+
+### Logging Configuration
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/log/config` | Get current logging configuration |
+| `POST` | `/api/log/config` | Update logging config for a component |
+| `GET` | `/api/log/components` | List all logging components and stats |
+| `POST` | `/api/log/reload` | Reload all loggers from config |
+| `POST` | `/api/log/filters` | Update API request log filters |
+| `POST` | `/api/log/reset` | Reset logging config to defaults |
+| `POST` | `/api/log/global-level` | Set global log level |
+| `POST` | `/api/log/timestamp-format` | Set timestamp format |
+| `GET` | `/api/log/files/{component}` | Get last N lines from a component's log file |
+
+### Message Reactions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/messages/react` | Add a reaction emoji to a specific message |
+
+### Autonomous V2 Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/autonomous/v2/stats/{guild_id}` | V2 social stats for a server |
+| `GET` | `/autonomous/v2/check/{guild_id}` | Manual V2 context check (debug) |
+| `GET` | `/autonomous/v2/status` | V2 system status for all servers |
+
+### Conversation Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/conversation/{user_id}` | Get conversation history for a user |
+| `POST` | `/conversation/reset` | Reset conversation history (`{ "user_id": "..." }`) |
+| `POST` | `/sleep` | Force Miku to sleep (legacy) |
+| `POST` | `/wake` | Wake Miku up (legacy) |
+| `POST` | `/bedtime` | Send bedtime reminder (`?guild_id=` or all servers) |
+
+---
+
+## Discord Event Handlers
+
+These are non-command behaviors handled by Discord events in `bot/bot.py`:
+
+| Event | Handler | Description |
+|-------|---------|-------------|
+| `on_ready` | `bot.py` ~L89 | Initialize all systems, restore modes, start schedulers |
+| `on_message` | `bot.py` ~L160 | Main message handler — routes commands, handles conversations |
+| `on_raw_reaction_add` | `bot.py` ~L716 | Log DM reactions (user and bot) |
+| `on_raw_reaction_remove` | `bot.py` ~L756 | Log DM reaction removals |
+| `on_presence_update` | `bot.py` ~L793 | Track user presence for autonomous V2 |
+| `on_member_join` | `bot.py` ~L799 | Track member joins for autonomous V2 |
+| `on_voice_state_update` | `bot.py` ~L803 | Track voice channel joins/leaves, auto-listen for voice calls |
+
+---
+
+## Environment Variables
+
+Key configuration from `bot/globals.py` and `bot/config.py`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DISCORD_BOT_TOKEN` | — | Discord bot token |
+| `LLAMA_URL` | `http://llama-swap:8080` | NVIDIA GPU llama-swap URL |
+| `LLAMA_AMD_URL` | `http://llama-swap-amd:8080` | AMD GPU llama-swap URL |
+| `TEXT_MODEL` | `llama3.1` | Default text model name |
+| `VISION_MODEL` | `vision` | Vision model name (Qwen) |
+| `EVIL_TEXT_MODEL` | `darkidol` | Uncensored model for evil mode |
+| `JAPANESE_TEXT_MODEL` | `swallow` | Japanese text model |
+| `OWNER_USER_ID` | `209381657369772032` | Bot owner's Discord ID (for reports) |
+| `CHESHIRE_CAT_URL` | `http://cheshire-cat:80` | Cheshire Cat memory server URL |
+| `USE_CHESHIRE_CAT` | `true` | Enable/disable memory system |
+| `AUTONOMOUS_DEBUG` | `false` | Verbose autonomous decision logging |
+| `VOICE_DEBUG_MODE` | `false` | Show voice transcriptions in text channel |