docs: define v1 requirements

33 requirements across 9 categories:
- Message detection & translation (6)
- Teaching system (7)
- Unknown emoji handling (3)
- Error handling (3)
- Configuration (2)
- Database (4)
- Accessibility (5)
- Generalization (3)

All v1 requirements mapped to phases 1-5.

.planning/REQUIREMENTS.md

@@ -0,0 +1,174 @@
+# Requirements: Vivi Speech Translator
+
+**Defined:** 2025-01-29
+**Core Value:** Vivi posts emojis and others instantly understand her without needing to know what each emoji means.
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Message Detection
+
+- [ ] **DETECT-01**: Bot detects when Vivi is communicating via PluralKit webhook proxying
+- [ ] **DETECT-02**: Bot ignores non-Vivi messages (no false positives on other members/bots)
+- [ ] **DETECT-03**: Bot works in Discord channels and direct messages (DMs)
+- [ ] **DETECT-04**: Bot detects Vivi's messages reliably even after edits or reactions
+
+### Emoji Parsing & Translation
+
+- [ ] **TRANS-01**: Bot parses standard emojis (😷, ❌, 2️⃣) from Vivi's messages
+- [ ] **TRANS-02**: Bot parses custom Discord server emojis (`:me1:`, `:custom_name:`) from Vivi's messages
+- [ ] **TRANS-03**: Bot translates parsed emojis to text and replies automatically (auto mode)
+- [ ] **TRANS-04**: Bot composition reads emojis left-to-right and composes natural language translation
+- [ ] **TRANS-05**: Bot replies with plain text translation (never emoji-only responses)
+- [ ] **TRANS-06**: Bot's response is concise and clear (respects message length limits)
+
+### Teaching System
+
+- [ ] **TEACH-01**: `/teach emoji "meaning"` command allows users to teach new emoji meanings
+- [ ] **TEACH-02**: Bot confirms what it learned (shows emoji and meaning back to user)
+- [ ] **TEACH-03**: Bot stores emoji meanings globally across all Discord servers
+- [ ] **TEACH-04**: `/meaning emoji` command shows the current meaning of an emoji
+- [ ] **TEACH-05**: `/correct emoji "new meaning"` command updates incorrect emoji meanings
+- [ ] **TEACH-06**: Audit trail tracks who taught/corrected each emoji and when
+- [ ] **TEACH-07**: Any user can teach emojis (not restricted to Vivi or admins)
+
+### Unknown Emoji Handling
+
+- [ ] **UNK-01**: When bot encounters unknown emoji, it skips that emoji
+- [ ] **UNK-02**: Bot shows translation of known emojis and prompts user to teach unknown ones
+- [ ] **UNK-03**: Teaching prompt is accessible (simple command: `/teach emoji "meaning"`)
+
+### Error Handling
+
+- [ ] **ERROR-01**: When bot encounters an error, it reacts with ❌ instead of crashing
+- [ ] **ERROR-02**: Bot logs errors for debugging (no message to user)
+- [ ] **ERROR-03**: Bot retries failed database operations (exponential backoff)
+
+### Configuration
+
+- [ ] **CONFIG-01**: `/config auto-translate on|off` command toggles automatic translation per server
+- [ ] **CONFIG-02**: Default mode is auto (bot translates every Vivi message)
+- [ ] **CONFIG-03**: Setting is per-server (each Discord server has its own preference)
+- [ ] **CONFIG-04**: Only server admins can change configuration
+
+### Database & Persistence
+
+- [ ] **DB-01**: Global emoji dictionary persists across bot restarts
+- [ ] **DB-02**: Emoji meanings shared across all Discord servers (one dictionary)
+- [ ] **DB-03**: Per-server configuration persists (auto/on-demand toggle)
+- [ ] **DB-04**: Audit trail of teaching actions stored with user ID and timestamp
+
+### Accessibility
+
+- [ ] **A11Y-01**: All bot responses are plain text (no heavy formatting or embeds)
+- [ ] **A11Y-02**: `/teach emoji "meaning"` command is simple and short
+- [ ] **A11Y-03**: Bot responses are concise (under 3 sentences)
+- [ ] **A11Y-04**: Slash commands are used (better keyboard navigation than buttons)
+- [ ] **A11Y-05**: Emoji names included in responses for screen readers
+
+### Generalization & Multi-System
+
+- [ ] **GEN-01**: Architecture supports adding other plural systems in future (not Vivi-only hardcoded)
+- [ ] **GEN-02**: Emoji dictionary design allows per-system or per-guild overrides (for future v2)
+- [ ] **GEN-01**: Code is modular enough for other systems to fork and customize
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### On-Demand Translation
+
+- **DEMAND-01**: Users can react with 🔤 to request translation (on-demand mode)
+- **DEMAND-02**: `/translate message_id` command translates a specific Vivi message
+
+### Advanced Configuration
+
+- **CONFIG-05**: Per-server custom emoji overrides (e.g., server A uses 😊 for "happy", server B uses it for "embarrassed")
+- **CONFIG-06**: Per-server emoji moderation (block certain emojis from being taught)
+
+### Analytics & Admin
+
+- **STATS-01**: `/stats` shows frequently-translated emojis per server
+- **STATS-02**: `/emoji-list` shows all known emoji meanings with teaching source
+- **ADMIN-01**: Server admins can reset emoji meanings to defaults
+- **ADMIN-02**: Bot owner can view global statistics (all servers)
+
+### Translation Quality
+
+- **QUALITY-01**: Reaction-based feedback (👍/👎) on translations
+- **QUALITY-02**: Bot improves formatting based on feedback patterns
+
+### Multi-Language
+
+- **MULTI-01**: Emoji meanings in multiple languages (future expansion)
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Real-time chat simulation | Out of scope — this is translation only, not a messaging system |
+| Cross-Discord emoji translation | Potential conflicts; focus on Vivi's system meanings only |
+| Context-aware inference | Explicit teaching required — meanings don't infer from conversation context |
+| Voice/audio output | Translation to text only — no text-to-speech |
+| Mobile app | Discord bot only — no standalone app |
+| ML-based emoji sentiment | Rule-based only for v1; statistical fallback deferred to future |
+| Custom emoji creation | Bot translates existing emojis; doesn't create new ones |
+| Message history scanning | Only translates new messages; doesn't retroactively translate old ones |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DETECT-01 | Phase 1 | Pending |
+| DETECT-02 | Phase 1 | Pending |
+| DETECT-03 | Phase 1 | Pending |
+| DETECT-04 | Phase 2 | Pending |
+| TRANS-01 | Phase 2 | Pending |
+| TRANS-02 | Phase 2 | Pending |
+| TRANS-03 | Phase 2 | Pending |
+| TRANS-04 | Phase 2 | Pending |
+| TRANS-05 | Phase 2 | Pending |
+| TRANS-06 | Phase 2 | Pending |
+| TEACH-01 | Phase 3 | Pending |
+| TEACH-02 | Phase 3 | Pending |
+| TEACH-03 | Phase 3 | Pending |
+| TEACH-04 | Phase 3 | Pending |
+| TEACH-05 | Phase 3 | Pending |
+| TEACH-06 | Phase 3 | Pending |
+| TEACH-07 | Phase 3 | Pending |
+| UNK-01 | Phase 2 | Pending |
+| UNK-02 | Phase 3 | Pending |
+| UNK-03 | Phase 3 | Pending |
+| ERROR-01 | Phase 2 | Pending |
+| ERROR-02 | Phase 5 | Pending |
+| ERROR-03 | Phase 5 | Pending |
+| CONFIG-01 | Phase 4 | Pending |
+| CONFIG-02 | Phase 2 | Pending |
+| CONFIG-03 | Phase 4 | Pending |
+| CONFIG-04 | Phase 4 | Pending |
+| DB-01 | Phase 1 | Pending |
+| DB-02 | Phase 2 | Pending |
+| DB-03 | Phase 4 | Pending |
+| DB-04 | Phase 3 | Pending |
+| A11Y-01 | Phase 2 | Pending |
+| A11Y-02 | Phase 3 | Pending |
+| A11Y-03 | Phase 3 | Pending |
+| A11Y-04 | Phase 2 | Pending |
+| A11Y-05 | Phase 3 | Pending |
+| GEN-01 | Phase 1 | Pending |
+| GEN-02 | Phase 4 | Pending |
+| GEN-03 | Phase 3 | Pending |
+
+**Coverage:**
+- v1 requirements: 33 total
+- Mapped to phases: 33
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2025-01-29*
+*Last updated: 2025-01-29 after initial definition*