From 7059b44f6975f456c85c98a32f945f540b8b5932 Mon Sep 17 00:00:00 2001
From: Dani B <daniel.sapelli@gmail.com>
Date: Thu, 29 Jan 2026 10:42:14 -0500
Subject: [PATCH] docs: initialize project

Discord bot that translates Vivi's emoji communication into text so her community understands her instantly.
---
 .planning/PROJECT.md | 78 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 .planning/PROJECT.md

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..437e7ce
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,78 @@
+# Vivi Speech Translator
+
+## What This Is
+
+A Discord bot that translates Vivi's emoji-based communication into text so her community understands what she's saying without prior knowledge. Works with PluralKit/Tupperbox to detect Vivi's messages, learns emoji meanings over time, and can be adopted by other plural systems with mute members who use emojis to communicate.
+
+## Core Value
+
+Vivi posts emojis and others instantly understand her without needing to know what each emoji means.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Bot detects Vivi's messages via PluralKit/Tupperbox integration
+- [ ] Bot translates emoji sequences into natural language
+- [ ] Bot learns new emoji meanings when taught (by Vivi or other alters)
+- [ ] Bot can update/correct existing emoji meanings
+- [ ] Translation mode can toggle between automatic and on-demand
+- [ ] Unknown emojis are shown with meanings for known emojis only
+- [ ] Bot works in Discord channels and DMs
+- [ ] Emoji meanings are global across all servers
+- [ ] Bot works in any Discord server without per-server installation friction
+- [ ] Translation format adapts based on emoji sequences (natural language where possible)
+
+### Out of Scope
+
+- Real-time learning from context (emoji meanings learned explicitly, not inferred)
+- Voice/speech synthesis (text translation only)
+- Mobile app (Discord bot only)
+- Moderation or safety features beyond Discord's built-in tools
+- Support for non-emoji communication methods (focus on emoji first)
+
+## Context
+
+**About Vivi:**
+- Vivi is mute and communicates through custom emoji sequences
+- Vivi has Dysgraphia (writing difficulty), making emoji communication more accessible than text
+- Vivi can read normally, so she understands text translations
+- Vivi is one alter in a plural system; other alters can speak and help manage emoji meanings
+
+**Emoji Language:**
+- Emojis are compositional and read left-to-right, but meanings vary based on sequence
+- Includes both standard emojis (😷, ❌) and custom server emojis (`:me1:`)
+- Example: `:me1:😷 2️⃣ 🍑 ❌ 🤧` = "Vivi is sick, but not in the sinuses"
+
+**Integration:**
+- Must integrate with PluralKit or Tupperbox to detect when Vivi is the active communicator
+- These bots proxy messages through a shared account, but Vivi should be recognizable
+
+**Broader Vision:**
+- Initially built for Vivi's community
+- Designed to be generalizable so other plural systems with mute members can adopt it
+- Global emoji dictionary allows different systems to maintain their own emoji meanings
+
+## Constraints
+
+- **Platform**: Discord bot only (no web, mobile, or other platforms)
+- **Integration**: Must work seamlessly with PluralKit or Tupperbox
+- **Accessibility**: Must be low-friction for Vivi and other alters to teach/update emoji meanings
+- **Multi-server**: Should work in any Discord server without requiring complex per-server setup
+- **Global scope**: Emoji meanings are global, not per-server (but per-server overrides could be added later)
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Global emoji dictionary | Vivi's emoji language is consistent across communities; other systems will benefit from shared knowledge | — Pending |
+| Learning-based system | Vivi uses many emojis; manual mapping would be unsustainable. Bot learns when taught. | — Pending |
+| Auto + on-demand modes | Auto is natural but can be noisy; on-demand is explicit but requires action. Both options respect server preferences. | — Pending |
+| PluralKit/Tupperbox integration | These are standard plural system tools; integrating with them lets us detect Vivi's messages accurately | — Pending |
+
+---
+*Last updated: 2026-01-29 after initialization*